@particle-academy/fancy-term-host 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Particle Academy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+<p align="left"><img src="./art/fancy-ui.svg" alt="Fancy UI" height="28"></p>
+
+# @particle-academy/fancy-term-host
+
+**The headless Node terminal backend for [`@particle-academy/fancy-term`](https://www.npmjs.com/package/@particle-academy/fancy-term).**
+
+`fancy-term` is the browser-side React `<Terminal>` — it renders xterm.js and
+deliberately **never spawns a shell**. `fancy-term-host` is the other half: the
+Node process that **owns the PTYs** (via `node-pty`) and a **T1/T2/T3 persistence
+engine** — snapshot+replay, retained PTYs, and a detached pty-host — behind four
+small **injected ports**. It runs anywhere Node runs (Electron main, a Laravel
+queue worker, a plain server): OS-agnostic by construction, with **zero hard
+third-party dependencies** (`node-pty` is a peer the consumer builds).
+
+It can't live inside `fancy-term` or the other UI packages — `node-pty` is a
+native addon that would break their browser builds — so it's an independent
+sibling you install alongside.
+
+## Install
+
+```bash
+npm install @particle-academy/fancy-term-host node-pty
+```
+
+`node-pty` is a **peer dependency**: you own its native build (and, under
+Electron, the `asar-unpack` so its `.node` binary loads outside the archive).
+
+## Wire it up
+
+You provide four ports (see [`docs/ports.md`](./docs/ports.md)); the core does
+the rest. The minimal in-process (Tier 1/2) setup:
+
+```ts
+import {
+  configureInProcessBackend,
+  inProcessBackend,
+  createSnapshotStore,
+  type SettingsProvider,
+  type Encryptor,
+} from "@particle-academy/fancy-term-host";
+
+// 1. Settings (gates the cwd hook + T3). Defaults are sensible — track_cwd on.
+const settings: SettingsProvider = { get: (k) => undefined };
+
+// 2. A cipher for at-rest snapshots. A passthrough is fine to start with.
+const encryptor: Encryptor = {
+  isAvailable: () => false, // → snapshots stored as plaintext gzip
+  encrypt: (b) => b,
+  decrypt: (b) => b,
+};
+
+// 3. Snapshot store (T1) rooted under a writable dir (`<dir>/sessions/...`).
+const snapshots = createSnapshotStore({ baseDir: "/var/app/userData", encryptor });
+
+// 4. Configure + grab the backend.
+configureInProcessBackend({ settings, snapshots });
+const backend = inProcessBackend();
+
+// Spawn a shell and stream it to a fancy-term <Terminal> on the client.
+const { id, scrollback } = backend.create({ id: "t1", cols: 80, rows: 24 });
+backend.on("data", (tid, data) => sendToClient(tid, data)); // → <Terminal output>
+backend.on("exit", (tid) => closeOnClient(tid));
+
+// Client keystrokes (fancy-term `onData`) come back here:
+onClientData("t1", (d) => backend.write("t1", d));
+onClientResize("t1", (cols, rows) => backend.resize("t1", cols, rows));
+```
+
+The backend's `create` / `write` / `resize` / `kill` / `list` and its
+`data` / `exit` / `cwd` events are the whole surface the wire needs. Pair it
+with `fancy-term`'s controlled `output` buffer and `onData` and you have a live
+terminal that an agent can also inhabit (via the `registerTerminalBridge` in
+`@particle-academy/agent-integrations`).
+
+## Persistence tiers
+
+Switchable behind one `PtyBackend` interface (see [`docs/persistence.md`](./docs/persistence.md)):
+
+- **T1 — snapshot & replay.** Session state is serialized, (optionally)
+  encrypted, gzipped, and written to `<baseDir>/sessions/<id>.snap`. A cold
+  start replays it so a reopened terminal shows where it was.
+- **T2 — retained PTYs.** A PTY flagged `setRetained(true)` survives a window
+  detach (the live shell keeps running; scrollback replays on reattach) instead
+  of being killed.
+- **T3 — detached host.** PTYs live in a separate headless **pty-host** process
+  that survives a full quit of the app. The backend proxies calls over a named
+  pipe (Windows) / unix socket (POSIX); reopening reattaches to the still-running
+  shells.
+
+### Spawning the detached host (T3)
+
+The bundled host script is resolvable without knowing the dist layout:
+
+```ts
+import { spawn } from "node:child_process";
+import { ptyHostScriptPath } from "@particle-academy/fancy-term-host";
+
+const child = spawn(process.execPath, [ptyHostScriptPath(), userDataDir], {
+  detached: true,
+  stdio: "ignore",
+});
+child.unref();
+```
+
+Wrap that in a `HostSpawner` and pass it to `configureHostLifecycle(...)` to let
+the core connect-or-spawn-or-fall-back automatically. (`require.resolve(
+"@particle-academy/fancy-term-host/pty-host")` also resolves the script.)
+
+## cwd tracking (OSC-7)
+
+The host learns each terminal's working directory from **OSC-7** escape
+sequences the shell emits on every prompt, so a resumed shell can start where the
+old one left off. `fancy-term-host` injects the prompt hook for you, gated by the
+`track_cwd` setting (default **on**):
+
+| Shell | Mechanism | Status |
+|---|---|---|
+| **bash** | prepends an OSC-7 `printf` to `PROMPT_COMMAND` (env) | ✅ |
+| **zsh** | generated `ZDOTDIR` whose rc sources yours + adds a `precmd` | ✅ |
+| **fish** | generated `vendor_conf.d` via `XDG_DATA_DIRS` (`--on-event fish_prompt`) | ✅ |
+| **PowerShell** | dot-sourced profile shim wrapping your `prompt` (appended launch args) | ✅ |
+| **cmd.exe** | `PROMPT` with the `$E` escape | ⚠️ best-effort (only where the console honors VT in the prompt) |
+
+Every hook **overlays** your shell config — it never clobbers your prompt or rc.
+Any shell that can't be hooked degrades silently to the static `cwd`.
+
+## License
+
+MIT
+
+---
+
+## ⭐ Star Fancy UI
+
+If this package is useful to you, a quick ⭐ on the repo really helps us build a
+better kit. Thank you!

package/dist/chunk-2DQJKTG5.js

@@ -0,0 +1,127 @@
+import path from 'path';
+import os from 'os';
+import fs from 'fs';
+import crypto from 'crypto';
+
+// src/host-protocol.ts
+var PROTOCOL_VERSION = 1;
+var LENGTH_BYTES = 4;
+function encodeFrame(msg) {
+  const body = Buffer.from(JSON.stringify(msg), "utf8");
+  const header = Buffer.allocUnsafe(LENGTH_BYTES);
+  header.writeUInt32BE(body.length, 0);
+  return Buffer.concat([header, body]);
+}
+var _FrameDecoder = class _FrameDecoder {
+  constructor() {
+    this.buffer = Buffer.alloc(0);
+    /** True when the last push hit an oversized/desynced frame. The caller
+     *  should drop the connection — the stream can't be trusted to realign. */
+    this.desynced = false;
+  }
+  push(chunk) {
+    this.buffer = this.buffer.length ? Buffer.concat([this.buffer, chunk]) : chunk;
+    const out = [];
+    for (; ; ) {
+      if (this.buffer.length < LENGTH_BYTES) break;
+      const len = this.buffer.readUInt32BE(0);
+      if (len > _FrameDecoder.MAX_FRAME) {
+        this.desynced = true;
+        this.buffer = Buffer.alloc(0);
+        break;
+      }
+      if (this.buffer.length < LENGTH_BYTES + len) break;
+      const body = this.buffer.subarray(LENGTH_BYTES, LENGTH_BYTES + len);
+      this.buffer = this.buffer.subarray(LENGTH_BYTES + len);
+      try {
+        out.push(JSON.parse(body.toString("utf8")));
+      } catch {
+      }
+    }
+    return out;
+  }
+};
+/** Hard cap on a single frame (16 MB). Guards against a runaway/garbage
+ *  length prefix allocating unbounded memory. node-pty data chunks are tiny;
+ *  a serialized scrollback is bounded well under this. */
+_FrameDecoder.MAX_FRAME = 16 * 1024 * 1024;
+var FrameDecoder = _FrameDecoder;
+function userHash() {
+  const seed = `${os.userInfo().username}|${os.hostname()}`;
+  return crypto.createHash("sha1").update(seed).digest("hex").slice(0, 12);
+}
+function socketPathFor(userDataDir) {
+  if (process.platform === "win32") {
+    return `\\\\.\\pipe\\genie-ptyhost-${userHash()}`;
+  }
+  const candidate = path.join(userDataDir, "ptyhost.sock");
+  if (candidate.length < 100) return candidate;
+  return path.join(os.tmpdir(), `genie-ptyhost-${userHash()}.sock`);
+}
+function pidfilePath(userDataDir) {
+  return path.join(userDataDir, "ptyhost.json");
+}
+function writePidfile(userDataDir, pf) {
+  const target = pidfilePath(userDataDir);
+  const tmp = `${target}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(pf));
+  fs.renameSync(tmp, target);
+}
+function readPidfile(userDataDir) {
+  try {
+    const raw = fs.readFileSync(pidfilePath(userDataDir), "utf8");
+    const pf = JSON.parse(raw);
+    if (typeof pf.pid !== "number" || typeof pf.socketPath !== "string" || typeof pf.protocolVersion !== "number") {
+      return null;
+    }
+    return pf;
+  } catch {
+    return null;
+  }
+}
+function deletePidfile(userDataDir) {
+  try {
+    fs.rmSync(pidfilePath(userDataDir), { force: true });
+  } catch {
+  }
+}
+function isPidAlive(pid) {
+  if (!pid || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+function pidfileUsable(pf) {
+  if (!pf) return false;
+  if (pf.protocolVersion !== PROTOCOL_VERSION) return false;
+  if (!isPidAlive(pf.pid)) return false;
+  return true;
+}
+function resolveHostScript(dirname) {
+  const candidates = [
+    // Packaged: node-pty must be unpacked, so run the host from the unpacked
+    // tree too (its require('node-pty') resolves to the unpacked .node).
+    dirname.includes(`app.asar${path.sep}`) || dirname.includes("app.asar/") ? dirname.replace(
+      /app\.asar([\\/])/,
+      `app.asar.unpacked$1`
+    ) + path.sep + "pty-host.js" : "",
+    // Same dir as the compiled main bundle (dev: app/pty-host.js).
+    path.join(dirname, "pty-host.js"),
+    // Defensive: a sibling unpacked dir computed from the asar path.
+    path.join(dirname.replace("app.asar", "app.asar.unpacked"), "pty-host.js")
+  ].filter(Boolean);
+  for (const c of candidates) {
+    try {
+      if (fs.existsSync(c)) return c;
+    } catch {
+    }
+  }
+  return null;
+}
+
+export { FrameDecoder, PROTOCOL_VERSION, deletePidfile, encodeFrame, isPidAlive, pidfilePath, pidfileUsable, readPidfile, resolveHostScript, socketPathFor, userHash, writePidfile };
+//# sourceMappingURL=chunk-2DQJKTG5.js.map
+//# sourceMappingURL=chunk-2DQJKTG5.js.map

package/dist/chunk-2DQJKTG5.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/host-protocol.ts","../src/host-locate.ts"],"names":[],"mappings":"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","file":"chunk-2DQJKTG5.js","sourcesContent":["/**\n * Pty-host wire protocol (Tier 3).\n *\n * The detached pty-host (main/terminal/pty-host.ts) and the in-app HostClient\n * (main/terminal/host-client.ts) talk over a local IPC transport — a named pipe\n * on Windows, a unix domain socket on POSIX — using a tiny length-prefixed JSON\n * framing so there's no heavy dependency. This module is PURE (no electron, no\n * node-pty, no net): just the message shapes + the encode/decode for the framing,\n * so it can be imported by both ends AND unit-tested in isolation.\n *\n * Framing: each message is `[4-byte big-endian uint32 length][utf8 JSON body]`.\n * The length prefix is the byte length of the JSON body. A FrameDecoder buffers\n * partial reads and yields whole messages as they complete — TCP/pipe streams\n * don't preserve message boundaries, so we can't assume one `data` event == one\n * message.\n */\n\n/**\n * Protocol version. Bumped whenever the message shapes change in a way that\n * makes an old host incompatible with a new client (or vice-versa). The client\n * refuses to attach to a host whose pidfile reports a different version and\n * spawns a fresh host instead — see host-client.ts connect-or-spawn.\n */\nexport const PROTOCOL_VERSION = 1;\n\n/** Requests the client sends to the host. `seq` correlates a reply. */\nexport type ClientMessage =\n    | { kind: 'hello'; seq: number; protocolVersion: number }\n    | {\n          kind: 'create';\n          seq: number;\n          opts: {\n              id: string;\n              cwd: string;\n              shell?: string;\n              args?: string[];\n              cols?: number;\n              rows?: number;\n              env?: Record<string, string>;\n          };\n      }\n    | { kind: 'write'; id: string; data: string }\n    | { kind: 'resize'; id: string; cols: number; rows: number }\n    | { kind: 'kill'; id: string }\n    | { kind: 'list'; seq: number }\n    | { kind: 'set-retained'; id: string; retained: boolean }\n    | { kind: 'get-scrollback'; seq: number; id: string }\n    | { kind: 'ping'; seq: number };\n\n/** Pushes + replies the host sends to the client. */\nexport type HostMessage =\n    | { kind: 'hello-ok'; seq: number; protocolVersion: number; pid: number }\n    | {\n          kind: 'created';\n          seq: number;\n          result: {\n              id: string;\n              pid: number;\n              shell: string;\n              existing: boolean;\n              scrollback: string;\n          };\n      }\n    | {\n          kind: 'list-result';\n          seq: number;\n          terminals: Array<{ id: string; pid: number; shell: string }>;\n      }\n    | { kind: 'scrollback-result'; seq: number; scrollback: string | null }\n    | { kind: 'pong'; seq: number }\n    | { kind: 'data'; id: string; data: string }\n    | { kind: 'exit'; id: string; exitCode: number; signal?: number };\n\nexport type Frame = ClientMessage | HostMessage;\n\nconst LENGTH_BYTES = 4;\n\n/** Encode a message as a length-prefixed JSON frame ready for the socket. */\nexport function encodeFrame(msg: Frame): Buffer {\n    const body = Buffer.from(JSON.stringify(msg), 'utf8');\n    const header = Buffer.allocUnsafe(LENGTH_BYTES);\n    header.writeUInt32BE(body.length, 0);\n    return Buffer.concat([header, body]);\n}\n\n/**\n * Streaming frame decoder. Feed it raw socket chunks via `push`; it returns the\n * complete messages that became available (zero or more), buffering any partial\n * tail until the rest arrives. One decoder per socket.\n *\n * Resilient by design: a malformed JSON body is skipped (the frame is consumed\n * but yields nothing) rather than throwing — a corrupt frame must not wedge the\n * whole stream. An absurd length prefix (> MAX_FRAME) is treated as a desync and\n * the buffer is reset; the caller can decide whether to drop the connection.\n */\nexport class FrameDecoder {\n    private buffer: Buffer = Buffer.alloc(0);\n\n    /** Hard cap on a single frame (16 MB). Guards against a runaway/garbage\n     *  length prefix allocating unbounded memory. node-pty data chunks are tiny;\n     *  a serialized scrollback is bounded well under this. */\n    static readonly MAX_FRAME = 16 * 1024 * 1024;\n\n    /** True when the last push hit an oversized/desynced frame. The caller\n     *  should drop the connection — the stream can't be trusted to realign. */\n    desynced = false;\n\n    push(chunk: Buffer): Frame[] {\n        this.buffer = this.buffer.length ? Buffer.concat([this.buffer, chunk]) : chunk;\n        const out: Frame[] = [];\n        for (;;) {\n            if (this.buffer.length < LENGTH_BYTES) break;\n            const len = this.buffer.readUInt32BE(0);\n            if (len > FrameDecoder.MAX_FRAME) {\n                // Desync / garbage. Reset and flag — realigning a length-prefixed\n                // stream after a bad prefix isn't possible without a sentinel.\n                this.desynced = true;\n                this.buffer = Buffer.alloc(0);\n                break;\n            }\n            if (this.buffer.length < LENGTH_BYTES + len) break; // wait for more\n            const body = this.buffer.subarray(LENGTH_BYTES, LENGTH_BYTES + len);\n            this.buffer = this.buffer.subarray(LENGTH_BYTES + len);\n            try {\n                out.push(JSON.parse(body.toString('utf8')) as Frame);\n            } catch {\n                /* skip a corrupt frame; the framing itself is still aligned */\n            }\n        }\n        return out;\n    }\n}\n","import path from 'node:path';\nimport os from 'node:os';\nimport fs from 'node:fs';\nimport crypto from 'node:crypto';\nimport { PROTOCOL_VERSION } from './host-protocol';\n\n/**\n * Path + pidfile resolution for the detached pty-host (Tier 3).\n *\n * Kept ELECTRON-FREE on the resolution side that the host itself uses (the host\n * is a plain node process — no `app`), so the userData path is passed IN. The\n * in-app side (host-client lifecycle) imports `app` separately and feeds it here.\n */\n\nexport interface Pidfile {\n    pid: number;\n    socketPath: string;\n    protocolVersion: number;\n    startedAt: number;\n}\n\n/** Short, stable per-user hash so two OS users don't collide on the Windows\n *  pipe name (the pipe namespace is machine-global). */\nexport function userHash(): string {\n    const seed = `${os.userInfo().username}|${os.hostname()}`;\n    return crypto.createHash('sha1').update(seed).digest('hex').slice(0, 12);\n}\n\n/**\n * The local IPC transport address.\n *   • Windows: a named pipe `\\\\.\\pipe\\genie-ptyhost-<userhash>`. The default\n *     Windows pipe ACL is per-logon-session, so another user on the same machine\n *     can't open it — that's our ACL. (Documented; we don't tighten further.)\n *   • POSIX: a unix domain socket under userData (preferred — survives /tmp\n *     cleaners and is per-user by directory perms) named `ptyhost.sock`.\n */\nexport function socketPathFor(userDataDir: string): string {\n    if (process.platform === 'win32') {\n        return `\\\\\\\\.\\\\pipe\\\\genie-ptyhost-${userHash()}`;\n    }\n    // Keep the path short — unix socket paths have a ~104-char limit. userData is\n    // typically well under that; fall back to os.tmpdir() if it's pathologically\n    // long.\n    const candidate = path.join(userDataDir, 'ptyhost.sock');\n    if (candidate.length < 100) return candidate;\n    return path.join(os.tmpdir(), `genie-ptyhost-${userHash()}.sock`);\n}\n\nexport function pidfilePath(userDataDir: string): string {\n    return path.join(userDataDir, 'ptyhost.json');\n}\n\nexport function writePidfile(userDataDir: string, pf: Pidfile): void {\n    const target = pidfilePath(userDataDir);\n    const tmp = `${target}.tmp`;\n    fs.writeFileSync(tmp, JSON.stringify(pf));\n    fs.renameSync(tmp, target);\n}\n\nexport function readPidfile(userDataDir: string): Pidfile | null {\n    try {\n        const raw = fs.readFileSync(pidfilePath(userDataDir), 'utf8');\n        const pf = JSON.parse(raw) as Pidfile;\n        if (\n            typeof pf.pid !== 'number' ||\n            typeof pf.socketPath !== 'string' ||\n            typeof pf.protocolVersion !== 'number'\n        ) {\n            return null;\n        }\n        return pf;\n    } catch {\n        return null;\n    }\n}\n\nexport function deletePidfile(userDataDir: string): void {\n    try {\n        fs.rmSync(pidfilePath(userDataDir), { force: true });\n    } catch {\n        /* ignore */\n    }\n}\n\n/** True when a process with `pid` is alive (signal 0 probes without killing). */\nexport function isPidAlive(pid: number): boolean {\n    if (!pid || pid <= 0) return false;\n    try {\n        process.kill(pid, 0);\n        return true;\n    } catch (err) {\n        // EPERM = exists but not ours (still \"alive\"); ESRCH = gone.\n        return (err as NodeJS.ErrnoException).code === 'EPERM';\n    }\n}\n\n/**\n * Decide whether an existing pidfile points at a usable host.\n * Usable = pid alive AND protocol versions match. A stale/dead/mismatched\n * pidfile means we must spawn a fresh host.\n */\nexport function pidfileUsable(pf: Pidfile | null): boolean {\n    if (!pf) return false;\n    if (pf.protocolVersion !== PROTOCOL_VERSION) return false;\n    if (!isPidAlive(pf.pid)) return false;\n    return true;\n}\n\n/**\n * Resolve the compiled pty-host script on disk, trying multiple candidate paths\n * so it works in BOTH `npm run dev` (script at app/pty-host.js next to\n * background.js) AND a packaged asar build. node-pty's native binding can't load\n * from inside an asar, so the host (which requires node-pty) must run UNPACKED —\n * `app.asar.unpacked/...`. We try the unpacked path first, then the in-asar path,\n * then a dev-relative path. Returns the first that exists, or null.\n *\n * `dirname` is main/background's __dirname (the directory the compiled main\n * bundle lives in). The host script is emitted alongside it as `pty-host.js`.\n */\nexport function resolveHostScript(dirname: string): string | null {\n    const candidates = [\n        // Packaged: node-pty must be unpacked, so run the host from the unpacked\n        // tree too (its require('node-pty') resolves to the unpacked .node).\n        dirname.includes(`app.asar${path.sep}`) || dirname.includes('app.asar/')\n            ? dirname.replace(\n                  /app\\.asar([\\\\/])/,\n                  `app.asar.unpacked$1`,\n              ) + path.sep + 'pty-host.js'\n            : '',\n        // Same dir as the compiled main bundle (dev: app/pty-host.js).\n        path.join(dirname, 'pty-host.js'),\n        // Defensive: a sibling unpacked dir computed from the asar path.\n        path.join(dirname.replace('app.asar', 'app.asar.unpacked'), 'pty-host.js'),\n    ].filter(Boolean);\n\n    for (const c of candidates) {\n        try {\n            if (fs.existsSync(c)) return c;\n        } catch {\n            /* keep trying */\n        }\n    }\n    return null;\n}\n"]}