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

package/dist/service.d.cts

@@ -0,0 +1,248 @@
+/**
+ * Per-user OS-service layer (Tier 3+) — run the pty-host as a launchd
+ * LaunchAgent / systemd --user unit / Windows per-user scheduled task, on its
+ * OWN standalone Node runtime instead of the consumer's Electron binary.
+ *
+ * Why: the detached host launched via `process.execPath` (Electron-as-node)
+ * PINS the consumer's executable, so an Electron auto-update can't overwrite it
+ * without killing live sessions. A service on its own runtime is never pinned —
+ * terminals survive both quits AND updates.
+ *
+ * The wire protocol, `HostClient`, pidfile, and socket path are all UNCHANGED;
+ * only the host's launch + lifecycle move here. See docs/persistence.md.
+ */
+/** The per-OS service mechanism. */
+type ServicePlatform = 'launchd' | 'systemd' | 'windows-task';
+/**
+ * The standalone runtime the service runs the host on. MUST NOT be the
+ * consumer's Electron binary (that reintroduces the pin) — a plain Node.
+ */
+interface ServiceRuntime {
+    /** Absolute path to a standalone `node` (never `electron`). */
+    nodePath: string;
+    /**
+     * Directory holding an ABI-matched `node-pty` build for `nodePath` (added to
+     * the service's `NODE_PATH`). Omit if node-pty resolves normally from the
+     * host script's own `node_modules`.
+     */
+    nodePtyDir?: string;
+    /** How this runtime was resolved (diagnostics only). */
+    source: string;
+}
+/** Inputs describing the service to install for this user. */
+interface HostServiceConfig {
+    /**
+     * Reverse-DNS-ish service label, stable per app + user, e.g.
+     * `"academy.particle.genie.ptyhost"`. Used as the launchd Label, the
+     * systemd unit name, and the Windows task name.
+     */
+    label: string;
+    /** User-data dir the host uses for its pidfile / socket / snapshots. */
+    userDataDir: string;
+    /** Path to the pty-host script. Defaults to `ptyHostScriptPath()`. */
+    hostScript?: string;
+    /** The standalone runtime. Defaults to `resolveServiceRuntime()`. */
+    runtime?: ServiceRuntime;
+    /** Extra environment variables for the host process. */
+    env?: Record<string, string>;
+    /**
+     * Service revision. Bump (or rely on the default, which encodes the host
+     * protocol version) to force a reinstall on upgrade so a stale unit doesn't
+     * keep running an incompatible host.
+     */
+    revision?: string;
+    /** Directory for the service's stdout/stderr logs. Defaults to userDataDir. */
+    logDir?: string;
+}
+type ServiceState = 'running' | 'installed' | 'not-installed' | 'unsupported' | 'unknown';
+/** A snapshot of the installed service's state. */
+interface ServiceStatus {
+    platform: ServicePlatform | 'unsupported';
+    state: ServiceState;
+    installed: boolean;
+    running: boolean;
+    label: string;
+    /** Path to the written unit/plist/launcher, when applicable. */
+    unitPath?: string;
+    /** The revision recorded in the installed unit, if any. */
+    installedRevision?: string;
+    /** Free-text diagnostic (last command output / error). */
+    detail?: string;
+}
+/** What `ensureHostService()` did. */
+type EnsureAction = 'already-running' | 'started' | 'installed-and-started' | 'reinstalled' | 'failed' | 'unsupported';
+/** Result of `ensureHostService()` — never throws; inspect `ok`. */
+interface EnsureResult {
+    /** True when the service is installed AND running at the matching revision. */
+    ok: boolean;
+    installed: boolean;
+    running: boolean;
+    action: EnsureAction;
+    runtime?: ServiceRuntime;
+    /** Set when `ok` is false — the reason, so the caller can fall back. */
+    error?: string;
+}
+/**
+ * Injected IO so the orchestration is unit-testable without touching the real
+ * OS. `nodeServiceIo()` is the production implementation.
+ */
+interface ServiceIo {
+    /** Run a command; resolves with the exit code + captured output. */
+    run(argv: string[]): Promise<{
+        code: number;
+        stdout: string;
+        stderr: string;
+    }>;
+    writeFile(path: string, contents: string, opts?: {
+        mode?: number;
+    }): Promise<void>;
+    readFile(path: string): Promise<string | null>;
+    mkdirp(dir: string): Promise<void>;
+    rm(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+}
+
+/**
+ * Default service revision. Encodes the host PROTOCOL_VERSION so that a protocol
+ * bump (which makes an old host incompatible) forces a reinstall — the installed
+ * unit carries this marker and `ensureHostService` reinstalls on a mismatch.
+ */
+declare const SERVICE_REVISION = "svc1+proto2";
+/** A fully-resolved, per-OS description of the service to install. */
+interface ServiceDescriptor {
+    platform: ServicePlatform;
+    label: string;
+    revision: string;
+    /** The file we write + own (plist / unit / launcher .cmd). */
+    unitPath: string;
+    unitContents: string;
+    /** POSIX file mode for the unit (e.g. 0o600 plist, 0o700 launcher). */
+    unitMode: number;
+    /** Commands (after the file is written) to register + start the service. */
+    installArgv: string[][];
+    /** Commands to stop + deregister. */
+    uninstallArgv: string[][];
+    startArgv: string[][];
+    stopArgv: string[][];
+    /** Single command whose output tells us installed/running. */
+    statusArgv: string[];
+    /** Files to remove on uninstall (unit + any logs we created). */
+    removePaths: string[];
+}
+interface DescriptorContext {
+    /** Override the platform (tests). Defaults to the current OS. */
+    platform?: ServicePlatform;
+    /** Home dir (tests). Defaults to `os.homedir()`. */
+    home?: string;
+    /** Numeric uid for launchd domain targets (tests / non-posix). */
+    uid?: number;
+}
+/** Map `process.platform` to a service mechanism, or null when unsupported. */
+declare function servicePlatformFor(platform?: NodeJS.Platform): ServicePlatform | null;
+/**
+ * Build the per-OS descriptor for a service config. PURE — no fs, no spawning —
+ * so the generated units + command argv are fully unit-testable.
+ */
+declare function buildServiceDescriptor(config: ResolvedServiceConfig, ctx?: DescriptorContext): ServiceDescriptor;
+/**
+ * A config with all defaults filled in — produced by `resolveServiceConfig`
+ * (see index.ts) and consumed by the descriptor builder.
+ */
+interface ResolvedServiceConfig {
+    label: string;
+    userDataDir: string;
+    hostScript: string;
+    runtime: ServiceRuntime;
+    env: Record<string, string>;
+    revision: string;
+    logDir: string;
+}
+/** Read the revision marker out of an installed unit's contents, or null. */
+declare function parseInstalledRevision(unitContents: string): string | null;
+
+/**
+ * Locate a STANDALONE Node runtime to run the host service on — explicitly NOT
+ * the consumer's Electron binary, whose whole problem is that running the host
+ * on it pins the executable across auto-updates.
+ *
+ * Precedence:
+ *   1. An explicit `nodePath` (the consumer ships/locates its own node).
+ *   2. `$FANCY_TERM_NODE` (a deploy-time override).
+ *   3. `process.execPath` — but ONLY if the current process is plain Node, not
+ *      Electron (`process.versions.electron`), and the binary is named `node`.
+ *   4. A `node` / `node.exe` found on `$PATH`.
+ *
+ * Returns null when no safe standalone runtime is found — the caller should then
+ * fall back to the existing detached-spawn (which works for a normal quit) or
+ * in-process. Never throws.
+ */
+interface ResolveRuntimeOptions {
+    /** Explicit standalone node path (wins). */
+    nodePath?: string;
+    /** Directory with an ABI-matched node-pty for that runtime. */
+    nodePtyDir?: string;
+    /** Environment to read overrides from. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Current process binary. Defaults to `process.execPath`. */
+    execPath?: string;
+    /** Whether the current process is Electron. Defaults to detecting it. */
+    isElectron?: boolean;
+    /** PATH lookup probe (injectable for tests). Defaults to an fs probe. */
+    pathProbe?: (binNames: string[], env: NodeJS.ProcessEnv) => string | null;
+}
+declare function resolveServiceRuntime(opts?: ResolveRuntimeOptions): ServiceRuntime | null;
+
+/**
+ * Production {@link ServiceIo}: real fs + child_process. The orchestration in
+ * index.ts takes a ServiceIo so tests can inject a fake and never touch the OS.
+ */
+declare function nodeServiceIo(): ServiceIo;
+
+/**
+ * Per-user OS-service lifecycle for the pty-host. Install / start / stop /
+ * status / uninstall + a single `ensureHostService()` that does the
+ * install-if-missing-or-stale → start-if-stopped dance.
+ *
+ * Pairs with the existing detached-host path: the wire protocol, pidfile, and
+ * `HostClient` are unchanged, so the consumer connects exactly as today. The
+ * difference is WHO launches the host — a per-user service on a standalone Node
+ * runtime, not a child of the consumer's Electron binary.
+ *
+ * Everything here is graceful: `ensureHostService` never throws (inspect `ok`),
+ * so a consumer can try the service and, on failure, fall back to
+ * `HostSpawner.spawnDetached` (normal-quit survival) → in-process.
+ */
+
+/** True when the current OS has a supported service mechanism. */
+declare function isServiceSupported(): boolean;
+/**
+ * Fill in every default (host script, runtime, revision, log dir) so the
+ * descriptor builder has a complete config. Throws only if no standalone Node
+ * runtime can be resolved — callers that want graceful behaviour should use
+ * `ensureHostService`, which catches this.
+ */
+declare function resolveServiceConfig(config: HostServiceConfig): ResolvedServiceConfig;
+/** Write the unit file(s) and register + start the service. */
+declare function installHostService(config: HostServiceConfig, io?: ServiceIo): Promise<ServiceStatus>;
+/** Stop + deregister the service and remove its unit file(s). */
+declare function uninstallHostService(config: HostServiceConfig, io?: ServiceIo): Promise<void>;
+declare function startHostService(config: HostServiceConfig, io?: ServiceIo): Promise<void>;
+declare function stopHostService(config: HostServiceConfig, io?: ServiceIo): Promise<void>;
+declare function isServiceInstalled(config: HostServiceConfig, io?: ServiceIo): Promise<boolean>;
+declare function serviceStatus(config: HostServiceConfig, io?: ServiceIo): Promise<ServiceStatus>;
+/**
+ * Ensure the service is installed at the current revision AND running.
+ *
+ *   - already running at this revision   → no-op
+ *   - installed (this revision), stopped → start
+ *   - installed at a DIFFERENT revision  → uninstall + reinstall + start
+ *   - not installed                      → install (+ start)
+ *
+ * NEVER throws. On any failure (no runtime, unsupported OS, a command error) it
+ * returns `{ ok: false, … }` with an `error` so the caller can fall back to the
+ * detached-spawn path. Snapshot live sessions before a reinstall if you need
+ * history to survive it (a reinstall restarts the host).
+ */
+declare function ensureHostService(config: HostServiceConfig, io?: ServiceIo): Promise<EnsureResult>;
+
+export { type EnsureAction, type EnsureResult, type HostServiceConfig, type ResolvedServiceConfig, SERVICE_REVISION, type ServiceDescriptor, type ServiceIo, type ServicePlatform, type ServiceRuntime, type ServiceState, type ServiceStatus, buildServiceDescriptor, ensureHostService, installHostService, isServiceInstalled, isServiceSupported, nodeServiceIo, parseInstalledRevision, resolveServiceConfig, resolveServiceRuntime, servicePlatformFor, serviceStatus, startHostService, stopHostService, uninstallHostService };

package/dist/service.d.ts

@@ -0,0 +1,248 @@
+/**
+ * Per-user OS-service layer (Tier 3+) — run the pty-host as a launchd
+ * LaunchAgent / systemd --user unit / Windows per-user scheduled task, on its
+ * OWN standalone Node runtime instead of the consumer's Electron binary.
+ *
+ * Why: the detached host launched via `process.execPath` (Electron-as-node)
+ * PINS the consumer's executable, so an Electron auto-update can't overwrite it
+ * without killing live sessions. A service on its own runtime is never pinned —
+ * terminals survive both quits AND updates.
+ *
+ * The wire protocol, `HostClient`, pidfile, and socket path are all UNCHANGED;
+ * only the host's launch + lifecycle move here. See docs/persistence.md.
+ */
+/** The per-OS service mechanism. */
+type ServicePlatform = 'launchd' | 'systemd' | 'windows-task';
+/**
+ * The standalone runtime the service runs the host on. MUST NOT be the
+ * consumer's Electron binary (that reintroduces the pin) — a plain Node.
+ */
+interface ServiceRuntime {
+    /** Absolute path to a standalone `node` (never `electron`). */
+    nodePath: string;
+    /**
+     * Directory holding an ABI-matched `node-pty` build for `nodePath` (added to
+     * the service's `NODE_PATH`). Omit if node-pty resolves normally from the
+     * host script's own `node_modules`.
+     */
+    nodePtyDir?: string;
+    /** How this runtime was resolved (diagnostics only). */
+    source: string;
+}
+/** Inputs describing the service to install for this user. */
+interface HostServiceConfig {
+    /**
+     * Reverse-DNS-ish service label, stable per app + user, e.g.
+     * `"academy.particle.genie.ptyhost"`. Used as the launchd Label, the
+     * systemd unit name, and the Windows task name.
+     */
+    label: string;
+    /** User-data dir the host uses for its pidfile / socket / snapshots. */
+    userDataDir: string;
+    /** Path to the pty-host script. Defaults to `ptyHostScriptPath()`. */
+    hostScript?: string;
+    /** The standalone runtime. Defaults to `resolveServiceRuntime()`. */
+    runtime?: ServiceRuntime;
+    /** Extra environment variables for the host process. */
+    env?: Record<string, string>;
+    /**
+     * Service revision. Bump (or rely on the default, which encodes the host
+     * protocol version) to force a reinstall on upgrade so a stale unit doesn't
+     * keep running an incompatible host.
+     */
+    revision?: string;
+    /** Directory for the service's stdout/stderr logs. Defaults to userDataDir. */
+    logDir?: string;
+}
+type ServiceState = 'running' | 'installed' | 'not-installed' | 'unsupported' | 'unknown';
+/** A snapshot of the installed service's state. */
+interface ServiceStatus {
+    platform: ServicePlatform | 'unsupported';
+    state: ServiceState;
+    installed: boolean;
+    running: boolean;
+    label: string;
+    /** Path to the written unit/plist/launcher, when applicable. */
+    unitPath?: string;
+    /** The revision recorded in the installed unit, if any. */
+    installedRevision?: string;
+    /** Free-text diagnostic (last command output / error). */
+    detail?: string;
+}
+/** What `ensureHostService()` did. */
+type EnsureAction = 'already-running' | 'started' | 'installed-and-started' | 'reinstalled' | 'failed' | 'unsupported';
+/** Result of `ensureHostService()` — never throws; inspect `ok`. */
+interface EnsureResult {
+    /** True when the service is installed AND running at the matching revision. */
+    ok: boolean;
+    installed: boolean;
+    running: boolean;
+    action: EnsureAction;
+    runtime?: ServiceRuntime;
+    /** Set when `ok` is false — the reason, so the caller can fall back. */
+    error?: string;
+}
+/**
+ * Injected IO so the orchestration is unit-testable without touching the real
+ * OS. `nodeServiceIo()` is the production implementation.
+ */
+interface ServiceIo {
+    /** Run a command; resolves with the exit code + captured output. */
+    run(argv: string[]): Promise<{
+        code: number;
+        stdout: string;
+        stderr: string;
+    }>;
+    writeFile(path: string, contents: string, opts?: {
+        mode?: number;
+    }): Promise<void>;
+    readFile(path: string): Promise<string | null>;
+    mkdirp(dir: string): Promise<void>;
+    rm(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+}
+
+/**
+ * Default service revision. Encodes the host PROTOCOL_VERSION so that a protocol
+ * bump (which makes an old host incompatible) forces a reinstall — the installed
+ * unit carries this marker and `ensureHostService` reinstalls on a mismatch.
+ */
+declare const SERVICE_REVISION = "svc1+proto2";
+/** A fully-resolved, per-OS description of the service to install. */
+interface ServiceDescriptor {
+    platform: ServicePlatform;
+    label: string;
+    revision: string;
+    /** The file we write + own (plist / unit / launcher .cmd). */
+    unitPath: string;
+    unitContents: string;
+    /** POSIX file mode for the unit (e.g. 0o600 plist, 0o700 launcher). */
+    unitMode: number;
+    /** Commands (after the file is written) to register + start the service. */
+    installArgv: string[][];
+    /** Commands to stop + deregister. */
+    uninstallArgv: string[][];
+    startArgv: string[][];
+    stopArgv: string[][];
+    /** Single command whose output tells us installed/running. */
+    statusArgv: string[];
+    /** Files to remove on uninstall (unit + any logs we created). */
+    removePaths: string[];
+}
+interface DescriptorContext {
+    /** Override the platform (tests). Defaults to the current OS. */
+    platform?: ServicePlatform;
+    /** Home dir (tests). Defaults to `os.homedir()`. */
+    home?: string;
+    /** Numeric uid for launchd domain targets (tests / non-posix). */
+    uid?: number;
+}
+/** Map `process.platform` to a service mechanism, or null when unsupported. */
+declare function servicePlatformFor(platform?: NodeJS.Platform): ServicePlatform | null;
+/**
+ * Build the per-OS descriptor for a service config. PURE — no fs, no spawning —
+ * so the generated units + command argv are fully unit-testable.
+ */
+declare function buildServiceDescriptor(config: ResolvedServiceConfig, ctx?: DescriptorContext): ServiceDescriptor;
+/**
+ * A config with all defaults filled in — produced by `resolveServiceConfig`
+ * (see index.ts) and consumed by the descriptor builder.
+ */
+interface ResolvedServiceConfig {
+    label: string;
+    userDataDir: string;
+    hostScript: string;
+    runtime: ServiceRuntime;
+    env: Record<string, string>;
+    revision: string;
+    logDir: string;
+}
+/** Read the revision marker out of an installed unit's contents, or null. */
+declare function parseInstalledRevision(unitContents: string): string | null;
+
+/**
+ * Locate a STANDALONE Node runtime to run the host service on — explicitly NOT
+ * the consumer's Electron binary, whose whole problem is that running the host
+ * on it pins the executable across auto-updates.
+ *
+ * Precedence:
+ *   1. An explicit `nodePath` (the consumer ships/locates its own node).
+ *   2. `$FANCY_TERM_NODE` (a deploy-time override).
+ *   3. `process.execPath` — but ONLY if the current process is plain Node, not
+ *      Electron (`process.versions.electron`), and the binary is named `node`.
+ *   4. A `node` / `node.exe` found on `$PATH`.
+ *
+ * Returns null when no safe standalone runtime is found — the caller should then
+ * fall back to the existing detached-spawn (which works for a normal quit) or
+ * in-process. Never throws.
+ */
+interface ResolveRuntimeOptions {
+    /** Explicit standalone node path (wins). */
+    nodePath?: string;
+    /** Directory with an ABI-matched node-pty for that runtime. */
+    nodePtyDir?: string;
+    /** Environment to read overrides from. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Current process binary. Defaults to `process.execPath`. */
+    execPath?: string;
+    /** Whether the current process is Electron. Defaults to detecting it. */
+    isElectron?: boolean;
+    /** PATH lookup probe (injectable for tests). Defaults to an fs probe. */
+    pathProbe?: (binNames: string[], env: NodeJS.ProcessEnv) => string | null;
+}
+declare function resolveServiceRuntime(opts?: ResolveRuntimeOptions): ServiceRuntime | null;
+
+/**
+ * Production {@link ServiceIo}: real fs + child_process. The orchestration in
+ * index.ts takes a ServiceIo so tests can inject a fake and never touch the OS.
+ */
+declare function nodeServiceIo(): ServiceIo;
+
+/**
+ * Per-user OS-service lifecycle for the pty-host. Install / start / stop /
+ * status / uninstall + a single `ensureHostService()` that does the
+ * install-if-missing-or-stale → start-if-stopped dance.
+ *
+ * Pairs with the existing detached-host path: the wire protocol, pidfile, and
+ * `HostClient` are unchanged, so the consumer connects exactly as today. The
+ * difference is WHO launches the host — a per-user service on a standalone Node
+ * runtime, not a child of the consumer's Electron binary.
+ *
+ * Everything here is graceful: `ensureHostService` never throws (inspect `ok`),
+ * so a consumer can try the service and, on failure, fall back to
+ * `HostSpawner.spawnDetached` (normal-quit survival) → in-process.
+ */
+
+/** True when the current OS has a supported service mechanism. */
+declare function isServiceSupported(): boolean;
+/**
+ * Fill in every default (host script, runtime, revision, log dir) so the
+ * descriptor builder has a complete config. Throws only if no standalone Node
+ * runtime can be resolved — callers that want graceful behaviour should use
+ * `ensureHostService`, which catches this.
+ */
+declare function resolveServiceConfig(config: HostServiceConfig): ResolvedServiceConfig;
+/** Write the unit file(s) and register + start the service. */
+declare function installHostService(config: HostServiceConfig, io?: ServiceIo): Promise<ServiceStatus>;
+/** Stop + deregister the service and remove its unit file(s). */
+declare function uninstallHostService(config: HostServiceConfig, io?: ServiceIo): Promise<void>;
+declare function startHostService(config: HostServiceConfig, io?: ServiceIo): Promise<void>;
+declare function stopHostService(config: HostServiceConfig, io?: ServiceIo): Promise<void>;
+declare function isServiceInstalled(config: HostServiceConfig, io?: ServiceIo): Promise<boolean>;
+declare function serviceStatus(config: HostServiceConfig, io?: ServiceIo): Promise<ServiceStatus>;
+/**
+ * Ensure the service is installed at the current revision AND running.
+ *
+ *   - already running at this revision   → no-op
+ *   - installed (this revision), stopped → start
+ *   - installed at a DIFFERENT revision  → uninstall + reinstall + start
+ *   - not installed                      → install (+ start)
+ *
+ * NEVER throws. On any failure (no runtime, unsupported OS, a command error) it
+ * returns `{ ok: false, … }` with an `error` so the caller can fall back to the
+ * detached-spawn path. Snapshot live sessions before a reinstall if you need
+ * history to survive it (a reinstall restarts the host).
+ */
+declare function ensureHostService(config: HostServiceConfig, io?: ServiceIo): Promise<EnsureResult>;
+
+export { type EnsureAction, type EnsureResult, type HostServiceConfig, type ResolvedServiceConfig, SERVICE_REVISION, type ServiceDescriptor, type ServiceIo, type ServicePlatform, type ServiceRuntime, type ServiceState, type ServiceStatus, buildServiceDescriptor, ensureHostService, installHostService, isServiceInstalled, isServiceSupported, nodeServiceIo, parseInstalledRevision, resolveServiceConfig, resolveServiceRuntime, servicePlatformFor, serviceStatus, startHostService, stopHostService, uninstallHostService };