akm-cli 0.9.0-rc.1 → 0.9.0-rc.13

package/dist/tasks/backends/launchd.js

@@ -2,7 +2,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
- * launchd backend for `akm tasks` (macOS default).
+ * launchd backend for `akm task` (macOS default).
  *
  * Each task is written as a per-user LaunchAgent plist at
  * `~/Library/LaunchAgents/com.akm.task.<id>.plist` and registered via
@@ -29,7 +29,8 @@ import { ConfigError } from "../../core/errors.js";
 import { getTaskLogDir } from "../../core/paths.js";
 import { resolveAkmInvocation } from "../resolve-akm-bin.js";
 import { parseSchedule, translateToLaunchd } from "../schedule.js";
-import { escapeXml, nodeExec, nodeFs } from "./exec-utils.js";
+import { buildScheduledTaskInvocation, parseScheduledTaskArgv, resolveScheduledTaskContext, schedulerContextDescriptor, schedulerContextPath, } from "../scheduler-invocation.js";
+import { escapeXml, nodeExec, nodeFs, runOrThrow } from "./exec-utils.js";
 export const LAUNCHD_LABEL_PREFIX = "com.akm.task.";
 export function LAUNCHD_BACKEND(options = {}) {
     const exec = options.exec ?? defaultLaunchdExec();
@@ -37,57 +38,157 @@ export function LAUNCHD_BACKEND(options = {}) {
     const agentsDir = options.agentsDir ?? defaultAgentsDir();
     const logDir = options.logDir ?? getTaskLogDir();
     const akmArgv = options.akmArgv ?? resolveAkmInvocation().argv;
+    const scheduledContext = options.scheduledContext ?? resolveScheduledTaskContext();
     const plistPath = (id) => path.join(agentsDir, `${LAUNCHD_LABEL_PREFIX}${id}.plist`);
     const label = (id) => `${LAUNCHD_LABEL_PREFIX}${id}`;
     const target = (id) => `gui/${exec.uid()}/${label(id)}`;
+    const pathEnv = () => {
+        if (options.envPath === false)
+            return undefined;
+        if (typeof options.envPath === "string")
+            return options.envPath;
+        return process.env.PATH ?? "";
+    };
+    const defaultContextPath = schedulerContextPath(schedulerContextDescriptor(scheduledContext, pathEnv() ?? ""));
+    const setEnableState = (id, enabled) => {
+        const verb = enabled ? "enable" : "disable";
+        runOrThrow(exec, ["launchctl", verb, target(id)], {
+            message: (r) => `launchctl ${verb} failed: ${r.stderr || r.stdout || "no output"}.`,
+        });
+    };
     return {
         name: "launchd",
-        install(task) {
+        install(task, opts) {
             // Capture PATH at install time so launchd (which strips the environment
             // aggressively) can find the same binaries the user sees interactively.
-            let pathEnv;
-            if (options.envPath === false) {
-                pathEnv = undefined;
-            }
-            else if (typeof options.envPath === "string") {
-                pathEnv = options.envPath;
-            }
-            else {
-                pathEnv = process.env.PATH ?? "";
+            const xml = buildPlistXml(task, [...(opts?.binding ?? akmArgv)], logDir, opts?.contextPath ?? defaultContextPath, opts?.target);
+            const file = plistPath(task.id);
+            const previousPlist = fsLike.exists(file) ? fsLike.readFile(file) : undefined;
+            let previousEnabled = true;
+            if (previousPlist !== undefined) {
+                const disabledLabels = readDisabledLabels(exec);
+                if (disabledLabels === undefined) {
+                    throw new ConfigError(`launchctl print-disabled failed; cannot safely replace existing task "${task.id}".`, "INVALID_CONFIG_FILE");
+                }
+                previousEnabled = !disabledLabels.has(label(task.id));
             }
-            const xml = buildPlistXml(task, akmArgv, logDir, pathEnv);
             fsLike.ensureDir(agentsDir);
             // launchd refuses to start a job when StandardOutPath/StandardErrorPath
             // points at a non-existent directory; create it before bootstrap.
             fsLike.ensureDir(logDir);
-            fsLike.writeFile(plistPath(task.id), xml);
-            const bootout = exec.run(["launchctl", "bootout", target(task.id)]);
-            // bootout returning non-zero is fine — agent might not be loaded.
-            void bootout;
-            const bootstrap = exec.run(["launchctl", "bootstrap", `gui/${exec.uid()}`, plistPath(task.id)]);
-            if (bootstrap.status !== 0) {
-                throw new ConfigError(`launchctl bootstrap failed (exit ${bootstrap.status}): ${bootstrap.stderr || bootstrap.stdout || "no output"}.`, "INVALID_CONFIG_FILE", "Ensure `launchctl` is available; on macOS it is part of the base system.");
+            const tempFile = path.join(agentsDir, `.${task.id}.${Date.now()}.tmp`);
+            fsLike.writeFile(tempFile, xml);
+            let bootoutCompleted = false;
+            let previousWasLoaded = false;
+            let fileReplaced = false;
+            let enableStateTouched = false;
+            try {
+                const bootout = runOrThrow(exec, ["launchctl", "bootout", target(task.id)], {
+                    isOk: (r) => r.status === 0 || isServiceNotFoundResult(r),
+                    message: (r) => `launchctl bootout failed (exit ${r.status}): ${r.stderr || r.stdout || "no output"}.`,
+                });
+                bootoutCompleted = true;
+                previousWasLoaded = previousPlist !== undefined && bootout.status === 0;
+                fsLike.replaceFile(tempFile, file);
+                fileReplaced = true;
+                // A disable override survives bootout and plist replacement. Clear it
+                // before bootstrap, then apply the desired state after registration.
+                enableStateTouched = true;
+                setEnableState(task.id, true);
+                runOrThrow(exec, ["launchctl", "bootstrap", `gui/${exec.uid()}`, file], {
+                    message: (r) => `launchctl bootstrap failed (exit ${r.status}): ${r.stderr || r.stdout || "no output"}.`,
+                    hint: "Ensure `launchctl` is available; on macOS it is part of the base system.",
+                });
+                if (!task.enabled) {
+                    setEnableState(task.id, false);
+                }
             }
-            if (!task.enabled) {
-                const disable = exec.run(["launchctl", "disable", target(task.id)]);
-                if (disable.status !== 0) {
-                    throw new ConfigError(`launchctl disable failed: ${disable.stderr || disable.stdout || "no output"}.`, "INVALID_CONFIG_FILE");
+            catch (err) {
+                if (!bootoutCompleted)
+                    throw err;
+                const rollbackErrors = [];
+                let priorFileRestored = !fileReplaced;
+                if (fileReplaced) {
+                    let replacementUnloaded = false;
+                    try {
+                        const rollbackBootout = exec.run(["launchctl", "bootout", target(task.id)]);
+                        replacementUnloaded = rollbackBootout.status === 0 || isServiceNotFoundResult(rollbackBootout);
+                        if (!replacementUnloaded) {
+                            rollbackErrors.push(new ConfigError(`launchctl bootout during rollback failed: ${rollbackBootout.stderr || rollbackBootout.stdout || "no output"}.`, "INVALID_CONFIG_FILE"));
+                        }
+                    }
+                    catch (rollbackError) {
+                        rollbackErrors.push(rollbackError);
+                    }
+                    if (replacementUnloaded) {
+                        try {
+                            if (previousPlist === undefined) {
+                                if (fsLike.exists(file))
+                                    fsLike.removeFile(file);
+                            }
+                            else {
+                                fsLike.writeFile(tempFile, previousPlist);
+                                fsLike.replaceFile(tempFile, file);
+                            }
+                            priorFileRestored = true;
+                        }
+                        catch (rollbackError) {
+                            rollbackErrors.push(rollbackError);
+                        }
+                    }
+                }
+                if (previousPlist !== undefined && previousWasLoaded && priorFileRestored) {
+                    try {
+                        setEnableState(task.id, true);
+                        const restore = exec.run(["launchctl", "bootstrap", `gui/${exec.uid()}`, file]);
+                        if (restore.status !== 0) {
+                            rollbackErrors.push(new ConfigError(`launchctl bootstrap during rollback failed: ${restore.stderr || restore.stdout || "no output"}.`, "INVALID_CONFIG_FILE"));
+                        }
+                    }
+                    catch (rollbackError) {
+                        rollbackErrors.push(rollbackError);
+                    }
+                    if (!previousEnabled) {
+                        try {
+                            setEnableState(task.id, false);
+                        }
+                        catch (rollbackError) {
+                            rollbackErrors.push(rollbackError);
+                        }
+                    }
+                }
+                else if (enableStateTouched) {
+                    try {
+                        setEnableState(task.id, previousPlist === undefined || previousEnabled);
+                    }
+                    catch (rollbackError) {
+                        rollbackErrors.push(rollbackError);
+                    }
                 }
+                if (rollbackErrors.length > 0) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    throw new AggregateError([err, ...rollbackErrors], `${message}; rollback for launchd task "${task.id}" was incomplete.`);
+                }
+                throw err;
+            }
+            finally {
+                if (fsLike.exists(tempFile))
+                    fsLike.removeFile(tempFile);
             }
         },
         uninstall(id) {
-            // Bootout first (may fail if agent never loaded — that's fine).
-            exec.run(["launchctl", "bootout", target(id)]);
+            runOrThrow(exec, ["launchctl", "bootout", target(id)], {
+                isOk: (r) => r.status === 0 || isServiceNotFoundResult(r),
+                message: (r) => `launchctl bootout failed (exit ${r.status}): ${r.stderr || r.stdout || "no output"}.`,
+            });
+            // launchctl disable overrides persist after the plist is removed.
+            setEnableState(id, true);
             const file = plistPath(id);
             if (fsLike.exists(file))
                 fsLike.removeFile(file);
         },
         setEnabled(id, enabled) {
-            const verb = enabled ? "enable" : "disable";
-            const r = exec.run(["launchctl", verb, target(id)]);
-            if (r.status !== 0) {
-                throw new ConfigError(`launchctl ${verb} failed: ${r.stderr || r.stdout || "no output"}.`, "INVALID_CONFIG_FILE");
-            }
+            setEnableState(id, enabled);
         },
         list() {
             if (!fsLike.exists(agentsDir))
@@ -98,55 +199,185 @@ export function LAUNCHD_BACKEND(options = {}) {
                     ids.push(file.slice(LAUNCHD_LABEL_PREFIX.length, -".plist".length));
                 }
             }
-            return ids.map((id) => ({ id }));
+            if (ids.length === 0)
+                return [];
+            const disabledLabels = readDisabledLabels(exec);
+            return ids
+                .map((id) => inspectInstalledLaunchdTask(id, fsLike.readFile(plistPath(id)), disabledLabels, exec))
+                .filter((ref) => ref !== undefined);
+        },
+        listForRebind() {
+            if (!fsLike.exists(agentsDir))
+                return [];
+            const refs = [];
+            for (const file of fsLike.list(agentsDir)) {
+                if (!file.startsWith(LAUNCHD_LABEL_PREFIX) || !file.endsWith(".plist"))
+                    continue;
+                const id = file.slice(LAUNCHD_LABEL_PREFIX.length, -".plist".length);
+                const installed = extractPlistInvocation(fsLike.readFile(plistPath(id)));
+                refs.push({ id, ...(installed?.target !== undefined ? { target: installed.target } : {}) });
+            }
+            return refs;
+        },
+        expectedSignature(task, opts) {
+            return normalizeSignature(buildPlistXml(task, [...(opts?.binding ?? akmArgv)], logDir, opts?.contextPath ?? defaultContextPath, opts?.target));
         },
     };
 }
+function inspectInstalledLaunchdTask(id, raw, disabledLabels, exec) {
+    const installed = extractPlistInvocation(raw);
+    // An invocation that no longer parses (e.g. a pre-0.9 `tasks run` entry
+    // surviving the scheduler-ABI respelling) is an orphan of its marker id,
+    // not a hard failure: `list()` omits it so `akmTasksSync` treats the id as
+    // "not present" and reinstalls it from the current task file.
+    if (!installed)
+        return undefined;
+    const metadata = {
+        ...(installed.target !== undefined ? { target: installed.target } : {}),
+        binding: installed.binding,
+        contextPath: installed.contextPath,
+    };
+    if (!disabledLabels)
+        return { id, ...metadata };
+    const jobLabel = `${LAUNCHD_LABEL_PREFIX}${id}`;
+    try {
+        const loaded = exec.run(["launchctl", "print", `gui/${exec.uid()}/${jobLabel}`]);
+        if (loaded.status !== 0)
+            return { id, ...metadata };
+    }
+    catch {
+        return { id, ...metadata };
+    }
+    try {
+        const xml = raw.replace(/<!-- akm-enabled:(?:true|false) -->/, `<!-- akm-enabled:${!disabledLabels.has(jobLabel)} -->`);
+        return {
+            id,
+            signature: normalizeSignature(xml),
+            ...metadata,
+        };
+    }
+    catch {
+        return { id, ...metadata };
+    }
+}
+/**
+ * Recover the bundle name embedded as a `--bundle <bundle>` pair in a plist's
+ * `<ProgramArguments>`. Returns undefined for the primary/default form.
+ */
+export function extractPlistTarget(xml) {
+    return extractPlistInvocation(xml)?.target;
+}
+export function extractPlistInvocation(xml) {
+    const block = xml.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/);
+    if (!block)
+        return undefined;
+    const args = [...block[1].matchAll(/<string>([\s\S]*?)<\/string>/g)].map((m) => decodeXmlEntities(m[1]));
+    return parseScheduledTaskArgv(args);
+}
+function decodeXmlEntities(value) {
+    return value
+        .replaceAll("&lt;", "<")
+        .replaceAll("&gt;", ">")
+        .replaceAll("&quot;", '"')
+        .replaceAll("&apos;", "'")
+        .replaceAll("&amp;", "&");
+}
 // ── XML builder (exported for tests) ────────────────────────────────────────
-export function buildPlistXml(task, akmArgv, logDir, pathEnv) {
+export function buildPlistXml(task, akmArgv, logDir, contextPath, target) {
     const spec = parseSchedule(task.schedule, "launchd");
     const trigger = translateToLaunchd(spec);
-    const argv = [...akmArgv, "tasks", "run", task.id];
+    const invocation = buildScheduledTaskInvocation(akmArgv, task.id, contextPath, target);
+    const argv = invocation.argv;
     const programArgs = argv.map((a) => `      <string>${escapeXml(a)}</string>`).join("\n");
     const logPath = path.join(logDir, `${task.id}.log`);
     const triggerXml = renderLaunchdTrigger(trigger);
-    const envVarsXml = pathEnv !== undefined
-        ? `  <key>EnvironmentVariables</key>\n  <dict>\n    <key>PATH</key>\n    <string>${escapeXml(pathEnv)}</string>\n  </dict>\n`
-        : "";
-    return launchdTemplate
+    const xml = launchdTemplate
+        .replace("<dict>\n", `<dict>\n  <!-- akm-enabled:${task.enabled} -->\n`)
         .replace("{{LABEL}}", LAUNCHD_LABEL_PREFIX + escapeXml(task.id))
         .replace("{{PROGRAM_ARGS}}", programArgs)
         .replaceAll("{{LOG_PATH}}", escapeXml(logPath))
-        .replace("{{ENV_VARS}}", envVarsXml)
+        .replace("{{ENV_VARS}}", "")
         .replace("{{TRIGGER_XML}}", triggerXml);
+    for (const char of xml) {
+        const code = char.codePointAt(0) ?? 0;
+        if (code <= 0x08 || code === 0x0b || code === 0x0c || (code >= 0x0e && code <= 0x1f)) {
+            throw new ConfigError("Launchd plist values must not contain XML-forbidden control characters.", "INVALID_CONFIG_FILE");
+        }
+    }
+    return xml;
 }
 function renderLaunchdTrigger(trigger) {
-    if (trigger.intervalSeconds !== undefined) {
-        return `  <key>StartInterval</key>
-  <integer>${trigger.intervalSeconds}</integer>`;
+    if (trigger.calendars !== undefined) {
+        const lines = ["  <key>StartCalendarInterval</key>", "  <array>"];
+        for (const calendar of trigger.calendars) {
+            lines.push(...renderCalendar(calendar, "    "));
+        }
+        lines.push("  </array>");
+        return lines.join("\n");
     }
     const cal = trigger.calendar ?? {};
-    const lines = ["  <key>StartCalendarInterval</key>", "  <dict>"];
-    if (cal.Minute !== undefined)
-        lines.push(`    <key>Minute</key><integer>${cal.Minute}</integer>`);
-    if (cal.Hour !== undefined)
-        lines.push(`    <key>Hour</key><integer>${cal.Hour}</integer>`);
-    if (cal.Day !== undefined)
-        lines.push(`    <key>Day</key><integer>${cal.Day}</integer>`);
-    if (cal.Month !== undefined)
-        lines.push(`    <key>Month</key><integer>${cal.Month}</integer>`);
-    if (cal.Weekday !== undefined)
-        lines.push(`    <key>Weekday</key><integer>${cal.Weekday}</integer>`);
-    lines.push("  </dict>");
+    const lines = ["  <key>StartCalendarInterval</key>", ...renderCalendar(cal, "  ")];
     return lines.join("\n");
 }
+function renderCalendar(calendar, indent) {
+    const valueIndent = `${indent}  `;
+    const lines = [`${indent}<dict>`];
+    if (calendar.Minute !== undefined) {
+        lines.push(`${valueIndent}<key>Minute</key><integer>${calendar.Minute}</integer>`);
+    }
+    if (calendar.Hour !== undefined)
+        lines.push(`${valueIndent}<key>Hour</key><integer>${calendar.Hour}</integer>`);
+    if (calendar.Day !== undefined)
+        lines.push(`${valueIndent}<key>Day</key><integer>${calendar.Day}</integer>`);
+    if (calendar.Month !== undefined)
+        lines.push(`${valueIndent}<key>Month</key><integer>${calendar.Month}</integer>`);
+    if (calendar.Weekday !== undefined) {
+        lines.push(`${valueIndent}<key>Weekday</key><integer>${calendar.Weekday}</integer>`);
+    }
+    lines.push(`${indent}</dict>`);
+    return lines;
+}
+function normalizeSignature(xml) {
+    return xml.replace(/\r\n/g, "\n").trim();
+}
+function readDisabledLabels(exec) {
+    try {
+        const result = exec.run(["launchctl", "print-disabled", `gui/${exec.uid()}`]);
+        if (result.status !== 0)
+            return undefined;
+        return parseDisabledLabels(result.stdout);
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseDisabledLabels(output) {
+    const envelope = /^\s*disabled services\s*=\s*\{([\s\S]*)\}\s*$/.exec(output);
+    if (!envelope)
+        return undefined;
+    const disabled = new Set();
+    let body = envelope[1];
+    while (body.trim()) {
+        const entry = /^\s*"([^"\r\n]+)"\s*=>\s*(true|false|enabled|disabled)\s*/.exec(body);
+        if (!entry)
+            return undefined;
+        if (entry[2] === "true" || entry[2] === "disabled")
+            disabled.add(entry[1]);
+        body = body.slice(entry[0].length);
+    }
+    return disabled;
+}
+function isServiceNotFoundResult(result) {
+    const output = `${result.stderr ?? ""}\n${result.stdout ?? ""}`;
+    return /could not find service\b|service\b.*\bnot found\b|\bno such process\b/i.test(output);
+}
 function defaultAgentsDir() {
     // launchd's per-user LaunchAgents live under the user's home directory.
     // If we can't determine HOME, refuse rather than silently producing a
     // relative path that would write somewhere unexpected.
     const home = os.homedir();
     if (!home) {
-        throw new ConfigError("Cannot determine user home directory; launchd backend requires HOME to locate ~/Library/LaunchAgents.", "INVALID_CONFIG_FILE", "Set $HOME (POSIX) or the equivalent before running `akm tasks` on macOS.");
+        throw new ConfigError("Cannot determine user home directory; launchd backend requires HOME to locate ~/Library/LaunchAgents.", "INVALID_CONFIG_FILE", "Set $HOME (POSIX) or the equivalent before running `akm task` on macOS.");
     }
     return path.join(home, "Library", "LaunchAgents");
 }
@@ -162,9 +393,15 @@ function defaultLaunchdExec() {
 function defaultLaunchdFs() {
     return {
         ...nodeFs(),
+        readFile(file) {
+            return fs.readFileSync(file, "utf8");
+        },
         removeFile(file) {
             fs.rmSync(file, { force: true });
         },
+        replaceFile(source, destination) {
+            fs.renameSync(source, destination);
+        },
         list(dir) {
             try {
                 return fs.readdirSync(dir);