coaia-visualizer 1.6.0 → 1.6.2

package/dist/skill.js

@@ -0,0 +1,342 @@
+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';
+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 = [
+    { 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) {
+    return globalInstall
+        ? resolve(homedir(), '.agents', 'skills', SKILL_NAME)
+        : resolve(process.cwd(), '.agents', 'skills', SKILL_NAME);
+}
+function getClaudeSkillLinkPath(globalInstall) {
+    return globalInstall
+        ? resolve(homedir(), '.claude', 'skills', SKILL_NAME)
+        : resolve(process.cwd(), '.claude', 'skills', SKILL_NAME);
+}
+function pathExists(pathName) {
+    try {
+        lstatSync(pathName);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function removePath(pathName) {
+    const stat = lstatSync(pathName);
+    if (stat.isDirectory() && !stat.isSymbolicLink()) {
+        rmSync(pathName, { recursive: true, force: true });
+    }
+    else {
+        unlinkSync(pathName);
+    }
+}
+function writeEmbeddedSkill(targetDir, force) {
+    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, targetDir, force) {
+    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, autoYes) {
+    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, force, autoYes) {
+    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() {
+    console.log('coaia-visualizer Skill (embedded)');
+    console.log('');
+    process.stdout.write(COAIA_VISUALIZER_SKILL_MD);
+}
+export function showSkillCommandHelp() {
+    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) {
+    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/docker-compose.test.yml

@@ -0,0 +1,69 @@
+version: '3.8'
+
+services:
+  # Next.js application server
+  visualizer-app:
+    build:
+      context: .
+      dockerfile: Dockerfile.app
+    ports:
+      - "4321:4321"
+    volumes:
+      - ./samples:/app/samples:ro
+      - ./test-data:/app/test-data
+    environment:
+      - NODE_ENV=production
+      - PORT=4321
+    networks:
+      - test-network
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:4321/api/charts"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  # MCP Server
+  mcp-server:
+    build:
+      context: ./mcp
+      dockerfile: Dockerfile
+    environment:
+      - VISUALIZER_API_URL=http://visualizer-app:4321
+      - VISUALIZER_API_KEY=${VISUALIZER_API_KEY:-test-api-key}
+      - NODE_ENV=production
+    volumes:
+      - ./test-data:/data
+    networks:
+      - test-network
+    depends_on:
+      visualizer-app:
+        condition: service_healthy
+    stdin_open: true
+    tty: true
+
+  # Test runner using claude-code CLI or gemini-cli
+  test-runner:
+    build:
+      context: .
+      dockerfile: Dockerfile.test
+    environment:
+      - MCP_SERVER_HOST=mcp-server
+      - VISUALIZER_API_URL=http://visualizer-app:4321
+      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
+      - GOOGLE_API_KEY=${GOOGLE_API_KEY}
+    volumes:
+      - ./test-scripts:/test-scripts:ro
+      - ./test-results:/test-results
+      - ./test-data:/test-data
+    networks:
+      - test-network
+    depends_on:
+      visualizer-app:
+        condition: service_healthy
+      mcp-server:
+        condition: service_started
+    command: ["/test-scripts/run-all-tests.sh"]
+
+networks:
+  test-network:
+    driver: bridge

package/index.tsx

@@ -13,31 +13,6 @@ export type {
 // JSONL Parser
 export { parseJSONL, organizeData, getChartSummary, getChartProgress } from "./lib/jsonl-parser"
 
-// GitHub provenance helpers
-export {
-  GITHUB_BRIDGE_RELATION_TYPES,
-  GITHUB_PROJECT_FIELD_KEYS,
-  GITHUB_SYNC_STATES,
-  formatGithubIssueRef,
-  formatProjectItemRef,
-  getGithubBridgeRelationType,
-  getGithubEntityProvenance,
-  getGithubIssueRef,
-  getGithubProjectItems,
-  getGithubSource,
-  getGithubSyncState,
-  getProjectFieldEntries,
-} from "./lib/github-provenance"
-export type {
-  GithubBridgeRelationType,
-  GithubEntityProvenance,
-  GithubIssueRef,
-  GithubProjectFieldEntry,
-  GithubProjectItemRef,
-  GithubSourceProvenance,
-  GithubSyncState,
-} from "./lib/github-provenance"
-
 // Utilities
 export { cn } from "./lib/utils"
 
@@ -53,7 +28,6 @@ export { ChartDetail } from "./components/chart-detail"
 export { DataStats } from "./components/data-stats"
 export { CreateChartForm } from "./components/create-chart-form"
 export { NarrativeBeats } from "./components/narrative-beats"
-export { ActionStepIssueBadge, ProjectSourceBadge, SyncStatePill } from "./components/github-provenance"
 export { LiveIndicator } from "./components/live-indicator"
 export { ThemeToggle } from "./components/theme-toggle"
 export { EditDesiredOutcome } from "./components/edit-desired-outcome"