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

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/watch.js

@@ -0,0 +1,116 @@
+// 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/.
+/**
+ * `akm workflow watch <run>` — run-scoped event tail (redesign addendum R2).
+ *
+ * Prints the run's `workflow_*` / `workflow_unit_*` events from the state.db
+ * `events` table (matched on `metadata.runId`) as NDJSON — one
+ * {@link EventEnvelope} per line — and exits. With `stream: true` it keeps
+ * polling from the last seen event id (monotonic rowid cursor, so concurrent
+ * writers can never cause skips) and exits when the run reaches a terminal
+ * status.
+ *
+ * Design constraints (pinned R2 decisions):
+ *   - FOREGROUND poll loop only — no daemon, no background process, no
+ *     `tailEvents` subscription held past the terminal status.
+ *   - Reads go through the existing events repository (via
+ *     {@link readEvents}); this module issues no SQL of its own.
+ *   - "Terminal" means any non-`active` run status (`completed`, `failed`,
+ *     `blocked`): in all three the engine has stopped driving, so no further
+ *     events arrive until a human resumes the run. The status is read BEFORE
+ *     each drain, so events written before the status flip are always
+ *     emitted before the loop exits. The engine commits the status flip
+ *     (workflow.db transaction) BEFORE it appends the terminal
+ *     `workflow_step_completed` / `workflow_finished` events to state.db, so
+ *     after first observing a terminal status the loop keeps performing
+ *     grace polls (sleep + drain) until one drains nothing new — the
+ *     terminal events landing in that commit→append window are never
+ *     dropped.
+ *   - Event lines are the raw envelopes (ids/status metadata only — event
+ *     emitters never journal workflow-authored content, 07 P1-B rule).
+ */
+import { NotFoundError } from "../../core/errors.js";
+import { readEvents } from "../../core/events.js";
+import { withWorkflowRunsRepo } from "../../storage/repositories/workflow-runs-repository.js";
+/** Default `--stream` poll interval (ms). */
+export const DEFAULT_WATCH_INTERVAL_MS = 1000;
+/**
+ * True when `event` belongs to workflow run `runId`: the event type is in the
+ * `workflow_*` family (which includes `workflow_unit_*`) AND the metadata
+ * carries a matching `runId`. Events of other families that happen to carry
+ * a `runId` (e.g. `llm_usage`) are excluded by design.
+ */
+export function isWorkflowRunEvent(event, runId) {
+    if (!event.eventType.startsWith("workflow_"))
+        return false;
+    return event.metadata?.runId === runId;
+}
+/** Default status reader — repository lookup; a missing run is a structured not-found. */
+async function readRunStatus(runId) {
+    return withWorkflowRunsRepo((repo) => {
+        const row = repo.getRunById(runId);
+        if (!row) {
+            throw new NotFoundError(`Workflow run "${runId}" not found.`, "WORKFLOW_NOT_FOUND", "Run `akm workflow list --active` to see runs.");
+        }
+        return row.status;
+    });
+}
+/**
+ * Watch one workflow run's events. Emits each matching event envelope as a
+ * single NDJSON line via `emit`, then returns a summary. See the module doc
+ * for the backlog/stream/terminal-status contract.
+ */
+export async function watchWorkflowRun(options) {
+    const intervalMs = options.intervalMs ?? DEFAULT_WATCH_INTERVAL_MS;
+    const emit = options.emit ?? ((line) => process.stdout.write(`${line}\n`));
+    const read = options.readEventsFn ?? ((readOptions) => readEvents(readOptions));
+    const getRunStatus = options.getRunStatus ?? readRunStatus;
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    // Existence check first so an unknown run id is a structured error, not an
+    // empty NDJSON stream.
+    let status = await getRunStatus(options.runId);
+    let eventCount = 0;
+    let cursor = 0;
+    const drain = () => {
+        const { events, nextOffset } = read({ sinceOffset: cursor });
+        cursor = nextOffset;
+        for (const event of events) {
+            if (!isWorkflowRunEvent(event, options.runId))
+                continue;
+            emit(JSON.stringify(event));
+            eventCount++;
+        }
+    };
+    // Backlog: everything already journaled for this run.
+    drain();
+    if (options.stream === true) {
+        // Foreground poll loop (NO daemon). Status is re-read BEFORE each drain
+        // so events written before a terminal flip are emitted before exit.
+        while (status === "active") {
+            await sleep(intervalMs);
+            status = await getRunStatus(options.runId);
+            drain();
+        }
+        // Terminal grace polls: completeWorkflowStep commits the run-status flip
+        // (workflow.db) BEFORE appending workflow_step_completed /
+        // workflow_finished to state.db, so the drain that first observed the
+        // terminal status can predate those events. Keep sleeping + draining
+        // until an idle poll (a drain that emits nothing new for this run) —
+        // the engine has stopped driving, so this converges after the terminal
+        // events land (already-terminal runs pay exactly one idle poll).
+        let emittedBefore;
+        do {
+            emittedBefore = eventCount;
+            await sleep(intervalMs);
+            drain();
+        } while (eventCount > emittedBefore);
+    }
+    return {
+        runId: options.runId,
+        status,
+        eventCount,
+        lastEventId: cursor,
+        streamed: options.stream === true,
+    };
+}

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);
+}