@claudecollab/cli 0.1.0

package/packages/cli/src/hooks.js

@@ -0,0 +1,243 @@
+// Hook injection + event listener — how claude-share learns Claude's state.
+//
+// We never scrape the repainting TUI for state (spec §agent state detection).
+// Instead claude-share launches Claude with a `--settings` file whose four hooks
+// each POST their stdin JSON to a private unix socket, and this module serves that
+// socket and maps every hook to one internal event:
+//
+//   Claude hook        internal event   why
+//   ────────────────   ──────────────   ─────────────────────────────────────────
+//   UserPromptSubmit  → 'busy'          turn started; payload carries permission_mode
+//   Stop              → 'idle'          turn finished; queue may drain (fail-closed)
+//   Notification      → 'ask'           ONLY when notification_type=permission_prompt
+//   PostToolUse       → 'tool'          a tool ran; feeds the join context card
+//
+// Gate on events, not predictions (spec): Claude auto-approves harmless read-only
+// bash via its own heuristics, so which command will prompt is not predictable. The
+// permission gate therefore arms ONLY on the permission_prompt Notification — any
+// other Notification is dropped here so it can never arm the gate.
+
+import net from 'node:net';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { EventEmitter } from 'node:events';
+import process from 'node:process';
+
+/** The Claude Code hooks we inject, in the order they appear in the settings file. */
+export const HOOK_EVENTS = Object.freeze(['UserPromptSubmit', 'Stop', 'Notification', 'PostToolUse']);
+
+// Hooks with a one-to-one internal event. Notification and UserPromptSubmit are
+// special-cased below.
+const SIMPLE = Object.freeze({
+  Stop: 'idle',
+  PostToolUse: 'tool',
+});
+
+/**
+ * Map a Claude hook name + its parsed payload to an internal event, or null to
+ * drop it. Pure, so the whole routing table is unit-testable without a socket.
+ * @param {string} hook   Claude hook name (e.g. 'UserPromptSubmit')
+ * @param {object} payload parsed hook JSON (may be null)
+ * @returns {'busy'|'idle'|'ask'|'tool'|null}
+ */
+export function mapHookEvent(hook, payload) {
+  if (hook === 'Notification') {
+    return payload && payload.notification_type === 'permission_prompt' ? 'ask' : null;
+  }
+  // A slash command (/model) or ! bash line fires UserPromptSubmit on submission
+  // but resolves client-side: no turn runs, so no Stop hook ever follows. Flipping
+  // busy on that edge wedges the room "brewing" forever (dogfood: /model from a
+  // draft froze the queue). Drop the busy edge for those — a slash command that
+  // DOES run a real turn (a skill) still flips busy at its first PostToolUse.
+  // No prompt text in the payload → fail toward busy (a real turn may be starting).
+  if (hook === 'UserPromptSubmit') {
+    const p = payload && typeof payload.prompt === 'string' ? payload.prompt.trimStart() : '';
+    return p.startsWith('/') || p.startsWith('!') ? null : 'busy';
+  }
+  return SIMPLE[hook] ?? null;
+}
+
+// The body of the injected `node -e` poster. It reads Claude's hook JSON from
+// stdin, connects to our unix socket, and writes one line: {hook, payload} where
+// payload is the raw JSON string (the listener parses it). It fails silently on
+// any socket error so a relay/listener hiccup can never break a Claude hook.
+//
+// Constraints that keep this shell-safe:
+//   • NO single quotes inside — the whole body is wrapped in single quotes for sh.
+//   • argv[1] = hook name, argv[2] = socket path (passed as command args).
+const POSTER = [
+  'const net=require("net");',
+  'let d="";',
+  'process.stdin.on("data",c=>d+=c);',
+  'process.stdin.on("end",()=>{',
+  'const s=net.connect(process.argv[2]);',
+  's.on("connect",()=>s.end(JSON.stringify({hook:process.argv[1],payload:d})+"\\n"));',
+  's.on("error",()=>process.exit(0));',
+  '});',
+].join('');
+
+/**
+ * Build the shell command string for one injected hook. Uses `node -e` (per plan,
+ * not `nc`), the current node binary (robust vs. PATH), and double-quotes the
+ * node path + socket path so spaces survive the shell.
+ * @param {string} hook       Claude hook name
+ * @param {string} socketPath unix socket the listener serves
+ * @returns {string}
+ */
+export function buildHookCommand(hook, socketPath) {
+  return `"${process.execPath}" -e '${POSTER}' ${hook} "${socketPath}"`;
+}
+
+/**
+ * Build the Claude Code `--settings` object: one command hook per event, in the
+ * shape Claude expects (`{ hooks: { <Event>: [{ hooks: [{type,command}] }] } }`).
+ * @param {string} socketPath
+ * @returns {object}
+ */
+export function buildHookSettings(socketPath) {
+  const hooks = {};
+  for (const hook of HOOK_EVENTS) {
+    hooks[hook] = [{ hooks: [{ type: 'command', command: buildHookCommand(hook, socketPath) }] }];
+  }
+  return { hooks };
+}
+
+/**
+ * Write the settings file to a temp path and return it — pass this to Claude as
+ * `--settings <file>`. Caller deletes it on teardown.
+ * @param {string} socketPath
+ * @returns {string} absolute path to the settings file
+ */
+export function installHooks(socketPath) {
+  const rand = Math.random().toString(36).slice(2, 8);
+  const file = path.join(os.tmpdir(), `claude-share-settings-${process.pid}-${rand}.json`);
+  fs.writeFileSync(file, JSON.stringify(buildHookSettings(socketPath), null, 2));
+  return file;
+}
+
+/**
+ * Serves the unix socket the injected hooks post to, turning each post into an
+ * internal event. Extends EventEmitter, so consumers do `.on('busy'|'idle'|'ask'|'tool', payload)`.
+ * Also emits `'mode'` when the tracked permission_mode changes, and `'error'` for
+ * post-listen server errors.
+ */
+export class HookListener extends EventEmitter {
+  #server;
+  #socketPath;
+  #mode = null;
+
+  /** @param {string} socketPath path to bind the unix socket at */
+  constructor(socketPath) {
+    super();
+    this.#socketPath = socketPath;
+    // A stale socket file from a crashed run would make listen() throw EADDRINUSE.
+    try {
+      fs.unlinkSync(socketPath);
+    } catch {}
+
+    this.#server = net.createServer((conn) => this.#onConnection(conn));
+
+    /** Resolves once the socket is accepting connections; rejects if it can't bind. */
+    this.ready = new Promise((resolve, reject) => {
+      const onErr = (err) => reject(err);
+      this.#server.once('error', onErr);
+      this.#server.listen(socketPath, () => {
+        this.#server.removeListener('error', onErr);
+        this.#server.on('error', (err) => this.emit('error', err));
+        resolve();
+      });
+    });
+    // Don't crash the process if nobody awaits ready and the bind fails.
+    this.ready.catch(() => {});
+    // The socket must not keep the event loop alive on its own.
+    if (typeof this.#server.unref === 'function') this.#server.unref();
+  }
+
+  /** The last permission_mode seen on any hook payload (null until the first hook). */
+  get mode() {
+    return this.#mode;
+  }
+
+  #onConnection(conn) {
+    let buf = '';
+    let done = false;
+    conn.setEncoding('utf8');
+    const finish = () => {
+      if (done) return;
+      done = true;
+      this.#ingest(buf);
+    };
+    conn.on('data', (c) => {
+      buf += c;
+    });
+    conn.on('end', finish);
+    conn.on('close', finish);
+    conn.on('error', () => {}); // a dropped hook connection is not our problem
+  }
+
+  #ingest(buf) {
+    for (const line of buf.split('\n')) {
+      const trimmed = line.trim();
+      if (trimmed === '') continue;
+      let msg;
+      try {
+        msg = JSON.parse(trimmed);
+      } catch {
+        continue; // malformed line: drop it, keep serving
+      }
+      this.#handle(msg);
+    }
+  }
+
+  #handle(msg) {
+    if (!msg || typeof msg !== 'object') return;
+    const hook = msg.hook;
+    let payload = msg.payload;
+    // The injected poster sends payload as a raw JSON string; parse it back.
+    if (typeof payload === 'string') {
+      try {
+        payload = JSON.parse(payload);
+      } catch {
+        payload = {};
+      }
+    }
+    if (!payload || typeof payload !== 'object') payload = {};
+
+    const event = mapHookEvent(hook, payload);
+    // permission_mode rides on EVERY hook payload (spec: mode tracking for free), so
+    // track it from any hook — not only UserPromptSubmit. A mode flip (Shift+Tab)
+    // then surfaces the moment the next hook of any kind fires (Stop, PostToolUse, a
+    // permission Notification, or the next prompt), so the room's mode-change warning
+    // banner is raised on the mode-change signal itself rather than waiting for the
+    // next UserPromptSubmit. Update before emitting so an event handler reading .mode
+    // sees the fresh value.
+    if (typeof payload.permission_mode === 'string' && payload.permission_mode !== this.#mode) {
+      this.#mode = payload.permission_mode;
+      this.emit('mode', this.#mode);
+    }
+    if (event) this.emit(event, payload);
+  }
+
+  /** Stop serving and remove the socket file. */
+  close() {
+    return new Promise((resolve) => {
+      this.#server.close(() => {
+        try {
+          fs.unlinkSync(this.#socketPath);
+        } catch {}
+        resolve();
+      });
+    });
+  }
+}
+
+/**
+ * Start serving the hook socket. `listenHooks(path).on('busy'|'idle'|'ask'|'tool', payload)`.
+ * Await the returned listener's `.ready` before expecting events.
+ * @param {string} socketPath
+ * @returns {HookListener}
+ */
+export function listenHooks(socketPath) {
+  return new HookListener(socketPath);
+}

package/packages/cli/src/invite.js

@@ -0,0 +1,43 @@
+// Room-URL helpers + the room-ready toast — pure so they are unit-testable and so the
+// host/guest URL distinction lives in exactly one place.
+//
+// TWO different URLs, and mixing them up is a security bug:
+//   • hostUrl  — carries ?host=<token>. Whoever opens it is auto-admitted as HOST (no
+//     knock): they can /end, /kick, set roles, /pause. This is for the host's OWN tab.
+//   • inviteUrl — token-free. This is the safe link to hand a friend; they land on the
+//     normal knock/roles flow. This is what we copy to the clipboard.
+// The earlier code surfaced ONLY the hostUrl (status line + clipboard + "link copied"),
+// so the natural "paste the clipboard link to a friend" flow silently granted the host
+// seat. Keep them separate: hostUrl on the host's own status line, inviteUrl on the
+// clipboard and the host tab's "copy invite" button.
+
+// A deployed relay advertises its public https origin (`base`) in the room grant;
+// links then carry that origin. Localhost dev has no base → http://host:port.
+function origin({ base, host, port }) {
+  if (base) return String(base).replace(/\/+$/, '');
+  return `http://${host}:${port}`;
+}
+
+/** The host's own tab URL — carries the host token (auto-admit as host). */
+export function hostUrl({ base, host, port, code, token }) {
+  return `${origin({ base, host, port })}/${code}?host=${token}`;
+}
+
+/** The token-free invite URL — the safe link to share with guests. */
+export function inviteUrl({ base, host, port, code }) {
+  return `${origin({ base, host, port })}/${code}`;
+}
+
+/**
+ * The "room ready" toast. Only claims the clipboard when the copy actually happened —
+ * the copy is macOS-only, opt-out via CLAUDE_SHARE_NO_CLIPBOARD, and can fail. Claiming
+ * it unconditionally (as before) told a linux/opt-out/failed host the link was on the
+ * clipboard when it was not, which — with a truncated status line — could leave them
+ * unable to reach their own room.
+ * @param {boolean} copied  did the invite actually land on the clipboard?
+ */
+export function readyToast(copied) {
+  return copied
+    ? 'room ready · invite link copied to clipboard'
+    : 'room ready · copy the invite from your host tab';
+}

package/packages/cli/src/known-relays.js

@@ -0,0 +1,66 @@
+// Relay identity pinning — the CLI-side half of host-key verification (spec
+// §trust: the host must know it is talking to ITS relay, not an impersonator).
+// Works like ssh's known_hosts, trust-on-first-use: the first connection to a
+// relay stores its SHA256:… key fingerprint under "host:port"; every later
+// connection must present the same one or the CLI refuses to connect.
+//
+// An explicit expected fingerprint (--fingerprint, e.g. copied from the relay's
+// boot log) skips the store entirely and pins exactly that value.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Read the pin store (a flat {"host:port": "SHA256:…"} map). Missing/corrupt ⇒ empty. */
+export function loadPins(file) {
+  try {
+    const o = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return o !== null && typeof o === 'object' && !Array.isArray(o) ? o : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Persist one pin. Best-effort: an unwritable home degrades to session-only TOFU. */
+export function savePin(file, key, fp) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const pins = loadPins(file);
+    pins[key] = fp;
+    fs.writeFileSync(file, JSON.stringify(pins, null, 2) + '\n', { mode: 0o600 });
+  } catch {
+    /* home not writable — the in-memory pin still guards this run */
+  }
+}
+
+/**
+ * One pin check per connection attempt, handed to connectRelay's verifyHostKey.
+ * `verify` returns whether to proceed; afterwards `outcome()` says what happened
+ * so the caller can tell a mismatch (scary, do not retry) from a plain failure.
+ *
+ * @param {object} opts
+ * @param {string} opts.key         store key, "host:port"
+ * @param {string} opts.file        pin-store path (~/.claude-share/known_relays.json)
+ * @param {string} [opts.expected]  explicit fingerprint; when set the store is not consulted
+ * @returns {{verify(fp:string):boolean, outcome():'first-seen'|'match'|'mismatch'|null, expected():string|null, seen():string|null}}
+ */
+export function createPinCheck({ key, file, expected }) {
+  let want = expected ?? null;
+  let outcome = null;
+  let seen = null;
+  const verify = (fp) => {
+    seen = fp;
+    if (!want) {
+      want = loadPins(file)[key] ?? null;
+      if (!want) {
+        // First contact: adopt and store this identity (TOFU, like ssh).
+        savePin(file, key, fp);
+        want = fp;
+        outcome = 'first-seen';
+        return true;
+      }
+    }
+    outcome = fp === want ? 'match' : 'mismatch';
+    return outcome === 'match';
+  };
+  return { verify, outcome: () => outcome, expected: () => want, seen: () => seen };
+}

package/packages/cli/src/pty.js

@@ -0,0 +1,175 @@
+// The PTY wrapper: spawn Claude in a terminal that is `bandRows` shorter than
+// the real one, and hand its output to the caller split on synchronized-update
+// frame boundaries so the band can redraw without smearing mid-repaint.
+//
+// Two pieces:
+//   • FrameSplitter — pure stream cutter on the `?2026l` marker (unit-tested).
+//   • startPty()    — spawns node-pty, wires FrameSplitter + an idle flush, and
+//                     exposes { onFrame, onExit, write, resize, kill }.
+//
+// node-pty is a native module and is imported lazily inside startPty, so this
+// file (and FrameSplitter's tests) load fine even where node-pty isn't built.
+
+/** Synchronized-update END marker. Claude ends every repaint frame with this. */
+export const SU_END = '\x1b[?2026l';
+/** Synchronized-update BEGIN marker (exported for reference / future use). */
+export const SU_BEGIN = '\x1b[?2026h';
+
+/**
+ * Cuts a byte stream into frames on the `?2026l` boundary. Feed chunks with
+ * push(); it returns every complete frame (each ending in the marker) and holds
+ * the trailing partial frame until more arrives or you flush(). Handles a marker
+ * that straddles a chunk boundary because it buffers before searching.
+ */
+export class FrameSplitter {
+  #buf = '';
+
+  /**
+   * @param {string} chunk decoded terminal output
+   * @returns {string[]} complete frames this chunk finished (possibly empty)
+   */
+  push(chunk) {
+    this.#buf += chunk;
+    const frames = [];
+    let idx;
+    while ((idx = this.#buf.indexOf(SU_END)) !== -1) {
+      const end = idx + SU_END.length;
+      frames.push(this.#buf.slice(0, end));
+      this.#buf = this.#buf.slice(end);
+    }
+    return frames;
+  }
+
+  /** Return + clear whatever partial frame is buffered (null if empty). */
+  flush() {
+    if (this.#buf === '') return null;
+    const rem = this.#buf;
+    this.#buf = '';
+    return rem;
+  }
+
+  /** Bytes currently buffered without a terminating marker. */
+  get pending() {
+    return this.#buf.length;
+  }
+}
+
+/**
+ * Spawn a command in a shortened PTY and stream its output as frames.
+ *
+ * @param {object} opts
+ * @param {string} opts.cmd            binary to spawn (e.g. 'claude')
+ * @param {string[]} [opts.args]       arguments
+ * @param {number} [opts.bandRows=2]   rows reserved at the bottom for the band
+ * @param {number} [opts.cols]         real terminal columns (default stdout)
+ * @param {number} [opts.rows]         real terminal rows (default stdout)
+ * @param {object} [opts.env]          extra env merged over process.env
+ * @param {string} [opts.cwd]          working directory
+ * @param {number} [opts.flushMs=8]    idle delay before flushing a markerless tail
+ * @returns {Promise<{onFrame,onExit,write,resize,kill,cols,childRows}>}
+ */
+export async function startPty({
+  cmd,
+  args = [],
+  bandRows = 2,
+  cols,
+  rows,
+  env,
+  cwd,
+  flushMs = 8,
+} = {}) {
+  const mod = await import('node-pty');
+  const spawn = mod.spawn ?? mod.default?.spawn;
+  if (typeof spawn !== 'function') {
+    throw new Error('node-pty did not export spawn(); is it installed and built?');
+  }
+
+  const realCols = cols ?? process.stdout.columns ?? 80;
+  const realRows = rows ?? process.stdout.rows ?? 24;
+  const childRows = Math.max(1, realRows - bandRows);
+
+  const term = spawn(cmd, args, {
+    name: 'xterm-256color',
+    cols: realCols,
+    rows: childRows,
+    cwd: cwd ?? process.cwd(),
+    env: { ...process.env, ...env },
+  });
+
+  const splitter = new FrameSplitter();
+  const frameCbs = new Set();
+  const exitCbs = new Set();
+  let flushTimer = null;
+
+  const emit = (chunk) => {
+    if (chunk) for (const cb of frameCbs) cb(chunk);
+  };
+
+  const scheduleFlush = () => {
+    if (flushTimer) return;
+    flushTimer = setTimeout(() => {
+      flushTimer = null;
+      emit(splitter.flush());
+    }, flushMs);
+    if (typeof flushTimer.unref === 'function') flushTimer.unref();
+  };
+
+  term.onData((d) => {
+    for (const frame of splitter.push(typeof d === 'string' ? d : d.toString('utf8'))) {
+      emit(frame);
+    }
+    scheduleFlush();
+  });
+
+  term.onExit((e) => {
+    if (flushTimer) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+    emit(splitter.flush()); // deliver any tail before we report exit
+    for (const cb of exitCbs) cb(e);
+  });
+
+  return {
+    /** Register a frame callback. Returns an unsubscribe fn. */
+    onFrame(cb) {
+      frameCbs.add(cb);
+      return () => frameCbs.delete(cb);
+    },
+    /** Register an exit callback ({exitCode, signal}). Returns an unsubscribe fn. */
+    onExit(cb) {
+      exitCbs.add(cb);
+      return () => exitCbs.delete(cb);
+    },
+    /** Send input (keystrokes) to the child. */
+    write(data) {
+      term.write(typeof data === 'string' ? data : data.toString('utf8'));
+    },
+    /** Resize the child PTY to (newCols, newRows - bandRows). Defaults to stdout size. */
+    resize(newCols, newRows) {
+      const c = newCols ?? process.stdout.columns ?? realCols;
+      const r = (newRows ?? process.stdout.rows ?? realRows) - bandRows;
+      term.resize(Math.max(1, c), Math.max(1, r));
+    },
+    /**
+     * Resize the child PTY to an EXACT size (cols × childRows), no band arithmetic.
+     * The band's height is dynamic (it grows/shrinks with content), so the caller
+     * computes Claude's region directly — rows minus the current band height — and
+     * sets it here (dogfood finding: the child must shrink/grow so the band never
+     * overlaps Claude's output). Undefined dimensions keep the current one.
+     */
+    resizeChild(newCols, childRows) {
+      term.resize(Math.max(1, newCols ?? term.cols), Math.max(1, childRows ?? term.rows));
+    },
+    /** Kill the child. */
+    kill(signal) {
+      term.kill(signal);
+    },
+    get cols() {
+      return term.cols;
+    },
+    get childRows() {
+      return term.rows;
+    },
+  };
+}