akm-cli 0.9.2-alpha.4 → 0.9.2

package/dist/tasks/source/parse-task-source.js

@@ -0,0 +1,59 @@
+// 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/.
+/**
+ * The task source version router (spec docs/plans/specs/p4-deletions-closeout.md
+ * §3.2.2).
+ *
+ * Runs the bounded YAML front end ONCE (`readBoundedTaskSourceYaml`), reads
+ * `root.version`, and either dispatches into `parseTaskSourceV4Document` or
+ * fails closed — no second parse, no re-serialization, no synthetic document
+ * (the P1b §4.3 invariant this phase carries forward).
+ *
+ * The terminal routing table:
+ *
+ *   | root `version`        | outcome                                                        |
+ *   |------------------------|-----------------------------------------------------------------|
+ *   | `4`                    | `parseTaskSourceV4Document` — the new grammar (row B-13)        |
+ *   | any other number       | `TASK_SCHEMA_VERSION_UNSUPPORTED`, naming the migrator (B-14/B-15) |
+ *   | absent / not a number  | `parseTaskSourceV4Document` — its own `TASK_SOURCE_INVALID` "version is required and must be 4" / "must be exactly 4" wording (row B-16) |
+ *
+ * A missing or non-numeric `version:` is a MALFORMED v4 document, not a
+ * legacy one — it routes into the v4 parser so the field error names the
+ * one grammar `src` still accepts, rather than a generic "unsupported"
+ * message that would send the user to the migrator for a document that was
+ * never task v2 or v3 in the first place.
+ *
+ * task v2 and task v3 sources are no longer read by `src` at all — the only
+ * surviving reader is the frozen, vendored copy in
+ * `scripts/akm-migrate/migrate/task-source-v3-frozen.ts`, reachable only
+ * through `akm migrate apply` / `akm-migrate`. The front end's own
+ * pre-version failures (source not a string, source too large, YAML
+ * parse/warning/expansion) render with the label `task source` (row B-17,
+ * closing the "task v3 source" label wart P2a's §3.4 recorded).
+ */
+import { UsageError } from "../../core/errors.js";
+import { readBoundedTaskSourceYaml } from "./bounded-document.js";
+import { parseTaskSourceV4Document, TASK_SOURCE_V4_VERSION } from "./task-source-v4.js";
+/** Read the root `version` field without over-accepting non-number values (e.g. the string `"4"`). */
+export function peekTaskSourceVersion(root) {
+    if (root === null || typeof root !== "object" || Array.isArray(root))
+        return undefined;
+    const value = root.version;
+    return typeof value === "number" ? value : undefined;
+}
+const TASK_MIGRATE_HINT = "Run `akm migrate apply --dry-run` to preview the task-v3 to task-source-v4 conversion, then run `akm migrate apply`.";
+/** Parse task source YAML, routing per the terminal table above. */
+export function parseTaskSource(input) {
+    const { root, lineAt } = readBoundedTaskSourceYaml(input, { sourceLabel: "task source" });
+    const version = peekTaskSourceVersion(root);
+    if (version !== undefined && version !== TASK_SOURCE_V4_VERSION) {
+        throw new UsageError(`TASK_SCHEMA_VERSION_UNSUPPORTED: Task at ${input.filePath} uses task schema version ${version}, which this release does not accept.`, "TASK_SCHEMA_VERSION_UNSUPPORTED", TASK_MIGRATE_HINT);
+    }
+    const documentOptions = {
+        filePath: input.filePath,
+        ...(input.workspaceRoot ? { workspaceRoot: input.workspaceRoot } : {}),
+        lineAt,
+    };
+    return Object.freeze({ version: 4, v4: parseTaskSourceV4Document(root, documentOptions) });
+}

package/dist/tasks/source/project-v4.js

@@ -0,0 +1,62 @@
+// 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/.
+/**
+ * Map every top-level task source v4 execution control and D2-N7 survivor
+ * into v3's `akm.*` shape, one field at a time (never a whole-object copy,
+ * so a field task source v4 does not represent — `inputs`, per-binding
+ * `enabled` — can never leak in by accident). Returns `undefined` when
+ * nothing maps, matching v3's own
+ * convention of omitting the `akm` key entirely rather than emitting an
+ * always-present empty object (`source-v3.ts:789`).
+ */
+function projectAkm(document) {
+    const out = {};
+    if (document.description !== undefined)
+        out.description = document.description;
+    if (document.when_to_use !== undefined)
+        out.when_to_use = document.when_to_use;
+    if (document.tags !== undefined)
+        out.tags = document.tags;
+    const execution = document.execution;
+    if (execution.agent !== undefined)
+        out.agent = execution.agent;
+    if (execution.engine !== undefined)
+        out.engine = execution.engine;
+    if (execution.model !== undefined)
+        out.model = execution.model;
+    if (execution.inference !== undefined)
+        out.inference = execution.inference;
+    if (execution.tools !== undefined)
+        out.tools = execution.tools;
+    if (execution.timeout !== undefined)
+        out.timeout = execution.timeout;
+    if (execution.redact !== undefined)
+        out.redact = execution.redact;
+    if (execution.maxSteps !== undefined)
+        out.maxSteps = execution.maxSteps;
+    if (execution.maxRetries !== undefined)
+        out.maxRetries = execution.maxRetries;
+    if (document.output !== undefined)
+        out.outputSchema = document.output;
+    return Object.keys(out).length > 0 ? Object.freeze(out) : undefined;
+}
+/** Project one parsed task source v4 document into the prepare seam's existing input shape (spec §3.5). */
+export function projectTaskSourceV4(document) {
+    const akm = projectAkm(document);
+    const schedules = Object.freeze(document.schedule.map((entry) => Object.freeze({ cron: entry.cron, source: entry.source, ordinal: entry.ordinal })));
+    return Object.freeze({
+        // The literal `3` is the prepare seam's own discriminant
+        // (PreparableTaskDocument = TaskV3SourceDocument), not an assertion that
+        // the source this was projected from was task v3 — `TASK_V3_SCHEMA_VERSION`
+        // is gone (P4 deleted task v3 acceptance from src), and this projection
+        // only ever runs on a task source v4 document (P2a §3.5's recorded wart).
+        version: 3,
+        ...(document.name !== undefined ? { name: document.name } : {}),
+        target: document.target,
+        ...(document.env !== undefined ? { env: document.env } : {}),
+        ...(akm !== undefined ? { akm } : {}),
+        triggers: Object.freeze({ manual: document.manualOnly, schedules }),
+        source: Object.freeze({ path: document.source.path }),
+    });
+}

package/dist/tasks/source/task-input-diagnostics.js

@@ -0,0 +1,36 @@
+// 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/.
+/**
+ * `TASK_INPUT_DIAGNOSTICS` — the task-side message/code vocabulary for
+ * `materializeInputFlags` (spec docs/plans/specs/p2a-task-source-v4.md §1.5
+ * D3-N3, §4.2, §5.1).
+ *
+ * `materializeInputFlags` (`src/execution/input-contract.ts`) contains no
+ * literal user-facing string of its own — every message/code it raises comes
+ * from a caller-supplied `InputFlagDiagnostics`. `src/workflows/ir/params.ts`
+ * supplies `WORKFLOW_PARAMETER_DIAGNOSTICS` for workflow params; this module
+ * is that same seam's task-side sibling, consumed by `akm task run`'s Stage 2
+ * (`src/tasks/run/load-task.ts`). Mirrors `WORKFLOW_PARAMETER_DIAGNOSTICS`'s
+ * shape exactly (`unknownFlag`'s declared-name enumeration in the SEPARATE
+ * `hint`, not the message — `params.ts:65-72`) with task-flavored nouns and
+ * the codes §5.1 binds: `UNKNOWN_FLAG` for an undeclared name,
+ * `INPUT_BINDING_INVALID` for every value/contract failure.
+ */
+import { UsageError } from "../../core/errors.js";
+function invalidTaskInput(name, detail) {
+    return new UsageError(`Task input "--${name}" ${detail}.`, "INPUT_BINDING_INVALID");
+}
+/** The task-input message/code vocabulary for `materializeInputFlags` (D3-N3). */
+export const TASK_INPUT_DIAGNOSTICS = {
+    unknownFlag: (name, declared) => {
+        const available = declared.map((n) => `--${n}`).join(", ");
+        return new UsageError(`Unknown task input "--${name}". Input flags must exactly match a declared task input.`, "UNKNOWN_FLAG", available ? `Declared inputs: ${available}.` : "This task declares no inputs.");
+    },
+    invalidValue: (name, detail) => invalidTaskInput(name, detail),
+    contractViolation: (errors) => new UsageError(`Task input flags do not satisfy the task's declared input schemas:\n${errors
+        .map((error) => `  - ${error.replace(/^\$/, "inputs")}`)
+        .join("\n")}`, "INPUT_BINDING_INVALID"),
+    duplicateNonArray: (name) => invalidTaskInput(name, "was provided more than once but is not declared as an array"),
+    malformedJson: (name) => invalidTaskInput(name, "must contain valid JSON"),
+};