@anhlp/alp-client 0.0.0-beta.1

package/src/rpc/errors.js

@@ -0,0 +1,54 @@
+/**
+ * Errors the client raises itself, as opposed to AlpRpcError, which carries an error alpd returned.
+ * Portable: no Node built-ins, process or Buffer (plans/reference/ALPD.md §3, docs/alp/client-sdk.md).
+ */
+
+const BRAND = Symbol.for('@anhlp/alp-client/AlpClientError');
+
+/**
+ * Why a request or a connection ended on the client side.
+ * - `closed`: this client was closed locally with close().
+ * - `disconnected`: the transport closed or failed. A request that was already sent may or may not
+ *   have run on the daemon; the client never resends it.
+ * - `protocol`: the peer sent something that is not ALP JSON-RPC, so the client closed the connection.
+ * - `send_failed`: the transport refused the frame; the request never left this client.
+ * - `timeout` / `aborted`: the caller stopped waiting. Only the local wait ends; the daemon is not told.
+ * - `overloaded`: too many requests are waiting for an answer already; nothing was sent.
+ */
+export const CLIENT_ERROR = Object.freeze({
+  closed: 'closed',
+  disconnected: 'disconnected',
+  protocol: 'protocol',
+  sendFailed: 'send_failed',
+  timeout: 'timeout',
+  aborted: 'aborted',
+  overloaded: 'overloaded',
+});
+
+export class AlpClientError extends Error {
+  /**
+   * @param {string} message
+   * @param {{ reason: 'closed' | 'disconnected' | 'protocol' | 'send_failed' | 'timeout' | 'aborted' | 'overloaded', cause?: unknown, data?: unknown }} details
+   */
+  constructor(message, { reason, cause, data }) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = 'AlpClientError';
+    /** @type {'closed' | 'disconnected' | 'protocol' | 'send_failed' | 'timeout' | 'aborted' | 'overloaded'} */
+    this.reason = reason;
+    /** @type {unknown} */
+    this.data = data;
+    Object.defineProperty(this, BRAND, { value: true });
+  }
+}
+
+/**
+ * True for an AlpClientError, also one thrown by another copy of this module (a bundle may carry
+ * two); `reason` narrows the check.
+ * @param {unknown} error
+ * @param {string} [reason]
+ * @returns {error is AlpClientError}
+ */
+export function isAlpClientError(error, reason) {
+  return typeof error === 'object' && error !== null && /** @type {any} */ (error)[BRAND] === true
+    && (reason === undefined || /** @type {any} */ (error).reason === reason);
+}

package/src/rpc/framing.js

@@ -0,0 +1,61 @@
+/**
+ * Newline-delimited JSON framing for stream transports (a Unix socket, a named pipe, a TCP
+ * stream). Portable: strings in, strings out; the stream owner decodes bytes to text first.
+ * Message transports such as a WebSocket carry whole frames and need none of this.
+ */
+
+/** UTF-8 length of `text` without Buffer or TextEncoder; an unpaired surrogate counts as U+FFFD (3 bytes). @param {string} text */
+export function utf8Length(text) {
+  let bytes = 0;
+  for (let index = 0; index < text.length; index++) {
+    const code = text.charCodeAt(index);
+    if (code < 0x80) bytes += 1;
+    else if (code < 0x800) bytes += 2;
+    else if (code >= 0xd800 && code <= 0xdbff && index + 1 < text.length && (text.charCodeAt(index + 1) & 0xfc00) === 0xdc00) { bytes += 4; index++; }
+    else bytes += 3;
+  }
+  return bytes;
+}
+
+/**
+ * Splits decoded text chunks into frames. `push` returns the complete frames in order, blank
+ * lines skipped, and throws once a frame (complete or still arriving) exceeds `maxFrame` bytes;
+ * the decoder is unusable after that. Each character is measured once, so a frame that arrives
+ * in many chunks costs linear time.
+ * @param {{ maxFrame: number }} options
+ * @returns {{ push(chunk: string): string[], readonly buffered: number }}
+ */
+export function createLineDecoder({ maxFrame }) {
+  /** @type {string[]} */
+  let parts = [];
+  let bytes = 0;
+  let failed = false;
+  const overflow = () => { failed = true; parts = []; bytes = 0; return new RangeError(`Frame exceeds ${maxFrame} bytes`); };
+  return {
+    push(chunk) {
+      if (failed) throw new RangeError('Line decoder already failed');
+      /** @type {string[]} */
+      const frames = [];
+      let start = 0;
+      for (let index = chunk.indexOf('\n'); index >= 0; index = chunk.indexOf('\n', start)) {
+        const piece = chunk.slice(start, index);
+        bytes += utf8Length(piece);
+        if (bytes > maxFrame) throw overflow();
+        parts.push(piece);
+        const line = parts.length === 1 ? parts[0] : parts.join('');
+        parts = [];
+        bytes = 0;
+        start = index + 1;
+        if (line.trim()) frames.push(line);
+      }
+      if (start < chunk.length) {
+        const rest = chunk.slice(start);
+        bytes += utf8Length(rest);
+        if (bytes > maxFrame) throw overflow();
+        parts.push(rest);
+      }
+      return frames;
+    },
+    get buffered() { return bytes; },
+  };
+}

package/src/rpc/handshake.js

@@ -0,0 +1,16 @@
+import { PROTOCOL_VERSION } from '@anhlp/alp-protocol';
+
+/** @typedef {{ name: string, version: string }} ClientInfo */
+
+/**
+ * The version handshake every ALP connection starts with (plans/reference/ALPD.md §3): alpd
+ * answers nothing else before it. Shared by the Node `connect` and portable clients, so a change
+ * to the handshake (Task 06) lands in one place.
+ * @param {{ request(method: string, params?: unknown, options?: import('./client.js').RequestOptions): Promise<any> }} client
+ * @param {ClientInfo} [info]
+ * @param {import('./client.js').RequestOptions} [options]
+ * @returns {Promise<{ protocolVersion: number } & Record<string, unknown>>}
+ */
+export function hello(client, info = { name: 'alp', version: '0' }, options) {
+  return client.request('daemon.hello', { protocolVersion: PROTOCOL_VERSION, client: info }, options);
+}

package/src/rpc/reconnect.js

@@ -0,0 +1,226 @@
+import { AlpRpcError, ERROR } from '@anhlp/alp-protocol';
+import { AlpRpcClient } from './client.js';
+import { AlpClientError } from './errors.js';
+
+/**
+ * Keeps an ALP connection up: connects, runs the caller's `onConnect` (handshake, reattach and
+ * replay as the protocol defines them), and after a disconnect connects again with exponential
+ * backoff until stopped. A connection counts as up only once it has stayed open `stableMs`; one
+ * that drops sooner (a gateway closing right after the handshake) counts as a failed attempt, so
+ * backoff and `maxAttempts` still apply. It never resends a request: requests in flight when the connection drops
+ * reject as `disconnected`, and requests made while it is down reject at once. Whether and how to
+ * retry belongs to the caller, who knows which methods are safe to repeat.
+ */
+
+/**
+ * @typedef {import('./client.js').AlpTransport} AlpTransport
+ * @typedef {import('./client.js').AlpRpcClientOptions} AlpRpcClientOptions
+ * @typedef {import('./client.js').RequestOptions} RequestOptions
+ * @typedef {import('./client.js').AbortSignalLike} AbortSignalLike
+ * @typedef {'connecting' | 'open' | 'waiting' | 'stopped'} ReconnectState
+ * @typedef {{ initialMs?: number, maxMs?: number, factor?: number, jitter?: number }} Backoff
+ * @typedef {{
+ *   connect(context: { attempt: number, signal: AbortSignalLike }): Promise<AlpTransport>,
+ *   onConnect?(client: AlpRpcClient, context: { attempt: number, reconnect: boolean, signal: AbortSignalLike }): unknown,
+ *   onDisconnect?(error: Error, context: { reconnect: boolean }): void,
+ *   backoff?: Backoff,
+ *   maxAttempts?: number,
+ *   stableMs?: number,
+ *   shouldRetry?(error: Error): boolean,
+ *   client?: AlpRpcClientOptions,
+ *   random?: () => number,
+ * }} ReconnectOptions
+ * @typedef {{
+ *   readonly state: ReconnectState,
+ *   readonly client: AlpRpcClient | undefined,
+ *   readonly attempt: number,
+ *   ready(options?: { signal?: AbortSignalLike }): Promise<AlpRpcClient>,
+ *   request<T = any>(method: string, params?: unknown, options?: RequestOptions): Promise<T>,
+ *   onEvent(listener: (envelope: any) => void): () => boolean,
+ *   onNotification(listener: (method: string, params: any) => void): () => boolean,
+ *   onState(listener: (state: ReconnectState, error?: Error) => void): () => boolean,
+ *   stop(): void,
+ * }} ReconnectingClient
+ */
+
+/** The delay before attempt `attempt` (1-based), with ±jitter. @param {number} attempt @param {Backoff} backoff @param {() => number} random */
+export function backoffDelay(attempt, { initialMs = 250, maxMs = 10_000, factor = 2, jitter = 0.2 } = {}, random = Math.random) {
+  const base = Math.min(maxMs, initialMs * factor ** Math.max(0, attempt - 1));
+  return Math.max(0, Math.round(base * (1 + jitter * (2 * random() - 1))));
+}
+
+/**
+ * Whether a failed connect or onConnect is worth another attempt: everything but alpd refusing the
+ * handshake (ERROR.protocol, an unsupported protocol version), which retrying cannot fix.
+ * @param {Error} error
+ */
+export function retryable(error) {
+  return !(error instanceof AlpRpcError && error.code === ERROR.protocol);
+}
+
+/** The platform's AbortController, whose signal fetch and AbortSignal.any accept; a minimal one where there is none. */
+function controller() {
+  if (typeof globalThis.AbortController === 'function') {
+    const native = new globalThis.AbortController();
+    return { signal: /** @type {AbortSignalLike} */ (native.signal), /** @param {unknown} reason */ abort: reason => native.abort(reason) };
+  }
+  /** @type {Set<() => void>} */
+  const listeners = new Set();
+  const signal = {
+    aborted: false,
+    /** @type {unknown} */ reason: undefined,
+    /** @param {'abort'} _type @param {() => void} listener */
+    addEventListener(_type, listener) { listeners.add(listener); },
+    /** @param {'abort'} _type @param {() => void} listener */
+    removeEventListener(_type, listener) { listeners.delete(listener); },
+  };
+  return {
+    signal,
+    /** @param {unknown} reason */
+    abort(reason) {
+      if (signal.aborted) return;
+      signal.aborted = true;
+      signal.reason = reason;
+      for (const listener of [...listeners]) listener();
+      listeners.clear();
+    },
+  };
+}
+
+/**
+ * @param {ReconnectOptions} options
+ * @returns {ReconnectingClient}
+ */
+export function createReconnectingClient({ connect, onConnect, onDisconnect, backoff = {}, maxAttempts = Infinity, stableMs = 5_000, shouldRetry = retryable, client: clientOptions, random = Math.random }) {
+  if (typeof connect !== 'function') throw new TypeError('createReconnectingClient needs connect()');
+  /** @type {ReconnectState} */
+  let state = 'connecting';
+  /** @type {AlpRpcClient | undefined} */
+  let current;
+  let attempt = 0;
+  let connectedBefore = false;
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer;
+  // One run for the client's whole life: stop() is final and aborts it.
+  const run = controller();
+  /** @type {Set<(envelope: any) => void>} */
+  const events = new Set();
+  /** @type {Set<(method: string, params: any) => void>} */
+  const notifications = new Set();
+  /** @type {Set<(state: ReconnectState, error?: Error) => void>} */
+  const states = new Set();
+  /** @type {Set<{ resolve(client: AlpRpcClient): void, reject(error: Error): void }>} */
+  const waiters = new Set();
+
+  const onListenerError = clientOptions?.onListenerError ?? (error => { setTimeout(() => { throw error; }, 0); });
+  /** @param {Function} listener @param {unknown[]} args */
+  const dispatch = (listener, ...args) => { try { listener(...args); } catch (error) { onListenerError(error); } };
+
+  /** @param {ReconnectState} next @param {Error} [error] */
+  const enter = (next, error) => {
+    state = next;
+    for (const listener of [...states]) {
+      dispatch(listener, next, error);
+      // A listener that called stop() has moved the state on; later ones must not hear a stale one.
+      if (state !== next) return;
+    }
+    if (next === 'open' && current) for (const waiter of [...waiters]) { waiters.delete(waiter); waiter.resolve(current); }
+    if (next === 'stopped') for (const waiter of [...waiters]) { waiters.delete(waiter); waiter.reject(error ?? new AlpClientError('ALP connection stopped', { reason: 'closed' })); }
+  };
+
+  /** @param {Error} error */
+  const retry = error => {
+    if (state === 'stopped') return;
+    if (attempt >= maxAttempts || !shouldRetry(error)) return enter('stopped', error);
+    enter('waiting', error);
+    if (state !== 'waiting') return;
+    timer = setTimeout(() => { timer = undefined; void open(); }, backoffDelay(attempt, backoff, random));
+  };
+
+  const open = async () => {
+    if (state === 'stopped') return;
+    attempt++;
+    enter('connecting');
+    const { signal } = run;
+    if (state !== 'connecting' || signal.aborted) return;
+    /** @type {AlpRpcClient | undefined} */
+    let candidate;
+    // stop() during the handshake closes the connection being set up: its pending requests reject
+    // and nothing more is sent on it.
+    const closeCandidate = () => candidate?.close();
+    signal.addEventListener('abort', closeCandidate, { once: true });
+    try {
+      const transport = await connect({ attempt, signal });
+      if (signal.aborted) { try { transport.close(); } catch {} return; }
+      candidate = new AlpRpcClient(transport, clientOptions);
+      // Listeners go on before onConnect so a replay it requests reaches them.
+      // Each caller listener runs on its own, as on AlpRpcClient: one that throws does not stop the rest.
+      candidate.onEvent(envelope => { for (const listener of [...events]) dispatch(listener, envelope); });
+      candidate.onNotification((method, params) => { for (const listener of [...notifications]) dispatch(listener, method, params); });
+      if (onConnect) await onConnect(candidate, { attempt, reconnect: connectedBefore, signal });
+      if (signal.aborted) { candidate.close(); return; }
+      if (candidate.closed) throw new AlpClientError('ALP connection closed during onConnect', { reason: 'disconnected' });
+    } catch (error) {
+      candidate?.close();
+      if (signal.aborted) return;
+      return retry(error instanceof Error ? error : new Error(String(error)));
+    } finally {
+      signal.removeEventListener('abort', closeCandidate);
+    }
+    const connected = /** @type {AlpRpcClient} */ (candidate);
+    current = connected;
+    const reconnect = connectedBefore;
+    connectedBefore = true;
+    const openedAt = Date.now();
+    connected.onClose(error => {
+      if (current !== connected) return;
+      current = undefined;
+      // Only a connection that stayed up starts the next one from a fresh backoff.
+      if (Date.now() - openedAt >= stableMs) attempt = 0;
+      dispatch(() => onDisconnect?.(error, { reconnect }));
+      retry(error);
+    });
+    enter('open');
+  };
+
+  void open();
+
+  return {
+    get state() { return state; },
+    get client() { return current; },
+    get attempt() { return attempt; },
+    ready({ signal } = {}) {
+      if (state === 'open' && current) return Promise.resolve(current);
+      if (state === 'stopped') return Promise.reject(new AlpClientError('ALP connection stopped', { reason: 'closed' }));
+      return new Promise((resolve, reject) => {
+        const waiter = {
+          /** @param {AlpRpcClient} client */ resolve: client => { signal?.removeEventListener('abort', onAbort); resolve(client); },
+          /** @param {Error} error */ reject: error => { signal?.removeEventListener('abort', onAbort); reject(error); },
+        };
+        const onAbort = () => { waiters.delete(waiter); reject(new AlpClientError('Waiting for the ALP connection was aborted', { reason: 'aborted', cause: signal?.reason })); };
+        if (signal?.aborted) return onAbort();
+        waiters.add(waiter);
+        signal?.addEventListener('abort', onAbort, { once: true });
+      });
+    },
+    request(method, params, options) {
+      if (state !== 'open' || !current) return Promise.reject(new AlpClientError('ALP daemon connection closed', { reason: state === 'stopped' ? 'closed' : 'disconnected' }));
+      return current.request(method, params, options);
+    },
+    onEvent(listener) { events.add(listener); return () => events.delete(listener); },
+    onNotification(listener) { notifications.add(listener); return () => notifications.delete(listener); },
+    onState(listener) { states.add(listener); return () => states.delete(listener); },
+    stop() {
+      if (state === 'stopped') return;
+      if (timer !== undefined) { clearTimeout(timer); timer = undefined; }
+      run.abort(new AlpClientError('ALP connection stopped', { reason: 'closed' }));
+      const last = current;
+      current = undefined;
+      enter('stopped');
+      last?.close();
+      events.clear();
+      notifications.clear();
+      states.clear();
+    },
+  };
+}

package/src/rpc/timers.js

@@ -0,0 +1,16 @@
+/** The longest delay setTimeout honours; a longer one fires at once, in browsers, Node and Hermes. */
+export const MAX_TIMER_MS = 2_147_483_647;
+
+/**
+ * A timeout option as a setTimeout delay. `undefined` means no timer: no timeout given, Infinity,
+ * or a wait longer than any timer can (about 24.8 days). Anything that is not a non-negative
+ * number is a TypeError, so a typo cannot turn into an instant timeout.
+ * @param {unknown} value
+ * @param {string} [name]
+ * @returns {number | undefined}
+ */
+export function timerDelay(value, name = 'timeoutMs') {
+  if (value === undefined || value === Infinity) return undefined;
+  if (typeof value !== 'number' || Number.isNaN(value) || value < 0) throw new TypeError(`${name} must be a non-negative number of milliseconds`);
+  return value > MAX_TIMER_MS ? undefined : value;
+}

package/src/service.js

@@ -0,0 +1,154 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { runCommand } from './command.js';
+
+/**
+ * alpd as a user service (ALPD §37): a LaunchAgent on macOS, a systemd user unit on
+ * Linux. The service manager starts alpd at login and starts it again after a crash;
+ * a clean stop (`alp daemon stop`, exit 0) stays stopped until `alp daemon start`.
+ * Paths can be redirected for tests: ALP_SERVICE_DIR for the definition's directory,
+ * ALP_LAUNCHCTL and ALP_SYSTEMCTL for the managers.
+ */
+
+/** Variables alpd reads, carried into the service when the installing shell sets them. */
+const CARRIED = ['ALP_RUN_LOG_DIR', 'ALP_CODEX_BIN', 'ALP_CLAUDE_BIN', 'ALP_ANTIGRAVITY_BIN', 'ALP_GH_BIN'];
+
+const escapeXml = value => value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+const quoteUnit = value => `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+
+/**
+ * Where and how alpd for `home` is defined as a service on `platform`, or undefined
+ * where ALP has no service support. Each ALP_HOME gets its own service.
+ */
+export function serviceFor({ home, env = process.env, platform = process.platform, uid = process.getuid?.() ?? 0 }) {
+  const custom = path.resolve(home) !== path.join(os.homedir(), '.alp');
+  const suffix = custom ? createHash('sha256').update(path.resolve(home)).digest('hex').slice(0, 8) : '';
+  if (platform === 'darwin') {
+    const label = `com.alp.alpd${suffix ? `.${suffix}` : ''}`;
+    const directory = env.ALP_SERVICE_DIR || path.join(os.homedir(), 'Library', 'LaunchAgents');
+    const launchctl = env.ALP_LAUNCHCTL || 'launchctl';
+    const target = `gui/${uid}/${label}`;
+    const file = path.join(directory, `${label}.plist`);
+    return {
+      kind: 'launchd', name: label, file,
+      install: [[launchctl, ['bootout', target], { ignore: true }], [launchctl, ['bootstrap', `gui/${uid}`, file]]],
+      start: [[launchctl, ['kickstart', target]]],
+      uninstall: [[launchctl, ['bootout', target], { ignore: true }]],
+    };
+  }
+  if (platform === 'linux') {
+    const name = `alpd${suffix ? `-${suffix}` : ''}`;
+    const directory = env.ALP_SERVICE_DIR || path.join(env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'systemd', 'user');
+    const systemctl = env.ALP_SYSTEMCTL || 'systemctl';
+    return {
+      kind: 'systemd', name, file: path.join(directory, `${name}.service`),
+      install: [[systemctl, ['--user', 'daemon-reload']], [systemctl, ['--user', 'enable', '--now', `${name}.service`]]],
+      start: [[systemctl, ['--user', 'start', `${name}.service`]]],
+      uninstall: [[systemctl, ['--user', 'disable', '--now', `${name}.service`], { ignore: true }]],
+      afterUninstall: [[systemctl, ['--user', 'daemon-reload'], { ignore: true }]],
+    };
+  }
+  return undefined;
+}
+
+/** The service definition that runs `entry` with `execPath` for `home`. */
+export function serviceDefinition(service, { home, entry, execPath = process.execPath, env = process.env }) {
+  const variables = { ALP_HOME: path.resolve(home), PATH: env.PATH ?? '' };
+  for (const name of CARRIED) if (env[name]) variables[name] = env[name];
+  const program = [execPath, entry, '--service'];
+  const fatal = path.join(path.resolve(home), 'logs', 'alpd.service.log');
+  if (service.kind === 'launchd') {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${escapeXml(service.name)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${program.map(arg => `    <string>${escapeXml(arg)}</string>`).join('\n')}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+${Object.entries(variables).map(([key, value]) => `    <key>${escapeXml(key)}</key>\n    <string>${escapeXml(value)}</string>`).join('\n')}
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>Crashed</key>
+    <true/>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <key>ProcessType</key>
+  <string>Background</string>
+  <key>StandardOutPath</key>
+  <string>${escapeXml(fatal)}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(fatal)}</string>
+</dict>
+</plist>
+`;
+  }
+  return `[Unit]
+Description=ALP daemon (alpd) for ${path.resolve(home)}
+
+[Service]
+ExecStart=${program.map(quoteUnit).join(' ')}
+${Object.entries(variables).map(([key, value]) => `Environment=${quoteUnit(`${key}=${value}`)}`).join('\n')}
+Restart=on-failure
+RestartSec=10
+StandardOutput=append:${fatal}
+StandardError=append:${fatal}
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+/** The program an installed definition runs: [node, alpd.js], or undefined when it is not installed. */
+export async function installedProgram(service) {
+  const text = await readFile(service.file, 'utf8').catch(() => undefined);
+  if (text === undefined) return undefined;
+  if (service.kind === 'launchd') {
+    const array = text.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/)?.[1] ?? '';
+    const unescape = value => value.replace(/&quot;/g, '"').replace(/&gt;/g, '>').replace(/&lt;/g, '<').replace(/&amp;/g, '&');
+    return [...array.matchAll(/<string>([\s\S]*?)<\/string>/g)].map(match => unescape(match[1])).slice(0, 2);
+  }
+  const line = text.match(/^ExecStart=(.*)$/m)?.[1] ?? '';
+  return [...line.matchAll(/"((?:[^"\\]|\\.)*)"/g)].map(match => match[1].replace(/\\(.)/g, '$1')).slice(0, 2);
+}
+
+async function runAll(steps, run) {
+  for (const [command, args, { ignore = false } = {}] of steps) {
+    const result = await run(command, args);
+    if (result.code !== 0 && !ignore) throw new Error(`${command} ${args.join(' ')} failed: ${(result.stderr || result.stdout).trim() || `exit ${result.code}`}`);
+  }
+}
+
+/** Writes the definition and loads it, which starts alpd. */
+export async function installService(service, options, run = runCommand) {
+  await mkdir(path.dirname(service.file), { recursive: true });
+  await mkdir(path.join(path.resolve(options.home), 'logs'), { recursive: true, mode: 0o700 });
+  await writeFile(service.file, serviceDefinition(service, options), { mode: 0o644 });
+  await runAll(service.install, run);
+}
+
+/** Starts an installed service's alpd. */
+export async function startService(service, run = runCommand) {
+  await runAll(service.start, run);
+}
+
+/** Unloads the service, which stops its alpd, and removes the definition; false when none was installed. */
+export async function uninstallService(service, run = runCommand) {
+  if (await installedProgram(service) === undefined) return false;
+  await runAll(service.uninstall, run);
+  await unlink(service.file).catch(error => { if (error.code !== 'ENOENT') throw error; });
+  await runAll(service.afterUninstall ?? [], run);
+  return true;
+}