coaiajs 0.1.0

package/rispecs/08-cli-interface.spec.md

@@ -0,0 +1,134 @@
+# 08 — CLI Interface
+
+> Unified `coaia` command with subcommands for all modules.
+
+## Desired Outcome
+
+A single `coaia` CLI binary that provides subcommands for every CoAiA module — replacing the separate CLIs in coaiapy (argparse-based) and coaia-narrative (minimist-based) with a unified commander-based interface.
+
+## Structural Tension
+
+**Current Reality:**
+- CLI entry point defined in `package.json` as `"coaia": "./dist/src/cli.js"` but no implementation exists
+- commander dependency is installed
+- coaiapy has an argparse-based CLI covering: tash, fetch, env, pipeline, transcribe, synthesize, fuse, gh
+- coaia-narrative has a minimist-based CLI covering: chart visualization, markdown export, progress display
+- coaia-pde has no CLI
+- coaia-planning has no CLI
+
+**Desired Outcome:**
+Unified CLI at `src/cli.ts` using commander, with subcommands:
+
+```
+coaia tash <key> <value> [--ttl N]
+coaia fetch <key>
+coaia env [list|get|set|unset|init]
+coaia fuse [traces|trace|prompts|scores|datasets]
+coaia pipeline [list|render|execute] <template>
+coaia transcribe <audio-file>
+coaia synthesize <text> --output <file>
+coaia gh [issues|issue|comments]
+coaia narrative [charts|chart|progress|export]
+coaia pde [decompose|list|get|export|to-stc]
+coaia plan [parse|to-stc|from-stc|sync|diff]
+coaia mcp [start|tools]
+```
+
+## Core Structure
+
+```typescript
+import { Command } from 'commander';
+
+const program = new Command()
+  .name('coaia')
+  .version(pkg.version)
+  .description('CoAiA unified CLI');
+
+// Register subcommands
+program.addCommand(redisCommands());
+program.addCommand(envCommands());
+program.addCommand(fuseCommands());
+program.addCommand(pipelineCommands());
+program.addCommand(audioCommands());
+program.addCommand(ghCommands());
+program.addCommand(narrativeCommands());
+program.addCommand(pdeCommands());
+program.addCommand(planCommands());
+program.addCommand(mcpCommands());
+```
+
+## Command Details
+
+### Redis Commands
+```
+coaia tash <key> <value> [--ttl N]     # Set key with optional TTL
+coaia fetch <key>                       # Get value by key
+coaia del <key>                         # Delete key
+coaia keys [pattern]                    # List keys matching pattern
+```
+
+### Environment Commands
+```
+coaia env init                          # Create .coaia-env file
+coaia env list                          # Show all env vars
+coaia env get <key>                     # Get specific var
+coaia env set <key> <value>             # Set env var
+coaia env unset <key>                   # Remove env var
+```
+
+### Langfuse Commands
+```
+coaia fuse traces [--limit N]           # List traces
+coaia fuse trace <id>                   # Get trace details
+coaia fuse prompts [--name X]           # List prompts
+coaia fuse scores [--trace-id X]        # List scores
+coaia fuse datasets                     # List datasets
+```
+
+### Narrative Commands
+```
+coaia narrative charts                  # List all active charts
+coaia narrative chart <id>              # Show chart details
+coaia narrative progress <id>           # Show chart progress
+coaia narrative export <id> [--format md|json]  # Export chart
+```
+
+### PDE Commands
+```
+coaia pde decompose <prompt>            # Decompose a prompt
+coaia pde list                          # List decompositions
+coaia pde get <id>                      # Get decomposition
+coaia pde export <id>                   # Export as markdown
+coaia pde to-stc <id>                   # Transform to STC
+```
+
+### Plan Commands
+```
+coaia plan parse <file>                 # Parse plan markdown
+coaia plan to-stc <file>                # Convert plan to STC
+coaia plan from-stc <chart-id>          # Generate plan from STC
+coaia plan sync <file> <chart-id>       # Bidirectional sync
+coaia plan diff <file> <chart-id>       # Show differences
+```
+
+### MCP Commands
+```
+coaia mcp start [--mode MINIMAL|STANDARD|FULL]  # Start MCP server
+coaia mcp tools [--mode X]                       # List available tools
+```
+
+## Output Formatting
+
+- Use `chalk` for colored terminal output
+- JSON output available via `--json` global flag
+- Quiet mode via `--quiet` global flag (exit code only)
+- Error output to stderr, data to stdout
+
+## Quality Criteria
+
+- ✅ Every coaiapy CLI command has an equivalent subcommand
+- ✅ `coaia --help` shows all subcommands with descriptions
+- ✅ `coaia <subcommand> --help` shows subcommand-specific help
+- ✅ Exit code 0 on success, 1 on error
+- ✅ `--json` flag produces machine-parseable output for every command
+- ✅ Works in pipe context (no TTY-dependent formatting when piped)

package/rispecs/09-mcp-server.spec.md

@@ -0,0 +1,140 @@
+# 09 — MCP Server
+
+> Unified MCP server exposing 64+ tools from all modules with feature gating.
+
+## Desired Outcome
+
+A single MCP server (`coaiajs-mcp`) that consolidates the 44 tools from coaia-narrative (27), coaia-pde (12), and coaia-planning (5) into one server, adds 20 new tools for Redis, Langfuse, pipeline, and audio, and supports feature gating so resource-constrained environments can load only what they need.
+
+## Structural Tension
+
+**Current Reality:**
+- MCP server entry defined in `package.json` as `"coaiajs-mcp": "./dist/mcp/server.js"` but `mcp/` directory is empty (only a `tools/` subdirectory stub)
+- `@modelcontextprotocol/sdk` v1.25.0 is installed as a dependency
+- Four separate MCP servers exist in parent projects:
+  - coaia-narrative: 27 tools (STC lifecycle, knowledge graph, narrative beats, MMOT)
+  - coaia-pde: 12 tools (decomposition, session management, STC transformation)
+  - coaia-planning: 5 tools (plan parsing, plan↔STC sync, PDE bridge)
+  - coaiapy: 0 MCP tools (Python library only, no MCP)
+- Each parent server has its own startup, tool registration, and transport handling
+- Users currently need 3 MCP server entries in their config to access all tools
+
+**Desired Outcome:**
+Single MCP server at `mcp/server.ts` providing:
+- All 44 parent tools with identical schemas and behavior
+- 20 new tools for previously-CLI-only functionality
+- Feature gating via `COAIAJS_MCP_MODE` environment variable
+- Single server entry in MCP client config
+
+## Feature Gating
+
+```typescript
+type McpMode = 'MINIMAL' | 'STANDARD' | 'FULL';
+```
+
+| Mode | Tools loaded | Use case |
+|------|-------------|----------|
+| **MINIMAL** | STC tools (11), KG tools (9), MMOT (2), narrative beats (3) = **25** | Memory-constrained agents, basic STC workflow |
+| **STANDARD** | MINIMAL + PDE (12) + planning (6) + Redis (5) = **48** | Standard development sessions |
+| **FULL** | STANDARD + Langfuse (8) + pipeline (3) + audio (2) + guidance (3) = **64** | Full-featured agent sessions |
+
+Default mode: `STANDARD`.
+
+## Server Architecture
+
+```typescript
+// mcp/server.ts
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+const server = new McpServer({
+  name: 'coaiajs-mcp',
+  version: pkg.version
+});
+
+// Register tools based on mode
+const mode = (process.env.COAIAJS_MCP_MODE ?? 'STANDARD') as McpMode;
+registerNarrativeTools(server);       // always
+if (mode !== 'MINIMAL') {
+  registerPdeTools(server);
+  registerPlanningTools(server);
+  registerRedisTools(server);
+}
+if (mode === 'FULL') {
+  registerLangfuseTools(server);
+  registerPipelineTools(server);
+  registerAudioTools(server);
+}
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+## Tool Registry
+
+### Narrative Engine (28 tools — always loaded)
+
+STC: `create_structural_tension_chart`, `list_active_charts`, `get_chart`, `get_chart_progress`, `manage_action_step`, `mark_action_complete`, `update_action_progress`, `update_current_reality`, `update_desired_outcome`, `get_action_step`, `remove_action_step`
+
+Knowledge Graph: `create_entities`, `create_relations`, `add_observations`, `search_nodes`, `open_nodes`, `read_graph`, `delete_entities`, `delete_relations`, `delete_observations`
+
+Narrative Beats: `create_narrative_beat`, `telescope_narrative_beat`, `list_narrative_beats`
+
+MMOT: `perform_mmot_evaluation`, `init_llm_guidance`
+
+### PDE Engine (12 tools — STANDARD+)
+
+`pde_decompose`, `pde_parse_response`, `pde_get`, `pde_list`, `pde_export_markdown`, `pde_to_stc`, `pde_preview_stc`, `pde_create_session`, `pde_get_session`, `pde_list_sessions`, `pde_session_status`, `pde_bridge_plan`
+
+### Planning Engine (6 tools — STANDARD+)
+
+`plan_parse`, `plan_to_stc`, `plan_from_stc`, `plan_sync`, `plan_diff`, `plan_bridge_pde`
+
+### Redis (5 tools — STANDARD+)
+
+`redis_tash`, `redis_fetch`, `redis_del`, `redis_keys`, `redis_exists`
+
+### Langfuse (8 tools — FULL only)
+
+`langfuse_list_traces`, `langfuse_get_trace`, `langfuse_list_prompts`, `langfuse_get_prompt`, `langfuse_list_datasets`, `langfuse_list_scores`, `langfuse_create_score`, `langfuse_list_score_configs`
+
+### Pipeline (3 tools — FULL only)
+
+`pipeline_list`, `pipeline_render`, `pipeline_execute`
+
+### Audio (2 tools — FULL only)
+
+`audio_transcribe`, `audio_synthesize`
+
+## Tool Registration Pattern
+
+Each module provides a `registerXxxTools(server: McpServer)` function:
+
+```typescript
+// mcp/tools/redis.ts
+export function registerRedisTools(server: McpServer) {
+  server.tool('redis_tash', 'Store a value in Redis with optional TTL', {
+    key: z.string().describe('Redis key'),
+    value: z.string().describe('Value to store'),
+    ttl: z.number().optional().describe('TTL in seconds'),
+  }, async ({ key, value, ttl }) => {
+    await tash(key, value, ttl);
+    return { content: [{ type: 'text', text: `Stored ${key}` }] };
+  });
+  // ... more tools
+}
+```
+
+## Transport
+
+stdio transport only (standard MCP pattern). Server reads JSON-RPC from stdin, writes to stdout. This is compatible with all MCP clients (Claude Code, Cursor, VS Code Copilot, etc.).
+
+## Quality Criteria
+
+- ✅ Single MCP config entry replaces three separate servers
+- ✅ All 44 parent tools produce identical results to their parent implementations
+- ✅ Feature gating reduces tool count without breaking functionality
+- ✅ `COAIAJS_MCP_MODE=MINIMAL` loads ≤25 tools
+- ✅ Server starts in <500ms for MINIMAL mode
+- ✅ Tool descriptions are self-documenting (LLMs understand usage without external docs)
+- ✅ Error responses include actionable information

package/rispecs/10-audio-module.spec.md

@@ -0,0 +1,63 @@
+# 10 — Audio Module
+
+> Audio transcription (OpenAI Whisper) and synthesis (AWS Polly).
+
+## Desired Outcome
+
+An audio module providing speech-to-text transcription via OpenAI Whisper and text-to-speech synthesis via AWS Polly — enabling voice-driven agent interactions and audio content generation.
+
+## Structural Tension
+
+**Current Reality:**
+- `src/audio.ts` is fully implemented (76 lines) with `synthesize()` function using AWS Polly
+- `src/llm.ts` includes `transcribeAudio()` using OpenAI Whisper
+- Both use lazy client initialization
+- coaiapy's `syntation.py` provides the same functionality via boto3 and openai Python packages
+- No MCP tools exist for audio in any parent project
+
+**Desired Outcome:**
+Audio module consolidating transcription and synthesis in one place:
+- `transcribe(audioPath)` — OpenAI Whisper speech-to-text
+- `synthesize(text, outputPath, options?)` — AWS Polly text-to-speech
+- 2 MCP tools for interactive audio operations
+- Support for multiple voices, engines, and output formats
+
+## Core API
+
+```typescript
+// Transcription (via OpenAI Whisper)
+transcribe(audioPath: string, options?: {
+  model?: string;       // default: 'whisper-1'
+  language?: string;    // ISO 639-1 code
+  prompt?: string;      // context hint
+}): Promise<string>     // returns transcribed text
+
+// Synthesis (via AWS Polly)
+synthesize(text: string, outputPath: string, options?: {
+  voice?: string;       // default: 'Joanna' (from config)
+  engine?: 'neural' | 'standard';  // default: 'neural'
+  format?: 'mp3' | 'ogg_vorbis' | 'pcm';  // default: 'mp3'
+}): Promise<string>     // returns output file path
+```
+
+## MCP Tools (2)
+
+| Tool | Purpose |
+|------|---------|
+| `audio_transcribe` | Transcribe audio file to text |
+| `audio_synthesize` | Synthesize text to audio file |
+
+## Configuration
+
+Uses config keys from `src/config.ts`:
+- `openai_api_key` — for Whisper transcription
+- `aws_access_key_id`, `aws_secret_access_key`, `aws_region` — for Polly synthesis
+- `aws_polly_voice` — default voice (fallback: `Joanna`)
+
+## Quality Criteria
+
+- ✅ `transcribe()` accepts wav, mp3, m4a, webm, mp4 audio files
+- ✅ `synthesize()` produces valid MP3 output playable in standard players
+- ✅ Missing credentials produce clear error at call time, not import time
+- ✅ Parity with coaiapy's transcription and synthesis behavior
+- ✅ `resetClient()` clears cached clients for test isolation

package/rispecs/KINSHIP.md

@@ -0,0 +1,56 @@
+# KINSHIP.md — coaiajs/rispecs
+
+## Identity
+
+**Name:** coaiajs rispecs
+**Role:** RISE-based structural specifications for the coaiajs platform
+**Status:** Genesis (2026-03-11)
+
+## Lineage
+
+These specifications synthesize the creative intent, structural patterns, and behavioral requirements from four parent projects into a unified specification set.
+
+### Parent Rispecs
+
+| Source | Location | What was inherited |
+|--------|----------|-------------------|
+| **coaia-narrative rispecs** | `/src/coaia-narrative/rispecs/` | 15 specs — STC creation, telescoping, advancing patterns, JSONL storage, MCP tools, MMOT, narrative beats, input validation, educational guidance, CLI visualization |
+| **coaia-pde rispecs** | `/src/coaia-pde/rispecs/` | 1 spec — PDE→STC transformation mapping (Four Directions → STC components) |
+| **RISE Framework** | `/src/llms/llms-rise-framework.txt` | Methodology: creative orientation, structural tension dynamics, variable detail levels, spec-as-source-of-truth |
+
+### No Prior Rispecs Existed For
+
+| Module | First specified here |
+|--------|---------------------|
+| Core config | `01-core-config.spec.md` |
+| Redis | `02-redis-module.spec.md` |
+| Langfuse | `03-langfuse-module.spec.md` |
+| Planning | `06-planning-engine.spec.md` |
+| Pipeline | `07-pipeline-templates.spec.md` |
+| CLI | `08-cli-interface.spec.md` |
+| MCP server (unified) | `09-mcp-server.spec.md` |
+| Audio | `10-audio-module.spec.md` |
+
+## Accountabilities
+
+1. **Completeness** — These specs are sufficient for another LLM to re-implement the entire coaiajs platform from scratch
+2. **Accuracy** — Current reality assessments are honest and factual, reflecting actual implementation state as of 2026-03-11
+3. **Creative orientation** — All desired outcomes use creation language, not problem-solving language
+4. **Backward compatibility** — Specs preserve behavioral compatibility with parent projects
+5. **Independence** — Specs are codebase-agnostic; they describe behavior, not implementation
+
+## Consumers
+
+| Consumer | How they use these specs |
+|----------|------------------------|
+| **coaiajs implementors** | Build each module from its spec |
+| **coaia-narrative maintainers** | Verify their rispecs are preserved in consolidation |
+| **coaia-pde maintainers** | Verify PDE→STC mapping is preserved |
+| **MMOT evaluations** | Elements of Performance derived from quality criteria sections |
+| **mia-code / miaco** | Reference for PDE and narrative integration patterns |
+
+## Structural Tension
+
+**Desired Outcome:** These rispecs serve as the single source of truth for what coaiajs should become — complete enough for autonomous re-implementation, accurate enough for MMOT self-evaluation.
+
+**Current Reality:** 13 spec files covering the full platform. Parent project rispecs remain authoritative for deep behavioral details (especially coaia-narrative's 15 specs). These specs provide the consolidation vision and module boundaries.

package/rispecs/README.md

@@ -0,0 +1,100 @@
+# CoAiA.js — RISE Specifications
+
+> Complete RISE-based specifications for rebuilding CoAiA.js from scratch.
+> Another LLM or developer reading these specs alone should be able to re-implement the entire system.
+
+## Purpose
+
+These rispecs define the structural specifications for **coaiajs** — the unified TypeScript platform that consolidates `coaiapy`, `coaia-narrative`, `coaia-pde`, and `coaia-planning` into a single modern Node.js package.
+
+## Specification Index
+
+### Platform
+
+| # | Spec | Scope |
+|---|------|-------|
+| 00 | [coaiajs-platform](./00-coaiajs-platform.spec.md) | Master platform spec — vision, lineage, component map |
+
+### Core Modules
+
+| # | Spec | Scope | Lineage |
+|---|------|-------|---------|
+| 01 | [core-config](./01-core-config.spec.md) | Config loading, env vars, deep merge | coaiapy `read_config()` |
+| 02 | [redis-module](./02-redis-module.spec.md) | Redis tash/fetch, lazy connection, Upstash | coaiapy `tash/fetch` |
+| 03 | [langfuse-module](./03-langfuse-module.spec.md) | Langfuse observability REST client | coaiapy `cofuse.py` |
+
+### Engine Modules
+
+| # | Spec | Scope | Lineage |
+|---|------|-------|---------|
+| 04 | [narrative-engine](./04-narrative-engine.spec.md) | JSONL knowledge graph, STC, beats, MMOT | coaia-narrative `graph-manager.ts` |
+| 05 | [pde-engine](./05-pde-engine.spec.md) | PDE→STC transformation, session management | coaia-pde `stc-mapper.ts` |
+| 06 | [planning-engine](./06-planning-engine.spec.md) | Plan parsing, plan↔STC sync | coaia-planning `plan-parser.ts` |
+
+### Support Modules
+
+| # | Spec | Scope | Lineage |
+|---|------|-------|---------|
+| 07 | [pipeline-templates](./07-pipeline-templates.spec.md) | Template rendering, variable substitution | coaiapy `pipeline.py` |
+| 10 | [audio-module](./10-audio-module.spec.md) | Whisper transcription, Polly synthesis | coaiapy `syntation.py` |
+
+### Interface Layers
+
+| # | Spec | Scope | Lineage |
+|---|------|-------|---------|
+| 08 | [cli-interface](./08-cli-interface.spec.md) | Unified `coaia` CLI with all subcommands | coaiapy argparse + coaia-narrative minimist |
+| 09 | [mcp-server](./09-mcp-server.spec.md) | Unified MCP server with 64+ tools | 4 separate MCP servers |
+
+## How Specs Relate
+
+```
+┌─────────────────────────────────────────────────────┐
+│  00-coaiajs-platform (master)                       │
+│                                                     │
+│  ┌─────────┐  ┌──────────┐  ┌───────────────────┐  │
+│  │01 config │→ │02 redis  │  │03 langfuse        │  │
+│  └────┬─────┘  └─────┬────┘  └────────┬──────────┘  │
+│       │              │               │              │
+│  ┌────▼──────────────▼───────────────▼──────────┐   │
+│  │  04 narrative-engine (JSONL, STC, MMOT)      │   │
+│  └────────┬──────────────────────┬──────────────┘   │
+│           │                      │                  │
+│  ┌────────▼──────┐  ┌───────────▼──────────────┐   │
+│  │05 pde-engine  │  │06 planning-engine        │   │
+│  └───────────────┘  └──────────────────────────┘   │
+│                                                     │
+│  ┌───────────────┐  ┌──────────────────────────┐   │
+│  │07 pipeline    │  │10 audio                  │   │
+│  └───────────────┘  └──────────────────────────┘   │
+│                                                     │
+│  ┌──────────────────────────────────────────────┐   │
+│  │ 08 cli-interface        09 mcp-server        │   │
+│  └──────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────┘
+```
+
+## Conventions
+
+- **Creative orientation**: Desired Outcome describes what IS CREATED, not what is fixed
+- **Honest current reality**: Factual assessment of where things stand today
+- **Structural tension**: The gap between current and desired that drives advancement
+- **Variable detail**: Broad for obvious patterns, precise for critical behavior
+- **Naming**: `NN-kebab-case.spec.md`
+- **Codebase-agnostic**: Specs describe behavior, not implementation details
+
+## Relationship to Parent Rispecs
+
+| Project | Rispecs location | Status |
+|---------|-----------------|--------|
+| coaia-narrative | `/src/coaia-narrative/rispecs/` | 15 specs — most mature, patterns inherited here |
+| coaia-pde | `/src/coaia-pde/rispecs/` | 1 spec — PDE→STC transformation |
+| coaia-planning | — | No rispecs yet — spec 06 here is the first |
+| coaiapy | — | No rispecs — specs 01-03, 07, 10 here are the first |
+
+## RISE Framework Reference
+
+These specs follow the RISE Framework (`/src/llms/llms-rise-framework.txt`):
+- **R**everse-engineer: Extract creative intent from parent projects
+- **I**ntent-extract: Identify what each module enables users to create
+- **S**pecify: Define structural tension between current and desired
+- **E**xport: Produce specs sufficient for autonomous re-implementation

package/src/audio.ts

@@ -0,0 +1,76 @@
+// coaiajs/src/audio.ts — Audio synthesis module
+// Parity with coaiapy's syntation.py using AWS Polly
+
+import {
+  PollyClient,
+  SynthesizeSpeechCommand,
+  type SynthesizeSpeechCommandInput,
+} from '@aws-sdk/client-polly';
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { getConfig } from './config.js';
+
+let _client: PollyClient | null = null;
+
+function getPollyClient(): PollyClient {
+  if (!_client) {
+    const cfg = getConfig();
+    _client = new PollyClient({
+      region: cfg.aws?.region ?? process.env['AWS_REGION'] ?? 'us-east-1',
+      credentials:
+        cfg.aws?.accessKeyId
+          ? {
+              accessKeyId: cfg.aws.accessKeyId,
+              secretAccessKey: cfg.aws.secretAccessKey ?? '',
+            }
+          : undefined,
+    });
+  }
+  return _client;
+}
+
+/** Reset client (testing). */
+export function resetClient(): void {
+  _client = null;
+}
+
+/**
+ * Synthesize text to speech using AWS Polly.
+ * Returns the path to the output audio file.
+ *
+ * @param text - Text to synthesize
+ * @param voiceId - Polly voice ID (default: "Joanna")
+ * @param outFile - Output file path (default: "./output.mp3")
+ */
+export async function synthesize(
+  text: string,
+  voiceId?: string,
+  outFile?: string,
+): Promise<string> {
+  const client = getPollyClient();
+  const outputPath = resolve(outFile ?? './output.mp3');
+
+  const params: SynthesizeSpeechCommandInput = {
+    Text: text,
+    OutputFormat: 'mp3',
+    VoiceId: (voiceId ?? 'Joanna') as SynthesizeSpeechCommandInput['VoiceId'],
+    Engine: 'neural',
+  };
+
+  const result = await client.send(new SynthesizeSpeechCommand(params));
+
+  if (result.AudioStream) {
+    // AudioStream is a Readable or Uint8Array depending on environment
+    const chunks: Uint8Array[] = [];
+    const stream = result.AudioStream as AsyncIterable<Uint8Array>;
+
+    for await (const chunk of stream) {
+      chunks.push(chunk);
+    }
+
+    const buffer = Buffer.concat(chunks);
+    writeFileSync(outputPath, buffer);
+  }
+
+  return outputPath;
+}

package/src/cli-helpers.ts

@@ -0,0 +1,86 @@
+import chalk from 'chalk';
+
+let colorEnabled = true;
+
+export function setColorEnabled(enabled: boolean): void {
+  colorEnabled = enabled;
+  if (!enabled) {
+    chalk.level = 0;
+  }
+}
+
+export function formatTable(headers: string[], rows: string[][]): string {
+  if (rows.length === 0) return '(no data)';
+
+  const widths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map(r => (r[i] ?? '').length))
+  );
+
+  const headerLine = headers
+    .map((h, i) => h.padEnd(widths[i]!))
+    .join('  ');
+  const separator = widths.map(w => '─'.repeat(w)).join('──');
+  const dataLines = rows.map(row =>
+    row.map((cell, i) => (cell ?? '').padEnd(widths[i]!)).join('  ')
+  );
+
+  return [
+    colorEnabled ? chalk.bold(headerLine) : headerLine,
+    separator,
+    ...dataLines,
+  ].join('\n');
+}
+
+export function formatJson(data: unknown): string {
+  return JSON.stringify(data, null, 2);
+}
+
+export function formatError(message: string): string {
+  const sym = colorEnabled ? chalk.red('✗') : '✗';
+  const txt = colorEnabled ? chalk.red(message) : message;
+  return `${sym} ${txt}`;
+}
+
+export function formatSuccess(message: string): string {
+  const sym = colorEnabled ? chalk.green('✓') : '✓';
+  const txt = colorEnabled ? chalk.green(message) : message;
+  return `${sym} ${txt}`;
+}
+
+export function truncate(text: string, maxLength: number): string {
+  if (text.length <= maxLength) return text;
+  return text.slice(0, maxLength - 1) + '…';
+}
+
+export function formatDate(iso: string): string {
+  const date = new Date(iso);
+  if (isNaN(date.getTime())) return iso;
+  const now = new Date();
+  const diffMs = now.getTime() - date.getTime();
+  const diffMins = Math.floor(diffMs / 60_000);
+  const diffHours = Math.floor(diffMins / 60);
+  const diffDays = Math.floor(diffHours / 24);
+
+  if (diffMins < 1) return 'just now';
+  if (diffMins < 60) return `${diffMins}m ago`;
+  if (diffHours < 24) return `${diffHours}h ago`;
+  if (diffDays < 7) return `${diffDays}d ago`;
+  return date.toISOString().slice(0, 10);
+}
+
+export function formatProgress(completed: number, total: number): string {
+  if (total === 0) return '[░░░░░░░░░░] 0% (0/0)';
+  const ratio = Math.min(completed / total, 1);
+  const pct = Math.round(ratio * 100);
+  const filled = Math.round(ratio * 10);
+  const empty = 10 - filled;
+  const bar = '█'.repeat(filled) + '░'.repeat(empty);
+  const colored = colorEnabled
+    ? ratio >= 1
+      ? chalk.green(bar)
+      : ratio >= 0.5
+        ? chalk.yellow(bar)
+        : chalk.red(bar)
+    : bar;
+  return `[${colored}] ${pct}% (${completed}/${total})`;
+}