@devdogsuga/devtools 0.1.25 → 0.1.27

package/dist/deploy/require-planner.js

@@ -1,60 +0,0 @@
-/**
- * `pnpm devtools deploy require-planner`
- *
- * Refuses the §3.5 stage-1 dry run when its `DB_URL` is anything more than
- * the `migration_planner` role.
- *
- * The preflight credential is the one narrowed value NOTHING can verify at
- * rest: a full-access connection string pasted into `.env.preflight` works
- * identically. The dry run succeeds, `env push` uploads it cleanly, and
- * `env audit` reports no drift forever, because the stored value matches the
- * file it came from. Only a live connection shows the difference, so this
- * guard opens one: it must authenticate as the planner, it must FAIL to read
- * `platform.profile`, and it must succeed in reading the migrations table the
- * dry run is about to plan against. See `planner/checks.ts` for the three
- * checks; `planner create` runs the same ones, so a credential that passed at
- * minting time passes here.
- *
- * Runs in the `main-plan` job only. `production-plan` runs the same dry run
- * with the PRODUCTION environment's `DB_URL`, which is the full connection
- * string by design, since apps boot from it, so this guard would (correctly)
- * refuse there. The narrowing belongs to the preflight tier, not to the dry
- * run.
- *
- * Like the rest of the group: `cli:no-env` (the job holds one credential in
- * the step's `env:` block and composes no file), reports through `say()`
- * (stderr), refuses by `DeployError`. One line per check on success. This
- * runs as its own step, and three green lines are the evidence the §3.5
- * argument leans on.
- */
-import { checkPlanner } from "../planner/checks.js";
-import { connectDb } from "../planner/db.js";
-import { DeployError, say } from "./report.js";
-export async function runRequirePlanner(env = process.env, connect = connectDb) {
-    const url = env.DB_URL;
-    if (!url) {
-        throw new DeployError("DB_URL is not set — refusing to plan.", [
-            "This step runs with the preflight environment's DB_URL: the",
-            "migration_planner role, pushed by `env push --target preflight`.",
-            "An empty value usually means the environment secret was never",
-            "pushed, or the workflow step lost its env: block.",
-        ]);
-    }
-    const db = connect(url);
-    try {
-        const verdict = await checkPlanner(db);
-        for (const line of verdict.lines)
-            say([`require-planner: ${line}`]);
-        if (!verdict.ok) {
-            throw new DeployError(`refusing to plan: ${verdict.problem}`, [
-                "The preflight DB_URL must be the migration_planner role and no",
-                "more — this environment is reachable from `main`. Mint or repair",
-                "it with `pnpm devtools planner create` (or `planner status` to",
-                "see what is wrong), then `env push --target preflight`.",
-            ]);
-        }
-    }
-    finally {
-        await db.end();
-    }
-}

package/dist/deploy/require-token.d.ts

@@ -1,15 +0,0 @@
-/**
- * Refuses the deploy when `CLOUDFLARE_API_TOKEN` is absent, and says nothing
- * when it is set.
- *
- * The silence is deliberate: it stands in front of a deploy inside an `&&`
- * chain, and a guard that announces itself on every run is a guard people stop
- * reading. The refusal is the only thing it has to say.
- *
- * It refuses by throwing rather than by returning a code so that `cli.ts`
- * renders it like every other deploy failure, through `say()`, which is
- * stderr, never `explain()`, which is clack and therefore stdout.
- *
- * @throws {DeployError} when `CLOUDFLARE_API_TOKEN` is absent or empty.
- */
-export declare function runRequireToken(env?: Record<string, string | undefined>): void;

package/dist/deploy/require-token.js

@@ -1,78 +0,0 @@
-/**
- * `pnpm devtools deploy require-token`
- *
- * Refuses a Cloudflare deploy when `CLOUDFLARE_API_TOKEN` is absent. Without
- * it, wrangler falls back to an interactive browser OAuth prompt, which on a
- * contributor's machine reads as an invitation to authenticate. The policy
- * (design doc §9) is that only devops hold the token and nobody else deploys.
- *
- * ## ⚠️ Invoke it through `cli:no-env`, never through `cli`
- *
- * This is a GUARD, not a command anybody types. It runs in two shapes, and
- * `cli` (`with-env tsx src/cli.ts`) is wrong for both:
- *
- *   * **Inside the deploy's own `with-env -c '...'` string**, in
- *     `apps/{platform,schedule-builder,sandbox}/package.json`:
- *
- *       DEPLOY_ENV=production with-env -c '<guard> && wrangler deploy -e production'
- *
- *     The guard must run after with-env loads the env files, because the token
- *     lives in a devops `.env.production` and never in the ambient
- *     environment. `guard && with-env deploy` would check the wrong
- *     environment; `with-env guard && deploy` would drop the loaded env for
- *     the deploy itself. `-c` gives both commands the same loaded env, and it
- *     evaluates through @yarnpkg/shell, so the `&&` chain works identically on
- *     Windows and POSIX. The env is therefore ALREADY LOADED by the time the
- *     guard runs; a second `with-env` inside it re-loads the same files to no
- *     effect and prints a second `with-env: loaded ...` line, which makes the
- *     deploy log claim the environment was selected twice.
- *
- *   * **Bare, in CI**, in the orphan-audit and prune jobs, which run with no
- *     env file at all, on purpose: they read secret NAMES from Cloudflare and
- *     need exactly one credential to do it. Here `cli` is an outright bug.
- *     With no `.env*` present, `with-env` raises `MissingEnvFileError` and
- *     exits 1 BEFORE this code runs, so the guard would refuse the deploy
- *     while reporting a missing file instead of a missing token. The wrong
- *     diagnosis, on the failure path, which is the only path anybody reads.
- *
- * `cli:no-env` (`tsx --conditions=devdogs-source src/cli.ts`) is the seam for
- * both: it loads no env of its own and reads whatever the caller already put
- * in `process.env`. Verified by running `pnpm --filter @devdogsuga/devtools
- * run cli:no-env` inside a real `with-env -c` string, where it resolves
- * through @yarnpkg/shell and adds no second env-selection line.
- *
- * Nesting `with-env` is otherwise HARMLESS: dotenvx leaves values already in
- * the environment alone, so the inner load re-reads the same files and changes
- * nothing. The objection is the missing-file case above and the duplicated
- * `with-env: loaded ...` line, not a wrong value.
- *
- * `cf:build:*` scripts deliberately do NOT run this: building needs no token.
- */
-import { DeployError } from "./report.js";
-/**
- * Refuses the deploy when `CLOUDFLARE_API_TOKEN` is absent, and says nothing
- * when it is set.
- *
- * The silence is deliberate: it stands in front of a deploy inside an `&&`
- * chain, and a guard that announces itself on every run is a guard people stop
- * reading. The refusal is the only thing it has to say.
- *
- * It refuses by throwing rather than by returning a code so that `cli.ts`
- * renders it like every other deploy failure, through `say()`, which is
- * stderr, never `explain()`, which is clack and therefore stdout.
- *
- * @throws {DeployError} when `CLOUDFLARE_API_TOKEN` is absent or empty.
- */
-export function runRequireToken(env = process.env) {
-    if (env.CLOUDFLARE_API_TOKEN)
-        return;
-    throw new DeployError("CLOUDFLARE_API_TOKEN is not set — refusing to deploy.", [
-        "Cloudflare access is devops-only (design doc §9). Without this guard",
-        "wrangler falls back to an interactive browser login, which looks like",
-        "an invitation to authenticate rather than the refusal it should be.",
-        "",
-        "Ask the devops team to run this deploy. If you are joining them, the",
-        "token lives in the devops .env.production:",
-        "  pnpm devtools env pull --target production",
-    ]);
-}

package/dist/deploy/secrets-file.d.ts

@@ -1,17 +0,0 @@
-export interface SecretsFileOptions {
-    /** `--app`: the workspace app whose manifest names the Worker's secrets. */
-    app: string;
-    /** Defaults to the ambient environment; a parameter so tests need not mutate it. */
-    env?: NodeJS.ProcessEnv;
-}
-export interface SecretsFileResult {
-    /** The 0700 directory holding the file; the caller removes it. */
-    dir: string;
-    /** The 0600 file itself. */
-    file: string;
-    /** Names sent, in registry order. Never values. */
-    keys: string[];
-    /** Declared, optional, and absent from the environment. Reported, not fatal. */
-    omitted: string[];
-}
-export declare function runDeploySecretsFile(options: SecretsFileOptions): Promise<SecretsFileResult>;

package/dist/deploy/secrets-file.js

@@ -1,166 +0,0 @@
-/**
- * `devtools deploy secrets-file --app <app>`
- *
- * Composes the `--secrets-file` a `wrangler deploy` uploads with one Worker.
- *
- * Runs INSIDE `with-env`, invoked as the ordinary
- * `pnpm devtools deploy secrets-file …`, so `process.env` is the environment
- * `devtools deploy write-env` composed a few steps earlier. `write-env` is the
- * one command in this group that has to bypass the wrapper. This one reads no
- * GitHub context of its own: one place in the pipeline touches `secrets` and
- * `vars`, and this is not it.
- *
- * ## Which keys, and why they are derived rather than listed
- *
- * `storableKeys()` intersected with the keys the app's own manifest declares.
- * A hand-written list per Worker is the exact failure the registry was built
- * to remove: a variable added to `src/env.ts` and forgotten in the list is
- * simply absent from the deployed environment, and the first thing that reads
- * it fails at run time in production.
- *
- * Two exclusions follow from that rule rather than being special cases:
- *
- *   * `:tooling` sources — declared for the deploy pipeline itself, not for
- *     the Worker. `study-group-finder:tooling` declares `SECRET_KEY` for
- *     supadart, which runs on a laptop. A key the deploy needs is not
- *     automatically a key the WORKER needs, and sending one anyway hands an
- *     internet-facing Worker a credential it never asks for.
- *   * `client: true` declarations, inlined into the browser bundle at build
- *     time and not Worker secrets at all (§A.6.3).
- *
- * ## ⚠️ Always the complete set
- *
- * `wrangler deploy --secrets-file` applies ADDITIVELY: it preserves every
- * secret it does not mention, which may be one another environment set. A
- * partial file inherits stale values silently rather than failing. So this
- * sends everything the app declares, every time, and `devtools deploy orphans`
- * reports whatever the Worker is still holding that nothing declares any more.
- *
- * ## Minted keys are refused, not filled
- *
- * A `secrecy: "secret"` key `storableKeys()` excludes is "minted": signed at
- * deploy time rather than stored anywhere, which is what `SANDBOX_PROXY_TOKEN`
- * is declared as. This command has no minter of its own — there is nothing in
- * this repository that produces one — so a declared minted key is always a
- * hard failure here rather than a silent omission: a Worker that expects a
- * value substituted fails loudly at the file it never got, not at whatever
- * reads it.
- *
- * ## Interface
- *
- *   DEPLOY_ENV=production pnpm devtools deploy secrets-file --app platform
- *
- * Writes `dir=` and `file=` to `$GITHUB_OUTPUT`. The caller removes `dir` in an
- * `if: always()` step. The runner is ephemeral, so this matters on a
- * self-hosted one and costs nothing on a hosted one.
- */
-import { mkdtempSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { assertRegistryLoaded } from "../env/discovery.js";
-import { getEnvSync } from "../repo/peers.js";
-import { DeployError, say, summary } from "./report.js";
-/**
- * Declared by this app, for this app's Worker.
- *
- * `source` is the manifest that declared it, and a `:` suffix is the repo's
- * existing convention for "declared here, but not part of the running thing".
- * See `sectionOf()` in devtools' `env/example.ts`, which folds the two together
- * for display and keeps them distinct everywhere else.
- */
-function declaredBy(entries, app) {
-    return entries.some((e) => e.source === app && !e.client);
-}
-export async function runDeploySecretsFile(options) {
-    assertRegistryLoaded();
-    const { app } = options;
-    const env = options.env ?? process.env;
-    const storable = new Set(getEnvSync().storableKeys());
-    const send = new Map();
-    const absent = [];
-    const minted = [];
-    for (const [key, entries] of getEnvSync().variables()) {
-        if (!declaredBy(entries, app))
-            continue;
-        const meta = entries[0].meta;
-        // Public server keys ship alongside the secrets because a value that was
-        // only in the composed .env file at build time is absent from the deployed
-        // Worker's runtime environment. The first staging deploy proved it: the
-        // schedule-builder Worker booted without API_URL, REST_URL,
-        // PUBLISHABLE_KEY, STORAGE_S3_URL or S3_PROTOCOL_REGION and answered 500
-        // on every route. Client (NEXT_PUBLIC) keys are excluded by `declaredBy`
-        // (inlined at build); never-store keys stay excluded because a Worker
-        // secret is a remote copy, the thing they forbid.
-        if (meta.secrecy === "secret") {
-            if (!storable.has(key)) {
-                minted.push(key);
-                continue;
-            }
-        }
-        else if (meta.secrecy !== "public") {
-            continue;
-        }
-        const value = env[key];
-        if (value === undefined || value === "") {
-            absent.push(key);
-            continue;
-        }
-        send.set(key, value);
-    }
-    // Absent is reported, not fatal. `deploy write-env` already failed the job
-    // for anything an app's schema requires, so what reaches here is optional by
-    // declaration, `OAUTH_CLIENT_SECRET` on a deployment that uses the built-in
-    // provider, say. Sending an empty string instead would be worse than omitting
-    // it: every consumer that checks for presence would read it as configured.
-    if (absent.length > 0) {
-        say([
-            `devtools deploy secrets-file: ${absent.length} optional key(s) have ` +
-                `no value and are omitted: ${absent.join(", ")}`,
-        ]);
-    }
-    if (minted.length > 0) {
-        throw new DeployError(`${app} declares minted secret(s) with nothing to mint them: ${minted.join(", ")}.`, [
-            "This command has no minter — nothing in this repository mints a",
-            "secret. Drop the `minted: true` declaration from the app's",
-            "env.ts, or the Worker deploys without it and keeps whatever the",
-            "previous deploy left — --secrets-file preserves omissions.",
-        ]);
-    }
-    if (send.size === 0) {
-        throw new DeployError(`${app} has no Worker secrets to send.`, [
-            "That is almost certainly wrong: a --secrets-file with nothing in it",
-            "would leave every previously set secret in place, unexamined.",
-        ]);
-    }
-    // mkdtemp gives 0700 on every platform Node supports; the mode is repeated
-    // anyway so the intent survives a reader who does not know that. RUNNER_TEMP
-    // is cleared between jobs on a hosted runner and is the documented place for
-    // this on a self-hosted one.
-    const dir = mkdtempSync(join(env.RUNNER_TEMP ?? tmpdir(), "deploy-secrets-"));
-    const file = join(dir, `${app}.json`);
-    writeFileSync(file, `${JSON.stringify(Object.fromEntries(send), null, 2)}\n`, { mode: 0o600 });
-    const out = env.GITHUB_OUTPUT;
-    if (out)
-        writeFileSync(out, `dir=${dir}\nfile=${file}\n`, { flag: "a" });
-    const keys = [...send.keys()];
-    say([
-        `devtools deploy secrets-file: ${send.size} secret(s) for ${app} -> ${file}`,
-        ...keys.map((k) => `  ${k}`),
-    ]);
-    // Names go to the job summary as well as the log, because this list IS every
-    // credential the Worker holds. Reading it should not require expanding a
-    // step: "why does this Worker hold that?" is exactly the question a
-    // per-deploy record makes answerable, and the answer lives in the app's
-    // manifest rather than anywhere in this pipeline.
-    summary([
-        `### Worker secrets sent to \`${app}\``,
-        "",
-        ...keys.map((key) => `* \`${key}\``),
-        "",
-        "Names only. The complete set is sent every deploy, because",
-        "`--secrets-file` preserves what it omits.",
-        "",
-        "",
-    ], env);
-    return { dir, file, keys, omitted: absent };
-}

package/dist/deploy/write-env.d.ts

@@ -1,40 +0,0 @@
-/** Where a value came from, for the provenance table. */
-export type Provenance = "secret" | "variable" | "derived" | "committed";
-export interface WriteEnvOptions {
-    /** `--source`: compose only what this manifest declares. */
-    source?: string | null;
-    /**
-     * Directory the env file is written into.
-     *
-     * The CLI always passes the project root, which is what the workflow means.
-     * It is a parameter so the tests can compose into a temporary directory:
-     * the real destinations are `.env.staging` and `.env.production`, which on a
-     * maintainer's laptop are the files being filled in with live credentials.
-     */
-    root?: string;
-    /** Defaults to the ambient environment; a parameter so tests need not mutate it. */
-    env?: NodeJS.ProcessEnv;
-}
-export interface WriteEnvResult {
-    /** The file that was written, relative to `root`. */
-    file: string;
-    /** Key → where its value came from, in the order they were written. */
-    provenance: Map<string, Provenance>;
-}
-/**
- * Composes the file and writes it.
- *
- * Every refusal is a `DeployError`, and every one of them ALSO lands in the job
- * summary, via the wrapper below. That is deliberate here and not for the other
- * commands in the group: the failure mode this exists to catch is a missing
- * credential, and the person who has to add it is reading the run page rather
- * than a step's log.
- */
-export declare function runDeployWriteEnv(options?: WriteEnvOptions): Promise<WriteEnvResult>;
-/**
- * The line the job log gets: names and provenance only.
- *
- * Never a value, and never a fingerprint either. A fingerprint helps when
- * comparing two stores by hand, and there is nothing here to compare against.
- */
-export declare function renderWriteEnvReport(result: WriteEnvResult): string[];