@devdogsuga/devtools 0.1.0

package/dist/doctor.js

@@ -0,0 +1,225 @@
+/**
+ * Does my app's moderation integration actually work?
+ *
+ * Two checks, and the second is the one that matters.
+ *
+ * `conformance()` asks the database what it derived from your schema: is the
+ * table addressable, can an author be attributed, does quarantine have a column
+ * to write to, can a client still write that column. All of it is answerable
+ * from the catalog, and `platform.conformance_check()` does the answering.
+ *
+ * `quarantineRoundTrip()` answers the question the catalog cannot: *does
+ * quarantine do anything?* Quarantine is the only moderation outcome whose
+ * effect lives in the app's own policies rather than the platform's, so it is
+ * the only one that can be wired up wrong while everything appears to work.
+ * The platform records the decision, sets the column, and has no way to notice
+ * nobody reads it. The only proof is to file, resolve, and then look.
+ *
+ * It runs against `platform.profile`, where quarantine means FREEZE rather than
+ * hide: the display name is reset to the member's name of record and they lose
+ * the ability to change it back. A profile cannot be hidden: rosters, teams
+ * and standings all render the name, and the row is own-row-only over PostgREST
+ * anyway, so there is nobody to hide it from. See
+ * 20260808000000_platform_profile_moderation.sql.
+ *
+ * Both run as seeded personas over PostgREST rather than as `postgres` over
+ * SQL, because RLS is the thing under test and a superuser bypasses it.
+ */
+import { adminClient, personaClient, PERSONA_PASSWORD, PERSONAS, } from "./instance.js";
+/** Runs `platform.conformance_check()` as the seeded moderator. */
+export async function conformance(instance, appSlug) {
+    const client = await personaClient(instance, PERSONAS.moderator);
+    const { data, error } = await client.rpc("conformance_check", {
+        app_slug: appSlug,
+    });
+    if (error)
+        throw new Error(error.message);
+    return (data ?? []);
+}
+/** The apps that have anything to check, for the picker. */
+export async function listApps(instance) {
+    const { data, error } = await adminClient(instance)
+        .from("apps")
+        .select("slug")
+        .order("slug");
+    if (error)
+        throw new Error(error.message);
+    return (data ?? []).map((row) => row.slug);
+}
+/**
+ * Files a report against a profile, resolves it with quarantine, and checks
+ * that the freeze and the name reset both landed.
+ *
+ * The subject is a THROWAWAY member created for the run, not one of the seeded
+ * personas, and that is not squeamishness about touching fixtures.
+ * `file_report` corroborates an existing open report rather than filing a
+ * second one against the same content, and the seeds ship exactly such a report
+ * against the author persona's profile. Reusing it would make this function's
+ * first step silently become "add a corroboration", and every assertion after
+ * it would be reading the seed's decision instead of its own.
+ *
+ * Everything it creates, it deletes, including on the failure paths, which is
+ * why the teardown is in a `finally`. A contributor running this twice should
+ * get the same answer the second time.
+ */
+export async function quarantineRoundTrip(instance) {
+    const steps = [];
+    const admin = adminClient(instance);
+    const email = `roundtrip-${crypto.randomUUID().slice(0, 8)}@devdogs.test`;
+    const abusiveName = "BUY CHEAP FOLLOWERS NOW";
+    let subjectId = null;
+    let reportId = null;
+    try {
+        // ── Arrange: a member with an abusive display name and a name of record ──
+        //
+        // Through the GoTrue admin API rather than `from("users")`: the `auth`
+        // schema is not exposed over PostgREST, and should not be.
+        const { data: created, error: createErr } = await admin.auth.admin.createUser({
+            email,
+            password: PERSONA_PASSWORD,
+            email_confirm: true,
+        });
+        if (createErr ?? !created.user) {
+            throw new Error(`Could not create the subject account: ${createErr?.message}`);
+        }
+        subjectId = created.user.id;
+        const { error: profileErr } = await admin.from("profile").insert({
+            userId: subjectId,
+            preferredName: abusiveName,
+            bio: "Created by `pnpm devtools`, and deleted again immediately.",
+            // The name the reset restores. Written by the Involvement roster import
+            // in production (server/actions/verification.ts); set by hand here so the
+            // round-trip exercises the branch that has something to restore.
+            legalFirstName: "Round",
+            legalLastName: "Trip",
+        });
+        if (profileErr) {
+            throw new Error(`Could not create a profile: ${profileErr.message}`);
+        }
+        steps.push({
+            name: "fixture",
+            ok: true,
+            detail: `Created a profile named "${abusiveName}" with a name of record.`,
+        });
+        // ── Editable before ─────────────────────────────────────────────────────
+        //
+        // Establishes the baseline the freeze is measured against. Without it a
+        // profile that was never editable in the first place would pass the freeze
+        // check for the wrong reason.
+        const subject = await personaClient(instance, email);
+        await subject
+            .from("profile")
+            .update({ bio: "Edited." })
+            .eq("userId", subjectId);
+        const { data: beforeRow } = await admin
+            .from("profile")
+            .select("bio")
+            .eq("userId", subjectId)
+            .single();
+        const editableBefore = beforeRow?.bio === "Edited.";
+        steps.push({
+            name: "editable_before",
+            ok: editableBefore,
+            detail: editableBefore
+                ? "The member can edit their own profile before it is reported."
+                : "The member could NOT edit their own profile before it was reported — the update policy is denying more than quarantine.",
+        });
+        // ── Act: file a report as the seeded member ─────────────────────────────
+        const memberClient = await personaClient(instance, PERSONAS.member);
+        // A literal, not a lookup. The vocabulary is a platform-owned enum, so
+        // there is no per-app row to find first. If this label ever stops existing,
+        // Postgres rejects the call by type rather than silently reporting "no
+        // reasons configured".
+        const { data: filed, error: fileErr } = await memberClient.rpc("file_report", {
+            app_slug: "platform",
+            content_type: "profile",
+            content_ref: subjectId,
+            reason: "spam",
+            description: "Filed by the devtools round-trip.",
+        });
+        if (fileErr)
+            throw new Error(`file_report failed: ${fileErr.message}`);
+        // A one-element array, not an object: these RPCs return `setof` now, so
+        // PostgREST serialises even a single result as a list.
+        const [row] = (filed ?? []);
+        if (!row)
+            throw new Error("file_report returned no rows");
+        reportId = row.reportId;
+        steps.push({
+            name: "file_report",
+            ok: true,
+            detail: `A member filed a report against the profile (${reportId}).`,
+        });
+        // ── Act: resolve with quarantine as the moderator ───────────────────────
+        const moderator = await personaClient(instance, PERSONAS.moderator);
+        const { error: resolveErr } = await moderator.rpc("resolve_report", {
+            report_id: reportId,
+            subject_action: "no_action",
+            filer_action: "no_action",
+            content_action: "quarantine",
+            moderator_note: "devtools round-trip",
+        });
+        if (resolveErr) {
+            throw new Error(`resolve_report failed: ${resolveErr.message}`);
+        }
+        steps.push({
+            name: "resolve_report",
+            ok: true,
+            detail: "A moderator resolved the report with `quarantine`.",
+        });
+        // ── Assert: the effect actually landed ──────────────────────────────────
+        const { data: after } = await admin
+            .from("profile")
+            .select("quarantinedBy, preferredName")
+            .eq("userId", subjectId)
+            .single();
+        const columnSet = Boolean(after?.quarantinedBy);
+        steps.push({
+            name: "quarantine_column",
+            ok: columnSet,
+            detail: columnSet
+                ? 'The resolution set "quarantinedBy" on the row.'
+                : 'The resolution did NOT set "quarantinedBy" — apply_content_action did not reach this table.',
+        });
+        const nameReset = after?.preferredName === "Round Trip";
+        steps.push({
+            name: "name_reset",
+            ok: nameReset,
+            detail: nameReset
+                ? 'The display name was reset to the name of record ("Round Trip").'
+                : `The display name is still "${String(after?.preferredName)}" — the reset trigger did not fire, so the remedy is a record with no effect.`,
+        });
+        // ── Assert: and that the member stopped being able to undo it ───────────
+        //
+        // The check that matters. A denied UPDATE under RLS is not an error, it
+        // simply matches no rows, so asserting on `error` here would pass just as
+        // happily if the write had landed. Read the value back instead.
+        await subject
+            .from("profile")
+            .update({ preferredName: abusiveName })
+            .eq("userId", subjectId);
+        const { data: frozenRow } = await admin
+            .from("profile")
+            .select("preferredName")
+            .eq("userId", subjectId)
+            .single();
+        const frozen = frozenRow?.preferredName !== abusiveName;
+        steps.push({
+            name: "frozen_after",
+            ok: frozen,
+            detail: frozen
+                ? "The member can no longer change their display name back."
+                : 'The member CHANGED IT STRAIGHT BACK. The update policy does not filter on "quarantinedBy" — this is the check that matters.',
+        });
+        return steps;
+    }
+    finally {
+        // Teardown runs whether or not the assertions held. Deleting the report
+        // first lets the resolution cascade, which releases the FK on the profile;
+        // deleting the auth user then cascades to the profile row itself.
+        if (reportId)
+            await admin.from("reports").delete().eq("id", reportId);
+        if (subjectId)
+            await admin.auth.admin.deleteUser(subjectId);
+    }
+}

package/dist/emails/commands.d.ts

@@ -0,0 +1,15 @@
+import { EMAIL_FIXTURES } from "./fixtures.js";
+export type EmailFormat = "html" | "text";
+export declare const EMAIL_FORMATS: readonly ["html", "text"];
+export type EmailName = keyof typeof EMAIL_FIXTURES;
+export declare const EMAIL_NAMES: EmailName[];
+export interface EmailOptions {
+    names: EmailName[];
+    formats: EmailFormat[];
+    out: string;
+    noOutput: boolean;
+}
+export declare function parseEmailArgs(argv: readonly string[], cwd: string): EmailOptions | Error;
+export declare function destination(out: string, name: EmailName, format: EmailFormat): string;
+export declare function generateEmails(options: EmailOptions): Promise<string[]>;
+export declare function runEmails(argv: string[]): Promise<void>;

package/dist/emails/commands.js

@@ -0,0 +1,130 @@
+/** `pnpm devtools emails [template…] [--format html,text] [--out dir]`. */
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { isTTY, log, multiselect, note, text as askText } from "@clack/prompts";
+import { positionals } from "../args.js";
+import { errorMessage, explain, unwrap } from "../ui.js";
+import { EMAIL_FIXTURES } from "./fixtures.js";
+import { loadEmail } from "../repo/source.js";
+export const EMAIL_FORMATS = ["html", "text"];
+export const EMAIL_NAMES = Object.keys(EMAIL_FIXTURES);
+function flagValue(argv, flag) {
+    const index = argv.indexOf(flag);
+    if (index === -1)
+        return undefined;
+    const value = argv[index + 1];
+    return value && !value.startsWith("--") ? value : undefined;
+}
+function expandHome(value) {
+    return value === "~" || value.startsWith("~/")
+        ? resolve(homedir(), value.slice(2))
+        : value;
+}
+export function parseEmailArgs(argv, cwd) {
+    const requested = positionals(argv);
+    const unknown = requested.filter((name) => name !== "*" && !EMAIL_NAMES.includes(name));
+    if (unknown.length) {
+        return new Error(`No email template called ${unknown.join(", ")}. Try ${EMAIL_NAMES.join(", ")}, or *.`);
+    }
+    const rawFormats = (flagValue(argv, "--format") ?? "html")
+        .split(",")
+        .map((value) => value.trim())
+        .filter(Boolean);
+    const badFormats = rawFormats.filter((value) => !EMAIL_FORMATS.includes(value));
+    if (badFormats.length)
+        return new Error(`Unknown format ${badFormats.join(", ")}. Try html or text.`);
+    const names = requested.includes("*")
+        ? [...EMAIL_NAMES]
+        : requested;
+    return {
+        names,
+        formats: [...new Set(rawFormats)],
+        out: resolve(cwd, expandHome(flagValue(argv, "--out") ?? "email-previews")),
+        noOutput: argv.includes("--dry-run") || argv.includes("--no-output"),
+    };
+}
+async function interactive(options) {
+    if (options.names.length)
+        return options;
+    if (!isTTY(process.stdout)) {
+        throw new Error("No terminal to choose templates. Name one, or pass * for all.");
+    }
+    const names = unwrap(await multiselect({
+        message: "Which emails?",
+        options: EMAIL_NAMES.map((name) => ({ value: name, label: name })),
+        initialValues: [...EMAIL_NAMES],
+        required: true,
+    }));
+    const formats = unwrap(await multiselect({
+        message: "Which formats?",
+        options: [
+            { value: "html", label: "HTML", hint: "open in a browser" },
+            { value: "text", label: "Plain text", hint: "the email alternative" },
+        ],
+        initialValues: ["html"],
+        required: true,
+    }));
+    const entered = unwrap(await askText({
+        message: "Where should these go?",
+        placeholder: "./email-previews",
+        defaultValue: "./email-previews",
+    })).trim();
+    return {
+        ...options,
+        names,
+        formats,
+        out: resolve(process.cwd(), expandHome(entered || "email-previews")),
+    };
+}
+export function destination(out, name, format) {
+    return resolve(out, `${name}.${format === "text" ? "txt" : "html"}`);
+}
+export async function generateEmails(options) {
+    // Dynamic so every unrelated devtools command can still run before the
+    // generated email package has been built on a fresh checkout.
+    const { render } = await loadEmail();
+    const written = [];
+    for (const name of options.names) {
+        const email = render(name, EMAIL_FIXTURES[name]);
+        for (const format of options.formats) {
+            const file = destination(options.out, name, format);
+            await mkdir(dirname(file), { recursive: true });
+            await writeFile(file, format === "html" ? email.html : email.text);
+            written.push(file);
+        }
+    }
+    return written;
+}
+export async function runEmails(argv) {
+    const parsed = parseEmailArgs(argv, process.cwd());
+    if (parsed instanceof Error) {
+        explain("Could not read that.", parsed.message, [
+            "pnpm devtools emails",
+            "pnpm devtools emails '*' --format html,text --out ~/emails",
+        ]);
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const options = await interactive(parsed);
+        if (options.noOutput) {
+            const { render } = await loadEmail();
+            note(options.names
+                .map((name) => `${name}\n  ${render(name, EMAIL_FIXTURES[name]).subject}\n  ${options.formats.map((f) => destination(options.out, name, f)).join("\n  ")}`)
+                .join("\n"), `${options.names.length} email template${options.names.length === 1 ? "" : "s"}`);
+            return;
+        }
+        const written = await generateEmails(options);
+        for (const file of written)
+            log.success(file);
+        log.info(`${written.length} preview file${written.length === 1 ? "" : "s"} written.`);
+    }
+    catch (err) {
+        explain("Could not render those emails.", errorMessage(err), [
+            "Build the email package with `pnpm --filter @devdogsuga/email build`.",
+            "Then try `pnpm devtools emails '*' --out ~/emails`.",
+        ]);
+        process.exitCode = 1;
+    }
+}

package/dist/emails/email-types.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Type-only stand-in for `@devdogsuga/email`'s generated `Templates` map.
+ *
+ * `@devdogsuga/email` is `"private": true` and never published — it stays
+ * in DevDogsUGA and devtools resolves it FROM the repo at runtime
+ * (`repo/source.ts`'s `loadEmail()`). Backstage has no copy to pull the
+ * real generated type from, so `fixtures.ts`'s `satisfies` check is
+ * loosened to "every template's fixture is a flat string-prop object"
+ * instead of the real per-template exact prop shape. A prop typo here is
+ * caught at runtime (the real `render()` throws on a missing required
+ * prop), not at Backstage's typecheck time.
+ */
+export type EmailTemplates = Record<string, Record<string, string>>;

package/dist/emails/email-types.js

@@ -0,0 +1 @@
+export {};

package/dist/emails/fixtures.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Credible, non-sensitive values for local previews.
+ *
+ * `satisfies` is the maintenance mechanism: a new template or prop cannot be
+ * shipped without deciding what its preview should say.
+ */
+export declare const EMAIL_FIXTURES: {
+    JoinRequest: {
+        leadName: string;
+        applicantName: string;
+        teamName: string;
+        reviewUrl: string;
+    };
+    TeamInvite: {
+        inviteeName: string;
+        teamName: string;
+        leadName: string;
+        acceptUrl: string;
+    };
+};

package/dist/emails/fixtures.js

@@ -0,0 +1,20 @@
+/**
+ * Credible, non-sensitive values for local previews.
+ *
+ * `satisfies` is the maintenance mechanism: a new template or prop cannot be
+ * shipped without deciding what its preview should say.
+ */
+export const EMAIL_FIXTURES = {
+    JoinRequest: {
+        leadName: "Jordan",
+        applicantName: "Avery",
+        teamName: "Byte Bulldogs",
+        reviewUrl: "https://devdogsuga.org/teams/requests",
+    },
+    TeamInvite: {
+        inviteeName: "Avery",
+        teamName: "Byte Bulldogs",
+        leadName: "Jordan",
+        acceptUrl: "https://devdogsuga.org/teams/requests",
+    },
+};

package/dist/env/audit.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Four-way drift detection: local `.env`, Bitwarden, GitHub, Cloudflare.
+ *
+ * Each store answers a different question, and only one of them answers it
+ * completely:
+ *
+ *   | Store              | Exposes           | So it can be checked for |
+ *   |--------------------|-------------------|--------------------------|
+ *   | local .env         | names AND values  | value drift              |
+ *   | Bitwarden          | names AND values  | value drift (the truth)  |
+ *   | GitHub *secrets*   | names + updatedAt | presence, staleness      |
+ *   | GitHub *variables* | names AND values  | value drift              |
+ *   | Cloudflare         | names only        | presence, orphans        |
+ *
+ * That asymmetry is the whole design. A GitHub *secret* is write-only, so a
+ * clean audit of one does not mean "the values match". It means "nothing
+ * detectable is wrong", and the report says which is which rather than implying
+ * the stronger claim.
+ *
+ * Timestamps are what rescue that row from being presence-only. Bitwarden
+ * reports a `revisionDate` per secret and `gh secret list` reports `updatedAt`,
+ * so "was GitHub updated after Bitwarden last changed?" IS answerable. That is
+ * the failure this design actually has: a credential rotated in Bitwarden and
+ * never propagated, which a name-only check calls healthy right up until the old
+ * one is revoked.
+ *
+ * ⚠️ GitHub *variables* are the one downstream store that needs none of that
+ * reasoning: `gh variable list` returns the value, so the public per-environment
+ * keys are compared exactly the way the local file is. Staleness is deliberately
+ * NOT applied to them: a timestamp is a proxy for a comparison that could not
+ * be made, and using the proxy where the real answer is available would report a
+ * variable re-pushed with an identical value as drift. The security plan's §3.6
+ * limitation ("names only… a changed value is undetectable") now holds for the
+ * secret row alone.
+ *
+ * ⚠️ One scope sits outside that table altogether: the repository's OWN
+ * variables. Push writes environment-scoped values only, and an environment
+ * variable SHADOWS a repository one of the same name, so a repository-level
+ * copy of a managed key is read by nothing, drifts forever, and becomes the
+ * live value on the day somebody deletes the environment copy. It is checked
+ * here for the same reason §3.6's orphans are: nothing manages it, so nothing
+ * else in this system would ever mention it.
+ */
+export type Severity = "error" | "warning" | "info";
+export interface Finding {
+    key: string;
+    severity: Severity;
+    /** Where the problem is, for grouping. */
+    store: "local" | "github" | "cloudflare";
+    summary: string;
+}
+export interface BwsEntry {
+    value: string;
+    /** ISO 8601. Absent when the CLI did not report one. */
+    revisionDate?: string;
+}
+export interface GithubEntry {
+    /** Which GitHub environment this copy sits in. */
+    environment: string;
+    name: string;
+    /** ISO 8601. */
+    updatedAt?: string;
+}
+/**
+ * A GitHub environment *variable*: the same shape plus the thing that makes
+ * variables worth having, a readable value.
+ */
+export interface GithubVariableEntry extends GithubEntry {
+    value: string;
+}
+export interface AuditInput {
+    /** Active assignments in the local `.env`. */
+    local: Map<string, string>;
+    /** Keys present in the local `.env` but commented out. */
+    localCommented?: Set<string>;
+    /** The source of truth. */
+    bws: Map<string, BwsEntry>;
+    /**
+     * Every GitHub copy found, across every environment this project feeds.
+     *
+     * A list rather than a map keyed by name, because one Bitwarden project can
+     * feed two GitHub environments and the interesting case is a key appearing in
+     * BOTH, which a name-keyed map would quietly collapse to one.
+     */
+    github: GithubEntry[];
+    /**
+     * Every GitHub environment *variable* found, across the same environments.
+     *
+     * Separate from `github` rather than merged with a discriminator, because
+     * GitHub genuinely allows one name to exist as both a secret and a variable
+     * in one environment and resolves the ambiguity by never telling you. See
+     * `deploy/write-env.ts`, which refuses that case outright. Two lists can
+     * represent it; one list keyed by name cannot, and would silently pick a
+     * winner.
+     */
+    githubVariables?: GithubVariableEntry[];
+    /**
+     * Keys that belong in the variable store rather than the secret store, from
+     * `variableKeys()` in the registry.
+     *
+     * Drives two things at once: which store a key is compared against, and the
+     * pair of misplacement errors. Absent, every key is treated as a secret,
+     * which is the pre-variables behaviour.
+     */
+    variables?: ReadonlySet<string>;
+    /**
+     * Where a key is supposed to live: the PRIMARY environment, the one whose
+     * absence is an error. `null` means "nowhere in this environment", which is
+     * ordinary rather than wrong.
+     */
+    route: (key: string) => string | null;
+    /**
+     * Whether a copy found in some OTHER environment is legitimate.
+     *
+     * Separate from `route` because the two questions stopped having the same
+     * answer when `production-apply` became a superset of `production`: an
+     * ordinary production key is now pushed to both, so "not where `route` says"
+     * no longer means "misplaced". Folding them back together reports every
+     * correctly-pushed copy as a stray to delete, and a reviewer who deletes 46
+     * of those learns to skim the stray finding, which is the one finding that
+     * catches an apply-tier credential sitting in the unreviewed environment.
+     *
+     * Defaults to the old behaviour (`only where route says`), so a caller that
+     * has not thought about fan-out gets the strict answer rather than a
+     * permissive one.
+     */
+    accepted?: (key: string, environment: string) => boolean;
+    /** Worker name → secret names on it. Values are unreadable. */
+    cloudflare?: Map<string, Set<string>>;
+    /** Keys that legitimately live outside Bitwarden: the non-secrets. */
+    ignore?: ReadonlySet<string>;
+    /**
+     * Credentials that must never be stored remotely at all.
+     *
+     * Distinct from `ignore`, and the opposite of it: an ignored key is expected
+     * somewhere else, whereas one of these appearing in ANY remote store is a
+     * finding. Being in the local `.env` and nowhere else is the correct state,
+     * so the ordinary "not in Bitwarden" warning must not fire for them.
+     */
+    neverStore?: ReadonlySet<string>;
+    /**
+     * Credentials signed at deploy time, whose only copy is on the deploy target.
+     *
+     * The third category, and it sits between the other two rather than beside
+     * them: unlike `ignore` it is a secret, and unlike `neverStore` there is one
+     * remote store it BELONGS in. A key like this is signed at deploy time and
+     * written straight to the Worker, so being on Cloudflare and nowhere else is
+     * exactly right. `SANDBOX_PROXY_TOKEN` is still declared this way in
+     * `apps/sandbox/env.ts` — nothing mints it any more, since the deploy that
+     * did was removed with the sandbox integration it authenticated, but the
+     * declaration is what keeps this category from reading "on production-
+     * sandbox, not in Bitwarden" the day someone does fill it in by hand.
+     *
+     * Without this set the Cloudflare pass below reports a key like that as an
+     * orphan, which the plan doc's §3.6 prune path then offers to delete.
+     * Marking it the other obvious way, as `never-store`, inverts the error into
+     * "must NEVER be a Worker secret" and is just as wrong in the opposite
+     * direction.
+     */
+    minted?: ReadonlySet<string>;
+    /**
+     * Every key the registry knows. When provided, a local key outside it is
+     * reported as UNDECLARED: its own category, not folded into drift, because
+     * the fix is different: drift wants a push or a pull, an undeclared key
+     * wants a `define()` in the owning manifest (or the line removed). It is
+     * also why `env push` skipped it, and the audit should say so rather
+     * than let "not in Bitwarden" imply pushing would help.
+     */
+    declared?: ReadonlySet<string>;
+    /**
+     * The repository's OWN variables, the scope with no environment, or the fact
+     * that they could not be listed.
+     *
+     * A union rather than a list, because three states have to stay apart and a
+     * list can only hold two of them: nobody looked (absent: the pre-existing
+     * behaviour, no claim either way), looked and saw these names
+     * (`readable`), and TRIED TO LOOK AND COULD NOT (`readable: false`). Listing
+     * repository variables can fail where listing environment ones succeeds, so
+     * the third state is ordinary rather than exotic, and collapsing it into an
+     * empty list is precisely the bug this check was added to catch, one scope
+     * up: a report that says "checked, nothing found" about a check that never
+     * ran.
+     *
+     * Names only. See `GhRepositoryVariable` for why the value is deliberately
+     * not fetched.
+     */
+    repositoryVariables?: RepositoryVariableScan;
+}
+/**
+ * What `gh variable list` (no `--env`) returned, or why it returned nothing.
+ *
+ * `reason` is carried rather than dropped because the two failures need
+ * different next steps and look identical from a finding that omits it: a
+ * missing permission is fixed by an admin, an unauthenticated CLI by the person
+ * reading the report.
+ */
+export type RepositoryVariableScan = {
+    readable: true;
+    names: readonly string[];
+} | {
+    readable: false;
+    reason: string;
+};
+export declare function audit(input: AuditInput): Finding[];
+export declare function hasErrors(findings: Finding[]): boolean;
+export declare function renderFindings(findings: Finding[]): string;