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.
• Transport selection (usesDeploymentsApi()): a detected worker artifact always takes the deployments API (a tar.gz cannot ship a worker) and needs no site.outputDirectory, since the worker brings its own assets directory; a plain static build takes it only behind BASE44_STATIC_DEPLOYMENTS, else the legacy tar.gz upload. Asked after the build, because the artifact is itself a build output.
• 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: missing nodejs_compat, wrangler vars, _headers/_redirects and run_worker_first route arrays are surfaced after the task rather than erroring or quietly changing behavior — 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): --git-hash and --concurrency are registered unconditionally (a worker build is ungated), 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, nodejs_compat warning, bucket retry resending the body, session-expired mapping, create failure), tests/core/site-modules.spec.ts, tests/core/site-wrangler-config.spec.ts, transport-precedence 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 static 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) --git-hash / --concurrency now appear on base44 site deploy --help even with the static gate off, because a worker build is ungated.
• Backwards compatible otherwise. A project with no worker artifact and BASE44_STATIC_DEPLOYMENTS unset keeps the legacy tar.gz upload unchanged, 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 and publish-preview 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-08-31 10:33 UTC | 92706a2}

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/cli@0.1.12-pr.584.92706a2

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.12-pr.584.92706a2"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/cli@0.1.12-pr.584.92706a2"
  }
}

• 📦 Preview Package: @base44-preview/cli@0.1.12-pr.584.92706a2
• 🔗 View this commit on GitHub

---

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

[netanelgilad]

there's no need to have full-stack apps in user facing copy.
the copy that is user facing always says "site" as an encompassiong term for what we deploy, whetehr it has the backend worker or not, so there shoudn't be copy changes ideally

[netanelgilad]

Reverted to main's copy — the second hint is gone, so the error is No site configuration found. with the site.outputDirectory hint exactly as before this branch.

Same for the rest of the command's copy: description back to "Deploy built site files to Base44 hosting", spinner/success/error back to "Deploying site..." / "Site deployed" / "Site deploy failed" (no orange highlight for one of them either). I also dropped "full-stack" from the errors the wrangler and module paths raise — "No Workers build artifact found", "Base44 only deploys pre-bundled Workers output", "exceeds the 40 MB limit for a Base44 deploy" — since those reach the user too.

The one place a word had to be chosen rather than reverted: the spinner's Deploying worker (N modules)… stage, which only appears when there is a worker. Left as "worker" — it names the thing being uploaded rather than a kind of app, and no other stage line changes with the build. Say so if you'd rather it just stayed "Deploying site...".

Recorded the rule in docs/deployments.md so it doesn't drift back.

---

Generated by Claude Code

[netanelgilad]

same here

[netanelgilad]

Done — the prompt is Deploy site from ${outputDirectory}? again, with no branch on the kind of build.

It does still need a fallback: a project whose build produced a worker has no site.outputDirectory to name (the worker's own assets.directory supersedes it — the fullstack-project fixture has no site config at all), so with nothing to interpolate the prompt is just Deploy site?. That's a missing directory name, not a second kind of deploy.

---

Generated by Claude Code

[netanelgilad]

I dont think we need to code flow to start separating here based on fullstack / static.
inside deploytoDEplymentsApi we should check if there is a user worker to also deploy and decide internally what to add to the createDeployment call, but the bottom line is that we sdhould have a single call to createDeployment in the code, it's jsut the paramters to it that changes based on what we have to deploy

[netanelgilad]

Agreed, and done — there is now one flow and one createDeployment() call site.

core/site/full-stack.ts and core/site/static-site.ts are gone, replaced by core/site/deployment.ts with a single deployToDeployments({projectRoot, outputDir, gitHash, ...}). It checks for a worker itself, and that only changes what it sends:

const worker = await resolveWorkerBuild(projectRoot, progress);   // null = no worker
const assetsDir = worker ? worker.assetsDir : outputDir;
const assets = assetsDir ? await buildAssetManifest(assetsDir, appId) : NO_ASSETS;

const created = await createDeployment({
  git_hash: gitHash,
  config: worker?.config,          // presence is what selects the storage target
  asset_manifest: assets.manifest,
});

Two more forks collapsed on the way, both for the same reason — they were us deciding something the server had already decided:

• Upload: uploadDeploymentAssets(created.assetUploads, assets, …) dispatches on the asset_uploads discriminant and returns the completion token when that arm has one. It also owns the "Found N static assets (M new)" progress, since counting what's owed is per-arm. The two assetUploads.type !== "cf"/"s3" guards each flow used to raise are deleted: with one dispatch there is no wrong arm to reject.
• Finalize: one finalizeDeployment(deploymentId, sessionId, payload), where payload is {modules, completionJwt} or {indexHtml}. The remaining if is inside api.ts building the multipart form — that difference is the wire protocol (a worker completes with its modules, a static build with the index.html sentinel), not a flow choice, and the bytes on both arms are unchanged.

The command is down to one call: planAppDeploy() now returns deployment | tarball | none (the two deployments kinds merged), so site deploy has a 3-arm switch with a single deployToDeploymentsApi(), and its runDeployTask wrapper is inlined now that there's one caller. A worker build stays ungated and needs no site.outputDirectory.

Net −23 lines. static_site_deployments.spec.ts already asserted both parameter shapes of that one call — expect(body).not.toHaveProperty("config") on the static arm, body.config.main on the worker arm — so the contract you described is locked in by tests. Full suite: 732 passed, all 296 deploy + core tests green, typecheck/lint/knip clean.

---

Generated by Claude Code