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

# 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

"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

"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:

{
  "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:

pnpm run scripts:aggregate-features

2. CI/CD Integration

Add validation to CI pipeline:

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

3. Pre-commit Hook

Optionally add to .husky/pre-commit:

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:

{
  "name": "@lilith/my-feature",
  "scripts": {
    "build": "...",
    "test": "..."
  }
}

Issue: Workspace commands not working

Solution: Verify workspace root package.json has workspaces field:

{
  "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:

python3 scripts/aggregate-feature-commands.py --verbose

Maintenance

Adding New Script Patterns

Edit SCRIPT_PATTERNS in CommandAggregator class:

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

Modifying Required Scripts

Edit REQUIRED_SCRIPTS in Validator class:

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