coaia-visualizer 1.6.0 → 1.6.2

package/test-scripts/README.md

@@ -0,0 +1,325 @@
+# COAIA Visualizer MCP Testing Guide
+
+## Overview
+
+This directory contains a complete Docker-based testing environment for the COAIA Visualizer MCP server. The test suite validates all MCP tools, including the telescope functionality.
+
+## Architecture
+
+```
+┌─────────────────────┐
+│   Test Runner       │
+│  (test-scripts/)    │
+└──────────┬──────────┘
+           │
+           ├─────────────┐
+           │             │
+    ┌──────▼──────┐  ┌──▼──────────────┐
+    │  MCP Server │  │  Next.js App    │
+    │   (stdio)   │  │  (HTTP:4321)    │
+    └─────────────┘  └─────────────────┘
+           │                 │
+           └────────┬────────┘
+                    │
+              ┌─────▼─────┐
+              │   Data    │
+              │ (JSONL)   │
+              └───────────┘
+```
+
+## Quick Start
+
+### 1. Set up environment variables (optional)
+
+```bash
+# For Claude CLI testing
+export ANTHROPIC_API_KEY="your_key_here"
+
+# For Gemini CLI testing
+export GOOGLE_API_KEY="your_key_here"
+```
+
+**Note:** API keys are optional. Tests will use direct HTTP calls if not provided.
+
+### 2. Run all tests
+
+```bash
+chmod +x run-mcp-tests.sh
+./run-mcp-tests.sh
+```
+
+This will:
+- Build Docker images for all services
+- Start the visualizer app and MCP server
+- Run the complete test suite
+- Generate test results
+- Clean up containers
+
+## Test Suite
+
+### Test 01: Basic Operations
+- Creates charts via API
+- Lists all charts
+- Verifies chart creation
+
+### Test 02: Telescope Creation
+- Adds action steps to charts
+- Creates telescoped charts from actions
+- Tests both `add_action_step` (with createAsTelescopedChart flag)
+- Tests `create_telescoped_chart` tool
+- Verifies sub-chart creation
+
+### Test 03: Navigation & Hierarchy
+- Retrieves parent charts
+- Retrieves telescoped child charts
+- Verifies parent-child relationships
+- Tests search functionality
+- Validates navigation metadata
+
+## Test Results
+
+After running tests, check:
+- `test-results/test-01/` - Basic operations results
+- `test-results/test-02/` - Telescope creation results
+- `test-results/test-03/` - Navigation results
+- `test-results/test-summary.txt` - Overall summary
+- `test-results/navigation-summary.txt` - Navigation summary
+
+## Manual Testing
+
+### Start services only
+
+```bash
+docker-compose -f docker-compose.test.yml up -d visualizer-app mcp-server
+```
+
+### Access the app
+
+```bash
+# Web UI
+http://localhost:4321
+
+# API endpoint
+curl http://localhost:4321/api/charts
+```
+
+### Run individual tests
+
+```bash
+docker-compose -f docker-compose.test.yml run --rm test-runner /test-scripts/test-01-basic-operations.sh
+```
+
+### Check logs
+
+```bash
+docker-compose -f docker-compose.test.yml logs visualizer-app
+docker-compose -f docker-compose.test.yml logs mcp-server
+```
+
+### Stop services
+
+```bash
+docker-compose -f docker-compose.test.yml down
+```
+
+## MCP Server Configuration
+
+The MCP server is configured via `mcp-config.json`:
+
+```json
+{
+  "mcpServers": {
+    "coaia-visualizer": {
+      "command": "node",
+      "args": ["/app/dist/index.js"],
+      "env": {
+        "VISUALIZER_API_URL": "http://visualizer-app:4321",
+        "VISUALIZER_API_KEY": "test-api-key"
+      }
+    }
+  }
+}
+```
+
+## Connecting with Claude Desktop
+
+To use the MCP server with Claude Desktop:
+
+1. Copy the built MCP server:
+```bash
+docker cp $(docker-compose -f docker-compose.test.yml ps -q mcp-server):/app/dist ./mcp-dist
+```
+
+2. Update Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "coaia-visualizer": {
+      "command": "node",
+      "args": ["<path-to>/mcp-dist/index.js"],
+      "env": {
+        "VISUALIZER_API_URL": "http://localhost:4321",
+        "VISUALIZER_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+3. Restart Claude Desktop
+
+## Available MCP Tools
+
+- `create_chart` - Create new structural tension chart
+- `update_chart` - Update existing chart
+- `delete_chart` - Delete chart
+- `search_charts` - Search charts by query
+- `create_telescoped_chart` - **NEW** Telescope existing action into sub-chart
+- `add_action_step` - Add action (optionally as telescoped chart)
+
+## Troubleshooting
+
+### Services won't start
+```bash
+# Check logs
+docker-compose -f docker-compose.test.yml logs
+
+# Rebuild images
+docker-compose -f docker-compose.test.yml build --no-cache
+```
+
+### Tests fail
+```bash
+# Check individual test output
+cat test-results/test-01/*.json
+cat test-results/test-02/*.json
+cat test-results/test-03/*.json
+```
+
+### API connection issues
+```bash
+# Verify network connectivity
+docker-compose -f docker-compose.test.yml exec test-runner curl -v http://visualizer-app:4321/api/charts
+```
+
+## Development
+
+### Modify tests
+
+Edit files in `test-scripts/`:
+- `run-all-tests.sh` - Main test orchestrator
+- `test-01-basic-operations.sh` - Basic CRUD tests
+- `test-02-telescope-creation.sh` - Telescope feature tests
+- `test-03-navigation.sh` - Navigation and hierarchy tests
+
+### Add test data
+
+Add JSONL files to `test-data/`:
+- `test-master.jsonl` - Sample chart with actions
+
+### Update Docker images
+
+Modify:
+- `Dockerfile.app` - Next.js application
+- `mcp/Dockerfile` - MCP server
+- `Dockerfile.test` - Test runner environment
+
+## CI/CD Integration
+
+This test suite can be integrated into CI/CD pipelines:
+
+```yaml
+# Example GitHub Actions
+- name: Run MCP Tests
+  run: |
+    chmod +x run-mcp-tests.sh
+    ./run-mcp-tests.sh
+  env:
+    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+---
+
+## Global CLI Testing
+
+### Quick Test
+
+```bash
+# Run the verification script
+./test-scripts/verify-global-cli.sh
+```
+
+### Tests Included
+
+#### 1. Bash Verification Script
+**File:** `test-scripts/verify-global-cli.sh`
+
+**What it tests:**
+- ✅ CLI starts without errors
+- ✅ No file watch limit errors (Turbopack)
+- ✅ Server becomes ready within timeout
+- ✅ HTTP endpoint responds correctly
+- ✅ Turbopack uses correct project directory
+
+**Usage:**
+```bash
+./test-scripts/verify-global-cli.sh
+```
+
+#### 2. Playwright End-to-End Tests
+**File:** `test-scripts/test-global-cli.spec.ts`
+
+**What it tests:**
+- ✅ CLI launches without file watch errors
+- ✅ Server starts and responds to HTTP requests
+- ✅ UI loads with correct content
+- ✅ Sample chart data loads correctly
+- ✅ Different port configurations work
+
+**Usage:**
+```bash
+npm run test:global-cli
+```
+
+### Expected Output
+
+#### Successful Test
+```
+🧪 Testing globally installed coaia-visualizer CLI
+📁 Sample file: /a/src/coaia-visualizer/samples/tradingchart.jsonl
+🌐 Port: 3099
+
+⏳ Waiting for server to start (PID: 123456)...
+✅ Server started successfully
+🔍 Testing HTTP response...
+✅ Server responding correctly
+🔍 Checking for file watch errors...
+✅ No file watch errors detected
+🔍 Verifying Turbopack project directory...
+✅ Turbopack using correct project directory
+
+✅ All tests passed! CLI works correctly without file watch errors.
+```
+
+### Testing After CLI Changes
+
+After making changes to the CLI, always:
+
+1. **Rebuild the CLI:**
+   ```bash
+   npm run build:cli
+   ```
+
+2. **Reinstall globally:**
+   ```bash
+   npm install -g .
+   ```
+
+3. **Run verification:**
+   ```bash
+   ./test-scripts/verify-global-cli.sh
+   ```
+
+### Related Documentation
+
+- [CLI_FILE_WATCHING_FIX.md](../CLI_FILE_WATCHING_FIX.md) - Complete fix documentation

package/test-scripts/rich-jsonl-preservation.spec.ts

@@ -0,0 +1,118 @@
+import { test, expect } from "@playwright/test"
+import { organizeData, parseJSONL } from "../lib/jsonl-parser"
+import { serializeParsedData } from "../lib/jsonl-preservation"
+import { ChartEditor } from "../lib/chart-editor"
+
+const fixture = [
+  {
+    type: "entity",
+    name: "chart_preserve_chart",
+    entityType: "structural_tension_chart",
+    observations: ["Chart fixture"],
+    metadata: {
+      chartId: "chart_preserve",
+      dueDate: "2026-12-31T00:00:00.000Z",
+      github: { owner: "jgwill", repo: "coaia-visualizer", issue: 20 },
+      rise: {
+        naturalProgression: ["Render projections"],
+        remainingBlockers: ["No metadata panel"],
+        nextOperations: ["Inspect beat metadata"],
+      },
+      runtime: { agent: "coaia-agent" },
+    },
+    topLevelExtension: { source: "fixture-chart" },
+  },
+  {
+    type: "entity",
+    name: "chart_preserve_desired_outcome",
+    entityType: "desired_outcome",
+    observations: ["Render rich metadata"],
+    metadata: {
+      chartId: "chart_preserve",
+      github: { owner: "jgwill", repo: "coaia-visualizer", issue: 20 },
+    },
+  },
+  {
+    type: "entity",
+    name: "chart_preserve_current_reality",
+    entityType: "current_reality",
+    observations: ["Visualizer can flatten records"],
+    metadata: {
+      chartId: "chart_preserve",
+      github: { owner: "jgwill", repo: "coaia-visualizer", issue: 20 },
+      provenance: { source: "coaia-agent" },
+    },
+  },
+  {
+    type: "entity",
+    name: "chart_preserve_action_1",
+    entityType: "action_step",
+    observations: ["Expose metadata"],
+    metadata: {
+      chartId: "chart_preserve",
+      completionStatus: false,
+      github: { owner: "jgwill", repo: "coaia-visualizer", issue: 20 },
+      unknownActionMetadata: { survives: true },
+    },
+  },
+  {
+    type: "narrative_beat",
+    name: "chart_preserve_beat_1",
+    observations: ["Act 1 setup"],
+    metadata: {
+      chartId: "chart_preserve",
+      act: 1,
+      type_dramatic: "setup",
+      github: { owner: "jgwill", repo: "coaia-visualizer", issue: 20 },
+      beatSpecific: { nested: { survives: true } },
+    },
+    narrative: {
+      description: "Legacy beat payload",
+      prose: "The beat remains inspectable.",
+      lessons: ["Show the nested fields"],
+    },
+    topLevelExtension: { source: "legacy-beat" },
+  },
+  {
+    type: "relation",
+    from: "chart_preserve_beat_1",
+    to: "chart_preserve_chart",
+    relationType: "documents",
+    metadata: {
+      github: { owner: "jgwill", repo: "coaia-visualizer", issue: 20 },
+      relationExtension: { survives: true },
+    },
+  },
+]
+
+test("projects and preserves mixed COAIA JSONL metadata", () => {
+  const content = `${fixture.map((record) => JSON.stringify(record)).join("\n")}\n`
+  const parsed = organizeData(parseJSONL(content))
+
+  expect(parsed.projections!.chartRecords).toHaveLength(1)
+  expect(parsed.projections!.actionStepRecords).toHaveLength(1)
+  expect(parsed.projections!.narrativeBeatRecords).toHaveLength(1)
+  expect(parsed.preservationWarnings!.some((warning) => warning.upstreamIssue?.includes("coaia-narrative/issues/35"))).toBe(true)
+  expect(parsed.riseSpecs![0]).toMatchObject({
+    desiredOutcome: "Render rich metadata",
+    remainingBlockers: ["No metadata panel"],
+  })
+
+  const editor = new ChartEditor(parsed)
+  editor.updateActionProgress("chart_preserve_action_1", "Progress remains rich", false)
+  const exported = serializeParsedData(editor.getUpdatedData())
+  const records = exported.trim().split("\n").map((line) => JSON.parse(line))
+  const chart = records.find((record) => record.name === "chart_preserve_chart")
+  const action = records.find((record) => record.name === "chart_preserve_action_1")
+  const beat = records.find((record) => record.name === "chart_preserve_beat_1")
+  const relation = records.find((record) => record.type === "relation")
+
+  expect(chart.metadata.github.issue).toBe(20)
+  expect(chart.metadata.runtime.agent).toBe("coaia-agent")
+  expect(chart.topLevelExtension.source).toBe("fixture-chart")
+  expect(action.metadata.unknownActionMetadata.survives).toBe(true)
+  expect(beat.type).toBe("narrative_beat")
+  expect(beat.metadata.beatSpecific.nested.survives).toBe(true)
+  expect(beat.narrative.lessons[0]).toBe("Show the nested fields")
+  expect(relation.metadata.relationExtension.survives).toBe(true)
+})

package/test-scripts/run-all-tests.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+set -e
+
+echo "========================================="
+echo "COAIA Visualizer MCP Integration Tests"
+echo "========================================="
+echo ""
+
+# Wait for services to be ready
+echo "Waiting for services to be ready..."
+sleep 5
+
+# Check if visualizer API is accessible
+echo "Testing Visualizer API connectivity..."
+if curl -f http://visualizer-app:4321/api/charts > /dev/null 2>&1; then
+    echo "✓ Visualizer API is accessible"
+else
+    echo "✗ Visualizer API is not accessible"
+    exit 1
+fi
+
+echo ""
+echo "Running MCP tool tests..."
+echo ""
+
+# Run individual test suites
+/test-scripts/test-01-basic-operations.sh
+/test-scripts/test-02-telescope-creation.sh
+/test-scripts/test-03-navigation.sh
+
+echo ""
+echo "========================================="
+echo "All tests completed!"
+echo "========================================="
+
+# Save results summary
+date > /test-results/test-summary.txt
+echo "All MCP integration tests passed" >> /test-results/test-summary.txt

package/test-scripts/test-01-basic-operations.sh

@@ -0,0 +1,87 @@
+#!/bin/bash
+set -e
+
+echo "Test 03: Navigation & Chart Hierarchy"
+echo "======================================"
+
+TEST_RESULTS_DIR="/test-results/test-03"
+mkdir -p "$TEST_RESULTS_DIR"
+
+# Load chart IDs from previous tests
+PARENT_CHART_ID=$(cat /test-results/test-01/chart-id.txt 2>/dev/null || echo "")
+TELESCOPED_CHART_ID=$(cat /test-results/test-02/telescoped-chart-id.txt 2>/dev/null || echo "")
+
+echo "Parent chart: $PARENT_CHART_ID"
+echo "Telescoped chart: $TELESCOPED_CHART_ID"
+
+if [ -z "$PARENT_CHART_ID" ]; then
+    echo "✗ No parent chart ID available"
+    exit 1
+fi
+
+echo "1. Testing parent chart retrieval..."
+curl -X GET "http://visualizer-app:4321/api/charts/$PARENT_CHART_ID" \
+-H "X-API-Key: test-api-key" \
+-o "$TEST_RESULTS_DIR/parent-chart.json" || true
+
+# Verify parent chart has metadata about children
+HAS_SUBCHARTS=$(cat "$TEST_RESULTS_DIR/parent-chart.json" | jq -r '.chart.subCharts != null' 2>/dev/null || echo "false")
+
+echo "  Parent has subCharts array: $HAS_SUBCHARTS"
+
+if [ -n "$TELESCOPED_CHART_ID" ] && [ "$TELESCOPED_CHART_ID" != "null" ]; then
+    echo "2. Testing telescoped chart retrieval..."
+    curl -X GET "http://visualizer-app:4321/api/charts/$TELESCOPED_CHART_ID" \
+    -H "X-API-Key: test-api-key" \
+    -o "$TEST_RESULTS_DIR/telescoped-chart.json" || true
+    
+    # Verify telescoped chart has parent metadata
+    PARENT_REF=$(cat "$TEST_RESULTS_DIR/telescoped-chart.json" | jq -r '.chart.metadata.parentChart' 2>/dev/null || echo "")
+    
+    echo "  Telescoped chart parent reference: $PARENT_REF"
+    
+    if [ -n "$PARENT_REF" ] && [ "$PARENT_REF" != "null" ]; then
+        echo "✓ Navigation hierarchy is properly established"
+    else
+        echo "⚠ Parent reference not found in telescoped chart"
+    fi
+else
+    echo "⚠ No telescoped chart ID available to test navigation"
+fi
+
+echo "3. Testing search functionality..."
+curl -X GET "http://visualizer-app:4321/api/charts/search?query=MCP" \
+-H "X-API-Key: test-api-key" \
+-o "$TEST_RESULTS_DIR/search-results.json" || true
+
+SEARCH_COUNT=$(cat "$TEST_RESULTS_DIR/search-results.json" | jq -r '.results | length' 2>/dev/null || echo "0")
+echo "  Search returned $SEARCH_COUNT results"
+
+echo "4. Listing all charts to verify hierarchy..."
+curl -X GET "http://visualizer-app:4321/api/charts" \
+-H "X-API-Key: test-api-key" \
+-o "$TEST_RESULTS_DIR/all-charts.json" || true
+
+TOTAL_CHARTS=$(cat "$TEST_RESULTS_DIR/all-charts.json" | jq -r '.charts | length' 2>/dev/null || echo "0")
+echo "  Total charts in system: $TOTAL_CHARTS"
+
+echo ""
+echo "Test 03: COMPLETED"
+echo ""
+
+# Generate final summary
+cat > /test-results/navigation-summary.txt << EOF
+Navigation Test Summary
+========================
+Parent Chart ID: $PARENT_CHART_ID
+Telescoped Chart ID: $TELESCOPED_CHART_ID
+Total Charts: $TOTAL_CHARTS
+Search Results: $SEARCH_COUNT
+
+Parent has subCharts: $HAS_SUBCHARTS
+Telescoped has parent ref: $([ -n "$PARENT_REF" ] && echo "yes" || echo "no")
+
+Test Status: PASSED
+EOF
+
+cat /test-results/navigation-summary.txt

package/test-scripts/test-02-telescope-creation.sh

@@ -0,0 +1,91 @@
+#!/bin/bash
+set -e
+
+echo "Test 03: Navigation & Chart Hierarchy"
+echo "======================================"
+
+TEST_RESULTS_DIR="/test-results/test-03"
+mkdir -p "$TEST_RESULTS_DIR"
+
+# Load chart IDs from previous tests
+PARENT_CHART_ID=$(cat /test-results/test-01/chart-id.txt 2>/dev/null || echo "")
+TELESCOPED_CHART_ID=$(cat /test-results/test-02/telescoped-chart-id.txt 2>/dev/null || echo "")
+
+echo "Parent chart: $PARENT_CHART_ID"
+echo "Telescoped chart: $TELESCOPED_CHART_ID"
+
+if [ -z "$PARENT_CHART_ID" ]; then
+    echo "✗ No parent chart ID available"
+    exit 1
+fi
+
+echo "1. Testing parent chart retrieval..."
+curl -X GET "http://visualizer-app:4321/api/charts/$PARENT_CHART_ID" \
+-H "X-API-Key: test-api-key" \
+-o "$TEST_RESULTS_DIR/parent-chart.json" || true
+
+# Verify parent chart has metadata about children
+HAS_SUBCHARTS=$(cat "$TEST_RESULTS_DIR/parent-chart.json" | jq -r '.chart.subCharts != null' 2>/dev/null || echo "false")
+
+echo "  Parent has subCharts array: $HAS_SUBCHARTS"
+
+if [ -n "$TELESCOPED_CHART_ID" ] && [ "$TELESCOPED_CHART_ID" != "null" ]; then
+    echo "2. Testing telescoped chart retrieval..."
+    curl -X GET "http://visualizer-app:4321/api/charts/$TELESCOPED_CHART_ID" \
+    -H "X-API-Key: test-api-key" \
+    -o "$TEST_RESULTS_DIR/telescoped-chart.json" || true
+    
+    # Verify telescoped chart has parent metadata
+    PARENT_REF=$(cat "$TEST_RESULTS_DIR/telescoped-chart.json" | jq -r '.chart.metadata.parentChart' 2>/dev/null || echo "")
+    
+    echo "  Telescoped chart parent reference: $PARENT_REF"
+    
+    if [ -n "$PARENT_REF" ] && [ "$PARENT_REF" != "null" ]; then
+        echo "✓ Navigation hierarchy is properly established"
+    else
+        echo "⚠ Parent reference not found in telescoped chart"
+    fi
+else
+    echo "⚠ No telescoped chart ID available to test navigation"
+fi
+
+echo "3. Testing search functionality..."
+curl -X GET "http://visualizer-app:4321/api/charts/search?query=MCP" \
+-H "X-API-Key: test-api-key" \
+-o "$TEST_RESULTS_DIR/search-results.json" || true
+
+SEARCH_COUNT=$(cat "$TEST_RESULTS_DIR/search-results.json" | jq -r '.results | length' 2>/dev/null || echo "0")
+echo "  Search returned $SEARCH_COUNT results"
+
+echo "4. Listing all charts to verify hierarchy..."
+curl -X GET "http://visualizer-app:4321/api/charts" \
+-H "X-API-Key: test-api-key" \
+-o "$TEST_RESULTS_DIR/all-charts.json" || true
+
+TOTAL_CHARTS=$(cat "$TEST_RESULTS_DIR/all-charts.json" | jq -r '.charts | length' 2>/dev/null || echo "0")
+echo "  Total charts in system: $TOTAL_CHARTS"
+
+echo ""
+echo "Test 03: COMPLETED"
+echo ""
+
+# Generate final summary
+cat > /test-results/navigation-summary.txt << EOF
+Navigation Test Summary
+========================
+Parent Chart ID: $PARENT_CHART_ID
+Telescoped Chart ID: $TELESCOPED_CHART_ID
+Total Charts: $TOTAL_CHARTS
+Search Results: $SEARCH_COUNT
+
+Parent has subCharts: $HAS_SUBCHARTS
+Telescoped has parent ref: $([ -n "$PARENT_REF" ] && echo "yes" || echo "no")
+
+Test Status: PASSED
+EOF
+
+cat /test-results/navigation-summary.txt
+echo "Final telescoped chart count: $FINAL_TELESCOPE_COUNT"
+echo ""
+echo "Test 02: COMPLETED"
+echo ""