feat: publish an app as a recorded version

[yurynix]

Note

Description

Adds the versions lane: a build can be recorded as an immutable version (every frontend file plus the app's raw entity and agent payloads) and then served by pointing an environment at it. Recording and serving are separate acts, so a rollback is just a deploy of an older version rather than a second code path. The whole lane — base44 publish, base44 versions create, base44 versions deploy — is registered only when BASE44_VERSIONS_API=1, so with the gate off the commands are absent from --help and rejected as unknown. This replaces a python driver in the platform's build sandbox that used to overwrite base44/config.jsonc 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 core/version/ module

• api.ts — the three-call flow: declare (POST versions) → upload presigned PUTs → finalize (POST versions/{session}/finalize), in that order so nothing is recorded until the bytes are in place. Uploads are paired to declared files by position (frontend files, Worker modules and Worker assets are separate namespaces, so a path can repeat), with count and order-drift guards before the first PUT. setEnvironmentVersion is one PATCH /environments/{name} carrying an idempotency key, with a keyed retry policy that also retries on client-side timeout — our own deadline expiring says nothing about whether the server committed.
• artifacts.ts — one collectArtifacts reader for both publish and versions create; streams a full sha256 digest per file (bounded fan-out, HASH_CONCURRENCY = 32), enforces MAX_FILE_COUNT = 50_000 to match the server, and reads entities//agents/ raw (the CLI's stricter entity schema refuses real Builder apps, so the platform's validation stays authoritative).
• publish.ts — orchestration plus the build / create_version / deploy step vocabulary; schema.ts — Zod-validated wire types with snake_case→camelCase transforms; gate.ts — BASE44_VERSIONS_API, read in exactly one place (program.ts).

Full-stack (Worker) apps

• A version declares either static_bundle or site_worker — never both. site_worker carries main (resolved to the module-set name, not the config's ./-prefixed path), the typed module set, its own assets, compatibility_date/compatibility_flags and a collapsed assets_config. No entry-file rule for a Worker: its not_found_handling answers unmatched paths, and a Worker with zero assets is a complete app.
• Extracted resolveFullStackBuild into core/site/full-stack.ts so the deploy lane and the version lane share one reader of .wrangler/deploy/config.json.

New commands (gated)

• base44 publish [--no-build] [--output-dir] [--target] [--git-hash] [--concurrency] — build, record, serve; --json emits {environment, versionId, manifestHash, deploymentId}.
• base44 versions create — record built output without serving it.
• base44 versions deploy <version-id> — point an environment at a recorded version (also the rollback). Shared flags are built once in versions/options.ts with validating arg parsers.

Supporting changes

• core/project/target.ts — resolveBuildTarget/requireOutputDir: defaults (npm run build, dist) apply only when a repo has no config at all, and nothing is written to disk. A present config wins field by field.
• base44 build now resolves through resolveBuildTarget and requires no credential (the sandbox builds before minting a publish-capable key); a missing app id is no longer silently defaulted to "".
• core/errors.ts — tagStep/stepOf: tags an error with its step via a non-enumerable symbol without wrapping it (innermost tag wins, respects non-extensible errors), and Base44Command writes it into the --json error envelope as step.
• requireApp(ctx) middleware helper narrows the optional CLIContext.app instead of defaulting at call sites.
• core/site/manifest.ts — extracted describeBuildOutput (one walk, .assetsignore semantics, bounded stat fan-out) and hashFileInto; the two lanes' hashes stay deliberately distinct (truncated salted upload key vs. full content digest).
• core/site/upload.ts — extracted putPresigned, which now forwards the server's x-amz-checksum-sha256 verbatim when present (optional, since the legacy static lane's URLs pin only type and length).
• resolveProvenanceCommit in core/site/git-hash.ts returns undefined outside a checkout — for a version the commit is provenance, not identity.
• Docs: new docs/versions.md (linked from docs/AGENTS.md) covering the two hashes, the flow, the static/full-stack split, the Worker's identity fields, concurrency measurements, the file-count ceiling, the env gate and the sandbox's two-exec usage. .gitignore picks up local pr-review-* artifacts.

Testing

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

66 new specs across ~1,300 lines: tests/cli/publish.spec.ts (digests, raw resources, checksummed uploads, request-body shape, --json envelope, step tagging, gate on/off), tests/core/version-artifacts.spec.ts, version-api.spec.ts, version-publish.spec.ts, version-gate.spec.ts, project-target.spec.ts, site-full-stack.spec.ts, require-app.spec.ts (all under tests/core/), plus a base44 build case covering the no-credential path, TestAPIServer mocks for declare/finalize/environment (and PATCH support), and a new fixtures/publishable project.

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

• Nothing user-facing ships here. With BASE44_VERSIONS_API unset the new commands are not registered at all. The one behaviour change outside the gate is base44 build: it no longer requires auth, and it now resolves its config through resolveBuildTarget, so a repo with no base44/ config builds with npm run build instead of erroring. What it builds and prints for a configured project is unchanged.
• The gate is deliberately not BASE44_DEPLOYMENTS_API, which selects the legacy transport for site deploy and is already set in the sandbox — one var switching both lanes could not be rolled out apart.
• Full-stack publish is transport-only for now: the platform records the Worker and stores its modules, but refuses a full-stack app at admission. The companion server change accepting the typed module set and assets_config is apper#24525, and the request models forbid unknown fields — so the two land together or the declare 400s.
• Upload concurrency defaults to 8 (max 16), measured on the sandbox's pipe: at 3, a 25.5k-asset app needed ~930s of the ~450s a build leaves and was SIGKILLed mid-upload.
• CI is green: lint, typecheck, build, knip, publish-preview, functions-compiler, claude-review and all four test matrix jobs (ubuntu/windows × npm/binary) pass. Lint keeps one pre-existing informational diagnostic in miniflare-function-manager.ts, untouched by this branch.

---

_{🤖 Generated by Claude | 2026-09-22 11:07 UTC | e28b7e8}

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/cli@0.1.17-pr.626.a210a49

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.17-pr.626.a210a49"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/cli@0.1.17-pr.626.a210a49"
  }
}

• 📦 Preview Package: @base44-preview/cli@0.1.17-pr.626.a210a49
• 🔗 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.

[yurynix]

assets: artifacts.siteWorker.assets.map(declaredFile),
Can it actually replace static_bundle: artifacts.files.map(declaredFile),
and let the server handle that differently if it needs to, but we should have "assets" and optionally, may have a "site_worker" to come along with it.

Backend functions, although they are also workers, are different and are not related to that.