@elmundi/ship-cli 0.8.1 → 0.12.0

package/lib/templates.mjs

@@ -1,50 +1,71 @@
-const MARKER = "<!-- ship-cli: methodology-api -->";
+const MARKER = "<!-- ship-cli: artifacts-protocol v1 -->";
+const END_MARKER = "<!-- ship-cli:end artifacts-protocol -->";
 
 /**
+ * Short "Artifacts protocol" stub shared by every rendered template.
+ * Keep it tight; the authoritative contract lives in RFC-0001.
+ *
  * @param {string} baseUrl
  */
-export function cursorRuleMdc(baseUrl) {
-  return `---
-name: ship-methodology-api
-description: Call the Ship methodology HTTP API (semantic search, fetch full docs, retro feedback, pattern index) from the agent.
----
+function protocolBody(baseUrl) {
+  return `Base URL (env \`SHIP_API_BASE\`, flag \`--base-url\`): \`${baseUrl}\`
 
-${MARKER}
+## Artifacts protocol (RFC-0001)
 
-# Ship methodology API (local)
+Every Ship artifact is versioned (semver + \`content_sha256\`). Clients never
+vendor artifact bodies — they call \`shipctl\` (which hits \`POST /fetch\` and
+writes a local \`.ship/cache/<kind>/<id>@<version>/ARTIFACT.md\` entry).
 
-Base URL (override with \`SHIP_API_BASE\` for agents, or \`--base-url\` for CLI): \`${baseUrl}\`
+Agent protocol (must follow before applying an artifact):
 
-## When to use
+1. **Resolve before use.** Run \`shipctl <kind> show <id>\` (or \`fetch\`) so the
+   body you act on is the current pinned version. Pins live in
+   \`.ship/config.yml\` (\`artifacts.pins\`).
+2. **Record the exact version.** Put \`<kind>:<id>@<version>\` in the PR
+   description for every artifact you consumed (one per line).
+3. **Do not copy bodies into the repo.** Reference the artifact id + version.
+4. **Feedback is opt-in.** Use \`shipctl feedback draft\`; never auto-submit.
 
-1. **Discover** — \`POST /search\` with a natural-language query over Ship docs + prompts.
-2. **Read** — \`POST /fetch\` with a repo-relative \`path\` from search hits (markdown/text only).
-3. **Retro** — \`POST /feedback\` to open a sanitized GitHub issue (needs \`GITHUB_TOKEN\` on the server).
-4. **Catalog** — \`ship pattern|tool|workflow|collection list\` / \`show <id>\` / \`fetch <id>\` (\`GET /…\` on the same base URL as search, or \`POST /fetch\` with \`{ kind, id }\` when hosted; or disk when cwd/\`SHIP_REPO\` is the Ship tree).
-
-## Examples (CLI from Ship repo)
+## CLI
 
 \`\`\`bash
-npm run ship -- search "release gates and qa split" --top-k 8
-npm run ship -- docs fetch documentation/adoption/delivery-quality-and-release-process.md
-npm run ship -- pattern list
+shipctl pattern list
+shipctl pattern show role-developer              # resolves latest or pin
+shipctl pattern fetch role-developer --version 1.4.2
+shipctl search "release gates and qa split" --top-k 8
+shipctl docs fetch documentation/adoption/delivery-quality-and-release-process.md
+shipctl sync                                       # reconcile .ship/cache/
 \`\`\`
 
-Equivalent curl (when not using the CLI):
+## HTTP (curl, no CLI)
 
 \`\`\`bash
-curl -sS -X POST "${baseUrl}/search" -H "Content-Type: application/json" \\
-  -d '{"query":"release gates and qa split","top_k":8}'
 curl -sS -X POST "${baseUrl}/fetch" -H "Content-Type: application/json" \\
-  -d '{"path":"documentation/adoption/delivery-quality-and-release-process.md"}'
+  -d '{"kind":"pattern","id":"role-developer"}'
 curl -sS "${baseUrl}/patterns"
 \`\`\`
 
-## Agent workflow
+See \`documentation/protocol/rfc-0001-artifacts-protocol.md\` in the Ship repo for the
+full HTTP surface, pin rules, and cache layout. \`.ship/config.yml\` schema is
+RFC-0002.`;
+}
+
+/**
+ * @param {string} baseUrl
+ */
+export function cursorRuleMdc(baseUrl) {
+  return `---
+name: ship-artifacts-protocol
+description: Resolve, use, and record Ship artifacts (patterns/tools/collections) via shipctl.
+---
+
+${MARKER}
+
+# Ship artifacts protocol (Cursor rule)
 
-Prefer **search → fetch one path → quote** in your reply. Never paste secrets into \`/feedback\`; the server redacts common token shapes.
+${protocolBody(baseUrl)}
 
-Run the API locally: \`uvicorn backend.app.main:app --reload --host 127.0.0.1 --port 8100\` (see \`documentation/tools/backend-api.md\` in the Ship repo).
+${END_MARKER}
 `;
 }
 
@@ -58,16 +79,9 @@ export function markdownSection(baseUrl) {
 
 ${MARKER}
 
-## Ship methodology API
-
-Base URL: \`${baseUrl}\` (env \`SHIP_API_BASE\`).
-
-- **Search** \`POST /search\` JSON \`{ "query": string, "top_k"?: number }\`
-- **Fetch** \`POST /fetch\` JSON \`{ "path": "documentation/...md" }\`
-- **Feedback** \`POST /feedback\` JSON \`{ "title", "summary", "recommendations"?: string[], "source_context"?: string }\`
-- **Catalog** — \`ship pattern|tool|workflow|collection list\` / \`show <id>\` / \`fetch <id>\` (same \`SHIP_API_BASE\` as search, or local tree): \`GET /patterns\`, \`GET /patterns/{id}\`, or \`POST /fetch\` with \`{ "kind": "pattern", "id": "…" }\`
+## Ship artifacts protocol
 
-Use search first, then fetch the best path. Keep tokens out of feedback bodies.
+${protocolBody(baseUrl)}
 `;
 }
 
@@ -75,40 +89,14 @@ Use search first, then fetch the best path. Keep tokens out of feedback bodies.
  * @param {string} baseUrl
  */
 export function standaloneDoc(baseUrl) {
-  return `# Ship methodology API — agent reference
+  return `# Ship artifacts protocol — agent reference
 
 ${MARKER}
 
-Generated by \`ship init\`. Base URL: \`${baseUrl}\`
-
-See the Ship repo \`documentation/tools/backend-api.md\` for full contract.
-
-## Endpoints
-
-| Method | Path | Body / notes |
-|--------|------|----------------|
-| POST | /search | \`{ "query": "...", "top_k": 8 }\` |
-| POST | /fetch | \`{ "path": "documentation/foo.md" }\` |
-| POST | /feedback | \`{ "title", "summary", "recommendations": [], "source_context" }\` |
-| GET | /patterns | list manifest — **CLI:** \`ship pattern list\` (HTTP or disk in clone) |
-| GET | /patterns/{id} | metadata + markdown \`content\` — **CLI:** \`ship pattern show <id>\` |
-| POST | /fetch | catalog body — **CLI:** \`ship pattern fetch <id>\` with \`{ "kind": "pattern", "id" }\` |
+Generated by \`shipctl init\`.
 
-## CLI (from Ship monorepo)
-
-\`\`\`bash
-npm run ship -- pattern list
-npm run ship -- pattern show catalog-a1-intake
-npm run ship -- search "intake labels" --top-k 5
-\`\`\`
-
-## curl (direct HTTP)
-
-\`\`\`bash
-export SHIP=${baseUrl}
-curl -sS -X POST "$SHIP/search" -H "Content-Type: application/json" -d '{"query":"intake labels","top_k":5}'
-\`\`\`
+${protocolBody(baseUrl)}
 `;
 }
 
-export { MARKER };
+export { MARKER, END_MARKER };

package/lib/verify/checks/agents-on-disk.mjs

@@ -0,0 +1,58 @@
+import fs from "node:fs";
+import path from "node:path";
+import { detectAgentTargets } from "../../detect.mjs";
+import { readCachedArtifact } from "../../cache/store.mjs";
+
+export const id = "agents-on-disk";
+export const category = "config";
+export const description = "Declared stack.agents have detectable signals on disk";
+
+/**
+ * @param {import("../registry.mjs").CheckContext} ctx
+ */
+export async function run(ctx) {
+  const declared = (ctx.config && ctx.config.stack && Array.isArray(ctx.config.stack.agents))
+    ? ctx.config.stack.agents
+    : [];
+  if (!declared.length) {
+    return { status: "skip", detail: "stack.agents is empty" };
+  }
+  const detected = new Set(detectAgentTargets(ctx.cwd).map((t) => t.id));
+  const missing = [];
+  for (const agent of declared) {
+    if (detected.has(agent)) continue;
+    // Second chance: the cached agent-rules artifact may declare a custom
+    // install_target (e.g. codex -> AGENTS.md) that the heuristic detector
+    // doesn't recognise. Treat a present install_target file as "signal".
+    let fm = null;
+    try {
+      fm = readCachedArtifact(ctx.cwd, "collection", `agent-rules-${agent}`);
+    } catch {
+      fm = null;
+    }
+    const topLevel = fm && fm.fm && typeof fm.fm.install_target === "string"
+      ? fm.fm.install_target.trim()
+      : "";
+    const nested = fm && fm.spec && typeof fm.spec.install_target === "string"
+      ? fm.spec.install_target.trim()
+      : "";
+    const target = topLevel || nested;
+    if (target && fs.existsSync(path.join(ctx.cwd, target))) {
+      detected.add(agent);
+      continue;
+    }
+    missing.push(agent);
+  }
+  if (missing.length) {
+    return {
+      status: "warn",
+      detail: `no on-disk signal for declared agents: ${missing.join(", ")}`,
+      data: { missing, detected: [...detected] },
+    };
+  }
+  return {
+    status: "pass",
+    detail: `${declared.length} declared agent(s) have on-disk signals`,
+    data: { detected: [...detected] },
+  };
+}

package/lib/verify/checks/api-reachable.mjs

@@ -0,0 +1,39 @@
+import { apiGet, HttpError } from "../../http.mjs";
+
+export const id = "api-reachable";
+export const category = "network";
+export const description = "Ship methodology API responds on /health or /patterns";
+
+/**
+ * @param {import("../registry.mjs").CheckContext} ctx
+ */
+export async function run(ctx) {
+  const baseUrl = ctx.baseUrl
+    || (ctx.config && ctx.config.api && ctx.config.api.base_url)
+    || process.env.SHIP_API_BASE
+    || "https://ship.elmundi.com";
+
+  // Try /health first (cheap endpoint). If unavailable, fall back to
+  // /patterns — RFC-0005 removed the legacy /manifest aggregator, so we
+  // probe the smallest catalog endpoint instead. Both routes are public.
+  try {
+    await apiGet(baseUrl, "/health");
+    return { status: "pass", detail: `${baseUrl}/health → 200` };
+  } catch (e) {
+    if (!(e instanceof HttpError) || e.status !== 404) {
+      // network error OR other HTTP code — try /patterns
+    }
+  }
+
+  try {
+    await apiGet(baseUrl, "/patterns");
+    return { status: "pass", detail: `${baseUrl}/patterns → 200` };
+  } catch (e) {
+    const msg = e instanceof HttpError ? `${e.status} ${e.statusText}` : e.message;
+    return {
+      status: "fail",
+      detail: `${baseUrl} unreachable: ${msg}`,
+      data: { baseUrl },
+    };
+  }
+}

package/lib/verify/checks/artifacts-up-to-date.mjs

@@ -0,0 +1,78 @@
+import { fetchManifest } from "../../http.mjs";
+import { listCached } from "../../cache/store.mjs";
+
+export const id = "artifacts-up-to-date";
+export const category = "network";
+export const description = "Local cache matches latest manifest on the configured channel";
+
+function newestVersion(versions) {
+  if (!Array.isArray(versions) || !versions.length) return null;
+  // Manifest entries are usually already sorted descending; treat the first as latest.
+  return versions[0];
+}
+
+/**
+ * @param {import("../registry.mjs").CheckContext} ctx
+ */
+export async function run(ctx) {
+  let cache;
+  try {
+    cache = listCached(ctx.cwd);
+  } catch {
+    cache = [];
+  }
+  if (!cache.length) {
+    return { status: "skip", detail: "no cached artifacts to compare" };
+  }
+
+  const baseUrl = ctx.baseUrl
+    || (ctx.config && ctx.config.api && ctx.config.api.base_url)
+    || process.env.SHIP_API_BASE
+    || "https://ship.elmundi.com";
+  const channel = (ctx.config && ctx.config.api && ctx.config.api.channel) || "stable";
+
+  let manifest;
+  try {
+    manifest = await fetchManifest(baseUrl, { channel });
+  } catch (e) {
+    return { status: "warn", detail: `manifest fetch failed: ${e.message}` };
+  }
+
+  const index = new Map();
+  for (const m of manifest || []) {
+    const k = `${m.kind}/${m.id}`;
+    if (!index.has(k)) index.set(k, m);
+  }
+
+  const stale = [];
+  for (const entry of cache) {
+    const key = `${entry.kind}/${entry.id}`;
+    const m = index.get(key);
+    if (!m) continue;
+    const latest = m.version || (m.versions ? newestVersion(m.versions) : null);
+    if (latest && entry.version && latest !== entry.version) {
+      stale.push({
+        kind: entry.kind,
+        id: entry.id,
+        cached: entry.version,
+        latest,
+      });
+    }
+  }
+
+  if (stale.length) {
+    const summary = stale
+      .slice(0, 3)
+      .map((s) => `${s.kind}/${s.id} ${s.cached}→${s.latest}`)
+      .join(", ");
+    return {
+      status: "warn",
+      detail: `${stale.length} stale artifact(s): ${summary}${stale.length > 3 ? "…" : ""} — run 'shipctl sync'`,
+      data: { stale, channel },
+    };
+  }
+  return {
+    status: "pass",
+    detail: `all ${cache.length} cached entries are current on channel=${channel}`,
+  };
+}

package/lib/verify/checks/bootstrap-files.mjs

@@ -0,0 +1,67 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const id = "bootstrap-files";
+export const category = "local";
+export const description = "Bootstrap scaffolding files carry ship-managed markers";
+
+/**
+ * @param {import("../registry.mjs").CheckContext} ctx
+ */
+export async function run(ctx) {
+  const stack = (ctx.config && ctx.config.stack) || {};
+  const preset = stack.preset;
+  const ci = stack.ci;
+  const tracker = stack.tracker;
+
+  if (preset !== "mobile-app" || ci !== "gh-actions" || tracker !== "linear") {
+    return {
+      status: "skip",
+      detail: `combo ${preset || "?"}+${ci || "?"}+${tracker || "?"} has no bootstrap template`,
+    };
+  }
+
+  const targets = [
+    {
+      rel: ".github/workflows/ship-pilot.yml",
+      marker: "ship-managed: workflow",
+    },
+    {
+      rel: ".ship/labels.yml",
+      marker: "ship-managed: labels",
+    },
+    {
+      rel: ".env.example",
+      marker: "--- ship-managed ---",
+    },
+  ];
+
+  const rows = [];
+  let fail = false;
+  let warn = false;
+  for (const t of targets) {
+    const abs = path.join(ctx.cwd, t.rel);
+    if (!fs.existsSync(abs)) {
+      rows.push({ path: t.rel, status: "fail", detail: "missing" });
+      fail = true;
+      continue;
+    }
+    const body = fs.readFileSync(abs, "utf8");
+    if (!body.includes(t.marker)) {
+      rows.push({
+        path: t.rel,
+        status: "warn",
+        detail: `present but missing marker '${t.marker}'`,
+      });
+      warn = true;
+      continue;
+    }
+    rows.push({ path: t.rel, status: "pass", detail: "ok" });
+  }
+
+  const status = fail ? "fail" : warn ? "warn" : "pass";
+  const detail = status === "pass"
+    ? `${rows.length} bootstrap files carry ship-managed markers`
+    : rows.filter((r) => r.status !== "pass").map((r) => `${r.path}: ${r.detail}`).join("; ");
+  return { status, detail, data: { rows } };
+}

package/lib/verify/checks/cache-integrity.mjs

@@ -0,0 +1,51 @@
+import { listCached, verifyCached } from "../../cache/store.mjs";
+
+export const id = "cache-integrity";
+export const category = "local";
+export const description = "Cached artifact bodies match their .meta.json sha256";
+
+/**
+ * @param {import("../registry.mjs").CheckContext} ctx
+ */
+export async function run(ctx) {
+  let entries = [];
+  try {
+    entries = listCached(ctx.cwd);
+  } catch (e) {
+    return { status: "fail", detail: `failed to read cache index: ${e.message}` };
+  }
+  if (!entries.length) {
+    return { status: "skip", detail: "no cached artifacts (.ship/cache/)" };
+  }
+
+  const tampered = [];
+  for (const e of entries) {
+    const res = verifyCached(ctx.cwd, e.kind, e.id, e.version);
+    if (!res.ok) {
+      tampered.push({
+        kind: e.kind,
+        id: e.id,
+        version: e.version,
+        expected: res.expected,
+        actual: res.actual,
+        reason: res.reason || "sha256 mismatch",
+      });
+    }
+  }
+
+  if (tampered.length) {
+    return {
+      status: "fail",
+      detail: `${tampered.length}/${entries.length} cached entries tampered: ${tampered
+        .slice(0, 3)
+        .map((t) => `${t.kind}/${t.id}@${t.version}`)
+        .join(", ")}${tampered.length > 3 ? "…" : ""}`,
+      data: { tampered, total: entries.length },
+    };
+  }
+  return {
+    status: "pass",
+    detail: `${entries.length} cached entries verified (sha256 ok)`,
+    data: { total: entries.length },
+  };
+}

package/lib/verify/checks/ci-secrets.mjs

@@ -0,0 +1,86 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const id = "ci-secrets";
+export const category = "network";
+export const description = "Every workflow ${{ secrets.X }} reference is declared in .env.example";
+
+const SECRET_RE = /\$\{\{\s*secrets\.([A-Z0-9_]+)\s*\}\}/g;
+
+/**
+ * Extract secret names referenced in a gh-actions workflow body.
+ */
+function extractSecrets(body) {
+  const found = new Set();
+  let m;
+  // Reset regex across calls
+  const re = new RegExp(SECRET_RE.source, SECRET_RE.flags);
+  while ((m = re.exec(body)) !== null) {
+    const name = m[1];
+    if (name && name !== "GITHUB_TOKEN") found.add(name);
+  }
+  return [...found];
+}
+
+function parseEnvExample(body) {
+  const out = new Set();
+  for (const raw of body.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq < 0) continue;
+    const key = line.slice(0, eq).trim();
+    if (/^[A-Z0-9_]+$/.test(key)) out.add(key);
+  }
+  return out;
+}
+
+/**
+ * @param {import("../registry.mjs").CheckContext} ctx
+ */
+export async function run(ctx) {
+  const ci = ctx.config && ctx.config.stack && ctx.config.stack.ci;
+  if (ci !== "gh-actions") {
+    return { status: "skip", detail: `stack.ci=${ci || "?"} (gh-actions-only check)` };
+  }
+
+  const wfDir = path.join(ctx.cwd, ".github", "workflows");
+  if (!fs.existsSync(wfDir)) {
+    return { status: "skip", detail: ".github/workflows not present" };
+  }
+  let files;
+  try {
+    files = fs.readdirSync(wfDir).filter((f) => /\.ya?ml$/.test(f));
+  } catch {
+    files = [];
+  }
+  if (!files.length) {
+    return { status: "skip", detail: "no workflow files under .github/workflows" };
+  }
+
+  const referenced = new Set();
+  for (const f of files) {
+    const body = fs.readFileSync(path.join(wfDir, f), "utf8");
+    for (const s of extractSecrets(body)) referenced.add(s);
+  }
+  if (!referenced.size) {
+    return { status: "pass", detail: `no ${"${{ secrets.* }}"} references in ${files.length} workflow(s)` };
+  }
+
+  const envExamplePath = path.join(ctx.cwd, ".env.example");
+  const declared = fs.existsSync(envExamplePath)
+    ? parseEnvExample(fs.readFileSync(envExamplePath, "utf8"))
+    : new Set();
+  const missing = [...referenced].filter((s) => !declared.has(s));
+  if (!missing.length) {
+    return {
+      status: "pass",
+      detail: `all ${referenced.size} referenced secret(s) declared in .env.example`,
+    };
+  }
+  return {
+    status: "warn",
+    detail: `secrets referenced in workflows but missing from .env.example: ${missing.join(", ")}`,
+    data: { missing, referenced: [...referenced] },
+  };
+}

package/lib/verify/checks/config-present.mjs

@@ -0,0 +1,39 @@
+import fs from "node:fs";
+import path from "node:path";
+import { validateConfig } from "../../config/schema.mjs";
+
+export const id = "config-present";
+export const category = "local";
+export const description = ".ship/config.yml exists and validates";
+
+/**
+ * @param {import("../registry.mjs").CheckContext} ctx
+ */
+export async function run(ctx) {
+  const configPath = path.join(ctx.cwd, ".ship", "config.yml");
+  if (!fs.existsSync(configPath)) {
+    return {
+      status: "fail",
+      detail: `missing ${path.relative(ctx.cwd, configPath)} — run 'shipctl config init'`,
+    };
+  }
+  if (!ctx.config) {
+    return {
+      status: "fail",
+      detail: `${path.relative(ctx.cwd, configPath)} could not be parsed`,
+    };
+  }
+  const res = validateConfig(ctx.config);
+  if (!res.ok) {
+    return {
+      status: "fail",
+      detail: `${path.relative(ctx.cwd, configPath)} invalid: ${res.errors[0]}`,
+      data: { errors: res.errors, warnings: res.warnings },
+    };
+  }
+  return {
+    status: "pass",
+    detail: `${path.relative(ctx.cwd, configPath)} parsed; schema v${ctx.config.version ?? "?"}`,
+    data: { warnings: res.warnings },
+  };
+}

package/lib/verify/checks/gitignore-cache.mjs

@@ -0,0 +1,51 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const id = "gitignore-cache";
+export const category = "local";
+export const description = ".gitignore contains .ship/cache/";
+
+/**
+ * @param {import("../registry.mjs").CheckContext} ctx
+ */
+export async function run(ctx) {
+  const cacheTracked =
+    !!(ctx.config && ctx.config.cache && ctx.config.cache.vcs_tracked === true);
+  const giPath = path.join(ctx.cwd, ".gitignore");
+  if (!fs.existsSync(giPath)) {
+    if (cacheTracked) {
+      return {
+        status: "pass",
+        detail: ".gitignore absent but cache.vcs_tracked=true — cache is intentionally committed",
+      };
+    }
+    return {
+      status: "warn",
+      detail: ".gitignore not found; add `.ship/cache/` to keep cached artifacts out of git",
+    };
+  }
+  const body = fs.readFileSync(giPath, "utf8");
+  const lines = new Set(body.split(/\r?\n/).map((l) => l.trim()));
+  const listed = lines.has(".ship/cache/") || lines.has(".ship/cache");
+
+  if (cacheTracked && listed) {
+    return {
+      status: "warn",
+      detail:
+        ".ship/cache/ listed in .gitignore but cache.vcs_tracked=true — entries will be ignored by git",
+    };
+  }
+  if (cacheTracked) {
+    return {
+      status: "pass",
+      detail: "cache.vcs_tracked=true; .gitignore does not exclude .ship/cache/",
+    };
+  }
+  if (!listed) {
+    return {
+      status: "warn",
+      detail: ".ship/cache/ not listed in .gitignore — add it to avoid committing cached bodies",
+    };
+  }
+  return { status: "pass", detail: ".ship/cache/ listed in .gitignore" };
+}