cinatra 0.1.0

package/src/command-table.mjs

@@ -0,0 +1,390 @@
+// ---------------------------------------------------------------------------
+// Declarative command table for the `cinatra` CLI (cinatra#255 Stage-1).
+//
+// Plain ESM `.mjs`, NO imports, NO heavy deps — importable from anywhere
+// (including the eager-`pg`-free unit tests). This module owns the DECLARATIVE
+// shape of the command surface (the descriptors) and the PURE matching +
+// help-index logic; `index.mjs` owns the HANDLERS (keyed by `id`) that close
+// over the run* implementations and their lazy `import()`s.
+//
+// Why the split: the dispatcher in `index.mjs` was a hand-maintained ~200-line
+// `if`-chain and the help banner (`printHelp`) was a separate hand-maintained
+// string — the two drifted independently. The descriptors below are the single
+// source of truth for "what commands exist"; the matcher replaces the if-chain
+// (first-match-wins, identical semantics) and `buildHelpIndex` lets a drift test
+// assert the help banner and the dispatcher stay in lockstep.
+//
+// IMPORTANT — behavior-preserving contract (do not "improve" without care):
+//   * Ordering is significant. `matchDescriptor` scans the array top-to-bottom
+//     and returns the FIRST match, mirroring the original if-chain exactly. Do
+//     not reorder for aesthetics, and do not switch to a trie / longest-match.
+//   * Match kinds mirror the original guards precisely:
+//       - "command"        : matches on `argv[0]` ALONE, ignoring `mode`
+//                            (e.g. `status`, `doctor` — `cinatra status x` still
+//                            routed to status, as the original `command===` did).
+//       - "command+mode"   : matches `argv[0]` AND `argv[1]`.
+//       - "command+mode+sub": matches `argv[0]`, `argv[1]`, AND `argv[2]`
+//                            (the `rest[0]` 3-token guards: `mcp llm-access …`).
+//   * Handlers receive the LEGACY `rest = argv.slice(2)` (NOT a descriptor-
+//     relative remainder). The 3-token handlers re-slice themselves
+//     (`mcp llm-access verify` uses `rest.slice(1)`), exactly as before.
+//   * `hidden: true` marks dispatch-only descriptors that have no standalone
+//     help row (the env-driven `setup` no-mode entry and the removed
+//     `mcp tunnel` stub). The dispatcher still routes them; the help banner does
+//     not advertise them. So descriptors are NOT 1:1 with help rows.
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} CommandDescriptor
+ * @property {string} id        Stable handler key (index.mjs HANDLERS[id]).
+ * @property {string[]} path    The literal token(s) that route to this command.
+ * @property {"command"|"command-no-mode"|"command+mode"|"command+mode+sub"} match  Match kind.
+ * @property {boolean} [hidden] Dispatch-only (no standalone help row) when true.
+ * @property {string} [summary] One-line description for the help index.
+ */
+
+/**
+ * The canonical command surface, in dispatch order. The order MUST match the
+ * original `runCli` if-chain so first-match-wins semantics are preserved.
+ *
+ * @type {CommandDescriptor[]}
+ */
+export const COMMAND_DESCRIPTORS = [
+  {
+    id: "install",
+    path: ["install"],
+    match: "command",
+    summary: "Bootstrap a Cinatra dev/prod instance from zero (clone, env, infra, setup).",
+  },
+  {
+    id: "login",
+    path: ["login"],
+    match: "command",
+    summary: "Sign in to a Cinatra instance (browser OAuth) and cache the token.",
+  },
+  {
+    id: "status",
+    path: ["status"],
+    match: "command",
+    summary: "Show current setup state (auth tables, user count, MCP config).",
+  },
+  {
+    id: "skills.reset-repo",
+    path: ["skills", "reset-repo"],
+    match: "command+mode",
+    summary: "Force-push the local skills store to the connected GitHub repo (dev only).",
+  },
+  {
+    id: "extensions.purge",
+    path: ["extensions", "purge"],
+    match: "command+mode",
+    summary: "Fully remove an extension everywhere (dev only; loopback; destructive).",
+  },
+  {
+    id: "extensions.acquire-prod",
+    path: ["extensions", "acquire-prod"],
+    match: "command+mode",
+    summary: "Download the production required-extension set into extensions/.",
+  },
+  {
+    id: "extensions.submit",
+    path: ["extensions", "submit"],
+    match: "command+mode",
+    summary: "Submit a built extension tarball to the Cinatra Marketplace for review.",
+  },
+  {
+    id: "mcp.tunnel",
+    path: ["mcp", "tunnel"],
+    match: "command+mode",
+    hidden: true, // Removed feature — routes to a guidance error, not advertised.
+  },
+  {
+    id: "backup.create",
+    path: ["backup", "create"],
+    match: "command+mode",
+    summary: "Export a full backup bundle to data/backups/.",
+  },
+  {
+    id: "backup.import",
+    path: ["backup", "import"],
+    match: "command+mode",
+    summary: "Import a backup bundle (destructive — requires --yes).",
+  },
+  {
+    id: "backup.export-api-configs",
+    path: ["backup", "export-api-configs"],
+    match: "command+mode",
+    summary: "Export connector_config:* + openai_connection metadata to JSON.",
+  },
+  {
+    id: "backup.import-api-configs",
+    path: ["backup", "import-api-configs"],
+    match: "command+mode",
+    summary: "Import API configs from an export-api-configs JSON file.",
+  },
+  {
+    id: "setup",
+    path: ["setup"],
+    match: "command-no-mode", // ONLY when no `mode` token follows (env-driven dev|prod).
+    hidden: true, // No standalone help row.
+  },
+  {
+    id: "setup.dev|prod",
+    path: ["setup", "dev|prod"],
+    match: "command+mode",
+    summary: "Prepare Better Auth, schema, Nango, MCP server, and OAuth clients.",
+  },
+  {
+    id: "setup.nango",
+    path: ["setup", "nango"],
+    match: "command+mode",
+    summary: "Configure Nango administration only.",
+  },
+  {
+    id: "setup.branch",
+    path: ["setup", "branch"],
+    match: "command+mode",
+    summary: "Provision an isolated dev environment for the current git worktree.",
+  },
+  {
+    id: "teardown.branch",
+    path: ["teardown", "branch"],
+    match: "command+mode",
+    summary: "Remove the isolated Postgres schema for the current git worktree.",
+  },
+  {
+    id: "setup.clone",
+    path: ["setup", "clone"],
+    match: "command+mode",
+    summary: "Create + provision a dormant deep-fork clone.",
+  },
+  {
+    id: "clone.refresh-seed",
+    path: ["clone", "refresh-seed"],
+    match: "command+mode",
+    summary: "(Re)build the cinatra_seed template database.",
+  },
+  {
+    id: "clone.prune",
+    path: ["clone", "prune"],
+    match: "command+mode",
+    summary: "Destroy a clone (drops its DB, cleans Redis, releases the slot).",
+  },
+  {
+    id: "clone.list",
+    path: ["clone", "list"],
+    match: "command+mode",
+    summary: "List registered clones (slug, ports, database, state, worktree).",
+  },
+  {
+    id: "clone.start",
+    path: ["clone", "start"],
+    match: "command+mode",
+    summary: "Start a registered clone.",
+  },
+  {
+    id: "clone.stop",
+    path: ["clone", "stop"],
+    match: "command+mode",
+    summary: "Stop a registered clone.",
+  },
+  {
+    id: "clone.status",
+    path: ["clone", "status"],
+    match: "command+mode",
+    summary: "Show a clone's predicted-vs-registered runtime status.",
+  },
+  {
+    id: "clone.slug-for-worktree",
+    path: ["clone", "slug-for-worktree"],
+    match: "command+mode",
+    summary: "Registry lookup for shell hooks (resolve a worktree to its slug).",
+  },
+  {
+    id: "db.migrate",
+    path: ["db", "migrate"],
+    match: "command+mode",
+    summary: "Apply the additive bootstrap + versioned core migration chain.",
+  },
+  {
+    id: "dev.refresh",
+    path: ["dev", "refresh"],
+    match: "command+mode",
+    summary: "Reconcile your local dev environment (deps + dev DB schema).",
+  },
+  {
+    id: "dev.tunnel",
+    path: ["dev", "tunnel"],
+    match: "command+mode",
+    summary: "Manage the dev-main Tailscale Funnel (start|stop|status).",
+  },
+  {
+    id: "reset.dev",
+    path: ["reset", "dev"],
+    match: "command+mode",
+    summary: "Reset the development environment (requires --yes; dev only).",
+  },
+  {
+    id: "mcp.llm-access.setup",
+    path: ["mcp", "llm-access", "setup"],
+    match: "command+mode+sub",
+    summary: "Provision OAuth clients for OpenAI, Anthropic, and Gemini (dev only).",
+  },
+  {
+    id: "mcp.llm-access.refresh",
+    path: ["mcp", "llm-access", "refresh"],
+    match: "command+mode+sub",
+    summary: "Rotate all LLM provider client secrets.",
+  },
+  {
+    id: "doctor",
+    path: ["doctor"],
+    match: "command",
+    summary: "READ-ONLY content-editor write-path self-check (the \"done\" gate).",
+  },
+  {
+    id: "mcp.llm-access.verify",
+    path: ["mcp", "llm-access", "verify"],
+    match: "command+mode+sub",
+    summary: "Alias for `cinatra doctor`.",
+  },
+  {
+    id: "agents.install",
+    path: ["agents", "install"],
+    match: "command+mode",
+    summary: "Resolve and install an agent package tree from Verdaccio.",
+  },
+  {
+    id: "agent.export",
+    path: ["agent", "export"],
+    match: "command+mode",
+    summary: "Export an agent template to a portable ZIP archive.",
+  },
+  {
+    id: "agent.import",
+    path: ["agent", "import"],
+    match: "command+mode",
+    summary: "Import an agent template from a ZIP archive created by `agent export`.",
+  },
+];
+
+/**
+ * Find the first descriptor that matches `argv`, mirroring the original
+ * if-chain's first-match-wins semantics. Returns the descriptor, or `null` when
+ * nothing matches (the caller then applies its `agents`-no-mode fallback and the
+ * unknown-command throw).
+ *
+ * `path` tokens may use the `a|b` alternation shape (e.g. `setup dev|prod`); a
+ * token matches the argv slot when the slot equals the token outright OR is one
+ * of the pipe-separated alternatives.
+ *
+ * @param {CommandDescriptor[]} descriptors
+ * @param {string[]} argv
+ * @returns {CommandDescriptor|null}
+ */
+export function matchDescriptor(descriptors, argv) {
+  const [command, mode, sub] = argv;
+  for (const d of descriptors) {
+    if (descriptorMatches(d, command, mode, sub)) {
+      return d;
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {CommandDescriptor} d
+ * @param {string|undefined} command
+ * @param {string|undefined} mode
+ * @param {string|undefined} sub
+ * @returns {boolean}
+ */
+function descriptorMatches(d, command, mode, sub) {
+  switch (d.match) {
+    case "command":
+      return tokenMatches(d.path[0], command);
+    case "command-no-mode":
+      // Matches the bare command ONLY when no `mode` token follows it, mirroring
+      // the original `command === "setup" && !mode` guard. `!mode` was truthy for
+      // both `undefined` and an empty-string token, so mirror that exactly.
+      return tokenMatches(d.path[0], command) && !mode;
+    case "command+mode":
+      return tokenMatches(d.path[0], command) && tokenMatches(d.path[1], mode);
+    case "command+mode+sub":
+      return (
+        tokenMatches(d.path[0], command) &&
+        tokenMatches(d.path[1], mode) &&
+        tokenMatches(d.path[2], sub)
+      );
+    default:
+      return false;
+  }
+}
+
+/**
+ * A single path token matches an argv slot. For a plain token, the slot must
+ * equal it. For an `a|b` alternation token, the slot must be one of the
+ * EXPANDED alternatives — never the literal `"a|b"` string. This mirrors the
+ * original `mode === "dev" || mode === "prod"` guard exactly: `cinatra setup dev`
+ * and `cinatra setup prod` route, but a literal `cinatra setup "dev|prod"` does
+ * NOT (it falls through to the unknown-command path, as before).
+ *
+ * @param {string} token
+ * @param {string|undefined} slot
+ * @returns {boolean}
+ */
+function tokenMatches(token, slot) {
+  if (slot === undefined) return false;
+  if (token.includes("|")) {
+    // Alternation: match ONLY the expanded alternatives, not the literal token.
+    return token.split("|").includes(slot);
+  }
+  if (token === slot) return true;
+  return false;
+}
+
+/**
+ * A deterministic, human-readable index of the (visible) command surface,
+ * derived purely from the descriptors. The drift test snapshots this and
+ * asserts every visible command also appears in `printHelp`'s usage block (and
+ * vice-versa), so the dispatcher and the banner can never silently diverge.
+ *
+ * Hidden (dispatch-only) descriptors are excluded — they have no help row.
+ *
+ * @param {CommandDescriptor[]} descriptors
+ * @returns {{ id: string, command: string, summary: string }[]}
+ */
+export function buildHelpIndex(descriptors) {
+  return descriptors
+    .filter((d) => !d.hidden)
+    .map((d) => ({
+      id: d.id,
+      command: d.path.join(" "),
+      summary: d.summary ?? "",
+    }));
+}
+
+/**
+ * True when `argv` carries a help request (`--help` or `-h`) as a recognized
+ * affordance. The dispatcher uses this to SHORT-CIRCUIT to a usage print BEFORE
+ * any handler (and therefore any side effect) runs — this is the guard that
+ * stops `cinatra install --help` from kicking off a real from-zero install
+ * (cinatra#255 footgun: `--help` was an unknown flag the per-command parsers
+ * silently ignored, so the destructive handler executed).
+ *
+ * Scanning stops at the conventional `--` end-of-flags separator, so a literal
+ * `-h` / `--help` that a future command might accept as a positional VALUE
+ * (after `--`) is not mistaken for a help request. A `--help`/`-h` BEFORE `--`
+ * is always treated as help (the conventional meaning, and no current command
+ * takes either token as a value).
+ *
+ * @param {string[]} argv
+ * @returns {boolean}
+ */
+export function hasHelpFlag(argv) {
+  for (const token of argv) {
+    if (token === "--") break; // end-of-flags: anything after is positional.
+    if (token === "--help" || token === "-h") return true;
+  }
+  return false;
+}

package/src/dev-apps.mjs

@@ -0,0 +1,79 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+import { defaultRepoSyncDeps, envOverrideVarFor, syncOneRepo } from "./dev-repo-sync.mjs";
+
+// ---------------------------------------------------------------------------
+// Dev-app clone sync.
+//
+// The WordPress plugin (cinatra-ai/wordpress-plugin) and Drupal module
+// (cinatra-ai/drupal-module) are EXTERNAL apps' integration code — they live in
+// their own git repos and ship to WordPress.org / Drupal.org, NOT cinatra's
+// marketplace. For the dev docker stack, `cinatra setup {dev,branch,clone}`
+// clones / fast-forwards them into fixed paths under `dev/` (declared in
+// package.json `cinatra.devApps`). The source of truth is the companion repos,
+// NOT this tree (the clone paths are gitignored).
+//
+// Flags: --skip-dev-apps (skip entirely),
+//        --force-dev-apps (override a DIRTY tree only).
+// Per-repo URL overrides via env: CINATRA_<NAME>_REPO_URL (HTTPS or SSH).
+//
+// The five-state tree-safety model + git utilities live in `dev-repo-sync.mjs`.
+// ---------------------------------------------------------------------------
+
+export function readDevAppsConfig(repoRoot, readFile = readFileSync) {
+  try {
+    const pkg = JSON.parse(readFile(path.join(repoRoot, "package.json"), "utf8"));
+    const config = pkg?.cinatra?.devApps;
+    return config && typeof config === "object" ? config : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Sync all configured dev apps into `targetRoot`.
+ * - repoRoot: where package.json (the config) lives.
+ * - targetRoot: where the clones are materialized (repo root for `setup dev`,
+ *   the worktree path for `setup branch` / `setup clone`).
+ */
+export async function syncDevApps({
+  repoRoot,
+  targetRoot,
+  argv = [],
+  env = process.env,
+  log = console.log,
+  deps,
+} = {}) {
+  if (argv.includes("--skip-dev-apps")) {
+    log("- Dev apps: skipped (--skip-dev-apps).");
+    return { skipped: true, reason: "flag" };
+  }
+  const config = readDevAppsConfig(repoRoot, deps?.readFile);
+  if (!config || Object.keys(config).length === 0) {
+    return { skipped: true, reason: "no-config" };
+  }
+  const force = argv.includes("--force-dev-apps");
+  const realDeps = deps ?? defaultRepoSyncDeps();
+  const results = [];
+  log("- Dev apps:");
+  for (const [pkgName, spec] of Object.entries(config)) {
+    const url = env[envOverrideVarFor(pkgName)] || spec.url;
+    const branch = spec.branch || "main";
+    const dest = path.resolve(targetRoot, spec.path);
+    results.push(
+      syncOneRepo({
+        pkgName,
+        url,
+        branch,
+        dest,
+        force,
+        deps: realDeps,
+        log,
+        forceFlagHint: "--force-dev-apps",
+        stashLabel: "cinatra --force-dev-apps",
+      }),
+    );
+  }
+  return { results };
+}

package/src/dev-cli-modules.mjs

@@ -0,0 +1,91 @@
+// Dev-CLI module discovery (cinatra#151 Stage 5c).
+//
+// Extensions contribute modules to the dev CLI by DECLARING them in their
+// manifest: `cinatra.devCliModules: { "<key>": "./relative/module.mjs" }`.
+// The CLI discovers a key by scanning `extensions/<scope>/<name>/package.json`
+// — it never names a concrete extension package or path. The tailscale
+// provisioning handlers consume the "tailscale-api" / "tailscale-hostname"
+// keys declared by the tailscale connector's manifest.
+//
+// Absence posture (UNCHANGED from the retired literal lazy imports): the
+// extensions tree is a gitignored clone-back target, ABSENT on a fresh
+// checkout until `cinatra setup dev` populates it. When no present extension
+// declares the requested key, the loader throws an Error with
+// `.code = "ERR_MODULE_NOT_FOUND"` — the exact failure class the inline
+// `import()` of a missing path produced — so every caller's existing
+// graceful-degradation guard keeps working.
+
+import { readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL, fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// packages/cli/src -> repo root
+const REPO_ROOT = path.resolve(__dirname, "..", "..", "..");
+
+/**
+ * Find the module file declared under `cinatra.devCliModules[key]` by any
+ * extension present on disk. Returns an absolute path or null.
+ *
+ * Deterministic: scopes and package dirs are scanned in sorted order; the
+ * first declarer wins (in practice each key has exactly one declarer — a
+ * duplicate would indicate two extensions claiming the same CLI surface, and
+ * the first sorted one is used).
+ */
+export function discoverDevCliModulePath(key, repoRoot = REPO_ROOT) {
+  const extRoot = path.join(repoRoot, "extensions");
+  let scopes;
+  try {
+    scopes = readdirSync(extRoot).sort();
+  } catch {
+    return null;
+  }
+  for (const scope of scopes) {
+    let dirs;
+    try {
+      dirs = readdirSync(path.join(extRoot, scope)).sort();
+    } catch {
+      continue;
+    }
+    for (const dir of dirs) {
+      let pkg;
+      try {
+        pkg = JSON.parse(
+          readFileSync(path.join(extRoot, scope, dir, "package.json"), "utf8"),
+        );
+      } catch {
+        continue; // not a package dir
+      }
+      const declared = pkg?.cinatra?.devCliModules;
+      if (!declared || typeof declared !== "object") continue;
+      const rel = declared[key];
+      if (typeof rel !== "string" || rel.length === 0) continue;
+      // Confine the declared path inside the declaring extension dir
+      // (a manifest is repo-external data; never let it traverse out).
+      const base = path.join(extRoot, scope, dir);
+      const resolved = path.resolve(base, rel);
+      if (resolved !== base && !resolved.startsWith(base + path.sep)) continue;
+      return resolved;
+    }
+  }
+  return null;
+}
+
+/**
+ * Dynamic-import the module declared under `cinatra.devCliModules[key]`.
+ * Throws ERR_MODULE_NOT_FOUND (as `.code`) when no present extension
+ * declares the key — same failure class as the retired literal import of a
+ * missing extension path, preserving every caller's degradation guard.
+ */
+export async function loadDevCliModule(key, repoRoot = REPO_ROOT) {
+  const modulePath = discoverDevCliModulePath(key, repoRoot);
+  if (!modulePath) {
+    const err = new Error(
+      `Cannot find module for dev-CLI key "${key}" — no extension present under extensions/ ` +
+        `declares cinatra.devCliModules["${key}"] (the extensions tree is populated by \`cinatra setup dev\`).`,
+    );
+    err.code = "ERR_MODULE_NOT_FOUND";
+    throw err;
+  }
+  return import(pathToFileURL(modulePath).href);
+}

package/src/dev-refresh.mjs

@@ -0,0 +1,117 @@
+// Pure, side-effect-free decision helpers for `cinatra dev refresh`.
+//
+// `cinatra dev refresh` reconciles a contributor's local dev environment
+// (dependencies + dev database schema) to the code they have checked out. It is
+// the idempotent, non-destructive subset of `scripts/setup.sh` minus .env.local
+// creation: the human owns git (pull / checkout), the command never touches it.
+//
+// The flow orchestration (docker / pnpm install / runSetup) lives in index.mjs
+// because it depends on that file's internal helpers. The decision logic that is
+// worth testing in isolation lives here so it can be unit-tested without a live
+// docker stack or database.
+
+const DEFAULT_SCHEMA = "cinatra";
+const DEFAULT_QUEUE = "cinatra-background-jobs";
+const DOCKER_FLAG_PREFIX = "--docker=";
+
+/**
+ * Parse `dev refresh` flags into a normalized docker mode.
+ * - `--no-docker`            → "off" (takes precedence over --docker=)
+ * - `--docker=always`        → "always"
+ * - `--docker=auto` / absent → "auto"
+ * Any other `--docker=<value>` throws.
+ */
+export function parseDevRefreshFlags(argv = []) {
+  // Reject anything that is not a recognized flag so typos (`--dockr=always`) or a
+  // dropped flag (`--rebuild-shell`) fail loudly instead of silently no-opping to
+  // the default — a silent `--dockr=always` would run `auto` and surprise the user.
+  for (const arg of argv) {
+    if (arg === "--no-docker" || arg.startsWith(DOCKER_FLAG_PREFIX)) {
+      continue;
+    }
+    throw new Error(
+      `Unknown flag "${arg}" for cinatra dev refresh. Supported flags: --docker=auto|always, --no-docker.`,
+    );
+  }
+
+  const dockerArg = argv.find((arg) => arg.startsWith(DOCKER_FLAG_PREFIX));
+  if (dockerArg) {
+    const value = dockerArg.slice(DOCKER_FLAG_PREFIX.length);
+    if (value !== "auto" && value !== "always") {
+      throw new Error(
+        `Invalid ${DOCKER_FLAG_PREFIX}${value}. Expected --docker=auto, --docker=always, or --no-docker.`,
+      );
+    }
+  }
+  // A malformed --docker= value is always rejected above, so typos fail loudly even
+  // when combined with --no-docker. Otherwise --no-docker is the most conservative
+  // choice and wins over a valid --docker=.
+  if (argv.includes("--no-docker")) {
+    return { dockerMode: "off" };
+  }
+  if (dockerArg) {
+    return { dockerMode: dockerArg.slice(DOCKER_FLAG_PREFIX.length) };
+  }
+  return { dockerMode: "auto" };
+}
+
+function hostnameOf(url) {
+  if (!url) return null;
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * True when SUPABASE_DB_URL points at the bundled local stack (or is unset —
+ * a fresh dev checkout defaults to the local docker Postgres). External
+ * (non-localhost) database URLs return false so `auto` mode leaves infra alone.
+ */
+export function looksLikeBundledStack(env = {}) {
+  const host = hostnameOf(env.SUPABASE_DB_URL);
+  if (!host) return true;
+  // Node's URL parser returns IPv6 hosts wrapped in brackets, e.g. "[::1]".
+  return host === "127.0.0.1" || host === "localhost" || host === "::1" || host === "[::1]";
+}
+
+/**
+ * True when this checkout is an isolated worktree/clone that borrows the shared
+ * main docker stack rather than owning it. Bringing the bundled compose stack up
+ * from such a checkout would port-conflict with the main dev server, so `auto`
+ * mode must skip docker here. Detected via the markers `cinatra setup branch` /
+ * `setup clone` write into the worktree `.env.local`.
+ */
+export function isIsolatedWorktree(env = {}) {
+  const schema = (env.SUPABASE_SCHEMA || "").trim();
+  if (schema && schema !== DEFAULT_SCHEMA) return true;
+  if ((env.CINATRA_CLONE_SLUG || "").trim()) return true;
+  const queue = (env.BULLMQ_QUEUE_NAME || "").trim();
+  if (queue && queue !== DEFAULT_QUEUE) return true;
+  return false;
+}
+
+/**
+ * Decide whether `dev refresh` should run `docker compose up -d`, and why.
+ * Returns `{ run, reason }` so the orchestrator can print an explanation either way.
+ * - off    → never
+ * - always → always (forced; the orchestrator treats failure as fatal)
+ * - auto   → only when this checkout owns the bundled local stack
+ */
+export function describeDockerDecision({ dockerMode, env = {} }) {
+  if (dockerMode === "off") return { run: false, reason: "--no-docker" };
+  if (dockerMode === "always") return { run: true, reason: "--docker=always" };
+  if (isIsolatedWorktree(env)) {
+    return { run: false, reason: "isolated worktree/clone (it borrows the shared main stack)" };
+  }
+  if (!looksLikeBundledStack(env)) {
+    return { run: false, reason: "external infrastructure (SUPABASE_DB_URL is not localhost)" };
+  }
+  return { run: true, reason: "bundled local stack" };
+}
+
+/** Convenience boolean form of {@link describeDockerDecision}. */
+export function shouldRunDocker({ dockerMode, env = {} }) {
+  return describeDockerDecision({ dockerMode, env }).run;
+}