feat: add support for redirecting Wrangler to a generated config when…

… running deploy commands (#7442)

* Do not console log wrangler output during normal fixture tests

This creates a lot of unwanted logging in the console.

The logging is still dumped to the console if the test times out, or if `WRANGLER_LOG=debug` is set as env var.

* no need to get relative config path for calls to verifyWorkerMatchesCITag()

* feat: add support for redirecting Wrangler to a generated config when running deploy commands

This new feature is designed for build tools and frameworks to provide a deploy-specific configuration,
which Wrangler can use instead of user configuration when running deploy commands.
It is not expected that developers of Workers will need to use this feature directly.

The commands that use this feature are:

- `wrangler deploy`
- `wrangler dev`
- `wrangler versions upload`
- `wrangler versions deploy`

When running these commands, Wrangler will look up the directory tree from the current working directory for a file at the path `.wrangler/deploy/config.json`. This file must contain only a single JSON object of the form:

```json
{ "configPath": "../../path/to/wrangler.json" }
```

When this file exists Wrangler will use the `configPath` (relative to the `deploy.json` file) to find an alternative Wrangler configuration file to load and use as part of this command.

When this happens Wrangler will display a warning to the user to indicate that the configuration has been redirected to a different file than the user's configuration file.

A common approach that a build tool might choose to implement.

- The user writes code that uses Cloudflare Workers resources, configured via a user `wrangler.toml` file.

  ```toml
  name = "my-worker"
  main = "src/index.ts"
  [[kv_namespaces]]
  binding = "<BINDING_NAME1>"
  id = "<NAMESPACE_ID1>"
  ```

  Note that this configuration points `main` at user code entry-point.

- The user runs a custom build, which might read the `wrangler.toml` to find the entry-point:

  ```bash
  > my-tool build
  ```

- This tool generates a `dist` directory that contains both compiled code and a new deployment configuration file, but also a `.wrangler/deploy/config.json` file that redirects Wrangler to this new deployment configuration file:

  ```plain
  - dist
    - index.js
  	- wrangler.json
  - .wrangler
    - deploy
  	  - config.json
  ```

  The `dist/wrangler.json` will contain:

  ```json
  {
  	"name": "my-worker",
  	"main": "./index.js",
  	"kv_namespaces": [{ "binding": "<BINDING_NAME1>", "id": "<NAMESPACE_ID1>" }]
  }
  ```

  And the `.wrangler/deploy/config.json` will contain:

  ```json
  {
  	"configPath": "../../dist/wrangler.json"
  }
  ```

* add config redirect fixture with tests

* Add config redirect support for Pages commands

* refactor: compute both the actual config path and the original user's configuration

* add `userConfigPath` to the `Config` type so it can be used where needed

* add fixture and test for redirected config in a pages project

* Do not check formatting of generated fixture files

* clean node_modules for npm-import fixture before testing

* fix unstable_dev tests

* run more Wrangler e2e tests on safe ports

* Requires that you create a `.env` file in the `packages/wrangler` directory containing:

```
CLOUDFLARE_ACCOUNT_ID=<dev-prod-account-id>
CLOUDFLARE_API_TOKEN=<dev-prod-account-api-key>
WRANGLER="node <path to workers-sdk/packages/wrangler/bin/wrangler.js>"
WRANGLER_IMPORT="<path to /workers-sdk/packages/wrangler/wrangler-dist/cli.js>"
````

* correctly configure python workers when no command line script is provided

* test: ensure that `pages functions build-env` command outputs correct relative pages_build_output_dir path

* Improve error message when deploy/config.json is not valid

* Complete jsdoc description

* Update jsdocs to note that the result of `resolveWranglerConfigPath()` contains absolute paths.

* PR feedback

* rename `useRedirect` to `useRedirectIfAvailable`

* Rename command definition behaviour from "useConfigRedirect" to "useConfigRedirectIfAvailable"

* Add clarifying comment

* Do not store package-lock.json for import-npm fixture

This fixture does not need a package lockfile to work.

* Remove unnecessary option in test

.changeset/thin-pots-camp.md

@@ -0,0 +1,84 @@
+---
+"wrangler": minor
+---
+
+feat: add support for redirecting Wrangler to a generated config when running deploy-related commands
+
+This new feature is designed for build tools and frameworks to provide a deploy-specific configuration,
+which Wrangler can use instead of user configuration when running deploy-related commands.
+It is not expected that developers of Workers will need to use this feature directly.
+
+### Affected commands
+
+The commands that use this feature are:
+
+- `wrangler deploy`
+- `wrangler dev`
+- `wrangler versions upload`
+- `wrangler versions deploy`
+- `wrangler pages deploy`
+- `wrangler pages build`
+- `wrangler pages build-env`
+
+### Config redirect file
+
+When running these commands, Wrangler will look up the directory tree from the current working directory for a file at the path `.wrangler/deploy/config.json`. This file must contain only a single JSON object of the form:
+
+```json
+{ "configPath": "../../path/to/wrangler.json" }
+```
+
+When this file exists Wrangler will follow the `configPath` (relative to the `.wrangler/deploy/config.json` file) to find an alternative Wrangler configuration file to load and use as part of this command.
+
+When this happens Wrangler will display a warning to the user to indicate that the configuration has been redirected to a different file than the user's configuration file.
+
+### Custom build tool example
+
+A common approach that a build tool might choose to implement.
+
+- The user writes code that uses Cloudflare Workers resources, configured via a user `wrangler.toml` file.
+
+  ```toml
+  name = "my-worker"
+  main = "src/index.ts"
+  [[kv_namespaces]]
+  binding = "<BINDING_NAME1>"
+  id = "<NAMESPACE_ID1>"
+  ```
+
+  Note that this configuration points `main` at user code entry-point.
+
+- The user runs a custom build, which might read the `wrangler.toml` to find the entry-point:
+
+  ```bash
+  > my-tool build
+  ```
+
+- This tool generates a `dist` directory that contains both compiled code and a new deployment configuration file, but also a `.wrangler/deploy/config.json` file that redirects Wrangler to this new deployment configuration file:
+
+  ```plain
+  - dist
+    - index.js
+  	- wrangler.json
+  - .wrangler
+    - deploy
+  	  - config.json
+  ```
+
+  The `dist/wrangler.json` will contain:
+
+  ```json
+  {
+  	"name": "my-worker",
+  	"main": "./index.js",
+  	"kv_namespaces": [{ "binding": "<BINDING_NAME1>", "id": "<NAMESPACE_ID1>" }]
+  }
+  ```
+
+  And the `.wrangler/deploy/config.json` will contain:
+
+  ```json
+  {
+  	"configPath": "../../dist/wrangler.json"
+  }
+  ```

.prettierignore

@@ -40,3 +40,7 @@ templates/*/dist
 
 # This file intentionally has a syntax error
 fixtures/interactive-dev-tests/src/startup-error.ts
+
+# These are generated by the build step
+fixtures/pages-redirected-config/build/*
+fixtures/redirected-config-worker/build/*

fixtures/import-npm/package.json

@@ -7,9 +7,10 @@
 		"packages/*"
 	],
 	"scripts": {
-		"check:type": "rm -rf node_modules && npm install && npm run check:type --workspaces",
-		"test:ci": "npm install && npm run test:ci --workspaces",
-		"test:watch": "npm install && npm run test:watch --workspaces",
-		"type:tests": "rm -rf node_modules && npm install && npm run type:tests --workspaces"
+		"_clean_install": "rm -rf node_modules && npm install --no-package-lock",
+		"check:type": "npm run check:type --workspaces",
+		"test:ci": "npm run test:ci --workspaces",
+		"test:watch": "npm run test:watch --workspaces",
+		"type:tests": "npm run type:tests --workspaces"
 	}
 }

fixtures/import-npm/turbo.json

@@ -1,11 +1,18 @@
 {
 	"extends": ["//"],
 	"tasks": {
-		"test": {
-			"dependsOn": ["wrangler#build"]
+		"_clean_install": {},
+		"check:type": {
+			"dependsOn": ["_clean_install"]
+		},
+		"test:watch": {
+			"dependsOn": ["_clean_install"]
+		},
+		"type:tests": {
+			"dependsOn": ["_clean_install"]
 		},
 		"test:ci": {
-			"dependsOn": ["wrangler#build"]
+			"dependsOn": ["_clean_install", "wrangler#build"]
 		}
 	}
 }

fixtures/pages-redirected-config/.gitignore

@@ -0,0 +1,2 @@
+dist
+build

fixtures/pages-redirected-config/package.json

@@ -0,0 +1,23 @@
+{
+	"name": "pages-redirected-config",
+	"private": true,
+	"description": "",
+	"license": "ISC",
+	"author": "",
+	"main": "src/index.js",
+	"scripts": {
+		"build": "node -r esbuild-register tools/build.ts",
+		"check:type": "tsc",
+		"dev": "pnpm run build && wrangler pages dev",
+		"test:ci": "pnpm run build && vitest run"
+	},
+	"devDependencies": {
+		"@cloudflare/workers-tsconfig": "workspace:^",
+		"undici": "catalog:default",
+		"vitest": "catalog:default",
+		"wrangler": "workspace:*"
+	},
+	"volta": {
+		"extends": "../../package.json"
+	}
+}

fixtures/pages-redirected-config/src/index.js

@@ -0,0 +1,5 @@
+export default {
+	async fetch(request, env) {
+		return new Response("Generated: " + env.generated ?? false);
+	},
+};