@devdogsuga/devtools 0.1.0

package/dist/env/selection.d.ts

@@ -0,0 +1,105 @@
+import { type VaultTarget } from "../bws/environments.js";
+export interface PushSelection {
+    push: Map<string, string>;
+    /**
+     * Public per-environment values, bound for Bitwarden and for GitHub
+     * *variables*. Plaintext at both ends, with no libsodium sealing, and
+     * readable back through the API, which is what lets `audit` compare them by
+     * value.
+     */
+    variables: Map<string, string>;
+    refused: string[];
+    /** Present in the file, declared by no manifest. Skipped, warned about. */
+    unknown: string[];
+    /**
+     * Left to the registry: the file still holds the declared derivation itself.
+     *
+     * Its own outcome rather than part of the skipped-and-unreported majority,
+     * because `env init --target` WRITES these lines, eight of them, and a push
+     * that said nothing about them would read as "your eight `$VAR` lines were
+     * stored". They were not, deliberately. See `selectForPush()`.
+     */
+    derived: string[];
+}
+/**
+ * Public per-environment values: Bitwarden, and then GitHub *variables*.
+ *
+ * Symmetric with `neverStore()` and `minted()`: a set, read at call time,
+ * refusing an empty registry. See `getEnvSync().variableKeys()` for why the set is narrower
+ * than "every public key" and why the five `localStack` ones are still in it.
+ */
+export declare function pushableVariables(): Set<string>;
+/**
+ * Nothing to send: the committed and per-developer non-secrets, the minted
+ * credentials, plus the apply-only ones outside production.
+ *
+ * ⚠️ This is `getEnvSync().neverSecretKeys()` MINUS the pushable variables, and the
+ * subtraction is what gave 27 public, environment-scoped values a remote home.
+ * They used to land here, as "not a secret, therefore uninteresting", which
+ * conflated two different facts: that a value must not be a GitHub *secret*
+ * (true of all of them) and that it goes nowhere (true only of the committed
+ * and per-developer ones). Every consumer of this set reads it as the second,
+ * so the first no longer belongs in it.
+ *
+ * The apply-only two exist to reshape production, so a copy in staging or
+ * preflight is a second write-capable token to rotate for no benefit.
+ *
+ * Minted credentials are here because there is nothing to send: the value is
+ * signed at deploy time and its only copy is on the Worker. Skipped rather
+ * than refused, because "not pushed" is the ordinary state of one of these. A
+ * refusal is for a credential somebody put in the file expecting it to sync,
+ * and nobody has this one to put there.
+ *
+ * ⚠️ AND, for a target no app boots from, EVERYTHING THAT DID NOT OPT IN. This
+ * is the one exclusion that inverts the default: a deployed target skips a
+ * named few, `preflight` skips all but a named few. It inverts it because the
+ * two questions are different. "Which keys does staging not want?" has a short
+ * answer; "which credentials may a CI-only tier hold?" has the answer "the
+ * ones deliberately narrowed for it, and nothing by omission". Until this
+ * existed, `env push --target preflight` uploaded `SUPABASE_JWT_SIGNING_KEY`,
+ * `SECRET_KEY` and `GH_APP_PRIVATE_KEY` into a project whose GitHub
+ * environment is reachable from `main`. Both halves are derived, the target
+ * from `deployEnv: false` and the keys from `EnvMeta.narrowed`, so neither is
+ * a list to keep up to date.
+ */
+export declare function ignoredFor(target: VaultTarget): Set<string>;
+export declare function neverStore(): Set<string>;
+/**
+ * The keys a push for this target ROUTES: its two destinations, unioned.
+ *
+ * The complement of everything above, stated positively, because one consumer
+ * needs the question the other way round. `env init --target staging` renders
+ * a file whose whole purpose is to be filled in and pushed, so the keys it
+ * should contain are exactly the keys a push for that target would carry
+ * somewhere. Derived from `ignoredFor()` rather than re-listed, so the file
+ * and the upload cannot disagree about which target a key belongs to. The
+ * generated file used to be byte-identical for all three targets, which put
+ * the apply-tier credentials in `.env.staging` where `ignoredFor()` refuses
+ * them. The same derivation shrank `env init --target preflight` from 45 keys
+ * to the narrowed ones: the exclusion is stated once, in `ignoredFor()`, and
+ * the rendered file follows for free.
+ *
+ * The `neverStore()` subtraction is unreachable today (a never-store key is
+ * neither `secrecy: "secret"` nor `"public"`, so neither selector returns it)
+ * and is written down anyway: this set decides what gets an assignable line in
+ * a file people fill in, and `BWS_ACCESS_TOKEN=` is the one line that must
+ * never appear in one.
+ */
+export declare function keysRoutedTo(target: VaultTarget): Set<string>;
+/**
+ * Signed at deploy time; the deploy target holds the only copy.
+ *
+ * Passed to `audit` separately from `ignoredFor()` even though it is a subset,
+ * because the audit needs the distinction: an ignored key is uninteresting
+ * everywhere, whereas a minted one is CORRECT on Cloudflare (which is what
+ * stops it being reported as an orphan and pruned) and WRONG in Bitwarden or
+ * GitHub.
+ */
+export declare function minted(): Set<string>;
+/**
+ * `entries` is the ACTIVE assignments in the local `.env`, in file order.
+ *
+ * A commented-out line is not an assignment and never reaches here, which is
+ * what makes commenting-out a safe way to retire a key.
+ */
+export declare function selectForPush(entries: readonly (readonly [string, string])[], target: VaultTarget): PushSelection;

package/dist/env/selection.js

@@ -0,0 +1,226 @@
+import {} from "../bws/environments.js";
+import { assertRegistryLoaded } from "./discovery.js";
+import { getEnvSync } from "../repo/peers.js";
+// The key sets are DERIVED from the env manifests (see `discovery.ts`), not
+// hand-listed here, which is why every function below insists the registry is
+// loaded. An empty registry makes each selector return `[]`, and `[]` fails
+// open in the one direction that matters: nothing would be refused, so
+// `BWS_ACCESS_TOKEN` would upload.
+/**
+ * Public per-environment values: Bitwarden, and then GitHub *variables*.
+ *
+ * Symmetric with `neverStore()` and `minted()`: a set, read at call time,
+ * refusing an empty registry. See `getEnvSync().variableKeys()` for why the set is narrower
+ * than "every public key" and why the five `localStack` ones are still in it.
+ */
+export function pushableVariables() {
+    assertRegistryLoaded();
+    return new Set(getEnvSync().variableKeys());
+}
+/**
+ * Nothing to send: the committed and per-developer non-secrets, the minted
+ * credentials, plus the apply-only ones outside production.
+ *
+ * ⚠️ This is `getEnvSync().neverSecretKeys()` MINUS the pushable variables, and the
+ * subtraction is what gave 27 public, environment-scoped values a remote home.
+ * They used to land here, as "not a secret, therefore uninteresting", which
+ * conflated two different facts: that a value must not be a GitHub *secret*
+ * (true of all of them) and that it goes nowhere (true only of the committed
+ * and per-developer ones). Every consumer of this set reads it as the second,
+ * so the first no longer belongs in it.
+ *
+ * The apply-only two exist to reshape production, so a copy in staging or
+ * preflight is a second write-capable token to rotate for no benefit.
+ *
+ * Minted credentials are here because there is nothing to send: the value is
+ * signed at deploy time and its only copy is on the Worker. Skipped rather
+ * than refused, because "not pushed" is the ordinary state of one of these. A
+ * refusal is for a credential somebody put in the file expecting it to sync,
+ * and nobody has this one to put there.
+ *
+ * ⚠️ AND, for a target no app boots from, EVERYTHING THAT DID NOT OPT IN. This
+ * is the one exclusion that inverts the default: a deployed target skips a
+ * named few, `preflight` skips all but a named few. It inverts it because the
+ * two questions are different. "Which keys does staging not want?" has a short
+ * answer; "which credentials may a CI-only tier hold?" has the answer "the
+ * ones deliberately narrowed for it, and nothing by omission". Until this
+ * existed, `env push --target preflight` uploaded `SUPABASE_JWT_SIGNING_KEY`,
+ * `SECRET_KEY` and `GH_APP_PRIVATE_KEY` into a project whose GitHub
+ * environment is reachable from `main`. Both halves are derived, the target
+ * from `deployEnv: false` and the keys from `EnvMeta.narrowed`, so neither is
+ * a list to keep up to date.
+ */
+export function ignoredFor(target) {
+    assertRegistryLoaded();
+    const pushable = pushableVariables();
+    const skip = new Set(getEnvSync().neverSecretKeys().filter((key) => !pushable.has(key)));
+    for (const key of getEnvSync().mintedKeys())
+        skip.add(key);
+    if (target !== "production") {
+        for (const key of getEnvSync().applyOnlyKeys())
+            skip.add(key);
+    }
+    // Plan-tier keys are read by exactly two jobs: `main-plan` (preflight) and
+    // `production-plan` (production). Everywhere else, staging today, a copy is
+    // a credential nothing reads, so it is skipped the same way the apply-tier
+    // pair is. Preflight is NOT excluded here: the narrowed-only branch below
+    // already decides that target key by key, and a plan-tier key reaches it
+    // through its `narrowed` opt-in.
+    if (target !== "production" && !getEnvSync().holdsOnlyNarrowedKeys(target)) {
+        for (const key of getEnvSync().planOnlyKeys())
+            skip.add(key);
+    }
+    if (getEnvSync().holdsOnlyNarrowedKeys(target)) {
+        const narrow = new Set(getEnvSync().narrowedKeys());
+        // Over every DECLARED key, not over the routable ones: this set is also
+        // what `audit` treats as uninteresting and what `push` reports orphans
+        // against, and both want the full answer.
+        for (const key of getEnvSync().variables().keys()) {
+            if (!narrow.has(key))
+                skip.add(key);
+        }
+    }
+    return skip;
+}
+export function neverStore() {
+    assertRegistryLoaded();
+    return new Set(getEnvSync().neverStoreKeys());
+}
+/**
+ * The keys a push for this target ROUTES: its two destinations, unioned.
+ *
+ * The complement of everything above, stated positively, because one consumer
+ * needs the question the other way round. `env init --target staging` renders
+ * a file whose whole purpose is to be filled in and pushed, so the keys it
+ * should contain are exactly the keys a push for that target would carry
+ * somewhere. Derived from `ignoredFor()` rather than re-listed, so the file
+ * and the upload cannot disagree about which target a key belongs to. The
+ * generated file used to be byte-identical for all three targets, which put
+ * the apply-tier credentials in `.env.staging` where `ignoredFor()` refuses
+ * them. The same derivation shrank `env init --target preflight` from 45 keys
+ * to the narrowed ones: the exclusion is stated once, in `ignoredFor()`, and
+ * the rendered file follows for free.
+ *
+ * The `neverStore()` subtraction is unreachable today (a never-store key is
+ * neither `secrecy: "secret"` nor `"public"`, so neither selector returns it)
+ * and is written down anyway: this set decides what gets an assignable line in
+ * a file people fill in, and `BWS_ACCESS_TOKEN=` is the one line that must
+ * never appear in one.
+ */
+export function keysRoutedTo(target) {
+    assertRegistryLoaded();
+    const skip = ignoredFor(target);
+    const refuse = neverStore();
+    return new Set([...getEnvSync().storableKeys(), ...getEnvSync().variableKeys()].filter((key) => !skip.has(key) && !refuse.has(key)));
+}
+/**
+ * Signed at deploy time; the deploy target holds the only copy.
+ *
+ * Passed to `audit` separately from `ignoredFor()` even though it is a subset,
+ * because the audit needs the distinction: an ignored key is uninteresting
+ * everywhere, whereas a minted one is CORRECT on Cloudflare (which is what
+ * stops it being reported as an orphan and pruned) and WRONG in Bitwarden or
+ * GitHub.
+ */
+export function minted() {
+    assertRegistryLoaded();
+    return new Set(getEnvSync().mintedKeys());
+}
+/**
+ * Whether the file's value is still, exactly, the derivation the registry
+ * declares for this key.
+ *
+ * ⚠️ EXACT IDENTITY, and nothing looser. Not "looks like a formula", not
+ * "contains a `$`", not "starts with the derivation". String equality with
+ * what `getEnvSync().derivationOf()` returns. Everything else somebody could type is
+ * deliberate input: a real value, obviously, but also a DIFFERENT derivation,
+ * which is how a target says its value is built from something else. Widening
+ * this predicate by one inch silently drops a credential on the floor: the
+ * push reports success, the environment is missing a secret, and `env audit`
+ * agrees with the file it came from.
+ *
+ * `some` rather than `every` across duplicate declarations, matching
+ * `keysWhere()`: the safe reading is that a value matching ANY declared
+ * derivation is that derivation. It cannot discard a credential either way,
+ * since no usable credential is byte-identical to `$BASE_URL/auth/callback`.
+ */
+function isDeclaredDerivation(entries, value) {
+    // `getEnvSync().derivationOf()` returns null for everything that is not a derivation, and
+    // `value` is non-empty by the time this is called, so null never matches.
+    return entries.some((entry) => getEnvSync().derivationOf(entry.meta) === value);
+}
+/**
+ * `entries` is the ACTIVE assignments in the local `.env`, in file order.
+ *
+ * A commented-out line is not an assignment and never reaches here, which is
+ * what makes commenting-out a safe way to retire a key.
+ */
+export function selectForPush(entries, target) {
+    const skip = ignoredFor(target);
+    const refuse = neverStore();
+    const pushable = pushableVariables();
+    const declared = getEnvSync().variables();
+    const push = new Map();
+    const publicValues = new Map();
+    const refused = [];
+    const unknown = [];
+    const derived = [];
+    for (const [key, value] of entries) {
+        // Refusal is checked FIRST and independently of the value. A blank
+        // BWS_ACCESS_TOKEN is still a line somebody is about to fill in.
+        if (refuse.has(key)) {
+            if (value !== "")
+                refused.push(key);
+            continue;
+        }
+        // Undeclared means unclassified. Nothing says whether this is a secret,
+        // whose it is, or where it routes, so it does not leave the machine.
+        // Reported even when empty, because the problem is the missing
+        // declaration, not the value.
+        if (!declared.has(key)) {
+            unknown.push(key);
+            continue;
+        }
+        // Checked BEFORE the variable branch, so the exclusions about *this
+        // target* keep winning: an apply-only key outside production, or a minted
+        // one anywhere, is skipped whatever its secrecy. The two sets are disjoint
+        // today, and this ordering is what keeps a future overlap failing closed
+        // rather than open.
+        if (skip.has(key))
+            continue;
+        // An empty secret reads as "configured" to every consumer that checks for
+        // presence, which is worse than an absent one. Equally true of a variable:
+        // an empty `PROJECT_REF` builds a URL pointing at nothing.
+        if (value === "")
+            continue;
+        // Still the declared derivation, so there is no VALUE here, only the
+        // shape, which the registry already holds. Storing it is harmful rather
+        // than merely redundant: a stored value BEATS the registry when the
+        // deploy composes an env file, so the literal `https://$PROJECT_REF...`
+        // arrives as `from: "variable"`, is never expanded (only `from: "derived"`
+        // is), and is written single-quoted, which dotenvx takes as fully literal.
+        // The deployed app then resolves a host called `$PROJECT_REF.supabase.co`
+        // while `env audit` reports NO DRIFT, because the stored value does match
+        // the file.
+        //
+        // ⚠️ NOT expanded here and sent, which is the tempting alternative. That
+        // would make GitHub the source of truth for these eight shapes: changing
+        // `REST_URL` from `/rest/v1` to `/rest/v2` in the registry would then never
+        // take effect anywhere. Skipping is what lets the deploy's `fromRegistry()`
+        // run and expand at compose time.
+        if (isDeclaredDerivation(declared.get(key), value)) {
+            derived.push(key);
+            continue;
+        }
+        // Public and per-environment: a GitHub *variable*, not a secret. Routed
+        // here rather than dropped, because the value still has to reach CI, and
+        // still belongs in Bitwarden so that `pull` rebuilds a COMPLETE env file
+        // rather than the secret half of one.
+        if (pushable.has(key)) {
+            publicValues.set(key, value);
+            continue;
+        }
+        push.set(key, value);
+    }
+    return { push, variables: publicValues, refused, unknown, derived };
+}

package/dist/environment.d.ts

@@ -0,0 +1,92 @@
+import type { Condition } from "./commands.js";
+import { findRepoRoot } from "./repo/root.js";
+/**
+ * The repo root, which is where `supabase/config.toml` and `.env` live.
+ *
+ * Used to be a fixed `join(import.meta.dirname, "..", "..", "..")` — that
+ * only worked because devtools lived inside the repo it operated on. Now
+ * published as its own package, every former reader of that constant calls
+ * `findRepoRoot()` (re-exported here for callers that already import from
+ * this module) — see `repo/root.ts` for the marker and why it is a lazy,
+ * throwing function rather than a constant.
+ */
+export { findRepoRoot };
+/** A fact that may be unreadable. See the header: unknown is not "no". */
+export type Known = "yes" | "no" | "unknown";
+export interface Environment {
+    /** The Docker daemon answers. Without it there is no Supabase on this machine. */
+    docker: Known;
+    /** The local Supabase stack's containers are up. */
+    stack: Known;
+    /** The root `.env` exists, so `setup` has been run at least once. */
+    envFile: Known;
+}
+/**
+ * The environment that adapts nothing.
+ *
+ * What the tests use, and what any caller that would rather not probe can
+ * pass. Because nothing is hidden or flagged on `"unknown"`, this is exactly
+ * the pre-adaptation menu, which makes it a safe fallback rather than a
+ * special case to remember.
+ */
+export declare const UNKNOWN_ENVIRONMENT: Environment;
+/**
+ * Reads the machine.
+ *
+ * Two subprocesses at worst, one when Docker is down, plus an `existsSync`.
+ * The budget is "cheaper than the first keystroke", because this runs before
+ * the wizard's first screen and anything slower would be paid on every
+ * invocation to save a few of them later.
+ *
+ * It does NOT call `supabase status`, which is the authoritative answer but
+ * 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.
+ */
+export declare function probeEnvironment(execute?: (file: string, args: string[]) => string | null): Environment;
+/**
+ * Whether a `Condition` from the command tree currently holds.
+ *
+ * The tree declares conditions as strings so that it stays inert data the docs
+ * build can render (see `commands.ts`); this is the one place that knows what
+ * they mean. `"unknown"` propagates rather than collapsing to false, and both
+ * callers below read it as "do nothing".
+ */
+export declare function holds(condition: Condition, env: Environment): Known;
+/**
+ * Whether the wizard should offer this command at all.
+ *
+ * False only for a command whose `when` is definitively unmet: `stop`
+ * against a stack that is already stopped. This is reserved for commands that
+ * would be *meaningless*, never merely inconvenient: one that would fail with
+ * a good error message stays in the menu and carries `needs` instead, because
+ * a contributor who cannot find a command they know exists is worse off than
+ * one who runs it and is told why it did not work.
+ *
+ * Hiding is a wizard-only decision. `--help` still lists these, the dispatcher
+ * still accepts them, and the generated reference still documents them. The
+ * menu is a guide to right now, and those three are the reference.
+ */
+export declare function isOffered(node: {
+    when?: Condition;
+}, env: Environment): boolean;
+/**
+ * Why this command will not work right now, or `null` if nothing is in the way.
+ *
+ * Appended to the entry's hint, so the menu says "needs Docker, which is not
+ * running" on the line itself, rather than after the reader has chosen it and
+ * waited for a connection attempt to fail.
+ */
+export declare function blockedBecause(node: {
+    needs?: Condition;
+}, env: Environment): string | null;
+/**
+ * The three facts, as the wizard's opening note and as `status --local`.
+ *
+ * Printed before the first question rather than discovered through failures:
+ * "Docker running  no" at the top of the screen is the whole explanation for
+ * why the database commands below it are flagged, and it costs one glance.
+ */
+export declare function describeEnvironment(env: Environment): string;

package/dist/environment.js

@@ -0,0 +1,206 @@
+/**
+ * What this machine currently is, read once before the menu draws itself.
+ *
+ * The wizard used to offer the same commands to everyone: someone whose Docker
+ * daemon was not running was invited to reset a database that could not
+ * answer, and someone whose stack was already up had no way to stop it at all,
+ * because "stop" was not in the tree. Both are the same bug. The menu
+ * described the CLI rather than the situation.
+ *
+ * So this reads three facts and `menu.ts` adapts to them. The facts are few
+ * and cheap on purpose; see `probeEnvironment` for the budget and why.
+ *
+ * ## Unknown is not "no"
+ *
+ * Every probe can come back `"unknown"`, and that is what a failed probe
+ * reports rather than guessing. Nothing is hidden or flagged on `"unknown"`: a
+ * machine this cannot read gets the full menu, exactly as before. A tool that
+ * hides a command because a `docker ps` timed out is worse than one that never
+ * adapted at all, because the command it hides is the one you were looking
+ * for.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { findRepoRoot } from "./repo/root.js";
+/**
+ * The repo root, which is where `supabase/config.toml` and `.env` live.
+ *
+ * Used to be a fixed `join(import.meta.dirname, "..", "..", "..")` — that
+ * only worked because devtools lived inside the repo it operated on. Now
+ * published as its own package, every former reader of that constant calls
+ * `findRepoRoot()` (re-exported here for callers that already import from
+ * this module) — see `repo/root.ts` for the marker and why it is a lazy,
+ * throwing function rather than a constant.
+ */
+export { findRepoRoot };
+/**
+ * The environment that adapts nothing.
+ *
+ * What the tests use, and what any caller that would rather not probe can
+ * pass. Because nothing is hidden or flagged on `"unknown"`, this is exactly
+ * the pre-adaptation menu, which makes it a safe fallback rather than a
+ * special case to remember.
+ */
+export const UNKNOWN_ENVIRONMENT = {
+    docker: "unknown",
+    stack: "unknown",
+    envFile: "unknown",
+};
+// ── Probes ───────────────────────────────────────────────────────────────────
+/**
+ * Every probe is bounded, silent, and total.
+ *
+ * `timeout` because a Docker daemon that is starting up (or a VM that has just
+ * been resumed) accepts the connection and then never answers, and the failure
+ * that produces is a menu that hangs before printing anything, with no output
+ * to explain what it is waiting for.
+ */
+function run(file, args) {
+    try {
+        return execFileSync(file, args, {
+            cwd: findRepoRoot(),
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 3000,
+        });
+    }
+    catch {
+        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.
+ *
+ * Two subprocesses at worst, one when Docker is down, plus an `existsSync`.
+ * The budget is "cheaper than the first keystroke", because this runs before
+ * the wizard's first screen and anything slower would be paid on every
+ * invocation to save a few of them later.
+ *
+ * It does NOT call `supabase status`, which is the authoritative answer but
+ * 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.
+ */
+export function probeEnvironment(execute = run) {
+    const envFile = existsSync(join(findRepoRoot(), ".env")) ? "yes" : "no";
+    // `docker info` rather than `docker version`: version answers from the
+    // client alone, so it reports success against a daemon that is not running.
+    const docker = execute("docker", ["info"]) === null ? "no" : "yes";
+    // A stack cannot be up without a daemon to hold it, so this needs no second
+    // subprocess to say "no", and asking anyway on a machine with no Docker
+    // installed would pay the whole timeout for an answer already in hand.
+    if (docker === "no")
+        return { docker, stack: "no", envFile };
+    const names = execute("docker", ["ps", "--format", "{{.Names}}"]);
+    if (names === null)
+        return { docker, stack: "unknown", envFile };
+    const prefix = containerPrefix();
+    const running = names
+        .split("\n")
+        .some((name) => name.trim().startsWith(prefix));
+    return { docker, stack: running ? "yes" : "no", envFile };
+}
+// ── Conditions ───────────────────────────────────────────────────────────────
+/**
+ * Whether a `Condition` from the command tree currently holds.
+ *
+ * The tree declares conditions as strings so that it stays inert data the docs
+ * build can render (see `commands.ts`); this is the one place that knows what
+ * they mean. `"unknown"` propagates rather than collapsing to false, and both
+ * callers below read it as "do nothing".
+ */
+export function holds(condition, env) {
+    switch (condition) {
+        case "docker":
+            return env.docker;
+        case "instance-running":
+            return env.stack;
+        case "instance-stopped":
+            // The negation of an unreadable fact is still unreadable.
+            if (env.stack === "unknown")
+                return "unknown";
+            return env.stack === "no" ? "yes" : "no";
+    }
+}
+/** What `needs` renders as when it does not hold. Kept short: it is a hint. */
+const UNMET = {
+    docker: "Docker is not running",
+    "instance-running": "Supabase is not running on this machine",
+    "instance-stopped": "Supabase is already running on this machine",
+};
+/**
+ * Whether the wizard should offer this command at all.
+ *
+ * False only for a command whose `when` is definitively unmet: `stop`
+ * against a stack that is already stopped. This is reserved for commands that
+ * would be *meaningless*, never merely inconvenient: one that would fail with
+ * a good error message stays in the menu and carries `needs` instead, because
+ * a contributor who cannot find a command they know exists is worse off than
+ * one who runs it and is told why it did not work.
+ *
+ * Hiding is a wizard-only decision. `--help` still lists these, the dispatcher
+ * still accepts them, and the generated reference still documents them. The
+ * menu is a guide to right now, and those three are the reference.
+ */
+export function isOffered(node, env) {
+    return node.when === undefined || holds(node.when, env) !== "no";
+}
+/**
+ * Why this command will not work right now, or `null` if nothing is in the way.
+ *
+ * Appended to the entry's hint, so the menu says "needs Docker, which is not
+ * running" on the line itself, rather than after the reader has chosen it and
+ * waited for a connection attempt to fail.
+ */
+export function blockedBecause(node, env) {
+    if (!node.needs)
+        return null;
+    return holds(node.needs, env) === "no" ? UNMET[node.needs] : null;
+}
+// ── Reporting ────────────────────────────────────────────────────────────────
+const LABELS = {
+    yes: "yes",
+    no: "no",
+    unknown: "could not tell",
+};
+/**
+ * The three facts, as the wizard's opening note and as `status --local`.
+ *
+ * Printed before the first question rather than discovered through failures:
+ * "Docker running  no" at the top of the screen is the whole explanation for
+ * why the database commands below it are flagged, and it costs one glance.
+ */
+export function describeEnvironment(env) {
+    return [
+        `Docker running   ${LABELS[env.docker]}`,
+        `Local stack up   ${LABELS[env.stack]}`,
+        `.env present     ${LABELS[env.envFile]}`,
+    ].join("\n");
+}

package/dist/fingerprint.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A fingerprint, for showing that a value changed without showing the value.
+ *
+ * Length plus first and last character. Enough to tell "I pasted the wrong
+ * token" from "the token rotated", and not enough to reconstruct anything. The
+ * whole point of these commands is to move secrets without printing them, and a
+ * diff that renders values would undo that in the one place people paste output
+ * into a chat window.
+ */
+export declare function fingerprint(value: string): string;

package/dist/fingerprint.js

@@ -0,0 +1,18 @@
+/**
+ * A fingerprint, for showing that a value changed without showing the value.
+ *
+ * Length plus first and last character. Enough to tell "I pasted the wrong
+ * token" from "the token rotated", and not enough to reconstruct anything. The
+ * whole point of these commands is to move secrets without printing them, and a
+ * diff that renders values would undo that in the one place people paste output
+ * into a chat window.
+ */
+export function fingerprint(value) {
+    if (value === "")
+        return "empty";
+    // Short values would be largely reconstructable from first/last, so they get
+    // no description at all.
+    if (value.length <= 4)
+        return `${value.length} chars`;
+    return `${value.length} chars, ${value[0]}…${value[value.length - 1]}`;
+}

package/dist/gen/campus-map.d.ts

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