@ruvnet/open-claude-code 2.0.0 → 2.1.0

package/README.md

@@ -0,0 +1,113 @@
+# open-claude-code v2 — Technical Guide
+
+## Quick Start
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+node src/index.mjs "hello"          # one-shot
+node src/index.mjs                   # interactive REPL
+node src/index.mjs -m claude-opus-4-6 -p "explain this"  # print mode
+```
+
+## Architecture
+
+```
+v2/src/
+├── core/                    # Core engine
+│   ├── agent-loop.mjs       # Async generator (13 event types, recursive)
+│   ├── streaming.mjs        # SSE handler (all event types)
+│   ├── context-manager.mjs  # Token tracking + compaction
+│   ├── system-prompt.mjs    # CLAUDE.md loading + cache boundary
+│   ├── session.mjs          # Save/resume/teleport
+│   ├── checkpoints.mjs      # File checkpointing + undo
+│   ├── cache.mjs            # Prompt caching
+│   ├── rate-limiter.mjs     # 429/529 handling + backoff
+│   ├── providers.mjs        # 5 AI providers
+│   └── scheduler.mjs        # Cron task scheduling
+├── tools/                   # 25 tools
+│   ├── registry.mjs         # validateInput/call interface
+│   ├── bash.mjs             # Shell (sandboxed, timeout, background)
+│   ├── read.mjs             # File read (PDF, binary detect, line nums)
+│   ├── edit.mjs             # Edit (replace_all, uniqueness check)
+│   ├── write.mjs            # Write (mkdir, overwrite protection)
+│   ├── glob.mjs             # Glob (proper matching, mtime sort)
+│   ├── grep.mjs             # Grep (-i/-n/-A/-B/-C, ripgrep)
+│   ├── agent.mjs            # Subagent (worktree, background, model)
+│   ├── web-fetch.mjs        # URL fetch
+│   ├── web-search.mjs       # Web search
+│   ├── todo-write.mjs       # Task management
+│   ├── notebook-edit.mjs    # Jupyter notebooks
+│   ├── multi-edit.mjs       # Atomic multi-file edits
+│   ├── ls.mjs               # Directory listing
+│   ├── tool-search.mjs      # Deferred tool discovery
+│   ├── ask-user.mjs         # User prompts
+│   ├── skill.mjs            # Skill invocation
+│   ├── send-message.mjs     # Agent team messaging
+│   ├── cron-create.mjs      # Scheduled tasks
+│   ├── cron-delete.mjs
+│   ├── cron-list.mjs
+│   ├── enter-worktree.mjs   # Git worktree
+│   ├── exit-worktree.mjs
+│   ├── remote-trigger.mjs   # Remote execution
+│   ├── lsp.mjs              # Language server
+│   └── read-mcp-resource.mjs
+├── mcp/                     # MCP protocol
+│   ├── client.mjs           # JSON-RPC client
+│   ├── transport-sse.mjs    # SSE transport
+│   ├── transport-shttp.mjs  # Streamable HTTP
+│   └── transport-ws.mjs     # WebSocket
+├── permissions/              # Security
+│   ├── checker.mjs          # 6 modes + interactive prompts
+│   ├── sandbox.mjs          # bubblewrap/seatbelt
+│   ├── injection-check.mjs  # Command injection detection
+│   ├── path-check.mjs       # File path validation
+│   └── prompt.mjs           # Permission prompting
+├── hooks/
+│   └── engine.mjs           # PreToolUse/PostToolUse/Stop/Notification
+├── agents/
+│   ├── loader.mjs           # Agent definition loader
+│   ├── parser.mjs           # JSON/MD frontmatter parser
+│   └── teams.mjs            # Multi-agent teams
+├── skills/
+│   ├── loader.mjs           # Skill discovery
+│   └── runner.mjs           # Skill execution
+├── plugins/
+│   └── loader.mjs           # Plugin discovery + git clone
+├── auth/
+│   └── oauth.mjs            # PKCE OAuth flow
+├── config/
+│   ├── settings.mjs         # 4-source deep merge
+│   ├── cli-args.mjs         # All CLI flags
+│   └── env.mjs              # 104 env vars
+├── ui/
+│   ├── repl.mjs             # Interactive REPL
+│   ├── ink-app.mjs          # Rich terminal output
+│   └── commands.mjs         # 40 slash commands
+├── telemetry/
+│   └── index.mjs            # Telemetry stub
+└── index.mjs                # Entry point
+
+test/
+└── test.mjs                 # 1,581 tests
+```
+
+## Stats
+
+| Metric | Value |
+|--------|:-----:|
+| Source files | 61 |
+| Lines of code | 8,314 |
+| Tests | 1,581 (0 failures) |
+| Tools | 25 |
+| Slash commands | 40 |
+| MCP transports | 4 |
+| AI providers | 5 |
+| Env vars | 104 |
+| Permission modes | 6 |
+
+## Tests
+
+```bash
+node test/test.mjs
+# Tests: 1581 total, 1581 passed, 0 failed
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ruvnet/open-claude-code",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Open source Claude Code CLI — based on ruDevolution decompilation of v2.1.91",
   "type": "module",
   "bin": {
@@ -23,5 +23,23 @@
     "open-source"
   ],
   "license": "MIT",
-  "repository": "https://github.com/ruvnet/open-claude-code"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ruvnet/open-claude-code.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ruvnet/open-claude-code/issues"
+  },
+  "homepage": "https://github.com/ruvnet/open-claude-code#readme",
+  "main": "index.js",
+  "directories": {
+    "test": "test"
+  },
+  "author": "",
+  "dependencies": {
+    "ink": "^5.2.1",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
+    "react": "^18.3.1"
+  }
 }

package/src/index.mjs

@@ -141,7 +141,7 @@ async function main() {
     process.on('SIGTERM', async () => { await cleanup(); process.exit(0); });
 
     if (args.prompt) {
-        // Non-interactive: run prompt and exit
+        // Non-interactive: run prompt and exit (no Ink — plain stdout)
         const outputFormat = args.outputFormat || 'text';
         const results = [];
 
@@ -172,9 +172,21 @@ async function main() {
 
         await cleanup();
     } else {
-        // Interactive REPL
-        const { startRepl } = await import('./ui/repl.mjs');
-        await startRepl(loop, settings);
+        // Interactive: use Ink React TUI
+        try {
+            const { startInkApp } = await import('./ui/app.mjs');
+            const inkInstance = startInkApp(loop, settings);
+
+            // Wait for Ink to exit (user pressed Ctrl+C or /quit)
+            await inkInstance.waitUntilExit();
+        } catch (err) {
+            // Fallback to readline REPL if Ink fails (e.g. no TTY, missing deps)
+            if (settings.debug) {
+                console.error(`Ink UI unavailable (${err.message}), falling back to readline REPL`);
+            }
+            const { startRepl } = await import('./ui/repl.mjs');
+            await startRepl(loop, settings);
+        }
         await cleanup();
     }
 }

package/src/ui/app.mjs

@@ -0,0 +1,286 @@
+/**
+ * Main Ink App — full React terminal UI matching Claude Code's interface.
+ *
+ * Uses React.createElement (no JSX transpiler needed).
+ *
+ * Features:
+ * - Scrolling messages area with assistant, user, tool, thinking messages
+ * - Persistent status bar (model, context%, cost, time, permission mode)
+ * - Text input with prompt indicator
+ * - Loading spinner during API calls
+ * - Tool execution display with spinners
+ * - Keyboard shortcuts (Escape, Ctrl+C, Ctrl+L)
+ * - Slash command support (39 commands)
+ * - Skill invocation via /skill-name
+ */
+
+import React, { useState, useCallback, useRef } from 'react';
+import { render, Box, Text, useInput, useApp } from 'ink';
+import TextInput from 'ink-text-input';
+import {
+    StatusBar,
+    Message,
+    LoadingIndicator,
+    WelcomeBanner,
+} from './components.mjs';
+import { executeCommand, COMMANDS } from './commands.mjs';
+
+const h = React.createElement;
+
+/**
+ * Main application component.
+ */
+export function App({ agentLoop, settings }) {
+    const [input, setInput] = useState('');
+    const [messages, setMessages] = useState([]);
+    const [isLoading, setIsLoading] = useState(false);
+    const [model, setModel] = useState(agentLoop.state.model || 'claude-sonnet-4-6');
+    const [tokenCount, setTokenCount] = useState({ input: 0, output: 0 });
+    const [cost, setCost] = useState(0);
+    const [mode] = useState(settings.permissions?.defaultMode || 'default');
+    const [toolStatus, setToolStatus] = useState(null);
+    const [startTime] = useState(Date.now());
+    const loadingRef = useRef(false);
+    const { exit } = useApp();
+
+    // Calculate cost from token counts
+    const updateCost = useCallback((tokens) => {
+        const m = agentLoop.state.model || '';
+        let priceIn = 3, priceOut = 15;
+        if (m.includes('haiku')) { priceIn = 0.25; priceOut = 1.25; }
+        if (m.includes('opus')) { priceIn = 15; priceOut = 75; }
+        const costIn = (tokens.input / 1_000_000) * priceIn;
+        const costOut = (tokens.output / 1_000_000) * priceOut;
+        setCost(costIn + costOut);
+    }, [agentLoop.state.model]);
+
+    // Add a message to the display
+    const addMessage = useCallback((msg) => {
+        setMessages(prev => {
+            const next = [...prev, msg];
+            return next.length > 200 ? next.slice(-150) : next;
+        });
+    }, []);
+
+    // Handle slash commands
+    const handleCommand = useCallback((text) => {
+        const cmdName = text.split(/\s+/)[0].toLowerCase();
+
+        // Check for skill invocation
+        if (!COMMANDS[cmdName] && agentLoop.state._skillsLoader) {
+            const skill = agentLoop.state._skillsLoader.get(cmdName.slice(1));
+            if (skill) {
+                const args = text.slice(cmdName.length).trim();
+                addMessage({ role: 'user', content: text });
+                runPrompt(
+                    `[Skill: ${skill.name}]\n${skill.prompt}${args ? `\nArguments: ${args}` : ''}`
+                );
+                return;
+            }
+        }
+
+        const { response, exit: shouldExit } = executeCommand(text, agentLoop.state);
+        if (shouldExit) {
+            exit();
+            return;
+        }
+        addMessage({ role: 'system', content: response });
+
+        // Sync model if it changed
+        if (agentLoop.state.model !== model) {
+            setModel(agentLoop.state.model);
+        }
+    }, [agentLoop, model, addMessage, exit]);
+
+    // Run a prompt through the agent loop
+    const runPrompt = useCallback(async (text) => {
+        setIsLoading(true);
+        loadingRef.current = true;
+        setToolStatus(null);
+
+        try {
+            for await (const event of agentLoop.run(text)) {
+                switch (event.type) {
+                    case 'stream_event':
+                        setMessages(prev => {
+                            const last = prev[prev.length - 1];
+                            if (last && last.role === 'assistant' && last._streaming) {
+                                return [
+                                    ...prev.slice(0, -1),
+                                    { ...last, content: (last.content || '') + (event.text || '') },
+                                ];
+                            }
+                            return [
+                                ...prev,
+                                { role: 'assistant', content: event.text || '', _streaming: true },
+                            ];
+                        });
+                        break;
+
+                    case 'assistant':
+                        setMessages(prev => {
+                            const last = prev[prev.length - 1];
+                            if (last && last.role === 'assistant' && last._streaming) {
+                                return [
+                                    ...prev.slice(0, -1),
+                                    { ...last, _streaming: false },
+                                ];
+                            }
+                            if (event.content) {
+                                return [...prev, { role: 'assistant', content: event.content }];
+                            }
+                            return prev;
+                        });
+                        break;
+
+                    case 'thinking':
+                        addMessage({ role: 'thinking', thinking: event.text });
+                        break;
+
+                    case 'tool_progress':
+                        setToolStatus(event.tool);
+                        addMessage({
+                            role: 'tool',
+                            toolName: event.tool,
+                            toolStatus: 'running',
+                        });
+                        break;
+
+                    case 'result':
+                        setToolStatus(null);
+                        setMessages(prev => {
+                            const idx = prev.findLastIndex(
+                                m => m.role === 'tool' &&
+                                     m.toolName === event.tool &&
+                                     m.toolStatus === 'running'
+                            );
+                            if (idx >= 0) {
+                                const updated = [...prev];
+                                updated[idx] = {
+                                    ...updated[idx],
+                                    toolResult: typeof event.result === 'string'
+                                        ? event.result
+                                        : JSON.stringify(event.result),
+                                    toolStatus: 'done',
+                                };
+                                return updated;
+                            }
+                            return prev;
+                        });
+                        break;
+
+                    case 'compaction':
+                        addMessage({ role: 'system', content: `[compaction #${event.count}]` });
+                        break;
+
+                    case 'hookPermissionResult':
+                        if (!event.allowed) {
+                            addMessage({ role: 'system', content: `[blocked: ${event.tool}]` });
+                        }
+                        break;
+
+                    case 'error':
+                        addMessage({ role: 'error', content: event.message });
+                        break;
+
+                    case 'stop':
+                        break;
+                }
+
+                // Update token counts
+                const usage = agentLoop.state.tokenUsage;
+                setTokenCount({ input: usage.input, output: usage.output });
+                updateCost(usage);
+            }
+        } catch (err) {
+            addMessage({ role: 'error', content: err.message });
+        } finally {
+            setIsLoading(false);
+            loadingRef.current = false;
+            setToolStatus(null);
+        }
+    }, [agentLoop, addMessage, updateCost]);
+
+    // Handle submit
+    const handleSubmit = useCallback((value) => {
+        const trimmed = value.trim();
+        if (!trimmed) return;
+
+        setInput('');
+
+        if (trimmed.startsWith('/')) {
+            handleCommand(trimmed);
+            return;
+        }
+
+        addMessage({ role: 'user', content: trimmed });
+        runPrompt(trimmed);
+    }, [handleCommand, addMessage, runPrompt]);
+
+    // Keyboard shortcuts
+    useInput((ch, key) => {
+        if (key.escape && loadingRef.current) {
+            setIsLoading(false);
+            setToolStatus(null);
+            addMessage({ role: 'system', content: '[cancelled]' });
+        }
+        if (key.ctrl && ch === 'c') {
+            exit();
+        }
+        if (key.ctrl && ch === 'l') {
+            setMessages([]);
+        }
+    });
+
+    const toolCount = agentLoop.state.tools?.list?.()?.length || 0;
+
+    // Build the message list
+    const messageElements = messages.map((msg, i) =>
+        h(Message, { key: i, ...msg })
+    );
+
+    return h(Box, { flexDirection: 'column' },
+        // Welcome banner
+        h(WelcomeBanner, { model, toolCount }),
+
+        // Messages area
+        h(Box, { flexDirection: 'column', flexGrow: 1 },
+            ...messageElements,
+            isLoading ? h(LoadingIndicator, { tool: toolStatus }) : null,
+        ),
+
+        // Input area
+        h(Box, { borderStyle: 'round', borderColor: 'cyan', paddingX: 1, marginTop: 1 },
+            h(Text, { color: 'cyan' }, '> '),
+            h(TextInput, {
+                value: input,
+                onChange: setInput,
+                onSubmit: handleSubmit,
+                placeholder: 'Type a message...',
+            }),
+        ),
+
+        // Status bar
+        h(StatusBar, {
+            model,
+            tokens: tokenCount,
+            cost,
+            mode,
+            startTime,
+            contextMax: settings.maxContextTokens || 200000,
+        }),
+    );
+}
+
+/**
+ * Start the Ink application.
+ * @param {object} agentLoop - agent loop instance
+ * @param {object} settings - loaded settings
+ * @returns {object} Ink instance
+ */
+export function startInkApp(agentLoop, settings) {
+    const instance = render(
+        h(App, { agentLoop, settings })
+    );
+    return instance;
+}

package/src/ui/components.mjs

@@ -0,0 +1,219 @@
+/**
+ * Ink UI Components — React components for the terminal interface.
+ *
+ * Uses React.createElement (no JSX transpiler needed).
+ *
+ * Components:
+ * - StatusBar: persistent bottom bar (model, context%, cost, time, mode)
+ * - Message: renders different message types
+ * - AssistantMessage: markdown-formatted assistant output
+ * - UserMessage: user input display
+ * - ToolMessage: tool execution with spinner
+ * - ThinkingMessage: dim italic thinking blocks
+ * - CodeBlock: bordered code display
+ * - PermissionPrompt: interactive y/n/a prompt
+ * - LoadingIndicator: spinner during API calls
+ * - WelcomeBanner: startup banner
+ */
+
+import React, { useState, useEffect } from 'react';
+import { Box, Text } from 'ink';
+import Spinner from 'ink-spinner';
+import { renderMarkdown } from './markdown.mjs';
+
+const h = React.createElement;
+
+/**
+ * Format duration in seconds to human-readable string.
+ */
+function formatDuration(seconds) {
+    if (seconds < 60) return `${Math.floor(seconds)}s`;
+    const mins = Math.floor(seconds / 60);
+    const secs = Math.floor(seconds % 60);
+    return `${mins}m${secs}s`;
+}
+
+/**
+ * Truncate text to a maximum length.
+ */
+function truncate(text, max) {
+    if (!text) return '';
+    if (text.length <= max) return text;
+    return text.slice(0, max) + '...';
+}
+
+/**
+ * Format cost to display string.
+ */
+function formatCost(cost) {
+    if (cost < 0.01) return `$${cost.toFixed(4)}`;
+    return `$${cost.toFixed(2)}`;
+}
+
+// ---- Status Bar ----
+
+export function StatusBar({ model, tokens, cost, mode, startTime, contextMax }) {
+    const [elapsed, setElapsed] = useState(0);
+
+    useEffect(() => {
+        const interval = setInterval(() => {
+            setElapsed(Math.floor((Date.now() - (startTime || Date.now())) / 1000));
+        }, 1000);
+        return () => clearInterval(interval);
+    }, [startTime]);
+
+    const totalTokens = (tokens?.input || 0) + (tokens?.output || 0);
+    const maxCtx = contextMax || 200000;
+    const contextPct = Math.min(100, Math.round((totalTokens / maxCtx) * 100));
+    const ctxColor = contextPct > 80 ? 'red' : contextPct > 50 ? 'yellow' : 'green';
+
+    return h(Box, null,
+        h(Text, { color: 'cyan', bold: true }, '\u258A '),
+        h(Text, { color: 'white' }, 'open-claude-code'),
+        h(Text, { color: 'gray' }, ' \u2502 '),
+        h(Text, { color: 'green' }, model || 'default'),
+        h(Text, { color: 'gray' }, ' \u2502 '),
+        h(Text, { color: 'yellow' }, '\u23F1 ', formatDuration(elapsed)),
+        h(Text, { color: 'gray' }, ' \u2502 '),
+        h(Text, { color: ctxColor }, '\u25CF ', contextPct, '% ctx'),
+        h(Text, { color: 'gray' }, ' \u2502 '),
+        h(Text, { color: 'white' }, formatCost(cost || 0)),
+        h(Text, { color: 'gray' }, ' \u2502 '),
+        h(Text, { color: 'magenta' }, mode || 'default'),
+    );
+}
+
+// ---- Message Components ----
+
+export function Message({ role, content, toolName, toolResult, toolStatus, thinking }) {
+    if (role === 'assistant') return h(AssistantMessage, { content });
+    if (role === 'tool') return h(ToolMessage, { name: toolName, result: toolResult, status: toolStatus });
+    if (role === 'thinking') return h(ThinkingMessage, { content: thinking });
+    if (role === 'user') return h(UserMessage, { content });
+    if (role === 'error') return h(ErrorMessage, { content });
+    if (role === 'system') return h(SystemMessage, { content });
+    return null;
+}
+
+export function AssistantMessage({ content }) {
+    if (!content) return null;
+    const rendered = renderMarkdown(content);
+    return h(Box, { marginLeft: 0, marginBottom: 0 },
+        h(Text, null, rendered),
+    );
+}
+
+export function UserMessage({ content }) {
+    if (!content) return null;
+    return h(Box, { marginBottom: 0 },
+        h(Text, { color: 'blue', bold: true }, 'You: '),
+        h(Text, null, content),
+    );
+}
+
+export function ToolMessage({ name, result, status }) {
+    const children = [
+        h(Text, { color: 'yellow', key: 'label' }, '[', name, '] '),
+    ];
+
+    if (status === 'running') {
+        children.push(
+            h(Text, { color: 'cyan', key: 'spinner' },
+                h(Spinner, { type: 'dots' }),
+                ' running...',
+            ),
+        );
+    }
+    if (status === 'done' && result) {
+        children.push(
+            h(Text, { color: 'gray', key: 'result' }, ' ', truncate(String(result), 200)),
+        );
+    }
+    if (status === 'error' && result) {
+        children.push(
+            h(Text, { color: 'red', key: 'error' }, ' ', truncate(String(result), 200)),
+        );
+    }
+
+    return h(Box, null, ...children);
+}
+
+export function ThinkingMessage({ content }) {
+    if (!content) return null;
+    return h(Box, null,
+        h(Text, { dimColor: true, italic: true }, '\uD83D\uDCAD ', truncate(content, 500)),
+    );
+}
+
+export function ErrorMessage({ content }) {
+    return h(Box, null,
+        h(Text, { color: 'red', bold: true }, 'Error: '),
+        h(Text, { color: 'red' }, content),
+    );
+}
+
+export function SystemMessage({ content }) {
+    return h(Box, null,
+        h(Text, { dimColor: true }, content),
+    );
+}
+
+// ---- Code Block ----
+
+export function CodeBlock({ code, language }) {
+    if (!code) return null;
+    const children = [];
+    if (language) {
+        children.push(h(Text, { dimColor: true, key: 'lang' }, language));
+    }
+    children.push(h(Text, { key: 'code' }, code));
+
+    return h(Box, {
+        borderStyle: 'single',
+        borderColor: 'gray',
+        paddingX: 1,
+        marginLeft: 2,
+    }, ...children);
+}
+
+// ---- Permission Prompt ----
+
+export function PermissionPrompt({ toolName, command }) {
+    const children = [
+        h(Text, { color: 'yellow', key: 'allow' }, 'Allow '),
+        h(Text, { bold: true, key: 'tool' }, toolName),
+    ];
+    if (command) {
+        children.push(
+            h(Text, { color: 'gray', key: 'cmd' }, ': ', truncate(command, 60)),
+        );
+    }
+    children.push(h(Text, { key: 'prompt' }, ' [y/n/a] '));
+
+    return h(Box, {
+        borderStyle: 'round',
+        borderColor: 'yellow',
+        paddingX: 1,
+    }, ...children);
+}
+
+// ---- Loading Indicator ----
+
+export function LoadingIndicator({ tool }) {
+    return h(Box, null,
+        h(Text, { color: 'cyan' },
+            h(Spinner, { type: 'dots' }),
+        ),
+        h(Text, { dimColor: true }, ' ', tool ? `Running ${tool}...` : 'Thinking...'),
+    );
+}
+
+// ---- Welcome Banner ----
+
+export function WelcomeBanner({ model, toolCount }) {
+    return h(Box, { flexDirection: 'column', marginBottom: 1 },
+        h(Text, { bold: true }, 'open-claude-code v2'),
+        h(Text, { dimColor: true }, 'Model: ', model || 'default', ' | Tools: ', toolCount || 0),
+        h(Text, { dimColor: true }, 'Type your prompt or /help. Press Ctrl+C to exit.'),
+    );
+}

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');
+}