@thecat69/cache-ctrl 1.0.0

package/src/commands/touch.ts

@@ -0,0 +1,47 @@
+import { findRepoRoot, listCacheFiles, writeCache } from "../cache/cacheManager.js";
+import { resolveTopExternalMatch } from "../cache/externalCache.js";
+import { resolveLocalCachePath } from "../cache/localCache.js";
+import { ErrorCode, type Result } from "../types/result.js";
+import type { TouchArgs, TouchResult } from "../types/commands.js";
+import { validateSubject } from "../utils/validate.js";
+
+export async function touchCommand(args: TouchArgs): Promise<Result<TouchResult["value"]>> {
+  try {
+    const repoRoot = await findRepoRoot(process.cwd());
+    const newTimestamp = new Date().toISOString();
+    const touched: string[] = [];
+
+    if (args.agent === "external") {
+      let filesToTouch: 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;
+        filesToTouch = [matchResult.value];
+      } else {
+        const filesResult = await listCacheFiles("external", repoRoot);
+        if (!filesResult.ok) return filesResult;
+        filesToTouch = filesResult.value;
+      }
+
+      for (const filePath of filesToTouch) {
+        const writeResult = await writeCache(filePath, { fetched_at: newTimestamp });
+        if (!writeResult.ok) return writeResult;
+        touched.push(filePath);
+      }
+    } else {
+      // local
+      const localPath = resolveLocalCachePath(repoRoot);
+      const writeResult = await writeCache(localPath, { timestamp: newTimestamp });
+      if (!writeResult.ok) return writeResult;
+      touched.push(localPath);
+    }
+
+    return { ok: true, value: { touched, new_timestamp: newTimestamp } };
+  } catch (err) {
+    const error = err as Error;
+    return { ok: false, error: error.message, code: ErrorCode.UNKNOWN };
+  }
+}

package/src/commands/write.ts

@@ -0,0 +1,170 @@
+import { join } from "node:path";
+import { ExternalCacheFileSchema, LocalCacheFileSchema } from "../types/cache.js";
+import { ErrorCode, type Result } from "../types/result.js";
+import type { WriteArgs, WriteResult } from "../types/commands.js";
+import { writeCache, findRepoRoot, resolveCacheDir, readCache } from "../cache/cacheManager.js";
+import { validateSubject, formatZodError } from "../utils/validate.js";
+import { resolveTrackedFileStats, filterExistingFiles } from "../files/changeDetector.js";
+import type { TrackedFile } from "../types/cache.js";
+import { TrackedFileSchema } from "../types/cache.js";
+
+function evictFactsForDeletedPaths(
+  facts: Record<string, string[]>,
+  survivingFiles: TrackedFile[],
+): Record<string, string[]> {
+  const survivingPaths = new Set(survivingFiles.map((f) => f.path));
+  return Object.fromEntries(Object.entries(facts).filter(([path]) => survivingPaths.has(path)));
+}
+
+export async function writeCommand(args: WriteArgs): Promise<Result<WriteResult["value"]>> {
+  try {
+    const repoRoot = await findRepoRoot(process.cwd());
+
+    if (args.agent === "external") {
+      // subject is required
+      if (!args.subject) {
+        return { ok: false, error: "subject is required for external agent", code: ErrorCode.INVALID_ARGS };
+      }
+
+      const subjectValidation = validateSubject(args.subject);
+      if (!subjectValidation.ok) return subjectValidation;
+
+      // if content.subject is set but mismatches the subject param → error
+      if (args.content["subject"] !== undefined && args.content["subject"] !== args.subject) {
+        return {
+          ok: false,
+          error: `content.subject "${String(args.content["subject"])}" does not match subject argument "${args.subject}"`,
+          code: ErrorCode.VALIDATION_ERROR,
+        };
+      }
+
+      // inject subject into content if absent
+      const contentWithSubject = { ...args.content, subject: args.subject };
+
+      // validate against ExternalCacheFileSchema
+      const parsed = ExternalCacheFileSchema.safeParse(contentWithSubject);
+      if (!parsed.success) {
+        const message = formatZodError(parsed.error);
+        return { ok: false, error: `Validation failed: ${message}`, code: ErrorCode.VALIDATION_ERROR };
+      }
+
+      const cacheDir = resolveCacheDir("external", repoRoot);
+      const filePath = join(cacheDir, `${args.subject}.json`);
+      const writeResult = await writeCache(filePath, contentWithSubject);
+      if (!writeResult.ok) return writeResult;
+      return { ok: true, value: { file: filePath } };
+    }
+
+    // local — auto-inject server-side timestamp; agent must not control this field
+    const contentWithTimestamp: Record<string, unknown> = {
+      ...args.content,
+      timestamp: new Date().toISOString(),
+    };
+
+    // Resolve real mtimes for submitted tracked_files if present
+    const rawTrackedFiles = contentWithTimestamp["tracked_files"];
+    let survivingSubmitted: TrackedFile[] = [];
+    let guardedPaths = new Set<string>();
+
+    if (Array.isArray(rawTrackedFiles)) {
+      const validEntries = rawTrackedFiles
+        .filter(
+          (entry): entry is { path: string } =>
+            entry !== null &&
+            typeof entry === "object" &&
+            typeof (entry as Record<string, unknown>)["path"] === "string",
+        )
+        .map((entry) => ({ path: entry.path }));
+
+      guardedPaths = new Set(validEntries.map((e) => e.path));
+
+      const resolved = await resolveTrackedFileStats(validEntries, repoRoot);
+      // Evict submitted entries for files that are missing or path-traversal-rejected
+      survivingSubmitted = resolved.filter((f) => f.mtime !== 0);
+    }
+
+    // Guard: submitted facts paths must be a strict subset of submitted tracked_files paths
+    const rawSubmittedFacts = contentWithTimestamp["facts"];
+    if (
+      rawSubmittedFacts !== null &&
+      rawSubmittedFacts !== undefined &&
+      typeof rawSubmittedFacts === "object" &&
+      !Array.isArray(rawSubmittedFacts)
+    ) {
+      const violatingPaths = Object.keys(rawSubmittedFacts as Record<string, string[]>).filter(
+        (p) => !guardedPaths.has(p),
+      );
+      if (violatingPaths.length > 0) {
+        return {
+          ok: false,
+          error: `facts contains paths not in submitted tracked_files: ${violatingPaths.join(", ")}`,
+          code: ErrorCode.VALIDATION_ERROR,
+        };
+      }
+    }
+
+    // Read existing cache to perform per-path merge
+    const localCacheDir = resolveCacheDir("local", repoRoot);
+    const filePath = join(localCacheDir, "context.json");
+
+    const readResult = await readCache(filePath);
+    let existingContent: Record<string, unknown> = {};
+    let existingTrackedFiles: TrackedFile[] = [];
+
+    if (readResult.ok) {
+      existingContent = readResult.value;
+      // Validate the on-disk tracked_files against the schema — fall back to [] on corrupt/missing data
+      const parseResult = TrackedFileSchema.array().safeParse(existingContent["tracked_files"]);
+      existingTrackedFiles = parseResult.success ? parseResult.data : [];
+    } else if (readResult.code !== ErrorCode.FILE_NOT_FOUND) {
+      return { ok: false, error: readResult.error, code: readResult.code };
+    }
+
+    // Keep existing entries whose paths are NOT being replaced by the submitted set
+    const submittedPaths = new Set(survivingSubmitted.map((f) => f.path));
+    const existingNotSubmitted = existingTrackedFiles.filter((f) => !submittedPaths.has(f.path));
+
+    // Evict deleted files from the preserved existing entries
+    const survivingExisting = await filterExistingFiles(existingNotSubmitted, repoRoot);
+
+    const mergedTrackedFiles = [...survivingExisting, ...survivingSubmitted];
+
+    // Per-path merge for facts (mirrors tracked_files merge)
+    const existingFactsRaw = existingContent["facts"];
+    const submittedFactsRaw = contentWithTimestamp["facts"];
+
+    const existingFacts =
+      typeof existingFactsRaw === "object" && existingFactsRaw !== null && !Array.isArray(existingFactsRaw)
+        ? (existingFactsRaw as Record<string, string[]>)
+        : {};
+    const submittedFacts =
+      typeof submittedFactsRaw === "object" && submittedFactsRaw !== null && !Array.isArray(submittedFactsRaw)
+        ? (submittedFactsRaw as Record<string, string[]>)
+        : {};
+
+    const rawMergedFacts = { ...existingFacts, ...submittedFacts };
+    const mergedFacts = evictFactsForDeletedPaths(rawMergedFacts, mergedTrackedFiles);
+
+    // Merge top-level fields: existing base → then submitted content (submitted wins)
+    const processedContent: Record<string, unknown> = {
+      ...existingContent,
+      ...contentWithTimestamp,
+      tracked_files: mergedTrackedFiles,
+      facts: mergedFacts,
+    };
+
+    const parsed = LocalCacheFileSchema.safeParse(processedContent);
+    if (!parsed.success) {
+      const message = formatZodError(parsed.error);
+      return { ok: false, error: `Validation failed: ${message}`, code: ErrorCode.VALIDATION_ERROR };
+    }
+
+    // processedContent is used (not parsed.data) to preserve loose fields not known to the schema — intentional merge semantics
+    const writeResult = await writeCache(filePath, processedContent, "replace");
+    if (!writeResult.ok) return writeResult;
+    return { ok: true, value: { file: filePath } };
+  } catch (err) {
+    const error = err as Error;
+    return { ok: false, error: error.message, code: ErrorCode.UNKNOWN };
+  }
+}

package/src/files/changeDetector.ts

@@ -0,0 +1,122 @@
+import { readFile, lstat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { resolve, isAbsolute } from "node:path";
+import type { TrackedFile } from "../types/cache.js";
+
+export interface FileComparisonResult {
+  path: string;
+  status: "changed" | "unchanged" | "missing";
+  reason?: "mtime" | "hash" | "missing";
+}
+
+export async function compareTrackedFile(file: TrackedFile, repoRoot: string): Promise<FileComparisonResult> {
+  const absolutePath = resolveTrackedFilePath(file.path, repoRoot);
+
+  if (absolutePath === null) {
+    // Path traversal attempt — treat as missing
+    return { path: file.path, status: "missing", reason: "missing" };
+  }
+
+  try {
+    // lstat: mtime reflects the symlink node, not the target; hash check covers content drift when hash is stored
+    const fileStat = await lstat(absolutePath);
+    const currentMtime = fileStat.mtimeMs;
+
+    if (currentMtime === file.mtime) {
+      return { path: file.path, status: "unchanged" };
+    }
+
+    // mtime differs
+    if (file.hash) {
+      const currentHash = await computeFileHash(absolutePath);
+      if (currentHash === file.hash) {
+        // Hash matches despite mtime change — just a touch
+        return { path: file.path, status: "unchanged" };
+      }
+      return { path: file.path, status: "changed", reason: "hash" };
+    }
+
+    // No hash stored — mtime change alone is sufficient
+    return { path: file.path, status: "changed", reason: "mtime" };
+  } catch (err) {
+    if (err instanceof Error && "code" in err && (err as NodeJS.ErrnoException).code === "ENOENT") {
+      return { path: file.path, status: "missing", reason: "missing" };
+    }
+    // Re-throw unexpected errors
+    throw err;
+  }
+}
+
+export async function computeFileHash(filePath: string): Promise<string> {
+  const content = await readFile(filePath);
+  return createHash("sha256").update(content).digest("hex");
+}
+
+/**
+ * Resolves a tracked file path against the repo root.
+ * Returns null if the resolved path escapes the repo root (path traversal guard).
+ */
+export function resolveTrackedFilePath(inputPath: string, repoRoot: string): string | null {
+  const resolved = isAbsolute(inputPath) ? resolve(inputPath) : resolve(repoRoot, inputPath);
+  // Normalize root to ensure trailing slash for prefix matching
+  const normalizedRoot = repoRoot.endsWith("/") ? repoRoot : repoRoot + "/";
+  if (!resolved.startsWith(normalizedRoot) && resolved !== repoRoot) {
+    return null; // path traversal rejected
+  }
+  return resolved;
+}
+
+/**
+ * Checks existence of already-tracked files via lstat(). Used during write to evict stale entries
+ * (deleted files). Does NOT recompute mtime or hash — only confirms the file is still present on disk.
+ */
+export async function filterExistingFiles(files: TrackedFile[], repoRoot: string): Promise<TrackedFile[]> {
+  const results = await Promise.all(
+    files.map(async (file): Promise<TrackedFile | null> => {
+      const absolutePath = resolveTrackedFilePath(file.path, repoRoot);
+      if (absolutePath === null) {
+        // Path traversal rejected — evict
+        return null;
+      }
+      try {
+        await lstat(absolutePath);
+        return file;
+      } catch (err) {
+        if (err instanceof Error && "code" in err && (err as NodeJS.ErrnoException).code === "ENOENT") {
+          return null;
+        }
+        throw err;
+      }
+    }),
+  );
+  return results.filter((entry): entry is TrackedFile => entry !== null);
+}
+
+/**
+ * Resolves filesystem stats (mtime and hash) for a list of path-only tracked file entries.
+ * For each entry: if the path is valid and the file exists, computes mtime via lstat().mtimeMs
+ * and hash via SHA-256 in parallel, returning { path, mtime, hash }.
+ * Falls back to { path, mtime: 0 } (no hash) on path traversal rejection or missing file.
+ * Never throws — always returns gracefully.
+ */
+export async function resolveTrackedFileStats(
+  files: Array<{ path: string }>,
+  repoRoot: string,
+): Promise<TrackedFile[]> {
+  return Promise.all(
+    files.map(async (file) => {
+      const absolutePath = resolveTrackedFilePath(file.path, repoRoot);
+      if (absolutePath === null) {
+        return { path: file.path, mtime: 0 };
+      }
+      try {
+        // lstat: mtime reflects the symlink node; hash is computed from the target content via readFile
+        const [fileStat, hash] = await Promise.all([lstat(absolutePath), computeFileHash(absolutePath)]);
+        return { path: file.path, mtime: fileStat.mtimeMs, hash };
+      } catch {
+        // Always return gracefully per the "never throws" contract — do not propagate filesystem errors
+        return { path: file.path, mtime: 0 };
+      }
+    }),
+  );
+}

package/src/files/gitFiles.ts

@@ -0,0 +1,41 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+function parseGitOutput(stdout: string): string[] {
+  return stdout
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0);
+}
+
+export async function getGitTrackedFiles(repoRoot: string): Promise<string[]> {
+  try {
+    const result = await execFileAsync("git", ["ls-files"], { cwd: repoRoot, maxBuffer: 10 * 1024 * 1024 });
+    return parseGitOutput(result.stdout);
+  } catch {
+    return [];
+  }
+}
+
+export async function getGitDeletedFiles(repoRoot: string): Promise<string[]> {
+  try {
+    const result = await execFileAsync("git", ["ls-files", "--deleted"], { cwd: repoRoot, maxBuffer: 10 * 1024 * 1024 });
+    return parseGitOutput(result.stdout);
+  } catch {
+    return [];
+  }
+}
+
+export async function getUntrackedNonIgnoredFiles(repoRoot: string): Promise<string[]> {
+  try {
+    const result = await execFileAsync("git", ["ls-files", "--others", "--exclude-standard"], {
+      cwd: repoRoot,
+      maxBuffer: 10 * 1024 * 1024,
+    });
+    return parseGitOutput(result.stdout).filter((p) => !p.endsWith("/"));
+  } catch {
+    return [];
+  }
+}

package/src/files/openCodeInstaller.ts

@@ -0,0 +1,66 @@
+import { copyFile, mkdir, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import type { InstallResult } from "../types/commands.js";
+import { ErrorCode, type Result } from "../types/result.js";
+
+const SKILL_NAMES = ["cache-ctrl-external", "cache-ctrl-local", "cache-ctrl-caller"] as const;
+
+export function resolveOpenCodeConfigDir(overrideDir?: string): string {
+  if (overrideDir !== undefined) {
+    return overrideDir;
+  }
+
+  if (process.platform === "win32") {
+    const appData = process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming");
+    return path.join(appData, "opencode");
+  }
+
+  const xdgConfigHome = process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config");
+  return path.join(xdgConfigHome, "opencode");
+}
+
+export function buildToolWrapperContent(packageRoot: string): string {
+  const normalizedPackageRoot = packageRoot.replace(/\\/g, "/");
+
+  return [
+    "// Auto-generated by cache-ctrl install — do not edit manually",
+    "// Re-run 'cache-ctrl install' after 'npm update -g @thecat69/cache-ctrl'",
+    `export * from \"${normalizedPackageRoot}/cache_ctrl.ts\";`,
+  ].join("\n");
+}
+
+export async function installOpenCodeIntegration(configDir: string, packageRoot: string): Promise<Result<InstallResult>> {
+  try {
+    const toolDir = path.join(configDir, "tools");
+    const toolPath = path.join(toolDir, "cache_ctrl.ts");
+
+    await mkdir(toolDir, { recursive: true, mode: 0o755 });
+    await writeFile(toolPath, buildToolWrapperContent(packageRoot), { encoding: "utf-8", mode: 0o644 });
+
+    const skillPaths: string[] = [];
+
+    for (const skillName of SKILL_NAMES) {
+      const targetSkillDir = path.join(configDir, "skills", skillName);
+      const sourceSkillPath = path.join(packageRoot, "skills", skillName, "SKILL.md");
+      const targetSkillPath = path.join(targetSkillDir, "SKILL.md");
+
+      await mkdir(targetSkillDir, { recursive: true, mode: 0o755 });
+      await copyFile(sourceSkillPath, targetSkillPath);
+      skillPaths.push(targetSkillPath);
+    }
+
+    return {
+      ok: true,
+      value: {
+        toolPath,
+        skillPaths,
+        configDir,
+      },
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: message, code: ErrorCode.FILE_WRITE_ERROR };
+  }
+}

package/src/http/freshnessChecker.ts

@@ -0,0 +1,116 @@
+export interface FreshnessCheckInput {
+  url: string;
+  etag?: string;
+  last_modified?: string;
+}
+
+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:|f[cd][0-9a-f]{0,2}:|\[f[cd][0-9a-f]{0,2}:)/i;
+
+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}` };
+  }
+}
+
+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);
+  }
+}