@axplusb/kepler 0.0.1 → 1.0.0

package/src/ui/formatter.mjs

@@ -0,0 +1,379 @@
+/**
+ * Formatter — Clean terminal output for Tarang events.
+ *
+ * Style reference: Claude Code screenshot
+ *   ◐ Cyan spinner + cyan text for working/thinking
+ *   ✓ Green checkmark + green path for file changes
+ *   ✗ Red for errors
+ *   White for content and summaries
+ */
+
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const RED = '\x1b[31m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+
+// Spinner frames
+const SPINNER = ['◐', '◓', '◑', '◒'];
+
+export class EventFormatter {
+    constructor({ verbose = false } = {}) {
+        this.verbose = verbose;
+        this.toolCount = 0;
+        this.toolCalls = [];
+        this.changes = [];
+        this.phases = new Map();
+        this.sessionInfo = null;
+        this.tokenCount = { input: 0, output: 0 };
+        this._spinnerFrame = 0;
+        this._hasContent = false;
+        this._lastContent = '';
+        this._completed = false;
+        this._seenCallIds = new Set();
+        this._lastThinking = '';
+    }
+
+    render(event) {
+        const { type, data } = event;
+        switch (type) {
+            case 'session_info':
+                this.sessionInfo = data;
+                if (this.verbose) {
+                    process.stderr.write(`${DIM}  [session] ${data.session_id || ''}${RESET}\n`);
+                }
+                return true;
+            case 'status':
+                this._status(data);
+                return true;
+            case 'thinking':
+                this._thinking(data);
+                return true;
+            case 'content':
+            case 'content_partial':
+                this._content(data);
+                return true;
+            case 'tool_call':
+            case 'tool_request':
+                this._toolCall(data);
+                return true;
+            case 'tool_done':
+                this._toolDone(data);
+                return true;
+            case 'complete':
+                this._complete(data);
+                return true;
+            case 'error':
+                this._error(data);
+                return true;
+            case 'plan':
+                this._plan(data);
+                return true;
+            case 'phase_start':
+                this._phaseStart(data);
+                return true;
+            case 'phase_update':
+                this._phaseUpdate(data);
+                return true;
+            case 'phase_summary':
+                this._phaseSummary(data);
+                return true;
+            case 'change':
+                this._change(data);
+                return true;
+            case 'worker_update':
+            case 'worker_start':
+            case 'worker_done':
+                this._workerEvent(type, data);
+                return true;
+            case 'delegation':
+                this._delegation(data);
+                return true;
+            case 'cancelled':
+                process.stderr.write(`\n${YELLOW}  Cancelled${data?.reason ? ': ' + data.reason : ''}${RESET}\n`);
+                return true;
+            case 'paused':
+                process.stderr.write(`${CYAN}  Paused${RESET}\n`);
+                return true;
+            case 'resumed':
+                process.stderr.write(`${GREEN}  Resumed${RESET}\n`);
+                return true;
+            case 'pause_instruction':
+                this._pauseInstruction(data);
+                return true;
+            default:
+                if (this.verbose) {
+                    process.stderr.write(`${DIM}  [${type}] ${JSON.stringify(data).slice(0, 100)}${RESET}\n`);
+                }
+                return false;
+        }
+    }
+
+    _spinner() {
+        const frame = SPINNER[this._spinnerFrame % SPINNER.length];
+        this._spinnerFrame++;
+        return `${CYAN}${frame}${RESET}`;
+    }
+
+    _status(data) {
+        const msg = data?.message || '';
+        // Skip noisy statuses
+        if (!msg || msg === 'Agent started') return;
+        if (msg.startsWith('Creating agent') || msg.startsWith('Task type:')) {
+            process.stderr.write(`${DIM}  ${msg}${RESET}\n`);
+            return;
+        }
+        process.stderr.write(`  ${this._spinner()} ${CYAN}${msg}${RESET}\n`);
+    }
+
+    _thinking(data) {
+        if (!this.verbose) return;
+
+        const text = data?.message || data?.text || '';
+        if (!text || text === this._lastThinking) return;
+        this._lastThinking = text;
+
+        // Skip generic "Processing (iteration N)..." — too noisy
+        if (text.startsWith('Processing')) return;
+
+        process.stderr.write(`  ${this._spinner()} ${CYAN}${text.slice(0, 200)}${RESET}\n`);
+    }
+
+    _content(data) {
+        const text = data?.text || '';
+        if (!text) return;
+
+        // Deduplicate exact same content (CONTENT event may repeat)
+        if (text === this._lastContent) return;
+        this._lastContent = text;
+
+        // Add newline separator before content block
+        if (this.toolCount > 0 || this._hasContent) process.stdout.write('\n');
+        this._hasContent = true;
+
+        // Render content with 2-space indent
+        const lines = text.split('\n');
+        for (const line of lines) {
+            process.stdout.write(`  ${line}\n`);
+        }
+    }
+
+    _toolCall(data) {
+        const callId = data?.call_id;
+        const tool = data?.tool || 'unknown';
+        const args = data?.args || {};
+
+        // Deduplicate: agent event + bridge event both fire
+        if (callId) {
+            if (this._seenCallIds.has(callId)) return;
+            this._seenCallIds.add(callId);
+        } else {
+            // Agent event (no call_id) — skip if bridge event follows
+            // Use tool+args as dedup key
+            const key = `${tool}:${JSON.stringify(args)}`;
+            if (this._seenCallIds.has(key)) return;
+            this._seenCallIds.add(key);
+        }
+
+        this.toolCount++;
+
+        // Build human-readable description
+        const desc = this._toolDescription(tool, args);
+        process.stderr.write(`  ${this._spinner()} [${this.toolCount}] ${CYAN}${tool}: ${desc}${RESET}\n`);
+
+        this.toolCalls.push({ name: tool, callId, startTime: Date.now() });
+    }
+
+    _toolDescription(tool, args) {
+        switch (tool) {
+            case 'read_file':
+                return `Reading ${args.file_path || 'file'}...`;
+            case 'read_files': {
+                const paths = args.file_paths || [];
+                return `Reading ${paths.length} files...`;
+            }
+            case 'write_file':
+                return `Writing ${args.file_path || 'file'}...`;
+            case 'write_project': {
+                const files = args.files || [];
+                return `Writing ${files.length} files...`;
+            }
+            case 'edit_file':
+                return `Editing ${args.file_path || 'file'}...`;
+            case 'list_files':
+                return `Listing files${args.pattern ? ' (' + args.pattern + ')' : ''}...`;
+            case 'search_files':
+                return `Searching for "${args.pattern || ''}"...`;
+            case 'search_code':
+                return `Searching code: ${args.query || ''}...`;
+            case 'shell': {
+                const cmd = (args.command || '').slice(0, 60);
+                return `Running: ${cmd}${(args.command || '').length > 60 ? '...' : ''}`;
+            }
+            case 'validate_build':
+                return `Running build validation...`;
+            case 'validate_file':
+                return `Validating ${args.file_path || 'file'}...`;
+            case 'lint_check':
+                return `Linting ${args.file_path || 'file'}...`;
+            default:
+                return `${tool}...`;
+        }
+    }
+
+    _toolDone(data) {
+        const tool = data?.tool || '';
+        const success = data?.success !== false;
+        const durationMs = data?.duration_ms;
+
+        if (this.verbose) {
+            const dur = durationMs ? ` (${durationMs}ms)` : '';
+            process.stderr.write(`  ${GREEN}✓${RESET} ${tool} done${dur}\n`);
+        }
+
+        // Show file modifications as green checkmarks
+        if (tool === 'write_file' || tool === 'edit_file' || tool === 'write_project') {
+            const path = data?.result?.file_path || data?.args?.file_path || '';
+            if (path) {
+                const action = tool === 'edit_file' ? 'Modified' : tool === 'write_project' ? 'Created' : 'Written';
+                process.stderr.write(`  ${GREEN}✓ ${action} ${path}${RESET}\n`);
+                this.changes.push({ path, action });
+            }
+        }
+
+        // Show validation results
+        if (tool === 'validate_build' || tool === 'lint_check' || tool === 'validate_file') {
+            if (success) {
+                const label = tool === 'validate_build' ? 'Build passed' :
+                              tool === 'lint_check' ? 'Lint check passed' :
+                              'File validated';
+                process.stderr.write(`  ${GREEN}✓ ${label}${RESET}\n`);
+            } else {
+                const msg = data?.result?.error || data?.result?.stderr || 'Failed';
+                process.stderr.write(`  ${RED}✗ ${tool.replace('_', ' ')} failed: ${msg.slice(0, 100)}${RESET}\n`);
+            }
+        }
+
+        // Show shell command results (if verbose or if failed)
+        if (tool === 'shell' && !success) {
+            const stderr = data?.result?.stderr || '';
+            if (stderr) {
+                process.stderr.write(`  ${RED}✗ Command failed: ${stderr.slice(0, 100)}${RESET}\n`);
+            }
+        }
+    }
+
+    _plan(data) {
+        const milestones = data?.milestones || [];
+        if (milestones.length === 0) return;
+        process.stderr.write(`\n  ${BOLD}Plan${RESET}\n`);
+        for (const m of milestones) {
+            const icon = m.status === 'completed' ? `${GREEN}✓${RESET}` :
+                         m.status === 'started' ? `${CYAN}◐${RESET}` :
+                         `${DIM}○${RESET}`;
+            process.stderr.write(`  ${icon} ${m.name}\n`);
+        }
+    }
+
+    _phaseStart(data) {
+        const phase = data?.phase || data?.stage_name || '';
+        if (phase && phase !== 'undefined') {
+            process.stderr.write(`\n  ${this._spinner()} ${CYAN}${BOLD}${phase}${RESET}\n`);
+        }
+    }
+
+    _phaseUpdate(data) {
+        const phase = data?.phase || data?.stage_name || '';
+        const status = data?.status || '';
+        if (phase && phase !== 'undefined') {
+            this.phases.set(phase, status);
+            process.stderr.write(`\n  ${this._spinner()} ${CYAN}${BOLD}${phase}${RESET}\n`);
+        }
+    }
+
+    _phaseSummary(data) {
+        if (data?.summary) {
+            process.stderr.write(`  ${GREEN}✓${RESET} ${data.summary.slice(0, 200)}\n`);
+        }
+    }
+
+    _workerEvent(type, data) {
+        const worker = data?.worker || data?.name || '';
+        const status = data?.status || '';
+        if (type === 'worker_start') {
+            process.stderr.write(`  ${this._spinner()} ${CYAN}${worker} starting${RESET}\n`);
+        } else if (type === 'worker_done') {
+            process.stderr.write(`  ${GREEN}✓${RESET} ${worker} done\n`);
+        } else {
+            process.stderr.write(`  ${this._spinner()} ${CYAN}${worker}: ${status}${RESET}\n`);
+        }
+    }
+
+    _delegation(data) {
+        const from = data?.from || '';
+        const to = data?.to || '';
+        const instruction = data?.instruction || '';
+        process.stderr.write(`  ${CYAN}${from} → ${to}${RESET}${instruction ? ': ' + instruction : ''}\n`);
+    }
+
+    _pauseInstruction(data) {
+        const instruction = data?.instruction || '';
+        if (instruction) {
+            process.stderr.write(`  ${YELLOW}Pause instruction: ${instruction}${RESET}\n`);
+        }
+    }
+
+    _change(data) {
+        const icon = data?.type === 'create' ? `${GREEN}+${RESET}` : `${GREEN}~${RESET}`;
+        process.stderr.write(`  ${icon} ${GREEN}${data?.path || ''}${RESET}\n`);
+        this.changes.push(data);
+    }
+
+    _error(data) {
+        const msg = data?.message || 'Unknown error';
+        process.stderr.write(`\n  ${RED}✗ ${msg}${RESET}\n`);
+
+        // Helpful suggestions for common errors
+        if (msg.includes('Authentication') || msg.includes('token')) {
+            process.stderr.write(`  ${DIM}Run /login to re-authenticate${RESET}\n`);
+        } else if (msg.includes('API key') || msg.includes('OpenRouter')) {
+            process.stderr.write(`  ${DIM}Run /config to set up your provider${RESET}\n`);
+        } else if (msg.includes('Backend') || msg.includes('Network')) {
+            process.stderr.write(`  ${DIM}Check if the backend is running at ${this.sessionInfo?.backend || 'localhost:8000'}${RESET}\n`);
+        }
+    }
+
+    _complete(data) {
+        // Only show once
+        if (this._completed) return;
+        this._completed = true;
+
+        const summary = data?.summary || '';
+        const duration = data?.duration_s ? `${Number(data.duration_s).toFixed(1)}s` : '';
+        const tools = this.toolCount || data?.tool_calls || 0;
+        const changeCount = data?.changes || this.changes.length || 0;
+
+        // Summary line
+        const parts = [];
+        if (duration) parts.push(duration);
+        if (tools > 0) parts.push(`${tools} tool calls`);
+        if (changeCount > 0) parts.push(`${changeCount} changes`);
+
+        const stats = parts.length > 0 ? ` (${parts.join(', ')})` : '';
+        if (summary) {
+            process.stderr.write(`\n  ${GREEN}✓ ${summary}${stats}${RESET}\n`);
+        } else {
+            process.stderr.write(`\n  ${GREEN}✓ Done${stats}${RESET}\n`);
+        }
+
+        // Token usage if available
+        const usage = data?.usage;
+        if (usage && (usage.input_tokens || usage.total_tokens)) {
+            const inp = usage.input_tokens || 0;
+            const out = usage.output_tokens || 0;
+            process.stderr.write(`  ${DIM}Tokens: ${inp.toLocaleString()} in / ${out.toLocaleString()} out${RESET}\n`);
+        }
+    }
+}

package/src/ui/markdown.mjs

@@ -0,0 +1,278 @@
+/**
+ * Terminal Markdown Renderer — parse markdown to ANSI-styled text.
+ *
+ * Supports:
+ * - **bold** -> bold text
+ * - *italic* -> italic text
+ * - `code` -> inverse/cyan
+ * - ```code block``` -> bordered box
+ * - - list item -> bullet
+ * - # heading -> bold + underline
+ * - [link](url) -> blue underline
+ * - | table | -> formatted table
+ */
+
+const ANSI = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    italic: '\x1b[3m',
+    underline: '\x1b[4m',
+    inverse: '\x1b[7m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    magenta: '\x1b[35m',
+    cyan: '\x1b[36m',
+    white: '\x1b[37m',
+    gray: '\x1b[90m',
+};
+
+const noColor = process.env.NO_COLOR === '1';
+
+function a(codes, text) {
+    if (noColor) return text;
+    const prefix = Array.isArray(codes) ? codes.join('') : codes;
+    return `${prefix}${text}${ANSI.reset}`;
+}
+
+/**
+ * Render inline markdown formatting within a single line.
+ * @param {string} line
+ * @returns {string}
+ */
+export function renderInline(line) {
+    if (noColor) return line;
+    let result = line;
+
+    // Bold: **text**
+    result = result.replace(/\*\*(.+?)\*\*/g, (_, t) => a(ANSI.bold, t));
+
+    // Italic: *text* (not preceded/followed by *)
+    result = result.replace(/(?<!\*)\*([^*]+)\*(?!\*)/g, (_, t) => a(ANSI.italic, t));
+
+    // Inline code: `text`
+    result = result.replace(/`([^`]+)`/g, (_, t) => a(ANSI.cyan, t));
+
+    // Links: [text](url)
+    result = result.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_, text, url) => {
+        return `${a([ANSI.blue, ANSI.underline], text)} ${a(ANSI.dim, `(${url})`)}`;
+    });
+
+    return result;
+}
+
+/**
+ * Highlight syntax within a code line (basic keyword/string/number/comment coloring).
+ * @param {string} line
+ * @param {string} lang
+ * @returns {string}
+ */
+export function highlightSyntax(line, lang) {
+    if (noColor) return line;
+    let result = line;
+
+    // Strings
+    result = result.replace(/(["'`])(.*?)\1/g, (m, q, s) => a(ANSI.green, `${q}${s}${q}`));
+
+    // Keywords
+    const kw = /\b(const|let|var|function|return|if|else|for|while|class|import|export|from|async|await|try|catch|throw|new|this|def|fn|pub|use|mod|struct|enum|impl|match|type|interface)\b/g;
+    result = result.replace(kw, (m) => a(ANSI.magenta, m));
+
+    // Numbers
+    result = result.replace(/\b(\d+\.?\d*)\b/g, (m) => a(ANSI.yellow, m));
+
+    // Comments
+    result = result.replace(/(\/\/.*|#.*)$/, (m) => a(ANSI.gray, m));
+
+    return result;
+}
+
+/**
+ * Render a full markdown string to ANSI terminal output.
+ * Handles block-level elements (headings, code blocks, lists, tables)
+ * and inline formatting.
+ *
+ * @param {string} text - raw markdown
+ * @returns {string} - ANSI-formatted string
+ */
+export function renderMarkdown(text) {
+    if (!text) return '';
+    const lines = text.split('\n');
+    const output = [];
+    let inCodeBlock = false;
+    let codeLang = '';
+    let codeLines = [];
+    let inTable = false;
+    let tableRows = [];
+
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+
+        // Code block start/end
+        if (line.trimStart().startsWith('```')) {
+            if (inCodeBlock) {
+                // End code block - render it
+                output.push(formatCodeBlock(codeLines, codeLang));
+                inCodeBlock = false;
+                codeLines = [];
+                codeLang = '';
+                continue;
+            }
+            // Start code block
+            inCodeBlock = true;
+            codeLang = line.trimStart().slice(3).trim();
+            continue;
+        }
+
+        if (inCodeBlock) {
+            codeLines.push(line);
+            continue;
+        }
+
+        // Table detection
+        if (line.trim().startsWith('|') && line.trim().endsWith('|')) {
+            // Check if separator row
+            if (/^\|[\s\-:|]+\|$/.test(line.trim())) {
+                // Table separator, skip
+                continue;
+            }
+            tableRows.push(line);
+            // Check if next line is NOT a table row
+            const nextLine = lines[i + 1];
+            if (!nextLine || (!nextLine.trim().startsWith('|') || !nextLine.trim().endsWith('|'))) {
+                // Flush table
+                if (tableRows.length > 0) {
+                    output.push(formatTable(tableRows));
+                    tableRows = [];
+                }
+            }
+            continue;
+        }
+
+        // Flush any pending table rows
+        if (tableRows.length > 0) {
+            output.push(formatTable(tableRows));
+            tableRows = [];
+        }
+
+        // Headings
+        const headingMatch = line.match(/^(#{1,6})\s+(.+)/);
+        if (headingMatch) {
+            const level = headingMatch[1].length;
+            const text = headingMatch[2];
+            if (level === 1) {
+                output.push(a([ANSI.bold, ANSI.underline], text));
+            } else if (level === 2) {
+                output.push(a(ANSI.bold, text));
+            } else {
+                output.push(a(ANSI.bold, text));
+            }
+            continue;
+        }
+
+        // Unordered list
+        const listMatch = line.match(/^(\s*)([-*+])\s+(.*)/);
+        if (listMatch) {
+            const indent = listMatch[1];
+            const content = renderInline(listMatch[3]);
+            output.push(`${indent}  * ${content}`);
+            continue;
+        }
+
+        // Ordered list
+        const olMatch = line.match(/^(\s*)(\d+)\.\s+(.*)/);
+        if (olMatch) {
+            const indent = olMatch[1];
+            const num = olMatch[2];
+            const content = renderInline(olMatch[3]);
+            output.push(`${indent}  ${num}. ${content}`);
+            continue;
+        }
+
+        // Horizontal rule
+        if (/^[-*_]{3,}\s*$/.test(line)) {
+            const cols = process.stdout.columns || 80;
+            output.push(a(ANSI.dim, '\u2500'.repeat(Math.min(cols, 60))));
+            continue;
+        }
+
+        // Blockquote
+        const bqMatch = line.match(/^>\s?(.*)/);
+        if (bqMatch) {
+            output.push(a(ANSI.dim, `  | ${renderInline(bqMatch[1])}`));
+            continue;
+        }
+
+        // Normal line with inline formatting
+        output.push(renderInline(line));
+    }
+
+    // Flush remaining
+    if (inCodeBlock && codeLines.length > 0) {
+        output.push(formatCodeBlock(codeLines, codeLang));
+    }
+    if (tableRows.length > 0) {
+        output.push(formatTable(tableRows));
+    }
+
+    return output.join('\n');
+}
+
+/**
+ * Format a code block with a border.
+ * @param {string[]} lines
+ * @param {string} lang
+ * @returns {string}
+ */
+function formatCodeBlock(lines, lang) {
+    if (noColor) {
+        return lines.map(l => `  ${l}`).join('\n');
+    }
+
+    const maxLen = Math.max(...lines.map(l => l.length), 20);
+    const width = Math.min(maxLen + 4, (process.stdout.columns || 80) - 4);
+    const top = a(ANSI.gray, `  \u250C${'─'.repeat(width)}\u2510${lang ? ` ${lang}` : ''}`);
+    const bot = a(ANSI.gray, `  \u2514${'─'.repeat(width)}\u2518`);
+    const body = lines.map(l => {
+        const highlighted = highlightSyntax(l, lang);
+        return `  ${a(ANSI.gray, '\u2502')} ${highlighted}`;
+    });
+
+    return [top, ...body, bot].join('\n');
+}
+
+/**
+ * Format a markdown table.
+ * @param {string[]} rows
+ * @returns {string}
+ */
+function formatTable(rows) {
+    const parsed = rows.map(r =>
+        r.split('|').slice(1, -1).map(c => c.trim())
+    );
+
+    if (parsed.length === 0) return '';
+
+    // Calculate column widths
+    const colCount = parsed[0].length;
+    const widths = [];
+    for (let c = 0; c < colCount; c++) {
+        widths.push(Math.max(...parsed.map(r => (r[c] || '').length)));
+    }
+
+    const formatted = parsed.map((row, ri) => {
+        const cells = row.map((cell, ci) => cell.padEnd(widths[ci] || 0));
+        const line = `  ${cells.join('  ')}`;
+        return ri === 0 ? a(ANSI.bold, line) : line;
+    });
+
+    // Add separator after header
+    if (formatted.length > 1) {
+        const sep = widths.map(w => '─'.repeat(w)).join('──');
+        formatted.splice(1, 0, a(ANSI.dim, `  ${sep}`));
+    }
+
+    return formatted.join('\n');
+}