agileflow 2.90.7 → 2.92.0

package/scripts/tui/blessed/panels/trace.js

@@ -0,0 +1,97 @@
+'use strict';
+
+const blessed = require('blessed');
+
+/**
+ * Create the trace panel showing execution steps
+ */
+module.exports = function createTracePanel(grid, state) {
+  const box = blessed.box({
+    parent: grid.screen,
+    top: 3,
+    left: 0,
+    width: '100%',
+    height: '100%-4',
+    label: ' {yellow-fg}{bold}Trace{/bold}{/yellow-fg} ',
+    tags: true,
+    border: {
+      type: 'line',
+      fg: 'yellow',
+    },
+    style: {
+      fg: 'white',
+      bg: 'black',
+      border: { fg: 'yellow' },
+    },
+    scrollable: true,
+    alwaysScroll: true,
+    scrollbar: {
+      ch: '│',
+      style: { fg: 'yellow' },
+    },
+    keys: true,
+    vi: true,
+  });
+
+  let traces = [];
+
+  function render() {
+    if (traces.length === 0) {
+      box.setContent(`
+  {gray-fg}No trace data{/}
+
+  {yellow-fg}What shows here:{/}
+  • Active command execution
+  • Step-by-step agent workflow
+  • Tool calls and responses
+  • Timing information
+
+  {gray-fg}Trace data comes from .agileflow/session-state.json{/}
+      `);
+      return;
+    }
+
+    let lines = [];
+    traces.forEach((t, i) => {
+      // Status indicator
+      let statusIcon = '{gray-fg}○{/}';
+      if (t.status === 'running') statusIcon = '{yellow-fg}◉{/}';
+      else if (t.status === 'completed') statusIcon = '{green-fg}●{/}';
+      else if (t.status === 'error') statusIcon = '{red-fg}✖{/}';
+
+      const stepNum = String(i + 1).padStart(2, '0');
+      const action = (t.action || 'Unknown').substring(0, 40);
+      const duration = t.duration || '--';
+
+      lines.push(`  ${statusIcon} Step ${stepNum}: {bold}${action}{/}`);
+      if (t.details) {
+        lines.push(`           {gray-fg}${t.details.substring(0, 60)}{/}`);
+      }
+      lines.push(`           {gray-fg}Duration: ${duration}{/}`);
+      lines.push('');
+    });
+
+    box.setContent(lines.join('\n'));
+  }
+
+  return {
+    element: box,
+    show() {
+      box.show();
+    },
+    hide() {
+      box.hide();
+    },
+    focus() {
+      box.focus();
+    },
+    setData(data) {
+      traces = data || [];
+      render();
+    },
+    addStep(action, status = 'running', details = '') {
+      traces.push({ action, status, details, duration: '--' });
+      render();
+    },
+  };
+};

package/scripts/tui/blessed/ui/help.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const blessed = require('blessed');
+
+/**
+ * Create the help overlay that shows all available commands
+ * Toggled with ? or h key
+ */
+module.exports = function createHelpOverlay(screen, state) {
+  const help = blessed.box({
+    parent: screen,
+    top: 'center',
+    left: 'center',
+    width: 55,
+    height: 22,
+    tags: true,
+    border: { type: 'line', fg: 'yellow' },
+    style: {
+      fg: 'white',
+      bg: 'black',
+      border: { fg: 'yellow' },
+    },
+    label: ' {yellow-fg}Help{/yellow-fg} ',
+    hidden: true,
+    content: `
+{bold}Navigation{/bold}
+  {cyan-fg}1{/}         Sessions tab
+  {cyan-fg}2{/}         Output tab
+  {cyan-fg}3{/}         Trace tab
+  {cyan-fg}Tab{/}       Next tab
+  {cyan-fg}j/k or {/}{cyan-fg}arrow-down/arrow-up{/} Navigate list items
+  {cyan-fg}Enter{/}     Select item
+
+{bold}Actions{/bold}
+  {cyan-fg}r{/}         Refresh data
+  {cyan-fg}s{/}         Start loop on current story
+  {cyan-fg}p{/}         Pause active loop
+
+{bold}Display{/bold}
+  {cyan-fg}?{/} or {cyan-fg}h{/}   Toggle this help
+  {cyan-fg}Escape{/}    Close help/dialogs
+
+{bold}Exit{/bold}
+  {cyan-fg}q{/}         Quit TUI
+  {cyan-fg}Ctrl+C{/}    Force quit
+
+{gray-fg}Press Escape or ? to close{/gray-fg}`,
+  });
+
+  // Close help on various keys
+  help.key(['escape', 'q', '?', 'h', 'enter', 'space'], () => {
+    help.hide();
+    screen.render();
+  });
+
+  return {
+    element: help,
+    toggle() {
+      if (help.hidden) {
+        help.show();
+        help.focus();
+      } else {
+        help.hide();
+      }
+    },
+    show() {
+      help.show();
+      help.focus();
+    },
+    hide() {
+      help.hide();
+    },
+    isVisible() {
+      return !help.hidden;
+    },
+  };
+};

package/scripts/tui/blessed/ui/screen.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const blessed = require('blessed');
+
+/**
+ * Create the main blessed screen with flicker-free rendering
+ *
+ * Key settings:
+ * - smartCSR: Enable differential rendering (only update changed cells)
+ * - fullUnicode: Support Unicode characters like box drawing
+ */
+module.exports = function createScreen() {
+  const screen = blessed.screen({
+    smartCSR: true, // Key for flicker-free differential rendering
+    fullUnicode: true, // Support Unicode characters
+    title: 'AgileFlow TUI',
+    cursor: {
+      artificial: true,
+      blink: true,
+      shape: 'line',
+    },
+    debug: false,
+    warnings: false,
+    autoPadding: true,
+    dockBorders: true,
+  });
+
+  // Enable synchronized output mode for atomic updates
+  // This batches all screen updates and flushes them at once
+  // Note: Not all terminals support this, but it gracefully degrades
+  try {
+    process.stdout.write('\x1b[?2026h');
+  } catch (e) {
+    // Ignore if terminal doesn't support
+  }
+
+  // Disable synchronized output on exit
+  process.on('exit', () => {
+    try {
+      process.stdout.write('\x1b[?2026l');
+    } catch (e) {
+      // Ignore
+    }
+  });
+
+  // Handle resize gracefully
+  screen.on('resize', () => {
+    screen.render();
+  });
+
+  return screen;
+};

package/scripts/tui/blessed/ui/statusbar.js

@@ -0,0 +1,47 @@
+'use strict';
+
+const blessed = require('blessed');
+
+/**
+ * Create the status bar at the bottom with always-visible key hints
+ * nano-style: users can always see what keys are available
+ */
+module.exports = function createStatusBar(screen, state) {
+  const statusBar = blessed.box({
+    parent: screen,
+    bottom: 0,
+    left: 0,
+    width: '100%',
+    height: 1,
+    tags: true,
+    style: {
+      fg: 'white',
+      bg: 'blue',
+    },
+  });
+
+  // Always-visible key hints (nano-style for user-friendliness)
+  const hints = [
+    '{bold}1-3{/bold}:Tab',
+    '{bold}Tab{/bold}:Next',
+    '{bold}j/k{/bold}:Nav',
+    '{bold}r{/bold}:Refresh',
+    '{bold}?{/bold}:Help',
+    '{bold}q{/bold}:Quit',
+  ];
+
+  const hintText = ' ' + hints.join('  ');
+  statusBar.setContent(hintText);
+
+  return {
+    element: statusBar,
+    setStatus(text) {
+      // Show custom status with key hints
+      const shortHints = ['{bold}r{/bold}:Refresh', '{bold}?{/bold}:Help', '{bold}q{/bold}:Quit'];
+      statusBar.setContent(` ${text}  |  ${shortHints.join('  ')}`);
+    },
+    resetHints() {
+      statusBar.setContent(hintText);
+    },
+  };
+};

package/scripts/tui/blessed/ui/tabbar.js

@@ -0,0 +1,99 @@
+'use strict';
+
+const blessed = require('blessed');
+
+/**
+ * Create a proper styled tab bar with visual distinction
+ */
+module.exports = function createTabBar(screen, state) {
+  // Header bar background
+  const header = blessed.box({
+    parent: screen,
+    top: 0,
+    left: 0,
+    width: '100%',
+    height: 3,
+    style: {
+      bg: 'black',
+    },
+  });
+
+  // Logo/title
+  blessed.box({
+    parent: header,
+    top: 0,
+    left: 0,
+    width: 20,
+    height: 3,
+    content: '{bold}{#e8683a-fg}▄▀▄ AgileFlow{/}',
+    tags: true,
+    style: {
+      bg: 'black',
+    },
+  });
+
+  // Tab container
+  const tabContainer = blessed.box({
+    parent: header,
+    top: 0,
+    left: 20,
+    width: '100%-20',
+    height: 3,
+    style: {
+      bg: 'black',
+    },
+  });
+
+  // Create styled tabs
+  const tabs = state.tabs.map((name, i) => {
+    const tab = blessed.box({
+      parent: tabContainer,
+      top: 1,
+      left: i * 18,
+      width: 16,
+      height: 1,
+      content: `[${i + 1}] ${name}`,
+      tags: true,
+      style: {
+        fg: 'white',
+        bg: 'black',
+      },
+    });
+    return tab;
+  });
+
+  // Version info on right
+  blessed.box({
+    parent: header,
+    top: 1,
+    right: 1,
+    width: 12,
+    height: 1,
+    content: '{gray-fg}v2.90.7{/}',
+    tags: true,
+    style: {
+      bg: 'black',
+    },
+  });
+
+  return {
+    element: header,
+    setTab(index) {
+      tabs.forEach((tab, i) => {
+        if (i === index) {
+          // Active tab - cyan background, black text, with brackets
+          tab.style.fg = 'black';
+          tab.style.bg = 'cyan';
+          tab.style.bold = true;
+          tab.setContent(`▶ ${state.tabs[i]} ◀`);
+        } else {
+          // Inactive tabs
+          tab.style.fg = 'gray';
+          tab.style.bg = 'black';
+          tab.style.bold = false;
+          tab.setContent(`[${i + 1}] ${state.tabs[i]}`);
+        }
+      });
+    },
+  };
+};

package/scripts/tui/index.js

@@ -4,50 +4,58 @@
 /**
  * AgileFlow TUI - Terminal User Interface
  *
- * Real-time visualization for session monitoring, multi-agent orchestration,
- * and interactive loop control.
+ * Full-screen, flicker-free dashboard for session monitoring, multi-agent
+ * orchestration, and interactive workflow control.
  *
  * Usage:
  *   node scripts/tui/index.js
  *   npx agileflow tui
+ *   npx agileflow tui --fallback  (use simple ANSI version)
  *
  * Key bindings:
- *   q - Quit TUI
- *   s - Start loop on current story
- *   p - Pause active loop
- *   r - Resume paused loop
- *   t - Toggle trace panel
- *   1-9 - Switch session focus
+ *   1-3       Switch tabs (Sessions, Output, Trace)
+ *   Tab       Next tab
+ *   j/k       Navigate list items
+ *   r         Refresh data
+ *   ?/h       Toggle help overlay
+ *   q         Quit TUI
  */
 
-// Use simple-tui (pure Node.js) - Ink has React version conflicts in monorepo
-const useInk = false;
+// Check for --fallback flag
+const useFallback = process.argv.includes('--fallback') || process.argv.includes('--simple');
 
 /**
  * Main entry point
  */
 async function main() {
-  if (useInk) {
-    // Use the React/Ink-based Dashboard for modern terminals
-    const React = require('react');
-    const { render } = require('ink');
-    const { Dashboard } = require('./Dashboard');
-
-    // Handle actions from the dashboard
-    const handleAction = action => {
-      // TODO: Implement loop control actions
-      // console.log('Action:', action);
-    };
-
-    // Render the dashboard
-    const { waitUntilExit } = render(React.createElement(Dashboard, { onAction: handleAction }));
-
-    // Wait for exit
-    await waitUntilExit();
+  if (useFallback) {
+    // Use simple TUI (pure Node.js ANSI codes, no dependencies)
+    try {
+      const { main: simpleTuiMain } = require('./simple-tui');
+      simpleTuiMain();
+    } catch (err) {
+      console.error('Simple TUI Error:', err.message);
+      process.exit(1);
+    }
   } else {
-    // Use simple TUI (pure Node.js, no React dependencies)
-    const { main: simpleTuiMain } = require('./simple-tui');
-    simpleTuiMain();
+    // Use blessed TUI (professional full-screen interface)
+    try {
+      const { main: blessedMain } = require('./blessed');
+      blessedMain();
+    } catch (err) {
+      // If blessed fails (missing deps, terminal issues), fall back to simple
+      console.error('Blessed TUI failed to load:', err.message);
+      console.error('Falling back to simple TUI...\n');
+
+      try {
+        const { main: simpleTuiMain } = require('./simple-tui');
+        simpleTuiMain();
+      } catch (fallbackErr) {
+        console.error('Fallback TUI also failed:', fallbackErr.message);
+        console.error('\nTry running with: npx agileflow status');
+        process.exit(1);
+      }
+    }
   }
 }
 

package/scripts/validators/README.md

@@ -0,0 +1,143 @@
+# Validators
+
+Specialized self-validation scripts for AgileFlow agents.
+
+## Overview
+
+Validators are Node.js scripts that run via hooks to verify agent output. They enable **closed-loop prompts** where validation is guaranteed, not optional.
+
+**Research**: See [ADR-0009](../../../docs/03-decisions/adr-0009-specialized-self-validating-agents.md)
+
+---
+
+## Exit Codes
+
+| Code | Meaning | Behavior |
+|------|---------|----------|
+| `0` | Success | Proceed normally |
+| `2` | Error (blocking) | Stderr sent to Claude for self-correction |
+| Other | Warning | Log but continue |
+
+**Exit code 2 is special**: Claude receives stderr output and automatically attempts to fix the issue.
+
+---
+
+## Input Format
+
+Validators receive JSON via stdin with tool context:
+
+```json
+{
+  "tool_name": "Write",
+  "tool_input": {
+    "file_path": "/path/to/file.json",
+    "content": "..."
+  },
+  "result": "File written successfully"
+}
+```
+
+---
+
+## Validator Template
+
+```javascript
+#!/usr/bin/env node
+const fs = require('fs');
+
+let input = '';
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const context = JSON.parse(input);
+    const filePath = context.tool_input?.file_path;
+
+    if (!filePath) {
+      console.log('No file path in context, skipping');
+      process.exit(0);
+    }
+
+    // Your validation logic here
+    const issues = validate(filePath);
+
+    if (issues.length > 0) {
+      // Exit 2 = Claude will try to fix these
+      console.error(`Resolve these issues in ${filePath}:`);
+      issues.forEach(i => console.error(`  - ${i}`));
+      process.exit(2);
+    }
+
+    console.log(`Validation passed: ${filePath}`);
+    process.exit(0);
+  } catch (e) {
+    // Exit 1 = warning, don't block
+    console.error(`Validator error: ${e.message}`);
+    process.exit(1);
+  }
+});
+
+function validate(filePath) {
+  const issues = [];
+  // Add your checks here
+  return issues;
+}
+```
+
+---
+
+## Hook Configuration
+
+Add hooks to agent/command frontmatter:
+
+### PostToolUse (after each tool call)
+
+```yaml
+hooks:
+  PostToolUse:
+    - matcher: "Write"
+      hooks:
+        - type: command
+          command: "node .agileflow/hooks/validators/your-validator.js"
+```
+
+### Stop (when agent finishes)
+
+```yaml
+hooks:
+  Stop:
+    - hooks:
+        - type: command
+          command: "node .agileflow/hooks/validators/final-validator.js"
+```
+
+---
+
+## Best Practices
+
+1. **Keep validators fast** (< 100ms) - they run on every matching tool call
+2. **Use specific matchers** - `"Write"` not `"Write|Edit|Read"`
+3. **Return helpful errors** - Claude uses stderr to fix issues
+4. **Test standalone first** - `echo '{"tool_input":{"file_path":"test.json"}}' | node validator.js`
+5. **Log success too** - helps debugging hook chains
+
+---
+
+## Available Validators
+
+| Validator | Purpose | Matcher |
+|-----------|---------|---------|
+| `json-schema-validator.js` | Validate JSON structure | Write (*.json) |
+| `markdown-validator.js` | Validate markdown format | Write (*.md) |
+| `story-format-validator.js` | Validate story structure | Write (status.json) |
+
+---
+
+## Testing Validators
+
+```bash
+# Test with sample input
+echo '{"tool_name":"Write","tool_input":{"file_path":"test.json","content":"{}"}}' | node json-schema-validator.js
+
+# Check exit code
+echo $?
+```