@tomorrowos/sdk 1.1.0 → 1.1.1

package/REPLIT_SETUP.md

@@ -78,7 +78,7 @@ Replit Agent must ask **only** the questions defined in **this file**, in **this
 | Q1 + Supabase | Database choice ?**immediately** one Secrets input for `SUPABASE_URL` (still Question 1) |
 | Q2 + Cloudinary | Media choice ?**immediately** one multi-field Secrets dialog for all `CLOUDINARY_*` keys (still Question 2) |
 | Q3 branding | **One** multi-field dialog with **all seven** branding inputs stacked (name, tagline, primary, background, text, secondary, logo) |
-| Q4 CMS password | Optional single Secrets input for `CMS_PASSWORD` (blank/skip allowed; can set later) |
+| Q4 CMS password | **Immediately after Q3** ? one Secrets input for `CMS_PASSWORD` (blank/skip allowed). **Never** ask a yes/no "do you want a password?" first. |
 
 **Critical ?Question 1 option order (exact):** Present database choices in **this order only**:
 1. **Supabase Postgres (Recommended)**
@@ -88,13 +88,15 @@ Replit Agent must ask **only** the questions defined in **this file**, in **this
 
 **Critical:** Question 2 is **not complete** when the user says Cloudinary?or **1**. You **must immediately** open the **multi-field** Cloudinary Secrets dialog (same Question 2 ?**not** ?b? **not** one key per message) and collect `CLOUDINARY_CLOUD_NAME`, `CLOUDINARY_API_KEY`, and `CLOUDINARY_API_SECRET` **before** Question 3.
 
-**Critical ?Question 3:** All seven branding fields are **optional** and must appear in **one stacked multi-input dialog**. Empty / skip / use defaults??keep starter **`brand.json`**. **Never** ask name, then colours, then logo across separate turns.
+**Critical ? Question 3:** All seven branding fields are **optional** and must appear in **one stacked multi-input dialog**. Empty / skip / use defaults ? keep starter **`brand.json`**. **Never** ask name, then colours, then logo across separate turns.
+
+**Critical ? Question 4 (right after Q3, no warm-up):** As soon as Q3 is submitted/skipped, open the **CMS password** Secrets input (or one chat prompt). **Forbidden before Q4:** "Do you want to protect the CMS?", "Add a password?", "Enable auth?", Option A/B for password yes/no. The password field itself is optional ? blank/skip is a complete Q4 answer.
 
 If the user volunteers extra info early (e.g. brand name before Q3), **record it** and still ask the current question's required fields you do not yet have. Do not skip ahead to execution until Q1?Q4 are complete (Question 2 includes Cloudinary Secrets when applicable; Q4 may be blank/skip). For Q3, "complete" includes the user skipping or leaving fields blank.
 
 If the user says just set it up, dont ask questions,?respond:
 
-> I need a few quick answers from REPLIT_SETUP.md (database choice ? Supabase recommended, then Replit Postgres ? media storage ? plus Cloudinary credentials if you choose Cloudinary ? optional branding ? and optional Control Panel password). It takes about a minute and ensures the CMS deploys correctly on Replit.
+> I need a few quick answers from REPLIT_SETUP.md (database choice ? Supabase recommended, then Replit Postgres ? media storage ? plus Cloudinary credentials if you choose Cloudinary ? optional branding ? and optional CMS password). It takes about a minute and ensures the CMS deploys correctly on Replit.
 
 Then ask **Question 1** ?stay on this file.
 
@@ -107,7 +109,7 @@ Then ask **Question 1** ?stay on this file.
 2a. **Q1 Supabase:** choice ?**immediately** `SUPABASE_URL` input (same Question 1).
 2b. **Q2 Cloudinary:** choice ?**immediately** multi-field `CLOUDINARY_*` Secrets dialog (same Question 2).
 2c. **Q3:** one dialog, **seven inputs stacked** (all optional).
-2d. **Q4:** Optional CMS password. If blank/skip ? omit `CMS_PASSWORD`. If set ? store as Secret `CMS_PASSWORD` (Control Panel only; never enable Replit whole-site password).
+2d. **Q4:** Right after Q3 ? open the CMS password input immediately. **No** yes/no prelude. Blank/skip ? omit `CMS_PASSWORD`. If set ? Secret `CMS_PASSWORD` (app login only; never Replit whole-site password). Ensure Publish readiness uses **`GET /status`** (see **Publish health check**).
 3. **Do not invent** Cloudinary credentials, Supabase URLs, or brand colours. **Do not ask** screen / device count.
 4. **Do not use Replits reserved `DATABASE_URL` Secret for Supabase.** On Replit, `DATABASE_URL` is often the **built-in Replit PostgreSQL** URL. For Supabase always use **`SUPABASE_URL`**. For built-in Replit Postgres, use **`DATABASE_URL`** with `TOMORROWOS_STORE=postgres`.
 4a. **If Supabase is chosen: never collect `SUPABASE_URL` twice.** One capture right after the choice is enough.
@@ -161,7 +163,24 @@ Replit Publish must see:
 - A Node process started by `npm run start` ?`tsx server.ts`
 - `host: "0.0.0.0"` and `port: Number(process.env.PORT) || 3000`
 - An exposed port with `externalPort = 80` in `.replit` (see template below)
-- **Autoscale** (or Reserved VM) deployment ?**not** Static-only
+- **Reserved VM** deployment preferred for TomorrowOS (persistent WebSockets) ? Autoscale is a fallback; **not** Static-only
+
+### Publish health check / readiness probe (IRON RULE)
+
+Replit Publish readiness must **not** treat a password-gated Control Panel redirect as healthy.
+
+**Cause of a common Publish failure:** build OK, then readiness hits `GET /`. With `CMS_PASSWORD` set, older auth wrappers **303 ? `/login`**, and the checker follows redirects until it fails.
+
+**Required agent behavior before / during Publish:**
+
+1. Prefer the public JSON endpoint: configure the production **startup / health / readiness probe** to **`GET /status`** (returns HTTP 200, no auth, no redirect).
+2. Confirm starter `cms-auth` serves unauthenticated panel HTML at `/` with **HTTP 200** (login page ? **no 303 redirect loop**). Do **not** revert to redirecting `/` ? `/login`.
+3. Verify before telling the user Publish is ready:
+   - `GET /status` ? **200** JSON, **no** `Location` redirect
+   - `GET /` with `CMS_PASSWORD` set ? **200** (login HTML) or authenticated panel ? **not** a redirect chain
+4. In Publishing, choose **Reserved VM** (preferred for WebSocket pairing). Autoscale may drop long-lived sockets; Static is forbidden.
+
+If Publish fails with redirect / readiness errors after setting `CMS_PASSWORD`: switch the probe to **`/status`**, confirm `cms-auth` uses 200-at-`/` (not 303), then republish.
 
 ### `.replit` (create or replace ?required for publish)
 
@@ -189,10 +208,11 @@ ignorePorts = false
 **Agent rules for `.replit`:**
 
 - Set `entrypoint = "server.ts"` (not `index.js` unless that file exists and starts TomorrowOS).
-- Set `deploymentTarget = "autoscale"` (WebSocket + long-lived connections; Static Deploy is wrong).
+- Prefer **Reserved VM** in the Publishing UI for TomorrowOS WebSockets. Keep `deploymentTarget = "autoscale"` in `.replit` only if that is what the workspace template requires ? still choose **Reserved VM** when the Publish dialog offers it (see Replit Publishing pane).
 - Keep exactly **one** primary `[[ports]]` entry with `externalPort = 80` for the CMS server.
 - Ensure `.replit-artifact/artifact.toml` has **`kind = "web"`** (shipped in cms-starter). If `kind = "api"`, change to **`web`** before Publish.
-- If `.replit` contains `[[artifacts]]` with **only** `artifacts/api-server` and Publish fails, set artifact **`kind = "web"`** or create a **new Web app** Repl and migrate ?do not tell the user publish succeeded.
+- If `.replit` contains `[[artifacts]]` with **only** `artifacts/api-server` and Publish fails, set artifact **`kind = "web"`** or create a **new Web app** Repl and migrate ? do not tell the user publish succeeded.
+- **Always** set Publish readiness / health probe to **`/status`** when the UI allows (see **Publish health check**). Never leave the probe on `/` if it follows auth redirects.
 
 If Replit assigns a different `localPort` via `PORT`, update `localPort` to match the port in `[TomorrowOS] listening on http://0.0.0.0:<PORT>` logs, but keep `externalPort = 80`.
 
@@ -201,9 +221,10 @@ If Replit assigns a different `localPort` via `PORT`, update `localPort` to matc
 Before Publish:
 
 1. Confirm project filter / type shows **Web** (not API-only).
-2. In Publishing, choose **Autoscale** (recommended) or **Reserved VM** ?**not Static**.
-3. Stop stale processes; clear port conflicts; restart workspace if needed.
-4. `npm run start` ?Preview at `/` shows Control Panel.
+2. In Publishing, choose **Reserved VM** (preferred for WebSockets) or Autoscale ? **not Static**.
+3. Set readiness / health check path to **`/status`** when the UI exposes it (mandatory if `CMS_PASSWORD` is set).
+4. Stop stale processes; clear port conflicts; restart workspace if needed.
+5. `npm run start` ? Preview at `/` shows Control Panel (or CMS login HTML with HTTP 200 if password set).
 
 After Publish, the public URL is:
 
@@ -706,14 +727,16 @@ Do **not** ask for screen count. Keep a default `cms.expectedScreens` (e.g. `5`)
 
 ## Question 4 ? Optional CMS password (`CMS_PASSWORD`)
 
-> **Optional.** Protect the Control Panel with app-level auth. You may **skip** and set Secret `CMS_PASSWORD` later (then Redeploy / restart).
+> **Optional.** Protect the CMS with app-level auth. You may **skip** and set Secret `CMS_PASSWORD` later (then Redeploy / restart).
+>
+> **IRON RULE ? no prelude:** After Q3 finishes, ask **this** question next. Do **not** first ask whether they want a password / auth / lock. Open the password field (or one chat prompt) immediately; blank/skip is valid.
 
-**Ask (Secrets input or one chat reply):**
+**Ask (Secrets input or one chat reply) ? copy this intent:**
 
-> Optional: set a Control Panel password now? If yes, enter the password to store as Secret **`CMS_PASSWORD`**. Leave blank / skip to keep the panel open for now ? you can add this Secret later and redeploy.
+> Optional: set a CMS password now? If yes, enter the password to store as Secret **`CMS_PASSWORD`**. Leave blank / skip to keep the CMS open for now ? you can add this Secret later and redeploy.
 
 **Why:**
-- Locks the **CMS Control Panel only** (not the whole Repl).
+- Locks the **CMS Control Panel** only (not the whole Repl).
 - Devices still reach WebSocket / brand / uploads without that password.
 - Safer than Replit **whole-site** password protection (that breaks Tizen/BrightSign).
 - Leaving it blank is fine; add `CMS_PASSWORD` later when you want the login page.
@@ -725,6 +748,9 @@ Do **not** ask for screen count. Keep a default `cms.expectedScreens` (e.g. `5`)
 **Reject / clarify:**
 - Do **not** enable Replit **site-wide** password / auth gate for this project.
 - Do **not** put the password in committed source (git, README, pasted into files).
+- Do **not** ask a separate "enable password protection?" question before this step.
+
+**Publish note (mandatory when `CMS_PASSWORD` is set or may be set):** See **Publish health check / readiness probe** ? probe **`/status`**, never rely on `/` redirecting. Starter `cms-auth` serves login at `/` with **HTTP 200** (no redirect loop); still configure the probe to `/status`.
 
 ---
 
@@ -807,6 +833,8 @@ Link an App Storage bucket in the Replit UI. Do **not** set Cloudinary Secrets f
 - If Q4 set a password: create Replit Secret `CMS_PASSWORD` (never commit it).
 - If Q4 blank/skipped: omit it ? panel stays open until they add the Secret later and Redeploy / restart.
 - Do **not** enable Replit whole-site password protection.
+- **Before Publish:** set readiness probe to **`/status`**. Confirm `GET /status` is 200 with no redirects. Do **not** leave Publish probing `/` if auth redirects would break readiness (starter serves login at `/` with 200; still prefer `/status`).
+- Prefer **Reserved VM** for published WebSocket pairing.
 
 ### C. Wire `server.ts`
 
@@ -921,7 +949,9 @@ Do **not**:
 - Omit `[[ports]]` / `deploymentTarget` from `.replit` when setting up for Publish
 - Run **database connection tests**, **WebSocket console tests**, or other post-setup smoke tests unless Preview fails or the user asks
 - **Debug or fix?Supabase** because dev logs show `getaddrinfo ENOTFOUND` or `database connection failure` ?save config and finish setup instead
-- Ask how many screens / devices (? vs >5)
+- Ask a yes/no "do you want a CMS password / enable auth?" **before** Q4 ? after Q3 go **straight** to the CMS password field (blank/skip allowed)
+- Leave Publish readiness probing `/` when `CMS_PASSWORD` is set if that path 303-redirects (use **`/status`**; serve login at `/` with **200**)
+- Enable Replit **whole-site** password instead of `CMS_PASSWORD`
 
 ---
 
@@ -930,7 +960,8 @@ Do **not**:
 | Symptom | Likely cause | Fix |
 |---------|--------------|-----|
 | Agent installs older SDK for supply-chain safety window?| Agent age-gated `@latest` | **Override:** `npm install @tomorrowos/sdk@latest` in Shell until local version = `npm view @tomorrowos/sdk version` |
-| Publish: **api-kind artifact not deployable** | CMS artifact `kind = "api"` or API-only Repl | Set **`kind = "web"`** in `.replit-artifact/artifact.toml`; new **Web app** Repl if needed; `.replit` ports + `deploymentTarget=autoscale` |
+| Publish fails after build: too many redirects / readiness on `/` | Health probe hit password-gated `/` (303 ? `/login` loop) | Set probe to **`GET /status`**; ensure `cms-auth` returns **200** login HTML at `/` (no 303); prefer **Reserved VM**; republish |
+| Publish: **api-kind artifact not deployable** | CMS artifact `kind = "api"` or API-only Repl | Set **`kind = "web"`** in `.replit-artifact/artifact.toml`; new **Web app** Repl if needed; `.replit` ports + Reserved VM / autoscale |
 | Preview empty / wrong app at `/` | Project type API, wrong staticRoot, or stale process | Set project to **Web app**; confirm `staticRoot: public`; stop old servers; restart workspace |
 | TV / browser: WebSocket handshake timeout | Node CMS not running or crash-loop | Fix Run ?`npm run start`; check logs for `listening` |
 | Deploy/Publish fails / `tsx: not found` | `tsx` only in devDependencies | Move `tsx` to `dependencies`, reinstall, keep `start`: `tsx server.ts` |
@@ -946,7 +977,9 @@ Do **not**:
 
 ## Protocol version
 
-`replit-setup/1.17` - aligned with TomorrowOS protocol `1.0` and `@tomorrowos/sdk` store drivers `sqlite` | `supabase` | `postgres` | `memory`.
+`replit-setup/1.18` - aligned with TomorrowOS protocol `1.0` and `@tomorrowos/sdk` store drivers `sqlite` | `supabase` | `postgres` | `memory`.
+
+**Changelog 1.18:** Q4 is asked **immediately after Q3** with no yes/no password prelude. Publish readiness must use **`GET /status`** (and `cms-auth` serves login at `/` with HTTP 200 ? no redirect loop). Prefer **Reserved VM** for WebSockets.
 
 **Changelog 1.17:** Question 4 is optional Control Panel Secret `CMS_PASSWORD` (blank/skip allowed; can set later). Do not use Replit whole-site password. Devices stay reachable without it.
 

package/VERCEL_QUESTIONS.md

@@ -94,7 +94,7 @@ Blank fields -> keep existing `brand.json`. Logo blank -> `./assets/logo.svg`.
 
 ## Q4 - Optional CMS password (paste this entire block)
 
-Optional: set a Control Panel password now?
+Optional: set a CMS password now?
 
 If yes, reply with the password to store as Environment Variable **`CMS_PASSWORD`**.
 

package/VERCEL_SETUP.md

@@ -195,7 +195,7 @@ If the user **skips** a Question 2 option, do **not** invent a substitute questi
 
 If the user says ?just set it up, don?t ask questions,??respond:
 
-> I need a few quick answers from VERCEL_SETUP.md (database — Supabase or Neon preferred — media storage with Cloudinary recommended, branding, and optional Control Panel password). It takes about a minute and ensures the CMS works on Vercel.
+> I need a few quick answers from VERCEL_SETUP.md (database — Supabase or Neon preferred — media storage with Cloudinary recommended, branding, and optional CMS password). It takes about a minute and ensures the CMS works on Vercel.
 
 Then ask **Question 1**.
 
@@ -856,7 +856,7 @@ Set `cmsEndpoint` only if they already know the public `https://?vercel.app` URL
 
 **Ask (Env input or one chat reply):**
 
-> Optional: set a Control Panel password now? If yes, enter the password to store as Environment Variable **`CMS_PASSWORD`**. Leave blank / skip to keep the panel open for now — you can add this later in Vercel → Settings → Environment Variables and redeploy.
+> Optional: set a CMS password now? If yes, enter the password to store as Environment Variable **`CMS_PASSWORD`**. Leave blank / skip to keep the panel open for now — you can add this later in Vercel → Settings → Environment Variables and redeploy.
 
 **Why:**
 - Locks the **CMS Control Panel only** (not the whole deployment).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomorrowos/sdk",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "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/.replit

@@ -7,6 +7,7 @@ run = "npm run start"
 channel = "stable-24_11"
 
 # Expose the CMS HTTP + WebSocket server (TomorrowOS Control Panel at /).
+# Publish readiness: probe GET /status (public). Do not rely on auth redirects from /.
 [[ports]]
 localPort = 3000
 externalPort = 80
@@ -15,3 +16,5 @@ externalPort = 80
 run = ["sh", "-c", "npm run start"]
 deploymentTarget = "autoscale"
 ignorePorts = false
+# Prefer Reserved VM in the Publishing UI for persistent WebSockets.
+# If the UI allows a health/readiness path, set it to /status.

package/templates/cms-starter/cms-auth.ts

@@ -200,12 +200,16 @@ export async function handleCmsAuth(
 
   if (isDevicePublicPath(method, pathname)) return false;
 
-  if (method === "GET" && pathname === "/login") {
+  if ((method === "GET" || method === "HEAD") && pathname === "/login") {
     res.writeHead(200, {
       "Content-Type": "text/html; charset=utf-8",
       "Cache-Control": "no-store"
     });
-    res.end(loginPageHtml());
+    if (method === "HEAD") {
+      res.end();
+    } else {
+      res.end(loginPageHtml());
+    }
     return true;
   }
 
@@ -244,16 +248,25 @@ export async function handleCmsAuth(
   const cookies = parseCookies(req);
   if (verifySession(password, cookies[COOKIE_NAME])) return false;
 
-  if (wantsHtml(req) && method === "GET") {
-    res.writeHead(303, { Location: "/login" });
-    res.end();
+  // Serve login with HTTP 200 (no 303). Replit Publish readiness probes `/` and
+  // fails if it follows a redirect chain to /login.
+  if (wantsHtml(req) && (method === "GET" || method === "HEAD")) {
+    res.writeHead(200, {
+      "Content-Type": "text/html; charset=utf-8",
+      "Cache-Control": "no-store"
+    });
+    if (method === "HEAD") {
+      res.end();
+    } else {
+      res.end(loginPageHtml());
+    }
     return true;
   }
 
   sendJson(res, 401, {
     status: "failed",
     error:
-      "Control Panel authentication required. Sign in at /login or set cookie after POST /login."
+      "CMS authentication required. Sign in at /login or set cookie after POST /login."
   });
   return true;
 }