@particle-academy/fancy-term-host 0.1.0 → 0.1.2

package/dist/index.d.cts

@@ -366,6 +366,23 @@ declare class HostClient extends EventEmitter implements PtyBackend {
      *  the reattach (renderer remounts these specs, replaying host scrollback). */
     liveIds(): string[];
     isConnected(): boolean;
+    /**
+     * Gracefully shut the host DOWN — the deliberate counterpart to
+     * `disconnect()` (which leaves the host running). Asks the host to kill its
+     * ptys, remove its pidfile/socket, and exit cleanly, then drops the local
+     * socket. Use this when a consumer needs the host genuinely gone — e.g.
+     * before an Electron auto-update whose installer must overwrite the binary
+     * the host runs on — INSTEAD of SIGKILLing by pidfile pid, which skips the
+     * host's own cleanup.
+     *
+     * The client mirror already holds the live scrollback, so snapshot via the
+     * SnapshotStore BEFORE calling this if you want T1 history to survive.
+     *
+     * Resolves once the host acknowledges (`shutdown-ok`) or the connection
+     * closes (the host exited), whichever comes first; never rejects — a host
+     * that's already gone is a successful shutdown.
+     */
+    shutdownHost(timeoutMs?: number): Promise<void>;
     /** Disconnect WITHOUT killing host ptys (before-quit leave-running). */
     disconnect(): void;
     create(opts: CreateTerminalOpts): AttachResult;
@@ -450,6 +467,19 @@ declare function initTerminalBackend(): Promise<{
  * the host running so the next launch reattaches.
  */
 declare function disconnectHostLeaveRunning(): void;
+/**
+ * Gracefully STOP the detached host (the opposite of leave-running): ask it to
+ * kill its ptys, clean up its pidfile/socket, and exit, then drop our client and
+ * revert to the in-process backend so any later create() still works.
+ *
+ * Intended for the case where a consumer needs the host genuinely gone — most
+ * notably before an Electron auto-update whose installer must overwrite the
+ * binary the detached host is running on. Snapshot first (the normal before-quit
+ * T1 path) if you want history to survive; this is a clean shutdown, NOT a
+ * SIGKILL-by-pidfile, so the host runs its own cleanup. No-op (resolves) when no
+ * host is active. NEVER throws.
+ */
+declare function shutdownHost(timeoutMs?: number): Promise<void>;
 
 /**
  * Absolute path to the bundled detached pty-host script (Tier 3), so a
@@ -544,7 +574,7 @@ declare function resolveHostScript(dirname: string): string | null;
  * refuses to attach to a host whose pidfile reports a different version and
  * spawns a fresh host instead — see host-client.ts connect-or-spawn.
  */
-declare const PROTOCOL_VERSION = 1;
+declare const PROTOCOL_VERSION = 2;
 /** Requests the client sends to the host. `seq` correlates a reply. */
 type ClientMessage = {
     kind: 'hello';
@@ -588,6 +618,9 @@ type ClientMessage = {
 } | {
     kind: 'ping';
     seq: number;
+} | {
+    kind: 'shutdown';
+    seq: number;
 };
 /** Pushes + replies the host sends to the client. */
 type HostMessage = {
@@ -620,6 +653,9 @@ type HostMessage = {
 } | {
     kind: 'pong';
     seq: number;
+} | {
+    kind: 'shutdown-ok';
+    seq: number;
 } | {
     kind: 'data';
     id: string;
@@ -774,4 +810,38 @@ declare function parseFileUrl(payload: string): string | null;
  */
 declare function scanOsc7Cwd(chunk: string): string | null;
 
-export { type AttachResult, type BackendDeps, type ClientMessage, type CreateTerminalOpts, type CwdHook, type Encryptor, type Frame, FrameDecoder, HostClient, type HostMessage, type HostSpawner, type HostStatus, PROTOCOL_VERSION, type Pidfile, type PtyBackend, type SettingsProvider, type ShellInfo, type ShellKind, type SnapshotRead, type SnapshotStore, type SnapshotStoreConfig, type TerminalInfo, type TerminalManager, configureHostLifecycle, configureInProcessBackend, createSnapshotStore, cwdHookEnv, cwdHookSpawn, defaultShell, defaultShellId, deletePidfile, detectShells, disconnectHostLeaveRunning, encodeFrame, getHostClient, inProcessBackend, initTerminalBackend, isHostBacked, isPidAlive, parseCommandLine, parseFileUrl, pidfilePath, pidfileUsable, ptyHostScriptPath, readPidfile, resolveDefaultShell, resolveHostScript, scanOsc7Cwd, setActiveBackend, shellKind, socketPathFor, subscribeBackendEvents, terminalManager, userHash, writePidfile };
+/**
+ * Spawn-cwd normalization (Tier 1.5 companion to osc7.ts).
+ *
+ * Git Bash / MSYS reports `$PWD` in MSYS form (`/c/Users/me`), not native
+ * Windows (`C:\Users\me`). The OSC-7 hook emits that raw, and `parseFileUrl`
+ * only converts the drive-colon form (`/C:/...`), so an MSYS path flows through
+ * unchanged. Handing `/c/Users/me` to node-pty as a working dir makes Windows
+ * fail with ERROR_DIRECTORY (error code 267) — terminal creation crashes.
+ *
+ * Two small, OS-agnostic helpers fix this at the source:
+ *   - `toNativeCwd` converts an MSYS path to native Windows form (no-op on
+ *     POSIX, or when already native).
+ *   - `resolveSpawnCwd` native-converts the requested dir AND validates it,
+ *     falling back to the home directory so a stale/foreign/deleted cwd can
+ *     never crash spawn.
+ *
+ * Used at both spawn sites (manager.ts, pty-host.ts) and at the OSC-7 capture
+ * so the persisted `live_cwd` is already a valid native path.
+ */
+/**
+ * Convert an MSYS/Git-Bash cwd to a native Windows path.
+ *   /c/Users/me  -> C:\Users\me
+ *   /d/work      -> D:\work
+ *   /c           -> C:\        (bare drive root)
+ * No-op on non-win32, on an empty string, or on an already-native path.
+ */
+declare function toNativeCwd(p: string): string;
+/**
+ * Resolve the directory a pty should actually spawn in. Prefer the requested
+ * dir (native-converted); if it isn't an existing directory, fall back to the
+ * home directory — so a stale, foreign, or deleted cwd can't crash spawn.
+ */
+declare function resolveSpawnCwd(requested: string | undefined | null): string;
+
+export { type AttachResult, type BackendDeps, type ClientMessage, type CreateTerminalOpts, type CwdHook, type Encryptor, type Frame, FrameDecoder, HostClient, type HostMessage, type HostSpawner, type HostStatus, PROTOCOL_VERSION, type Pidfile, type PtyBackend, type SettingsProvider, type ShellInfo, type ShellKind, type SnapshotRead, type SnapshotStore, type SnapshotStoreConfig, type TerminalInfo, type TerminalManager, configureHostLifecycle, configureInProcessBackend, createSnapshotStore, cwdHookEnv, cwdHookSpawn, defaultShell, defaultShellId, deletePidfile, detectShells, disconnectHostLeaveRunning, encodeFrame, getHostClient, inProcessBackend, initTerminalBackend, isHostBacked, isPidAlive, parseCommandLine, parseFileUrl, pidfilePath, pidfileUsable, ptyHostScriptPath, readPidfile, resolveDefaultShell, resolveHostScript, resolveSpawnCwd, scanOsc7Cwd, setActiveBackend, shellKind, shutdownHost, socketPathFor, subscribeBackendEvents, terminalManager, toNativeCwd, userHash, writePidfile };

package/dist/index.d.ts

@@ -366,6 +366,23 @@ declare class HostClient extends EventEmitter implements PtyBackend {
      *  the reattach (renderer remounts these specs, replaying host scrollback). */
     liveIds(): string[];
     isConnected(): boolean;
+    /**
+     * Gracefully shut the host DOWN — the deliberate counterpart to
+     * `disconnect()` (which leaves the host running). Asks the host to kill its
+     * ptys, remove its pidfile/socket, and exit cleanly, then drops the local
+     * socket. Use this when a consumer needs the host genuinely gone — e.g.
+     * before an Electron auto-update whose installer must overwrite the binary
+     * the host runs on — INSTEAD of SIGKILLing by pidfile pid, which skips the
+     * host's own cleanup.
+     *
+     * The client mirror already holds the live scrollback, so snapshot via the
+     * SnapshotStore BEFORE calling this if you want T1 history to survive.
+     *
+     * Resolves once the host acknowledges (`shutdown-ok`) or the connection
+     * closes (the host exited), whichever comes first; never rejects — a host
+     * that's already gone is a successful shutdown.
+     */
+    shutdownHost(timeoutMs?: number): Promise<void>;
     /** Disconnect WITHOUT killing host ptys (before-quit leave-running). */
     disconnect(): void;
     create(opts: CreateTerminalOpts): AttachResult;
@@ -450,6 +467,19 @@ declare function initTerminalBackend(): Promise<{
  * the host running so the next launch reattaches.
  */
 declare function disconnectHostLeaveRunning(): void;
+/**
+ * Gracefully STOP the detached host (the opposite of leave-running): ask it to
+ * kill its ptys, clean up its pidfile/socket, and exit, then drop our client and
+ * revert to the in-process backend so any later create() still works.
+ *
+ * Intended for the case where a consumer needs the host genuinely gone — most
+ * notably before an Electron auto-update whose installer must overwrite the
+ * binary the detached host is running on. Snapshot first (the normal before-quit
+ * T1 path) if you want history to survive; this is a clean shutdown, NOT a
+ * SIGKILL-by-pidfile, so the host runs its own cleanup. No-op (resolves) when no
+ * host is active. NEVER throws.
+ */
+declare function shutdownHost(timeoutMs?: number): Promise<void>;
 
 /**
  * Absolute path to the bundled detached pty-host script (Tier 3), so a
@@ -544,7 +574,7 @@ declare function resolveHostScript(dirname: string): string | null;
  * refuses to attach to a host whose pidfile reports a different version and
  * spawns a fresh host instead — see host-client.ts connect-or-spawn.
  */
-declare const PROTOCOL_VERSION = 1;
+declare const PROTOCOL_VERSION = 2;
 /** Requests the client sends to the host. `seq` correlates a reply. */
 type ClientMessage = {
     kind: 'hello';
@@ -588,6 +618,9 @@ type ClientMessage = {
 } | {
     kind: 'ping';
     seq: number;
+} | {
+    kind: 'shutdown';
+    seq: number;
 };
 /** Pushes + replies the host sends to the client. */
 type HostMessage = {
@@ -620,6 +653,9 @@ type HostMessage = {
 } | {
     kind: 'pong';
     seq: number;
+} | {
+    kind: 'shutdown-ok';
+    seq: number;
 } | {
     kind: 'data';
     id: string;
@@ -774,4 +810,38 @@ declare function parseFileUrl(payload: string): string | null;
  */
 declare function scanOsc7Cwd(chunk: string): string | null;
 
-export { type AttachResult, type BackendDeps, type ClientMessage, type CreateTerminalOpts, type CwdHook, type Encryptor, type Frame, FrameDecoder, HostClient, type HostMessage, type HostSpawner, type HostStatus, PROTOCOL_VERSION, type Pidfile, type PtyBackend, type SettingsProvider, type ShellInfo, type ShellKind, type SnapshotRead, type SnapshotStore, type SnapshotStoreConfig, type TerminalInfo, type TerminalManager, configureHostLifecycle, configureInProcessBackend, createSnapshotStore, cwdHookEnv, cwdHookSpawn, defaultShell, defaultShellId, deletePidfile, detectShells, disconnectHostLeaveRunning, encodeFrame, getHostClient, inProcessBackend, initTerminalBackend, isHostBacked, isPidAlive, parseCommandLine, parseFileUrl, pidfilePath, pidfileUsable, ptyHostScriptPath, readPidfile, resolveDefaultShell, resolveHostScript, scanOsc7Cwd, setActiveBackend, shellKind, socketPathFor, subscribeBackendEvents, terminalManager, userHash, writePidfile };
+/**
+ * Spawn-cwd normalization (Tier 1.5 companion to osc7.ts).
+ *
+ * Git Bash / MSYS reports `$PWD` in MSYS form (`/c/Users/me`), not native
+ * Windows (`C:\Users\me`). The OSC-7 hook emits that raw, and `parseFileUrl`
+ * only converts the drive-colon form (`/C:/...`), so an MSYS path flows through
+ * unchanged. Handing `/c/Users/me` to node-pty as a working dir makes Windows
+ * fail with ERROR_DIRECTORY (error code 267) — terminal creation crashes.
+ *
+ * Two small, OS-agnostic helpers fix this at the source:
+ *   - `toNativeCwd` converts an MSYS path to native Windows form (no-op on
+ *     POSIX, or when already native).
+ *   - `resolveSpawnCwd` native-converts the requested dir AND validates it,
+ *     falling back to the home directory so a stale/foreign/deleted cwd can
+ *     never crash spawn.
+ *
+ * Used at both spawn sites (manager.ts, pty-host.ts) and at the OSC-7 capture
+ * so the persisted `live_cwd` is already a valid native path.
+ */
+/**
+ * Convert an MSYS/Git-Bash cwd to a native Windows path.
+ *   /c/Users/me  -> C:\Users\me
+ *   /d/work      -> D:\work
+ *   /c           -> C:\        (bare drive root)
+ * No-op on non-win32, on an empty string, or on an already-native path.
+ */
+declare function toNativeCwd(p: string): string;
+/**
+ * Resolve the directory a pty should actually spawn in. Prefer the requested
+ * dir (native-converted); if it isn't an existing directory, fall back to the
+ * home directory — so a stale, foreign, or deleted cwd can't crash spawn.
+ */
+declare function resolveSpawnCwd(requested: string | undefined | null): string;
+
+export { type AttachResult, type BackendDeps, type ClientMessage, type CreateTerminalOpts, type CwdHook, type Encryptor, type Frame, FrameDecoder, HostClient, type HostMessage, type HostSpawner, type HostStatus, PROTOCOL_VERSION, type Pidfile, type PtyBackend, type SettingsProvider, type ShellInfo, type ShellKind, type SnapshotRead, type SnapshotStore, type SnapshotStoreConfig, type TerminalInfo, type TerminalManager, configureHostLifecycle, configureInProcessBackend, createSnapshotStore, cwdHookEnv, cwdHookSpawn, defaultShell, defaultShellId, deletePidfile, detectShells, disconnectHostLeaveRunning, encodeFrame, getHostClient, inProcessBackend, initTerminalBackend, isHostBacked, isPidAlive, parseCommandLine, parseFileUrl, pidfilePath, pidfileUsable, ptyHostScriptPath, readPidfile, resolveDefaultShell, resolveHostScript, resolveSpawnCwd, scanOsc7Cwd, setActiveBackend, shellKind, shutdownHost, socketPathFor, subscribeBackendEvents, terminalManager, toNativeCwd, userHash, writePidfile };

package/dist/index.js

@@ -1,5 +1,5 @@
-import { FrameDecoder, PROTOCOL_VERSION, encodeFrame, readPidfile, pidfileUsable, deletePidfile, resolveHostScript } from './chunk-2DQJKTG5.js';
-export { FrameDecoder, PROTOCOL_VERSION, deletePidfile, encodeFrame, isPidAlive, pidfilePath, pidfileUsable, readPidfile, resolveHostScript, socketPathFor, userHash, writePidfile } from './chunk-2DQJKTG5.js';
+import { FrameDecoder, PROTOCOL_VERSION, encodeFrame, readPidfile, pidfileUsable, deletePidfile, resolveHostScript, resolveSpawnCwd, toNativeCwd } from './chunk-M5TFZDJA.js';
+export { FrameDecoder, PROTOCOL_VERSION, deletePidfile, encodeFrame, isPidAlive, pidfilePath, pidfileUsable, readPidfile, resolveHostScript, resolveSpawnCwd, socketPathFor, toNativeCwd, userHash, writePidfile } from './chunk-M5TFZDJA.js';
 import { spawn } from 'node-pty';
 import { EventEmitter } from 'events';
 import fs2 from 'fs';
@@ -342,7 +342,10 @@ var InProcessBackend = class extends EventEmitter {
     env.TERM = env.TERM || "xterm-256color";
     const pty = spawn(shell, args, {
       name: "xterm-color",
-      cwd: opts.cwd,
+      // Native-convert + validate the requested dir; a stale/foreign/MSYS
+      // cwd (e.g. Git Bash's /c/Users/me) would otherwise crash spawn with
+      // Windows ERROR_DIRECTORY (267). Falls back to home if unusable.
+      cwd: resolveSpawnCwd(opts.cwd),
       cols: opts.cols ?? 80,
       rows: opts.rows ?? 24,
       env
@@ -357,7 +360,8 @@ var InProcessBackend = class extends EventEmitter {
         opts.id,
         next.length > SCROLLBACK_MAX ? next.slice(-SCROLLBACK_MAX) : next
       );
-      const cwd = scanOsc7Cwd(data);
+      const raw = scanOsc7Cwd(data);
+      const cwd = raw ? toNativeCwd(raw) : null;
       if (cwd && cwd !== this.liveCwd.get(opts.id)) {
         this.liveCwd.set(opts.id, cwd);
         this.scheduleCwdPersist(opts.id, cwd);
@@ -801,6 +805,42 @@ var HostClient = class _HostClient extends EventEmitter {
   isConnected() {
     return this.connected;
   }
+  /**
+   * Gracefully shut the host DOWN — the deliberate counterpart to
+   * `disconnect()` (which leaves the host running). Asks the host to kill its
+   * ptys, remove its pidfile/socket, and exit cleanly, then drops the local
+   * socket. Use this when a consumer needs the host genuinely gone — e.g.
+   * before an Electron auto-update whose installer must overwrite the binary
+   * the host runs on — INSTEAD of SIGKILLing by pidfile pid, which skips the
+   * host's own cleanup.
+   *
+   * The client mirror already holds the live scrollback, so snapshot via the
+   * SnapshotStore BEFORE calling this if you want T1 history to survive.
+   *
+   * Resolves once the host acknowledges (`shutdown-ok`) or the connection
+   * closes (the host exited), whichever comes first; never rejects — a host
+   * that's already gone is a successful shutdown.
+   */
+  shutdownHost(timeoutMs = 2e3) {
+    if (!this.socket || !this.connected) {
+      this.disconnect();
+      return Promise.resolve();
+    }
+    this.connected = false;
+    return new Promise((resolve) => {
+      let done = false;
+      const finish = () => {
+        if (done) return;
+        done = true;
+        clearTimeout(timer);
+        this.disconnect();
+        resolve();
+      };
+      const timer = setTimeout(finish, timeoutMs);
+      this.socket?.once("close", finish);
+      this.request({ kind: "shutdown", seq: this.nextSeq() }).then(finish).catch(finish);
+    });
+  }
   /** Disconnect WITHOUT killing host ptys (before-quit leave-running). */
   disconnect() {
     this.connected = false;
@@ -1005,11 +1045,22 @@ function disconnectHostLeaveRunning() {
     }
   }
 }
+async function shutdownHost(timeoutMs = 2e3) {
+  const c = client;
+  usingHost = false;
+  client = null;
+  setActiveBackend(inProcessBackend());
+  if (!c) return;
+  try {
+    await c.shutdownHost(timeoutMs);
+  } catch {
+  }
+}
 function ptyHostScriptPath() {
   const here = typeof __dirname !== "undefined" ? __dirname : path.dirname(fileURLToPath(import.meta.url));
   return resolveHostScript(here) ?? path.join(here, "pty-host.js");
 }
 
-export { HostClient, configureHostLifecycle, configureInProcessBackend, createSnapshotStore, cwdHookEnv, cwdHookSpawn, defaultShell, defaultShellId, detectShells, disconnectHostLeaveRunning, getHostClient, inProcessBackend, initTerminalBackend, isHostBacked, parseCommandLine, parseFileUrl, ptyHostScriptPath, resolveDefaultShell, scanOsc7Cwd, setActiveBackend, shellKind, subscribeBackendEvents, terminalManager };
+export { HostClient, configureHostLifecycle, configureInProcessBackend, createSnapshotStore, cwdHookEnv, cwdHookSpawn, defaultShell, defaultShellId, detectShells, disconnectHostLeaveRunning, getHostClient, inProcessBackend, initTerminalBackend, isHostBacked, parseCommandLine, parseFileUrl, ptyHostScriptPath, resolveDefaultShell, scanOsc7Cwd, setActiveBackend, shellKind, shutdownHost, subscribeBackendEvents, terminalManager };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map