@particle-academy/fancy-term-host 0.1.1 → 0.2.0

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;
@@ -808,4 +844,4 @@ declare function toNativeCwd(p: string): string;
  */
 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, socketPathFor, subscribeBackendEvents, terminalManager, toNativeCwd, userHash, writePidfile };
+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;
@@ -808,4 +844,4 @@ declare function toNativeCwd(p: string): string;
  */
 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, socketPathFor, subscribeBackendEvents, terminalManager, toNativeCwd, userHash, writePidfile };
+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,8 @@
-import { FrameDecoder, PROTOCOL_VERSION, encodeFrame, readPidfile, pidfileUsable, deletePidfile, resolveHostScript, resolveSpawnCwd, toNativeCwd } from './chunk-WMP4YLM5.js';
-export { FrameDecoder, PROTOCOL_VERSION, deletePidfile, encodeFrame, isPidAlive, pidfilePath, pidfileUsable, readPidfile, resolveHostScript, resolveSpawnCwd, socketPathFor, toNativeCwd, userHash, writePidfile } from './chunk-WMP4YLM5.js';
+import { resolveSpawnCwd, toNativeCwd } from './chunk-V3MW5UTX.js';
+export { resolveSpawnCwd, toNativeCwd } from './chunk-V3MW5UTX.js';
+export { ptyHostScriptPath } from './chunk-DB3SIE53.js';
+import { FrameDecoder, PROTOCOL_VERSION, encodeFrame, readPidfile, pidfileUsable, deletePidfile } from './chunk-7NXYRMNA.js';
+export { FrameDecoder, PROTOCOL_VERSION, deletePidfile, encodeFrame, isPidAlive, pidfilePath, pidfileUsable, readPidfile, resolveHostScript, socketPathFor, userHash, writePidfile } from './chunk-7NXYRMNA.js';
 import { spawn } from 'node-pty';
 import { EventEmitter } from 'events';
 import fs2 from 'fs';
@@ -8,7 +11,6 @@ import os from 'os';
 import crypto from 'crypto';
 import zlib from 'zlib';
 import net from 'net';
-import { fileURLToPath } from 'url';
 
 // src/osc7.ts
 var OSC7_RE = /\x1b\]7;([^\x07\x1b]*)(?:\x07|\x1b\\)/g;
@@ -805,6 +807,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;
@@ -1009,11 +1047,18 @@ function disconnectHostLeaveRunning() {
     }
   }
 }
-function ptyHostScriptPath() {
-  const here = typeof __dirname !== "undefined" ? __dirname : path.dirname(fileURLToPath(import.meta.url));
-  return resolveHostScript(here) ?? path.join(here, "pty-host.js");
+async function shutdownHost(timeoutMs = 2e3) {
+  const c = client;
+  usingHost = false;
+  client = null;
+  setActiveBackend(inProcessBackend());
+  if (!c) return;
+  try {
+    await c.shutdownHost(timeoutMs);
+  } catch {
+  }
 }
 
-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, resolveDefaultShell, scanOsc7Cwd, setActiveBackend, shellKind, shutdownHost, subscribeBackendEvents, terminalManager };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map