z-clean 0.1.1 → 0.3.0

package/src/config.js

@@ -4,19 +4,34 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
-// Config directory: ~/.zclean/
-const CONFIG_DIR = path.join(os.homedir(), '.zclean');
-const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
-const LOG_FILE = path.join(CONFIG_DIR, 'history.jsonl');
+const CONFIG_DIR_ENV = 'ZCLEAN_CONFIG_DIR';
+
+function getConfigDir() {
+  const configured = process.env[CONFIG_DIR_ENV];
+  if (configured) return path.resolve(configured);
+  if (process.env.NODE_TEST_CONTEXT) {
+    return path.join(os.tmpdir(), 'zclean-node-test', String(process.pid));
+  }
+  return path.join(os.homedir(), '.zclean');
+}
+
+function getConfigFile() {
+  return path.join(getConfigDir(), 'config.json');
+}
+
+function getLogFile() {
+  return path.join(getConfigDir(), 'history.jsonl');
+}
 
 const DEFAULT_CONFIG = {
   whitelist: [],
   maxAge: '24h',
   memoryThreshold: '500MB',
-  schedule: 'hourly',
   sigterm_timeout: 10,
   dryRunDefault: true,
   logRetention: '30d',
+  maxKillBatch: 20,
+  customAiDirs: [],
 };
 
 /**
@@ -53,8 +68,9 @@ function parseMemory(str) {
  * Ensure the config directory exists.
  */
 function ensureConfigDir() {
-  if (!fs.existsSync(CONFIG_DIR)) {
-    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  const configDir = getConfigDir();
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true });
   }
 }
 
@@ -63,9 +79,10 @@ function ensureConfigDir() {
  */
 function loadConfig() {
   ensureConfigDir();
-  if (fs.existsSync(CONFIG_FILE)) {
+  const configFile = getConfigFile();
+  if (fs.existsSync(configFile)) {
     try {
-      const raw = fs.readFileSync(CONFIG_FILE, 'utf-8');
+      const raw = fs.readFileSync(configFile, 'utf-8');
       const userConfig = JSON.parse(raw);
       return { ...DEFAULT_CONFIG, ...userConfig };
     } catch {
@@ -81,7 +98,7 @@ function loadConfig() {
  */
 function saveConfig(config) {
   ensureConfigDir();
-  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+  fs.writeFileSync(getConfigFile(), JSON.stringify(config, null, 2) + '\n', 'utf-8');
 }
 
 /**
@@ -91,16 +108,17 @@ function saveConfig(config) {
 function appendLog(entry) {
   ensureConfigDir();
   const line = JSON.stringify({ timestamp: new Date().toISOString(), ...entry }) + '\n';
-  fs.appendFileSync(LOG_FILE, line, 'utf-8');
+  fs.appendFileSync(getLogFile(), line, 'utf-8');
 }
 
 /**
  * Read recent log entries (up to `limit`).
  */
 function readLogs(limit = 50) {
-  if (!fs.existsSync(LOG_FILE)) return [];
+  const logFile = getLogFile();
+  if (!fs.existsSync(logFile)) return [];
   try {
-    const lines = fs.readFileSync(LOG_FILE, 'utf-8').trim().split('\n').filter(Boolean);
+    const lines = fs.readFileSync(logFile, 'utf-8').trim().split('\n').filter(Boolean);
     return lines
       .slice(-limit)
       .map((line) => {
@@ -117,10 +135,11 @@ function readLogs(limit = 50) {
  */
 function pruneLogs(config) {
   const retentionMs = parseDuration(config.logRetention || '30d');
-  if (!retentionMs || !fs.existsSync(LOG_FILE)) return;
+  const logFile = getLogFile();
+  if (!retentionMs || !fs.existsSync(logFile)) return;
 
   const cutoff = Date.now() - retentionMs;
-  const lines = fs.readFileSync(LOG_FILE, 'utf-8').trim().split('\n').filter(Boolean);
+  const lines = fs.readFileSync(logFile, 'utf-8').trim().split('\n').filter(Boolean);
   const kept = lines.filter((line) => {
     try {
       const entry = JSON.parse(line);
@@ -129,20 +148,106 @@ function pruneLogs(config) {
       return false;
     }
   });
-  fs.writeFileSync(LOG_FILE, kept.join('\n') + (kept.length ? '\n' : ''), 'utf-8');
+  fs.writeFileSync(logFile, kept.join('\n') + (kept.length ? '\n' : ''), 'utf-8');
+}
+
+/**
+ * Compute cumulative stats from history.jsonl.
+ * Returns { totalKilled, totalMemFreed, weekKilled, weekMemFreed, lastRun }.
+ */
+function getCumulativeStats() {
+  const logs = readLogs(10000);
+  const weekAgo = Date.now() - 7 * 24 * 60 * 60 * 1000;
+
+  let totalKilled = 0;
+  let totalMemFreed = 0;
+  let weekKilled = 0;
+  let weekMemFreed = 0;
+  let lastRun = null;
+
+  for (const entry of logs) {
+    if (entry.action === 'cleanup-summary') {
+      totalKilled += entry.killed || 0;
+      totalMemFreed += entry.totalMemFreed || 0;
+      if (!lastRun || entry.timestamp > lastRun) lastRun = entry.timestamp;
+
+      const ts = new Date(entry.timestamp).getTime();
+      if (ts >= weekAgo) {
+        weekKilled += entry.killed || 0;
+        weekMemFreed += entry.totalMemFreed || 0;
+      }
+    }
+  }
+
+  return { totalKilled, totalMemFreed, weekKilled, weekMemFreed, lastRun };
 }
 
-module.exports = {
-  CONFIG_DIR,
-  CONFIG_FILE,
-  LOG_FILE,
+function summarizeHistory(logs, stats = {}) {
+  let dryRuns = 0;
+  let scans = 0;
+  let scanFailures = 0;
+  let cleanupSummaries = 0;
+  let summaryFailedKills = 0;
+  let looseFailedKills = 0;
+
+  for (const entry of logs || []) {
+    switch (entry.action) {
+      case 'dry-run':
+        dryRuns++;
+        break;
+      case 'scan':
+        scans++;
+        break;
+      case 'scan-failed':
+        scanFailures++;
+        break;
+      case 'cleanup-summary':
+        cleanupSummaries++;
+        summaryFailedKills += entry.failed || 0;
+        break;
+      case 'kill-failed':
+        looseFailedKills++;
+        break;
+      default:
+        break;
+    }
+  }
+
+  return {
+    dryRuns,
+    scans,
+    scanFailures,
+    cleanupSummaries,
+    failedKills: cleanupSummaries > 0 ? summaryFailedKills : looseFailedKills,
+    totalKilled: stats.totalKilled || 0,
+    totalMemFreed: stats.totalMemFreed || 0,
+    weekKilled: stats.weekKilled || 0,
+    weekMemFreed: stats.weekMemFreed || 0,
+    lastRun: stats.lastRun || null,
+  };
+}
+
+const exported = {
   DEFAULT_CONFIG,
   parseDuration,
   parseMemory,
+  getConfigDir,
+  getConfigFile,
+  getLogFile,
   loadConfig,
   saveConfig,
   appendLog,
   readLogs,
   pruneLogs,
   ensureConfigDir,
+  getCumulativeStats,
+  summarizeHistory,
 };
+
+Object.defineProperties(exported, {
+  CONFIG_DIR: { enumerable: true, get: getConfigDir },
+  CONFIG_FILE: { enumerable: true, get: getConfigFile },
+  LOG_FILE: { enumerable: true, get: getLogFile },
+});
+
+module.exports = exported;

package/src/detector/orphan.js

@@ -1,149 +1,39 @@
 'use strict';
 
-const { execSync } = require('child_process');
-const os = require('os');
-
-const platform = os.platform();
-
 /**
- * Check if a PID is an orphan process.
- *
- * Orphan definition by platform:
- *   macOS:   PPID === 1 (launchd)
- *   Linux:   PPID === 1 OR PPID === systemd --user PID
- *   Windows: parent process no longer exists
+ * Orphan detection — now a thin wrapper around ProcessTree.
  *
- * Returns { isOrphan: boolean, ppid: number|null, reason: string }
- */
-function checkOrphan(pid) {
-  try {
-    if (platform === 'win32') {
-      return checkOrphanWindows(pid);
-    } else {
-      return checkOrphanUnix(pid);
-    }
-  } catch {
-    // Process may have disappeared during check
-    return { isOrphan: false, ppid: null, reason: 'check-failed' };
-  }
-}
-
-/**
- * Unix (macOS/Linux) orphan check.
+ * scanner.js uses ProcessTree directly. This module is kept for
+ * backward compatibility if external code imports checkOrphan().
  */
-function checkOrphanUnix(pid) {
-  let ppidStr;
-  try {
-    ppidStr = execSync(`ps -o ppid= -p ${pid}`, { encoding: 'utf-8', timeout: 5000 }).trim();
-  } catch {
-    return { isOrphan: false, ppid: null, reason: 'process-gone' };
-  }
-
-  const ppid = parseInt(ppidStr, 10);
-  if (isNaN(ppid)) {
-    return { isOrphan: false, ppid: null, reason: 'invalid-ppid' };
-  }
-
-  // macOS: PPID 1 means reparented to launchd
-  if (platform === 'darwin' && ppid === 1) {
-    return { isOrphan: true, ppid, reason: 'reparented-to-launchd' };
-  }
 
-  // Linux: PPID 1 means reparented to init/systemd
-  if (platform === 'linux' && ppid === 1) {
-    return { isOrphan: true, ppid, reason: 'reparented-to-init' };
-  }
-
-  // Linux: also check if reparented to systemd --user
-  if (platform === 'linux' && ppid > 1) {
-    try {
-      const parentCmd = execSync(`ps -o comm= -p ${ppid}`, { encoding: 'utf-8', timeout: 5000 }).trim();
-      if (parentCmd === 'systemd') {
-        return { isOrphan: true, ppid, reason: 'reparented-to-systemd-user' };
-      }
-    } catch {
-      // Parent might have died between checks
-    }
-  }
-
-  return { isOrphan: false, ppid, reason: 'has-parent' };
-}
+const { ProcessTree } = require('../process-tree');
 
 /**
- * Windows orphan check — parent process doesn't exist.
+ * Check if a PID is an orphan process.
+ * Builds a fresh ProcessTree — prefer tree.isOrphan(pid) in hot paths.
+ *
+ * @param {number} pid
+ * @returns {{ isOrphan: boolean, ppid: number|null, reason: string }}
  */
-function checkOrphanWindows(pid) {
-  try {
-    // Get parent PID via wmic
-    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 { isOrphan: false, ppid: null, reason: 'no-ppid-info' };
-    }
-
-    const ppid = parseInt(match[1], 10);
-
-    // Check if parent process still exists
-    try {
-      execSync(`wmic process where ProcessId=${ppid} get ProcessId /value`, {
-        encoding: 'utf-8',
-        timeout: 5000,
-      });
-      return { isOrphan: false, ppid, reason: 'has-parent' };
-    } catch {
-      // Parent doesn't exist — orphan
-      return { isOrphan: true, ppid, reason: 'parent-gone' };
-    }
-  } catch {
-    return { isOrphan: false, ppid: null, reason: 'check-failed' };
-  }
+function checkOrphan(pid) {
+  const tree = ProcessTree.build();
+  return tree.isOrphan(pid);
 }
 
 /**
- * Check if a process is inside a tmux or screen session tree.
- * Walks the process tree upward looking for tmux/screen ancestor.
+ * Check if a PID is inside a terminal multiplexer (tmux/screen).
+ * Builds a fresh ProcessTree — prefer tree.hasAncestorMatching() in hot paths.
  *
- * Returns true if the process has a tmux or screen ancestor.
+ * @param {number} pid
+ * @returns {boolean}
  */
 function isInTerminalMultiplexer(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();
-
-      // Parse "  PPID COMMAND"
-      const parts = info.trim().split(/\s+/);
-      if (parts.length < 2) break;
-
-      const parentPid = parseInt(parts[0], 10);
-      const comm = parts.slice(1).join(' ');
-
-      // Check for tmux/screen
-      if (/^(tmux|screen)/.test(comm)) {
-        return true;
-      }
-
-      if (isNaN(parentPid) || parentPid <= 1) break;
-      currentPid = parentPid;
-    } catch {
-      break;
-    }
-  }
-
-  return false;
+  const tree = ProcessTree.build();
+  return tree.hasAncestorMatching(pid, (proc) => {
+    const comm = proc.cmd.split(/\s+/)[0].split('/').pop();
+    return comm === 'tmux' || comm === 'screen';
+  });
 }
 
 module.exports = { checkOrphan, isInTerminalMultiplexer };

package/src/detector/patterns.js

@@ -4,13 +4,40 @@
  * Process patterns to detect AI tool zombies.
  *
  * Each pattern has:
- *   name       — human-readable identifier
- *   match      — RegExp to test against full command line
- *   minAge     — minimum age (ms) before considering it a zombie (0 = any age)
- *   maxOrphanAge — if set, orphan processes older than this are zombies (duration string)
- *   memThreshold — if set, only flag if RSS exceeds this (bytes string like "500MB")
- *   orphanOnly — if true, only flag orphaned processes (default: true for most)
+ *   name          — human-readable identifier
+ *   match         — RegExp to test against full command line
+ *   minAge        — minimum age (ms) before considering it a zombie (0 = any age)
+ *   maxOrphanAge  — if set, orphan processes older than this are zombies (duration string)
+ *   memThreshold  — if set, only flag if RSS exceeds this (bytes string like "500MB")
+ *   orphanOnly    — if true, only flag orphaned processes (default: true for most)
+ *   aiPathRequired — if true, cmdline must also match AI_DIR_REGEX to be flagged
  */
+
+/** Centralized list of AI tool config directories */
+const AI_TOOL_DIRS = [
+  '.claude', '.cursor', '.windsurf', '.continue', '.cline',
+  '.roo', '.kilocode', '.augment', '.codex', '.copilot',
+  '.aider', '.gemini', '.trae', '.goose',
+];
+
+/**
+ * Build a regex that matches any AI tool directory in a path.
+ * Matches "{dir}/" or "{dir}\" for each directory.
+ * @param {string[]} [customDirs] — additional directories from config
+ * @returns {RegExp}
+ */
+function buildAiDirRegex(customDirs) {
+  const allDirs = customDirs && customDirs.length > 0
+    ? [...AI_TOOL_DIRS, ...customDirs]
+    : AI_TOOL_DIRS;
+
+  const escaped = allDirs.map((d) => d.replace(/\./g, '\\.'));
+  return new RegExp(`(?:${escaped.join('|')})[/\\\\]`);
+}
+
+/** Default regex (no custom dirs) */
+const AI_DIR_REGEX = buildAiDirRegex();
+
 const PATTERNS = [
   // MCP servers — any orphaned MCP server is suspect
   {
@@ -37,6 +64,14 @@ const PATTERNS = [
     orphanOnly: true,
   },
 
+  // Claude session processes (claude --session-id)
+  {
+    name: 'claude-session',
+    match: /claude\s+--session-id/,
+    minAge: 0,
+    orphanOnly: true,
+  },
+
   // Claude subagent processes
   {
     name: 'claude-subagent',
@@ -53,13 +88,38 @@ const PATTERNS = [
     orphanOnly: true,
   },
 
-  // Build tools — only if orphaned for 24h+
+  // Codex sandbox processes
+  {
+    name: 'codex-sandbox',
+    match: /codex-sandbox/,
+    minAge: 0,
+    orphanOnly: true,
+  },
+
+  // Aider processes
+  {
+    name: 'aider',
+    match: /python.*aider|(?:^|\s|\/)aider\b/,
+    minAge: 0,
+    orphanOnly: true,
+  },
+
+  // Gemini CLI processes
+  {
+    name: 'gemini-cli',
+    match: /\bgemini\b/,
+    minAge: 0,
+    orphanOnly: true,
+  },
+
+  // Build tools — only if orphaned for 24h+ AND in AI path
   {
     name: 'esbuild',
     match: /esbuild/,
     minAge: 0,
     maxOrphanAge: '24h',
     orphanOnly: true,
+    aiPathRequired: true,
   },
   {
     name: 'vite',
@@ -67,6 +127,7 @@ const PATTERNS = [
     minAge: 0,
     maxOrphanAge: '24h',
     orphanOnly: true,
+    aiPathRequired: true,
   },
   {
     name: 'next-dev',
@@ -74,6 +135,7 @@ const PATTERNS = [
     minAge: 0,
     maxOrphanAge: '24h',
     orphanOnly: true,
+    aiPathRequired: true,
   },
   {
     name: 'webpack',
@@ -81,33 +143,39 @@ const PATTERNS = [
     minAge: 0,
     maxOrphanAge: '24h',
     orphanOnly: true,
+    aiPathRequired: true,
   },
 
-  // npx/npm exec — orphaned
+  // npx/npm exec — orphaned, AI path required
   {
     name: 'npm-exec',
     match: /npm\s+exec|npx\s/,
     minAge: 0,
     orphanOnly: true,
+    aiPathRequired: true,
   },
 
   // Node processes with AI tool paths — orphan + age/memory gated
+  // match: node running from AI dirs, MCP servers, or agent paths
+  // aiPathRequired adds a second gate via AI_DIR_REGEX
   {
     name: 'node-ai-path',
-    match: /node\b.*(?:\.claude[/\\]|[/\\]mcp[/\\]|[/\\]agent[/\\])/,
+    match: /node\b.*(?:[/\\]mcp[/\\]|[/\\]agent[/\\]|[/\\]server[/\\])/,
     minAge: 0,
     maxOrphanAge: '24h',
     memThreshold: '500MB',
     orphanOnly: true,
+    aiPathRequired: true,
   },
 
-  // TypeScript runners — orphan + AI tool related
+  // TypeScript runners — orphan + AI path required
   {
     name: 'tsx',
     match: /\btsx\b/,
     minAge: 0,
     maxOrphanAge: '24h',
     orphanOnly: true,
+    aiPathRequired: true,
   },
   {
     name: 'ts-node',
@@ -115,34 +183,49 @@ const PATTERNS = [
     minAge: 0,
     maxOrphanAge: '24h',
     orphanOnly: true,
+    aiPathRequired: true,
   },
   {
     name: 'bun',
-    match: /\bbun\b.*(?:\.claude|mcp|agent)/,
+    match: /\bbun\b/,
     minAge: 0,
     maxOrphanAge: '24h',
     orphanOnly: true,
+    aiPathRequired: true,
   },
   {
     name: 'deno',
-    match: /\bdeno\b.*(?:\.claude|mcp|agent)/,
+    match: /\bdeno\b/,
     minAge: 0,
     maxOrphanAge: '24h',
     orphanOnly: true,
+    aiPathRequired: true,
   },
 ];
 
 /**
  * Match a command line against known patterns.
  * Returns the first matching pattern or null.
+ *
+ * @param {string} cmdline — process command line
+ * @param {object} [config] — optional config with customAiDirs
+ * @returns {object|null} matched pattern or null
  */
-function matchPattern(cmdline) {
+function matchPattern(cmdline, config) {
+  const aiRegex = config && config.customAiDirs && config.customAiDirs.length > 0
+    ? buildAiDirRegex(config.customAiDirs)
+    : AI_DIR_REGEX;
+
   for (const pattern of PATTERNS) {
     if (pattern.match.test(cmdline)) {
+      // If pattern requires AI path context, check it
+      if (pattern.aiPathRequired && !aiRegex.test(cmdline)) {
+        continue;
+      }
       return pattern;
     }
   }
   return null;
 }
 
-module.exports = { PATTERNS, matchPattern };
+module.exports = { PATTERNS, AI_TOOL_DIRS, AI_DIR_REGEX, buildAiDirRegex, matchPattern };