@shipd-ai/cli 0.1.0

package/dist/plan.js

@@ -0,0 +1,367 @@
+import { isPrecheckKey, precheckStageId, } from "./contract.js";
+import { errorMessage } from "./errors.js";
+import { formatDuration } from "./format.js";
+import { precheckVerdict } from "./report.js";
+export const DEFAULT_POLL_MS = 15_000;
+/** The longest worker timeout. */
+export const DEFAULT_MAX_STEP_MS = 3 * 60 * 60 * 1000;
+function sleep(ms, signal) {
+    if (signal?.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const done = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        signal?.addEventListener("abort", done, { once: true });
+    });
+}
+const TERMINAL = new Set([
+    "completed",
+    "failed",
+    "skipped",
+    "error",
+    "cancelled",
+]);
+function isTerminal(record) {
+    return TERMINAL.has(record.status);
+}
+/** The step nothing depends on. With several, the last declared wins. */
+export function sinkStepId(check) {
+    const depended = new Set(check.steps.flatMap((s) => s.after));
+    const sinks = check.steps.filter((s) => !depended.has(s.id));
+    const last = sinks[sinks.length - 1] ?? check.steps[check.steps.length - 1];
+    return last?.id ?? "run";
+}
+function completedOutputs(steps) {
+    const out = {};
+    for (const [id, record] of Object.entries(steps)) {
+        if (record.status === "completed")
+            out[id] = record.output;
+    }
+    return out;
+}
+function finish(check, partial, startedAt, controls) {
+    const result = {
+        key: check.key,
+        label: check.label,
+        kind: check.kind,
+        durationMs: Date.now() - startedAt,
+        ...partial,
+    };
+    controls.onEvent?.({ type: "check:end", checkKey: check.key, result });
+    return result;
+}
+async function runStatelessPrecheck(api, bundle, check, startedAt, controls) {
+    const stageId = precheckStageId(check.key);
+    controls.onEvent?.({ type: "step:start", checkKey: check.key, stepId: "run", immediate: false });
+    try {
+        const stage = await api.runPrecheckStage(bundle, stageId);
+        const verdict = precheckVerdict(stage.status);
+        const skipped = verdict === "skipped";
+        const reason = skipped
+            ? stage.missingFields?.length
+                ? `missing fields: ${stage.missingFields.join(", ")}`
+                : "stage skipped"
+            : undefined;
+        const step = {
+            status: "completed",
+            output: stage,
+            verdict,
+            startedAt,
+            finishedAt: Date.now(),
+            reason,
+        };
+        controls.onEvent?.({
+            type: "step:end",
+            checkKey: check.key,
+            stepId: "run",
+            status: "completed",
+            verdict,
+        });
+        return finish(check, {
+            status: skipped ? "skipped" : "completed",
+            verdict,
+            output: stage,
+            reason,
+            steps: { run: step },
+        }, startedAt, controls);
+    }
+    catch (error) {
+        const message = errorMessage(error);
+        controls.onEvent?.({
+            type: "step:end",
+            checkKey: check.key,
+            stepId: "run",
+            status: "error",
+            error: message,
+        });
+        return finish(check, {
+            status: "error",
+            error: message,
+            steps: { run: { status: "error", error: message, startedAt, finishedAt: Date.now() } },
+        }, startedAt, controls);
+    }
+}
+/** Run one check against a Harbor bundle without writing anything to the quest. */
+export async function executeStatelessCheck(api, bundle, check, options, controls) {
+    const startedAt = Date.now();
+    controls.onEvent?.({ type: "check:start", checkKey: check.key });
+    if (check.kind === "precheck" || isPrecheckKey(check.key)) {
+        return runStatelessPrecheck(api, bundle, check, startedAt, controls);
+    }
+    const steps = {};
+    for (const step of check.steps)
+        steps[step.id] = { status: "pending" };
+    const { signal } = controls;
+    const endStep = (stepId, record) => {
+        steps[stepId] = { ...steps[stepId], ...record, finishedAt: Date.now() };
+        controls.onEvent?.({
+            type: "step:end",
+            checkKey: check.key,
+            stepId,
+            status: record.status,
+            verdict: record.verdict,
+            error: record.error,
+            reason: record.reason,
+        });
+    };
+    const startStep = async (stepId) => {
+        const now = Date.now();
+        steps[stepId] = { status: "running", startedAt: now };
+        try {
+            const started = await api.startStep(bundle, check.key, stepId, completedOutputs(steps), options);
+            if (started.kind === "immediate") {
+                controls.onEvent?.({ type: "step:start", checkKey: check.key, stepId, immediate: true });
+                endStep(stepId, { status: "completed", output: started.output });
+                return;
+            }
+            steps[stepId] = { status: "running", startedAt: now, handle: started.handle };
+            controls.onEvent?.({
+                type: "step:start",
+                checkKey: check.key,
+                stepId,
+                handle: started.handle,
+                immediate: false,
+            });
+        }
+        catch (error) {
+            endStep(stepId, { status: "error", error: errorMessage(error) });
+        }
+    };
+    const pollStep = async (stepId) => {
+        const record = steps[stepId];
+        if (record.status !== "running" || !record.handle)
+            return;
+        const elapsed = Date.now() - (record.startedAt ?? Date.now());
+        if (elapsed >= controls.maxStepMs) {
+            // Keep the handle so `shipd checks status` / `cancel` still work on it.
+            endStep(stepId, {
+                status: "error",
+                error: `timed out after ${formatDuration(controls.maxStepMs)}`,
+            });
+            return;
+        }
+        try {
+            const status = await api.getStep(record.handle);
+            if (status.status === "running")
+                return;
+            if (status.status === "completed") {
+                endStep(stepId, { status: "completed", output: status.output, verdict: status.verdict });
+                return;
+            }
+            endStep(stepId, {
+                status: "failed",
+                error: status.error,
+                output: status.output,
+                verdict: status.verdict,
+            });
+        }
+        catch (error) {
+            endStep(stepId, { status: "error", error: errorMessage(error) });
+        }
+    };
+    const cancelInFlight = async () => {
+        const running = Object.entries(steps).filter(([, r]) => r.status === "running");
+        const leave = controls.onAbort?.() === "leave";
+        await Promise.all(running.map(async ([stepId, record]) => {
+            if (record.handle && !leave) {
+                try {
+                    await api.cancelStep(record.handle);
+                }
+                catch {
+                    // Best effort: the handle is still in the report for a manual cancel.
+                }
+            }
+            endStep(stepId, {
+                status: "cancelled",
+                reason: leave ? "interrupted; left running (handle kept in the report)" : "cancelled",
+            });
+        }));
+        for (const [stepId, record] of Object.entries(steps)) {
+            if (record.status === "pending")
+                endStep(stepId, { status: "skipped", reason: "cancelled" });
+        }
+    };
+    let cancelled = false;
+    while (true) {
+        if (signal?.aborted) {
+            cancelled = true;
+            await cancelInFlight();
+            break;
+        }
+        // Schedule: every pending step whose dependencies are all terminal.
+        const toStart = [];
+        let progressed = false;
+        for (const step of check.steps) {
+            if (steps[step.id].status !== "pending")
+                continue;
+            if (!step.after.every((dep) => steps[dep] && isTerminal(steps[dep])))
+                continue;
+            const broken = step.after.find((dep) => steps[dep].status !== "completed");
+            if (broken) {
+                endStep(step.id, { status: "skipped", reason: `upstream failed: ${broken}` });
+                progressed = true;
+                continue;
+            }
+            toStart.push(step.id);
+        }
+        if (toStart.length > 0) {
+            progressed = true;
+            await Promise.all(toStart.map(startStep));
+        }
+        const running = Object.keys(steps).filter((id) => steps[id].status === "running");
+        if (running.length > 0) {
+            await Promise.all(running.map(pollStep));
+            progressed = true;
+        }
+        const allTerminal = Object.values(steps).every(isTerminal);
+        if (allTerminal)
+            break;
+        if (!progressed) {
+            // Nothing can start and nothing is running: the plan references steps
+            // that do not exist. Report rather than spin forever.
+            for (const [stepId, record] of Object.entries(steps)) {
+                if (record.status === "pending") {
+                    endStep(stepId, { status: "error", error: "unresolvable step dependencies" });
+                }
+            }
+            break;
+        }
+        const stillRunning = Object.values(steps).some((r) => r.status === "running");
+        if (stillRunning)
+            await sleep(controls.pollMs, signal);
+    }
+    const sink = steps[sinkStepId(check)];
+    const entries = Object.entries(steps);
+    if (cancelled || entries.some(([, r]) => r.status === "cancelled")) {
+        return finish(check, { status: "cancelled", reason: "cancelled", steps }, startedAt, controls);
+    }
+    if (sink?.status === "completed") {
+        return finish(check, { status: "completed", verdict: sink.verdict, output: sink.output, steps }, startedAt, controls);
+    }
+    const failed = entries.find(([, r]) => r.status === "failed");
+    if (failed) {
+        const [stepId, record] = failed;
+        const prefix = check.steps.length > 1 ? `${stepId}: ` : "";
+        return finish(check, {
+            status: "failed",
+            verdict: record.verdict,
+            output: record.output,
+            error: `${prefix}${record.error ?? "step failed"}`,
+            steps,
+        }, startedAt, controls);
+    }
+    const errored = entries.find(([, r]) => r.status === "error");
+    const [stepId, record] = errored ?? ["", { status: "error" }];
+    const prefix = check.steps.length > 1 && stepId ? `${stepId}: ` : "";
+    return finish(check, { status: "error", error: `${prefix}${record.error ?? "step did not complete"}`, steps }, startedAt, controls);
+}
+/** Run one check live on an existing task; the quest writes its normal rows. */
+export async function executeLiveCheck(api, task, check, options, controls) {
+    const startedAt = Date.now();
+    controls.onEvent?.({ type: "check:start", checkKey: check.key });
+    const { signal } = controls;
+    const step = (record) => ({
+        trigger: { status: "pending", startedAt, finishedAt: Date.now(), ...record },
+    });
+    let started;
+    try {
+        started = await api.runLiveCheck(task.versionId, task.problemId, check.key, options);
+    }
+    catch (error) {
+        const message = errorMessage(error);
+        return finish(check, { status: "error", error: message, steps: step({ status: "error", error: message }) }, startedAt, controls);
+    }
+    controls.onEvent?.({
+        type: "live:started",
+        checkKey: check.key,
+        started: started.started,
+        detail: started.detail,
+    });
+    if (!started.started) {
+        const reason = started.detail ?? "the quest did not start this check";
+        return finish(check, { status: "skipped", reason, steps: step({ status: "skipped", reason }) }, startedAt, controls);
+    }
+    let nudged = false;
+    while (true) {
+        if (signal?.aborted) {
+            const reason = "interrupted; the check keeps running in the product";
+            return finish(check, { status: "cancelled", reason, steps: step({ status: "cancelled", reason }) }, startedAt, controls);
+        }
+        if (Date.now() - startedAt >= controls.maxStepMs) {
+            const error = `timed out after ${formatDuration(controls.maxStepMs)}`;
+            return finish(check, { status: "error", error, steps: step({ status: "error", error }) }, startedAt, controls);
+        }
+        let live;
+        try {
+            live = await api.getLiveCheck(task.versionId, check.key);
+        }
+        catch (error) {
+            const message = errorMessage(error);
+            return finish(check, { status: "error", error: message, steps: step({ status: "error", error: message }) }, startedAt, controls);
+        }
+        if (live.status === "running") {
+            if (live.nudgeSynthesis && !nudged) {
+                nudged = true;
+                controls.onEvent?.({ type: "live:nudge", checkKey: check.key });
+                try {
+                    await api.nudgeSynthesis(task.versionId);
+                }
+                catch {
+                    // The product's own scheduler will pick it up; keep polling.
+                }
+            }
+            await sleep(controls.pollMs, signal);
+            continue;
+        }
+        const output = live.output ?? undefined;
+        const jobIds = live.jobIds;
+        if (live.status === "completed") {
+            return finish(check, {
+                status: "completed",
+                verdict: live.verdict,
+                output,
+                jobIds,
+                steps: step({ status: "completed", output, verdict: live.verdict }),
+            }, startedAt, controls);
+        }
+        const error = live.error ?? "check failed";
+        return finish(check, {
+            status: "failed",
+            verdict: live.verdict,
+            output,
+            error,
+            jobIds,
+            steps: step({ status: "failed", output, verdict: live.verdict, error }),
+        }, startedAt, controls);
+    }
+}
+/** Run the selected checks concurrently and return one result per check. */
+export function runChecks(api, target, checks, options, controls) {
+    return Promise.all(checks.map((check) => target.kind === "harbor"
+        ? executeStatelessCheck(api, target.bundle, check, options, controls)
+        : executeLiveCheck(api, target.task, check, options, controls)));
+}

package/dist/quests.d.ts

@@ -0,0 +1,24 @@
+declare const VERSION: string, PACKAGE_NAME: string;
+export { VERSION, PACKAGE_NAME };
+export declare const DEFAULT_QUEST = "olympus";
+export declare function knownQuests(): string[];
+/** `SHIPD_<QUEST>_URL` override, or NODE_ENV=development → localhost. */
+export declare function questBaseUrl(quest: string): string;
+/** The page that mints the CLI token for the browser login flow. */
+export declare function questAuthUrl(quest: string): string;
+export interface QuestConfig {
+    convexUrl: string;
+    minCliVersion: string;
+    fetchedAt: string;
+}
+/** Load the quest's CLI config (cached 5 minutes) or fetch it from the quest. */
+export declare function questConfig(quest: string): Promise<QuestConfig>;
+/** The quest's Convex deployment URL, with `SHIPD_<QUEST>_CONVEX_URL` override. */
+export declare function questConvexUrl(quest: string): Promise<string>;
+/** Compare semver strings numerically (e.g. "0.10.0" > "0.9.0"). */
+export declare function semverGt(a: string, b: string): boolean;
+/**
+ * Warn (never block) when this CLI is below the quest's minimum or behind the
+ * latest npm release. Set SHIPD_NO_UPDATE_CHECK=1 to skip.
+ */
+export declare function checkVersion(quest?: string): Promise<void>;

package/dist/quests.js

@@ -0,0 +1,181 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+import { ensureShipdDir, shipdDir } from "./auth.js";
+import { UsageError } from "./errors.js";
+const require = createRequire(import.meta.url);
+const { version: VERSION, name: PACKAGE_NAME } = require("../package.json");
+export { VERSION, PACKAGE_NAME };
+// A quest entry is just a base URL. Everything else (the Convex deployment,
+// the minimum CLI version) comes from the quest's `/api/cli/config`.
+const REGISTRY = {
+    olympus: {
+        prod: "https://shipd.ai/quests/olympus",
+        dev: "http://localhost:3006/quests/olympus",
+    },
+};
+export const DEFAULT_QUEST = "olympus";
+export function knownQuests() {
+    return Object.keys(REGISTRY);
+}
+function envKey(quest, suffix) {
+    return `SHIPD_${quest.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_${suffix}`;
+}
+/** `SHIPD_<QUEST>_URL` override, or NODE_ENV=development → localhost. */
+export function questBaseUrl(quest) {
+    const override = process.env[envKey(quest, "URL")];
+    if (override)
+        return override.replace(/\/+$/, "");
+    const entry = REGISTRY[quest];
+    if (!entry) {
+        throw new UsageError(`Unknown quest "${quest}". Known quests: ${knownQuests().join(", ")}`);
+    }
+    return process.env.NODE_ENV === "development" ? entry.dev : entry.prod;
+}
+/** The page that mints the CLI token for the browser login flow. */
+export function questAuthUrl(quest) {
+    return `${questBaseUrl(quest)}/cli-auth`;
+}
+const CONFIG_TTL_MS = 5 * 60 * 1000;
+const VERSION_CACHE_TTL_MS = 12 * 60 * 60 * 1000;
+function configCachePath(quest) {
+    return resolve(shipdDir(), `config-${quest}.json`);
+}
+function isValidQuestConfig(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const candidate = value;
+    return (typeof candidate.convexUrl === "string" &&
+        candidate.convexUrl.length > 0 &&
+        typeof candidate.minCliVersion === "string" &&
+        candidate.minCliVersion.length > 0 &&
+        typeof candidate.fetchedAt === "string" &&
+        candidate.fetchedAt.length > 0);
+}
+function readFreshCache(path, ttlMs, isValid) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const cached = JSON.parse(readFileSync(path, "utf-8"));
+        if (!isValid(cached))
+            return null;
+        const age = Date.now() - new Date(cached.fetchedAt).getTime();
+        return age < ttlMs ? cached : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(path, value) {
+    try {
+        ensureShipdDir();
+        writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+    }
+    catch {
+        // A cache write failure must not break the command.
+    }
+}
+/** Load the quest's CLI config (cached 5 minutes) or fetch it from the quest. */
+export async function questConfig(quest) {
+    const cached = readFreshCache(configCachePath(quest), CONFIG_TTL_MS, isValidQuestConfig);
+    if (cached)
+        return cached;
+    const baseUrl = questBaseUrl(quest);
+    const configUrl = `${baseUrl}/api/cli/config`;
+    let res;
+    try {
+        res = await fetch(configUrl);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new UsageError(`Could not reach ${configUrl} (${detail}).\n` +
+            `  Set ${envKey(quest, "URL")} if the quest runs somewhere else.`);
+    }
+    if (!res.ok) {
+        throw new UsageError(`Could not fetch CLI config from ${configUrl} (HTTP ${res.status}).`);
+    }
+    const data = (await res.json());
+    if (typeof data.convexUrl !== "string" || !data.convexUrl) {
+        throw new UsageError(`CLI config from ${configUrl} is missing convexUrl.\n` +
+            `  Temporary workaround: set ${envKey(quest, "CONVEX_URL")} manually.`);
+    }
+    const config = {
+        convexUrl: data.convexUrl,
+        minCliVersion: typeof data.minCliVersion === "string" ? data.minCliVersion : "0.0.0",
+        fetchedAt: new Date().toISOString(),
+    };
+    writeCache(configCachePath(quest), config);
+    return config;
+}
+/** The quest's Convex deployment URL, with `SHIPD_<QUEST>_CONVEX_URL` override. */
+export async function questConvexUrl(quest) {
+    const override = process.env[envKey(quest, "CONVEX_URL")];
+    if (override)
+        return override;
+    return (await questConfig(quest)).convexUrl;
+}
+/** Compare semver strings numerically (e.g. "0.10.0" > "0.9.0"). */
+export function semverGt(a, b) {
+    const pa = a.split(".").map(Number);
+    const pb = b.split(".").map(Number);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        if ((pa[i] ?? 0) > (pb[i] ?? 0))
+            return true;
+        if ((pa[i] ?? 0) < (pb[i] ?? 0))
+            return false;
+    }
+    return false;
+}
+function isValidVersionCache(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const candidate = value;
+    return (typeof candidate.latestVersion === "string" &&
+        candidate.latestVersion.length > 0 &&
+        typeof candidate.fetchedAt === "string" &&
+        candidate.fetchedAt.length > 0);
+}
+async function latestPublishedVersion() {
+    const cachePath = resolve(shipdDir(), "version-check.json");
+    const cached = readFreshCache(cachePath, VERSION_CACHE_TTL_MS, isValidVersionCache);
+    if (cached)
+        return cached.latestVersion;
+    try {
+        const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME)}/latest`, {
+            headers: { Accept: "application/json" },
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        if (typeof data.version !== "string" || !data.version)
+            return null;
+        writeCache(cachePath, { latestVersion: data.version, fetchedAt: new Date().toISOString() });
+        return data.version;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Warn (never block) when this CLI is below the quest's minimum or behind the
+ * latest npm release. Set SHIPD_NO_UPDATE_CHECK=1 to skip.
+ */
+export async function checkVersion(quest = DEFAULT_QUEST) {
+    if (process.env.SHIPD_NO_UPDATE_CHECK === "1")
+        return;
+    const [configResult, latestResult] = await Promise.allSettled([
+        questConfig(quest),
+        latestPublishedVersion(),
+    ]);
+    if (configResult.status === "fulfilled" && semverGt(configResult.value.minCliVersion, VERSION)) {
+        console.error(`\n  CLI v${VERSION} is below the minimum required v${configResult.value.minCliVersion}` +
+            "\n  Run: shipd update\n");
+        return;
+    }
+    if (latestResult.status === "fulfilled" &&
+        latestResult.value &&
+        semverGt(latestResult.value, VERSION)) {
+        console.error(`\n  CLI v${VERSION} is behind the latest published v${latestResult.value}` +
+            "\n  Run: shipd update\n");
+    }
+}

package/dist/report.d.ts

@@ -0,0 +1,62 @@
+import type { Handle, PrecheckResult, Verdict } from "./contract.js";
+export type StepState = "pending" | "running" | "completed" | "failed" | "skipped" | "error" | "cancelled";
+export type StepRecord = {
+    status: StepState;
+    handle?: Handle;
+    output?: unknown;
+    verdict?: Verdict;
+    error?: string;
+    reason?: string;
+    startedAt?: number;
+    finishedAt?: number;
+};
+export type CheckStatus = "completed" | "failed" | "skipped" | "error" | "cancelled";
+export type CheckResult = {
+    key: string;
+    label: string;
+    kind: "precheck" | "dynamic";
+    status: CheckStatus;
+    verdict?: Verdict;
+    output?: unknown;
+    error?: string;
+    reason?: string;
+    durationMs: number;
+    steps: Record<string, StepRecord>;
+    /** Live modes only: the quest's job ids behind this check. */
+    jobIds?: Record<string, string>;
+};
+export type ReportMode = "harbor" | "harbor-create" | "task";
+export type ReportSource = {
+    dir?: string;
+    inputHash?: string;
+    problemId?: string;
+    versionId?: string;
+    title?: string;
+    url?: string;
+};
+export type Report = {
+    quest: string;
+    mode: ReportMode;
+    /** `explicit` = --check; `all` = --all. Skips are failures only for explicit selections. */
+    selection: "explicit" | "all";
+    source: ReportSource;
+    /** Live modes only: the task's page in the product (also in `source.url`). */
+    taskUrl?: string;
+    generatedAt: string;
+    checks: Record<string, CheckResult>;
+    prechecks: Record<string, PrecheckResult>;
+};
+export declare function modeLabel(mode: ReportMode): string;
+/** The precheck stage status, as the product spells it, mapped to a verdict. */
+export declare function precheckVerdict(status: string): Verdict;
+/** A one-line human detail for a check row. */
+export declare function checkDetail(check: CheckResult): string;
+export declare function renderTable(report: Report, opts?: {
+    color?: boolean;
+}): string;
+/**
+ * 0 when every run check passed or warned; 1 when any failed or errored (or
+ * an explicitly requested check was skipped); 3 when any check was cancelled.
+ */
+export declare function exitCodeFor(report: Report): number;
+export declare function writeReport(report: Report, path: string): Promise<string>;