@byok-sdk/client 0.1.0

package/dist/lifecycle/create-service-lifecycle.d.ts

@@ -0,0 +1,59 @@
+import { type LaunchdDeps } from './launchd';
+import { type SystemdDeps } from './systemd';
+import { type WinswDeps } from './winsw';
+import type { ServiceDefinition, ServiceLifecycle } from './service-types';
+export declare class UnsupportedServicePlatformError extends Error {
+    constructor(platform: string);
+}
+export interface CreateServiceLifecycleOptions {
+    /**
+     * Overrides `process.platform` — test-only seam for exercising a
+     * specific platform's generator/install logic from any host (combine
+     * with a mocked `deps.run`/`deps.fs`, since the real launchctl/systemctl/
+     * WinSW binaries obviously aren't present on the "wrong" OS).
+     */
+    platform?: NodeJS.Platform;
+    /** Platform-specific DI seams (mocked exec, mocked fs, mocked homedir/getuid) — only the fields matching the resolved platform are ever read. */
+    deps?: LaunchdDeps & SystemdDeps & WinswDeps;
+}
+/**
+ * Platform-dispatched entry point for M3-4's lifecycle API: manages the
+ * daemon as a background OS service via the platform's own idiomatic
+ * mechanism —
+ *
+ *  - **macOS**: a launchd LaunchAgent (`launchd.ts`).
+ *  - **Linux**: a systemd user unit (`systemd.ts`).
+ *  - **Windows**: a WinSW-wrapped Windows Service (`winsw.ts`) — Node has no
+ *    native SCM control-handler support in core, so a wrapper is used
+ *    rather than hand-rolling the SCM protocol; see `winsw.ts`'s own doc
+ *    comment for why WinSW specifically.
+ *
+ * Every implementation delegates crash-restart entirely to the OS
+ * supervisor (`KeepAlive`/`Restart=on-failure`/`<onfailure>`) — none of them
+ * runs an in-process supervisor loop.
+ *
+ * Deliberately does NOT try to auto-resolve `ServiceDefinition.program`'s
+ * `command`/`agentBin` from `import.meta.resolve`/`import.meta.url`-style
+ * introspection the way `adapters/pi/resolve-bin.ts` does for pi's
+ * optionalDependency. That pattern is a genuinely hazardous fit here: a
+ * relative path from THIS source file to `bin/byok-agent.ts` (`../bin/...`,
+ * since `lifecycle/` and `bin/` are sibling directories under `src/`) does
+ * NOT survive tsup's bundling unchanged — `src/index.ts` and
+ * `src/bin/byok-agent.ts` are two SEPARATE, independently-bundled tsup
+ * entries (see `tsup.config.ts`), so any code from `lifecycle/` ends up
+ * inlined into `dist/index.js` itself, whose OWN directory is `dist/`, not
+ * `dist/lifecycle/` — a path relative to "wherever this bundled code
+ * actually runs from" would need to be `./bin/byok-agent.js` there, the
+ * OPPOSITE of the `../bin/...` that's correct in unbundled `src/`. Guessing
+ * across that bundle boundary is exactly the class of hazard
+ * `templates/packaging/sea/README.md` had to empirically work around for
+ * pi's own resolution path. Rather than add a second such hazard, this
+ * module requires the caller to supply an explicit, already-resolved
+ * `program.command`/args (see `service-types.ts`'s `nodeAgentProgram` —
+ * still just a formatting convenience, not a resolution mechanism) — the
+ * `install`/`uninstall`/`service-*` CLI subcommands (`bin/commands/service.ts`)
+ * default `agentBin` to `process.argv[1]` instead, which Node always
+ * populates correctly with the actual script path being run regardless of
+ * how it was invoked, bundled or not.
+ */
+export declare function createServiceLifecycle(def: ServiceDefinition, opts?: CreateServiceLifecycleOptions): ServiceLifecycle;

package/dist/lifecycle/exec-runner.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Result of running an external command, regardless of its exit code.
+ * `code !== 0` is an ordinary, expected outcome for several callers in this
+ * module (e.g. `launchctl bootout` on a service that isn't currently
+ * loaded, `systemctl --user is-active` on an inactive unit) — it is NOT
+ * treated as a thrown error. See {@link Runner}'s own doc comment for what
+ * DOES reject.
+ */
+export interface RunResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Runs an external service-manager CLI (`launchctl`, `systemctl`, a
+ * WinSW-produced `.exe`, `sc.exe`) and resolves with its exit code +
+ * captured stdout/stderr — it deliberately does NOT reject just because the
+ * command exited non-zero (see {@link RunResult}'s doc comment: that is
+ * everyday signal for several callers here, not failure). It DOES reject
+ * for a genuine spawn failure (the executable itself couldn't be found/run
+ * at all, e.g. `ENOENT`) — see {@link defaultRunner}'s implementation for
+ * how the two are told apart. Callers that need "ran and returned 0 or
+ * throw" wrap this with {@link runOrThrow}.
+ *
+ * The DI seam every one of `launchd.ts`/`systemd.ts`/`winsw.ts` accepts
+ * (`LaunchdDeps.run`/`SystemdDeps.run`/`WinswDeps.run`) — this is what lets
+ * the install/uninstall/start/stop/status logic for all three platforms be
+ * unit-tested from any single host OS with a plain mock, per M3-4's own
+ * verification requirement, without ever shelling out for real in tests.
+ */
+export type Runner = (command: string, args: string[]) => Promise<RunResult>;
+/**
+ * Real implementation: `child_process.execFile`, never a shell
+ * (`exec`/`shell: true`) — the same reasoning as the pi adapter's own
+ * `detect()` (see `templates/packaging/sea/README.md`'s "Windows note" and
+ * `adapters/pi/pi-adapter.ts`): no shell-quoting hazard for a service name,
+ * config path, or WinSW install directory containing spaces or special
+ * characters. Every command this module ever invokes (`launchctl`,
+ * `systemctl`, a WinSW-produced `.exe`, `sc.exe`) is a genuine native
+ * executable, never a `.cmd`/`.bat` shell script, so the one real caveat of
+ * `execFile`-without-`shell` on Windows (a `.cmd`/`.bat` target can't be
+ * `CreateProcess`'d directly) never applies here.
+ *
+ * Node's `execFile` callback distinguishes two failure shapes on its error
+ * argument: when the target process ran and merely exited non-zero, `error.code`
+ * is that NUMERIC exit code; when the executable itself couldn't be spawned
+ * (e.g. `ENOENT`), `error.code` is an ERRNO STRING and there is no real exit
+ * code at all. This implementation resolves the first case as an ordinary
+ * {@link RunResult} (letting callers decide whether a given non-zero exit
+ * matters) and rejects only the second (a real inability to run the
+ * command at all, which every caller should hear about).
+ */
+export declare const defaultRunner: Runner;
+/**
+ * Runs `command`/`args` via `run` and throws a clear, labeled error if it
+ * exits non-zero — for the subset of calls across launchd/systemd/WinSW
+ * that must actually succeed for `install()`/`start()` to honestly report
+ * "the service is now running" (e.g. `launchctl bootstrap`, `systemctl
+ * start`, `winsw install`). Callers that instead want best-effort/tolerant
+ * semantics (e.g. "stop if running, no-op if already stopped") call `run`
+ * directly and ignore the result — see `launchd.ts`/`systemd.ts`/
+ * `winsw.ts`'s own `uninstall()`/`stop()` implementations.
+ */
+export declare function runOrThrow(run: Runner, command: string, args: string[], label: string): Promise<RunResult>;
+/**
+ * Describes what a "genuinely nothing to do" outcome looks like for a
+ * best-effort stop/uninstall step whose target may legitimately already be
+ * absent (not currently loaded/enabled/installed) — as opposed to a genuine
+ * failure (permission denied, service busy, a manager fault, the manager
+ * itself unreachable) that must NOT be treated the same way. See
+ * {@link isIdempotentAbsence}.
+ */
+export interface IdempotentAbsence {
+    /** Exit codes that ALONE mean "already absent", independent of any stdout/stderr text (e.g. Windows's `ERROR_SERVICE_DOES_NOT_EXIST`, 1060). */
+    codes?: readonly number[];
+    /** Case-insensitive patterns checked against `stdout + "\n" + stderr`; a match means "already absent/not loaded/does not exist" for this platform's tool. */
+    patterns: readonly RegExp[];
+    /**
+     * Case-insensitive patterns checked against the SAME `stdout + "\n" +
+     * stderr` text, and consulted BEFORE `codes`/`patterns`: a match here
+     * means "this is a genuine failure", full stop, even if `codes`/`patterns`
+     * would otherwise call the result idempotent absence. Exists because a
+     * connectivity/permission/manager-unreachable error can be textually
+     * indistinguishable from — or reuse the very same generic OS errno string
+     * as — a genuine "not loaded"/"does not exist" message. Concretely: on a
+     * headless host with no reachable `systemd --user` D-Bus session (common
+     * for exactly the SSH/no-lingering boxes this daemon runs on),
+     * `systemctl --user disable --now` fails with `Failed to connect to bus:
+     * No such file or directory` — the SAME "No such file or directory" text
+     * a genuinely-absent unit can also produce, but here it means "we could
+     * not even ask the manager", not "the manager confirms it's gone".
+     * Conflating the two previously let this REAL failure look identical to
+     * idempotent absence and then delete the still-relevant plist/unit/exe
+     * (cross-model-review P1 #7, round 2 — the same re-orphan shape the
+     * original `codes`/`patterns` split was meant to fix in round 1). Each
+     * platform module supplies its own `neverAbsence` for the same reason it
+     * supplies its own `patterns`/`codes`: the actual wording is tool-specific
+     * — see `launchd.ts`/`systemd.ts`/`winsw.ts`'s own constants.
+     */
+    neverAbsence?: readonly RegExp[];
+}
+/**
+ * Distinguishes a KNOWN idempotent "already absent / not loaded / does not
+ * exist" outcome (safe to still proceed with cleanup) from a genuine
+ * failure. A non-zero exit is ambiguous on its own: `launchctl bootout`,
+ * `systemctl disable --now`, and a WinSW `stop`+`uninstall` all use the SAME
+ * non-zero exit for both "there was nothing to stop/unregister" (fine, an
+ * everyday outcome — see this module's own {@link RunResult} doc comment)
+ * and "I refused/failed to do it" (not fine) — conflating the two
+ * previously let a real failure look identical to success and then delete
+ * the plist/unit/exe out from under a still-running service
+ * (cross-model-review P1 #7: an orphaned, uncontrollable process). Each
+ * platform module supplies its own `patterns`/`codes` because the actual
+ * wording/codes are tool-specific — see `launchd.ts`/`systemd.ts`/
+ * `winsw.ts`'s own constants.
+ *
+ * `absence.neverAbsence` is checked FIRST (right after the unambiguous
+ * `code === 0` success case) and, on a match, wins outright over any
+ * `codes`/`patterns` match — see {@link IdempotentAbsence.neverAbsence}'s
+ * own doc comment for why a connectivity/permission/manager-unreachable
+ * signal must never be reclassified as absence no matter what else matches
+ * (cross-model-review P1 #7, round 2).
+ */
+export declare function isIdempotentAbsence(result: RunResult, absence: IdempotentAbsence): boolean;
+/**
+ * Runs `command`/`args` via `run` for a best-effort stop/uninstall step and
+ * throws a clear, labeled error UNLESS the result is either a genuine
+ * success or a known idempotent "already absent" outcome (see
+ * {@link isIdempotentAbsence}). Unlike {@link runOrThrow} (which throws on
+ * ANY non-zero exit, for calls that must actually succeed), this is the
+ * tolerant-but-not-blind form each platform's `uninstall()` needs: proceed
+ * to delete the plist/unit/exe+xml ONLY when this resolves without
+ * throwing; a thrown error here means "do NOT delete the control files —
+ * surface this to the caller so they can retry" (see each platform's own
+ * `uninstall()`). Each platform's standalone `stop()` uses the same
+ * function for the same reason: tolerate "already stopped/not loaded", but
+ * surface — rather than silently swallow — a genuine failure (permission
+ * denied, manager unreachable) instead of misreporting it as "stopped"
+ * (cross-model-review P1 #7, round 2, second half).
+ */
+export declare function runIdempotent(run: Runner, command: string, args: string[], label: string, absence: IdempotentAbsence): Promise<RunResult>;

package/dist/lifecycle/launchd.d.ts

@@ -0,0 +1,55 @@
+import { promises as fsp } from 'node:fs';
+import { type Runner } from './exec-runner';
+import { type ServiceDefinition, type ServiceLifecycle, type ServiceProgram } from './service-types';
+/** DI seam for tests — see `exec-runner.ts`'s `Runner` doc comment for why a mocked `run` is enough to unit-test all of this file's install/uninstall/start/stop/status logic on any host OS. */
+export interface LaunchdDeps {
+    run?: Runner;
+    fs?: Pick<typeof fsp, 'mkdir' | 'writeFile' | 'rm' | 'stat'>;
+    homedir?: () => string;
+    /** Defaults to `process.getuid` — macOS/Linux only; this module is never constructed on `win32` (see `create-service-lifecycle.ts`). */
+    getuid?: () => number;
+}
+/**
+ * Generates a launchd LaunchAgent plist for `label` running `program`,
+ * logging to `logDir`. Pure/no I/O — unit-tested directly for exact content
+ * shape.
+ *
+ * - `RunAtLoad`: true — starts immediately on `launchctl bootstrap`.
+ * - `KeepAlive.SuccessfulExit: false` — the standard, widely-documented
+ *   launchd idiom for "restart only on crash/non-zero-or-signaled exit, do
+ *   NOT restart after a clean `exit(0)`". This is the crash-restart M3-4
+ *   asks for, delegated entirely to launchd — nothing in this SDK
+ *   supervises the process itself.
+ * - `ThrottleInterval: 10` — matches the WinSW recipe's `onfailure delay="10
+ *   sec"` (see `winsw.ts`) so a crash-looping process backs off at a
+ *   comparable rate on every platform, rather than launchd's own default
+ *   (which is already 10s, but left implicit is easy to mistake for
+ *   "unthrottled").
+ * - `StandardOutPath`/`StandardErrorPath` under `logDir` — this is what M3-4
+ *   asks for explicitly ("StandardOut/Error paths under storeDir"), unlike
+ *   `systemd.ts`'s unit (which ALSO writes append-mode log files under
+ *   `logDir` for cross-platform parity, even though systemd's own native
+ *   idiom is the journal).
+ */
+export declare function generateLaunchdPlist(def: {
+    label: string;
+    program: ServiceProgram;
+    logDir: string;
+}): string;
+/**
+ * macOS LaunchAgent lifecycle, built on the modern `launchctl` subcommand
+ * interface (`bootstrap`/`bootout`/`enable`/`kickstart`/`print`, targeting
+ * `gui/<uid>` — the per-user GUI domain LaunchAgents run in — rather than
+ * the legacy `load`/`unload`/`start`/`stop`).
+ *
+ * `start`/`stop` mapping (a real nuance worth documenting, not an arbitrary
+ * choice): `KeepAlive` means a plain signal-kill (`launchctl kill`) would
+ * just have launchd immediately restart the job — that's the crash-restart
+ * feature working exactly as designed, but it means "kill" can't implement
+ * a genuine "stop" on its own. `bootout` (fully unloading the job from the
+ * domain) is the only primitive that stops it without KeepAlive fighting
+ * back, so `stop()` = `bootout` and `start()` = `bootstrap` again (reload
+ * from the still-on-disk plist) — not `kickstart`, which only force-restarts
+ * an ALREADY-loaded job.
+ */
+export declare function createLaunchdLifecycle(def: ServiceDefinition, deps?: LaunchdDeps): ServiceLifecycle;

package/dist/lifecycle/service-types.d.ts

@@ -0,0 +1,177 @@
+/**
+ * What the OS service manager should actually execute to run the daemon in
+ * the background. Deliberately requires an explicit `command` (an absolute
+ * path is strongly recommended, not just a bare command name) rather than
+ * ever trying to auto-resolve one internally — see
+ * `create-service-lifecycle.ts`'s module doc comment for why. A bare
+ * command name relies on the OS service manager's own minimal PATH, which
+ * commonly does NOT include nvm/volta/homebrew node install directories —
+ * a frequent real-world "service can't find node" bug on every one of the
+ * three platforms this module supports.
+ */
+export interface ServiceProgram {
+    command: string;
+    /**
+     * Args passed verbatim to `command` — e.g. `[agentBinPath, 'start',
+     * '--config', configPath]` for a plain node + script run (see
+     * {@link nodeAgentProgram}), or `['start', '--config', configPath]` alone
+     * if `command` is already a self-contained bundled binary (see
+     * `templates/packaging/`). Every platform generator passes these through
+     * untouched — `winsw.ts` emits one `<argument>` element per entry rather
+     * than a single shell-quoted string specifically so a path containing
+     * spaces never needs manual escaping (see that file's doc comment).
+     */
+    args: string[];
+    /** Working directory for the running service process. Each platform generator has its own documented default (see `launchd.ts`/`systemd.ts`/`winsw.ts`) when omitted. */
+    cwd?: string;
+}
+export interface NodeAgentProgramOptions {
+    /** Absolute path to the `byok-agent` entry script to run. No auto-detection — see `create-service-lifecycle.ts`'s doc comment. */
+    agentBin: string;
+    /** Absolute path to the JSON config file `byok-agent start` should load — resolve this to an absolute path BEFORE calling, since the service will run with the OS service manager's own cwd, not the caller's. */
+    configPath: string;
+    /** Node executable to invoke `agentBin` with. Defaults to `process.execPath` (the currently running node) — always an absolute, real path, unlike a bare `node` on PATH. */
+    nodeBin?: string;
+    cwd?: string;
+}
+/**
+ * Convenience builder for the common case: run `node <agentBin> start
+ * --config <configPath>` as the service's program. Still requires the
+ * caller to supply an absolute `agentBin` — this helper is a formatting
+ * convenience only, not a resolution mechanism.
+ */
+export declare function nodeAgentProgram(opts: NodeAgentProgramOptions): ServiceProgram;
+export interface ServiceDefinition {
+    /** Stable service identifier — becomes the launchd `Label`, the systemd unit's basename, and the WinSW `<id>` (sanitized per-platform via {@link sanitizeServiceName}). Typically `DaemonConfig.productId`. */
+    name: string;
+    /** Human-readable display name — systemd `Description=`, WinSW `<name>`/`<description>`. Defaults to `name` if omitted. */
+    displayName?: string;
+    /** What to run — see {@link ServiceProgram}. */
+    program: ServiceProgram;
+    /** Directory the service's stdout/stderr logs are written under (created if missing). On Windows this also doubles as the default WinSW install directory — see `windows.installDir`. */
+    logDir: string;
+    /**
+     * Windows/WinSW-only inputs. Required when actually constructing a
+     * lifecycle on `win32` (`create-service-lifecycle.ts` throws a clear
+     * error otherwise); ignored on macOS/Linux.
+     */
+    windows?: {
+        /**
+         * Absolute path to the product-bundled WinSW executable. Decision-6
+         * boundary: this SDK never bundles or downloads this binary itself —
+         * see `templates/service/winsw/README.md`. The lifecycle copies it
+         * into `installDir` under this service's own name (WinSW's own
+         * convention: the exe and its XML config must share a basename).
+         */
+        winswBin: string;
+        /** Directory the renamed WinSW exe + generated XML are installed into. Defaults to `logDir`. */
+        installDir?: string;
+    };
+}
+/** Options for {@link ServiceLifecycle.install} — an escape hatch for the rare case of reinstalling with a changed program (e.g. after an upgrade moved the agent binary) without reconstructing the whole lifecycle object. Omit to reuse the program given to `createServiceLifecycle`. */
+export interface ServiceInstallOptions {
+    program?: ServiceProgram;
+}
+export interface ServiceStatusResult {
+    /** Whether the platform's own service manager has this service registered at all (a plist/unit/WinSW-config file present — checked directly, not inferred from `running`). */
+    installed: boolean;
+    /** Whether it's currently running, per the platform's own authoritative query (`launchctl print`, `systemctl --user is-active`, `sc.exe query`) — never a locally-cached guess. `false` here means "confirmed not running" ONLY when `determinate` is also `true` — see that field's own doc comment. */
+    running: boolean;
+    /**
+     * Finding P1 #2 (residual, round 3): whether `running`/`installed` above
+     * were actually CONFIRMED by a clean query, as opposed to a fallback
+     * because the platform's own service-manager tool could not be asked at
+     * all. `run()` (`exec-runner.ts`'s `Runner`) resolves an ordinary
+     * non-throwing `RunResult` for a bus-connect failure, an unreachable
+     * launchd GUI domain, or a permission-denied query — the SAME shape a
+     * genuine "not running" query returns — so without this field, a caller
+     * receiving `running: false` could not tell "the manager confirms it's
+     * not running" apart from "the manager could not even be asked" (both
+     * silently collapsed into the same boolean). Concretely:
+     *
+     * - `true`: either an authoritative "running"/"active" match, or a query
+     *   that resolved with a KNOWN clean "not running"/"not loaded"/"not
+     *   found" result.
+     * - `false`: the query itself could not be answered — a
+     *   connectivity/permission/manager-unreachable failure (each platform
+     *   classifies this with the SAME `neverAbsence`-style pattern list its
+     *   `uninstall()`/`stop()` already use for the identical reason — see
+     *   `systemd.ts`/`launchd.ts`/`winsw.ts`'s own
+     *   `*_CONNECTIVITY_OR_PERMISSION_FAILURE` constants). `running: false`
+     *   in this case is a FALLBACK, not a confirmed fact.
+     *
+     * Callers that must not fail open on an unreachable manager (see
+     * `bin/commands/unpair.ts`'s `checkServiceState`) must treat
+     * `determinate: false` exactly the same as a thrown `status()` call.
+     */
+    determinate: boolean;
+    /** Raw human-readable output from the underlying platform tool, for the `service-status` CLI subcommand and debugging. Never parsed further than the booleans above. */
+    detail: string;
+}
+/**
+ * The lifecycle API M3-4 asks for: `install(opts) / uninstall() / start() /
+ * stop() / status()`. Every method but `install` is deliberately
+ * parameterless — the service's identity/program/logDir are already fixed
+ * at `createServiceLifecycle(definition, ...)` construction time (mirrors
+ * `createDaemon(config)`'s own "5-line launcher" shape), so `uninstall`/
+ * `start`/`stop`/`status` always act on that one already-known service.
+ *
+ * Crash-restart is ALWAYS delegated to the OS supervisor (launchd
+ * `KeepAlive`, systemd `Restart=on-failure`, WinSW `<onfailure>`) — no
+ * implementation of this interface runs an in-process supervisor loop of
+ * its own.
+ *
+ * Idempotency convention shared by every platform implementation: `install`
+ * and `start` hard-fail (throw) if the final "make it actually running"
+ * step fails, since silently doing nothing there would misreport success.
+ * `stop` is best-effort/tolerant ONLY of a KNOWN idempotent "already
+ * stopped"/"not loaded"/"not installed" result (mirrors `Daemon.unpair()`'s
+ * own "safe to call at any point in the lifecycle" convention in
+ * `daemon/create-daemon.ts` for that idempotent case) — a genuine failure
+ * (permission denied, manager unreachable, the exe locked/busy) is thrown
+ * instead of being misreported as "stopped", using the same precise
+ * classifier `uninstall` uses (cross-model-review P1 #7, round 2, second
+ * half: silently swallowing a real `stop()` failure undermines the operator's
+ * ability to trust "stopped" at all). `uninstall` is tolerant ONLY of a
+ * KNOWN idempotent "not loaded"/"does not exist"/"already absent" result
+ * from its stop+unregister step (see `exec-runner.ts`'s
+ * `isIdempotentAbsence`) — a genuine failure (permission denied, service
+ * busy, manager error, manager UNREACHABLE — e.g. no reachable systemd
+ * `--user` D-Bus session or launchd GUI domain for this uid, textually
+ * indistinguishable from "already absent" unless explicitly excluded, see
+ * `exec-runner.ts`'s `IdempotentAbsence.neverAbsence`) is thrown instead,
+ * and the plist/unit/winsw exe+xml are deliberately left in place, so a
+ * still-running service never loses its control files and becomes an
+ * orphan nobody can stop/uninstall (cross-model-review P1 #7).
+ */
+export interface ServiceLifecycle {
+    /** Writes the platform service definition and registers + starts it with the OS service manager. Safe to call again later (e.g. after an upgrade): overwrites the definition and reloads it. */
+    install(opts?: ServiceInstallOptions): Promise<void>;
+    /** Stops (if running) and fully removes the service registration + generated definition file. Safe to call when not installed. Throws — and leaves the control file in place — if the underlying service manager reports a genuine failure rather than success/"not installed"; see this interface's own doc comment. */
+    uninstall(): Promise<void>;
+    /** Starts an already-installed service. Throws a clear error if it isn't installed. */
+    start(): Promise<void>;
+    /** Stops a running service without uninstalling it. Safe to call when already stopped (or not installed/not loaded). Throws if the underlying service manager reports a genuine failure instead (e.g. permission denied, manager unreachable) rather than silently reporting success; see this interface's own doc comment. */
+    stop(): Promise<void>;
+    /** Current installed/running state, queried fresh from the platform's own service manager. */
+    status(): Promise<ServiceStatusResult>;
+}
+/**
+ * Sanitizes a free-form product/service identifier into something safe to
+ * embed in a launchd `Label`, a systemd unit filename, and a WinSW `<id>`
+ * (which doubles as a Windows service name AND a generated filename) — the
+ * intersection of all three platforms' safe-identifier rules is
+ * "letters, digits, `.`, `-`, `_`". Anything outside that set collapses to
+ * `-`. A LEADING `-` is then stripped even though `-` is itself an allowed
+ * character: `systemctl`'s argument parser (and, generally, any
+ * getopt-style CLI) mistakes a bare positional argument starting with `-`
+ * for an option rather than the service/unit name — e.g. `systemctl --user
+ * enable --now -foo.service` — which would otherwise misparse every one of
+ * `launchd.ts`/`systemd.ts`/`winsw.ts`'s own `run()` calls that pass this
+ * sanitized name straight through as a CLI argument (cross-model-review P1
+ * #8). Called independently by each platform module (not once centrally) so
+ * every one of `launchd.ts`/`systemd.ts`/`winsw.ts` stays correct even when
+ * used directly, without going through `createServiceLifecycle`'s
+ * dispatcher.
+ */
+export declare function sanitizeServiceName(name: string): string;

package/dist/lifecycle/systemd.d.ts

@@ -0,0 +1,46 @@
+import { promises as fsp } from 'node:fs';
+import { type Runner } from './exec-runner';
+import { type ServiceDefinition, type ServiceLifecycle, type ServiceProgram } from './service-types';
+/** DI seam for tests — see `exec-runner.ts`'s `Runner` doc comment. */
+export interface SystemdDeps {
+    run?: Runner;
+    fs?: Pick<typeof fsp, 'mkdir' | 'writeFile' | 'rm' | 'stat'>;
+    homedir?: () => string;
+}
+/**
+ * Generates a systemd user unit for `name` running `program`, logging to
+ * `logDir`. Pure/no I/O — unit-tested directly for exact content shape, and
+ * (locally, when `systemd-analyze` is available) verified with
+ * `systemd-analyze verify` — see `templates/service/systemd/README.md`.
+ *
+ * `Restart=on-failure` + `RestartSec=10` is the crash-restart M3-4 asks for,
+ * delegated entirely to systemd. `StandardOutput`/`StandardError` are
+ * pointed at append-mode files under `logDir` for parity with the launchd
+ * plist's `StandardOutPath`/`StandardErrorPath` and the WinSW `<logpath>` —
+ * systemd's own native idiom (the journal, `journalctl --user -u <name>`)
+ * still works unconditionally alongside this (systemd always journals
+ * unit's output; explicitly setting `StandardOutput=append:...` needs
+ * systemd >= 240, present on every currently-supported distro this SDK
+ * targets) and is documented in the README as the alternative.
+ */
+export declare function generateSystemdUnit(def: {
+    name: string;
+    displayName: string;
+    program: ServiceProgram;
+    logDir: string;
+}): string;
+/**
+ * Linux systemd **user** service lifecycle (`~/.config/systemd/user/`,
+ * `systemctl --user ...`) — deliberately not a system-wide unit under
+ * `/etc/systemd/system/`, so install/uninstall never needs root, matching
+ * launchd's per-user LaunchAgent (not a system Daemon) and WinSW's
+ * per-machine Windows Service the same way each platform's own idiomatic
+ * "run this in the background for me" mechanism works.
+ *
+ * Requires a running systemd **user instance** for this user (normal on any
+ * desktop/login-manager session, and on modern systemd with
+ * `loginctl enable-linger` for a headless box) — a bare container with no
+ * systemd user session at all will fail every `systemctl --user` call here
+ * with a clear error surfaced from `runOrThrow`, not a silent no-op.
+ */
+export declare function createSystemdLifecycle(def: ServiceDefinition, deps?: SystemdDeps): ServiceLifecycle;

package/dist/lifecycle/winsw.d.ts

@@ -0,0 +1,64 @@
+import { promises as fsp } from 'node:fs';
+import { type Runner } from './exec-runner';
+import { type ServiceDefinition, type ServiceLifecycle, type ServiceProgram } from './service-types';
+/** DI seam for tests — see `exec-runner.ts`'s `Runner` doc comment. */
+export interface WinswDeps {
+    run?: Runner;
+    fs?: Pick<typeof fsp, 'mkdir' | 'writeFile' | 'rm' | 'stat' | 'copyFile'>;
+}
+/**
+ * Generates a WinSW (https://github.com/winsw/winsw) service descriptor XML
+ * for `id` running `program`, logging to `logDir`. Pure/no I/O — unit-tested
+ * directly for exact content shape; the REAL proof this is valid WinSW XML
+ * is the `windows-service-smoke` CI job (`.github/workflows/ci.yml`), which
+ * actually runs `winsw install` against generated output on a real
+ * `windows-latest` runner — this macOS dev box cannot execute WinSW at all.
+ *
+ * Each argument becomes its own `<argument>` element (WinSW's supported
+ * repeatable-element form) rather than a single space-joined `<arguments>`
+ * string — this sidesteps shell-style quoting entirely for a config path
+ * containing spaces, the exact same concern the pi adapter's
+ * `execFile`-without-`shell` note raises for Windows (see
+ * `templates/packaging/sea/README.md`'s "Windows note": WinSW itself
+ * launches `<executable>` directly, no shell involved, so an unescaped
+ * space in a single `<arguments>` string would be split in the wrong
+ * place — one `<argument>` per token has no such ambiguity).
+ *
+ * `<onfailure action="restart" delay="10 sec"/>` (with a second, longer
+ * backoff on repeated failure) is the crash-restart M3-4 asks for,
+ * delegated entirely to WinSW/the Windows SCM — nothing in this SDK
+ * supervises the process itself. `<startmode>Automatic</startmode>` mirrors
+ * launchd's `RunAtLoad`/systemd's `WantedBy=default.target`: the service
+ * also starts automatically on the next machine boot, not just right now.
+ */
+export declare function generateWinswXml(def: {
+    id: string;
+    displayName: string;
+    program: ServiceProgram;
+    logDir: string;
+}): string;
+/**
+ * Windows Service lifecycle via WinSW — the standard, widely-used .NET
+ * service wrapper that gives any exe/command real Windows Service Control
+ * Manager (SCM) integration (crash-restart, logging, boot autostart)
+ * without this SDK hand-rolling the SCM protocol in Node (which has no
+ * native control-handler support in core — the reason a wrapper is needed
+ * at all).
+ *
+ * Decision-6 boundary: the product supplies the WinSW binary
+ * (`def.windows.winswBin`); this module only generates the correct config
+ * and drives install/uninstall/start/stop/status around it. WinSW's own
+ * convention is that its executable and XML config share a basename in the
+ * same directory (`<id>.exe` + `<id>.xml`), so `install()` copies the
+ * product-supplied binary into place under that name rather than invoking
+ * it in place — this is the version-agnostic approach documented across
+ * WinSW v2/v3, unlike relying on a specific `--config` CLI flag that may
+ * differ between major versions.
+ *
+ * `status()` queries `sc.exe` (the real Windows SCM query tool, always
+ * present) rather than parsing WinSW's own `status` subcommand text —
+ * authoritative ground truth independent of WinSW's own output, and the
+ * exact tool `templates/service/winsw/smoke-test.mjs` / the CI job also
+ * assert against.
+ */
+export declare function createWinswLifecycle(def: ServiceDefinition, deps?: WinswDeps): ServiceLifecycle;