@hwip/cli 0.0.1 → 0.1.0

package/dist/listener-service.d.ts

@@ -0,0 +1,225 @@
+import { type ListenerStop } from './listener-process.js';
+/**
+ * The listener as an OS service: a launchd LaunchAgent on macOS, a systemd user
+ * unit on Linux, that starts it at user login so the phone's picker is populated
+ * without anyone opening a terminal.
+ *
+ * Until this existed, the only thing that ever started the daemon was
+ * `hwip cc` (wrapper.ts → startListenerDetached). After a reboot that means an
+ * empty picker until the user happens to launch an agent — the machine is
+ * online, the past sessions are on disk, and the app says "no agents".
+ *
+ * Two constraints shape this file:
+ *
+ * 1. **Node builtins only.** wrapper.ts reads `serviceInstalled()` on the
+ *    `hwip cc` hot path, and the same rule that keeps listener.ts out of
+ *    wrapper.ts (ws + the crypto stack on every agent launch) applies here.
+ *    listener-process.ts is the one import, and it is builtins-only too.
+ *
+ * 2. **Everything the job needs is resolved at install time and baked into
+ *    the plist.** launchd hands a job `/usr/bin:/bin:/usr/sbin:/sbin` and
+ *    nothing else — no shell profile, no homebrew prefix. `verifyTmux()`
+ *    (listener.ts) exits 127 when tmux is not on PATH, so a plist without a
+ *    baked PATH produces a service that dies at every login and is restarted
+ *    forever by KeepAlive. The interpreter is baked for the same reason.
+ */
+/** Reverse-DNS launchd label. Lives on the user's machine once installed —
+ *  renaming it orphans every plist already out there. */
+export declare const SERVICE_LABEL = "app.hwip.listener";
+/** The systemd user unit: the same label, so every message that names
+ *  SERVICE_LABEL names this unit too. */
+export declare const SERVICE_UNIT = "app.hwip.listener.service";
+export type ServiceManager = 'launchd' | 'systemd';
+export interface ServiceSpec {
+    readonly nodePath: string;
+    readonly cliPath: string;
+    readonly tmuxPath: string;
+    readonly logPath: string;
+    /** PATH baked into the job: tmux dir, node dir, then launchd's own. */
+    readonly pathEnv: string;
+    /** UTF-8 locale baked into the job. Always UTF-8 — see resolveServiceSpec. */
+    readonly lang: string;
+}
+export type SpecResolution = {
+    readonly ok: true;
+    readonly value: ServiceSpec;
+    readonly warning?: string;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** The machine facts spec resolution needs, injectable so tests describe a
+ *  machine instead of inheriting the developer's own. */
+export interface ServiceEnv {
+    readonly exists: (path: string) => boolean;
+    /** Version (`v24.15.0`) of the node at `path`, or null when it won't run. */
+    readonly nodeVersion: (path: string) => string | null;
+    /** Absolute tmux path from the invoking shell's PATH, or null. */
+    readonly whichTmux: () => string | null;
+    readonly cliPath: () => string | null;
+    /** The invoking shell's LANG, or undefined when it has none. */
+    readonly lang: () => string | undefined;
+}
+export interface ServiceStatus {
+    readonly manager: ServiceManager;
+    readonly supported: boolean;
+    readonly installed: boolean;
+    readonly label: string;
+    /** The file the service is registered from: the LaunchAgent plist, or under
+     *  systemd the unit file. */
+    readonly plistPath: string;
+    /** Read back from the installed plist — null when nothing is installed. */
+    readonly nodePath: string | null;
+    readonly cliPath: string | null;
+    readonly pathEnv: string | null;
+    readonly langEnv: string | null;
+    /** Programs the plist names that are no longer on disk. The shape a node
+     *  upgrade leaves behind: registered, listed by launchctl, unable to run. */
+    readonly missing: readonly string[];
+}
+/**
+ * Which service manager can run the listener here. macOS always has launchd.
+ * Linux has a systemd user manager only when one answers: a container, or a
+ * shell without a login session, may have none.
+ */
+export declare const serviceManager: (platform?: NodeJS.Platform, userManagerAnswers?: () => boolean) => ServiceManager | null;
+/** launchd on macOS, a systemd user manager on Linux. Every other platform is
+ *  an explicit refusal, never a quiet success. */
+export declare const serviceSupported: () => boolean;
+export declare const servicePlistPath: () => string;
+/** Where systemd's user manager reads a user's own units: `$XDG_CONFIG_HOME/systemd/user`,
+ *  else `~/.config/systemd/user` (systemd.unit(5), user unit search path). */
+export declare const serviceUnitPath: () => string;
+/** Read on the `hwip cc` hot path, so it goes by platform and checks a file —
+ *  it never runs a program to ask whether systemd is there. */
+export declare const serviceInstalled: () => boolean;
+export declare const defaultServiceEnv: ServiceEnv;
+/**
+ * Decide what to bake into the plist, or say why we can't. Nothing is written
+ * and nothing is registered — a caller that gets `ok: false` has touched
+ * nothing on the machine.
+ */
+export declare const resolveServiceSpec: (env?: ServiceEnv) => SpecResolution;
+export declare const renderLaunchAgentPlist: (spec: ServiceSpec) => string;
+/**
+ * What is registered on this machine and whether it can still run. The single
+ * source `verify`, `--service-status` and the `hwip cc` branch all read, so
+ * they can never disagree about whether a service is installed.
+ */
+export declare const serviceStatus: (manager?: ServiceManager | null) => ServiceStatus;
+/**
+ * The unit holds what the plist holds, for the same reasons (see the top of
+ * this file): absolute node and CLI paths, a PATH that reaches tmux — the user
+ * manager's own PATH is whatever the distribution configured (systemd.exec(5),
+ * $PATH) — and a UTF-8 LANG.
+ *
+ * - `Restart=on-failure` + `RestartSec=30` is `KeepAlive:{SuccessfulExit:false}`
+ *   + `ThrottleInterval 30`: a crash comes back, a clean exit stays down
+ *   (systemd.service(5), Restart=).
+ * - `KillMode=process`: stop and restart kill the main process only. The
+ *   default (`control-group`) would kill everything else left in the unit's
+ *   cgroup — including the tmux server the listener started under this unit,
+ *   and with it every agent session (launchd's detach spares it).
+ *   systemd.kill(5) marks process "not recommended!", since it "allows
+ *   processes to escape the service manager's lifecycle and resource
+ *   management" — that escape is the point here: the tmux server is shared
+ *   state, not a child of this service.
+ * - `append:` keeps the daemon writing ~/.hwip/listener.log, which `hwip verify`
+ *   and the log rotation know, instead of the journal (systemd.exec(5)).
+ * - `WantedBy=default.target`: the user manager's main target, started with it
+ *   at login (systemd.special(7), Special User Units).
+ */
+export declare const renderSystemdUnit: (spec: ServiceSpec) => string;
+/**
+ * Side effects the service operations need, injectable so tests can drive the
+ * launchd sequence without a launchd.
+ */
+export interface ServiceOpDeps {
+    readonly supported: () => boolean;
+    readonly resolveSpec: () => SpecResolution;
+    /** PID of a listener running right now, or null. */
+    readonly runningPid: () => number | null;
+    readonly stopListener: (pid: number) => Promise<ListenerStop>;
+    readonly launchctl: (args: string[]) => {
+        ok: boolean;
+        stderr: string;
+    };
+    readonly settle: (ms: number) => Promise<void>;
+}
+/** The same operations under systemd: `systemctl --user` instead of launchctl. */
+export interface SystemdOpDeps extends Omit<ServiceOpDeps, 'launchctl'> {
+    readonly systemctl: (args: string[]) => {
+        ok: boolean;
+        stderr: string;
+    };
+}
+export type ServiceOpResult = {
+    readonly ok: true;
+    readonly notes: readonly string[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+    readonly notes: readonly string[];
+};
+export declare const defaultServiceOpDeps: ServiceOpDeps;
+export declare const defaultSystemdOpDeps: SystemdOpDeps;
+type OpDeps = ServiceOpDeps | SystemdOpDeps;
+/**
+ * Register the service and get the daemon running under it.
+ *
+ * The order is load-bearing, not incidental:
+ *
+ * - **Any listener already running is stopped first.** `handleListener` exits
+ *   **0** when it finds another listener alive, and it only does so quietly
+ *   under HWIP_LISTENER_AUTOSTART, which a service does not have. So a
+ *   kickstart into a live `hwip cc` daemon produces a clean exit, and
+ *   `KeepAlive:{SuccessfulExit:false}` (systemd: `Restart=on-failure`) reads a
+ *   clean exit as "stay down" — for the whole login session. The manager lists
+ *   the job; nothing runs.
+ * - **Nothing is written until the spec resolves.** A refusal leaves the
+ *   machine exactly as it was.
+ * - **The daemon is confirmed alive afterwards.** Without that check the
+ *   failure above ships silently.
+ *
+ * The deps say which manager: launchctl for launchd, systemctl for systemd.
+ */
+export declare const installService: (deps?: OpDeps) => Promise<ServiceOpResult>;
+/** Unregister the job and remove its file. Doing only one of the two leaves
+ *  either a running service with no file or a file the manager ignores. */
+export declare const uninstallService: (deps?: OpDeps) => Promise<ServiceOpResult>;
+/**
+ * Stop the service until the next login.
+ *
+ * launchd: `bootout` and not `disable` — disable writes to launchd's persistent
+ * disabled database, survives logins, and leaves no obvious way back: a
+ * `--stop` that quietly becomes permanent. Session-scoped is what stopping
+ * should mean. systemd: `stop` leaves the unit enabled, so the user manager
+ * starts it again the next time it starts itself.
+ */
+export declare const stopService: (deps?: OpDeps) => ServiceOpResult;
+/** Restart the service in place. Both kill the running instance first, so this
+ *  is also how a version-drifted daemon is replaced. */
+export declare const restartService: (deps?: OpDeps) => ServiceOpResult;
+export interface ServiceHealthRow {
+    readonly label: string;
+    readonly state: 'pass' | 'warn' | 'fail';
+}
+/** The two live facts a health check can't read off the plist. */
+export interface ServiceProbe {
+    /** Can a process started with this PATH find tmux? */
+    readonly tmuxOnPath: (pathEnv: string) => boolean;
+    /** Is the service manager actually running the job right now? */
+    readonly loaded: () => boolean;
+}
+export declare const defaultServiceProbe: ServiceProbe;
+/** `is-active` exits 0 when the unit is running (systemctl(1)). */
+export declare const systemdServiceProbe: ServiceProbe;
+/**
+ * Why this exists: every way the service breaks leaves it looking installed.
+ * `launchctl list` shows the job whether or not its interpreter still exists,
+ * and a PATH without tmux makes the daemon exit 127 at every login while the
+ * registration sits there unchanged. None of that is visible without asking.
+ */
+export declare const serviceHealthChecks: (status: ServiceStatus, probe?: ServiceProbe) => ServiceHealthRow[];
+export {};
+//# sourceMappingURL=listener-service.d.ts.map