@powerhousedao/ph-clint-cli 0.1.0-dev.6 → 0.1.0-dev.61

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 @@
+export { type ManifestEntry, type SkillsManifest, type SyncResult, type SyncOptions, readManifest, diffSkills, syncExternalSkills, } from '@powerhousedao/ph-clint-dev/skills/sync';

package/dist/skills/sync.js

@@ -0,0 +1 @@
+export { readManifest, diffSkills, syncExternalSkills, } from '@powerhousedao/ph-clint-dev/skills/sync';

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

package/dist/spec/types.js

@@ -1,112 +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';
-const powerhouseFeatureSchema = z.object({
-    enabled: z.boolean().default(false),
-    switchboard: z.boolean().default(true),
-    connect: z.boolean().default(true),
-});
-const mastraFeatureSchema = z.object({
-    enabled: z.boolean().default(false),
-});
-const routineFeatureSchema = z.object({
-    enabled: z.boolean().default(false),
-});
-// Zod 4 does not cascade `.default({})` through nested object schemas — a
-// missing outer key fills in `{}`, but nested keys with their own `.default`
-// are not re-defaulted unless the object itself re-parses. We spell out full
-// defaults here so `clintProjectSpecSchema.parse({ name: 'x' })` yields a
-// fully-populated feature tree.
-const DEFAULT_POWERHOUSE = {
-    enabled: false,
-    switchboard: true,
-    connect: true,
-};
-const DEFAULT_MASTRA = { enabled: false };
-const DEFAULT_ROUTINE = { enabled: false };
-export const clintProjectSpecSchema = z.object({
-    name: z
-        .string()
-        .regex(/^[a-z0-9][a-z0-9-]*$/, 'lowercase letters, digits, hyphens only'),
-    scope: z
-        .string()
-        .regex(/^[a-z0-9][a-z0-9-]*$/, 'lowercase letters, digits, hyphens only')
-        .optional(),
-    version: z.string().default('0.1.0'),
-    description: z.string().default(''),
-    bin: z.string().optional(),
-    features: z
-        .object({
-        powerhouse: powerhouseFeatureSchema.default(DEFAULT_POWERHOUSE),
-        mastra: mastraFeatureSchema.default(DEFAULT_MASTRA),
-        routine: routineFeatureSchema.default(DEFAULT_ROUTINE),
-    })
-        .default({
-        powerhouse: DEFAULT_POWERHOUSE,
-        mastra: DEFAULT_MASTRA,
-        routine: DEFAULT_ROUTINE,
-    }),
-    /**
-     * Document types registered with this CLI — full documentType ID strings
-     * (e.g. `powerhouse/ph-clint-project`). Drives codegen of `src/framework.gen.ts`,
-     * which emits a typed `defineRegistry([...] as const)` call so impl code
-     * gets narrowed `reactor.client.get(id, 'my-type')` access. Empty on
-     * fresh projects — populated as document models are added to the reactor
-     * package.
-     */
-    documentTypes: z.array(z.string()).default([]),
-});
-/** npm package name (e.g. `@scope/foo` or `foo`). */
-export function getPackageName(spec) {
-    return spec.scope ? `@${spec.scope}/${spec.name}` : spec.name;
-}
-/** bin name (defaults to the bare project name). */
-export function getBinName(spec) {
-    return spec.bin ?? spec.name;
-}
-/**
- * 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 function getCliFolderName(spec) {
-    return `${spec.name}-cli`;
-}
-/**
- * Name of the reactor-package sub-folder when the project is split.
- */
-export function getAppFolderName(spec) {
-    return `${spec.name}-app`;
-}
-/**
- * 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 function getDocumentTypeSlug(documentType) {
-    const lastSlash = documentType.lastIndexOf('/');
-    return lastSlash >= 0 ? documentType.slice(lastSlash + 1) : documentType;
-}
-/**
- * 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 function getDocumentTypeModuleName(documentType) {
-    const slug = getDocumentTypeSlug(documentType);
-    return slug
-        .split(/[-_]/)
-        .filter((s) => s.length > 0)
-        .map((s) => s[0].toUpperCase() + s.slice(1))
-        .join('');
-}
+export { POWERHOUSE_LEVELS, powerhouseLevelSchema, phAtLeast, agentModelSchema, agentProfileSchema, powerhousePackageSchema, externalSkillSchema, clintProjectSpecSchema, getPackageName, getBinName, getCliFolderName, getAppFolderName, getAllDocumentTypes, getAppPackageName, getAppDirName, getDocumentTypeSlug, getDocumentTypeModuleName, isDocTypeGlob, docTypeGlobToRegex, } from '@powerhousedao/ph-clint-dev/spec';

package/dist/triggers/publish-trigger.d.ts

@@ -0,0 +1,10 @@
+/** Map document model PublishTag values to CLI --tag values. */
+export declare function tagToCli(tag: string): 'dev' | 'staging' | 'production' | null;
+export declare const publishTrigger: import("@powerhousedao/ph-clint").Trigger<{
+    pending: number;
+}, {
+    model: string;
+    devServicePort: number;
+    phVersion: string;
+    apiKey?: string | undefined;
+}, import("@powerhousedao/ph-clint").InferRegistry<readonly [import("document-model").DocumentModelModule<import("@powerhousedao/ph-clint-app").PhClintProjectPHState>]>>;

package/dist/triggers/publish-trigger.js

@@ -0,0 +1,133 @@
+/**
+ * `publish-trigger` — watches ALL `powerhouse/ph-clint-project` documents for
+ * publish records with `Pending` status and invokes the publish pipeline.
+ *
+ * Unlike `spec-change`, this trigger does NOT convert to a `ClintProjectSpec`.
+ * It reads `publishHistory` directly from the document state, since publish
+ * records are a doc-model concern (not a codegen input).
+ *
+ * Uses the multi-doc path (no `documentId`), scanning all matching documents
+ * on each poll. For each document with a pending publish record, it uses the
+ * project mapping to resolve the on-disk project directory.
+ *
+ * Flow:
+ *   1. On document change, scans `publishHistory` for records with status
+ *      `"Pending"`.
+ *   2. For each pending record, returns a work item that:
+ *      a. Dispatches SET_PUBLISH_STATUS({ id, status: "InProgress" }).
+ *      b. Runs `ph-clint clint-project-publish --tag <tag>`.
+ *      c. Dispatches SET_PUBLISH_STATUS({ id, status: "Succeeded"|"Failed" }).
+ */
+import path from 'node:path';
+import { scanProjects, getProjectMapping } from '@powerhousedao/ph-clint';
+import { setPublishStatus } from '@powerhousedao/ph-clint-app';
+import { createDocumentChangeTrigger } from '../framework.js';
+import { specFromDocumentState } from '../spec/from-document.js';
+import { clintProject } from '../services/clint-project.js';
+const DOCUMENT_TYPE = 'powerhouse/ph-clint-project';
+const TAG = '[publish]';
+/** Map document model PublishTag values to CLI --tag values. */
+export function tagToCli(tag) {
+    switch (tag) {
+        case 'Dev':
+            return 'dev';
+        case 'Staging':
+            return 'staging';
+        case 'Production':
+            return 'production';
+        default:
+            return null;
+    }
+}
+export const publishTrigger = createDocumentChangeTrigger({
+    id: 'publish-trigger',
+    documentType: DOCUMENT_TYPE,
+    // No documentId → watches ALL ph-clint-project docs
+    // Don't fire on startup — only react to new pending records.
+    initialReconcile: false,
+    async onChange(docs, ctx) {
+        const log = ctx.context.log;
+        const folders = ctx.context.folders;
+        // Build the mapping to resolve on-disk project directories
+        const scanner = clintProject.projectScanner;
+        const scanResults = scanner
+            ? scanProjects(ctx.context.workdir, scanner)
+            : [];
+        const mapping = await getProjectMapping(scanResults, folders);
+        for (const doc of docs) {
+            const publishHistory = doc.state.global.publishHistory ?? [];
+            const pending = publishHistory.filter((r) => r.status === 'Pending');
+            if (pending.length === 0)
+                continue;
+            // Resolve the on-disk target directory for this document
+            const spec = specFromDocumentState(doc.state.global, {
+                documentId: doc.header.id,
+                documentType: doc.header.documentType,
+            });
+            const entry = mapping.find((m) => m.documentId === doc.header.id);
+            const workdir = entry?.path
+                ?? (spec ? path.join(ctx.context.workdir, spec.name) : ctx.context.workdir);
+            // Process the first pending record (one per tick to avoid races).
+            const record = pending[0];
+            const cliTag = tagToCli(record.tag);
+            if (!cliTag) {
+                log?.warn(`${TAG} unknown publish tag "${record.tag}" for record ${record.id}`);
+                continue;
+            }
+            log?.info(`${TAG} found pending ${record.tag} publish for doc ${doc.header.id} (id=${record.id}, version=${record.version})`);
+            const { runProcess, stdout } = ctx.context;
+            return {
+                type: 'function',
+                params: {
+                    fn: async () => {
+                        const reactor = await ctx.reactor();
+                        if (!reactor) {
+                            log?.error(`${TAG} reactor not available, cannot update publish status`);
+                            return;
+                        }
+                        // Mark as InProgress.
+                        log?.info(`${TAG} marking record ${record.id} as InProgress`);
+                        await reactor.client.execute(doc.header.id, 'main', [
+                            setPublishStatus({ id: record.id, status: 'InProgress' }),
+                        ]);
+                        // Install dependencies in the generated project before publishing.
+                        stdout(`${TAG} running pnpm install in ${workdir}\n`);
+                        const installResult = await runProcess('pnpm install', {
+                            cwd: workdir,
+                            timeout: 300_000,
+                        });
+                        if (!installResult.success) {
+                            log?.error(`${TAG} pnpm install failed in ${workdir}`);
+                        }
+                        // Run the publish command.
+                        let success = false;
+                        try {
+                            stdout(`${TAG} invoking clint-project-publish --tag ${cliTag}\n`);
+                            const { clintProjectPublish } = await import('../commands/clint-project-publish.js');
+                            const result = await clintProjectPublish.execute({ tag: cliTag, dir: workdir, dryRun: false, skipBuild: false, skipGitCheck: true, verbose: false }, ctx.commandContext);
+                            success = !result.text.includes('failed');
+                        }
+                        catch (err) {
+                            log?.error(`${TAG} publish failed: ${err instanceof Error ? err.message : String(err)}`);
+                        }
+                        // Update status.
+                        const finalStatus = success ? 'Succeeded' : 'Failed';
+                        stdout(`${TAG} marking record ${record.id} as ${finalStatus}\n`);
+                        await reactor.client.execute(doc.header.id, 'main', [
+                            setPublishStatus({
+                                id: record.id,
+                                status: finalStatus,
+                            }),
+                        ]);
+                    },
+                },
+                callbacks: {
+                    onFailure: (err) => {
+                        log?.error(`${TAG} publish trigger failed: ${err.message}`);
+                    },
+                },
+            };
+        }
+        return null;
+    },
+});