chainlesschain 0.161.11 → 0.161.12

package/src/assets/web-panel/assets/xterm-DFuMZ0ql.css

@@ -0,0 +1 @@
+.xterm{cursor:text;position:relative;user-select:none;-ms-user-select:none;-webkit-user-select:none}.xterm.focus,.xterm:focus{outline:none}.xterm .xterm-helpers{position:absolute;top:0;z-index:5}.xterm .xterm-helper-textarea{padding:0;border:0;margin:0;position:absolute;opacity:0;left:-9999em;top:0;width:0;height:0;z-index:-5;white-space:nowrap;overflow:hidden;resize:none}.xterm .composition-view{background:#000;color:#fff;display:none;position:absolute;white-space:nowrap;z-index:1}.xterm .composition-view.active{display:block}.xterm .xterm-viewport{background-color:#000;overflow-y:scroll;cursor:default;position:absolute;inset:0}.xterm .xterm-screen{position:relative}.xterm .xterm-screen canvas{position:absolute;left:0;top:0}.xterm .xterm-scroll-area{visibility:hidden}.xterm-char-measure-element{display:inline-block;visibility:hidden;position:absolute;top:0;left:-9999em;line-height:normal}.xterm.enable-mouse-events{cursor:default}.xterm.xterm-cursor-pointer,.xterm .xterm-cursor-pointer{cursor:pointer}.xterm.column-select.focus{cursor:crosshair}.xterm .xterm-accessibility:not(.debug),.xterm .xterm-message{position:absolute;inset:0;z-index:10;color:transparent;pointer-events:none}.xterm .xterm-accessibility-tree:not(.debug) *::selection{color:transparent}.xterm .xterm-accessibility-tree{-webkit-user-select:text;user-select:text;white-space:pre}.xterm .live-region{position:absolute;left:-9999px;width:1px;height:1px;overflow:hidden}.xterm-dim{opacity:1!important}.xterm-underline-1{text-decoration:underline}.xterm-underline-2{text-decoration:double underline}.xterm-underline-3{text-decoration:wavy underline}.xterm-underline-4{text-decoration:dotted underline}.xterm-underline-5{text-decoration:dashed underline}.xterm-overline{text-decoration:overline}.xterm-overline.xterm-underline-1{text-decoration:overline underline}.xterm-overline.xterm-underline-2{text-decoration:overline double underline}.xterm-overline.xterm-underline-3{text-decoration:overline wavy underline}.xterm-overline.xterm-underline-4{text-decoration:overline dotted underline}.xterm-overline.xterm-underline-5{text-decoration:overline dashed underline}.xterm-strikethrough{text-decoration:line-through}.xterm-screen .xterm-decoration-container .xterm-decoration{z-index:6;position:absolute}.xterm-screen .xterm-decoration-container .xterm-decoration.xterm-decoration-top-layer{z-index:7}.xterm-decoration-overview-ruler{z-index:8;position:absolute;top:0;right:0;pointer-events:none}.xterm-decoration-top{z-index:2;position:relative}

package/src/assets/web-panel/assets/{zoom-DE1Teifl.js → zoom-B6Ipb64r.js}

@@ -1,4 +1,4 @@
-import{K as o}from"./index-BRWO_MUe.js";import{i as f}from"./motion-By5VpSMZ.js";const c=new o("antZoomIn",{"0%":{transform:"scale(0.2)",opacity:0},"100%":{transform:"scale(1)",opacity:1}}),y=new o("antZoomOut",{"0%":{transform:"scale(1)"},"100%":{transform:"scale(0.2)",opacity:0}}),a=new o("antZoomBigIn",{"0%":{transform:"scale(0.8)",opacity:0},"100%":{transform:"scale(1)",opacity:1}}),s=new o("antZoomBigOut",{"0%":{transform:"scale(1)"},"100%":{transform:"scale(0.8)",opacity:0}}),g=new o("antZoomUpIn",{"0%":{transform:"scale(0.8)",transformOrigin:"50% 0%",opacity:0},"100%":{transform:"scale(1)",transformOrigin:"50% 0%"}}),O=new o("antZoomUpOut",{"0%":{transform:"scale(1)",transformOrigin:"50% 0%"},"100%":{transform:"scale(0.8)",transformOrigin:"50% 0%",opacity:0}}),l=new o("antZoomLeftIn",{"0%":{transform:"scale(0.8)",transformOrigin:"0% 50%",opacity:0},"100%":{transform:"scale(1)",transformOrigin:"0% 50%"}}),u=new o("antZoomLeftOut",{"0%":{transform:"scale(1)",transformOrigin:"0% 50%"},"100%":{transform:"scale(0.8)",transformOrigin:"0% 50%",opacity:0}}),p=new o("antZoomRightIn",{"0%":{transform:"scale(0.8)",transformOrigin:"100% 50%",opacity:0},"100%":{transform:"scale(1)",transformOrigin:"100% 50%"}}),z=new o("antZoomRightOut",{"0%":{transform:"scale(1)",transformOrigin:"100% 50%"},"100%":{transform:"scale(0.8)",transformOrigin:"100% 50%",opacity:0}}),K=new o("antZoomDownIn",{"0%":{transform:"scale(0.8)",transformOrigin:"50% 100%",opacity:0},"100%":{transform:"scale(1)",transformOrigin:"50% 100%"}}),w=new o("antZoomDownOut",{"0%":{transform:"scale(1)",transformOrigin:"50% 100%"},"100%":{transform:"scale(0.8)",transformOrigin:"50% 100%",opacity:0}}),I={zoom:{inKeyframes:c,outKeyframes:y},"zoom-big":{inKeyframes:a,outKeyframes:s},"zoom-big-fast":{inKeyframes:a,outKeyframes:s},"zoom-left":{inKeyframes:l,outKeyframes:u},"zoom-right":{inKeyframes:p,outKeyframes:z},"zoom-up":{inKeyframes:g,outKeyframes:O},"zoom-down":{inKeyframes:K,outKeyframes:w}},h=(n,r)=>{const{antCls:m}=n,t=`${m}-${r}`,{inKeyframes:i,outKeyframes:e}=I[r];return[f(t,i,e,r==="zoom-big-fast"?n.motionDurationFast:n.motionDurationMid),{[`
+import{K as o}from"./index-DPzT5L14.js";import{i as f}from"./motion-44iMBc1o.js";const c=new o("antZoomIn",{"0%":{transform:"scale(0.2)",opacity:0},"100%":{transform:"scale(1)",opacity:1}}),y=new o("antZoomOut",{"0%":{transform:"scale(1)"},"100%":{transform:"scale(0.2)",opacity:0}}),a=new o("antZoomBigIn",{"0%":{transform:"scale(0.8)",opacity:0},"100%":{transform:"scale(1)",opacity:1}}),s=new o("antZoomBigOut",{"0%":{transform:"scale(1)"},"100%":{transform:"scale(0.8)",opacity:0}}),g=new o("antZoomUpIn",{"0%":{transform:"scale(0.8)",transformOrigin:"50% 0%",opacity:0},"100%":{transform:"scale(1)",transformOrigin:"50% 0%"}}),O=new o("antZoomUpOut",{"0%":{transform:"scale(1)",transformOrigin:"50% 0%"},"100%":{transform:"scale(0.8)",transformOrigin:"50% 0%",opacity:0}}),l=new o("antZoomLeftIn",{"0%":{transform:"scale(0.8)",transformOrigin:"0% 50%",opacity:0},"100%":{transform:"scale(1)",transformOrigin:"0% 50%"}}),u=new o("antZoomLeftOut",{"0%":{transform:"scale(1)",transformOrigin:"0% 50%"},"100%":{transform:"scale(0.8)",transformOrigin:"0% 50%",opacity:0}}),p=new o("antZoomRightIn",{"0%":{transform:"scale(0.8)",transformOrigin:"100% 50%",opacity:0},"100%":{transform:"scale(1)",transformOrigin:"100% 50%"}}),z=new o("antZoomRightOut",{"0%":{transform:"scale(1)",transformOrigin:"100% 50%"},"100%":{transform:"scale(0.8)",transformOrigin:"100% 50%",opacity:0}}),K=new o("antZoomDownIn",{"0%":{transform:"scale(0.8)",transformOrigin:"50% 100%",opacity:0},"100%":{transform:"scale(1)",transformOrigin:"50% 100%"}}),w=new o("antZoomDownOut",{"0%":{transform:"scale(1)",transformOrigin:"50% 100%"},"100%":{transform:"scale(0.8)",transformOrigin:"50% 100%",opacity:0}}),I={zoom:{inKeyframes:c,outKeyframes:y},"zoom-big":{inKeyframes:a,outKeyframes:s},"zoom-big-fast":{inKeyframes:a,outKeyframes:s},"zoom-left":{inKeyframes:l,outKeyframes:u},"zoom-right":{inKeyframes:p,outKeyframes:z},"zoom-up":{inKeyframes:g,outKeyframes:O},"zoom-down":{inKeyframes:K,outKeyframes:w}},h=(n,r)=>{const{antCls:m}=n,t=`${m}-${r}`,{inKeyframes:i,outKeyframes:e}=I[r];return[f(t,i,e,r==="zoom-big-fast"?n.motionDurationFast:n.motionDurationMid),{[`
         ${t}-enter,
         ${t}-appear
       `]:{transform:"scale(0)",opacity:0,animationTimingFunction:n.motionEaseOutCirc,"&-prepare":{transform:"none"}},[`${t}-leave`]:{animationTimingFunction:n.motionEaseInOutCirc}}]};export{h as i,c as z};

package/src/assets/web-panel/index.html

@@ -8,9 +8,9 @@
     // Injected by web-ui-server.js at serve time
     window.__CC_CONFIG__ = __CC_CONFIG_PLACEHOLDER__;
   </script>
-  <script type="module" crossorigin src="./assets/index-BRWO_MUe.js"></script>
-  <link rel="modulepreload" crossorigin href="./assets/vendor-BVLz_z7V.js">
-  <link rel="modulepreload" crossorigin href="./assets/icons-Q99MnhG8.js">
+  <script type="module" crossorigin src="./assets/index-DPzT5L14.js"></script>
+  <link rel="modulepreload" crossorigin href="./assets/vendor-M5lGV-wr.js">
+  <link rel="modulepreload" crossorigin href="./assets/icons-NT6gy8Ee.js">
   <link rel="stylesheet" crossorigin href="./assets/index-CfX1DEtk.css">
 </head>
 <body>

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;
+  }
+}

package/src/gateways/terminal/terminal-handlers.js

@@ -0,0 +1,121 @@
+/**
+ * terminal-handlers — WS topic handlers for Plan A remote-terminal.
+ *
+ * ESM mirror of `desktop-app-vue/src/main/web-shell/handlers/terminal-handlers.js`.
+ * Keep both copies in sync (see the matching mirror docstring there).
+ */
+
+export const DEFAULT_DANGEROUS_PATTERNS = [
+  /\brm\s+-rf\b/i,
+  /\bformat\s+[a-z]:/i,
+  /\bshutdown\b/i,
+  /\bdel\s+\/[sq]/i,
+  /\bdiskpart\b/i,
+  /:\(\)\s*{\s*:\s*\|\s*:\s*&\s*}\s*;\s*:/,
+];
+
+export function bufferToBase64(buf) {
+  return Buffer.isBuffer(buf)
+    ? buf.toString("base64")
+    : Buffer.from(buf, "utf-8").toString("base64");
+}
+
+export function base64ToBuffer(s) {
+  if (typeof s !== "string") {
+    throw new Error("data_must_be_base64_string");
+  }
+  return Buffer.from(s, "base64");
+}
+
+export function createTerminalHandlers(options) {
+  const { ptyManager, broadcast } = options;
+  if (!ptyManager) throw new TypeError("ptyManager is required");
+  if (typeof broadcast !== "function") {
+    throw new TypeError("broadcast must be a function");
+  }
+  const dangerousPatterns =
+    options.dangerousPatterns || DEFAULT_DANGEROUS_PATTERNS;
+  const requireConfirmation =
+    options.requireConfirmation || (async () => false);
+  const verifyTrustedSource = options.verifyTrustedSource || (() => true);
+
+  function attachServerEvents() {
+    ptyManager.on("stdout", ({ sessionId, data, seq }) => {
+      broadcast({
+        type: "terminal.stdout",
+        payload: { sessionId, data: bufferToBase64(data), seq },
+      });
+    });
+    ptyManager.on("exit", ({ sessionId, exitCode, signal }) => {
+      broadcast({
+        type: "terminal.exit",
+        payload: { sessionId, exitCode, signal },
+      });
+    });
+  }
+
+  const handlers = {
+    "terminal.create": async (frame) => {
+      if (!verifyTrustedSource(frame)) return null;
+      const payload = frame?.payload || frame || {};
+      return ptyManager.create({
+        shell: payload.shell,
+        cwd: payload.cwd,
+        env: payload.env,
+        cols: payload.cols,
+        rows: payload.rows,
+      });
+    },
+
+    "terminal.list": async (frame) => {
+      if (!verifyTrustedSource(frame)) return null;
+      return { sessions: ptyManager.list() };
+    },
+
+    "terminal.stdin": async (frame) => {
+      if (!verifyTrustedSource(frame)) return null;
+      const { sessionId, data } = frame?.payload || frame || {};
+      if (!sessionId) throw new Error("session_id_required");
+      const buf = base64ToBuffer(data);
+      const text = buf.toString("utf-8");
+      if (dangerousPatterns.some((re) => re.test(text))) {
+        const ok = await requireConfirmation(text, sessionId);
+        if (!ok) throw new Error("dangerous_keyword_blocked");
+      }
+      ptyManager.write(sessionId, buf);
+      return { ok: true };
+    },
+
+    "terminal.resize": async (frame) => {
+      if (!verifyTrustedSource(frame)) return null;
+      const { sessionId, cols, rows } = frame?.payload || frame || {};
+      if (!sessionId) throw new Error("session_id_required");
+      ptyManager.resize(sessionId, cols, rows);
+      return { ok: true };
+    },
+
+    "terminal.close": async (frame) => {
+      if (!verifyTrustedSource(frame)) return null;
+      const { sessionId } = frame?.payload || frame || {};
+      if (!sessionId) throw new Error("session_id_required");
+      ptyManager.close(sessionId);
+      return { ok: true };
+    },
+
+    "terminal.history": async (frame) => {
+      if (!verifyTrustedSource(frame)) return null;
+      const { sessionId, fromSeq } = frame?.payload || frame || {};
+      if (!sessionId) throw new Error("session_id_required");
+      const { chunks, truncated } = ptyManager.history(sessionId, fromSeq || 0);
+      return {
+        chunks: chunks.map((c) => ({
+          seq: c.seq,
+          data: bufferToBase64(c.data),
+        })),
+        truncated,
+      };
+    },
+  };
+
+  return { handlers, attachServerEvents };
+}

package/src/gateways/ws/topic-handler-attachment.js

@@ -0,0 +1,211 @@
+/**
+ * topic-handler-attachment — wrap a `ChainlessChainWSServer` instance with
+ * custom topic handlers, mirroring the existing dispatcher.
+ *
+ * Extracted from `desktop-app-vue/src/main/web-shell/ws-cli-loader.js` so
+ * both consumers (desktop web-shell AND `cc ui`) get the same protocol
+ * features:
+ *
+ *   - id + auth gates (token-protected servers reject unauthenticated
+ *     custom-topic calls; native CLI dispatch is untouched)
+ *   - plain async handler → `{type:"<topic>.result", ok, result}`
+ *   - async generator handler → `{type:"<topic>.chunk", ok, chunk}` *N +
+ *     terminal `{type:"<topic>.result", ok, result}`
+ *   - `<topic>.cancel` frame → `gen.return("client_cancel")` for in-flight
+ *     streams (keyed by request id, not topic)
+ *   - `ws.on("close")` → unwind every stream the client owned
+ *
+ * Single call site contract:
+ *
+ *   const handle = attachTopicHandlers(server, {
+ *     handlers: { 'terminal.create': async (frame, ctx) => {...}, ... },
+ *   });
+ *   handle.register('extra.topic', fn);
+ *   handle.broadcast({type:'terminal.stdout', payload:{...}});
+ *
+ * Returns `{ register, broadcast, topicHandlers }`. The server's
+ * `_dispatcher` is mutated in place — calling this twice on the same
+ * server stacks wrappers (each falls through to the previous), which is
+ * fine but usually unnecessary.
+ */
+
+/**
+ * @typedef {(frame: any, ctx: { topic: string, id: string, server: any, ws: any, clientId: string }) => (Promise<any> | any | AsyncIterable<any>)} TopicHandler
+ */
+
+/**
+ * @param {any} server  ChainlessChainWSServer instance (post-start())
+ * @param {object} [opts]
+ * @param {Record<string, TopicHandler>} [opts.handlers]
+ * @returns {{
+ *   register: (topic: string, fn: TopicHandler) => void,
+ *   broadcast: (frame: any) => void,
+ *   topicHandlers: Map<string, TopicHandler>,
+ * }}
+ */
+export function attachTopicHandlers(server, opts = {}) {
+  /** @type {Map<string, TopicHandler>} */
+  const topicHandlers = new Map();
+  if (opts.handlers) {
+    for (const [topic, fn] of Object.entries(opts.handlers)) {
+      if (typeof fn !== "function") {
+        throw new TypeError(
+          `attachTopicHandlers: handler for "${topic}" must be a function`,
+        );
+      }
+      topicHandlers.set(topic, fn);
+    }
+  }
+
+  /** @type {Map<string, { gen: AsyncIterator<any>, clientId: string }>} */
+  const inFlightStreams = new Map();
+
+  async function unwindStream(id, reason) {
+    const entry = inFlightStreams.get(id);
+    if (!entry) return;
+    inFlightStreams.delete(id);
+    try {
+      if (typeof entry.gen.return === "function") {
+        await entry.gen.return(reason);
+      }
+    } catch {
+      // Generator throw on unwind is non-fatal.
+    }
+  }
+
+  const wsCloseHooked = new WeakSet();
+  function ensureWsCloseHook(ws, clientId) {
+    if (!ws || typeof ws.on !== "function") return;
+    if (wsCloseHooked.has(ws)) return;
+    wsCloseHooked.add(ws);
+    ws.on("close", () => {
+      for (const [id, entry] of inFlightStreams) {
+        if (entry.clientId === clientId) {
+          unwindStream(id, "ws_close").catch(() => {});
+        }
+      }
+    });
+  }
+
+  const originalDispatcher = server._dispatcher;
+  server._dispatcher = {
+    async dispatch(clientId, ws, message) {
+      const { id, type } = message || {};
+      ensureWsCloseHook(ws, clientId);
+
+      if (id && typeof type === "string" && type.endsWith(".cancel")) {
+        await unwindStream(id, "client_cancel");
+        return;
+      }
+
+      if (id && type && topicHandlers.has(type)) {
+        const client = server.clients.get(clientId);
+        if (server.token && (!client || !client.authenticated)) {
+          server._send(ws, {
+            id,
+            type: "error",
+            code: "AUTH_REQUIRED",
+            message: "Authentication required. Send an auth message first.",
+          });
+          return;
+        }
+
+        const handler = topicHandlers.get(type);
+        try {
+          const ret = handler(message, {
+            topic: type,
+            id,
+            server,
+            ws,
+            clientId,
+          });
+
+          if (ret && typeof ret[Symbol.asyncIterator] === "function") {
+            inFlightStreams.set(id, { gen: ret, clientId });
+            let finalReturn = null;
+            try {
+              for (;;) {
+                const step = await ret.next();
+                if (step.done) {
+                  finalReturn = step.value ?? null;
+                  break;
+                }
+                if (ws.readyState !== 1) {
+                  await unwindStream(id, "readyState_closed");
+                  return;
+                }
+                server._send(ws, {
+                  id,
+                  type: `${type}.chunk`,
+                  ok: true,
+                  chunk: step.value ?? null,
+                });
+              }
+              server._send(ws, {
+                id,
+                type: `${type}.result`,
+                ok: true,
+                result: finalReturn,
+              });
+            } catch (streamErr) {
+              server._send(ws, {
+                id,
+                type: `${type}.result`,
+                ok: false,
+                error:
+                  streamErr instanceof Error
+                    ? streamErr.message
+                    : String(streamErr),
+              });
+            } finally {
+              inFlightStreams.delete(id);
+            }
+            return;
+          }
+
+          const result = await ret;
+          server._send(ws, {
+            id,
+            type: `${type}.result`,
+            ok: true,
+            result: result ?? null,
+          });
+        } catch (err) {
+          server._send(ws, {
+            id,
+            type: `${type}.result`,
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+        return;
+      }
+
+      return originalDispatcher.dispatch(clientId, ws, message);
+    },
+  };
+
+  function register(topic, fn) {
+    if (typeof topic !== "string" || !topic) {
+      throw new TypeError(
+        "attachTopicHandlers: topic must be a non-empty string",
+      );
+    }
+    if (typeof fn !== "function") {
+      throw new TypeError("attachTopicHandlers: handler must be a function");
+    }
+    topicHandlers.set(topic, fn);
+  }
+
+  function broadcast(frame) {
+    if (!frame || typeof frame !== "object") return;
+    try {
+      server._broadcast(frame);
+    } catch {
+      // _send is readyState-guarded inside the server; the only path here
+      // would be an internal CLI ws-server bug. Don't crash the caller.
+    }
+  }
+
+  return { register, broadcast, topicHandlers };
+}