runwork 0.2.4 → 0.3.0

package/dist/git/sync.js

@@ -0,0 +1,157 @@
+import { execFileSync } from 'child_process';
+import { unlinkSync } from 'fs';
+import { join } from 'path';
+export function hasCommits(cwd) {
+    try {
+        execFileSync('git', ['rev-parse', 'HEAD'], { cwd, stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function hasTrackedChanges(cwd) {
+    try {
+        const output = execFileSync('git', ['status', '--porcelain'], { cwd, encoding: 'utf-8' });
+        return output.trim().split('\n').some(line => line.length > 0 && !line.startsWith('??'));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Remove untracked local files that exist on the remote.
+ * Skeleton files are ephemeral (re-downloaded each session) so the
+ * server's versions take precedence. User-edited files are already
+ * tracked/committed at this point and won't be affected.
+ */
+function removeConflictingUntrackedFiles(cwd) {
+    try {
+        const remoteFiles = execFileSync('git', ['ls-tree', '-r', '--name-only', 'runwork/main'], {
+            cwd,
+            encoding: 'utf-8',
+        }).trim().split('\n');
+        const untrackedOutput = execFileSync('git', ['ls-files', '--others', '--exclude-standard'], {
+            cwd,
+            encoding: 'utf-8',
+        }).trim();
+        const untracked = new Set(untrackedOutput.split('\n').filter(Boolean));
+        for (const file of remoteFiles) {
+            if (untracked.has(file)) {
+                try {
+                    unlinkSync(join(cwd, file));
+                }
+                catch { /* already gone */ }
+            }
+        }
+    }
+    catch {
+        // best effort
+    }
+}
+function extractGitError(err) {
+    if (err && typeof err === 'object') {
+        const obj = err;
+        // execFileSync errors have stderr and stdout as Buffer or string
+        const stderr = bufToStr(obj.stderr);
+        const stdout = bufToStr(obj.stdout);
+        // Prefer stderr (git's error output), fall back to stdout (merge conflict details)
+        if (stderr)
+            return stderr;
+        if (stdout)
+            return stdout;
+    }
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+function bufToStr(val) {
+    if (!val)
+        return '';
+    if (typeof val === 'string')
+        return val.trim();
+    if (Buffer.isBuffer(val))
+        return val.toString('utf-8').trim();
+    return '';
+}
+/**
+ * Sync local repository with the runwork remote.
+ *
+ * Strategy: fetch, then attempt rebase. If rebase fails (e.g. diverged
+ * histories after a template update), fall back to merge with
+ * --allow-unrelated-histories. Stash/pop around dirty working trees.
+ */
+export function syncWithRemote(cwd) {
+    if (!hasCommits(cwd)) {
+        return { status: 'skipped', pushed: false };
+    }
+    const dirty = hasTrackedChanges(cwd);
+    if (dirty) {
+        execFileSync('git', ['stash', 'push', '-m', 'runwork-dev-sync'], { cwd, stdio: 'pipe' });
+    }
+    let status = 'synced';
+    let syncError;
+    try {
+        execFileSync('git', ['fetch', 'runwork', 'main'], { cwd, stdio: 'pipe' });
+        removeConflictingUntrackedFiles(cwd);
+        try {
+            execFileSync('git', ['rebase', 'runwork/main'], { cwd, stdio: 'pipe' });
+        }
+        catch (rebaseErr) {
+            try {
+                execFileSync('git', ['rebase', '--abort'], { cwd, stdio: 'pipe' });
+            }
+            catch { /* no rebase in progress */ }
+            try {
+                execFileSync('git', ['merge', 'runwork/main', '--allow-unrelated-histories', '--no-edit'], { cwd, stdio: 'pipe' });
+                status = 'merged';
+            }
+            catch {
+                // Merge conflicts (common with unrelated histories / first sync).
+                // Abort and retry accepting the remote's version for all conflicts.
+                // This is safe because: user edits were committed before sync,
+                // and local template files are ephemeral (re-downloaded each session).
+                try {
+                    execFileSync('git', ['merge', '--abort'], { cwd, stdio: 'pipe' });
+                }
+                catch { /* no merge in progress */ }
+                try {
+                    execFileSync('git', ['merge', 'runwork/main', '--allow-unrelated-histories', '--no-edit', '-X', 'theirs'], { cwd, stdio: 'pipe' });
+                    status = 'merged';
+                }
+                catch (mergeErr) {
+                    try {
+                        execFileSync('git', ['merge', '--abort'], { cwd, stdio: 'pipe' });
+                    }
+                    catch { /* no merge in progress */ }
+                    status = 'sync-failed';
+                    syncError = extractGitError(mergeErr);
+                }
+            }
+        }
+    }
+    catch (fetchErr) {
+        status = 'sync-failed';
+        syncError = extractGitError(fetchErr);
+    }
+    if (dirty) {
+        try {
+            execFileSync('git', ['stash', 'pop'], { cwd, stdio: 'pipe' });
+        }
+        catch {
+            return { status, pushed: false, error: 'stash-conflict' };
+        }
+    }
+    if (status === 'sync-failed') {
+        return { status, pushed: false, error: syncError };
+    }
+    let pushed = false;
+    try {
+        execFileSync('git', ['push', 'runwork', 'main'], { cwd, stdio: 'pipe' });
+        pushed = true;
+    }
+    catch {
+        // push failed — continue with current state
+    }
+    return { status, pushed };
+}

package/dist/index.js

@@ -8,6 +8,7 @@ import { logsCommand } from './commands/logs.js';
 import { upgradeCommand } from './commands/upgrade.js';
 import { logoutCommand } from './commands/logout.js';
 import { integrationsCommand } from './commands/integrations.js';
+import { openCommand } from './commands/open.js';
 import { handleGitCredentialRequest } from './git/credentials.js';
 import { VERSION } from './generated/version.js';
 const program = new Command();
@@ -24,6 +25,7 @@ program.addCommand(logsCommand);
 program.addCommand(upgradeCommand);
 program.addCommand(logoutCommand);
 program.addCommand(integrationsCommand);
+program.addCommand(openCommand);
 const credentialHelper = program
     .command('git-credential-helper', { hidden: true })
     .argument('<action>', 'Credential action (get/store/erase)')
@@ -32,4 +34,18 @@ const credentialHelper = program
     await handleGitCredentialRequest(action);
 });
 credentialHelper.helpOption(false);
+// First-run detection: bare `runwork` with no command and no credentials -> welcome wizard
+const args = process.argv.slice(2);
+const isHelpOrVersion = args.includes('--help') || args.includes('-h') ||
+    args.includes('--version') || args.includes('-v') || args.includes('-V');
+const knownCommands = program.commands.map(c => c.name());
+const hasCommand = args.some(arg => !arg.startsWith('-') && knownCommands.includes(arg));
+if (!hasCommand && !isHelpOrVersion && args.length === 0) {
+    const { getCredentials } = await import('./auth/store.js');
+    if (!getCredentials()) {
+        const { runWelcomeWizard } = await import('./commands/welcome.js');
+        await runWelcomeWizard();
+        process.exit(0);
+    }
+}
 program.parse();

package/dist/logs/__tests__/tailer-format.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/logs/__tests__/tailer-format.test.js

@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest';
+import { formatLogLine, formatRelativeTime } from '../tailer.js';
+import { stripAnsi } from '../../ui/colors.js';
+describe('formatLogLine', () => {
+    it('formats RUNTIME lines with timestamp and tag', () => {
+        const line = formatLogLine('RUNTIME', 'Server started on port 8787');
+        const plain = stripAnsi(line);
+        expect(plain).toMatch(/\d{2}:\d{2}:\d{2}/);
+        expect(plain).toContain('RUNTIME');
+        expect(plain).toContain('Server started on port 8787');
+    });
+    it('formats ERROR lines', () => {
+        const line = formatLogLine('ERROR', 'Something broke');
+        const plain = stripAnsi(line);
+        expect(plain).toContain('ERROR');
+    });
+    it('formats EVENT lines', () => {
+        const line = formatLogLine('EVENT', 'workflow_completed: done');
+        const plain = stripAnsi(line);
+        expect(plain).toContain('EVENT');
+    });
+    it('indents log lines with 2 spaces', () => {
+        const line = formatLogLine('RUNTIME', 'test');
+        expect(line.startsWith('  ')).toBe(true);
+    });
+});
+describe('formatRelativeTime', () => {
+    it('returns "now" for future timestamps', () => {
+        const future = new Date(Date.now() + 10000).toISOString();
+        expect(formatRelativeTime(future)).toBe('now');
+    });
+    it('returns seconds for recent events', () => {
+        const recent = new Date(Date.now() - 5000).toISOString();
+        expect(formatRelativeTime(recent)).toMatch(/\ds ago/);
+    });
+    it('returns minutes for older events', () => {
+        const older = new Date(Date.now() - 120000).toISOString();
+        expect(formatRelativeTime(older)).toMatch(/\dm ago/);
+    });
+    it('returns absolute time when no timestamp given', () => {
+        expect(formatRelativeTime()).toMatch(/\d{2}:\d{2}:\d{2}/);
+    });
+});

package/dist/logs/tailer.d.ts

@@ -6,7 +6,10 @@ interface TailerOptions {
     toTerminal: boolean;
     toFile: boolean;
     intervalMs?: number;
+    getFilter?: () => 'all' | 'events' | 'runtime';
 }
+export declare function formatLogLine(tag: string, line: string): string;
+export declare function formatRelativeTime(eventTimestamp?: string): string;
 export declare function startLogTailer(options: TailerOptions): {
     stop: () => void;
 };

package/dist/logs/tailer.js

@@ -1,5 +1,7 @@
 import { appendFileSync, mkdirSync, writeFileSync } from 'fs';
 import { join, dirname } from 'path';
+import { bold, red, yellow, cyan, gray, dim } from '../ui/colors.js';
+import { stripAnsi } from '../ui/colors.js';
 const LOG_FILE = '.runwork/logs.txt';
 function formatTime() {
     const now = new Date();
@@ -9,8 +11,35 @@ function formatTime() {
         String(now.getSeconds()).padStart(2, '0'),
     ].join(':');
 }
-function formatLogLine(tag, line) {
-    return `[${formatTime()}] [${tag}] ${line}`;
+export function formatLogLine(tag, line) {
+    const time = gray(formatTime());
+    let tagFormatted;
+    switch (tag) {
+        case 'ERROR':
+            tagFormatted = bold(red('ERROR  '));
+            break;
+        case 'EVENT':
+            tagFormatted = yellow('EVENT  ');
+            break;
+        case 'RUNTIME':
+            tagFormatted = cyan('RUNTIME');
+            break;
+        default:
+            tagFormatted = dim(tag.padEnd(7));
+    }
+    return `  ${time} ${tagFormatted}  ${line}`;
+}
+export function formatRelativeTime(eventTimestamp) {
+    if (!eventTimestamp)
+        return formatTime();
+    const diff = Date.now() - new Date(eventTimestamp).getTime();
+    if (diff < 0)
+        return 'now';
+    if (diff < 60_000)
+        return `${Math.floor(diff / 1000)}s ago`;
+    if (diff < 3_600_000)
+        return `${Math.floor(diff / 60_000)}m ago`;
+    return formatTime();
 }
 export function startLogTailer(options) {
     const { appId, client, projectDir, toTerminal, toFile, intervalMs = 5000, } = options;
@@ -25,18 +54,25 @@ export function startLogTailer(options) {
     let seenEventIds = new Set();
     let stopped = false;
     let timer;
-    function writeLine(line) {
-        if (toTerminal) {
-            console.log(line);
-        }
+    function writeLineFiltered(line, tag) {
+        // Always write to file (stripped of ANSI codes)
         if (toFile) {
             try {
-                appendFileSync(logFilePath, line + '\n', 'utf-8');
+                appendFileSync(logFilePath, stripAnsi(line) + '\n', 'utf-8');
             }
             catch {
                 // Silently ignore file write errors
             }
         }
+        // Filter for terminal
+        if (!toTerminal)
+            return;
+        const filter = options.getFilter?.() || 'all';
+        if (filter === 'events' && tag !== 'EVENT')
+            return;
+        if (filter === 'runtime' && tag !== 'RUNTIME' && tag !== 'ERROR')
+            return;
+        console.log(line);
     }
     async function poll() {
         if (stopped)
@@ -55,7 +91,7 @@ export function startLogTailer(options) {
                 const newContent = logs.stdout.slice(lastStdoutLength);
                 const lines = newContent.split('\n').filter(Boolean);
                 for (const line of lines) {
-                    writeLine(formatLogLine('RUNTIME', line));
+                    writeLineFiltered(formatLogLine('RUNTIME', line), 'RUNTIME');
                 }
                 lastStdoutLength = logs.stdout.length;
             }
@@ -63,7 +99,7 @@ export function startLogTailer(options) {
                 const newContent = logs.stderr.slice(lastStderrLength);
                 const lines = newContent.split('\n').filter(Boolean);
                 for (const line of lines) {
-                    writeLine(formatLogLine('ERROR', line));
+                    writeLineFiltered(formatLogLine('ERROR', line), 'ERROR');
                 }
                 lastStderrLength = logs.stderr.length;
             }
@@ -98,7 +134,8 @@ export function startLogTailer(options) {
                             detail += ` [${meta.path}]`;
                         }
                     }
-                    writeLine(formatLogLine('EVENT', `${event.type}: ${detail}`));
+                    const relTime = gray(formatRelativeTime(event.timestamp));
+                    writeLineFiltered(`  ${relTime} ${yellow('EVENT  ')}  ${event.type}: ${detail}`, 'EVENT');
                     seenEventIds.add(event.id);
                 }
                 // Cap the set size to prevent unbounded growth (keep last 200 IDs)

package/dist/template/manifest.js

@@ -63,10 +63,13 @@ export async function loadManifest(dir) {
  */
 export async function detectUserEdits(dir, manifest) {
     const edits = [];
-    // 1. Uncommitted changes to tracked files
+    // 1. Uncommitted changes to tracked files (skip if no commits yet)
+    // Use -c core.quotePath=false to get real filenames instead of octal-escaped quoted strings
+    // for non-ASCII characters (e.g. "caf\303\251.txt" → café.txt)
     try {
-        const modified = execFileSync('git', ['diff', '--name-only', 'HEAD'], { cwd: dir, encoding: 'utf-8' }).trim();
-        const staged = execFileSync('git', ['diff', '--cached', '--name-only'], { cwd: dir, encoding: 'utf-8' }).trim();
+        execFileSync('git', ['rev-parse', 'HEAD'], { cwd: dir, stdio: 'pipe' });
+        const modified = execFileSync('git', ['-c', 'core.quotePath=false', 'diff', '--name-only', 'HEAD'], { cwd: dir, encoding: 'utf-8' }).trim();
+        const staged = execFileSync('git', ['-c', 'core.quotePath=false', 'diff', '--cached', '--name-only'], { cwd: dir, encoding: 'utf-8' }).trim();
         for (const file of [...modified.split('\n'), ...staged.split('\n')]) {
             if (file && !edits.includes(file))
                 edits.push(file);
@@ -77,7 +80,7 @@ export async function detectUserEdits(dir, manifest) {
     }
     // 2. Untracked files that aren't template files
     try {
-        const untracked = execFileSync('git', ['ls-files', '--others', '--exclude-standard'], { cwd: dir, encoding: 'utf-8' }).trim();
+        const untracked = execFileSync('git', ['-c', 'core.quotePath=false', 'ls-files', '--others', '--exclude-standard'], { cwd: dir, encoding: 'utf-8' }).trim();
         for (const relPath of untracked.split('\n')) {
             if (!relPath)
                 continue;
@@ -98,5 +101,22 @@ export async function detectUserEdits(dir, manifest) {
     catch {
         // No git repo
     }
+    // 3. Scan manifest files on disk directly — catches gitignored files that
+    // git ls-files --exclude-standard would miss. If a template file was added
+    // to .gitignore by the user and then modified, only this check detects it.
+    for (const [relPath, expectedHash] of Object.entries(manifest.files)) {
+        if (edits.includes(relPath))
+            continue;
+        const filePath = join(dir, relPath);
+        try {
+            const content = readFileSync(filePath);
+            if (sha256(content) !== expectedHash) {
+                edits.push(relPath);
+            }
+        }
+        catch {
+            // File doesn't exist on disk — not an edit to detect
+        }
+    }
     return edits;
 }

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 export interface RunworkConfig {
     workspaceId: string;
+    workspaceName?: string;
     appId: string;
     appName: string;
 }

package/dist/ui/__tests__/banner.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ui/__tests__/banner.test.js

@@ -0,0 +1,82 @@
+import { describe, it, expect } from 'vitest';
+import { getAgentCommand, SUPPORTED_AGENTS, getDevBanner, getKeyboardHints, getWelcomeBanner, getInfoPanel } from '../banner.js';
+import { stripAnsi } from '../colors.js';
+describe('getAgentCommand', () => {
+    it('returns claude command for a directory', () => {
+        const cmd = getAgentCommand('claude-code', '/path/to/app');
+        expect(cmd).toContain('claude');
+        expect(cmd).toContain('/path/to/app');
+    });
+    it('returns cursor command', () => {
+        expect(getAgentCommand('cursor', '/path')).toContain('cursor');
+    });
+    it('returns codex command', () => {
+        expect(getAgentCommand('codex', '/path')).toContain('codex');
+    });
+    it('returns null for unknown agent', () => {
+        expect(getAgentCommand('unknown-agent', '/path')).toBe(null);
+    });
+});
+describe('SUPPORTED_AGENTS', () => {
+    it('includes common agents', () => {
+        const ids = SUPPORTED_AGENTS.map(a => a.id);
+        expect(ids).toContain('claude-code');
+        expect(ids).toContain('cursor');
+        expect(ids).toContain('codex');
+    });
+});
+describe('getDevBanner', () => {
+    it('includes preview URL and app name', () => {
+        const banner = getDevBanner({ appName: 'test-app', previewUrl: 'https://test.runwork.dev' });
+        const plain = stripAnsi(banner);
+        expect(plain).toContain('https://test.runwork.dev');
+        expect(plain).toContain('test-app');
+    });
+});
+describe('getKeyboardHints', () => {
+    it('includes shortcut keys', () => {
+        const hints = stripAnsi(getKeyboardHints());
+        expect(hints).toContain('o');
+        expect(hints).toContain('q');
+    });
+});
+describe('getInfoPanel', () => {
+    it('includes app info and agent commands', () => {
+        const panel = getInfoPanel({
+            appName: 'my-app',
+            previewUrl: 'https://test.dev',
+            workspaceName: 'my-ws',
+            directory: '/path/to/app',
+        });
+        const plain = stripAnsi(panel);
+        expect(plain).toContain('my-app');
+        expect(plain).toContain('https://test.dev');
+        expect(plain).toContain('my-ws');
+        expect(plain).toContain('/path/to/app');
+        expect(plain).toContain('Claude Code');
+        expect(plain).toContain('Cursor');
+    });
+    it('omits workspace when not provided', () => {
+        const panel = getInfoPanel({
+            appName: 'my-app',
+            previewUrl: 'https://test.dev',
+            directory: '/path',
+        });
+        const plain = stripAnsi(panel);
+        expect(plain).not.toContain('Workspace');
+    });
+});
+describe('getDevBanner', () => {
+    it('includes workspace name when provided', () => {
+        const banner = getDevBanner({ appName: 'app', previewUrl: 'https://x', workspaceName: 'ws' });
+        const plain = stripAnsi(banner);
+        expect(plain).toContain('ws');
+    });
+});
+describe('getWelcomeBanner', () => {
+    it('includes Runwork name and mentions AI agents', () => {
+        const text = stripAnsi(getWelcomeBanner());
+        expect(text).toContain('Runwork');
+        expect(text).toContain('Claude');
+    });
+});

package/dist/ui/__tests__/colors.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ui/__tests__/colors.test.js

@@ -0,0 +1,22 @@
+import { describe, it, expect } from 'vitest';
+import { bold, red, green, yellow, cyan, dim, gray, stripAnsi, pc } from '../colors.js';
+describe('colors', () => {
+    it('re-exports picocolors functions that produce strings', () => {
+        // Verify they're callable and return strings (not just that they exist)
+        expect(bold('test')).toEqual(expect.any(String));
+        expect(red('test')).toEqual(expect.any(String));
+        expect(green('test')).toEqual(expect.any(String));
+        expect(yellow('test')).toEqual(expect.any(String));
+        expect(cyan('test')).toEqual(expect.any(String));
+        expect(dim('test')).toEqual(expect.any(String));
+        expect(gray('test')).toEqual(expect.any(String));
+    });
+    it('exports the full picocolors object', () => {
+        expect(typeof pc.bold).toBe('function');
+    });
+    it('strips ANSI codes', () => {
+        expect(stripAnsi('\x1b[1mhello\x1b[22m')).toBe('hello');
+        expect(stripAnsi('no codes')).toBe('no codes');
+        expect(stripAnsi('\x1b[31m\x1b[1mfail\x1b[22m\x1b[39m')).toBe('fail');
+    });
+});

package/dist/ui/__tests__/keyboard.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ui/__tests__/keyboard.test.js

@@ -0,0 +1,30 @@
+import { describe, it, expect } from 'vitest';
+import { parseKeypress } from '../keyboard.js';
+describe('parseKeypress', () => {
+    it('detects "o" key', () => {
+        expect(parseKeypress(Buffer.from('o'))).toBe('o');
+    });
+    it('detects uppercase "O" as lowercase', () => {
+        expect(parseKeypress(Buffer.from('O'))).toBe('o');
+    });
+    it('detects "p" key', () => {
+        expect(parseKeypress(Buffer.from('p'))).toBe('p');
+    });
+    it('detects Ctrl+C as quit', () => {
+        expect(parseKeypress(Buffer.from([0x03]))).toBe('quit');
+    });
+    it('detects "q" as quit', () => {
+        expect(parseKeypress(Buffer.from('q'))).toBe('quit');
+    });
+    it('returns null for unknown keys', () => {
+        expect(parseKeypress(Buffer.from('x'))).toBe(null);
+    });
+    it('detects log filter keys (a, e, r)', () => {
+        expect(parseKeypress(Buffer.from('a'))).toBe('a');
+        expect(parseKeypress(Buffer.from('e'))).toBe('e');
+        expect(parseKeypress(Buffer.from('r'))).toBe('r');
+    });
+    it('detects "i" for info', () => {
+        expect(parseKeypress(Buffer.from('i'))).toBe('i');
+    });
+});

package/dist/ui/__tests__/status-line.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ui/__tests__/status-line.test.js

@@ -0,0 +1,54 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createStatusLine } from '../status-line.js';
+function createMockStream() {
+    const mockWrite = vi.fn().mockReturnValue(true);
+    return {
+        write: mockWrite,
+        isTTY: true,
+        rows: 24,
+        columns: 80,
+        on: vi.fn(),
+        removeListener: vi.fn(),
+    };
+}
+describe('createStatusLine', () => {
+    it('returns a no-op status line when not a TTY', () => {
+        const stream = createMockStream();
+        stream.isTTY = false;
+        const status = createStatusLine(stream);
+        status.update('test');
+        expect(stream.write).not.toHaveBeenCalled();
+    });
+    it('sets up scroll region on creation for TTY', () => {
+        const stream = createMockStream();
+        createStatusLine(stream);
+        // Should have written scroll region escape sequence
+        const output = stream.write.mock.calls.map((c) => c[0]).join('');
+        // Scroll region: \x1b[1;23r (rows-1 = 23)
+        expect(output).toContain('\x1b[1;23r');
+    });
+    it('writes status text with inverse styling', () => {
+        const stream = createMockStream();
+        const status = createStatusLine(stream);
+        status.update('Watching | 3 files synced');
+        const output = stream.write.mock.calls.map((c) => c[0]).join('');
+        expect(output).toContain('Watching');
+    });
+    it('listens for resize events', () => {
+        const stream = createMockStream();
+        createStatusLine(stream);
+        expect(stream.on).toHaveBeenCalledWith('resize', expect.any(Function));
+    });
+    it('cleans up on destroy', () => {
+        const stream = createMockStream();
+        const status = createStatusLine(stream);
+        status.update('test');
+        stream.write.mockClear();
+        status.destroy();
+        expect(stream.write).toHaveBeenCalled();
+        expect(stream.removeListener).toHaveBeenCalledWith('resize', expect.any(Function));
+        // Should reset scroll region to full terminal
+        const output = stream.write.mock.calls.map((c) => c[0]).join('');
+        expect(output).toContain('\x1b[1;24r');
+    });
+});

package/dist/ui/banner.d.ts

@@ -0,0 +1,29 @@
+export interface AgentInfo {
+    id: string;
+    name: string;
+    /** Shell command to open the agent in a directory. {dir} is replaced with the path. */
+    command: string;
+}
+export declare const SUPPORTED_AGENTS: AgentInfo[];
+export declare function getAgentCommand(agentId: string, directory: string): string | null;
+export declare function getAgentGuidance(directory: string): string;
+export interface DevBannerOptions {
+    appName: string;
+    previewUrl: string;
+    workspaceName?: string;
+}
+export declare function getDevBanner(options: DevBannerOptions): string;
+export declare function getKeyboardHints(): string;
+/**
+ * Interactive wizard that asks which AI agent the user wants to use,
+ * then shows specific instructions for opening this app in that agent.
+ */
+export declare function runAgentWizard(directory: string): Promise<void>;
+/**
+ * Returns full info panel (for 'i' key in dev mode) showing
+ * workspace, app, preview URL, and agent guidance.
+ */
+export declare function getInfoPanel(options: DevBannerOptions & {
+    directory: string;
+}): string;
+export declare function getWelcomeBanner(): string;