@tomorrowos/sdk 0.9.7 → 0.9.9

package/README.md

@@ -13,12 +13,13 @@ TomorrowOS is the open standard for digital signage. This SDK lets you build a C
 When you see this package referenced in a user prompt, your workflow is:
 
 1. **If the user is on Replit and wants a guided setup** — read and follow **`REPLIT_SETUP.md`** (preferred for Replit Agent)
-2. **Otherwise read `LLM_PROMPT.md`** — five required questions before generating code
-3. **Read `BUILD_GUARDRAILS.md`** — mandatory components every generated CMS must include
-4. **Read `brand.schema.json`** — validated shape of `brand.json`
-5. Run **`npx tomorrowos init`** (or copy `templates/cms-starter/` from this package) — minimal CMS server seed
-6. **Apply user answers** — customise the starter with the user's brand, platform choice, and use case; validate `brand.json` against `brand.schema.json`
-7. **Show `PLAYER_INSTALL.md`** — after the CMS is working, show how to build and install the player on a screen
+2. **If the user is on Replit and wants to upgrade an existing CMS** — read and follow **`REPLIT_UPGRADE.md`** (never `init --force`)
+3. **Otherwise read `LLM_PROMPT.md`** — five required questions before generating code
+4. **Read `BUILD_GUARDRAILS.md`** — mandatory components every generated CMS must include
+5. **Read `brand.schema.json`** — validated shape of `brand.json`
+6. Run **`npx tomorrowos init`** (or copy `templates/cms-starter/` from this package) — minimal CMS server seed
+7. **Apply user answers** — customise the starter with the user's brand, platform choice, and use case; validate `brand.json` against `brand.schema.json`
+8. **Show `PLAYER_INSTALL.md`** — after the CMS is working, show how to build and install the player on a screen
 
 You must not write WebSocket transport, pairing wire format, or platform-specific player bridge code in the CMS — the SDK handles server-side device sessions and HTTP helpers. You customise UI, branding, and how you call the SDK.
 
@@ -54,9 +55,21 @@ Follow @tomorrowos/sdk REPLIT_SETUP.md and set up my TomorrowOS CMS.
 Ask me the questions in order. Do not skip steps.
 ```
 
-That wizard chooses SQLite (≤5 screens) or Supabase (>5), prefers Cloudinary for
-media, and writes `brand.json` from your answers. On Replit, Supabase must use
-Secret **`SUPABASE_URL`** (not the reserved `DATABASE_URL`).
+That wizard configures Supabase, prefers Cloudinary for media, and writes
+`brand.json` from your answers. On Replit, Supabase must use Secret
+**`SUPABASE_URL`** (not the reserved `DATABASE_URL`).
+
+### Replit upgrade (existing CMS)
+
+In Replit Agent, paste:
+
+```text
+Follow @tomorrowos/sdk REPLIT_UPGRADE.md to upgrade my CMS with the latest SDK.
+```
+
+That protocol installs `@tomorrowos/sdk@latest`, backs up panel/server files,
+diffs `cms-starter` templates (merge — never blind overwrite), and must **not**
+run `init` / delete `data/` or `public/uploads/`.
 
 To switch to Supabase/Postgres manually, edit `.env` / Secrets:
 
@@ -139,6 +152,8 @@ See `PLAYER_INSTALL.md` for installation notes.
 | File | Purpose |
 |------|---------|
 | `LLM_PROMPT.md` | Five-question elicitation for LLMs |
+| `REPLIT_SETUP.md` | Replit Agent guided CMS setup |
+| `REPLIT_UPGRADE.md` | Replit Agent upgrade to latest SDK (no init) |
 | `BUILD_GUARDRAILS.md` | Mandatory CMS components |
 | `PLAYER_INSTALL.md` | Player build / install / pairing |
 | `brand.schema.json` | JSON Schema for `brand.json` |

package/REPLIT_SETUP.md

@@ -230,7 +230,7 @@ Allowed extras (optional): `"build-player": "tomorrowos build --platform tizen"`
     "node": ">=20"
   },
   "dependencies": {
-    "@tomorrowos/sdk": "^0.9.7",
+    "@tomorrowos/sdk": "^0.9.9",
     "dotenv": "^17.2.3",
     "tsx": "^4.19.0"
   },

package/REPLIT_UPGRADE.md

@@ -0,0 +1,205 @@
+# Replit Upgrade Protocol for TomorrowOS CMS
+
+> **This file is a contract for Replit Agent / Replit AI.**  
+> Follow it literally. This protocol **upgrades an existing CMS** to the latest `@tomorrowos/sdk`.  
+> It is **not** a greenfield setup. Do **not** use `REPLIT_SETUP.md` or `LLM_PROMPT.md` for this flow unless the user explicitly asks for a full re-setup.
+
+---
+
+## User trigger (copy-paste)
+
+When a human pastes a prompt like this, **read this file and execute the upgrade steps immediately** (no questionnaire):
+
+```text
+Follow @tomorrowos/sdk REPLIT_UPGRADE.md to upgrade my CMS with the latest SDK.
+Do not run init or init --force. Do not delete data/ or public/uploads/.
+Compare cms-starter template files and merge carefully — do not blindly overwrite custom changes.
+```
+
+Alternate triggers that also activate this protocol:
+
+- “Upgrade TomorrowOS on Replit using REPLIT_UPGRADE.md”
+- “Update my CMS to the latest @tomorrowos/sdk”
+- “Follow REPLIT_UPGRADE.md”
+
+When any of these triggers fire:
+
+1. **Ignore `LLM_PROMPT.md` and `REPLIT_SETUP.md` questionnaires** — this is an upgrade, not setup Q&A.
+2. **Do not** reinvent pairing, WebSocket, or playlist servers.
+3. Preserve project data and custom UI/server wiring.
+
+---
+
+## Hard rules (non-negotiable)
+
+1. **Do NOT** run `npx @tomorrowos/sdk init` or `npx @tomorrowos/sdk init --force` (or any command that re-scaffolds / overwrites the project from the starter). That would wipe customisations.
+2. **Do NOT** delete `data/` or `public/uploads/` (or move them aside permanently). Pairings, playlists, and local media must survive the upgrade.
+3. **Do NOT** invent or rotate Secrets (`SUPABASE_URL`, Cloudinary keys, etc.). Keep existing Secrets / `.env`.
+4. **Do NOT** blindly overwrite `public/methods.js`, `public/index.html`, `public/panel.css`, or `server.ts` with template copies. Always **diff → report → merge only with user consent** (or apply surgical patches that preserve custom code).
+5. **Do NOT** change artifact `kind` to `api`. CMS must stay a **web** app if already web.
+6. **Do NOT** treat Replit Preview Supabase `ENOTFOUND` / `getaddrinfo` as an upgrade failure. Configure-only; DB often works after **Publish**.
+7. Prefer **`npm install @tomorrowos/sdk@latest`** over pinning an older version unless the user named a specific version.
+8. Keep `tsx` available at runtime (`dependencies`, not only `devDependencies`) if the project already relies on `tsx server.ts`.
+
+---
+
+## Preflight (record before changing anything)
+
+Capture and remember:
+
+| Item | How |
+|------|-----|
+| **Old SDK version** | `package.json` → `dependencies["@tomorrowos/sdk"]`, and/or `npm ls @tomorrowos/sdk --depth=0` |
+| **Run command** | `.replit` `run` / `[deployment].run`, else `package.json` scripts (`dev` / `start`) |
+| **Project root** | Confirm `server.ts` (or equivalent) and `public/` exist — this is an existing CMS |
+
+If `@tomorrowos/sdk` is not a dependency, stop and tell the user this project does not look like a TomorrowOS CMS — offer `REPLIT_SETUP.md` instead. Do **not** run `init` unless they explicitly switch to setup.
+
+---
+
+## Upgrade steps (exact order)
+
+### 1. Stop the running server
+
+If a TomorrowOS / `tsx server.ts` / `npm run start|dev` process is active, stop it (Replit Stop / kill the listening process). Port conflicts (`EADDRINUSE`) block a clean restart.
+
+### 2. Backup merge candidates (required)
+
+Before any UI/server merge, copy the current files to a timestamped backup folder under the project (e.g. `.tomorrowos-upgrade-backup/<ISO-timestamp>/`):
+
+- `public/methods.js`
+- `public/index.html`
+- `public/panel.css`
+- `server.ts`
+
+Also back up `package.json` (version pin record).
+
+**Do not** put backups inside `data/` or `public/uploads/`.  
+Record the **backup path** for the final report.
+
+### 3. Install latest SDK
+
+```bash
+npm install @tomorrowos/sdk@latest
+```
+
+### 4. Verify `package.json` dependency
+
+Confirm `dependencies["@tomorrowos/sdk"]` reflects a newer / latest range (or exact version after install).
+
+- If `package.json` did not update, set `"@tomorrowos/sdk": "^<installed version>"` (or `@latest` resolution result) and run:
+
+```bash
+npm install
+```
+
+- Confirm `node_modules/@tomorrowos/sdk/package.json` `"version"` is the **new** version.
+
+Record **new SDK version** for the final report.
+
+### 5. Template compare (merge — never blind overwrite)
+
+Compare the project files with the **installed** starter template:
+
+**Template root:**
+
+`node_modules/@tomorrowos/sdk/templates/cms-starter/`
+
+**Always compare at least:**
+
+| Project file | Template file |
+|--------------|---------------|
+| `public/methods.js` | `templates/cms-starter/public/methods.js` |
+| `public/index.html` | `templates/cms-starter/public/index.html` |
+| `public/panel.css` | `templates/cms-starter/public/panel.css` |
+| `server.ts` | `templates/cms-starter/server.ts` |
+
+**Also notice (optional extras in newer SDKs):**
+
+- `public/assets/player-download/*` (Download Players assets)
+- Any new starter files that the panel references
+
+**Agent behaviour for diffs:**
+
+1. Summarise meaningful differences (new status UI, buttons, API routes usage, store wiring helpers, CSS classes, etc.).
+2. Classify each file:
+
+   | Classification | Meaning |
+   |----------------|---------|
+   | **No merge needed** | Project already has the feature / only whitespace differs |
+   | **Safe additive merge** | Template adds new sections the project lacks (e.g. Server status card, Download Players) without conflicting customs |
+   | **Needs human decision** | Both sides edited the same regions — do **not** overwrite; propose a patch or ask |
+
+3. **Default:** report the recommendation and wait for confirmation before applying merges that touch customised regions.  
+   If the user already said “upgrade and apply safe merges”, apply **only additive / non-conflicting** changes, and list anything skipped.
+4. When merging `server.ts`: preserve existing Secrets wiring (`SUPABASE_URL`, Cloudinary, `createTomorrowOSStore`, `staticRoot`, `host: "0.0.0.0"`, `PORT`). Prefer bringing in new SDK usage patterns without dropping production config.
+5. When merging panel files: preserve custom branding, copy, and business-specific UI the starter does not know about.
+
+**Forbidden:** `cp -r node_modules/@tomorrowos/sdk/templates/cms-starter/* .` or wholesale replace of `public/` / `server.ts`.
+
+### 6. Restart the server
+
+Start with the project’s normal Replit run command:
+
+1. Prefer `.replit` `run` value if present.
+2. Else `npm run start` if that is the Deploy / Publish entrypoint.
+3. Else `npm run dev` for iterative Preview (starter default).
+
+Confirm logs show something like `[TomorrowOS] listening on http://0.0.0.0:<port>`.
+
+### 7. Smoke check (minimal)
+
+After the server is up:
+
+1. Preview Control Panel at `/` loads.
+2. Check playlists still load (`GET /playlists` or panel Playlists list).
+3. Check devices still load (`GET /devices` or Paired devices section).
+4. If the new SDK includes Server status UI, note that Supabase may show **Warning** in Replit Preview (`ENOTFOUND`) — that is expected; not an upgrade failure.
+
+**Do not** run long Supabase/Cloudinary/WebSocket test suites.
+
+---
+
+## Final report (required)
+
+Tell the user clearly:
+
+1. **SDK version:** `old → new` (e.g. `0.9.5 → 0.9.8`)
+2. **Backup path:** where the pre-merge copies live
+3. **Template merge:** which files were compared; what was merged / skipped / needs their decision
+4. **Data preserved:** confirm `data/` and `public/uploads/` were not deleted
+5. **Runtime:** which command restarted the server
+6. **Smoke:** whether playlists and devices still load (yes / no / could not verify + why)
+7. **Next step:** re-Publish the Repl if they use Deployments, so production picks up the new dependency and merged UI
+
+---
+
+## What not to do
+
+- ❌ `npx @tomorrowos/sdk init` / `init --force`
+- ❌ Delete or empty `data/`, `public/uploads/`, or SQLite DB files
+- ❌ Blind overwrite of customised panel / `server.ts`
+- ❌ Re-run full `REPLIT_SETUP.md` questionnaire during upgrade
+- ❌ “Fix” Supabase by removing `SUPABASE_URL` because Preview logs show `ENOTFOUND`
+- ❌ Switch Publish mode to Static-only or artifact `kind = "api"`
+- ❌ Commit real secrets into git
+
+---
+
+## Failure recovery (upgrade-specific)
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| Panel looks old after `npm install` | Dependency updated but UI not merged | Diff template `public/*` → merge carefully from backup/template |
+| `Cannot find module '@tomorrowos/sdk'` | Install failed / wrong cwd | Re-run `npm install @tomorrowos/sdk@latest` at project root |
+| Playlists/devices empty after upgrade | Accidental DB wipe or wrong Secrets | Restore `data/` from backup/hosting; confirm `SUPABASE_URL` / `TOMORROWOS_STORE` unchanged |
+| `EADDRINUSE` | Old server still running | Stop old process, restart once |
+| Preview Supabase Warning / ENOTFOUND | Replit Preview DNS | Expected — validate on published URL |
+
+---
+
+## Protocol version
+
+`replit-upgrade/1.0` — pairs with `@tomorrowos/sdk` packages that ship `templates/cms-starter` and this file.
+
+**Changelog 1.0:** Initial upgrade-only Agent contract: install `@latest`, backup, template diff/merge (no init, no data wipe), restart, report versions + smoke.

package/dist/server-status.js

@@ -23,14 +23,14 @@ function resolveDatabaseProvider(env) {
     if (driver === "supabase" || (!driver && env.SUPABASE_URL)) {
         return {
             provider: "supabase",
-            label: "Supabase",
+            label: "Database",
             configured: !!env.SUPABASE_URL || !!env.DATABASE_URL
         };
     }
     if (driver === "postgres" || (!driver && hasUrl && !env.SUPABASE_URL)) {
         return {
             provider: "postgres",
-            label: "Postgres",
+            label: "Database",
             configured: hasUrl
         };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomorrowos/sdk",
-  "version": "0.9.7",
+  "version": "0.9.9",
   "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",
@@ -20,6 +20,7 @@
     "README.md",
     "LLM_PROMPT.md",
     "REPLIT_SETUP.md",
+    "REPLIT_UPGRADE.md",
     "BUILD_GUARDRAILS.md",
     "PLAYER_INSTALL.md",
     "brand.schema.json",

package/templates/cms-starter/package.json

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