@devdogsuga/devtools 0.1.0

package/dist/deploy/orphans.js

@@ -0,0 +1,177 @@
+/**
+ * `devtools deploy orphans [--prune]`
+ *
+ * Reports, and only when asked deletes, Worker secrets nothing declares.
+ *
+ * ## Why there is anything to audit
+ *
+ * `wrangler deploy --secrets-file` applies additively: it preserves every
+ * secret it does not mention. So renaming a variable, or dropping one, leaves
+ * the old secret on the Worker indefinitely, and nothing else in the system can
+ * see it. Bitwarden does not know about it, GitHub does not, and the app's
+ * schema stopped mentioning it. Cloudflare will hold a credential nobody has
+ * thought about for a year.
+ *
+ * The expected set is derived from the app's own manifest: every key it
+ * declares with `secrecy: "secret"`. That deliberately includes the MINTED
+ * ones. `SANDBOX_PROXY_TOKEN` has no copy in Bitwarden or GitHub by design, and
+ * an audit that reasoned from stored copies alone would report the live proxy
+ * credential as safe to delete. (`env audit` had exactly that bug; see
+ * `EnvMeta.minted`.)
+ *
+ * ## Report always, prune almost never (security plan §3.6)
+ *
+ *   report   every production deploy      environment: production
+ *   prune    `workflow_dispatch` only     environment: production-apply
+ *
+ * **Orphans never fail the deploy.** A stale secret name is not a defect in the
+ * change being deployed, and failing on it would make an unrelated commit
+ * responsible for a cleanup somebody else deferred. So the reporting path
+ * returns normally even when it found something; the only non-zero exit here is
+ * a deletion that was asked for and did not happen.
+ *
+ * **Pruning must not chain to a deploy.** Deleting a secret publishes a new
+ * version of the currently deployed code with the secret gone. There is no way
+ * to change a secret without publishing. Auto-pruning would turn every deploy
+ * carrying an orphan into TWO version publishes, and the second one bypasses
+ * both the promotion PR and the `production-apply` approval that the first went
+ * through. That is why this is a separate, human-triggered run, and why
+ * `--prune` is the only thing that can reach `deleteSecret`: a default that
+ * deleted would be a default that deployed.
+ *
+ * > **Names only.** Cloudflare never returns a secret's value, so a secret
+ * > whose VALUE is wrong is undetectable here. A clean audit means "no name is
+ * > unaccounted for", not "the configuration is correct".
+ *
+ * Recovery from a wrong prune is real but not instant: Bitwarden is the source
+ * of truth and every deploy sends the complete set, so a wrongly deleted secret
+ * comes back on the next deploy, with an outage in between.
+ *
+ * ## Interface
+ *
+ * Reads secret NAMES from Cloudflare and needs no env file, so it runs through
+ * the `cli:no-env` seam like `write-env` does. There is no `.env.production` in
+ * the job that audits, and demanding one would be demanding the whole
+ * credential set to list some names:
+ *
+ *   DEPLOY_ENV=production \
+ *     pnpm --filter @devdogsuga/devtools run cli:no-env deploy orphans [--prune]
+ */
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { assertRegistryLoaded } from "../env/discovery.js";
+import { listWorkerSecrets, workerApps } from "../env/cloudflare.js";
+import { getEnvSync } from "../repo/peers.js";
+import { findRepoRoot } from "../repo/root.js";
+import { DeployError, say, summary } from "./report.js";
+/**
+ * Deletes one secret through wrangler.
+ *
+ * Wrangler prompts before deleting and takes the default when stdin is not a
+ * TTY, which on a runner it is not. `stdio: "inherit"` keeps its own output on
+ * the job log where a reviewer approving this can read it.
+ */
+function deleteViaWrangler(root, app, key, environment) {
+    execFileSync("pnpm", 
+    // WRANGLER's `--env` is a wrangler.jsonc environment block. Unrelated to
+    // devtools' `--target`, and not renamed with it.
+    ["exec", "wrangler", "secret", "delete", key, "--env", environment], { cwd: join(root, "apps", app), stdio: "inherit", shell: false });
+}
+/**
+ * Names the app's manifest declares for its Worker: secrets (stored or minted)
+ * AND public server keys. `secrets-file` ships both since 2026-08-20, so a
+ * public key on the Worker is expected, not an orphan.
+ */
+function expectedFor(app) {
+    const keys = new Set();
+    for (const [key, entries] of getEnvSync().variables()) {
+        const own = entries.filter((e) => e.source === app && !e.client);
+        if (own.length === 0)
+            continue;
+        if (own.some((e) => e.meta.secrecy === "secret" || e.meta.secrecy === "public")) {
+            keys.add(key);
+        }
+    }
+    return keys;
+}
+export async function runDeployOrphans(options) {
+    assertRegistryLoaded();
+    const env = options.env ?? process.env;
+    const root = options.root ?? findRepoRoot();
+    const listSecrets = options.listSecrets ?? listWorkerSecrets;
+    const deleteSecret = options.deleteSecret ??
+        ((app, key, environment) => deleteViaWrangler(root, app, key, environment));
+    const environment = getEnvSync().resolveEnvironment(env.DEPLOY_ENV);
+    if (environment === "development") {
+        throw new DeployError("DEPLOY_ENV must name a deployed environment (staging | production).");
+    }
+    // Both the job summary and the log, because a run of this IS its report and
+    // the two audiences read different places.
+    const emit = (lines) => {
+        summary(lines, env);
+        say(lines);
+    };
+    const { secrets, unreadable } = await listSecrets(environment);
+    const lines = [
+        `### Worker secret audit — \`${environment}\``,
+        "",
+        "Names only: Cloudflare never returns a value, so this cannot see a secret",
+        "that is present and wrong.",
+        "",
+    ];
+    let total = 0;
+    const toPrune = [];
+    for (const app of workerApps()) {
+        const worker = `${environment}-${app}`;
+        const found = secrets.get(worker);
+        if (!found)
+            continue;
+        const expected = expectedFor(app);
+        const orphans = [...found].filter((name) => !expected.has(name)).sort();
+        total += orphans.length;
+        lines.push(orphans.length === 0
+            ? `* \`${worker}\` — ${found.size} secret(s), nothing unaccounted for.`
+            : `* \`${worker}\` — **${orphans.length} orphaned**: ${orphans.map((o) => `\`${o}\``).join(", ")}`);
+        for (const key of orphans)
+            toPrune.push({ app, worker, key });
+    }
+    if (unreadable.length > 0) {
+        lines.push("", `Could not read: ${unreadable.map((w) => `\`${w}\``).join(", ")}. A Worker`, "that has never been deployed is the ordinary reason, and the audit still", "reports everything it could see — an audit that refuses to run is an", "audit nobody runs.");
+    }
+    if (total === 0) {
+        lines.push("", "No orphaned secrets.");
+        emit([...lines, ""]);
+        return { orphans: 0, pruned: [] };
+    }
+    if (!options.prune) {
+        lines.push("", "Nothing was deleted, and this does not fail the deploy — a stale name is", "not a defect in the change that was just shipped. To remove them, run", "this workflow by hand with **Prune orphaned Worker secrets** ticked; it", "goes through the `production-apply` reviewers, because each deletion", "publishes a new version of the deployed code.", "");
+        emit(lines);
+        return { orphans: total, pruned: [] };
+    }
+    lines.push("", "Pruning:");
+    const pruned = [];
+    for (const { app, worker, key } of toPrune) {
+        try {
+            deleteSecret(app, key, environment);
+            pruned.push(`${worker}/${key}`);
+            lines.push(`* deleted \`${key}\` from \`${worker}\``);
+        }
+        catch {
+            // Fatal HERE and only here: this run exists to delete these, so a failure
+            // is the whole result rather than a footnote to a deploy. The report goes
+            // out before the throw, so the partial result survives the failure.
+            lines.push(`* **failed** to delete \`${key}\` from \`${worker}\``);
+            emit([...lines, ""]);
+            throw new DeployError(`Could not delete ${key} from ${worker}. Wrangler's own message is above.`);
+        }
+    }
+    emit([
+        ...lines,
+        "",
+        "Each deletion published a new version of the code already deployed. If one",
+        "of these was live rather than stale, the next deploy restores it from",
+        "Bitwarden — with an outage in between.",
+        "",
+    ]);
+    return { orphans: total, pruned };
+}

package/dist/deploy/preflight.d.ts

@@ -0,0 +1,53 @@
+/** Enough to answer, short enough that a hung gateway is not a stuck job. */
+export declare const TIMEOUT_MS = 15000;
+/**
+ * Transport failures get a retry; HTTP statuses do not.
+ *
+ * A status, any status, is the gateway ANSWERING, and classifying that answer
+ * is this command's whole job; retrying would just ask the same question
+ * again. A rejected fetch is the absence of an answer, and a DNS blip on a
+ * shared runner turning into a red staging deploy is the noise §3.2 exists to
+ * avoid.
+ */
+export declare const TRANSPORT_ATTEMPTS = 3;
+/** Supabase's own gateway code for a paused project. Not in any HTTP registry. */
+export declare const PAUSED_STATUS = 540;
+/**
+ * Everything that touches the outside world, injected.
+ *
+ * The 540-vs-everything-else decision must not rot, and it is unreachable in a
+ * test that has to open a socket or find a real paused project. So the fetch,
+ * the environment and the reporter are all parameters, and `preflight.test.ts`
+ * drives every branch without a socket.
+ *
+ * The two FILE writes are deliberately not injected: `$GITHUB_OUTPUT` and
+ * `$GITHUB_STEP_SUMMARY` are paths the environment already supplies, so a test
+ * points them at a temp file and asserts the real bytes. A stub there would
+ * assert the call and not the contract.
+ */
+export interface PreflightDeps {
+    env?: Record<string, string | undefined>;
+    fetch?: typeof globalThis.fetch;
+    /** Where the human-readable lines go. Defaults to `say()`, so stderr. */
+    report?: (lines: readonly string[]) => void;
+}
+export interface PreflightVerdict {
+    /**
+     * `true` for a paused project, `false` for a healthy one. Both exit 0; the
+     * workflow reads `paused` from `$GITHUB_OUTPUT` to decide whether to deploy.
+     */
+    paused: boolean;
+}
+/**
+ * Classifies the project.
+ *
+ * Returning at all means exit 0, healthy or paused. Anything else throws a
+ * `DeployError`, which `cli.ts` renders to stderr and turns into exit 1. That
+ * mapping IS the contract the deploy job gates on, so the two must not drift:
+ * a refusal that returned, or a paused project that threw, would each invert a
+ * deploy decision.
+ *
+ * @throws {DeployError} for a broken project, an unreachable one, or a
+ *   missing `PROJECT_REF` / `PUBLISHABLE_KEY`.
+ */
+export declare function runPreflight(deps?: PreflightDeps): Promise<PreflightVerdict>;

package/dist/deploy/preflight.js

@@ -0,0 +1,189 @@
+/**
+ * `pnpm devtools deploy preflight`
+ *
+ * Classifies a Supabase project as healthy, paused, or broken before a deploy
+ * spends any credential on it.
+ *
+ * ## Why this exists (security plan §3.2)
+ *
+ * Staging's Supabase project is on the free tier, so it pauses after a week
+ * without activity, and staging deploys land roughly weekly. A paused project
+ * is the expected state, not an exception. Unhandled, it does not announce
+ * itself: the deploy proceeds until the migrations step opens a Postgres
+ * connection and dies with a connection error that reads exactly like a broken
+ * migration.
+ *
+ * Supabase publishes a status code for this case: HTTP 540, "the project the
+ * request was being made against has been paused". It comes from the API
+ * gateway rather than from Postgres, so one request classifies the project
+ * before anything authenticates to it.
+ *
+ *   540        paused    skip the deploy, annotate, exit 0
+ *   200        healthy   proceed
+ *   anything   broken    fail loudly
+ *
+ * ## Skip rather than fail, and ONLY on 540
+ *
+ * A staging deploy runs after the merge to `main` has already landed, so
+ * failing it blocks nothing and only paints CI red. If that happens most weeks
+ * then red stops meaning anything, which costs more than a stale staging
+ * environment. Every other outcome stays a hard failure, because those are the
+ * ones a person has to look at.
+ *
+ * Resuming is a dashboard action on purpose: there is no documented Management
+ * API restore, and a Management API token carries full account privileges
+ * across BOTH Supabase organizations (§1.3), which is what the staging tier
+ * must not hold. So the skip writes the dashboard link and stops there.
+ *
+ * > Rejected: a keep-alive cron on the staging Worker. Supabase documents that
+ * > a few requests a day prevent pausing, but that only holds while staging is
+ * > deployed and healthy, so the first broken deploy silently starts a one-week
+ * > timer to a paused project.
+ *
+ * ⚠️ Delete this command when staging moves to a paid project. Paid projects
+ * cannot be paused, and this becomes dead code.
+ *
+ * ## ⚠️ The exit code is the interface, and it gates a deploy job
+ *
+ * Exit 0 for healthy OR paused; 1 for anything else. The workflow reads
+ * `paused` from `$GITHUB_OUTPUT` to decide whether to run the deploy, and
+ * reads the exit code to decide whether the preflight itself failed, so
+ * "paused" and "broken" must never collapse into one another. Only 540 skips.
+ *
+ * ## Everything human goes to stderr
+ *
+ * Like every command under `deploy/`, this one reports through `say()` rather
+ * than `@clack/prompts`, which writes exclusively to stdout (see
+ * `deploy/report.ts`). Second reason: it runs in GitHub Actions, which merges
+ * stdout and stderr into one log with no guaranteed ordering between them, so
+ * a verdict on one stream and its hints on the other can surface out of order.
+ *
+ * ## Interface
+ *
+ *   PROJECT_REF=… PUBLISHABLE_KEY=… pnpm devtools deploy preflight
+ *
+ * Writes `paused=true|false` to `$GITHUB_OUTPUT` and, when paused, a note to
+ * `$GITHUB_STEP_SUMMARY`. It needs no env FILE and no credential. Both
+ * variables are public (§A.4), so it runs through `cli:no-env`.
+ */
+import { appendFileSync } from "node:fs";
+import { DeployError, say, summary } from "./report.js";
+/** Enough to answer, short enough that a hung gateway is not a stuck job. */
+export const TIMEOUT_MS = 15_000;
+/**
+ * Transport failures get a retry; HTTP statuses do not.
+ *
+ * A status, any status, is the gateway ANSWERING, and classifying that answer
+ * is this command's whole job; retrying would just ask the same question
+ * again. A rejected fetch is the absence of an answer, and a DNS blip on a
+ * shared runner turning into a red staging deploy is the noise §3.2 exists to
+ * avoid.
+ */
+export const TRANSPORT_ATTEMPTS = 3;
+/** Supabase's own gateway code for a paused project. Not in any HTTP registry. */
+export const PAUSED_STATUS = 540;
+/**
+ * Classifies the project.
+ *
+ * Returning at all means exit 0, healthy or paused. Anything else throws a
+ * `DeployError`, which `cli.ts` renders to stderr and turns into exit 1. That
+ * mapping IS the contract the deploy job gates on, so the two must not drift:
+ * a refusal that returned, or a paused project that threw, would each invert a
+ * deploy decision.
+ *
+ * @throws {DeployError} for a broken project, an unreachable one, or a
+ *   missing `PROJECT_REF` / `PUBLISHABLE_KEY`.
+ */
+export async function runPreflight(deps = {}) {
+    const { env = process.env, fetch = globalThis.fetch, report = say } = deps;
+    /** A machine-readable verdict, echoed to the log so a human sees it too. */
+    const output = (text) => {
+        const path = env.GITHUB_OUTPUT;
+        if (path)
+            appendFileSync(path, `${text}\n`);
+        report([`preflight: ${text}`]);
+    };
+    const ref = env.PROJECT_REF;
+    const key = env.PUBLISHABLE_KEY;
+    if (!ref) {
+        throw new DeployError("PROJECT_REF is not set — nothing to classify.", [
+            "It is a per-environment GitHub VARIABLE (not a secret); see §A.4.",
+        ]);
+    }
+    // Unauthenticated, PostgREST answers 401 and a 401 is indistinguishable from
+    // the "broken" bucket. The publishable key is what makes 200 mean 200; it
+    // discloses nothing, which is why this check can run before any real
+    // credential is in scope.
+    if (!key) {
+        throw new DeployError("PUBLISHABLE_KEY is not set — a healthy project would look broken.", [
+            "Without it PostgREST answers 401, which this command cannot tell apart",
+            "from a genuinely broken project. It is a GitHub VARIABLE, not a secret.",
+        ]);
+    }
+    // Auth's health endpoint, NOT `/rest/v1/`. The REST root is PostgREST's
+    // OpenAPI schema document, and Supabase now answers it with 401 "Secret API
+    // key required" for every non-secret key, publishable and legacy anon alike
+    // (observed 2026-08-20; it failed the first real staging preflight). Health
+    // keeps the same verdict table: 200 only with the right publishable key,
+    // 401 for a wrong one, 540 from the gateway when paused.
+    const url = `https://${ref}.supabase.co/auth/v1/health`;
+    let response;
+    let lastTransportError;
+    for (let attempt = 1; attempt <= TRANSPORT_ATTEMPTS; attempt += 1) {
+        try {
+            response = await fetch(url, {
+                headers: { apikey: key },
+                signal: AbortSignal.timeout(TIMEOUT_MS),
+            });
+            break;
+        }
+        catch (error) {
+            lastTransportError = error;
+            report([
+                `preflight: attempt ${attempt}/${TRANSPORT_ATTEMPTS} did not reach ${ref}: ${String(error)}`,
+            ]);
+        }
+    }
+    if (!response) {
+        throw new DeployError(`could not reach ${url} — ${String(lastTransportError)}`, [
+            "This is not a verdict about the project: nothing answered at all.",
+            "Re-run the job; if it keeps happening, the DNS name or the ref is wrong.",
+        ]);
+    }
+    if (response.status === PAUSED_STATUS) {
+        output("paused=true");
+        const note = [
+            "### Staging is paused — deploy skipped",
+            "",
+            `Supabase project \`${ref}\` answered **HTTP 540**: the project has been`,
+            "paused. Free-tier projects pause after a week without activity, and",
+            "staging deploys roughly weekly, so this is the expected state rather than",
+            "a fault. Nothing was deployed and nothing is broken.",
+            "",
+            `**Resume it:** <https://supabase.com/dashboard/project/${ref}>`,
+            "",
+            "Resuming is a dashboard action on purpose: there is no documented",
+            "Management API restore, and a Management API token would carry full",
+            "account privileges across both Supabase organizations — which is exactly",
+            "what the staging tier must not hold. Re-run this workflow once the",
+            "project is up.",
+            "",
+        ];
+        summary(note, env);
+        // Echoed to the log as well as the summary tab: a paused staging deploy is
+        // a green job that did nothing, and the log is where somebody looks first.
+        report(note);
+        return { paused: true };
+    }
+    if (response.status === 200) {
+        output("paused=false");
+        report([`preflight: ${ref} is up.`]);
+        return { paused: false };
+    }
+    throw new DeployError(`${url} answered ${response.status} ${response.statusText}, which is neither ` +
+        "healthy (200) nor paused (540).", [
+        "Only 540 is skippable. Everything else is a real fault and stays red:",
+        "401 means the publishable key is wrong for this project, 404 means the",
+        "ref is, and a 5xx means Supabase is having a bad day.",
+    ]);
+}

package/dist/deploy/report.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A deploy command's own refusal, as opposed to a crash.
+ *
+ * The distinction lets `cli.ts` print a message a person can act on instead of
+ * a stack trace, and it is worth having even though both outcomes exit 1:
+ * these commands run unattended, and the log line IS the report.
+ */
+export declare class DeployError extends Error {
+    readonly detail: readonly string[];
+    constructor(message: string, detail?: readonly string[]);
+}
+/**
+ * Prints to STDERR. The only way a deploy command should say anything.
+ *
+ * See the header for why this is not `log.message`: stdout is machine-read
+ * here, and clack writes there.
+ */
+export declare function say(lines: readonly string[]): void;
+/**
+ * Appends to the job summary under Actions; a no-op anywhere else.
+ *
+ * `env` is a parameter rather than a read of `process.env` so a test can point
+ * it at a temporary file without mutating the ambient environment of whatever
+ * else the runner is executing in the same process.
+ */
+export declare function summary(lines: readonly string[], env?: NodeJS.ProcessEnv): void;

package/dist/deploy/report.js

@@ -0,0 +1,70 @@
+/**
+ * What a `devtools deploy` command may print, and where it may print it.
+ *
+ * ## ⚠️ stdout belongs to the machine
+ *
+ * Every other command in this CLI talks through `@clack/prompts`, and every
+ * one of its writers goes to **stdout**: `intro`, `outro`, `log.*`, `note`,
+ * the spinner. Verified against @clack/prompts as vendored here on 2026-08-16
+ * by running each of them with the two streams captured separately: stdout got
+ * the whole box-drawn transcript and stderr got nothing.
+ *
+ * That is fine for a contributor at a terminal and wrong for this group: a
+ * deploy command's stdout is a channel something downstream may PARSE or take
+ * whole, `::add-mask::` directives and minted credentials among the things
+ * that have lived there. So `cli.ts` prints no banner for the `deploy` group,
+ * and everything in this group reports through `say()`, which is stderr,
+ * instead of `log`/`note`. A `console.log` anywhere under this directory is a
+ * bug: the next command with a real stdout protocol would inherit a
+ * decoration it never asked for, silently, with no test catching it until
+ * that command exists.
+ *
+ * ## Failures
+ *
+ * `DeployError` carries the same two-part shape the scripts these commands
+ * grew out of printed by hand: a one-line message, then indented detail naming
+ * the thing to go and fix. `cli.ts` renders it to stderr and sets a non-zero
+ * exit code; a command that wants the failure in the job summary as well writes
+ * that itself, because which failures deserve a summary entry is a per-command
+ * judgement (`write-env`'s do; a bad flag does not).
+ */
+import { appendFileSync } from "node:fs";
+/**
+ * A deploy command's own refusal, as opposed to a crash.
+ *
+ * The distinction lets `cli.ts` print a message a person can act on instead of
+ * a stack trace, and it is worth having even though both outcomes exit 1:
+ * these commands run unattended, and the log line IS the report.
+ */
+export class DeployError extends Error {
+    detail;
+    constructor(message, detail = []) {
+        super(message);
+        this.name = "DeployError";
+        this.detail = detail;
+    }
+}
+/**
+ * Prints to STDERR. The only way a deploy command should say anything.
+ *
+ * See the header for why this is not `log.message`: stdout is machine-read
+ * here, and clack writes there.
+ */
+export function say(lines) {
+    if (lines.length === 0)
+        return;
+    process.stderr.write(`${lines.join("\n")}\n`);
+}
+/**
+ * Appends to the job summary under Actions; a no-op anywhere else.
+ *
+ * `env` is a parameter rather than a read of `process.env` so a test can point
+ * it at a temporary file without mutating the ambient environment of whatever
+ * else the runner is executing in the same process.
+ */
+export function summary(lines, env = process.env) {
+    const path = env.GITHUB_STEP_SUMMARY;
+    if (!path)
+        return;
+    appendFileSync(path, `${lines.join("\n")}\n`);
+}

package/dist/deploy/require-planner.d.ts

@@ -0,0 +1,2 @@
+import { type Connect } from "../planner/db.js";
+export declare function runRequirePlanner(env?: Record<string, string | undefined>, connect?: Connect): Promise<void>;

package/dist/deploy/require-planner.js

@@ -0,0 +1,60 @@
+/**
+ * `pnpm devtools deploy require-planner`
+ *
+ * Refuses the §3.5 stage-1 dry run when its `DB_URL` is anything more than
+ * the `migration_planner` role.
+ *
+ * The preflight credential is the one narrowed value NOTHING can verify at
+ * rest: a full-access connection string pasted into `.env.preflight` works
+ * identically. The dry run succeeds, `env push` uploads it cleanly, and
+ * `env audit` reports no drift forever, because the stored value matches the
+ * file it came from. Only a live connection shows the difference, so this
+ * guard opens one: it must authenticate as the planner, it must FAIL to read
+ * `platform.profile`, and it must succeed in reading the migrations table the
+ * dry run is about to plan against. See `planner/checks.ts` for the three
+ * checks; `planner create` runs the same ones, so a credential that passed at
+ * minting time passes here.
+ *
+ * Runs in the `main-plan` job only. `production-plan` runs the same dry run
+ * with the PRODUCTION environment's `DB_URL`, which is the full connection
+ * string by design, since apps boot from it, so this guard would (correctly)
+ * refuse there. The narrowing belongs to the preflight tier, not to the dry
+ * run.
+ *
+ * Like the rest of the group: `cli:no-env` (the job holds one credential in
+ * the step's `env:` block and composes no file), reports through `say()`
+ * (stderr), refuses by `DeployError`. One line per check on success. This
+ * runs as its own step, and three green lines are the evidence the §3.5
+ * argument leans on.
+ */
+import { checkPlanner } from "../planner/checks.js";
+import { connectDb } from "../planner/db.js";
+import { DeployError, say } from "./report.js";
+export async function runRequirePlanner(env = process.env, connect = connectDb) {
+    const url = env.DB_URL;
+    if (!url) {
+        throw new DeployError("DB_URL is not set — refusing to plan.", [
+            "This step runs with the preflight environment's DB_URL: the",
+            "migration_planner role, pushed by `env push --target preflight`.",
+            "An empty value usually means the environment secret was never",
+            "pushed, or the workflow step lost its env: block.",
+        ]);
+    }
+    const db = connect(url);
+    try {
+        const verdict = await checkPlanner(db);
+        for (const line of verdict.lines)
+            say([`require-planner: ${line}`]);
+        if (!verdict.ok) {
+            throw new DeployError(`refusing to plan: ${verdict.problem}`, [
+                "The preflight DB_URL must be the migration_planner role and no",
+                "more — this environment is reachable from `main`. Mint or repair",
+                "it with `pnpm devtools planner create` (or `planner status` to",
+                "see what is wrong), then `env push --target preflight`.",
+            ]);
+        }
+    }
+    finally {
+        await db.end();
+    }
+}

package/dist/deploy/require-token.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Refuses the deploy when `CLOUDFLARE_API_TOKEN` is absent, and says nothing
+ * when it is set.
+ *
+ * The silence is deliberate: it stands in front of a deploy inside an `&&`
+ * chain, and a guard that announces itself on every run is a guard people stop
+ * reading. The refusal is the only thing it has to say.
+ *
+ * It refuses by throwing rather than by returning a code so that `cli.ts`
+ * renders it like every other deploy failure, through `say()`, which is
+ * stderr, never `explain()`, which is clack and therefore stdout.
+ *
+ * @throws {DeployError} when `CLOUDFLARE_API_TOKEN` is absent or empty.
+ */
+export declare function runRequireToken(env?: Record<string, string | undefined>): void;