@devdogsuga/devtools 0.1.25 → 0.1.27

package/dist/workflows/commands.js

@@ -1,763 +0,0 @@
-/** 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, 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";
-// 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) {
-    return configs
-        .flatMap(({ app, config }) => tiers.flatMap((tier) => workflowsForTier(config, tier).map((workflow) => ({
-        app,
-        tier,
-        binding: workflow.binding,
-        name: workflow.name,
-        className: workflow.class_name,
-    }))))
-        .sort((a, b) => a.app.localeCompare(b.app) ||
-        a.tier.localeCompare(b.tier) ||
-        a.name.localeCompare(b.name));
-}
-function parseOptions(argv) {
-    const options = {
-        yes: argv.includes("--yes"),
-        json: argv.includes("--json"),
-    };
-    for (let index = 0; index < argv.length; index += 1) {
-        const flag = argv[index];
-        const value = argv[index + 1];
-        if (flag === "--app")
-            options.app = value;
-        else if (flag === "--tier")
-            options.tier = value;
-        else if (flag === "--workflow")
-            options.workflow = value;
-        else if (flag === "--params")
-            options.params = value;
-        else if (flag === "--port")
-            options.port = value;
-    }
-    return options;
-}
-function validateTier(value, command) {
-    if (value === undefined)
-        return undefined;
-    if (isCronTier(value))
-        return value;
-    process.stderr.write(`devtools workflows ${command}: unknown tier "${value}". Expected: ${CRON_TIERS.join(", ")}.\n`);
-    return null;
-}
-export function workflowTriggerArgs(choice, options) {
-    const args = [
-        "--filter",
-        choice.app,
-        "exec",
-        "wrangler",
-        "workflows",
-        "trigger",
-        choice.name,
-    ];
-    if (options.params)
-        args.push(options.params);
-    if (options.instanceId)
-        args.push("--id", options.instanceId);
-    if (choice.tier === "development") {
-        args.push("--local", "--port", options.port ?? "8787");
-    }
-    else {
-        args.push("--env", choice.tier);
-    }
-    return args;
-}
-/** Wait until a locally-triggered instance finishes before its server is stopped. */
-export async function waitForLocalWorkflow(workflowName, instanceId, port, options = {}) {
-    const timeoutMs = options.timeoutMs ?? LOCAL_WORKFLOW_TIMEOUT_MS;
-    const pollMs = options.pollMs ?? 500;
-    const fetcher = options.fetcher ?? fetch;
-    const deadline = Date.now() + timeoutMs;
-    const url = `http://127.0.0.1:${port}${WRANGLER_PROBE_PATH}/` +
-        `${encodeURIComponent(workflowName)}/instances/${encodeURIComponent(instanceId)}`;
-    let previousStatus;
-    while (Date.now() < deadline) {
-        const response = await fetcher(url, {
-            signal: AbortSignal.timeout(2_000),
-        });
-        if (response.status === 404) {
-            await delay(pollMs);
-            continue;
-        }
-        if (!response.ok) {
-            throw new Error(`Wrangler returned HTTP ${response.status} while checking Workflow instance ${instanceId}.`);
-        }
-        const envelope = (await response.json());
-        if (envelope.success !== true || !envelope.result) {
-            const message = envelope.errors?.[0]?.message ?? "unknown Wrangler error";
-            throw new Error(`Could not read Workflow instance ${instanceId}: ${message}`);
-        }
-        const { status, error } = envelope.result;
-        if (status && status !== previousStatus) {
-            process.stdout.write(`Workflow ${instanceId}: ${status}\n`);
-            previousStatus = status;
-        }
-        if (status === "complete") {
-            const output = envelope.result.output;
-            const failures = typeof output === "object" &&
-                output !== null &&
-                "failures" in output &&
-                Array.isArray(output.failures)
-                ? output.failures
-                : [];
-            if (failures.length > 0) {
-                process.stderr.write(`devtools workflows run: Workflow ${instanceId} completed with ${failures.length} recorded failure${failures.length === 1 ? "" : "s"}:\n`);
-                for (const failure of failures) {
-                    if (typeof failure === "object" && failure !== null) {
-                        const period = "academicPeriod" in failure
-                            ? String(failure.academicPeriod)
-                            : "unknown item";
-                        const message = "error" in failure ? String(failure.error) : "unknown error";
-                        process.stderr.write(`  - ${period}: ${message}\n`);
-                    }
-                    else {
-                        process.stderr.write(`  - ${String(failure)}\n`);
-                    }
-                }
-                return 1;
-            }
-            return 0;
-        }
-        if (status === "errored" || status === "terminated") {
-            const detail = error?.message
-                ? `: ${error.name ? `${error.name}: ` : ""}${error.message}`
-                : "";
-            process.stderr.write(`devtools workflows run: Workflow ${instanceId} ${status}${detail}\n`);
-            return 1;
-        }
-        await delay(pollMs);
-    }
-    process.stderr.write(`devtools workflows run: Workflow ${instanceId} did not finish within ${Math.round(timeoutMs / 60_000)} minutes.\n`);
-    return 1;
-}
-export function wranglerDevArgs(app, port) {
-    return [
-        "--filter",
-        app,
-        "exec",
-        "wrangler",
-        "dev",
-        "--port",
-        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 {
-        const response = await fetcher(`http://127.0.0.1:${port}${WRANGLER_PROBE_PATH}`, { signal: AbortSignal.timeout(timeoutMs) });
-        if (!response.ok)
-            return false;
-        const payload = (await response.json());
-        return payload.success === true;
-    }
-    catch {
-        return false;
-    }
-}
-function signalProcessGroup(child, signal) {
-    if (child.pid === undefined)
-        return;
-    try {
-        if (process.platform === "win32")
-            child.kill(signal);
-        else
-            process.kill(-child.pid, signal);
-    }
-    catch {
-        // It may have exited between the readiness/exit check and the signal.
-    }
-}
-async function stopTemporaryWrangler(child) {
-    if (child.exitCode !== null || child.signalCode !== null)
-        return;
-    signalProcessGroup(child, "SIGINT");
-    if (await waitForExit(child, 3_000))
-        return;
-    signalProcessGroup(child, "SIGTERM");
-    if (await waitForExit(child, 3_000))
-        return;
-    signalProcessGroup(child, "SIGKILL");
-    await waitForExit(child, 1_000);
-}
-async function waitForExit(child, timeoutMs) {
-    if (child.exitCode !== null || child.signalCode !== null)
-        return true;
-    return Promise.race([
-        new Promise((resolve) => child.once("exit", () => resolve(true))),
-        delay(timeoutMs).then(() => false),
-    ]);
-}
-/** Whether nothing is bound to `port` on loopback — a real bind test, not a
- * connect probe, so it answers the only question that matters here: can Wrangler
- * take this port? */
-export function isPortFree(port) {
-    return new Promise((resolve) => {
-        const server = createServer();
-        server.once("error", () => resolve(false));
-        server.listen({ host: "127.0.0.1", port }, () => {
-            server.close(() => resolve(true));
-        });
-    });
-}
-/** The first free port at or after `from`, or null if a bounded scan finds
- * none. Bounded so an exhausted range fails loudly instead of looping. */
-export async function findFreePort(from, attempts = 20) {
-    for (let port = from; port < from + attempts && port <= 65_535; port += 1) {
-        if (await isPortFree(port))
-            return port;
-    }
-    return null;
-}
-async function startTemporaryWrangler(app, requestedPort) {
-    const envLoad = await loadEnvLoad();
-    // Auto-pick a free port when the requested one is taken. The usual culprit is
-    // another project's `wrangler dev` holding the default 8787; without this,
-    // `wrangler dev --port <taken>` cannot bind and the session never becomes
-    // ready — read as "triggering a workflow is broken" rather than "that port is
-    // busy". The trigger below uses whatever port we actually bound.
-    let port = requestedPort;
-    if (!(await isPortFree(Number(port)))) {
-        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 dev session.\n`);
-            return null;
-        }
-        process.stdout.write(`Port ${requestedPort} is in use; starting the temporary dev session on ${free} instead.\n`);
-        port = String(free);
-    }
-    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
-    // to this process's own inherited env: `override: true` re-reads `.env`
-    // fresh, so an edit made after this process started is picked up instead
-    // of a value it happened to inherit at boot.
-    let loaded;
-    try {
-        loaded = await envLoad.loadEnvironment("development", { override: true });
-    }
-    catch (err) {
-        if (err instanceof envLoad.MissingEnvFileError) {
-            process.stderr.write(`devtools workflows: ${err.message}\n`);
-            return null;
-        }
-        throw err;
-    }
-    // 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) => {
-        startupError = error;
-    });
-    const deadline = Date.now() + WRANGLER_READY_TIMEOUT_MS;
-    while (Date.now() < deadline) {
-        if (await isWranglerDevRunning(port)) {
-            process.stdout.write(`${runtime} is ready.\n`);
-            const stopOnParentExit = () => {
-                signalProcessGroup(child, "SIGTERM");
-                runtimeEnv?.remove();
-            };
-            process.once("exit", stopOnParentExit);
-            return {
-                stop: async () => {
-                    process.off("exit", stopOnParentExit);
-                    await stopTemporaryWrangler(child);
-                    runtimeEnv?.remove();
-                },
-                forceStop: () => {
-                    process.off("exit", stopOnParentExit);
-                    signalProcessGroup(child, "SIGKILL");
-                    runtimeEnv?.remove();
-                },
-                port,
-            };
-        }
-        if (startupError || child.exitCode !== null || child.signalCode !== null) {
-            // 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: ${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 Workflow runtime (vinext dev or wrangler dev) was found on port ${port}.`,
-            options: [
-                {
-                    value: "start",
-                    label: "Start one temporarily",
-                    hint: "stop it after this Workflow is triggered",
-                },
-                {
-                    value: "port",
-                    label: "Use another port",
-                    hint: "a dev session may already be running there",
-                },
-                { value: "cancel", label: "Cancel" },
-            ],
-        }));
-        if (action === "cancel")
-            return undefined;
-        if (action === "port") {
-            port = unwrap(await text({
-                message: "Which port is wrangler dev using?",
-                placeholder: "8787",
-                validate: validatePort,
-            })).trim();
-            continue;
-        }
-        const temporary = await startTemporaryWrangler(app, port);
-        // `temporary.port` — not `port` — because the session may have landed on a
-        // different port when the requested one was taken; the trigger must aim at
-        // where Wrangler actually came up.
-        return temporary ? { port: temporary.port, temporary } : undefined;
-    }
-    return { port };
-}
-function validatePort(value) {
-    if (!value || !/^\d+$/.test(value))
-        return "Enter a port number.";
-    const port = Number(value);
-    if (port < 1 || port > 65_535)
-        return "Enter a port from 1 to 65535.";
-    return undefined;
-}
-export function isWranglerDevConnectionFailure(stderr) {
-    return /Could not connect to local dev session on port \d+[\s\S]*Make sure ["“]wrangler dev["”] is running/i.test(stderr);
-}
-export function wranglerDevConnectionHint(app, port) {
-    return ("\nThe local Workflow trigger connects to Wrangler's Worker runtime, not " +
-        "the Next.js development server. `next dev` renders the web app, but it " +
-        "does not register Cloudflare Workflow bindings or expose Wrangler's " +
-        "local control API.\n\n" +
-        "Start a separate app-scoped Wrangler session, then retry the trigger:\n" +
-        `  pnpm devtools workflows serve --app ${app} --port ${port}\n` +
-        `  pnpm devtools workflows run --app ${app} --tier development --port ${port}\n\n` +
-        "The serve command loads only this app's declared environment. Keep " +
-        "`next dev` running too if you also need the Next.js development UI.\n");
-}
-export function wranglerDevNotRunningHint(app, port) {
-    return (`devtools workflows run: no Wrangler dev session was found on port ${port}.\n` +
-        "A local Workflow needs Wrangler's Worker runtime; `next dev` only serves " +
-        "the Next.js UI and does not register Workflow bindings.\n" +
-        `Start it with: pnpm devtools workflows serve --app ${app} --port ${port}\n` +
-        `If Wrangler uses another port, rerun this command with --port <number>.\n`);
-}
-export async function runWorkflowsList(argv) {
-    const options = parseOptions(argv);
-    const tier = validateTier(options.tier, "list");
-    if (tier === null)
-        return 1;
-    let choices = workflowChoices(discoverWranglerConfigs(), tier ? [tier] : CRON_TIERS);
-    if (options.app)
-        choices = choices.filter((item) => item.app === options.app);
-    if (options.json) {
-        process.stdout.write(`${JSON.stringify(choices, null, 2)}\n`);
-        return 0;
-    }
-    if (choices.length === 0) {
-        process.stdout.write("(no configured Workflows found)\n");
-        return 0;
-    }
-    for (const item of choices) {
-        process.stdout.write(`${item.app}  [${item.tier}]\n` +
-            `  ${item.name}\n` +
-            `    binding: ${item.binding}${item.className ? ` · class: ${item.className}` : ""}\n`);
-    }
-    return 0;
-}
-export async function runWorkflowsRun(argv) {
-    const options = parseOptions(argv);
-    // What arrived as a flag versus what a prompt will decide — only the latter
-    // is worth recording for the "skip the prompts next time" line, since a flag
-    // is already in the recorded base argv.
-    const givenApp = options.app;
-    const givenTier = options.tier;
-    const givenWorkflow = options.workflow;
-    const givenPort = options.port;
-    const tier = await resolveTier(options.tier, "Which tier should receive the Workflow?", { label: "devtools workflows run" });
-    if (!tier)
-        return 1;
-    if (options.params) {
-        try {
-            JSON.parse(options.params);
-        }
-        catch {
-            process.stderr.write("devtools workflows run: --params must be valid JSON.\n");
-            return 1;
-        }
-    }
-    if (options.port) {
-        const error = validatePort(options.port);
-        if (error) {
-            process.stderr.write("devtools workflows run: --port must be an integer from 1 to 65535.\n");
-            return 1;
-        }
-    }
-    let choices = workflowChoices(discoverWranglerConfigs(), [tier]);
-    if (options.app)
-        choices = choices.filter((item) => item.app === options.app);
-    let choice;
-    if (options.workflow) {
-        const matches = choices.filter((item) => item.name === options.workflow || item.binding === options.workflow);
-        if (matches.length > 1 && !options.app) {
-            process.stderr.write(`devtools workflows run: "${options.workflow}" is ambiguous; pass --app.\n`);
-            return 1;
-        }
-        choice = matches[0];
-    }
-    else if (process.stdin.isTTY) {
-        if (choices.length > 0) {
-            choice = unwrap(await select({
-                message: "Which Workflow should run?",
-                options: choices.map((item) => ({
-                    value: item,
-                    label: `${item.app} · ${item.name}`,
-                    hint: `${item.binding}${item.className ? ` · ${item.className}` : ""}`,
-                })),
-            }));
-        }
-    }
-    if (!choice) {
-        process.stderr.write(options.workflow
-            ? `devtools workflows run: no configured Workflow named "${options.workflow}" for ${tier}.\n`
-            : "devtools workflows run: no Workflow was selected; pass --workflow when no terminal is available.\n");
-        return 1;
-    }
-    if (tier !== "development" && !options.yes) {
-        if (!process.stdin.isTTY) {
-            process.stderr.write(`devtools workflows run: --yes is required to trigger ${tier}.\n`);
-            return 1;
-        }
-        const approved = unwrap(await confirm({
-            message: `Trigger ${choice.name} on ${tier}?`,
-            initialValue: false,
-        }));
-        if (!approved)
-            return 1;
-    }
-    let local;
-    // Uninstalls the signal handlers installed below, when this session's
-    // temporary Wrangler (if any) is stopped through the ordinary `finally`
-    // instead of a signal — set only on that branch, so the no-temporary-
-    // session run leaves nothing to uninstall.
-    let uninstallSignalCleanup;
-    if (tier === "development") {
-        local = await prepareLocalWrangler(choice.app, options.port ?? "8787");
-        if (!local)
-            return 1;
-        options.port = local.port;
-        // A successful trigger only means "queued". Keep the exact instance ID so
-        // we can wait for its terminal status before stopping a temporary server.
-        options.instanceId = randomUUID();
-        if (local.temporary) {
-            // Everything below can wait up to an hour for the triggered Workflow
-            // (`waitForLocalWorkflow`'s timeout) with a credential-bearing temp env
-            // file on disk and a `wrangler dev` child running. Without a handler,
-            // Ctrl+C during that wait kills only this process — Node's default
-            // SIGINT/SIGTERM disposition — and leaves both behind. `stop()` handles
-            // both (it kills the child and calls the temp env's `remove()`); once
-            // it settles, re-raise the signal with the handler already off, so the
-            // default disposition terminates the process and the exit status still
-            // reflects the signal.
-            const session = local.temporary;
-            let stopping = false;
-            const onSignal = (signal) => {
-                if (stopping)
-                    return;
-                stopping = true;
-                process.off("SIGINT", onSignal);
-                process.off("SIGTERM", onSignal);
-                void session.stop().finally(() => process.kill(process.pid, signal));
-            };
-            process.on("SIGINT", onSignal);
-            process.on("SIGTERM", onSignal);
-            uninstallSignalCleanup = () => {
-                process.off("SIGINT", onSignal);
-                process.off("SIGTERM", onSignal);
-            };
-        }
-    }
-    // A remote trigger (`wrangler workflows trigger --env <tier>`) authenticates
-    // against Cloudflare with that tier's own credentials, which live only in
-    // `.env.<tier>` — never in this process's own inherited env, which is
-    // development's. Loading it here, rather than leaving the child to whatever
-    // this process happened to inherit, is an accepted behavior change: a
-    // remote trigger now requires `.env.<tier>` to be present and authenticates
-    // with ITS credentials, not development's. The local path needs none of
-    // this — the temporary Wrangler session already carries development's env.
-    const envLoad = await loadEnvLoad();
-    let triggerEnv;
-    if (tier !== "development") {
-        try {
-            triggerEnv = (await envLoad.loadEnvironment(tier, { override: true }))
-                .env;
-        }
-        catch (err) {
-            if (err instanceof envLoad.MissingEnvFileError) {
-                process.stderr.write(`devtools workflows run: ${err.message}\n`);
-                return 1;
-            }
-            throw err;
-        }
-    }
-    // Record the decisions the prompts made, in flag form, so the CLI can print
-    // a command that reruns this without any of them. `--yes` is deliberately
-    // never recorded: it exists to gate a deployed trigger behind a confirm, and
-    // a copy-pasteable line that skips that confirm would be a footgun. `--app`
-    // is inferred from the chosen Workflow when it was not passed.
-    if (givenApp === undefined)
-        recordResolved("--app", choice.app);
-    if (givenWorkflow === undefined)
-        recordResolved("--workflow", choice.binding);
-    // Only when `resolveTier` actually decided something itself — its own
-    // prompt, or an explicit `--tier` above (already excluded by `givenTier`).
-    // When it fell through to the tier `launch.ts` already entered for the
-    // whole session, `recordEnteredTier` has that covered with its own
-    // `--tier` prefix; recording it again here would print the flag twice.
-    if (givenTier === undefined &&
-        tier !== (process.env.DEPLOY_ENV ?? "development")) {
-        recordResolved("--tier", tier);
-    }
-    if (givenPort === undefined && options.port && options.port !== "8787")
-        recordResolved("--port", options.port);
-    process.stdout.write(`→ ${choice.name} (${choice.app}, ${tier})\n`);
-    try {
-        const result = await runWithStderr(workflowTriggerArgs(choice, options), triggerEnv);
-        if (result.code !== 0 &&
-            tier === "development" &&
-            isWranglerDevConnectionFailure(result.stderr)) {
-            process.stderr.write(wranglerDevConnectionHint(choice.app, options.port ?? "8787"));
-        }
-        if (result.code === 0 && tier === "development" && options.instanceId) {
-            try {
-                return await waitForLocalWorkflow(choice.name, options.instanceId, options.port ?? "8787");
-            }
-            catch (error) {
-                process.stderr.write(`devtools workflows run: ${error instanceof Error ? error.message : String(error)}\n`);
-                return 1;
-            }
-        }
-        return result.code;
-    }
-    finally {
-        uninstallSignalCleanup?.();
-        if (local?.temporary) {
-            process.stdout.write("Stopping the temporary dev session…\n");
-            await local.temporary.stop();
-        }
-    }
-}
-export async function runWorkflowsServe(argv) {
-    const options = parseOptions(argv);
-    const port = options.port ?? "8787";
-    if (validatePort(port)) {
-        process.stderr.write("devtools workflows serve: --port must be an integer from 1 to 65535.\n");
-        return 1;
-    }
-    const apps = [
-        ...new Set(workflowChoices(discoverWranglerConfigs(), ["development"]).map(({ app }) => app)),
-    ];
-    let app = options.app;
-    if (app && !apps.includes(app)) {
-        process.stderr.write(`devtools workflows serve: no development Workflow is configured for "${app}".\n`);
-        return 1;
-    }
-    if (!app && process.stdin.isTTY) {
-        app = unwrap(await select({
-            message: "Which app's Workflow runtime should start?",
-            options: apps.map((value) => ({ value, label: value })),
-        }));
-    }
-    if (!app) {
-        process.stderr.write("devtools workflows serve: pass --app when no terminal is available.\n");
-        return 1;
-    }
-    // Record an app chosen at the prompt (a non-default port too), so the rerun
-    // line can start the same session without the picker.
-    if (options.app === undefined)
-        recordResolved("--app", app);
-    if (options.port === undefined && port !== "8787") {
-        recordResolved("--port", port);
-    }
-    if (await isWranglerDevRunning(port)) {
-        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);
-    if (!session)
-        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(`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-
-        // 3-second graceful escalation has no listener left to catch it — Node's
-        // default SIGINT/SIGTERM disposition then kills the process before the
-        // `stop()` below (and its `runtimeEnv.remove()`) ever runs. The
-        // reentrancy guard tells the two calls apart: the first starts the
-        // graceful stop below; any further signal forces it instead, then
-        // re-raises the signal so the exit status still reflects it.
-        let stopping = false;
-        const onSignal = (signal) => {
-            if (stopping) {
-                process.off("SIGINT", onSignal);
-                process.off("SIGTERM", onSignal);
-                process.stdout.write("Stopping the dev session (forced)…\n");
-                session.forceStop();
-                process.kill(process.pid, signal);
-                return;
-            }
-            stopping = true;
-            resolve();
-        };
-        process.on("SIGINT", onSignal);
-        process.on("SIGTERM", onSignal);
-    });
-    process.stdout.write("Stopping the dev session…\n");
-    await session.stop();
-    return 0;
-}
-export async function runWorkflows(argv) {
-    const [sub, ...rest] = argv;
-    if (sub === "list")
-        return runWorkflowsList(rest);
-    if (sub === "run")
-        return runWorkflowsRun(rest);
-    if (sub === "serve")
-        return runWorkflowsServe(rest);
-    process.stderr.write(`devtools workflows: unknown subcommand "${sub ?? "(none)"}". Expected: list, run or serve.\n`);
-    return 1;
-}