@devdogsuga/devtools 0.1.26 → 0.1.27

package/dist/stack.js

@@ -1,403 +0,0 @@
-/**
- * Database commands, over the session's database.
- *
- * Previously delegated to `@devdogsuga/supabase` package scripts by name,
- * then to a `--target local|remote` flag; now every data command acts on the
- * ONE database the session entered (see `db/connection.ts`), passed to the
- * supabase CLI as an explicit `--db-url`. That uniformity is load-bearing:
- * the CLI's own defaults disagree per subcommand (`db push` defaults to the
- * LINKED project, `db reset` to `--local`), and `--db-url` is the one
- * spelling that can neither fall back to `supabase link`'s ambient state
- * nor quietly pick a different database than the session says.
- *
- * The stack-lifecycle commands (`start`/`stop`/`restart`) are the deliberate
- * exception: they act on this machine's Docker containers, which no DB_URL
- * names, and they run under any session — starting your local stack while
- * the session targets staging is odd but harmless, and refusing it would
- * block the one command that fixes an offline-local session.
- */
-import { existsSync, rmSync } from "node:fs";
-import { writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import { describeEnvironment, probeEnvironment } from "./environment.js";
-import { findRepoRoot } from "./repo/root.js";
-import { foreignStackMessage, foreignStackProjectId, listContainerNames, STACK_API_PORT, readProjectId, } from "./repo/supabase-project.js";
-import { dbPush, generateTypes, seedBuckets, supabase, supabaseCapture, } from "./db/run.js";
-import { describeDbTarget, isLocalConnection, } from "./db/connection.js";
-import { refreshSessionEnv } from "./db/session-refresh.js";
-import { runSeedProduction } from "./db/seed-production.js";
-import { originReachable, resolveBaseUrl } from "./cron/commands.js";
-import { ensureGeneratedEnvFile, realEnsureGeneratedEnvDeps, } from "./db/generated-env.js";
-import { loadEnvLoad } from "./repo/peers.js";
-// Scope order, matching `db`'s subcommands in `commands.ts`: the four that
-// act on the Supabase stack (`connect` is handled separately below — it
-// takes a positional ref), then the two that write the Postgres database
-// inside the session's endpoint.
-export const STACK_COMMANDS = [
-    "start",
-    "stop",
-    "restart",
-    "status",
-    "migrate",
-    "reset",
-];
-// ── Implementations ──────────────────────────────────────────────────────────
-/**
- * A running Docker container whose name says it belongs to a DIFFERENT
- * Supabase project than this checkout's own `config.toml` — the signature
- * of a foreign stack holding the shared ports (see
- * `repo/supabase-project.ts`'s header). `undefined` when nothing points
- * that way, including when Docker or `config.toml` could not be read at
- * all: with no signal either way, `startLocalStack`'s own failure and the
- * Supabase CLI's own output are still the reader's best explanation.
- */
-function foreignStackHint() {
-    const names = listContainerNames(STACK_API_PORT);
-    if (names === null)
-        return undefined;
-    const foreign = foreignStackProjectId(names, readProjectId(findRepoRoot()));
-    return foreign === null ? undefined : foreignStackMessage(foreign);
-}
-/**
- * `wroteEnvFile` is split out from `code` on purpose: `.env.generated` is
- * written to disk BEFORE `seedBuckets` runs, so a nonzero `code` from
- * `seedBuckets` alone does not mean the file on disk is unchanged — the
- * fresh connection block is already there, a later `db start` retry or the
- * probe table would already see it, and this process's OWN entered
- * environment is now the stale one. `afterLocalStackChange` below refreshes
- * whenever the file changed, independently of whether the command as a whole
- * succeeded, and still reports the failing code so the caller does not
- * mistake a seed failure for success.
- *
- * `hint` is set when `supabase start` itself fails (before anything here
- * could have written `.env.generated`) AND a foreign project's stack is
- * holding the ports — the same signal `db/generated-env.ts` surfaces for a
- * failed `supabase status -o env`, named here too so `db start` explains
- * itself instead of leaving only the bare Supabase CLI error.
- */
-async function startLocalStack() {
-    const code = await supabase("start");
-    if (code !== 0) {
-        const hint = foreignStackHint();
-        return hint === undefined
-            ? { code, wroteEnvFile: false }
-            : { code, wroteEnvFile: false, hint };
-    }
-    // Write the local stack's connection details so with-env can load them.
-    let env;
-    try {
-        env = await supabaseCapture("status", "-o", "env");
-    }
-    catch {
-        return { code: 1, wroteEnvFile: false };
-    }
-    await writeFile(join(findRepoRoot(), ".env.generated"), env);
-    const bucketsCode = await seedBuckets({ kind: "local" });
-    return { code: bucketsCode, wroteEnvFile: true };
-}
-async function stopLocalStack() {
-    const code = await supabase("stop");
-    if (code !== 0)
-        return code;
-    rmSync(join(findRepoRoot(), ".env.generated"), { force: true });
-    return 0;
-}
-/**
- * `db connect [<project-ref>]` — run `supabase link` for whoever drives the
- * bare supabase CLI by hand. Nothing in devtools reads what it writes any
- * more (see `db/connection.ts`'s header); it survives as a convenience, not
- * a dependency.
- */
-export async function connectRemoteProject(ref) {
-    const projectRef = ref ?? process.env.PROJECT_REF;
-    if (!projectRef) {
-        process.stderr.write("devtools db connect: no project ref given, and PROJECT_REF is not set. " +
-            "Pass one, or add PROJECT_REF to your .env file.\n");
-        return 1;
-    }
-    return supabase("link", "--project-ref", projectRef);
-}
-/** The `seed buckets` shape this connection implies — `--db-url` does not
- * exist for that subcommand, so it is the one data command still keyed on
- * local-vs-hosted rather than on the URL itself. */
-function bucketsShape(connection) {
-    return isLocalConnection(connection)
-        ? { kind: "local" }
-        : { kind: "remote", projectRef: connection.projectRef };
-}
-async function pushMigrations(connection) {
-    // The bare push (shared with CI's `deploy migrate`) then the type
-    // regeneration the contributor path layers on top — see `dbPush`'s header
-    // for why the two are split.
-    const code = await dbPush(connection.dbUrl);
-    if (code !== 0)
-        return code;
-    return generateTypes(connection.dbUrl);
-}
-/**
- * ⚠️ SAFETY-CRITICAL: drops and re-migrates `connection.dbUrl`. The caller
- * (`cli.ts`'s `runStack`) has already confirmed the session target —
- * including the hard production gate — before this ever runs.
- *
- * A non-development target gets `--no-seed` on the reset itself, followed by
- * an explicit `runSeedProduction` — the same two steps `db seed production`
- * runs on its own (see `seed-production.ts`) — rather than letting the bare
- * `supabase db reset` apply whatever `config.toml`'s `[db.seed]` happens to
- * list. That is deliberately belt-and-suspenders: `[db.seed]` today lists
- * only `supabase/seed/production`, so the bare reset would already do the
- * right thing, but that is a property of the CURRENT config, not of this
- * function. An older checkout, or a config edited to add
- * `supabase/seed/development` back for some local-only reason, must still be
- * structurally unable to run development's password-login seeds against a
- * hosted, non-dev database — the one seed directory that must never reach
- * staging or production, named in that directory's own header. Development
- * resets are untouched: they keep applying whatever `[db.seed]` lists, same
- * as always.
- *
- * Meetings and workshops are NOT among the tables `supabase/seed/*.sql`
- * populates -- they come from `@devdogsuga/events` via
- * `reconcileFromConfig`, an authenticated platform route rather than a
- * devtools-side function this CLI can call directly (it needs the app's
- * Drizzle client, relations and Sentry wiring, none of which belong in this
- * package). On any DEVELOPMENT reset -- local Docker or the shared remote dev
- * project alike -- this calls that route itself, over the same origin `cron
- * run` would use, once the reset and rebuild finish -- see
- * `reconcileConfigAfterReset` for what happens when nothing is listening yet.
- */
-async function reset(connection) {
-    const isDev = connection.tier === "development";
-    const code = await supabase("db", "reset", "--db-url", connection.dbUrl, ...(isDev ? [] : ["--no-seed"]));
-    if (code !== 0)
-        return { code, lines: [] };
-    const types = await generateTypes(connection.dbUrl);
-    if (types !== 0)
-        return { code: types, lines: [] };
-    const bucketsCode = await seedBuckets(bucketsShape(connection));
-    if (bucketsCode !== 0)
-        return { code: bucketsCode, lines: [] };
-    if (!isDev) {
-        const seedCode = await runSeedProduction(connection.dbUrl);
-        if (seedCode !== 0)
-            return { code: seedCode, lines: [] };
-        return { code: 0, lines: [] };
-    }
-    return {
-        code: 0,
-        // Both development databases — local Docker and the shared remote dev
-        // project (`--tier development:remote`) — rather than gated on
-        // `isLocalConnection`. The platform dev server this hits is always local
-        // (`resolveBaseUrl("platform", "development", …)` inside
-        // `reconcileConfigAfterReset`); what varies with `devDatabase` is only
-        // which Postgres that local server happens to be pointed at, and a
-        // remote-dev reset leaves meetings and workshops just as unseeded as a
-        // local one.
-        lines: await reconcileConfigAfterReset(),
-    };
-}
-/**
- * Best-effort trigger for `GET /cron/config-reconcile` against the local
- * platform dev server, so `db reset` leaves meetings and workshops seeded
- * whenever that server happens to already be up -- the common case for a
- * repeat reset during development, rather than a first clone. No
- * `CRON_SECRET` is sent because the route itself skips auth outside a
- * deployed `DEPLOY_ENV` (see that route's header); this is exactly the
- * unauthenticated local request `cron run` would send.
- *
- * When nothing answers yet -- most likely a first-time reset, before anyone
- * has run `pnpm --filter platform dev` -- this reports that instead of
- * silently leaving the tables empty, and names the manual step: start the
- * server, then either re-run this reset or fire the shared fifteen-minute
- * cron slot directly with `pnpm devtools cron run`.
- */
-export async function reconcileConfigAfterReset(deps = {
-    reachable: originReachable,
-    fetch: globalThis.fetch,
-}) {
-    const { reachable, fetch: fetchImpl } = deps;
-    const baseUrl = resolveBaseUrl("platform", "development", undefined, {});
-    const manualStep = "Start the platform app (`pnpm --filter platform dev`) and either " +
-        "re-run `pnpm devtools db reset` or run `pnpm devtools cron run --app " +
-        "platform --cron '*/15 * * * *' --yes`.";
-    if (!(await reachable(baseUrl))) {
-        return [
-            `Meetings and workshops are not seeded yet -- nothing is listening at ${baseUrl} ` +
-                `to reconcile @devdogsuga/events into them. ${manualStep}`,
-        ];
-    }
-    const url = new URL("/cron/config-reconcile", baseUrl).toString();
-    let response;
-    try {
-        response = await fetchImpl(url);
-    }
-    catch (err) {
-        return [
-            `Config reconcile request to ${url} failed: ` +
-                `${err instanceof Error ? err.message : String(err)}. ${manualStep}`,
-        ];
-    }
-    if (!response.ok) {
-        return [
-            `Config reconcile answered HTTP ${response.status} at ${url}. ${manualStep}`,
-        ];
-    }
-    const body = (await response.json());
-    if (!body.success) {
-        return [
-            `Config reconcile ran but was aborted (${body.reason}) -- meetings and ` +
-                "workshops are still empty. Check the platform dev server's console.",
-        ];
-    }
-    return ["Meetings and workshops reconciled from @devdogsuga/events."];
-}
-/**
- * BUG 2's fix, applied at every point `start`/`stop`/`restart` can change
- * `.env.generated`: on success, refresh this process's entered environment
- * (see `db/session-refresh.ts`) so the rest of the session — including a
- * `db introspect` run right after this one — sees the stack's CURRENT
- * connection, not whatever `process.env` held at launch. A failed stack
- * command USUALLY changed nothing on disk, so by default there is nothing to
- * refresh.
- *
- * `wroteEnvFile` is the one exception: `startLocalStack` writes
- * `.env.generated` BEFORE the buckets-seed step that can still fail
- * afterwards, so a nonzero `code` from THAT failure does not mean the file on
- * disk is unchanged — see `startLocalStack`'s own doc. Passing `true` here
- * refreshes regardless of `code`, while the failing code itself still reaches
- * the caller untouched, so `db start` is still reported as failed even though
- * the session's environment was brought current.
- */
-async function afterLocalStackChange(code, wroteEnvFile = false) {
-    if (code !== 0 && !wroteEnvFile)
-        return [];
-    return refreshSessionEnv();
-}
-// ── The local stack's lifecycle ──────────────────────────────────────────────
-/**
- * Stop, then start again.
- *
- * Two steps rather than one, because `supabase restart` does not exist. The
- * CLI's own answer to a changed `config.toml` is a stop/start pair. Doing it
- * here turns that into one menu entry, rather than two commands the contributor
- * has to know to run in that order.
- *
- * A failed stop short-circuits. Starting a stack that never went down would
- * report success and leave the config change unapplied, which is the one
- * outcome worse than a visible failure.
- */
-async function restartLocal() {
-    const stopCode = await stopLocalStack();
-    if (stopCode !== 0) {
-        return {
-            code: stopCode,
-            lines: [
-                "Stopping failed, so nothing was restarted. " +
-                    "Scroll up for the output from the Supabase CLI.",
-            ],
-        };
-    }
-    const { code, wroteEnvFile, hint } = await startLocalStack();
-    const lines = await afterLocalStackChange(code, wroteEnvFile);
-    return { code, lines: hint === undefined ? lines : [hint, ...lines] };
-}
-/**
- * What `status` says for a local session, now that it can answer for itself.
- *
- * `environment.ts` already reads the two facts that question is really
- * asking about, so this reports them and names the next step. When the
- * stack's containers are up but this checkout's own `.env.generated` is
- * missing — most often a stack another workspace started, sharing this
- * repo's `project_id` — this also attempts the same regeneration
- * `enterSessionEnvironment` (`env-entry.ts`) runs before every command, so
- * `db status` reports the file's ACTUAL state after trying to fix it,
- * rather than a stale "the stack is up" that leaves the absence a mystery.
- */
-async function localStatus() {
-    const env = probeEnvironment();
-    const lines = [describeEnvironment(env)];
-    if (env.docker === "no") {
-        lines.push("Start Docker, then `pnpm devtools db start` to bring the stack up.");
-        return { code: 0, lines };
-    }
-    if (env.stack === "no") {
-        lines.push("Nothing is running. `pnpm devtools db start` starts it.");
-        return { code: 0, lines };
-    }
-    if (env.stack === "unknown") {
-        lines.push("Could not read Docker. `supabase status` asks the stack directly.");
-        return { code: 0, lines };
-    }
-    // env.stack === "yes"
-    const repoRoot = findRepoRoot();
-    if (existsSync(join(repoRoot, ".env.generated"))) {
-        lines.push("The stack is up. `supabase status` prints its URLs and keys.");
-        return { code: 0, lines };
-    }
-    const envLoad = await loadEnvLoad();
-    const generated = await ensureGeneratedEnvFile("development", undefined, realEnsureGeneratedEnvDeps(envLoad.probeLocalStack));
-    if (generated.outcome === "wrote") {
-        lines.push(generated.line.replace(/^devtools: /, ""), "The stack is up. `supabase status` prints its URLs and keys.");
-    }
-    else if (generated.outcome === "foreign") {
-        lines.push(generated.line.replace(/^devtools: /, ""));
-    }
-    else if (generated.outcome === "unreachable") {
-        lines.push("The stack's containers are up but .env.generated could not be " +
-            "regenerated — run `supabase status -o env` yourself to see why.");
-    }
-    else {
-        // "skipped": Docker's container list said the stack is up, but nothing
-        // answered the port probe — a race right after `db start`/`db restart`,
-        // most likely. Nothing to regenerate from yet.
-        lines.push("Docker reports the stack's containers running, but nothing is " +
-            "answering on 127.0.0.1:54321 yet — try again in a moment.");
-    }
-    return { code: 0, lines };
-}
-/**
- * Runs a stack command, returning its exit code and anything to report.
- *
- * `connection` is present exactly when the command writes the database
- * (`migrate`, `reset`) — the caller (`cli.ts`'s `runStack`) resolves it,
- * because resolving means possibly refusing with a printed reason, and the
- * lifecycle commands must keep working with no resolvable database at all
- * (that is what `db start` is FOR). `status` receives whatever resolved,
- * or `null`, and degrades to machine facts.
- */
-export async function runStackCommand(command, connection) {
-    if (command === "restart")
-        return restartLocal();
-    if (command === "stop") {
-        const code = await stopLocalStack();
-        return { code, lines: await afterLocalStackChange(code) };
-    }
-    if (command === "start") {
-        const { code, wroteEnvFile, hint } = await startLocalStack();
-        const lines = await afterLocalStackChange(code, wroteEnvFile);
-        return { code, lines: hint === undefined ? lines : [hint, ...lines] };
-    }
-    if (command === "status") {
-        if (connection === null || isLocalConnection(connection)) {
-            return localStatus();
-        }
-        return {
-            code: 0,
-            lines: [
-                `This session targets ${describeDbTarget(connection)}` +
-                    (connection.projectRef
-                        ? ` (project ${connection.projectRef}).`
-                        : ".") +
-                    " Check the Supabase dashboard for its health.",
-            ],
-        };
-    }
-    if (connection === null) {
-        return {
-            code: 1,
-            lines: [`No database connection was resolved for \`${command}\`.`],
-        };
-    }
-    if (command === "migrate") {
-        return { code: await pushMigrations(connection), lines: [] };
-    }
-    return reset(connection);
-}

package/dist/telemetry.d.ts

@@ -1,59 +0,0 @@
-/** The run-time `DEVTOOLS_SENTRY_DSN` if set, else the baked one. */
-export declare function resolveDevtoolsDsn(env: NodeJS.ProcessEnv, baked: string): string;
-/**
- * `'ci'` in every GitHub Actions job (`CI` is set by the runner itself,
- * before any workflow-authored env), `'local'` on a contributor's machine.
- * One of `@devdogsuga/telemetry`'s `ENVIRONMENTS`.
- */
-export declare function devtoolsEnvironment(): "ci" | "local";
-/**
- * `DEVTOOLS_TELEMETRY=0` (any other value, including unset, leaves reporting
- * on) is the only opt-out. Checked by both `initDevtoolsTelemetry` (skips
- * `Sentry.init` outright) and `captureDevtoolsError` (so setting it mid-run,
- * or between two invocations in the same process, still works).
- */
-export declare function devtoolsTelemetryEnabled(): boolean;
-/**
- * Whether anyone is actually using devtools in this process. Package-registry
- * scanners install every published version within minutes and run it in a
- * throwaway sandbox (random `DESKTOP-xxxxxx` hosts, Firecracker VMs, a fuzzer
- * that turns `process.exit` into a throw). Left unfiltered, each release filed
- * the same two issues from them. They run with no DevDogsUGA checkout and no
- * terminal. A person has at least one of the two (`setup` runs outside a
- * checkout, but in a terminal), and CI always has a checkout.
- */
-export declare function hasRealCaller(inRepo: boolean, isTTY: boolean): boolean;
-/**
- * Initializes `@sentry/node` for this CLI process. Safe to call more than
- * once (idempotent) and safe to call with no DSN configured (no-ops via
- * `buildSentryOptions`, see its header).
- *
- * `command` becomes a `command` tag on every event this process reports, so
- * an issue in Sentry names the subcommand it came from (`db reset`,
- * `deploy platform`, …) without anyone opening the job log first.
- */
-export declare function initDevtoolsTelemetry(command: string): void;
-/**
- * Reports an error nothing below the entry points caught — `launch.ts`'s
- * `dispatch`, `launch-ci.ts`, and the bins — then flushes before the process
- * exits. Node's event loop dies with `process.exit`, taking any in-flight
- * request to Sentry's ingest endpoint with it, so the flush must be awaited
- * BEFORE that call — never after.
- *
- * A short timeout: a CLI exiting on error should not hang perceptibly longer
- * because Sentry's ingest is slow or unreachable.
- */
-export declare function captureDevtoolsError(err: unknown): Promise<void>;
-/**
- * Reports an error a command caught and explained to the reader itself
- * (`explainError` in `ui.ts`, `devtools-ci deploy`'s catch), then carried on
- * to a normal exit. Not flushed: the SDK's in-flight request keeps the event
- * loop alive until it lands, so a natural exit waits for it on its own. A
- * path that ends in `process.exit` instead must use `captureDevtoolsError`.
- */
-export declare function reportDevtoolsError(err: unknown): void;
-/**
- * Reports a failure that has no error object — a subprocess or deploy step
- * that exited non-zero. Same no-flush contract as `reportDevtoolsError`.
- */
-export declare function reportDevtoolsFailure(message: string, extra?: Record<string, unknown>): void;

package/dist/tier.d.ts

@@ -1,40 +0,0 @@
-import type { DeployEnvironment } from "@devdogsuga/env";
-interface ResolveTierOptions {
-    /** Stderr prefix, e.g. "devtools cf preview". */
-    label?: string;
-    /** Injectable for tests; defaults to the repo's `availableTiers()`. */
-    available?: DeployEnvironment[];
-    /**
-     * The tier the process has already ENTERED, honoured when no explicit tier
-     * was passed. Injectable for tests; defaults to `process.env.DEPLOY_ENV`.
-     *
-     * The wizard enters a tier once, up front (see `menu.ts`), by loading its
-     * env and setting `DEPLOY_ENV`; a `DEPLOY_ENV=staging pnpm devtools …` on
-     * the command line does the same. Either way a command that resolves its own
-     * tier should use that answer rather than ask a question already settled for
-     * the whole session.
-     */
-    deployEnv?: string;
-    /** Injectable for tests; defaults to `process.stdin.isTTY`. */
-    isTTY?: boolean;
-    /** Injectable for tests; defaults to a clack `select` wrapped in `unwrap`. */
-    prompt?: (message: string, choices: {
-        value: DeployEnvironment;
-        label: string;
-        hint?: string;
-    }[]) => Promise<DeployEnvironment>;
-}
-/**
- * The deploy tier a command runs under when `--tier` was not passed.
- *
- * Prompts ONLY when more than one deploy tier's file is present — the
- * handful of contributors working on the deploy workflow — so that everyone
- * else (just development, possibly with `.env.generated` from a running
- * local stack) falls straight through to development with no prompt at all.
- *
- * Returns `null` after reporting an error on stderr — an invalid `--tier`, or
- * an interactive pick of a tier whose file is missing — so the caller can
- * exit nonzero without printing a second message of its own.
- */
-export declare function resolveTier(given: string | undefined, message: string, opts?: ResolveTierOptions): Promise<DeployEnvironment | null>;
-export {};

package/dist/tier.js

@@ -1,96 +0,0 @@
-/**
- * The shared `--tier` resolver for the handful of commands that pick a
- * deploy tier of their OWN, separate from the session-wide tier
- * `src/launch.ts` already resolved and entered before this CLI ever runs
- * (see that file's header, and `@devdogsuga/env/session`, which is where
- * `availableTiers` and the session-wide policy now live — this module used
- * to carry its own copy of both, one of two the wizard's tier question also
- * used to keep before it moved into `launch.ts`).
- *
- * `cf preview`, `cron run` and `workflows run` still need a resolver of their
- * own: each names the tier something it is doing right now — running a
- * workflow, previewing a build — SEPARATELY from the tier the session as a
- * whole is running under (`process.env.DEPLOY_ENV`, honoured here as the
- * fallback below), and a command flag can still name a different one. All
- * three used to ask the same "which tier?" question with a subtly different
- * answer, which is what this module unified. It asks only when the answer is
- * not foregone: when more than one deploy tier's env file is actually
- * present. That is the signature of someone working on the deploy workflow
- * itself, who keeps `.env.staging` or `.env.production` around to test
- * against. Everyone else falls straight through to development, exactly as
- * if `--tier development` had been typed.
- */
-import { select } from "@clack/prompts";
-import { loadEnv, loadEnvSession } from "./repo/peers.js";
-import { findRepoRoot } from "./repo/root.js";
-import { unwrap } from "./ui.js";
-/**
- * The deploy tier a command runs under when `--tier` was not passed.
- *
- * Prompts ONLY when more than one deploy tier's file is present — the
- * handful of contributors working on the deploy workflow — so that everyone
- * else (just development, possibly with `.env.generated` from a running
- * local stack) falls straight through to development with no prompt at all.
- *
- * Returns `null` after reporting an error on stderr — an invalid `--tier`, or
- * an interactive pick of a tier whose file is missing — so the caller can
- * exit nonzero without printing a second message of its own.
- */
-export async function resolveTier(given, message, opts = {}) {
-    const label = opts.label ?? "devtools";
-    const env = await loadEnv();
-    if (given !== undefined) {
-        if (env.isDeployEnvironment(given))
-            return given;
-        process.stderr.write(`${label}: unknown tier "${given}". Expected: ${env.DEPLOY_ENVIRONMENTS.join(", ")}.\n`);
-        return null;
-    }
-    // Already inside a tier? Honour it instead of prompting. An entered tier is
-    // an answer, exactly like an explicit `--tier` above — including one whose
-    // file is missing, which `loadEnvironment` then reports — so it is validated
-    // for shape only, not existence, and does NOT fall through to the picker.
-    const entered = opts.deployEnv ?? process.env.DEPLOY_ENV;
-    if (entered !== undefined &&
-        entered !== "" &&
-        env.isDeployEnvironment(entered)) {
-        return entered;
-    }
-    const available = opts.available ??
-        (await (await loadEnvSession()).availableTiers(findRepoRoot()));
-    // Zero or one tier file present: there is nothing to choose between, so
-    // asking would be a question with one possible answer. Fall through to
-    // whichever tier is present, or development when nothing is (a machine
-    // that has never run `env pull` at all).
-    if (available.length <= 1)
-        return available[0] ?? "development";
-    const isTTY = opts.isTTY ?? process.stdin.isTTY;
-    if (!isTTY)
-        return "development";
-    const prompt = opts.prompt ??
-        (async (msg, choices) => unwrap(await select({
-            message: msg,
-            options: choices,
-        })));
-    // Show every deploy tier, not just the present ones: clack's `select` has
-    // no true "disabled" state, so a tier whose file is missing is shown with
-    // a hint that says so and how to fix it, rather than removed from the list
-    // where a contributor who expected to see "production" would wonder if
-    // they misconfigured something.
-    const choices = env.DEPLOY_ENVIRONMENTS.map((tier) => ({
-        value: tier,
-        label: tier,
-        hint: !available.includes(tier)
-            ? `needs env pull --target ${tier}`
-            : tier === "development"
-                ? "the default"
-                : tier === "production"
-                    ? "⚠️  live data"
-                    : undefined,
-    }));
-    const choice = await prompt(message, choices);
-    if (!available.includes(choice)) {
-        process.stderr.write(`${label}: ${env.fileFor(choice)} is not present — run \`pnpm devtools env pull --target ${choice}\` first.\n`);
-        return null;
-    }
-    return choice;
-}

package/dist/ui.d.ts

@@ -1,40 +0,0 @@
-export declare function bail(message?: string): never;
-/** Exits cleanly on Ctrl-C rather than letting a cancel symbol leak onward. */
-export declare function unwrap<T>(value: T | symbol): T;
-/**
- * Reports a failure with the next thing to try.
- *
- * `hints` is not decoration: for most of these failures the fix is one command,
- * and printing it is the difference between a contributor continuing and a
- * contributor asking in Discord.
- */
-export declare function explain(summary: string, detail: string, hints?: string[]): void;
-/**
- * A refusal the reader can fix themselves — a name that matches nothing, a
- * flag missing where there is no terminal to ask. Thrown from deep enough
- * that the command's catch can't tell it from a real failure any other way;
- * `explainError` prints it like any other error but keeps it out of Sentry.
- */
-export declare class UsageError extends Error {
-    name: string;
-}
-/**
- * `explain()` for a caught error rather than a refusal: prints the same way,
- * with `err`'s message as the detail, and reports `err` to Sentry unless it
- * is a {@link UsageError}. Only failures nobody anticipated belong there.
- */
-export declare function explainError(summary: string, err: unknown, hints?: string[]): void;
-export declare function errorMessage(err: unknown): string;
-export interface CheckResult {
-    name: string;
-    ok: boolean;
-    detail: string;
-}
-/**
- * A pass/fail list.
- *
- * Deliberately plain text rather than a box-drawing table: these lines get
- * pasted into Discord and GitHub issues, where anything fancier turns to
- * rubble.
- */
-export declare function renderChecks(checks: CheckResult[]): string;