akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/workflows/freeze/resolve-steps.js

@@ -1,86 +0,0 @@
-// 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/.
-import { ConfigError, UsageError } from "../../core/errors.js";
-import { prepareInlineExecution } from "../../integrations/agent/inline-execution.js";
-import { sourceStepProgramUnit, sourceStepRef } from "../source-ir/program.js";
-import { classifyWorkflowStepUses } from "../source-ir/semantics.js";
-import { qualifyRef } from "./environment.js";
-import { childWorkflowDispatch } from "./targets/child-workflow.js";
-import { commandDispatch, commandResult, inlineDispatch } from "./targets/command.js";
-import { directScript } from "./targets/script.js";
-import { directShell } from "./targets/shell.js";
-import { taskDispatch } from "./targets/task.js";
-export async function resolveStep(source, context) {
-    const baseUnit = sourceStepProgramUnit(source);
-    if (source.exec || source.run !== undefined)
-        return directShell(source, baseUnit, context);
-    if (!source.uses)
-        return inlineDispatch(source, baseUnit, context);
-    const target = classifyWorkflowStepUses(source.uses);
-    if (target.kind === "task")
-        return taskDispatch(source, baseUnit, target.ref, context);
-    // A direct `uses: workflows/<ref>` step (spec docs/plans/specs/
-    // p3a-plan-v5-child-freeze.md §4.2, row B-01/B-04). `with:` on this target
-    // IS a valid binding surface (A-N8) — unlike scripts/commands below,
-    // `rejectNonTaskBindingWith` must NOT be extended to it.
-    if (target.kind === "workflow") {
-        return childWorkflowDispatch({
-            source,
-            baseUnit,
-            childRefInput: target.ref,
-            context,
-            via: "direct",
-            authoredInputs: { kind: "with", value: source.with },
-        });
-    }
-    if (target.kind === "script") {
-        rejectNonTaskBindingWith(source, target.ref, "script");
-        return directScript(source, baseUnit, target.ref, context);
-    }
-    if (target.kind === "command" || target.kind === "builtin-command") {
-        if (target.kind === "command")
-            rejectNonTaskBindingWith(source, target.ref, "command");
-        const action = target.kind === "builtin-command"
-            ? source.with
-            : { ref: qualifyRef(target.ref, "commands", context.asset, context.config) };
-        return commandDispatch(source, baseUnit, action, context);
-    }
-    throw new UsageError(`Workflow target ${source.uses} is not executable in 0.9.2.`, "WORKFLOW_SOURCE_INVALID");
-}
-/**
- * A-N5 (spec docs/plans/specs/p2b-input-bindings.md §1.7): `commands/<ref>`
- * and `scripts/<ref>` are not binding surfaces — a `with:` authored on either
- * now fails closed instead of being silently dropped (the same defect P1a
- * closed for `tasks/<ref>`, now repeated for these two targets, B-22/B-23).
- * `akm/command`'s `with:` is its own argument bag
- * (`parseBuiltinCommandAction`) and never routes through here.
- */
-function rejectNonTaskBindingWith(source, ref, kind) {
-    if (source.with === undefined)
-        return;
-    const family = kind === "command" ? "commands" : "scripts";
-    throw new UsageError(`Workflow step ${source.id} cannot pass with: to ${family} target ${ref}; a ${kind} ref is not a binding surface.`, "COMPOSITION_INVALID");
-}
-const NO_ENGINE_AVAILABLE_MESSAGE = "the fixed opencode-sdk fallback is unavailable";
-function isNoEngineAvailable(err) {
-    return err instanceof ConfigError && err.message.includes(NO_ENGINE_AVAILABLE_MESSAGE);
-}
-export function resolveJudge(source, context) {
-    const configuredEngine = context.config.workflow?.judgeEngine;
-    const content = source.gate?.rubric?.trim() ?? "Judge workflow completion.";
-    try {
-        const prepared = prepareInlineExecution({
-            content,
-            config: context.config,
-            invocationKind: "workflow",
-            ...(configuredEngine ? { current: { engine: configuredEngine } } : {}),
-        });
-        return commandResult(source, { onError: "fail", source: sourceStepRef(source) }, prepared, context);
-    }
-    catch (err) {
-        if (configuredEngine || !isNoEngineAvailable(err))
-            throw err;
-        return undefined;
-    }
-}

package/dist/workflows/freeze/source-freeze.js

@@ -1,64 +0,0 @@
-// 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/.
-import { COMPOSITION_INVALID_MULTI_JOB_HINT, UsageError } from "../../core/errors.js";
-import { warn } from "../../core/warn.js";
-import { compileWorkflowSource } from "../source-ir/compile.js";
-import { resolveJudge, resolveStep } from "./resolve-steps.js";
-/**
- * Resolve every authored target through the shared command/task authorities
- * before v4 publication.
- *
- * `composition` and `freezeChild` (spec docs/plans/specs/
- * p3a-plan-v5-child-freeze.md §4.1/§4.3) thread the recursive
- * child-workflow-freeze state down into every step's `ResolutionContext`;
- * `ir/freeze-v4.ts`'s `compileResolveFreezeWorkflowV4` is this function's
- * ONLY caller (directly — P4 deleted the `ir/source-freeze-v4.ts` shim that
- * used to sit on this edge) and supplies both — the root default
- * composition, or the composition
- * `targets/child-workflow.ts` built for a recursive child freeze.
- */
-export async function resolveWorkflowSourceV4(asset, workflowSource, config, collector, composition, freezeChild) {
-    const compiled = compileWorkflowSource(workflowSource.content, { path: asset.path, workspaceRoot: asset.sourcePath });
-    if (!compiled.ok) {
-        // P4-N2 (docs/plans/specs/p4-deletions-closeout.md §3.3.4): a compile
-        // result whose single error is the adapter's multi-job rejection
-        // surfaces as COMPOSITION_INVALID — one authoritative composition
-        // policy; every other compile failure (a YAML syntax error, an
-        // unsupported trigger, …) is WORKFLOW_SOURCE_INVALID. Never blanket-recode.
-        const isMultiJob = compiled.errors.length === 1 && compiled.errors[0]?.code === "multi-job-unsupported";
-        const code = isMultiJob ? "COMPOSITION_INVALID" : "WORKFLOW_SOURCE_INVALID";
-        throw new UsageError(`Workflow source cannot be frozen: ${compiled.errors.map((error) => error.message).join("; ")}`, code, isMultiJob ? COMPOSITION_INVALID_MULTI_JOB_HINT : undefined);
-    }
-    const context = { asset, config, collector, sourceIr: compiled.ir, composition, freezeChild };
-    const units = new Map();
-    const judges = new Map();
-    let engineAnnouncement;
-    const sourceSteps = compiled.ir.jobs[0]?.steps ?? [];
-    for (const sourceStep of sourceSteps) {
-        if (!sourceStep.route) {
-            const resolved = await resolveStep(sourceStep, context);
-            units.set(sourceStep.id, Object.freeze(resolved));
-            engineAnnouncement ??= resolved.engineAnnouncement;
-        }
-        if (sourceStep.gate?.rubric?.trim()) {
-            const judge = resolveJudge(sourceStep, context);
-            if (judge === undefined) {
-                warn(`Workflow step "${sourceStep.id}" has completion criteria but no verification engine is available ` +
-                    "(set workflow.judgeEngine, defaults.engine, or install an opencode-sdk binary). The step will block " +
-                    "for `akm workflow resume` once it is reached.");
-                continue;
-            }
-            if (judge.target.kind !== "command")
-                throw new Error(`workflow judge ${sourceStep.id} did not resolve to a command target`);
-            judges.set(sourceStep.id, judge.target);
-            engineAnnouncement ??= judge.engineAnnouncement;
-        }
-    }
-    return Object.freeze({
-        sourceIr: compiled.ir,
-        units,
-        judges,
-        ...(engineAnnouncement ? { engineAnnouncement } : {}),
-    });
-}

package/dist/workflows/ir/compile.js

@@ -1,321 +0,0 @@
-// 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/.
-/**
- * Frontend -> unresolved workflow plan compiler (workflow-format-unification).
- *
- * ONE frontend now: {@link compileWorkflowPlan} lowers adapter-neutral source
- * IR into the current unresolved plan draft. Markdown and YAML never reach a
- * format-specific runtime compiler. This pass owns the
- * semantic rules the parser deliberately does not check:
- *
- *   - every reference string (`map.over` / `route.input` / `inputs[]`) parses
- *     against the CLOSED two-root grammar (`program/expressions.ts`);
- *   - `steps.<id>` references name an EARLIER step (a producer that has
- *     already run when the reference resolves);
- *   - `inputs:` entries must reference a STEP OUTPUT, never `params.*` — params
- *     are already attached to every unit unconditionally, so naming one as a
- *     declared input would be redundant.
- *
- * Node-id convention (stable, unique within a plan):
- *   step root  → `<stepId>`          (unit) or `<stepId>.map` (map)
- *   map unit   → `<stepId>.unit`     (template instantiated per item)
- *   gate       → `<stepId>.gate`
- *
- * Returns accumulated `WorkflowError`s rather than throwing. Pure and
- * deterministic: the same document always compiles to the same plan.
- */
-import { compareCodePoints } from "../../core/common.js";
-import { formatReference, parseReference } from "../program/expressions.js";
-import { projectExecCore } from "../program/schema.js";
-import { sourceStepInstructions, sourceStepProgramUnit, sourceStepRef } from "../source-ir/program.js";
-import { decodeWorkflowSourceIrV1, } from "../source-ir/schema.js";
-/**
- * Compile source IR into a frozen-plan-ready graph.
- * `title` is the run-level display title (the asset's canonical name — the
- * format carries no authored title). Assumes the document came out of
- * `parseWorkflow` ok (structure already valid).
- */
-export function compileWorkflowPlan(input, title, resolvedUnits = new Map()) {
-    const sourceIr = decodeWorkflowSourceIrV1(input);
-    const errors = [];
-    // The decoder guarantees exactly one job (P4 §3.3, docs/plans/specs/
-    // p4-deletions-closeout.md, row B-43) — a 2+-job document is rejected at
-    // the adapter boundary and never reaches this compiler.
-    const sourceSteps = sourceIr.jobs[0]?.steps ?? [];
-    const allStepIds = new Set(sourceSteps.map((step) => step.id));
-    const earlierStepIds = new Set();
-    const steps = [];
-    sourceSteps.forEach((step, sequenceIndex) => {
-        const check = { allStepIds, earlierStepIds, errors };
-        if (step.map) {
-            checkReferenceField(step.map.over, { ...check, line: step.source.start, label: `Step "${step.id}" map.over` });
-        }
-        if (step.route) {
-            checkReferenceField(step.route.input, {
-                ...check,
-                line: step.source.start,
-                label: `Step "${step.id}" route.input`,
-            });
-        }
-        for (const [index, reference] of (step.inputs ?? []).entries()) {
-            checkInputReference(reference, index, {
-                ...check,
-                line: step.source.start,
-                label: `Step "${step.id}" inputs`,
-            });
-        }
-        steps.push(compileStep(step, sequenceIndex, sourceIr.defaults, resolvedUnits.get(step.id)));
-        earlierStepIds.add(step.id);
-    });
-    // P3b (spec §4.2, rows B-06/B-07): `outputs:` references are validated
-    // against the FULL step id set (never `earlierStepIds` — resolution happens
-    // at RUN COMPLETION, after every step has run, so an output may legitimately
-    // name any declared step regardless of its position).
-    for (const [name, declaration] of Object.entries(sourceIr.outputs ?? {})) {
-        checkOutputReference(name, declaration.from, { errors, allStepIds, line: sourceIr.source.start });
-    }
-    if (errors.length > 0)
-        return { ok: false, errors };
-    const paramNames = sourceIr.params ? Object.keys(sourceIr.params) : [];
-    return {
-        ok: true,
-        warnings: collectWorkflowWarnings(sourceIr),
-        plan: {
-            title,
-            ...(paramNames.length > 0 ? { params: paramNames } : {}),
-            ...(sourceIr.params && paramNames.length > 0
-                ? { paramSchemas: sourceIr.params }
-                : {}),
-            ...(sourceIr.outputs ? { outputs: sortedOutputs(sourceIr.outputs) } : {}),
-            ...(sourceIr.budget
-                ? {
-                    budget: {
-                        ...(sourceIr.budget.maxTokens !== undefined ? { maxTokens: sourceIr.budget.maxTokens } : {}),
-                        ...(sourceIr.budget.maxUnits !== undefined ? { maxUnits: sourceIr.budget.maxUnits } : {}),
-                    },
-                }
-                : {}),
-            steps,
-        },
-    };
-}
-/**
- * Re-key `outputs:` into canonical wire order (code-point-ascending by name)
- * — the order {@link decodeWorkflowOutputs} in `ir/schema-v4.ts` requires,
- * mirroring how `freeze/task-bindings.ts`'s `finalizeBindings` sorts
- * `inputBindings` before freezing. The source parser preserves AUTHOR order
- * (P3b spec §4.2 places no ordering requirement on authoring), so this is the
- * one place that must impose it.
- */
-function sortedOutputs(outputs) {
-    const sorted = {};
-    for (const name of Object.keys(outputs).sort(compareCodePoints)) {
-        sorted[name] = outputs[name];
-    }
-    return sorted;
-}
-function compileStep(step, sequenceIndex, defaults, resolved) {
-    const gate = {
-        kind: "gate",
-        id: `${step.id}.gate`,
-        stepId: step.id,
-        // The body `### gate` rubric is carried through as the ONE criterion string
-        // — the judge receives the whole section byte-exact (spec §2.4). A step
-        // with no rubric needs no verification (criteria: []).
-        criteria: step.gate?.rubric?.trim() ? [step.gate.rubric] : [],
-        ...(step.gate?.maxLoops !== undefined ? { maxLoops: step.gate.maxLoops } : {}),
-    };
-    let root;
-    if (step.route === undefined) {
-        const unit = resolved?.unit ?? sourceStepProgramUnit(step);
-        const instructionsText = resolved?.instructions ?? sourceStepInstructions(step);
-        if (step.map) {
-            root = {
-                kind: "map",
-                id: `${step.id}.map`,
-                over: step.map.over,
-                template: compileUnit(unit, `${step.id}.unit`, instructionsText, defaults, step.inputs, sourceStepRef(step)),
-                ...(step.map.concurrency !== undefined ? { concurrency: step.map.concurrency } : {}),
-                reducer: step.map.reducer ?? "collect",
-                source: step.source,
-            };
-        }
-        else {
-            root = compileUnit(unit, step.id, instructionsText, defaults, step.inputs, sourceStepRef(step));
-        }
-    }
-    return {
-        stepId: step.id,
-        title: step.id,
-        sequenceIndex,
-        ...(root ? { root } : {}),
-        ...(step.route
-            ? {
-                route: {
-                    input: step.route.input,
-                    when: Object.fromEntries(step.route.branches.map((b) => [b.match, b.stepId])),
-                    ...(step.route.defaultStepId !== undefined ? { defaultStepId: step.route.defaultStepId } : {}),
-                },
-            }
-            : {}),
-        ...(step.output !== undefined ? { outputSchema: step.output } : {}),
-        gate,
-    };
-}
-/**
- * Lower one source unit into the unresolved structural plan. Instructions are
- * ALWAYS the step's body prose, byte-exact — never templated, never scanned
- * for reference syntax. Engine/model/timeout settings remain on the parsed
- * override bag until the single freeze boundary.
- */
-function compileUnit(unit, id, instructions, defaults, inputs, source) {
-    return {
-        kind: "unit",
-        id,
-        instructions,
-        ...(inputs && inputs.length > 0 ? { inputs: [...inputs] } : {}),
-        // Shared projection: named pass-through scope is carried conditionally;
-        // whole-process environment inheritance is not an authoring surface.
-        ...(unit.exec ? { exec: projectExecCore(unit.exec) } : {}),
-        ...(unit.output !== undefined ? { schema: unit.output } : {}),
-        ...(unit.retry ? { retry: { max: unit.retry.max, on: [...unit.retry.on] } } : {}),
-        onError: unit.onError ?? defaults?.onError ?? "fail",
-        ...(unit.env ? { env: [...unit.env] } : {}),
-        ...(unit.isolation !== undefined ? { isolation: unit.isolation } : {}),
-        ...(source ? { source } : {}),
-    };
-}
-/** Validate a whole-value reference field (`map.over`, `route.input`). */
-function checkReferenceField(text, check) {
-    const parsed = parseReference(text);
-    if (!parsed.ok) {
-        check.errors.push({ line: check.line, message: `${check.label}: ${parsed.message}` });
-        return;
-    }
-    if (parsed.expr.kind === "stepOutput" && !check.earlierStepIds.has(parsed.expr.stepId)) {
-        const why = check.allStepIds.has(parsed.expr.stepId)
-            ? `step "${parsed.expr.stepId}" does not come before this step — references must name an earlier step (a producer that has already run)`
-            : `"${parsed.expr.stepId}" is not a step in this workflow`;
-        check.errors.push({
-            line: check.line,
-            message: `${check.label}: "${formatReference(parsed.expr)}" cannot be resolved — ${why}.`,
-        });
-    }
-}
-/** Validate one `inputs[]` entry: must be a step-output reference to an earlier step. */
-function checkInputReference(text, index, check) {
-    const parsed = parseReference(text);
-    if (!parsed.ok) {
-        check.errors.push({ line: check.line, message: `${check.label}[${index}]: ${parsed.message}` });
-        return;
-    }
-    if (parsed.expr.kind === "param") {
-        check.errors.push({
-            line: check.line,
-            message: `${check.label}[${index}]: "${formatReference(parsed.expr)}" names a param, not a step output — ` +
-                `params are already attached to every unit, so declaring one as an input is redundant. "inputs:" only ` +
-                `names step outputs (steps.<id>.output...).`,
-        });
-        return;
-    }
-    if (!check.earlierStepIds.has(parsed.expr.stepId)) {
-        const why = check.allStepIds.has(parsed.expr.stepId)
-            ? `step "${parsed.expr.stepId}" does not come before this step — references must name an earlier step (a producer that has already run)`
-            : `"${parsed.expr.stepId}" is not a step in this workflow`;
-        check.errors.push({
-            line: check.line,
-            message: `${check.label}[${index}]: "${formatReference(parsed.expr)}" cannot be resolved — ${why}.`,
-        });
-    }
-}
-/**
- * Validate one `outputs.<name>.from` reference (P3b, spec §4.2, rows
- * B-06/B-07): it must parse, it must name a STEP output — never a param (an
- * output projects a step artifact; a param is already on the run row) — and
- * that step must be DECLARED somewhere in the document. Unlike
- * {@link checkInputReference}, the named step need not be EARLIER: an output
- * resolves at run completion, after every step has already run.
- */
-function checkOutputReference(name, text, check) {
-    const parsed = parseReference(text);
-    if (!parsed.ok) {
-        check.errors.push({ line: check.line, message: `Output "${name}" from: ${parsed.message}` });
-        return;
-    }
-    if (parsed.expr.kind === "param") {
-        check.errors.push({
-            line: check.line,
-            message: `Output "${name}" from: "${formatReference(parsed.expr)}" names a param, not a step output — an output ` +
-                `projects a STEP artifact, never a param. "outputs:" only names step outputs (steps.<id>.output...).`,
-        });
-        return;
-    }
-    if (!check.allStepIds.has(parsed.expr.stepId)) {
-        check.errors.push({
-            line: check.line,
-            message: `Output "${name}" from: "${formatReference(parsed.expr)}" cannot be resolved — "${parsed.expr.stepId}" is ` +
-                `not a step in this workflow.`,
-        });
-    }
-}
-// ── Non-fatal warnings ───────────────────────────────────────────────────────
-/**
- * Collect the document's non-fatal WARNINGS — advisories that never fail
- * compilation, never change the frozen plan or its hash, and are surfaced as
- * `workflow-warning` entries in `akm lint`'s separate `warnings` channel
- * (human + JSON output, via `core/adapter/adapters/akm-lint.ts#
- * workflowCompileWarnings`) and as `warn()` lines at `workflow run`.
- *
- *   A. A `params.<name>` reference (in `map.over`/`route.input`) to an
- *      UNDECLARED param, but ONLY when the document declares a `params:`
- *      block — a likely typo. Prose can no longer carry param references at
- *      all (it is never scanned), so this warning's surface shrinks to the
- *      two whole-value fields that can legally contain one.
- *   B. `gate.max_loops` above 1 on an `exec` step. The engine judges such a
- *      step but never loops it (`exec/step-work.ts#effectiveGateMaxLoops`):
- *      a frozen argv cannot read the judge's feedback, so a second loop would
- *      only re-run the identical command — and its side effects. The declared
- *      budget is not silently different from what runs; say so.
- */
-export function collectWorkflowWarnings(input) {
-    const sourceIr = decodeWorkflowSourceIrV1(input);
-    const warnings = [];
-    const declaredParams = sourceIr.params ? new Set(Object.keys(sourceIr.params)) : undefined;
-    for (const job of sourceIr.jobs) {
-        for (const step of job.steps) {
-            const maxLoops = step.gate?.maxLoops ?? 1;
-            const execUnit = step.exec ?? step.run;
-            if (maxLoops > 1 && execUnit && step.gate?.rubric?.trim()) {
-                warnings.push({
-                    line: step.source.start,
-                    message: `Step "${step.id}" declares \`gate.max_loops: ${maxLoops}\` on an \`exec\` step — it runs its command ` +
-                        `ONCE. A gate loop re-executes the step so it can address the judge's feedback, and a frozen argv cannot ` +
-                        `read that feedback; looping would only repeat the command's side effects. The gate still evaluates and ` +
-                        `can still fail the step.`,
-                });
-            }
-            if (declaredParams) {
-                const declaredList = [...declaredParams].join(", ");
-                const scan = (text, label) => {
-                    if (!text)
-                        return;
-                    const parsed = parseReference(text);
-                    if (!parsed.ok || parsed.expr.kind !== "param" || declaredParams.has(parsed.expr.name))
-                        return;
-                    warnings.push({
-                        line: step.source.start,
-                        message: `${label}: "${formatReference(parsed.expr)}" references a param not declared in \`params:\` ` +
-                            `(declared: ${declaredList || "none"}) — likely a typo. An undeclared param supplied at start still ` +
-                            `resolves at run time.`,
-                    });
-                };
-                if (step.map)
-                    scan(step.map.over, `Step "${step.id}" map.over`);
-                if (step.route)
-                    scan(step.route.input, `Step "${step.id}" route.input`);
-            }
-        }
-    }
-    return warnings;
-}