@void/deploy-cloudflare 0.20.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present, Cloudflare, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# @void/deploy-cloudflare
+
+Public Cloudflare target adapter primitives for Void deployments.
+
+This package owns Wrangler JSON/JSONC config reads and the final verified
+Cloudflare upload boundary. Source inference and app builds remain in `void`;
+provider-neutral contracts and plans remain in `@void/deploy-core`.
+
+Existing Worker handoffs read the active version, validate resource identities,
+and check the uploaded bindings before activation. Traffic-only activation uses
+an isolated config to retain Worker settings and triggers. Trigger snapshots
+record when configuration was preserved, so rollback can keep those settings
+for versions originally deployed outside Void.
+
+Handoff verifiers can accept an explicit list of new KV binding identities.
+Only those exact namespaces may be added; existing bindings, variables, secrets,
+and handlers must remain unchanged. New bindings cannot alias an existing KV
+namespace. The Void CLI uses this for the migration's explicit ISR cache choice.
+
+First-deployment readiness allows up to one minute for the new Worker's public
+route to propagate, with bounded requests and backoff. A successful check still
+requires the ready response, and Cloudflare Access denials fail immediately.
+Subsequent version previews retain the shorter retry window.
+
+Failed version uploads and first-deployment bootstraps return a bounded diagnostic
+alongside the exit status and Cloudflare error code. It retains validation messages
+and stack locations, strips terminal formatting, excludes stdout binding tables,
+and redacts common credential formats before callers display or log it.

package/dist/index.d.mts

@@ -0,0 +1,322 @@
+import { AssetConfig, HeaderRule, RedirectRule } from "@void/deploy-core";
+//#region src/execute.d.ts
+type CloudflareCommandResult = {
+  stdout: string;
+  stderr: string;
+  status: number;
+  signal?: NodeJS.Signals | null;
+  error?: string | null;
+};
+type CloudflareCommandRunner = (args: Array<string>, options: {
+  capture: boolean;
+}) => CloudflareCommandResult | Promise<CloudflareCommandResult>;
+type CloudflareDeployExecution = {
+  ok: true;
+} | {
+  ok: false;
+  reason: "uploader-changed";
+} | {
+  ok: false;
+  reason: "deploy-failed";
+  status: number;
+};
+/** Upload the already-verified Worker artifact without Wrangler autoconfiguration. */
+export declare function executeCloudflareDeploy(options: {
+  runWrangler: CloudflareCommandRunner;
+  verifyUploader: () => boolean;
+  configPath?: string;
+}): Promise<CloudflareDeployExecution>;
+//#endregion
+//#region src/existing.d.ts
+type ExistingCloudflareWorker = {
+  versionId: string;
+  bindings: Array<Record<string, unknown>>;
+  runtime: Record<string, unknown>;
+  script: Record<string, unknown>;
+};
+/** Exact identities of new KV bindings explicitly approved before the build. */
+type ApprovedCloudflareKvBinding = Readonly<{
+  binding: string;
+  id: string;
+}>;
+type CloudflareWorkerMigrationTagOptions = {
+  runWrangler: CloudflareCommandRunner;
+  accountId: string;
+  apiBaseUrl: string;
+  workerName: string;
+};
+/** Read the deployed version, not the most recently uploaded candidate. */
+export declare function readExistingCloudflareWorker(options: {
+  runWrangler: CloudflareCommandRunner;
+  configPath: string;
+  workerName: string;
+  versionId?: string;
+}): Promise<ExistingCloudflareWorker>;
+/** Parse legacy version-detail shapes; this is not authoritative Worker migration state. */
+export declare function readCloudflareVersionMigrationTag(version: unknown): string | null;
+/** Read the authoritative migration tag from Worker script metadata. */
+export declare function readCloudflareWorkerMigrationTag(options: CloudflareWorkerMigrationTagOptions): Promise<string | null>;
+/**
+ * The Versions upload endpoint cannot safely apply a new Durable Object class migration to an
+ * existing Worker in the native beta. Reject that pending lifecycle change before the caller
+ * mutates a database or Worker secret; ordinary uploads whose migration tag is already active
+ * continue normally.
+ */
+export declare function assertCloudflareDurableObjectLifecycleSupported(options: {
+  runWrangler: CloudflareCommandRunner;
+  configPath: string;
+  workerName: string;
+  accountId: string;
+  apiBaseUrl: string;
+  readMigrationTag?: (options: CloudflareWorkerMigrationTagOptions) => Promise<string | null>;
+}): Promise<void>;
+export declare function assertCloudflareBindingsPreserved(before: ExistingCloudflareWorker, after: ExistingCloudflareWorker, approvedKv?: ReadonlyArray<ApprovedCloudflareKvBinding>): void;
+/** Preserve the existing Worker, allowing only explicitly approved KV additions. */
+export declare function assertExistingCloudflareConfig(existing: ExistingCloudflareWorker, config: Record<string, unknown>, built?: boolean, approvedKv?: ReadonlyArray<ApprovedCloudflareKvBinding>): void;
+//#endregion
+//#region src/config.d.ts
+/** Parse a root Wrangler JSON/JSONC config without accepting a partial parse. */
+export declare function parseRootWranglerConfig(configPath: string): Record<string, unknown>;
+export declare function readWranglerTopLevelString(config: Record<string, unknown>, field: string): string | undefined;
+export declare function readStoredResourceName(config: Record<string, unknown>, field: string, binding: string, nameField: string): string | undefined;
+export declare function readBindingFieldPresence(config: Record<string, unknown>, field: string, binding: string, key: string): {
+  present: boolean;
+  value: unknown;
+};
+export declare function readConfigEntryString(entry: unknown, field: string): string | undefined;
+export declare function resolveD1MigrateTarget(config: Record<string, unknown>, binding: string): {
+  ok: true;
+  token: string;
+} | {
+  ok: false;
+  reason: string;
+};
+//#endregion
+//#region src/framework.d.ts
+type CloudflareFrameworkDeployConfig = Readonly<{
+  configPath: string;
+  deployPointerPath: string;
+  name: string;
+  accountId: string;
+  main: string;
+  assetsDirectory: string;
+  compatibilityDate: string;
+  compatibilityFlags?: ReadonlyArray<string>;
+  assetsIgnore?: ReadonlyArray<string>;
+  crons?: ReadonlyArray<string>;
+  requiredSecrets?: ReadonlyArray<string>;
+}>;
+/**
+ * Point a standalone framework Worker at the canonical root Cloudflare state.
+ *
+ * Resource ids and deployment history remain in the user's root wrangler
+ * config. The generated deploy pointer contains only a relative path back to
+ * that file, so Wrangler uploads the exact config Void verifies.
+ */
+export declare function writeCloudflareFrameworkDeployConfig(options: CloudflareFrameworkDeployConfig): boolean;
+//#endregion
+//#region src/static.d.ts
+type CloudflareStaticDeployConfig = Readonly<{
+  configPath: string;
+  name: string;
+  accountId: string;
+  main: string;
+  assetsDirectory: string;
+  compatibilityDate: string;
+  assetConfig: AssetConfig;
+}>;
+/** Generate the deterministic thin Worker entry bundled by Wrangler. */
+export declare function renderCloudflareStaticEntry(options: {
+  runtimeImport?: string;
+  headerRules?: ReadonlyArray<HeaderRule>;
+  redirectRules?: ReadonlyArray<RedirectRule>;
+  fallbackRules?: ReadonlyArray<RedirectRule>;
+}): string;
+/**
+ * Copy static assets into Void's deploy area without Cloudflare's reserved routing files.
+ *
+ * Void has already compiled the root `_headers` and `_redirects` files into the thin edge
+ * Worker. Wrangler parses those files independently of `.assetsignore`, so uploading the source
+ * directory would apply every rule twice and can reject valid Void fallbacks as redirect loops.
+ */
+export declare function stageCloudflareStaticAssets(options: {
+  sourceDirectory: string;
+  destinationDirectory: string;
+}): void;
+/**
+ * Persist the mutable Cloudflare target state without replacing comments,
+ * Durable Object migrations, resource ids, or unrelated user configuration.
+ */
+export declare function writeCloudflareStaticDeployConfig(options: CloudflareStaticDeployConfig): boolean;
+//#endregion
+//#region src/version.d.ts
+type CloudflareVersionMetadata = Readonly<{
+  schema: 1;
+  migrations: ReadonlyArray<string>;
+}> | Readonly<{
+  schema: 2;
+  migrations: ReadonlyArray<string>;
+  triggerConfig: CloudflareTriggerConfig;
+}>;
+type CloudflareTriggerConfig = Readonly<{
+  /** This version retained the existing triggers instead of publishing a snapshot. */
+  preserve?: boolean;
+  preserveRoutes?: boolean;
+  preserveWorkersDev?: boolean;
+  preservePreviewUrls?: boolean;
+  /** Fingerprint of explicit non-versioned settings while remote triggers stay opaque. */
+  settingsHash?: string;
+  workers_dev: boolean;
+  preview_urls: boolean;
+  routes: ReadonlyArray<unknown>;
+  crons: ReadonlyArray<unknown>;
+  queueConsumers: ReadonlyArray<unknown>;
+  workflows: ReadonlyArray<unknown>;
+  /**
+   * Email Routing addresses (`addresses` in Wrangler config). Wrangler 4.131 applies its
+   * Email Routing plan inside `triggers deploy` — `undefined` skips the plan entirely, while
+   * `[]` is a destructive plan that deletes every rule this Worker owns — so the two must stay
+   * distinct through the snapshot. Absent from annotations written before this field existed.
+   */
+  addresses?: ReadonlyArray<string>;
+}>;
+type CloudflareTrafficConfig = Pick<CloudflareTriggerConfig, "workers_dev" | "preview_urls" | "routes">;
+type CloudflareVersionActivation = {
+  ok: true;
+  versionId: string;
+  previewUrl: string;
+  previousVersionId: string | null;
+  workersDevSubdomain?: string;
+  preservedTriggers?: boolean;
+  trafficConfig?: CloudflareTrafficConfig;
+} | {
+  ok: false;
+  reason: "uploader-changed" | "status-failed" | "deployment-changed" | "inheritance-source-unavailable" | "inheritance-source-changed" | "traffic-preservation-unavailable" | "traffic-split-unsupported" | "upload-failed" | "upload-output-invalid" | "preview-unavailable" | "readiness-staging-failed" | "readiness-failed" | "readiness-access-denied" | "bootstrap-failed" | "bootstrap-output-invalid" | "bootstrap-readiness-failed" | "bootstrap-readiness-access-denied" | "activation-failed" | "triggers-failed";
+  status?: number;
+  cloudflareErrorCode?: number;
+  /** Bounded uploader error text with terminal escapes removed and common credential formats redacted. */
+  diagnostic?: string;
+  /** Wrangler reached Cloudflare's Containers entitlement endpoint and received a 403. */
+  containersUnavailable?: boolean;
+  versionId?: string;
+  previousVersionId?: string | null;
+  rollback?: "not-needed" | "succeeded" | "failed" | "unavailable" | "unsafe";
+  /** Version that owned production after a concurrent operation superseded this command. */
+  activeVersionId?: string | null;
+  /** Whether Void restored the active version's immutable trigger snapshot. */
+  triggerRepair?: "succeeded" | "failed" | "unavailable";
+};
+/** Encode migration state into Cloudflare's version annotation for safe rollback diagnostics. */
+export declare function encodeCloudflareVersionMessage(migrations: ReadonlyArray<string>, triggerConfig?: CloudflareTriggerConfig): string;
+/** Read migration state written by {@link encodeCloudflareVersionMessage}. */
+export declare function parseCloudflareVersionMessage(message: string | null | undefined): CloudflareVersionMetadata | null;
+/**
+ * Capture every configuration surface mutated by `wrangler triggers deploy` — routes,
+ * workers.dev / preview flags, crons, queue consumers, workflows, and Email Routing addresses.
+ */
+export declare function readCloudflareTriggerConfig(configPath: string, sourceConfigPath?: string): CloudflareTriggerConfig;
+/** Apply a version's persisted trigger state using an isolated temporary Wrangler config. */
+export declare function deployCloudflareVersionTriggers(options: {
+  runWrangler: CloudflareCommandRunner;
+  workerName: string;
+  configPath?: string;
+  triggerConfig: CloudflareTriggerConfig;
+  /** Exact trigger state active before this transition, used to remove stale state. */
+  previousTriggerConfig?: CloudflareTriggerConfig;
+  /** Wrangler skips an empty Custom Domain set, so the caller may publish it directly. */
+  publishEmptyCustomDomains?: () => Promise<CloudflareCommandResult>;
+  manageRoutes?: boolean;
+}): Promise<CloudflareCommandResult>;
+type CloudflareTriggerStabilization = Readonly<{
+  ok: true;
+  activeVersionId: string;
+  targetOwnsTraffic: boolean;
+}> | Readonly<{
+  ok: false;
+  reason: "status-failed" | "traffic-split" | "metadata-unavailable" | "triggers-failed";
+  status?: number;
+  activeVersionId?: string | null;
+}>;
+/**
+ * Reconcile triggers to the version that actually owns production traffic.
+ *
+ * Worker Version activation and `wrangler triggers deploy` are separate Cloudflare operations.
+ * Another deploy or rollback can therefore take ownership between them. Re-read ownership before
+ * and after every trigger publication and, when it changes, repair the new owner's immutable
+ * schema-2 snapshot. The bounded loop fails closed if traffic never stabilizes.
+ */
+export declare function stabilizeCloudflareVersionTriggers(options: {
+  runWrangler: CloudflareCommandRunner;
+  workerName: string;
+  configPath?: string;
+  targetVersionId: string;
+  targetTriggerConfig: CloudflareTriggerConfig;
+  previousTriggerConfig?: CloudflareTriggerConfig;
+  knownTriggerConfigs?: Readonly<Record<string, CloudflareTriggerConfig>>;
+  publishEmptyCustomDomains?: () => Promise<CloudflareCommandResult>;
+  manageRoutes?: boolean;
+  attempts?: number;
+}): Promise<CloudflareTriggerStabilization>;
+type CloudflareVersionActivationOptions = {
+  /** Reuse an inspected Worker without republishing its domains or other triggers. */
+  preserveTriggers?: boolean;
+  expectedPreviousVersionId?: string;
+  trustedInheritanceVersionIds?: ReadonlyArray<string>;
+  recordVerifiedCandidate?: (versionId: string) => void | Promise<void>;
+  validateUploadedVersion?: (versionId: string) => Promise<void>;
+  runWrangler: CloudflareCommandRunner;
+  verifyUploader: () => boolean;
+  workerName: string;
+  configPath?: string;
+  /** Override only the asset directory for this upload, leaving the persisted config intact. */
+  assetsDirectoryOverride?: string;
+  /** Optional Cloudflare Access headers used only by the readiness probe. */
+  readinessHeaders?: Readonly<Record<string, string>>;
+  /** Account workers.dev subdomain used when this Worker cannot expose version preview URLs. */
+  workersDevSubdomain?: string;
+  /**
+   * Operator-provided workers.dev subdomain that may receive readiness credentials even when
+   * Wrangler cannot report a preview URL. Cached/project-controlled values must not be used here.
+   */
+  readinessHeadersWorkersDevSubdomain?: string;
+  message: string;
+  /** Direct empty-domain publisher for the Wrangler reconciliation gap. */
+  publishEmptyCustomDomains?: () => Promise<CloudflareCommandResult>;
+  /** Last successfully published traffic state, newer than immutable version annotations. */
+  previousTrafficConfig?: CloudflareTrafficConfig;
+  /** Explicitly Void-owned queue consumers retained for schema-1 cleanup and failed retries. */
+  queueConsumerCleanup?: ReadonlyArray<string>;
+  /**
+   * The caller proved that the Worker did not exist before this deploy provisioned its secrets.
+   * Wrangler creates an active placeholder version when attaching the first secret, so the status
+   * read below can legitimately observe a version even though no application was ever deployed.
+   */
+  allowFirstDeploymentBootstrap?: boolean;
+  fetch?: typeof globalThis.fetch;
+  sleep?: (milliseconds: number) => Promise<void>;
+  readinessAttempts?: number;
+  /** Verify that omitted remote secrets come from the active Worker Version before uploading. */
+  verifyInheritedSecrets?: boolean;
+  /**
+   * Plaintext secrets to attach only to the uploaded candidate version. Supplying every remote
+   * `secret_text` binding lets a deployment recover safely when an inactive upload is newer than
+   * production; `secret_key` bindings cannot be replaced through this option.
+   */
+  candidateSecrets?: Readonly<Record<string, string>>;
+};
+/** Upload, probe, and atomically activate a verified Worker Version. */
+export declare function activateCloudflareVersion(options: CloudflareVersionActivationOptions): Promise<CloudflareVersionActivation>;
+/** Change version traffic without synchronizing Worker settings from local config. */
+export declare function deployCloudflareVersionTraffic(options: {
+  runWrangler: CloudflareCommandRunner;
+  configPath: string;
+  workerName: string;
+  percentages: Array<string>;
+  message: string;
+}): Promise<CloudflareCommandResult>;
+/** Normalize an account workers.dev subdomain supplied by config or the environment. */
+export declare function normalizeWorkersDevSubdomain(value: string | undefined): string | undefined;
+/** Extract the account subdomain from a Wrangler-reported workers.dev URL. */
+export declare function extractWorkersDevSubdomain(url: string): string | undefined;
+//#endregion
+export type { ApprovedCloudflareKvBinding, CloudflareCommandResult, CloudflareCommandRunner, CloudflareDeployExecution, CloudflareFrameworkDeployConfig, CloudflareStaticDeployConfig, CloudflareTrafficConfig, CloudflareTriggerConfig, CloudflareTriggerStabilization, CloudflareVersionActivation, CloudflareVersionActivationOptions, CloudflareVersionMetadata, CloudflareWorkerMigrationTagOptions, ExistingCloudflareWorker };