@thecat69/cache-ctrl 1.0.0 → 1.2.0

package/src/index.ts

@@ -5,12 +5,19 @@ import { flushCommand } from "./commands/flush.js";
 import { invalidateCommand } from "./commands/invalidate.js";
 import { touchCommand } from "./commands/touch.js";
 import { pruneCommand } from "./commands/prune.js";
-import { checkFreshnessCommand } from "./commands/checkFreshness.js";
 import { checkFilesCommand } from "./commands/checkFiles.js";
 import { searchCommand } from "./commands/search.js";
-import { writeCommand } from "./commands/write.js";
+import { writeLocalCommand } from "./commands/writeLocal.js";
+import { writeExternalCommand } from "./commands/writeExternal.js";
 import { installCommand } from "./commands/install.js";
+import { updateCommand } from "./commands/update.js";
+import { uninstallCommand } from "./commands/uninstall.js";
+import { graphCommand } from "./commands/graph.js";
+import { mapCommand } from "./commands/map.js";
+import { watchCommand } from "./commands/watch.js";
+import { versionCommand } from "./commands/version.js";
 import { ErrorCode } from "./types/result.js";
+import { toUnknownResult } from "./utils/errors.js";
 
 type CommandName =
   | "list"
@@ -19,11 +26,17 @@ type CommandName =
   | "invalidate"
   | "touch"
   | "prune"
-  | "check-freshness"
   | "check-files"
   | "search"
-  | "write"
-  | "install";
+  | "write-local"
+  | "write-external"
+  | "install"
+  | "update"
+  | "uninstall"
+  | "graph"
+  | "map"
+  | "watch"
+  | "version";
 
 function isKnownCommand(cmd: string): cmd is CommandName {
   return Object.hasOwn(COMMAND_HELP as Record<string, unknown>, cmd);
@@ -118,19 +131,6 @@ const COMMAND_HELP: Record<CommandName, CommandHelp> = {
       "    --delete                     Actually delete the stale entries (dry-run if omitted)",
     ].join("\n"),
   },
-  "check-freshness": {
-    usage: "check-freshness <subject-keyword> [--url <url>]",
-    description: "Send HTTP HEAD requests to verify source freshness",
-    details: [
-      "  Arguments:",
-      "    <subject-keyword>   Keyword identifying the cache entry to check",
-      "",
-      "  Options:",
-      "    --url <url>   Override the URL used for the HEAD request",
-      "",
-      "  Output: HTTP response metadata and freshness verdict.",
-    ].join("\n"),
-  },
   "check-files": {
     usage: "check-files",
     description: "Compare tracked local files against stored mtime/hash",
@@ -152,13 +152,25 @@ const COMMAND_HELP: Record<CommandName, CommandHelp> = {
       "  Output: Ranked list of matching cache entries.",
     ].join("\n"),
   },
-  write: {
-    usage: "write <agent> [subject] --data '<json>'",
-    description: "Write a validated cache entry from JSON",
+  "write-local": {
+    usage: "write-local --data '<json>'",
+    description: "Write a validated local cache entry",
+    details: [
+      "  Arguments:",
+      "    (none)",
+      "",
+      "  Options:",
+      "    --data '<json>'   JSON string containing the cache entry payload",
+      "",
+      "  Output: Confirmation with the written entry's key.",
+    ].join("\n"),
+  },
+  "write-external": {
+    usage: "write-external <subject> --data '<json>'",
+    description: "Write a validated external cache entry",
     details: [
       "  Arguments:",
-      "    <agent>     Agent type: external or local",
-      "    [subject]   Optional subject identifier (required for external agent)",
+      "    <subject>   Subject identifier for the external entry",
       "",
       "  Options:",
       "    --data '<json>'   JSON string containing the cache entry payload",
@@ -179,6 +191,84 @@ const COMMAND_HELP: Record<CommandName, CommandHelp> = {
       "  Output: JSON object describing installed tool/skill paths.",
     ].join("\n"),
   },
+  update: {
+    usage: "update [--config-dir <path>]",
+    description: "Update npm package globally and refresh OpenCode integration",
+    details: [
+      "  Arguments:",
+      "    (none)",
+      "",
+      "  Options:",
+      "    --config-dir <path>  Override the OpenCode config directory (default: platform-specific)",
+      "",
+      "  Output: JSON object with package update status, installed paths, and warnings.",
+    ].join("\n"),
+  },
+  uninstall: {
+    usage: "uninstall [--config-dir <path>]",
+    description: "Remove OpenCode integration files and uninstall global npm package",
+    details: [
+      "  Arguments:",
+      "    (none)",
+      "",
+      "  Options:",
+      "    --config-dir <path>  Override the OpenCode config directory (default: platform-specific)",
+      "",
+      "  Output: JSON object with removed paths, npm uninstall status, and warnings.",
+    ].join("\n"),
+  },
+  graph: {
+    usage: "graph [--max-tokens <number>] [--seed <path>[,<path>...]]",
+    description: "Return a PageRank-ranked dependency graph under a token budget",
+    details: [
+      "  Arguments:",
+      "    (none)",
+      "",
+      "  Options:",
+      "    --max-tokens <number>        Token budget for ranked_files output (default: 1024)",
+      "    --seed <path>[,<path>...]    Personalize rank toward specific file path(s)",
+      "                                 (repeat --seed to provide multiple values)",
+      "",
+      "  Output: Ranked files with deps, defs, and ref_count from graph.json.",
+    ].join("\n"),
+  },
+  map: {
+    usage: "map [--depth overview|modules|full] [--folder <path-prefix>]",
+    description: "Return a semantic map of local context.json",
+    details: [
+      "  Arguments:",
+      "    (none)",
+      "",
+      "  Options:",
+      "    --depth overview|modules|full   Output depth (default: overview)",
+      "    --folder <path-prefix>          Restrict map to files whose path starts with prefix",
+      "",
+      "  Output: JSON object with global_facts, files, optional modules, and total_files.",
+    ].join("\n"),
+  },
+  watch: {
+    usage: "watch [--verbose]",
+    description: "Watch for file changes and recompute the dependency graph",
+    details: [
+      "  Arguments:",
+      "    (none)",
+      "",
+      "  Options:",
+      "    --verbose   Log watcher lifecycle and rebuild events",
+      "",
+      "  Output: Long-running daemon process that updates graph.json on source changes.",
+    ].join("\n"),
+  },
+  version: {
+    usage: "version",
+    description: "Show the current cache-ctrl package version",
+    details: [
+      "  Arguments:",
+      "    (none)",
+      "",
+      "  Output: JSON object containing the current package version.",
+    ].join("\n"),
+  },
 };
 
 const GLOBAL_OPTIONS_SECTION = [
@@ -206,7 +296,7 @@ export function printHelp(command?: string): boolean {
       ...Object.values(COMMAND_HELP).map((h) => h.usage.length),
     );
 
-    for (const [, help] of Object.entries(COMMAND_HELP) as [CommandName, CommandHelp][]) {
+    for (const help of Object.values(COMMAND_HELP)) {
       const paddedUsage = help.usage.padEnd(maxUsageLen);
       lines.push(`  ${paddedUsage}   ${help.description}`);
     }
@@ -216,12 +306,12 @@ export function printHelp(command?: string): boolean {
     return true;
   }
 
-  const sanitized = command.replace(/[\x00-\x1F\x7F]/g, "");
-
   if (command === "help") {
     return printHelp();
   }
 
+  const sanitized = command.replace(/[\x00-\x1F\x7F]/g, "");
+
   if (!isKnownCommand(command)) {
     process.stderr.write(`Unknown command: "${sanitized}". Run 'cache-ctrl help' for available commands.\n`);
     return false;
@@ -257,6 +347,12 @@ function printError(error: { ok: false; error: string; code: string }, pretty: b
   }
 }
 
+/**
+ * Prints a structured usage error and terminates the process.
+ *
+ * @param message - Human-readable usage failure detail.
+ * @remarks Always exits with process code `2` to distinguish usage failures from runtime errors.
+ */
 function usageError(message: string): never {
   process.stderr.write(JSON.stringify({ ok: false, error: message, code: ErrorCode.INVALID_ARGS }) + "\n");
   process.exit(2);
@@ -265,8 +361,44 @@ function usageError(message: string): never {
 export { usageError };
 
 /** Flags that consume the following token as their value. Boolean flags must NOT appear here. */
-const VALUE_FLAGS = new Set(["data", "agent", "url", "max-age", "filter", "folder", "search-facts", "config-dir"]);
+const VALUE_FLAGS = new Set([
+  "data",
+  "agent",
+  "max-age",
+  "filter",
+  "folder",
+  "search-facts",
+  "config-dir",
+  "max-tokens",
+  "seed",
+  "depth",
+]);
+
+function collectFlagValues(argv: string[], flagName: string): string[] {
+  const values: string[] = [];
+
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] !== `--${flagName}`) {
+      continue;
+    }
+    const next = argv[i + 1];
+    if (next !== undefined) {
+      values.push(next);
+      i += 1;
+    }
+  }
+
+  return values;
+}
 
+/**
+ * Parses raw CLI argv tokens into positional args and flag key/value pairs.
+ *
+ * @param argv - Raw argument tokens (typically `process.argv.slice(2)`).
+ * @returns Parsed positional args and normalized flags map.
+ * @remarks Flags listed in `VALUE_FLAGS` consume the following token as their value;
+ * all other `--flag` tokens are treated as boolean flags.
+ */
 export function parseArgs(argv: string[]): { args: string[]; flags: Record<string, string | boolean> } {
   const positional: string[] = [];
   const flags: Record<string, string | boolean> = {};
@@ -305,7 +437,7 @@ async function main(): Promise<void> {
 
   const command = args[0];
   if (!command) {
-    usageError("Usage: cache-ctrl <command> [args]. Commands: list, inspect, flush, invalidate, touch, prune, check-freshness, check-files, search, write, install");
+    usageError("Usage: cache-ctrl <command> [args]. Commands: list, inspect, flush, invalidate, touch, prune, check-files, search, write-local, write-external, install, update, uninstall, graph, map, watch, version");
   }
 
   switch (command) {
@@ -456,13 +588,8 @@ async function main(): Promise<void> {
       break;
     }
 
-    case "check-freshness": {
-      const subject = args[1];
-      if (!subject) {
-        usageError("Usage: cache-ctrl check-freshness <subject-keyword> [--url <url>]");
-      }
-      const url = typeof flags.url === "string" ? flags.url : undefined;
-      const result = await checkFreshnessCommand({ subject, ...(url !== undefined ? { url } : {}) });
+    case "check-files": {
+      const result = await checkFilesCommand();
       if (result.ok) {
         printResult(result, pretty);
       } else {
@@ -472,8 +599,12 @@ async function main(): Promise<void> {
       break;
     }
 
-    case "check-files": {
-      const result = await checkFilesCommand();
+    case "search": {
+      const keywords = args.slice(1);
+      if (keywords.length === 0) {
+        usageError("Usage: cache-ctrl search <keyword> [<keyword>...]");
+      }
+      const result = await searchCommand({ keywords });
       if (result.ok) {
         printResult(result, pretty);
       } else {
@@ -483,12 +614,24 @@ async function main(): Promise<void> {
       break;
     }
 
-    case "search": {
-      const keywords = args.slice(1);
-      if (keywords.length === 0) {
-        usageError("Usage: cache-ctrl search <keyword> [<keyword>...]");
+    case "write-local": {
+      const dataStr = typeof flags.data === "string" ? flags.data : undefined;
+      if (!dataStr) {
+        usageError("Usage: cache-ctrl write-local --data '<json>'");
       }
-      const result = await searchCommand({ keywords });
+      let content: Record<string, unknown>;
+      try {
+        content = JSON.parse(dataStr) as Record<string, unknown>; // JSON.parse returns any; writeLocalCommand validates the payload shape via Zod before use.
+      } catch {
+        usageError("--data must be valid JSON");
+      }
+      if (typeof content !== "object" || content === null || Array.isArray(content)) {
+        usageError("--data must be a JSON object");
+      }
+      const result = await writeLocalCommand({
+        agent: "local",
+        content,
+      });
       if (result.ok) {
         printResult(result, pretty);
       } else {
@@ -498,28 +641,27 @@ async function main(): Promise<void> {
       break;
     }
 
-    case "write": {
-      const agent = args[1];
-      if (!agent) {
-        usageError("Usage: cache-ctrl write <agent> [subject] --data '<json>'");
-      }
-      if (agent !== "external" && agent !== "local") {
-        usageError(`Invalid agent: "${agent}". Must be external or local`);
+    case "write-external": {
+      const subject = args[1];
+      if (!subject) {
+        usageError("Usage: cache-ctrl write-external <subject> --data '<json>'");
       }
       const dataStr = typeof flags.data === "string" ? flags.data : undefined;
       if (!dataStr) {
-        usageError("Usage: cache-ctrl write <agent> [subject] --data '<json>'");
+        usageError("Usage: cache-ctrl write-external <subject> --data '<json>'");
       }
       let content: Record<string, unknown>;
       try {
-        content = JSON.parse(dataStr) as Record<string, unknown>;
+        content = JSON.parse(dataStr) as Record<string, unknown>; // JSON.parse returns any; writeExternalCommand validates the payload shape via Zod before use.
       } catch {
         usageError("--data must be valid JSON");
       }
-      const subject = agent === "external" ? args[2] : undefined;
-      const result = await writeCommand({
-        agent,
-        ...(subject !== undefined ? { subject } : {}),
+      if (typeof content !== "object" || content === null || Array.isArray(content)) {
+        usageError("--data must be a JSON object");
+      }
+      const result = await writeExternalCommand({
+        agent: "external",
+        subject,
         content,
       });
       if (result.ok) {
@@ -532,6 +674,9 @@ async function main(): Promise<void> {
     }
 
     case "install": {
+      if (flags["config-dir"] === true) {
+        usageError("--config-dir requires a value: --config-dir <path>");
+      }
       const configDir = typeof flags["config-dir"] === "string" ? flags["config-dir"] : undefined;
       const result = await installCommand({ ...(configDir !== undefined ? { configDir } : {}) });
       if (result.ok) {
@@ -543,15 +688,126 @@ async function main(): Promise<void> {
       break;
     }
 
+    case "update": {
+      if (flags["config-dir"] === true) {
+        usageError("--config-dir requires a value: --config-dir <path>");
+      }
+      const configDir = typeof flags["config-dir"] === "string" ? flags["config-dir"] : undefined;
+      const result = await updateCommand({ ...(configDir !== undefined ? { configDir } : {}) });
+      if (result.ok) {
+        printResult(result, pretty);
+      } else {
+        printError(result, pretty);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "uninstall": {
+      if (flags["config-dir"] === true) {
+        usageError("--config-dir requires a value: --config-dir <path>");
+      }
+      const configDir = typeof flags["config-dir"] === "string" ? flags["config-dir"] : undefined;
+      const result = await uninstallCommand({ ...(configDir !== undefined ? { configDir } : {}) });
+      if (result.ok) {
+        printResult(result, pretty);
+      } else {
+        printError(result, pretty);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "graph": {
+      if (flags["max-tokens"] === true) {
+        usageError("--max-tokens requires a numeric value");
+      }
+      const maxTokensRaw = typeof flags["max-tokens"] === "string" ? flags["max-tokens"] : undefined;
+      let maxTokensParsed: number | undefined;
+      if (maxTokensRaw !== undefined) {
+        const parsed = Number(maxTokensRaw);
+        if (!Number.isFinite(parsed) || parsed < 0) {
+          usageError(`Invalid --max-tokens value: "${maxTokensRaw}". Must be a non-negative number`);
+        }
+        maxTokensParsed = parsed;
+      }
+      if (flags.seed === true) {
+        usageError("--seed requires a value: --seed <path>[,<path>...]");
+      }
+      const seedFlagValues = collectFlagValues(rawArgs, "seed");
+      const seed = seedFlagValues
+        .flatMap((value) => value.split(","))
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0);
+
+      const result = await graphCommand({
+        ...(maxTokensParsed !== undefined ? { maxTokens: maxTokensParsed } : {}),
+        ...(seed.length > 0 ? { seed } : {}),
+      });
+      if (result.ok) {
+        printResult(result, pretty);
+      } else {
+        printError(result, pretty);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "map": {
+      if (flags.depth === true) {
+        usageError("--depth requires a value: --depth overview|modules|full");
+      }
+      const depthRaw = typeof flags.depth === "string" ? flags.depth : undefined;
+      if (depthRaw !== undefined && depthRaw !== "overview" && depthRaw !== "modules" && depthRaw !== "full") {
+        usageError(`Invalid --depth value: "${depthRaw}". Must be overview, modules, or full`);
+      }
+      if (flags.folder === true) {
+        usageError("--folder requires a value: --folder <path-prefix>");
+      }
+      const folder = typeof flags.folder === "string" ? flags.folder : undefined;
+
+      const result = await mapCommand({
+        ...(depthRaw !== undefined ? { depth: depthRaw } : {}),
+        ...(folder !== undefined ? { folder } : {}),
+      });
+
+      if (result.ok) {
+        printResult(result, pretty);
+      } else {
+        printError(result, pretty);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "watch": {
+      const result = await watchCommand({ verbose: flags.verbose === true });
+      if (!result.ok) {
+        printError(result, pretty);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "version": {
+      const result = versionCommand({});
+      if (result.ok) {
+        printResult(result, pretty);
+      } else {
+        printError(result, pretty);
+        process.exit(1);
+      }
+      break;
+    }
+
     default:
-      usageError(`Unknown command: "${command}". Commands: list, inspect, flush, invalidate, touch, prune, check-freshness, check-files, search, write, install`);
+      usageError(`Unknown command: "${command}". Commands: list, inspect, flush, invalidate, touch, prune, check-files, search, write-local, write-external, install, update, uninstall, graph, map, watch, version`);
   }
 }
 
 if (import.meta.main) {
   main().catch((err: unknown) => {
-    const error = err as Error;
-    process.stderr.write(JSON.stringify({ ok: false, error: error.message, code: ErrorCode.UNKNOWN }) + "\n");
+    process.stderr.write(JSON.stringify(toUnknownResult(err)) + "\n");
     process.exit(1);
   });
 }

package/src/search/keywordSearch.ts

@@ -1,6 +1,15 @@
 import type { CacheEntry } from "../types/cache.js";
 import { getFileStem } from "../utils/fileStem.js";
 
+/**
+ * Scores a cache entry against one or more keywords.
+ *
+ * @param entry - Candidate cache entry.
+ * @param keywords - Search keywords.
+ * @returns Numeric relevance score (higher is better).
+ * Scoring matrix uses max-per-keyword weights: exact stem (100), stem substring (80),
+ * exact word in subject/topic (70), subject/topic substring (50), description substring (30).
+ */
 export function scoreEntry(entry: CacheEntry, keywords: string[]): number {
   const stem = getFileStem(entry.file).toLowerCase();
   const subject = entry.subject.toLowerCase();
@@ -37,6 +46,13 @@ export function scoreEntry(entry: CacheEntry, keywords: string[]): number {
   return total;
 }
 
+/**
+ * Ranks cache entries by keyword relevance.
+ *
+ * @param entries - Candidate entries to rank.
+ * @param keywords - Search keywords.
+ * @returns Score-sorted entries with zero-score candidates removed.
+ */
 export function rankResults(entries: CacheEntry[], keywords: string[]): CacheEntry[] {
   const scored = entries.map((entry) => ({
     entry,
@@ -52,6 +68,14 @@ export function rankResults(entries: CacheEntry[], keywords: string[]): CacheEnt
   return matched.map((s) => ({ ...s.entry, score: s.score }));
 }
 
+/**
+ * Checks whether a keyword appears as an exact word in text.
+ *
+ * @param text - Candidate text.
+ * @param keyword - Lowercased keyword to match.
+ * @returns `true` when an exact token match exists.
+ * @remarks Word matching is based on split boundaries (`space`, `_`, `-`, `.`, `/`).
+ */
 export function isExactWordMatch(text: string, keyword: string): boolean {
   // Match whole words — split on non-alphanumeric chars
   const words = text.split(/[\s\-_./]+/);

package/src/types/cache.ts

@@ -1,7 +1,11 @@
 import { z } from "zod";
 
+/** Supported cache namespaces exposed by the CLI and plugin tools. */
 export type AgentType = "external" | "local";
 
+/**
+ * Normalized cache entry summary returned by the `list` command prior to formatting.
+ */
 export interface CacheEntry {
   file: string;
   agent: AgentType;
@@ -17,27 +21,32 @@ const SourceSchema = z.object({
   version: z.string().optional(),
 });
 
-const HeaderMetaSchema = z.object({
-  etag: z.string().optional(),
-  last_modified: z.string().optional(),
-  checked_at: z.string(),
-  status: z.enum(["fresh", "stale", "unchecked"]),
-});
-
+/**
+ * Validates external context cache JSON files stored under `.ai/external-context-gatherer_cache/`.
+ */
 export const ExternalCacheFileSchema = z.looseObject({
   subject: z.string(),
   description: z.string(),
   fetched_at: z.string(),
   sources: z.array(SourceSchema),
-  header_metadata: z.record(z.string(), HeaderMetaSchema),
 });
 
+/** Validates one tracked file baseline used by local file-change detection. */
 export const TrackedFileSchema = z.object({
   path: z.string(),
   mtime: z.number(),
   hash: z.string().optional(),
 });
 
+const FileFactsSchema = z.object({
+  summary: z.string().max(300).optional(),
+  role: z
+    .enum(["entry-point", "interface", "implementation", "test", "config"])
+    .optional(),
+  importance: z.union([z.literal(1), z.literal(2), z.literal(3)]).optional(),
+  facts: z.array(z.string().max(300)).max(10).optional(),
+});
+
 /**
  * Zod schema for the local context-gatherer cache file (`context.json`).
  *
@@ -47,8 +56,8 @@ export const TrackedFileSchema = z.object({
  * Size constraints enforced at write time:
  * - `global_facts`: max 20 entries; each string ≤ 300 characters.
  *   For cross-cutting structural observations only (e.g. repo layout, toolchain).
- * - `facts`: max 30 entries per file path; each string ≤ 800 characters.
- *   Facts must be concise observations — not raw file content or code snippets.
+ * - `facts`: per-file structured metadata with max 10 concise fact strings
+ *   (each string ≤ 300 characters).
  */
 export const LocalCacheFileSchema = z.looseObject({
   timestamp: z.string(),
@@ -68,24 +77,27 @@ export const LocalCacheFileSchema = z.looseObject({
         "max 20 global facts — choose only cross-cutting structural observations",
     })
     .optional(),
-  facts: z
-    .record(
-      z.string(),
-      z
-        .array(
-          z.string().max(800, {
-            message:
-              "write concise observations, not file content (max 800 chars per fact)",
-          }),
-        )
-        .max(30, {
-          message:
-            "max 30 facts per file — choose the most architecturally meaningful observations",
-        }),
-    )
-    .optional(),
+  facts: z.record(z.string(), FileFactsSchema).optional(),
+  modules: z.record(z.string(), z.array(z.string())).optional(),
 });
 
 export type TrackedFile = z.infer<typeof TrackedFileSchema>;
+export type FileFacts = z.infer<typeof FileFactsSchema>;
 export type ExternalCacheFile = z.infer<typeof ExternalCacheFileSchema>;
 export type LocalCacheFile = z.infer<typeof LocalCacheFileSchema>;
+
+const GraphNodeSchema = z.object({
+  rank: z.number(),
+  deps: z.array(z.string()),
+  defs: z.array(z.string()),
+});
+
+/**
+ * Validates graph cache payloads written by `watch` and consumed by `graph`.
+ */
+export const GraphCacheFileSchema = z.object({
+  files: z.record(z.string(), GraphNodeSchema),
+  computed_at: z.string(),
+});
+
+export type GraphCacheFile = z.infer<typeof GraphCacheFileSchema>;