@mnstry/atelier 0.2.0-alpha.11 → 0.2.0-alpha.13

package/src/runtime/obsidian/service-main.mjs

@@ -3,70 +3,160 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { firstString, parseArgs, resolveProjectConfig } from '../../project/config.mjs'
-import { runMaintenanceService } from './service.mjs'
+import { workspaceStateRoot } from './machine-settings.mjs'
+import { RELEASE_CHANGED, resolveServiceWorkspace, runMaintenanceService } from './service.mjs'
 
 // The process of the maintenance service. `start` runs it as a child; a unit
 // installed at the operating-system level runs it with `--startup`.
 //
 //   --project=<absolute atelier.project.json>   required
 //   --data-root=<absolute directory>            optional; otherwise the pointer, the overlay or the platform default
+//   --workspace-id=<identifier>                 named by a login item: under `--startup`, where a refusal is recorded
+//                                               when the project no longer leads to a workspace
 //   --runtime-id=<identifier>                   given by `start`, so it can recognise the child it created
 //   --interval-ms=<milliseconds>                optional
-//   --startup                                   run by an operating-system unit; needs a consent that covers startup
+//   --startup                                   run by a login item; needs a consent that covers startup
 //   --adapter=obsidian-cli                      the editor adapter; there is no default
 //
 // Without `--adapter` the process refuses before it listens or ticks: reaching
 // a running app is a decision of whoever starts the service, never a default.
+//
+// Exit codes: 0 after a clean stop, and under `--startup` after a refusal too;
+// 2 (EXIT_REFUSED) after a refusal otherwise; 75 (EXIT_RELEASE_CHANGED) under
+// `--startup` once the package changed on disk; 1 after an error without a
+// code. A refusal is any error that carries a string code, Node's system
+// errors (EACCES, EADDRNOTAVAIL, EPERM) included.
 
 // Reaching a real app happens here and nowhere else in the service: the
 // production probe and the CLI transport are imported only once `--adapter`
 // selected them. The editor adapter is constructed only for an app that meets
 // the minimum version; below it, or when the version cannot be read, the
 // factory refuses, the engine records that reason and nothing is published.
-// An adapter qualified while no app ran carries that qualification and does
-// not coordinate with an app that starts before the next qualification.
+// The app is asked for its version only when a view is published, without
+// blocking the service. An adapter qualified while no app ran carries that
+// qualification and does not coordinate with an app that starts before the
+// next qualification. The engine is told what the app looks like from the
+// process table and the app's vault list alone (whether it runs, which vaults
+// its list shows open), so a view that did not settle is tried again as soon
+// as that changes, and the app is not asked anything to find out; the list is
+// only read here.
 const ADAPTERS = Object.freeze({
   'obsidian-cli': async () => {
-    const [{ createObsidianCliAdapter }, { createProductionAppProbe }, { createQualifiedAdapterFactory }] = await Promise.all([
+    const [{ createObsidianCliAdapter, defaultObsidianProcessProbe }, { createProductionAppProbe }, { createQualifiedAdapterFactory }, { obsidianSandboxedBuild, obsidianUserDataDir, readObsidianSettings }, { appStateSignature }, { readAppVaultListForAllocation }, { createProductionUnheldEvidence }] = await Promise.all([
       import('../../projection/obsidian/publication/transport.mjs'), import('./app-production-seams.mjs'), import('./app-capability.mjs'),
+      import('../../projection/obsidian/publication/vault-list.mjs'), import('./app-registration.mjs'), import('./vault-location.mjs'), import('./unheld-evidence.mjs'),
     ])
     const adapterFactory = createQualifiedAdapterFactory({ appProbe: createProductionAppProbe(), createAdapter: ({ qualification }) => createObsidianCliAdapter({ qualification }) })
-    return { adapterFactory, appStatus: () => { const known = adapterFactory.lastQualification(); return known === null ? null : { outcome: known.outcome, reason: known.reason, version: known.version, floor: known.floor } } }
+    const userDataDir = obsidianUserDataDir()
+    const observeApp = () => appStateSignature({ processes: defaultObsidianProcessProbe(), settings: userDataDir === null ? null : readObsidianSettings({ userDataDir }) })
+    // The app's own vault list, read from its file and never written, so a new vault's folder is never allocated inside
+    // a vault it lists nor under a name one of its vaults has; a list that cannot be read allocates nothing.
+    const readAppVaultList = () => readAppVaultListForAllocation({
+      read: () => (userDataDir === null ? { ok: false, code: 'obsidian-settings-location-unknown' } : readObsidianSettings({ userDataDir })),
+      sandboxed: obsidianSandboxedBuild() !== null,
+    })
+    return {
+      // The same file tells the publisher whether a view's first publication may go into a vault no Obsidian lists yet.
+      adapterFactory, engineOptions: { observeApp, readAppVaultList, readUnheldEvidence: createProductionUnheldEvidence() },
+      appStatus: () => { const known = adapterFactory.lastQualification(); return known === null ? null : { outcome: known.outcome, reason: known.reason, version: known.version, floor: known.floor } },
+    }
   },
 })
 
+// What the tests read: which reader each adapter hands its engine. Calling one builds the production seams, and
+// reaches no app and no file until the engine uses them.
+export { ADAPTERS as SERVICE_ADAPTERS }
+
+import { createReleaseWatch, packageRootOfEntry } from './release-watch.mjs'
 import { SERVICE_ENTRY_PATH } from './service-entry-path.mjs'
+import { LAST_STARTUP_SCHEMA, openServiceLog, writeLastStartup } from './service-record.mjs'
 
 export { SERVICE_ENTRY_PATH }
 export const EXIT_REFUSED = 2
+// A service a login item started exits with this code when the package it runs from changed on disk: its service
+// manager restarts it (a non-zero exit), on the release now installed. EX_TEMPFAIL.
+export const EXIT_RELEASE_CHANGED = 75
 
-const log = (entry) => { try { process.stdout.write(`${JSON.stringify(entry)}\n`) } catch { /* a closed log never ends the service */ } }
+const printed = (entry) => { try { process.stdout.write(`${JSON.stringify(entry)}\n`) } catch { /* a closed log never ends the service */ } }
+
+// The workspace of a service a login item started, when it can be found: where it keeps its log and records how its
+// start ended. When the project no longer leads to one (it moved, its pointer is gone), the workspace the unit names by
+// its data root and identity, if that exists; it is never created here. Null otherwise; a refusal is then printed
+// only, into the unit's own output file.
+function startupWorkspace({ loadProject, dataRoot, workspaceId, env = process.env, platform = process.platform }) {
+  try {
+    const workspace = resolveServiceWorkspace({ project: loadProject(), dataRoot, env, platform })
+    if (workspace?.workspaceRoot) return workspace
+  } catch { /* the workspace the unit names, below */ }
+  if (typeof dataRoot !== 'string' || !path.isAbsolute(dataRoot) || typeof workspaceId !== 'string') return null
+  try {
+    const root = workspaceStateRoot(path.resolve(dataRoot), workspaceId)
+    return fs.lstatSync(root).isDirectory() ? { workspaceId, workspaceRoot: fs.realpathSync(root) } : null
+  } catch { return null }
+}
+
+// The service's own log, bounded as under `start`, which hands a child that same file. Under a login item the output
+// goes to the unit's file instead, which nothing bounds; it keeps only what happens before this log is open.
+function workspaceLog(workspaceRoot) {
+  let descriptor
+  try { descriptor = openServiceLog(workspaceRoot).descriptor } catch { return printed }
+  return (entry) => { try { fs.writeSync(descriptor, `${JSON.stringify(entry)}\n`) } catch { /* a closed log never ends the service */ } }
+}
+
+function recordStartup(workspace, { at, outcome, code }) {
+  if (workspace === null) return
+  try { writeLastStartup({ ...workspace, document: { schema: LAST_STARTUP_SCHEMA, workspaceId: workspace.workspaceId, at, outcome, code } }) } catch { /* reported by the log only */ }
+}
 
 // The common body of a service process: run, end cleanly on a signal, exit 0
 // after a clean stop and EXIT_REFUSED when the service refused to run.
+//
+// Started by a login item (`startup`), it logs into its workspace's bounded
+// service log, records how the start ended (`last-startup.json`), exits 0 on
+// a refusal as well, so the service manager does not start it again every
+// minute over something that does not change by itself, and exits
+// EXIT_RELEASE_CHANGED after the tick that found another release on disk.
+// Anything else that ends it (an error nobody typed, a signal) is a crash,
+// and the manager restarts it after its throttle.
 export async function runServiceProcess(options) {
+  const startup = options.startup === true
+  const workspace = startup ? startupWorkspace(options) : null
+  const log = workspace === null ? printed : workspaceLog(workspace.workspaceRoot)
   try {
-    const service = await runMaintenanceService({ log, ...options })
+    const service = await runMaintenanceService({ log, invokedAs: process.argv[1], ...options })
+    if (startup) recordStartup(workspace, { at: new Date().toISOString(), outcome: 'started', code: null })
     for (const signal of ['SIGTERM', 'SIGINT']) process.on(signal, () => { void service.shutdown(`signal-${signal}`) })
-    await service.done
+    const { reason } = await service.done
     // Everything durable is on disk by now; nothing left over may keep a stopped service's PID alive.
-    process.exit(0)
+    process.exit(reason === RELEASE_CHANGED ? EXIT_RELEASE_CHANGED : 0)
   } catch (error) {
-    log({ at: new Date().toISOString(), event: 'refused', code: error?.code ?? 'untyped-error', message: String(error?.message ?? error) })
-    process.exitCode = typeof error?.code === 'string' ? EXIT_REFUSED : 1
+    const at = new Date().toISOString()
+    const code = typeof error?.code === 'string' ? error.code : null
+    log({ at, event: 'refused', code: code ?? 'untyped-error', message: String(error?.message ?? error) })
+    if (startup && code !== null) { recordStartup(workspace, { at, outcome: 'refused', code }); process.exitCode = 0; return }
+    process.exitCode = code !== null ? EXIT_REFUSED : 1
   }
 }
 
+// The release a service a login item started runs, read through the path it was started by (`argv[1]`), so an
+// upgrade, or a linked install pointed elsewhere, is seen. Null when that package cannot be read.
+function watchRelease(invokedAs) {
+  const root = packageRootOfEntry(invokedAs) ?? packageRootOfEntry(SERVICE_ENTRY_PATH)
+  if (root === null) return null
+  try { return createReleaseWatch({ root }) } catch { return null }
+}
+
 export function serviceOptionsFromArgv(argv, { env = process.env } = {}) {
   const args = parseArgs(argv)
   const configPath = firstString(args.project)
   if (!configPath || !path.isAbsolute(configPath)) throw Object.assign(new Error('--project must be the absolute path of a project configuration'), { code: 'service-arguments-invalid' })
   const dataRoot = firstString(args['data-root']) ?? undefined
+  const workspaceId = firstString(args['workspace-id']) ?? undefined
   const intervalMs = args['interval-ms'] === undefined ? undefined : Number(args['interval-ms'])
   if (intervalMs !== undefined && (!Number.isInteger(intervalMs) || intervalMs < 1)) throw Object.assign(new Error('--interval-ms must be a positive integer'), { code: 'service-arguments-invalid' })
   return {
     loadProject: () => resolveProjectConfig({ argv: [`--project=${configPath}`], cwd: path.dirname(configPath), env, writeLocalState: false }),
-    ...(dataRoot === undefined ? {} : { dataRoot }), ...(intervalMs === undefined ? {} : { intervalMs }),
+    ...(dataRoot === undefined ? {} : { dataRoot }), ...(workspaceId === undefined ? {} : { workspaceId }), ...(intervalMs === undefined ? {} : { intervalMs }),
     ...(firstString(args['runtime-id']) ? { runtimeId: firstString(args['runtime-id']) } : {}),
     startup: args.startup === true, adapter: firstString(args.adapter),
   }
@@ -75,19 +165,25 @@ export function serviceOptionsFromArgv(argv, { env = process.env } = {}) {
 const invokedDirectly = (() => { try { return Boolean(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)) } catch { return false } })()
 
 if (invokedDirectly) {
+  const argv = process.argv.slice(2)
+  // As early as this entry can: its static imports have already loaded most of the modules, so a release that changes
+  // between this process's start and this reading is not noticed until the next change (docs/obsidian.md says so).
+  const releaseWatch = argv.includes('--startup') ? watchRelease(process.argv[1]) : null
   let options = null
   try {
-    options = serviceOptionsFromArgv(process.argv.slice(2))
+    options = serviceOptionsFromArgv(argv)
     if (!options.adapter || !Object.hasOwn(ADAPTERS, options.adapter)) throw Object.assign(new Error('no editor adapter was selected; pass --adapter explicitly'), { code: 'service-adapter-not-selected' })
   } catch (error) {
-    log({ at: new Date().toISOString(), event: 'refused', code: error.code ?? 'untyped-error', message: error.message })
-    process.exitCode = EXIT_REFUSED
+    printed({ at: new Date().toISOString(), event: 'refused', code: error.code ?? 'untyped-error', message: error.message })
+    // Under a login item arguments that do not work never will: it ends cleanly, and is not started again every minute.
+    process.exitCode = argv.includes('--startup') ? 0 : EXIT_REFUSED
     options = null
   }
   if (options) {
     const { adapter, ...rest } = options
     const [{ loadContributions }, { createObsidianRegistry }] = await Promise.all([import('./contributions.mjs'), import('./extension-points.mjs')])
     const registry = createObsidianRegistry({ contributions: await loadContributions() })
-    await runServiceProcess({ ...rest, entryPath: SERVICE_ENTRY_PATH, ...(await ADAPTERS[adapter]()), engineOptions: { extensions: registry.extensions } })
+    const { engineOptions, ...seams } = await ADAPTERS[adapter]()
+    await runServiceProcess({ ...rest, entryPath: SERVICE_ENTRY_PATH, ...seams, engineOptions: { ...engineOptions, extensions: registry.extensions }, releaseWatch })
   }
 }

package/src/runtime/obsidian/service-manager-production.mjs

@@ -0,0 +1,61 @@
+import { execFile } from 'node:child_process'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { refuse } from './errors.mjs'
+import { createLaunchdManager, createSystemdManager, homeIsAccountHome } from './service-managers.mjs'
+
+// The production service manager of a login item: the only code that runs
+// launchctl or systemctl, or writes into ~/Library/LaunchAgents or the user's
+// systemd folder.
+//
+// It is imported in exactly one place, dynamically: the command entry
+// (src/commands/obsidian.mjs), only when it runs as the real command-line
+// entry. Importing it leaves a trace below that the test suite asserts is
+// absent. It refuses, before anything is looked up or run:
+//
+//   - under the Node test runner (`real-login-item-under-test`), whatever
+//     environment it is handed: a test hands in its own manager;
+//   - when HOME is not the account's own home directory
+//     (`login-item-home-mismatch`): launchd and systemd register a unit in
+//     the account's real session whatever HOME says, so a private HOME must
+//     never install one;
+//   - on Windows (`startup-platform-unqualified`) and on any platform but
+//     macOS and Linux (`startup-platform-unsupported`).
+globalThis[Symbol.for('mnstry.atelier.obsidian.production-service-manager-loaded')] = true
+
+const RUN_TIMEOUT_MS = 15 * 1000
+const SYSTEMCTL = ['/usr/bin/systemctl', '/bin/systemctl']
+
+// No shell, in the root directory, bounded.
+function runner(env) {
+  return (program, args) => new Promise((resolve) => {
+    execFile(program, args, { env, cwd: '/', timeout: RUN_TIMEOUT_MS, killSignal: 'SIGKILL', encoding: 'utf8', maxBuffer: 1024 * 1024, windowsHide: true }, (error, stdout, stderr) => {
+      resolve({ status: error ? (typeof error.code === 'number' ? error.code : null) : 0, stdout: String(stdout ?? ''), stderr: String(stderr ?? '') })
+    })
+  })
+}
+
+export function createProductionServiceManager({ platform = process.platform, env = process.env } = {}) {
+  if (process.env.NODE_TEST_CONTEXT !== undefined || env.NODE_TEST_CONTEXT !== undefined) refuse('real-login-item-under-test', 'the production login-item manager is never used under the test runner; a test hands in its own')
+  if (platform === 'win32') refuse('startup-platform-unqualified', 'operating-system startup on Windows has not been qualified', { platform })
+  if (platform !== 'darwin' && platform !== 'linux') refuse('startup-platform-unsupported', 'no login item is known for this platform', { platform: String(platform) })
+  const account = os.userInfo()
+  if (!homeIsAccountHome({ env, accountHome: account.homedir })) refuse('login-item-home-mismatch', 'HOME is not this account\'s home directory; a login item is registered in the account\'s real session whatever HOME says, so none is installed from here')
+  const run = runner(env)
+  if (platform === 'darwin') return createLaunchdManager({ run, uid: account.uid, directory: path.join(account.homedir, 'Library', 'LaunchAgents') })
+  const configHome = typeof env.XDG_CONFIG_HOME === 'string' && path.isAbsolute(env.XDG_CONFIG_HOME) ? env.XDG_CONFIG_HOME : path.join(account.homedir, '.config')
+  const systemctl = SYSTEMCTL.find((candidate) => { try { return fs.statSync(candidate).isFile() } catch { return false } })
+  if (systemctl === undefined) return unavailableManager({ directory: path.join(configHome, 'systemd', 'user') })
+  return createSystemdManager({ run, systemctl, directory: path.join(configHome, 'systemd', 'user') })
+}
+
+// Linux without systemctl: every change answers `login-item-unavailable`, and nothing is written.
+function unavailableManager({ directory }) {
+  const unavailable = async () => ({ ok: false, code: 'login-item-unavailable', status: null, message: 'systemctl was not found' })
+  return {
+    kind: 'systemd-user-unit', platform: 'linux', directory, fileFor: (fileName) => path.join(directory, fileName),
+    readUnit: () => null, install: unavailable, start: unavailable, remove: async () => ({ ok: true, removed: false }),
+    inspect: async ({ fileName }) => ({ ok: true, file: path.join(directory, fileName), present: false, loaded: null, running: null, pid: null, lastExit: null, disabled: null }),
+  }
+}

package/src/runtime/obsidian/service-managers.mjs

@@ -0,0 +1,275 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { atomicReplacePrivateText, readRegularTextNoFollow } from '../../project/private-state.mjs'
+
+// The operating system's service managers, as a login item uses them: a
+// launchd user agent on macOS and a systemd user unit on Linux.
+//
+// Each is built from the directory its unit files live in and `run`, the only
+// way it starts a program: `run(program, args)` resolves { status, stdout,
+// stderr }, with a null status when the program could not be run at all.
+// Neither has a default here. The production ones are made only by the real
+// command-line entry, through the production manager module, never under the
+// test runner and never for a HOME that is not the account's own; tests hand
+// in a `run` that records what it was asked and a temporary directory.
+//
+// What each does, in order:
+//
+//   launchd  install  write the property list (mode 0644, atomically); boot
+//                     the job out if it is loaded, because a loaded job keeps
+//                     the definition it was loaded with, and wait until
+//                     launchd has let it go; bootstrap it (RunAtLoad starts it);
+//                     a file written where none was is removed again when
+//                     launchd did not take it
+//            start    kickstart -p: starts the job when it is not running and
+//                     prints its PID either way
+//            remove   bootout; delete the file
+//            inspect  print (loaded, state, PID, last exit code) and
+//                     print-disabled (switched off in System Settings)
+//   systemd  install  write the unit (mode 0644, atomically); daemon-reload;
+//                     enable
+//            start    start
+//            remove   disable --now; delete the file; daemon-reload
+//            inspect  show LoadState, ActiveState, SubState, UnitFileState,
+//                     MainPID, ExecMainStatus
+//
+// Every answer is { ok: true, ... } or { ok: false, code, status, message }
+// with one of these codes:
+//
+//   login-item-unavailable     no manager to install into (no systemd user
+//                              instance: WSL, a container, no session bus)
+//   login-item-install-failed  the manager refused the unit
+//   login-item-not-loaded      a start of a job the manager does not have
+//                              loaded (booted out, or not allowed to run)
+//   login-item-start-failed    the manager did not start it for another reason
+//   login-item-remove-failed   the manager did not let the job go
+//   login-item-file-unsafe     the unit's file is a link or not a regular file
+//
+// The exit statuses and texts of launchctl and systemctl read here are the
+// documented ones; they are exercised against recorded texts, never against
+// this machine's own session.
+
+export const SERVICE_MANAGER_KINDS = Object.freeze(['launchd-user-agent', 'systemd-user-unit'])
+export const LAUNCHCTL = '/bin/launchctl'
+const UNIT_FILE_MODE = 0o644
+const LABEL = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
+// launchctl: the service is not in the domain (print, kickstart), and the job was not loaded (bootout).
+const LAUNCHD_NOT_FOUND = [113, 3]
+const BOOTOUT_WAIT_MS = 10 * 1000
+const BOOTOUT_POLL_MS = 100
+
+// Whether HOME names the account's own home directory (`accountHome`, as the system records it). A login item is
+// registered in the account's real session whatever HOME says, so only then is one installed.
+export function homeIsAccountHome({ env, accountHome }) {
+  const home = env?.HOME
+  if (typeof home !== 'string' || !path.isAbsolute(home) || typeof accountHome !== 'string' || !path.isAbsolute(accountHome)) return false
+  if (path.resolve(home) === path.resolve(accountHome)) return true
+  try { return fs.realpathSync(home) === fs.realpathSync(accountHome) } catch { return false }
+}
+
+const failed = (code, answer, message) => ({ ok: false, code, status: answer?.status ?? null, message: message ?? firstLine(answer) })
+// The first line of what a manager printed, bounded: never a whole output, which can carry an environment.
+function firstLine(answer) {
+  const text = `${answer?.stderr ?? ''}\n${answer?.stdout ?? ''}`.split('\n').map((line) => line.trim()).find((line) => line !== '')
+  return text === undefined ? null : text.slice(0, 200)
+}
+const sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms) })
+
+function checkUnit({ label, fileName }) {
+  if (typeof label !== 'string' || !LABEL.test(label)) throw new TypeError('a login item has a plain label')
+  if (typeof fileName !== 'string' || fileName !== path.basename(fileName) || !fileName.startsWith(label)) throw new TypeError('a unit file name is the label and its suffix')
+}
+
+// The unit's file, owned by this module: written atomically with the mode a manager accepts (neither launchd nor
+// systemd reads a unit anyone else can write), never through a link.
+function unitFiles(directory) {
+  if (typeof directory !== 'string' || !path.isAbsolute(directory)) throw new TypeError('a service manager needs the absolute directory of its unit files')
+  const fileFor = (fileName) => path.join(directory, fileName)
+  return {
+    directory,
+    fileFor,
+    read(fileName) {
+      try { return readRegularTextNoFollow(fileFor(fileName)) } catch (error) {
+        if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null
+        return undefined
+      }
+    },
+    write(fileName, text) {
+      try {
+        fs.mkdirSync(directory, { recursive: true, mode: 0o700 })
+        atomicReplacePrivateText(fileFor(fileName), text, UNIT_FILE_MODE)
+        return { ok: true }
+      } catch (error) {
+        return { ok: false, code: error?.code === undefined || /regular file|redirected/.test(String(error.message)) ? 'login-item-file-unsafe' : 'login-item-install-failed', status: null, message: String(error.code ?? 'not-written') }
+      }
+    },
+    remove(fileName) {
+      let before
+      try { before = fs.lstatSync(fileFor(fileName)) } catch (error) { if (error.code === 'ENOENT') return { ok: true, removed: false }; return { ok: false, code: 'login-item-remove-failed', status: null, message: String(error.code) } }
+      if (!before.isFile()) return { ok: false, code: 'login-item-file-unsafe', status: null, message: 'not a regular file' }
+      try { fs.unlinkSync(fileFor(fileName)); return { ok: true, removed: true } } catch (error) {
+        return error.code === 'ENOENT' ? { ok: true, removed: false } : { ok: false, code: 'login-item-remove-failed', status: null, message: String(error.code) }
+      }
+    },
+    present(fileName) { try { return fs.lstatSync(fileFor(fileName)).isFile() } catch { return false } },
+  }
+}
+
+// Pure. What `launchctl print <domain>/<label>` says about one job.
+export function readLaunchdPrint(text) {
+  const value = (name) => { const match = new RegExp(`^\\s*${name} = (.+)$`, 'm').exec(String(text ?? '')); return match === null ? null : match[1].trim() }
+  const pid = Number(value('pid'))
+  const exit = Number(value('last exit code'))
+  return { state: value('state'), pid: Number.isSafeInteger(pid) && pid > 0 ? pid : null, lastExit: Number.isInteger(exit) ? exit : null }
+}
+
+// Pure. Whether `launchctl print-disabled <domain>` lists this label as disabled: true, false, or null when it is not
+// listed. Releases of macOS print `=> disabled` / `=> enabled`, earlier ones `=> true` / `=> false`.
+export function readLaunchdDisabled(text, label) {
+  for (const line of String(text ?? '').split('\n')) {
+    const match = /^\s*"([^"]+)"\s*=>\s*(\S+)\s*$/.exec(line)
+    if (match === null || match[1] !== label) continue
+    if (match[2] === 'disabled' || match[2] === 'true') return true
+    if (match[2] === 'enabled' || match[2] === 'false') return false
+  }
+  return null
+}
+
+export function createLaunchdManager({ run, uid, directory, waitMs = BOOTOUT_WAIT_MS, pollMs = BOOTOUT_POLL_MS } = {}) {
+  if (typeof run !== 'function') throw new TypeError('a service manager needs run')
+  if (!Number.isSafeInteger(uid) || uid < 0) throw new TypeError('a launchd manager needs the user id of its session')
+  const files = unitFiles(directory)
+  const domain = `gui/${uid}`
+  const target = (label) => `${domain}/${label}`
+  const launchctl = (...args) => run(LAUNCHCTL, args)
+  const loaded = async (label) => {
+    const answer = await launchctl('print', target(label))
+    return answer.status === 0 ? { loaded: true, answer } : { loaded: LAUNCHD_NOT_FOUND.includes(answer.status) ? false : null, answer }
+  }
+  // Boots the job out when launchd has it, and waits, bounded, until it is gone: bootstrap refuses a label still loaded.
+  async function bootout(label) {
+    const answer = await launchctl('bootout', target(label))
+    if (answer.status !== 0 && !LAUNCHD_NOT_FOUND.includes(answer.status)) return failed('login-item-remove-failed', answer)
+    const until = Date.now() + waitMs
+    for (;;) {
+      const now = await loaded(label)
+      if (now.loaded === false) return { ok: true, wasLoaded: answer.status === 0 }
+      if (Date.now() >= until) return failed('login-item-remove-failed', now.answer, 'launchd kept the job loaded')
+      await sleep(pollMs)
+    }
+  }
+  return {
+    kind: 'launchd-user-agent', platform: 'darwin', directory: files.directory, fileFor: files.fileFor,
+    readUnit({ label, fileName }) { checkUnit({ label, fileName }); return files.read(fileName) },
+    async install({ label, fileName, text }) {
+      checkUnit({ label, fileName })
+      // launchd loads every property list in LaunchAgents at login: one this installation wrote where none was is
+      // removed again when launchd did not take it.
+      const existed = files.present(fileName)
+      const written = files.write(fileName, text)
+      if (!written.ok) return written
+      const out = await bootout(label)
+      if (!out.ok) { if (!existed) files.remove(fileName); return out }
+      const answer = await launchctl('bootstrap', domain, files.fileFor(fileName))
+      if (answer.status !== 0) {
+        if (!existed) files.remove(fileName)
+        return failed(answer.status === null ? 'login-item-unavailable' : 'login-item-install-failed', answer)
+      }
+      return { ok: true, file: files.fileFor(fileName) }
+    },
+    async start({ label, fileName }) {
+      checkUnit({ label, fileName })
+      const answer = await launchctl('kickstart', '-p', target(label))
+      if (answer.status === 0) { const pid = Number(String(answer.stdout ?? '').trim()); return { ok: true, pid: Number.isSafeInteger(pid) && pid > 0 ? pid : null } }
+      return failed(LAUNCHD_NOT_FOUND.includes(answer.status) ? 'login-item-not-loaded' : 'login-item-start-failed', answer)
+    },
+    async remove({ label, fileName }) {
+      checkUnit({ label, fileName })
+      const out = await bootout(label)
+      if (!out.ok) return out
+      const removed = files.remove(fileName)
+      return removed.ok ? { ok: true, removed: removed.removed || out.wasLoaded } : removed
+    },
+    async inspect({ label, fileName }) {
+      checkUnit({ label, fileName })
+      const present = files.present(fileName)
+      const printed = await loaded(label)
+      const disabled = await launchctl('print-disabled', domain)
+      const job = printed.loaded === true ? readLaunchdPrint(printed.answer.stdout) : { state: null, pid: null, lastExit: null }
+      return {
+        ok: true, file: files.fileFor(fileName), present, loaded: printed.loaded, running: printed.loaded === true ? job.state === 'running' : printed.loaded === false ? false : null,
+        pid: job.pid, lastExit: job.lastExit, disabled: disabled.status === 0 ? readLaunchdDisabled(disabled.stdout, label) === true : null,
+      }
+    },
+  }
+}
+
+// Pure. The `KEY=value` lines of `systemctl show`.
+export function readSystemdShow(text) {
+  const values = {}
+  for (const line of String(text ?? '').split('\n')) {
+    const at = line.indexOf('=')
+    if (at > 0) values[line.slice(0, at).trim()] = line.slice(at + 1).trim()
+  }
+  const pid = Number(values.MainPID)
+  const exit = Number(values.ExecMainStatus)
+  return {
+    loadState: values.LoadState ?? null, activeState: values.ActiveState ?? null, subState: values.SubState ?? null, unitFileState: values.UnitFileState ?? null,
+    pid: Number.isSafeInteger(pid) && pid > 0 ? pid : null, lastExit: values.ExecMainStatus === undefined || !Number.isInteger(exit) ? null : exit,
+  }
+}
+
+export function createSystemdManager({ run, systemctl, directory } = {}) {
+  if (typeof run !== 'function') throw new TypeError('a service manager needs run')
+  if (typeof systemctl !== 'string' || !path.isAbsolute(systemctl)) throw new TypeError('a systemd manager needs the absolute path of systemctl')
+  const files = unitFiles(directory)
+  const user = (...args) => run(systemctl, ['--user', ...args])
+  // A user instance that cannot be reached (no session bus: WSL, a container, a session without systemd) makes the
+  // first call fail; nothing is left behind by an installation it stopped.
+  const unreachable = (answer) => answer.status === null || /Failed to connect to bus|No medium found|not been booted with systemd|System has not been booted/i.test(`${answer.stderr ?? ''}`)
+  return {
+    kind: 'systemd-user-unit', platform: 'linux', directory: files.directory, fileFor: files.fileFor,
+    readUnit({ label, fileName }) { checkUnit({ label, fileName }); return files.read(fileName) },
+    async install({ label, fileName, text }) {
+      checkUnit({ label, fileName })
+      const existed = files.present(fileName)
+      const written = files.write(fileName, text)
+      if (!written.ok) return written
+      const reloaded = await user('daemon-reload')
+      if (reloaded.status !== 0) {
+        if (!existed) files.remove(fileName)
+        return failed(unreachable(reloaded) ? 'login-item-unavailable' : 'login-item-install-failed', reloaded)
+      }
+      const enabled = await user('enable', fileName)
+      if (enabled.status !== 0) return failed(unreachable(enabled) ? 'login-item-unavailable' : 'login-item-install-failed', enabled)
+      return { ok: true, file: files.fileFor(fileName) }
+    },
+    async start({ label, fileName }) {
+      checkUnit({ label, fileName })
+      const answer = await user('start', fileName)
+      if (answer.status === 0) return { ok: true, pid: null }
+      return failed(unreachable(answer) ? 'login-item-unavailable' : /not found|not loaded|does not exist/i.test(`${answer.stderr ?? ''}`) ? 'login-item-not-loaded' : 'login-item-start-failed', answer)
+    },
+    async remove({ label, fileName }) {
+      checkUnit({ label, fileName })
+      const disabled = await user('disable', '--now', fileName)
+      const missing = disabled.status !== 0 && /not found|not loaded|does not exist/i.test(`${disabled.stderr ?? ''}`)
+      if (disabled.status !== 0 && !missing) return failed(unreachable(disabled) ? 'login-item-unavailable' : 'login-item-remove-failed', disabled)
+      const removed = files.remove(fileName)
+      if (!removed.ok) return removed
+      await user('daemon-reload')
+      return { ok: true, removed: removed.removed || disabled.status === 0 }
+    },
+    async inspect({ label, fileName }) {
+      checkUnit({ label, fileName })
+      const present = files.present(fileName)
+      const answer = await user('show', '-p', 'LoadState,ActiveState,SubState,UnitFileState,MainPID,ExecMainStatus', fileName)
+      if (answer.status !== 0) return { ok: true, file: files.fileFor(fileName), present, loaded: null, running: null, pid: null, lastExit: null, disabled: null }
+      const unit = readSystemdShow(answer.stdout)
+      return {
+        ok: true, file: files.fileFor(fileName), present, loaded: unit.loadState === 'loaded', running: unit.activeState === 'active' || unit.activeState === 'activating',
+        pid: unit.pid, lastExit: unit.lastExit, disabled: unit.unitFileState === null ? null : !['enabled', 'enabled-runtime', 'linked', 'linked-runtime'].includes(unit.unitFileState),
+      }
+    },
+  }
+}