@thecat69/cache-ctrl 1.0.0 → 1.2.0

package/src/commands/writeExternal.ts

@@ -0,0 +1,51 @@
+import { join } from "node:path";
+
+import { findRepoRoot, resolveCacheDir, writeCache } from "../cache/cacheManager.js";
+import type { WriteArgs, WriteResult } from "../types/commands.js";
+import { ExternalCacheFileSchema } from "../types/cache.js";
+import { ErrorCode, type Result } from "../types/result.js";
+import { toUnknownResult } from "../utils/errors.js";
+import { formatZodError, validateSubject } from "../utils/validate.js";
+
+/**
+ * Validates and writes one external cache entry.
+ *
+ * @param args - {@link WriteArgs} command arguments for the external agent.
+ * @returns Promise<Result<WriteResult["value"]>>; common failures include INVALID_ARGS,
+ * VALIDATION_ERROR, FILE_WRITE_ERROR, LOCK_TIMEOUT/LOCK_ERROR, and UNKNOWN.
+ */
+export async function writeExternalCommand(args: WriteArgs): Promise<Result<WriteResult["value"]>> {
+  try {
+    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 (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,
+      };
+    }
+
+    const contentWithSubject = { ...args.content, subject: args.subject };
+
+    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 repoRoot = await findRepoRoot(process.cwd());
+    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 } };
+  } catch (err) {
+    return toUnknownResult(err);
+  }
+}

package/src/commands/writeLocal.ts

@@ -0,0 +1,121 @@
+import { join } from "node:path";
+
+import { findRepoRoot, readCache, resolveCacheDir, writeCache } from "../cache/cacheManager.js";
+import { filterExistingFiles, resolveTrackedFileStats } from "../files/changeDetector.js";
+import type { WriteArgs, WriteResult } from "../types/commands.js";
+import { type FileFacts, LocalCacheFileSchema, type TrackedFile, TrackedFileSchema } from "../types/cache.js";
+import { ErrorCode, type Result } from "../types/result.js";
+import { toUnknownResult } from "../utils/errors.js";
+import { formatZodError } from "../utils/validate.js";
+
+function evictFactsForDeletedPaths(
+  facts: Record<string, unknown>,
+  survivingFiles: TrackedFile[],
+): Record<string, unknown> {
+  const survivingPaths = new Set(survivingFiles.map((file) => file.path));
+  return Object.fromEntries(Object.entries(facts).filter(([path]) => survivingPaths.has(path)));
+}
+
+function hasStringPath(entry: unknown): entry is { path: string } {
+  if (typeof entry !== "object" || entry === null) {
+    return false;
+  }
+  const pathValue = Reflect.get(entry, "path");
+  return typeof pathValue === "string";
+}
+
+function getSubmittedTrackedPaths(rawTrackedFiles: unknown): string[] {
+  if (!Array.isArray(rawTrackedFiles)) return [];
+
+  return rawTrackedFiles.filter(hasStringPath).map((entry) => entry.path);
+}
+
+/**
+ * Validates and writes local context cache content with per-path merge semantics.
+ *
+ * @param args - {@link WriteArgs} command arguments for the local agent.
+ * @returns Promise<Result<WriteResult["value"]>>; common failures include VALIDATION_ERROR,
+ * FILE_READ_ERROR/FILE_WRITE_ERROR, LOCK_TIMEOUT/LOCK_ERROR, and UNKNOWN.
+ */
+export async function writeLocalCommand(args: WriteArgs): Promise<Result<WriteResult["value"]>> {
+  try {
+    const repoRoot = await findRepoRoot(process.cwd());
+
+    const contentWithTimestamp: Record<string, unknown> = {
+      ...args.content,
+      timestamp: new Date().toISOString(),
+    };
+
+    const submittedPaths = getSubmittedTrackedPaths(contentWithTimestamp["tracked_files"]);
+    const guardedPaths = new Set(submittedPaths);
+    const resolvedTrackedFiles = await resolveTrackedFileStats(submittedPaths.map((path) => ({ path })), repoRoot);
+    const survivingSubmitted = resolvedTrackedFiles.filter((trackedFile) => trackedFile.mtime !== 0);
+
+    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));
+      if (violatingPaths.length > 0) {
+        return {
+          ok: false,
+          error: `facts contains paths not in submitted tracked_files: ${violatingPaths.join(", ")}`,
+          code: ErrorCode.VALIDATION_ERROR,
+        };
+      }
+    }
+
+    const localCacheDir = resolveCacheDir("local", repoRoot);
+    const filePath = join(localCacheDir, "context.json");
+
+    const readResult = await readCache(filePath);
+    let existingContent: Record<string, unknown> = {};
+    let existingTrackedFiles: TrackedFile[] = [];
+    let existingFacts: Record<string, FileFacts> = {};
+
+    if (readResult.ok) {
+      existingContent = readResult.value;
+      const localParseResult = LocalCacheFileSchema.safeParse(existingContent);
+      if (localParseResult.success) {
+        existingTrackedFiles = localParseResult.data.tracked_files;
+        existingFacts = localParseResult.data.facts ?? {};
+      } else {
+        const trackedFilesResult = TrackedFileSchema.array().safeParse(existingContent["tracked_files"]);
+        existingTrackedFiles = trackedFilesResult.success ? trackedFilesResult.data : [];
+      }
+    } else if (readResult.code !== ErrorCode.FILE_NOT_FOUND) {
+      return { ok: false, error: readResult.error, code: readResult.code };
+    }
+
+    const submittedTrackedPaths = new Set(survivingSubmitted.map((trackedFile) => trackedFile.path));
+    const existingNotSubmitted = existingTrackedFiles.filter((trackedFile) => !submittedTrackedPaths.has(trackedFile.path));
+    const survivingExisting = await filterExistingFiles(existingNotSubmitted, repoRoot);
+    const mergedTrackedFiles = [...survivingExisting, ...survivingSubmitted];
+
+    const rawMergedFacts = { ...existingFacts, ...submittedFacts };
+    const mergedFacts = evictFactsForDeletedPaths(rawMergedFacts, mergedTrackedFiles);
+
+    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 };
+    }
+
+    const writeResult = await writeCache(filePath, processedContent, "replace");
+    if (!writeResult.ok) return writeResult;
+    return { ok: true, value: { file: filePath } };
+  } catch (err) {
+    return toUnknownResult(err);
+  }
+}

package/src/files/changeDetector.ts

@@ -3,12 +3,26 @@ import { createHash } from "node:crypto";
 import { resolve, isAbsolute } from "node:path";
 import type { TrackedFile } from "../types/cache.js";
 
+/**
+ * Comparison outcome for one tracked file baseline.
+ *
+ * `status` and `reason` are coupled: `changed` uses `mtime`/`hash`, `missing` uses `missing`,
+ * and `unchanged` omits `reason`. `missing` covers both deleted files and traversal-rejected
+ * paths blocked by path-safety guards.
+ */
 export interface FileComparisonResult {
   path: string;
   status: "changed" | "unchanged" | "missing";
   reason?: "mtime" | "hash" | "missing";
 }
 
+/**
+ * Compares one tracked file against current filesystem state.
+ *
+ * Uses `mtime` as a fast path and falls back to SHA-256 hash comparison when stored hash is
+ * available and `mtime` changed. Paths that escape `repoRoot` are rejected by traversal guard
+ * and reported as `missing`. `ENOENT` is also reported as `missing`.
+ */
 export async function compareTrackedFile(file: TrackedFile, repoRoot: string): Promise<FileComparisonResult> {
   const absolutePath = resolveTrackedFilePath(file.path, repoRoot);
 
@@ -47,6 +61,7 @@ export async function compareTrackedFile(file: TrackedFile, repoRoot: string): P
   }
 }
 
+/** Computes SHA-256 hex digest for a file's current bytes. */
 export async function computeFileHash(filePath: string): Promise<string> {
   const content = await readFile(filePath);
   return createHash("sha256").update(content).digest("hex");

package/src/files/gitFiles.ts

@@ -10,6 +10,11 @@ function parseGitOutput(stdout: string): string[] {
     .filter((l) => l.length > 0);
 }
 
+/**
+ * Returns git-tracked file paths for a repository.
+ *
+ * Falls back to `[]` when git is unavailable, command execution fails, or directory is not a git repo.
+ */
 export async function getGitTrackedFiles(repoRoot: string): Promise<string[]> {
   try {
     const result = await execFileAsync("git", ["ls-files"], { cwd: repoRoot, maxBuffer: 10 * 1024 * 1024 });
@@ -19,6 +24,11 @@ export async function getGitTrackedFiles(repoRoot: string): Promise<string[]> {
   }
 }
 
+/**
+ * Returns git-tracked files deleted from the working tree.
+ *
+ * Falls back to `[]` when git is unavailable, command execution fails, or directory is not a git repo.
+ */
 export async function getGitDeletedFiles(repoRoot: string): Promise<string[]> {
   try {
     const result = await execFileAsync("git", ["ls-files", "--deleted"], { cwd: repoRoot, maxBuffer: 10 * 1024 * 1024 });
@@ -28,6 +38,11 @@ export async function getGitDeletedFiles(repoRoot: string): Promise<string[]> {
   }
 }
 
+/**
+ * Returns untracked files that are not ignored by git.
+ *
+ * Falls back to `[]` when git is unavailable, command execution fails, or directory is not a git repo.
+ */
 export async function getUntrackedNonIgnoredFiles(repoRoot: string): Promise<string[]> {
   try {
     const result = await execFileAsync("git", ["ls-files", "--others", "--exclude-standard"], {

package/src/files/openCodeInstaller.ts

@@ -4,9 +4,18 @@ import path from "node:path";
 
 import type { InstallResult } from "../types/commands.js";
 import { ErrorCode, type Result } from "../types/result.js";
+import { toUnknownResult } from "../utils/errors.js";
 
 const SKILL_NAMES = ["cache-ctrl-external", "cache-ctrl-local", "cache-ctrl-caller"] as const;
 
+/**
+ * Resolves the OpenCode configuration directory.
+ *
+ * @param overrideDir - Explicit CLI override path.
+ * @returns Absolute config directory path used for tool and skill installation.
+ * @remarks Resolution order: explicit override → `%APPDATA%/opencode` on Windows →
+ * `$XDG_CONFIG_HOME/opencode` on Unix-like systems → `~/.config/opencode` fallback.
+ */
 export function resolveOpenCodeConfigDir(overrideDir?: string): string {
   if (overrideDir !== undefined) {
     return overrideDir;
@@ -21,6 +30,7 @@ export function resolveOpenCodeConfigDir(overrideDir?: string): string {
   return path.join(xdgConfigHome, "opencode");
 }
 
+/** Builds the generated OpenCode tool wrapper file content. */
 export function buildToolWrapperContent(packageRoot: string): string {
   const normalizedPackageRoot = packageRoot.replace(/\\/g, "/");
 
@@ -31,6 +41,15 @@ export function buildToolWrapperContent(packageRoot: string): string {
   ].join("\n");
 }
 
+/**
+ * Installs or refreshes OpenCode tool + skill integration files.
+ *
+ * @param configDir - Target OpenCode config directory.
+ * @param packageRoot - Installed package root used to resolve bundled assets.
+ * @returns Written tool path and copied skill file paths.
+ * @remarks Operation is idempotent: reruns overwrite the wrapper and recopy skill files
+ * to align the config directory with the currently installed package version.
+ */
 export async function installOpenCodeIntegration(configDir: string, packageRoot: string): Promise<Result<InstallResult>> {
   try {
     const toolDir = path.join(configDir, "tools");
@@ -60,7 +79,7 @@ export async function installOpenCodeIntegration(configDir: string, packageRoot:
       },
     };
   } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return { ok: false, error: message, code: ErrorCode.FILE_WRITE_ERROR };
+    const unknownError = toUnknownResult(err);
+    return { ...unknownError, code: ErrorCode.FILE_WRITE_ERROR };
   }
 }