mia-code 0.2.0 → 0.3.0

package/rispecs/_sync_/miadi-code/dashboard/SPEC.md

@@ -0,0 +1,465 @@
+# RISE Specification: Interactive Terminal Dashboard (TUI)
+
+## Status: IMPLEMENTED ✅
+
+**Version**: 1.0.0
+**Module**: `miadi-code/src/dashboard.ts`
+**Document ID**: miadi-code-dashboard-rise-spec-v1
+**Last Updated**: 2026-01-31
+
+---
+
+## Core Creative Intent
+
+The Interactive Terminal Dashboard empowers CLI agent developers to create **rich, menu-driven terminal user interfaces** within any interactive command-line application. This pattern enables:
+
+- Full-screen terminal rendering with visual hierarchy
+- Interactive menu selection with keyboard navigation
+- Real-time data refresh and progress visualization
+- Graceful TTY detection and fallback modes
+- Isolated input handling to prevent readline conflicts
+
+---
+
+## R - Reverse Engineering
+
+### Current State Analysis
+
+The dashboard module (`dashboard.ts`) implements a **Structural Tension Interface (STI)** - a TUI for visualizing and managing Structural Tension Charts within the miadi-code CLI.
+
+### File Structure
+
+```
+miadi-code/src/
+├── dashboard.ts           # Main dashboard class (StructuralTensionDashboard)
+├── dashboard.test.ts      # Data adapter and rendering tests
+├── cli.ts                 # Integration point (/dashboard, /ui commands)
+└── stc/
+    └── workspace-client.ts # API client used by dashboard
+```
+
+### Architectural Pattern
+
+```
+User Input (/dashboard)
+        ↓
+┌──────────────────────────────────────────────────────────────────────┐
+│                   StructuralTensionDashboard                          │
+├──────────────────────────────────────────────────────────────────────┤
+│  ┌───────────────┐  ┌───────────────┐  ┌────────────────────────────┐│
+│  │ TTY Detection │  │ Health Check  │  │ Repo Auto-Detection        ││
+│  │ & Fallback    │  │ (API reachable)│  │ (git remote get-url origin)││
+│  └───────┬───────┘  └───────┬───────┘  └───────────┬────────────────┘│
+│          │                  │                      │                  │
+│          ▼                  ▼                      ▼                  │
+│  ┌────────────────────────────────────────────────────────────────┐  │
+│  │                      MAIN LOOP                                  │  │
+│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │  │
+│  │  │ Render   │→ │ Show Menu│→ │ Handle   │→ │ Refresh  │→ LOOP  │  │
+│  │  │ Screen   │  │ (Enquirer)│  │ Selection│  │ Data     │        │  │
+│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘        │  │
+│  └────────────────────────────────────────────────────────────────┘  │
+├──────────────────────────────────────────────────────────────────────┤
+│  ┌───────────────────────────────────────────────────────────────┐   │
+│  │                    RENDER COMPONENTS                           │   │
+│  │  Header: Title bar with desired outcome                        │   │
+│  │  Tension Field: Progress bar, action steps, narrative beats    │   │
+│  │  Footer: Current reality observations                          │   │
+│  │  Status: Error/success message display                         │   │
+│  └───────────────────────────────────────────────────────────────┘   │
+└──────────────────────────────────────────────────────────────────────┘
+        ↓
+  STCWorkspaceClient (HTTP → Miadi Platform /api/stc/*)
+```
+
+### Core Dependencies
+
+| Dependency | Purpose | Import Pattern |
+|------------|---------|----------------|
+| `chalk` | Terminal colors and styling | `import chalk from 'chalk'` |
+| `enquirer` | Interactive prompts (select, input) | `import Enquirer from 'enquirer'` |
+| `child_process.execSync` | Git command execution | `import { execSync } from 'child_process'` |
+| `readline` | TTY detection | `import { createInterface } from 'readline'` |
+
+---
+
+## I - Intent Extraction
+
+### Primary Intent
+
+Enable developers of interactive CLI agents to create **rich terminal dashboards** with:
+
+1. **Full-screen rendering** - Clear screen, draw structured layout
+2. **Interactive menus** - Arrow key navigation, selection
+3. **Real-time updates** - Data refresh on user actions
+4. **Input isolation** - Prevent readline listener conflicts
+5. **Graceful degradation** - Static view when TTY unavailable
+
+### User Stories
+
+1. **As a CLI developer**, I want to create interactive menus so users can navigate complex data without typing commands.
+
+2. **As a terminal user**, I want a visual dashboard showing my progress toward goals with clear visual hierarchy.
+
+3. **As an agent developer**, I want to integrate TUI elements without breaking existing readline-based chat interfaces.
+
+4. **As an operator**, I want dashboards to fail gracefully when run in non-interactive contexts (CI, pipes).
+
+### Success Criteria
+
+- [x] Full-screen terminal rendering with console.clear()
+- [x] Interactive menu with arrow keys via Enquirer
+- [x] Data adapter pattern for server-to-UI transformation
+- [x] TTY detection with read-only fallback
+- [x] Readline listener isolation for integration with chat modes
+- [x] Error and status message display
+- [x] Progress bar visualization
+- [x] Automated sync after mutations
+
+---
+
+## S - Specification
+
+### Class: StructuralTensionDashboard
+
+```typescript
+export class StructuralTensionDashboard {
+  private client: STCWorkspaceClient;
+  private currentChart: STCChart | null;
+  private currentRepo: string | null;
+  private isRunning: boolean;
+  private errorMessage: string | null;
+  private statusMessage: string | null;
+  private isTTY: boolean;
+
+  constructor(repo?: string);
+
+  // Lifecycle
+  public async start(): Promise<void>;
+
+  // Rendering
+  private render(): void;
+  private renderReadOnly(): void;
+  private renderHeader(): void;
+  private renderTensionField(): void;
+  private renderFooter(): void;
+
+  // Interaction
+  private async showMenu(): Promise<void>;
+  private async promptObserve(): Promise<void>;
+  private async promptAction(): Promise<void>;
+  private async promptComplete(): Promise<void>;
+
+  // Data
+  private async refreshData(): Promise<void>;
+  private calculateProgress(actions: RawAction[]): number;
+
+  // Utilities
+  private detectRepositoryFromPath(projectRoot: string): string | undefined;
+  private centerText(text: string, width: number): string;
+}
+```
+
+### Data Adapter Pattern
+
+The dashboard transforms server data structures to UI-friendly formats:
+
+```typescript
+// Server format (FullWorkspaceChart from API)
+interface RawChart {
+  chartId?: string;
+  desiredOutcome?: { observations?: string[] };
+  currentReality?: { observations?: string[] };
+  actions?: RawAction[];
+  narrativeBeats?: RawBeat[];
+  chartEntity?: { metadata?: { createdAt?: string; updatedAt?: string } };
+}
+
+// UI format (STCChart for rendering)
+interface STCChart {
+  id: string;
+  desiredOutcome: string;
+  currentReality: string[];
+  actionSteps: STCActionStep[];
+  narrativeBeats: STCNarrativeBeat[];
+  progress: number;          // Calculated from completed/total
+  createdAt: string;
+  updatedAt: string;
+}
+
+// Adapter function
+function adaptChartData(rawChart: RawChart): STCChart;
+```
+
+### Menu Definition Pattern
+
+```typescript
+const response = await prompt<{ choice: string }>({
+  type: 'select',
+  name: 'choice',
+  message: 'Actions:',
+  choices: [
+    { name: 'observe', message: '👁️  Add Observation', hint: 'Add to current reality' },
+    { name: 'action', message: '⚡ Add Action Step', hint: 'Add to path' },
+    { name: 'complete', message: '✅ Complete Action', hint: 'Mark step done' },
+    { name: 'sync', message: '🔄 Sync & Refresh', hint: 'Force file sync' },
+    { name: 'quit', message: '❌ Quit Dashboard', hint: 'Return to chat' }
+  ]
+});
+```
+
+### TTY Detection & Fallback
+
+```typescript
+constructor(repo?: string) {
+  this.isTTY = process.stdin.isTTY ?? false;
+}
+
+public async start(): Promise<void> {
+  // ...health checks and setup...
+
+  if (!this.isTTY) {
+    console.log(chalk.yellow('\n⚠️  Dashboard requires an interactive terminal.'));
+    console.log(chalk.dim('Run miadi-code directly (not through a pipe) to use the dashboard.'));
+    
+    // Show read-only snapshot instead
+    await this.refreshData();
+    this.renderReadOnly();
+    return;
+  }
+
+  // Interactive mode continues...
+}
+```
+
+### Readline Isolation Pattern
+
+```typescript
+// In cli.ts - before launching dashboard
+case 'dashboard':
+case 'ui':
+  try {
+    requiresFeature(config.engine, 'charts');
+    const dashboard = new StructuralTensionDashboard();
+    
+    // COMPLETELY ISOLATE STDIN - prevent readline conflicts
+    const listeners = rl.listeners('line');
+    rl.removeAllListeners('line');
+    rl.pause();
+    
+    await dashboard.start();
+    
+    // RESTORE LISTENERS after dashboard exits
+    rl.resume();
+    listeners.forEach(l => rl.on('line', l as any));
+    rl.prompt();
+  } catch (e: any) {
+    console.log(formatError(e.message));
+  }
+  break;
+```
+
+### Progress Bar Rendering
+
+```typescript
+function getProgressBar(progress: number, width: number = 20): string {
+  const filled = Math.round(progress * width);
+  const empty = width - filled;
+  return '█'.repeat(filled) + '░'.repeat(empty);
+}
+
+// Usage in render
+const bar = getProgressBar(this.currentChart.progress, 40);
+console.log(` 🚀 PATH PROGRESS: [${chalk.cyan(bar)}] ${Math.round(progress * 100)}%`);
+```
+
+### Full-Screen Layout Structure
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│              STRUCTURAL TENSION INTERFACE                             │
+│━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━│
+│ 🎯 DESIRED OUTCOME: [Goal text from chart]                            │
+│━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━│
+│                                                                       │
+│ 🚀 PATH PROGRESS: [████████████████░░░░] 80%                          │
+│                                                                       │
+│ 🗺️  PATH OF LEAST RESISTANCE (Latest Action Steps):                   │
+│   ✅ Completed action 1                                               │
+│   ✅ Completed action 2                                               │
+│   ⏳ Pending action 3                                                  │
+│   ⏳ Pending action 4                                                  │
+│                                                                       │
+│ 🎭 NARRATIVE BEATS (Latest):                                          │
+│   ✨ [Act 1] Initial setup complete                                   │
+│   ✨ [Act 2] Integration milestone                                    │
+│                                                                       │
+│━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━│
+│ 🧱 CURRENT REALITY (Latest):                                          │
+│   👁️  Observation 1                                                   │
+│   👁️  Observation 2                                                   │
+│   👁️  Observation 3                                                   │
+│━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━│
+│                                                                       │
+│ ✨ [Status message if any]                                            │
+│                                                                       │
+│ ? Actions: (Use arrow keys)                                           │
+│ ❯ 👁️  Add Observation                                                 │
+│   ⚡ Add Action Step                                                   │
+│   ✅ Complete Action                                                   │
+│   🔄 Sync & Refresh                                                    │
+│   ❌ Quit Dashboard                                                    │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## E - Export Optimization
+
+### CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `/dashboard` | Launch interactive TUI dashboard |
+| `/ui` | Alias for /dashboard |
+
+### Programmatic API
+
+```typescript
+import { StructuralTensionDashboard } from './dashboard.js';
+
+// Basic usage
+const dashboard = new StructuralTensionDashboard();
+await dashboard.start();
+
+// With specific repository
+const dashboard = new StructuralTensionDashboard('owner/repo');
+await dashboard.start();
+```
+
+### Integration Pattern for Other CLI Agents
+
+To add a similar dashboard to any CLI agent:
+
+```typescript
+// 1. Create a dashboard class with the pattern
+class MyDashboard {
+  private isRunning = false;
+  private isTTY = process.stdin.isTTY ?? false;
+
+  async start() {
+    if (!this.isTTY) {
+      this.renderReadOnly();
+      return;
+    }
+
+    this.isRunning = true;
+    while (this.isRunning) {
+      this.render();
+      await this.showMenu();
+    }
+  }
+
+  private render() {
+    console.clear();
+    // Draw your UI with chalk
+  }
+
+  private async showMenu() {
+    const { prompt } = Enquirer;
+    const response = await prompt({
+      type: 'select',
+      name: 'choice',
+      message: 'Select:',
+      choices: ['Option 1', 'Option 2', 'Quit']
+    });
+    // Handle selection
+  }
+}
+
+// 2. Isolate readline when launching
+const listeners = rl.listeners('line');
+rl.removeAllListeners('line');
+rl.pause();
+
+await new MyDashboard().start();
+
+rl.resume();
+listeners.forEach(l => rl.on('line', l as any));
+rl.prompt();
+```
+
+### Key Implementation Guidelines
+
+1. **Always check TTY** - `process.stdin.isTTY` before interactive mode
+2. **Use console.clear()** - Full-screen rendering each frame
+3. **Chalk for styling** - Colors, bold, dim for visual hierarchy
+4. **Enquirer for menus** - Handles arrow keys, selection
+5. **Isolate readline** - Pause and restore listeners
+6. **Data adapter pattern** - Transform API data to UI-friendly format
+7. **Status messages** - Temporary feedback after actions
+8. **Error handling** - Display errors without crashing loop
+
+---
+
+## Testing Patterns
+
+### Data Adapter Tests
+
+```typescript
+describe('Dashboard Data Adapter', () => {
+  it('should handle empty chart data', () => {
+    const raw = {};
+    const result = adaptChartData(raw);
+    assert.strictEqual(result.id, 'unknown');
+    assert.strictEqual(result.desiredOutcome, 'No Goal Set');
+  });
+
+  it('should calculate progress correctly', () => {
+    const actions = [
+      { name: 'a1', metadata: { completionStatus: true } },
+      { name: 'a2', metadata: { completionStatus: false } },
+    ];
+    assert.strictEqual(calculateProgress(actions), 0.5);
+  });
+});
+```
+
+### Rendering Helper Tests
+
+```typescript
+describe('Dashboard Rendering Helpers', () => {
+  it('should render progress bar for 50%', () => {
+    const bar = getProgressBar(0.5, 10);
+    assert.strictEqual(bar, '█████░░░░░');
+  });
+});
+```
+
+---
+
+## Known Limitations
+
+1. **Terminal Flickering** - Rapid render cycles may cause visual artifacts
+2. **Settle Delay** - API mutations require 1.5s wait for server sync
+3. **Input Bleeding** - Some terminal multiplexers leak buffered input
+4. **Schema Drift** - Manual adapter updates needed for API changes
+
+---
+
+## Dependencies
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `chalk` | ^5.x | Terminal styling |
+| `enquirer` | ^2.x | Interactive prompts |
+| Node.js | 18+ | TTY support, async/await |
+
+---
+
+## References
+
+- miadi-code implementation: `miadi-code/src/dashboard.ts`
+- Test suite: `miadi-code/src/dashboard.test.ts`
+- CLI integration: `miadi-code/src/cli.ts` (lines 855-875)
+- API client: `miadi-code/src/stc/workspace-client.ts`

package/rispecs/_sync_/miadi-code/dashboard/STATUS.md

@@ -0,0 +1,212 @@
+# Interactive Terminal Dashboard (TUI) - STATUS
+
+**Version**: 1.1
+**Date**: 2026-01-31
+**Status**: ✅ ENHANCED
+
+---
+
+## Implementation Checklist
+
+### ✅ Phase 1: Core Architecture (COMPLETE)
+- [x] Create `src/dashboard.ts` - Main dashboard class
+- [x] Implement TTY detection with fallback
+- [x] Implement repository auto-detection via git remote
+- [x] Implement health check for API availability
+
+### ✅ Phase 2: Rendering System (COMPLETE)
+- [x] Full-screen rendering with `console.clear()`
+- [x] Header with desired outcome display
+- [x] Tension field with progress bar
+- [x] Action steps list (completed/pending)
+- [x] Narrative beats section
+- [x] Footer with current reality observations
+- [x] Status/error message display
+
+### ✅ Phase 3: Interaction Layer (ENHANCED)
+- [x] Menu system with Enquirer
+- [x] Observe action (add observation)
+- [x] Action step addition
+- [x] Action completion via selection menu
+- [x] Sync & refresh operation
+- [x] Quit with graceful cleanup
+- [x] **NEW**: Dynamic menu hints showing operation availability
+- [x] **NEW**: Prerequisite checks before prompting
+
+### ✅ Phase 4: Data Layer (COMPLETE)
+- [x] Data adapter: FullWorkspaceChart → STCChart
+- [x] Progress calculation from action completion
+- [x] Handle nested/complex data structures
+- [x] Graceful handling of missing fields
+
+### ✅ Phase 5: CLI Integration (COMPLETE)
+- [x] `/dashboard` command in cli.ts
+- [x] `/ui` alias
+- [x] Readline listener isolation
+- [x] Listener restoration after exit
+
+### ✅ Phase 6: Testing (COMPLETE)
+- [x] Data adapter tests (11 tests)
+- [x] Progress calculation tests (5 tests)
+- [x] Rendering helper tests (4 tests)
+- [x] Edge case tests (4 tests)
+- [x] Total: 24 dashboard-specific tests passing
+
+---
+
+## Files Created
+
+| File | Purpose | Lines |
+|------|---------|-------|
+| `src/dashboard.ts` | Main dashboard class | ~365 |
+| `src/dashboard.test.ts` | Data adapter & rendering tests | ~355 |
+
+## Files Modified
+
+| File | Changes |
+|------|---------|
+| `src/cli.ts` | Added `/dashboard` and `/ui` command handlers |
+| `src/formatting.ts` | Help text updated (if applicable) |
+
+---
+
+## Feature Summary
+
+### Commands
+| Command | Status |
+|---------|--------|
+| `/dashboard` | ✅ Working |
+| `/ui` | ✅ Working (alias) |
+
+### Capabilities
+| Feature | Status | Notes |
+|---------|--------|-------|
+| Full-screen rendering | ✅ | Uses console.clear() |
+| TTY detection | ✅ | Falls back to read-only |
+| Repo auto-detection | ✅ | Via git remote |
+| Interactive menu | ✅ | Enquirer select |
+| Add observation | ✅ | With auto-sync |
+| Add action step | ✅ | With auto-sync |
+| Complete action | ✅ | Selection from list |
+| Progress visualization | ✅ | Unicode progress bar |
+| Readline isolation | ✅ | Prevents chat conflicts |
+| Error display | ✅ | Non-crashing |
+| Status messages | ✅ | Temporary feedback |
+
+---
+
+## Test Coverage
+
+```
+Dashboard Data Adapter
+  ✓ should handle empty chart data
+  ✓ should extract desired outcome from observations array
+  ✓ should extract current reality observations
+  ✓ should transform action steps correctly
+  ✓ should transform narrative beats correctly
+  ✓ should preserve chart timestamps
+
+calculateProgress
+  ✓ should return 0 for empty actions
+  ✓ should return 0 for no completed actions
+  ✓ should return 1 for all completed actions
+  ✓ should return correct ratio for partial completion
+  ✓ should handle missing metadata gracefully
+
+Dashboard Rendering Helpers
+  ✓ should render empty progress bar for 0%
+  ✓ should render full progress bar for 100%
+  ✓ should render half progress bar for 50%
+  ✓ should handle custom widths
+
+Dashboard Data Edge Cases
+  ✓ should handle actions without observations
+  ✓ should handle narrative beats with nested description
+  ✓ should fall back to observations when narrative.description is missing
+  ✓ should handle real-world complex chart structure
+```
+
+---
+
+## Known Limitations
+
+| Limitation | Description | Mitigation |
+|------------|-------------|------------|
+| Settle delay | 1.5s wait after mutations for server sync | Documented, may improve with WebSocket |
+| Input bleeding | Some terminals leak input after exit | Readline isolation pattern |
+| Flickering | Rapid render cycles cause artifacts | Reduce refresh rate |
+| Schema drift | API changes require adapter updates | Type-safe adapter pattern |
+
+---
+
+## Usage Examples
+
+### Basic Launch
+```bash
+miadi
+> /dashboard
+```
+
+### From Specific Repository
+```bash
+cd /path/to/my/repo
+miadi
+> /dashboard
+# Auto-detects repository from git remote
+```
+
+### Non-TTY Fallback
+```bash
+echo "/dashboard" | miadi
+# Shows read-only snapshot instead of interactive mode
+```
+
+---
+
+## Dependencies
+
+| Package | Version | Used For |
+|---------|---------|----------|
+| `chalk` | ^5.x | Terminal colors |
+| `enquirer` | ^2.x | Interactive menus |
+| Node.js | 18+ | TTY support |
+
+---
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    /dashboard command                        │
+└────────────────────────────┬────────────────────────────────┘
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────────┐
+│              StructuralTensionDashboard                      │
+│  ┌────────────┐  ┌────────────┐  ┌────────────┐             │
+│  │ TTY Check  │  │ Health     │  │ Repo       │             │
+│  │            │  │ Check      │  │ Detection  │             │
+│  └─────┬──────┘  └─────┬──────┘  └─────┬──────┘             │
+│        │               │               │                     │
+│        └───────────────┼───────────────┘                     │
+│                        │                                     │
+│                        ▼                                     │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │                   MAIN LOOP                          │    │
+│  │                                                      │    │
+│  │   render() → showMenu() → handleAction() → refresh() │    │
+│  │       ↑                                       │       │    │
+│  │       └───────────────────────────────────────┘       │    │
+│  └─────────────────────────────────────────────────────┘    │
+│                        │                                     │
+│                        ▼                                     │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │              STCWorkspaceClient                      │    │
+│  │  HTTP → Miadi Platform /api/stc/*                    │    │
+│  └─────────────────────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+**Last Updated**: 2026-01-31T20:00:00Z