npm - @tomorrowos/sdk - Versions diffs - 0.9.26 → 0.9.27 - Mend

@tomorrowos/sdk 0.9.26 → 0.9.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md +1 -1
package/VERCEL_SETUP.md +187 -32
package/package.json +1 -1
package/templates/cms-starter/package.json +2 -2

package/README.md CHANGED Viewed

@@ -73,7 +73,7 @@ IF any step contradicts Vercel, adapt to settings that Vercel can accept.
 That wizard asks: database (**Supabase** → **Neon** → SQLite demo), media (**Cloudinary** → **Vercel Blob** → local),
 branding (manual fields or **website URL → `brand.json` only**, no login unless asked). Preview may use a thin **Next.js reverse proxy**;
-**Publish stays pure Node** `TomorrowOS.listen` (Framework Preset = Other — gate on no `404 NOT_FOUND`). Cloudinary uses **one Env popup** (all fields).
+**Publish stays pure Node** `TomorrowOS.listen` (Scheme A: root `server.ts`, Next in `preview/`, `GET /status` must be JSON). Cloudinary uses **one Env popup** (all fields).
 Neon/Supabase: agent auto-sets `TOMORROWOS_STORE` + `DATABASE_SSL`. Sets `cms.hostingTarget` to `"vercel"`.
 ### Replit upgrade (existing CMS)

package/VERCEL_SETUP.md CHANGED Viewed

@@ -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.5` — pairs with `@tomorrowos/sdk` packages that ship `templates/cms-starter` and this file.
+> Protocol id: `vercel-setup/1.6` — pairs with `@tomorrowos/sdk` packages that ship `templates/cms-starter` and this file.
 ## User trigger (copy-paste)
@@ -19,7 +19,7 @@ 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, and GET / on the production URL must return the Control Panel (not 404 NOT_FOUND).
+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).
 ```
 Alternate triggers:
@@ -82,6 +82,29 @@ almost always means **Vercel still thinks this is a Next.js / static deploy**, n
 **Setup is NOT complete** while Production `GET /` returns `404: NOT_FOUND`. Fix Framework Preset + Start Command and redeploy.
+### Publish static trap — `public/` served without Node (read this)
+A common **worse** failure mode than `404: NOT_FOUND`:
+- `GET /` loads the Control Panel HTML (from static `public/index.html`)
+- `GET /status`, `/devices`, etc. return **HTML** (Vercel 404 page)
+- The panel shows **CMS unreachable** and console:
+  `Unexpected token 'T', "The page c"... is not valid JSON`
+**Root cause:** Vercel deployed `public/` as a **static site** (Output Directory = `public` or Framework=Other default *“public if it exists”*). **No Node process** is running `tsx server.ts`, so API routes never hit `TomorrowOS`.
+**Fix (Scheme A — see dedicated section below):** force Vercel to run the **root `server.ts` Node entry** with Fluid. `public/` must be served **at runtime** via `staticRoot` in `listen()`, **not** as the build output directory.
+**Publish gate (mandatory):** after deploy, `GET /status` must return **JSON** starting with `{`, not HTML starting with `<` or `The page`.
+```bash
+curl -s https://YOUR-PROJECT.vercel.app/status | head -c 80
+# Expected: {"status":"success",...}
+# Failure:  The page could not be found  OR  <!DOCTYPE html>
+```
+**Setup is NOT complete** while `/status` returns HTML or the panel shows the JSON parse error.
 ### Preview (v0 / Vercel Agent sandbox) — Next.js shell allowed
 v0 Preview is often a **Next.js runtime** hardwired to `next dev`. A raw `tsx server.ts` may listen successfully while Preview still shows a blank page, because the sandbox intercepts the public port with Next before requests reach TomorrowOS.
@@ -150,12 +173,138 @@ Then ask **Question 1**.
 14. **No inventing CMS login.** A branding URL never means “build auth.” Only add login if the user **explicitly** requests it.
 15. **Skip ≠ invent.** If the user skips media choice or a credential, do not replace it with OpenAI/auth/login questions. Stay on Q1–Q3 only.
 16. **Neon / Supabase helpers are agent-owned.** After the user pastes the DB URL, **you** set `TOMORROWOS_STORE` and `DATABASE_SSL` automatically — **do not** ask the user to fill those two.
-17. **Publish gate:** do not mark setup complete while Production returns `404: NOT_FOUND`. Fix Framework Preset + Start Command first (see **Publish 404** section).
+17. **Publish gate:** do not mark setup complete while Production returns `404: NOT_FOUND` **or** `/status` returns HTML (static `public/` trap).
+18. **Scheme A is doc-driven:** achieve Production Node Publish by **project layout + `vercel.json` + dashboard settings** during setup — **no SDK code changes** required (see **Scheme A** section).
 **Question order:** Q1 → Q2 → Q3 → execution checklist.
 ---
+## Scheme A — Standard Node Publish (mandatory for Production)
+> **Goal:** Preview may use Next + proxy; **Publish** runs **only** root `server.ts` + `TomorrowOS.listen` on Vercel Fluid.
+> **Scope:** This section is implemented entirely during setup (move files, write `vercel.json`, patch dashboard). **Do not** change `@tomorrowos/sdk` source.
+### Why Scheme A exists
+| Layer | Preview (v0) | Publish (Production) |
+|-------|----------------|----------------------|
+| Host | Next.js shell + HTTP proxy | **Node `server.ts`** only |
+| `public/` | Proxied from TomorrowOS | Served by **`staticRoot`** inside `listen()` — **not** as Vercel Output Directory |
+| WebSocket | Optional / may fail in Preview | Required on same origin (`wss://`) |
+| Next files | Allowed under `preview/` | **Must not** live at project root |
+### A1 — Project layout (Agent must enforce)
+**At project root (Production):**
+```
+server.ts          ← REQUIRED name at root (or server.mts)
+vercel.json
+package.json
+brand.json
+public/            ← CMS static UI; NOT the Vercel output directory
+```
+**Preview only (when v0 needs Next) — move ALL of these under `preview/`:**
+```
+preview/
+  next.config.mjs
+  app/               ← Next proxy routes
+  postcss.config.mjs
+  next-env.d.ts
+  tsconfig.json      ← Next/tsconfig if separate from server
+```
+**Remove from project root after move:** `next.config.mjs`, `app/`, root Next `tsconfig` plugin config, `postcss.config.mjs`, `next-env.d.ts`.
+**Do NOT:**
+- ❌ Leave `next.config.mjs` + `app/` at root while claiming Production is Node-only
+- ❌ Create root `api/index.ts` exporting `http.Server` + `routes` catch-all
+- ❌ Set Output Directory to `public` or `.`
+**Update `package.json` scripts when Preview uses `preview/`:**
+```json
+{
+  "scripts": {
+    "dev": "tsx watch server.ts",
+    "dev:preview": "concurrently -k \"npm:dev:tomorrowos\" \"npm:dev:next\"",
+    "dev:tomorrowos": "cross-env TOMORROWOS_INTERNAL_PORT=3001 tsx watch server.ts",
+    "dev:next": "cd preview && next dev -p 3000",
+    "start": "tsx server.ts",
+    "build": "node -e \"process.exit(0)\""
+  }
+}
+```
+### A2 — `server.ts` entry (Vercel zero-config Node detection)
+Vercel detects a **root** `server.ts` / `server.mts` and routes traffic to it when:
+1. The file lives at **project root** (not only under `api/`)
+2. **`listen()` runs at module load** (top-level, not inside an unexported function)
+3. The file **`export default server`** (the `http.Server` from `tomorrowos.listen`)
+Use the pattern in **Runtime & Vercel deploy rules** below. On Publish, **do not** set `TOMORROWOS_INTERNAL_PORT` — let Vercel inject `PORT`.
+### A3 — `vercel.json` (Production)
+```json
+{
+  "fluid": true,
+  "framework": null,
+  "installCommand": "npm install",
+  "buildCommand": "npm run build",
+  "startCommand": "npm run start",
+  "outputDirectory": null
+}
+```
+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
+### A4 — Vercel Project Settings (dashboard or API — mandatory)
+`vercel.json` alone is **not enough** if the dashboard still shows Framework = **Next.js** or Output = `public`.
+| Setting | Required value |
+|---------|----------------|
+| Framework Preset | **Other** / null — **not Next.js** |
+| 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` |
+| Fluid compute | **On** |
+If Framework Preset still shows **Next.js** after `vercel.json`: **patch via Vercel API / CLI / dashboard**, then redeploy.
+### A5 — Publish acceptance (all must pass before “setup complete”)
+1. Deploy logs show Node starting / `[TomorrowOS] listening on ...` (not only “Uploading static files”)
+2. `curl -s https://PROD/status` → JSON (`{"status":...}`)
+3. `curl -s https://PROD/` → Control Panel HTML
+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.
+### A6 — What Scheme A does **not** require
+- ❌ No changes to `@tomorrowos/sdk` package code
+- ❌ No `(req, res)` handler refactor
+- ❌ No `next build` / `next start` on Production
+- ❌ No root `api/` directory for the CMS server
+---
 ## Runtime & Vercel deploy rules (mandatory)
 ### Production runtime (Publish)
@@ -300,28 +449,30 @@ Write `vercel.json` so Production cannot be mistaken for Next. Minimum:
   "framework": null,
   "installCommand": "npm install",
   "buildCommand": "npm run build",
+  "startCommand": "npm run start",
   "outputDirectory": null
 }
 ```
-Use `pnpm` / `yarn` variants of install/build if that is the project’s package manager.
+Use `pnpm` / `yarn` variants of install/build/start if that is the project’s package manager.
-**Also force Project Settings (dashboard or Vercel API) — this is mandatory:**
+**Also force Project Settings (dashboard or Vercel API) — this is mandatory (see Scheme A4):**
 | Setting | Required value |
 |---------|----------------|
 | Framework Preset | **Other** / null — **not Next.js** |
 | Install Command | `npm install` (or pnpm/yarn) |
 | Build Command | `npm run build` (no-op exit 0) |
-| Output Directory | **empty** |
-| Start Command | `npm run start` → `tsx server.ts` (or `.mts`) |
+| Output Directory | **empty / null** — **NOT `public`** |
+| Start Command | `npm run start` → `tsx server.ts` (or `.mts`) — **explicit in `vercel.json` too** |
 | Fluid compute | **On** |
 If `next` / `next.config.*` exist for Preview and the dashboard still auto-selects Next.js:
 1. Patch Framework Preset to **Other** via API/CLI/dashboard.
 2. Redeploy.
-3. Hit Production `GET /` — must be Control Panel HTML, not `404: NOT_FOUND`.
+3. Hit Production `GET /status` — must be **JSON**, not HTML.
+4. Hit Production `GET /` — must be Control Panel HTML, not `404: NOT_FOUND`.
 If Vercel’s UI and this file disagree on bundling, **prefer whatever keeps a single long-lived Node HTTP server with WebSocket upgrade on `/` for Production**. Document the adaptation in the final summary.
@@ -611,16 +762,15 @@ npx @tomorrowos/sdk@latest init .
 # npx @tomorrowos/sdk@latest init . --force
 ```
-Then:
+Then (**Scheme A — mandatory for Publish**):
-1. Keep TomorrowOS `server.ts` / `server.mts` at **root** as the **Production** app (**export `listen()` HTTP server**).
-2. If the environment is **v0 / Next Preview**, add the **Preview adapter** (Next shell + reverse proxy + internal TomorrowOS port). Isolate Next configs when possible. Do **not** make Next the Production CMS.
-3. Write `vercel.json` with **`fluid: true`**, **`framework: null`**, no-op **`buildCommand`**, and **empty outputDirectory**.
-4. **Force Project Settings:** Framework Preset = **Other**, Start Command = `npm run start` (Node), Fluid on.
-5. Ensure Production start command is **`tsx server.ts`** (or `.mts`), **not** `next start`.
-6. Do **not** add root `api/` catch-all for raw `http.Server`.
-7. Do **not** add `.replit*`.
-8. If Q2 = Vercel Blob: install `@vercel/blob` and wire the upload bridge.
+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`).
+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*`.
+7. If Q2 = Vercel Blob: install `@vercel/blob` and wire the upload bridge.
 ### B. Environment Variables (Vercel dashboard + local)
@@ -658,15 +808,17 @@ vercel --prod
 # or git push → Vercel Git integration
 ```
-**Publish acceptance checklist (all must pass):**
+**Publish acceptance checklist (all must pass — Scheme A5):**
 1. Framework Preset = **Other** / null (dashboard confirms — not Next.js)
-2. Start Command = Node `TomorrowOS.listen` (`npm run start`)
-3. Fluid compute on
-4. Env Vars present for Production
-5. Production `GET /` returns Control Panel HTML — **not** `404: NOT_FOUND`
+2. Output Directory = **empty** (not `public`)
+3. Start Command = Node `TomorrowOS.listen` (`npm run start` / `tsx server.ts`)
+4. Fluid compute on
+5. Env Vars present for Production
+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 5 fails: do **not** invent `api/` + `routes`. Patch Framework Preset + Start Command, redeploy, re-check `/`.
+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`.
 Tell the user:
@@ -678,11 +830,12 @@ Tell the user:
 **Do:**
-1. Preview: Control Panel HTML at `/` (via Next proxy if applicable)
-2. Publish: Control Panel HTML at `/` from **Node** TomorrowOS (block on `404: NOT_FOUND`)
-3. Server status: Media OK when Cloudinary or Blob configured
-4. Database: if ERROR shows **`ENETUNREACH` … IPv6 … `:5432`**, switch to **pooled** URL (Supabase `:6543` or Neon pooler) and redeploy — call this out explicitly to the user
-5. Fluid compute on for Production
+1. Preview: Control Panel HTML at `/` (via Next proxy in `preview/` if applicable)
+2. Publish: `GET /status` → JSON; `GET /` → Control Panel from **Node** TomorrowOS
+3. Publish: panel does **not** show `Unexpected token 'T'` / CMS unreachable
+4. Server status: Media OK when Cloudinary or Blob configured
+5. Database: if ERROR shows **`ENETUNREACH` … IPv6 … `:5432`**, switch to **pooled** URL (Supabase `:6543` or Neon pooler) and redeploy — call this out explicitly to the user
+6. Fluid compute on for Production
 **Do not block** on long WebSocket/device pairing tests unless the user asks. Prefer pairing against **Publish**, not Preview.
@@ -692,8 +845,10 @@ Tell the user:
 | Symptom | Likely cause | Fix |
 |---------|--------------|-----|
-| Publish `404: NOT_FOUND` | Framework Preset still **Next.js** / no Node start | Set Framework = **Other**, Start = `npm run start`, Fluid on; redeploy. Do **not** add root `api/` catch-all |
-| Build runs `next build` / missing routes-manifest | Next auto-detected from `next.config` / deps | Force Framework null/Other; `build` = no-op; isolate Preview Next files |
+| 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` |
+| 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` |
 | `ENETUNREACH` / IPv6 / `:5432` | Direct Postgres URL | Use **pooled** URL (Supabase `:6543` or Neon pooler) |
@@ -731,7 +886,7 @@ Tell the user:
 After setup, report:
 1. **Live URL** (Production Publish)
-2. **Publish health:** Framework Preset = Other; Start = Node; `GET /` OK (not 404)
+2. **Publish health:** Framework = Other; Output ≠ `public`; `GET /status` → JSON; `GET /` OK
 3. **Preview note:** Next proxy shell used / not needed
 4. **Env Vars set** (names only — never values); note which were auto-set (`TOMORROWOS_STORE`, `DATABASE_SSL`)
 5. **Store:** Supabase pooler / Neon pooled / SQLite (with warning)
@@ -743,7 +898,7 @@ After setup, report:
 Protocol complete when:
 - **Preview** shows the Control Panel at `/` (via Next proxy if required), **and**
-- **Publish** returns Control Panel at `/` from pure Node `TomorrowOS.listen` with Fluid (not `404: NOT_FOUND`), **and**
+- **Publish** returns Control Panel at `/` **and** `/status` JSON from pure Node `TomorrowOS.listen` with Fluid (not static `public/`, not `404: NOT_FOUND`, not `Unexpected token 'T'`), **and**
 - Q1–Q3 configuration is saved
 — even if a sandbox DB probe still flakes **after** the pooled URL is correctly set for Production.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@tomorrowos/sdk",
-  "version": "0.9.26",
+  "version": "0.9.27",
   "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 CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "my-cms",
-  "version": "0.9.26",
+  "version": "0.9.27",
   "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.26",
+    "@tomorrowos/sdk": "^0.9.27",
     "dotenv": "^17.2.3",
     "tsx": "^4.19.0"
   },