@powerhousedao/ph-clint-cli 0.1.0-dev.8 → 0.1.0-dev.81

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;
+}

package/dist/spec/ensure-document.d.ts

@@ -0,0 +1,17 @@
+import type { FolderOperations } from '@powerhousedao/ph-clint';
+import type { ReactorContext, DocumentRegistry } from '@powerhousedao/ph-clint';
+import type { ClintProjectSpec } from './types.js';
+export interface EnsureSpecDocumentResult {
+    docId: string;
+    created: boolean;
+}
+/**
+ * Ensure the spec document exists in the personal drive. Creates one if
+ * missing or if the existing `documentId` no longer resolves to a drive node.
+ */
+export declare function ensureSpecDocument<R extends DocumentRegistry = DocumentRegistry>(opts: {
+    spec: ClintProjectSpec;
+    targetDir: string;
+    reactor: ReactorContext<R>;
+    folders: FolderOperations;
+}): Promise<EnsureSpecDocumentResult>;

package/dist/spec/ensure-document.js

@@ -0,0 +1,56 @@
+/**
+ * Ensure a ph-clint-project spec document exists in the personal drive.
+ *
+ * Single code path used by:
+ *   - `clint-project-init` (after scaffolding)
+ *   - `clint-project-regen` (recover deleted docs)
+ *   - `spec-change` trigger (auto-link unlinked projects)
+ *
+ * If the spec already has a `documentId` that exists in the drive, this is
+ * a no-op. If the document was deleted (or never created), a new one is
+ * created, added to the drive at `specs/{name}`, and the spec JSON on disk
+ * is updated with the new `documentId`.
+ */
+import { importSpec } from '@powerhousedao/ph-clint-app/document-models/ph-clint-project';
+import { writeProjectSpec } from './file.js';
+import { specToImportInput } from '../triggers/spec-change.js';
+const DOCUMENT_TYPE = 'powerhouse/ph-clint-project';
+/**
+ * Ensure the spec document exists in the personal drive. Creates one if
+ * missing or if the existing `documentId` no longer resolves to a drive node.
+ */
+export async function ensureSpecDocument(opts) {
+    const { spec, targetDir, reactor, folders } = opts;
+    // Check if the document already exists in the drive's folder tree
+    if (spec.documentId) {
+        const entries = await folders.findByType(DOCUMENT_TYPE);
+        const inDrive = entries.some((e) => e.id === spec.documentId);
+        if (inDrive)
+            return { docId: spec.documentId, created: false };
+    }
+    let docId;
+    if (spec.documentId) {
+        try {
+            await reactor.client.get(spec.documentId);
+            docId = spec.documentId;
+            // Orphan recovery: doc exists in reactor but not in drive. Re-attach via
+            // addDocument; we can't retrofit CREATE/UPGRADE into the drive's stream.
+            await folders.addDocument(docId, `specs/${spec.name}`, spec.name);
+        }
+        catch {
+            const created = await folders.createDocument(DOCUMENT_TYPE, `specs/${spec.name}`, spec.name);
+            docId = created.documentId;
+        }
+    }
+    else {
+        const created = await folders.createDocument(DOCUMENT_TYPE, `specs/${spec.name}`, spec.name);
+        docId = created.documentId;
+    }
+    const importInput = specToImportInput(spec);
+    await reactor.client.execute(docId, 'main', [importSpec(importInput)]);
+    // Persist the link back to disk
+    spec.documentId = docId;
+    spec.documentType = DOCUMENT_TYPE;
+    await writeProjectSpec(targetDir, spec);
+    return { docId, created: true };
+}

package/dist/spec/file.d.ts

@@ -1,4 +1 @@
-import { type ClintProjectSpec } from './types.js';
-export declare function getSpecPath(projectDir: string): string;
-export declare function readProjectSpec(projectDir: string): Promise<ClintProjectSpec | null>;
-export declare function writeProjectSpec(projectDir: string, spec: ClintProjectSpec): Promise<void>;
+export { getSpecPath, readProjectSpec, writeProjectSpec, } from '@powerhousedao/ph-clint-dev/spec/file';

package/dist/spec/file.js

@@ -1,34 +1 @@
-/**
- * Persistence for `ClintProjectSpec`.
- * Stored at `{impl-project}/.ph/ph-clint-cli/project-spec.json`.
- */
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { clintProjectSpecSchema, } from './types.js';
-const SPEC_DIR = path.join('.ph', 'ph-clint-cli');
-const SPEC_FILE = 'project-spec.json';
-export function getSpecPath(projectDir) {
-    return path.join(projectDir, SPEC_DIR, SPEC_FILE);
-}
-function isEnoent(err) {
-    return (!!err &&
-        typeof err === 'object' &&
-        'code' in err &&
-        err.code === 'ENOENT');
-}
-export async function readProjectSpec(projectDir) {
-    try {
-        const raw = await fs.readFile(getSpecPath(projectDir), 'utf8');
-        return clintProjectSpecSchema.parse(JSON.parse(raw));
-    }
-    catch (err) {
-        if (isEnoent(err))
-            return null;
-        throw err;
-    }
-}
-export async function writeProjectSpec(projectDir, spec) {
-    const file = getSpecPath(projectDir);
-    await fs.mkdir(path.dirname(file), { recursive: true });
-    await fs.writeFile(file, JSON.stringify(spec, null, 2) + '\n', 'utf8');
-}
+export { getSpecPath, readProjectSpec, writeProjectSpec, } from '@powerhousedao/ph-clint-dev/spec/file';

package/dist/spec/from-document.d.ts

@@ -15,4 +15,7 @@ import { type ClintProjectSpec } from './types.js';
  * Returns `null` if the document has no valid package name yet — callers
  * should wait for the user to populate it before triggering codegen.
  */
-export declare function specFromDocumentState(state: PhClintProjectGlobalState): ClintProjectSpec | null;
+export declare function specFromDocumentState(state: PhClintProjectGlobalState, meta?: {
+    documentId?: string;
+    documentType?: string;
+}): ClintProjectSpec | null;