@devdogsuga/devtools 0.1.0

package/dist/ci.js

@@ -0,0 +1,319 @@
+/**
+ * `devtools-ci deploy <app|step> [flags]`
+ *
+ * The CI entry point. No wizard and no `@clack/prompts`. Commands that create
+ * the deploy env file run through the bare `ci` package script; commands that
+ * consume that file run through `ci:env`, which wraps this same entry point in
+ * `with-env`. Every command runs in GitHub Actions and reports failures by
+ * exiting non-zero.
+ *
+ * ## Why a separate bin
+ *
+ * The contributor CLI (`devtools`) prompts interactively and wraps output in
+ * clack's box-drawing. None of that belongs in a deploy job. This entry point
+ * never imports clack, so a caller that pipes its stdout is never surprised by
+ * a banner landing on that stream. `with-env` reports its selected file on
+ * stderr, leaving the command's stdout protocol intact.
+ *
+ * ## The deploy orchestrator
+ *
+ * `devtools-ci deploy <app> --tier <staging|production>` replaces the three
+ * near-identical `cf:deploy:*` shell strings in the app package.json files.
+ * It runs `require-token`, then the app-specific deploy commands: docs index
+ * for platform only, then a plain `wrangler deploy` for all three apps.
+ * Both Next.js apps are on vinext now -- deploy-app.yaml's separate "Build"
+ * step already ran `vinext build` (`cf:build:$DEPLOY_ENV`), which leaves a
+ * Wrangler "config redirect" at `.wrangler/deploy/config.json` pointing at
+ * the generated `dist/server/wrangler.json`; a bare `wrangler deploy` from
+ * the app dir resolves through that redirect with no `--config` needed.
+ * Sandbox (plain Worker, wrangler bundles it at deploy time) always used
+ * this shape, so all three apps now share one deploy step.
+ *
+ * Step commands (`write-env`, `secrets-file`, etc.) are still individually
+ * addressable for jobs that run only one step.
+ */
+import { spawn } from "node:child_process";
+import { loadEnvLoad } from "./repo/peers.js";
+import { DeployError, say } from "./deploy/report.js";
+import { renderWriteEnvReport, runDeployWriteEnv } from "./deploy/write-env.js";
+import { runDeploySecretsFile } from "./deploy/secrets-file.js";
+import { runDeployOrphans } from "./deploy/orphans.js";
+import { runPreflight } from "./deploy/preflight.js";
+import { runDeployMigrate, runDeployPlan } from "./deploy/migrations.js";
+import { runRequirePlanner } from "./deploy/require-planner.js";
+import { runRequireToken } from "./deploy/require-token.js";
+import { runDocsIndex } from "./docs/index-pages.js";
+import { loadRegistry } from "./env/discovery.js";
+import { positionals } from "./args.js";
+import { findCiCommand, subcommandCiNames } from "./commands.js";
+import { isWorkerApp, workerApps } from "./workers.js";
+import { captureDevtoolsError, initDevtoolsTelemetry } from "./telemetry.js";
+function flagValue(rest, flag) {
+    const index = rest.indexOf(flag);
+    if (index === -1)
+        return undefined;
+    const value = rest[index + 1];
+    return value && !value.startsWith("--") ? value : undefined;
+}
+function isApp(value) {
+    return isWorkerApp(value);
+}
+/**
+ * Wrangler's local Hyperdrive emulator wants its binding-specific alias, not
+ * `DB_URL`. Mirror both of `process.env`'s relevant keys into a scratch
+ * object so the shared `applyWranglerLocalDatabaseAlias` guard — never
+ * clobber an alias someone already set — runs against the same values it
+ * would in-process, then hand back only the alias override for `pnpm()`'s
+ * env merge (`DB_URL` itself reaches the child already, via the base
+ * `process.env` spread).
+ */
+async function hyperdriveLocalAliasEnv() {
+    const { applyWranglerLocalDatabaseAlias, HYPERDRIVE_LOCAL_CONNECTION_ENV } = await loadEnvLoad();
+    const scratch = {};
+    const existingAlias = process.env[HYPERDRIVE_LOCAL_CONNECTION_ENV];
+    if (existingAlias !== undefined) {
+        scratch[HYPERDRIVE_LOCAL_CONNECTION_ENV] = existingAlias;
+    }
+    if (process.env.DB_URL !== undefined)
+        scratch.DB_URL = process.env.DB_URL;
+    applyWranglerLocalDatabaseAlias(scratch);
+    delete scratch.DB_URL;
+    return scratch;
+}
+/**
+ * Runs a command via pnpm, inheriting stdio, returning the exit code.
+ *
+ * All orchestrator steps are external processes rather than imported
+ * functions: `wrangler` (and, for platform, the docs build) own their own
+ * stdout and must not be wrapped.
+ */
+function pnpm(args, env) {
+    return new Promise((resolve) => {
+        const child = spawn("pnpm", args, {
+            stdio: "inherit",
+            env: { ...process.env, ...env },
+        });
+        child.on("exit", (code) => resolve(code ?? 1));
+    });
+}
+/**
+ * `devtools-ci deploy <app> --tier <staging|production>`
+ *
+ * Orchestrates the full deploy for one app:
+ *   1. `require-token` guard
+ *   2. Docs index (platform only)
+ *   3. App deploy via `wrangler deploy`
+ *
+ * The `--dry-run` flag prints what would run and exits 0.
+ */
+async function runAppDeploy(app, rest) {
+    const tier = flagValue(rest, "--tier") ?? process.env.DEPLOY_ENV;
+    if (!tier) {
+        throw new DeployError("--tier <staging|production> is required.", [
+            "Or set DEPLOY_ENV in the environment.",
+        ]);
+    }
+    if (tier !== "staging" && tier !== "production") {
+        throw new DeployError(`Unknown tier "${tier}".`, [
+            "Use --tier staging or --tier production.",
+        ]);
+    }
+    const dryRun = rest.includes("--dry-run");
+    const secretsFile = process.env.DEPLOY_SECRETS_FILE;
+    const steps = [];
+    // Platform is the only app with a prestep: it owns the docs site, so its
+    // deploy re-indexes the (already-built-elsewhere) docs into the remote
+    // search store before the Worker goes out.
+    if (app === "platform") {
+        steps.push({
+            label: "Index docs",
+            fn: async () => {
+                const buildCode = await pnpm(["--filter", "@devdogsuga/docs", "build"]);
+                if (buildCode !== 0)
+                    return buildCode;
+                const before = process.exitCode;
+                process.exitCode = 0;
+                await runDocsIndex({ target: "remote" });
+                const code = process.exitCode === 0 ? 0 : 1;
+                process.exitCode = before;
+                return code;
+            },
+        });
+    }
+    // All three apps now share one deploy shape: a bare `wrangler deploy -e
+    // <tier>` from the app directory. Both Next.js apps' target environment is
+    // baked in at BUILD time (deploy-app.yaml's separate "Build" step already
+    // ran `cf:build:$DEPLOY_ENV`, i.e. `vinext build` with
+    // `CLOUDFLARE_ENV=$tier`), which leaves a Wrangler "config redirect" at
+    // `.wrangler/deploy/config.json` pointing at `dist/server/wrangler.json`;
+    // sandbox is a plain Worker with no such redirect and no build step at all.
+    // `-e` is passed regardless: for the vinext apps, Wrangler cross-checks it
+    // against the environment the build was tagged with and errors loudly on a
+    // mismatch, rather than silently deploying the wrong tier.
+    const deployArgs = [
+        "--filter",
+        app,
+        "exec",
+        "wrangler",
+        "deploy",
+        "-e",
+        tier,
+    ];
+    if (secretsFile)
+        deployArgs.push("--secrets-file", secretsFile);
+    // See apps/*/cloudflare/worker.ts's `WorkerEnv` doc: `SENTRY_RELEASE` is
+    // the deploy's git SHA, minted fresh by CI every run rather than a value
+    // Bitwarden holds, so it reaches the Worker as a `--var` here rather than
+    // through `~/env`'s schema or the secrets file above. Absent outside a
+    // CI-driven deploy.
+    if (process.env.SENTRY_RELEASE) {
+        deployArgs.push("--var", `SENTRY_RELEASE:${process.env.SENTRY_RELEASE}`);
+    }
+    steps.push({
+        label: `Deploy ${app} (${tier})`,
+        // sandbox has no Hyperdrive binding, so the local-database alias is a
+        // no-op for it; passing it unconditionally keeps this one step shape for
+        // all three apps rather than branching again just to omit it.
+        fn: async () => pnpm(deployArgs, await hyperdriveLocalAliasEnv()),
+    });
+    if (dryRun) {
+        say([
+            `devtools-ci deploy ${app} --tier ${tier} --dry-run`,
+            ...steps.map((s) => `  ${s.label}`),
+        ]);
+        return;
+    }
+    // require-token guard: checked inline so the step list above prints on
+    // --dry-run without requiring the token.
+    runRequireToken();
+    for (const step of steps) {
+        const code = await step.fn();
+        if (code !== 0) {
+            process.exitCode = code;
+            return;
+        }
+    }
+}
+// ── Deploy dispatch ───────────────────────────────────────────────────────────
+async function runDeployCommand(rest) {
+    const [sub] = positionals(rest);
+    if (!sub) {
+        const steps = subcommandCiNames(["deploy"]);
+        const width = Math.max(...steps.map((name) => name.length)) + 2;
+        say([
+            "devtools-ci deploy: which step or app?",
+            ...steps.map((name) => `  ${name.padEnd(width)}${findCiCommand(["deploy", name]).summary}`),
+        ]);
+        process.exitCode = 1;
+        return;
+    }
+    // App orchestrators
+    if (isApp(sub)) {
+        await runAppDeploy(sub, rest.slice(1));
+        return;
+    }
+    try {
+        if (sub === "require-token") {
+            runRequireToken();
+            return;
+        }
+        if (sub === "require-planner") {
+            await runRequirePlanner();
+            return;
+        }
+        if (sub === "plan") {
+            await runDeployPlan(flagValue(rest, "--label"));
+            return;
+        }
+        if (sub === "migrate") {
+            await runDeployMigrate();
+            return;
+        }
+        if (sub === "preflight") {
+            await runPreflight();
+            return;
+        }
+        await loadRegistry();
+        if (sub === "write-env") {
+            const index = rest.indexOf("--source");
+            const source = index === -1 ? null : rest[index + 1];
+            if (index !== -1 && (!source || source.startsWith("--"))) {
+                throw new DeployError("--source needs a manifest name, e.g. --source supabase.");
+            }
+            const result = await runDeployWriteEnv({ source });
+            say(renderWriteEnvReport(result));
+            return;
+        }
+        if (sub === "secrets-file") {
+            const app = flagValue(rest, "--app");
+            if (!app) {
+                throw new DeployError("--app <name> is required.", [
+                    "It names the workspace app whose manifest declares the Worker's",
+                    `secrets — ${workerApps().join(", ")}.`,
+                ]);
+            }
+            await runDeploySecretsFile({ app });
+            return;
+        }
+        if (sub === "orphans") {
+            await runDeployOrphans({ prune: rest.includes("--prune") });
+            return;
+        }
+        say([`devtools-ci deploy: unknown subcommand "${sub}".`]);
+        process.exitCode = 1;
+    }
+    catch (err) {
+        say(err instanceof DeployError
+            ? [
+                `devtools-ci deploy ${sub}: ${err.message}`,
+                ...err.detail.map((line) => `  ${line}`),
+            ]
+            : [
+                `devtools-ci deploy ${sub}: ${err instanceof Error ? err.message : String(err)}`,
+            ]);
+        process.exitCode = 1;
+    }
+}
+// ── Entry ─────────────────────────────────────────────────────────────────────
+export async function main(argv) {
+    const [first, ...rest] = argv;
+    // Same bootstrap point as `cli.ts`'s `main()`: after `argv` is split, before
+    // any dispatch below. `[first, rest[0]]` names the step (`deploy
+    // secrets-file`, `deploy platform`, …) as the `command` tag rather than just
+    // "deploy", which every invocation here would otherwise share.
+    initDevtoolsTelemetry([first, rest[0]].filter(Boolean).join(" ") || "help");
+    if (!first || first === "--help" || first === "-h") {
+        const steps = subcommandCiNames(["deploy"]);
+        const width = Math.max(...steps.map((name) => name.length)) + 2;
+        process.stdout.write([
+            "devtools-ci <command>",
+            "",
+            "Commands:",
+            `  ${"deploy".padEnd(width)}Deploy an app or run a deploy step.`,
+            "",
+            "Run `devtools-ci deploy` for the full step list.",
+            "",
+        ].join("\n"));
+        return;
+    }
+    if (first === "deploy") {
+        await runDeployCommand(rest);
+        return;
+    }
+    process.stderr.write(`devtools-ci: unknown command "${first}".\n`);
+    process.exitCode = 1;
+}
+// Run only from `src/launch-ci.ts` (via the `devtools-ci` bin) or from a
+// bare `run ci` package script for the steps that must not go through
+// `with-env`'s replacement at all — see that file's header. Never
+// self-invoking here: importing this module must not run anything, so
+// `launch-ci.ts` can resolve the deploy tier and enter its environment
+// first.
+if (import.meta.url === `file://${process.argv[1]}`) {
+    main(process.argv.slice(2)).catch(async (err) => {
+        process.stderr.write(`devtools-ci: ${err instanceof Error ? err.message : String(err)}\n`);
+        // Report BEFORE exiting — see `captureDevtoolsError`'s header.
+        await captureDevtoolsError(err);
+        process.exitCode = 1;
+    });
+}

package/dist/cli.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Runs the CLI against an already-resolved argv.
+ *
+ * Exported rather than run at import, so `src/launch.ts` can resolve the
+ * deploy tier and enter its environment BEFORE this module's imports (and the
+ * commands they pull in) ever see `process.env` — see that file's header. The
+ * shebang above stays harmless: importing this module runs nothing, only
+ * `main()` does, and nothing calls it but `launch.ts` and the `import.meta.url`
+ * guard at the bottom of this file, for a direct `tsx src/cli.ts` run.
+ */
+export declare function main(argv: string[]): Promise<void>;