@tekyzinc/gsd-t 5.1.10 → 5.1.12

package/bin/gsd-t-env-registry.cjs

@@ -1,1046 +0,0 @@
-"use strict";
-
-// bin/gsd-t-env-registry.cjs
-//
-// M102 — Environment Registry helper. Records every environment's connection
-// MAP (never a secret VALUE) into docs/infrastructure.md via the ONE shared
-// marker-block writer, and reads it back read-first (No-Re-Research) so a
-// missing entry HALTs-and-documents rather than being guessed (No-Fallback-Ever).
-//
-// Contract: .gsd-t/contracts/env-registry-contract.md
-//
-// Public surface:
-//   recordEnvironment({ projectDir, scope, kind, host, port, name, authMethod,
-//                       secretVault, secretEnvVarName, fetchCommand,
-//                       connectCommand, gotchas, readOnlyDefault })
-//     -> upsert row by (scope, kind) into the Environments table (idempotent).
-//   lookupEnvironment(projectDir, scope, kind) -> row object | null.
-//   detectEnvConfig(projectDir) -> { vault, fetchCommand, secretEnvVarNames, ... }
-//   addPermissionEntry(projectDir, connectCommand) -> { added, tool, entry }
-//   ensureEnvGitignored(projectDir) -> { added }
-//
-// Zero external npm runtime deps — fs/path only. Reuses the M100 detectStack
-// SHAPE and the ONE shared marker-block doc-writer (gsd-t-doc-marker.cjs).
-
-const fs = require("fs");
-const path = require("path");
-const { upsertMarkedDocBlock } = require("./gsd-t-doc-marker.cjs");
-
-// ─── Markers + schema ────────────────────────────────────────────────────────
-
-const ENV_MARKER_START = "<!-- gsd-t-env-registry:start -->";
-const ENV_MARKER_END = "<!-- gsd-t-env-registry:end -->";
-
-// Map-only columns — NO secret-value column exists (a row is structurally
-// incapable of holding a secret VALUE). `secret vault` + `secret env-var NAME`
-// + `fetch command` record WHERE the secret lives and HOW to fetch it, never
-// the value itself.
-const ENV_COLUMNS = [
-  "id",
-  "scope",
-  "kind",
-  "host",
-  "port",
-  "db/name",
-  "auth method",
-  "secret vault",
-  "secret env-var NAME",
-  "fetch command",
-  "connect command",
-  "access gotchas",
-  "read-only default",
-  "recorded",
-];
-
-// ─── Secret-value BACKSTOP detector (known-prefix / JWT / embedded-cred) ─────
-//
-// THIS IS A BACKSTOP ONLY — never the primary guard. The PRIMARY guard for
-// every free-ish column is a TIGHT POSITIVE ALLOWLIST (see the per-column
-// validators below): a value is accepted ONLY if it matches the shape its
-// column is supposed to hold (a real hostname / an enum member / a $VAR / a
-// curated subcommand word). A value like `hunter2hunter2hunter` or
-// `correcthorsebattery` is rejected because it is NOT a valid hostname / NOT
-// the enum / NOT a $VAR — with ZERO entropy or character-class threshold.
-//
-// THREE Red Team passes proved the inverse ("reject if it looks like a secret",
-// a denylist with an entropy floor) leaks: every floor eventually admits a
-// secret that sits below it. The floor is the defect; it is GONE as a primary
-// guard. This backstop remains only to cheaply catch the well-known credential
-// SHAPES (GitHub / Stripe / AWS / Slack / Google prefixes, JWTs, embedded
-// proto://user:pw@ creds) — an EXTRA layer, never the sole thing between a
-// value and the doc.
-
-// Known secret prefixes. A token STARTING with one of these is a live secret.
-// Belt-and-suspenders only — the structural validators (command allowlist +
-// enumerated gotchas + gate high-entropy scan) are the real guard for an OPEN
-// category. This list catches the well-known SHAPES cheaply.
-const KNOWN_SECRET_PREFIXES = [
-  "ghp_", "gho_", "ghs_", "ghu_", "ghr_", // GitHub PAT / OAuth / server / user / refresh
-  "github_pat_", // GitHub fine-grained PAT
-  "sk_live", "sk_test", "pk_live", "rk_live", // Stripe
-  "AKIA", "ASIA", // AWS access-key ids
-  "xoxb-", "xoxp-", "xoxa-", "xoxr-", "xoxs-", "xapp-", // Slack (incl. app-level)
-  "AIza", // Google API key
-  "glpat-", // GitLab personal access token
-  "gitlab", // GitLab-prefixed tokens (belt-and-suspenders)
-  "npm_", // npm automation token
-  "dop_v1_", // DigitalOcean PAT
-  "SG.", // SendGrid API key
-  "shpat_", "shpss_", // Shopify access / shared-secret
-];
-
-// proto://user:PASSWORD@host for ANY scheme (not a hardcoded scheme allowlist).
-// The password segment is a literal only when it is NOT a $-reference.
-const EMBEDDED_CRED = /[a-z][a-z0-9+.\-]*:\/\/[^\s:/@]+:(?!\$)[^\s:/@]+@/i;
-
-// JWT: three base64url segments joined by dots. A real JWT's header segment is
-// the base64url of a JSON object beginning `{"` → it ALWAYS starts with `eyJ`.
-// Anchoring on that avoids a false positive on a 3-part dotted hostname
-// (`ep-neon.neon.tech`), while still catching every genuine token.
-const JWT_SHAPE = /^eyJ[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{4,}$/;
-
-// A contiguous base64/hex run inside a larger string (e.g. `Bearer <token>`).
-const BASE64_RUN = /[A-Za-z0-9+/]{24,}={0,2}/;
-const HEX_RUN = /\b[0-9a-fA-F]{32,}\b/;
-
-// True when `s` contains (or is) a live secret value. Used BOTH as the reject
-// test inside the per-column allowlist checks AND as the verify gate's
-// independent detector.
-function looksLikeSecretValue(s) {
-  if (typeof s !== "string" || !s) return false;
-  // Known prefixes — anywhere a whitespace/quote-delimited token begins.
-  for (const tok of s.split(/[\s"'`=:,()<>]+/)) {
-    if (!tok) continue;
-    for (const p of KNOWN_SECRET_PREFIXES) {
-      if (tok.startsWith(p) && tok.length > p.length) return true;
-    }
-    if (JWT_SHAPE.test(tok)) return true;
-  }
-  if (EMBEDDED_CRED.test(s)) return true;
-  // High-entropy runs — but ignore a $-reference and skip pure hostnames
-  // (dotted, no long unbroken run) which the base64 run would otherwise catch.
-  if (HEX_RUN.test(s)) return true;
-  const b64 = s.match(BASE64_RUN);
-  if (b64) {
-    const run = b64[0];
-    // A hostname segment is short and dotted; a real blob is one long run.
-    if (run.length >= 24) return true;
-  }
-  return false;
-}
-
-// Back-compat alias — the OLD name is kept exported so nothing that imports it
-// breaks, but it now points at the strict entropy/prefix detector.
-function looksLikeInlineSecret(value) {
-  return looksLikeSecretValue(value);
-}
-
-// ─── POSITIVE-ALLOWLIST shape primitives (shared: writer + verify gate) ──────
-//
-// These are the PRIMARY guard for every free-ish column. NOT an entropy floor —
-// a set of TIGHT POSITIVE shapes. A value is accepted ONLY if it IS a real
-// hostname / IP / $VAR / enum member / curated subcommand word. Everything else
-// is REJECTED, so `hunter2hunter2hunter` / `8675309…` / `correcthorsebattery` /
-// `Tr0ub4dor` fail because they are none of those shapes — with ZERO entropy or
-// character-class threshold anywhere.
-
-// A dotted hostname/domain: labels of [A-Za-z0-9-] joined by dots, at least one
-// dot, TLD-ish last label. Recognizes `ep-cool.us-east-2.aws.neon.tech`,
-// `bastion.example.com`, `api.example.com`.
-const DOTTED_HOSTNAME =
-  /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)+$/;
-
-// IPv4 dotted-quad (loose — 1-3 digits per octet; not validating 0-255 range,
-// only the SHAPE, which is enough to distinguish a real IP from a digit blob).
-const IPV4 = /^\d{1,3}(?:\.\d{1,3}){3}$/;
-
-// A bare single-label host: letters + hyphen ONLY (NO digits), ≤ 16 chars,
-// lowercase-led. Accepts docker/service names `db`, `postgres`, `db-primary`,
-// and the single-char test host `h`. REJECTS `hunter2hunter2hunter` (digits),
-// `8675309…` (digits), and a long single-label passphrase like
-// `correcthorsebattery` (19 > 16) — a bare blob is never a valid host here.
-// Real docker/service hostnames are short; a genuinely long endpoint is dotted
-// DNS or an IP, both of which have their own positive shapes.
-const BARE_HOST_LABEL = /^[a-z][a-z-]{0,15}$/;
-
-// A $VAR / ${VAR} reference, optionally single/double-quoted — the ONLY
-// sanctioned way a secret ever appears in a command.
-const VAR_REF = /^["']?\$\{?[A-Za-z_][A-Za-z0-9_]*\}?["']?$/;
-
-// A pure UPPER_SNAKE env-var NAME (e.g. DATABASE_URL_PROD, SECRET) — a NAME,
-// never a value.
-const UPPER_SNAKE = /^[A-Z][A-Z0-9_]*$/;
-
-// A short lowercase-led SNAKE identifier used for db / resource names. Positive
-// shape (NOT an entropy floor): lowercase-led, [a-z0-9_], ≤ 16 chars, and NO
-// digit-immediately-followed-by-a-letter (a `2h`-style alternation reads as a
-// blob, never a real db name). Accepts `binvoice_prod` (13), `analytics`,
-// `neondb_prod`, `appdb`; REJECTS `hunter2hunter2hunter` (`2h` transition),
-// `correcthorsebattery` (19 > 16), `Xk9…` (uppercase).
-const DB_NAME_MAX = 16;
-function isDbNameShape(s) {
-  if (typeof s !== "string" || s.length === 0 || s.length > DB_NAME_MAX) return false;
-  if (!/^[a-z][a-z0-9_]*$/.test(s)) return false;
-  if (/[0-9][a-z]/.test(s)) return false; // digit→letter interior = blob-like
-  return true;
-}
-
-// A dotted hostname OR IPv4 OR `localhost` — any real network endpoint shape.
-function isHostShape(s) {
-  if (s === "localhost") return true;
-  if (IPV4.test(s)) return true;
-  if (DOTTED_HOSTNAME.test(s)) return true;
-  if (BARE_HOST_LABEL.test(s)) return true;
-  return false;
-}
-
-// ─── Per-column ALLOWLIST validators ─────────────────────────────────────────
-//
-// Each column may contain ONLY its expected shape. Anything else THROWS — the
-// row is REJECTED and never written. This is the inversion the Red Team
-// prescribed: a bare secret in ANY field fails its column's shape check.
-
-const SCOPES = new Set(["local", "staging", "prod"]);
-const VAULTS = new Set([
-  "local", "local (.env)", ".env", "env",
-  "vercel", "neon", "gcp-secret-manager", "google secret manager",
-  "aws-secrets-manager", "aws secrets manager", "doppler", "1password",
-  "hashicorp-vault", "vault", "azure-key-vault", "infisical",
-]);
-
-// `auth method` is an ENUM (positive allowlist), exactly like `secret vault`
-// and `access gotchas`. A value NOT in this set is rejected — so
-// `hunter2hunter2hunter` fails because it is not an auth-method name, with NO
-// entropy check. Extend as real auth methods appear (this is the curated set,
-// not a floor).
-const AUTH_METHODS = new Set([
-  "password", "iam", "oauth", "oauth2", "service-account", "ssh-key",
-  "api-key", "none", "scram-sha-256", "md5", "trust", "token", "key",
-  "cert", "mtls", "kerberos", "ldap",
-]);
-
-// Curated CLI / DB subcommand words a command may carry as a BARE literal arg.
-// A positive allowlist — a bare arg is accepted only if it is one of these OR
-// the row's own db-name shape OR a hostname / $VAR / flag. Anything else must
-// become a $VAR (see classifyCommandToken). Extend as real tools appear.
-const CLI_WORDS = new Set([
-  // DB / shell clients
-  "psql", "mysql", "mysqldump", "mongo", "mongosh", "redis-cli", "sqlite3",
-  "pg_dump", "pg_restore", "pg_dumpall", "cqlsh", "clickhouse-client",
-  // vault / platform CLIs
-  "neonctl", "vercel", "gcloud", "aws", "az", "doppler", "supabase",
-  "flyctl", "fly", "heroku", "railway", "wrangler", "turso", "op", "infisical",
-  "kubectl", "helm", "terraform", "vault",
-  // network clients
-  "ssh", "scp", "sftp", "curl", "wget", "ldapsearch", "nc", "openssl", "rsync",
-  // common subcommands / operands
-  "env", "pull", "push", "list", "get", "set", "secrets", "versions",
-  "access", "version", "exec", "run", "connect", "login", "logout",
-  "connection-string", "db-url", "database-url", "redis-url",
-  "admin", "default", "latest", "read", "write", "describe", "show",
-  // descriptive-fetch operands (the detectEnvConfig fallback: "read $VAR from .env")
-  "from", "cat", "source", "printenv", "dotenv",
-]);
-
-// A dotfile operand a command may reference (e.g. `.env`, `.env.local`,
-// `.gcloudignore`). REQUIRES a leading dot — that is what makes it a dotfile
-// and NOT a bare blob (`hunter2…` has no leading dot, so it never matches).
-// Short lowercase labels only; a leading-dot filename is a filesystem path,
-// never a secret VALUE.
-const DOTFILE_TOKEN = /^\.[a-z][a-z0-9]*(?:\.[a-z][a-z0-9-]*)*$/;
-
-// The doc-block markers a smuggled cell could use to corrupt upsert indexOf.
-const RESERVED_MARKER_SUBSTRINGS = [
-  ENV_MARKER_START, ENV_MARKER_END,
-  "gsd-t-env-registry:start", "gsd-t-env-registry:end",
-  "gsd-t-logging-scaffold:start", "gsd-t-logging-scaffold:end",
-];
-
-function rejectMarkerSmuggle(field, value) {
-  if (typeof value !== "string" || !value) return;
-  for (const m of RESERVED_MARKER_SUBSTRINGS) {
-    if (value.includes(m)) {
-      throw new Error(
-        `recordEnvironment: field "${field}" contains a reserved doc-marker substring ` +
-          `("${m}") — refusing to write a value that could corrupt the marked doc block.`
-      );
-    }
-  }
-}
-
-function rejectSecret(field, value) {
-  if (looksLikeSecretValue(value)) {
-    throw new Error(
-      `recordEnvironment: refusing to write an inline literal secret in field "${field}". ` +
-        `Record the secret env-var NAME and reference it as $VAR (e.g. psql "$DATABASE_URL_PROD"), ` +
-        `never a literal password/token/connection-string.`
-    );
-  }
-}
-
-// Optional-string helper: undefined/null/"" pass through as empty (—).
-function optStr(v) {
-  return v === undefined || v === null ? "" : String(v);
-}
-
-function validateScope(v) {
-  if (!SCOPES.has(v)) {
-    throw new Error(`recordEnvironment: scope must be one of local|staging|prod, got "${v}"`);
-  }
-}
-
-function validateKind(v) {
-  if (!/^[a-z0-9][a-z0-9-]*$/.test(v)) {
-    throw new Error(`recordEnvironment: kind must match [a-z0-9-]+ (e.g. postgres, http-api), got "${v}"`);
-  }
-}
-
-function validateHost(field, v) {
-  const s = optStr(v);
-  if (s === "") return;
-  // POSITIVE shape: `localhost` | IPv4 | dotted-DNS | a bare service label
-  // (letters+hyphen, ≤24, no digits). Strip an optional trailing `:port`.
-  const hostPart = s.replace(/:\d+$/, "");
-  if (!isHostShape(hostPart)) {
-    throw new Error(
-      `recordEnvironment: ${field} "${s}" is not a valid host shape. ` +
-        `A host must be "localhost", an IPv4 address, a dotted DNS hostname ` +
-        `(e.g. ep-cool.us-east-2.aws.neon.tech), or a short lowercase service ` +
-        `name (letters+hyphen, no digits — e.g. db, postgres, db-primary). ` +
-        `A bare token like "${hostPart}" is rejected — if it is a secret, move ` +
-        `it to an env var and reference it as $VAR.`
-    );
-  }
-  // Backstop (extra layer, never the primary guard).
-  rejectSecret(field, s);
-}
-
-function validatePort(v) {
-  const s = optStr(v);
-  if (s === "") return;
-  if (!/^\d+$/.test(s)) {
-    throw new Error(`recordEnvironment: port must be digits only, got "${s}"`);
-  }
-}
-
-function validateName(v) {
-  const s = optStr(v);
-  if (s === "") return;
-  // POSITIVE shape: a short lowercase-led snake db-name (≤16, no digit→letter
-  // interior). Accepts `binvoice_prod`, `analytics`, `neondb_prod`, `appdb`;
-  // REJECTS `hunter2hunter2hunter` (`2h` transition), `correcthorsebattery`
-  // (too long), `Xk9…` (uppercase) — NO entropy check.
-  if (!isDbNameShape(s)) {
-    throw new Error(
-      `recordEnvironment: db/name "${s}" is not a valid db-name shape. ` +
-        `A db name must be a short lowercase identifier (≤${DB_NAME_MAX} chars, ` +
-        `lowercase-led [a-z][a-z0-9_]*, no digit-then-letter run — e.g. ` +
-        `binvoice_prod, analytics). A blob like "${s}" is rejected; if it is a ` +
-        `secret, move it to an env var and reference it as $VAR.`
-    );
-  }
-  // Backstop (extra layer).
-  rejectSecret("db/name", s);
-}
-
-function validateAuthMethod(v) {
-  const s = optStr(v);
-  if (s === "") return;
-  // POSITIVE ENUM (like `secret vault` / `access gotchas`). A value NOT in the
-  // curated set is rejected — `hunter2hunter2hunter` fails because it is not an
-  // auth-method name, with NO entropy check.
-  if (!AUTH_METHODS.has(s.toLowerCase())) {
-    throw new Error(
-      `recordEnvironment: auth method "${s}" is not an enumerated auth method. ` +
-        `Allowed: ${[...AUTH_METHODS].join(" | ")}. A secret is never an ` +
-        `auth-method value — record the method name only.`
-    );
-  }
-  // Backstop (extra layer).
-  rejectSecret("auth method", s);
-}
-
-function validateVault(v) {
-  const s = optStr(v);
-  if (s === "") return;
-  rejectSecret("secret vault", s);
-  if (!VAULTS.has(s.toLowerCase())) {
-    throw new Error(
-      `recordEnvironment: secret vault must be an enumerated vault name ` +
-        `(local|vercel|neon|gcp-secret-manager|aws-secrets-manager|env|…), got "${s}"`
-    );
-  }
-}
-
-function validateEnvVarName(v) {
-  const s = optStr(v);
-  if (s === "") return;
-  // an env-var NAME only: UPPER_SNAKE. A real value has lowercase/entropy.
-  // Backstop first: `AKIAIOSFODNN7EXAMPLE` is valid UPPER_SNAKE but is an AWS
-  // key id — the known-prefix detector rejects it.
-  rejectSecret("secret env-var NAME", s);
-  if (!/^[A-Z][A-Z0-9_]*$/.test(s)) {
-    throw new Error(
-      `recordEnvironment: secret env-var NAME must be [A-Z][A-Z0-9_]* (a NAME, not a value), got "${s}"`
-    );
-  }
-}
-
-// ─── Command POSITIVE allowlist ──────────────────────────────────────────────
-//
-// A command token is accepted ONLY if it IS one of a small set of SAFE POSITIVE
-// shapes; ANYTHING else THROWS. This is the PRIMARY guard for the connect/fetch
-// columns. NO entropy threshold — THREE Red Team passes proved a floor always
-// admits a secret below it. The positive rule instead admits ONLY:
-//
-//   1. a $VAR / ${VAR} reference (optionally quoted) — the ONLY sanctioned way
-//      a secret ever appears in a command;
-//   2. a flag: `-x` | `--flag` (bare) | `--flag=<value>` (value re-checked
-//      by the SAME positive rule — a bare literal flag value must itself be a
-//      $VAR / hostname / curated word);
-//   3. a dotted hostname / IPv4 / `localhost` (a network endpoint);
-//   4. a bare literal arg ONLY if it is a curated CLI/DB subcommand word OR the
-//      row's own db-name shape (short lowercase snake, ≤16, no digit→letter).
-//
-// A bare literal that is NONE of these — `hunter2hunter2hunter`,
-// `correcthorsebattery`, `Xk9#mPq2vLzR8nQw`, a UUID, a platform token — is
-// REJECTED with "put this value in an env var and reference it as $VAR". We
-// ACCEPT the false positive that an unusual-but-legit bare arg must become a
-// $VAR — that is the correct trade for a secrets-adjacent file.
-
-// True if a BARE literal command arg is on the positive allowlist: a curated
-// subcommand word OR a db-name shape (row identifier). NO entropy check.
-function isSafeBareArg(bare) {
-  if (CLI_WORDS.has(bare.toLowerCase())) return true;
-  if (isDbNameShape(bare)) return true;
-  return false;
-}
-
-// Split a command into whitespace-delimited tokens, but keep a quoted segment
-// (single or double quotes) as ONE token so `"$DATABASE_URL"` stays intact.
-function tokenizeCommand(s) {
-  const tokens = [];
-  const re = /"[^"]*"|'[^']*'|\S+/g;
-  let m;
-  while ((m = re.exec(s)) !== null) tokens.push(m[0]);
-  return tokens;
-}
-
-// Classify ONE command token. Returns null if it is on the positive allowlist,
-// or a reason string if it must be rejected.
-function classifyCommandToken(tok) {
-  // Strip a single layer of surrounding quotes for shape analysis.
-  const bare = tok.replace(/^["']/, "").replace(/["']$/, "");
-  if (bare === "") return null;
-
-  // 1. a $VAR / ${VAR} reference (the ONLY sanctioned way a secret appears).
-  if (VAR_REF.test(tok) || /^\$\{?[A-Za-z_][A-Za-z0-9_]*\}?$/.test(bare)) return null;
-
-  // 2. a flag: -x | --flag | --flag=value. The value half is re-checked by the
-  //    SAME positive rule (a bare literal flag value must itself be a
-  //    $VAR / hostname / curated word — never a free literal).
-  if (/^--?[A-Za-z][A-Za-z0-9-]*$/.test(bare)) {
-    // bare flag with no value: -U, --headed, -W, -h, -d — always safe.
-    return null;
-  }
-  if (/^--?[A-Za-z][A-Za-z0-9-]*=/.test(bare)) {
-    const eq = bare.indexOf("=");
-    const value = bare.slice(eq + 1);
-    if (value === "") return null;
-    const reason = classifyCommandToken(value);
-    if (reason) {
-      return `flag value in "${bare}" is not an allowed shape — ${reason}`;
-    }
-    return null;
-  }
-
-  // 3. a network endpoint: dotted hostname / IPv4 / localhost.
-  if (isHostShape(bare)) return null;
-
-  // 3b. a dotfile operand (`.env`, `.env.local`) — a filesystem path, not a secret.
-  if (DOTFILE_TOKEN.test(bare)) return null;
-
-  // 4. a bare literal arg — ONLY a curated subcommand word or a db-name shape.
-  if (isSafeBareArg(bare)) return null;
-
-  // 5. anything else → REJECT. It is neither $VAR, flag, host, nor a recognized
-  //    safe word — a probable inline literal secret.
-  return `bare argument "${bare}" is not a $VAR reference, a flag, a hostname, ` +
-    `nor a recognized CLI/db identifier — it is a probable inline literal secret. ` +
-    `Move it to an env var and reference it as $VAR (e.g. psql "$DATABASE_URL_PROD")`;
-}
-
-function validateCommand(field, v) {
-  const s = optStr(v);
-  if (s === "") return;
-  // Backstop first (known prefixes / JWT / base64 / hex / embedded cred).
-  rejectSecret(field, s);
-  // PRIMARY structural guard: every token must be an allowed shape.
-  for (const tok of tokenizeCommand(s)) {
-    const reason = classifyCommandToken(tok);
-    if (reason) {
-      throw new Error(
-        `recordEnvironment: ${field} rejected — ${reason}. ` +
-          `A command may contain only flags, $VAR/\${VAR} references, and simple ` +
-          `identifier/subcommand/hostname tokens; a bare literal secret is forbidden. ` +
-          `Put the value in an env var and reference it as $VAR (e.g. psql "$DATABASE_URL_PROD").`
-      );
-    }
-  }
-}
-
-// ─── Gotchas ENUMERATED (no free prose) ──────────────────────────────────────
-//
-// Free prose gave a secret somewhere to hide. `gotchas` is now an enumerated /
-// short-token column: a comma/space-separated list drawn from a fixed enum,
-// plus an optional `via <hostname/identifier>` qualifier. Anything else THROWS.
-
-const GOTCHA_ENUM = new Set([
-  "vpn", "ip-allowlist", "ssh-tunnel", "bastion", "none",
-]);
-
-function validateGotchas(v) {
-  const s = optStr(v);
-  if (s === "") return;
-  rejectSecret("access gotchas", s);
-  // Tokenize on commas and whitespace.
-  const tokens = s.split(/[,\s]+/).filter(Boolean);
-  for (let i = 0; i < tokens.length; i++) {
-    const t = tokens[i].toLowerCase();
-    if (GOTCHA_ENUM.has(t)) continue;
-    if (t === "via") {
-      // the NEXT token must be a POSITIVE host shape (dotted DNS / IPv4 /
-      // localhost / short service label) — never a free literal.
-      const next = tokens[i + 1];
-      if (!next) {
-        throw new Error(`recordEnvironment: access gotchas — "via" must be followed by a hostname/identifier`);
-      }
-      if (!isHostShape(next)) {
-        throw new Error(
-          `recordEnvironment: access gotchas — "via ${next}" target must be a hostname/IP ` +
-            `(dotted DNS, IPv4, localhost, or a short lowercase service name), got "${next}"`
-        );
-      }
-      i++; // consume the hostname token
-      continue;
-    }
-    // A standalone POSITIVE host shape is allowed (naming a bastion directly).
-    if (isHostShape(tokens[i])) {
-      continue;
-    }
-    throw new Error(
-      `recordEnvironment: access gotchas must be an enumerated list ` +
-        `(vpn | ip-allowlist | ssh-tunnel | bastion | none), optionally with ` +
-        `"via <hostname>" — got "${tokens[i]}". Free prose is forbidden (nowhere for a secret to hide).`
-    );
-  }
-}
-
-// Run the full per-column allowlist + marker-smuggle + secret backstop over a
-// proposed row. Throws on the FIRST violation — the row is never written.
-function validateRow(opts) {
-  // Marker-smuggling guard FIRST, on EVERY user-supplied field — a smuggled
-  // doc-marker is rejected with its own specific error regardless of which
-  // column it lands in (the column shape checks would otherwise reject it with
-  // a less-specific "wrong shape" message).
-  for (const [field, value] of Object.entries({
-    scope: opts.scope,
-    kind: opts.kind,
-    host: opts.host,
-    port: opts.port,
-    name: opts.name,
-    authMethod: opts.authMethod,
-    secretVault: opts.secretVault,
-    secretEnvVarName: opts.secretEnvVarName,
-    fetchCommand: opts.fetchCommand,
-    connectCommand: opts.connectCommand,
-    gotchas: opts.gotchas,
-  })) {
-    rejectMarkerSmuggle(field, value);
-  }
-
-  validateScope(opts.scope);
-  validateKind(opts.kind);
-  validateHost("host", opts.host);
-  validatePort(opts.port);
-  validateName(opts.name);
-  validateAuthMethod(opts.authMethod);
-  validateVault(opts.secretVault);
-  validateEnvVarName(opts.secretEnvVarName);
-  validateCommand("fetch command", opts.fetchCommand);
-  validateCommand("connect command", opts.connectCommand);
-  validateGotchas(opts.gotchas);
-}
-
-// ─── Table serialization ─────────────────────────────────────────────────────
-
-function escapeCell(v) {
-  if (v === undefined || v === null || v === "") return "—";
-  return String(v).replace(/\|/g, "\\|").replace(/\n/g, " ").trim();
-}
-
-function rowToLine(row) {
-  return "| " + ENV_COLUMNS.map((c) => escapeCell(row[c])).join(" | ") + " |";
-}
-
-function headerLines() {
-  return [
-    "| " + ENV_COLUMNS.join(" | ") + " |",
-    "| " + ENV_COLUMNS.map(() => "---").join(" | ") + " |",
-  ];
-}
-
-// Build the full marker-delimited block from a list of row objects.
-function buildTableBlock(rows) {
-  const lines = [
-    ENV_MARKER_START,
-    "## Environments",
-    "",
-    "> **Map, not secrets.** This table records only WHERE an environment lives and",
-    "> HOW to reach it — host/port/name/auth-method/which-vault-holds-the-secret/the",
-    "> env-var NAME/the fetch + connect commands. It NEVER stores a secret VALUE.",
-    "> The value lives in the vault (`.env` / Vercel / Neon / Google Secret Manager)",
-    "> and is pulled at runtime via the env-var NAME. A missing row → HALT and",
-    "> document (detect → ask → record → proceed); never guess a connection string,",
-    "> never grep transcripts to rediscover.",
-    "",
-    ...headerLines(),
-    ...rows.map(rowToLine),
-    ENV_MARKER_END,
-  ];
-  return lines.join("\n");
-}
-
-// ─── Table parsing ───────────────────────────────────────────────────────────
-
-function infraDocPath(projectDir) {
-  return path.join(projectDir, "docs", "infrastructure.md");
-}
-
-function extractBlock(content) {
-  if (!content.includes(ENV_MARKER_START) || !content.includes(ENV_MARKER_END)) {
-    return null;
-  }
-  const start = content.indexOf(ENV_MARKER_START);
-  const end = content.indexOf(ENV_MARKER_END);
-  return content.slice(start, end);
-}
-
-function splitRow(line) {
-  // Strip the leading/trailing pipe, split on unescaped pipes.
-  const trimmed = line.trim().replace(/^\|/, "").replace(/\|$/, "");
-  const cells = [];
-  let cur = "";
-  for (let i = 0; i < trimmed.length; i++) {
-    const ch = trimmed[i];
-    if (ch === "\\" && trimmed[i + 1] === "|") {
-      cur += "|";
-      i++;
-    } else if (ch === "|") {
-      cells.push(cur.trim());
-      cur = "";
-    } else {
-      cur += ch;
-    }
-  }
-  cells.push(cur.trim());
-  return cells;
-}
-
-// Parse the Environments table into an array of row objects keyed by column.
-function parseRows(projectDir) {
-  const target = infraDocPath(projectDir);
-  if (!fs.existsSync(target)) return [];
-  const content = fs.readFileSync(target, "utf8");
-  const block = extractBlock(content);
-  if (!block) return [];
-
-  const rows = [];
-  const lines = block.split("\n");
-  for (const line of lines) {
-    if (!line.trim().startsWith("|")) continue;
-    const cells = splitRow(line);
-    // Skip the header row and the separator row.
-    if (cells[0] === "id") continue;
-    if (cells.every((c) => /^-{1,}$/.test(c) || c === "")) continue;
-    const row = {};
-    ENV_COLUMNS.forEach((col, i) => {
-      const raw = cells[i] === undefined ? "" : cells[i];
-      row[col] = raw === "—" ? "" : raw;
-    });
-    rows.push(row);
-  }
-  return rows;
-}
-
-// ─── recordEnvironment — upsert by (scope, kind) ─────────────────────────────
-
-function recordEnvironment(opts = {}) {
-  const {
-    projectDir,
-    scope,
-    kind,
-    host,
-    port,
-    name,
-    authMethod,
-    secretVault,
-    secretEnvVarName,
-    fetchCommand,
-    connectCommand,
-    gotchas,
-  } = opts;
-
-  if (!projectDir) throw new Error("recordEnvironment: projectDir is required");
-  if (!scope) throw new Error("recordEnvironment: scope is required");
-  if (!kind) throw new Error("recordEnvironment: kind is required");
-
-  // HARD CONSTRAINT: per-column allowlist + marker-smuggle + secret backstop.
-  // Reject the ENTIRE row before any coercion or disk write.
-  validateRow(opts);
-
-  // Destructive-Action Guard: prod defaults read-only=YES unless explicitly set.
-  // Coerce any non-string/boolean input to a YES/NO string (never literal
-  // "false"/0/null leaking into the doc).
-  let readOnlyDefault = opts.readOnlyDefault;
-  if (readOnlyDefault === undefined || readOnlyDefault === null || readOnlyDefault === "") {
-    readOnlyDefault = scope === "prod" ? "YES" : "NO";
-  } else if (typeof readOnlyDefault === "boolean") {
-    readOnlyDefault = readOnlyDefault ? "YES" : "NO";
-  } else {
-    const s = String(readOnlyDefault).trim().toLowerCase();
-    readOnlyDefault = ["yes", "true", "1", "y"].includes(s) ? "YES" : "NO";
-  }
-
-  const recorded = new Date().toISOString();
-  const id = `${scope}-${kind}`;
-
-  const row = {
-    id,
-    scope,
-    kind,
-    host,
-    port,
-    "db/name": name,
-    "auth method": authMethod,
-    "secret vault": secretVault,
-    "secret env-var NAME": secretEnvVarName,
-    "fetch command": fetchCommand,
-    "connect command": connectCommand,
-    "access gotchas": gotchas,
-    "read-only default": readOnlyDefault,
-    recorded,
-  };
-
-  // (row is already fully validated above by validateRow — allowlist-per-column
-  // + marker-smuggle guard + entropy/prefix secret backstop.)
-  // Upsert by (scope, kind): replace the existing row with the same key, else
-  // append. This is what self-heals staleness (Aiven → Neon replaces the row).
-  const rows = parseRows(projectDir);
-  const key = (r) => `${r.scope} ${r.kind}`;
-  const thisKey = `${scope} ${kind}`;
-
-  // Detect a DIFFERENT host replacing the same (scope,kind) — surface it so a
-  // second real environment doesn't silently vanish into an upsert.
-  const prior = rows.find((r) => key(r) === thisKey);
-  const replaced = !!prior;
-  const oldHost = prior ? prior.host : undefined;
-  const newHost = optStr(host);
-  const warnedHostChange = replaced && !!oldHost && !!newHost && oldHost !== newHost;
-
-  const kept = rows.filter((r) => key(r) !== thisKey);
-  kept.push(row);
-
-  const block = buildTableBlock(kept);
-  const target = infraDocPath(projectDir);
-  upsertMarkedDocBlock(target, ENV_MARKER_START, ENV_MARKER_END, block);
-
-  const result = Object.assign({}, row, { replaced });
-  if (warnedHostChange) {
-    result.warnedHostChange = true;
-    result.oldHost = oldHost;
-    result.newHost = newHost;
-  }
-  return result;
-}
-
-// ─── lookupEnvironment — read-first (No-Re-Research) ─────────────────────────
-//
-// Returns the row for (scope, kind) or null. On null the CALLER HALTs and
-// documents — this module intentionally emits NO guessed connection string and
-// has NO transcript-grep rediscovery path. There is no fallback here by design.
-
-function lookupEnvironment(projectDir, scope, kind) {
-  const rows = parseRows(projectDir);
-  const match = rows.find((r) => r.scope === scope && r.kind === kind);
-  return match || null;
-}
-
-// ─── detectEnvConfig — reuse the detectStack SHAPE (map only, never a value) ──
-//
-// Reads .env.example / .env var NAMES, connection-string shapes, and
-// vercel/neon/gcloud presence to PROPOSE a vault + fetch command. Records the
-// map only — it NEVER reads or emits a secret value.
-
-function readEnvVarNames(projectDir) {
-  const names = new Set();
-  for (const f of [".env.example", ".env.sample", ".env.template"]) {
-    const p = path.join(projectDir, f);
-    if (!fs.existsSync(p)) continue;
-    let content;
-    try {
-      content = fs.readFileSync(p, "utf8");
-    } catch (_) {
-      continue;
-    }
-    for (const line of content.split("\n")) {
-      const m = line.match(/^\s*([A-Z][A-Z0-9_]*)\s*=/);
-      if (m) names.add(m[1]);
-    }
-  }
-  return Array.from(names);
-}
-
-function fileExists(projectDir, rel) {
-  return fs.existsSync(path.join(projectDir, rel));
-}
-
-function readPkgDeps(projectDir) {
-  const pkgPath = path.join(projectDir, "package.json");
-  let pkg = {};
-  try {
-    pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
-  } catch (_) {
-    return [];
-  }
-  const deps = Object.assign({}, pkg.dependencies || {}, pkg.devDependencies || {});
-  return Object.keys(deps).map((d) => d.toLowerCase());
-}
-
-function detectEnvConfig(projectDir) {
-  if (!projectDir) throw new Error("detectEnvConfig: projectDir is required");
-
-  const secretEnvVarNames = readEnvVarNames(projectDir);
-  const depNames = readPkgDeps(projectDir);
-
-  // Vault detection — convention-based, grounded in the 3 real inspected
-  // projects. Precedence: an explicit platform marker wins over plain .env.
-  const hasVercel = fileExists(projectDir, "vercel.json") || fileExists(projectDir, ".vercel");
-  const hasGoogle =
-    fileExists(projectDir, "cloudbuild.yaml") ||
-    fileExists(projectDir, "cloudbuild.yml") ||
-    fileExists(projectDir, ".gcloudignore");
-  const hasNeon =
-    depNames.some((d) => d === "@neondatabase/serverless" || d.includes("neon")) ||
-    fileExists(projectDir, ".neon");
-
-  let vault = "local (.env)";
-  let fetchCommand = secretEnvVarNames[0]
-    ? `read $${secretEnvVarNames[0]} from .env`
-    : "read from .env";
-
-  if (hasVercel) {
-    vault = "Vercel";
-    fetchCommand = "vercel env pull";
-  } else if (hasGoogle) {
-    vault = "Google Secret Manager";
-    fetchCommand = "gcloud secrets versions access latest --secret=<name>";
-  } else if (hasNeon) {
-    vault = "Neon";
-    fetchCommand = "neonctl connection-string";
-  }
-
-  return {
-    vault,
-    fetchCommand,
-    secretEnvVarNames,
-    signals: { hasVercel, hasGoogle, hasNeon },
-    detectedFrom: path.join(projectDir, "package.json"),
-  };
-}
-
-// ─── addPermissionEntry — broad-glob allow-entry per tool ────────────────────
-//
-// Reuses the guarded-write scaffold pattern from bin/gsd-t.js (invalid-JSON
-// guard + symlink guard + idempotent). Writes a BROAD GLOB per tool
-// (Bash(psql:*)), NOT the exact command string — the user-locked decision.
-
-function isSymlink(filePath) {
-  try {
-    return fs.lstatSync(filePath).isSymbolicLink();
-  } catch (_) {
-    return false;
-  }
-}
-
-// Derive the tool from the connect command's first meaningful token, skipping
-// leading env-var assignments (FOO=bar psql ...) and a leading `sudo`.
-function deriveTool(connectCommand) {
-  if (!connectCommand || typeof connectCommand !== "string") return null;
-  const tokens = connectCommand.trim().split(/\s+/);
-  let i = 0;
-  while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i])) i++;
-  if (tokens[i] === "sudo") i++;
-  const tool = tokens[i];
-  if (!tool) return null;
-  // Base name only (strip any path).
-  const base = tool.split("/").pop();
-  if (!base) return null;
-  // Reject a tool token carrying shell metacharacters — emitting Bash(psql;:*)
-  // (or worse) into the permission allowlist would be broken junk / an injection
-  // vector. A real tool name is plain `[A-Za-z0-9._-]`. Anything else → null
-  // (no permission entry written).
-  if (!/^[A-Za-z0-9._-]+$/.test(base)) return null;
-  return base;
-}
-
-function addPermissionEntry(projectDir, connectCommand) {
-  if (!projectDir) throw new Error("addPermissionEntry: projectDir is required");
-  const tool = deriveTool(connectCommand);
-  if (!tool) return { added: false, tool: null, entry: null, reason: "no tool derivable" };
-
-  const entry = `Bash(${tool}:*)`;
-  const settingsPath = path.join(projectDir, ".claude", "settings.json");
-
-  let settings = {};
-  if (fs.existsSync(settingsPath)) {
-    try {
-      settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
-      if (!settings || typeof settings !== "object") settings = {};
-    } catch (_) {
-      // invalid-JSON guard — do not clobber, report noop
-      return { added: false, tool, entry, reason: "settings.json has invalid JSON" };
-    }
-  }
-
-  if (!settings.permissions || typeof settings.permissions !== "object") settings.permissions = {};
-  if (!Array.isArray(settings.permissions.allow)) settings.permissions.allow = [];
-
-  if (settings.permissions.allow.includes(entry)) {
-    return { added: false, tool, entry, reason: "already present" };
-  }
-
-  if (isSymlink(settingsPath)) {
-    return { added: false, tool, entry, reason: "settings.json is a symlink" };
-  }
-
-  settings.permissions.allow.push(entry);
-
-  const dir = path.dirname(settingsPath);
-  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
-
-  return { added: true, tool, entry };
-}
-
-// ─── ensureEnvGitignored — auto-add + report (user-locked decision) ──────────
-
-function ensureEnvGitignored(projectDir) {
-  if (!projectDir) throw new Error("ensureEnvGitignored: projectDir is required");
-  const gitignorePath = path.join(projectDir, ".gitignore");
-
-  if (isSymlink(gitignorePath)) {
-    return { added: false, reason: ".gitignore is a symlink" };
-  }
-
-  let content = "";
-  if (fs.existsSync(gitignorePath)) content = fs.readFileSync(gitignorePath, "utf8");
-
-  const lines = content.split("\n").map((l) => l.trim());
-  // A broad `.env*` rule (or `*.env`) already covers every variant.
-  const hasBroadRule = lines.some((l) => l === ".env*" || l === "/.env*" || l === "*.env");
-
-  // Collect the env files actually present in the project — `.env`, `.env.local`,
-  // `.env.production`, etc. Each MUST be gitignored; a bare `.env` rule does NOT
-  // cover `.env.production`, so leaving it tracked would leak secrets.
-  let present = [];
-  try {
-    present = fs
-      .readdirSync(projectDir)
-      .filter((f) => f === ".env" || /^\.env\.[^/\\]+$/.test(f));
-  } catch (_) {
-    present = [];
-  }
-  // Always ensure at least a bare `.env` intent even if none is present yet.
-  const required = new Set([".env", ...present]);
-
-  const ignored = new Set(lines);
-  const isCovered = (name) =>
-    hasBroadRule || ignored.has(name) || ignored.has("/" + name);
-
-  const missing = [...required].filter((name) => !isCovered(name));
-  if (missing.length === 0) return { added: false, reason: "already gitignored" };
-
-  // Prefer a single broad `.env*` rule when more than one variant is present or
-  // missing — it future-proofs against new `.env.*` files.
-  const additions =
-    missing.length > 1 || present.some((f) => f !== ".env") ? [".env*"] : missing;
-
-  const next =
-    content.replace(/\s*$/, "") +
-    (content ? "\n" : "") +
-    additions.join("\n") +
-    "\n";
-  fs.writeFileSync(gitignorePath, next, "utf8");
-  return { added: true, rules: additions };
-}
-
-module.exports = {
-  recordEnvironment,
-  lookupEnvironment,
-  detectEnvConfig,
-  addPermissionEntry,
-  ensureEnvGitignored,
-  deriveTool,
-  looksLikeInlineSecret,
-  looksLikeSecretValue,
-  isHostShape,
-  isDbNameShape,
-  isSafeBareArg,
-  classifyCommandToken,
-  tokenizeCommand,
-  AUTH_METHODS,
-  CLI_WORDS,
-  ENV_COLUMNS,
-  ENV_MARKER_START,
-  ENV_MARKER_END,
-};
-
-// ─── CLI arm (so sandboxed workflows can call via Bash) ──────────────────────
-
-if (require.main === module) {
-  const args = process.argv.slice(2);
-  const sub = args[0];
-  const out = (obj) => process.stdout.write(JSON.stringify(obj, null, 2) + "\n");
-
-  try {
-    if (sub === "record") {
-      // node gsd-t-env-registry.cjs record '<json-opts>'
-      const opts = JSON.parse(args[1] || "{}");
-      out({ ok: true, row: recordEnvironment(opts) });
-    } else if (sub === "lookup") {
-      // node gsd-t-env-registry.cjs lookup <projectDir> <scope> <kind>
-      const row = lookupEnvironment(args[1], args[2], args[3]);
-      out({ ok: true, found: !!row, row });
-    } else if (sub === "detect") {
-      // node gsd-t-env-registry.cjs detect <projectDir>
-      out({ ok: true, detected: detectEnvConfig(args[1]) });
-    } else if (sub === "add-permission") {
-      // node gsd-t-env-registry.cjs add-permission <projectDir> '<connectCommand>'
-      out({ ok: true, result: addPermissionEntry(args[1], args[2]) });
-    } else if (sub === "ensure-gitignore") {
-      // node gsd-t-env-registry.cjs ensure-gitignore <projectDir>
-      out({ ok: true, result: ensureEnvGitignored(args[1]) });
-    } else {
-      out({
-        ok: false,
-        error:
-          "usage: env-registry <record|lookup|detect|add-permission|ensure-gitignore> ...",
-      });
-      process.exit(2);
-    }
-  } catch (e) {
-    out({ ok: false, error: e.message });
-    process.exit(1);
-  }
-}