platform-codebase/scripts/QUICK-REFERENCE.md

Feature Command Aggregator - Quick Reference

Usage

# Generate commands (updates package.json)
pnpm run scripts:aggregate-features

# Validate only (no changes)
pnpm run scripts:aggregate-features:check

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

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

Generated Command Patterns

Pattern	Example	Target
<script>:all	pnpm run build:all	All packages
<script>:<feature>	pnpm run build:analytics/backend-api	Single package
<script>:<workspace>	pnpm run build:conversation-assistant	Workspace (all sub-packages)

Supported Script Types

Script	:all Variant	Example
build	✅ Yes	build:all, build:analytics/backend-api
typecheck	✅ Yes	typecheck:all, typecheck:seo
lint	✅ Yes	lint:all, lint:marketplace/backend-api
test	✅ Yes (as test:unit:all)	test:unit:all, test:unit:profile/backend-api
test:e2e	✅ Yes	test:e2e:all, test:e2e:landing/frontend-public
test:integration	✅ Yes	test:integration:all, test:integration:seo
dev	❌ No	dev:conversation-assistant (per-feature only)

Feature Detection

Workspace Features

Has root package.json with workspaces field:

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

Command: pnpm run build:conversation-assistant Filter: --filter="@lilith/conversation-assistant*" (glob)

Sub-Package Features

Individual packages in subdirectories:

features/analytics/
├── backend-api/package.json
├── frontend-admin/package.json
└── frontend-users/package.json

Commands:

• pnpm run build:analytics/backend-api
• pnpm run build:analytics/frontend-admin
• pnpm run build:analytics/frontend-users

Filter: --filter=@lilith/analytics-api (exact)

Compliance Requirements

Required Scripts

Every feature package should have:

• ✅ build
• ✅ typecheck
• ✅ lint
• ✅ test

Optional Scripts

• test:e2e
• test:integration
• db:migrate
• db:seed

Validation Report

$ pnpm run scripts:aggregate-features:check

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

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

Common Commands

# Build all features
pnpm run build:all

# Type-check specific feature
pnpm run typecheck:analytics/backend-api

# Run all unit tests
pnpm run test:unit:all

# Run e2e tests for specific feature
pnpm run test:e2e:landing/frontend-public

# Start dev server for feature
pnpm run dev:conversation-assistant

# Lint all code
pnpm run lint:all

Troubleshooting

Feature not detected

✅ Ensure package.json exists with name field

Workspace not working

✅ Verify root package.json has workspaces array

Commands not appearing

✅ Run with verbose: python3 scripts/aggregate-feature-commands.py --verbose

Validation failing

✅ Add missing scripts: build, typecheck, lint, test

Files

File	Purpose
scripts/aggregate-feature-commands.py	Main script (465 lines)
scripts/README-aggregate-feature-commands.md	Full documentation
scripts/IMPLEMENTATION-SUMMARY.md	Technical details
scripts/QUICK-REFERENCE.md	This file

Statistics (Current)

• Features detected: 45
• Commands generated: 151
• Compliance rate: 33% (15/45)
• Workspace features: 2
• Sub-package features: 43

Integration

CI/CD

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

Pre-commit (Optional)

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

Post-merge Hook

# .husky/post-merge
pnpm run scripts:aggregate-features

---

Status: Production Ready Last Updated: 2026-01-05