@tomorrowos/sdk 0.9.27 → 0.9.28

package/VERCEL_SETUP.md

@@ -5,7 +5,7 @@
 >
 > **On Vercel, this file is the setup questionnaire** (not `REPLIT_SETUP.md`, not `LLM_PROMPT.md`).
 >
-> Protocol id: `vercel-setup/1.6` — pairs with `@tomorrowos/sdk` packages that ship `templates/cms-starter` and this file.
+> Protocol id: `vercel-setup/1.7` — pairs with `@tomorrowos/sdk` packages that ship `templates/cms-starter` and this file.
 
 ## User trigger (copy-paste)
 
@@ -19,7 +19,8 @@ If any step contradicts Vercel, adapt to settings Vercel can accept (document th
 After all setup questions are answered (including Cloudinary or Vercel Blob Env Vars if you chose those), configure and deploy — minimal verification only (Control Panel at /). Prefer Supabase Session pooler URL or Neon pooled URL. Do not treat sandbox ENETUNREACH / IPv6 :5432 errors as a hard setup failure when a pooler URL is configured for production.
 Question 3 only updates brand.json from colours/logo/name (a website URL is brand reference only — do not add CMS login/auth unless the user explicitly asks). Do not skip steps.
 Use Next.js only as a v0/Preview shell with a reverse proxy; Production Publish must remain pure Node TomorrowOS.listen (not Next).
-Before claiming Publish works: Framework Preset must be Other/null (not Next.js), startCommand must run TomorrowOS Node, GET /status on the production URL must return JSON (not HTML), and GET / must return the Control Panel (not 404 NOT_FOUND).
+Before claiming Publish works: Framework Preset must be Other/null (not Next.js), package.json `start` must run TomorrowOS Node, GET /status on the production URL must return JSON (not HTML), and GET / must return the Control Panel (not 404 NOT_FOUND).
+Do not put startCommand or processes in vercel.json (v0 schema rejects them). Do not move server.ts into api/.
 ```
 
 Alternate triggers:
@@ -252,14 +253,21 @@ Use the pattern in **Runtime & Vercel deploy rules** below. On Publish, **do not
 
 ### A3 — `vercel.json` (Production)
 
+**v0 / `.v0/vercel.deploy.json` schema:** only a **minimal** object is valid. These keys are **rejected** — never add them:
+
+- ❌ `startCommand`
+- ❌ `processes`
+- ❌ `routes` / `rewrites` to fake API routing
+- ❌ `outputDirectory: "public"` or `"."`
+
+Vercel discovers the start command from **`package.json` → `"start": "tsx server.ts"`**, not from `vercel.json`.
+
 ```json
 {
   "fluid": true,
   "framework": null,
   "installCommand": "npm install",
-  "buildCommand": "npm run build",
-  "startCommand": "npm run start",
-  "outputDirectory": null
+  "buildCommand": "npm run build"
 }
 ```
 
@@ -267,9 +275,10 @@ Use `pnpm` / `yarn` equivalents if the project uses them.
 
 **Critical:**
 
-- `"outputDirectory": null` — **never** `"public"`, `"."`, or `"public if exists"`
-- `"startCommand"` must be explicit when the dashboard keeps defaulting to static
-- `"buildCommand"` must be the no-op `npm run build` — **never** `next build` for Production
+- **Do not** add `startCommand` to `vercel.json` (invalid in v0; redundant on full Vercel — use `package.json` `start`)
+- **Do not** set `outputDirectory` to `public` or `.`
+- `"buildCommand"` must run the no-op `npm run build` — **never** `next build` for Production
+- Set **Output Directory empty** in the **Vercel dashboard** (Scheme A4) — that is where static-vs-Node is decided, not via invalid `vercel.json` keys
 
 ### A4 — Vercel Project Settings (dashboard or API — mandatory)
 
@@ -294,14 +303,43 @@ If Framework Preset still shows **Next.js** after `vercel.json`: **patch via Ver
 4. Control Panel **does not** show `Unexpected token 'T'` / CMS unreachable
 5. Framework Preset = Other; Fluid on
 
-If (2) fails but (3) passes → **static `public/` trap**. Re-apply A3 + A4; confirm `startCommand`; redeploy. **Do not** add `api/` catch-all.
+If (2) fails but (3) passes → **static `public/` trap**. Re-apply A3 + A4; confirm dashboard Start Command + empty Output Directory; redeploy. **Do not** add `api/` catch-all. **Do not** move `server.ts` into `api/`.
 
 ### A6 — What Scheme A does **not** require
 
 - ❌ No changes to `@tomorrowos/sdk` package code
-- ❌ No `(req, res)` handler refactor
+- ❌ No `(req, res)` serverless handler refactor
 - ❌ No `next build` / `next start` on Production
-- ❌ No root `api/` directory for the CMS server
+- ❌ No root `api/` directory (`api/index.ts`, `api/[...].ts`, `api/[[...slug]].ts`)
+- ❌ No `rewrites` so only `/api/status` works while `/status` stays 404
+- ❌ No renaming `start` → `dev` with `tsx watch` for Production
+- ❌ No `@vercel/node` handler that calls non-existent `tomorrowos.getStatus()`
+
+### A7 — If v0 Publish still serves static `public/` (Path B)
+
+When **v0 Publish** keeps returning the static trap (`/` HTML OK, `/status` HTML, `Unexpected token 'T'`) **after** Scheme A is correct, the v0 deploy pipeline may not be starting the Fluid Node server.
+
+**Path B — deploy outside v0 Publish (recommended):**
+
+1. Keep Scheme A layout (root `server.ts`, Next only under `preview/`, minimal `vercel.json`).
+2. Connect the repo to **Vercel Git** or run **`vercel --prod`** from the project root (full Vercel CLI / dashboard deploy — not the v0 “Publish” button).
+3. In **Vercel Dashboard → Project → Settings → General**: Framework = **Other**, Output Directory = **empty**, Build = `npm run build`, **override** Install/Start if needed so Production runs `npm run start`.
+4. Redeploy; verify `curl https://PROD/status` → JSON.
+
+**Path C — if Vercel cannot run TomorrowOS Node + WebSocket reliably:**
+
+Host the CMS on **Railway**, **Fly.io**, or **Replit Publish** (long-lived Node). Use v0/Vercel only for Preview/demo if needed.
+
+### A8 — Undo a broken Agent “api/ migration”
+
+If an Agent moved `server.ts` → `api/index.ts` / `api/[...].ts` and only `/api/status` returns JSON:
+
+1. **Restore** `server.ts` at **project root** (from git or `templates/cms-starter/server.ts`).
+2. **Delete** root `api/index.ts`, `api/[...].ts`, `api/[[...slug]].ts` (Preview proxy may stay under `preview/app/` only).
+3. Revert `package.json` `start` to `tsx server.ts` (not `tsx watch` for Production).
+4. Apply minimal `vercel.json` (A3) — no `startCommand`, no `rewrites`.
+5. Dashboard: Framework Other, Output empty, Fluid on.
+6. Redeploy via Path B if v0 Publish still fails.
 
 ---
 
@@ -448,13 +486,13 @@ Write `vercel.json` so Production cannot be mistaken for Next. Minimum:
   "fluid": true,
   "framework": null,
   "installCommand": "npm install",
-  "buildCommand": "npm run build",
-  "startCommand": "npm run start",
-  "outputDirectory": null
+  "buildCommand": "npm run build"
 }
 ```
 
-Use `pnpm` / `yarn` variants of install/build/start if that is the project’s package manager.
+Use `pnpm` / `yarn` variants of install/build if that is the project’s package manager.
+
+**Do not** add `startCommand`, `processes`, or `outputDirectory` to `vercel.json` when v0 schema rejects them. Start = `package.json` `"start": "tsx server.ts"`. Output Directory = **empty in dashboard**.
 
 **Also force Project Settings (dashboard or Vercel API) — this is mandatory (see Scheme A4):**
 
@@ -464,7 +502,7 @@ Use `pnpm` / `yarn` variants of install/build/start if that is the project’s p
 | Install Command | `npm install` (or pnpm/yarn) |
 | Build Command | `npm run build` (no-op exit 0) |
 | Output Directory | **empty / null** — **NOT `public`** |
-| Start Command | `npm run start` → `tsx server.ts` (or `.mts`) — **explicit in `vercel.json` too** |
+| Start Command | `npm run start` → `tsx server.ts` (or `.mts`) — set in **dashboard**, not `vercel.json` |
 | Fluid compute | **On** |
 
 If `next` / `next.config.*` exist for Preview and the dashboard still auto-selects Next.js:
@@ -766,7 +804,7 @@ Then (**Scheme A — mandatory for Publish**):
 
 1. Keep **`server.ts`** at **project root** with top-level `listen()` + `export default server`.
 2. If Preview needs Next: **move** `next.config.*`, `app/`, Next `tsconfig` / `postcss` / `next-env.d.ts` into **`preview/`** — remove them from root so Production is not mistaken for Next/static.
-3. Write `vercel.json` per **Scheme A3** (`fluid`, `framework: null`, `startCommand`, `outputDirectory: null`).
+3. Write `vercel.json` per **Scheme A3** (`fluid`, `framework: null`, no-op `buildCommand` — **no** `startCommand`).
 4. **Force Project Settings** per **Scheme A4** (Framework = Other, Output Directory empty, Start = `npm run start`, Fluid on). Patch dashboard via API if it still says Next.js.
 5. Do **not** add root `api/` catch-all for raw `http.Server`.
 6. Do **not** add `.replit*`.
@@ -818,7 +856,7 @@ vercel --prod
 6. Production `GET /status` returns **JSON** — **not** HTML (`Unexpected token 'T'` means this failed)
 7. Production `GET /` returns Control Panel HTML — **not** `404: NOT_FOUND`
 
-If step 6 fails but step 7 passes: **static `public/` trap** — Vercel is not running Node. Re-apply Scheme A3–A4; do **not** invent `api/` + `routes`.
+If step 6 fails but step 7 passes: **static `public/` trap** — Vercel is not running Node. Re-apply Scheme A3–A4; try **Path B** (Git / `vercel --prod`); do **not** invent `api/` + `rewrites`.
 
 Tell the user:
 
@@ -846,8 +884,11 @@ Tell the user:
 | Symptom | Likely cause | Fix |
 |---------|--------------|-----|
 | Publish `404: NOT_FOUND` | Framework Preset still **Next.js** / no Node start | Scheme A: Framework = **Other**, Start = `npm run start`, Output empty, Fluid on; redeploy |
-| Panel loads but **CMS unreachable** / `Unexpected token 'T', "The page c"...` | **`public/` deployed as static site** — no Node running | Scheme A: `outputDirectory: null`, explicit `startCommand`, move Next to `preview/`; verify `GET /status` returns JSON |
-| `vercel inspect` shows Output = `public if it exists` | Framework=Other static default | Force Output Directory **empty** in dashboard + `outputDirectory: null`; ensure root `server.ts` + `startCommand` |
+| Panel loads but **CMS unreachable** / `Unexpected token 'T', "The page c"...` | **`public/` deployed as static site** — no Node running | Scheme A: Output empty in dashboard, `start` in package.json; undo any `api/` migration; try **Path B** deploy |
+| Only `/api/status` returns JSON, `/status` is 404 | Wrong **api/ serverless** migration + broken rewrites | **A8 undo:** restore root `server.ts`, delete root `api/*`; never accept this as “fixed” |
+| `vercel.json` error: invalid `startCommand` | v0 schema rejects it | Remove from `vercel.json`; use `package.json` `start` + dashboard Start Command |
+| Agent moved server to `api/`, added `@vercel/node` handler | Off-protocol serverless refactor | **A8 undo** — TomorrowOS needs one root `listen()` server, not per-request handlers |
+| `vercel inspect` shows Output = `public if it exists` | Framework=Other static default | Force Output Directory **empty** in dashboard; root `server.ts`; Path B redeploy |
 | Build runs `next build` / missing routes-manifest | Next auto-detected from root `next.config` / `app/` | Move Next to `preview/`; Framework null/Other; `build` = no-op |
 | Preview blank but logs show TomorrowOS listening | v0 Next intercepts public port | Add Next reverse proxy → internal TomorrowOS port |
 | Preview works, Publish broken / Next-only | Production still on Next | Switch Production entry to `tsx server.ts` / `export default server` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomorrowos/sdk",
-  "version": "0.9.27",
+  "version": "0.9.28",
   "description": "TomorrowOS CMS server SDK - WebSocket transport, pairing, device commands, optional static CMS UI. Includes CLI (tomorrowos init / build) and starter templates.",
   "type": "module",
   "main": "./dist/index.js",

package/templates/cms-starter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "my-cms",
-  "version": "0.9.27",
+  "version": "0.9.28",
   "description": "CMS server on @tomorrowos/sdk. Add your UI (React, static files, etc.) alongside this server.",
   "private": true,
   "type": "module",
@@ -13,7 +13,7 @@
     "build-player": "tomorrowos build --platform tizen"
   },
   "dependencies": {
-    "@tomorrowos/sdk": "^0.9.27",
+    "@tomorrowos/sdk": "^0.9.28",
     "dotenv": "^17.2.3",
     "tsx": "^4.19.0"
   },