cinatra 0.1.0

package/src/tailscale-provision.mjs

@@ -0,0 +1,219 @@
+// ---------------------------------------------------------------------------
+// Pure provision-decision helpers.
+//
+// Plain ESM `.mjs` — NO TypeScript, NO `@/` aliases, NO `server-only`,
+// NO `node:child_process`, NO DB, NO network. Same leaf-purity contract
+// as `clone-runtime.mjs` so BOTH the plain-Node CLI (`runCloneStart`)
+// and the `cinatra dev tunnel` verb import the exact same proven decision
+// boundary, hermetically unit-testable without Docker / Tailscale.
+//
+// This module owns two safety-critical, reviewable concerns:
+//
+//   MagicDNS hostname-collision guard
+//     After a node registers, the registered `Self.DNSName` hostname
+//     segment MUST equal `deriveDevTailscaleHostname(...)`. A Tailscale
+//     `-1` collision suffix yields a dead predicted URL → callers must
+//     fail loud and NOT write `publicBaseUrl`. The guard returns a typed
+//     result (never throws an untyped error).
+//
+//   Write-vs-skip purity
+//     The decision to write `publicBaseUrl` depends ONLY on
+//     `(funnelUrl present)` AND `(hostname matches prediction)` — NEVER
+//     on a reachability/cert-warmup probe. `shouldWritePublicBaseUrl`
+//     takes a SINGLE object argument; that arity is the structural lock
+//     (regression-guarded in the test) that a probe arg can never be
+//     silently threaded in.
+//
+// `deriveDevTailscaleHostname` is the SINGLE source of truth for the
+// predicted hostname — imported via the exact relative specifier
+// `index.mjs` already resolves; this module NEVER re-derives it.
+//
+// Public surface:
+//   - TailscaleProvisionError (typed, `.code`)
+//   - extractTailscaleHostnameSegment(dnsNameOrUrl) → string ("" on bad input)
+//   - verifyRegisteredHostnameMatchesPrediction({ registered, dbUrl, schema })
+//   - shouldWritePublicBaseUrl({ funnelUrl, hostnameCheck })
+// ---------------------------------------------------------------------------
+
+// `deriveDevTailscaleHostname` (the single source of truth for the predicted
+// hostname) lives in the gitignored `extensions/cinatra-ai/` clone-back target,
+// ABSENT on a fresh checkout. It is loaded lazily inside
+// `verifyRegisteredHostnameMatchesPrediction` so this module — and any host
+// (CLI) module that statically imports it — resolves on an extension-empty
+// checkout. By the time a provisioning caller invokes verify, `cinatra setup
+// dev` has populated the extension.
+
+/**
+ * Errors returned (not thrown) by this module are tagged with `.code`
+ * so callers can fail loud and map to UI without parsing strings.
+ *
+ * Mirrors the shape of `TailscaleApiError` in
+ * `packages/connector-tailscale/src/tailscale-api.mjs` but is a SIBLING
+ * type — we deliberately do NOT import from `index.mjs` (cycle) nor from
+ * the connector (keep this leaf dependency-free apart from the pure
+ * hostname-derivation single source of truth).
+ *
+ * Codes:
+ *   - "tailscale.hostname_collision"  registered segment !== prediction
+ *   - "tailscale.hostname_unresolved" registered DNSName couldn't be parsed
+ */
+export class TailscaleProvisionError extends Error {
+  /**
+   * @param {string} code
+   * @param {string} message
+   */
+  constructor(code, message) {
+    super(message);
+    this.name = "TailscaleProvisionError";
+    this.code = code;
+  }
+}
+
+/**
+ * Extract the Tailscale hostname label from a registered `Self.DNSName`
+ * or a full Funnel URL.
+ *
+ * Normalisation:
+ *   1. Coerce to string; strip a leading `https://` (or `http://`) scheme.
+ *   2. Strip a single trailing `/`.
+ *   3. Strip a single trailing `.` (MagicDNS FQDN trailing dot).
+ *   4. The input MUST end in `.ts.net`. No `.ts.net` suffix → "".
+ *   5. The shape is `<hostname>.<tailnet>.ts.net` where `<tailnet>` may
+ *      itself contain dots (e.g. `acme.github` →
+ *      `myhost.foo.ts.net`). There MUST be at least one hostname
+ *      label AND a non-empty tailnet portion before `.ts.net`. The
+ *      hostname is ONLY the first label (everything up to the first `.`).
+ *      The tailnet remainder is NOT returned and NOT compared by callers.
+ *   6. Any malformed / garbage / no-suffix / zero-label input → "" (NEVER
+ *      throws). The caller's verify step converts "" into a typed
+ *      `tailscale.hostname_unresolved` error → fail-loud, no write.
+ *
+ * @param {string | null | undefined} dnsNameOrUrl
+ * @returns {string} hostname label, or "" when it cannot be resolved
+ */
+export function extractTailscaleHostnameSegment(dnsNameOrUrl) {
+  let s = String(dnsNameOrUrl ?? "").trim();
+  if (!s) return "";
+
+  // 1. Strip scheme (https:// preferred; tolerate http://).
+  s = s.replace(/^https?:\/\//i, "");
+  // 2 + 3. Strip a single trailing slash, then a single trailing dot
+  //        (order tolerates both `…ts.net/` and `…ts.net./`).
+  s = s.replace(/\/+$/, "");
+  s = s.replace(/\.+$/, "");
+  if (!s) return "";
+
+  // 4. Require the `.ts.net` tailnet TLD.
+  const SUFFIX = ".ts.net";
+  if (!s.toLowerCase().endsWith(SUFFIX)) return "";
+
+  // 5. Everything before `.ts.net` is `<hostname>.<tailnet…>`. Require a
+  //    non-empty hostname label AND a non-empty tailnet portion (so a
+  //    bare `foo.ts.net` with zero tailnet labels is rejected).
+  const beforeSuffix = s.slice(0, s.length - SUFFIX.length);
+  if (!beforeSuffix) return "";
+
+  const firstDot = beforeSuffix.indexOf(".");
+  if (firstDot <= 0) return ""; // no hostname label, or no tailnet label
+  const hostname = beforeSuffix.slice(0, firstDot);
+  const tailnet = beforeSuffix.slice(firstDot + 1);
+  if (!hostname || !tailnet) return "";
+
+  return hostname;
+}
+
+/**
+ * Collision guard. Compare the registered Tailscale hostname segment
+ * against the deterministic prediction from the SINGLE source of truth
+ * (`deriveDevTailscaleHostname`). Returns a typed result — NEVER throws.
+ *
+ *   - segment === prediction          → { ok: true, predicted, registered }
+ *   - segment !== prediction          → { ok: false, predicted, registered,
+ *                                          error: TailscaleProvisionError(
+ *                                            "tailscale.hostname_collision") }
+ *   - segment unresolved ("" parsed)  → { ok: false, predicted, registered:"",
+ *                                          error: TailscaleProvisionError(
+ *                                            "tailscale.hostname_unresolved") }
+ *
+ * `error` is ALWAYS a `TailscaleProvisionError` (has `.code`), never a
+ * bare `Error`.
+ *
+ * @param {object} args
+ * @param {string | null | undefined} args.registered  registered Self.DNSName
+ *   (trailing-dot / `.ts.net` / full `https://` URL forms all accepted)
+ * @param {string | null | undefined} args.dbUrl   SUPABASE_DB_URL
+ * @param {string | null | undefined} args.schema  SUPABASE_SCHEMA
+ * @returns {Promise<{ ok: boolean, predicted: string, registered: string,
+ *             error?: TailscaleProvisionError }>}
+ */
+export async function verifyRegisteredHostnameMatchesPrediction({
+  registered,
+  dbUrl,
+  schema,
+}) {
+  // Single source of truth — NEVER re-derive here. Discovered + loaded lazily
+  // through the connector's `cinatra.devCliModules` manifest declaration
+  // (cinatra#151 Stage 5c) so this module imports cleanly when the gitignored
+  // connector source is absent and names no extension.
+  const { loadDevCliModule } = await import("./dev-cli-modules.mjs");
+  const { deriveDevTailscaleHostname } = await loadDevCliModule("tailscale-hostname");
+  const predicted = deriveDevTailscaleHostname({ dbUrl, schema });
+  const segment = extractTailscaleHostnameSegment(registered);
+
+  if (!segment) {
+    return {
+      ok: false,
+      predicted,
+      registered: "",
+      error: new TailscaleProvisionError(
+        "tailscale.hostname_unresolved",
+        `Could not resolve a Tailscale hostname from the registered ` +
+          `node identity (expected "<hostname>.<tailnet>.ts.net"). ` +
+          `Predicted hostname was "${predicted}". Refusing to write ` +
+          `publicBaseUrl.`,
+      ),
+    };
+  }
+
+  if (segment !== predicted) {
+    return {
+      ok: false,
+      predicted,
+      registered: segment,
+      error: new TailscaleProvisionError(
+        "tailscale.hostname_collision",
+        `Tailscale registered hostname "${segment}" does not match the ` +
+          `predicted hostname "${predicted}" (likely a MagicDNS ` +
+          `collision suffix). The predicted Funnel URL would be dead — ` +
+          `refusing to write publicBaseUrl.`,
+      ),
+    };
+  }
+
+  return { ok: true, predicted, registered: segment };
+}
+
+/**
+ * Write-vs-skip decision. Decides whether to write `publicBaseUrl`
+ * purely from `(funnelUrl present)` AND `(hostnameCheck.ok === true)`.
+ *
+ * DECOUPLING INVARIANT — this function takes a SINGLE object argument
+ * and DELIBERATELY accepts NO probe / reachability / cert-warmup
+ * parameter. Its arity (`.length === 1`) is the reviewable structural
+ * lock (regression-guarded in the test) that the write decision can
+ * never be silently re-coupled to a reachability probe.
+ *
+ *   - funnelUrl truthy AND hostnameCheck.ok === true → true
+ *   - funnelUrl falsy                                → false (always)
+ *   - hostnameCheck missing / not ok                 → false (always)
+ *
+ * @param {object} args
+ * @param {string | null | undefined} args.funnelUrl  derived Funnel URL
+ * @param {{ ok?: boolean } | null | undefined} args.hostnameCheck
+ *   result of verifyRegisteredHostnameMatchesPrediction
+ * @returns {boolean}
+ */
+export function shouldWritePublicBaseUrl({ funnelUrl, hostnameCheck }) {
+  if (!funnelUrl) return false;
+  return hostnameCheck != null && hostnameCheck.ok === true;
+}

package/src/teardown-config.mjs

@@ -0,0 +1,113 @@
+// Pure helpers for `cinatra teardown branch`. Extracted from index.mjs so the
+// destructive-name resolution and guards can be tested hermetically — no DB,
+// no Redis, no git. See packages/cli/tests/teardown-config.test.mjs.
+//
+// Bug history: `runTeardownBranch` previously derived the
+// schema/queue names from the git branch alone, ignoring what the worktree's
+// `.env.local` actually declared. When a worktree was set up with a custom
+// `--slug` (or had `.env.local` SUPABASE_SCHEMA / BULLMQ_QUEUE_NAME written
+// at provisioning time that differed from the branch-derived form), the
+// teardown dropped a phantom schema and cleaned a phantom queue while the
+// real ones were orphaned. This module makes the
+// worktree's own `.env.local` the authoritative source of truth and only
+// falls back to slug-derivation when those keys are absent.
+//
+// MAIN-REPO `.env.local` is deliberately
+// NOT consulted for these target names — main's `SUPABASE_SCHEMA=cinatra`
+// would point teardown at the live app schema. Worktree-only, else derived.
+
+const SCHEMA_IDENTIFIER_SHAPE = /^[a-zA-Z_][a-zA-Z0-9_]{0,62}$/;
+const QUEUE_NAME_SHAPE = /^cinatra-bg-[a-zA-Z0-9_-]+$/;
+const PROTECTED_SCHEMAS = new Set([
+  "cinatra",
+  "public",
+  "information_schema",
+  "pg_catalog",
+]);
+const PROTECTED_QUEUES = new Set([
+  "cinatra-bg-main",
+  "cinatra-bg-cinatra",
+]);
+
+/**
+ * Resolve the destructive target names for `cinatra teardown branch`.
+ *
+ * @param {object} args
+ * @param {string} args.slug                 Sanitized branch slug (already validated upstream).
+ * @param {string|undefined} [args.envSchema] Worktree `.env.local`'s SUPABASE_SCHEMA (trimmed, or undefined).
+ * @param {string|undefined} [args.envQueue]  Worktree `.env.local`'s BULLMQ_QUEUE_NAME (trimmed, or undefined).
+ * @param {string|undefined} [args.envSource] Path to the worktree `.env.local` (only used in error/summary text).
+ * @returns {{schemaName: string, queueName: string, schemaSource: string, queueSource: string}}
+ * @throws if either resolved name fails its shape regex or hits a protected name.
+ */
+export function resolveTeardownNames({
+  slug,
+  envSchema,
+  envQueue,
+  envSource,
+}) {
+  if (typeof slug !== "string" || slug.length === 0) {
+    throw new Error("resolveTeardownNames: slug is required");
+  }
+  const derivedSchema = `cinatra_${slug.replace(/-/g, "_")}`;
+  const derivedQueue = `cinatra-bg-${slug}`;
+  // Distinguish "key absent" (undefined → fall back to derived) from "key
+  // present but blank" (empty string → throw). A blank declaration is a
+  // malformed env; silently falling back would mask an operator typo, and
+  // for a destructive command that's exactly the failure mode this whole
+  // module exists to prevent. Callers must pass the trimmed value or
+  // undefined — never a coerced empty default.
+  if (envSchema === "") {
+    throw new Error(
+      `SUPABASE_SCHEMA is declared but blank in ${envSource ?? "worktree .env.local"}. ` +
+        `Remove the key to fall back to slug-derived defaults, or set a value.`,
+    );
+  }
+  if (envQueue === "") {
+    throw new Error(
+      `BULLMQ_QUEUE_NAME is declared but blank in ${envSource ?? "worktree .env.local"}. ` +
+        `Remove the key to fall back to slug-derived defaults, or set a value.`,
+    );
+  }
+  const schemaName = envSchema ?? derivedSchema;
+  const queueName = envQueue ?? derivedQueue;
+  const schemaSource = envSchema !== undefined ? (envSource ?? "worktree .env.local") : "derived from slug";
+  const queueSource = envQueue !== undefined ? (envSource ?? "worktree .env.local") : "derived from slug";
+  validateSchemaName(schemaName, schemaSource, slug);
+  validateQueueName(queueName, queueSource);
+  return { schemaName, queueName, schemaSource, queueSource };
+}
+
+/**
+ * Throws if the schema name is malformed or names a protected app schema.
+ * Pure — does no I/O.
+ */
+export function validateSchemaName(schemaName, source, slug) {
+  if (!SCHEMA_IDENTIFIER_SHAPE.test(schemaName)) {
+    throw new Error(
+      `Refusing to drop schema "${schemaName}" (source: ${source}) — does not match Postgres identifier shape /^[a-zA-Z_][a-zA-Z0-9_]{0,62}$/.`,
+    );
+  }
+  if (PROTECTED_SCHEMAS.has(schemaName) || slug === "main") {
+    throw new Error(
+      `Refusing to drop protected schema "${schemaName}" (source: ${source}). This command is only for branch worktrees.`,
+    );
+  }
+}
+
+/**
+ * Throws if the queue name is malformed or names a protected queue.
+ * Pure — does no I/O.
+ */
+export function validateQueueName(queueName, source) {
+  if (!QUEUE_NAME_SHAPE.test(queueName)) {
+    throw new Error(
+      `Refusing to clean queue "${queueName}" (source: ${source}) — does not match cinatra-bg-<slug> shape.`,
+    );
+  }
+  if (PROTECTED_QUEUES.has(queueName)) {
+    throw new Error(
+      `Refusing to clean protected queue "${queueName}" (source: ${source}). This command is only for branch worktrees.`,
+    );
+  }
+}

package/src/worktree-collision-guard.mjs

@@ -0,0 +1,157 @@
+// Worktree-name collision guard.
+//
+// Pure logic for detecting whether a proposed worktree slug collides with an
+// existing worktree directory or local branch in the same repo. Replaces the
+// older planning-number collision guard; the new check is content-neutral —
+// it only looks at name uniqueness, never at slot/identifier semantics.
+//
+// Public surface:
+//   - sanitizeWorktreeSlug(input)
+//   - findCollisions({ slug, repoRoot, listWorktrees, listBranches })
+//   - runCollisionCheck({ slug, repoRoot, ...inject })
+//   - makeDefaultGitImpl(repoRoot)
+//   - formatResult(result)
+
+import { execFileSync } from "node:child_process";
+
+const SLUG_REGEX = /^[a-z0-9][a-z0-9-]{0,29}$/;
+
+export function sanitizeWorktreeSlug(input) {
+  if (typeof input !== "string") return null;
+  const lowered = input.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-");
+  const trimmed = lowered.replace(/^-+/, "").replace(/-+$/, "");
+  if (!trimmed) return null;
+  const capped = trimmed.slice(0, 30);
+  return SLUG_REGEX.test(capped) ? capped : null;
+}
+
+/**
+ * Find worktree/branch collisions for a proposed slug.
+ *
+ * `selfWorktreePath` / `selfBranch` (optional): the worktree path / branch
+ * the caller is operating IN. Matching the slug to the caller's own worktree
+ * or branch is NOT a collision — it's the resume case for `cinatra setup
+ * branch` re-running inside an already-provisioned worktree.
+ */
+export function findCollisions({
+  slug,
+  listWorktrees,
+  listBranches,
+  selfWorktreePath,
+  selfBranch,
+}) {
+  if (!slug) {
+    return { verdict: "INVALID", reason: "slug is empty or unsanitized" };
+  }
+  const worktrees = listWorktrees();
+  const branches = listBranches();
+
+  const wtCollision = worktrees.find(
+    (w) => w.path && w.path.split("/").pop() === slug
+  );
+  if (wtCollision) {
+    // Self-match — caller is operating inside this worktree. Not a collision.
+    if (selfWorktreePath && wtCollision.path === selfWorktreePath) {
+      return { verdict: "FREE", slug, kind: "self-worktree" };
+    }
+    return {
+      verdict: "COLLISION",
+      kind: "worktree",
+      slug,
+      path: wtCollision.path,
+      branch: wtCollision.branch,
+    };
+  }
+
+  const branchCollision = branches.find(
+    (b) => b === slug || b === `worktree-${slug}` || b === `cinatra-ai-${slug}`
+  );
+  if (branchCollision) {
+    // Self-match — caller is operating on this branch.
+    if (selfBranch && (branchCollision === selfBranch || branchCollision === `worktree-${selfBranch}`)) {
+      return { verdict: "FREE", slug, kind: "self-branch" };
+    }
+    return { verdict: "COLLISION", kind: "branch", slug, branch: branchCollision };
+  }
+
+  return { verdict: "FREE", slug };
+}
+
+export function makeDefaultGitImpl(repoRoot) {
+  return {
+    listWorktrees() {
+      try {
+        const out = execFileSync("git", ["-C", repoRoot, "worktree", "list", "--porcelain"], {
+          encoding: "utf8",
+        });
+        const entries = [];
+        let cur = {};
+        for (const line of out.split("\n")) {
+          if (line.startsWith("worktree ")) {
+            if (cur.path) entries.push(cur);
+            cur = { path: line.slice("worktree ".length).trim() };
+          } else if (line.startsWith("branch ")) {
+            cur.branch = line.slice("branch ".length).trim();
+          } else if (line.startsWith("HEAD ")) {
+            cur.head = line.slice("HEAD ".length).trim();
+          }
+        }
+        if (cur.path) entries.push(cur);
+        return entries;
+      } catch {
+        return [];
+      }
+    },
+    listBranches() {
+      try {
+        const out = execFileSync(
+          "git",
+          ["-C", repoRoot, "for-each-ref", "--format=%(refname:short)", "refs/heads/"],
+          { encoding: "utf8" }
+        );
+        return out.split("\n").map((s) => s.trim()).filter(Boolean);
+      } catch {
+        return [];
+      }
+    },
+  };
+}
+
+export function runCollisionCheck({
+  slug,
+  repoRoot,
+  listWorktrees,
+  listBranches,
+  selfWorktreePath,
+  selfBranch,
+}) {
+  if (!listWorktrees || !listBranches) {
+    const impl = makeDefaultGitImpl(repoRoot ?? process.cwd());
+    listWorktrees ??= impl.listWorktrees;
+    listBranches ??= impl.listBranches;
+  }
+  const sanitized = sanitizeWorktreeSlug(slug);
+  if (!sanitized) {
+    return { verdict: "INVALID", reason: `slug ${JSON.stringify(slug)} fails ${SLUG_REGEX}` };
+  }
+  return findCollisions({
+    slug: sanitized,
+    listWorktrees,
+    listBranches,
+    selfWorktreePath,
+    selfBranch,
+  });
+}
+
+export function formatResult(result) {
+  if (!result) return "[collision-guard] (no result)";
+  if (result.verdict === "FREE") return `[collision-guard] FREE slug=${result.slug}`;
+  if (result.verdict === "INVALID") return `[collision-guard] INVALID ${result.reason}`;
+  if (result.verdict === "COLLISION") {
+    if (result.kind === "worktree") {
+      return `[collision-guard] COLLISION kind=worktree slug=${result.slug} path=${result.path}`;
+    }
+    return `[collision-guard] COLLISION kind=branch slug=${result.slug} branch=${result.branch}`;
+  }
+  return `[collision-guard] UNKNOWN ${JSON.stringify(result)}`;
+}