# 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

```typescript
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`:
   ```bash
   grep '"name"' features/your-feature/backend-api/package.json
   ```

3. **Add to DEV_CLUSTER_PACKAGES** in `workspace.ts`:
   ```typescript
   const DEV_CLUSTER_PACKAGES = [
     // ... existing packages
     '@lilith/your-new-service',  // Added for your-feature (DOMAIN_SERVICES)
   ];
   ```

4. **Test validation**:
   ```bash
   ./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**:
   ```bash
   # 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:
   ```bash
   ./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**:
   ```bash
   ./run dev:verify:cluster
   ```

## Validation

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

```typescript
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:**
   ```typescript
   // Read services.ts at runtime and extract package names
   const packages = DOMAIN_SERVICES.map(svc => getPackageForService(svc));
   ```

2. **Validate against services.ts:**
   ```typescript
   // Compare DEV_CLUSTER_PACKAGES against actual DOMAIN_SERVICES
   // Fail if mismatch detected
   ```

3. **Integration test:**
   ```typescript
   // Add test that compares array with services.ts
   expect(DEV_CLUSTER_PACKAGES).toMatchServicesDefinition();
   ```

---

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