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

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

@@ -0,0 +1,125 @@
+---
+name: cli-setup
+description: "Set up a new CLI with defineCli, config schemas, entrypoint, and interactive mode"
+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.
+
+# CLI Setup - Skill Preamble
+
+With this skill, you can scaffold or extend a `defineCli()` configuration — the composition root that wires commands, config, services, triggers, and integrations into a single CLI runtime. A single `defineCli()` call produces a CLI that works in command mode (`mycli cmd --arg val`), interactive REPL mode (`/cmd --arg val`), and as an MCP server — all from the same code.
+
+## Core Principles
+
+### defineCli Is Declarative
+
+You describe _what_ the CLI has — the framework wires it up. The order of options doesn't matter, but understanding what triggers what does:
+
+- `configSchema` present → auto-injects a `config` command for viewing/modifying settings
+- `secretsSchema` present → fields merge into configSchema internally, but are censored in output
+- `services` present → auto-injects per-service management commands (`{id}-start`, `{id}-stop`, etc.)
+- `interactive` present → enables the `-i` flag for REPL mode
+- `triggers` present → enables routine loop
+- `cli-docs` command is always auto-injected (CLI help for the agent)
+
+### Resolvable Values
+
+`description` and `interactive.welcome` accept either a static string or a function `({ config, workdir }) => string`. Use functions when the message depends on runtime state — e.g., showing "demo mode" vs "LLM mode" based on whether an API key is configured.
+
+### The Cli Object
+
+`defineCli()` returns a `Cli` object — the public API with methods for running, testing, introspection, and metadata. The standard entry point is `cli.run(process.argv)`. For programmatic access (e.g., codegen scripts), use `cli.bootstrap()` which resolves workdir, config, and context without entering the dispatch loop.
+
+### Two Interaction Modes
+
+1. **Command mode** (headless): Execute one subcommand, then exit. Triggered by `mycli cmd --flag val`.
+2. **Interactive REPL mode**: Persistent session with `/command` syntax and bare text for the default subcommand (typically the agent). Triggered by `mycli -i` or when keep-alive features are active (routine loop, API server).
+
+### 6-Layer Config Resolution
+
+Config values are resolved in this priority order (highest wins):
+1. `--config <file>` flag
+2. Environment variables: `{CLI_NAME}_{UPPER_SNAKE_FIELD}`
+3. Local config: `{workdir}/.ph/{cliName}.config.local.json`
+4. User config: `~/.ph/{cliName}.config.user.json`
+5. Implementation defaults: `configDefaults` in CliOptions
+6. Zod schema `.default()` values
+
+### Config vs Secrets
+
+- `configSchema` — user-facing settings (model name, ports, feature flags). Shown in `config` command output.
+- `secretsSchema` — sensitive values (API keys, tokens). Merged into configSchema internally but censored as `***` in output unless `--revealSecrets` is used.
+
+Put API keys and tokens in `secretsSchema`, not `configSchema`.
+
+### configDefaults vs Schema Defaults
+
+- `.default(value)` in the Zod schema → layer 6, the fallback when nothing else is configured
+- `configDefaults` in CliOptions → layer 5, implementation-level overrides that sit above schema defaults but below user/local config
+
+Use schema `.default()` for universal sensible defaults. Use `configDefaults` for implementation-specific overrides that differ from the general-purpose default.
+
+### Entry Point Convention
+
+The CLI entry point is a TypeScript file with a Node.js shebang:
+
+```typescript
+#!/usr/bin/env node
+import { defineCli } from '@powerhousedao/ph-clint';
+// ... imports ...
+const cli = defineCli({ /* options */ });
+cli.run(process.argv);
+```
+
+The `package.json` needs a `"bin"` field pointing to the compiled output and `"type": "module"` for ESM.
+
+## Common Pitfalls
+
+- **Forgetting `version`** — Commander needs it for the `--version` flag; omitting it breaks help output
+- **Putting secrets in `configSchema`** — they show up in `config` command output and metadata, exposing sensitive values
+- **Not setting `interactive.welcome`** — REPL starts with no context, confusing the user
+- **Using `configDefaults` for universal defaults** — use `.default()` in the schema instead; `configDefaults` is for implementation-level overrides only
+- **Calling `configureAgent()` inside `defineCli()`** — it's a method on the returned `Cli` object, called after definition
+- **Forgetting `"type": "module"` in package.json** — ESM imports fail at runtime
+- **Not exporting the `cli` object** — other files (e.g., `mastra/index.ts`) may need it for `cli.bootstrap()`
+
+## When to Use `createTypes()`
+
+For projects with a config schema, use the typed factory to get automatic config typing in all commands:
+
+```typescript
+import { createTypes } from '@powerhousedao/ph-clint';
+const { defineCommand, defineTrigger } = createTypes({ configSchema });
+// context.config is now fully typed in every command
+```
+
+## Codegen-Managed Projects
+
+In ph-clint-cli projects, `clint-project-init` generates the initial scaffold including `cli.ts` with `@clint:begin`/`@clint:end` marker regions. The codegen system:
+
+- **Generates `cli.ts`** with marker regions for imports, commands, services, triggers, prompts, events, interactive, reactor, and mastra
+- **Generates `framework.gen.ts`** (codegen-owned) with the document registry — regenerated when the spec's `documentTypes` change
+- **Emits `framework.ts`** once (user-owned) with `configSchema`, `secretsSchema`, and `createTypes()` — never overwritten after creation
+
+**The agent never hand-edits marker regions in `cli.ts`.** To add or change CLI features:
+
+1. Update `project-spec.json` to declare the new structure
+2. Run `clint-project-regen` to regenerate the marker regions
+3. Run `clint-project-build` to verify
+
+User-owned code outside markers (`configSchema`, `secretsSchema`, `CLI_NAME`) is preserved across regens. User-owned files (`framework.ts`, `src/commands/*.ts`, `src/services/*.ts`, `src/triggers/*.ts`) are never overwritten.
+
+=== END OF SKILL BRIEFING ===
+
+## Specific tasks
+
+* **Assess Cli Needs** [references/00.assess-cli-needs.md](references/00.assess-cli-needs.md)
+* **Define Config Schema** [references/01.define-config-schema.md](references/01.define-config-schema.md)
+* **Wire Cli** [references/02.wire-cli.md](references/02.wire-cli.md)
+* **Add Entrypoint** [references/03.add-entrypoint.md](references/03.add-entrypoint.md)
+* **Expected Outcome** [references/expected-outcome.md](references/expected-outcome.md)

package/dist/gen/skills/cli-setup/references/00.assess-cli-needs.md

@@ -0,0 +1,53 @@
+# Phase 0: Assess CLI Needs
+
+Before writing any code, determine which features the CLI requires.
+
+## Steps
+
+### 1. Name the CLI
+
+Choose a kebab-case name. This name is used for:
+- Config file paths: `{workdir}/.ph/{name}.config.local.json`
+- Environment variable prefix: `{NAME}_*` (UPPER_SNAKE_CASE)
+- Package `"bin"` field and executable name
+
+### 2. Determine version sourcing
+
+Choose one:
+- **Hardcoded**: `version: '1.0.0'`
+- **From package.json**: `const { version } = readPackageInfo(import.meta.url)`
+
+### 3. Feature checklist
+
+For each feature, determine if the CLI needs it:
+
+- [ ] **Custom config?** → needs `configSchema` (Zod object)
+- [ ] **Sensitive config (API keys, tokens)?** → needs `secretsSchema` (Zod object)
+- [ ] **Interactive REPL?** → needs `interactive` with `welcome` message
+- [ ] **Background services?** → needs `services` array of `defineService()` definitions
+- [ ] **Automated triggers?** → needs `triggers` array + `routine` config
+- [ ] **AI agent?** → needs `cli.configureAgent(loader)` after `defineCli()`
+- [ ] **Skill templates?** → needs `prompts` config with `artifacts`, `agents`, `skills`
+- [ ] **Powerhouse documents?** → needs `cli.configureReactor(config)` after `defineCli()`
+- [ ] **Service lifecycle events?** → needs `events` handlers
+- [ ] **Implementation-level workdir override?** → needs `workdir` option (hides `--workdir` flag)
+
+### 4. List commands to register
+
+Enumerate all commands that will be passed to the `commands` array. These should already be defined using `defineCommand()` (see the `command-definition` skill). Note which ones need agent-compatible `{ text, data }` returns.
+
+### 5. Detect codegen vs manual project
+
+For existing projects, check if `cli.ts` already has `@clint:begin` marker regions:
+- **Codegen-managed**: Markers present — update `project-spec.json` and run `clint-project-regen`. Never hand-edit marker regions.
+- **Manual**: No markers — edit `defineCli()` directly as a regular TypeScript file.
+
+For new projects, prefer using `clint-project-init` to generate the scaffold with markers.
+
+### 6. Determine config field names
+
+For each config/secret field, verify the auto-generated env var name is sensible:
+- Field `apiKey` on CLI `mycli` → env var `MYCLI_API_KEY`
+- Field `connectPort` on CLI `vetra` → env var `VETRA_CONNECT_PORT`
+
+If a name would be confusing, consider renaming the field.

package/dist/gen/skills/cli-setup/references/01.define-config-schema.md

@@ -0,0 +1,78 @@
+# Phase 1: Define Config and Secrets Schemas
+
+Design and wire the configuration layer. Skip this phase if the CLI needs no configuration.
+
+## Steps
+
+### 1. Define configSchema
+
+Create a Zod object schema for user-facing settings:
+
+```typescript
+import { z } from 'zod';
+
+export const configSchema = z.object({
+  model: z.string().default('anthropic/claude-sonnet-4-5').describe('LLM model to use'),
+  port: z.number().default(4001).describe('Server port'),
+  verbose: z.boolean().default(false).describe('Enable verbose output'),
+});
+```
+
+Rules:
+- Every field MUST have `.describe('...')` — it appears in `config` command output, `--help`, and env var listings
+- Use `.default(value)` for fields with sensible defaults
+- Use `.optional()` only for truly optional fields with no default
+- Prefer specific types: `z.enum([...])` for constrained choices, `z.number()` for ports
+
+### 2. Define secretsSchema
+
+Create a separate Zod object schema for sensitive values:
+
+```typescript
+export const secretsSchema = z.object({
+  apiKey: z.string().optional().describe('LLM API key'),
+  dbToken: z.string().optional().describe('Database access token'),
+});
+```
+
+Rules:
+- Secrets are almost always `.optional()` — the CLI should work without them (possibly in a degraded mode)
+- These fields are merged into configSchema internally but censored in output
+- They follow the same env var naming: `{CLI_NAME}_{FIELD}`
+
+### 3. Set configDefaults (if needed)
+
+Use `configDefaults` in `defineCli()` for implementation-specific overrides that differ from the schema defaults:
+
+```typescript
+defineCli({
+  configSchema,
+  configDefaults: {
+    port: 8080, // This implementation uses 8080, not the schema default of 4001
+  },
+});
+```
+
+This is layer 5 — above schema `.default()` but below user/local config files.
+
+### 4. Use createTypes for typed commands
+
+If you have a configSchema, create a typed factory so all commands get typed `context.config`:
+
+```typescript
+// framework.ts
+import { createTypes } from '@powerhousedao/ph-clint';
+import { configSchema, secretsSchema } from './config.js';
+
+export const { defineCommand, defineTrigger } = createTypes({ configSchema, secretsSchema });
+export { configSchema, secretsSchema };
+```
+
+Then import `defineCommand` from `./framework.js` instead of `ph-clint` in all command files.
+
+### 5. Verify env var names
+
+Run through each field and check the auto-generated env var name:
+- `{CLI_NAME}` is the CLI name uppercased with hyphens replaced by underscores
+- Field keys are converted to UPPER_SNAKE_CASE
+- Example: CLI `my-app`, field `connectPort` → `MY_APP_CONNECT_PORT`

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],
+  // ...
+});
+```