@devdogsuga/devtools 0.1.0

package/dist/gh/client.d.ts

@@ -0,0 +1,80 @@
+export declare class GhError extends Error {
+}
+export interface GhSecret {
+    name: string;
+    updatedAt: string;
+}
+/** Unlike `GhSecret`, this carries the value: variables are readable. */
+export interface GhVariable {
+    name: string;
+    value: string;
+    updatedAt: string;
+}
+/** Environment secret names and when each last changed. Never values. */
+export declare function listSecrets(environment: string): Promise<GhSecret[]>;
+/**
+ * Sets one secret, passing the value on **stdin**.
+ *
+ * Not `--body`, which would put a live credential in argv where `ps` can read
+ * it. Not `--env-file` either, despite it being one call for the whole set:
+ * that hands the file to `gh`'s own dotenv parser, and this tool has already
+ * parsed it with different rules. Two parsers over one file agree right up
+ * until a multi-line value, a PEM private key being the case, and then disagree
+ * silently, storing something that looks like a key and is not.
+ *
+ * One process per secret is the cost. It is paid once per rotation.
+ */
+export declare function setSecret(environment: string, name: string, value: string): Promise<void>;
+export declare function deleteSecret(environment: string, name: string): Promise<void>;
+/**
+ * Environment variable names, VALUES, and when each last changed.
+ *
+ * The value is the point. It is what turns the GitHub half of `env audit` from
+ * a presence check into a real comparison for these keys: a variable whose
+ * value drifted from Bitwarden is detectable, where the same drift in a secret
+ * is not detectable by anything.
+ */
+export declare function listVariables(environment: string): Promise<GhVariable[]>;
+/**
+ * Sets one variable, passing the value on **stdin**.
+ *
+ * Stdin rather than `--body` even though a variable is public by definition:
+ * argv is shared machinery, and a rule with an exception ("stdin for secrets,
+ * argv for variables") is a rule somebody applies to the wrong call. The
+ * `--env-file` form is refused for the reason `setSecret` refuses it: it would
+ * hand the file to `gh`'s own dotenv parser, which agrees with this tool's
+ * parser right up until a multi-line value and then disagrees silently.
+ */
+export declare function setVariable(environment: string, name: string, value: string): Promise<void>;
+export declare function deleteVariable(environment: string, name: string): Promise<void>;
+/**
+ * A repository-level variable. NAME ONLY, and that is deliberate.
+ *
+ * `gh variable list` will return the value here as readily as it does for an
+ * environment variable, and fetching it would invite the obvious next step,
+ * comparing it against Bitwarden. That comparison has no correct answer. This
+ * copy is unmanaged whatever it holds, so a value that matches today proves
+ * nothing except that somebody set them the same way once; reporting only the
+ * mismatch would then read as "the matching one is fine", which is the belief
+ * this whole check exists to break.
+ */
+export interface GhRepositoryVariable {
+    name: string;
+    updatedAt: string;
+}
+/**
+ * The repository's OWN variables, the ones with no environment.
+ *
+ * ⚠️ The reason this exists at all: an environment variable of the same name
+ * **shadows** a repository one, and nothing in GitHub's UI says so. Every job
+ * that runs in the environment reads the environment copy, so a repository
+ * variable a person set by hand before `env push` routed that key keeps its
+ * stale value indefinitely and invisibly, right up until somebody deletes the
+ * environment copy, at which point the stale value silently becomes live.
+ *
+ * No `--env`, and that missing flag IS the call. Everything else in this file
+ * addresses one environment; this addresses the repository itself, which is
+ * the scope nothing here writes to and therefore the scope nothing here would
+ * otherwise notice.
+ */
+export declare function listRepositoryVariables(): Promise<GhRepositoryVariable[]>;

package/dist/gh/client.js

@@ -0,0 +1,258 @@
+/**
+ * A thin wrapper over the `gh` CLI, for environment secrets and variables.
+ *
+ * `gh` rather than the REST API for the same reason `bws` is used over its API:
+ * a secret's value has to be encrypted client-side with a libsodium sealed box
+ * against the environment's public key before it can be sent. `gh` does that
+ * locally. Doing it by hand means fetching the key, pulling in a sodium
+ * binding, and owning that code forever to avoid one dependency that is already
+ * installed.
+ *
+ * ## Secrets and variables are two different stores
+ *
+ * They share an environment and nothing else, and the differences are the whole
+ * reason the public per-environment values go to the second:
+ *
+ *   |            | Sent as    | Readable back | In logs        |
+ *   |------------|------------|---------------|----------------|
+ *   | secret     | sealed box | never         | masked, by substring |
+ *   | variable   | plaintext  | value and all | verbatim       |
+ *
+ * The masking is not a nicety either way. `PROJECT_REF` as a *secret* rewrites
+ * `https://supabase.com/dashboard/project/<ref>` to `.../***`, which is the
+ * paused-project gate's whole output. And because the ref is a substring of
+ * every Supabase hostname, it corrupts unrelated log lines across the repo. The
+ * readability is what lets `env audit` compare a variable by VALUE, which it
+ * cannot do for anything on the top row.
+ *
+ * ⚠️ The corollary, and the reason each setter is its own function rather than
+ * one with a flag: putting a secret in the variable store publishes its value
+ * to anyone with read access to the repository's Actions config, silently and
+ * irreversibly. There is no operation here that can be pointed at the wrong
+ * store by a boolean somebody passed the wrong way round.
+ */
+import { spawn } from "node:child_process";
+import { promisify } from "node:util";
+import { execFile } from "node:child_process";
+const run = promisify(execFile);
+const MAX_BUFFER = 16 * 1024 * 1024;
+export class GhError extends Error {
+}
+let warnedAboutTokenOverride = false;
+/**
+ * Says, once, when `gh` is about to ignore its own login.
+ *
+ * `gh` prefers `GH_TOKEN` / `GITHUB_TOKEN` from the environment over the
+ * account somebody logged in with, and `with-env` loads `.env` for every
+ * devtools command, so a token line in that file takes over EVERY `gh` call
+ * silently. That is how a leftover classic PAT kept authenticating after the
+ * operator's real login was a perfectly valid OAuth token, right up until
+ * the org's classic-PAT block turned it into a 403 with no visible cause.
+ * stderr and not clack, so it shows the same way from every command shape.
+ */
+function warnOnEnvTokenOverride() {
+    if (warnedAboutTokenOverride)
+        return;
+    const source = process.env.GH_TOKEN
+        ? "GH_TOKEN"
+        : process.env.GITHUB_TOKEN
+            ? "GITHUB_TOKEN"
+            : undefined;
+    if (!source)
+        return;
+    warnedAboutTokenOverride = true;
+    console.error(`gh: authenticating with ${source} from the environment, NOT your ` +
+        "`gh auth login` account. with-env loads .env, so a token line there " +
+        "takes over silently — comment it out if that is not what you meant.");
+}
+/**
+ * Turns a spawn failure into something with a next step in it.
+ *
+ * The three that happen are a missing binary, an unauthenticated CLI, and an
+ * environment that does not exist yet. The last reports as a bare 404, because
+ * an environment you cannot see and one that was never created look identical
+ * from here.
+ */
+function describe(err) {
+    const e = err;
+    if (e.code === "ENOENT") {
+        return ("The `gh` CLI is not installed, or is not on PATH.\n" +
+            "Install it from https://cli.github.com, then run `gh auth login`.");
+    }
+    const stderr = (e.stderr ?? "").trim();
+    if (/personal access token \(classic\)/i.test(stderr)) {
+        return (`${stderr}\n\n` +
+            "The organization forbids classic PATs (by design — §0.3), and gh " +
+            "authenticated with one anyway. gh prefers GH_TOKEN / GITHUB_TOKEN " +
+            "from the environment over your `gh auth login`, and with-env loads " +
+            ".env — so the usual culprit is a leftover ghp_ token line in that " +
+            "file. Comment it out (and revoke the token at " +
+            "github.com/settings/tokens); your stored gh login then takes over.");
+    }
+    if (/not logged into|authentication required|gh auth login/i.test(stderr)) {
+        return `${stderr}\n\nRun \`gh auth login\`. Managing environment secrets needs the \`repo\` scope.`;
+    }
+    if (/404|not found/i.test(stderr)) {
+        return (`${stderr}\n\n` +
+            "A 404 usually means the environment does not exist yet — GitHub creates " +
+            "environments explicitly, and a typo silently addresses a different one. " +
+            "Check Settings → Environments.");
+    }
+    if (/403|forbidden|must have admin/i.test(stderr)) {
+        return `${stderr}\n\nSetting environment secrets needs admin on the repository.`;
+    }
+    if (/\b429\b|rate.?limit|too many requests/i.test(stderr)) {
+        return (`${stderr}\n\n` +
+            "GitHub rate-limited this. A push is one API call per secret, so a " +
+            "burst of pushes can trip the secondary limit — wait a minute and " +
+            "re-run; already-written values are simply overwritten with themselves.");
+    }
+    return stderr || e.message || "gh failed with no output.";
+}
+/** Environment secret names and when each last changed. Never values. */
+export async function listSecrets(environment) {
+    warnOnEnvTokenOverride();
+    try {
+        const { stdout } = await run("gh", ["secret", "list", "--env", environment, "--json", "name,updatedAt"], { maxBuffer: MAX_BUFFER, shell: false });
+        return stdout.trim() === "" ? [] : JSON.parse(stdout);
+    }
+    catch (err) {
+        throw new GhError(describe(err));
+    }
+}
+/**
+ * Sets one secret, passing the value on **stdin**.
+ *
+ * Not `--body`, which would put a live credential in argv where `ps` can read
+ * it. Not `--env-file` either, despite it being one call for the whole set:
+ * that hands the file to `gh`'s own dotenv parser, and this tool has already
+ * parsed it with different rules. Two parsers over one file agree right up
+ * until a multi-line value, a PEM private key being the case, and then disagree
+ * silently, storing something that looks like a key and is not.
+ *
+ * One process per secret is the cost. It is paid once per rotation.
+ */
+export async function setSecret(environment, name, value) {
+    warnOnEnvTokenOverride();
+    await new Promise((resolve, reject) => {
+        const child = spawn("gh", ["secret", "set", name, "--env", environment], {
+            stdio: ["pipe", "ignore", "pipe"],
+            shell: false,
+        });
+        let stderr = "";
+        child.stderr.on("data", (c) => (stderr += c.toString()));
+        child.on("error", (err) => reject(new GhError(describe(err))));
+        child.on("close", (code) => code === 0
+            ? resolve()
+            : reject(new GhError(describe({ stderr, message: `gh exited ${code}` }))));
+        // Exactly the bytes, with no trailing newline: `gh` stores stdin verbatim,
+        // so a stray "\n" becomes part of the secret and every comparison against
+        // it fails in a way that reads like a wrong value rather than a stray byte.
+        child.stdin.end(value);
+    });
+}
+export async function deleteSecret(environment, name) {
+    warnOnEnvTokenOverride();
+    try {
+        await run("gh", ["secret", "delete", name, "--env", environment], {
+            shell: false,
+        });
+    }
+    catch (err) {
+        throw new GhError(describe(err));
+    }
+}
+// ── variables ────────────────────────────────────────────────────────────────
+/**
+ * Environment variable names, VALUES, and when each last changed.
+ *
+ * The value is the point. It is what turns the GitHub half of `env audit` from
+ * a presence check into a real comparison for these keys: a variable whose
+ * value drifted from Bitwarden is detectable, where the same drift in a secret
+ * is not detectable by anything.
+ */
+export async function listVariables(environment) {
+    warnOnEnvTokenOverride();
+    try {
+        const { stdout } = await run("gh", [
+            "variable",
+            "list",
+            "--env",
+            environment,
+            "--json",
+            "name,value,updatedAt",
+        ], { maxBuffer: MAX_BUFFER, shell: false });
+        return stdout.trim() === "" ? [] : JSON.parse(stdout);
+    }
+    catch (err) {
+        throw new GhError(describe(err));
+    }
+}
+/**
+ * Sets one variable, passing the value on **stdin**.
+ *
+ * Stdin rather than `--body` even though a variable is public by definition:
+ * argv is shared machinery, and a rule with an exception ("stdin for secrets,
+ * argv for variables") is a rule somebody applies to the wrong call. The
+ * `--env-file` form is refused for the reason `setSecret` refuses it: it would
+ * hand the file to `gh`'s own dotenv parser, which agrees with this tool's
+ * parser right up until a multi-line value and then disagrees silently.
+ */
+export async function setVariable(environment, name, value) {
+    warnOnEnvTokenOverride();
+    await new Promise((resolve, reject) => {
+        const child = spawn("gh", ["variable", "set", name, "--env", environment], {
+            stdio: ["pipe", "ignore", "pipe"],
+            shell: false,
+        });
+        let stderr = "";
+        child.stderr.on("data", (c) => (stderr += c.toString()));
+        child.on("error", (err) => reject(new GhError(describe(err))));
+        child.on("close", (code) => code === 0
+            ? resolve()
+            : reject(new GhError(describe({ stderr, message: `gh exited ${code}` }))));
+        // No trailing newline, for a reason that bites harder here than it does for
+        // a secret: the stored value IS readable, so a stray "\n" turns every
+        // `audit` run into a value-drift error against a Bitwarden copy that is
+        // actually identical, and no amount of re-pushing fixes it.
+        child.stdin.end(value);
+    });
+}
+export async function deleteVariable(environment, name) {
+    warnOnEnvTokenOverride();
+    try {
+        await run("gh", ["variable", "delete", name, "--env", environment], {
+            shell: false,
+        });
+    }
+    catch (err) {
+        throw new GhError(describe(err));
+    }
+}
+/**
+ * The repository's OWN variables, the ones with no environment.
+ *
+ * ⚠️ The reason this exists at all: an environment variable of the same name
+ * **shadows** a repository one, and nothing in GitHub's UI says so. Every job
+ * that runs in the environment reads the environment copy, so a repository
+ * variable a person set by hand before `env push` routed that key keeps its
+ * stale value indefinitely and invisibly, right up until somebody deletes the
+ * environment copy, at which point the stale value silently becomes live.
+ *
+ * No `--env`, and that missing flag IS the call. Everything else in this file
+ * addresses one environment; this addresses the repository itself, which is
+ * the scope nothing here writes to and therefore the scope nothing here would
+ * otherwise notice.
+ */
+export async function listRepositoryVariables() {
+    warnOnEnvTokenOverride();
+    try {
+        const { stdout } = await run("gh", ["variable", "list", "--json", "name,updatedAt"], { maxBuffer: MAX_BUFFER, shell: false });
+        return stdout.trim() === ""
+            ? []
+            : JSON.parse(stdout);
+    }
+    catch (err) {
+        throw new GhError(describe(err));
+    }
+}

package/dist/gh/environments.d.ts

@@ -0,0 +1,83 @@
+export declare const GITHUB_ENVIRONMENTS: readonly ["preflight", "staging", "production", "production-apply"];
+export type GithubEnvironment = (typeof GITHUB_ENVIRONMENTS)[number];
+export declare function isGithubEnvironment(v: string): v is GithubEnvironment;
+export interface GithubEnvironmentSpec {
+    /** BWS project to compare against, or null when nothing backs it. */
+    bwsProject: string | null;
+    /** Deployment branch policy, for the summary line. */
+    branch: string;
+    /**
+     * Keys allowed here, or null for "whatever the file defines".
+     *
+     * ⚠️ NULL ON EVERY ROW TODAY, and that is the deliberate state rather than a
+     * field nobody got round to filling in. `production-apply` used to carry the
+     * apply-tier pair here, on the reasoning that "holding a third credential
+     * makes the reviewer gate stop meaning anything", which conflated two
+     * constraints and kept only the one that was not the gate. An allowlist here
+     * restricts what the REVIEWED environment may hold; the gate is
+     * `production.excludeKeys`, which restricts what the UNREVIEWED one may hold.
+     * Only the second is a security property, and it is enforced below.
+     *
+     * Kept as a field because the mechanism is worth having and costs one branch
+     * in `accepts()`: a future environment that genuinely holds a fixed short
+     * list, a third-party integration's two keys and nothing else, states it here
+     * rather than as an `excludeKeys` of everything else.
+     */
+    onlyKeys: readonly string[] | null;
+    /**
+     * Keys that must never reach this environment.
+     *
+     * The whole reviewer gate now lives in this field: `production` (and
+     * `staging`) exclude the apply-tier set, and nothing else stops a
+     * write-capable credential from landing in an environment that deploys with
+     * nobody in front of it.
+     */
+    excludeKeys: readonly string[];
+    /** Extra confirmation before writing. */
+    guarded: boolean;
+}
+export declare const GITHUB_ENVIRONMENT_SPECS: Record<GithubEnvironment, GithubEnvironmentSpec>;
+/** The GitHub environments fed by one Bitwarden project, in precedence order. */
+export declare function githubTargets(bwsProject: string): GithubEnvironment[];
+/** Whether one environment takes a given key. */
+export declare function accepts(environment: GithubEnvironment, key: string): boolean;
+/**
+ * The PRIMARY environment a key belongs in, or `null` for "nowhere here".
+ *
+ * `null` is not an error. Pushing `staging` with an apply-only credential in
+ * the file is the ordinary case: that key belongs to production and has no home
+ * in the staging environment.
+ *
+ * ⚠️ "Primary", not "only". Since `production-apply` became a superset, an
+ * ordinary production key legitimately lives in TWO environments and this
+ * returns the first, the unreviewed one, where the deploy reads it. A caller
+ * asking "is this copy misplaced?" wants `acceptedBy()` instead; answering that
+ * question with this function reports every correctly-pushed copy in
+ * `production-apply` as a stray that somebody should delete.
+ */
+export declare function routeTo(bwsProject: string, key: string): GithubEnvironment | null;
+/**
+ * EVERY environment of a project that takes a key, in precedence order.
+ *
+ * The set-shaped question, for callers that compare against what a push
+ * actually wrote rather than against one destination. `routeTo()` is this with
+ * `[0]` taken, and the difference is only ever visible for `production`, the
+ * one project that fans out to two environments.
+ */
+export declare function acceptedBy(bwsProject: string, key: string): GithubEnvironment[];
+/**
+ * `accepts()` for an environment name that has not been narrowed yet, in the
+ * argument order `AuditInput.accepted` wants.
+ *
+ * Exists so that the predicate `env audit` hands the audit is a NAME rather
+ * than a lambda written at the call site: `runEnvAudit` cannot be unit-tested
+ * without mocking Bitwarden, GitHub and Cloudflare at once, so anything spelled
+ * out there is untested by construction.
+ *
+ * ⚠️ An unrecognised environment is REFUSED, not accepted. The string comes
+ * from whatever `gh` listed, and the audit uses this to decide whether a found
+ * copy is a stray. Failing open here would silence the finding for a copy
+ * sitting in an environment this repository has never heard of, which is
+ * exactly the case worth hearing about.
+ */
+export declare function acceptsKey(key: string, environment: string): boolean;

package/dist/gh/environments.js

@@ -0,0 +1,178 @@
+/**
+ * The GitHub environments, and which BWS project (if any) backs each.
+ *
+ * GitHub environments and BWS projects are NOT the same set, and conflating
+ * them is the mistake this file exists to prevent. There are FOUR GitHub
+ * environments and THREE BWS projects:
+ *
+ *   | GitHub environment | BWS project  | Receives                     |
+ *   |--------------------|--------------|------------------------------|
+ *   | `preflight`        | `preflight`  | everything in the project    |
+ *   | `staging`          | `staging`    | everything in the project    |
+ *   | `production`       | `production` | everything EXCEPT apply-only |
+ *   | `production-apply` | `production` | everything, apply-only too   |
+ *
+ * The last two split one project between two GitHub environments, and that
+ * split IS the reviewer gate. `production` deploys on a push with nothing in
+ * front of it; `production-apply` has required reviewers. A write-capable
+ * credential reaching the first makes the second decorative, so the routing is
+ * enforced here rather than left to whoever last edited a file.
+ *
+ * ⚠️ THE GATE IS ONE-DIRECTIONAL, and reading it as symmetric is the mistake
+ * this file made until 2026-08-17. What the gate asserts, through
+ * `production.excludeKeys`, is that apply-tier credentials never reach the
+ * UNREVIEWED environment, and nothing more. What the reviewed environment also
+ * holds buys no privilege: it is the same Bitwarden project, and
+ * `production-apply` is the strictly MORE trusted of the two. Withholding
+ * ordinary keys from it broke every job that runs there: the config push wanted
+ * deploy-tier OAuth secrets, and the orphan prune wanted a deploy-tier API
+ * token. So `production-apply` now receives a SUPERSET of `production`.
+ */
+import { assertRegistryLoaded } from "../env/discovery.js";
+import { getEnvSync } from "../repo/peers.js";
+export const GITHUB_ENVIRONMENTS = [
+    "preflight",
+    "staging",
+    "production",
+    "production-apply",
+];
+export function isGithubEnvironment(v) {
+    return GITHUB_ENVIRONMENTS.includes(v);
+}
+/**
+ * The apply-only set, derived from the env manifests (`tier: "apply"` on the
+ * declarations in `packages/devtools/env.ts`) rather than listed here.
+ *
+ * Read at ACCESS time, not module load: this module is imported by the CLI
+ * before any manifest is, so a snapshot taken now would be empty, and an empty
+ * apply set routes the write-capable credentials to the unreviewed
+ * `production` environment, which is the exact failure the split exists to
+ * prevent. The guard turns "forgot to loadRegistry()" into a crash instead.
+ */
+function applyOnly() {
+    assertRegistryLoaded();
+    return getEnvSync().applyOnlyKeys();
+}
+/**
+ * The plan-tier set, same shape and same load-time caveat as `applyOnly()`.
+ * Read by `main-plan` (preflight) and `production-plan` (production); a copy
+ * anywhere else is a credential nothing reads, so `staging` excludes it.
+ */
+function planOnly() {
+    assertRegistryLoaded();
+    return getEnvSync().planOnlyKeys();
+}
+export const GITHUB_ENVIRONMENT_SPECS = {
+    preflight: {
+        bwsProject: "preflight",
+        branch: "main",
+        onlyKeys: null,
+        excludeKeys: [],
+        guarded: false,
+    },
+    staging: {
+        bwsProject: "staging",
+        branch: "main",
+        onlyKeys: null,
+        // Both narrow tiers: no staging job plans, and none may apply.
+        get excludeKeys() {
+            return [...applyOnly(), ...planOnly()];
+        },
+        guarded: false,
+    },
+    // ⚠️ THE REVIEWER GATE, in one property. `excludeKeys` here is the only
+    // thing keeping the apply-tier credentials out of an environment that
+    // deploys on a push to `production` with nobody in front of it. Widening it
+    // to `[]` hands a write-capable token to an unreviewed deploy, and so does
+    // letting `applyOnly()` answer empty, which is what `assertRegistryLoaded()`
+    // exists to prevent. `environments.test.ts` asserts both apply keys by name
+    // against exactly this.
+    production: {
+        bwsProject: "production",
+        branch: "production",
+        onlyKeys: null,
+        get excludeKeys() {
+            return applyOnly();
+        },
+        guarded: true,
+    },
+    // A SUPERSET of `production`, deliberately: everything that environment
+    // receives, plus the apply-tier credential it may not have.
+    //
+    // Not a relaxation of the gate. This is the same Bitwarden project behind
+    // required reviewers, the more trusted half of the split, so withholding a
+    // key from it protects nothing and only starves the jobs that run here
+    // (`production-config`, `prune-orphans`, both of which needed a deploy-tier
+    // secret and got none). The gate is what `production` may NOT have, one row
+    // above.
+    "production-apply": {
+        bwsProject: "production",
+        branch: "production",
+        onlyKeys: null,
+        excludeKeys: [],
+        guarded: true,
+    },
+};
+// ── Routing ──────────────────────────────────────────────────────────────────
+//
+// One Bitwarden project can feed more than one GitHub environment; production
+// feeds two. So a push has to know which key goes where. Derived from the table
+// above rather than written out a second time: the split IS the reviewer gate,
+// and a hardcoded copy of it is a copy that can disagree.
+/** The GitHub environments fed by one Bitwarden project, in precedence order. */
+export function githubTargets(bwsProject) {
+    return GITHUB_ENVIRONMENTS.filter((e) => GITHUB_ENVIRONMENT_SPECS[e].bwsProject === bwsProject);
+}
+/** Whether one environment takes a given key. */
+export function accepts(environment, key) {
+    const spec = GITHUB_ENVIRONMENT_SPECS[environment];
+    return spec.onlyKeys
+        ? spec.onlyKeys.includes(key)
+        : !spec.excludeKeys.includes(key);
+}
+/**
+ * The PRIMARY environment a key belongs in, or `null` for "nowhere here".
+ *
+ * `null` is not an error. Pushing `staging` with an apply-only credential in
+ * the file is the ordinary case: that key belongs to production and has no home
+ * in the staging environment.
+ *
+ * ⚠️ "Primary", not "only". Since `production-apply` became a superset, an
+ * ordinary production key legitimately lives in TWO environments and this
+ * returns the first, the unreviewed one, where the deploy reads it. A caller
+ * asking "is this copy misplaced?" wants `acceptedBy()` instead; answering that
+ * question with this function reports every correctly-pushed copy in
+ * `production-apply` as a stray that somebody should delete.
+ */
+export function routeTo(bwsProject, key) {
+    return acceptedBy(bwsProject, key)[0] ?? null;
+}
+/**
+ * EVERY environment of a project that takes a key, in precedence order.
+ *
+ * The set-shaped question, for callers that compare against what a push
+ * actually wrote rather than against one destination. `routeTo()` is this with
+ * `[0]` taken, and the difference is only ever visible for `production`, the
+ * one project that fans out to two environments.
+ */
+export function acceptedBy(bwsProject, key) {
+    return githubTargets(bwsProject).filter((e) => accepts(e, key));
+}
+/**
+ * `accepts()` for an environment name that has not been narrowed yet, in the
+ * argument order `AuditInput.accepted` wants.
+ *
+ * Exists so that the predicate `env audit` hands the audit is a NAME rather
+ * than a lambda written at the call site: `runEnvAudit` cannot be unit-tested
+ * without mocking Bitwarden, GitHub and Cloudflare at once, so anything spelled
+ * out there is untested by construction.
+ *
+ * ⚠️ An unrecognised environment is REFUSED, not accepted. The string comes
+ * from whatever `gh` listed, and the audit uses this to decide whether a found
+ * copy is a stray. Failing open here would silence the finding for a copy
+ * sitting in an environment this repository has never heard of, which is
+ * exactly the case worth hearing about.
+ */
+export function acceptsKey(key, environment) {
+    return isGithubEnvironment(environment) && accepts(environment, key);
+}

package/dist/gh/rulesets/actors.d.ts

@@ -0,0 +1,14 @@
+/** `GET /orgs/{org}/teams/{slug}` -> the team's numeric id. */
+export declare function resolveTeamId(org: string, slug: string): Promise<number>;
+/**
+ * `GET /orgs/{org}/installations` -> the id of the App installation whose
+ * `app_slug` matches, e.g. `devdogs-platform` (production) or
+ * `devdogs-platform-staging`.
+ *
+ * `orgs/{org}/installations` rather than the App's own `/app` endpoint: the
+ * latter needs App-JWT auth this CLI has no path to, while the installations
+ * list is a plain org-admin GET — the exact command DevDogsUGA's own
+ * `docs/platform/guides/identity/github-app.md` already tells an operator to
+ * run to verify the App's permission grant.
+ */
+export declare function resolveAppId(org: string, appSlug: string): Promise<number>;