akm-cli 0.7.4 → 0.8.0-rc1

package/dist/sources/website-ingest.js

@@ -167,6 +167,10 @@ async function crawlWebsite(startUrl, options) {
     return pages;
 }
 async function fetchWebsitePage(pageUrl) {
+    const parsedUrl = new URL(pageUrl);
+    if (parsedUrl.hostname.endsWith(".invalid")) {
+        throw new Error(`Refusing to fetch reserved invalid hostname: ${parsedUrl.hostname}`);
+    }
     const response = await fetchWithRetry(pageUrl, {
         headers: {
             Accept: "text/html, text/markdown, text/plain;q=0.9, application/xhtml+xml;q=0.8",

package/dist/tasks/backends/cron.js

@@ -0,0 +1,200 @@
+// crontab backend for `akm tasks` (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
+//     # akm:task <id> END
+//
+// The backend reads/writes the user's crontab via `crontab -l` and
+// `crontab -`. Disabling a task comments the entry with `# akm:disabled `
+// rather than removing it, so re-enabling preserves the original schedule.
+//
+// Platform notes:
+//   • Operates on the *per-user* crontab — system-wide /etc/cron.d entries
+//     are out of scope.
+//   • Cron runs jobs with a stripped environment (`SHELL`, `PATH`, `HOME`,
+//     `LOGNAME`/`USER` only). The cron line uses an absolute akm path
+//     resolved at install time so it doesn't rely on the inherited PATH.
+//   • BSD `crontab -l` returns exit 1 with "no crontab for <user>" on a
+//     fresh user; we treat that as an empty crontab rather than an error.
+//
+// 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";
+import { getTaskLogDir } from "../../core/paths";
+import { resolveAkmInvocation } from "../resolveAkmBin";
+import { parseSchedule, translateToCron } from "../schedule";
+const BEGIN = (id) => `# akm:task ${id} BEGIN`;
+const END = (id) => `# akm:task ${id} END`;
+const DISABLED_PREFIX = "# akm:disabled ";
+const BLOCK_RE = /^# akm:task ([\w.@:_-]+) BEGIN$/;
+export function CRON_BACKEND(options = {}) {
+    const exec = options.exec ?? defaultCronExec();
+    const logDir = options.logDir ?? getTaskLogDir();
+    const akmArgv = options.akmArgv ?? resolveAkmInvocation().argv;
+    return {
+        name: "cron",
+        install(task) {
+            // 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 existing = readCrontab(exec);
+            const block = renderBlock(task.id, cronLine, task.enabled);
+            const next = upsertBlock(existing, task.id, block);
+            writeCrontab(exec, next);
+        },
+        uninstall(id) {
+            const existing = readCrontab(exec);
+            const next = removeBlock(existing, id);
+            writeCrontab(exec, next);
+        },
+        setEnabled(id, enabled) {
+            const existing = readCrontab(exec);
+            const next = toggleBlock(existing, id, enabled);
+            writeCrontab(exec, next);
+        },
+        list() {
+            const existing = readCrontab(exec);
+            const ids = [];
+            for (const line of existing.split(/\r?\n/)) {
+                const m = line.match(BLOCK_RE);
+                if (m)
+                    ids.push(m[1]);
+            }
+            return ids.map((id) => ({ id }));
+        },
+    };
+}
+// ── helpers (exported for tests) ────────────────────────────────────────────
+export function buildCronLine(task, akmArgv, logDir) {
+    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(" ");
+    return `${cronExpr} ${cmd} >> ${quoteForCron(logPath)} 2>&1`;
+}
+export function renderBlock(id, cronLine, enabled) {
+    const body = enabled ? cronLine : `${DISABLED_PREFIX}${cronLine}`;
+    return [BEGIN(id), body, END(id)].join("\n");
+}
+export function upsertBlock(existing, id, block) {
+    const trimmed = existing.replace(/\s+$/g, "");
+    const removed = removeBlock(trimmed, id);
+    const sep = removed.length === 0 ? "" : "\n";
+    return `${removed}${sep}${block}\n`;
+}
+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);
+    }
+    // Collapse trailing blank lines.
+    while (out.length > 0 && out[out.length - 1] === "")
+        out.pop();
+    return out.join("\n");
+}
+export function toggleBlock(existing, id, enabled) {
+    const lines = existing.split(/\r?\n/);
+    const out = [];
+    let inBlock = false;
+    for (const line of lines) {
+        if (!inBlock && line === BEGIN(id)) {
+            inBlock = true;
+            out.push(line);
+            continue;
+        }
+        if (inBlock && line === END(id)) {
+            inBlock = false;
+            out.push(line);
+            continue;
+        }
+        if (inBlock) {
+            const isComment = line.startsWith(DISABLED_PREFIX);
+            if (enabled && isComment) {
+                out.push(line.slice(DISABLED_PREFIX.length));
+            }
+            else if (!enabled && !isComment) {
+                out.push(`${DISABLED_PREFIX}${line}`);
+            }
+            else {
+                out.push(line);
+            }
+            continue;
+        }
+        out.push(line);
+    }
+    return out.join("\n");
+}
+function quoteForCron(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'`.
+    if (/^[A-Za-z0-9_\-./@:%=+,]+$/.test(part))
+        return part;
+    return `'${part.replace(/'/g, `'\\''`)}'`;
+}
+function readCrontab(exec) {
+    const result = exec.read();
+    if (result.status === 0)
+        return result.stdout ?? "";
+    // BSD crontab returns 1 with "no crontab for <user>" on stderr — treat as empty.
+    if (/no crontab for/i.test(result.stderr ?? ""))
+        return "";
+    if (/no crontab/i.test(result.stdout ?? ""))
+        return "";
+    throw new ConfigError(`crontab -l failed (exit ${result.status}): ${result.stderr || result.stdout || "no output"}.`, "INVALID_CONFIG_FILE", "Ensure the `crontab` binary is on PATH and your shell can read the user crontab.");
+}
+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.");
+    }
+}
+function ensureDir(dir) {
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    catch {
+        // Best-effort: the install will surface a clearer error if the cron
+        // line later fails at runtime due to a missing redirection target.
+    }
+}
+function defaultCronExec() {
+    return {
+        read() {
+            const r = spawnSync("crontab", ["-l"], { encoding: "utf8" });
+            return {
+                status: r.status ?? 1,
+                stdout: r.stdout ?? "",
+                stderr: r.stderr ?? "",
+            };
+        },
+        write(content) {
+            const r = spawnSync("crontab", ["-"], { encoding: "utf8", input: content });
+            return {
+                status: r.status ?? 1,
+                stdout: r.stdout ?? "",
+                stderr: r.stderr ?? "",
+            };
+        },
+    };
+}

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

@@ -0,0 +1,25 @@
+import { spawnSync } from "node:child_process";
+/**
+ * Run a command synchronously, normalizing null results to safe defaults.
+ * args[0] is the binary; args[1..] are its arguments.
+ */
+export function spawnCommand(args) {
+    const [bin, ...rest] = args;
+    const r = spawnSync(bin, rest, { encoding: "utf8" });
+    return {
+        status: r.status ?? 1,
+        stdout: r.stdout ?? "",
+        stderr: r.stderr ?? "",
+    };
+}
+/**
+ * Escape a string for safe embedding in an XML attribute or text node.
+ */
+export function escapeXml(s) {
+    return s
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}

package/dist/tasks/backends/index.js

@@ -0,0 +1,32 @@
+/**
+ * Backend selection for the OS-native scheduler.
+ *
+ *   • Linux   → crontab
+ *   • macOS   → launchd (per-user LaunchAgent)
+ *   • Windows → schtasks.exe / Task Scheduler
+ *
+ * Each backend implements {@link TaskBackend}; selection is a one-line
+ * platform check. Tests inject a fake `platform` to exercise non-host
+ * code paths.
+ */
+import { CRON_BACKEND } from "./cron";
+import { LAUNCHD_BACKEND } from "./launchd";
+import { SCHTASKS_BACKEND } from "./schtasks";
+export function selectBackend(options = {}) {
+    const platform = options.platform ?? process.platform;
+    switch (platform) {
+        case "win32":
+            return SCHTASKS_BACKEND(options.schtasks);
+        case "darwin":
+            return LAUNCHD_BACKEND(options.launchd);
+        default:
+            return CRON_BACKEND(options.cron);
+    }
+}
+export function backendNameForPlatform(platform = process.platform) {
+    if (platform === "win32")
+        return "schtasks";
+    if (platform === "darwin")
+        return "launchd";
+    return "cron";
+}

package/dist/tasks/backends/launchd-template.xml

@@ -0,0 +1,19 @@
+<?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>
+  <string>{{LABEL}}</string>
+  <key>ProgramArguments</key>
+  <array>
+{{PROGRAM_ARGS}}
+  </array>
+  <key>StandardOutPath</key>
+  <string>{{LOG_PATH}}</string>
+  <key>StandardErrorPath</key>
+  <string>{{LOG_PATH}}</string>
+  <key>RunAtLoad</key>
+  <false/>
+{{ENV_VARS}}{{TRIGGER_XML}}
+</dict>
+</plist>

package/dist/tasks/backends/launchd.js

@@ -0,0 +1,184 @@
+/**
+ * launchd backend for `akm tasks` (macOS default).
+ *
+ * Each task is written as a per-user LaunchAgent plist at
+ * `~/Library/LaunchAgents/com.akm.task.<id>.plist` and registered via
+ * `launchctl bootstrap gui/<uid> <plist>`. Disabling uses
+ * `launchctl disable gui/<uid>/<label>` and re-enabling uses `enable`.
+ *
+ * Platform notes:
+ *   • The `bootstrap` / `bootout` / `enable` / `disable` subcommands require
+ *     macOS 10.10 (Yosemite) or newer. On older systems the equivalents
+ *     are `launchctl load -w` / `unload -w`. We only target modern macOS.
+ *   • `gui/<uid>` is the per-user GUI launchd domain — agents in this
+ *     domain only run while the user is logged in (no background runs at
+ *     the loginwindow). Tasks that need to run when the user is logged
+ *     out should be installed as system Daemons, which is out of scope.
+ *
+ * Tests inject a fake exec + filesystem so the backend can be unit-tested
+ * without touching the host launchctl.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { ConfigError } from "../../core/errors";
+import { getTaskLogDir } from "../../core/paths";
+import { resolveAkmInvocation } from "../resolveAkmBin";
+import { parseSchedule, translateToLaunchd } from "../schedule";
+import { escapeXml, spawnCommand } from "./exec-utils";
+import launchdTemplate from "./launchd-template.xml" with { type: "text" };
+export const LAUNCHD_LABEL_PREFIX = "com.akm.task.";
+export function LAUNCHD_BACKEND(options = {}) {
+    const exec = options.exec ?? defaultLaunchdExec();
+    const fsLike = options.fs ?? defaultLaunchdFs();
+    const agentsDir = options.agentsDir ?? defaultAgentsDir();
+    const logDir = options.logDir ?? getTaskLogDir();
+    const akmArgv = options.akmArgv ?? resolveAkmInvocation().argv;
+    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)}`;
+    return {
+        name: "launchd",
+        install(task) {
+            // 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, 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.");
+            }
+            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");
+                }
+            }
+        },
+        uninstall(id) {
+            // Bootout first (may fail if agent never loaded — that's fine).
+            exec.run(["launchctl", "bootout", target(id)]);
+            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");
+            }
+        },
+        list() {
+            if (!fsLike.exists(agentsDir))
+                return [];
+            const ids = [];
+            for (const file of fsLike.list(agentsDir)) {
+                if (file.startsWith(LAUNCHD_LABEL_PREFIX) && file.endsWith(".plist")) {
+                    ids.push(file.slice(LAUNCHD_LABEL_PREFIX.length, -".plist".length));
+                }
+            }
+            return ids.map((id) => ({ id }));
+        },
+    };
+}
+// ── XML builder (exported for tests) ────────────────────────────────────────
+export function buildPlistXml(task, akmArgv, logDir, pathEnv) {
+    const spec = parseSchedule(task.schedule, "launchd");
+    const trigger = translateToLaunchd(spec);
+    const argv = [...akmArgv, "tasks", "run", task.id];
+    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
+        .replace("{{LABEL}}", LAUNCHD_LABEL_PREFIX + escapeXml(task.id))
+        .replace("{{PROGRAM_ARGS}}", programArgs)
+        .replaceAll("{{LOG_PATH}}", escapeXml(logPath))
+        .replace("{{ENV_VARS}}", envVarsXml)
+        .replace("{{TRIGGER_XML}}", triggerXml);
+}
+function renderLaunchdTrigger(trigger) {
+    if (trigger.intervalSeconds !== undefined) {
+        return `  <key>StartInterval</key>
+  <integer>${trigger.intervalSeconds}</integer>`;
+    }
+    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>");
+    return lines.join("\n");
+}
+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.");
+    }
+    return path.join(home, "Library", "LaunchAgents");
+}
+function defaultLaunchdExec() {
+    return {
+        run(args) {
+            return spawnCommand(args);
+        },
+        uid() {
+            const fn = process.getuid;
+            return typeof fn === "function" ? fn.call(process) : 0;
+        },
+    };
+}
+function defaultLaunchdFs() {
+    return {
+        writeFile(file, content) {
+            fs.writeFileSync(file, content, { encoding: "utf8" });
+        },
+        removeFile(file) {
+            fs.rmSync(file, { force: true });
+        },
+        ensureDir(dir) {
+            fs.mkdirSync(dir, { recursive: true });
+        },
+        list(dir) {
+            try {
+                return fs.readdirSync(dir);
+            }
+            catch {
+                return [];
+            }
+        },
+        exists(file) {
+            return fs.existsSync(file);
+        },
+    };
+}

package/dist/tasks/backends/schtasks-template.xml

@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>akm scheduled task: {{TASK_ID}}</Description>
+    <URI>{{FOLDER}}{{TASK_ID}}</URI>
+  </RegistrationInfo>
+  <Triggers>
+{{TRIGGER_XML}}
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <Enabled>{{ENABLED}}</Enabled>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>{{COMMAND}}</Command>
+      <Arguments>{{ARGS}}</Arguments>
+    </Exec>
+  </Actions>
+  <!-- Log target (informational only; schtasks doesn't redirect): {{LOG_PATH}} -->
+</Task>