@thecat69/cache-ctrl 1.0.0

package/src/index.ts

@@ -0,0 +1,557 @@
+#!/usr/bin/env bun
+import { listCommand } from "./commands/list.js";
+import { inspectCommand } from "./commands/inspect.js";
+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 { installCommand } from "./commands/install.js";
+import { ErrorCode } from "./types/result.js";
+
+type CommandName =
+  | "list"
+  | "inspect"
+  | "flush"
+  | "invalidate"
+  | "touch"
+  | "prune"
+  | "check-freshness"
+  | "check-files"
+  | "search"
+  | "write"
+  | "install";
+
+function isKnownCommand(cmd: string): cmd is CommandName {
+  return Object.hasOwn(COMMAND_HELP as Record<string, unknown>, cmd);
+}
+
+interface CommandHelp {
+  usage: string;
+  description: string;
+  details: string;
+}
+
+const COMMAND_HELP: Record<CommandName, CommandHelp> = {
+  list: {
+    usage: "list [--agent external|local|all]",
+    description: "List all cache entries with age and staleness",
+    details: [
+      "  Arguments:",
+      "    (none)",
+      "",
+      "  Options:",
+      "    --agent external|local|all   Filter by agent type (default: all)",
+      "",
+      "  Output: JSON array of cache entries with timestamps and staleness flags.",
+    ].join("\n"),
+  },
+  inspect: {
+    usage: "inspect <agent> <subject-keyword> [--filter <kw>] [--folder <path>] [--search-facts <kw>]",
+    description: "Show full content of a cache entry",
+    details: [
+      "  Arguments:",
+      "    <agent>            Agent type: external or local",
+      "    <subject-keyword>  Keyword used to locate the cache entry",
+      "",
+      "  Options:",
+      "    --filter <kw>[,<kw>...]      Return only facts whose file path contains any keyword",
+      "                                 (local agent only; comma-separated; case-insensitive OR match)",
+      "    --folder <path>              Return only facts whose file path starts with the given folder prefix",
+      "                                 (local agent only; recursive; INVALID_ARGS if used with external agent)",
+      "    --search-facts <kw>[,<kw>...]  Return only facts where any fact string contains any keyword",
+      "                                   (local agent only; comma-separated; case-insensitive OR match)",
+      "",
+      "  Output: Full JSON content of the matched cache entry.",
+      "  Note: tracked_files is never returned for local agent inspect.",
+      "  Note: --filter, --folder, and --search-facts are AND-ed when combined.",
+    ].join("\n"),
+  },
+  flush: {
+    usage: "flush <agent|all> --confirm",
+    description: "Delete all cache entries (destructive, requires --confirm)",
+    details: [
+      "  Arguments:",
+      "    <agent|all>   Agent to flush: external, local, or all",
+      "",
+      "  Options:",
+      "    --confirm     Required flag — confirms the destructive operation",
+      "",
+      "  WARNING: This permanently deletes all matching cache entries.",
+    ].join("\n"),
+  },
+  invalidate: {
+    usage: "invalidate <agent> [subject-keyword]",
+    description: "Mark cache entries as stale (content preserved)",
+    details: [
+      "  Arguments:",
+      "    <agent>             Agent type: external or local",
+      "    [subject-keyword]   Optional keyword to target a specific entry",
+      "",
+      "  Output: Number of entries marked as stale.",
+    ].join("\n"),
+  },
+  touch: {
+    usage: "touch <agent> [subject-keyword]",
+    description: "Refresh timestamps on cache entries",
+    details: [
+      "  Arguments:",
+      "    <agent>             Agent type: external or local",
+      "    [subject-keyword]   Optional keyword to target a specific entry",
+      "",
+      "  Output: Number of entries whose timestamps were updated.",
+    ].join("\n"),
+  },
+  prune: {
+    usage: "prune [--agent external|local|all] [--max-age <duration>] [--delete]",
+    description: "Find and optionally remove stale entries",
+    details: [
+      "  Arguments:",
+      "    (none)",
+      "",
+      "  Options:",
+      "    --agent external|local|all   Filter by agent type (default: all)",
+      "    --max-age <duration>         Maximum age threshold (e.g. 24h, 7d)",
+      "    --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",
+    details: [
+      "  Arguments:",
+      "    (none)",
+      "",
+      "  Output: List of files whose mtime or hash differs from the stored baseline.",
+      "  Also reports new_files (files not excluded by .gitignore that are absent from cache — includes git-tracked and untracked-non-ignored files) and deleted_git_files.",
+    ].join("\n"),
+  },
+  search: {
+    usage: "search <keyword> [<keyword>...]",
+    description: "Search cache entries by keyword (ranked results)",
+    details: [
+      "  Arguments:",
+      "    <keyword> [<keyword>...]   One or more keywords to search for",
+      "",
+      "  Output: Ranked list of matching cache entries.",
+    ].join("\n"),
+  },
+  write: {
+    usage: "write <agent> [subject] --data '<json>'",
+    description: "Write a validated cache entry from JSON",
+    details: [
+      "  Arguments:",
+      "    <agent>     Agent type: external or local",
+      "    [subject]   Optional subject identifier (required for external agent)",
+      "",
+      "  Options:",
+      "    --data '<json>'   JSON string containing the cache entry payload",
+      "",
+      "  Output: Confirmation with the written entry's key.",
+    ].join("\n"),
+  },
+  install: {
+    usage: "install [--config-dir <path>]",
+    description: "Set up OpenCode tool and skills in the user config directory",
+    details: [
+      "  Arguments:",
+      "    (none)",
+      "",
+      "  Options:",
+      "    --config-dir <path>  Override the OpenCode config directory (default: platform-specific)",
+      "",
+      "  Output: JSON object describing installed tool/skill paths.",
+    ].join("\n"),
+  },
+};
+
+const GLOBAL_OPTIONS_SECTION = [
+  "Global options:",
+  "  --help    Show help (use 'help <command>' for command-specific help)",
+  "  --pretty  Pretty-print JSON output",
+].join("\n");
+
+/**
+ * Writes plain-text usage information to stdout.
+ *
+ * @param command - If provided, prints help for that specific command.
+ *                  If omitted, prints the full command reference.
+ *                  Does NOT call process.exit — the caller handles exit.
+ */
+export function printHelp(command?: string): boolean {
+  if (command === undefined) {
+    const lines: string[] = [
+      "Usage: cache-ctrl <command> [args] [options]",
+      "",
+      "Commands:",
+    ];
+
+    const maxUsageLen = Math.max(
+      ...Object.values(COMMAND_HELP).map((h) => h.usage.length),
+    );
+
+    for (const [, help] of Object.entries(COMMAND_HELP) as [CommandName, CommandHelp][]) {
+      const paddedUsage = help.usage.padEnd(maxUsageLen);
+      lines.push(`  ${paddedUsage}   ${help.description}`);
+    }
+
+    lines.push("", GLOBAL_OPTIONS_SECTION, "", "Run 'cache-ctrl help <command>' for command-specific help.");
+    process.stdout.write(lines.join("\n") + "\n");
+    return true;
+  }
+
+  const sanitized = command.replace(/[\x00-\x1F\x7F]/g, "");
+
+  if (command === "help") {
+    return printHelp();
+  }
+
+  if (!isKnownCommand(command)) {
+    process.stderr.write(`Unknown command: "${sanitized}". Run 'cache-ctrl help' for available commands.\n`);
+    return false;
+  }
+
+  const help = COMMAND_HELP[command];
+  const lines: string[] = [
+    `Usage: cache-ctrl ${help.usage}`,
+    "",
+    `Description: ${help.description}`,
+    "",
+    help.details,
+    "",
+    GLOBAL_OPTIONS_SECTION,
+  ];
+  process.stdout.write(lines.join("\n") + "\n");
+  return true;
+}
+
+function printResult(value: unknown, pretty: boolean): void {
+  if (pretty) {
+    process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+  } else {
+    process.stdout.write(JSON.stringify(value) + "\n");
+  }
+}
+
+function printError(error: { ok: false; error: string; code: string }, pretty: boolean): void {
+  if (pretty) {
+    process.stderr.write(JSON.stringify(error, null, 2) + "\n");
+  } else {
+    process.stderr.write(JSON.stringify(error) + "\n");
+  }
+}
+
+function usageError(message: string): never {
+  process.stderr.write(JSON.stringify({ ok: false, error: message, code: ErrorCode.INVALID_ARGS }) + "\n");
+  process.exit(2);
+}
+
+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"]);
+
+export function parseArgs(argv: string[]): { args: string[]; flags: Record<string, string | boolean> } {
+  const positional: string[] = [];
+  const flags: Record<string, string | boolean> = {};
+
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i]!;
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (VALUE_FLAGS.has(key) && next !== undefined) {
+        flags[key] = next;
+        i += 2;
+      } else {
+        flags[key] = true;
+        i += 1;
+      }
+    } else {
+      positional.push(arg);
+      i += 1;
+    }
+  }
+
+  return { args: positional, flags };
+}
+
+async function main(): Promise<void> {
+  const rawArgs = process.argv.slice(2);
+  const { args, flags } = parseArgs(rawArgs);
+  const pretty = flags.pretty === true;
+
+  if (flags["help"] === true) {
+    printHelp();
+    process.exit(0);
+  }
+
+  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");
+  }
+
+  switch (command) {
+    case "help": {
+      const ok = printHelp(args[1]);
+      process.exit(ok ? 0 : 1);
+      break;
+    }
+    case "list": {
+      const agentArg = typeof flags.agent === "string" ? flags.agent : undefined;
+      const validAgents: (string | undefined)[] = ["external", "local", "all", undefined];
+      if (!validAgents.includes(agentArg)) {
+        usageError(`Invalid --agent value: "${agentArg}". Must be external, local, or all`);
+      }
+      const result = await listCommand({
+        ...(agentArg !== undefined ? { agent: agentArg as "external" | "local" | "all" } : {}),
+      });
+      if (result.ok) {
+        printResult(result, pretty);
+      } else {
+        printError(result, pretty);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "inspect": {
+      const agent = args[1];
+      const subject = args[2];
+      if (!agent || !subject) {
+        usageError("Usage: cache-ctrl inspect <agent> <subject-keyword>");
+      }
+      if (agent !== "external" && agent !== "local") {
+        usageError(`Invalid agent: "${agent}". Must be external or local`);
+      }
+      if (flags.filter === true) {
+        usageError("--filter requires a value: --filter <kw>[,<kw>...]");
+      }
+      if (typeof flags.folder === "string" && flags.folder.trim() === "") {
+        usageError("--folder requires a non-empty value");
+      }
+      const filterRaw = typeof flags.filter === "string" ? flags.filter : undefined;
+      const filter = filterRaw
+        ? filterRaw
+            .split(",")
+            .map((f) => f.trim())
+            .filter(Boolean)
+        : undefined;
+      const folder = typeof flags.folder === "string" ? flags.folder : undefined;
+      const searchFactsRaw = typeof flags["search-facts"] === "string" ? flags["search-facts"] : undefined;
+      const searchFacts = searchFactsRaw
+        ? searchFactsRaw
+            .split(",")
+            .map((f) => f.trim())
+            .filter(Boolean)
+        : undefined;
+      const result = await inspectCommand({
+        agent,
+        subject,
+        ...(filter !== undefined ? { filter } : {}),
+        ...(folder !== undefined ? { folder } : {}),
+        ...(searchFacts !== undefined ? { searchFacts } : {}),
+      });
+      if (result.ok) {
+        printResult(result, pretty);
+      } else {
+        printError(result, pretty);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "flush": {
+      const agent = args[1];
+      if (!agent) {
+        usageError("Usage: cache-ctrl flush <agent|all> --confirm");
+      }
+      if (agent !== "external" && agent !== "local" && agent !== "all") {
+        usageError(`Invalid agent: "${agent}". Must be external, local, or all`);
+      }
+      const confirm = flags.confirm === true;
+      const result = await flushCommand({ agent, confirm });
+      if (result.ok) {
+        printResult(result, pretty);
+      } else {
+        printError(result, pretty);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "invalidate": {
+      const agent = args[1];
+      if (!agent) {
+        usageError("Usage: cache-ctrl invalidate <agent> [subject-keyword]");
+      }
+      if (agent !== "external" && agent !== "local") {
+        usageError(`Invalid agent: "${agent}". Must be external or local`);
+      }
+      const subject = args[2];
+      const result = await invalidateCommand({ agent, ...(subject !== undefined ? { subject } : {}) });
+      if (result.ok) {
+        printResult(result, pretty);
+      } else {
+        printError(result, pretty);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "touch": {
+      const agent = args[1];
+      if (!agent) {
+        usageError("Usage: cache-ctrl touch <agent> [subject-keyword]");
+      }
+      if (agent !== "external" && agent !== "local") {
+        usageError(`Invalid agent: "${agent}". Must be external or local`);
+      }
+      const subject = args[2];
+      const result = await touchCommand({ agent, ...(subject !== undefined ? { subject } : {}) });
+      if (result.ok) {
+        printResult(result, pretty);
+      } else {
+        printError(result, pretty);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "prune": {
+      const agentArg = typeof flags.agent === "string" ? flags.agent : undefined;
+      if (agentArg && agentArg !== "external" && agentArg !== "local" && agentArg !== "all") {
+        usageError(`Invalid --agent value: "${agentArg}". Must be external, local, or all`);
+      }
+      const maxAge = typeof flags["max-age"] === "string" ? flags["max-age"] : undefined;
+      const doDelete = flags.delete === true;
+      const result = await pruneCommand({
+        ...(agentArg !== undefined ? { agent: agentArg as "external" | "local" | "all" } : {}),
+        ...(maxAge !== undefined ? { maxAge } : {}),
+        delete: doDelete,
+      });
+      if (result.ok) {
+        printResult(result, pretty);
+      } else {
+        printError(result, pretty);
+        process.exit(1);
+      }
+      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 } : {}) });
+      if (result.ok) {
+        printResult(result, pretty);
+      } else {
+        printError(result, pretty);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "check-files": {
+      const result = await checkFilesCommand();
+      if (result.ok) {
+        printResult(result, pretty);
+      } else {
+        printError(result, pretty);
+        process.exit(1);
+      }
+      break;
+    }
+
+    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 {
+        printError(result, pretty);
+        process.exit(1);
+      }
+      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`);
+      }
+      const dataStr = typeof flags.data === "string" ? flags.data : undefined;
+      if (!dataStr) {
+        usageError("Usage: cache-ctrl write <agent> [subject] --data '<json>'");
+      }
+      let content: Record<string, unknown>;
+      try {
+        content = JSON.parse(dataStr) as Record<string, unknown>;
+      } catch {
+        usageError("--data must be valid JSON");
+      }
+      const subject = agent === "external" ? args[2] : undefined;
+      const result = await writeCommand({
+        agent,
+        ...(subject !== undefined ? { subject } : {}),
+        content,
+      });
+      if (result.ok) {
+        printResult(result, pretty);
+      } else {
+        printError(result, pretty);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "install": {
+      const configDir = typeof flags["config-dir"] === "string" ? flags["config-dir"] : undefined;
+      const result = await installCommand({ ...(configDir !== undefined ? { configDir } : {}) });
+      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`);
+  }
+}
+
+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.exit(1);
+  });
+}

package/src/search/keywordSearch.ts

@@ -0,0 +1,59 @@
+import type { CacheEntry } from "../types/cache.js";
+import { getFileStem } from "../utils/fileStem.js";
+
+export function scoreEntry(entry: CacheEntry, keywords: string[]): number {
+  const stem = getFileStem(entry.file).toLowerCase();
+  const subject = entry.subject.toLowerCase();
+  const description = (entry.description ?? "").toLowerCase();
+
+  let total = 0;
+  for (const keyword of keywords) {
+    const kw = keyword.toLowerCase();
+    let score = 0;
+
+    // Exact file stem match
+    if (stem === kw) {
+      score = Math.max(score, 100);
+    } else if (stem.includes(kw)) {
+      // Substring file stem match
+      score = Math.max(score, 80);
+    }
+
+    // Exact word match on subject/topic
+    if (isExactWordMatch(subject, kw)) {
+      score = Math.max(score, 70);
+    } else if (subject.includes(kw)) {
+      // Substring match on subject/topic
+      score = Math.max(score, 50);
+    }
+
+    // Keyword match on description
+    if (description.includes(kw)) {
+      score = Math.max(score, 30);
+    }
+
+    total += score;
+  }
+  return total;
+}
+
+export function rankResults(entries: CacheEntry[], keywords: string[]): CacheEntry[] {
+  const scored = entries.map((entry) => ({
+    entry,
+    score: scoreEntry(entry, keywords),
+  }));
+
+  // Filter out zero-score entries
+  const matched = scored.filter((s) => s.score > 0);
+
+  // Sort by score descending; preserve order for ties
+  matched.sort((a, b) => b.score - a.score);
+
+  return matched.map((s) => ({ ...s.entry, score: s.score }));
+}
+
+export function isExactWordMatch(text: string, keyword: string): boolean {
+  // Match whole words — split on non-alphanumeric chars
+  const words = text.split(/[\s\-_./]+/);
+  return words.some((word) => word === keyword);
+}

package/src/types/cache.ts

@@ -0,0 +1,91 @@
+import { z } from "zod";
+
+export type AgentType = "external" | "local";
+
+export interface CacheEntry {
+  file: string;
+  agent: AgentType;
+  subject: string;
+  description?: string;
+  fetched_at: string;
+  score?: number;
+}
+
+const SourceSchema = z.object({
+  type: z.string(),
+  url: z.string(),
+  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"]),
+});
+
+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),
+});
+
+export const TrackedFileSchema = z.object({
+  path: z.string(),
+  mtime: z.number(),
+  hash: z.string().optional(),
+});
+
+/**
+ * Zod schema for the local context-gatherer cache file (`context.json`).
+ *
+ * Uses `z.looseObject()` so that unknown fields written by agents are preserved
+ * unchanged through atomic read-modify-write merges.
+ *
+ * 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.
+ */
+export const LocalCacheFileSchema = z.looseObject({
+  timestamp: z.string(),
+  topic: z.string(),
+  description: z.string(),
+  cache_miss_reason: z.string().optional(),
+  tracked_files: z.array(TrackedFileSchema),
+  global_facts: z
+    .array(
+      z.string().max(300, {
+        message:
+          "global facts must be concise cross-cutting observations (max 300 chars)",
+      }),
+    )
+    .max(20, {
+      message:
+        "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(),
+});
+
+export type TrackedFile = z.infer<typeof TrackedFileSchema>;
+export type ExternalCacheFile = z.infer<typeof ExternalCacheFileSchema>;
+export type LocalCacheFile = z.infer<typeof LocalCacheFileSchema>;