z-clean 0.1.1 → 0.3.1

package/src/detector/whitelist.js

@@ -1,8 +1,7 @@
 'use strict';
 
-const { execSync } = require('child_process');
-const os = require('os');
 const fs = require('fs');
+const os = require('os');
 
 const platform = os.platform();
 
@@ -12,16 +11,14 @@ const DAEMON_MANAGERS = ['pm2', 'forever', 'supervisord', 'supervisor', 'nodemon
 /**
  * Check if a process should be protected from cleanup.
  *
- * Protection criteria:
- *   1. In user's config whitelist (PID or name pattern)
- *   2. Has a daemon manager ancestor (pm2, forever, supervisord)
- *   3. Running inside a Docker container (Linux: different PID namespace)
- *   4. Launched with nohup
- *   5. VS Code child process (48h grace period)
+ * Now tree-aware: ancestor checks use ProcessTree instead of per-process execSync.
  *
- * Returns { protected: boolean, reason: string }
+ * @param {object} proc — process info from tree
+ * @param {object} config — zclean config
+ * @param {import('../process-tree').ProcessTree} [tree] — in-memory process tree
+ * @returns {{ protected: boolean, reason: string }}
  */
-function isWhitelisted(proc, config) {
+function isWhitelisted(proc, config, tree) {
   // 1. Config whitelist — match by PID or name substring
   if (config.whitelist && config.whitelist.length > 0) {
     for (const entry of config.whitelist) {
@@ -34,12 +31,12 @@ function isWhitelisted(proc, config) {
     }
   }
 
-  // 2. Daemon manager ancestor
-  if (hasDaemonAncestor(proc.pid)) {
+  // 2. Daemon manager ancestor (tree-based, no execSync)
+  if (tree && hasDaemonAncestorTree(proc.pid, tree)) {
     return { protected: true, reason: 'daemon-managed' };
   }
 
-  // 3. Docker container (Linux only)
+  // 3. Docker container (Linux only — reads /proc, no tree needed)
   if (isInDocker(proc.pid)) {
     return { protected: true, reason: 'docker-container' };
   }
@@ -49,9 +46,9 @@ function isWhitelisted(proc, config) {
     return { protected: true, reason: 'nohup-launched' };
   }
 
-  // 5. VS Code child with grace period
+  // 5. VS Code child with grace period (tree-based)
   const vscodeGrace = 48 * 60 * 60 * 1000; // 48 hours
-  if (isVSCodeChild(proc.pid) && proc.age < vscodeGrace) {
+  if (tree && isVSCodeChildTree(proc.pid, tree) && proc.age < vscodeGrace) {
     return { protected: true, reason: 'vscode-child-grace' };
   }
 
@@ -59,68 +56,20 @@ function isWhitelisted(proc, config) {
 }
 
 /**
- * Walk process tree upward looking for daemon manager ancestors.
+ * Check for daemon manager ancestor via ProcessTree.
  */
-function hasDaemonAncestor(pid) {
-  if (platform === 'win32') {
-    // Simplified check for Windows — just check parent command
-    try {
-      const output = execSync(
-        `wmic process where ProcessId=${pid} get ParentProcessId /value`,
-        { encoding: 'utf-8', timeout: 5000 }
-      ).trim();
-      const match = output.match(/ParentProcessId=(\d+)/);
-      if (!match) return false;
-      const ppid = parseInt(match[1], 10);
-      const parentCmd = execSync(
-        `wmic process where ProcessId=${ppid} get CommandLine /value`,
-        { encoding: 'utf-8', timeout: 5000 }
-      ).trim();
-      return DAEMON_MANAGERS.some((dm) => parentCmd.toLowerCase().includes(dm));
-    } catch {
-      return false;
-    }
-  }
-
-  // Unix: walk up the tree
-  const visited = new Set();
-  let currentPid = pid;
-
-  while (currentPid > 1 && !visited.has(currentPid)) {
-    visited.add(currentPid);
-    try {
-      const info = execSync(`ps -o ppid=,comm= -p ${currentPid}`, {
-        encoding: 'utf-8',
-        timeout: 5000,
-      }).trim();
-
-      const parts = info.trim().split(/\s+/);
-      if (parts.length < 2) break;
-
-      const parentPid = parseInt(parts[0], 10);
-      const comm = parts.slice(1).join(' ').toLowerCase();
-
-      if (DAEMON_MANAGERS.some((dm) => comm.includes(dm))) {
-        return true;
-      }
-
-      if (isNaN(parentPid) || parentPid <= 1) break;
-      currentPid = parentPid;
-    } catch {
-      break;
-    }
-  }
-
-  return false;
+function hasDaemonAncestorTree(pid, tree) {
+  return tree.hasAncestorMatching(pid, (proc) => {
+    const comm = proc.cmd.split(/\s+/)[0].split('/').pop().toLowerCase();
+    return DAEMON_MANAGERS.some((dm) => comm.includes(dm));
+  });
 }
 
 /**
- * Check if a process is running inside a Docker container.
- * Linux only: compares PID namespace with init (PID 1).
+ * Check if running inside a Docker container (Linux only).
  */
 function isInDocker(pid) {
   if (platform !== 'linux') return false;
-
   try {
     const procNs = fs.readlinkSync(`/proc/${pid}/ns/pid`);
     const initNs = fs.readlinkSync('/proc/1/ns/pid');
@@ -138,41 +87,13 @@ function isNohup(cmdline) {
 }
 
 /**
- * Check if a process is a child of VS Code.
+ * Check for VS Code ancestor via ProcessTree.
  */
-function isVSCodeChild(pid) {
-  if (platform === 'win32') return false;
-
-  const visited = new Set();
-  let currentPid = pid;
-
-  while (currentPid > 1 && !visited.has(currentPid)) {
-    visited.add(currentPid);
-    try {
-      const info = execSync(`ps -o ppid=,comm= -p ${currentPid}`, {
-        encoding: 'utf-8',
-        timeout: 5000,
-      }).trim();
-
-      const parts = info.trim().split(/\s+/);
-      if (parts.length < 2) break;
-
-      const parentPid = parseInt(parts[0], 10);
-      const comm = parts.slice(1).join(' ').toLowerCase();
-
-      // VS Code process names: code, code-insiders, electron (Code.app)
-      if (/\b(code|code-insiders|electron.*code)\b/.test(comm)) {
-        return true;
-      }
-
-      if (isNaN(parentPid) || parentPid <= 1) break;
-      currentPid = parentPid;
-    } catch {
-      break;
-    }
-  }
-
-  return false;
+function isVSCodeChildTree(pid, tree) {
+  return tree.hasAncestorMatching(pid, (proc) => {
+    const comm = proc.cmd.split(/\s+/)[0].split('/').pop().toLowerCase();
+    return /\b(code|code-insiders|electron.*code)\b/.test(comm);
+  });
 }
 
-module.exports = { isWhitelisted, hasDaemonAncestor, isInDocker, isNohup, isVSCodeChild };
+module.exports = { isWhitelisted, isInDocker, isNohup };

package/src/doctor/checks.js

@@ -0,0 +1,229 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execSync } = require('child_process');
+const { scan, hasScanErrors } = require('../scanner');
+const { getConfigFile, getCumulativeStats } = require('../config');
+
+function buildDoctorReport(config, options = {}) {
+  const runtime = buildRuntime(options);
+  const generatedAt = readGeneratedAt(options);
+  const stats = normalizeStats(options.stats || getCumulativeStats());
+  const checks = [
+    checkConfig(),
+    checkProcessScan(config, options),
+    checkHook(runtime.homedir),
+    checkScheduler(runtime),
+    checkLastRun(stats, generatedAt),
+  ];
+
+  return {
+    schemaVersion: 1,
+    generatedAt,
+    overallStatus: getOverallStatus(checks),
+    issueCount: checks.filter((check) => check.status !== 'ok').length,
+    checks,
+    stats,
+  };
+}
+
+function buildRuntime(options) {
+  const runtime = options.runtime || {};
+  return {
+    platform: runtime.platform || options.platform || os.platform(),
+    homedir: runtime.homedir || options.homedir || os.homedir(),
+    execSync: runtime.execSync || options.execSync || execSync,
+  };
+}
+
+function readGeneratedAt(options) {
+  const value = typeof options.now === 'function' ? options.now() : new Date().toISOString();
+  if (value instanceof Date) return value.toISOString();
+  return String(value);
+}
+
+function normalizeStats(stats) {
+  return {
+    totalKilled: stats.totalKilled || 0,
+    totalMemFreed: stats.totalMemFreed || 0,
+    weekKilled: stats.weekKilled || 0,
+    weekMemFreed: stats.weekMemFreed || 0,
+    lastRun: stats.lastRun || null,
+  };
+}
+
+function checkConfig() {
+  if (fs.existsSync(getConfigFile())) {
+    return { id: 'config', status: 'ok', message: 'found' };
+  }
+  return {
+    id: 'config',
+    status: 'warning',
+    message: 'not found - run `zclean init`',
+  };
+}
+
+function checkProcessScan(config, options) {
+  const scanFn = options.scan || scan;
+  const hasScanErrorsFn = options.hasScanErrors || hasScanErrors;
+  let scanResult;
+
+  try {
+    scanResult = scanFn(config);
+  } catch (err) {
+    return {
+      id: 'process-scan',
+      status: 'error',
+      message: err.message || 'unable to enumerate processes',
+    };
+  }
+
+  if (hasScanErrorsFn(scanResult)) {
+    const errors = Array.isArray(scanResult.errors) ? scanResult.errors : [];
+    const first = errors[0] || {};
+    return {
+      id: 'process-scan',
+      status: 'error',
+      message: `failed - ${first.message || first.code || 'unable to enumerate processes'}`,
+      details: { errors },
+    };
+  }
+
+  if (Array.isArray(scanResult.warnings) && scanResult.warnings.length > 0) {
+    return {
+      id: 'process-scan',
+      status: 'warning',
+      message: `warning - ${scanResult.warnings[0].message || scanResult.warnings[0].code || 'partial diagnostic'}`,
+      details: { warnings: scanResult.warnings },
+    };
+  }
+
+  return { id: 'process-scan', status: 'ok', message: 'healthy' };
+}
+
+function checkHook(homeDir) {
+  const claudeSettings = path.join(homeDir, '.claude', 'settings.json');
+  let hookInstalled = false;
+  if (fs.existsSync(claudeSettings)) {
+    try {
+      const settings = JSON.parse(fs.readFileSync(claudeSettings, 'utf-8'));
+      const hooks = settings.hooks?.Stop || [];
+      hookInstalled = hooks.some((h) =>
+        (h.command && h.command.includes('zclean')) ||
+        (Array.isArray(h.hooks) && h.hooks.some((sub) => sub.command && sub.command.includes('zclean')))
+      );
+    } catch {}
+  }
+  if (hookInstalled) return { id: 'hook', status: 'ok', message: 'Claude Code SessionEnd registered' };
+  return { id: 'hook', status: 'warning', message: 'not registered - run `zclean init`' };
+}
+
+function checkScheduler(runtime) {
+  if (runtime.platform === 'darwin') return checkLaunchd(runtime);
+  if (runtime.platform === 'linux') return checkSystemd(runtime);
+  if (runtime.platform === 'win32') return checkTaskScheduler(runtime);
+  return {
+    id: 'scheduler',
+    status: 'warning',
+    message: `unsupported platform (${runtime.platform})`,
+    details: { platform: runtime.platform },
+  };
+}
+
+function checkLaunchd(runtime) {
+  const plistPath = path.join(runtime.homedir, 'Library', 'LaunchAgents', 'com.zclean.hourly.plist');
+  if (!fs.existsSync(plistPath)) {
+    return {
+      id: 'scheduler',
+      status: 'warning',
+      message: 'not installed - run `zclean init`',
+      details: { platform: 'darwin' },
+    };
+  }
+
+  try {
+    const out = runtime.execSync('launchctl list com.zclean.hourly 2>&1', { encoding: 'utf-8', timeout: 5000 });
+    if (!out.includes('Could not find')) {
+      return {
+        id: 'scheduler',
+        status: 'ok',
+        message: 'launchd agent loaded',
+        details: { platform: 'darwin' },
+      };
+    }
+  } catch {}
+
+  return {
+    id: 'scheduler',
+    status: 'warning',
+    message: 'plist exists but not loaded - run `zclean init`',
+    details: { platform: 'darwin' },
+  };
+}
+
+function checkSystemd(runtime) {
+  const timerPath = path.join(runtime.homedir, '.config', 'systemd', 'user', 'zclean.timer');
+  if (fs.existsSync(timerPath)) {
+    return {
+      id: 'scheduler',
+      status: 'ok',
+      message: 'systemd timer installed',
+      details: { platform: 'linux' },
+    };
+  }
+  return {
+    id: 'scheduler',
+    status: 'warning',
+    message: 'not installed - run `zclean init`',
+    details: { platform: 'linux' },
+  };
+}
+
+function checkTaskScheduler(runtime) {
+  try {
+    runtime.execSync('schtasks /query /TN "zclean-hourly"', { encoding: 'utf-8', timeout: 5000 });
+    return {
+      id: 'scheduler',
+      status: 'ok',
+      message: 'Task Scheduler task installed',
+      details: { platform: 'win32' },
+    };
+  } catch {}
+  return {
+    id: 'scheduler',
+    status: 'warning',
+    message: 'not installed - run `zclean init`',
+    details: { platform: 'win32' },
+  };
+}
+
+function checkLastRun(stats, generatedAt) {
+  if (!stats.lastRun) return { id: 'last-run', status: 'ok', message: 'never - run `zclean --yes` to test' };
+
+  const ago = new Date(generatedAt).getTime() - new Date(stats.lastRun).getTime();
+  const agoStr = ago < 3600000 ? `${Math.floor(ago / 60000)}m ago` :
+                 ago < 86400000 ? `${Math.floor(ago / 3600000)}h ago` :
+                 `${Math.floor(ago / 86400000)}d ago`;
+  if (ago > 2 * 3600000) {
+    return {
+      id: 'last-run',
+      status: 'warning',
+      message: `${agoStr} (${stats.lastRun.slice(0, 19).replace('T', ' ')}) - scheduler may not be running`,
+    };
+  }
+  return {
+    id: 'last-run',
+    status: 'ok',
+    message: `${agoStr} (${stats.lastRun.slice(0, 19).replace('T', ' ')})`,
+  };
+}
+
+function getOverallStatus(checks) {
+  if (checks.some((check) => check.status === 'error')) return 'error';
+  if (checks.some((check) => check.status === 'warning')) return 'warning';
+  return 'ok';
+}
+
+module.exports = { buildDoctorReport };

package/src/doctor/render.js

@@ -0,0 +1,37 @@
+'use strict';
+
+const { c, bold } = require('../reporter');
+
+function renderDoctorText(report, write) {
+  write(bold('\n  zclean doctor\n\n'));
+  for (const check of report.checks) {
+    write(formatCheckLine(check));
+  }
+  write(c('cyan', '  Stats:') + `     ${report.stats.totalKilled} cleaned all time, ${report.stats.weekKilled} this week\n`);
+  write('\n');
+  if (report.overallStatus === 'ok') {
+    write(c('green', '  All checks passed.\n\n'));
+    return;
+  }
+  write(c('yellow', `  ${report.issueCount} issue${report.issueCount === 1 ? '' : 's'} found. Run \`zclean init\` to fix.\n\n`));
+}
+
+function formatCheckLine(check) {
+  const labels = {
+    config: 'Config',
+    'process-scan': 'Process scan',
+    hook: 'Hook',
+    scheduler: 'Scheduler',
+    'last-run': 'Last run',
+  };
+  const colors = {
+    ok: 'green',
+    warning: 'yellow',
+    error: 'red',
+  };
+  const label = `${labels[check.id] || check.id}:`;
+  const padding = ' '.repeat(Math.max(1, 14 - label.length));
+  return c(colors[check.status] || 'gray', `  ${label}`) + `${padding}${check.message}\n`;
+}
+
+module.exports = { renderDoctorText };

package/src/doctor.js

@@ -0,0 +1,22 @@
+'use strict';
+
+const { buildDoctorReport } = require('./doctor/checks');
+const { renderDoctorText } = require('./doctor/render');
+
+function runDoctor(config, options = {}) {
+  const report = buildDoctorReport(config, options);
+  const exitCode = report.overallStatus === 'ok' ? 0 : 1;
+  const write = typeof options.write === 'function'
+    ? options.write
+    : (chunk) => process.stdout.write(chunk);
+
+  if (options.json) {
+    write(`${JSON.stringify(report, null, 2)}\n`);
+  } else {
+    renderDoctorText(report, write);
+  }
+
+  return { ...report, exitCode };
+}
+
+module.exports = { runDoctor };

package/src/installer/bin-path.js

@@ -0,0 +1,106 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const LOCAL_BIN_HINT = 'Install zclean first with `npm install -g z-clean`, then run `zclean init` again.';
+
+function resolveZcleanBin(options = {}) {
+  const runtime = {
+    execSync: options.execSync || execSync,
+    existsSync: options.existsSync || fs.existsSync,
+    homedir: options.homedir || os.homedir(),
+    platform: options.platform || os.platform(),
+    argv: options.argv || process.argv,
+  };
+
+  const current = currentExecutableCandidate(runtime);
+  if (current) return current;
+
+  for (const candidate of npmGlobalCandidates(runtime)) {
+    if (runtime.existsSync(candidate)) return candidate;
+  }
+
+  for (const candidate of commonCandidates(runtime)) {
+    if (runtime.existsSync(candidate)) return candidate;
+  }
+
+  return null;
+}
+
+function currentExecutableCandidate(runtime) {
+  const current = runtime.argv && runtime.argv[1] ? path.resolve(runtime.argv[1]) : null;
+  if (!current || isTransientNpxPath(current) || !runtime.existsSync(current)) return null;
+
+  const base = path.basename(current).toLowerCase();
+  if (base === 'zclean' || base === 'zclean.cmd' || base === 'zclean.js') return current;
+  return null;
+}
+
+function npmGlobalCandidates(runtime) {
+  const names = runtime.platform === 'win32' ? ['zclean.cmd', 'zclean'] : ['zclean'];
+  const prefixes = [];
+
+  try {
+    const npmBin = runtime.execSync('npm bin -g', { encoding: 'utf-8', timeout: 5000 }).trim();
+    if (npmBin) prefixes.push(npmBin);
+  } catch {}
+
+  try {
+    const npmPrefix = runtime.execSync('npm prefix -g', { encoding: 'utf-8', timeout: 5000 }).trim();
+    if (npmPrefix) {
+      prefixes.push(runtime.platform === 'win32' ? npmPrefix : path.join(npmPrefix, 'bin'));
+      prefixes.push(path.join(npmPrefix, 'node_modules', '.bin'));
+    }
+  } catch {}
+
+  return unique(prefixes.flatMap((prefix) => names.map((name) => path.join(prefix, name))));
+}
+
+function commonCandidates(runtime) {
+  if (runtime.platform === 'win32') {
+    const appData = process.env.APPDATA || path.join(runtime.homedir, 'AppData', 'Roaming');
+    return [
+      path.join(appData, 'npm', 'zclean.cmd'),
+      path.join(runtime.homedir, 'AppData', 'Roaming', 'npm', 'zclean.cmd'),
+    ];
+  }
+
+  return [
+    path.join(runtime.homedir, '.local', 'bin', 'zclean'),
+    path.join(runtime.homedir, 'node_modules', '.bin', 'zclean'),
+    path.join(runtime.homedir, '.local', 'share', 'npm', 'bin', 'zclean'),
+    '/opt/homebrew/bin/zclean',
+    '/usr/local/bin/zclean',
+    '/usr/bin/zclean',
+  ];
+}
+
+function quoteShellArg(value) {
+  const text = String(value);
+  if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(text)) return text;
+  return `'${text.replace(/'/g, "'\\''")}'`;
+}
+
+function quoteSystemdArg(value) {
+  const text = String(value);
+  if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(text)) return text;
+  return `"${text.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+function isTransientNpxPath(filePath) {
+  return /[\\/]_npx[\\/]/.test(filePath);
+}
+
+function unique(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+module.exports = {
+  LOCAL_BIN_HINT,
+  quoteShellArg,
+  quoteSystemdArg,
+  resolveZcleanBin,
+};

package/src/installer/hook.js

@@ -3,10 +3,9 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const { LOCAL_BIN_HINT, quoteShellArg, resolveZcleanBin } = require('./bin-path');
 
 const CLAUDE_SETTINGS_PATH = path.join(os.homedir(), '.claude', 'settings.json');
-// Use npx to ensure zclean is found regardless of global install status
-const HOOK_COMMAND = 'npx --yes @thestackai/zclean --yes --session-pid=$PPID';
 const HOOK_ID = 'zclean-session-cleanup';
 
 /**
@@ -71,13 +70,21 @@ function installHook() {
     };
   }
 
+  const binPath = resolveZcleanBin();
+  if (!binPath) {
+    return {
+      installed: false,
+      message: `Local zclean executable not found. ${LOCAL_BIN_HINT}`,
+    };
+  }
+
   // Add hook using the matcher + hooks array format required by Claude Code
   settings.hooks.Stop.push({
     matcher: '',
     hooks: [
       {
         type: 'command',
-        command: HOOK_COMMAND,
+        command: buildHookCommand(binPath),
       },
     ],
   });
@@ -133,4 +140,8 @@ function removeHook() {
   return { removed: true, message: 'Hook removed from Claude Code settings.' };
 }
 
-module.exports = { installHook, removeHook };
+function buildHookCommand(binPath) {
+  return `${quoteShellArg(binPath)} --yes --session-pid=$PPID`;
+}
+
+module.exports = { installHook, removeHook, buildHookCommand };