@shipd-ai/cli 0.1.0

package/dist/contract.d.ts

@@ -0,0 +1,129 @@
+export type BundlePart = "metadata.repo" | "metadata.commit" | "instruction" | "dockerfile" | "testPatch" | "solutionPatch";
+export type HarborMetadata = {
+    problemTitle?: string;
+    category?: string;
+    language?: string;
+    difficulty?: string;
+    repositoryUrl?: string;
+    baseCommitHash?: string;
+    dockerImage?: string;
+    verifierTimeoutSec?: number;
+};
+export declare const HARBOR_FILES: readonly [{
+    readonly key: "taskToml";
+    readonly path: "task.toml";
+}, {
+    readonly key: "instructionMd";
+    readonly path: "instruction.md";
+}, {
+    readonly key: "dockerfile";
+    readonly path: "environment/Dockerfile";
+}, {
+    readonly key: "testPatch";
+    readonly path: "tests/test.patch";
+}, {
+    readonly key: "testSh";
+    readonly path: "tests/test.sh";
+}, {
+    readonly key: "solutionPatch";
+    readonly path: "solution/solution.patch";
+}, {
+    readonly key: "solveSh";
+    readonly path: "solution/solve.sh";
+}];
+export type HarborFileKey = (typeof HARBOR_FILES)[number]["key"];
+export type HarborFilePath = (typeof HARBOR_FILES)[number]["path"];
+export declare const HARBOR_FILE_PATHS: readonly HarborFilePath[];
+export type HarborBundle = {
+    dir: string;
+    metadata: HarborMetadata;
+    files: Partial<Record<HarborFileKey, string>>;
+};
+export type Step = {
+    id: string;
+    after: string[];
+};
+export type CheckDef = {
+    key: string;
+    label: string;
+    kind: "precheck" | "dynamic";
+    requires: BundlePart[];
+    steps: Step[];
+    notes?: string;
+};
+export type Catalog = {
+    quest: string;
+    checks: CheckDef[];
+};
+export type AdaptResult = {
+    fields: Record<string, unknown>;
+    draft: Record<string, unknown>;
+    checks: Record<string, {
+        eligible: boolean;
+        missing: BundlePart[];
+    }>;
+};
+export type Handle = {
+    quest: string;
+    checkKey: string;
+    stepId: string;
+    jobType: string;
+    modalFunctionCallId: string;
+    artifactPath: string;
+    startedAt: number;
+};
+export type StartStepResult = {
+    kind: "spawned";
+    handle: Handle;
+} | {
+    kind: "immediate";
+    output: Record<string, unknown>;
+};
+export type Verdict = "pass" | "fail" | "warning" | "error" | "pending" | "skipped" | string;
+export type StepStatus = {
+    status: "running";
+} | {
+    status: "completed";
+    output: Record<string, unknown>;
+    verdict: Verdict;
+} | {
+    status: "failed";
+    error: string;
+    output?: Record<string, unknown>;
+    verdict: Verdict;
+};
+export type Options = {
+    agentModel?: string;
+    reasoningEffort?: "low" | "medium" | "high" | "xhigh";
+};
+export type TaskRef = {
+    problemId: string;
+    versionId: string;
+    title: string;
+    status: string;
+    url: string;
+};
+export type LiveStatus = {
+    status: "running" | "completed" | "failed";
+    error?: string;
+    output: Record<string, unknown> | null;
+    verdict: Verdict;
+    jobIds: Record<string, string>;
+    nudgeSynthesis: boolean;
+};
+export type PrecheckResult = {
+    id: string;
+    name: string;
+    status: string;
+    missingFields?: string[];
+    checks: Array<{
+        id: string;
+        description?: string;
+        status: string;
+        message?: string;
+        details?: unknown;
+    }>;
+};
+export declare const PRECHECK_PREFIX = "precheck:";
+export declare function isPrecheckKey(key: string): boolean;
+export declare function precheckStageId(key: string): string;

package/dist/contract.js

@@ -0,0 +1,24 @@
+// Shared shapes of the quest contract. Every quest that supports the CLI
+// exposes `adhocChecks:*` Convex functions with these argument and return
+// types; the quest mirrors them with Convex validators. The CLI never imports
+// quest source, so this file is the only place the two sides meet.
+// The seven files read from a Harbor task directory. `key` is the wire
+// field (Convex object validators only accept identifier keys); `path` is
+// the on-disk location.
+export const HARBOR_FILES = [
+    { key: "taskToml", path: "task.toml" },
+    { key: "instructionMd", path: "instruction.md" },
+    { key: "dockerfile", path: "environment/Dockerfile" },
+    { key: "testPatch", path: "tests/test.patch" },
+    { key: "testSh", path: "tests/test.sh" },
+    { key: "solutionPatch", path: "solution/solution.patch" },
+    { key: "solveSh", path: "solution/solve.sh" },
+];
+export const HARBOR_FILE_PATHS = HARBOR_FILES.map((f) => f.path);
+export const PRECHECK_PREFIX = "precheck:";
+export function isPrecheckKey(key) {
+    return key.startsWith(PRECHECK_PREFIX);
+}
+export function precheckStageId(key) {
+    return key.slice(PRECHECK_PREFIX.length);
+}

package/dist/errors.d.ts

@@ -0,0 +1,20 @@
+export declare const EXIT_OK = 0;
+export declare const EXIT_CHECK_FAILED = 1;
+export declare const EXIT_USAGE = 2;
+export declare const EXIT_CANCELLED = 3;
+export declare class CliError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+export declare class UsageError extends CliError {
+    constructor(message: string);
+}
+export declare class AuthError extends CliError {
+    constructor(message: string);
+}
+export declare class BundleError extends CliError {
+    constructor(message: string);
+}
+/** Map any thrown value to the exit code the CLI should use for it. */
+export declare function exitCodeForError(error: unknown): number;
+export declare function errorMessage(error: unknown): string;

package/dist/errors.js

@@ -0,0 +1,49 @@
+// Exit codes: 0 every run check passed or warned; 1 a check failed or errored;
+// 2 usage, auth, or bundle error; 3 cancelled.
+export const EXIT_OK = 0;
+export const EXIT_CHECK_FAILED = 1;
+export const EXIT_USAGE = 2;
+export const EXIT_CANCELLED = 3;
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = EXIT_USAGE) {
+        super(message);
+        this.name = "CliError";
+        this.exitCode = exitCode;
+    }
+}
+export class UsageError extends CliError {
+    constructor(message) {
+        super(message, EXIT_USAGE);
+        this.name = "UsageError";
+    }
+}
+export class AuthError extends CliError {
+    constructor(message) {
+        super(message, EXIT_USAGE);
+        this.name = "AuthError";
+    }
+}
+export class BundleError extends CliError {
+    constructor(message) {
+        super(message, EXIT_USAGE);
+        this.name = "BundleError";
+    }
+}
+/** Map any thrown value to the exit code the CLI should use for it. */
+export function exitCodeForError(error) {
+    if (error instanceof CliError)
+        return error.exitCode;
+    const message = error instanceof Error ? error.message : String(error);
+    // Quest-side auth failures (Convex `Unauthorized` / `Forbidden: admin role
+    // required`) are usage errors from the CLI's point of view.
+    if (/\b(unauthorized|unauthenticated|forbidden|not authenticated)\b/i.test(message)) {
+        return EXIT_USAGE;
+    }
+    return EXIT_CHECK_FAILED;
+}
+export function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}

package/dist/format.d.ts

@@ -0,0 +1,19 @@
+export declare function stripAnsi(str: string): string;
+export type TableColumn = {
+    key: string;
+    label: string;
+    width?: number;
+};
+export type TableRow = Record<string, string | number | boolean | null | undefined>;
+/** Render rows as an aligned text table (two-space indent, same look as the Olympus CLI). */
+export declare function formatTable(rows: TableRow[], columns: TableColumn[]): string[];
+export declare function printTable(rows: TableRow[], columns: TableColumn[]): void;
+export declare function printJson(data: unknown): void;
+export declare function printKeyValue(pairs: [string, string | undefined | null][]): void;
+/** Status badge for terminal output; colors only when asked for. */
+export declare function statusBadge(status: string, color?: boolean): string;
+export declare function dim(text: string, color?: boolean): string;
+/** Collapse to one line and truncate with an ellipsis. */
+export declare function truncate(str: string, max: number): string;
+/** Compact human duration: 850ms, 5s, 2m10s, 3h, 1h05m. */
+export declare function formatDuration(ms: number): string;

package/dist/format.js

@@ -0,0 +1,93 @@
+// Minimal output formatting helpers. Every command also supports --json.
+const ESC = String.fromCharCode(27);
+const ANSI_RE = new RegExp(`${ESC}\\[[0-9;]*m`, "g");
+export function stripAnsi(str) {
+    return str.replace(ANSI_RE, "");
+}
+function padVisible(str, width) {
+    const needed = width - stripAnsi(str).length;
+    return needed > 0 ? str + " ".repeat(needed) : str;
+}
+/** Render rows as an aligned text table (two-space indent, same look as the Olympus CLI). */
+export function formatTable(rows, columns) {
+    if (rows.length === 0)
+        return ["  (no results)"];
+    const widths = columns.map((col) => {
+        const maxData = Math.max(...rows.map((r) => stripAnsi(String(r[col.key] ?? "")).length));
+        return col.width ?? Math.max(col.label.length, maxData);
+    });
+    const lines = [];
+    lines.push(`  ${columns.map((col, i) => col.label.padEnd(widths[i])).join("  ")}`);
+    lines.push(`  ${widths.map((w) => "─".repeat(w)).join("  ")}`);
+    for (const row of rows) {
+        lines.push(`  ${columns.map((col, i) => padVisible(String(row[col.key] ?? ""), widths[i])).join("  ")}`);
+    }
+    return lines.map((line) => line.trimEnd());
+}
+export function printTable(rows, columns) {
+    for (const line of formatTable(rows, columns))
+        console.log(line);
+}
+export function printJson(data) {
+    console.log(JSON.stringify(data, null, 2));
+}
+export function printKeyValue(pairs) {
+    const maxKey = Math.max(...pairs.map(([k]) => k.length));
+    for (const [key, value] of pairs) {
+        if (value !== undefined && value !== null) {
+            console.log(`  ${key.padEnd(maxKey)}  ${value}`);
+        }
+    }
+}
+const COLORS = {
+    green: "\x1b[32m",
+    red: "\x1b[31m",
+    yellow: "\x1b[33m",
+    gray: "\x1b[90m",
+    blue: "\x1b[34m",
+};
+const RESET = "\x1b[0m";
+const BADGES = {
+    completed: { icon: "✓", color: "green" },
+    pass: { icon: "✓", color: "green" },
+    running: { icon: "⟳", color: "yellow" },
+    pending: { icon: "○", color: "gray" },
+    failed: { icon: "✗", color: "red" },
+    fail: { icon: "✗", color: "red" },
+    error: { icon: "✗", color: "red" },
+    warning: { icon: "!", color: "yellow" },
+    skipped: { icon: "-", color: "gray" },
+    cancelled: { icon: "-", color: "gray" },
+    missing_fields: { icon: "○", color: "yellow" },
+};
+/** Status badge for terminal output; colors only when asked for. */
+export function statusBadge(status, color = false) {
+    const badge = BADGES[status] ?? { icon: "?", color: "gray" };
+    const icon = color ? `${COLORS[badge.color]}${badge.icon}${RESET}` : badge.icon;
+    return `${icon} ${status}`;
+}
+export function dim(text, color = false) {
+    return color ? `${COLORS.gray}${text}${RESET}` : text;
+}
+/** Collapse to one line and truncate with an ellipsis. */
+export function truncate(str, max) {
+    const oneLine = str.replace(/\n/g, " ").replace(/\s+/g, " ").trim();
+    if (oneLine.length <= max)
+        return oneLine;
+    return `${oneLine.slice(0, max - 3)}...`;
+}
+/** Compact human duration: 850ms, 5s, 2m10s, 3h, 1h05m. */
+export function formatDuration(ms) {
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    const totalSeconds = Math.round(ms / 1000);
+    if (totalSeconds < 60)
+        return `${totalSeconds}s`;
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    if (minutes < 60)
+        return seconds ? `${minutes}m${String(seconds).padStart(2, "0")}s` : `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    const rest = minutes % 60;
+    return rest ? `${hours}h${String(rest).padStart(2, "0")}m` : `${hours}h`;
+}

package/dist/harbor.d.ts

@@ -0,0 +1,25 @@
+import { type HarborBundle, type HarborMetadata } from "./contract.js";
+/** Total text the CLI will send to a quest. Well under Convex's argument limit. */
+export declare const MAX_BUNDLE_BYTES: number;
+/** Command-line overrides that win over `task.toml`. */
+export type MetadataOverrides = {
+    repo?: string;
+    commit?: string;
+    title?: string;
+    category?: string;
+    language?: string;
+    difficulty?: string;
+};
+export type HarborBundleWithHash = HarborBundle & {
+    inputHash: string;
+};
+/** Map `task.toml` tables onto `HarborMetadata`; overrides win. */
+export declare function metadataFromToml(toml: Record<string, unknown>, overrides?: MetadataOverrides): HarborMetadata;
+/** JSON with object keys sorted at every level, so equal content hashes equal. */
+export declare function canonicalJson(value: unknown): string;
+export declare function bundleInputHash(bundle: HarborBundle): string;
+/**
+ * Read a Harbor task directory. Only the seven known paths are read; anything
+ * else in the directory is ignored. `task.toml` must exist and parse.
+ */
+export declare function readHarborBundle(dir: string, overrides?: MetadataOverrides): Promise<HarborBundleWithHash>;

package/dist/harbor.js

@@ -0,0 +1,137 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parse as parseToml } from "smol-toml";
+import { HARBOR_FILE_PATHS, HARBOR_FILES, } from "./contract.js";
+import { BundleError } from "./errors.js";
+/** Total text the CLI will send to a quest. Well under Convex's argument limit. */
+export const MAX_BUNDLE_BYTES = 4 * 1024 * 1024;
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function str(table, key) {
+    const value = table?.[key];
+    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+function num(table, key) {
+    const value = table?.[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function nonEmpty(value) {
+    return value && value.trim().length > 0 ? value : undefined;
+}
+/** Map `task.toml` tables onto `HarborMetadata`; overrides win. */
+export function metadataFromToml(toml, overrides = {}) {
+    const metadata = isRecord(toml.metadata) ? toml.metadata : undefined;
+    const environment = isRecord(toml.environment) ? toml.environment : undefined;
+    const verifier = isRecord(toml.verifier) ? toml.verifier : undefined;
+    const out = {
+        problemTitle: nonEmpty(overrides.title) ?? str(metadata, "problem_title"),
+        category: nonEmpty(overrides.category) ?? str(metadata, "category"),
+        language: nonEmpty(overrides.language) ?? str(metadata, "language"),
+        difficulty: nonEmpty(overrides.difficulty) ?? str(metadata, "difficulty"),
+        repositoryUrl: nonEmpty(overrides.repo) ?? str(metadata, "repository_url"),
+        baseCommitHash: nonEmpty(overrides.commit) ?? str(metadata, "base_commit_hash"),
+        dockerImage: str(environment, "docker_image"),
+        verifierTimeoutSec: num(verifier, "timeout_sec"),
+    };
+    // Drop undefined keys so the wire payload and the hash only carry set fields.
+    for (const key of Object.keys(out)) {
+        if (out[key] === undefined)
+            delete out[key];
+    }
+    return out;
+}
+/** JSON with object keys sorted at every level, so equal content hashes equal. */
+export function canonicalJson(value) {
+    return JSON.stringify(sortKeys(value));
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (isRecord(value)) {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            const v = value[key];
+            if (v !== undefined)
+                out[key] = sortKeys(v);
+        }
+        return out;
+    }
+    return value;
+}
+export function bundleInputHash(bundle) {
+    const digest = createHash("sha256")
+        .update(canonicalJson({ metadata: bundle.metadata, files: bundle.files }))
+        .digest("hex");
+    return `sha256:${digest}`;
+}
+function formatMiB(bytes) {
+    return `${(bytes / (1024 * 1024)).toFixed(2)} MiB`;
+}
+async function fileSize(path) {
+    try {
+        // lstat, not stat: a bundle from an untrusted source could point a
+        // whitelisted name at any readable file via a symlink and have its
+        // contents sent to the quest.
+        const info = await lstat(path);
+        if (info.isSymbolicLink()) {
+            throw new BundleError(`${path} is a symlink; symlinked bundle files are not read.`);
+        }
+        return info.isFile() ? info.size : null;
+    }
+    catch (error) {
+        if (error instanceof BundleError)
+            throw error;
+        if (error.code === "ENOENT")
+            return null;
+        throw new BundleError(`Could not read ${path}: ${error.message}`);
+    }
+}
+/**
+ * Read a Harbor task directory. Only the seven known paths are read; anything
+ * else in the directory is ignored. `task.toml` must exist and parse.
+ */
+export async function readHarborBundle(dir, overrides = {}) {
+    const root = resolve(dir);
+    try {
+        const info = await stat(root);
+        if (!info.isDirectory())
+            throw new BundleError(`${root} is not a directory.`);
+    }
+    catch (error) {
+        if (error instanceof BundleError)
+            throw error;
+        throw new BundleError(`Harbor directory not found: ${root}`);
+    }
+    const present = [];
+    for (const { key, path } of HARBOR_FILES) {
+        const size = await fileSize(resolve(root, path));
+        if (size !== null)
+            present.push({ key, path, size });
+    }
+    if (!present.some((f) => f.key === "taskToml")) {
+        throw new BundleError(`task.toml not found in ${root}. Is this a Harbor task directory?`);
+    }
+    const totalBytes = present.reduce((sum, f) => sum + f.size, 0);
+    if (totalBytes > MAX_BUNDLE_BYTES) {
+        throw new BundleError(`Harbor bundle text is ${formatMiB(totalBytes)}; the cap is ${formatMiB(MAX_BUNDLE_BYTES)}. ` +
+            `Only ${HARBOR_FILE_PATHS.join(", ")} are read.`);
+    }
+    const files = {};
+    for (const { key, path } of present) {
+        files[key] = await readFile(resolve(root, path), "utf-8");
+    }
+    let toml;
+    try {
+        toml = parseToml(files.taskToml ?? "");
+    }
+    catch (error) {
+        throw new BundleError(`task.toml could not be parsed: ${error.message}`);
+    }
+    if (!isRecord(toml)) {
+        throw new BundleError("task.toml could not be parsed: expected a table at the top level.");
+    }
+    const bundle = { dir: root, metadata: metadataFromToml(toml, overrides), files };
+    return { ...bundle, inputHash: bundleInputHash(bundle) };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { defineCommand, runCommand, showUsage } from "citty";
+import { login, logout, whoami } from "./commands/auth.js";
+import checks from "./commands/checks.js";
+import { EXIT_USAGE, errorMessage, exitCodeForError } from "./errors.js";
+import { checkVersion, PACKAGE_NAME, VERSION } from "./quests.js";
+const update = defineCommand({
+    meta: { name: "update", description: "Update the CLI to the latest published version" },
+    args: {
+        version: { type: "string", description: "Target version (default: latest)" },
+    },
+    run: async ({ args }) => {
+        const spec = `${PACKAGE_NAME}@${args.version ?? "latest"}`;
+        console.log(`\n  Updating to ${spec}...`);
+        try {
+            execFileSync("npm", ["install", "-g", spec], { stdio: "inherit" });
+            console.log("\n  Updated successfully.");
+        }
+        catch {
+            console.error(`\n  Update failed. Try manually: npm install -g ${spec}`);
+            process.exitCode = 1;
+        }
+    },
+});
+const version = defineCommand({
+    meta: { name: "version", description: "Print the CLI version" },
+    run: () => {
+        console.log(VERSION);
+    },
+});
+const main = defineCommand({
+    meta: {
+        name: "shipd",
+        version: VERSION,
+        description: "Shipd admin CLI: run quest checks on Harbor tasks or existing tasks",
+    },
+    subCommands: { login, logout, whoami, checks, update, version },
+});
+async function run() {
+    const rawArgs = process.argv.slice(2);
+    if (rawArgs.length === 0 || rawArgs.includes("--help") || rawArgs.includes("-h")) {
+        await showUsageFor(rawArgs);
+        return;
+    }
+    if (rawArgs.length === 1 && (rawArgs[0] === "--version" || rawArgs[0] === "-v")) {
+        console.log(VERSION);
+        return;
+    }
+    // Warn about an outdated CLI without blocking the command.
+    void checkVersion(questFromArgs(rawArgs)).catch(() => { });
+    try {
+        await runCommand(main, { rawArgs });
+    }
+    catch (error) {
+        const name = error instanceof Error ? error.name : "";
+        if (name === "CLIError") {
+            // citty's own usage errors (unknown command, missing argument).
+            await showUsageFor(rawArgs);
+            console.error(`\n  Error: ${errorMessage(error)}\n`);
+            process.exitCode = EXIT_USAGE;
+            return;
+        }
+        console.error(`\n  Error: ${errorMessage(error)}\n`);
+        process.exitCode = exitCodeForError(error);
+    }
+}
+function questFromArgs(rawArgs) {
+    for (let i = 0; i < rawArgs.length; i++) {
+        const arg = rawArgs[i];
+        if (arg === "--quest")
+            return rawArgs[i + 1];
+        if (arg.startsWith("--quest="))
+            return arg.slice("--quest=".length);
+    }
+    return undefined;
+}
+async function showUsageFor(rawArgs) {
+    // Resolve the deepest sub-command named on the command line so `shipd checks run --help`
+    // prints the right usage.
+    let cmd = main;
+    let parent;
+    for (const arg of rawArgs) {
+        if (arg.startsWith("-"))
+            break;
+        const subs = (cmd.subCommands ?? {});
+        const next = subs[arg];
+        if (!next)
+            break;
+        parent = cmd;
+        cmd = next;
+    }
+    await showUsage(cmd, parent);
+}
+void run();

package/dist/plan.d.ts

@@ -0,0 +1,65 @@
+import type { QuestApi } from "./client.js";
+import { type CheckDef, type Handle, type HarborBundle, type Options, type TaskRef, type Verdict } from "./contract.js";
+import { type CheckResult, type StepRecord } from "./report.js";
+export declare const DEFAULT_POLL_MS = 15000;
+/** The longest worker timeout. */
+export declare const DEFAULT_MAX_STEP_MS: number;
+export type PlanEvent = {
+    type: "check:start";
+    checkKey: string;
+} | {
+    type: "step:start";
+    checkKey: string;
+    stepId: string;
+    handle?: Handle;
+    immediate: boolean;
+} | {
+    type: "step:end";
+    checkKey: string;
+    stepId: string;
+    status: StepRecord["status"];
+    verdict?: Verdict;
+    error?: string;
+    reason?: string;
+} | {
+    type: "live:started";
+    checkKey: string;
+    started: boolean;
+    detail?: string;
+} | {
+    type: "live:nudge";
+    checkKey: string;
+} | {
+    type: "check:end";
+    checkKey: string;
+    result: CheckResult;
+};
+export type RunControls = {
+    pollMs: number;
+    maxStepMs: number;
+    signal?: AbortSignal;
+    onEvent?: (event: PlanEvent) => void;
+    /**
+     * What an abort does to in-flight Modal steps. `"cancel"` (default)
+     * cancels them; `"leave"` keeps them running and only stops polling, so
+     * their handles survive in the report for `checks status` / `checks
+     * cancel` later. The interrupt handler flips this to `"leave"` when the
+     * user declines the cancel prompt.
+     */
+    onAbort?: () => "cancel" | "leave";
+};
+export type RunTarget = {
+    kind: "harbor";
+    bundle: HarborBundle;
+} | {
+    kind: "live";
+    task: TaskRef;
+};
+/** The step nothing depends on. With several, the last declared wins. */
+export declare function sinkStepId(check: CheckDef): string;
+/** Run one check against a Harbor bundle without writing anything to the quest. */
+export declare function executeStatelessCheck(api: QuestApi, bundle: HarborBundle, check: CheckDef, options: Options, controls: RunControls): Promise<CheckResult>;
+/** Run one check live on an existing task; the quest writes its normal rows. */
+export declare function executeLiveCheck(api: QuestApi, task: TaskRef, check: CheckDef, options: Options, controls: RunControls): Promise<CheckResult>;
+/** Run the selected checks concurrently and return one result per check. */
+export declare function runChecks(api: QuestApi, target: RunTarget, checks: CheckDef[], options: Options, controls: RunControls): Promise<CheckResult[]>;