@shipfoundry/cli 0.1.0

package/src/config.mjs

@@ -0,0 +1,102 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+export function resolveBaseUrl(explicit) {
+  const raw =
+    explicit || process.env.SHIPFOUNDRY_BASE_URL || readProfileBaseUrl();
+  if (!raw) {
+    throw new Error(
+      "Set --base-url, SHIPFOUNDRY_BASE_URL, or a profile baseUrl before making requests."
+    );
+  }
+  const url = new URL(raw);
+  if (
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash ||
+    url.pathname !== "/"
+  ) {
+    throw new Error(
+      "Base URL must be an origin without credentials, a path, query, or fragment."
+    );
+  }
+
+  if (url.protocol === "http:" && !LOOPBACK_HOSTS.has(url.hostname)) {
+    throw new Error(
+      `Refusing plain HTTP for non-loopback host ${url.hostname}. Use HTTPS or a loopback development endpoint.`
+    );
+  }
+
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error(`Unsupported base URL protocol: ${url.protocol}.`);
+  }
+
+  return url.origin;
+}
+
+export function isLoopbackOrigin(origin) {
+  try {
+    return LOOPBACK_HOSTS.has(new URL(origin).hostname);
+  } catch {
+    return false;
+  }
+}
+
+export function resolveApiKey(explicit) {
+  return (
+    explicit ||
+    process.env.SHIPFOUNDRY_API_KEY ||
+    process.env.SHIPFOUNDRY_MCP_TOKEN ||
+    null
+  );
+}
+
+export function keySource(explicit) {
+  if (explicit) {
+    return "option";
+  }
+
+  if (process.env.SHIPFOUNDRY_API_KEY) {
+    return "SHIPFOUNDRY_API_KEY";
+  }
+
+  if (process.env.SHIPFOUNDRY_MCP_TOKEN) {
+    return "SHIPFOUNDRY_MCP_TOKEN (legacy)";
+  }
+
+  return "none";
+}
+
+function profilePath() {
+  const dir = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(dir, "shipfoundry", "config.json");
+}
+
+function readProfileBaseUrl() {
+  try {
+    const path = profilePath();
+
+    if (!existsSync(path)) {
+      return null;
+    }
+
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    const candidate =
+      parsed && Object(parsed) === parsed && parsed.baseUrl
+        ? String(parsed.baseUrl)
+        : null;
+
+    if (!candidate) {
+      return null;
+    }
+
+    new URL(candidate);
+    return candidate;
+  } catch {
+    return null;
+  }
+}

package/src/http.mjs

@@ -0,0 +1,143 @@
+export const EXIT = {
+  OK: 0,
+  USAGE: 2,
+  AUTH: 3,
+  FORBIDDEN: 4,
+  NOT_FOUND: 5,
+  CONFLICT: 6,
+  QUOTA: 7,
+  TRANSIENT: 8,
+  TIMEOUT: 9
+};
+
+const STATUS_TO_EXIT = new Map([
+  [400, EXIT.USAGE],
+  [401, EXIT.AUTH],
+  [403, EXIT.FORBIDDEN],
+  [404, EXIT.NOT_FOUND],
+  [409, EXIT.CONFLICT],
+  [429, EXIT.QUOTA],
+  [502, EXIT.TRANSIENT],
+  [503, EXIT.TRANSIENT]
+]);
+
+export class CliApiError extends Error {
+  constructor({ code, detail, message, recovery, requestId, status }) {
+    super(message);
+    this.code = code;
+    this.detail = detail;
+    this.recovery = recovery;
+    this.requestId = requestId;
+    this.status = status;
+  }
+}
+
+export function exitForStatus(status) {
+  return STATUS_TO_EXIT.get(status) ?? EXIT.TRANSIENT;
+}
+
+export async function apiFetch({
+  baseUrl,
+  key,
+  method = "GET",
+  path,
+  query,
+  body,
+  idempotencyKey,
+  timeoutMs = 30000
+}) {
+  let url = `${baseUrl}/api/v1${path}`;
+
+  if (query) {
+    const params = new URLSearchParams();
+    for (const [name, value] of Object.entries(query)) {
+      if (value !== undefined && value !== null && value !== "") {
+        params.append(name, String(value));
+      }
+    }
+    const suffix = params.toString();
+    if (suffix) {
+      url += `?${suffix}`;
+    }
+  }
+
+  const headers = { Accept: "application/json" };
+
+  if (key) {
+    headers.Authorization = `Bearer ${key}`;
+  }
+
+  let payload;
+  if (body !== undefined) {
+    headers["Content-Type"] = "application/json";
+    payload = JSON.stringify(body);
+  }
+
+  if (idempotencyKey) {
+    headers["X-Idempotency-Key"] = idempotencyKey;
+  }
+
+  const response = await fetch(url, {
+    body: payload,
+    headers,
+    method,
+    redirect: "manual",
+    signal: AbortSignal.timeout(timeoutMs)
+  });
+
+  if (response.status >= 300 && response.status < 400) {
+    const location = response.headers.get("location");
+    throw new CliApiError({
+      code: "unsafe_redirect",
+      detail: { location },
+      message: `Refusing redirect to ${location ?? "unknown target"} while credentials are configured.`,
+      recovery: "Check SHIPFOUNDRY_BASE_URL for typos or trailing paths.",
+      requestId: response.headers.get("x-request-id"),
+      status: 0
+    });
+  }
+
+  const requestId = response.headers.get("x-request-id");
+  const text = await response.text();
+  const parsed = parseJsonBody(text);
+
+  if (!response.ok) {
+    const error = parsed?.error ?? {};
+    throw new CliApiError({
+      code: error.code ?? `http_${response.status}`,
+      detail: parsed?.data ?? null,
+      message: error.message ?? `Request failed with HTTP ${response.status}.`,
+      recovery:
+        error.recovery ?? "Retry once; report the request ID if it persists.",
+      requestId: error.requestId ?? requestId,
+      status: response.status
+    });
+  }
+
+  return { data: parsed, requestId };
+}
+
+function parseJsonBody(text) {
+  if (!text.trim()) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new CliApiError({
+      code: "invalid_response",
+      detail: null,
+      message: "Server returned a non-JSON response.",
+      recovery:
+        "Check SHIPFOUNDRY_BASE_URL points at a ShipFoundry application.",
+      requestId: null,
+      status: 0
+    });
+  }
+}
+
+export function newIdempotencyKey() {
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}

package/src/main.mjs

@@ -0,0 +1,236 @@
+import { keySource, resolveApiKey, resolveBaseUrl } from "./config.mjs";
+import { commandSpecs } from "./commands.mjs";
+import { EXIT } from "./http.mjs";
+import { emit, emitError, exitCodeFor } from "./output.mjs";
+
+const GLOBAL_FLAGS = new Set([
+  "json",
+  "base-url",
+  "api-key",
+  "yes",
+  "timeout",
+  "help"
+]);
+
+export async function main(argv) {
+  const { positionals, flags } = parseArgs(argv);
+
+  if (flags.help || positionals.length === 0) {
+    printHelp();
+    return EXIT.OK;
+  }
+
+  const command = matchCommand(positionals);
+
+  if (!command) {
+    emitError(
+      {
+        code: "usage",
+        message: `Unknown command: ${positionals.join(" ")}.`,
+        recovery: "Run shipfoundry --help."
+      },
+      { json: flags.json === true }
+    );
+    return EXIT.USAGE;
+  }
+
+  const json = flags.json === true;
+  let baseUrl;
+
+  try {
+    baseUrl =
+      command.name === "auth login"
+        ? undefined
+        : resolveBaseUrl(flags["base-url"]);
+  } catch (error) {
+    emitError(
+      {
+        code: "usage",
+        message: error.message,
+        recovery: "Set a valid SHIPFOUNDRY_BASE_URL."
+      },
+      { json }
+    );
+    return EXIT.USAGE;
+  }
+
+  const key = resolveApiKey(flags["api-key"]);
+  const context = {
+    baseUrl,
+    key,
+    keySource: keySource(flags["api-key"]),
+    timeoutMs: Number(flags.timeout ?? 30) * 1000
+  };
+
+  try {
+    const result = await command.run(context, command.rest, flags);
+    emit(result, { json });
+    return EXIT.OK;
+  } catch (error) {
+    emitError(error, { json });
+
+    if (error.code === "wait_timeout") {
+      return EXIT.TIMEOUT;
+    }
+
+    if (
+      error.code === "usage" ||
+      error.code === "confirmation_required" ||
+      error.code === "invalid_response"
+    ) {
+      return EXIT.USAGE;
+    }
+
+    return exitCodeFor(error);
+  }
+}
+
+function parseArgs(argv) {
+  const positionals = [];
+  const flags = {};
+  let onlyPositionals = false;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (onlyPositionals) {
+      positionals.push(token);
+      continue;
+    }
+
+    if (token === "--") {
+      onlyPositionals = true;
+      continue;
+    }
+
+    if (token.startsWith("--")) {
+      const [name, inline] = token.slice(2).split("=", 2);
+      const normalized = name.toLowerCase();
+
+      if (!GLOBAL_FLAGS.has(normalized) && !isCommandFlag(normalized)) {
+        const error = new Error(`Unknown option: --${name}.`);
+        error.code = "usage";
+        throw error;
+      }
+
+      if (inline !== undefined) {
+        flags[normalized] = coerceFlag(normalized, inline);
+      } else if (
+        normalized === "yes" ||
+        normalized === "json" ||
+        normalized === "help" ||
+        normalized === "force-new" ||
+        normalized === "restore" ||
+        normalized === "retry" ||
+        normalized === "wait"
+      ) {
+        flags[normalized] = true;
+      } else {
+        index += 1;
+        flags[normalized] = coerceFlag(normalized, argv[index]);
+      }
+
+      continue;
+    }
+
+    positionals.push(token);
+  }
+
+  return { flags, positionals };
+}
+
+function isCommandFlag(name) {
+  return [
+    "name",
+    "description",
+    "domain",
+    "repo-url",
+    "summary",
+    "project",
+    "workspace",
+    "status",
+    "priority",
+    "query",
+    "limit",
+    "cursor",
+    "question-hash",
+    "answer",
+    "decision",
+    "dismiss-reason",
+    "reason",
+    "mode",
+    "brief-id",
+    "recommendation-ids",
+    "selection-ids",
+    "names",
+    "match",
+    "force-new",
+    "restore",
+    "retry",
+    "wait",
+    "idempotency-key",
+    "file",
+    "outcome",
+    "format"
+  ].includes(name);
+}
+
+function coerceFlag(name, raw) {
+  if (raw === undefined) {
+    const error = new Error(`Missing value for --${name}.`);
+    error.code = "usage";
+    throw error;
+  }
+
+  if (name === "timeout" || name === "limit") {
+    const parsed = Number(raw);
+
+    if (!Number.isFinite(parsed)) {
+      const error = new Error(`Invalid numeric value for --${name}.`);
+      error.code = "usage";
+      throw error;
+    }
+
+    return parsed;
+  }
+
+  return raw;
+}
+
+function matchCommand(positionals) {
+  for (let length = 2; length >= 1; length -= 1) {
+    const head = positionals.slice(0, length).join(" ");
+    const spec = commandSpecs.find((candidate) => candidate.name === head);
+
+    if (spec) {
+      return { ...spec, rest: positionals.slice(length) };
+    }
+  }
+
+  return null;
+}
+
+function printHelp() {
+  const lines = [
+    "shipfoundry — operate ShipFoundry without the dashboard.",
+    "",
+    "Usage: shipfoundry <command> [args] [--json] [--base-url ...] [--api-key ...] [--yes]",
+    "",
+    "Global: --json (structured stdout, diagnostics on stderr), --yes (confirm writes),",
+    "  --base-url, --api-key, --timeout seconds. Reads never prompt. Writes require --yes.",
+    "  Config: SHIPFOUNDRY_API_KEY (or legacy SHIPFOUNDRY_MCP_TOKEN), SHIPFOUNDRY_BASE_URL.",
+    "  Key setup is dashboard-bootstrapped; see `shipfoundry auth login`.",
+    "",
+    "Commands:"
+  ];
+
+  for (const spec of commandSpecs) {
+    lines.push(`  ${spec.usage}\n    ${spec.summary}`);
+  }
+
+  lines.push(
+    "",
+    "Exit codes: 0 ok, 2 usage, 3 auth, 4 forbidden, 5 not found, 6 conflict, 7 quota, 8 transient, 9 wait timeout."
+  );
+  process.stdout.write(`${lines.join("\n")}\n`);
+}

package/src/output.mjs

@@ -0,0 +1,140 @@
+import { EXIT } from "./http.mjs";
+
+export function emit(data, { json }) {
+  if (json) {
+    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    return;
+  }
+
+  process.stdout.write(`${summarize(data)}\n`);
+}
+
+export function emitError(error, { json }) {
+  const payload = {
+    code: error.code ?? "unknown",
+    message: error.message,
+    recovery: error.recovery ?? null,
+    requestId: error.requestId ?? null
+  };
+
+  if (json) {
+    process.stderr.write(
+      `${JSON.stringify({ error: payload, ok: false }, null, 2)}\n`
+    );
+    return;
+  }
+
+  const suffix = payload.requestId ? ` (request ${payload.requestId})` : "";
+  const hint = payload.recovery ? `\nRecovery: ${payload.recovery}` : "";
+  process.stderr.write(
+    `Error [${payload.code}]: ${payload.message}${suffix}${hint}\n`
+  );
+}
+
+export function exitCodeFor(error) {
+  if (Number.isInteger(error.status) && error.status > 0) {
+    return exitForKnownStatus(error.status);
+  }
+
+  return EXIT.TRANSIENT;
+}
+
+function exitForKnownStatus(status) {
+  if (status === 400) {
+    return EXIT.USAGE;
+  }
+
+  if (status === 401) {
+    return EXIT.AUTH;
+  }
+
+  if (status === 403) {
+    return EXIT.FORBIDDEN;
+  }
+
+  if (status === 404) {
+    return EXIT.NOT_FOUND;
+  }
+
+  if (status === 409) {
+    return EXIT.CONFLICT;
+  }
+
+  if (status === 429) {
+    return EXIT.QUOTA;
+  }
+
+  return EXIT.TRANSIENT;
+}
+
+function isRecord(value) {
+  return Object(value) === value && !Array.isArray(value);
+}
+
+function summarize(data) {
+  if (data === null || data === undefined) {
+    return "No result.";
+  }
+
+  if (!isRecord(data) && !Array.isArray(data)) {
+    return String(data);
+  }
+
+  const envelope = data;
+  const raw = isRecord(envelope) ? envelope.message : null;
+  const message =
+    raw === null || raw === undefined || Object(raw) === raw
+      ? null
+      : String(raw);
+  const payload = isRecord(envelope) ? (envelope.data ?? envelope) : envelope;
+
+  if (message) {
+    const detail = summarizeValue(payload);
+    return detail ? `${message}\n${detail}` : message;
+  }
+
+  return summarizeValue(payload);
+}
+
+function summarizeValue(value) {
+  if (value === null || value === undefined) {
+    return "";
+  }
+
+  if (Array.isArray(value)) {
+    return value
+      .slice(0, 20)
+      .map((item) => `- ${oneLine(item)}`)
+      .join("\n");
+  }
+
+  if (isRecord(value)) {
+    const lines = [];
+    for (const [name, entry] of Object.entries(value).slice(0, 12)) {
+      lines.push(`${name}: ${oneLine(entry)}`);
+    }
+    return lines.join("\n");
+  }
+
+  return String(value);
+}
+
+function oneLine(value) {
+  if (value === null || value === undefined) {
+    return "none";
+  }
+
+  if (Array.isArray(value)) {
+    return `${value.length} item(s)`;
+  }
+
+  if (isRecord(value)) {
+    const name = value.name ?? value.title ?? value.id ?? value.status;
+    return name === undefined || isRecord(name) || Array.isArray(name)
+      ? "object"
+      : String(name);
+  }
+
+  const text = String(value);
+  return text.length > 120 ? `${text.slice(0, 117)}...` : text;
+}