barry-cache 0.3.2 → 0.4.0

package/README.md

@@ -12,7 +12,7 @@ It creates source-backed context files for coding agents, validates them, and gi
 
 Barry Cache exists because coding agents need durable project context that is shared, reviewable, and smaller than the whole repository. Private assistant memory, ad hoc chat history, and vendor-specific instruction files drift apart; Barry keeps the source of truth in the repo and lets every agent load the same facts.
 
-The structure is intentionally layered: canonical context lives in `docs/context/`, operational continuity lives in `.context-state/`, and generated retrieval data lives in `.context-cache/`. Canonical facts stay source-backed and validated, while `route`, `search`, `load`, and `resume` project only the relevant feature pack into an agent session.
+The structure is intentionally layered: canonical context lives in `docs/context/`, operational continuity lives in `.context-state/`, and generated retrieval data lives in `.context-cache/`. Canonical facts stay source-backed and validated, while `route`, `search`, `load`, and `resume` project only the relevant feature pack into an agent session. Repeated retrieval commands reuse `.context-cache/context-index.json` when the source context file manifest is unchanged.
 
 That gives Barry three core advantages: it is agent-agnostic, because adapters point to one canonical context; auditable, because facts carry stable IDs and source references; and context-efficient, because agents start from a small routed slice instead of rereading the whole codebase.
 
@@ -297,6 +297,8 @@ bun run barry -- load --route editor-media-runtime
 
 This keeps the agent from reading every context file in the repo.
 
+Barry also keeps a disposable parsed context index in `.context-cache/context-index.json`. It is keyed by the source context files and directories, so repeated `resume`, `load`, `route`, `search`, and `review --json` commands reuse parsed context until a context source file changes.
+
 If an agent ignores the repo instructions, prompt it explicitly:
 
 ```text

package/dist/cli.js

@@ -263,7 +263,11 @@ function unquote(input) {
 
 // src/core/context.ts
 import { appendFile, mkdir as mkdir2 } from "node:fs/promises";
-import { basename as basename2, join as join4 } from "node:path";
+import { basename as basename2, join as join5 } from "node:path";
+
+// src/core/context-cache.ts
+import { stat as stat2 } from "node:fs/promises";
+import { join as join4 } from "node:path";
 
 // src/core/validate.ts
 import { join as join3 } from "node:path";
@@ -338,17 +342,155 @@ function validateFact(value) {
   return null;
 }
 
+// src/core/context-cache.ts
+var cacheVersion = 1;
+var contextCachePath = ".context-cache/context-index.json";
+async function readContextSnapshot(repo) {
+  const cached = await readFreshContextCache(repo);
+  if (cached)
+    return hydrateSnapshot(repo, cached);
+  const snapshot = await readContextSnapshotFromDisk(repo);
+  await writeContextCache(repo, snapshot);
+  return snapshot;
+}
+async function readFreshContextCache(repo) {
+  try {
+    const parsed = JSON.parse(await readTextIfExists(repoPath(repo, contextCachePath)));
+    if (!isContextCacheFile(parsed))
+      return null;
+    return await manifestIsFresh(repo, parsed.manifest) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+async function writeContextCache(repo, snapshot) {
+  const cache = {
+    version: cacheVersion,
+    generated_at: new Date().toISOString(),
+    manifest: await buildManifest(repo, snapshot),
+    features: snapshot.features.map((feature) => ({
+      ...feature,
+      dir: rel(repo, feature.dir)
+    })),
+    adrs: snapshot.adrs
+  };
+  try {
+    await writeText(repoPath(repo, contextCachePath), `${JSON.stringify(cache, null, 2)}
+`);
+  } catch {}
+}
+async function readContextSnapshotFromDisk(repo) {
+  return {
+    features: await readFeaturePacksFromDisk(repo),
+    adrs: (await readAdrCatalog(repo)).adrs
+  };
+}
+async function readFeaturePacksFromDisk(repo) {
+  const root = repoPath(repo, "docs/context/features");
+  const slugs = await listDirs(root);
+  const features = [];
+  for (const slug2 of slugs) {
+    const dir = join4(root, slug2);
+    features.push({
+      slug: slug2,
+      dir,
+      readme: await readTextIfExists(join4(dir, "README.md")),
+      idmap: await readTextIfExists(join4(dir, "IDMAP.md")),
+      graph: await readTextIfExists(join4(dir, "KG.adj")),
+      facts: await readFacts(join4(dir, "FACTS.jsonl"))
+    });
+  }
+  return features;
+}
+async function readFacts(path) {
+  const rows = (await readTextIfExists(path)).split(/\r?\n/);
+  const facts = [];
+  for (const row of rows) {
+    if (row.trim().length === 0)
+      continue;
+    const parsed = JSON.parse(row);
+    if (validateFact(parsed) === null)
+      facts.push(parsed);
+  }
+  return facts;
+}
+async function buildManifest(repo, snapshot) {
+  const paths = new Map;
+  paths.set("docs/context/features", "dir");
+  paths.set("docs/context/adrs", "dir");
+  for (const feature of snapshot.features) {
+    const dir = rel(repo, feature.dir);
+    paths.set(dir, "dir");
+    paths.set(`${dir}/README.md`, "file");
+    paths.set(`${dir}/IDMAP.md`, "file");
+    paths.set(`${dir}/KG.adj`, "file");
+    paths.set(`${dir}/FACTS.jsonl`, "file");
+  }
+  for (const adr of snapshot.adrs) {
+    paths.set(adr.path, "file");
+  }
+  const entries = [...paths.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+  return await Promise.all(entries.map(([path, kind]) => statManifestEntry(repo, path, kind)));
+}
+async function manifestIsFresh(repo, manifest) {
+  for (const entry of manifest) {
+    const current = await statManifestEntry(repo, entry.path, entry.kind);
+    if (!sameManifestEntry(entry, current))
+      return false;
+  }
+  return true;
+}
+async function statManifestEntry(repo, path, kind) {
+  try {
+    const value = await stat2(repoPath(repo, path));
+    const matchesKind = kind === "dir" ? value.isDirectory() : value.isFile();
+    if (!matchesKind)
+      return { path, kind, exists: false };
+    return {
+      path,
+      kind,
+      exists: true,
+      mtimeMs: value.mtimeMs,
+      size: value.size
+    };
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return { path, kind, exists: false };
+    throw error;
+  }
+}
+function sameManifestEntry(left, right) {
+  if (left.path !== right.path || left.kind !== right.kind || left.exists !== right.exists)
+    return false;
+  if (!left.exists || !right.exists)
+    return true;
+  return left.mtimeMs === right.mtimeMs && left.size === right.size;
+}
+function hydrateSnapshot(repo, cache) {
+  return {
+    features: cache.features.map((feature) => ({
+      ...feature,
+      dir: repoPath(repo, feature.dir)
+    })),
+    adrs: cache.adrs
+  };
+}
+function isContextCacheFile(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const candidate = value;
+  return candidate.version === cacheVersion && Array.isArray(candidate.manifest) && Array.isArray(candidate.features) && Array.isArray(candidate.adrs);
+}
+
 // src/core/context.ts
 async function routeTask({ repo, task }) {
-  const features = await readFeaturePacks(repo);
-  const adrs = await listAdrs({ repo });
+  const { features, adrs } = await readContextSnapshot(repo);
   const taskTokens = tokens(task);
   const routes = features.map((feature) => scoreFeature(feature, taskTokens, adrs)).filter((route) => route.score > 0).sort((a, b) => b.score - a.score || a.slug.localeCompare(b.slug));
   return { task, routes };
 }
 async function searchContext({ repo, query }) {
-  const features = await readFeaturePacks(repo);
-  const adrs = await listAdrs({ repo });
+  const { features, adrs } = await readContextSnapshot(repo);
   const queryTokens = tokens(query);
   const results = [];
   for (const feature of features) {
@@ -374,7 +516,7 @@ async function searchContext({ repo, query }) {
           route: feature.slug,
           score,
           text: factText,
-          source: `${rel(repo, join4(feature.dir, "FACTS.jsonl"))}#${fact.id}`
+          source: `${rel(repo, join5(feature.dir, "FACTS.jsonl"))}#${fact.id}`
         });
       }
     }
@@ -396,8 +538,7 @@ async function searchContext({ repo, query }) {
   return { query, results };
 }
 async function loadContext({ repo, route }) {
-  const features = await readFeaturePacks(repo);
-  const adrs = await listAdrs({ repo });
+  const { features, adrs } = await readContextSnapshot(repo);
   const feature = features.find((item) => item.slug === route) ?? null;
   if (!feature)
     return { feature: null, facts: [], sources: [], adrs: [] };
@@ -405,10 +546,10 @@ async function loadContext({ repo, route }) {
     feature,
     facts: feature.facts,
     sources: [
-      rel(repo, join4(feature.dir, "README.md")),
-      rel(repo, join4(feature.dir, "IDMAP.md")),
-      rel(repo, join4(feature.dir, "KG.adj")),
-      rel(repo, join4(feature.dir, "FACTS.jsonl"))
+      rel(repo, join5(feature.dir, "README.md")),
+      rel(repo, join5(feature.dir, "IDMAP.md")),
+      rel(repo, join5(feature.dir, "KG.adj")),
+      rel(repo, join5(feature.dir, "FACTS.jsonl"))
     ],
     adrs: linkedAdrsForSources(feature.facts.flatMap((fact) => fact.src), adrs)
   };
@@ -432,7 +573,7 @@ async function resumeProject({ repo, task }) {
 async function finalizeProject(options) {
   const dir = repoPath(options.repo, ".context-state/handoffs");
   await mkdir2(dir, { recursive: true });
-  const path = join4(dir, "handoffs.jsonl");
+  const path = join5(dir, "handoffs.jsonl");
   const record = {
     id: `handoff-${new Date().toISOString()}`,
     updated_at: new Date().toISOString(),
@@ -445,35 +586,6 @@ async function finalizeProject(options) {
 `);
   return { saved: true, path: rel(options.repo, path), summary: options.summary };
 }
-async function readFeaturePacks(repo) {
-  const root = repoPath(repo, "docs/context/features");
-  const slugs = await listDirs(root);
-  const features = [];
-  for (const slug2 of slugs) {
-    const dir = join4(root, slug2);
-    features.push({
-      slug: slug2,
-      dir,
-      readme: await readTextIfExists(join4(dir, "README.md")),
-      idmap: await readTextIfExists(join4(dir, "IDMAP.md")),
-      graph: await readTextIfExists(join4(dir, "KG.adj")),
-      facts: await readFacts(join4(dir, "FACTS.jsonl"))
-    });
-  }
-  return features;
-}
-async function readFacts(path) {
-  const rows = (await readTextIfExists(path)).split(/\r?\n/);
-  const facts = [];
-  for (const row of rows) {
-    if (row.trim().length === 0)
-      continue;
-    const parsed = JSON.parse(row);
-    if (validateFact(parsed) === null)
-      facts.push(parsed);
-  }
-  return facts;
-}
 function scoreFeature(feature, taskTokens, adrs) {
   const linkedAdrs = linkedAdrsForSources(feature.facts.flatMap((fact) => fact.src), adrs);
   const text = [
@@ -516,7 +628,7 @@ function firstLine(value) {
 }
 
 // src/core/import-pulpcut.ts
-import { join as join5 } from "node:path";
+import { join as join6 } from "node:path";
 async function importPulpcutKb(options) {
   const dryRun = options.dryRun ?? false;
   const result = {
@@ -531,19 +643,19 @@ async function importPulpcutKb(options) {
     warnings: []
   };
   const sourceDocs = repoPath(options.from, "docs");
-  const kbIndex = await readTextIfExists(join5(sourceDocs, "KB_INDEX.md"));
+  const kbIndex = await readTextIfExists(join6(sourceDocs, "KB_INDEX.md"));
   if (kbIndex.trim().length === 0) {
-    throw new Error(`PulpCut KB index not found at ${join5(sourceDocs, "KB_INDEX.md")}`);
+    throw new Error(`PulpCut KB index not found at ${join6(sourceDocs, "KB_INDEX.md")}`);
   }
   const routes = parseKbIndex(kbIndex);
   const slugs = await listDirs(sourceDocs);
   for (const slug2 of slugs) {
-    const sourceDir = join5(sourceDocs, slug2);
-    const rawFacts = await readTextIfExists(join5(sourceDir, "FACTS.jsonl"));
+    const sourceDir = join6(sourceDocs, slug2);
+    const rawFacts = await readTextIfExists(join6(sourceDir, "FACTS.jsonl"));
     if (rawFacts.trim().length === 0)
       continue;
-    const idmap = await readTextIfExists(join5(sourceDir, "IDMAP.md"));
-    const graph = await readTextIfExists(join5(sourceDir, "KG.adj"));
+    const idmap = await readTextIfExists(join6(sourceDir, "IDMAP.md"));
+    const graph = await readTextIfExists(join6(sourceDir, "KG.adj"));
     if (idmap.trim().length === 0)
       result.warnings.push(`${slug2}: missing IDMAP.md`);
     if (graph.trim().length === 0)
@@ -728,7 +840,7 @@ function stringOrStringArray(value) {
 
 // src/core/init.ts
 import { mkdir as mkdir3 } from "node:fs/promises";
-import { join as join6 } from "node:path";
+import { join as join7 } from "node:path";
 
 // src/core/templates.ts
 var managedStart = "<!-- barry-cache:start -->";
@@ -761,6 +873,8 @@ Barry Cache remembers this repo through source-backed context files.
 
 ${commandNote}
 
+Repeated retrieval commands use the disposable parsed index in \`.context-cache/context-index.json\` when source context files have not changed.
+
 Start task context with:
 
 \`\`\`bash
@@ -855,7 +969,7 @@ Barry Cache keeps repo context source-backed, validated, and easy for agents to
 
 This directory is the canonical project memory for Barry Cache. It keeps durable implementation context in Git so humans and agents can review the same source-backed facts instead of relying on private assistant memory or stale chat history.
 
-Barry separates three concerns: \`docs/context/\` is reviewed truth, \`.context-state/\` is operational session continuity, and \`.context-cache/\` is disposable retrieval data. Use this structure to explain existing behavior, route tasks, validate facts, and resume agent work without loading the whole repo.
+Barry separates three concerns: \`docs/context/\` is reviewed truth, \`.context-state/\` is operational session continuity, and \`.context-cache/\` is disposable retrieval data. Barry stores a parsed context index in \`.context-cache/context-index.json\` and reuses it while the source context manifest is unchanged. Use this structure to explain existing behavior, route tasks, validate facts, and resume agent work without loading the whole repo.
 `;
 var adrReadmeMd = `# Architecture Decision Records
 
@@ -876,7 +990,7 @@ Barry Cache separates canonical context, operational state, and generated caches
 
 - Canonical context lives in \`docs/context/\`.
 - Operational continuity lives in \`.context-state/\`.
-- Generated retrieval data lives in \`.context-cache/\`.
+- Generated retrieval data lives in \`.context-cache/\`, including the disposable parsed context index.
 `;
 var factSchema = {
   $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -975,11 +1089,11 @@ async function initProject(options) {
   await patchAgentInstructions(repo, dryRun, result, options.agents, commandPrefix, packageManager);
   await patchGitignore(repo, dryRun, result);
   if (!dryRun) {
-    await mkdir3(join6(repo, ".context-state/work/threads"), { recursive: true });
-    await mkdir3(join6(repo, ".context-state/handoffs"), { recursive: true });
-    await mkdir3(join6(repo, ".context-state/failures"), { recursive: true });
-    await mkdir3(join6(repo, ".context-state/strategies"), { recursive: true });
-    await mkdir3(join6(repo, ".context-cache"), { recursive: true });
+    await mkdir3(join7(repo, ".context-state/work/threads"), { recursive: true });
+    await mkdir3(join7(repo, ".context-state/handoffs"), { recursive: true });
+    await mkdir3(join7(repo, ".context-state/failures"), { recursive: true });
+    await mkdir3(join7(repo, ".context-state/strategies"), { recursive: true });
+    await mkdir3(join7(repo, ".context-cache"), { recursive: true });
   }
   result.changed = result.written.length > 0 || result.updated.length > 0;
   return result;
@@ -1102,7 +1216,7 @@ function llmsTxt() {
 }
 
 // src/core/review-model.ts
-import { join as join7 } from "node:path";
+import { join as join8 } from "node:path";
 
 // src/core/review-tree.ts
 function buildReviewTree(facts) {
@@ -1254,8 +1368,7 @@ async function buildReviewModel({ repo }) {
   const warnings = [];
   const facts = [];
   const timeline = [];
-  const features = await readFeaturePacks(repo);
-  const adrs = await listAdrs({ repo });
+  const { features, adrs } = await readContextSnapshot(repo);
   for (const adr of adrs)
     addAdr(graph, adr);
   for (const feature of features) {
@@ -1265,7 +1378,7 @@ async function buildReviewModel({ repo }) {
     for (const fact of feature.facts) {
       facts.push({
         route: feature.slug,
-        source: `${rel(repo, join7(feature.dir, "FACTS.jsonl"))}#${fact.id}`,
+        source: `${rel(repo, join8(feature.dir, "FACTS.jsonl"))}#${fact.id}`,
         fact
       });
       addFact(graph, repo, feature, fact, sourceMap, adrs);
@@ -1347,7 +1460,7 @@ function addFact(graph, repo, feature, fact, sourceMap, adrs) {
     kind: "fact",
     label: fact.id,
     subtitle: `${fact.subject} ${fact.predicate} ${fact.object}`,
-    source: `${rel(repo, join7(feature.dir, "FACTS.jsonl"))}#${fact.id}`,
+    source: `${rel(repo, join8(feature.dir, "FACTS.jsonl"))}#${fact.id}`,
     meta: {
       route: feature.slug,
       status: fact.status,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "barry-cache",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Barry Cache remembers your repo.",
   "type": "module",
   "bin": {