@serfab/cadre-host 0.7.1

package/src/installer/config.ts

@@ -0,0 +1,153 @@
+/**
+ * `host.config.json` schema + I/O.
+ *
+ * This file captures the wizard's output. Subsystems (trust-circle, NAT,
+ * orchestrator) each own their own files under `<dataDir>/`; this is NOT
+ * an umbrella config.
+ *
+ * Schema versions:
+ *   v1 — initial layout from 6.4.1.
+ *   v2 — adds `updates: { autoApply, manifestUrl? }` for the update-flow
+ *        (6.4.2). v1 files are silently upgraded on read with autoApply=false.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+export interface UpdatesConfig {
+  /** When true, the daily-check timer auto-applies updates. Default false. */
+  autoApply: boolean;
+  /** Optional override for the manifest URL (env var still wins). */
+  manifestUrl?: string;
+}
+
+export interface HostConfigFile {
+  version: 2;
+  /** A stable per-install id; useful for log correlation and the control-network partyId. */
+  installId: string;
+  /** Localhost-only management UI + API listener port. */
+  uiPort: number;
+  /** External cadre libp2p port (NAT will map to this). */
+  libp2pPort: number;
+  /** Self-reference (convenient for service-host ExecStart). */
+  dataDir: string;
+  /** Absolute path to the Ed25519 protobuf identity. */
+  identityPath: string;
+  /** Whether UPnP/NAT-PMP should be attempted at start time. */
+  upnpEnabled: boolean;
+  /** ISO timestamp the wizard wrote this file. */
+  installedAt: string;
+  /** Installer (= package) version that wrote this file. */
+  installerVersion: string;
+  /** Update-flow settings; defaults: { autoApply: false }. */
+  updates: UpdatesConfig;
+}
+
+const CURRENT_VERSION = 2;
+
+export function writeHostConfig(filePath: string, cfg: HostConfigFile): void {
+  if (cfg.version !== CURRENT_VERSION) {
+    throw new Error(`Refusing to write host.config.json with version=${cfg.version} (current: ${CURRENT_VERSION})`);
+  }
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+}
+
+/** Apply a partial patch to the persisted config (read-modify-write). */
+export function updateHostConfig(
+  filePath: string,
+  patch: Partial<Omit<HostConfigFile, 'version'>>,
+): HostConfigFile {
+  const current = readHostConfig(filePath);
+  const next: HostConfigFile = {
+    ...current,
+    ...patch,
+    updates: { ...current.updates, ...(patch.updates ?? {}) },
+    version: 2,
+  };
+  writeHostConfig(filePath, next);
+  return next;
+}
+
+export function readHostConfig(filePath: string): HostConfigFile {
+  const raw = readFileSync(filePath, 'utf8');
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Failed to parse host.config.json at ${filePath}: ${(err as Error).message}`);
+  }
+  if (!parsed || typeof parsed !== 'object') {
+    throw new Error(`host.config.json at ${filePath} is not a JSON object`);
+  }
+  const obj = parsed as Record<string, unknown>;
+  if (obj.version === 1) {
+    // Silent in-place upgrade. v1 lacks `updates`; default to notify-only.
+    const upgraded = upgradeV1(obj, filePath);
+    writeHostConfig(filePath, upgraded);
+    return upgraded;
+  }
+  if (obj.version !== CURRENT_VERSION) {
+    throw new Error(
+      `host.config.json at ${filePath} has unsupported version=${obj.version} (this build expects ${CURRENT_VERSION})`,
+    );
+  }
+  if (!isHostConfigShape(obj)) {
+    throw new Error(`host.config.json at ${filePath} is missing required fields`);
+  }
+  return obj;
+}
+
+/** v1 → v2 migration: stamp `updates: { autoApply: false }` and bump version. */
+function upgradeV1(obj: Record<string, unknown>, filePath: string): HostConfigFile {
+  if (!isV1Shape(obj)) {
+    throw new Error(`host.config.json at ${filePath} is missing required v1 fields`);
+  }
+  return {
+    version: 2,
+    installId: obj.installId as string,
+    uiPort: obj.uiPort as number,
+    libp2pPort: obj.libp2pPort as number,
+    dataDir: obj.dataDir as string,
+    identityPath: obj.identityPath as string,
+    upnpEnabled: obj.upnpEnabled as boolean,
+    installedAt: obj.installedAt as string,
+    installerVersion: obj.installerVersion as string,
+    updates: { autoApply: false },
+  };
+}
+
+function isV1Shape(v: Record<string, unknown>): boolean {
+  return (
+    typeof v.installId === 'string' &&
+    typeof v.uiPort === 'number' &&
+    typeof v.libp2pPort === 'number' &&
+    typeof v.dataDir === 'string' &&
+    typeof v.identityPath === 'string' &&
+    typeof v.upnpEnabled === 'boolean' &&
+    typeof v.installedAt === 'string' &&
+    typeof v.installerVersion === 'string'
+  );
+}
+
+function isHostConfigShape(v: unknown): v is HostConfigFile {
+  if (!v || typeof v !== 'object') return false;
+  const o = v as Record<string, unknown>;
+  if (
+    typeof o.installId !== 'string' ||
+    typeof o.uiPort !== 'number' ||
+    typeof o.libp2pPort !== 'number' ||
+    typeof o.dataDir !== 'string' ||
+    typeof o.identityPath !== 'string' ||
+    typeof o.upnpEnabled !== 'boolean' ||
+    typeof o.installedAt !== 'string' ||
+    typeof o.installerVersion !== 'string'
+  ) {
+    return false;
+  }
+  const updates = o.updates as Record<string, unknown> | undefined;
+  if (!updates || typeof updates !== 'object') return false;
+  if (typeof updates.autoApply !== 'boolean') return false;
+  if (updates.manifestUrl !== undefined && typeof updates.manifestUrl !== 'string') return false;
+  return true;
+}

package/src/installer/identity.ts

@@ -0,0 +1,49 @@
+/**
+ * Identity persistence for cadre-host.
+ *
+ * The host's libp2p peer identity is an Ed25519 keypair generated at
+ * install time. The protobuf-encoded private key is written to
+ * `<dataDir>/identity.key` with mode 0600 on POSIX. `cadre-host start`
+ * later loads it with `privateKeyFromProtobuf`.
+ *
+ * We persist the protobuf form (not raw bytes) because that's the format
+ * libp2p's `privateKeyFromProtobuf` consumes directly and it preserves the
+ * key type tag — future migrations to a different key algorithm don't
+ * require a schema change here.
+ */
+
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import {
+  generateKeyPair,
+  privateKeyFromProtobuf,
+  privateKeyToProtobuf,
+} from '@libp2p/crypto/keys';
+import { peerIdFromPrivateKey } from '@libp2p/peer-id';
+import type { PrivateKey } from '@libp2p/interface';
+
+export interface IdentityRecord {
+  privateKey: PrivateKey;
+  /** Stringified libp2p peer ID (`12D3Koo…`). */
+  peerId: string;
+}
+
+/** Generate a fresh Ed25519 identity and persist it. Returns the in-memory record. */
+export async function generateIdentity(filePath: string): Promise<IdentityRecord> {
+  const privateKey = await generateKeyPair('Ed25519');
+  const bytes = privateKeyToProtobuf(privateKey);
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, bytes);
+  // 0600 — owner read/write only. No-op on Windows.
+  if (process.platform !== 'win32') {
+    chmodSync(filePath, 0o600);
+  }
+  return { privateKey, peerId: peerIdFromPrivateKey(privateKey).toString() };
+}
+
+/** Load an existing identity file. Throws if it doesn't decode. */
+export function loadIdentity(filePath: string): IdentityRecord {
+  const bytes = readFileSync(filePath);
+  const privateKey = privateKeyFromProtobuf(new Uint8Array(bytes));
+  return { privateKey, peerId: peerIdFromPrivateKey(privateKey).toString() };
+}

package/src/installer/index.ts

@@ -0,0 +1,303 @@
+/**
+ * Public installer surface for cadre-host.
+ *
+ * Orchestrates the install / uninstall flow described in
+ * `tickets/implement/6.4.1-cadre-host-installer.md`.
+ *
+ * The class is purposefully thin — heavy lifting lives in the focused
+ * subsystem modules (wizard.ts, identity.ts, config.ts,
+ * service-host/{systemd,launchd,nssm}.ts, browser.ts).
+ */
+
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+import debug from 'debug';
+
+import { NatStore } from '../nat/index.js';
+
+import { openBrowser } from './browser.js';
+import { writeHostConfig, type HostConfigFile } from './config.js';
+import { generateIdentity } from './identity.js';
+import {
+  configPath,
+  defaultHostJs,
+  defaultServiceDir,
+  identityPath,
+  logsDir,
+} from './paths.js';
+import {
+  detectPlatform,
+  type SupportedPlatform,
+} from './platform.js';
+import { createServiceHost, type ServiceHost, type ServiceHostContext } from './service-host/index.js';
+import {
+  defaultsForPlatform,
+  runWizard,
+  runWizardWith,
+  DEFAULT_UI_PORT,
+  DEFAULT_LIBP2P_PORT,
+  type WizardAnswers,
+} from './wizard.js';
+
+export type { HostConfigFile } from './config.js';
+export type { WizardAnswers, WizardDefaults } from './wizard.js';
+export type { ServiceHost, ServiceHostContext, ServiceHostStatus } from './service-host/index.js';
+
+const log = debug('cadre:host:installer');
+
+export interface InstallOptions {
+  /** If true, all prompts use defaults; CLI flags override individual values. */
+  nonInteractive: boolean;
+  /** Override the data dir. */
+  dataDir?: string;
+  /** Override the UI port. */
+  uiPort?: number;
+  /** Override the libp2p port. */
+  libp2pPort?: number;
+  /** Disable UPnP probing on first run. */
+  noUpnp?: boolean;
+  /** Open browser at end (default true; suppressed by --no-browser or non-TTY). */
+  openBrowser?: boolean;
+  /** Skip the enrollment-invite step (no QR printed). */
+  noInvite?: boolean;
+  /** System-wide install — v1 emits a not-yet-supported error. */
+  system?: boolean;
+  /** Path to node.exe / node binary used by the service-host unit. */
+  nodePath?: string;
+  /** Test-only: stub the service-host registration. */
+  serviceHost?: ServiceHost;
+}
+
+export interface InstallResult {
+  dataDir: string;
+  uiUrl: string;
+  serviceName: string;
+  /** Path to the rendered config file. */
+  configPath: string;
+  /** Generated enrollment invite, unless --no-invite. */
+  enrollmentInvite?: {
+    encodedInvite: string;
+    expiresAt?: string;
+  };
+}
+
+export interface UninstallOptions {
+  /** Also remove the data dir (default false — preserve trust circle + identity). */
+  removeData: boolean;
+  /** Skip the confirmation prompt (for scripts). */
+  yes: boolean;
+  /** Override the data dir to remove (defaults to platform default). */
+  dataDir?: string;
+  /** Test-only: stub the service-host registration. */
+  serviceHost?: ServiceHost;
+}
+
+export interface InstallerOptions {
+  platform?: SupportedPlatform;
+  /** Installer version string written into host.config.json. */
+  installerVersion?: string;
+}
+
+export class Installer {
+  private readonly platform: SupportedPlatform;
+  private readonly installerVersion: string;
+
+  constructor(opts: InstallerOptions = {}) {
+    this.platform = opts.platform ?? detectPlatform();
+    this.installerVersion = opts.installerVersion ?? readPackageVersion();
+  }
+
+  async install(opts: InstallOptions): Promise<InstallResult> {
+    if (opts.system) {
+      throw new Error(
+        'cadre-host install --system is not yet supported. Run without --system ' +
+          'for a per-user install; see packages/cadre-host/service/README.md.',
+      );
+    }
+
+    // 1. Resolve answers — wizard for interactive, defaults+overrides otherwise.
+    const answers = await this.resolveAnswers(opts);
+
+    // 2. Make sure the data dir exists.
+    mkdirSync(answers.dataDir, { recursive: true });
+    mkdirSync(logsDir(answers.dataDir), { recursive: true });
+
+    // 3. Identity + config. Don't overwrite an existing key — re-running
+    //    install on a populated data dir must preserve the host's peer ID.
+    const idPath = identityPath(answers.dataDir);
+    if (existsSync(idPath)) {
+      log('identity already exists at %s — leaving it', idPath);
+    } else {
+      await generateIdentity(idPath);
+    }
+
+    const cfg: HostConfigFile = {
+      version: 2,
+      installId: randomInstallId(),
+      uiPort: answers.uiPort,
+      libp2pPort: answers.libp2pPort,
+      dataDir: answers.dataDir,
+      identityPath: idPath,
+      upnpEnabled: answers.upnpEnabled,
+      installedAt: new Date().toISOString(),
+      installerVersion: this.installerVersion,
+      updates: { autoApply: false },
+    };
+    const cfgPath = configPath(answers.dataDir);
+    writeHostConfig(cfgPath, cfg);
+
+    // 4. Seed nat.json with the chosen libp2p port + UPnP flag so the
+    //    NatService picks them up on first start.
+    seedNatSettings(answers.dataDir, answers.libp2pPort, answers.upnpEnabled);
+
+    // 5. Service-host registration.
+    const serviceHost = opts.serviceHost ?? createServiceHost(this.platform);
+    const ctx: ServiceHostContext = {
+      nodePath: opts.nodePath ?? process.execPath,
+      hostJs: defaultHostJs(),
+      dataDir: answers.dataDir,
+      serviceDir: defaultServiceDir(),
+    };
+    await serviceHost.install(ctx);
+
+    // 6. Browser open (best-effort).
+    const uiUrl = `http://127.0.0.1:${answers.uiPort}/`;
+    const shouldOpenBrowser = opts.openBrowser !== false && !opts.nonInteractive && process.stdout.isTTY;
+    if (shouldOpenBrowser) {
+      openBrowser(uiUrl);
+    }
+
+    // 7. Enrollment invite (best-effort — the listener may not be up yet).
+    let invite: InstallResult['enrollmentInvite'];
+    if (!opts.noInvite && !opts.nonInteractive) {
+      invite = await fetchEnrollmentInvite(answers.uiPort).catch((err) => {
+        log('enrollment-invite fetch failed: %s', (err as Error).message);
+        return undefined;
+      });
+    }
+
+    return {
+      dataDir: answers.dataDir,
+      uiUrl,
+      serviceName: serviceHost.name,
+      configPath: cfgPath,
+      ...(invite ? { enrollmentInvite: invite } : {}),
+    };
+  }
+
+  async uninstall(opts: UninstallOptions): Promise<void> {
+    const dataDir = opts.dataDir ?? defaultsForPlatform(this.platform).dataDir;
+    const serviceHost = opts.serviceHost ?? createServiceHost(this.platform);
+    const ctx: ServiceHostContext = {
+      nodePath: process.execPath,
+      hostJs: defaultHostJs(),
+      dataDir,
+      serviceDir: defaultServiceDir(),
+    };
+    await serviceHost.uninstall(ctx);
+
+    if (opts.removeData) {
+      if (existsSync(dataDir)) {
+        rmSync(dataDir, { recursive: true, force: true });
+        log('removed data dir %s', dataDir);
+      }
+    }
+  }
+
+  async status(opts: { serviceHost?: ServiceHost } = {}): Promise<{ installed: boolean; running: boolean }> {
+    const serviceHost = opts.serviceHost ?? createServiceHost(this.platform);
+    const ctx: ServiceHostContext = {
+      nodePath: process.execPath,
+      hostJs: defaultHostJs(),
+      dataDir: defaultsForPlatform(this.platform).dataDir,
+      serviceDir: defaultServiceDir(),
+    };
+    return await serviceHost.status(ctx);
+  }
+
+  /** Exposed for tests / unattended CI. Resolves the wizard answers without running prompts. */
+  resolveAnswersFromOptions(opts: InstallOptions): WizardAnswers {
+    const defaults = defaultsForPlatform(this.platform);
+    return {
+      dataDir: opts.dataDir ?? defaults.dataDir,
+      uiPort: opts.uiPort ?? defaults.uiPort,
+      libp2pPort: opts.libp2pPort ?? defaults.libp2pPort,
+      upnpEnabled: opts.noUpnp ? false : defaults.upnpEnabled,
+      configureDdns: false,
+    };
+  }
+
+  private async resolveAnswers(opts: InstallOptions): Promise<WizardAnswers> {
+    if (opts.nonInteractive) {
+      return this.resolveAnswersFromOptions(opts);
+    }
+    const defaults = defaultsForPlatform(this.platform);
+    const answers = await runWizard(defaults);
+    // CLI flags still take precedence over wizard input — useful when the
+    // user passes `--ui-port 9000` but accepts defaults at the prompts.
+    return {
+      dataDir: opts.dataDir ?? answers.dataDir,
+      uiPort: opts.uiPort ?? answers.uiPort,
+      libp2pPort: opts.libp2pPort ?? answers.libp2pPort,
+      upnpEnabled: opts.noUpnp ? false : answers.upnpEnabled,
+      configureDdns: answers.configureDdns,
+    };
+  }
+}
+
+export { runWizardWith, defaultsForPlatform, DEFAULT_UI_PORT, DEFAULT_LIBP2P_PORT };
+
+function seedNatSettings(dataDir: string, libp2pPort: number, upnpEnabled: boolean): void {
+  const store = new NatStore(dataDir);
+  // `update()` merges + persists.
+  store.update({
+    externalPort: libp2pPort,
+    internalPort: libp2pPort,
+    upnpEnabled,
+  });
+}
+
+function randomInstallId(): string {
+  return randomBytes(16).toString('hex');
+}
+
+function readPackageVersion(): string {
+  // Best-effort: read the package.json next to dist/ at runtime.
+  try {
+    const here = new URL('../../package.json', import.meta.url);
+    const raw = readFileSync(here, 'utf8');
+    const parsed = JSON.parse(raw) as { version?: string };
+    return parsed.version ?? '0.0.0-unknown';
+  } catch {
+    return '0.0.0-unknown';
+  }
+}
+
+async function fetchEnrollmentInvite(uiPort: number): Promise<InstallResult['enrollmentInvite']> {
+  const url = `http://127.0.0.1:${uiPort}/auth/invites`;
+  // Node 18+'s fetch has no default timeout. Bound it so a slow / hung
+  // local-UI listener can't wedge `cadre-host install` indefinitely.
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 5000);
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ label: 'Install — first device', ttlMs: 24 * 60 * 60 * 1000 }),
+      signal: controller.signal,
+    });
+    if (!response.ok) return undefined;
+    const body = await response.json() as { encodedInvite?: string; expiresAt?: string };
+    if (!body.encodedInvite) return undefined;
+    return {
+      encodedInvite: body.encodedInvite,
+      ...(body.expiresAt ? { expiresAt: body.expiresAt } : {}),
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Exposed for tests that drive the wizard with a custom prompt fn.
+export { runWizard };

package/src/installer/paths.ts

@@ -0,0 +1,109 @@
+/**
+ * Per-platform default paths for the installer.
+ *
+ * Linux:   XDG_DATA_HOME / ~/.local/share/cadre-host
+ * macOS:   ~/Library/Application Support/CadreHost
+ * Windows: %LocalAppData%\CadreHost
+ *
+ * The package root (where the installed `dist/bin/host.js` and `service/`
+ * directory live) is resolved at runtime relative to this module. The
+ * installer needs both: the data dir is per-user state, while the package
+ * root is what the service-host unit's `ExecStart` line points at.
+ */
+
+import { homedir } from 'node:os';
+import { posix, win32, join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import type { SupportedPlatform } from './platform.js';
+
+/** Use the path joiner the *target* platform would use, not the runtime's. */
+function joinFor(platform: SupportedPlatform, ...parts: string[]): string {
+  return platform === 'win32' ? win32.join(...parts) : posix.join(...parts);
+}
+
+export interface InstallerEnv {
+  HOME?: string;
+  XDG_DATA_HOME?: string;
+  XDG_CONFIG_HOME?: string;
+  LocalAppData?: string;
+}
+
+/** Default data dir for the given platform. Honors XDG_DATA_HOME / LocalAppData. */
+export function defaultDataDir(
+  platform: SupportedPlatform,
+  env: InstallerEnv = process.env as InstallerEnv,
+  home: string = homedir(),
+): string {
+  switch (platform) {
+    case 'linux': {
+      const base = env.XDG_DATA_HOME?.trim() || joinFor(platform, env.HOME?.trim() || home, '.local', 'share');
+      return joinFor(platform, base, 'cadre-host');
+    }
+    case 'darwin': {
+      return joinFor(platform, env.HOME?.trim() || home, 'Library', 'Application Support', 'CadreHost');
+    }
+    case 'win32': {
+      // %LocalAppData% is the canonical per-user, non-roaming app data dir.
+      const base = env.LocalAppData?.trim();
+      if (!base) {
+        // Fallback: derive from HOME (works under cygwin/MSYS test envs too).
+        return joinFor(platform, home, 'AppData', 'Local', 'CadreHost');
+      }
+      return joinFor(platform, base, 'CadreHost');
+    }
+  }
+}
+
+/** Path on disk for the installed cadre-host CLI entrypoint. */
+export function defaultHostJs(): string {
+  // dist/installer/paths.js -> ../../dist/bin/host.js
+  // src/installer/paths.ts  -> ../bin/host.ts (only used by tests; build emits dist)
+  const here = dirname(fileURLToPath(import.meta.url));
+  return resolve(here, '..', 'bin', 'host.js');
+}
+
+/** Directory containing service templates (cadre-host.service.tmpl etc.). */
+export function defaultServiceDir(): string {
+  // dist/installer/paths.js -> ../../service/
+  const here = dirname(fileURLToPath(import.meta.url));
+  return resolve(here, '..', '..', 'service');
+}
+
+/** Where the wizard writes the JSON config. */
+export function configPath(dataDir: string): string {
+  return join(dataDir, 'host.config.json');
+}
+
+/** Where the wizard writes the Ed25519 identity. */
+export function identityPath(dataDir: string): string {
+  return join(dataDir, 'identity.key');
+}
+
+/** Logs directory (used by launchd / NSSM unit templates). */
+export function logsDir(dataDir: string): string {
+  return join(dataDir, 'logs');
+}
+
+/** Per-platform install dir for the rendered service unit file. */
+export function serviceInstallPath(
+  platform: SupportedPlatform,
+  env: InstallerEnv = process.env as InstallerEnv,
+  home: string = homedir(),
+): string {
+  const hd = env.HOME?.trim() || home;
+  switch (platform) {
+    case 'linux': {
+      const base = env.XDG_CONFIG_HOME?.trim() || joinFor(platform, hd, '.config');
+      return joinFor(platform, base, 'systemd', 'user', 'cadre-host.service');
+    }
+    case 'darwin': {
+      return joinFor(platform, hd, 'Library', 'LaunchAgents', 'com.serfab.cadre-host.plist');
+    }
+    case 'win32': {
+      // NSSM stores service config in the registry; this path is unused
+      // on Windows but returned for symmetry / logging.
+      return 'HKLM\\SYSTEM\\CurrentControlSet\\Services\\CadreHost';
+    }
+  }
+}

package/src/installer/platform.ts

@@ -0,0 +1,27 @@
+/**
+ * Platform detection helpers for the installer.
+ *
+ * Kept narrow on purpose — `process.platform` everywhere else in the
+ * installer is funneled through here so tests can stub a single point.
+ */
+
+export type SupportedPlatform = 'linux' | 'darwin' | 'win32';
+
+const SUPPORTED: ReadonlySet<NodeJS.Platform> = new Set<NodeJS.Platform>([
+  'linux',
+  'darwin',
+  'win32',
+]);
+
+export function detectPlatform(p: NodeJS.Platform = process.platform): SupportedPlatform {
+  if (!SUPPORTED.has(p)) {
+    throw new Error(
+      `Unsupported platform: ${p}. cadre-host install supports linux, darwin, win32.`,
+    );
+  }
+  return p as SupportedPlatform;
+}
+
+export function isPosix(p: SupportedPlatform): boolean {
+  return p === 'linux' || p === 'darwin';
+}

package/src/installer/service-host/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Pick the right service-host impl for the current platform.
+ */
+
+import { detectPlatform, type SupportedPlatform } from '../platform.js';
+import { SystemdServiceHost } from './systemd.js';
+import { LaunchdServiceHost } from './launchd.js';
+import { NssmServiceHost } from './nssm.js';
+import type { ServiceHost } from './types.js';
+
+export type { ServiceHost, ServiceHostContext, ServiceHostStatus } from './types.js';
+
+export function createServiceHost(platform: SupportedPlatform = detectPlatform()): ServiceHost {
+  switch (platform) {
+    case 'linux':  return new SystemdServiceHost();
+    case 'darwin': return new LaunchdServiceHost();
+    case 'win32':  return new NssmServiceHost();
+  }
+}
+
+export { SystemdServiceHost, LaunchdServiceHost, NssmServiceHost };