@thecat69/cache-ctrl 1.0.0 → 1.2.0

package/src/commands/graph.ts

@@ -0,0 +1,131 @@
+import { computePageRank } from "../analysis/pageRank.js";
+import { findRepoRoot, readCache } from "../cache/cacheManager.js";
+import { resolveGraphCachePath } from "../cache/graphCache.js";
+import { GraphCacheFileSchema } from "../types/cache.js";
+import { ErrorCode, type Result } from "../types/result.js";
+import type { DependencyGraph } from "../analysis/graphBuilder.js";
+import type { GraphArgs, GraphResult } from "../types/commands.js";
+import { toUnknownResult } from "../utils/errors.js";
+
+interface RankedFileEntry {
+  path: string;
+  rank: number;
+  deps: string[];
+  defs: string[];
+  ref_count: number;
+}
+
+function estimateEntryTokens(entry: RankedFileEntry): number {
+  return Math.ceil(JSON.stringify(entry).length / 4);
+}
+
+function countReferences(graph: DependencyGraph): Map<string, number> {
+  const refCounts = new Map<string, number>();
+
+  for (const nodePath of graph.keys()) {
+    refCounts.set(nodePath, 0);
+  }
+
+  for (const graphNode of graph.values()) {
+    const uniqueDeps = new Set(graphNode.deps);
+    for (const depPath of uniqueDeps) {
+      if (!refCounts.has(depPath)) {
+        continue;
+      }
+      const currentCount = refCounts.get(depPath) ?? 0;
+      refCounts.set(depPath, currentCount + 1);
+    }
+  }
+
+  return refCounts;
+}
+
+/**
+ * Returns a token-budgeted, PageRank-ranked projection of the dependency graph cache.
+ *
+ * @param args - {@link GraphArgs} command arguments.
+ * @returns Promise<Result<GraphResult["value"]>>; common failures include FILE_NOT_FOUND,
+ * PARSE_ERROR, FILE_READ_ERROR, and UNKNOWN.
+ */
+export async function graphCommand(args: GraphArgs): Promise<Result<GraphResult["value"]>> {
+  try {
+    const repoRoot = await findRepoRoot(process.cwd());
+    const graphPath = resolveGraphCachePath(repoRoot);
+
+    const readResult = await readCache(graphPath);
+    if (!readResult.ok) {
+      if (readResult.code === ErrorCode.FILE_NOT_FOUND) {
+        return {
+          ok: false,
+          error:
+            "graph.json not found — run 'cache-ctrl watch' or wait for the background daemon to compute the graph",
+          code: ErrorCode.FILE_NOT_FOUND,
+        };
+      }
+      return readResult;
+    }
+
+    const parseResult = GraphCacheFileSchema.safeParse(readResult.value);
+    if (!parseResult.success) {
+      return {
+        ok: false,
+        error: `Malformed graph cache file: ${graphPath}`,
+        code: ErrorCode.PARSE_ERROR,
+      };
+    }
+
+    const parsed = parseResult.data;
+    const graph: DependencyGraph = new Map(
+      Object.entries(parsed.files).map(([nodePath, node]) => [
+        nodePath,
+        {
+          deps: node.deps,
+          defs: node.defs,
+        },
+      ]),
+    );
+
+    const refCounts = countReferences(graph);
+    const ranks = computePageRank(graph, {
+      ...(args.seed !== undefined ? { seedFiles: args.seed } : {}),
+    });
+
+    const rankedEntries = [...ranks.entries()]
+      .map(([nodePath, rank]): RankedFileEntry => {
+        const node = graph.get(nodePath);
+        return {
+          path: nodePath,
+          rank,
+          deps: node?.deps ?? [],
+          defs: node?.defs ?? [],
+          ref_count: refCounts.get(nodePath) ?? 0,
+        };
+      })
+      .sort((a, b) => b.rank - a.rank);
+
+    const tokenBudget = Math.max(64, Math.min(args.maxTokens ?? 1024, 128_000));
+    let tokenEstimate = 0;
+    const budgetedEntries: RankedFileEntry[] = [];
+
+    for (const entry of rankedEntries) {
+      const estimatedTokens = estimateEntryTokens(entry);
+      if (tokenEstimate + estimatedTokens > tokenBudget) {
+        break;
+      }
+      budgetedEntries.push(entry);
+      tokenEstimate += estimatedTokens;
+    }
+
+    return {
+      ok: true,
+      value: {
+        ranked_files: budgetedEntries,
+        total_files: graph.size,
+        computed_at: parsed.computed_at,
+        token_estimate: tokenEstimate,
+      },
+    };
+  } catch (err) {
+    return toUnknownResult(err);
+  }
+}

package/src/commands/inspect.ts

@@ -1,184 +1,16 @@
-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))),
-  );
-}
-
+import { inspectExternalCommand } from "./inspectExternal.js";
+import { inspectLocalCommand } from "./inspectLocal.js";
+import type { Result } from "../types/result.js";
+
+/**
+ * Routes inspect requests to the agent-specific implementation.
+ *
+ * @param args - {@link InspectArgs} command arguments.
+ * @returns Promise<Result<InspectResult["value"]>>; may return INVALID_ARGS,
+ * FILE_NOT_FOUND, AMBIGUOUS_MATCH, PARSE_ERROR, or UNKNOWN.
+ */
 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 };
-  }
+  if (args.agent === "local") return inspectLocalCommand(args);
+  return inspectExternalCommand(args);
 }

package/src/commands/inspectExternal.ts

@@ -0,0 +1,79 @@
+import { findRepoRoot, loadExternalCacheEntries, readCache } from "../cache/cacheManager.js";
+import { scoreEntry } from "../search/keywordSearch.js";
+import type { CacheEntry, ExternalCacheFile } from "../types/cache.js";
+import type { InspectArgs, InspectResult } from "../types/commands.js";
+import { ExternalCacheFileSchema } from "../types/cache.js";
+import { ErrorCode, type Result } from "../types/result.js";
+import { toUnknownResult } from "../utils/errors.js";
+
+/**
+ * Inspects the best-matching external cache entry by subject keyword.
+ *
+ * @param args - {@link InspectArgs} with `agent: "external"`.
+ * @returns Promise<Result<InspectResult["value"]>>; common failures include INVALID_ARGS,
+ * FILE_NOT_FOUND, AMBIGUOUS_MATCH, PARSE_ERROR, and UNKNOWN.
+ */
+export async function inspectExternalCommand(args: InspectArgs): Promise<Result<InspectResult["value"]>> {
+  try {
+    if (args.folder !== undefined) {
+      return {
+        ok: false,
+        error: "--folder is only supported for local cache",
+        code: ErrorCode.INVALID_ARGS,
+      };
+    }
+
+    const repoRoot = await findRepoRoot(process.cwd());
+    const entriesResult = await loadExternalCacheEntries(repoRoot);
+    if (!entriesResult.ok) return entriesResult;
+
+    const candidates: Array<{ entry: CacheEntry; content: ExternalCacheFile; file: string }> = [];
+
+    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 });
+    }
+
+    if (candidates.length === 0) {
+      return { ok: false, error: `No cache entries found for agent "${args.agent}"`, code: ErrorCode.FILE_NOT_FOUND };
+    }
+
+    const keywords = [args.subject];
+    const scored = candidates.map((candidate) => ({
+      ...candidate,
+      score: scoreEntry(candidate.entry, keywords),
+    }));
+    const matched = scored.filter((candidate) => candidate.score > 0);
+
+    if (matched.length === 0) {
+      return { ok: false, error: `No cache entry matched keyword "${args.subject}"`, code: ErrorCode.FILE_NOT_FOUND };
+    }
+
+    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,
+      };
+    }
+
+    return {
+      ok: true,
+      value: {
+        ...top.content,
+        file: top.file,
+        agent: args.agent,
+      },
+    };
+  } catch (err) {
+    return toUnknownResult(err);
+  }
+}

package/src/commands/inspectLocal.ts

@@ -0,0 +1,134 @@
+import { normalize } from "node:path";
+
+import { findRepoRoot, readCache } from "../cache/cacheManager.js";
+import { resolveLocalCachePath } from "../cache/localCache.js";
+import { scoreEntry } from "../search/keywordSearch.js";
+import type { CacheEntry, FileFacts } from "../types/cache.js";
+import type { InspectArgs, InspectResult } from "../types/commands.js";
+import { LocalCacheFileSchema } from "../types/cache.js";
+import { ErrorCode, type Result } from "../types/result.js";
+import { toUnknownResult } from "../utils/errors.js";
+
+function filterFacts(
+  facts: Record<string, FileFacts>,
+  keywords: string[],
+): Record<string, FileFacts> {
+  if (keywords.length === 0) return facts;
+  const lowerKeywords = keywords.map((keyword) => keyword.toLowerCase());
+  return Object.fromEntries(
+    Object.entries(facts).filter(([path]) => lowerKeywords.some((keyword) => path.toLowerCase().includes(keyword))),
+  );
+}
+
+function normalizeFolderArg(folder: string): Result<string> {
+  const normalizedFolder = 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,
+    };
+  }
+
+  return { ok: true, value: normalizedFolder };
+}
+
+/**
+ * Inspects local context cache content with optional path/fact filters.
+ *
+ * @param args - {@link InspectArgs} with `agent: "local"`.
+ * @returns Promise<Result<InspectResult["value"]>>; common failures include INVALID_ARGS,
+ * FILE_NOT_FOUND, PARSE_ERROR, and UNKNOWN.
+ */
+export async function inspectLocalCommand(args: InspectArgs): Promise<Result<InspectResult["value"]>> {
+  try {
+    let normalizedFolder: string | undefined;
+    if (args.folder !== undefined) {
+      const folderResult = normalizeFolderArg(args.folder);
+      if (!folderResult.ok) return folderResult;
+      normalizedFolder = folderResult.value;
+    }
+
+    const repoRoot = await findRepoRoot(process.cwd());
+    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 ?? "",
+    };
+
+    const scored = [
+      {
+        entry,
+        content: data,
+        file: localPath,
+        score: scoreEntry(entry, [args.subject]),
+      },
+    ];
+    const matched = scored.filter((candidate) => candidate.score > 0);
+
+    if (matched.length === 0) {
+      return { ok: false, error: `No cache entry matched keyword "${args.subject}"`, code: ErrorCode.FILE_NOT_FOUND };
+    }
+
+    const top = matched[0]!;
+    const { tracked_files: _dropped, facts, ...rest } = top.content;
+
+    let filteredFacts = facts;
+    if (filteredFacts !== undefined && normalizedFolder !== undefined) {
+      filteredFacts = Object.fromEntries(
+        Object.entries(filteredFacts).filter(([key]) => {
+          const normalizedPath = key.replace(/\\/g, "/");
+          return normalizedPath === normalizedFolder || normalizedPath.startsWith(normalizedFolder + "/");
+        }),
+      );
+    }
+
+    if (filteredFacts !== undefined) {
+      filteredFacts = filterFacts(filteredFacts, args.filter ?? []);
+    }
+
+    if (filteredFacts !== undefined && args.searchFacts !== undefined) {
+      const loweredKeywords = args.searchFacts.map((keyword) => keyword.toLowerCase());
+      filteredFacts = Object.fromEntries(
+        Object.entries(filteredFacts).filter(([, factEntry]) =>
+          (factEntry.facts ?? []).some((fact) => loweredKeywords.some((keyword) => fact.toLowerCase().includes(keyword))),
+        ),
+      );
+    }
+
+    const resultValue: InspectResult["value"] = {
+      ...rest,
+      ...(filteredFacts !== undefined ? { facts: filteredFacts } : {}),
+      file: top.file,
+      agent: args.agent,
+    };
+
+    return {
+      ok: true,
+      value: resultValue,
+    };
+  } catch (err) {
+    return toUnknownResult(err);
+  }
+}

package/src/commands/install.ts

@@ -4,6 +4,12 @@ import { installOpenCodeIntegration, resolveOpenCodeConfigDir } from "../files/o
 import type { InstallArgs, InstallResult } from "../types/commands.js";
 import type { Result } from "../types/result.js";
 
+/**
+ * Installs OpenCode tool wrapper and bundled skill files.
+ *
+ * @param args - {@link InstallArgs} command arguments.
+ * @returns Promise<Result<InstallResult>>; common failures include FILE_WRITE_ERROR and UNKNOWN.
+ */
 export async function installCommand(
   args: InstallArgs,
   packageRoot: string = path.resolve(import.meta.dir, "../.."),

package/src/commands/invalidate.ts

@@ -1,35 +1,27 @@
-import { findRepoRoot, listCacheFiles, writeCache, readCache } from "../cache/cacheManager.js";
-import { resolveTopExternalMatch } from "../cache/externalCache.js";
+import { findRepoRoot, writeCache, readCache } from "../cache/cacheManager.js";
+import { updateExternalFetchedAt } from "../cache/externalCache.js";
+import { resolveGraphCachePath } from "../cache/graphCache.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";
+import { toUnknownResult } from "../utils/errors.js";
 
+/**
+ * Marks cache entries stale by zeroing their freshness timestamps.
+ *
+ * @param args - {@link InvalidateArgs} command arguments.
+ * @returns Promise<Result<InvalidateResult["value"]>>; common failures include INVALID_ARGS,
+ * NO_MATCH, FILE_NOT_FOUND, FILE_WRITE_ERROR, and UNKNOWN.
+ */
 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);
-      }
+      const updateResult = await updateExternalFetchedAt(repoRoot, args.subject, "");
+      if (!updateResult.ok) return updateResult;
+      invalidated.push(...updateResult.value);
     } else {
       // local — only invalidate if the file already exists
       const localPath = resolveLocalCachePath(repoRoot);
@@ -43,11 +35,19 @@ export async function invalidateCommand(args: InvalidateArgs): Promise<Result<In
       const writeResult = await writeCache(localPath, { timestamp: "" });
       if (!writeResult.ok) return writeResult;
       invalidated.push(localPath);
+
+      const graphPath = resolveGraphCachePath(repoRoot);
+      const graphReadResult = await readCache(graphPath);
+      if (graphReadResult.ok) {
+        const graphWriteResult = await writeCache(graphPath, { computed_at: "" });
+        if (!graphWriteResult.ok) return graphWriteResult;
+      } else if (graphReadResult.code !== ErrorCode.FILE_NOT_FOUND) {
+        return graphReadResult;
+      }
     }
 
     return { ok: true, value: { invalidated } };
   } catch (err) {
-    const error = err as Error;
-    return { ok: false, error: error.message, code: ErrorCode.UNKNOWN };
+    return toUnknownResult(err);
   }
 }

package/src/commands/list.ts

@@ -1,18 +1,19 @@
 import { findRepoRoot, loadExternalCacheEntries, readCache } from "../cache/cacheManager.js";
-import { getAgeHuman } from "../cache/externalCache.js";
+import { getAgeHuman, isFetchedAtStale } 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 { toUnknownResult } from "../utils/errors.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;
-}
-
+/**
+ * Lists cache entries for external and/or local namespaces.
+ *
+ * @param args - {@link ListArgs} command arguments.
+ * @returns Promise<Result<ListResult["value"]>>; common failures include FILE_READ_ERROR,
+ * FILE_NOT_FOUND, PARSE_ERROR, and UNKNOWN.
+ */
 export async function listCommand(args: ListArgs): Promise<Result<ListResult["value"]>> {
   try {
     const repoRoot = await findRepoRoot(process.cwd());
@@ -31,7 +32,7 @@ export async function listCommand(args: ListArgs): Promise<Result<ListResult["va
           ...(entry.description !== undefined ? { description: entry.description } : {}),
           fetched_at: entry.fetched_at,
           age_human: getAgeHuman(entry.fetched_at),
-          is_stale: isEntryStale(entry.fetched_at),
+          is_stale: isFetchedAtStale(entry.fetched_at),
         });
       }
     }
@@ -77,7 +78,6 @@ export async function listCommand(args: ListArgs): Promise<Result<ListResult["va
 
     return { ok: true, value: entries };
   } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return { ok: false, error: msg, code: ErrorCode.UNKNOWN };
+    return toUnknownResult(err);
   }
 }