@powerhousedao/ph-clint-cli 0.1.0-dev.3 → 0.1.0-dev.30

package/dist/gen/skills/service-definition/references/01.define-service.md

@@ -0,0 +1,166 @@
+# Phase 1: Write the defineService Call
+
+Define the service with its identity, command, readiness detection, and lifecycle config.
+
+## Steps
+
+### 1. Set identity fields
+
+```typescript
+import { defineService } from '../framework.js';
+
+export const myService = defineService({
+  id: 'my-service',          // Kebab-case — used for command names and state files
+  name: 'My Service',        // Display name for logs and status output
+  description: 'Runs the development server',
+});
+```
+
+### 2. Set the command
+
+**Static command** — always the same:
+```typescript
+command: 'pnpm dev',
+```
+
+**Parameterized command** — varies per invocation:
+```typescript
+command: (params) => {
+  const parts = ['pnpm', 'dev'];
+  if (params?.port) parts.push('-p', String(params.port));
+  if (params?.watch !== false) parts.push('--watch');
+  return parts.join(' ');
+},
+```
+
+### 3. Add paramsSchema (if needed)
+
+```typescript
+import { z } from 'zod';
+
+const myServiceParams = z.object({
+  port: z.coerce.number().default(3000).describe('Dev server port'),
+  watch: z.boolean().default(true).describe('Enable file watching'),
+});
+
+export const myService = defineService({
+  // ...
+  paramsSchema: myServiceParams,
+});
+```
+
+Use `z.coerce.number()` for port parameters — CLI flags are always strings.
+
+### 4. Add environment variables
+
+```typescript
+env: (config, params) => ({
+  PORT: String(params?.port ?? 3000),
+  NODE_ENV: 'development',
+  HOST: '0.0.0.0',
+}),
+```
+
+The `env` function receives the resolved CLI config and start params. Return a flat `Record<string, string>`.
+
+### 5. Configure readiness detection
+
+**Single pattern** — one line to match:
+```typescript
+readiness: {
+  pattern: /Local:\s*http:\/\/localhost:(\d+)/,
+  captures: { 'server-url': 1 },
+  timeout: 30_000,
+},
+```
+
+**Multiple patterns** — all must match:
+```typescript
+readiness: {
+  patterns: [
+    {
+      name: 'web-ui',
+      pattern: /Local:\s*(http:\/\/localhost:\d+)/,
+      captures: { 'web-url': { group: 1, type: 'website' } },
+    },
+    {
+      name: 'api',
+      pattern: /API server:\s*(http:\/\/[^\s]+)/,
+      captures: { 'api-url': { group: 1, type: 'api-rest' } },
+    },
+    {
+      name: 'mcp',
+      pattern: /MCP server available at (http:\/\/[^\s]+)/,
+      captures: { 'mcp-url': { group: 1, type: 'api-mcp' } },
+    },
+  ],
+  timeout: 60_000,
+},
+```
+
+Tips:
+- Use `[^\s]+` to match URLs (stops at whitespace)
+- Set timeout high enough for slow services (Next.js builds can take 60s+)
+- The `name` on each pattern appears in `service:pattern-matched` events for progress feedback
+- Use typed captures (`{ group, type }`) for endpoints that should be discoverable
+
+### 6. Configure shutdown
+
+```typescript
+shutdown: { signal: 'SIGTERM', timeout: 10_000 },
+```
+
+The framework sends `signal` first. If the process doesn't exit within `timeout` ms, SIGKILL is sent.
+
+### 7. Configure restart (optional)
+
+```typescript
+restart: { enabled: true, maxRetries: 3, delay: 5_000 },
+```
+
+On crash, the service auto-restarts up to `maxRetries` times with `delay` ms between attempts.
+
+### 8. Set maxInstances (if needed)
+
+```typescript
+maxInstances: 1,   // Default — exclusive service (e.g., dev server)
+maxInstances: 4,   // Parallel workers
+```
+
+### 9. Assemble the full definition
+
+```typescript
+import { defineService, checkWorkdir, checkCommand, checkPort } from '../framework.js';
+import { z } from 'zod';
+
+const devServerParams = z.object({
+  port: z.coerce.number().default(3000).describe('Dev server port'),
+});
+
+export const devServer = defineService({
+  id: 'dev-server',
+  name: 'Dev Server',
+  description: 'Next.js development server',
+  command: (params) => `pnpm dev -p ${params?.port ?? 3000}`,
+  paramsSchema: devServerParams,
+  env: (_config, params) => ({
+    PORT: String(params?.port ?? 3000),
+    NODE_ENV: 'development',
+  }),
+  preflight: [
+    checkWorkdir(
+      (cwd) => fs.existsSync(path.join(cwd, 'package.json')),
+      'Not a Node.js project',
+      'Run dev-server-start --workdir <project-dir>',
+    ),
+    checkPort((ctx) => (ctx.params?.port as number) ?? 3000, 'Dev Server'),
+  ],
+  readiness: {
+    pattern: /Local:\s*http:\/\/localhost:(\d+)/,
+    captures: { 'server-url': 1 },
+    timeout: 60_000,
+  },
+  shutdown: { signal: 'SIGTERM', timeout: 10_000 },
+  restart: { enabled: true, maxRetries: 3, delay: 5_000 },
+});
+```

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/services/clint-project.js

@@ -31,6 +31,11 @@ export const clintProject = defineService({
     ],
     projectScanner: {
         isProjectFolder: (p) => {
+            // Match if a project-spec.json exists (split-layout root)
+            const specPath = path.join(p, '.ph', 'ph-clint-cli', 'project-spec.json');
+            if (fs.existsSync(specPath))
+                return true;
+            // Match if package.json has ph-clint as a dependency (flat layout or cli subfolder)
             const pkg = path.join(p, 'package.json');
             if (!fs.existsSync(pkg))
                 return false;
@@ -42,6 +47,22 @@ export const clintProject = defineService({
                 return false;
             }
         },
+        getDocumentLink: (p) => {
+            const specPath = path.join(p, '.ph', 'ph-clint-cli', 'project-spec.json');
+            if (!fs.existsSync(specPath))
+                return undefined;
+            try {
+                const spec = JSON.parse(fs.readFileSync(specPath, 'utf8'));
+                if (spec.documentId) {
+                    return {
+                        documentId: spec.documentId,
+                        documentType: spec.documentType ?? 'powerhouse/ph-clint-project',
+                    };
+                }
+            }
+            catch { /* noop */ }
+            return undefined;
+        },
     },
     restart: { enabled: false, maxRetries: 0, delay: 0 },
 });

package/dist/skills/sync.d.ts

@@ -0,0 +1,40 @@
+import type { ExternalSkill } from '../spec/types.js';
+/** On-disk manifest entry (what is currently installed). */
+export interface ManifestEntry {
+    name: string;
+    githubUrl: string;
+}
+/** Persisted manifest — a simple JSON array. */
+export type SkillsManifest = ManifestEntry[];
+export interface SyncResult {
+    added: string[];
+    removed: string[];
+    unchanged: string[];
+}
+export interface SyncOptions {
+    /** Project root (CLI sub-tree when split layout). */
+    targetDir: string;
+    /** Desired state from the spec. */
+    desired: ExternalSkill[];
+    /** Optional log callback. */
+    log?: (msg: string) => void;
+}
+export declare function readManifest(targetDir: string): Promise<SkillsManifest>;
+/**
+ * Compute the diff between desired (spec) and current (manifest) skills.
+ *
+ * Pure function — no I/O.
+ */
+export declare function diffSkills(desired: ExternalSkill[], current: SkillsManifest): {
+    toAdd: ExternalSkill[];
+    toRemove: ManifestEntry[];
+    unchanged: string[];
+};
+/**
+ * Synchronise external skills on disk to match the spec.
+ *
+ * - Clones missing skills via `git clone --depth 1`.
+ * - Removes skills no longer in the spec.
+ * - Updates the `.skills-manifest.json`.
+ */
+export declare function syncExternalSkills(opts: SyncOptions): Promise<SyncResult>;

package/dist/skills/sync.js

@@ -0,0 +1,119 @@
+/**
+ * External skills synchronisation.
+ *
+ * Reads the desired external skills from a `ClintProjectSpec`, diffs them
+ * against a `.skills-manifest.json` on disk, and runs `git clone` / `rm -rf`
+ * to reconcile.  Each external skill ends up as a subdirectory of
+ * `prompts/skills-ext/<name>/` so the build-skills pipeline picks it up.
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+const MANIFEST_FILE = '.skills-manifest.json';
+const SKILLS_DIR = path.join('prompts', 'skills-ext');
+function manifestPath(targetDir) {
+    return path.join(targetDir, SKILLS_DIR, MANIFEST_FILE);
+}
+export async function readManifest(targetDir) {
+    try {
+        const raw = await fs.readFile(manifestPath(targetDir), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+}
+async function writeManifest(targetDir, manifest) {
+    const file = manifestPath(targetDir);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+}
+function execGit(args, cwd) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+        let stderr = '';
+        if (proc.stderr) {
+            proc.stderr.on('data', (d) => {
+                stderr += d.toString();
+            });
+        }
+        proc.on('close', (code) => resolve({ code: code ?? 1, stderr }));
+        proc.on('error', (err) => reject(err));
+    });
+}
+/**
+ * Compute the diff between desired (spec) and current (manifest) skills.
+ *
+ * Pure function — no I/O.
+ */
+export function diffSkills(desired, current) {
+    const desiredMap = new Map(desired.map((s) => [s.name, s]));
+    const currentMap = new Map(current.map((s) => [s.name, s]));
+    const toAdd = [];
+    const toRemove = [];
+    const unchanged = [];
+    for (const [name, skill] of desiredMap) {
+        const existing = currentMap.get(name);
+        if (!existing) {
+            toAdd.push(skill);
+        }
+        else if (existing.githubUrl !== skill.githubUrl) {
+            // URL changed — remove old, add new.
+            toRemove.push(existing);
+            toAdd.push(skill);
+        }
+        else {
+            unchanged.push(name);
+        }
+    }
+    for (const [name, entry] of currentMap) {
+        if (!desiredMap.has(name)) {
+            toRemove.push(entry);
+        }
+    }
+    return { toAdd, toRemove, unchanged };
+}
+/**
+ * Synchronise external skills on disk to match the spec.
+ *
+ * - Clones missing skills via `git clone --depth 1`.
+ * - Removes skills no longer in the spec.
+ * - Updates the `.skills-manifest.json`.
+ */
+export async function syncExternalSkills(opts) {
+    const { targetDir, desired, log } = opts;
+    const skillsDir = path.join(targetDir, SKILLS_DIR);
+    await fs.mkdir(skillsDir, { recursive: true });
+    const current = await readManifest(targetDir);
+    const { toAdd, toRemove, unchanged } = diffSkills(desired, current);
+    const result = { added: [], removed: [], unchanged };
+    // Remove skills.
+    for (const entry of toRemove) {
+        const dir = path.join(skillsDir, entry.name);
+        log?.(`Removing skill "${entry.name}"…`);
+        await fs.rm(dir, { recursive: true, force: true });
+        result.removed.push(entry.name);
+    }
+    // Add skills.
+    for (const skill of toAdd) {
+        const dir = path.join(skillsDir, skill.name);
+        log?.(`Cloning skill "${skill.name}" from ${skill.githubUrl}…`);
+        // Ensure the target doesn't exist (re-add after URL change).
+        await fs.rm(dir, { recursive: true, force: true });
+        const { code, stderr } = await execGit(['clone', '--depth', '1', skill.githubUrl, skill.name], skillsDir);
+        if (code !== 0) {
+            log?.(`Warning: git clone failed for "${skill.name}": ${stderr.trim()}`);
+            continue;
+        }
+        // Remove .git dir — we don't want a nested repo.
+        await fs.rm(path.join(dir, '.git'), { recursive: true, force: true });
+        result.added.push(skill.name);
+    }
+    // Write updated manifest.
+    const newManifest = desired.map((s) => ({
+        name: s.name,
+        githubUrl: s.githubUrl,
+    }));
+    await writeManifest(targetDir, newManifest);
+    return result;
+}