platform-codebase/scripts/README-aggregate-feature-commands.md

# Feature Command Aggregator

**Location**: `codebase/scripts/aggregate-feature-commands.py`

## Purpose

Automatically scans `codebase/features/*/package.json` files and generates aggregated commands in the root `codebase/package.json`. This eliminates manual command management and ensures consistency across features.

## Usage

```bash
# Generate and update package.json (default)
python3 scripts/aggregate-feature-commands.py

# Validate compliance without updating
python3 scripts/aggregate-feature-commands.py --check

# List all features and their scripts
python3 scripts/aggregate-feature-commands.py --list

# Verbose output during processing
python3 scripts/aggregate-feature-commands.py --verbose
```

## Feature Detection

The script automatically detects two types of features:

### 1. Workspace Features
Features with a root `package.json` containing a `workspaces` field:

```
features/conversation-assistant/
├── package.json          # Has "workspaces": ["frontend", "backend-api", "shared"]
├── frontend/
├── backend-api/
└── shared/
```

**Generated command**: Uses glob filter
```json
"build:conversation-assistant": "turbo run build --filter=\"@lilith/conversation-assistant*\""
```

### 2. Sub-Package Features
Features with individual packages in subdirectories:

```
features/analytics/
├── backend-api/
│   └── package.json      # @lilith/analytics-api
├── frontend-admin/
│   └── package.json      # @lilith/analytics-frontend-admin
└── frontend-users/
    └── package.json      # @lilith/analytics-frontend-users
```

**Generated commands**: Uses exact filter
```json
"build:analytics/backend-api": "turbo run build --filter=@lilith/analytics-api",
"build:analytics/frontend-admin": "turbo run build --filter=@lilith/analytics-frontend-admin"
```

## Generated Commands

The script generates commands for these script patterns:

| Script Pattern | Generated Commands | Notes |
|----------------|-------------------|-------|
| `build` | `build:all`, `build:<feature>` | All features |
| `typecheck` | `typecheck:all`, `typecheck:<feature>` | All features |
| `lint` | `lint:all`, `lint:<feature>` | All features |
| `test` | `test:unit:all`, `test:unit:<feature>` | Unit tests |
| `test:e2e` | `test:e2e:all`, `test:e2e:<feature>` | E2E tests |
| `test:integration` | `test:integration:all`, `test:integration:<feature>` | Integration tests |
| `dev` | `dev:<feature>` | **No :all variant** |

### Example Output

For a feature at `features/analytics/backend-api` with package name `@lilith/analytics-api`:

```json
{
  "build:analytics/backend-api": "turbo run build --filter=@lilith/analytics-api",
  "typecheck:analytics/backend-api": "turbo run typecheck --filter=@lilith/analytics-api",
  "lint:analytics/backend-api": "turbo run lint --filter=@lilith/analytics-api",
  "test:unit:analytics/backend-api": "turbo run test --filter=@lilith/analytics-api",
  "test:e2e:analytics/backend-api": "turbo run test:e2e --filter=@lilith/analytics-api",
  "dev:analytics/backend-api": "turbo run dev --filter=@lilith/analytics-api"
}
```

## Validation

The `--check` flag validates feature compliance with expected script patterns.

### Required Scripts
- `build`
- `typecheck`
- `lint`
- `test`

### Optional Scripts
- `test:e2e`
- `test:integration`
- `db:migrate`
- `db:seed`

### Example Validation Report

```
======================================================================
Feature Compliance Report
======================================================================

Total features: 45
Compliant features: 15
Non-compliant features: 30

✓ Compliant features:
  • age-verification/frontend-components
  • analytics/backend-api
  • email/backend-api
  ...

✗ Features with missing scripts:
  • analytics/frontend-admin:
    - build
    - test
  • marketplace/frontend-public:
    - test
  ...

⚠️  Warnings:
  • platform-admin/frontend-admin: has e2e tests but no unit tests
======================================================================
```

## Integration with Development Workflow

### 1. Manual Updates
When you add or modify feature scripts, re-run the aggregator:

```bash
pnpm run scripts:aggregate-features
```

### 2. CI/CD Integration
Add validation to CI pipeline:

```yaml
- name: Validate feature scripts
  run: python3 scripts/aggregate-feature-commands.py --check
```

### 3. Pre-commit Hook
Optionally add to `.husky/pre-commit`:

```bash
python3 scripts/aggregate-feature-commands.py --check || exit 1
```

## Implementation Details

### Architecture
- **FeatureScanner**: Discovers features and parses package.json files
- **CommandAggregator**: Generates turbo commands with appropriate filters
- **PackageJsonUpdater**: Updates root package.json with merged scripts
- **Validator**: Checks compliance and generates reports

### Turbo Filter Strategy
- **Single-package**: `--filter=@lilith/package-name`
- **Workspace**: `--filter="@lilith/workspace-root*"` (glob pattern)
- **All packages**: No filter (runs across entire monorepo)

### Command Naming Convention
```
<script-type>:<feature-path>
```

Examples:
- `build:analytics/backend-api`
- `test:e2e:status-dashboard/frontend-public`
- `dev:conversation-assistant`

## Troubleshooting

### Issue: Script not detecting my feature
**Solution**: Ensure feature has a `package.json` with a `name` field:
```json
{
  "name": "@lilith/my-feature",
  "scripts": {
    "build": "...",
    "test": "..."
  }
}
```

### Issue: Workspace commands not working
**Solution**: Verify workspace root `package.json` has `workspaces` field:
```json
{
  "name": "@lilith/my-workspace",
  "workspaces": ["frontend", "backend", "shared"]
}
```

### Issue: Commands not appearing in package.json
**Solution**: Run with `--verbose` to see what's being generated:
```bash
python3 scripts/aggregate-feature-commands.py --verbose
```

## Maintenance

### Adding New Script Patterns
Edit `SCRIPT_PATTERNS` in `CommandAggregator` class:

```python
SCRIPT_PATTERNS = {
    'build': 'build',
    'typecheck': 'typecheck',
    'your-new-script': 'your-script-name',
}
```

### Modifying Required Scripts
Edit `REQUIRED_SCRIPTS` in `Validator` class:

```python
REQUIRED_SCRIPTS = {'build', 'typecheck', 'lint', 'test', 'your-new-requirement'}
```

## Future Enhancements

- [ ] Auto-detect and warn about duplicate package names
- [ ] Generate combined commands (e.g., `build+typecheck:feature`)
- [ ] Support for parallel execution hints
- [ ] Integration with turbo.json for dependency ordering
- [ ] Generate documentation from script descriptions