chainlesschain 0.161.11 → 0.162.0

package/src/commands/pair.js

@@ -0,0 +1,291 @@
+/**
+ * `cc pair` — LAN pairing utilities. v0.1 ships only the `preflight`
+ * subcommand for Linux LAN-pairing diagnostics (#21 A.1 PR1).
+ *
+ * Future:
+ *   cc pair init             — headless mode pairing initiator (PR2)
+ *   cc pair accept --qr ...  — accept a scanned QR from CLI (PR2)
+ */
+
+import chalk from "chalk";
+import { Command } from "commander";
+import {
+  runPreflight,
+  firewallCommandTemplate,
+  detectFirewallTool,
+  STATUS,
+} from "../lib/lan-pairing-preflight.js";
+import {
+  addToken,
+  listTokens,
+  findToken,
+  revokeToken,
+  STATUS as TOKEN_STATUS,
+} from "../lib/lan-pairing-tokens.js";
+
+function statusBadge(s) {
+  switch (s) {
+    case STATUS.OK:
+      return chalk.green("✔ ok");
+    case STATUS.WARNING:
+      return chalk.yellow("⚠ warn");
+    case STATUS.BLOCKER:
+      return chalk.red("✖ blocker");
+    case STATUS.SKIP:
+      return chalk.gray("· skip");
+    default:
+      return s;
+  }
+}
+
+function printHumanReadable(report, showFirewall) {
+  console.log(chalk.bold("\n  cc pair preflight\n"));
+  for (const c of report.checks) {
+    console.log(
+      `  ${statusBadge(c.status).padEnd(20)} ${chalk.bold(c.name.padEnd(22))} ${c.detail}`,
+    );
+  }
+  console.log();
+  console.log(
+    chalk.bold(
+      `  summary: ${chalk.green(report.summary.ok + " ok")}, ` +
+        `${chalk.yellow(report.summary.warnings + " warning")}, ` +
+        `${chalk.red(report.summary.blockers + " blocker")}`,
+    ),
+  );
+
+  // Show firewall commands when there's a blocker on multicast_bind, or
+  // when --show-firewall is set.
+  const multicastBlocked = report.checks.some(
+    (c) => c.name === "multicast_bind" && c.status === STATUS.BLOCKER,
+  );
+  if (showFirewall || multicastBlocked) {
+    const tool = detectFirewallTool();
+    const tpl = firewallCommandTemplate(tool);
+    if (tpl) {
+      console.log();
+      console.log(chalk.bold("  Firewall fix (detected tool: " + tool + "):"));
+      console.log();
+      console.log(
+        tpl
+          .split("\n")
+          .map((l) => "    " + l)
+          .join("\n"),
+      );
+    }
+  }
+  console.log();
+}
+
+function tokenStatusBadge(s) {
+  switch (s) {
+    case TOKEN_STATUS.PENDING:
+      return chalk.cyan("pending");
+    case TOKEN_STATUS.CONSUMED:
+      return chalk.green("consumed");
+    case TOKEN_STATUS.REVOKED:
+      return chalk.gray("revoked");
+    case TOKEN_STATUS.EXPIRED:
+      return chalk.yellow("expired");
+    default:
+      return s;
+  }
+}
+
+function relTime(ms) {
+  const diff = ms - Date.now();
+  const absMin = Math.abs(diff) / 60_000;
+  if (absMin < 60) {
+    return diff > 0
+      ? `${Math.round(absMin)} min from now`
+      : `${Math.round(absMin)} min ago`;
+  }
+  const absH = absMin / 60;
+  if (absH < 24) {
+    return diff > 0
+      ? `${Math.round(absH)}h from now`
+      : `${Math.round(absH)}h ago`;
+  }
+  return diff > 0
+    ? `${Math.round(absH / 24)}d from now`
+    : `${Math.round(absH / 24)}d ago`;
+}
+
+export function registerPairCommand(program) {
+  const pair = program
+    .command("pair")
+    .description(
+      "LAN pairing utilities (preflight diagnostics + pairing token issuance)",
+    );
+
+  pair
+    .command("preflight")
+    .description(
+      "Diagnose Linux LAN pairing — checks multicast bind, port 5353 holders, firewall hints (#21 A.1)",
+    )
+    .option("--json", "Machine-readable JSON output")
+    .option(
+      "--show-firewall",
+      "Always print firewall fix commands (default: only on blocker)",
+    )
+    .option(
+      "--multicast-bind-timeout-ms <ms>",
+      "Timeout for multicast bind probe",
+      (v) => parseInt(v, 10),
+    )
+    .action(async (options) => {
+      const report = await runPreflight({
+        multicastBindTimeoutMs: options.multicastBindTimeoutMs,
+      });
+
+      if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+        process.exitCode = report.exitCode;
+        return;
+      }
+
+      printHumanReadable(report, options.showFirewall);
+      process.exitCode = report.exitCode;
+    });
+
+  // ─── pair token (PR2) ─────────────────────────────────────────
+
+  const token = pair
+    .command("token")
+    .description(
+      "Manage pairing tokens (issue/list/show/revoke). Tokens are compatible with desktop device-pairing-handler QR shape.",
+    );
+
+  token
+    .command("generate")
+    .description("Issue a new 6-digit pairing token for a given DID")
+    .requiredOption("--did <did>", "PC DID (the token will pair this DID)")
+    .option("--name <name>", "Friendly device name (default: hostname)")
+    .option(
+      "--device-id <id>",
+      "Override deviceId (default: cli-<hostname>-<ts>)",
+    )
+    .option("--json", "Machine-readable JSON output (full qrData + metadata)")
+    .action((options) => {
+      const deviceInfo = (() => {
+        const out = {};
+        if (options.name) out.name = options.name;
+        if (options.deviceId) out.deviceId = options.deviceId;
+        return Object.keys(out).length ? out : undefined;
+      })();
+      const t = addToken({ did: options.did, deviceInfo });
+      if (options.json) {
+        console.log(JSON.stringify(t, null, 2));
+        return;
+      }
+      console.log();
+      console.log(chalk.bold("  ✓ Pairing token issued\n"));
+      console.log("  code:       " + chalk.bold.cyan(t.code));
+      console.log("  did:        " + t.qrData.did);
+      console.log("  device:     " + (t.qrData.deviceInfo?.name || "(none)"));
+      console.log("  expires:    " + relTime(t.expiresAtMs));
+      console.log();
+      console.log(
+        chalk.gray("  QR data (paste into mobile scanner / Electron handler):"),
+      );
+      console.log();
+      console.log("    " + JSON.stringify(t.qrData));
+      console.log();
+    });
+
+  token
+    .command("list")
+    .description("List pairing tokens")
+    .option(
+      "--status <s>",
+      "Filter by status (pending/consumed/revoked/expired)",
+    )
+    .option("--did <did>", "Filter by DID")
+    .option("--json", "Machine-readable JSON output")
+    .action((options) => {
+      const tokens = listTokens({ status: options.status, did: options.did });
+      if (options.json) {
+        console.log(JSON.stringify({ tokens }, null, 2));
+        return;
+      }
+      if (tokens.length === 0) {
+        console.log(chalk.gray("\n  No pairing tokens.\n"));
+        return;
+      }
+      console.log();
+      console.log(chalk.bold("  Pairing tokens:\n"));
+      console.log(
+        "  " +
+          chalk.gray("code").padEnd(10) +
+          chalk.gray("status").padEnd(14) +
+          chalk.gray("did").padEnd(30) +
+          chalk.gray("expires"),
+      );
+      for (const t of tokens) {
+        console.log(
+          "  " +
+            chalk.bold(t.code).padEnd(20) +
+            tokenStatusBadge(t.status).padEnd(20) +
+            String(t.qrData?.did || "?")
+              .slice(0, 28)
+              .padEnd(30) +
+            relTime(t.expiresAtMs),
+        );
+      }
+      console.log();
+    });
+
+  token
+    .command("show <code>")
+    .description("Show a single pairing token by code")
+    .option("--json", "Machine-readable JSON output")
+    .action((code, options) => {
+      const t = findToken(code);
+      if (!t) {
+        console.error(chalk.red(`✖ token not found: ${code}`));
+        process.exitCode = 2;
+        return;
+      }
+      if (options.json) {
+        console.log(JSON.stringify(t, null, 2));
+        return;
+      }
+      console.log();
+      console.log(chalk.bold(`  Token ${chalk.cyan(t.code)}\n`));
+      console.log("  status:     " + tokenStatusBadge(t.status));
+      console.log("  did:        " + t.qrData.did);
+      console.log(
+        "  device:     " +
+          (t.qrData.deviceInfo?.name || "(none)") +
+          " (" +
+          (t.qrData.deviceInfo?.platform || "?") +
+          ")",
+      );
+      console.log("  created:    " + new Date(t.createdAtMs).toISOString());
+      console.log("  expires:    " + new Date(t.expiresAtMs).toISOString());
+      if (t.consumedAtMs)
+        console.log("  consumed:   " + new Date(t.consumedAtMs).toISOString());
+      if (t.revokedAtMs)
+        console.log("  revoked:    " + new Date(t.revokedAtMs).toISOString());
+      console.log();
+    });
+
+  token
+    .command("revoke <code>")
+    .description("Revoke a pending pairing token")
+    .option("--json", "Machine-readable JSON output")
+    .action((code, options) => {
+      const r = revokeToken(code);
+      if (options.json) {
+        console.log(JSON.stringify(r, null, 2));
+        if (!r.revoked) process.exitCode = 2;
+        return;
+      }
+      if (r.revoked) {
+        console.log(chalk.green(`\n  ✓ Token ${code} revoked.\n`));
+      } else {
+        console.error(chalk.red(`\n  ✖ Cannot revoke: ${r.reason}\n`));
+        process.exitCode = 2;
+      }
+    });
+}

package/src/gateways/terminal/PtyManager.js

@@ -0,0 +1,248 @@
+/**
+ * PtyManager — ESM mirror of `desktop-app-vue/src/main/terminal/PtyManager.js`.
+ *
+ * Keep both copies in sync. The desktop copy targets Electron's CJS main
+ * process; this one targets `cc ui` (Node ESM) so `cc ui` users also get
+ * remote-terminal support via the same WS protocol.
+ *
+ * Design notes — see docs/design/Android_Remote_Terminal_Plan_A.md §4:
+ *   - node-pty loaded lazily so the module loads without the native
+ *     binding installed (tests, headless CI, machines without it).
+ *   - Per-session RingBuffer (256 KiB default, memory-only — no disk
+ *     persistence: terminal stdout often contains secrets).
+ *   - EventEmitter fans out `stdout` / `exit` so handlers translate to
+ *     WS envelopes without coupling.
+ *   - Idle kill default 24h, resets on stdin OR stdout activity.
+ *   - Shell whitelist enforced at create() — unknown shell → throws
+ *     `shell_not_allowed`.
+ */
+
+import EventEmitter from "events";
+import { randomUUID } from "crypto";
+import { createRequire } from "module";
+import { RingBuffer } from "./RingBuffer.js";
+
+const require = createRequire(import.meta.url);
+
+export const DEFAULT_CONFIG = Object.freeze({
+  shellWhitelist: ["pwsh", "cmd", "bash", "wsl"],
+  defaultShell: process.platform === "win32" ? "pwsh" : "bash",
+  defaultCwd: null,
+  maxConcurrentSessions: 8,
+  ringBufferBytes: 256 * 1024,
+  idleKillMs: 24 * 60 * 60 * 1000,
+});
+
+function resolveShellCmd(shell) {
+  if (process.platform === "win32") {
+    if (shell === "cmd") return process.env.ComSpec || "cmd.exe";
+    if (shell === "pwsh") return "pwsh.exe";
+    if (shell === "wsl") return "wsl.exe";
+    if (shell === "bash") return "bash.exe";
+  }
+  return shell;
+}
+
+class PtySession {
+  constructor({ id, shell, cwd, cols, rows, proc, createdAt, ringBuffer }) {
+    this.id = id;
+    this.shell = shell;
+    this.cwd = cwd;
+    this.cols = cols;
+    this.rows = rows;
+    this.proc = proc;
+    this.createdAt = createdAt;
+    this.ringBuffer = ringBuffer;
+    this.alive = true;
+    this.exitCode = null;
+    this.signal = null;
+    this.lastActivityAt = createdAt;
+  }
+}
+
+export class PtyManager extends EventEmitter {
+  constructor(opts = {}) {
+    super();
+    this.config = { ...DEFAULT_CONFIG, ...(opts.config || {}) };
+    this._deps = {
+      loadNodePty: opts._deps?.loadNodePty || (() => require("node-pty")),
+      now: opts._deps?.now || (() => Date.now()),
+    };
+    this._sessions = new Map();
+    this._idleTimer = null;
+    this._stopped = false;
+  }
+
+  create(req = {}) {
+    if (this._stopped) throw new Error("pty_manager_stopped");
+    if (this._sessions.size >= this.config.maxConcurrentSessions) {
+      throw new Error("max_concurrent_sessions_exceeded");
+    }
+    const shell = req.shell || this.config.defaultShell;
+    if (!this.config.shellWhitelist.includes(shell)) {
+      throw new Error("shell_not_allowed");
+    }
+
+    let pty;
+    try {
+      pty = this._deps.loadNodePty();
+    } catch {
+      const err = new Error("pty_native_unavailable");
+      err.cause = "node-pty failed to load (native binding missing)";
+      throw err;
+    }
+
+    const cwd = req.cwd || this.config.defaultCwd || process.cwd();
+    const cols = Number.isFinite(req.cols) ? req.cols : 80;
+    const rows = Number.isFinite(req.rows) ? req.rows : 24;
+    const cmd = resolveShellCmd(shell);
+
+    const proc = pty.spawn(cmd, [], {
+      name: "xterm-256color",
+      cols,
+      rows,
+      cwd,
+      env: { ...process.env, ...(req.env || {}) },
+    });
+
+    const sessionId = randomUUID();
+    const session = new PtySession({
+      id: sessionId,
+      shell,
+      cwd,
+      cols,
+      rows,
+      proc,
+      createdAt: this._deps.now(),
+      ringBuffer: new RingBuffer({ maxBytes: this.config.ringBufferBytes }),
+    });
+    this._sessions.set(sessionId, session);
+
+    proc.onData((data) => {
+      const buf = typeof data === "string" ? Buffer.from(data, "utf-8") : data;
+      const seq = session.ringBuffer.push(buf);
+      session.lastActivityAt = this._deps.now();
+      this.emit("stdout", { sessionId, data: buf, seq });
+    });
+
+    proc.onExit(({ exitCode, signal }) => {
+      session.alive = false;
+      session.exitCode = exitCode ?? null;
+      session.signal = signal ?? null;
+      this.emit("exit", {
+        sessionId,
+        exitCode: session.exitCode,
+        signal: session.signal,
+      });
+      setTimeout(() => {
+        if (this._sessions.get(sessionId) === session) {
+          this._sessions.delete(sessionId);
+        }
+      }, 60 * 1000).unref?.();
+    });
+
+    this._ensureIdleSweeper();
+
+    return {
+      sessionId,
+      pid: proc.pid,
+      shell,
+      createdAt: session.createdAt,
+    };
+  }
+
+  write(sessionId, data) {
+    const session = this._sessions.get(sessionId);
+    if (!session) throw new Error("session_not_found");
+    if (!session.alive) throw new Error("session_not_alive");
+    const str = Buffer.isBuffer(data) ? data.toString("utf-8") : data;
+    session.proc.write(str);
+    session.lastActivityAt = this._deps.now();
+  }
+
+  resize(sessionId, cols, rows) {
+    const session = this._sessions.get(sessionId);
+    if (!session) throw new Error("session_not_found");
+    if (!session.alive) throw new Error("session_not_alive");
+    if (!Number.isFinite(cols) || !Number.isFinite(rows)) {
+      throw new Error("invalid_dimensions");
+    }
+    session.proc.resize(cols, rows);
+    session.cols = cols;
+    session.rows = rows;
+  }
+
+  close(sessionId) {
+    const session = this._sessions.get(sessionId);
+    if (!session) throw new Error("session_not_found");
+    if (session.alive) {
+      try {
+        session.proc.kill();
+      } catch {
+        /* onExit will mark dead */
+      }
+    }
+  }
+
+  list() {
+    const out = [];
+    for (const s of this._sessions.values()) {
+      out.push({
+        id: s.id,
+        shell: s.shell,
+        cwd: s.cwd,
+        createdAt: s.createdAt,
+        alive: s.alive,
+        lastSeq: s.ringBuffer.lastSeq,
+      });
+    }
+    return out;
+  }
+
+  history(sessionId, fromSeq = 0) {
+    const session = this._sessions.get(sessionId);
+    if (!session) throw new Error("session_not_found");
+    return session.ringBuffer.since(fromSeq);
+  }
+
+  _ensureIdleSweeper() {
+    if (this._idleTimer) return;
+    this._idleTimer = setInterval(() => this._sweepIdle(), 60 * 60 * 1000);
+    this._idleTimer.unref?.();
+  }
+
+  _sweepIdle() {
+    const now = this._deps.now();
+    for (const session of this._sessions.values()) {
+      if (!session.alive) continue;
+      if (now - session.lastActivityAt > this.config.idleKillMs) {
+        try {
+          session.proc.kill();
+        } catch {
+          /* onExit will clean up */
+        }
+      }
+    }
+  }
+
+  shutdown() {
+    this._stopped = true;
+    if (this._idleTimer) {
+      clearInterval(this._idleTimer);
+      this._idleTimer = null;
+    }
+    for (const session of this._sessions.values()) {
+      if (session.alive) {
+        try {
+          session.proc.kill();
+        } catch {
+          /* best effort */
+        }
+      }
+    }
+  }
+
+  get _sessionCount() {
+    return this._sessions.size;
+  }
+}

package/src/gateways/terminal/RingBuffer.js

@@ -0,0 +1,61 @@
+/**
+ * RingBuffer — bounded byte-aware FIFO for PTY stdout chunks.
+ *
+ * ESM mirror of `desktop-app-vue/src/main/terminal/RingBuffer.js`. Both
+ * shells (Electron web-shell + `cc ui`) ship their own copy because the
+ * runtime module systems are incompatible (CJS vs ESM). Keep them in
+ * sync — future consolidation goes into a workspace package once the
+ * surface stabilises.
+ */
+
+export class RingBuffer {
+  constructor(opts = {}) {
+    const maxBytes = opts.maxBytes ?? 256 * 1024;
+    if (typeof maxBytes !== "number" || maxBytes <= 0) {
+      throw new TypeError("RingBuffer: maxBytes must be a positive number");
+    }
+    this.maxBytes = maxBytes;
+    this._entries = [];
+    this._totalBytes = 0;
+    this._lastSeq = 0;
+    this._firstRetainedSeq = 1;
+  }
+
+  push(data) {
+    const buf = Buffer.isBuffer(data)
+      ? data
+      : typeof data === "string"
+        ? Buffer.from(data, "utf-8")
+        : Buffer.from(data);
+    this._lastSeq += 1;
+    const seq = this._lastSeq;
+    this._entries.push({ seq, data: buf });
+    this._totalBytes += buf.byteLength;
+    this._evictUntilUnderCap();
+    return seq;
+  }
+
+  _evictUntilUnderCap() {
+    while (this._totalBytes > this.maxBytes && this._entries.length > 0) {
+      const evicted = this._entries.shift();
+      this._totalBytes -= evicted.data.byteLength;
+      this._firstRetainedSeq = evicted.seq + 1;
+    }
+  }
+
+  since(fromSeq = 0) {
+    const truncated = fromSeq > 0 && fromSeq < this._firstRetainedSeq;
+    const chunks = this._entries.filter((e) => e.seq >= fromSeq);
+    return { chunks, truncated };
+  }
+
+  get lastSeq() {
+    return this._lastSeq;
+  }
+  get totalBytes() {
+    return this._totalBytes;
+  }
+  get size() {
+    return this._entries.length;
+  }
+}