@volter/teams 0.2.20 → 0.2.22

package/board-owner.mjs

@@ -0,0 +1,80 @@
+// A home's board owner (`supercode workflow serve`, one per install: D152) answers every card verb on that home's boards
+// over one local socket. The CLI and the machine daemon's board door hold nothing: each sends the verb here and renders
+// the answer. The socket is the home's own (`<home>/board.sock`, beside the owner's lock `<home>/board.lock`), by the
+// home's real path, so every process naming the home reaches the one owner whatever its environment.
+//
+//   request:  one JSON line  { v: 1, argv | tool, board, caller, session, facts, cwd, stdin }
+//               argv     the verb and its arguments, without --root or --board
+//               tool     a dispatched worker's board tool instead of a verb: { name, args, env } (its HERMES_KANBAN_*
+//                        task, run and board, and HERMES_PROFILE); answered with the tool's JSON as stdout
+//               board    the board's slug
+//               caller   the calling session's address when its side named it (`sc:<machine>:<harness>:<id>`), or null
+//               session  { id, harness } when the caller is a session on the owner's machine that the CLI named
+//               facts    what the caller's environment says of it (SUPERCODE_AGENT_ID, SUPERCODE_AUTOMATION,
+//                        SUPERCODE_CONTEXT, HERMES_PROFILE, USER, SUPERCODE_CALLER, and a launched worker's
+//                        SUPERCODE_RUN_LAUNCH: the owner's secret for its run, which only run-session reads)
+//               cwd      the caller's working directory, against which a path it names is read
+//               stdin    the caller's standard input, when it names `-` as a file (else null)
+//   answer:   one JSON line  { code, stdout, stderr }
+import { realpathSync } from 'node:fs';
+import { connect } from 'node:net';
+import { join, resolve } from 'node:path';
+
+/** A Unix socket's path is at most 104 bytes on macOS (108 on Linux), terminator included. */
+const SOCKET_PATH_MAX = 103;
+
+/** The home's real path. */
+export function boardHome(root) {
+  try { return realpathSync(resolve(root)); } catch { return resolve(root); }
+}
+
+/** The owner's socket for the home at `root`: the home's own, by its real path. */
+export function boardOwnerSocket(root) {
+  const path = join(boardHome(root), 'board.sock');
+  if (Buffer.byteLength(path) > SOCKET_PATH_MAX) throw new Error(`the home's board socket ${path} is longer than a Unix socket path may be (${SOCKET_PATH_MAX} bytes); keep the home at a shorter path`);
+  return path;
+}
+
+/**
+ * The verbs that are a board's own operation, run on its machine as acts of their own and never sent to its owner or
+ * through the board door: the owner itself and its one-shot round, init, adoption, the board list, housekeeping and
+ * repair, migration, the dispatching switch, and the verbs that hold the call open (watch, tail, attach, events).
+ */
+export const BOARD_OPERATION_VERBS = new Set(['serve', 'daemon', 'dispatch', 'dispatching', 'init', 'boards', 'gc', 'repair', 'migrate', 'watch', 'tail', 'events']);
+
+/** The facts of a caller's environment the owner reads, and nothing else of it. */
+export const CALLER_FACTS = ['SUPERCODE_AGENT_ID', 'SUPERCODE_AUTOMATION', 'SUPERCODE_CONTEXT', 'HERMES_PROFILE', 'USER', 'SUPERCODE_CALLER', 'SUPERCODE_RUN_LAUNCH'];
+export const callerFacts = (env = process.env) => Object.fromEntries(CALLER_FACTS.filter((key) => env[key]).map((key) => [key, env[key]]));
+
+/**
+ * Send one verb to the owner of the home at `root`: answers `{ code, stdout, stderr }`. A home whose owner is not
+ * running answers that, with what starts it; nothing else runs the verb.
+ */
+export function askBoardOwner(root, request) {
+  let path;
+  try { path = boardOwnerSocket(root); } catch (error) { return Promise.resolve({ code: 1, stdout: '', stderr: `${error.message}\n` }); }
+  return new Promise((done) => {
+    let answer = '';
+    let settled = false;
+    const finish = (value) => { if (!settled) { settled = true; done(value); } };
+    const socket = connect(path);
+    socket.setEncoding('utf8');
+    // The request is one line, and the connection stays open both ways until the answer's line has come: an answer that
+    // takes its time (a Teams lookup, a reread home) is never lost to a closed side.
+    socket.on('connect', () => socket.write(`${JSON.stringify({ v: 1, ...request })}\n`));
+    socket.on('data', (chunk) => {
+      answer += chunk;
+      const end = answer.indexOf('\n');
+      if (end < 0) return;
+      socket.end();
+      try { finish(JSON.parse(answer.slice(0, end))); } catch { finish({ code: 1, stdout: '', stderr: `the board owner of ${root} answered nothing readable\n` }); }
+    });
+    socket.on('close', () => finish({ code: 1, stdout: '', stderr: `the board owner of ${root} closed the call before answering\n` }));
+    socket.on('error', (error) => {
+      const down = ['ENOENT', 'ECONNREFUSED'].includes(error.code);
+      finish({ code: 1, stdout: '', stderr: down
+        ? `the boards of ${root} have no running owner: \`supercode workflow serve --root ${root}\` is it (an install's keeper runs it)\n`
+        : `the board owner of ${root} could not be reached: ${error.message}\n` });
+    });
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/teams",
-  "version": "0.2.20",
+  "version": "0.2.22",
   "type": "module",
   "description": "Volter Teams, the neutral team plane: machine identity and daemon core, the local door and server link, admission from machine grants, product doors, and the Teams server's neutral routes (company RFC 0008).",
   "license": "MIT",
@@ -54,7 +54,8 @@
       "default": "./redact.mjs"
     },
     "./checkout": "./checkout.mjs",
-    "./board-name": "./board-name.mjs"
+    "./board-name": "./board-name.mjs",
+    "./board-owner": "./board-owner.mjs"
   },
   "files": [
     "LICENSE-MIT",