patchrelay 0.1.0 → 0.3.0

package/dist/cli/index.js

@@ -1,59 +1,14 @@
-import { spawn } from "node:child_process";
-import { setTimeout as delay } from "node:timers/promises";
 import { loadConfig } from "../config.js";
-import { initializePatchRelayHome, installUserServiceUnits, upsertProjectInConfig } from "../install.js";
 import { runPreflight } from "../preflight.js";
-import { getDefaultConfigPath, getDefaultRuntimeEnvPath, getDefaultServiceEnvPath, getSystemdUserPathUnitPath, getSystemdUserReloadUnitPath, getSystemdUserUnitPath, } from "../runtime-paths.js";
+import { parseArgs, resolveCommand } from "./args.js";
+import { handleConnectCommand, handleInstallationsCommand } from "./commands/connect.js";
+import { handleEventsCommand, handleInspectCommand, handleListCommand, handleLiveCommand, handleOpenCommand, handleReportCommand, handleRetryCommand, handleWorktreeCommand, } from "./commands/issues.js";
+import { handleProjectCommand } from "./commands/project.js";
+import { handleInitCommand, handleInstallServiceCommand, handleRestartServiceCommand } from "./commands/setup.js";
 import { CliDataAccess } from "./data.js";
 import { formatJson } from "./formatters/json.js";
-import { formatEvents, formatInspect, formatList, formatLive, formatOpen, formatReport, formatRetry, formatWorktree } from "./formatters/text.js";
-const KNOWN_COMMANDS = new Set([
-    "serve",
-    "inspect",
-    "live",
-    "report",
-    "events",
-    "worktree",
-    "open",
-    "retry",
-    "list",
-    "doctor",
-    "init",
-    "project",
-    "connect",
-    "installations",
-    "install-service",
-    "restart-service",
-    "help",
-]);
-function parseArgs(argv) {
-    const positionals = [];
-    const flags = new Map();
-    for (let index = 0; index < argv.length; index += 1) {
-        const value = argv[index];
-        if (!value.startsWith("--")) {
-            positionals.push(value);
-            continue;
-        }
-        const trimmed = value.slice(2);
-        const [name, inline] = trimmed.split("=", 2);
-        if (!name) {
-            continue;
-        }
-        if (inline !== undefined) {
-            flags.set(name, inline);
-            continue;
-        }
-        const next = argv[index + 1];
-        if (next && !next.startsWith("--")) {
-            flags.set(name, next);
-            index += 1;
-            continue;
-        }
-        flags.set(name, true);
-    }
-    return { positionals, flags };
-}
+import { runInteractiveCommand } from "./interactive.js";
+import { formatDoctor, writeOutput } from "./output.js";
 function helpText() {
     return [
         "PatchRelay",
@@ -107,167 +62,6 @@ function helpText() {
         "                                                           List tracked issues",
     ].join("\n");
 }
-function normalizePublicBaseUrl(value) {
-    const candidate = /^[a-zA-Z][a-zA-Z\d+.-]*:\/\//.test(value) ? value : `https://${value}`;
-    const url = new URL(candidate);
-    return url.origin;
-}
-function getStageFlag(value) {
-    if (typeof value !== "string") {
-        return undefined;
-    }
-    const trimmed = value.trim();
-    return trimmed || undefined;
-}
-function parseCsvFlag(value) {
-    if (typeof value !== "string") {
-        return [];
-    }
-    return value
-        .split(",")
-        .map((entry) => entry.trim())
-        .filter(Boolean);
-}
-function writeOutput(stream, text) {
-    stream.write(text);
-}
-function formatDoctor(report) {
-    const lines = ["PatchRelay doctor", ""];
-    for (const check of report.checks) {
-        const marker = check.status === "pass" ? "PASS" : check.status === "warn" ? "WARN" : "FAIL";
-        lines.push(`${marker} [${check.scope}] ${check.message}`);
-    }
-    lines.push("");
-    lines.push(report.ok ? "Doctor result: ready" : "Doctor result: not ready");
-    return `${lines.join("\n")}\n`;
-}
-function buildOpenCommand(config, worktreePath, resumeThreadId) {
-    const args = ["--dangerously-bypass-approvals-and-sandbox"];
-    if (resumeThreadId) {
-        args.push("resume", "-C", worktreePath, resumeThreadId);
-    }
-    else {
-        args.push("-C", worktreePath);
-    }
-    return {
-        command: config.runner.codex.bin,
-        args,
-    };
-}
-async function runInteractiveCommand(command, args) {
-    return await new Promise((resolve, reject) => {
-        const child = spawn(command, args, {
-            stdio: "inherit",
-        });
-        child.on("error", reject);
-        child.on("exit", (code, signal) => {
-            if (signal) {
-                resolve(1);
-                return;
-            }
-            resolve(code ?? 0);
-        });
-    });
-}
-async function openExternalUrl(url) {
-    const candidates = process.platform === "darwin"
-        ? [{ command: "open", args: [url] }]
-        : process.platform === "win32"
-            ? [{ command: "cmd", args: ["/c", "start", "", url] }]
-            : [{ command: "xdg-open", args: [url] }];
-    for (const candidate of candidates) {
-        try {
-            const exitCode = await runInteractiveCommand(candidate.command, candidate.args);
-            if (exitCode === 0) {
-                return true;
-            }
-        }
-        catch {
-            // Try the next opener.
-        }
-    }
-    return false;
-}
-async function runServiceCommands(runner, commands) {
-    for (const entry of commands) {
-        const exitCode = await runner(entry.command, entry.args);
-        if (exitCode !== 0) {
-            throw new Error(`Command failed with exit code ${exitCode}: ${entry.command} ${entry.args.join(" ")}`);
-        }
-    }
-}
-function parseTimeoutSeconds(value, command) {
-    const timeoutSeconds = typeof value === "string" ? Number(value) : 180;
-    if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0) {
-        throw new Error(`${command} --timeout must be a positive number of seconds.`);
-    }
-    return timeoutSeconds;
-}
-async function runConnectFlow(params) {
-    const result = await params.data.connect(params.projectId);
-    if (params.json) {
-        writeOutput(params.stdout, formatJson(result));
-        return 0;
-    }
-    if ("completed" in result && result.completed) {
-        const label = result.installation.workspaceName ?? result.installation.actorName ?? `installation #${result.installation.id}`;
-        writeOutput(params.stdout, `Linked project ${result.projectId} to existing Linear installation ${result.installation.id} (${label}). No new OAuth approval was needed.\n`);
-        return 0;
-    }
-    if ("completed" in result) {
-        throw new Error("Unexpected completed connect result.");
-    }
-    const opener = params.openExternal ?? openExternalUrl;
-    const opened = params.noOpen ? false : await opener(result.authorizeUrl);
-    writeOutput(params.stdout, `${result.projectId ? `Project: ${result.projectId}\n` : ""}${opened ? "Opened browser for Linear OAuth.\n" : "Open this URL in a browser:\n"}${opened ? result.authorizeUrl : `${result.authorizeUrl}\n`}Waiting for OAuth approval...\n`);
-    const deadline = Date.now() + (params.timeoutSeconds ?? 180) * 1000;
-    const pollIntervalMs = params.connectPollIntervalMs ?? 1000;
-    do {
-        const status = await params.data.connectStatus(result.state);
-        if (status.status === "completed") {
-            const label = status.installation?.workspaceName ?? status.installation?.actorName ?? `installation #${status.installation?.id ?? "unknown"}`;
-            writeOutput(params.stdout, [
-                `Connected ${label}${status.projectId ? ` for project ${status.projectId}` : ""}.${status.installation?.id ? ` Installation ${status.installation.id}.` : ""}`,
-                params.config.linear.oauth.actor === "app"
-                    ? "If your Linear OAuth app webhook settings are configured, Linear has now provisioned the workspace webhook automatically."
-                    : undefined,
-            ]
-                .filter(Boolean)
-                .join("\n") + "\n");
-            return 0;
-        }
-        if (status.status === "failed") {
-            throw new Error(status.errorMessage ?? "Linear OAuth failed.");
-        }
-        if (Date.now() >= deadline) {
-            throw new Error(`Timed out waiting for Linear OAuth after ${params.timeoutSeconds ?? 180} seconds.`);
-        }
-        await delay(pollIntervalMs);
-    } while (true);
-}
-async function tryManageService(runner, commands) {
-    try {
-        await runServiceCommands(runner, commands);
-        return { ok: true };
-    }
-    catch (error) {
-        return { ok: false, error: error instanceof Error ? error.message : String(error) };
-    }
-}
-function installServiceCommands() {
-    return [
-        { command: "systemctl", args: ["--user", "daemon-reload"] },
-        { command: "systemctl", args: ["--user", "enable", "--now", "patchrelay.path"] },
-        { command: "systemctl", args: ["--user", "enable", "patchrelay.service"] },
-        { command: "systemctl", args: ["--user", "reload-or-restart", "patchrelay.service"] },
-    ];
-}
-function restartServiceCommands() {
-    return [
-        { command: "systemctl", args: ["--user", "daemon-reload"] },
-        { command: "systemctl", args: ["--user", "reload-or-restart", "patchrelay.service"] },
-    ];
-}
 function getCommandConfigProfile(command) {
     switch (command) {
         case "doctor":
@@ -293,13 +87,7 @@ export async function runCli(argv, options) {
     const stdout = options?.stdout ?? process.stdout;
     const stderr = options?.stderr ?? process.stderr;
     const parsed = parseArgs(argv);
-    const requestedCommand = parsed.positionals[0];
-    const command = !requestedCommand
-        ? "help"
-        : KNOWN_COMMANDS.has(requestedCommand)
-            ? requestedCommand
-            : "inspect";
-    const commandArgs = command === requestedCommand ? parsed.positionals.slice(1) : parsed.positionals;
+    const { command, commandArgs } = resolveCommand(parsed);
     if (command === "help") {
         writeOutput(stdout, `${helpText()}\n`);
         return 0;
@@ -310,265 +98,45 @@ export async function runCli(argv, options) {
     const runInteractive = options?.runInteractive ?? runInteractiveCommand;
     const json = parsed.flags.get("json") === true;
     if (command === "init") {
-        try {
-            const requestedPublicBaseUrl = typeof parsed.flags.get("public-base-url") === "string"
-                ? String(parsed.flags.get("public-base-url"))
-                : commandArgs[0];
-            if (!requestedPublicBaseUrl) {
-                throw new Error([
-                    "patchrelay init requires <public-base-url>.",
-                    "PatchRelay must know the public HTTPS origin that Linear will call for the webhook and OAuth callback.",
-                    "Example: patchrelay init https://patchrelay.example.com",
-                ].join("\n"));
-            }
-            const publicBaseUrl = normalizePublicBaseUrl(requestedPublicBaseUrl);
-            const result = await initializePatchRelayHome({
-                force: parsed.flags.get("force") === true,
-                publicBaseUrl,
-            });
-            const serviceUnits = await installUserServiceUnits({ force: parsed.flags.get("force") === true });
-            const serviceState = await tryManageService(runInteractive, installServiceCommands());
-            writeOutput(stdout, json
-                ? formatJson({ ...result, serviceUnits, serviceState })
-                : [
-                    `Config directory: ${result.configDir}`,
-                    `Runtime env: ${result.runtimeEnvPath} (${result.runtimeEnvStatus})`,
-                    `Service env: ${result.serviceEnvPath} (${result.serviceEnvStatus})`,
-                    `Config file: ${result.configPath} (${result.configStatus})`,
-                    `State directory: ${result.stateDir}`,
-                    `Data directory: ${result.dataDir}`,
-                    `Service unit: ${serviceUnits.unitPath} (${serviceUnits.serviceStatus})`,
-                    `Reload unit: ${serviceUnits.reloadUnitPath} (${serviceUnits.reloadStatus})`,
-                    `Watcher unit: ${serviceUnits.pathUnitPath} (${serviceUnits.pathStatus})`,
-                    "",
-                    "PatchRelay public URLs:",
-                    `- Public base URL: ${result.publicBaseUrl}`,
-                    `- Webhook URL: ${result.webhookUrl}`,
-                    `- OAuth callback: ${result.oauthCallbackUrl}`,
-                    "",
-                    "Created with defaults:",
-                    `- Config file contains only machine-level essentials such as server.public_base_url`,
-                    `- Database, logs, bind address, and worktree roots use built-in defaults`,
-                    `- The user service and config watcher are installed for you`,
-                    "",
-                    "Register the app in Linear:",
-                    "- Open Linear Settings > API > Applications",
-                    "- Create an OAuth app for PatchRelay",
-                    "- Choose actor `app`",
-                    "- Choose scopes `read`, `write`, `app:assignable`, `app:mentionable`",
-                    `- Add redirect URI ${result.oauthCallbackUrl}`,
-                    `- Add webhook URL ${result.webhookUrl}`,
-                    "- Enable webhook categories for issue events, comment events, agent session events, permission changes, and inbox/app-user notifications",
-                    "",
-                    result.configStatus === "skipped"
-                        ? `Config file was skipped, so make sure ${result.configPath} still has server.public_base_url: ${result.publicBaseUrl}`
-                        : `Config file already includes server.public_base_url: ${result.publicBaseUrl}`,
-                    "",
-                    "Service status:",
-                    serviceState.ok
-                        ? "PatchRelay service and config watcher are installed and reload-or-restart has been requested."
-                        : `PatchRelay service units were installed, but the service could not be started yet: ${serviceState.error}`,
-                    !serviceState.ok
-                        ? "This is expected until the required env vars and at least one valid project workflow are in place. The watcher will retry when config or env files change."
-                        : undefined,
-                    "",
-                    "Next steps:",
-                    `1. Edit ${result.serviceEnvPath}`,
-                    "2. Paste your Linear OAuth client id and client secret into service.env and keep the generated webhook secret and token encryption key",
-                    "3. Paste LINEAR_WEBHOOK_SECRET from service.env into the Linear OAuth app webhook signing secret",
-                    "4. Run `patchrelay project apply <id> <repo-path>`",
-                    "5. Edit the generated project workflows if you want custom state names or workflow files, then add those workflow files to the repo",
-                    "6. Run `patchrelay doctor`",
-                ]
-                    .filter(Boolean)
-                    .join("\n") + "\n");
-            return 0;
-        }
-        catch (error) {
-            writeOutput(stderr, `${error instanceof Error ? error.message : String(error)}\n`);
-            return 1;
-        }
+        return await handleInitCommand({
+            commandArgs,
+            parsed,
+            json,
+            stdout,
+            stderr,
+            runInteractive,
+        });
     }
     if (command === "install-service") {
-        try {
-            const result = await installUserServiceUnits({ force: parsed.flags.get("force") === true });
-            const writeOnly = parsed.flags.get("write-only") === true;
-            if (!writeOnly) {
-                await runServiceCommands(runInteractive, installServiceCommands());
-            }
-            writeOutput(stdout, json
-                ? formatJson({ ...result, writeOnly })
-                : [
-                    `Service unit: ${result.unitPath} (${result.serviceStatus})`,
-                    `Reload unit: ${result.reloadUnitPath} (${result.reloadStatus})`,
-                    `Watcher unit: ${result.pathUnitPath} (${result.pathStatus})`,
-                    `Runtime env: ${result.runtimeEnvPath}`,
-                    `Service env: ${result.serviceEnvPath}`,
-                    `Config file: ${result.configPath}`,
-                    writeOnly
-                        ? "Service units written. Start them with: systemctl --user daemon-reload && systemctl --user enable --now patchrelay.path && systemctl --user enable patchrelay.service && systemctl --user reload-or-restart patchrelay.service"
-                        : "PatchRelay user service and config watcher are installed and running.",
-                    "After package updates, run: patchrelay restart-service",
-                ].join("\n") + "\n");
-            return 0;
-        }
-        catch (error) {
-            writeOutput(stderr, `${error instanceof Error ? error.message : String(error)}\n`);
-            return 1;
-        }
+        return await handleInstallServiceCommand({
+            commandArgs,
+            parsed,
+            json,
+            stdout,
+            stderr,
+            runInteractive,
+        });
     }
     if (command === "restart-service") {
-        try {
-            await runServiceCommands(runInteractive, restartServiceCommands());
-            writeOutput(stdout, json
-                ? formatJson({
-                    service: "patchrelay",
-                    unitPath: getSystemdUserUnitPath(),
-                    reloadUnitPath: getSystemdUserReloadUnitPath(),
-                    pathUnitPath: getSystemdUserPathUnitPath(),
-                    runtimeEnvPath: getDefaultRuntimeEnvPath(),
-                    serviceEnvPath: getDefaultServiceEnvPath(),
-                    configPath: getDefaultConfigPath(),
-                    restarted: true,
-                })
-                : "Reloaded systemd user units and reload-or-restart was requested for PatchRelay.\n");
-            return 0;
-        }
-        catch (error) {
-            writeOutput(stderr, `${error instanceof Error ? error.message : String(error)}\n`);
-            return 1;
-        }
+        return await handleRestartServiceCommand({
+            commandArgs,
+            parsed,
+            json,
+            stdout,
+            stderr,
+            runInteractive,
+        });
     }
     if (command === "project") {
-        try {
-            const subcommand = commandArgs[0];
-            if (subcommand !== "apply") {
-                throw new Error("Usage: patchrelay project apply <id> <repo-path> [--issue-prefix <prefixes>] [--team-id <ids>] [--no-connect] [--timeout <seconds>]");
-            }
-            const projectId = commandArgs[1];
-            const repoPath = commandArgs[2];
-            if (!projectId || !repoPath) {
-                throw new Error("Usage: patchrelay project apply <id> <repo-path> [--issue-prefix <prefixes>] [--team-id <ids>] [--no-connect] [--timeout <seconds>]");
-            }
-            const result = await upsertProjectInConfig({
-                id: projectId,
-                repoPath,
-                issueKeyPrefixes: parseCsvFlag(parsed.flags.get("issue-prefix")),
-                linearTeamIds: parseCsvFlag(parsed.flags.get("team-id")),
-            });
-            const serviceUnits = await installUserServiceUnits();
-            const noConnect = parsed.flags.get("no-connect") === true;
-            const lines = [
-                `Config file: ${result.configPath}`,
-                `${result.status === "created" ? "Created" : result.status === "updated" ? "Updated" : "Verified"} project ${result.project.id} for ${result.project.repoPath}`,
-                result.project.issueKeyPrefixes.length > 0 ? `Issue key prefixes: ${result.project.issueKeyPrefixes.join(", ")}` : undefined,
-                result.project.linearTeamIds.length > 0 ? `Linear team ids: ${result.project.linearTeamIds.join(", ")}` : undefined,
-                `Service unit: ${serviceUnits.unitPath} (${serviceUnits.serviceStatus})`,
-                `Watcher unit: ${serviceUnits.pathUnitPath} (${serviceUnits.pathStatus})`,
-            ].filter(Boolean);
-            let fullConfig;
-            try {
-                fullConfig = loadConfig(undefined, { profile: "doctor" });
-            }
-            catch (error) {
-                if (json) {
-                    writeOutput(stdout, formatJson({
-                        ...result,
-                        serviceUnits,
-                        readiness: {
-                            ok: false,
-                            error: error instanceof Error ? error.message : String(error),
-                        },
-                        connect: {
-                            attempted: false,
-                            skipped: "missing_env",
-                        },
-                    }));
-                    return 0;
-                }
-                lines.push(`Linear connect was skipped: ${error instanceof Error ? error.message : String(error)}`);
-                lines.push("Finish the required env vars and rerun `patchrelay project apply`.");
-                writeOutput(stdout, `${lines.join("\n")}\n`);
-                return 0;
-            }
-            const report = await runPreflight(fullConfig);
-            const failedChecks = report.checks.filter((check) => check.status === "fail");
-            if (failedChecks.length > 0) {
-                if (json) {
-                    writeOutput(stdout, formatJson({
-                        ...result,
-                        serviceUnits,
-                        readiness: report,
-                        connect: {
-                            attempted: false,
-                            skipped: "preflight_failed",
-                        },
-                    }));
-                    return 0;
-                }
-                lines.push("Linear connect was skipped because PatchRelay is not ready yet:");
-                lines.push(...failedChecks.map((check) => `- [${check.scope}] ${check.message}`));
-                lines.push("Fix the failures above and rerun `patchrelay project apply`.");
-                writeOutput(stdout, `${lines.join("\n")}\n`);
-                return 0;
-            }
-            const serviceState = await tryManageService(runInteractive, installServiceCommands());
-            if (!serviceState.ok) {
-                throw new Error(`Project was saved, but PatchRelay could not be reloaded: ${serviceState.error}`);
-            }
-            const cliData = options?.data ?? new CliDataAccess(fullConfig);
-            try {
-                if (json) {
-                    const connectResult = noConnect ? undefined : await cliData.connect(projectId);
-                    writeOutput(stdout, formatJson({
-                        ...result,
-                        serviceUnits,
-                        readiness: report,
-                        serviceReloaded: true,
-                        ...(noConnect
-                            ? {
-                                connect: {
-                                    attempted: false,
-                                    skipped: "no_connect",
-                                },
-                            }
-                            : {
-                                connect: {
-                                    attempted: true,
-                                    result: connectResult,
-                                },
-                            }),
-                    }));
-                    return 0;
-                }
-                if (noConnect) {
-                    lines.push("Project saved and PatchRelay was reloaded.");
-                    lines.push(`Next: patchrelay connect --project ${result.project.id}`);
-                    writeOutput(stdout, `${lines.join("\n")}\n`);
-                    return 0;
-                }
-                writeOutput(stdout, `${lines.join("\n")}\n`);
-                return await runConnectFlow({
-                    config: fullConfig,
-                    data: cliData,
-                    stdout,
-                    noOpen: parsed.flags.get("no-open") === true,
-                    timeoutSeconds: parseTimeoutSeconds(parsed.flags.get("timeout"), "project apply"),
-                    projectId,
-                    ...(options?.openExternal ? { openExternal: options.openExternal } : {}),
-                    ...(options?.connectPollIntervalMs !== undefined ? { connectPollIntervalMs: options.connectPollIntervalMs } : {}),
-                });
-            }
-            finally {
-                if (!options?.data) {
-                    cliData.close();
-                }
-            }
-        }
-        catch (error) {
-            writeOutput(stderr, `${error instanceof Error ? error.message : String(error)}\n`);
-            return 1;
-        }
+        return await handleProjectCommand({
+            commandArgs,
+            parsed,
+            json,
+            stdout,
+            stderr,
+            runInteractive,
+            ...(options ? { options } : {}),
+        });
     }
     const config = options?.config ??
         loadConfig(undefined, {
@@ -583,169 +151,45 @@ export async function runCli(argv, options) {
         }
         data ??= new CliDataAccess(config);
         if (command === "inspect") {
-            const issueKey = commandArgs[0];
-            if (!issueKey) {
-                throw new Error("inspect requires <issueKey>.");
-            }
-            const result = await data.inspect(issueKey);
-            if (!result) {
-                throw new Error(`Issue not found: ${issueKey}`);
-            }
-            writeOutput(stdout, json ? formatJson(result) : formatInspect(result));
-            return 0;
+            return await handleInspectCommand({ commandArgs, parsed, json, stdout, data, config, runInteractive });
         }
         if (command === "live") {
-            const issueKey = commandArgs[0];
-            if (!issueKey) {
-                throw new Error("live requires <issueKey>.");
-            }
-            const watch = parsed.flags.get("watch") === true;
-            do {
-                const result = await data.live(issueKey);
-                if (!result) {
-                    throw new Error(`No active stage found for ${issueKey}`);
-                }
-                writeOutput(stdout, json ? formatJson(result) : formatLive(result));
-                if (!watch || result.stageRun.status !== "running") {
-                    break;
-                }
-                await delay(2000);
-            } while (true);
-            return 0;
+            return await handleLiveCommand({ commandArgs, parsed, json, stdout, data, config, runInteractive });
         }
         if (command === "report") {
-            const issueKey = commandArgs[0];
-            if (!issueKey) {
-                throw new Error("report requires <issueKey>.");
-            }
-            const reportOptions = {};
-            const stage = getStageFlag(parsed.flags.get("stage"));
-            if (stage) {
-                reportOptions.stage = stage;
-            }
-            if (typeof parsed.flags.get("stage-run") === "string") {
-                reportOptions.stageRunId = Number(parsed.flags.get("stage-run"));
-            }
-            const result = data.report(issueKey, reportOptions);
-            if (!result) {
-                throw new Error(`Issue not found: ${issueKey}`);
-            }
-            writeOutput(stdout, json ? formatJson(result) : formatReport(result));
-            return 0;
+            return await handleReportCommand({ commandArgs, parsed, json, stdout, data, config, runInteractive });
         }
         if (command === "events") {
-            const issueKey = commandArgs[0];
-            if (!issueKey) {
-                throw new Error("events requires <issueKey>.");
-            }
-            const follow = parsed.flags.get("follow") === true;
-            let afterId;
-            let stageRunId = typeof parsed.flags.get("stage-run") === "string" ? Number(parsed.flags.get("stage-run")) : undefined;
-            do {
-                const result = data.events(issueKey, {
-                    ...(stageRunId !== undefined ? { stageRunId } : {}),
-                    ...(typeof parsed.flags.get("method") === "string" ? { method: String(parsed.flags.get("method")) } : {}),
-                    ...(afterId !== undefined ? { afterId } : {}),
-                });
-                if (!result) {
-                    throw new Error(`Stage run not found for ${issueKey}`);
-                }
-                stageRunId = result.stageRun.id;
-                if (result.events.length > 0) {
-                    writeOutput(stdout, json ? formatJson(result) : formatEvents(result));
-                    afterId = result.events.at(-1)?.id;
-                }
-                if (!follow || result.stageRun.status !== "running") {
-                    break;
-                }
-                await delay(2000);
-            } while (true);
-            return 0;
+            return await handleEventsCommand({ commandArgs, parsed, json, stdout, data, config, runInteractive });
         }
         if (command === "worktree") {
-            const issueKey = commandArgs[0];
-            if (!issueKey) {
-                throw new Error("worktree requires <issueKey>.");
-            }
-            const result = data.worktree(issueKey);
-            if (!result) {
-                throw new Error(`Workspace not found for ${issueKey}`);
-            }
-            writeOutput(stdout, json ? formatJson(result) : formatWorktree(result, parsed.flags.get("cd") === true));
-            return 0;
+            return await handleWorktreeCommand({ commandArgs, parsed, json, stdout, data, config, runInteractive });
         }
         if (command === "open") {
-            const issueKey = commandArgs[0];
-            if (!issueKey) {
-                throw new Error("open requires <issueKey>.");
-            }
-            const result = data.open(issueKey);
-            if (!result) {
-                throw new Error(`Workspace not found for ${issueKey}`);
-            }
-            if (json) {
-                writeOutput(stdout, formatJson(result));
-                return 0;
-            }
-            if (parsed.flags.get("print") === true) {
-                writeOutput(stdout, formatOpen(result));
-                return 0;
-            }
-            const openCommand = buildOpenCommand(config, result.workspace.worktreePath, result.resumeThreadId);
-            return await runInteractive(openCommand.command, openCommand.args);
+            return await handleOpenCommand({ commandArgs, parsed, json, stdout, data, config, runInteractive });
         }
         if (command === "connect") {
-            return await runConnectFlow({
+            return await handleConnectCommand({
+                parsed,
+                json,
+                stdout,
                 config,
                 data,
-                stdout,
-                noOpen: parsed.flags.get("no-open") === true,
-                timeoutSeconds: parseTimeoutSeconds(parsed.flags.get("timeout"), "connect"),
-                json,
-                ...(options?.openExternal ? { openExternal: options.openExternal } : {}),
-                ...(options?.connectPollIntervalMs !== undefined ? { connectPollIntervalMs: options.connectPollIntervalMs } : {}),
-                ...(typeof parsed.flags.get("project") === "string" ? { projectId: String(parsed.flags.get("project")) } : {}),
+                ...(options ? { options } : {}),
             });
         }
         if (command === "installations") {
-            const result = await data.listInstallations();
-            if (json) {
-                writeOutput(stdout, formatJson(result));
-                return 0;
-            }
-            writeOutput(stdout, `${(result.installations.length > 0
-                ? result.installations.map((item) => `${item.installation.id}  ${item.installation.workspaceName ?? item.installation.actorName ?? "-"}  projects=${item.linkedProjects.join(",") || "-"}`)
-                : ["No installations found."]).join("\n")}\n`);
-            return 0;
+            return await handleInstallationsCommand({
+                json,
+                stdout,
+                data,
+            });
         }
         if (command === "retry") {
-            const issueKey = commandArgs[0];
-            if (!issueKey) {
-                throw new Error("retry requires <issueKey>.");
-            }
-            const retryOptions = {};
-            const stage = getStageFlag(parsed.flags.get("stage"));
-            if (stage) {
-                retryOptions.stage = stage;
-            }
-            if (typeof parsed.flags.get("reason") === "string") {
-                retryOptions.reason = String(parsed.flags.get("reason"));
-            }
-            const result = data.retry(issueKey, retryOptions);
-            if (!result) {
-                throw new Error(`Issue not found: ${issueKey}`);
-            }
-            writeOutput(stdout, json ? formatJson(result) : formatRetry(result));
-            return 0;
+            return await handleRetryCommand({ commandArgs, parsed, json, stdout, data, config, runInteractive });
         }
         if (command === "list") {
-            const result = data.list({
-                active: parsed.flags.get("active") === true,
-                failed: parsed.flags.get("failed") === true,
-                ...(typeof parsed.flags.get("project") === "string" ? { project: String(parsed.flags.get("project")) } : {}),
-            });
-            writeOutput(stdout, json ? formatJson(result) : formatList(result));
-            return 0;
+            return await handleListCommand({ commandArgs, parsed, json, stdout, data, config, runInteractive });
         }
         throw new Error(`Unknown command: ${command}`);
     }