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

package/dist/gen/skills/service-definition/.cli-docs.md

@@ -0,0 +1,214 @@
+## API Reference: Service Definition
+
+### `defineService<TConfig>(options): ServiceDefinition<TConfig>`
+
+Identity function that returns the options object with full type inference. One generic parameter:
+
+- `TConfig` — the config type from `defineCli` (for typed `env()` function)
+
+### `ServiceDefinition<TConfig>` Interface
+
+```typescript
+interface ServiceDefinition<TConfig = Record<string, unknown>> {
+  id: string;                          // Kebab-case identifier (e.g. 'dev-server')
+  command: string | ((params?: Record<string, unknown>) => string);
+  name?: string;                       // Display name (e.g. 'Dev Server')
+  description?: string;                // One-line description
+  env?: (config: TConfig, params?: Record<string, unknown>) => Record<string, string>;
+  paramsSchema?: ZodType;              // Runtime parameters (become start command flags)
+  maxInstances?: number;               // Concurrency limit (default: 1)
+  preflight?: PreflightCheck<TConfig>[];
+  readiness?: ReadinessConfig;
+  shutdown?: { signal: NodeJS.Signals; timeout: number };
+  restart?: { enabled: boolean; maxRetries: number; delay: number };
+  projectScanner?: ProjectScanner;
+}
+```
+
+### `ReadinessConfig` — Single Pattern Form
+
+```typescript
+{
+  pattern: RegExp;
+  captures?: Record<string, number | CaptureDefinition>;
+  timeout: number;       // ms before marking failed
+  wait?: boolean;        // true (default) = block until match; false = ready immediately
+}
+```
+
+### `ReadinessConfig` — Multiple Patterns Form
+
+```typescript
+{
+  patterns: ReadinessPattern[];
+  timeout: number;
+  wait?: boolean;
+}
+```
+
+ALL patterns must match before the service is considered ready.
+
+### `ReadinessPattern`
+
+```typescript
+interface ReadinessPattern {
+  name: string;           // Identifier for progress reporting
+  pattern: RegExp;        // Regex to match against stdout/stderr lines
+  captures?: Record<string, number | CaptureDefinition>;
+}
+```
+
+### `CaptureDefinition`
+
+```typescript
+interface CaptureDefinition {
+  group: number;          // 1-indexed regex capture group
+  type?: EndpointType;    // Enables downstream features (e.g. MCP discovery)
+}
+```
+
+### `EndpointType` Union
+
+```typescript
+type EndpointType = 'other' | 'api-mcp' | 'api-rest' | 'api-graphql' | 'website';
+```
+
+### Preflight Checks
+
+```typescript
+type PreflightCheck<TConfig> =
+  (ctx: PreflightContext<TConfig>) => PreflightResult | Promise<PreflightResult>;
+
+interface PreflightContext<TConfig> {
+  cwd: string;
+  config: TConfig;
+  params?: Record<string, unknown>;
+  command: string;             // Resolved command string
+}
+
+type PreflightResult =
+  | { ok: true }
+  | { ok: false; message: string; hint?: string };
+```
+
+### Built-in Preflight Factories
+
+**`checkWorkdir(test, message, hint?)`**
+```typescript
+checkWorkdir(
+  test: (cwd: string) => boolean,   // Return true if valid
+  message: string,                   // Error message on failure
+  hint?: string                      // Suggested fix
+): PreflightCheck
+```
+
+**`checkCommand(binary, options?)`**
+```typescript
+checkCommand(
+  binary: string,
+  options?: {
+    versionFlag?: string;                          // Default: '--version'
+    versionTest?: (version: string) => boolean;    // Validate version output
+    hint?: string;                                 // Install instructions
+  }
+): PreflightCheck
+```
+
+**`checkPort(port, label?)`**
+```typescript
+checkPort(
+  port: number | ((ctx: PreflightContext) => number | undefined),
+  label?: string               // Display name (e.g. 'Dev Server')
+): PreflightCheck
+```
+
+**`isPortFree(port): Promise<boolean>`** — utility for custom checks.
+
+### `ServiceManager` Interface
+
+Methods available on `context.services`:
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `start` | `(id, opts?: ServiceStartOptions) => Promise<string>` | Start service, returns instanceId |
+| `stop` | `(id, instanceId?) => Promise<void>` | Stop service instance |
+| `list` | `(serviceId?) => ServiceInstanceStatus[]` | List instance statuses |
+| `getDefinition` | `(id) => ServiceDefinition \| undefined` | Look up a service definition |
+| `logs` | `(id, instanceId?, lines?) => string` | Tail service log (default 50 lines) |
+| `watchLogs` | `(id, instanceId, onLine) => () => void` | Stream log lines, returns unsubscribe |
+| `scanProjects` | `(id, rootDir) => ProjectScanResult[]` | Discover projects for a service |
+| `purgeStoppedInstances` | `(id) => void` | Clean up stopped instance state |
+
+### `ServiceStartOptions`
+
+```typescript
+interface ServiceStartOptions {
+  workdir?: string;                    // For instance identity (hashed into instanceId)
+  cwd?: string;                        // Spawn directory (defaults to process.cwd())
+  params?: Record<string, unknown>;    // Runtime parameters
+  name?: string;                       // Named instance (for multi-instance services)
+}
+```
+
+### `ServiceInstanceStatus`
+
+```typescript
+interface ServiceInstanceStatus {
+  serviceId: string;
+  instanceId: string;
+  name: string;
+  status: 'idle' | 'starting' | 'ready' | 'failed' | 'stopping' | 'stopped';
+  pid?: number;
+  endpoints?: Record<string, string>;
+  endpointTypes?: Record<string, EndpointType>;
+  error?: string;
+  restartAttempt?: number;
+  workdir?: string;
+  params?: Record<string, unknown>;
+}
+```
+
+### Service Events
+
+| Event | Payload | When |
+|-------|---------|------|
+| `service:ready` | `{ id, instanceId, name, endpoints?, endpointTypes? }` | All readiness patterns matched |
+| `service:failed` | `{ id, instanceId, name, error }` | Readiness timeout or process crash |
+| `service:stopped` | `{ id, instanceId, name }` | Explicit stop completed |
+| `service:pattern-matched` | `{ id, instanceId, name, patternName, endpoints, endpointTypes, remaining }` | One readiness pattern matched |
+| `service:restarting` | `{ id, instanceId, name, attempt, maxRetries }` | Auto-restart triggered |
+
+### `ProjectScanner` Interface
+
+```typescript
+interface ProjectScanner {
+  isProjectFolder(folderPath: string): boolean;
+  getProjectName?(folderPath: string): string;
+  getProjectConfig?(folderPath: string): Record<string, unknown>;
+  getDocumentLink?(folderPath: string): { documentId: string; documentType: string } | undefined;
+}
+```
+
+### Auto-Generated Commands per Service
+
+| Command ID | Description |
+|-----------|-------------|
+| `{id}-start` | Start the service (flags from paramsSchema + workdir + name) |
+| `{id}-stop` | Stop a running instance |
+| `{id}-restart` | Restart preserving workdir/params |
+| `{id}-ps` | Show instance status |
+| `{id}-logs` | Tail service logs (default 50 lines) |
+| `{id}-manage` | Interactive management panel (REPL only) |
+| `{id}-ls` | List discovered projects (only if projectScanner defined) |
+
+### Registration in `defineCli`
+
+Services are registered via the `services` array:
+
+```typescript
+const cli = defineCli({
+  name: 'mycli',
+  services: [devServer, workerPool],
+  // ...
+});
+```

package/dist/gen/skills/service-definition/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: service-definition
+description: "Define background services with readiness detection, preflight checks, and project scanning"
+metadata:
+  author: Powerhouse
+  version: "1.0.0"
+---
+
+=== BEGIN SKILL BRIEFING ===
+
+IMPORTANT: Don't take any action yet. You will be guided through your tasks after the briefing(s). Just process and confirm your understanding.
+
+# Service Definition - Skill Preamble
+
+With this skill, you can define ph-clint services — long-running background processes with lifecycle management, readiness detection, preflight validation, and automatic restart. A single `defineService()` call produces auto-generated management commands (`{id}-start`, `{id}-stop`, `{id}-restart`, `{id}-ps`, `{id}-logs`, `{id}-manage`) and integrates with the event bus for cross-cutting concerns.
+
+## Core Principles
+
+### Services vs Processes
+
+Services are long-running with lifecycle management (start, stop, restart, health checks). One-shot shell commands use `context.processes.run()` inside a command's execute function instead. If it runs and exits, it's a process. If it stays alive and serves requests, it's a service.
+
+### Readiness Is a Contract
+
+The service declares what "ready" looks like via stdout regex patterns. The framework watches stdout AND stderr combined, matching each line against the patterns. ALL patterns must match before the service transitions to `ready`. If any pattern never matches, the service hits the readiness timeout and is marked `failed`.
+
+### Endpoint Captures Extract URLs from Regex Groups
+
+Captures turn regex groups into named endpoints. Two forms:
+
+- **Simple**: `{ 'name': groupIndex }` — captures the regex group as a plain string
+- **Typed**: `{ 'name': { group: index, type: 'api-mcp' } }` — adds an `EndpointType` that enables downstream features like MCP tool discovery
+
+Capture groups are 1-indexed (group 0 is the full match). The `type` field accepts: `'other'`, `'api-mcp'`, `'api-rest'`, `'api-graphql'`, `'website'`.
+
+### Preflight Checks Fail Fast
+
+Preflight checks run before the process spawns. They validate preconditions (working directory, required binaries, port availability) and fail with clear messages rather than letting a process spawn and fail cryptically. Order checks from cheapest to most expensive: workdir first, then binaries, then ports (network I/O).
+
+### Shutdown and Restart Policies
+
+- **Shutdown**: `{ signal, timeout }` — sends `signal` (SIGTERM, SIGINT, or SIGKILL) then waits `timeout` ms. After timeout, SIGKILL is sent unconditionally.
+- **Restart**: `{ enabled, maxRetries, delay }` — on crash, automatically restart up to `maxRetries` times with `delay` ms between attempts.
+
+### maxInstances Controls Concurrency
+
+Use `maxInstances: 1` (default) for exclusive services like dev servers. Use higher values for services that can run multiple instances in parallel (e.g., worker pools).
+
+## Service State Machine
+
+Services transition through these states:
+
+```
+idle → starting → ready → stopping → stopped
+                ↘ failed → (restarting → starting)
+```
+
+- **idle**: Defined but never started
+- **starting**: Process spawned, waiting for readiness patterns to match
+- **ready**: All readiness patterns matched (or no readiness config), service is accepting connections
+- **failed**: Readiness timeout expired, or process crashed during startup
+- **stopping**: Shutdown signal sent, waiting for process to exit
+- **stopped**: Process has exited (clean shutdown or after force-kill)
+- **restarting**: Failed service with restart policy, waiting for delay before retry
+
+Each transition emits an event via the event bus (if configured).
+
+## Instance Identity
+
+Every running service has an `instanceId` derived from the start parameters:
+
+- No name, no workdir → instanceId = `serviceId`
+- Named instance → instanceId = `serviceId:name`
+- Workdir-derived → instanceId = `serviceId:hash8` (first 8 chars of SHA256 of workdir)
+
+This means starting the same service in different workdirs creates separate tracked instances.
+
+## The ServiceManager in Commands
+
+Commands access the service manager via `context.services`:
+
+```typescript
+// In a command's execute function
+const status = context.services!.list('my-service');
+const instanceId = await context.services!.start('my-service', { workdir: '/path' });
+const logs = context.services!.logs('my-service', instanceId, 100);
+```
+
+Always null-check `context.services` — it's `undefined` when no services are configured in `defineCli`.
+
+## Auto-Generated Management Commands
+
+When you register a service in `defineCli({ services: [...] })`, the framework auto-generates these commands:
+
+- `{id}-start` — Start with optional params, workdir, and instance name
+- `{id}-stop` — Stop by instance ID (or the default instance)
+- `{id}-restart` — Restart preserving the original workdir and params
+- `{id}-ps` — Show status of all instances
+- `{id}-logs` — Tail the log file (default 50 lines)
+- `{id}-manage` — Interactive management panel (REPL only)
+- `{id}-ls` — List discovered projects (only if `projectScanner` is defined)
+
+You don't need to write these commands yourself — they are injected automatically.
+
+## Common Pitfalls
+
+- **Patterns match stdout AND stderr** — some tools (Next.js, Vite) log to stderr; your patterns will still match
+- **Regex must match a single line** — patterns don't span lines; design them to match one log line
+- **Capture groups are 1-indexed** — group 0 is the full match, group 1 is the first capture
+- **No readiness config = immediately ready** — if you omit `readiness`, the service is marked ready right after spawn; use `readiness: { pattern: /.../, timeout: 30_000 }` to wait for actual readiness
+- **Dynamic ports need dynamic preflight** — use `checkPort((ctx) => ctx.params?.port as number ?? 3000)` when ports come from params
+- **Forgetting `checkCommand`** — the service fails cryptically if the binary isn't installed; add a preflight check with a helpful install hint
+- **Timeout too short** — services that compile on first start (Next.js, Webpack) need longer timeouts (60-90s)
+- **Static port in preflight but dynamic in params** — if the port comes from `paramsSchema`, use a function in `checkPort`, not a literal number
+
+## When to Use paramsSchema
+
+Add `paramsSchema` (a Zod schema) when the service needs runtime parameters that vary per invocation — ports, feature flags, URLs. These become flags on the auto-generated `{id}-start` command and are passed to both the `command()` and `env()` functions. Use `z.coerce.number()` for port parameters since CLI flags are always strings.
+
+## When to Use projectScanner
+
+Add `projectScanner` when one service definition manages multiple project directories (e.g., a dev server that can run in any project folder). The scanner enables the `{id}-ls` command for project discovery and integrates with `services.scanProjects()`. The scanner performs breadth-first search and prunes at foreign project boundaries.
+
+## Typed Captures and MCP Discovery
+
+Typed captures with `type: 'api-mcp'` make the captured endpoint discoverable by the agent integration. When the agent boots, it can scan service endpoints for MCP servers and automatically load their tools. This is the bridge between services and agent capabilities — you define the service, capture the MCP URL with the right type, and the agent picks it up.
+
+## Registration in Codegen-Managed Projects
+
+In codegen-managed projects, do NOT manually edit `cli.ts` marker regions to register services. Instead:
+
+1. Write the service definition file in `src/services/`
+2. Add the service to `project-spec.json`
+3. Run `clint-project-regen` to regenerate `cli.ts` (updates `@clint:begin services`, `@clint:begin imports`, and `@clint:begin events`)
+4. Run `clint-project-build` to verify
+
+Import `defineService` from `../framework.js` (not from `@powerhousedao/ph-clint`) for automatic config typing.
+
+=== END OF SKILL BRIEFING ===
+
+## Specific tasks
+
+* **Assess Service** [references/00.assess-service.md](references/00.assess-service.md)
+* **Define Service** [references/01.define-service.md](references/01.define-service.md)
+* **Add Preflight** [references/02.add-preflight.md](references/02.add-preflight.md)
+* **Add Project Scanner** [references/03.add-project-scanner.md](references/03.add-project-scanner.md)
+* **Wire Events** [references/04.wire-events.md](references/04.wire-events.md)
+* **Expected Outcome** [references/expected-outcome.md](references/expected-outcome.md)

package/dist/gen/skills/service-definition/references/00.assess-service.md

@@ -0,0 +1,69 @@
+# Phase 0: Assess Service Requirements
+
+Before writing any code, identify what the service needs.
+
+## Steps
+
+### 1. Identify the process
+
+What does this service run?
+
+- **Static command**: `'pnpm dev'` — always the same
+- **Parameterized command**: `(params) => \`pnpm dev -p ${params?.port ?? 3000}\`` — varies per invocation
+
+### 2. Determine readiness signals
+
+What does the process print to stdout/stderr when it's ready?
+
+- Copy the **exact line(s)** from the process output
+- Identify the regex that matches each line
+- Note any URLs, ports, or other values to capture from those lines
+- If the process prints multiple readiness signals (e.g., Connect Studio URL + Switchboard URL + MCP URL), each needs its own pattern — all must match
+
+### 3. Identify endpoints
+
+What endpoints does the service expose?
+
+- [ ] HTTP REST API → `type: 'api-rest'`
+- [ ] GraphQL API → `type: 'api-graphql'`
+- [ ] MCP server → `type: 'api-mcp'` (enables agent tool discovery)
+- [ ] Website/UI → `type: 'website'`
+- [ ] Other → `type: 'other'`
+
+For each endpoint, note which stdout line contains its URL and which regex group captures it.
+
+### 4. Identify preflight requirements
+
+What must be true before the process can start?
+
+- [ ] **Working directory**: Does it need specific files? (`package.json`, `powerhouse.config.ts`, etc.)
+- [ ] **Binaries**: Does it need installed tools? (`node`, `pnpm`, `ph`, `docker`, etc.)
+- [ ] **Ports**: What ports does it bind to? Are they configurable?
+
+### 5. Determine lifecycle policies
+
+- **Shutdown**: Which signal does the process respond to? (Most Node.js processes: SIGTERM)
+- **Restart on crash?** How many retries? What delay between attempts?
+- **Multiple instances?** Can several run simultaneously, or is it exclusive? (`maxInstances`)
+
+### 6. Determine runtime parameters
+
+Does the service need per-invocation parameters?
+
+- Ports, URLs, feature flags → define `paramsSchema` (Zod schema)
+- Parameters become flags on the auto-generated `{id}-start` command
+- Parameters are passed to both `command()` and `env()` functions
+
+### 7. Determine environment variables
+
+Does the process need environment variables derived from CLI config or params?
+
+- `env(config, params) => Record<string, string>`
+- Common: `PORT`, `NODE_ENV`, `HOST`, API URLs, feature flags
+
+### 8. Check for project scanning needs
+
+Does one service definition serve multiple project directories?
+
+- If yes → define `projectScanner` to enable `{id}-ls` command
+- Scanner needs `isProjectFolder(path)` predicate at minimum

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 },
+});
+```