@devdogsuga/devtools 0.1.0

package/dist/cron/schema.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Zod schemas for the two cron-trigger exports an app's
+ * `cloudflare/scheduled.ts` may declare: `CRON_ROUTES` (a schedule that fetches
+ * one or more of the app's own routes) and the optional `WORKFLOW_CRONS`
+ * (audit metadata for a native Cloudflare Workflow schedule).
+ *
+ * devtools enforces both at its import boundary (see `discovery.ts`): an app
+ * that drifts from the shape fails the audit and a conformance test, rather
+ * than reading as an empty (silently unaudited) map.
+ *
+ * Invariants, each a test rather than a hope:
+ *   - Every route starts `/` and lives on the app's own origin.
+ *   - `routes` is non-empty: a key that fires nothing is a config bug.
+ *   - `label` is non-blank: the audit's English description; never empty.
+ *   - Keyed by the cron expression exactly as wrangler carries it, so
+ *     reconciliation is a set comparison, never a parse.
+ */
+import { z } from "zod";
+declare const CronEntry: z.ZodObject<{
+    routes: z.ZodArray<z.ZodString>;
+    label: z.ZodString;
+}, z.core.$strip>;
+export declare const CronRoutes: z.ZodRecord<z.ZodString, z.ZodObject<{
+    routes: z.ZodArray<z.ZodString>;
+    label: z.ZodString;
+}, z.core.$strip>>;
+export type CronRoutes = z.infer<typeof CronRoutes>;
+export type CronEntry = z.infer<typeof CronEntry>;
+/**
+ * A native workflow schedule. `binding` names the Workflows binding (e.g.
+ * `SCRAPE_WORKFLOW`); `cron list` reconciles the expression against that
+ * binding's `workflows[].schedules` in the tier's `wrangler.jsonc`. `label` is
+ * the audit's English description, same contract as routes.
+ */
+declare const WorkflowCronEntry: z.ZodObject<{
+    binding: z.ZodString;
+    label: z.ZodString;
+}, z.core.$strip>;
+export declare const WorkflowCrons: z.ZodRecord<z.ZodString, z.ZodObject<{
+    binding: z.ZodString;
+    label: z.ZodString;
+}, z.core.$strip>>;
+export type WorkflowCrons = z.infer<typeof WorkflowCrons>;
+export type WorkflowCronEntry = z.infer<typeof WorkflowCronEntry>;
+export {};

package/dist/cron/schema.js

@@ -0,0 +1,35 @@
+/**
+ * Zod schemas for the two cron-trigger exports an app's
+ * `cloudflare/scheduled.ts` may declare: `CRON_ROUTES` (a schedule that fetches
+ * one or more of the app's own routes) and the optional `WORKFLOW_CRONS`
+ * (audit metadata for a native Cloudflare Workflow schedule).
+ *
+ * devtools enforces both at its import boundary (see `discovery.ts`): an app
+ * that drifts from the shape fails the audit and a conformance test, rather
+ * than reading as an empty (silently unaudited) map.
+ *
+ * Invariants, each a test rather than a hope:
+ *   - Every route starts `/` and lives on the app's own origin.
+ *   - `routes` is non-empty: a key that fires nothing is a config bug.
+ *   - `label` is non-blank: the audit's English description; never empty.
+ *   - Keyed by the cron expression exactly as wrangler carries it, so
+ *     reconciliation is a set comparison, never a parse.
+ */
+import { z } from "zod";
+const CronRoute = z.string().startsWith("/");
+const CronEntry = z.object({
+    routes: z.array(CronRoute).min(1),
+    label: z.string().min(1),
+});
+export const CronRoutes = z.record(z.string(), CronEntry);
+/**
+ * A native workflow schedule. `binding` names the Workflows binding (e.g.
+ * `SCRAPE_WORKFLOW`); `cron list` reconciles the expression against that
+ * binding's `workflows[].schedules` in the tier's `wrangler.jsonc`. `label` is
+ * the audit's English description, same contract as routes.
+ */
+const WorkflowCronEntry = z.object({
+    binding: z.string().min(1),
+    label: z.string().min(1),
+});
+export const WorkflowCrons = z.record(z.string(), WorkflowCronEntry);

package/dist/db/config-push.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `config.toml` lives on a hosted project only — there is no local
+ * `--project-ref` to push to — so this takes the ref directly rather than a
+ * `Target`. The caller (`cli.ts`) resolves it from the tier, exactly like
+ * every other remote db operation now does, instead of letting the supabase
+ * CLI fall back to whatever project it has `--linked`.
+ */
+export declare function runConfigPush(projectRef: string): Promise<number>;

package/dist/db/config-push.js

@@ -0,0 +1,11 @@
+import { supabase } from "./run.js";
+/**
+ * `config.toml` lives on a hosted project only — there is no local
+ * `--project-ref` to push to — so this takes the ref directly rather than a
+ * `Target`. The caller (`cli.ts`) resolves it from the tier, exactly like
+ * every other remote db operation now does, instead of letting the supabase
+ * CLI fall back to whatever project it has `--linked`.
+ */
+export async function runConfigPush(projectRef) {
+    return supabase("config", "push", "--project-ref", projectRef);
+}

package/dist/db/connection.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Resolves the database a `db` command acts on — from the SESSION, never
+ * from a flag.
+ *
+ * There used to be two connection mechanisms here (`db/remote.ts`'s
+ * `--target remote` tier resolver, and `db/local-env.ts`'s "whatever this
+ * process entered"), joined by a `--target local|remote` flag that asked a
+ * question the launcher had already answered: `launch.ts` settles a session
+ * (`--tier development:local|development:remote|staging|production`, or the
+ * picker) and enters its env BEFORE any command dispatches, so
+ * `process.env.DB_URL` already names the one database this session means.
+ * This module reads that — the same `DB_URL` every app and script uses —
+ * and every mechanism-one caller now goes through it. `resolveLocalToolingEnv`
+ * remains for the two commands that hand a whole ENVIRONMENT to a child
+ * process rather than needing a connection of their own.
+ *
+ * What it adds over a raw `process.env.DB_URL` read is the two sanity
+ * guards a session can still violate:
+ *
+ *   * development meaning the LOCAL stack, but `DB_URL` pointing somewhere
+ *     that is not loopback — the stack went down after launch (the overlay
+ *     is applied at entry; see `load.ts`'s probe table) or the degraded
+ *     `db`-exempt entry ran without it. Refused with `db start`
+ *     troubleshooting rather than letting `.env`'s hosted `DB_URL` answer
+ *     for a command that asked for Docker.
+ *   * a DEPLOYED tier whose `DB_URL` points AT loopback — the signature of
+ *     inherited development values winning under `override: false` (see
+ *     `launch.ts`). Refused rather than "migrating staging" against a local
+ *     container.
+ *
+ * Reports the reason on stderr and returns `null` on every failure path —
+ * never throws for an expected failure — so a caller can stop without
+ * printing a second explanation of its own.
+ *
+ * ## `db connect` — plausibly vestigial
+ *
+ * `connectRemoteProject` (`stack.ts`) still runs `supabase link
+ * --project-ref <ref>`, the pre-session way of naming "the remote project",
+ * remembered by the supabase CLI on disk and read by nothing in this CLI:
+ * every operation here passes `--db-url`/`--project-ref` explicitly. It may
+ * still matter to someone driving the bare `supabase` CLI by hand, so
+ * removing it is a separate decision from this refactor.
+ */
+import type { DeployEnvironment } from "@devdogsuga/env";
+import type { DevDatabase } from "@devdogsuga/env/load";
+export declare function isLocalDbUrl(url: string): boolean;
+/** The hostname for messages — never the URL itself, which carries the
+ * password. */
+export declare function dbHost(url: string): string;
+/** What the session resolved to: the one database every `db` data command
+ * in this process acts on. `projectRef` is only validated where it is
+ * actually needed (`seed buckets`, `config push`). */
+export interface DbConnection {
+    tier: DeployEnvironment;
+    /** The session's development qualifier, when one was entered. */
+    devDatabase: DevDatabase | undefined;
+    dbUrl: string;
+    projectRef: string | undefined;
+}
+/** Whether this connection is the Docker stack on this machine — the one
+ * database whose erasure is routine rather than gated sternly. */
+export declare function isLocalConnection(conn: DbConnection): boolean;
+/**
+ * How gates and reports name the target. Deliberately tier-and-host only —
+ * never the DB_URL, which carries the password — and "remote development"
+ * is spelled out because `staging`/`production` are also remote: the whole
+ * reason the session vocabulary qualifies development.
+ */
+export declare function describeDbTarget(conn: DbConnection): string;
+export interface ResolveDbConnectionOptions {
+    /** Stderr prefix, e.g. "devtools db reset". */
+    label?: string;
+    /** Injectable for tests; defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Suppress the stderr reason — for callers like `db status` that treat
+     * "no resolvable database" as an answer, not a failure. */
+    quiet?: boolean;
+}
+export declare function resolveDbConnection(opts?: ResolveDbConnectionOptions): Promise<DbConnection | null>;

package/dist/db/connection.js

@@ -0,0 +1,114 @@
+import { loadEnv, loadEnvLoad } from "../repo/peers.js";
+/**
+ * Hostnames that mean "the Docker stack on this machine". The same list
+ * `docs/index-pages.ts` keeps for its delete-acknowledgment; duplicated
+ * because that module answers a different question ("may I delete rows
+ * here without --target remote?") and coupling the two would let a change
+ * for one silently reshape the other.
+ */
+const LOCAL_DB_HOSTS = [
+    "localhost",
+    "127.0.0.1",
+    "[::1]",
+    "host.docker.internal",
+];
+export function isLocalDbUrl(url) {
+    try {
+        return LOCAL_DB_HOSTS.includes(new URL(url).hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/** The hostname for messages — never the URL itself, which carries the
+ * password. */
+export function dbHost(url) {
+    try {
+        return new URL(url).hostname || "unknown host";
+    }
+    catch {
+        return "unknown host";
+    }
+}
+/** Whether this connection is the Docker stack on this machine — the one
+ * database whose erasure is routine rather than gated sternly. */
+export function isLocalConnection(conn) {
+    return conn.tier === "development" && isLocalDbUrl(conn.dbUrl);
+}
+/**
+ * How gates and reports name the target. Deliberately tier-and-host only —
+ * never the DB_URL, which carries the password — and "remote development"
+ * is spelled out because `staging`/`production` are also remote: the whole
+ * reason the session vocabulary qualifies development.
+ */
+export function describeDbTarget(conn) {
+    if (conn.tier !== "development")
+        return `the ${conn.tier} database`;
+    if (isLocalDbUrl(conn.dbUrl))
+        return "your local database";
+    return `the remote development database at ${dbHost(conn.dbUrl)}`;
+}
+export async function resolveDbConnection(opts = {}) {
+    const { DEPLOY_ENVIRONMENTS, fileFor, isDeployEnvironment } = await loadEnv();
+    const { DEV_DB_ENV, isDevDatabase } = await loadEnvLoad();
+    const env = opts.env ?? process.env;
+    const label = opts.label ?? "devtools db";
+    const report = (message) => {
+        if (!opts.quiet)
+            process.stderr.write(message);
+    };
+    const rawTier = env.DEPLOY_ENV;
+    let tier;
+    if (rawTier === undefined || rawTier === "") {
+        tier = "development";
+    }
+    else if (isDeployEnvironment(rawTier)) {
+        tier = rawTier;
+    }
+    else {
+        report(`${label}: DEPLOY_ENV="${rawTier}" is not one of ${DEPLOY_ENVIRONMENTS.join(", ")}.\n`);
+        return null;
+    }
+    let devDatabase;
+    const rawDevDb = env[DEV_DB_ENV];
+    if (tier === "development" && rawDevDb !== undefined && rawDevDb !== "") {
+        if (!isDevDatabase(rawDevDb)) {
+            report(`${label}: ${DEV_DB_ENV}="${rawDevDb}" is not one of: local, remote.\n`);
+            return null;
+        }
+        devDatabase = rawDevDb;
+    }
+    const dbUrl = env.DB_URL;
+    if (dbUrl === undefined || dbUrl === "") {
+        if (tier !== "development") {
+            report(`${label}: ${fileFor(tier)} has no DB_URL.\n`);
+        }
+        else if (devDatabase === "remote") {
+            report(`${label}: this session targets the remote development database, but .env has no DB_URL.\n`);
+        }
+        else {
+            report(`${label}: no DB_URL in this session — the local Supabase stack is ` +
+                "not running. Run `pnpm devtools db start`, or relaunch with " +
+                "`--tier development:remote` (or staging/production) to act on a " +
+                "hosted database.\n");
+        }
+        return null;
+    }
+    if (tier === "development" &&
+        devDatabase !== "remote" &&
+        !isLocalDbUrl(dbUrl)) {
+        report(`${label}: DB_URL points at ${dbHost(dbUrl)}, not the local stack — ` +
+            "it is offline (or .env.generated is stale). Run `pnpm devtools db " +
+            "start`, or relaunch with `--tier development:remote` if you mean " +
+            "that database.\n");
+        return null;
+    }
+    if (tier !== "development" && isLocalDbUrl(dbUrl)) {
+        report(`${label}: the session tier is ${tier} but DB_URL points at ` +
+            `${dbHost(dbUrl)} — a local address, the signature of inherited ` +
+            "development values. Relaunch with `pnpm devtools --tier " +
+            `${tier}\` from a clean shell.\n`);
+        return null;
+    }
+    return { tier, devDatabase, dbUrl, projectRef: env.PROJECT_REF };
+}

package/dist/db/exec.d.ts

@@ -0,0 +1 @@
+export declare function runDbExec(args: string[]): Promise<number>;

package/dist/db/exec.js

@@ -0,0 +1,11 @@
+/**
+ * `db exec -- <args…>` — the escape hatch.
+ *
+ * Everything after `--` passes straight to the Supabase CLI, unmodified. Same
+ * stance as `bw` and `cf exec`: the wrapped CLI owns its own targeting and its
+ * own flags, so this declares no subcommands and does no parsing of its own.
+ */
+import { supabase } from "./run.js";
+export async function runDbExec(args) {
+    return supabase(...args);
+}

package/dist/db/generate-migration.d.ts

@@ -0,0 +1 @@
+export declare function runGenerateMigration(appSlug?: string): Promise<number>;

package/dist/db/generate-migration.js

@@ -0,0 +1,67 @@
+/**
+ * `db migration generate [--app <slug>]` — draft a migration from an app's
+ * Drizzle schema drift.
+ *
+ * Absorbs schedule-builder's `db:generate` package script (`with-env
+ * drizzle-kit generate --config drizzle-migrations.config.ts`), the same way
+ * `db introspect` absorbed platform's `db:pull`. It touches no database: it
+ * diffs the schema files against drizzle-kit's own snapshot and writes SQL
+ * under the app's `drizzle-generated/`, a draft to be carried by hand into a
+ * real migration under `supabase/migrations/` — never something that runs on
+ * its own. `DB_URL` is still required because drizzle-kit's Postgres
+ * introspection needs a live connection to compare against, matching what
+ * `with-env` supplied before — sourced via `resolveLocalToolingEnv`, the
+ * tier this process already entered rather than a raw `.env` parse. See
+ * `db/local-env.ts`'s header.
+ */
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { select } from "@clack/prompts";
+import { findRepoRoot } from "../repo/root.js";
+import { unwrap } from "../ui.js";
+import { resolveLocalToolingEnv } from "./local-env.js";
+// ── Per-app config ────────────────────────────────────────────────────────────
+/** Apps whose Drizzle schema drafts migrations via `drizzle-kit generate`. */
+const APP_CONFIGS = {
+    "schedule-builder": "drizzle-migrations.config.ts",
+};
+async function pickApp() {
+    const names = Object.keys(APP_CONFIGS);
+    if (names.length === 1)
+        return names[0];
+    return unwrap(await select({
+        message: "Whose schema drift should I draft a migration from?",
+        options: names.map((value) => ({ value, label: value })),
+    }));
+}
+function runDrizzleGenerate(appDir, configFile, env) {
+    return new Promise((resolve) => {
+        const child = spawn("pnpm", ["exec", "drizzle-kit", "generate", "--config", configFile], { stdio: "inherit", cwd: appDir, env });
+        child.on("exit", (code) => resolve(code ?? 1));
+    });
+}
+// ── Entry ─────────────────────────────────────────────────────────────────────
+export async function runGenerateMigration(appSlug) {
+    const app = appSlug ?? (await pickApp());
+    const configFile = APP_CONFIGS[app];
+    if (!configFile) {
+        const valid = Object.keys(APP_CONFIGS).join(", ");
+        process.stderr.write(`devtools db migration generate: unknown app "${app}". Expected: ${valid}.\n`);
+        return 1;
+    }
+    const appDir = join(findRepoRoot(), "apps", app);
+    // Matching `db introspect`'s approach: `pnpm devtools` enters a tier into
+    // `process.env` before dispatch (`launch.ts`), but drizzle-kit here runs as
+    // its own child process in the app's directory, so that entered
+    // environment needs to be injected explicitly rather than inherited
+    // implicitly.
+    const env = await resolveLocalToolingEnv();
+    if (!env["DB_URL"]) {
+        process.stderr.write("devtools db migration generate: DB_URL is not set. Run " +
+            "`pnpm devtools db start` first (for local — its connection string " +
+            "lives in .env.generated once the stack is up), or set DB_URL in " +
+            "the deploy tier's env file this process entered.\n");
+        return 1;
+    }
+    return runDrizzleGenerate(appDir, configFile, env);
+}

package/dist/db/generate-types.d.ts

@@ -0,0 +1 @@
+export declare function runGenerateTypes(dbUrl: string): Promise<number>;

package/dist/db/generate-types.js

@@ -0,0 +1,4 @@
+import { generateTypes } from "./run.js";
+export async function runGenerateTypes(dbUrl) {
+    return generateTypes(dbUrl);
+}

package/dist/db/introspect.d.ts

@@ -0,0 +1 @@
+export declare function runIntrospect(app?: string): Promise<number>;

package/dist/db/introspect.js

@@ -0,0 +1,113 @@
+/**
+ * `db introspect --app <slug>` — pull an app's live schema into its generated
+ * Drizzle files, then apply post-pull fixups.
+ *
+ * Replicates the old `db:pull` package script chain:
+ *   1. drizzle-kit pull --config drizzle-introspection.config.ts  (auth/storage schemas)
+ *   2. drizzle-kit pull --config drizzle.config.ts                (platform schema)
+ *   3. Post-pull fixups on the generated schema.ts:
+ *      a. Delete relations.ts (we maintain hand-written relations)
+ *      b. Re-inject the cross-schema FK-target import (auth.users etc.)
+ *      c. Append InPlatform-suffix aliases so existing imports stay stable
+ *
+ * `DB_URL` comes from `resolveLocalToolingEnv` — the tier this process
+ * already entered (`launch.ts`, before `cli.ts` ever dispatched this
+ * command), `.env.generated` overlay included — and is injected into the
+ * subprocess environment. See `db/local-env.ts`'s header for why this is
+ * NOT a raw `.env` parse.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { findRepoRoot } from "../repo/root.js";
+import { resolveLocalToolingEnv } from "./local-env.js";
+const APP_CONFIGS = {
+    platform: {
+        configs: ["drizzle-introspection.config.ts", "drizzle.config.ts"],
+        schemaFile: "src/server/db/schema/generated/schema.ts",
+        schemaSuffix: "InPlatform",
+        crossSchemaImport: 'import { usersInAuth as users, oauthClientsInAuth as oauthClients } from "~/supabase/drizzle/schema"',
+    },
+};
+// ── drizzle-kit pull ──────────────────────────────────────────────────────────
+function runDrizzlePull(appDir, configFile, env) {
+    return new Promise((resolve) => {
+        const child = spawn("pnpm", ["exec", "drizzle-kit", "pull", "--config", configFile], { stdio: "inherit", cwd: appDir, env });
+        child.on("exit", (code) => resolve(code ?? 1));
+    });
+}
+// ── Post-pull fixups ──────────────────────────────────────────────────────────
+function applyPostPullFixups(appDir, cfg) {
+    const schemaPath = join(appDir, cfg.schemaFile);
+    const relationsPath = join(appDir, cfg.schemaFile.replace("schema.ts", "relations.ts"));
+    // 1. Delete relations.ts
+    if (existsSync(relationsPath))
+        rmSync(relationsPath);
+    if (!existsSync(schemaPath))
+        return;
+    let src = readFileSync(schemaPath, "utf8");
+    // 2. Re-inject cross-schema FK-target import (idempotent)
+    const IMPORT_MARKER = "// Cross-schema FK targets";
+    if (cfg.crossSchemaImport && !src.includes(IMPORT_MARKER)) {
+        const lines = src.split("\n");
+        let insertAt = 0;
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i] ?? "";
+            if (line.startsWith("import ") && line.includes("drizzle-orm")) {
+                insertAt = i + 1;
+            }
+            else if (line.trim() !== "" && !line.startsWith("import ")) {
+                break;
+            }
+        }
+        lines.splice(insertAt, 0, `${IMPORT_MARKER} — re-injected by devtools db introspect after each drizzle-kit pull`, cfg.crossSchemaImport);
+        src = lines.join("\n");
+    }
+    // 3. Append base-name aliases for every `<name><suffix>` export (idempotent)
+    const ALIAS_MARKER = "// Schema-suffix aliases";
+    if (cfg.schemaSuffix && !src.includes(ALIAS_MARKER)) {
+        const names = new Set();
+        const re = new RegExp(`export const (\\w+)${cfg.schemaSuffix}\\b`, "g");
+        for (const m of src.matchAll(re))
+            if (m[1])
+                names.add(m[1]);
+        if (names.size > 0) {
+            const aliases = [...names]
+                .sort()
+                .map((n) => `export { ${n}${cfg.schemaSuffix} as ${n} };`)
+                .join("\n");
+            src = `${src.trimEnd()}\n\n${ALIAS_MARKER} — appended by devtools db introspect\n${aliases}\n`;
+        }
+    }
+    writeFileSync(schemaPath, src);
+    process.stdout.write(`[introspect] patched ${cfg.schemaFile}\n`);
+}
+// ── Entry ─────────────────────────────────────────────────────────────────────
+export async function runIntrospect(app) {
+    if (!app) {
+        process.stderr.write("devtools db introspect: --app <slug> is required.\n");
+        return 1;
+    }
+    const cfg = APP_CONFIGS[app];
+    if (!cfg) {
+        const valid = Object.keys(APP_CONFIGS).join(", ");
+        process.stderr.write(`devtools db introspect: unknown app "${app}". Expected: ${valid}.\n`);
+        return 1;
+    }
+    const appDir = join(findRepoRoot(), "apps", app);
+    const env = await resolveLocalToolingEnv();
+    if (!env["DB_URL"]) {
+        process.stderr.write("devtools db introspect: DB_URL is not set. Run " +
+            "`pnpm devtools db start` first (for local — its connection string " +
+            "lives in .env.generated once the stack is up), or set DB_URL in " +
+            "the deploy tier's env file this process entered.\n");
+        return 1;
+    }
+    for (const configFile of cfg.configs) {
+        const code = await runDrizzlePull(appDir, configFile, env);
+        if (code !== 0)
+            return code;
+    }
+    applyPostPullFixups(appDir, cfg);
+    return 0;
+}

package/dist/db/local-env.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The environment `db introspect` and `db migration generate` hand to the
+ * `drizzle-kit` child process they spawn.
+ *
+ * ## How this relates to `db/connection.ts`
+ *
+ * `db/connection.ts` resolves the session's one database CONNECTION (its
+ * `DB_URL`, with sanity guards) for commands that open one themselves. This
+ * is the other need: a whole ENVIRONMENT to hand a child process. Both read
+ * the same source — whatever THIS PROCESS already entered — `launch.ts`
+ * runs before
+ * `cli.ts`'s command dispatch even imports, and enters a tier (development,
+ * by default) into `process.env` via `@devdogsuga/env/session`'s
+ * `enterEnvironment`, applying `selectEnvFiles`'s overlay-plus-liveness-probe
+ * logic (`.env.generated`, the running local stack's connection block,
+ * ahead of `.env` — see `load.ts`'s probe table) along the way.
+ *
+ * These two commands used to bypass all of that: each parsed `.env` directly
+ * with raw `dotenv`, and merged it OVER `process.env`
+ * (`{...process.env, ...tierEnv}`). Two bugs followed from that shortcut:
+ *
+ *   a. `.env.generated` — where the running local stack's `DB_URL` actually
+ *      lives — was never read, so with the stack up these commands reported
+ *      "DB_URL is not set in .env. Run `supabase start` first" (wrong
+ *      command AND wrong file) or silently connected to a stale/hosted URL,
+ *      while every other command in this CLI, going through `selectEnvFiles`,
+ *      worked fine.
+ *   b. The precedence was inverted: a raw `.env` parse merged OVER
+ *      `process.env` clobbers whatever tier this process actually entered —
+ *      backwards from the documented expectation (now `db/connection.ts`'s)
+ *      that a command reads the tier the process is already running
+ *      under rather than reimposing development on top of it.
+ *
+ * `resolveLocalToolingEnv` fixes both by returning `process.env` itself
+ * (fresh values, `.env.generated` included, whatever tier was entered)
+ * instead of re-deriving anything. The only case it still loads a tier
+ * itself is a caller that reaches these commands WITHOUT going through
+ * `launch.ts` first — `process.env.DEPLOY_ENV` unset is the tell, since
+ * `enterEnvironment` always sets it, even for `development` — and even then
+ * it falls back to `loadEnvironment("development")`, never a raw dotenv
+ * parse, so the overlay-plus-probe logic still applies.
+ */
+import type { LoadedEnvironment } from "@devdogsuga/env/load";
+export interface ResolveLocalToolingEnvOptions {
+    /** Injectable for tests; defaults to `process.env`. */
+    processEnv?: NodeJS.ProcessEnv;
+    /** Injectable for tests; defaults to the real `loadEnvironment`. */
+    loadEnvironment?: (deployEnv?: string, options?: {
+        override?: boolean;
+    }) => Promise<LoadedEnvironment>;
+}
+/**
+ * Returns the environment a local-tooling child process (`drizzle-kit`,
+ * spawned by `db introspect` / `db migration generate`) should inherit.
+ *
+ * Normal path (the process went through `launch.ts`, as `pnpm devtools`
+ * always does): returns `process.env` unchanged — it already carries
+ * whatever tier was entered, `.env.generated` overlay included.
+ *
+ * Fallback path (no tier was ever entered — a direct import, e.g. from a
+ * test, or a future caller that skips `launch.ts`): loads development
+ * through the shared `loadEnvironment`, which applies the same overlay and
+ * liveness probe `selectEnvFiles` always has, then returns that snapshot.
+ */
+export declare function resolveLocalToolingEnv(opts?: ResolveLocalToolingEnvOptions): Promise<NodeJS.ProcessEnv>;

package/dist/db/local-env.js

@@ -0,0 +1,23 @@
+import { loadEnvLoad } from "../repo/peers.js";
+/**
+ * Returns the environment a local-tooling child process (`drizzle-kit`,
+ * spawned by `db introspect` / `db migration generate`) should inherit.
+ *
+ * Normal path (the process went through `launch.ts`, as `pnpm devtools`
+ * always does): returns `process.env` unchanged — it already carries
+ * whatever tier was entered, `.env.generated` overlay included.
+ *
+ * Fallback path (no tier was ever entered — a direct import, e.g. from a
+ * test, or a future caller that skips `launch.ts`): loads development
+ * through the shared `loadEnvironment`, which applies the same overlay and
+ * liveness probe `selectEnvFiles` always has, then returns that snapshot.
+ */
+export async function resolveLocalToolingEnv(opts = {}) {
+    const processEnv = opts.processEnv ?? process.env;
+    if (processEnv.DEPLOY_ENV !== undefined && processEnv.DEPLOY_ENV !== "") {
+        return processEnv;
+    }
+    const load = opts.loadEnvironment ?? (await loadEnvLoad()).loadEnvironment;
+    const loaded = await load("development");
+    return loaded.env;
+}

package/dist/db/new-migration.d.ts

@@ -0,0 +1 @@
+export declare function runNewMigration(name: string | undefined): Promise<number>;

package/dist/db/new-migration.js

@@ -0,0 +1,8 @@
+import { supabase } from "./run.js";
+export async function runNewMigration(name) {
+    if (!name) {
+        process.stderr.write("devtools new-migration: a migration name is required.\n");
+        return 1;
+    }
+    return supabase("migration", "new", name);
+}