@lexmanh/shed-cli 0.2.0-beta.1 → 0.2.0-beta.10

package/dist/cli.js

@@ -1,25 +1,17 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { createRequire } from "module";
+import { createRequire as createRequire2 } from "module";
 import { Command } from "commander";
 
 // src/commands/clean.ts
 import { resolve } from "path";
 import * as p from "@clack/prompts";
 import {
-  AndroidDetector,
-  CocoaPodsDetector,
-  DockerDetector,
-  FlutterDetector,
-  IdeDetector,
-  NodeDetector,
-  PythonDetector,
   RiskTier,
-  RustDetector,
   SafetyChecker,
   Scanner,
-  XcodeDetector
+  defaultDetectors
 } from "@lexmanh/shed-core";
 import pc from "picocolors";
 
@@ -58,20 +50,10 @@ async function cleanCommand(path = ".", options = {}) {
       "Safe mode"
     );
   }
-  const spinner3 = p.spinner();
+  const spinner4 = p.spinner();
   verbose(`clean root: ${rootDir}, dryRun=${isDryRun}, hardDelete=${options.hardDelete ?? false}`);
-  spinner3.start(`Scanning ${rootDir} \u2026`);
-  const scanner = new Scanner([
-    new NodeDetector(),
-    new PythonDetector(),
-    new RustDetector(),
-    new DockerDetector(),
-    new XcodeDetector(),
-    new FlutterDetector(),
-    new AndroidDetector(),
-    new CocoaPodsDetector(),
-    new IdeDetector()
-  ]);
+  spinner4.start(`Scanning ${rootDir} \u2026`);
+  const scanner = new Scanner(defaultDetectors());
   const ctx = { scanRoot: rootDir, maxDepth: 8 };
   const [projects, globalItems] = await Promise.all([
     scanner.scan(rootDir),
@@ -82,7 +64,7 @@ async function cleanCommand(path = ".", options = {}) {
     ...globalItems
   ].filter((i) => options.includeRed || i.risk !== RiskTier.Red);
   verbose(`scan complete: ${allItems.length} cleanable items`);
-  spinner3.stop(`Found ${pc.bold(String(allItems.length))} cleanable items.`);
+  spinner4.stop(`Found ${pc.bold(String(allItems.length))} cleanable items.`);
   if (allItems.length === 0) {
     p.outro(pc.dim("Nothing to clean."));
     return;
@@ -139,10 +121,11 @@ async function cleanCommand(path = ".", options = {}) {
             label: `${pc.yellow("Yellow only")}  ${pc.dim(`${yellowItems.length} items \xB7 ${formatBytes(yellowBytes)}`)}`
           }
         ] : [],
-        { value: "custom", label: "Custom  (pick individual items)" }
+        { value: "custom", label: "Custom  (pick individual items)" },
+        { value: "cancel", label: pc.dim("Cancel  (do nothing, exit)") }
       ]
     });
-    if (p.isCancel(preset)) {
+    if (p.isCancel(preset) || preset === "cancel") {
       p.cancel("Cleanup cancelled.");
       return;
     }
@@ -226,8 +209,124 @@ async function cleanCommand(path = ".", options = {}) {
     }
   }
   console.log();
-  const outro6 = isDryRun ? `Dry-run complete. Run with ${pc.cyan("--execute")} to perform actual cleanup.` : result.failed.length > 0 ? `Completed with ${result.failed.length} failure(s).` : "All done!";
-  p.outro(outro6);
+  const outro7 = isDryRun ? `Dry-run complete. Run with ${pc.cyan("--execute")} to perform actual cleanup.` : result.failed.length > 0 ? `Completed with ${result.failed.length} failure(s).` : "All done!";
+  p.outro(outro7);
+}
+
+// src/commands/completions.ts
+var BASH = `# shed bash completion
+_shed_completions() {
+  local cur prev cmds
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  cmds="scan clean undo doctor config completions"
+
+  case "\${prev}" in
+    scan)
+      COMPREPLY=( $(compgen -W "--json --max-age --all" -- "\${cur}") )
+      return 0
+      ;;
+    clean)
+      COMPREPLY=( $(compgen -W "--dry-run --execute --hard-delete --include-red --yes" -- "\${cur}") )
+      return 0
+      ;;
+    config)
+      COMPREPLY=( $(compgen -W "get set list reset" -- "\${cur}") )
+      return 0
+      ;;
+    completions)
+      COMPREPLY=( $(compgen -W "bash zsh fish" -- "\${cur}") )
+      return 0
+      ;;
+  esac
+
+  if [ "\${COMP_CWORD}" -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "\${cmds} --version --help --verbose" -- "\${cur}") )
+    return 0
+  fi
+}
+complete -F _shed_completions shed
+`;
+var ZSH = `#compdef shed
+# shed zsh completion
+
+_shed() {
+  local -a commands
+  commands=(
+    'scan:Scan for cleanable items without modifying anything'
+    'clean:Interactive cleanup of detected items'
+    'undo:List and restore items from previous cleanups'
+    'doctor:Check environment and configuration'
+    'config:Manage user preferences'
+    'completions:Print shell completion script (bash | zsh | fish)'
+  )
+
+  if (( CURRENT == 2 )); then
+    _describe -t commands 'shed command' commands
+    return
+  fi
+
+  case "\${words[2]}" in
+    scan)
+      _arguments \\
+        '--json[Output machine-readable JSON]' \\
+        '--max-age[Only include items older than N days]:days' \\
+        '--all[Show every item (default: compact summary)]'
+      ;;
+    clean)
+      _arguments \\
+        '--dry-run[Preview operations without executing]' \\
+        '--execute[Actually perform the cleanup]' \\
+        '--hard-delete[Skip Trash, delete permanently]' \\
+        '--include-red[Include Red-tier (high-risk) items]' \\
+        '--yes[Skip interactive confirmations (CI mode)]'
+      ;;
+    config)
+      _values 'config action' get set list reset
+      ;;
+    completions)
+      _values 'shell' bash zsh fish
+      ;;
+  esac
+}
+
+_shed "$@"
+`;
+var FISH = `# shed fish completion
+complete -c shed -f
+
+# subcommands
+complete -c shed -n '__fish_use_subcommand' -a 'scan' -d 'Scan for cleanable items'
+complete -c shed -n '__fish_use_subcommand' -a 'clean' -d 'Interactive cleanup'
+complete -c shed -n '__fish_use_subcommand' -a 'undo' -d 'Restore from previous cleanups'
+complete -c shed -n '__fish_use_subcommand' -a 'doctor' -d 'Check environment'
+complete -c shed -n '__fish_use_subcommand' -a 'config' -d 'Manage preferences'
+complete -c shed -n '__fish_use_subcommand' -a 'completions' -d 'Print shell completion script'
+
+# scan flags
+complete -c shed -n '__fish_seen_subcommand_from scan' -l json -d 'Output JSON'
+complete -c shed -n '__fish_seen_subcommand_from scan' -l max-age -d 'Min age in days'
+complete -c shed -n '__fish_seen_subcommand_from scan' -l all -d 'Show every item'
+
+# clean flags
+complete -c shed -n '__fish_seen_subcommand_from clean' -l dry-run -d 'Preview only'
+complete -c shed -n '__fish_seen_subcommand_from clean' -l execute -d 'Actually delete'
+complete -c shed -n '__fish_seen_subcommand_from clean' -l hard-delete -d 'Skip Trash'
+complete -c shed -n '__fish_seen_subcommand_from clean' -l include-red -d 'Include Red tier'
+complete -c shed -n '__fish_seen_subcommand_from clean' -l yes -d 'Skip confirmations'
+
+# config + completions argument values
+complete -c shed -n '__fish_seen_subcommand_from config' -a 'get set list reset'
+complete -c shed -n '__fish_seen_subcommand_from completions' -a 'bash zsh fish'
+`;
+var SCRIPTS = { bash: BASH, zsh: ZSH, fish: FISH };
+function completionsCommand(shell) {
+  if (shell !== "bash" && shell !== "zsh" && shell !== "fish") {
+    console.error("shed completions: shell must be one of: bash, zsh, fish");
+    process.exit(1);
+  }
+  process.stdout.write(SCRIPTS[shell]);
 }
 
 // src/commands/config.ts
@@ -395,30 +494,92 @@ async function doctorCommand() {
 }
 
 // src/commands/scan.ts
+import { createRequire } from "module";
+import { hostname } from "os";
 import { resolve as resolve2 } from "path";
 import * as p4 from "@clack/prompts";
 import {
-  AndroidDetector as AndroidDetector2,
-  CocoaPodsDetector as CocoaPodsDetector2,
-  DatabaseDetector,
-  DockerDetector as DockerDetector2,
-  DotnetDetector,
-  FlutterDetector as FlutterDetector2,
-  GoDetector,
-  IdeDetector as IdeDetector2,
-  JavaGradleDetector,
-  JavaMavenDetector,
-  NodeDetector as NodeDetector2,
-  PythonDetector as PythonDetector2,
   RiskTier as RiskTier2,
-  RubyDetector,
-  RustDetector as RustDetector2,
   Scanner as Scanner2,
-  SystemDetector,
-  WebserverDetector,
-  XcodeDetector as XcodeDetector2
+  defaultDetectors as defaultDetectors2
 } from "@lexmanh/shed-core";
 import pc4 from "picocolors";
+
+// src/commands/scan-aggregate.ts
+import { dirname } from "path";
+var AGGREGATE_THRESHOLD = 3;
+function aggregateForDisplay(items) {
+  const buckets = /* @__PURE__ */ new Map();
+  const singles = [];
+  for (const item of items) {
+    const kind = item.metadata?.kind ?? null;
+    if (!kind) {
+      singles.push(item);
+      continue;
+    }
+    const key = `${dirname(item.path)}::${item.detector}::${kind}`;
+    const arr = buckets.get(key) ?? [];
+    arr.push(item);
+    buckets.set(key, arr);
+  }
+  const result = [];
+  for (const arr of buckets.values()) {
+    if (arr.length >= AGGREGATE_THRESHOLD) {
+      const first = arr[0];
+      if (!first) continue;
+      const totalBytes = arr.reduce((s, i) => s + i.sizeBytes, 0);
+      const kind = first.metadata?.kind;
+      const parentDir = dirname(first.path);
+      const displayPath = parentDir === "." ? kind : parentDir;
+      result.push({
+        type: "aggregate",
+        risk: first.risk,
+        displayPath,
+        description: `${arr.length} ${kind} files`,
+        totalBytes,
+        detector: first.detector,
+        itemCount: arr.length,
+        items: arr
+      });
+    } else {
+      for (const item of arr) result.push(toSingle(item));
+    }
+  }
+  for (const item of singles) result.push(toSingle(item));
+  return result;
+}
+function toSingle(item) {
+  return {
+    type: "single",
+    risk: item.risk,
+    displayPath: item.path,
+    description: item.description,
+    totalBytes: item.sizeBytes,
+    detector: item.detector,
+    itemCount: 1,
+    items: [item]
+  };
+}
+function selectTopGroups(groups, topN) {
+  const sorted = [...groups].sort((a, b) => b.totalBytes - a.totalBytes);
+  const shown = sorted.slice(0, topN);
+  const rest = sorted.slice(topN);
+  return {
+    shown,
+    hidden: {
+      groupCount: rest.length,
+      itemCount: rest.reduce((s, g) => s + g.itemCount, 0),
+      totalBytes: rest.reduce((s, g) => s + g.totalBytes, 0)
+    }
+  };
+}
+
+// src/commands/scan.ts
+var require2 = createRequire(import.meta.url);
+var { version: SHED_VERSION } = require2("../package.json");
+var JSON_SCHEMA_VERSION = 1;
+var COMPACT_TOP_N = 15;
+var DETECTOR_BREAKDOWN_TOP_N = 6;
 var RISK_LABEL = {
   [RiskTier2.Green]: pc4.green("\u25CF Green"),
   [RiskTier2.Yellow]: pc4.yellow("\u25CF Yellow"),
@@ -441,28 +602,11 @@ async function scanCommand(path = ".", options = {}) {
   if (!options.json) {
     p4.intro(pc4.bgCyan(pc4.black(" shed scan ")));
   }
-  const spinner3 = options.json ? null : p4.spinner();
+  const spinner4 = options.json ? null : p4.spinner();
   verbose(`scan root: ${rootDir}`);
-  spinner3?.start(`Scanning ${rootDir} \u2026`);
-  const scanner = new Scanner2([
-    new NodeDetector2(),
-    new PythonDetector2(),
-    new RustDetector2(),
-    new GoDetector(),
-    new JavaMavenDetector(),
-    new JavaGradleDetector(),
-    new RubyDetector(),
-    new DotnetDetector(),
-    new DockerDetector2(),
-    new XcodeDetector2(),
-    new FlutterDetector2(),
-    new AndroidDetector2(),
-    new CocoaPodsDetector2(),
-    new IdeDetector2(),
-    new SystemDetector(),
-    new WebserverDetector(),
-    new DatabaseDetector()
-  ]);
+  spinner4?.start(`Scanning ${rootDir} \u2026`);
+  const scanStartedAt = Date.now();
+  const scanner = new Scanner2(defaultDetectors2());
   const ctx = { scanRoot: rootDir, maxDepth: 8 };
   const [projects, globalItems] = await Promise.all([
     scanner.scan(rootDir),
@@ -478,17 +622,45 @@ async function scanCommand(path = ".", options = {}) {
   );
   for (const item of allItems)
     verbose(`  item: ${item.risk} ${item.path} (${item.sizeBytes} bytes)`);
-  spinner3?.stop(
+  spinner4?.stop(
     `Found ${pc4.bold(String(allItems.length))} cleanable items across ${projects.length} project(s).`
   );
   if (options.json) {
+    const byRisk = { green: 0, yellow: 0, red: 0 };
+    let detectOnly = 0;
+    for (const item of allItems) {
+      byRisk[item.risk]++;
+      if (item.metadata?.detectOnly === true) detectOnly++;
+    }
+    const projectsOut = projects.map((proj) => ({
+      root: proj.root,
+      detectors: [...new Set(proj.items.map((i) => i.detector))],
+      itemCount: proj.items.length,
+      totalBytes: proj.items.reduce((s, i) => s + i.sizeBytes, 0)
+    }));
     console.log(
       JSON.stringify(
         {
-          root: rootDir,
-          projects: projects.length,
-          items: allItems,
-          totalBytes
+          schemaVersion: JSON_SCHEMA_VERSION,
+          shedVersion: SHED_VERSION,
+          timestamp: new Date(scanStartedAt).toISOString(),
+          host: {
+            hostname: hostname(),
+            platform: process.platform,
+            arch: process.arch
+          },
+          scan: {
+            root: rootDir,
+            durationMs: Date.now() - scanStartedAt
+          },
+          summary: {
+            totalBytes,
+            totalItems: allItems.length,
+            byRisk,
+            detectOnly
+          },
+          projects: projectsOut,
+          items: allItems
         },
         null,
         2
@@ -501,6 +673,52 @@ async function scanCommand(path = ".", options = {}) {
     p4.outro(pc4.dim("All clear!"));
     return;
   }
+  if (options.all) {
+    renderFull(allItems);
+  } else {
+    renderCompact(allItems);
+  }
+  console.log();
+  p4.outro(
+    `Total recoverable: ${pc4.bold(pc4.green(formatBytes2(totalBytes)))} \u2014 run ${pc4.cyan("shed clean")} to proceed.`
+  );
+}
+function renderCompact(allItems) {
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+  const byRisk = { green: 0, yellow: 0, red: 0 };
+  let detectOnly = 0;
+  const byDetector = /* @__PURE__ */ new Map();
+  for (const item of allItems) {
+    byRisk[item.risk]++;
+    if (item.metadata?.detectOnly === true) detectOnly++;
+    byDetector.set(item.detector, (byDetector.get(item.detector) ?? 0) + item.sizeBytes);
+  }
+  const riskLine = `${pc4.green(`\u25CF ${byRisk.green} Green`)}   ${pc4.yellow(`\u25CF ${byRisk.yellow} Yellow`)}   ${pc4.red(`\u25CF ${byRisk.red} Red`)}${detectOnly > 0 ? pc4.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 ");
+  console.log();
+  console.log(`  By risk:    ${riskLine}`);
+  console.log(`  By detector: ${pc4.dim(detectorLine)}`);
+  const groups = aggregateForDisplay(allItems);
+  const { shown, hidden } = selectTopGroups(groups, COMPACT_TOP_N);
+  console.log();
+  console.log(`  ${pc4.bold(`Top ${shown.length} items:`)}`);
+  for (const g of shown) {
+    const path = home ? g.displayPath.replace(home, "~") : g.displayPath;
+    const tag = g.type === "aggregate" ? pc4.dim(` (${g.itemCount} ${g.detector} items)`) : "";
+    const size = g.totalBytes > 0 ? pc4.dim(` ${formatBytes2(g.totalBytes)}`) : "";
+    console.log(`    ${RISK_LABEL[g.risk]}  ${path}${tag}${size}`);
+  }
+  if (hidden.groupCount > 0) {
+    console.log();
+    console.log(
+      pc4.dim(
+        `  \u2026 ${hidden.groupCount} more groups (${hidden.itemCount} items, ${formatBytes2(hidden.totalBytes)}) \u2014 use --all to see everything`
+      )
+    );
+  }
+}
+function renderFull(allItems) {
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
   const byProject = /* @__PURE__ */ new Map();
   for (const item of allItems) {
     const key = item.projectRoot ?? "(global)";
@@ -509,7 +727,6 @@ async function scanCommand(path = ".", options = {}) {
     byProject.set(key, group);
   }
   for (const [projectRoot, items] of byProject.entries()) {
-    const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
     const projectLabel = projectRoot === "(global)" ? pc4.dim("global caches") : pc4.cyan(home ? projectRoot.replace(home, "~") : projectRoot);
     const groupTotal = items.reduce((s, i) => s + i.sizeBytes, 0);
     console.log(`
@@ -522,10 +739,6 @@ async function scanCommand(path = ".", options = {}) {
       console.log(`    ${pc4.dim(`       ${item.description}`)}`);
     }
   }
-  console.log();
-  p4.outro(
-    `Total recoverable: ${pc4.bold(pc4.green(formatBytes2(totalBytes)))} \u2014 run ${pc4.cyan("shed clean")} to proceed.`
-  );
 }
 
 // src/commands/undo.ts
@@ -570,39 +783,309 @@ async function undoCommand() {
   p5.outro(pc5.green("Nothing to do \u2014 restore items via your OS Trash."));
 }
 
-// src/logo.ts
+// src/commands/upgrade.ts
+import * as p6 from "@clack/prompts";
+import { execa as execa2 } from "execa";
 import pc6 from "picocolors";
-var ART = [
+
+// src/update/detect-install.ts
+import { realpathSync } from "fs";
+import { constants, access } from "fs/promises";
+import { dirname as dirname2 } from "path";
+var PACKAGE_NAME = "@lexmanh/shed-cli";
+function classifyInstall(resolvedPath) {
+  const p7 = resolvedPath.replace(/\\/g, "/").toLowerCase();
+  if (p7.includes("/_npx/") || p7.includes("/npx-cache/")) {
+    return {
+      kind: "npx",
+      note: "Running via npx (ephemeral). Re-run with `npx @lexmanh/shed-cli@latest`."
+    };
+  }
+  if (p7.includes("/bun/install/cache/") || p7.includes("/.bun/install/cache/")) {
+    return {
+      kind: "bunx",
+      note: "Running via bunx (ephemeral). Re-run with `bunx @lexmanh/shed-cli@latest`."
+    };
+  }
+  if (p7.includes("/.volta/") || p7.includes("/volta/tools/")) {
+    return { kind: "volta" };
+  }
+  if (p7.includes("/pnpm/global/") || p7.includes("/library/pnpm/") || p7.includes("/.local/share/pnpm/")) {
+    return { kind: "pnpm-global" };
+  }
+  if (p7.includes("/yarn/global/") || p7.includes("/.config/yarn/global/")) {
+    return { kind: "yarn-global" };
+  }
+  if (p7.includes("/.bun/install/global/")) {
+    return { kind: "bun-global" };
+  }
+  if (p7.includes("/node_modules/")) {
+    return { kind: "npm-global" };
+  }
+  return { kind: "unknown" };
+}
+function buildUpgradeCommand(kind, pkg = PACKAGE_NAME) {
+  switch (kind) {
+    case "npm-global":
+      return `npm i -g ${pkg}@latest`;
+    case "pnpm-global":
+      return `pnpm add -g ${pkg}@latest`;
+    case "yarn-global":
+      return `yarn global add ${pkg}@latest`;
+    case "bun-global":
+      return `bun add -g ${pkg}@latest`;
+    case "volta":
+      return `volta install ${pkg}@latest`;
+    case "npx":
+    case "bunx":
+    case "unknown":
+      return null;
+  }
+}
+function detectInstall(binPath) {
+  let resolvedPath;
+  try {
+    resolvedPath = realpathSync(binPath);
+  } catch {
+    resolvedPath = binPath;
+  }
+  const { kind, note: note7 } = classifyInstall(resolvedPath);
+  return {
+    kind,
+    upgradeCommand: buildUpgradeCommand(kind),
+    resolvedPath,
+    note: note7
+  };
+}
+async function needsElevation(resolvedPath) {
+  if (process.platform === "win32") return false;
+  try {
+    await access(dirname2(resolvedPath), constants.W_OK);
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+// src/update/registry.ts
+import Conf2 from "conf";
+var REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+var CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
+var DEFAULT_TIMEOUT_MS = 3e3;
+function getCache() {
+  return new Conf2({ projectName: "shed", configName: "update-cache" });
+}
+function readCachedLatest() {
+  const last = getCache().get("lastCheck");
+  if (!last) return null;
+  if (Date.now() - last.checkedAt >= CACHE_TTL_MS) return null;
+  return last.version;
+}
+async function fetchLatestVersion(opts = {}) {
+  if (!opts.force) {
+    const cached = readCachedLatest();
+    if (cached) return cached;
+  }
+  try {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    const res = await fetch(REGISTRY_URL, {
+      signal: ctrl.signal,
+      headers: { Accept: "application/json" }
+    });
+    clearTimeout(t);
+    if (!res.ok) return null;
+    const json = await res.json();
+    if (!json.version) return null;
+    getCache().set("lastCheck", { version: json.version, checkedAt: Date.now() });
+    return json.version;
+  } catch {
+    return null;
+  }
+}
+function compareSemver(a, b) {
+  const [aMain, aPre = ""] = a.split("-");
+  const [bMain, bPre = ""] = b.split("-");
+  const aParts = (aMain ?? "").split(".").map((n2) => Number(n2) || 0);
+  const bParts = (bMain ?? "").split(".").map((n2) => Number(n2) || 0);
+  for (let i = 0; i < 3; i++) {
+    const x = aParts[i] ?? 0;
+    const y = bParts[i] ?? 0;
+    if (x !== y) return x - y;
+  }
+  if (aPre === "" && bPre === "") return 0;
+  if (aPre === "") return 1;
+  if (bPre === "") return -1;
+  const aP = aPre.split(".");
+  const bP = bPre.split(".");
+  const n = Math.max(aP.length, bP.length);
+  for (let i = 0; i < n; i++) {
+    const x = aP[i];
+    const y = bP[i];
+    if (x === void 0) return -1;
+    if (y === void 0) return 1;
+    const xIsNum = /^\d+$/.test(x);
+    const yIsNum = /^\d+$/.test(y);
+    if (xIsNum && yIsNum) {
+      const diff = Number(x) - Number(y);
+      if (diff !== 0) return diff;
+    } else if (xIsNum) {
+      return -1;
+    } else if (yIsNum) {
+      return 1;
+    } else if (x !== y) {
+      return x > y ? 1 : -1;
+    }
+  }
+  return 0;
+}
+function isNewer(latest, current) {
+  return compareSemver(latest, current) > 0;
+}
+
+// src/commands/upgrade.ts
+async function upgradeCommand(opts, currentVersion) {
+  p6.intro(pc6.bgMagenta(pc6.black(" shed upgrade ")));
+  const install = detectInstall(process.argv[1] ?? "");
+  const spin = p6.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) {
+    p6.outro(pc6.yellow("No upgrade information available. Check your network and try again."));
+    process.exit(1);
+  }
+  if (!isNewer(latest, currentVersion)) {
+    p6.note(
+      `Installed:  ${pc6.cyan(`v${currentVersion}`)}
+Latest:     ${pc6.cyan(`v${latest}`)}`,
+      "Already up to date"
+    );
+    p6.outro(pc6.green("Nothing to do."));
+    return;
+  }
+  p6.note(
+    [
+      `Installed:  ${pc6.dim(`v${currentVersion}`)}`,
+      `Latest:     ${pc6.green(`v${latest}`)}`,
+      `Source:     ${pc6.cyan(install.kind)}`,
+      `Path:       ${pc6.dim(install.resolvedPath)}`
+    ].join("\n"),
+    "Upgrade available"
+  );
+  if (!install.upgradeCommand) {
+    p6.note(
+      install.note ?? "Could not detect how shed was installed.",
+      pc6.yellow("Cannot self-upgrade")
+    );
+    p6.outro(pc6.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) {
+    p6.note(finalCommand, "Run this to upgrade");
+    p6.outro(pc6.dim("(--check mode: nothing executed)"));
+    return;
+  }
+  if (elevate) {
+    p6.note(finalCommand, pc6.yellow("Install dir is not writable \u2014 run this manually"));
+    p6.outro(pc6.dim("Re-run `shed upgrade` after the install completes to verify."));
+    return;
+  }
+  if (!opts.yes) {
+    const ok = await p6.confirm({ message: `Run \`${finalCommand}\` now?`, initialValue: true });
+    if (p6.isCancel(ok) || !ok) {
+      p6.cancel("Upgrade cancelled.");
+      return;
+    }
+  }
+  const runSpin = p6.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(pc6.green(`Upgraded to v${latest}.`));
+    p6.outro(pc6.green("Done. Re-run `shed --version` to confirm."));
+  } catch (err) {
+    runSpin.stop(pc6.red("Upgrade failed."));
+    const message = err instanceof Error ? err.message : String(err);
+    p6.note(message, pc6.red("Error"));
+    p6.outro(pc6.dim(`You can retry manually: ${finalCommand}`));
+    process.exit(1);
+  }
+}
+
+// src/update/notifier.ts
+import pc7 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 = [
+    pc7.yellow("\u25B2"),
+    pc7.dim(`shed v${currentVersion} \u2192`),
+    pc7.green(`v${cached}`),
+    pc7.dim("available."),
+    pc7.dim("Run"),
+    pc7.cyan("`shed upgrade`"),
+    pc7.dim(`(or \`${cmd}\`).`)
+  ].join(" ");
+  console.log(banner);
+}
+function scheduleBackgroundRefresh() {
+  if (readCachedLatest() !== null) return;
+  void fetchLatestVersion({ force: false, timeoutMs: 1500 }).catch(() => {
+  });
+}
+
+// src/logo.ts
+import pc8 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 = [
   "  ____  _              _ ",
   " / ___|| |__   ___  __| |",
   " \\___ \\| '_ \\ / _ \\/ _` |",
   "  ___) | | | |  __/ (_| |",
   " |____/|_| |_|\\___|\\__,_|"
-].join("\n");
+];
 function printLogo(version2) {
-  console.log(pc6.cyan(ART));
-  console.log(`  ${pc6.dim(`v${version2} \xB7 safe disk cleanup for developers`)}`);
+  for (let i = 0; i < CABIN.length; i++) {
+    console.log(pc8.yellow(CABIN[i]) + pc8.cyan(WORDMARK[i]));
+  }
+  console.log(`  ${pc8.dim(`v${version2} \xB7 safe disk cleanup \xB7 dev machines & servers`)}`);
   console.log(
-    `  ${pc6.dim("by")} ${pc6.white("L\xEA Xu\xE2n M\u1EA1nh")} ${pc6.dim("\xB7 https://github.com/lexmanh/shed")}
+    `  ${pc8.dim("by")} ${pc8.white("L\xEA Xu\xE2n M\u1EA1nh")} ${pc8.dim("\xB7 https://github.com/lexmanh/shed")}
 `
   );
 }
 
 // src/cli.ts
-var require2 = createRequire(import.meta.url);
-var { version } = require2("../package.json");
+var require3 = createRequire2(import.meta.url);
+var { version } = require3("../package.json");
 var program = new Command();
-program.name("shed").description("Safe, cross-platform disk cleanup for developers").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").action(scanCommand);
+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("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);
+program.command("upgrade").alias("update").description("Check for and install the latest version of shed").option("--check", "Only check; print the upgrade command without running it").option("--yes", "Skip the confirmation prompt").action((opts) => upgradeCommand(opts, version));
 program.hook("preAction", (_thisCommand, actionCommand) => {
   const opts = program.opts();
   setVerbose(opts.verbose ?? false);
   const cmdOpts = actionCommand.opts();
-  if (!cmdOpts.json) printLogo(version);
+  const cmdName = actionCommand.name();
+  const isCompletions = cmdName === "completions";
+  const isUpgrade = cmdName === "upgrade";
+  if (!cmdOpts.json && !isCompletions) printLogo(version);
+  if (!cmdOpts.json && !isCompletions && !isUpgrade) {
+    maybeNotifyOfUpdate(version);
+    scheduleBackgroundRefresh();
+  }
 });
 program.parseAsync(process.argv).catch((err) => {
   console.error("shed: fatal error:", err instanceof Error ? err.message : err);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lexmanh/shed-cli",
-  "version": "0.2.0-beta.1",
-  "description": "Safe, cross-platform disk cleanup CLI for developers — reclaim space from dev caches without breaking active work",
+  "version": "0.2.0-beta.10",
+  "description": "Safe disk cleanup CLI for dev machines and Linux servers — git-aware, cross-stack, trash-by-default",
   "type": "module",
   "bin": {
     "shed": "./dist/cli.js"
@@ -10,6 +10,10 @@
     "dist",
     "package.json"
   ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lexmanh/shed.git"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -19,7 +23,7 @@
     "conf": "^13.1.0",
     "execa": "^9.5.0",
     "picocolors": "^1.1.1",
-    "@lexmanh/shed-core": "0.2.0-beta.1"
+    "@lexmanh/shed-core": "0.2.0-beta.10"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",