coaia-visualizer 1.5.10 → 1.6.1

package/skill.ts

@@ -0,0 +1,385 @@
+import {
+  lstatSync,
+  mkdirSync,
+  readlinkSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync,
+} from 'fs';
+import { homedir } from 'os';
+import { dirname, relative as relativePath, resolve } from 'path';
+import { createInterface } from 'readline/promises';
+import type minimist from 'minimist';
+
+type EmbeddedSkillFile = {
+  relativePath: string;
+  content: string;
+};
+
+const SKILL_NAME = 'coaia-visualizer';
+
+const COAIA_VISUALIZER_SKILL_MD = [
+  '---',
+  'name: coaia-visualizer',
+  'description: Use coaia-visualizer to launch, inspect, edit, and expose COAIA structural tension chart JSONL files through a web UI, REST API, and optional MCP bridge.',
+  'license: MIT',
+  'compatibility: Requires the coaia-visualizer package. Optional MCP bridge uses coaia-visualizer-mcp.',
+  'metadata:',
+  '  author: Guillaume D. Isabelle',
+  '  version: "1.0.0"',
+  'allowed-tools: Bash(coaia-visualizer:*), Bash(coaia-visualizer-mcp:*)',
+  '---',
+  '',
+  '# coaia-visualizer',
+  '',
+  '`coaia-visualizer` is the visual and API surface for COAIA Structural Tension Chart JSONL files. Use it when an LLM or human needs to inspect chart hierarchy, current reality, action-step telescoping, narrative beats, and chart progress through the web UI or the visualizer MCP bridge.',
+  '',
+  '## Status',
+  '',
+  '!`coaia-visualizer --help 2>/dev/null || echo "Not installed: npm install -g coaia-visualizer"`',
+  '',
+  '## Relationship To coaia-narrative',
+  '',
+  '- `coaia-narrative` is the primary chart-memory authoring MCP and CLI.',
+  '- `coaia-visualizer` reads the same JSONL format and presents it as an interactive UI.',
+  '- `coaia-visualizer-mcp` connects an LLM to a running visualizer REST API, not directly to the file.',
+  '- Prefer `coaia-narrative` MCP for pure memory creation. Prefer `coaia-visualizer` when the UI/API context matters.',
+  '',
+  '## Launch The UI',
+  '',
+  '```bash',
+  'coaia-visualizer -M ./memory.jsonl --no-open',
+  'coaia-visualizer --docker -M ./memory.jsonl --port 4321',
+  'coaia-visualizer -M ./memory.jsonl --live --poll-interval 2000',
+  '```',
+  '',
+  'The memory file must exist. The CLI sets `COAIAV_MEMORY_PATH` and starts the Next.js visualizer against that file.',
+  '',
+  '## MCP Bridge Setup',
+  '',
+  'The visualizer MCP requires a running visualizer API and a token shared through `COAIAN_API_TOKEN`.',
+  '',
+  '```bash',
+  'export COAIAN_API_TOKEN="$(openssl rand -hex 32)"',
+  'coaia-visualizer -M ./memory.jsonl --port 4321 --no-open',
+  '```',
+  '',
+  'Then configure the MCP client:',
+  '',
+  '```json',
+  '{',
+  '  "mcpServers": {',
+  '    "coaia-visualizer": {',
+  '      "command": "npx",',
+  '      "args": ["-y", "coaia-visualizer-mcp"],',
+  '      "env": {',
+  '        "COAIAN_API_TOKEN": "the-same-token",',
+  '        "COAIAV_API_URL": "http://localhost:4321"',
+  '      }',
+  '    }',
+  '  }',
+  '}',
+  '```',
+  '',
+  'If no token is provided to the visualizer, it generates a temporary one and logs it on first API access. For repeatable agent work, set `COAIAN_API_TOKEN` explicitly.',
+  '',
+  '## Tool Map',
+  '',
+  '| MCP Tool | Use |',
+  '|---|---|',
+  '| `list_charts` | Start here; read chart hierarchy from the visualizer API |',
+  '| `get_chart` | Inspect one chart with outcome, reality, actions, metadata |',
+  '| `create_chart` | Create a chart through the visualizer API |',
+  '| `update_chart` | Update desired outcome, current reality, or due date |',
+  '| `add_action_step` | Add a new telescoped action chart with explicit current reality |',
+  '| `update_action_step` | Change an action description |',
+  '| `mark_action_complete` | Mark an action complete |',
+  '| `update_action_progress` | Add progress without completion |',
+  '| `update_current_reality` | Add current-reality observations |',
+  '| `toggle_action_completion` | Toggle action completion state |',
+  '| `delete_action_step` | Remove an action step |',
+  '| `create_telescoped_chart` | Convert an existing action into a sub-chart |',
+  '| `delete_chart` | Delete a chart and its descendants |',
+  '| `search_charts` | Search by text and filters |',
+  '| `get_chart_progress` | Calculate chart progress |',
+  '',
+  '## Structural-Tension Discipline',
+  '',
+  '- Do not treat charts as generic task boards.',
+  '- Do not default current reality to "ready to begin."',
+  '- Action steps are strategic secondary choices, and visualizer action creation should include an honest current reality.',
+  '- Use `create_telescoped_chart` only for an existing action. Use `add_action_step` for a new action.',
+  '',
+  '## References',
+  '',
+  '- `references/visualizer-workflow.md` for UI and CLI launch patterns.',
+  '- `references/mcp-bridge.md` for API/MCP wiring.',
+  '- `references/structural-tension-foundation.md` for shared methodology.',
+  '- `references/install-and-environment.md` for install and environment notes.',
+].join('\n') + '\n';
+
+const VISUALIZER_WORKFLOW_MD = [
+  '# Visualizer Workflow',
+  '',
+  'Use `coaia-visualizer` when the work benefits from seeing the chart hierarchy or when an agent needs REST/API access to the visualizer runtime.',
+  '',
+  'Common launch forms:',
+  '',
+  '```bash',
+  'coaia-visualizer -M ./memory.jsonl',
+  'coaia-visualizer -M ./memory.jsonl --port 4321 --no-open',
+  'coaia-visualizer --docker -M ./memory.jsonl --port 4321',
+  'coaia-visualizer -M ./memory.jsonl --live --poll-interval 2000',
+  '```',
+  '',
+  'The UI reads structural tension charts, current realities, action steps, narrative beats, and relations from JSONL. It can also edit charts through API routes when running as the app server.',
+].join('\n') + '\n';
+
+const MCP_BRIDGE_MD = [
+  '# MCP Bridge',
+  '',
+  '`coaia-visualizer-mcp` is a stdio MCP server that talks to the visualizer REST API. It does not parse the JSONL file by itself.',
+  '',
+  'Required runtime pieces:',
+  '',
+  '1. A running visualizer app.',
+  '2. `COAIAN_API_TOKEN` set in the visualizer process.',
+  '3. The same `COAIAN_API_TOKEN` set for the MCP process.',
+  '4. `COAIAV_API_URL` pointing at the running visualizer, usually `http://localhost:4321`.',
+  '',
+  'MCP client config:',
+  '',
+  '```json',
+  '{',
+  '  "mcpServers": {',
+  '    "coaia-visualizer": {',
+  '      "command": "npx",',
+  '      "args": ["-y", "coaia-visualizer-mcp"],',
+  '      "env": {',
+  '        "COAIAN_API_TOKEN": "your-token",',
+  '        "COAIAV_API_URL": "http://localhost:4321"',
+  '      }',
+  '    }',
+  '  }',
+  '}',
+  '```',
+  '',
+  'Use `list_charts` before mutation tools so the agent has current chart IDs and hierarchy.',
+].join('\n') + '\n';
+
+const STRUCTURAL_TENSION_FOUNDATION_MD = [
+  '# Structural Tension Foundation',
+  '',
+  'The visualizer presents the same methodology used by `coaia-narrative`.',
+  '',
+  'Core rules:',
+  '',
+  '- Desired Outcome is what is being created.',
+  '- Current Reality is the factual present state in relation to that outcome.',
+  '- Structural tension is active disequilibrium, not a gap to fill.',
+  '- Action steps are strategic secondary choices, not independent to-do items.',
+  '- Each action step can become a telescoped chart with its own current reality.',
+  '',
+  'Current reality must not be invented. Avoid "ready to begin", "prepared to start", or motivational filler. Use concrete present facts.',
+].join('\n') + '\n';
+
+const INSTALL_AND_ENVIRONMENT_MD = [
+  '# Install And Environment',
+  '',
+  'Install:',
+  '',
+  '```bash',
+  'npm install -g coaia-visualizer',
+  'coaia-visualizer skill show',
+  'coaia-visualizer skill install --yes',
+  '```',
+  '',
+  'Important environment variables:',
+  '',
+  '| Variable | Purpose |',
+  '|---|---|',
+  '| `COAIAN_MF` | Default memory file path |',
+  '| `COAIAV_PORT` | Default server port |',
+  '| `COAIAV_LIVE` | Enable live mode when `true` |',
+  '| `COAIAV_POLL_INTERVAL` | Live polling interval in milliseconds |',
+  '| `COAIAV_AUTO_PLAY` | Enable audio autoplay when `true` |',
+  '| `COAIAV_AUDIO_DIR` | Audio directory path |',
+  '| `COAIAN_API_TOKEN` | Bearer token for REST API and MCP bridge |',
+  '| `COAIAV_API_URL` | MCP bridge target API URL |',
+  '',
+  '`coaia-visualizer skill install` writes `.agents/skills/coaia-visualizer`. Add `--global` for `~/.agents/skills/coaia-visualizer`. Add `--yes` to create the matching `.claude/skills/coaia-visualizer` symlink.',
+].join('\n') + '\n';
+
+const EMBEDDED_SKILL_FILES: EmbeddedSkillFile[] = [
+  { relativePath: 'SKILL.md', content: COAIA_VISUALIZER_SKILL_MD },
+  { relativePath: 'references/visualizer-workflow.md', content: VISUALIZER_WORKFLOW_MD },
+  { relativePath: 'references/mcp-bridge.md', content: MCP_BRIDGE_MD },
+  { relativePath: 'references/structural-tension-foundation.md', content: STRUCTURAL_TENSION_FOUNDATION_MD },
+  { relativePath: 'references/install-and-environment.md', content: INSTALL_AND_ENVIRONMENT_MD },
+];
+
+function getSkillInstallDir(globalInstall: boolean): string {
+  return globalInstall
+    ? resolve(homedir(), '.agents', 'skills', SKILL_NAME)
+    : resolve(process.cwd(), '.agents', 'skills', SKILL_NAME);
+}
+
+function getClaudeSkillLinkPath(globalInstall: boolean): string {
+  return globalInstall
+    ? resolve(homedir(), '.claude', 'skills', SKILL_NAME)
+    : resolve(process.cwd(), '.claude', 'skills', SKILL_NAME);
+}
+
+function pathExists(pathName: string): boolean {
+  try {
+    lstatSync(pathName);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function removePath(pathName: string): void {
+  const stat = lstatSync(pathName);
+  if (stat.isDirectory() && !stat.isSymbolicLink()) {
+    rmSync(pathName, { recursive: true, force: true });
+  } else {
+    unlinkSync(pathName);
+  }
+}
+
+function writeEmbeddedSkill(targetDir: string, force: boolean): void {
+  if (pathExists(targetDir)) {
+    if (!force) {
+      throw new Error(`Skill already exists: ${targetDir} (use --force to replace it)`);
+    }
+    removePath(targetDir);
+  }
+
+  mkdirSync(targetDir, { recursive: true });
+  for (const file of EMBEDDED_SKILL_FILES) {
+    const destination = resolve(targetDir, file.relativePath);
+    mkdirSync(dirname(destination), { recursive: true });
+    writeFileSync(destination, file.content, 'utf-8');
+  }
+}
+
+function ensureClaudeSymlink(linkPath: string, targetDir: string, force: boolean): boolean {
+  const parentDir = dirname(linkPath);
+  if (pathExists(parentDir)) {
+    const resolvedTargetParent = realpathSync(dirname(targetDir));
+    const resolvedLinkParent = realpathSync(parentDir);
+
+    if (resolvedTargetParent === resolvedLinkParent) {
+      return false;
+    }
+  }
+
+  const linkTarget = relativePath(parentDir, targetDir) || '.';
+  mkdirSync(parentDir, { recursive: true });
+
+  if (pathExists(linkPath)) {
+    const stat = lstatSync(linkPath);
+    if (stat.isSymbolicLink() && readlinkSync(linkPath) === linkTarget) {
+      return true;
+    }
+    if (!force) {
+      throw new Error(`Claude skill path already exists: ${linkPath} (use --force to replace it)`);
+    }
+    removePath(linkPath);
+  }
+
+  symlinkSync(linkTarget, linkPath, 'dir');
+  return true;
+}
+
+async function shouldCreateClaudeSymlink(linkPath: string, autoYes: boolean): Promise<boolean> {
+  if (autoYes) {
+    return true;
+  }
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    console.log(`Tip: create a Claude symlink manually at ${linkPath}`);
+    return false;
+  }
+
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    const answer = await rl.question(`Create a symlink in ${linkPath}? [y/N] `);
+    const normalized = answer.trim().toLowerCase();
+    return normalized === 'y' || normalized === 'yes';
+  } finally {
+    rl.close();
+  }
+}
+
+async function installSkill(globalInstall: boolean, force: boolean, autoYes: boolean): Promise<void> {
+  const installDir = getSkillInstallDir(globalInstall);
+  writeEmbeddedSkill(installDir, force);
+  console.log(`Installed coaia-visualizer skill to ${installDir}`);
+
+  const claudeLinkPath = getClaudeSkillLinkPath(globalInstall);
+  if (!(await shouldCreateClaudeSymlink(claudeLinkPath, autoYes))) {
+    return;
+  }
+
+  const linked = ensureClaudeSymlink(claudeLinkPath, installDir, force);
+  if (linked) {
+    console.log(`Linked Claude skill at ${claudeLinkPath}`);
+  } else {
+    console.log(`Claude already sees the skill via ${dirname(claudeLinkPath)}`);
+  }
+}
+
+export function showCoaiaVisualizerSkill(): void {
+  console.log('coaia-visualizer Skill (embedded)');
+  console.log('');
+  process.stdout.write(COAIA_VISUALIZER_SKILL_MD);
+}
+
+export function showSkillCommandHelp(): void {
+  console.log([
+    'Usage: coaia-visualizer skill <show|install|help> [options]',
+    '',
+    'Commands:',
+    '  show                Print the packaged coaia-visualizer skill',
+    '  install             Install into ./.agents/skills/coaia-visualizer',
+    '  help                Show this help',
+    '',
+    'Options for install:',
+    '  --global            Install into ~/.agents/skills/coaia-visualizer',
+    '  --yes, -y           Also create the .claude/skills/coaia-visualizer symlink',
+    '  --force, -f         Replace existing install or symlink',
+  ].join('\n'));
+}
+
+export async function handleSkillCommand(args: minimist.ParsedArgs): Promise<void> {
+  const subcommand = String(args._[1] || '');
+
+  if (args.help || args.h || subcommand === 'help') {
+    showSkillCommandHelp();
+    return;
+  }
+
+  if (!subcommand) {
+    showSkillCommandHelp();
+    return;
+  }
+
+  if (subcommand === 'show') {
+    showCoaiaVisualizerSkill();
+    return;
+  }
+
+  if (subcommand === 'install') {
+    await installSkill(Boolean(args.global), Boolean(args.force || args.f), Boolean(args.yes || args.y));
+    return;
+  }
+
+  throw new Error(`Unknown skill command: ${subcommand}`);
+}

package/.coaia/jgwill-coaia-visualizer.jsonl

@@ -1,6 +0,0 @@
-{"type":"entity","name":"chart_1770523106343_chart","entityType":"structural_tension_chart","observations":["Chart created for jgwill/coaia-visualizer on 2026-02-08T03:58:26.343Z"],"metadata":{"chartId":"chart_1770523106343","repository":"jgwill/coaia-visualizer","level":0,"createdAt":"2026-02-08T03:58:26.343Z","updatedAt":"2026-02-08T03:58:26.343Z"}}
-{"type":"entity","name":"chart_1770523106343_desired_outcome","entityType":"desired_outcome","observations":["Successful development and collaboration on jgwill/coaia-visualizer"],"metadata":{"chartId":"chart_1770523106343","createdAt":"2026-02-08T03:58:26.343Z","updatedAt":"2026-02-08T03:58:26.343Z"}}
-{"type":"entity","name":"chart_1770523106343_current_reality","entityType":"current_reality","observations":["Repository initialized with STC bot integration","[2026-02-08T03:58:26.404Z] @stcissue triggered: Issue #8 - LIVE_MODE_DESIGN.md (issues.opened)","[2026-02-08T04:38:12.548Z] @stcissue triggered: Issue #8 - Live Narrative Witness Mode (issues.edited)","[2026-02-12T04:05:37.474Z] @stcissue triggered: Issue #9 - file watching issue (issues.opened)","[2026-02-18T19:29:54.244Z] @stcissue triggered: Issue #10 - Containerization (issues.opened)"],"metadata":{"chartId":"chart_1770523106343","createdAt":"2026-02-08T03:58:26.343Z","updatedAt":"2026-02-18T19:29:54.244Z"}}
-{"type":"relation","from":"chart_1770523106343_chart","to":"chart_1770523106343_desired_outcome","relationType":"contains","metadata":{"createdAt":"2026-02-08T03:58:26.343Z"}}
-{"type":"relation","from":"chart_1770523106343_chart","to":"chart_1770523106343_current_reality","relationType":"contains","metadata":{"createdAt":"2026-02-08T03:58:26.343Z"}}
-{"type":"relation","from":"chart_1770523106343_current_reality","to":"chart_1770523106343_desired_outcome","relationType":"creates_tension_with","metadata":{"createdAt":"2026-02-08T03:58:26.343Z"}}

package/test-run.log

@@ -1,101 +0,0 @@
-=========================================
-COAIA Visualizer MCP Test Environment
-=========================================
-
-Working directory: /workspace/repos/jgwill/coaia-visualizer-feat-4
-
-⚠ Warning: No ANTHROPIC_API_KEY or GOOGLE_API_KEY found
-  Tests will use direct HTTP calls instead of CLI clients
-
-Cleaning up previous test results...
-Building Docker images...
-time="2026-01-16T09:09:43-05:00" level=warning msg="The \"ANTHROPIC_API_KEY\" variable is not set. Defaulting to a blank string."
-time="2026-01-16T09:09:43-05:00" level=warning msg="The \"GOOGLE_API_KEY\" variable is not set. Defaulting to a blank string."
-#0 building with "default" instance using docker driver
-
-#1 [visualizer-app internal] load build definition from Dockerfile.app
-#1 transferring dockerfile: 1.09kB done
-#1 DONE 0.0s
-
-#2 [visualizer-app internal] load metadata for docker.io/library/node:20-alpine
-#2 DONE 0.2s
-
-#3 [visualizer-app internal] load .dockerignore
-#3 transferring context: 121B done
-#3 DONE 0.0s
-
-#4 [visualizer-app builder 1/6] FROM docker.io/library/node:20-alpine@sha256:3960ed74dfe320a67bf8da9555b6bade25ebda2b22b6081d2f60fd7d5d430e9c
-#4 DONE 0.0s
-
-#5 [visualizer-app internal] load build context
-#5 transferring context: 82.91kB 0.2s done
-#5 DONE 0.2s
-
-#6 [visualizer-app builder 2/6] WORKDIR /app
-#6 CACHED
-
-#7 [visualizer-app runner  3/13] RUN npm install -g pnpm@latest
-#7 CACHED
-
-#8 [visualizer-app builder 3/6] COPY package.json pnpm-lock.yaml ./
-#8 CACHED
-
-#9 [visualizer-app runner  4/13] COPY package.json pnpm-lock.yaml ./
-#9 CACHED
-
-#10 [visualizer-app builder 4/6] RUN npm install -g pnpm@latest &&   pnpm install --frozen-lockfile
-#10 4.059 
-#10 4.059 added 1 package in 3s
-#10 4.059 
-#10 4.060 1 package is looking for funding
-#10 4.060   run `npm fund` for details
-#10 4.064 npm notice
-#10 4.064 npm notice New major version of npm available! 10.8.2 -> 11.7.0
-#10 4.064 npm notice Changelog: https://github.com/npm/cli/releases/tag/v11.7.0
-#10 4.064 npm notice To update run: npm install -g npm@11.7.0
-#10 4.064 npm notice
-#10 5.648 Lockfile is up to date, resolution step is skipped
-#10 5.842 Progress: resolved 1, reused 0, downloaded 0, added 0
-#10 6.386 Packages: +296
-#10 6.386 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-#10 6.846 Progress: resolved 296, reused 0, downloaded 0, added 0
-#10 9.510 Progress: resolved 296, reused 0, downloaded 1, added 0
-#10 ...
-
-#11 [visualizer-app runner  5/13] RUN pnpm install --prod --frozen-lockfile --ignore-scripts
-#11 1.835 Lockfile is up to date, resolution step is skipped
-#11 1.898 Progress: resolved 1, reused 0, downloaded 0, added 0
-#11 2.020 Packages: +267
-#11 2.020 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-#11 2.966 Progress: resolved 267, reused 0, downloaded 27, added 20
-#11 3.978 Progress: resolved 267, reused 0, downloaded 142, added 56
-#11 5.006 Progress: resolved 267, reused 0, downloaded 218, added 101
-#11 6.017 Progress: resolved 267, reused 0, downloaded 258, added 221
-#11 7.020 Progress: resolved 267, reused 0, downloaded 260, added 259
-#11 8.018 Progress: resolved 267, reused 0, downloaded 261, added 261
-#11 ...
-
-#10 [visualizer-app builder 4/6] RUN npm install -g pnpm@latest &&   pnpm install --frozen-lockfile
-#10 10.56 Progress: resolved 296, reused 0, downloaded 100, added 95
-#10 11.57 Progress: resolved 296, reused 0, downloaded 196, added 195
-#10 12.60 Progress: resolved 296, reused 0, downloaded 248, added 231
-#10 13.60 Progress: resolved 296, reused 0, downloaded 284, added 283
-#10 14.60 Progress: resolved 296, reused 0, downloaded 288, added 288
-#10 15.60 Progress: resolved 296, reused 0, downloaded 289, added 288
-#10 16.60 Progress: resolved 296, reused 0, downloaded 290, added 290
-#10 19.46 Progress: resolved 296, reused 0, downloaded 291, added 290
-#10 20.46 Progress: resolved 296, reused 0, downloaded 291, added 291
-#10 22.03 Progress: resolved 296, reused 0, downloaded 292, added 291
-#10 ...
-
-#11 [visualizer-app runner  5/13] RUN pnpm install --prod --frozen-lockfile --ignore-scripts
-#11 12.39 Progress: resolved 267, reused 0, downloaded 262, added 261
-#11 13.39 Progress: resolved 267, reused 0, downloaded 262, added 262
-#11 14.39 Progress: resolved 267, reused 0, downloaded 264, added 264
-#11 15.39 Progress: resolved 267, reused 0, downloaded 265, added 265
-#11 ...
-
-#10 [visualizer-app builder 4/6] RUN npm install -g pnpm@latest &&   pnpm install --frozen-lockfile
-#10 23.04 Progress: resolved 296, reused 0, downloaded 292, added 292
-#10 24.40 Progress: resolved 296, reused 0, downloaded 293, added 292
-#10 25.40 Progress: resolved 296, reused 0, downloaded 293, added 293