@shipd-ai/cli 0.1.0

package/dist/commands/checks.js

@@ -0,0 +1,669 @@
+import { readFile } from "node:fs/promises";
+import { createInterface } from "node:readline";
+import { defineCommand } from "citty";
+import { connectQuest } from "../client.js";
+import { isPrecheckKey, precheckStageId, } from "../contract.js";
+import { EXIT_CHECK_FAILED, UsageError } from "../errors.js";
+import { dim, formatDuration, printJson, printTable, statusBadge, truncate } from "../format.js";
+import { readHarborBundle } from "../harbor.js";
+import { DEFAULT_MAX_STEP_MS, DEFAULT_POLL_MS, runChecks, } from "../plan.js";
+import { DEFAULT_QUEST } from "../quests.js";
+import { exitCodeFor, modeLabel, renderTable, writeReport, } from "../report.js";
+const color = () => Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+const questArg = {
+    quest: {
+        type: "string",
+        description: `Quest to talk to (default: ${DEFAULT_QUEST})`,
+        default: DEFAULT_QUEST,
+    },
+};
+function parsePositiveNumber(raw, fallback, flag) {
+    if (raw === undefined || raw === "")
+        return fallback;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new UsageError(`--${flag} must be a positive number, got "${raw}".`);
+    }
+    return parsed;
+}
+/** "a + b → c": steps grouped by dependency depth. */
+export function formatSteps(check) {
+    const depth = new Map();
+    const resolve = (id, seen = []) => {
+        const known = depth.get(id);
+        if (known !== undefined)
+            return known;
+        if (seen.includes(id))
+            return 0;
+        const step = check.steps.find((s) => s.id === id);
+        const d = step?.after.length
+            ? 1 + Math.max(...step.after.map((a) => resolve(a, [...seen, id])))
+            : 0;
+        depth.set(id, d);
+        return d;
+    };
+    const levels = new Map();
+    for (const step of check.steps) {
+        const d = resolve(step.id);
+        levels.set(d, [...(levels.get(d) ?? []), step.id]);
+    }
+    return [...levels.keys()]
+        .sort((a, b) => a - b)
+        .map((d) => (levels.get(d) ?? []).join(" + "))
+        .join(" → ");
+}
+export function selectChecks(catalog, explicit, all) {
+    if (all)
+        return { checks: catalog.checks, selection: "all" };
+    const keys = (explicit ?? "")
+        .split(",")
+        .map((k) => k.trim())
+        .filter(Boolean);
+    if (keys.length === 0)
+        throw new UsageError("Pass --check <key[,key...]> or --all.");
+    const byKey = new Map(catalog.checks.map((c) => [c.key, c]));
+    const unknown = keys.filter((k) => !byKey.has(k));
+    if (unknown.length > 0) {
+        throw new UsageError(`Unknown check${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}.\n` +
+            `  Valid keys for ${catalog.quest}: ${catalog.checks.map((c) => c.key).join(", ")}`);
+    }
+    const unique = [...new Set(keys)];
+    return { checks: unique.map((k) => byKey.get(k)), selection: "explicit" };
+}
+function skippedResult(check, reason) {
+    return {
+        key: check.key,
+        label: check.label,
+        kind: check.kind,
+        status: "skipped",
+        reason,
+        durationMs: 0,
+        steps: {},
+    };
+}
+function warnLive(message) {
+    console.error(`\n  Writes to production: ${message}\n`);
+}
+function progressPrinter() {
+    const c = color();
+    return (event) => {
+        switch (event.type) {
+            case "step:start":
+                if (event.immediate) {
+                    console.error(`  ${dim("·", c)} ${event.checkKey}/${event.stepId} resolved immediately`);
+                }
+                else {
+                    const id = event.handle ? ` ${dim(`(${event.handle.modalFunctionCallId})`, c)}` : "";
+                    console.error(`  ${dim("▸", c)} ${event.checkKey}/${event.stepId} started${id}`);
+                }
+                break;
+            case "step:end": {
+                const verdict = event.verdict ? ` (${event.verdict})` : "";
+                const detail = event.error ? `: ${event.error}` : event.reason ? `: ${event.reason}` : "";
+                console.error(`  ${statusBadge(event.status, c)} ${event.checkKey}/${event.stepId}${verdict}${detail}`);
+                break;
+            }
+            case "live:started":
+                console.error(event.started
+                    ? `  ${dim("▸", c)} ${event.checkKey} triggered`
+                    : `  ${statusBadge("skipped", c)} ${event.checkKey} not started${event.detail ? `: ${event.detail}` : ""}`);
+                break;
+            case "live:nudge":
+                console.error(`  ${dim("▸", c)} ${event.checkKey} nudging synthesis`);
+                break;
+            case "check:end": {
+                const r = event.result;
+                const verdict = r.verdict ? ` (${r.verdict})` : "";
+                console.error(`  ${statusBadge(r.status, c)} ${r.key}${verdict} in ${formatDuration(r.durationMs)}`);
+                break;
+            }
+            default:
+                break;
+        }
+    };
+}
+// Never exits the process directly: every path aborts the run and lets the
+// command finish writing the report (handles included) before exit 3.
+function installInterruptHandler(controller, state) {
+    let asked = false;
+    const leaveRunning = () => {
+        state.mode = "leave";
+        console.error("\n  Leaving in-flight steps running; their handles stay in the report. Exit 3.");
+        controller.abort();
+    };
+    const onSigint = () => {
+        if (asked || controller.signal.aborted) {
+            leaveRunning();
+            return;
+        }
+        asked = true;
+        if (!process.stdin.isTTY) {
+            console.error("\n  Interrupted: cancelling in-flight steps...");
+            controller.abort();
+            return;
+        }
+        const rl = createInterface({ input: process.stdin, output: process.stderr });
+        rl.on("SIGINT", () => {
+            rl.close();
+            leaveRunning();
+        });
+        rl.question("\n  Cancel in-flight steps? [Y/n] ", (answer) => {
+            rl.close();
+            if (answer.trim().toLowerCase().startsWith("n")) {
+                leaveRunning();
+                return;
+            }
+            console.error("  Cancelling in-flight steps...");
+            controller.abort();
+        });
+    };
+    process.on("SIGINT", onSigint);
+    return () => {
+        process.off("SIGINT", onSigint);
+    };
+}
+/** Lines for `--dry-run --task`: what would be dispatched, without dispatching. */
+export function dryRunTaskLines(task, checks) {
+    return [
+        `Task ${task.problemId} ("${task.title}", ${task.status}) — ${task.url}`,
+        `Nothing started (dry run). These checks would run live and re-point the task's visible results:`,
+        ...checks.map((c) => `  ${c.key.padEnd(28)} ${c.kind.padEnd(9)} ${formatSteps(c)}`),
+    ];
+}
+function printDryRun(report, bundle, adapt, checks, json, withDraft) {
+    const selected = Object.fromEntries(checks.map((c) => [c.key, adapt.checks[c.key] ?? { eligible: true, missing: [] }]));
+    if (json) {
+        printJson({
+            quest: report.quest,
+            mode: report.mode,
+            dryRun: true,
+            source: report.source,
+            fields: adapt.fields,
+            checks: selected,
+            ...(withDraft ? { draft: adapt.draft } : {}),
+        });
+        return;
+    }
+    const c = color();
+    console.log(`\n  Quest: ${report.quest} (dry run, nothing started)`);
+    console.log(`  Bundle: ${bundle.dir}`);
+    console.log(`  Input:  ${bundle.inputHash}\n`);
+    console.log("  Adapted fields:");
+    for (const [key, value] of Object.entries(adapt.fields)) {
+        if (value === undefined || value === null || value === "")
+            continue;
+        const text = typeof value === "string" ? value : JSON.stringify(value);
+        const size = typeof value === "string" && value.length > 60 ? ` (${value.length} chars)` : "";
+        console.log(`    ${key.padEnd(16)} ${truncate(text, 60)}${size}`);
+    }
+    console.log("");
+    printTable(checks.map((check) => {
+        const entry = selected[check.key];
+        return {
+            check: check.key,
+            kind: check.kind,
+            eligible: entry.eligible
+                ? statusBadge("pass", c).replace("pass", "yes")
+                : statusBadge("fail", c).replace("fail", "no"),
+            missing: entry.missing.join(", "),
+            steps: formatSteps(check),
+        };
+    }), [
+        { key: "check", label: "Check" },
+        { key: "kind", label: "Kind" },
+        { key: "eligible", label: "Eligible" },
+        { key: "missing", label: "Missing" },
+        { key: "steps", label: "Steps" },
+    ]);
+    if (withDraft) {
+        console.log("\n  Draft that --create would create (not created):");
+        for (const [key, value] of Object.entries(adapt.draft)) {
+            const text = typeof value === "string" ? value : JSON.stringify(value);
+            const size = typeof value === "string" && value.length > 60 ? ` (${value.length} chars)` : "";
+            console.log(`    ${key.padEnd(16)} ${truncate(text, 60)}${size}`);
+        }
+    }
+    console.log("");
+}
+async function startWithoutWaiting(api, target, checks, options) {
+    let failures = 0;
+    for (const check of checks) {
+        try {
+            if (target.kind === "live") {
+                const started = await api.runLiveCheck(target.task.versionId, target.task.problemId, check.key, options);
+                console.log(JSON.stringify({
+                    checkKey: check.key,
+                    mode: "live",
+                    problemId: target.task.problemId,
+                    versionId: target.task.versionId,
+                    url: target.task.url,
+                    ...started,
+                }));
+                continue;
+            }
+            if (check.kind === "precheck" || isPrecheckKey(check.key)) {
+                const result = await api.runPrecheckStage(target.bundle, precheckStageId(check.key));
+                console.log(JSON.stringify({ checkKey: check.key, kind: "precheck", result }));
+                continue;
+            }
+            const roots = check.steps.filter((s) => s.after.length === 0);
+            const dependents = check.steps.filter((s) => s.after.length > 0);
+            if (dependents.length > 0) {
+                console.error(`  ${check.key}: only the root step${roots.length > 1 ? "s" : ""} ${roots.map((s) => s.id).join(", ")} ` +
+                    `start without --wait; ${dependents.map((s) => s.id).join(", ")} need the earlier outputs.`);
+            }
+            for (const step of roots) {
+                const started = await api.startStep(target.bundle, check.key, step.id, {}, options);
+                console.log(JSON.stringify({ checkKey: check.key, stepId: step.id, ...started }));
+            }
+        }
+        catch (error) {
+            failures += 1;
+            console.log(JSON.stringify({
+                checkKey: check.key,
+                kind: "error",
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        }
+    }
+    return failures > 0 ? EXIT_CHECK_FAILED : 0;
+}
+/** Parse `status`/`cancel` positionals: a handle JSON string or a report file path. */
+async function readHandles(raw) {
+    if (raw.length === 0) {
+        throw new UsageError("Pass one or more handles (JSON from --no-wait) or a report file path.");
+    }
+    const handles = [];
+    const isHandle = (value) => !!value &&
+        typeof value === "object" &&
+        typeof value.modalFunctionCallId === "string" &&
+        typeof value.checkKey === "string";
+    const collect = (value) => {
+        if (isHandle(value)) {
+            handles.push(value);
+            return;
+        }
+        if (value && typeof value === "object") {
+            for (const inner of Object.values(value))
+                collect(inner);
+        }
+    };
+    for (const arg of raw) {
+        let parsed;
+        const trimmed = arg.trim();
+        if (trimmed.startsWith("{")) {
+            try {
+                parsed = JSON.parse(trimmed);
+            }
+            catch {
+                throw new UsageError(`Not a valid handle JSON: ${truncate(trimmed, 60)}`);
+            }
+        }
+        else {
+            try {
+                parsed = JSON.parse(await readFile(trimmed, "utf-8"));
+            }
+            catch {
+                throw new UsageError(`Could not read handles from ${trimmed}: not a handle and not a JSON file.`);
+            }
+        }
+        const before = handles.length;
+        collect(parsed);
+        if (handles.length === before) {
+            throw new UsageError(`No handles found in ${truncate(trimmed, 60)}`);
+        }
+    }
+    return handles;
+}
+const list = defineCommand({
+    meta: { name: "list", description: "List the checks a quest offers for ad-hoc runs" },
+    args: {
+        ...questArg,
+        json: { type: "boolean", description: "Output as JSON" },
+    },
+    run: async ({ args }) => {
+        const api = await connectQuest(args.quest);
+        const catalog = await api.listChecks();
+        if (args.json) {
+            printJson(catalog);
+            return;
+        }
+        console.log(`\n  Checks for ${catalog.quest}\n`);
+        printTable(catalog.checks.map((check) => ({
+            key: check.key,
+            label: check.label,
+            kind: check.kind,
+            requires: check.requires.join(", "),
+            steps: formatSteps(check),
+        })), [
+            { key: "key", label: "Key" },
+            { key: "label", label: "Label" },
+            { key: "kind", label: "Kind" },
+            { key: "requires", label: "Requires" },
+            { key: "steps", label: "Steps" },
+        ]);
+        const notes = catalog.checks.filter((c) => c.notes);
+        if (notes.length > 0) {
+            console.log("\n  Notes:");
+            for (const check of notes)
+                console.log(`    ${check.key}: ${check.notes}`);
+        }
+        console.log("");
+    },
+});
+const run = defineCommand({
+    meta: {
+        name: "run",
+        description: "Run checks on a Harbor task directory (stateless or --create) or on a task (--task)",
+    },
+    args: {
+        dir: { type: "positional", description: "Harbor task directory", required: false },
+        ...questArg,
+        task: { type: "string", description: "Run live on an existing task (problem id)" },
+        create: {
+            type: "boolean",
+            description: "Turn the Harbor directory into a real draft under your account, then run live",
+            default: false,
+        },
+        check: { type: "string", description: "Comma-separated check keys (see `checks list`)" },
+        all: {
+            type: "boolean",
+            description: "Run every check; ineligible ones are skipped with the reason",
+        },
+        "dry-run": {
+            type: "boolean",
+            description: "Adapt the bundle, print eligibility (and the draft for --create), start nothing",
+        },
+        wait: {
+            type: "boolean",
+            description: "Wait for results; --no-wait prints handles as JSON lines and exits",
+            default: true,
+        },
+        json: { type: "boolean", description: "Print the report as JSON" },
+        out: { type: "string", description: "Write the JSON report to this file" },
+        repo: { type: "string", description: "Override metadata.repository_url" },
+        commit: { type: "string", description: "Override metadata.base_commit_hash" },
+        title: { type: "string", description: "Override metadata.problem_title" },
+        category: { type: "string", description: "Override metadata.category" },
+        language: { type: "string", description: "Override metadata.language" },
+        difficulty: { type: "string", description: "Override metadata.difficulty" },
+        model: { type: "string", description: "Agent model override where the check honors it" },
+        effort: {
+            type: "enum",
+            description: "Reasoning effort override where the check honors it",
+            options: ["low", "medium", "high", "xhigh"],
+        },
+        poll: { type: "string", description: "Poll interval in seconds (default 15)" },
+        timeout: { type: "string", description: "Per-step ceiling in minutes (default 180)" },
+    },
+    run: async ({ args }) => {
+        const dir = args.dir;
+        if (!dir && !args.task)
+            throw new UsageError("Pass a Harbor directory or --task <problemId>.");
+        if (dir && args.task)
+            throw new UsageError("Pass either a Harbor directory or --task, not both.");
+        if (args.create && !dir)
+            throw new UsageError("--create needs a Harbor directory.");
+        if (args.check && args.all)
+            throw new UsageError("Pass either --check or --all, not both.");
+        if (!args.check && !args.all)
+            throw new UsageError("Pass --check <key[,key...]> or --all.");
+        const pollMs = parsePositiveNumber(args.poll, DEFAULT_POLL_MS / 1000, "poll") * 1000;
+        const maxStepMs = parsePositiveNumber(args.timeout, DEFAULT_MAX_STEP_MS / 60_000, "timeout") * 60_000;
+        const options = {};
+        if (args.model)
+            options.agentModel = args.model;
+        if (args.effort)
+            options.reasoningEffort = args.effort;
+        // Bundle errors exit 2 before any network call.
+        const overrides = {
+            repo: args.repo,
+            commit: args.commit,
+            title: args.title,
+            category: args.category,
+            language: args.language,
+            difficulty: args.difficulty,
+        };
+        const bundle = dir ? await readHarborBundle(dir, overrides) : null;
+        const api = await connectQuest(args.quest);
+        const catalog = await api.listChecks();
+        const { checks: selected, selection } = selectChecks(catalog, args.check, Boolean(args.all));
+        const mode = args.task ? "task" : args.create ? "harbor-create" : "harbor";
+        const report = {
+            quest: catalog.quest,
+            mode,
+            selection,
+            source: {},
+            generatedAt: new Date().toISOString(),
+            checks: {},
+            prechecks: {},
+        };
+        let runnable = selected;
+        if (bundle) {
+            report.source = { dir: bundle.dir, inputHash: bundle.inputHash };
+            const adapt = await api.adapt(bundle);
+            if (args["dry-run"]) {
+                printDryRun(report, bundle, adapt, selected, Boolean(args.json), Boolean(args.create));
+                return;
+            }
+            runnable = [];
+            for (const check of selected) {
+                const entry = adapt.checks[check.key];
+                if (entry && !entry.eligible) {
+                    report.checks[check.key] = skippedResult(check, `missing: ${entry.missing.join(", ")}`);
+                }
+                else {
+                    runnable.push(check);
+                }
+            }
+        }
+        let target;
+        if (args.task) {
+            const task = await api.resolveTask(args.task);
+            if (!task)
+                throw new UsageError(`Task not found or not readable: ${args.task}`);
+            if (args["dry-run"]) {
+                if (args.json) {
+                    printJson({
+                        ...report,
+                        source: { ...task },
+                        dryRun: true,
+                        checks: selected.map((c) => c.key),
+                    });
+                }
+                else {
+                    for (const line of dryRunTaskLines(task, selected))
+                        console.log(`  ${line}`);
+                    console.log("");
+                }
+                return;
+            }
+            report.source = {
+                problemId: task.problemId,
+                versionId: task.versionId,
+                title: task.title,
+                url: task.url,
+            };
+            warnLive(`checks run live on task ${task.problemId} ("${task.title}"); its visible results are re-pointed.`);
+            report.taskUrl = task.url;
+            target = { kind: "live", task };
+        }
+        else if (args.create && bundle) {
+            warnLive(`creating a draft task from ${bundle.dir} under your account, then running checks live on it.`);
+            const task = await api.createFromHarbor(bundle);
+            console.error(`  Created draft ${task.problemId}: ${task.url}\n`);
+            report.taskUrl = task.url;
+            report.source = {
+                ...report.source,
+                problemId: task.problemId,
+                versionId: task.versionId,
+                title: task.title,
+                url: task.url,
+            };
+            target = { kind: "live", task };
+        }
+        else {
+            target = { kind: "harbor", bundle: bundle };
+        }
+        if (!args.wait) {
+            // Checks `adapt` marked ineligible never start; with an explicit
+            // --check list they still count as a failure, like in the waited run.
+            const skipped = Object.values(report.checks).filter((c) => c.status === "skipped");
+            for (const check of skipped) {
+                console.log(JSON.stringify({ checkKey: check.key, kind: "skipped", reason: check.reason }));
+            }
+            const startExit = await startWithoutWaiting(api, target, runnable, options);
+            const skipExit = skipped.length > 0 && selection === "explicit" ? EXIT_CHECK_FAILED : 0;
+            process.exitCode = Math.max(startExit, skipExit);
+            return;
+        }
+        if (!args.json) {
+            console.error(`  Quest: ${report.quest} (${modeLabel(mode)})`);
+            if (target.kind === "live") {
+                console.error(`  Task:  ${target.task.title} — ${target.task.url}`);
+            }
+            console.error(`  Running ${runnable.length} check${runnable.length === 1 ? "" : "s"}: ${runnable.map((c) => c.key).join(", ")}\n`);
+        }
+        const controller = new AbortController();
+        const interrupt = { mode: "cancel" };
+        const restore = installInterruptHandler(controller, interrupt);
+        const controls = {
+            pollMs,
+            maxStepMs,
+            signal: controller.signal,
+            onEvent: progressPrinter(),
+            onAbort: () => interrupt.mode,
+        };
+        let results;
+        try {
+            results = await runChecks(api, target, runnable, options, controls);
+        }
+        finally {
+            restore();
+        }
+        for (const result of results) {
+            report.checks[result.key] = result;
+            if (isPrecheckKey(result.key) && result.output && typeof result.output === "object") {
+                report.prechecks[precheckStageId(result.key)] = result.output;
+            }
+        }
+        if (args.json) {
+            printJson(report);
+        }
+        else {
+            console.log(`\n${renderTable(report, { color: color() })}\n`);
+            const failed = Object.values(report.checks).filter((c) => c.error);
+            for (const check of failed) {
+                console.log(`  ${check.key}: ${check.error}`);
+            }
+            if (failed.length > 0)
+                console.log("");
+            if (target.kind === "live") {
+                console.log(`  Task page (results live there): ${target.task.url}\n`);
+            }
+        }
+        if (args.out) {
+            const path = await writeReport(report, args.out);
+            console.error(`  Report written to ${path}`);
+            if (target.kind === "live")
+                console.error(`  Task page: ${target.task.url}`);
+        }
+        process.exitCode = exitCodeFor(report);
+    },
+});
+const status = defineCommand({
+    meta: { name: "status", description: "Poll handles printed by `checks run --no-wait`" },
+    args: {
+        handles: { type: "positional", description: "Handle JSON or a report file", required: false },
+        ...questArg,
+        json: { type: "boolean", description: "Output as JSON lines" },
+    },
+    run: async ({ args }) => {
+        const handles = await readHandles(args._);
+        const api = await connectQuest(args.quest);
+        const rows = [];
+        for (const handle of handles) {
+            try {
+                const step = await api.getStep(handle);
+                if (args.json) {
+                    console.log(JSON.stringify({ handle, ...step }));
+                    continue;
+                }
+                rows.push({
+                    handle,
+                    status: step.status,
+                    verdict: step.status === "running" ? undefined : step.verdict,
+                    detail: step.status === "failed" ? step.error : undefined,
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (args.json) {
+                    console.log(JSON.stringify({ handle, status: "error", error: message }));
+                    continue;
+                }
+                rows.push({ handle, status: "error", detail: message });
+            }
+        }
+        if (!args.json) {
+            const c = color();
+            printTable(rows.map((row) => ({
+                step: `${row.handle.checkKey}/${row.handle.stepId}`,
+                call: row.handle.modalFunctionCallId,
+                status: statusBadge(row.status, c),
+                verdict: row.verdict ?? "",
+                detail: truncate(row.detail ?? "", 60),
+            })), [
+                { key: "step", label: "Step" },
+                { key: "call", label: "Call" },
+                { key: "status", label: "Status" },
+                { key: "verdict", label: "Verdict" },
+                { key: "detail", label: "Detail" },
+            ]);
+        }
+    },
+});
+const cancel = defineCommand({
+    meta: { name: "cancel", description: "Cancel handles printed by `checks run --no-wait`" },
+    args: {
+        handles: { type: "positional", description: "Handle JSON or a report file", required: false },
+        ...questArg,
+        json: { type: "boolean", description: "Output as JSON lines" },
+    },
+    run: async ({ args }) => {
+        const handles = await readHandles(args._);
+        const api = await connectQuest(args.quest);
+        let failures = 0;
+        for (const handle of handles) {
+            const label = `${handle.checkKey}/${handle.stepId} (${handle.modalFunctionCallId})`;
+            try {
+                const result = await api.cancelStep(handle);
+                if (args.json) {
+                    console.log(JSON.stringify({ handle, ...result }));
+                }
+                else {
+                    console.log(`  ${result.cancelled ? "cancelled" : "not cancelled"}  ${label}`);
+                }
+            }
+            catch (error) {
+                failures += 1;
+                const message = error instanceof Error ? error.message : String(error);
+                if (args.json) {
+                    console.log(JSON.stringify({ handle, cancelled: false, error: message }));
+                }
+                else {
+                    console.log(`  error  ${label}: ${message}`);
+                }
+            }
+        }
+        if (failures > 0)
+            process.exitCode = EXIT_CHECK_FAILED;
+    },
+});
+export default defineCommand({
+    meta: {
+        name: "checks",
+        description: "List and run quest checks on Harbor tasks or existing tasks",
+    },
+    subCommands: { list, run, status, cancel },
+});