@devdogsuga/devtools 0.1.11 → 0.1.13

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

package/dist/workflows/commands.js

@@ -1,21 +1,26 @@
 /** Config-derived listing and manual triggering for Cloudflare Workflows. */
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
 import { createServer } from "node:net";
+import { basename, join } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { confirm, select, text } from "@clack/prompts";
 import { loadEnvLoad } from "../repo/peers.js";
-import { createTemporaryWranglerEnv, renderWranglerEnvFile, } from "../cf/local-env.js";
+import { createTemporaryWranglerEnv, renderWranglerEnvFile, scopedProcessEnv, } from "../cf/local-env.js";
+import { buildWorkspaceDeps, needsFrameworkBuild } from "../cf/build.js";
 import { runWithStderr } from "../db/run.js";
 import { findRepoRoot } from "../repo/root.js";
+import { workerPaths } from "../workers.js";
 import { recordResolved } from "../invocation.js";
 import { resolveTier } from "../tier.js";
 import { unwrap } from "../ui.js";
 import { CRON_TIERS, discoverWranglerConfigs, isCronTier, workflowsForTier, } from "../cron/discovery.js";
 export { renderWranglerEnvFile } from "../cf/local-env.js";
-// A clean OpenNext checkout builds before Wrangler can boot. Keep showing that
-// build's inherited output and allow enough time for a production Next build.
-const WRANGLER_READY_TIMEOUT_MS = 5 * 60_000;
+// Covers `vinext dev`'s first-run dependency optimization and workerd boot. It
+// also bounds how long a broken bundle stalls the command: both runtimes report
+// a bundling error but keep watching for changes instead of exiting.
+const WRANGLER_READY_TIMEOUT_MS = 3 * 60_000;
 const LOCAL_WORKFLOW_TIMEOUT_MS = 60 * 60_000;
 const WRANGLER_PROBE_PATH = "/cdn-cgi/local/explorer/api/workflows";
 export function workflowChoices(configs, tiers = CRON_TIERS) {
@@ -162,6 +167,53 @@ export function wranglerDevArgs(app, port) {
         "--show-interactive-dev-session=false",
     ];
 }
+/** `vinext dev` bound to loopback, where `isWranglerDevRunning` probes. */
+export function vinextDevArgs(app, port) {
+    return [
+        "--filter",
+        app,
+        "exec",
+        "vinext",
+        "dev",
+        "--port",
+        port,
+        "--hostname",
+        "127.0.0.1",
+    ];
+}
+/**
+ * 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 function runningVinextDevPort(appDir, isAlive = pidIsAlive) {
+    try {
+        const lock = JSON.parse(readFileSync(join(appDir, ".vinext", "dev", "lock.json"), "utf8"));
+        if (typeof lock.pid !== "number" || typeof lock.port !== "number") {
+            return undefined;
+        }
+        return isAlive(lock.pid) ? String(lock.port) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function pidIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM: alive, just not ours to signal.
+        return error.code === "EPERM";
+    }
+}
+function appDir(app) {
+    const path = workerPaths().find((candidate) => basename(candidate) === app);
+    return path === undefined ? undefined : join(findRepoRoot(), path);
+}
 /** Probe Wrangler's Workflow explorer API, rather than merely checking a port. */
 export async function isWranglerDevRunning(port, timeoutMs = 1_000, fetcher = fetch) {
     try {
@@ -241,13 +293,14 @@ async function startTemporaryWrangler(app, requestedPort) {
         const free = await findFreePort(Number(port) + 1);
         if (free === null) {
             process.stderr.write(`devtools workflows: port ${requestedPort} is in use and no free port ` +
-                `was found near it for a temporary Wrangler session.\n`);
+                `was found near it for a temporary dev session.\n`);
             return null;
         }
-        process.stdout.write(`Port ${requestedPort} is in use; starting the temporary Wrangler session on ${free} instead.\n`);
+        process.stdout.write(`Port ${requestedPort} is in use; starting the temporary dev session on ${free} instead.\n`);
         port = String(free);
     }
-    process.stdout.write(`Preparing and starting a temporary Wrangler session for ${app} on port ${port}…\n`);
+    const runtime = needsFrameworkBuild(app) ? "vinext dev" : "Wrangler";
+    process.stdout.write(`Preparing and starting a temporary ${runtime} session for ${app} on port ${port}…\n`);
     // Both callers of this function (`workflows serve`, `workflows run --tier
     // development`) are local-only, so the tier is always development — but
     // load it explicitly rather than letting the scoped `.dev.vars` fall back
@@ -265,11 +318,30 @@ async function startTemporaryWrangler(app, requestedPort) {
         }
         throw err;
     }
-    const runtimeEnv = await createTemporaryWranglerEnv(app, loaded.env);
-    const child = spawn("pnpm", [...wranglerDevArgs(app, port), "--env-file", runtimeEnv.path], {
+    // Their `exports` point at gitignored `dist/`, so on a fresh clone the
+    // app's `next.config.ts` can't load without this (see `cf/build.ts`).
+    const buildCode = await buildWorkspaceDeps(app);
+    if (buildCode !== 0) {
+        process.stderr.write(`devtools workflows: building ${app}'s workspace dependencies failed (exit ${buildCode}); not starting ${runtime}.\n`);
+        return null;
+    }
+    // A vinext app runs on `vinext dev`: the Cloudflare Vite plugin serves the
+    // same Workflow bindings and local explorer API as `wrangler dev`, straight
+    // from source. A bare `wrangler dev` against its pre-build wrangler.jsonc
+    // cannot bundle it at all (see `cf/build.ts`). The plugin takes no env file,
+    // so the scoped env rides the child's own environment instead.
+    const runtimeEnv = needsFrameworkBuild(app)
+        ? undefined
+        : await createTemporaryWranglerEnv(app, loaded.env);
+    const child = spawn("pnpm", runtimeEnv
+        ? [...wranglerDevArgs(app, port), "--env-file", runtimeEnv.path]
+        : vinextDevArgs(app, port), {
         cwd: findRepoRoot(),
         stdio: "inherit",
         detached: process.platform !== "win32",
+        ...(runtimeEnv
+            ? {}
+            : { env: await scopedProcessEnv(app, loaded.env, "development") }),
     });
     let startupError;
     child.once("error", (error) => {
@@ -278,57 +350,72 @@ async function startTemporaryWrangler(app, requestedPort) {
     const deadline = Date.now() + WRANGLER_READY_TIMEOUT_MS;
     while (Date.now() < deadline) {
         if (await isWranglerDevRunning(port)) {
-            process.stdout.write("Wrangler is ready.\n");
+            process.stdout.write(`${runtime} is ready.\n`);
             const stopOnParentExit = () => {
                 signalProcessGroup(child, "SIGTERM");
-                runtimeEnv.remove();
+                runtimeEnv?.remove();
             };
             process.once("exit", stopOnParentExit);
             return {
                 stop: async () => {
                     process.off("exit", stopOnParentExit);
                     await stopTemporaryWrangler(child);
-                    runtimeEnv.remove();
+                    runtimeEnv?.remove();
                 },
                 forceStop: () => {
                     process.off("exit", stopOnParentExit);
                     signalProcessGroup(child, "SIGKILL");
-                    runtimeEnv.remove();
+                    runtimeEnv?.remove();
                 },
                 port,
             };
         }
         if (startupError || child.exitCode !== null || child.signalCode !== null) {
-            process.stderr.write(`devtools workflows run: Wrangler stopped before it became ready${startupError ? `: ${startupError.message}` : "."}\n`);
-            runtimeEnv.remove();
+            // Name the exit status: a silent early exit is otherwise undiagnosable,
+            // since the runtime itself may print nothing on the way out.
+            const how = startupError
+                ? `: ${startupError.message}`
+                : child.signalCode !== null
+                    ? ` (killed by ${child.signalCode}).`
+                    : ` (exit ${child.exitCode}).`;
+            process.stderr.write(`devtools workflows run: ${runtime} stopped before it became ready${how}\n`);
+            runtimeEnv?.remove();
             return null;
         }
         await delay(250);
     }
     await stopTemporaryWrangler(child);
-    runtimeEnv.remove();
-    process.stderr.write(`devtools workflows run: Wrangler did not become ready on port ${port} within 5 minutes.\n`);
+    runtimeEnv?.remove();
+    process.stderr.write(`devtools workflows run: ${runtime} did not become ready on port ${port} within ${WRANGLER_READY_TIMEOUT_MS / 60_000} minutes.\n`);
     return null;
 }
 async function prepareLocalWrangler(app, initialPort) {
     let port = initialPort;
+    if (!(await isWranglerDevRunning(port))) {
+        const dir = appDir(app);
+        const running = dir === undefined ? undefined : runningVinextDevPort(dir);
+        if (running !== undefined && (await isWranglerDevRunning(running))) {
+            process.stdout.write(`Using the vinext dev session already running for ${app} on port ${running}.\n`);
+            return { port: running };
+        }
+    }
     while (!(await isWranglerDevRunning(port))) {
         if (!process.stdin.isTTY) {
             process.stderr.write(wranglerDevNotRunningHint(app, port));
             return undefined;
         }
         const action = unwrap(await select({
-            message: `No Wrangler dev session was found on port ${port}.`,
+            message: `No Workflow runtime (vinext dev or wrangler dev) was found on port ${port}.`,
             options: [
                 {
                     value: "start",
-                    label: "Start Wrangler temporarily",
+                    label: "Start one temporarily",
                     hint: "stop it after this Workflow is triggered",
                 },
                 {
                     value: "port",
                     label: "Use another port",
-                    hint: "Wrangler may already be running there",
+                    hint: "a dev session may already be running there",
                 },
                 { value: "cancel", label: "Cancel" },
             ],
@@ -579,7 +666,7 @@ export async function runWorkflowsRun(argv) {
     finally {
         uninstallSignalCleanup?.();
         if (local?.temporary) {
-            process.stdout.write("Stopping the temporary Wrangler session…\n");
+            process.stdout.write("Stopping the temporary dev session…\n");
             await local.temporary.stop();
         }
     }
@@ -617,7 +704,14 @@ export async function runWorkflowsServe(argv) {
         recordResolved("--port", port);
     }
     if (await isWranglerDevRunning(port)) {
-        process.stderr.write(`devtools workflows serve: Wrangler is already running on port ${port}.\n`);
+        process.stderr.write(`devtools workflows serve: a Workflow runtime is already running on port ${port}.\n`);
+        return 1;
+    }
+    const dir = appDir(app);
+    const running = dir === undefined ? undefined : runningVinextDevPort(dir);
+    if (running !== undefined) {
+        process.stderr.write(`devtools workflows serve: vinext dev is already running for ${app} on port ${running}; ` +
+            "vinext allows one per app, and `workflows run` reuses it.\n");
         return 1;
     }
     const session = await startTemporaryWrangler(app, port);
@@ -625,7 +719,7 @@ export async function runWorkflowsServe(argv) {
         return 1;
     // `session.port`, not `port`: the session auto-picks a free port when the
     // requested one is taken, so this line must report where it actually landed.
-    process.stdout.write(`Wrangler will keep running on port ${session.port}. Press Ctrl+C to stop it.\n`);
+    process.stdout.write(`The dev session will keep running on port ${session.port}. Press Ctrl+C to stop it.\n`);
     await new Promise((resolve) => {
         // `process.on`, not `once`: `once` unregisters itself after the first
         // signal, so a second Ctrl+C arriving during `session.stop()`'s up-to-
@@ -640,7 +734,7 @@ export async function runWorkflowsServe(argv) {
             if (stopping) {
                 process.off("SIGINT", onSignal);
                 process.off("SIGTERM", onSignal);
-                process.stdout.write("Stopping Wrangler (forced)…\n");
+                process.stdout.write("Stopping the dev session (forced)…\n");
                 session.forceStop();
                 process.kill(process.pid, signal);
                 return;
@@ -651,7 +745,7 @@ export async function runWorkflowsServe(argv) {
         process.on("SIGINT", onSignal);
         process.on("SIGTERM", onSignal);
     });
-    process.stdout.write("Stopping Wrangler…\n");
+    process.stdout.write("Stopping the dev session…\n");
     await session.stop();
     return 0;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devdogsuga/devtools",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "private": false,
   "type": "module",
   "description": "Contributor CLI for a DevDogsUGA checkout: database, env, images, emails, cron, deploy. Ships built JS; run via `pnpm dlx @devdogsuga/devtools` (or the `devtools`/`devtools-ci` bins once installed) from inside a DevDogsUGA clone.",
@@ -43,7 +43,8 @@
   "peerDependencies": {
     "@devdogsuga/brand": "*",
     "@devdogsuga/db": "*",
-    "@devdogsuga/env": "*"
+    "@devdogsuga/env": "*",
+    "@devdogsuga/events": "*"
   },
   "peerDependenciesMeta": {
     "@devdogsuga/brand": {
@@ -54,6 +55,9 @@
     },
     "@devdogsuga/env": {
       "optional": true
+    },
+    "@devdogsuga/events": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -62,10 +66,11 @@
     "@vitest/coverage-v8": "^4.1.11",
     "react": "^19.2.8",
     "vitest": "^4.1.11",
-    "@devdogsuga/config": "0.1.1",
-    "@devdogsuga/brand": "0.1.1",
     "@devdogsuga/db": "0.1.1",
-    "@devdogsuga/env": "0.1.1"
+    "@devdogsuga/env": "0.1.1",
+    "@devdogsuga/brand": "0.1.2",
+    "@devdogsuga/events": "0.1.2",
+    "@devdogsuga/config": "0.1.1"
   },
   "scripts": {
     "build": "tsc && node scripts/write-build-info.mjs",