coaiajs 0.3.0 → 0.3.2

package/articles/technical/yaml-parsing-node.md

@@ -1,266 +0,0 @@
-# YAML Parsing in Node.js: Technical Assessment for CoAiA.js
-
-> Package selection brief — YAML parser for pipeline templates, session files, and config loading replacing coaiapy's PyYAML
-
-## Summary & Recommendation
-
-**Use `yaml` v2.x** (the npm package named simply `yaml`). Despite `js-yaml` having higher download numbers, the modern `yaml` package offers streaming support for large files, comment preservation (critical for human-edited pipeline templates), and a cleaner API. CoAiA pipeline templates are user-authored YAML that benefits from round-trip fidelity — comments survive parse→stringify cycles.
-
-**Pin:** `"yaml": "^2.6.0"`
-
-## What We're Replacing
-
-Coaiapy uses PyYAML for pipeline template loading:
-
-```python
-# coaiapy/pipeline.py — PyYAML pattern
-import yaml
-
-# Load pipeline template
-for template_file in search_path.glob("*.yaml"):
-    with open(yaml_file, 'r') as f:
-        data = yaml.safe_load(f)  # Parse YAML → dict
-
-# Pipeline template format:
-# name: "trace-session"
-# version: "1.0"
-# variables:
-#   - name: session_id
-#     type: string
-#     required: true
-# steps:
-#   - name: create_trace
-#     observation_type: SPAN
-```
-
-PyYAML's `safe_load` works well; the JavaScript equivalent needs the same safety guarantees plus TypeScript types.
-
-## Options Compared
-
-| Feature | yaml v2.6 | js-yaml v4.1 |
-|---------|-----------|-------------|
-| Weekly npm downloads | ~80M | ~130M |
-| GitHub stars | ~1,600 | ~6,500 |
-| Parse speed (typical files) | Good | Faster (~10%) |
-| Stringify speed | Faster | Slower |
-| Streaming support | ✅ Parse & stringify | ❌ Memory only |
-| Comment preservation | ✅ Round-trip fidelity | ❌ Comments lost |
-| Anchor/alias support | ✅ Full | ✅ Full |
-| Custom tags | ✅ Flexible API | ✅ Schema-based |
-| TypeScript | Native types | `@types/js-yaml` |
-| YAML 1.2 compliance | ✅ Full | ⚠️ Mostly |
-| Security (CVEs) | None known | CVE-2025-64718 (fixed in 4.1.1) |
-| API style | `parse(str)`, `stringify(obj)` | `load(str)`, `dump(obj)` |
-| Bundle size | ~45KB | ~30KB |
-| Dependencies | 0 | 0 |
-
-## API Overview
-
-### Basic Parse & Stringify
-
-```typescript
-import { parse, stringify } from 'yaml';
-import { readFile, writeFile } from 'fs/promises';
-
-// Parse YAML file
-async function loadYaml<T>(filePath: string): Promise<T> {
-  const content = await readFile(filePath, 'utf-8');
-  return parse(content) as T;
-}
-
-// Stringify to YAML
-async function saveYaml(filePath: string, data: unknown): Promise<void> {
-  const yamlStr = stringify(data, {
-    indent: 2,
-    lineWidth: 120,
-  });
-  await writeFile(filePath, yamlStr, 'utf-8');
-}
-```
-
-### Pipeline Template Loading (replacing pipeline.py)
-
-```typescript
-import { parse } from 'yaml';
-import { readFile } from 'fs/promises';
-import { glob } from 'glob';
-import { z } from 'zod';
-
-// Schema (validated with Zod after YAML parse)
-const PipelineTemplateSchema = z.object({
-  name: z.string().min(1),
-  version: z.string().default('1.0'),
-  variables: z.array(z.object({
-    name: z.string().min(1),
-    type: z.enum(['string', 'number', 'boolean', 'list']).default('string'),
-    required: z.boolean().default(true),
-    default: z.unknown().optional(),
-    choices: z.array(z.unknown()).optional(),
-  })).default([]),
-  steps: z.array(z.object({
-    name: z.string().min(1),
-    observation_type: z.enum(['EVENT', 'SPAN', 'GENERATION']).default('EVENT'),
-    conditional: z.string().optional(),
-  })).min(1),
-});
-
-type PipelineTemplate = z.infer<typeof PipelineTemplateSchema>;
-
-async function loadPipelineTemplates(templateDir: string): Promise<Map<string, PipelineTemplate>> {
-  const templates = new Map<string, PipelineTemplate>();
-  const files = await glob('*.yaml', { cwd: templateDir, absolute: true });
-  
-  for (const file of files) {
-    const raw = parse(await readFile(file, 'utf-8'));
-    const template = PipelineTemplateSchema.parse(raw);
-    templates.set(template.name, template);
-  }
-  
-  return templates;
-}
-```
-
-### Comment-Preserving Round-Trip (unique to `yaml` package)
-
-```typescript
-import { parseDocument, stringify } from 'yaml';
-import { readFile, writeFile } from 'fs/promises';
-
-// Load, modify, save — preserving user comments
-async function updateTemplateVersion(filePath: string, newVersion: string): Promise<void> {
-  const content = await readFile(filePath, 'utf-8');
-  const doc = parseDocument(content);  // Preserves comments, anchors, formatting
-  
-  doc.set('version', newVersion);
-  
-  await writeFile(filePath, doc.toString(), 'utf-8');
-  // Original comments and formatting are preserved!
-}
-
-// Example input:
-// # Pipeline for session tracing
-// name: trace-session
-// version: "1.0"  # Bump this on changes
-// 
-// After update, the comment "# Bump this on changes" survives
-```
-
-### Session File Persistence
-
-```typescript
-import { parse, stringify } from 'yaml';
-import { readFile, writeFile } from 'fs/promises';
-
-interface SessionFile {
-  id: string;
-  created: string;
-  traces: { id: string; name: string; status: string }[];
-  charts: { id: string; outcome: string }[];
-  metadata: Record<string, unknown>;
-}
-
-async function saveSession(filePath: string, session: SessionFile): Promise<void> {
-  await writeFile(filePath, stringify(session, {
-    indent: 2,
-    lineWidth: 120,
-    sortMapEntries: false,  // Preserve insertion order
-  }), 'utf-8');
-}
-
-async function loadSession(filePath: string): Promise<SessionFile> {
-  const content = await readFile(filePath, 'utf-8');
-  return parse(content) as SessionFile;
-}
-```
-
-### Streaming for Large Files
-
-```typescript
-import { parseAllDocuments } from 'yaml';
-import { createReadStream } from 'fs';
-
-// Stream-parse a multi-document YAML file
-async function parseMultiDoc(filePath: string) {
-  const content = await readFile(filePath, 'utf-8');
-  const docs = parseAllDocuments(content);
-  
-  for (const doc of docs) {
-    if (doc.errors.length > 0) {
-      console.error(`Parse errors in ${filePath}:`, doc.errors);
-      continue;
-    }
-    yield doc.toJSON();
-  }
-}
-```
-
-### Config File Loading
-
-```typescript
-import { parse } from 'yaml';
-import { readFile } from 'fs/promises';
-import { existsSync } from 'fs';
-
-// Load coaia.json or coaia.yaml config
-async function loadConfigFile(configPath: string): Promise<Record<string, unknown>> {
-  if (!existsSync(configPath)) return {};
-  
-  const content = await readFile(configPath, 'utf-8');
-  
-  if (configPath.endsWith('.yaml') || configPath.endsWith('.yml')) {
-    return parse(content) ?? {};
-  }
-  if (configPath.endsWith('.json')) {
-    return JSON.parse(content);
-  }
-  
-  // Try YAML first (superset of JSON)
-  try {
-    return parse(content) ?? {};
-  } catch {
-    return JSON.parse(content);
-  }
-}
-```
-
-## Integration Plan
-
-1. **Core utility:** `src/yaml.ts` — typed `loadYaml<T>()` and `saveYaml()` wrappers
-2. **Pipeline templates:** `src/pipeline/template-loader.ts` — YAML template discovery + Zod validation
-3. **Session files:** `src/session/file.ts` — YAML session persistence
-4. **Config loading:** `src/config.ts` — support `.yaml` config alongside `.json`
-5. **Round-trip editing:** Use `parseDocument()` for user-facing template modifications
-6. **Multi-doc:** Support `---` separated YAML documents for batch operations
-
-## Why Not js-yaml?
-
-1. **Comment preservation**: Pipeline templates are human-authored; losing comments on round-trip is unacceptable
-2. **Security**: CVE-2025-64718 (prototype pollution) was a recent concern; `yaml` has a clean record
-3. **YAML 1.2**: Full compliance matters for interop with other tools
-4. **Streaming**: Future-proofing for large narrative JSONL files converted to/from YAML
-5. **TypeScript**: Native types without DefinitelyTyped dependency
-
-The ~10% parse speed advantage of js-yaml is irrelevant for config/template files (sub-millisecond either way).
-
-## Version & Ecosystem
-
-| Metric | Value |
-|--------|-------|
-| Current version | 2.6.x (2026) |
-| Weekly downloads | ~80M |
-| TypeScript | Native types |
-| Dependencies | 0 |
-| YAML spec | 1.2 compliant |
-| Comment round-trip | ✅ Full support |
-| Streaming | ✅ Parse & stringify |
-| Node.js compat | ≥14 (we target ≥20) |
-| License | ISC |
-
-## References
-
-- npm: https://www.npmjs.com/package/yaml
-- GitHub: https://github.com/eemeli/yaml
-- js-yaml: https://www.npmjs.com/package/js-yaml
-- Comparison: https://npm-compare.com/js-yaml,yaml
-- Performance: https://github.com/eemeli/yaml/discussions/358
-- CVE-2025-64718: https://www.cvedetails.com/cve/CVE-2025-64718/

package/articles/technical/zod-runtime-validation.md

@@ -1,212 +0,0 @@
-# Zod Runtime Validation: Technical Assessment for CoAiA.js
-
-> Package selection brief — TypeScript-first schema validation replacing coaia-narrative's custom 181-line validation.ts
-
-## Summary & Recommendation
-
-**Use `zod` v4.x** as the unified validation layer for all coaiajs modules. Zod replaces coaia-narrative's custom `validation.ts` (181 lines of hand-rolled recursive validation) with a standard, composable, type-inferring schema library. The MCP SDK already requires Zod as a peer dependency for tool argument schemas — using it everywhere eliminates dual validation code.
-
-**Pin:** `"zod": "^4.0.0"` (v4.3.6 stable, required by `@modelcontextprotocol/sdk`)
-
-## What We're Replacing
-
-coaia-narrative has a custom `validation.ts` implementing recursive schema validation:
-
-```typescript
-// coaia-narrative/src/validation.ts — 181 lines of custom validation
-type ValidationType = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'date' | 'enum';
-
-interface ValidationRule {
-  type: ValidationType;
-  required?: boolean;
-  minLength?: number;
-  maxLength?: number;
-  pattern?: RegExp;
-  minValue?: number;
-  maxValue?: number;
-  enumValues?: (string | number)[];
-  items?: ValidationRule;         // array items schema
-  properties?: Record<string, ValidationRule>;  // object properties
-}
-
-export function validate(args: any, schema: ValidationSchema): { valid: boolean; error?: string }
-```
-
-Pre-built schemas: `stringArray()`, `entityArray()`, `relationArray()`, `isoDate()`, `nonEmptyString()`.
-
-This works but: no type inference, no composition, no transform/coerce, no JSON Schema export, and every new validation type requires manual code.
-
-## Options Compared
-
-| Feature | Zod v4 | Custom validation.ts | io-ts | Yup |
-|---------|--------|---------------------|-------|-----|
-| Type inference | ✅ Automatic `z.infer<>` | ❌ Manual types | ✅ (verbose) | ⚠️ Partial |
-| Schema composition | ✅ `.merge()`, `.extend()`, `.pick()` | ❌ Manual nesting | ✅ | ✅ |
-| MCP SDK compat | ✅ Required peer dep | ❌ N/A | ❌ | ❌ |
-| JSON Schema export | ✅ `toJSONSchema()` | ❌ N/A | ❌ | ❌ |
-| Transform/coerce | ✅ `.transform()`, `.coerce` | ❌ N/A | ❌ | ✅ |
-| Error messages | ✅ Structured `ZodError` | ⚠️ Single string | ⚠️ Verbose | ✅ |
-| Bundle size | ~2KB gzip (core) | ~3KB | ~15KB | ~12KB |
-| Weekly downloads | ~100M+ | N/A | ~8M | ~15M |
-| Performance (v4) | 14x faster strings, 7x faster arrays vs v3 | Adequate | Slower | Slower |
-
-## API Overview
-
-### Replacing Custom Schemas
-
-```typescript
-import { z } from 'zod';
-
-// Replaces: ValidationSchemas.nonEmptyString()
-const NonEmptyString = z.string().min(1);
-
-// Replaces: ValidationSchemas.isoDate()
-const IsoDate = z.string().datetime();
-
-// Replaces: ValidationSchemas.stringArray(minLength)
-const StringArray = (min = 0) => z.array(z.string()).min(min);
-
-// Replaces: ValidationSchemas.entityArray()
-const Entity = z.object({
-  name: z.string().min(1),
-  entityType: z.string().min(1),
-  observations: z.array(z.string()).default([]),
-});
-const EntityArray = z.array(Entity).min(1);
-
-// Replaces: ValidationSchemas.relationArray()
-const Relation = z.object({
-  from: z.string().min(1),
-  to: z.string().min(1),
-  relationType: z.string().min(1),
-});
-const RelationArray = z.array(Relation);
-```
-
-### Structural Tension Chart Schema
-
-```typescript
-const ChartSchema = z.object({
-  id: z.string().min(1),
-  desiredOutcome: z.string().min(1),
-  currentReality: z.string().min(1),
-  dueDate: z.string().datetime().optional(),
-  actionSteps: z.array(z.object({
-    title: z.string().min(1),
-    status: z.enum(['pending', 'in_progress', 'done', 'blocked']),
-    currentReality: z.string().optional(),
-  })).default([]),
-  createdAt: z.string().datetime(),
-  updatedAt: z.string().datetime(),
-});
-
-type Chart = z.infer<typeof ChartSchema>;  // TypeScript type auto-generated
-```
-
-### MCP Tool Argument Validation
-
-```typescript
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { z } from 'zod';
-
-const server = new McpServer({ name: 'coaiajs', version: '1.0.0' });
-
-// Zod schemas ARE the MCP tool input schemas — zero duplication
-server.tool(
-  'create_chart',
-  'Create a structural tension chart',
-  {
-    desiredOutcome: z.string().describe('What you want to CREATE'),
-    currentReality: z.string().describe('Factual assessment of current state'),
-    dueDate: z.string().datetime().optional().describe('Target date (ISO 8601)'),
-    actionSteps: z.array(z.string()).optional().describe('Initial action steps'),
-  },
-  async ({ desiredOutcome, currentReality, dueDate, actionSteps }) => {
-    // Arguments are already validated and typed
-    const chart = await createChart({ desiredOutcome, currentReality, dueDate, actionSteps });
-    return { content: [{ type: 'text', text: JSON.stringify(chart) }] };
-  }
-);
-```
-
-### Pipeline Template Validation
-
-```typescript
-// Replaces coaiapy's pipeline.py validate_variables()
-const PipelineVariable = z.object({
-  name: z.string().min(1),
-  type: z.enum(['string', 'number', 'boolean', 'list']).default('string'),
-  required: z.boolean().default(true),
-  default: z.unknown().optional(),
-  choices: z.array(z.unknown()).optional(),
-});
-
-const PipelineTemplate = z.object({
-  name: z.string().min(1),
-  version: z.string().default('1.0'),
-  variables: z.array(PipelineVariable).default([]),
-  steps: z.array(z.object({
-    name: z.string().min(1),
-    observation_type: z.enum(['EVENT', 'SPAN', 'GENERATION']).default('EVENT'),
-    conditional: z.string().optional(),
-  })).min(1),
-});
-
-// Validate and get typed result
-function loadTemplate(raw: unknown): PipelineTemplate {
-  return PipelineTemplate.parse(raw);  // throws ZodError on invalid
-}
-```
-
-### Error Handling
-
-```typescript
-import { z } from 'zod';
-
-function validateSafe<T>(schema: z.ZodSchema<T>, data: unknown): { valid: true; data: T } | { valid: false; error: string } {
-  const result = schema.safeParse(data);
-  if (result.success) {
-    return { valid: true, data: result.data };
-  }
-  // Structured error messages
-  const messages = result.error.issues.map(i => `${i.path.join('.')}: ${i.message}`);
-  return { valid: false, error: messages.join('; ') };
-}
-```
-
-## Integration Plan
-
-1. **Shared schemas:** `src/schemas/` directory with reusable Zod schemas
-   - `chart.ts` — ChartSchema, ActionStepSchema
-   - `entity.ts` — Entity, Relation schemas (replaces validation.ts)
-   - `pipeline.ts` — PipelineTemplate, PipelineVariable
-   - `session.ts` — Session, Trace schemas
-2. **MCP tools:** Direct Zod schemas in tool definitions (no separate validation layer)
-3. **Config validation:** Zod for config file/env var validation at startup
-4. **JSON Schema export:** `toJSONSchema()` for documentation and interop
-5. **Migration:** Delete coaia-narrative's `validation.ts`, import from `@coaiajs/schemas`
-
-### @zod/mini for Future Frontend
-
-If coaiajs adds a web UI, use `@zod/mini` (~1.9KB) for client-side validation with the same schemas.
-
-## Version & Ecosystem
-
-| Metric | Value |
-|--------|-------|
-| Current version | 4.3.6 (Jan 2026) |
-| Weekly downloads | ~100M+ |
-| TypeScript | First-class, type inference is the core value |
-| Bundle size | ~2KB gzip (core), ~1.9KB (@zod/mini) |
-| MCP SDK | Required peer dependency |
-| JSON Schema | `toJSONSchema()` built-in |
-| Node.js compat | Any (zero native deps) |
-| License | MIT |
-
-## References
-
-- npm: https://www.npmjs.com/package/zod
-- GitHub: https://github.com/colinhacks/zod
-- v4 announcement: https://www.infoq.com/news/2025/08/zod-v4-available/
-- What's new in v4: https://basicutils.com/learn/zod/whats-new-in-zod-v4
-- MCP SDK peer dep: https://www.npmjs.com/package/@modelcontextprotocol/sdk

package/coaiajs-langfuse-claude-plugin/.claude-plugin/marketplace.json

@@ -1,16 +0,0 @@
-{
-  "name": "coaiajs-marketplace",
-  "owner": { "name": "Guillaume Isabelle", "email": "jgi@jgwill.com", "url": "https://github.com/jgwill" },
-  "metadata": { "description": "CoAIA Claude Code plugins", "version": "0.3.0" },
-  "plugins": [
-    {
-      "name": "coaiajs-langfuse",
-      "source": "./",
-      "description": "CoAIA unified MCP — 64+ tools (structural tension, narrative graph, PDE, planning, Redis tash/fetch, Langfuse tracing).",
-      "version": "0.3.0",
-      "author": { "name": "Guillaume Isabelle", "url": "https://github.com/jgwill" },
-      "license": "MIT",
-      "keywords": ["coaia", "mcp", "structural-tension", "narrative", "pde", "planning", "langfuse"]
-    }
-  ]
-}

package/coaiajs-langfuse-claude-plugin/.claude-plugin/plugin.json

@@ -1,10 +0,0 @@
-{
-  "name": "coaiajs-langfuse",
-  "description": "CoAIA unified MCP for Claude Code — 64+ tools across structural-tension charts, narrative knowledge graph, Prompt Decomposition Engine (PDE), action planning, Redis tash/fetch, and Langfuse tracing. Bundles the published `coaiajs` npm package's `coaiajs-mcp` server via npx.",
-  "version": "0.3.0",
-  "author": { "name": "Guillaume Isabelle", "email": "jgi@jgwill.com", "url": "https://github.com/jgwill" },
-  "homepage": "https://github.com/jgwill/coaiajs/tree/master/coaiajs-langfuse-claude-plugin",
-  "repository": "https://github.com/jgwill/coaiajs",
-  "license": "MIT",
-  "keywords": ["coaia", "mcp", "structural-tension", "narrative", "pde", "planning", "langfuse"]
-}

package/coaiajs-langfuse-claude-plugin/.mcp.json

@@ -1,8 +0,0 @@
-{
-  "mcpServers": {
-    "coaia": {
-      "command": "npx",
-      "args": ["-y", "--package=coaiajs", "coaiajs-mcp"]
-    }
-  }
-}

package/coaiajs-langfuse-claude-plugin/README.md

@@ -1,60 +0,0 @@
-# coaiajs-langfuse — Claude Code Plugin
-
-A Claude Code plugin that registers the `coaiajs-mcp` server — 64+ tools, 3 prompts, and 3 resources — as an MCP server inside Claude Code. It does not bundle its own copy of the server; it launches the published `coaiajs` npm package on demand via `npx`:
-
-```
-npx -y --package=coaiajs coaiajs-mcp
-```
-
-That command is declared in `.mcp.json` at the root of this plugin, which Claude Code auto-loads on install.
-
-## Install
-
-From a marketplace source (GitHub):
-
-```
-claude plugin marketplace add https://github.com/jgwill/coaiajs
-claude plugin install coaiajs-langfuse@coaiajs-marketplace
-```
-
-Or from a local checkout:
-
-```
-claude plugin marketplace add /a/src/coaiajs/coaiajs-langfuse-claude-plugin
-claude plugin install coaiajs-langfuse@coaiajs-marketplace
-```
-
-Confirm it registered:
-
-```
-claude plugin list
-```
-
-## Tool families
-
-- **Structural-tension charts** — desired outcome / current reality / action steps, the core CoAIA data model.
-- **Narrative knowledge graph** — entities, relations, and graph queries (from coaia-narrative).
-- **PDE (Prompt Decomposition Engine)** — decompose complex prompts into actionable intent maps.
-- **Action planning** — structural tension plans and action-step management (from coaia-planning).
-- **Redis tash/fetch** — SET/GET shorthand against a Redis store.
-- **Langfuse tracing** — trace, span, and observation tools for Langfuse-backed observability.
-
-## Environment variables
-
-The server boots with no configuration — it connects to nothing at import time. Individual tool families activate only when their own credentials are present in the environment Claude Code runs in:
-
-| Variable | Used by |
-| --- | --- |
-| `REDIS_URL` | tash/fetch |
-| `OPENAI_API_KEY` | LLM-backed tools |
-| `LANGFUSE_PUBLIC_KEY` | Langfuse tracing |
-| `LANGFUSE_SECRET_KEY` | Langfuse tracing |
-| `LANGFUSE_BASE_URL` | Langfuse tracing |
-| `GITHUB_TOKEN` | GitHub-integration tools |
-| AWS credentials (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, etc.) | Polly audio tools |
-
-None of these are set by the plugin itself — they are inherited from whatever shell/environment Claude Code is launched in. Set them in your shell profile, `.env`, or however you normally manage secrets for this machine.
-
-## Versioning
-
-This plugin tracks the published npm `coaiajs` package rather than vendoring source. `.mcp.json` calls `npx -y --package=coaiajs coaiajs-mcp`, which always resolves the latest published version at launch time. To pin a specific version, edit `.mcp.json` and change `--package=coaiajs` to `--package=coaiajs@<version>` (e.g. `coaiajs@0.3.0`).