z-clean 0.1.1

package/src/reporter.js

@@ -0,0 +1,220 @@
+'use strict';
+
+/**
+ * ANSI color codes — no external dependencies.
+ */
+const C = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  gray: '\x1b[90m',
+};
+
+// Disable colors if NO_COLOR env is set or not a TTY
+const useColor = !process.env.NO_COLOR && process.stdout.isTTY;
+
+function c(color, text) {
+  if (!useColor) return text;
+  return `${C[color]}${text}${C.reset}`;
+}
+
+function bold(text) {
+  if (!useColor) return text;
+  return `${C.bold}${text}${C.reset}`;
+}
+
+/**
+ * Format bytes into human-readable string.
+ */
+function formatBytes(bytes) {
+  if (bytes === 0) return '0 B';
+  const units = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  const val = (bytes / Math.pow(1024, i)).toFixed(i > 0 ? 1 : 0);
+  return `${val} ${units[i]}`;
+}
+
+/**
+ * Format milliseconds into human-readable duration.
+ */
+function formatDuration(ms) {
+  if (ms < 60000) return `${Math.floor(ms / 1000)}s`;
+  if (ms < 3600000) return `${Math.floor(ms / 60000)}m`;
+  if (ms < 86400000) {
+    const h = Math.floor(ms / 3600000);
+    const m = Math.floor((ms % 3600000) / 60000);
+    return m > 0 ? `${h}h ${m}m` : `${h}h`;
+  }
+  const d = Math.floor(ms / 86400000);
+  const h = Math.floor((ms % 86400000) / 3600000);
+  return h > 0 ? `${d}d ${h}h` : `${d}d`;
+}
+
+/**
+ * Truncate a string to maxLen, adding ellipsis if needed.
+ */
+function truncate(str, maxLen = 80) {
+  if (str.length <= maxLen) return str;
+  return str.substring(0, maxLen - 3) + '...';
+}
+
+/**
+ * Report dry-run scan results.
+ */
+function reportDryRun(zombies) {
+  if (zombies.length === 0) {
+    console.log(c('green', '  No zombie processes found. System is clean.'));
+    return;
+  }
+
+  console.log(bold(`\n  Found ${c('yellow', String(zombies.length))} zombie process${zombies.length === 1 ? '' : 'es'}:\n`));
+
+  const totalMem = zombies.reduce((sum, z) => sum + z.mem, 0);
+
+  for (const z of zombies) {
+    console.log(`  ${c('red', 'PID')} ${c('bold', String(z.pid).padStart(6))}  ${c('cyan', z.name.padEnd(16))}  ${c('yellow', formatBytes(z.mem).padStart(8))}  ${c('gray', formatDuration(z.age).padStart(6))}`);
+    console.log(`  ${c('gray', '  cmd:')} ${truncate(z.cmd, 72)}`);
+    console.log(`  ${c('gray', '  why:')} ${z.reason}`);
+    console.log();
+  }
+
+  console.log(c('yellow', `  Total memory reclaimable: ${formatBytes(totalMem)}`));
+  console.log(c('gray', `\n  Run ${c('white', 'zclean --yes')} to clean up these processes.\n`));
+}
+
+/**
+ * Report kill results.
+ */
+function reportKill(results) {
+  const { killed, failed, skipped } = results;
+
+  if (killed.length === 0 && failed.length === 0 && skipped.length === 0) {
+    console.log(c('green', '  No zombie processes to clean.'));
+    return;
+  }
+
+  console.log();
+
+  if (killed.length > 0) {
+    const totalMem = killed.reduce((sum, p) => sum + p.mem, 0);
+    console.log(c('green', `  Killed ${killed.length} zombie process${killed.length === 1 ? '' : 'es'}:`));
+    for (const p of killed) {
+      console.log(`    ${c('green', 'KILLED')} PID ${String(p.pid).padStart(6)}  ${p.name.padEnd(16)}  ${formatBytes(p.mem).padStart(8)}`);
+    }
+    console.log(c('green', `\n  Memory freed: ${formatBytes(totalMem)}`));
+  }
+
+  if (skipped.length > 0) {
+    console.log(c('yellow', `\n  Skipped ${skipped.length} (re-verification failed):`));
+    for (const p of skipped) {
+      console.log(`    ${c('yellow', 'SKIP')}   PID ${String(p.pid).padStart(6)}  ${p.name.padEnd(16)}  reason: ${p.skipReason}`);
+    }
+  }
+
+  if (failed.length > 0) {
+    console.log(c('red', `\n  Failed to kill ${failed.length}:`));
+    for (const p of failed) {
+      console.log(`    ${c('red', 'FAIL')}   PID ${String(p.pid).padStart(6)}  ${p.name.padEnd(16)}  error: ${p.error}`);
+    }
+  }
+
+  console.log();
+}
+
+/**
+ * Report current status (for `zclean status`).
+ */
+function reportStatus(zombies, logs) {
+  console.log(bold('\n  zclean status\n'));
+
+  // Current zombies
+  if (zombies.length === 0) {
+    console.log(c('green', '  Current zombies: 0'));
+  } else {
+    console.log(c('yellow', `  Current zombies: ${zombies.length}`));
+    const totalMem = zombies.reduce((sum, z) => sum + z.mem, 0);
+    console.log(c('yellow', `  Memory held:     ${formatBytes(totalMem)}`));
+  }
+
+  // Last cleanup
+  const lastCleanup = logs.filter((l) => l.action === 'cleanup-summary').pop();
+  if (lastCleanup) {
+    console.log(`  Last cleanup:    ${c('gray', lastCleanup.timestamp)}`);
+    console.log(`    Killed:        ${lastCleanup.killed}`);
+    console.log(`    Memory freed:  ${formatBytes(lastCleanup.totalMemFreed || 0)}`);
+  } else {
+    console.log(c('gray', '  Last cleanup:    never'));
+  }
+
+  console.log();
+}
+
+/**
+ * Report recent logs (for `zclean logs`).
+ */
+function reportLogs(logs) {
+  if (logs.length === 0) {
+    console.log(c('gray', '  No cleanup history yet.\n'));
+    return;
+  }
+
+  console.log(bold('\n  Recent cleanup history\n'));
+
+  for (const entry of logs.slice(-20)) {
+    const time = c('gray', entry.timestamp.replace('T', ' ').substring(0, 19));
+
+    switch (entry.action) {
+      case 'kill':
+        console.log(`  ${time}  ${c('green', 'KILL')}  PID ${String(entry.pid).padStart(6)}  ${(entry.name || '').padEnd(16)}  ${formatBytes(entry.memFreed || 0)}`);
+        break;
+      case 'kill-failed':
+        console.log(`  ${time}  ${c('red', 'FAIL')}  PID ${String(entry.pid).padStart(6)}  ${(entry.name || '').padEnd(16)}  ${entry.error || ''}`);
+        break;
+      case 'cleanup-summary':
+        console.log(`  ${time}  ${c('cyan', 'DONE')}  killed:${entry.killed} failed:${entry.failed} skipped:${entry.skipped}  freed:${formatBytes(entry.totalMemFreed || 0)}`);
+        break;
+      default:
+        console.log(`  ${time}  ${c('gray', entry.action)}`);
+    }
+  }
+
+  console.log();
+}
+
+/**
+ * Report current config (for `zclean config`).
+ */
+function reportConfig(config, configPath) {
+  console.log(bold('\n  zclean config\n'));
+  console.log(`  Config file: ${c('gray', configPath)}`);
+  console.log();
+
+  for (const [key, value] of Object.entries(config)) {
+    const displayValue = Array.isArray(value)
+      ? (value.length === 0 ? '[]' : JSON.stringify(value))
+      : String(value);
+    console.log(`  ${c('cyan', key.padEnd(20))} ${displayValue}`);
+  }
+
+  console.log();
+}
+
+module.exports = {
+  reportDryRun,
+  reportKill,
+  reportStatus,
+  reportLogs,
+  reportConfig,
+  formatBytes,
+  formatDuration,
+  C,
+  c,
+  bold,
+};

package/src/scanner.js

@@ -0,0 +1,296 @@
+'use strict';
+
+const { execSync } = require('child_process');
+const os = require('os');
+const { matchPattern } = require('./detector/patterns');
+const { checkOrphan, isInTerminalMultiplexer } = require('./detector/orphan');
+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 }
+ *
+ * @param {object} config — loaded zclean config
+ * @param {object} opts — { sessionPid?: number } for session-aware filtering
+ */
+function scan(config, opts = {}) {
+  const processes = listProcesses();
+  const zombies = [];
+
+  for (const proc of processes) {
+    // Match against known AI tool patterns
+    const pattern = matchPattern(proc.cmd);
+    if (!pattern) continue;
+
+    // Check orphan status
+    const orphanResult = checkOrphan(proc.pid);
+    proc.ppid = orphanResult.ppid;
+
+    // If pattern requires orphan status and process isn't orphaned, skip
+    if (pattern.orphanOnly && !orphanResult.isOrphan) continue;
+
+    // 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;
+    }
+
+    // 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;
+        }
+      }
+    }
+
+    // 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);
+    }
+
+    // Build reason string
+    const reasons = [];
+    reasons.push(`pattern:${pattern.name}`);
+    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');
+    }
+
+    zombies.push({
+      pid: proc.pid,
+      name: pattern.name,
+      cmd: proc.cmd,
+      ppid: proc.ppid,
+      mem: proc.mem,
+      age: proc.age,
+      startTime: proc.startTime,
+      reason: reasons.join(', '),
+      pattern: pattern.name,
+    });
+  }
+
+  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,
+    });
+  } 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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));
+
+  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;
+  }
+
+  return ((days * 24 + hours) * 3600 + minutes * 60 + seconds) * 1000;
+}
+
+/**
+ * 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;
+
+  while (currentPid > 1 && !visited.has(currentPid)) {
+    visited.add(currentPid);
+    if (currentPid === sessionPid) return true;
+
+    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;
+    }
+  }
+
+  return false;
+}
+
+module.exports = { scan, listProcesses, parseElapsed };