akm-cli 0.9.3 → 0.9.5

package/dist/tasks/source/task-to-v3.js

@@ -0,0 +1,512 @@
+// 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/.
+/** Pure, byte-producing legacy-task to task-v3 migration planner. */
+import crypto from "node:crypto";
+import path from "node:path";
+import { LineCounter, parseDocument, stringify as stringifyYaml } from "yaml";
+import { bundleRefToString, parseBundleRef } from "../../core/asset/asset-ref.js";
+import { formatExtraParamsIssue, validateExtraParams } from "../../core/extra-params.js";
+import { WORKFLOW_ENV_VAR_NAME_PATTERN, WORKFLOW_MAX_EXEC_PASS_ENV, WORKFLOW_MAX_RETRIES, WORKFLOW_MAX_TIMEOUT_MS, } from "../../workflows/resource-limits.js";
+import { validateTaskId } from "../task-id.js";
+import { assertBoundedTaskYamlDocument, TASK_V3_MAX_SOURCE_BYTES } from "./bounded-document.js";
+import { classifyTaskV3Uses, parseTaskV3Yaml } from "./task-source-v3-frozen.js";
+import { parseTaskSourceV4 } from "./task-source-v4.js";
+const V2_KEYS = new Set([
+    "version",
+    "name",
+    "description",
+    "when_to_use",
+    "tags",
+    "schedule",
+    "enabled",
+    "workflow",
+    "prompt",
+    "command",
+    "params",
+    "engine",
+    "model",
+    "timeoutMs",
+    "maxSteps",
+    "maxRetries",
+    "llm",
+    "redact",
+]);
+const V2_SHARED_KEYS = new Set([
+    "version",
+    "name",
+    "description",
+    "when_to_use",
+    "tags",
+    "schedule",
+    "enabled",
+    "redact",
+]);
+const V2_LLM_KEYS = new Set([
+    "temperature",
+    "maxTokens",
+    "supportsJsonSchema",
+    "extraParams",
+    "contextLength",
+    "enableThinking",
+    "reasoningEffort",
+]);
+const SAFE_V2_COMMAND_TOKEN = /^[A-Za-z0-9_./:=+,-]+$/;
+const SHELL_ASSIGNMENT_WORD = /^[A-Za-z_][A-Za-z0-9_]*=/;
+/**
+ * V2 executed argv directly, while v3 `run:` enters a host shell. An explicit
+ * path bypasses shell aliases/builtins; `akm` is the one bare executable whose
+ * v3 runtime resolution is contractually pinned to the current installation.
+ */
+function shellStableV2Executable(executable) {
+    return executable === "akm" || executable.includes("/");
+}
+/**
+ * `env NAME=value... cmd args...` is env(1) itself resolving and exec'ing
+ * `cmd` via its own PATH search — that lookup happens inside env's execvp()
+ * regardless of whether env was launched by direct execve (v2) or by a host
+ * shell (v3 `run:`). The shell-vs-argv divergence `shellStableV2Executable`
+ * guards against (bare names shadowed by shell aliases/builtins/functions)
+ * therefore does not apply to whatever env ultimately invokes, so skip past
+ * a leading `env` and its `NAME=value` assignments to find the real target.
+ * Returns the original tokens, unchanged, when there is no such target
+ * (e.g. `env` with nothing after its assignments).
+ */
+function skipEnvAssignmentPrefix(tokens) {
+    if (tokens[0] !== "env")
+        return { tokens, envWrapped: false };
+    let index = 1;
+    while (index < tokens.length && SHELL_ASSIGNMENT_WORD.test(tokens[index]))
+        index += 1;
+    if (index >= tokens.length)
+        return { tokens, envWrapped: false };
+    return { tokens: tokens.slice(index), envWrapped: true };
+}
+const KNOWN_PROMPT_REF_FAMILIES = new Set([
+    "agents",
+    "commands",
+    "env",
+    "facts",
+    "instructions",
+    "knowledge",
+    "lessons",
+    "memories",
+    "scripts",
+    "secrets",
+    "sessions",
+    "skills",
+    "tasks",
+    "workflows",
+]);
+function hash(bytes) {
+    return crypto.createHash("sha256").update(bytes).digest("hex");
+}
+function base(input) {
+    return {
+        filePath: input.filePath,
+        before: Buffer.from(input.bytes),
+        beforeHash: hash(input.bytes),
+        mode: input.mode,
+        writable: input.writable,
+        ...(input.onDiskWritable !== undefined ? { onDiskWritable: input.onDiskWritable } : {}),
+        ...(input.containmentRoot ? { containmentRoot: input.containmentRoot } : {}),
+    };
+}
+function blocked(input, reason, detail) {
+    return Object.freeze({ status: "blocked", ...base(input), reason, ...(detail ? { detail } : {}) });
+}
+function plainRecord(value, label) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${label} must be a mapping`);
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        throw new Error(`${label} must use a plain or null prototype`);
+    return value;
+}
+function exactString(value, label, nonempty = false) {
+    if (typeof value !== "string" || (nonempty && value.trim().length === 0)) {
+        throw new Error(`${label} must be ${nonempty ? "a non-empty " : "a "}string`);
+    }
+    return value;
+}
+function optionalString(value, label) {
+    if (value === undefined || value === null)
+        return undefined;
+    return exactString(value, label);
+}
+function parseLegacyTaskYaml(input) {
+    if (input.bytes.byteLength > TASK_V3_MAX_SOURCE_BYTES) {
+        throw new Error(`task YAML exceeds the 1 MiB (${TASK_V3_MAX_SOURCE_BYTES}-byte) source resource limit`);
+    }
+    let source;
+    try {
+        source = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(input.bytes);
+    }
+    catch {
+        throw new Error("task YAML contains invalid UTF-8 bytes");
+    }
+    const lineCounter = new LineCounter();
+    let document;
+    try {
+        document = parseDocument(source, { lineCounter, uniqueKeys: true });
+    }
+    catch (cause) {
+        throw new Error(`invalid YAML: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    const [parseError] = document.errors;
+    if (parseError)
+        throw new Error(`invalid YAML: ${parseError.message.split("\n")[0]}`);
+    const [parseWarning] = document.warnings;
+    if (parseWarning)
+        throw new Error(`unsupported YAML construct: ${parseWarning.message}`);
+    assertBoundedTaskYamlDocument(document, {
+        filePath: input.filePath,
+        sourceLabel: "task v2 migration source",
+        lineCounter,
+    });
+    return { data: plainRecord(document.toJS({ maxAliasCount: 0 }), "task YAML"), source };
+}
+function validateCommonV2(data) {
+    const unknown = Object.keys(data).filter((key) => !V2_KEYS.has(key));
+    if (unknown.length > 0)
+        throw new Error(`unknown v2 field(s): ${unknown.join(", ")}`);
+    exactString(data.schedule, "schedule", true);
+    if (data.enabled !== undefined && typeof data.enabled !== "boolean")
+        throw new Error("enabled must be a boolean");
+    for (const key of ["name", "description", "when_to_use"])
+        optionalString(data[key], key);
+    if (data.tags !== undefined && data.tags !== null) {
+        if (!Array.isArray(data.tags) || data.tags.some((entry) => typeof entry !== "string" || entry.length === 0)) {
+            throw new Error("tags must be an array of non-empty strings");
+        }
+    }
+    if (data.timeoutMs !== undefined && data.timeoutMs !== null) {
+        if (!Number.isInteger(data.timeoutMs) ||
+            data.timeoutMs < 1 ||
+            data.timeoutMs > WORKFLOW_MAX_TIMEOUT_MS) {
+            throw new Error(`timeoutMs must be null or an integer from 1 through ${WORKFLOW_MAX_TIMEOUT_MS}`);
+        }
+    }
+    if (data.redact !== undefined && data.redact !== null) {
+        if (!Array.isArray(data.redact) ||
+            data.redact.length > WORKFLOW_MAX_EXEC_PASS_ENV ||
+            data.redact.some((entry) => typeof entry !== "string" || !WORKFLOW_ENV_VAR_NAME_PATTERN.test(entry))) {
+            throw new Error("redact must contain only bounded environment variable names");
+        }
+    }
+}
+function validateTargetFields(data, allowed) {
+    const targetFields = new Set([...allowed, "workflow", "prompt", "command"]);
+    const invalid = Object.keys(data).filter((key) => !V2_SHARED_KEYS.has(key) && !targetFields.has(key));
+    if (invalid.length > 0)
+        throw new Error(`field(s) not valid for this target: ${invalid.join(", ")}`);
+}
+function validateV2Llm(value) {
+    if (value === undefined)
+        return undefined;
+    const llm = plainRecord(value, "llm");
+    const unknown = Object.keys(llm).filter((key) => !V2_LLM_KEYS.has(key));
+    if (unknown.length > 0)
+        throw new Error(`llm has unknown field(s): ${unknown.join(", ")}`);
+    if (llm.temperature !== undefined && (typeof llm.temperature !== "number" || !Number.isFinite(llm.temperature))) {
+        throw new Error("llm.temperature must be a finite number");
+    }
+    for (const key of ["maxTokens", "contextLength"]) {
+        if (llm[key] !== undefined && (!Number.isInteger(llm[key]) || llm[key] <= 0)) {
+            throw new Error(`llm.${key} must be a positive integer`);
+        }
+    }
+    for (const key of ["supportsJsonSchema", "enableThinking"]) {
+        if (llm[key] !== undefined && typeof llm[key] !== "boolean")
+            throw new Error(`llm.${key} must be a boolean`);
+    }
+    if (llm.reasoningEffort !== undefined && (typeof llm.reasoningEffort !== "string" || !llm.reasoningEffort.trim())) {
+        throw new Error("llm.reasoningEffort must be a non-empty string");
+    }
+    if (llm.extraParams !== undefined) {
+        const issue = validateExtraParams(llm.extraParams)[0];
+        if (issue)
+            throw new Error(formatExtraParamsIssue("llm.extraParams", issue));
+    }
+    return llm;
+}
+function commonAkm(data) {
+    const akm = {
+        schedule: exactString(data.schedule, "schedule", true),
+        enabled: data.enabled === undefined ? true : data.enabled,
+    };
+    for (const key of ["description", "when_to_use", "tags"]) {
+        if (data[key] !== undefined && data[key] !== null)
+            akm[key] = data[key];
+    }
+    return akm;
+}
+function addRuntimeOverrides(data, akm) {
+    for (const key of ["engine", "model"]) {
+        const value = optionalString(data[key], key);
+        if (value)
+            akm[key] = value;
+    }
+    const llm = validateV2Llm(data.llm);
+    if (llm !== undefined)
+        akm.inference = llm;
+    if (data.timeoutMs !== undefined)
+        akm.timeout = data.timeoutMs;
+    if (data.redact !== undefined && data.redact !== null) {
+        akm.redact = [...new Set(data.redact)];
+    }
+}
+function addSharedNonPromptOverrides(data, akm) {
+    if (data.timeoutMs !== undefined)
+        akm.timeout = data.timeoutMs;
+    if (data.redact !== undefined && data.redact !== null) {
+        akm.redact = [...new Set(data.redact)];
+    }
+}
+function promptSourceKind(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.startsWith("./") ||
+        trimmed.startsWith("../") ||
+        path.isAbsolute(trimmed) ||
+        /^[A-Za-z]:[\\/]/.test(trimmed)) {
+        return "file";
+    }
+    try {
+        const parsed = parseBundleRef(trimmed);
+        const family = parsed.conceptId.split("/", 1)[0] ?? "";
+        if (bundleRefToString(parsed) !== trimmed || !parsed.conceptId.includes("/")) {
+            return "inline";
+        }
+        if (!KNOWN_PROMPT_REF_FAMILIES.has(family))
+            return parsed.bundle === undefined ? "inline" : "other-ref";
+        if (family === "agents")
+            return "agent";
+        if (family === "commands")
+            return "command";
+        return "other-ref";
+    }
+    catch {
+        return "inline";
+    }
+}
+function migratedObject(data) {
+    validateCommonV2(data);
+    const targets = ["workflow", "prompt", "command"].filter((key) => Object.hasOwn(data, key) && data[key] !== null && data[key] !== "");
+    if (targets.length !== 1)
+        throw new Error("v2 task must declare exactly one of workflow, prompt, or command");
+    const output = { version: 3 };
+    if (data.name !== undefined && data.name !== null)
+        output.name = data.name;
+    const akm = commonAkm(data);
+    if (targets[0] === "workflow") {
+        validateTargetFields(data, ["params", "timeoutMs", "maxSteps", "maxRetries"]);
+        const ref = exactString(data.workflow, "workflow", true).trim();
+        let target;
+        try {
+            target = classifyTaskV3Uses(ref);
+        }
+        catch {
+            throw new Error("workflow is not a canonical v3 asset ref");
+        }
+        if (target.kind !== "workflow")
+            throw new Error("workflow target is not a workflows/ ref");
+        output.uses = ref;
+        if (data.params !== undefined && data.params !== null) {
+            const params = plainRecord(data.params, "params");
+            output.with = params;
+        }
+        if (data.maxSteps !== undefined && data.maxSteps !== null) {
+            if (!Number.isSafeInteger(data.maxSteps) || data.maxSteps < 1)
+                throw new Error("maxSteps must be positive");
+            akm.maxSteps = data.maxSteps;
+        }
+        if (data.maxRetries !== undefined && data.maxRetries !== null) {
+            if (!Number.isSafeInteger(data.maxRetries) ||
+                data.maxRetries < 0 ||
+                data.maxRetries > WORKFLOW_MAX_RETRIES) {
+                throw new Error(`maxRetries must be from 0 through ${WORKFLOW_MAX_RETRIES}`);
+            }
+            akm.maxRetries = data.maxRetries;
+        }
+        addSharedNonPromptOverrides(data, akm);
+    }
+    else if (targets[0] === "prompt") {
+        validateTargetFields(data, ["engine", "model", "timeoutMs", "llm"]);
+        const prompt = exactString(data.prompt, "prompt", true).trim();
+        const kind = promptSourceKind(prompt);
+        if (kind === "file")
+            return "dynamic-file-read-cannot-be-inlined-without-changing-semantics";
+        if (kind === "agent")
+            return "agent-ref-has-persona-but-no-command-work";
+        if (kind === "other-ref")
+            return "non-command-asset-has-no-v3-command-ref-equivalent";
+        if (kind === "command")
+            output.uses = prompt;
+        else {
+            output.uses = "akm/command";
+            output.with = { content: prompt };
+        }
+        addRuntimeOverrides(data, akm);
+    }
+    else {
+        validateTargetFields(data, ["timeoutMs"]);
+        if (Array.isArray(data.command))
+            return "argv-array-has-no-portable-shell-string";
+        const command = exactString(data.command, "command", true).trim();
+        if (/['"\\]/.test(command))
+            return "shell-quoting-changes-v2-whitespace-split-semantics";
+        const tokens = command.split(/\s+/).filter(Boolean);
+        if (tokens.length === 0 || tokens.some((token) => !SAFE_V2_COMMAND_TOKEN.test(token))) {
+            return "shell-operators-change-v2-literal-argv-semantics";
+        }
+        const { tokens: targetTokens, envWrapped } = skipEnvAssignmentPrefix(tokens);
+        const executable = targetTokens[0];
+        if (SHELL_ASSIGNMENT_WORD.test(executable) || (!envWrapped && !shellStableV2Executable(executable))) {
+            return "shell-command-resolution-changes-v2-literal-argv-semantics";
+        }
+        output.run = tokens.join(" ");
+        addSharedNonPromptOverrides(data, akm);
+    }
+    output.akm = akm;
+    return output;
+}
+function isReason(value) {
+    return typeof value === "string";
+}
+/** Convert one already-normalized legacy record directly to final task v3. */
+export function planLegacyTaskDataToV3(input, data) {
+    if (data.version !== 2) {
+        return blocked(input, "unsupported-task-version", `expected normalized legacy version 2, got ${String(data.version)}`);
+    }
+    if (!input.writable || input.onDiskWritable === false) {
+        return blocked(input, "read-only-source", !input.writable ? "the owning source is not writable" : "the source file or publication directory is read-only");
+    }
+    try {
+        validateTaskId(path.basename(input.filePath, ".yml"));
+    }
+    catch (cause) {
+        return blocked(input, "invalid-v2-task", cause instanceof Error ? cause.message : String(cause));
+    }
+    let migrated;
+    try {
+        migrated = migratedObject(data);
+    }
+    catch (cause) {
+        return blocked(input, "invalid-v2-task", cause instanceof Error ? cause.message : String(cause));
+    }
+    if (isReason(migrated))
+        return blocked(input, migrated);
+    const after = Buffer.from(stringifyYaml(migrated), "utf8");
+    try {
+        parseTaskV3Yaml({
+            yaml: after.toString("utf8"),
+            filePath: input.filePath,
+            ...(input.containmentRoot ? { workspaceRoot: input.containmentRoot } : {}),
+        });
+    }
+    catch (cause) {
+        return blocked(input, "generated-v3-validation-failed", cause instanceof Error ? cause.message : String(cause));
+    }
+    return Object.freeze({
+        status: "changed",
+        ...base(input),
+        reason: "task-converted",
+        after,
+        afterHash: hash(after),
+    });
+}
+/** Plan exactly one source file without touching disk. */
+export function planTaskToV3File(input) {
+    let data;
+    let source;
+    try {
+        ({ data, source } = parseLegacyTaskYaml(input));
+    }
+    catch (cause) {
+        return blocked(input, "invalid-task-yaml", cause instanceof Error ? cause.message : String(cause));
+    }
+    if (data.version === 3) {
+        try {
+            parseTaskV3Yaml({
+                yaml: source,
+                filePath: input.filePath,
+                ...(input.containmentRoot ? { workspaceRoot: input.containmentRoot } : {}),
+            });
+            return Object.freeze({ status: "skipped", ...base(input), reason: "already-v3" });
+        }
+        catch (cause) {
+            return blocked(input, "invalid-v3-task", cause instanceof Error ? cause.message : String(cause));
+        }
+    }
+    if (data.version === 4) {
+        try {
+            parseTaskSourceV4({
+                yaml: source,
+                filePath: input.filePath,
+                ...(input.containmentRoot ? { workspaceRoot: input.containmentRoot } : {}),
+            });
+            return Object.freeze({ status: "skipped", ...base(input), reason: "already-v4" });
+        }
+        catch (cause) {
+            return blocked(input, "invalid-v4-task", cause instanceof Error ? cause.message : String(cause));
+        }
+    }
+    if (data.version !== 2) {
+        return blocked(input, "unsupported-task-version", `expected version 2, 3, or 4, got ${String(data.version)}`);
+    }
+    return planLegacyTaskDataToV3(input, data);
+}
+function generationFor(files) {
+    const digest = crypto.createHash("sha256");
+    digest.update("akm-task-to-v3-plan-v1\0");
+    for (const file of files) {
+        digest.update(file.filePath);
+        digest.update("\0");
+        digest.update(file.status);
+        digest.update("\0");
+        digest.update(file.reason);
+        digest.update("\0");
+        digest.update(String(file.mode));
+        digest.update("\0");
+        digest.update(file.writable ? "writable" : "read-only");
+        digest.update("\0");
+        digest.update(file.onDiskWritable === false ? "disk-read-only" : "disk-writable-or-unspecified");
+        digest.update("\0");
+        if (file.containmentRoot)
+            digest.update(file.containmentRoot);
+        digest.update("\0");
+        digest.update(file.beforeHash);
+        digest.update("\0");
+        if (file.status === "changed")
+            digest.update(file.afterHash);
+        digest.update("\0");
+        if (file.detail)
+            digest.update(file.detail);
+        digest.update("\0");
+    }
+    return digest.digest("hex");
+}
+/** Build/fingerprint a plan from already-derived immutable outcomes. */
+export function taskToV3PlanFromOutcomes(outcomes) {
+    const files = [...outcomes].sort((left, right) => left.filePath < right.filePath ? -1 : left.filePath > right.filePath ? 1 : 0);
+    for (let index = 1; index < files.length; index += 1) {
+        const previous = files[index - 1];
+        const current = files[index];
+        if (previous && current && path.resolve(previous.filePath) === path.resolve(current.filePath)) {
+            throw new Error(`duplicate task migration file path: ${current.filePath}`);
+        }
+    }
+    return Object.freeze({ schemaVersion: 1, generation: generationFor(files), files: Object.freeze(files) });
+}
+/** Plan a complete, stable file set. Input order cannot change the result. */
+export function planTaskToV3Migration(inputs) {
+    const sorted = [...inputs].sort((left, right) => left.filePath < right.filePath ? -1 : left.filePath > right.filePath ? 1 : 0);
+    let previous;
+    for (const current of sorted) {
+        if (previous && path.resolve(previous.filePath) === path.resolve(current.filePath)) {
+            throw new Error(`duplicate task migration file path: ${current.filePath}`);
+        }
+        previous = current;
+    }
+    return taskToV3PlanFromOutcomes(sorted.map(planTaskToV3File));
+}