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

package/dist/workflows/exec/unit-writer.js

@@ -0,0 +1,23 @@
+// 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/.
+/**
+ * Serialized writer queue for `workflow_run_units` (orchestration plan,
+ * *Persistence changes*).
+ *
+ * `withWorkflowRunsRepo` opens a fresh SQLite connection per call, so N
+ * parallel units completing at once would contend on SQLite's single writer
+ * and burn the 30 s busy_timeout. Bun is single-threaded, so a promise-chained
+ * in-process queue is sufficient: every unit write is appended to one chain
+ * and executes strictly in enqueue order. Reads and gate evaluation stay OFF
+ * this queue — only writes serialize.
+ *
+ * A failed write rejects its own caller but never wedges the chain.
+ */
+let tail = Promise.resolve();
+export function enqueueUnitWrite(fn) {
+    const run = tail.then(() => fn());
+    // Keep the chain alive regardless of individual outcomes.
+    tail = run.then(() => undefined, () => undefined);
+    return run;
+}

package/dist/workflows/exec/workflow-engine-gate.js

@@ -0,0 +1,67 @@
+// 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 `akm workflow` engine gate (`experimental.workflowEngine`, Q-05).
+ *
+ * Mirrors the shape of `src/commands/improve/autonomy-gate.ts` (D8) for a
+ * different failure mode. `akm improve`'s gated lanes have a safe downgrade —
+ * skip the lane, keep the rest of the run going — but a workflow step either
+ * executes or it does not: there is no partial-execution fallback to degrade
+ * into. So this gate REFUSES outright rather than silently skipping: an
+ * ungated call throws a classified `ConfigError` naming the exact config key,
+ * which the CLI's JSON error envelope (`emitJsonError`, `src/cli/shared.ts`)
+ * always routes to stderr with a non-zero exit — in every `--format`, not
+ * just `json` — so the refusal is visible and never a silent no-op. (A
+ * second, plain-text `warn()` call alongside the throw was deliberately
+ * rejected: it would interleave non-JSON text with the JSON error envelope on
+ * the SAME stream, corrupting stderr for any `--json` caller — a real defect,
+ * not just a test inconvenience.)
+ *
+ * Gated surfaces:
+ *  - `akm workflow run`    — the native step-execution engine
+ *  - `akm workflow brief`  — the harness-neutral driver protocol (read half)
+ *  - `akm workflow report` — the harness-neutral driver protocol (write half)
+ *
+ * Deliberately NOT gated: authoring/linting the unified markdown format and
+ * the manual workflow CLI contract (`start`, `next`, `complete`, `status`,
+ * `list`, `create`, `resume`, `abandon`) remain stable per STABILITY.md.
+ */
+import { ConfigError } from "../../core/errors.js";
+/**
+ * The config key an operator sets to enable the workflow engine.
+ *
+ * Named rather than inlined because it is user-facing text: it goes into the
+ * thrown error's message and `akm task doctor`, and those must name the same
+ * key as the schema.
+ */
+export const WORKFLOW_ENGINE_CONFIG_KEY = "experimental.workflowEngine";
+/**
+ * True only when the user has explicitly opted into the workflow engine.
+ * Absent, an absent `experimental` section, and an explicit `false` all read
+ * as off — the engine is never enabled by inference.
+ */
+export function isWorkflowEngineEnabled(config) {
+    return config?.experimental?.workflowEngine === true;
+}
+/** The message shown to the user AND matched by tests naming the config key. */
+export function workflowEngineGateMessage(surface) {
+    return (`\`akm workflow ${surface}\` is EXPERIMENTAL and refuses to run until ` +
+        `\`${WORKFLOW_ENGINE_CONFIG_KEY}\` is set. Run \`akm config set ${WORKFLOW_ENGINE_CONFIG_KEY} true\` to enable it.`);
+}
+/**
+ * Refuse a gated workflow-engine surface unless the opt-in is set.
+ *
+ * `surface` is the human name of the subcommand/action being refused (e.g.
+ * `"run"`, `"brief"`, `"create <name>.yaml"`) — it is folded into the thrown
+ * error's message so the refusal names both the surface and the exact config
+ * key that would enable it. The throw alone is the whole mechanism: every
+ * command defined with `defineJsonCommand` routes an uncaught throw through
+ * `runWithJsonErrors`/`emitJsonError`, which prints the error to stderr and
+ * exits non-zero regardless of `--format` — so this is never a silent no-op.
+ */
+export function requireWorkflowEngineEnabled(config, surface) {
+    if (isWorkflowEngineEnabled(config))
+        return;
+    throw new ConfigError(workflowEngineGateMessage(surface), "WORKFLOW_ENGINE_NOT_ENABLED");
+}

package/dist/workflows/exec/worktree.js

@@ -0,0 +1,171 @@
+// 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/.
+/**
+ * Git worktree lifecycle for `isolation: worktree` units (redesign addendum,
+ * R2). Parallel file-mutating units on the agent/sdk runners each get a
+ * fresh DETACHED worktree of the run's base repository under a run-scoped
+ * tmp directory, so concurrent units can never trample each other's working
+ * tree. Lifecycle (driven by the native executor per journaled attempt):
+ *
+ *   1. {@link assertGitWorkTree} — preflight, once per step: a non-git base
+ *      directory fails the step cleanly before anything dispatches.
+ *   2. {@link createUnitWorktree} — `git worktree add --detach` into
+ *      `<tmp>/akm-worktrees/<runId>/<attemptId>`; the path is journaled on
+ *      the unit row (`workflow_run_units.worktree_path`, migration 004) and
+ *      passed to dispatch as the unit's cwd.
+ *   3. {@link cleanupUnitWorktree} — after the unit finishes:
+ *      `git status --porcelain` CLEAN → the worktree is removed;
+ *      DIRTY → it is RETAINED (the caller logs the path) so uncollected work
+ *      is never destroyed.
+ *
+ * What "uncollected work" means (the honest contract): the clean probe is
+ * `git status --porcelain` WITHOUT `--ignored`, so it counts tracked-file
+ * modifications and untracked *unignored* files, but NOT files the base repo's
+ * own `.gitignore` matches (build outputs, caches, logs, dependency dirs such
+ * as `node_modules`/`dist`). Those ignored files are DISPOSABLE BY DEFINITION
+ * — the repository already declares them regenerable — so a worktree whose only
+ * residue is ignored files probes clean and IS removed. This is deliberate:
+ * adding `--ignored` would retain a worktree after essentially every unit that
+ * ran a package install or a build (the ignored `node_modules`/`dist` tree),
+ * blowing up disk under the run-scoped tmp root. Work a unit needs preserved
+ * must therefore be tracked or untracked-unignored; anything the workflow
+ * repo has chosen to `.gitignore` is treated as throwaway.
+ *
+ * All git invocations are `spawnSync` (the repo-wide pattern for git
+ * shell-outs) with explicit timeouts; this module never throws — every
+ * operation returns a result object so the executor maps failures onto its
+ * own step/unit failure vocabulary.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const GIT_TIMEOUT_MS = 30_000;
+/** Run one git command; `ok` = exit 0. Never throws (spawn errors → ok: false). */
+function git(cwd, args) {
+    const result = spawnSync("git", ["-C", cwd, ...args], { encoding: "utf8", timeout: GIT_TIMEOUT_MS });
+    if (result.error) {
+        return { ok: false, stdout: "", error: `git ${args[0]} failed to spawn: ${result.error.message}` };
+    }
+    if (result.status !== 0) {
+        const detail = (result.stderr || result.stdout || "").trim();
+        return {
+            ok: false,
+            stdout: result.stdout ?? "",
+            error: `git ${args.join(" ")} exited ${result.status}${detail ? `: ${detail}` : ""}`,
+        };
+    }
+    return { ok: true, stdout: result.stdout ?? "" };
+}
+/** True when a usable `git` binary is on PATH (tests skip gracefully without one). */
+export function isGitAvailable() {
+    const result = spawnSync("git", ["--version"], { encoding: "utf8", timeout: 5_000 });
+    return !result.error && result.status === 0;
+}
+/**
+ * Preflight for worktree isolation: `dir` must be inside a git work tree.
+ * Returns an error message (for a clean step failure) or undefined when ok.
+ * A missing git binary reports as the same clean failure — a workflow that
+ * declares isolation cannot run without git.
+ */
+export function assertGitWorkTree(dir) {
+    const result = git(dir, ["rev-parse", "--is-inside-work-tree"]);
+    if (!result.ok) {
+        return `"${dir}" is not a git repository (isolation: worktree requires one): ${result.error}`;
+    }
+    if (result.stdout.trim() !== "true") {
+        return `"${dir}" is not inside a git work tree (isolation: worktree requires one).`;
+    }
+    return undefined;
+}
+/** Journal-safe directory name for a unit attempt id (ids carry `:` / `~`). */
+function sanitizeAttemptId(attemptId) {
+    return attemptId.replace(/[^A-Za-z0-9._-]/g, "-");
+}
+/** Run-scoped parent directory for all of one run's unit worktrees. */
+export function runWorktreeRoot(runId) {
+    return path.join(os.tmpdir(), "akm-worktrees", runId);
+}
+/**
+ * Move a leftover attempt directory aside to `<dest>.retained-<ts>[-n]`
+ * (never overwriting an earlier retained copy). Throws on fs errors — the
+ * caller maps them onto its result object.
+ */
+function moveLeftoverAside(dest) {
+    const base = `${dest}.retained-${Date.now()}`;
+    let aside = base;
+    for (let n = 1; fs.existsSync(aside); n++)
+        aside = `${base}-${n}`;
+    fs.renameSync(dest, aside);
+    return aside;
+}
+/**
+ * Create a fresh DETACHED worktree of `baseDir`'s repository at
+ * `<tmp>/akm-worktrees/<runId>/<attemptId>` (detached HEAD — no branch is
+ * minted, so parallel units cannot collide on branch names).
+ *
+ * A leftover directory at the attempt path (a RETAINED dirty worktree from a
+ * prior invocation, or a crashed attempt's partial state) is handled with the
+ * same never-destroy-unverified-work rule as {@link cleanupUnitWorktree}:
+ * `git status --porcelain` CLEAN → removed; DIRTY or unverifiable (the probe
+ * fails — e.g. a half-created directory that is no longer a valid worktree)
+ * → moved aside to `<dest>.retained-<ts>` and reported via
+ * `preservedLeftover` so the caller can log where the work went. Either way
+ * `git worktree prune` clears the stale registration before re-creating.
+ */
+export function createUnitWorktree(baseDir, runId, attemptId) {
+    const dest = path.join(runWorktreeRoot(runId), sanitizeAttemptId(attemptId));
+    let preservedLeftover;
+    try {
+        if (fs.existsSync(dest)) {
+            const status = git(dest, ["status", "--porcelain"]);
+            if (status.ok && status.stdout.trim() === "") {
+                fs.rmSync(dest, { recursive: true, force: true });
+            }
+            else {
+                preservedLeftover = moveLeftoverAside(dest);
+            }
+            git(baseDir, ["worktree", "prune"]);
+        }
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+    }
+    catch (err) {
+        return { ok: false, error: `could not prepare worktree directory ${dest}: ${message(err)}` };
+    }
+    const added = git(baseDir, ["worktree", "add", "--detach", dest]);
+    if (!added.ok) {
+        return { ok: false, error: `could not create isolation worktree at ${dest}: ${added.error}` };
+    }
+    return { ok: true, path: dest, ...(preservedLeftover !== undefined ? { preservedLeftover } : {}) };
+}
+/**
+ * Post-unit cleanup: remove the worktree when `git status --porcelain` shows
+ * it clean; retain it (dirty: true) when the unit left uncommitted work —
+ * the caller logs the retained path. Any git failure retains the worktree
+ * too (never destroy a tree whose state could not be verified).
+ *
+ * The probe deliberately omits `--ignored`: a worktree whose only residue is
+ * files matched by the base repo's `.gitignore` (build artifacts, caches,
+ * logs, `node_modules`) probes clean and IS removed. Those files are disposable
+ * by the repo's own declaration; retaining a worktree per build/install would
+ * blow up disk. "Uncollected work" the caller preserves is therefore
+ * tracked-or-untracked-unignored changes only (module doc).
+ */
+export function cleanupUnitWorktree(baseDir, worktreePath) {
+    const status = git(worktreePath, ["status", "--porcelain"]);
+    if (!status.ok) {
+        return { removed: false, dirty: false, error: status.error };
+    }
+    if (status.stdout.trim() !== "") {
+        return { removed: false, dirty: true };
+    }
+    const removed = git(baseDir, ["worktree", "remove", worktreePath]);
+    if (!removed.ok) {
+        return { removed: false, dirty: false, error: removed.error };
+    }
+    return { removed: true, dirty: false };
+}
+function message(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/workflows/ir/compile.js

@@ -0,0 +1,246 @@
+// 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 a parsed unified
+ * `WorkflowDocument` (`../parser.ts`) into the same `WorkflowPlanDraft` shape
+ * IR v3 has always consumed — the pre-unification split between a linear
+ * markdown compiler and a YAML-program compiler is gone. 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 { formatReference, parseReference } from "../program/expressions.js";
+/**
+ * Compile a parsed unified workflow document 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(document, title) {
+    const errors = [];
+    const allStepIds = new Set(document.steps.map((s) => s.id));
+    const earlierStepIds = new Set();
+    const steps = [];
+    document.steps.forEach((step) => {
+        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, defaultsOf(document)));
+        earlierStepIds.add(step.id);
+    });
+    if (errors.length > 0)
+        return { ok: false, errors };
+    const paramNames = document.params ? Object.keys(document.params) : [];
+    return {
+        ok: true,
+        warnings: collectWorkflowWarnings(document),
+        plan: {
+            title,
+            ...(paramNames.length > 0 ? { params: paramNames } : {}),
+            ...(document.params && paramNames.length > 0 ? { paramSchemas: document.params } : {}),
+            ...(document.budget
+                ? {
+                    budget: {
+                        ...(document.budget.maxTokens !== undefined ? { maxTokens: document.budget.maxTokens } : {}),
+                        ...(document.budget.maxUnits !== undefined ? { maxUnits: document.budget.maxUnits } : {}),
+                    },
+                }
+                : {}),
+            steps,
+        },
+    };
+}
+function defaultsOf(document) {
+    return document.defaults;
+}
+function compileStep(step, defaults) {
+    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 has no gate at all (fail-open, criteria: []).
+        criteria: step.gateRubric?.text.trim() ? [step.gateRubric.text] : [],
+        ...(step.gate?.maxLoops !== undefined ? { maxLoops: step.gate.maxLoops } : {}),
+    };
+    let root;
+    if (step.route === undefined) {
+        const instructionsText = step.instructions?.text ?? "";
+        if (step.map) {
+            root = {
+                kind: "map",
+                id: `${step.id}.map`,
+                over: step.map.over,
+                template: compileUnit(step.map.unit, `${step.id}.unit`, instructionsText, defaults, step.inputs, step.source),
+                ...(step.map.concurrency !== undefined ? { concurrency: step.map.concurrency } : {}),
+                reducer: step.map.reducer ?? "collect",
+                source: step.source,
+            };
+        }
+        else {
+            root = compileUnit(step.unit, step.id, instructionsText, defaults, step.inputs, step.instructions?.source);
+        }
+    }
+    return {
+        stepId: step.id,
+        title: step.id,
+        sequenceIndex: step.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,
+        templating: "verbatim",
+        ...(inputs && inputs.length > 0 ? { inputs: [...inputs] } : {}),
+        ...(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}.`,
+        });
+    }
+}
+// ── 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 by
+ * `workflow validate` (human + JSON) and as `warn()` lines at `workflow start`.
+ *
+ *   A. A unit/map step with NO step-level `output:` schema carries its units'
+ *      raw results as an untyped artifact — permitted, but worth flagging.
+ *   B. 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.
+ */
+export function collectWorkflowWarnings(document) {
+    const warnings = [];
+    const declaredParams = document.params ? new Set(Object.keys(document.params)) : undefined;
+    for (const step of document.steps) {
+        if ((step.map || step.route === undefined) && step.output === undefined) {
+            warnings.push({
+                line: step.source.start,
+                message: `Step "${step.id}" declares no \`output:\` schema — its unit results are carried as an untyped ` +
+                    `artifact (permitted). Add an \`output:\` JSON Schema to type and validate the step artifact.`,
+            });
+        }
+        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;
+}