cinatra 0.1.0

package/src/dev-repo-sync.mjs

@@ -0,0 +1,297 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync } from "node:fs";
+import path from "node:path";
+
+// ---------------------------------------------------------------------------
+// Generic dev-time git repo sync.
+//
+// Shared clone/fast-forward machinery used by BOTH `dev-apps.mjs` (the external
+// WordPress plugin + Drupal module clones) and `cinatra-dev-extensions.mjs` (the
+// cinatra extension checkouts). Lives in its own module so neither consumer has
+// to import the other's surface.
+//
+// Five explicit states per target (never silently destroys local work):
+//   - absent OR empty non-git dir            -> clone
+//   - clean git, correct origin + branch     -> fetch + ff-only (force: reset)
+//   - dirty git, correct origin + branch     -> skip + warn (force: stash+reset)
+//   - wrong origin OR wrong branch           -> fail with remediation (never reset)
+//   - non-empty non-git dir                  -> fail with remediation
+//
+// Per-repo URL overrides via env: CINATRA_<NAME>_REPO_URL (HTTPS or SSH).
+// ---------------------------------------------------------------------------
+
+/** "@cinatra-ai/wordpress-plugin" -> "CINATRA_WORDPRESS_PLUGIN_REPO_URL" */
+export function envOverrideVarFor(pkgName) {
+  const base = String(pkgName)
+    .replace(/^@[^/]+\//, "")
+    .replace(/[^a-zA-Z0-9]+/g, "_")
+    .toUpperCase();
+  return `CINATRA_${base}_REPO_URL`;
+}
+
+/**
+ * Normalize a GitHub remote (HTTPS or SSH) to "owner/repo" (lowercased, no
+ * trailing slash, no .git) so HTTPS ↔ SSH forms of the same repo compare equal.
+ * Returns null for non-GitHub / unparseable URLs.
+ */
+export function normalizeGitHubRemote(url) {
+  if (!url) return null;
+  const s = String(url).trim().replace(/\.git$/i, "");
+  const m =
+    s.match(/^git@github\.com:(.+)$/i) ||
+    s.match(/^ssh:\/\/(?:[^@/]+@)?github\.com\/(.+)$/i) ||
+    // Accept an optional `user@`/`token@` credential before the host so a
+    // credentialed GitHub URL still normalizes to owner/repo (otherwise it
+    // returned null → the origin check degraded to a raw path compare).
+    s.match(/^https?:\/\/(?:[^@/]+@)?github\.com\/(.+)$/i);
+  if (!m) return null;
+  return m[1].replace(/\/+$/, "").toLowerCase();
+}
+
+// A local (non-network) git remote: file:// or an absolute filesystem path.
+// Used to confine the path-equality origin fallback to local remotes ONLY.
+export function isLocalGitRemote(url) {
+  if (typeof url !== "string") return false;
+  const u = url.trim();
+  return u.startsWith("file://") || path.isAbsolute(u);
+}
+
+// Strip credentials embedded in a URL before logging (e.g. a
+// `https://<token>@github.com/...` override leaks a PAT into CI/dev logs).
+export function redactGitUrl(url) {
+  if (typeof url !== "string") return String(url);
+  return url.replace(/(\bhttps?:\/\/)[^@/\s]*@/gi, "$1***@").replace(/(\bssh:\/\/)[^@/\s]*@/gi, "$1***@");
+}
+
+// Remote allowlist: GitHub over https/ssh/scp (real extension + app repos) OR a
+// local filesystem path / file:// (local mirrors + test fixtures). Anything else
+// is refused BEFORE `git clone` so a malicious config can't make git contact an
+// arbitrary remote.
+export function isAllowedGitRemote(url) {
+  if (typeof url !== "string" || url.trim() === "") return false;
+  const u = url.trim();
+  if (/^https:\/\/([^/@\s]+@)?github\.com\//i.test(u)) return true;
+  if (/^ssh:\/\/git@github\.com\//i.test(u)) return true;
+  if (/^git@github\.com:/i.test(u)) return true;
+  if (u.startsWith("file://")) return true;
+  if (path.isAbsolute(u)) return true; // local bare repo / mirror
+  return false;
+}
+
+export function defaultRepoSyncDeps() {
+  return {
+    git: (args, cwd) =>
+      execFileSync("git", args, {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+      }).toString(),
+    exists: (p) => existsSync(p),
+    readdir: (p) => readdirSync(p),
+    mkdirp: (p) => mkdirSync(p, { recursive: true }),
+  };
+}
+
+function dirIsEmpty(dir, deps) {
+  try {
+    return deps.readdir(dir).filter((n) => n !== ".DS_Store").length === 0;
+  } catch {
+    return true;
+  }
+}
+
+const COMMIT_SHA_RE = /^[0-9a-f]{40}$/;
+
+/**
+ * Sync a single target repo. `deps` is injectable for tests. Returns
+ * { pkgName, action } or throws on a fail-state. `forceFlagHint` / `stashLabel`
+ * let each caller surface the right force-flag advice (dev-apps vs extensions).
+ *
+ * Pinned mode (`sha` set): the target is checked out DETACHED at exactly that
+ * commit instead of tracking `origin/<branch>`. Used by CI so the validated
+ * extension universe is the COMMITTED lock state, not whatever the companion
+ * repos' tips say at run time (cinatra#141). Pinned semantics per state:
+ *   - absent/empty            -> clone (delegates partial-state cleanup to
+ *                                `git clone`), ensure the commit is present
+ *                                (fetch the exact sha only when the cloned
+ *                                branch does not already contain it), then
+ *                                `checkout --detach <sha>` + assert HEAD==sha.
+ *                                A failure after the clone leaves a valid
+ *                                branch-mode checkout that the existing-git
+ *                                path below re-pins on retry.
+ *   - existing git, clean     -> verify origin (branch-name check does NOT
+ *                                apply — detached HEAD is the expected state),
+ *                                no-op when HEAD already equals the pin,
+ *                                otherwise fetch-if-missing + re-detach.
+ *   - existing git, dirty     -> HARD FAIL. Pinned mode never stashes or
+ *                                resets local work (no --force semantics).
+ *   - wrong origin / non-git  -> hard fail (unchanged from branch mode).
+ */
+export function syncOneRepo({
+  pkgName,
+  url,
+  branch,
+  sha,
+  dest,
+  force,
+  deps,
+  log,
+  forceFlagHint = "--force",
+  stashLabel = "cinatra setup --force",
+}) {
+  const { git } = deps;
+  // Pinned mode accepts ONLY a full lowercase 40-hex commit sha — anything
+  // else (branch name, short sha, flag-like string) is refused before any git
+  // invocation. The regex also subsumes the leading-dash argument guard.
+  if (sha !== undefined && (typeof sha !== "string" || !COMMIT_SHA_RE.test(sha))) {
+    throw new Error(
+      `${pkgName}: pinned sync requires a full lowercase 40-hex commit sha (got "${sha}").`,
+    );
+  }
+  // Git argument-injection defense-in-depth: a `url`/`branch` (from package.json
+  // config or a CINATRA_*_REPO_URL env override) that begins with "-" would be
+  // parsed by git as an option, not a positional. execFileSync already blocks
+  // shell metachars; this blocks flag-like git args. A leading-dash repo URL or
+  // branch is never legitimate here.
+  for (const [label, val] of [["url", url], ["branch", branch]]) {
+    if (typeof val === "string" && val.startsWith("-")) {
+      throw new Error(`${pkgName}: refusing a "${label}" that begins with "-" ("${val}") — flag-like git arguments are not allowed.`);
+    }
+  }
+  // Remote allowlist: never let a config entry make git contact an arbitrary host.
+  if (!isAllowedGitRemote(url)) {
+    throw new Error(
+      `${pkgName}: refusing a git remote that is not GitHub or a local path: "${redactGitUrl(url)}". ` +
+        `Allowed: https/ssh github.com, file://, or an absolute local path.`,
+    );
+  }
+  const wantRemote = normalizeGitHubRemote(url);
+  const exists = deps.exists(dest);
+  const isGit = deps.exists(path.join(dest, ".git"));
+
+  // Ensure the pinned commit exists locally, fetching the EXACT sha only when
+  // the checkout does not already contain it (the common case — a recorded
+  // branch head — is already present after a branch clone/earlier fetch, so
+  // this avoids a per-repo network round-trip). GitHub serves reachable-sha
+  // fetches; an unreachable pin (force-pushed companion history) fails loud
+  // here — that is the bump-the-lock signal, never a silent fallback to tip.
+  const ensurePinnedCommit = () => {
+    let present = true;
+    try {
+      git(["cat-file", "-e", `${sha}^{commit}`], dest);
+    } catch {
+      present = false;
+    }
+    if (!present) git(["fetch", "origin", sha], dest);
+    git(["checkout", "--detach", sha], dest);
+    const head = git(["rev-parse", "HEAD"], dest).trim();
+    if (head !== sha) {
+      throw new Error(
+        `${pkgName}: pinned checkout verification failed — HEAD is ${head}, expected ${sha}.`,
+      );
+    }
+  };
+
+  // absent OR empty non-git dir -> clone
+  if (!exists || (!isGit && dirIsEmpty(dest, deps))) {
+    log(
+      sha
+        ? `  ${pkgName}: cloning ${redactGitUrl(url)} (pinned ${sha.slice(0, 12)}) -> ${dest}`
+        : `  ${pkgName}: cloning ${redactGitUrl(url)} (${branch}) -> ${dest}`,
+    );
+    deps.mkdirp(path.dirname(dest));
+    git(["clone", "--branch", branch, "--single-branch", "--", url, dest], path.dirname(dest));
+    if (sha) {
+      ensurePinnedCommit();
+      return { pkgName, action: "cloned", changed: true, pinnedSha: sha };
+    }
+    return { pkgName, action: "cloned" };
+  }
+
+  // non-empty non-git dir -> fail
+  if (!isGit) {
+    throw new Error(
+      `${pkgName}: "${dest}" is a non-empty, non-git directory. ` +
+        `Move it aside (or delete it), then re-run \`cinatra setup\`. ` +
+        `Expected a clean clone of ${redactGitUrl(url)}.`,
+    );
+  }
+
+  // git checkout: verify origin + branch (HTTPS ↔ SSH normalized)
+  const originRaw = git(["remote", "get-url", "origin"], dest).trim();
+  const haveRemote = normalizeGitHubRemote(originRaw);
+  const curBranch = git(["rev-parse", "--abbrev-ref", "HEAD"], dest).trim();
+
+  // For GitHub remotes, compare the normalized owner/repo. For local remotes
+  // `normalizeGitHubRemote` returns null for BOTH — comparing null===null would
+  // treat two DIFFERENT repos as the same origin — so fall back to a resolved-path
+  // comparison ONLY when BOTH sides are genuinely local (file:// / absolute path).
+  // A non-GitHub, non-local remote is impossible here (the allowlist rejected it).
+  const originMatches =
+    wantRemote !== null
+      ? haveRemote === wantRemote
+      : isLocalGitRemote(url) && isLocalGitRemote(originRaw) && path.resolve(originRaw) === path.resolve(url);
+
+  // Pinned mode skips the branch-name check (a detached HEAD reports "HEAD",
+  // and a pre-existing branch checkout is simply re-pinned below) — the origin
+  // check still applies in full.
+  if (!originMatches || (sha === undefined && curBranch !== branch)) {
+    // Wrong origin or branch is NEVER auto-reset, even with --force.
+    throw new Error(
+      `${pkgName}: "${dest}" tracks ${redactGitUrl(originRaw) || "(no origin)"} on branch "${curBranch}", ` +
+        `but ${redactGitUrl(url)} on "${branch}" is expected. ` +
+        `Fix the remote/branch or move the directory aside; this is never auto-reset. ` +
+        `(Use ${envOverrideVarFor(pkgName)} to point at a fork/SSH URL.)`,
+    );
+  }
+
+  // clean+correct origin+branch: check dirty
+  const dirty = git(["status", "--porcelain"], dest).trim() !== "";
+
+  if (sha) {
+    // Pinned mode has NO stash/reset path: a dirty tree is a hard fail (CI
+    // checkouts are always fresh; a local pinned run must never destroy work).
+    if (dirty) {
+      throw new Error(
+        `${pkgName}: "${dest}" has uncommitted changes — pinned sync never stashes or resets local work. ` +
+          `Clean the tree (or move the directory aside), then re-run.`,
+      );
+    }
+    const headBefore = git(["rev-parse", "HEAD"], dest).trim();
+    if (headBefore === sha) {
+      // The pinned contract is "AT the pin and DETACHED" — a warm checkout
+      // sitting on a branch that happens to point at the pin is still
+      // detached here (cheap; content unchanged, so `changed` stays false).
+      if (curBranch !== "HEAD") git(["checkout", "--detach", sha], dest);
+      return { pkgName, action: "pinned", changed: false, pinnedSha: sha };
+    }
+    log(`  ${pkgName}: re-pinning ${headBefore.slice(0, 12)} -> ${sha.slice(0, 12)} (detached)`);
+    ensurePinnedCommit();
+    return { pkgName, action: "repinned", changed: true, pinnedSha: sha };
+  }
+  if (dirty) {
+    if (!force) {
+      log(
+        `  ${pkgName}: SKIP — uncommitted changes in ${dest}. ` +
+          `Commit or stash them, or re-run with ${forceFlagHint}.`,
+      );
+      return { pkgName, action: "skipped-dirty" };
+    }
+    log(`  ${pkgName}: --force — stashing local changes, then hard-reset to origin/${branch}`);
+    git(["stash", "push", "--include-untracked", "-m", stashLabel], dest);
+    log(`  ${pkgName}: local changes stashed as "${stashLabel}" — recover via: git -C ${dest} stash list && git -C ${dest} stash pop`);
+  }
+
+  const headBefore = git(["rev-parse", "HEAD"], dest).trim();
+  git(["fetch", "origin", branch], dest);
+  if (force) {
+    git(["reset", "--hard", `origin/${branch}`], dest);
+    return { pkgName, action: "force-reset" };
+  }
+  git(["merge", "--ff-only", `origin/${branch}`], dest);
+  const headAfter = git(["rev-parse", "HEAD"], dest).trim();
+  // `updated` covers BOTH a no-op pull and a real fast-forward. `changed`
+  // distinguishes them so a post-sync workspace re-link runs only when HEAD
+  // actually moved (a ff that may have added/changed deps), not on every warm run.
+  return { pkgName, action: "updated", changed: headBefore !== headAfter };
+}

package/src/extensions-dependency-gate.mjs

@@ -0,0 +1,258 @@
+// Dependency-ordering gate for marketplace submission.
+//
+// Before an extension tarball is submitted to the Cinatra Marketplace, every
+// `@cinatra-ai/*` EXTENSION EDGE it declares in its canonical `cinatra.dependencies`
+// MUST already be published on `registry.cinatra.ai` — those extension packages live
+// ONLY there, never on npmjs. Host-internal SDK/app peers (sdk-extensions, sdk-ui,
+// mcp-client, …) are NOT extension edges: under model-B they are host-provided
+// optional peers, intentionally never on the registry, so the gate SKIPS them
+// (probing would 404/401). Submitting a package whose sibling-extension closure is
+// not yet on the registry would produce a public extension repo that cannot
+// `pnpm install` a sibling it needs. This gate fails BEFORE submit if a real edge
+// is missing.
+//
+// Strict failure semantics:
+//   - 404 / no published versions / no version satisfying the range  → MISSING
+//     (a real ordering violation — publish the closure first).
+//   - 401 / 403                                                       → UNREADABLE
+//     (registry.cinatra.ai requires authentication by design — no read-scope
+//     token is set in this shell). This is NOT "missing" — we simply cannot
+//     verify, so the gate fails closed with a DISTINCT message rather than
+//     green-lighting blindly.
+//   - network / non-JSON / other non-2xx                              → ERROR.
+//
+// Queries ONLY the configured registry (no npmjs fallback — a silent fallback
+// would mask an ordering violation or a registry outage).
+
+import semver from "semver";
+
+export const CINATRA_SCOPE = "@cinatra-ai/";
+export const DEFAULT_REGISTRY_URL = "https://registry.cinatra.ai";
+
+/**
+ * Extract every `@cinatra-ai/*` dependency (name + range + source field) from a
+ * package manifest's `dependencies` and `peerDependencies`.
+ * @param {{dependencies?:Record<string,string>, peerDependencies?:Record<string,string>}} manifest
+ * @returns {Array<{name:string, range:string, field:string}>}
+ */
+export function extractCinatraDeps(manifest) {
+  const out = [];
+  const seen = new Set();
+  for (const field of ["dependencies", "peerDependencies"]) {
+    const deps = manifest?.[field];
+    if (!deps || typeof deps !== "object") continue;
+    for (const [name, range] of Object.entries(deps)) {
+      if (!name.startsWith(CINATRA_SCOPE)) continue;
+      const key = `${name}@${range}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push({ name, range: String(range ?? ""), field });
+    }
+  }
+  return out;
+}
+
+/**
+ * Canonical cross-extension edge names from the manifest's `cinatra.dependencies`
+ * (array of `{packageName}`, array of strings, or a name→spec object).
+ * Only these @cinatra-ai/* deps are real marketplace dependencies that
+ * must be on the registry first; host-internal SDK/app packages (sdk-extensions,
+ * sdk-ui, mcp-client, …) are NEVER declared here — under model-B they are
+ * host-provided OPTIONAL peers, intentionally not on any registry, and the gate
+ * must SKIP them (probing would 404/401).
+ * @param {{cinatra?:{dependencies?:unknown}}} manifest
+ * @returns {string[]}
+ */
+export function extractCinatraManifestDepNames(manifest) {
+  const c = manifest?.cinatra?.dependencies;
+  const out = new Set();
+  if (Array.isArray(c)) {
+    for (const e of c) {
+      if (e && typeof e === "object" && typeof e.packageName === "string") out.add(e.packageName);
+      else if (typeof e === "string") out.add(e.startsWith("@") ? e : `${CINATRA_SCOPE}${e}`);
+    }
+  } else if (c && typeof c === "object") {
+    for (const k of Object.keys(c)) out.add(k);
+  }
+  return [...out];
+}
+
+/**
+ * Select which @cinatra-ai/* deps the ordering gate must verify on the registry:
+ * ONLY the canonical extension edges declared in `cinatra.dependencies`. An npm
+ * dep/peer that is NOT a declared edge is host-internal (a host-provided peer) and
+ * is SKIPPED. An edge declared ONLY in `cinatra.dependencies` (no npm dep entry —
+ * e.g. linkedin→social-media, resend→email) is still probed with range "*".
+ * @param {object} manifest
+ * @returns {{toProbe:Array<{name:string,range:string,field:string}>, skippedNonManifestCinatraDeps:string[]}}
+ */
+export function selectExtensionDepsToProbe(manifest) {
+  const edgeNames = new Set(extractCinatraManifestDepNames(manifest));
+  const npmDeps = extractCinatraDeps(manifest);
+  const toProbe = [];
+  const seen = new Set();
+  for (const d of npmDeps) {
+    if (edgeNames.has(d.name) && !seen.has(d.name)) {
+      toProbe.push(d);
+      seen.add(d.name);
+    }
+  }
+  for (const name of edgeNames) {
+    if (!seen.has(name)) {
+      toProbe.push({ name, range: "*", field: "cinatra.dependencies" });
+      seen.add(name);
+    }
+  }
+  const skippedNonManifestCinatraDeps = npmDeps.filter((d) => !edgeNames.has(d.name)).map((d) => d.name);
+  return { toProbe, skippedNonManifestCinatraDeps };
+}
+
+/** Build the npm-registry packument URL for a scoped package name. */
+function packumentUrl(registryUrl, name) {
+  // Scoped names are URL-encoded with every slash escaped: @scope%2Fname.
+  return `${String(registryUrl).replace(/\/+$/, "")}/${name.replace(/\//g, "%2F")}`;
+}
+
+function authHeader(token) {
+  if (!token) return {};
+  const value = /^(Bearer|Basic)\s/i.test(token) ? token : `Bearer ${token}`;
+  return { authorization: value };
+}
+
+/** True when at least one published version satisfies the declared range. */
+export function isRangeSatisfied(range, versions, distTags = {}) {
+  const r = String(range ?? "").trim();
+  // The companion repos convert workspace deps to peerDependencies "*"; any
+  // published version satisfies. Empty / "x" / "latest" behave the same.
+  if (r === "" || r === "*" || r === "x" || r === "latest") return versions.length > 0;
+  // A dist-tag reference (e.g. "next") is satisfied if that tag exists.
+  if (Object.prototype.hasOwnProperty.call(distTags, r)) return true;
+  try {
+    return versions.some((v) => semver.satisfies(v, r, { includePrerelease: false }));
+  } catch {
+    // Unparseable range (git/url/file spec) — existence is the best we can do;
+    // treat a published package as satisfying and let marketplace-side checks
+    // own the deeper validation.
+    return versions.length > 0;
+  }
+}
+
+/**
+ * Probe one `@cinatra-ai/*` dependency against the registry.
+ * @returns {Promise<{name,range,field,state:'satisfied'|'unsatisfied'|'missing'|'unreadable'|'error', detail?:string, status?:number, versions?:string[]}>}
+ */
+export async function probeDep(dep, { registryUrl, token, fetchImpl }) {
+  const url = packumentUrl(registryUrl, dep.name);
+  let res;
+  try {
+    res = await fetchImpl(url, { headers: { accept: "application/json", ...authHeader(token) } });
+  } catch (err) {
+    return { ...dep, state: "error", detail: err instanceof Error ? err.message : String(err) };
+  }
+  if (res.status === 401 || res.status === 403) {
+    return { ...dep, state: "unreadable", status: res.status };
+  }
+  if (res.status === 404) {
+    return { ...dep, state: "missing", status: 404, detail: "not found on the registry" };
+  }
+  if (!res.ok) {
+    return { ...dep, state: "error", status: res.status, detail: `unexpected HTTP ${res.status}` };
+  }
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    return { ...dep, state: "error", detail: "registry returned a non-JSON packument" };
+  }
+  const versions = Object.keys(body?.versions ?? {});
+  const distTags = body?.["dist-tags"] ?? {};
+  if (versions.length === 0) {
+    return { ...dep, state: "missing", detail: "no published versions" };
+  }
+  return isRangeSatisfied(dep.range, versions, distTags)
+    ? { ...dep, state: "satisfied" }
+    : { ...dep, state: "unsatisfied", versions };
+}
+
+/**
+ * Check that every `@cinatra-ai/*` dependency of `manifest` is published on the
+ * registry. Resolves to a structured report; never throws on a gate violation
+ * (the caller decides). Throws only on a programming error.
+ */
+export async function checkDependencyOrdering({
+  manifest,
+  registryUrl = DEFAULT_REGISTRY_URL,
+  token,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  if (typeof fetchImpl !== "function") {
+    throw new Error("checkDependencyOrdering: no fetch implementation available");
+  }
+  // Probe ONLY canonical extension edges (cinatra.dependencies); host-internal
+  // @cinatra-ai/* peers are host-provided under model-B and never on the registry.
+  const { toProbe: deps, skippedNonManifestCinatraDeps } = selectExtensionDepsToProbe(manifest);
+  const results = [];
+  for (const dep of deps) {
+    results.push(await probeDep(dep, { registryUrl, token, fetchImpl }));
+  }
+  const missing = results.filter((r) => r.state === "missing" || r.state === "unsatisfied");
+  const unreadable = results.filter((r) => r.state === "unreadable");
+  const errored = results.filter((r) => r.state === "error");
+  const satisfied = results.filter((r) => r.state === "satisfied");
+  return {
+    ok: missing.length === 0 && unreadable.length === 0 && errored.length === 0,
+    registryUrl,
+    deps,
+    skippedNonManifestCinatraDeps,
+    results,
+    missing,
+    unreadable,
+    errored,
+    satisfied,
+  };
+}
+
+/** Render a human-readable failure message for a non-ok report. */
+export function formatGateFailure(report) {
+  const lines = [];
+  if (report.missing.length > 0) {
+    lines.push(
+      `Dependency-ordering gate FAILED — ${report.missing.length} @cinatra-ai/* dependency(ies) not on ${report.registryUrl}:`,
+    );
+    for (const m of report.missing) {
+      lines.push(
+        `  • ${m.name}@${m.range} [${m.field}] — ${m.state === "unsatisfied" ? `no published version satisfies (have: ${(m.versions || []).join(", ") || "none"})` : m.detail || "missing"}`,
+      );
+    }
+    lines.push(
+      "Publish the missing @cinatra-ai/* dependency extension(s) (in dependency order) THROUGH the marketplace storefront FIRST, then re-submit. (These are dependency extensions, not the host SDK.)",
+    );
+  }
+  if (report.unreadable.length > 0) {
+    lines.push(
+      `Dependency-ordering gate could NOT verify — ${report.registryUrl} returned ${report.unreadable[0].status} (registry not readable):`,
+    );
+    for (const u of report.unreadable) lines.push(`  • ${u.name}@${u.range} [${u.field}]`);
+    lines.push(
+      "registry.cinatra.ai requires authentication by design — export a read-scope CINATRA_REGISTRY_TOKEN, then re-run. " +
+        "(Use --skip-dependency-check only if you have independently confirmed the closure is published.)",
+    );
+  }
+  if (report.errored.length > 0) {
+    lines.push(`Dependency-ordering gate hit ${report.errored.length} registry error(s):`);
+    for (const e of report.errored) lines.push(`  • ${e.name}@${e.range}: ${e.detail || `HTTP ${e.status}`}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Assert the dependency-ordering gate passes. Throws with a formatted message
+ * on any violation (missing / unreadable / error). Returns the report on pass.
+ */
+export async function assertDependencyOrdering(opts) {
+  const report = await checkDependencyOrdering(opts);
+  if (!report.ok) {
+    throw new Error(formatGateFailure(report));
+  }
+  return report;
+}