wrangler 4.28.0 → 4.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wrangler",
-  "version": "4.28.0",
+  "version": "4.29.0",
   "description": "Command-line interface for all things Cloudflare Workers",
   "keywords": [
     "wrangler",
@@ -55,9 +55,9 @@
     "path-to-regexp": "6.3.0",
     "unenv": "2.0.0-rc.19",
     "workerd": "1.20250803.0",
-    "miniflare": "4.20250803.0",
-    "@cloudflare/unenv-preset": "2.6.0",
-    "@cloudflare/kv-asset-handler": "0.4.0"
+    "@cloudflare/kv-asset-handler": "0.4.0",
+    "@cloudflare/unenv-preset": "2.6.1",
+    "miniflare": "4.20250803.1"
   },
   "devDependencies": {
     "@aws-sdk/client-s3": "^3.721.0",
@@ -137,9 +137,9 @@
     "xxhash-wasm": "^1.0.1",
     "yargs": "^17.7.2",
     "@cloudflare/cli": "1.1.1",
-    "@cloudflare/containers-shared": "0.2.8",
+    "@cloudflare/containers-shared": "0.2.9",
     "@cloudflare/eslint-config-worker": "1.1.0",
-    "@cloudflare/pages-shared": "^0.13.60",
+    "@cloudflare/pages-shared": "^0.13.61",
     "@cloudflare/workers-shared": "0.18.5",
     "@cloudflare/workers-tsconfig": "0.0.0"
   },

package/wrangler-dist/cli.d.ts

@@ -1,12 +1,14 @@
 import { Json, Request, Response as Response$1, DispatchFetch, NodeJSCompatMode, Miniflare, MiniflareOptions, Mutex, WorkerOptions, ModuleRule, RemoteProxyConnectionString } from 'miniflare';
 import * as undici from 'undici';
 import { RequestInfo, RequestInit, Response, FormData } from 'undici';
+import { CamelCaseKey, ArgumentsCamelCase, InferredOptionTypes, Alias, PositionalOptions, Options } from 'yargs';
 import { RouterConfig, AssetConfig } from '@cloudflare/workers-shared';
 import { EventEmitter } from 'node:events';
 import Protocol from 'devtools-protocol/types/protocol-mapping';
 import { Metafile } from 'esbuild';
 import { ContainerNormalizedConfig } from '@cloudflare/containers-shared';
 import { IncomingRequestCfProperties } from '@cloudflare/workers-types/experimental';
+import { URLSearchParams } from 'node:url';
 
 /**
  * The `Environment` interface declares all the configuration fields that
@@ -1284,6 +1286,25 @@ interface EnvironmentMap {
         [envName: string]: RawEnvironment;
     };
 }
+type OnlyCamelCase<T = Record<string, never>> = {
+    [key in keyof T as CamelCaseKey<key>]: T[key];
+};
+
+/**
+ * Yargs options included in every wrangler command.
+ */
+interface CommonYargsOptions {
+    v: boolean | undefined;
+    cwd: string | undefined;
+    config: string | undefined;
+    env: string | undefined;
+    "env-file": string[] | undefined;
+    "experimental-provision": boolean | undefined;
+    "experimental-remote-bindings": boolean | undefined;
+}
+type RemoveIndex<T> = {
+    [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K];
+};
 
 type ResolveConfigPathOptions = {
     useRedirectIfAvailable?: boolean;
@@ -1395,6 +1416,15 @@ type CfSendEmailBindings = {
 } | {
     allowed_destination_addresses?: string[];
 });
+/**
+ * A binding to the AI project
+ */
+interface CfAIBinding {
+    binding: string;
+    staging?: boolean;
+    experimental_remote?: boolean;
+    raw?: boolean;
+}
 /**
  * A Durable Object.
  */
@@ -1768,6 +1798,11 @@ declare const unstable_pages: {
     deploy: typeof deploy;
 };
 
+/**
+ * The compliance region to use for the API requests.
+ */
+type ComplianceConfig = Partial<Pick<Config, "compliance_region">>;
+
 type WorkerRegistry = Record<string, WorkerDefinition>;
 type WorkerEntrypointsDefinition = Record<"default" | string, {
     host: string;
@@ -1795,6 +1830,29 @@ type DevToolsEvent<Method extends _EventMethods> = Method extends unknown ? {
     params: _Params<Protocol.Events[Method]>;
 } : never;
 
+/**
+ * This is used to provide telemetry with a sanitised error
+ * message that could not have any user-identifying information.
+ * Set to `true` to duplicate `message`.
+ *  */
+type TelemetryMessage = {
+    telemetryMessage?: string | true;
+};
+/**
+ * Base class for errors where the user has done something wrong. These are not
+ * reported to Sentry. API errors are intentionally *not* `UserError`s, and are
+ * reported to Sentry. This will help us understand which API errors need better
+ * messaging.
+ */
+declare class UserError extends Error {
+    telemetryMessage: string | undefined;
+    constructor(message?: string | undefined, options?: (ErrorOptions & TelemetryMessage) | undefined);
+}
+declare class FatalError extends UserError {
+    readonly code?: number | undefined;
+    constructor(message?: string, code?: number | undefined, options?: TelemetryMessage);
+}
+
 type AssetsOptions = {
     directory: string;
     binding?: string;
@@ -2109,9 +2167,9 @@ type Binding = {
     source: File;
 } | {
     type: "browser";
-} | {
+} | ({
     type: "ai";
-} | {
+} & BindingOmit<CfAIBinding>) | {
     type: "images";
 } | {
     type: "version_metadata";
@@ -2545,6 +2603,7 @@ declare function unstable_getMiniflareWorkerOptions(configPath: string, env?: st
     remoteBindingsEnabled?: boolean;
     overrides?: {
         assets?: Partial<AssetsOptions>;
+        enableContainers?: boolean;
     };
     containerBuildId?: string;
 }): Unstable_MiniflareWorkerOptions;
@@ -2554,6 +2613,7 @@ declare function unstable_getMiniflareWorkerOptions(config: Config, env?: string
     remoteBindingsEnabled?: boolean;
     overrides?: {
         assets?: Partial<AssetsOptions>;
+        enableContainers?: boolean;
     };
     containerBuildId?: string;
 }): Unstable_MiniflareWorkerOptions;
@@ -2570,28 +2630,39 @@ type StartRemoteProxySessionOptions = {
 };
 declare function startRemoteProxySession(bindings: StartDevWorkerInput["bindings"], options?: StartRemoteProxySessionOptions): Promise<RemoteProxySession>;
 declare function pickRemoteBindings(bindings: Record<string, Binding>): Record<string, Binding>;
+type WranglerConfigObject = {
+    /** The path to the wrangler config file */
+    path: string;
+    /** The target environment */
+    environment?: string;
+};
+type WorkerConfigObject = {
+    /** The name of the worker */
+    name?: string;
+    /** The Worker's bindings */
+    bindings: NonNullable<StartDevWorkerInput["bindings"]>;
+    /** If running in a non-public compliance region, set this here. */
+    complianceRegion?: Config["compliance_region"];
+};
 /**
  * Utility for potentially starting or updating a remote proxy session.
  *
  * It uses an internal map for storing existing remote proxy session indexed by worker names. If no worker name is provided
  * the remote proxy session won't be retrieved nor saved to/from the internal map.
  *
- * @param configPathOrWorkerConfig either a file path to a wrangler configuration file or an object containing the name of
+ * @param wranglerOrWorkerConfigObject either a file path to a wrangler configuration file or an object containing the name of
  *                                 the target worker alongside its bindings.
  * @param preExistingRemoteProxySessionData the optional data of a pre-existing remote proxy session if there was one, this
  *                                          argument can be omitted or set to null if there is no pre-existing remote proxy session
+ * @param auth the authentication information for establishing the remote proxy connection
  * @returns null if no existing remote proxy session was provided and one should not be created (because the worker is not
  *          defining any remote bindings), the data associated to the created/updated remote proxy session otherwise.
  */
-declare function maybeStartOrUpdateRemoteProxySession(configPathOrWorkerConfig: string | {
-    name?: string;
-    /** If running in a non-public compliance region, set this here. */
-    complianceRegion?: Config["compliance_region"];
-    bindings: NonNullable<StartDevWorkerInput["bindings"]>;
-}, preExistingRemoteProxySessionData?: {
+declare function maybeStartOrUpdateRemoteProxySession(wranglerOrWorkerConfigObject: WranglerConfigObject | WorkerConfigObject, preExistingRemoteProxySessionData?: {
     session: RemoteProxySession;
     remoteBindings: Record<string, Binding>;
-} | null): Promise<{
+    auth?: CfAccount | undefined;
+} | null, auth?: CfAccount | undefined): Promise<{
     session: RemoteProxySession;
     remoteBindings: Record<string, Binding>;
 } | null>;
@@ -2654,6 +2725,191 @@ declare const experimental_patchConfig: (configPath: string,
  */
 patch: RawConfig, isArrayInsertion?: boolean) => string;
 
+/**
+ * Make a fetch request, and extract the `result` from the JSON response.
+ */
+declare function fetchResult<ResponseType>(complianceConfig: ComplianceConfig, resource: string, init?: RequestInit, queryParams?: URLSearchParams, abortSignal?: AbortSignal, apiToken?: ApiCredentials): Promise<ResponseType>;
+
+type ExperimentalFlags = {
+    MULTIWORKER: boolean;
+    RESOURCES_PROVISION: boolean;
+    REMOTE_BINDINGS: boolean;
+};
+
+// Team names from https://wiki.cfdata.org/display/EW/Developer+Platform+Components+and+Pillar+Ownership
+type Teams =
+	| "Workers: Onboarding & Integrations"
+	| "Workers: Builds and Automation"
+	| "Workers: Deploy and Config"
+	| "Workers: Authoring and Testing"
+	| "Workers: Frameworks and Runtime APIs"
+	| "Workers: Runtime Platform"
+	| "Workers: Workers Observability"
+	| "Product: KV"
+	| "Product: R2"
+	| "Product: R2 Data Catalog"
+	| "Product: D1"
+	| "Product: Queues"
+	| "Product: AI"
+	| "Product: Hyperdrive"
+	| "Product: Pipelines"
+	| "Product: Vectorize"
+	| "Product: Workflows"
+	| "Product: Cloudchamber"
+	| "Product: SSL";
+
+type StringKeyOf<T> = Extract<keyof T, string>;
+type DeepFlatten<T> = T extends object ? {
+    [K in keyof T]: DeepFlatten<T[K]>;
+} : T;
+type Command = `wrangler${string}`;
+type Metadata = {
+    description: string;
+    status: "experimental" | "alpha" | "private-beta" | "open-beta" | "stable";
+    statusMessage?: string;
+    deprecated?: boolean;
+    deprecatedMessage?: string;
+    hidden?: boolean;
+    owner: Teams;
+    /** Prints something at the bottom of the help */
+    epilogue?: string;
+    examples?: {
+        command: string;
+        description: string;
+    }[];
+    hideGlobalFlags?: string[];
+};
+type ArgDefinition = Omit<PositionalOptions, "type"> & Pick<Options, "hidden" | "requiresArg" | "deprecated" | "type">;
+type NamedArgDefinitions = {
+    [key: string]: ArgDefinition;
+};
+type HandlerArgs<Args extends NamedArgDefinitions> = DeepFlatten<OnlyCamelCase<RemoveIndex<ArgumentsCamelCase<CommonYargsOptions & InferredOptionTypes<Args> & Alias<Args>>>>>;
+type HandlerContext = {
+    /**
+     * The wrangler config file read from disk and parsed.
+     */
+    config: Config;
+    /**
+     * The logger instance provided to the command implementor as a convenience.
+     */
+    logger: Logger;
+    /**
+     * Use fetchResult to make *auth'd* requests to the Cloudflare API.
+     */
+    fetchResult: typeof fetchResult;
+    /**
+     * Error classes provided to the command implementor as a convenience
+     * to aid discoverability and to encourage their usage.
+     */
+    errors: {
+        UserError: typeof UserError;
+        FatalError: typeof FatalError;
+    };
+};
+type CommandDefinition<NamedArgDefs extends NamedArgDefinitions = NamedArgDefinitions> = {
+    /**
+     * Descriptive information about the command which does not affect behaviour.
+     * This is used for the CLI --help and subcommand --help output.
+     * This should be used as the source-of-truth for status and ownership.
+     */
+    metadata: Metadata;
+    /**
+     * Controls shared behaviour across all commands.
+     * This will allow wrangler commands to remain consistent and only diverge intentionally.
+     */
+    behaviour?: {
+        /**
+         * By default, wrangler's version banner will be printed before the handler is executed.
+         * Set this value to `false` to skip printing the banner.
+         *
+         * @default true
+         */
+        printBanner?: boolean | ((args: HandlerArgs<NamedArgDefs>) => boolean);
+        /**
+         * By default, wrangler will print warnings about the Wrangler configuration file.
+         * Set this value to `false` to skip printing these warnings.
+         */
+        printConfigWarnings?: boolean;
+        /**
+         * By default, wrangler will read & provide the wrangler.toml/wrangler.json configuration.
+         * Set this value to `false` to skip this.
+         */
+        provideConfig?: boolean;
+        /**
+         * By default, wrangler will provide experimental flags in the handler context,
+         * according to the default values in register-yargs.command.ts
+         * Use this to override those defaults per command.
+         */
+        overrideExperimentalFlags?: (args: HandlerArgs<NamedArgDefs>) => ExperimentalFlags;
+        /**
+         * If true, then look for a redirect file at `.wrangler/deploy/config.json` and use that to find the Wrangler configuration file.
+         */
+        useConfigRedirectIfAvailable?: boolean;
+        /**
+         * If true, print a message about whether the command is operating on a local or remote resource
+         */
+        printResourceLocation?: ((args?: HandlerArgs<NamedArgDefs>) => boolean) | boolean;
+        /**
+         * If true, check for environments in the wrangler config, if there are some and the user hasn't specified an environment
+         * using the `-e|--env` cli flag, show a warning suggesting that one should instead be specified.
+         */
+        warnIfMultipleEnvsConfiguredButNoneSpecified?: boolean;
+    };
+    /**
+     * A plain key-value object describing the CLI args for this command.
+     * Shared args can be defined as another plain object and spread into this.
+     */
+    args?: NamedArgDefs;
+    /**
+     * Optionally declare some of the named args as positional args.
+     * The order of this array is the order they are expected in the command.
+     * Use args[key].demandOption and args[key].array to declare required and variadic
+     * positional args, respectively.
+     */
+    positionalArgs?: Array<StringKeyOf<NamedArgDefs>>;
+    /**
+     * A hook to implement custom validation of the args before the handler is called.
+     * Throw `CommandLineArgsError` with actionable error message if args are invalid.
+     * The return value is ignored.
+     */
+    validateArgs?: (args: HandlerArgs<NamedArgDefs>) => void | Promise<void>;
+    /**
+     * The implementation of the command which is given camelCase'd args
+     * and a ctx object of convenience properties
+     */
+    handler: (args: HandlerArgs<NamedArgDefs>, ctx: HandlerContext) => void | Promise<void>;
+};
+type NamespaceDefinition = {
+    metadata: Metadata;
+};
+type AliasDefinition = {
+    aliasOf: Command;
+    metadata?: Partial<Metadata>;
+};
+type InternalDefinition = ({
+    type: "command";
+    command: Command;
+} & CommandDefinition) | ({
+    type: "namespace";
+    command: Command;
+} & NamespaceDefinition) | ({
+    type: "alias";
+    command: Command;
+} & AliasDefinition);
+type DefinitionTreeNode = {
+    definition?: InternalDefinition;
+    subtree: DefinitionTree;
+};
+type DefinitionTree = Map<string, DefinitionTreeNode>;
+
+/**
+ * EXPERIMENTAL: Get all registered Wrangler commands for documentation generation.
+ * This API is experimental and may change without notice.
+ *
+ * @returns The complete command tree structure with all metadata
+ */
+declare function experimental_getWranglerCommands(): DefinitionTreeNode;
+
 interface Unstable_ASSETSBindingsOptions {
     log: Logger;
     proxyPort?: number;
@@ -2661,4 +2917,4 @@ interface Unstable_ASSETSBindingsOptions {
 }
 declare const generateASSETSBinding: (opts: Unstable_ASSETSBindingsOptions) => (request: Request) => Promise<Response$1>;
 
-export { type ConfigBindingOptions as Experimental_ConfigBindingOptions, type RemoteProxySession as Experimental_RemoteProxySession, type GetPlatformProxyOptions, type PlatformProxy, type SourcelessWorkerOptions, type Unstable_ASSETSBindingsOptions, type Binding as Unstable_Binding, type Config as Unstable_Config, type Unstable_DevOptions, type Unstable_DevWorker, type Unstable_MiniflareWorkerOptions, type RawConfig as Unstable_RawConfig, type RawEnvironment as Unstable_RawEnvironment, type StartRemoteProxySessionOptions as experimental_StartRemoteProxySessionOptions, maybeStartOrUpdateRemoteProxySession as experimental_maybeStartOrUpdateRemoteProxySession, experimental_patchConfig, pickRemoteBindings as experimental_pickRemoteBindings, experimental_readRawConfig, startRemoteProxySession as experimental_startRemoteProxySession, getPlatformProxy, DevEnv as unstable_DevEnv, convertConfigBindingsToStartWorkerBindings as unstable_convertConfigBindingsToStartWorkerBindings, unstable_dev, generateASSETSBinding as unstable_generateASSETSBinding, unstable_getMiniflareWorkerOptions, getVarsForDev as unstable_getVarsForDev, unstable_pages, readConfig as unstable_readConfig, splitSqlQuery as unstable_splitSqlQuery, startWorker as unstable_startWorker };
+export { type ConfigBindingOptions as Experimental_ConfigBindingOptions, type RemoteProxySession as Experimental_RemoteProxySession, type GetPlatformProxyOptions, type PlatformProxy, type SourcelessWorkerOptions, type Unstable_ASSETSBindingsOptions, type Binding as Unstable_Binding, type Config as Unstable_Config, type Unstable_DevOptions, type Unstable_DevWorker, type Unstable_MiniflareWorkerOptions, type RawConfig as Unstable_RawConfig, type RawEnvironment as Unstable_RawEnvironment, type StartRemoteProxySessionOptions as experimental_StartRemoteProxySessionOptions, experimental_getWranglerCommands, maybeStartOrUpdateRemoteProxySession as experimental_maybeStartOrUpdateRemoteProxySession, experimental_patchConfig, pickRemoteBindings as experimental_pickRemoteBindings, experimental_readRawConfig, startRemoteProxySession as experimental_startRemoteProxySession, getPlatformProxy, DevEnv as unstable_DevEnv, convertConfigBindingsToStartWorkerBindings as unstable_convertConfigBindingsToStartWorkerBindings, unstable_dev, generateASSETSBinding as unstable_generateASSETSBinding, unstable_getMiniflareWorkerOptions, getVarsForDev as unstable_getVarsForDev, unstable_pages, readConfig as unstable_readConfig, splitSqlQuery as unstable_splitSqlQuery, startWorker as unstable_startWorker };