runwork 0.5.0 → 0.6.0

package/dist/ui/banner.d.ts

@@ -18,7 +18,7 @@ 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>;
+export declare function runAgentWizard(directory: string, configuredAgents?: string[]): Promise<void>;
 /**
  * Returns full info panel (for 'i' key in dev mode) showing
  * workspace, app, preview URL, and agent guidance.

package/dist/ui/banner.js

@@ -1,3 +1,4 @@
+import { basename } from 'path';
 import { bold, cyan, dim, green } from './colors.js';
 export const SUPPORTED_AGENTS = [
     { id: 'claude-code', name: 'Claude Code', command: 'cd {dir} && claude' },
@@ -48,7 +49,32 @@ export function getKeyboardHints() {
  * Interactive wizard that asks which AI agent the user wants to use,
  * then shows specific instructions for opening this app in that agent.
  */
-export async function runAgentWizard(directory) {
+export async function runAgentWizard(directory, configuredAgents) {
+    // Skip interactive wizard in non-TTY environments (CI, agents)
+    if (!process.stdout.isTTY) {
+        console.log(getAgentGuidance(directory));
+        return;
+    }
+    const slug = basename(directory) || directory;
+    // If we already know which agents are configured, skip the prompt
+    if (configuredAgents && configuredAgents.length > 0) {
+        const knownAgent = SUPPORTED_AGENTS.find(a => configuredAgents.includes(a.id));
+        if (knownAgent) {
+            const agentCmd = knownAgent.command.replace(/{dir}/g, slug);
+            console.log('');
+            console.log(bold('Get started:'));
+            console.log('');
+            console.log(`  ${dim('1.')} cd ${slug} && runwork dev`);
+            if (knownAgent.id === 'claude-desktop') {
+                console.log(`  ${dim('2.')} ${agentCmd}`);
+            }
+            else {
+                console.log(`  ${dim('2.')} ${cyan(agentCmd)}  ${dim('(in a second terminal)')}`);
+            }
+            console.log('');
+            return;
+        }
+    }
     const { select, isCancel } = await import('@clack/prompts');
     console.log('');
     const result = await select({
@@ -64,7 +90,6 @@ export async function runAgentWizard(directory) {
     const agent = SUPPORTED_AGENTS.find(a => a.id === result);
     if (!agent)
         return;
-    const slug = directory.split('/').pop() || directory;
     const agentCmd = agent.command.replace(/{dir}/g, slug);
     console.log('');
     console.log(bold('Get started:'));

package/dist/utils/__tests__/resolve.test.d.ts

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

package/dist/utils/__tests__/resolve.test.js

@@ -0,0 +1,95 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { resolveWorkspace, resolveApp } from '../resolve.js';
+const mockWorkspaces = [
+    { id: 'ws-1', name: 'Team Alpha' },
+    { id: 'ws-2', name: 'Team Beta' },
+];
+const mockApps = [
+    { id: 'app-1', name: 'My App', slug: 'my-app', workspaceId: 'ws-1', workspaceName: 'Team Alpha', gitRemoteUrl: '' },
+    { id: 'app-2', name: 'Other App', slug: 'other-app', workspaceId: 'ws-2', workspaceName: 'Team Beta', gitRemoteUrl: '' },
+];
+function createMockClient(workspaces, apps) {
+    return {
+        listWorkspaces: vi.fn().mockResolvedValue(workspaces),
+        listApps: vi.fn().mockResolvedValue(apps),
+    };
+}
+// Mock process.exit to throw instead of exiting
+const mockExit = vi.spyOn(process, 'exit').mockImplementation(((code) => {
+    throw new Error(`process.exit(${code})`);
+}));
+beforeEach(() => {
+    vi.clearAllMocks();
+    vi.spyOn(console, 'error').mockImplementation(() => { });
+});
+describe('resolveWorkspace', () => {
+    it('resolves by exact ID', async () => {
+        const client = createMockClient(mockWorkspaces, []);
+        const ws = await resolveWorkspace(client, 'ws-1');
+        expect(ws).toEqual(mockWorkspaces[0]);
+    });
+    it('resolves by name (case-insensitive)', async () => {
+        const client = createMockClient(mockWorkspaces, []);
+        const ws = await resolveWorkspace(client, 'team beta');
+        expect(ws).toEqual(mockWorkspaces[1]);
+    });
+    it('prefers ID match over name match', async () => {
+        const workspaces = [
+            { id: 'ws-1', name: 'ws-2' }, // name matches a different workspace's ID
+            { id: 'ws-2', name: 'Other' },
+        ];
+        const client = createMockClient(workspaces, []);
+        const ws = await resolveWorkspace(client, 'ws-2');
+        expect(ws.id).toBe('ws-2');
+    });
+    it('exits when no workspaces found', async () => {
+        const client = createMockClient([], []);
+        await expect(resolveWorkspace(client, 'any')).rejects.toThrow('process.exit(1)');
+        expect(console.error).toHaveBeenCalledWith(expect.stringContaining('No workspaces found'));
+    });
+    it('exits when workspace not found', async () => {
+        const client = createMockClient(mockWorkspaces, []);
+        await expect(resolveWorkspace(client, 'nonexistent')).rejects.toThrow('process.exit(1)');
+        expect(console.error).toHaveBeenCalledWith(expect.stringContaining('not found'));
+    });
+    it('exits on ambiguous name match', async () => {
+        const workspaces = [
+            { id: 'ws-1', name: 'Team' },
+            { id: 'ws-2', name: 'Team' },
+        ];
+        const client = createMockClient(workspaces, []);
+        await expect(resolveWorkspace(client, 'Team')).rejects.toThrow('process.exit(1)');
+        expect(console.error).toHaveBeenCalledWith(expect.stringContaining('Ambiguous'));
+    });
+});
+describe('resolveApp', () => {
+    it('resolves by exact ID', async () => {
+        const client = createMockClient([], mockApps);
+        const app = await resolveApp(client, 'app-1');
+        expect(app).toEqual(mockApps[0]);
+    });
+    it('resolves by name (case-insensitive)', async () => {
+        const client = createMockClient([], mockApps);
+        const app = await resolveApp(client, 'my app');
+        expect(app).toEqual(mockApps[0]);
+    });
+    it('exits when no apps found', async () => {
+        const client = createMockClient([], []);
+        await expect(resolveApp(client, 'any')).rejects.toThrow('process.exit(1)');
+        expect(console.error).toHaveBeenCalledWith(expect.stringContaining('No apps found'));
+    });
+    it('exits when app not found', async () => {
+        const client = createMockClient([], mockApps);
+        await expect(resolveApp(client, 'nonexistent')).rejects.toThrow('process.exit(1)');
+        expect(console.error).toHaveBeenCalledWith(expect.stringContaining('not found'));
+    });
+    it('exits on ambiguous name match', async () => {
+        const apps = [
+            { id: 'app-1', name: 'Dup', slug: 'dup-1', workspaceId: 'ws-1', workspaceName: 'WS', gitRemoteUrl: '' },
+            { id: 'app-2', name: 'Dup', slug: 'dup-2', workspaceId: 'ws-1', workspaceName: 'WS', gitRemoteUrl: '' },
+        ];
+        const client = createMockClient([], apps);
+        await expect(resolveApp(client, 'Dup')).rejects.toThrow('process.exit(1)');
+        expect(console.error).toHaveBeenCalledWith(expect.stringContaining('Ambiguous'));
+    });
+});

package/dist/utils/__tests__/sqlite.test.d.ts

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

package/dist/utils/__tests__/sqlite.test.js

@@ -0,0 +1,77 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import path from 'path';
+// Mock better-sqlite3 for controlled tests
+vi.mock('better-sqlite3', () => {
+    const MockDatabase = vi.fn();
+    return { default: MockDatabase };
+});
+import Database from 'better-sqlite3';
+import { querySqlite } from '../sqlite.js';
+const FIXTURE_DB = path.resolve(__dirname, '../../agents/__tests__/fixtures/codex/state.sqlite');
+beforeEach(() => {
+    vi.restoreAllMocks();
+});
+describe('querySqlite', () => {
+    // ── Tests using the real fixture database ──────────────────────────
+    describe('with real fixture database', () => {
+        beforeEach(() => {
+            // Restore the real better-sqlite3 implementation for fixture tests
+            vi.mocked(Database).mockImplementation((...args) => {
+                const RealDatabase = vi.importActual('better-sqlite3');
+                // importActual returns a promise, but we need synchronous access;
+                // however vi.importActual in the module-scope mock is async.
+                // Instead, re-require the real module.
+                // eslint-disable-next-line @typescript-eslint/no-require-imports
+                const Actual = require('better-sqlite3');
+                return new Actual(...args);
+            });
+        });
+        it('returns pipe-separated values for multi-column results', () => {
+            const result = querySqlite(FIXTURE_DB, "SELECT id, tokens_used FROM threads WHERE id = 'old-session'");
+            expect(result).toBe('old-session|50000');
+        });
+        it('returns newline-separated rows for multiple rows', () => {
+            const result = querySqlite(FIXTURE_DB, 'SELECT id, tokens_used FROM threads ORDER BY created_at');
+            const lines = result.split('\n');
+            expect(lines).toHaveLength(3);
+            expect(lines[0]).toContain('old-session');
+            expect(lines[1]).toContain('recent-session');
+            expect(lines[2]).toContain('newest-session');
+        });
+    });
+    // ── Tests using mocked database ────────────────────────────────────
+    describe('error handling', () => {
+        it('returns empty string when database does not exist', () => {
+            vi.mocked(Database).mockImplementation(() => {
+                throw new Error('SQLITE_CANTOPEN: unable to open database file');
+            });
+            const result = querySqlite('/nonexistent/path.db', 'SELECT 1');
+            expect(result).toBe('');
+        });
+        it('returns empty string when SQL is invalid', () => {
+            const mockPrepare = vi.fn().mockImplementation(() => {
+                throw new Error('SQLITE_ERROR: near "INVALID": syntax error');
+            });
+            const mockClose = vi.fn();
+            vi.mocked(Database).mockImplementation(() => ({ prepare: mockPrepare, close: mockClose }));
+            const result = querySqlite('/some/db.sqlite', 'INVALID SQL QUERY');
+            expect(result).toBe('');
+        });
+        it('returns empty string when database is corrupted', () => {
+            vi.mocked(Database).mockImplementation(() => {
+                throw new Error('SQLITE_CORRUPT: database disk image is malformed');
+            });
+            const result = querySqlite('/corrupted/db.sqlite', 'SELECT 1');
+            expect(result).toBe('');
+        });
+        it('closes database even on query error', () => {
+            const mockClose = vi.fn();
+            const mockPrepare = vi.fn().mockImplementation(() => {
+                throw new Error('query failed');
+            });
+            vi.mocked(Database).mockImplementation(() => ({ prepare: mockPrepare, close: mockClose }));
+            querySqlite('/some/db.sqlite', 'SELECT 1');
+            expect(mockClose).toHaveBeenCalledTimes(1);
+        });
+    });
+});

package/dist/utils/agent-guidance.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Centralized agent teaching content.
+ * All guidance strings and builder functions live here so when Runwork
+ * features change, one file updates.
+ */
+export interface AgentGuide {
+    context: string;
+    structure?: Record<string, string>;
+    nextSteps: string[];
+    tips?: string[];
+    learnMore?: string;
+}
+export interface AgentError {
+    message: string;
+    diagnosis: string;
+    suggestions: string[];
+}
+export interface AgentResponse<T> {
+    success: boolean;
+    command: string;
+    result: T;
+    guide?: AgentGuide;
+    error?: AgentError;
+}
+/** Map of key template files and what they're for. */
+export declare const APP_STRUCTURE: Record<string, string>;
+export declare function buildInitGuide(appName: string, dir: string): AgentGuide;
+export declare function buildCloneGuide(appName: string, dir: string): AgentGuide;
+export declare function buildDevSessionGuide(): AgentGuide;
+export declare function buildDeployGuide(): AgentGuide;
+export declare function buildInfoGuide(): AgentGuide;
+export declare function buildErrorResponse(command: string, message: string, diagnosis: string, suggestions: string[]): AgentResponse<null>;

package/dist/utils/agent-guidance.js

@@ -0,0 +1,106 @@
+/**
+ * Centralized agent teaching content.
+ * All guidance strings and builder functions live here so when Runwork
+ * features change, one file updates.
+ */
+/** Map of key template files and what they're for. */
+export const APP_STRUCTURE = {
+    'worker/entities.ts': 'Define persistent data models. Extend Entity<State> for storage with CRUD.',
+    'worker/schedules.ts': 'Add background cron jobs. Standard 5-field cron syntax.',
+    'worker/workflows.ts': 'Multi-step durable processes. Use ctx.step.do() for retryable steps.',
+    'worker/routes.ts': 'Internal API endpoints the frontend calls. CRUD operations, search, filters.',
+    'worker/endpoints.ts': 'Public APIs for external access. Webhooks, third-party integrations.',
+    'worker/agents.ts': 'AI agents -- conversational (chat UI) or task (headless automation).',
+    'worker/integration-requirements.ts': 'Declare third-party service dependencies (Slack, GitHub, etc.).',
+    'worker/components.ts': 'Reusable UI components other workspace apps can embed.',
+    'shared/types.ts': 'TypeScript interfaces shared between frontend and backend.',
+    'src/pages/': 'Frontend React pages. Each file becomes a route.',
+    'blueprint.json': 'App feature registry. Update after adding entities, workflows, agents, etc.',
+    'CLAUDE.md': 'Complete framework documentation. Read this before editing anything.',
+};
+const COMMON_TIPS = [
+    'Read CLAUDE.md in the app directory first -- it has complete framework documentation with code examples.',
+    'You do NOT need git commands. runwork dev handles file syncing automatically.',
+    'Do NOT install external AI SDKs (openai, @anthropic-ai/sdk). Use @runworkai/framework/ai instead.',
+    'Every workflow MUST have a trigger (API endpoint, scheduled job, or UI button). Workflows without triggers are dead code.',
+    'Every conversational agent MUST have a frontend page to access it.',
+    'After adding entities, workflows, or agents, update blueprint.json with the new metadata.',
+    'Never guess integration IDs. Run: runwork integrations search <query>',
+];
+export function buildInitGuide(appName, dir) {
+    return {
+        context: 'Created a Runwork app -- a full-stack Cloudflare Workers application with built-in support for persistent data (entities), background jobs (schedules), multi-step durable processes (workflows), AI agents, public APIs, and third-party integrations. The app runs in a sandbox during development and deploys to Cloudflare Workers for production.',
+        structure: APP_STRUCTURE,
+        nextSteps: [
+            `cd ${dir}`,
+            'runwork dev  # start development server -- watches for file changes and syncs automatically',
+            'Edit files for your needs (see structure above)',
+            'runwork deploy  # deploy to production when ready',
+        ],
+        tips: COMMON_TIPS,
+        learnMore: 'Read CLAUDE.md in the app directory for complete framework documentation with code examples.',
+    };
+}
+export function buildCloneGuide(appName, dir) {
+    return {
+        context: 'Cloned an existing Runwork app. This app may already have entities, workflows, agents, and other features configured. Check the existing files before making changes.',
+        structure: APP_STRUCTURE,
+        nextSteps: [
+            `cd ${dir}`,
+            'runwork dev  # start development server',
+            'Review existing files to understand what is already built',
+            'Edit files for your needs',
+            'runwork deploy  # deploy to production when ready',
+        ],
+        tips: COMMON_TIPS,
+        learnMore: 'Read CLAUDE.md in the app directory for complete framework documentation.',
+    };
+}
+export function buildDevSessionGuide() {
+    return {
+        context: 'Development server is running. Files are watched and synced to a sandbox automatically. Edit your code and changes will appear at the preview URL.',
+        nextSteps: [
+            'Edit files in the app directory -- changes sync automatically',
+            'Open the preview URL to see your app',
+            'Run runwork deploy in another terminal when ready for production',
+        ],
+        tips: [
+            'You do NOT need git commands. The dev server handles all file syncing.',
+            'If the preview seems stuck, try runwork dev again to restart the session.',
+        ],
+    };
+}
+export function buildDeployGuide() {
+    return {
+        context: 'App deployed to production on Cloudflare Workers. The production URL is live and serving traffic. Registered resources (entities, schedules, workflows, agents) are active.',
+        nextSteps: [
+            'Verify the app at the production URL',
+            'Run runwork info to see all registered resources and their status',
+            'Share the production URL with users or integrate it into other systems',
+        ],
+    };
+}
+export function buildInfoGuide() {
+    return {
+        context: 'This shows the current state of the app: what is deployed, what integrations are connected, and what resources (entities, workflows, agents, etc.) are registered.',
+        nextSteps: [
+            'runwork dev  # start development server if not already running',
+            'runwork deploy  # deploy to production when ready',
+        ],
+        tips: [
+            'Entities listed here are the data models available via Entity CRUD methods.',
+            'Workflows listed here can be triggered via their registered endpoints or schedules.',
+            'Agents listed here need frontend pages (conversational) or triggers (task) to be accessible.',
+            'Integrations with connected status are ready to use. Others need setup in workspace settings.',
+            'If preview is not active, run runwork dev to start a development session.',
+        ],
+    };
+}
+export function buildErrorResponse(command, message, diagnosis, suggestions) {
+    return {
+        success: false,
+        command,
+        result: null,
+        error: { message, diagnosis, suggestions },
+    };
+}

package/dist/utils/fs.js

@@ -1,5 +1,5 @@
 import { readdirSync, rmSync } from 'fs';
-import { join, relative } from 'path';
+import { join, relative, sep } from 'path';
 /**
  * Remove .git directories nested at depth >= 2 under the given root.
  * Replaces `find <dir> -mindepth 2 -name .git -type d`.
@@ -14,7 +14,7 @@ export function removeNestedGitDirs(rootDir) {
             : entry.path;
         const fullPath = join(parentPath, entry.name);
         const rel = relative(rootDir, fullPath);
-        const depth = rel.split('/').length;
+        const depth = rel.split(sep).length;
         // Only remove .git dirs at depth >= 2 (not the root .git)
         if (depth >= 2) {
             rmSync(fullPath, { recursive: true, force: true });

package/dist/utils/help-json.d.ts

@@ -0,0 +1,56 @@
+/**
+ * JSON help output for AI agents.
+ *
+ * When --json is active (explicitly or via non-TTY), `runwork --help` and
+ * `runwork <command> --help` output a machine-readable command tree instead
+ * of Commander's human-readable text.
+ *
+ * This lets an agent discover the full CLI surface in a single call.
+ */
+import type { Command } from 'commander';
+interface JsonOption {
+    flags: string;
+    description: string;
+    required: boolean;
+    optional: boolean;
+    variadic: boolean;
+    defaultValue?: unknown;
+    choices?: string[];
+    envVar?: string;
+}
+interface JsonArgument {
+    name: string;
+    description: string;
+    required: boolean;
+    variadic: boolean;
+    defaultValue?: unknown;
+    choices?: string[];
+}
+interface JsonCommand {
+    name: string;
+    description: string;
+    aliases: string[];
+    usage: string;
+    options: JsonOption[];
+    arguments: JsonArgument[];
+    subcommands: JsonCommand[];
+}
+interface JsonHelpOutput {
+    version: string;
+    name: string;
+    description: string;
+    usage: string;
+    globalOptions: JsonOption[];
+    commands: JsonCommand[];
+}
+/**
+ * Serialize the full command tree to a JSON-friendly structure.
+ */
+export declare function buildHelpJson(program: Command): JsonHelpOutput;
+/**
+ * Serialize a single command (for `runwork <cmd> --help --json`).
+ */
+export declare function buildCommandHelpJson(cmd: Command, version: string): JsonCommand & {
+    version: string;
+};
+export {};

package/dist/utils/help-json.js

@@ -0,0 +1,85 @@
+/**
+ * JSON help output for AI agents.
+ *
+ * When --json is active (explicitly or via non-TTY), `runwork --help` and
+ * `runwork <command> --help` output a machine-readable command tree instead
+ * of Commander's human-readable text.
+ *
+ * This lets an agent discover the full CLI surface in a single call.
+ */
+function serializeOption(opt) {
+    const result = {
+        flags: opt.flags,
+        description: opt.description,
+        required: opt.required,
+        optional: opt.optional,
+        variadic: opt.variadic,
+    };
+    if (opt.defaultValue !== undefined)
+        result.defaultValue = opt.defaultValue;
+    if (opt.argChoices)
+        result.choices = opt.argChoices;
+    if (opt.envVar)
+        result.envVar = opt.envVar;
+    return result;
+}
+function serializeArgument(arg) {
+    const result = {
+        name: arg.name(),
+        description: arg.description,
+        required: arg.required,
+        variadic: arg.variadic,
+    };
+    if (arg.defaultValue !== undefined)
+        result.defaultValue = arg.defaultValue;
+    if (arg.argChoices)
+        result.choices = arg.argChoices;
+    return result;
+}
+function serializeCommand(cmd) {
+    const subcommands = cmd.commands
+        .filter((c) => !c._hidden)
+        .map(serializeCommand);
+    // Get command-level options (exclude inherited global options)
+    const options = cmd.options
+        .filter((o) => !o.hidden)
+        .map(serializeOption);
+    const registeredArguments = cmd.registeredArguments ?? [];
+    return {
+        name: cmd.name(),
+        description: cmd.description(),
+        aliases: cmd.aliases(),
+        usage: cmd.usage(),
+        options,
+        arguments: registeredArguments.map(serializeArgument),
+        subcommands,
+    };
+}
+/**
+ * Serialize the full command tree to a JSON-friendly structure.
+ */
+export function buildHelpJson(program) {
+    const globalOptions = program.options
+        .filter((o) => !o.hidden)
+        .map(serializeOption);
+    const commands = program.commands
+        .filter((c) => !c._hidden)
+        .map(serializeCommand);
+    return {
+        version: program.version() ?? 'unknown',
+        name: program.name(),
+        description: program.description(),
+        usage: program.usage(),
+        globalOptions,
+        commands,
+    };
+}
+/**
+ * Serialize a single command (for `runwork <cmd> --help --json`).
+ */
+export function buildCommandHelpJson(cmd, version) {
+    return {
+        version,
+        ...serializeCommand(cmd),
+    };
+}

package/dist/utils/resolve.d.ts

@@ -0,0 +1,12 @@
+import type { ApiClient } from '../api/client.js';
+import type { AppInfo, WorkspaceInfo } from '../types.js';
+/**
+ * Resolve a workspace by name or ID from the user's accessible workspaces.
+ * Tries exact ID match first, then case-insensitive name match.
+ */
+export declare function resolveWorkspace(client: ApiClient, nameOrId: string): Promise<WorkspaceInfo>;
+/**
+ * Resolve an app by name or ID from the user's accessible apps.
+ * Tries exact ID match first, then case-insensitive name match.
+ */
+export declare function resolveApp(client: ApiClient, nameOrId: string): Promise<AppInfo>;

package/dist/utils/resolve.js

@@ -0,0 +1,52 @@
+/**
+ * Resolve a workspace by name or ID from the user's accessible workspaces.
+ * Tries exact ID match first, then case-insensitive name match.
+ */
+export async function resolveWorkspace(client, nameOrId) {
+    const workspaces = await client.listWorkspaces();
+    if (workspaces.length === 0) {
+        console.error('No workspaces found. Create one at runwork.ai first.');
+        process.exit(1);
+    }
+    // Exact ID match
+    const byId = workspaces.find(w => w.id === nameOrId);
+    if (byId)
+        return byId;
+    // Case-insensitive name match
+    const lower = nameOrId.toLowerCase();
+    const byName = workspaces.filter(w => w.name.toLowerCase() === lower);
+    if (byName.length === 1)
+        return byName[0];
+    if (byName.length > 1) {
+        console.error(`Ambiguous workspace name "${nameOrId}". Matches: ${byName.map(w => `${w.name} (${w.id})`).join(', ')}`);
+        process.exit(1);
+    }
+    console.error(`Workspace "${nameOrId}" not found. Available: ${workspaces.map(w => w.name).join(', ')}`);
+    process.exit(1);
+}
+/**
+ * Resolve an app by name or ID from the user's accessible apps.
+ * Tries exact ID match first, then case-insensitive name match.
+ */
+export async function resolveApp(client, nameOrId) {
+    const apps = await client.listApps();
+    if (apps.length === 0) {
+        console.error('No apps found.');
+        process.exit(1);
+    }
+    // Exact ID match
+    const byId = apps.find(a => a.id === nameOrId);
+    if (byId)
+        return byId;
+    // Case-insensitive name match
+    const lower = nameOrId.toLowerCase();
+    const byName = apps.filter(a => a.name.toLowerCase() === lower);
+    if (byName.length === 1)
+        return byName[0];
+    if (byName.length > 1) {
+        console.error(`Ambiguous app name "${nameOrId}". Matches: ${byName.map(a => `${a.name} (${a.id})`).join(', ')}`);
+        process.exit(1);
+    }
+    console.error(`App "${nameOrId}" not found. Available: ${apps.map(a => a.name).join(', ')}`);
+    process.exit(1);
+}

package/dist/utils/setup-state.d.ts

@@ -0,0 +1,3 @@
+import type { SetupState } from '../types.js';
+/** Load setup state, checking project-level then user-level. */
+export declare function loadSetupState(): SetupState | null;

package/dist/utils/setup-state.js

@@ -0,0 +1,19 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+/** Load setup state, checking project-level then user-level. */
+export function loadSetupState() {
+    const projectPath = join(process.cwd(), '.runwork', 'setup.json');
+    const userPath = join(homedir(), '.runwork', 'setup.json');
+    for (const p of [projectPath, userPath]) {
+        if (existsSync(p)) {
+            try {
+                return JSON.parse(readFileSync(p, 'utf-8'));
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return null;
+}

package/dist/utils/sqlite.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Query a SQLite database using better-sqlite3.
+ * Cross-platform, no CLI dependency.
+ * Opens database in readonly mode with a 5-second busy timeout.
+ * Returns empty string on any error (missing DB, locked, corrupted).
+ */
+export declare function querySqlite(dbPath: string, sql: string): string;

package/dist/utils/sqlite.js

@@ -0,0 +1,24 @@
+import Database from 'better-sqlite3';
+/**
+ * Query a SQLite database using better-sqlite3.
+ * Cross-platform, no CLI dependency.
+ * Opens database in readonly mode with a 5-second busy timeout.
+ * Returns empty string on any error (missing DB, locked, corrupted).
+ */
+export function querySqlite(dbPath, sql) {
+    let db = null;
+    try {
+        db = new Database(dbPath, { readonly: true, timeout: 5000 });
+        const rows = db.prepare(sql).all();
+        return rows.map(row => Object.values(row).join('|')).join('\n');
+    }
+    catch {
+        return '';
+    }
+    finally {
+        try {
+            db?.close();
+        }
+        catch { /* ignore close errors */ }
+    }
+}

package/dist/utils/which.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Cross-platform binary detection.
+ * Uses `which` on macOS/Linux, `where.exe` on Windows.
+ * Returns the resolved path on success, null if not found.
+ */
+export declare function whichBinary(name: string): string | null;