@devdogsuga/devtools 0.1.12 → 0.1.14

package/dist/launch.js

@@ -16,9 +16,27 @@
  * This module settles the tier ONCE, before any command's imports — let alone
  * its code — run, using the shared policy in `@devdogsuga/env/session`. By
  * the time `cli.ts` is imported, `process.env.DEPLOY_ENV` already names the
- * tier and its env files are already loaded, so `cli.ts`, `menu.ts` and every
- * runner underneath them just read `process.env` like any other command would
- * under `with-env` — this module IS the replacement for `with-env`'s job.
+ * tier, so `cli.ts`, `menu.ts` and every runner underneath them just read
+ * `process.env.DEPLOY_ENV`/`DEV_DB` like any other command would under
+ * `with-env` — this module IS the replacement for `with-env`'s job.
+ *
+ * ## Entering the environment: at launch, or deferred to the menu
+ *
+ * "Settling the tier" and "entering it" (loading `.env.<tier>` and its
+ * `DEV_DB` overlay onto `process.env`, via `@devdogsuga/env/session`'s
+ * `enterEnvironment`) are two different steps, and a MENU invocation —
+ * a bare `pnpm devtools`, or a bare group like `pnpm devtools db` resumed
+ * through `bareGroupStartPath` — only gets the first one here. Entering holds
+ * the env files hostage to whatever was true at the moment this process
+ * started; a contributor who starts the local stack in another terminal
+ * while still choosing from the wizard would otherwise have that missed
+ * entirely. So for a menu invocation this module resolves the tier, exports
+ * `DEPLOY_ENV`/`DEV_DB` directly (skipping `enterEnvironment` itself), and
+ * registers `env-entry.ts`'s menu hook instead of entering — `menu.ts`'s
+ * `runMenu` calls it right before dispatching the ONE command the reader
+ * chose, so the env files loaded are current as of that moment, not this
+ * one. A typed command line still enters right here, unchanged: there is no
+ * wizard delay to protect it from.
  *
  * ## `--tier`, a global flag
  *
@@ -30,10 +48,13 @@
  * already been made, and `resolveTier` (see `tier.ts`) falls back to reading
  * it off `process.env.DEPLOY_ENV` rather than asking again.
  */
-import { confirm, select } from "@clack/prompts";
+import { select } from "@clack/prompts";
 import { findCommand } from "./commands.js";
+import { enterSessionEnvironment, realEnvEntryDeps, setMenuEnvHook, } from "./env-entry.js";
+import { bareGroupStartPath } from "./menu.js";
 import { discoverRepoRoot, findRepoRoot, RepoNotFoundError } from "./repo/root.js";
 import { loadEnvLoad, loadEnvSession } from "./repo/peers.js";
+import { captureDevtoolsError, initDevtoolsTelemetry } from "./telemetry.js";
 import { errorMessage, unwrap } from "./ui.js";
 /**
  * Pulls a global `--tier <t>` out of `argv`, wherever it sits, leaving every
@@ -104,11 +125,14 @@ async function dispatch(argv) {
     }
     catch (err) {
         process.stderr.write(`devtools: ${errorMessage(err)}\n`);
+        // Report BEFORE exiting — see `captureDevtoolsError`'s header.
+        await captureDevtoolsError(err);
         process.exit(1);
     }
 }
 /**
- * Resolves the session's deploy tier, enters it, and hands off to `cli.ts`.
+ * Resolves the session's deploy tier, enters it (or defers entry to the
+ * menu — see this file's header), and hands off to `cli.ts`.
  *
  * Exits the process directly on a refusal from `resolveSessionTier` — there
  * is no command dispatched yet for a caller to fall back to, so there is
@@ -116,6 +140,20 @@ async function dispatch(argv) {
  */
 export async function launch(argv) {
     const { explicit, rest } = stripTierFlag(argv);
+    // Here rather than only in `cli.ts`'s `main()`, so a failure while
+    // resolving or entering the tier below is reported too. `main()`'s own
+    // call is then a no-op (`initDevtoolsTelemetry` is idempotent) and this
+    // tag, computed from the same argv `main()` receives, stands.
+    initDevtoolsTelemetry(rest[0] ?? "menu");
+    // Same test `cli.ts`'s own `main()` uses to decide whether a bare command
+    // group resumes the wizard instead of dispatching — computed here too so
+    // this function can decide, before resolving anything, whether entry gets
+    // deferred to `menu.ts`'s hook. A non-TTY caller never resumes the wizard
+    // (see `bareGroupStartPath`'s own doc), so `rest.length === 0` is the only
+    // menu shape it can hit — mirroring `main()`'s own `process.stdin.isTTY ?
+    // bareGroupStartPath(argv) : null`.
+    const isMenuInvocation = rest.length === 0 ||
+        (process.stdin.isTTY === true && bareGroupStartPath(rest) !== null);
     // `--help`/`-h` bypasses tier resolution entirely, BEFORE it can refuse.
     // `cli.ts`'s own `main()` already answers these with no env in play (see
     // its header comment); resolving a tier first anyway meant `pnpm devtools
@@ -133,6 +171,24 @@ export async function launch(argv) {
     }
     const envLoad = await loadEnvLoad();
     const envSession = await loadEnvSession();
+    // Records, once, which keys THIS shell actually exported before devtools
+    // touched anything — the fix for the staleness bug `enterEnvironment`'s own
+    // `override: false` comment below describes. `Object.keys(process.env)` at
+    // this exact point is still a faithful snapshot of the calling shell: the
+    // imports above load code, not env; nothing before this line has mutated
+    // `process.env`. See `SHELL_KEYS_ENV` (`@devdogsuga/env/load`) for how
+    // `loadEnvironment` narrows "a shell var beats the file" to just this list.
+    //
+    // Guarded on absence so a NESTED devtools launcher (one `pnpm devtools`
+    // command spawning another, e.g. the `db start` offer below re-dispatching
+    // through `dispatch()`) keeps the ORIGINAL list instead of recomputing one:
+    // by the time a nested launcher's `launch()` runs, `process.env` already
+    // holds this session's entered values, not the outer shell's, and
+    // recomputing from it would misclassify every one of them as a genuine
+    // shell export — the exact bug this marker exists to prevent, one layer in.
+    if (process.env[envLoad.SHELL_KEYS_ENV] === undefined) {
+        process.env[envLoad.SHELL_KEYS_ENV] = Object.keys(process.env).join(",");
+    }
     let tier;
     let devDatabase;
     if (rest[0] === "setup" || rest[0] === "completions" || isEnvFreeCommand(rest)) {
@@ -207,116 +263,23 @@ export async function launch(argv) {
         tier = resolution.tier;
         devDatabase = resolution.devDatabase;
     }
-    // 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` — a fresh process, so an already-exported shell
-        // variable beats the file the same way `with-env` always let it, rather
-        // than a stale `.env.<tier>` value silently winning over what the caller
-        // just set for this one invocation.
-        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`);
-            // Rather than making the contributor stop, run `db start`, and re-run
-            // whatever they meant, offer to bring the stack up right here and then
-            // carry on with their original command. Only on a TTY (there is no one
-            // to answer otherwise), 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. The bare top menu is likewise left to its own
-            // Database → start entry.
-            const lifecycle = rest[0] === "db" &&
-                (rest[1] === "start" || rest[1] === "stop" || rest[1] === "restart");
-            if (process.stdin.isTTY === true && rest.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 we dispatch 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) {
-                        await dispatch(rest);
-                        return;
-                    }
-                    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 the bare menu
-            // (the road to `db start`) 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 (rest.length !== 0 && rest[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);
-            await dispatch(rest);
-            return;
-        }
-        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);
-        }
+    if (isMenuInvocation) {
+        // Export the decision, not the files: `DEPLOY_ENV`/`DEV_DB` name the
+        // session the same way `enterEnvironment` would set them, but loading
+        // `.env.<tier>` itself — and everything `enterSessionEnvironment` does
+        // around that, including the offline-stack offer — waits for a command to
+        // actually be chosen. See this file's header.
+        process.env.DEPLOY_ENV = tier;
+        if (devDatabase !== undefined)
+            process.env.DEV_DB = devDatabase;
+        setMenuEnvHook((commandArgv, dispatchCommand) => enterSessionEnvironment(tier, devDatabase, commandArgv, realEnvEntryDeps(envLoad, envSession), dispatchCommand));
+        await dispatch(rest);
+        return;
     }
     // Caught here rather than left to `bin/devtools.mjs`'s `child.on("error",
     // …)`, which only ever sees a spawn failure, never a rejection thrown
     // inside this process.
-    await dispatch(rest);
+    await enterSessionEnvironment(tier, devDatabase, rest, realEnvEntryDeps(envLoad, envSession), () => dispatch(rest));
 }
 // `bin/devtools.mjs` runs this file directly through tsx — `tsx
 // --conditions=devdogs-source src/launch.ts <argv…>` — so `process.argv`

package/dist/menu.d.ts

@@ -20,11 +20,23 @@ export declare function bareGroupStartPath(argv: readonly string[]): string[] |
  * `options.startPath`, from `bareGroupStartPath`, skips straight to that
  * node's subcommand screen — see `walk`'s `startPath` branch.
  *
- * The deploy tier is NOT asked here any more. `src/launch.ts` resolves and
- * enters it before `cli.ts` — and therefore this module — is even imported,
- * so by the time the wizard opens the whole session is already running under
- * it, exactly as if `--tier` had been typed. Recording it for the "run it
- * directly next time" line only needs to read `process.env.DEPLOY_ENV` back.
+ * The deploy tier is NOT asked here any more. `src/launch.ts` resolves it
+ * before `cli.ts` — and therefore this module — is even imported, and
+ * exports `DEPLOY_ENV`/`DEV_DB` right away, so by the time the wizard opens
+ * `process.env` already names the session exactly as if `--tier` had been
+ * typed. Recording it for the "run it directly next time" line only needs to
+ * read `process.env.DEPLOY_ENV` back.
+ *
+ * Entering that tier — loading its `.env.<tier>` file onto `process.env` —
+ * is what's deferred: `launch.ts` registers a hook (`env-entry.ts`'s
+ * `setMenuEnvHook`) instead of entering up front, so whatever changed while
+ * the reader was still walking the menu (the local stack coming up in
+ * another terminal, `.env.generated` being rewritten) is picked up rather
+ * than missed. `takeMenuEnvHook()` below runs it right before the chosen
+ * command dispatches — the ONE place in a menu walk an env value is ever
+ * actually read. `undefined` (no hook registered — a typed command entered
+ * already, or a test drives `runMenu` directly) just dispatches straight
+ * through, unchanged from before this existed.
  */
 export declare function runMenu(dispatch: (argv: string[]) => Promise<string | null>, env?: Environment, options?: {
     startPath?: string[];

package/dist/menu.js

@@ -19,6 +19,7 @@
 import { confirm, note, select, text } from "@clack/prompts";
 import { positionals } from "./args.js";
 import { findCommand, GROUPS, SCOPES, } from "./commands.js";
+import { takeMenuEnvHook } from "./env-entry.js";
 import { blockedBecause, describeEnvironment, isOffered, probeEnvironment, } from "./environment.js";
 import { beginInvocation, recordEnteredTier } from "./invocation.js";
 import { unwrap } from "./ui.js";
@@ -41,10 +42,13 @@ function offered(nodes, env) {
 /**
  * The line beside a name, with whatever is standing in this command's way.
  *
- * The reader learns that `roundtrip` needs a stack that is not up *before*
- * choosing it, instead of after a spinner and a connection error. The command
- * stays selectable: the check is a probe, the probe can be wrong, and the
- * command's own failure message is the authority on whether it can run.
+ * The reader learns a command needs something standing in its way *before*
+ * choosing it, instead of after a spinner and a connection error — `db
+ * start`'s `when: "instance-stopped"` is the one still in the tree today. The
+ * command stays selectable when it merely `needs` rather than requires the
+ * condition to be shown at all: the check is a probe, the probe can be
+ * wrong, and the command's own failure message is the authority on whether
+ * it can run.
  */
 function hintFor(node, env) {
     const base = node.hint ?? node.summary;
@@ -115,8 +119,7 @@ async function pickSubcommand(node, env) {
  *
  * An empty array is a real answer, not a failure: a declined confirm adds no
  * flag, and a blank optional text means "let the command decide", which is
- * how `--db-url` falls back to `.env.production` and `--base-url` falls
- * through to the OAuth wizard's own prompt.
+ * how `--db-url` falls back to `.env.production`.
  */
 async function askOption(option) {
     const prompt = option.prompt;
@@ -241,11 +244,23 @@ export function bareGroupStartPath(argv) {
  * `options.startPath`, from `bareGroupStartPath`, skips straight to that
  * node's subcommand screen — see `walk`'s `startPath` branch.
  *
- * The deploy tier is NOT asked here any more. `src/launch.ts` resolves and
- * enters it before `cli.ts` — and therefore this module — is even imported,
- * so by the time the wizard opens the whole session is already running under
- * it, exactly as if `--tier` had been typed. Recording it for the "run it
- * directly next time" line only needs to read `process.env.DEPLOY_ENV` back.
+ * The deploy tier is NOT asked here any more. `src/launch.ts` resolves it
+ * before `cli.ts` — and therefore this module — is even imported, and
+ * exports `DEPLOY_ENV`/`DEV_DB` right away, so by the time the wizard opens
+ * `process.env` already names the session exactly as if `--tier` had been
+ * typed. Recording it for the "run it directly next time" line only needs to
+ * read `process.env.DEPLOY_ENV` back.
+ *
+ * Entering that tier — loading its `.env.<tier>` file onto `process.env` —
+ * is what's deferred: `launch.ts` registers a hook (`env-entry.ts`'s
+ * `setMenuEnvHook`) instead of entering up front, so whatever changed while
+ * the reader was still walking the menu (the local stack coming up in
+ * another terminal, `.env.generated` being rewritten) is picked up rather
+ * than missed. `takeMenuEnvHook()` below runs it right before the chosen
+ * command dispatches — the ONE place in a menu walk an env value is ever
+ * actually read. `undefined` (no hook registered — a typed command entered
+ * already, or a test drives `runMenu` directly) just dispatches straight
+ * through, unchanged from before this existed.
  */
 export async function runMenu(dispatch, env = probeEnvironment(), options = {}) {
     // Before the first question, not after a failure. Three lines saying what
@@ -273,5 +288,13 @@ export async function runMenu(dispatch, env = probeEnvironment(), options = {})
     recordEnteredTier(enteredTier === "development" && (devDb === "local" || devDb === "remote")
         ? `development:${devDb}`
         : enteredTier);
+    // The deferred entry, if `launch.ts` registered one — see this function's
+    // header. Read-and-cleared in one call so a nested launcher (this same
+    // command re-dispatching through its own `launch()`, e.g. `db start`'s
+    // offline-stack offer) never inherits a hook meant for this walk.
+    const enterEnvironment = takeMenuEnvHook();
+    if (enterEnvironment) {
+        return enterEnvironment(chosen.argv, () => dispatch(chosen.argv));
+    }
     return dispatch(chosen.argv);
 }

package/dist/moderation.d.ts

@@ -1,31 +1,28 @@
 /**
  * Does my app's moderation integration actually work?
  *
- * Two checks, and the second is the one that matters.
- *
  * `conformance()` asks the database what it derived from your schema: is the
  * table addressable, can an author be attributed, does quarantine have a column
  * to write to, can a client still write that column. All of it is answerable
  * from the catalog, and `platform.conformance_check()` does the answering.
  *
- * `quarantineRoundTrip()` answers the question the catalog cannot: *does
- * quarantine do anything?* Quarantine is the only moderation outcome whose
- * effect lives in the app's own policies rather than the platform's, so it is
- * the only one that can be wired up wrong while everything appears to work.
- * The platform records the decision, sets the column, and has no way to notice
- * nobody reads it. The only proof is to file, resolve, and then look.
- *
- * It runs against `platform.profile`, where quarantine means FREEZE rather than
- * hide: the display name is reset to the member's name of record and they lose
- * the ability to change it back. A profile cannot be hidden: rosters, teams
- * and standings all render the name, and the row is own-row-only over PostgREST
- * anyway, so there is nobody to hide it from. See
- * 20260808000000_platform_profile_moderation.sql.
+ * The end-to-end round trip that used to live here (`quarantineRoundTrip`,
+ * `moderation roundtrip`) is gone: the app repo's own CI covers that path —
+ * file, quarantine, and check the freeze — more thoroughly than a devtools
+ * command driven by hand ever did, and keeping two implementations of the
+ * same assertion around was a drift risk with no offsetting benefit.
  *
- * Both run as seeded personas over PostgREST rather than as `postgres` over
- * SQL, because RLS is the thing under test and a superuser bypasses it.
+ * Both `conformance()` and `catalog.ts`'s `readCatalog()` need to run as a
+ * moderator, subject to the same RLS and `canModerate` checks a real one
+ * would hit, rather than as `postgres` bypassing them. `withTemporaryModerator`
+ * below is what supplies that account: a throwaway user, created through the
+ * admin API and deleted again in a `finally`, rather than the seeded
+ * `moderator@devdogs.test` persona this package used to sign in as — that
+ * persona came from `supabase/seed/development/02_moderation.sql`, which only
+ * ever ran on a local reset and is going away along with the rest of
+ * `seed/development/` (see `persona.ts`'s header for the replacement).
  */
-import { type Instance } from "./instance.js";
+import { type DevtoolsClient, type Instance } from "./instance.js";
 import type { CheckResult } from "./ui.js";
 interface ConformanceType {
     contentType: string;
@@ -33,30 +30,41 @@ interface ConformanceType {
     tableName: string;
     checks: CheckResult[];
 }
-/** Runs `platform.conformance_check()` as the seeded moderator. */
-export declare function conformance(instance: Instance, appSlug: string): Promise<ConformanceType[]>;
-/** The apps that have anything to check, for the picker. */
-export declare function listApps(instance: Instance): Promise<string[]>;
-export interface RoundTripStep {
-    name: string;
-    ok: boolean;
-    detail: string;
-}
+/** Runs `platform.conformance_check()` as the given moderator client. */
+export declare function conformance(client: DevtoolsClient, appSlug: string): Promise<ConformanceType[]>;
+/**
+ * The role every devtools-granted moderator holds — `moderation check`'s
+ * throwaway account and `persona moderator`'s longer-lived one alike, so
+ * both resolve to the SAME role row rather than each accumulating their own.
+ *
+ * Reuses the id `supabase/seed/development/02_moderation.sql` used to seed
+ * this same role under, on the theory that an existing local database that
+ * still has that seeded row should be upserted into agreement rather than
+ * given a second, redundant "Moderator" role.
+ */
+export declare const MODERATOR_ROLE_ID = "00000000-0000-4000-9000-000000000001";
 /**
- * Files a report against a profile, resolves it with quarantine, and checks
- * that the freeze and the name reset both landed.
+ * Creates (or updates) the Moderator role definition, and returns its id.
  *
- * The subject is a THROWAWAY member created for the run, not one of the seeded
- * personas, and that is not squeamishness about touching fixtures.
- * `file_report` corroborates an existing open report rather than filing a
- * second one against the same content, and the seeds ship exactly such a report
- * against the author persona's profile. Reusing it would make this function's
- * first step silently become "add a corroboration", and every assertion after
- * it would be reading the seed's decision instead of its own.
+ * `canModerate: true` and nothing else — not Root, not any of the other
+ * `roles` permission columns — mirroring exactly what the seed persona held.
+ * Idempotent (`upsert`) so repeated calls, from either caller above, never
+ * race each other into two rows or fail on the second one.
+ */
+export declare function ensureModeratorRole(admin: DevtoolsClient): Promise<string>;
+/** Grants the Moderator role to `userId`, creating the role definition first
+ * if this is the first account to need it. */
+export declare function grantModerator(admin: DevtoolsClient, userId: string): Promise<void>;
+/**
+ * Runs `fn` with a client signed in as a throwaway moderator, created for
+ * this call and deleted again in a `finally` whether or not `fn` throws.
  *
- * Everything it creates, it deletes, including on the failure paths, which is
- * why the teardown is in a `finally`. A contributor running this twice should
- * get the same answer the second time.
+ * The admin API's `createUser` bypasses the app's `before_user_created`
+ * uga.edu hook (that hook only runs on the sign-up/OTP paths a real user
+ * takes, not the service-role admin API), which is why a `@persona.test`
+ * address works here at all — see `persona.ts`'s header for the same note
+ * in more detail, since that is the command a contributor is more likely to
+ * read first.
  */
-export declare function quarantineRoundTrip(instance: Instance): Promise<RoundTripStep[]>;
+export declare function withTemporaryModerator<T>(instance: Instance, fn: (client: DevtoolsClient) => Promise<T>): Promise<T>;
 export {};