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

package/dist/integrations/lockfile.js

@@ -4,8 +4,9 @@
 import fs from "node:fs";
 import path from "node:path";
 import { writeFileAtomic } from "../core/common.js";
-import { rethrowIfTestIsolationError } from "../core/errors.js";
-import { probeLock, releaseLock, tryAcquireLockSync } from "../core/file-lock.js";
+import { ConfigError, rethrowIfTestIsolationError } from "../core/errors.js";
+import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync } from "../core/file-lock.js";
+import { acquireMaintenanceBarrier } from "../core/maintenance-barrier.js";
 import { getDataDir, getLockfileLockPath, getLockfilePath } from "../core/paths.js";
 // ── Lock sentinel ────────────────────────────────────────────────────────────
 const LOCK_MAX_RETRIES = 3;
@@ -15,23 +16,26 @@ async function acquireLockSentinel() {
     // Ensure the directory exists before attempting to create the sentinel.
     fs.mkdirSync(path.dirname(sentinelPath), { recursive: true });
     for (let attempt = 0; attempt < LOCK_MAX_RETRIES; attempt++) {
-        if (tryAcquireLockSync(sentinelPath, String(process.pid))) {
-            return true; // Sentinel created — we own the lock.
+        const releaseBarrier = acquireMaintenanceBarrier();
+        try {
+            const ownership = tryAcquireLockSync(sentinelPath, createLockPayload());
+            if (ownership) {
+                return () => releaseLock(ownership);
+            }
+            const probe = probeLock(sentinelPath);
+            if (probe.state === "stale" && reclaimStaleLock(sentinelPath, probe)) {
+                continue; // Reclaimed — retry immediately.
+            }
         }
-        if (probeLock(sentinelPath).state === "stale") {
-            releaseLock(sentinelPath);
-            continue; // Reclaimed — retry immediately.
+        finally {
+            releaseBarrier();
         }
         // Another process holds the lock — wait briefly before retrying.
         if (attempt < LOCK_MAX_RETRIES - 1) {
             await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_DELAY_MS));
         }
     }
-    // Best-effort: proceed without the lock rather than failing the install.
-    return false;
-}
-function releaseLockSentinel() {
-    releaseLock(getLockfileLockPath());
+    throw new ConfigError(`Could not acquire lockfile sentinel at ${sentinelPath}; refusing to write without exclusive ownership.`, "INVALID_CONFIG_FILE");
 }
 // ── Read / Write ────────────────────────────────────────────────────────────
 export function readLockfile() {
@@ -50,40 +54,223 @@ export function readLockfile() {
         return [];
     }
 }
-export function writeLockfile(entries) {
+/**
+ * Like {@link readLockfile}, but THROWS instead of silently degrading to `[]`
+ * when the on-disk lockfile exists yet is not parseable JSON or not a JSON
+ * array (R-012).
+ *
+ * `readLockfile`'s fail-open contract is intentional for READ paths — a
+ * corrupt lock degrades a managed bundle to "unmanaged" rather than erroring
+ * every read-only command (`list`, `installed-stashes`, …). But
+ * {@link upsertLockEntry} and {@link removeLockEntry} read the current
+ * entries and then WRITE `[...entries, change]` back out; if that read
+ * silently returned `[]` for a corrupt file, the write would silently
+ * replace the corrupt file with one containing only the single new/changed
+ * entry — permanently destroying every other surviving lock record. Write
+ * paths use this strict variant so a corrupt lockfile fails the operation
+ * loudly (matching the guard `mergeLockEntriesSync` already applies) instead
+ * of quietly deleting user state. A missing file is NOT corruption — there
+ * is nothing to preserve, so that case still returns `[]`. Entries that fail
+ * per-entry validation are still tolerated (filtered out), matching
+ * `readLockfile`'s existing shape-tolerant behavior.
+ */
+function readLockfileOrThrow() {
+    const lockfilePath = getLockfilePath();
+    let raw;
+    try {
+        raw = fs.readFileSync(lockfilePath, "utf8");
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+        return []; // File does not exist (or is otherwise unreadable) — nothing to preserve.
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new ConfigError(`Refusing to modify lockfile ${lockfilePath}: existing content is not valid JSON (${error instanceof Error ? error.message : String(error)}). Fix or remove the file by hand before retrying — every existing lock entry would otherwise be lost.`, "INVALID_CONFIG_FILE");
+    }
+    if (!Array.isArray(parsed)) {
+        throw new ConfigError(`Refusing to modify lockfile ${lockfilePath}: existing content is not a JSON array. Fix or remove the file by hand before retrying — every existing lock entry would otherwise be lost.`, "INVALID_CONFIG_FILE");
+    }
+    return parsed.filter(isValidLockfileEntry);
+}
+/**
+ * The materialized content root recorded in the lock for a managed (git/npm)
+ * bundle — spec §10.2 desired/resolved split, where the desired config carries
+ * only the source LOCATOR and the resolved `localRoot` lives here.
+ *
+ * This is the SINGLE lock-first resolution point shared by the indexer READ
+ * path (`resolveEntryContentDir` in indexer/search) and the command-layer WRITE
+ * path (`adaptConfiguredSource` in core/write-source): consulting it first makes
+ * a write land in exactly the directory a read walks. Returns `undefined` for a
+ * bundle with no lock `localRoot` (e.g. a config migrated from a `sources[]`
+ * url, whose provider re-derives the cache path) or a non-managed type, so both
+ * callers fall back to the identical provider-path derivation.
+ */
+export function lockContentRootFor(bundleId, type) {
+    if (!bundleId || (type !== "git" && type !== "npm"))
+        return undefined;
+    for (const lock of readLockfile()) {
+        if (lock.id === bundleId && typeof lock.localRoot === "string" && lock.localRoot.length > 0) {
+            return lock.localRoot;
+        }
+    }
+    return undefined;
+}
+function writeLockfileUnlocked(entries) {
     // Always write to $DATA — never to the legacy $CONFIG location.
     const lockfilePath = getLockfilePath();
     const dir = path.dirname(lockfilePath);
     fs.mkdirSync(dir, { recursive: true });
     writeFileAtomic(lockfilePath, `${JSON.stringify(entries, null, 2)}\n`);
 }
+export async function writeLockfile(entries) {
+    const release = await acquireLockSentinel();
+    try {
+        writeLockfileUnlocked(entries);
+    }
+    finally {
+        release();
+    }
+}
+/** Replace one exact parsed lock generation while the lockfile sentinel is held. */
+export async function compareAndSwapLockfile(expected, desired) {
+    const release = await acquireLockSentinel();
+    try {
+        const current = readLockfileOrThrow();
+        if (JSON.stringify(current) !== JSON.stringify(expected))
+            return false;
+        writeLockfileUnlocked(desired);
+        return true;
+    }
+    finally {
+        release();
+    }
+}
 export async function upsertLockEntry(entry) {
-    const acquired = await acquireLockSentinel();
+    const release = await acquireLockSentinel();
     try {
-        const entries = readLockfile();
+        // R-012: readLockfileOrThrow (not readLockfile) — a corrupt/malformed
+        // lockfile must abort the upsert loudly rather than read as `[]` and get
+        // silently overwritten with just this one entry.
+        const entries = readLockfileOrThrow();
         const withoutExisting = entries.filter((e) => e.id !== entry.id);
-        writeLockfile([...withoutExisting, entry]);
+        writeLockfileUnlocked([...withoutExisting, entry]);
     }
     finally {
-        if (acquired)
-            releaseLockSentinel();
+        release();
     }
 }
+/**
+ * Synchronously upsert lock entries (merge by id) WITHOUT acquiring the async
+ * sentinel — for a caller already holding an exclusive lifecycle lock (e.g.
+ * migrate-apply's config lock + maintenance barrier) whose synchronous body
+ * cannot await the sentinel's retry loop. No-op for an empty list.
+ */
+export function mergeLockEntriesSync(entries) {
+    if (entries.length === 0)
+        return;
+    let existing = [];
+    const lockfilePath = getLockfilePath();
+    if (fs.existsSync(lockfilePath)) {
+        let raw;
+        try {
+            raw = JSON.parse(fs.readFileSync(lockfilePath, "utf8"));
+        }
+        catch (error) {
+            throw new ConfigError(`Cannot merge migration lock entries into unreadable lockfile ${lockfilePath}: ${error instanceof Error ? error.message : String(error)}.`, "INVALID_CONFIG_FILE");
+        }
+        if (!Array.isArray(raw) || !raw.every(isValidLockfileEntry)) {
+            throw new ConfigError(`Cannot merge migration lock entries into malformed lockfile ${lockfilePath}.`, "INVALID_CONFIG_FILE");
+        }
+        existing = raw;
+    }
+    // MERGE per id, never replace: the migrator's entries are sparse (id/source/
+    // ref/localRoot), while an existing row may carry `resolvedVersion`,
+    // `resolvedRevision`, `integrity`, `installedAt`, … from a real install.
+    // Replacing the whole row discarded the user's recorded resolution/pin and
+    // left later update reporting comparing against an unknown prior version.
+    // Incoming DEFINED fields win; existing fields absent from the incoming
+    // entry are preserved.
+    const byId = new Map(existing.map((e) => [e.id, e]));
+    const merged = entries.map((incoming) => {
+        const prior = byId.get(incoming.id);
+        return prior ? { ...prior, ...incoming } : incoming;
+    });
+    const incomingIds = new Set(entries.map((e) => e.id));
+    writeLockfileUnlocked([...existing.filter((e) => !incomingIds.has(e.id)), ...merged]);
+}
+/** Freeze exact old/desired lockfile bytes while the migration lifecycle lock is held. */
+export function planLockMergeSync(entries) {
+    const lockfilePath = getLockfilePath();
+    let oldBytes = null;
+    let existing = [];
+    try {
+        oldBytes = fs.readFileSync(lockfilePath, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    if (oldBytes !== null) {
+        let parsed;
+        try {
+            parsed = JSON.parse(oldBytes);
+        }
+        catch (error) {
+            throw new ConfigError(`Cannot plan migration lock entries from unreadable lockfile ${lockfilePath}: ${error instanceof Error ? error.message : String(error)}.`, "INVALID_CONFIG_FILE");
+        }
+        if (!Array.isArray(parsed) || !parsed.every(isValidLockfileEntry)) {
+            throw new ConfigError(`Cannot plan migration lock entries from malformed lockfile ${lockfilePath}.`, "INVALID_CONFIG_FILE");
+        }
+        existing = parsed;
+    }
+    if (entries.length === 0)
+        return { oldBytes, desiredBytes: oldBytes };
+    const byId = new Map(existing.map((entry) => [entry.id, entry]));
+    for (const entry of entries)
+        byId.set(entry.id, { ...byId.get(entry.id), ...entry });
+    return { oldBytes, desiredBytes: `${JSON.stringify([...byId.values()], null, 2)}\n` };
+}
+/** Publish a frozen migration lock generation, accepting only exact old or exact desired bytes. */
+export function publishPlannedLockMergeSync(plan) {
+    const lockfilePath = getLockfilePath();
+    let current = null;
+    try {
+        current = fs.readFileSync(lockfilePath, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    if (current === plan.desiredBytes)
+        return;
+    if (current !== plan.oldBytes) {
+        throw new ConfigError(`Refusing migration lockfile publication because ${lockfilePath} is a third generation, neither the journaled old nor desired bytes.`, "INVALID_CONFIG_FILE");
+    }
+    if (plan.desiredBytes === null)
+        return;
+    fs.mkdirSync(path.dirname(lockfilePath), { recursive: true });
+    writeFileAtomic(lockfilePath, plan.desiredBytes, 0o600);
+}
 export async function removeLockEntry(id) {
     if (!fs.existsSync(getDataDir()))
         return;
-    const acquired = await acquireLockSentinel();
+    const release = await acquireLockSentinel();
     try {
-        const entries = readLockfile();
-        writeLockfile(entries.filter((e) => e.id !== id));
+        // R-012: see upsertLockEntry — same destructive-overwrite risk on a
+        // corrupt lockfile, so the same strict reader is used here.
+        const entries = readLockfileOrThrow();
+        writeLockfileUnlocked(entries.filter((e) => e.id !== id));
     }
     finally {
-        if (acquired)
-            releaseLockSentinel();
+        release();
     }
 }
 // ── Helpers ─────────────────────────────────────────────────────────────────
-function isValidLockfileEntry(value) {
+export function isValidLockfileEntry(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return false;
     const obj = value;

package/dist/integrations/session-logs/index.js

@@ -2,24 +2,46 @@
 // 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/.
 import { getHarness, SESSION_LOG_HARNESSES } from "../harnesses/index.js";
-import { ClaudeCodeProvider } from "../harnesses/claude/session-log.js";
-import { OpenCodeProvider } from "../harnesses/opencode/session-log.js";
 export { extractInlineRefMentions } from "./inline-refs.js";
-const HARNESSES = [new ClaudeCodeProvider(), new OpenCodeProvider()];
-// #562: the unified HARNESS_REGISTRY is the single source of truth for which
-// harnesses expose session logs. Validate (behaviour-preserving) that every
-// session-log provider instantiated above resolves to a registry harness whose
-// `sessionLogs` capability is set — and via the id-normalization bridge, so a
-// provider named "claude-code" still maps to the canonical "claude" harness.
-// This turns a silently-drifting third registry into a startup invariant.
+// #562/P2 (plan §"Kill registry drift"): the provider array is DERIVED from
+// the unified HARNESS_REGISTRY — every harness with `capabilities.sessionLogs`
+// must supply a `sessionLogProvider` factory on its descriptor, and this is
+// the only place providers are instantiated. Adding a session-log harness is
+// therefore one registry entry, never an edit here.
+//
+// Ordered by canonical id so the pre-derivation provider order
+// ([claude-code, opencode] — visible in e.g. `extract --auto` result order)
+// is preserved deterministically, independent of HARNESS_REGISTRY declaration
+// order (which is pinned for JSON-schema enum stability).
+//
+// WI-9.7 (H1): `SESSION_LOG_HARNESSES` is `HARNESS_REGISTRY` narrowed by the
+// `isSessionLogHarness` type-predicate (see `../harnesses/types.ts`), so every
+// element's `capabilities.sessionLogs` is the literal `true` and
+// `sessionLogProvider` is a required (non-optional) field — a harness
+// declaring `sessionLogs: true` without a provider is now a compile error at
+// its `HARNESS_REGISTRY` entry, not a throw here. The load-time throw this
+// used to guard (`h.sessionLogProvider?.()` returning undefined) is gone;
+// `h.sessionLogProvider()` cannot be called with no provider to invoke.
+const HARNESSES = [...SESSION_LOG_HARNESSES]
+    .sort((a, b) => a.id.localeCompare(b.id))
+    .map((h) => h.sessionLogProvider());
+// Reverse invariant (kept from #562): every derived provider's runtime `name`
+// — a plain string the provider implementation sets independently of the
+// harness registry (e.g. `ClaudeCodeProvider`'s `"claude-code"`) — must
+// resolve back, via the id-normalization bridge, to a registry harness whose
+// `sessionLogs` capability is set. This is NOT expressible as a compile-time
+// type constraint: `SessionLogHarness.name` is a runtime string with no
+// static link to the `AkmHarness` that produced it, so a typo'd or
+// stale `name` (e.g. copy-pasted from another provider, or renamed on one
+// side only) would only ever surface as a wrong/silent lookup miss much later
+// (health scans, `extract --auto` attribution) rather than here at load time.
+// Kept as a runtime guard for that reason.
 for (const provider of HARNESSES) {
     const harness = getHarness(provider.name);
     if (!harness?.capabilities.sessionLogs) {
         throw new Error(`[akm] session-log provider "${provider.name}" is not registered as a sessionLogs harness in HARNESS_REGISTRY (src/integrations/harnesses). Add it there.`);
     }
 }
-// Touch the derived list so the dependency is explicit and tree-shake-safe.
-void SESSION_LOG_HARNESSES;
 const ERROR_PATTERNS = /error|failed|exception|cannot|undefined|null pointer|ENOENT|timeout/i;
 /**
  * Returns all available session log harnesses for the current machine.
@@ -28,22 +50,6 @@ const ERROR_PATTERNS = /error|failed|exception|cannot|undefined|null pointer|ENO
 export function getAvailableHarnesses() {
     return HARNESSES.filter((harness) => harness.isAvailable());
 }
-/**
- * Map each available harness to its `{ harnessName, roots }` watch target,
- * skipping harnesses that expose no roots (absent `watchRoots()` or an empty
- * result). This is the one stable entry point the watcher uses so it never
- * reaches into providers directly.
- */
-export function getWatchTargets() {
-    const targets = [];
-    for (const harness of getAvailableHarnesses()) {
-        const roots = harness.watchRoots?.() ?? [];
-        if (roots.length === 0)
-            continue;
-        targets.push({ harnessName: harness.name, roots });
-    }
-    return targets;
-}
 export function normalizeSessionTopic(text) {
     const normalized = text.replace(/\s+/g, " ").trim().toLowerCase();
     if (normalized.length < 10)
@@ -85,16 +91,13 @@ export function aggregateSessionEvents(events) {
  * Collect normalized session events from a set of harnesses for the health
  * candidate scan (#568).
  *
- * Pipeline selection per harness (capability-gated):
- *   - readSession-capable harness (`supportsReadSession !== false`): drive the
- *     richer `listSessions()` + `readSession()` pipeline. `readSession` flattens
+ * Pipeline selection per harness:
+ *   - Drive the richer `listSessions()` + `readSession()` pipeline. `readSession` flattens
  *     structured content — tool calls, assistant content blocks, thinking,
  *     tool_result — into event text (e.g. ClaudeCodeProvider's `parseClaudeEvent`
  *     surfaces `[tool:*]` / `[tool_result]` blocks that the legacy flat
  *     `readEvents` scan drops entirely). This is what lets health advisories see
  *     repeated tool failures / long runs that the flat scan hid.
- *   - legacy-only harness (`supportsReadSession === false`): fall back to the
- *     legacy flat `readEvents()` scan (behaviour-preserving).
  *
  * Extracted as a pure function (harnesses injected) so it is unit-testable
  * without touching the real on-disk session-log locations.
@@ -107,19 +110,13 @@ export function aggregateSessionEvents(events) {
  * health command (`akm health`, which calls this synchronously) blow past its
  * latency budget. `listSessions()` returns summaries sorted newest-first, so
  * capping to the most-recent N sessions per harness keeps the richer signal
- * for what actually matters (recent activity) while bounding cost. The legacy
- * flat-scan path is naturally cheaper and is left uncapped.
+ * for what actually matters (recent activity) while bounding cost.
  */
 const DEFAULT_MAX_SESSIONS_PER_HARNESS = 50;
 export function collectSessionEvents(harnesses, sinceMs, maxSessionsPerHarness = DEFAULT_MAX_SESSIONS_PER_HARNESS) {
     const events = [];
     for (const harness of harnesses) {
         try {
-            if (harness.supportsReadSession === false) {
-                // Legacy-only harness: only the flat event scan is available.
-                events.push(...harness.readEvents({ sinceMs }));
-                continue;
-            }
             // Rich path: enumerate sessions cheaply, then read each one's full
             // structured event stream. Falls back to readEvents if listSessions
             // surfaces nothing (e.g. a harness that wired readSession but whose

package/dist/integrations/session-logs/provider-base.js

@@ -0,0 +1,113 @@
+// 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/.
+/**
+ * Shared skeleton for {@link SessionLogHarness} providers (§4.6 dedup).
+ *
+ * Holds only what the concrete providers genuinely share: safe stat'ing,
+ * recursive directory walking, the mtime-filtered file→summary listing loop,
+ * the flat JSONL/log line→event scan, and conditional-spread assembly of
+ * {@link SessionSummary} refs stamped with the provider's runtime name.
+ * Everything platform-specific — file layouts, metadata peeking, SQLite
+ * stores, message flattening — stays in the subclasses.
+ */
+import fs from "node:fs";
+import path from "node:path";
+export class AbstractSessionLogProvider {
+    isAvailable() {
+        return fs.existsSync(this.availabilityRoot());
+    }
+    /** `fs.statSync` that returns `undefined` instead of throwing. */
+    statSafe(target) {
+        try {
+            return fs.statSync(target);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Recursively yield files under `dir` whose basename passes `matches`. */
+    *walkFiles(dir, matches) {
+        try {
+            for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                const full = path.join(dir, entry.name);
+                if (entry.isDirectory())
+                    yield* this.walkFiles(full, matches);
+                else if (matches(entry.name))
+                    yield full;
+            }
+        }
+        catch {
+            // permission errors etc.
+        }
+    }
+    /**
+     * Assemble a {@link SessionSummary} stamped with this provider's name.
+     * Timestamps are included whenever defined (0 is valid); `projectHint` /
+     * `title` only when non-empty, so absent metadata stays absent.
+     */
+    sessionRef(input) {
+        return {
+            harness: this.name,
+            sessionId: input.sessionId,
+            filePath: input.filePath,
+            ...(input.startedAt !== undefined ? { startedAt: input.startedAt } : {}),
+            ...(input.endedAt !== undefined ? { endedAt: input.endedAt } : {}),
+            ...(input.projectHint ? { projectHint: input.projectHint } : {}),
+            ...(input.title ? { title: input.title } : {}),
+        };
+    }
+    /**
+     * The shared listing loop: enumerate candidate session files, drop the
+     * unstat'able and the ones older than `sinceMs`, summarize the rest, and
+     * sort newest-ended first. An enumeration failure (root missing or
+     * unreadable) returns what was collected so far rather than throwing.
+     */
+    listSessionsFromFiles(input) {
+        const summaries = [];
+        try {
+            for (const filePath of input.enumerate()) {
+                const stat = this.statSafe(filePath);
+                if (!stat)
+                    continue;
+                if (stat.mtimeMs < input.sinceMs)
+                    continue;
+                const summary = input.summarize(filePath, stat);
+                if (summary)
+                    summaries.push(summary);
+            }
+        }
+        catch {
+            // Root missing or unreadable — return what we have.
+        }
+        return summaries.sort((a, b) => (b.endedAt ?? 0) - (a.endedAt ?? 0));
+    }
+    /**
+     * The legacy flat line scan shared by both providers' `readEvents`: parse
+     * each line as JSON, pull text/session-id through the per-provider
+     * selectors, skip entries whose text is missing or under 10 chars, and
+     * fall back to the file mtime when the entry carries no numeric timestamp.
+     */
+    *logLineEvents(input) {
+        for (const line of input.lines) {
+            try {
+                const entry = JSON.parse(line);
+                const text = input.selectText(entry);
+                if (typeof text !== "string" || text.length < 10)
+                    continue;
+                const sessionId = input.selectSessionId(entry);
+                yield {
+                    harness: this.name,
+                    text,
+                    ts: typeof entry?.timestamp === "number" ? entry.timestamp : input.fallbackTsMs,
+                    sessionId: typeof sessionId === "string" ? sessionId : undefined,
+                    role: typeof entry?.role === "string" ? entry.role : "unknown",
+                    filePath: input.filePath,
+                };
+            }
+            catch {
+                // skip malformed lines
+            }
+        }
+    }
+}