akm-cli 0.7.5 → 0.8.0-rc2

package/dist/tasks/backends/schtasks.js

@@ -0,0 +1,212 @@
+/**
+ * schtasks.exe backend for `akm tasks` (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
+ * sent through `schtasks /Create /TN \akm\<id> /XML <path>` so we can
+ * express triggers/principals/actions without quoting hell.
+ *
+ * Platform notes:
+ *   • `LogonType=InteractiveToken` means the task runs in the context of
+ *     the registering user only when they are logged in — there is no
+ *     stored password and the task will not fire at the lock screen.
+ *   • `<Principal>` deliberately omits `<UserId>`; per the Task Scheduler
+ *     2.0 schema (`principalType.UserId` minOccurs=0) this is valid and
+ *     defaults to the registering user.
+ *   • `<DisallowStartIfOnBatteries>false</…>` and `<StopIfGoingOnBatteries>
+ *     false</…>` allow the task to run on battery — utility tasks would
+ *     otherwise be silently skipped on laptops.
+ *   • `MultipleInstancesPolicy=IgnoreNew` makes overlapping triggers safe:
+ *     while a task is still running, a new fire is dropped rather than
+ *     queued or run in parallel.
+ *   • `/Query /FO CSV /NH` (without `/V`) outputs three columns:
+ *     `TaskName,Next Run Time,Status` — so the regex anchors on the task
+ *     name as the leading quoted field. Adding `/V` would shift HostName
+ *     into column 0; we deliberately don't.
+ *
+ * Tests inject a fake exec + filesystem.
+ */
+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, translateToSchtasks } from "../schedule";
+import { escapeXml, spawnCommand } from "./exec-utils";
+import schtasksTemplate from "./schtasks-template.xml" with { type: "text" };
+export const DEFAULT_FOLDER_PREFIX = "\\akm\\";
+export function SCHTASKS_BACKEND(options = {}) {
+    const exec = options.exec ?? defaultSchtasksExec();
+    const fsLike = options.fs ?? defaultSchtasksFs();
+    const akmArgv = options.akmArgv ?? resolveAkmInvocation().argv;
+    const logDir = options.logDir ?? getTaskLogDir();
+    const folder = options.folderPrefix ?? DEFAULT_FOLDER_PREFIX;
+    const taskName = (id) => `${folder}${id}`;
+    return {
+        name: "schtasks",
+        install(task) {
+            fsLike.ensureDir(logDir);
+            const xml = buildSchtasksXml(task, akmArgv, logDir, { folderPrefix: folder });
+            const tmpFile = path.join(fsLike.tmpdir(), `akm-task-${task.id}-${Date.now()}.xml`);
+            fsLike.writeFile(tmpFile, xml);
+            try {
+                // /F forces overwrite if a task with the same name exists.
+                const r = exec.run(["schtasks", "/Create", "/TN", taskName(task.id), "/XML", tmpFile, "/F"]);
+                if (r.status !== 0) {
+                    throw new ConfigError(`schtasks /Create failed (exit ${r.status}): ${r.stderr || r.stdout || "no output"}.`, "INVALID_CONFIG_FILE");
+                }
+                if (!task.enabled) {
+                    const dis = exec.run(["schtasks", "/Change", "/TN", taskName(task.id), "/DISABLE"]);
+                    if (dis.status !== 0) {
+                        throw new ConfigError(`schtasks /Change /DISABLE failed: ${dis.stderr || dis.stdout || "no output"}.`, "INVALID_CONFIG_FILE");
+                    }
+                }
+            }
+            finally {
+                fsLike.removeFile(tmpFile);
+            }
+        },
+        uninstall(id) {
+            const r = exec.run(["schtasks", "/Delete", "/TN", taskName(id), "/F"]);
+            if (r.status !== 0 && !/cannot find/i.test(r.stderr ?? "")) {
+                throw new ConfigError(`schtasks /Delete failed: ${r.stderr || r.stdout || "no output"}.`, "INVALID_CONFIG_FILE");
+            }
+        },
+        setEnabled(id, enabled) {
+            const flag = enabled ? "/ENABLE" : "/DISABLE";
+            const r = exec.run(["schtasks", "/Change", "/TN", taskName(id), flag]);
+            if (r.status !== 0) {
+                throw new ConfigError(`schtasks /Change ${flag} failed: ${r.stderr || r.stdout || "no output"}.`, "INVALID_CONFIG_FILE");
+            }
+        },
+        list() {
+            const r = exec.run(["schtasks", "/Query", "/FO", "CSV", "/NH"]);
+            if (r.status !== 0)
+                return [];
+            const ids = [];
+            for (const line of (r.stdout ?? "").split(/\r?\n/)) {
+                const m = line.match(/^"([^"]+)",/);
+                if (!m)
+                    continue;
+                const name = m[1];
+                if (name.startsWith(folder)) {
+                    ids.push(name.slice(folder.length));
+                }
+            }
+            return ids.map((id) => ({ id }));
+        },
+    };
+}
+export function buildSchtasksXml(task, akmArgv, logDir, options = {}) {
+    const folder = options.folderPrefix ?? DEFAULT_FOLDER_PREFIX;
+    const now = options.now ? options.now() : new Date();
+    const startBoundary = formatStartBoundary(now);
+    const spec = parseSchedule(task.schedule, "schtasks");
+    const trigger = translateToSchtasks(spec);
+    const command = akmArgv[0];
+    const args = [...akmArgv.slice(1), "tasks", "run", task.id].map((a) => quoteArg(a)).join(" ");
+    const triggerXml = renderSchtasksTrigger(trigger, startBoundary);
+    const logPath = path.join(logDir, `${task.id}.log`);
+    return schtasksTemplate
+        .replaceAll("{{TASK_ID}}", escapeXml(task.id))
+        .replaceAll("{{FOLDER}}", escapeXml(folder))
+        .replace("{{TRIGGER_XML}}", triggerXml)
+        .replace("{{ENABLED}}", task.enabled ? "true" : "false")
+        .replace("{{COMMAND}}", escapeXml(command))
+        .replace("{{ARGS}}", escapeXml(args))
+        .replace("{{LOG_PATH}}", escapeXml(logPath));
+}
+function renderSchtasksTrigger(trigger, startBoundary) {
+    switch (trigger.kind) {
+        case "minute":
+            return `    <TimeTrigger>
+      <Repetition>
+        <Interval>PT${trigger.everyMinutes}M</Interval>
+      </Repetition>
+      <StartBoundary>${startBoundary}</StartBoundary>
+      <Enabled>true</Enabled>
+    </TimeTrigger>`;
+        case "hour":
+            return `    <TimeTrigger>
+      <Repetition>
+        <Interval>PT${trigger.everyHours}H</Interval>
+      </Repetition>
+      <StartBoundary>${startBoundary}</StartBoundary>
+      <Enabled>true</Enabled>
+    </TimeTrigger>`;
+        case "daily":
+            return `    <CalendarTrigger>
+      <StartBoundary>${pad(startBoundary, trigger.atHour, trigger.atMinute)}</StartBoundary>
+      <Enabled>true</Enabled>
+      <ScheduleByDay><DaysInterval>1</DaysInterval></ScheduleByDay>
+    </CalendarTrigger>`;
+        case "weekly": {
+            const dayMap = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+            const days = trigger.daysOfWeek.map((d) => `        <${dayMap[d]} />`).join("\n");
+            return `    <CalendarTrigger>
+      <StartBoundary>${pad(startBoundary, trigger.atHour, trigger.atMinute)}</StartBoundary>
+      <Enabled>true</Enabled>
+      <ScheduleByWeek>
+        <DaysOfWeek>
+${days}
+        </DaysOfWeek>
+        <WeeksInterval>1</WeeksInterval>
+      </ScheduleByWeek>
+    </CalendarTrigger>`;
+        }
+    }
+}
+function pad(base, hour, minute) {
+    // Rewrite the time component of an ISO-8601 boundary while preserving
+    // the date so daily/weekly triggers fire at the configured wall-clock
+    // time rather than the install instant.
+    const hh = String(hour).padStart(2, "0");
+    const mm = String(minute).padStart(2, "0");
+    return base.replace(/T\d\d:\d\d:\d\d$/, `T${hh}:${mm}:00`);
+}
+function formatStartBoundary(d) {
+    // Local-time ISO-8601 (no zone suffix) — Task Scheduler interprets a
+    // bare boundary in the registering user's timezone, which matches what
+    // a user typing "0 9 * * *" intuitively means ("9am local").
+    const yyyy = d.getFullYear();
+    const mm = String(d.getMonth() + 1).padStart(2, "0");
+    const dd = String(d.getDate()).padStart(2, "0");
+    const hh = String(d.getHours()).padStart(2, "0");
+    const mi = String(d.getMinutes()).padStart(2, "0");
+    const ss = String(d.getSeconds()).padStart(2, "0");
+    return `${yyyy}-${mm}-${dd}T${hh}:${mi}:${ss}`;
+}
+function quoteArg(s) {
+    if (/^[A-Za-z0-9_\-./@:%=+,\\]+$/.test(s))
+        return s;
+    return `"${s.replace(/"/g, '\\"')}"`;
+}
+function defaultSchtasksExec() {
+    return {
+        run(args) {
+            return spawnCommand(args);
+        },
+    };
+}
+function defaultSchtasksFs() {
+    return {
+        writeFile(file, content) {
+            fs.writeFileSync(file, content, { encoding: "utf8" });
+        },
+        removeFile(file) {
+            try {
+                fs.rmSync(file, { force: true });
+            }
+            catch {
+                /* ignore */
+            }
+        },
+        ensureDir(dir) {
+            fs.mkdirSync(dir, { recursive: true });
+        },
+        tmpdir() {
+            return os.tmpdir();
+        },
+    };
+}

package/dist/tasks/parser.js

@@ -0,0 +1,198 @@
+/**
+ * Parse a task markdown file (frontmatter + body) into a {@link TaskDocument}.
+ *
+ * The on-disk shape is:
+ *
+ * ```markdown
+ * ---
+ * schedule: "0 9 * * *"
+ * # one of:
+ * workflow: workflow:daily-backup
+ * params:
+ *   region: us-east-1
+ * # ...or:
+ * prompt: inline                    # body is the prompt
+ * profile: opencode                 # optional
+ * # ...or:
+ * prompt: agent:my-agent            # asset ref
+ * # ...or:
+ * prompt: ./prompts/my-prompt.md    # relative file path
+ * enabled: true                     # default true
+ * description: …
+ * tags: [scheduled, backup]
+ * ---
+ *
+ * # Task: Daily backup           (optional notes; for prompt:inline this is the prompt)
+ * ```
+ *
+ * Validation lives in {@link validateTaskDocument}. The parser only enforces
+ * shape; cron syntax, target reachability, and profile availability are
+ * checked separately so callers can choose how strictly to surface errors.
+ */
+import path from "node:path";
+import { UsageError } from "../core/errors";
+import { parseFrontmatter } from "../core/frontmatter";
+import { TASK_SCHEMA_VERSION } from "./schema";
+export function parseTaskDocument(input) {
+    const { markdown, filePath, id } = input;
+    const fm = parseFrontmatter(markdown);
+    const data = fm.data;
+    const schedule = readString(data.schedule, "schedule", filePath);
+    if (!schedule) {
+        throw new UsageError(`Task "${id}" is missing a schedule (frontmatter key "schedule"). File: ${filePath}`, "MISSING_REQUIRED_ARGUMENT");
+    }
+    const enabled = data.enabled === undefined ? true : data.enabled === true;
+    const description = readString(data.description, "description", filePath);
+    const tags = readStringArray(data.tags);
+    const hasWorkflow = "workflow" in data && data.workflow !== "";
+    const hasPrompt = "prompt" in data && data.prompt !== "";
+    const hasCommand = "command" in data && data.command !== "" && data.command !== null && data.command !== undefined;
+    const targetCount = [hasWorkflow, hasPrompt, hasCommand].filter(Boolean).length;
+    if (targetCount > 1) {
+        throw new UsageError(`Task "${id}" sets more than one of \`workflow\`, \`prompt\`, \`command\`; pick exactly one. File: ${filePath}`, "INVALID_FLAG_VALUE");
+    }
+    if (targetCount === 0) {
+        throw new UsageError(`Task "${id}" must set one of \`workflow\`, \`prompt\`, or \`command\` in frontmatter. File: ${filePath}`, "MISSING_REQUIRED_ARGUMENT");
+    }
+    let target;
+    if (hasWorkflow) {
+        const ref = readString(data.workflow, "workflow", filePath);
+        if (!ref) {
+            throw new UsageError(`Task "${id}" has empty \`workflow\`. File: ${filePath}`, "INVALID_FLAG_VALUE");
+        }
+        target = {
+            kind: "workflow",
+            ref,
+            params: readParams(data.params, filePath),
+        };
+    }
+    else if (hasCommand) {
+        const cmd = readCommand(data.command, filePath, id);
+        target = { kind: "command", cmd };
+    }
+    else {
+        const promptRaw = readString(data.prompt, "prompt", filePath);
+        if (!promptRaw) {
+            throw new UsageError(`Task "${id}" has empty \`prompt\`. File: ${filePath}`, "INVALID_FLAG_VALUE");
+        }
+        const profile = readString(data.profile, "profile", filePath);
+        target = {
+            kind: "prompt",
+            source: resolvePromptSource(promptRaw, fm.content, filePath, id),
+            profile: profile && profile.length > 0 ? profile : undefined,
+        };
+    }
+    // null / 0 / negative → disabled (no timeout). Positive number → override.
+    // Omitted → undefined (inherits config.agent.timeoutMs).
+    let timeoutMs;
+    if ("timeoutMs" in data) {
+        const raw = data.timeoutMs;
+        if (raw === null || raw === "null" || raw === 0 || (typeof raw === "number" && raw < 0)) {
+            timeoutMs = null;
+        }
+        else if (typeof raw === "number" && raw > 0) {
+            timeoutMs = raw;
+        }
+        // non-numeric / unrecognised → leave as undefined (inherit)
+    }
+    return {
+        schemaVersion: TASK_SCHEMA_VERSION,
+        id,
+        schedule,
+        enabled,
+        target,
+        description: description && description.length > 0 ? description : undefined,
+        tags: tags && tags.length > 0 ? tags : undefined,
+        source: { path: filePath },
+        timeoutMs,
+    };
+}
+/**
+ * Split `prompt:` frontmatter into one of {@link TaskPromptSource} variants.
+ *
+ *   • "inline"                          → body is the prompt
+ *   • "<type>:<name>" (asset ref)       → asset
+ *   • "./foo.md", "../foo.md", "/abs"   → file
+ *   • anything else                     → treated as inline prompt text
+ *     (the value itself is the prompt)
+ */
+function resolvePromptSource(raw, body, filePath, id) {
+    const trimmed = raw.trim();
+    if (trimmed === "inline") {
+        const text = body.trim();
+        if (!text) {
+            throw new UsageError(`Task "${id}" sets \`prompt: inline\` but the markdown body is empty. File: ${filePath}`, "MISSING_REQUIRED_ARGUMENT");
+        }
+        return { kind: "inline", text };
+    }
+    if (trimmed.startsWith("./") || trimmed.startsWith("../") || path.isAbsolute(trimmed)) {
+        return { kind: "file", path: trimmed };
+    }
+    if (/^[A-Za-z]:[\\/]/.test(trimmed)) {
+        return { kind: "file", path: trimmed };
+    }
+    if (/^[a-z][a-z0-9_-]*:[^\s]/i.test(trimmed)) {
+        return { kind: "asset", ref: trimmed };
+    }
+    // Fallback: treat the literal value as the prompt text.
+    return { kind: "inline", text: trimmed };
+}
+function readString(value, key, filePath) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === "string")
+        return value.trim();
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    throw new UsageError(`Frontmatter key "${key}" must be a string. File: ${filePath}`, "INVALID_FLAG_VALUE");
+}
+function readStringArray(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === "string") {
+        return value
+            .split(/[\s,]+/)
+            .map((s) => s.trim())
+            .filter(Boolean);
+    }
+    if (Array.isArray(value)) {
+        return value.filter((v) => typeof v === "string" && v.trim().length > 0);
+    }
+    return undefined;
+}
+function readCommand(value, filePath, id) {
+    if (Array.isArray(value)) {
+        const parts = value.filter((v) => typeof v === "string" && v.trim().length > 0);
+        if (parts.length === 0) {
+            throw new UsageError(`Task "${id}" has empty \`command\` array. File: ${filePath}`, "INVALID_FLAG_VALUE");
+        }
+        return parts;
+    }
+    if (typeof value === "string") {
+        const parts = value.trim().split(/\s+/).filter(Boolean);
+        if (parts.length === 0) {
+            throw new UsageError(`Task "${id}" has empty \`command\`. File: ${filePath}`, "INVALID_FLAG_VALUE");
+        }
+        return parts;
+    }
+    throw new UsageError(`Frontmatter key "command" must be a string or array of strings. File: ${filePath}`, "INVALID_FLAG_VALUE");
+}
+function readParams(value, filePath) {
+    if (value === undefined || value === null)
+        return {};
+    if (typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    if (typeof value === "string" && value.trim()) {
+        try {
+            const parsed = JSON.parse(value);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // fall through
+        }
+    }
+    throw new UsageError(`Frontmatter key "params" must be a mapping or a JSON object. File: ${filePath}`, "INVALID_FLAG_VALUE");
+}

package/dist/tasks/resolveAkmBin.js

@@ -0,0 +1,84 @@
+/**
+ * Resolve the absolute invocation that the OS scheduler should run.
+ *
+ * cron / launchd / schtasks all execute jobs with a stripped environment and
+ * a minimal PATH, so the registered command must be an absolute path.
+ *
+ * Resolution order:
+ *
+ *   1. `$AKM_BIN` (explicit override; takes precedence everywhere).
+ *   2. `process.execPath` + the resolved CLI script — works when running
+ *      from a development checkout (`bun /repo/src/cli.ts`) and from a
+ *      compiled install (`bun /opt/akm/dist/cli.js`).
+ *   3. `which akm` / `where akm` — last resort when the binary is on PATH
+ *      but neither override applies.
+ *
+ * Returns the argv array the scheduler should execute (e.g.
+ * `["/usr/local/bin/bun", "/repo/dist/cli.js"]`). The caller appends
+ * subcommand args (`"tasks", "run", "<id>"`).
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ConfigError } from "../core/errors";
+export function resolveAkmInvocation(options = {}) {
+    const env = options.env ?? process.env;
+    const override = env.AKM_BIN?.trim();
+    if (override) {
+        return { argv: [override], via: "AKM_BIN" };
+    }
+    const cliPath = resolveCliEntry(options.cliEntryUrl ?? import.meta.url);
+    if (cliPath && process.execPath) {
+        return { argv: [process.execPath, cliPath], via: "execPath" };
+    }
+    const whichBin = findOnPath("akm", env);
+    if (whichBin) {
+        return { argv: [whichBin], via: "which" };
+    }
+    throw new ConfigError("Cannot resolve absolute path to the akm binary for scheduler registration.", "INVALID_CONFIG_FILE", "Set AKM_BIN to the absolute path of the akm binary, or ensure `akm` is on PATH.");
+}
+/**
+ * From the URL of a module inside `src/tasks/` figure out the CLI entry.
+ *
+ *   • dev      `…/src/tasks/resolveAkmBin.ts`   → `…/src/cli.ts`
+ *   • build    `…/dist/tasks/resolveAkmBin.js`  → `…/dist/cli.js`
+ */
+function resolveCliEntry(moduleUrl) {
+    let modulePath;
+    try {
+        modulePath = fileURLToPath(moduleUrl);
+    }
+    catch {
+        return undefined;
+    }
+    const dir = path.dirname(modulePath); // .../tasks
+    const parent = path.dirname(dir); // .../src or .../dist
+    const ext = path.extname(modulePath); // .ts | .js
+    const candidate = path.join(parent, `cli${ext}`);
+    if (fs.existsSync(candidate))
+        return candidate;
+    // Fallback: try the other extension.
+    const alt = path.join(parent, ext === ".ts" ? "cli.js" : "cli.ts");
+    if (fs.existsSync(alt))
+        return alt;
+    return undefined;
+}
+function findOnPath(bin, env) {
+    const tool = process.platform === "win32" ? "where" : "which";
+    try {
+        const out = spawnSync(tool, [bin], { encoding: "utf8", env });
+        if (out.status === 0 && typeof out.stdout === "string") {
+            const first = out.stdout
+                .split(/\r?\n/)
+                .map((s) => s.trim())
+                .find(Boolean);
+            if (first && fs.existsSync(first))
+                return first;
+        }
+    }
+    catch {
+        // ignore — caller will throw a ConfigError
+    }
+    return undefined;
+}