@adecore/service 0.39.0 → 0.40.0

package/dist/definitions.js

@@ -8,9 +8,7 @@ function xmlValue(text) {
 function plistString(value, indent) {
     return `${indent}<string>${xmlText(value)}</string>`;
 }
-/*
- * `ProcessType=Interactive` avoids launchd throttling during a handover to a background process.
- */
+/* `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"?>',
@@ -40,9 +38,7 @@ function unitWord(value, command) {
     }
     return `"${escaped}"`;
 }
-/*
- * User services stop at logout unless the caller explicitly enables lingering.
- */
+/* User services stop at logout unless the caller enables lingering. */
 export function systemdUnit(spec) {
     const lines = [
         '[Unit]',
@@ -70,17 +66,14 @@ function cmdArgument(arg) {
     }
     return cmdEscaped(`"${arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, '$1$1')}"`);
 }
-/* The line cmd.exe runs: its title, the environment, the program and the log it appends to. */
 function taskCommandLine(spec) {
     const variables = Object.entries(spec.environment).map(([name, value]) => `set ${cmdEscaped(`"${name}=${value}"`)}`);
     const program = [cmdEscaped(spec.program), ...spec.args.map(cmdArgument)].join(' ');
     return `${scheduledTaskMarker(spec.label)}${[...variables, `${program} >>${cmdEscaped(spec.logFile)} 2>&1`].join(' && ')}`;
 }
 /*
- * A scheduled task for one person, started at their logon in their own session without a stored
- * password, and run again every minute so it comes back after a crash: a second instance is ignored
- * while one runs. RestartOnFailure is left out, since it also starts a task a stop ended. A task carries no environment
- * of its own, so cmd.exe sets it and appends the output to the log.
+ * Started at the person's logon without a stored password, and run again every minute so it comes back
+ * after a crash. RestartOnFailure would also start a task a stop ended. cmd.exe sets the environment.
  */
 export function scheduledTask(spec) {
     if (spec.user === undefined || spec.user === '') {
@@ -163,14 +156,17 @@ function launchAgentProgram(definition) {
     let depth = 0;
     let key = null;
     let start = 0;
+    const close = (end) => {
+        if (key !== null) {
+            entries.set(key, xml.slice(start, end));
+        }
+    };
     for (const token of xml.matchAll(/<(\/?)(dict|array)\s*>|<key>([^<]*)<\/key>/g)) {
         if (token[3] !== undefined) {
             if (depth !== 1) {
                 continue;
             }
-            if (key !== null) {
-                entries.set(key, xml.slice(start, token.index));
-            }
+            close(token.index);
             key = token[3];
             if (entries.has(key)) {
                 return null;
@@ -183,9 +179,7 @@ function launchAgentProgram(definition) {
         else {
             depth--;
             if (depth === 0) {
-                if (key !== null) {
-                    entries.set(key, xml.slice(start, token.index));
-                }
+                close(token.index);
                 const program = entries.get('Program');
                 return program !== undefined
                     ? (/^\s*<string>([^<]*)<\/string>\s*$/.exec(program)?.[1] ?? null)
@@ -220,9 +214,7 @@ function systemdRunsProgram(definition, program) {
     const executable = unitWord(program, true);
     return commands.length > 0 && commands.every((command) => command === executable || command.startsWith(`${executable} `));
 }
-/*
- * Callers sharing a service identity can check executable ownership before replacing its definition.
- */
+/* Callers sharing a service identity can check executable ownership before replacing its definition. */
 export function definitionRunsProgram(definition, program) {
     if (/<Task[\s>]/.test(definition)) {
         return scheduledTaskRunsProgram(definition, program);

package/dist/manager.js

@@ -5,10 +5,22 @@ function expectSuccess(result, what) {
         throw new Error(`${what} failed (${result.code}): ${(result.stderr || result.stdout).trim() || 'no output'}`);
     }
 }
+/* Writes the definition when it differs and returns the one it replaces. */
+function writeDefinition(files, path, definition) {
+    const previous = files.read(path);
+    if (previous !== definition) {
+        files.write(path, definition);
+    }
+    return previous;
+}
+async function waitWhile(condition, sleep) {
+    for (let attempt = 0; attempt < 25 && condition(); attempt++) {
+        await sleep(200);
+    }
+}
 /*
- * 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.
+ * A plist in ~/Library/LaunchAgents, loaded into the person's GUI domain. Not SMAppService: it wants a
+ * plist sealed inside the bundle, where the login shell's PATH and a log path in the home cannot go.
  */
 export function launchdManager(options) {
     const path = posix.join(options.home, 'Library', 'LaunchAgents', `${options.label}.plist`);
@@ -27,10 +39,7 @@ export function launchdManager(options) {
         install(definition) {
             // launchd opens the log but makes no folder for it, and a job whose log cannot open never starts.
             options.files.makeDirectory(posix.dirname(options.logFile));
-            const previous = options.files.read(path);
-            if (previous !== definition) {
-                options.files.write(path, definition);
-            }
+            const previous = writeDefinition(options.files, path, definition);
             return previous !== null && previous !== definition;
         },
         start() {
@@ -44,9 +53,7 @@ export function launchdManager(options) {
             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);
-                }
+                await waitWhile(isLoaded, options.sleep);
             }
             bootstrap();
         },
@@ -107,9 +114,8 @@ export function systemdManager(options) {
     };
 }
 /*
- * A task in the person's own Task Scheduler library, registered with `schtasks` from a copy of the
- * definition on disk. Creating one for oneself takes no admin. The task runs again every minute, so
- * a stop also disables it, and a start enables it again.
+ * A task in the person's own Task Scheduler library, which takes no admin. The task runs again every
+ * minute, so a stop also disables it and a start enables it again.
  */
 export function taskSchedulerManager(options) {
     const path = options.definitionFile;
@@ -147,26 +153,19 @@ export function taskSchedulerManager(options) {
         install(definition) {
             // cmd.exe appends to the log but makes no folder for it, and the task ends at once without one.
             options.files.makeDirectory(win32.dirname(options.logFile));
-            const previous = options.files.read(path);
-            if (previous !== definition) {
-                options.files.write(path, definition);
-            }
+            const previous = writeDefinition(options.files, path, definition);
             if (previous !== definition || !exists()) {
                 expectSuccess(schtasks('/Create', '/TN', name, '/XML', path, '/F'), 'schtasks /Create');
             }
             return previous !== null && previous !== definition;
         },
-        start() {
-            run();
-        },
+        start: run,
         async restart() {
             if (isRunning()) {
                 endTree();
                 schtasks('/End', '/TN', name);
                 // A task that still counts as running ignores the next start.
-                for (let attempt = 0; attempt < 25 && isRunning(); attempt++) {
-                    await options.sleep(200);
-                }
+                await waitWhile(isRunning, options.sleep);
             }
             run();
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/service",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "description": "User service definitions and injectable launchd, systemd and Task Scheduler managers.",
   "license": "FSL-1.1-MIT",
   "author": "Bas Milius",
@@ -51,8 +51,8 @@
     "test": "bun test"
   },
   "devDependencies": {
-    "@types/bun": "^1.4.2",
-    "@types/node": "^24.13.6",
+    "@types/bun": "^1.4.4",
+    "@types/node": "^24.19.2",
     "typescript": "^7.0.2"
   }
 }

package/src/definitions.ts

@@ -25,9 +25,7 @@ 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.
- */
+/* `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"?>',
@@ -43,9 +41,11 @@ export function launchAgentPlist(spec: ServiceSpec): string {
         '    <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>',
@@ -64,21 +64,22 @@ export function launchAgentPlist(spec: ServiceSpec): string {
         '</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.
- */
+/* User services stop at logout unless the caller enables lingering. */
 export function systemdUnit(spec: ServiceSpec): string {
     const lines = [
         '[Unit]',
@@ -97,6 +98,7 @@ export function systemdUnit(spec: ServiceSpec): string {
         'WantedBy=default.target',
         ''
     ];
+
     return lines.join('\n');
 }
 
@@ -105,27 +107,28 @@ function cmdArgument(arg: string): string {
     if (/[\r\n]/.test(arg)) {
         throw new Error('A scheduled task cannot pass on a line break');
     }
+
     return cmdEscaped(`"${arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, '$1$1')}"`);
 }
 
-/* The line cmd.exe runs: its title, the environment, the program and the log it appends to. */
 function taskCommandLine(spec: ServiceSpec): string {
     const variables = Object.entries(spec.environment).map(([name, value]) => `set ${cmdEscaped(`"${name}=${value}"`)}`);
     const program = [cmdEscaped(spec.program), ...spec.args.map(cmdArgument)].join(' ');
+
     return `${scheduledTaskMarker(spec.label)}${[...variables, `${program} >>${cmdEscaped(spec.logFile)} 2>&1`].join(' && ')}`;
 }
 
 /*
- * A scheduled task for one person, started at their logon in their own session without a stored
- * password, and run again every minute so it comes back after a crash: a second instance is ignored
- * while one runs. RestartOnFailure is left out, since it also starts a task a stop ended. A task carries no environment
- * of its own, so cmd.exe sets it and appends the output to the log.
+ * Started at the person's logon without a stored password, and run again every minute so it comes back
+ * after a crash. RestartOnFailure would also start a task a stop ended. cmd.exe sets the environment.
  */
 export function scheduledTask(spec: ServiceSpec): string {
     if (spec.user === undefined || spec.user === '') {
         throw new Error('A scheduled task needs the user it starts for.');
     }
+
     const user = xmlText(spec.user);
+
     // No XML declaration: schtasks decodes the file itself and refuses one that names an encoding.
     const lines = [
         '<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">',
@@ -181,73 +184,94 @@ export function scheduledTask(spec: ServiceSpec): string {
         '</Task>',
         ''
     ];
+
     return lines.join('\r\n');
 }
 
 function scheduledTaskRunsProgram(definition: string, program: string): boolean {
     const exec = definition.match(/<Exec>[\s\S]*?<\/Exec>/g);
+
     if (exec?.length !== 1) {
         return false;
     }
+
     const args = /<Arguments>([^<]*)<\/Arguments>/.exec(exec[0])?.[1];
     const line = args === undefined ? undefined : /\/c "([\s\S]*)"$/.exec(xmlValue(args))?.[1];
+
     return line !== undefined && (line.split(' && ').at(-1) ?? '').startsWith(`${cmdEscaped(program)} `);
 }
 
 /* Only keys of the outer plist dictionary identify the executable; nested environment keys are data. */
 function launchAgentProgram(definition: string): string | null {
     const xml = definition.replace(/<!--[\s\S]*?-->/g, '');
+
     if (xml.includes('<!--')) {
         return null;
     }
+
     const entries = new Map<string, string>();
     let depth = 0;
     let key: string | null = null;
     let start = 0;
+
+    const close = (end: number): void => {
+        if (key !== null) {
+            entries.set(key, xml.slice(start, end));
+        }
+    };
+
     for (const token of xml.matchAll(/<(\/?)(dict|array)\s*>|<key>([^<]*)<\/key>/g)) {
         if (token[3] !== undefined) {
             if (depth !== 1) {
                 continue;
             }
-            if (key !== null) {
-                entries.set(key, xml.slice(start, token.index));
-            }
+
+            close(token.index);
             key = token[3];
+
             if (entries.has(key)) {
                 return null;
             }
+
             start = token.index + token[0].length;
         } else if (token[1] === '') {
             depth++;
         } else {
             depth--;
+
             if (depth === 0) {
-                if (key !== null) {
-                    entries.set(key, xml.slice(start, token.index));
-                }
+                close(token.index);
                 const program = entries.get('Program');
+
                 return program !== undefined
                     ? (/^\s*<string>([^<]*)<\/string>\s*$/.exec(program)?.[1] ?? null)
                     : (/^\s*<array>\s*<string>([^<]*)<\/string>/.exec(entries.get('ProgramArguments') ?? '')?.[1] ?? null);
             }
         }
     }
+
     return null;
 }
 
 function systemdRunsProgram(definition: string, program: string): boolean {
     let service = false;
     let commands: string[] = [];
+
     for (const raw of definition.split('\n')) {
         const line = raw.trim();
+
         if (line.startsWith('#') || line.startsWith(';')) {
             continue;
         }
+
         if (/^\[.*\]$/.test(line)) {
             service = line === '[Service]';
+
             continue;
         }
+
         const command = service ? /^ExecStart\s*=\s*(.*)$/.exec(line)?.[1] : undefined;
+
         if (command !== undefined) {
             if (command === '') {
                 commands = [];
@@ -256,16 +280,17 @@ function systemdRunsProgram(definition: string, program: string): boolean {
             }
         }
     }
+
     const executable = unitWord(program, true);
+
     return commands.length > 0 && commands.every((command) => command === executable || command.startsWith(`${executable} `));
 }
 
-/*
- * Callers sharing a service identity can check executable ownership before replacing its definition.
- */
+/* Callers sharing a service identity can check executable ownership before replacing its definition. */
 export function definitionRunsProgram(definition: string, program: string): boolean {
     if (/<Task[\s>]/.test(definition)) {
         return scheduledTaskRunsProgram(definition, program);
     }
+
     return definition.trimStart().startsWith('<') ? launchAgentProgram(definition) === xmlText(program) : systemdRunsProgram(definition, program);
 }

package/src/manager.ts

@@ -48,6 +48,23 @@ function expectSuccess(result: CommandResult, what: string): void {
     }
 }
 
+/* Writes the definition when it differs and returns the one it replaces. */
+function writeDefinition(files: ServiceFiles, path: string, definition: string): string | null {
+    const previous = files.read(path);
+
+    if (previous !== definition) {
+        files.write(path, definition);
+    }
+
+    return previous;
+}
+
+async function waitWhile(condition: () => boolean, sleep: (ms: number) => Promise<void>): Promise<void> {
+    for (let attempt = 0; attempt < 25 && condition(); attempt++) {
+        await sleep(200);
+    }
+}
+
 export interface LaunchdOptions {
     uid: number;
     home: string;
@@ -59,15 +76,16 @@ export interface LaunchdOptions {
 }
 
 /*
- * 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.
+ * A plist in ~/Library/LaunchAgents, loaded into the person's GUI domain. Not SMAppService: it wants a
+ * plist sealed inside the bundle, where the login shell's PATH and a log path in the home cannot go.
  */
 export function launchdManager(options: LaunchdOptions): ServiceManager {
     const path = posix.join(options.home, 'Library', 'LaunchAgents', `${options.label}.plist`);
     const domain = `gui/${options.uid}`;
     const target = `${domain}/${options.label}`;
+
     const launchctl = (...args: string[]): CommandResult => options.run('/bin/launchctl', args);
+
     const isLoaded = (): boolean => launchctl('print', target).code === 0;
 
     const bootstrap = (): void => {
@@ -82,27 +100,26 @@ export function launchdManager(options: LaunchdOptions): ServiceManager {
         install(definition) {
             // launchd opens the log but makes no folder for it, and a job whose log cannot open never starts.
             options.files.makeDirectory(posix.dirname(options.logFile));
-            const previous = options.files.read(path);
-            if (previous !== definition) {
-                options.files.write(path, definition);
-            }
+            const previous = writeDefinition(options.files, 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);
-                }
+                await waitWhile(isLoaded, options.sleep);
             }
+
             bootstrap();
         },
         stop() {
@@ -128,6 +145,7 @@ export interface SystemdOptions {
 export function systemdManager(options: SystemdOptions): ServiceManager {
     const unit = options.unitName;
     const path = posix.join(options.configHome, 'systemd', 'user', unit);
+
     const systemctl = (...args: string[]): CommandResult => options.run('systemctl', ['--user', ...args]);
 
     const reload = (): void => {
@@ -141,11 +159,14 @@ export function systemdManager(options: SystemdOptions): ServiceManager {
         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() {
@@ -185,15 +206,17 @@ export interface TaskSchedulerOptions {
 }
 
 /*
- * A task in the person's own Task Scheduler library, registered with `schtasks` from a copy of the
- * definition on disk. Creating one for oneself takes no admin. The task runs again every minute, so
- * a stop also disables it, and a start enables it again.
+ * A task in the person's own Task Scheduler library, which takes no admin. The task runs again every
+ * minute, so a stop also disables it and a start enables it again.
  */
 export function taskSchedulerManager(options: TaskSchedulerOptions): ServiceManager {
     const path = options.definitionFile;
     const name = options.taskName;
+
     const schtasks = (...args: string[]): CommandResult => options.run('schtasks.exe', args);
+
     const exists = (): boolean => schtasks('/Query', '/TN', name).code === 0;
+
     // schtasks writes the state in the language of the system; PowerShell names it the same everywhere.
     const isRunning = (): boolean =>
         options
@@ -208,11 +231,13 @@ export function taskSchedulerManager(options: TaskSchedulerOptions): ServiceMana
     // Before `/End`, which leaves what the task's cmd.exe started running without a parent to find it by.
     const endTree = (): void => {
         const marker = scheduledTaskMarker(name).replace(/'/g, "''");
+
         const script = [
             'Get-CimInstance Win32_Process -Filter "Name=\'cmd.exe\'"',
             `Where-Object { $_.CommandLine -and $_.CommandLine.Contains('${marker}') }`,
             'ForEach-Object { taskkill.exe /PID $_.ProcessId /T /F | Out-Null }'
         ].join(' | ');
+
         options.run('powershell.exe', ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64')]);
     };
 
@@ -229,27 +254,23 @@ export function taskSchedulerManager(options: TaskSchedulerOptions): ServiceMana
         install(definition) {
             // cmd.exe appends to the log but makes no folder for it, and the task ends at once without one.
             options.files.makeDirectory(win32.dirname(options.logFile));
-            const previous = options.files.read(path);
-            if (previous !== definition) {
-                options.files.write(path, definition);
-            }
+            const previous = writeDefinition(options.files, path, definition);
+
             if (previous !== definition || !exists()) {
                 expectSuccess(schtasks('/Create', '/TN', name, '/XML', path, '/F'), 'schtasks /Create');
             }
+
             return previous !== null && previous !== definition;
         },
-        start() {
-            run();
-        },
+        start: run,
         async restart() {
             if (isRunning()) {
                 endTree();
                 schtasks('/End', '/TN', name);
                 // A task that still counts as running ignores the next start.
-                for (let attempt = 0; attempt < 25 && isRunning(); attempt++) {
-                    await options.sleep(200);
-                }
+                await waitWhile(isRunning, options.sleep);
             }
+
             run();
         },
         stop() {

package/src/platform.ts

@@ -20,12 +20,15 @@ export function platformServiceManager(platform: NodeJS.Platform, options: Platf
     if (platform === 'darwin') {
         return launchdManager(options.launchd);
     }
+
     if (platform === 'linux') {
         return systemdManager(options.systemd);
     }
+
     if (platform === 'win32' && options.taskScheduler !== undefined) {
         return taskSchedulerManager(options.taskScheduler);
     }
+
     return null;
 }
 
@@ -33,11 +36,14 @@ export function serviceDefinition(platform: NodeJS.Platform, spec: ServiceSpec):
     if (platform === 'darwin') {
         return launchAgentPlist(spec);
     }
+
     if (platform === 'linux') {
         return systemdUnit(spec);
     }
+
     if (platform === 'win32') {
         return scheduledTask(spec);
     }
+
     throw new Error(`Background services are unsupported on ${platform}.`);
 }

package/src/system.ts

@@ -6,6 +6,7 @@ import type { CommandResult, ServiceFiles } from './manager.js';
 /* The real launchctl, systemctl, loginctl and schtasks 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'], windowsHide: true });
+
     return { code: result.status ?? 1, stdout: result.stdout ?? '', stderr: result.stderr || result.error?.message || '' };
 }