agileflow 2.90.6 → 2.91.0

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

@@ -0,0 +1,51 @@
+'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,52 +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
  */
 
-// Ink-based TUI is disabled due to React version conflicts in monorepo
-// The simple-tui provides responsive layouts and works reliably
-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 {
-    // Fallback to simple TUI (pure Node.js, no React)
-    console.log('React/Ink not available, using simple TUI...');
-    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/tui/simple-tui.js

@@ -55,6 +55,7 @@ const ANSI = {
   showCursor: '\x1b[?25h',
   saveCursor: '\x1b[s',
   restoreCursor: '\x1b[u',
+  clearLine: '\x1b[K', // Clear from cursor to end of line
 };
 
 // Get project root
@@ -213,7 +214,8 @@ class SimpleTUI {
       this.render();
     });
 
-    // Initial render
+    // Clear screen once at start, then render
+    process.stdout.write(ANSI.clear + ANSI.home);
     this.render();
 
     // Update loop
@@ -290,8 +292,8 @@ class SimpleTUI {
     const height = process.stdout.rows || 24;
     const output = [];
 
-    // Clear screen
-    output.push(ANSI.clear + ANSI.home);
+    // Move to home position (don't clear - prevents bouncing)
+    output.push(ANSI.home);
 
     // Determine layout mode based on terminal width
     const isWide = width >= 100;
@@ -317,8 +319,9 @@ class SimpleTUI {
       this.renderStacked(output, width, height, sessions, loopStatus, agentEvents, isNarrow);
     }
 
-    // Output everything
-    process.stdout.write(output.join('\n'));
+    // Output everything with line clearing to prevent artifacts
+    const outputWithClear = output.map(line => line + ANSI.clearLine);
+    process.stdout.write(outputWithClear.join('\n'));
   }
 
   renderSideBySide(output, width, height, sessions, loopStatus, agentEvents) {

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 $?
+```

package/scripts/validators/component-validator.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+/**
+ * Component Validator
+ *
+ * Validates React/Vue/Svelte component files for common issues.
+ *
+ * Exit codes:
+ *   0 = Success
+ *   2 = Error (Claude will attempt to fix)
+ *   1 = Warning (logged but not blocking)
+ *
+ * Usage in agent hooks:
+ *   hooks:
+ *     PostToolUse:
+ *       - matcher: "Write"
+ *         hooks:
+ *           - type: command
+ *             command: "node .agileflow/hooks/validators/component-validator.js"
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+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;
+
+    // Only validate component files
+    if (!filePath || !isComponentFile(filePath)) {
+      process.exit(0);
+    }
+
+    // Skip if file doesn't exist
+    if (!fs.existsSync(filePath)) {
+      console.log(`File not found: ${filePath} (skipping validation)`);
+      process.exit(0);
+    }
+
+    const issues = validateComponent(filePath);
+
+    if (issues.length > 0) {
+      console.error(`Fix these component issues in ${filePath}:`);
+      issues.forEach(i => console.error(`  - ${i}`));
+      process.exit(2); // Claude will fix
+    }
+
+    console.log(`Component validation passed: ${filePath}`);
+    process.exit(0);
+  } catch (e) {
+    console.error(`Validator error: ${e.message}`);
+    process.exit(1);
+  }
+});
+
+function isComponentFile(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  const componentExtensions = ['.jsx', '.tsx', '.vue', '.svelte'];
+
+  // Also check for .js/.ts files in component directories
+  if (['.js', '.ts'].includes(ext)) {
+    const normalizedPath = filePath.toLowerCase();
+    return normalizedPath.includes('/components/') ||
+           normalizedPath.includes('/pages/') ||
+           normalizedPath.includes('/views/');
+  }
+
+  return componentExtensions.includes(ext);
+}
+
+function validateComponent(filePath) {
+  const issues = [];
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const ext = path.extname(filePath).toLowerCase();
+    const fileName = path.basename(filePath, ext);
+
+    // Check for empty component
+    if (!content.trim()) {
+      issues.push('Component file is empty');
+      return issues;
+    }
+
+    // React/JSX/TSX validation
+    if (['.jsx', '.tsx'].includes(ext) || content.includes('React')) {
+      issues.push(...validateReactComponent(content, fileName));
+    }
+
+    // Vue validation
+    if (ext === '.vue') {
+      issues.push(...validateVueComponent(content));
+    }
+
+    // Svelte validation
+    if (ext === '.svelte') {
+      issues.push(...validateSvelteComponent(content));
+    }
+
+    // General accessibility checks
+    issues.push(...validateAccessibility(content));
+
+  } catch (e) {
+    issues.push(`Read error: ${e.message}`);
+  }
+
+  return issues;
+}
+
+function validateReactComponent(content, fileName) {
+  const issues = [];
+
+  // Check for component export
+  if (!content.includes('export default') && !content.includes('export function') && !content.includes('export const')) {
+    issues.push('Component should have an export (export default, export function, or export const)');
+  }
+
+  // Check for React import in JSX files
+  if (content.includes('React.') && !content.includes("from 'react'") && !content.includes('from "react"')) {
+    issues.push('Using React. prefix but React is not imported');
+  }
+
+  // Check for proper function/component naming (should match filename for default exports)
+  const pascalCaseRegex = /^[A-Z][a-zA-Z0-9]*$/;
+  if (!pascalCaseRegex.test(fileName) && !fileName.startsWith('use')) {
+    // Only warn, don't block - could be a utility file
+    console.log(`Note: Component filename "${fileName}" should be PascalCase`);
+  }
+
+  // Check for inline styles (prefer CSS modules or styled-components)
+  const inlineStyleCount = (content.match(/style=\{\{/g) || []).length;
+  if (inlineStyleCount > 5) {
+    issues.push(`Too many inline styles (${inlineStyleCount}) - consider using CSS modules or styled-components`);
+  }
+
+  // Check for console.log in production code
+  if (content.includes('console.log') && !content.includes('// debug') && !content.includes('// DEBUG')) {
+    console.log('Note: console.log found - ensure it\'s removed before production');
+  }
+
+  // Check for missing key prop in map
+  if (content.includes('.map(') && content.includes('<') && !content.includes('key=')) {
+    issues.push('Array .map() rendering elements should include key prop');
+  }
+
+  return issues;
+}
+
+function validateVueComponent(content) {
+  const issues = [];
+
+  // Check for required template section
+  if (!content.includes('<template>') && !content.includes('<template ')) {
+    issues.push('Vue component must have a <template> section');
+  }
+
+  // Check for script section
+  if (!content.includes('<script') && !content.includes('<script>')) {
+    // Not strictly required but recommended
+    console.log('Note: Vue component has no <script> section');
+  }
+
+  // Check for scoped styles (recommended)
+  if (content.includes('<style>') && !content.includes('<style scoped') && !content.includes('scoped>')) {
+    console.log('Note: Consider using scoped styles to prevent CSS leaks');
+  }
+
+  return issues;
+}
+
+function validateSvelteComponent(content) {
+  const issues = [];
+
+  // Check for script section
+  if (!content.includes('<script') && !content.includes('<script>')) {
+    console.log('Note: Svelte component has no <script> section');
+  }
+
+  return issues;
+}
+
+function validateAccessibility(content) {
+  const issues = [];
+
+  // Check for images without alt
+  const imgWithoutAlt = content.match(/<img[^>]*(?!alt=)[^>]*>/gi) || [];
+  const imgWithEmptyAlt = content.match(/<img[^>]*alt=["']["'][^>]*>/gi) || [];
+
+  if (imgWithoutAlt.length > 0) {
+    issues.push(`Found ${imgWithoutAlt.length} <img> tag(s) without alt attribute`);
+  }
+
+  // Check for button without type
+  if (content.includes('<button') && !content.includes('type=')) {
+    console.log('Note: <button> elements should have explicit type attribute');
+  }
+
+  // Check for click handlers on non-interactive elements
+  const clickOnDiv = content.match(/onClick[^>]*>[^<]*<\/div>/gi) || [];
+  if (clickOnDiv.length > 0) {
+    issues.push('onClick on <div> detected - use <button> for interactive elements (accessibility)');
+  }
+
+  // Check for form inputs without labels
+  if (content.includes('<input') && !content.includes('<label') && !content.includes('aria-label')) {
+    console.log('Note: <input> elements should have associated <label> or aria-label');
+  }
+
+  return issues;
+}