@shipd-ai/cli 0.1.0

package/README.md

@@ -0,0 +1,133 @@
+# Shipd CLI (`@shipd-ai/cli`)
+
+`shipd` is the admin command line for Shipd quests. Point it at a Harbor task
+directory (or an existing task) and it runs the quest's checks on the quest's
+own infrastructure, then returns the same structured output the product shows.
+Olympus is the first quest; every quest that implements the small
+`adhocChecks:*` contract works the same way.
+
+Admins only: every quest entrypoint checks the caller's effective admin role.
+
+## Install and log in
+
+Admin docs, the supported checks, and a copy-paste setup prompt for coding agents live at https://shipd.ai/admin/cli (admins only; direct link to the prompt: https://shipd.ai/admin/cli#agent-setup-prompt).
+
+```bash
+npm install -g @shipd-ai/cli
+shipd login            # opens https://shipd.ai/quests/olympus/cli-auth
+shipd whoami
+```
+
+`login` opens the token page in your browser; paste the token back into the
+terminal. It is stored at `~/.shipd/credentials.json` (mode 0600). The token is
+personal: never commit it, never pass it on a command line. `shipd logout`
+deletes it.
+
+## Three input modes
+
+| Mode | Command | What happens | Writes to production |
+| --- | --- | --- | --- |
+| Harbor, stateless (default) | `shipd checks run <harbor-dir> --check …` | Adapts the bundle, runs the checks on the quest's infrastructure, returns their normal output. | Nothing. |
+| Harbor, create | `shipd checks run <harbor-dir> --create --check …` | Turns the bundle into a real draft task under your account (every authoring guard applies), then runs the checks live on it. | A draft task + version and the normal job rows. Not submitted for review. |
+| Existing task | `shipd checks run --task <problemId> --check …` | Runs the checks live on the task's latest version. | The normal job rows; the version's visible results are re-pointed. |
+
+Both live modes print a `Writes to production:` line before anything is
+dispatched; `--create` prints the new task URL as soon as the draft exists.
+Checks cost real compute: use `--dry-run` first and confirm `--all` with a
+human when an agent is driving.
+
+## Harbor layout
+
+Only these paths are read; everything else in the directory is ignored.
+
+| Path | Used as | Required for |
+| --- | --- | --- |
+| `task.toml` | `[metadata]` (`problem_title`, `category`, `language`, `difficulty`, `repository_url`, `base_commit_hash`), `[environment].docker_image`, `[verifier].timeout_sec` | all |
+| `instruction.md` | task description | description-bearing checks |
+| `environment/Dockerfile` | sandbox image | sandbox checks without `docker_image` |
+| `tests/test.patch` | test patch | every check except `verifyBuild` |
+| `tests/test.sh` | carried for future native runs | unused by v1 checks |
+| `solution/solution.patch` | solution patch | solution-bearing checks |
+| `solution/solve.sh` | carried for future native runs | unused by v1 checks |
+
+A missing or unparsable `task.toml` is a bundle error (exit 2). The seven
+files may total at most 4 MiB. `--repo`, `--commit`, `--title`, `--category`,
+`--language` and `--difficulty` override the `task.toml` metadata, which is how
+a non-Olympus bundle fills in what it lacks.
+
+## Commands
+
+```bash
+shipd checks list --quest olympus
+shipd checks run ./task --all --dry-run                  # eligibility + adapted inputs, spends nothing
+shipd checks run ./task --check verifyBuild,descriptionQuality
+shipd checks run ./task --all --json --out report.json
+shipd checks run ./task --create --check autoReview      # creates a draft, runs live
+shipd checks run --task <problemId> --check scopeGate     # runs live on an existing task
+shipd checks run ./task --check verifyBuild --no-wait     # prints handles as JSON lines
+shipd checks status '<handle json>'                      # or: shipd checks status report.json
+shipd checks cancel '<handle json>'                      # or: shipd checks cancel report.json
+```
+
+`run` options: `--quest` (default `olympus`), `--check a,b` or `--all`,
+`--dry-run`, `--no-wait`, `--json`, `--out <file>`, metadata overrides,
+`--model` and `--effort low|medium|high|xhigh` (honored where the production
+dispatcher honors them), `--poll <seconds>` (default 15), `--timeout <minutes>`
+per step (default 180, the longest worker timeout).
+
+Checks whose required bundle parts are missing are reported as `skipped` with
+the missing list. With `--all` that is informational; with `--check` it fails
+the run. Multi-step checks (for example `autoReview`) run as a step plan the
+quest describes: independent steps in parallel, each later step fed the
+earlier outputs, a failed step marking its dependents `skipped: upstream
+failed`. Prechecks (`precheck:<stage>`) run synchronously.
+
+Ctrl-C asks whether to cancel the in-flight steps; a second Ctrl-C leaves them
+running. Handles stay in the JSON report, so `checks status` and
+`checks cancel` keep working on them afterwards.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | every run check passed or warned |
+| 1 | a check failed or errored (or an explicitly requested check was skipped) |
+| 2 | usage, auth, or bundle error (nothing was dispatched) |
+| 3 | cancelled |
+
+## Report
+
+`--json` and `--out` produce the same document: `quest`, `mode`, `source`
+(bundle directory and `inputHash`, or the task ids, title and URL), a top-level
+`taskUrl` in live modes, one entry per
+check with `status`, `verdict`, `output`, `error`, `durationMs`, and `steps`
+(each step's handle and output), plus `prechecks` keyed by stage id.
+
+## Environment
+
+| Variable | Effect |
+| --- | --- |
+| `SHIPD_<QUEST>_URL` | Override the quest's base URL (for example `SHIPD_OLYMPUS_URL`). |
+| `SHIPD_<QUEST>_CONVEX_URL` | Skip `/api/cli/config` and talk to this Convex deployment. |
+| `SHIPD_HOME` | Credentials and caches directory (default `~/.shipd`). |
+| `SHIPD_NO_UPDATE_CHECK=1` | Skip the version check. |
+| `NODE_ENV=development` | Use the localhost quest URLs. |
+
+## Developer notes
+
+```bash
+pnpm --dir packages/shipd-cli typecheck
+pnpm --dir packages/shipd-cli test
+pnpm --dir packages/shipd-cli build
+pnpm --dir packages/shipd-cli cli checks list --quest olympus          # runs src/ with tsx
+NODE_ENV=development pnpm --dir packages/shipd-cli cli checks list     # against a local quest
+```
+
+The CLI contains no quest logic. It calls `adhocChecks:*` by name through
+Convex's `anyApi`; the shared argument and return shapes live in
+`src/contract.ts`, and each quest mirrors them with validators. The plan
+executor (`src/plan.ts`) and bundle reader (`src/harbor.ts`) are unit-tested
+against a fake quest and a fixture bundle in `test/`.
+
+Publishing: `pnpm --dir packages/shipd-cli build && npm publish --access public`
+from an account in the `@shipd-ai` npm org.

package/dist/auth.d.ts

@@ -0,0 +1,26 @@
+export declare function shipdDir(): string;
+export interface DecodedIdentity {
+    sub: string;
+    email: string;
+    username: string;
+    name: string;
+    picture: string;
+    exp: number;
+}
+/**
+ * Decode the JWT payload without verifying the signature. The quest's Convex
+ * deployment verifies it on every request; the CLI only reads the payload for
+ * display (name, email) and the local expiry check.
+ */
+export declare function decodeJwtPayload(token: string): DecodedIdentity;
+export declare function ensureShipdDir(): string;
+export declare function saveCredentials(token: string): DecodedIdentity;
+export declare function loadCredentials(): {
+    token: string;
+    identity: DecodedIdentity;
+} | null;
+export declare function clearCredentials(): boolean;
+export declare function requireAuth(): {
+    token: string;
+    identity: DecodedIdentity;
+};

package/dist/auth.js

@@ -0,0 +1,75 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { AuthError } from "./errors.js";
+export function shipdDir() {
+    return resolve(process.env.SHIPD_HOME ?? resolve(homedir(), ".shipd"));
+}
+function credentialsPath() {
+    return resolve(shipdDir(), "credentials.json");
+}
+/**
+ * Decode the JWT payload without verifying the signature. The quest's Convex
+ * deployment verifies it on every request; the CLI only reads the payload for
+ * display (name, email) and the local expiry check.
+ */
+export function decodeJwtPayload(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+        throw new AuthError("Invalid token: expected a JWT with three segments.");
+    }
+    const payload = Buffer.from(parts[1], "base64url").toString("utf-8");
+    const decoded = JSON.parse(payload);
+    if (typeof decoded.exp !== "number" || typeof decoded.sub !== "string") {
+        throw new AuthError("Invalid token: payload is missing sub or exp.");
+    }
+    return decoded;
+}
+export function ensureShipdDir() {
+    const dir = shipdDir();
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    return dir;
+}
+export function saveCredentials(token) {
+    const identity = decodeJwtPayload(token);
+    const expiresAt = new Date(identity.exp * 1000).toISOString();
+    ensureShipdDir();
+    const data = { token, expiresAt };
+    writeFileSync(credentialsPath(), `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+    return identity;
+}
+export function loadCredentials() {
+    const path = credentialsPath();
+    if (!existsSync(path))
+        return null;
+    try {
+        const stored = JSON.parse(readFileSync(path, "utf-8"));
+        if (!stored.token)
+            return null;
+        const identity = decodeJwtPayload(stored.token);
+        const now = Math.floor(Date.now() / 1000);
+        if (identity.exp <= now)
+            return null;
+        return { token: stored.token, identity };
+    }
+    catch {
+        return null;
+    }
+}
+export function clearCredentials() {
+    const path = credentialsPath();
+    if (existsSync(path)) {
+        unlinkSync(path);
+        return true;
+    }
+    return false;
+}
+export function requireAuth() {
+    const creds = loadCredentials();
+    if (!creds) {
+        throw new AuthError("Not logged in or the token has expired. Run: shipd login");
+    }
+    return creds;
+}

package/dist/client.d.ts

@@ -0,0 +1,51 @@
+import type { AdaptResult, Catalog, Handle, HarborBundle, LiveStatus, Options, PrecheckResult, StartStepResult, StepStatus, TaskRef } from "./contract.js";
+/**
+ * Everything the plan executor needs from a quest. `QuestClient` implements it
+ * over Convex; tests implement it with a fake.
+ */
+export interface QuestApi {
+    readonly quest: string;
+    listChecks(): Promise<Catalog>;
+    adapt(bundle: HarborBundle): Promise<AdaptResult>;
+    runPrecheckStage(bundle: HarborBundle, stageId: string): Promise<PrecheckResult>;
+    startStep(bundle: HarborBundle, checkKey: string, stepId: string, priorOutputs: Record<string, unknown>, options?: Options): Promise<StartStepResult>;
+    getStep(handle: Handle): Promise<StepStatus>;
+    cancelStep(handle: Handle): Promise<{
+        cancelled: boolean;
+    }>;
+    fetchArtifact(handle: Handle, key: string): Promise<string | null>;
+    createFromHarbor(bundle: HarborBundle): Promise<TaskRef>;
+    resolveTask(problemId: string): Promise<TaskRef | null>;
+    runLiveCheck(versionId: string, problemId: string, checkKey: string, options?: Options): Promise<{
+        started: boolean;
+        detail?: string;
+    }>;
+    getLiveCheck(versionId: string, checkKey: string): Promise<LiveStatus>;
+    nudgeSynthesis(versionId: string): Promise<null>;
+}
+/** The bundle as sent over the wire: `dir`, `metadata`, `files` and nothing else. */
+export declare function toWireBundle(bundle: HarborBundle): HarborBundle;
+export declare class QuestClient implements QuestApi {
+    readonly quest: string;
+    private readonly convex;
+    constructor(quest: string, convexUrl: string, token: string);
+    listChecks(): Promise<Catalog>;
+    adapt(bundle: HarborBundle): Promise<AdaptResult>;
+    runPrecheckStage(bundle: HarborBundle, stageId: string): Promise<PrecheckResult>;
+    startStep(bundle: HarborBundle, checkKey: string, stepId: string, priorOutputs: Record<string, unknown>, options?: Options): Promise<StartStepResult>;
+    getStep(handle: Handle): Promise<StepStatus>;
+    cancelStep(handle: Handle): Promise<{
+        cancelled: boolean;
+    }>;
+    fetchArtifact(handle: Handle, key: string): Promise<string | null>;
+    createFromHarbor(bundle: HarborBundle): Promise<TaskRef>;
+    resolveTask(problemId: string): Promise<TaskRef | null>;
+    runLiveCheck(versionId: string, problemId: string, checkKey: string, options?: Options): Promise<{
+        started: boolean;
+        detail?: string;
+    }>;
+    getLiveCheck(versionId: string, checkKey: string): Promise<LiveStatus>;
+    nudgeSynthesis(versionId: string): Promise<null>;
+}
+/** Build an authenticated client for a quest, or throw an AuthError/UsageError. */
+export declare function connectQuest(quest: string): Promise<QuestClient>;

package/dist/client.js

@@ -0,0 +1,70 @@
+import { ConvexHttpClient } from "convex/browser";
+import { anyApi } from "convex/server";
+import { requireAuth } from "./auth.js";
+import { questConvexUrl } from "./quests.js";
+/** The bundle as sent over the wire: `dir`, `metadata`, `files` and nothing else. */
+export function toWireBundle(bundle) {
+    return { dir: bundle.dir, metadata: bundle.metadata, files: bundle.files };
+}
+function withOptions(args, options) {
+    return options && Object.keys(options).length > 0 ? { ...args, options } : args;
+}
+// Functions are addressed by name through `anyApi` so the CLI has no
+// dependency on any quest's generated API at typecheck time.
+const fns = anyApi.adhocChecks;
+export class QuestClient {
+    quest;
+    convex;
+    constructor(quest, convexUrl, token) {
+        this.quest = quest;
+        this.convex = new ConvexHttpClient(convexUrl);
+        this.convex.setAuth(token);
+    }
+    listChecks() {
+        return this.convex.query(fns.listChecks, {});
+    }
+    adapt(bundle) {
+        return this.convex.query(fns.adapt, { bundle: toWireBundle(bundle) });
+    }
+    runPrecheckStage(bundle, stageId) {
+        return this.convex.action(fns.runPrecheckStage, {
+            bundle: toWireBundle(bundle),
+            stageId,
+        });
+    }
+    startStep(bundle, checkKey, stepId, priorOutputs, options) {
+        return this.convex.action(fns.startStep, withOptions({ bundle: toWireBundle(bundle), checkKey, stepId, priorOutputs }, options));
+    }
+    getStep(handle) {
+        return this.convex.action(fns.getStep, { handle });
+    }
+    cancelStep(handle) {
+        return this.convex.action(fns.cancelStep, { handle });
+    }
+    fetchArtifact(handle, key) {
+        return this.convex.action(fns.fetchArtifact, { handle, key });
+    }
+    createFromHarbor(bundle) {
+        return this.convex.action(fns.createFromHarbor, {
+            bundle: toWireBundle(bundle),
+        });
+    }
+    resolveTask(problemId) {
+        return this.convex.query(fns.resolveTask, { problemId });
+    }
+    runLiveCheck(versionId, problemId, checkKey, options) {
+        return this.convex.action(fns.runLiveCheck, withOptions({ versionId, problemId, checkKey }, options));
+    }
+    getLiveCheck(versionId, checkKey) {
+        return this.convex.query(fns.getLiveCheck, { versionId, checkKey });
+    }
+    nudgeSynthesis(versionId) {
+        return this.convex.action(fns.nudgeSynthesis, { versionId });
+    }
+}
+/** Build an authenticated client for a quest, or throw an AuthError/UsageError. */
+export async function connectQuest(quest) {
+    const { token } = requireAuth();
+    const convexUrl = await questConvexUrl(quest);
+    return new QuestClient(quest, convexUrl, token);
+}

package/dist/commands/auth.d.ts

@@ -0,0 +1,22 @@
+export declare const login: import("citty").CommandDef<{
+    readonly token: {
+        readonly type: "string";
+        readonly description: "Paste the token directly instead of prompting";
+    };
+    readonly "no-browser": {
+        readonly type: "boolean";
+        readonly description: "Print the login URL instead of opening it";
+    };
+    readonly quest: {
+        readonly type: "string";
+        readonly description: "Quest whose login page to open (default: olympus)";
+        readonly default: "olympus";
+    };
+}>;
+export declare const logout: import("citty").CommandDef<import("citty").ArgsDef>;
+export declare const whoami: import("citty").CommandDef<{
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output as JSON";
+    };
+}>;

package/dist/commands/auth.js

@@ -0,0 +1,109 @@
+import { exec, execFile } from "node:child_process";
+import { createInterface } from "node:readline";
+import { defineCommand } from "citty";
+import { clearCredentials, loadCredentials, saveCredentials } from "../auth.js";
+import { UsageError } from "../errors.js";
+import { printJson } from "../format.js";
+import { DEFAULT_QUEST, questAuthUrl } from "../quests.js";
+function openBrowser(url) {
+    if (process.platform === "win32") {
+        // `start` is a cmd.exe built-in, not a standalone executable.
+        exec(`start "" "${url.replace(/"/g, '\\"')}"`, () => { });
+    }
+    else {
+        const cmd = process.platform === "darwin" ? "open" : "xdg-open";
+        execFile(cmd, [url], () => { });
+    }
+}
+function prompt(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+const questArg = {
+    quest: {
+        type: "string",
+        description: `Quest whose login page to open (default: ${DEFAULT_QUEST})`,
+        default: DEFAULT_QUEST,
+    },
+};
+export const login = defineCommand({
+    meta: { name: "login", description: "Sign in via the browser and store the CLI token" },
+    args: {
+        ...questArg,
+        token: { type: "string", description: "Paste the token directly instead of prompting" },
+        "no-browser": { type: "boolean", description: "Print the login URL instead of opening it" },
+    },
+    run: async ({ args }) => {
+        const authUrl = questAuthUrl(args.quest);
+        let token = args.token?.trim();
+        if (!token) {
+            if (args["no-browser"]) {
+                console.log(`\n  Open this page and copy the token:\n  ${authUrl}\n`);
+            }
+            else {
+                console.log(`\n  Opening browser...\n  ${authUrl}\n`);
+                openBrowser(authUrl);
+            }
+            token = await prompt("  Paste your token: ");
+        }
+        if (!token)
+            throw new UsageError("No token provided.");
+        const identity = saveCredentials(token);
+        const expiresAt = new Date(identity.exp * 1000).toLocaleDateString();
+        console.log(`\n  Logged in as ${identity.name || identity.email || identity.sub}`);
+        if (identity.username)
+            console.log(`  Username:  @${identity.username}`);
+        console.log(`  Expires:   ${expiresAt}\n`);
+    },
+});
+export const logout = defineCommand({
+    meta: { name: "logout", description: "Delete the stored CLI token" },
+    run: async () => {
+        const removed = clearCredentials();
+        console.log(removed ? "  Logged out." : "  Not logged in.");
+    },
+});
+export const whoami = defineCommand({
+    meta: { name: "whoami", description: "Show who the stored token belongs to" },
+    args: {
+        json: { type: "boolean", description: "Output as JSON" },
+    },
+    run: async ({ args }) => {
+        const creds = loadCredentials();
+        if (!creds) {
+            if (args.json) {
+                printJson({ authenticated: false });
+            }
+            else {
+                console.log("  Not logged in. Run: shipd login");
+            }
+            process.exitCode = 2;
+            return;
+        }
+        const { identity } = creds;
+        const expiresAt = new Date(identity.exp * 1000);
+        const daysLeft = Math.ceil((expiresAt.getTime() - Date.now()) / (1000 * 60 * 60 * 24));
+        if (args.json) {
+            printJson({
+                authenticated: true,
+                userId: identity.sub,
+                email: identity.email,
+                username: identity.username,
+                name: identity.name,
+                expiresAt: expiresAt.toISOString(),
+                daysLeft,
+            });
+            return;
+        }
+        console.log(`  Logged in as ${identity.name || identity.email || identity.sub}`);
+        if (identity.username)
+            console.log(`  Username:  @${identity.username}`);
+        console.log(`  User ID:   ${identity.sub}`);
+        console.log(`  Expires:   ${expiresAt.toLocaleDateString()} (${daysLeft}d)`);
+    },
+});

package/dist/commands/checks.d.ts

@@ -0,0 +1,12 @@
+import { type Catalog, type CheckDef, type TaskRef } from "../contract.js";
+import { type Report } from "../report.js";
+/** "a + b → c": steps grouped by dependency depth. */
+export declare function formatSteps(check: CheckDef): string;
+export declare function selectChecks(catalog: Catalog, explicit: string | undefined, all: boolean): {
+    checks: CheckDef[];
+    selection: Report["selection"];
+};
+/** Lines for `--dry-run --task`: what would be dispatched, without dispatching. */
+export declare function dryRunTaskLines(task: TaskRef, checks: CheckDef[]): string[];
+declare const _default: import("citty").CommandDef<import("citty").ArgsDef>;
+export default _default;