coaiajs 0.1.0

package/articles/technical/aws-sdk-v3-polly.md

@@ -0,0 +1,270 @@
+# @aws-sdk/client-polly: Technical Assessment for CoAiA.js
+
+> Package selection brief — Text-to-speech synthesis replacing coaiapy's boto3-based syntation.py
+
+## Summary & Recommendation
+
+**Use `@aws-sdk/client-polly` v3.x** (currently 3.997.0). The AWS SDK v3 modular architecture means we import only the Polly client — not the entire AWS SDK. Streaming audio responses pipe directly to files or downstream consumers. This replaces coaiapy's `syntation.py` which uses boto3 with manually configured credentials.
+
+**Pin:** `"@aws-sdk/client-polly": "^3.700.0"`
+
+## What We're Replacing
+
+Coaiapy's `syntation.py` uses boto3 for AWS Polly:
+
+```python
+# coaiapy/syntation.py — boto3-based Polly
+import boto3
+from coaiamodule import read_config
+
+def synthesize(text, voice_id, outfile, outformat="mp3"):
+    config = read_config()
+    key = config["pollyconf"]["key"]
+    secret = config["pollyconf"]["secret"]
+    region = config["pollyconf"]["region"]
+    
+    polly = boto3.client('polly',
+                         aws_access_key_id=key,
+                         aws_secret_access_key=secret,
+                         region_name=region)
+    response = polly.synthesize_speech(
+        Text=text,
+        OutputFormat=outformat,
+        VoiceId=voice_id
+    )
+    # Write audio stream to file
+    with open(outfile, 'wb') as f:
+        f.write(response['AudioStream'].read())
+```
+
+Key issues: monolithic boto3 import (~100MB installed), manual credential management from config file, synchronous blocking I/O.
+
+## Options Compared
+
+| Feature | @aws-sdk/client-polly v3 | boto3 (Python) | AWS SDK v2 (deprecated) |
+|---------|------------------------|----------------|----------------------|
+| Install size | ~5MB (just Polly) | ~100MB (all of boto3) | ~40MB (entire aws-sdk) |
+| Modular imports | ✅ Only Polly client | ❌ Entire SDK | ❌ Entire SDK |
+| Streaming response | ✅ Node.js Readable stream | ⚠️ StreamingBody | ✅ |
+| Credential chain | ✅ Automatic (env, profile, IMDS) | ✅ Automatic | ✅ Automatic |
+| TypeScript | Full native types | N/A | @types/aws-sdk |
+| Async/await | ✅ Native | ✅ | ⚠️ Callback + promise |
+| End of support | Active | Active | September 2025 ❌ |
+| SSML support | ✅ | ✅ | ✅ |
+| Neural voices | ✅ | ✅ | ✅ |
+
+## API Overview
+
+### Basic Speech Synthesis
+
+```typescript
+import { PollyClient, SynthesizeSpeechCommand } from '@aws-sdk/client-polly';
+import { Readable } from 'stream';
+import { createWriteStream } from 'fs';
+import { pipeline } from 'stream/promises';
+import { loadConfig } from '../config.js';
+
+const config = loadConfig();
+
+const polly = new PollyClient({
+  region: config.awsRegion ?? 'us-east-1',
+  // Credentials auto-resolve from env/profile/config
+  // Or explicit:
+  credentials: config.pollyKey ? {
+    accessKeyId: config.pollyKey,
+    secretAccessKey: config.pollySecret!,
+  } : undefined,
+});
+
+async function synthesize(
+  text: string,
+  voiceId: string,
+  outfile: string,
+  format: 'mp3' | 'ogg_vorbis' | 'pcm' = 'mp3'
+): Promise<void> {
+  const command = new SynthesizeSpeechCommand({
+    Text: text,
+    VoiceId: voiceId,
+    OutputFormat: format,
+    Engine: 'neural', // Use neural voices for quality
+  });
+
+  const response = await polly.send(command);
+
+  if (response.AudioStream instanceof Readable) {
+    await pipeline(response.AudioStream, createWriteStream(outfile));
+  }
+}
+```
+
+### SSML Support (Rich Speech Control)
+
+```typescript
+async function synthesizeSSML(
+  ssml: string,
+  voiceId: string,
+  outfile: string
+): Promise<void> {
+  const command = new SynthesizeSpeechCommand({
+    Text: ssml,
+    TextType: 'ssml',
+    VoiceId: voiceId,
+    OutputFormat: 'mp3',
+    Engine: 'neural',
+  });
+
+  const response = await polly.send(command);
+  if (response.AudioStream instanceof Readable) {
+    await pipeline(response.AudioStream, createWriteStream(outfile));
+  }
+}
+
+// Usage
+await synthesizeSSML(
+  `<speak>
+    <prosody rate="slow">Welcome to CoAiA.</prosody>
+    <break time="500ms"/>
+    Your structural tension chart has <emphasis>three</emphasis> pending actions.
+  </speak>`,
+  'Joanna',
+  'output.mp3'
+);
+```
+
+### Long-Form Synthesis (Start Task)
+
+For texts >3000 characters, use the async task API:
+
+```typescript
+import { 
+  PollyClient, 
+  StartSpeechSynthesisTaskCommand,
+  GetSpeechSynthesisTaskCommand 
+} from '@aws-sdk/client-polly';
+
+async function synthesizeLongForm(
+  text: string,
+  voiceId: string,
+  s3Bucket: string,
+  s3Key: string
+): Promise<string> {
+  const command = new StartSpeechSynthesisTaskCommand({
+    Text: text,
+    VoiceId: voiceId,
+    OutputFormat: 'mp3',
+    OutputS3BucketName: s3Bucket,
+    OutputS3KeyPrefix: s3Key,
+    Engine: 'neural',
+  });
+
+  const response = await polly.send(command);
+  const taskId = response.SynthesisTask?.TaskId;
+
+  // Poll for completion
+  let status = 'inProgress';
+  while (status === 'inProgress' || status === 'scheduled') {
+    await new Promise(r => setTimeout(r, 2000));
+    const task = await polly.send(
+      new GetSpeechSynthesisTaskCommand({ TaskId: taskId })
+    );
+    status = task.SynthesisTask?.TaskStatus ?? 'failed';
+  }
+
+  return response.SynthesisTask?.OutputUri ?? '';
+}
+```
+
+### Voice Listing
+
+```typescript
+import { DescribeVoicesCommand } from '@aws-sdk/client-polly';
+
+async function listVoices(language?: string): Promise<{ id: string; name: string; engine: string }[]> {
+  const command = new DescribeVoicesCommand({
+    LanguageCode: language,
+    Engine: 'neural',
+  });
+
+  const response = await polly.send(command);
+  return (response.Voices ?? []).map(v => ({
+    id: v.Id!,
+    name: v.Name!,
+    engine: v.SupportedEngines?.join(', ') ?? 'standard',
+  }));
+}
+```
+
+### Stream to Buffer (for API responses)
+
+```typescript
+async function synthesizeToBuffer(text: string, voiceId: string): Promise<Buffer> {
+  const command = new SynthesizeSpeechCommand({
+    Text: text,
+    VoiceId: voiceId,
+    OutputFormat: 'mp3',
+    Engine: 'neural',
+  });
+
+  const response = await polly.send(command);
+  
+  if (response.AudioStream instanceof Readable) {
+    const chunks: Buffer[] = [];
+    for await (const chunk of response.AudioStream) {
+      chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+  }
+  throw new Error('No audio stream in response');
+}
+```
+
+## Integration Plan
+
+1. **Core module:** `src/polly/client.ts` — PollyClient singleton from config
+2. **Synthesis:** `src/polly/synthesize.ts` — text/SSML → audio file/buffer
+3. **Voice management:** `src/polly/voices.ts` — list/select voices
+4. **CLI command:** `src/commands/speak.ts` or integrate into pipeline steps
+5. **MCP tool:** `mcp/tools/speech.ts` — speech synthesis as an agent tool
+6. **Credential pattern:** AWS credential chain (env → profile → config file)
+
+### Credential Migration
+
+```typescript
+// BEFORE (coaiapy — manual from config)
+key = config["pollyconf"]["key"]
+secret = config["pollyconf"]["secret"]
+
+// AFTER (coaiajs — AWS credential chain)
+// Option 1: Environment variables (recommended)
+// AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION
+
+// Option 2: Explicit from coaia config (backward compat)
+const polly = new PollyClient({
+  region: config.awsRegion,
+  credentials: config.pollyKey ? {
+    accessKeyId: config.pollyKey,
+    secretAccessKey: config.pollySecret!,
+  } : undefined, // falls back to default credential chain
+});
+```
+
+## Version & Ecosystem
+
+| Metric | Value |
+|--------|-------|
+| Current version | 3.997.0 (Feb 2026) |
+| Install size | ~5MB (Polly client only) |
+| TypeScript | Full native types |
+| Node.js compat | ≥16 (we target ≥20) |
+| Streaming | Native Node.js Readable |
+| Credential chain | env → profile → IMDS → config |
+| Neural voices | 60+ voices, 30+ languages |
+| SSML | Full support |
+| License | Apache-2.0 |
+
+## References
+
+- npm: https://www.npmjs.com/package/@aws-sdk/client-polly
+- AWS Polly docs: https://docs.aws.amazon.com/polly/
+- SDK v3 migration: https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/
+- v2 EOL notice: https://www.npmjs.com/package/aws-sdk

package/articles/technical/commander-cli-framework.md

@@ -0,0 +1,262 @@
+# Commander.js CLI Framework: Technical Assessment for CoAiA.js
+
+> Package selection brief — CLI framework for coaiajs's multi-subcommand interface (tash, fetch, fuse, pipeline, env, gh, narrative, pde, planning)
+
+## Summary & Recommendation
+
+**Use `commander` v12.x** for the coaiajs CLI. Commander's Git-style subcommand model maps directly to our 9+ subcommand structure. It's the most widely adopted Node.js CLI framework (weekly downloads dwarf alternatives), has zero dependencies, generates help automatically, and every team member already knows it. Clipanion's class-based approach is elegant but niche; yargs is powerful but over-engineered for our tree.
+
+**Pin:** `"commander": "^12.1.0"`
+
+## What We're Replacing
+
+**Coaiapy** uses Python's `argparse` with subparsers:
+
+```python
+# coaiapy/coaiacli.py — argparse subcommand pattern
+import argparse
+parser = argparse.ArgumentParser(description='CoAiA CLI')
+subparsers = parser.add_subparsers(dest='command')
+parser_fuse = subparsers.add_parser('fuse', help='Manage Langfuse integrations.')
+parser_gh = subparsers.add_parser('gh', help='GitHub operations.')
+# ... 9+ subcommands
+```
+
+**coaia-narrative** uses `minimist` — bare-bones argv parsing with no help generation:
+
+```typescript
+// coaia-narrative/src/cli.ts — minimist pattern
+import minimist from 'minimist';
+const args = minimist(process.argv.slice(2));
+// Manual flag handling: --memory-path, -M, --json, --no-color, --interactive
+```
+
+**coaia-planning** also uses `minimist` for `--plans-dir` and `--output-dir`.
+
+## Options Compared
+
+| Feature | Commander v12 | Yargs v17 | Clipanion v4 | minimist v1.2 |
+|---------|--------------|-----------|-------------|--------------|
+| Weekly downloads | ~125M | ~80M | ~4M | ~50M |
+| Dependencies | 0 | 5+ | 0 | 0 |
+| Subcommand model | Git-style `.command()` | Builder callbacks | Class-based `paths` | None (manual) |
+| Auto-help | ✅ Excellent | ✅ Excellent | ✅ Good | ❌ None |
+| TypeScript | Good (DefinitelyTyped) | Good | Excellent (first-class) | Minimal |
+| Learning curve | Low | Medium | Medium-high | Very low |
+| Argument parsing | Options, args, variadic | All types + coercion | All types + validation | Raw key-value |
+| Completion (bash/zsh) | Plugin available | Built-in | Not built-in | ❌ |
+| Version handling | Built-in `.version()` | Built-in | Manual | ❌ |
+| Nested subcommands | `.command()` nesting | Recursive builders | Arbitrary `paths` depth | ❌ |
+| Exit override | `.exitOverride()` for testing | `fail()` handler | Exception-based | N/A |
+
+## API Overview
+
+### Main CLI Entry Point
+
+```typescript
+// src/cli.ts
+import { Command } from 'commander';
+import { version } from '../package.json';
+
+const program = new Command()
+  .name('coaia')
+  .version(version)
+  .description('CoAiA.js — Structural Tension Agent Framework');
+
+// Register subcommands
+program.addCommand(createTashCommand());
+program.addCommand(createFetchCommand());
+program.addCommand(createFuseCommand());
+program.addCommand(createPipelineCommand());
+program.addCommand(createEnvCommand());
+program.addCommand(createGhCommand());
+program.addCommand(createNarrativeCommand());
+program.addCommand(createPdeCommand());
+program.addCommand(createPlanningCommand());
+
+program.parse();
+```
+
+### Subcommand Definition Pattern
+
+```typescript
+// src/commands/fuse.ts
+import { Command } from 'commander';
+
+export function createFuseCommand(): Command {
+  const fuse = new Command('fuse')
+    .description('Manage Langfuse integrations');
+
+  fuse
+    .command('trace')
+    .description('Create or list traces')
+    .option('-s, --session <id>', 'Session ID')
+    .option('--list', 'List recent traces')
+    .option('--json', 'Output as JSON')
+    .action(async (opts) => {
+      if (opts.list) {
+        const traces = await listTraces(opts);
+        console.log(opts.json ? JSON.stringify(traces) : formatTable(traces));
+      } else {
+        await createTrace(opts);
+      }
+    });
+
+  fuse
+    .command('score')
+    .description('Score a trace')
+    .requiredOption('-t, --trace-id <id>', 'Trace ID to score')
+    .requiredOption('-n, --name <name>', 'Score name')
+    .requiredOption('-v, --value <number>', 'Score value', parseFloat)
+    .action(async (opts) => {
+      await scoreTrace(opts.traceId, opts.name, opts.value);
+    });
+
+  return fuse;
+}
+```
+
+### GitHub Subcommand (replacing cogh.py)
+
+```typescript
+// src/commands/gh.ts
+import { Command } from 'commander';
+
+export function createGhCommand(): Command {
+  const gh = new Command('gh')
+    .description('GitHub operations');
+
+  gh.command('issues')
+    .description('List repository issues')
+    .argument('<owner>', 'Repository owner')
+    .argument('<repo>', 'Repository name')
+    .option('--state <state>', 'Filter by state', 'open')
+    .option('--labels <labels...>', 'Filter by labels')
+    .option('--json', 'JSON output')
+    .action(async (owner, repo, opts) => {
+      const issues = await listIssues(owner, repo, opts);
+      console.log(opts.json ? JSON.stringify(issues) : formatIssuesTable(issues));
+    });
+
+  gh.command('issue <owner> <repo> <number>')
+    .description('Get a specific issue')
+    .action(async (owner, repo, number) => {
+      const issue = await getIssue(owner, repo, parseInt(number));
+      console.log(JSON.stringify(issue, null, 2));
+    });
+
+  return gh;
+}
+```
+
+### Pipeline Subcommand (with YAML template loading)
+
+```typescript
+// src/commands/pipeline.ts
+import { Command } from 'commander';
+
+export function createPipelineCommand(): Command {
+  const pipeline = new Command('pipeline')
+    .description('Execute pipeline templates');
+
+  pipeline
+    .command('run <template>')
+    .description('Run a pipeline template')
+    .option('-v, --var <key=value...>', 'Template variables')
+    .option('--dry-run', 'Show execution plan without running')
+    .option('--template-dir <dir>', 'Template search directory')
+    .action(async (template, opts) => {
+      const vars = parseVars(opts.var ?? []);
+      await runPipeline(template, vars, opts);
+    });
+
+  pipeline
+    .command('list')
+    .description('List available templates')
+    .action(async () => {
+      const templates = await listTemplates();
+      templates.forEach(t => console.log(`  ${t.name} (v${t.version})`));
+    });
+
+  return pipeline;
+}
+```
+
+### Global Options Pattern
+
+```typescript
+// Shared options across all subcommands
+program
+  .option('--json', 'Output as JSON')
+  .option('--no-color', 'Disable colored output')
+  .option('--verbose', 'Verbose logging')
+  .option('-M, --memory-path <path>', 'Memory file path')
+  .option('--env <file>', 'Custom env file');
+
+// Access in any subcommand action
+function getGlobalOpts(cmd: Command) {
+  const root = cmd.parent ?? cmd;
+  return root.opts() as { json?: boolean; color?: boolean; verbose?: boolean; memoryPath?: string };
+}
+```
+
+## Integration Plan
+
+1. **Entry point:** `src/cli.ts` — Commander program with `.parse()`
+2. **Command directory:** `src/commands/` — one file per subcommand
+   - `tash.ts` — Task management (structural tension)
+   - `fetch.ts` — Data fetching operations
+   - `fuse.ts` — Langfuse integration
+   - `pipeline.ts` — Pipeline template execution
+   - `env.ts` — Environment management
+   - `gh.ts` — GitHub operations
+   - `narrative.ts` — Narrative/chart operations
+   - `pde.ts` — Prompt decomposition
+   - `planning.ts` — Plan-to-STC operations
+3. **Bin entry:** `package.json` → `"bin": { "coaia": "./dist/src/cli.js" }`
+4. **Testing:** Commander's `.exitOverride()` + `.configureOutput()` for unit tests
+
+### Migration Path from minimist
+
+```typescript
+// BEFORE (coaia-narrative minimist pattern)
+const args = minimist(process.argv.slice(2));
+const memoryPath = args['memory-path'] || args.M || process.env.COAIA_MEMORY_PATH;
+
+// AFTER (Commander)
+program.option('-M, --memory-path <path>', 'Memory file path', process.env.COAIA_MEMORY_PATH);
+// memoryPath is now typed and auto-documented in --help
+```
+
+## Version & Ecosystem
+
+| Metric | Value |
+|--------|-------|
+| Current version | 12.1.0 |
+| Weekly downloads | ~125M |
+| Dependencies | 0 |
+| TypeScript | `@types/commander` (DefinitelyTyped) |
+| GitHub stars | ~27,000 |
+| Used by | npm CLI, Vue CLI, create-react-app |
+| Node.js compat | ≥16 (we target ≥20) |
+| License | MIT |
+
+## Why Not Yargs?
+
+Yargs is powerful but overkill. Our subcommand tree is wide (9 commands) but not deeply nested. Commander's chainable API makes each command file self-contained and readable. Yargs' middleware system and callback-based builders add complexity we don't need.
+
+## Why Not Clipanion?
+
+Clipanion's TypeScript-first class-based approach is architecturally beautiful, but:
+1. ~4M weekly downloads vs Commander's ~125M = smaller help ecosystem
+2. Class-based commands are less familiar to contributors
+3. Yarn is its primary consumer; documentation coverage is thin for edge cases
+4. Commander is already in our `package.json`
+
+## References
+
+- npm: https://www.npmjs.com/package/commander
+- GitHub: https://github.com/tj/commander.js
+- Guide: https://betterstack.com/community/guides/scaling-nodejs/commander-explained/
+- Comparison: https://npm-compare.com/commander,yargs
+- Clipanion: https://github.com/arcanis/clipanion