@shipfoundry/cli 0.1.0

package/src/commands.mjs

@@ -0,0 +1,730 @@
+import { readFileSync } from "node:fs";
+
+import { isLoopbackOrigin } from "./config.mjs";
+import { apiFetch, newIdempotencyKey } from "./http.mjs";
+
+const TERMINAL_OPERATION_STATUSES = new Set([
+  "completed",
+  "failed",
+  "canceled",
+  "dead",
+  "skipped"
+]);
+
+function requireKey(context) {
+  if (!context.key) {
+    const error = new Error(
+      "No API key configured. Set SHIPFOUNDRY_API_KEY (or use --api-key). Keys are issued from the dashboard; the CLI never mints them."
+    );
+    error.code = "missing_key";
+    error.status = 401;
+    throw error;
+  }
+}
+
+export const commandSpecs = [
+  {
+    name: "doctor",
+    usage: "doctor [--json]",
+    summary:
+      "Show resolved host, credential status, and version compatibility without secrets.",
+    run: doctor
+  },
+  {
+    name: "auth status",
+    usage: "auth status [--json]",
+    summary: "Validate the configured credential and show its grant.",
+    run: (context) => apiGet(context, "/me")
+  },
+  {
+    name: "auth login",
+    usage: "auth login",
+    summary: "Explain the dashboard bootstrap path for issuing a key.",
+    run: authLogin
+  },
+  {
+    name: "projects list",
+    usage: "projects list [--json]",
+    summary: "List accessible projects.",
+    run: (context) => apiGet(context, "/projects")
+  },
+  {
+    name: "projects show",
+    usage: "projects show <project-id> [--json]",
+    summary: "Show one project.",
+    run: (context, [id]) =>
+      apiGet(context, `/projects/${need(id, "project-id")}`)
+  },
+  {
+    name: "projects create",
+    usage:
+      "projects create --name <name> [--description ...] [--domain ...] [--repo-url ...] [--idempotency-key ...] [--yes] [--json]",
+    summary: "Create a project (unrestricted credentials only).",
+    write: true,
+    run: (context, args, flags) => {
+      needYes(flags, "Creating a project");
+      return apiSend(context, "POST", "/projects", {
+        body: {
+          description: flags.description,
+          domain: flags.domain,
+          name: need(flags.name, "--name"),
+          repoUrl: flags["repo-url"]
+        },
+        idempotencyKey: flags["idempotency-key"] ?? newIdempotencyKey()
+      });
+    }
+  },
+  {
+    name: "projects update",
+    usage:
+      "projects update <project-id> [--name ...] [--summary ...] [--idempotency-key ...] [--yes] [--json]",
+    summary: "Rename or re-summarize a project.",
+    write: true,
+    run: (context, [id], flags) => {
+      needYes(flags, "Updating a project");
+      return apiSend(context, "PATCH", `/projects/${need(id, "project-id")}`, {
+        body: { name: flags.name, summary: flags.summary },
+        idempotencyKey: flags["idempotency-key"] ?? newIdempotencyKey()
+      });
+    }
+  },
+  {
+    name: "projects archive",
+    usage: "projects archive <project-id> [--restore] [--yes] [--json]",
+    summary: "Archive (or restore) a project with explicit confirmation.",
+    write: true,
+    run: (context, [id], flags) => {
+      needYes(flags, "Archiving a project");
+      return apiSend(
+        context,
+        "POST",
+        `/projects/${need(id, "project-id")}/archive`,
+        {
+          body: {
+            action: flags.restore ? "restore" : "archive",
+            confirmed: true
+          },
+          idempotencyKey: flags["idempotency-key"] ?? newIdempotencyKey()
+        }
+      );
+    }
+  },
+  {
+    name: "projects status",
+    usage: "projects status <project-id> [--json]",
+    summary: "Read setup readiness without triggering work.",
+    run: (context, [id]) =>
+      apiGet(context, `/projects/${need(id, "project-id")}/status`)
+  },
+  {
+    name: "projects context",
+    usage:
+      "projects context <project-id> [--file context.json --yes] [--idempotency-key <key>] [--json]",
+    summary:
+      "Read project context or submit evidence-based context from a JSON file.",
+    run: (context, [id], flags) => {
+      const path = `/projects/${need(id, "project-id")}/context`;
+      if (!flags.file) return apiGet(context, path);
+      needYes(flags, "Updating project context");
+      return apiSend(context, "PATCH", path, {
+        body: JSON.parse(readFileSync(flags.file, "utf8")),
+        idempotencyKey: flags["idempotency-key"] ?? newIdempotencyKey()
+      });
+    }
+  },
+  {
+    name: "projects activate",
+    usage: "projects activate <project-id> [--retry] [--yes] [--json]",
+    summary:
+      "Confirm the watchlist and start the first review. Use --retry for a failed review (may consume allowance).",
+    write: true,
+    run: (context, [id], flags) => {
+      needYes(flags, "Starting the first review");
+      return apiSend(
+        context,
+        "POST",
+        `/projects/${need(id, "project-id")}/activation`,
+        {
+          body: {
+            confirmed: true,
+            retryFailed: flags.retry === true ? true : undefined
+          },
+          idempotencyKey: flags["idempotency-key"] ?? newIdempotencyKey()
+        }
+      );
+    }
+  },
+  {
+    name: "reviews status",
+    usage: "reviews status <project-id> [--json]",
+    summary: "Read processing status.",
+    run: (context, [id]) =>
+      apiGet(context, `/projects/${need(id, "project-id")}/processing-status`)
+  },
+  {
+    name: "updates list",
+    usage:
+      "updates list --project <project-id> [--workspace active|ready|needs_input|checking|done|all] [--status ...] [--priority ...] [--query ...] [--limit ...] [--cursor ...] [--json]",
+    summary: "List recommendations with filters and pagination.",
+    run: (context, args, flags) =>
+      apiGet(context, `/projects/${need(flags.project, "--project")}/updates`, {
+        cursor: flags.cursor,
+        limit: flags.limit,
+        priority: flags.priority,
+        query: flags.query,
+        status: flags.status,
+        workspace: flags.workspace
+      })
+  },
+  {
+    name: "updates show",
+    usage: "updates show <update-id> [--json]",
+    summary: "Show one recommendation with verdict and evidence identity.",
+    run: (context, [id]) => apiGet(context, `/updates/${need(id, "update-id")}`)
+  },
+  {
+    name: "updates answer",
+    usage:
+      "updates answer <update-id> --question-hash <hash> --answer <text> [--yes] [--json]",
+    summary: "Answer the current version-bound question.",
+    write: true,
+    run: (context, [id], flags) => {
+      needYes(flags, "Answering a customer question");
+      return apiSend(
+        context,
+        "POST",
+        `/updates/${need(id, "update-id")}/answers`,
+        {
+          body: {
+            answer: need(flags.answer, "--answer"),
+            questionHash: need(flags["question-hash"], "--question-hash")
+          },
+          idempotencyKey: flags["idempotency-key"] ?? newIdempotencyKey()
+        }
+      );
+    }
+  },
+  {
+    name: "updates decide",
+    usage:
+      "updates decide <update-id> --decision keep_open|useful|not_useful|dismiss|reopen [--dismiss-reason ...] [--reason ...] [--yes] [--json]",
+    summary: "Record Keep Open, Useful, Not Useful, Dismiss, or Reopen.",
+    write: true,
+    run: (context, [id], flags) => {
+      needYes(flags, "Recording a decision");
+      return apiSend(
+        context,
+        "POST",
+        `/updates/${need(id, "update-id")}/decisions`,
+        {
+          body: {
+            decision: need(flags.decision, "--decision"),
+            dismissReason: flags["dismiss-reason"],
+            reason: flags.reason
+          },
+          idempotencyKey: flags["idempotency-key"] ?? newIdempotencyKey()
+        }
+      );
+    }
+  },
+  {
+    name: "briefs show",
+    usage: "briefs show <update-id> [--json]",
+    summary: "Read the stored brief. Never generates.",
+    run: (context, [id]) =>
+      apiGet(context, `/updates/${need(id, "update-id")}/brief`)
+  },
+  {
+    name: "briefs request",
+    usage:
+      "briefs request <update-id> [--mode if_missing_or_stale|regenerate] [--reason ...] [--idempotency-key ...] [--wait] [--timeout ...] [--yes] [--json]",
+    summary: "Explicitly request brief generation, optionally waiting.",
+    write: true,
+    run: requestBrief
+  },
+  {
+    name: "briefs mark-used",
+    usage:
+      "briefs mark-used <update-id> --brief-id <brief-id> [--yes] [--json]",
+    summary: "Record brief use without changing the outcome.",
+    write: true,
+    run: (context, [id], flags) => {
+      needYes(flags, "Marking a brief used");
+      return apiSend(
+        context,
+        "POST",
+        `/updates/${need(id, "update-id")}/brief-uses`,
+        {
+          body: { briefId: need(flags["brief-id"], "--brief-id") },
+          idempotencyKey: flags["idempotency-key"] ?? newIdempotencyKey()
+        }
+      );
+    }
+  },
+  {
+    name: "operations show",
+    usage: "operations show <operation-id> [--json]",
+    summary: "Read durable operation status.",
+    run: (context, [id]) =>
+      apiGet(context, `/operations/${need(id, "operation-id")}`)
+  },
+  {
+    name: "operations wait",
+    usage: "operations wait <operation-id> [--timeout ...] [--json]",
+    summary: "Poll until terminal or timeout; always reports the operation ID.",
+    run: waitOperation
+  },
+  {
+    name: "operations cancel",
+    usage: "operations cancel <operation-id> [--yes] [--json]",
+    summary: "Cancel a pending operation.",
+    write: true,
+    run: (context, [id], flags) => {
+      needYes(flags, "Canceling an operation");
+      return apiSend(
+        context,
+        "POST",
+        `/operations/${need(id, "operation-id")}/cancel`,
+        {
+          body: { confirmed: true },
+          idempotencyKey: flags["idempotency-key"] ?? newIdempotencyKey()
+        }
+      );
+    }
+  },
+  {
+    name: "handoff show",
+    usage:
+      "handoff show <update-id> [--format json|markdown] [--mode compact|full]",
+    summary: "Fetch the canonical execution packet.",
+    run: showHandoff
+  },
+  {
+    name: "outcomes record",
+    usage:
+      "outcomes record <update-id> --outcome <value> [--file outcome.json] [--summary ...] [--reason ...] [--idempotency-key ...] [--yes] [--json]",
+    summary: "Record evidence-bearing work outcomes.",
+    write: true,
+    run: recordOutcome
+  },
+  {
+    name: "watchlist list",
+    usage: "watchlist list --project <project-id> [--json]",
+    summary: "List tracked selections and suggestions.",
+    run: (context, args, flags) =>
+      apiGet(context, `/projects/${need(flags.project, "--project")}/watchlist`)
+  },
+  {
+    name: "watchlist add",
+    usage:
+      "watchlist add --project <project-id> --recommendation-ids <a,b> [--yes] [--json]",
+    summary: "Accept suggestions onto the watchlist.",
+    write: true,
+    run: (context, args, flags) => {
+      needYes(flags, "Adding to the watchlist");
+      return apiSend(
+        context,
+        "POST",
+        `/projects/${need(flags.project, "--project")}/watchlist`,
+        {
+          body: {
+            action: "add",
+            recommendationIds: splitIds(
+              need(flags["recommendation-ids"], "--recommendation-ids")
+            )
+          },
+          idempotencyKey: flags["idempotency-key"] ?? newIdempotencyKey()
+        }
+      );
+    }
+  },
+  {
+    name: "watchlist remove",
+    usage:
+      "watchlist remove --project <project-id> --selection-ids <a,b> [--yes] [--json]",
+    summary: "Stop tracking selections.",
+    write: true,
+    run: (context, args, flags) => {
+      needYes(flags, "Removing from the watchlist");
+      return apiSend(
+        context,
+        "DELETE",
+        `/projects/${need(flags.project, "--project")}/watchlist`,
+        {
+          body: {
+            selectionIds: splitIds(
+              need(flags["selection-ids"], "--selection-ids")
+            )
+          },
+          idempotencyKey: flags["idempotency-key"] ?? newIdempotencyKey()
+        }
+      );
+    }
+  },
+  {
+    name: "stack request",
+    usage:
+      "stack request --project <project-id> --name <tool> [--note ...] [--idempotency-key ...] --yes [--json]",
+    summary:
+      "Request missing coverage without enabling monitoring or paid work.",
+    write: true,
+    run: (context, args, flags) => {
+      needYes(flags, "Requesting stack coverage");
+      return apiSend(
+        context,
+        "POST",
+        `/projects/${need(flags.project, "--project")}/tracking-requests`,
+        {
+          body: {
+            name: need(flags.name, "--name"),
+            note: flags.note,
+            confirmed: true
+          },
+          idempotencyKey: flags["idempotency-key"] ?? newIdempotencyKey()
+        }
+      );
+    }
+  },
+  {
+    name: "stack resolve",
+    usage: "stack resolve --names <a,b> [--json]",
+    summary: "Resolve stack names to catalog entities.",
+    run: (context, args, flags) =>
+      apiSend(context, "POST", "/stack:resolve", {
+        body: { names: splitIds(need(flags.names, "--names")) }
+      })
+  },
+  {
+    name: "repositories list",
+    usage: "repositories list --project <project-id> [--json]",
+    summary:
+      "List authorized repositories, connection state and the browser setup link.",
+    run: (context, args, flags) =>
+      apiGet(
+        context,
+        `/projects/${need(flags.project, "--project")}/repository`
+      )
+  },
+  {
+    name: "repositories select",
+    usage:
+      "repositories select <repo-id> --project <project-id> [--idempotency-key <key>] --yes [--json]",
+    summary: "Select one already-authorized repository for the project.",
+    write: true,
+    run: (context, [id], flags) => {
+      needYes(flags, "Selecting a repository");
+      return apiSend(
+        context,
+        "POST",
+        `/projects/${need(flags.project, "--project")}/repository`,
+        {
+          body: { repoId: need(id, "repo-id") },
+          idempotencyKey: flags["idempotency-key"] ?? newIdempotencyKey()
+        }
+      );
+    }
+  },
+  {
+    name: "repositories disconnect",
+    usage:
+      "repositories disconnect <project-repository-id> --project <project-id> [--idempotency-key <key>] --yes [--json]",
+    summary: "Disconnect a project repository link without deleting history.",
+    write: true,
+    run: (context, [id], flags) => {
+      needYes(flags, "Disconnecting a repository");
+      return apiSend(
+        context,
+        "DELETE",
+        `/projects/${need(flags.project, "--project")}/repository`,
+        {
+          body: {
+            projectRepositoryId: need(id, "project-repository-id"),
+            confirmed: true
+          },
+          idempotencyKey: flags["idempotency-key"] ?? newIdempotencyKey()
+        }
+      );
+    }
+  },
+  {
+    name: "connections status",
+    usage: "connections status [--json]",
+    summary: "Read GitHub and Linear connection state.",
+    run: (context) => apiGet(context, "/connections")
+  },
+  {
+    name: "linear status",
+    usage: "linear status [--project <project-id>] [--json]",
+    summary: "Read Linear export target configuration.",
+    run: (context, args, flags) =>
+      apiGet(context, "/linear/status", { projectId: flags.project })
+  },
+  {
+    name: "linear preview",
+    usage: "linear preview --match <update-id> [--json]",
+    summary: "Preview the exact Linear payload with dedupe identity.",
+    run: (context, args, flags) =>
+      apiSend(context, "POST", "/linear/preview", {
+        body: { matchId: need(flags.match, "--match") }
+      })
+  },
+  {
+    name: "linear export",
+    usage: "linear export --match <update-id> [--force-new] [--yes] [--json]",
+    summary: "Create a Linear issue from the current brief.",
+    write: true,
+    run: (context, args, flags) => {
+      needYes(flags, "Creating a Linear issue");
+      return apiSend(context, "POST", "/linear/export", {
+        body: {
+          confirmed: true,
+          forceNew: flags["force-new"] === true,
+          matchId: need(flags.match, "--match")
+        },
+        idempotencyKey: flags["idempotency-key"] ?? newIdempotencyKey()
+      });
+    }
+  },
+  {
+    name: "account usage",
+    usage: "account usage [--json]",
+    summary: "Read plan, usage, and limits.",
+    run: (context) => apiGet(context, "/usage")
+  },
+  {
+    name: "account settings",
+    usage: "account settings [--json]",
+    summary: "Read supported account settings.",
+    run: (context) => apiGet(context, "/settings")
+  }
+];
+
+async function doctor(context) {
+  const probe = await apiGet(
+    { ...context, key: context.key ?? null },
+    "/me"
+  ).catch((error) => ({
+    authorized: false,
+    code: error.code ?? "unknown",
+    status: error.status ?? 0
+  }));
+  const contract = await apiFetch({
+    baseUrl: context.baseUrl,
+    key: null,
+    path: "/openapi"
+  })
+    .then((response) => response.data?.info?.version ?? null)
+    .catch(() => null);
+
+  return {
+    baseUrl: context.baseUrl,
+    credential: context.key
+      ? { configured: true, source: context.keySource }
+      : { configured: false, source: "none" },
+    identity: probe && probe.data ? { ok: true } : { ok: false },
+    local: isLoopbackOrigin(context.baseUrl),
+    openapi: contract
+  };
+}
+
+function authLogin(context) {
+  return {
+    bootstrap:
+      "Open /dashboard/settings/mcp on your ShipFoundry instance. Under Developer Keys, create a key with the projects and permissions you need, then export SHIPFOUNDRY_API_KEY and set SHIPFOUNDRY_BASE_URL to that instance origin.",
+    keyConfigured: Boolean(context.key),
+    note: "The CLI never mints keys and never persists secrets. Keys are account-scoped bearer credentials, not a development bypass."
+  };
+}
+
+async function apiGet(context, path, query) {
+  requireKey(context);
+  const response = await apiFetch({
+    baseUrl: context.baseUrl,
+    key: context.key,
+    method: "GET",
+    path,
+    query,
+    timeoutMs: context.timeoutMs
+  });
+
+  return response.data;
+}
+
+async function apiSend(context, method, path, { body, idempotencyKey } = {}) {
+  requireKey(context);
+  const response = await apiFetch({
+    baseUrl: context.baseUrl,
+    body,
+    idempotencyKey,
+    key: context.key,
+    method,
+    path,
+    timeoutMs: context.timeoutMs
+  });
+
+  return response.data;
+}
+
+async function requestBrief(context, [id], flags) {
+  needYes(flags, "Requesting paid brief generation");
+  const updateId = need(id, "update-id");
+  const result = await apiSend(
+    context,
+    "POST",
+    `/updates/${updateId}/brief-requests`,
+    {
+      body: {
+        confirmed: true,
+        mode: flags.mode ?? "if_missing_or_stale",
+        reason: flags.reason
+      },
+      idempotencyKey: flags["idempotency-key"] ?? newIdempotencyKey()
+    }
+  );
+
+  if (!flags.wait) {
+    return result;
+  }
+
+  const jobId = result?.data?.job?.id ?? result?.data?.brief?.id ?? null;
+
+  if (
+    !jobId ||
+    result?.data?.status === "already_current" ||
+    result?.data?.status === "blocked"
+  ) {
+    return result;
+  }
+
+  return waitOperation(context, [jobId], flags);
+}
+
+async function waitOperation(context, [id], flags) {
+  const operationId = need(id, "operation-id");
+  const timeoutMs = Number(flags.timeout ?? 120) * 1000;
+  const deadline = Date.now() + timeoutMs;
+  let last = null;
+
+  while (true) {
+    last = await apiGet(context, `/operations/${operationId}`);
+
+    if (TERMINAL_OPERATION_STATUSES.has(last?.data?.status)) {
+      return last;
+    }
+
+    if (Date.now() >= deadline) {
+      const error = new Error(
+        `Timed out waiting for operation ${operationId}. It may still be running; poll operations show ${operationId} to resume.`
+      );
+      error.code = "wait_timeout";
+      error.status = 0;
+      error.operationId = operationId;
+      error.last = last;
+      throw error;
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 5000));
+  }
+}
+
+async function showHandoff(context, [id], flags) {
+  const updateId = need(id, "update-id");
+  const result = await apiGet(context, `/updates/${updateId}/packet`, {
+    mode: flags.mode ?? "compact"
+  });
+
+  if ((flags.format ?? "json") === "markdown") {
+    const markdown = extractMarkdown(result);
+
+    if (markdown) {
+      return { markdown };
+    }
+  }
+
+  return result;
+}
+
+function markdownField(value) {
+  if (value === null || value === undefined || Object(value) === value) {
+    return null;
+  }
+
+  const text = String(value);
+  return text.trim() ? text : null;
+}
+
+function extractMarkdown(result) {
+  if (!result || Object(result) !== result) {
+    return null;
+  }
+
+  const data = Object(result.data) === result.data ? result.data : null;
+
+  if (!data) {
+    return null;
+  }
+
+  const packet = Object(data.packet) === data.packet ? data.packet : null;
+
+  return (
+    markdownField(packet?.markdown) ??
+    markdownField(data.markdown) ??
+    markdownField(data.prompt) ??
+    markdownField(packet?.prompt)
+  );
+}
+
+async function recordOutcome(context, [id], flags) {
+  needYes(flags, "Recording a work outcome");
+  const updateId = need(id, "update-id");
+  let fileEvidence = {};
+
+  if (flags.file) {
+    fileEvidence = JSON.parse(readFileSync(flags.file, "utf8"));
+  }
+
+  return apiSend(context, "POST", `/updates/${updateId}/outcomes`, {
+    body: {
+      commitUrl: fileEvidence.commitUrl,
+      filesChanged: fileEvidence.filesChanged ?? [],
+      filesInspected: fileEvidence.filesInspected ?? [],
+      outcome: need(flags.outcome ?? fileEvidence.outcome, "--outcome"),
+      prUrl: fileEvidence.prUrl,
+      reason: flags.reason ?? fileEvidence.reason,
+      summary: flags.summary ?? fileEvidence.summary,
+      validationNotes: fileEvidence.validationNotes ?? []
+    },
+    idempotencyKey: flags["idempotency-key"] ?? newIdempotencyKey()
+  });
+}
+
+function need(value, label) {
+  if (value === undefined || value === null || value === "") {
+    const error = new Error(`Missing required ${label}.`);
+    error.code = "usage";
+    error.status = 400;
+    throw error;
+  }
+
+  return value;
+}
+
+function needYes(flags, action) {
+  if (flags.yes === true) {
+    return;
+  }
+
+  const error = new Error(
+    `${action} requires explicit intent. Re-run with --yes to confirm this write.`
+  );
+  error.code = "confirmation_required";
+  error.status = 400;
+  throw error;
+}
+
+function splitIds(raw) {
+  return String(raw)
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}