@devdogsuga/devtools 0.1.11 → 0.1.13

package/dist/db/generated-env.js

@@ -0,0 +1,113 @@
+/**
+ * Regenerating `.env.generated` from a Supabase stack that is ALREADY
+ * running — started by `db start` in THIS checkout, sure, but just as
+ * often by another workspace (a different clone or worktree of the
+ * DevDogsUGA repo) that shares this repo's `project_id`. `supabase status`
+ * finds containers by project id, not by which checkout ran `db start`, so
+ * a stack a sibling workspace brought up answers for THIS checkout too —
+ * except `.env.generated` (the connection block `startLocalStack`,
+ * `../stack.ts`, writes) only ever lands in the workspace that actually ran
+ * it. Left alone, this checkout sees port 54321 listening with the file
+ * missing, and `@devdogsuga/env/load`'s `selectEnvFiles` either warns (an
+ * unqualified session) or throws `LocalStackOfflineError` (an explicit
+ * `development:local` one) — both of which used to mean the contributor
+ * ran `supabase status -o env > .env.generated` by hand.
+ *
+ * `ensureGeneratedEnvFile` does that automatically, before a session's env
+ * files ever load: `enterSessionEnvironment` (`../env-entry.ts`) calls it on
+ * every command dispatch, and `db status` (`../stack.ts`) calls it to
+ * report the file's state accurately instead of trusting a stale absence.
+ * Both are read-only from THIS checkout's point of view — nothing here
+ * starts, stops, or resets anything; it only reads a port, a file, and
+ * (best-effort) the stack's own connection block.
+ *
+ * The other failure this covers: `supabase status -o env` itself fails
+ * because what is listening on 54321 belongs to a DIFFERENT Supabase
+ * project — a stack this repo's own `project_id` rename left orphaned, or
+ * an unrelated project entirely. That is reported (`"foreign"`) rather than
+ * silently falling through to the existing offline handling, which would
+ * otherwise just repeat "nothing is listening" advice for a port that very
+ * much has something listening on it.
+ */
+import { existsSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { supabaseCapture } from "./run.js";
+import { findRepoRoot } from "../repo/root.js";
+import { foreignStackMessage, foreignStackProjectId, listContainerNames, STACK_API_PORT, readProjectId, } from "../repo/supabase-project.js";
+/** The file this module writes and checks — see `@devdogsuga/env/load`'s
+ *  `GENERATED_FILE`, duplicated as a literal rather than imported so this
+ *  module never has to load the `@devdogsuga/env` peer just for one
+ *  constant. Keep in sync if that constant's value ever changes. */
+const GENERATED_FILE = ".env.generated";
+/**
+ * Regenerates `.env.generated` from a running local stack when THIS
+ * checkout's own copy is missing.
+ *
+ * A no-op (`"skipped"`) unless every one of these holds: `tier` is
+ * `"development"`, `devDatabase` is not `"remote"` (an explicit `"local"`
+ * or the probe-decides `undefined` both qualify), the file is genuinely
+ * absent, and something answers the local stack's port. That last check
+ * also covers "the file is missing because the stack is genuinely down" —
+ * nothing here runs `supabase status` against a stack that is not there;
+ * the existing `LocalStackOfflineError`/warning handling covers that case
+ * exactly as before.
+ *
+ * `"foreign"` and `"unreachable"` both mean `supabase status -o env`
+ * itself failed — the port answered, but the CLI could not produce a
+ * connection block. `"foreign"` is the case a running Docker container's
+ * name resolves to: another project's stack holds the port.
+ * `"unreachable"` is everything else (an unreadable `config.toml`, an
+ * unreadable `docker ps`, a container name that matches nobody) — the
+ * caller falls through to its existing offline handling either way, since
+ * `.env.generated` is still missing on disk.
+ */
+export async function ensureGeneratedEnvFile(tier, devDatabase, deps) {
+    if (tier !== "development" || devDatabase === "remote") {
+        return { outcome: "skipped" };
+    }
+    if (deps.exists(GENERATED_FILE))
+        return { outcome: "skipped" };
+    if (!(await deps.probeLocalStack()))
+        return { outcome: "skipped" };
+    try {
+        const env = await deps.captureStatus();
+        await deps.write(join(deps.repoRoot, GENERATED_FILE), env);
+        return {
+            outcome: "wrote",
+            line: "devtools: wrote .env.generated from the running local stack",
+        };
+    }
+    catch {
+        const names = deps.listContainerNames();
+        const foreign = names === null ? null : foreignStackProjectId(names, deps.projectId());
+        if (foreign !== null) {
+            return {
+                outcome: "foreign",
+                projectId: foreign,
+                line: `devtools: ${foreignStackMessage(foreign)}`,
+            };
+        }
+        return { outcome: "unreachable" };
+    }
+}
+/**
+ * The production wiring for `EnsureGeneratedEnvDeps`, shared by
+ * `../env-entry.ts` (via `realEnvEntryDeps`) and `../stack.ts`'s `db
+ * status`. `probeLocalStack` is passed in rather than resolved here because
+ * both callers already hold the loaded `@devdogsuga/env/load` peer their
+ * own dispatch needs anyway — resolving it again here would mean two
+ * different copies of the same optional peer in play.
+ */
+export function realEnsureGeneratedEnvDeps(probeLocalStack) {
+    const repoRoot = findRepoRoot();
+    return {
+        probeLocalStack,
+        exists: (file) => existsSync(join(repoRoot, file)),
+        captureStatus: () => supabaseCapture("status", "-o", "env"),
+        write: (path, contents) => writeFile(path, contents),
+        listContainerNames: () => listContainerNames(STACK_API_PORT),
+        projectId: () => readProjectId(repoRoot),
+        repoRoot,
+    };
+}

package/dist/db/seed-production.js

@@ -5,12 +5,18 @@
  * (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`.
+ * target). `db reset` used to run both, but only ever against a LOCAL
+ * stack, back when `detectLocalInstance()` was the only way this CLI found
+ * a database at all. The session system changed that: `db reset` now runs
+ * against any tier, including staging and production, so a reset there
+ * explicitly passes `--no-seed` to the Supabase CLI and calls this function
+ * itself afterward (see `stack.ts`'s `reset()`) — the config-derived
+ * `[db.seed]` list is no longer trusted to keep development's seeds off a
+ * hosted target on its own. `production/` is also what a staging or
+ * production target needs applied WITHOUT a reset — an already-migrated
+ * database that only needs this content refreshed — which is this command's
+ * other, still-current use: run it directly, 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`.

package/dist/docs/index-pages.js

@@ -30,7 +30,7 @@
  */
 import { confirm, log, spinner } from "@clack/prompts";
 import postgres from "postgres";
-import { bail, errorMessage, explain, unwrap } from "../ui.js";
+import { bail, errorMessage, explain, explainError, unwrap } from "../ui.js";
 import { loadDocs } from "../repo/source.js";
 export function connectDocsDb(url) {
     // `max: 1` is load-bearing, not tuning: the write below is BEGIN, two
@@ -173,7 +173,7 @@ export async function runDocsIndex(options = {}) {
     }
     catch (err) {
         s.stop("The index was not written");
-        explain("Writing the docs index failed.", errorMessage(err), [
+        explainError("Writing the docs index failed.", err, [
             "`pnpm devtools db migrate` applies any migration the table is missing.",
         ]);
         process.exitCode = 1;

package/dist/emails/commands.js

@@ -4,7 +4,7 @@ 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 { explain, explainError, unwrap, UsageError } from "../ui.js";
 import { EMAIL_FIXTURES } from "./fixtures.js";
 import { loadEmail } from "../repo/source.js";
 export const EMAIL_FORMATS = ["html", "text"];
@@ -48,7 +48,7 @@ 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.");
+        throw new UsageError("No terminal to choose templates. Name one, or pass * for all.");
     }
     const names = unwrap(await multiselect({
         message: "Which emails?",
@@ -121,7 +121,7 @@ export async function runEmails(argv) {
         log.info(`${written.length} preview file${written.length === 1 ? "" : "s"} written.`);
     }
     catch (err) {
-        explain("Could not render those emails.", errorMessage(err), [
+        explainError("Could not render those emails.", err, [
             "Build the email package with `pnpm --filter @devdogsuga/email build`.",
             "Then try `pnpm devtools emails '*' --out ~/emails`.",
         ]);

package/dist/env/discovery.js

@@ -37,10 +37,11 @@
  * its `declare()`/`define()` calls landing in the SAME `@devdogsuga/env`
  * registry instance the target repo's manifests populate (module identity —
  * see `repo/peers.ts`'s header and the devtools-dlx prototype's
- * FINDINGS.md experiment 3): both resolve the `@devdogsuga/env` bare
- * specifier through pnpm's single physical store location for that one
- * installed version, not through devtools' own bundled copy (it ships
- * none — `@devdogsuga/env` is only ever an optional peer).
+ * FINDINGS.md experiment 3). Its bare `@devdogsuga/env` import is
+ * redirected to the copy `loadEnv()` resolved through the repo, because
+ * from a `pnpm dlx` copy the specifier does not resolve at all: devtools
+ * ships no copy of its own (`@devdogsuga/env` is only ever an optional
+ * peer), and nothing installs one next to it. See `repo/peer-redirect.ts`.
  *
  * Most workspace packages declare nothing, so "no env.ts found" means
  * not-a-manifest rather than an error.
@@ -58,8 +59,9 @@
  */
 import { existsSync, readdirSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { getEnvSync, loadEnv } from "../repo/peers.js";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { redirectPeer } from "../repo/peer-redirect.js";
+import { getEnvSync, loadEnv, repoPeerUrl } from "../repo/peers.js";
 import { findRepoRoot } from "../repo/root.js";
 import { importRepoTs } from "../repo/tsx-loader.js";
 /**
@@ -105,6 +107,17 @@ async function importManifests() {
     // see `repo/peers.ts`'s header), and `assertRegistryLoaded()` /
     // `gh/environments.ts`'s getters read it back synchronously afterward.
     await loadEnv();
+    // devtools' own manifest imports `@devdogsuga/env` by bare specifier, which
+    // does not resolve at all from a `pnpm dlx` copy. Point it at the copy
+    // `loadEnv()` just resolved through the repo. See `repo/peer-redirect.ts`.
+    const envUrl = repoPeerUrl("@devdogsuga/env");
+    if (envUrl) {
+        redirectPeer({
+            parentURL: pathToFileURL(ownManifestPath()).href,
+            specifier: "@devdogsuga/env",
+            url: envUrl,
+        });
+    }
     // The Next apps' manifests run `createEnv` at import time. Without this flag
     // they would validate the AMBIENT environment, a devtools process rather than
     // an app build, and throw on whatever is missing. The manifests already

package/dist/env-entry.d.ts

@@ -0,0 +1,49 @@
+import type { DeployEnvironment } from "@devdogsuga/env";
+import type { DevDatabase } from "@devdogsuga/env/load";
+import type * as EnvLoadModule from "@devdogsuga/env/load";
+import type * as EnvSessionModule from "@devdogsuga/env/session";
+import { type EnsureGeneratedEnvResult } from "./db/generated-env.js";
+export interface EnvEntryDeps {
+    envLoad: typeof EnvLoadModule;
+    envSession: typeof EnvSessionModule;
+    /**
+     * Regenerates `.env.generated` from a running local stack when this
+     * checkout's own copy is missing, right before the session's env files
+     * load — see this module's header and `db/generated-env.ts`. Required
+     * (not defaulted here) so every caller is explicit about it: `launch.ts`
+     * uses `realEnvEntryDeps` for the real wiring, tests inject a stub that
+     * never touches a real filesystem, Docker daemon, or the Supabase CLI.
+     */
+    ensureGeneratedEnv: (tier: DeployEnvironment, devDatabase: DevDatabase | undefined) => Promise<EnsureGeneratedEnvResult>;
+}
+/**
+ * The production wiring for `EnvEntryDeps`, shared by both call sites in
+ * `launch.ts`.
+ */
+export declare function realEnvEntryDeps(envLoad: typeof EnvLoadModule, envSession: typeof EnvSessionModule): EnvEntryDeps;
+/**
+ * Enters `tier` (and `devDatabase`'s overlay) for the current process,
+ * handling `LocalStackOfflineError` (the TTY offer to start the local stack,
+ * the `db`-exemption degraded-entry fallback) and `MissingEnvFileError` (the
+ * clean-clone tolerance for `development`, fatal otherwise) exactly as
+ * `launch.ts` always has. `dispatchCommand` is called exactly once, in every
+ * non-fatal branch — including immediately, in place of any further entry
+ * work, when a declined-then-accepted stack start already ran it — so its
+ * return value is always this function's own return value.
+ */
+export declare function enterSessionEnvironment<T>(tier: DeployEnvironment, devDatabase: DevDatabase | undefined, commandArgv: readonly string[], deps: EnvEntryDeps, dispatchCommand: () => Promise<T>): Promise<T>;
+/**
+ * What `runMenu` calls, right before dispatching the chosen command, in
+ * place of entering the environment itself — `commandArgv` is the chosen
+ * leaf's argv, `dispatchCommand` is `runMenu`'s own injected dispatcher for
+ * it. See this module's header for why a module-level slot rather than a
+ * `runMenu` parameter.
+ */
+export type MenuEnvHook = (commandArgv: readonly string[], dispatchCommand: () => Promise<string | null>) => Promise<string | null>;
+/** Set by `launch.ts` for a menu invocation; `undefined` for a typed command
+ *  (which entered already) and for any test that drives `runMenu` directly
+ *  without going through `launch.ts` at all. */
+export declare function setMenuEnvHook(hook: MenuEnvHook | undefined): void;
+/** Read by `runMenu`, then cleared — see this module's header on why a
+ *  nested launcher must not inherit a stale hook. */
+export declare function takeMenuEnvHook(): MenuEnvHook | undefined;

package/dist/env-entry.js

@@ -0,0 +1,204 @@
+/**
+ * Entering a resolved deploy tier's environment — the part of `launch.ts`
+ * that actually loads `.env.<tier>` (and its `DEV_DB` overlay) onto
+ * `process.env`, with the two recoverable failures `enterEnvironment` can
+ * throw handled the same way everywhere it is called from.
+ *
+ * ## Why this is its own module
+ *
+ * A typed command line enters its tier at launch, before `cli.ts` is even
+ * imported — see `launch.ts`'s header. A menu invocation cannot: the whole
+ * point of the wizard is to show a contributor what is possible before they
+ * have chosen anything, and loading env files (and possibly offering to
+ * start the local stack) before that first question is answered means
+ * whatever changed in another terminal while they were deciding — the stack
+ * coming up, `.env.generated` being rewritten — is missed. So a menu
+ * invocation defers this exact block until `menu.ts`'s `runMenu` is about to
+ * dispatch the ONE command the reader chose, right before it runs.
+ *
+ * `enterSessionEnvironment` is the block both callers share, generic over
+ * what "dispatch the command" means to each: `launch.ts` imports `cli.ts`
+ * fresh and calls its `main()`, `runMenu` already holds the dispatcher
+ * `cli.ts` injected into it. `commandArgv` is the argv the caller is about to
+ * dispatch — used for the two `LocalStackOfflineError` exemptions (a `db`
+ * lifecycle command, and an empty argv) exactly as `launch.ts` used `rest`
+ * for them before this was extracted.
+ *
+ * ## The hook `runMenu` calls
+ *
+ * `setMenuEnvHook`/`takeMenuEnvHook` are a module-level slot shared by
+ * `launch.ts` and `menu.ts`: `cli.ts` calls `runMenu` with a fixed signature
+ * that has no room for a per-invocation callback. `launch.ts` sets the hook
+ * for a menu invocation before handing off to `cli.ts`; `runMenu` takes it
+ * (reading clears it) right before its own dispatch, so a nested launcher
+ * never inherits a stale one.
+ *
+ * ## Regenerating `.env.generated` before entry
+ *
+ * Before either caller's `enterEnvironment` call, this also gives a running
+ * local stack a chance to fix its own absence: `deps.ensureGeneratedEnv`
+ * (`db/generated-env.ts`'s `ensureGeneratedEnvFile`, wired by
+ * `realEnvEntryDeps`) writes `.env.generated` from `supabase status -o env`
+ * when the port is listening but the file is missing — the common shape of
+ * a local stack another workspace started, sharing this repo's
+ * `project_id` — so the entry below usually just succeeds instead of
+ * throwing `LocalStackOfflineError` or warning about a file nobody wrote.
+ * A `"foreign"` result (the stack on the port belongs to a DIFFERENT
+ * project) prints its own hint and then falls through to the unchanged
+ * error handling below, since the file is still missing either way.
+ */
+import { confirm } from "@clack/prompts";
+import { ensureGeneratedEnvFile, realEnsureGeneratedEnvDeps, } from "./db/generated-env.js";
+import { unwrap } from "./ui.js";
+/**
+ * The production wiring for `EnvEntryDeps`, shared by both call sites in
+ * `launch.ts`.
+ */
+export function realEnvEntryDeps(envLoad, envSession) {
+    return {
+        envLoad,
+        envSession,
+        ensureGeneratedEnv: (tier, devDatabase) => ensureGeneratedEnvFile(tier, devDatabase, realEnsureGeneratedEnvDeps(envLoad.probeLocalStack)),
+    };
+}
+/**
+ * Enters `tier` (and `devDatabase`'s overlay) for the current process,
+ * handling `LocalStackOfflineError` (the TTY offer to start the local stack,
+ * the `db`-exemption degraded-entry fallback) and `MissingEnvFileError` (the
+ * clean-clone tolerance for `development`, fatal otherwise) exactly as
+ * `launch.ts` always has. `dispatchCommand` is called exactly once, in every
+ * non-fatal branch — including immediately, in place of any further entry
+ * work, when a declined-then-accepted stack start already ran it — so its
+ * return value is always this function's own return value.
+ */
+export async function enterSessionEnvironment(tier, devDatabase, commandArgv, deps, dispatchCommand) {
+    const { envLoad, envSession } = deps;
+    const generated = await deps.ensureGeneratedEnv(tier, devDatabase);
+    if (generated.outcome === "wrote" || generated.outcome === "foreign") {
+        process.stderr.write(`${generated.line}\n`);
+    }
+    // Mandatory, not chattiness: which database a command is about to touch
+    // must never be a guess. Names the QUALIFIED session (`development:local`)
+    // when one was resolved. See `session.ts`'s and `load.ts`'s own headers.
+    const reportEntered = (files, label) => {
+        process.stderr.write(`devtools: loaded ${files.length > 0 ? files.join(", ") : "no env files"} (${label})\n`);
+    };
+    const sessionLabel = devDatabase === undefined ? tier : `${tier}:${devDatabase}`;
+    try {
+        // `override: false` — see `launch.ts`'s former header comment on this
+        // same call, reproduced here since this IS that call now.
+        const entered = await envSession.enterEnvironment(tier, {
+            override: false,
+            devDatabase,
+        });
+        for (const warning of entered.warnings) {
+            process.stderr.write(`devtools: ${warning}\n`);
+        }
+        reportEntered(entered.files, sessionLabel);
+    }
+    catch (err) {
+        if (err instanceof envLoad.LocalStackOfflineError) {
+            // The session explicitly means the local database and the stack is not
+            // reachable.
+            process.stderr.write(`devtools: ${err.message}\n`);
+            // Offer to bring the stack up right here and then carry on with the
+            // command about to dispatch. Only on a TTY, and not when the command is
+            // ITSELF a stack lifecycle command — `db start`/`stop`/`restart` do
+            // this on their own, and `db stop` against an already-down stack must
+            // not be interrupted by an offer to start it. An empty `commandArgv`
+            // (nothing chosen yet) is likewise left alone.
+            const lifecycle = commandArgv[0] === "db" &&
+                (commandArgv[1] === "start" ||
+                    commandArgv[1] === "stop" ||
+                    commandArgv[1] === "restart");
+            if (process.stdin.isTTY === true &&
+                commandArgv.length !== 0 &&
+                !lifecycle) {
+                const start = unwrap(await confirm({
+                    message: "Start the local Supabase stack now?",
+                }));
+                if (start) {
+                    // Keep the session's local qualifier set so the env refresh that
+                    // `runStackCommand("start")` performs on success re-applies the
+                    // overlay under it, and the command dispatched next resolves the
+                    // freshly-started local database.
+                    if (devDatabase !== undefined)
+                        process.env.DEV_DB = devDatabase;
+                    const { runStackCommand } = await import("./stack.js");
+                    const { code, lines } = await runStackCommand("start", null);
+                    for (const line of lines) {
+                        process.stderr.write(`devtools: ${line}\n`);
+                    }
+                    if (code === 0) {
+                        return await dispatchCommand();
+                    }
+                    process.stderr.write("devtools: the stack did not start — see the Supabase CLI output " +
+                        "above.\n");
+                    process.exit(1);
+                }
+            }
+            // Declined, or nobody to ask. `db` (whose `start` is the fix, and whose
+            // data commands re-check the connection themselves) and an empty argv
+            // (the road to `db start` — the bare menu, when nothing has deferred
+            // this far, or the menu resumed on `db` itself) may continue in a
+            // degraded, unqualified entry; anything else stops here, with the
+            // error's own troubleshooting, instead of failing later against
+            // whatever `.env` happens to name.
+            if (commandArgv.length !== 0 && commandArgv[0] !== "db") {
+                process.exit(1);
+            }
+            process.stderr.write("devtools: continuing without the overlay so `db start` can fix this.\n");
+            const inherited = process.env.DEV_DB;
+            delete process.env.DEV_DB;
+            const entered = await envSession.enterEnvironment(tier, {
+                override: false,
+            });
+            if (devDatabase !== undefined) {
+                // Children spawned AFTER `db start` succeeds should still inherit
+                // the session's answer; the refresh that follows a successful start
+                // re-applies the overlay under this same variable.
+                process.env.DEV_DB = devDatabase;
+            }
+            else if (inherited !== undefined) {
+                process.env.DEV_DB = inherited;
+            }
+            for (const warning of entered.warnings) {
+                process.stderr.write(`devtools: ${warning}\n`);
+            }
+            reportEntered(entered.files, tier);
+            return await dispatchCommand();
+        }
+        if (!(err instanceof envLoad.MissingEnvFileError))
+            throw err;
+        if (tier === "development") {
+            // The clean-clone path: a fresh checkout has no `.env` at all, and
+            // `pnpm devtools setup` is how one gets created — `MissingEnvFileError`
+            // names it. Reporting and continuing here, rather than refusing, is
+            // what lets `setup` itself run through this same entry point. See
+            // `load.ts`'s `MissingEnvFileError` for the message this prints.
+            process.stderr.write(`devtools: ${err.message}\n`);
+        }
+        else {
+            // An EXPLICITLY selected staging/production tier with no env file is
+            // not a first run — it is a real problem, and `env pull` is the fix
+            // `MissingEnvFileError`'s own message already names. Fatal.
+            process.stderr.write(`devtools: ${err.message}\n`);
+            process.exit(1);
+        }
+    }
+    return await dispatchCommand();
+}
+let menuEnvHook;
+/** Set by `launch.ts` for a menu invocation; `undefined` for a typed command
+ *  (which entered already) and for any test that drives `runMenu` directly
+ *  without going through `launch.ts` at all. */
+export function setMenuEnvHook(hook) {
+    menuEnvHook = hook;
+}
+/** Read by `runMenu`, then cleared — see this module's header on why a
+ *  nested launcher must not inherit a stale hook. */
+export function takeMenuEnvHook() {
+    const hook = menuEnvHook;
+    menuEnvHook = undefined;
+    return hook;
+}

package/dist/environment-doctor.d.ts

@@ -27,6 +27,15 @@ export declare function checkRepoUnderMntC(repoRoot: string): DoctorCheck;
 /** Windows only. `RemoteSigned` (or looser) is what lets fnm's PowerShell
  * hook and pnpm's shims actually run. */
 export declare function checkPowerShellExecutionPolicy(policy: string | null): DoctorCheck;
+/**
+ * The checkout's development env the way every other command loads it:
+ * `.env.generated` (the local stack's connection block, written by `db
+ * start`) first and winning, then `.env`. Reading `.env` alone reported a
+ * working local-Docker checkout as missing PUBLISHABLE_KEY, and took the
+ * blank hosted template's `https://$PROJECT_REF.supabase.co` for a real
+ * hosted project that "did not respond".
+ */
+export declare function readCheckoutEnv(repoRoot: string): Record<string, string | undefined>;
 export declare function checkEnvKeysPresent(env: Record<string, string | undefined>, keys: string[]): DoctorCheck;
 export { validateSessionPoolerUrl };
 export interface RunDoctorOptions {

package/dist/environment-doctor.js

@@ -139,6 +139,22 @@ export function checkPowerShellExecutionPolicy(policy) {
         faqId: restricted ? "powershell-execution-policy" : undefined,
     };
 }
+/**
+ * The checkout's development env the way every other command loads it:
+ * `.env.generated` (the local stack's connection block, written by `db
+ * start`) first and winning, then `.env`. Reading `.env` alone reported a
+ * working local-Docker checkout as missing PUBLISHABLE_KEY, and took the
+ * blank hosted template's `https://$PROJECT_REF.supabase.co` for a real
+ * hosted project that "did not respond".
+ */
+export function readCheckoutEnv(repoRoot) {
+    const read = (name) => {
+        const path = join(repoRoot, name);
+        return existsSync(path) ? parseDotenv(readFileSync(path, "utf8")) : {};
+    };
+    const generated = Object.fromEntries(Object.entries(read(".env.generated")).filter(([, value]) => value !== ""));
+    return { ...read(".env"), ...generated };
+}
 export function checkEnvKeysPresent(env, keys) {
     const missing = keys.filter((k) => !env[k]);
     return {
@@ -268,7 +284,7 @@ export async function runEnvironmentDoctor(opts) {
             summary: dockerUp ? "Docker is running" : "Docker daemon is not answering",
             fix: dockerUp
                 ? undefined
-                : "Start Docker Desktop or OrbStack (macOS: set DOCKER_HOST=unix://$HOME/.orbstack/run/docker.sock for OrbStack). Never Colima.",
+                : "Start Docker Desktop, or Docker Engine in WSL2. Never Colima.",
             faqId: dockerUp ? undefined : "docker-not-running",
         });
     }
@@ -302,10 +318,7 @@ export async function runEnvironmentDoctor(opts) {
     }
     let env = {};
     if (repoRoot) {
-        const envPath = join(repoRoot, ".env");
-        if (existsSync(envPath)) {
-            env = parseDotenv(readFileSync(envPath, "utf8"));
-        }
+        env = readCheckoutEnv(repoRoot);
         checks.push(checkEnvKeysPresent(env, ["API_URL", "PUBLISHABLE_KEY"]));
     }
     // ── Hosted checks — only when .env looks like a hosted project ───────────

package/dist/environment.d.ts

@@ -42,8 +42,8 @@ export declare const UNKNOWN_ENVIRONMENT: Environment;
  * takes the better part of a second: it shells out through `pnpm exec` and
  * then talks to every service in the stack. `docker ps` answers the only
  * question the menu has (is it up?) in a fraction of that, and the commands
- * that need real credentials still go through `detectLocalInstance`, which
- * asks the authority at the moment it matters.
+ * that need real credentials go through `resolveInstance` (`instance.ts`),
+ * which reads the session's already-entered env at the moment it matters.
  */
 export declare function probeEnvironment(execute?: (file: string, args: string[]) => string | null): Environment;
 /**

package/dist/environment.js

@@ -20,9 +20,10 @@
  * for.
  */
 import { execFileSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { findRepoRoot } from "./repo/root.js";
+import { containerPrefix, readProjectId } from "./repo/supabase-project.js";
 /**
  * The repo root, which is where `supabase/config.toml` and `.env` live.
  *
@@ -69,30 +70,6 @@ function run(file, args) {
         return null;
     }
 }
-/**
- * The container name prefix the Supabase CLI gives this project's stack.
- *
- * Read with a regex rather than a TOML parser: it is one line, the shape has
- * been stable across every CLI version this repo has seen, and a parser on a
- * menu's startup path to read one string is a cost that stays invisible until
- * it is why the tool feels slow.
- *
- * Falling back to the bare `supabase_db_` prefix means a machine whose
- * `config.toml` cannot be read still detects *a* stack. That over-match is
- * deliberate: over-matching offers `stop` to someone running a different
- * Supabase project, which they can decline, while under-matching tells someone
- * their running stack is down.
- */
-function containerPrefix() {
-    try {
-        const path = join(findRepoRoot(), "supabase", "config.toml");
-        const id = /^\s*project_id\s*=\s*"([^"]+)"/m.exec(readFileSync(path, "utf8"));
-        return id?.[1] ? `supabase_db_${id[1]}` : "supabase_db_";
-    }
-    catch {
-        return "supabase_db_";
-    }
-}
 /**
  * Reads the machine.
  *
@@ -105,8 +82,8 @@ function containerPrefix() {
  * takes the better part of a second: it shells out through `pnpm exec` and
  * then talks to every service in the stack. `docker ps` answers the only
  * question the menu has (is it up?) in a fraction of that, and the commands
- * that need real credentials still go through `detectLocalInstance`, which
- * asks the authority at the moment it matters.
+ * that need real credentials go through `resolveInstance` (`instance.ts`),
+ * which reads the session's already-entered env at the moment it matters.
  */
 export function probeEnvironment(execute = run) {
     const envFile = existsSync(join(findRepoRoot(), ".env")) ? "yes" : "no";
@@ -121,7 +98,7 @@ export function probeEnvironment(execute = run) {
     const names = execute("docker", ["ps", "--format", "{{.Names}}"]);
     if (names === null)
         return { docker, stack: "unknown", envFile };
-    const prefix = containerPrefix();
+    const prefix = containerPrefix(readProjectId(findRepoRoot()));
     const running = names
         .split("\n")
         .some((name) => name.trim().startsWith(prefix));

package/dist/images/commands.d.ts

@@ -1,5 +1,4 @@
 import type { Format } from "./open-graph-types.js";
-import { type Instance } from "../instance.js";
 import { type EventReader } from "./events.js";
 import { type Selection } from "./select.js";
 export interface ImagesOptions {
@@ -23,13 +22,11 @@ export declare function wantsEvents(patterns: readonly string[]): boolean;
 /** Whether a pattern names events specifically, rather than sweeping them up. */
 export declare function namesEvents(patterns: readonly string[]): boolean;
 export interface ImagesDeps {
-    /** Resolves the database, printing its own diagnosis on failure. */
-    connect: () => Promise<Instance | null>;
-    /** Overridden in tests so nothing opens a socket. */
-    reader?: (instance: Instance) => EventReader;
+    /** Overridden in tests so nothing reads the peer package or the filesystem. */
+    reader?: () => EventReader;
 }
 /** Where one selection is written. */
 export declare function destinationOf({ graphic, format }: Selection, out: string | undefined): string;
-export declare function runImages(argv: string[], deps: ImagesDeps): Promise<void>;
+export declare function runImages(argv: string[], deps?: ImagesDeps): Promise<void>;
 /** Re-exported so `render.ts`'s options type is the format's own shape. */
 export type { Format };