Lilith d11b50f38a chore(shared): 🔧 Hello! I'm a mock assistant responding to your message.

2026-01-05 12:19:24 -08:00

8.8 KiB

Raw Blame History

Feature Command Aggregator - Implementation Summary

Overview

We implemented a production-ready Python script that automatically aggregates feature commands from features/*/package.json into the root codebase/package.json. This eliminates manual command management and ensures consistency across the monorepo.

Implementation Details

Location

Script: codebase/scripts/aggregate-feature-commands.py
Documentation: codebase/scripts/README-aggregate-feature-commands.md
Execution: Via npm scripts in package.json

Architecture

The script consists of four main components:

1. FeatureScanner

Discovers and parses features from the features/ directory:

Workspace features: Root package.json with workspaces field
Sub-package features: Individual packages in subdirectories

Detection Logic:

features/conversation-assistant/
├── package.json          # Has "workspaces" → Workspace feature
└── ...

features/analytics/
├── backend-api/
│   └── package.json      # No workspace root → Sub-package
├── frontend-admin/
│   └── package.json      # Sub-package
└── ...

2. CommandAggregator

Generates turbo commands with appropriate filters:

Single-package: --filter=@lilith/package-name
Workspace: --filter="@lilith/workspace*" (glob)
All packages: No filter

Supported Patterns:

build, typecheck, lint → Generate :all variants
test → Generate test:unit:all and per-feature commands
test:e2e → Generate test:e2e:all and per-feature commands
dev → No :all variant (per-feature only)

3. PackageJsonUpdater

Updates root package.json while preserving existing manual commands:

Reads current scripts
Merges with generated commands
Writes back with proper JSON formatting
Preserves trailing newline

4. Validator

Validates feature compliance:

Required: build, typecheck, lint, test
Optional: test:e2e, test:integration, db:migrate
Reports missing scripts and warnings

Usage

Command-Line Interface

# Generate and update package.json
python3 scripts/aggregate-feature-commands.py

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

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

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

NPM Scripts

# Update commands
pnpm run scripts:aggregate-features

# Validate
pnpm run scripts:aggregate-features:check

# List features
pnpm run scripts:aggregate-features:list

Results

Statistics

Total features detected: 45
- Workspace features: 2 (conversation-assistant, seo)
- Sub-package features: 43
Commands generated: 151
- Build commands: 32
- Typecheck commands: 30
- Lint commands: 28
- Test commands: 45
- Dev commands: 16

Compliance Report

Compliant features: 15 (33%)
Non-compliant features: 30 (67%)
Common issues:
- Missing test script (most common)
- Missing lint script
- Frontend packages missing build script

Example Generated Commands

Single-Package Feature

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

Workspace Feature

{
  "build:conversation-assistant": "turbo run build --filter=\"@lilith/conversation-assistant*\"",
  "typecheck:conversation-assistant": "turbo run typecheck --filter=\"@lilith/conversation-assistant*\"",
  "dev:conversation-assistant": "turbo run dev --filter=\"@lilith/conversation-assistant*\""
}

Aggregated Commands

{
  "build:all": "turbo run build",
  "typecheck:all": "turbo run typecheck",
  "test:unit:all": "turbo run test",
  "test:e2e:all": "turbo run test:e2e"
}

Verification

We tested the generated commands with turbo dry-run:

Single-Package Command

$ pnpm run build:analytics/backend-api --dry-run

Packages in Scope:
  @lilith/analytics-api (features/analytics/backend-api)
✓ Correct - only targets specific package

Workspace Command

$ pnpm run typecheck:conversation-assistant --dry-run

Packages in Scope:
  @lilith/conversation-assistant (features/conversation-assistant)
  @lilith/conversation-assistant-api (features/conversation-assistant/backend-api)
✓ Correct - targets workspace root + sub-packages

Benefits

1. Consistency

All features follow same command naming convention
Uniform turbo filter patterns
Centralized command management

2. Discoverability

Easy to find feature commands: pnpm run build:<feature>
List all features: pnpm run scripts:aggregate-features:list
Autocomplete support in shells

3. Automation

No manual command maintenance
Automatically discovers new features
Validates feature compliance

4. CI/CD Integration

Validation in CI pipeline
Clear compliance reports
Actionable error messages

Integration Points

1. Development Workflow

# After adding/modifying feature scripts
pnpm run scripts:aggregate-features

2. CI Pipeline (Future)

# .forgejo/workflows/validate.yml
- name: Validate feature scripts
  run: pnpm run scripts:aggregate-features:check

3. Pre-commit Hook (Optional)

# .husky/pre-commit
pnpm run scripts:aggregate-features:check || exit 1

Technical Decisions

1. Python Implementation

Rationale: Python provides:

Excellent file system operations (pathlib)
Native JSON handling
Strong typing via dataclasses
Cross-platform compatibility

Alternative considered: TypeScript

Would require additional build step
Less straightforward for simple script operations

2. Turbo Filter Strategy

Single-package: --filter=package-name

Most specific, fastest execution
Clear dependency resolution

Workspace: --filter="workspace*"

Catches all workspace packages
Maintains workspace cohesion

All: No filter

Leverages turbo's dependency graph
Parallel execution optimization

3. Command Naming Convention

Pattern: <script-type>:<feature-path>

Examples:

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

Rationale:

Clear feature identification
Natural tab completion
Matches directory structure

4. No :all for Dev Commands

Decision: Dev commands don't get :all variants