feat: full-stack deploy — build a commit's worker from the CLI (cf arm)

[netanelgilad]

Note

Description

Adds the worker (cf) arm of the deployments API so a full-stack framework build (React Router 7, TanStack Start, Astro 6, vinext — anything built through @cloudflare/vite-plugin) can be deployed from the CLI as a Workers deployment addressed by the commit that produced it. The CLI detects the .wrangler/deploy/config.json redirect artifact, resolves and validates the generated wrangler config, collects the unbundled worker modules plus the static assets, POSTs asset buckets straight to Cloudflare under the upload-session JWT, then finalizes with the worker modules.

The worker and static arms are one flow with one createDeployment() call, not two lanes: deployToDeployments() checks for a worker itself, and that changes only what it sends (the worker's config on create, its modules at finalize). Everything downstream follows the server's answer — uploadDeploymentAssets() dispatches on the asset_uploads discriminant, finalizeDeployment() takes whichever payload completes the deployment. Deploy still only builds; nothing here publishes, and re-deploying a commit stays idempotent.

Related Issue

None (pairs with the cf arm of the backend's discriminated create response)

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Other (please describe):

Changes Made

• One flow (core/site/deployment.ts, replacing static-site.ts): deployToDeployments() — resolve the worker if there is one → manifest → one createDeployment() → upload → finalize. config: worker?.config is the only difference on create, and its presence is what selects the storage target server-side.
• One env gate (deploymentsApiEnabled(), BASE44_DEPLOYMENTS_API): the gate is the only thing that selects the transport — deployments API for static output and full-stack builds alike, legacy tar.gz otherwise. It is read in exactly two places, both in the command: the transport choice, and the registration of --git-hash / --concurrency, which exist only on the lane that can honor them. On the lane a worker build needs no site.outputDirectory, since the worker brings its own assets directory.
• Artifact detection (core/site/wrangler-config.ts): the only trigger is .wrangler/deploy/config.json, with configPath resolved relative to the redirect file's own directory; hand-authored root configs are deliberately not artifacts. The resolved config must be no_bundle: true, and only fields the deploy acts on are declared, so bindings and the worker name ride along ignored.
• Module collection (core/site/modules.ts): entry module plus the rules globs, relative paths as module names, wrangler.json / .dev.vars / the assets dir excluded, sourcemaps beside modules (all of them under upload_source_maps), 40 MB total cap under the server's 50 MB.
• Commit address (core/site/git-hash.ts): resolveGitHash() — explicit --git-hash wins, otherwise git rev-parse HEAD; neither available fails fast with guidance. A malformed value is still rejected by the option's argParser before the action runs.
• cf create arm (core/site/schema.ts): asset_uploads becomes a discriminated union (cf alongside s3), the request carries an optional worker config, and AssetUploadResponseSchema parses Cloudflare's bucket reply.
• Direct Cloudflare uploads (core/site/upload.ts): buckets POST straight to Cloudflare with ?base64=true and a bearer session JWT — never the app client, which would leak app auth. 401/403 maps to "upload session expired — rerun deploy". The completion token is read from whichever bucket reply carries one, since the server decides completeness by manifest membership and buckets upload concurrently. Both arms now share one UPLOAD_RETRY on ky (the cf arm must name methods: ["post"] or bucket uploads would never retry).
• One finalize (core/site/api.ts): finalizeDeployment(deploymentId, sessionId, payload) where payload is {modules, completionJwt} or {indexHtml}; the if lives inside the multipart form builder, where the protocol itself differs.
• Warnings, not silent drops: _headers/_redirects and run_worker_first route arrays are surfaced as warnings after the task rather than erroring or quietly changing behavior. vars and a missing nodejs_compat are passed over untouched — the config is framework-generated, so the fix belongs in the adapter's settings.
• Content types (core/site/manifest.ts): per-file MIME lookup for the cf arm's multipart parts; the s3 arm still echoes the server-signed Content-Type verbatim.
• Command surface (cli/commands/site/deploy.ts): the build step now runs before the deploy confirmation, so the prompt is the last gate before anything leaves the machine; maybeBuildBeforeDeploy no longer requires site.outputDirectory; the flow keeps saying "site" to the user whether or not there is a worker; and the tar.gz path is now the one that raises "No site configuration found."
• Docs: docs/deployments.md rewritten to cover the single flow and both arms; docs/resources.md, docs/testing.md, docs/AGENTS.md updated.

Testing

• I have tested these changes locally
• I have added/updated tests as needed
• All tests pass (npm test)

New: tests/cli/fullstack_deploy.spec.ts (manifest/bucket/finalize round trip, null completion token when every asset is already stored, git-hash requirement and argParser rejection, --json, a config with no nodejs_compat forwarded as-is, bucket retry resending the body, session-expired mapping, create failure), tests/core/site-modules.spec.ts, tests/core/site-wrangler-config.spec.ts, transport cases in site_deploy.spec.ts, a base44 deploy case asserting the lane's flags stay off the unified command, and a retargeted static_site_deployments.spec.ts. Testkit gains mockAssetUpload / mockAssetUploadAfterFailures / mockAssetUploadError and assetUploadRequests, plus a tests/fixtures/fullstack-project/ fixture.

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (if applicable)
• My changes generate no new warnings
• I have updated docs/ (AGENTS.md) if I made architectural changes

Additional Notes

• Two behavior changes against main. (1) main selected the deployments lane by the presence of --git-hash; here the env gate picks the transport and the commit defaults to HEAD, so with the gate on and no commit available the deploy fails asking for --git-hash instead of silently falling back to tar.gz — a build with no address could never be published. (2) The build step moved ahead of the confirmation prompt, and no longer needs site.outputDirectory to run.
• Backwards compatible otherwise. With BASE44_DEPLOYMENTS_API unset, every site deploy takes the legacy tar.gz upload unchanged (a full-stack project's worker is then simply not shipped), and base44 deploy (unified) is untouched — it still ships the site through deployAll()'s tar.gz step and has neither flag. Adopting the lane there needs a commit address the unified deploy has no way to take.
• The retry test guards two ky behaviors: POST must be named in retry.methods, and ky clones a pristine request so a FormData body survives being resent.
• Current limitations, each an explicit error or warning rather than a silent drop: output that still needs bundling (no_bundle !== true) is rejected; wrangler vars are ignored in favor of app secrets; _headers/_redirects and run_worker_first route patterns are not forwarded yet.
• CI on this head: build, lint, typecheck, knip, publish-preview and the gateway check pass; the four test jobs (ubuntu/windows × npm/binary) were still running when this description was generated, so the testing boxes above are left unchecked rather than asserted.

---

_{🤖 Generated by Claude | 2026-09-01 03:57 UTC | f81051e}

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/cli@0.1.13-pr.584.f81051e

Prefer not to change any import paths? Install using npm alias so your code still imports base44:

npm i "base44@npm:@base44-preview/cli@0.1.13-pr.584.f81051e"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/cli@0.1.13-pr.584.f81051e"
  }
}

• 📦 Preview Package: @base44-preview/cli@0.1.13-pr.584.f81051e
• 🔗 View this commit on GitHub

---

_{Preview published to npm registry — try new features instantly!}