envoic 0.0.1 → 0.0.10

package/README.md

@@ -0,0 +1,13 @@
+<img src="https://raw.githubusercontent.com/mahimailabs/envoic/main/assets/envoic.png" width="1000" alt="envoic logo" />
+
+Discover and manage `node modules` and JavaScript artifacts.
+
+```bash
+npx envoic scan ~/projects
+```
+
+For full documentation, see the [main repository](https://github.com/mahimailabs/envoic).
+
+Also available for Python: `uvx envoic scan .`
+
+> Development note: local JS development (`npm ci`, `npm run lint`, `npm run build`) requires Node `>=20.19.0`.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.js

@@ -0,0 +1,841 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { createRequire } from "module";
+import { Command } from "commander";
+
+// src/cli.ts
+import fs6 from "fs";
+import path7 from "path";
+
+// src/detector.ts
+import fs from "fs";
+import path from "path";
+function detectPackageManager(nodeModulesPath) {
+  const parent = path.dirname(nodeModulesPath);
+  if (fs.existsSync(path.join(parent, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs.existsSync(path.join(parent, "yarn.lock"))) return "yarn";
+  if (fs.existsSync(path.join(parent, "bun.lockb")) || fs.existsSync(path.join(parent, "bun.lock"))) return "bun";
+  if (fs.existsSync(path.join(parent, "package-lock.json"))) return "npm";
+  if (fs.existsSync(path.join(nodeModulesPath, ".modules.yaml"))) return "pnpm";
+  if (fs.existsSync(path.join(nodeModulesPath, ".yarn-integrity"))) return "yarn";
+  if (fs.existsSync(path.join(nodeModulesPath, ".package-lock.json"))) return "npm";
+  return "unknown";
+}
+function countTopLevelPackages(nodeModulesPath) {
+  let count = 0;
+  let entries;
+  try {
+    entries = fs.readdirSync(nodeModulesPath, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith(".")) continue;
+    if (entry.name.startsWith("@")) {
+      const scopedPath = path.join(nodeModulesPath, entry.name);
+      let scoped;
+      try {
+        scoped = fs.readdirSync(scopedPath, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      count += scoped.filter((item) => item.isDirectory()).length;
+    } else {
+      count += 1;
+    }
+  }
+  return count;
+}
+function pathSizeBytes(targetPath) {
+  let stat;
+  try {
+    stat = fs.lstatSync(targetPath);
+  } catch {
+    return 0;
+  }
+  if (stat.isSymbolicLink()) return stat.size;
+  if (stat.isFile()) return stat.size;
+  if (!stat.isDirectory()) return 0;
+  let total = 0;
+  const stack = [targetPath];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const next = path.join(current, entry.name);
+      try {
+        const itemStat = fs.lstatSync(next);
+        if (itemStat.isSymbolicLink()) {
+          total += itemStat.size;
+        } else if (itemStat.isFile()) {
+          total += itemStat.size;
+        } else if (itemStat.isDirectory()) {
+          stack.push(next);
+        }
+      } catch {
+        continue;
+      }
+    }
+  }
+  return total;
+}
+function detectEnvironment(nodeModulesPath, staleDays, deep) {
+  const parent = path.dirname(nodeModulesPath);
+  const signals = [];
+  const hasNpmMarker = fs.existsSync(path.join(nodeModulesPath, ".package-lock.json"));
+  const hasYarnMarker = fs.existsSync(path.join(nodeModulesPath, ".yarn-integrity"));
+  const hasPnpmMarker = fs.existsSync(path.join(nodeModulesPath, ".modules.yaml"));
+  const hasPackageJson = fs.existsSync(path.join(parent, "package.json"));
+  if (hasNpmMarker) signals.push("npm-marker");
+  if (hasYarnMarker) signals.push("yarn-marker");
+  if (hasPnpmMarker) signals.push("pnpm-marker");
+  if (hasPackageJson) signals.push("package.json");
+  let stat;
+  try {
+    stat = fs.statSync(nodeModulesPath);
+  } catch {
+    return {
+      path: nodeModulesPath,
+      packageManager: detectPackageManager(nodeModulesPath),
+      packageCount: deep ? countTopLevelPackages(nodeModulesPath) : null,
+      sizeBytes: deep ? pathSizeBytes(nodeModulesPath) : null,
+      created: null,
+      modified: null,
+      isStale: false,
+      isOutdated: false,
+      signals: [...signals, "stat-unavailable"]
+    };
+  }
+  const created = stat.birthtime ?? null;
+  const modified = stat.mtime ?? null;
+  const staleThreshold = Date.now() - staleDays * 864e5;
+  const isStale = modified.getTime() < staleThreshold;
+  let isOutdated = false;
+  const packageJsonPath = path.join(parent, "package.json");
+  if (fs.existsSync(packageJsonPath)) {
+    const pkgStat = fs.statSync(packageJsonPath);
+    isOutdated = pkgStat.mtime.getTime() > modified.getTime();
+  }
+  return {
+    path: nodeModulesPath,
+    packageManager: detectPackageManager(nodeModulesPath),
+    packageCount: deep ? countTopLevelPackages(nodeModulesPath) : null,
+    sizeBytes: deep ? pathSizeBytes(nodeModulesPath) : null,
+    created,
+    modified,
+    isStale,
+    isOutdated,
+    signals
+  };
+}
+function installHint(packageManager) {
+  if (packageManager === "pnpm") return "pnpm install";
+  if (packageManager === "yarn") return "yarn install";
+  if (packageManager === "bun") return "bun install";
+  return "npm install";
+}
+
+// src/manager.ts
+import fs2 from "fs";
+import path3 from "path";
+import { stdin as input, stdout as output } from "process";
+import readline from "readline/promises";
+import { checkbox } from "@inquirer/prompts";
+
+// src/utils.ts
+import os from "os";
+import path2 from "path";
+var VENV_NAMES = /* @__PURE__ */ new Set(["node_modules"]);
+function formatSize(numBytes) {
+  if (numBytes === null) return "-";
+  if (numBytes < 1024) return `${numBytes}B`;
+  const units = ["K", "M", "G", "T"];
+  let value = numBytes;
+  for (const unit of units) {
+    value /= 1024;
+    if (value < 1024 || unit === units[units.length - 1]) {
+      if (value >= 100) return `${value.toFixed(0)}${unit}`;
+      return `${value.toFixed(1).replace(/\.0$/, "")}${unit}`;
+    }
+  }
+  return `${numBytes}B`;
+}
+function formatAge(moment, now = /* @__PURE__ */ new Date()) {
+  if (!moment) return "-";
+  const days = Math.max(0, Math.floor((now.getTime() - moment.getTime()) / 864e5));
+  if (days < 30) return `${days}d`;
+  if (days < 365) return `${Math.floor(days / 30)}mo`;
+  return `${Math.floor(days / 365)}y`;
+}
+function barChart(value, maxValue, width = 24) {
+  if (maxValue <= 0) return `[${"\u2591".repeat(width)}]`;
+  const filled = Math.max(0, Math.min(width, Math.round(value / maxValue * width)));
+  return `[${"\u2588".repeat(filled)}${"\u2591".repeat(width - filled)}]`;
+}
+function boxLine(text, width = 58) {
+  const clipped = text.slice(0, width);
+  return `\u2502${clipped.padEnd(width, " ")}\u2502`;
+}
+function shortenPath(inputPath, maxLen = 36) {
+  let text = inputPath;
+  const home = os.homedir();
+  if (text.startsWith(home)) text = `~${text.slice(home.length)}`;
+  if (text.length <= maxLen) return text;
+  const keep = maxLen - 3;
+  const prefix = Math.floor(keep / 2);
+  const suffix = keep - prefix;
+  return `${text.slice(0, prefix)}...${text.slice(-suffix)}`;
+}
+function normalizeDisplayPath(targetPath, scanRoot) {
+  try {
+    const rel = path2.relative(scanRoot, targetPath);
+    const normalized = rel === "" ? "." : rel;
+    const base = path2.basename(normalized);
+    if (VENV_NAMES.has(base)) {
+      const parent = path2.dirname(normalized);
+      return parent === "." ? "." : parent;
+    }
+    return normalized;
+  } catch {
+    return targetPath;
+  }
+}
+function toSerializable(value) {
+  return JSON.parse(
+    JSON.stringify(
+      value,
+      (_key, val) => val instanceof Date ? val.toISOString() : val
+    )
+  );
+}
+
+// src/manager.ts
+function insideRoot(candidate, scanRoot) {
+  const abs = path3.resolve(candidate);
+  const root = path3.resolve(scanRoot);
+  return abs === root || abs.startsWith(`${root}${path3.sep}`);
+}
+function sizeForDelete(target) {
+  try {
+    const st = fs2.lstatSync(target);
+    if (st.isSymbolicLink() || st.isFile()) return st.size;
+  } catch {
+    return 0;
+  }
+  let total = 0;
+  const stack = [target];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let entries;
+    try {
+      entries = fs2.readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const next = path3.join(current, entry.name);
+      try {
+        const st = fs2.lstatSync(next);
+        if (st.isSymbolicLink() || st.isFile()) total += st.size;
+        else if (st.isDirectory()) stack.push(next);
+      } catch {
+        continue;
+      }
+    }
+  }
+  return total;
+}
+function envLabel(env, scanRoot) {
+  const stale = env.isStale ? " STALE" : "";
+  const outdated = env.isOutdated ? " OUTDATED" : "";
+  return `${normalizeDisplayPath(env.path, scanRoot).padEnd(45, " ")} ${String(env.packageManager).padEnd(8, " ")} ${formatSize(env.sizeBytes).padStart(6, " ")}  ${formatAge(env.modified).padStart(5, " ")}${stale}${outdated}`;
+}
+async function fallbackSelect(environments, scanRoot, staleOnly) {
+  console.log("Found environments. Enter numbers to delete (comma-separated):");
+  environments.forEach((env, i) => {
+    const marker = staleOnly && env.isStale ? "x" : " ";
+    console.log(`${String(i + 1).padStart(3, " ")} [${marker}] ${envLabel(env, scanRoot)}`);
+  });
+  const rl = readline.createInterface({ input, output });
+  const raw = await rl.question("Select [e.g. 1,3,5]: ");
+  rl.close();
+  const selected = /* @__PURE__ */ new Set();
+  for (const token of raw.split(",").map((s) => s.trim())) {
+    if (!/^\d+$/.test(token)) continue;
+    const idx = Number(token);
+    if (idx >= 1 && idx <= environments.length) selected.add(idx - 1);
+  }
+  return [...selected].sort((a, b) => a - b).map((idx) => environments[idx]);
+}
+async function interactiveSelect(environments, scanRoot, staleOnly) {
+  if (environments.length === 0) return [];
+  if (process.stdin.isTTY && process.stdout.isTTY) {
+    try {
+      const choices = environments.map((env, index) => ({
+        name: envLabel(env, scanRoot),
+        value: index,
+        checked: staleOnly && env.isStale
+      }));
+      const selected = await checkbox({
+        message: "Select environments to delete",
+        choices,
+        instructions: "Use \u2191\u2193 to move, Space to toggle, Enter to confirm"
+      });
+      return selected.map((idx) => environments[idx]);
+    } catch {
+    }
+  }
+  return fallbackSelect(environments, scanRoot, staleOnly);
+}
+async function confirmDeletion(selected, scanRoot, dryRun, skipConfirm) {
+  console.log("\n\u26A0 The following items will be PERMANENTLY DELETED:\n");
+  let total = 0;
+  selected.forEach((item, idx) => {
+    const size = item.sizeBytes ?? 0;
+    total += size;
+    const p = normalizeDisplayPath(item.path, scanRoot);
+    console.log(`  ${String(idx + 1).padEnd(3, " ")} ${p.padEnd(42, " ")} ${formatSize(size).padStart(6, " ")}`);
+  });
+  console.log(`
+  Total: ${formatSize(total)} will be freed`);
+  if (dryRun) {
+    console.log("\nDRY RUN \u2014 no files will be deleted.");
+    return false;
+  }
+  if (skipConfirm) return true;
+  const rl = readline.createInterface({ input, output });
+  const typed = await rl.question('Type "delete" to confirm: ');
+  rl.close();
+  return typed.trim() === "delete";
+}
+function deleteSelected(selected, scanRoot, dryRun, dryRunEcho = true) {
+  const summary = {
+    selectedCount: selected.length,
+    deletedCount: 0,
+    failedCount: 0,
+    skippedCount: 0,
+    bytesFreed: 0,
+    wouldFreeBytes: 0,
+    errors: [],
+    dryRun
+  };
+  for (const item of selected) {
+    const target = item.path;
+    if (!insideRoot(target, scanRoot)) {
+      summary.skippedCount += 1;
+      summary.errors.push(`outside scan root: ${target}`);
+      continue;
+    }
+    const size = sizeForDelete(target);
+    summary.wouldFreeBytes += size;
+    if (dryRun) {
+      if (dryRunEcho) console.log(`[dry-run] Would delete ${normalizeDisplayPath(target, scanRoot)}`);
+      continue;
+    }
+    let targetStat;
+    try {
+      targetStat = fs2.lstatSync(target);
+    } catch {
+      summary.skippedCount += 1;
+      continue;
+    }
+    process.stdout.write(`Deleting ${normalizeDisplayPath(target, scanRoot)} ...`);
+    try {
+      if (targetStat.isSymbolicLink()) fs2.unlinkSync(target);
+      else fs2.rmSync(target, { recursive: true, force: false });
+      summary.deletedCount += 1;
+      summary.bytesFreed += size;
+      console.log(" done");
+    } catch (error) {
+      const code = error.code;
+      if (code === "EPERM" || code === "EACCES") {
+        console.log(" failed (permission denied)");
+      } else {
+        console.log(" failed");
+      }
+      summary.failedCount += 1;
+      summary.errors.push(String(error));
+    }
+  }
+  return summary;
+}
+function printDeletionReport(summary, initialTotal, items = []) {
+  const hasEnvs = items.some((i) => "packageManager" in i);
+  const label = hasEnvs ? "environment(s)" : items.length > 0 ? "artifact(s)" : "item(s)";
+  const remaining = Math.max(0, initialTotal - summary.deletedCount);
+  const freed = summary.dryRun ? summary.wouldFreeBytes : summary.bytesFreed;
+  console.log("\u2500".repeat(58));
+  if (summary.dryRun) console.log("  DRY RUN SUMMARY");
+  console.log(`  Deleted:   ${summary.deletedCount} ${label}`);
+  console.log(`  Failed:    ${summary.failedCount}`);
+  console.log(`  Skipped:   ${summary.skippedCount}`);
+  console.log(`  Freed:     ${formatSize(freed)}`);
+  console.log(`  Remaining: ${remaining} ${label}`);
+  console.log("\u2500".repeat(58));
+}
+
+// src/report.ts
+import fs4 from "fs";
+import path5 from "path";
+
+// src/artifacts.ts
+import fs3 from "fs";
+import path4 from "path";
+var ARTIFACT_PATTERNS = [
+  { name: ".next", type: "dir", category: "build_cache", safety: "always_safe" },
+  { name: ".nuxt", type: "dir", category: "build_cache", safety: "always_safe" },
+  { name: ".turbo", type: "dir", category: "build_cache", safety: "always_safe" },
+  { name: ".parcel-cache", type: "dir", category: "build_cache", safety: "always_safe" },
+  { name: ".webpack", type: "dir", category: "build_cache", safety: "always_safe" },
+  { name: ".swc", type: "dir", category: "build_cache", safety: "always_safe" },
+  { name: ".output", type: "dir", category: "build_cache", safety: "always_safe" },
+  { name: "storybook-static", type: "dir", category: "build_cache", safety: "always_safe" },
+  { name: "dist", type: "dir", category: "build_output", safety: "usually_safe", requiresParentPackageJson: true },
+  { name: "build", type: "dir", category: "build_output", safety: "usually_safe", requiresParentPackageJson: true },
+  { name: ".eslintcache", type: "file", category: "tool_cache", safety: "always_safe" },
+  { name: ".stylelintcache", type: "file", category: "tool_cache", safety: "always_safe" },
+  { name: "tsconfig.tsbuildinfo", type: "file", category: "tool_cache", safety: "always_safe" },
+  { name: ".cache", type: "dir", category: "tool_cache", safety: "always_safe" },
+  { name: "coverage", type: "dir", category: "test_output", safety: "always_safe" },
+  { name: ".nyc_output", type: "dir", category: "test_output", safety: "always_safe" }
+];
+var SAFETY_TEXT = {
+  always_safe: "safe to delete",
+  usually_safe: "usually safe",
+  careful: "careful"
+};
+function isJsProjectDir(parentPath) {
+  return fs3.existsSync(path4.join(parentPath, "package.json"));
+}
+function artifactPatternName(pattern) {
+  if (pattern.name) return pattern.name;
+  return `*${pattern.suffix}`;
+}
+function matchArtifact(entry, parentPath, fullPath) {
+  for (const pattern of ARTIFACT_PATTERNS) {
+    if (!pattern.name && !pattern.suffix) continue;
+    if (pattern.type === "dir" && !entry.isDirectory()) continue;
+    if (pattern.type === "file" && !entry.isFile()) continue;
+    if (pattern.name && entry.name !== pattern.name) continue;
+    if (pattern.suffix && !entry.name.endsWith(pattern.suffix)) continue;
+    if (pattern.requiresParentPackageJson && !isJsProjectDir(parentPath)) continue;
+    return {
+      path: fullPath,
+      category: pattern.category,
+      safety: pattern.safety,
+      sizeBytes: null,
+      patternMatched: artifactPatternName(pattern)
+    };
+  }
+  return null;
+}
+function summarizeArtifacts(artifacts) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const item of artifacts) {
+    const key = `${item.patternMatched}:${item.category}:${item.safety}`;
+    const existing = grouped.get(key);
+    if (!existing) {
+      grouped.set(key, {
+        pattern: item.patternMatched,
+        category: item.category,
+        safety: item.safety,
+        count: 1,
+        totalSizeBytes: item.sizeBytes ?? 0,
+        items: [item]
+      });
+    } else {
+      existing.count += 1;
+      existing.totalSizeBytes += item.sizeBytes ?? 0;
+      existing.items.push(item);
+    }
+  }
+  return [...grouped.values()].sort((a, b) => a.pattern.localeCompare(b.pattern));
+}
+
+// src/report.ts
+var WIDTH = 58;
+function boxTop(width = WIDTH) {
+  return `\u250C${"\u2500".repeat(width)}\u2510`;
+}
+function boxMid(width = WIDTH) {
+  return `\u251C${"\u2500".repeat(width)}\u2524`;
+}
+function boxBottom(width = WIDTH) {
+  return `\u2514${"\u2500".repeat(width)}\u2518`;
+}
+function row(label, value, width = WIDTH) {
+  const left = `  ${label.padEnd(12, " ")}`;
+  const rightWidth = Math.max(0, width - left.length - 2);
+  const clipped = value.slice(0, rightWidth);
+  return boxLine(`${left}${clipped.padStart(rightWidth, " ")}  `, width);
+}
+function envHeader() {
+  return `  ${"#".padEnd(3, " ")} ${"Path".padEnd(30, " ")} ${"Pkg Mgr".padEnd(8, " ")} ${"Size".padStart(6, " ")} ${"Age".padStart(5, " ")}`;
+}
+function envRow(index, env, scanRoot) {
+  const label = normalizeDisplayPath(env.path, scanRoot);
+  const stale = env.isStale ? " STALE" : "";
+  const outdated = env.isOutdated ? " OUTDATED" : "";
+  return `  ${String(index).padEnd(3, " ")} ${shortenPath(label, 30).padEnd(30, " ")} ${env.packageManager.padEnd(8, " ")} ${formatSize(env.sizeBytes).padStart(6, " ")} ${formatAge(env.modified).padStart(5, " ")}${stale}${outdated}`;
+}
+function formatReport(result, deep = false) {
+  const staleCount = result.environments.filter((item) => item.isStale).length;
+  const outdatedCount = result.environments.filter((item) => item.isOutdated).length;
+  const artifactCount = result.artifactSummary.reduce((acc, item) => acc + item.count, 0);
+  const artifactSize = result.artifactSummary.reduce((acc, item) => acc + item.totalSizeBytes, 0);
+  const lines = [];
+  lines.push(boxTop());
+  lines.push(boxLine("  ENVOIC - JavaScript Environment Report"));
+  lines.push(boxLine("  TR-200  Environment Scanner"));
+  lines.push(boxMid());
+  lines.push(row("Date", result.timestamp.toISOString().replace("T", " ").slice(0, 19)));
+  lines.push(row("Host", result.hostname));
+  lines.push(row("Scan Path", shortenPath(result.scanPath, 36)));
+  lines.push(row("Scan Depth", String(result.scanDepth)));
+  lines.push(row("Duration", `${result.durationSeconds.toFixed(2)}s`));
+  lines.push(boxMid());
+  lines.push(row("NM Found", String(result.environments.length)));
+  lines.push(row("Total Size", formatSize(result.totalSizeBytes)));
+  lines.push(row("Stale", `>${result.staleDays}d: ${staleCount}`));
+  lines.push(row("Outdated", String(outdatedCount)));
+  lines.push(row("Artifacts", String(artifactCount)));
+  lines.push(row("Art Size", deep ? formatSize(artifactSize) : "-"));
+  lines.push(boxBottom());
+  lines.push("");
+  lines.push("NODE MODULES");
+  lines.push("\u2500".repeat(58));
+  lines.push(envHeader());
+  lines.push("\u2500".repeat(58));
+  if (result.environments.length === 0) {
+    lines.push("  (no node_modules found)");
+  } else {
+    result.environments.forEach((env, i) => lines.push(envRow(i + 1, env, result.scanPath)));
+  }
+  lines.push("\u2500".repeat(58));
+  lines.push("");
+  lines.push("ARTIFACTS");
+  lines.push("\u2500".repeat(58));
+  lines.push(`  ${"Category".padEnd(22, " ")} ${"Count".padStart(6, " ")} ${"Size".padStart(8, " ")} ${"Safety".padStart(16, " ")}`);
+  lines.push("\u2500".repeat(58));
+  for (const item of result.artifactSummary) {
+    lines.push(`  ${item.pattern.padEnd(22, " ")} ${String(item.count).padStart(6, " ")} ${formatSize(item.totalSizeBytes).padStart(8, " ")} ${SAFETY_TEXT[item.safety].padStart(16, " ")}`);
+  }
+  if (result.artifactSummary.length === 0) lines.push("  (no artifacts found)");
+  lines.push("\u2500".repeat(58));
+  if (deep) {
+    lines.push("");
+    lines.push("SIZE DISTRIBUTION");
+    const sized = result.environments.filter((item) => item.sizeBytes !== null);
+    const maxSize = sized.reduce((acc, item) => Math.max(acc, item.sizeBytes ?? 0), 0);
+    for (const env of sized) {
+      const size = env.sizeBytes ?? 0;
+      const label = normalizeDisplayPath(env.path, result.scanPath);
+      lines.push(`  ${barChart(size, maxSize, 24)} ${shortenPath(label, 24).padEnd(24, " ")} ${formatSize(size).padStart(6, " ")}`);
+    }
+  }
+  return lines.join("\n");
+}
+function formatList(environments, scanRoot) {
+  const lines = [envHeader(), "\u2500".repeat(58)];
+  environments.forEach((env, i) => lines.push(envRow(i + 1, env, scanRoot)));
+  if (environments.length === 0) lines.push("  (no node_modules found)");
+  return lines.join("\n");
+}
+function formatInfo(env, topPackages, reinstallHint) {
+  const lines = [];
+  lines.push(boxTop());
+  lines.push(boxLine("  ENVOIC - Node Modules Detail"));
+  lines.push(boxMid());
+  lines.push(row("Path", env.path));
+  lines.push(row("Manager", env.packageManager));
+  lines.push(row("Packages", String(env.packageCount ?? "-")));
+  lines.push(row("Size", formatSize(env.sizeBytes)));
+  lines.push(row("Modified", env.modified ? env.modified.toISOString().replace("T", " ").slice(0, 19) : "-"));
+  lines.push(row("Stale", env.isStale ? "yes" : "no"));
+  lines.push(row("Outdated", env.isOutdated ? "yes" : "no"));
+  lines.push(row("Reinstall", reinstallHint));
+  lines.push(boxBottom());
+  lines.push("");
+  lines.push("TOP PACKAGES");
+  lines.push("\u2500".repeat(58));
+  if (topPackages.length === 0) {
+    lines.push("  (no packages found)");
+  } else {
+    topPackages.forEach((item, idx) => {
+      lines.push(`  ${String(idx + 1).padStart(2, " ")}. ${item.name} (${formatSize(item.size)})`);
+    });
+  }
+  lines.push("\u2500".repeat(58));
+  return lines.join("\n");
+}
+function topLargestPackages(nodeModulesPath, limit = 10) {
+  const resolvedPath = path5.resolve(nodeModulesPath);
+  const result = [];
+  let direct;
+  try {
+    direct = fs4.readdirSync(resolvedPath, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  for (const entry of direct) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith(".")) continue;
+    if (entry.name.startsWith("@")) {
+      const scopePath = path5.join(resolvedPath, entry.name);
+      let scopedEntries;
+      try {
+        scopedEntries = fs4.readdirSync(scopePath, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const scoped of scopedEntries) {
+        if (!scoped.isDirectory()) continue;
+        if (scoped.name.startsWith(".")) continue;
+        const full2 = path5.join(scopePath, scoped.name);
+        const size2 = measureDirSize(full2);
+        result.push({ name: `${entry.name}/${scoped.name}`, size: size2 });
+      }
+      continue;
+    }
+    const full = path5.join(resolvedPath, entry.name);
+    const size = measureDirSize(full);
+    result.push({ name: entry.name, size });
+  }
+  return result.sort((a, b) => b.size - a.size).slice(0, limit);
+}
+function measureDirSize(dirPath) {
+  let size = 0;
+  const stack = [dirPath];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let children;
+    try {
+      children = fs4.readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const child of children) {
+      const childPath = path5.join(current, child.name);
+      try {
+        const st = fs4.lstatSync(childPath);
+        if (st.isSymbolicLink() || st.isFile()) size += st.size;
+        else if (st.isDirectory()) stack.push(childPath);
+      } catch {
+        continue;
+      }
+    }
+  }
+  return size;
+}
+
+// src/scanner.ts
+import fs5 from "fs";
+import os2 from "os";
+import path6 from "path";
+var SKIP_NAMES = /* @__PURE__ */ new Set([".git", ".hg", ".svn"]);
+var ALLOWED_HIDDEN = /* @__PURE__ */ new Set([".next", ".nuxt", ".turbo", ".swc", ".output", ".cache", ".parcel-cache", ".webpack"]);
+function dirSizeBytes(targetPath) {
+  let total = 0;
+  const stack = [targetPath];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let entries;
+    try {
+      entries = fs5.readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const next = path6.join(current, entry.name);
+      try {
+        const st = fs5.lstatSync(next);
+        if (st.isSymbolicLink() || st.isFile()) total += st.size;
+        else if (st.isDirectory()) stack.push(next);
+      } catch {
+        continue;
+      }
+    }
+  }
+  return total;
+}
+function scan(options) {
+  const scanPath = path6.resolve(options.root);
+  const start = performance.now();
+  const environments = [];
+  const artifacts = [];
+  const seenEnv = /* @__PURE__ */ new Set();
+  const seenArtifact = /* @__PURE__ */ new Set();
+  function walk(current, depth) {
+    if (depth > options.depth) return;
+    let entries;
+    try {
+      entries = fs5.readdirSync(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const next = path6.join(current, entry.name);
+      if (options.includeArtifacts) {
+        const artifact = matchArtifact(entry, current, path6.resolve(next));
+        if (artifact) {
+          if (!seenArtifact.has(artifact.path)) {
+            if (options.deep) {
+              artifact.sizeBytes = entry.isFile() ? fs5.statSync(path6.resolve(next)).size : dirSizeBytes(artifact.path);
+            }
+            artifacts.push(artifact);
+            seenArtifact.add(artifact.path);
+          }
+          if (entry.isDirectory()) continue;
+        }
+      }
+      if (!entry.isDirectory()) continue;
+      if (entry.name === "node_modules") {
+        const abs = path6.resolve(next);
+        if (!seenEnv.has(abs)) {
+          environments.push(detectEnvironment(abs, options.staleDays, options.deep));
+          seenEnv.add(abs);
+        }
+        continue;
+      }
+      if (SKIP_NAMES.has(entry.name)) continue;
+      if (entry.name.startsWith(".") && !ALLOWED_HIDDEN.has(entry.name)) continue;
+      walk(next, depth + 1);
+    }
+  }
+  walk(scanPath, 1);
+  const durationSeconds = (performance.now() - start) / 1e3;
+  const totalSizeBytes = environments.reduce((acc, item) => acc + (item.sizeBytes ?? 0), 0);
+  const artifactSummary = summarizeArtifacts(artifacts);
+  return {
+    scanPath,
+    scanDepth: options.depth,
+    staleDays: options.staleDays,
+    durationSeconds,
+    environments: environments.sort((a, b) => a.path.localeCompare(b.path)),
+    totalSizeBytes,
+    hostname: os2.hostname(),
+    timestamp: /* @__PURE__ */ new Date(),
+    artifacts: artifacts.sort((a, b) => a.path.localeCompare(b.path)),
+    artifactSummary
+  };
+}
+
+// src/cli.ts
+function parseIntOption(value) {
+  const n = Number.parseInt(value, 10);
+  if (!Number.isFinite(n) || n < 1) throw new Error("must be a positive integer");
+  return n;
+}
+async function confirmAndDelete(selected, scanRoot, initialTotal, dryRun, yes) {
+  const confirmed = await confirmDeletion(selected, scanRoot, dryRun, yes);
+  if (dryRun) {
+    const summary2 = deleteSelected(selected, scanRoot, true, false);
+    printDeletionReport(summary2, initialTotal, selected);
+    return;
+  }
+  if (!confirmed) {
+    console.log("Deletion cancelled.");
+    return;
+  }
+  const summary = deleteSelected(selected, scanRoot, false);
+  printDeletionReport(summary, initialTotal, selected);
+}
+function registerCommands(program2) {
+  program2.command("scan").argument("[path]", "path to scan", ".").option("-d, --depth <n>", "max directory depth", parseIntOption, 5).option("--deep", "compute size and package metadata", false).option("--json", "output JSON report", false).option("--stale-days <n>", "mark stale after N days", parseIntOption, 90).option("--no-artifacts", "disable JS artifact detection").action((targetPath, options) => {
+    const result = scan({
+      root: targetPath,
+      depth: options.depth,
+      deep: options.deep,
+      staleDays: options.staleDays,
+      includeArtifacts: options.artifacts
+    });
+    if (options.json) {
+      console.log(JSON.stringify(toSerializable(result), null, 2));
+      return;
+    }
+    console.log(formatReport(result, options.deep));
+  });
+  program2.command("list").argument("[path]", "path to scan", ".").option("-d, --depth <n>", "max directory depth", parseIntOption, 5).option("--deep", "compute size metadata", false).option("--stale-days <n>", "mark stale after N days", parseIntOption, 90).action((targetPath, options) => {
+    const result = scan({
+      root: targetPath,
+      depth: options.depth,
+      deep: options.deep,
+      staleDays: options.staleDays,
+      includeArtifacts: false
+    });
+    console.log(formatList(result.environments, result.scanPath));
+  });
+  program2.command("info").argument("<nodeModulesPath>", "path to node_modules directory").action((targetPath) => {
+    const abs = path7.resolve(targetPath);
+    if (path7.basename(abs) !== "node_modules" || !fs6.existsSync(abs)) {
+      console.error(`Not a recognized node_modules path: ${targetPath}`);
+      process.exitCode = 1;
+      return;
+    }
+    const scanRoot = path7.dirname(abs);
+    const result = scan({
+      root: scanRoot,
+      depth: 2,
+      deep: true,
+      staleDays: 90,
+      includeArtifacts: false
+    });
+    const env = result.environments.find((item) => path7.resolve(item.path) === abs);
+    if (!env) {
+      console.error(`Could not inspect environment: ${targetPath}`);
+      process.exitCode = 1;
+      return;
+    }
+    const topPackages = topLargestPackages(abs, 10);
+    console.log(formatInfo(env, topPackages, installHint(env.packageManager)));
+  });
+  program2.command("manage").argument("[path]", "path to scan", ".").option("-d, --depth <n>", "max directory depth", parseIntOption, 5).option("--stale-only", "pre-select stale environments", false).option("--stale-days <n>", "stale threshold in days", parseIntOption, 90).option("--dry-run", "preview without deleting", false).option("-y, --yes", "skip final confirmation", false).option("--deep", "compute size metadata", false).action(async (targetPath, options) => {
+    const result = scan({
+      root: targetPath,
+      depth: options.depth,
+      deep: options.deep,
+      staleDays: options.staleDays,
+      includeArtifacts: false
+    });
+    if (result.environments.length === 0) {
+      console.log("No environments found.");
+      return;
+    }
+    const selected = await interactiveSelect(result.environments, result.scanPath, options.staleOnly);
+    if (selected.length === 0) {
+      console.log("Nothing selected.");
+      return;
+    }
+    await confirmAndDelete(selected, result.scanPath, result.environments.length, options.dryRun, options.yes);
+  });
+  program2.command("clean").argument("[path]", "path to scan", ".").option("-d, --depth <n>", "max directory depth", parseIntOption, 5).option("--stale-days <n>", "stale threshold in days", parseIntOption, 90).option("--dry-run", "preview without deleting", false).option("-y, --yes", "skip final confirmation", false).option("--deep", "compute size metadata", true).action(async (targetPath, options) => {
+    const result = scan({
+      root: targetPath,
+      depth: options.depth,
+      deep: options.deep,
+      staleDays: options.staleDays,
+      includeArtifacts: false
+    });
+    const selected = result.environments.filter((item) => item.isStale);
+    if (selected.length === 0) {
+      console.log("No stale environments found.");
+      return;
+    }
+    await confirmAndDelete(selected, result.scanPath, result.environments.length, options.dryRun, options.yes);
+  });
+}
+
+// src/index.ts
+var require2 = createRequire(import.meta.url);
+var { version } = require2("../package.json");
+var program = new Command();
+program.name("envoic").description("Discover and manage node_modules and JS artifacts").version(version);
+registerCommands(program);
+program.parse();

package/package.json

@@ -1,12 +1,51 @@
 {
   "name": "envoic",
-  "version": "0.0.1",
-  "description": "",
-  "main": "index.js",
+  "version": "0.0.10",
+  "description": "Discover and manage node modules and JS artifacts on your system",
+  "type": "module",
+  "bin": {
+    "envoic": "./dist/index.js"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest",
+    "prepublishOnly": "npm run build",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix"
   },
-  "keywords": [],
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "node_modules",
+    "cleanup",
+    "disk",
+    "scanner",
+    "cli",
+    "devtools"
+  ],
   "author": "Mahimai",
-  "license": "MIT"
-}
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mahimailabs/envoic",
+    "directory": "packages/js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.10.1",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.19.11",
+    "eslint": "^10.0.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "8.56.0",
+    "vitest": "^2.1.9"
+  }
+}

package/index.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-console.log("envoic: coming soon. https://github.com/mahimailabs/envoic");