@adecore/service 0.0.1 → 0.17.0-beta.1

package/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Bas Milius
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# @adecore/service
+
+Definitions and injectable managers for macOS launchd GUI jobs and Linux systemd user services. The host supplies identity, paths, environment, commands and files. It keeps installation authorization and executable policy.
+
+The package is private at `0.0.0` pending first publication. Use its local `source` exports, or run the package build for compiled JavaScript and declarations. It retains the [FSL-1.1-MIT license](LICENSE).
+
+```ts
+import { systemdUnit, type ServiceSpec } from '@adecore/service/definitions';
+
+const spec: ServiceSpec = {
+    label: 'com.example.worker',
+    description: 'Example background worker',
+    program: '/opt/example/bin/worker',
+    args: ['--listen', '127.0.0.1'],
+    environment: { PATH: '/usr/bin:/bin' },
+    workingDirectory: '/home/ada',
+    logFile: '/home/ada/worker.log'
+};
+const definition = systemdUnit(spec);
+```
+
+`/definitions` has no Node or Bun runtime imports. The root, `/manager`, `/platform` and `/system` are backend entrypoints. Importing them does not install or start a service.
+
+`install()` returns whether an existing definition changed, so a first install returns `false`. Await `restart()` for a changed definition, otherwise call `start()`. Uninstall does not stop a running job. Managers supply no authorization, lock, cancellation or automatic lingering.
+
+The full documentation covers [getting started](https://adecore.dev/service/getting-started), [definitions and identity](https://adecore.dev/service/definitions), [lifecycle](https://adecore.dev/service/lifecycle), [API reference](https://adecore.dev/service/reference) and [testing and host migration](https://adecore.dev/service/testing-migration). The first guide uses safe fakes rather than real service commands.

package/dist/definitions.d.ts

@@ -0,0 +1,12 @@
+export interface ServiceSpec {
+    label: string;
+    description: string;
+    program: string;
+    args: string[];
+    environment: Record<string, string>;
+    workingDirectory: string;
+    logFile: string;
+}
+export declare function launchAgentPlist(spec: ServiceSpec): string;
+export declare function systemdUnit(spec: ServiceSpec): string;
+export declare function definitionRunsProgram(definition: string, program: string): boolean;

package/dist/definitions.js

@@ -0,0 +1,69 @@
+function xmlText(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+function plistString(value, indent) {
+    return `${indent}<string>${xmlText(value)}</string>`;
+}
+/*
+ * `ProcessType=Interactive` avoids launchd throttling during a handover to a background process.
+ */
+export function launchAgentPlist(spec) {
+    const lines = [
+        '<?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>',
+        plistString(spec.label, '    '),
+        '    <key>ProgramArguments</key>',
+        '    <array>',
+        ...[spec.program, ...spec.args].map((arg) => plistString(arg, '        ')),
+        '    </array>',
+        '    <key>EnvironmentVariables</key>',
+        '    <dict>'
+    ];
+    for (const [name, value] of Object.entries(spec.environment)) {
+        lines.push(`        <key>${xmlText(name)}</key>`, plistString(value, '        '));
+    }
+    lines.push('    </dict>', '    <key>WorkingDirectory</key>', plistString(spec.workingDirectory, '    '), '    <key>RunAtLoad</key>', '    <true/>', '    <key>KeepAlive</key>', '    <true/>', '    <key>ProcessType</key>', '    <string>Interactive</string>', '    <key>StandardOutPath</key>', plistString(spec.logFile, '    '), '    <key>StandardErrorPath</key>', plistString(spec.logFile, '    '), '</dict>', '</plist>', '');
+    return lines.join('\n');
+}
+/* systemd expands `%` specifiers everywhere and `$` variables in a command line, so both are doubled; quotes keep a space in a path. */
+function unitWord(value, command) {
+    let escaped = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/%/g, '%%');
+    if (command) {
+        escaped = escaped.replace(/\$/g, '$$$$');
+    }
+    return `"${escaped}"`;
+}
+/*
+ * User services stop at logout unless the caller explicitly enables lingering.
+ */
+export function systemdUnit(spec) {
+    const lines = [
+        '[Unit]',
+        `Description=${spec.description.replace(/%/g, '%%')}`,
+        '',
+        '[Service]',
+        'Type=simple',
+        `ExecStart=${[spec.program, ...spec.args].map((word) => unitWord(word, true)).join(' ')}`,
+        ...Object.entries(spec.environment).map(([name, value]) => `Environment=${unitWord(`${name}=${value}`, false)}`),
+        // The one setting here that takes no quotes: it reads the rest of the line as the path.
+        `WorkingDirectory=${spec.workingDirectory.replace(/%/g, '%%')}`,
+        'Restart=always',
+        'RestartSec=2',
+        '',
+        '[Install]',
+        'WantedBy=default.target',
+        ''
+    ];
+    return lines.join('\n');
+}
+/*
+ * Callers sharing a service identity can check executable ownership before replacing its definition.
+ */
+export function definitionRunsProgram(definition, program) {
+    return (definition.includes(`<string>${xmlText(program)}</string>`) ||
+        definition.includes(`ExecStart=${unitWord(program, true)} `) ||
+        definition.includes(`ExecStart=${unitWord(program, true)}\n`));
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { definitionRunsProgram, launchAgentPlist, systemdUnit, type ServiceSpec } from './definitions.js';
+export { launchdManager, systemdManager, type CommandResult, type CommandRunner, type LaunchdOptions, type ServiceFiles, type ServiceManager, type SystemdOptions } from './manager.js';
+export { platformServiceManager, serviceDefinition, type PlatformServiceOptions } from './platform.js';
+export { diskFiles, runCommand } from './system.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { definitionRunsProgram, launchAgentPlist, systemdUnit } from './definitions.js';
+export { launchdManager, systemdManager } from './manager.js';
+export { platformServiceManager, serviceDefinition } from './platform.js';
+export { diskFiles, runCommand } from './system.js';

package/dist/manager.d.ts

@@ -0,0 +1,45 @@
+export interface CommandResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export type CommandRunner = (command: string, args: string[]) => CommandResult;
+export interface ServiceFiles {
+    read(path: string): string | null;
+    write(path: string, text: string): void;
+    remove(path: string): void;
+    makeDirectory(path: string): void;
+}
+export interface ServiceManager {
+    readonly kind: 'launchd' | 'systemd';
+    readonly path: string;
+    isInstalled(): boolean;
+    read(): string | null;
+    install(definition: string): boolean;
+    start(): void;
+    restart(): Promise<void>;
+    stop(): void;
+    uninstall(): void;
+    linger?: {
+        enabled(): boolean;
+        enable(): void;
+    };
+}
+export interface LaunchdOptions {
+    uid: number;
+    home: string;
+    run: CommandRunner;
+    files: ServiceFiles;
+    sleep(ms: number): Promise<void>;
+    label: string;
+    logFile: string;
+}
+export declare function launchdManager(options: LaunchdOptions): ServiceManager;
+export interface SystemdOptions {
+    configHome: string;
+    run: CommandRunner;
+    files: ServiceFiles;
+    user: string;
+    unitName: string;
+}
+export declare function systemdManager(options: SystemdOptions): ServiceManager;

package/dist/manager.js

@@ -0,0 +1,111 @@
+import { dirname, join } from 'node:path';
+function describe(result, what) {
+    return `${what} failed (${result.code}): ${(result.stderr || result.stdout).trim() || 'no output'}`;
+}
+function expectSuccess(result, what) {
+    if (result.code !== 0) {
+        throw new Error(describe(result, what));
+    }
+}
+/*
+ * A plist in ~/Library/LaunchAgents, loaded with `launchctl bootstrap` into the person's GUI domain.
+ * SMAppService (Electron's `agentService`) was the other way: it wants a plist that is sealed inside
+ * the bundle, where the login shell's PATH and a log path in the home cannot be written.
+ */
+export function launchdManager(options) {
+    const label = options.label;
+    const path = join(options.home, 'Library', 'LaunchAgents', `${label}.plist`);
+    const domain = `gui/${options.uid}`;
+    const target = `${domain}/${label}`;
+    const launchctl = (...args) => options.run('/bin/launchctl', args);
+    const isLoaded = () => launchctl('print', target).code === 0;
+    const bootstrap = () => {
+        expectSuccess(launchctl('bootstrap', domain, path), 'launchctl bootstrap');
+    };
+    return {
+        kind: 'launchd',
+        path,
+        isInstalled: () => options.files.read(path) !== null,
+        read: () => options.files.read(path),
+        install(definition) {
+            // launchd opens the log but makes no folder for it, and a job whose log cannot open never starts.
+            options.files.makeDirectory(dirname(options.logFile));
+            const previous = options.files.read(path);
+            if (previous !== definition) {
+                options.files.write(path, definition);
+            }
+            return previous !== null && previous !== definition;
+        },
+        start() {
+            if (isLoaded()) {
+                expectSuccess(launchctl('kickstart', target), 'launchctl kickstart');
+                return;
+            }
+            bootstrap();
+        },
+        async restart() {
+            if (isLoaded()) {
+                launchctl('bootout', target);
+                // bootout returns before the label is released; bootstrapping sooner fails with an I/O error.
+                for (let attempt = 0; attempt < 25 && isLoaded(); attempt++) {
+                    await options.sleep(200);
+                }
+            }
+            bootstrap();
+        },
+        stop() {
+            if (isLoaded()) {
+                launchctl('bootout', target);
+            }
+        },
+        uninstall() {
+            options.files.remove(path);
+        }
+    };
+}
+/* A user unit under ~/.config/systemd/user, enabled for `default.target`. */
+export function systemdManager(options) {
+    const unit = options.unitName;
+    const path = join(options.configHome, 'systemd', 'user', unit);
+    const systemctl = (...args) => options.run('systemctl', ['--user', ...args]);
+    const reload = () => {
+        expectSuccess(systemctl('daemon-reload'), 'systemctl daemon-reload');
+    };
+    return {
+        kind: 'systemd',
+        path,
+        isInstalled: () => options.files.read(path) !== null,
+        read: () => options.files.read(path),
+        install(definition) {
+            const previous = options.files.read(path);
+            if (previous !== definition) {
+                options.files.write(path, definition);
+                reload();
+            }
+            expectSuccess(systemctl('enable', unit), 'systemctl enable');
+            return previous !== null && previous !== definition;
+        },
+        start() {
+            expectSuccess(systemctl('start', unit), 'systemctl start');
+        },
+        async restart() {
+            reload();
+            expectSuccess(systemctl('restart', unit), 'systemctl restart');
+        },
+        stop() {
+            systemctl('stop', unit);
+        },
+        uninstall() {
+            systemctl('disable', unit);
+            options.files.remove(path);
+            // A running unit stays loaded without its file, so `stop` still reaches it afterwards.
+            systemctl('daemon-reload');
+        },
+        linger: {
+            enabled: () => options.run('loginctl', ['show-user', options.user, '--property=Linger', '--value']).stdout.trim() === 'yes',
+            enable() {
+                expectSuccess(options.run('loginctl', ['enable-linger', options.user]), 'loginctl enable-linger');
+            }
+        }
+    };
+}

package/dist/platform.d.ts

@@ -0,0 +1,8 @@
+import { type ServiceSpec } from './definitions.js';
+import { type LaunchdOptions, type ServiceManager, type SystemdOptions } from './manager.js';
+export interface PlatformServiceOptions {
+    launchd: LaunchdOptions;
+    systemd: SystemdOptions;
+}
+export declare function platformServiceManager(platform: NodeJS.Platform, options: PlatformServiceOptions): ServiceManager | null;
+export declare function serviceDefinition(platform: NodeJS.Platform, spec: ServiceSpec): string;

package/dist/platform.js

@@ -0,0 +1,20 @@
+import { launchAgentPlist, systemdUnit } from './definitions.js';
+import { launchdManager, systemdManager } from './manager.js';
+export function platformServiceManager(platform, options) {
+    if (platform === 'darwin') {
+        return launchdManager(options.launchd);
+    }
+    if (platform === 'linux') {
+        return systemdManager(options.systemd);
+    }
+    return null;
+}
+export function serviceDefinition(platform, spec) {
+    if (platform === 'darwin') {
+        return launchAgentPlist(spec);
+    }
+    if (platform === 'linux') {
+        return systemdUnit(spec);
+    }
+    throw new Error(`Background services are unsupported on ${platform}.`);
+}

package/dist/system.d.ts

@@ -0,0 +1,3 @@
+import type { CommandResult, ServiceFiles } from './manager.js';
+export declare function runCommand(command: string, args: string[]): CommandResult;
+export declare const diskFiles: ServiceFiles;

package/dist/system.js

@@ -0,0 +1,28 @@
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+/* The real launchctl, systemctl and loginctl under a service manager, bounded so a hung one cannot hold up a quit. */
+export function runCommand(command, args) {
+    const result = spawnSync(command, args, { encoding: 'utf8', timeout: 15_000, stdio: ['ignore', 'pipe', 'pipe'] });
+    return { code: result.status ?? 1, stdout: result.stdout ?? '', stderr: result.stderr || result.error?.message || '' };
+}
+export const diskFiles = {
+    read(path) {
+        try {
+            return readFileSync(path, 'utf8');
+        }
+        catch {
+            return null;
+        }
+    },
+    write(path, text) {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, text);
+    },
+    remove(path) {
+        rmSync(path, { force: true });
+    },
+    makeDirectory(path) {
+        mkdirSync(path, { recursive: true });
+    }
+};

package/package.json

@@ -1,11 +1,58 @@
 {
   "name": "@adecore/service",
-  "version": "0.0.1",
-  "description": "Placeholder for the first release.",
+  "version": "0.17.0-beta.1",
+  "description": "User service definitions and injectable launchd and systemd managers.",
   "license": "FSL-1.1-MIT",
+  "author": "Bas Milius",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/basmilius/adecore.git",
     "directory": "packages/service"
+  },
+  "homepage": "https://adecore.dev/service/",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/__snapshots__"
+  ],
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./definitions": {
+      "source": "./src/definitions.ts",
+      "types": "./dist/definitions.d.ts",
+      "default": "./dist/definitions.js"
+    },
+    "./manager": {
+      "source": "./src/manager.ts",
+      "types": "./dist/manager.d.ts",
+      "default": "./dist/manager.js"
+    },
+    "./platform": {
+      "source": "./src/platform.ts",
+      "types": "./dist/platform.d.ts",
+      "default": "./dist/platform.js"
+    },
+    "./system": {
+      "source": "./src/system.ts",
+      "types": "./dist/system.d.ts",
+      "default": "./dist/system.js"
+    }
+  },
+  "scripts": {
+    "build": "bun scripts/build.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.2",
+    "@types/node": "^24.13.6",
+    "typescript": "^7.0.2"
   }
 }

package/src/definitions.ts

@@ -0,0 +1,104 @@
+export interface ServiceSpec {
+    label: string;
+    description: string;
+    program: string;
+    args: string[];
+    environment: Record<string, string>;
+    workingDirectory: string;
+    /* launchd only: where stdout and stderr go. systemd has the journal. */
+    logFile: string;
+}
+
+function xmlText(value: string): string {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+function plistString(value: string, indent: string): string {
+    return `${indent}<string>${xmlText(value)}</string>`;
+}
+
+/*
+ * `ProcessType=Interactive` avoids launchd throttling during a handover to a background process.
+ */
+export function launchAgentPlist(spec: ServiceSpec): string {
+    const lines = [
+        '<?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>',
+        plistString(spec.label, '    '),
+        '    <key>ProgramArguments</key>',
+        '    <array>',
+        ...[spec.program, ...spec.args].map((arg) => plistString(arg, '        ')),
+        '    </array>',
+        '    <key>EnvironmentVariables</key>',
+        '    <dict>'
+    ];
+    for (const [name, value] of Object.entries(spec.environment)) {
+        lines.push(`        <key>${xmlText(name)}</key>`, plistString(value, '        '));
+    }
+    lines.push(
+        '    </dict>',
+        '    <key>WorkingDirectory</key>',
+        plistString(spec.workingDirectory, '    '),
+        '    <key>RunAtLoad</key>',
+        '    <true/>',
+        '    <key>KeepAlive</key>',
+        '    <true/>',
+        '    <key>ProcessType</key>',
+        '    <string>Interactive</string>',
+        '    <key>StandardOutPath</key>',
+        plistString(spec.logFile, '    '),
+        '    <key>StandardErrorPath</key>',
+        plistString(spec.logFile, '    '),
+        '</dict>',
+        '</plist>',
+        ''
+    );
+    return lines.join('\n');
+}
+
+/* systemd expands `%` specifiers everywhere and `$` variables in a command line, so both are doubled; quotes keep a space in a path. */
+function unitWord(value: string, command: boolean): string {
+    let escaped = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/%/g, '%%');
+    if (command) {
+        escaped = escaped.replace(/\$/g, '$$$$');
+    }
+    return `"${escaped}"`;
+}
+
+/*
+ * User services stop at logout unless the caller explicitly enables lingering.
+ */
+export function systemdUnit(spec: ServiceSpec): string {
+    const lines = [
+        '[Unit]',
+        `Description=${spec.description.replace(/%/g, '%%')}`,
+        '',
+        '[Service]',
+        'Type=simple',
+        `ExecStart=${[spec.program, ...spec.args].map((word) => unitWord(word, true)).join(' ')}`,
+        ...Object.entries(spec.environment).map(([name, value]) => `Environment=${unitWord(`${name}=${value}`, false)}`),
+        // The one setting here that takes no quotes: it reads the rest of the line as the path.
+        `WorkingDirectory=${spec.workingDirectory.replace(/%/g, '%%')}`,
+        'Restart=always',
+        'RestartSec=2',
+        '',
+        '[Install]',
+        'WantedBy=default.target',
+        ''
+    ];
+    return lines.join('\n');
+}
+
+/*
+ * Callers sharing a service identity can check executable ownership before replacing its definition.
+ */
+export function definitionRunsProgram(definition: string, program: string): boolean {
+    return (
+        definition.includes(`<string>${xmlText(program)}</string>`) ||
+        definition.includes(`ExecStart=${unitWord(program, true)} `) ||
+        definition.includes(`ExecStart=${unitWord(program, true)}\n`)
+    );
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export { definitionRunsProgram, launchAgentPlist, systemdUnit, type ServiceSpec } from './definitions.js';
+export {
+    launchdManager,
+    systemdManager,
+    type CommandResult,
+    type CommandRunner,
+    type LaunchdOptions,
+    type ServiceFiles,
+    type ServiceManager,
+    type SystemdOptions
+} from './manager.js';
+export { platformServiceManager, serviceDefinition, type PlatformServiceOptions } from './platform.js';
+export { diskFiles, runCommand } from './system.js';

package/src/manager.ts

@@ -0,0 +1,178 @@
+import { dirname, join } from 'node:path';
+
+export interface CommandResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+
+/* Runs a command to completion, bounded by a timeout. Synchronous, because quitting cannot wait on a promise. */
+export type CommandRunner = (command: string, args: string[]) => CommandResult;
+
+export interface ServiceFiles {
+    read(path: string): string | null;
+    write(path: string, text: string): void;
+    remove(path: string): void;
+    /* With every parent, and nothing when it is there already. */
+    makeDirectory(path: string): void;
+}
+
+export interface ServiceManager {
+    readonly kind: 'launchd' | 'systemd';
+    /* Where the definition lives, for the documentation and the error a person reads. */
+    readonly path: string;
+    isInstalled(): boolean;
+    /* The definition on disk, null when there is none. */
+    read(): string | null;
+    /*
+     * Puts the definition on disk, so the service starts with the person's session. A running daemon
+     * keeps running, on the definition it was started from: true says that one is not this one.
+     */
+    install(definition: string): boolean;
+    /* Starts the daemon from the definition on disk; nothing when it already runs. */
+    start(): void;
+    /* Ends the running daemon and starts it from the definition on disk, which is how a new binary takes over. */
+    restart(): Promise<void>;
+    /* Ends the running daemon. The definition stays. */
+    stop(): void;
+    /* Takes the definition away, so nothing starts it again. A running daemon keeps running until `stop`. */
+    uninstall(): void;
+    /* Linux only: whether the person's services outlive their session, and the step that makes them. */
+    linger?: { enabled(): boolean; enable(): void };
+}
+
+function describe(result: CommandResult, what: string): string {
+    return `${what} failed (${result.code}): ${(result.stderr || result.stdout).trim() || 'no output'}`;
+}
+
+function expectSuccess(result: CommandResult, what: string): void {
+    if (result.code !== 0) {
+        throw new Error(describe(result, what));
+    }
+}
+
+export interface LaunchdOptions {
+    uid: number;
+    home: string;
+    run: CommandRunner;
+    files: ServiceFiles;
+    sleep(ms: number): Promise<void>;
+    label: string;
+    logFile: string;
+}
+
+/*
+ * A plist in ~/Library/LaunchAgents, loaded with `launchctl bootstrap` into the person's GUI domain.
+ * SMAppService (Electron's `agentService`) was the other way: it wants a plist that is sealed inside
+ * the bundle, where the login shell's PATH and a log path in the home cannot be written.
+ */
+export function launchdManager(options: LaunchdOptions): ServiceManager {
+    const label = options.label;
+    const path = join(options.home, 'Library', 'LaunchAgents', `${label}.plist`);
+    const domain = `gui/${options.uid}`;
+    const target = `${domain}/${label}`;
+    const launchctl = (...args: string[]): CommandResult => options.run('/bin/launchctl', args);
+    const isLoaded = (): boolean => launchctl('print', target).code === 0;
+
+    const bootstrap = (): void => {
+        expectSuccess(launchctl('bootstrap', domain, path), 'launchctl bootstrap');
+    };
+
+    return {
+        kind: 'launchd',
+        path,
+        isInstalled: () => options.files.read(path) !== null,
+        read: () => options.files.read(path),
+        install(definition) {
+            // launchd opens the log but makes no folder for it, and a job whose log cannot open never starts.
+            options.files.makeDirectory(dirname(options.logFile));
+            const previous = options.files.read(path);
+            if (previous !== definition) {
+                options.files.write(path, definition);
+            }
+            return previous !== null && previous !== definition;
+        },
+        start() {
+            if (isLoaded()) {
+                expectSuccess(launchctl('kickstart', target), 'launchctl kickstart');
+                return;
+            }
+            bootstrap();
+        },
+        async restart() {
+            if (isLoaded()) {
+                launchctl('bootout', target);
+                // bootout returns before the label is released; bootstrapping sooner fails with an I/O error.
+                for (let attempt = 0; attempt < 25 && isLoaded(); attempt++) {
+                    await options.sleep(200);
+                }
+            }
+            bootstrap();
+        },
+        stop() {
+            if (isLoaded()) {
+                launchctl('bootout', target);
+            }
+        },
+        uninstall() {
+            options.files.remove(path);
+        }
+    };
+}
+
+export interface SystemdOptions {
+    configHome: string;
+    run: CommandRunner;
+    files: ServiceFiles;
+    user: string;
+    unitName: string;
+}
+
+/* A user unit under ~/.config/systemd/user, enabled for `default.target`. */
+export function systemdManager(options: SystemdOptions): ServiceManager {
+    const unit = options.unitName;
+    const path = join(options.configHome, 'systemd', 'user', unit);
+    const systemctl = (...args: string[]): CommandResult => options.run('systemctl', ['--user', ...args]);
+
+    const reload = (): void => {
+        expectSuccess(systemctl('daemon-reload'), 'systemctl daemon-reload');
+    };
+
+    return {
+        kind: 'systemd',
+        path,
+        isInstalled: () => options.files.read(path) !== null,
+        read: () => options.files.read(path),
+        install(definition) {
+            const previous = options.files.read(path);
+            if (previous !== definition) {
+                options.files.write(path, definition);
+                reload();
+            }
+            expectSuccess(systemctl('enable', unit), 'systemctl enable');
+            return previous !== null && previous !== definition;
+        },
+        start() {
+            expectSuccess(systemctl('start', unit), 'systemctl start');
+        },
+        async restart() {
+            reload();
+            expectSuccess(systemctl('restart', unit), 'systemctl restart');
+        },
+        stop() {
+            systemctl('stop', unit);
+        },
+        uninstall() {
+            systemctl('disable', unit);
+            options.files.remove(path);
+            // A running unit stays loaded without its file, so `stop` still reaches it afterwards.
+            systemctl('daemon-reload');
+        },
+        linger: {
+            enabled: () => options.run('loginctl', ['show-user', options.user, '--property=Linger', '--value']).stdout.trim() === 'yes',
+            enable() {
+                expectSuccess(options.run('loginctl', ['enable-linger', options.user]), 'loginctl enable-linger');
+            }
+        }
+    };
+}

package/src/platform.ts

@@ -0,0 +1,27 @@
+import { launchAgentPlist, systemdUnit, type ServiceSpec } from './definitions.js';
+import { launchdManager, systemdManager, type LaunchdOptions, type ServiceManager, type SystemdOptions } from './manager.js';
+
+export interface PlatformServiceOptions {
+    launchd: LaunchdOptions;
+    systemd: SystemdOptions;
+}
+
+export function platformServiceManager(platform: NodeJS.Platform, options: PlatformServiceOptions): ServiceManager | null {
+    if (platform === 'darwin') {
+        return launchdManager(options.launchd);
+    }
+    if (platform === 'linux') {
+        return systemdManager(options.systemd);
+    }
+    return null;
+}
+
+export function serviceDefinition(platform: NodeJS.Platform, spec: ServiceSpec): string {
+    if (platform === 'darwin') {
+        return launchAgentPlist(spec);
+    }
+    if (platform === 'linux') {
+        return systemdUnit(spec);
+    }
+    throw new Error(`Background services are unsupported on ${platform}.`);
+}

package/src/system.ts

@@ -0,0 +1,30 @@
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import type { CommandResult, ServiceFiles } from './manager.js';
+
+/* The real launchctl, systemctl and loginctl under a service manager, bounded so a hung one cannot hold up a quit. */
+export function runCommand(command: string, args: string[]): CommandResult {
+    const result = spawnSync(command, args, { encoding: 'utf8', timeout: 15_000, stdio: ['ignore', 'pipe', 'pipe'] });
+    return { code: result.status ?? 1, stdout: result.stdout ?? '', stderr: result.stderr || result.error?.message || '' };
+}
+
+export const diskFiles: ServiceFiles = {
+    read(path) {
+        try {
+            return readFileSync(path, 'utf8');
+        } catch {
+            return null;
+        }
+    },
+    write(path, text) {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, text);
+    },
+    remove(path) {
+        rmSync(path, { force: true });
+    },
+    makeDirectory(path) {
+        mkdirSync(path, { recursive: true });
+    }
+};