@lexmanh/shed-cli 0.3.0-beta.2 → 0.4.0-beta.1

package/dist/cli.js

@@ -7,6 +7,7 @@ import { Command } from "commander";
 // src/commands/clean.ts
 import * as p2 from "@clack/prompts";
 import {
+  OpLog,
   RiskTier,
   SafetyChecker,
   Scanner,
@@ -111,7 +112,7 @@ async function cleanCommand(path, options = {}) {
     p2.outro(pc2.dim("Nothing to clean."));
     return;
   }
-  const checker = new SafetyChecker();
+  const checker = new SafetyChecker({ oplog: new OpLog() });
   const checkResults = await Promise.all(allItems.map((item) => checker.check(item)));
   const eligibleItems = allItems.filter((_, i) => {
     const result2 = checkResults[i];
@@ -250,9 +251,14 @@ async function cleanCommand(path, options = {}) {
       console.log(`    ${pc2.dim(f.item.path)}: ${f.error}`);
     }
   }
+  if (!isDryRun && !options.hardDelete && result.succeeded.length > 0) {
+    console.log();
+    console.log(`  ${pc2.dim("To restore: ")}${pc2.cyan(`shed undo --session ${result.sessionId}`)}`);
+    console.log(`  ${pc2.dim("History:    ")}${pc2.cyan("shed history")}`);
+  }
   console.log();
-  const outro7 = isDryRun ? `Dry-run complete. Run with ${pc2.cyan("--execute")} to perform actual cleanup.` : result.failed.length > 0 ? `Completed with ${result.failed.length} failure(s).` : "All done!";
-  p2.outro(outro7);
+  const outro8 = isDryRun ? `Dry-run complete. Run with ${pc2.cyan("--execute")} to perform actual cleanup.` : result.failed.length > 0 ? `Completed with ${result.failed.length} failure(s).` : "All done!";
+  p2.outro(outro8);
 }
 
 // src/commands/completions.ts
@@ -535,16 +541,89 @@ async function doctorCommand() {
   p4.outro(pc4.green("Environment check complete."));
 }
 
+// src/commands/history.ts
+import * as p5 from "@clack/prompts";
+import { OpLog as OpLog2 } from "@lexmanh/shed-core";
+import pc5 from "picocolors";
+function formatBytes2(bytes) {
+  if (bytes === 0) return "0 B";
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+  return `${(bytes / 1024 / 1024 / 1024).toFixed(2)} GB`;
+}
+function formatRelative(ts) {
+  const ms = Date.now() - new Date(ts).getTime();
+  if (Number.isNaN(ms)) return ts;
+  const sec = Math.floor(ms / 1e3);
+  if (sec < 60) return `${sec}s ago`;
+  const min = Math.floor(sec / 60);
+  if (min < 60) return `${min}m ago`;
+  const hr = Math.floor(min / 60);
+  if (hr < 24) return `${hr}h ago`;
+  const day = Math.floor(hr / 24);
+  return `${day}d ago`;
+}
+var ACTION_BADGE = {
+  trash: pc5.cyan("TRASH "),
+  delete: pc5.red("DELETE"),
+  revert: pc5.green("REVERT")
+};
+var RISK_DOT = {
+  green: pc5.green("\u25CF"),
+  yellow: pc5.yellow("\u25CF"),
+  red: pc5.red("\u25CF")
+};
+async function historyCommand(options = {}) {
+  const limit = options.limit ? Math.max(1, Number.parseInt(options.limit, 10) || 20) : 20;
+  const oplog = new OpLog2();
+  const entries = await oplog.read({ limit, session: options.session });
+  if (options.json) {
+    console.log(JSON.stringify({ entries }, null, 2));
+    return;
+  }
+  p5.intro(pc5.bgMagenta(pc5.black(" shed history ")));
+  if (entries.length === 0) {
+    p5.note(
+      [
+        "No cleanup operations have been recorded yet.",
+        "",
+        `Run ${pc5.cyan("shed clean --execute")} to perform a real cleanup.`,
+        "",
+        pc5.dim("Operations are logged to ~/.shed/ops.jsonl when shed actually deletes files.")
+      ].join("\n"),
+      "Empty oplog"
+    );
+    p5.outro(pc5.dim("Nothing to show."));
+    return;
+  }
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+  const lines = entries.map((e) => {
+    const path = home ? e.path.replace(home, "~") : e.path;
+    const reverted = e.reverted ? pc5.dim(" [reverted]") : "";
+    const tokenShort = e.token.slice(-8);
+    const when = formatRelative(e.ts);
+    return `  ${ACTION_BADGE[e.action]} ${RISK_DOT[e.risk]} ${pc5.dim(when.padEnd(7))} ${pc5.bold(tokenShort)}  ${path}  ${pc5.dim(formatBytes2(e.sizeBytes))}${reverted}`;
+  });
+  console.log();
+  console.log(`  ${pc5.bold(`Last ${entries.length} operation(s):`)}`);
+  console.log();
+  for (const line of lines) console.log(line);
+  console.log();
+  p5.outro(
+    `Restore: ${pc5.cyan("shed undo <token>")}  \xB7  All in session: ${pc5.cyan("shed undo --session <id>")}`
+  );
+}
+
 // src/commands/scan.ts
 import { createRequire } from "module";
 import { hostname } from "os";
-import * as p5 from "@clack/prompts";
+import * as p6 from "@clack/prompts";
 import {
   RiskTier as RiskTier2,
   Scanner as Scanner2,
   defaultDetectors as defaultDetectors2
 } from "@lexmanh/shed-core";
-import pc5 from "picocolors";
+import pc6 from "picocolors";
 
 // src/commands/scan-aggregate.ts
 import { dirname } from "path";
@@ -622,16 +701,16 @@ var JSON_SCHEMA_VERSION = 2;
 var COMPACT_TOP_N = 15;
 var DETECTOR_BREAKDOWN_TOP_N = 6;
 var RISK_LABEL = {
-  [RiskTier2.Green]: pc5.green("\u25CF Green"),
-  [RiskTier2.Yellow]: pc5.yellow("\u25CF Yellow"),
-  [RiskTier2.Red]: pc5.red("\u25CF Red")
+  [RiskTier2.Green]: pc6.green("\u25CF Green"),
+  [RiskTier2.Yellow]: pc6.yellow("\u25CF Yellow"),
+  [RiskTier2.Red]: pc6.red("\u25CF Red")
 };
 var RISK_ORDER = {
   [RiskTier2.Red]: 0,
   [RiskTier2.Yellow]: 1,
   [RiskTier2.Green]: 2
 };
-function formatBytes2(bytes) {
+function formatBytes3(bytes) {
   if (bytes === 0) return "0 B";
   if (bytes < 1024) return `${bytes} B`;
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
@@ -640,7 +719,7 @@ function formatBytes2(bytes) {
 }
 async function scanCommand(path, options = {}) {
   if (!options.json) {
-    p5.intro(pc5.bgCyan(pc5.black(" shed scan ")));
+    p6.intro(pc6.bgCyan(pc6.black(" shed scan ")));
   }
   const scope = await resolveScanScope({ path, nonInteractive: options.json });
   if (!scope.ok) {
@@ -649,11 +728,11 @@ async function scanCommand(path, options = {}) {
         JSON.stringify({ schemaVersion: JSON_SCHEMA_VERSION, error: scope.message }, null, 2)
       );
     } else {
-      p5.cancel(scope.message);
+      p6.cancel(scope.message);
     }
     return;
   }
-  const spinner4 = options.json ? null : p5.spinner();
+  const spinner4 = options.json ? null : p6.spinner();
   verbose(`scan roots: ${scope.roots.join(", ")}`);
   spinner4?.start(
     scope.roots.length === 1 ? `Scanning ${scope.roots[0]} \u2026` : `Scanning ${scope.roots.length} roots \u2026`
@@ -675,7 +754,7 @@ async function scanCommand(path, options = {}) {
   for (const item of allItems)
     verbose(`  item: ${item.risk} ${item.path} (${item.sizeBytes} bytes)`);
   spinner4?.stop(
-    `Found ${pc5.bold(String(allItems.length))} cleanable items across ${projects.length} project(s).`
+    `Found ${pc6.bold(String(allItems.length))} cleanable items across ${projects.length} project(s).`
   );
   if (options.json) {
     const byRisk = { green: 0, yellow: 0, red: 0 };
@@ -721,8 +800,8 @@ async function scanCommand(path, options = {}) {
     return;
   }
   if (allItems.length === 0) {
-    p5.note("Nothing found to clean in this directory.", "Result");
-    p5.outro(pc5.dim("All clear!"));
+    p6.note("Nothing found to clean in this directory.", "Result");
+    p6.outro(pc6.dim("All clear!"));
     return;
   }
   if (options.all) {
@@ -731,8 +810,8 @@ async function scanCommand(path, options = {}) {
     renderCompact(allItems);
   }
   console.log();
-  p5.outro(
-    `Total recoverable: ${pc5.bold(pc5.green(formatBytes2(totalBytes)))} \u2014 run ${pc5.cyan("shed clean")} to proceed.`
+  p6.outro(
+    `Total recoverable: ${pc6.bold(pc6.green(formatBytes3(totalBytes)))} \u2014 run ${pc6.cyan("shed clean")} to proceed.`
   );
 }
 function renderCompact(allItems) {
@@ -745,26 +824,26 @@ function renderCompact(allItems) {
     if (item.metadata?.detectOnly === true) detectOnly++;
     byDetector.set(item.detector, (byDetector.get(item.detector) ?? 0) + item.sizeBytes);
   }
-  const riskLine = `${pc5.green(`\u25CF ${byRisk.green} Green`)}   ${pc5.yellow(`\u25CF ${byRisk.yellow} Yellow`)}   ${pc5.red(`\u25CF ${byRisk.red} Red`)}${detectOnly > 0 ? pc5.dim(` (${detectOnly} detect-only)`) : ""}`;
-  const detectorLine = [...byDetector.entries()].sort(([, a], [, b]) => b - a).slice(0, DETECTOR_BREAKDOWN_TOP_N).map(([d, b]) => `${d} ${formatBytes2(b)}`).join(" \xB7 ");
+  const riskLine = `${pc6.green(`\u25CF ${byRisk.green} Green`)}   ${pc6.yellow(`\u25CF ${byRisk.yellow} Yellow`)}   ${pc6.red(`\u25CF ${byRisk.red} Red`)}${detectOnly > 0 ? pc6.dim(` (${detectOnly} detect-only)`) : ""}`;
+  const detectorLine = [...byDetector.entries()].sort(([, a], [, b]) => b - a).slice(0, DETECTOR_BREAKDOWN_TOP_N).map(([d, b]) => `${d} ${formatBytes3(b)}`).join(" \xB7 ");
   console.log();
   console.log(`  By risk:    ${riskLine}`);
-  console.log(`  By detector: ${pc5.dim(detectorLine)}`);
+  console.log(`  By detector: ${pc6.dim(detectorLine)}`);
   const groups = aggregateForDisplay(allItems);
   const { shown, hidden } = selectTopGroups(groups, COMPACT_TOP_N);
   console.log();
-  console.log(`  ${pc5.bold(`Top ${shown.length} items:`)}`);
+  console.log(`  ${pc6.bold(`Top ${shown.length} items:`)}`);
   for (const g of shown) {
     const path = home ? g.displayPath.replace(home, "~") : g.displayPath;
-    const tag = g.type === "aggregate" ? pc5.dim(` (${g.itemCount} ${g.detector} items)`) : "";
-    const size = g.totalBytes > 0 ? pc5.dim(` ${formatBytes2(g.totalBytes)}`) : "";
+    const tag = g.type === "aggregate" ? pc6.dim(` (${g.itemCount} ${g.detector} items)`) : "";
+    const size = g.totalBytes > 0 ? pc6.dim(` ${formatBytes3(g.totalBytes)}`) : "";
     console.log(`    ${RISK_LABEL[g.risk]}  ${path}${tag}${size}`);
   }
   if (hidden.groupCount > 0) {
     console.log();
     console.log(
-      pc5.dim(
-        `  \u2026 ${hidden.groupCount} more groups (${hidden.itemCount} items, ${formatBytes2(hidden.totalBytes)}) \u2014 use --all to see everything`
+      pc6.dim(
+        `  \u2026 ${hidden.groupCount} more groups (${hidden.itemCount} items, ${formatBytes3(hidden.totalBytes)}) \u2014 use --all to see everything`
       )
     );
   }
@@ -779,66 +858,138 @@ function renderFull(allItems) {
     byProject.set(key, group);
   }
   for (const [projectRoot, items] of byProject.entries()) {
-    const projectLabel = projectRoot === "(global)" ? pc5.dim("global caches") : pc5.cyan(home ? projectRoot.replace(home, "~") : projectRoot);
+    const projectLabel = projectRoot === "(global)" ? pc6.dim("global caches") : pc6.cyan(home ? projectRoot.replace(home, "~") : projectRoot);
     const groupTotal = items.reduce((s, i) => s + i.sizeBytes, 0);
     console.log(`
-  ${projectLabel}  ${pc5.dim(formatBytes2(groupTotal))}`);
+  ${projectLabel}  ${pc6.dim(formatBytes3(groupTotal))}`);
     for (const item of items) {
-      const size = item.sizeBytes > 0 ? pc5.dim(` ${formatBytes2(item.sizeBytes)}`) : "";
+      const size = item.sizeBytes > 0 ? pc6.dim(` ${formatBytes3(item.sizeBytes)}`) : "";
       const displayPath = home ? item.path.replace(home, "~") : item.path;
       const shortPath = projectRoot !== "(global)" ? displayPath.replace(home ? projectRoot.replace(home, "~") : projectRoot, "").replace(/^\//, "") || displayPath : displayPath;
       console.log(`    ${RISK_LABEL[item.risk]}  ${shortPath}${size}`);
-      console.log(`    ${pc5.dim(`       ${item.description}`)}`);
+      console.log(`    ${pc6.dim(`       ${item.description}`)}`);
     }
   }
 }
 
 // src/commands/undo.ts
-import { platform as platform2 } from "os";
-import * as p6 from "@clack/prompts";
-import pc6 from "picocolors";
-function trashPath() {
-  switch (platform2()) {
-    case "darwin":
-      return "~/.Trash";
-    case "win32":
-      return "Recycle Bin";
-    default:
-      return "~/.local/share/Trash";
-  }
+import * as p7 from "@clack/prompts";
+import { OpLog as OpLog3, restoreFromTrash } from "@lexmanh/shed-core";
+import pc7 from "picocolors";
+function formatBytes4(bytes) {
+  if (bytes === 0) return "0 B";
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+  return `${(bytes / 1024 / 1024 / 1024).toFixed(2)} GB`;
 }
-function trashOpenHint() {
-  switch (platform2()) {
-    case "darwin":
-      return "open ~/.Trash  (or click Trash in Dock \u2192 right-click \u2192 Put Back)";
-    case "win32":
-      return "Open Recycle Bin on desktop \u2192 right-click item \u2192 Restore";
-    default:
-      return "nautilus trash:///  or  gio trash --list / gio trash --restore";
+async function undoCommand(token, options = {}) {
+  p7.intro(pc7.bgMagenta(pc7.black(" shed undo ")));
+  const oplog = new OpLog3();
+  let targets;
+  if (token) {
+    const found = await oplog.findByToken(token);
+    if (!found) {
+      p7.cancel(`No operation found with token: ${token}`);
+      return;
+    }
+    targets = [found];
+  } else if (options.last) {
+    const recent = await oplog.read({ limit: 1 });
+    if (recent.length === 0) {
+      p7.cancel("No operations recorded yet.");
+      return;
+    }
+    targets = [...recent];
+  } else if (options.session) {
+    targets = [...await oplog.read({ session: options.session })];
+    if (targets.length === 0) {
+      p7.cancel(`No operations found for session: ${options.session}`);
+      return;
+    }
+  } else {
+    targets = await pickInteractively(oplog);
+    if (targets.length === 0) return;
+  }
+  const restorable = targets.filter((t) => t.action === "trash" && !t.reverted);
+  const skipped = targets.length - restorable.length;
+  if (restorable.length === 0) {
+    if (skipped > 0) {
+      p7.cancel(
+        `Nothing to restore. ${skipped} op(s) were either hard-deleted or already reverted.`
+      );
+    } else {
+      p7.cancel("Nothing to restore.");
+    }
+    return;
+  }
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+  let restored = 0;
+  let failed = 0;
+  for (const op of restorable) {
+    const display = home ? op.path.replace(home, "~") : op.path;
+    const result = await restoreFromTrash(op.path);
+    if (result.ok) {
+      await oplog.markReverted(op.token);
+      console.log(
+        `  ${pc7.green("\u2713")} restored ${pc7.bold(display)} ${pc7.dim(formatBytes4(op.sizeBytes))}`
+      );
+      restored++;
+    } else {
+      console.log(`  ${pc7.red("\u2717")} ${display}: ${pc7.dim(result.message)}`);
+      failed++;
+    }
+  }
+  console.log();
+  if (failed === 0) {
+    p7.outro(pc7.green(`Restored ${restored} item(s).`));
+  } else if (restored === 0) {
+    p7.outro(pc7.red(`Failed to restore any of ${failed} item(s).`));
+  } else {
+    p7.outro(`Restored ${restored} of ${restored + failed} item(s).`);
   }
 }
-async function undoCommand() {
-  p6.intro(pc6.bgMagenta(pc6.black(" shed undo ")));
-  p6.note(
-    [
-      "shed clean moves items to your OS Trash by default.",
-      "",
-      `  Trash location: ${pc6.cyan(trashPath())}`,
-      "",
-      `  To restore: ${pc6.dim(trashOpenHint())}`,
-      "",
-      pc6.dim("Tip: shed clean --hard-delete bypasses Trash (no undo possible)."),
-      pc6.dim("     shed clean --dry-run to preview before any real deletion.")
-    ].join("\n"),
-    "How to undo a cleanup"
-  );
-  p6.outro(pc6.green("Nothing to do \u2014 restore items via your OS Trash."));
+async function pickInteractively(oplog) {
+  const recent = await oplog.read({ limit: 20 });
+  const restorable = recent.filter((e) => e.action === "trash" && !e.reverted);
+  if (restorable.length === 0) {
+    p7.note(
+      [
+        "No restorable operations in your oplog.",
+        "",
+        `Run ${pc7.cyan("shed history")} to see all recorded operations,`,
+        `or ${pc7.cyan("shed clean --execute")} to perform a real cleanup.`,
+        "",
+        pc7.dim("Note: hard-deletes (--hard-delete) cannot be undone.")
+      ].join("\n"),
+      "Nothing to undo"
+    );
+    p7.outro(pc7.dim("Empty."));
+    return [];
+  }
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+  const choice = await p7.select({
+    message: "Pick an operation to restore:",
+    options: restorable.map((e) => {
+      const display = home ? e.path.replace(home, "~") : e.path;
+      const tokenShort = e.token.slice(-8);
+      return {
+        value: e.token,
+        label: `${pc7.bold(tokenShort)}  ${display}  ${pc7.dim(formatBytes4(e.sizeBytes))}`
+      };
+    })
+  });
+  if (p7.isCancel(choice) || typeof choice !== "string") {
+    p7.cancel("Cancelled.");
+    return [];
+  }
+  const picked = restorable.find((e) => e.token === choice);
+  return picked ? [picked] : [];
 }
 
 // src/commands/upgrade.ts
-import * as p7 from "@clack/prompts";
+import * as p8 from "@clack/prompts";
 import { execa as execa2 } from "execa";
-import pc7 from "picocolors";
+import pc8 from "picocolors";
 
 // src/update/detect-install.ts
 import { realpathSync } from "fs";
@@ -846,32 +997,32 @@ import { constants, access } from "fs/promises";
 import { dirname as dirname2 } from "path";
 var PACKAGE_NAME = "@lexmanh/shed-cli";
 function classifyInstall(resolvedPath) {
-  const p8 = resolvedPath.replace(/\\/g, "/").toLowerCase();
-  if (p8.includes("/_npx/") || p8.includes("/npx-cache/")) {
+  const p9 = resolvedPath.replace(/\\/g, "/").toLowerCase();
+  if (p9.includes("/_npx/") || p9.includes("/npx-cache/")) {
     return {
       kind: "npx",
       note: "Running via npx (ephemeral). Re-run with `npx @lexmanh/shed-cli@latest`."
     };
   }
-  if (p8.includes("/bun/install/cache/") || p8.includes("/.bun/install/cache/")) {
+  if (p9.includes("/bun/install/cache/") || p9.includes("/.bun/install/cache/")) {
     return {
       kind: "bunx",
       note: "Running via bunx (ephemeral). Re-run with `bunx @lexmanh/shed-cli@latest`."
     };
   }
-  if (p8.includes("/.volta/") || p8.includes("/volta/tools/")) {
+  if (p9.includes("/.volta/") || p9.includes("/volta/tools/")) {
     return { kind: "volta" };
   }
-  if (p8.includes("/pnpm/global/") || p8.includes("/library/pnpm/") || p8.includes("/.local/share/pnpm/")) {
+  if (p9.includes("/pnpm/global/") || p9.includes("/library/pnpm/") || p9.includes("/.local/share/pnpm/")) {
     return { kind: "pnpm-global" };
   }
-  if (p8.includes("/yarn/global/") || p8.includes("/.config/yarn/global/")) {
+  if (p9.includes("/yarn/global/") || p9.includes("/.config/yarn/global/")) {
     return { kind: "yarn-global" };
   }
-  if (p8.includes("/.bun/install/global/")) {
+  if (p9.includes("/.bun/install/global/")) {
     return { kind: "bun-global" };
   }
-  if (p8.includes("/node_modules/")) {
+  if (p9.includes("/node_modules/")) {
     return { kind: "npm-global" };
   }
   return { kind: "unknown" };
@@ -901,12 +1052,12 @@ function detectInstall(binPath) {
   } catch {
     resolvedPath = binPath;
   }
-  const { kind, note: note8 } = classifyInstall(resolvedPath);
+  const { kind, note: note9 } = classifyInstall(resolvedPath);
   return {
     kind,
     upgradeCommand: buildUpgradeCommand(kind),
     resolvedPath,
-    note: note8
+    note: note9
   };
 }
 async function needsElevation(resolvedPath) {
@@ -997,93 +1148,93 @@ function isNewer(latest, current) {
 
 // src/commands/upgrade.ts
 async function upgradeCommand(opts, currentVersion) {
-  p7.intro(pc7.bgMagenta(pc7.black(" shed upgrade ")));
+  p8.intro(pc8.bgMagenta(pc8.black(" shed upgrade ")));
   const install = detectInstall(process.argv[1] ?? "");
-  const spin = p7.spinner();
+  const spin = p8.spinner();
   spin.start("Checking npm registry\u2026");
   const latest = await fetchLatestVersion({ force: true });
   spin.stop(latest ? `Latest: v${latest}` : "Could not reach registry");
   if (!latest) {
-    p7.outro(pc7.yellow("No upgrade information available. Check your network and try again."));
+    p8.outro(pc8.yellow("No upgrade information available. Check your network and try again."));
     process.exit(1);
   }
   if (!isNewer(latest, currentVersion)) {
-    p7.note(
-      `Installed:  ${pc7.cyan(`v${currentVersion}`)}
-Latest:     ${pc7.cyan(`v${latest}`)}`,
+    p8.note(
+      `Installed:  ${pc8.cyan(`v${currentVersion}`)}
+Latest:     ${pc8.cyan(`v${latest}`)}`,
       "Already up to date"
     );
-    p7.outro(pc7.green("Nothing to do."));
+    p8.outro(pc8.green("Nothing to do."));
     return;
   }
-  p7.note(
+  p8.note(
     [
-      `Installed:  ${pc7.dim(`v${currentVersion}`)}`,
-      `Latest:     ${pc7.green(`v${latest}`)}`,
-      `Source:     ${pc7.cyan(install.kind)}`,
-      `Path:       ${pc7.dim(install.resolvedPath)}`
+      `Installed:  ${pc8.dim(`v${currentVersion}`)}`,
+      `Latest:     ${pc8.green(`v${latest}`)}`,
+      `Source:     ${pc8.cyan(install.kind)}`,
+      `Path:       ${pc8.dim(install.resolvedPath)}`
     ].join("\n"),
     "Upgrade available"
   );
   if (!install.upgradeCommand) {
-    p7.note(
+    p8.note(
       install.note ?? "Could not detect how shed was installed.",
-      pc7.yellow("Cannot self-upgrade")
+      pc8.yellow("Cannot self-upgrade")
     );
-    p7.outro(pc7.dim("Re-install manually using your preferred package manager."));
+    p8.outro(pc8.dim("Re-install manually using your preferred package manager."));
     return;
   }
   const elevate = await needsElevation(install.resolvedPath);
   const finalCommand = elevate ? `sudo ${install.upgradeCommand}` : install.upgradeCommand;
   if (opts.check) {
-    p7.note(finalCommand, "Run this to upgrade");
-    p7.outro(pc7.dim("(--check mode: nothing executed)"));
+    p8.note(finalCommand, "Run this to upgrade");
+    p8.outro(pc8.dim("(--check mode: nothing executed)"));
     return;
   }
   if (elevate) {
-    p7.note(finalCommand, pc7.yellow("Install dir is not writable \u2014 run this manually"));
-    p7.outro(pc7.dim("Re-run `shed upgrade` after the install completes to verify."));
+    p8.note(finalCommand, pc8.yellow("Install dir is not writable \u2014 run this manually"));
+    p8.outro(pc8.dim("Re-run `shed upgrade` after the install completes to verify."));
     return;
   }
   if (!opts.yes) {
-    const ok = await p7.confirm({ message: `Run \`${finalCommand}\` now?`, initialValue: true });
-    if (p7.isCancel(ok) || !ok) {
-      p7.cancel("Upgrade cancelled.");
+    const ok = await p8.confirm({ message: `Run \`${finalCommand}\` now?`, initialValue: true });
+    if (p8.isCancel(ok) || !ok) {
+      p8.cancel("Upgrade cancelled.");
       return;
     }
   }
-  const runSpin = p7.spinner();
+  const runSpin = p8.spinner();
   runSpin.start(`Running ${finalCommand}\u2026`);
   try {
     const [bin, ...args] = finalCommand.split(" ");
     if (!bin) throw new Error("Empty upgrade command");
     await execa2(bin, args, { stdio: "pipe" });
-    runSpin.stop(pc7.green(`Upgraded to v${latest}.`));
-    p7.outro(pc7.green("Done. Re-run `shed --version` to confirm."));
+    runSpin.stop(pc8.green(`Upgraded to v${latest}.`));
+    p8.outro(pc8.green("Done. Re-run `shed --version` to confirm."));
   } catch (err) {
-    runSpin.stop(pc7.red("Upgrade failed."));
+    runSpin.stop(pc8.red("Upgrade failed."));
     const message = err instanceof Error ? err.message : String(err);
-    p7.note(message, pc7.red("Error"));
-    p7.outro(pc7.dim(`You can retry manually: ${finalCommand}`));
+    p8.note(message, pc8.red("Error"));
+    p8.outro(pc8.dim(`You can retry manually: ${finalCommand}`));
     process.exit(1);
   }
 }
 
 // src/update/notifier.ts
-import pc8 from "picocolors";
+import pc9 from "picocolors";
 function maybeNotifyOfUpdate(currentVersion) {
   const cached = readCachedLatest();
   if (!cached || !isNewer(cached, currentVersion)) return;
   const install = detectInstall(process.argv[1] ?? "");
   const cmd = install.upgradeCommand ?? "shed upgrade";
   const banner = [
-    pc8.yellow("\u25B2"),
-    pc8.dim(`shed v${currentVersion} \u2192`),
-    pc8.green(`v${cached}`),
-    pc8.dim("available."),
-    pc8.dim("Run"),
-    pc8.cyan("`shed upgrade`"),
-    pc8.dim(`(or \`${cmd}\`).`)
+    pc9.yellow("\u25B2"),
+    pc9.dim(`shed v${currentVersion} \u2192`),
+    pc9.green(`v${cached}`),
+    pc9.dim("available."),
+    pc9.dim("Run"),
+    pc9.cyan("`shed upgrade`"),
+    pc9.dim(`(or \`${cmd}\`).`)
   ].join(" ");
   console.log(banner);
 }
@@ -1094,7 +1245,7 @@ function scheduleBackgroundRefresh() {
 }
 
 // src/logo.ts
-import pc9 from "picocolors";
+import pc10 from "picocolors";
 var CABIN = ["       \u2571\u2572    ", "      \u2571\u2500\u2500\u2572   ", "     \u2571\u2500\u2500\u2500\u2500\u2572  ", "     \u2502 \u2588\u2588 \u2502  ", "     \u2514\u2500\u2500\u2500\u2500\u2518  "];
 var WORDMARK = [
   "  ____  _              _ ",
@@ -1105,11 +1256,11 @@ var WORDMARK = [
 ];
 function printLogo(version2) {
   for (let i = 0; i < CABIN.length; i++) {
-    console.log(pc9.yellow(CABIN[i]) + pc9.cyan(WORDMARK[i]));
+    console.log(pc10.yellow(CABIN[i]) + pc10.cyan(WORDMARK[i]));
   }
-  console.log(`  ${pc9.dim(`v${version2} \xB7 safe disk cleanup \xB7 dev machines & servers`)}`);
+  console.log(`  ${pc10.dim(`v${version2} \xB7 safe disk cleanup \xB7 dev machines & servers`)}`);
   console.log(
-    `  ${pc9.dim("by")} ${pc9.white("L\xEA Xu\xE2n M\u1EA1nh")} ${pc9.dim("\xB7 https://github.com/lexmanh/shed")}
+    `  ${pc10.dim("by")} ${pc10.white("L\xEA Xu\xE2n M\u1EA1nh")} ${pc10.dim("\xB7 https://github.com/lexmanh/shed")}
 `
   );
 }
@@ -1121,7 +1272,8 @@ var program = new Command();
 program.name("shed").description("Safe disk cleanup for dev machines and Linux servers").version(version).option("-v, --verbose", "Enable verbose logging");
 program.command("scan [path]").description("Scan for cleanable items without modifying anything").option("--json", "Output machine-readable JSON").option("--max-age <days>", "Only include items older than N days", "30").option("--all", "Show every item (default: compact summary with top 15)").action(scanCommand);
 program.command("clean [path]").description("Interactive cleanup of detected items").option("--dry-run", "Preview operations without executing", true).option("--execute", "Actually perform the cleanup (overrides --dry-run)").option("--hard-delete", "Skip Trash, delete permanently").option("--include-red", "Include Red-tier (high-risk) items").option("--yes", "Skip interactive confirmations (CI mode)").action(cleanCommand);
-program.command("undo").description("List and restore items from previous cleanups").action(undoCommand);
+program.command("undo [token]").description("Restore a previously cleaned item from Trash").option("--last", "Restore the most recent operation").option("--session <id>", "Restore every operation from a session").action(undoCommand);
+program.command("history").description("List recent cleanup operations from the oplog").option("--limit <n>", "Show at most N entries", "20").option("--session <id>", "Filter to a single session ULID").option("--json", "Output machine-readable JSON").action(historyCommand);
 program.command("doctor").description("Check environment and configuration").action(doctorCommand);
 program.command("config").description("Manage user preferences").argument("[action]", "get | set | list | reset").argument("[key]", "Configuration key").argument("[value]", "Configuration value (for set)").action(configCommand);
 program.command("completions").description("Print shell completion script").argument("<shell>", "bash | zsh | fish").action(completionsCommand);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexmanh/shed-cli",
-  "version": "0.3.0-beta.2",
+  "version": "0.4.0-beta.1",
   "description": "Safe disk cleanup CLI for dev machines and Linux servers — git-aware, cross-stack, trash-by-default",
   "type": "module",
   "bin": {
@@ -23,7 +23,7 @@
     "conf": "^13.1.0",
     "execa": "^9.5.0",
     "picocolors": "^1.1.1",
-    "@lexmanh/shed-core": "0.3.0-beta.2"
+    "@lexmanh/shed-core": "0.4.0-beta.1"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",