@tomorrowos/sdk 0.7.5 → 0.7.6

package/REPLIT_SETUP.md

@@ -30,6 +30,98 @@ 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.6",
+    "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. `package.json` has `scripts.start` = `tsx server.ts`
+2. `tsx` is listed under `dependencies` (runtime-safe for Deploy)
+3. Dependency is `@tomorrowos/sdk` (not a fork or vendored rewrite)
+4. `.replit` Run + `[deployment].run` use `npm run start`
+5. Node is **20+**
+6. `npm run start` prints `[TomorrowOS] listening on http://0.0.0.0:...`
+7. Browser WebSocket test to `wss://<host>/` succeeds
+8. Secrets required by the Q&A answers are set (`SUPABASE_URL`, Cloudinary, etc.)
+
+If any item fails, fix it before finishing.
 
 ---
 
@@ -251,20 +343,42 @@ 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
 
 ```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”
+### F. Verify before telling the user “done”
 
 1. Open the Control Panel URL.
 2. `GET /brand.json` → 200 and correct `name` / colours.
@@ -276,9 +390,11 @@ ws.onopen = () => console.log("WS OK");
 ws.onerror = (e) => console.log("WS ERR", e);
 ```
 
+4. 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/`
@@ -300,9 +416,11 @@ 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
 
 ---
 
@@ -328,7 +446,9 @@ 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` |
+| 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"]` |
 | 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.6",
   "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.6",
   "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.6",
+    "dotenv": "^17.2.3",
+    "tsx": "^4.19.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
-    "tsx": "^4.19.0",
     "typescript": "^5.5.0"
   }
 }