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

package/dist/tasks/backends/types.js

@@ -0,0 +1,4 @@
+// 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/.
+export {};

package/dist/tasks/command-executable.js

@@ -0,0 +1,93 @@
+// 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/.
+const ENV_OPTIONS_WITH_OPERAND = new Set(["--argv0", "--chdir", "--unset"]);
+const ENV_OPTIONS_WITH_OPTIONAL_VALUE = new Set(["--block-signal", "--default-signal", "--ignore-signal"]);
+const ENV_OPTIONS_WITHOUT_OPERAND = new Set(["--debug", "--ignore-environment", "--list-signal-handling"]);
+/** Locate a command whose executable position clearly names AKM, including an explicit path. */
+export function findAkmExecutableIndex(command) {
+    if (command.length === 0)
+        return undefined;
+    const executableIndex = isEnvExecutable(command[0]) ? findEnvCommandIndex(command) : 0;
+    if (executableIndex === undefined || !isAkmExecutable(command[executableIndex]))
+        return undefined;
+    return executableIndex;
+}
+/** Locate only PATH-selected AKM, which is safe to redirect to the current installation. */
+export function findBareAkmExecutableIndex(command) {
+    const executableIndex = findAkmExecutableIndex(command);
+    if (executableIndex === undefined || !isBareAkm(command[executableIndex]))
+        return undefined;
+    return executableIndex;
+}
+function findEnvCommandIndex(command) {
+    let index = 1;
+    while (index < command.length) {
+        const part = command[index];
+        if (part === "--") {
+            index += 1;
+            break;
+        }
+        if (isEnvironmentAssignment(part))
+            break;
+        if (!part.startsWith("-"))
+            break;
+        const operandCount = envOptionOperandCount(part);
+        if (operandCount === undefined || index + operandCount >= command.length)
+            return undefined;
+        index += operandCount + 1;
+    }
+    while (index < command.length && isEnvironmentAssignment(command[index]))
+        index += 1;
+    return index < command.length ? index : undefined;
+}
+function envOptionOperandCount(option) {
+    if (option === "-")
+        return 0;
+    if (ENV_OPTIONS_WITHOUT_OPERAND.has(option) || ENV_OPTIONS_WITH_OPTIONAL_VALUE.has(option))
+        return 0;
+    if ([...ENV_OPTIONS_WITH_OPTIONAL_VALUE].some((prefix) => option.startsWith(`${prefix}=`)))
+        return 0;
+    if (ENV_OPTIONS_WITH_OPERAND.has(option))
+        return 1;
+    if (["--argv0=", "--chdir=", "--unset="].some((prefix) => option.startsWith(prefix)))
+        return 0;
+    if (!option.startsWith("-") || option.startsWith("--"))
+        return undefined;
+    const shortOptions = option.slice(1);
+    for (let index = 0; index < shortOptions.length; index += 1) {
+        const flag = shortOptions[index];
+        if (flag === "i" || flag === "v")
+            continue;
+        if (flag === "S")
+            return undefined;
+        if (flag === "u" || flag === "C" || flag === "P" || flag === "a") {
+            return index === shortOptions.length - 1 ? 1 : 0;
+        }
+        return undefined;
+    }
+    return shortOptions.length > 0 ? 0 : undefined;
+}
+function isEnvironmentAssignment(value) {
+    return /^[A-Za-z_][A-Za-z0-9_]*=/.test(value);
+}
+function isEnvExecutable(value) {
+    if (!value)
+        return false;
+    if (value === "env")
+        return true;
+    if (!isAbsolutePath(value))
+        return false;
+    return /^env(?:\.exe)?$/i.test(value.split(/[\\/]/).at(-1) ?? "");
+}
+function isAbsolutePath(value) {
+    return value.startsWith("/") || value.startsWith("\\\\") || /^[A-Za-z]:[\\/]/.test(value);
+}
+function isBareAkm(value) {
+    return value !== undefined && /^akm(?:\.exe)?$/i.test(value);
+}
+function isAkmExecutable(value) {
+    if (!value)
+        return false;
+    return /^akm(?:\.exe)?$/i.test(value.split(/[\\/]/).at(-1) ?? "");
+}

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,55 +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 : "";
-        tasks.push({
-            id,
-            label: `core/${id}`,
-            command,
-            schedule,
-            description,
-            yaml,
-        });
     }
     return tasks;
 }

package/dist/tasks/parser.js

@@ -9,11 +9,11 @@
  * ```yaml
  * schedule: "0 9 * * *"
  * # one of:
- * workflow: workflow:daily-backup
+ * workflow: workflows/daily-backup
  * params:
  *   region: us-east-1
  * # ...or:
- * prompt: agent:my-agent            # asset ref
+ * prompt: agents/my-agent           # asset ref
  * # ...or:
  * prompt: ./prompts/my-prompt.md    # relative file path
  * # ...or:
@@ -21,7 +21,7 @@
  *   Do the thing.
  *   And the other thing.
  * # ...or:
- * command: akm improve --auto-accept=90 --limit 25
+ * command: akm improve --strategy quick --limit 25
  * enabled: true                     # default true
  * name: Daily backup
  * description: …
@@ -29,16 +29,20 @@
  * tags: [scheduled, backup]
  * ```
  *
- * Validation lives in {@link validateTaskDocument}. The parser only enforces
- * shape; cron syntax, target reachability, and profile availability are
+ * Validation lives in {@link validateTaskDocument}. The parser enforces the
+ * strict source shape; cron syntax and target reachability are
  * checked separately so callers can choose how strictly to surface errors.
  */
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
+import { isFullRefInput } from "../core/asset/resolve-ref.js";
 import { UsageError } from "../core/errors.js";
+import { formatExtraParamsIssue, validateExtraParams } from "../core/extra-params.js";
 import { TASK_SCHEMA_VERSION } from "./schema.js";
+import { validateTaskId } from "./task-id.js";
 export function parseTaskDocument(input) {
-    const { yaml, filePath, id } = input;
+    const { yaml, filePath } = input;
+    const id = validateTaskId(input.id);
     let data;
     try {
         const parsed = parseYaml(yaml);
@@ -52,15 +56,17 @@ export function parseTaskDocument(input) {
             throw err;
         throw new UsageError(`Task "${id}" has invalid YAML: ${err instanceof Error ? err.message : String(err)}. File: ${filePath}`, "INVALID_FLAG_VALUE");
     }
-    const schedule = readString(data.schedule, "schedule", filePath);
+    requireVersion(data, id, filePath);
+    rejectUnknownKeys(data, id, filePath);
+    const schedule = requireString(data.schedule, "schedule", filePath);
     if (!schedule) {
         throw new UsageError(`Task "${id}" is missing a schedule (YAML key "schedule"). File: ${filePath}`, "MISSING_REQUIRED_ARGUMENT");
     }
-    const enabled = data.enabled === undefined ? true : data.enabled === true;
-    const name = readString(data.name, "name", filePath);
-    const description = readString(data.description, "description", filePath);
-    const when_to_use = readString(data.when_to_use, "when_to_use", filePath);
-    const tags = readStringArray(data.tags);
+    const enabled = readEnabled(data.enabled, filePath);
+    const name = optionalString(data.name, "name", filePath);
+    const description = optionalString(data.description, "description", filePath);
+    const when_to_use = optionalString(data.when_to_use, "when_to_use", filePath);
+    const tags = readTags(data.tags, filePath);
     const hasWorkflow = "workflow" in data && data.workflow !== "" && data.workflow != null;
     const hasPrompt = "prompt" in data && data.prompt !== "" && data.prompt != null;
     const hasCommand = "command" in data && data.command !== "" && data.command != null;
@@ -73,7 +79,8 @@ export function parseTaskDocument(input) {
     }
     let target;
     if (hasWorkflow) {
-        const ref = readString(data.workflow, "workflow", filePath);
+        rejectTargetFields(data, ["params"], id, filePath);
+        const ref = requireString(data.workflow, "workflow", filePath);
         if (!ref) {
             throw new UsageError(`Task "${id}" has empty \`workflow\`. File: ${filePath}`, "INVALID_FLAG_VALUE");
         }
@@ -84,98 +91,146 @@ export function parseTaskDocument(input) {
         };
     }
     else if (hasCommand) {
-        const cmd = readCommand(data.command, filePath, id);
-        target = { kind: "command", cmd };
+        rejectTargetFields(data, ["timeoutMs"], id, filePath);
+        target = { kind: "command", cmd: readCommand(data.command, filePath, id) };
     }
     else {
-        const promptRaw = readString(data.prompt, "prompt", filePath);
+        rejectTargetFields(data, ["engine", "model", "timeoutMs", "llm"], id, filePath);
+        const promptRaw = requireString(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);
+        const engine = optionalString(data.engine, "engine", filePath);
+        const model = optionalString(data.model, "model", filePath);
+        const timeoutMs = readTimeout(data.timeoutMs, filePath);
+        const llm = readLlmOverrides(data.llm, filePath);
         target = {
             kind: "prompt",
             source: resolvePromptSource(promptRaw, filePath, id),
-            profile: profile && profile.length > 0 ? profile : undefined,
+            ...(engine ? { engine } : {}),
+            ...(model ? { model } : {}),
+            ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+            ...(llm ? { llm } : {}),
         };
     }
-    // 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)
-    }
+    const timeoutMs = hasCommand ? readTimeout(data.timeoutMs, filePath) : undefined;
     return {
+        version: TASK_SCHEMA_VERSION,
         schemaVersion: TASK_SCHEMA_VERSION,
         id,
         schedule,
         enabled,
         target,
-        name: name && name.length > 0 ? name : undefined,
-        description: description && description.length > 0 ? description : undefined,
-        when_to_use: when_to_use && when_to_use.length > 0 ? when_to_use : undefined,
-        tags: tags && tags.length > 0 ? tags : undefined,
+        ...(name ? { name } : {}),
+        ...(description ? { description } : {}),
+        ...(when_to_use ? { when_to_use } : {}),
+        ...(tags ? { tags } : {}),
         source: { path: filePath },
         timeoutMs,
     };
 }
+const TASK_KEYS = new Set([
+    "version",
+    "name",
+    "description",
+    "when_to_use",
+    "tags",
+    "schedule",
+    "enabled",
+    "workflow",
+    "prompt",
+    "command",
+    "params",
+    "engine",
+    "model",
+    "timeoutMs",
+    "llm",
+]);
+const SHARED_KEYS = new Set(["version", "name", "description", "when_to_use", "tags", "schedule", "enabled"]);
+function requireVersion(data, id, filePath) {
+    if (data.version === TASK_SCHEMA_VERSION)
+        return;
+    const actual = data.version === undefined ? "missing" : JSON.stringify(data.version);
+    throw new UsageError(`TASK_SCHEMA_VERSION_UNSUPPORTED: Task "${id}" uses task schema version ${actual}; version: 2 is required. File: ${filePath}`, "TASK_SCHEMA_VERSION_UNSUPPORTED", "Use task schema version: 2.");
+}
+function rejectUnknownKeys(data, id, filePath) {
+    const unknown = Object.keys(data).filter((key) => !TASK_KEYS.has(key));
+    if (unknown.length > 0) {
+        throw new UsageError(`Task "${id}" has unknown key(s): ${unknown.join(", ")}. File: ${filePath}`, "INVALID_FLAG_VALUE");
+    }
+}
+function rejectTargetFields(data, allowed, id, filePath) {
+    const forbidden = Object.keys(data).filter((key) => !SHARED_KEYS.has(key) && !allowed.includes(key) && !["workflow", "prompt", "command"].includes(key));
+    if (forbidden.length > 0) {
+        throw new UsageError(`Task "${id}" has field(s) not valid for this target: ${forbidden.join(", ")}. File: ${filePath}`, "INVALID_FLAG_VALUE");
+    }
+}
 /**
  * Resolve a `prompt:` value into a {@link TaskPromptSource} variant.
  *
- *   • "<type>:<name>" (asset ref)              → asset
+ *   • "[bundle//]<subdir>/<name>" (asset ref)  → asset
  *   • "./foo.md", "../foo.md", "/abs"          → file
  *   • "C:\\abs" (Windows absolute)             → file
- *   • anything else (incl. block scalars)      → inline text
+ *   • anything else (including colon text and block scalars) → inline text
  */
 function resolvePromptSource(raw, filePath, id) {
     const trimmed = raw.trim();
+    if (!trimmed) {
+        throw new UsageError(`Task "${id}" has empty \`prompt\`. File: ${filePath}`, "MISSING_REQUIRED_ARGUMENT");
+    }
     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)) {
+    // Canonical 0.9.0 asset ref: `[bundle//]<stash-subdir>/<name>`. Detection is
+    // delegated to the canonical parser (never a hand-rolled regex) — only a
+    // conceptId whose leading segment is a real stash subdir counts as a ref; a
+    // bare `word/word` inline prompt (no known subdir) stays inline text (D-R3).
+    if (isFullRefInput(trimmed)) {
         return { kind: "asset", ref: trimmed };
     }
-    if (!trimmed) {
-        throw new UsageError(`Task "${id}" has empty \`prompt\`. File: ${filePath}`, "MISSING_REQUIRED_ARGUMENT");
-    }
     return { kind: "inline", text: trimmed };
 }
-function readString(value, key, filePath) {
+function optionalString(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);
+        return value;
     throw new UsageError(`Key "${key}" must be a string. File: ${filePath}`, "INVALID_FLAG_VALUE");
 }
-function readStringArray(value) {
+function requireString(value, key, filePath) {
+    const result = optionalString(value, key, filePath);
+    if (result === undefined || result.length === 0) {
+        throw new UsageError(`Key "${key}" must be a non-empty string. File: ${filePath}`, "INVALID_FLAG_VALUE");
+    }
+    return result;
+}
+function readEnabled(value, filePath) {
+    if (value === undefined)
+        return true;
+    if (typeof value !== "boolean")
+        throw new UsageError(`Key "enabled" must be a boolean. File: ${filePath}`, "INVALID_FLAG_VALUE");
+    return value;
+}
+function readTags(value, filePath) {
     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);
+        if (!value.every((entry) => typeof entry === "string" && entry.length > 0)) {
+            throw new UsageError(`Key "tags" must be an array of non-empty strings. File: ${filePath}`, "INVALID_FLAG_VALUE");
+        }
+        return value;
     }
-    return undefined;
+    throw new UsageError(`Key "tags" must be an array of strings. File: ${filePath}`, "INVALID_FLAG_VALUE");
 }
 function readCommand(value, filePath, id) {
     if (Array.isArray(value)) {
-        const parts = value.filter((v) => typeof v === "string" && v.trim().length > 0);
+        if (!value.every((entry) => typeof entry === "string" && entry.length > 0)) {
+            throw new UsageError(`Task "${id}" command array must contain non-empty strings. File: ${filePath}`, "INVALID_FLAG_VALUE");
+        }
+        const parts = value;
         if (parts.length === 0) {
             throw new UsageError(`Task "${id}" has empty \`command\` array. File: ${filePath}`, "INVALID_FLAG_VALUE");
         }
@@ -196,16 +251,53 @@ function readParams(value, filePath) {
     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;
-            }
+    throw new UsageError(`Key "params" must be a mapping. File: ${filePath}`, "INVALID_FLAG_VALUE");
+}
+function readTimeout(value, filePath) {
+    if (value === undefined)
+        return undefined;
+    if (value === null)
+        return null;
+    if (typeof value === "number" && Number.isInteger(value) && value > 0)
+        return value;
+    throw new UsageError(`Key "timeoutMs" must be a positive integer or null. File: ${filePath}`, "INVALID_FLAG_VALUE");
+}
+function readLlmOverrides(value, filePath) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new UsageError(`Key "llm" must be a mapping. File: ${filePath}`, "INVALID_FLAG_VALUE");
+    }
+    const data = value;
+    const allowed = new Set([
+        "temperature",
+        "maxTokens",
+        "supportsJsonSchema",
+        "extraParams",
+        "contextLength",
+        "enableThinking",
+    ]);
+    const unknown = Object.keys(data).filter((key) => !allowed.has(key));
+    if (unknown.length)
+        throw new UsageError(`Key "llm" has unknown field(s): ${unknown.join(", ")}. File: ${filePath}`, "INVALID_FLAG_VALUE");
+    if (data.temperature !== undefined && (typeof data.temperature !== "number" || !Number.isFinite(data.temperature))) {
+        throw new UsageError(`Key "llm.temperature" must be a finite number. File: ${filePath}`, "INVALID_FLAG_VALUE");
+    }
+    for (const key of ["maxTokens", "contextLength"]) {
+        if (data[key] !== undefined && (!Number.isInteger(data[key]) || data[key] <= 0)) {
+            throw new UsageError(`Key "llm.${key}" must be a positive integer. File: ${filePath}`, "INVALID_FLAG_VALUE");
+        }
+    }
+    for (const key of ["supportsJsonSchema", "enableThinking"]) {
+        if (data[key] !== undefined && typeof data[key] !== "boolean") {
+            throw new UsageError(`Key "llm.${key}" must be a boolean. File: ${filePath}`, "INVALID_FLAG_VALUE");
         }
-        catch {
-            // fall through
+    }
+    if (data.extraParams !== undefined) {
+        const issue = validateExtraParams(data.extraParams)[0];
+        if (issue) {
+            throw new UsageError(`${formatExtraParamsIssue('Key "llm.extraParams"', issue)}. File: ${filePath}`, "INVALID_FLAG_VALUE");
         }
     }
-    throw new UsageError(`Key "params" must be a mapping or a JSON object. File: ${filePath}`, "INVALID_FLAG_VALUE");
+    return data;
 }