akm-cli 0.9.0-rc.9 → 0.9.1-beta.1

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,7 @@ 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 { buildScheduledTaskInvocation, resolveScheduledTaskContext, } from "../scheduler-invocation.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 = {}) {
@@ -49,6 +49,7 @@ export function LAUNCHD_BACKEND(options = {}) {
             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)], {
@@ -57,10 +58,10 @@ export function LAUNCHD_BACKEND(options = {}) {
     };
     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.
-            const xml = buildPlistXml(task, akmArgv, logDir, pathEnv(), scheduledContext);
+            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;
@@ -201,55 +202,101 @@ export function LAUNCHD_BACKEND(options = {}) {
             if (ids.length === 0)
                 return [];
             const disabledLabels = readDisabledLabels(exec);
-            return ids.map((id) => {
-                if (!disabledLabels)
-                    return { id };
-                try {
-                    const loaded = exec.run(["launchctl", "print", target(id)]);
-                    if (loaded.status !== 0)
-                        return { id };
-                }
-                catch {
-                    return { id };
-                }
-                try {
-                    const xml = fsLike
-                        .readFile(plistPath(id))
-                        .replace(/<!-- akm-enabled:(?:true|false) -->/, `<!-- akm-enabled:${!disabledLabels.has(label(id))} -->`);
-                    return { id, signature: normalizeSignature(xml) };
-                }
-                catch {
-                    return { id };
-                }
-            });
+            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) {
-            return normalizeSignature(buildPlistXml(task, akmArgv, logDir, pathEnv(), scheduledContext));
+        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, scheduledContext) {
+export function buildPlistXml(task, akmArgv, logDir, contextPath, target) {
     const spec = parseSchedule(task.schedule, "launchd");
     const trigger = translateToLaunchd(spec);
-    const invocation = buildScheduledTaskInvocation(akmArgv, task.id, scheduledContext);
+    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 environment = { ...invocation.environment };
-    if (pathEnv !== undefined)
-        environment.PATH = pathEnv;
-    const envEntries = Object.entries(environment)
-        .map(([key, value]) => `    <key>${key}</key>\n    <string>${escapeXml(value)}</string>`)
-        .join("\n");
-    const envVarsXml = `  <key>EnvironmentVariables</key>\n  <dict>\n${envEntries}\n  </dict>\n`;
     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;
@@ -330,7 +377,7 @@ function defaultAgentsDir() {
     // 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");
 }

package/dist/tasks/backends/schtasks.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/.
 /**
- * schtasks.exe backend for `akm tasks` (Windows default).
+ * schtasks.exe backend for `akm task` (Windows default).
  *
  * Each task is registered under the `\akm\` Task Scheduler folder so the
  * backend never touches user-managed tasks. The full task definition is
@@ -37,7 +37,7 @@ import { ConfigError } from "../../core/errors.js";
 import { getTaskLogDir } from "../../core/paths.js";
 import { resolveAkmInvocation } from "../resolve-akm-bin.js";
 import { parseSchedule, translateToSchtasks } from "../schedule.js";
-import { buildScheduledTaskInvocation, resolveScheduledTaskContext, } from "../scheduler-invocation.js";
+import { buildScheduledTaskInvocation, parseScheduledTaskArgv, resolveScheduledTaskContext, schedulerContextDescriptor, schedulerContextPath, } from "../scheduler-invocation.js";
 import { escapeXml, nodeExec, nodeFs, normalizeXmlForUtf16File, runOrThrow, } from "./exec-utils.js";
 export const DEFAULT_FOLDER_PREFIX = "\\akm\\";
 const SIGNATURE_PREFIX = "akm:v1:";
@@ -48,12 +48,19 @@ export function SCHTASKS_BACKEND(options = {}) {
     const logDir = options.logDir ?? getTaskLogDir();
     const folder = options.folderPrefix ?? DEFAULT_FOLDER_PREFIX;
     const scheduledContext = options.scheduledContext ?? resolveScheduledTaskContext();
+    const defaultContextPath = schedulerContextPath(schedulerContextDescriptor(scheduledContext, process.env.PATH ?? ""));
     const userSid = options.userSid ?? resolveCurrentUserSid(exec);
     const taskName = (id) => `${folder}${id}`;
     return {
         name: "schtasks",
-        install(task) {
-            const xml = normalizeXmlForUtf16File(buildSchtasksXml(task, akmArgv, logDir, { folderPrefix: folder, scheduledContext, userSid }));
+        install(task, opts) {
+            const xml = normalizeXmlForUtf16File(buildSchtasksXml(task, akmArgv, logDir, {
+                folderPrefix: folder,
+                contextPath: opts?.contextPath ?? defaultContextPath,
+                userSid,
+                binding: [...(opts?.binding ?? akmArgv)],
+                ...(opts?.target !== undefined ? { target: opts.target } : {}),
+            }));
             const query = runOrThrow(exec, ["schtasks", "/Query", "/TN", taskName(task.id), "/XML"], {
                 isOk: (r) => r.status === 0 || isMissingTaskResult(r),
                 message: (r) => `schtasks /Query failed (exit ${r.status}): ${r.stderr || r.stdout || "no output"}.`,
@@ -146,26 +153,142 @@ export function SCHTASKS_BACKEND(options = {}) {
                     ids.push(name.slice(folder.length));
                 }
             }
-            return ids.map((id) => {
+            const refs = [];
+            for (const id of ids) {
                 const query = runOrThrow(exec, ["schtasks", "/Query", "/TN", taskName(id), "/XML"], {
                     message: (r) => `schtasks /Query /XML for "${taskName(id)}" failed (exit ${r.status}): ${r.stderr || r.stdout || "no output"}.`,
                 });
                 const signature = installedSignature(query.stdout);
-                return signature === undefined ? { id } : { id, signature };
+                const installed = extractSchtasksInvocation(query.stdout);
+                // 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: omit it so `akmTasksSync` treats the
+                // id as "not present" and reinstalls it from the current task file.
+                if (!installed)
+                    continue;
+                refs.push({
+                    id,
+                    ...(signature !== undefined ? { signature } : {}),
+                    ...(installed.target !== undefined ? { target: installed.target } : {}),
+                    binding: installed.binding,
+                    contextPath: installed.contextPath,
+                });
+            }
+            return refs;
+        },
+        listForRebind() {
+            const r = runOrThrow(exec, ["schtasks", "/Query", "/FO", "CSV", "/NH"], {
+                message: (res) => `schtasks /Query failed (exit ${res.status}): ${res.stderr || res.stdout || "no output"}.`,
             });
+            const refs = [];
+            for (const line of (r.stdout ?? "").split(/\r?\n/)) {
+                const match = line.match(/^"([^"]+)",/);
+                const name = match?.[1];
+                if (!name?.startsWith(folder))
+                    continue;
+                const id = name.slice(folder.length);
+                const query = runOrThrow(exec, ["schtasks", "/Query", "/TN", taskName(id), "/XML"], {
+                    message: (result) => `schtasks /Query /XML for "${taskName(id)}" failed (exit ${result.status}): ${result.stderr || result.stdout || "no output"}.`,
+                });
+                const signature = installedSignature(query.stdout);
+                const installed = extractSchtasksInvocation(query.stdout);
+                refs.push({
+                    id,
+                    ...(signature !== undefined ? { signature } : {}),
+                    ...(installed?.target !== undefined ? { target: installed.target } : {}),
+                });
+            }
+            return refs;
         },
-        expectedSignature(task) {
-            const signature = taskXmlSignature(buildSchtasksXml(task, akmArgv, logDir, { folderPrefix: folder, scheduledContext, userSid }));
+        expectedSignature(task, opts) {
+            const signature = taskXmlSignature(buildSchtasksXml(task, akmArgv, logDir, {
+                folderPrefix: folder,
+                contextPath: opts?.contextPath ?? defaultContextPath,
+                userSid,
+                binding: [...(opts?.binding ?? akmArgv)],
+                ...(opts?.target !== undefined ? { target: opts.target } : {}),
+            }));
             if (signature === undefined)
                 throw new Error("Failed to fingerprint generated Task Scheduler XML.");
             return signature;
         },
     };
 }
+/**
+ * Recover the bundle name embedded as a `--bundle <bundle>` pair in the
+ * PowerShell `<Arguments>` of an installed Task Scheduler definition. Returns
+ * undefined for the primary/default form.
+ */
+export function extractSchtasksTarget(xml) {
+    return extractSchtasksInvocation(xml)?.target;
+}
+export function extractSchtasksInvocation(xml) {
+    const argsElement = xml.match(/<(?:[\w.-]+:)?Arguments>([\s\S]*?)<\/(?:[\w.-]+:)?Arguments>/i);
+    if (!argsElement)
+        return undefined;
+    const commandLine = decodeXml(argsElement[1]);
+    const invocationStart = findPowerShellInvocationOperator(commandLine);
+    if (invocationStart === undefined)
+        return undefined;
+    return parseScheduledTaskArgv(parsePowerShellSingleQuotedArgs(commandLine, invocationStart + 1));
+}
+function findPowerShellInvocationOperator(script) {
+    let inSingleQuote = false;
+    for (let index = 0; index < script.length; index += 1) {
+        const char = script[index];
+        if (char === "'") {
+            if (inSingleQuote && script[index + 1] === "'") {
+                index += 1;
+            }
+            else {
+                inSingleQuote = !inSingleQuote;
+            }
+            continue;
+        }
+        if (!inSingleQuote && char === "&" && /\s/.test(script[index + 1] ?? ""))
+            return index;
+    }
+    return undefined;
+}
+function parsePowerShellSingleQuotedArgs(script, start) {
+    const argv = [];
+    let index = start;
+    while (index < script.length) {
+        while (/\s/.test(script[index] ?? ""))
+            index += 1;
+        if (script[index] === ";" || script[index] === '"' || index >= script.length)
+            break;
+        if (script[index] !== "'")
+            return [];
+        index += 1;
+        let value = "";
+        let closed = false;
+        while (index < script.length) {
+            const char = script[index];
+            if (char !== "'") {
+                value += char;
+                index += 1;
+                continue;
+            }
+            if (script[index + 1] === "'") {
+                value += "'";
+                index += 2;
+                continue;
+            }
+            index += 1;
+            closed = true;
+            break;
+        }
+        if (!closed)
+            return [];
+        argv.push(value);
+    }
+    return argv;
+}
 export function buildSchtasksXml(task, akmArgv, logDir, options) {
     const folder = options.folderPrefix ?? DEFAULT_FOLDER_PREFIX;
     const now = options.now ? options.now() : new Date();
-    const definition = buildSchtasksDefinition(task, akmArgv, logDir, folder, options.scheduledContext, options.userSid);
+    const definition = buildSchtasksDefinition(task, options.binding ?? akmArgv, logDir, folder, options.contextPath, options.userSid, options.target);
     const triggerXml = renderSchtasksTrigger(definition.trigger, now);
     return schtasksTemplate
         .replaceAll("{{TASK_ID}}", escapeXml(task.id))
@@ -178,15 +301,12 @@ export function buildSchtasksXml(task, akmArgv, logDir, options) {
         .replace("{{ARGS}}", escapeXml(definition.args))
         .replace("{{LOG_PATH}}", escapeXml(definition.logPath));
 }
-function buildSchtasksDefinition(task, akmArgv, logDir, folder, scheduledContext, userSid) {
+function buildSchtasksDefinition(task, akmArgv, logDir, folder, contextPath, userSid, target) {
     const spec = parseSchedule(task.schedule, "schtasks");
     const trigger = translateToSchtasks(spec);
-    const invocation = buildScheduledTaskInvocation(akmArgv, task.id, scheduledContext);
-    const environment = Object.entries(invocation.environment)
-        .map(([key, value]) => `$env:${key}=${quotePowerShell(value)}`)
-        .join("; ");
+    const invocation = buildScheduledTaskInvocation(akmArgv, task.id, contextPath, target);
     const invoke = `& ${invocation.argv.map((arg) => quotePowerShell(arg)).join(" ")}`;
-    const script = `${environment}; ${invoke}; exit $LASTEXITCODE`;
+    const script = `${invoke}; exit $LASTEXITCODE`;
     const command = "powershell.exe";
     const args = ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", script].map(quoteArg).join(" ");
     const logPath = path.join(logDir, `${task.id}.log`);

package/dist/tasks/embedded.js

@@ -2,14 +2,18 @@
 // 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/.
 /**
- * Embedded core task templates.
+ * Embedded task templates.
  *
- * A curated set of read-only YAML task templates ships inside the akm binary
- * under `src/assets/tasks/core/`. They are resolved at runtime via
+ * Curated sets of read-only YAML task templates ship inside the akm binary
+ * under `src/assets/tasks/<category>/` — `core/` (general-purpose maintenance)
+ * and `improve/` (the maintainer-oriented multi-cadence improve schedule,
+ * folded in from the retired `registerDefaultTasks`/`akm tasks init` path in
+ * 0.9, S6). Every category subdirectory is enumerated the same way; adding a
+ * new one needs no code change here. Templates are resolved at runtime via
  * `import.meta.dir` (mirroring `SKELETON_DIR` in
  * src/commands/stash-skeleton.ts) and are NOT written to any stash at
- * install/init time — the `akm setup` wizard copies a template into the
- * primary stash only when the user opts in (copy-on-enable).
+ * install time — the `akm setup` wizard copies a template into the primary
+ * stash only when the user opts in (copy-on-enable).
  *
  * Each entry exposes the parsed `command`, `schedule`, and `description`
  * alongside the raw `yaml`, so the wizard can both render a choice and write
@@ -17,57 +21,69 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { parse as yamlParse } from "yaml";
 import { getDirname } from "../runtime.js";
-/** Directory holding the bundled core task templates. */
-const CORE_TASKS_DIR = path.join(getDirname(import.meta.url), "../assets/tasks/core");
+import { parseTaskDocument } from "./parser.js";
+/** Directory holding the bundled task template categories. */
+const TASKS_ASSETS_DIR = path.join(getDirname(import.meta.url), "../assets/tasks");
 /**
- * Enumerate the embedded core task templates from the bundled assets
- * directory. Sorted by id for deterministic ordering. Returns an empty array
- * if the directory is missing (defensive — a build without assets should not
- * crash the wizard).
+ * Enumerate the embedded task templates from every category subdirectory of
+ * the bundled assets directory. Sorted by category then id for deterministic
+ * ordering. Returns an empty array if the directory is missing (defensive —
+ * a build without assets should not crash the wizard).
  */
 export function listEmbeddedTasks() {
-    let entries;
+    let categories;
     try {
-        entries = fs.readdirSync(CORE_TASKS_DIR);
+        categories = fs
+            .readdirSync(TASKS_ASSETS_DIR, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
     }
     catch {
         return [];
     }
     const tasks = [];
-    for (const entry of entries.sort()) {
-        if (!entry.endsWith(".yml"))
-            continue;
-        const id = entry.slice(0, -4);
-        const filePath = path.join(CORE_TASKS_DIR, entry);
-        let yaml;
+    for (const category of categories) {
+        const categoryDir = path.join(TASKS_ASSETS_DIR, category);
+        let entries;
         try {
-            yaml = fs.readFileSync(filePath, "utf8");
+            entries = fs.readdirSync(categoryDir);
         }
         catch {
             continue;
         }
-        let doc;
-        try {
-            doc = yamlParse(yaml) ?? {};
-        }
-        catch {
-            continue;
+        for (const entry of entries.sort()) {
+            if (!entry.endsWith(".yml"))
+                continue;
+            const id = entry.slice(0, -4);
+            const filePath = path.join(categoryDir, entry);
+            let yaml;
+            try {
+                yaml = fs.readFileSync(filePath, "utf8");
+            }
+            catch {
+                continue;
+            }
+            let task;
+            try {
+                task = parseTaskDocument({ yaml, filePath, id });
+            }
+            catch {
+                continue;
+            }
+            if (task.target.kind !== "command")
+                continue;
+            tasks.push({
+                id,
+                label: `${category}/${id}`,
+                command: task.target.cmd.join(" "),
+                schedule: task.schedule,
+                description: task.description ?? "",
+                enabled: task.enabled,
+                yaml,
+            });
         }
-        const command = typeof doc.command === "string" ? doc.command : "";
-        const schedule = typeof doc.schedule === "string" ? doc.schedule : "";
-        const description = typeof doc.description === "string" ? doc.description : "";
-        const enabled = doc.enabled !== false;
-        tasks.push({
-            id,
-            label: `core/${id}`,
-            command,
-            schedule,
-            description,
-            enabled,
-            yaml,
-        });
     }
     return tasks;
 }