@claudecollab/cli 0.1.3 → 0.2.0

package/packages/cli/src/relay-client.js

@@ -16,7 +16,7 @@
 
 import ssh2 from 'ssh2';
 import { createHash } from 'node:crypto';
-import { TYPES, encode, validate, Decoder } from '../../shared/protocol.js';
+import { TYPES, encode, validate, Decoder, PROTOCOL_V } from '../../shared/protocol.js';
 
 const { Client, utils } = ssh2;
 
@@ -70,6 +70,8 @@ export function openingMove(heldRoom) {
  * @param {string} [opts.roomPass]           optional join password for the room this host
  *                                            creates — the relay challenges every guest
  *                                            with it before their knock is delivered
+ * @param {number} [opts.cap]                 requested max guests for this room; rides HELLO
+ *                                            as `cap` and the relay clamps it to [1, relayCap]
  * @param {(fp:string)=>boolean} [opts.verifyHostKey]  called with the relay's SHA256:…
  *                                            key fingerprint during the handshake; return
  *                                            false to abort (impersonation defense).
@@ -84,7 +86,7 @@ export function openingMove(heldRoom) {
  * }}
  */
 export function connectRelay(opts = {}) {
-  const { url, keepaliveInterval = 20000, secret, roomPass, verifyHostKey } = opts;
+  const { url, keepaliveInterval = 20000, secret, roomPass, cap, verifyHostKey } = opts;
   const { host, port } = parseRelayUrl(url);
   // A stable key lets the host reclaim its room after a drop; if the caller has
   // none we still connect (relay rejects `none` auth) with a throwaway key —
@@ -243,7 +245,15 @@ export function connectRelay(opts = {}) {
     onClose: on(sets.close), // ()                         the control channel closed
     onError: on(sets.error), // (err)                      ssh transport error
 
-    hello: () => send({ t: TYPES.HELLO, want: 'room', ...(secret ? { secret } : {}), ...(roomPass ? { pass: roomPass } : {}) }),
+    hello: () =>
+      send({
+        t: TYPES.HELLO,
+        want: 'room',
+        v: PROTOCOL_V, // announce our wire version; the relay refuses a newer one
+        ...(Number.isFinite(cap) ? { cap } : {}), // requested room size (relay clamps)
+        ...(secret ? { secret } : {}),
+        ...(roomPass ? { pass: roomPass } : {}),
+      }),
     reclaim: (code) => send({ t: TYPES.RECLAIM, code }),
     admit: (id) => send({ t: TYPES.ADMIT, id }),
     deny: (id) => send({ t: TYPES.DENY, id }),

package/packages/cli/src/room-file.js

@@ -0,0 +1,22 @@
+// The room file — how the Claude INSIDE the session learns its own invite link
+// (env CLAUDE_SHARE_ROOM_FILE names it). Whitelist, not caller discipline: the
+// host URL carries the seat token and must never reach the child-readable file.
+import fs from 'node:fs';
+const FIELDS = ['room', 'inviteUrl', 'webUrl'];
+export function writeRoomFile(file, info = {}) {
+  const out = {};
+  for (const k of FIELDS) if (typeof info[k] === 'string' && info[k]) out[k] = info[k];
+  try {
+    fs.writeFileSync(file, JSON.stringify(out) + '\n', { mode: 0o600 });
+    return true;
+  } catch {
+    return false; // a tmpfile problem must never take the session down
+  }
+}
+export function clearRoomFile(file) {
+  try {
+    fs.unlinkSync(file);
+  } catch {
+    /* already gone / never written */
+  }
+}

package/packages/cli/src/setup-actions.js

@@ -0,0 +1,163 @@
+// The first-run side effects, split out from the bin so they're execFile-injectable
+// and unit-testable without a real HOME or a real `claude` on PATH.
+//
+//   • installPlugin      — `claude plugin marketplace add` + `install` (best-effort)
+//   • installShimAction  — write the `claude` shim + rc edit (see shim.js)
+//   • connectorInstructions — honest per-connector guidance (see the docs note below)
+//   • runActions/runSetup — the orchestrated first-run: screen → actions → marker
+//   • undoSetup          — reverse the shim + best-effort plugin uninstall
+//   • shouldRunSetup + marker helpers — the trigger gate
+//
+// CONNECTOR MECHANICS (verified against code.claude.com/docs/en/mcp, 2026-07-14):
+// `claude mcp add --transport http <name> <url>` is the documented non-interactive
+// add, but it needs a KNOWN server URL, and the docs publish NO official server URLs
+// for the user-facing Slack / Gmail / Discord connectors — those are claude.ai
+// connectors, added in the browser at claude.ai/customize/connectors, after which they
+// appear in Claude Code automatically. There is no documented CLI one-liner for them,
+// so we print the exact instruction instead of inventing a server URL (plan's graceful
+// degradation). Even remote servers added via the CLI still need interactive OAuth.
+
+import { execFile as nodeExecFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { installShim, removeShim } from './shim.js';
+import { runFirstRun } from './first-run.js';
+
+const pexec = promisify(nodeExecFile);
+const CONNECTOR_LABELS = { slack: 'Slack', gmail: 'Gmail', discord: 'Discord' };
+
+/** The shown-once marker: `<home>/.claude-share/setup-done`. Brand stays out of paths. */
+export function markerPath(home = os.homedir()) {
+  return path.join(home, '.claude-share', 'setup-done');
+}
+
+/** True once the first-run screen has completed at least once. */
+export function setupDone(home = os.homedir()) {
+  return fs.existsSync(markerPath(home));
+}
+
+/** Record that setup ran (best-effort; a write failure just means we may re-show it). */
+export function writeMarker(home = os.homedir()) {
+  const p = markerPath(home);
+  try {
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, new Date().toISOString() + '\n');
+  } catch {
+    /* home not writable — the screen may show again next run, which is harmless */
+  }
+}
+
+/**
+ * The trigger gate. Show the first-run screen iff we're interactive on both ends, no
+ * skip env, no --yes, and the marker isn't set. Pure — so it's unit-tested directly.
+ */
+export function shouldRunSetup({ stdinTTY, stdoutTTY, home = os.homedir(), skipEnv, yes } = {}) {
+  return !!stdinTTY && !!stdoutTTY && skipEnv !== '1' && !yes && !setupDone(home);
+}
+
+/**
+ * Install the /collab plugin (the required core). Best-effort — a private repo or an
+ * offline machine fails here, which is EXPECTED pre-launch, so the failure copy says so.
+ * @returns {Promise<string>} one honest report line
+ */
+export async function installPlugin({ execFile = pexec } = {}) {
+  try {
+    await execFile('claude', ['plugin', 'marketplace', 'add', 'ir272/claudecollab'], { timeout: 30000 });
+    await execFile('claude', ['plugin', 'install', 'collab@claudecollab'], { timeout: 30000 });
+    return '✓ /collab is installed — type /collab in Claude Code when you want company';
+  } catch {
+    return "couldn't install the /collab plugin (offline or repo not public yet) — rerun anytime: collab setup";
+  }
+}
+
+/**
+ * Write the `claude` shim + rc edit. Best-effort — a read-only home fails here.
+ * @returns {string} one honest report line
+ */
+export function installShimAction({ home = os.homedir(), rcFiles, installShimFn = installShim } = {}) {
+  try {
+    installShimFn({ home, rcFiles });
+    return '✓ `claude` is now shareable (new terminals; or run: rehash)';
+  } catch {
+    return "couldn't shim the `claude` command — undo any partial changes with: collab setup --undo";
+  }
+}
+
+/**
+ * One honest instruction line per checked connector. No CLI add exists for the hosted
+ * connectors (see the docs note at the top), so we point the user at claude.ai — never
+ * a fabricated server URL.
+ * @param {string[]} connectors  checked connector keys
+ * @returns {string[]}
+ */
+export function connectorInstructions(connectors = []) {
+  return connectors.map((key) => {
+    const label = CONNECTOR_LABELS[key] ?? key;
+    return `• ${label}: add it at claude.ai/customize/connectors — it then shows up in Claude Code automatically (check /mcp).`;
+  });
+}
+
+/**
+ * Run all first-run side effects and report each on its own line via `out`. Each is
+ * best-effort and reports honestly; this never throws.
+ */
+export async function runActions({ connectors = [], home = os.homedir(), rcFiles, execFile, installShimFn, out = () => {} } = {}) {
+  out('');
+  out(await installPlugin({ execFile }));
+  out(installShimAction({ home, rcFiles, installShimFn }));
+  const connLines = connectorInstructions(connectors);
+  if (connLines.length) {
+    out('');
+    out('link delivery — turn on the connectors you picked (they live in your claude.ai account):');
+    for (const l of connLines) out(l);
+  }
+}
+
+/**
+ * The orchestrated first run: render the screen, run the actions, write the marker.
+ * The marker is written AFTER the screen even if an action failed (failures print
+ * their own retry line) so the screen never nags on every subsequent run.
+ */
+export async function runSetup({ input, output, home = os.homedir(), rcFiles, execFile, installShimFn, connectors } = {}) {
+  const picked = await runFirstRun({ input, output, connectors });
+  await runActions({
+    connectors: picked.connectors,
+    home,
+    rcFiles,
+    execFile,
+    installShimFn,
+    out: (s) => output.write(s + '\r\n'),
+  });
+  writeMarker(home);
+  return picked;
+}
+
+/**
+ * Reverse setup: remove the shim + rc edit, best-effort uninstall the plugin. The
+ * marker is RETAINED — setup stays "done", so a later plain `collab` won't re-prompt.
+ */
+export async function undoSetup({ home = os.homedir(), rcFiles, execFile = pexec, removeShimFn = removeShim, out = () => {} } = {}) {
+  removeShimFn({ home, rcFiles });
+  out('✓ removed the `claude` shim (restart your terminal, or run: rehash)');
+  try {
+    await execFile('claude', ['plugin', 'uninstall', 'collab@claudecollab'], { timeout: 30000 });
+    out('✓ uninstalled the /collab plugin');
+  } catch {
+    out("left the /collab plugin in place (couldn't uninstall it — remove it with /plugin inside Claude Code)");
+  }
+}
+
+/**
+ * The `collab setup [--undo]` bin entry point. Re-runs the screen + actions ignoring
+ * the marker, or reverses everything with --undo. Owns its own exit.
+ */
+export async function setupMain(args = []) {
+  if (args.includes('--undo')) {
+    await undoSetup({ out: (s) => process.stdout.write(s + '\n') });
+  } else {
+    await runSetup({ input: process.stdin, output: process.stdout });
+  }
+  process.exit(0);
+}

package/packages/cli/src/shim.js

@@ -0,0 +1,125 @@
+// The `claude` shim — the mechanism that makes `claude` itself go multiplayer.
+//
+// A tiny `claude` script in <home>/.claude-share/bin execs `collab "$@"`; a
+// marker-delimited line in the user's rc prepends that dir to PATH, so a fresh
+// terminal's `claude` IS collab wrapping the real claude. The recursion guard lives
+// in claude-share.js: when collab spawns its child `claude`, it strips THIS dir from
+// the child's PATH (stripShimDir), so the wrapped command resolves to the real
+// binary, never back to the shim. Spike-proven (2026-07-14): no recursion at depth 3.
+//
+// Everything here is pure/injectable — install/undo take an explicit `home` and
+// `rcFiles`, so tests run entirely under a tmp HOME and never touch the real one.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const MARK_START = '# >>> claude-share shim >>>';
+const MARK_END = '# <<< claude-share shim <<<';
+// The one PATH line the block manages. $HOME (not the expanded path) so the rc line
+// stays portable across machines/home dirs.
+const PATH_LINE = 'export PATH="$HOME/.claude-share/bin:$PATH"';
+// Default rc candidates (macOS/Linux stance — no Windows rc handling by design).
+const RC_CANDIDATES = ['.zshrc', '.bashrc'];
+
+/** The dir the shim script lives in: `<home>/.claude-share/bin`. */
+export function shimDir(home = os.homedir()) {
+  return path.join(home, '.claude-share', 'bin');
+}
+
+/** The full managed block, markers + the PATH line, each on its own line. */
+function block() {
+  return `${MARK_START}\n${PATH_LINE}\n${MARK_END}\n`;
+}
+
+// Which rc files to write to. An explicit list wins (tests, power users). Otherwise
+// every existing default candidate; if NONE exists, create a .zshrc.
+function resolveRcFiles(home, rcFiles) {
+  if (Array.isArray(rcFiles)) return rcFiles;
+  const existing = RC_CANDIDATES.map((n) => path.join(home, n)).filter((p) => fs.existsSync(p));
+  return existing.length ? existing : [path.join(home, '.zshrc')];
+}
+
+/**
+ * Install the shim: write the exec script (0755) and append the managed PATH block
+ * to each rc (idempotent — a present marker skips it). Returns which rc files carry
+ * the block.
+ * @returns {{ installed: true, rcFiles: string[] }}
+ */
+export function installShim({ home = os.homedir(), rcFiles } = {}) {
+  const dir = shimDir(home);
+  fs.mkdirSync(dir, { recursive: true });
+  const script = path.join(dir, 'claude');
+  fs.writeFileSync(script, '#!/bin/sh\nexec collab "$@"\n', { mode: 0o755 });
+  fs.chmodSync(script, 0o755); // writeFileSync doesn't re-chmod an existing file
+
+  const targets = resolveRcFiles(home, rcFiles);
+  for (const rc of targets) {
+    let content = '';
+    try {
+      content = fs.readFileSync(rc, 'utf8');
+    } catch {
+      /* rc doesn't exist yet — we create it below */
+    }
+    if (content.includes(MARK_START)) continue; // idempotent: block already present
+    // Keep the block on its own line: separate from prior content that lacks a
+    // trailing newline. A normal rc (ends in \n) needs no separator, so removeShim
+    // restores it byte-for-byte.
+    const sep = content.length && !content.endsWith('\n') ? '\n' : '';
+    fs.appendFileSync(rc, sep + block());
+  }
+  return { installed: true, rcFiles: targets };
+}
+
+// Strip the managed block from rc text. Matches the whole block through its trailing
+// newline, so an rc that ended in \n before install is restored byte-identical.
+function stripBlock(content) {
+  const re = new RegExp(`${escapeRe(MARK_START)}\\n[\\s\\S]*?${escapeRe(MARK_END)}\\n?`);
+  return content.replace(re, '');
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Remove the shim: delete the exec script and strip the managed block from each rc.
+ * Idempotent — missing script/block is a no-op.
+ * @returns {{ removed: true }}
+ */
+export function removeShim({ home = os.homedir(), rcFiles } = {}) {
+  try {
+    fs.unlinkSync(path.join(shimDir(home), 'claude'));
+  } catch {
+    /* already gone */
+  }
+  const targets = resolveRcFiles(home, rcFiles);
+  for (const rc of targets) {
+    let content;
+    try {
+      content = fs.readFileSync(rc, 'utf8');
+    } catch {
+      continue; // no such rc — nothing to strip
+    }
+    const stripped = stripBlock(content);
+    if (stripped !== content) fs.writeFileSync(rc, stripped);
+  }
+  return { removed: true };
+}
+
+/**
+ * The recursion guard: return `pathStr` with the shim dir entry removed. Matches the
+ * expanded dir AND the unexpanded $HOME/~ forms an rc might have introduced. A PATH
+ * without the shim dir is returned unchanged.
+ * @param {string} pathStr  a PATH-style, delimiter-joined string
+ * @param {string} home
+ */
+export function stripShimDir(pathStr, home = os.homedir()) {
+  if (!pathStr) return pathStr;
+  const dir = shimDir(home);
+  const variants = new Set([dir, '$HOME/.claude-share/bin', '${HOME}/.claude-share/bin', '~/.claude-share/bin']);
+  return pathStr
+    .split(path.delimiter)
+    .filter((entry) => !variants.has(entry))
+    .join(path.delimiter);
+}

package/packages/relay/bin/serve.js

@@ -55,6 +55,8 @@ const relay = await startRelay({
   hostName,
   maxRooms: Number(process.env.MAX_ROOMS || 50),
   roomSecret,
+  // Only enable behind Fly's proxy: `fly secrets set CLAUDE_SHARE_TRUST_PROXY=1`.
+  trustProxy: process.env.CLAUDE_SHARE_TRUST_PROXY === '1',
 });
 
 // The public-half fingerprint of our ssh identity. Safe to publish — hosts pin