@tomorrowos/sdk 0.7.5 → 0.7.7

package/REPLIT_SETUP.md

@@ -30,6 +30,139 @@ Alternate triggers that also activate this protocol:
    - HTTP Control Panel loads
    - `GET /brand.json` returns 200
    - WebSocket upgrade on `wss://<repl-host>/` succeeds (critical for TV pairing)
+7. **Follow the Runtime & Replit publish rules below exactly.** A project that cannot Deploy / Publish on Replit is incomplete.
+
+---
+
+## Runtime & Replit publish rules (mandatory)
+
+These rules exist so the CMS can be **Run** and **Published/Deployed** on Replit without custom build steps.
+
+### Runtime
+
+- The server **must** run directly from source using `tsx server.ts`.
+- **Do not** compile to `dist/` as the production entrypoint.
+- **Do not** replace `@tomorrowos/sdk` with a hand-rolled server, Express wrapper that drops WebSocket upgrades, or a different package name.
+- Always depend on **`@tomorrowos/sdk`**.
+- **`tsx` must be available at runtime.** Prefer putting `tsx` in **`dependencies`** (not only `devDependencies`) so Replit Deploy / production installs still include it.
+- Use **Node.js 20 or newer** (set in `.replit` / Nix / package engines if the workspace asks).
+
+### Expected `package.json` scripts
+
+```json
+{
+  "scripts": {
+    "dev": "tsx watch server.ts",
+    "start": "tsx server.ts"
+  }
+}
+```
+
+Allowed extras (optional): `"build-player": "tomorrowos build --platform tizen"`.  
+**Forbidden as the Deploy entrypoint:** `node dist/server.js`, `next start`, static-only hosts, or any command that does not start `TomorrowOS.listen(...)`.
+
+### Minimal dependency expectations
+
+```json
+{
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@tomorrowos/sdk": "^0.7.7",
+    "dotenv": "^17.2.3",
+    "tsx": "^4.19.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.5.0"
+  },
+  "scripts": {
+    "dev": "tsx watch server.ts",
+    "start": "tsx server.ts"
+  }
+}
+```
+
+Bump `@tomorrowos/sdk` to the latest published version when scaffolding.
+
+### Replit Run command
+
+```text
+npm run start
+```
+
+### Replit deployment / publish command
+
+```text
+npm run start
+```
+
+### `.replit` (create or edit)
+
+```toml
+run = "npm run start"
+
+[deployment]
+run = ["sh", "-c", "npm run start"]
+```
+
+If the workspace already has a `.replit`, **merge** these keys — do not wipe unrelated Nix/modules config. Ensure the effective Run and Deployment commands remain `npm run start`.
+
+### Publish readiness checklist (before telling the user “done”)
+
+1. Replit project type is **Web** (not API)
+2. `package.json` has `scripts.start` = `tsx server.ts`
+3. `tsx` is listed under `dependencies` (runtime-safe for Deploy)
+4. Dependency is `@tomorrowos/sdk` (not a fork or vendored rewrite)
+5. `.replit` Run + `[deployment].run` use `npm run start`
+6. Node is **20+**
+7. Preview at `/` shows the TomorrowOS Control Panel (not Canvas, not another app)
+8. Stale processes / port conflicts cleared before publish
+9. `npm run start` prints `[TomorrowOS] listening on http://0.0.0.0:...`
+10. Browser WebSocket test to `wss://<host>/` succeeds
+11. Secrets required by the Q&A answers are set (`SUPABASE_URL`, Cloudinary, etc.)
+
+If any item fails, fix it before finishing.
+
+### Preview requirements (Replit workspace)
+
+The Replit **Preview** must show the **TomorrowOS Control Panel** at `/` (root URL).
+
+- `GET /` must serve the CMS Control Panel (`public/index.html` via `staticRoot: public`).
+- **Do not** serve another app, API-only landing page, or placeholder at `/`.
+- **Do not** use or rely on the **Canvas** preview for this CMS — use the normal **Web** preview in the browser.
+- If the preview is **empty** or shows the wrong thing:
+  1. Confirm the Replit project type is **Web**, not **API**.
+  2. Confirm `npm run start` is running and logs show `[TomorrowOS] listening on http://0.0.0.0:...`
+  3. Confirm `server.ts` calls `tomorrowos.listen({ staticRoot: join(__dirname, "public"), ... })`
+  4. Open the preview URL directly (not Canvas) and hard-refresh.
+
+### Before publishing / deploying
+
+Do this **before** clicking Publish / Deploy:
+
+1. **Stop** stale running processes (old `tsx` / `node` servers from prior attempts).
+2. **Clear** old background tasks from previous failed projects (Replit Shell / Processes panel).
+3. **Ensure no old process is holding the port** (`EADDRINUSE` in logs = something still bound to `PORT`).
+4. **Restart the Replit workspace** if the port is stuck or preview still shows a ghost app.
+5. Run `npm run start` once cleanly and confirm Control Panel loads at `/` in preview.
+
+### After publishing / deploying
+
+Tell the user their live CMS URLs:
+
+- **Control Panel (browser):** `https://YOUR-REPLIT-DOMAIN`
+- **TV / player CMS endpoint:** same HTTPS origin, e.g. `https://YOUR-REPLIT-DOMAIN/` (player converts `https://` → `wss://` for WebSocket)
+
+Replace `YOUR-REPLIT-DOMAIN` with the actual published hostname (e.g. `my-cms.replit.app`).
+
+Verify after publish:
+
+1. `https://YOUR-REPLIT-DOMAIN/` shows the Control Panel (not empty, not API docs).
+2. `https://YOUR-REPLIT-DOMAIN/brand.json` returns 200.
+3. WebSocket to `wss://YOUR-REPLIT-DOMAIN/` succeeds.
 
 ---
 
@@ -251,24 +384,51 @@ CLOUDINARY_API_SECRET=...
 - Supabase path: pass `databaseUrl: process.env.SUPABASE_URL || process.env.DATABASE_URL` into `createTomorrowOSStore`
 - Keep TomorrowOS event handlers from the starter (paired / online policy push)
 
-### D. Install and run
+### D. Runtime files for Replit publish
+
+1. Ensure `package.json` scripts are exactly:
+
+```json
+"dev": "tsx watch server.ts",
+"start": "tsx server.ts"
+```
+
+2. Move / keep `tsx` in **`dependencies`** so Deploy works.
+3. Set `engines.node` to `>=20`.
+4. Create or update `.replit`:
+
+```toml
+run = "npm run start"
+
+[deployment]
+run = ["sh", "-c", "npm run start"]
+```
+
+### E. Install and run
+
+**Before starting:** stop stale processes, clear old background tasks, free the port if needed, restart workspace if stuck.
 
 ```bash
 npm install
-npm run dev
+npm run start
 ```
 
+(Use `npm run dev` only for local edit/watch. **Publish / Deploy / Replit Run must use `npm run start`.**)
+
 Confirm logs contain something like:
 
 ```text
 [TomorrowOS] listening on http://0.0.0.0:<PORT>
 ```
 
-### E. Verify before telling the user “done”
+Confirm the **Web preview** (not Canvas) shows the Control Panel at `/`.
 
-1. Open the Control Panel URL.
-2. `GET /brand.json` → 200 and correct `name` / colours.
-3. In browser console on the Control Panel origin:
+### F. Verify before telling the user “done”
+
+1. Replit project type is **Web**; preview at `/` shows Control Panel (not empty, not Canvas-only).
+2. Open the Control Panel URL.
+3. `GET /brand.json` → 200 and correct `name` / colours.
+4. In browser console on the Control Panel origin:
 
 ```javascript
 const ws = new WebSocket(location.origin.replace(/^http/, "ws") + "/");
@@ -276,15 +436,18 @@ ws.onopen = () => console.log("WS OK");
 ws.onerror = (e) => console.log("WS ERR", e);
 ```
 
+5. Confirm the **Publish readiness checklist** in **Runtime & Replit publish rules**.
+
 If WebSocket fails, fix Run command / process crash / sleep **before** asking the user to pair a TV.
 
-### F. Tell the user next steps (no code)
+### G. Tell the user next steps (no code)
 
 1. Keep this Repl **running** (Always On if available).
-2. On the TomorrowOS player, enter the CMS URL: `https://<your-repl>.replit.app/`
-3. Enter the 6-character pairing code from the screen into the Control Panel.
-4. Create a playlist, upload media, Publish to the device.
-5. Point them at `PLAYER_INSTALL.md` in the SDK for player install details.
+2. **Published Control Panel URL:** `https://YOUR-REPLIT-DOMAIN`
+3. On the TomorrowOS player, enter the CMS URL: `https://YOUR-REPLIT-DOMAIN/`
+4. Enter the 6-character pairing code from the screen into the Control Panel.
+5. Create a playlist, upload media, Publish to the device.
+6. Point them at `PLAYER_INSTALL.md` in the SDK for player install details.
 
 ---
 
@@ -300,9 +463,13 @@ Do **not** ask the user how to implement:
 Do **not**:
 
 - Replace `@tomorrowos/sdk` with a hand-rolled server
+- Change the production start command away from `tsx server.ts` / `npm run start`
 - Point Supabase at Replit’s reserved `DATABASE_URL` when `SUPABASE_URL` should be used
 - Skip Cloudinary recommendation without stating the persistence tradeoff
 - Claim uploads are “permanent” on Replit local disk without Object Storage or Cloudinary
+- Leave `tsx` only in `devDependencies` if the Deploy pipeline installs production deps only
+- Use Canvas preview as the primary CMS verification surface
+- Serve a different app or API-only response at `/` instead of the Control Panel
 
 ---
 
@@ -328,7 +495,11 @@ TOMORROWOS_STORE=sqlite
 
 | Symptom | Likely cause | Fix |
 |---------|--------------|-----|
-| TV / browser: WebSocket handshake timeout | Node CMS not running or crash-loop | Fix Run → `npm start` / `npm run dev`; check logs for `listening` |
+| Preview empty / wrong app at `/` | Project type API, wrong staticRoot, or stale process | Set project to **Web**; 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` |
+| Deploy runs wrong process | `.replit` / Deployment not `npm run start` | Set `run = "npm run start"` and `[deployment] run = ["sh", "-c", "npm run start"]` |
+| `EADDRINUSE` on start | Old process holding port | Stop stale processes, clear background tasks, restart Repl |
 | Upload: `storage.objects.create` denied | Replit Object Storage IAM | Fix Object Storage permissions **or** switch to Cloudinary |
 | Upload OK then thumbnails vanish later | Non-persistent `public/uploads` | Object Storage or Cloudinary |
 | Supabase connection errors | Wrong URL or using reserved `DATABASE_URL` | Use `SUPABASE_URL` + `TOMORROWOS_STORE=supabase` |

package/package.json

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

@@ -0,0 +1,4 @@
+run = "npm run start"
+
+[deployment]
+run = ["sh", "-c", "npm run start"]

package/templates/cms-starter/package.json

@@ -1,21 +1,24 @@
 {
   "name": "my-cms",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "description": "CMS server on @tomorrowos/sdk. Add your UI (React, static files, etc.) alongside this server.",
   "private": true,
   "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
     "dev": "tsx watch server.ts",
     "start": "tsx server.ts",
     "build-player": "tomorrowos build --platform tizen"
   },
   "dependencies": {
-    "@tomorrowos/sdk": "^0.7.5",
-    "dotenv": "^17.2.3"
+    "@tomorrowos/sdk": "^0.7.7",
+    "dotenv": "^17.2.3",
+    "tsx": "^4.19.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
-    "tsx": "^4.19.0",
     "typescript": "^5.5.0"
   }
 }