@rexezuge/tooling 0.0.0-stage → 1.0.0

package/src/scripts/init-secrets.ts

@@ -0,0 +1,265 @@
+#!/usr/bin/env tsx
+/**
+ * Create the Secrets Store entries declared in `wrangler.jsonc`, generating a fresh
+ * value for each one that does not exist yet.
+ *
+ * Provenance: Edge-Sonic's `scripts/deploy/init-secrets.ts` and Durable-DAV's
+ * `scripts/init-secrets.ts`, converged. Both record the same two defects that hid
+ * a broken deploy for a whole release, and both fixes are carried over.
+ *
+ * ### Why this script exists at all
+ *
+ * A `secrets_store_secrets` binding fails the deploy unless the named secret
+ * already exists inside the named store. Nothing creates it: Cloudflare will not
+ * generate a value, and the template cannot carry one. So this script is the only
+ * thing standing between a fresh account and a deploy that cannot succeed.
+ *
+ * ### The two defects that hid a broken deploy
+ *
+ * **The generator list was stale.** Durable-DAV's copy carried an allowlist of
+ * exact names from the repository it was inherited from, all deleted when the repo
+ * was renamed, so the very first iteration threw `Unknown secret` and never created
+ * anything. So the rule here is the secret's **name shape**, not a list of names:
+ * `*-encryption-key` gets a generated AES-GCM key and `*-signing-secret` gets 32
+ * random bytes. Adding a secret to the template is then a one-line change needing
+ * no matching edit here, which is the property the exact-name list did not have.
+ *
+ * **The throw was swallowed.** The original ended in `main().catch(console.error)`.
+ * `console.error` returns `undefined` and never sets an exit status, so the process
+ * exited **0** and CI marked the step green — the failure only surfaced one step
+ * later, as an unexplainable `wrangler deploy` failure. Hence: the whole plan is
+ * validated **before** any Cloudflare call, and a rejection reaches the runner as
+ * a non-zero exit with a workflow annotation.
+ *
+ * ### Create-if-absent is a correctness property, not laziness
+ *
+ * An existing secret is left untouched. A replication encryption key seals every
+ * remote target's credential; regenerating it on a redeploy would strand them all
+ * as undecryptable. Rotation has to be a deliberate act with a re-encrypt path,
+ * not a side effect of deploying.
+ *
+ * Requires a materialized `wrangler.jsonc` — run
+ * `scripts/prepare-wrangler-config.ts` first. Fails rather than skipping when the
+ * config is missing, because a step reporting "Secret initialization complete"
+ * having created nothing is worse than a named error.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { parse } from 'jsonc-parser';
+import { fail } from './lib/github-actions';
+import { isEmptySecretsStoreListing, parseWranglerNames } from './lib/wrangler-table';
+import { CONFIG_PATH, type WranglerConfig } from './wrangler-config/types';
+
+/**
+ * The secret names the AES-GCM key generator produces, matched by **shape**.
+ *
+ * Keyed on the suffix because the alternative is the exact-name map that went
+ * stale. See the header: a template naming `*-encryption-key` is then a one-line
+ * change with no matching edit here, and a new secret breaks the deploy loudly
+ * instead of silently.
+ */
+const ENCRYPTION_KEY_SUFFIX = '-encryption-key';
+
+/** The secret names the random signing secret generator produces. */
+const SIGNING_SECRET_SUFFIX = '-signing-secret';
+
+/** A 256-bit AES-GCM key, base64-encoded — the shape the worker's crypto layer accepts. */
+async function generateAESGCMKey(): Promise<string> {
+  const key = await crypto.subtle.generateKey({ name: 'AES-GCM', length: 256 }, true, ['encrypt', 'decrypt']);
+  const exported = await crypto.subtle.exportKey('raw', key);
+  // Chunked rather than spread: `String.fromCharCode(...bytes)` passes 32 arguments,
+  // which is fine today and is a stack overflow the day the key is longer.
+  let binary = '';
+  for (const byte of new Uint8Array(exported)) {
+    binary += String.fromCodePoint(byte);
+  }
+  return btoa(binary);
+}
+
+/** A 256-bit random signing secret for internal self-calls, hex-encoded. */
+function generateSigningSecret(): Promise<string> {
+  let hex = '';
+  for (const byte of crypto.getRandomValues(new Uint8Array(32))) {
+    hex += byte.toString(16).padStart(2, '0');
+  }
+  return Promise.resolve(hex);
+}
+
+/**
+ * The generator for a secret name, chosen by the name's shape.
+ *
+ * A name matching neither is still refused rather than given a guess: the generator
+ * is not the only thing that has to be right, and an unusable value that looks
+ * provisioned is worse than a failure.
+ */
+function generatorFor(secretName: string): () => Promise<string> {
+  if (secretName.endsWith(ENCRYPTION_KEY_SUFFIX)) return generateAESGCMKey;
+  if (secretName.endsWith(SIGNING_SECRET_SUFFIX)) return generateSigningSecret;
+  throw new Error(
+    `Unknown secret: ${secretName}. Name it '*-encryption-key' for a generated 32-byte AES-GCM key, ` +
+      `or '*-signing-secret' for 32 random bytes, and teach this script the shape if neither fits.`,
+  );
+}
+
+/** Whether this script can produce a value for `secretName`. */
+export function canProvisionSecret(secretName: string): boolean {
+  try {
+    generatorFor(secretName);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Runs a wrangler subcommand, optionally feeding `input` on stdin.
+ *
+ * Arguments are passed as an argv array rather than interpolated into a shell
+ * string, so a value containing shell metacharacters cannot alter the command.
+ */
+function wrangler(args: readonly string[], input?: string): string {
+  try {
+    // eslint-disable-next-line sonarjs/no-os-command-from-path
+    return execFileSync('pnpm', ['exec', 'wrangler', ...args], {
+      encoding: 'utf8',
+      stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'],
+      ...(input !== undefined && { input }),
+    });
+  } catch (error: unknown) {
+    const maybeProcessError = error as { stdout?: string | Buffer; stderr?: string | Buffer; message?: string };
+    const stdout: string = maybeProcessError.stdout ? maybeProcessError.stdout.toString() : '';
+    const stderr: string = maybeProcessError.stderr ? maybeProcessError.stderr.toString() : '';
+    throw new Error(`Command failed: pnpm exec wrangler ${args.join(' ')}\n${stdout}${stderr || maybeProcessError.message || ''}`);
+  }
+}
+
+function parseWranglerConfig(): WranglerConfig {
+  if (!existsSync(CONFIG_PATH)) {
+    throw new Error(
+      `${CONFIG_PATH} not found. Run scripts/prepare-wrangler-config.ts first — it is what creates the file this script reads.`,
+    );
+  }
+  // `parse` is error-tolerant and returns a partial object, so an empty result means
+  // malformed JSON rather than "no secrets declared". Treating that as an empty list
+  // would report success having created nothing.
+  const config = parse(readFileSync(CONFIG_PATH, 'utf8')) as WranglerConfig;
+  if (config.secrets_store_secrets === undefined && Object.keys(config).length === 0) {
+    throw new Error(`${CONFIG_PATH} is empty or not valid JSONC. Run scripts/prepare-wrangler-config.ts to regenerate it.`);
+  }
+  return config;
+}
+
+/** One secret to create, as the plan names it. */
+interface PlannedSecret {
+  storeId: string;
+  secretName: string;
+}
+
+/**
+ * Turn the config's bindings into a validated work list.
+ *
+ * Every entry is checked *before* the first Cloudflare call, so an
+ * unprovisionable secret fails the step in milliseconds instead of after some other
+ * secret has already been created.
+ */
+export function planSecrets(config: WranglerConfig): PlannedSecret[] {
+  const plan: PlannedSecret[] = [];
+  for (const [index, secret] of (config.secrets_store_secrets ?? []).entries()) {
+    const label = secret.binding ?? `index ${index}`;
+    const storeId = secret.store_id;
+    const secretName = secret.secret_name;
+    if (storeId === undefined || storeId === '' || secretName === undefined || secretName === '') {
+      throw new Error(
+        `secrets_store_secrets[${index}] ("${label}") needs both store_id and secret_name; ` +
+          'store_id is normally filled in by scripts/prepare-wrangler-config.ts.',
+      );
+    }
+    if (!canProvisionSecret(secretName)) {
+      throw new Error(`No generator for secret "${secretName}" (binding "${label}").`);
+    }
+    plan.push({ storeId, secretName });
+  }
+  return plan;
+}
+
+/**
+ * List the secret names present in a store.
+ *
+ * Returns `undefined` when the listing itself failed, which is deliberately
+ * distinct from an empty set: a transient CLI failure must not be read as "the
+ * secret is missing" and cause a duplicate insert over a live value. An empty store
+ * *is* a confirmed absence, so it maps to an empty set rather than `undefined`.
+ *
+ * The name is taken exactly. `output.includes(secretName)` is not a membership test:
+ * `my-replication-encryption-key-2` satisfies a search for
+ * `my-replication-encryption-key`, so a store holding only the suffixed entry would
+ * report the unsuffixed one as already present and it would never be created.
+ */
+function listSecretNames(storeId: string): Set<string> | undefined {
+  let output: string;
+  try {
+    output = wrangler(['secrets-store', 'secret', 'list', storeId, '--remote']);
+  } catch (error: unknown) {
+    if (isEmptySecretsStoreListing(error)) {
+      console.log(`Secrets Store ${storeId} is empty`);
+      return new Set();
+    }
+    console.warn(`Unable to list secrets in store ${storeId}:`, error instanceof Error ? error.message : 'unknown error');
+    return undefined;
+  }
+  return parseWranglerNames(output);
+}
+
+function createSecret(storeId: string, secretName: string, secretValue: string): void {
+  console.log(`Creating secret: ${secretName}`);
+  // The value goes in on stdin, never as an argv entry: an argv is visible to every
+  // process on the runner through `ps`, and the previous
+  // `echo "${value}" | wrangler … ${name}` also broke on `"`, `$`, backticks and
+  // newlines.
+  wrangler(['secrets-store', 'secret', 'create', storeId, '--name', secretName, '--scopes', 'workers', '--remote'], secretValue);
+}
+
+async function main(): Promise<void> {
+  console.log('Initializing Cloudflare secrets...');
+  const config = parseWranglerConfig();
+  const plan = planSecrets(config);
+
+  if (plan.length === 0) {
+    throw new Error('wrangler.jsonc declares no secrets_store_secrets entries, so there is nothing to initialize.');
+  }
+
+  const listedByStore = new Map<string, Set<string> | undefined>();
+
+  for (const { storeId, secretName } of plan) {
+    if (!listedByStore.has(storeId)) {
+      listedByStore.set(storeId, listSecretNames(storeId));
+    }
+    const existing = listedByStore.get(storeId);
+    if (existing === undefined) {
+      // Refuse to guess: creating a secret we could not read back risks overwriting
+      // a live value with a freshly generated one.
+      throw new Error(
+        `Could not list secrets in store ${storeId}; refusing to create ${secretName} without confirming it is absent.`,
+      );
+    }
+    if (existing.has(secretName)) {
+      console.log(`Secret ${secretName} already exists; leaving it untouched.`);
+      continue;
+    }
+    createSecret(storeId, secretName, await generatorFor(secretName)());
+    existing.add(secretName);
+  }
+
+  console.log('Secret initialization complete');
+}
+
+// Top-level await rather than `.catch(console.error)`, so a rejected `main` surfaces
+// as a stack trace with its cause intact and the process exits non-zero. Either way
+// the exit status has to be right: this runs in the deploy pipeline, and swallowing
+// the rejection reported a failed key bootstrap as a green step.
+try {
+  await main();
+} catch (error: unknown) {
+  fail(error instanceof Error ? `Secret initialization failed: ${error.message}` : String(error));
+}

package/src/scripts/lib/cli-args.ts

@@ -0,0 +1,154 @@
+/**
+ * Minimal flag parsing for the operator scripts.
+ *
+ * Provenance: ported from Edge-Sonic's `scripts/lib/cli-args.ts`, which is the
+ * only typed arg parser in the family — every other repo reads `process.argv`
+ * with `includes('--flag')` inline.
+ *
+ * The shape is generic: a declared set of value flags and boolean flags, so an
+ * unknown or valueless flag is rejected **by name** rather than silently ignored.
+ * A mistyped `--write` must not degrade into "ran with no flags" — which is what
+ * an inline `argv.includes()` does, and what turns a migration-lock invocation
+ * that misspelled the flag into a read-only run that reports success.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const flags = parseFlags(process.argv.slice(2), {
+ *   boolean: ['write', 'dry-run'],
+ *   value: ['locales-dir', 'root'],
+ * });
+ * if (isSet(flags, 'write')) { ... }
+ * const dir = valueOf(flags, 'locales-dir');
+ * ```
+ */
+
+/**
+ * Parsed flags: value flags map to their string, boolean flags to `true`.
+ */
+export type ParsedFlags = Map<string, string | true>;
+
+/**
+ * Declares which flags take a value and which are bare switches.
+ */
+export interface FlagSpec {
+  /**
+   * `--name` takes a value, e.g. `--to new@example.com`.
+   */
+  value?: readonly string[];
+  /**
+   * `--dry-run` takes no value.
+   */
+  boolean?: readonly string[];
+  /**
+   * Short form → long form, e.g. `{ h: 'help' }`.
+   */
+  alias?: Readonly<Record<string, string>>;
+}
+
+/**
+ * Parses `--flag value` and `--boolean` pairs out of `argv`.
+ *
+ * @throws when a value flag is missing its value, when a flag is repeated, or
+ *   when an undeclared flag is seen. Each case names the offending flag.
+ */
+export function parseFlags(argv: readonly string[], spec: FlagSpec): ParsedFlags {
+  const valueFlags = new Set(spec.value);
+  const booleanFlags = new Set(spec.boolean);
+  const aliases = spec.alias ?? {};
+  const flags: ParsedFlags = new Map();
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index] as string;
+    if (!arg.startsWith('-')) {
+      throw new Error(`Unexpected argument: ${arg}`);
+    }
+    const raw = arg.replace(/^--?/, '');
+    const name = aliases[raw] ?? raw;
+
+    if (booleanFlags.has(name)) {
+      if (flags.has(name)) {
+        throw new Error(`--${name} was given more than once`);
+      }
+      flags.set(name, true);
+      continue;
+    }
+
+    if (!valueFlags.has(name)) {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+    if (flags.has(name)) {
+      throw new Error(`--${name} was given more than once`);
+    }
+
+    const value = argv[index + 1];
+    // A value that starts with `-` is treated as a missing value so that
+    // `--to --dry-run` reports the real problem instead of capturing the flag.
+    if (value === undefined || value.startsWith('-')) {
+      throw new Error(`--${name} requires a value`);
+    }
+    flags.set(name, value);
+    index += 1;
+  }
+
+  return flags;
+}
+
+/**
+ * Reads a value flag, or `undefined` when it was not supplied.
+ */
+export function valueOf(flags: ParsedFlags, name: string): string | undefined {
+  const value = flags.get(name);
+  return typeof value === 'string' ? value : undefined;
+}
+
+/**
+ * Reads a boolean flag, defaulting to `false`.
+ */
+export function isSet(flags: ParsedFlags, name: string): boolean {
+  return flags.get(name) === true;
+}
+
+/**
+ * Split `argv` into its positional arguments and the rest, so a caller can accept
+ * `tsx script.ts <dir>` alongside `--root <dir>`.
+ *
+ * A token that follows a value flag *is* that flag's value, not a positional: the
+ * naive `argv.filter((arg) => !arg.startsWith('-'))` takes `.` out of
+ * `--root . --fail-on-hard` and then `parseFlags` reports `--root requires a value`.
+ * The value flags are passed in rather than inferred, because only the caller knows
+ * which of its declared flags take one.
+ *
+ * @throws when more than `expected` positionals are given, naming them: a second
+ *   directory is far more likely to be a mistyped flag than an intended argument.
+ */
+export function splitPositional(
+  argv: readonly string[],
+  valueFlags: readonly string[],
+  expected = 1,
+): { positional: string[]; rest: string[] } {
+  const takes = new Set(valueFlags);
+  const positional: string[] = [];
+  const rest: string[] = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index] as string;
+    if (arg.startsWith('-')) {
+      rest.push(arg);
+      continue;
+    }
+    const previous = argv[index - 1] as string | undefined;
+    const isFlagValue = previous !== undefined && previous.startsWith('-') && takes.has(previous.replace(/^--?/, ''));
+    if (isFlagValue) {
+      rest.push(arg);
+      continue;
+    }
+    positional.push(arg);
+  }
+
+  if (positional.length > expected) {
+    throw new Error(`Expected at most ${expected} positional argument(s), got: ${positional.join(', ')}`);
+  }
+  return { positional, rest };
+}
+

package/src/scripts/lib/github-actions.ts

@@ -0,0 +1,41 @@
+/**
+ * Minimal GitHub Actions step helpers shared by the CI scripts.
+ *
+ * Provenance: ported from Edge-Sonic's `scripts/lib/github-actions.ts`, the only
+ * repo that factored these out. The scripts deliberately avoid `@actions/*`
+ * dependencies so they stay runnable with plain `tsx` from a local shell, which
+ * is how they are tested.
+ */
+
+import { appendFileSync } from 'node:fs';
+
+/**
+ * Append `name=value` to the step's output file. No-op outside Actions.
+ */
+export function setOutput(name: string, value: string): void {
+  const outputFile = process.env.GITHUB_OUTPUT;
+  if (!outputFile) {
+    return;
+  }
+  appendFileSync(outputFile, `${name}=${value}\n`);
+}
+
+/**
+ * Emit a workflow-command annotation so the failure is visible in the run log.
+ */
+export function logError(message: string): void {
+  process.stderr.write(`::error::${message}\n`);
+}
+
+/**
+ * Report a fatal error and exit non-zero.
+ *
+ * The annotation is written *before* exiting so the reason survives in the run
+ * log. This is the whole point of the helper: the failure mode it exists to
+ * prevent is a script that ends in `.catch(console.error)`, which reports success
+ * while every side effect it was supposed to perform did not happen.
+ */
+export function fail(message: string): never {
+  logError(message);
+  process.exit(1);
+}

package/src/scripts/lib/wrangler-table.ts

@@ -0,0 +1,105 @@
+/**
+ * Parsers for the human-readable tables `wrangler` prints.
+ *
+ * Provenance: ported from Edge-Sonic's `scripts/lib/wrangler-table.ts`, which was
+ * factored out of two scripts that had each grown their own copy.
+ *
+ * `wrangler secrets-store …` renders through `cli-table3`, which draws a
+ * box-drawing frame and separates cells with U+2502 (`│`) padded by exactly one
+ * space. Columns are therefore *not* space-aligned, and a parser written for
+ * aligned output silently matches nothing — which reads as "the resource is
+ * absent" and makes provisioning create a duplicate.
+ *
+ * ### Why membership is exact and never a substring
+ *
+ * Durable-DAV's `init-secrets.ts` used `output.includes(secretName)`, and that is
+ * the defect this port replaces: a store holding both
+ * `durable-dav-replication-encryption-key` and a `…-key-backup` would satisfy a
+ * substring search for the first, so the real secret was reported as already
+ * present and never created. A substring match is not a membership test.
+ */
+
+/**
+ * Cell separator emitted by `cli-table3`.
+ */
+const COLUMN_SEPARATOR = String.fromCodePoint(0x25_02);
+
+/**
+ * Horizontal rule drawn by `cli-table3`; a row made of these is not data.
+ */
+const RULE_CHARACTER = String.fromCodePoint(0x25_00);
+
+/**
+ * Header row of every `wrangler … list` table.
+ */
+const HEADER_FIRST_CELL = 'Name';
+
+/**
+ * Extracts the data rows of a `wrangler` table, dropping the frame, the header,
+ * and any surrounding log lines.
+ *
+ * Rows are returned in print order with cells trimmed and empty cells removed,
+ * so a blank optional column (`Comment`, typically unset) does not shift the
+ * columns a caller indexes into.
+ */
+export function parseWranglerTableRows(output: string): string[][] {
+  const rows: string[][] = [];
+  for (const line of output.split('\n')) {
+    // The frame rows use U+253C (`┼`) at the joints rather than U+2502, so they
+    // are already excluded here; the rule-character guard below additionally
+    // covers borders that happen to contain a separator.
+    if (!line.includes(COLUMN_SEPARATOR)) {
+      continue;
+    }
+
+    const cells: string[] = line
+      .split(COLUMN_SEPARATOR)
+      .map((cell) => cell.trim())
+      .filter(Boolean);
+    const firstCell = cells[0];
+    if (firstCell === undefined || cells.length < 2) {
+      continue;
+    }
+    // The header row and the horizontal rules are frame, not data.
+    if (firstCell === HEADER_FIRST_CELL || firstCell.includes(RULE_CHARACTER)) {
+      continue;
+    }
+    rows.push(cells);
+  }
+  return rows;
+}
+
+/**
+ * The exact names in the first column of a `wrangler secrets-store secret list`
+ * table.
+ *
+ * Exact values rather than a substring search — see the header.
+ */
+export function parseWranglerNames(output: string): Set<string> {
+  const names = new Set<string>();
+  for (const row of parseWranglerTableRows(output)) {
+    const name = row[0];
+    if (name !== undefined) names.add(name);
+  }
+  return names;
+}
+
+/**
+ * wrangler exits non-zero when a Secrets Store holds no secrets
+ * (`secrets-store secret list` throws this `FatalError`), which is
+ * indistinguishable by exit code from a genuine failure.
+ */
+const EMPTY_STORE_MESSAGE = 'List request returned no secrets';
+
+/**
+ * True when a failed `secrets-store secret list` means the store is empty
+ * rather than the listing having failed.
+ *
+ * Callers must treat this as a confirmed absence; every other failure has to
+ * stay indistinguishable from "unknown", or a transient CLI error would be read
+ * as permission to create a secret that already holds a live value.
+ */
+export function isEmptySecretsStoreListing(error: unknown): boolean {
+  const message: string = error instanceof Error ? error.message : String(error);
+  return message.includes(EMPTY_STORE_MESSAGE);
+}

package/src/scripts/migrations-lock.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env tsx
+/**
+ * Record newly-added migration files in `migrations/migrations.lock.json`.
+ *
+ * Provenance: Edge-Sonic's `scripts/migrations/verify-migrations.ts --write`,
+ * which is the only repo that splits the two operations into two commands. The
+ * other repos have one script with a flag; the split is kept here because the two
+ * calls have different audiences and different blast radii — `verify-migrations`
+ * runs in CI and changes nothing, while this one is an operator action that writes
+ * a file into version control.
+ *
+ * The rules live once, in `verify-migrations.ts`, so the two entrypoints cannot
+ * disagree. `--write` is add-only: it records unlocked files, refreshes the
+ * baseline's own entry, and drops entries the baseline absorbed. It never touches
+ * another existing entry, so an incremental migration that has drifted still
+ * fails afterwards — re-baselining one means deleting its entry by hand, which
+ * shows up in the diff.
+ *
+ * There is deliberately no `--force`, because a write that could bless a drift
+ * without reading the drift is the operator blessing their own edit, and they are
+ * by definition the one making it.
+ *
+ * Usage, from the repo root:
+ *
+ * ```bash
+ * pnpm exec tsx scripts/migrations-lock.ts                   # ./migrations
+ * pnpm exec tsx scripts/migrations-lock.ts path/to/migrations
+ * ```
+ */
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { LOCK_NAME, verifyMigrations } from './verify-migrations';
+
+const REPOSITORY_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const migrationsDir = process.argv[2] === undefined ? path.join(REPOSITORY_ROOT, 'migrations') : path.resolve(process.argv[2]);
+
+const report = verifyMigrations(migrationsDir, { write: true });
+
+for (const problem of report.problems) {
+  console.error(`FAIL: ${problem.problem}`);
+}
+
+console.log(
+  `${report.lock === null ? 'left' : 'wrote'} ${path.join(migrationsDir, LOCK_NAME)} ` +
+    `(${report.files.length} migration(s) recorded)`,
+);
+
+// The lock is re-checked by the caller: `verify-migrations.ts` re-reads from disk,
+// so running it after this command reports the same verdict CI will. A `--write`
+// that could not resolve everything still exits non-zero here, which is why an
+// incremental `edited` finding does not vanish just because someone wrote.
+process.exit(report.problems.length === 0 ? 0 : 1);

package/src/scripts/prepare-wrangler-config.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env tsx
+/**
+ * Materialize `wrangler.jsonc` and provision what it refers to.
+ *
+ * Provenance: Durable-DAV's `scripts/prepare-wrangler-config.ts` and Edge-Sonic's
+ * `scripts/deploy/prepare-wrangler-config.ts`, converged. The five ordered calls
+ * live in `wrangler-config/`: read or copy the config, refuse one older than the
+ * template requires, apply the caller's patches, then create whatever resources it
+ * names and write their real ids over the placeholders. This file is only the
+ * order; it has nothing else to do.
+ *
+ * Run by the deploy job before `wrangler deploy`, and by the backup workflow
+ * before `wrangler d1 export` — so the database a backup covers is resolved from
+ * the same config the deploy targets, with no second `D1_DATABASE_ID` secret to
+ * keep in sync.
+ *
+ * The one thing it does beyond calling is publish what
+ * `provisionWranglerResources` created, which the backup workflow reads to refuse
+ * exporting a database that did not exist until this run.
+ *
+ * Usage, from the repo root:
+ *
+ * ```bash
+ * pnpm exec tsx scripts/prepare-wrangler-config.ts
+ * ```
+ *
+ * Environment:
+ *
+ * - `WRANGLER_JSONC` — the whole config, as a repository variable. When set it is
+ *   written verbatim instead of copying the template.
+ * - `WRANGLER_PATCH_JSON` — top-level keys merged into the config.
+ * - `WRANGLER_VARS_PATCH_JSON` — `vars` entries merged into the config.
+ */
+import { setOutput } from './lib/github-actions';
+import { applyTopLevelPatch, applyVarsPatch, ensureMinimumConfigVersion, prepareConfigFile } from './wrangler-config/patches';
+import { provisionWranglerResources } from './wrangler-config/resources';
+
+prepareConfigFile();
+ensureMinimumConfigVersion();
+applyTopLevelPatch();
+applyVarsPatch();
+const created = provisionWranglerResources();
+
+// Published as a step output rather than only printed. The backup workflow needs
+// to know whether the D1 database *existed* or was created moments ago: a fresh one
+// holds no user data, and uploading that empty dump every night is a false sense
+// of safety. The alternative — re-reading the placeholder id out of
+// `wrangler.jsonc` — is unreachable, because `provisionWranglerResources` patches
+// the placeholder away before the reader ever runs.
+setOutput('created', created.join(','));
+console.log('Wrangler configuration is ready.');