@powerhousedao/ph-clint-cli 0.1.0-dev.22 → 0.1.0-dev.24

package/dist/gen/skills/service-definition/references/02.add-preflight.md

@@ -0,0 +1,132 @@
+# Phase 2: Add Preflight Validation Checks
+
+Add checks that run before the service process spawns. These catch common failure modes early with clear error messages.
+
+## Steps
+
+### 1. Add workdir check
+
+Use `checkWorkdir()` when the service requires specific directory structure:
+
+```typescript
+import { checkWorkdir } from '../framework.js';
+import fs from 'node:fs';
+import path from 'node:path';
+
+preflight: [
+  checkWorkdir(
+    (cwd) => fs.existsSync(path.join(cwd, 'package.json')),
+    'Not a Node.js project',
+    'Run {id}-start --workdir <project-dir>, or create a project first',
+  ),
+],
+```
+
+The `test` function receives the resolved working directory. Return `true` if valid.
+
+You can check for multiple files:
+```typescript
+checkWorkdir(
+  (cwd) => fs.existsSync(path.join(cwd, 'powerhouse.config.ts'))
+         || fs.existsSync(path.join(cwd, 'powerhouse.config.json')),
+  'Not a Reactor Package project',
+  'Run {id}-start --workdir <project>, or create one with /init',
+),
+```
+
+### 2. Add binary checks
+
+Use `checkCommand()` for required binaries:
+
+```typescript
+import { checkCommand } from '../framework.js';
+
+checkCommand('node', {
+  hint: 'Install Node.js from https://nodejs.org',
+}),
+checkCommand('pnpm', {
+  hint: 'Install pnpm: npm install -g pnpm',
+}),
+checkCommand('ph', {
+  hint: 'Install the Powerhouse CLI: npm install -g ph-cli',
+}),
+```
+
+With version validation:
+```typescript
+checkCommand('node', {
+  versionFlag: '--version',
+  versionTest: (v) => parseInt(v.replace('v', '')) >= 22,
+  hint: 'Node.js >= 22 is required. Update from https://nodejs.org',
+}),
+```
+
+### 3. Add port checks
+
+Use `checkPort()` for each port the service binds to:
+
+**Static port**:
+```typescript
+import { checkPort } from '../framework.js';
+
+checkPort(3000, 'Dev Server'),
+```
+
+**Dynamic port from params**:
+```typescript
+checkPort((ctx) => (ctx.params?.port as number) ?? 3000, 'Dev Server'),
+```
+
+**Multiple ports**:
+```typescript
+checkPort((ctx) => (ctx.params?.connectPort as number) ?? 3000, 'Connect Studio'),
+checkPort((ctx) => (ctx.params?.switchboardPort as number) ?? 4001, 'Switchboard'),
+```
+
+### 4. Order checks correctly
+
+Place checks in order from cheapest to most expensive:
+
+```typescript
+preflight: [
+  // 1. Workdir check — pure filesystem, instant
+  checkWorkdir(
+    (cwd) => fs.existsSync(path.join(cwd, 'package.json')),
+    'Not a Node.js project',
+  ),
+  // 2. Binary check — spawns a process, fast
+  checkCommand('pnpm', { hint: 'Install pnpm: npm install -g pnpm' }),
+  // 3. Port check — network I/O, slowest
+  checkPort((ctx) => (ctx.params?.port as number) ?? 3000, 'Dev Server'),
+],
+```
+
+### 5. Write custom preflight checks (if needed)
+
+For checks not covered by the built-in factories, write a custom function:
+
+```typescript
+preflight: [
+  async (ctx) => {
+    const configPath = path.join(ctx.cwd, '.env');
+    if (!fs.existsSync(configPath)) {
+      return {
+        ok: false,
+        message: 'Missing .env file',
+        hint: 'Copy .env.example to .env and fill in the values',
+      };
+    }
+    return { ok: true };
+  },
+],
+```
+
+Custom checks receive `PreflightContext` with `cwd`, `config`, `params`, and `command`.
+
+### 6. Write clear error messages and hints
+
+Every failing check should tell the user:
+- **What's wrong**: `'Port 3000 is already in use'`
+- **How to fix it** (hint): `'Stop the other process or use --port <number>'`
+
+Good hints save users from having to search for solutions.

package/dist/gen/skills/service-definition/references/03.add-project-scanner.md

@@ -0,0 +1,82 @@
+# Phase 3: Add Project Scanner (Optional)
+
+Add project scanning when one service definition can manage multiple project directories. Skip this phase if the service always runs in a single fixed location.
+
+## When to Add a Scanner
+
+- A dev server that can run in any project folder matching a pattern
+- A reactor service that works with any Powerhouse project
+- Any service where users need to discover eligible project directories
+
+## Steps
+
+### 1. Define the scanner
+
+At minimum, implement `isProjectFolder`:
+
+```typescript
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const myService = defineService({
+  // ...
+  projectScanner: {
+    isProjectFolder: (p) => fs.existsSync(path.join(p, 'next.config.ts')),
+  },
+});
+```
+
+### 2. Add getProjectName (recommended)
+
+Extract a display name from the project directory:
+
+```typescript
+projectScanner: {
+  isProjectFolder: (p) => fs.existsSync(path.join(p, 'package.json')),
+  getProjectName: (p) => {
+    const pkg = JSON.parse(fs.readFileSync(path.join(p, 'package.json'), 'utf-8'));
+    return pkg.name ?? path.basename(p);
+  },
+},
+```
+
+### 3. Add getProjectConfig (optional)
+
+Return project-specific configuration:
+
+```typescript
+getProjectConfig: (p) => {
+  const pkg = JSON.parse(fs.readFileSync(path.join(p, 'package.json'), 'utf-8'));
+  return { name: pkg.name, version: pkg.version };
+},
+```
+
+### 4. Add getDocumentLink (optional, Powerhouse projects)
+
+Return a document reference for Powerhouse-linked projects:
+
+```typescript
+getDocumentLink: (p) => {
+  const configPath = path.join(p, 'powerhouse.config.json');
+  if (!fs.existsSync(configPath)) return undefined;
+  const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  return config.documentId
+    ? { documentId: config.documentId, documentType: config.documentType }
+    : undefined;
+},
+```
+
+### 5. How scanning works
+
+When `projectScanner` is defined:
+- The auto-generated `{id}-ls` command becomes available
+- `services.scanProjects(serviceId, rootDir)` performs a breadth-first search
+- The scanner prunes subtrees at foreign project boundaries (`package.json`, `Cargo.toml`, etc.)
+- Returns `ProjectScanResult[]` with `{ name, path, config?, documentId?, documentType? }`
+
+### 6. Using scan results
+
+Scan results are useful for:
+- Listing projects in the REPL (`/{id}-ls`)
+- Auto-starting services for discovered projects
+- Building project selection menus in interactive mode

package/dist/gen/skills/service-definition/references/04.wire-events.md

@@ -0,0 +1,120 @@
+# Phase 4: Wire Service Lifecycle Events
+
+Handle service state transitions for logging, notifications, and dependent actions.
+
+## Steps
+
+### 1. Add event handlers in defineCli
+
+Service events are wired via the `events` property in `defineCli()`:
+
+```typescript
+import { defineCli } from '@powerhousedao/ph-clint';
+
+const cli = defineCli({
+  // ...
+  services: [myService],
+  events: {
+    'service:pattern-matched': (event, log) => {
+      log.info(`${event.name}: matched "${event.patternName}" (${event.remaining} remaining)`);
+    },
+    'service:ready': (event, log) => {
+      log.info(`${event.name} is ready`);
+      if (event.endpoints) {
+        for (const [name, url] of Object.entries(event.endpoints)) {
+          log.info(`  ${name}: ${url}`);
+        }
+      }
+    },
+    'service:failed': (event, log) => {
+      log.error(`${event.name} failed: ${event.error}`);
+    },
+    'service:restarting': (event, log) => {
+      log.warn(`${event.name} restarting (attempt ${event.attempt}/${event.maxRetries})`);
+    },
+    'service:stopped': (event, log) => {
+      log.info(`${event.name} stopped`);
+    },
+  },
+});
+```
+
+### 2. Understand event payloads
+
+Each event handler receives `(event, log)`:
+- `event` — typed payload with `id`, `instanceId`, `name`, and event-specific fields
+- `log` — structured Logger with `debug`, `info`, `warn`, `error` methods
+
+**`service:pattern-matched`** — fired progressively as each readiness pattern matches:
+- `event.patternName` — which pattern matched
+- `event.endpoints` — captured endpoints so far
+- `event.endpointTypes` — endpoint types so far
+- `event.remaining` — number of patterns still unmatched
+
+**`service:ready`** — fired when ALL patterns have matched:
+- `event.endpoints` — all captured endpoints
+- `event.endpointTypes` — all endpoint types
+
+**`service:failed`** — fired on readiness timeout or process crash:
+- `event.error` — error message (includes log tail for diagnosis)
+
+**`service:restarting`** — fired when auto-restart triggers:
+- `event.attempt` — current attempt number
+- `event.maxRetries` — maximum attempts configured
+
+**`service:stopped`** — fired after explicit stop completes
+
+### 3. Common event patterns
+
+**Log endpoints on ready**:
+```typescript
+'service:ready': (event, log) => {
+  const urls = Object.entries(event.endpoints ?? {})
+    .map(([name, url]) => `  ${name}: ${url}`)
+    .join('\n');
+  log.info(`${event.name} ready\n${urls}`);
+},
+```
+
+**Trigger dependent service startup**:
+```typescript
+'service:ready': async (event, log) => {
+  if (event.id === 'backend') {
+    log.info('Backend ready, starting frontend...');
+    // Frontend can now connect to the backend URL
+  }
+},
+```
+
+**Progress feedback during startup**:
+```typescript
+'service:pattern-matched': (event, log) => {
+  if (event.remaining > 0) {
+    log.info(`${event.name}: ${event.patternName} ready, waiting for ${event.remaining} more...`);
+  }
+},
+```
+
+### 4. Register the service in defineCli
+
+**In a codegen-managed project** (cli.ts has `@clint:begin` markers):
+
+Do NOT manually edit `cli.ts` marker regions. Instead:
+
+1. Add the service to `project-spec.json`
+2. Run `clint-project-regen` — this regenerates the `@clint:begin services`, `@clint:begin imports`, and `@clint:begin events` marker regions
+3. Run `clint-project-build` to verify TypeScript compiles
+
+**In a manually-managed project** (no markers):
+
+```typescript
+import { myService } from './services/my-service.js';
+
+const cli = defineCli({
+  services: [myService],
+  events: { /* ... */ },
+  // ...
+});
+```
+
+This auto-injects the management commands: `{id}-start`, `{id}-stop`, `{id}-restart`, `{id}-ps`, `{id}-logs`, `{id}-manage`, and `{id}-ls` (if projectScanner is defined).

package/dist/gen/skills/service-definition/references/expected-outcome.md

@@ -0,0 +1,3 @@
+## Expected Outcome
+
+Service is defined with readiness detection, preflight checks, and lifecycle config. It is registered in `defineCli`, auto-generates management commands (`{id}-start`, `{id}-stop`, etc.), and transitions through starting/ready/failed states correctly. Endpoints are captured and typed. Preflight checks fail fast with clear messages and hints.

package/dist/spec/types.d.ts

@@ -23,6 +23,17 @@ export declare const powerhouseLevelSchema: z.ZodDefault<z.ZodEnum<{
 export type PowerhouseLevel = z.infer<typeof powerhouseLevelSchema>;
 /** Check whether `level` is at least `threshold` in the ordered enum. */
 export declare function phAtLeast(level: PowerhouseLevel, threshold: PowerhouseLevel): boolean;
+export declare const agentModelSchema: z.ZodObject<{
+    id: z.ZodString;
+    isDefault: z.ZodBoolean;
+}, z.core.$strip>;
+export type AgentModel = z.infer<typeof agentModelSchema>;
+export declare const agentProfileSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strip>;
+export type AgentProfile = z.infer<typeof agentProfileSchema>;
 export declare const powerhousePackageSchema: z.ZodObject<{
     id: z.ZodString;
     packageName: z.ZodString;
@@ -50,6 +61,17 @@ export declare const clintProjectSpecSchema: z.ZodObject<{
         }>>;
         mastra: z.ZodDefault<z.ZodObject<{
             enabled: z.ZodDefault<z.ZodBoolean>;
+            agentId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            agentName: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            models: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                isDefault: z.ZodBoolean;
+            }, z.core.$strip>>>;
+            profiles: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                title: z.ZodString;
+                content: z.ZodString;
+            }, z.core.$strip>>>;
         }, z.core.$strip>>;
         routine: z.ZodDefault<z.ZodObject<{
             enabled: z.ZodDefault<z.ZodBoolean>;

package/dist/spec/types.js

@@ -26,13 +26,32 @@ export const powerhouseLevelSchema = z
 export function phAtLeast(level, threshold) {
     return (POWERHOUSE_LEVELS.indexOf(level) >= POWERHOUSE_LEVELS.indexOf(threshold));
 }
+export const agentModelSchema = z.object({
+    id: z.string(),
+    isDefault: z.boolean(),
+});
+export const agentProfileSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    content: z.string(),
+});
 const mastraFeatureSchema = z.object({
     enabled: z.boolean().default(false),
+    agentId: z.string().nullable().default(null),
+    agentName: z.string().nullable().default(null),
+    models: z.array(agentModelSchema).default([]),
+    profiles: z.array(agentProfileSchema).default([]),
 });
 const routineFeatureSchema = z.object({
     enabled: z.boolean().default(false),
 });
-const DEFAULT_MASTRA = { enabled: false };
+const DEFAULT_MASTRA = {
+    enabled: false,
+    agentId: null,
+    agentName: null,
+    models: [],
+    profiles: [],
+};
 const DEFAULT_ROUTINE = { enabled: false };
 export const powerhousePackageSchema = z.object({
     id: z.string(),

package/dist/triggers/spec-change.js

@@ -86,6 +86,17 @@ export function specToImportInput(spec) {
         powerhouse: spec.features.powerhouse,
         mastraEnabled: spec.features.mastra.enabled,
         routineEnabled: spec.features.routine.enabled,
+        agentId: spec.features.mastra.agentId ?? null,
+        agentName: spec.features.mastra.agentName ?? null,
+        models: spec.features.mastra.models.map(m => ({
+            id: m.id,
+            isDefault: m.isDefault,
+        })),
+        profiles: spec.features.mastra.profiles.map(p => ({
+            id: p.id,
+            title: p.title,
+            content: p.content,
+        })),
         packages: spec.packages.map(p => ({
             id: p.id,
             packageName: p.packageName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerhousedao/ph-clint-cli",
-  "version": "0.1.0-dev.22",
+  "version": "0.1.0-dev.24",
   "publishConfig": {
     "access": "public"
   },
@@ -18,6 +18,7 @@
     "dev": "tsx src/main.ts",
     "start": "node dist/main.js",
     "test": "NODE_OPTIONS='--experimental-vm-modules' jest --detectOpenHandles",
+    "test:e2e": "NODE_OPTIONS='--experimental-vm-modules' jest --detectOpenHandles --testPathPatterns 'tests/(e2e|codegen-e2e)/' --testPathIgnorePatterns '/node_modules/'",
     "lint": "eslint src",
     "mastra:dev": "mastra dev",
     "mastra:build": "mastra build",
@@ -28,9 +29,9 @@
     "@mastra/core": "^1.22.0",
     "@mastra/libsql": "^1.7.4",
     "@mastra/memory": "^1.13.1",
-    "@powerhousedao/ph-clint": "^0.1.0-dev.22",
-    "@powerhousedao/ph-clint-app": "^0.1.0-dev.22",
-    "@powerhousedao/ph-clint-dev": "^0.1.0-dev.22",
+    "@powerhousedao/ph-clint": "^0.1.0-dev.24",
+    "@powerhousedao/ph-clint-app": "^0.1.0-dev.24",
+    "@powerhousedao/ph-clint-dev": "^0.1.0-dev.24",
     "@powerhousedao/reactor": "6.0.0-dev.170",
     "@powerhousedao/reactor-api": "6.0.0-dev.170",
     "@powerhousedao/shared": "6.0.0-dev.170",