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

package/dist/tasks/backends/cron.js

@@ -1,13 +1,13 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // 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/.
-// crontab backend for `akm tasks` (Linux default).
+// crontab backend for `akm task` (Linux default).
 //
 // Each akm-owned entry is wrapped in markers so a hand-edited crontab keeps
 // its other lines untouched:
 //
 //     # akm:task <id> BEGIN
-//     [SCHED] /abs/akm tasks run <id> >> /home/.../tasks/logs/<id>.log 2>&1
+//     [SCHED] /abs/akm task run <id> >> /home/.../tasks/logs/<id>.log 2>&1
 //     # akm:task <id> END
 //
 // The backend reads/writes the user's crontab via `crontab -l` and
@@ -25,59 +25,100 @@
 //
 // Tests inject a fake exec so unit tests don't touch the real crontab.
 import { spawnSync } from "node:child_process";
-import fs from "node:fs";
 import path from "node:path";
 import { ConfigError } from "../../core/errors.js";
 import { getTaskLogDir } from "../../core/paths.js";
 import { resolveAkmInvocation } from "../resolve-akm-bin.js";
 import { parseSchedule, translateToCron } from "../schedule.js";
-const BEGIN = (id) => `# akm:task ${id} BEGIN`;
-const END = (id) => `# akm:task ${id} END`;
+import { buildScheduledTaskInvocation, parseScheduledTaskArgv, resolveScheduledTaskContext, schedulerContextDescriptor, schedulerContextPath, } from "../scheduler-invocation.js";
+import { nodeFs, throwIfNotOk } from "./exec-utils.js";
+const BEGIN = (id) => `# akm:task ${assertCronValue(id)} BEGIN`;
+const END = (id) => `# akm:task ${assertCronValue(id)} END`;
 const DISABLED_PREFIX = "# akm:disabled ";
 const BLOCK_RE = /^# akm:task ([\w.@:_-]+) BEGIN$/;
+const BLOCK_END_RE = /^# akm:task ([\w.@:_-]+) END$/;
+export const PORTABLE_CRON_LINE_LIMIT = 1000;
 export function CRON_BACKEND(options = {}) {
     const exec = options.exec ?? defaultCronExec();
+    const fsLike = options.fs ?? nodeFs();
     const logDir = options.logDir ?? getTaskLogDir();
     const akmArgv = options.akmArgv ?? resolveAkmInvocation().argv;
+    const envPath = options.envPath === false ? undefined : (options.envPath ?? process.env.PATH);
+    const scheduledContext = options.scheduledContext ?? resolveScheduledTaskContext();
+    const defaultContextPath = schedulerContextPath(schedulerContextDescriptor(scheduledContext, envPath ?? ""));
     return {
         name: "cron",
-        install(task) {
+        install(task, opts) {
             // Create the log directory before writing the crontab line — cron
             // appends with `>>` and the surrounding shell will fail the entire
             // entry if the parent directory doesn't exist.
-            ensureDir(logDir);
-            const cronLine = buildCronLine(task, akmArgv, logDir);
+            const cronLine = buildCronLine(task, [...(opts?.binding ?? akmArgv)], logDir, opts?.contextPath ?? defaultContextPath, opts?.target);
+            assertPortableCronLine(cronLine);
+            fsLike.ensureDir(logDir);
             const existing = readCrontab(exec);
             const block = renderBlock(task.id, cronLine, task.enabled);
             const next = upsertBlock(existing, task.id, block);
-            writeCrontab(exec, next);
+            replaceCrontab(exec, existing, next);
         },
         uninstall(id) {
             const existing = readCrontab(exec);
             const next = removeBlock(existing, id);
-            writeCrontab(exec, next);
+            replaceCrontab(exec, existing, next);
         },
         setEnabled(id, enabled) {
             const existing = readCrontab(exec);
             const next = toggleBlock(existing, id, enabled);
-            writeCrontab(exec, next);
+            replaceCrontab(exec, existing, next);
         },
         list() {
             const existing = readCrontab(exec);
-            return listBlocks(existing).map(({ id, body }) => ({ id, signature: normalizeSignature(body) }));
+            const refs = [];
+            for (const { id, body } of listBlocks(existing)) {
+                const installed = extractCronInvocation(body);
+                // An invocation that no longer parses (e.g. a pre-0.9 `tasks run`
+                // entry surviving the scheduler-ABI respelling, or any other
+                // foreign/malformed line between our markers) is an orphan of its
+                // marker id, not a hard failure: omit it here so `akmTasksSync`
+                // treats the id as "not present" and reinstalls it from the current
+                // task file — going through the normal eligibility/`--rebind` gate
+                // exactly like a fresh install.
+                if (!installed)
+                    continue;
+                refs.push({
+                    id,
+                    signature: normalizeSignature(body),
+                    ...(installed.target !== undefined ? { target: installed.target } : {}),
+                    binding: installed.binding,
+                    contextPath: installed.contextPath,
+                });
+            }
+            return refs;
+        },
+        listForRebind() {
+            const existing = readCrontab(exec);
+            return listBlocks(existing).map(({ id, body }) => {
+                const installed = extractCronInvocation(body);
+                return {
+                    id,
+                    signature: normalizeSignature(body),
+                    ...(installed?.target !== undefined ? { target: installed.target } : {}),
+                };
+            });
         },
-        expectedSignature(task) {
-            const cronLine = buildCronLine(task, akmArgv, logDir);
+        expectedSignature(task, opts) {
+            const cronLine = buildCronLine(task, [...(opts?.binding ?? akmArgv)], logDir, opts?.contextPath ?? defaultContextPath, opts?.target);
+            assertPortableCronLine(cronLine);
             return normalizeSignature(cronBlockBody(cronLine, task.enabled));
         },
     };
 }
 // ── helpers (exported for tests) ────────────────────────────────────────────
-export function buildCronLine(task, akmArgv, logDir) {
+export function buildCronLine(task, akmArgv, logDir, contextPath, target) {
     const spec = parseSchedule(task.schedule, "cron");
     const cronExpr = translateToCron(spec);
     const logPath = path.join(logDir, `${task.id}.log`);
-    const cmd = [...akmArgv, "tasks", "run", task.id].map((part) => quoteForCron(part)).join(" ");
+    const invocation = buildScheduledTaskInvocation(akmArgv, task.id, contextPath, target);
+    const cmd = invocation.argv.map((part) => quoteForCron(part)).join(" ");
     return `${cronExpr} ${cmd} >> ${quoteForCron(logPath)} 2>&1`;
 }
 /** The crontab line as it appears inside a block — commented when disabled. */
@@ -93,28 +134,97 @@ export function renderBlock(id, cronLine, enabled) {
  * drift signature, and exported for tests.
  */
 export function listBlocks(existing) {
+    return parseBlocks(existing).map(({ id, body }) => ({ id, body }));
+}
+function parseBlocks(existing) {
     const out = [];
     const lines = existing.split(/\r?\n/);
     let currentId = null;
+    let start = -1;
     let body = [];
-    for (const line of lines) {
+    for (const [index, line] of lines.entries()) {
         const begin = line.match(BLOCK_RE);
         if (begin) {
+            if (currentId !== null)
+                throw malformedBlockError(currentId);
             currentId = begin[1];
+            start = index;
             body = [];
             continue;
         }
-        if (currentId !== null && line === END(currentId)) {
-            out.push({ id: currentId, body: body.join("\n") });
+        const end = line.match(BLOCK_END_RE);
+        if (end) {
+            if (currentId === null || end[1] !== currentId)
+                throw malformedBlockError(currentId ?? end[1]);
+            out.push({ id: currentId, body: body.join("\n"), start, end: index });
             currentId = null;
+            start = -1;
             body = [];
             continue;
         }
         if (currentId !== null)
             body.push(line);
     }
+    if (currentId !== null)
+        throw malformedBlockError(currentId);
     return out;
 }
+function malformedBlockError(id) {
+    return new ConfigError(`Crontab contains a malformed akm task block for "${id}"; refusing to modify it.`, "INVALID_CONFIG_FILE");
+}
+/**
+ * Recover the bundle name from an installed cron block body by reading the
+ * `--bundle <bundle>` token embedded in the scheduled `akm task run …`
+ * invocation. Returns undefined for the byte-identical primary/default form
+ * (no `--bundle`). Bundle slugs never contain whitespace (config-schema
+ * `isBundleSlug`), so the quoted token is a single whitespace-delimited field
+ * even when cron-quoted — a plain field split recovers it, and
+ * the shell-word parser below reverses the quoting.
+ */
+export function extractInstalledTarget(body) {
+    return extractCronInvocation(body)?.target;
+}
+export function extractCronInvocation(body) {
+    const line = body.startsWith(DISABLED_PREFIX) ? body.slice(DISABLED_PREFIX.length) : body;
+    const fields = splitCronShellWords(line);
+    if (fields.length < 6)
+        return undefined;
+    let commandStart = 5;
+    while (commandStart < fields.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(fields[commandStart]))
+        commandStart += 1;
+    const redirectIndex = fields.indexOf(">>", commandStart);
+    if (redirectIndex === -1)
+        return undefined;
+    return parseScheduledTaskArgv(fields.slice(commandStart, redirectIndex));
+}
+/** Reverse {@link quoteForCron} for a single whitespace-free token. */
+function splitCronShellWords(value) {
+    const words = [];
+    let current = "";
+    let quoted = false;
+    for (let index = 0; index < value.length; index += 1) {
+        const char = value[index];
+        if (char === "'") {
+            quoted = !quoted;
+            continue;
+        }
+        if (char === "\\" && index + 1 < value.length) {
+            current += value[index + 1];
+            index += 1;
+            continue;
+        }
+        if (!quoted && /\s/.test(char)) {
+            if (current)
+                words.push(current);
+            current = "";
+            continue;
+        }
+        current += char;
+    }
+    if (current)
+        words.push(current);
+    return words;
+}
 /** Collapse incidental whitespace so signature comparison ignores it. */
 function normalizeSignature(body) {
     return body
@@ -131,27 +241,17 @@ export function upsertBlock(existing, id, block) {
 }
 export function removeBlock(existing, id) {
     const lines = existing.split(/\r?\n/);
-    const out = [];
-    let inBlock = false;
-    for (const line of lines) {
-        if (!inBlock && line === BEGIN(id)) {
-            inBlock = true;
-            continue;
-        }
-        if (inBlock && line === END(id)) {
-            inBlock = false;
-            continue;
-        }
-        if (inBlock)
-            continue;
-        out.push(line);
-    }
+    const blocks = parseBlocks(existing).filter((block) => block.id === id);
+    if (blocks.length === 0)
+        return existing;
+    const out = lines.filter((_, index) => !blocks.some((block) => index >= block.start && index <= block.end));
     // Collapse trailing blank lines.
     while (out.length > 0 && out[out.length - 1] === "")
         out.pop();
     return out.join("\n");
 }
 export function toggleBlock(existing, id, enabled) {
+    parseBlocks(existing);
     const lines = existing.split(/\r?\n/);
     const out = [];
     let inBlock = false;
@@ -184,12 +284,29 @@ export function toggleBlock(existing, id, enabled) {
     return out.join("\n");
 }
 function quoteForCron(part) {
+    assertCronValue(part);
     // crontab passes the rest of the line to /bin/sh -c, so quote anything that
     // isn't a plain shell-safe token. Single-quote and escape embedded single
-    // quotes via the standard shell idiom: `'foo'\''bar'`.
+    // quotes via the standard shell idiom: `'foo'\''bar'`. Cron interprets `%`
+    // before the shell, even inside quotes, so close the quote around its escape.
     if (/^[A-Za-z0-9_\-./@:%=+,]+$/.test(part))
-        return part;
-    return `'${part.replace(/'/g, `'\\''`)}'`;
+        return part.replaceAll("%", "\\%");
+    return `'${part.replace(/'/g, `'\\''`).replace(/%/g, `'\\%'`)}'`;
+}
+function assertCronValue(value) {
+    for (const char of value) {
+        const code = char.codePointAt(0) ?? 0;
+        if (code < 0x20 || (code >= 0x7f && code <= 0x9f)) {
+            throw new ConfigError("Cron values must not contain control characters.", "INVALID_CONFIG_FILE");
+        }
+    }
+    return value;
+}
+function assertPortableCronLine(line) {
+    const bytes = Buffer.byteLength(line, "utf8");
+    if (bytes > PORTABLE_CRON_LINE_LIMIT) {
+        throw new ConfigError(`Generated cron definition is ${bytes} bytes; portable cron command lines are limited to ${PORTABLE_CRON_LINE_LIMIT} bytes.`, "INVALID_CONFIG_FILE");
+    }
 }
 function readCrontab(exec) {
     const result = exec.read();
@@ -204,18 +321,24 @@ function readCrontab(exec) {
 }
 function writeCrontab(exec, content) {
     const normalised = content.endsWith("\n") || content.length === 0 ? content : `${content}\n`;
-    const result = exec.write(normalised);
-    if (result.status !== 0) {
-        throw new ConfigError(`crontab - failed (exit ${result.status}): ${result.stderr || result.stdout || "no output"}.`, "INVALID_CONFIG_FILE", "Ensure the `crontab` binary is on PATH and your shell can write the user crontab.");
-    }
+    throwIfNotOk(exec.write(normalised), {
+        message: (r) => `crontab - failed (exit ${r.status}): ${r.stderr || r.stdout || "no output"}.`,
+        hint: "Ensure the `crontab` binary is on PATH and your shell can write the user crontab.",
+    });
 }
-function ensureDir(dir) {
+function replaceCrontab(exec, existing, next) {
     try {
-        fs.mkdirSync(dir, { recursive: true });
+        writeCrontab(exec, next);
     }
-    catch {
-        // Best-effort: the install will surface a clearer error if the cron
-        // line later fails at runtime due to a missing redirection target.
+    catch (err) {
+        try {
+            writeCrontab(exec, existing);
+        }
+        catch (rollbackError) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new AggregateError([err, rollbackError], `${message}; restoring the prior crontab also failed.`);
+        }
+        throw err;
     }
 }
 function defaultCronExec() {

package/dist/tasks/backends/exec-utils.js

@@ -3,6 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
+import { ConfigError } from "../../core/errors.js";
 /**
  * Default exec strategy: run commands synchronously via {@link spawnCommand}.
  *
@@ -40,13 +41,85 @@ export function nodeFs() {
  */
 export function spawnCommand(args) {
     const [bin, ...rest] = args;
-    const r = spawnSync(bin, rest, { encoding: "utf8" });
+    const r = spawnSync(bin, rest);
     return {
         status: r.status ?? 1,
-        stdout: r.stdout ?? "",
-        stderr: r.stderr ?? "",
+        stdout: decodeCommandOutput(r.stdout),
+        stderr: decodeCommandOutput(r.stderr),
     };
 }
+/**
+ * Throw a `ConfigError` (code `INVALID_CONFIG_FILE`) when `result` doesn't
+ * satisfy `isOk` (default: `status === 0`); otherwise return `result`
+ * unchanged. Factors out the "run a native scheduler command, throw a
+ * formatted error on a bad exit" idiom repeated across the cron/launchd/
+ * schtasks backends — NOT the accumulate-into-`rollbackErrors`-and-continue
+ * idiom used during rollback, which stays inline (throwing there would
+ * change control flow: rollback needs to keep trying its remaining steps).
+ */
+export function throwIfNotOk(result, options) {
+    const ok = options.isOk ? options.isOk(result) : result.status === 0;
+    if (!ok) {
+        throw new ConfigError(options.message(result), "INVALID_CONFIG_FILE", options.hint);
+    }
+    return result;
+}
+/** {@link throwIfNotOk} for the common case of running `args` via `exec` first. */
+export function runOrThrow(exec, args, options) {
+    return throwIfNotOk(exec.run(args), options);
+}
+/** Decode native command output, including the UTF-16 XML emitted by schtasks. */
+export function decodeCommandOutput(output) {
+    if (output === null || output === undefined)
+        return "";
+    if (typeof output === "string")
+        return output.replace(/^\uFEFF/, "");
+    if (output.length === 0)
+        return "";
+    if (output[0] === 0xef && output[1] === 0xbb && output[2] === 0xbf) {
+        return output.toString("utf8", 3);
+    }
+    if (output[0] === 0xff && output[1] === 0xfe) {
+        return output.subarray(2).toString("utf16le");
+    }
+    if (output[0] === 0xfe && output[1] === 0xff) {
+        return decodeUtf16Be(output.subarray(2));
+    }
+    const pairs = Math.floor(output.length / 2);
+    if (pairs > 1) {
+        let evenNuls = 0;
+        let oddNuls = 0;
+        for (let i = 0; i < pairs * 2; i += 2) {
+            if (output[i] === 0)
+                evenNuls += 1;
+            if (output[i + 1] === 0)
+                oddNuls += 1;
+        }
+        if (oddNuls / pairs > 0.6)
+            return output.toString("utf16le");
+        if (evenNuls / pairs > 0.6)
+            return decodeUtf16Be(output);
+    }
+    return output.toString("utf8");
+}
+/** Return XML with the declaration required by Task Scheduler's UTF-16 input. */
+export function normalizeXmlForUtf16File(xml) {
+    const source = xml.replace(/^\uFEFF/, "");
+    const declaration = '<?xml version="1.0" encoding="UTF-16"?>';
+    if (/^<\?xml\b[^?]*\?>/i.test(source)) {
+        return source.replace(/^<\?xml\b[^?]*\?>/i, declaration);
+    }
+    return `${declaration}\n${source}`;
+}
+function decodeUtf16Be(output) {
+    const evenLength = output.length - (output.length % 2);
+    const swapped = Buffer.allocUnsafe(evenLength);
+    for (let i = 0; i < evenLength; i += 2) {
+        swapped[i] = output[i + 1];
+        swapped[i + 1] = output[i];
+    }
+    return swapped.toString("utf16le");
+}
 /**
  * Escape a string for safe embedding in an XML attribute or text node.
  */

package/dist/tasks/backends/index.js

@@ -4,14 +4,13 @@
 import { CRON_BACKEND } from "./cron.js";
 import { LAUNCHD_BACKEND } from "./launchd.js";
 import { SCHTASKS_BACKEND } from "./schtasks.js";
-let backendsOverrides;
-/** TEST-ONLY. Swap backend selection; pass undefined to restore the real implementations. */
-export function _setBackendsForTests(fakes) {
-    backendsOverrides = fakes;
-}
+// WI-9.10e: the former `_setBackendsForTests` module-mutation seam was retired.
+// Tests inject a fake `TaskBackend` directly via the `deps.backend` parameter
+// the `akm task` mutation entries already accept (the backend carries its own
+// `name`), so no module-level override binding is needed. `selectBackend`'s
+// `options.platform` covers the platform-steering the seam's second override
+// used to provide.
 export function selectBackend(options = {}) {
-    if (backendsOverrides?.selectBackend)
-        return backendsOverrides.selectBackend(options);
     const platform = options.platform ?? process.platform;
     switch (platform) {
         case "win32":
@@ -23,8 +22,6 @@ export function selectBackend(options = {}) {
     }
 }
 export function backendNameForPlatform(platform = process.platform) {
-    if (backendsOverrides?.backendNameForPlatform)
-        return backendsOverrides.backendNameForPlatform(platform);
     if (platform === "win32")
         return "schtasks";
     if (platform === "darwin")