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

package/dist/core/subprocess.js

@@ -0,0 +1,303 @@
+// 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/.
+/**
+ * Managed-subprocess primitive.
+ *
+ * The battle-tested spawn/timeout/abort/capture core, extracted from the agent
+ * CLI spawn wrapper so non-agent subprocess callers (task commands, setup
+ * probes/installers) get the same guarantees the agent path already had:
+ *
+ *   • Process-GROUP spawn (`detached: true` when capturing) so a negative-pid
+ *     kill reaps the whole descendant tree — no orphaned children.
+ *   • A SIGTERM→SIGKILL kill ladder on timeout/abort — a child that ignores
+ *     SIGTERM is force-killed after a grace period instead of wedging forever.
+ *   • Bounded output capture ({@link readStream}) that cannot block past the
+ *     wall budget even when the child leaves a pipe endpoint open.
+ *   • Injectable `spawnFn`/`setTimeoutFn`/`clearTimeoutFn` seams so callers
+ *     can drive the machinery deterministically in tests.
+ *
+ * Runtime boundary: the default spawn comes from `../runtime`; this module
+ * never touches `Bun.*` directly. It also never imports from `integrations/`
+ * or `tasks/` — it is a leaf primitive those layers consume.
+ */
+import { spawn as runtimeSpawn } from "../runtime.js";
+/**
+ * Kill the process group of `proc` with `signal`, falling back to
+ * `proc.kill(signal)` when `proc.pid` is unavailable (e.g. test fakes).
+ *
+ * Passing a negative PID to `process.kill` targets the entire process
+ * group, so opencode's child processes (the .opencode binary, etc.) are
+ * reaped alongside the node wrapper. The fallback keeps test fakes working
+ * without modification.
+ */
+export function killGroup(proc, signal) {
+    if (typeof proc.pid === "number") {
+        try {
+            process.kill(-proc.pid, signal);
+            return;
+        }
+        catch {
+            // Process may have already exited; fall through to direct kill.
+        }
+    }
+    try {
+        proc.kill(signal);
+    }
+    catch {
+        /* ignore */
+    }
+}
+/**
+ * SIGTERM→SIGKILL kill ladder shared by the timeout and abort paths (§4.6
+ * dedup, H3). No-op when the child has already exited; otherwise runs
+ * `onKill` (the caller's reason flag — `timedOut` / `aborted` — set BEFORE
+ * the first signal, exactly as the inlined copies did), SIGTERMs the
+ * process group, and schedules a follow-up SIGKILL after `graceMs` in case
+ * the process ignores SIGTERM. The SIGKILL timer is unref'ed so it never
+ * pins the event loop.
+ */
+export function scheduleKillLadder(proc, opts) {
+    if (!proc || proc.exitCode !== null)
+        return;
+    opts.onKill();
+    killGroup(proc, "SIGTERM");
+    const sigkillTimer = opts.setTimeoutFn(() => {
+        if (!proc || proc.exitCode !== null)
+            return;
+        killGroup(proc, "SIGKILL");
+    }, opts.graceMs ?? 5000);
+    if (typeof sigkillTimer !== "number")
+        sigkillTimer.unref?.();
+}
+const STREAM_READ_TIMEOUT = Symbol("stream-read-timeout");
+/**
+ * Drain a readable stream to text, optionally racing each read against a
+ * timeout so a process that is killed via SIGTERM/SIGKILL but whose pipe
+ * endpoints stay open (e.g. background threads still holding the fd) cannot
+ * block the caller indefinitely. On timeout we return whatever was decoded
+ * before the pipe stopped draining.
+ */
+export async function readStream(stream, opts) {
+    if (!stream)
+        return { text: "", timedOut: false };
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let text = "";
+    if (!opts?.timeoutMs) {
+        try {
+            while (true) {
+                const chunk = await reader.read();
+                if (chunk.done)
+                    break;
+                text += decoder.decode(chunk.value, { stream: true });
+            }
+            text += decoder.decode();
+            return { text, timedOut: false };
+        }
+        catch (error) {
+            return { text, timedOut: false, error };
+        }
+        finally {
+            try {
+                reader.releaseLock();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    const setTimeoutImpl = opts.setTimeoutFn ?? setTimeout;
+    const clearTimeoutImpl = opts.clearTimeoutFn ?? clearTimeout;
+    let timer;
+    const timeoutPromise = new Promise((resolve) => {
+        timer = setTimeoutImpl(() => {
+            timer = undefined;
+            resolve(STREAM_READ_TIMEOUT);
+        }, opts.timeoutMs);
+        if (typeof timer !== "number")
+            timer.unref?.();
+    });
+    try {
+        while (true) {
+            const chunk = await Promise.race([reader.read(), timeoutPromise]);
+            if (chunk === STREAM_READ_TIMEOUT) {
+                void reader.cancel().catch(() => { });
+                return { text, timedOut: true };
+            }
+            if (chunk.done)
+                break;
+            text += decoder.decode(chunk.value, { stream: true });
+        }
+        text += decoder.decode();
+        return { text, timedOut: false };
+    }
+    catch (error) {
+        return { text, timedOut: false, error };
+    }
+    finally {
+        if (timer !== undefined) {
+            clearTimeoutImpl(timer);
+        }
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+const EMPTY_READ = { text: "", timedOut: false };
+function toError(err) {
+    return err instanceof Error ? err : new Error(String(err));
+}
+/**
+ * Spawn `cmd` and manage its lifecycle: process-group spawn, hard timeout and
+ * cooperative abort (both via the SIGTERM→SIGKILL {@link scheduleKillLadder}),
+ * bounded output capture, and an optional stdin payload. Never throws for a
+ * spawn/exit failure — those surface as {@link ManagedSubprocessResult.spawnError}.
+ */
+export async function runManagedSubprocess(cmd, opts) {
+    const setTimeoutImpl = opts.setTimeoutFn ?? setTimeout;
+    const clearTimeoutImpl = opts.clearTimeoutFn ?? clearTimeout;
+    const spawnFn = opts.spawnFn ?? runtimeSpawn;
+    const capture = opts.capture;
+    const timeoutMs = opts.timeoutMs;
+    // Refuse to spawn at all when the caller's signal is already aborted.
+    if (opts.signal?.aborted) {
+        return {
+            exitCode: null,
+            stdout: "",
+            stderr: "",
+            timedOut: false,
+            aborted: true,
+            stdoutRead: EMPTY_READ,
+            stderrRead: EMPTY_READ,
+        };
+    }
+    let proc;
+    try {
+        proc = spawnFn(cmd, {
+            stdin: capture ? (opts.stdin !== undefined ? "pipe" : "ignore") : "inherit",
+            stdout: capture ? "pipe" : "inherit",
+            stderr: capture ? "pipe" : "inherit",
+            ...(opts.env ? { env: opts.env } : {}),
+            ...(opts.cwd ? { cwd: opts.cwd } : {}),
+            // Spawn in its own process group so killGroup(-pid, signal) reaches all
+            // descendants. Only in captured mode — interactive mode inherits the
+            // parent terminal's process group intentionally.
+            ...(capture ? { detached: true } : {}),
+        });
+    }
+    catch (err) {
+        return {
+            exitCode: null,
+            stdout: "",
+            stderr: "",
+            timedOut: false,
+            aborted: false,
+            spawnError: toError(err),
+            stdoutRead: EMPTY_READ,
+            stderrRead: EMPTY_READ,
+        };
+    }
+    opts.onSpawn?.(proc);
+    // Hard timeout: SIGTERM now, SIGKILL after the grace period if ignored.
+    // Skipped entirely when timeoutMs is null.
+    let timedOut = false;
+    let timer;
+    if (timeoutMs !== null) {
+        timer = setTimeoutImpl(() => {
+            scheduleKillLadder(proc, {
+                onKill: () => {
+                    timedOut = true;
+                },
+                setTimeoutFn: setTimeoutImpl,
+                ...(opts.graceMs !== undefined ? { graceMs: opts.graceMs } : {}),
+            });
+        }, timeoutMs);
+    }
+    // Cooperative cancel: same ladder, flagged separately so the caller can tell
+    // a budget/user abort from a wall-clock expiry.
+    let aborted = false;
+    const abortSignal = opts.signal;
+    const onAbort = () => {
+        scheduleKillLadder(proc, {
+            onKill: () => {
+                aborted = true;
+            },
+            setTimeoutFn: setTimeoutImpl,
+            ...(opts.graceMs !== undefined ? { graceMs: opts.graceMs } : {}),
+        });
+    };
+    if (abortSignal) {
+        // A signal that aborted between the pre-spawn check and here fires the
+        // listener directly (the "abort" event would otherwise never re-dispatch).
+        if (abortSignal.aborted)
+            onAbort();
+        else
+            abortSignal.addEventListener("abort", onAbort, { once: true });
+    }
+    // Stream-drain timeout: the wall budget plus a 2 s grace, or 30 s when there
+    // is no kill timer. Ensures the caller never hangs past the budget even if a
+    // killed child leaves a pipe write-end open in a background thread.
+    const streamDrainTimeoutMs = timeoutMs !== null ? timeoutMs + 2_000 : 30_000;
+    const stdoutPromise = capture
+        ? readStream(proc.stdout ?? null, {
+            timeoutMs: streamDrainTimeoutMs,
+            setTimeoutFn: setTimeoutImpl,
+            clearTimeoutFn: clearTimeoutImpl,
+        })
+        : Promise.resolve(EMPTY_READ);
+    const stderrPromise = capture
+        ? readStream(proc.stderr ?? null, {
+            timeoutMs: streamDrainTimeoutMs,
+            setTimeoutFn: setTimeoutImpl,
+            clearTimeoutFn: clearTimeoutImpl,
+        })
+        : Promise.resolve(EMPTY_READ);
+    // Optional stdin payload (captured mode only). Race the write/close against
+    // proc.exited so a child that never drains stdin cannot pin us past the
+    // timeout.
+    if (opts.stdin !== undefined && capture && proc.stdin) {
+        const stdinPayload = opts.stdin;
+        const stdinStream = proc.stdin;
+        const stdinDone = (async () => {
+            try {
+                const writer = stdinStream.getWriter();
+                await writer.write(new TextEncoder().encode(stdinPayload));
+                await writer.close();
+            }
+            catch {
+                // Best-effort: ignore stdin write failures, the child will get EOF.
+            }
+        })();
+        await Promise.race([stdinDone, proc.exited.catch(() => undefined)]);
+    }
+    let exitCode = null;
+    try {
+        exitCode = await proc.exited;
+    }
+    catch (err) {
+        if (timer !== undefined)
+            clearTimeoutImpl(timer);
+        abortSignal?.removeEventListener("abort", onAbort);
+        // Drain readers so they don't surface as unhandled rejections. The streams
+        // carry their own drain timeout so this cannot block indefinitely.
+        await Promise.allSettled([stdoutPromise, stderrPromise]);
+        return {
+            exitCode: null,
+            stdout: "",
+            stderr: "",
+            timedOut: false,
+            aborted: false,
+            spawnError: toError(err),
+            stdoutRead: EMPTY_READ,
+            stderrRead: EMPTY_READ,
+        };
+    }
+    clearTimeoutImpl(timer);
+    abortSignal?.removeEventListener("abort", onAbort);
+    const [stdoutRead, stderrRead] = await Promise.all([stdoutPromise, stderrPromise]);
+    return { exitCode, stdout: stdoutRead.text, stderr: stderrRead.text, timedOut, aborted, stdoutRead, stderrRead };
+}

package/dist/core/text-truncation.js

@@ -9,9 +9,11 @@
  * implementations historically maintained overlapping-but-not-identical
  * vocabularies of hanging-connector words, which was a maintenance trap.
  *
- * This module is the single source of truth. `distill` continues to layer its
- * own section-heading regex on top (those patterns are distill-specific and
- * intentionally stay local to that module).
+ * This module is the single source of truth. A separate section-heading regex
+ * (`HEADING_FRAGMENT_PATTERNS` in
+ * `src/commands/proposal/validators/proposal-quality-validators.ts`) layers on
+ * top of these heuristics and is shared across distill, consolidate, and
+ * reflect rather than staying local to any one of them.
  */
 /**
  * Words that, when ending a sentence, suggest the description was truncated
@@ -87,8 +89,10 @@ export const TRUNCATION_TRAILING_WORDS = new Set([
  *   - Trailing ellipsis (`...` or `…`)
  *   - Last word matches {@link TRUNCATION_TRAILING_WORDS}
  *
- * Does NOT detect section-heading fragments — that check is distill-specific
- * and lives in `src/commands/distill.ts` (`HEADING_FRAGMENT_PATTERNS`).
+ * Does NOT detect section-heading fragments — that check lives in
+ * `HEADING_FRAGMENT_PATTERNS` in
+ * `src/commands/proposal/validators/proposal-quality-validators.ts`, shared by
+ * distill, consolidate, and reflect.
  */
 export function detectTruncatedDescription(description) {
     const trimmed = description.trim();

package/dist/core/time.js

@@ -98,6 +98,26 @@ export function parseSinceToIso(since) {
     }
     return parsed.toISOString();
 }
+/**
+ * LENIENT variant for config-driven since-values that may be a duration
+ * shorthand (e.g. `"30m"`, `"24h"`, `"7d"` per {@link DURATION_UNITS}):
+ * a matching duration resolves to the ISO timestamp of `now - duration`;
+ * anything else is returned UNCHANGED (assumed to already be an ISO
+ * timestamp) — this function never throws.
+ *
+ * Deliberately distinct from {@link parseSinceToIso}, which rejects
+ * unparseable input with a UsageError: the identity fallback here is
+ * behavior consumers rely on (consolidate's incremental narrowing compares
+ * the returned string lexicographically against file-mtime ISO strings, so
+ * garbage input silently selects nothing rather than failing the run —
+ * pinned by tests/commands/goldens-duration-flags.test.ts).
+ */
+export function parseSinceToIsoLenient(since) {
+    const ms = parseDuration(since, DURATION_UNITS);
+    if (ms === null)
+        return since;
+    return new Date(Date.now() - ms).toISOString();
+}
 /**
  * Convert an ISO-8601 timestamp string to the SQLite datetime format
  * `"YYYY-MM-DD HH:MM:SS"` used by `datetime('now')`.

package/dist/core/type-presentation.js

@@ -0,0 +1,130 @@
+// 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/.
+/**
+ * Chunk 1.5 (WI-1.5.1, D1.5-4) — the §2.3 "compile-time safety mitigation"
+ * table for AKM's own presentation metadata. EXTENDED by chunk-2 WI-C
+ * (`docs/architecture/specs/akm-0.9.0-bundle-adapter-spec.md` §2) to carry the per-`type`
+ * renderer NAME + action builder, so this table becomes the `TYPE_PRESENTATION`
+ * data table §2 mandates ("Renderer/action = data table keyed on the open
+ * `type`, pointing at a named-function core module").
+ *
+ * The open type token (chunk 1.5) trades the deleted closed asset-type
+ * union's exhaustiveness checking for a runtime lookup. `TYPE_PRESENTATION`
+ * restores that exhaustiveness for AKM's OWN known types (the compiler
+ * demands an entry whenever {@link KnownType} gains a member), while
+ * {@link presentationFor} stays open over `string` so foreign/adapter types
+ * still resolve to a sane generic fallback instead of `undefined`/a throw.
+ *
+ * ── renderer/action provenance (WI-C, §2) ──
+ *
+ * The `renderer` NAMES and `action` builders below are the SINGLE SOURCE OF
+ * TRUTH for search-hit rendering — chunk-3 folded the old mutable renderer/
+ * action registry singleton into this static table (reached via
+ * {@link defaultRendererRegistry}). They cover all built-in types — INCLUDING
+ * the 15th type `instruction` (a read-like-knowledge markdown doc added for the
+ * format-family adapters) and the 6 "static-only" mappings
+ * (script/skill/command/agent/knowledge/memory) — §6 "6 renderer mappings".
+ * The workflow action is the one function-valued builder; its
+ * `buildWorkflowAction` body (`output/renderers.ts` — a cycle-sensitive module)
+ * is reproduced inline here rather than imported, to keep this leaf import-free
+ * (only `recognition-util`, D1-5's pure sink); `tests/core/adapter/
+ * akm-presentation.test.ts` pins the renderer/action values against drift.
+ */
+import { isKnownType } from "./recognition-util.js";
+/** POSIX-shell single-quote a value — inlined from `output/renderers.ts#shellQuote` (cycle-sensitive; see file header). */
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** Reproduced from `output/renderers.ts#buildWorkflowAction` — the one function-valued `ACTION_BUILDERS.workflow` entry. */
+function buildWorkflowAction(ref) {
+    return `Resume the active run or start a new run with \`akm workflow next ${shellQuote(ref)}\`.`;
+}
+/**
+ * Exhaustive over {@link KnownType} — a HAND-WRITTEN literal, not derived
+ * from `KNOWN_TYPES` programmatically, so the compiler rejects this object
+ * if a `KNOWN_TYPES` member is added without a corresponding entry here
+ * (TypeScript's version of the `§7.3 shipped-assets lint` cross-check the
+ * plan describes for later — "adding a KNOWN_TYPE forces a decision").
+ *
+ * `renderer`/`action` are the built-in search-hit rendering data (WI-C, §2) —
+ * see the file header.
+ */
+export const TYPE_PRESENTATION = {
+    skill: { label: "Skill", renderer: "skill-md", action: (ref) => `akm show ${ref} -> follow the instructions` },
+    command: {
+        label: "Command",
+        renderer: "command-md",
+        action: (ref) => `akm show ${ref} -> fill placeholders and dispatch`,
+    },
+    agent: { label: "Agent", renderer: "agent-md", action: (ref) => `akm show ${ref} -> dispatch with full prompt` },
+    knowledge: {
+        label: "Knowledge",
+        renderer: "knowledge-md",
+        action: (ref) => `akm show ${ref} -> read reference material`,
+    },
+    workflow: { label: "Workflow", renderer: "workflow-md", action: (ref) => buildWorkflowAction(ref) },
+    script: { label: "Script", renderer: "script-source", action: (ref) => `akm show ${ref} -> execute the run command` },
+    memory: { label: "Memory", renderer: "memory-md", action: (ref) => `akm show ${ref} -> recall context` },
+    env: {
+        label: "Env",
+        renderer: "env-file",
+        action: (ref) => `akm show ${ref} -> inspect key names; akm env run ${ref} -- <command> -> run with the whole .env injected (prefer --clean to minimize inherited parent env; child stdout is not redacted). akm env export ${ref} --out <file> writes a sourceable script (values to a file, not stdout).`,
+    },
+    secret: {
+        label: "Secret",
+        renderer: "secret-file",
+        action: (ref) => `akm show ${ref} -> name only (value never shown); akm secret run ${ref} <VAR> -- <command> -> run with value injected into $VAR`,
+    },
+    lesson: {
+        label: "Lesson",
+        renderer: "lesson-md",
+        action: (ref) => `akm show ${ref} -> read the lesson and apply when_to_use`,
+    },
+    task: {
+        label: "Task",
+        renderer: "task-yaml",
+        action: (ref) => `akm show ${ref} -> inspect; akm task run <id> -> run now; edit the file + akm task sync -> unschedule`,
+    },
+    session: {
+        label: "Session",
+        renderer: "session-md",
+        action: (ref) => `akm show ${ref} -> read the session summary; follow the \`access\` frontmatter to open the raw log at \`log_path\``,
+    },
+    fact: {
+        label: "Fact",
+        renderer: "fact-md",
+        action: (ref) => `akm show ${ref} -> read the stash fact and apply it as durable context`,
+    },
+    // `instruction` (CLAUDE.md / AGENTS.md) is a read-like-knowledge markdown
+    // doc (spec §6/§7 instruction row, maintainer resolution 2026-07): it REUSES
+    // the `knowledge-md` renderer and mirrors knowledge's read action, so an
+    // instruction hit renders exactly like knowledge instead of the generic
+    // fallback (the parity guard in akm-presentation.test.ts pins this).
+    instruction: {
+        label: "Instruction",
+        renderer: "knowledge-md",
+        action: (ref) => `akm show ${ref} -> read the project instructions`,
+    },
+};
+/** Generic fallback for a type outside {@link KNOWN_TYPES} — never `undefined`, never a throw. */
+const DEFAULT_PRESENTATION = { label: "Asset" };
+/**
+ * Open-string lookup with a generic, non-`undefined` fallback (plan §2.3).
+ * `undefined` (no type known yet) and any foreign/adapter type both resolve
+ * to {@link DEFAULT_PRESENTATION}; only AKM's own {@link KNOWN_TYPES} get a
+ * type-specific presentation.
+ */
+export function presentationFor(type) {
+    if (type !== undefined && isKnownType(type))
+        return TYPE_PRESENTATION[type];
+    return DEFAULT_PRESENTATION;
+}
+export const defaultRendererRegistry = {
+    rendererNameFor(type) {
+        return presentationFor(type).renderer;
+    },
+    actionBuilderFor(type) {
+        return presentationFor(type).action;
+    },
+};

package/dist/core/warn.js

@@ -78,9 +78,6 @@ export function setLogFile(filePath) {
 export function clearLogFile() {
     logFilePath = undefined;
 }
-export function getLogFile() {
-    return logFilePath;
-}
 function appendToLogFile(level, args) {
     if (!logFilePath)
         return;