@smoothbricks/cli 0.11.18 → 0.11.20

package/src/wrangler/format-parity.test.ts

@@ -0,0 +1,433 @@
+// One worker, written twice: as `wrangler.toml` and as `wrangler.jsonc`. Everything a deploy
+// derives from it — the parsed model, every stage plan, the derived pull-request document and
+// every refusal — has to come out deep-equal, because past the parser there is one model and one
+// implementation. A divergence here means a repo that renamed its config deploys something else.
+
+import { describe, expect, it } from 'bun:test';
+import { parseWranglerConfig } from './source-config.js';
+import {
+  derivePullRequestDocument,
+  type LiveKvNamespace,
+  planConfiguredStageResources,
+  planPullRequestResources,
+  rateLimitNamespaceId,
+  type WranglerDocument,
+} from './stage.js';
+
+const TOML = `name = "acme-site"
+main = "src/index.ts"
+compatibility_date = "2026-05-06"
+compatibility_flags = ["nodejs_compat"]
+
+[observability]
+enabled = true
+
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["QueueDO"]
+
+[env.staging]
+name = "acme-site-staging"
+workers_dev = false
+
+[env.staging.assets]
+directory = "./dist"
+not_found_handling = "single-page-application"
+
+[[env.staging.routes]]
+pattern = "*.staging.example.test/*"
+zone_name = "example.test"
+
+[[env.staging.routes]]
+pattern = "staging.example.test"
+custom_domain = true
+
+[[env.staging.routes]]
+pattern = "next.example.test"
+custom_domain = true
+
+[[env.staging.durable_objects.bindings]]
+name = "QUEUE"
+class_name = "QueueDO"
+
+[[env.staging.kv_namespaces]]
+binding = "SESSIONS"
+id = "kv-sessions-staging"
+preview_id = "kv-sessions-preview"
+
+[[env.staging.r2_buckets]]
+binding = "MEDIA"
+bucket_name = "acme-media-staging"
+
+[[env.staging.d1_databases]]
+binding = "DB"
+database_name = "acme-staging-db"
+database_id = "d1-staging"
+migrations_dir = "./migrations"
+
+[[env.staging.services]]
+binding = "BACKEND"
+service = "acme-backend-staging"
+
+[[env.staging.services]]
+binding = "SHARED"
+service = "auth-service"
+
+[[env.staging.send_email]]
+name = "EMAIL"
+allowed_sender_addresses = ["login@mail.staging.example.test"]
+
+[[env.staging.ratelimits]]
+name = "SIGNUP"
+namespace_id = "2026071701"
+simple = { limit = 5, period = 60 }
+
+[env.staging.vars]
+ENVIRONMENT = "staging"
+APP_ORIGIN = "https://app.staging.example.test"
+BUILD_CHANNEL = "staging-weekly"
+
+[env.production]
+name = "acme-site"
+workers_dev = false
+
+[[env.production.routes]]
+pattern = "example.test"
+custom_domain = true
+
+[[env.production.kv_namespaces]]
+binding = "SESSIONS"
+id = "kv-sessions-production"
+
+[[env.production.r2_buckets]]
+binding = "MEDIA"
+bucket_name = "acme-media"
+
+[env.production.vars]
+ENVIRONMENT = "production"
+`;
+
+// The same worker in the format Cloudflare now recommends, with the comments and trailing commas
+// that are the whole reason for the `.jsonc` spelling.
+const JSONC = `{
+  // The worker every stage of this repo deploys.
+  "name": "acme-site",
+  "main": "src/index.ts",
+  "compatibility_date": "2026-05-06",
+  "compatibility_flags": ["nodejs_compat"],
+  "observability": { "enabled": true },
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["QueueDO"] }],
+  "env": {
+    "staging": {
+      "name": "acme-site-staging",
+      "workers_dev": false,
+      "assets": { "directory": "./dist", "not_found_handling": "single-page-application" },
+      "routes": [
+        { "pattern": "*.staging.example.test/*", "zone_name": "example.test" },
+        { "pattern": "staging.example.test", "custom_domain": true },
+        /* pinned: this one has no stage label and is dropped from a pull-request stage */
+        { "pattern": "next.example.test", "custom_domain": true },
+      ],
+      "durable_objects": { "bindings": [{ "name": "QUEUE", "class_name": "QueueDO" }] },
+      "kv_namespaces": [
+        { "binding": "SESSIONS", "id": "kv-sessions-staging", "preview_id": "kv-sessions-preview" },
+      ],
+      "r2_buckets": [{ "binding": "MEDIA", "bucket_name": "acme-media-staging" }],
+      "d1_databases": [
+        {
+          "binding": "DB",
+          "database_name": "acme-staging-db",
+          "database_id": "d1-staging",
+          "migrations_dir": "./migrations",
+        },
+      ],
+      "services": [
+        { "binding": "BACKEND", "service": "acme-backend-staging" },
+        { "binding": "SHARED", "service": "auth-service" }, // unlabelled: stays shared
+      ],
+      "send_email": [{ "name": "EMAIL", "allowed_sender_addresses": ["login@mail.staging.example.test"] }],
+      "ratelimits": [{ "name": "SIGNUP", "namespace_id": "2026071701", "simple": { "limit": 5, "period": 60 } }],
+      "vars": {
+        "ENVIRONMENT": "staging",
+        "APP_ORIGIN": "https://app.staging.example.test",
+        "BUILD_CHANNEL": "staging-weekly",
+      },
+    },
+    "production": {
+      "name": "acme-site",
+      "workers_dev": false,
+      "routes": [{ "pattern": "example.test", "custom_domain": true }],
+      "kv_namespaces": [{ "binding": "SESSIONS", "id": "kv-sessions-production" }],
+      "r2_buckets": [{ "binding": "MEDIA", "bucket_name": "acme-media" }],
+      "vars": { "ENVIRONMENT": "production" },
+    },
+  },
+}
+`;
+
+const LIVE_NAMESPACES: LiveKvNamespace[] = [{ id: 'kv-sessions-staging', title: 'acme-sessions-staging' }];
+
+const PR42 = {
+  stage: 'pr42',
+  accountId: 'account-1',
+  kvNamespaceIds: new Map([['kv-sessions-staging', 'kv-sessions-pr42']]),
+  d1DatabaseIds: new Map([['d1-staging', 'd1-pr42']]),
+} as const;
+
+const fromToml = parseWranglerConfig('wrangler.toml', TOML, 'toml');
+const fromJsonc = parseWranglerConfig('wrangler.jsonc', JSONC, 'jsonc');
+
+/**
+ * What `act` refused with, for each spelling. Returning the message rather than asserting inside
+ * keeps the two halves comparable: a refusal only reaches parity when both sides produce the same
+ * sentence, not merely when both throw something.
+ */
+function refusals(
+  toml: string,
+  jsonc: string,
+  act: (document: WranglerDocument) => unknown,
+): { toml: string; jsonc: string } {
+  const message = (text: string, file: 'wrangler.toml' | 'wrangler.jsonc'): string => {
+    try {
+      act(parseWranglerConfig(file, text, file === 'wrangler.toml' ? 'toml' : 'jsonc'));
+    } catch (error) {
+      return error instanceof Error ? error.message : String(error);
+    }
+    return 'did not refuse';
+  };
+  return { toml: message(toml, 'wrangler.toml'), jsonc: message(jsonc, 'wrangler.jsonc') };
+}
+
+describe('a worker written as TOML and as JSONC', () => {
+  it('parses to one model, comments and trailing commas included', () => {
+    expect(fromJsonc).toEqual(fromToml);
+  });
+
+  it('plans staging identically', () => {
+    const plan = planConfiguredStageResources(fromToml, 'staging');
+    expect(planConfiguredStageResources(fromJsonc, 'staging')).toEqual(plan);
+    expect(plan).toEqual({
+      stage: 'staging',
+      workerName: 'acme-site-staging',
+      kvNamespaces: [{ binding: 'SESSIONS', id: 'kv-sessions-staging' }],
+      r2Buckets: [{ binding: 'MEDIA', bucketName: 'acme-media-staging' }],
+      routes: [
+        { pattern: '*.staging.example.test/*', zoneName: 'example.test', customDomain: false },
+        { pattern: 'staging.example.test', customDomain: true },
+        { pattern: 'next.example.test', customDomain: true },
+      ],
+    });
+  });
+
+  it('plans production identically', () => {
+    const plan = planConfiguredStageResources(fromToml, 'production');
+    expect(planConfiguredStageResources(fromJsonc, 'production')).toEqual(plan);
+    expect(plan).toEqual({
+      stage: 'production',
+      workerName: 'acme-site',
+      kvNamespaces: [{ binding: 'SESSIONS', id: 'kv-sessions-production' }],
+      r2Buckets: [{ binding: 'MEDIA', bucketName: 'acme-media' }],
+      routes: [{ pattern: 'example.test', customDomain: true }],
+    });
+  });
+
+  it('plans a pull-request stage identically, down to the resources it would create', () => {
+    const plan = planPullRequestResources(fromToml, 'pr42', LIVE_NAMESPACES);
+    expect(planPullRequestResources(fromJsonc, 'pr42', LIVE_NAMESPACES)).toEqual(plan);
+    expect(plan).toEqual({
+      stage: 'pr42',
+      workerName: 'acme-site-pr42',
+      workerBaseName: 'acme-site',
+      kvNamespaces: [
+        {
+          binding: 'SESSIONS',
+          stagingId: 'kv-sessions-staging',
+          stagingTitle: 'acme-sessions-staging',
+          title: 'acme-sessions-pr42',
+        },
+      ],
+      d1Databases: [{ binding: 'DB', stagingId: 'd1-staging', name: 'acme-pr42-db' }],
+      r2Buckets: [{ binding: 'MEDIA', bucketName: 'acme-media-pr42' }],
+      // `staging.example.test` carries the label too, so the stage gets its own custom domain;
+      // only the pinned `next.example.test` is dropped.
+      routes: [
+        { pattern: '*.pr42.example.test/*', zoneName: 'example.test', customDomain: false },
+        { pattern: 'pr42.example.test', customDomain: true },
+      ],
+    });
+  });
+
+  it('derives the same pull-request document, carrying keys it does not model', () => {
+    const derived = derivePullRequestDocument(fromToml, PR42);
+    expect(derivePullRequestDocument(fromJsonc, PR42)).toEqual(derived);
+    expect(derived.env?.pr42).toEqual({
+      name: 'acme-site-pr42',
+      workers_dev: false,
+      assets: { directory: './dist', not_found_handling: 'single-page-application' },
+      routes: [
+        { pattern: '*.pr42.example.test/*', zone_name: 'example.test' },
+        { pattern: 'pr42.example.test', custom_domain: true },
+      ],
+      durable_objects: { bindings: [{ name: 'QUEUE', class_name: 'QueueDO' }] },
+      // `preview_id` is not a field this derivation models, and it survives anyway.
+      kv_namespaces: [{ binding: 'SESSIONS', id: 'kv-sessions-pr42', preview_id: 'kv-sessions-preview' }],
+      r2_buckets: [{ binding: 'MEDIA', bucket_name: 'acme-media-pr42' }],
+      d1_databases: [
+        {
+          binding: 'DB',
+          database_name: 'acme-pr42-db',
+          database_id: 'd1-pr42',
+          migrations_dir: './migrations',
+        },
+      ],
+      services: [
+        { binding: 'BACKEND', service: 'acme-backend-pr42' },
+        { binding: 'SHARED', service: 'auth-service' },
+      ],
+      send_email: [{ name: 'EMAIL', allowed_sender_addresses: ['login@mail.pr42.example.test'] }],
+      ratelimits: [
+        {
+          name: 'SIGNUP',
+          namespace_id: rateLimitNamespaceId('account-1', 'acme-site', 'pr42', 'SIGNUP'),
+          simple: { limit: 5, period: 60 },
+        },
+      ],
+      vars: {
+        ENVIRONMENT: 'pr42',
+        APP_ORIGIN: 'https://app.pr42.example.test',
+        BUILD_CHANNEL: 'staging-weekly',
+      },
+    });
+    // Top-level declarations and the block the stage was derived from are left exactly as read.
+    expect(derived.migrations).toEqual([{ tag: 'v1', new_sqlite_classes: ['QueueDO'] }]);
+    expect(derived.observability).toEqual({ enabled: true });
+    expect(derived.env?.staging).toEqual(fromToml.env?.staging);
+    expect(derived.env?.production).toEqual(fromToml.env?.production);
+  });
+
+  it('leaves the parsed source document untouched by a derivation', () => {
+    const before = structuredClone(fromToml);
+    derivePullRequestDocument(fromToml, PR42);
+    expect(fromToml).toEqual(before);
+  });
+});
+
+describe('a refusal reads the same whichever format declared it', () => {
+  it('refuses a template whose every route is pinned', () => {
+    const { toml, jsonc } = refusals(
+      `[env.staging]
+name = "acme-site-staging"
+[[env.staging.routes]]
+pattern = "next.example.test"
+custom_domain = true
+`,
+      `{
+  // no stage-derivable route anywhere
+  "env": {
+    "staging": {
+      "name": "acme-site-staging",
+      "routes": [{ "pattern": "next.example.test", "custom_domain": true }],
+    },
+  },
+}`,
+      (document) => planPullRequestResources(document, 'pr42', []),
+    );
+    expect(jsonc).toBe(toml);
+    expect(toml).toBe(
+      'Every route of acme-site-staging is pinned (no staging label): next.example.test. A pull-request stage would deploy unrouted and Wrangler would expose it on workers.dev; add a stage-derivable route such as site.staging.<zone>/*.',
+    );
+  });
+
+  it('refuses an R2 bucket the pull-request stage would share with staging', () => {
+    const { toml, jsonc } = refusals(
+      `[env.staging]
+name = "acme-site-staging"
+[[env.staging.routes]]
+pattern = "site.staging.example.test/*"
+[[env.staging.r2_buckets]]
+binding = "MEDIA"
+bucket_name = "acme-shared-media"
+`,
+      `{
+  "env": {
+    "staging": {
+      "name": "acme-site-staging",
+      "routes": [{ "pattern": "site.staging.example.test/*" }],
+      "r2_buckets": [{ "binding": "MEDIA", "bucket_name": "acme-shared-media" }], // no staging segment
+    },
+  },
+}`,
+      (document) => planPullRequestResources(document, 'pr42', []),
+    );
+    expect(jsonc).toBe(toml);
+    expect(toml).toBe('Staging R2 bucket acme-shared-media has no exact staging segment.');
+  });
+
+  it('refuses a D1 database the pull-request stage would share with staging', () => {
+    const { toml, jsonc } = refusals(
+      `[env.staging]
+name = "acme-site-staging"
+[[env.staging.routes]]
+pattern = "site.staging.example.test/*"
+[[env.staging.d1_databases]]
+binding = "DB"
+database_name = "acme-shared-db"
+database_id = "d1-shared"
+`,
+      `{
+  "env": {
+    "staging": {
+      "name": "acme-site-staging",
+      "routes": [{ "pattern": "site.staging.example.test/*" }],
+      "d1_databases": [{ "binding": "DB", "database_name": "acme-shared-db", "database_id": "d1-shared" }],
+    },
+  },
+}`,
+      (document) => planPullRequestResources(document, 'pr42', []),
+    );
+    expect(jsonc).toBe(toml);
+    expect(toml).toBe('Staging D1 database acme-shared-db has no exact staging segment.');
+  });
+
+  it('refuses a stage the configuration does not declare', () => {
+    const { toml, jsonc } = refusals(
+      `name = "acme-site"
+[env.staging]
+name = "acme-site-staging"
+`,
+      `{
+  "name": "acme-site",
+  "env": { "staging": { "name": "acme-site-staging" } },
+}`,
+      (document) => planConfiguredStageResources(document, 'production'),
+    );
+    expect(jsonc).toBe(toml);
+    expect(toml).toBe('Wrangler configuration must declare [env.production].');
+  });
+
+  it('refuses a pull-request stage the repo committed itself, rather than replacing it', () => {
+    const { toml, jsonc } = refusals(
+      `[env.staging]
+name = "acme-site-staging"
+[[env.staging.routes]]
+pattern = "site.staging.example.test/*"
+[env.pr42]
+name = "hand-written"
+`,
+      `{
+  "env": {
+    "staging": {
+      "name": "acme-site-staging",
+      "routes": [{ "pattern": "site.staging.example.test/*" }],
+    },
+    "pr42": { "name": "hand-written" },
+  },
+}`,
+      (document) => derivePullRequestDocument(document, PR42),
+    );
+    expect(jsonc).toBe(toml);
+    expect(toml).toBe(
+      'Wrangler configuration already declares [env.pr42]; a pull-request stage is derived from [env.staging] and must not be committed.',
+    );
+  });
+});

package/src/wrangler/prepare-env.ts

@@ -22,6 +22,7 @@ import { $ } from 'bun';
 import { type AST, getStaticTOMLValue, parseTOML } from 'toml-eslint-parser';
 import typia from 'typia';
 import { decode, printCommandOutput, runText } from '../lib/run.js';
+import { readWranglerSourceConfig } from './source-config.js';
 
 // ── runtime narrowing (wrangler TOML/JSON is external data — no casts) ───────
 
@@ -280,13 +281,14 @@ export function parseDevVarsExample(text: string): string[] {
 }
 
 /**
- * Read the vars/secrets split for `env` from `<root>/wrangler.toml` (public var
- * keys) + `<root>/.dev.vars.example` (secret names). This is the "what to prompt
- * for" manifest a prepare-env script derives its work from.
+ * Read the vars/secrets split for `env` from the project's own Wrangler configuration (public
+ * var keys) + `<root>/.dev.vars.example` (secret names). This is the "what to prompt for"
+ * manifest a prepare-env script derives its work from. The config may be JSONC, JSON or TOML —
+ * reading it is format-blind; the editors below are the TOML half of the flow.
  */
 export function readManifest(root: string, env: string): Manifest {
-  const toml = readFileSync(join(root, 'wrangler.toml'), 'utf8');
-  const block = envRecord(toml, env);
+  const declared: unknown = readWranglerSourceConfig(root).document.env?.[env];
+  const block = isWranglerEnvBlock(declared) ? declared : null;
   const vars = Object.keys(block?.vars ?? {});
   const kvBindings = (block?.kv_namespaces ?? []).flatMap((row) =>
     typeof row.binding === 'string' ? [row.binding] : [],

package/src/wrangler/source-config.test.ts

@@ -0,0 +1,102 @@
+import { afterEach, describe, expect, it } from 'bun:test';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  discoverWranglerSourceConfig,
+  parseWranglerConfig,
+  readWranglerSourceConfig,
+  WRANGLER_SOURCE_CONFIG_FILES,
+} from './source-config.js';
+
+const roots: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+/** A project directory holding exactly the named config files. */
+async function project(files: Record<string, string>): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), 'smoo-wrangler-source-'));
+  roots.push(root);
+  for (const [name, content] of Object.entries(files)) {
+    await writeFile(join(root, name), content);
+  }
+  return root;
+}
+
+describe('discovering the config wrangler itself would read', () => {
+  it('follows wrangler precedence for each spelling on its own', async () => {
+    for (const file of WRANGLER_SOURCE_CONFIG_FILES) {
+      const root = await project({ [file]: file.endsWith('.toml') ? 'name = "acme"\n' : '{ "name": "acme" }' });
+      expect(discoverWranglerSourceConfig(root).path).toBe(join(root, file));
+    }
+  });
+
+  it('refuses two configs, naming every one and the one wrangler would have silently taken', async () => {
+    const root = await project({
+      'wrangler.jsonc': '{ "name": "acme-from-jsonc" }',
+      'wrangler.toml': 'name = "acme-from-toml"\n',
+    });
+
+    // Verified against wrangler 4.131.0: with both present it reads the .jsonc and says nothing.
+    expect(() => discoverWranglerSourceConfig(root)).toThrow(
+      `${root} declares more than one Wrangler configuration: wrangler.jsonc, wrangler.toml. Wrangler would read wrangler.jsonc and ignore the rest without saying so; keep exactly one.`,
+    );
+  });
+
+  it('refuses a project with no config, naming the spellings it looked for', async () => {
+    const root = await project({});
+
+    expect(() => discoverWranglerSourceConfig(root)).toThrow(
+      `${root} declares no Wrangler configuration (wrangler.jsonc, wrangler.json, wrangler.toml); pass --config for a build-generated flat configuration.`,
+    );
+  });
+
+  it('reads and parses the discovered file in one step', async () => {
+    const root = await project({ 'wrangler.jsonc': '{\n  // the worker\n  "name": "acme",\n}\n' });
+
+    expect(readWranglerSourceConfig(root)).toEqual({ path: join(root, 'wrangler.jsonc'), document: { name: 'acme' } });
+  });
+});
+
+describe('parsing a source config', () => {
+  it('tolerates comments and trailing commas in wrangler.json too, exactly as wrangler does', () => {
+    const document = parseWranglerConfig(
+      'wrangler.json',
+      '{\n  /* recommended spelling is .jsonc, but wrangler parses both the same way */\n  "name": "acme",\n  "compatibility_flags": ["nodejs_compat"],\n}\n',
+      'jsonc',
+    );
+
+    expect(document).toEqual({ name: 'acme', compatibility_flags: ['nodejs_compat'] });
+  });
+
+  it('names the file when the text is not the format it is spelled as', () => {
+    expect(() => parseWranglerConfig('wrangler.jsonc', '{ "name": ', 'jsonc')).toThrow(
+      /^wrangler\.jsonc is not valid JSONC: /,
+    );
+    expect(() => parseWranglerConfig('wrangler.toml', '[env.\nbad', 'toml')).toThrow(
+      /^wrangler\.toml is not valid TOML: /,
+    );
+  });
+
+  it('refuses anything that is not a configuration object', () => {
+    expect(() => parseWranglerConfig('wrangler.jsonc', '[1, 2]', 'jsonc')).toThrow(
+      'wrangler.jsonc is not a Wrangler configuration document: expected an object, optionally with env blocks.',
+    );
+  });
+
+  it('refuses a bare TOML date rather than shifting it through JSON', () => {
+    // The temporary per-stage config is JSON whatever the source was, and JSON.stringify would
+    // turn this into an ISO timestamp in the deploying machine's timezone.
+    expect(() => parseWranglerConfig('wrangler.toml', 'compatibility_date = 2026-05-06\n', 'toml')).toThrow(
+      'wrangler.toml declares a bare TOML date or time at compatibility_date, which JSON cannot carry; quote it as a string.',
+    );
+  });
+
+  it('refuses a non-finite TOML number rather than writing null for it', () => {
+    expect(() => parseWranglerConfig('wrangler.toml', '[env.staging.vars]\nBUDGET = inf\n', 'toml')).toThrow(
+      'wrangler.toml declares Infinity at env.staging.vars.BUDGET, which JSON cannot carry; write a finite number.',
+    );
+  });
+});

package/src/wrangler/source-config.ts

@@ -0,0 +1,110 @@
+// Where a project's Wrangler configuration lives, and how its file formats become one model.
+//
+// Wrangler reads whichever of `wrangler.jsonc`, `wrangler.json` and `wrangler.toml` it finds
+// first and says nothing about the rest: with a `.jsonc` and a `.toml` side by side, wrangler
+// 4.131.0 deploys the `.jsonc` silently, whichever of the two the repo is actually editing.
+// Discovery here follows the same precedence but refuses the pick, naming every file it found.
+//
+// Both JSON spellings go through the JSONC parser because wrangler does — comments and trailing
+// commas parse in `wrangler.json` too (verified against wrangler 4.131.0) — so the format only
+// ever decides which parser runs. Past this module there is one model and no config text.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getStaticTOMLValue, parseTOML } from 'toml-eslint-parser';
+import typia from 'typia';
+import type { WranglerDocument } from './stage.js';
+
+/** Which parser a source config needs; `wrangler.json` and `wrangler.jsonc` share one. */
+export type WranglerConfigFormat = 'jsonc' | 'toml';
+
+/** Wrangler's own precedence: the first of these that exists is the one it reads. */
+export const WRANGLER_SOURCE_CONFIG_FILES = ['wrangler.jsonc', 'wrangler.json', 'wrangler.toml'] as const;
+
+export interface WranglerSourceConfig {
+  /** The file wrangler itself would read, ready to hand back to it as `--config`. */
+  path: string;
+  document: WranglerDocument;
+}
+
+const isWranglerDocument = typia.createIs<WranglerDocument>();
+
+/**
+ * The one source config this project declares. Two configs is a refusal, not a precedence
+ * exercise: the repo would deploy whichever file wrangler prefers, which is not necessarily the
+ * one anybody is editing.
+ */
+export function discoverWranglerSourceConfig(cwd: string): { path: string; format: WranglerConfigFormat } {
+  const found = WRANGLER_SOURCE_CONFIG_FILES.filter((file) => existsSync(join(cwd, file)));
+  const [first] = found;
+  if (first === undefined) {
+    throw new Error(
+      `${cwd} declares no Wrangler configuration (${WRANGLER_SOURCE_CONFIG_FILES.join(', ')}); pass --config for a build-generated flat configuration.`,
+    );
+  }
+  if (found.length > 1) {
+    throw new Error(
+      `${cwd} declares more than one Wrangler configuration: ${found.join(', ')}. Wrangler would read ${first} and ignore the rest without saying so; keep exactly one.`,
+    );
+  }
+  return { path: join(cwd, first), format: first === 'wrangler.toml' ? 'toml' : 'jsonc' };
+}
+
+/** The discovered source config, parsed into the model every stage derivation reads. */
+export function readWranglerSourceConfig(cwd: string): WranglerSourceConfig {
+  const { path, format } = discoverWranglerSourceConfig(cwd);
+  return { path, document: parseWranglerConfig(path, readFileSync(path, 'utf8'), format) };
+}
+
+/** One document out of either format. The text is never handed on: everything downstream reads data. */
+export function parseWranglerConfig(path: string, text: string, format: WranglerConfigFormat): WranglerDocument {
+  const value = parseConfigText(path, text, format);
+  // TOML carries values JSON does not, and the temporary per-stage config is JSON whatever the
+  // source format was. Name them here rather than let JSON.stringify shift a date by its timezone
+  // or write `null` for an infinity halfway through a deploy.
+  if (format === 'toml') assertJsonRepresentable(value, '', path);
+  if (!isWranglerDocument(value)) {
+    throw new Error(
+      `${path} is not a Wrangler configuration document: expected an object, optionally with env blocks.`,
+    );
+  }
+  return value;
+}
+
+function parseConfigText(path: string, text: string, format: WranglerConfigFormat): unknown {
+  try {
+    return format === 'toml' ? getStaticTOMLValue(parseTOML(text)) : Bun.JSONC.parse(text);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`${path} is not valid ${format === 'toml' ? 'TOML' : 'JSONC'}: ${detail}`);
+  }
+}
+
+function assertJsonRepresentable(value: unknown, path: string, file: string): void {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return;
+  if (typeof value === 'number') {
+    if (Number.isFinite(value)) return;
+    throw new Error(`${file} declares ${value} at ${path}, which JSON cannot carry; write a finite number.`);
+  }
+  if (Array.isArray(value)) {
+    for (const [index, item] of value.entries()) {
+      assertJsonRepresentable(item, `${path}[${index}]`, file);
+    }
+    return;
+  }
+  if (isPlainObject(value)) {
+    for (const [key, item] of Object.entries(value)) {
+      assertJsonRepresentable(item, path ? `${path}.${key}` : key, file);
+    }
+    return;
+  }
+  throw new Error(
+    `${file} declares a bare TOML ${value instanceof Date ? 'date or time' : typeof value} at ${path}, which JSON cannot carry; quote it as a string.`,
+  );
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null) return false;
+  const prototype: unknown = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}