runwork 0.2.5 → 0.3.0

package/dist/git/auto-commit.d.ts

@@ -1,4 +1,8 @@
 import type { ApiClient } from '../api/client.js';
 export declare function isIgnored(filePath: string): boolean;
-export declare function watchAndAutoCommit(directory: string, client: ApiClient, appId: string): Promise<void>;
+export declare function watchAndAutoCommit(directory: string, client: ApiClient, appId: string, callbacks?: {
+    onFileChange?: (relPath: string, pendingCount: number) => void;
+    onFastSync?: (count: number) => void;
+    onGitPush?: (count: number) => void;
+}): Promise<void>;
 export declare function stopAutoCommit(): Promise<void>;

package/dist/git/auto-commit.js

@@ -2,11 +2,13 @@ import { execFileSync } from 'child_process';
 import { readFileSync } from 'fs';
 import { watch } from 'chokidar';
 import { basename, join, relative } from 'path';
+import { dim, cyan, yellow } from '../ui/colors.js';
 let watcher = null;
 let fastSyncTimer = null;
 let gitTimer = null;
 let gitPushing = false;
 let gitPendingAfterPush = false;
+let activeCallbacks;
 // Files awaiting fast sync: path -> 'changed' | 'deleted'
 const pendingFastSync = new Map();
 // Track files the user actually touched during this session (for git)
@@ -33,7 +35,8 @@ export function isIgnored(filePath) {
         return true;
     return false;
 }
-export async function watchAndAutoCommit(directory, client, appId) {
+export async function watchAndAutoCommit(directory, client, appId, callbacks) {
+    activeCallbacks = callbacks;
     watcher = watch(directory, {
         ignored: isIgnored,
         persistent: true,
@@ -46,19 +49,20 @@ export async function watchAndAutoCommit(directory, client, appId) {
     const onFileChange = (filePath) => {
         const rel = relative(directory, filePath);
         if (changedFiles.size === 0) {
-            console.log(`Changed: ${rel}`);
+            console.log(`  ${dim('Changed:')} ${cyan(rel)}`);
         }
         else {
-            console.log(`Changed: ${rel} (+${changedFiles.size} pending)`);
+            console.log(`  ${dim('Changed:')} ${cyan(rel)} ${dim(`(+${changedFiles.size} pending)`)}`);
         }
         changedFiles.add(rel);
         pendingFastSync.set(rel, 'changed');
+        activeCallbacks?.onFileChange?.(rel, changedFiles.size);
         scheduleFastSync(directory, client, appId);
         scheduleGitCommit();
     };
     const onFileUnlink = (filePath) => {
         const rel = relative(directory, filePath);
-        console.log(`Deleted: ${rel}`);
+        console.log(`  ${dim('Deleted:')} ${cyan(rel)}`);
         changedFiles.add(rel);
         pendingFastSync.set(rel, 'deleted');
         scheduleFastSync(directory, client, appId);
@@ -109,11 +113,12 @@ async function executeFastSync(directory, client, appId) {
     const total = files.length + deletedFiles.length;
     try {
         await client.syncFiles(appId, files, deletedFiles.length > 0 ? deletedFiles : undefined);
-        console.log(`  Synced ${total} file(s) to preview.`);
+        console.log(dim(`  Synced ${total} file(s) to preview.`));
+        activeCallbacks?.onFastSync?.(total);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        console.warn(`  Fast sync failed (git will handle it): ${message}`);
+        console.warn(yellow(`  Fast sync failed (git will handle it): ${message}`));
     }
 }
 // ========================================
@@ -178,7 +183,7 @@ function commitAndPush() {
                     execFileSync('git', ['merge', '--abort'], { stdio: 'pipe' });
                 }
                 catch { /* no merge in progress */ }
-                console.warn('Auto-sync: merge failed, skipping push. Run `git pull --rebase runwork main` manually.');
+                console.warn(yellow('Auto-sync: merge failed, skipping push. Run `git pull --rebase runwork main` manually.'));
                 return;
             }
         }
@@ -189,11 +194,12 @@ function commitAndPush() {
         catch {
             execFileSync('git', ['push', '-u', 'runwork', 'main'], { stdio: 'pipe' });
         }
-        console.log(`  Pushed ${stagedFiles.length} file(s) to git.`);
+        console.log(dim(`  Pushed ${stagedFiles.length} file(s) to git.`));
+        activeCallbacks?.onGitPush?.(stagedFiles.length);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        console.warn(`Auto-sync failed: ${message}`);
+        console.warn(yellow(`Auto-sync failed: ${message}`));
     }
     finally {
         gitPushing = false;

package/dist/git/sync.js

@@ -49,6 +49,31 @@ function removeConflictingUntrackedFiles(cwd) {
         // 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.
  *
@@ -65,13 +90,14 @@ export function syncWithRemote(cwd) {
         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 {
+        catch (rebaseErr) {
             try {
                 execFileSync('git', ['rebase', '--abort'], { cwd, stdio: 'pipe' });
             }
@@ -81,17 +107,32 @@ export function syncWithRemote(cwd) {
                 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 */ }
-                status = 'sync-failed';
+                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 {
-        // fetch failed — remote may be unreachable or have no commits
+    catch (fetchErr) {
         status = 'sync-failed';
+        syncError = extractGitError(fetchErr);
     }
     if (dirty) {
         try {
@@ -102,7 +143,7 @@ export function syncWithRemote(cwd) {
         }
     }
     if (status === 'sync-failed') {
-        return { status, pushed: false, error: 'Pull failed (remote may not have commits yet)' };
+        return { status, pushed: false, error: syncError };
     }
     let pushed = false;
     try {

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/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;