@tomorrowos/sdk 0.7.8 → 0.7.9

package/REPLIT_SETUP.md

@@ -3,7 +3,7 @@
 > **This file is a contract for Replit Agent / Replit AI.**  
 > Follow it literally. Ask questions in order. Do not invent answers. Do not write or rewrite application logic until the Q&A is complete. Prefer configuring Secrets, `.env`, `brand.json`, and `server.ts` store wiring over inventing a custom CMS.
 >
-> **On Replit, this file is the ONLY questionnaire.** Do **not** use `LLM_PROMPT.md` questions.
+> **On Replit, this file is the ONLY questionnaire.**
 
 ## User trigger (copy-paste)
 
@@ -22,6 +22,8 @@ Alternate triggers that also activate this protocol:
 
 When any of these triggers fire, **ignore `LLM_PROMPT.md` entirely** for the Q&A phase.
 
+**Before Question 1:** ensure the Replit workspace is a **Web app** project (see **Deployability: Web app artifact**). If the project is API-only or not publishable, fix that first — do not continue the questionnaire on a broken project type.
+
 ---
 
 ## Questionnaire scope (STRICT — read before asking anything)
@@ -37,18 +39,6 @@ Replit Agent must ask **only** the questions defined in **this file**, in **this
 
 **That is the complete list.** There are no other setup questions.
 
-### Forbidden questions (never ask on Replit setup)
-
-Do **not** ask questions from `LLM_PROMPT.md` or improvise similar ones, including but not limited to:
-
-- ❌ “Which screen platform will you manage? … Tizen … BrightSign …” as a **standalone first question**
-- ❌ “What's the primary use case?” as a **standalone** question (use case is collected **inside Question 4** only)
-- ❌ “Where will the CMS server run? … here / vercel / railway …” — on Replit, hosting is always **`here`**; set `cms.hostingTarget: "here"` without asking
-- ❌ Separate “brand identity” interview before Question 4 (colours, logo, name belong in **Question 4** only)
-- ❌ “How many screens?” asked **again** after Question 1 (you already have `cms.expectedScreens`)
-- ❌ Any technical implementation question (WebSocket library, pairing format, etc.)
-
-**Target platform (`tizen` / `brightsign`):** collect only as **item 8 inside Question 4**, not as its own step.
 
 If the user volunteers extra info early (e.g. brand name before Q4), **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 (or Q1, Q3, Q4 if ≤5 screens) are complete.
 
@@ -83,6 +73,97 @@ Never insert extra questions between these steps.
 
 ---
 
+## Deployability: Web app artifact (mandatory — fixes “api-kind not deployable”)
+
+TomorrowOS CMS is a **user-facing Web app** (Control Panel at `/` + WebSocket for TVs). Replit must treat it as a **Web app** artifact, **not** an API-only / backend-library project.
+
+### Create the project correctly (do this first)
+
+When scaffolding a **new** Repl:
+
+1. On the Replit homepage, open the artifact-type dropdown and choose **Web app** (not API, not “Backend only”, not Agent & Automation-only).
+2. **Do not** create an “API server” artifact as the only publishable output.
+3. Describe the project as: *“TomorrowOS digital signage CMS — web Control Panel at `/` with WebSocket device pairing.”*
+4. Run `npx @tomorrowos/sdk init` at the project root (or merge the cms-starter template).
+
+**Forbidden setups that cause publish failure:**
+
+- ❌ Project / primary artifact classified as **API** (`api-kind` artifact)
+- ❌ Backend-only Express/Fastify service with **no** `staticRoot` / Control Panel at `/`
+- ❌ Splitting CMS into a non-publishable API artifact + separate unpublished frontend
+- ❌ **Static Deployment** as the publish type (TomorrowOS needs a **live Node server** for WebSocket)
+- ❌ `deploymentTarget` or publish mode that only serves static files without `tsx server.ts`
+
+### What “deployable” means for TomorrowOS
+
+Replit Publish must see:
+
+- A **Web app** that serves HTML at `GET /` (`public/index.html`)
+- 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
+
+### `.replit` (create or replace — required for publish)
+
+Use this **minimum** configuration (merge with existing Nix/modules if needed; **do not** remove `[[ports]]` or `deploymentTarget`):
+
+```toml
+entrypoint = "server.ts"
+modules = ["nodejs-20"]
+hidden = [".config", "package-lock.json"]
+run = "npm run start"
+
+[nix]
+channel = "stable-24_11"
+
+[[ports]]
+localPort = 3000
+externalPort = 80
+
+[deployment]
+run = ["sh", "-c", "npm run start"]
+deploymentTarget = "autoscale"
+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).
+- Keep exactly **one** primary `[[ports]]` entry with `externalPort = 80` for the CMS server.
+- If `.replit` contains `[[artifacts]]` with **only** `artifacts/api-server` and Publish fails, **convert to Web app layout** or create a **new Web app** Repl and migrate — do not tell the user publish succeeded.
+
+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`.
+
+### Publishing pane (human + Agent)
+
+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.
+
+After Publish, the public URL is:
+
+`https://YOUR-REPLIT-DOMAIN`
+
+### If Publish says “api-kind artifact … not deployable”
+
+**Do not** keep retrying publish unchanged. Fix in this order:
+
+1. Verify homepage artifact type is **Web app**; if the Repl was created as API-only, **create a new Web app Repl** and re-run this setup (fastest fix).
+2. Replace `.replit` with the template above (`entrypoint`, `modules`, `[[ports]]`, `deploymentTarget = "autoscale"`).
+3. Confirm `server.ts` calls `tomorrowos.listen({ staticRoot: join(__dirname, "public"), host: "0.0.0.0", port: Number(process.env.PORT) || 3000 })`.
+4. Confirm `GET /` returns Control Panel HTML (not JSON-only API root).
+5. In Publishing, switch to **Autoscale** if currently Static.
+6. Restart workspace → `npm run start` → Publish again.
+
+Tell the user plainly if step 1 requires a new Repl — API-only projects cannot publish a browser CMS without reclassification.
+
+---
+
 ## Runtime & Replit publish rules (mandatory)
 
 These rules exist so the CMS can be **Run** and **Published/Deployed** on Replit without custom build steps.
@@ -119,7 +200,7 @@ Allowed extras (optional): `"build-player": "tomorrowos build --platform tizen"`
     "node": ">=20"
   },
   "dependencies": {
-    "@tomorrowos/sdk": "^0.7.8",
+    "@tomorrowos/sdk": "^0.7.9",
     "dotenv": "^17.2.3",
     "tsx": "^4.19.0"
   },
@@ -150,28 +231,40 @@ npm run start
 
 ### `.replit` (create or edit)
 
+Use the full template in **Deployability: Web app artifact** (not run/deployment lines only). Minimum:
+
 ```toml
+entrypoint = "server.ts"
+modules = ["nodejs-20"]
 run = "npm run start"
 
+[[ports]]
+localPort = 3000
+externalPort = 80
+
 [deployment]
 run = ["sh", "-c", "npm run start"]
+deploymentTarget = "autoscale"
+ignorePorts = false
 ```
 
-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`.
+If the workspace already has a `.replit`, **merge** these keys — do not wipe unrelated Nix/modules config. Ensure Run, Deployment, **ports**, and **deploymentTarget** are correct.
 
 ### 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.)
+1. Replit project / primary artifact is **Web app** (not API-only / `api-kind`)
+2. `.replit` has `entrypoint = "server.ts"`, `modules = ["nodejs-20"]`, `[[ports]]` with `externalPort = 80`, `deploymentTarget = "autoscale"`
+3. Publishing type is **Autoscale** or **Reserved VM** (not Static-only)
+4. `package.json` has `scripts.start` = `tsx server.ts`
+5. `tsx` is listed under `dependencies` (runtime-safe for Deploy)
+6. Dependency is `@tomorrowos/sdk` (not a fork or vendored rewrite)
+7. `.replit` Run + `[deployment].run` use `npm run start`
+8. Node is **20+**
+9. Preview at `/` shows the TomorrowOS Control Panel (not Canvas, not another app, not API JSON)
+10. Stale processes / port conflicts cleared before publish
+11. `npm run start` prints `[TomorrowOS] listening on http://0.0.0.0:...`
+12. Browser WebSocket test to `wss://<host>/` succeeds
+13. Secrets required by the Q&A answers are set (`SUPABASE_URL`, Cloudinary, etc.)
 
 If any item fails, fix it before finishing.
 
@@ -352,8 +445,7 @@ Tell the user:
 > 5. **Text colour** (hex, optional — default `#0A0908`)
 > 6. **Secondary / accent colour** (hex, optional)
 > 7. **Logo** — upload an SVG/PNG into the project, or give a URL I can fetch into `./assets/`
-> 8. **Target platforms** — `tizen`, `brightsign`, or both
-> 9. **Use case** — one of: `restaurant`, `retail`, `corporate`, `wayfinding`, `transit`, `other`
+
 
 If the user only gives a name and primary colour, use defaults for the rest and say what you assumed.
 
@@ -393,7 +485,9 @@ Set `cms.expectedScreens` from Question 1 (do not ask screen count again). Alway
 
 Run these steps in order. Tick mentally; do not skip.
 
-### A. Seed the project
+### A. Seed the project (Web app first)
+
+**If creating a new Repl:** choose **Web app** on the Replit homepage before `init`.
 
 ```bash
 npx @tomorrowos/sdk@latest init .
@@ -448,14 +542,7 @@ CLOUDINARY_API_SECRET=...
 
 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"]
-```
+4. Create or update `.replit` using the **Deployability** template (`entrypoint`, `modules`, `[[ports]]`, `deploymentTarget = "autoscale"`).
 
 ### E. Install and run
 
@@ -528,6 +615,8 @@ Do **not**:
 - 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
+- Create the Repl as **API-only** or publish with **Static Deployment** only
+- Omit `[[ports]]` / `deploymentTarget` from `.replit` when setting up for Publish
 
 ---
 
@@ -553,7 +642,8 @@ TOMORROWOS_STORE=sqlite
 
 | Symptom | Likely cause | Fix |
 |---------|--------------|-----|
-| 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 |
+| Publish: **api-kind artifact not deployable** | Repl created as API-only, or missing Web app + ports | New **Web app** Repl **or** fix `.replit` (`entrypoint`, `[[ports]]`, `deploymentTarget=autoscale`); serve Control Panel at `/` |
+| 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` |
 | Deploy runs wrong process | `.replit` / Deployment not `npm run start` | Set `run = "npm run start"` and `[deployment] run = ["sh", "-c", "npm run start"]` |
@@ -567,6 +657,6 @@ TOMORROWOS_STORE=sqlite
 
 ## Protocol version
 
-`replit-setup/1.1` — aligned with TomorrowOS protocol `1.0` and `@tomorrowos/sdk` store drivers `sqlite` | `supabase` | `postgres` | `memory`.
+`replit-setup/1.2` — aligned with TomorrowOS protocol `1.0` and `@tomorrowos/sdk` store drivers `sqlite` | `supabase` | `postgres` | `memory`.
 
-**Changelog 1.1:** strict questionnaire scope; Replit must not use `LLM_PROMPT.md` questions (e.g. standalone target-platform prompt).
+**Changelog 1.2:** Web app deployability rules — avoid `api-kind` publish failure; full `.replit` with `[[ports]]`, `deploymentTarget = "autoscale"`, `entrypoint = "server.ts"`.

package/package.json

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

package/templates/cms-starter/.replit

@@ -1,4 +1,17 @@
+entrypoint = "server.ts"
+modules = ["nodejs-20"]
+hidden = [".config", "package-lock.json"]
 run = "npm run start"
 
+[nix]
+channel = "stable-24_11"
+
+# Expose the CMS HTTP + WebSocket server (TomorrowOS Control Panel at /).
+[[ports]]
+localPort = 3000
+externalPort = 80
+
 [deployment]
 run = ["sh", "-c", "npm run start"]
+deploymentTarget = "autoscale"
+ignorePorts = false

package/templates/cms-starter/package.json

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

package/LLM_PROMPT.md

@@ -1,173 +0,0 @@
-# Elicitation Protocol for TomorrowOS CMS Projects
-
-> **This file is the contract between TomorrowOS and any LLM generating code using this package. You must follow it literally. Do not skip questions, do not infer answers, do not start writing code until the protocol is complete.**
-
-> **Replit Agent:** if the user is setting up a CMS on Replit (or pastes a prompt that mentions `REPLIT_SETUP.md`), follow **`REPLIT_SETUP.md` only** — not this file. Do **not** ask `LLM_PROMPT.md` questions (e.g. standalone “Which screen platform will you manage?”). Replit uses four questions: screen count → optional Supabase → media storage → brand (including platform and use case inside Question 4).
-
-You are generating a digital signage CMS using `@tomorrowos/sdk`. The user has asked you to build something like "a CMS for my restaurant" or "a signage dashboard for my retail network". Before you write any code, you must gather five pieces of information from the user.
-
-Ask each question in order. If the user answers multiple at once, record those and skip ahead. If the user hasn't given you an answer to a specific field, do not invent one — ask the question explicitly.
-
----
-
-## Question 1 — Target platform
-
-**Ask exactly:**
-
-> "Which screen platform will you manage? TomorrowOS V1 fully supports Samsung Tizen (commercial signage displays) and BrightSign (media players). Which would you like to target?"
-
-**Valid answers:** `tizen`, `brightsign`, or `both`
-
-**If the user names a platform not in V1** (webOS, Android, ChromeOS, Windows), respond:
-
-> "That platform is planned for a later release. For V1, the supported options are Tizen and BrightSign. Which would you like to use for now?"
-
-**Store answer as:** `targetPlatforms` array in `brand.json`
-
----
-
-## Question 2 — Brand identity
-
-**Ask exactly:**
-
-> "What's the name of the product or company this CMS is for? I'll also need:
->
-> - A logo file (SVG preferred, PNG acceptable — or a URL I can fetch)
-> - A primary brand colour (hex format, e.g. `#FF8A3D`)
-> - Optional: a secondary/accent colour"
-
-**Required fields:**
-
-- `brand.name` — string
-- `brand.primaryColor` — hex string matching `^#[0-9A-Fa-f]{6}$`
-- `brand.logoPath` — relative path to logo file the user will save to the project
-
-**If the user does not provide a logo**, proceed with a placeholder comment in the generated code noting that the logo must be added before production use. Do not fabricate a logo.
-
-**If the user provides a brand name but no colour**, ask:
-
-> "What's the primary colour for your brand? I need it as a hex code like `#FF8A3D`."
-
-Store answers in `brand.json`.
-
----
-
-## Question 3 — Use case
-
-**Ask exactly:**
-
-> "What's the primary use case for this CMS? For example: restaurant menu boards, retail promotions, corporate lobby displays, hospital wayfinding, transit information."
-
-**Use the answer to:**
-
-- Tailor the example content shown in the starter template (e.g. menu items vs retail promo templates)
-- Set the dashboard's default greeting and page titles
-- Suggest sensible default playlist names
-
-**Do NOT use the answer to:**
-
-- Change the SDK method signatures
-- Add or remove required components from `BUILD_GUARDRAILS.md`
-- Skip any mandatory pages
-
-The SDK contract is identical regardless of use case. Use case only affects content and copy.
-
-**Store answer as:** `cms.useCase` in `brand.json` (one of: `restaurant`, `retail`, `corporate`, `wayfinding`, `transit`, `other`)
-
----
-
-## Question 4 — Hosting target
-
-**Ask exactly:**
-
-> "Where will the CMS server run? Options:
->
-> - `here` — you're in Replit, Claude Code, or another hosted AI workspace (I'll configure it automatically)
-> - `vercel` — deploy to Vercel
-> - `railway` — deploy to Railway
-> - `self-hosted` — you'll run it on your own infrastructure"
-
-**If the user says `here`:**
-
-- Use environment variable `process.env.PORT` for the server port
-- Configure the WebSocket handler to bind to `0.0.0.0`
-- Include a comment in `server.ts` noting that Replit/Claude Code handles the hosting and HTTPS termination
-- Do NOT commit any secrets or keys to the generated code
-
-**If the user says `vercel`:**
-
-- Note that Vercel free tier has WebSocket limitations; recommend Railway for production
-- Generate `vercel.json` with appropriate WebSocket routing
-
-**If the user says `railway`:**
-
-- Generate `railway.toml` with port configuration
-- Include Dockerfile if appropriate
-
-**Store answer as:** `cms.hostingTarget` in `brand.json`
-
----
-
-## Question 5 — Expected number of screens
-
-**Ask exactly:**
-
-> "How many screens will you manage initially? (1-10 is fine for testing. For larger deployments I'll add pagination and grouping features.)"
-
-**If answer is 1-10:** generate simple list views without pagination.
-
-**If answer is 11-100:** include pagination on the screens list page (page size 20).
-
-**If answer is 100+:** include pagination, grouping, and tag filtering on the screens list. Note to user that fleet-level features (bulk commands, group broadcast) are recommended.
-
-**Store answer as:** `cms.expectedScreens` in `brand.json`
-
----
-
-## After all five answers collected
-
-Follow this sequence strictly:
-
-1. **Write `brand.json`** at the project root using the answers. Validate against `brand.schema.json`.
-2. **Run `npx tomorrowos init [dir]`** or copy `templates/cms-starter/` from the SDK package into the user's project as the seed.
-3. **Customise the starter:**
-   - Replace placeholder brand name, colour, logo references
-   - Rename example content to match the use case
-   - Remove any platform-specific notes for platforms the user didn't select
-4. **Read `BUILD_GUARDRAILS.md`** and verify every mandatory component is present in the generated code. Do not skip any.
-5. **Run `npm install`** and confirm dependencies resolve.
-6. **Start the dev server** (`npm run dev`) and confirm it runs without errors.
-7. **Show the user `PLAYER_INSTALL.md`** and explain what to do next to get a screen paired and controllable.
-
----
-
-## What not to ask
-
-Do not ask the user:
-
-- How WebSocket connections should be handled (the SDK handles this)
-- How to implement pairing (the SDK handles this)
-- How to format command messages (the SDK handles this)
-- Which WebSocket library to use (the SDK bundles this)
-- What TCP port to use (use `process.env.PORT` or `3000`)
-- Whether to use TypeScript or JavaScript (default to TypeScript; offer JS only if user explicitly asks)
-
-These are implementation details the SDK controls. The user cares about their brand, their platform, their use case. Everything else is the SDK's job.
-
----
-
-## When to re-prompt
-
-If the user's initial prompt already contains answers to some questions (e.g. "build me a CMS for my Acme Burger restaurant menu boards on Samsung Tizen"), record those answers and only ask the remaining questions. Do not re-ask what the user has already told you.
-
-If the user says "just build it, don't ask me questions," respond:
-
-> "I'd love to, but I need five quick answers to make sure the CMS you get actually works with your screens and looks like your brand. It'll take about sixty seconds. Ready?"
-
-Do not proceed without the answers. The SDK will not function without at minimum: `targetPlatforms`, `brand.name`, `brand.primaryColor`, and `cms.hostingTarget`.
-
----
-
-## Protocol version
-
-This elicitation protocol is version `1.0`, aligned with TomorrowOS wire protocol `1.0`. Future SDK versions may add questions; they will not remove existing ones without a major-version bump.