@tomorrowos/sdk 1.1.1 → 1.1.2

package/VERCEL_QUESTIONS.md

@@ -1,12 +1,13 @@
 # Vercel / v0 - Verbatim question bank
 
-> **Protocol:** `vercel-questions/1.6` (pairs with `VERCEL_SETUP.md` 1.16+ / `@tomorrowos/sdk` 0.9.70+)  
+> **Protocol:** `vercel-questions/1.6` (pairs with `VERCEL_SETUP.md` 1.17+ / `@tomorrowos/sdk` 0.9.70+)  
 > **For Agents:** When asking the user a setup question, **copy-paste the block below for that step EXACTLY**.  
 > Do **not** paraphrase, reorder, rename options, or invent alternatives (no S3, no Supabase Storage, no "Blob recommended", no "disable media").  
 > After each answer, configure per `VERCEL_SETUP.md`, then paste the **next** block.  
 > **Q1 and Q2 are choice questions. Q3 is a form only - never a multiple-choice question. Q4 is optional CMS password (`CMS_PASSWORD`).**  
 > **HARD STOP on Q3:** show the form, then **wait** for the user's reply. Optional fields do **not** mean you may auto-skip.  
-> **Q4 is optional:** blank/skip is valid; they can set `CMS_PASSWORD` later.
+> **Q4 is optional:** blank/skip is valid; they can set `CMS_PASSWORD` later.  
+> **After Q4 (or after Q3 if you deferred Q4):** run `VERCEL_SETUP.md` **IRON GATE — v0 Preview hygiene** before debugging Neon/Postgres or Blob.
 
 ---
 

package/VERCEL_SETUP.md

@@ -5,11 +5,12 @@
 >
 > **On Vercel, this file is the setup questionnaire** (not `REPLIT_SETUP.md`).
 >
-> Protocol id: `vercel-setup/1.16` - pairs with `@tomorrowos/sdk` **0.9.70+** (`templates/cms-starter-v0`, Fluid Functions WebSockets).
+> Protocol id: `vercel-setup/1.17` - pairs with `@tomorrowos/sdk` **0.9.70+** (`templates/cms-starter-v0`, Fluid Functions WebSockets).
 >
 > **Questions source of truth:** `VERCEL_QUESTIONS.md` - Agents must **open that file and paste each Q block verbatim**. Do not paraphrase.  
 > **Q1/Q2 = choice questions. Q3 = form only:** open **all seven optional inputs at once**, then **HARD STOP and WAIT** for submit or "skip". Never auto-skip because fields are optional. Never ask a branding choice first. Never show only Name + Primary colour. Logo = **Upload** above **Logo URL**.  
 > **Q4 = optional `CMS_PASSWORD`:** blank/skip is valid; can set later. Control Panel auth only — never Vercel Deployment Protection / whole-site password.  
+> **After Q&A (before debugging DB):** run **IRON GATE — v0 Preview hygiene** (clear root Next leftovers, restart supervised `dev`, prove `GET /status` is TomorrowOS JSON). Do **not** spend turns “fixing Neon/Blob” while port 3000 is still a stale Next/Turbopack process.  
 > **Copy questions verbatim from `VERCEL_QUESTIONS.md`.** Do not invent alternate Q2 options (no "Supabase Storage", no S3, no "disable media", no making Blob the recommended option).  
 > **`TOMORROWOS_STORE` and `DATABASE_SSL` are agent-only** - set them automatically after Q1; never put them in a user-facing Env form for the customer to type.
 
@@ -40,8 +41,10 @@ Follow @tomorrowos/sdk (an NPM package) VERCEL_SETUP.md and set up my TomorrowOS
 Open VERCEL_QUESTIONS.md first.
 For Q1, Q2, Q3: paste each question block VERBATIM. Do not rephrase options.
 For Q3: DO NOT ask a branding choice. Open one form with ALL SEVEN optional inputs at once, then HARD STOP and WAIT for my submit or "skip". Never auto-continue with defaults without my reply. Never only Name + Primary colour. Logo = Upload above Logo URL.
+After Q3, paste Q4 (optional CMS password). Blank/skip is valid.
 After Q1 database choice, YOU set TOMORROWOS_STORE and DATABASE_SSL. Do not ask me to fill those.
 After Q2 media storage choice, YOU set TOMORROWOS_MEDIA. Do not ask me to fill those.
+After answers: run IRON GATE v0 Preview hygiene BEFORE debugging Postgres/media — clear root Next leftovers, restart supervised dev, prove GET /status is TomorrowOS JSON.
 Run: npx @tomorrowos/sdk@latest init . --hosting v0 --force
 Keep cms-starter-v0 layout.
 Apply the NON-NEGOTIABLE VERCEL RUNTIME CONTRACT exactly:
@@ -221,13 +224,76 @@ Then ask **Question 1**.
 16. **No inventing CMS login** from a branding URL.
 17. **Skip → invent.** Stay on Q1–Q4 only.
 18. **Publish gate:** `/status` JSON + WebSocket 101; no static `public/` trap.
-19. **Q3 is a form, not a question ? and you must WAIT.** After Q2, open one dialog with **all seven** optional inputs visible together, then **stop and wait** for submit or explicit **"skip"**. **Never** auto-continue because fields are optional. **Never** ask a preliminary branding choice. **Never** show only Product Name + Primary colour. **Never** use multiple-choice / Option A-B for branding. Logo = **Upload** above **Logo URL**.
+19. **Q3 is a form, not a question — and you must WAIT.** After Q2, open one dialog with **all seven** optional inputs visible together, then **stop and wait** for submit or explicit **"skip"**. **Never** auto-continue because fields are optional. **Never** ask a preliminary branding choice. **Never** show only Product Name + Primary colour. **Never** use multiple-choice / Option A-B for branding. Logo = **Upload** above **Logo URL**.
+20. **IRON GATE after Q&A:** Before blaming Neon / Blob / migrations, complete **IRON GATE — v0 Preview hygiene** below. Preview 500s are usually leftover root Next or a stale supervised `next-server`, not a bad Q1/Q2 choice.
 
-**Question order:** Q1 -> (auto-set store env) -> Q2 -> Q3 form (**wait for user**) -> Q4 optional `CMS_PASSWORD` -> execution checklist.
+**Question order:** Q1 -> (auto-set store env) -> Q2 -> Q3 form (**wait for user**) -> Q4 optional `CMS_PASSWORD` -> **IRON GATE** -> execution checklist.
 
 ---
 
-## Scheme A ??Vercel Functions + WebSockets (mandatory for Production)
+## IRON GATE — v0 Preview hygiene (run after Q&A, before DB rabbit holes)
+
+> **Why this exists:** On v0, agents often answer Q1–Q3, run `init`, then spend a long time “fixing Postgres” while port **3000** is still the original **Next/Turbopack** starter (or a manually spawned `tsx` without injected env). Neon vs Blob choices are **not** the usual cause.
+
+### Do this in order — stop when each check passes
+
+1. **Identify what owns `:3000` (empirical, 30 seconds)**  
+   - If process/logs look like `next-server` / Turbopack / `ENOENT .../app` → you are **not** talking to TomorrowOS yet.  
+   - If `GET /status` returns TomorrowOS **JSON** (`{"status":...}`) → proceed.  
+   - **Forbidden:** debugging `DATABASE_URL` / Neon pooler while `/status` is HTML, Next error overlay, or Turbopack crash.
+
+2. **Clear forbidden root Next leftovers (from the original v0 starter)**  
+   Remove from **project root** (keep the SDK shell under `preview/`):  
+   `app/`, `pages/`, root `next.config.*`, root `next-env.d.ts`, root `postcss.config.*`, leftover `components/` / `lib/` from the starter, `components.json` — anything that makes Framework detection or v0 Preview latch onto Next at root.  
+   **Do not** delete `preview/` (that is the sanctioned Next reverse-proxy shell).  
+   Empty leftover dirs after deleting files.
+
+3. **Confirm scripts + layout**  
+   - Root `package.json` `"dev"` / `"start"` run TomorrowOS (`tsx` …), not `next dev` at root.  
+   - `preview/` exists if Preview stays Next-hardwired; use `dev:preview` (Next public + TomorrowOS on **3001**) when required.  
+   - `cms-panel/` (or template static root) is TomorrowOS UI — **not** Vercel Output Directory `public/`.
+
+4. **Restart the platform-supervised `dev` — do not double-bind**  
+   - After rewriting `package.json` scripts, the **old** supervised `next-server` may still hold `:3000`. Kill/restart so the supervisor re-execs the **new** `dev` script.  
+   - **Forbidden:** spawning a second manual `pnpm dev` / `tsx` that fights the supervised process (`EADDRINUSE`) **and** lacks v0-injected env.  
+   - Prefer the **v0/Vercel managed** process (it inherits injected secrets). Only start TomorrowOS yourself if you also load the same env (see **Env loading trap**).
+
+5. **Prove TomorrowOS before touching DB**  
+   - `GET /status` → **200 JSON** from TomorrowOS (not Next HTML, not `The page could not be found`).  
+   - `GET /` → Control Panel HTML (or CMS login HTML if `CMS_PASSWORD` set).  
+   - Only **then** interpret Database/Media connector errors as real store/media issues.
+
+### Env loading trap (v0 / Preview vs Production)
+
+| Context | How secrets arrive | What `import "dotenv/config"` sees |
+|---------|-------------------|-------------------------------------|
+| **Production Deploy** | Vercel injects into `process.env` | N/A — platform env wins |
+| **v0 / Agent Preview** | Often written to **`.env.development.local`** (and/or injected only into the **supervised** Node process) | **Only `.env`** by default — **not** `.env.development.local` |
+| **Manual Bash `pnpm dev`** | Usually **no** injected `DATABASE_URL` / Blob token unless you export them | Easy false “Postgres broken” |
+
+**Rules:**
+
+- Non-secret flags may live in committed `.env` (`TOMORROWOS_STORE`, `DATABASE_SSL`, `TOMORROWOS_MEDIA`).  
+- Secrets (`DATABASE_URL`, `SUPABASE_URL`, `BLOB_READ_WRITE_TOKEN`, `CMS_PASSWORD`, Cloudinary keys) belong in **Vercel Env** / v0 injection — never commit them.  
+- If logs say store=`postgres` but `DATABASE_URL` is missing in a **manual** process: load `.env` **and** `.env.development.local`, or restart the **supervised** server — do **not** immediately change Neon URLs.  
+- Preview flakes ≠ Production failure. Fix Preview hygiene first; do not “repair” Production Framework because Preview 500’d.
+
+### Preview decision tree (after hygiene)
+
+```
+Is GET /status TomorrowOS JSON on the Preview URL?
+  YES → continue checklist (Publish gates still required).
+  NO → What owns the public port?
+        next-server / Turbopack / ENOENT app/ → clear root Next + restart supervised dev (steps 2–4).
+        tsx TomorrowOS listening but Preview blank → v0 still hardwires Next: use preview/ reverse-proxy + TOMORROWOS_INTERNAL_PORT=3001 + dev:preview.
+        EADDRINUSE :3000 → kill stale Next/tsx; one process only.
+```
+
+**Reminder:** Q1 Neon / Q2 Blob are valid protocol choices. A long Preview outage after those answers is almost always **process/layout/env injection**, not “wrong database/media product.”
+
+---
+
+## Scheme A — Vercel Functions + WebSockets (mandatory for Production)
 
 > **Goal:** Preview may use Next + proxy; **Publish** runs TomorrowOS as a **Vercel Function** (`api/index.ts`) on **Fluid**, with WebSocket support per [Vercel WebSockets docs](https://vercel.com/docs/functions/websockets).  
 > **Scope:** Layout + `vercel.json` + dashboard. Prefer `npx @tomorrowos/sdk@latest init --hosting v0` (`cms-starter-v0`).  
@@ -511,12 +577,14 @@ const server = tomorrowos.listen({
 export default server;
 ```
 
-- **Production:** `PORT` from Vercel ??TomorrowOS listens on that port (no Next).
+- **Production:** `PORT` from Vercel — TomorrowOS listens on that port (no Next).
 - **Preview:** set `TOMORROWOS_INTERNAL_PORT=3001` (or similar) so Next can own `:3000` and proxy inward.
 
-Load env with `dotenv` for local/`vercel dev`. On production Deploy, Vercel injects Environment Variables natively.
+Load env with `dotenv` for local/`vercel dev` (loads **`.env` only**). On production Deploy, Vercel injects Environment Variables natively.
 
-### Preview adapter (v0 / Next reverse proxy) ??required when Preview is Next-hardwired
+**v0 / Preview caveat:** platform secrets often land in **`.env.development.local`** or only in the **supervised** process env. TomorrowOS `import "dotenv/config"` does **not** auto-load `.env.development.local`. See **IRON GATE — Env loading trap**. Never treat a manual Bash server missing `DATABASE_URL` as proof that Neon is misconfigured.
+
+### Preview adapter (v0 / Next reverse proxy) — required when Preview is Next-hardwired
 
 Detect Preview / v0 (Next already present, or Preview blank while TomorrowOS logs ?listening??. Then:
 
@@ -874,26 +942,35 @@ Set `cmsEndpoint` only if they already know the public `https://?vercel.app` URL
 
 ---
 
-## After all answers ? execution checklist
+## After all answers — execution checklist
+
+### A0. IRON GATE first (mandatory)
+
+Complete **IRON GATE — v0 Preview hygiene** before long Postgres/media debugging:
+
+1. Prove `GET /status` is TomorrowOS JSON (or clear root Next + restart supervised `dev` until it is).
+2. Remove root `app/` / `next.config.*` leftovers; keep `preview/` only for the proxy shell.
+3. Do not spawn a second manual server that lacks injected env / fights `:3000`.
+4. Only then treat Database/Media connector errors as real.
 
 ### A. Seed the project
 
 ```bash
-npx @tomorrowos/sdk@latest init .
+npx @tomorrowos/sdk@latest init . --hosting v0
 # If not empty and user confirms starter overwrite:
-# npx @tomorrowos/sdk@latest init . --force
+# npx @tomorrowos/sdk@latest init . --hosting v0 --force
 ```
 
-Then (**Scheme A ??mandatory for Publish**):
+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`, no-op `buildCommand` ??**no** `startCommand`).
+2. **Immediately** move leftover v0 Next from root into **`preview/`** or delete root Next files (`next.config.*`, `app/`, Next `tsconfig` / `postcss` / `next-env.d.ts`, starter `components/`). Production must not see root Next.
+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*`.
 7. If Q2 = Vercel Blob: set `BLOB_READ_WRITE_TOKEN` + `TOMORROWOS_MEDIA=vercel-blob` (SDK-native; no custom bridge).
-
+8. **Restart** the platform-supervised Preview `dev` after script/layout changes (stale `next-server` is the #1 false “DB failure”).
 ### B. Environment Variables (Vercel dashboard + local)
 
 | Name | Required | Who fills it |
@@ -909,14 +986,16 @@ Then (**Scheme A ??mandatory for Publish**):
 | `PORT` | Optional | Vercel injects for Production |
 | `CMS_PASSWORD` | Optional (Q4) | User if set; blank/skip = omit (can add later) |
 
-Mirror non-secrets in `.env` for local `npm run dev` if helpful; never commit secrets.
+Mirror non-secrets in `.env` for local `npm run start` if helpful; never commit secrets.  
+On v0 Preview, secrets may exist only in **`.env.development.local`** / supervised env — see **Env loading trap**. Do not “fix Neon” until the process that serves `/status` actually has `DATABASE_URL` / `SUPABASE_URL`.
 
 ### C. Install and run
 
 ```bash
 npm install
 npm run start
-# Preview / v0: npm run dev:preview  (Next + TomorrowOS internal)
+# Preview / v0 when Next-hardwired: npm run dev:preview  (Next :3000 + TomorrowOS :3001)
+# After changing package.json "dev": restart the supervised process — do not leave stale next-server on :3000
 ```
 
 Confirm logs: `[TomorrowOS] listening on http://0.0.0.0:?`  
@@ -994,6 +1073,12 @@ More detail: https://docs.tomorrowos.org/docs/os/tizen and https://docs.tomorrow
 
 | Symptom | Likely cause | Fix |
 |---------|--------------|-----|
+| Preview 500 / Turbopack / `ENOENT .../app` after Q1–Q3 | Leftover **root** Next from v0 starter; not Neon/Blob | **IRON GATE:** delete/move root `app/` + `next.config.*`; keep `preview/`; restart supervised `dev`; prove `/status` JSON |
+| `Internal Server Error` + logs blame missing `DATABASE_URL` in a **manual** Bash server | `dotenv` loaded `.env` only; secret is in `.env.development.local` / supervised env | Restart **supervised** Preview process; or load both env files — do **not** immediately change Neon URL |
+| `EADDRINUSE :3000` while debugging | Second `pnpm dev` / stale `next-server` after script rewrite | Kill stale Next/tsx; one process; let supervisor re-exec new `"dev"` |
+| Preview still Next after `package.json` `"dev"` → `tsx` | Supervised process never restarted | Kill old tree; wait for supervisor / restart Preview |
+| Agent spent many turns on Postgres before `/status` JSON | Skipped IRON GATE | Stop; run hygiene steps 1–5; only then debug store |
+| Q1=Neon / Q2=Blob then long Preview outage | Usually **not** the product choice | Same as root-Next / env-injection failures; choices are valid |
 | Publish `404: NOT_FOUND` | Framework Preset still **Next.js** / no Function | Scheme A: Framework = **Other**, Fluid on, `api/index.ts` + rewrites; redeploy |
 | Panel loads but **CMS unreachable** / `Unexpected token 'T', "The page c"...` | **`public/` deployed as static site** ??no Function | Rename to `cms-panel/`; Output empty; Scheme A Function entry; **Path B** if needed |
 | Only `/api/status` returns JSON, `/status` is 404 | Missing **rewrites** to `/api` | Add Scheme A3 rewrite `/(.*) ??/api` (exclude existing `/api/`); redeploy |
@@ -1069,7 +1154,9 @@ Protocol complete when:
 
 ## Protocol version
 
-`vercel-setup/1.16` - pairs with `@tomorrowos/sdk` 0.9.70+ and `VERCEL_QUESTIONS.md` 1.6.
+`vercel-setup/1.17` - pairs with `@tomorrowos/sdk` 0.9.70+ and `VERCEL_QUESTIONS.md` 1.6.
+
+**Changelog 1.17:** After Q&A, agents **must** run **IRON GATE — v0 Preview hygiene** before DB rabbit holes: clear root Next leftovers, restart supervised `dev`, prove `GET /status` is TomorrowOS JSON. Documents `.env` vs `.env.development.local` / supervised-env trap. Preview decision tree + cheat-sheet rows for Turbopack/`ENOENT`, missing `DATABASE_URL` in manual Bash, `EADDRINUSE`, stale `next-server`. Neon/Blob choices are not the usual Preview failure cause.
 
 **Changelog 1.16:** Question 4 is optional Control Panel Env `CMS_PASSWORD` (blank/skip allowed; can set later). Do not use Vercel Deployment Protection / whole-site password for devices.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomorrowos/sdk",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Server SDK for building and self-hosting digital signage CMS products with TomorrowOS players.",
   "type": "module",
   "main": "./dist/index.js",

package/templates/cms-starter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "my-cms",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "CMS server on @tomorrowos/sdk. Add your UI (React, static files, etc.) alongside this server.",
   "private": true,
   "type": "module",
@@ -12,7 +12,7 @@
     "start": "tsx server.ts"
   },
   "dependencies": {
-    "@tomorrowos/sdk": "^1.1.1",
+    "@tomorrowos/sdk": "^1.1.2",
     "dotenv": "^17.2.3",
     "tsx": "^4.19.0"
   },

package/templates/cms-starter-v0/package.json

@@ -1,6 +1,6 @@
 {
   "name": "my-cms",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "TomorrowOS CMS for Vercel / v0 Publish (Fluid Function + WebSockets + optional Next Preview).",
   "private": true,
   "type": "module",
@@ -16,7 +16,7 @@
     "build": "node -e \"process.exit(0)\""
   },
   "dependencies": {
-    "@tomorrowos/sdk": "^1.1.1",
+    "@tomorrowos/sdk": "^1.1.2",
     "dotenv": "^17.2.3",
     "tsx": "^4.19.0"
   },