@thecat69/cache-ctrl 1.1.1 → 1.2.0

package/src/commands/watch.ts

@@ -28,8 +28,16 @@ type BunWatchFunction = (
   callback: BunWatchCallback,
 ) => WatcherHandle;
 
-function resolveBunWatch(): Result<BunWatchFunction> {
-  const watchFn = Reflect.get(Object(Bun), "watch");
+export function resolveBunWatch(): Result<BunWatchFunction> {
+  const bunRuntime = Reflect.get(globalThis, "Bun");
+  if (typeof bunRuntime !== "object" || bunRuntime === null) {
+    return {
+      ok: false,
+      error: "Bun.watch is not available in this runtime",
+      code: ErrorCode.UNKNOWN,
+    };
+  }
+  const watchFn = Reflect.get(bunRuntime, "watch");
   if (typeof watchFn !== "function") {
     return {
       ok: false,
@@ -104,19 +112,38 @@ export async function resolveSourceFilePaths(
   return [...sourcePaths];
 }
 
-async function rebuildGraphCache(repoRoot: string, changedPath: string | undefined, verbose: boolean): Promise<void> {
+interface RebuildGraphCacheDependencies {
+  resolveSourceFilePaths: typeof resolveSourceFilePaths;
+  buildGraph: typeof buildGraph;
+  resolveGraphCachePath: typeof resolveGraphCachePath;
+  writeCache: typeof writeCache;
+}
+
+const defaultRebuildGraphCacheDependencies: RebuildGraphCacheDependencies = {
+  resolveSourceFilePaths,
+  buildGraph,
+  resolveGraphCachePath,
+  writeCache,
+};
+
+export async function rebuildGraphCache(
+  repoRoot: string,
+  changedPath: string | undefined,
+  verbose: boolean,
+  dependencies: RebuildGraphCacheDependencies = defaultRebuildGraphCacheDependencies,
+): Promise<Result<void>> {
   try {
-    const sourceFilePaths = await resolveSourceFilePaths(repoRoot);
-    const graph = await buildGraph(sourceFilePaths, repoRoot);
-    const graphCachePath = resolveGraphCachePath(repoRoot);
+    const sourceFilePaths = await dependencies.resolveSourceFilePaths(repoRoot);
+    const graph = await dependencies.buildGraph(sourceFilePaths, repoRoot);
+    const graphCachePath = dependencies.resolveGraphCachePath(repoRoot);
     const graphPayload: GraphCacheFile = {
       files: serializeGraphToCache(graph),
       computed_at: new Date().toISOString(),
     };
-    const writeResult = await writeCache(graphCachePath, graphPayload, "replace");
+    const writeResult = await dependencies.writeCache(graphCachePath, graphPayload, "replace");
     if (!writeResult.ok) {
       process.stderr.write(`[watch] Failed to update graph cache: ${writeResult.error}\n`);
-      return;
+      return writeResult;
     }
     if (verbose) {
       if (changedPath !== undefined) {
@@ -125,9 +152,11 @@ async function rebuildGraphCache(repoRoot: string, changedPath: string | undefin
         process.stdout.write(`[watch] Initial graph computed: ${graph.size} files\n`);
       }
     }
+    return { ok: true, value: undefined };
   } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    process.stderr.write(`[watch] Failed to rebuild graph: ${message}\n`);
+    const unknownError = toUnknownResult(err);
+    process.stderr.write(`[watch] Failed to rebuild graph: ${unknownError.error}\n`);
+    return unknownError;
   }
 }
 
@@ -142,25 +171,9 @@ export async function watchCommand(args: WatchArgs): Promise<Result<never>> {
   try {
     const repoRoot = await findRepoRoot(process.cwd());
 
-    const initialSourceFiles = await resolveSourceFilePaths(repoRoot);
-    const initialGraph = await buildGraph(initialSourceFiles, repoRoot);
-    const graphCachePath = resolveGraphCachePath(repoRoot);
-    const initialPayload: GraphCacheFile = {
-      files: serializeGraphToCache(initialGraph),
-      computed_at: new Date().toISOString(),
-    };
-    const initialWriteResult = await writeCache(graphCachePath, initialPayload, "replace");
-    if (!initialWriteResult.ok) {
-      const errorMessage = `[watch] Failed to write initial graph cache: ${initialWriteResult.error}`;
-      process.stderr.write(`${errorMessage}\n`);
-      return {
-        ok: false,
-        error: errorMessage,
-        code: ErrorCode.UNKNOWN,
-      };
-    }
-    if (args.verbose) {
-      process.stdout.write(`[watch] Initial graph computed: ${initialGraph.size} files\n`);
+    const initialRebuildResult = await rebuildGraphCache(repoRoot, undefined, args.verbose === true);
+    if (!initialRebuildResult.ok) {
+      return initialRebuildResult;
     }
 
     let pendingChangedPath: string | undefined;
@@ -180,7 +193,11 @@ export async function watchCommand(args: WatchArgs): Promise<Result<never>> {
           rebuildQueued = false;
           const changedPath = pendingChangedPath;
           pendingChangedPath = undefined;
-          await rebuildGraphCache(repoRoot, changedPath, args.verbose === true);
+          const rebuildResult = await rebuildGraphCache(repoRoot, changedPath, args.verbose === true);
+          if (!rebuildResult.ok) {
+            // Error already logged in rebuildGraphCache; continue watching for future changes.
+            continue;
+          }
         } while (rebuildQueued);
       } finally {
         rebuildInProgress = false;

package/src/commands/writeLocal.ts

@@ -30,13 +30,6 @@ function getSubmittedTrackedPaths(rawTrackedFiles: unknown): string[] {
   return rawTrackedFiles.filter(hasStringPath).map((entry) => entry.path);
 }
 
-function toPlainObjectRecord(rawValue: unknown): Record<string, unknown> {
-  if (typeof rawValue === "object" && rawValue !== null && !Array.isArray(rawValue)) {
-    return Object.fromEntries(Object.entries(rawValue));
-  }
-  return {};
-}
-
 /**
  * Validates and writes local context cache content with per-path merge semantics.
  *
@@ -58,7 +51,12 @@ export async function writeLocalCommand(args: WriteArgs): Promise<Result<WriteRe
     const resolvedTrackedFiles = await resolveTrackedFileStats(submittedPaths.map((path) => ({ path })), repoRoot);
     const survivingSubmitted = resolvedTrackedFiles.filter((trackedFile) => trackedFile.mtime !== 0);
 
-    const submittedFacts = toPlainObjectRecord(contentWithTimestamp["facts"]);
+    const submittedFacts =
+      typeof contentWithTimestamp["facts"] === "object" &&
+      contentWithTimestamp["facts"] !== null &&
+      !Array.isArray(contentWithTimestamp["facts"])
+        ? (contentWithTimestamp["facts"] as Record<string, unknown>)
+        : {};
     const rawSubmittedFacts = contentWithTimestamp["facts"];
     if (typeof rawSubmittedFacts === "object" && rawSubmittedFacts !== null && !Array.isArray(rawSubmittedFacts)) {
       const violatingPaths = Object.keys(submittedFacts).filter((path) => !guardedPaths.has(path));

package/src/index.ts

@@ -5,12 +5,13 @@ 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 { 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";
@@ -25,12 +26,13 @@ type CommandName =
   | "invalidate"
   | "touch"
   | "prune"
-  | "check-freshness"
   | "check-files"
   | "search"
   | "write-local"
   | "write-external"
   | "install"
+  | "update"
+  | "uninstall"
   | "graph"
   | "map"
   | "watch"
@@ -129,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",
@@ -202,6 +191,32 @@ 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",
@@ -349,7 +364,6 @@ export { usageError };
 const VALUE_FLAGS = new Set([
   "data",
   "agent",
-  "url",
   "max-age",
   "filter",
   "folder",
@@ -423,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-local, write-external, install, graph, map, watch, version");
+    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) {
@@ -574,22 +588,6 @@ 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 } : {}) });
-      if (result.ok) {
-        printResult(result, pretty);
-      } else {
-        printError(result, pretty);
-        process.exit(1);
-      }
-      break;
-    }
-
     case "check-files": {
       const result = await checkFilesCommand();
       if (result.ok) {
@@ -676,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) {
@@ -687,6 +688,36 @@ 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");
@@ -770,7 +801,7 @@ async function main(): Promise<void> {
     }
 
     default:
-      usageError(`Unknown command: "${command}". Commands: list, inspect, flush, invalidate, touch, prune, check-freshness, check-files, search, write-local, write-external, install, graph, map, watch, version`);
+      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`);
   }
 }
 

package/src/types/cache.ts

@@ -21,17 +21,6 @@ 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(),
-  // "unchecked" = entry written without HTTP check
-  status: z.enum(["fresh", "stale", "unchecked"]),
-});
-
-/** Stored HTTP validator metadata for one source URL in an external cache entry. */
-export type HeaderMeta = z.infer<typeof HeaderMetaSchema>;
-
 /**
  * Validates external context cache JSON files stored under `.ai/external-context-gatherer_cache/`.
  */
@@ -40,7 +29,6 @@ export const ExternalCacheFileSchema = z.looseObject({
   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. */

package/src/types/commands.ts

@@ -125,29 +125,6 @@ export type PruneResult = {
   };
 };
 
-// ── check-freshness ───────────────────────────────────────────────────────────
-
-/** Arguments accepted by the `check-freshness` command. */
-export interface CheckFreshnessArgs {
-  subject: string;
-  url?: string;
-}
-
-/** Success payload shape returned by the `check-freshness` command. */
-export type CheckFreshnessResult = {
-  ok: true;
-  value: {
-    subject: string;
-    sources: Array<{
-      url: string;
-      status: "fresh" | "stale" | "error";
-      http_status?: number;
-      error?: string;
-    }>;
-    overall: "fresh" | "stale" | "error";
-  };
-};
-
 // ── check-files ───────────────────────────────────────────────────────────────
 
 /** Success payload shape returned by the `check-files` command. */
@@ -288,3 +265,29 @@ export type VersionArgs = Record<string, never>;
 
 /** Success payload shape returned by the `version` command. */
 export type VersionResult = { value: { version: string } };
+
+// ── update / uninstall ────────────────────────────────────────────────────────
+
+/** Arguments accepted by the `update` command. */
+export interface UpdateArgs {
+  configDir?: string;
+}
+
+/** Success payload shape returned by the `update` command. */
+export interface UpdateResult {
+  packageUpdated: boolean;
+  installedPaths: string[];
+  warnings: string[];
+}
+
+/** Arguments accepted by the `uninstall` command. */
+export interface UninstallArgs {
+  configDir?: string;
+}
+
+/** Success payload shape returned by the `uninstall` command. */
+export interface UninstallResult {
+  removed: string[];
+  packageUninstalled: boolean;
+  warnings: string[];
+}

package/src/types/result.ts

@@ -28,9 +28,6 @@ export enum ErrorCode {
   /** Returned when keyword matching yields multiple top-scoring candidates. */
   AMBIGUOUS_MATCH = "AMBIGUOUS_MATCH",
 
-  /** Returned when a user-specified URL is not present in the matched entry's sources list. */
-  URL_NOT_FOUND = "URL_NOT_FOUND",
-
   /** Returned for unexpected internal exceptions converted at command boundaries. */
   UNKNOWN = "UNKNOWN",
 }

package/src/commands/checkFreshness.ts

@@ -1,123 +0,0 @@
-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, HeaderMeta } 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 { getFileStem } from "../utils/fileStem.js";
-import { toUnknownResult } from "../utils/errors.js";
-
-/**
- * Performs HTTP freshness checks for the matched external cache entry sources.
- *
- * @param args - {@link CheckFreshnessArgs} command arguments.
- * @returns Promise<Result<CheckFreshnessResult["value"]>>; common failures include
- * NO_MATCH, URL_NOT_FOUND, PARSE_ERROR, FILE_READ_ERROR/FILE_WRITE_ERROR, and UNKNOWN.
- */
-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 ?? [];
-    const specificSource = args.url ? sources.find((source) => source.url === args.url) : undefined;
-    if (args.url && !specificSource) {
-      return {
-        ok: false,
-        error: `URL not found in sources for subject '${subject}'`,
-        code: ErrorCode.URL_NOT_FOUND,
-      };
-    }
-    const urlsToCheck = specificSource ? [specificSource] : 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) {
-    return toUnknownResult(err);
-  }
-}

package/src/http/freshnessChecker.ts

@@ -1,138 +0,0 @@
-/** Input payload for one HTTP freshness check request. */
-export interface FreshnessCheckInput {
-  url: string;
-  etag?: string;
-  last_modified?: string;
-}
-
-/**
- * Output payload for one HTTP freshness check request.
- *
- * @remarks Status semantics: HTTP 304 maps to `fresh`, HTTP 200 maps to `stale`, and
- * all other outcomes (network errors, blocked URLs, non-200/304 responses) map to `error`.
- */
-export interface FreshnessCheckOutput {
-  url: string;
-  status: "fresh" | "stale" | "error";
-  http_status?: number;
-  etag?: string;
-  last_modified?: string;
-  error?: string;
-}
-
-/**
- * RFC-1918 / loopback / link-local / ULA / mapped-IPv6 IP pattern.
- * Blocks raw IP literals only — does NOT do DNS resolution.
- *
- * Covers:
- *   - 127.x          loopback IPv4
- *   - ::1            loopback IPv6 (URL.hostname returns "[::1]")
- *   - localhost      loopback hostname
- *   - 10.x           RFC-1918 class A
- *   - 169.254.x      link-local IPv4
- *   - 172.16–31.x    RFC-1918 class B
- *   - 192.168.x      RFC-1918 class C
- *   - 0.0.0.0        unspecified IPv4
- *   - fc00::/7       RFC-4193 unique-local IPv6 (ULA — fc or fd prefix)
- *   - ::ffff:        IPv4-mapped IPv6
- */
-const PRIVATE_IP_PATTERN =
-  /^(127\.|localhost$|10\.|169\.254\.|172\.(1[6-9]|2\d|3[01])\.|192\.168\.|0\.0\.0\.0$|\[::1\]$|::1$|::ffff:|\[::ffff:|f[cd][0-9a-f]{0,2}:|\[f[cd][0-9a-f]{0,2}:)/i;
-
-/**
- * Validates whether a URL is eligible for outbound freshness checks.
- *
- * @remarks Security control for SSRF risk reduction. Blocks non-HTTP(S) schemes and host
- * patterns that target loopback/private address space or raw IP-style local endpoints
- * (for example localhost, RFC1918 IPv4 ranges, loopback/link-local, and mapped/ULA IPv6).
- */
-export function isAllowedUrl(url: string): { allowed: boolean; reason?: string } {
-  try {
-    const parsed = new URL(url);
-    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-      return { allowed: false, reason: `Disallowed URL scheme — only http and https are permitted: ${url}` };
-    }
-    if (PRIVATE_IP_PATTERN.test(parsed.hostname)) {
-      return { allowed: false, reason: `Requests to private/loopback addresses are not permitted: ${url}` };
-    }
-    return { allowed: true };
-  } catch {
-    return { allowed: false, reason: `Invalid URL: ${url}` };
-  }
-}
-
-/**
- * Performs a conditional HTTP HEAD freshness check.
- *
- * @param input - URL plus optional stored validators (`etag`, `last_modified`).
- * @returns Freshness verdict and response metadata for one URL.
- * @remarks Uses a 10-second abort timeout, sends conditional headers when available,
- * maps 304→fresh and 200→stale, and reports all other outcomes as `error`.
- */
-export async function checkFreshness(input: FreshnessCheckInput): Promise<FreshnessCheckOutput> {
-  const allowCheck = isAllowedUrl(input.url);
-  if (!allowCheck.allowed) {
-    const reason = allowCheck.reason ?? `Freshness check blocked for URL: ${input.url}`;
-    return {
-      url: input.url,
-      status: "error",
-      error: reason,
-    };
-  }
-
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), 10_000);
-
-  try {
-    const headers: Record<string, string> = {};
-    if (input.etag) {
-      headers["If-None-Match"] = input.etag;
-    }
-    if (input.last_modified) {
-      headers["If-Modified-Since"] = input.last_modified;
-    }
-
-    const response = await fetch(input.url, {
-      method: "HEAD",
-      headers,
-      signal: controller.signal,
-    });
-
-    if (response.status === 304) {
-      return {
-        url: input.url,
-        status: "fresh",
-        http_status: 304,
-      };
-    }
-
-    if (response.status === 200) {
-      const etag = response.headers.get("etag") ?? undefined;
-      const lastModified = response.headers.get("last-modified") ?? undefined;
-      return {
-        url: input.url,
-        status: "stale",
-        http_status: 200,
-        ...(etag !== undefined ? { etag } : {}),
-        ...(lastModified !== undefined ? { last_modified: lastModified } : {}),
-      };
-    }
-
-    // 4xx/5xx
-    return {
-      url: input.url,
-      status: "error",
-      http_status: response.status,
-      error: `HTTP ${response.status}: ${response.statusText}`,
-    };
-  } catch (err) {
-    const error = err as Error;
-    return {
-      url: input.url,
-      status: "error",
-      error: error.message,
-    };
-  } finally {
-    clearTimeout(timeoutId);
-  }
-}