@powerhousedao/ph-clint-cli 0.0.1

package/dist/gen/skills/cli-setup/references/02.wire-cli.md

@@ -0,0 +1,141 @@
+# Phase 2: Wire the defineCli Call
+
+Compose the `defineCli()` call with all the options determined in Phase 0.
+
+## Steps
+
+### 1. Assemble the core options
+
+```typescript
+import { defineCli } from '@powerhousedao/ph-clint';
+import { configSchema, secretsSchema } from './config.js';
+import { myCommand, otherCommand } from './commands/index.js';
+
+export const cli = defineCli({
+  name: 'my-app',
+  version: '1.0.0',
+  description: 'My application CLI',
+  commands: [myCommand, otherCommand],
+  configSchema,
+  secretsSchema,
+});
+```
+
+Always export the `cli` object — other files may need it (e.g., `mastra/index.ts` for `cli.bootstrap()`).
+
+### 2. Configure interactive mode
+
+Add an `interactive` block if the CLI supports REPL mode:
+
+```typescript
+interactive: {
+  welcome: 'My App CLI — type /help for commands',
+},
+```
+
+For dynamic welcome messages that depend on config:
+
+```typescript
+interactive: {
+  welcome: ({ config, workdir }) => {
+    const mode = config.apiKey ? config.model : 'demo mode';
+    return `My App (${mode})\nWorkdir: ${workdir}`;
+  },
+},
+```
+
+### 3. Add services (if needed)
+
+```typescript
+import { myService } from './services/my-service.js';
+
+defineCli({
+  // ...
+  services: [myService],
+});
+```
+
+This auto-injects `my-service-start`, `my-service-stop`, `my-service-restart`, `my-service-ps`, `my-service-logs`, and `my-service-manage` commands.
+
+### 4. Add event handlers (if needed)
+
+Wire lifecycle events for services or custom events:
+
+```typescript
+events: {
+  'service:ready': (event, log) => {
+    log.info(`${event.name} is ready`);
+  },
+  'service:failed': (event, log) => {
+    log.error(`${event.name} failed: ${event.error}`);
+  },
+  'service:stopped': (event, log) => {
+    log.info(`${event.name} stopped`);
+  },
+},
+```
+
+Available service events: `service:pattern-matched`, `service:ready`, `service:failed`, `service:restarting`, `service:stopped`. Each receives `(event, log)` where `log` is a structured Logger.
+
+### 5. Add prompts config (if skills are needed)
+
+```typescript
+import path from 'node:path';
+
+prompts: {
+  artifacts: [path.join(CLI_ROOT, 'gen', 'skills')],
+  agents: {
+    'my-agent': {
+      name: 'MyAgent',
+      sections: ['AgentBase.md', 'MySpecialization.md'],
+      skills: ['skill-one', 'skill-two'],
+    },
+  },
+  skills: {
+    'skill-one': {
+      description: 'Description of skill one',
+      inputSchema: z.object({
+        mode: z.enum(['expert', 'discovery']).default('expert').describe('Interaction mode'),
+      }),
+      instructionTemplate: 'Use your {{skillId}} skill in {{mode}} mode for: {{prompt}}',
+    },
+  },
+},
+```
+
+### 6. Call configureAgent / configureReactor (if needed)
+
+These are called AFTER `defineCli()` — they are methods on the returned `Cli` object:
+
+```typescript
+export const cli = defineCli({ /* ... */ });
+
+// Agent integration (Mastra)
+cli.configureAgent(createAgent);
+
+// Reactor integration (Powerhouse)
+cli.configureReactor({
+  registry: [/* document models */],
+  // ...
+});
+```
+
+Both are lazy-loaded — the actual agent/reactor is only created when first accessed.
+
+### 7. Codegen projects: use spec + regen
+
+In codegen-managed projects, do NOT manually edit `cli.ts` marker regions. Instead:
+
+1. Update `project-spec.json` with the new features (commands, services, triggers, integrations)
+2. Run `clint-project-regen` to regenerate marker regions
+3. Edit user-owned files directly: `framework.ts` for config/secrets schemas, `src/commands/*.ts` for commands, etc.
+
+Core options outside markers (`name`, `version`, `description`, `configSchema`, `secretsSchema`) are in the user-editable zone — edit those directly in `cli.ts`.
+
+### 8. Verify built-in commands
+
+After wiring, confirm these commands will be auto-injected:
+- `cli-docs` — always present
+- `config` — present if `configSchema` was provided
+- Service commands — present for each entry in `services`
+- Skill commands — present for each entry in `prompts.skills`

package/dist/gen/skills/cli-setup/references/03.add-entrypoint.md

@@ -0,0 +1,128 @@
+# Phase 3: Create the Entry Point
+
+Set up the CLI entry point and package.json configuration.
+
+## Steps
+
+### 1. Create the entry point file
+
+Create `src/cli.ts` (or `src/main.ts`) with the Node.js shebang:
+
+```typescript
+#!/usr/bin/env node
+import { defineCli } from '@powerhousedao/ph-clint';
+import { configSchema } from './config.js';
+import { myCommand } from './commands/my-command.js';
+
+const cli = defineCli({
+  name: 'my-app',
+  version: '1.0.0',
+  description: 'My application',
+  commands: [myCommand],
+  configSchema,
+  interactive: {
+    welcome: 'My App — type /help for commands',
+  },
+});
+
+cli.run(process.argv);
+```
+
+If the CLI definition is complex, keep it in a separate file (`src/cli-definition.ts`) and import it:
+
+```typescript
+#!/usr/bin/env node
+import { cli } from './cli-definition.js';
+cli.run(process.argv);
+```
+
+### 2. Configure package.json
+
+Add these fields:
+
+```json
+{
+  "type": "module",
+  "bin": {
+    "my-app": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "dev": "tsx src/cli.ts"
+  }
+}
+```
+
+- `"type": "module"` — required for ESM imports
+- `"bin"` — maps the CLI name to the compiled entry point
+- `"dev"` script uses `tsx` for development without compilation
+
+### 3. Configure tsconfig.json
+
+Ensure these compiler options:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "strict": true,
+    "esModuleInterop": true
+  },
+  "include": ["src"]
+}
+```
+
+### 4. Add ph-clint dependency
+
+```sh
+pnpm add @powerhousedao/ph-clint zod
+```
+
+Or for local development with the library:
+
+```json
+{
+  "dependencies": {
+    "ph-clint": "file:../../packages/ph-clint"
+  }
+}
+```
+
+### 5. Codegen projects already have entry points
+
+In codegen-managed projects (created by `clint-project-init`), the scaffold already includes:
+- `src/main.ts` — shebang entry point with `cli.run(process.argv)`
+- `src/cli.ts` — `defineCli()` with marker regions
+- `src/framework.ts` — user-owned config schemas and `createTypes()`
+- `package.json` — pre-configured with `bin`, `type: "module"`, and scripts
+
+Skip steps 1-4 if these already exist. Proceed directly to verification.
+
+### 6. Verify the CLI works
+
+Run these checks:
+
+```sh
+# Build
+pnpm build
+
+# Help output (should show all commands)
+node dist/cli.js --help
+
+# Version
+node dist/cli.js --version
+
+# A specific command
+node dist/cli.js my-command --help
+
+# Interactive mode (if configured)
+node dist/cli.js -i
+```
+
+Expected: `--help` shows the description, version, all registered commands (including auto-injected ones like `config` and `cli-docs`), and global options (`-i`, `--workdir`, `--config`, `--verbose`).

package/dist/gen/skills/cli-setup/references/expected-outcome.md

@@ -0,0 +1,3 @@
+## Expected Outcome
+
+CLI is defined with all required features wired in (config, secrets, services, interactive mode as needed). The entry point is set up with a shebang and `cli.run(process.argv)`. The `package.json` has `"bin"` and `"type": "module"` fields. The CLI responds correctly to `--help`, `--version`, `-i`, and all registered commands. If `configureAgent()` or `configureReactor()` are needed, they are called after `defineCli()`.

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

@@ -0,0 +1,84 @@
+## API Reference: Command Definition
+
+### `defineCommand<TInput, TOutput, TConfig>(options)`
+
+Identity function that returns the options object with full type inference. Accepts three generic parameters:
+
+- `TInput extends z.ZodType` — the input schema type
+- `TOutput` — the return type of `execute`
+- `TConfig` — the config type from `defineCli`
+
+### `Command<TInput, TOutput, TConfig>` Interface
+
+```typescript
+interface Command<TInput, TOutput, TConfig> {
+  id: string;                    // Kebab-case identifier (e.g. 'add-task')
+  description: string;           // One-line description for help text
+  inputSchema: TInput;           // Zod object schema — each field = CLI flag
+  outputSchema?: z.ZodType;      // Optional output validation schema
+  prompt?: PromptConfig;         // Interactive prompting configuration
+  execute: (
+    input: z.output<TInput>,
+    context: CommandContext<TConfig>
+  ) => Promise<TOutput>;
+}
+```
+
+### `CommandContext<TConfig>` Interface
+
+Available properties on the context object:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `workdir` | `string` | Resolved working directory |
+| `workspace` | `WorkdirStore` | Persistent file-based state (`.ph/{cliName}/`) |
+| `config` | `TConfig` | Typed configuration object |
+| `stdout` | `(text: string) => void` | Output function for streaming text |
+| `log` | `Logger?` | Structured logger (debug/info/warn/error) |
+| `routine` | `Routine?` | Routine loop control (if triggers configured) |
+| `processes` | `ProcessManager?` | Run shell commands with timeout and labeling |
+| `services` | `ServiceManager?` | Manage background services (if configured) |
+| `emit` | `EmitFn?` | Event bus emitter |
+| `reactor` | `() => Promise<ReactorContext?>` | Lazy Powerhouse reactor access |
+| `agent` | `() => Promise<AgentProvider?>` | Lazy Mastra agent access |
+
+### `WorkdirStore` Methods
+
+```typescript
+workspace.loadJsonObject<T>(filename, fallback)   // Load JSON from .ph/ store
+workspace.storeJsonObject(filename, value)         // Save JSON to .ph/ store
+workspace.loadLocalConfig()                        // Load local config
+workspace.storeLocalConfig(config)                 // Save local config
+workspace.getWorkdir()                             // Get workdir path
+workspace.getStoreFolder(subpath?)                 // Get .ph/ store folder path
+```
+
+### `PromptConfig` Interface
+
+```typescript
+interface PromptConfig {
+  promptForDefaults?: boolean;   // Prompt for fields with .default()? (default: true)
+  promptOptional?: string[];     // List of optional field IDs to prompt for
+}
+```
+
+### Return Value Handling
+
+The framework processes return values as follows:
+
+1. `undefined` or `null` — nothing is printed
+2. `string` — displayed directly as output
+3. Object with `.text` property — the `text` string is displayed; `.data` is available for programmatic/agent consumption
+4. Any other value — converted via `String(value)`
+
+### Registration in `defineCli`
+
+Commands are registered via the `commands` array:
+
+```typescript
+const cli = defineCli({
+  name: 'mycli',
+  commands: [greet, addTask, listTasks],
+  // ...
+});
+```

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

@@ -0,0 +1,99 @@
+---
+name: command-definition
+description: "Define commands with Zod schemas, execute functions, return values, and parameter prompting"
+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.
+
+# Command Definition - Skill Preamble
+
+With this skill, you can define ph-clint commands — the atomic building blocks of every CLI. A single command definition produces a CLI subcommand (`mycli greet --name World`), a REPL command (`/greet --name World`), an MCP tool, and an agent tool — all from the same code.
+
+## Core Principles
+
+### One Command = One User Intent
+
+Each command does one thing. Don't create CRUD bundles — instead define `add-task`, `list-tasks`, `remove-task` as separate commands. This keeps schemas focused and help text clear.
+
+### inputSchema Is the Single Source of Truth
+
+The Zod `inputSchema` drives everything: CLI flags, help text, validation, agent tool descriptions, and interactive prompting. Design the schema carefully — it's the command's public API.
+
+### `.describe()` on Every Field
+
+Every Zod field MUST have `.describe('...')`. This text appears in:
+- CLI `--help` output
+- REPL auto-completion hints
+- Agent tool descriptions
+- Parameter prompting labels
+
+Without `.describe()`, the user sees empty descriptions everywhere.
+
+### Return `{ text, data }` for Agent-Compatible Commands
+
+- Return a **string** for simple display-only commands
+- Return `{ text: 'human-readable', data: structuredResult }` when the command will also be used as an agent tool — `text` is shown to users, `data` is consumed by the agent
+
+### Execute Receives Validated Input and Injected Context
+
+The `execute(input, context)` function receives:
+1. `input` — already validated and parsed by Zod. Destructure directly: `({ name, loud })`
+2. `context` — injected by the framework. Destructure only what you need: `{ workspace, config }`
+
+Never construct context yourself. Never call `process.exit()` or `console.log()` — use the injected `context.stdout()` for streaming output, and throw errors for failures.
+
+## Common Pitfalls
+
+- **Forgetting `.describe()`** — help text and tool descriptions show empty fields
+- **Using `.optional()` when you mean `.default('value')`** — optional means the flag can be omitted entirely with no fallback; default provides a sensible fallback value
+- **Returning void** — the CLI has nothing to display; always return a string or `{ text, data }`
+- **Accessing `context.services` without null check** — it's `undefined` when no services are configured
+- **Using `console.log`** — use `context.stdout(text)` instead so output is capturable in tests
+- **Calling `process.exit()`** — throw an error instead; the framework handles exit codes
+
+## When to Use Typed Generics
+
+For simple commands, `defineCommand({ ... })` with inline schemas infers types automatically. Use explicit generics when you need to:
+- Share the input schema across commands (extract to a const)
+- Enforce a specific output type
+- Bind to a project-specific config type via `createTypes()`
+
+```typescript
+// Project-level typed factory (from framework.ts)
+const { defineCommand } = createTypes({ configSchema });
+
+// Now context.config is typed automatically
+const myCmd = defineCommand({
+  id: 'my-cmd',
+  inputSchema: z.object({ name: z.string().describe('Name') }),
+  execute: async ({ name }, { config }) => {
+    // config is fully typed here
+  },
+});
+```
+
+## Working in a Codegen-Managed Project
+
+ph-clint-cli projects are spec-driven. When defining commands:
+
+- **Import `defineCommand` from `../framework.js`**, not from `@powerhousedao/ph-clint`. The typed factory from `framework.ts` gives automatic config typing via `createTypes()`.
+- **Never hand-edit `cli.ts` marker regions.** The `@clint:begin`/`@clint:end` regions are codegen-owned. Instead:
+  1. Write the command file in `src/commands/`
+  2. Update `project-spec.json` to declare the new command
+  3. Run `clint-project-regen` to regenerate `cli.ts` with the correct imports and registration
+- **Build** after regen with `clint-project-build` to verify TypeScript compiles
+
+=== END OF SKILL BRIEFING ===
+
+## Specific tasks
+
+* **Assess Requirements** [references/00.assess-requirements.md](references/00.assess-requirements.md)
+* **Define Schema** [references/01.define-schema.md](references/01.define-schema.md)
+* **Implement Execute** [references/02.implement-execute.md](references/02.implement-execute.md)
+* **Add Prompting** [references/03.add-prompting.md](references/03.add-prompting.md)
+* **Expected Outcome** [references/expected-outcome.md](references/expected-outcome.md)

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

@@ -0,0 +1,58 @@
+# Phase 0: Assess Requirements
+
+Before writing any code, clarify what the command should do.
+
+## Steps
+
+### 1. Name the command
+
+Choose a kebab-case, verb-noun name that describes the action:
+- `add-task`, `list-images`, `run-build`, `show-status`
+- The `id` becomes the CLI subcommand and REPL `/command` name
+
+### 2. Identify all inputs
+
+For each parameter, determine:
+- **Type**: `z.string()`, `z.number()`, `z.boolean()`, `z.enum([...])`, `z.array(z.string())`
+- **Required vs optional**: Is this mandatory or can it be omitted?
+- **Default value**: What's a sensible default? Use `.default(value)` instead of `.optional()` when there is one
+- **Validation**: Regex patterns, min/max ranges, URL format, etc.
+- **Description**: One-line user-facing text for `--help`
+
+### 3. Determine context needs
+
+Which `CommandContext` properties does the command need?
+
+- [ ] `workspace` — persistent state across invocations
+- [ ] `config` — typed CLI configuration
+- [ ] `processes` — spawn shell commands
+- [ ] `services` — manage background services
+- [ ] `stdout` — streaming output (for long-running operations)
+- [ ] `log` — debug/info/warn/error logging
+- [ ] `reactor()` — Powerhouse document operations
+- [ ] `agent()` — AI agent access
+
+### 4. Determine return shape
+
+- **Display-only**: return a string
+- **Agent-compatible**: return `{ text: 'human message', data: structuredResult }`
+- **Silent**: return `undefined` (rare — most commands should confirm what they did)
+
+### 5. Determine prompting needs
+
+If the command will be used in interactive/REPL mode:
+- Which optional fields should be prompted for?
+- Should fields with defaults be re-prompted? (Usually no — set `promptForDefaults: false`)
+- Enum fields get selection prompts automatically
+
+### 6. Detect codegen project
+
+Check if `cli.ts` contains `@clint:begin` markers. If it does, this is a codegen-managed project:
+- Import `defineCommand` from `../framework.js`, not from `@powerhousedao/ph-clint`
+- Do NOT manually edit marker regions in `cli.ts` — update `project-spec.json` instead and run `clint-project-regen` to regenerate
+
+### 7. Check for existing commands
+
+- Are there existing commands that overlap with this one?
+- Does this command depend on another command's output?
+- Could this be an extension of an existing command instead?

package/dist/gen/skills/command-definition/references/01.define-schema.md

@@ -0,0 +1,72 @@
+# Phase 1: Define the Input Schema
+
+Design and write the Zod `inputSchema` that defines the command's parameters.
+
+## Steps
+
+### 1. Choose field types
+
+Select the appropriate Zod type for each parameter:
+
+```typescript
+z.string()                         // Free text
+z.string().url()                   // URL validation
+z.string().regex(/^[a-z-]+$/)      // Pattern validation
+z.number()                         // Numeric input
+z.number().min(1).max(100)         // Bounded number
+z.boolean()                        // Flag (--verbose, --dry-run)
+z.enum(['low', 'medium', 'high'])  // Fixed choices (auto-completion in REPL)
+z.array(z.string())                // Multiple values (--tag a --tag b)
+```
+
+### 2. Add `.describe()` to every field
+
+This is mandatory. The description text appears in help output, agent tool descriptions, and prompting labels:
+
+```typescript
+z.string().describe('Name of the project to initialize')
+z.boolean().default(false).describe('Run without making changes')
+```
+
+### 3. Add `.default()` for sensible defaults
+
+Fields with defaults become optional CLI flags. Without a default, the flag is mandatory:
+
+```typescript
+z.number().default(3000).describe('Port number')          // --port is optional, defaults to 3000
+z.enum(['json', 'table']).default('table').describe('Output format')
+```
+
+### 4. Mark truly optional fields
+
+Use `.optional()` only when there is genuinely no default value and the field can be absent:
+
+```typescript
+z.string().optional().describe('Due date (YYYY-MM-DD)')   // --due can be omitted entirely
+```
+
+### 5. Add validation constraints
+
+```typescript
+z.string().regex(/^[a-zA-Z0-9-]+$/).describe('Project name (alphanumeric + hyphens)')
+z.number().min(1).max(65535).describe('Port number')
+z.string().url().describe('API endpoint URL')
+```
+
+### 6. Assemble the schema
+
+```typescript
+const inputSchema = z.object({
+  name: z.string().describe('Project name'),
+  port: z.number().default(3000).describe('Dev server port'),
+  template: z.enum(['minimal', 'full']).default('minimal').describe('Project template'),
+  dryRun: z.boolean().default(false).describe('Preview changes without writing files'),
+});
+```
+
+### 7. Verify
+
+- Every required field without a default will be a mandatory `--flag`
+- Every field has `.describe()`
+- Field names are camelCase (they become `--camel-case` CLI flags automatically)
+- Enum types list all valid options