@devdogsuga/devtools 0.1.0

package/dist/setup.js

@@ -0,0 +1,152 @@
+/**
+ * One-command onboarding, the first thing a new contributor runs.
+ *
+ * Checks prerequisites (warns, never hard-fails on optional tools), seeds the
+ * root `.env`, and points at the database and OAuth steps. Deliberately does NOT run remote
+ * Supabase commands: linking a remote project needs credentials that are not
+ * in `.env` yet.
+ *
+ * Was `scripts/setup.ts` at the repo root, resolving paths from
+ * `process.cwd()`, so it only worked when invoked from the root. Same class of
+ * bug that made the Supabase CLI look for `supabase_db_platform`. It resolves
+ * from `findRepoRoot()` now and works from anywhere.
+ */
+import { execSync } from "node:child_process";
+import { existsSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { log, note } from "@clack/prompts";
+import { loadRegistry } from "./env/discovery.js";
+import { renderInit, resolveSections } from "./env/example.js";
+import { discoverRepoRoot } from "./repo/root.js";
+function has(cmd) {
+    try {
+        execSync(cmd, { stdio: ["ignore", "pipe", "ignore"] });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function runSetup() {
+    const checks = [];
+    // ── Prerequisites ──────────────────────────────────────────────────────────
+    //
+    // Optional tools report as information rather than warnings. A contributor
+    // without Flutter is not misconfigured; they are just not working on the
+    // Flutter app, and saying otherwise trains people to ignore the output.
+    const node = process.versions.node;
+    // The floor is 22.12, not the .nvmrc pin (24): pnpm 11 needs node:sqlite,
+    // which appeared in 22.5 and went LTS-stable at 22.12. CI's first-ever run
+    // failed on exactly this, with Node 20 from the old pin.
+    const [major = 0, minor = 0] = node.split(".").map(Number);
+    checks.push(major > 22 || (major === 22 && minor >= 12)
+        ? `OK    Node ${node}`
+        : `WARN  Node ${node} — this repo needs >= 22.12 for pnpm 11 (see .nvmrc)`);
+    checks.push(has("corepack --version")
+        ? "OK    corepack available"
+        : "WARN  corepack not found — run `corepack enable` for the pinned pnpm");
+    checks.push(has("docker info")
+        ? "OK    Docker running (local Supabase stack available)"
+        : "INFO  Docker not running — fine against a hosted project, needed to run Supabase on this machine");
+    checks.push(has("flutter --version")
+        ? "OK    Flutter installed (study-group-finder buildable)"
+        : "INFO  Flutter not installed — only needed for apps/study-group-finder");
+    // ── No repo yet? ───────────────────────────────────────────────────────────
+    //
+    // `discoverRepoRoot()` (the non-throwing lookup — see `repo/root.ts`)
+    // rather than `findRepoRoot()`: per the carve-out plan's §5,
+    // `pnpm dlx @devdogsuga/devtools setup` is meant to work PRE-CLONE, run
+    // from wherever a contributor happens to be before they have a checkout
+    // at all. The prerequisite checks above need no repo either way; only the
+    // `.env`-seeding half below does, so that's the only part skipped here.
+    const repoRoot = discoverRepoRoot();
+    if (repoRoot === null) {
+        note(checks.join("\n"), "Prerequisites");
+        note([
+            "No DevDogsUGA checkout found in this directory or its parents.",
+            "",
+            "1. git clone https://github.com/devdogsuga/DevDogsUGA.git",
+            "2. cd DevDogsUGA && pnpm install",
+            "3. pnpm devtools setup   — run again from inside the clone to seed .env",
+        ].join("\n"), "Next steps");
+        return;
+    }
+    // ── Env ────────────────────────────────────────────────────────────────────
+    // Seeded from the SAME renderer as `env init` and the generated
+    // .env.example, rather than by copying the example file: a copy would carry
+    // the example's "GENERATED ... Do not edit this file" header into the one
+    // file that is meant to be edited. Like init, an existing file is untouched.
+    const env = join(repoRoot, ".env");
+    let seededEnv = false;
+    // The apps the picker chose, so "Next steps" boots what this contributor is
+    // actually here for rather than a hardcoded default. Null when the .env
+    // already existed (no picker ran) — the generic `pnpm dev` picker covers it.
+    let chosenApps = null;
+    if (existsSync(env)) {
+        checks.push("OK    .env already exists (left untouched)");
+    }
+    else {
+        await loadRegistry();
+        // The project picker: a contributor's .env carries the sections for the
+        // projects they picked (plus the shared Supabase stack), not all six.
+        // The operator tooling is offered as a ROLE in the same picker, off by
+        // default: no app reads those keys, and every command that needs one
+        // refuses by name with the recovery step. Re-running `env init` later
+        // APPENDS the sections for a new project without touching filled values.
+        const sections = await resolveSections();
+        if (sections) {
+            // Lead with the two projects most contributors join; platform is shared
+            // auth infrastructure you depend on but rarely edit, and sandbox is
+            // dormant, trailing last as the one almost nobody touches.
+            const order = [
+                "schedule-builder",
+                "study-group-finder",
+                "platform",
+                "sandbox",
+            ];
+            chosenApps = order.filter((app) => sections.has(app));
+        }
+        writeFileSync(env, renderInit("development", new Date().toISOString().slice(0, 10), sections), { flag: "wx" });
+        checks.push("OK    created .env (same as `pnpm devtools env init`)");
+        seededEnv = true;
+    }
+    note(checks.join("\n"), "Prerequisites");
+    if (seededEnv) {
+        log.info(".env starts blank. Supabase on this machine fills the connection block " +
+            "for you; only a hosted project needs values typed in.");
+    }
+    // Boot what the contributor picked. study-group-finder still goes through
+    // the same `pnpm dev --filter` picker path (pnpm runs its `flutter run`
+    // task), so the shape is uniform; the SDK note is the only difference.
+    const startSteps = chosenApps && chosenApps.length > 0
+        ? chosenApps.map((app) => app === "study-group-finder"
+            ? `     pnpm dev --filter study-group-finder   (Flutter — needs the SDK)`
+            : `     pnpm dev --filter ${app}`)
+        : ["     pnpm dev   — then pick your app from the list"];
+    note([
+        "1. Run `pnpm devtools` again and choose:",
+        "     Database → start   — boots the local Docker stack and writes",
+        "                          .env.generated (no credentials needed)",
+        "",
+        '2. Choose Workspace → oauth to configure "Sign in with DevDogs"',
+        "   after the local database is running. Every app signs in through",
+        "   platform's OAuth server, so this step is shared no matter which",
+        "   project you are building.",
+        "",
+        "3. Start the project you picked:",
+        ...startSteps,
+        ...(chosenApps?.includes("schedule-builder")
+            ? [
+                "",
+                "   schedule-builder starts with an empty catalog. Populate it by",
+                "   triggering the registrar scrape workflow (starts Wrangler for you):",
+                "     pnpm devtools workflows run --app schedule-builder --tier development",
+            ]
+            : []),
+        "",
+        "Working against a hosted Supabase project instead? Fill in .env",
+        "(dashboard → Project Settings), then:",
+        "  pnpm devtools db connect <project-ref>",
+        "  pnpm devtools db types",
+    ].join("\n"), "Next steps");
+}

package/dist/stack.d.ts

@@ -0,0 +1,48 @@
+import { type DbConnection } from "./db/connection.js";
+import { originReachable } from "./cron/commands.js";
+export declare const STACK_COMMANDS: readonly ["start", "stop", "restart", "status", "migrate", "reset"];
+export type StackCommand = (typeof STACK_COMMANDS)[number];
+/**
+ * `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 declare function connectRemoteProject(ref?: string): Promise<number>;
+/** Injectable so a test can fake "server up" / "server down" and inspect the
+ * request `reconcileConfigAfterReset` sends, without a real dev server or a
+ * `vi.stubGlobal` on `fetch`. Defaults to the real network. */
+export interface ReconcileConfigDeps {
+    reachable: typeof originReachable;
+    fetch: typeof globalThis.fetch;
+}
+/**
+ * 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 declare function reconcileConfigAfterReset(deps?: ReconcileConfigDeps): Promise<string[]>;
+/**
+ * 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 declare function runStackCommand(command: StackCommand, connection: DbConnection | null): Promise<{
+    code: number;
+    lines: string[];
+}>;

package/dist/stack.js

@@ -0,0 +1,290 @@
+/**
+ * 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 { 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 { dbPush, generateTypes, seedBuckets, supabase, supabaseCapture, } from "./db/run.js";
+import { describeDbTarget, isLocalConnection, } from "./db/connection.js";
+import { refreshSessionEnv } from "./db/session-refresh.js";
+import { originReachable, resolveBaseUrl } from "./cron/commands.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 ──────────────────────────────────────────────────────────
+async function startLocalStack() {
+    const code = await supabase("start");
+    if (code !== 0)
+        return code;
+    // Write the local stack's connection details so with-env can load them.
+    let env;
+    try {
+        env = await supabaseCapture("status", "-o", "env");
+    }
+    catch {
+        return 1;
+    }
+    await writeFile(join(findRepoRoot(), ".env.generated"), env);
+    return seedBuckets({ kind: "local" });
+}
+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.
+ *
+ * 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 a local reset 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 code = await supabase("db", "reset", "--db-url", connection.dbUrl);
+    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: [] };
+    return {
+        code: 0,
+        lines: isLocalConnection(connection)
+            ? 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 changed nothing on disk, so there is nothing to refresh.
+ */
+async function afterLocalStackChange(code) {
+    if (code !== 0)
+        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 = await startLocalStack();
+    return { code, lines: await afterLocalStackChange(code) };
+}
+/**
+ * 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.
+ */
+function localStatus() {
+    const env = probeEnvironment();
+    let next;
+    if (env.docker === "no") {
+        next = "Start Docker, then `pnpm devtools db start` to bring the stack up.";
+    }
+    else if (env.stack === "yes") {
+        next = "The stack is up. `supabase status` prints its URLs and keys.";
+    }
+    else if (env.stack === "no") {
+        next = "Nothing is running. `pnpm devtools db start` starts it.";
+    }
+    else {
+        next = "Could not read Docker. `supabase status` asks the stack directly.";
+    }
+    return { code: 0, lines: [describeEnvironment(env), next] };
+}
+/**
+ * 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 = await startLocalStack();
+        return { code, lines: await afterLocalStackChange(code) };
+    }
+    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

@@ -0,0 +1,34 @@
+/**
+ * `'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;
+/**
+ * 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 uncaught error from the top-level `main().catch` in `cli.ts`
+ * and `ci.ts` alike, 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>;

package/dist/telemetry.js

@@ -0,0 +1,93 @@
+/**
+ * devtools' own Sentry wiring — the CLI is a consumer of
+ * `@devdogsuga/telemetry` like `apps/platform`, `apps/schedule-builder`, and
+ * `apps/sandbox`, but on `@sentry/node` rather than a framework SDK: a CLI
+ * process starts, runs one command, and exits, with none of a server's
+ * request lifecycle for a framework integration to hook into.
+ *
+ * ## Reporting is on by default
+ *
+ * Every other `*_SENTRY_DSN` in this workspace is optional-and-empty until
+ * an org exists to receive it (see `@devdogsuga/telemetry`'s no-op-without-
+ * DSN contract). `DEVTOOLS_SENTRY_DSN` follows the same contract — empty
+ * means `buildSentryOptions` returns `undefined` and `Sentry.init` never
+ * runs — but the DEFAULT here is reporting ON once a DSN exists, unlike a
+ * feature a contributor opts into. `DEVTOOLS_TELEMETRY=0` is the one escape
+ * hatch, checked before `Sentry.init` and before every capture call, so it
+ * also works as a kill switch after init already ran (a long-lived `pnpm
+ * devtools` menu session, for instance).
+ *
+ * `PLACEHOLDER_DEVTOOLS_SENTRY_DSN` is committed empty on purpose: the
+ * devtools Sentry project does not exist yet. Once it does, either replace
+ * this constant with the real ingest DSN or — preferably — set
+ * `DEVTOOLS_SENTRY_DSN` in the environment, which always wins over the
+ * placeholder. Either way, an empty result here is indistinguishable from
+ * "not configured": no init, no network call, no console spam, which is the
+ * whole point of shipping this file before the org is onboarded.
+ */
+import * as Sentry from "@sentry/node";
+import { buildSentryOptions } from "@devdogsuga/telemetry";
+// ⚠️ PLACEHOLDER — see this file's header. Leave empty until the devtools
+// Sentry project exists.
+const PLACEHOLDER_DEVTOOLS_SENTRY_DSN = "";
+let initialized = false;
+/**
+ * `'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 function devtoolsEnvironment() {
+    return process.env.CI ? "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 function devtoolsTelemetryEnabled() {
+    return process.env.DEVTOOLS_TELEMETRY !== "0";
+}
+/**
+ * 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 function initDevtoolsTelemetry(command) {
+    if (initialized)
+        return;
+    initialized = true;
+    if (!devtoolsTelemetryEnabled())
+        return;
+    const dsn = process.env.DEVTOOLS_SENTRY_DSN || PLACEHOLDER_DEVTOOLS_SENTRY_DSN;
+    const options = buildSentryOptions({
+        service: "devtools",
+        environment: devtoolsEnvironment(),
+        dsn,
+        release: process.env.SENTRY_RELEASE,
+    });
+    if (!options)
+        return;
+    Sentry.init(options);
+    Sentry.getCurrentScope().setTag("command", command);
+}
+/**
+ * Reports an uncaught error from the top-level `main().catch` in `cli.ts`
+ * and `ci.ts` alike, 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 async function captureDevtoolsError(err) {
+    if (!devtoolsTelemetryEnabled())
+        return;
+    Sentry.captureException(err);
+    await Sentry.flush(2000);
+}

package/dist/tier.d.ts

@@ -0,0 +1,40 @@
+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 {};