@joystack/cli 0.1.54 → 0.1.56

package/lib/maker.mjs

@@ -24,8 +24,8 @@ export const MAKER_LANE =
 
 export const MAKER_DEV =
   "You are in the Joystack maker: this folder's dev server is already running, and the " +
-  'person plays the game on their page, beside the chat. Every file you save shows up ' +
-  'there. Nothing was started.';
+  'person plays the game on their page, beside the chat (on a phone, under Play). Every file you save shows up ' +
+  'there. Nothing was started. There is no link to give them: to hand the game over, tell them it is ready to play on their page.';
 
 // `publish` and `land` both do what the page's Publish button does: the draft
 // goes into the game, and the game goes online under the name it has. The
@@ -61,3 +61,17 @@ export async function makerPublish(at, { slug = null, log = console.log, fetchIm
   );
   return body;
 }
+
+// The port of this draft's dev server on the maker's machine, starting it if
+// it sleeps (`POST <JOYSTACK_MAKER>/serve`, which answers `{ port }`), or null
+// when the maker does not say. A draft's server is on a port of the maker's
+// choosing, which the ports `joystack dev` takes on a laptop do not include.
+export async function makerDevPort(at, { fetchImpl = fetch } = {}) {
+  try {
+    const res = await fetchImpl(`${at}/serve`, { method: 'POST', signal: AbortSignal.timeout(60_000) });
+    const port = res.ok ? Number((await res.json())?.port) : NaN;
+    return Number.isInteger(port) && port > 0 && port < 65536 ? port : null;
+  } catch {
+    return null;
+  }
+}

package/lib/mime.mjs

@@ -0,0 +1,28 @@
+// The content type the dev server sends for a file, by its extension.
+export const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.ico': 'image/x-icon',
+  '.wasm': 'application/wasm',
+  '.mp3': 'audio/mpeg',
+  '.ogg': 'audio/ogg',
+  '.wav': 'audio/wav',
+  '.m4a': 'audio/mp4',
+  '.flac': 'audio/flac',
+  '.txt': 'text/plain; charset=utf-8',
+  '.md': 'text/markdown; charset=utf-8',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.glb': 'model/gltf-binary',
+  '.gltf': 'model/gltf+json',
+  '.bin': 'application/octet-stream',
+};

package/lib/relay/cli.mjs

@@ -1,112 +1,61 @@
-// `joystack relay publish` and `joystack relay tail`: the agent's end of the
-// relay, from the game folder. Each running dev server for the folder wrote
-// its port and a bearer token to .joystack/relay/.connection-<port>
-// (connection.mjs), so only a process that can read the folder can speak as
-// the agent, and with several servers for one game every one of them hears.
+// `joystack relay reply`: the agent's end of the relay, from the game
+// folder. Each running dev server for the folder wrote its port and a bearer token
+// to .joystack/relay/.connection-<port> (connection.mjs), so only a process
+// that can read the folder can speak as the agent, and with several servers
+// for one game every one of them hears.
 import { connections } from './connection.mjs';
 
-export const RELAY_HELP = `joystack relay publish [--dir <game>] <name> [<json>]
-  Put an event on the relay of every running 'joystack dev' for this game, as
-  the agent: <name> is <publisher>.<what> (agent.replied, agent.show), <json>
-  its data. The events worth publishing, with their exact command lines, are
-  in your game's AGENTS.md and the engine's docs.
-joystack relay tail [--dir <game>] [<pattern>…]
-  Print every event on the relay as it happens, one JSON line each, until
-  stopped. A pattern is a name whose segments may be *; none means every event.`;
+export const RELAY_HELP = `joystack relay reply [--dir <game>] <note id> <text>
+  Answer a note the creator sent you from the running game: the text shows
+  under their note, even if the game reloaded since. The command line with
+  the note's id is in the message the note woke you with.`;
 
-const RELAY = '/__joystack/relay';
+const RELAY_REQUEST = '/__joystack/relay';
 
-// Publish `data` under `name` on every server for `dir`. Resolves the number
-// of listeners reached, summed over the servers; throws when no server for
-// the folder is running.
-export async function relayPublish({ dir = process.cwd(), name, data = null, log = console.log }) {
-  if (!name) throw new Error(`Usage: ${RELAY_HELP}`);
-  let reached = 0;
-  let delivered = 0;
-  let agent = false;
+// Ask every running dev server for `dir` the agent's `name` with `data`, as
+// the agent. Resolves the answers, one per server reached, a refusal as an
+// error answer; throws when no server for the folder is running.
+async function askAsAgent(dir, name, data) {
+  const answers = [];
   for (const { port, token } of connections(dir)) {
     let res;
     try {
       // Always loopback: the credential names a port, never an address.
-      res = await fetch(`http://127.0.0.1:${port}${RELAY}`, {
+      res = await fetch(`http://127.0.0.1:${port}${RELAY_REQUEST}`, {
         method: 'POST',
         headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
         body: JSON.stringify({ name, data }),
         signal: AbortSignal.timeout(5000),
       });
     } catch { continue; } // that server has stopped
-    reached += 1;
-    if (!res.ok) {
-      // Whatever answers on that port wrote the body; it is reported by
-      // status only, never echoed.
-      throw new Error(`The dev server on port ${port} refused the event (HTTP ${res.status}).`);
-    }
-    const out = await res.json().catch(() => ({}));
-    delivered += Number(out.delivered) || 0;
-    agent = agent || out.agent === true;
+    // Whatever answers on that port wrote the body; a refusal is reported by
+    // status only, never echoed. Another server for the same folder (one
+    // from an older CLI, say) may still take it.
+    if (!res.ok) { answers.push({ ok: false, reason: 'error', message: `The dev server on port ${port} refused it (HTTP ${res.status}).` }); continue; }
+    answers.push(await res.json().catch(() => ({ ok: false, reason: 'error', message: 'not an answer' })));
   }
-  if (!reached) throw new Error(`No running 'joystack dev' for ${dir}.`);
-  log(`Published ${name} to ${delivered} listener${delivered === 1 ? '' : 's'}.`);
-  return { delivered, agent };
+  if (!answers.length) throw new Error(`No running 'joystack dev' for ${dir}.`);
+  return answers;
 }
 
-// Read one server's stream, calling `onEvent` for each event frame, until
-// the stream ends or `signal` aborts.
-async function tailOne(port, token, patterns, onEvent, signal) {
-  const listen = encodeURIComponent(JSON.stringify(patterns.map((p) => [p, false])));
-  const res = await fetch(`http://127.0.0.1:${port}${RELAY}/stream?listen=${listen}`, { headers: { Authorization: `Bearer ${token}` }, signal });
-  if (!res.ok) throw new Error(`The dev server on port ${port} refused the stream (HTTP ${res.status}).`);
-  let buffer = '';
-  for await (const chunk of res.body) {
-    buffer += Buffer.from(chunk).toString('utf8');
-    let at;
-    while ((at = buffer.indexOf('\n\n')) !== -1) {
-      const block = buffer.slice(0, at);
-      buffer = buffer.slice(at + 2);
-      const data = block.split('\n').filter((l) => l.startsWith('data:')).map((l) => l.slice(5).trimStart()).join('\n');
-      if (!data) continue;
-      let frame;
-      try { frame = JSON.parse(data); } catch { continue; }
-      if (frame.type === 'event' && frame.event) onEvent(frame.event, port);
-    }
-  }
-}
-
-// Tail every server for `dir`. Resolves when every stream has ended (the
-// servers stopped, or `signal` aborted); throws when none is running.
-export async function relayTail({ dir = process.cwd(), patterns = [], onEvent = (e) => console.log(JSON.stringify(e)), signal = undefined, log = console.error } = {}) {
-  const servers = connections(dir);
-  if (!servers.length) throw new Error(`No running 'joystack dev' for ${dir}.`);
-  const wanted = patterns.length ? patterns : ['*'];
-  log(`Tailing ${wanted.join(', ')} on ${servers.length} dev server${servers.length === 1 ? '' : 's'} (port${servers.length === 1 ? '' : 's'} ${servers.map((s) => s.port).join(', ')})…`);
-  const results = await Promise.allSettled(servers.map(({ port, token }) => tailOne(port, token, wanted, onEvent, signal)));
-  const failed = results.filter((r) => r.status === 'rejected' && r.reason?.name !== 'AbortError');
-  if (failed.length === results.length) throw failed[0].reason;
+// Answer the note `id` with `text`, on every dev server running for `dir`:
+// each keeps the same file and announces it to the pages it serves.
+export async function relayReply({ dir = process.cwd(), id, text, log = console.log }) {
+  if (!id || !text?.trim()) throw new Error(`Usage: ${RELAY_HELP}`);
+  const answers = await askAsAgent(dir, 'agent.reply', { to: id, text });
+  const kept = answers.filter((a) => a?.ok);
+  if (!kept.length) throw new Error(answers[0]?.message || 'The reply was refused.');
+  const shown = kept.some((a) => a.value?.shown);
+  log(shown ? `Replied to note ${id}; it shows under the note.` : `Replied to note ${id}; it shows under the note when the creator's page is open again.`);
+  return { shown };
 }
 
-// The command line: `relay publish [--dir d] <name> [<json>]` or `relay tail
-// [--dir d] [<pattern>…]`.
+// The command line: `relay reply [--dir d] <note id> <text>`.
 export async function relayCommand(rest, { dir, log = console.log } = {}) {
   const [verb, ...args] = rest;
-  if (verb === 'publish') {
-    const [name, raw] = args;
-    let data = null;
-    if (raw !== undefined) {
-      try { data = JSON.parse(raw); } catch { throw new Error(`The data must be JSON, for example '{"to":"ab12cd34","text":"Done."}'. Usage: ${RELAY_HELP}`); }
-    }
-    return relayPublish({ dir, name, data, log });
-  }
-  if (verb === 'tail') {
-    const controller = new AbortController();
-    const stop = () => controller.abort();
-    process.once('SIGINT', stop);
-    process.once('SIGTERM', stop);
-    try {
-      return await relayTail({ dir, patterns: args, signal: controller.signal });
-    } finally {
-      process.off('SIGINT', stop);
-      process.off('SIGTERM', stop);
-    }
+  if (verb === 'reply') {
+    const [id, ...words] = args;
+    return relayReply({ dir, id, text: words.join(' '), log });
   }
   throw new Error(`Usage: ${RELAY_HELP}`);
 }

package/lib/relay/connection.mjs

@@ -1,7 +1,6 @@
-// The hub's credential for the agent: each running dev server writes its port
+// The relay's credential for the agent: each running dev server writes its port
 // and a bearer token to .joystack/relay/.connection-<port>, owner-only, so
-// only a process that can read the game folder can publish or tail as the
-// agent. `joystack relay` reads every file there and speaks to each server.
+// only a process that can read the game folder can reply as the agent. `joystack relay` reads every file there and speaks to each server.
 import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { stateDir } from '../legacy-names.mjs';

package/lib/relay/conversation.mjs

@@ -1,21 +1,22 @@
-// The hub's own listener for the laptop conversation: a `note.sent` event
-// (the note in shared/ui/note/, once the person pressed Send) becomes files
-// the agent can open under .joystack/relay/ and a message in the Claude Code
-// session that started this dev server, through that session's inbox socket
-// (agent-session.mjs). Installed only when a session started the server; a
-// server from a plain terminal has no such listener, and the maker's dev
-// server has none either (its conversation is the maker page's).
+// The laptop conversation: a note the person sent (shared/ui/note/, once
+// they pressed Send) becomes files the agent can open under .joystack/relay/
+// and a message in the Claude Code session that started this dev server,
+// through that session's inbox socket (agent-session.mjs). Made only when a
+// session started the server; a server from a plain terminal has none, and
+// the maker's dev server has none either (its conversation is the maker
+// page's).
 //
-// Reaching the agent starts paid work, so only a note the person sent from
-// the creator's own browser wakes it: the hub stamps `from.creator`, and a
-// page a phone on the wifi or a --share tester loaded is never the creator's.
+// Reaching the agent starts paid work, so only a note the creator's own
+// browser sent reaches here: the relay's route refuses any other page
+// (relay.mjs), and a page a phone on the wifi or a --share tester
+// loaded is never the creator's.
 import { randomBytes } from 'node:crypto';
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { postToSession, sessionAlive } from '../agent-session.mjs';
 import { relayDir } from './connection.mjs';
 
-// A page can publish in a loop. The agent is woken at most this often: a note
+// A page can send notes in a loop. The agent is woken at most this often: a note
 // sent sooner waits its turn, and once this many are waiting, the rest are
 // filed without waking it (a burst that size is a script, not someone typing).
 export const WAKE_MIN_INTERVAL_MS = 1000;
@@ -41,12 +42,12 @@ export function shellWord(text) {
 // so no line of it can read as one the server wrote (a second header, a
 // different reply command).
 const LINE_BREAK_RE = /\r\n?|[\u0085\u2028\u2029]/g;
-const asLines = (text) => String(text).replace(LINE_BREAK_RE, '\n').replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, '').split('\n');
+const asLines = (text) => String(text).replace(LINE_BREAK_RE, '\n').replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u0084\u0086-\u009f]/g, '').split('\n');
 const indented = (text) => asLines(text).map((l) => `  ${l}`).join('\n');
 // A label is one line: JSON.stringify escapes \n and \r but not the Unicode
 // separators, so they are made spaces first.
 const oneLine = (text) => asLines(text).join(' ');
-// The kind of thing attached is an event name (relay.mjs NAME_RE) or nothing.
+// The kind of thing attached is a relay name (`<owner>.<what>`) or nothing.
 const KIND_RE = /^[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)+$/;
 
 // The message that wakes the agent. Everything the server writes comes
@@ -58,8 +59,7 @@ export function agentMessage({ kind, label, words, text, file, image, id, projec
   if (words) lines.push(indented(words));
   lines.push(`Data: ${file}`);
   if (image) lines.push(`Picture of what they see: ${image}`);
-  const reply = JSON.stringify({ to: id, text: '<what you did>' });
-  lines.push(`Answer where they asked, in one or two sentences: node ${shellWord(cliBin)} relay publish --dir ${shellWord(projectDir)} agent.replied ${shellWord(reply)}`);
+  lines.push(`Answer where they asked, in one or two sentences: node ${shellWord(cliBin)} relay reply --dir ${shellWord(projectDir)} ${id} '<what you did>'`);
   lines.push('', ...asLines(String(text).trim()).map((line) => `> ${line}`));
   return lines.join('\n');
 }

package/lib/relay/engine.mjs

@@ -0,0 +1,15 @@
+// The folder of the engine's relay the dev server loads its pure files from:
+// the game's installed engine, or this CLI's own repository when it runs
+// from inside it. Null when that engine has no relay with `files` in it.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function relayFiles(sharedDir, files) {
+  // The repository's own relay only from a checkout of it: an installed CLI
+  // sits in node_modules, where the same path names a package called
+  // `shared`.
+  const repo = join(import.meta.dirname, '../../../..');
+  const fromRepo = existsSync(join(repo, 'packages', 'cli', 'package.json')) ? join(repo, 'shared', 'ui', 'relay') : null;
+  const candidates = [sharedDir && join(sharedDir, 'ui', 'relay'), fromRepo];
+  return candidates.find((dir) => dir && files.every((f) => existsSync(join(dir, f)))) ?? null;
+}

package/lib/relay/http.mjs

@@ -0,0 +1,57 @@
+// The relay's HTTP pieces on the dev server: answers, a bounded body, and
+// the agent's bearer token.
+import { timingSafeEqual } from 'node:crypto';
+
+// What one post may weigh: a pick carries its picture.
+export const MAX_BYTES = 8 * 1024 * 1024;
+const LOOPBACK = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
+
+export const json = (res, status, body, extra = {}) => {
+  const buf = Buffer.from(JSON.stringify(body));
+  res.writeHead(status, { 'Content-Type': 'application/json', 'Content-Length': buf.length, 'Cache-Control': 'no-store', ...extra });
+  res.end(buf);
+};
+export const text = (res, status, body, extra = {}) => {
+  res.writeHead(status, { 'Content-Type': 'text/plain', ...extra });
+  res.end(body);
+};
+// The agent's credential: a bearer token from a process on this machine,
+// never a browser (which always sends Origin on a cross-origin request and
+// cannot set this header from a page the server did not serve). 'agent'
+// when it is the server's token, 'refused' when a bearer was offered and is
+// not, null when none was offered.
+export function bearer(req, token) {
+  const header = String(req.headers.authorization ?? '');
+  if (!header.startsWith('Bearer ')) return null;
+  const supplied = Buffer.from(header.slice(7));
+  const expected = Buffer.from(token);
+  const ok = LOOPBACK.has(req.socket.remoteAddress) && !req.headers.origin
+    && supplied.length === expected.length && timingSafeEqual(supplied, expected);
+  return ok ? 'agent' : 'refused';
+}
+
+export function readBody(req, res, maxBytes) {
+  return new Promise((resolve) => {
+    const chunks = [];
+    let size = 0;
+    let overflowed = false;
+    req.on('data', (chunk) => {
+      if (overflowed) return; // draining the rest so the client can read the 413
+      size += chunk.length;
+      if (size > maxBytes) {
+        overflowed = true;
+        chunks.length = 0;
+        text(res, 413, `message too large (max ${maxBytes} bytes)`, { Connection: 'close' });
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => resolve(overflowed ? null : Buffer.concat(chunks).toString('utf8')));
+    // A client that goes before the body ends is answered by nobody; the
+    // promise still settles, so nothing waits on it for good.
+    req.on('close', () => { if (!req.complete) resolve(null); });
+    req.on('error', () => resolve(null));
+  });
+}
+export const parse = (raw) => { try { return JSON.parse(raw); } catch { return undefined; } };
+