@thecat69/cache-ctrl 1.0.0

package/src/types/commands.ts

@@ -0,0 +1,192 @@
+import type { AgentType, ExternalCacheFile, LocalCacheFile } from "./cache.js";
+
+// ── list ──────────────────────────────────────────────────────────────────────
+
+export interface ListArgs {
+  agent?: AgentType | "all";
+}
+
+export interface ListEntry {
+  file: string;
+  agent: AgentType;
+  subject: string;
+  description?: string;
+  fetched_at: string;
+  age_human: string;
+  is_stale: boolean;
+}
+
+export type ListResult = { ok: true; value: ListEntry[] };
+
+// ── inspect ───────────────────────────────────────────────────────────────────
+
+export interface InspectArgs {
+  agent: AgentType;
+  subject: string;
+  /** Path-keyword filter for local agent. Only facts entries whose file path contains
+   *  at least one keyword (case-insensitive substring) are included. global_facts is
+   *  always included. Ignored for external agent. */
+  filter?: string[];
+  /** Recursive folder prefix filter for local agent. Only facts entries whose file path
+   *  equals the normalized folder or starts with `<normalizedFolder>/` are included.
+   *  global_facts is always included. INVALID_ARGS if used with external agent. */
+  folder?: string;
+  /** Fact-content keyword filter for local agent. Only facts entries where at least one
+   *  fact string contains at least one keyword (case-insensitive OR) are included.
+   *  Silently ignored for external agent by design — external cache entries have no facts
+   *  map. Use `folder` if you need to guard against passing search-facts to external; note
+   *  that `folder` is an error on external while this is not. */
+  searchFacts?: string[];
+}
+
+export type InspectResult = {
+  ok: true;
+  value: (ExternalCacheFile | LocalCacheFile) & {
+    file: string;
+    agent: AgentType;
+  };
+};
+
+// ── flush ─────────────────────────────────────────────────────────────────────
+
+export interface FlushArgs {
+  agent: AgentType | "all";
+  confirm: boolean;
+}
+
+export type FlushResult = {
+  ok: true;
+  value: {
+    deleted: string[];
+    count: number;
+  };
+};
+
+// ── invalidate ────────────────────────────────────────────────────────────────
+
+export interface InvalidateArgs {
+  agent: AgentType;
+  subject?: string;
+}
+
+export type InvalidateResult = {
+  ok: true;
+  value: {
+    invalidated: string[];
+  };
+};
+
+// ── touch ─────────────────────────────────────────────────────────────────────
+
+export interface TouchArgs {
+  agent: AgentType;
+  subject?: string;
+}
+
+export type TouchResult = {
+  ok: true;
+  value: {
+    touched: string[];
+    new_timestamp: string;
+  };
+};
+
+// ── prune ─────────────────────────────────────────────────────────────────────
+
+export interface PruneArgs {
+  agent?: AgentType | "all";
+  maxAge?: string;
+  delete?: boolean;
+}
+
+export type PruneResult = {
+  ok: true;
+  value: {
+    matched: Array<{ file: string; agent: AgentType; subject: string }>;
+    action: "invalidated" | "deleted";
+    count: number;
+  };
+};
+
+// ── check-freshness ───────────────────────────────────────────────────────────
+
+export interface CheckFreshnessArgs {
+  subject: string;
+  url?: string;
+}
+
+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 ───────────────────────────────────────────────────────────────
+
+export type CheckFilesResult = {
+  ok: true;
+  value: {
+    status: "changed" | "unchanged";
+    changed_files: Array<{
+      path: string;
+      reason: "mtime" | "hash" | "missing";
+    }>;
+    unchanged_files: string[];
+    missing_files: string[];
+    new_files: string[];
+    deleted_git_files: string[];
+  };
+};
+
+// ── search ────────────────────────────────────────────────────────────────────
+
+export interface SearchArgs {
+  keywords: string[];
+}
+
+export type SearchResult = {
+  ok: true;
+  value: Array<{
+    file: string;
+    subject: string;
+    description?: string;
+    agent: AgentType;
+    fetched_at: string;
+    score: number;
+  }>;
+};
+
+// ── write ─────────────────────────────────────────────────────────────────────
+
+export interface WriteArgs {
+  agent: AgentType;
+  subject?: string; // required for external, unused for local
+  content: Record<string, unknown>;
+}
+
+export type WriteResult = {
+  ok: true;
+  value: {
+    file: string;
+  };
+};
+
+// ── install ───────────────────────────────────────────────────────────────────
+
+export interface InstallArgs {
+  configDir?: string;
+}
+
+export interface InstallResult {
+  toolPath: string;
+  skillPaths: string[];
+  configDir: string;
+}

package/src/types/result.ts

@@ -0,0 +1,36 @@
+export enum ErrorCode {
+  // File system errors
+  FILE_NOT_FOUND = "FILE_NOT_FOUND",
+  FILE_READ_ERROR = "FILE_READ_ERROR",
+  FILE_WRITE_ERROR = "FILE_WRITE_ERROR",
+  PARSE_ERROR = "PARSE_ERROR",
+
+  // Lock errors
+  LOCK_TIMEOUT = "LOCK_TIMEOUT",
+  LOCK_ERROR = "LOCK_ERROR",
+
+  // Validation errors
+  INVALID_ARGS = "INVALID_ARGS",
+  CONFIRMATION_REQUIRED = "CONFIRMATION_REQUIRED",
+  VALIDATION_ERROR = "VALIDATION_ERROR",
+
+  // Search/match errors
+  NO_MATCH = "NO_MATCH",
+  AMBIGUOUS_MATCH = "AMBIGUOUS_MATCH",
+
+  // HTTP errors
+  HTTP_REQUEST_FAILED = "HTTP_REQUEST_FAILED",
+  URL_NOT_FOUND = "URL_NOT_FOUND",
+
+  // Internal
+  UNKNOWN = "UNKNOWN",
+}
+
+export interface CacheError {
+  code: ErrorCode;
+  error: string;
+}
+
+export type Result<T, E extends CacheError = CacheError> =
+  | { ok: true; value: T }
+  | { ok: false; error: string; code: E["code"] };

package/src/utils/fileStem.ts

@@ -0,0 +1,7 @@
+import { basename } from "node:path";
+
+/** Returns the file name without its `.json` extension, or the name as-is if not `.json`. */
+export function getFileStem(filePath: string): string {
+  const name = basename(filePath);
+  return name.endsWith(".json") ? name.slice(0, -5) : name;
+}

package/src/utils/validate.ts

@@ -0,0 +1,50 @@
+import type { ZodError } from "zod";
+
+import { ErrorCode, type Result } from "../types/result.js";
+
+/**
+ * Regex for safe cache subject names.
+ * First character must be alphanumeric — blocks pure-dot strings and dot-leading strings
+ * that would otherwise enable relative path traversal (e.g. "../secrets", "..").
+ */
+const SUBJECT_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+
+/** Maximum allowed length for a cache subject. */
+const SUBJECT_MAX_LENGTH = 128;
+
+/**
+ * Formats a ZodError's issues into a human-readable semicolon-separated string.
+ * Each issue is prefixed with its dot-separated field path when present.
+ */
+export function formatZodError(error: ZodError): string {
+  return error.issues
+    .map((i) => {
+      if (i.path.length === 0) return i.message;
+      const pathStr = i.path.map((seg) => String(seg).replace(/[\x00-\x1f\x7f]/g, "?")).join(".");
+      return `${pathStr}: ${i.message}`;
+    })
+    .join("; ");
+}
+
+/**
+ * Validates a cache subject string.
+ * Rejects values that could enable path traversal (e.g. "../secrets") or inject
+ * unexpected characters into file paths derived from the subject.
+ */
+export function validateSubject(subject: string): Result<void> {
+  if (subject.length > SUBJECT_MAX_LENGTH) {
+    return {
+      ok: false,
+      error: "Subject must be 128 characters or fewer",
+      code: ErrorCode.INVALID_ARGS,
+    };
+  }
+  if (!SUBJECT_PATTERN.test(subject)) {
+    return {
+      ok: false,
+      error: `Invalid subject "${subject}": must match /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/`,
+      code: ErrorCode.INVALID_ARGS,
+    };
+  }
+  return { ok: true, value: undefined };
+}