mandrel-platform 1.8.1 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
   "license": "MIT",
   "repository": {

package/scripts/env-doctor.mjs

@@ -131,7 +131,7 @@ export const KEY_SCHEMA = Object.freeze({
   kind: "'var' | 'secret'",
   sensitivity: "'public' | 'secret'",
   residency:
-    "object — {local: 'var'|'secret'|'file'|null, github: {scope,kind}|null, cloudflare: {workers,kind}|null}",
+    "object — {local: 'var'|'secret'|'file'|null, github: G|G[]|null where G = {scope,kind,environments?}, cloudflare: {workers,kind}|null}",
   infisical: "{folder, environments} | 'unmanaged'",
   shape: `string? — one of ${SHAPE_NAMES.join(", ")}`,
   placeholderPattern: "string? — literal, case-insensitive substring marking an unset placeholder value",
@@ -181,6 +181,96 @@ export function parseManifest(raw) {
   return { environments: [...environments], workers, keys };
 }
 
+/**
+ * Normalize `residency.github` to its canonical array form.
+ *
+ * The field accepts EITHER a single `{scope, kind}` object — the shape every
+ * manifest written before Story #459 uses — or an array of them, because two
+ * residencies that occur in practice cannot be said with one object:
+ *
+ *   1. **Dual scope.** A key can legitimately live at repository level AND at
+ *      environment level, for different consumers: a deploy job declares
+ *      `environment:` and reads the per-environment value while a CI job
+ *      declares none and reads a repo-level credential of the same name.
+ *      Under a single object, whichever scope the manifest declared, the other
+ *      reported as an orphan — permanently, on a healthy repo.
+ *   2. **Per-environment presence.** A key can be deliberately present in one
+ *      environment and absent from another (a production-only analytics token
+ *      whose staging counterpart is meant to resolve empty). With no
+ *      per-entry `environments`, the absence read as a `missing` failure.
+ *
+ * Both authored shapes normalize to one array of `{scope, kind, environments}`
+ * with `environments` defaulted and materialized to `manifest.environments`,
+ * so `probeGitHub` has exactly one shape to read — the same normalize-at-parse
+ * treatment `infisical.environments` already receives.
+ *
+ * Validation fails closed, matching this module's posture on an unknown
+ * `shape`: silently ignoring a misplaced or misspelled `environments` is how a
+ * manifest author comes to believe they have scoped something they have not.
+ *
+ * @param {unknown} raw
+ * @param {{at: string, name: string, environments: string[]}} ctx
+ * @returns {Array<{scope: string, kind: string, environments: string[]}> | null}
+ */
+function normalizeGitHubResidency(raw, { at, name, environments }) {
+  if (raw === undefined || raw === null) return null;
+
+  const authoredAsArray = Array.isArray(raw);
+  const entries = authoredAsArray ? raw : [raw];
+  if (entries.length === 0) {
+    throw new Error(
+      `${at}.residency.github must not be an empty array — use null when the key does not belong in GitHub (key ${name})`
+    );
+  }
+
+  const seenPairs = new Set();
+  return entries.map((entry, j) => {
+    const where = authoredAsArray ? `${at}.residency.github[${j}]` : `${at}.residency.github`;
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new Error(`${where} must be an object with {scope, kind} (key ${name})`);
+    }
+    if (entry.scope !== "environment" && entry.scope !== "repository") {
+      throw new Error(`${where}.scope must be "environment" or "repository" (key ${name})`);
+    }
+    if (entry.kind !== "secret" && entry.kind !== "var") {
+      throw new Error(`${where}.kind must be "secret" or "var" (key ${name})`);
+    }
+
+    const pair = `${entry.scope}/${entry.kind}`;
+    if (seenPairs.has(pair)) {
+      throw new Error(
+        `${where} repeats the (scope, kind) pair "${pair}" — declare one entry per pair (key ${name})`
+      );
+    }
+    seenPairs.add(pair);
+
+    if (entry.environments !== undefined) {
+      if (entry.scope === "repository") {
+        throw new Error(
+          `${where}.environments is meaningful only under scope "environment" — a repository-scope ` +
+            `secret or variable belongs to no environment (key ${name})`
+        );
+      }
+      if (!Array.isArray(entry.environments) || !entry.environments.every((e) => typeof e === "string")) {
+        throw new Error(`${where}.environments must be an array of environment slugs (key ${name})`);
+      }
+      for (const e of entry.environments) {
+        if (!environments.includes(e)) {
+          throw new Error(
+            `${where}.environments names "${e}", absent from manifest.environments (key ${name})`
+          );
+        }
+      }
+    }
+
+    return {
+      scope: entry.scope,
+      kind: entry.kind,
+      environments: entry.environments ? [...entry.environments] : [...environments],
+    };
+  });
+}
+
 /**
  * @param {unknown} entry
  * @param {number} index
@@ -217,15 +307,7 @@ function validateKeyEntry(entry, index, workers, environments, seen) {
     throw new Error(`${at}.residency.local must be "var", "secret", "file" or null (key ${name})`);
   }
 
-  const github = residency.github ?? null;
-  if (github !== null) {
-    if (github.scope !== "environment" && github.scope !== "repository") {
-      throw new Error(`${at}.residency.github.scope must be "environment" or "repository" (key ${name})`);
-    }
-    if (github.kind !== "secret" && github.kind !== "var") {
-      throw new Error(`${at}.residency.github.kind must be "secret" or "var" (key ${name})`);
-    }
-  }
+  const github = normalizeGitHubResidency(residency.github, { at, name, environments });
 
   const cloudflare = residency.cloudflare ?? null;
   if (cloudflare !== null) {
@@ -774,12 +856,22 @@ export function runOfflineChecks({ manifest, repoRoot }) {
  * @param {string} opts.surface
  * @param {string | null} opts.environment
  * @param {string} [opts.scope]     Free-text scope for the detail line.
+ * @param {Iterable<string> | null} [opts.declaredElsewhere]
+ *   Names the caller has already accounted for in a SIBLING partition of the
+ *   same surface. A name in this set is never reported as an orphan here; it
+ *   has no effect on `missing`. The option exists because a surface can be
+ *   probed in more than one partition — GitHub is read at repository scope and
+ *   again per environment — and a key legitimately resident in two of them is
+ *   not drift. Only the caller knows which partitions are siblings, so the set
+ *   is supplied rather than inferred: the default is `null`, which keeps this
+ *   function's behaviour identical for every caller that omits it.
  * @returns {object[]} findings
  */
-export function reconcileNames({ expected, present, surface, environment, scope = "" }) {
+export function reconcileNames({ expected, present, surface, environment, scope = "", declaredElsewhere = null }) {
   const findings = [];
   const presentSet = new Set(present);
   const expectedSet = new Set(expected);
+  const elsewhere = declaredElsewhere ? new Set(declaredElsewhere) : null;
   const where = scope ? ` (${scope})` : "";
   for (const name of expected) {
     if (!presentSet.has(name)) {
@@ -795,6 +887,7 @@ export function reconcileNames({ expected, present, surface, environment, scope
   }
   for (const name of present) {
     if (!expectedSet.has(name)) {
+      if (elsewhere?.has(name)) continue;
       findings.push({
         severity: "orphan",
         kind: "orphan",
@@ -1065,6 +1158,45 @@ function unavailableNotice(unavailability, surface) {
 }
 
 /**
+ * Names declared at one GitHub `(scope, kind)`, optionally narrowed to the
+ * entries that name a given environment.
+ *
+ * @param {object[]} keys           Parsed manifest keys.
+ * @param {string} scope            "repository" | "environment"
+ * @param {string} kind             "secret" | "var"
+ * @param {string | null} environment  Non-null narrows to entries naming it.
+ * @returns {string[]}
+ */
+function githubNamesAt(keys, scope, kind, environment) {
+  return keys
+    .filter((k) =>
+      (k.residency.github ?? []).some(
+        (g) =>
+          g.scope === scope && g.kind === kind && (environment === null || g.environments.includes(environment))
+      )
+    )
+    .map((k) => k.name);
+}
+
+/**
+ * Reconcile the GitHub surface per `(scope, kind, environment)` triple.
+ *
+ * Two partitions are read — repository scope once, environment scope once per
+ * environment — and a key may legitimately be resident in both. So each
+ * partition suppresses orphans for names declared at the OTHER scope with the
+ * SAME kind, and nothing wider:
+ *
+ * - **Cross-scope, same kind** is suppressed: that is the dual-scope residency
+ *   the array form exists to describe, and reporting it was the false orphan.
+ * - **Cross-kind is NOT suppressed.** A name declared as a secret but present
+ *   as a variable is a real mismatch, and the orphan is how it surfaces.
+ * - **Cross-environment is NOT suppressed.** A production-only key turning up
+ *   in staging is undeclared presence in that environment — arguably the most
+ *   interesting thing this surface can find — so it still orphans.
+ *
+ * A name declared in no GitHub scope at all orphans exactly as before, which
+ * is what keeps `--strict-orphans` worth enabling once a manifest is correct.
+ *
  * @param {object} ctx
  */
 async function probeGitHub({ manifest, environments, github, surfaces, findings, unavailability = {} }) {
@@ -1076,18 +1208,18 @@ async function probeGitHub({ manifest, environments, github, surfaces, findings,
     });
     return;
   }
-  const repoKeys = manifest.keys.filter((k) => k.residency.github?.scope === "repository");
-  const envKeys = manifest.keys.filter((k) => k.residency.github?.scope === "environment");
+  const keys = manifest.keys;
   try {
     const present = await github.repositoryNames();
     for (const kind of ["secret", "var"]) {
       findings.push(
         ...reconcileNames({
-          expected: repoKeys.filter((k) => k.residency.github.kind === kind).map((k) => k.name),
+          expected: githubNamesAt(keys, "repository", kind, null),
           present: present[kind] ?? [],
           surface: "github",
           environment: null,
           scope: `repository ${kind}s`,
+          declaredElsewhere: githubNamesAt(keys, "environment", kind, null),
         })
       );
     }
@@ -1096,11 +1228,12 @@ async function probeGitHub({ manifest, environments, github, surfaces, findings,
       for (const kind of ["secret", "var"]) {
         findings.push(
           ...reconcileNames({
-            expected: envKeys.filter((k) => k.residency.github.kind === kind).map((k) => k.name),
+            expected: githubNamesAt(keys, "environment", kind, environment),
             present: envPresent[kind] ?? [],
             surface: "github",
             environment,
             scope: `environment ${kind}s`,
+            declaredElsewhere: githubNamesAt(keys, "repository", kind, null),
           })
         );
       }

package/scripts/env-doctor.test.mjs

@@ -186,6 +186,78 @@ test("parseManifest rejects a duplicate key name and an infisical env outside th
   assert.throws(() => parseManifest(badEnv), /absent from manifest.environments/);
 });
 
+test("parseManifest normalizes the single-object residency.github to a one-entry array", () => {
+  const m = parseManifest(singleWorkerManifest());
+  // The authored shape is an object; the parsed shape is always an array, so
+  // probeGitHub reads exactly one shape. `environments` defaults to all of
+  // manifest.environments, the same treatment infisical.environments gets.
+  assert.deepEqual(m.keys[0].residency.github, [
+    { scope: "environment", kind: "var", environments: ["staging", "production"] },
+  ]);
+});
+
+test("parseManifest accepts the array form and defaults environments per entry", () => {
+  const raw = singleWorkerManifest();
+  raw.keys[0].residency.github = [
+    { scope: "repository", kind: "var" },
+    { scope: "environment", kind: "var", environments: ["production"] },
+  ];
+  const m = parseManifest(raw);
+  assert.deepEqual(m.keys[0].residency.github, [
+    { scope: "repository", kind: "var", environments: ["staging", "production"] },
+    { scope: "environment", kind: "var", environments: ["production"] },
+  ]);
+});
+
+test("parseManifest rejects an residency.github environments slug outside manifest.environments", () => {
+  const raw = singleWorkerManifest();
+  raw.keys[0].residency.github = [{ scope: "environment", kind: "var", environments: ["preview"] }];
+  assert.throws(() => parseManifest(raw), (err) => {
+    assert.match(err.message, /absent from manifest.environments/);
+    assert.match(err.message, /PUBLIC_SITE_URL/);
+    return true;
+  });
+});
+
+test("parseManifest rejects environments on a repository-scope entry rather than ignoring it", () => {
+  // Silently ignoring it is how an author comes to believe they scoped
+  // something they did not — the same fail-closed posture as an unknown shape.
+  const raw = singleWorkerManifest();
+  raw.keys[0].residency.github = [{ scope: "repository", kind: "var", environments: ["production"] }];
+  assert.throws(() => parseManifest(raw), (err) => {
+    assert.match(err.message, /meaningful only under scope "environment"/);
+    assert.match(err.message, /PUBLIC_SITE_URL/);
+    return true;
+  });
+});
+
+test("parseManifest rejects a duplicate (scope, kind) pair and an empty residency.github array", () => {
+  const dup = singleWorkerManifest();
+  dup.keys[0].residency.github = [
+    { scope: "environment", kind: "var" },
+    { scope: "environment", kind: "var", environments: ["production"] },
+  ];
+  assert.throws(() => parseManifest(dup), (err) => {
+    assert.match(err.message, /repeats the \(scope, kind\) pair "environment\/var"/);
+    assert.match(err.message, /PUBLIC_SITE_URL/);
+    return true;
+  });
+
+  const empty = singleWorkerManifest();
+  empty.keys[0].residency.github = [];
+  assert.throws(() => parseManifest(empty), /must not be an empty array/);
+});
+
+test("parseManifest still rejects a malformed scope and kind under both authored shapes", () => {
+  const objForm = singleWorkerManifest();
+  objForm.keys[0].residency.github = { scope: "org", kind: "var" };
+  assert.throws(() => parseManifest(objForm), /\.scope must be "environment" or "repository"/);
+
+  const arrForm = singleWorkerManifest();
+  arrForm.keys[0].residency.github = [{ scope: "repository", kind: "file" }];
+  assert.throws(() => parseManifest(arrForm), /residency\.github\[0\]\.kind must be "secret" or "var"/);
+});
+
 test("resolveScriptName substitutes {env} per environment", () => {
   assert.equal(resolveScriptName("acme-site-{env}", "staging"), "acme-site-staging");
   assert.equal(resolveScriptName("acme-site-{env}", "production"), "acme-site-production");
@@ -458,6 +530,214 @@ test("a non-404 probe failure becomes an error surface and exits 1 — never 'no
   }
 });
 
+// ---------------------------------------------------------------------------
+// GitHub residency — dual scope and per-environment presence (Story #459)
+// ---------------------------------------------------------------------------
+
+/**
+ * A manifest with no workers and no local residency, so the offline arm over an
+ * empty repo root contributes no findings and every finding under test comes
+ * from the GitHub probe.
+ */
+function githubOnlyManifest(github) {
+  return parseManifest({
+    environments: ["staging", "production"],
+    keys: [{ name: "SHARED_TOKEN", kind: "secret", sensitivity: "secret", residency: { local: null, github } }],
+  });
+}
+
+/** Mock the two GitHub probe calls from a `{repository, staging, production}` map. */
+function githubProbe(present) {
+  const at = (slot) => ({ secret: [], var: [], ...(present[slot] ?? {}) });
+  return {
+    repositoryNames: async () => at("repository"),
+    environmentNames: async (environment) => at(environment),
+  };
+}
+
+async function githubFindings({ manifest, present, environments = ["staging", "production"] }) {
+  const root = makeRepo({});
+  try {
+    const report = await runDoctor({ manifest, repoRoot: root, environments, github: githubProbe(present) });
+    return report.findings.filter((f) => f.surface === "github");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+const DUAL_SCOPE = [
+  { scope: "repository", kind: "secret" },
+  { scope: "environment", kind: "secret" },
+];
+
+test("a dual-scope key present at both scopes reports no finding", async () => {
+  const findings = await githubFindings({
+    manifest: githubOnlyManifest(DUAL_SCOPE),
+    present: {
+      repository: { secret: ["SHARED_TOKEN"] },
+      staging: { secret: ["SHARED_TOKEN"] },
+      production: { secret: ["SHARED_TOKEN"] },
+    },
+  });
+  assert.deepEqual(findings, []);
+});
+
+test("a dual-scope key absent from one scope reports a missing naming that scope only", async () => {
+  const findings = await githubFindings({
+    manifest: githubOnlyManifest(DUAL_SCOPE),
+    present: {
+      repository: { secret: [] },
+      staging: { secret: ["SHARED_TOKEN"] },
+      production: { secret: ["SHARED_TOKEN"] },
+    },
+  });
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].kind, "missing");
+  assert.equal(findings[0].key, "SHARED_TOKEN");
+  assert.equal(findings[0].environment, null);
+  assert.match(findings[0].detail, /repository secrets/);
+});
+
+test("a dual-scope key absent from one environment reports a missing naming that environment only", async () => {
+  const findings = await githubFindings({
+    manifest: githubOnlyManifest(DUAL_SCOPE),
+    present: {
+      repository: { secret: ["SHARED_TOKEN"] },
+      staging: { secret: [] },
+      production: { secret: ["SHARED_TOKEN"] },
+    },
+  });
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].kind, "missing");
+  assert.equal(findings[0].environment, "staging");
+});
+
+test("an environments-scoped entry reports no missing for an environment it never names", async () => {
+  // The motivating case: a production-only analytics token whose staging
+  // counterpart is meant to resolve empty. That is design, not drift.
+  const manifest = githubOnlyManifest([{ scope: "environment", kind: "secret", environments: ["production"] }]);
+  assert.deepEqual(
+    await githubFindings({ manifest, present: { production: { secret: ["SHARED_TOKEN"] } } }),
+    []
+  );
+
+  const missing = await githubFindings({ manifest, present: {} });
+  assert.equal(missing.length, 1, "production still fails when it lacks the key");
+  assert.equal(missing[0].kind, "missing");
+  assert.equal(missing[0].environment, "production");
+});
+
+test("a key declared only at environment scope is not a repository-level orphan", async () => {
+  const findings = await githubFindings({
+    manifest: githubOnlyManifest([{ scope: "environment", kind: "secret" }]),
+    present: {
+      repository: { secret: ["SHARED_TOKEN"] },
+      staging: { secret: ["SHARED_TOKEN"] },
+      production: { secret: ["SHARED_TOKEN"] },
+    },
+  });
+  assert.deepEqual(findings, []);
+});
+
+test("suppression is cross-scope only — an undeclared name still orphans", async () => {
+  // The half that keeps --strict-orphans worth enabling: nothing about the
+  // suppression hides a name the manifest never declared anywhere.
+  const findings = await githubFindings({
+    manifest: githubOnlyManifest([{ scope: "environment", kind: "secret" }]),
+    present: {
+      repository: { secret: ["SHARED_TOKEN", "UNDECLARED_TOKEN"] },
+      staging: { secret: ["SHARED_TOKEN"] },
+      production: { secret: ["SHARED_TOKEN"] },
+    },
+  });
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].kind, "orphan");
+  assert.equal(findings[0].key, "UNDECLARED_TOKEN");
+  assert.equal(findings[0].environment, null);
+});
+
+test("suppression does not cross kind — a secret declared, a variable present, still orphans", async () => {
+  const findings = await githubFindings({
+    manifest: githubOnlyManifest([{ scope: "environment", kind: "secret" }]),
+    present: {
+      repository: { var: ["SHARED_TOKEN"] },
+      staging: { secret: ["SHARED_TOKEN"] },
+      production: { secret: ["SHARED_TOKEN"] },
+    },
+  });
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].kind, "orphan");
+  assert.match(findings[0].detail, /repository vars/);
+});
+
+test("suppression does not cross environment — a production-only key found in staging orphans", async () => {
+  // Undeclared presence in the wrong environment is the most interesting thing
+  // this surface can find, so the cross-scope rule must not reach it.
+  const findings = await githubFindings({
+    manifest: githubOnlyManifest([{ scope: "environment", kind: "secret", environments: ["production"] }]),
+    present: {
+      staging: { secret: ["SHARED_TOKEN"] },
+      production: { secret: ["SHARED_TOKEN"] },
+    },
+  });
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].kind, "orphan");
+  assert.equal(findings[0].environment, "staging");
+});
+
+test("the single-object residency.github form yields exactly the findings it did before", async () => {
+  // The regression case, over the unchanged existing fixture: both keys are
+  // authored as single objects at environment scope, so a repo-level probe
+  // holding neither must produce two per-environment missings and nothing else.
+  const root = makeRepo(CONSISTENT_REPO);
+  try {
+    const report = await runDoctor({
+      manifest: parseManifest(singleWorkerManifest()),
+      repoRoot: root,
+      environments: ["staging", "production"],
+      github: githubProbe({
+        staging: { var: ["PUBLIC_SITE_URL"], secret: ["TURSO_AUTH_TOKEN"] },
+        production: { var: ["PUBLIC_SITE_URL"] },
+      }),
+    });
+    const gh = report.findings.filter((f) => f.surface === "github");
+    assert.equal(gh.length, 1);
+    assert.deepEqual(
+      { kind: gh[0].kind, key: gh[0].key, environment: gh[0].environment },
+      { kind: "missing", key: "TURSO_AUTH_TOKEN", environment: "production" }
+    );
+    assert.equal(report.surfaces.find((s) => s.surface === "github").status, "checked");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("declaredElsewhere suppresses only orphans, never a missing", async () => {
+  // The new argument is opt-in and orphan-only, so the cloudflare and infisical
+  // call sites that omit it cannot change behaviour.
+  const suppressed = reconcileNames({
+    expected: ["A"],
+    present: ["B"],
+    surface: "github",
+    environment: null,
+    declaredElsewhere: ["A", "B"],
+  });
+  assert.deepEqual(
+    suppressed.map((f) => [f.kind, f.key]),
+    [["missing", "A"]]
+  );
+  assert.deepEqual(reconcileNames({ expected: [], present: ["B"], surface: "github", environment: null }), [
+    {
+      severity: "orphan",
+      kind: "orphan",
+      key: "B",
+      surface: "github",
+      environment: null,
+      detail: "present in github but declared by no manifest key",
+    },
+  ]);
+});
+
 test("the Cloudflare probe resolves {env} in scriptName once per environment", async () => {
   const root = makeRepo(CONSISTENT_REPO);
   const asked = [];