@claudecollab/cli 0.1.0

package/packages/cli/src/brain/knocks.js

@@ -0,0 +1,27 @@
+// Pending-knock bookkeeping (spec §knock). One card per guest: a WS reconnect during
+// the join flow re-knocks with a NEW connection id but the SAME fingerprint, and the
+// stock ssh/browser flows can double-fire a knock too. Without dedup the host sees two
+// cards for one guest and can admit the stale one (finding 3), landing a phantom in the
+// roster and count. So a re-knock from the same fingerprint REPLACES the prior pending
+// knock rather than stacking a duplicate.
+//
+// Pure, so it is unit-tested without a relay. bin/claude-share.js calls foldKnock on
+// each relay KNOCK, swaps in the returned list, and denies the `replaced` connections.
+
+/**
+ * Fold a new knock into the pending list, replacing any earlier pending knock from the
+ * same (non-empty) fingerprint. Keyless / tokenless guests carry an empty fp — every
+ * one of those is a distinct person, so they are never deduped.
+ *
+ * @param {Array<{id:string,name:string,fp:string,seen:*}>} pending  current pending knocks
+ * @param {{id:string,name:string,fp:string,seen:*}} knock            the arriving knock
+ * @returns {{pending: Array, replaced: string[]}}  new list (newest knock last) + the
+ *   connection ids of the superseded knocks the caller should deny/forget
+ */
+export function foldKnock(pending, knock) {
+  const list = Array.isArray(pending) ? pending : [];
+  if (!knock || !knock.fp) return { pending: [...list, knock], replaced: [] };
+  const replaced = list.filter((k) => k.fp === knock.fp).map((k) => k.id);
+  const kept = list.filter((k) => k.fp !== knock.fp);
+  return { pending: [...kept, knock], replaced };
+}

package/packages/cli/src/brain/log.js

@@ -0,0 +1,123 @@
+// The in-memory attributed log — the room's who-typed-what record (spec §host
+// controls, §join context card). It captures three kinds of entry:
+//
+//   prompt  — a sent draft, attributed to its author (feeds the card + /recap)
+//   event   — a room event: joins, leaves, role changes, kicks, mode flips, pause
+//   tool    — a Claude PostToolUse, with the files it touched (feeds the card)
+//
+// The log lives only for the session. On /end the host chooses whether to persist
+// it: N discards it, Y writes session.md via write(). toText() is the plain
+// transcript /recap hands to a one-shot `claude -p`.
+
+import fs from 'node:fs';
+
+export class Log {
+  #entries = [];
+  #files = [];
+  #now;
+  #startedAt;
+
+  /** @param {object} [opts] @param {() => number} [opts.now] injectable clock */
+  constructor({ now = () => Date.now() } = {}) {
+    this.#now = now;
+    this.#startedAt = now();
+  }
+
+  /** Record an attributed prompt. */
+  prompt(author, text, at = this.#now()) {
+    const e = { kind: 'prompt', author, text: String(text), at };
+    this.#entries.push(e);
+    return e;
+  }
+
+  /** Record a room event (join/leave/role/kick/mode/pause). */
+  event(text, at = this.#now()) {
+    const e = { kind: 'event', text: String(text), at };
+    this.#entries.push(e);
+    return e;
+  }
+
+  /** Record a tool use and merge any touched files into the ordered unique list. */
+  tool(name, files = [], at = this.#now()) {
+    const list = Array.isArray(files) ? files : [];
+    const e = { kind: 'tool', name, files: [...list], at };
+    for (const f of list) if (f && !this.#files.includes(f)) this.#files.push(f);
+    this.#entries.push(e);
+    return e;
+  }
+
+  /** All entries, as copies. */
+  get entries() {
+    return this.#entries.map((e) => ({ ...e }));
+  }
+
+  /** The de-duplicated files touched so far, in first-touch order. */
+  get files() {
+    return [...this.#files];
+  }
+
+  get startedAt() {
+    return this.#startedAt;
+  }
+
+  /** Just the prompt entries. */
+  prompts() {
+    return this.#entries.filter((e) => e.kind === 'prompt').map((e) => ({ ...e }));
+  }
+
+  /** The last `n` prompts, oldest→newest. */
+  recentPrompts(n = 3) {
+    const p = this.prompts();
+    return p.slice(Math.max(0, p.length - n));
+  }
+
+  /** Author of the most recent prompt, or null. */
+  lastPromptAuthor() {
+    const p = this.#entries.filter((e) => e.kind === 'prompt');
+    return p.length ? p[p.length - 1].author : null;
+  }
+
+  /** Plain attributed transcript — the input /recap feeds to `claude -p`. */
+  toText() {
+    return this.#entries
+      .map((e) => {
+        if (e.kind === 'prompt') return `${e.author}: ${e.text}`;
+        if (e.kind === 'event') return `* ${e.text}`;
+        if (e.kind === 'tool') return `[tool] ${e.name}${e.files.length ? ' ' + e.files.join(', ') : ''}`;
+        return '';
+      })
+      .join('\n');
+  }
+
+  /**
+   * Render the attributed log as a Markdown session record.
+   * @param {object} [opts]
+   * @param {string} [opts.title]  document title
+   * @returns {string}
+   */
+  toMarkdown({ title = 'claude-share session' } = {}) {
+    const rel = (at) => {
+      const s = Math.max(0, Math.round((at - this.#startedAt) / 1000));
+      const mm = String(Math.floor(s / 60)).padStart(2, '0');
+      const ss = String(s % 60).padStart(2, '0');
+      return `${mm}:${ss}`;
+    };
+    const lines = [`# ${title}`, ''];
+    for (const e of this.#entries) {
+      if (e.kind === 'prompt') lines.push(`- \`${rel(e.at)}\` **${e.author}**: ${e.text}`);
+      else if (e.kind === 'event') lines.push(`- \`${rel(e.at)}\` _${e.text}_`);
+      else if (e.kind === 'tool')
+        lines.push(`- \`${rel(e.at)}\` \`${e.name}\`${e.files.length ? ' — ' + e.files.join(', ') : ''}`);
+    }
+    if (this.#files.length) {
+      lines.push('', '## Files touched', '', ...this.#files.map((f) => `- ${f}`));
+    }
+    return lines.join('\n') + '\n';
+  }
+
+  /** Write the Markdown record to a file (spec §host controls: /end → session.md). */
+  write(filePath, opts) {
+    fs.writeFileSync(filePath, this.toMarkdown(opts));
+    return filePath;
+  }
+}

package/packages/cli/src/brain/queue.js

@@ -0,0 +1,81 @@
+// The attributed queue — where sent drafts land while Claude is busy, and from
+// which they drain, in order, one per idle turn (spec §queue). Pure logic; the
+// wiring calls drain() from the 'idle' hook handler and feeds the released item
+// to the PTY.
+//
+// Permissions (spec): the author may edit or delete their own item; the host and
+// the host may delete anyone's. Draining is fail-closed — it only releases an item
+// when Claude is *known* idle; any other (or unknown) state keeps the queue frozen
+// so a missed hook can never auto-fire a stranger's prompt.
+
+import { atLeast } from './state.js';
+
+export class Queue {
+  #items = [];
+  #seq = 0;
+
+  /** Append an attributed item; returns the stored record (with its id). */
+  enqueue(text, author) {
+    const item = { id: `q${++this.#seq}`, text: String(text), author };
+    this.#items.push(item);
+    return item;
+  }
+
+  /** Defensive copies so a caller can't mutate queue internals through a read. */
+  get items() {
+    return this.#items.map((i) => ({ ...i }));
+  }
+
+  get length() {
+    return this.#items.length;
+  }
+
+  /** The front item (copy) without removing it, or null. */
+  peek() {
+    return this.#items[0] ? { ...this.#items[0] } : null;
+  }
+
+  /**
+   * Edit a queued item's text. Author-only (spec): the host can DELETE any
+   * item but may not rewrite what someone else meant to say.
+   * @returns {boolean} true if edited
+   */
+  edit(id, text, byUserId, _byRole) {
+    const it = this.#items.find((i) => i.id === id);
+    if (!it || it.author !== byUserId) return false;
+    it.text = String(text);
+    return true;
+  }
+
+  /**
+   * Delete a queued item. Allowed for the author, or for the host on any item.
+   * @returns {boolean} true if removed
+   */
+  remove(id, byUserId, byRole) {
+    const idx = this.#items.findIndex((i) => i.id === id);
+    if (idx === -1) return false;
+    const it = this.#items[idx];
+    if (it.author !== byUserId && !atLeast(byRole, 'host')) return false;
+    this.#items.splice(idx, 1);
+    return true;
+  }
+
+  /** Drop every item authored by a user (they left or were kicked). Returns the count. */
+  removeByAuthor(userId) {
+    const before = this.#items.length;
+    this.#items = this.#items.filter((i) => i.author !== userId);
+    return before - this.#items.length;
+  }
+
+  /**
+   * Release the front item — but only when Claude is *known* idle. Any other state
+   * (busy, ask, or an ambiguous/undefined signal) returns null and leaves the queue
+   * untouched (fail closed, spec §agent-state-detection).
+   * @param {string} claudeState the current hook-derived state
+   * @returns {{id:string,text:string,author:string}|null}
+   */
+  drain(claudeState) {
+    if (claudeState !== 'idle') return null;
+    return this.#items.shift() ?? null;
+  }
+}

package/packages/cli/src/brain/state.js

@@ -0,0 +1,245 @@
+// Room state — the host brain's canonical view of who is in the room, what role
+// each holds, Claude's current permission mode, whether sharing is paused, and
+// how big the shared screen may be (spec §roles, §renderer size clamp).
+//
+// Pure state, no I/O. The relay client feeds it join/leave/resize; the hook
+// listener feeds it the mode; commands mutate roles/pause. The renderer and the
+// join-context card read it. Roles rank here so gate.js / queue.js / commands.js
+// share one source of truth for "who outranks whom".
+
+/** Role names, lowest privilege first. */
+export const ROLES = Object.freeze(['viewer', 'prompter', 'host']);
+
+/** Numeric privilege rank — higher answers more (spec §roles table). */
+export const ROLE_RANK = Object.freeze({ viewer: 0, prompter: 1, host: 2 });
+
+/**
+ * Is `role` at least as privileged as `min`? Fails closed: an unknown actor role
+ * ranks below everything, and an unknown required floor is unreachable.
+ * @param {string} role
+ * @param {string} min
+ * @returns {boolean}
+ */
+export function atLeast(role, min) {
+  const have = ROLE_RANK[role];
+  const need = ROLE_RANK[min];
+  if (have == null || need == null) return false;
+  return have >= need;
+}
+
+// Spec §renderer: the shared view is clamped to the smallest participant's
+// terminal, floored at 80×24. A participant below the floor spectates instead of
+// shrinking the room for everyone.
+export const FLOOR_COLS = 80;
+export const FLOOR_ROWS = 24;
+
+// Stable participant colors for the browser overlay (spec §roles: "color is a
+// bonus — colorblind-safe by not being load-bearing"; name tags carry identity).
+// Eight distinct hues, assigned by the brain per fingerprint so a returning key
+// keeps its color on reconnect. Kept accessible/distinct; never load-bearing.
+export const PALETTE = Object.freeze([
+  '#e5484d', // red
+  '#f76b15', // orange
+  '#ffb224', // amber
+  '#30a46c', // green
+  '#0091ff', // blue
+  '#8e4ec6', // purple
+  '#e93d82', // pink
+  '#12a594', // teal
+]);
+
+/** The host's own participant id (the host is not a relay guest). */
+export const HOST_ID = 'host';
+
+export class RoomState {
+  /** @type {Map<string,{id:string,name:string,fp:string|null,role:string,cols?:number,rows?:number}>} */
+  participants = new Map();
+  mode = 'default';
+  paused = false;
+  room = null;
+  startedAt;
+
+  #defaultRole;
+  #now;
+  // fp -> the last role that fingerprint held this session. A returning key resumes
+  // its seat's role on reconnect (spec §identity: name, color, role restored on
+  // reconnect); keyless guests (no fp) are never recorded and rejoin as new.
+  #seatRoles = new Map();
+  // colorKey -> palette color. The key is a fingerprint (so a returning key keeps its
+  // color) or, for the host and keyless guests, the participant id. Assigned in first-
+  // seen order and wrapped modulo the palette so it never runs out.
+  #colorByKey = new Map();
+
+  /**
+   * @param {object} [opts]
+   * @param {string} [opts.hostName='host']       display name for the host
+   * @param {string} [opts.defaultRole='prompter'] role new guests get (spec default)
+   * @param {{cols:number,rows:number}} [opts.hostSize] the host terminal size
+   * @param {() => number} [opts.now]             injectable clock (ms)
+   */
+  constructor({ hostName = 'host', defaultRole = 'prompter', hostSize, now = () => Date.now() } = {}) {
+    this.#now = now;
+    this.#defaultRole = defaultRole;
+    this.startedAt = now();
+    this.participants.set(HOST_ID, {
+      id: HOST_ID,
+      name: hostName,
+      fp: null,
+      role: 'host',
+      color: this.#assignColor(HOST_ID),
+      cols: hostSize?.cols,
+      rows: hostSize?.rows,
+    });
+  }
+
+  // Return the stable color for a color key, assigning the next palette slot on
+  // first sight. Reused for a returning fingerprint (same key ⇒ same color).
+  #assignColor(key) {
+    const existing = this.#colorByKey.get(key);
+    if (existing) return existing;
+    const color = PALETTE[this.#colorByKey.size % PALETTE.length];
+    this.#colorByKey.set(key, color);
+    return color;
+  }
+
+  /** The palette color assigned to a participant, or null if unknown. */
+  colorOf(id) {
+    return this.participants.get(id)?.color ?? null;
+  }
+
+  setRoom(code) {
+    this.room = code;
+  }
+
+  /** Update the permission mode; returns true only if it actually changed. */
+  setMode(mode) {
+    if (mode === this.mode) return false;
+    this.mode = mode;
+    return true;
+  }
+
+  setPaused(paused) {
+    this.paused = !!paused;
+  }
+
+  get(id) {
+    return this.participants.get(id);
+  }
+
+  roleOf(id) {
+    return this.participants.get(id)?.role ?? null;
+  }
+
+  nameOf(id) {
+    return this.participants.get(id)?.name ?? null;
+  }
+
+  /** All participants including the host, in insertion order. */
+  list() {
+    return [...this.participants.values()];
+  }
+
+  /** Just the guests (everyone but the host). */
+  guests() {
+    return this.list().filter((p) => p.id !== HOST_ID);
+  }
+
+  /**
+   * Add a guest. A returning fingerprint (one that held a seat earlier this session)
+   * resumes the role it last held — spec §identity: role is restored on reconnect,
+   * and §failure-behavior: "reconnect with same key restores identity + role". A new
+   * or keyless guest gets the explicit role, else the room default. Returns the record.
+   */
+  addGuest(id, { name, fp, role } = {}) {
+    const restored = fp ? this.#seatRoles.get(fp) : undefined;
+    const p = {
+      id,
+      name: name ?? 'guest',
+      fp: fp ?? null,
+      role: restored ?? role ?? this.#defaultRole,
+      // Keyed guests color by fingerprint (restored on reconnect); keyless by id.
+      color: this.#assignColor(fp ?? id),
+      cols: undefined,
+      rows: undefined,
+    };
+    this.participants.set(id, p);
+    return p;
+  }
+
+  /**
+   * Drop a guest. The host can never be removed. A keyed guest's current role is
+   * remembered against its fingerprint so a same-key reconnect resumes the seat.
+   */
+  removeGuest(id) {
+    if (id === HOST_ID) return false;
+    const p = this.participants.get(id);
+    if (p?.fp) this.#seatRoles.set(p.fp, p.role);
+    return this.participants.delete(id);
+  }
+
+  /**
+   * Set a guest's role. Refuses to touch the host, to promote anyone to host, or
+   * to set an unknown role (spec: host is fixed; /role targets prompter|viewer).
+   */
+  setRole(id, role) {
+    const p = this.participants.get(id);
+    if (!p || id === HOST_ID) return false;
+    if (!Object.prototype.hasOwnProperty.call(ROLE_RANK, role) || role === 'host') return false;
+    p.role = role;
+    return true;
+  }
+
+  /** Record a participant's terminal size (host or guest). */
+  setSize(id, cols, rows) {
+    const p = this.participants.get(id);
+    if (!p) return false;
+    p.cols = cols;
+    p.rows = rows;
+    return true;
+  }
+
+  /** True if this participant's terminal is below the 80×24 floor (they spectate). */
+  belowFloor(id) {
+    const p = this.participants.get(id);
+    if (!p) return false;
+    return (p.cols != null && p.cols < FLOOR_COLS) || (p.rows != null && p.rows < FLOOR_ROWS);
+  }
+
+  /**
+   * Guest ids eligible for the live mirror — at or above the 80×24 floor. Below-floor
+   * guests are excluded: they spectate on a "make your terminal bigger" hint instead
+   * of receiving a shared view sized for larger terminals (spec §renderer clamp).
+   */
+  mirrorTargets() {
+    return this.guests().filter((p) => !this.belowFloor(p.id)).map((p) => p.id);
+  }
+
+  /** Guest ids parked on the spectate hint (below the floor). */
+  spectators() {
+    return this.guests().filter((p) => this.belowFloor(p.id)).map((p) => p.id);
+  }
+
+  /**
+   * The shared view dimensions: the component-wise minimum over participants that
+   * meet the floor, then raised to the 80×24 floor. Below-floor participants are
+   * excluded (they spectate) and participants of unknown size do not constrain it.
+   * @returns {{cols:number, rows:number}}
+   */
+  clamp() {
+    let cols = Infinity;
+    let rows = Infinity;
+    for (const p of this.participants.values()) {
+      if (this.belowFloor(p.id)) continue;
+      if (p.cols != null) cols = Math.min(cols, p.cols);
+      if (p.rows != null) rows = Math.min(rows, p.rows);
+    }
+    if (!Number.isFinite(cols)) cols = FLOOR_COLS;
+    if (!Number.isFinite(rows)) rows = FLOOR_ROWS;
+    return { cols: Math.max(FLOOR_COLS, cols), rows: Math.max(FLOOR_ROWS, rows) };
+  }
+
+  /** Milliseconds since the session started (uses the injected clock). */
+  ageMs() {
+    return this.#now() - this.startedAt;
+  }
+}