@surph_ai/cli 0.0.37 → 0.0.38

package/board/deploy.js

@@ -13,6 +13,9 @@
 //   4. Unzip it on S3 into boards/<slug>/site/ (the board's pages and assets).
 //   5. Upload board.json to boards/<slug>/board.json — last, so the live
 //      board's definition only changes once its site is up.
+//   6. Clear the board's files from the CDN cache (CloudFront serves
+//      https://<slug>.surph-boards.com from boards/<slug>/site/), so the new
+//      version shows right away.
 //
 // Node's built-ins only (zlib for compression, fetch for the upload). Needs
 // Node.js 20 or later.
@@ -28,6 +31,8 @@ const RPC_URL = 'https://rpc.surph.ai';
 const SYNC_URL = 'https://e3lunom2hka3u6iiotrlzrcez40uwdnk.lambda-url.us-east-1.on.aws/';
 // Also the board's host name (<slug>.surph-boards.com), so at most 63 characters.
 const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,62}$/;
+// The CloudFront distribution in front of the boards (*.surph-boards.com).
+const CLOUDFRONT_ID = 'E1AB54JQZBIU11';
 const PLACEHOLDER_SLUG = 'my-board';
 
 // The board's site: site/ in its folder (boards/<slug>/site/ when live).
@@ -184,6 +189,28 @@ const upload = async (uploadUrl, body, filetype, filename) => {
   }
 };
 
+// Clear boards/<slug>/* from CloudFront's cache (the `invalidateCache`
+// action, on the same Lambda as `sync`). The board is already published by
+// now, so a failure is reported, not fatal: the old files expire on their own.
+const invalidateCache = async (slug) => {
+  const path = `/boards/${slug}/*`;
+  try {
+    const res = await fetch(SYNC_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'Turbo-Client': 'portal' },
+      body: JSON.stringify({ action: 'invalidateCache', args: { cloudfront: CLOUDFRONT_ID, path } }),
+    });
+    const text = await res.text().catch(() => '');
+    let json = null;
+    try { json = JSON.parse(text); } catch { /* not JSON */ }
+    const error = json?.error || json?.response?.error || json?.data?.error;
+    if (!res.ok || error) throw new Error(typeof error === 'string' ? error : (error?.message || text.slice(0, 300) || `HTTP ${res.status}`));
+    console.log(`Cleared the CDN cache: ${path} (https://${slug}.surph-boards.com shows the new version in a minute or two)`);
+  } catch (e) {
+    console.warn(`The board is published, but clearing the CDN cache (${path}) failed: ${e.message}. https://${slug}.surph-boards.com may show the old version for a while.`);
+  }
+};
+
 // Unzip boards/<slug>/site/site.zip on S3 into boards/<slug>/site/.
 const unzipOnS3 = async (slug) => {
   const res = await fetch(SYNC_URL, {
@@ -208,11 +235,19 @@ const main = async () => {
     fail(`No board.json in ${ROOT}. Run this from the board's folder.`);
   }
   const slug = boardSlug();
-  if (!fs.existsSync(SITE) || !fs.statSync(SITE).isDirectory()) {
-    fail(`No site/ folder in ${ROOT}. The board's pages and assets go in site/ (site/index.html, site/assets/…).`);
+  // A board whose pages live on its own site (pages by `url`, the site in
+  // board.json's `origins`) has no site/ to publish: only board.json goes up.
+  const hasSite = fs.existsSync(SITE) && fs.statSync(SITE).isDirectory();
+  const files = hasSite ? siteFiles() : [];
+  if (!files.length) {
+    console.log(`No site/ files to publish${hasSite ? ' (site/ is empty)' : ''}: publishing board.json only.`);
+    console.log(`\nDeploying the board "${slug}"…`);
+    const boardUrl = await uploadUrlFor(slug, 'board.json', 'application/json');
+    await upload(boardUrl, fs.readFileSync(path.join(ROOT, 'board.json')), 'application/json', 'board.json');
+    console.log(`Uploaded: ${boardUrl.split('?')[0]}`);
+    await invalidateCache(slug);
+    return;
   }
-  const files = siteFiles();
-  if (!files.length) fail('Nothing to deploy: site/ has no files.');
 
   const zip = zipFiles(files);
   fs.writeFileSync(path.join(ROOT, ZIP_NAME), zip);
@@ -231,6 +266,7 @@ const main = async () => {
   const boardUrl = await uploadUrlFor(slug, 'board.json', 'application/json');
   await upload(boardUrl, fs.readFileSync(path.join(ROOT, 'board.json')), 'application/json', 'board.json');
   console.log(`Uploaded: ${boardUrl.split('?')[0]}`);
+  await invalidateCache(slug);
 };
 
 const MIN_NODE = 20;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surph_ai/cli",
-  "version": "0.0.37",
+  "version": "0.0.38",
   "description": "",
   "main": "index.js",
   "types": "./types.d.ts",

package/scaffold/board/AGENTS.md

@@ -25,7 +25,7 @@ Previewing and publishing the board need **Node.js 20 or later**. The pages them
 
 Keep them in step on a board that hasn't been published yet. The person won't think about the slug, so you do:
 
-1. **Whenever you set or change the board's name on an unpublished board, set `slug` from it in the same edit:** lowercase, spaces and punctuation turned into single dashes (BreakLedger → `breakledger`, "DC Tech Events" → `dc-tech-events`). Tell the person the slug you chose, in a word: it's the board's address (`https://<slug>.surph-boards.com`).
+1. **Whenever you set or change the board's name on an unpublished board, set `slug` from it in the same edit:** lowercase, spaces and punctuation turned into single dashes (BreakLedger → `breakledger`, "DC Tech Events" → `dc-tech-events`). Tell the person the slug you chose, in a word: it's the board's address (`https://<slug>.surph-boards.com`). Every page names the slug too, on its SDK tag (`<script data-board="<slug>" src="…/surph-board.js">`): change it there in the same edit, or the page stops speaking for the board.
 2. **A new board's slug starts from its folder name** (`surph board break-ledger` → `break-ledger`). Older boards may still have the placeholder `my-board`: replace it as soon as the board has a name. `npm run deploy` refuses to publish with `my-board`.
 3. **Check the slug is free before you settle on it:** `curl -s -o /dev/null -w "%{http_code}" https://surph.s3.us-east-1.amazonaws.com/boards/<slug>/board.json`. `200` means a board with that slug already exists. If this folder never published it, it's someone else's: pick another (add a short suffix, e.g. `breakledger-dk`) and say so. Anything else (403 or 404) means it's free.
 4. **Is this board published?** Treat it as published if the person says so, or if you ran `npm run deploy` for it. If unsure, ask.
@@ -34,7 +34,7 @@ Keep them in step on a board that hasn't been published yet. The person won't th
 ## The working loop
 
 1. **Preview:** run `npm run dev` from this folder and leave it running. It serves the board at `http://localhost:4180`: the pages in `site/` as its base (`/` is `site/index.html`), plus `/board.json` (nothing to install; it uses the Surph CLI through `npx`).
-2. **See it in Surph:** ask the person to open Surph, go to **Settings → Developer**, turn on **Run Surph as a local board**, and keep the address `http://localhost:4180`. Surph reloads as this board.
+2. **See it in Surph:** ask the person to open Surph, go to **Settings → Developer**, turn on **Run Surph as a local board**, and keep the address `http://localhost:4180`. Surph reloads as this board. Or, simpler: with `npm run dev` running, the person says "open http://localhost:4180" in Surph's chat, and the board joins the chat (its pages must load the SDK with `board: '<slug>'` and call `ready()`; see the README).
 3. **Configure the board** (name, contexts, tools, instructions): the person can click the **DEV** label in Surph's canvas header to open the Local board panel, which saves `board.json` for you. You can also edit `board.json` directly; the README describes every field.
 4. **Change pages:** the pages and their assets live in `site/` (`site/index.html`, `site/assets/…`). Edit them there and keep `board.json`'s `config.pages` in step (every page listed, `shows` written as plain facts, `ops` matching the page's `host.rpc` calls). The person reloads Surph to see the change.
 5. **Publish:** `npm run deploy`. **Only when the person asks you to in this conversation.** It replaces the live board for everyone who uses it. Check the board in dev mode first, and check `slug` first (see above): not `my-board`, and either free or this board's own. Once deployed, the site is live at `https://<slug>.surph-boards.com/`.

package/scaffold/board/README.md

@@ -1,6 +1,6 @@
 # Surph board
 
-This project is a **Surph board**: a set of web pages that Surph shows in its **canvas**, the panel beside the Surph chat. Each page is a static HTML file. Surph loads it in an iframe and answers the page's requests for data. The page talks to Surph only through the Surph SDK (`surph-wave.js`), which works over `postMessage`.
+This project is a **Surph board**: a set of web pages that Surph shows in its **canvas**, the panel beside the Surph chat. Each page is a static HTML file. Surph loads it in an iframe and answers the page's requests for data. The page talks to Surph only through the Surph board SDK (`surph-board.js`), which works over `postMessage`.
 
 **If you're a coding agent, read this whole file before writing a page.** Surph answers only the operations listed in [Operations the host answers](#operations-the-host-answers), with exactly the payloads shown. A page that calls anything else gets an error, and a field not listed here doesn't exist.
 
@@ -96,6 +96,7 @@ Surph only shows pages that are registered with the board. The board itself is d
 | `tools` | Slugs of Surph tools the board's chat can use. Optional. |
 | `config.instructions` | Instructions from the board's owner for the board's chat: tone, behavior, what it helps with. On a board they take the place of each context's own instructions. |
 | `config.pages` | The board's pages, one registry entry each (below). |
+| `origins` | Optional. Other sites allowed to speak for this board, as origins (`["https://breakledger.com"]`), for pages hosted outside Surph that load the SDK with `board: '<slug>'`. The board's own `https://<slug>.surph-boards.com` is always allowed. List only sites you control: a listed site can speak as the board. |
 | `config.icon` | Optional. The board's icon: a file in `site/`, by its path there (`apple-touch-icon.png`, `assets/img/icon.png`). Surph shows it beside the board's name: on each of the chat's replies ("@BreakLedger") and in the header. A small square image works best. |
 
 A registry entry:
@@ -121,31 +122,31 @@ A registry entry:
 
 ## The SDK
 
-Every page loads the SDK from this exact URL. Don't copy, bundle, edit or replace it.
+Every page loads the SDK from this exact URL, with the board's slug on the tag. Don't copy, bundle, edit or replace it.
 
 ```html
-<script src="https://surph.s3.us-east-1.amazonaws.com/admin/desktop/js/wave-sdk/v1/surph-wave.js"></script>
+<script data-board="my-board" src="https://surph.s3.us-east-1.amazonaws.com/admin/desktop/js/board-sdk/v1/surph-board.js"></script>
 ```
 
-It defines one global, `SurphWave`:
+`data-board` is this board's slug (`board.json`'s `slug`). With it, the SDK connects to Surph and announces the board as it loads; there's nothing to call. Add `data-page="events"` to name the page (optional). It defines one global, `SurphBoard`, for the page's own scripts:
 
 ```js
-const host = SurphWave.connect({
-  pageSlug: 'events',                    // The page's own name (any short string)
-  onRefresh: function () { paint(); }    // Surph's data changed: ask again and repaint
-});
-
-host.ready();                       // Call once, after connect
+const host = SurphBoard.host;       // The page's connection to Surph
+SurphBoard.onRefresh(paint);        // Surph's data changed: ask again and repaint
 host.rpc(op, args, { timeout });    // Ask Surph for something; returns a Promise
 host.hosted;                        // true inside the Surph canvas, false when opened directly
 ```
 
+Setting it up by hand instead (a tag without `data-board`) also works: `const host = SurphBoard.connect({ board: 'my-board', page: 'events', onRefresh: paint }); host.ready();`. Either way there's one connection per page: `SurphBoard.connect()` returns `SurphBoard.host` when it already exists, and `ready()` announces once.
+
 - `rpc(op, args, extra)` sends `args` as an object (use `{}` when there are none). It resolves with the operation's result object.
 - It rejects with:
   - `Error('host timeout')`: no reply in time. The default wait is 15 seconds; pass `{ timeout: 800 }` on reads.
   - `Error('not in a Surph host')`: the page isn't inside the canvas (`hosted` is false).
   - `Error('<message>')`: Surph answered with an error, for example `Unknown op: …` for an operation it doesn't support.
-- Only use `connect`, `ready`, `rpc`, `hosted` and the `onRefresh` option. The script has other options; they belong to other hosts and do nothing here.
+- `data-board` (or `board` in `connect`) says which board the page speaks for. The SDK passes it to Surph when the page loads, which checks the page's site against the board's: the board's own `https://<slug>.surph-boards.com`, plus any listed in `board.json`'s `origins`. A page on any other site is shown as an ordinary web page.
+- When the chat reads the page, the SDK answers with the page's visible text on its own; nothing to add.
+- Pages written before the board SDK load `surph-wave.js` and call `SurphWave.connect({ pageSlug, board, onRefresh })`. They still work; use the board SDK's tag for new pages and when you touch an old one.
 
 ## Call pattern
 
@@ -155,10 +156,9 @@ Every page that reads data uses this loop. Keep its rules:
 - paint only after a successful reply.
 
 ```js
-const host = SurphWave.connect({
-  pageSlug: 'events',
-  onRefresh: function () { paint(); }
-});
+// The page loads <script data-board="my-board" src="…/surph-board.js"></script> first.
+const host = SurphBoard.host;
+SurphBoard.onRefresh(paint);
 
 let painting = false;
 async function paint() {
@@ -176,7 +176,6 @@ async function paint() {
   // got is the operation's result. Paint it here (see "Rules for pages").
 }
 
-host.ready();
 paint();
 ```
 
@@ -424,6 +423,7 @@ A field marked "omitted" is missing from the object, not `null`. Every URL is `h
 2. Keep it running while you work; the terminal shows a line each time Surph saves `board.json`.
 3. Open `http://localhost:4180/` (your `site/index.html`) to check a page loads without console errors. It shows its empty layout there (`hosted` is false); real data only appears inside the Surph canvas.
 4. **Run Surph as your board with dev mode.** Keep `npm run dev` running. In Surph, open **Settings → Developer**, turn on **Run Surph as a local board**, and keep the address `http://localhost:4180`. Surph reloads as the board `board.json` describes: its name and icon in the header, its contexts and instructions in the chat, and its pages in the canvas (it opens on your start page, the Pages menu lists your pages, and the chat's model sees their `shows` lines). The status under the address says what loaded, or why it couldn't read `board.json`; until it loads, Surph runs as usual. A **DEV** label in the canvas header shows your board is loaded. While it's on, anything the chat saves goes to your own space in Surph, not to a board's shared space.
+   - **Or chat with the board without dev mode:** with `npm run dev` running, say "open http://localhost:4180" in Surph's chat. When the page loads the SDK with `board: '<slug>'` and calls `ready()`, the board joins the chat from the `board.json` at that address (it's your own machine, so no live board is needed): the canvas header shows it, its description opens its part of the conversation, and its replies are signed with its name. Live, the same happens for pages on `https://<slug>.surph-boards.com` or a site in `origins`.
 5. **Configure the board from Surph.** Click the **DEV** label to open the **Local board** panel: set the board's name, slug, description and icon (an image in `site/`), pick its contexts (yours, or public ones by search) and which one the chat starts with, pick its tools, and write its instructions. The panel also lists the pages and flags a missing `shows` line or an operation the host doesn't answer. **Save and reload** writes `board.json` through the dev server and reloads Surph as the updated board. Pages and any other fields are kept as they are in the file; edit pages in `board.json` itself.
 6. Dev mode affects only your browser. Turn it off in the same place to get Surph's own pages back.
 7. In Surph, keep your browser's DevTools open with **Network → Disable cache** checked, or the canvas may keep showing an older copy of a page after you change it. After editing `board.json` by hand, reload Surph so it reads the file again.
@@ -432,13 +432,16 @@ A field marked "omitted" is missing from the object, not `null`. Every URL is `h
 
 `npm run deploy` (`npx @surph_ai/cli board-deploy`, from the Surph CLI) publishes the board to Surph. Run it from the board's folder. It needs Node.js 20 or later and nothing else installed. In order, it:
 
+A board whose pages live on its own site (pages listed by `url`, the site in `origins`) can have no `site/` folder, or an empty one: the deploy then publishes `board.json` only.
+
 1. **Reads the board's `slug`** from `board.json` (lowercase letters, digits and dashes). The slug names the board's place in Surph, so it must be this board's own, not the placeholder `my-board` and not another board's (see the `slug` field above); without a valid one it stops before doing anything.
 2. **Zips the site** into `site.zip`: every file in `site/`, except dot-files (`.env`, `.DS_Store`) and `node_modules`. Nothing outside `site/` is included (`board.json` goes up on its own in step 5). It lists the files it zipped.
 3. **Uploads `site.zip`** to the board's `site/` folder in Surph's storage, then deletes the local `site.zip`. If the upload fails, the zip is kept to look at.
 4. **Unzips it there**, so the board's `site/` folder in Surph's storage holds the same files as your `site/`, where each page's `file` is found.
 5. **Uploads `board.json`**, last, so the live board's definition only changes once its pages are up. If an earlier step fails, `board.json` isn't uploaded and the live board keeps its previous version.
+6. **Clears the board's cached files** at `https://<slug>.surph-boards.com`, so the new version shows within a minute or two. If this step fails, the board is still published; it says so, and the old files may show for a while.
 
-Each step prints what it did; a failure prints why and stops. After a deploy, the site is live at `https://<slug>.surph-boards.com/`, and Surph picks up the new `board.json` within about a minute. A changed file can take a few minutes to replace the old copy there; reload to check.
+Each step prints what it did; a failure prints why and stops. After a deploy, the site is live at `https://<slug>.surph-boards.com/`, and Surph picks up the new `board.json` within about a minute. The deploy clears the cached copies there, so a changed file shows within a minute or two; reload to check.
 
 **For coding agents:**
 - **Deploying publishes the board to everyone who uses it.** Don't run `npm run deploy` unless the person asks you to in this conversation. Check the board with dev mode first (see [Developing locally](#developing-locally)).
@@ -451,7 +454,7 @@ Each step prints what it did; a failure prints why and stops. After a deploy, th
 - [ ] Reads use the call pattern: a timeout retries, other errors stop, nothing is cleared before a reply.
 - [ ] Data from Surph is written with `textContent`; links and images use only `http(s)` values.
 - [ ] Operations that act for the person run only from their click (a start page's `page.open` aside).
-- [ ] The SDK `<script>` tag is the v1 URL above, unchanged.
+- [ ] The SDK `<script>` tag is the v1 URL above, unchanged, and every page's SDK tag has `data-board="<slug>"` matching `board.json`'s `slug`.
 - [ ] Every page (in `site/`) links `assets/css/site.css?v=<n>`; if `site.css` changed, `<n>` is bumped in every page.
 - [ ] `board.json`'s `config.pages` lists every page: `name`, `file` (or `url`), `shows` written as facts, `ops` matching the file's `rpc` calls, and one `start` page.
 - [ ] Opened at `http://localhost:4180/<page>`, every page loads without console errors.

package/scaffold/board/site/index.html

@@ -81,7 +81,7 @@
   <h2>How a page works in Surph</h2>
   <ul class="facts">
     <li><strong>It's a static HTML file.</strong> No build step or framework. Surph loads it in an iframe; you can host it anywhere on <code>https</code>.</li>
-    <li><strong>It talks to Surph through the SDK.</strong> The page loads <code>surph-wave.js</code>, calls <code>SurphWave.connect()</code>, then asks the host for data with <code>host.rpc(op, args)</code>: the board's recent items, the chat's context, the items the chat looked up, and more. The page never calls Surph's servers itself.</li>
+    <li><strong>It talks to Surph through the SDK.</strong> The page loads <code>surph-board.js</code>, calls <code>SurphBoard.connect()</code>, then asks the host for data with <code>host.rpc(op, args)</code>: the board's recent items, the chat's context, the items the chat looked up, and more. The page never calls Surph's servers itself.</li>
     <li><strong>The chat decides when to show it.</strong> Each page is registered with a <code>shows</code> line, plain facts about what it displays. The chat's model reads those and opens the page that fits what the person asked. A page can also take values in its address (<code>?ids=…</code>) that the chat fills in.</li>
     <li><strong>It updates as the chat goes.</strong> When the host's data changes, it calls the page's <code>onRefresh</code>, and the page asks again and repaints.</li>
     <li><strong>Opened directly, it still loads.</strong> Outside Surph, <code>host.hosted</code> is false and every call rejects, so the page shows its empty layout. That's what you see here when you run it locally.</li>
@@ -95,12 +95,11 @@
     <li><strong>See them in Surph:</strong> open <strong>Settings → Developer</strong> and turn on dev mode for <code>http://localhost:4180</code>. The canvas then shows the board's pages, with real data.</li>
   </ol>
 
-  <script src="https://surph.s3.us-east-1.amazonaws.com/admin/desktop/js/wave-sdk/v1/surph-wave.js"></script>
+  <!-- data-board: this board's slug (board.json's "slug"). The SDK connects and announces the board as it loads. -->
+  <script data-board="my-board" src="https://surph.s3.us-east-1.amazonaws.com/admin/desktop/js/board-sdk/v1/surph-board.js"></script>
   <script>
-    const host = SurphWave.connect({
-      pageSlug: 'index',
-      onRefresh: function () { paint(); }
-    });
+    const host = SurphBoard.host;
+    SurphBoard.onRefresh(paint);
 
     const statusBox = document.getElementById('status');
     const statusTitle = document.getElementById('status-title');
@@ -145,7 +144,6 @@
           : 'board.get answered: this chat isn’t on a board, so it has no board items.');
     }
 
-    host.ready();
     paint();
   </script>
 </body>

package/scaffold/index.js

@@ -285,7 +285,9 @@ const scaffoldBoard = async (name) => {
     // The board's pages and assets go in site/ (boards/<slug>/site/ when live).
     shell.mkdir('-p', 'site/assets/css')
     shell.mkdir('-p', 'site/assets/js')
-    shell.cp('-R', path.join(__dirname, `board/site/index.html`), 'site/index.html')
+    // The starter page speaks for this board: its SDK tag names the slug.
+    const indexHtml = utils.readFile(path.join(__dirname, 'board/site/index.html'))
+    utils.write('site/index.html', indexHtml.replace('data-board="my-board"', `data-board="${boardJson.slug}"`))
     shell.cp('-R', path.join(__dirname, `board/site/assets/css/site.css`), 'site/assets/css/site.css')
 
     await progress.done()