platform-docs/dev-environment/verify-dev-maintenance.md

dev:verify:cluster Command - Maintenance Guide

Overview

The dev:verify:cluster 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
knowledge-verification.api	@lilith/knowledge-verification-api	External (knowledge-platform)
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/
• Knowledge verification → External at ~/Code/@applications/@ml/knowledge-platform/

How to Update

When Adding a New Service

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

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

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

3. Add to DEV_CLUSTER_PACKAGES in workspace.ts:

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

4. Test validation:

   ./run dev:verify:cluster
   

When Renaming a Package

1. Update the package name in DEV_CLUSTER_PACKAGES

2. Test that validation catches the old name:

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

3. Update to new name and verify:

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

When Removing a Service

1. Remove from DOMAIN_SERVICES in services.ts

2. Remove from DEV_CLUSTER_PACKAGES in workspace.ts

3. Test:

   ./run dev:verify:cluster
   

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	dev:verify:cluster
Pre-commit hook	dev:verify:cluster
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 dev:verify:cluster to verify it passes
• Run ./run dev:verify:cluster --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:

1. Auto-generate from service registry:

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

2. Validate against services.ts:

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

3. Integration test:

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

---

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