201 lines
6 KiB
Markdown
201 lines
6 KiB
Markdown
# 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
|