feat: static-site deploys through the deployments API (s3 arm, env-gated)

[netanelgilad]

Note

Description

Adds an env-gated lane for deploying a site's built output through the new deployments API, alongside the existing tar.gz upload. The output directory is hashed into a content-addressed asset manifest, the deployment is created at the commit's address (git_hash), only the assets the server still owes are PUT directly to presigned S3 URLs, and index.html is sent as the finalize sentinel. The lane is reachable only from base44 site deploy --git-hash <commit> and only when BASE44_STATIC_DEPLOYMENTS=1; with the gate off, behavior is unchanged from the legacy path.

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

Core (src/core/site/)

• manifest.ts — walks the output directory with globby (dotfiles included, symlinks not followed), honors .assetsignore via globby's ignoreFiles for real gitignore semantics (anchoring, directory patterns, negation), and hashes each file as the first 32 hex chars of sha256(utf8(app_id) || bytes). The app-id salt means a tenant can only collide with its own files. Caps: 25 MiB per file (stat before read), 100,000 files.
• static-site.ts — the flow: build manifest → fail early if there is no /index.html → createDeployment() → upload owed assets → finalize with the index.html bytes.
• upload.ts — presigned PUTs via plain ky (no app client, no auth headers — the URL is the credential), echoing the server-signed Content-Type verbatim, 3 attempts with exponential backoff, concurrency via p-map (default 3, max 50).
• api.ts / schema.ts — POST deployments and POST deployments/{id}/finalize with Zod snake_case→camelCase transforms; asset_uploads is modeled as a discriminated ADT ({type: "s3", ...} or null) so a worker arm can slot in later without protocol changes.
• utils/git.ts — isGitCommitHash(), matching the server's ^[a-fA-F0-9]{7,64}$.

CLI (site deploy)

• --git-hash <hash> and --concurrency <n> are registered only when BASE44_STATIC_DEPLOYMENTS is 1/true, so with the gate off the flags are absent from --help and rejected as unknown options. Both validate in Commander argParsers, before the action runs.
• The action forks on options.gitHash: present → deployStaticSite(), absent → the legacy deploySite() tar.gz upload. Each branch owns its spinner labels and result shape; --json emits {deploymentId, gitHash}.
• base44 deploy (unified) is untouched — it still ships the site through the legacy tar.gz step, gate on or off.

Deps / repo

• Adds p-map, bumps globby to ^16.2.2 (for ignoreFiles), both in devDependencies per the bundled-distribution rule.
• .gitattributes pins test fixtures to LF so content-addressed hashes don't shift on Windows checkouts.

Docs

• New docs/deployments.md topic guide (contract, hashing, gate, rules), linked from docs/AGENTS.md; updates to docs/resources.md (two site transports) and docs/testing.md (deployment mocks).

Testing

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

New coverage:

• tests/cli/static_site_deployments.spec.ts (11 cases) — gate off hides and rejects --git-hash/--concurrency; gate off and gate-on-without-commit both keep the legacy tar.gz upload; full happy path asserting the create body (git_hash, manifest keys, no config), presigned bodies byte-for-byte with the signed Content-Type and no Authorization header, and a single-field index.html multipart finalize; asset_uploads: null sends no PUTs but still finalizes; --json shape; invalid --git-hash and out-of-range --concurrency.
• tests/core/site-manifest.spec.ts (12 cases) — hash formula and app-id salting, manifest key/shape, .assetsignore globs/negation/anchoring/literal braces, dotfiles, always-ignored names, the 25 MiB limit, and hash dedupe.
• TestAPIServer gains mockDeploymentCreate, mockPresignedUpload, mockDeploymentFinalize with request capture.

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 experimental and off by default: nothing about it surfaces until BASE44_STATIC_DEPLOYMENTS is set. A deployment addresses a build, not production — there is no --prod, promote, rollback, or list surface; publishing stays with the platform. Deployment ids are derived from git_hash, so re-deploying a commit is idempotent. Adopting the lane in base44 deploy is a deliberate follow-up.

---

_{🤖 Generated by Claude | 2026-08-04 05:36 UTC | ca3aebe}

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/cli@0.1.7-pr.585.ca3aebe

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.7-pr.585.ca3aebe"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/cli@0.1.7-pr.585.ca3aebe"
  }
}

• 📦 Preview Package: @base44-preview/cli@0.1.7-pr.585.ca3aebe
• 🔗 View this commit on GitHub

---

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