feat: publish an app as a recorded version

[yurynix]

Note

Description

Adds a versions lane to the CLI: a version is one immutable record of everything a build produced — every frontend file, the app's own Worker when the framework built one, and the raw entity and agent payloads the app declares — and a deployment is that version made live at an environment. Recording and serving are separate acts, which makes a rollback a deploy of an older version rather than a second code path. The lane ships as base44 publish, base44 versions create and base44 versions deploy <version-id>, all gated behind BASE44_VERSIONS_API so they are not registered at all until the platform side is ready. It exists to replace the python driver the platform's build sandbox runs today — which overwrote base44/config.jsonc with a minimal config before building, destroying checked-in configuration.

Related Issue

None

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

New src/core/version/ module

• api.ts — the three HTTP calls, in order: POST versions (declare the artifact set, get a session_id and one presigned PUT per file) → upload → POST versions/{session_id}/finalize. Nothing is recorded until the bytes are in place, so an interrupt leaves staged objects that expire rather than a version naming files that are not there. Uploads pair with declared files by position — the frontend then the Worker's modules, the order the server signed them in — because the two sets are separate namespaces and the same path can appear in both. setEnvironmentVersion is one PATCH /environments/{name} with an idempotency key: an environment serves one version, so making a version live is editing that pointer.
• artifacts.ts — walks the build output and streams a full sha256: digest per file (bounded at 32 open descriptors); collectSiteWorker detects a full-stack build and describes its modules the same way, reusing the existing full-stack deploy lane's detectFullStackArtifact / resolveWranglerConfig / collectModules whole rather than reading the framework's output a second time; and reads entities//agents/ raw, keyed the way the platform names them (agents/support/triage.jsonc → support/triage). Deliberately not the validated resource readers: the CLI's stricter entity schema refuses real Builder apps. Refuses an empty set, a set with no index.html, and more than MAX_FILE_COUNT (50 000, matching the server's ceiling).
• publish.ts — orchestration, plus tagStep/stepOf: attaches build / create_version / deploy to a failure through a non-enumerable symbol, leaving the original error type, message, status and request id intact. Base44Command writes it into the --json error envelope as step.
• project.ts — resolvePublishTarget fills in npm run build and dist only when a repo has no config at all, and writes nothing. A config that is present wins field by field; one that omits a field still gets today's error. requireOutputDir raises at collection, not resolution.
• gate.ts — versionsApiEnabled(), read in exactly one place (program.ts). Separate from BASE44_DEPLOYMENTS_API so the two lanes can roll out apart.
• schema.ts — Zod wire schemas with snake_case→camelCase transforms; a response mismatch raises SchemaValidationError naming the field.

Full-stack apps — when .wrangler/deploy/config.json is present, the version declares a site_worker (entry module, module set with digests, compatibility_date, compatibility_flags) alongside the frontend, and the frontend is taken from the Worker's own assets.directory rather than the project's site.outputDirectory. main is sent as the module set names it, resolved by identity, so a surviving ./ cannot name a module the set does not provide. Nothing deploys this yet — the platform stores it and still refuses a full-stack app at admission — so this is the transport, sent and stored.

New commands (publish.ts, versions/{create,deploy,index,options}.ts) — shared flags (--output-dir, --target, --git-hash, --concurrency) built in one place so two --help screens cannot describe the same flag differently. --concurrency defaults to 8 and caps at 16; --json emits a single {versionId, manifestHash, deploymentId} document via RunCommandResult.stdout.

Shared with the existing site lane

• Extracted walkBuildOutput() from buildAssetManifest so both lanes apply one rule for what a build produced (.assetsignore semantics + always-ignored names).
• Extracted putPresigned() from uploadPresignedAsset so both lanes share one PUT while each decides which file a signed URL is for (the site lane by path, the version lane by declared order). It forwards the server's x-amz-checksum-sha256 verbatim when present, which is what makes S3 itself reject a body other than the declared one. AssetFile.contentType became optional — only the cf arm reads it, the s3 arm echoes what the server signed.
• Added resolveProvenanceCommit(): returns undefined outside a checkout, because a version is identified by its content and the commit is recorded beside it, never hashed.

base44 build — no longer requires a credential (it calls no API, and the sandbox builds before minting a key that can deploy) and no longer requires a linked CLI config; it resolves through resolvePublishTarget. What it builds and prints is unchanged.

Docs — new docs/versions.md (linked from docs/AGENTS.md) covering the two-hashes distinction, the declare→upload→finalize order, why the digest is signed into the URL, the full-stack Worker, raw resource payloads, the measured concurrency and file-count bounds, the env gate, and the sandbox's two-exec invocation.

Testing

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

4 new spec files plus additions to build.spec.ts (~785 lines): end-to-end publish coverage (digests declared, resources sent raw, checksum header forwarded, environment named in the path and version in the body, --json envelope, step tagging, --no-build), a full-stack app (Worker declared in the same version, frontend taken from the Worker's assets directory, each declared file's own bytes at the URL signed for it), gate on/off/--help, artifact collection (nested paths, .assetsignore, descriptor exhaustion on a large set, missing entry point, module set vs. assets), publish-target resolution (including "writes nothing" and "leaves a checked-in config exactly as it was"), and tagStep semantics. Testkit gained PATCH routing, mockVersionDeclare/mockVersionFinalize/mockEnvironmentSet/mockVersionDeclareError with request capture, and a publishable fixture. Unchecked boxes are not claims of failure — this description was generated in an environment that could not execute the suite; CI is the source of truth.

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

The lane is inert until BASE44_VERSIONS_API=1, so nothing here is reachable by a user on this release. Three things worth a reviewer's attention: the base44 build auth relaxation is the one change visible outside the gate; AssetFile.contentType becoming optional and the putPresigned extraction touch the existing site deploy lane; and the full-stack Worker declaration is transport only, with no platform arm behind it yet. The .gitignore additions (pr-review-*.md/.html) are local review scratch files.

---

_{🤖 Generated by Claude | 2026-09-16 11:08 UTC | 451886c}

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/cli@0.1.15-pr.626.da7a7d8

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.15-pr.626.da7a7d8"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/cli@0.1.15-pr.626.da7a7d8"
  }
}

• 📦 Preview Package: @base44-preview/cli@0.1.15-pr.626.da7a7d8
• 🔗 View this commit on GitHub

---

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

[netanelgilad]

why both?
and source_commit should be optional (for BaaS)

[yurynix]

Done in fe5c313. frontend_commit is gone from the wire, the session, the contract and the log — a version describes an app at a source, and its frontend and backend are that same app. build still refuses two inputs naming different commits, which is what earns the single field. And source_commit was already optional server-side (str | None); it stays that way, so a build outside a checkout is still a complete version.

[netanelgilad]

let's make it an API on an Environment object
PATCH /environments/
{ version: ... }

[yurynix]

Done in fe5c313 — agreed, this is the truer model. PATCH /environments/{name} { version_id } replaces POST /versions/{id}/deployments, on its own router rather than under versions, since an environment outlives every version it has pointed at. The Deployment record still exists internally (it is what the conditional pointer write points at) and comes back in the response so a log line can be correlated — but nobody asks for one.

[netanelgilad]

check how to reduce duplication here with the deployments api code

[yurynix]

Done in 3fddea1. It was worse than similar: my collector had its own copy of the globby call, the .assetsignore handling, the ALWAYS_IGNORED set and even the comment about globby's ignore/ignoreFiles footgun. Two collectors disagreeing would mean the two lanes publish different sets from the same directory. walkBuildOutput in core/site/manifest.ts is now the one rule; both callers use it and do their own per-file work. The hashes stay separate deliberately — hashAsset is a salted, truncated provider cache key, digestFile is full sha256 artifact identity.

[netanelgilad]

remove these files

[yurynix]

Done in 3fddea1 — my mistake, those were local review artifacts. Untracked and added to .gitignore.