Support assets-only deployments without delegation

.changeset/curly-dogs-deploy.md

@@ -0,0 +1,7 @@
+---
+"cf": minor
+---
+
+Deploy any prebuilt static asset directory directly with `cf deploy [directory]` and the equivalent Preview deployment and version creation commands.
+
+The directory form creates assets-only Build Output, reuses optional assets-only Worker configuration, and skips project build delegation. Projects containing a configured Worker entrypoint or Container continue to omit the directory and use the delegated build path.

AGENTS.md

@@ -78,8 +78,10 @@ In the rules below, `src/` means `packages/cli/src/`.
   supplies status-level hints.
 - **Keep source config access scoped.** Normal startup and API commands read
   only account/compliance settings from `cloudflare.config.ts`. Worker
-  validation belongs to `cf workers types` and the type generation reused by
-  `cf init`. Other project workflows consume Build Output through
+  validation belongs to `cf workers types`, the type generation reused by
+  `cf init`, and the assets-only `[directory]` artifact producer shared by
+  Worker upload workflows, which rejects server-side entrypoints and Containers.
+  Other project workflows consume Build Output through
   `readBuildOutput()` from `@cloudflare/build-output-utils`; do not compose
   output paths by hand. Invalid Worker bindings must not break unrelated API
   commands. cf supports ES module Workers only, not service-worker format.

docs/architecture.md

@@ -329,10 +329,15 @@ Practical extensions of this rule:
     default (or `--worker`-selected) Build Output Worker locally; there is no API
     operation to derive it from.
   - `cf workers types` is a hand-written leaf added to the generated Workers
-    tree. It is the bounded source-config exception: it validates the Worker in
+    tree. It is a bounded source-config exception: it validates the Worker in
     the nearest `cloudflare.config.ts` and generates
     `.cloudflare/types/index.d.ts`. `cf init` reuses its generator
     (`generate.ts`) for a project it has just created and installed.
+  - The directory forms of `cf deploy`, `cf previews deploy`, and
+    `cf workers versions create` are another bounded source-config exception.
+    They reuse an optional assets-only Worker definition while producing Build
+    Output, and reject configured entrypoints or Containers because those
+    require a delegated build.
   - `cf containers build` and `cf containers push` are hand-written leaves
     added to the generated Containers tree. They wrap the shared Container
     Docker and registry helpers; there are no OpenAPI operations for local
@@ -376,10 +381,21 @@ Shell-completion scripts are no longer generated — `cf complete`
 Normal cf startup and generated API commands read only `accountId` and
 `complianceRegion` from the default export in `cloudflare.config.ts`; they do
 not inspect or validate the `worker` or `containers` fields. Project resource
-config is otherwise the dev-server impl's domain. The bounded exception is
-`cf workers types`, which loads and validates the Worker definition to generate
-declarations. `cf init` reuses the same generator for a project it has just
-created and installed.
+config is otherwise the dev-server impl's domain. Source Worker validation is
+limited to type generation and assets-only directory uploads. `cf workers types`
+loads and validates the Worker definition to generate declarations; `cf init`
+reuses that generator for a project it has just created and installed.
+
+Supplying `[directory]` to `cf deploy`, `cf previews deploy`, or
+`cf workers versions create` invokes the shared
+`src/commands/deploy/static-assets.ts` helper. It loads and validates the nearest
+`cloudflare.config.ts` when present, reuses its account settings and Worker
+definition, and rejects configured Worker entrypoints or Containers. If no Worker
+is configured, it derives a Worker name from the project and uses the default
+compatibility date. The helper writes assets-only Build Output without a
+delegated build, recording `--mode` and Preview context, before the command
+continues through the normal Build Output upload path. Without `[directory]`,
+these commands consume Build Output from a delegated build or `--prebuilt`.
 
 This keeps Worker-definition validation lazy: `cf dns records list` cannot fail
 merely because a binding field in the configured Worker is invalid. Loading
@@ -391,10 +407,13 @@ What cf DOES read:
 
 - **Account settings from `cloudflare.config.ts`'s default export** for project
   account and compliance-region defaults.
-- **The Worker definition from `cloudflare.config.ts`** only when running
+- **The Worker definition from `cloudflare.config.ts`** when running
   `cf workers types`, including its compatibility date and flags for runtime
-  type generation, or when `cf init` generates types for the project it just
-  created.
+  type generation; when `cf init` generates types for the project it just
+  created; or when an assets-only directory workflow produces Build Output for
+  `cf deploy`, `cf previews deploy`, or `cf workers versions create`.
+- **The `containers` field from `cloudflare.config.ts`** only when an assets-only
+  directory workflow validates that no Containers are configured.
 - **`~/.config/cloudflare/state.json`** records the shell-completion tip and
   telemetry preferences. Owned by `lib/state.ts`.
 - **`.cloudflare/state/v3/` next to the nearest `cloudflare.config.ts`** stores
@@ -405,16 +424,19 @@ What cf DOES read:
 
 What cf does NOT read:
 
-- The `worker` field outside `cf workers types` type generation, or the
-  `containers` field from `cloudflare.config.ts`.
-- Other source resource config in any form, for any API command.
+- The `worker` field outside type generation and assets-only directory
+  workflows, or the `containers` field outside assets-only directory workflows.
+- Other source resource config in any form for generated API commands.
 - `package.json` worker config (none exists today; reserved for
   the future).
-- Source binding manifests, durable-object class lists, and trigger lists. Project workflows may consume their built equivalents from Build Output.
-
-Outside the explicit type-generation workflow, if a feature seems to require cf to parse the source config,
-that's a signal to push it elsewhere — usually to the local-explorer
-API or to a forge annotation. Local mode is the worked example: `--local`
+- Source binding manifests, durable-object class lists, and trigger lists
+  outside the assets-only directory workflows. Other project workflows consume
+  their built equivalents from Build Output.
+
+Outside the explicit type-generation and assets-only artifact-production
+workflows, if a feature seems to require cf to parse the source config, that's
+a signal to push it elsewhere — usually to the local-explorer API or to a forge
+annotation. Local mode is the worked example: `--local`
 derives resource identity from the request URL and sends the request to a
 cf-spawned Miniflare local-explorer instance over shared persisted state. It
 does not read the project's binding declarations.

packages/cli/AGENTS.md

@@ -83,11 +83,11 @@ public AI Search endpoint, outside the platform API/SDK, and returns ranked
 JSON page metadata without authentication. Agents fetch returned URLs with
 `Accept: text/markdown` to read complete pages.
 
-`auth`, `complete`, `dev`, `build`, `deploy`, `migrate`, `cli`, `schema`, and `tools` are root entries in `src/commands/hand-written.ts`, registered lazily by `src/index.ts`. `cf cli telemetry` is the telemetry-settings path. `cf migrate` uses `@cloudflare/codemods` to convert a Wrangler configuration to `cloudflare.config.ts` and report manual follow-up work. `cf dev` analyzes and, when needed, configures a project before running its canonical framework command, with an installed Cloudflare implementation as fallback. `cf build` follows the same routing and validates the resulting Build Output. `cf previews deploy [--preview-name <name>]` builds with Preview context and uploads the default Worker from the resulting Preview Build Output, or the one selected with `--worker`. `cf deploy`, `cf workers versions create`, and `cf workers triggers deploy` build first unless `--prebuilt` is passed, then read Build Output and call `@cloudflare/deploy-helpers`; trigger deployment applies only the configured triggers. Deploy-helper provisioning is enabled for supported bindings.
+`auth`, `complete`, `dev`, `build`, `deploy`, `migrate`, `cli`, `schema`, and `tools` are root entries in `src/commands/hand-written.ts`, registered lazily by `src/index.ts`. `cf cli telemetry` is the telemetry-settings path. `cf migrate` uses `@cloudflare/codemods` to convert a Wrangler configuration to `cloudflare.config.ts` and report manual follow-up work. `cf dev` analyzes and, when needed, configures a project before running its canonical framework command, with an installed Cloudflare implementation as fallback. `cf build` follows the same routing and validates the resulting Build Output. `cf deploy`, `cf previews deploy`, and `cf workers versions create` accept an optional `[directory]` containing already-built, assets-only content and write it into Build Output without delegation; Preview output is marked with Preview context. The directory form reuses an optional source Worker config but rejects configured entrypoints and Containers, so server-side projects omit it and use the normal build path. Without the positional argument, these commands build first unless `--prebuilt` is passed, then read Build Output and call `@cloudflare/deploy-helpers`; Preview names use `--preview-name`, and version creation uploads without deploying. `cf workers triggers deploy` likewise builds by default or consumes `--prebuilt` Build Output, but only applies the configured triggers and does not accept an assets directory. Deploy-helper provisioning is enabled for supported bindings.
 
 `previews` uses a generated group containing the hand-written `previews deploy` workflow. Its parent override opts into `createIfMissing`, so generation creates an empty API parent when the pinned schema has no Preview CLI operations. Future schema operations join the same group without colliding with a hand-written root.
 
-The registry's other entries are spliced into the generated tree by the generator plugin, which `generator/index.ts` bundles them into: leaf overrides for `cf ai run` and `cf registrar registrations create`; added leaves for `cf workers check`, `cf workers types`, nested `cf workers versions create`, `cf tunnels quick-start`, `cf tunnels run`, and the process-backed `cf access` workflows; and subgroups for `cf d1 migrations` and `cf workers triggers`. The cloudflared-backed Tunnel and Access leaves delegate to the cf-managed cloudflared binary alongside their generated API-backed operations. `cf workers check` profiles the default Worker emitted through Build Output, or the one selected with `--worker`. `cf workers types` is the bounded source-config exception: it validates the Worker in the nearest `cloudflare.config.ts` and writes `.cloudflare/types/index.d.ts`. Version creation remains a project-aware Build Output workflow while the raw upload operations stay API-only. D1 migration apply targets a database identified by ID only, with `--dir` / `--pattern` / `--table` as flags rather than config; its bookkeeping is wire-compatible with `wrangler d1 migrations apply`.
+The registry's other entries are spliced into the generated tree by the generator plugin, which `generator/index.ts` bundles them into: leaf overrides for `cf ai run` and `cf registrar registrations create`; added leaves for `cf workers check`, `cf workers types`, nested `cf workers versions create`, `cf tunnels quick-start`, `cf tunnels run`, and the process-backed `cf access` workflows; and subgroups for `cf d1 migrations` and `cf workers triggers`. The cloudflared-backed Tunnel and Access leaves delegate to the cf-managed cloudflared binary alongside their generated API-backed operations. `cf workers check` profiles the default Worker emitted through Build Output, or the one selected with `--worker`. Source Worker config access is bounded to `cf workers types`, which writes `.cloudflare/types/index.d.ts`, and the Worker upload `[directory]` workflows, which validate an optional assets-only Worker before emitting Build Output. Version creation remains a project-aware Build Output workflow while the raw upload operations stay API-only. D1 migration apply targets a database identified by ID only, with `--dir` / `--pattern` / `--table` as flags rather than config; its bookkeeping is wire-compatible with `wrangler d1 migrations apply`.
 
 ## Dotenv and Child Processes
 

packages/cli/README.md

@@ -59,7 +59,7 @@ cf dev
 
 `cf dev` and `cf build` detect supported projects, run autoconfiguration when needed, and invoke the canonical framework command or an installed Cloudflare implementation. Successful builds produce standardized Build Output.
 
-`cf deploy` builds by default and then uploads that output. `cf workers versions create` uploads a version without deploying it, and `cf workers triggers deploy` applies the configured routes and cron schedules. Pass `--prebuilt` to any of these commands to reuse existing Build Output.
+`cf deploy` builds by default and then uploads that output. `cf workers versions create` uploads a version without deploying it, and `cf workers triggers deploy` applies the configured routes and cron schedules. Pass `--prebuilt` to any of these commands to reuse existing Build Output. Alternatively, `cf deploy [directory]`, `cf previews deploy [directory]`, and `cf workers versions create [directory]` upload prebuilt assets-only output without invoking project tooling; omit the directory for projects with server-side code.
 
 ## Local resources