@surph_ai/cli 0.0.34 → 0.0.35

package/board/deploy.js

@@ -3,7 +3,7 @@
 // the board's folder. Built up step by step; so far:
 //
 //   1. Zip the board's site: every file in the folder except the project
-//      files (package.json, package-lock.json, README.md, board.json,
+//      files (package.json, package-lock.json, README.md, AGENTS.md, CLAUDE.md, board.json,
 //      node_modules), dot-files (.env, .git, .DS_Store) and the zip itself.
 //      Written to site.zip in the board's folder.
 //   2. Ask Surph for an upload address for it: boards/<slug>/site/site.zip on
@@ -14,7 +14,8 @@
 //   5. Upload board.json to boards/<slug>/board.json — last, so the live
 //      board's definition only changes once its site is up.
 //
-// Node's built-ins only (zlib for compression, fetch for the upload; Node 18+).
+// Node's built-ins only (zlib for compression, fetch for the upload). Needs
+// Node.js 20 or later.
 
 const fs = require('fs');
 const path = require('path');
@@ -28,7 +29,7 @@ const SYNC_URL = 'https://e3lunom2hka3u6iiotrlzrcez40uwdnk.lambda-url.us-east-1.
 const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
 
 // Left out at the board's top level: the project's own files.
-const SKIP_AT_ROOT = new Set(['package.json', 'package-lock.json', 'README.md', 'board.json', ZIP_NAME]);
+const SKIP_AT_ROOT = new Set(['package.json', 'package-lock.json', 'README.md', 'AGENTS.md', 'CLAUDE.md', 'board.json', ZIP_NAME]);
 
 // The files to deploy, as paths relative to the board's folder ('/'-separated).
 const siteFiles = (dir = ROOT, rel = '') => {
@@ -224,7 +225,13 @@ const main = async () => {
   console.log(`Uploaded: ${boardUrl.split('?')[0]}`);
 };
 
-const run = () => main().catch((error) => fail(`Deploy failed: ${error.message}`));
+const MIN_NODE = 20;
+
+const run = () => {
+  const major = Number(process.versions.node.split('.')[0]);
+  if (major < MIN_NODE) fail(`Deploying a board needs Node.js ${MIN_NODE} or later; this is ${process.version}. Install a newer Node.js (https://nodejs.org) and try again.`);
+  return main().catch((error) => fail(`Deploy failed: ${error.message}`));
+};
 
 // `surph board-deploy` calls run(); running this file directly runs it too.
 if (require.main === module) run();

package/board/server.js

@@ -2,7 +2,7 @@
 // The board's local dev server (`npm run dev` → `surph-board-dev`): serves
 // the board folder it's run from (the current directory) at
 // http://localhost:4180 for Surph's dev mode (Settings → Developer → Run
-// Surph as a local board). Node's built-ins only.
+// Surph as a local board). Node's built-ins only; needs Node.js 20 or later.
 //
 //   GET  /<file>             This folder's files, never cached, with CORS so
 //                            Surph (another address) can read board.json.
@@ -158,7 +158,14 @@ const handle = async (req, res) => {
 
 // Start serving the current folder. localhost may be reached over IPv4 or
 // IPv6: listen on both loopbacks.
+const MIN_NODE = 20;
+
 const start = () => {
+  const major = Number(process.versions.node.split('.')[0]);
+  if (major < MIN_NODE) {
+    console.error(`The board dev server needs Node.js ${MIN_NODE} or later; this is ${process.version}. Install a newer Node.js (https://nodejs.org) and try again.`);
+    process.exit(1);
+  }
   http.createServer(handle)
     .on('error', (error) => {
       console.error(error.code === 'EADDRINUSE'

package/package.json

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

package/scaffold/board/AGENTS.md

@@ -0,0 +1,32 @@
+# Surph board: notes for coding agents
+
+This folder is a **Surph board**: static web pages that Surph shows in its canvas, beside the Surph chat. The person you're working with may not be technical. Explain steps in plain words, and say what a command does before you run it.
+
+**`README.md` is the full reference.** Read it before writing or changing a page: it lists every operation Surph answers, the item shape, the rules for pages, and how `board.json` works. This file covers setup and the working loop.
+
+## Setup: Node.js
+
+Previewing and publishing the board need **Node.js 20 or later**. The pages themselves don't.
+
+1. Check with `node -v`.
+2. If it's missing or older than 20, tell the person that Node.js is needed to preview the board inside Surph and to publish it, and offer to install it. Install only with their OK.
+   - **Mac:** prefer a user-level install that needs no admin password, such as [fnm](https://github.com/Schniz/fnm) (`curl -fsSL https://fnm.vercel.app/install | bash`, then `fnm install --lts`). Homebrew (`brew install node`) is fine if Homebrew is already installed.
+   - **Windows:** `winget install OpenJS.NodeJS.LTS` (Windows may ask the person to approve once).
+   - **Linux:** the distribution's package manager, or fnm as on Mac.
+3. A fresh install may not be visible in the current terminal. If `node -v` still fails afterwards, open a new terminal session (or load the shell profile) and check again.
+4. If an install isn't possible (declined, or blocked on a work computer), point them to the installer at https://nodejs.org and wait for them.
+
+## The working loop
+
+1. **Preview:** run `npm run dev` from this folder and leave it running. It serves the board at `http://localhost:4180` (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.
+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:** edit the HTML in this folder 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.
+
+## What to keep in mind
+
+- Pages talk to Surph only through the Surph SDK (`host.rpc(…)`) and only with the operations the README lists. Don't invent operations or fields; if a page needs data Surph doesn't offer, say so.
+- Write data from Surph with `textContent`, never `innerHTML`.
+- Everything in this folder except `package.json`, `package-lock.json`, `README.md`, `AGENTS.md`, `CLAUDE.md`, `board.json`, `node_modules` and dot-files gets published by `npm run deploy`. Keep drafts, exports and secrets out of it (or in dot-files).
+- Before handing off, go through the README's "Checklist before handing off a change".

package/scaffold/board/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/scaffold/board/README.md

@@ -410,10 +410,10 @@ A field marked "omitted" is missing from the object, not `null`. Every URL is `h
 
 ## Deploying
 
-`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 18 or later and nothing else installed. In order, it:
+`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:
 
 1. **Reads the board's `slug`** from `board.json` (lowercase letters, digits and dashes). The slug names the board's place in Surph; without a valid one it stops before doing anything.
-2. **Zips the site** into `site.zip`: every file in the folder except `package.json`, `package-lock.json`, `README.md`, `board.json`, `node_modules`, dot-files (`.env`, `.git`, `.DS_Store`) and `site.zip` itself. It lists the files it zipped.
+2. **Zips the site** into `site.zip`: every file in the folder except `package.json`, `package-lock.json`, `README.md`, `AGENTS.md`, `CLAUDE.md`, `board.json`, `node_modules`, dot-files (`.env`, `.git`, `.DS_Store`) and `site.zip` itself. 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 pages and `assets/` sit in the board's `site/` folder, 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.

package/scaffold/board/package.json

@@ -9,5 +9,8 @@
   "keywords": [],
   "author": "",
   "license": "ISC",
-  "type": "commonjs"
+  "type": "commonjs",
+  "engines": {
+    "node": ">=20"
+  }
 }

package/scaffold/index.js

@@ -270,6 +270,8 @@ const scaffoldBoard = async (name) => {
     utils.write('package.json', JSON.stringify(pkgJson, null, 2) + '\n')
 
     shell.cp('-R', path.join(__dirname, `board/README.md`), 'README.md')
+    shell.cp('-R', path.join(__dirname, `board/AGENTS.md`), 'AGENTS.md')
+    shell.cp('-R', path.join(__dirname, `board/CLAUDE.md`), 'CLAUDE.md')
     shell.cp('-R', path.join(__dirname, `board/index.html`), 'index.html')
     shell.cp('-R', path.join(__dirname, `board/board.json`), 'board.json')