@thecat69/cache-ctrl 1.0.0 → 1.2.0

package/src/commands/map.ts

@@ -0,0 +1,87 @@
+import { findRepoRoot, readCache } from "../cache/cacheManager.js";
+import { resolveLocalCachePath } from "../cache/localCache.js";
+import { LocalCacheFileSchema } from "../types/cache.js";
+import type { MapArgs, MapDepth, MapResult } from "../types/commands.js";
+import { ErrorCode, type Result } from "../types/result.js";
+import { toUnknownResult } from "../utils/errors.js";
+
+/**
+ * Returns a semantic map view of local context cache content.
+ *
+ * @param args - {@link MapArgs} command arguments.
+ * @returns Promise<Result<MapResult["value"]>>; common failures include FILE_NOT_FOUND,
+ * PARSE_ERROR, FILE_READ_ERROR, and UNKNOWN.
+ */
+export async function mapCommand(args: MapArgs): Promise<Result<MapResult["value"]>> {
+  try {
+    const depth: MapDepth = args.depth ?? "overview";
+    const repoRoot = await findRepoRoot(process.cwd());
+    const contextPath = resolveLocalCachePath(repoRoot);
+
+    const readResult = await readCache(contextPath);
+    if (!readResult.ok) {
+      if (readResult.code === ErrorCode.FILE_NOT_FOUND) {
+        return {
+          ok: false,
+          error: "context.json not found — run local-context-gatherer to populate the cache",
+          code: ErrorCode.FILE_NOT_FOUND,
+        };
+      }
+      return readResult;
+    }
+
+    const parseResult = LocalCacheFileSchema.safeParse(readResult.value);
+    if (!parseResult.success) {
+      return {
+        ok: false,
+        error: `Malformed local cache file: ${contextPath}`,
+        code: ErrorCode.PARSE_ERROR,
+      };
+    }
+
+    const parsed = parseResult.data;
+    const allFacts = parsed.facts ?? {};
+    const folderPrefix = args.folder;
+    const filteredFacts =
+      folderPrefix !== undefined
+        ? Object.fromEntries(
+            Object.entries(allFacts).filter(
+              ([filePath]) => filePath === folderPrefix || filePath.startsWith(`${folderPrefix}/`),
+            ),
+          )
+        : allFacts;
+
+    const files = Object.entries(filteredFacts)
+      .map(([path, fileFacts]) => ({
+        path,
+        ...(fileFacts.summary !== undefined ? { summary: fileFacts.summary } : {}),
+        ...(fileFacts.role !== undefined ? { role: fileFacts.role } : {}),
+        ...(fileFacts.importance !== undefined ? { importance: fileFacts.importance } : {}),
+        ...(depth === "full" && fileFacts.facts !== undefined ? { facts: fileFacts.facts } : {}),
+      }))
+      .sort((a, b) => {
+        const aImportance = a.importance ?? Number.POSITIVE_INFINITY;
+        const bImportance = b.importance ?? Number.POSITIVE_INFINITY;
+        if (aImportance !== bImportance) {
+          return aImportance - bImportance;
+        }
+        return a.path.localeCompare(b.path);
+      });
+
+    return {
+      ok: true,
+      value: {
+        depth,
+        global_facts: parsed.global_facts ?? [],
+        files,
+        ...((depth === "modules" || depth === "full") && parsed.modules !== undefined
+          ? { modules: parsed.modules }
+          : {}),
+        total_files: files.length,
+        ...(args.folder !== undefined ? { folder_filter: args.folder } : {}),
+      },
+    };
+  } catch (err) {
+    return toUnknownResult(err);
+  }
+}

package/src/commands/prune.ts

@@ -6,17 +6,32 @@ import { ExternalCacheFileSchema } from "../types/cache.js";
 import { ErrorCode, type Result } from "../types/result.js";
 import type { PruneArgs, PruneResult } from "../types/commands.js";
 import { getFileStem } from "../utils/fileStem.js";
+import { toUnknownResult } from "../utils/errors.js";
 
+/**
+ * Parses duration text in `<number><unit>` form.
+ *
+ * @param duration - Duration string where unit is one of `s`, `m`, `h`, `d`.
+ * @returns Milliseconds value, or `null` when format is invalid.
+ */
 export function parseDurationMs(duration: string): number | null {
-  const match = /^(\d+)(h|d)$/.exec(duration);
+  const match = /^(\d+)(s|m|h|d)$/.exec(duration);
   if (!match) return null;
   const value = parseInt(match[1]!, 10);
   const unit = match[2]!;
+  if (unit === "s") return value * 1_000;
+  if (unit === "m") return value * 60_000;
   if (unit === "h") return value * 3_600_000;
-  if (unit === "d") return value * 86_400_000;
-  return null;
+  return value * 86_400_000;
 }
 
+/**
+ * Prunes stale cache entries by invalidating or deleting them.
+ *
+ * @param args - {@link PruneArgs} command arguments.
+ * @returns Promise<Result<PruneResult["value"]>>; common failures include INVALID_ARGS,
+ * FILE_READ_ERROR, FILE_WRITE_ERROR, and UNKNOWN.
+ */
 export async function pruneCommand(args: PruneArgs): Promise<Result<PruneResult["value"]>> {
   try {
     const repoRoot = await findRepoRoot(process.cwd());
@@ -82,9 +97,7 @@ export async function pruneCommand(args: PruneArgs): Promise<Result<PruneResult[
         // Only invalidate if the file already exists
         const readResult = await readCache(localPath);
         if (!readResult.ok) {
-          if (readResult.code === ErrorCode.FILE_NOT_FOUND) {
-            // Nothing to prune — skip silently
-          } else {
+          if (readResult.code !== ErrorCode.FILE_NOT_FOUND) {
             return readResult;
           }
         } else {
@@ -104,7 +117,6 @@ export async function pruneCommand(args: PruneArgs): Promise<Result<PruneResult[
       },
     };
   } catch (err) {
-    const error = err as Error;
-    return { ok: false, error: error.message, code: ErrorCode.UNKNOWN };
+    return toUnknownResult(err);
   }
 }

package/src/commands/search.ts

@@ -5,7 +5,15 @@ import type { CacheEntry } from "../types/cache.js";
 import { LocalCacheFileSchema } from "../types/cache.js";
 import { ErrorCode, type Result } from "../types/result.js";
 import type { SearchArgs, SearchResult } from "../types/commands.js";
+import { toUnknownResult } from "../utils/errors.js";
 
+/**
+ * Searches cache entries across namespaces using keyword-based scoring.
+ *
+ * @param args - {@link SearchArgs} command arguments.
+ * @returns Promise<Result<SearchResult["value"]>>; common failures include FILE_READ_ERROR
+ * (external directory listing), PARSE_ERROR (malformed local cache), and UNKNOWN.
+ */
 export async function searchCommand(args: SearchArgs): Promise<Result<SearchResult["value"]>> {
   try {
     const repoRoot = await findRepoRoot(process.cwd());
@@ -51,7 +59,6 @@ export async function searchCommand(args: SearchArgs): Promise<Result<SearchResu
       })),
     };
   } catch (err) {
-    const error = err as Error;
-    return { ok: false, error: error.message, code: ErrorCode.UNKNOWN };
+    return toUnknownResult(err);
   }
 }

package/src/commands/touch.ts

@@ -1,10 +1,17 @@
-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 { validateSubject } from "../utils/validate.js";
+import { toUnknownResult } from "../utils/errors.js";
 
+/**
+ * Marks cache entries fresh by setting timestamps to current UTC time.
+ *
+ * @param args - {@link TouchArgs} command arguments.
+ * @returns Promise<Result<TouchResult["value"]>>; common failures include INVALID_ARGS,
+ * NO_MATCH, FILE_WRITE_ERROR, and UNKNOWN.
+ */
 export async function touchCommand(args: TouchArgs): Promise<Result<TouchResult["value"]>> {
   try {
     const repoRoot = await findRepoRoot(process.cwd());
@@ -12,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);
@@ -41,7 +32,6 @@ export async function touchCommand(args: TouchArgs): Promise<Result<TouchResult[
 
     return { ok: true, value: { touched, new_timestamp: newTimestamp } };
   } catch (err) {
-    const error = err as Error;
-    return { ok: false, error: error.message, code: ErrorCode.UNKNOWN };
+    return toUnknownResult(err);
   }
 }

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,
+    };
+  }
+}

package/src/commands/version.ts

@@ -0,0 +1,14 @@
+import type { VersionArgs, VersionResult } from "../types/commands.js";
+import type { Result } from "../types/result.js";
+
+import packageJson from "../../package.json" with { type: "json" };
+
+/**
+ * Returns the package version from `package.json`.
+ *
+ * @param args - {@link VersionArgs} command arguments (unused).
+ * @returns `Result<VersionResult["value"]>` containing the CLI version.
+ */
+export function versionCommand(_args: VersionArgs = {}): Result<VersionResult["value"]> {
+  return { ok: true, value: { version: packageJson.version } };
+}

package/src/commands/watch.ts

@@ -0,0 +1,270 @@
+import path from "node:path";
+import { realpath } from "node:fs/promises";
+
+import { buildGraph, type DependencyGraph } from "../analysis/graphBuilder.js";
+import { findRepoRoot, writeCache } from "../cache/cacheManager.js";
+import { resolveGraphCachePath } from "../cache/graphCache.js";
+import { getGitTrackedFiles } from "../files/gitFiles.js";
+import type { GraphCacheFile } from "../types/cache.js";
+import type { WatchArgs } from "../types/commands.js";
+import { ErrorCode, type Result } from "../types/result.js";
+import { toUnknownResult } from "../utils/errors.js";
+
+const WATCH_DEBOUNCE_MS = 200;
+const SOURCE_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx"]);
+
+type TrackedFilesProvider = (repoRoot: string) => Promise<string[]>;
+type WatchEvent = "rename" | "change";
+type BunWatchCallback = (event: WatchEvent, filename: string | null) => void;
+
+interface WatcherHandle {
+  close?: () => void;
+  stop?: () => void;
+}
+
+type BunWatchFunction = (
+  watchPath: string,
+  options: { recursive: boolean },
+  callback: BunWatchCallback,
+) => WatcherHandle;
+
+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,
+      error: "Bun.watch is not available in this runtime",
+      code: ErrorCode.UNKNOWN,
+    };
+  }
+  return { ok: true, value: watchFn };
+}
+
+/**
+ * Checks whether a file path is a supported source file for graph analysis.
+ *
+ * @param filePath - Absolute or relative file path.
+ * @returns `true` when extension is one of `.ts`, `.tsx`, `.js`, `.jsx`.
+ */
+export function isSourceFile(filePath: string): boolean {
+  const extension = path.extname(filePath).toLowerCase();
+  return SOURCE_EXTENSIONS.has(extension);
+}
+
+/**
+ * Converts in-memory dependency graph nodes into graph cache file shape.
+ *
+ * @param graph - Dependency graph to serialize.
+ * @returns `GraphCacheFile["files"]` payload suitable for `graph.json`.
+ */
+export function serializeGraphToCache(graph: DependencyGraph): GraphCacheFile["files"] {
+  const files: GraphCacheFile["files"] = {};
+
+  for (const [filePath, node] of graph.entries()) {
+    files[filePath] = {
+      rank: 0.0,
+      deps: node.deps,
+      defs: node.defs,
+    };
+  }
+
+  return files;
+}
+
+/**
+ * Resolves tracked source files to safe absolute paths for graph building.
+ *
+ * @param repoRoot - Repository root used for path resolution.
+ * @param trackedFilesProvider - Optional provider for tracked paths (defaults to git).
+ * @returns Absolute, de-duplicated source file paths constrained to `repoRoot`.
+ */
+export async function resolveSourceFilePaths(
+  repoRoot: string,
+  trackedFilesProvider: TrackedFilesProvider = getGitTrackedFiles,
+): Promise<string[]> {
+  const trackedFiles = await trackedFilesProvider(repoRoot);
+  const normalizedRepoRoot = path.resolve(repoRoot);
+  const repoPrefix = `${normalizedRepoRoot}${path.sep}`;
+  const sourcePaths = new Set<string>();
+
+  await Promise.all(
+    trackedFiles.filter(isSourceFile).map(async (relPath) => {
+      const absolutePath = path.join(normalizedRepoRoot, relPath);
+      try {
+        const resolvedPath = await realpath(absolutePath);
+        if (resolvedPath === normalizedRepoRoot || resolvedPath.startsWith(repoPrefix)) {
+          sourcePaths.add(resolvedPath);
+        }
+      } catch {
+        // Ignore missing or unreadable paths from tracked files.
+      }
+    }),
+  );
+
+  return [...sourcePaths];
+}
+
+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 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 dependencies.writeCache(graphCachePath, graphPayload, "replace");
+    if (!writeResult.ok) {
+      process.stderr.write(`[watch] Failed to update graph cache: ${writeResult.error}\n`);
+      return writeResult;
+    }
+    if (verbose) {
+      if (changedPath !== undefined) {
+        process.stdout.write(`[watch] Graph updated: ${graph.size} files, changed: ${changedPath}\n`);
+      } else {
+        process.stdout.write(`[watch] Initial graph computed: ${graph.size} files\n`);
+      }
+    }
+    return { ok: true, value: undefined };
+  } catch (err) {
+    const unknownError = toUnknownResult(err);
+    process.stderr.write(`[watch] Failed to rebuild graph: ${unknownError.error}\n`);
+    return unknownError;
+  }
+}
+
+/**
+ * Starts the long-running graph watch daemon.
+ *
+ * @param args - {@link WatchArgs} command arguments.
+ * @returns Promise<Result<never>>; common failures include FILE_WRITE_ERROR via wrapped
+ * UNKNOWN, runtime unavailability errors, and UNKNOWN.
+ */
+export async function watchCommand(args: WatchArgs): Promise<Result<never>> {
+  try {
+    const repoRoot = await findRepoRoot(process.cwd());
+
+    const initialRebuildResult = await rebuildGraphCache(repoRoot, undefined, args.verbose === true);
+    if (!initialRebuildResult.ok) {
+      return initialRebuildResult;
+    }
+
+    let pendingChangedPath: string | undefined;
+    let debounceTimer: ReturnType<typeof setTimeout> | undefined;
+    let rebuildInProgress = false;
+    let rebuildQueued = false;
+
+    const triggerRebuild = async (): Promise<void> => {
+      if (rebuildInProgress) {
+        rebuildQueued = true;
+        return;
+      }
+
+      rebuildInProgress = true;
+      try {
+        do {
+          rebuildQueued = false;
+          const changedPath = pendingChangedPath;
+          pendingChangedPath = undefined;
+          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;
+      }
+    };
+
+    const scheduleRebuild = (changedPath: string): void => {
+      pendingChangedPath = changedPath;
+
+      if (debounceTimer !== undefined) {
+        clearTimeout(debounceTimer);
+      }
+
+      debounceTimer = setTimeout(() => {
+        debounceTimer = undefined;
+        void triggerRebuild();
+      }, WATCH_DEBOUNCE_MS);
+    };
+
+    const watchResult = resolveBunWatch();
+    if (!watchResult.ok) {
+      process.stderr.write(`[watch] ${watchResult.error}\n`);
+      return watchResult;
+    }
+
+    const watcher = watchResult.value(repoRoot, { recursive: true }, (_event, filename) => {
+      if (filename === null) {
+        return;
+      }
+
+      const absolutePath = path.join(repoRoot, filename);
+      if (!isSourceFile(absolutePath)) {
+        return;
+      }
+
+      if (args.verbose) {
+        process.stdout.write(`[watch] File changed: ${absolutePath}, recomputing...\n`);
+      }
+
+      scheduleRebuild(absolutePath);
+    });
+
+    const shutdown = (): void => {
+      if (debounceTimer !== undefined) {
+        clearTimeout(debounceTimer);
+      }
+      if (args.verbose) {
+        process.stdout.write("[watch] Shutting down\n");
+      }
+      if (typeof watcher.close === "function") {
+        watcher.close();
+      } else if (typeof watcher.stop === "function") {
+        watcher.stop();
+      }
+      process.exit(0);
+    };
+
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+
+    return new Promise<never>(() => {
+      // Keep command alive until signal-based shutdown.
+    });
+  } catch (err) {
+    const unknownError = toUnknownResult(err);
+    const message = unknownError.error;
+    process.stderr.write(`[watch] Failed to start watcher: ${message}\n`);
+    return unknownError;
+  }
+}