aiwcli 0.15.5 → 0.17.0

package/dist/lib/context/context-store.js

@@ -0,0 +1,644 @@
+/**
+ * Context store — 2-layer CRUD for context state management.
+ * See SPEC.md §7
+ *
+ * Replaces context_manager's 3-layer approach with a simpler 2-layer model:
+ *   state.json   (per context folder — SOURCE OF TRUTH)
+ *   index.json   (at _output/ root — fast session→context lookup)
+ */
+import * as fs from "node:fs";
+import path from "node:path";
+import { atomicWrite } from "../runtime/atomic-write.js";
+import { getContextDir, getContextsDir, getIndexPath, getArchiveDir, getArchiveContextDir, getArchiveIndexPath, validateContextId, } from "../runtime/constants.js";
+import { logInfo, logWarn, logError, setContextPath } from "../runtime/logger.js";
+import { readStateJson, writeStateJson } from "../runtime/state-io.js";
+import { nowIso, generateContextId } from "../runtime/utils.js";
+import { IndexFileSchema } from "../schemas.js";
+const INDEX_VERSION = "3.0";
+// Module-level index cache — safe because each hook is a separate bun process
+let _indexCache = null;
+// ---------------------------------------------------------------------------
+// Public utilities
+// ---------------------------------------------------------------------------
+/**
+ * Determine artifact type from context state.
+ * Checks explicit next_artifact_type field first, falls back to field detection.
+ *
+ * Edge cases:
+ * - Both artifacts exist: Log warning, return "plan" (deterministic fallback for corrupted state)
+ * - No artifacts: Return null (caller handles gracefully)
+ */
+export function determineArtifactType(state) {
+    // Explicit field takes precedence
+    if (state.next_artifact_type) {
+        return state.next_artifact_type;
+    }
+    // Implicit detection
+    const hasPlan = Boolean(state.plan_path && state.plan_hash);
+    const hasHandoff = Boolean(state.handoff_path);
+    // Edge case: Both exist (shouldn't happen - indicates bug in replacement logic)
+    // Fallback: Pick plan (deterministic, no filesystem I/O)
+    if (hasPlan && hasHandoff) {
+        logWarn("context_store", `Context ${state.id} has both plan and handoff - indicates bug in replacement logic`);
+        return "plan";
+    }
+    if (hasPlan)
+        return "plan";
+    if (hasHandoff)
+        return "handoff";
+    // No artifacts present - return null (caller logs warning and skips)
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function loadIndex(projectRoot) {
+    if (_indexCache)
+        return _indexCache;
+    const indexPath = getIndexPath(projectRoot);
+    if (fs.existsSync(indexPath)) {
+        try {
+            const raw = fs.readFileSync(indexPath, "utf8");
+            const data = JSON.parse(raw);
+            const validated = IndexFileSchema.safeParse(data);
+            if (!validated.success) {
+                logWarn("context_store", `Index schema validation failed, recreating: ${validated.error.message}`);
+            }
+            else {
+                _indexCache = data;
+                return _indexCache;
+            }
+        }
+        catch (error) {
+            logWarn("context_store", `Failed to read index, recreating: ${error}`);
+        }
+    }
+    const fresh = { version: INDEX_VERSION, updated_at: nowIso(), sessions: {}, contexts: {} };
+    _indexCache = fresh;
+    return fresh;
+}
+function saveIndex(index, projectRoot) {
+    index.updated_at = nowIso();
+    const content = JSON.stringify(index, null, 2);
+    // fsync: false — index.json is reconstructable by scanning _output/contexts/
+    const [success, error] = atomicWrite(getIndexPath(projectRoot), content, 2, [500, 1000], false);
+    if (!success) {
+        logWarn("context_store", `Failed to write index: ${error}`);
+    }
+    _indexCache = index;
+    return success;
+}
+function toIndexEntry(state) {
+    return {
+        summary: state.summary,
+        mode: state.mode,
+        last_active: state.last_active,
+    };
+}
+/**
+ * Backward compat: read legacy context.json and convert to ContextState.
+ */
+function migrateContextJson(contextId, projectRoot) {
+    const legacyPath = path.join(getContextDir(contextId, projectRoot), "context.json");
+    if (!fs.existsSync(legacyPath))
+        return null;
+    try {
+        const data = JSON.parse(fs.readFileSync(legacyPath, "utf8"));
+        const inFlight = data.in_flight ?? {};
+        const oldMode = inFlight.mode ?? "none";
+        const MODE_MIGRATION = {
+            none: "idle",
+            planning: "idle",
+            pending_implementation: "has_plan",
+            implementing: "active",
+        };
+        const mode = (MODE_MIGRATION[oldMode] ?? "idle");
+        const sessionIds = inFlight.session_ids ??
+            (inFlight.session_id ? [inFlight.session_id] : []);
+        return {
+            id: data.id ?? contextId,
+            status: data.status ?? "active",
+            summary: data.summary ?? "",
+            method: data.method ?? "",
+            tags: data.tags ?? [],
+            created_at: data.created_at ?? "",
+            last_active: data.last_active ?? "",
+            mode,
+            plan_path: inFlight.artifact_path ?? null,
+            plan_hash: inFlight.artifact_hash ?? null,
+            plan_signature: null,
+            plan_id: null,
+            plan_anchors: [],
+            plan_hash_consumed: null,
+            plan_consumed: false,
+            handoff_path: inFlight.handoff_path ?? null,
+            handoff_consumed: false,
+            work_consumed: false,
+            next_artifact_type: null,
+            session_ids: sessionIds,
+            last_session: null,
+            tasks: [],
+        };
+    }
+    catch (error) {
+        logWarn("context_store", `Failed to migrate context.json for '${contextId}': ${error}`);
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Core CRUD
+// ---------------------------------------------------------------------------
+/**
+ * Read state.json for a context. Falls back to context.json for migration.
+ * See SPEC.md §7.2
+ */
+export function loadState(contextId, projectRoot) {
+    const state = readStateJson(contextId, projectRoot);
+    if (state)
+        return state;
+    // Backward compat: migrate from legacy context.json
+    return migrateContextJson(contextId, projectRoot);
+}
+/**
+ * Atomically write state.json AND update index.json.
+ * See SPEC.md §7.3
+ */
+export function saveState(contextId, state, projectRoot) {
+    // Ensure the state ID matches
+    state.id = contextId;
+    const [success, error] = writeStateJson(contextId, state, projectRoot);
+    if (!success) {
+        logWarn("context_store", `Failed to write state.json for '${contextId}': ${error}`);
+        return [false, error];
+    }
+    // Update index.json
+    const index = loadIndex(projectRoot);
+    index.contexts[contextId] = toIndexEntry(state);
+    // Keep session mappings in sync
+    for (const sid of state.session_ids) {
+        if (!index.sessions)
+            index.sessions = {};
+        index.sessions[sid] = contextId;
+    }
+    const indexOk = saveIndex(index, projectRoot);
+    if (!indexOk) {
+        return [true, "state.json saved but index.json update failed"];
+    }
+    return [true, null];
+}
+/**
+ * Create a new context folder + state.json + index entry.
+ * Throws ValueError-equivalent if context already exists.
+ * See SPEC.md §7.4
+ */
+export function createContext(contextId, summary, method = "", projectRoot, tags) {
+    // Generate ID if needed
+    if (!contextId) {
+        const existingIds = new Set();
+        const contextsDir = getContextsDir(projectRoot);
+        if (fs.existsSync(contextsDir)) {
+            for (const entry of fs.readdirSync(contextsDir)) {
+                const fullPath = path.join(contextsDir, entry);
+                try {
+                    if (fs.statSync(fullPath).isDirectory()) {
+                        existingIds.add(entry);
+                    }
+                }
+                catch { /* ignore */ }
+            }
+        }
+        contextId = generateContextId(summary, existingIds);
+    }
+    contextId = validateContextId(contextId);
+    const contextDir = getContextDir(contextId, projectRoot);
+    if (fs.existsSync(contextDir)) {
+        throw new Error(`Context '${contextId}' already exists`);
+    }
+    fs.mkdirSync(contextDir, { recursive: true });
+    fs.mkdirSync(path.join(contextDir, "notes"), { recursive: true });
+    const now = nowIso();
+    const state = {
+        id: contextId,
+        status: "active",
+        summary,
+        method,
+        tags: tags ?? [],
+        created_at: now,
+        last_active: now,
+        mode: "idle",
+        plan_path: null,
+        plan_hash: null,
+        plan_signature: null,
+        plan_id: null,
+        plan_anchors: [],
+        plan_hash_consumed: null,
+        handoff_path: null,
+        work_consumed: false, // CHANGED: unified flag
+        next_artifact_type: null,
+        session_ids: [],
+        last_session: null,
+        tasks: [],
+    };
+    saveState(contextId, state, projectRoot);
+    logInfo("context_store", `Created context: ${contextId}`);
+    return state;
+}
+/**
+ * Load a single context by ID.
+ * See SPEC.md §7.5
+ */
+export function getContext(contextId, projectRoot) {
+    try {
+        contextId = validateContextId(contextId);
+    }
+    catch {
+        return null;
+    }
+    return loadState(contextId, projectRoot);
+}
+/**
+ * List contexts from index.json, loading each state.json.
+ * Falls back to scanning context folders if index is missing.
+ * Results sorted by last_active descending.
+ * See SPEC.md §7.6
+ */
+export function getAllContexts(status, projectRoot) {
+    const results = [];
+    const contextsDir = getContextsDir(projectRoot);
+    if (!fs.existsSync(contextsDir))
+        return [];
+    // Try index-driven path first
+    const index = loadIndex(projectRoot);
+    const ctxMap = index.contexts;
+    if (ctxMap && typeof ctxMap === "object" && Object.keys(ctxMap).length > 0) {
+        const orphanIds = [];
+        for (const cid of Object.keys(ctxMap)) {
+            const state = loadState(cid, projectRoot);
+            if (state && (!status || state.status === status)) {
+                results.push(state);
+            }
+            else if (!state) {
+                orphanIds.push(cid);
+            }
+        }
+        if (orphanIds.length > 0) {
+            logWarn("context_store", `Index references ${orphanIds.length} missing context(s): ${orphanIds.join(", ")}. Auto-repairing index.`);
+            const idx = loadIndex(projectRoot);
+            for (const cid of orphanIds) {
+                delete idx.contexts[cid];
+                if (idx.sessions) {
+                    for (const [sid, target] of Object.entries(idx.sessions)) {
+                        if (target === cid)
+                            delete idx.sessions[sid];
+                    }
+                }
+            }
+            saveIndex(idx, projectRoot);
+        }
+    }
+    else {
+        // Fallback: scan folders
+        try {
+            for (const entry of fs.readdirSync(contextsDir)) {
+                if (entry.startsWith("_"))
+                    continue;
+                const fullPath = path.join(contextsDir, entry);
+                try {
+                    if (!fs.statSync(fullPath).isDirectory())
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+                const state = loadState(entry, projectRoot);
+                if (state && (!status || state.status === status)) {
+                    results.push(state);
+                }
+            }
+        }
+        catch { /* empty dir */ }
+    }
+    results.sort((a, b) => (b.last_active || "").localeCompare(a.last_active || ""));
+    return results;
+}
+/**
+ * Update allowed metadata fields (summary, tags, method) on a context.
+ * See SPEC.md §7.7
+ */
+export function updateContext(contextId, updates, projectRoot) {
+    const state = getContext(contextId, projectRoot);
+    if (!state)
+        return null;
+    let changed = false;
+    if (updates.summary !== undefined) {
+        state.summary = updates.summary;
+        changed = true;
+    }
+    if (updates.tags !== undefined) {
+        state.tags = updates.tags;
+        changed = true;
+    }
+    if (updates.method !== undefined) {
+        state.method = updates.method;
+        changed = true;
+    }
+    if (!changed)
+        return state;
+    state.last_active = nowIso();
+    saveState(contextId, state, projectRoot);
+    return state;
+}
+// ---------------------------------------------------------------------------
+// Session binding & mode updates
+// ---------------------------------------------------------------------------
+/**
+ * O(1) lookup: check index.json sessions map first.
+ * Side effect: sets logger context path for per-context log routing.
+ * See SPEC.md §7.8
+ */
+export function getContextBySessionId(sessionId, projectRoot) {
+    if (!sessionId || sessionId === "unknown")
+        return null;
+    const index = loadIndex(projectRoot);
+    const cid = index.sessions?.[sessionId];
+    if (cid) {
+        const state = loadState(cid, projectRoot);
+        if (state) {
+            setLoggerContext(state.id, projectRoot);
+            return state;
+        }
+    }
+    // Fallback: scan all contexts
+    for (const state of getAllContexts("active", projectRoot)) {
+        if (state.session_ids.includes(sessionId)) {
+            setLoggerContext(state.id, projectRoot);
+            return state;
+        }
+    }
+    return null;
+}
+function setLoggerContext(contextId, projectRoot) {
+    try {
+        const ctxDir = getContextDir(contextId, projectRoot);
+        if (fs.existsSync(ctxDir)) {
+            setContextPath(ctxDir);
+        }
+    }
+    catch {
+        // Never crash on logging setup
+    }
+}
+/**
+ * Add session_id to both index.json sessions map and state.json session_ids.
+ * See SPEC.md §7.9
+ */
+export function bindSession(contextId, sessionId, projectRoot) {
+    if (!sessionId || sessionId === "unknown")
+        return false;
+    const state = getContext(contextId, projectRoot);
+    if (!state)
+        return false;
+    if (!state.session_ids.includes(sessionId)) {
+        state.session_ids.push(sessionId);
+    }
+    state.last_active = nowIso();
+    const [success] = saveState(contextId, state, projectRoot);
+    return success;
+}
+/**
+ * Change the mode field, optionally setting plan/handoff fields.
+ * See SPEC.md §7.10
+ */
+export function updateMode(contextId, mode, projectRoot, opts) {
+    const state = getContext(contextId, projectRoot);
+    if (!state)
+        return null;
+    state.mode = mode;
+    state.last_active = nowIso();
+    if (opts) {
+        if (opts.plan_path !== undefined)
+            state.plan_path = opts.plan_path;
+        if (opts.plan_hash !== undefined)
+            state.plan_hash = opts.plan_hash;
+        if (opts.plan_signature !== undefined)
+            state.plan_signature = opts.plan_signature;
+        if (opts.plan_id !== undefined)
+            state.plan_id = opts.plan_id;
+        if (opts.plan_anchors !== undefined)
+            state.plan_anchors = opts.plan_anchors;
+        if (opts.work_consumed !== undefined)
+            state.work_consumed = opts.work_consumed; // CHANGED: unified flag
+        if (opts.plan_hash_consumed !== undefined)
+            state.plan_hash_consumed = opts.plan_hash_consumed;
+    }
+    // Clear plan/handoff fields when returning to idle
+    if (mode === "idle") {
+        state.plan_path = null;
+        state.plan_hash = null;
+        state.plan_signature = null;
+        state.plan_id = null;
+        state.plan_anchors = [];
+        state.plan_hash_consumed = null;
+        state.handoff_path = null;
+        state.work_consumed = false; // CHANGED: unified flag
+        state.next_artifact_type = null;
+    }
+    saveState(contextId, state, projectRoot);
+    return state;
+}
+/**
+ * Transition idle/has_staged_work → active, unless in plan mode.
+ * See SPEC.md §7.11
+ */
+export function maybeActivate(contextId, permissionMode, projectRoot, caller = "") {
+    if (permissionMode === "plan")
+        return false;
+    const state = getContext(contextId, projectRoot);
+    if (!state)
+        return false;
+    if (state.mode === "idle" || state.mode === "has_staged_work") {
+        const oldMode = state.mode;
+        const opts = {};
+        if (oldMode === "has_staged_work")
+            opts.work_consumed = true; // CHANGED: unified flag
+        updateMode(contextId, "active", projectRoot, opts);
+        logInfo("context_store", `maybe_activate (${caller}): ${contextId} ${oldMode} -> active`);
+        return true;
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Lifecycle
+// ---------------------------------------------------------------------------
+/**
+ * Mark context completed and archive it.
+ * See SPEC.md §7.12
+ */
+export function completeContext(contextId, projectRoot) {
+    const state = getContext(contextId, projectRoot);
+    if (!state)
+        return null;
+    if (state.status === "completed") {
+        logInfo("context_store", `Context '${contextId}' already completed`);
+        return state;
+    }
+    state.status = "completed";
+    state.last_active = nowIso();
+    saveState(contextId, state, projectRoot);
+    logInfo("context_store", `Completed context: ${contextId}`);
+    const archived = archiveContext(contextId, projectRoot);
+    return archived ?? state;
+}
+/**
+ * Move completed context folder to _archive/, update indices.
+ * See SPEC.md §7.13
+ */
+export function archiveContext(contextId, projectRoot) {
+    const state = getContext(contextId, projectRoot);
+    if (!state) {
+        logWarn("context_store", `Cannot archive: context '${contextId}' not found`);
+        return null;
+    }
+    if (state.status !== "completed") {
+        logWarn("context_store", `Cannot archive: context '${contextId}' not completed`);
+        return null;
+    }
+    const sourceDir = getContextDir(contextId, projectRoot);
+    const archiveDest = getArchiveContextDir(contextId, projectRoot);
+    if (fs.existsSync(archiveDest)) {
+        logWarn("context_store", `Cannot archive: archive folder already exists for '${contextId}'`);
+        return null;
+    }
+    const archiveParent = path.dirname(archiveDest);
+    fs.mkdirSync(archiveParent, { recursive: true });
+    try {
+        fs.renameSync(sourceDir, archiveDest);
+    }
+    catch (error) {
+        logError("context_store", `Failed to move context to archive: ${error}`);
+        return null;
+    }
+    // Remove from main index
+    const index = loadIndex(projectRoot);
+    delete index.contexts[contextId];
+    const sessions = index.sessions ?? {};
+    for (const [sid, cid] of Object.entries(sessions)) {
+        if (cid === contextId)
+            delete sessions[sid];
+    }
+    saveIndex(index, projectRoot);
+    // Add to archive index
+    updateArchiveIndex(state, projectRoot);
+    logInfo("context_store", `Archived context: ${contextId}`);
+    return state;
+}
+/**
+ * Reopen a completed/archived context.
+ * See SPEC.md §7.14
+ */
+export function reopenContext(contextId, projectRoot) {
+    let state = getContext(contextId, projectRoot);
+    if (!state) {
+        state = restoreFromArchive(contextId, projectRoot);
+    }
+    if (!state)
+        return null;
+    if (state.status === "active") {
+        logInfo("context_store", `Context '${contextId}' already active`);
+        return state;
+    }
+    state.status = "active";
+    state.last_active = nowIso();
+    saveState(contextId, state, projectRoot);
+    logInfo("context_store", `Reopened context: ${contextId}`);
+    return state;
+}
+// ---------------------------------------------------------------------------
+// Auto-creation from prompt
+// ---------------------------------------------------------------------------
+/**
+ * Auto-create a context from the user's prompt.
+ * See SPEC.md §7.15
+ */
+export function createContextFromPrompt(userPrompt, projectRoot) {
+    let summary = userPrompt.trim().slice(0, 2000);
+    if (userPrompt.trim().length > 2000) {
+        summary += "...";
+    }
+    return createContext(null, summary, "auto-created", projectRoot, ["auto-created"]);
+}
+// ---------------------------------------------------------------------------
+// Archive helpers
+// ---------------------------------------------------------------------------
+function updateArchiveIndex(state, projectRoot) {
+    const archiveDir = getArchiveDir(projectRoot);
+    const archiveIndexPath = getArchiveIndexPath(projectRoot);
+    fs.mkdirSync(archiveDir, { recursive: true });
+    let archiveIndex = {
+        version: INDEX_VERSION,
+        updated_at: nowIso(),
+        sessions: {},
+        contexts: {},
+    };
+    if (fs.existsSync(archiveIndexPath)) {
+        try {
+            archiveIndex = JSON.parse(fs.readFileSync(archiveIndexPath, "utf8"));
+        }
+        catch (error_) {
+            logWarn("context_store", `Failed to read archive index, recreating: ${error_}`);
+        }
+    }
+    archiveIndex.contexts[state.id] = toIndexEntry(state);
+    archiveIndex.updated_at = nowIso();
+    const content = JSON.stringify(archiveIndex, null, 2);
+    const [success, error] = atomicWrite(archiveIndexPath, content);
+    if (!success) {
+        logWarn("context_store", `Failed to write archive index: ${error}`);
+    }
+    return success;
+}
+function restoreFromArchive(contextId, projectRoot) {
+    const archiveDir = getArchiveContextDir(contextId, projectRoot);
+    const activeDir = getContextDir(contextId, projectRoot);
+    if (!fs.existsSync(archiveDir))
+        return null;
+    if (fs.existsSync(activeDir)) {
+        logWarn("context_store", `Cannot restore: active folder already exists for '${contextId}'`);
+        return null;
+    }
+    try {
+        fs.renameSync(archiveDir, activeDir);
+    }
+    catch (error) {
+        logError("context_store", `Failed to restore context from archive: ${error}`);
+        return null;
+    }
+    // Remove from archive index
+    removeFromArchiveIndex(contextId, projectRoot);
+    const state = loadState(contextId, projectRoot);
+    logInfo("context_store", `Restored context from archive: ${contextId}`);
+    return state;
+}
+function removeFromArchiveIndex(contextId, projectRoot) {
+    const archiveIndexPath = getArchiveIndexPath(projectRoot);
+    if (!fs.existsSync(archiveIndexPath))
+        return true;
+    try {
+        const archiveIndex = JSON.parse(fs.readFileSync(archiveIndexPath, "utf8"));
+        if (archiveIndex.contexts[contextId]) {
+            delete archiveIndex.contexts[contextId];
+            archiveIndex.updated_at = nowIso();
+            const content = JSON.stringify(archiveIndex, null, 2);
+            const [success, error] = atomicWrite(archiveIndexPath, content);
+            if (!success) {
+                logWarn("context_store", `Failed to write archive index: ${error}`);
+                return false;
+            }
+        }
+        return true;
+    }
+    catch (error) {
+        logWarn("context_store", `Failed to read archive index: ${error}`);
+        return false;
+    }
+}

package/dist/lib/context/plan-manager.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Plan lifecycle management — archival, lookup, and path extraction.
+ * See SPEC.md §9
+ *
+ * Provides pure-data operations on plan files:
+ * - archivePlan: copy plan to context plans/ folder, compute hash + signature
+ * - findLatestPlan: locate the most relevant plan for a context
+ * - extractPlanPathFromResult: parse plan path from ExitPlanMode output
+ */
+/**
+ * Archive a plan file to the context's plans/ folder.
+ * Computes a content hash and signature.
+ * Does NOT modify state.json or mode.
+ * See SPEC.md §9.2
+ *
+ * Returns [archivedPath, planHash, planSignature] on success,
+ * or [null, null, null] on error.
+ */
+export declare function archivePlan(planPath: string, contextId: string, projectRoot?: string): [string | null, string | null, string | null];
+/**
+ * Find the most relevant plan file for a context.
+ * Priority: state.json plan_path > most recent .md in plans/ dir.
+ * See SPEC.md §9.3
+ */
+export declare function findLatestPlan(contextId: string, projectRoot?: string): string | null;
+/**
+ * Generate a short unique plan identifier (8 hex chars).
+ * See SPEC.md §9.4
+ */
+export declare function generatePlanId(): string;
+/**
+ * Aggressively normalize plan content for hashing.
+ * Strips all XML/HTML tags and collapses whitespace.
+ * See SPEC.md §9.5
+ */
+export declare function normalizePlanContent(text: string): string;
+/**
+ * Extract structural anchors from plan content.
+ * Returns markdown headings + first substantial paragraph as short strings.
+ * See SPEC.md §9.6
+ */
+export declare function extractPlanAnchors(content: string, maxAnchors?: number): string[];
+/**
+ * Find the plan file path by parsing the session transcript JSONL.
+ * Searches in reverse for the most recent Write tool call targeting .claude/plans/.
+ * See SPEC.md §9.7
+ */
+export declare function findPlanPathInTranscript(transcriptPath: string): string | null;
+/**
+ * Extract plan file path from ExitPlanMode tool result.
+ * Parses the pattern: "Your plan has been saved to: <path>"
+ * See SPEC.md §9.8
+ */
+export declare function extractPlanPathFromResult(toolResult: string): string | null;