@thecat69/cache-ctrl 1.1.1 → 1.2.0

package/skills/cache-ctrl-local/SKILL.md

@@ -5,16 +5,9 @@ description: How to use cache-ctrl to detect file changes and manage the local c
 
 # cache-ctrl — Local Cache Usage
 
-Manage `.ai/local-context-gatherer_cache/context.json` to avoid redundant full-repo scans.
-Two tiers of access — use the best one available.
-
-> Availability Detection: see `cache-ctrl-caller`.
-
----
-
 ## Fact-Writing Rules
-Per-file `facts` entries are no longer flat string arrays. Each path now maps to a
-**`FileFacts` object**:
+
+Per-file entries use the `FileFacts` object shape:
 
 ```json
 {
@@ -25,135 +18,93 @@ Per-file `facts` entries are no longer flat string arrays. Each path now maps to
 }
 ```
 
-Required and recommended fields:
-
-- **`summary` is mandatory** when writing a file entry. Keep it to one sentence.
-- **`role` is mandatory** when writing a file entry. Must be one of:
-  - `entry-point`
-  - `interface`
-  - `implementation`
-  - `test`
-  - `config`
-- **`importance` is optional but strongly recommended**:
-  - `1` = core module
-  - `2` = supporting module
-  - `3` = peripheral/config module
-- **`facts` is optional** and capped at **10 items**, each **≤ 300 chars**.
+Fields:
+- **`summary`** — mandatory. One sentence.
+- **`role`** — mandatory. One of: `entry-point`, `interface`, `implementation`, `test`, `config`.
+- **`importance`** — strongly recommended. `1` = core, `2` = supporting, `3` = peripheral.
+- **`facts`** — optional. Max 10 items, each ≤ 300 chars.
 
 Content quality rules:
-
-- **Never write** raw import lines, function bodies, code snippets, or verbatim text from the file.
+- **Never write** raw import lines, code snippets, or verbatim file content.
 - **Do write** concise architectural observations: purpose, key exports, constraints, dependencies, notable patterns.
+- Write facts as **enumerable observations** — one entry per distinct property, up to the 10-item limit.
 
-**Good `facts[]` item** ✅:
+Good example ✅:
 > `"Delegates local writes to writeLocalCommand and preserves unrelated paths through per-path merge"`
 
-**Bad `facts[]` item** ❌:
-> `"import { ExternalCacheFileSchema, LocalCacheFileSchema } from '../types/cache.js'; import { ErrorCode, Result } from '../types/result.js'"` ← raw file content
+Bad example ❌:
+> `"import { ExternalCacheFileSchema } from '../types/cache.js'"` ← raw file content
 
-**Global facts** are for cross-cutting structural observations only (e.g. CLI entry pattern, installation steps). Max 20, each ≤ 300 chars. Only update global_facts when you re-read a structural file (AGENTS.md, install.sh, package.json, *.toml, opencode.json).
+**Global facts** — cross-cutting structural observations only (CLI entry pattern, installation steps, etc.). Max 20, each ≤ 300 chars. Only update `global_facts` when re-reading a structural file: `AGENTS.md`, `install.sh`, `opencode.json`, `package.json`, `*.toml`.
 
----
+## Scan Workflow
 
-## Mandatory: Write Before Return
-**Every invocation that reads any file MUST call `cache_ctrl_write_local` before returning — no exceptions, no edge cases.**
+1. Call `cache_ctrl_check_files` to identify changed and new files.
+2. Read only the changed/new files (skip unchanged ones).
+3. Extract `FileFacts` per file (follow Fact-Writing Rules above).
+4. Call `cache_ctrl_write_local` — **mandatory** (see Write-Before-Return Rule below for the skip exception).
+5. Return your summary.
 
-Sequential checklist (do not skip any step):
+> **⚠ Cache is non-exhaustive:** `status: "unchanged"` only confirms previously-tracked files are stable — it does not mean the file set is complete. Always check `new_files` and `deleted_git_files` in the response.
 
-1. Call `cache_ctrl_check_files` — identify changed/new files
-2. Read only the changed/new files (skip unchanged ones)
-3. Extract concise facts per file (follow Fact-Writing Rules above)
-4. **Call `cache_ctrl_write_local` — MANDATORY. NO EXCEPTIONS.** (even if only 1 file changed, even if only global_facts changed, even if you believe the facts are identical to what is cached)
-5. Return your summary
+## Write-Before-Return Rule
 
-> **⛔ Write-or-fail rule**: If you read any file in steps 2–3, you MUST call `cache_ctrl_write_local` in step 4. Returning without writing after reading files is a critical failure — the cache will be stale and the orchestrator will detect the missing write and re-invoke you. Even if zero files were read, you must still consult the decision table below before deciding to skip the write.
+**Every invocation that reads any file MUST call `cache_ctrl_write_local` before returning.**
 
-**The only time you may skip `cache_ctrl_write_local` is when ALL of the following are true simultaneously:**
+The only time you may skip the write is when ALL of the following are true:
 
 | Condition | Required value |
 |---|---|
-| `changed_files` from `cache_ctrl_check_files` | empty `[]` |
-| `new_files` from `cache_ctrl_check_files` | empty `[]` |
-| No files were force-requested by the caller | true |
+| `changed_files` from `check_files` | `[]` |
+| `new_files` from `check_files` | `[]` |
+| No files were force-requested by caller | true |
 | Cache already exists and is non-empty | true |
 | This invocation was NOT triggered by a cache invalidation | true |
 
-If any one of these conditions is not met, you **must** write.
-
----
-
-## Startup Workflow
-### 1. Check if tracked files changed
-
-**Tier 1:** Call `cache_ctrl_check_files` (no parameters).
-**Tier 2:** `cache-ctrl check-files`
-
-Result interpretation (Tier 1 & 2):
-- `status: "unchanged"` → tracked files are content-stable; skip re-scan and return cached context.
-- `status: "changed"` → at least one tracked file changed; proceed to **delta scan**.
-- `status: "unchanged"` with empty `tracked_files` → cold start, proceed to scan.
-
-The response also reports:
-- `new_files` — untracked non-ignored files absent from cache, plus git-tracked files absent from cache when the cache is non-empty (blank-slate caches skip git-tracked files to avoid false positives on cold start)
-- `deleted_git_files` — git-tracked files deleted from the working tree (reported by `git ls-files --deleted`)
-
-> **⚠ Cache is non-exhaustive**: `status: "unchanged"` only confirms that previously-tracked files are content-stable — it does not mean the file set is complete. Always check `new_files` and `deleted_git_files` in the response; if either is non-empty, include those paths in the next write to keep the cache up to date.
+If any condition is not met, you **must** write.
 
-### 2. Invalidate before writing (optional)
-> Do this only if cache is really outdated and a full rescan is needed. Otherwise just proceed with next step (writing).
+> **⛔ Write-or-fail:** Returning without writing after reading files is a critical failure — the cache will be stale. Even if you believe facts are unchanged, if you read a file, you write.
 
-**Tier 1:** Call `cache_ctrl_invalidate` with `agent: "local"`.
-**Tier 2:** `cache-ctrl invalidate local`
+## `cache_ctrl_write_local` Reference
 
-### 3. Write cache after scanning
-**Always use the write tool/command — never write the file directly.** Direct writes bypass schema validation and can silently corrupt the cache format.
+Always use `cache_ctrl_write_local` — never write cache files directly.
 
-> **Write is per-path merge**: Submitted `tracked_files` entries replace existing entries for the same paths. Paths not in the submission are preserved. Entries for files deleted from disk are evicted automatically (no agent action needed).
-
-#### Input fields (top-level args)
+#### Input fields
 
 | Field | Type | Required | Notes |
 |---|---|---|---|
 | `topic` | `string` | ✅ | Human description of what was scanned |
 | `description` | `string` | ✅ | One-liner for keyword search |
-| `tracked_files` | `Array<{ path: string }>` | ✅ | Paths to track; `mtime` and `hash` are auto-computed by the tool |
-| `global_facts` | `string[]` | optional | Repo-level facts; last-write-wins; see trigger rule below |
-| `facts` | `Record<string, FileFacts>` | optional | Per-file structured facts keyed by path; per-path merge |
-| `cache_miss_reason` | `string` | optional | Why the previous cache was discarded |
-
-> **Cold start vs incremental**: On first run (no existing cache), submit all relevant files. On subsequent runs, submit only new and changed files — the tool merges them in.
+| `tracked_files` | `Array<{ path: string }>` | ✅ | `mtime` and `hash` are auto-computed |
+| `facts` | `Record<string, FileFacts>` | optional | Per-file structured facts; per-path merge |
+| `global_facts` | `string[]` | optional | Last-write-wins; see trigger rule above |
+| `cache_miss_reason` | `string` | optional | Why prior cache was discarded |
 
-> **Auto-set by the tool — do not include**: `timestamp` (current UTC), `mtime` (filesystem `lstat()`), and `hash` (SHA-256) per `tracked_files` entry.
+> **Auto-set by the tool — do not include:** `timestamp`, `mtime`, `hash`.
+> **Write is per-path merge:** Submitted paths replace existing entries for those paths. Other paths are preserved. Deleted-file entries are evicted automatically.
 
-### Scope rule for `facts`
-Submit `facts` ONLY for files you actually read in this session (i.e., files present in
-your submitted `tracked_files`). Never reconstruct or re-submit facts for unchanged files —
-the tool preserves them automatically via per-path merge.
+#### Scope rule for `facts`
 
-Submitting a facts key for a path absent from submitted `tracked_files` is a
-VALIDATION_ERROR and the entire write is rejected.
+Submit `facts` ONLY for files you actually read in this session (files present in `tracked_files`). Never reconstruct or re-submit facts for unchanged files — the tool preserves them automatically.
 
-### Fact completeness
-When a file appears in `changed_files` or `new_files`, read the **whole file** before writing
-facts — not just the diff. A 2-line change does not support a complete re-description of the
-file, and submitting partial facts for a re-read path **permanently replaces** whatever was
-cached before.
+Submitting a `facts` key for a path absent from `tracked_files` is a `VALIDATION_ERROR` and the entire write is rejected.
 
-Write facts as **enumerable observations** — one entry per notable characteristic (purpose,
-structure, key dependencies, patterns, constraints, entry points). Do not bundle multiple
-distinct properties into a single string. A file should have as many fact entries as it has
-distinct notable properties, up to the 10-item limit.
+#### Fact completeness
 
-Each per-file `facts` entry MUST include `summary` + `role`, should include `importance`,
-and may include an optional `facts[]` list.
+When a file appears in `changed_files` or `new_files`, read the **whole file** before writing facts — not just the diff. Submitting partial facts for a re-read path **permanently replaces** whatever was cached.
 
-#### `cache_ctrl_write_local` facts shape example (`FileFacts`)
+#### Example
 
 ```json
 {
+  "topic": "src/commands scan",
+  "description": "Scan of src/commands after write refactor",
+  "tracked_files": [
+    { "path": "src/commands/writeLocal.ts" }
+  ],
   "facts": {
     "src/commands/writeLocal.ts": {
-      "summary": "Thin router dispatching write calls to writeLocal or writeExternal based on agent type.",
+      "summary": "Thin router dispatching write calls based on agent type.",
       "role": "implementation",
       "importance": 2,
       "facts": [
@@ -165,58 +116,16 @@ and may include an optional `facts[]` list.
 }
 ```
 
-### When to submit `global_facts`
-Submit `global_facts` only when you re-read at least one structural file in this session:
-AGENTS.md, install.sh, opencode.json, package.json, *.toml config files.
-
-If none of those are in `changed_files` or `new_files`, omit `global_facts` from the write.
-The existing value is preserved automatically.
-
-### Eviction
-Facts for files deleted from disk are evicted automatically on the next write — no agent
-action needed. `global_facts` is never evicted.
-
-#### Tier 1 — `cache_ctrl_write_local`
-
-```json
-{
-  "topic": "neovim plugin configuration scan",
-  "description": "Full scan of lua/plugins tree for neovim lazy.nvim setup",
-  "tracked_files": [
-    { "path": "lua/plugins/ui/bufferline.lua" },
-    { "path": "lua/plugins/lsp/nvim-lspconfig.lua" }
-  ]
-}
-```
-
-#### Tier 2 — CLI
+## Eviction
 
-`cache-ctrl write-local --data '<json>'` — pass the same top-level fields as the JSON value.
+Facts for files deleted from disk are evicted automatically on the next write — no agent action needed. `global_facts` is never evicted.
 
-### 4. Confirm cache (optional)
-**Tier 1:** Call `cache_ctrl_list` with `agent: "local"` to confirm the entry was written.
-**Tier 2:** `cache-ctrl list --agent local`
+## Tool Reference
 
-Note: local entries show `is_stale: true` only when `cache_ctrl_check_files` detects actual changes.
-
----
-
-## Tool / Command Reference
-| Operation | Tier 1 (built-in) | Tier 2 (CLI) |
-|---|---|---|
-| Detect file changes | `cache_ctrl_check_files` | `cache-ctrl check-files` |
-| Invalidate cache | `cache_ctrl_invalidate` | `cache-ctrl invalidate local` |
-| Confirm written | `cache_ctrl_list` | `cache-ctrl list --agent local` |
-| Read facts (filtered) | `cache_ctrl_inspect` with `filter`, `folder`, or `searchFacts` | `cache-ctrl inspect local context --filter <kw>[,<kw>...]` / `--folder <path>` / `--search-facts <kw>[,<kw>...]` |
-| Read all facts (rare) | `cache_ctrl_inspect` (no filter) | `cache-ctrl inspect local context` |
-| Write cache | `cache_ctrl_write_local` | `cache-ctrl write-local --data '<json>'` |
-
-> For `inspect` filter targeting options, see `cache-ctrl-caller`.
-
-> All `cache_ctrl_*` tools return `server_time`; see `cache-ctrl-caller` for freshness-decision usage.
-
-## Cache Location
-
-`.ai/local-context-gatherer_cache/context.json` — single file, no per-subject splitting.
-
-No time-based TTL for Tier 1/2. Freshness determined by `cache_ctrl_check_files`.
+| Operation | Tool |
+|---|---|
+| Detect file changes | `cache_ctrl_check_files` |
+| Invalidate cache | `cache_ctrl_invalidate` (agent: "local") |
+| Write cache | `cache_ctrl_write_local` |
+| Read facts (filtered) | `cache_ctrl_inspect` (agent: "local", filter / folder / search_facts) |
+| Confirm written | `cache_ctrl_list` (agent: "local") |

package/src/analysis/pageRank.ts

@@ -90,11 +90,8 @@ function buildInLinks(graph: DependencyGraph, nodes: string[]): Map<string, stri
 
   for (const [sourceNode, graphNode] of graph.entries()) {
     for (const targetNode of graphNode.deps) {
-      if (!inLinks.has(targetNode)) {
-        continue;
-      }
       const targetInLinks = inLinks.get(targetNode);
-      if (targetInLinks !== undefined) {
+      if (targetInLinks) {
         targetInLinks.push(sourceNode);
       }
     }

package/src/cache/cacheManager.ts

@@ -1,5 +1,4 @@
-import { readFile, writeFile, rename, stat, unlink, readdir, mkdir } from "node:fs/promises";
-import { open } from "node:fs/promises";
+import { readFile, writeFile, rename, stat, unlink, readdir, mkdir, open } from "node:fs/promises";
 import { join, dirname } from "node:path";
 import { randomBytes } from "node:crypto";
 import type { AgentType, CacheEntry, ExternalCacheFile, LocalCacheFile } from "../types/cache.js";

package/src/cache/externalCache.ts

@@ -1,7 +1,8 @@
-import type { ExternalCacheFile, HeaderMeta } from "../types/cache.js";
+import type { ExternalCacheFile } from "../types/cache.js";
 import { ErrorCode, type Result } from "../types/result.js";
-import { loadExternalCacheEntries } from "./cacheManager.js";
+import { listCacheFiles, loadExternalCacheEntries, writeCache } from "./cacheManager.js";
 import { scoreEntry } from "../search/keywordSearch.js";
+import { validateSubject } from "../utils/validate.js";
 
 const DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 
@@ -30,26 +31,6 @@ export function isExternalStale(entry: ExternalCacheFile, maxAgeMs?: number): bo
   return isFetchedAtStale(entry.fetched_at ?? "", maxAgeMs);
 }
 
-/**
- * Merges newly fetched header metadata into an external cache entry.
- *
- * @param existing - Existing external cache entry.
- * @param updates - Per-URL header metadata updates.
- * @returns New entry with merged `header_metadata`.
- */
-export function mergeHeaderMetadata(
-  existing: ExternalCacheFile,
-  updates: Record<string, HeaderMeta>,
-): ExternalCacheFile {
-  return {
-    ...existing,
-    header_metadata: {
-      ...existing.header_metadata,
-      ...updates,
-    },
-  };
-}
-
 /**
  * Formats human-readable age text from an external `fetched_at` timestamp.
  *
@@ -102,3 +83,40 @@ export async function resolveTopExternalMatch(repoRoot: string, subject: string)
 
   return { ok: true, value: scored[0]!.entry.file };
 }
+
+/**
+ * Updates `fetched_at` for one external entry (best subject match) or all entries.
+ *
+ * @param repoRoot - Repository root.
+ * @param subject - Optional subject keyword; when provided, only top match is updated.
+ * @param fetchedAt - New ISO timestamp value (or empty string to invalidate).
+ * @returns Updated file paths.
+ */
+export async function updateExternalFetchedAt(
+  repoRoot: string,
+  subject: string | undefined,
+  fetchedAt: string,
+): Promise<Result<string[]>> {
+  let filesToUpdate: string[];
+
+  if (subject) {
+    const subjectCheck = validateSubject(subject);
+    if (!subjectCheck.ok) return subjectCheck;
+    const matchResult = await resolveTopExternalMatch(repoRoot, subject);
+    if (!matchResult.ok) return matchResult;
+    filesToUpdate = [matchResult.value];
+  } else {
+    const filesResult = await listCacheFiles("external", repoRoot);
+    if (!filesResult.ok) return filesResult;
+    filesToUpdate = filesResult.value;
+  }
+
+  const updated: string[] = [];
+  for (const filePath of filesToUpdate) {
+    const writeResult = await writeCache(filePath, { fetched_at: fetchedAt });
+    if (!writeResult.ok) return writeResult;
+    updated.push(filePath);
+  }
+
+  return { ok: true, value: updated };
+}

package/src/commands/checkFiles.ts

@@ -30,20 +30,20 @@ export async function checkFilesCommand(): Promise<Result<CheckFilesResult["valu
 
     const changedFiles: Array<{ path: string; reason: "mtime" | "hash" | "missing" }> = [];
     const unchangedFiles: string[] = [];
-    const missingFiles: string[] = [];
 
     for (const trackedFile of trackedFiles) {
       const result = await compareTrackedFile(trackedFile, repoRoot);
       if (result.status === "unchanged") {
         unchangedFiles.push(trackedFile.path);
       } else if (result.status === "missing") {
-        missingFiles.push(trackedFile.path);
         changedFiles.push({ path: trackedFile.path, reason: "missing" });
       } else {
         changedFiles.push({ path: trackedFile.path, reason: result.reason ?? "mtime" });
       }
     }
 
+    const missingFiles = changedFiles.filter((file) => file.reason === "missing").map((file) => file.path);
+
     const [gitTrackedFiles, deletedGitFiles, untrackedNonIgnoredFiles] = await Promise.all([
       getGitTrackedFiles(repoRoot),
       getGitDeletedFiles(repoRoot),

package/src/commands/invalidate.ts

@@ -1,11 +1,10 @@
-import { findRepoRoot, listCacheFiles, writeCache, readCache } from "../cache/cacheManager.js";
-import { resolveTopExternalMatch } from "../cache/externalCache.js";
+import { findRepoRoot, writeCache, readCache } from "../cache/cacheManager.js";
+import { updateExternalFetchedAt } from "../cache/externalCache.js";
 import { resolveGraphCachePath } from "../cache/graphCache.js";
 import { resolveLocalCachePath } from "../cache/localCache.js";
 import { ErrorCode, type Result } from "../types/result.js";
 import type { InvalidateArgs, InvalidateResult } from "../types/commands.js";
 import { toUnknownResult } from "../utils/errors.js";
-import { validateSubject } from "../utils/validate.js";
 
 /**
  * Marks cache entries stale by zeroing their freshness timestamps.
@@ -20,25 +19,9 @@ export async function invalidateCommand(args: InvalidateArgs): Promise<Result<In
     const invalidated: string[] = [];
 
     if (args.agent === "external") {
-      let filesToInvalidate: 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;
-        filesToInvalidate = [matchResult.value];
-      } else {
-        const filesResult = await listCacheFiles("external", repoRoot);
-        if (!filesResult.ok) return filesResult;
-        filesToInvalidate = filesResult.value;
-      }
-
-      for (const filePath of filesToInvalidate) {
-        const writeResult = await writeCache(filePath, { fetched_at: "" });
-        if (!writeResult.ok) return writeResult;
-        invalidated.push(filePath);
-      }
+      const updateResult = await updateExternalFetchedAt(repoRoot, args.subject, "");
+      if (!updateResult.ok) return updateResult;
+      invalidated.push(...updateResult.value);
     } else {
       // local — only invalidate if the file already exists
       const localPath = resolveLocalCachePath(repoRoot);

package/src/commands/touch.ts

@@ -1,10 +1,9 @@
-import { findRepoRoot, listCacheFiles, writeCache } from "../cache/cacheManager.js";
-import { resolveTopExternalMatch } from "../cache/externalCache.js";
+import { findRepoRoot, writeCache } from "../cache/cacheManager.js";
+import { updateExternalFetchedAt } from "../cache/externalCache.js";
 import { resolveLocalCachePath } from "../cache/localCache.js";
-import { ErrorCode, type Result } from "../types/result.js";
+import { type Result } from "../types/result.js";
 import type { TouchArgs, TouchResult } from "../types/commands.js";
 import { toUnknownResult } from "../utils/errors.js";
-import { validateSubject } from "../utils/validate.js";
 
 /**
  * Marks cache entries fresh by setting timestamps to current UTC time.
@@ -20,25 +19,9 @@ export async function touchCommand(args: TouchArgs): Promise<Result<TouchResult[
     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);
-      }
+      const updateResult = await updateExternalFetchedAt(repoRoot, args.subject, newTimestamp);
+      if (!updateResult.ok) return updateResult;
+      touched.push(...updateResult.value);
     } else {
       // local
       const localPath = resolveLocalCachePath(repoRoot);

package/src/commands/uninstall.ts

@@ -0,0 +1,103 @@
+import { readdir, rm, unlink } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { resolveOpenCodeConfigDir } from "../files/openCodeInstaller.js";
+import type { UninstallArgs, UninstallResult } from "../types/commands.js";
+import { ErrorCode, type Result } from "../types/result.js";
+
+const textDecoder = new TextDecoder();
+const CACHE_CTRL_SKILL_DIR_PATTERN = /^cache-ctrl-/;
+
+/**
+ * Removes cache-ctrl OpenCode integration files and uninstalls the global npm package.
+ */
+export async function uninstallCommand(args: UninstallArgs): Promise<Result<UninstallResult>> {
+  try {
+    if (args.configDir !== undefined) {
+      const absConfigDir = path.isAbsolute(args.configDir)
+        ? path.resolve(args.configDir)
+        : path.resolve(process.cwd(), args.configDir);
+      const home = os.homedir();
+      if (!absConfigDir.startsWith(home + path.sep) && absConfigDir !== home) {
+        return {
+          ok: false,
+          error: `--config-dir must be within the user home directory, got: ${args.configDir}`,
+          code: ErrorCode.INVALID_ARGS,
+        };
+      }
+    }
+
+    const removed: string[] = [];
+    const warnings: string[] = [];
+    let packageUninstalled = true;
+
+    const configDir = resolveOpenCodeConfigDir(args.configDir);
+    const toolFilePath = path.join(configDir, "tools", "cache_ctrl.ts");
+    const skillsDirPath = path.join(configDir, "skills");
+    const localBinaryPath = path.join(os.homedir(), ".local", "bin", "cache-ctrl");
+
+    try {
+      await unlink(toolFilePath);
+      removed.push(toolFilePath);
+    } catch (err) {
+      if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+        warnings.push(`Tool file not found: ${toolFilePath}`);
+      } else {
+        throw err;
+      }
+    }
+
+    try {
+      const skillEntries = await readdir(skillsDirPath, { withFileTypes: true });
+      for (const skillEntry of skillEntries) {
+        if (!skillEntry.isDirectory() || !CACHE_CTRL_SKILL_DIR_PATTERN.test(skillEntry.name)) {
+          continue;
+        }
+        const skillPath = path.join(skillsDirPath, skillEntry.name);
+        await rm(skillPath, { recursive: true });
+        removed.push(skillPath);
+      }
+    } catch (err) {
+      if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+        warnings.push(`Skills directory not found: ${skillsDirPath}`);
+      } else {
+        throw err;
+      }
+    }
+
+    try {
+      await unlink(localBinaryPath);
+      removed.push(localBinaryPath);
+    } catch (err) {
+      if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+        warnings.push(`Local binary not found: ${localBinaryPath}`);
+      } else {
+        throw err;
+      }
+    }
+
+    const uninstallProcess = Bun.spawnSync(["npm", "uninstall", "-g", "@thecat69/cache-ctrl"]);
+    if (uninstallProcess.exitCode !== 0) {
+      packageUninstalled = false;
+      const npmError = textDecoder.decode(uninstallProcess.stderr);
+      warnings.push(npmError.length > 0 ? npmError : "npm uninstall -g @thecat69/cache-ctrl failed");
+    }
+
+    return {
+      ok: true,
+      value: {
+        removed,
+        packageUninstalled,
+        warnings,
+      },
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      error: message,
+      code: ErrorCode.UNKNOWN,
+    };
+  }
+}

package/src/commands/update.ts

@@ -0,0 +1,65 @@
+import os from "node:os";
+import path from "node:path";
+
+import type { UpdateArgs, UpdateResult } from "../types/commands.js";
+import { ErrorCode, type Result } from "../types/result.js";
+
+import { installCommand } from "./install.js";
+
+const textDecoder = new TextDecoder();
+
+/**
+ * Updates the globally installed npm package and refreshes OpenCode integration files.
+ */
+export async function updateCommand(args: UpdateArgs): Promise<Result<UpdateResult>> {
+  try {
+    if (args.configDir !== undefined) {
+      const absConfigDir = path.isAbsolute(args.configDir)
+        ? path.resolve(args.configDir)
+        : path.resolve(process.cwd(), args.configDir);
+      const home = os.homedir();
+      if (!absConfigDir.startsWith(home + path.sep) && absConfigDir !== home) {
+        return {
+          ok: false,
+          error: `--config-dir must be within the user home directory, got: ${args.configDir}`,
+          code: ErrorCode.INVALID_ARGS,
+        };
+      }
+    }
+
+    const warnings: string[] = [];
+    let packageUpdated = true;
+
+    const installProcess = Bun.spawnSync(["npm", "install", "-g", "@thecat69/cache-ctrl@latest"]);
+    if (installProcess.exitCode !== 0) {
+      packageUpdated = false;
+      const npmError = textDecoder.decode(installProcess.stderr);
+      warnings.push(npmError.length > 0 ? npmError : "npm install -g @thecat69/cache-ctrl@latest failed");
+    }
+
+    const installResult = await installCommand({ ...(args.configDir !== undefined ? { configDir: args.configDir } : {}) });
+    if (!installResult.ok) {
+      return {
+        ok: false,
+        error: installResult.error,
+        code: installResult.code,
+      };
+    }
+
+    return {
+      ok: true,
+      value: {
+        packageUpdated,
+        installedPaths: [installResult.value.toolPath, ...installResult.value.skillPaths],
+        warnings,
+      },
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      error: message,
+      code: ErrorCode.UNKNOWN,
+    };
+  }
+}