s-app-scoder-agent 0.8.20 → 0.9.2

package/dist/diagnostics.js

@@ -0,0 +1,188 @@
+/**
+ * v2 (3.5): Diagnostics — turn raw build/test/lint logs into structured
+ * {file, line, severity, code, message} records, plus an error classifier
+ * that maps a failure to a recovery strategy for the agent.
+ *
+ * Supported: tsc (both formats), eslint stylish/compact, pytest (tracebacks +
+ * FAILED lines), go test, cargo, make. Unknown formats fall back to a generic
+ * "error-ish line with a file(:line)? prefix" pattern. Output is deduplicated
+ * and capped (30 diagnostics) so the agent gets a fixable list, not a log.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const MAX_DIAGNOSTICS = 30;
+function add(out, seen, d) {
+    const key = `${d.file}:${d.line}:${d.code}:${d.message.slice(0, 80)}`;
+    if (seen.has(key))
+        return;
+    seen.add(key);
+    if (out.length < MAX_DIAGNOSTICS)
+        out.push(d);
+}
+/** Parse a command output into structured diagnostics (best-effort). */
+export function parseDiagnostics(output) {
+    const out = [];
+    const seen = new Set();
+    let currentFile = null;
+    let pendingCargo = null;
+    for (const rawLine of output.split("\n")) {
+        const line = rawLine.trimEnd();
+        let m;
+        // ── cargo (real output): error line, then "  --> file:line" on the NEXT line.
+        if (pendingCargo) {
+            m = /^\s*-->\s+([^\s:]+):(\d+)(?::\d+)?$/.exec(line);
+            if (m) {
+                add(out, seen, { file: m[1], line: Number(m[2]), severity: "error", code: pendingCargo.code, message: pendingCargo.message, source: "cargo" });
+                pendingCargo = null;
+                continue;
+            }
+            pendingCargo = null; // the error had no location line — drop it
+        }
+        // ── tsc (modern): src/foo.ts(12,5): error TS2322: message
+        m = /^([^\s()][^()]*)\((\d+),(\d+)\):\s*(error|warning)\s+(TS\d+):\s*(.+)$/.exec(line);
+        if (m) {
+            add(out, seen, { file: m[1], line: Number(m[2]), severity: m[4] === "warning" ? "warning" : "error", code: m[5], message: m[6].trim(), source: "tsc" });
+            continue;
+        }
+        // ── tsc (new style): src/foo.ts:12:5 - error TS2322: message
+        m = /^([^\s:][^:]*):(\d+):(\d+)\s+-\s+(error|warning)\s+(TS\d+):\s*(.+)$/.exec(line);
+        if (m) {
+            add(out, seen, { file: m[1], line: Number(m[2]), severity: m[4] === "warning" ? "warning" : "error", code: m[5], message: m[6].trim(), source: "tsc" });
+            continue;
+        }
+        // ── cargo: error[E0308]: msg  --> src/main.rs:10:5
+        m = /^error(?:\[(E\d+)\])?:\s*(.+)\s+-->\s+([^\s:]+):(\d+)(?::\d+)?$/.exec(line);
+        if (m) {
+            add(out, seen, { file: m[3], line: Number(m[4]), severity: "error", code: m[1] ?? null, message: m[2].trim(), source: "cargo" });
+            continue;
+        }
+        // ── cargo (2-line): "error[E0308]: msg" standing alone → expect --> next line.
+        m = /^error(?:\[(E\d+)\])?:\s*(.+)$/.exec(line);
+        if (m) {
+            pendingCargo = { code: m[1] ?? null, message: m[2].trim() };
+            continue;
+        }
+        // ── go vet/test: file.go:123: message   (also covers "# package" headers)
+        m = /^([^\s:][^:()]*(?:\.go|\.py|\.rs|\.ts|\.tsx|\.js|\.mjs)):(\d+):\s+(.+)$/.exec(line);
+        if (m && /error|fail|cannot|undefined|invalid|unexpected|panic/i.test(m[3])) {
+            add(out, seen, { file: m[1], line: Number(m[2]), severity: "error", code: null, message: m[3].trim(), source: "generic" });
+            continue;
+        }
+        // ── eslint stylish: "✖ N problems" ignored; file header then indented rows
+        m = /^\s*(\d+):(\d+)\s+(error|warning)\s+(.+?)\s{2,}([\w-]+)$/.exec(line);
+        if (m && currentFile) {
+            add(out, seen, { file: currentFile, line: Number(m[1]), severity: m[3], code: m[5], message: m[4].trim(), source: "eslint" });
+            continue;
+        }
+        // eslint file header: /abs/path/file.ts  (a bare path on its own line)
+        if (/^([\w./-]+\.(?:ts|tsx|js|jsx|mjs|cjs|vue|svelte))\s*$/.test(line.trim())) {
+            currentFile = line.trim();
+            continue;
+        }
+        // ── pytest: FAILED test_x.py::test_name - assert ...
+        m = /^FAILED\s+([^\s:]+)(?:::[^\s]+)?(?:\s+-\s+(.+))?$/.exec(line);
+        if (m) {
+            add(out, seen, { file: m[1], line: null, severity: "error", code: "FAILED", message: (m[2] ?? "test failed").trim(), source: "pytest" });
+            continue;
+        }
+        // pytest traceback frame: E   AssertionError: ...
+        m = /^E\s+(.+)$/.exec(line);
+        if (m) {
+            add(out, seen, { file: "(pytest)", line: null, severity: "error", code: null, message: m[1].trim().slice(0, 200), source: "pytest" });
+            continue;
+        }
+        // ── go test: --- FAIL: TestName
+        m = /^--- FAIL:\s+([\w/]+)/.exec(line);
+        if (m) {
+            add(out, seen, { file: "(go test)", line: null, severity: "error", code: "FAIL", message: `test failed: ${m[1]}`, source: "go" });
+            continue;
+        }
+        // ── make: make: *** [target] Error 2
+        m = /^make(?:\[\d+\])?: \*\*\* \[([^\]]+)\] Error (\d+)/.exec(line);
+        if (m) {
+            add(out, seen, { file: "Makefile", line: null, severity: "error", code: `make:${m[2]}`, message: `target failed: ${m[1]}`, source: "make" });
+            continue;
+        }
+    }
+    return out;
+}
+/** Compact one-line-per-diagnostic rendering (prompt + UI friendly). */
+export function formatDiagnostics(diags) {
+    if (diags.length === 0)
+        return "";
+    const lines = diags.map((d) => `- ${d.file}${d.line != null ? `:${d.line}` : ""} [${d.severity}${d.code ? ` ${d.code}` : ""}] ${d.message}`);
+    return `Diagnostics (${diags.length}):\n${lines.join("\n")}`;
+}
+/** Classify an error into a recovery strategy for the agent. */
+export function classifyError(text) {
+    const t = text.toLowerCase();
+    const has = (...pats) => pats.some((p) => t.includes(p));
+    if (has("permission denied", "eacces", "denied by policy", "access is denied", "unauthorized", "403")) {
+        return { kind: "permission", strategy: "do NOT retry the same command — use a safer alternative or report the limitation to the user." };
+    }
+    if (has("enotfound", "econnrefused", "etimedout", "network", "fetch failed", "eai_again", "econnreset", "401", "rate limit", "429")) {
+        return { kind: "network", strategy: "check connectivity and credentials first (web_fetch/env), wait or pick another source; do not loop blindly." };
+    }
+    if (has("syntaxerror", "unexpected token", "unexpected end of", "parse error", "unterminated")) {
+        return { kind: "syntax", strategy: "read the file around the indicated line and fix the syntax error directly." };
+    }
+    if (/ts\d{3,5}|type .{0,40}is not assignable|type mismatch|expected type|no compatible/.test(t)) {
+        return { kind: "type", strategy: "read the failing type declaration and the usage site — fix the type, don't cast blindly." };
+    }
+    if (has("assertionerror", "assert failed", "expected", "to equal", "failed assert", "--- fail")) {
+        return { kind: "test", strategy: "read the failing test, understand what it expects, then fix the implementation (or the test only if it is provably wrong)." };
+    }
+    if (has("typeerror", "referenceerror", "rangeerror", "panic", "nil pointer", "null pointer", "segmentation", "enoent")) {
+        return { kind: "runtime", strategy: "read the stack trace, find the failing frame, and fix the root cause." };
+    }
+    return { kind: "unknown", strategy: "read the full error carefully; try a different approach or ask the user." };
+}
+/**
+ * Detect verify commands for the workdir from manifests. rc override via
+ * `verifyCmds` wins (empty string disables one).
+ */
+export function detectVerifyCmds(workdir) {
+    const out = {};
+    try {
+        const pkgPath = join(workdir, "package.json");
+        if (existsSync(pkgPath)) {
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+            const s = pkg.scripts ?? {};
+            if (s.build)
+                out.build = "npm run build";
+            if (s.test)
+                out.test = "npm test";
+            if (s.lint)
+                out.lint = "npm run lint";
+            if (s.typecheck)
+                out.typecheck = "npm run typecheck";
+            else if (s["type-check"])
+                out.typecheck = "npm run type-check";
+        }
+    }
+    catch { /* malformed package.json — fall through */ }
+    try {
+        if (existsSync(join(workdir, "pyproject.toml")))
+            out.test = out.test ?? "pytest";
+        if (existsSync(join(workdir, "Cargo.toml"))) {
+            out.build = out.build ?? "cargo build";
+            out.test = out.test ?? "cargo test";
+        }
+        if (existsSync(join(workdir, "go.mod"))) {
+            out.build = out.build ?? "go build ./...";
+            out.test = out.test ?? "go test ./...";
+        }
+        const makefile = join(workdir, "Makefile");
+        if (existsSync(makefile)) {
+            const mk = readFileSync(makefile, "utf8");
+            if (/^build:/m.test(mk))
+                out.build = out.build ?? "make";
+            if (/^test:/m.test(mk))
+                out.test = out.test ?? "make test";
+            if (/^lint:/m.test(mk))
+                out.lint = out.lint ?? "make lint";
+        }
+    }
+    catch { /* best-effort */ }
+    return out;
+}

package/dist/index.js

@@ -9,6 +9,7 @@ import { JsonlLogger } from "./logger.js";
 import { collectUsage, formatCostReport } from "./cost.js";
 import { getVersion as getPackageVersion } from "./version.js";
 import { dispatchCommand } from "./tui/command-registry.js";
+import { selectableAgents } from "./agents.js";
 import * as ui from "./ui.js";
 // Single source of truth: read version from package.json (see src/version.ts).
 const VERSION = getPackageVersion();
@@ -48,6 +49,7 @@ OPTIONS
   -s, --max-steps <n>       Max autonomous loop iterations (default 40)
   -y, --yes                 Non-interactive mode (auto-approves commands)
   --permission <mode>       auto | ask | readonly (env SCODER_PERMISSION, default auto)
+  --agent <name>            primary agent to run (default build; see /agent): build | plan | review | <custom>
   --no-save                 Disable session auto-save to .scoder/sessions/
   --log-file                Write a JSONL event log to .scoder/logs/<session>.jsonl
                             (or set SCODER_LOG_FILE=1 / =/path/to/log.jsonl)
@@ -102,6 +104,9 @@ function parseArgs(argv) {
             case "--yes":
                 args.yes = true;
                 break;
+            case "--agent":
+                args.agent = next();
+                break;
             case "--permission": {
                 const mode = next();
                 if (mode !== "auto" && mode !== "ask" && mode !== "readonly") {
@@ -113,6 +118,18 @@ function parseArgs(argv) {
             case "--no-save":
                 args.noSave = true;
                 break;
+            case "--no-color":
+                args.noColor = true;
+                break;
+            case "--no-motion":
+                args.noMotion = true;
+                break;
+            case "--plain":
+                args.plain = true;
+                break;
+            case "--high-contrast":
+                args.highContrast = true;
+                break;
             case "--log-file":
                 args.logFile = true;
                 break;
@@ -154,11 +171,23 @@ function parseArgs(argv) {
             case "--version":
                 args.version = true;
                 break;
-            default:
+            default: {
                 if (a.startsWith("-")) {
-                    throw new Error(`Unknown option: ${a} (see --help)`);
+                    // MCP subcommand flags (--command, --url, --trust, --args) are not
+                    // known globally — pass them through as positional args for runMcpCommand
+                    // to interpret. Only throw if we are NOT in an mcp subcommand context.
+                    const isMcpContext = rest[0] === "mcp" || argv.slice(0, i).includes("mcp");
+                    if (!isMcpContext)
+                        throw new Error(`Unknown option: ${a} (see --help)`);
+                    rest.push(a);
+                    // Consume the next token as this option's value if present.
+                    if (i + 1 < argv.length && !argv[i + 1].startsWith("-")) {
+                        rest.push(argv[++i]);
+                    }
+                    break;
                 }
                 rest.push(a);
+            }
         }
     }
     args.task = rest.length > 0 ? rest.join(" ") : null;
@@ -201,6 +230,23 @@ function parseArgs(argv) {
         args.subcommand = "init";
         args.task = null;
     }
+    else if (rest[0] === "mcp") {
+        // scoder mcp list|add <name>|remove <name>|test <name>
+        // e.g. scoder mcp add github --command "npx mcp-github" --url "..." --trust readonly
+        args.subcommand = "mcp";
+        const m = rest[1];
+        if (m === "list" || m === "add" || m === "remove" || m === "test" || m === "import") {
+            args.mcpCmd = m;
+        }
+        else if (m) {
+            args.mcpCmd = "list";
+        }
+        else {
+            args.mcpCmd = "list";
+        }
+        args.mcpArgs = rest.slice(2);
+        args.task = null;
+    }
     return args;
 }
 async function runOnce(cfg, task) {
@@ -324,6 +370,9 @@ async function repl(cfg) {
         const host = {
             agent: () => agent,
             config: cfg,
+            updateConfig: (patch) => {
+                Object.assign(cfg, patch); // mutate the shared cfg so new Agents see it
+            },
             replaceAgent: (next) => {
                 agent.abort();
                 agent.dispose();
@@ -350,6 +399,17 @@ async function repl(cfg) {
                 break;
             if (outcome?.notice)
                 ui.info(outcome.notice);
+            if (!outcome?.task)
+                continue;
+            try {
+                const result = first ? await agent.run(outcome.task) : await agent.runTurn(outcome.task);
+                first = false;
+                if (!result.success)
+                    ui.warn("task did not complete — try refining it");
+            }
+            catch (err) {
+                ui.error(err.message);
+            }
             continue;
         }
         try {
@@ -366,6 +426,191 @@ async function repl(cfg) {
     ui.info("bye");
     process.exit(0);
 }
+async function runMcpCommand(cfg, cmd, restArgs) {
+    const { McpManager } = await import("./mcp.js");
+    const { readFileSync, writeFileSync, existsSync } = await import("node:fs");
+    const { join, dirname } = await import("node:path");
+    const { mkdirSync } = await import("node:fs");
+    const rcPath = join(cfg.workdir, ".scoderrc.json");
+    // Load existing mcpServers from workdir rc.
+    const existing = {};
+    if (existsSync(rcPath)) {
+        try {
+            Object.assign(existing, JSON.parse(readFileSync(rcPath, "utf8")).mcpServers ?? {});
+        }
+        catch { /* ignore */ }
+    }
+    if (cmd === "list") {
+        const servers = Object.entries(cfg.mcpServers ?? existing);
+        if (servers.length === 0) {
+            console.log("no MCP servers configured — add mcpServers to .scoderrc.json");
+            return;
+        }
+        for (const [name, cfg_srv] of servers) {
+            const trust = cfg_srv.trust ?? "auto";
+            const enabled = cfg_srv.enabled === false ? " (disabled)" : "";
+            const target = cfg_srv.url ?? cfg_srv.command ?? "?";
+            console.log(`${name}: ${target}${trust !== "auto" ? ` [${trust}]` : ""}${enabled}`);
+        }
+        return;
+    }
+    if (cmd === "add") {
+        // scoder mcp add <name> --command "..." [--url "..."] [--trust auto|ask|readonly|deny]
+        const name = restArgs[0];
+        if (!name) {
+            console.error("usage: scoder mcp add <name> --command '...' [--url '...'] [--trust readonly]");
+            return;
+        }
+        const opts = {};
+        for (let i = 1; i < restArgs.length; i++) {
+            if (restArgs[i] === "--command" || restArgs[i] === "-c")
+                opts.command = restArgs[++i];
+            else if (restArgs[i] === "--url" || restArgs[i] === "-u")
+                opts.url = restArgs[++i];
+            else if (restArgs[i] === "--trust" || restArgs[i] === "-t")
+                opts.trust = restArgs[++i];
+            else if (restArgs[i] === "--args" || restArgs[i] === "-a")
+                opts.args = restArgs[++i];
+        }
+        if (!opts.command && !opts.url) {
+            console.error("error: --command or --url required");
+            return;
+        }
+        const newEntry = { ...(opts.command ? { command: opts.command } : {}), ...(opts.url ? { url: opts.url } : {}), ...(opts.args ? { args: opts.args.split(" ") } : {}), ...(opts.trust ? { trust: opts.trust } : {}) };
+        const allServers = { ...existing, [name]: newEntry };
+        const rc = existsSync(rcPath) ? JSON.parse(readFileSync(rcPath, "utf8")) : {};
+        mkdirSync(dirname(rcPath) || ".", { recursive: true });
+        writeFileSync(rcPath, JSON.stringify({ ...rc, mcpServers: allServers }, null, 2) + "\n", "utf8");
+        console.log(`MCP server "${name}" added to ${rcPath}`);
+        return;
+    }
+    if (cmd === "remove") {
+        const name = restArgs[0];
+        if (!name) {
+            console.error("usage: scoder mcp remove <name>");
+            return;
+        }
+        if (!existing[name] && !(cfg.mcpServers ?? {})[name]) {
+            console.error(`MCP server "${name}" not found in config`);
+            return;
+        }
+        const allServers = { ...existing };
+        delete allServers[name];
+        const rc = existsSync(rcPath) ? JSON.parse(readFileSync(rcPath, "utf8")) : {};
+        mkdirSync(dirname(rcPath) || ".", { recursive: true });
+        writeFileSync(rcPath, JSON.stringify({ ...rc, mcpServers: allServers }, null, 2) + "\n", "utf8");
+        console.log(`MCP server "${name}" removed from ${rcPath}`);
+        return;
+    }
+    if (cmd === "test") {
+        const name = restArgs[0];
+        if (!name) {
+            console.error("usage: scoder mcp test <name>");
+            return;
+        }
+        const srvCfg = (cfg.mcpServers ?? {})[name] ?? existing[name];
+        if (!srvCfg) {
+            console.error(`MCP server "${name}" not found`);
+            return;
+        }
+        if (srvCfg.enabled === false) {
+            console.log(`✘ "${name}" is disabled (enabled:false)`);
+            return;
+        }
+        if (srvCfg.trust === "readonly") {
+            console.log(`✘ "${name}" is trust:readonly — not spawning`);
+            return;
+        }
+        console.log(`connecting to "${name}"...`);
+        const m = new McpManager({ [name]: srvCfg });
+        try {
+            await m.connectAll();
+            const states = m.serverStates();
+            const s = states[0];
+            if (s?.state === "ready") {
+                console.log(`✓ "${name}" connected — ${s.toolCount} tools`);
+                console.log(`  serverInfo: ${s.serverInfo.name ?? "?"} v${s.serverInfo.version ?? "?"}`);
+                console.log(`  capabilities: ${Object.keys(s.capabilities).join(", ") || "(none)"}`);
+            }
+            else {
+                console.log(`✘ "${name}" failed to connect (state: ${s?.state})`);
+            }
+        }
+        finally {
+            m.killAll();
+        }
+        return;
+    }
+    if (cmd === "import") {
+        // scoder mcp import [path] [--dry-run] [--force]
+        const { loadConfigFile, discoverConfigs, mergeConfigs } = await import("./mcp-import.js");
+        const dryRun = restArgs.includes("--dry-run");
+        const force = restArgs.includes("--force");
+        const paths = restArgs.filter((a) => !a.startsWith("--"));
+        let discovered = [];
+        try {
+            discovered = discoverConfigs();
+        }
+        catch { /* ignore */ }
+        if (paths.length === 0 && discovered.length === 0) {
+            console.log("No config files found. Provide a path or ensure one of these exists:");
+            console.log("  ~/.claude/config.json  — Claude Desktop MCP servers");
+            console.log("  opencode.json         — OpenCode MCP config");
+            console.log("  .mcp.json             — standard MCP server list");
+            console.log("\nUsage: scoder mcp import [path] [--dry-run] [--force]");
+            return;
+        }
+        // Auto-discover when no path given
+        const toCheck = paths.length > 0 ? paths : discovered.map((d) => d.source);
+        if (paths.length === 0 && discovered.length > 0) {
+            console.log("Auto-discovered MCP config files:");
+            for (const d of discovered) {
+                console.log(`  ${d.format}: ${d.source} (${d.serverCount} server${d.serverCount === 1 ? "" : "s"})`);
+            }
+            console.log();
+        }
+        const { readFileSync, writeFileSync, existsSync } = await import("node:fs");
+        const { mkdirSync } = await import("node:fs");
+        let totalAdded = 0;
+        let totalSkipped = 0;
+        for (const srcPath of toCheck) {
+            const servers = loadConfigFile(srcPath);
+            if (!servers) {
+                console.log(`  skip: ${srcPath} not found`);
+                continue;
+            }
+            const { added, skipped } = mergeConfigs(existing, servers, { force, dryRun });
+            totalAdded += added.length;
+            totalSkipped += skipped.length;
+            console.log(`${srcPath}:`);
+            for (const s of added) {
+                const target = s.config.url ?? s.config.command ?? "?";
+                console.log(`  + ${s.name}: ${target} (from ${s.originalKey})`);
+            }
+            for (const s of skipped) {
+                console.log(`  ~ ${s.name}: skipped (already exists; use --force to overwrite)`);
+            }
+            if (added.length === 0 && skipped.length === 0) {
+                console.log(`    (no servers found)`);
+            }
+        }
+        if (dryRun) {
+            console.log(`\n[DRY RUN] Would import ${totalAdded} server${totalAdded === 1 ? "" : "s"} (${totalSkipped} skipped).`);
+            return;
+        }
+        if (totalAdded > 0) {
+            const rc = existsSync(rcPath) ? JSON.parse(readFileSync(rcPath, "utf8")) : {};
+            mkdirSync(dirname(rcPath) || ".", { recursive: true });
+            writeFileSync(rcPath, JSON.stringify({ ...rc, mcpServers: existing }, null, 2) + "\n", "utf8");
+            console.log(`\nImported ${totalAdded} server${totalAdded === 1 ? "" : "s"} into ${rcPath} (${totalSkipped} skipped).`);
+        }
+        else {
+            console.log(`\nNothing to import.`);
+        }
+        return;
+    }
+    console.error(`unknown mcp command: ${cmd}`);
+}
 async function main() {
     let args;
     try {
@@ -383,6 +628,14 @@ async function main() {
         console.log(HELP);
         return;
     }
+    if (args.noColor)
+        process.env.NO_COLOR = "1";
+    if (args.noMotion)
+        process.env.SCODER_NO_MOTION = "1";
+    if (args.plain)
+        process.env.SCODER_PLAIN = "1";
+    if (args.highContrast)
+        process.env.SCODER_THEME = "high-contrast";
     const cfg = loadConfig({
         model: args.model,
         baseUrl: args.baseUrl,
@@ -395,7 +648,16 @@ async function main() {
         provider: args.provider ?? undefined,
         noSave: args.noSave,
         logFile: args.logFile,
+        agent: args.agent,
     });
+    // v2: --agent must reference a selectable (mode primary|all) agent.
+    if (args.agent) {
+        const ok = selectableAgents(cfg.workdir).some((a) => a.name === args.agent);
+        if (!ok) {
+            ui.error(`unknown or non-primary agent "${args.agent}" — selectable: ${selectableAgents(cfg.workdir).map((a) => a.name).join(", ")}`);
+            process.exit(2);
+        }
+    }
     // Subcommands
     if (args.subcommand === "init") {
         await runInit();
@@ -486,6 +748,10 @@ async function main() {
             console.log(`  (no models match "${filter}")`);
         return;
     }
+    if (args.subcommand === "mcp") {
+        await runMcpCommand(cfg, args.mcpCmd ?? "list", args.mcpArgs ?? []);
+        return;
+    }
     if (args.subcommand === "tui") {
         if (!process.stdin.isTTY || !process.stdout.isTTY) {
             ui.warn("TUI requires an interactive terminal (TTY) — falling back to the classic REPL.");
@@ -531,7 +797,12 @@ async function main() {
     }
     await repl(cfg);
 }
-main().catch((err) => {
-    ui.error(`fatal: ${err.stack ?? err.message}`);
-    process.exit(2);
-});
+import { pathToFileURL } from "node:url";
+// Guard: only run when executed as entry point (not imported in tests).
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    main().catch((err) => {
+        ui.error(`fatal: ${err.stack ?? err.message}`);
+        process.exit(2);
+    });
+}
+export { parseArgs };