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

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/package.json

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