@powerhousedao/ph-clint-cli 0.1.0-dev.8 → 0.1.0-dev.81

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

package/dist/gen/skills/command-definition/references/02.implement-execute.md

@@ -0,0 +1,118 @@
+# Phase 2: Implement the Execute Function
+
+Write the command's logic inside the `execute` function.
+
+## Steps
+
+### 1. Destructure input and context
+
+Only destructure what you need:
+
+```typescript
+execute: async ({ name, port }, { workspace, config }) => {
+  // `name` and `port` are validated by Zod
+  // `workspace` and `config` are injected by the framework
+}
+```
+
+### 2. Implement the command logic
+
+The body is a regular async function. Use the context resources:
+
+**Workspace (persistent state)**:
+```typescript
+const tasks = await workspace.loadJsonObject<Task[]>('tasks.json', []);
+tasks.push(newTask);
+await workspace.storeJsonObject('tasks.json', tasks);
+```
+
+**Processes (shell commands)**:
+```typescript
+const result = await processes!.run('npm install', {
+  label: 'install',
+  timeout: 60_000,
+});
+```
+
+**Streaming output (long operations)**:
+```typescript
+context.stdout('Building project...\n');
+// ... work ...
+context.stdout('Done.\n');
+```
+
+### 3. Choose the return shape
+
+**Simple display** — return a string:
+```typescript
+return `Created project "${name}" at port ${port}`;
+```
+
+**Agent-compatible** — return `{ text, data }`:
+```typescript
+const project = { name, port, path: projectDir };
+return {
+  text: `Created project "${name}" at ${projectDir}`,
+  data: project,
+};
+```
+
+### 4. Handle errors
+
+Throw errors — the framework catches them and formats the output:
+
+```typescript
+if (!fs.existsSync(targetDir)) {
+  throw new Error(`Directory not found: ${targetDir}`);
+}
+```
+
+Do NOT:
+- Return error strings (the exit code will be 0)
+- Call `process.exit(1)` (breaks testability)
+- Use `console.error()` (not captured by RunOptions)
+
+### 5. Assemble the full command
+
+```typescript
+import { defineCommand } from '../framework.js';
+import { z } from 'zod';
+
+export const myCommand = defineCommand({
+  id: 'my-command',
+  description: 'Does something useful',
+  inputSchema: z.object({
+    name: z.string().describe('The name'),
+    verbose: z.boolean().default(false).describe('Show detailed output'),
+  }),
+  execute: async ({ name, verbose }, { workspace, config }) => {
+    // Implementation here
+    return { text: `Done: ${name}`, data: { name } };
+  },
+});
+```
+
+### 6. Export and register
+
+Export the command from its file, then register it in the CLI.
+
+**In a codegen-managed project** (cli.ts has `@clint:begin` markers):
+
+Do NOT manually edit `cli.ts`. Instead:
+
+1. Add the command to `project-spec.json`
+2. Run `clint-project-regen` — this regenerates the marker regions with the correct import and registration
+3. Run `clint-project-build` to verify TypeScript compiles
+
+**In a manually-managed project** (no markers):
+
+```typescript
+import { myCommand } from './commands/my-command.js';
+
+const cli = defineCli({
+  commands: [...existingCommands, myCommand],
+  // ...
+});
+```
+
+In both cases, import `defineCommand` from `../framework.js` in your command file (not from `@powerhousedao/ph-clint`) to get automatic config typing.

package/dist/gen/skills/command-definition/references/03.add-prompting.md

@@ -0,0 +1,54 @@
+# Phase 3: Configure Interactive Prompting (Optional)
+
+Set up parameter prompting for REPL/interactive mode.
+
+## When to Add Prompting
+
+Add prompting when the command is frequently used in interactive mode and has optional parameters that benefit from guided input. Skip this phase if the command is primarily used in command mode or all parameters are required.
+
+## Steps
+
+### 1. Add `prompt` config to `defineCommand`
+
+```typescript
+export const addTask = defineCommand({
+  id: 'add-task',
+  description: 'Add a new task',
+  inputSchema: z.object({
+    title: z.string().describe('Task title'),
+    priority: z.enum(['low', 'medium', 'high']).optional().describe('Task priority'),
+    due: z.string().optional().describe('Due date (YYYY-MM-DD)'),
+  }),
+  prompt: {
+    promptForDefaults: false,
+    promptOptional: ['priority'],
+  },
+  execute: async ({ title, priority, due }, { workspace }) => {
+    // ...
+  },
+});
+```
+
+### 2. Understand the prompting options
+
+**`promptForDefaults: false`** (recommended):
+- Fields with `.default()` values will NOT be prompted for
+- The default value is used silently
+- Set to `true` only if users frequently need to override defaults
+
+**`promptOptional: ['field1', 'field2']`**:
+- These `.optional()` fields WILL be prompted for in REPL mode
+- Omitted optional fields are NOT prompted (they stay `undefined`)
+- Use this for fields that are useful but not required
+
+### 3. How prompting works at runtime
+
+- **CLI mode** (`mycli add-task --title "Buy milk"`): No prompting. Missing required fields are errors. Optional fields default to `undefined`.
+- **REPL mode** (`/add-task`): Missing required fields trigger text prompts. Fields in `promptOptional` trigger prompts. Enum fields show selection menus.
+
+### 4. Test the prompting behavior
+
+In the REPL:
+1. Type `/add-task` with no arguments — required fields should be prompted
+2. Type `/add-task --title "test"` — only `promptOptional` fields should be prompted
+3. Enum fields should show a selection list, not free text input

package/dist/gen/skills/command-definition/references/expected-outcome.md

@@ -0,0 +1,3 @@
+## Expected Outcome
+
+Command is defined with typed inputSchema, exported, and registered in `defineCli`. Help text is complete (every field has `.describe()`). If intended as an agent tool, returns `{ text, data }`. The command handles all input combinations correctly and follows ph-clint conventions (no `console.log`, no `process.exit`, errors are thrown).