@tomorrowos/sdk 0.1.0

package/BUILD_GUARDRAILS.md

@@ -0,0 +1,348 @@
+# Build Guardrails for TomorrowOS CMS Projects
+
+> **These are not suggestions. Every CMS generated from `@tomorrowos/sdk` must include each component in this document. The SDK assumes they exist. If any are missing, pairing will fail, content will not deploy, and the LLM that generated the CMS has produced broken code.**
+
+This document exists because an LLM given a blank canvas will produce a CMS that looks right and doesn't work. This file is the fence that stops that. Read each section. Include each component. Do not skip any.
+
+---
+
+## 1. Server-side WebSocket host
+
+**File:** `server.ts` (or `server.js`)
+
+**Must contain:**
+
+```typescript
+import { TomorrowOS } from '@tomorrowos/sdk';
+import brand from './brand.json';
+
+const tomorrowos = new TomorrowOS({ brand });
+
+tomorrowos.listen({
+  port: Number(process.env.PORT) || 3000,
+  host: '0.0.0.0',
+});
+```
+
+**Why this matters:**
+
+- `TomorrowOS` is a class from the SDK that wraps WebSocket handling, pairing, command envelopes, lifecycle tracking, and event publishing. Do not reimplement any of this.
+- `tomorrowos.listen()` binds a WebSocket server that every player connects to. Without this call, no screen can ever pair.
+- `host: '0.0.0.0'` is required for Replit / Claude Code / containerised hosting. Do not use `localhost` or `127.0.0.1` in the starter.
+
+**Must not contain:**
+
+- Raw `ws` or `socket.io` imports — the SDK handles WebSocket transport
+- Manual pairing code generation — the SDK provides `tomorrowos.pairing.createCode()`
+- Manual JWT signing for device tokens — the SDK mints and verifies these
+
+---
+
+## 2. Pairing page
+
+**Route:** `/pair`
+
+**Must include:**
+
+- An input field accepting a 6-digit numeric code (input pattern `\d{6}`)
+- A submit button that calls `tomorrowos.pairing.verify(code)` via the SDK
+- Success state showing the newly-paired device's name and ID
+- Error state for expired, invalid, or already-paired codes
+- A link back to the main screens list
+
+**Example flow:**
+
+```typescript
+import { useTomorrowOS } from '@tomorrowos/sdk/react';
+
+function PairPage() {
+  const { pairing } = useTomorrowOS();
+  const [code, setCode] = useState('');
+  const [result, setResult] = useState(null);
+
+  async function handleSubmit() {
+    try {
+      const device = await pairing.verify(code);
+      setResult({ success: true, device });
+    } catch (err) {
+      setResult({ success: false, error: err.message });
+    }
+  }
+
+  return (/* UI here */);
+}
+```
+
+**Why mandatory:**
+
+Without a pairing page, a device showing an activation code on its screen has no way to tell the CMS "I am device X, please accept me." The CMS will never gain a paired device. Every CMS needs this page regardless of use case.
+
+---
+
+## 3. Screens list page
+
+**Route:** `/` or `/screens`
+
+**Must include:**
+
+- Live list of paired devices from `tomorrowos.devices.list()`
+- Online / offline indicator per device (driven by `device.heartbeat` events)
+- Last-seen timestamp per device (from heartbeat stream)
+- Device name, model, and platform per row
+- Click-through to `/screens/[deviceId]`
+
+**Real-time updates:**
+
+The SDK emits `device.online`, `device.offline`, and `device.heartbeat` events. Subscribe to these via `tomorrowos.on('device.online', handler)` to keep the list live without polling.
+
+**Why mandatory:**
+
+This is the operator's primary workspace. Without it, the CMS has paired devices it cannot show.
+
+---
+
+## 4. Per-device control panel
+
+**Route:** `/screens/[deviceId]`
+
+**Must include the following controls, wired to SDK methods:**
+
+### Device info panel (top of page)
+
+Display output of `tomorrowos.device(deviceId).info.get()`:
+
+- Device name
+- Platform and platform version
+- Hardware model and serial
+- Current resolution
+- Paired since date
+
+### Control buttons
+
+Each button calls the corresponding SDK method via `tomorrowos.device(deviceId).sendCommand()`:
+
+| Label            | SDK call                                         | Notes                                          |
+|------------------|--------------------------------------------------|------------------------------------------------|
+| Reboot           | `device.power.reboot()`                          | Confirm dialog before sending                  |
+| Deploy content   | Opens URL input → `device.content.setPolicy()`   | Wrap URL as single-item policy; see below      |
+| Clear content    | `device.content.clear()`                         | Confirm dialog                                 |
+| Screenshot       | `device.display.screenshot()`                    | Only show button if capability supports it     |
+
+### Current content indicator
+
+Poll `tomorrowos.device(deviceId).content.current()` every 10 seconds, or subscribe to `content.started` / `content.finished` events for push updates.
+
+### Deploy content — correct shape
+
+When the user enters a URL to deploy, the SDK call must wrap it as a content policy:
+
+```typescript
+await device.sendCommand('device.content.setPolicy', {
+  policy: {
+    revision: Date.now(), // monotonic
+    playlists: [{
+      playlistId: crypto.randomUUID(),
+      priority: 10,
+      items: [{
+        contentId: crypto.randomUUID(),
+        url: userProvidedUrl,
+        durationSec: 30,
+        transition: 'cut',
+      }],
+      loop: true,
+      schedule: { startDate: null, endDate: null },
+    }],
+    priorityResolution: 'highest_wins',
+  },
+});
+```
+
+**Do not call** `device.content.deploy(url)` — this method does not exist in V1. Content is declarative policy, not imperative deploy.
+
+**Why mandatory:**
+
+Without the control panel, the CMS is a pretty dashboard with no function. Every TomorrowOS demo, test, and user showcase depends on this page working.
+
+---
+
+## 5. Brand application via `brand.json`
+
+**Brand data MUST flow through `brand.json`**, never hard-coded in components.
+
+### Read brand at startup
+
+```typescript
+import brand from './brand.json';
+```
+
+### Apply brand via CSS custom properties
+
+Generate a `brand.css` file (or equivalent) on server start that derives CSS variables from `brand.json`:
+
+```css
+:root {
+  --color-primary: #FF8A3D;       /* from brand.primaryColor */
+  --color-background: #FAFAF9;    /* from brand.backgroundColor */
+  --color-text: #0A0908;          /* from brand.textColor */
+  --font-sans: 'Inter', sans-serif; /* from brand.fontFamily */
+}
+```
+
+### Use the `useBrand()` hook in React components
+
+```typescript
+import { useBrand } from '@tomorrowos/sdk/react';
+
+function Header() {
+  const brand = useBrand();
+  return (
+    <header>
+      <img src={brand.logoPath} alt={brand.name} />
+      <h1>{brand.name} Signage</h1>
+    </header>
+  );
+}
+```
+
+**Must not:**
+
+- Hard-code the brand name, logo path, or colours in any component
+- Use inline `style={{ color: '#FF8A3D' }}` — always use the CSS variable
+- Reference the TomorrowOS amber or the starter's placeholder colour in production components
+
+**Why mandatory:**
+
+Hard-coded branding means the user has to edit every file to change a colour. `brand.json`-driven branding means one file change propagates everywhere — including into the device's activation screen (baked into the `.wgt` at build time by `tomorrowos build`).
+
+---
+
+## 6. Command envelope
+
+**Every mutating command must go through `sdk.sendCommand(method, params)`.**
+
+The SDK wraps your call with the standard command envelope:
+
+```json
+{
+  "commandId": "uuid-generated",
+  "method": "device.power.reboot",
+  "params": {},
+  "issuedAt": "2026-05-14T10:30:00Z",
+  "ttlSec": 300,
+  "idempotencyKey": "uuid-generated",
+  "requiresAck": true
+}
+```
+
+**Must not:**
+
+- Write to the WebSocket directly. If you find yourself typing `ws.send()` or `socket.emit()` in your CMS code, stop — you are bypassing the SDK and your commands will be rejected by the player.
+- Construct your own commandId or idempotency logic. The SDK does this.
+- Assume a command is complete when `sendCommand` resolves. `sendCommand` returns when the command is `accepted`. Listen for `command.verified` or `command.failed` events to know the final outcome.
+
+---
+
+## 7. No platform-specific branching in CMS code
+
+The CMS must be platform-agnostic. The SDK + capability declarations abstract every platform difference.
+
+**Do not write:**
+
+```typescript
+// WRONG
+if (device.platform === 'tizen') {
+  await device.sendCommand('device.power.reboot');
+} else if (device.platform === 'brightsign') {
+  await device.sendCommand('device.power.restart');
+}
+```
+
+**Write:**
+
+```typescript
+// CORRECT
+await device.sendCommand('device.power.reboot');
+```
+
+If the device doesn't support reboot, the SDK returns a `CAPABILITY_NOT_SUPPORTED` error. Handle that error — do not pre-branch on platform.
+
+**Do not:**
+
+- Check `device.platform` or `device.class` to change which methods you call
+- Call raw native APIs (there are none exposed to the CMS — only SDK methods)
+- Import any `@tomorrowos/player-*` packages into the CMS — those are player-side, not CMS-side
+
+---
+
+## 8. Event subscription for real-time UI
+
+Subscribe to events for live dashboards. Do not poll unless explicitly required.
+
+```typescript
+tomorrowos.on('device.online', (event) => {
+  // update UI
+});
+
+tomorrowos.on('device.heartbeat', (event) => {
+  // update last-seen
+});
+
+tomorrowos.on('command.verified', (event) => {
+  // mark command as successful in UI
+});
+
+tomorrowos.on('command.failed', (event) => {
+  // show error to operator
+});
+
+tomorrowos.on('content.error', (event) => {
+  // alert operator of content playback failure
+});
+```
+
+---
+
+## Optional but strongly recommended
+
+The following are not required but improve the CMS substantially. Include them if the user is at expectedScreens > 10 or if the use case warrants it.
+
+### Build player button
+
+A button in the CMS admin area that runs `npx tomorrowos build --platform tizen` (or other) and links the user to the generated `.wgt` file in `dist/`. Saves the user a terminal step.
+
+### Settings page for `brand.json`
+
+A `/settings` page that lets the user edit brand fields in-UI and writes back to `brand.json`. On save, the CMS reloads the brand.
+
+### Fleet broadcast
+
+A bulk-command UI that uses `tomorrowos.fleet.broadcast(method, params, targets)` to send the same command to many devices at once. Essential at > 50 screens.
+
+### Proof-of-play log
+
+A `/playback` page showing which content played on which screen at what time. Reads from `tomorrowos.device(id).proofOfPlay.getLog()`.
+
+---
+
+## Summary — the "did I build this right?" checklist
+
+Before shipping a generated CMS, verify:
+
+- `server.ts` imports `TomorrowOS` from `@tomorrowos/sdk` and calls `listen()` — ☐
+- `/pair` page exists and calls `pairing.verify(code)` — ☐
+- `/screens` page shows live device list with online/offline status — ☐
+- `/screens/[id]` page has reboot, deploy, clear, current-content at minimum — ☐
+- Deploy uses `device.content.setPolicy` with a wrapped policy object, not `content.deploy` — ☐
+- `brand.json` exists at project root and drives all UI branding via CSS variables — ☐
+- No hard-coded colours, logos, or brand names in components — ☐
+- All mutating commands use `sdk.sendCommand()` — no raw WebSocket writes — ☐
+- No platform branching in CMS code — ☐
+- Event subscriptions for `device.online`, `device.offline`, `device.heartbeat` active — ☐
+
+If every box is checked, the CMS will work on first connection. If any box is unchecked, pairing or control will fail in ways the user cannot diagnose.
+
+---
+
+## Protocol compliance
+
+This guardrails document is version `1.0`, aligned with TomorrowOS wire protocol `1.0`. Future SDK versions may add or strengthen guardrails; they will not relax them without a major-version bump.

package/LLM_PROMPT.md

@@ -0,0 +1,171 @@
+# 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.**
+
+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.