@opsee/cli 0.11.9

package/src/foreman/run-recipe.ts

@@ -0,0 +1,274 @@
+/**
+ * Run Recipe seam (see ../../CONTEXT.md).
+ *
+ * The per-repo Foreman config that says how to start the app in a Workspace: start command,
+ * readiness URL, and the port variable it honours, plus the commands the Gates run. It lives under
+ * the `foreman` key of the analyzer-written `.opsee/config` (yaml and its json copy), beside the
+ * analyzer's own `commands`, so the orchestrator's `OpseeConfig` round-trips it untouched.
+ *
+ * The Foreman substitutes a Worker-specific port (`{port}` in any field, or the port variable as
+ * `$PORT` / `${PORT}`), starts the app with that variable set, and waits on the readiness URL
+ * before a Verifier is launched (spec story 37).
+ */
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { parseJsonObject } from "../init/text.js";
+import { OPSEE_CONFIG_JSON, OPSEE_CONFIG_YAML, readOpseeConfigFiles, readYamlBlock } from "../opsee-config.js";
+import { PROCESS_GROUPS, stopProcessGroup } from "./process-group.js";
+import { trackLiveProcess } from "./worker-process.js";
+
+/** The deterministic checks a Gate runs after a Hand-off; each is a shell command, pass or fail by
+ * exit code. A missing command means the repo has no such Gate. */
+export interface RunRecipeGates {
+  test?: string;
+  lint?: string;
+  typecheck?: string;
+}
+
+/** Whether a Task gets browser verification after its Gates (core/verifier.ts): `auto` reads the
+ * Task's Verification section for a UI journey, `browser` verifies every Task in the browser,
+ * `none` stops every Task at its Gates. */
+export const VERIFY_MODES = ["auto", "browser", "none"] as const;
+export type VerifyMode = (typeof VERIFY_MODES)[number];
+
+export interface RunRecipe {
+  /** Shell command that serves the app; `{port}` and the port variable are substituted. */
+  start: string;
+  /** URL that answers once the app is up; `{port}` and the port variable are substituted. */
+  readinessUrl: string;
+  /** Name of the environment variable set to the port when `start` runs. */
+  portEnv: string;
+  gates: RunRecipeGates;
+  /** Absent means `auto`; `opsee init` never writes it, a human adds it to the block. */
+  verify?: VerifyMode;
+}
+
+/** The `foreman` block as it sits in `.opsee/config` (snake_case, mirroring the analyzer's keys). */
+export interface RunRecipeConfig {
+  start?: string;
+  readiness_url?: string;
+  port_env?: string;
+  gates?: RunRecipeGates;
+  verify?: VerifyMode;
+}
+
+/** The block's `verify` value, `auto` when absent; an unknown word is an error the caller names. */
+export function verifyModeOf(raw: unknown): VerifyMode {
+  if (raw === undefined || raw === null || raw === "") return "auto";
+  if (typeof raw === "string" && (VERIFY_MODES as readonly string[]).includes(raw)) return raw as VerifyMode;
+  throw new Error(`foreman.verify must be one of ${VERIFY_MODES.join(", ")}, not ${JSON.stringify(raw)}`);
+}
+
+export const RECIPE_KEY = "foreman";
+export const DEFAULT_PORT_ENV = "PORT";
+export const DEFAULT_READINESS_URL = "http://localhost:{port}/";
+
+/** Expands the port into `text`: the `{port}` placeholder, and `$VAR` / `${VAR}` for the recipe's
+ * port variable (a longer name such as `$PORTS` is a different variable and stays). */
+export function substitutePort(text: string, port: number, portEnv: string): string {
+  const name = portEnv.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return text
+    .replace(/\{port\}/g, String(port))
+    .replace(new RegExp(`\\$\\{${name}\\}`, "g"), String(port))
+    .replace(new RegExp(`\\$${name}(?![A-Za-z0-9_])`, "g"), String(port));
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+
+/** Validates a raw `foreman` block into a RunRecipe; `source` names the file for the error. */
+export function recipeFromConfig(raw: unknown, source: string): RunRecipe {
+  if (!raw || typeof raw !== "object") throw new Error(`${source} has no foreman block; run opsee init to write the Run Recipe.`);
+  const block = raw as Record<string, unknown>;
+  const start = nonEmptyString(block.start);
+  const readinessUrl = nonEmptyString(block.readiness_url);
+  if (!start) throw new Error(`${source}: foreman.start is missing; it is the command that serves the app.`);
+  if (!readinessUrl) throw new Error(`${source}: foreman.readiness_url is missing; it is the URL that answers once the app is up.`);
+  const gatesRaw = block.gates && typeof block.gates === "object" ? (block.gates as Record<string, unknown>) : {};
+  const gates: RunRecipeGates = {};
+  for (const name of ["test", "lint", "typecheck"] as const) {
+    const command = nonEmptyString(gatesRaw[name]);
+    if (command) gates[name] = command;
+  }
+  let verify: VerifyMode;
+  try {
+    verify = verifyModeOf(block.verify);
+  } catch (error) {
+    throw new Error(`${source}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  return { start, readinessUrl, portEnv: nonEmptyString(block.port_env) ?? DEFAULT_PORT_ENV, gates, ...(block.verify === undefined ? {} : { verify }) };
+}
+
+/** Resolves the Run Recipe of the repo at `root`. The JSON copy is authoritative when present
+ * (it is the analyzer's programmatic form); otherwise the `foreman` block is read from the YAML. */
+export function loadRunRecipe(root: string): RunRecipe {
+  const files = readOpseeConfigFiles(root);
+  if (files.json !== null) {
+    const parsed = parseJsonObject(files.json);
+    if ("reason" in parsed) throw new Error(`${OPSEE_CONFIG_JSON} is not valid JSON: ${parsed.reason}`);
+    return recipeFromConfig(parsed.root[RECIPE_KEY], OPSEE_CONFIG_JSON);
+  }
+  if (files.yaml === null) throw new Error(`${join(root, OPSEE_CONFIG_YAML)}: no ${OPSEE_CONFIG_YAML} here; run opsee init to write the Run Recipe.`);
+  return recipeFromConfig(readYamlBlock(files.yaml, RECIPE_KEY) ?? undefined, OPSEE_CONFIG_YAML);
+}
+
+export interface StartOptions {
+  port: number;
+  /** Working directory the start command runs in: the Workspace root. */
+  cwd: string;
+  /** Receives the app's combined stdout and stderr, line by line, when given. */
+  onOutput?: (line: string) => void;
+  /** The app's environment before the port variable is set; this process's when unset. The
+   * Verifier hands in the Gates' filtered one (core/gates.ts `gateEnv`): the start command is
+   * code from the repository and sees no credential the Foreman holds. */
+  env?: Readonly<Record<string, string>>;
+}
+
+export interface AppHandle {
+  /** The start command after port substitution: what was actually run. */
+  command: string;
+  /** The readiness URL after port substitution. */
+  readinessUrl: string;
+  pid: number | undefined;
+  /** Resolves with the exit code (null when killed by a signal) once the process is gone. */
+  exited: Promise<number | null>;
+  /** Fires when the process exits, with the reason; hand it to waitForReady so an app that dies
+   * before it is up fails the wait at once instead of at the timeout. */
+  exitSignal: AbortSignal;
+  /** SIGTERM to the whole process group, SIGKILL to whatever is still in it after `graceMs`
+   * (default 5s); resolves once the group is gone, not just the shell. Idempotent. */
+  stop: (graceMs?: number) => Promise<void>;
+}
+
+/** Starts the app described by `recipe` on `port`. The command runs through the shell (recipes
+ * are shell commands) in its own process group, so `stop` reaches the servers a `make` or `bun run`
+ * wrapper spawned underneath it. The child goes on this process's live registry
+ * (worker-process.ts `trackLiveProcess`) beside the Workers, so a Foreman that is signalled or
+ * exits stops the app with them rather than orphaning it. */
+export function startApp(recipe: RunRecipe, options: StartOptions): AppHandle {
+  const command = substitutePort(recipe.start, options.port, recipe.portEnv);
+  const readinessUrl = substitutePort(recipe.readinessUrl, options.port, recipe.portEnv);
+  const child = spawn(command, {
+    cwd: options.cwd,
+    shell: true,
+    detached: PROCESS_GROUPS,
+    env: { ...(options.env ?? process.env), [recipe.portEnv]: String(options.port) },
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  const controller = new AbortController();
+  let done = false;
+  const exited = new Promise<number | null>((resolve) => {
+    const finish = (code: number | null, reason: string) => {
+      if (done) return;
+      done = true;
+      controller.abort(new Error(reason));
+      resolve(code);
+    };
+    child.once("exit", (code, signal) => finish(code, signal ? `app exited on ${signal}` : `app exited with code ${code}`));
+    child.once("error", (error) => finish(null, `app could not start: ${error.message}`));
+  });
+  if (options.onOutput) {
+    const forward = (chunk: Buffer) => chunk.toString().split(/\r?\n/).filter(Boolean).forEach((line) => options.onOutput?.(line));
+    child.stdout?.on("data", forward);
+    child.stderr?.on("data", forward);
+  } else {
+    child.stdout?.resume();
+    child.stderr?.resume();
+  }
+  const stop = (graceMs = 5_000) => stopProcessGroup(child, exited, graceMs, () => done);
+  trackLiveProcess({ child, settled: exited, stop: () => stop() });
+  return { command, readinessUrl, pid: child.pid, exited, exitSignal: controller.signal, stop };
+}
+
+export interface WaitOptions {
+  timeoutMs: number;
+  /** First retry delay; doubles each attempt up to `maxDelayMs` (defaults 100ms and 1s). */
+  initialDelayMs?: number;
+  maxDelayMs?: number;
+  /** Aborting ends the wait early with the signal's reason (see AppHandle.exitSignal). */
+  signal?: AbortSignal;
+  /** Test seam; defaults to the global fetch. */
+  fetch?: typeof fetch;
+}
+
+export interface Readiness {
+  attempts: number;
+  elapsedMs: number;
+}
+
+/** Polls `url` with exponential backoff until it answers with anything below HTTP 500 (a 404 still
+ * means the server is up), or throws once `timeoutMs` has elapsed or `signal` fires. */
+export async function waitForReady(url: string, options: WaitOptions): Promise<Readiness> {
+  const started = Date.now();
+  const doFetch = options.fetch ?? fetch;
+  let delay = options.initialDelayMs ?? 100;
+  const maxDelay = options.maxDelayMs ?? 1_000;
+  let attempts = 0;
+  let last = "not attempted";
+  for (;;) {
+    if (options.signal?.aborted) throw abortError(options.signal, url, attempts, last);
+    attempts++;
+    try {
+      const response = await doFetch(url, { signal: requestSignal(options) });
+      if (response.status < 500) return { attempts, elapsedMs: Date.now() - started };
+      last = `HTTP ${response.status}`;
+    } catch (error) {
+      if (options.signal?.aborted) throw abortError(options.signal, url, attempts, last);
+      last = describeFetchError(error);
+    }
+    const remaining = options.timeoutMs - (Date.now() - started);
+    if (remaining <= 0) {
+      throw new Error(`${url} not ready after ${options.timeoutMs}ms (${attempts} attempts; last: ${last})`);
+    }
+    // Never sleep past the deadline: the last attempt lands at the timeout, not up to a second early.
+    await sleep(Math.min(delay, remaining), options.signal);
+    delay = Math.min(delay * 2, maxDelay);
+  }
+}
+
+/** One request's signal: a per-request timeout, and the caller's signal so an app that exits
+ * mid-request ends the request at once rather than after the request timeout. */
+function requestSignal(options: WaitOptions): AbortSignal {
+  const perRequest = Math.max(1_000, Math.min(5_000, options.timeoutMs));
+  if (!options.signal) return AbortSignal.timeout(perRequest);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(new Error(`request timed out after ${perRequest}ms`)), perRequest);
+  const onAbort = () => {
+    clearTimeout(timer);
+    controller.abort(options.signal?.reason);
+  };
+  if (options.signal.aborted) onAbort();
+  else options.signal.addEventListener("abort", onAbort, { once: true });
+  controller.signal.addEventListener("abort", () => clearTimeout(timer), { once: true });
+  return controller.signal;
+}
+
+function abortError(signal: AbortSignal, url: string, attempts: number, last: string): Error {
+  const reason = signal.reason instanceof Error ? signal.reason.message : String(signal.reason ?? "aborted");
+  return new Error(`${url}: gave up waiting, ${reason} (${attempts} attempts; last: ${last})`);
+}
+
+function describeFetchError(error: unknown): string {
+  if (error instanceof Error) {
+    const cause = (error as Error & { cause?: unknown }).cause;
+    const code = cause && typeof cause === "object" && "code" in cause ? String((cause as { code: unknown }).code) : null;
+    return code ?? error.message;
+  }
+  return String(error);
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted) return Promise.resolve();
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}

package/src/foreman/service-unit.ts

@@ -0,0 +1,257 @@
+/**
+ * The service manager's view of the daemon (story 16): a launchd LaunchAgent on macOS, a systemd
+ * user unit on Linux, each starting `opsee foreman up` at login or boot and restarting it after a
+ * crash. Pure writers: given where node, the CLI, the checkout and the state directory are, they
+ * produce the file and the commands the service manager wants, and never run anything. The unit
+ * carries no credential: the daemon reads Accounts from its store (ADR-0001), and a key-by-name
+ * Account needs its variable in the service environment, which is the developer's to add.
+ */
+import { join } from "node:path";
+
+/** The identity the service manager knows the daemon by. */
+export const LAUNCHD_LABEL = "io.opsee.foreman";
+export const SYSTEMD_UNIT = "opsee-foreman.service";
+
+/** The exit code `foreman up` leaves with when another Foreman holds the pid file (foreman-up.ts):
+ * not a crash, so systemd must not restart it (RestartPreventExitStatus). launchd cannot tell exit
+ * codes apart, so there KeepAlive retries it every ThrottleInterval until the other one stops. */
+export const EXIT_ANOTHER_FOREMAN = 3;
+
+/** How long both managers give the daemon to leave after SIGTERM, in seconds. On SIGTERM the
+ * daemon's process hooks SIGTERM every Worker it has running and SIGKILL them 5 s later
+ * (worker-process.ts KILL_GRACE_MS), and systemd's default KillMode=control-group signals the
+ * Workers at the same time anyway; the daemon then removes its pid file and leaves. The interrupted
+ * turn is resumed by session id on the next start (ADR-0009), so the budget is short: it covers
+ * the grace period, not a Worker turn. */
+export const STOP_TIMEOUT_S = 30;
+
+/** How long launchd waits before restarting the daemon after an unsuccessful exit. */
+export const RESTART_INTERVAL_S = 10;
+
+/** What both writers need to know about this machine. */
+export interface ServiceTarget {
+  /** The user's home, where the unit lives. */
+  home: string;
+  /** The node binary that runs the CLI, absolute (process.execPath). */
+  node: string;
+  /** The CLI entry the unit runs, absolute (bin/opsee.js). */
+  bin: string;
+  /** The checkout the daemon serves: the unit's working directory. */
+  repoRoot: string;
+  /** The Foreman's local state directory (local-dir.ts): where the daemon's output goes. */
+  localDir: string;
+  /** The PATH the daemon inherits; the vendors' CLIs must be on it. */
+  path: string;
+  /** Further variables the daemon inherits, after PATH and HOME: the OPSEE_* overrides set where
+   * install ran, so the daemon talks to the same backend and files. Never a credential. */
+  env?: Record<string, string>;
+  /** The user id, for the launchd domain in the printed commands; undefined where node has none. */
+  uid?: number;
+}
+
+/** One service-manager command, and the exit it may end with that is not a failure. */
+export interface ServiceCommand {
+  argv: string[];
+  /** An exit that means "nothing to do" rather than "failed": the codes, an output that says the
+   * same, and what it means, printed in place of a failure. */
+  tolerated?: { codes: number[]; output?: RegExp; means: string };
+}
+
+/** A written unit: where it goes, what it says, and how the service manager is told about it. */
+export interface ServiceUnit {
+  manager: "launchd" | "systemd";
+  path: string;
+  content: string;
+  /** Where the daemon's output goes once the service manager runs it. */
+  log: string;
+  /** Commands, in order, to load and start the unit after the file is written. A loaded copy is
+   * replaced: launchd is told to bootout before bootstrap, systemd to restart after enable, so a
+   * re-install takes effect instead of failing (bootstrap exits 5 on a loaded label) or leaving
+   * the old process running (enable --now does not restart). */
+  start: ServiceCommand[];
+  /** Commands, in order, to stop and unload the unit before the file is removed. */
+  stop: ServiceCommand[];
+  /** Notes the developer must read: what the unit does not do for them. */
+  notes: string[];
+}
+
+export function launchdPlistPath(home: string): string {
+  return join(home, "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
+}
+
+export function systemdUnitPath(home: string): string {
+  return join(home, ".config", "systemd", "user", SYSTEMD_UNIT);
+}
+
+/** Where the service manager sends the daemon's stdout and stderr (one file, so a `tail -f` shows
+ * both), beside the Process Table. */
+export function serviceLogPath(localDir: string): string {
+  return join(localDir, "foreman.log");
+}
+
+/** The extra variables in a stable order, so the file is the same for the same machine. */
+function extraEnv(target: ServiceTarget): [string, string][] {
+  return Object.entries(target.env ?? {}).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
+function xml(text: string): string {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+/** The launchd domain the agent lives in: the user's GUI session. */
+function launchdDomain(uid: number): string {
+  return `gui/${uid}`;
+}
+
+/** The LaunchAgent: RunAtLoad starts it at login, KeepAlive on an unsuccessful exit restarts it
+ * after a crash but leaves a clean stop (exit 0 on SIGTERM) down, ThrottleInterval spaces those
+ * restarts so a daemon that keeps failing (the checkout gone, another Foreman holding the pid file)
+ * is retried every 10 s instead of in a tight loop, and ExitTimeOut gives it the same shutdown
+ * budget systemd does. Everything is an absolute path: launchd runs it with no shell and a bare
+ * environment. */
+export function launchdPlist(target: ServiceTarget): string {
+  const log = serviceLogPath(target.localDir);
+  const args = [target.node, target.bin, "foreman", "up"];
+  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">',
+    `<!-- Written by "opsee foreman service install". KeepAlive restarts any unsuccessful exit, exit ${EXIT_ANOTHER_FOREMAN} (another Foreman, started from a terminal, holds the pid file) included: stop that one first, or launchd retries every ${RESTART_INTERVAL_S} s. -->`,
+    "<dict>",
+    "  <key>Label</key>",
+    `  <string>${LAUNCHD_LABEL}</string>`,
+    "  <key>ProgramArguments</key>",
+    "  <array>",
+    ...args.map((a) => `    <string>${xml(a)}</string>`),
+    "  </array>",
+    "  <key>WorkingDirectory</key>",
+    `  <string>${xml(target.repoRoot)}</string>`,
+    "  <key>RunAtLoad</key>",
+    "  <true/>",
+    "  <key>KeepAlive</key>",
+    "  <dict>",
+    "    <key>SuccessfulExit</key>",
+    "    <false/>",
+    "  </dict>",
+    "  <key>ThrottleInterval</key>",
+    `  <integer>${RESTART_INTERVAL_S}</integer>`,
+    "  <key>ExitTimeOut</key>",
+    `  <integer>${STOP_TIMEOUT_S}</integer>`,
+    "  <key>StandardOutPath</key>",
+    `  <string>${xml(log)}</string>`,
+    "  <key>StandardErrorPath</key>",
+    `  <string>${xml(log)}</string>`,
+    "  <key>EnvironmentVariables</key>",
+    "  <dict>",
+    "    <key>PATH</key>",
+    `    <string>${xml(target.path)}</string>`,
+    "    <key>HOME</key>",
+    `    <string>${xml(target.home)}</string>`,
+    ...extraEnv(target).flatMap(([key, value]) => [`    <key>${xml(key)}</key>`, `    <string>${xml(value)}</string>`]),
+    "  </dict>",
+    "</dict>",
+    "</plist>",
+    "",
+  ].join("\n");
+}
+
+/** A value systemd reads literally: `%` is a specifier (`%h`, `%i`) in Environment=, ExecStart=
+ * and WorkingDirectory=, so it is doubled. */
+function unitLiteral(text: string): string {
+  return text.replace(/%/g, "%%");
+}
+
+/** One word of a systemd command line or Environment= assignment: `%` doubled, then quoted the
+ * way systemd's word splitter reads it (double quotes, with a backslash and the quote escaped).
+ * Not for WorkingDirectory=, which takes one path and does not strip quotes. */
+function unitQuote(text: string): string {
+  return `"${unitLiteral(text).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+/** The user unit: Restart=on-failure restarts a crash and leaves a clean stop down, exit 3 (another
+ * Foreman holds the pid file) is not retried, and default.target starts it with the user's
+ * session. The session only exists at boot when lingering is on; that is a note, not the unit's.
+ * No network ordering: network-online.target is a system target and a no-op in the user manager;
+ * the daemon retries the backend on its own each tick. */
+export function systemdUnit(target: ServiceTarget): string {
+  return [
+    "[Unit]",
+    "Description=Opsee Foreman daemon (opsee foreman up)",
+    "",
+    "[Service]",
+    "Type=simple",
+    `WorkingDirectory=${unitLiteral(target.repoRoot)}`,
+    `ExecStart=${unitQuote(target.node)} ${unitQuote(target.bin)} foreman up`,
+    "Restart=on-failure",
+    "RestartSec=10",
+    // Another Foreman (started from a terminal) holds the pid file: not a crash, so no restart.
+    `RestartPreventExitStatus=${EXIT_ANOTHER_FOREMAN}`,
+    "KillSignal=SIGTERM",
+    // The daemon stops its Workers (SIGTERM, SIGKILL after 5 s) and leaves; the turn is resumed by
+    // session on the next start, so the budget covers the grace period, not a Worker turn.
+    `TimeoutStopSec=${STOP_TIMEOUT_S}`,
+    `Environment=${unitQuote(`PATH=${target.path}`)}`,
+    `Environment=${unitQuote(`HOME=${target.home}`)}`,
+    ...extraEnv(target).map(([key, value]) => `Environment=${unitQuote(`${key}=${value}`)}`),
+    "",
+    "[Install]",
+    "WantedBy=default.target",
+    "",
+  ].join("\n");
+}
+
+/** One command as a shell line, for printing: an argument with a space or a quote is quoted. */
+export function shellLine(argv: string[]): string {
+  return argv.map((a) => (/[\s"'$`\\]/.test(a) ? `'${a.replace(/'/g, "'\\''")}'` : a)).join(" ");
+}
+
+/** The unit for this platform, or undefined where no service manager is supported. On darwin the
+ * user id is required: the launchd domain is `gui/<uid>`, and a command line with a placeholder in
+ * it would be run as written, not through a shell. */
+export function serviceUnitFor(platform: NodeJS.Platform, target: ServiceTarget): ServiceUnit | undefined {
+  const log = serviceLogPath(target.localDir);
+  if (platform === "darwin") {
+    if (target.uid === undefined) throw new Error("launchd needs the user id for its gui/<uid> domain, and this node reports none (process.getuid)");
+    const path = launchdPlistPath(target.home);
+    const domain = launchdDomain(target.uid);
+    const service = `${domain}/${LAUNCHD_LABEL}`;
+    return {
+      manager: "launchd",
+      path,
+      content: launchdPlist(target),
+      log,
+      start: [
+        // bootstrap fails (exit 5) on a label that is already loaded and launchd keeps the old plist;
+        // unload first, tolerating "not loaded".
+        { argv: ["launchctl", "bootout", service], tolerated: { codes: [3, 5], output: /No such process/, means: "was not loaded" } },
+        { argv: ["launchctl", "bootstrap", domain, path] },
+      ],
+      stop: [{ argv: ["launchctl", "bootout", service], tolerated: { codes: [3], output: /No such process/, means: "was not loaded" } }],
+      notes: [
+        `launchd starts it at login and after a crash; a clean stop (launchctl bootout, or a SIGTERM) leaves it down until the next login or: launchctl kickstart -k ${service}`,
+        `KeepAlive also restarts exit ${EXIT_ANOTHER_FOREMAN} (a Foreman started from a terminal holds the pid file), every ${RESTART_INTERVAL_S} s until that one is stopped; stop it before loading the unit.`,
+        `Output: ${log}`,
+      ],
+    };
+  }
+  if (platform === "linux") {
+    return {
+      manager: "systemd",
+      path: systemdUnitPath(target.home),
+      content: systemdUnit(target),
+      log: "journalctl --user -u opsee-foreman -f",
+      start: [
+        { argv: ["systemctl", "--user", "daemon-reload"] },
+        { argv: ["systemctl", "--user", "enable", SYSTEMD_UNIT] },
+        // restart, not enable --now: a running unit is replaced by the one just written.
+        { argv: ["systemctl", "--user", "restart", SYSTEMD_UNIT] },
+      ],
+      stop: [{ argv: ["systemctl", "--user", "disable", "--now", SYSTEMD_UNIT] }],
+      notes: [
+        "A user unit only runs while you have a session; for it to start at boot and survive logout, enable lingering once: loginctl enable-linger $USER",
+        "Output: journalctl --user -u opsee-foreman -f",
+      ],
+    };
+  }
+  return undefined;
+}