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

[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 and static assets, POSTs asset buckets directly to Cloudflare with the upload-session JWT, then finalizes with the worker modules. Deploy still only builds — nothing here publishes, and re-deploying the same commit stays idempotent.

The static (s3) arm has since landed on main as #585, so this branch is merged with it: both arms now share one transport — one upload shape, one retry idiom — and the code lives in core/site/, since deployments are a transport of the site module rather than a module of their own. A final pass trims the module's comments (net −108 lines, no behavior change) and corrects one that was wrong about where the asset-upload completion token comes from.

Related Issue

None (pairs with the cf arm of apper#18596's discriminated create response; #585 has landed, so this is no longer stacked on it)

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

• Artifact detection (core/site/wrangler-config.ts): the only trigger is the .wrangler/deploy/config.json redirect from @cloudflare/vite-plugin builds, 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.
• cf create arm (core/site/schema.ts): asset_uploads becomes a discriminated union (cf alongside s3); the request carries an optional worker config whose presence is what selects the storage target server-side. Each flow rejects the arm it did not ask for.
• Direct Cloudflare uploads (core/site/upload.ts, api.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 (the server decides completeness by manifest membership, and buckets upload concurrently, so it is usually not the last bucket), and finalize sends it alongside one multipart part per module.
• One retry idiom for both arms: the cf arm's hand-rolled attempt loop, sleep() and bespoke 429 bookkeeping are replaced by a shared UPLOAD_RETRY on ky. ky retries network errors and its default statuses only, so an expired credential fails fast and a 429 honors Retry-After. The cf arm must name methods: ["post"] or bucket uploads would silently never retry.
• Orchestration (core/site/full-stack.ts): resolve → collect → manifest → create → buckets → finalize, warning (rather than erroring or silently changing behavior) on missing nodejs_compat, wrangler vars, _headers/_redirects and run_worker_first route arrays.
• Transport precedence (core/site/deploy-app.ts): deployAppSite() picks the transport for both commands, and a full-stack artifact wins over both static ones — it carries the server, so shipping static output instead would silently drop the worker. base44 deploy now passes site: false to deployAll() and ships the site itself, after the optional build step, so a freshly generated artifact is seen; hasResourcesToDeploy() also counts a buildCommand, since a full-stack project may configure nothing else.
• Flags & UX: --git-hash/--concurrency defined once in addDeploymentOptions() and ungated (BASE44_STATIC_DEPLOYMENTS now only picks a transport, never a flag's existence); git hash from the flag else git rev-parse HEAD (core/site/git-hash.ts); one shared spinner runner (cli/commands/site/run-app-deploy.ts) with an onWorker step, log.warn warnings, a Deployment: <id> (commit <hash>) row, and --json emitting {deploymentId, gitHash} from both commands.
• 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.
• Layout (no behavior change): core/deployments/ folded into core/site/ — full-stack.ts, static-site.ts, deploy.ts (legacy tar.gz) over shared manifest.ts, upload.ts, modules.ts, wrangler-config.ts, git-hash.ts, api.ts, schema.ts.
• Docs: docs/deployments.md rewritten for both arms plus a "never hand-roll upload retry or backoff" rule; docs/resources.md, docs/testing.md and 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 (8 cases — manifest/bucket/finalize relay, null completion token when every asset is already stored, git-hash requirement and argParser rejection, --json, nodejs_compat warning, bucket retry after a transient failure, session-expired mapping, create failure), tests/core/site-modules.spec.ts (8) and tests/core/site-wrangler-config.spec.ts (7), plus transport-precedence cases in site_deploy.spec.ts and the retargeted static_site_deployments.spec.ts. Testkit gains mockAssetUpload/mockAssetUploadAfterFailures/mockAssetUploadError and assetUploadRequests, with a new tests/fixtures/fullstack-project/ fixture (redirect file + build/server worker + build/client assets with .assetsignore).

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

• Test status is reported, not re-verified here: this description was generated in an environment where the suite could not be run, so "All tests pass" is left unchecked. Reported on the branch head: typecheck, lint and knip clean, full suite green (714 tests, 71 files). A pre-existing "Body is unusable" flake under parallel load also reproduces on pristine main.
• 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. Dropped with the old loop: MAX_RATE_LIMIT_WAITS, RATE_LIMIT_DELAY_MS, uploadBucketWithRetry, sleep() — the fixed 15s 429 wait had no test.
• Merge-resolution behavior change: a malformed --git-hash is now rejected by the option's argParser before the action runs, not later by resolveGitHash.
• Static projects behave identically (same tar.gz upload, same App URL line), but the step moved out of deployAll() into the deploy command — that's where to look if a site deploy regresses.
• Unsupported-but-present wrangler config warns rather than erroring or silently dropping: the config is framework-generated, so the fix belongs in the adapter's settings. The client-side 40 MB module cap sits under the server's 50 MB so oversized bundles fail before any upload work.

---

_{🤖 Generated by Claude | 2026-08-04 09:46 UTC | 6f5ac21}

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/cli@0.1.8-pr.584.c8b5c9f

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.8-pr.584.c8b5c9f"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/cli@0.1.8-pr.584.c8b5c9f"
  }
}

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

---

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