coaia-visualizer 1.6.3 → 1.6.5

package/rispecs/chart-visualization-hierarchy.spec.md

@@ -0,0 +1,235 @@
+# Chart Visualization & Hierarchy
+## RISE Specification for Chart Display, Navigation, and Structural Tension Rendering
+
+**Component Purpose**: Render structural tension charts in navigable hierarchy and list views, enabling users to see the creative gap between desired outcomes and current reality at every level of depth.
+
+**Source Files**: `components/chart-list.tsx`, `components/chart-detail.tsx`, `components/chart-detail-editable.tsx`
+
+---
+
+## 🎯 What This Component Enables Users to Create
+
+- Visual maps of structural tension across hierarchical chart trees
+- Navigable depth — drilling from root charts through telescoped sub-charts
+- At-a-glance progress awareness through progress bars and completion counts
+- Contextual detail views showing the full picture of any chart
+- Breadcrumb-style navigation that maintains context while exploring depth
+
+---
+
+## 🌊 Structural Tension Dynamics
+
+### Current Reality
+Charts in coaia-narrative exist as flat JSONL records. A root chart with 3 levels of telescoped sub-charts is just 20+ entity records and 15+ relation records in a text file. There is no visual hierarchy, no at-a-glance progress, no way to "see" the structural tension.
+
+### Desired Result
+A two-pane interface where:
+- Left pane shows all charts in either hierarchy (tree) or flat list mode
+- Right pane shows full detail of the selected chart
+- Navigation stack enables drilling into sub-charts with back navigation
+- Every chart visually renders the tension between desired outcome and current reality
+- Progress bars show advancement toward completion
+
+### Natural Resolution
+The `ChartList` component transforms `ParsedData.rootCharts` into a navigable tree (via recursive `ChartTree` sub-component), while `ChartDetailEditable` renders the selected chart's full structure with inline editing. Stack-based navigation tracks the user's path through the hierarchy.
+
+---
+
+## 📋 ChartList Component
+
+### Props
+```typescript
+interface ChartListProps {
+  data: ParsedData
+  selectedChart: Chart | null
+  onSelectChart: (chart: Chart) => void
+  mode: "hierarchy" | "list"
+  onDataUpdate?: (updatedData: ParsedData) => void
+}
+```
+
+### Two Display Modes
+
+**Hierarchy Mode** (default):
+- Renders `ChartTree` — a recursive component that displays root charts with expandable sub-charts
+- Each level is indented with left padding and vertical border
+- Chevron icons toggle expand/collapse state
+- Sub-charts nested within parent nodes
+
+**List Mode**:
+- Flat `ScrollArea` listing all charts regardless of level
+- Each chart rendered as `ChartItem`
+- No indentation or hierarchy
+
+### ChartItem Sub-Component
+Each chart item displays:
+- **Chart ID**: Badge with chart identifier (e.g., "chart_1")
+- **Level Badge**: Shows depth level (0 = root)
+- **Summary**: First 100 chars of desired outcome via `getChartSummary()`
+- **Narrative Beat Indicators**: If beats exist, shows first beat description snippet
+- **Action Count**: Number of action steps
+- **Progress Bar**: Visual bar showing `getChartProgress()` percentage
+- **Selected State**: Primary border highlight when this chart is selected
+
+### ChartTree Sub-Component
+```
+▼ chart_1 — "Build structural tension framework"    [Level 0] [3 actions] [66%]
+    ▶ chart_4 — "Design entity type system"          [Level 1] [2 actions] [50%]
+    ▼ chart_5 — "Implement parsing algorithm"         [Level 1] [4 actions] [25%]
+        ▶ chart_8 — "Handle malformed input"          [Level 2] [1 action]  [0%]
+  chart_2 — "Create UI component library"             [Level 0] [5 actions] [80%]
+```
+
+### AddMasterChart Integration
+When `onDataUpdate` prop is provided, an "Add Chart" button appears at the bottom of the list, triggering the `AddMasterChart` dialog for creating new root-level charts.
+
+---
+
+## 📋 ChartDetail Component (Read-Only)
+
+> ⚠️ **Note**: This component exists in the codebase but is NOT rendered by `page.tsx`. The application exclusively uses `ChartDetailEditable` for all chart display. ChartDetail is retained for potential future read-only embedding scenarios.
+
+### Props
+```typescript
+interface ChartDetailProps {
+  chart: Chart
+  data: ParsedData
+}
+```
+
+### Renders (Top to Bottom)
+1. **Header Card**: Chart title (from desired outcome), level badge, creation date, due date
+2. **Structural Tension Card** (section order is critical — maintains the creative tension visual):
+   - **Desired Outcome** in teal-colored box (chart-1 theme) — the vision
+   - **Action Steps** with completion indicators and due dates — the path
+   - **Current Reality** observations in amber-colored box (chart-2 theme) — where you are now
+3. **Narrative Beats Section**: If beats exist, renders `NarrativeBeats` component
+4. **Sub-Charts List**: Child charts listed at bottom
+
+### ActionItem Sub-Component
+```
+┌──────────────────────────────────────────────┐
+│ ○  Action Step Title                         │
+│    Due: 2024-03-15                           │
+│ ──────────────────────────────────────────── │
+│ ✓  Completed Action (strikethrough text)     │
+│    Completed: 2024-03-10                     │
+└──────────────────────────────────────────────┘
+```
+- Circle icon (`○`) for incomplete, check icon (`✓`) for complete
+- Strikethrough styling applied to completed actions
+- Due date displayed below action text when present
+
+---
+
+## 📋 ChartDetailEditable Component
+
+### Props
+```typescript
+interface ChartDetailEditableProps {
+  chart: Chart
+  data: ParsedData
+  onUpdate: (updatedData: ParsedData) => void
+  onNavigateToSubChart?: (subChart: Chart) => void
+  onNavigateBack?: () => void
+}
+```
+
+### Additional Features (Beyond Read-Only)
+- **Back Button**: Appears when navigation stack has entries (i.e., `chartNavigationStack.length > 0`), calls `onNavigateBack()`
+- **Inline Editing**: Uses `EditDesiredOutcome`, `EditCurrentReality`, `EditActionStep` components
+- **Due Date Editor**: `EditChartDueDate` component on header card
+- **Add Action Step**: `AddActionStep` form at bottom of actions list
+- **Telescope Actions**: Each action has telescope icon to create/navigate to sub-chart
+- **Completion Toggle**: Checkbox-style toggle on each action
+
+### Structural Tension Card Section Order
+The Structural Tension card renders three sections top-to-bottom, separated by `<Separator>` elements:
+1. **Desired Outcome** (Target icon, chart-1 color) — `EditDesiredOutcome`
+2. **Action Steps** (ListChecks icon, chart-3 color) — `EditActionStep` list + `AddActionStep` form
+3. **Current Reality** (MapPin icon, chart-2 color) — `EditCurrentReality`
+
+> ⚠️ This order is intentional. Action Steps sit between outcome and reality to represent the bridge across the structural tension gap.
+
+### applyEdit Pattern
+All edits follow a consistent pattern:
+```
+1. Create ChartEditor instance from current ParsedData
+2. Call appropriate editor method (e.g., updateDesiredOutcome)
+3. Get updated ParsedData via editor.getUpdatedData()
+4. Pass to onUpdate() callback → parent state updates → re-render
+```
+
+### Telescoping Flow
+```
+User clicks telescope icon on action
+       │
+       ├─ If action already has telescoped chart:
+       │    → onNavigateToSubChart(existingSubChart)
+       │
+       └─ If action has no telescoped chart:
+            → ChartEditor.createTelescopedChartFromAction()
+            → New sub-chart created with action as desired outcome
+            → onUpdate(newData)
+            → onNavigateToSubChart(newSubChart)
+```
+
+---
+
+## 📋 Navigation Stack
+
+The main page (`app/page.tsx`) maintains a `chartNavigationStack: Chart[]` array:
+
+```typescript
+handleNavigateToSubChart(subChart: Chart):
+  1. Push current selectedChart onto stack
+  2. Set selectedChart = subChart
+
+handleNavigateBack():
+  1. Pop last chart from stack
+  2. Set selectedChart = popped chart (or null if stack empty)
+```
+
+This enables unlimited depth navigation with consistent back-button behavior.
+
+---
+
+## 📋 View Mode Toggle
+
+The main page offers a `viewMode` toggle between "hierarchy" and "list":
+- **Hierarchy**: Shows `ChartList` in tree mode with expand/collapse
+- **List**: Shows `ChartList` in flat mode — useful for searching or quick overview
+
+Toggle rendered as `Tabs` component at the top of the left pane.
+
+---
+
+## ✅ Quality Criteria
+
+✅ **Structural Tension Visible**
+- Every chart clearly displays desired outcome and current reality in contrasting color boxes
+- The gap between them is the structural tension — always visible, never hidden
+
+✅ **Navigation Integrity**
+- Back button always returns to correct parent chart
+- Stack correctly tracks multi-level depth navigation
+- Sub-charts display in both hierarchy tree and detail view
+
+✅ **Progress Awareness**
+- Progress bars calculate from action completion status
+- Summary text truncated consistently at 100 characters
+- Level badges distinguish root charts from sub-charts at a glance
+
+✅ **Responsive Layout**
+- Two-pane layout with scrollable chart list and detail view
+- Responsive typography (md: breakpoints for text sizing)
+- Hover-triggered toolbars for editing actions
+
+---
+
+## 🔗 Related Components
+
+- [jsonl-parsing-data-types.spec.md](./jsonl-parsing-data-types.spec.md) — provides ParsedData consumed by these components
+- [chart-editing-workflow.spec.md](./chart-editing-workflow.spec.md) — editing components used within ChartDetailEditable
+- [narrative-beats-display.spec.md](./narrative-beats-display.spec.md) — NarrativeBeats rendered within chart detail
+- [relation-graph-visualization.spec.md](./relation-graph-visualization.spec.md) — RelationGraph rendered in relations tab

package/rispecs/cli-mode.spec.md

@@ -0,0 +1,224 @@
+# CLI Mode
+## RISE Specification for Command-Line Interface and Deployment
+
+**Component Purpose**: Launch the coaia-visualizer from the terminal with a single command, supporting both local Next.js development and Docker containerized deployment, configurable via flags and environment variables.
+
+**Source Files**: `cli.ts`, `Dockerfile`, `package.json` (bin field)
+
+**Key Dependencies**: `minimist` (argument parsing), `dotenv` (env file loading)
+
+> **Note**: The CLI uses ESM (`import` syntax). The compiled output targets ES modules.
+
+---
+
+## 🎯 What This Component Enables Users to Create
+
+- Instant visualization of any local JSONL memory file via `coaia-visualizer --memory-path ./file.jsonl`
+- Containerized deployments with volume-mounted memory files
+- Configurable live-polling sessions with auto-reload
+- Audio-enabled sessions with auto-play capability
+- Zero-configuration startup with sensible defaults
+
+---
+
+## 🌊 Structural Tension Dynamics
+
+### Current Reality
+JSONL memory files sit on the filesystem. Opening them requires a running web server, environment variables, and browser navigation. Docker deployment needs image management, port mapping, and volume mounting. These steps are manual without the CLI.
+
+### Desired Result
+A single `coaia-visualizer` command that:
+1. Resolves the memory file path (from flag, env var, or default)
+2. Starts the appropriate server (Next.js local or Docker container)
+3. Opens the browser automatically
+4. Handles graceful shutdown on SIGINT
+
+### Natural Resolution
+The CLI script (`cli.ts`) compiles to `dist/cli.js` and is registered as the `coaia-visualizer` npm binary. It resolves configuration from three layers (args > env > defaults), then spawns either a Docker container or a local Next.js dev server.
+
+---
+
+## 📋 Command-Line Flags
+
+```
+coaia-visualizer [options]
+
+Options:
+  --memory-path, -M PATH    Path to JSONL memory file (default: ./memory.jsonl)
+  --port, -p PORT            Server port (default: 4321)
+  --docker, -d               Run in Docker container
+  --docker-image IMAGE       Custom Docker image (default: jgwill/coaia:visualizer)
+  --pull                     Pull Docker image before running
+  --live                     Enable live file polling
+  --poll-interval MS         Polling frequency in milliseconds (default: 2000)
+  --auto-play                Auto-play audio files
+  --audio-dir PATH           Directory for audio files
+  --no-open                  Don't auto-open browser
+  --help, -h                 Show help text
+```
+
+---
+
+## 📋 Environment Variables
+
+| Variable | Flag Equivalent | Default | Purpose |
+|:---|:---|:---|:---|
+| `COAIAN_MF` | `--memory-path` | `./memory.jsonl` | Memory file path |
+| `COAIAV_MEMORY_PATH` | *(internal)* | — | Resolved absolute path (set by CLI from `COAIAN_MF`). API routes read this variable. |
+| `COAIAV_MEMORY_DISPLAY_NAME` | *(internal)* | — | Original filename for UI display. Set by CLI to preserve the actual filename when Docker remaps to `/data/memory.jsonl`. Falls back to `path.basename(COAIAV_MEMORY_PATH)` if unset. |
+| `COAIAV_PORT` | `--port` | `4321` | Server port |
+| `COAIAV_LIVE` | `--live` | `false` | Enable live polling |
+| `COAIAV_POLL_INTERVAL` | `--poll-interval` | `2000` | Polling interval (ms) |
+| `COAIAV_AUTO_PLAY` | `--auto-play` | `false` | Auto-play audio |
+| `COAIAV_AUDIO_DIR` | `--audio-dir` | — | Audio directory path |
+| `COAIAN_API_TOKEN` | — | auto-generated | API authentication token |
+
+---
+
+## 📋 Configuration Priority
+
+```
+1. Command-line flags     (highest priority)
+2. Environment variables
+3. .env file values
+4. Default values          (lowest priority)
+```
+
+---
+
+## 📋 Execution Modes
+
+### Local Mode (Default)
+
+```
+coaia-visualizer --memory-path ./memory.jsonl --port 3000
+```
+
+**Process**:
+1. Resolve absolute path to memory file
+2. Set environment variables: `COAIAV_MEMORY_PATH`, `COAIAV_MEMORY_DISPLAY_NAME`, `PORT`, `NEXT_PUBLIC_LIVE_MODE`, `NEXT_PUBLIC_POLL_INTERVAL`, `COAIAV_AUTO_PLAY`, `COAIAV_AUDIO_DIR`
+3. Spawn `npm run dev` in the coaia-visualizer package directory
+4. Inherit stdio for visible server output
+5. Wait 3 seconds, then auto-open browser at `http://localhost:{port}`
+6. Listen for SIGINT → gracefully terminate child process
+
+### Docker Mode
+
+```
+coaia-visualizer --docker --memory-path ./memory.jsonl --pull
+```
+
+**Process**:
+1. If `--pull` flag → execute `docker pull {image}` first
+2. Resolve absolute path to memory file
+3. Execute Docker run:
+   ```
+   docker run --rm
+     -p {hostPort}:{containerPort}
+     -v {absPath}:/data/memory.jsonl
+     -e COAIAV_MEMORY_PATH=/data/memory.jsonl
+     -e COAIAV_MEMORY_DISPLAY_NAME={originalFilename}
+     -e PORT={containerPort}
+     -e NEXT_PUBLIC_LIVE_MODE={live}
+     -e NEXT_PUBLIC_POLL_INTERVAL={interval}
+     {image}
+   ```
+4. Container port: always 4321 internally
+5. Auto-open browser at `http://localhost:{hostPort}`
+
+### Docker Constants
+```typescript
+const DOCKER_IMAGE = 'jgwill/coaia:visualizer'
+const CONTAINER_PORT = 4321
+```
+
+---
+
+## 📋 Dockerfile (Production)
+
+**Base**: `node:22-alpine` (two-stage build)
+
+### Builder Stage
+1. Install pnpm via corepack
+2. Copy `package.json` + `pnpm-lock.yaml`
+3. Install dependencies (skip prepare hook)
+4. Copy source files
+5. Build: `pnpm prepare && pnpm build` (CLI + Next.js)
+
+### Runner Stage
+1. Copy dependencies from builder
+2. Prune dev dependencies
+3. Copy built `.next/`, `public/`, `next.config.mjs`
+4. Copy `docker-entrypoint.sh`
+5. **VOLUME**: `/data` (mount point for JSONL files)
+6. **ENV**: `PORT=4321`, `COAIAV_MEMORY_PATH=/data/memory.jsonl`
+7. **ENTRYPOINT**: `docker-entrypoint.sh`
+8. **EXPOSE**: 4321
+
+---
+
+## 📋 npm Package Entry
+
+```json
+{
+  "bin": {
+    "coaia-visualizer": "dist/cli.js"
+  }
+}
+```
+
+**Build CLI**: `npm run build:cli` → `tsc` compiles `cli.ts` → `dist/cli.js`  
+**Prepare hook**: `npm run build:cli` runs automatically on `npm install`
+
+### Global Installation
+```bash
+npm install -g coaia-visualizer
+coaia-visualizer --memory-path /path/to/memory.jsonl
+```
+
+---
+
+## 📋 Creative Advancement Scenario
+
+### Scenario: Quick Visualization of Agent Session
+**User Intent**: See the structural tension charts my AI agent created during a session  
+**Current Structural Reality**: Agent wrote to `./memory.jsonl` via coaia-narrative MCP, but the file is raw JSONL  
+
+**Natural Progression**:
+1. User runs: `coaia-visualizer -M ./memory.jsonl --live`
+2. CLI resolves absolute path, sets env vars
+3. Next.js dev server starts with live polling enabled
+4. Browser opens to `http://localhost:4321`
+5. Charts load from filesystem automatically
+6. Live polling detects agent writes → UI auto-refreshes
+7. User navigates charts while agent continues working
+8. SIGINT → graceful shutdown
+
+---
+
+## ✅ Quality Criteria
+
+✅ **Zero-Config Startup**
+- Sensible defaults for all settings (port 4321, ./memory.jsonl, no live mode)
+- Works with just `coaia-visualizer` in a directory with `memory.jsonl`
+
+✅ **Configuration Flexibility**
+- Three-layer configuration (flags > env > defaults)
+- All settings available as both flags and environment variables
+
+✅ **Docker Parity**
+- Docker mode produces identical user experience to local mode
+- Volume mounting correctly maps host file into container
+- Environment variables pass through to container
+
+✅ **Graceful Lifecycle**
+- Auto-open browser after startup delay
+- SIGINT terminates child process cleanly
+- Docker `--rm` flag cleans up containers
+
+---
+
+## 🔗 Related Components
+
+- [api-mcp-interface.spec.md](./api-mcp-interface.spec.md) — API routes served by the server CLI starts
+- [app.spec.md](./app.spec.md) — full application that CLI launches