@rexezuge/tooling 0.0.0-stage → 1.0.0

package/src/github/workflows/continuous-integration.yml

@@ -0,0 +1,259 @@
+# Continuous Integration — the converged gate for the family's worker repos.
+#
+# The most-common superset of the nine repos' CI workflows. Each job exists because
+# its failure is invisible to every other job: a locale defect still typechecks, a
+# god file still lints, an edited migration still deploys. A job per gate means the
+# run log names the tool that broke rather than burying it in a `checks` job.
+#
+# PLACEHOLDERS — the things a consumer must change for this to run at all:
+#   * REPLACE_ME_SCOPE       the npm scope, in the `pnpm --filter @REPLACE_ME_SCOPE/web build`
+#                           invocations below.
+#   * REPLACE_ME_WEB_FILTER  the workspace filter for the SPA (usually @REPLACE_ME_SCOPE/web).
+#   * REPLACE_ME_MIGRATIONS  the D1 binding `wrangler d1 migrations apply` targets.
+#
+# The script names in the `run:` steps are the ones this package's scripts suggest;
+# see README.md for the package.json wiring.
+
+name: Continuous Integration
+
+permissions:
+  contents: read
+
+on:
+  repository_dispatch:
+    types:
+      - Upstream Sync Integration
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+concurrency:
+  group: continuous-integration-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Typecheck and lint are separate from the gates that follow, because they need
+  # nothing but a checkout while the gates are read-only consumers of the tree.
+  checks:
+    name: Checks
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v6
+
+      - name: Setup Environment
+        uses: ./.github/actions/setup-env
+
+      # `pnpm -r typecheck` reaches every workspace package, `test/` among them.
+      - name: Run Type Check and Lint
+        run: pnpm -r typecheck && pnpm run lint
+
+      # Its own step, and read-only, because the `lint` job cannot catch this:
+      # `pnpm run lint` is `eslint --fix --quiet`, and `--fix` repairs what it can
+      # while `--quiet` suppresses the rest — so CI exits 0 on a tree Prettier
+      # rejects, the repairs land in the runner's checkout, and they are thrown
+      # away. `prettier --check` is the one command that fails instead of
+      # repairing. Edge-Sonic had 242 files in exactly that state.
+      - name: Check Formatting
+        run: pnpm run format:check
+
+      - name: Check God-Files
+        uses: ./.github/actions/retry-step
+        with:
+          command: pnpm run check:god-files
+          max_attempts: '2'
+
+      # A locale defect is invisible to the unit tests: the catalogs are data, and
+      # a key missing from every bundle still typechecks and still builds.
+      - name: Validate Locale Bundles
+        uses: ./.github/actions/retry-step
+        with:
+          command: pnpm run validate:locales
+          max_attempts: '2'
+
+      # Editing an already-applied migration is invisible to every other check:
+      # the deploy succeeds, fresh databases pick up the edited statements, and
+      # production keeps the schema it had. The lock is what turns that into a
+      # failure, and this job is read-only — `migrations-lock` is the operator's
+      # command, deliberately not CI's.
+      - name: Verify Migration Lock
+        uses: ./.github/actions/retry-step
+        with:
+          command: pnpm run validate:migrations
+          max_attempts: '2'
+
+  unit-tests:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v6
+
+      - name: Setup Environment
+        uses: ./.github/actions/setup-env
+
+      - name: Run Tests with Coverage
+        uses: ./.github/actions/retry-step
+        with:
+          command: pnpm run test:coverage
+          max_attempts: '2'
+
+      - name: Upload Coverage Report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage/
+          retention-days: 14
+
+  # The SPA's own suite. Only repositories with a Vite SPA keep this job; the two
+  # configs partition the suite rather than each running all of it, so a jsdom
+  # suite under `node` cannot pass while failing.
+  web-tests:
+    name: Web Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v6
+
+      - name: Setup Environment
+        uses: ./.github/actions/setup-env
+
+      - name: Run SPA Unit Tests
+        run: pnpm run test:web
+
+  integration-tests:
+    name: Integration Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v6
+
+      - name: Setup Environment
+        uses: ./.github/actions/setup-env
+
+      - name: Run Integration Tests
+        run: pnpm run test:integration
+
+  # Only the SPA build. The API worker is typechecked by `pnpm -r typecheck` above,
+  # so repeating it here would run the same `tsc --noEmit` against the same
+  # tsconfig a second time.
+  build:
+    name: Build Web App
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v6
+
+      - name: Setup Environment
+        uses: ./.github/actions/setup-env
+
+      # PLACEHOLDER: the workspace filter for the SPA.
+      - name: Build Web App
+        run: pnpm --filter @REPLACE_ME_SCOPE/web build
+
+  # Verifies the shell the API worker *serves*, which is a different artifact from
+  # `apps/web/dist/` — it is embedded into `apps/api/src/generated/spa-shell.ts` by
+  # the Vite plugin, and both are gitignored. A stale-but-present shell is a deploy
+  # that serves yesterday's operator UI.
+  #
+  # It builds first rather than depending on `build`, so the failure says "the
+  # served shell is wrong" instead of arriving inside a build log. That costs a
+  # second Vite build per run; the alternative — verifying inside `build` — is free
+  # and is the trade being made here.
+  spa-shell:
+    name: Verify SPA Shell
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v6
+
+      - name: Setup Environment
+        uses: ./.github/actions/setup-env
+
+      # PLACEHOLDER: the workspace filter for the SPA.
+      - name: Build Web App
+        run: pnpm --filter @REPLACE_ME_SCOPE/web build
+
+      # The build is a **precondition**, not a convenience: a fresh checkout has
+      # neither `apps/web/dist/` nor `apps/api/src/generated/`, and postinstall
+      # writes a deliberately empty stub so `tsc` can resolve `SPA_HTML` before
+      # anyone has built. Verifying without building cannot pass, and it fails
+      # with precisely the message the check exists to give.
+      - name: Verify The SPA Shell
+        uses: ./.github/actions/retry-step
+        with:
+          command: pnpm run verify:spa-shell
+          max_attempts: '2'
+
+  dependabot-auto-merge:
+    if: ${{ github.event_name == 'pull_request' && github.event.pull_request.user.login == 'dependabot[bot]' && github.event.pull_request.state == 'open' && !github.event.repository.fork }}
+    name: Auto-Merge Dependabot PR
+    needs:
+      - checks
+      - unit-tests
+      - web-tests
+      - integration-tests
+      - build
+      - spa-shell
+    permissions:
+      contents: write
+      pull-requests: write
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v6
+
+      # Auto-merge only after every gate above is green, which is what makes it
+      # safe: a dependency bump that breaks the suite waits for a human instead of
+      # merging itself.
+      - name: Enable Auto-Merge
+        uses: ./.github/actions/retry-step
+        with:
+          command: gh pr merge --auto --merge "$PR_URL"
+          max_attempts: '5'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_URL: ${{ github.event.pull_request.html_url }}
+
+  dispatch-upstream-sync-deployment:
+    if: ${{ github.event_name == 'repository_dispatch' && github.event.action == 'Upstream Sync Integration' }}
+    name: Dispatch Upstream Sync Deployment
+    needs:
+      - checks
+      - unit-tests
+      - web-tests
+      - integration-tests
+      - build
+      - spa-shell
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v6
+
+      # The second half of the upstream-sync contract: a fork's sync runs CI, and
+      # CI — not the sync workflow — is what authorises the deploy.
+      - name: Dispatch Deployment
+        uses: ./.github/actions/retry-step
+        with:
+          command: >
+            printf '{"event_type":"Upstream Sync Deployment","client_payload":{"branch":"%s","sha":"%s"}}\n'
+            "$PAYLOAD_BRANCH" "$PAYLOAD_SHA"
+            | gh api repos/${{ github.repository }}/dispatches --method POST --input -
+          max_attempts: '2'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PAYLOAD_BRANCH: ${{ github.event.client_payload.branch || 'main' }}
+          PAYLOAD_SHA: ${{ github.event.client_payload.sha || github.sha }}

package/src/github/workflows/scheduled-version-update.yml

@@ -0,0 +1,38 @@
+# Scheduled Version Update — stamp .github/.version twice a month.
+#
+# The stamp is the family's cache-buster: the CD workflow reads it, and the
+# backup workflows use it in branch names. Forked repos skip the schedule
+# (`if: !github.event.repository.fork`) because a fork must not race its
+# upstream's push.
+
+name: Scheduled Version Update
+
+on:
+  schedule:
+    - cron: '0 0 1,15 * *'
+
+permissions:
+  contents: write
+
+jobs:
+  update-version:
+    if: ${{ !github.event.repository.fork }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: true
+
+      - name: Write Current Unix Timestamp
+        run: date +%s > .github/.version
+
+      - name: Commit and Push
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          git add .github/.version
+          git diff --staged --quiet || git commit -m "chore: update .version stamp"
+          git push

package/src/github/workflows/upstream-sync.yml

@@ -0,0 +1,56 @@
+# Upstream Sync — a fork's scheduled pull from the repository it forked.
+#
+# Converged from eight repos (all but Records-Provider and CalDAV-Bridge ship this
+# file, and the two that differ do so only in the upstream repository name).
+#
+# The contract has two sides and they change in the same commit: this workflow
+# publishes `Upstream Sync Integration`, and continuous-integration.yml listens for
+# it. The event is named `Upstream Sync Integration` rather than `Upstream Sync`
+# precisely so it cannot be confused with the `Upstream Sync Deployment` event the
+# deploy workflow listens for — one sync, two dispatches, and the name is what keeps
+# a reader from wiring the wrong one.
+
+name: Upstream Sync
+
+on:
+  schedule:
+    # Weekly, Monday 02:00 UTC. Off the hour on purpose: GitHub drops scheduled
+    # workflows that share a minute with high-traffic crons.
+    - cron: '0 2 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  sync:
+    if: ${{ !github.event.repository.fork }}
+    name: Sync From Upstream
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v6
+
+      # Pinned by commit rather than a tag: this action writes a config file and
+      # fetches a binary onto the runner, so a moved tag is a supply-chain change
+      # arriving through a version bump nobody reviewed.
+      - name: Sync Changes
+        id: sync
+        uses: aormsby/Fork-Sync-With-Upstream-action@v3.4
+        with:
+          # PLACEHOLDER: the upstream repository this one forks, as owner/name.
+          upstream_sync_repo: REPLACE_ME_ORG/REPLACE_ME_REPO
+          upstream_sync_branch: main
+          target_sync_branch: main
+          target_repo_token: ${{ secrets.GITHUB_TOKEN }}
+          test_mode: false
+
+      - name: Trigger Continuous Integration
+        if: steps.sync.outputs.has_new_commits == 'true'
+        uses: ./.github/actions/retry-step
+        with:
+          command: gh api repos/${{ github.repository }}/dispatches --method POST -f event_type='Upstream Sync Integration'
+          max_attempts: '2'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/src/index.ts

@@ -0,0 +1,42 @@
+/**
+ * `@rexezuge/tooling` — the tooling layer of the kit.
+ *
+ * The config factories and the test helpers are re-exported here, so a consumer has
+ * one import for everything its `*.config.mts` files and its mocks need. The
+ * scripts under `scripts/` are **not** re-exported: they resolve paths relative to
+ * the repository they run in, so they are run from disk with `tsx`, not imported.
+ * See `README.md` for the copy-in recipe and the per-script usage.
+ *
+ * The zero-dependency rule: nothing here imports another `@rexezuge/*` package. The
+ * one exception in the tree is `scripts/backup/encrypt-backup.ts`, which uses
+ * `@rexezuge/d1`'s AES-GCM so the backup and the workers share one definition of
+ * "what an encryption key looks like"; that dependency is declared on the package
+ * and is only ever resolved in the consumer's repo, where the kit is installed
+ * alongside `@rexezuge/d1`.
+ */
+
+export { defineRepoLintConfig } from './eslint';
+export type { RepoLintConfigOptions } from './eslint';
+
+export { defineUnitVitestConfig } from './vitest';
+export type { CoverageThresholds, UnitVitestConfigOptions, VitestAlias } from './vitest';
+
+export { defineWebVitestConfig } from './vitest-web';
+export type { WebVitestConfigOptions } from './vitest-web';
+
+export { defineWebViteConfig, spaShellEmbedPlugin } from './vite';
+export type { ProxyEntry, SpaShellTarget, WebViteConfigOptions } from './vite';
+
+export { createPagesProxy } from './functions/pages-proxy';
+export type { Fetcher, PagesFunction, PagesFunctionContext, PagesProxyEnv, PagesProxyOptions } from './functions/pages-proxy';
+
+// --- Test helpers ---------------------------------------------------------
+//
+// Aliased in a Vitest config, not imported by application code, so the mocks stay
+// where the suites can reach them.
+
+export { DurableObject, RpcTarget, WorkflowEntrypoint } from './test/mocks/cloudflare-workers';
+export type { DurableObjectState, ExecutionContext } from './test/mocks/cloudflare-workers';
+
+export { createMigrationHelper, readMigrationFiles, splitSql } from './test/integration-migrations';
+export type { D1DatabaseLike, D1PreparedStatementLike, MigrationFile, MigrationHelper, MigrationHelperOptions, MigrationRange } from './test/integration-migrations';

package/src/scripts/backup/backup-rules.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest';
+import { resolveD1Target } from './d1-target';
+import { evaluateConfig } from './destination-config';
+import { backupFileName, backupStamp, requireRetentionDays, retentionCutoff } from './naming';
+
+describe('resolveD1Target', () => {
+  it('prefers database_name, falling back to the binding', () => {
+    // `wrangler d1 export` takes a database *name*, so the name wins when present.
+    expect(resolveD1Target({ d1_databases: [{ binding: 'DB', database_name: 'my-db', database_id: 'abc' }] })).toStrictEqual({
+      binding: 'DB',
+      databaseId: 'abc',
+      target: 'my-db',
+    });
+    expect(resolveD1Target({ d1_databases: [{ binding: 'DB', database_id: 'abc' }] }).target).toBe('DB');
+  });
+
+  it('refuses a placeholder id, because the database was never created', () => {
+    expect(() => resolveD1Target({ d1_databases: [{ binding: 'DB', database_id: '00000000-0000-0000-0000-000000000000' }] })).toThrow(
+      /template placeholder/,
+    );
+  });
+
+  it('refuses a config with no binding to export under', () => {
+    expect(() => resolveD1Target({ d1_databases: [{ database_id: 'abc' }] })).toThrow(/No d1_databases entry with a binding/);
+    expect(() => resolveD1Target({})).toThrow(/No d1_databases entry with a binding/);
+  });
+});
+
+describe('evaluateConfig', () => {
+  it('stays silent when nothing is configured', () => {
+    // An unconfigured repository is a legitimate "I do not want off-site backups"
+    // state and must not turn the schedule red.
+    expect(evaluateConfig({})).toMatchObject({ cloudflare: false, encryption: false, anyDestination: false, errors: [] });
+  });
+
+  it('fails closed on a destination without an encryption key', () => {
+    const config = evaluateConfig({
+      CLOUDFLARE_API_TOKEN: 'token',
+      CLOUDFLARE_ACCOUNT_ID: 'account',
+      S3_ACCESS_KEY_ID: 'key',
+      S3_SECRET_ACCESS_KEY: 'secret',
+      S3_BUCKET: 'bucket',
+    });
+    expect(config.s3).toBe(true);
+    expect(config.encryption).toBe(false);
+    expect(config.errors.join('\n')).toMatch(/BACKUP_ENCRYPTION_KEY is required/);
+  });
+
+  it('fails a destination with no Cloudflare credentials', () => {
+    expect(evaluateConfig({ BACKUP_ENCRYPTION_KEY: 'k', WEBDAV_URL: 'https://dav.example.com', WEBDAV_USER: 'u', WEBDAV_PASSWORD: 'p' }).errors).toStrictEqual(
+      ['A backup destination is configured but CLOUDFLARE_API_TOKEN / CLOUDFLARE_ACCOUNT_ID are missing.'],
+    );
+  });
+
+  it('passes when both a destination and the key are present', () => {
+    const config = evaluateConfig({
+      CLOUDFLARE_API_TOKEN: 'token',
+      CLOUDFLARE_ACCOUNT_ID: 'account',
+      BACKUP_ENCRYPTION_KEY: 'key',
+      WEBDAV_URL: 'https://dav.example.com',
+      WEBDAV_USER: 'u',
+      WEBDAV_PASSWORD: 'p',
+    });
+    expect(config.errors).toStrictEqual([]);
+    expect(config.webdav).toBe(true);
+    expect(config.s3).toBe(false);
+  });
+
+  it('treats whitespace-only secrets as absent', () => {
+    expect(evaluateConfig({ S3_ACCESS_KEY_ID: '   ', S3_SECRET_ACCESS_KEY: ' ', S3_BUCKET: '\t' }).s3).toBe(false);
+  });
+});
+
+describe('naming', () => {
+  it('names the artifact sortably, in UTC', () => {
+    // UTC rather than local: a retention window computed across a DST boundary is
+    // one day wide in one direction, and a backup pruned a day early is a backup
+    // that was never needed.
+    const stamp = backupStamp(new Date('2026-10-01T04:15:00.000Z'));
+    expect(stamp).toBe('2026-10-01_04-15-00');
+    expect(backupFileName(new Date('2026-10-01T04:15:00.000Z'))).toBe('backup_prod_2026-10-01_04-15-00.sql.xz.enc');
+  });
+
+  it('computes a retention cutoff as a date, days back', () => {
+    expect(retentionCutoff(new Date('2026-10-31T12:00:00.000Z'), 30)).toBe('2026-10-01');
+  });
+
+  it('rejects a bad retention window rather than defaulting one', () => {
+    // Silently falling back would either prune everything or keep backups forever.
+    const before = process.env['BACKUP_RETENTION_DAYS'];
+    try {
+      process.env['BACKUP_RETENTION_DAYS'] = '30d';
+      expect(() => requireRetentionDays()).toThrow(/must be a positive number/);
+      process.env['BACKUP_RETENTION_DAYS'] = '-1';
+      expect(() => requireRetentionDays()).toThrow(/must be a positive number/);
+      delete process.env['BACKUP_RETENTION_DAYS'];
+      expect(() => requireRetentionDays()).toThrow(/must be a positive number/);
+      process.env['BACKUP_RETENTION_DAYS'] = '30';
+      expect(requireRetentionDays()).toBe(30);
+    } finally {
+      if (before === undefined) delete process.env['BACKUP_RETENTION_DAYS'];
+      else process.env['BACKUP_RETENTION_DAYS'] = before;
+    }
+  });
+});

package/src/scripts/backup/d1-target.ts

@@ -0,0 +1,54 @@
+/**
+ * Choosing which D1 database the backup workflow exports.
+ *
+ * Provenance: ported from Edge-Sonic's `scripts/backup/d1-target.ts`. Pure, so the
+ * empty-database guard is asserted without running Actions or touching a real
+ * account.
+ */
+
+import { DEFAULT_UUID } from '../wrangler-config/types';
+
+/** A D1 binding as a parsed wrangler config carries one. */
+export interface D1DatabaseBinding {
+  binding?: string;
+  database_id?: string;
+  database_name?: string;
+}
+
+/** The resolved export target. */
+export interface D1Target {
+  /** The binding name, used for log output and as the export fallback. */
+  binding: string;
+  /** The database id, verified against Cloudflare by the caller. */
+  databaseId: string;
+  /** What `wrangler d1 export` should be pointed at. */
+  target: string;
+}
+
+/**
+ * Pick the export target from a parsed wrangler config.
+ *
+ * `wrangler d1 export` takes a database *name*, so `database_name` wins when
+ * present. Hand-written configs that omit it fall back to the binding name.
+ *
+ * @throws when there is no binding, or when `database_id` is still the template
+ *   placeholder — meaning the database was auto-provisioned and holds no data.
+ */
+export function resolveD1Target(config: { d1_databases?: D1DatabaseBinding[] }): D1Target {
+  const database = config.d1_databases?.[0];
+
+  const binding = database?.binding?.trim();
+  if (binding === undefined || binding === '') {
+    throw new Error('No d1_databases entry with a binding found in wrangler.jsonc.');
+  }
+
+  const databaseId = database?.database_id?.trim() ?? '';
+  if (databaseId === DEFAULT_UUID) {
+    throw new Error(
+      `D1 database_id for ${binding} is still the template placeholder. The database does not exist yet, so there is nothing to back up.`,
+    );
+  }
+
+  const target = database?.database_name?.trim() || binding;
+  return { binding, databaseId, target };
+}

package/src/scripts/backup/destination-config.ts

@@ -0,0 +1,92 @@
+/**
+ * Destination and encryption policy for the D1 backup workflow.
+ *
+ * Provenance: ported from Edge-Sonic's `scripts/backup/destination-config.ts`.
+ * Pure and side-effect free, so the fail-closed rules are asserted without running
+ * Actions.
+ */
+
+/** The environment the `check-secrets` job is given, as repository secrets. */
+export interface BackupSecretEnvironment {
+  CLOUDFLARE_API_TOKEN?: string;
+  CLOUDFLARE_ACCOUNT_ID?: string;
+  BACKUP_ENCRYPTION_KEY?: string;
+  S3_ACCESS_KEY_ID?: string;
+  S3_SECRET_ACCESS_KEY?: string;
+  S3_BUCKET?: string;
+  WEBDAV_URL?: string;
+  WEBDAV_USER?: string;
+  WEBDAV_PASSWORD?: string;
+}
+
+/** What is configured, and why the run cannot proceed when it is not. */
+export interface DestinationConfig {
+  /** Cloudflare credentials present, so the export job can run. */
+  cloudflare: boolean;
+  /** An encryption passphrase is available. */
+  encryption: boolean;
+  /** At least one upload destination is configured. */
+  anyDestination: boolean;
+  /** The S3 destination is fully configured. */
+  s3: boolean;
+  /** The WebDAV destination is fully configured. */
+  webdav: boolean;
+  /** Human-readable reasons the run cannot proceed, empty when it can. */
+  errors: string[];
+}
+
+/** A secret counts as set only when it has non-whitespace content. */
+function isSet(value: string | undefined): boolean {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+/**
+ * Decides which destinations are configured and enforces fail-closed encryption.
+ *
+ * ### Why the encryption requirement is not optional here
+ *
+ * Two independent reasons, and they have different consequences so both are stated.
+ *
+ * **The at-rest protection assumes the dump is not in hand.** Every repo in this
+ * family seals credentials with AES-256-GCM, and each one's migration notes say the
+ * same thing: *obfuscation against a D1 dump, not protection against a full worker
+ * compromise.* An unencrypted backup inverts that assumption — dump plus the
+ * Secrets Store key is a complete credential set, and the WebDAV key is read on
+ * every scan and every stream.
+ *
+ * **The dump is a listening history.** Stars, ratings, play counts, play queues and
+ * auth failures record what each user does and when, and the schema records the
+ * full topology and every file path. None of that is credential material, and all
+ * of it is nobody else's to read.
+ *
+ * `S3_REGION` is deliberately not part of the S3 gate. R2 and MinIO have no
+ * meaningful region — Cloudflare documents an R2 bucket's region as `auto`, with
+ * empty and `us-east-1` both aliasing to it — so requiring the secret would
+ * silently disable backups for anyone using such a provider. The upload script
+ * defaults `AWS_DEFAULT_REGION` to `auto` instead.
+ */
+export function evaluateConfig(env: BackupSecretEnvironment): DestinationConfig {
+  const cloudflare = isSet(env.CLOUDFLARE_API_TOKEN) && isSet(env.CLOUDFLARE_ACCOUNT_ID);
+  const encryption = isSet(env.BACKUP_ENCRYPTION_KEY);
+  const s3 = isSet(env.S3_ACCESS_KEY_ID) && isSet(env.S3_SECRET_ACCESS_KEY) && isSet(env.S3_BUCKET);
+  const webdav = isSet(env.WEBDAV_URL) && isSet(env.WEBDAV_USER) && isSet(env.WEBDAV_PASSWORD);
+  const anyDestination = s3 || webdav;
+
+  const errors: string[] = [];
+
+  // Fail closed, but only once someone has opted into a destination. An
+  // unconfigured repository is a legitimate "I do not want off-site backups" state
+  // and must not turn the schedule red.
+  if (anyDestination) {
+    if (!cloudflare) {
+      errors.push('A backup destination is configured but CLOUDFLARE_API_TOKEN / CLOUDFLARE_ACCOUNT_ID are missing.');
+    }
+    if (!encryption) {
+      errors.push(
+        'BACKUP_ENCRYPTION_KEY is required. The D1 dump holds AES-GCM-obfuscated credentials — obfuscation that, by its own design, assumes the dump is not in hand — plus every user history and the full schema topology.',
+      );
+    }
+  }
+
+  return { cloudflare, encryption, anyDestination, s3, webdav, errors };
+}