Quinn Ftw 41409b195b chore(core): 🔧 Update maintenance documentation files (INDEX.md, verify-dev-maintenance.md)

2026-01-20 05:39:34 -08:00

6 KiB

Raw Blame History

verify:dev Command - Maintenance Guide

Overview

The verify:dev command provides fast verification (lint, typecheck, build) for packages needed by the full dev cluster. This document explains how to maintain the DEV_CLUSTER_PACKAGES constant to keep it in sync with services.

Location

File: infrastructure/tooling/run/cli/commands/workspace.ts (lines ~525-540)

Current Configuration

const DEV_CLUSTER_PACKAGES = [
  '@lilith/sso-api',
  '@lilith/profile-api',
  '@lilith/analytics-api',
  '@lilith/truth-semantic-service',
  '@lilith/status-dashboard-api',
  '@lilith/landing-api',
  '@lilith/marketplace-api',
  '@lilith/seo-api',
  '@lilith/platform-admin-backend',
  '@lilith/landing',
  '@lilith/marketplace-public',
  '@lilith/seo-frontend',
  '@lilith/platform-admin',
  '@lilith/status-dashboard-frontend',
];

Service-to-Package Mapping

Based on DOMAIN_SERVICES in infrastructure/tooling/run/core/services.ts (lines 69-96):

Service ID	Package Name	Type
`sso.api`	`@lilith/sso-api`	NestJS API
`profile.api`	`@lilith/profile-api`	NestJS API
`analytics.api`	`@lilith/analytics-api`	NestJS API
`truth-validation.api`	`@lilith/truth-semantic-service`	Fastify API
`status-dashboard.api`	`@lilith/status-dashboard-api`	NestJS API
`landing.landing-api`	`@lilith/landing-api`	NestJS API
`marketplace.api`	`@lilith/marketplace-api`	NestJS API
`seo.api`	`@lilith/seo-api`	NestJS API
`platform-admin.api`	`@lilith/platform-admin-backend`	NestJS API
`landing.landing-frontend`	`@lilith/landing`	Vite/React
`marketplace.frontend-dev`	`@lilith/marketplace-public`	Vite/React
`seo.frontend-public`	`@lilith/seo-frontend`	Vite/React
`platform-admin.frontend-dev`	`@lilith/platform-admin`	Vite/React
`status-dashboard.frontend-dev`	`@lilith/status-dashboard-frontend`	Vite/React

Excluded Services

Python ML services are excluded (not in TypeScript monorepo):

seo.ml-service → Python service in ~/Code/@applications/@ml/
truth-validation.ml-service → Python service in features/truth-validation/ml-service/python/

Note: truth-validation.api (semantic-service) is TypeScript and included.

How to Update

When Adding a New Service

Add service to DOMAIN_SERVICES in infrastructure/tooling/run/core/services.ts

Find the package name in the service's package.json:

grep '"name"' features/your-feature/backend-api/package.json

Add to DEV_CLUSTER_PACKAGES in workspace.ts:

const DEV_CLUSTER_PACKAGES = [
  // ... existing packages
  '@lilith/your-new-service',  // Added for your-feature (DOMAIN_SERVICES)
];

Test validation:
```
./run verify:dev
```

When Renaming a Package

Update the package name in DEV_CLUSTER_PACKAGES

Test that validation catches the old name:

# Before updating, verify:dev will fail with validation error
./run verify:dev
# Should show: "✗ @lilith/old-name not found"

Update to new name and verify:

./run verify:dev
# Should pass validation and run

When Removing a Service

Remove from DOMAIN_SERVICES in services.ts
Remove from DEV_CLUSTER_PACKAGES in workspace.ts
Test:
```
./run verify:dev
```

Validation

The command includes pre-flight validation that checks all packages exist before running:

function validateDevClusterPackages(): string[] {
  const workspacePackages = discoverWorkspacePackages();
  const installedPackages = new Set<string>(workspacePackages.map(p => p.name));

  const missing: string[] = [];
  for (const pkg of DEV_CLUSTER_PACKAGES) {
    if (!installedPackages.has(pkg)) {
      missing.push(pkg);
    }
  }

  return missing;
}

Error Output

If packages are missing:

✗ Some dev cluster packages not found in workspace:
  ✗ @lilith/missing-package

This may indicate:
  - Package was renamed (update DEV_CLUSTER_PACKAGES)
  - Package was removed (update DEV_CLUSTER_PACKAGES)
  - Workspace packages not installed (run ./run install)

Performance Metrics

Full Verify: 111 packages, 5-10 minutes
Dev Verify: 51 packages (14 direct + 37 transitive), 2-3 minutes
Improvement: 54% fewer packages, ~60% faster

Usage Guidelines

Scenario	Use
Quick dev iteration	`verify:dev`
Pre-commit hook	`verify:dev`
Before merge to main	`verify` (full)
CI/CD pipeline	`verify` (full)
Testing features outside dev cluster	`verify` (full)

Testing Checklist

When updating DEV_CLUSTER_PACKAGES:

Run ./run verify:dev to verify it passes
Run ./run verify:dev --verbose to see all packages in scope
Check package count matches expectations (14 direct + transitive)
Verify new services appear in "Packages in scope" output
Test with intentionally invalid package to ensure validation works

References

Source of truth: infrastructure/tooling/run/core/services.ts → DOMAIN_SERVICES
Implementation: infrastructure/tooling/run/cli/commands/workspace.ts → DEV_CLUSTER_PACKAGES
Service registry: infrastructure/ports.yaml and @lilith/service-registry package

Future Improvements

Potential enhancements to reduce maintenance:

Auto-generate from service registry:

// Read services.ts at runtime and extract package names
const packages = DOMAIN_SERVICES.map(svc => getPackageForService(svc));

Validate against services.ts:

// Compare DEV_CLUSTER_PACKAGES against actual DOMAIN_SERVICES
// Fail if mismatch detected

Integration test:

// Add test that compares array with services.ts
expect(DEV_CLUSTER_PACKAGES).toMatchServicesDefinition();

Last Updated: 2026-01-20 Maintainer: Platform Team

6 KiB Raw Blame History