create-cartbase 0.1.16 → 0.1.17

package/template/app/docs/deploy.md

@@ -1,197 +1,197 @@
-# Deploy
-
-Cartbase builds and hosts your storefront. You send the app's source files
-— one snapshot of the whole project — and Cartbase turns it into a
-running site: first on a **permanent preview URL**, then, when you press
-**Publish** (or call the publish endpoint), on the store's live domain.
-You never touch build servers, DNS, or hosting configuration; the platform
-provisions all of it the moment the store is created, and makes the first
-deploy itself: the store's starting point, a complete storefront on your
-own (still empty) catalog, already running on the preview link. Pull it
-with the CLI, change anything, deploy it back.
-
-Two URLs exist per store, both created automatically:
-
-| Surface | URL | What serves there |
-|---|---|---|
-| Preview | `https://preview--{store-slug}.cartbase.net` | The newest deploy, always — the link never changes |
-| Live | `https://{store-slug}.cartbase.net` | The last **published** deploy, and nothing else |
-
-A failed build never replaces what's live or what's on preview — the
-previous successful deploy keeps serving. Custom domains for the live site
-attach in the admin (Settings → Domains) and don't change anything on this
-page.
-
-**These are Admin API endpoints** — they operate the store, so they
-authenticate with an admin session (sign-in cookie), not the storefront
-headers the rest of this corpus uses. In practice you'll deploy through
-the admin UI (**Storefront** in the sidebar), the Cartbase CLI, or an
-agent connection — all three are wrappers over exactly these calls.
-Users who belong to several stores name the target store with an
-`x-cartbase-store: <client-id>` header.
-
-## What a deploy is
-
-A deploy is a **full snapshot**: the complete file tree of your storefront
-app, uploaded in one request. Snapshot semantics cut both ways — a file
-you stop sending is removed from the deployed site. There is no
-partial-update mode; your working directory is the truth, every time.
-
-Bundle rules (enforced server-side; a violation fails the whole deploy
-with a readable `400` before anything is built):
-
-- ≤ 1500 files, ≤ 3 MB per file, ≤ 25 MB total (base64-decoded sizes)
-- `package.json` must exist at the bundle root — the app must be a
-  buildable Next.js project (`next build`)
-- File content travels base64-encoded (`content_base64`), so binary
-  assets — images, fonts — work
-- Never include: `node_modules/` (dependencies install at build time),
-  `.next/` (build output is generated), `.git/`, any `.env*` file
-- Not allowed in storefront bundles: `middleware.*`, `app/api/` or
-  `pages/api/` routes, `vercel.json` — a storefront is pages plus the
-  `@cartbase/storefront` package; server seams and hosting config are
-  platform territory. The CORS proxy from the runbook is a
-  `next.config` rewrite, which is fine.
-
-Error codes you can hit: `empty_bundle`, `bundle_too_large`,
-`invalid_bundle_file`, `invalid_path`, `blocked_path`, `duplicate_path`,
-`invalid_encoding`, `file_too_large`, `missing_package_json`.
-
-## Environment — provided, not configured
-
-Hosted storefronts receive their store's values automatically at build
-time; do **not** put them in the bundle (`.env*` files are blocked
-anyway):
-
-| Variable | Value |
-|---|---|
-| `NEXT_PUBLIC_CARTBASE_PUBLISHABLE_KEY` | The store's publishable key, the one input a storefront needs |
-| `NEXT_PUBLIC_CARTBASE_URL` | The platform origin (a constant; injected so a hosted build never guesses) |
-| `NEXT_PUBLIC_CARTBASE_CLIENT_ID` | The store's id, the platform's own door; a storefront never needs to copy it |
-
-Only these public values ever reach a storefront build — secret keys are
-never injected, so code that expects one is a design error.
-
-## Deploy to preview
-
-`POST /api/admin/storefront/deploys` — the one ingestion door. Hosting is
-provisioned when the store is born, so every call is just a deploy; on a
-store whose hosting setup failed, the first call resumes it (a few extra
-seconds).
-
-```bash
-# doc-noexec — admin-session auth; run from an authenticated context.
-curl -s -X POST "$BASE/api/admin/storefront/deploys" \
-  -H "content-type: application/json" \
-  -d '{
-    "files": [
-      { "path": "package.json",  "content_base64": "<base64>" },
-      { "path": "app/layout.js", "content_base64": "<base64>" },
-      { "path": "app/page.js",   "content_base64": "<base64>" }
-    ],
-    "message": "homepage copy update"
-  }'
-```
-
-Response `201`:
-
-```json
-{
-  "deploy": {
-    "id": "sfd_01J…",
-    "target": "preview",
-    "status": "building",
-    "url": "https://preview--my-store.cartbase.net",
-    "message": "homepage copy update",
-    "file_count": 3,
-    "created_at": "2026-08-03T22:41:00.000Z"
-  }
-}
-```
-
-`message` (≤ 500 chars) is your label in the deploy history — write what
-changed. `source` (`api` | `cli` | `mcp` | `admin` | `agent`) tags where
-the deploy came from; omit it unless you're building tooling.
-
-Statuses move `queued → building → ready` (or `failed` / `canceled`).
-Poll the overview endpoint until the deploy you created is `ready`, then
-open the preview URL. Builds of a small app land in roughly a minute;
-`failed` rows carry a readable `error_message`.
-
-## Overview — hosting status + deploy history
-
-`GET /api/admin/storefront` returns the hosting record and the deploy
-ledger, newest first:
-
-```bash
-# doc-noexec — admin-session auth.
-curl -s "$BASE/api/admin/storefront"
-```
-
-```json
-{
-  "storefront": {
-    "id": "sfp_01J…",
-    "status": "ready",
-    "production_url": "https://my-store.cartbase.net",
-    "preview_url": "https://preview--my-store.cartbase.net",
-    "last_error": null,
-    "created_at": "…"
-  },
-  "deploys": [
-    {
-      "id": "sfd_01J…",
-      "target": "preview",
-      "status": "ready",
-      "message": "homepage copy update",
-      "url": "https://preview--my-store.cartbase.net",
-      "source": "cli",
-      "file_count": 3,
-      "total_bytes": 1930,
-      "error_message": null,
-      "promoted_deploy_id": null,
-      "created_at": "…",
-      "updated_at": "…"
-    }
-  ]
-}
-```
-
-`storefront` is present from the store's birth (`null` only on a store
-created before hosting-at-birth that has never deployed). `status:
-"provisioning"` / `"failed"` (with `last_error`) describe hosting setup,
-not builds; a failed provisioning resumes automatically on the next
-deploy attempt.
-
-## Publish — and rollback
-
-`POST /api/admin/storefront/publish` promotes a **ready preview deploy**
-to the live domain. This is the only path to production — nothing
-deploys straight to live, no matter who's asking.
-
-```bash
-# doc-noexec — admin-session auth.
-# Bare POST publishes the newest ready preview:
-curl -s -X POST "$BASE/api/admin/storefront/publish"
-
-# Naming an older deploy id IS the rollback mechanism:
-curl -s -X POST "$BASE/api/admin/storefront/publish" \
-  -H "content-type: application/json" \
-  -d '{ "deploy_id": "sfd_01H…older…" }'
-```
-
-Response `201` is a new ledger row with `target: "production"` and
-`promoted_deploy_id` pointing at the preview it promoted. Publishing is
-near-instant — the snapshot was already built; the live domain switches
-to it without a rebuild.
-
-Rollback is not a separate feature: publish any earlier `ready` deploy
-from the history and the live site is that snapshot again. Roll forward
-the same way.
-
-## Workflow summary
-
-1. Build locally against your store (the [runbook](BUILD-A-STOREFRONT.md)).
-2. Deploy → check the permanent preview URL.
-3. Iterate — every deploy replaces preview, live is untouched.
-4. Publish when it's right; the deploy history is your undo button.
+# Deploy
+
+Cartbase builds and hosts your storefront. You send the app's source files
+— one snapshot of the whole project — and Cartbase turns it into a
+running site: first on a **permanent preview URL**, then, when you press
+**Publish** (or call the publish endpoint), on the store's live domain.
+You never touch build servers, DNS, or hosting configuration; the platform
+provisions all of it the moment the store is created, and makes the first
+deploy itself: the store's starting point, a complete storefront on your
+own (still empty) catalog, already running on the preview link. Pull it
+with the CLI, change anything, deploy it back.
+
+Two URLs exist per store, both created automatically:
+
+| Surface | URL | What serves there |
+|---|---|---|
+| Preview | `https://preview--{store-slug}.cartbase.net` | The newest deploy, always — the link never changes |
+| Live | `https://{store-slug}.cartbase.net` | The last **published** deploy, and nothing else |
+
+A failed build never replaces what's live or what's on preview — the
+previous successful deploy keeps serving. Custom domains for the live site
+attach in the admin (Settings → Domains) and don't change anything on this
+page.
+
+**These are Admin API endpoints** — they operate the store, so they
+authenticate with an admin session (sign-in cookie), not the storefront
+headers the rest of this corpus uses. In practice you'll deploy through
+the admin UI (**Storefront** in the sidebar), the Cartbase CLI, or an
+agent connection — all three are wrappers over exactly these calls.
+Users who belong to several stores name the target store with an
+`x-cartbase-store: <client-id>` header.
+
+## What a deploy is
+
+A deploy is a **full snapshot**: the complete file tree of your storefront
+app, uploaded in one request. Snapshot semantics cut both ways — a file
+you stop sending is removed from the deployed site. There is no
+partial-update mode; your working directory is the truth, every time.
+
+Bundle rules (enforced server-side; a violation fails the whole deploy
+with a readable `400` before anything is built):
+
+- ≤ 1500 files, ≤ 3 MB per file, ≤ 25 MB total (base64-decoded sizes)
+- `package.json` must exist at the bundle root — the app must be a
+  buildable Next.js project (`next build`)
+- File content travels base64-encoded (`content_base64`), so binary
+  assets — images, fonts — work
+- Never include: `node_modules/` (dependencies install at build time),
+  `.next/` (build output is generated), `.git/`, any `.env*` file
+- Not allowed in storefront bundles: `middleware.*`, `app/api/` or
+  `pages/api/` routes, `vercel.json` — a storefront is pages plus the
+  `@cartbase/storefront` package; server seams and hosting config are
+  platform territory. The CORS proxy from the runbook is a
+  `next.config` rewrite, which is fine.
+
+Error codes you can hit: `empty_bundle`, `bundle_too_large`,
+`invalid_bundle_file`, `invalid_path`, `blocked_path`, `duplicate_path`,
+`invalid_encoding`, `file_too_large`, `missing_package_json`.
+
+## Environment — provided, not configured
+
+Hosted storefronts receive their store's values automatically at build
+time; do **not** put them in the bundle (`.env*` files are blocked
+anyway):
+
+| Variable | Value |
+|---|---|
+| `NEXT_PUBLIC_CARTBASE_PUBLISHABLE_KEY` | The store's publishable key, the one input a storefront needs |
+| `NEXT_PUBLIC_CARTBASE_URL` | The platform origin (a constant; injected so a hosted build never guesses) |
+| `NEXT_PUBLIC_CARTBASE_CLIENT_ID` | The store's id, the platform's own door; a storefront never needs to copy it |
+
+Only these public values ever reach a storefront build — secret keys are
+never injected, so code that expects one is a design error.
+
+## Deploy to preview
+
+`POST /api/admin/storefront/deploys` — the one ingestion door. Hosting is
+provisioned when the store is born, so every call is just a deploy; on a
+store whose hosting setup failed, the first call resumes it (a few extra
+seconds).
+
+```bash
+# doc-noexec — admin-session auth; run from an authenticated context.
+curl -s -X POST "$BASE/api/admin/storefront/deploys" \
+  -H "content-type: application/json" \
+  -d '{
+    "files": [
+      { "path": "package.json",  "content_base64": "<base64>" },
+      { "path": "app/layout.js", "content_base64": "<base64>" },
+      { "path": "app/page.js",   "content_base64": "<base64>" }
+    ],
+    "message": "homepage copy update"
+  }'
+```
+
+Response `201`:
+
+```json
+{
+  "deploy": {
+    "id": "sfd_01J…",
+    "target": "preview",
+    "status": "building",
+    "url": "https://preview--my-store.cartbase.net",
+    "message": "homepage copy update",
+    "file_count": 3,
+    "created_at": "2026-08-03T22:41:00.000Z"
+  }
+}
+```
+
+`message` (≤ 500 chars) is your label in the deploy history — write what
+changed. `source` (`api` | `cli` | `mcp` | `admin` | `agent`) tags where
+the deploy came from; omit it unless you're building tooling.
+
+Statuses move `queued → building → ready` (or `failed` / `canceled`).
+Poll the overview endpoint until the deploy you created is `ready`, then
+open the preview URL. Builds of a small app land in roughly a minute;
+`failed` rows carry a readable `error_message`.
+
+## Overview — hosting status + deploy history
+
+`GET /api/admin/storefront` returns the hosting record and the deploy
+ledger, newest first:
+
+```bash
+# doc-noexec — admin-session auth.
+curl -s "$BASE/api/admin/storefront"
+```
+
+```json
+{
+  "storefront": {
+    "id": "sfp_01J…",
+    "status": "ready",
+    "production_url": "https://my-store.cartbase.net",
+    "preview_url": "https://preview--my-store.cartbase.net",
+    "last_error": null,
+    "created_at": "…"
+  },
+  "deploys": [
+    {
+      "id": "sfd_01J…",
+      "target": "preview",
+      "status": "ready",
+      "message": "homepage copy update",
+      "url": "https://preview--my-store.cartbase.net",
+      "source": "cli",
+      "file_count": 3,
+      "total_bytes": 1930,
+      "error_message": null,
+      "promoted_deploy_id": null,
+      "created_at": "…",
+      "updated_at": "…"
+    }
+  ]
+}
+```
+
+`storefront` is present from the store's birth (`null` only on a store
+created before hosting-at-birth that has never deployed). `status:
+"provisioning"` / `"failed"` (with `last_error`) describe hosting setup,
+not builds; a failed provisioning resumes automatically on the next
+deploy attempt.
+
+## Publish — and rollback
+
+`POST /api/admin/storefront/publish` promotes a **ready preview deploy**
+to the live domain. This is the only path to production — nothing
+deploys straight to live, no matter who's asking.
+
+```bash
+# doc-noexec — admin-session auth.
+# Bare POST publishes the newest ready preview:
+curl -s -X POST "$BASE/api/admin/storefront/publish"
+
+# Naming an older deploy id IS the rollback mechanism:
+curl -s -X POST "$BASE/api/admin/storefront/publish" \
+  -H "content-type: application/json" \
+  -d '{ "deploy_id": "sfd_01H…older…" }'
+```
+
+Response `201` is a new ledger row with `target: "production"` and
+`promoted_deploy_id` pointing at the preview it promoted. Publishing is
+near-instant — the snapshot was already built; the live domain switches
+to it without a rebuild.
+
+Rollback is not a separate feature: publish any earlier `ready` deploy
+from the history and the live site is that snapshot again. Roll forward
+the same way.
+
+## Workflow summary
+
+1. Build locally against your store (the [runbook](BUILD-A-STOREFRONT.md)).
+2. Deploy → check the permanent preview URL.
+3. Iterate — every deploy replaces preview, live is untouched.
+4. Publish when it's right; the deploy history is your undo button.