@powerhousedao/ph-clint-cli 0.1.0-dev.11 → 0.1.0-dev.111

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/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;

package/dist/spec/from-document.js

@@ -5,26 +5,14 @@ import { clintProjectSpecSchema, } 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 function specFromDocumentState(state) {
+export function specFromDocumentState(state, meta) {
     if (!state.name)
         return null;
-    // `documentTypes` is a forward-compatible field — older `ph-clint-project`
-    // document states don't declare it yet. Pull through if present, otherwise
-    // leave it to the schema default (`[]`). Codegen treats the empty list as
-    // "no registry entries" and emits an empty `defineRegistry([...])`.
-    const documentTypes = state.documentTypes ?? undefined;
     const parsed = clintProjectSpecSchema.safeParse({
-        name: state.name,
+        ...state,
         scope: state.scope ?? undefined,
-        version: state.version,
-        description: state.description,
-        bin: state.bin ?? undefined,
-        features: {
-            powerhouse: { ...state.features.powerhouse },
-            mastra: { ...state.features.mastra },
-            routine: { ...state.features.routine },
-        },
-        ...(Array.isArray(documentTypes) ? { documentTypes } : {}),
+        documentId: meta?.documentId,
+        documentType: meta?.documentType,
     });
     return parsed.success ? parsed.data : null;
 }

package/dist/spec/types.d.ts

@@ -1,62 +1 @@
-/**
- * ClintProjectSpec — the in-memory shape that describes a ph-clint
- * implementation project. Persisted at
- * `{impl-project}/.ph/ph-clint-cli/project-spec.json` and consumed by
- * the code generator (src/codegen/).
- *
- * Intentionally minimal. Richer structure (services, skills, agents,
- * triggers, document-models) gets added in later phases as each
- * generator step actually needs it.
- */
-import { z } from 'zod';
-export declare const clintProjectSpecSchema: z.ZodObject<{
-    name: z.ZodString;
-    scope: z.ZodOptional<z.ZodString>;
-    version: z.ZodDefault<z.ZodString>;
-    description: z.ZodDefault<z.ZodString>;
-    bin: z.ZodOptional<z.ZodString>;
-    features: z.ZodDefault<z.ZodObject<{
-        powerhouse: z.ZodDefault<z.ZodObject<{
-            enabled: z.ZodDefault<z.ZodBoolean>;
-            switchboard: z.ZodDefault<z.ZodBoolean>;
-            connect: z.ZodDefault<z.ZodBoolean>;
-        }, z.core.$strip>>;
-        mastra: z.ZodDefault<z.ZodObject<{
-            enabled: z.ZodDefault<z.ZodBoolean>;
-        }, z.core.$strip>>;
-        routine: z.ZodDefault<z.ZodObject<{
-            enabled: z.ZodDefault<z.ZodBoolean>;
-        }, z.core.$strip>>;
-    }, z.core.$strip>>;
-    documentTypes: z.ZodDefault<z.ZodArray<z.ZodString>>;
-}, z.core.$strip>;
-export type ClintProjectSpec = z.infer<typeof clintProjectSpecSchema>;
-export type ClintProjectSpecInput = z.input<typeof clintProjectSpecSchema>;
-/** npm package name (e.g. `@scope/foo` or `foo`). */
-export declare function getPackageName(spec: ClintProjectSpec): string;
-/** bin name (defaults to the bare project name). */
-export declare function getBinName(spec: ClintProjectSpec): string;
-/**
- * Name of the CLI sub-folder when the project is split (Powerhouse enabled).
- * For flat projects this is irrelevant — callers use the project root directly.
- */
-export declare function getCliFolderName(spec: ClintProjectSpec): string;
-/**
- * Name of the reactor-package sub-folder when the project is split.
- */
-export declare function getAppFolderName(spec: ClintProjectSpec): string;
-/**
- * Folder slug for a documentType ID. The slug is the portion after the last
- * `/` (e.g. `powerhouse/ph-clint-project` → `ph-clint-project`). Matches the
- * convention used by Powerhouse's reactor-package codegen — each document
- * model lives at `document-models/<slug>/`.
- */
-export declare function getDocumentTypeSlug(documentType: string): string;
-/**
- * PascalCase export name for a documentType ID. Powerhouse's module
- * generator exports each module as `PascalCase(<slug>)` (e.g.
- * `powerhouse/ph-clint-project` → `PhClintProject`). The top-level reactor
- * package re-exports these names, so this helper gives codegen the string
- * it needs both for the import and the `defineRegistry` entry.
- */
-export declare function getDocumentTypeModuleName(documentType: string): string;
+export { POWERHOUSE_LEVELS, powerhouseLevelSchema, type PowerhouseLevel, phAtLeast, agentModelSchema, type AgentModel, agentProfileSchema, type AgentProfile, powerhousePackageSchema, type PowerhousePackage, externalSkillSchema, type ExternalSkill, clintProjectSpecSchema, type ClintProjectSpec, type ClintProjectSpecInput, getPackageName, getBinName, getCliFolderName, getAppFolderName, getAllDocumentTypes, getAppPackageName, getAppDirName, getDocumentTypeSlug, getDocumentTypeModuleName, isDocTypeGlob, docTypeGlobToRegex, } from '@powerhousedao/ph-clint-dev/spec';