@visulima/vis 1.0.0-alpha.10 → 1.0.0-alpha.11

package/dist/packem_chunks/handler14.js

@@ -1,5 +1,916 @@
-var g=Object.defineProperty;var a=(e,i)=>g(e,"name",{value:i,configurable:!0});import{createRequire as y}from"node:module";import{isAccessibleSync as u,readFileSync as p,writeFileSync as j}from"@visulima/fs";import{join as r}from"@visulima/path";const _=y(import.meta.url),c=typeof globalThis<"u"&&typeof globalThis.process<"u"?globalThis.process:process,d=a(e=>{if(typeof c<"u"&&c.versions&&c.versions.node){const[i,o]=c.versions.node.split(".").map(Number);if(i>22||i===22&&o>=3||i===20&&o>=16)return c.getBuiltinModule(e)}return _(e)},"__cjs_getBuiltinModule"),{rmSync:b}=d("node:fs"),{homedir:s}=d("node:os"),{createInterface:w}=d("node:readline");var S=Object.defineProperty,m=a((e,i)=>S(e,"name",{value:i,configurable:!0}),"l");const f=r(s(),".vis"),h=[r(s(),".zshrc"),r(s(),".zshenv"),r(s(),".bashrc"),r(s(),".bash_profile"),r(s(),".profile"),r(s(),".config","fish","config.fish")],T=m(e=>{const i=[];for(const o of h)if(u(o))try{const l=p(o).split(`
-`),n=l.filter(t=>!t.includes(".vis/bin")&&!t.includes("VIS_HOME")&&!t.includes("# vis "));n.length!==l.length&&(j(o,n.join(`
-`)),i.push(o))}catch{e.warn(`warning: could not clean ${o}`)}return i},"cleanShellProfiles"),F=m(async({logger:e,options:i})=>{if(!u(f)){e.info("vis is not installed (no ~/.vis directory found).");return}e.info("This will remove:"),e.info(`  ${f}/`);const o=h.filter(n=>u(n)&&p(n).includes(".vis"));for(const n of o)e.info(`  Lines in ${n}`);if(!i.yes){if(!process.stdin.isTTY)throw new Error("Non-interactive terminal. Use --yes to confirm.");const n=w({input:process.stdin,output:process.stdout}),t=await new Promise(v=>{n.question(`
-Type "uninstall" to confirm: `,v)});if(n.close(),t.trim()!=="uninstall"){e.info("Aborted.");return}}const l=T(e);for(const n of l)e.info(`Cleaned ${n}`);try{b(f,{force:!0,recursive:!0}),e.info(`
-✓ Removed ${f}`)}catch(n){throw new Error(`Failed to remove ${f}: ${n instanceof Error?n.message:String(n)}`)}e.info("✓ vis has been uninstalled.")},"execute");export{F as default};
+import { createRequire as __cjs_createRequire } from "node:module";
+
+const __cjs_require = __cjs_createRequire(import.meta.url);
+
+const __cjs_getProcess = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" ? globalThis.process : process;
+
+const __cjs_getBuiltinModule = (module) => {
+    // Check if we're in Node.js and version supports getBuiltinModule
+    if (typeof __cjs_getProcess !== "undefined" && __cjs_getProcess.versions && __cjs_getProcess.versions.node) {
+        const [major, minor] = __cjs_getProcess.versions.node.split(".").map(Number);
+        // Node.js 20.16.0+ and 22.3.0+
+        if (major > 22 || (major === 22 && minor >= 3) || (major === 20 && minor >= 16)) {
+            return __cjs_getProcess.getBuiltinModule(module);
+        }
+    }
+    // Fallback to createRequire
+    return __cjs_require(module);
+};
+
+const {
+  readdir,
+  stat,
+  realpath,
+  rm,
+  mkdtemp
+} = __cjs_getBuiltinModule("node:fs/promises");
+const {
+  tmpdir
+} = __cjs_getBuiltinModule("node:os");
+const {
+  createInterface
+} = __cjs_getBuiltinModule("node:readline");
+import { isAccessibleSync } from '@visulima/fs';
+import { formatBytes } from '@visulima/humanizer';
+import { join, relative } from '@visulima/path';
+import { Cache, readLastRunSummary, parseCacheSize, getLastRunSummaryPath, digestFile } from '@visulima/task-runner';
+import { g as getCacheStats, c as clearCache } from '../packem_shared/ai-cache-Be_jexe4.js';
+import { i as isCacheDirectoryInsideWorkspace, r as resolveSharedCacheDirectory } from '../packem_shared/cache-directory-2qvs4goY.js';
+import { p as pail, u as getSocketCacheStats, v as clearSocketCache } from './bin.js';
+import { r as readRunSummaryById, f as findTaskInSummary, a as readPreviousRunSummary, d as diffHashDetails } from '../packem_shared/run-summary-utils-PVMl4aIh.js';
+
+const sumDirectorySize = async (directory) => {
+  let total = 0;
+  try {
+    const entries = await readdir(directory, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = join(directory, entry.name);
+      if (entry.isDirectory()) {
+        total += await sumDirectorySize(full);
+      } else if (entry.isFile()) {
+        const s = await stat(full);
+        total += s.size;
+      }
+    }
+  } catch {
+  }
+  return total;
+};
+const collectCacheEntries = async (cacheDirectory) => {
+  const entries = [];
+  let dirents;
+  try {
+    dirents = await readdir(cacheDirectory);
+  } catch {
+    return [];
+  }
+  for (const name of dirents) {
+    if (name.startsWith(".")) {
+      continue;
+    }
+    const fullPath = join(cacheDirectory, name);
+    try {
+      const s = await stat(fullPath);
+      if (!s.isDirectory()) {
+        continue;
+      }
+      const sizeBytes = await sumDirectorySize(fullPath);
+      entries.push({
+        hash: name,
+        mtimeMs: s.mtimeMs,
+        path: fullPath,
+        sizeBytes
+      });
+    } catch {
+    }
+  }
+  entries.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return entries;
+};
+const formatAge = (mtimeMs, now = Date.now()) => {
+  const seconds = Math.max(0, Math.floor((now - mtimeMs) / 1e3));
+  if (seconds < 60) {
+    return `${String(seconds)}s`;
+  }
+  if (seconds < 3600) {
+    return `${String(Math.floor(seconds / 60))}m`;
+  }
+  if (seconds < 86400) {
+    return `${String(Math.floor(seconds / 3600))}h`;
+  }
+  return `${String(Math.floor(seconds / 86400))}d`;
+};
+const confirmPrompt = (question) => new Promise((resolvePromise) => {
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  rl.question(`${question} (y/N) `, (answer) => {
+    rl.close();
+    const trimmed = answer.trim().toLowerCase();
+    resolvePromise(trimmed === "y" || trimmed === "yes");
+  });
+});
+const runList = async (cacheDirectory, format, logger) => {
+  if (!isAccessibleSync(cacheDirectory)) {
+    if (format === "json") {
+      process.stdout.write(`${JSON.stringify({ directory: cacheDirectory, entries: [], totalBytes: 0, totalCount: 0 }, void 0, 2)}
+`);
+      return;
+    }
+    pail.info(`No cache directory found at ${cacheDirectory}`);
+    return;
+  }
+  const entries = await collectCacheEntries(cacheDirectory);
+  if (entries.length === 0) {
+    if (format === "json") {
+      process.stdout.write(`${JSON.stringify({ directory: cacheDirectory, entries: [], totalBytes: 0, totalCount: 0 }, void 0, 2)}
+`);
+      return;
+    }
+    pail.info(`Cache directory is empty: ${cacheDirectory}`);
+    return;
+  }
+  const totalBytes = entries.reduce((sum, entry) => sum + entry.sizeBytes, 0);
+  if (format === "json") {
+    const now = Date.now();
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          directory: cacheDirectory,
+          entries: entries.map((entry) => {
+            return {
+              ageMs: now - entry.mtimeMs,
+              hash: entry.hash,
+              mtimeIso: new Date(entry.mtimeMs).toISOString(),
+              sizeBytes: entry.sizeBytes
+            };
+          }),
+          totalBytes,
+          totalCount: entries.length
+        },
+        void 0,
+        2
+      )}
+`
+    );
+    return;
+  }
+  pail.info(`Cache directory: ${cacheDirectory}`);
+  pail.info(`Entries: ${String(entries.length)} (${formatBytes(totalBytes, { decimals: 1, space: false })})`);
+  logger.info("");
+  const renderedAt = Date.now();
+  const rows = entries.map((entry) => {
+    return {
+      age: formatAge(entry.mtimeMs, renderedAt),
+      hash: entry.hash.slice(0, 12),
+      size: formatBytes(entry.sizeBytes, { decimals: 1, space: false })
+    };
+  });
+  const hashWidth = Math.max(4, ...rows.map((r) => r.hash.length));
+  const sizeWidth = Math.max(4, ...rows.map((r) => r.size.length));
+  const ageWidth = Math.max(3, ...rows.map((r) => r.age.length));
+  logger.info(`  ${"hash".padEnd(hashWidth)}  ${"size".padEnd(sizeWidth)}  ${"age".padEnd(ageWidth)}`);
+  logger.info(`  ${"-".repeat(hashWidth)}  ${"-".repeat(sizeWidth)}  ${"-".repeat(ageWidth)}`);
+  for (const row of rows) {
+    logger.info(`  ${row.hash.padEnd(hashWidth)}  ${row.size.padEnd(sizeWidth)}  ${row.age.padEnd(ageWidth)}`);
+  }
+};
+const clearAiCacheSafe = () => {
+  try {
+    const aiDeleted = clearCache();
+    if (aiDeleted > 0) {
+      pail.info(`Cleared ${String(aiDeleted)} cached AI response${aiDeleted === 1 ? "" : "s"}.`);
+    }
+  } catch (error) {
+    pail.warn(`Failed to clear AI response cache: ${error instanceof Error ? error.message : String(error)}`);
+  }
+};
+const clearSocketCacheSafe = () => {
+  try {
+    const socketDeleted = clearSocketCache();
+    if (socketDeleted > 0) {
+      pail.info(`Cleared ${String(socketDeleted)} cached Socket.dev report${socketDeleted === 1 ? "" : "s"}.`);
+    }
+  } catch (error) {
+    pail.warn(`Failed to clear Socket.dev cache: ${error instanceof Error ? error.message : String(error)}`);
+  }
+};
+const runClean = async (cacheDirectory, workspaceRoot, options) => {
+  if (!isAccessibleSync(cacheDirectory)) {
+    pail.info(`No cache directory to clean at ${cacheDirectory}`);
+    return;
+  }
+  if (options.dryRun) {
+    const entries = await collectCacheEntries(cacheDirectory);
+    const totalBytes = entries.reduce((sum, entry) => sum + entry.sizeBytes, 0);
+    pail.info(
+      `Would remove ${String(entries.length)} cache entr${entries.length === 1 ? "y" : "ies"} (${formatBytes(totalBytes, { decimals: 1, space: false })}) from ${cacheDirectory}`
+    );
+    return;
+  }
+  const insideWorkspace = isCacheDirectoryInsideWorkspace(cacheDirectory, workspaceRoot);
+  try {
+    const realCache = await realpath(cacheDirectory);
+    const realWorkspace = await realpath(workspaceRoot);
+    if (realCache === realWorkspace) {
+      pail.error("Refusing to delete the workspace root. The cache directory resolved to the same path as the workspace.");
+      process.exitCode = 1;
+      return;
+    }
+  } catch {
+  }
+  if (!insideWorkspace && !options.force) {
+    pail.warn(`Cache directory is outside the workspace root: ${cacheDirectory}`);
+    pail.warn("This will recursively delete the entire directory, including anything stored there by other tools.");
+    if (!process.stdin.isTTY) {
+      pail.error("Refusing to clean an out-of-workspace cache without --force (stdin is not a TTY).");
+      process.exitCode = 1;
+      return;
+    }
+    const confirmed = await confirmPrompt("  Continue?");
+    if (!confirmed) {
+      pail.info("Aborted.");
+      return;
+    }
+  }
+  if (insideWorkspace) {
+    const cache = new Cache({ cacheDirectory, workspaceRoot });
+    await cache.clear();
+  } else {
+    await rm(cacheDirectory, { force: true, recursive: true });
+  }
+  pail.success(`Cleared cache: ${cacheDirectory}`);
+};
+const runPrune = async (cacheDirectory, workspaceRoot, options) => {
+  if (!isAccessibleSync(cacheDirectory)) {
+    pail.info(`No cache directory to prune at ${cacheDirectory}`);
+    return;
+  }
+  if (options.maxCacheAgeDays !== void 0 && (!Number.isFinite(options.maxCacheAgeDays) || options.maxCacheAgeDays < 0)) {
+    pail.error(`Invalid --max-age-days value: expected a finite number >= 0, got ${String(options.maxCacheAgeDays)}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (options.keepLast !== void 0 && (!Number.isFinite(options.keepLast) || options.keepLast < 0 || !Number.isInteger(options.keepLast))) {
+    pail.error(`Invalid --keep-last value: expected a non-negative integer, got ${String(options.keepLast)}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (options.maxCacheSize !== void 0) {
+    let parsedBytes;
+    try {
+      parsedBytes = parseCacheSize(options.maxCacheSize);
+    } catch (error) {
+      pail.error(`Invalid --max-size value: ${error instanceof Error ? error.message : String(error)}`);
+      process.exitCode = 1;
+      return;
+    }
+    if (!Number.isFinite(parsedBytes) || parsedBytes <= 0) {
+      pail.error(`Invalid --max-size value: expected a positive size, got "${options.maxCacheSize}" (${String(parsedBytes)} bytes)`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+  const maxCacheAge = options.maxCacheAgeDays === void 0 ? void 0 : options.maxCacheAgeDays * 24 * 60 * 60 * 1e3;
+  const before = await collectCacheEntries(cacheDirectory);
+  const beforeBytes = before.reduce((sum, entry) => sum + entry.sizeBytes, 0);
+  if (options.keepLast !== void 0 && before.length > options.keepLast) {
+    const stale = before.slice(options.keepLast);
+    await Promise.all(stale.map((entry) => rm(entry.path, { force: true, recursive: true })));
+  }
+  const cache = new Cache({
+    cacheDirectory,
+    maxCacheAge,
+    maxCacheSize: options.maxCacheSize,
+    workspaceRoot
+  });
+  await cache.removeOldEntries();
+  const after = await collectCacheEntries(cacheDirectory);
+  const afterBytes = after.reduce((sum, entry) => sum + entry.sizeBytes, 0);
+  const removed = before.length - after.length;
+  const reclaimedBytes = beforeBytes - afterBytes;
+  if (removed <= 0) {
+    pail.info("Nothing to prune — all entries are within the configured limits.");
+    return;
+  }
+  pail.success(`Pruned ${String(removed)} entr${removed === 1 ? "y" : "ies"}, freed ${formatBytes(reclaimedBytes, { decimals: 1, space: false })}.`);
+};
+const HASH_DISPLAY_PREFIX = 16;
+const truncateHash = (value) => value.length > HASH_DISPLAY_PREFIX ? `${value.slice(0, HASH_DISPLAY_PREFIX)}…` : value;
+const renderHashDetailsBucket = (label, bucket, logger) => {
+  const entries = Object.entries(bucket ?? {});
+  if (entries.length === 0) {
+    return;
+  }
+  logger.info(`  ${label}:`);
+  entries.sort(([a], [b]) => a.localeCompare(b));
+  for (const [key, value] of entries) {
+    logger.info(`    ${key.padEnd(40)}  ${truncateHash(value)}`);
+  }
+};
+const runWhy = async (taskId, options, logger) => {
+  const { format, runId, workspaceRoot } = options;
+  const summary = runId === void 0 ? await readLastRunSummary(workspaceRoot) : await readRunSummaryById(workspaceRoot, runId);
+  if (!summary) {
+    if (format === "json") {
+      process.stdout.write(`${JSON.stringify({ error: "no-summary", runId: runId ?? null, taskId }, void 0, 2)}
+`);
+      process.exitCode = 1;
+      return;
+    }
+    if (runId === void 0) {
+      pail.error("No previous run summary found. Run a task first to populate `.task-runner/last-summary.json`.");
+    } else {
+      pail.error(`Run summary "${runId}" not found in .task-runner/runs/.`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+  const task = findTaskInSummary(summary, taskId);
+  if (!task) {
+    if (format === "json") {
+      process.stdout.write(`${JSON.stringify({ error: "task-not-in-summary", runId: summary.id, taskId }, void 0, 2)}
+`);
+      process.exitCode = 1;
+      return;
+    }
+    pail.error(`Task "${taskId}" was not part of run ${summary.id}.`);
+    pail.info(`Tasks in this run: ${summary.tasks.map((t) => t.taskId).join(", ") || "(none)"}`);
+    process.exitCode = 1;
+    return;
+  }
+  const previousSummary = await readPreviousRunSummary(workspaceRoot, summary.id);
+  const previousTask = previousSummary ? findTaskInSummary(previousSummary, taskId) : void 0;
+  const diff = diffHashDetails(task.hashDetails, previousTask?.hashDetails);
+  if (format === "json") {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          diff,
+          previousRunId: previousSummary?.id ?? null,
+          previousTask: previousTask ? {
+            cacheStatus: previousTask.cacheStatus,
+            hash: previousTask.hash ?? null,
+            hashDetails: previousTask.hashDetails ?? null
+          } : null,
+          runId: summary.id,
+          task: {
+            cacheStatus: task.cacheStatus,
+            hash: task.hash ?? null,
+            hashDetails: task.hashDetails ?? null,
+            taskId: task.taskId
+          }
+        },
+        void 0,
+        2
+      )}
+`
+    );
+    return;
+  }
+  pail.info(`Why ${taskId}? (run ${summary.id})`);
+  logger.info("");
+  logger.info(`  status:  ${task.cacheStatus}`);
+  logger.info(`  hash:    ${task.hash ?? "(none)"}`);
+  if (previousTask) {
+    logger.info(`  prev:    ${previousTask.hash ?? "(none)"}  [run ${previousSummary?.id ?? "?"}]`);
+  } else {
+    logger.info(`  prev:    (no prior run found)`);
+  }
+  logger.info("");
+  if (!previousTask) {
+    pail.info("No previous run to diff against — first time this task was recorded.");
+    return;
+  }
+  const noChanges = !diff.commandChanged && diff.nodes.added.length === 0 && diff.nodes.changed.length === 0 && diff.nodes.removed.length === 0 && diff.runtime.added.length === 0 && diff.runtime.changed.length === 0 && diff.runtime.removed.length === 0 && diff.implicitDeps.added.length === 0 && diff.implicitDeps.changed.length === 0 && diff.implicitDeps.removed.length === 0;
+  if (noChanges) {
+    pail.success("No hash inputs changed since the previous run.");
+    return;
+  }
+  logger.info("Hash inputs that changed since the previous run:");
+  logger.info("");
+  if (diff.commandChanged) {
+    logger.info("  command:  changed");
+  }
+  for (const bucket of ["nodes", "runtime", "implicitDeps"]) {
+    const bucketDiff = diff[bucket];
+    if (bucketDiff.added.length === 0 && bucketDiff.changed.length === 0 && bucketDiff.removed.length === 0) {
+      continue;
+    }
+    logger.info(`  ${bucket}:`);
+    for (const key of bucketDiff.added) {
+      logger.info(`    + ${key}`);
+    }
+    for (const key of bucketDiff.changed) {
+      logger.info(`    ~ ${key}`);
+    }
+    for (const key of bucketDiff.removed) {
+      logger.info(`    - ${key}`);
+    }
+  }
+  logger.info("");
+  pail.info(`Last summary file: ${getLastRunSummaryPath(workspaceRoot)}`);
+};
+const runHash = async (taskId, options, logger) => {
+  const { format, runId, workspaceRoot } = options;
+  const summary = runId === void 0 ? await readLastRunSummary(workspaceRoot) : await readRunSummaryById(workspaceRoot, runId);
+  if (!summary) {
+    if (format === "json") {
+      process.stdout.write(`${JSON.stringify({ error: "no-summary", runId: runId ?? null, taskId }, void 0, 2)}
+`);
+      process.exitCode = 1;
+      return;
+    }
+    if (runId === void 0) {
+      pail.error("No previous run summary found. Run a task first to populate `.task-runner/last-summary.json`.");
+    } else {
+      pail.error(`Run summary "${runId}" not found in .task-runner/runs/.`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+  const task = findTaskInSummary(summary, taskId);
+  if (!task) {
+    if (format === "json") {
+      process.stdout.write(`${JSON.stringify({ error: "task-not-in-summary", runId: summary.id, taskId }, void 0, 2)}
+`);
+      process.exitCode = 1;
+      return;
+    }
+    pail.error(`Task "${taskId}" was not part of run ${summary.id}.`);
+    process.exitCode = 1;
+    return;
+  }
+  if (format === "json") {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          cacheStatus: task.cacheStatus,
+          hash: task.hash ?? null,
+          hashDetails: task.hashDetails ?? null,
+          runId: summary.id,
+          taskId: task.taskId
+        },
+        void 0,
+        2
+      )}
+`
+    );
+    return;
+  }
+  pail.info(`Hash for ${taskId} (run ${summary.id})`);
+  logger.info("");
+  logger.info(`  status:  ${task.cacheStatus}`);
+  logger.info(`  hash:    ${task.hash ?? "(none)"}`);
+  if (task.hashDetails) {
+    logger.info("");
+    logger.info(`  command: ${truncateHash(task.hashDetails.command)}`);
+    renderHashDetailsBucket("nodes", task.hashDetails.nodes, logger);
+    renderHashDetailsBucket("runtime", task.hashDetails.runtime, logger);
+    renderHashDetailsBucket("implicitDeps", task.hashDetails.implicitDeps, logger);
+  } else {
+    logger.info("");
+    pail.info("No hash details recorded for this task.");
+  }
+};
+const runSize = async (cacheDirectory, format) => {
+  if (!isAccessibleSync(cacheDirectory)) {
+    if (format === "json") {
+      process.stdout.write(`${JSON.stringify({ directory: cacheDirectory, exists: false, totalBytes: 0, totalCount: 0 })}
+`);
+      return;
+    }
+    pail.info(`No cache directory at ${cacheDirectory}`);
+    return;
+  }
+  const entries = await collectCacheEntries(cacheDirectory);
+  const totalBytes = entries.reduce((sum, entry) => sum + entry.sizeBytes, 0);
+  if (format === "json") {
+    process.stdout.write(
+      `${JSON.stringify({
+        directory: cacheDirectory,
+        exists: true,
+        totalBytes,
+        totalCount: entries.length
+      })}
+`
+    );
+    return;
+  }
+  pail.info(`Cache directory: ${cacheDirectory}`);
+  pail.info(`Entries:         ${String(entries.length)}`);
+  pail.info(`Total size:      ${formatBytes(totalBytes, { decimals: 1, space: false })}`);
+};
+const walkAndDigest = async (root) => {
+  const out = [];
+  const walk = async (absolute) => {
+    const items = (await readdir(absolute, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
+    for (const item of items) {
+      const childAbsolute = join(absolute, item.name);
+      if (item.isDirectory()) {
+        await walk(childAbsolute);
+        continue;
+      }
+      if (!item.isFile()) {
+        continue;
+      }
+      const [info, digest] = await Promise.all([stat(childAbsolute), digestFile(childAbsolute)]);
+      out.push({
+        hash: digest?.hash ?? "",
+        // eslint-disable-next-line no-bitwise -- low 12 bits hold the rwx triplet
+        mode: info.mode & 4095,
+        mtimeMs: info.mtimeMs,
+        relativePath: relative(root, childAbsolute).replaceAll("\\", "/"),
+        sizeBytes: info.size
+      });
+    }
+  };
+  await walk(root);
+  return out;
+};
+const compareSecondsTruncated = (a, b) => Math.floor(a / 1e3) === Math.floor(b / 1e3);
+const VERIFY_DIFF_CONCURRENCY = 16;
+const computeFileDiff = async (file, workspaceRoot) => {
+  const livePath = join(workspaceRoot, file.relativePath);
+  const liveStat = await stat(livePath).catch(() => void 0);
+  if (!liveStat) {
+    return {
+      expected: { hash: file.hash, mode: file.mode, mtimeMs: file.mtimeMs },
+      issues: ["missing"],
+      relativePath: file.relativePath
+    };
+  }
+  const liveDigest = await digestFile(livePath);
+  const issues = [];
+  if ((liveDigest?.hash ?? "") !== file.hash) {
+    issues.push("content");
+  }
+  const liveMode = liveStat.mode & 4095;
+  if (process.platform !== "win32" && liveMode !== file.mode) {
+    issues.push("mode");
+  }
+  if (!compareSecondsTruncated(liveStat.mtimeMs, file.mtimeMs)) {
+    issues.push("mtime");
+  }
+  if (issues.length === 0) {
+    return void 0;
+  }
+  return {
+    actual: { hash: liveDigest?.hash, mode: liveMode, mtimeMs: liveStat.mtimeMs },
+    expected: { hash: file.hash, mode: file.mode, mtimeMs: file.mtimeMs },
+    issues,
+    relativePath: file.relativePath
+  };
+};
+const runVerify = async (taskId, options, logger) => {
+  const { cacheDirectories, format, workspaceRoot } = options;
+  if (cacheDirectories.length === 0) {
+    if (format === "json") {
+      process.stdout.write(`${JSON.stringify({ error: "no-cache-directory", taskId }, void 0, 2)}
+`);
+    } else {
+      pail.error("No cache directory resolved — pass --cache-dir or run inside a workspace.");
+    }
+    process.exitCode = 1;
+    return;
+  }
+  let cacheDirectory;
+  let cached;
+  for (const directory of cacheDirectories) {
+    const found = await new Cache({ cacheDirectory: directory, workspaceRoot }).getByTaskId(taskId);
+    if (found) {
+      cacheDirectory = directory;
+      cached = found;
+      break;
+    }
+  }
+  if (!cached || !cacheDirectory) {
+    if (format === "json") {
+      process.stdout.write(`${JSON.stringify({ error: "no-cached-entry", searchedCaches: cacheDirectories, taskId }, void 0, 2)}
+`);
+    } else {
+      pail.error(`No cached entry found for task "${taskId}". Run it once before verifying.`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+  const stagingRoot = await mkdtemp(join(tmpdir(), "vis-cache-verify-"));
+  try {
+    const stagingCache = new Cache({ cacheDirectory, workspaceRoot: stagingRoot });
+    const restored = await stagingCache.restoreOutputs(cached.hash);
+    if (!restored) {
+      if (format === "json") {
+        process.stdout.write(`${JSON.stringify({ error: "restore-failed", hash: cached.hash, taskId }, void 0, 2)}
+`);
+      } else {
+        pail.error(`Cache restore failed for ${taskId} (hash ${cached.hash}).`);
+      }
+      process.exitCode = 1;
+      return;
+    }
+    const cachedFiles = await walkAndDigest(stagingRoot);
+    if (cachedFiles.length === 0) {
+      if (format === "json") {
+        process.stdout.write(`${JSON.stringify({ diffs: [], hash: cached.hash, status: "no-outputs", taskId }, void 0, 2)}
+`);
+      } else {
+        pail.info(`Cached entry for ${taskId} has no recorded outputs — nothing to verify.`);
+      }
+      return;
+    }
+    const diffSlots = Array.from({ length: cachedFiles.length });
+    for (let offset = 0; offset < cachedFiles.length; offset += VERIFY_DIFF_CONCURRENCY) {
+      const chunk = cachedFiles.slice(offset, offset + VERIFY_DIFF_CONCURRENCY);
+      const results = await Promise.all(chunk.map(async (file) => computeFileDiff(file, workspaceRoot)));
+      for (const [index, result] of results.entries()) {
+        diffSlots[offset + index] = result;
+      }
+    }
+    const diffs = diffSlots.filter((slot) => slot !== void 0);
+    if (format === "json") {
+      process.stdout.write(
+        `${JSON.stringify(
+          {
+            cacheDirectory,
+            cachedFileCount: cachedFiles.length,
+            diffs,
+            hash: cached.hash,
+            status: diffs.length === 0 ? "ok" : "drift",
+            taskId
+          },
+          void 0,
+          2
+        )}
+`
+      );
+      if (diffs.length > 0) {
+        process.exitCode = 1;
+      }
+      return;
+    }
+    pail.info(`Verify ${taskId}  (hash ${cached.hash})`);
+    logger.info("");
+    logger.info(`  cache:      ${cacheDirectory}`);
+    logger.info(`  files:      ${String(cachedFiles.length)}`);
+    if (diffs.length === 0) {
+      logger.info("");
+      pail.success("Cache restore is faithful — all files match content, mode, and mtime.");
+      return;
+    }
+    logger.info(`  drift:      ${String(diffs.length)} file(s)`);
+    logger.info("");
+    for (const diff of diffs) {
+      const tag = diff.issues.includes("missing") ? "MISSING" : diff.issues.join(",").toUpperCase();
+      logger.info(`  [${tag}] ${diff.relativePath}`);
+      if (!diff.issues.includes("missing") && diff.expected && diff.actual) {
+        if (diff.issues.includes("content")) {
+          logger.info(`    expected hash: ${diff.expected.hash || "(none)"}`);
+          logger.info(`    actual   hash: ${diff.actual.hash ?? "(unreadable)"}`);
+        }
+        if (diff.issues.includes("mode")) {
+          logger.info(`    expected mode: ${diff.expected.mode.toString(8)}`);
+          logger.info(`    actual   mode: ${(diff.actual.mode ?? 0).toString(8)}`);
+        }
+        if (diff.issues.includes("mtime")) {
+          logger.info(`    expected mtime: ${new Date(diff.expected.mtimeMs).toISOString()}`);
+          logger.info(`    actual   mtime: ${diff.actual.mtimeMs === void 0 ? "(unreadable)" : new Date(diff.actual.mtimeMs).toISOString()}`);
+        }
+      }
+    }
+    process.exitCode = 1;
+  } finally {
+    await rm(stagingRoot, { force: true, recursive: true }).catch(() => {
+    });
+  }
+};
+const parseCacheTarget = (raw) => {
+  if (raw === "task" || raw === "ai" || raw === "socket" || raw === "all") {
+    return raw;
+  }
+  if (raw && raw.length > 0) {
+    pail.warn(`Unknown --type value '${raw}'; falling back to 'all'.`);
+  }
+  return "all";
+};
+const includesTarget = (selected, kind) => selected === "all" || selected === kind;
+const isoOrNull = (value) => value === void 0 ? null : new Date(value).toISOString();
+const printAuxStatsBlock = (label, stats) => {
+  pail.info(`${label}:`);
+  pail.info(`  Entries:    ${String(stats.entries)}`);
+  pail.info(`  Total size: ${formatBytes(stats.totalSizeBytes, { decimals: 1, space: false })}`);
+  pail.info(`  Oldest:     ${stats.oldestEntry ? new Date(stats.oldestEntry).toISOString() : "N/A"}`);
+  pail.info(`  Newest:     ${stats.newestEntry ? new Date(stats.newestEntry).toISOString() : "N/A"}`);
+};
+const parseScope = (raw) => {
+  if (raw === "worktree" || raw === "shared" || raw === "all") {
+    return raw;
+  }
+  if (raw && raw.length > 0) {
+    pail.warn(`Unknown --scope value '${raw}'; falling back to 'shared'.`);
+  }
+  return "shared";
+};
+const resolveCacheDirectoryFromContext = (workspaceRoot, options, visConfig) => {
+  const resolvedWorkspaceRoot = workspaceRoot ?? process.cwd();
+  const cfg = visConfig ?? {};
+  const taskRunnerOptions = cfg.taskRunnerOptions ?? {};
+  const scope = parseScope(options.scope);
+  const optionsCacheDir = options.cacheDir;
+  const worktreeDirectory = resolveSharedCacheDirectory(resolvedWorkspaceRoot, optionsCacheDir, taskRunnerOptions.cacheDirectory, false);
+  const sharedDirectory = resolveSharedCacheDirectory(resolvedWorkspaceRoot, optionsCacheDir, taskRunnerOptions.cacheDirectory, cfg.sharedWorktreeCache);
+  let primary;
+  let directories;
+  switch (scope) {
+    case "all": {
+      primary = sharedDirectory;
+      directories = sharedDirectory === worktreeDirectory ? [sharedDirectory] : [sharedDirectory, worktreeDirectory];
+      break;
+    }
+    case "worktree": {
+      primary = worktreeDirectory;
+      directories = [worktreeDirectory];
+      break;
+    }
+    default: {
+      primary = sharedDirectory;
+      directories = [sharedDirectory];
+    }
+  }
+  return {
+    cacheDirectories: directories,
+    cacheDirectory: primary,
+    scope,
+    sharedWorktreeCache: cfg.sharedWorktreeCache,
+    workspaceRoot: resolvedWorkspaceRoot
+  };
+};
+const cacheListExecute = async ({ logger, options, visConfig, workspaceRoot: wsRoot }) => {
+  const { cacheDirectories } = resolveCacheDirectoryFromContext(wsRoot, options, visConfig);
+  const format = options.format ?? "table";
+  for (const directory of cacheDirectories) {
+    if (cacheDirectories.length > 1) {
+      pail.info(`# ${directory}`);
+    }
+    await runList(directory, format, logger);
+  }
+};
+const cacheCleanExecute = async ({ options, visConfig, workspaceRoot: wsRoot }) => {
+  const target = parseCacheTarget(options.type);
+  const dryRun = Boolean(options.dryRun);
+  if (includesTarget(target, "task")) {
+    const { cacheDirectory, workspaceRoot } = resolveCacheDirectoryFromContext(wsRoot, options, visConfig);
+    await runClean(cacheDirectory, workspaceRoot, {
+      dryRun,
+      force: Boolean(options.force)
+    });
+  }
+  if (includesTarget(target, "ai")) {
+    if (dryRun) {
+      const stats = getCacheStats();
+      pail.info(`Would clear ${String(stats.entries)} cached AI response${stats.entries === 1 ? "" : "s"}.`);
+    } else {
+      clearAiCacheSafe();
+    }
+  }
+  if (includesTarget(target, "socket")) {
+    if (dryRun) {
+      const stats = getSocketCacheStats();
+      pail.info(`Would clear ${String(stats.entries)} cached Socket.dev report${stats.entries === 1 ? "" : "s"}.`);
+    } else {
+      clearSocketCacheSafe();
+    }
+  }
+};
+const cachePruneExecute = async ({ options, visConfig, workspaceRoot: wsRoot }) => {
+  const { cacheDirectories, workspaceRoot } = resolveCacheDirectoryFromContext(wsRoot, options, visConfig);
+  for (const directory of cacheDirectories) {
+    if (cacheDirectories.length > 1) {
+      pail.info(`# ${directory}`);
+    }
+    await runPrune(directory, workspaceRoot, {
+      keepLast: typeof options.keepLast === "number" ? options.keepLast : void 0,
+      maxCacheAgeDays: typeof options.maxAgeDays === "number" ? options.maxAgeDays : void 0,
+      maxCacheSize: options.maxSize
+    });
+  }
+};
+const resolveWorkspaceRoot = (workspaceRoot) => workspaceRoot ?? process.cwd();
+const cacheWhyExecute = async ({ argument, logger, options, workspaceRoot: wsRoot }) => {
+  const taskId = argument[0];
+  if (!taskId) {
+    pail.error("No task ID specified. Usage: vis cache why <project>:<target>");
+    process.exitCode = 1;
+    return;
+  }
+  await runWhy(
+    taskId,
+    {
+      format: options.format ?? "table",
+      runId: options.run,
+      workspaceRoot: resolveWorkspaceRoot(wsRoot)
+    },
+    logger
+  );
+};
+const cacheHashExecute = async ({ argument, logger, options, workspaceRoot: wsRoot }) => {
+  const taskId = argument[0];
+  if (!taskId) {
+    pail.error("No task ID specified. Usage: vis cache hash <project>:<target>");
+    process.exitCode = 1;
+    return;
+  }
+  await runHash(
+    taskId,
+    {
+      format: options.format ?? "table",
+      runId: options.run,
+      workspaceRoot: resolveWorkspaceRoot(wsRoot)
+    },
+    logger
+  );
+};
+const cacheSizeExecute = async ({ options, visConfig, workspaceRoot: wsRoot }) => {
+  const target = parseCacheTarget(options.type);
+  const format = options.format ?? "table";
+  if (format === "json") {
+    const payload = {};
+    if (includesTarget(target, "task")) {
+      const { cacheDirectories } = resolveCacheDirectoryFromContext(wsRoot, options, visConfig);
+      payload.task = await Promise.all(
+        cacheDirectories.map(async (directory) => {
+          const exists = isAccessibleSync(directory);
+          const entries = exists ? await collectCacheEntries(directory) : [];
+          const totalBytes = entries.reduce((sum, entry) => sum + entry.sizeBytes, 0);
+          return {
+            directory,
+            entries: entries.length,
+            exists,
+            newestEntry: isoOrNull(entries[0]?.mtimeMs),
+            oldestEntry: isoOrNull(entries.at(-1)?.mtimeMs),
+            totalBytes
+          };
+        })
+      );
+    }
+    if (includesTarget(target, "ai")) {
+      const stats = getCacheStats();
+      payload.ai = {
+        entries: stats.entries,
+        newestEntry: isoOrNull(stats.newestEntry),
+        oldestEntry: isoOrNull(stats.oldestEntry),
+        totalBytes: stats.totalSizeBytes
+      };
+    }
+    if (includesTarget(target, "socket")) {
+      const stats = getSocketCacheStats();
+      payload.socket = {
+        entries: stats.entries,
+        newestEntry: isoOrNull(stats.newestEntry),
+        oldestEntry: isoOrNull(stats.oldestEntry),
+        totalBytes: stats.totalSizeBytes
+      };
+    }
+    process.stdout.write(`${JSON.stringify(payload, void 0, 2)}
+`);
+    return;
+  }
+  if (includesTarget(target, "task")) {
+    const { cacheDirectories } = resolveCacheDirectoryFromContext(wsRoot, options, visConfig);
+    for (const directory of cacheDirectories) {
+      if (cacheDirectories.length > 1) {
+        pail.info(`# ${directory}`);
+      }
+      await runSize(directory, "table");
+    }
+  }
+  if (includesTarget(target, "ai")) {
+    printAuxStatsBlock("AI response cache", getCacheStats());
+  }
+  if (includesTarget(target, "socket")) {
+    printAuxStatsBlock("Socket.dev report cache", getSocketCacheStats());
+  }
+};
+const cacheVerifyExecute = async ({
+  argument,
+  logger,
+  options,
+  visConfig,
+  workspaceRoot: wsRoot
+}) => {
+  const taskId = argument[0];
+  if (!taskId) {
+    pail.error("No task ID specified. Usage: vis cache verify <project>:<target>");
+    process.exitCode = 1;
+    return;
+  }
+  const { cacheDirectories, workspaceRoot } = resolveCacheDirectoryFromContext(wsRoot, options, visConfig);
+  await runVerify(
+    taskId,
+    {
+      cacheDirectories,
+      format: options.format ?? "table",
+      workspaceRoot
+    },
+    logger
+  );
+};
+
+export { cacheCleanExecute, cacheHashExecute, cacheListExecute, cachePruneExecute, cacheSizeExecute, cacheVerifyExecute, cacheWhyExecute, clearAiCacheSafe, clearSocketCacheSafe, collectCacheEntries, formatAge, runClean, runHash, runList, runPrune, runSize, runVerify, runWhy };