z-clean 0.1.1 → 0.3.0

package/src/scanner.js

@@ -1,90 +1,91 @@
 'use strict';
 
-const { execSync } = require('child_process');
-const os = require('os');
-const { matchPattern } = require('./detector/patterns');
-const { checkOrphan, isInTerminalMultiplexer } = require('./detector/orphan');
+const { ProcessTree } = require('./process-tree');
+const { matchPattern, AI_DIR_REGEX, buildAiDirRegex } = require('./detector/patterns');
 const { isWhitelisted } = require('./detector/whitelist');
 const { parseDuration, parseMemory } = require('./config');
 
-const platform = os.platform();
-
 /**
  * Scan for zombie/orphan processes left by AI coding tools.
  *
- * Returns an array of process objects:
- *   { pid, name, cmd, ppid, mem, age, startTime, reason, pattern }
+ * Uses ProcessTree for all process data — single ps/wmic call,
+ * zero execSync during scan loop.
  *
  * @param {object} config — loaded zclean config
- * @param {object} opts — { sessionPid?: number } for session-aware filtering
+ * @param {object} opts — { sessionPid?: number }
+ * @returns {Array<{pid, name, cmd, ppid, mem, age, startTime, reason, pattern}>}
  */
 function scan(config, opts = {}) {
-  const processes = listProcesses();
+  const tree = ProcessTree.build();
+  const aiDirRegex = buildAiDirRegex(config.customAiDirs);
   const zombies = [];
-
-  for (const proc of processes) {
+  const warnings = Array.isArray(tree.warnings) ? [...tree.warnings] : [];
+  const errors = Array.isArray(tree.errors) ? [...tree.errors] : [];
+  const sessionPid = normalizePid(opts.sessionPid);
+  const session = sessionPid
+    ? { pid: sessionPid, filtered: true, matched: 0, excluded: 0, unattributed: 0 }
+    : null;
+
+  // Multiplexer detection function for tree queries
+  const isMultiplexer = (proc) => {
+    const comm = proc.cmd.split(/\s+/)[0].split('/').pop();
+    return comm === 'tmux' || comm === 'screen';
+  };
+
+  // Iterate all processes in the tree
+  for (const [, proc] of tree.byPid) {
     // Match against known AI tool patterns
-    const pattern = matchPattern(proc.cmd);
+    const pattern = matchPattern(proc.cmd, config);
     if (!pattern) continue;
 
-    // Check orphan status
-    const orphanResult = checkOrphan(proc.pid);
-    proc.ppid = orphanResult.ppid;
+    // AI path filter: skip generic patterns if command isn't in an AI tool directory
+    if (pattern.aiPathRequired && !aiDirRegex.test(proc.cmd)) continue;
 
-    // If pattern requires orphan status and process isn't orphaned, skip
-    if (pattern.orphanOnly && !orphanResult.isOrphan) continue;
+    // Check orphan status via tree (no execSync)
+    const orphanResult = tree.isOrphan(proc.pid);
+    const sessionRelated = sessionPid
+      ? tree.hasAncestorMatching(proc.pid, (p) => p.pid === sessionPid)
+      : false;
 
-    // Skip processes in tmux/screen sessions (they're likely intentional)
-    if (isInTerminalMultiplexer(proc.pid)) continue;
-
-    // Check whitelist
-    const whitelistResult = isWhitelisted(proc, config);
-    if (whitelistResult.protected) continue;
-
-    // Check maxOrphanAge if defined on the pattern
-    if (pattern.maxOrphanAge) {
-      const maxAge = parseDuration(pattern.maxOrphanAge);
-      if (maxAge && proc.age < maxAge) continue;
-    }
+    // If pattern requires orphan status and process isn't orphaned, skip
+    if (pattern.orphanOnly && !orphanResult.isOrphan && !sessionRelated) continue;
 
-    // Check memory threshold for node-ai-path pattern
-    if (pattern.memThreshold) {
-      const threshold = parseMemory(pattern.memThreshold);
-      const configThreshold = parseMemory(config.memoryThreshold);
-      // Use whichever is set — pattern threshold is the gate, but either can trigger
-      if (threshold && proc.mem < threshold) {
-        // Also check if age exceeds maxOrphanAge
-        if (pattern.maxOrphanAge) {
-          const maxAge = parseDuration(pattern.maxOrphanAge);
-          if (maxAge && proc.age < maxAge) continue;
-        } else {
-          continue;
-        }
+    if (sessionPid && !sessionRelated) {
+      if (orphanResult.isOrphan) {
+        session.unattributed++;
+      } else {
+        session.excluded++;
       }
+      continue;
     }
+    if (sessionRelated) session.matched++;
 
-    // Session affinity: if --session-pid was provided, prefer processes
-    // that were children of that session
-    if (opts.sessionPid) {
-      // Still include non-session orphans, but note affinity
-      proc.sessionRelated = isSessionRelated(proc.pid, opts.sessionPid);
-    }
+    // tmux/screen protection — but NOT for orphans (PPID=1).
+    // If a process is orphaned, it's already detached from any tmux session,
+    // so the multiplexer check is irrelevant. This fixes the tmux orphan bug.
+    if (!orphanResult.isOrphan && tree.hasAncestorMatching(proc.pid, isMultiplexer)) continue;
+
+    // Check whitelist (now tree-aware — no execSync)
+    const whitelistResult = isWhitelisted(proc, config, tree);
+    if (whitelistResult.protected) continue;
+
+    const threshold = evaluateThresholds(pattern, config, proc);
+    if (!threshold.passed) continue;
 
     // Build reason string
     const reasons = [];
     reasons.push(`pattern:${pattern.name}`);
+    if (sessionRelated) reasons.push(`session-pid:${sessionPid}`);
     if (orphanResult.isOrphan) reasons.push(`orphan:${orphanResult.reason}`);
-    if (proc.age > parseDuration(config.maxAge || '24h')) reasons.push('age-exceeded');
-    if (parseMemory(config.memoryThreshold) && proc.mem > parseMemory(config.memoryThreshold)) {
-      reasons.push('memory-exceeded');
-    }
+    if (threshold.ageExceeded) reasons.push('age-exceeded');
+    if (threshold.memoryExceeded) reasons.push('memory-exceeded');
 
     zombies.push({
       pid: proc.pid,
       name: pattern.name,
       cmd: proc.cmd,
-      ppid: proc.ppid,
-      mem: proc.mem,
+      ppid: orphanResult.ppid,
+      mem: proc.mem || 0,
       age: proc.age,
       startTime: proc.startTime,
       reason: reasons.join(', '),
@@ -92,205 +93,60 @@ function scan(config, opts = {}) {
     });
   }
 
-  return zombies;
-}
-
-/**
- * List all processes with their details.
- * Cross-platform: macOS/Linux use `ps`, Windows uses `wmic`.
- *
- * Returns array of { pid, cmd, mem, age, startTime }
- */
-function listProcesses() {
-  if (platform === 'win32') {
-    return listProcessesWindows();
-  }
-  return listProcessesUnix();
-}
-
-/**
- * Unix process listing via `ps aux`.
- */
-function listProcessesUnix() {
-  let output;
-  try {
-    // ps aux with etime for age calculation
-    // Columns: PID, RSS (KB), ELAPSED, STARTED, COMMAND
-    output = execSync('ps -eo pid=,rss=,etime=,lstart=,command=', {
-      encoding: 'utf-8',
-      timeout: 10000,
-      maxBuffer: 10 * 1024 * 1024,
+  if (session && session.unattributed > 0) {
+    warnings.push({
+      code: 'session-attribution-gap',
+      sessionPid,
+      count: session.unattributed,
+      message: `${session.unattributed} candidate process${session.unattributed === 1 ? '' : 'es'} could not be proven related to session PID ${sessionPid}`,
     });
-  } catch {
-    return [];
   }
 
-  const processes = [];
-  const lines = output.trim().split('\n');
-  const myPid = process.pid;
-
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-
-    // Parse the fixed-width fields
-    // Format: "  PID   RSS     ELAPSED             LSTART                    COMMAND"
-    const match = trimmed.match(
-      /^\s*(\d+)\s+(\d+)\s+([\d:.-]+)\s+\w+\s+(\w+\s+\d+\s+[\d:]+\s+\d+)\s+(.+)$/
-    );
-    if (!match) continue;
-
-    const pid = parseInt(match[1], 10);
-    const rssKB = parseInt(match[2], 10);
-    const elapsed = match[3];
-    const lstart = match[4];
-    const cmd = match[5];
-
-    // Skip our own process
-    if (pid === myPid) continue;
-
-    // Parse elapsed time (format: [[DD-]HH:]MM:SS)
-    const ageMs = parseElapsed(elapsed);
-
-    // Parse start time
-    let startTime = null;
-    try {
-      startTime = new Date(lstart).toISOString();
-    } catch {
-      // Ignore parse errors
-    }
-
-    processes.push({
-      pid,
-      cmd,
-      mem: rssKB * 1024, // Convert KB to bytes
-      age: ageMs,
-      startTime,
-    });
-  }
-
-  return processes;
+  return attachDiagnostics(zombies, { warnings, errors, session });
 }
 
-/**
- * Windows process listing via wmic.
- */
-function listProcessesWindows() {
-  let output;
-  try {
-    output = execSync(
-      'wmic process get ProcessId,CommandLine,WorkingSetSize,CreationDate /format:csv',
-      { encoding: 'utf-8', timeout: 15000, maxBuffer: 10 * 1024 * 1024 }
-    );
-  } catch {
-    return [];
-  }
-
-  const processes = [];
-  const lines = output.trim().split('\n');
-  const myPid = process.pid;
-
-  for (const line of lines) {
-    const parts = line.trim().split(',');
-    if (parts.length < 5) continue;
-
-    // CSV format: Node, CommandLine, CreationDate, ProcessId, WorkingSetSize
-    const cmd = parts[1];
-    const creationDate = parts[2];
-    const pid = parseInt(parts[3], 10);
-    const workingSet = parseInt(parts[4], 10);
-
-    if (isNaN(pid) || pid === myPid || !cmd) continue;
-
-    // Parse WMI datetime: YYYYMMDDHHMMSS.MMMMMM+UUU
-    let ageMs = 0;
-    let startTime = null;
-    if (creationDate) {
-      try {
-        const year = creationDate.substring(0, 4);
-        const month = creationDate.substring(4, 6);
-        const day = creationDate.substring(6, 8);
-        const hours = creationDate.substring(8, 10);
-        const minutes = creationDate.substring(10, 12);
-        const seconds = creationDate.substring(12, 14);
-        const dt = new Date(`${year}-${month}-${day}T${hours}:${minutes}:${seconds}`);
-        startTime = dt.toISOString();
-        ageMs = Date.now() - dt.getTime();
-      } catch {
-        // Ignore
-      }
-    }
-
-    processes.push({
-      pid,
-      cmd,
-      mem: workingSet || 0,
-      age: ageMs,
-      startTime,
-    });
-  }
-
-  return processes;
+function normalizePid(value) {
+  const pid = Number(value);
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
 }
 
-/**
- * Parse ps elapsed time format: [[DD-]HH:]MM:SS or DD-HH:MM:SS
- * Returns milliseconds.
- */
-function parseElapsed(elapsed) {
-  if (!elapsed) return 0;
-
-  let days = 0;
-  let rest = elapsed.trim();
-
-  // Check for "DD-" prefix
-  const dayMatch = rest.match(/^(\d+)-(.+)$/);
-  if (dayMatch) {
-    days = parseInt(dayMatch[1], 10);
-    rest = dayMatch[2];
-  }
-
-  const parts = rest.split(':').map((p) => parseInt(p, 10));
+function evaluateThresholds(pattern, config, proc) {
+  const maxAgeValue = getPatternMaxAge(pattern, config);
+  const memoryValue = getPatternMemoryThreshold(pattern, config);
+  const maxAge = maxAgeValue ? parseDuration(maxAgeValue) : null;
+  const memoryThreshold = memoryValue ? parseMemory(memoryValue) : null;
+  const ageExceeded = Boolean(maxAge && proc.age >= maxAge);
+  const memoryExceeded = Boolean(memoryThreshold && proc.mem >= memoryThreshold);
 
-  let hours = 0, minutes = 0, seconds = 0;
-  if (parts.length === 3) {
-    [hours, minutes, seconds] = parts;
-  } else if (parts.length === 2) {
-    [minutes, seconds] = parts;
-  } else if (parts.length === 1) {
-    [seconds] = parts;
+  if (maxAge && memoryThreshold) {
+    return { passed: ageExceeded || memoryExceeded, ageExceeded, memoryExceeded };
   }
-
-  return ((days * 24 + hours) * 3600 + minutes * 60 + seconds) * 1000;
+  if (maxAge) return { passed: ageExceeded, ageExceeded, memoryExceeded: false };
+  if (memoryThreshold) return { passed: memoryExceeded, ageExceeded: false, memoryExceeded };
+  return { passed: true, ageExceeded: false, memoryExceeded: false };
 }
 
-/**
- * Check if a process was a descendant of a given session PID.
- * Used for session-affinity cleanup.
- */
-function isSessionRelated(pid, sessionPid) {
-  if (platform === 'win32') return false;
-
-  const visited = new Set();
-  let currentPid = pid;
+function getPatternMaxAge(pattern, config) {
+  if (!pattern.maxOrphanAge) return null;
+  if (pattern.aiPathRequired && config.maxAge) return config.maxAge;
+  return pattern.maxOrphanAge;
+}
 
-  while (currentPid > 1 && !visited.has(currentPid)) {
-    visited.add(currentPid);
-    if (currentPid === sessionPid) return true;
+function getPatternMemoryThreshold(pattern, config) {
+  if (!pattern.memThreshold) return null;
+  return config.memoryThreshold || pattern.memThreshold;
+}
 
-    try {
-      const ppidStr = execSync(`ps -o ppid= -p ${currentPid}`, {
-        encoding: 'utf-8',
-        timeout: 3000,
-      }).trim();
-      currentPid = parseInt(ppidStr, 10);
-      if (isNaN(currentPid)) break;
-    } catch {
-      break;
-    }
-  }
+function attachDiagnostics(zombies, diagnostics) {
+  zombies.warnings = diagnostics.warnings || [];
+  zombies.errors = diagnostics.errors || [];
+  zombies.enumerationFailed = hasScanErrors(zombies);
+  if (diagnostics.session) zombies.session = diagnostics.session;
+  return zombies;
+}
 
-  return false;
+function hasScanErrors(result) {
+  return Array.isArray(result?.errors) && result.errors.length > 0;
 }
 
-module.exports = { scan, listProcesses, parseElapsed };
+module.exports = { scan, hasScanErrors };

package/src/windows-processes.js

@@ -0,0 +1,257 @@
+'use strict';
+
+function normalizePid(pid) {
+  const parsed = Number(pid);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+}
+
+function readWMICProcesses(runtime) {
+  let output;
+  try {
+    output = runtime.execSync(
+      'wmic process get ProcessId,ParentProcessId,CommandLine,WorkingSetSize,CreationDate /format:csv',
+      { encoding: 'utf-8', timeout: 15000, maxBuffer: 10 * 1024 * 1024 }
+    );
+  } catch (err) {
+    return {
+      processes: [],
+      warnings: [providerDiagnostic('wmic', 'process-enumeration-provider-failed', err)],
+    };
+  }
+
+  const processes = parseWMICOutput(String(output || ''), runtime);
+  return {
+    processes,
+    warnings: processes.length > 0 ? [] : [providerDiagnostic(
+      'wmic',
+      'process-enumeration-provider-empty',
+      'WMIC returned no process rows.'
+    )],
+  };
+}
+
+function readCIMProcesses(runtime) {
+  let output;
+  try {
+    output = runtime.execSync(
+      'powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -Command "Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,CommandLine,WorkingSetSize,CreationDate | ConvertTo-Json -Compress"',
+      { encoding: 'utf-8', timeout: 15000, maxBuffer: 10 * 1024 * 1024 }
+    );
+  } catch (err) {
+    return {
+      processes: [],
+      warnings: [providerDiagnostic('cim', 'process-enumeration-provider-failed', err)],
+    };
+  }
+
+  const processes = parseCIMOutput(String(output || ''), runtime);
+  return {
+    processes,
+    warnings: processes.length > 0 ? [] : [providerDiagnostic(
+      'cim',
+      'process-enumeration-provider-empty',
+      'CIM returned no process rows.'
+    )],
+  };
+}
+
+function readWindowsProcess(pid, runtime) {
+  const safePid = normalizePid(pid);
+  if (!safePid) return null;
+
+  let output;
+  try {
+    output = runtime.execSync(
+      `powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -Command "Get-CimInstance Win32_Process -Filter 'ProcessId = ${safePid}' | Select-Object ProcessId,CommandLine,CreationDate | ConvertTo-Json -Compress"`,
+      { encoding: 'utf-8', timeout: 5000, maxBuffer: 1024 * 1024 }
+    );
+  } catch {
+    return null;
+  }
+
+  const rows = parseJsonRows(String(output || ''));
+  const row = rows.find((item) => Number(readField(item, 'ProcessId')) === safePid);
+  if (!row) return null;
+
+  return {
+    pid: safePid,
+    cmd: String(readField(row, 'CommandLine') || ''),
+    startTime: parseWindowsDate(readField(row, 'CreationDate')),
+  };
+}
+
+function windowsProcessExists(pid, runtime) {
+  const safePid = normalizePid(pid);
+  if (!safePid) return false;
+
+  try {
+    const output = runtime.execSync(
+      `powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -Command "Get-CimInstance Win32_Process -Filter 'ProcessId = ${safePid}' | Select-Object ProcessId | ConvertTo-Json -Compress"`,
+      { encoding: 'utf-8', timeout: 3000, maxBuffer: 1024 * 1024 }
+    );
+    return parseJsonRows(String(output || '')).some((row) => Number(readField(row, 'ProcessId')) === safePid);
+  } catch {
+    return null;
+  }
+}
+
+function parseWMICOutput(output, runtime) {
+  const processes = [];
+  let headers = null;
+
+  for (const line of output.trim().split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+    const parts = parseCsvLine(trimmed);
+    if (!headers) {
+      headers = parts.map((h) => h.trim().toLowerCase());
+      continue;
+    }
+
+    if (parts.length < headers.length) continue;
+
+    const idx = (name) => headers.indexOf(name);
+    const col = (name) => (idx(name) >= 0 ? parts[idx(name)] : '');
+    const pid = Number(col('processid'));
+    const cmd = String(col('commandline') || '').trim();
+    if (!Number.isFinite(pid) || pid === runtime.currentPid || !cmd) continue;
+
+    processes.push(processFromWindowsFields({
+      pid,
+      ppid: Number(col('parentprocessid')),
+      cmd,
+      workingSet: Number(col('workingsetsize')),
+      creationDate: col('creationdate'),
+      runtime,
+    }));
+  }
+
+  return processes;
+}
+
+function parseCIMOutput(output, runtime) {
+  const rows = parseJsonRows(output);
+  const processes = [];
+
+  for (const row of rows) {
+    const pid = Number(readField(row, 'ProcessId'));
+    const cmd = String(readField(row, 'CommandLine') || '').trim();
+    if (!Number.isFinite(pid) || pid === runtime.currentPid || !cmd) continue;
+
+    processes.push(processFromWindowsFields({
+      pid,
+      ppid: Number(readField(row, 'ParentProcessId')),
+      cmd,
+      workingSet: Number(readField(row, 'WorkingSetSize')),
+      creationDate: readField(row, 'CreationDate'),
+      runtime,
+    }));
+  }
+
+  return processes;
+}
+
+function processFromWindowsFields(fields) {
+  const startTime = parseWindowsDate(fields.creationDate);
+  const startMs = startTime ? new Date(startTime).getTime() : 0;
+  const now = typeof fields.runtime.now === 'function' ? fields.runtime.now() : fields.runtime.now;
+
+  return {
+    pid: fields.pid,
+    ppid: Number.isFinite(fields.ppid) ? fields.ppid : 0,
+    cmd: fields.cmd,
+    mem: Number.isFinite(fields.workingSet) ? fields.workingSet : 0,
+    age: startMs && Number.isFinite(now) ? now - startMs : 0,
+    startTime,
+  };
+}
+
+function parseJsonRows(output) {
+  if (!output.trim()) return [];
+  try {
+    const parsed = JSON.parse(output);
+    if (Array.isArray(parsed)) return parsed;
+    if (parsed && typeof parsed === 'object') return [parsed];
+  } catch {
+    return [];
+  }
+  return [];
+}
+
+function parseWindowsDate(value) {
+  if (!value) return null;
+  const raw = String(value).trim();
+  if (!raw) return null;
+
+  if (/^\d{14}/.test(raw)) {
+    const year = raw.substring(0, 4);
+    const month = raw.substring(4, 6);
+    const day = raw.substring(6, 8);
+    const hours = raw.substring(8, 10);
+    const minutes = raw.substring(10, 12);
+    const seconds = raw.substring(12, 14);
+    const date = new Date(`${year}-${month}-${day}T${hours}:${minutes}:${seconds}`);
+    return Number.isNaN(date.getTime()) ? null : date.toISOString();
+  }
+
+  const date = new Date(raw);
+  return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+
+function readField(row, name) {
+  if (!row || typeof row !== 'object') return undefined;
+  if (Object.prototype.hasOwnProperty.call(row, name)) return row[name];
+
+  const lower = name.toLowerCase();
+  const key = Object.keys(row).find((candidate) => candidate.toLowerCase() === lower);
+  return key ? row[key] : undefined;
+}
+
+function parseCsvLine(line) {
+  const parts = [];
+  let current = '';
+  let quoted = false;
+
+  for (let i = 0; i < line.length; i += 1) {
+    const char = line[i];
+    if (char === '"') {
+      if (quoted && line[i + 1] === '"') {
+        current += '"';
+        i += 1;
+      } else {
+        quoted = !quoted;
+      }
+      continue;
+    }
+
+    if (char === ',' && !quoted) {
+      parts.push(current);
+      current = '';
+      continue;
+    }
+
+    current += char;
+  }
+
+  parts.push(current);
+  return parts;
+}
+
+function providerDiagnostic(provider, code, err) {
+  return {
+    code,
+    provider,
+    message: err instanceof Error ? err.message : String(err || ''),
+  };
+}
+
+module.exports = {
+  normalizePid,
+  readCIMProcesses,
+  readWMICProcesses,
+  readWindowsProcess,
+  windowsProcessExists,
+  parseCIMOutput,
+  parseWindowsDate,
+};