@lunora/config 1.0.0-alpha.26 → 1.0.0-alpha.261

package/dist/cloudflare/index.d.ts

@@ -0,0 +1,969 @@
+import { D as DeployDriver, G as GeneratedClassModule, I as InferredBindings, S as SchemaInfo } from "../packem_shared/schema-info.d-DvKkJ7HJ.js";
+import { WranglerVariableIR } from '@lunora/codegen';
+/**
+ * Translate a `wrangler.jsonc` into an [Alchemy](https://alchemy.run) program.
+ *
+ * # Why translate rather than ask for a second config
+ *
+ * `wrangler.jsonc` is already the source of truth for what an app needs, and
+ * Lunora already infers and reconciles it — `inferLunoraBindings` decides that
+ * a project needs a shard namespace and a bucket, `reconcileWranglerBindings`
+ * writes them. Asking a developer to restate all of that in an
+ * `alchemy.run.ts` would give the project two sources of truth that drift, and
+ * the drift would surface as a deploy that provisions something the app does
+ * not bind.
+ *
+ * So Alchemy is an implementation detail of `deploy`, not a thing to configure:
+ * read the config, emit the program, run it.
+ *
+ * # Why this emits source rather than calling Alchemy
+ *
+ * `alchemy@0.93` has thirty dependencies, nine of them Node-shaped —
+ * `wrangler`, `miniflare`, `esbuild`, `execa`, `find-process`, `glob`, `open`,
+ * `proper-lockfile`, `signal-exit`. `@lunora/config` is imported by
+ * `@lunora/vite`, so importing Alchemy here would push that tree into every
+ * project that merely wanted to read `lunora.config.*`, and into any bundle
+ * targeting workerd — where none of it survives.
+ *
+ * Emitting text keeps this module pure and dependency-free. Alchemy is invoked
+ * as a CLI against the generated file, so it only has to exist on the machine
+ * that deploys.
+ *
+ * # Adoption, not re-creation
+ *
+ * Every resource is emitted with `adopt: true`. A project translated from an
+ * existing `wrangler.jsonc` already *has* its D1 database and its bucket, with
+ * data in them. Without adoption Alchemy would treat them as new and try to
+ * create alongside — the one outcome a deploy must never have.
+ */
+/** A Durable Object binding as `wrangler.jsonc` spells it. */
+interface WranglerDurableObjectBinding$1 {
+  class_name?: string;
+  name?: string;
+  script_name?: string;
+}
+/** The slice of `wrangler.jsonc` that translates into Alchemy resources. */
+interface WranglerConfigShape {
+  compatibility_date?: string;
+  compatibility_flags?: ReadonlyArray<string>;
+  d1_databases?: ReadonlyArray<{
+    binding?: string;
+    database_id?: string;
+    database_name?: string;
+  }>;
+  durable_objects?: {
+    bindings?: ReadonlyArray<WranglerDurableObjectBinding$1>;
+  };
+  kv_namespaces?: ReadonlyArray<{
+    binding?: string;
+    id?: string;
+  }>;
+  main?: string;
+  /** `new_sqlite_classes` marks which DO classes get SQLite storage — Alchemy needs that per namespace. */
+  migrations?: ReadonlyArray<{
+    new_classes?: ReadonlyArray<string>;
+    new_sqlite_classes?: ReadonlyArray<string>;
+  }>;
+  name?: string;
+  /** Only `producers` translate; a `consumers` entry is dropped and reported as `queues.consumers`. */
+  queues?: {
+    consumers?: ReadonlyArray<{
+      queue?: string;
+    }>;
+    producers?: ReadonlyArray<{
+      binding?: string;
+      queue?: string;
+    }>;
+  };
+  r2_buckets?: ReadonlyArray<{
+    binding?: string;
+    bucket_name?: string;
+  }>;
+  triggers?: {
+    crons?: ReadonlyArray<string>;
+  };
+  vars?: Readonly<Record<string, unknown>>;
+}
+/** What the translation could not carry over, so the caller can say so out loud. */
+interface AlchemyTranslation {
+  /** The emitted program source. */
+  source: string;
+  /**
+   * Bindings present in `wrangler.jsonc` that this translation drops.
+   *
+   * Reported rather than silently omitted: a deploy that quietly loses a
+   * Vectorize index produces a worker whose `env.POSTS_SEARCH` is undefined
+   * at runtime, and nothing in the build says why.
+   */
+  unsupported: ReadonlyArray<string>;
+}
+/**
+ * Translate a parsed `wrangler.jsonc` into an Alchemy program.
+ *
+ * Pure: it reads nothing and writes nothing, so the caller decides where the
+ * source lands and the whole thing stays testable as a string comparison.
+ * @param config The parsed `wrangler.jsonc`.
+ * @returns the program source, plus whatever could not be carried over.
+ */
+declare const wranglerToAlchemy: (config: WranglerConfigShape) => AlchemyTranslation;
+/** Schema version of the emitted document, so a consumer can gate on shape changes. */
+declare const BINDING_MANIFEST_VERSION = 1;
+/**
+ * One resource the built Worker expects to be bound to. `binding` is the name the
+ * Worker reads off `env`; the remaining fields are whatever identifies the
+ * resource for that type, omitted when the config does not carry them (an id
+ * Lunora could not mint is absent here exactly as it is absent from the config).
+ */
+interface BindingRequirement {
+  /** The `env` property name the Worker reads. */
+  binding: string;
+  /**
+   * Durable Object / Workflow / Container class the Worker must export. Present
+   * for the class-backed binding types, so a deployer can assert the bundle
+   * exports it before publishing.
+   */
+  className?: string;
+  /** Bucket name (`r2`), database name (`d1`), dataset (`analytics_engine`), queue name (`queue`), index (`vectorize`), pipeline (`pipelines`). */
+  resource?: string;
+  /** Remote resource id, when the config declares one (`d1`, `kv`, `hyperdrive`). */
+  resourceId?: string;
+  /** For `durable_object`: whether the class uses SQLite storage (`new_sqlite_classes`). */
+  sqlite?: boolean;
+  /** The kind of resource, keyed to the wrangler section it came from. */
+  type: "ai" | "analytics_engine" | "assets" | "browser" | "container" | "d1" | "durable_object" | "hyperdrive" | "images" | "kv" | "pipeline" | "queue_consumer" | "queue_producer" | "r2" | "vectorize" | "workflow";
+}
+/** The document the `lunora build --emit-bindings` flag writes. */
+interface BindingManifest {
+  /** Every resource the Worker expects, sorted by `type` then `binding` so the file is diff-stable. */
+  bindings: ReadonlyArray<BindingRequirement>;
+  /** `compatibility_date`, when declared. */
+  compatibilityDate?: string;
+  /** `compatibility_flags`, when declared. */
+  compatibilityFlags?: ReadonlyArray<string>;
+  /** Cron expressions the Worker must be triggered on (`triggers.crons`). */
+  crons: ReadonlyArray<string>;
+  /** Worker name from `wrangler.jsonc`. */
+  name?: string;
+  /**
+   * Wrangler sections present in the config that this version does not model,
+   * by field name. Empty for a fully-understood config; non-empty is a prompt to
+   * extend the collector, and is surfaced to the user rather than silently
+   * dropped.
+   */
+  unknown: ReadonlyArray<string>;
+  /** Names of `vars` entries. Values are deliberately excluded — a manifest is committed and read by CI, and a `vars` entry can hold a value a project would rather not publish. */
+  vars: ReadonlyArray<string>;
+  /** Schema version — {@link BINDING_MANIFEST_VERSION}. */
+  version: number;
+}
+/**
+ * The wider config this reads. {@link WranglerConfigShape} covers what the
+ * Alchemy translation models; a manifest additionally reports the sections that
+ * translation lists as unsupported, so those are declared here.
+ */
+interface ManifestConfigShape extends WranglerConfigShape {
+  ai?: {
+    binding?: string;
+  };
+  analytics_engine_datasets?: ReadonlyArray<{
+    binding?: string;
+    dataset?: string;
+  }>;
+  /** Static assets carry a real `binding` the Worker reads (`env.ASSETS`). */
+  assets?: {
+    binding?: string;
+    directory?: string;
+  };
+  browser?: {
+    binding?: string;
+  };
+  containers?: ReadonlyArray<{
+    class_name?: string;
+    image?: string;
+    max_instances?: number;
+  }>;
+  hyperdrive?: ReadonlyArray<{
+    binding?: string;
+    id?: string;
+  }>;
+  images?: {
+    binding?: string;
+  };
+  pipelines?: ReadonlyArray<{
+    binding?: string;
+    pipeline?: string;
+  }>;
+  /** Adds `consumers` — the Alchemy translation models producers only. */
+  queues?: {
+    consumers?: ReadonlyArray<{
+      queue?: string;
+    }>;
+    producers?: ReadonlyArray<{
+      binding?: string;
+      queue?: string;
+    }>;
+  };
+  vectorize?: ReadonlyArray<{
+    binding?: string;
+    index_name?: string;
+  }>;
+  workflows?: ReadonlyArray<{
+    binding?: string;
+    class_name?: string;
+    name?: string;
+  }>;
+}
+/**
+ * Build the manifest for a parsed `wrangler.jsonc`.
+ *
+ * Pure: reads nothing and writes nothing, so the caller decides where the
+ * document lands and the mapping stays testable as a plain object comparison.
+ * @param config The parsed, already-reconciled `wrangler.jsonc`.
+ * @returns the requirements document.
+ */
+declare const buildBindingManifest: (config: ManifestConfigShape) => BindingManifest;
+/** The Cloudflare deploy driver. */
+declare const CLOUDFLARE_DRIVER: DeployDriver;
+/**
+ * A container/workflow that is declared (so codegen emits its class) but the
+ * worker entry never re-exports — the one wiring step the generators can't always
+ * do for the developer. wrangler rejects a `class_name` the deployed worker
+ * doesn't export, so a deploy fails late on this; surfacing it as structured data
+ * lets the Vite plugin raise it in the dev error overlay (not just the console)
+ * the moment the gap appears. The human-readable form is also folded into
+ * {@link ReconcileBindingsResult.warnings}.
+ */
+interface ExportGap {
+  /** Generated class wrangler needs exported, e.g. `OrderPipelineWorkflow`. */
+  className: string;
+  /** The `lunora/{agents,containers,workflows}.ts` export name, e.g. `orderPipeline`. */
+  exportName: string;
+  /** Which declaration is unexported. */
+  kind: "agent" | "container" | "workflow";
+  /** The `_generated/{module}` to re-export from, e.g. `workflows`. */
+  module: GeneratedClassModule;
+}
+interface ReconcileBindingsResult {
+  /** Short labels for each binding written (e.g. `"SCHEDULER/SchedulerDO"`). */
+  added: string[];
+  /** `true` when `wrangler.jsonc` was rewritten. */
+  changed: boolean;
+  /**
+   * Declared containers/workflows the worker entry doesn't re-export — the
+   * structured form of the corresponding `warnings` entries, for the dev error
+   * overlay. Empty when every declaration is wired.
+   */
+  exportGaps: ExportGap[];
+  /** Reason reconciliation was skipped, for logging. */
+  reason?: string;
+  /**
+   * Short labels for each EXISTING entry whose settings were brought in line
+   * with its declaration (e.g. `"queues.consumers/receipt-queue (max_retries)"`).
+   * Kept apart from `added` so a retune is not logged as a new binding.
+   */
+  updated: string[];
+  /** Non-fatal hints for capabilities that cannot be auto-provisioned. */
+  warnings: string[];
+  /** Resolved wrangler path, or `undefined` when none was found. */
+  wranglerPath?: string;
+}
+/**
+ * The declared-but-not-re-exported containers and workflows, as structured
+ * {@link ExportGap}s. The same gaps `collectWarnings` renders into prose — kept
+ * here as data so the Vite plugin can raise them in the error overlay with a
+ * precise remediation, rather than re-parsing the warning strings.
+ *
+ * Exported because reconciliation is not the only caller that needs the answer:
+ * `lunora codegen` and `lunora doctor` both want the gaps WITHOUT rewriting
+ * `wrangler.jsonc`, which is the rest of what {@link reconcileWranglerBindings}
+ * does. Deriving them again from `inferred.{containers,workflows,agents}` at each
+ * call site is how one kind ends up silently uncovered.
+ */
+declare const collectExportGaps: (inferred: InferredBindings) => ExportGap[];
+/**
+ * Reconcile inferred Durable Object / D1 bindings into `wrangler.jsonc`.
+ *
+ * Writes only when something is missing; returns `changed: false` when the
+ * config already satisfies the inferred needs.
+ *
+ * `environment`, when passed, does NOT change where this provisions — every
+ * step below still only ADDS to the TOP-LEVEL config; wrangler's `env.<name>`
+ * blocks have no auto-provisioning path today. The one write into the block is
+ * {@link reconcileEnvQueues}, which retunes queue consumers the block already
+ * declares and adds nothing. Otherwise it is used only to emit an
+ * advisory warning, because bindings (`durable_objects`, `d1_databases`, …)
+ * are non-inheritable (see `wrangler-validator.ts`'s `NON_INHERITABLE_KEYS`):
+ * a `--env production` deploy needs its OWN copy of each one, and silently
+ * writing only to the top level would leave that gap unmentioned. Extending
+ * the JSONC writer itself to target `env.<name>.*` idempotently for every
+ * binding kind here is a separate, larger change (each of the ~10 pipeline
+ * steps below reads AND writes the top-level path) that this fix does not
+ * attempt — `lunora deploy --env <name>` now VALIDATES the env-scoped view
+ * (closing the reported gap), it just doesn't yet auto-provision it.
+ */
+declare const reconcileWranglerBindings: (projectRoot: string, inferred: InferredBindings, environment?: string) => ReconcileBindingsResult;
+interface ReconcileCompatibilityDateResult {
+  /** `true` when `wrangler.jsonc` was rewritten. */
+  changed: boolean;
+  /** The new date value, or the existing one when unchanged. */
+  date: string | undefined;
+  /** Human-readable reason when reconciliation was skipped. */
+  reason?: string;
+  /** Resolved wrangler path, or `undefined` when none was found. */
+  wranglerPath?: string;
+}
+/**
+ * Reconcile the `compatibility_date` in `wrangler.jsonc` when Workers Cache
+ * is enabled but the date is below the minimum required.
+ */
+declare const reconcileWranglerCompatibilityDate: (projectRoot: string) => ReconcileCompatibilityDateResult;
+interface ReconcileResult {
+  /** `true` when the wrangler config's `triggers.crons` was rewritten. */
+  changed: boolean;
+  /**
+   * Entries left in `triggers.crons` that this reconciler did not generate and
+   * does not own — a hand-written `backupCron` trigger, or anything already
+   * there before ownership was first recorded. Non-empty means the array is
+   * NOT the codegen-derived set, which is the surprising half of what this
+   * does and the one thing worth printing.
+   */
+  preserved: string[];
+  /** Human-readable reason when reconciliation was skipped (for logging). */
+  reason?: string;
+  /**
+   * Problems with the ownership record itself, for the caller to `warn`. A
+   * damaged `lunora.crons` is not fatal — the reconciler degrades to add-only
+   * — but the degradation is invisible: the generated cron it wrote last pass
+   * is reported back as hand-written and is then kept for good. Silence is
+   * what turns a merge conflict into a permanent orphan.
+   */
+  warnings: string[];
+  /** Resolved wrangler path, or `undefined` when none was found. */
+  wranglerPath?: string;
+}
+/**
+ * Reconcile the codegen-derived cron schedules into the project's wrangler
+ * config `triggers.crons` array, preserving comments and formatting via
+ * `jsonc-parser`'s structural edits.
+ *
+ * **This does not own the whole array.** Two runtime cron surfaces live on
+ * `createWorker` rather than in `lunora/crons.ts`: `backupCron` (the nightly
+ * NDJSON backup) and `crons` (handlers keyed by expression). Replacing the array
+ * wholesale deleted both on the next `lunora deploy` or dev-server schema save,
+ * silently — the nightly backup simply stopped. So an entry this reconciler did
+ * not generate is the user's, is kept, and is reported in
+ * {@link ReconcileResult.preserved}.
+ *
+ * Codegen now scans the worker entry for both, so the STATIC case arrives in
+ * `cronTriggers` like any declared cron — kept because it is generated, and
+ * cleared when the entry stops declaring it. What it cannot resolve is the
+ * dynamic case, and that case is supported: `.extend((env) => ({ backupCron:
+ * env.NIGHTLY_CRON }))` is the documented escape hatch, and its value exists
+ * only at runtime. That residue — plus a computed `crons` key, a spread options
+ * object, and anything a project put in `triggers.crons` for its own reasons —
+ * is what the preserve rule below is for. It is not redundant with discovery; it
+ * is the half discovery provably cannot reach.
+ *
+ * Ownership is recorded in the project's `package.json` under `lunora.crons`,
+ * which is why a REMOVED generated cron still gets cleared (it is in the record
+ * and no longer in `cronTriggers`) while a hand-written one never is. Three
+ * properties pick that location:
+ *
+ * COMMITTED, so it survives a fresh clone. Gitignored `.lunora/` state does not:
+ * a CI-only deploy finds none, and falling back to add-only there leaves a
+ * removed cron firing forever.
+ *
+ * VALID JSON, so `wrangler.json` — a supported config name — behaves exactly like
+ * `wrangler.jsonc`. A `//` marker inside the config does not: wrangler tolerates
+ * one in either (both go through its JSONC parser), but the project's own
+ * `JSON.parse`, its deploy wrapper and its editor's JSON schema validation all
+ * break the moment a `.json` grows a comment. Nor can the record be a plain key
+ * in the wrangler config — wrangler reports unknown fields ("Unexpected fields
+ * found in top-level field") on every command.
+ *
+ * READ AND WRITTEN AT ONE ADDRESS. A comment has to be found textually on the way
+ * in and positioned structurally on the way out, and those are not the same
+ * place: a stale duplicate higher in the file was read as the record and deleted
+ * the user's backup trigger.
+ *
+ * The wrangler config is rewritten only when an entry actually moves, so
+ * {@link ReconcileResult.changed} means what a `synced N cron trigger(s)` log
+ * claims it means.
+ *
+ * A project with nothing recorded yet — one predating this, or one with no
+ * manifest — treats every entry as the user's, which is the safe direction: a
+ * wrongly-kept trigger costs one no-op invocation, a wrongly-deleted one
+ * silently ends the backups. It becomes precise after a codegen run that still
+ * declares the cron; upgrading and deleting a cron in the same change records an
+ * empty set, and that orphan is then kept for good.
+ *
+ * This intentionally writes the SAME `triggers.crons` shape the
+ * `@lunora/config` validator accepts, so the wrangler validator never fights the
+ * generated value.
+ */
+declare const reconcileWranglerCrons: (projectRoot: string, cronTriggers: ReadonlyArray<string>) => ReconcileResult;
+/**
+ * The one log line worth printing for a reconcile that kept entries it does not
+ * own, or `undefined` when it owned the whole array. Lives here rather than in
+ * each caller because `lunora deploy` and the Vite plugin print it verbatim and
+ * had already drifted into two copies of the same sentence.
+ */
+declare const describePreservedCrons: (preserved: ReadonlyArray<string>) => string | undefined;
+/**
+ * The wrangler config sections Lunora can safely flip to remote mode in dev,
+ * each with the human label used in logs and the structural `shape` the entry
+ * lives in.
+ *
+ * `"array"` is a top-level array of binding objects (`d1_databases`,
+ * `kv_namespaces`, `r2_buckets`, `vectorize`, `services`). `"producers"` is
+ * `queues.producers[]` — consumers are NOT remoted (their schema has no `remote`
+ * field) and the edit path is two levels deep. `"object"` is a single binding
+ * object, not an array (`ai`), whose edit path targets the section key directly.
+ *
+ * Every kind here was confirmed against `wrangler/config-schema.json`: the
+ * entry's schema declares a `remote` property. Deliberately omits
+ * `durable_objects` (no CF remote-DO mode; shards stay local) and sections whose
+ * schema has no `remote` field (`hyperdrive`, `analytics_engine_datasets`,
+ * `secrets_store_secrets`, queue consumers, …). Widening further is a one-line
+ * table edit.
+ */
+declare const REMOTE_ELIGIBLE_KEYS: {
+  readonly ai: {
+    readonly label: "AI";
+    readonly shape: "object";
+  };
+  readonly d1_databases: {
+    readonly label: "D1";
+    readonly shape: "array";
+  };
+  readonly kv_namespaces: {
+    readonly label: "KV";
+    readonly shape: "array";
+  };
+  readonly queues: {
+    readonly label: "Queue";
+    readonly shape: "producers";
+  };
+  readonly r2_buckets: {
+    readonly label: "R2";
+    readonly shape: "array";
+  };
+  readonly services: {
+    readonly label: "Service";
+    readonly shape: "array";
+  };
+  readonly vectorize: {
+    readonly label: "Vectorize";
+    readonly shape: "array";
+  };
+};
+type RemoteEligibleKey = keyof typeof REMOTE_ELIGIBLE_KEYS;
+/** One binding object as it appears in any eligible section. */
+interface BindingEntry {
+  binding?: string;
+  remote?: boolean;
+}
+/** One binding entry we mark remote, with enough provenance to log + edit it. */
+interface RemoteBindingPlan {
+  /** The binding name as declared in the config (e.g. `"DB"`, `"FILES"`). */
+  binding: string;
+  /** Short kind label for logging (`"D1"`, `"KV"`, `"R2"`, `"Vectorize"`, …). */
+  kind: string;
+  /**
+   * The jsonc edit path within {@link RemoteBindingPlan.section}, relative to
+   * the section key: `[index]` for an `"array"` section, `["producers", index]`
+   * for a queue producer, or `[]` for the single-object `ai` section. The
+   * materializer prepends the section key and appends `"remote"`.
+   */
+  path: ReadonlyArray<number | string>;
+  /** The wrangler config key the entry lives under. */
+  section: RemoteEligibleKey;
+}
+/** The structural slice of a wrangler config the remote planner reads. */
+interface RemoteWranglerShape {
+  ai?: BindingEntry | null;
+  d1_databases?: ReadonlyArray<BindingEntry | null | undefined>;
+  kv_namespaces?: ReadonlyArray<BindingEntry | null | undefined>;
+  queues?: {
+    producers?: ReadonlyArray<BindingEntry | null | undefined>;
+  } | null;
+  r2_buckets?: ReadonlyArray<BindingEntry | null | undefined>;
+  services?: ReadonlyArray<BindingEntry | null | undefined>;
+  vectorize?: ReadonlyArray<BindingEntry | null | undefined>;
+}
+/**
+ * Inspect a parsed wrangler config and list every eligible binding that should
+ * be flipped to remote mode. Pure — no file-system access, no mutation. An
+ * entry already carrying `"remote": true` is still reported (so logging is
+ * complete) but the materializer's edit is a harmless no-op for it.
+ */
+declare const planRemoteBindings: (parsed: RemoteWranglerShape) => RemoteBindingPlan[];
+/**
+ * Inject `"remote": true` onto each planned binding in the config `text`,
+ * comment-preservingly via jsonc edits. Pure string→string; the edits target
+ * disjoint entries so applying them sequentially is safe. The edit path is
+ * `[section, ...plan.path, "remote"]`, which resolves to the array element, the
+ * `queues.producers[i]` entry, or the single `ai` object as the plan demands.
+ */
+declare const injectRemoteFlags: (text: string, plans: ReadonlyArray<RemoteBindingPlan>) => string;
+interface MaterializeOptions {
+  /** When `false`, the call is a no-op (returns `enabled: false`). */
+  enabled: boolean;
+  projectRoot: string;
+}
+interface MaterializeResult {
+  /**
+   * Removes the generated temp config file. Always present and always safe to
+   * call: it is idempotent, a no-op when nothing was written (disabled /
+   * fall-through cases), and never throws if the path is already gone. The dev
+   * command calls this on every exit path (normal, signal, error).
+   */
+  cleanup: () => void;
+  /**
+   * Absolute path to the generated temp config to pass to
+   * `wrangler dev --config`. `undefined` when remote mode is disabled, no
+   * wrangler config was found, it failed to parse, or it declared no eligible
+   * binding (nothing to remote — run plain local dev).
+   */
+  configPath?: string;
+  /** Whether remote mode was requested at all. */
+  enabled: boolean;
+  /** Why no temp config was produced, for logging (only set when none was). */
+  reason?: string;
+  /** The bindings flipped to remote, for the dev banner. */
+  remoteBindings: RemoteBindingPlan[];
+}
+/**
+ * Produce a temporary wrangler config with `"remote": true` on every eligible
+ * binding, so `lunora dev` can run `wrangler dev --config <temp>` against the
+ * deployed D1/KV/R2 without touching the user's file.
+ *
+ * The temp file is written as a sibling of the source `wrangler.jsonc` (in the
+ * project root), NOT an OS temp dir: wrangler resolves a config's relative paths
+ * (`main`, `assets`, `migrations_dir`, …) against the **config file's own
+ * directory**, so a temp config in `/tmp` would make wrangler look for
+ * `/tmp/src/server.ts` and fail to start the worker. Keeping it beside the real
+ * config preserves those relative paths. Returns `configPath: undefined` (with a
+ * `reason`) for every fall-through case so the caller degrades to plain local
+ * dev instead of failing.
+ */
+declare const materializeRemoteWranglerConfig: (options: MaterializeOptions) => MaterializeResult;
+/**
+ * Parse a `LUNORA_REMOTE` env value into the on/off decision. Truthy when set to
+ * `"1"` or `"true"` (case-insensitive); anything else — unset, `"0"`, `"false"`,
+ * empty — is off. Mirrors the `"1" | "true"` convention used across the runtime.
+ */
+declare const isRemoteEnvEnabled: (value: string | undefined) => boolean;
+/** The three inputs that can switch remote-binding dev on, in precedence order. */
+interface RemoteEnableInputs {
+  /**
+   * The `remote` preference from `lunora.config.*` (the lowest-priority signal).
+   * `undefined` means "no project preference"; an explicit `false` here loses
+   * to neither the flag nor the env when those are absent — it just stays off.
+   */
+  configPreference?: boolean;
+  /** The raw `LUNORA_REMOTE` env value (parsed with {@link isRemoteEnvEnabled}). */
+  envValue?: string;
+  /** The explicit `--remote` CLI flag — `true` when passed, `undefined`/`false` otherwise. */
+  flag?: boolean;
+}
+/**
+ * Resolve whether remote-binding dev is on, with a clear precedence:
+ *
+ * 1. an explicit `--remote` flag (highest — a deliberate per-invocation choice),
+ * 2. then `LUNORA_REMOTE` in the environment,
+ * 3. then the `remote` key in `lunora.config.*` (lowest — a project default).
+ *
+ * The flag and env are one-directional (they can only turn remote *on*); only
+ * the config preference carries a meaningful `false`, and it applies solely when
+ * neither stronger signal is present. So a project that sets `"remote": false`
+ * is still overridable per-run by `--remote` or `LUNORA_REMOTE=1`.
+ */
+declare const resolveRemoteEnabled: (inputs: RemoteEnableInputs) => boolean;
+/**
+ * Single source of truth for "does this wrangler config enable Workers
+ * Cache?" and "what compatibility_date does that require?".
+ *
+ * Before this module, `reconcile-compatibility-date.ts` (auto-bump) and
+ * `wrangler-validator.ts` (validation) each carried their own
+ * `WORKERS_CACHE_MIN_DATE` literal and their own top-level/`exports[]`
+ * cache-enabled walk — two copies of the same fact that could silently drift
+ * apart (a date bumped in one file without the other would either validate a
+ * config the reconciler wouldn't produce, or vice versa).
+ */
+/** The `compatibility_date` Workers Cache (`cache.enabled: true`) requires. */
+declare const WORKERS_CACHE_MIN_DATE = "2026-05-01";
+/** The subset of a parsed `wrangler.jsonc` the cache-enabled check reads. */
+interface WranglerCacheShape {
+  cache?: {
+    enabled?: boolean;
+  } | null;
+  exports?: Record<string, {
+    cache?: {
+      enabled?: boolean;
+    } | null;
+  } | null> | null;
+}
+/**
+ * Whether Workers Cache is enabled anywhere in a parsed wrangler config — the
+ * top-level `cache.enabled` toggle, or a per-export override in
+ * `exports[name].cache.enabled` (Workers can scope cache per named export).
+ * `undefined`/`null` (an unparsed or absent config) is treated as disabled.
+ */
+declare const isCacheEnabled: (parsed: WranglerCacheShape | null | undefined) => boolean;
+/** Candidate wrangler config filenames, in the order every consumer probes them. */
+declare const WRANGLER_FILES: readonly ["wrangler.jsonc", "wrangler.json"];
+/** Locate the project's wrangler config, or `undefined` when none exists. */
+declare const findWranglerFile: (projectRoot: string) => string | undefined;
+interface ReadWranglerResult<T> {
+  /** Parsed config, or `undefined` when the file was not valid JSONC. */
+  parsed: T | undefined;
+  /** Raw file text — needed for comment-preserving `modify`/`applyEdits`. */
+  text: string;
+}
+/**
+ * Read and JSONC-parse a wrangler config file. Returns the raw `text` (for
+ * structural edits) alongside `parsed`, which is `undefined` when the file is
+ * not valid JSONC or does not parse to an object. Allows trailing commas, as
+ * wrangler does.
+ */
+declare const readWranglerJsonc: <T = unknown>(wranglerPath: string) => ReadWranglerResult<T>;
+/**
+ * Pure scan of a `vars` map for plaintext secrets — the FS-free core, exported for
+ * unit tests. A variable is flagged when, for a **string** value that is neither a
+ * placeholder nor a public/publishable key, EITHER the value matches a known
+ * secret shape (`secretKindOf`) OR the key name strongly implies a secret and the
+ * value is long enough to plausibly be one. `kind` is the matched shape, or
+ * `secret_named_var` for the key-name path.
+ */
+declare const scanWranglerVariablesForSecrets: (variables: Record<string, unknown> | undefined, file: string) => WranglerVariableIR[];
+/**
+ * Read the project's `wrangler.jsonc` and return its plaintext-secret `vars` as IR
+ * for the `plaintext_secret_in_wrangler_vars` lint. Returns `[]` when there is no
+ * wrangler config, it doesn't parse, or nothing looks like a secret. Scans the
+ * top-level `vars` block (mirroring the existing `validateCorsVariables` scope);
+ * per-environment `env.<name>.vars` overrides are out of scope for now.
+ */
+declare const collectWranglerSecretVariables: (projectRoot: string) => WranglerVariableIR[];
+declare const REQUIRED_COMPATIBILITY_DATE: string;
+declare const REQUIRED_FLAG: string;
+interface WranglerDurableObjectBinding {
+  class_name?: string;
+  name?: string;
+  /** Present when the class lives in ANOTHER Worker — then it is that script's to export, not this entry's. */
+  script_name?: string;
+}
+/**
+ * A `tail_consumers` entry: a Worker that receives this Worker's tail events
+ * (logs, exceptions, fetch metadata) for forwarding to an external sink. See
+ * `withTailConsumer` for the wiring helper.
+ */
+interface TailConsumer {
+  /** Optional Cloudflare environment of the consumer Worker. */
+  environment?: string;
+  /** Name of the Worker that consumes tail events. */
+  service?: string;
+}
+/** A wrangler `containers[]` entry (parsed from untrusted JSONC). */
+interface WranglerContainerEntry {
+  class_name?: string;
+  image?: string;
+  instance_type?: string | {
+    disk_mb?: number;
+    memory_mib?: number;
+    vcpu?: number;
+  };
+  max_instances?: number;
+}
+/**
+ * A wrangler `workflows[]` entry (parsed from untrusted JSONC). Unlike
+ * containers, workflows are NOT Durable Objects — the entry stands alone (no
+ * `durable_objects` binding, no migration class).
+ */
+interface WranglerWorkflowEntry {
+  binding?: string;
+  class_name?: string;
+  name?: string;
+  /** Present when the class lives in ANOTHER Worker — then it is that script's to export. */
+  script_name?: string;
+}
+/** A wrangler `queues.producers[]` entry — a `Queue` binding sending to `queue`. */
+interface WranglerQueueProducer {
+  binding?: string;
+  delivery_delay?: number;
+  queue?: string;
+}
+/** A wrangler `queues.consumers[]` entry — push (worker) or `type: "http_pull"`. */
+interface WranglerQueueConsumer {
+  dead_letter_queue?: string;
+  max_batch_size?: number;
+  max_batch_timeout?: number;
+  max_retries?: number;
+  queue?: string;
+  retry_delay?: number;
+  type?: string;
+}
+interface WranglerConfig {
+  analytics_engine_datasets?: ReadonlyArray<{
+    binding?: string;
+    dataset?: string;
+  } | null | undefined>;
+  assets?: {
+    binding?: string;
+    directory?: string;
+    html_handling?: string;
+    not_found_handling?: string;
+  };
+  browser?: {
+    binding?: string;
+  };
+  cache?: {
+    enabled?: boolean;
+  } | null;
+  compatibility_date?: string;
+  compatibility_flags?: ReadonlyArray<string>;
+  containers?: ReadonlyArray<WranglerContainerEntry | null | undefined>;
+  d1_databases?: ReadonlyArray<{
+    binding?: string;
+    database_id?: string;
+    database_name?: string;
+  } | null | undefined>;
+  dispatch_namespaces?: ReadonlyArray<{
+    binding?: string;
+    namespace?: string;
+    outbound?: unknown;
+  } | null | undefined>;
+  durable_objects?: {
+    bindings?: ReadonlyArray<WranglerDurableObjectBinding>;
+  };
+  env?: Record<string, WranglerConfig>;
+  exports?: Record<string, {
+    cache?: {
+      enabled?: boolean;
+    } | null;
+    type?: string;
+  } | null> | null;
+  flagship?: ReadonlyArray<{
+    app_id?: string;
+    binding?: string;
+  } | null | undefined>;
+  hyperdrive?: ReadonlyArray<{
+    binding?: string;
+    id?: string;
+    localConnectionString?: string;
+  } | null | undefined>;
+  images?: {
+    binding?: string;
+  };
+  kv_namespaces?: ReadonlyArray<{
+    binding?: string;
+    id?: string;
+  } | null | undefined>;
+  limits?: {
+    cpu_ms?: number;
+  };
+  logpush?: boolean;
+  main?: string;
+  migrations?: ReadonlyArray<{
+    deleted_classes?: ReadonlyArray<string>;
+    new_classes?: ReadonlyArray<string>;
+    new_sqlite_classes?: ReadonlyArray<string>;
+    renamed_classes?: ReadonlyArray<{
+      from?: string;
+      to?: string;
+    } | null | undefined>;
+  } | null | undefined>;
+  mtls_certificates?: ReadonlyArray<{
+    binding?: string;
+    certificate_id?: string;
+  } | null | undefined>;
+  observability?: {
+    enabled?: boolean;
+    head_sampling_rate?: number;
+    logs?: {
+      enabled?: boolean;
+      head_sampling_rate?: number;
+      invocation_logs?: boolean;
+    };
+  };
+  pipelines?: ReadonlyArray<{
+    binding?: string;
+    pipeline?: string;
+    stream?: string;
+  } | null | undefined>;
+  placement?: {
+    host?: string;
+    hostname?: string;
+    mode?: string;
+    region?: string;
+  };
+  queues?: {
+    consumers?: ReadonlyArray<WranglerQueueConsumer | null | undefined>;
+    producers?: ReadonlyArray<WranglerQueueProducer | null | undefined>;
+  };
+  r2_buckets?: ReadonlyArray<{
+    binding?: string;
+    bucket_name?: string;
+  } | null | undefined>;
+  secrets_store_secrets?: ReadonlyArray<{
+    binding?: string;
+    secret_name?: string;
+    store_id?: string;
+  } | null | undefined>;
+  send_email?: ReadonlyArray<{
+    allowed_destination_addresses?: ReadonlyArray<string>;
+    destination_address?: string;
+    name?: string;
+  } | null | undefined>;
+  services?: ReadonlyArray<{
+    binding?: string;
+    entrypoint?: string;
+    environment?: string;
+    service?: string;
+  } | null | undefined>;
+  tail_consumers?: ReadonlyArray<TailConsumer | null | undefined>;
+  vars?: Record<string, unknown>;
+  vectorize?: ReadonlyArray<{
+    binding?: string;
+    index_name?: string;
+  } | null | undefined>;
+  workflows?: ReadonlyArray<WranglerWorkflowEntry | null | undefined>;
+}
+interface WranglerValidationReport {
+  errors: string[];
+  valid: boolean;
+  warnings: string[];
+}
+interface WranglerEnvironmentMerge {
+  /** Set when `environment` names no `env.<name>` block declared in the config — the caller should treat this as a hard validation failure. */
+  error?: string;
+  /** The env-scoped view: `wrangler` unchanged when `environment` is `undefined`, otherwise merged per {@link NON_INHERITABLE_KEYS} / {@link INHERITABLE_KEYS}. */
+  merged: WranglerConfig;
+  /**
+   * Keys the env block overrides whose inheritance status this validator
+   * cannot verify (not in either table above) — validated against the
+   * TOP-LEVEL value only, per the "do not guess" rule; the override is
+   * silently ignored for validation purposes. The caller logs this ONCE
+   * (not per key) so an unusual `env.<name>` block doesn't spam warnings.
+   */
+  unverifiedKeys: string[];
+}
+/**
+ * Resolve the config view `wrangler deploy --env <environment>` will actually
+ * use. Undefined `environment` returns `wrangler` unchanged — the top-level
+ * config is what a plain `wrangler deploy` reads, same as today.
+ *
+ * Deliberately independent of any other merge in this module: called fresh
+ * from the ORIGINAL `wrangler` each time (see both call sites), so there is
+ * no risk of merging an already-merged config and silently losing the
+ * top-level fallback a second merge pass would no longer have access to.
+ */
+declare const mergeWranglerEnvironment: (wrangler: WranglerConfig, environment: string | undefined) => WranglerEnvironmentMerge;
+/**
+ * Return a new `WranglerConfig` with `consumer` present in `tail_consumers`,
+ * wiring this Worker to forward its tail events (logs/exceptions) to another
+ * Worker that fans them out to an external sink. Pure and idempotent: an
+ * existing entry with the same `service` + `environment` is left untouched
+ * rather than duplicated, so it is safe to call on every codegen/deploy.
+ */
+declare const withTailConsumer: (wrangler: WranglerConfig, consumer: TailConsumer) => WranglerConfig;
+/**
+ * Pure validator: given a parsed `WranglerConfig` object and an optional
+ * `SchemaInfo`, produce a structured report. Performs no I/O.
+ *
+ * `environment`, when set, validates the `env.<environment>` view
+ * ({@link mergeWranglerEnvironment}) instead of the top-level config — e.g. a
+ * `durable_objects` binding present only at the top level is a validation
+ * FAILURE for `--env production` if `env.production` doesn't repeat it,
+ * because `durable_objects` is non-inheritable and wrangler will not carry it
+ * over. Omit `environment` to validate the top level only (unchanged default).
+ */
+declare const validateWranglerConfig: (wranglerInput: WranglerConfig | undefined, schema?: SchemaInfo, environment?: string) => WranglerValidationReport;
+/**
+ * Convenience alias matching the original task-spec signature
+ * `validateWrangler(wranglerJson, schema)` returning
+ * `{ valid, errors, warnings }`.
+ */
+declare const validateWrangler: typeof validateWranglerConfig;
+interface WranglerProjectValidationOptions {
+  /**
+   * Cloudflare environment to validate against `env.<name>` in
+   * wrangler.jsonc. See {@link mergeWranglerEnvironment} for which keys
+   * inherit the top-level value vs must be redeclared per environment.
+   * Omit to validate the top-level config only (unchanged default).
+   */
+  environment?: string;
+  projectRoot: string;
+  schemaDir?: string;
+}
+interface WranglerProjectValidationResult {
+  problems: ReadonlyArray<string>;
+  report: WranglerValidationReport;
+  wranglerPath: string | undefined;
+}
+/**
+ * The phrase every unexported-class error carries.
+ *
+ * Exported because it is a CONTRACT, not prose: `lunora doctor` picks these
+ * errors out of the report by substring to raise its own finding, and the
+ * validator's report is a flat `string[]`. Until the report entries carry a
+ * code, a copy-edit here would silently disable that check — so the copy-edit
+ * has to go through this constant.
+ */
+declare const UNEXPORTED_CLASS_MARKER = "does not export it";
+/**
+ * File-system aware variant: reads `wrangler.jsonc`/`wrangler.json` from
+ * the given project root, discovers the schema (if any), and delegates to
+ * `validateWranglerConfig`. Returns the legacy
+ * `{ problems, wranglerPath }` shape plus the structured `report`.
+ */
+declare const validateWranglerProject: (options: WranglerProjectValidationOptions) => WranglerProjectValidationResult;
+export { type AlchemyTranslation, BINDING_MANIFEST_VERSION,
+/**
+ * `@lunora/config/cloudflare` — the wrangler layer.
+ *
+ * Everything here speaks `wrangler.jsonc`: validating it, reconciling inferred
+ * bindings/crons/compatibility-date into it, resolving remote bindings, and the
+ * `DeployDriver` that ties them together for `--target cloudflare`.
+ *
+ * Split out from the package root so `@lunora/config` itself stays
+ * provider-neutral. The root keeps what any target needs — the `DeployDriver`
+ * contract, the driver registry, project config and target resolution,
+ * `.dev.vars` grammar, binding *inference* — while emission and validation,
+ * which are wrangler-shaped by definition, live behind this subpath.
+ * Plan 114 §5.3 (D6): a package carrying real provider code isolates it behind a
+ * subpath rather than relocating wholesale.
+ */
+type BindingManifest,
+/**
+ * `@lunora/config/cloudflare` — the wrangler layer.
+ *
+ * Everything here speaks `wrangler.jsonc`: validating it, reconciling inferred
+ * bindings/crons/compatibility-date into it, resolving remote bindings, and the
+ * `DeployDriver` that ties them together for `--target cloudflare`.
+ *
+ * Split out from the package root so `@lunora/config` itself stays
+ * provider-neutral. The root keeps what any target needs — the `DeployDriver`
+ * contract, the driver registry, project config and target resolution,
+ * `.dev.vars` grammar, binding *inference* — while emission and validation,
+ * which are wrangler-shaped by definition, live behind this subpath.
+ * Plan 114 §5.3 (D6): a package carrying real provider code isolates it behind a
+ * subpath rather than relocating wholesale.
+ */
+type BindingRequirement, CLOUDFLARE_DRIVER, type ExportGap,
+/**
+ * `@lunora/config/cloudflare` — the wrangler layer.
+ *
+ * Everything here speaks `wrangler.jsonc`: validating it, reconciling inferred
+ * bindings/crons/compatibility-date into it, resolving remote bindings, and the
+ * `DeployDriver` that ties them together for `--target cloudflare`.
+ *
+ * Split out from the package root so `@lunora/config` itself stays
+ * provider-neutral. The root keeps what any target needs — the `DeployDriver`
+ * contract, the driver registry, project config and target resolution,
+ * `.dev.vars` grammar, binding *inference* — while emission and validation,
+ * which are wrangler-shaped by definition, live behind this subpath.
+ * Plan 114 §5.3 (D6): a package carrying real provider code isolates it behind a
+ * subpath rather than relocating wholesale.
+ */
+type ManifestConfigShape, type MaterializeOptions, type MaterializeResult, REMOTE_ELIGIBLE_KEYS, REQUIRED_COMPATIBILITY_DATE, REQUIRED_FLAG, type ReadWranglerResult, type ReconcileBindingsResult, type ReconcileCompatibilityDateResult, type ReconcileResult as ReconcileCronsResult, type RemoteBindingPlan, type RemoteEnableInputs, type RemoteWranglerShape, type TailConsumer, UNEXPORTED_CLASS_MARKER, WORKERS_CACHE_MIN_DATE, WRANGLER_FILES, type WranglerCacheShape, type WranglerConfig, type WranglerConfigShape, type WranglerContainerEntry, type WranglerEnvironmentMerge, type WranglerProjectValidationOptions, type WranglerProjectValidationResult, type WranglerValidationReport, type WranglerWorkflowEntry, buildBindingManifest, collectExportGaps, collectWranglerSecretVariables, describePreservedCrons, findWranglerFile, injectRemoteFlags, isCacheEnabled, isRemoteEnvEnabled, materializeRemoteWranglerConfig, mergeWranglerEnvironment, planRemoteBindings, readWranglerJsonc, reconcileWranglerBindings, reconcileWranglerCompatibilityDate, reconcileWranglerCrons, resolveRemoteEnabled, scanWranglerVariablesForSecrets, validateWrangler, validateWranglerConfig, validateWranglerProject, withTailConsumer, wranglerToAlchemy };