@powerhousedao/ph-clint-cli 0.1.0-dev.0

package/dist/framework.gen.js

@@ -0,0 +1,16 @@
+/**
+ * THIS FILE IS GENERATED BY ph-clint-cli. DO NOT EDIT.
+ *
+ * Regenerated on every `ph-clint regen` and on every spec-change tick.
+ * Put custom bindings in `framework.ts`, not here — edits to this file
+ * will be overwritten.
+ */
+import { defineRegistry } from '@powerhousedao/ph-clint';
+import { PhClintProject } from '@powerhousedao/ph-clint-app';
+/**
+ * Typed document registry derived from the reactor package's document models.
+ * Regenerated whenever the spec's `documentTypes` list changes.
+ */
+export const registry = defineRegistry([
+    PhClintProject,
+]);

package/dist/framework.js

@@ -0,0 +1,41 @@
+/**
+ * Per-CLI typed framework binding.
+ *
+ * This file is USER-OWNED. ph-clint-cli emits it once at project creation
+ * and never overwrites it afterwards — edit `configSchema` and
+ * `secretsSchema` freely.
+ *
+ * Typed factories (`defineCommand`, `defineTrigger`, ...) and the document
+ * `registry` come from `framework.gen.ts`, which IS regenerated whenever
+ * the spec's `documentTypes` list changes.
+ */
+import { z } from 'zod';
+import { createTypes } from '@powerhousedao/ph-clint';
+import { registry } from './framework.gen.js';
+export const configSchema = z.object({
+    model: z
+        .string()
+        .default('anthropic/claude-haiku-4-5')
+        .describe('LLM model to use'),
+    devServicePort: z
+        .number()
+        .default(3000)
+        .describe('Port reserved for the impl project (Service B) `pnpm dev`'),
+    phVersion: z
+        .string()
+        .default('6.0.0-dev.170')
+        .describe('Pinned Powerhouse version used when emitting a new impl project'),
+    projectDocumentId: z
+        .string()
+        .optional()
+        .describe('ID of the powerhouse/ph-clint-project document that drives codegen (set on first regen; edit to switch projects)'),
+});
+export const secretsSchema = z.object({
+    apiKey: z.string().optional().describe('Anthropic API key'),
+});
+const fullConfigSchema = configSchema.merge(secretsSchema);
+export const { defineCommand, defineTrigger, defineService, createDocumentChangeTrigger, } = createTypes({
+    configSchema: fullConfigSchema,
+    registry,
+});
+export { registry } from './framework.gen.js';

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/main.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { cli } from './cli.js';
+cli.run(process.argv);

package/dist/mastra/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Mastra Studio entry point for `mastra dev` / `mastra build` / `mastra start`.
+ *
+ * Populated by codegen when `features.mastra.enabled`. Until then this file
+ * exports nothing — the `mastra:*` scripts will fail gracefully if invoked
+ * with Mastra disabled.
+ *
+ * See examples/05-ph-rupert/src/mastra/index.ts for the enabled form.
+ */
+export {};

package/dist/mastra/index.js

@@ -0,0 +1,11 @@
+/**
+ * Mastra Studio entry point for `mastra dev` / `mastra build` / `mastra start`.
+ *
+ * Populated by codegen when `features.mastra.enabled`. Until then this file
+ * exports nothing — the `mastra:*` scripts will fail gracefully if invoked
+ * with Mastra disabled.
+ *
+ * See examples/05-ph-rupert/src/mastra/index.ts for the enabled form.
+ */
+export {};
+// @clint:end mastra-index

package/dist/spec/file.d.ts

@@ -0,0 +1,4 @@
+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>;

package/dist/spec/file.js

@@ -0,0 +1,34 @@
+/**
+ * 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');
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Convert a `powerhouse/ph-clint-project` document's global state into a
+ * `ClintProjectSpec` that the code generator consumes.
+ *
+ * The document state is deliberately more permissive than the codegen spec:
+ * `name` is nullable in the state (so empty documents are creatable), but the
+ * generator requires a valid package name. Callers handle the `null` result
+ * (typically by skipping the regen until the user sets a name).
+ */
+import type { PhClintProjectGlobalState } from '@powerhousedao/ph-clint-app/document-models/ph-clint-project';
+import { type ClintProjectSpec } from './types.js';
+/**
+ * Build a `ClintProjectSpec` from the document state.
+ *
+ * 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;

package/dist/spec/from-document.js

@@ -0,0 +1,30 @@
+import { clintProjectSpecSchema, } from './types.js';
+/**
+ * Build a `ClintProjectSpec` from the document state.
+ *
+ * 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) {
+    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,
+        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 } : {}),
+    });
+    return parsed.success ? parsed.data : null;
+}

package/dist/spec/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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;

package/dist/spec/types.js

@@ -0,0 +1,112 @@
+/**
+ * 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('');
+}

package/dist/triggers/spec-change.d.ts

@@ -0,0 +1,43 @@
+import type { ClintProjectSpec } from '../spec/types.js';
+/** Stable hash of a ClintProjectSpec (sha256 of canonical-key JSON). */
+export declare function hashSpec(spec: ClintProjectSpec): string;
+export declare const specChangeTrigger: import("@powerhousedao/ph-clint").Trigger<{
+    pending: number;
+}, {
+    model: string;
+    devServicePort: number;
+    phVersion: string;
+    projectDocumentId?: string | undefined;
+    apiKey?: string | undefined;
+}, import("@powerhousedao/ph-clint").InferRegistry<readonly [{
+    readonly version: 1;
+    readonly reducer: import("document-model").Reducer<import("@powerhousedao/ph-clint-app").PhClintProjectPHState>;
+    readonly actions: {
+        enableRoutine: (input: import("@powerhousedao/ph-clint-app").EnableRoutineInput) => import("@powerhousedao/ph-clint-app").EnableRoutineAction;
+        disableRoutine: (input: import("@powerhousedao/ph-clint-app").DisableRoutineInput) => import("@powerhousedao/ph-clint-app").DisableRoutineAction;
+        enableMastra: (input: import("@powerhousedao/ph-clint-app").EnableMastraInput) => import("@powerhousedao/ph-clint-app").EnableMastraAction;
+        disableMastra: (input: import("@powerhousedao/ph-clint-app").DisableMastraInput) => import("@powerhousedao/ph-clint-app").DisableMastraAction;
+        enablePowerhouse: (input: import("@powerhousedao/ph-clint-app").EnablePowerhouseInput) => import("@powerhousedao/ph-clint-app").EnablePowerhouseAction;
+        setPowerhouseSwitchboard: (input: import("@powerhousedao/ph-clint-app").SetPowerhouseSwitchboardInput) => import("@powerhousedao/ph-clint-app").SetPowerhouseSwitchboardAction;
+        setPowerhouseConnect: (input: import("@powerhousedao/ph-clint-app").SetPowerhouseConnectInput) => import("@powerhousedao/ph-clint-app").SetPowerhouseConnectAction;
+        setPackageName: (input: import("@powerhousedao/ph-clint-app").SetPackageNameInput) => import("@powerhousedao/ph-clint-app").SetPackageNameAction;
+        clearBin: (input: import("@powerhousedao/ph-clint-app").ClearBinInput) => import("@powerhousedao/ph-clint-app").ClearBinAction;
+        setBin: (input: import("@powerhousedao/ph-clint-app").SetBinInput) => import("@powerhousedao/ph-clint-app").SetBinAction;
+        setDescription: (input: import("@powerhousedao/ph-clint-app").SetDescriptionInput) => import("@powerhousedao/ph-clint-app").SetDescriptionAction;
+        setVersion: (input: import("@powerhousedao/ph-clint-app").SetVersionInput) => import("@powerhousedao/ph-clint-app").SetVersionAction;
+        clearScope: (input: import("@powerhousedao/ph-clint-app").ClearScopeInput) => import("@powerhousedao/ph-clint-app").ClearScopeAction;
+        setScope: (input: import("@powerhousedao/ph-clint-app").SetScopeInput) => import("@powerhousedao/ph-clint-app").SetScopeAction;
+        setName: (name: string | {
+            name: string;
+        }) => import("document-model").SetNameAction;
+        undo: (count?: number, scope?: string) => import("document-model").UndoAction;
+        redo: (count?: number, scope?: string) => import("document-model").RedoAction;
+        prune: (start?: number, end?: number, scope?: string) => import("document-model").SchemaPruneAction;
+        loadState: <TState extends import("document-model").PHBaseState = import("document-model").PHBaseState>(state: TState & {
+            name: string;
+        }, operations: number) => import("document-model").LoadStateAction;
+        noop: (scope?: string) => import("document-model").NOOPAction;
+    };
+    readonly utils: import("document-model").DocumentModelUtils<import("@powerhousedao/ph-clint-app").PhClintProjectPHState>;
+    readonly documentModel: import("document-model").DocumentModelPHState;
+}]>>;

package/dist/triggers/spec-change.js

@@ -0,0 +1,171 @@
+/**
+ * `spec-change` trigger — watches the `powerhouse/ph-clint-project` document
+ * on the Reactor drive and, when its state changes, enqueues a work item
+ * that re-runs the code generator in update mode.
+ *
+ * Flow:
+ *   1. `createDocumentChangeTrigger` (from ph-clint) owns the subscription,
+ *      event coalescing, doc loading, and type narrowing.
+ *   2. `documentId` resolves the target doc lazily: it prefers
+ *      `config.projectDocumentId`, falling back to a drive scan for the first
+ *      `powerhouse/ph-clint-project` document (and pinning the id into local
+ *      config on success).
+ *   3. `onChange` converts the doc state to a `ClintProjectSpec`, hashes it,
+ *      and compares against `.ph/ph-clint-cli/.last-spec-hash`. If unchanged,
+ *      emits nothing. If different, returns a `function` work item that calls
+ *      `generateProject(spec, workdir, 'update')` and writes the new hash.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createDocumentChangeTrigger } from '../framework.js';
+import { generateProject } from '../codegen/index.js';
+import { specFromDocumentState } from '../spec/from-document.js';
+const DOCUMENT_TYPE = 'powerhouse/ph-clint-project';
+const HASH_DIR = path.join('.ph', 'ph-clint-cli');
+const HASH_FILE = '.last-spec-hash';
+const TAG = '[spec-change]';
+function getHashPath(targetDir) {
+    return path.join(targetDir, HASH_DIR, HASH_FILE);
+}
+function isEnoent(err) {
+    return (!!err &&
+        typeof err === 'object' &&
+        'code' in err &&
+        err.code === 'ENOENT');
+}
+async function readLastSpecHash(targetDir) {
+    try {
+        return (await fs.readFile(getHashPath(targetDir), 'utf8')).trim() || null;
+    }
+    catch (err) {
+        if (isEnoent(err))
+            return null;
+        throw err;
+    }
+}
+async function writeLastSpecHash(targetDir, hash) {
+    const file = getHashPath(targetDir);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, hash + '\n', 'utf8');
+}
+/** Stable hash of a ClintProjectSpec (sha256 of canonical-key JSON). */
+export function hashSpec(spec) {
+    return crypto
+        .createHash('sha256')
+        .update(canonicalJson(spec), 'utf8')
+        .digest('hex');
+}
+function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return '[' + value.map(canonicalJson).join(',') + ']';
+    }
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return ('{' +
+        keys
+            .map((k) => JSON.stringify(k) + ':' + canonicalJson(obj[k]))
+            .join(',') +
+        '}');
+}
+/** Find the first ph-clint-project document on the default drive. */
+async function findProjectDocumentId(client, driveId) {
+    try {
+        const children = await client.getChildren(driveId);
+        const results = (children?.results ?? []);
+        for (const node of results) {
+            if (node.header?.documentType === DOCUMENT_TYPE && node.header.id) {
+                return node.header.id;
+            }
+        }
+    }
+    catch {
+        // fall through
+    }
+    return undefined;
+}
+export const specChangeTrigger = createDocumentChangeTrigger({
+    id: 'spec-change',
+    documentType: DOCUMENT_TYPE,
+    // Resolve the target id lazily so we can also do first-time discovery and
+    // persist the discovered id into local config.
+    documentId: async (ctx) => {
+        const configured = ctx.context.config.projectDocumentId &&
+            ctx.context.config.projectDocumentId.length > 0
+            ? ctx.context.config.projectDocumentId
+            : undefined;
+        if (configured)
+            return configured;
+        const reactor = await ctx.reactor();
+        if (!reactor)
+            return undefined;
+        const discovered = await findProjectDocumentId(reactor.client, reactor.driveId);
+        if (!discovered) {
+            ctx.context.log?.debug(`${TAG} no ${DOCUMENT_TYPE} document found on drive ${reactor.driveId}`);
+            return undefined;
+        }
+        // Persist into local config + mutate in-memory so future ticks skip discovery.
+        try {
+            const current = await ctx.context.workspace.loadLocalConfig({});
+            await ctx.context.workspace.storeLocalConfig({
+                ...current,
+                projectDocumentId: discovered,
+            });
+            ctx.context.config.projectDocumentId = discovered;
+            ctx.context.log?.info(`${TAG} pinned projectDocumentId=${discovered} in ${ctx.context.workspace.getLocalConfigPath()}`);
+        }
+        catch (err) {
+            ctx.context.log?.warn(`${TAG} failed to persist projectDocumentId: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return discovered;
+    },
+    async onChange(doc, ctx) {
+        const log = ctx.context.log;
+        const spec = specFromDocumentState(doc.state.global);
+        if (!spec) {
+            log?.debug(`${TAG} document ${doc.header.id} state did not validate against ClintProjectSpec, skipping`);
+            return null;
+        }
+        const targetDir = ctx.context.workdir;
+        const nextHash = hashSpec(spec);
+        const prevHash = await readLastSpecHash(targetDir);
+        if (nextHash === prevHash) {
+            log?.debug(`${TAG} spec unchanged (hash=${nextHash.slice(0, 12)}…), nothing to do`);
+            return null;
+        }
+        log?.debug(`${TAG} spec changed: ${prevHash ? prevHash.slice(0, 12) + '…' : '<none>'} → ${nextHash.slice(0, 12)}…`);
+        return {
+            type: 'function',
+            params: {
+                fn: async () => {
+                    log?.info(`${TAG} regenerating project at ${targetDir} (doc=${doc.header.id})`);
+                    const t0 = Date.now();
+                    const warnings = [];
+                    const result = await generateProject({
+                        targetDir,
+                        spec,
+                        mode: 'update',
+                        onWarn: (m) => warnings.push(m),
+                    });
+                    await writeLastSpecHash(targetDir, nextHash);
+                    const elapsed = Date.now() - t0;
+                    if (log) {
+                        if (result.migrated)
+                            log.info(`${TAG} migrated flat → split layout`);
+                        log.info(`${TAG} regenerated in ${elapsed}ms: ${result.files.length} written, ${result.skipped.length} skipped, ${result.deleted.length} deleted`);
+                        for (const w of warnings)
+                            log.warn(`${TAG} ${w}`);
+                    }
+                },
+            },
+            callbacks: {
+                onFailure: (err) => {
+                    log?.error(`${TAG} regen failed: ${err.message}`);
+                    log?.debug(`${TAG} stack: ${err.stack ?? '<no stack>'}`);
+                },
+            },
+        };
+    },
+});

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@powerhousedao/ph-clint-cli",
+  "version": "0.1.0-dev.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "ph-clint CLI — scaffolds and maintains ph-clint implementation projects. Itself built with ph-clint from the ph-clint-tpl template.",
+  "type": "module",
+  "bin": {
+    "ph-clint": "./dist/main.js"
+  },
+  "files": [
+    "dist",
+    "prompts"
+  ],
+  "scripts": {
+    "build:skills": "tsx scripts/build-skills.ts",
+    "build": "pnpm build:skills && tsc",
+    "dev": "tsx src/main.ts",
+    "start": "node dist/main.js",
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest --detectOpenHandles",
+    "lint": "eslint src",
+    "mastra:dev": "mastra dev",
+    "mastra:build": "mastra build",
+    "mastra:start": "mastra start",
+    "publish:npm": "pnpm build && pnpm publish --no-git-checks"
+  },
+  "dependencies": {
+    "@powerhousedao/ph-clint": "^0.1.0-dev.0",
+    "@powerhousedao/ph-clint-app": "^0.1.0-dev.0",
+    "@mastra/core": "^1.22.0",
+    "@mastra/libsql": "^1.7.4",
+    "@mastra/memory": "^1.13.1",
+    "@powerhousedao/reactor": "6.0.0-dev.170",
+    "@powerhousedao/reactor-api": "6.0.0-dev.170",
+    "@powerhousedao/shared": "6.0.0-dev.170",
+    "@electric-sql/pglite": "0.3.15",
+    "document-model": "6.0.0-dev.170",
+    "kysely": "^0.27.0",
+    "kysely-pglite-dialect": "^1.3.0",
+    "zod": "^4.3.6"
+  },
+  "pnpm": {
+    "overrides": {
+      "mastra>@mastra/deployer": "1.22.0"
+    }
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.2.0",
+    "@types/node": "^25.5.2",
+    "jest": "^30.2.0",
+    "@powerhousedao/ph-clint-dev": "^0.1.0-dev.0",
+    "ts-jest": "^29.4.6",
+    "tsx": "^4.19.0",
+    "typescript": "^6.0.2"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  }
+}

package/prompts/agent-profiles/AgentBase.md

@@ -0,0 +1,13 @@
+# Agent Base System Prompt
+
+You are {{agentName}}, an agent available through the {{cliName}} CLI.
+
+## Capabilities
+
+This base profile is a minimal placeholder. Extend it with project-specific
+context, workflows, and domain knowledge. Additional sections listed in the
+agent's `sections` array are concatenated after this file at build time.
+
+See `examples/05-ph-rupert/prompts/agent-profiles/AgentBase.md` for a more
+complete example covering Powerhouse document system fundamentals,
+collaboration documents (inbox, WBS), and task management guidelines.