@devdogsuga/devtools 0.1.0

package/dist/cf/commands.js

@@ -0,0 +1,182 @@
+/**
+ * Dispatch for `devtools cf *`.
+ *
+ * Delegates to each app's package scripts for preview/typegen/build, and
+ * passes through to wrangler for `cf exec`.
+ */
+import { confirm } from "@clack/prompts";
+import { loadEnvLoad } from "../repo/peers.js";
+import { run } from "../db/run.js";
+import { resolveTier } from "../tier.js";
+import { unwrap } from "../ui.js";
+import { isWorkerApp, workerApps } from "../workers.js";
+import { withWranglerEnv } from "./local-env.js";
+// A function, not a top-level constant — `workerApps()` reads `workers.json`
+// via `findRepoRoot()`, which must not run at import time (see
+// `workers.ts`'s header on why that broke `--help`/`setup` outside a repo).
+function unknownAppHint() {
+    return `Expected: ${workerApps().join(", ")}.`;
+}
+function parseAppAndRest(argv) {
+    const idx = argv.indexOf("--app");
+    if (idx === -1 || idx + 1 >= argv.length)
+        return { rest: argv };
+    const app = argv[idx + 1];
+    const rest = [...argv.slice(0, idx), ...argv.slice(idx + 2)];
+    return { app, rest };
+}
+function parseTier(argv) {
+    const idx = argv.indexOf("--tier");
+    return idx !== -1 ? argv[idx + 1] : undefined;
+}
+export async function runCf(argv) {
+    const sub = argv[0];
+    const rest = argv.slice(1);
+    if (sub === "preview") {
+        const { app } = parseAppAndRest(rest);
+        if (!app) {
+            process.stderr.write("devtools cf preview: --app <slug> is required.\n");
+            return 1;
+        }
+        if (!isWorkerApp(app)) {
+            process.stderr.write(`devtools cf preview: unknown app "${app}". ${unknownAppHint()}\n`);
+            return 1;
+        }
+        // The command tree's own `--tier` option carries no `prompt` (see
+        // `commands.ts`): asking there AND here would ask twice, once on its own
+        // wizard screen and once from this resolver, whenever more than one tier
+        // file is present. `resolveTier` owns both the validation an explicit
+        // `--tier` needs and the conditional prompt an absent one gets.
+        const tier = await resolveTier(parseTier(rest), "Which tier's env should the preview use?", { label: "devtools cf preview" });
+        if (tier === null)
+            return 1;
+        // Previewing production means the local Worker talks to live production
+        // data (DB_URL, third-party API keys, the lot) from a developer's own
+        // machine — the same exposure `cron run`/`workflows run` gate behind a
+        // confirm for a deployed TIER. Staging carries no such weight; it is a
+        // normal development target and asks for nothing extra.
+        if (tier === "production" && !rest.includes("--yes")) {
+            if (!process.stdin.isTTY) {
+                process.stderr.write("devtools cf preview: --yes is required to preview production.\n");
+                return 1;
+            }
+            const approved = unwrap(await confirm({
+                message: `Preview ${app} against live production data?`,
+                initialValue: false,
+            }));
+            if (!approved)
+                return 1;
+        }
+        const envLoad = await loadEnvLoad();
+        let loaded;
+        if (tier !== "development") {
+            try {
+                // This process runs under `with-env` (development), so process.env
+                // already holds development's values; override: true makes the
+                // tier's own .env.<tier> win instead of quietly previewing against
+                // whatever development happened to have loaded.
+                loaded = await envLoad.loadEnvironment(tier, { override: true });
+            }
+            catch (err) {
+                // `err.message` already names the fetch command (see
+                // `MissingEnvFileError`'s constructor); repeating it here would just
+                // duplicate the line.
+                if (err instanceof envLoad.MissingEnvFileError) {
+                    process.stderr.write(`devtools cf preview: ${err.message}\n`);
+                    return 1;
+                }
+                throw err;
+            }
+        }
+        if (app === "sandbox") {
+            // No build step for the sandbox app: the tier only needs to reach
+            // Wrangler's materialized `--env-file`, below.
+            return withWranglerEnv(app, (envFile) => run([
+                "--filter",
+                app,
+                "exec",
+                "wrangler",
+                "dev",
+                "--env-file",
+                envFile,
+            ]), { env: loaded?.env });
+        }
+        // The build bakes tier-scoped values (NEXT_PUBLIC_* and anything else
+        // read at build time) into the bundle, exactly like `cf:build:<tier>`'s
+        // `DEPLOY_ENV=<tier> with-env` does — so it gets both the tier's loaded
+        // env AND DEPLOY_ENV itself, since build-time code may branch on that
+        // variable directly. The `wrangler dev` child below does NOT: the tier
+        // reaches the Worker at RUNTIME through the scoped `--env-file`
+        // `withWranglerEnv` materializes, not through this process's own
+        // environment, so passing DEPLOY_ENV there would be a no-op at best and a
+        // stale value baked nowhere at worst.
+        //
+        // Both Next.js apps are on vinext: `vinext build` additionally needs
+        // `CLOUDFLARE_ENV=<tier>` (see each app's `cf:build:<tier>` script) —
+        // vinext bakes the target environment in at BUILD time, and `wrangler
+        // dev` cross-checks it against `-e`/the env it resolves, erroring loudly
+        // on a mismatch rather than silently running the wrong tier.
+        const build = await run(["--filter", app, "exec", "vinext", "build"], tier && loaded
+            ? { ...loaded.env, DEPLOY_ENV: tier, CLOUDFLARE_ENV: tier }
+            : undefined);
+        if (build !== 0)
+            return build;
+        // Create this after the framework build. Apart from shortening the time a
+        // credential-bearing file exists, this prevents build-tool temp cleanup
+        // from invalidating the path before Wrangler opens it.
+        return withWranglerEnv(app, (envFile) => 
+        // `wrangler dev` auto-redirects to the just-built
+        // `dist/server/wrangler.json` (a "config redirect" vinext writes to
+        // `.wrangler/deploy/config.json`), so no `--config` flag is needed.
+        // The bundle is already built above; invoke the project's Wrangler
+        // directly so the scoped file becomes Worker vars.
+        run([
+            "--filter",
+            app,
+            "exec",
+            "wrangler",
+            "dev",
+            "--env-file",
+            envFile,
+        ]), { env: loaded?.env });
+    }
+    if (sub === "typegen") {
+        const { app, rest: remaining } = parseAppAndRest(rest);
+        if (!app) {
+            process.stderr.write("devtools cf typegen: --app <slug> is required.\n");
+            return 1;
+        }
+        if (!isWorkerApp(app)) {
+            process.stderr.write(`devtools cf typegen: unknown app "${app}". ${unknownAppHint()}\n`);
+            return 1;
+        }
+        const check = remaining.includes("--check");
+        const script = check ? "cf:typegen:check" : "cf:typegen";
+        return run(["--filter", app, "run", script]);
+    }
+    if (sub === "build") {
+        const { app } = parseAppAndRest(rest);
+        const tier = parseTier(rest);
+        if (!app) {
+            process.stderr.write("devtools cf build: --app <slug> is required.\n");
+            return 1;
+        }
+        if (!isWorkerApp(app)) {
+            process.stderr.write(`devtools cf build: unknown app "${app}". ${unknownAppHint()}\n`);
+            return 1;
+        }
+        if (!tier || (tier !== "staging" && tier !== "production")) {
+            process.stderr.write("devtools cf build: --tier <staging|production> is required.\n");
+            return 1;
+        }
+        return run(["--filter", app, "run", `cf:build:${tier}`]);
+    }
+    if (sub === "exec") {
+        // Everything after "exec" (or after "--") passes to wrangler
+        const wranglerArgs = rest[0] === "--" ? rest.slice(1) : rest;
+        return run(["exec", "wrangler", ...wranglerArgs]);
+    }
+    process.stderr.write(`devtools cf: unknown subcommand "${sub ?? "(none)"}". ` +
+        "Expected: preview, typegen, build, exec.\n");
+    return 1;
+}

package/dist/cf/local-env.d.ts

@@ -0,0 +1,44 @@
+import type { EnvEntry } from "@devdogsuga/env";
+export declare function renderWranglerEnvFile(keys: readonly string[], environment: NodeJS.ProcessEnv): string;
+/**
+ * Runs `fn` with the path to an app-scoped, mode-0600 `.dev.vars` file, and
+ * guarantees the file (and its containing directory) is gone before this
+ * resolves or rejects — including when `fn` throws, AND when a SIGINT/SIGTERM
+ * (e.g. the developer's Ctrl+C on a `wrangler dev` child `fn` is awaiting)
+ * arrives while `fn` is still running: without this, the signal kills the
+ * process before the `finally` below gets to run, leaving the credential-
+ * bearing temp directory behind in a world-findable location. Prefer this
+ * over `createTemporaryWranglerEnv` below for anything whose credential-
+ * bearing file's lifetime matches a single call's lifetime: a credential-
+ * bearing temp file can never outlive the call that needed it.
+ */
+export declare function withWranglerEnv<T>(app: string, fn: (envFilePath: string) => Promise<T>, options?: {
+    env?: NodeJS.ProcessEnv;
+    entries?: readonly EnvEntry[];
+}): Promise<T>;
+export interface TemporaryWranglerEnv {
+    path: string;
+    remove: () => void;
+}
+/**
+ * Create an app-scoped, mode-0600 env file for a local Worker runtime whose
+ * lifetime a single bracket callback cannot express.
+ *
+ * ⚠️ KEPT DELIBERATELY, not an oversight: `workflows/commands.ts` holds this
+ * file open across a long-lived `wrangler dev` child process, and in the
+ * `workflows run` temporary-session path that span crosses a `finally` that
+ * is unrelated to starting Wrangler at all — it also triggers a Workflow and
+ * polls for its completion before the session stops. Squeezing that into a
+ * single `withWranglerEnv` callback would mean merging two previously
+ * independent concerns (spinning up a dev session; triggering-and-waiting)
+ * into one control path, which is a real redesign of a 700-line orchestrator,
+ * not a mechanical bracket swap — and duplicating this function's
+ * retry/readiness loop across a bracket-shaped variant just to convert the
+ * `workflows serve` half would fragment one shared, tested implementation
+ * into two for no behavioural gain.
+ *
+ * `env` mirrors `withWranglerEnv`'s `options.env`: pass a tier's loaded map to
+ * materialize a scoped file from THAT tier rather than the inherited process
+ * environment; omit it to keep today's behavior.
+ */
+export declare function createTemporaryWranglerEnv(app: string, env?: NodeJS.ProcessEnv): Promise<TemporaryWranglerEnv>;

package/dist/cf/local-env.js

@@ -0,0 +1,148 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadEnv } from "../repo/peers.js";
+import { loadRegistry } from "../env/discovery.js";
+export function renderWranglerEnvFile(keys, environment) {
+    return (keys
+        .flatMap((key) => {
+        const value = environment[key];
+        // dotenv preserves single-quoted values byte-for-byte, including
+        // multiline private keys and literal backslash sequences.
+        return value === undefined ? [] : [`${key}='${value}'`];
+    })
+        .join("\n") + "\n");
+}
+/** The app's declared keys, deduped and sorted, from the given entries or the
+ * loaded registry.
+ *
+ * `DEPLOY_ENV` and `NODE_ENV` are excluded BY NAME, not by any registry-meta
+ * heuristic. Their committed source is wrangler.jsonc's per-env `vars` blocks
+ * (and the framework), never an env file — see each key's `define()` doc.
+ * Materializing them into the temp `.dev.vars` this file feeds to `wrangler
+ * dev` lets a stray or empty `.env` value OVERRIDE the tier's wrangler var,
+ * which surfaced as a Workflow isolate reading a blank `DEPLOY_ENV` and
+ * throwing "has no HYPERDRIVE binding".
+ *
+ * A `scope: "default"` + `commented: true` filter was tried first and is
+ * WRONG: that shape also matches `GITHUB_COMPETITION_REPO`, an opt-in
+ * override a contributor sets deliberately in their `.env` (its wrangler
+ * config defines no such var), and the heuristic silently stripped it from
+ * `wrangler dev`'s environment. Wrangler-ownership is a fact about
+ * wrangler.jsonc, not about registry metadata, so the two keys it is true
+ * for are named outright. */
+const WRANGLER_OWNED_KEYS = new Set(["DEPLOY_ENV", "NODE_ENV"]);
+async function scopedKeys(app, entries) {
+    if (!entries) {
+        await loadRegistry();
+        entries = (await loadEnv()).declarations();
+    }
+    return [
+        ...new Set(entries
+            .filter((entry) => entry.source === app)
+            .filter((entry) => !WRANGLER_OWNED_KEYS.has(entry.key))
+            .map((entry) => entry.key)),
+    ].sort();
+}
+/** Writes the mode-0600 `.dev.vars` into a fresh private temp directory. */
+function materializeEnvFile(keys, environment) {
+    const directory = mkdtempSync(join(tmpdir(), "devtools-wrangler-env-"));
+    const path = join(directory, ".dev.vars");
+    writeFileSync(path, renderWranglerEnvFile(keys, environment), {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    return { directory, path };
+}
+/** Signals a `wrangler dev` child normally dies to: Ctrl+C sends SIGINT, and
+ * SIGTERM is how a parent (or `kill`) asks any child to stop. Both bypass a
+ * `finally` block only if the process exits before it runs — which it
+ * doesn't here, since Node keeps running while a signal handler is
+ * registered — so installing one turns "the shell killed us" into an
+ * ordinary early return through the same `finally`. */
+const CLEANUP_SIGNALS = ["SIGINT", "SIGTERM"];
+/** Registers `cleanup` on SIGINT/SIGTERM for the duration of a bracket and
+ * returns a function that un-registers it. On signal, `cleanup` runs, the
+ * handler removes itself, and the signal is re-sent to this process so the
+ * default handler (absent any other listener) terminates it with the
+ * conventional 128+signal exit status — the caller's `fn` never resumes. */
+function installSignalCleanup(cleanup) {
+    const handlers = new Map();
+    for (const signal of CLEANUP_SIGNALS) {
+        const handler = () => {
+            cleanup();
+            process.off(signal, handler);
+            process.kill(process.pid, signal);
+        };
+        handlers.set(signal, handler);
+        process.on(signal, handler);
+    }
+    return () => {
+        for (const [signal, handler] of handlers)
+            process.off(signal, handler);
+    };
+}
+/**
+ * Runs `fn` with the path to an app-scoped, mode-0600 `.dev.vars` file, and
+ * guarantees the file (and its containing directory) is gone before this
+ * resolves or rejects — including when `fn` throws, AND when a SIGINT/SIGTERM
+ * (e.g. the developer's Ctrl+C on a `wrangler dev` child `fn` is awaiting)
+ * arrives while `fn` is still running: without this, the signal kills the
+ * process before the `finally` below gets to run, leaving the credential-
+ * bearing temp directory behind in a world-findable location. Prefer this
+ * over `createTemporaryWranglerEnv` below for anything whose credential-
+ * bearing file's lifetime matches a single call's lifetime: a credential-
+ * bearing temp file can never outlive the call that needed it.
+ */
+export async function withWranglerEnv(app, fn, options) {
+    const keys = await scopedKeys(app, options?.entries);
+    const { directory, path } = materializeEnvFile(keys, options?.env ?? process.env);
+    // Idempotent: the signal handler and the `finally` below can both fire
+    // (the handler runs cleanup, then re-raises the signal — which unwinds
+    // `fn` and reaches `finally` on its way out) and rmSync's `force: true`
+    // alone only suppresses ENOENT, not a guarantee against re-entrant calls.
+    let removed = false;
+    const cleanup = () => {
+        if (removed)
+            return;
+        removed = true;
+        rmSync(directory, { recursive: true, force: true });
+    };
+    const uninstall = installSignalCleanup(cleanup);
+    try {
+        return await fn(path);
+    }
+    finally {
+        uninstall();
+        cleanup();
+    }
+}
+/**
+ * Create an app-scoped, mode-0600 env file for a local Worker runtime whose
+ * lifetime a single bracket callback cannot express.
+ *
+ * ⚠️ KEPT DELIBERATELY, not an oversight: `workflows/commands.ts` holds this
+ * file open across a long-lived `wrangler dev` child process, and in the
+ * `workflows run` temporary-session path that span crosses a `finally` that
+ * is unrelated to starting Wrangler at all — it also triggers a Workflow and
+ * polls for its completion before the session stops. Squeezing that into a
+ * single `withWranglerEnv` callback would mean merging two previously
+ * independent concerns (spinning up a dev session; triggering-and-waiting)
+ * into one control path, which is a real redesign of a 700-line orchestrator,
+ * not a mechanical bracket swap — and duplicating this function's
+ * retry/readiness loop across a bracket-shaped variant just to convert the
+ * `workflows serve` half would fragment one shared, tested implementation
+ * into two for no behavioural gain.
+ *
+ * `env` mirrors `withWranglerEnv`'s `options.env`: pass a tier's loaded map to
+ * materialize a scoped file from THAT tier rather than the inherited process
+ * environment; omit it to keep today's behavior.
+ */
+export async function createTemporaryWranglerEnv(app, env) {
+    const keys = await scopedKeys(app);
+    const { directory, path } = materializeEnvFile(keys, env ?? process.env);
+    return {
+        path,
+        remove: () => rmSync(directory, { recursive: true, force: true }),
+    };
+}

package/dist/ci.d.ts

@@ -0,0 +1 @@
+export declare function main(argv: string[]): Promise<void>;