@thecat69/cache-ctrl 1.0.0

package/src/commands/checkFreshness.ts

@@ -0,0 +1,123 @@
+import { findRepoRoot, readCache, writeCache } from "../cache/cacheManager.js";
+import { isExternalStale, mergeHeaderMetadata, resolveTopExternalMatch } from "../cache/externalCache.js";
+import { checkFreshness } from "../http/freshnessChecker.js";
+import type { ExternalCacheFile } from "../types/cache.js";
+import { ExternalCacheFileSchema } from "../types/cache.js";
+import { ErrorCode, type Result } from "../types/result.js";
+import type { CheckFreshnessArgs, CheckFreshnessResult } from "../types/commands.js";
+import type { HeaderMeta } from "../cache/externalCache.js";
+import { getFileStem } from "../utils/fileStem.js";
+
+export async function checkFreshnessCommand(args: CheckFreshnessArgs): Promise<Result<CheckFreshnessResult["value"]>> {
+  try {
+    const repoRoot = await findRepoRoot(process.cwd());
+
+    // Find the best-matching external cache entry file path
+    const matchResult = await resolveTopExternalMatch(repoRoot, args.subject);
+    if (!matchResult.ok) return matchResult;
+
+    const filePath = matchResult.value;
+
+    // Load the matched entry's data
+    const readResult = await readCache(filePath);
+    if (!readResult.ok) return readResult;
+
+    const parseResult = ExternalCacheFileSchema.safeParse(readResult.value);
+    if (!parseResult.success) {
+      return { ok: false, error: `Malformed external cache file: ${filePath}`, code: ErrorCode.PARSE_ERROR };
+    }
+
+    const cacheEntry = parseResult.data;
+    const stem = getFileStem(filePath);
+    const subject = cacheEntry.subject ?? stem;
+
+    // Determine which URLs to check
+    const sources = cacheEntry.sources ?? [];
+    let urlsToCheck = sources;
+
+    if (args.url) {
+      const found = sources.find((s) => s.url === args.url);
+      if (!found) {
+        return {
+          ok: false,
+          error: `URL not found in sources for subject '${subject}'`,
+          code: ErrorCode.URL_NOT_FOUND,
+        };
+      }
+      urlsToCheck = [found];
+    } else {
+      urlsToCheck = sources;
+    }
+
+    // Check freshness for each URL
+    const sourceResults: Array<{
+      url: string;
+      status: "fresh" | "stale" | "error";
+      http_status?: number;
+      error?: string;
+    }> = [];
+
+    const headerUpdates: Record<string, HeaderMeta> = {};
+
+    for (const source of urlsToCheck) {
+      const stored = cacheEntry.header_metadata?.[source.url];
+      const result = await checkFreshness({
+        url: source.url,
+        ...(stored?.etag !== undefined ? { etag: stored.etag } : {}),
+        ...(stored?.last_modified !== undefined ? { last_modified: stored.last_modified } : {}),
+      });
+
+      sourceResults.push({
+        url: result.url,
+        status: result.status,
+        ...(result.http_status !== undefined ? { http_status: result.http_status } : {}),
+        ...(result.error !== undefined ? { error: result.error } : {}),
+      });
+
+      if (result.status !== "error") {
+        headerUpdates[source.url] = {
+          ...(result.etag !== undefined ? { etag: result.etag } : {}),
+          ...(result.last_modified !== undefined ? { last_modified: result.last_modified } : {}),
+          checked_at: new Date().toISOString(),
+          status: result.status,
+        };
+      }
+    }
+
+    // Only write back if at least one URL succeeded
+    const hasSuccessfulChecks = Object.keys(headerUpdates).length > 0;
+    if (hasSuccessfulChecks) {
+      const updated = mergeHeaderMetadata(cacheEntry, headerUpdates);
+      const writeResult = await writeCache(filePath, { header_metadata: updated.header_metadata });
+      if (!writeResult.ok) return writeResult;
+    }
+
+    // Determine overall status: entryIsOld always wins (stale by age), then anyStale, then allError
+    const allError = sourceResults.every((r) => r.status === "error");
+    const anyStale = sourceResults.some((r) => r.status === "stale");
+    const entryIsOld = isExternalStale(cacheEntry);
+
+    let overall: "fresh" | "stale" | "error";
+    if (entryIsOld) {
+      overall = "stale";
+    } else if (anyStale) {
+      overall = "stale";
+    } else if (allError && sourceResults.length > 0) {
+      overall = "error";
+    } else {
+      overall = "fresh";
+    }
+
+    return {
+      ok: true,
+      value: {
+        subject,
+        sources: sourceResults,
+        overall,
+      },
+    };
+  } catch (err) {
+    const error = err as Error;
+    return { ok: false, error: error.message, code: ErrorCode.UNKNOWN };
+  }
+}

package/src/commands/flush.ts

@@ -0,0 +1,55 @@
+import { unlink } from "node:fs/promises";
+import { findRepoRoot, listCacheFiles } from "../cache/cacheManager.js";
+import { resolveLocalCachePath } from "../cache/localCache.js";
+import { ErrorCode, type Result } from "../types/result.js";
+import type { FlushArgs, FlushResult } from "../types/commands.js";
+
+export async function flushCommand(args: FlushArgs): Promise<Result<FlushResult["value"]>> {
+  if (!args.confirm) {
+    return {
+      ok: false,
+      error: "flush requires --confirm flag to prevent accidental data loss",
+      code: ErrorCode.CONFIRMATION_REQUIRED,
+    };
+  }
+
+  try {
+    const repoRoot = await findRepoRoot(process.cwd());
+    const deleted: string[] = [];
+
+    if (args.agent === "external" || args.agent === "all") {
+      const filesResult = await listCacheFiles("external", repoRoot);
+      if (!filesResult.ok) return filesResult;
+
+      for (const filePath of filesResult.value) {
+        try {
+          await unlink(filePath);
+          deleted.push(filePath);
+        } catch (err) {
+          const error = err as NodeJS.ErrnoException;
+          if (error.code !== "ENOENT") {
+            return { ok: false, error: `Failed to delete ${filePath}: ${error.message}`, code: ErrorCode.FILE_WRITE_ERROR };
+          }
+        }
+      }
+    }
+
+    if (args.agent === "local" || args.agent === "all") {
+      const localPath = resolveLocalCachePath(repoRoot);
+      try {
+        await unlink(localPath);
+        deleted.push(localPath);
+      } catch (err) {
+        const error = err as NodeJS.ErrnoException;
+        if (error.code !== "ENOENT") {
+          return { ok: false, error: `Failed to delete ${localPath}: ${error.message}`, code: ErrorCode.FILE_WRITE_ERROR };
+        }
+      }
+    }
+
+    return { ok: true, value: { deleted, count: deleted.length } };
+  } catch (err) {
+    const error = err as Error;
+    return { ok: false, error: error.message, code: ErrorCode.UNKNOWN };
+  }
+}

package/src/commands/inspect.ts

@@ -0,0 +1,184 @@
+import { normalize } from "node:path";
+
+import { findRepoRoot, loadExternalCacheEntries, readCache } from "../cache/cacheManager.js";
+import { resolveLocalCachePath } from "../cache/localCache.js";
+import { scoreEntry } from "../search/keywordSearch.js";
+import type { CacheEntry, ExternalCacheFile, LocalCacheFile } from "../types/cache.js";
+import { ExternalCacheFileSchema, LocalCacheFileSchema } from "../types/cache.js";
+import { ErrorCode, type Result } from "../types/result.js";
+import type { InspectArgs, InspectResult } from "../types/commands.js";
+
+function filterFacts(
+  facts: Record<string, string[]>,
+  keywords: string[],
+): Record<string, string[]> {
+  if (keywords.length === 0) return facts;
+  const lower = keywords.map((k) => k.toLowerCase());
+  return Object.fromEntries(
+    Object.entries(facts).filter(([path]) => lower.some((kw) => path.toLowerCase().includes(kw))),
+  );
+}
+
+export async function inspectCommand(args: InspectArgs): Promise<Result<InspectResult["value"]>> {
+  try {
+    // Step 0 — folder guard: validate before any I/O.
+    if (args.folder !== undefined) {
+      if (args.agent === "external") {
+        return {
+          ok: false,
+          error: "--folder is only supported for local cache",
+          code: ErrorCode.INVALID_ARGS,
+        };
+      }
+
+      const normalizedFolder = args.folder.replace(/\\/g, "/").replace(/\/+$/, "");
+
+      if (normalizedFolder.length === 0) {
+        return {
+          ok: false,
+          error: "--folder must not be an empty string",
+          code: ErrorCode.INVALID_ARGS,
+        };
+      }
+
+      if (normalize(normalizedFolder).split("/").includes("..")) {
+        return {
+          ok: false,
+          error: "--folder must not contain '..' path segments",
+          code: ErrorCode.INVALID_ARGS,
+        };
+      }
+    }
+
+    const repoRoot = await findRepoRoot(process.cwd());
+
+    const candidates: Array<{ entry: CacheEntry; content: ExternalCacheFile | LocalCacheFile; file: string }> = [];
+
+    if (args.agent === "external") {
+      const entriesResult = await loadExternalCacheEntries(repoRoot);
+      if (!entriesResult.ok) return entriesResult;
+
+      for (const entry of entriesResult.value) {
+        const readResult = await readCache(entry.file);
+        if (!readResult.ok) continue;
+        const parseResult = ExternalCacheFileSchema.safeParse(readResult.value);
+        if (!parseResult.success) continue;
+        candidates.push({ entry, content: parseResult.data, file: entry.file });
+      }
+    } else {
+      const localPath = resolveLocalCachePath(repoRoot);
+      const readResult = await readCache(localPath);
+      if (!readResult.ok) return readResult;
+
+      const parseResult = LocalCacheFileSchema.safeParse(readResult.value);
+      if (!parseResult.success) {
+        return { ok: false, error: `Malformed local cache file: ${localPath}`, code: ErrorCode.PARSE_ERROR };
+      }
+      const data = parseResult.data;
+      const entry: CacheEntry = {
+        file: localPath,
+        agent: "local",
+        subject: data.topic ?? "local",
+        description: data.description,
+        fetched_at: data.timestamp ?? "",
+      };
+      candidates.push({ entry, content: data, file: localPath });
+    }
+
+    if (candidates.length === 0) {
+      return { ok: false, error: `No cache entries found for agent "${args.agent}"`, code: ErrorCode.FILE_NOT_FOUND };
+    }
+
+    // Score all candidates
+    const keywords = [args.subject];
+    const scored = candidates.map((c) => ({
+      ...c,
+      score: scoreEntry(c.entry, keywords),
+    }));
+
+    // Filter out zero-score entries
+    const matched = scored.filter((s) => s.score > 0);
+
+    if (matched.length === 0) {
+      return { ok: false, error: `No cache entry matched keyword "${args.subject}"`, code: ErrorCode.FILE_NOT_FOUND };
+    }
+
+    // Sort by score descending
+    matched.sort((a, b) => b.score - a.score);
+
+    const top = matched[0]!;
+    const second = matched[1];
+
+    if (second && top.score === second.score) {
+      return {
+        ok: false,
+        error: `Ambiguous match: multiple entries scored equally for "${args.subject}"`,
+        code: ErrorCode.AMBIGUOUS_MATCH,
+      };
+    }
+
+    if (args.agent === "local") {
+      // Destructure to strip tracked_files (internal operational metadata, never exposed
+      // to callers) and to extract facts for filtering. All other fields — including
+      // global_facts, topic, description, timestamp, cache_miss_reason — flow through
+      // via ...rest and are always included in the response.
+      const { tracked_files: _dropped, facts, ...rest } = top.content as LocalCacheFile;
+
+      // Step 1 — folder filter: keep only entries under the specified folder prefix.
+      let filteredFacts = facts;
+      if (filteredFacts !== undefined && args.folder !== undefined) {
+        const normalizedFolder = args.folder.replace(/\\/g, "/").replace(/\/+$/, "");
+        filteredFacts = Object.fromEntries(
+          Object.entries(filteredFacts).filter(([key]) => {
+            const normalizedPath = key.replace(/\\/g, "/");
+            return (
+              normalizedPath === normalizedFolder ||
+              normalizedPath.startsWith(normalizedFolder + "/")
+            );
+          }),
+        );
+      }
+
+      // Step 2 — path keyword filter (existing --filter logic applied to already-folder-filtered set).
+      if (filteredFacts !== undefined) {
+        filteredFacts = filterFacts(filteredFacts, args.filter ?? []);
+      }
+
+      // Step 3 — search-facts filter: keep entries where any fact string contains any keyword.
+      if (filteredFacts !== undefined && args.searchFacts !== undefined) {
+        const kwsLower = args.searchFacts.map((k) => k.toLowerCase());
+        filteredFacts = Object.fromEntries(
+          Object.entries(filteredFacts).filter(([, factStrings]) =>
+            factStrings.some((f) => kwsLower.some((kw) => f.toLowerCase().includes(kw))),
+          ),
+        );
+      }
+
+      return {
+        ok: true,
+        value: {
+          ...rest,
+          ...(filteredFacts !== undefined ? { facts: filteredFacts } : {}),
+          file: top.file,
+          agent: args.agent,
+          // The cast is safe: tracked_files is intentionally stripped from the local
+          // response. LocalCacheFile uses z.looseObject so the runtime shape is valid;
+          // the static type just cannot express the intentional omission without a
+          // separate type definition.
+        } as unknown as InspectResult["value"],
+      };
+    }
+
+    return {
+      ok: true,
+      value: {
+        ...top.content,
+        file: top.file,
+        agent: args.agent,
+      },
+    };
+  } catch (err) {
+    const error = err as Error;
+    return { ok: false, error: error.message, code: ErrorCode.UNKNOWN };
+  }
+}

package/src/commands/install.ts

@@ -0,0 +1,13 @@
+import path from "node:path";
+
+import { installOpenCodeIntegration, resolveOpenCodeConfigDir } from "../files/openCodeInstaller.js";
+import type { InstallArgs, InstallResult } from "../types/commands.js";
+import type { Result } from "../types/result.js";
+
+export async function installCommand(
+  args: InstallArgs,
+  packageRoot: string = path.resolve(import.meta.dir, "../.."),
+): Promise<Result<InstallResult>> {
+  const configDir = resolveOpenCodeConfigDir(args.configDir);
+  return installOpenCodeIntegration(configDir, packageRoot);
+}

package/src/commands/invalidate.ts

@@ -0,0 +1,53 @@
+import { findRepoRoot, listCacheFiles, writeCache, readCache } from "../cache/cacheManager.js";
+import { resolveTopExternalMatch } from "../cache/externalCache.js";
+import { resolveLocalCachePath } from "../cache/localCache.js";
+import { ErrorCode, type Result } from "../types/result.js";
+import type { InvalidateArgs, InvalidateResult } from "../types/commands.js";
+import { validateSubject } from "../utils/validate.js";
+
+export async function invalidateCommand(args: InvalidateArgs): Promise<Result<InvalidateResult["value"]>> {
+  try {
+    const repoRoot = await findRepoRoot(process.cwd());
+    const invalidated: string[] = [];
+
+    if (args.agent === "external") {
+      let filesToInvalidate: string[];
+
+      if (args.subject) {
+        const subjectCheck = validateSubject(args.subject);
+        if (!subjectCheck.ok) return subjectCheck;
+        const matchResult = await resolveTopExternalMatch(repoRoot, args.subject);
+        if (!matchResult.ok) return matchResult;
+        filesToInvalidate = [matchResult.value];
+      } else {
+        const filesResult = await listCacheFiles("external", repoRoot);
+        if (!filesResult.ok) return filesResult;
+        filesToInvalidate = filesResult.value;
+      }
+
+      for (const filePath of filesToInvalidate) {
+        const writeResult = await writeCache(filePath, { fetched_at: "" });
+        if (!writeResult.ok) return writeResult;
+        invalidated.push(filePath);
+      }
+    } else {
+      // local — only invalidate if the file already exists
+      const localPath = resolveLocalCachePath(repoRoot);
+      const readResult = await readCache(localPath);
+      if (!readResult.ok) {
+        if (readResult.code === ErrorCode.FILE_NOT_FOUND) {
+          return { ok: false, error: `Local cache file not found: ${localPath}`, code: ErrorCode.FILE_NOT_FOUND };
+        }
+        return readResult;
+      }
+      const writeResult = await writeCache(localPath, { timestamp: "" });
+      if (!writeResult.ok) return writeResult;
+      invalidated.push(localPath);
+    }
+
+    return { ok: true, value: { invalidated } };
+  } catch (err) {
+    const error = err as Error;
+    return { ok: false, error: error.message, code: ErrorCode.UNKNOWN };
+  }
+}

package/src/commands/list.ts

@@ -0,0 +1,83 @@
+import { findRepoRoot, loadExternalCacheEntries, readCache } from "../cache/cacheManager.js";
+import { getAgeHuman } from "../cache/externalCache.js";
+import { resolveLocalCachePath } from "../cache/localCache.js";
+import { checkFilesCommand } from "./checkFiles.js";
+import { LocalCacheFileSchema } from "../types/cache.js";
+import { ErrorCode, type Result } from "../types/result.js";
+import type { ListArgs, ListEntry, ListResult } from "../types/commands.js";
+
+const MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+function isEntryStale(fetchedAt: string): boolean {
+  if (!fetchedAt) return true;
+  return Date.now() - new Date(fetchedAt).getTime() > MAX_AGE_MS;
+}
+
+export async function listCommand(args: ListArgs): Promise<Result<ListResult["value"]>> {
+  try {
+    const repoRoot = await findRepoRoot(process.cwd());
+    const agent = args.agent ?? "all";
+    const entries: ListEntry[] = [];
+
+    if (agent === "external" || agent === "all") {
+      const entriesResult = await loadExternalCacheEntries(repoRoot);
+      if (!entriesResult.ok) return entriesResult;
+
+      for (const entry of entriesResult.value) {
+        entries.push({
+          file: entry.file,
+          agent: "external",
+          subject: entry.subject,
+          ...(entry.description !== undefined ? { description: entry.description } : {}),
+          fetched_at: entry.fetched_at,
+          age_human: getAgeHuman(entry.fetched_at),
+          is_stale: isEntryStale(entry.fetched_at),
+        });
+      }
+    }
+
+    if (agent === "local" || agent === "all") {
+      const localPath = resolveLocalCachePath(repoRoot);
+      const readResult = await readCache(localPath);
+
+      if (readResult.ok) {
+        const parseResult = LocalCacheFileSchema.safeParse(readResult.value);
+        if (parseResult.success) {
+          const data = parseResult.data;
+          const timestamp = data.timestamp ?? "";
+          const description = data.description;
+
+          const checkResult = await checkFilesCommand();
+          if (!checkResult.ok) {
+            process.stderr.write(
+              `[cache-ctrl] Warning: could not compute local cache staleness: ${checkResult.error}\n`,
+            );
+          }
+          // Local entry is stale if:
+          //   1. The timestamp has been zeroed (entry was invalidated), OR
+          //   2. check-files reports changed files
+          const isStale = !timestamp || !checkResult.ok || checkResult.value.status === "changed";
+
+          entries.push({
+            file: localPath,
+            agent: "local",
+            subject: data.topic ?? "local",
+            ...(description !== undefined ? { description } : {}),
+            fetched_at: timestamp,
+            age_human: getAgeHuman(timestamp),
+            is_stale: isStale,
+          });
+        } else {
+          process.stderr.write(`[cache-ctrl] Warning: malformed local cache file: ${localPath}\n`);
+        }
+      } else if (readResult.code !== ErrorCode.FILE_NOT_FOUND) {
+        return readResult;
+      }
+    }
+
+    return { ok: true, value: entries };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: msg, code: ErrorCode.UNKNOWN };
+  }
+}

package/src/commands/prune.ts

@@ -0,0 +1,110 @@
+import { unlink } from "node:fs/promises";
+import { findRepoRoot, listCacheFiles, writeCache, readCache } from "../cache/cacheManager.js";
+import { isExternalStale } from "../cache/externalCache.js";
+import { resolveLocalCachePath } from "../cache/localCache.js";
+import { ExternalCacheFileSchema } from "../types/cache.js";
+import { ErrorCode, type Result } from "../types/result.js";
+import type { PruneArgs, PruneResult } from "../types/commands.js";
+import { getFileStem } from "../utils/fileStem.js";
+
+export function parseDurationMs(duration: string): number | null {
+  const match = /^(\d+)(h|d)$/.exec(duration);
+  if (!match) return null;
+  const value = parseInt(match[1]!, 10);
+  const unit = match[2]!;
+  if (unit === "h") return value * 3_600_000;
+  if (unit === "d") return value * 86_400_000;
+  return null;
+}
+
+export async function pruneCommand(args: PruneArgs): Promise<Result<PruneResult["value"]>> {
+  try {
+    const repoRoot = await findRepoRoot(process.cwd());
+    const agent = args.agent ?? "all";
+    const doDelete = args.delete ?? false;
+    const matched: Array<{ file: string; agent: "external" | "local"; subject: string }> = [];
+
+    // Parse maxAge for external (default 24h)
+    const externalMaxAgeMs = args.maxAge ? parseDurationMs(args.maxAge) : 24 * 3_600_000;
+    if (args.maxAge && externalMaxAgeMs === null) {
+      return { ok: false, error: `Invalid duration format: "${args.maxAge}". Use format like "24h" or "7d"`, code: ErrorCode.INVALID_ARGS };
+    }
+
+    if (agent === "external" || agent === "all") {
+      const filesResult = await listCacheFiles("external", repoRoot);
+      if (!filesResult.ok) return filesResult;
+
+      for (const filePath of filesResult.value) {
+        const readResult = await readCache(filePath);
+        if (!readResult.ok) continue;
+
+        const parseResult = ExternalCacheFileSchema.safeParse(readResult.value);
+        if (!parseResult.success) continue;
+        const data = parseResult.data;
+
+        if (isExternalStale(data, externalMaxAgeMs ?? undefined)) {
+          const stem = getFileStem(filePath);
+          const subject = data.subject ?? stem;
+          matched.push({ file: filePath, agent: "external", subject });
+          if (doDelete) {
+            try {
+              await unlink(filePath);
+            } catch (err) {
+              const error = err as NodeJS.ErrnoException;
+              if (error.code !== "ENOENT") {
+                return { ok: false, error: `Failed to delete ${filePath}: ${error.message}`, code: ErrorCode.FILE_WRITE_ERROR };
+              }
+            }
+          } else {
+            const writeResult = await writeCache(filePath, { fetched_at: "" });
+            if (!writeResult.ok) return writeResult;
+          }
+        }
+      }
+    }
+
+    if (agent === "local" || agent === "all") {
+      // Local always matches (age 0 rule)
+      const localPath = resolveLocalCachePath(repoRoot);
+
+      if (doDelete) {
+        try {
+          await unlink(localPath);
+          matched.push({ file: localPath, agent: "local", subject: "local" });
+        } catch (err) {
+          const error = err as NodeJS.ErrnoException;
+          if (error.code !== "ENOENT") {
+            return { ok: false, error: `Failed to delete ${localPath}: ${error.message}`, code: ErrorCode.FILE_WRITE_ERROR };
+          }
+          // File didn't exist — nothing pruned, don't add to matched
+        }
+      } else {
+        // Only invalidate if the file already exists
+        const readResult = await readCache(localPath);
+        if (!readResult.ok) {
+          if (readResult.code === ErrorCode.FILE_NOT_FOUND) {
+            // Nothing to prune — skip silently
+          } else {
+            return readResult;
+          }
+        } else {
+          const writeResult = await writeCache(localPath, { timestamp: "" });
+          if (!writeResult.ok) return writeResult;
+          matched.push({ file: localPath, agent: "local", subject: "local" });
+        }
+      }
+    }
+
+    return {
+      ok: true,
+      value: {
+        matched,
+        action: doDelete ? "deleted" : "invalidated",
+        count: matched.length,
+      },
+    };
+  } catch (err) {
+    const error = err as Error;
+    return { ok: false, error: error.message, code: ErrorCode.UNKNOWN };
+  }
+}

package/src/commands/search.ts

@@ -0,0 +1,57 @@
+import { findRepoRoot, loadExternalCacheEntries, readCache } from "../cache/cacheManager.js";
+import { resolveLocalCachePath } from "../cache/localCache.js";
+import { rankResults } from "../search/keywordSearch.js";
+import type { CacheEntry } from "../types/cache.js";
+import { LocalCacheFileSchema } from "../types/cache.js";
+import { ErrorCode, type Result } from "../types/result.js";
+import type { SearchArgs, SearchResult } from "../types/commands.js";
+
+export async function searchCommand(args: SearchArgs): Promise<Result<SearchResult["value"]>> {
+  try {
+    const repoRoot = await findRepoRoot(process.cwd());
+    const entries: CacheEntry[] = [];
+
+    // Collect external entries
+    const externalEntriesResult = await loadExternalCacheEntries(repoRoot);
+    if (!externalEntriesResult.ok) return externalEntriesResult;
+    entries.push(...externalEntriesResult.value);
+
+    // Collect local entry
+    const localPath = resolveLocalCachePath(repoRoot);
+    const localReadResult = await readCache(localPath);
+    if (localReadResult.ok) {
+      const parseResult = LocalCacheFileSchema.safeParse(localReadResult.value);
+      if (parseResult.success) {
+        const data = parseResult.data;
+        entries.push({
+          file: localPath,
+          agent: "local",
+          subject: data.topic ?? "local",
+          description: data.description,
+          fetched_at: data.timestamp ?? "",
+        });
+      } else {
+        process.stderr.write(`[cache-ctrl] Warning: malformed local cache file: ${localPath}\n`);
+      }
+    } else if (localReadResult.code !== ErrorCode.FILE_NOT_FOUND) {
+      process.stderr.write(`[cache-ctrl] Warning: could not read local cache: ${localReadResult.error}\n`);
+    }
+
+    const ranked = rankResults(entries, args.keywords);
+
+    return {
+      ok: true,
+      value: ranked.map((entry) => ({
+        file: entry.file,
+        subject: entry.subject,
+        ...(entry.description !== undefined ? { description: entry.description } : {}),
+        agent: entry.agent,
+        fetched_at: entry.fetched_at,
+        score: entry.score ?? 0,
+      })),
+    };
+  } catch (err) {
+    const error = err as Error;
+    return { ok: false, error: error.message, code: ErrorCode.UNKNOWN };
+  }
+}