aiki-cli 0.2.0

package/dist/storage/runs-read.js

@@ -0,0 +1,95 @@
+// Read-side helpers for stored runs under `.aiki/runs/` (T9). The write side is RunWriter (runs.ts);
+// this is the counterpart used by `aiki show` and `aiki resolve`.
+//
+// Run ids are timestamp-prefixed (`20260704-1312-idea-refinement-8c44`) so a plain lexical sort is
+// chronological — the last element is the most recent run.
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+/**
+ * Pure run-id resolution (unit-tested without fs). Rules (grilled 2026-07-04):
+ * - no arg → the most recent run (lexical-max, since ids are timestamp-prefixed);
+ * - exact dir-name match wins;
+ * - else unique substring/suffix match (so `8c44` finds the full id);
+ * - multiple substring matches → ambiguous (return candidates); none → no-match.
+ */
+export function matchRunId(ids, arg) {
+    if (ids.length === 0)
+        return { ok: false, kind: 'none' };
+    const sorted = [...ids].sort();
+    if (!arg)
+        return { ok: true, runId: sorted[sorted.length - 1] };
+    if (ids.includes(arg))
+        return { ok: true, runId: arg };
+    const candidates = sorted.filter((id) => id.includes(arg));
+    if (candidates.length === 1)
+        return { ok: true, runId: candidates[0] };
+    if (candidates.length > 1)
+        return { ok: false, kind: 'ambiguous', arg, candidates };
+    return { ok: false, kind: 'no-match', arg };
+}
+/** List stored run ids (directory names under `<root>/runs/`). Empty if the dir doesn't exist. */
+export async function listRuns(root = '.aiki') {
+    try {
+        const entries = await readdir(join(root, 'runs'), { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+/** Resolve a run-id arg to a concrete run directory + id (listRuns + matchRunId). */
+export async function resolveRunId(arg, root = '.aiki') {
+    return matchRunId(await listRuns(root), arg);
+}
+export function runDir(runId, root = '.aiki') {
+    return join(root, 'runs', runId);
+}
+/** Read a run's final report, or null if it was never written (aborted/partial run). */
+export async function readFinalReport(dir) {
+    try {
+        return await readFile(join(dir, 'final-report.md'), 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/** Parse a JSON artifact from a run dir, or null if absent/unparseable. */
+export async function readJsonArtifact(dir, name) {
+    try {
+        return JSON.parse(await readFile(join(dir, name), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Recursively list every artifact file in a run dir as sorted relative paths (for `show --raw`). */
+export async function listArtifacts(dir) {
+    const out = [];
+    async function walk(d) {
+        let entries;
+        try {
+            entries = await readdir(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const full = join(d, e.name);
+            if (e.isDirectory())
+                await walk(full);
+            else
+                out.push(relative(dir, full));
+        }
+    }
+    await walk(dir);
+    return out.sort();
+}
+/** True if a run directory exists on disk. */
+export async function runExists(dir) {
+    try {
+        return (await stat(dir)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/storage/runs.js

@@ -0,0 +1,129 @@
+// Artifact writer for a single run's `.aiki/runs/<id>/` folder (§15).
+//
+// Guarantees (§14, §24 T4 acceptance):
+// - Ordered writes: numbered stage artifacts must be written in forward order. A write for a
+//   stage earlier than the furthest-reached stage is refused (`OutOfOrderWriteError`). This is
+//   §14's "the artifact writer refuses out-of-order writes".
+// - Immutable artifacts: a stage file, once written, cannot be rewritten (crash-forensics
+//   integrity). `meta.json` is the sole exception — it is finalized/updated (§16 aborted:true).
+// - Crash-safe writes: every file is written to `<path>.tmp` then atomically `rename`d into
+//   place, so a crash mid-write never leaves a truncated/invalid artifact on disk.
+// - Schema boundary: artifacts with a core schema (§14) are zod-validated BEFORE hitting disk;
+//   an invalid payload throws and writes nothing.
+import { mkdir, rename, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { ActionPlan, DisagreementMap, IntentContract, JudgeReport, ReviewMap, RoleOutput, RunBrief, RunMeta, VerificationSet } from '../schemas/index.js';
+export class OutOfOrderWriteError extends Error {
+    constructor(slot, ord, maxOrd) {
+        super(`out-of-order write: "${slot}" (stage ${ord}) after stage ${maxOrd} already written`);
+        this.name = 'OutOfOrderWriteError';
+    }
+}
+export class DuplicateWriteError extends Error {
+    constructor(relPath) {
+        super(`artifact already written (immutable): ${relPath}`);
+        this.name = 'DuplicateWriteError';
+    }
+}
+/** JSON stage slots. Composites without a T4 core schema (misunderstanding-guard, drift, claims)
+ *  are written as-is; their schemas land with S2/S5/S6 (T5–T6). */
+const JSON_SLOTS = {
+    'run-brief': { ord: 0.5, path: '00b-run-brief.json', schema: RunBrief },
+    'intent-contract': { ord: 1, path: '01-intent-contract.json', schema: IntentContract },
+    'misunderstanding-guard': { ord: 2, path: '02-misunderstanding-guard.json', schema: null },
+    'drift-report': { ord: 5, path: '05-drift-report.json', schema: null },
+    claims: { ord: 6, path: '06-claims.json', schema: null },
+    'disagreement-map': { ord: 7, path: '07-disagreement-map.json', schema: DisagreementMap },
+    // code-review's stage-7 artifact (ord 7, distinct path). A run writes one of {disagreement-map,
+    // review-map} depending on its workflow, so the shared ord never collides within a run.
+    'review-map': { ord: 7, path: '07-review-map.json', schema: ReviewMap },
+    verifications: { ord: 8, path: '08-verifications.json', schema: VerificationSet },
+    'judge-report': { ord: 9, path: '09-judge-report.json', schema: JudgeReport },
+    'action-plan': { ord: 9.5, path: '09b-action-plan.json', schema: ActionPlan },
+};
+/** Text (markdown) stage slots (§15). */
+const TEXT_SLOTS = {
+    original: { ord: 0, path: '00-original.md' },
+    'final-report': { ord: 10, path: 'final-report.md' },
+};
+const PROMPTS_DIR_ORD = 3; // 03-prompts/
+const ROLE_OUTPUTS_DIR_ORD = 4; // 04-role-outputs/
+/**
+ * Writes one run's artifacts under `<root>/runs/<runId>/`. One instance per run; not concurrency
+ * safe for the same run (a run is single-threaded through its stages). `root` defaults to `.aiki`.
+ */
+export class RunWriter {
+    runId;
+    dir;
+    maxOrd = -1;
+    written = new Set(); // relPaths of immutable artifacts already on disk
+    constructor(runId, root = '.aiki') {
+        this.runId = runId;
+        this.dir = join(root, 'runs', runId);
+    }
+    /** Create the run directory. Idempotent. */
+    async init() {
+        await mkdir(this.dir, { recursive: true });
+    }
+    // ── ordered stage artifacts ───────────────────────────────────────────────
+    /** Write a JSON stage artifact. Validates against its core schema when one exists (§14). */
+    async writeJson(slot, data) {
+        const def = JSON_SLOTS[slot];
+        const payload = def.schema ? def.schema.parse(data) : data; // throws on invalid → nothing written
+        this.reserve(def.ord, def.path);
+        return this.atomicWrite(def.path, JSON.stringify(payload, null, 2));
+    }
+    /** Write a markdown stage artifact (00-original.md / final-report.md). */
+    async writeText(slot, text) {
+        const def = TEXT_SLOTS[slot];
+        this.reserve(def.ord, def.path);
+        return this.atomicWrite(def.path, text);
+    }
+    /** Write the exact final prompt sent to a provider for a stage → 03-prompts/<name> (§15). */
+    async writePrompt(name, text) {
+        const rel = join('03-prompts', name);
+        this.reserve(PROMPTS_DIR_ORD, rel);
+        return this.atomicWrite(rel, text);
+    }
+    /** Write one validated S4 role output → 04-role-outputs/<name>.json. Validates RoleOutput (§14). */
+    async writeRoleOutput(name, data) {
+        const payload = RoleOutput.parse(data); // engine attaches the `workflow` discriminator first (S4)
+        const rel = join('04-role-outputs', name.endsWith('.json') ? name : `${name}.json`);
+        this.reserve(ROLE_OUTPUTS_DIR_ORD, rel);
+        return this.atomicWrite(rel, JSON.stringify(payload, null, 2));
+    }
+    // ── unordered artifacts ───────────────────────────────────────────────────
+    /** Copy an input verbatim → inputs/<name> (diff.patch, source docs). Unordered; overwritable. */
+    async writeInput(name, content) {
+        return this.atomicWrite(join('inputs', name), content);
+    }
+    /** Dump an untouched provider stdout/stderr → raw/<name> (e.g. s4-claude.out). Unordered. */
+    async writeRaw(name, content) {
+        return this.atomicWrite(join('raw', name), content);
+    }
+    /** Write/finalize meta.json (§15, §16). Validated against RunMeta; overwritable (updated at
+     *  finalize / on abort). Not subject to stage ordering. */
+    async writeMeta(meta) {
+        const payload = RunMeta.parse(meta);
+        return this.atomicWrite('meta.json', JSON.stringify(payload, null, 2));
+    }
+    // ── internals ─────────────────────────────────────────────────────────────
+    /** Enforce forward-only ordering + one-shot immutability for stage artifacts. */
+    reserve(ord, relPath) {
+        if (ord < this.maxOrd)
+            throw new OutOfOrderWriteError(relPath, ord, this.maxOrd);
+        if (this.written.has(relPath))
+            throw new DuplicateWriteError(relPath);
+        this.maxOrd = Math.max(this.maxOrd, ord);
+        this.written.add(relPath);
+    }
+    /** Atomic write: temp file + rename, so a crash never leaves a partial artifact (§24 T4). */
+    async atomicWrite(relPath, content) {
+        const full = join(this.dir, relPath);
+        await mkdir(dirname(full), { recursive: true });
+        const tmp = `${full}.tmp`;
+        await writeFile(tmp, content, 'utf8');
+        await rename(tmp, full);
+        return full;
+    }
+}

package/dist/storage/sessions.js

@@ -0,0 +1,71 @@
+// Global session registry (V6.3) — `~/.aiki/sessions.jsonl`, append-only, one JSON object per line.
+// Records every run REGARDLESS of where it was launched, so `aiki sessions` can list them and
+// `aiki resume` can locate a run that lives under a different project's `.aiki`. Status updates append
+// a fresh full line; readers keep the last line per id (last-write-wins).
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { homeAikiRoot } from './paths.js';
+export const SessionStatus = z.enum(['running', 'ok', 'failed', 'aborted']);
+export const SessionEntry = z
+    .object({
+    id: z.string().min(1),
+    workflow: z.string(),
+    cwd: z.string(), // launch dir (code-review needs it as the reviewer repo root on resume)
+    runsRoot: z.string(), // absolute .aiki root the run lives under (repo vs ~/.aiki)
+    startedAt: z.string(), // ISO
+    status: SessionStatus,
+    resumedFrom: z.string().optional(),
+})
+    .strict();
+function registryPath() {
+    return join(homeAikiRoot(), 'sessions.jsonl');
+}
+export async function recordSession(entry) {
+    await mkdir(homeAikiRoot(), { recursive: true });
+    await appendFile(registryPath(), `${JSON.stringify(SessionEntry.parse(entry))}\n`);
+}
+/** All sessions, newest first, deduped by id (the last line for an id wins — that's its latest status). */
+export async function readSessions() {
+    let raw;
+    try {
+        raw = await readFile(registryPath(), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const byId = new Map();
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const e = SessionEntry.parse(JSON.parse(line));
+            byId.set(e.id, e); // last line for this id wins
+        }
+        catch {
+            /* skip a malformed/legacy line */
+        }
+    }
+    // Newest first by startedAt.
+    return [...byId.values()].sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+}
+/** Re-append the entry with a new status (keeps the append-only file honest). No-op if id unknown. */
+export async function updateSessionStatus(id, status) {
+    const cur = (await readSessions()).find((s) => s.id === id);
+    if (!cur)
+        return;
+    await recordSession({ ...cur, status });
+}
+/** Locate a session by exact id or a unique suffix/substring (mirrors resolveRunId's matching). */
+export async function findSession(idArg) {
+    const all = await readSessions();
+    const exact = all.find((s) => s.id === idArg);
+    if (exact)
+        return exact;
+    const hits = all.filter((s) => s.id.includes(idArg));
+    if (hits.length === 1)
+        return hits[0];
+    if (hits.length > 1)
+        return { ambiguous: hits.map((s) => s.id) };
+    return null;
+}