@elmundi/ship-cli 0.8.1 → 0.11.2

package/lib/detect.mjs

@@ -2,58 +2,201 @@ import fs from "node:fs";
 import path from "node:path";
 
 /**
+ * @typedef {Object} AgentTarget
+ * @property {string} id
+ * @property {string} label
+ * @property {string[]} paths
+ * @property {number} confidence  0..1 — 1 for a definitive marker, 0.5 for directory-only.
+ */
+
+/**
+ * Detect agent integration targets in a repository.
+ *
+ * Each detector looks for marker files or directories that uniquely identify a
+ * given agent configuration (per RFC-0004 "Detect (signals)"). Returned list is
+ * sorted by `confidence` descending so callers (init, doctor, stack emit) can
+ * pick the strongest signals first.
+ *
  * @param {string} cwd
- * @returns {{ id: string; label: string; paths: string[] }[]}
+ * @returns {AgentTarget[]}
  */
 export function detectAgentTargets(cwd) {
-  /** @type {{ id: string; label: string; paths: string[] }[]} */
+  const exists = (...p) => fs.existsSync(path.join(cwd, ...p));
+  const abs = (...p) => path.join(cwd, ...p);
+
+  /** @type {AgentTarget[]} */
   const targets = [];
 
-  const cursorDir = path.join(cwd, ".cursor");
-  const cursorRules = path.join(cursorDir, "rules");
-  if (fs.existsSync(cursorDir)) {
+  if (exists(".cursor")) {
     targets.push({
       id: "cursor",
       label: "Cursor (`.cursor/` present)",
-      paths: [path.join(cursorRules, "ship-methodology-api.mdc")],
+      paths: [abs(".cursor", "rules", "ship-artifacts-protocol.mdc")],
+      confidence: exists(".cursor", "rules") ? 1 : 0.8,
     });
   }
 
-  const agents = path.join(cwd, "AGENTS.md");
-  if (fs.existsSync(agents)) {
+  if (exists("AGENTS.md")) {
     targets.push({
       id: "agents-md",
       label: "OpenAI Codex / generic `AGENTS.md`",
-      paths: [agents],
+      paths: [abs("AGENTS.md")],
+      confidence: 1,
     });
   }
 
-  const claude = path.join(cwd, "CLAUDE.md");
-  if (fs.existsSync(claude)) {
+  if (exists("CLAUDE.md")) {
     targets.push({
       id: "claude-md",
       label: "Claude Code `CLAUDE.md`",
-      paths: [claude],
+      paths: [abs("CLAUDE.md")],
+      confidence: 1,
     });
   }
 
-  const codexDir = path.join(cwd, ".codex");
-  if (fs.existsSync(codexDir)) {
+  if (exists(".codex")) {
     targets.push({
       id: "codex",
       label: "Codex config dir (`.codex/`)",
-      paths: [path.join(codexDir, "SHIP_API.md")],
+      paths: [abs(".codex", "SHIP_API.md")],
+      confidence: 0.8,
     });
   }
 
-  const copilot = path.join(cwd, ".github", "copilot-instructions.md");
-  if (fs.existsSync(copilot)) {
+  if (exists(".github", "copilot-instructions.md")) {
     targets.push({
       id: "copilot",
       label: "GitHub Copilot instructions",
-      paths: [copilot],
+      paths: [abs(".github", "copilot-instructions.md")],
+      confidence: 1,
+    });
+  }
+
+  const aiderSignals = [".aider.conf.yml", "AIDER.md", ".aider"];
+  const aiderHit = aiderSignals.find((p) => exists(p));
+  if (aiderHit) {
+    targets.push({
+      id: "aider",
+      label: "Aider (`.aider.conf.yml` present)",
+      paths: [abs("AIDER.md")],
+      confidence: aiderHit === ".aider" ? 0.5 : 1,
+    });
+  }
+
+  const clineSignals = [".clinerules", ".rooignore"];
+  const clineHit = clineSignals.find((p) => exists(p));
+  if (clineHit) {
+    targets.push({
+      id: "cline",
+      label: "Cline/Roo (`.clinerules`)",
+      paths: [abs(".clinerules")],
+      confidence: 1,
+    });
+  }
+
+  const continueSignals = [
+    path.join(".continue", "config.json"),
+    path.join(".continue", "config.yaml"),
+    ".continue",
+  ];
+  const continueHit = continueSignals.find((p) => exists(p));
+  if (continueHit) {
+    targets.push({
+      id: "continue",
+      label: "Continue.dev (`.continue/`)",
+      paths: [abs(".continue", "ship.md")],
+      confidence: continueHit === ".continue" ? 0.5 : 1,
     });
   }
 
-  return targets;
+  if (exists(".windsurfrules")) {
+    targets.push({
+      id: "windsurf",
+      label: "Windsurf (`.windsurfrules`)",
+      paths: [abs(".windsurfrules")],
+      confidence: 1,
+    });
+  }
+
+  const zedSignals = [path.join(".zed", "settings.json"), ".zed"];
+  const zedHit = zedSignals.find((p) => exists(p));
+  if (zedHit) {
+    targets.push({
+      id: "zed",
+      label: "Zed AI (`.zed/`)",
+      paths: [abs(".zed", "ship.md")],
+      confidence: zedHit === ".zed" ? 0.5 : 1,
+    });
+  }
+
+  const geminiSignals = ["GEMINI.md", ".gemini"];
+  const geminiHit = geminiSignals.find((p) => exists(p));
+  if (geminiHit) {
+    targets.push({
+      id: "gemini",
+      label: "Gemini CLI (`GEMINI.md`)",
+      paths: [abs("GEMINI.md")],
+      confidence: geminiHit === ".gemini" ? 0.5 : 1,
+    });
+  }
+
+  if (exists(".opencode")) {
+    targets.push({
+      id: "opencode",
+      label: "OpenCode (`.opencode/`)",
+      paths: [abs(".opencode", "ship.md")],
+      confidence: 0.5,
+    });
+  }
+
+  if (exists(".cursor", "environments.json")) {
+    targets.push({
+      id: "cursor-cloud",
+      label: "Cursor Cloud Agent env",
+      paths: [abs(".cursor", "environments.json")],
+      confidence: 1,
+    });
+  }
+
+  return targets.sort((a, b) => b.confidence - a.confidence);
+}
+
+/**
+ * Fixed catalog of agent ids + default paths used when the user forces
+ * an agent via `--agents` and the marker is missing.
+ * Keeping this in sync with detectAgentTargets() is intentional: the
+ * "target file if missing" column in RFC-0004 maps here.
+ */
+/**
+ * Map a raw on-disk agent signal id to the preferred agent id after taking
+ * the declared `.ship/config.yml` agents into account. Today this only
+ * re-maps `agents-md` → `codex` when config lists `codex`, so doctor and
+ * verify can reconcile a Codex-configured repo that only has `AGENTS.md`
+ * on disk (the codex rules-render target emits `AGENTS.md`, not
+ * `.codex/SHIP_API.md`).
+ *
+ * @param {string} signalId raw detector id (e.g. "agents-md")
+ * @param {string[]=} configuredAgents agents listed in `.ship/config.yml`
+ * @returns {string} preferred agent id after reconciliation
+ */
+export function resolveAgentSignal(signalId, configuredAgents) {
+  const configured = Array.isArray(configuredAgents) ? configuredAgents : [];
+  if (signalId === "agents-md" && configured.includes("codex")) return "codex";
+  return signalId;
 }
+
+export const KNOWN_AGENTS = Object.freeze({
+  cursor: { label: "Cursor", targetRel: [".cursor", "rules", "ship-artifacts-protocol.mdc"] },
+  "agents-md": { label: "AGENTS.md (Codex/generic)", targetRel: ["AGENTS.md"] },
+  "claude-md": { label: "Claude Code CLAUDE.md", targetRel: ["CLAUDE.md"] },
+  codex: { label: "Codex (.codex/)", targetRel: [".codex", "SHIP_API.md"] },
+  copilot: { label: "GitHub Copilot", targetRel: [".github", "copilot-instructions.md"] },
+  aider: { label: "Aider", targetRel: ["AIDER.md"] },
+  cline: { label: "Cline/Roo", targetRel: [".clinerules"] },
+  continue: { label: "Continue.dev", targetRel: [".continue", "ship.md"] },
+  windsurf: { label: "Windsurf", targetRel: [".windsurfrules"] },
+  zed: { label: "Zed", targetRel: [".zed", "ship.md"] },
+  gemini: { label: "Gemini CLI", targetRel: ["GEMINI.md"] },
+  opencode: { label: "OpenCode", targetRel: [".opencode", "ship.md"] },
+  "cursor-cloud": { label: "Cursor Cloud Agent", targetRel: [".cursor", "environments.json"] },
+});

package/lib/feedback/drafts.mjs

@@ -0,0 +1,129 @@
+import fs from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+
+export function draftsDir(shipRoot) {
+  return path.join(shipRoot, ".ship", "feedback-drafts");
+}
+
+function safeSlug(s) {
+  return String(s || "draft")
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 64) || "draft";
+}
+
+function timestamp() {
+  const iso = new Date().toISOString();
+  return iso.replace(/[:T]/g, "-").replace(/\..+$/, "");
+}
+
+/**
+ * Create a new feedback draft on disk.
+ *
+ * @param {string} shipRoot
+ * @param {{
+ *   kind: string, id: string, version?: string,
+ *   title: string, summary: string,
+ *   recommendation?: string, stack?: object, tags?: string[]
+ * }} fields
+ * @returns {string} the absolute path of the draft file
+ */
+export function createDraft(shipRoot, fields) {
+  const kind = String(fields.kind || "").trim();
+  const id = String(fields.id || "").trim();
+  if (!kind || !id) {
+    throw new Error("createDraft: kind and id are required");
+  }
+
+  const dir = draftsDir(shipRoot);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const name = `${timestamp()}-${safeSlug(kind)}-${safeSlug(id)}.md`;
+  const fp = path.join(dir, name);
+
+  const meta = {
+    kind,
+    id,
+    version: fields.version || null,
+    tags: Array.isArray(fields.tags) ? fields.tags : [],
+    created_at: new Date().toISOString(),
+  };
+  if (fields.title) meta.title = fields.title;
+
+  const stack = fields.stack || {};
+  const stackLine = `tracker=${stack.tracker || "-"}, ci=${stack.ci || "-"}, agents=${
+    Array.isArray(stack.agents) ? stack.agents.join("+") || "-" : stack.agents || "-"
+  }, preset=${stack.preset || "-"}`;
+
+  const body =
+    `# ${fields.title || ""}\n\n` +
+    `**Summary**: ${fields.summary || ""}\n\n` +
+    `**Recommendation**: ${fields.recommendation || ""}\n\n` +
+    `**Stack context**: ${stackLine}\n\n` +
+    `<!-- ship-feedback: v1 -->\n`;
+
+  const front = YAML.stringify(meta, { lineWidth: 0 });
+  const text = `---\n${front}---\n\n${body}`;
+  fs.writeFileSync(fp, text, "utf8");
+  return fp;
+}
+
+/**
+ * List all draft files under `.ship/feedback-drafts/`, including under `sent/`.
+ * Returns absolute paths, sorted ascending by filename (timestamp-prefixed).
+ */
+export function listDrafts(shipRoot) {
+  const dir = draftsDir(shipRoot);
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isFile() && entry.name.endsWith(".md")) {
+      out.push(path.join(dir, entry.name));
+    }
+  }
+  const sentDir = path.join(dir, "sent");
+  if (fs.existsSync(sentDir)) {
+    for (const entry of fs.readdirSync(sentDir, { withFileTypes: true })) {
+      if (entry.isFile() && entry.name.endsWith(".md")) {
+        out.push(path.join(sentDir, entry.name));
+      }
+    }
+  }
+  out.sort();
+  return out;
+}
+
+export function readDraft(filePath) {
+  const raw = fs.readFileSync(filePath, "utf8");
+  const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) {
+    return { meta: {}, body: raw };
+  }
+  let meta = {};
+  try {
+    meta = YAML.parse(match[1]) || {};
+  } catch (e) {
+    throw new Error(`feedback draft: failed to parse front-matter in ${filePath}: ${e.message}`);
+  }
+  const body = (match[2] || "").replace(/^\n+/, "");
+  return { meta, body };
+}
+
+export function removeDraft(filePath) {
+  fs.unlinkSync(filePath);
+}
+
+/**
+ * Move a draft into `.ship/feedback-drafts/sent/` preserving history.
+ * Returns the new path.
+ */
+export function moveDraftToSent(shipRoot, filePath) {
+  const dir = path.join(draftsDir(shipRoot), "sent");
+  fs.mkdirSync(dir, { recursive: true });
+  const base = path.basename(filePath);
+  const dest = path.join(dir, base);
+  fs.renameSync(filePath, dest);
+  return dest;
+}

package/lib/find-ship-root.mjs

@@ -1,19 +1,25 @@
 import fs from "node:fs";
 import path from "node:path";
 
-const MARKERS = [
-  "workflows/manifest.json",
-  "tools/manifest.json",
-  "collections/manifest.json",
-  "patterns/manifest.json",
+const MARKER_DIRS = [
+  "artifacts/patterns",
+  "artifacts/tools",
+  "artifacts/collections",
 ];
 
 function markersOk(dir) {
-  return MARKERS.every((m) => fs.existsSync(path.join(dir, m)));
+  return MARKER_DIRS.every((rel) => {
+    const abs = path.join(dir, rel);
+    try {
+      return fs.statSync(abs).isDirectory();
+    } catch {
+      return false;
+    }
+  });
 }
 
 /**
- * Walk parents from cwd for a directory containing all Ship manifest markers.
+ * Walk parents from cwd for a directory containing the v2 artifacts/ tree.
  * @returns {string | null}
  */
 export function tryFindShipRepoRootFromWalk() {
@@ -28,7 +34,7 @@ export function tryFindShipRepoRootFromWalk() {
 }
 
 /**
- * Root of the Ship monorepo (manifests at repo root).
+ * Root of the Ship monorepo (artifacts/<plural>/<id>/ARTIFACT.md present).
  * Set `SHIP_REPO` to an absolute path when not running from inside the tree.
  */
 export function findShipRepoRoot() {
@@ -37,7 +43,7 @@ export function findShipRepoRoot() {
     const r = path.resolve(env);
     if (!markersOk(r)) {
       throw new Error(
-        `SHIP_REPO=${r} is not the Ship monorepo (expected tools/, workflows/, collections/, patterns/ manifests at repo root).`,
+        `SHIP_REPO=${r} is not the Ship monorepo (expected artifacts/{patterns,tools,collections}/ at repo root).`,
       );
     }
     return r;
@@ -60,7 +66,7 @@ export function resolveShipRepoRootForCatalog() {
     const r = path.resolve(env);
     if (!markersOk(r)) {
       throw new Error(
-        `SHIP_REPO=${r} is not the Ship monorepo (expected tools/, workflows/, collections/, patterns/ manifests at repo root).`,
+        `SHIP_REPO=${r} is not the Ship monorepo (expected artifacts/{patterns,tools,collections}/ at repo root).`,
       );
     }
     return r;

package/lib/http.mjs

@@ -1,13 +1,50 @@
+import crypto from "node:crypto";
+import { getUserAgent } from "./version.mjs";
+
+function joinUrl(baseUrl, path) {
+  return `${baseUrl.replace(/\/$/, "")}${path.startsWith("/") ? path : `/${path}`}`;
+}
+
+function authHeaders() {
+  const token = process.env.SHIP_API_TOKEN;
+  return token ? { Authorization: `Bearer ${token}` } : {};
+}
+
+/* Stamp a real User-Agent on every outbound call so the methodology API can
+ * correlate adoption metrics with the CLI release. The version string lives
+ * in cli/package.json (kept in sync with the root VERSION file). */
+function commonHeaders() {
+  return {
+    "User-Agent": getUserAgent(),
+    ...authHeaders(),
+  };
+}
+
+export class HttpError extends Error {
+  constructor(status, statusText, url, body) {
+    const msg = typeof body === "string" ? body : JSON.stringify(body);
+    super(`HTTP ${status} ${statusText} for ${url}\n${msg}`);
+    this.status = status;
+    this.statusText = statusText;
+    this.url = url;
+    this.body = body;
+  }
+}
+
 /**
  * @param {string} baseUrl
  * @param {string} path
  * @param {Record<string, unknown>} body
  */
 export async function apiPost(baseUrl, path, body) {
-  const url = `${baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+  const url = joinUrl(baseUrl, path);
   const res = await fetch(url, {
     method: "POST",
-    headers: { "Content-Type": "application/json", Accept: "application/json" },
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      ...commonHeaders(),
+    },
     body: JSON.stringify(body),
   });
   const text = await res.text();
@@ -17,10 +54,7 @@ export async function apiPost(baseUrl, path, body) {
   } catch {
     data = text;
   }
-  if (!res.ok) {
-    const msg = typeof data === "string" ? data : JSON.stringify(data);
-    throw new Error(`HTTP ${res.status} ${res.statusText} for POST ${url}\n${msg}`);
-  }
+  if (!res.ok) throw new HttpError(res.status, res.statusText, url, data ?? text);
   return data;
 }
 
@@ -29,8 +63,10 @@ export async function apiPost(baseUrl, path, body) {
  * @param {string} path
  */
 export async function apiGet(baseUrl, path) {
-  const url = `${baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
-  const res = await fetch(url, { headers: { Accept: "application/json" } });
+  const url = joinUrl(baseUrl, path);
+  const res = await fetch(url, {
+    headers: { Accept: "application/json", ...commonHeaders() },
+  });
   const text = await res.text();
   let data;
   try {
@@ -38,9 +74,199 @@ export async function apiGet(baseUrl, path) {
   } catch {
     data = text;
   }
-  if (!res.ok) {
-    const msg = typeof data === "string" ? data : JSON.stringify(data);
-    throw new Error(`HTTP ${res.status} ${res.statusText} for GET ${url}\n${msg}`);
+  if (!res.ok) throw new HttpError(res.status, res.statusText, url, data ?? text);
+  return data;
+}
+
+/**
+ * Aggregated catalog. RFC-0005 removed the legacy `/manifest` endpoint
+ * and RFC-0007 Phase 6 retired the ``artifact_kind=workflow`` layer;
+ * the catalog is now exposed as three per-kind routes (`/patterns`,
+ * `/tools`, `/collections`). This helper fans them out in parallel and
+ * stamps a `kind` field on each entry so callers (sync, verify) keep
+ * their existing single-list shape. `channel` is applied client-side
+ * because the per-kind endpoints don't filter today.
+ *
+ * @param {string} baseUrl
+ * @param {{channel?:string}} [opts]
+ * @returns {Promise<Array<object>>}
+ */
+export async function fetchManifest(baseUrl, { channel } = {}) {
+  const KINDS = [
+    { plural: "patterns", singular: "pattern" },
+    { plural: "tools", singular: "tool" },
+    { plural: "collections", singular: "collection" },
+  ];
+  const responses = await Promise.all(
+    KINDS.map((k) => apiGet(baseUrl, `/${k.plural}`)),
+  );
+  /** @type {Array<object>} */
+  const entries = [];
+  for (let i = 0; i < KINDS.length; i += 1) {
+    const { plural, singular } = KINDS[i];
+    const data = responses[i];
+    const arr = data && Array.isArray(data[plural]) ? data[plural] : [];
+    for (const e of arr) {
+      entries.push({ ...e, kind: e.kind || singular });
+    }
+  }
+  const wantChannel = (channel || "").toLowerCase();
+  if (wantChannel && wantChannel !== "edge") {
+    return entries.filter(
+      (e) => (e.channel || "stable").toLowerCase() === wantChannel,
+    );
+  }
+  return entries;
+}
+
+function sha256Hex(buf) {
+  return crypto.createHash("sha256").update(buf).digest("hex");
+}
+
+/**
+ * POST /fetch with {kind,id,version?}. Handles 404 (version_not_found) and 410 (yanked).
+ * Returns {content, meta} where meta is the manifest record + source_url.
+ * @param {string} baseUrl
+ * @param {string} kind
+ * @param {string} id
+ * @param {string} [version]
+ */
+export async function fetchArtifact(baseUrl, kind, id, version) {
+  const body = { kind, id };
+  if (version) body.version = version;
+  let data;
+  try {
+    data = await apiPost(baseUrl, "/fetch", body);
+  } catch (e) {
+    if (e instanceof HttpError && e.status === 404) {
+      const err = new Error(
+        `artifact not found: ${kind}:${id}${version ? `@${version}` : ""}`,
+      );
+      err.code = "ARTIFACT_NOT_FOUND";
+      throw err;
+    }
+    if (e instanceof HttpError && e.status === 410) {
+      const err = new Error(
+        `artifact yanked: ${kind}:${id}${version ? `@${version}` : ""}`,
+      );
+      err.code = "ARTIFACT_YANKED";
+      throw err;
+    }
+    throw e;
+  }
+  if (!data || typeof data.content !== "string") {
+    throw new Error(`POST /fetch: missing 'content' in response for ${kind}:${id}`);
+  }
+  const content = data.content;
+  const meta = {
+    kind: data.kind || kind,
+    id: data.id || id,
+    version: data.version || version || null,
+    content_sha256: data.content_sha256 || sha256Hex(Buffer.from(content, "utf8")),
+    updated_at: data.updated_at || null,
+    channel: data.channel || null,
+    source_url: `${baseUrl.replace(/\/$/, "")}/fetch`,
+  };
+  return { content, meta };
+}
+
+/**
+ * POST /fetch with {path, version?} — for raw doc paths.
+ * @param {string} baseUrl
+ * @param {string} repoRelativePath
+ * @param {string} [version]
+ */
+export async function fetchDoc(baseUrl, repoRelativePath, version) {
+  const body = { path: repoRelativePath };
+  if (version) body.version = version;
+  let data;
+  try {
+    data = await apiPost(baseUrl, "/fetch", body);
+  } catch (e) {
+    if (e instanceof HttpError && e.status === 404) {
+      const err = new Error(`doc not found: ${repoRelativePath}`);
+      err.code = "ARTIFACT_NOT_FOUND";
+      throw err;
+    }
+    if (e instanceof HttpError && e.status === 410) {
+      const err = new Error(`doc yanked: ${repoRelativePath}`);
+      err.code = "ARTIFACT_YANKED";
+      throw err;
+    }
+    throw e;
+  }
+  if (!data || typeof data.content !== "string") {
+    throw new Error(`POST /fetch: missing 'content' in response for ${repoRelativePath}`);
+  }
+  const content = data.content;
+  const meta = {
+    kind: "doc",
+    id: data.id || repoRelativePath,
+    path: repoRelativePath,
+    version: data.version || version || null,
+    content_sha256: data.content_sha256 || sha256Hex(Buffer.from(content, "utf8")),
+    updated_at: data.updated_at || null,
+    source_url: `${baseUrl.replace(/\/$/, "")}/fetch`,
+  };
+  return { content, meta };
+}
+
+/**
+ * Best-effort POST /telemetry. Silent on network errors (buffer in outbox).
+ * Returns {ok, status?, error?}.
+ */
+export async function postTelemetry(baseUrl, events) {
+  try {
+    const data = await apiPost(baseUrl, "/telemetry", { events });
+    return { ok: true, data };
+  } catch (e) {
+    return { ok: false, error: e };
   }
+}
+
+/**
+ * GET /telemetry/<anonymous_id>/export → { events: [...] }.
+ * @param {string} baseUrl
+ * @param {string} anonymousId
+ */
+export async function exportTelemetry(baseUrl, anonymousId) {
+  return apiGet(baseUrl, `/telemetry/${encodeURIComponent(anonymousId)}/export`);
+}
+
+/**
+ * DELETE /telemetry/<anonymous_id> with X-Ship-Confirm: yes.
+ * Returns the server JSON (expected shape: { deleted: N }).
+ * @param {string} baseUrl
+ * @param {string} anonymousId
+ */
+export async function deleteTelemetry(baseUrl, anonymousId) {
+  const url = joinUrl(baseUrl, `/telemetry/${encodeURIComponent(anonymousId)}`);
+  const res = await fetch(url, {
+    method: "DELETE",
+    headers: {
+      Accept: "application/json",
+      "X-Ship-Confirm": "yes",
+      ...commonHeaders(),
+    },
+  });
+  const text = await res.text();
+  let data;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {
+    data = text;
+  }
+  if (!res.ok) throw new HttpError(res.status, res.statusText, url, data ?? text);
   return data;
 }
+
+/**
+ * POST /feedback → { issue_url, deduplicated, ... }.
+ * Server errors are thrown verbatim via HttpError so callers can surface the
+ * server-provided message.
+ * @param {string} baseUrl
+ * @param {object} body
+ */
+export async function postFeedback(baseUrl, body) {
+  return apiPost(baseUrl, "/feedback", body);
+}