@pennyfarthing/core 11.3.8 → 11.5.0-alpha.0

package/packages/core/src/public/utils/syntax.ts

@@ -0,0 +1,219 @@
+/**
+ * Syntax Highlighting Utilities
+ *
+ * Story MSSCI-13970: TypeScript syntax highlighting utilities extracted from
+ * js/components/message-view/syntax-highlighter.js
+ *
+ * Features:
+ * - Tokenizer-based highlighting (avoids regex conflicts)
+ * - Multi-language support: JS/TS, Python, Go, Rust, Bash
+ * - Theme-aware via CSS classes
+ */
+
+// Keyword sets by language family
+const jsKeywords = new Set([
+  'const', 'let', 'var', 'function', 'return', 'if', 'else', 'for', 'while',
+  'do', 'switch', 'case', 'break', 'continue', 'new', 'this', 'class',
+  'extends', 'import', 'export', 'from', 'default', 'async', 'await', 'try',
+  'catch', 'finally', 'throw', 'typeof', 'instanceof', 'in', 'of', 'true',
+  'false', 'null', 'undefined', 'void',
+]);
+
+const pyKeywords = new Set([
+  'def', 'class', 'return', 'if', 'elif', 'else', 'for', 'while', 'break',
+  'continue', 'import', 'from', 'as', 'try', 'except', 'finally', 'raise',
+  'with', 'lambda', 'yield', 'True', 'False', 'None', 'and', 'or', 'not',
+  'in', 'is', 'pass', 'self',
+]);
+
+const goKeywords = new Set([
+  'func', 'return', 'if', 'else', 'for', 'range', 'switch', 'case', 'break',
+  'continue', 'go', 'defer', 'chan', 'select', 'type', 'struct', 'interface',
+  'map', 'package', 'import', 'var', 'const', 'true', 'false', 'nil', 'make',
+  'new', 'append', 'len', 'cap', 'error',
+]);
+
+const rustKeywords = new Set([
+  'fn', 'let', 'mut', 'return', 'if', 'else', 'for', 'while', 'loop', 'match',
+  'break', 'continue', 'impl', 'struct', 'enum', 'trait', 'pub', 'use', 'mod',
+  'crate', 'self', 'super', 'where', 'async', 'await', 'true', 'false', 'Some',
+  'None', 'Ok', 'Err',
+]);
+
+const shKeywords = new Set([
+  'if', 'then', 'else', 'elif', 'fi', 'for', 'while', 'do', 'done', 'case',
+  'esac', 'function', 'return', 'exit', 'export', 'source', 'alias', 'cd',
+  'echo', 'printf', 'read', 'local',
+]);
+
+/**
+ * Supported language identifiers for syntax highlighting.
+ */
+export type SupportedLanguage =
+  | 'js' | 'javascript' | 'ts' | 'typescript' | 'jsx' | 'tsx'
+  | 'python' | 'py'
+  | 'go' | 'golang'
+  | 'rust' | 'rs'
+  | 'bash' | 'sh' | 'shell' | 'zsh';
+
+/**
+ * Get keywords set for a language.
+ * @param lang - Language identifier
+ * @returns Keywords for the language, or empty set if unsupported
+ */
+export function getKeywordsForLanguage(lang: string): Set<string> {
+  const language = lang.toLowerCase();
+
+  if (['js', 'javascript', 'ts', 'typescript', 'jsx', 'tsx'].includes(language)) {
+    return jsKeywords;
+  }
+  if (['python', 'py'].includes(language)) {
+    return pyKeywords;
+  }
+  if (['go', 'golang'].includes(language)) {
+    return goKeywords;
+  }
+  if (['rust', 'rs'].includes(language)) {
+    return rustKeywords;
+  }
+  if (['bash', 'sh', 'shell', 'zsh'].includes(language)) {
+    return shKeywords;
+  }
+
+  return new Set();
+}
+
+/**
+ * Check if a language is supported for syntax highlighting.
+ * @param lang - Language identifier
+ * @returns true if language is supported
+ */
+export function isSupportedLanguage(lang: string): boolean {
+  return getKeywordsForLanguage(lang).size > 0;
+}
+
+/**
+ * Check if language uses // for comments.
+ * @param lang - Language identifier
+ * @returns true if language uses slash comments
+ */
+function usesSlashComments(lang: string): boolean {
+  const language = lang.toLowerCase();
+  return ['js', 'javascript', 'ts', 'typescript', 'jsx', 'tsx', 'go', 'golang', 'rust', 'rs'].includes(language);
+}
+
+/**
+ * Check if language uses # for comments.
+ * @param lang - Language identifier
+ * @returns true if language uses hash comments
+ */
+function usesHashComments(lang: string): boolean {
+  const language = lang.toLowerCase();
+  return ['python', 'py', 'bash', 'sh', 'shell', 'zsh'].includes(language);
+}
+
+/**
+ * Highlight a single line of code using tokenizer approach.
+ * @param line - Line to highlight (already HTML-escaped)
+ * @param keywords - Keywords set for the language
+ * @param lang - Language for comment detection
+ * @returns HTML with highlighting spans
+ */
+function highlightLine(line: string, keywords: Set<string>, lang: string): string {
+  if (!line.trim()) return line;
+
+  // Handle full-line comments
+  const trimmed = line.trim();
+  if (usesSlashComments(lang) && trimmed.startsWith('//')) {
+    return `<span class="comment">${line}</span>`;
+  }
+  if (usesHashComments(lang) && trimmed.startsWith('#')) {
+    return `<span class="comment">${line}</span>`;
+  }
+
+  // Tokenize the line character by character
+  let result = '';
+  let i = 0;
+
+  while (i < line.length) {
+    // Check for HTML-escaped double quote string: &quot;...&quot;
+    if (line.slice(i, i + 6) === '&quot;') {
+      const endIdx = line.indexOf('&quot;', i + 6);
+      if (endIdx !== -1) {
+        result += `<span class="string">${line.slice(i, endIdx + 6)}</span>`;
+        i = endIdx + 6;
+        continue;
+      }
+    }
+
+    // Check for HTML-escaped single quote string: &#39;...&#39; or &#039;...&#039;
+    if (line.slice(i, i + 5) === '&#39;' || line.slice(i, i + 6) === '&#039;') {
+      const quoteLen = line.slice(i, i + 6) === '&#039;' ? 6 : 5;
+      const quote = line.slice(i, i + quoteLen);
+      const endIdx = line.indexOf(quote, i + quoteLen);
+      if (endIdx !== -1) {
+        result += `<span class="string">${line.slice(i, endIdx + quoteLen)}</span>`;
+        i = endIdx + quoteLen;
+        continue;
+      }
+    }
+
+    // Check for word (identifier/keyword)
+    if (/[a-zA-Z_]/.test(line[i])) {
+      let word = '';
+      while (i < line.length && /[a-zA-Z0-9_]/.test(line[i])) {
+        word += line[i];
+        i++;
+      }
+      if (keywords.has(word)) {
+        result += `<span class="keyword">${word}</span>`;
+      } else if (line[i] === '(') {
+        result += `<span class="function">${word}</span>`;
+      } else {
+        result += word;
+      }
+      continue;
+    }
+
+    // Check for number
+    if (/[0-9]/.test(line[i])) {
+      let num = '';
+      while (i < line.length && /[0-9.]/.test(line[i])) {
+        num += line[i];
+        i++;
+      }
+      result += `<span class="number">${num}</span>`;
+      continue;
+    }
+
+    // Default: pass through character
+    result += line[i];
+    i++;
+  }
+
+  return result;
+}
+
+/**
+ * Highlight code with syntax highlighting.
+ * @param code - The code to highlight (already HTML escaped)
+ * @param lang - Language identifier (js, ts, python, etc.)
+ * @returns HTML with syntax highlighting spans
+ */
+export function highlightCode(code: string, lang: string): string {
+  if (!code || !lang) return code || '';
+
+  const keywords = getKeywordsForLanguage(lang);
+
+  // Process line by line
+  const lines = code.split('\n');
+  const highlightedLines = lines.map((line) => highlightLine(line, keywords, lang));
+
+  return highlightedLines.join('\n');
+}
+
+export default {
+  highlightCode,
+  getKeywordsForLanguage,
+  isSupportedLanguage,
+};

package/packages/core/src/public/utils/toolIntentSummarizer.ts

@@ -0,0 +1,199 @@
+/**
+ * Tool Intent Summarizer
+ *
+ * Story 74-1: Generates human-readable summaries of tool use intent.
+ */
+
+const MAX_LENGTH = 70;
+
+/**
+ * Truncates a string to the max length, adding ellipsis if needed.
+ * Also removes newlines to ensure single-line output.
+ */
+function truncate(str: string, maxLen: number = MAX_LENGTH - 10): string {
+  // Replace newlines with spaces for single-line output
+  const singleLine = str.replace(/\n/g, ' ');
+  if (singleLine.length <= maxLen) return singleLine;
+  return singleLine.slice(0, maxLen - 3) + '...';
+}
+
+/**
+ * Safely gets a string value from input, returning empty string for null/undefined.
+ */
+function getString(input: Record<string, unknown> | null | undefined, key: string): string {
+  if (!input) return '';
+  const value = input[key];
+  if (value === null || value === undefined || value === '') return '';
+  return String(value);
+}
+
+/**
+ * Extracts the hostname from a URL.
+ */
+function extractHostname(url: string): string {
+  try {
+    const parsed = new URL(url);
+    return parsed.hostname;
+  } catch {
+    return url;
+  }
+}
+
+/**
+ * Detects special bash command patterns and returns a semantic summary.
+ */
+function summarizeBashCommand(command: string): string {
+  const cmd = command.toLowerCase();
+
+  // Package install commands
+  if (
+    cmd.startsWith('npm install') ||
+    cmd.startsWith('npm i ') ||
+    cmd === 'npm i' ||
+    cmd.startsWith('pnpm install') ||
+    cmd.startsWith('pnpm add') ||
+    cmd.startsWith('yarn install') ||
+    cmd.startsWith('yarn add')
+  ) {
+    return 'Installing dependencies';
+  }
+
+  // Test commands
+  if (
+    cmd.startsWith('npm test') ||
+    cmd.startsWith('npm run test') ||
+    cmd.startsWith('pnpm test') ||
+    cmd.startsWith('pnpm run test') ||
+    cmd.startsWith('yarn test') ||
+    cmd.startsWith('vitest') ||
+    cmd.startsWith('jest')
+  ) {
+    return 'Running tests';
+  }
+
+  // Build commands
+  if (
+    cmd.startsWith('npm run build') ||
+    cmd.startsWith('pnpm run build') ||
+    cmd.startsWith('pnpm build') ||
+    cmd.startsWith('yarn build')
+  ) {
+    return 'Building project';
+  }
+
+  // TypeScript type checking
+  if (cmd.startsWith('tsc')) {
+    return 'Type checking';
+  }
+
+  // Linting
+  if (cmd.startsWith('eslint') || cmd.startsWith('npm run lint') || cmd.startsWith('pnpm lint')) {
+    return 'Linting code';
+  }
+
+  // Formatting
+  if (cmd.startsWith('prettier')) {
+    return 'Formatting code';
+  }
+
+  // Default: show the command
+  return `Running ${truncate(command, MAX_LENGTH - 8)}`;
+}
+
+/**
+ * Generates a human-readable summary of what a tool is doing based on its name and input.
+ *
+ * @param toolName - The name of the tool (Read, Bash, Glob, Grep, Write, Edit, Task, etc.)
+ * @param input - The input parameters passed to the tool
+ * @returns A human-readable summary string
+ *
+ * @example
+ * generateToolIntentSummary('Read', { file_path: '/src/foo.ts' })
+ * // Returns: "Reading /src/foo.ts"
+ *
+ * @example
+ * generateToolIntentSummary('Bash', { command: 'npm install' })
+ * // Returns: "Installing dependencies"
+ */
+export function generateToolIntentSummary(
+  toolName: string,
+  input: Record<string, unknown>
+): string {
+  // Handle null/undefined input
+  const safeInput = input ?? {};
+
+  switch (toolName) {
+    case 'Read': {
+      const filePath = getString(safeInput, 'file_path');
+      if (!filePath) return 'Read';
+      return truncate(`Reading ${filePath}`);
+    }
+
+    case 'Bash': {
+      // Prefer Claude's description if provided (human-readable intent)
+      const description = getString(safeInput, 'description');
+      if (description) return truncate(description);
+      // Fall back to command-based summarization
+      const command = getString(safeInput, 'command');
+      if (!command) return 'Bash';
+      return summarizeBashCommand(command);
+    }
+
+    case 'Glob': {
+      const pattern = getString(safeInput, 'pattern');
+      if (!pattern) return 'Glob';
+      return truncate(`Finding ${pattern} files`);
+    }
+
+    case 'Grep': {
+      const pattern = getString(safeInput, 'pattern');
+      if (!pattern) return 'Grep';
+      // Remove outer quotes if present for display
+      const displayPattern = pattern.replace(/^["']|["']$/g, '');
+      return truncate(`Searching for '${displayPattern}'`);
+    }
+
+    case 'Write': {
+      const filePath = getString(safeInput, 'file_path');
+      if (!filePath) return 'Write';
+      return truncate(`Creating ${filePath}`);
+    }
+
+    case 'Edit': {
+      const filePath = getString(safeInput, 'file_path');
+      if (!filePath) return 'Edit';
+      return truncate(`Editing ${filePath}`);
+    }
+
+    case 'Task': {
+      const subagentType = getString(safeInput, 'subagent_type');
+      if (!subagentType) return 'Task';
+      return `Launching ${subagentType} agent`;
+    }
+
+    case 'WebFetch': {
+      const url = getString(safeInput, 'url');
+      if (!url) return 'WebFetch';
+      const hostname = extractHostname(url);
+      return truncate(`Fetching ${hostname}`);
+    }
+
+    case 'WebSearch': {
+      const query = getString(safeInput, 'query');
+      if (!query) return 'WebSearch';
+      return truncate(`Searching web for '${query}'`);
+    }
+
+    default: {
+      // Unknown tool: show tool name with truncated JSON
+      try {
+        const jsonStr = JSON.stringify(safeInput);
+        if (jsonStr === '{}') return toolName;
+        const maxJsonLen = MAX_LENGTH - toolName.length - 3; // space + parens
+        return `${toolName} (${truncate(jsonStr, maxJsonLen)})`;
+      } catch {
+        return toolName;
+      }
+    }
+  }
+}

package/packages/core/src/public/utils/toolStackGrouper.ts

@@ -0,0 +1,106 @@
+/**
+ * Tool Stack Grouper Utility
+ *
+ * Groups consecutive tool_use messages into collapsible stacks.
+ * Story MSSCI-13400 - Tool use stack between messages
+ */
+
+export interface ToolUseMessage {
+  type: 'tool_use';
+  tool_name: string;
+  tool_id: string;
+  input: Record<string, unknown>;
+  timestamp: number;
+  isStreaming?: boolean;
+}
+
+export interface ToolStackData {
+  stackId: string;
+  tools: ToolUseMessage[];
+  count: number;
+  isActive: boolean;
+  timestamp: number;
+}
+
+interface Message {
+  type: string;
+  timestamp: number;
+  tool_name?: string;
+  tool_id?: string;
+  input?: Record<string, unknown>;
+  isStreaming?: boolean;
+  content?: string;
+}
+
+/**
+ * Groups consecutive tool_use messages into stacks.
+ *
+ * Rules:
+ * - tool_result messages do NOT break the stack (they're paired with tool_use elsewhere)
+ * - assistant/user messages DO break the stack
+ * - Single tool_use messages ARE grouped (consistent rendering with multi-tool stacks)
+ * - Returns array of ToolStackData, each representing 1+ consecutive tools
+ *
+ * @param messages - Array of messages to process
+ * @returns Array of tool stacks (only stacks with 2+ tools)
+ */
+/**
+ * Generate a stable stack ID from the first tool's ID.
+ * This ensures the same stack keeps the same key across re-renders,
+ * preventing React from remounting and losing collapse state.
+ */
+function generateStableStackId(tools: ToolUseMessage[]): string {
+  if (tools.length === 0) return 'stack-empty';
+  // Use first tool's ID as anchor - it won't change as more tools are added
+  return `stack-${tools[0].tool_id}`;
+}
+
+export function groupToolsIntoStacks(messages: Message[]): ToolStackData[] {
+  const stacks: ToolStackData[] = [];
+  let currentTools: ToolUseMessage[] = [];
+
+  for (const msg of messages) {
+    if (msg.type === 'tool_use') {
+      // Add to current stack
+      currentTools.push({
+        type: 'tool_use',
+        tool_name: msg.tool_name || '',
+        tool_id: msg.tool_id || '',
+        input: msg.input || {},
+        timestamp: msg.timestamp,
+        isStreaming: msg.isStreaming,
+      });
+    } else if (msg.type === 'tool_result') {
+      // tool_result does NOT break the stack - it's matched separately
+      continue;
+    } else {
+      // assistant, user, or other message types break the stack
+      // Create stack for any tools (single tools also get stacked for consistent rendering)
+      if (currentTools.length >= 1) {
+        const lastTool = currentTools[currentTools.length - 1];
+        stacks.push({
+          stackId: generateStableStackId(currentTools),
+          tools: [...currentTools],
+          count: currentTools.length,
+          isActive: lastTool.isStreaming === true,
+          timestamp: currentTools[0].timestamp,
+        });
+      }
+      currentTools = [];
+    }
+  }
+
+  // Handle remaining tools at end of messages
+  if (currentTools.length >= 1) {
+    const lastTool = currentTools[currentTools.length - 1];
+    stacks.push({
+      stackId: generateStableStackId(currentTools),
+      tools: [...currentTools],
+      count: currentTools.length,
+      isActive: lastTool.isStreaming === true,
+      timestamp: currentTools[0].timestamp,
+    });
+  }
+
+  return stacks;
+}

package/packages/core/src/public/utils/toolTypeColors.ts

@@ -0,0 +1,45 @@
+/**
+ * Tool type color mappings
+ *
+ * Story MSSCI-13402 - Tool use visual design polish
+ *
+ * Provides color values and CSS class names for each tool type.
+ */
+
+/** Tool type to color hex mapping */
+export const TOOL_TYPE_COLORS: Record<string, string> = {
+  Read: '#3b82f6',    // blue
+  Write: '#f97316',   // orange
+  Bash: '#22c55e',    // green
+  Glob: '#a855f7',    // purple
+  Grep: '#06b6d4',    // cyan
+  Edit: '#eab308',    // yellow
+  Task: '#ec4899',    // pink
+};
+
+/** Default color for unknown tools */
+export const DEFAULT_TOOL_COLOR = '#6b7280'; // gray
+
+/**
+ * Get the color hex value for a tool type
+ *
+ * @param toolName - The name of the tool
+ * @returns Color hex string
+ */
+export function getToolTypeColor(toolName: string): string {
+  return TOOL_TYPE_COLORS[toolName] || DEFAULT_TOOL_COLOR;
+}
+
+/**
+ * Get the CSS class name for a tool type
+ *
+ * @param toolName - The name of the tool
+ * @returns CSS class name like "tool-read" or "tool-unknown"
+ */
+export function getToolTypeClass(toolName: string): string {
+  const knownTools = ['Read', 'Write', 'Bash', 'Glob', 'Grep', 'Edit', 'Task'];
+  if (knownTools.includes(toolName)) {
+    return `tool-${toolName.toLowerCase()}`;
+  }
+  return '';
+}

package/pennyfarthing-dist/guides/bikerack.md

@@ -26,6 +26,25 @@ Cyclist bundles the conversation UI and dashboard panels into one Electron app.
 
 ## Quick Start
 
+There are two approaches to running BikeRack.
+@arcaven currently uses:
+
+```bash
+# hint - cd ($repo)
+just wheelhub stop # in case it's running, clears left over pid and port files
+just wheelhub start # open browser w/ the URL for GUI
+just claude # handles some env setup
+
+# in another terminal
+# hint - cd ($repo)
+just tui
+
+# or
+just bikerack # your mileage may vary
+```
+
+RoseSecurity has been using:
+
 ```bash
 # Launch BikeRack + Claude CLI together
 pf.sh bikerack start
@@ -117,6 +136,81 @@ pf.sh bc list                 # List saved layouts
 | `packages/core/src/public/components/StandalonePanel.tsx` | `?panel=X` routing + `PANEL_REGISTRY` |
 | `pf/bikerack/cli.py` | `pf.sh bikerack` launcher CLI |
 
+## TUI Mode (Terminal Dashboard)
+
+BikeRack also ships a Textual-based TUI that runs entirely in the terminal — no browser needed.
+
+### Prerequisites
+
+- **Python** >= 3.11
+- **uv** (recommended) or pip
+- **just** >= 1.0
+
+### Setup
+
+```bash
+# From the pennyfarthing repo root — create venv and install TUI deps
+python3 -m venv .venv
+uv pip install --python .venv/bin/python3 -e "pennyfarthing-dist[tui]"
+```
+
+This installs the required packages into `.venv/`:
+
+| Package | Purpose |
+|---------|---------|
+| `textual` >= 1.0 | Terminal UI framework |
+| `websockets` >= 12.0 | WheelHub WebSocket client |
+| `rich` | Terminal rendering (textual dependency) |
+| `click` >= 8.0 | CLI framework (base dependency) |
+| `pyyaml` >= 6.0 | YAML parsing (base dependency) |
+| `textual-image` >= 0.7.0 | Agent portrait images (optional, graceful fallback) |
+
+The justfile automatically uses `.venv/bin/python3` when `.venv/` exists.
+
+### Launch
+
+```bash
+# Default — connects to WheelHub on localhost:1898
+just tui
+
+# Point at a specific project directory
+just tui dir=/path/to/project
+
+# Custom WheelHub port
+just tui port=2898
+```
+
+### Panels
+
+The TUI provides tabbed panels navigable via keyboard:
+
+| Key | Action |
+|-----|--------|
+| `Tab` / `]` | Next panel |
+| `[` | Previous panel |
+| `Shift+S` | Split view |
+| `Ctrl+P` | Command palette |
+| `q` | Quit |
+
+Available panels: Sprint, Git, Diffs, Audit Log, Debug, Progress.
+
+### Troubleshooting
+
+**`ModuleNotFoundError: No module named 'textual'`**
+```bash
+# Deps not installed in venv — re-run setup
+uv pip install --python .venv/bin/python3 -e "pennyfarthing-dist[tui]"
+```
+
+**`No module named 'pf'`**
+The justfile sets `PYTHONPATH` automatically. If running manually:
+```bash
+PYTHONPATH=pennyfarthing-dist:$PYTHONPATH .venv/bin/python3 -m pf.bikerack.tui
+```
+
+**Portrait images not rendering**
+Install `textual-image` (included in the `[tui]` extra). Requires a terminal with Sixel or Kitty graphics protocol support (iTerm2, WezTerm, Kitty). Falls back to text-only in unsupported terminals.
+
 ## Constraints
 
 - **No MessagePanel** — Claude conversation stays in your terminal. This is intentional.