@devdogsuga/devtools 0.1.0

package/dist/db/run.d.ts

@@ -0,0 +1,70 @@
+export declare function typesFile(): string;
+/** Spawn a pnpm command with inherited stdio; resolves to the exit code. Pass
+ * `env` to run the child against a loaded tier rather than process.env. */
+export declare function run(args: string[], env?: NodeJS.ProcessEnv): Promise<number>;
+export interface RunWithStderrResult {
+    code: number;
+    stderr: string;
+}
+/** Spawn a pnpm command while echoing and retaining stderr for diagnostics.
+ * Pass `env` to run the child against a loaded tier rather than process.env. */
+export declare function runWithStderr(args: string[], env?: NodeJS.ProcessEnv): Promise<RunWithStderrResult>;
+/** Spawn a pnpm command, capture stdout, throw on non-zero exit. */
+export declare function capture(args: string[]): Promise<string>;
+/** `pnpm exec supabase …` with inherited stdio. */
+export declare const supabase: (...args: string[]) => Promise<number>;
+/** `pnpm exec supabase …` with captured stdout. */
+export declare const supabaseCapture: (...args: string[]) => Promise<string>;
+/** Build the supabase package (compiles database.types.ts into dist/). */
+export declare const buildSupabase: () => Promise<number>;
+/**
+ * Generate and write Database types from the session's database.
+ *
+ * Delegates to `@devdogsuga/db/typegen`'s `generateDatabaseTypes`, which runs
+ * `pnpm exec supabase gen types --db-url <dbUrl>` (always `--db-url` — the
+ * session's own connection string, never the supabase CLI's
+ * `--local`/`--linked` modes, whose defaults can disagree with what this
+ * process entered; see `db/connection.ts`'s header) and formats the result
+ * with `pnpm exec prettier --write`, both run against `findRepoRoot()` so the
+ * workspace-pinned CLI versions are what actually run.
+ */
+export declare function generateTypes(dbUrl: string): Promise<number>;
+/**
+ * `supabase db push` over `dbUrl`, inherited stdio, resolving to the exit code.
+ *
+ * The one spelling of the migration push, shared by the contributor `db
+ * migrate` path (`stack.ts`'s `pushMigrations`) and CI's `deploy migrate`.
+ * `--yes` is the unattended apply CI wants; the contributor path omits it so a
+ * human still confirms. Neither variant regenerates types — that is
+ * `pushMigrations`' own second step, layered on top only where a checkout is
+ * meant to be rewritten. A CI apply must NOT write back into the repo, which is
+ * exactly why the bare push is factored out here rather than reused whole.
+ */
+export declare function dbPush(dbUrl: string, opts?: {
+    yes?: boolean;
+}): Promise<number>;
+/**
+ * `supabase db push --dry-run` over `dbUrl`, returning the plan text (stdout
+ * and stderr combined, as the workflow's old `2>&1` did).
+ *
+ * Throws on a non-zero exit — which for a dry run means the CONNECTION failed,
+ * not that the plan came back empty. That throw is the invariant `deploy plan`
+ * leans on, and the thing the old shell needed `set -o pipefail` to preserve: a
+ * dead connection must fail the step rather than read as "no migrations to
+ * apply". The child's own output is surfaced in the thrown message, because for
+ * a dry run that output is precisely the reason the operator needs.
+ */
+export declare function dbPushDryRun(dbUrl: string): Promise<string>;
+/**
+ * `seed buckets` takes no `--db-url` (verified against the supabase 2.115.0
+ * CLI) — it drives the Storage API, not Postgres — so it is the one data
+ * command still keyed on local-vs-hosted rather than on the session's URL.
+ */
+export type BucketsConnection = {
+    kind: "local";
+} | {
+    kind: "remote";
+    projectRef: string | undefined;
+};
+/** Seed storage buckets on the local stack or a resolved tier's project. */
+export declare function seedBuckets(conn: BucketsConnection): Promise<number>;

package/dist/db/run.js

@@ -0,0 +1,158 @@
+/**
+ * Shared helpers for running supabase CLI and pnpm commands from the repo root.
+ *
+ * The supabase CLI is a workspace devDependency (not a global install), so
+ * every invocation goes through `pnpm exec supabase`. The cwd is always
+ * findRepoRoot(), where `supabase/config.toml` lives.
+ */
+import { execFile, spawn as nodeSpawn } from "node:child_process";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { findRepoRoot } from "../repo/root.js";
+import { loadDbTypegen } from "../repo/peers.js";
+const runFile = promisify(execFile);
+export function typesFile() {
+    return join(findRepoRoot(), "packages", "supabase", "src", "database.types.ts");
+}
+/** Spawn a pnpm command with inherited stdio; resolves to the exit code. Pass
+ * `env` to run the child against a loaded tier rather than process.env. */
+export function run(args, env) {
+    return new Promise((resolve) => {
+        const child = nodeSpawn("pnpm", args, {
+            stdio: "inherit",
+            cwd: findRepoRoot(),
+            ...(env ? { env } : {}),
+        });
+        child.on("error", (error) => {
+            process.stderr.write(`${error.message}\n`);
+            resolve(1);
+        });
+        child.on("exit", (code) => resolve(code ?? 1));
+    });
+}
+/** Spawn a pnpm command while echoing and retaining stderr for diagnostics.
+ * Pass `env` to run the child against a loaded tier rather than process.env. */
+export function runWithStderr(args, env) {
+    return new Promise((resolve) => {
+        const child = nodeSpawn("pnpm", args, {
+            stdio: ["inherit", "inherit", "pipe"],
+            cwd: findRepoRoot(),
+            ...(env ? { env } : {}),
+        });
+        let stderr = "";
+        child.stderr.setEncoding("utf8");
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+            process.stderr.write(chunk);
+        });
+        child.on("error", (error) => {
+            const message = `${error.message}\n`;
+            stderr += message;
+            process.stderr.write(message);
+            resolve({ code: 1, stderr });
+        });
+        child.on("exit", (code) => resolve({ code: code ?? 1, stderr }));
+    });
+}
+/** Spawn a pnpm command, capture stdout, throw on non-zero exit. */
+export async function capture(args) {
+    const { stdout } = await runFile("pnpm", args, {
+        cwd: findRepoRoot(),
+        encoding: "utf8",
+    });
+    return stdout;
+}
+/** `pnpm exec supabase …` with inherited stdio. */
+export const supabase = (...args) => run(["exec", "supabase", ...args]);
+/** `pnpm exec supabase …` with captured stdout. */
+export const supabaseCapture = (...args) => capture(["exec", "supabase", ...args]);
+/** Build the supabase package (compiles database.types.ts into dist/). */
+export const buildSupabase = () => run(["--filter", "@devdogsuga/supabase", "build"]);
+/**
+ * Generate and write Database types from the session's database.
+ *
+ * Delegates to `@devdogsuga/db/typegen`'s `generateDatabaseTypes`, which runs
+ * `pnpm exec supabase gen types --db-url <dbUrl>` (always `--db-url` — the
+ * session's own connection string, never the supabase CLI's
+ * `--local`/`--linked` modes, whose defaults can disagree with what this
+ * process entered; see `db/connection.ts`'s header) and formats the result
+ * with `pnpm exec prettier --write`, both run against `findRepoRoot()` so the
+ * workspace-pinned CLI versions are what actually run.
+ */
+export async function generateTypes(dbUrl) {
+    try {
+        const { generateDatabaseTypes } = await loadDbTypegen();
+        await generateDatabaseTypes({
+            dbUrl,
+            outFile: typesFile(),
+            cwd: findRepoRoot(),
+        });
+    }
+    catch {
+        return 1;
+    }
+    return buildSupabase();
+}
+/**
+ * `supabase db push` over `dbUrl`, inherited stdio, resolving to the exit code.
+ *
+ * The one spelling of the migration push, shared by the contributor `db
+ * migrate` path (`stack.ts`'s `pushMigrations`) and CI's `deploy migrate`.
+ * `--yes` is the unattended apply CI wants; the contributor path omits it so a
+ * human still confirms. Neither variant regenerates types — that is
+ * `pushMigrations`' own second step, layered on top only where a checkout is
+ * meant to be rewritten. A CI apply must NOT write back into the repo, which is
+ * exactly why the bare push is factored out here rather than reused whole.
+ */
+export function dbPush(dbUrl, opts = {}) {
+    const args = ["db", "push", "--db-url", dbUrl];
+    if (opts.yes)
+        args.push("--yes");
+    return supabase(...args);
+}
+/**
+ * `supabase db push --dry-run` over `dbUrl`, returning the plan text (stdout
+ * and stderr combined, as the workflow's old `2>&1` did).
+ *
+ * Throws on a non-zero exit — which for a dry run means the CONNECTION failed,
+ * not that the plan came back empty. That throw is the invariant `deploy plan`
+ * leans on, and the thing the old shell needed `set -o pipefail` to preserve: a
+ * dead connection must fail the step rather than read as "no migrations to
+ * apply". The child's own output is surfaced in the thrown message, because for
+ * a dry run that output is precisely the reason the operator needs.
+ */
+export async function dbPushDryRun(dbUrl) {
+    try {
+        const { stdout, stderr } = await runFile("pnpm", ["exec", "supabase", "db", "push", "--db-url", dbUrl, "--dry-run"], { cwd: findRepoRoot(), encoding: "utf8", maxBuffer: 32 * 1024 * 1024 });
+        return `${stdout}${stderr}`;
+    }
+    catch (err) {
+        const e = err;
+        const detail = `${e.stdout ?? ""}${e.stderr ?? ""}`.trim();
+        throw new Error(detail
+            ? `supabase db push --dry-run failed:\n${detail}`
+            : (e.message ?? "supabase db push --dry-run failed"));
+    }
+}
+/** Seed storage buckets on the local stack or a resolved tier's project. */
+export async function seedBuckets(conn) {
+    if (conn.kind === "local") {
+        return supabase("seed", "buckets", "--local", "--yes");
+    }
+    // Surfaced here, before the supabase CLI ever runs, rather than left for it
+    // to reject: an empty `--project-ref ""` is exactly the kind of ambiguous
+    // failure this whole module exists to avoid.
+    if (!conn.projectRef) {
+        process.stderr.write("devtools db: seed buckets against a hosted project needs PROJECT_REF in the session's env file.\n");
+        return 1;
+    }
+    // `seed buckets` (unlike `config push`) rejects a bare `--project-ref` as
+    // ambiguous with `--local` and demands `--linked` alongside it. That does
+    // NOT mean it needs an ambient `supabase link` state on disk — verified
+    // empirically in an unlinked checkout, `--project-ref` names the target
+    // directly and `--linked` is just the mode selector for "use that ref",
+    // not "use whatever `supabase link` last remembered". So this stays
+    // consistent with `db/connection.ts`'s rule of never depending on
+    // `--linked`'s persisted state.
+    return supabase("seed", "buckets", "--project-ref", conn.projectRef, "--linked");
+}

package/dist/db/seed-buckets.d.ts

@@ -0,0 +1,2 @@
+import { type BucketsConnection } from "./run.js";
+export declare function runSeedBuckets(conn: BucketsConnection): Promise<number>;

package/dist/db/seed-buckets.js

@@ -0,0 +1,4 @@
+import { seedBuckets } from "./run.js";
+export async function runSeedBuckets(conn) {
+    return seedBuckets(conn);
+}

package/dist/db/seed-production.d.ts

@@ -0,0 +1,8 @@
+/** Injectable so a test can fake the connection without a real Postgres. */
+export interface SeedProductionDb {
+    unsafe(query: string): Promise<unknown>;
+    end(): Promise<void>;
+}
+export declare function runSeedProduction(dbUrl: string, deps?: {
+    connect: (url: string) => SeedProductionDb;
+}): Promise<number>;

package/dist/db/seed-production.js

@@ -0,0 +1,73 @@
+/**
+ * `db seed production` — apply `supabase/seed/production/*.sql` to a target.
+ *
+ * The DevDogsUGA repo splits its seeds into `supabase/seed/production/`
+ * (the role catalogue and the officer board — content every tier needs)
+ * and `supabase/seed/development/` (password-login personas and a worked
+ * moderation report — local-dev-only, never meant to reach a hosted
+ * target). `db reset` runs both, but only ever against a LOCAL stack,
+ * because a reset erases everything else on whatever it points at.
+ * `production/` is what a staging or production target needs applied on
+ * its own, without erasing anything: `db reset --no-seed` (or an
+ * already-migrated database) plus this command, instead of hand-picking
+ * files with `db query --file`.
+ *
+ * That is a deliberate departure from `runSeedRoles` (`seed-roles.ts`),
+ * which pipes its one file through `supabase db query --file --db-url`.
+ * `03_officers.sql` is many separate `insert into` statements in one file,
+ * and the supabase CLI's `db query` runs its `--file` argument as a single
+ * PREPARED statement — confirmed against the local stack, where it fails
+ * every multi-statement seed file with "cannot insert multiple commands
+ * into a prepared statement". `01_roles.sql` only ever worked through that
+ * path because it happens to be one big `with … insert … select`
+ * statement. So this connects directly with `postgres` (`prepare: false`,
+ * the same setting `planner/db.ts` uses and for the same reason: the
+ * simple query protocol, not the extended one, is what allows more than
+ * one statement per round trip) and runs each file's raw text, rather than
+ * shelling out per file.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import postgres from "postgres";
+import { findRepoRoot } from "../repo/root.js";
+const SEED_DIR = "production";
+// Lazy, like seed-roles.ts's `seedFiles()` — computed inside
+// `runSeedProduction`, not at module load, so importing this file never
+// calls `findRepoRoot()` (or touches the filesystem) on its own.
+function seedFiles() {
+    const dir = join(findRepoRoot(), "supabase", "seed", SEED_DIR);
+    return readdirSync(dir)
+        .filter((name) => name.endsWith(".sql"))
+        .sort()
+        .map((name) => join(dir, name));
+}
+/** Real connection: `prepare: false` so multi-statement files run over the
+ * simple query protocol instead of gotrue's `db query --file` prepared-
+ * statement path, which refuses them. `max: 1` — this is a short-lived,
+ * sequential CLI invocation, never a pool. */
+function connect(dbUrl) {
+    const sql = postgres(dbUrl, { max: 1, prepare: false, connect_timeout: 15 });
+    return {
+        unsafe: (query) => sql.unsafe(query),
+        end: () => sql.end({ timeout: 5 }),
+    };
+}
+export async function runSeedProduction(dbUrl, deps = { connect }) {
+    const db = deps.connect(dbUrl);
+    try {
+        for (const file of seedFiles()) {
+            try {
+                await db.unsafe(readFileSync(file, "utf8"));
+            }
+            catch (err) {
+                process.stderr.write(`devtools db seed production: ${file} failed: ` +
+                    `${err instanceof Error ? err.message : String(err)}\n`);
+                return 1;
+            }
+        }
+        return 0;
+    }
+    finally {
+        await db.end();
+    }
+}

package/dist/db/seed-roles.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Always `--db-url` — the session's own connection string, never the
+ * supabase CLI's `--local`/`--linked` modes. `db query`, which this runs
+ * through, supports it the same way `db reset`/`db push` do. See
+ * `db/connection.ts`'s header.
+ */
+export declare function runSeedRoles(dbUrl: string): Promise<number>;

package/dist/db/seed-roles.js

@@ -0,0 +1,31 @@
+/**
+ * `db seed roles` — reconcile platform's role catalogue against a target.
+ *
+ * Runs 01_roles.sql, the complete built-in and organizational role catalogue,
+ * against the chosen target. It never assigns Root: bootstrapping that
+ * break-glass role requires the explicit, service-key-backed grant-root command.
+ */
+import { join } from "node:path";
+import { findRepoRoot } from "../repo/root.js";
+import { supabase } from "./run.js";
+// Lazy — computed inside `runSeedRoles`, not at module load, so importing
+// this file never calls `findRepoRoot()` on its own (it used to, as a
+// top-level `const`, which broke `--help`/`setup` outside a repo — see
+// `workers.ts`'s header for the general pattern this follows).
+function seedFiles() {
+    return [join(findRepoRoot(), "supabase", "seed", "production", "01_roles.sql")];
+}
+/**
+ * Always `--db-url` — the session's own connection string, never the
+ * supabase CLI's `--local`/`--linked` modes. `db query`, which this runs
+ * through, supports it the same way `db reset`/`db push` do. See
+ * `db/connection.ts`'s header.
+ */
+export async function runSeedRoles(dbUrl) {
+    for (const file of seedFiles()) {
+        const code = await supabase("db", "query", "--file", file, "--db-url", dbUrl);
+        if (code !== 0)
+            return code;
+    }
+    return 0;
+}

package/dist/db/session-refresh.d.ts

@@ -0,0 +1,43 @@
+/**
+ * BUG 2 fix: keeping this process's environment in sync with the local
+ * stack's lifecycle.
+ *
+ * `launch.ts` enters a deploy tier into `process.env` exactly ONCE, before
+ * `cli.ts` ever dispatches a command. `db start` (`startLocalStack`, in
+ * `../stack.ts`) then writes a NEW `.env.generated` — the running stack's
+ * fresh connection block — and `db stop` (`stopLocalStack`) deletes it. Left
+ * alone, `process.env` keeps whatever it held at launch for the rest of a
+ * wizard session: `db start` followed by `db introspect` in the SAME
+ * session would still hand `drizzle-kit` the stale (or absent)
+ * `.env.generated` values `resolveLocalToolingEnv` reads straight off
+ * `process.env` (see `local-env.ts`) — the exact staleness BUG 1 fixed
+ * `db introspect` from reading off disk, reappearing one layer up.
+ *
+ * `refreshSessionEnv` closes that gap by re-running the SAME
+ * `enterEnvironment("development", …)` `launch.ts` used at startup —
+ * overlay-plus-liveness-probe included — after a stack command that could
+ * have changed `.env.generated` succeeds.
+ *
+ * ⚠️ Guarded to development only. `DEPLOY_ENV` naming a deployed tier means
+ * this session targets staging or production (see `../db/connection.ts`);
+ * blindly re-entering development here would silently overwrite that tier's
+ * connection with local values mid-session, for a stack command
+ * (`start`/`stop`/`restart`) that only ever touches the LOCAL Docker stack
+ * in the first place.
+ */
+import type { EnteredEnvironment } from "@devdogsuga/env/session";
+export interface RefreshSessionEnvOptions {
+    /** Injectable for tests; defaults to `process.env.DEPLOY_ENV`. */
+    deployEnv?: string;
+    /** Injectable for tests; defaults to the real `enterEnvironment`. */
+    enterEnvironment?: (tier: "development", opts: {
+        override: boolean;
+    }) => Promise<EnteredEnvironment>;
+}
+/**
+ * Re-enters development — refreshing `process.env` from `.env.generated`'s
+ * latest state — when (and only when) this process is already running under
+ * development. Returns the one-line note callers report on success, or an
+ * empty array when the guard held and nothing needed refreshing.
+ */
+export declare function refreshSessionEnv(opts?: RefreshSessionEnvOptions): Promise<string[]>;

package/dist/db/session-refresh.js

@@ -0,0 +1,40 @@
+import { loadEnvLoad, loadEnvSession } from "../repo/peers.js";
+/**
+ * Re-enters development — refreshing `process.env` from `.env.generated`'s
+ * latest state — when (and only when) this process is already running under
+ * development. Returns the one-line note callers report on success, or an
+ * empty array when the guard held and nothing needed refreshing.
+ */
+export async function refreshSessionEnv(opts = {}) {
+    const deployEnv = opts.deployEnv ?? process.env.DEPLOY_ENV;
+    if (deployEnv !== undefined &&
+        deployEnv !== "" &&
+        deployEnv !== "development") {
+        return [];
+    }
+    const envLoad = await loadEnvLoad();
+    const enter = opts.enterEnvironment ?? (await loadEnvSession()).enterEnvironment;
+    try {
+        await enter("development", { override: true });
+    }
+    catch (err) {
+        if (!(err instanceof envLoad.LocalStackOfflineError))
+            throw err;
+        // A `development:local` session whose stack just went down — `db stop`
+        // did exactly what it was asked, so this refresh must not turn that into
+        // a failure. Re-enter unqualified (probe decides: `.env` alone, with its
+        // stale-overlay warning) but LEAVE `DEV_DB` in place: the session still
+        // MEANS the local database, and `db/connection.ts`'s guard is what turns
+        // a later data command into "start the stack", not `.env`'s own DB_URL.
+        const devDb = process.env[envLoad.DEV_DB_ENV];
+        delete process.env[envLoad.DEV_DB_ENV];
+        try {
+            await enter("development", { override: true });
+        }
+        finally {
+            if (devDb !== undefined)
+                process.env[envLoad.DEV_DB_ENV] = devDb;
+        }
+    }
+    return [`refreshed ${envLoad.GENERATED_FILE}`];
+}

package/dist/deploy/migrations.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Dry-run the migrations and write the plan to the job summary.
+ *
+ * The plan text is captured, not streamed, so `dbPushDryRun`'s throw on a
+ * non-zero exit is what fails the step when the connection is dead — and the
+ * job summary then carries no plan, which is the honest outcome. `label` lets
+ * the caller distinguish the two stages (`main`'s early plan vs the one taken
+ * seconds before the apply); it is the only thing that varies between them.
+ */
+export declare function runDeployPlan(label?: string, env?: NodeJS.ProcessEnv, plan?: (dbUrl: string) => Promise<string>): Promise<void>;
+/**
+ * Apply the migrations to DB_URL.
+ *
+ * `dbPush(url, { yes: true })` — the bare push, WITHOUT the type regeneration
+ * the contributor path layers on, so a production apply never writes back into
+ * the checkout. A non-zero exit becomes a DeployError so the job fails with a
+ * line a person can read; the supabase CLI's own output (inherited stdio) says
+ * why above it.
+ */
+export declare function runDeployMigrate(env?: NodeJS.ProcessEnv, push?: (dbUrl: string) => Promise<number>): Promise<void>;

package/dist/deploy/migrations.js

@@ -0,0 +1,68 @@
+/**
+ * `pnpm devtools-ci deploy plan` and `deploy migrate`.
+ *
+ * The two halves of a production schema change, behind the same tested seam as
+ * the rest of the deploy group. They replace the raw `supabase db push` shell
+ * that used to live in four places in `deploy.yaml` — `--dry-run` piped to
+ * `$GITHUB_STEP_SUMMARY` for the plan, `--yes` for the apply. The load-bearing
+ * `set -o pipefail` there (so a failed connection did not read as a clean plan)
+ * was a shell idiom no test could reach; here it is `dbPushDryRun`'s
+ * throw-on-non-zero, which a test drives.
+ *
+ * Both read `DB_URL` from the step's own `env:` (the plan under the
+ * migration_planner role that `require-planner` guards, the apply under the
+ * deploy-tier credential), compose no env file, and run through the bare `ci`
+ * package script — the one-credential convention shared with `require-planner`
+ * and `require-token`. Dependencies are injected (env, the push runner) rather
+ * than reached for, so the tests exercise the argv, the refusals, the summary
+ * framing, and the failed-connection invariant without a database.
+ */
+import { dbPush, dbPushDryRun } from "../db/run.js";
+import { DeployError, say, summary } from "./report.js";
+const MISSING_DB_URL = [
+    "This step runs with the environment's DB_URL. An empty value usually",
+    "means the environment secret was never pushed, or the workflow step",
+    "lost its env: block.",
+];
+/**
+ * Dry-run the migrations and write the plan to the job summary.
+ *
+ * The plan text is captured, not streamed, so `dbPushDryRun`'s throw on a
+ * non-zero exit is what fails the step when the connection is dead — and the
+ * job summary then carries no plan, which is the honest outcome. `label` lets
+ * the caller distinguish the two stages (`main`'s early plan vs the one taken
+ * seconds before the apply); it is the only thing that varies between them.
+ */
+export async function runDeployPlan(label = "Migration plan", env = process.env, plan = dbPushDryRun) {
+    const url = env.DB_URL;
+    if (!url) {
+        throw new DeployError("DB_URL is not set — refusing to plan.", MISSING_DB_URL);
+    }
+    const text = await plan(url);
+    // Echoed to stderr as well as the summary, so the plan is visible in the live
+    // job log too — stdout belongs to the machine for this group (see report.ts).
+    say([text]);
+    summary([`### ${label}`, "", "```", text, "```"], env);
+}
+/**
+ * Apply the migrations to DB_URL.
+ *
+ * `dbPush(url, { yes: true })` — the bare push, WITHOUT the type regeneration
+ * the contributor path layers on, so a production apply never writes back into
+ * the checkout. A non-zero exit becomes a DeployError so the job fails with a
+ * line a person can read; the supabase CLI's own output (inherited stdio) says
+ * why above it.
+ */
+export async function runDeployMigrate(env = process.env, push = (url) => dbPush(url, { yes: true })) {
+    const url = env.DB_URL;
+    if (!url) {
+        throw new DeployError("DB_URL is not set — refusing to migrate.", MISSING_DB_URL);
+    }
+    const code = await push(url);
+    if (code !== 0) {
+        throw new DeployError(`\`supabase db push\` failed (exit ${code}).`, [
+            "The migration was not applied. The supabase CLI output above says why.",
+        ]);
+    }
+    say(["deploy migrate: migrations applied."]);
+}

package/dist/deploy/orphans.d.ts

@@ -0,0 +1,20 @@
+import { listWorkerSecrets } from "../env/cloudflare.js";
+export interface OrphansOptions {
+    /** `--prune`: delete what it found. Nothing else in here can delete. */
+    prune: boolean;
+    /** Defaults to the ambient environment; a parameter so tests need not mutate it. */
+    env?: NodeJS.ProcessEnv;
+    /** Project root; the CLI passes the real one. A parameter for the tests. */
+    root?: string;
+    /** Injectable so the tests need neither wrangler nor a Cloudflare token. */
+    listSecrets?: typeof listWorkerSecrets;
+    /** Injectable for the same reason. The tests assert it is NOT called without `--prune`. */
+    deleteSecret?: (app: string, key: string, environment: string) => void;
+}
+export interface OrphansResult {
+    /** How many names nothing declares, across every readable Worker. */
+    orphans: number;
+    /** `worker/key` for each deletion that happened. Empty unless `--prune`. */
+    pruned: string[];
+}
+export declare function runDeployOrphans(options: OrphansOptions): Promise<OrphansResult>;