cinatra 0.1.0

package/src/checkout-resolve.mjs

@@ -0,0 +1,236 @@
+// packages/cli/src/checkout-resolve.mjs (published as `cinatra/src/checkout-resolve.mjs`)
+//
+// Runtime resolution of the internal `@cinatra-ai/*` workspace packages from the
+// operator's CINATRA CHECKOUT — never from the published `cinatra` CLI's own
+// dependency tree.
+//
+// WHY THIS EXISTS (cinatra#402, P1 extraction)
+// --------------------------------------------
+// The `cinatra` CLI is a THIN, dependency-light driver published to npm. It is
+// deliberately decoupled from the heavy in-repo workspace packages it drives:
+//
+//   - `@cinatra-ai/migrations`           — the node-pg-migrate runner + SQL chain
+//   - `@cinatra-ai/connectors-catalog`   — the CLI-safe connector descriptors
+//   - `@cinatra-ai/skills`               — the agent-skill compile/register walker
+//
+// Bundling any of these into the published tarball would (a) re-couple the CLI
+// to the monorepo's heavy server graph and (b) ship a STALE copy of code that
+// must always match the checkout it operates on. So the CLI resolves them at
+// COMMAND ENTRY from the checkout's own `node_modules`, against the checkout's
+// installed versions.
+//
+// CODEX must-fix #2 — DO NOT file://-path-only resolve
+// ----------------------------------------------------
+// A naive `import(pathToFileURL(<repoRoot>/packages/<pkg>/...))` is wrong:
+// in the BAKED production runtime image only `packages/migrations` physical
+// source is guaranteed (Next.js output-file-tracing copies it explicitly; the
+// other workspace packages may be absent there). So the primary path is a
+// node-module resolution anchored at the checkout root (which honors the
+// package's `exports`/subpaths and finds the real installed copy), with a
+// guaranteed-source self-resolution fallback used ONLY for migrations.
+//
+// SECURITY / CORRECTNESS (per codex review of this shim)
+// ------------------------------------------------------
+//   - Only `@cinatra-ai/*` specifiers are accepted (no builtins, no escape).
+//   - Resolution is anchored at an ABSOLUTE `<repoRoot>/package.json`.
+//   - The resolved file is realpath-contained within the checkout (realpath +
+//     `path.relative`, NOT brittle `startsWith`; pnpm symlinks realpath to
+//     `<repoRoot>/packages/*` and `<repoRoot>/node_modules/.pnpm/*`, both inside
+//     the checkout).
+//   - The OWNING package's `package.json#name` is verified to equal the
+//     expected `@cinatra-ai/*` package (defense against a spoofed resolution).
+//   - The expected package name is REQUIRED (derived from the specifier).
+
+import { createRequire } from "node:module";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const CINATRA_SCOPE = "@cinatra-ai/";
+
+/**
+ * `@cinatra-ai/migrations` → `@cinatra-ai/migrations`
+ * `@cinatra-ai/skills/cli` → `@cinatra-ai/skills`
+ * `@cinatra-ai/connectors-catalog/descriptors.mjs` → `@cinatra-ai/connectors-catalog`
+ */
+function packageNameFromSpecifier(specifier) {
+  if (typeof specifier !== "string" || !specifier.startsWith(CINATRA_SCOPE)) {
+    throw new Error(
+      `checkout-resolve: refusing to resolve non-@cinatra-ai specifier "${specifier}".`,
+    );
+  }
+  const parts = specifier.split("/");
+  // ["@cinatra-ai", "<pkg>", ...subpath]
+  return `${parts[0]}/${parts[1]}`;
+}
+
+/**
+ * The cinatra checkout sentinel — the pnpm workspace manifest AND the
+ * never-removed internal `@cinatra-ai/migrations` package manifest (by exact
+ * name). Mirrors `isCinatraRepoRoot` / `isCinatraCheckout` in index.mjs /
+ * install.mjs; deliberately does NOT gate on `packages/cli` (that package goes
+ * external at P1/P2) nor on the bin-colliding root name `cinatra`.
+ */
+function assertCinatraCheckout(repoRoot) {
+  const ws = path.join(repoRoot, "pnpm-workspace.yaml");
+  const migPkg = path.join(repoRoot, "packages", "migrations", "package.json");
+  if (!existsSync(ws)) {
+    throw new Error(
+      `checkout-resolve: "${repoRoot}" is not a cinatra checkout (missing pnpm-workspace.yaml).`,
+    );
+  }
+  let migName;
+  try {
+    migName = JSON.parse(readFileSync(migPkg, "utf8"))?.name;
+  } catch {
+    migName = undefined;
+  }
+  if (migName !== "@cinatra-ai/migrations") {
+    throw new Error(
+      `checkout-resolve: "${repoRoot}" is not a cinatra checkout ` +
+        `(packages/migrations/package.json missing or not @cinatra-ai/migrations).`,
+    );
+  }
+}
+
+/** Best-effort native realpath; falls back to the resolved absolute path. */
+function realpath(p) {
+  try {
+    return realpathSync.native(path.resolve(p));
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+/** True iff `child` is `root` or a descendant of `root` (realpath-aware). */
+function isContained(root, child) {
+  const rel = path.relative(realpath(root), realpath(child));
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
+/**
+ * Walk up from `fromFile` to find the owning `package.json` and assert its
+ * `name` equals `expectName`. Bounded at the checkout root.
+ */
+function assertOwningPackageName(fromFile, expectName, repoRoot) {
+  const rootReal = realpath(repoRoot);
+  let dir = path.dirname(path.resolve(fromFile));
+  for (;;) {
+    const pkgPath = path.join(dir, "package.json");
+    if (existsSync(pkgPath)) {
+      let name;
+      try {
+        name = JSON.parse(readFileSync(pkgPath, "utf8"))?.name;
+      } catch {
+        name = undefined;
+      }
+      if (name === expectName) return;
+      // A nested package.json without the expected name — keep walking up only
+      // while still inside the checkout; a node_modules entry's own
+      // package.json is the authoritative owner, so a mismatch here is fatal.
+      throw new Error(
+        `checkout-resolve: resolved "${expectName}" to a file owned by ` +
+          `package "${name ?? "<unknown>"}" (${pkgPath}); refusing to import.`,
+      );
+    }
+    const parent = path.dirname(dir);
+    // Stop at the checkout root or the filesystem root.
+    if (parent === dir || realpath(dir) === rootReal) {
+      throw new Error(
+        `checkout-resolve: could not find the owning package.json for "${expectName}".`,
+      );
+    }
+    dir = parent;
+  }
+}
+
+/**
+ * Resolve a checkout-local `@cinatra-ai/*` specifier to an absolute file path,
+ * validating containment + owning-package name. Returns the absolute path.
+ *
+ * Primary: `createRequire(<repoRoot>/package.json).resolve(specifier)` — honors
+ * the package's `exports` subpaths (e.g. `@cinatra-ai/skills/cli`) and finds the
+ * real installed copy in the checkout's node_modules.
+ *
+ * Fallback (migrations ONLY, the guaranteed-source package): self-resolve from
+ * inside `<repoRoot>/packages/migrations` so a baked prod image whose top-level
+ * node_modules lacks the workspace symlink still resolves.
+ */
+function resolveCheckoutFile(repoRoot, specifier) {
+  const expectName = packageNameFromSpecifier(specifier);
+  const rootAbs = path.resolve(repoRoot);
+
+  // A resolved path is USABLE only if it is absolute, realpath-contained within
+  // the checkout, and owned by the expected `@cinatra-ai/*` package. Returns
+  // null (NOT throw) for an unusable candidate so the migrations fallback can
+  // still run when the PRIMARY resolution points OUTSIDE the checkout (e.g. the
+  // published CLI is installed inside an ambient parent's node_modules and
+  // require.resolve found that copy) — codex must-fix: an outside/mismatched
+  // primary must not pre-empt the guaranteed-source fallback.
+  const validate = (resolved) => {
+    if (!resolved || !path.isAbsolute(resolved)) return null;
+    if (!isContained(rootAbs, resolved)) return null;
+    try {
+      assertOwningPackageName(resolved, expectName, rootAbs);
+    } catch {
+      return null;
+    }
+    return resolved;
+  };
+
+  const tryResolveFrom = (anchorPkgJson) => {
+    try {
+      return createRequire(anchorPkgJson).resolve(specifier);
+    } catch {
+      return null;
+    }
+  };
+
+  // Primary: resolve from the checkout root (honors `exports` subpaths and finds
+  // the installed copy in the checkout's node_modules).
+  let usable = validate(tryResolveFrom(path.join(rootAbs, "package.json")));
+
+  // Fallback for migrations ONLY (the package guaranteed present in the baked
+  // prod image): self-resolve from inside `<repoRoot>/packages/migrations` so a
+  // missing top-level workspace symlink — OR an ambient-parent primary that
+  // failed containment above — still resolves to the in-checkout source.
+  if (!usable && expectName === "@cinatra-ai/migrations") {
+    const pkgJson = path.join(rootAbs, "packages", "migrations", "package.json");
+    if (existsSync(pkgJson)) {
+      usable = validate(tryResolveFrom(pkgJson));
+    }
+  }
+
+  if (!usable) {
+    throw new Error(
+      `checkout-resolve: cannot resolve "${specifier}" to an in-checkout copy of ` +
+        `${expectName} from the cinatra checkout at ${rootAbs} (not installed, or it ` +
+        `resolved OUTSIDE the checkout). Run the install step (pnpm install) inside ` +
+        `the checkout so its workspace packages are present.`,
+    );
+  }
+  return usable;
+}
+
+/**
+ * Resolve AND dynamically import a checkout-local `@cinatra-ai/*` module.
+ *
+ * @param {string} repoRoot  Absolute path to the cinatra checkout root.
+ * @param {string} specifier e.g. "@cinatra-ai/migrations",
+ *                           "@cinatra-ai/skills/cli",
+ *                           "@cinatra-ai/connectors-catalog/descriptors.mjs".
+ * @returns {Promise<object>} The imported module namespace.
+ */
+export async function importFromCheckout(repoRoot, specifier) {
+  assertCinatraCheckout(repoRoot);
+  const resolved = resolveCheckoutFile(repoRoot, specifier);
+  return import(pathToFileURL(resolved).href);
+}
+
+// Exposed for unit tests.
+export const __test = {
+  packageNameFromSpecifier,
+  isContained,
+  resolveCheckoutFile,
+  assertCinatraCheckout,
+};

package/src/cinatra-dev-extensions.mjs

@@ -0,0 +1,338 @@
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import { defaultRepoSyncDeps, normalizeGitHubRemote, syncOneRepo } from "./dev-repo-sync.mjs";
+
+// ---------------------------------------------------------------------------
+// `cinatra setup` dev-extension clone bootstrap.
+//
+// Dev consumes each extension from a git checkout under
+// `extensions/<scope>/<name>/` (git-ignored after the cutover). This module
+// clones-or-fast-forwards each entry of `package.json` `cinatra.devExtensions`
+// (the `cinatra.devExtensions` map, placed under the `cinatra` key for
+// consistency with `devApps`/`extensions`) into its slot.
+//
+// It REUSES the proven five-state tree-safety model from
+// `dev-repo-sync.mjs` (`syncOneRepo`): absent/empty → clone; clean
+// + correct origin/branch → fetch + ff-only (force: hard reset); dirty → skip
+// unless force; wrong origin/branch → hard fail even with force; non-empty
+// non-git → hard fail.
+//
+// `--pinned` (CI; cinatra#141) swaps tip-tracking for detached checkouts at
+// the shas committed in the two lock files (see `loadDevExtensionPins`), so a
+// companion-repo merge can never change what a host CI run validates. Local
+// `cinatra setup` keeps tip-tracking — devs want tips.
+//
+// `syncCinatraDevExtensions` returns `{ skipped: true, reason: "no-config" }` on
+// an empty map, or `{ results: [...] }` with one entry per selected extension
+// (`{ pkgName, action, kind, dest }`). A caller that materializes new checkouts
+// (a fresh clone or a `--force` reset) MUST re-run `pnpm install` afterward so the
+// newly-present extension packages are linked into the pnpm workspace — pnpm only
+// creates an extension's per-extension `node_modules` (and links its transitive
+// deps) when the package exists on disk at install time, so a package cloned in
+// AFTER the initial install stays unlinked until the next install. See
+// `installAfterExtensionSync` in index.mjs (the `setup dev` / `setup clone` flows).
+// ---------------------------------------------------------------------------
+
+const KIND_SUFFIXES = [
+  ["-agent", "agent"],
+  ["-connector", "connector"],
+  ["-artifact", "artifact"],
+  ["-skills", "skill"],
+  ["-skill", "skill"],
+  ["-workflow", "workflow"],
+];
+
+/** Derive the extension kind WITHOUT cloning — from a declared `kind` or the
+ * package-name suffix (best-effort; null when unknown). `--kind` filtering must
+ * not require a not-yet-cloned package.json. */
+export function deriveKindFromName(pkgName, declaredKind) {
+  if (declaredKind) return declaredKind;
+  const short = String(pkgName).replace(/^@[^/]+\//, "");
+  for (const [suffix, kind] of KIND_SUFFIXES) if (short.endsWith(suffix)) return kind;
+  return null;
+}
+
+// A real scoped npm name: @scope/name with conservative segment chars — NO "/"
+// inside the name segment, no "..", no leading dot. Blocks path-traversal config
+// keys like `@cinatra-ai/../../outside` from escaping the extensions tree.
+const SAFE_SCOPED_PKG_RE = /^@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/;
+
+/** Throw unless `dest` resolves to a path strictly INSIDE `rootDir`. */
+function assertContainedIn(rootDir, dest, pkgName, label) {
+  const rel = path.relative(path.resolve(rootDir), dest);
+  if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) {
+    throw new Error(
+      `[cinatra dev-extensions] refusing a destination outside ${label}: "${pkgName}" → "${dest}".`,
+    );
+  }
+  return dest;
+}
+
+/** `@scope/name` → `<targetRoot>/extensions/<scope>/<name>` (or spec.path).
+ * Hardened: an explicit `spec.path` may live anywhere UNDER the repo/worktree
+ * root but never escape it (blocks absolute paths + `../` traversal); a derived
+ * path requires a valid scoped package name + is contained to `extensions/`. */
+export function destDirForExtension(pkgName, spec, targetRoot) {
+  if (spec?.path) {
+    const dest = path.resolve(targetRoot, spec.path);
+    return assertContainedIn(targetRoot, dest, pkgName, "the repo root");
+  }
+  if (!SAFE_SCOPED_PKG_RE.test(String(pkgName))) {
+    throw new Error(
+      `[cinatra dev-extensions] invalid extension package name "${pkgName}" — expected @scope/name ` +
+        `(lowercase; no "/" in the name segment, no "..").`,
+    );
+  }
+  const m = String(pkgName).match(/^@([^/]+)\/(.+)$/);
+  const dest = path.resolve(targetRoot, "extensions", m[1], m[2]);
+  return assertContainedIn(path.join(targetRoot, "extensions"), dest, pkgName, "extensions/");
+}
+
+export function readDevExtensionsConfig(repoRoot, readFile = readFileSync) {
+  try {
+    const pkg = JSON.parse(readFile(path.join(repoRoot, "package.json"), "utf8"));
+    // The dev-extension clone set lives under `cinatra.devExtensions`
+    // (consistent with `cinatra.devApps`).
+    const cfg = pkg?.cinatra?.devExtensions;
+    return cfg && typeof cfg === "object" ? cfg : null;
+  } catch {
+    return null;
+  }
+}
+
+const shortName = (pkgName) => String(pkgName).replace(/^@[^/]+\//, "");
+
+// ---------------------------------------------------------------------------
+// Pinned mode (cinatra#141): CI checks out every dev extension DETACHED at a
+// committed lock sha instead of tracking branch tips, so a companion-repo
+// merge can never change what a host CI run validates.
+//
+// The pin set is PARTITIONED across two committed locks, with no overlap:
+//   - cinatra-required-extensions.lock.json — the prod bootable set (also the
+//     image build's acquisition source; it stays the SINGLE authority for
+//     those packages — never duplicated into the dev lock);
+//   - cinatra-dev-extensions.lock.json — every OTHER cinatra.devExtensions
+//     entry (regenerated by scripts/extensions/update-dev-extension-lock.mjs).
+// ---------------------------------------------------------------------------
+
+// Kept in lockstep with prod-extension-acquisition.mjs `LOCK_FILENAME` (not
+// imported from there: that module imports `destDirForExtension` from THIS
+// one, and the consistency test asserts the strings stay equal).
+export const REQUIRED_EXTENSIONS_LOCK_FILENAME = "cinatra-required-extensions.lock.json";
+export const DEV_EXTENSIONS_LOCK_FILENAME = "cinatra-dev-extensions.lock.json";
+
+const PIN_SHA_RE = /^[0-9a-f]{40}$/;
+const REPO_SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+function readPinLock(repoRoot, filename, readFile, { allowEmpty = false } = {}) {
+  let raw;
+  try {
+    raw = readFile(path.join(repoRoot, filename), "utf8");
+  } catch {
+    throw new Error(
+      `[cinatra dev-extensions] pinned sync requires the committed ${filename}, which could not be read. ` +
+        `Regenerate it (scripts/extensions/update-${filename.includes("-dev-") ? "dev" : "required"}-extension-lock.mjs) and commit it.`,
+    );
+  }
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`[cinatra dev-extensions] ${filename} is not valid JSON: ${err.message}`);
+  }
+  const packages = Array.isArray(doc?.packages) ? doc.packages : null;
+  if (!packages || (packages.length === 0 && !allowEmpty)) {
+    throw new Error(`[cinatra dev-extensions] ${filename} has no "packages" entries — refusing pinned sync.`);
+  }
+  const seen = new Set();
+  for (const [i, p] of packages.entries()) {
+    const tag = `${filename} packages[${i}]`;
+    if (!p || typeof p !== "object" || typeof p.packageName !== "string") {
+      throw new Error(`[cinatra dev-extensions] ${tag}: not an object with a packageName.`);
+    }
+    if (typeof p.resolvedSha !== "string" || !PIN_SHA_RE.test(p.resolvedSha)) {
+      throw new Error(`[cinatra dev-extensions] ${tag} (${p.packageName}): resolvedSha must be a 40-hex lowercase commit sha.`);
+    }
+    if (typeof p.repo !== "string" || !REPO_SLUG_RE.test(p.repo) || p.repo.includes("..")) {
+      throw new Error(`[cinatra dev-extensions] ${tag} (${p.packageName}): repo must be an "owner/name" GitHub slug.`);
+    }
+    // Duplicates WITHIN one lock would make the later merge order-dependent
+    // (last entry silently wins) — refuse them here, fail-closed.
+    if (seen.has(p.packageName)) {
+      throw new Error(`[cinatra dev-extensions] ${tag}: duplicate pin for "${p.packageName}" in ${filename}.`);
+    }
+    seen.add(p.packageName);
+  }
+  return packages;
+}
+
+const configUrlOf = (spec) => (spec && typeof spec === "object" ? spec.url : String(spec));
+
+/**
+ * Build the fail-closed pkgName -> { sha, repo, source } pin map for pinned
+ * sync. Throws (never degrades to tip-tracking) when:
+ *   - either lock is missing/malformed;
+ *   - a package is pinned in BOTH locks (two authorities = divergence risk);
+ *   - a dev-lock entry is not in `cinatra.devExtensions` (stale pin);
+ *   - a config entry has no pin in either lock (unpinnable universe);
+ *   - a lock `repo` slug contradicts the COMMITTED config URL (a
+ *     CINATRA_*_REPO_URL env override is deliberately NOT consulted here — an
+ *     override is only an alternate remote that must still serve the pin).
+ */
+export function loadDevExtensionPins(repoRoot, readFile = readFileSync) {
+  const config = readDevExtensionsConfig(repoRoot, readFile);
+  if (!config || Object.keys(config).length === 0) {
+    throw new Error("[cinatra dev-extensions] pinned sync requires a non-empty `cinatra.devExtensions` config.");
+  }
+  const required = readPinLock(repoRoot, REQUIRED_EXTENSIONS_LOCK_FILENAME, readFile);
+  // An empty dev lock is legal IFF the required lock covers the whole
+  // universe (the per-entry completeness check below still enforces that).
+  const dev = readPinLock(repoRoot, DEV_EXTENSIONS_LOCK_FILENAME, readFile, { allowEmpty: true });
+
+  const pins = new Map();
+  for (const p of required) {
+    pins.set(p.packageName, { sha: p.resolvedSha, repo: p.repo, source: REQUIRED_EXTENSIONS_LOCK_FILENAME });
+  }
+  for (const p of dev) {
+    if (pins.has(p.packageName)) {
+      throw new Error(
+        `[cinatra dev-extensions] "${p.packageName}" is pinned in BOTH locks — the required lock is the sole ` +
+          `authority for its packages; remove the duplicate from ${DEV_EXTENSIONS_LOCK_FILENAME} ` +
+          `(regenerate it via scripts/extensions/update-dev-extension-lock.mjs).`,
+      );
+    }
+    if (!(p.packageName in config)) {
+      throw new Error(
+        `[cinatra dev-extensions] ${DEV_EXTENSIONS_LOCK_FILENAME} pins "${p.packageName}", which is not a ` +
+          `cinatra.devExtensions entry — stale pin; regenerate the dev lock.`,
+      );
+    }
+    pins.set(p.packageName, { sha: p.resolvedSha, repo: p.repo, source: DEV_EXTENSIONS_LOCK_FILENAME });
+  }
+
+  for (const [pkgName, spec] of Object.entries(config)) {
+    const pin = pins.get(pkgName);
+    if (!pin) {
+      throw new Error(
+        `[cinatra dev-extensions] "${pkgName}" has no pin in ${REQUIRED_EXTENSIONS_LOCK_FILENAME} or ` +
+          `${DEV_EXTENSIONS_LOCK_FILENAME} — pinned sync is fail-closed. Regenerate the dev lock ` +
+          `(scripts/extensions/update-dev-extension-lock.mjs) and commit it.`,
+      );
+    }
+    // Repo-slug cross-check against the COMMITTED config URL. Local remotes
+    // (file:// / absolute path — test fixtures) normalize to null and skip it.
+    const want = normalizeGitHubRemote(configUrlOf(spec));
+    if (want !== null && pin.repo.toLowerCase() !== want) {
+      throw new Error(
+        `[cinatra dev-extensions] "${pkgName}": lock pins repo "${pin.repo}" but the committed config URL ` +
+          `resolves to "${want}" — retargeted repo without a re-pin; regenerate the lock entry.`,
+      );
+    }
+  }
+  return pins;
+}
+
+export function parseDevExtensionFlags(argv = []) {
+  const val = (flag) => {
+    const i = argv.indexOf(flag);
+    return i >= 0 && argv[i + 1] ? argv[i + 1] : null;
+  };
+  const list = (v) => (v ? v.split(",").map((s) => s.trim()).filter(Boolean) : []);
+  const jobs = parseInt(val("--jobs") ?? "1", 10);
+  return {
+    select: list(val("--select")),
+    kinds: list(val("--kind")),
+    exclude: list(val("--exclude")),
+    jobs: Number.isFinite(jobs) && jobs > 0 ? jobs : 1,
+    force: argv.includes("--force"),
+    // CI mode (cinatra#141): detached checkouts at the committed lock shas
+    // instead of branch tips. Mutually exclusive with --force by design — the
+    // pinned path has no stash/reset semantics.
+    pinned: argv.includes("--pinned"),
+  };
+}
+
+/** Apply `--select` / `--kind` / `--exclude` (match full or short name). */
+export function selectEntries(config, flags) {
+  const entries = Object.entries(config).map(([pkgName, spec]) => {
+    const normalized = spec && typeof spec === "object" ? spec : { url: String(spec) };
+    return { pkgName, spec: normalized, kind: deriveKindFromName(pkgName, normalized.kind) };
+  });
+  const matches = (set, e) => set.includes(e.pkgName) || set.includes(shortName(e.pkgName));
+  return entries.filter((e) => {
+    if (flags.select.length && !matches(flags.select, e)) return false;
+    if (flags.exclude.length && matches(flags.exclude, e)) return false;
+    if (flags.kinds.length && (!e.kind || !flags.kinds.includes(e.kind))) return false;
+    return true;
+  });
+}
+
+/** "@cinatra-ai/foo-agent" → "CINATRA_FOO_AGENT_REPO_URL" */
+export function extensionEnvOverrideVarFor(pkgName) {
+  return `CINATRA_${shortName(pkgName).replace(/[^a-zA-Z0-9]+/g, "_").toUpperCase()}_REPO_URL`;
+}
+
+/**
+ * Clone-or-pull every selected `cinatra.devExtensions` entry into its
+ * `extensions/<scope>/<name>` slot under `targetRoot`. Sequential (the clone
+ * correctness is the point; `--jobs` is parsed + reserved for a later perf pass,
+ * since the underlying git is synchronous and the dev config is empty today).
+ */
+export async function syncCinatraDevExtensions({
+  repoRoot,
+  targetRoot,
+  argv = [],
+  env = process.env,
+  log = console.log,
+  deps,
+} = {}) {
+  const config = readDevExtensionsConfig(repoRoot, deps?.readFile);
+  if (!config || Object.keys(config).length === 0) {
+    return { skipped: true, reason: "no-config" };
+  }
+  const flags = parseDevExtensionFlags(argv);
+  if (flags.pinned && flags.force) {
+    throw new Error(
+      "[cinatra dev-extensions] --pinned and --force are mutually exclusive — pinned sync never stashes or resets local work.",
+    );
+  }
+  // Fail-closed BEFORE any git work: every config entry must be pinnable, or
+  // pinned sync refuses outright (a partially-pinned universe would mix
+  // committed state with floating tips).
+  const pins = flags.pinned ? loadDevExtensionPins(repoRoot, deps?.readFile) : null;
+  const selected = selectEntries(config, flags);
+  if (selected.length === 0) {
+    log("- Dev extensions: nothing matched the --select/--kind/--exclude filters.");
+    return { results: [] };
+  }
+  // Merge over defaults so a caller can inject ONE dep (e.g. `readFile` for
+  // config, or a fake `git` in tests) without having to supply the whole git-op
+  // surface (`exists`/`git`/`mkdirp`/`readdir`) that `syncOneRepo` needs.
+  const realDeps = deps ? { ...defaultRepoSyncDeps(), ...deps } : defaultRepoSyncDeps();
+  const results = [];
+  log(
+    `- Dev extensions (${selected.length} selected${flags.pinned ? ", pinned to the committed lock shas" : ""}${flags.jobs > 1 ? `, --jobs ${flags.jobs} reserved` : ""}):`,
+  );
+  for (const { pkgName, spec, kind } of selected) {
+    const url = env[extensionEnvOverrideVarFor(pkgName)] || spec.url;
+    const branch = spec.branch || "main";
+    const dest = destDirForExtension(pkgName, spec, targetRoot);
+    const r = syncOneRepo({
+      pkgName,
+      url,
+      branch,
+      // An env-override remote (fork/mirror) must still SERVE the pinned sha;
+      // it never unpins (loadDevExtensionPins validated the lock against the
+      // committed config URL, not the override).
+      sha: pins ? pins.get(pkgName).sha : undefined,
+      dest,
+      force: flags.force,
+      deps: realDeps,
+      log,
+      forceFlagHint: "--force",
+      stashLabel: "cinatra setup --force (devExtensions)",
+    });
+    results.push({ ...r, kind, dest });
+  }
+  return { results };
+}