mfeflow 0.5.0 → 0.7.0

package/README.md

@@ -26,7 +26,7 @@ pnpm dev                                    # shell on :4300, remotes on :4311,
 | `mfeflow registry build <dir>`        | Check a folder of features and write `index.json` and the files to host               |
 | `mfeflow dev`                         | Run the shell and every remote, one prefixed log each; follows `add remote`           |
 | `mfeflow doctor`                      | Singletons, compatibility, config health, drift; `--fix` repairs the safe ones        |
-| `mfeflow validate`                    | `mfeflow.json`, every `mfe.json` and every registry entry against their schemas       |
+| `mfeflow validate`                    | `mfeflow.json`, every `mfeflow.app.json` and every registry entry against schemas     |
 | `mfeflow check-compat`                | Each remote's shared ranges against the shells it runs in                             |
 | `mfeflow budget`                      | Built first-load JS of the shell and each remote against the cost-model budget        |
 | `mfeflow deploy <remote> --env <env>` | Upload a remote's build to a static registry host and point the env's index at it     |
@@ -48,13 +48,17 @@ runs part of the project; `--remote name=url` uses a server you run yourself (th
 localhost unless `--allow-origin <origin>` names it); Ctrl+C stops every app, process trees included, on Windows too.
 It exits 130 after Ctrl+C.
 
+Each app keeps its owner, routes and budgets in `mfeflow.app.json`. An app that still has the old `mfe.json` works:
+the CLI reads it and prints one notice per command. An app with both files is an error (E122).
+
 `doctor` runs these checks, each with a code and a docs page (`https://mfeflow.github.io/mfeflow/errors/<code>`). It exits with 0
 when there are no errors, else with the lowest exit code among the errors' ranges (project 3 before build 5).
 
 | Check                                 | Code           | Fixed by `--fix`              |
 | ------------------------------------- | -------------- | ----------------------------- |
 | every app in mfeflow.json is on disk  | E112           |                               |
-| valid `mfe.json`, name matches        | E113, E116     |                               |
+| valid `mfeflow.app.json`, name match  | E113, E116     |                               |
+| no app has both app file names        | E122           |                               |
 | no shared port                        | E115           |                               |
 | no route claimed twice                | E116           |                               |
 | registry entry per remote and env     | E114           | writes the missing ones       |
@@ -70,7 +74,7 @@ when there are no errors, else with the lowest exit code among the errors' range
 | server keys listed in `turbo.json`    | E121 (warning) |                               |
 
 `validate` runs the schema and registry checks, `check-compat` the compatibility check, `budget` reads the build output
-(`dist/`): each remote's entry against `budget.remoteKb` (10), a route against `mfe.json` `budgets.initialJsKb`, and the
+(`dist/`): each remote's entry against `budget.remoteKb` (10), a route against `mfeflow.app.json` `budgets.initialJsKb`, and the
 shell against `budget.baselineKb + budget.shellKb` (32) when a baseline is set. All four take `--json` and exit non-zero on
 errors. LCP is measured by the perf job, not by `budget`.
 
@@ -111,6 +115,7 @@ MFEFLOW_E108 The target folder is not empty: /work/app already has notes.txt
 | 5    | build or runtime problem: `MFEFLOW_E3xx`                                |
 | 6    | feature registry problem: `MFEFLOW_E4xx`                                |
 | 7    | deploy problem: `MFEFLOW_E5xx`                                          |
+| 8    | upgrade problem, or files that need a decision: `MFEFLOW_E6xx`          |
 | 130  | cancelled at a prompt (nothing was written), or Ctrl+C in `mfeflow dev` |
 
 ## Try it from a checkout

package/assets/features/deploy-cloudflare/feature.json

@@ -0,0 +1,85 @@
+{
+  "name": "deploy-cloudflare",
+  "version": "0.1.0",
+  "description": "One way to host the shell and remotes on Cloudflare Workers static assets: a wrangler.jsonc per app with staging and prod, _headers with the cache and CORS rules, a script that picks each environment's runtime config and registry index without rebuilding, an optional R2 proxy for /registry/*, and, when ci-github is present, a workflow. Opt-in; every file is yours to edit or delete.",
+  "keywords": ["cloudflare", "workers", "wrangler", "r2", "deploy"],
+  "requires": ["core"],
+  "prompts": [
+    {
+      "name": "r2Proxy",
+      "type": "boolean",
+      "message": "Serve /registry/* from an R2 bucket through a small Worker (the remotes are then published with mfeflow deploy)",
+      "default": false
+    }
+  ],
+  "files": [
+    {
+      "to": "wrangler.jsonc",
+      "target": "shell",
+      "from": "files/wrangler.shell.jsonc.eta",
+      "template": true
+    },
+    {
+      "to": "wrangler.jsonc",
+      "target": "remotes",
+      "from": "files/wrangler.remote.jsonc.eta",
+      "template": true,
+      "when": { "r2Proxy": false }
+    },
+    {
+      "to": "public/_headers",
+      "target": "shell",
+      "from": "files/headers.shell.eta",
+      "template": true
+    },
+    {
+      "to": "public/_headers",
+      "target": "remotes",
+      "from": "files/headers.remote",
+      "when": { "r2Proxy": false }
+    },
+    {
+      "to": "worker/registry-proxy.ts",
+      "target": "shell",
+      "from": "files/registry-proxy.ts",
+      "when": { "r2Proxy": true }
+    },
+    {
+      "to": "deploy/r2-cors.json",
+      "target": "root",
+      "from": "files/r2-cors.json",
+      "when": { "r2Proxy": true }
+    },
+    {
+      "to": "deploy/cloudflare.json",
+      "target": "root",
+      "from": "files/cloudflare.json.eta",
+      "template": true
+    },
+    {
+      "to": "scripts/deploy-cloudflare.ts",
+      "target": "root",
+      "from": "files/deploy-cloudflare.ts"
+    },
+    {
+      "to": "docs/cloudflare.md",
+      "target": "root",
+      "from": "files/cloudflare.md.eta",
+      "template": true
+    },
+    {
+      "to": ".github/workflows/deploy-cloudflare.yml",
+      "target": "root",
+      "from": "files/deploy-cloudflare.yml",
+      "when": { "feature:ci-github": true }
+    }
+  ],
+  "dependencies": [{ "name": "wrangler", "range": "4.156.0", "target": "root", "dev": true }],
+  "scripts": [
+    {
+      "name": "deploy:cloudflare",
+      "command": "node --experimental-strip-types scripts/deploy-cloudflare.ts",
+      "target": "root"
+    }
+  ]
+}

package/assets/features/deploy-cloudflare/files/cloudflare.json.eta

@@ -0,0 +1,13 @@
+{
+  "registry": "<%= it.options.r2Proxy ? 'r2' : 'assets' %>",
+  "envs": {
+    "staging": {
+      "shell": "",
+      "remotes": {}
+    },
+    "prod": {
+      "shell": "",
+      "remotes": {}
+    }
+  }
+}

package/assets/features/deploy-cloudflare/files/cloudflare.md.eta

@@ -0,0 +1,104 @@
+# Cloudflare
+
+This is one way to host the project on Cloudflare Workers. The files were added by `deploy-cloudflare`. They are
+yours: edit them, replace them, or delete them. Nothing else in the project depends on them.
+
+## What was added
+
+<% if (it.options.r2Proxy) { %>- `apps/shell/wrangler.jsonc`: the shell as a Worker with static assets, with a `staging` and a `prod` environment.
+- `apps/shell/worker/registry-proxy.ts`: a small Worker that serves `/registry/*` from an R2 bucket.
+- `deploy/r2-cors.json`: the CORS rules for the bucket, for the case where you serve it from its own domain.
+<% } else { %>- `apps/<app>/wrangler.jsonc` for the shell and for each remote: one Worker per app, each with a `staging` and a `prod` environment. A remote added later gets its own file.
+<% } %>- `apps/<app>/public/_headers`: the cache rules<% if (!it.options.r2Proxy) { %>, and on remotes the CORS header<% } %>.
+- `deploy/cloudflare.json`: the address each environment is served from.
+- `scripts/deploy-cloudflare.ts` and the script `pnpm deploy:cloudflare`.
+- `.github/workflows/deploy-cloudflare.yml`, only when `ci-github` is in the project.
+- `wrangler` as a dev dependency.
+
+## How it works
+
+<% if (it.options.r2Proxy) { %>The shell is one Worker. Remotes are published to an R2 bucket with `mfeflow deploy`, and the shell Worker serves the bucket's index and files under `/registry`. <% } else { %>The shell and each remote are separate Workers on their own addresses, so the shell loads remotes from another origin. <% } %>The build is made once. `pnpm deploy:cloudflare prod` then copies each `dist` into `apps/<app>/.mfeflow/cloudflare/prod`, and changes only that copy:
+
+- The shell gets `config/runtime-config.json` from `runtime-config.prod.json`. The other environments' files are left out.
+<% if (!it.options.r2Proxy) { %>- The shell gets `registry/index.json`, written from the remotes' versions and the addresses in `deploy/cloudflare.json`, and their origins are added to `registryOrigins` so the runtime accepts them.
+- Each remote's `_headers` gets the shell's address as its `Access-Control-Allow-Origin`.
+<% } %>
+Then it runs `wrangler deploy --env prod` for each app. Cloudflare makes one Worker per environment, named `<%= it.scope.slice(1) %>-<app>-prod`. Bindings and `vars` are not inherited by an environment, so they are repeated in each block.
+
+## Set it up
+
+1. Put the real addresses in `deploy/cloudflare.json`. The script stops on an empty or `example.com` address.
+2. Choose how each Worker is reached. Without a `routes` entry, Cloudflare uses a `workers.dev` address. For your own domain, add `"routes": [{ "pattern": "shop.example.com", "custom_domain": true }]` to the environment in `wrangler.jsonc`.
+3. Build and look at what would be deployed:
+
+```sh
+pnpm build
+pnpm deploy:cloudflare staging --dry-run
+```
+
+4. Deploy. Wrangler reads `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` from the environment:
+
+```sh
+pnpm deploy:cloudflare staging
+```
+
+Pass app names to deploy only those: `pnpm deploy:cloudflare prod shell`.
+
+<% if (it.options.r2Proxy) { %>## The R2 bucket
+
+Create one bucket for each environment, named in `wrangler.jsonc` (`<%= it.scope.slice(1) %>-registry-staging` and `<%= it.scope.slice(1) %>-registry-prod`):
+
+```sh
+pnpm wrangler r2 bucket create <%= it.scope.slice(1) %>-registry-prod
+```
+
+Publish remotes with `mfeflow deploy`, using the bucket's S3 endpoint and the shell's address plus `/registry` as the base URL, so that the entries in the index point through the Worker:
+
+```sh
+export MFEFLOW_S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
+export MFEFLOW_S3_REGION=auto
+mfeflow deploy catalog --env prod --host s3://<%= it.scope.slice(1) %>-registry-prod --base-url https://shop.acme.dev/registry
+```
+
+The access key and secret come from an R2 API token, in `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`.
+
+The Worker answers `/registry/index.json` from `envs/<env>/index.json`, and `/registry/<name>/<version>/<file>` from the same key in the bucket. The index is checked on every load, and versioned files are cached for a year.
+
+Set `registryUrls` in the shell's runtime config only if you use another address. The default is `/registry/index.json`.
+
+If you would rather serve the bucket from its own domain, connect the domain in the dashboard and allow the shell's origin. Edit `deploy/r2-cors.json`, then:
+
+```sh
+pnpm wrangler r2 bucket cors set <%= it.scope.slice(1) %>-registry-prod --file deploy/r2-cors.json
+```
+
+<% } %>## In CI
+
+With `ci-github` in the project, `.github/workflows/deploy-cloudflare.yml` builds once and deploys each app with `cloudflare/wrangler-action`. A push to `main` deploys staging. Run it by hand to choose `prod`. Add these as secrets on the GitHub environments `cloudflare-staging` and `cloudflare-prod`:
+
+- `CLOUDFLARE_API_TOKEN`: an API token that may edit Workers
+- `CLOUDFLARE_ACCOUNT_ID`
+
+Add a required reviewer to `cloudflare-prod` to hold production until someone approves. The workflow starts with no permissions, gives each job `contents: read`, and pins every action to a commit SHA. The workflow is only written when `ci-github` is already in the project, so add `ci-github` first.
+
+## Cache rules
+
+`_headers` is read by Cloudflare for static assets. It is not applied to responses your own Worker code makes<% if (it.options.r2Proxy) { %>, which is why `registry-proxy.ts` sets its own `Cache-Control`<% } %>. Each path matches one rule, because a header set by two rules is joined with a comma. The file holds up to 100 rules.
+
+- `no-cache`: `/`, `/index.html`, `/mf-manifest.json`, `config/runtime-config*`<% if (!it.options.r2Proxy) { %>, `registry/index.json`<% } %>
+- `public, max-age=31536000, immutable`: `/static/*`, whose names carry a hash
+
+## Change or remove it
+
+- Rename a Worker or add a route: edit `wrangler.jsonc`.
+- Add a third environment: add a block to each `wrangler.jsonc`, to `deploy/cloudflare.json`, and the name to `ENVS` in the script.
+- Stop using it: delete the files above and `pnpm remove wrangler`. Run `pnpm mfeflow validate` afterwards.
+- Roll back: `pnpm wrangler rollback --env prod --config apps/<app>/wrangler.jsonc` makes the previous version of a Worker live again.
+
+## Gotchas
+
+- With the shell's single-page fallback, a mistyped path returns `index.html` with status 200. Remotes have no fallback, so a missing file is a 404.
+- pnpm 11 stops an install when a package has an install script nobody has approved. `workerd`, which wrangler pulls in, is set to `false` under `allowBuilds` in `pnpm-workspace.yaml` of new projects, and wrangler deploys without running that script, and `wrangler dev` starts and serves the build with it (tried with wrangler 4.156.0). If your workspace file lacks the entry, add `workerd: false` there, or the install fails with `ERR_PNPM_IGNORED_BUILDS`.
+- `compatibility_date` in `wrangler.jsonc` is `2026-10-28`. `wrangler dev` refuses a date newer than its bundled runtime knows, so raise the date together with wrangler.
+- Each environment has one shell address, because a remote sends a single `Access-Control-Allow-Origin`. Two shell addresses for the same remote need two environments, or a rule of your own in the remote's `_headers`.
+- The shell's `_headers` also sends `X-Content-Type-Options`, `Referrer-Policy` and `X-Frame-Options: SAMEORIGIN`. Remove the last one if another site must embed your shell in a frame.

package/assets/features/deploy-cloudflare/files/deploy-cloudflare.ts

@@ -0,0 +1,318 @@
+// Stages each app's build for one environment and deploys it to Cloudflare Workers. It is your code:
+// change it freely. The build is made once; only the staged copy differs per environment.
+//
+//   node scripts/deploy-cloudflare.ts <staging|prod> [app...]    stage, then wrangler deploy
+//   node scripts/deploy-cloudflare.ts <env> [app...] --prepare-only   stage only (CI runs wrangler itself)
+//   node scripts/deploy-cloudflare.ts <env> [app...] --dry-run        stage and print the wrangler commands
+//   node scripts/deploy-cloudflare.ts plan <env>[,env]                print the CI matrix as JSON
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const ENVS = ['staging', 'prod'];
+const STAGE = '.mfeflow/cloudflare';
+const SHELL_ORIGIN_TOKEN = '__SHELL_ORIGIN__';
+
+interface Project {
+  shell: string;
+  remotes: string[];
+  packageDirs: Record<string, string>;
+}
+
+interface EnvConfig {
+  shell?: string;
+  remotes?: Record<string, string>;
+}
+
+interface Config {
+  registry: string;
+  envs: Record<string, EnvConfig>;
+}
+
+function readJson(file: string): unknown {
+  let text: string;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    throw new Error(`${file} is missing`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`${file} is not valid JSON`);
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function readProject(root: string): Project {
+  const file = path.join(root, 'mfeflow.json');
+  const json = readJson(file);
+  const apps = isRecord(json) && isRecord(json.apps) ? json.apps : {};
+  let shell = '';
+  const remotes: string[] = [];
+  const packageDirs: Record<string, string> = {};
+  for (const [name, app] of Object.entries(apps)) {
+    if (!isRecord(app) || typeof app.path !== 'string') continue;
+    // These end up in file paths and in the CI matrix, so keep to what mfeflow itself allows.
+    if (
+      !/^[a-z][a-z0-9_]*$/.test(name) ||
+      !/^[\w.-]+(\/[\w.-]+)*$/.test(app.path) ||
+      app.path.split('/').includes('..')
+    ) {
+      throw new Error(`${file}: app "${name}" has a name or path this script will not use`);
+    }
+    packageDirs[name] = app.path;
+    if (app.kind === 'shell') shell = name;
+    if (app.kind === 'remote') remotes.push(name);
+  }
+  if (shell === '') throw new Error(`${file} has no shell app`);
+  return { shell, remotes, packageDirs };
+}
+
+export function readConfig(root: string): Config {
+  const json = readJson(path.join(root, 'deploy/cloudflare.json'));
+  if (!isRecord(json) || !isRecord(json.envs))
+    throw new Error('deploy/cloudflare.json has no "envs"');
+  const envs: Record<string, EnvConfig> = {};
+  for (const [name, value] of Object.entries(json.envs)) {
+    if (!isRecord(value)) continue;
+    const remotes: Record<string, string> = {};
+    if (isRecord(value.remotes)) {
+      for (const [remote, origin] of Object.entries(value.remotes)) {
+        if (typeof origin === 'string') remotes[remote] = origin;
+      }
+    }
+    envs[name] = { remotes, ...(typeof value.shell === 'string' ? { shell: value.shell } : {}) };
+  }
+  return { registry: json.registry === 'r2' ? 'r2' : 'assets', envs };
+}
+
+/**
+ * The origin (scheme and host) of an address, or an error saying which setting is wrong. https only;
+ * http is accepted for localhost outside prod, for trying a deploy on your own machine.
+ */
+export function checkOrigin(value: string | undefined, label: string, env = 'staging'): string {
+  if (value === undefined || value === '') {
+    throw new Error(
+      `${label} is empty. Set it in deploy/cloudflare.json to the address people will use.`,
+    );
+  }
+  // The URL parser drops tabs and newlines, so a value with one would pass as something else.
+  if (
+    /\s/.test(value) ||
+    Array.from(value, (c) => c.charCodeAt(0)).some((n) => n < 32 || n === 127)
+  ) {
+    throw new Error(`${label} must not contain spaces or control characters`);
+  }
+  const url = URL.canParse(value) ? new URL(value) : undefined;
+  const local = url?.protocol === 'http:' && url.hostname === 'localhost' && env !== 'prod';
+  if (url === undefined || (url.protocol !== 'https:' && !local)) {
+    throw new Error(`${label} must be an https address, got "${value}"`);
+  }
+  if (url.username !== '' || url.password !== '') {
+    throw new Error(`${label} must not contain a user name or password`);
+  }
+  if (/(^|\.)example\.(com|org|net)$/.test(url.hostname)) {
+    throw new Error(
+      `${label} still holds the placeholder "${value}". Put your real address in deploy/cloudflare.json.`,
+    );
+  }
+  if (url.pathname !== '/' || url.search !== '' || url.hash !== '') {
+    throw new Error(`${label} must be an origin without a path, got "${value}"`);
+  }
+  return url.origin;
+}
+
+export interface IndexEntry {
+  name: string;
+  version: string;
+  entry: string;
+  routes: string[];
+}
+
+export function buildIndex(env: string, remotes: IndexEntry[]): string {
+  return `${JSON.stringify({ env, remotes }, null, 2)}\n`;
+}
+
+function selectApps(project: Project, config: Config, requested: string[]): string[] {
+  const deployable =
+    config.registry === 'r2' ? [project.shell] : [project.shell, ...project.remotes];
+  if (requested.length === 0) return deployable;
+  for (const app of requested) {
+    if (!deployable.includes(app))
+      throw new Error(`"${app}" is not an app this project deploys (${deployable.join(', ')})`);
+  }
+  return requested;
+}
+
+function packageVersion(root: string, project: Project, app: string): string {
+  const dir = project.packageDirs[app] ?? `apps/${app}`;
+  const json = readJson(path.join(root, dir, 'package.json'));
+  return isRecord(json) && typeof json.version === 'string' ? json.version : '0.0.0';
+}
+
+function stageDir(root: string, project: Project, app: string, env: string): string {
+  return path.join(root, project.packageDirs[app] ?? `apps/${app}`, STAGE, env);
+}
+
+/** Copies the app's dist to its staging folder and applies this environment's settings. Returns the folder. */
+export function prepareApp(root: string, app: string, env: string): string {
+  const project = readProject(root);
+  const config = readConfig(root);
+  const envConfig = config.envs[env];
+  if (envConfig === undefined)
+    throw new Error(`deploy/cloudflare.json has no "${env}" environment`);
+  const dist = path.join(root, project.packageDirs[app] ?? `apps/${app}`, 'dist');
+  if (!fs.existsSync(dist)) throw new Error(`${dist} does not exist. Run the build first.`);
+
+  const out = stageDir(root, project, app, env);
+  fs.rmSync(out, { recursive: true, force: true });
+  fs.cpSync(dist, out, { recursive: true });
+
+  if (app === project.shell) prepareShell(root, project, config, envConfig, env, out);
+  else prepareRemote(app, envConfig, env, out);
+  return out;
+}
+
+function prepareShell(
+  root: string,
+  project: Project,
+  config: Config,
+  envConfig: EnvConfig,
+  env: string,
+  out: string,
+): void {
+  checkOrigin(envConfig.shell, `envs.${env}.shell`, env);
+  const configDir = path.join(out, 'config');
+  const chosen = path.join(configDir, `runtime-config.${env}.json`);
+  if (!fs.existsSync(chosen)) throw new Error(`The build has no config/runtime-config.${env}.json`);
+  const runtime = readJson(chosen);
+  const values: Record<string, unknown> = isRecord(runtime) ? runtime : {};
+
+  const origins = new Map<string, string>();
+  if (config.registry === 'assets') {
+    for (const remote of project.remotes) {
+      origins.set(
+        remote,
+        checkOrigin(envConfig.remotes?.[remote], `envs.${env}.remotes.${remote}`, env),
+      );
+    }
+    const known = Array.isArray(values.registryOrigins)
+      ? values.registryOrigins.filter((o) => typeof o === 'string')
+      : [];
+    values.registryOrigins = [...new Set([...known, ...origins.values()])];
+    const entries = project.remotes.map((remote) => ({
+      name: remote,
+      version: packageVersion(root, project, remote),
+      entry: `${origins.get(remote) ?? ''}/mf-manifest.json`,
+      routes: [`/${remote}`],
+    }));
+    fs.mkdirSync(path.join(out, 'registry'), { recursive: true });
+    fs.writeFileSync(path.join(out, 'registry/index.json'), buildIndex(env, entries));
+  }
+
+  for (const file of fs.readdirSync(configDir)) {
+    if (/^runtime-config\..+\.json$/.test(file)) fs.rmSync(path.join(configDir, file));
+  }
+  fs.writeFileSync(
+    path.join(configDir, 'runtime-config.json'),
+    `${JSON.stringify(values, null, 2)}\n`,
+  );
+}
+
+function prepareRemote(app: string, envConfig: EnvConfig, env: string, out: string): void {
+  const shellOrigin = checkOrigin(envConfig.shell, `envs.${env}.shell`, env);
+  if (!fs.existsSync(path.join(out, 'mf-manifest.json')))
+    throw new Error(`${out} has no mf-manifest.json. Is this a remote build?`);
+  const headers = path.join(out, '_headers');
+  if (!fs.existsSync(headers)) {
+    throw new Error(
+      `${out} has no _headers, so the shell could not load ${app} across origins. Keep apps/${app}/public/_headers and rebuild.`,
+    );
+  }
+  fs.writeFileSync(
+    headers,
+    fs.readFileSync(headers, 'utf8').replaceAll(SHELL_ORIGIN_TOKEN, () => shellOrigin),
+  );
+}
+
+export interface Target {
+  app: string;
+  env: string;
+  /** The app's wrangler config, relative to the project root. */
+  config: string;
+}
+
+/** The CI matrix: one entry per app and environment. */
+export function plan(root: string, envs: string[]): Target[] {
+  for (const env of envs) {
+    if (!ENVS.includes(env)) throw new Error(`unknown environment "${env}" (${ENVS.join(', ')})`);
+  }
+  const project = readProject(root);
+  const apps = selectApps(project, readConfig(root), []);
+  return envs.flatMap((env) =>
+    apps.map((app) => ({
+      app,
+      env,
+      config: `${project.packageDirs[app] ?? `apps/${app}`}/wrangler.jsonc`,
+    })),
+  );
+}
+
+function wranglerArgs(app: string, env: string, project: Project): string[] {
+  const dir = project.packageDirs[app] ?? `apps/${app}`;
+  return ['deploy', '--config', `${dir}/wrangler.jsonc`, '--env', env];
+}
+
+/** Wrangler's own script, so it can run under node without a shell, which works on every OS. */
+function wranglerScript(root: string): string {
+  const manifest = path.join(root, 'node_modules/wrangler/package.json');
+  const json = readJson(manifest);
+  const bin = isRecord(json) && isRecord(json.bin) ? json.bin.wrangler : undefined;
+  if (typeof bin !== 'string')
+    throw new Error(`${manifest} names no wrangler script. Run pnpm install.`);
+  return path.join(path.dirname(manifest), bin);
+}
+
+export function main(argv: string[], root = process.cwd()): number {
+  const flags = new Set(argv.filter((a) => a.startsWith('--')));
+  const [first, ...rest] = argv.filter((a) => !a.startsWith('--'));
+  try {
+    if (first === 'plan') {
+      console.log(JSON.stringify(plan(root, (rest[0] ?? '').split(',').filter(Boolean))));
+      return 0;
+    }
+    if (first === undefined || !ENVS.includes(first)) {
+      throw new Error(
+        `usage: deploy-cloudflare <${ENVS.join('|')}> [app...] [--prepare-only] [--dry-run]`,
+      );
+    }
+    const project = readProject(root);
+    for (const app of selectApps(project, readConfig(root), rest)) {
+      const out = prepareApp(root, app, first);
+      console.log(`staged ${app} for ${first}: ${path.relative(root, out)}`);
+      if (flags.has('--prepare-only')) continue;
+      const args = wranglerArgs(app, first, project);
+      if (flags.has('--dry-run')) {
+        console.log(`wrangler ${args.join(' ')}`);
+        continue;
+      }
+      const run = spawnSync(process.execPath, [wranglerScript(root), ...args], {
+        cwd: root,
+        stdio: 'inherit',
+      });
+      if (run.status !== 0) throw new Error(`wrangler deploy failed for ${app}`);
+    }
+    return 0;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    return 1;
+  }
+}
+
+if (process.argv[1] !== undefined && path.resolve(process.argv[1]) === import.meta.filename) {
+  process.exitCode = main(process.argv.slice(2));
+}

package/assets/features/deploy-cloudflare/files/deploy-cloudflare.yml

@@ -0,0 +1,111 @@
+name: deploy-cloudflare
+
+# Builds once, then deploys every app to the Cloudflare Workers named in deploy/cloudflare.json. A push to main
+# deploys staging. Run it by hand to choose staging or prod. Needs the secrets CLOUDFLARE_API_TOKEN and
+# CLOUDFLARE_ACCOUNT_ID in the GitHub environments cloudflare-staging and cloudflare-prod (see docs/cloudflare.md).
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      env:
+        description: Environment to deploy to
+        type: choice
+        options: [staging, prod]
+        default: staging
+
+permissions: {}
+
+# Two deploys at once would race on the same Workers; let the first finish.
+concurrency:
+  group: deploy-cloudflare
+  cancel-in-progress: false
+
+jobs:
+  plan:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    # A manual run from another branch would otherwise deploy that branch.
+    if: github.ref == 'refs/heads/main'
+    permissions:
+      contents: read
+    outputs:
+      targets: ${{ steps.plan.outputs.targets }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: lts/*
+      - name: List the apps and environments
+        id: plan
+        env:
+          DEPLOY_ENV: ${{ inputs.env || 'staging' }}
+        run: |
+          set -euo pipefail
+          targets=$(node --experimental-strip-types scripts/deploy-cloudflare.ts plan "$DEPLOY_ENV")
+          echo "targets=$targets" >> "$GITHUB_OUTPUT"
+
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    if: github.ref == 'refs/heads/main'
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: lts/*
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: apps/*/dist
+          if-no-files-found: error
+
+  deploy:
+    needs: [plan, build]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment: cloudflare-${{ matrix.target.env }}
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        target: ${{ fromJSON(needs.plan.outputs.targets) }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: lts/*
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
+        with:
+          name: dist
+          path: apps
+      - name: Stage the build for this environment
+        env:
+          DEPLOY_ENV: ${{ matrix.target.env }}
+          DEPLOY_APP: ${{ matrix.target.app }}
+        run: |
+          set -euo pipefail
+          node --experimental-strip-types scripts/deploy-cloudflare.ts "$DEPLOY_ENV" "$DEPLOY_APP" --prepare-only
+      - name: Deploy
+        uses: cloudflare/wrangler-action@953926a2e2182532811c01a25e53647d93bf07c0 # v4.1.3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          packageManager: pnpm
+          command: deploy --config ${{ matrix.target.config }} --env ${{ matrix.target.env }}