awel 0.1.0

package/dist/cli/sse.d.ts

@@ -0,0 +1,17 @@
+import type { SSEStreamingApi } from 'hono/streaming';
+export interface ChatMessage {
+    id: string;
+    eventType: string;
+    data: string;
+    timestamp: number;
+}
+export declare function addToHistory(eventType: string, data: string): void;
+export declare function getHistory(): ChatMessage[];
+export declare function clearHistory(): void;
+/**
+ * Helper to write an SSE event with a typed payload
+ */
+export declare function writeSSEEvent(stream: SSEStreamingApi, event: string, payload: {
+    type: string;
+    message: string;
+}): Promise<void>;

package/dist/cli/sse.js

@@ -0,0 +1,51 @@
+// In-memory chat history (persists for the lifetime of the CLI process)
+const chatHistory = [];
+const MAX_HISTORY = 500; // Limit to prevent memory bloat
+// Event types that should not be persisted in history
+const TRANSIENT_EVENTS = new Set(['status', 'done']);
+export function addToHistory(eventType, data) {
+    if (TRANSIENT_EVENTS.has(eventType))
+        return;
+    // Merge consecutive text events into a single history entry
+    if (eventType === 'text') {
+        const last = chatHistory[chatHistory.length - 1];
+        if (last && last.eventType === 'text') {
+            try {
+                const lastParsed = JSON.parse(last.data);
+                const newParsed = JSON.parse(data);
+                if (lastParsed.type === 'text' && newParsed.type === 'text') {
+                    lastParsed.text = (lastParsed.text || '') + (newParsed.text || '');
+                    last.data = JSON.stringify(lastParsed);
+                    return;
+                }
+            }
+            catch {
+                // Fall through to push as new entry
+            }
+        }
+    }
+    chatHistory.push({
+        id: crypto.randomUUID(),
+        eventType,
+        data,
+        timestamp: Date.now(),
+    });
+    // Trim old messages if we exceed the limit
+    if (chatHistory.length > MAX_HISTORY) {
+        chatHistory.splice(0, chatHistory.length - MAX_HISTORY);
+    }
+}
+export function getHistory() {
+    return [...chatHistory];
+}
+export function clearHistory() {
+    chatHistory.length = 0;
+}
+/**
+ * Helper to write an SSE event with a typed payload
+ */
+export async function writeSSEEvent(stream, event, payload) {
+    const data = JSON.stringify(payload);
+    addToHistory(event, data);
+    await stream.writeSSE({ event, data });
+}

package/dist/cli/subprocess.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Subprocess manager singleton for the user's dev server.
+ * Handles spawning, restarting, health checks, and auto-restart on crash.
+ */
+export type DevServerStatus = 'stopped' | 'starting' | 'running' | 'restarting' | 'crashed';
+/**
+ * Spawn the dev server. Called once from CLI entry point.
+ */
+export declare function spawnDevServer(opts: {
+    port: number;
+    cwd: string;
+}): Promise<void>;
+/**
+ * Restart the dev server. Sends SIGTERM, waits for exit, then spawns a new one.
+ */
+export declare function restartDevServer(): Promise<{
+    success: boolean;
+    message: string;
+}>;
+/**
+ * Get the current status of the dev server.
+ */
+export declare function getDevServerStatus(): {
+    status: DevServerStatus;
+    port: number;
+    startedAt: number | null;
+    restartCount: number;
+    lastError: string | null;
+    pid: number | undefined;
+};

package/dist/cli/subprocess.js

@@ -0,0 +1,163 @@
+/**
+ * Subprocess manager singleton for the user's dev server.
+ * Handles spawning, restarting, health checks, and auto-restart on crash.
+ */
+import { execa } from 'execa';
+import { awel, pipeChildOutput } from './logger.js';
+const state = {
+    process: null,
+    status: 'stopped',
+    port: 3000,
+    cwd: process.cwd(),
+    startedAt: null,
+    restartCount: 0,
+    lastError: null,
+};
+let autoRestartEnabled = true;
+/**
+ * Wait for the dev server to respond on its port.
+ * Polls with 500ms intervals up to the timeout.
+ */
+async function waitForServer(port, timeoutMs = 30_000) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        try {
+            const res = await fetch(`http://localhost:${port}`, {
+                signal: AbortSignal.timeout(2000),
+            });
+            // Any response (even 500) means the server is up
+            if (res.status)
+                return true;
+        }
+        catch {
+            // Not ready yet
+        }
+        await new Promise(r => setTimeout(r, 500));
+    }
+    return false;
+}
+/**
+ * Spawn the dev server process and pipe its output.
+ */
+function spawn(port, cwd) {
+    const child = execa('npm', ['run', 'dev'], {
+        stdin: 'inherit',
+        env: {
+            ...process.env,
+            PORT: String(port),
+        },
+        cwd,
+    });
+    pipeChildOutput(child);
+    return child;
+}
+/**
+ * Compute exponential backoff delay for auto-restart.
+ */
+function getBackoffDelay(restartCount) {
+    const delay = Math.min(1000 * Math.pow(2, restartCount - 1), 10_000);
+    return delay;
+}
+/**
+ * Handle process exit — auto-restart with exponential backoff if enabled.
+ */
+function attachExitHandler(child) {
+    child.catch(async (error) => {
+        // Don't auto-restart if we're intentionally stopping or restarting
+        if (state.status === 'restarting' || state.status === 'stopped')
+            return;
+        state.status = 'crashed';
+        state.lastError = error instanceof Error ? error.message : String(error);
+        awel.error(`Dev server crashed: ${state.lastError}`);
+        if (!autoRestartEnabled)
+            return;
+        state.restartCount++;
+        const delay = getBackoffDelay(state.restartCount);
+        awel.log(`Auto-restarting dev server in ${delay}ms (attempt ${state.restartCount})...`);
+        await new Promise(r => setTimeout(r, delay));
+        // Check we're still in crashed state (user may have manually restarted)
+        if (state.status !== 'crashed')
+            return;
+        try {
+            await doSpawn();
+            awel.log('Dev server auto-restarted successfully.');
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            awel.error(`Auto-restart failed: ${msg}`);
+        }
+    });
+}
+/**
+ * Internal spawn + health-check routine.
+ */
+async function doSpawn() {
+    state.status = 'starting';
+    const child = spawn(state.port, state.cwd);
+    state.process = child;
+    attachExitHandler(child);
+    const ready = await waitForServer(state.port);
+    if (ready) {
+        state.status = 'running';
+        state.startedAt = Date.now();
+    }
+    else {
+        awel.error('Dev server did not respond within 30s — it may still be starting.');
+        // Keep it as 'starting'; the exit handler will catch a crash if it happens
+    }
+}
+/**
+ * Spawn the dev server. Called once from CLI entry point.
+ */
+export async function spawnDevServer(opts) {
+    state.port = opts.port;
+    state.cwd = opts.cwd;
+    state.restartCount = 0;
+    awel.log('Starting your Next.js app...');
+    await doSpawn();
+}
+/**
+ * Restart the dev server. Sends SIGTERM, waits for exit, then spawns a new one.
+ */
+export async function restartDevServer() {
+    if (!state.process) {
+        return { success: false, message: 'No dev server process to restart.' };
+    }
+    state.status = 'restarting';
+    awel.log('Restarting dev server...');
+    // Kill current process
+    try {
+        state.process.kill('SIGTERM');
+        // Wait up to 5s for graceful shutdown
+        await Promise.race([
+            state.process.catch(() => { }),
+            new Promise(r => setTimeout(r, 5000)),
+        ]);
+    }
+    catch {
+        // Process may already be dead
+    }
+    state.process = null;
+    state.restartCount = 0;
+    try {
+        await doSpawn();
+        return { success: true, message: 'Dev server restarted successfully.' };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { success: false, message: `Restart failed: ${msg}` };
+    }
+}
+/**
+ * Get the current status of the dev server.
+ */
+export function getDevServerStatus() {
+    return {
+        status: state.status,
+        port: state.port,
+        startedAt: state.startedAt,
+        restartCount: state.restartCount,
+        lastError: state.lastError,
+        pid: state.process?.pid,
+    };
+}

package/dist/cli/tools/ask-user.d.ts

@@ -0,0 +1,11 @@
+export declare function createAskUserTool(): import("ai").Tool<{
+    questions: {
+        question: string;
+        header: string;
+        multiSelect: boolean;
+        options: {
+            label: string;
+            description: string;
+        }[];
+    }[];
+}, string>;

package/dist/cli/tools/ask-user.js

@@ -0,0 +1,28 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+export function createAskUserTool() {
+    return tool({
+        description: 'Ask the user clarifying questions before proceeding with a task. ' +
+            'Use this when you need to gather preferences, clarify ambiguous requirements, ' +
+            'or let the user choose between approaches. Present 1-4 questions, each with 2-4 options. ' +
+            'Set multiSelect to true when choices are not mutually exclusive. ' +
+            'After asking, STOP and wait for the user to respond before continuing. ' +
+            'IMPORTANT: All string fields must be plain text — no markdown, no bullet points, no bold/italic, no code blocks. ' +
+            'The UI renders these strings directly in a structured card layout.',
+        inputSchema: z.object({
+            questions: z.array(z.object({
+                question: z.string().describe('The full question text. Plain text only, no markdown.'),
+                header: z.string().describe('Short tab label (max 12 chars). Plain text only, e.g. "Framework" or "Auth method".'),
+                multiSelect: z.boolean().describe('Whether the user can select multiple options'),
+                options: z.array(z.object({
+                    label: z.string().describe('Short option name (1-5 words). Plain text only, no markdown.'),
+                    description: z.string().describe('One sentence explaining this option. Plain text only, no markdown.'),
+                })).min(2).max(4),
+            })).min(1).max(4),
+        }),
+        execute: async (input) => {
+            // Actual interception happens in the streaming loop (vercel.ts).
+            return JSON.stringify(input);
+        },
+    });
+}

package/dist/cli/tools/bash.d.ts

@@ -0,0 +1,4 @@
+export declare function createBashTool(cwd: string): import("ai").Tool<{
+    command: string;
+    timeout: number;
+}, string>;

package/dist/cli/tools/bash.js

@@ -0,0 +1,30 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+import { execSync } from 'child_process';
+export function createBashTool(cwd) {
+    return tool({
+        description: 'Execute a shell command and return stdout/stderr. Runs in the project directory.',
+        inputSchema: z.object({
+            command: z.string().describe('The shell command to execute'),
+            timeout: z.number().optional().default(30000).describe('Timeout in milliseconds (default 30s)'),
+        }),
+        execute: async ({ command, timeout }) => {
+            try {
+                const output = execSync(command, {
+                    cwd,
+                    encoding: 'utf-8',
+                    timeout,
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                    maxBuffer: 1024 * 1024, // 1MB
+                });
+                return output || '(no output)';
+            }
+            catch (err) {
+                const execErr = err;
+                const stderr = execErr.stderr || '';
+                const stdout = execErr.stdout || '';
+                return `Error: ${execErr.message || 'Command failed'}\n${stderr}\n${stdout}`.trim();
+            }
+        },
+    });
+}

package/dist/cli/tools/code-search.d.ts

@@ -0,0 +1,4 @@
+export declare function createCodeSearchTool(): import("ai").Tool<{
+    query: string;
+    tokensNum: number;
+}, string>;

package/dist/cli/tools/code-search.js

@@ -0,0 +1,70 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+const API_CONFIG = {
+    BASE_URL: 'https://mcp.exa.ai',
+    ENDPOINT: '/mcp',
+    TIMEOUT_MS: 30_000,
+    DEFAULT_TOKENS: 5_000,
+};
+export function createCodeSearchTool() {
+    return tool({
+        description: 'Search the web for code examples, API documentation, and SDK references. ' +
+            'Use this when you need to look up how to use a library, find code patterns, ' +
+            'or check API usage. Returns code-focused results from documentation and repositories.',
+        inputSchema: z.object({
+            query: z.string().describe('Search query for code examples or documentation (e.g. "Next.js App Router middleware example", "zod union type validation")'),
+            tokensNum: z.number().optional().default(5000)
+                .describe('Response length control: 1000-50000 tokens (default: 5000). Use higher values for detailed API docs.'),
+        }),
+        execute: async ({ query, tokensNum }) => {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), API_CONFIG.TIMEOUT_MS);
+            try {
+                const response = await fetch(`${API_CONFIG.BASE_URL}${API_CONFIG.ENDPOINT}`, {
+                    method: 'POST',
+                    headers: {
+                        'accept': 'application/json, text/event-stream',
+                        'content-type': 'application/json',
+                    },
+                    body: JSON.stringify({
+                        jsonrpc: '2.0',
+                        id: 1,
+                        method: 'tools/call',
+                        params: {
+                            name: 'codedocs',
+                            arguments: {
+                                query,
+                                tokensNum: Math.min(Math.max(tokensNum || API_CONFIG.DEFAULT_TOKENS, 1000), 50000),
+                            },
+                        },
+                    }),
+                    signal: controller.signal,
+                });
+                clearTimeout(timeoutId);
+                if (!response.ok) {
+                    const errorText = await response.text();
+                    return `Search error (${response.status}): ${errorText}`;
+                }
+                const responseText = await response.text();
+                // Parse SSE response
+                const lines = responseText.split('\n');
+                for (const line of lines) {
+                    if (line.startsWith('data: ')) {
+                        const data = JSON.parse(line.substring(6));
+                        if (data.result?.content?.length > 0) {
+                            return data.result.content[0].text;
+                        }
+                    }
+                }
+                return 'No code examples found. Try a more specific query.';
+            }
+            catch (err) {
+                clearTimeout(timeoutId);
+                if (err instanceof Error && err.name === 'AbortError') {
+                    return 'Error: Code search request timed out after 30 seconds.';
+                }
+                return `Error: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        },
+    });
+}

package/dist/cli/tools/edit.d.ts

@@ -0,0 +1,6 @@
+export declare function createEditTool(cwd: string): import("ai").Tool<{
+    file_path: string;
+    old_string: string;
+    new_string: string;
+    replace_all: boolean;
+}, string>;

package/dist/cli/tools/edit.js

@@ -0,0 +1,37 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import { pushSnapshot } from '../undo.js';
+export function createEditTool(cwd) {
+    return tool({
+        description: 'Perform a find-and-replace edit on a file. Replaces the first occurrence of old_string with new_string. Use replace_all to replace every occurrence.',
+        inputSchema: z.object({
+            file_path: z.string().describe('The path to the file to edit (absolute or relative to project root)'),
+            old_string: z.string().describe('The exact string to find in the file'),
+            new_string: z.string().describe('The replacement string'),
+            replace_all: z.boolean().optional().default(false).describe('Replace all occurrences instead of just the first'),
+        }),
+        execute: async ({ file_path, old_string, new_string, replace_all }) => {
+            const fullPath = file_path.startsWith('/') ? file_path : resolve(cwd, file_path);
+            if (!existsSync(fullPath)) {
+                return `Error: File not found: ${fullPath}`;
+            }
+            try {
+                pushSnapshot(fullPath);
+                const content = readFileSync(fullPath, 'utf-8');
+                if (!content.includes(old_string)) {
+                    return `Error: old_string not found in ${file_path}`;
+                }
+                const updated = replace_all
+                    ? content.replaceAll(old_string, new_string)
+                    : content.replace(old_string, new_string);
+                writeFileSync(fullPath, updated, 'utf-8');
+                return `Successfully edited ${file_path}`;
+            }
+            catch (err) {
+                return `Error editing file: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        },
+    });
+}

package/dist/cli/tools/glob.d.ts

@@ -0,0 +1,4 @@
+export declare function createGlobTool(cwd: string): import("ai").Tool<{
+    pattern: string;
+    path?: string | undefined;
+}, string>;

package/dist/cli/tools/glob.js

@@ -0,0 +1,29 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+import fg from 'fast-glob';
+export function createGlobTool(cwd) {
+    return tool({
+        description: 'Find files matching a glob pattern. Returns a list of matching file paths relative to the project root.',
+        inputSchema: z.object({
+            pattern: z.string().describe('Glob pattern (e.g. "**/*.ts", "src/**/*.tsx")'),
+            path: z.string().optional().describe('Directory to search in (default: project root)'),
+        }),
+        execute: async ({ pattern, path }) => {
+            try {
+                const searchDir = path || cwd;
+                const files = await fg(pattern, {
+                    cwd: searchDir,
+                    dot: false,
+                    ignore: ['**/node_modules/**', '**/.git/**', '**/dist/**'],
+                });
+                if (files.length === 0) {
+                    return 'No files matched the pattern.';
+                }
+                return files.join('\n');
+            }
+            catch (err) {
+                return `Error: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        },
+    });
+}

package/dist/cli/tools/grep.d.ts

@@ -0,0 +1,5 @@
+export declare function createGrepTool(cwd: string): import("ai").Tool<{
+    pattern: string;
+    path?: string | undefined;
+    include?: string | undefined;
+}, string>;

package/dist/cli/tools/grep.js

@@ -0,0 +1,146 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+import { execSync } from 'child_process';
+import { readFileSync } from 'fs';
+import { resolve, relative } from 'path';
+import fg from 'fast-glob';
+const MAX_RESULTS = 100;
+const MAX_LINE_LENGTH = 2000;
+const IGNORE_DIRS = ['node_modules', '.git', 'dist', 'build', '.next'];
+/** Check once at startup whether ripgrep is available. */
+let rgAvailable = null;
+function hasRipgrep() {
+    if (rgAvailable === null) {
+        try {
+            execSync('rg --version', { stdio: 'pipe', timeout: 3000 });
+            rgAvailable = true;
+        }
+        catch {
+            rgAvailable = false;
+        }
+    }
+    return rgAvailable;
+}
+export function createGrepTool(cwd) {
+    return tool({
+        description: 'Search file contents for a regex pattern. ' +
+            'Returns matching lines with file paths and line numbers. ' +
+            'Use this to find where functions are defined, where variables are used, ' +
+            'or to locate specific strings across the codebase.',
+        inputSchema: z.object({
+            pattern: z.string().describe('Regex pattern to search for (e.g. "function\\s+handleSubmit", "TODO", "import.*from")'),
+            path: z.string().optional().describe('Directory or file to search in (default: project root)'),
+            include: z.string().optional().describe('File glob filter (e.g. "*.ts", "*.{js,jsx,ts,tsx}")'),
+        }),
+        execute: async ({ pattern, path, include }) => {
+            const searchPath = path
+                ? (path.startsWith('/') ? path : resolve(cwd, path))
+                : cwd;
+            if (hasRipgrep()) {
+                return searchWithRipgrep(cwd, pattern, searchPath, include);
+            }
+            return searchWithNode(cwd, pattern, searchPath, include);
+        },
+    });
+}
+function searchWithRipgrep(cwd, pattern, searchPath, include) {
+    const args = [
+        '--no-heading',
+        '--line-number',
+        '--color=never',
+        '--max-count=5',
+        '--hidden',
+        '--follow',
+        ...IGNORE_DIRS.map(d => `--glob=!${d}`),
+    ];
+    if (include) {
+        args.push(`--glob=${include}`);
+    }
+    args.push('--', pattern, searchPath);
+    try {
+        const output = execSync(`rg ${args.map(a => `'${a.replace(/'/g, "'\\''")}'`).join(' ')}`, {
+            cwd,
+            encoding: 'utf-8',
+            timeout: 15_000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            maxBuffer: 2 * 1024 * 1024,
+        });
+        return formatOutput(output);
+    }
+    catch (err) {
+        const execErr = err;
+        if (execErr.status === 1) {
+            return 'No matches found.';
+        }
+        return `Error: ${execErr.stderr || execErr.message || 'Search failed'}`.trim();
+    }
+}
+async function searchWithNode(cwd, pattern, searchPath, include) {
+    let regex;
+    try {
+        regex = new RegExp(pattern);
+    }
+    catch {
+        return `Error: Invalid regex pattern: ${pattern}`;
+    }
+    const globPattern = include || '**/*';
+    const ignore = IGNORE_DIRS.map(d => `**/${d}/**`);
+    let files;
+    try {
+        files = await fg(globPattern, {
+            cwd: searchPath,
+            dot: true,
+            ignore,
+            followSymbolicLinks: true,
+            onlyFiles: true,
+            absolute: true,
+        });
+    }
+    catch {
+        return 'Error: Failed to list files for search.';
+    }
+    const matches = [];
+    let matchCount = 0;
+    for (const filePath of files) {
+        if (matchCount >= MAX_RESULTS)
+            break;
+        let content;
+        try {
+            content = readFileSync(filePath, 'utf-8');
+        }
+        catch {
+            continue; // skip binary / unreadable files
+        }
+        // Quick binary check: skip files with null bytes
+        if (content.includes('\0'))
+            continue;
+        const lines = content.split('\n');
+        let fileMatches = 0;
+        for (let i = 0; i < lines.length; i++) {
+            if (fileMatches >= 5 || matchCount >= MAX_RESULTS)
+                break;
+            if (regex.test(lines[i])) {
+                const rel = relative(cwd, filePath);
+                const line = lines[i].length > MAX_LINE_LENGTH
+                    ? lines[i].slice(0, MAX_LINE_LENGTH) + '...'
+                    : lines[i];
+                matches.push(`${rel}:${i + 1}:${line}`);
+                fileMatches++;
+                matchCount++;
+            }
+        }
+    }
+    if (matches.length === 0) {
+        return 'No matches found.';
+    }
+    return matches.join('\n');
+}
+function formatOutput(output) {
+    const lines = output.split('\n').filter(Boolean);
+    const truncated = lines.slice(0, MAX_RESULTS).map(line => line.length > MAX_LINE_LENGTH ? line.slice(0, MAX_LINE_LENGTH) + '...' : line);
+    const result = truncated.join('\n');
+    const suffix = lines.length > MAX_RESULTS
+        ? `\n\n(showing ${MAX_RESULTS} of ${lines.length} matches)`
+        : '';
+    return result + suffix || 'No matches found.';
+}