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

package/dist/cli.js

@@ -6,7 +6,9 @@
  * rewritten by ph-clint-cli's generator when the project spec changes.
  * Everything outside the markers is user-editable and preserved.
  */
+import path from 'node:path';
 import { defineCli, buildDefaultReactor } from '@powerhousedao/ph-clint';
+import { z } from 'zod';
 import { CLI_NAME, CLI_VERSION, CLI_ROOT } from './config.js';
 import { configSchema, secretsSchema } from './framework.js';
 // @clint:begin imports
@@ -39,9 +41,26 @@ export const cli = defineCli({
     // @clint:end triggers
     // @clint:begin prompts
     prompts: {
-        artifacts: [],
-        agents: {},
-        skills: {},
+        artifacts: [path.join(CLI_ROOT, 'gen', 'skills'), path.join(CLI_ROOT, 'dist', 'gen', 'skills')],
+        agents: {
+            'ph-clint-dev-agent': {
+                name: 'PhClintDevAgent',
+                sections: ['AgentBase.md'],
+                skills: ['command-definition'],
+            },
+        },
+        skills: {
+            'command-definition': {
+                description: 'Define commands with Zod schemas, execute functions, return values, and parameter prompting',
+                inputSchema: z.object({
+                    mode: z
+                        .enum(['expert', 'discovery', 'one-shot'])
+                        .default('expert')
+                        .describe('Expert: align design decisions with the developer. Discovery: explain concepts step by step. One-shot: make all decisions autonomously'),
+                }),
+                instructionTemplate: 'Use your {{skillId}} skill in {{mode}} mode for: {{prompt}}',
+            },
+        },
     },
     // @clint:end prompts
     // @clint:begin events

package/dist/codegen/builders/agent-ts.js

@@ -51,9 +51,9 @@ function buildRealAgent(spec) {
     const agentName = mastra.agentName;
     const defaultModel = mastra.models.find(m => m.isDefault) ?? mastra.models[0];
     const modelId = defaultModel?.id ?? 'anthropic/claude-sonnet-4-5';
-    const [provider] = modelId.split('/');
+    const [provider] = modelId.split(/[:/]/);
     const { pkg, fn } = providerImport(provider);
-    const envKey = `${provider.toUpperCase()}_API_KEY`;
+    const apiKeyField = `${provider}ApiKey`;
     const lines = [];
     lines.push("import { Agent } from '@mastra/core/agent';");
     lines.push("import { MCPClient } from '@mastra/mcp';");
@@ -72,7 +72,7 @@ function buildRealAgent(spec) {
     lines.push(' * agent as a ph-clint AgentProvider.');
     lines.push(' */');
     lines.push('export async function createAgent(ctx: AgentSetupContext<Config>): Promise<AgentProvider> {');
-    lines.push(`  if (!ctx.config.apiKey) return createDemoAgent();`);
+    lines.push(`  if (!ctx.config.${apiKeyField}) return createDemoAgent();`);
     lines.push('');
     lines.push('  const m = createMastraHelpers(ctx);');
     lines.push('');
@@ -80,9 +80,9 @@ function buildRealAgent(spec) {
     lines.push(`    id: '${agentId}',`);
     lines.push(`    name: '${agentName}',`);
     lines.push(`    instructions: m.getAgentInstructions('${agentId}'),`);
-    lines.push('    model: ctx.config.apiKey');
-    lines.push("      ? { id: ctx.config.model as `${string}/${string}`, apiKey: ctx.config.apiKey }");
-    lines.push("      : (ctx.config.model as `${string}/${string}`),");
+    lines.push(`    model: ctx.config.${apiKeyField}`);
+    lines.push(`      ? { id: ctx.config.model as \`\${string}/\${string}\`, apiKey: ctx.config.${apiKeyField} }`);
+    lines.push(`      : (ctx.config.model as \`\${string}/\${string}\`),`);
     lines.push('    tools: async () => {');
     lines.push("      ctx.context.log?.debug('[agent] tools callback invoked');");
     lines.push('      const tools = await m.getTools({ MCPClient });');

package/dist/codegen/builders/cli-package-json.js

@@ -52,6 +52,7 @@ export function buildCliPackageJson(spec) {
     if (mastra.enabled) {
         dependencies['@mastra/core'] = '^1.22.0';
         dependencies['@mastra/libsql'] = '^1.7.4';
+        dependencies['@mastra/mcp'] = '^1.4.1';
         dependencies['@mastra/memory'] = '^1.13.1';
     }
     if (phAtLeast(powerhouse, 'Reactor')) {

package/dist/codegen/builders/cli-ts.js

@@ -15,16 +15,19 @@ export function buildCliTs(spec) {
     lines.push(' * markers are rewritten by ph-clint when the project spec changes.');
     lines.push(' * Everything outside the markers is user-editable and preserved.');
     lines.push(' */');
+    const needsRoot = phAtLeast(ph, 'Reactor') || mastra.enabled;
+    lines.push('// @clint:begin imports');
     if (phAtLeast(ph, 'Reactor')) {
         lines.push(`import { defineCli, buildDefaultReactor } from '@powerhousedao/ph-clint';`);
     }
     else {
         lines.push(`import { defineCli } from '@powerhousedao/ph-clint';`);
     }
-    lines.push(`import { CLI_NAME, CLI_VERSION${phAtLeast(ph, 'Reactor') ? ', CLI_ROOT' : ''} } from './config.js';`);
+    if (needsRoot) {
+        lines.push("import path from 'node:path';");
+    }
+    lines.push(`import { CLI_NAME, CLI_VERSION${needsRoot ? ', CLI_ROOT' : ''} } from './config.js';`);
     lines.push(`import { configSchema, secretsSchema } from './framework.js';`);
-    lines.push('');
-    lines.push('// @clint:begin imports');
     if (phAtLeast(ph, 'Reactor')) {
         lines.push(`import { documentModels } from '${getAppPackageName(spec)}';`);
     }
@@ -62,15 +65,28 @@ export function buildCliTs(spec) {
     lines.push('');
     lines.push('  // @clint:begin prompts');
     lines.push('  prompts: {');
-    lines.push('    artifacts: [],');
-    if (mastra.enabled && mastra.agentId && mastra.profiles.length > 0) {
+    if (mastra.enabled) {
+        lines.push("    artifacts: [path.join(CLI_ROOT, 'gen', 'skills'), path.join(CLI_ROOT, 'dist', 'gen', 'skills')],");
+    }
+    else {
+        lines.push('    artifacts: [],');
+    }
+    if (mastra.enabled && mastra.agentId) {
         lines.push('    agents: {');
         lines.push(`      '${mastra.agentId}': {`);
-        lines.push('        sections: [');
-        for (const p of mastra.profiles) {
-            lines.push(`          { id: '${p.id}', title: '${p.title}', file: '${p.id}.md' },`);
+        if (mastra.profiles.length > 0) {
+            lines.push(`        name: '${mastra.profiles[0].id}',`);
+            lines.push('        sections: [');
+            for (const p of mastra.profiles) {
+                lines.push(`          '${p.id}.md',`);
+            }
+            lines.push('        ],');
+        }
+        else {
+            lines.push("        name: 'AgentBase',");
+            lines.push("        sections: ['AgentBase.md'],");
         }
-        lines.push('        ],');
+        lines.push('        skills: [],');
         lines.push('      },');
         lines.push('    },');
     }

package/dist/codegen/builders/demo-agent-ts.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Builds `src/agents/demo-agent.ts` — a deterministic echo agent fallback.
+ *
+ * Generated when `features.mastra.enabled` with full agent config so the real
+ * agent factory can fall back to demo mode when no API key is configured.
+ */
+import { type ClintProjectSpec } from '../../spec/types.js';
+export declare function buildDemoAgentTs(spec: ClintProjectSpec): string | null;

package/dist/codegen/builders/demo-agent-ts.js

@@ -0,0 +1,44 @@
+export function buildDemoAgentTs(spec) {
+    const { mastra } = spec.features;
+    // Only needed alongside the real agent (which imports it)
+    if (!mastra.enabled || !mastra.agentId || mastra.models.length === 0)
+        return null;
+    const agentId = mastra.agentId;
+    return [
+        "import type { AgentProvider, StreamChunk } from '@powerhousedao/ph-clint';",
+        '',
+        '/**',
+        ' * Demo agent — deterministic echo responses without an API key.',
+        ' *',
+        ' * Echoes user prompts with conversation tracking per thread.',
+        ' */',
+        'export function createDemoAgent(): AgentProvider {',
+        '  const conversations = new Map<string, string[]>();',
+        '',
+        '  return {',
+        `    id: '${agentId}',`,
+        '    async *stream(prompt, opts) {',
+        "      const threadId = opts?.threadId ?? 'default';",
+        '      if (!conversations.has(threadId)) {',
+        '        conversations.set(threadId, []);',
+        '      }',
+        '      const history = conversations.get(threadId)!;',
+        '      history.push(prompt);',
+        '',
+        '      const turnCount = history.length;',
+        '      if (turnCount > 1) {',
+        '        yield {',
+        "          type: 'text-delta',",
+        '          text: `I understand you\'re continuing our conversation (turn ${turnCount}). `,',
+        '        } satisfies StreamChunk;',
+        '      }',
+        '      yield {',
+        "        type: 'text-delta',",
+        '        text: `You said: "${prompt}". I\'m the demo agent — set an API key for real LLM responses.`,',
+        '      } satisfies StreamChunk;',
+        '    },',
+        '  };',
+        '}',
+        '',
+    ].join('\n');
+}

package/dist/codegen/builders/framework-ts.js

@@ -42,25 +42,30 @@ export function buildFrameworkTs(spec) {
     }
     lines.push('');
     lines.push('export const configSchema = z.object({');
+    lines.push('  // @clint:begin framework-config');
     if (mastra.enabled) {
         const defaultModel = mastra.models.find(m => m.isDefault)?.id ?? 'anthropic/claude-sonnet-4-5';
-        lines.push(`  model: z.string().default('${defaultModel}').describe('LLM model to use'),`);
+        lines.push(`  model: z.string().default('${defaultModel}').describe('LLM model to use'),`, `  agentLogging: z.boolean().default(false).describe('Enable agent conversation logging'),`);
     }
-    // Ports are derived from CLI name by resolveReactorDefaults() — no config fields needed.
-    // Override via switchboard.port / connect.port in configureReactor() if required.
-    lines.push('  // Add your own config fields here — this file survives regens.');
+    lines.push('  // @clint:end framework-config');
     lines.push('});');
     lines.push('');
     lines.push('export const secretsSchema = z.object({');
+    lines.push('  // @clint:begin framework-secrets');
     if (mastra.enabled) {
-        lines.push("  apiKey: z.string().optional().describe('LLM API key'),");
+        const providers = [...new Set(mastra.models.map(m => m.id.split(/[:/]/)[0]))];
+        for (const provider of providers) {
+            const field = `${provider}ApiKey`;
+            lines.push(`  ${field}: z.string().optional().describe('${provider} API key'),`);
+        }
     }
+    lines.push('  // @clint:end framework-secrets');
     lines.push('});');
     lines.push('');
     lines.push('export type Config = z.infer<typeof configSchema> &');
     lines.push('  z.infer<typeof secretsSchema>;');
     lines.push('');
-    lines.push('const fullConfigSchema = configSchema.merge(secretsSchema);');
+    lines.push('const fullConfigSchema = configSchema.extend(secretsSchema.shape);');
     lines.push('');
     if (hasGen) {
         lines.push('export const {');

package/dist/codegen/builders/index.d.ts

@@ -17,6 +17,7 @@ import { buildMastraIndexTs } from './mastra-index-ts.js';
 import { buildBuildSkillsScript } from './build-skills-ts.js';
 import { buildAgentBaseMd } from './agent-base-md.js';
 import { buildAgentTs } from './agent-ts.js';
+import { buildDemoAgentTs } from './demo-agent-ts.js';
 import { buildFrameworkGenTs } from './framework-gen-ts.js';
 import { buildFrameworkTs } from './framework-ts.js';
 import { type ClintProjectSpec } from '../../spec/types.js';
@@ -42,7 +43,7 @@ export interface FileBuilder {
  */
 export declare function getProfileFileBuilders(spec: ClintProjectSpec): FileBuilder[];
 export declare const CLI_FILE_BUILDERS: FileBuilder[];
-export { buildCliPackageJson, buildCliTs, buildConfigTs, buildMainTs, buildTsconfigJson, buildJestConfigJs, buildEslintConfigJs, buildGitignore, buildMastraIndexTs, buildBuildSkillsScript, buildAgentBaseMd, buildAgentTs, buildFrameworkGenTs, buildFrameworkTs, };
+export { buildCliPackageJson, buildCliTs, buildConfigTs, buildMainTs, buildTsconfigJson, buildJestConfigJs, buildEslintConfigJs, buildGitignore, buildMastraIndexTs, buildBuildSkillsScript, buildAgentBaseMd, buildAgentTs, buildDemoAgentTs, buildFrameworkGenTs, buildFrameworkTs, };
 export { buildRootPackageJson } from './root-package-json.js';
 export { buildPublishConfigTs } from './publish-config-ts.js';
 export { buildReadme } from './readme-md.js';

package/dist/codegen/builders/index.js

@@ -17,6 +17,7 @@ import { buildMastraIndexTs } from './mastra-index-ts.js';
 import { buildBuildSkillsScript } from './build-skills-ts.js';
 import { buildAgentBaseMd } from './agent-base-md.js';
 import { buildAgentTs } from './agent-ts.js';
+import { buildDemoAgentTs } from './demo-agent-ts.js';
 import { buildFrameworkGenTs } from './framework-gen-ts.js';
 import { buildFrameworkTs } from './framework-ts.js';
 /**
@@ -41,8 +42,8 @@ export const CLI_FILE_BUILDERS = [
     { relativePath: 'src/main.ts', build: () => buildMainTs() },
     { relativePath: 'src/cli.ts', build: buildCliTs },
     { relativePath: 'src/config.ts', build: buildConfigTs },
-    // User-owned; init-only. Holds `configSchema` + `secretsSchema` edits.
-    { relativePath: 'src/framework.ts', build: buildFrameworkTs, initOnly: true },
+    // User-owned outside markers; generated config/secrets inside markers.
+    { relativePath: 'src/framework.ts', build: buildFrameworkTs },
     // Machine-owned; regenerated on every run. Null when no document types.
     { relativePath: 'src/framework.gen.ts', build: buildFrameworkGenTs },
     { relativePath: 'src/mastra/index.ts', build: buildMastraIndexTs },
@@ -55,6 +56,10 @@ export const CLI_FILE_BUILDERS = [
         relativePath: 'src/agents/agent.ts',
         build: (spec) => (spec.features.mastra.enabled ? buildAgentTs(spec) : null),
     },
+    {
+        relativePath: 'src/agents/demo-agent.ts',
+        build: buildDemoAgentTs,
+    },
     // Gitkeep placeholders so directories are tracked in git when otherwise empty.
     { relativePath: 'src/commands/.gitkeep', build: () => '' },
     { relativePath: 'src/services/.gitkeep', build: () => '' },
@@ -70,7 +75,7 @@ export const CLI_FILE_BUILDERS = [
     { relativePath: 'prompts/skills-ext/.gitkeep', build: () => '' },
     { relativePath: 'tests/.gitkeep', build: () => '' },
 ];
-export { buildCliPackageJson, buildCliTs, buildConfigTs, buildMainTs, buildTsconfigJson, buildJestConfigJs, buildEslintConfigJs, buildGitignore, buildMastraIndexTs, buildBuildSkillsScript, buildAgentBaseMd, buildAgentTs, buildFrameworkGenTs, buildFrameworkTs, };
+export { buildCliPackageJson, buildCliTs, buildConfigTs, buildMainTs, buildTsconfigJson, buildJestConfigJs, buildEslintConfigJs, buildGitignore, buildMastraIndexTs, buildBuildSkillsScript, buildAgentBaseMd, buildAgentTs, buildDemoAgentTs, buildFrameworkGenTs, buildFrameworkTs, };
 export { buildRootPackageJson } from './root-package-json.js';
 export { buildPublishConfigTs } from './publish-config-ts.js';
 export { buildReadme } from './readme-md.js';

package/dist/codegen/builders/mastra-index-ts.d.ts

@@ -4,8 +4,8 @@
  * When Mastra is off, emit a no-op placeholder so the directory still exists
  * and `mastra dev` fails predictably rather than importing partial code.
  *
- * When Mastra is on with full agent config, emit a real Mastra instance
- * that registers the agent.
+ * When Mastra is on with full agent config, bootstrap the CLI and re-export
+ * the configured Mastra Agent via `cli.bootstrap()`.
  */
 import { type ClintProjectSpec } from '../../spec/types.js';
 export declare function buildMastraIndexTs(spec: ClintProjectSpec): string;

package/dist/codegen/builders/mastra-index-ts.js

@@ -1,48 +1,70 @@
+/**
+ * Derive the `{PROVIDER}_API_KEY` env var name from a provider prefix
+ * (e.g. `anthropic` → `ANTHROPIC_API_KEY`).
+ */
+function getApiKeyEnvVar(provider) {
+    return `${provider.toUpperCase()}_API_KEY`;
+}
 export function buildMastraIndexTs(spec) {
     const { mastra } = spec.features;
     if (!mastra.enabled) {
         return [
+            '// @clint:begin mastra-index',
             '/**',
             ' * Mastra Studio entry point — placeholder. Enable the `mastra` feature to',
             ' * populate this file. Until then `mastra:*` scripts are effectively no-ops.',
             ' */',
-            '// @clint:begin mastra-index',
             'export {};',
             '// @clint:end mastra-index',
             '',
         ].join('\n');
     }
-    // Full agent config available — emit real Mastra instance
+    // Full agent config available — emit bootstrap-based Mastra instance
     if (mastra.agentId && mastra.models.length > 0) {
-        const agentId = mastra.agentId;
-        return [
+        const providers = [...new Set(mastra.models.map(m => m.id.split(/[:/]/)[0]))];
+        const lines = [
+            '// @clint:begin mastra-index',
             '/**',
             ' * Mastra Studio entry point for `mastra dev` / `mastra build` / `mastra start`.',
             ' *',
-            ' * Exports a configured Mastra instance with the project agent registered.',
+            ' * Bootstraps the CLI to get the configured agent, then exports a Mastra',
+            ' * instance for Studio integration.',
             ' */',
             "import { Mastra } from '@mastra/core/mastra';",
-            "import { Agent } from '@mastra/core/agent';",
+            "import type { Agent } from '@mastra/core/agent';",
+            "import path from 'node:path';",
+            "import { cli } from '../cli.js';",
+            "import { CLI_ROOT } from '../config.js';",
             '',
-            '// @clint:begin mastra-index',
-            `const agent = new Agent({ id: '${agentId}', model: '${(mastra.models.find(m => m.isDefault) ?? mastra.models[0]).id}' });`,
+            "// Under `mastra dev`, CLI_ROOT points to .mastra/ (bundler output).",
+            '// The actual project root is its parent.',
+            "const projectRoot = path.basename(CLI_ROOT) === '.mastra'",
+            '  ? path.dirname(CLI_ROOT)',
+            '  : CLI_ROOT;',
             '',
-            'export const mastra = new Mastra({',
-            `  agents: { '${agentId}': agent },`,
-            '});',
-            '// @clint:end mastra-index',
+            'const rt = await cli.bootstrap({ workdir: projectRoot });',
             '',
-        ].join('\n');
+        ];
+        // API key env bridge for Studio
+        lines.push(`// Workaround: Mastra Studio checks process.env for API keys directly.`, `// Bridge the ph-clint resolved keys so Studio's provider detection works.`);
+        for (const provider of providers) {
+            const field = `${provider}ApiKey`;
+            const envVar = getApiKeyEnvVar(provider);
+            lines.push(`{`, `  const key = rt.config.${field} as string | undefined;`, `  if (key && !process.env.${envVar}) process.env.${envVar} = key;`, `}`);
+        }
+        lines.push('');
+        lines.push('const mastraAgent = await rt.mastraAgent as Agent | undefined;', '', 'export const mastra = new Mastra({', '  agents: mastraAgent ? { [mastraAgent.id]: mastraAgent } : {},', '});', '// @clint:end mastra-index', '');
+        return lines.join('\n');
     }
     // Mastra enabled but no full agent config yet — placeholder
     return [
+        '// @clint:begin mastra-index',
         '/**',
         ' * Mastra Studio entry point for `mastra dev` / `mastra build` / `mastra start`.',
         ' *',
         " * Re-export a configured `@mastra/core` Mastra instance from here once you",
         " * replace the demo createAgent shim with a real Mastra Agent.",
         ' */',
-        '// @clint:begin mastra-index',
         'export {};',
         '// @clint:end mastra-index',
         '',

package/dist/gen/agent-profiles/PhClintDevAgent.md

@@ -0,0 +1,13 @@
+# Agent Base System Prompt
+
+You are PhClintDevAgent, an agent available through the  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.

package/dist/gen/skills/cli-setup/.cli-docs.md

@@ -0,0 +1,135 @@
+## API Reference: CLI Setup
+
+### `defineCli<TSchema, TSecrets>(options): Cli`
+
+Factory function that creates a CLI from a declarative options object. Two generic type parameters:
+
+- `TSchema extends z.ZodType` — config schema type (defaults to `Record<string, unknown>`)
+- `TSecrets extends z.ZodType` — secrets schema type (defaults to `Record<string, unknown>`)
+
+### `CliOptions<TSchema, TSecrets>` Interface
+
+```typescript
+interface CliOptions<TSchema, TSecrets> {
+  name: string;                          // CLI name (kebab-case, used for config files and env var prefix)
+  version: string;                       // Semantic version (shown in --version)
+  root?: string;                         // Absolute path to package root (resolves sibling packages)
+  description: Resolvable<string, Config>; // Static string or function of ({ config, workdir })
+  commands: Command<any, any, any>[];    // Array of command definitions
+  configSchema?: TSchema;                // Zod schema for user-facing config
+  secretsSchema?: TSecrets;              // Zod schema for sensitive config (API keys, tokens)
+  interactive?: InteractiveConfig<Config>; // REPL configuration
+  triggers?: Trigger<any, any, any>[];   // Routine loop triggers
+  routine?: RoutineConfig;               // Routine loop timing & project scanner
+  services?: ServiceDefinition<Config>[]; // Background service definitions
+  events?: Record<string, (data: any, log: Logger) => void>; // Event handlers
+  workdir?: string;                      // Implementation-level workdir override (hides --workdir flag)
+  configDefaults?: Record<string, unknown>; // Layer 5 config defaults
+  prompts?: PromptsConfig;               // Agent skills & profiles
+}
+```
+
+### `InteractiveConfig<TConfig>` Interface
+
+```typescript
+interface InteractiveConfig<TConfig> {
+  welcome: Resolvable<string, TConfig>;  // Welcome message (static or dynamic)
+  outputWindow?: number;                 // Trailing output lines in REPL (default: 6)
+}
+```
+
+### `Resolvable<T, TConfig>` Type
+
+```typescript
+type Resolvable<T, TConfig> = T | ((ctx: { workdir: string; config: TConfig }) => T);
+```
+
+Allows static values OR dynamic computation based on resolved workdir and config.
+
+### `Cli` Object Interface
+
+Methods available on the object returned by `defineCli()`:
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `run` | `(argv: string[], options?: RunOptions) => Promise<void>` | Main entry point — parse args, dispatch command or start REPL |
+| `bootstrap` | `(opts?: BootstrapOptions) => Promise<BootstrapResult>` | Initialize runtime without dispatch — for programmatic access |
+| `execute` | `(commandId, args, context?) => Promise<unknown>` | Execute a command directly (programmatic use) |
+| `parseArgs` | `(commandId, argv) => Record<string, unknown>` | Parse CLI argv for a specific command |
+| `getCommand` | `(id: string) => Command \| undefined` | Look up a registered command |
+| `listCommands` | `() => Command[]` | List all registered commands |
+| `generateHelp` | `() => string` | Generate CLI help text |
+| `generateCommandHelp` | `(commandId: string) => string` | Generate help for a specific command |
+| `generateCompletion` | `(shell: string) => string` | Generate shell completion script (bash/zsh/fish) |
+| `configEnvVars` | `() => ConfigEnvVar[]` | List config env var mappings |
+| `getMetadata` | `() => CliMetadata` | JSON-serializable CLI metadata |
+| `configureAgent` | `(loader: AgentLoader<any>) => void` | Set the agent factory (lazy-loaded) |
+| `configureReactor` | `(config: ReactorConfiguration) => void` | Set the reactor configuration (lazy-loaded) |
+
+Properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `string` | CLI name |
+| `version` | `string` | CLI version |
+| `description` | `string` | CLI description |
+| `hasAgent` | `boolean` | True when `configureAgent()` has been called |
+| `hasReactor` | `boolean` | True when `configureReactor()` has been called |
+
+### `RunOptions` Interface
+
+```typescript
+interface RunOptions {
+  exit?: (code: number) => void;         // Override process.exit (for testing)
+  stdout?: (message: string) => void;    // Capture stdout
+  stderr?: (message: string) => void;    // Capture stderr
+  interactiveInput?: AsyncIterable<string>; // Headless REPL input (for testing)
+  resume?: string;                       // Resume agent conversation by thread ID
+  workdir?: string;                      // Override workdir (for testing)
+  configFile?: string;                   // --config flag value
+  logLevel?: LogLevel;                   // Override log verbosity (default: 'info')
+}
+```
+
+### `BootstrapOptions` & `BootstrapResult`
+
+```typescript
+interface BootstrapOptions {
+  workdir?: string;        // Explicit workdir (skips flag/cwd logic)
+  configFile?: string;     // Config file override
+  logLevel?: LogLevel;     // Log level (default: 'info')
+  stdout?: (text: string) => void;
+  stderr?: (text: string) => void;
+}
+
+interface BootstrapResult {
+  workdir: string;
+  config: Record<string, unknown>;
+  context: CommandContext;
+  getAgent(): Promise<AgentProvider | undefined>;
+  get mastraAgent(): Promise<unknown | undefined>;
+}
+```
+
+### Built-in Commands (Auto-Injected)
+
+| Command ID | Condition | Purpose |
+|-----------|-----------|---------|
+| `cli-docs` | Always | Show CLI help (also usable as agent tool) |
+| `config` | When `configSchema` provided | View/modify configuration settings |
+| `{service-id}-start` | Per service definition | Start a background service |
+| `{service-id}-stop` | Per service definition | Stop a running service |
+| `{service-id}-restart` | Per service definition | Restart a service |
+| `{service-id}-ps` | Per service definition | Show service status |
+| `{service-id}-logs` | Per service definition | Tail service logs |
+| `{service-id}-manage` | Per service definition | Interactive management (REPL only) |
+| `{service-id}-ls` | Per service + projectScanner | List discovered projects |
+
+### `readPackageInfo(importMetaUrl)`
+
+Utility to read name and version from the nearest `package.json`:
+
+```typescript
+import { readPackageInfo } from '@powerhousedao/ph-clint';
+const { name, version } = readPackageInfo(import.meta.url);
+```