@devdogsuga/devtools 0.1.12 → 0.1.14

package/dist/repo/supabase-project.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Reads `project_id` out of `<repoRoot>/supabase/config.toml`, or `null`
+ * when the file is missing or unparsable.
+ *
+ * Regex, not 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 path some
+ * callers pay before their first real subprocess is a cost that stays
+ * invisible until it is why the tool feels slow.
+ */
+export declare function readProjectId(repoRoot: string): string | null;
+/**
+ * The Supabase CLI's container name prefix for a project id, or the bare
+ * `supabase_db_` fallback when the id could not be read.
+ *
+ * Falling back to the bare prefix means a machine whose `config.toml`
+ * cannot be read still detects *a* stack, at the cost of over-matching a
+ * differently-named project — deliberate, and unchanged from this
+ * function's original home in `environment.ts`: over-matching offers
+ * `stop`/a foreign-stack hint for a stack that turns out to be this
+ * project's own, which is harmless to see and decline, while
+ * under-matching hides a real signal entirely.
+ */
+export declare function containerPrefix(projectId: string | null): string;
+/**
+ * The local stack's API port, published by its Kong container. Mirrors
+ * `@devdogsuga/env/load`'s `LOCAL_STACK_PORT`, which this module cannot import
+ * statically (that package is an optional peer, loaded on demand).
+ */
+export declare const STACK_API_PORT = 54321;
+/**
+ * `docker ps --format '{{.Names}}'`, split into trimmed, non-empty names —
+ * or `null` when Docker could not be read at all (no daemon, not
+ * installed, timed out). With `publish`, only the containers publishing that
+ * host port. `execute` is injectable for tests, mirroring `environment.ts`'s
+ * own probes.
+ */
+export declare function listContainerNames(publish?: number, execute?: (file: string, args: string[]) => string | null): string[] | null;
+/**
+ * Finds the `supabase_kong_<id>` container among `names` whose id differs
+ * from `projectId` — the signature of a stack started from a DIFFERENT
+ * Supabase project (this same repo before/after a rename, or another
+ * project entirely) holding the shared ports. Kong is the container that
+ * publishes the API port, so callers pass the names `listContainerNames`
+ * returns for `STACK_API_PORT`: that names the stack actually on 54321,
+ * not just any Supabase stack on the machine.
+ *
+ * Returns that foreign id, or `null` when every matching container belongs
+ * to this project, none match at all, or `projectId` itself could not be
+ * read — with no known id of our own, there is nothing to compare against,
+ * and guessing would risk telling a contributor their OWN stack is
+ * foreign.
+ */
+export declare function foreignStackProjectId(names: readonly string[], projectId: string | null): string | null;
+/**
+ * The actionable message for a detected foreign stack — shared by
+ * `db/generated-env.ts` (a failed `supabase status -o env`) and `stack.ts`
+ * (a failed `supabase start`), so both name the same fix in the same
+ * words.
+ */
+export declare function foreignStackMessage(foreignProjectId: string): string;

package/dist/repo/supabase-project.js

@@ -0,0 +1,124 @@
+/**
+ * This repo's Supabase project id — read from `supabase/config.toml` — and
+ * the container-name conventions the Supabase CLI derives from it.
+ *
+ * Shared by `environment.ts`'s adaptive-menu probe (does a stack answer for
+ * THIS project?) and the foreign-stack detection in `db/generated-env.ts`
+ * and `stack.ts` (does a DIFFERENT project's stack hold the shared ports? —
+ * the case where `supabase status -o env` fails not because nothing is
+ * running, but because what is running on 127.0.0.1:54321 belongs to
+ * another workspace, or to this same repo before/after a `project_id`
+ * rename). One project-id reader and one container-name parser, so both
+ * questions agree on what "this project" means.
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Reads `project_id` out of `<repoRoot>/supabase/config.toml`, or `null`
+ * when the file is missing or unparsable.
+ *
+ * Regex, not 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 path some
+ * callers pay before their first real subprocess is a cost that stays
+ * invisible until it is why the tool feels slow.
+ */
+export function readProjectId(repoRoot) {
+    try {
+        const path = join(repoRoot, "supabase", "config.toml");
+        const match = /^\s*project_id\s*=\s*"([^"]+)"/m.exec(readFileSync(path, "utf8"));
+        return match?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The Supabase CLI's container name prefix for a project id, or the bare
+ * `supabase_db_` fallback when the id could not be read.
+ *
+ * Falling back to the bare prefix means a machine whose `config.toml`
+ * cannot be read still detects *a* stack, at the cost of over-matching a
+ * differently-named project — deliberate, and unchanged from this
+ * function's original home in `environment.ts`: over-matching offers
+ * `stop`/a foreign-stack hint for a stack that turns out to be this
+ * project's own, which is harmless to see and decline, while
+ * under-matching hides a real signal entirely.
+ */
+export function containerPrefix(projectId) {
+    return projectId ? `supabase_db_${projectId}` : "supabase_db_";
+}
+/**
+ * The local stack's API port, published by its Kong container. Mirrors
+ * `@devdogsuga/env/load`'s `LOCAL_STACK_PORT`, which this module cannot import
+ * statically (that package is an optional peer, loaded on demand).
+ */
+export const STACK_API_PORT = 54321;
+function defaultExec(file, args) {
+    try {
+        return execFileSync(file, args, {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 3000,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `docker ps --format '{{.Names}}'`, split into trimmed, non-empty names —
+ * or `null` when Docker could not be read at all (no daemon, not
+ * installed, timed out). With `publish`, only the containers publishing that
+ * host port. `execute` is injectable for tests, mirroring `environment.ts`'s
+ * own probes.
+ */
+export function listContainerNames(publish, execute = defaultExec) {
+    const filter = publish === undefined ? [] : ["--filter", `publish=${publish}`];
+    const out = execute("docker", ["ps", ...filter, "--format", "{{.Names}}"]);
+    if (out === null)
+        return null;
+    return out
+        .split("\n")
+        .map((name) => name.trim())
+        .filter((name) => name.length > 0);
+}
+/**
+ * Finds the `supabase_kong_<id>` container among `names` whose id differs
+ * from `projectId` — the signature of a stack started from a DIFFERENT
+ * Supabase project (this same repo before/after a rename, or another
+ * project entirely) holding the shared ports. Kong is the container that
+ * publishes the API port, so callers pass the names `listContainerNames`
+ * returns for `STACK_API_PORT`: that names the stack actually on 54321,
+ * not just any Supabase stack on the machine.
+ *
+ * Returns that foreign id, or `null` when every matching container belongs
+ * to this project, none match at all, or `projectId` itself could not be
+ * read — with no known id of our own, there is nothing to compare against,
+ * and guessing would risk telling a contributor their OWN stack is
+ * foreign.
+ */
+export function foreignStackProjectId(names, projectId) {
+    if (projectId === null)
+        return null;
+    for (const name of names) {
+        const match = /^supabase_kong_(.+)$/.exec(name);
+        if (!match)
+            continue;
+        const id = match[1];
+        if (id !== projectId)
+            return id;
+    }
+    return null;
+}
+/**
+ * The actionable message for a detected foreign stack — shared by
+ * `db/generated-env.ts` (a failed `supabase status -o env`) and `stack.ts`
+ * (a failed `supabase start`), so both name the same fix in the same
+ * words.
+ */
+export function foreignStackMessage(foreignProjectId) {
+    return (`The stack on port ${STACK_API_PORT} belongs to project "${foreignProjectId}", not ` +
+        "this checkout's. Stop it with `supabase stop --project-id " +
+        `${foreignProjectId}\` then \`pnpm devtools db start\`.`);
+}

package/dist/setup.js

@@ -139,7 +139,7 @@ export async function runSetup() {
             {
                 value: "local",
                 label: "Local (Docker)",
-                hint: "needs Docker Desktop, OrbStack, or Docker Engine in WSL2",
+                hint: "needs Docker Desktop, or Docker Engine in WSL2",
             },
         ],
         initialValue: "hosted",
@@ -178,7 +178,7 @@ function printLocalNextSteps(chosenApps) {
             ? [
                 "",
                 "   schedule-builder starts with an empty catalog. Populate it by",
-                "   triggering the registrar scrape workflow (starts Wrangler for you):",
+                "   triggering the registrar scrape workflow (starts vinext dev for you):",
                 "     pnpm devtools workflows run --app schedule-builder --tier development",
             ]
             : []),

package/dist/stack.js

@@ -16,15 +16,19 @@
  * 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 { 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
@@ -38,20 +42,58 @@ export const STACK_COMMANDS = [
     "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)
-        return code;
+    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 1;
+        return { code: 1, wroteEnvFile: false };
     }
     await writeFile(join(findRepoRoot(), ".env.generated"), env);
-    return seedBuckets({ kind: "local" });
+    const bucketsCode = await seedBuckets({ kind: "local" });
+    return { code: bucketsCode, wroteEnvFile: true };
 }
 async function stopLocalStack() {
     const code = await supabase("stop");
@@ -97,17 +139,34 @@ async function pushMigrations(connection) {
  * (`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 a local reset this calls that route itself, over the same
- * origin `cron run` would use, once the reset and rebuild finish -- see
+ * 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 code = await supabase("db", "reset", "--db-url", connection.dbUrl);
+    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);
@@ -116,11 +175,23 @@ async function reset(connection) {
     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,
-        lines: isLocalConnection(connection)
-            ? await reconcileConfigAfterReset()
-            : [],
+        // 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(),
     };
 }
 /**
@@ -184,10 +255,19 @@ export async function reconcileConfigAfterReset(deps = {
  * (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.
+ * 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) {
-    if (code !== 0)
+async function afterLocalStackChange(code, wroteEnvFile = false) {
+    if (code !== 0 && !wroteEnvFile)
         return [];
     return refreshSessionEnv();
 }
@@ -215,31 +295,63 @@ async function restartLocal() {
             ],
         };
     }
-    const code = await startLocalStack();
-    return { code, lines: await afterLocalStackChange(code) };
+    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.
+ * `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.
  */
-function localStatus() {
+async function localStatus() {
     const env = probeEnvironment();
-    let next;
+    const lines = [describeEnvironment(env)];
     if (env.docker === "no") {
-        next = "Start Docker, then `pnpm devtools db start` to bring the stack up.";
+        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 };
     }
-    else if (env.stack === "yes") {
-        next = "The stack is up. `supabase status` prints its URLs and keys.";
+    if (env.stack === "unknown") {
+        lines.push("Could not read Docker. `supabase status` asks the stack directly.");
+        return { code: 0, lines };
     }
-    else if (env.stack === "no") {
-        next = "Nothing is running. `pnpm devtools db start` starts it.";
+    // 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 {
-        next = "Could not read Docker. `supabase status` asks the stack directly.";
+        // "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: [describeEnvironment(env), next] };
+    return { code: 0, lines };
 }
 /**
  * Runs a stack command, returning its exit code and anything to report.
@@ -259,8 +371,9 @@ export async function runStackCommand(command, connection) {
         return { code, lines: await afterLocalStackChange(code) };
     }
     if (command === "start") {
-        const code = await startLocalStack();
-        return { code, lines: await afterLocalStackChange(code) };
+        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)) {

package/dist/telemetry.d.ts

@@ -24,13 +24,26 @@ export declare function devtoolsTelemetryEnabled(): boolean;
  */
 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.
+ * 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/telemetry.js

@@ -92,11 +92,11 @@ export function initDevtoolsTelemetry(command) {
     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.
+ * 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.
@@ -107,3 +107,24 @@ export async function captureDevtoolsError(err) {
     Sentry.captureException(err);
     await Sentry.flush(2000);
 }
+/**
+ * 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 function reportDevtoolsError(err) {
+    if (!devtoolsTelemetryEnabled())
+        return;
+    Sentry.captureException(err);
+}
+/**
+ * Reports a failure that has no error object — a subprocess or deploy step
+ * that exited non-zero. Same no-flush contract as `reportDevtoolsError`.
+ */
+export function reportDevtoolsFailure(message, extra = {}) {
+    if (!devtoolsTelemetryEnabled())
+        return;
+    Sentry.captureMessage(message, { level: "error", extra });
+}

package/dist/ui.d.ts

@@ -9,6 +9,21 @@ export declare function unwrap<T>(value: T | symbol): T;
  * 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;

package/dist/ui.js

@@ -10,6 +10,7 @@
  *     ends at a stack trace.
  */
 import { cancel, isCancel, log, note } from "@clack/prompts";
+import { reportDevtoolsError } from "./telemetry.js";
 export function bail(message = "Cancelled.") {
     cancel(message);
     process.exit(1);
@@ -34,6 +35,25 @@ export function explain(summary, detail, hints = []) {
     if (hints.length > 0)
         note(hints.join("\n"), "Try this");
 }
+/**
+ * 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 class UsageError extends Error {
+    name = "UsageError";
+}
+/**
+ * `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 function explainError(summary, err, hints = []) {
+    if (!(err instanceof UsageError))
+        reportDevtoolsError(err);
+    explain(summary, errorMessage(err), hints);
+}
 export function errorMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }

package/dist/workflows/commands.d.ts

@@ -26,6 +26,16 @@ export declare function waitForLocalWorkflow(workflowName: string, instanceId: s
     fetcher?: typeof fetch;
 }): Promise<number>;
 export declare function wranglerDevArgs(app: string, port: string): string[];
+/** `vinext dev` bound to loopback, where `isWranglerDevRunning` probes. */
+export declare function vinextDevArgs(app: string, port: string): string[];
+/**
+ * The port of a `vinext dev` already running for `app`, from the lock file
+ * vinext keeps at `<app>/.vinext/dev/lock.json` — or undefined when there is
+ * none, or its process is gone. vinext refuses a second dev server in the same
+ * app directory, so starting one beside it fails ("Another vinext dev server
+ * is already running"); reusing it is the only way through.
+ */
+export declare function runningVinextDevPort(appDir: string, isAlive?: (pid: number) => boolean): string | undefined;
 /** Probe Wrangler's Workflow explorer API, rather than merely checking a port. */
 export declare function isWranglerDevRunning(port: string, timeoutMs?: number, fetcher?: typeof fetch): Promise<boolean>;
 /** Whether nothing is bound to `port` on loopback — a real bind test, not a