z-clean 0.1.1

package/src/detector/orphan.js

@@ -0,0 +1,149 @@
+'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
+ *
+ * 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.
+ */
+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' };
+}
+
+/**
+ * Windows orphan check — parent process doesn't exist.
+ */
+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' };
+  }
+}
+
+/**
+ * Check if a process is inside a tmux or screen session tree.
+ * Walks the process tree upward looking for tmux/screen ancestor.
+ *
+ * Returns true if the process has a tmux or screen ancestor.
+ */
+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;
+}
+
+module.exports = { checkOrphan, isInTerminalMultiplexer };

package/src/detector/patterns.js

@@ -0,0 +1,148 @@
+'use strict';
+
+/**
+ * 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)
+ */
+const PATTERNS = [
+  // MCP servers — any orphaned MCP server is suspect
+  {
+    name: 'mcp-server',
+    match: /mcp-server/,
+    minAge: 0,
+    maxOrphanAge: '1h',
+    orphanOnly: true,
+  },
+
+  // Headless browsers spawned by agents
+  {
+    name: 'agent-browser',
+    match: /agent-browser|chrome-headless-shell/,
+    minAge: 0,
+    orphanOnly: true,
+  },
+
+  // Playwright driver processes
+  {
+    name: 'playwright',
+    match: /playwright[/\\]driver/,
+    minAge: 0,
+    orphanOnly: true,
+  },
+
+  // Claude subagent processes
+  {
+    name: 'claude-subagent',
+    match: /claude\s+--print/,
+    minAge: 0,
+    orphanOnly: true,
+  },
+
+  // Codex exec processes
+  {
+    name: 'codex-exec',
+    match: /codex\s+exec/,
+    minAge: 0,
+    orphanOnly: true,
+  },
+
+  // Build tools — only if orphaned for 24h+
+  {
+    name: 'esbuild',
+    match: /esbuild/,
+    minAge: 0,
+    maxOrphanAge: '24h',
+    orphanOnly: true,
+  },
+  {
+    name: 'vite',
+    match: /vite/,
+    minAge: 0,
+    maxOrphanAge: '24h',
+    orphanOnly: true,
+  },
+  {
+    name: 'next-dev',
+    match: /next\s+dev/,
+    minAge: 0,
+    maxOrphanAge: '24h',
+    orphanOnly: true,
+  },
+  {
+    name: 'webpack',
+    match: /webpack/,
+    minAge: 0,
+    maxOrphanAge: '24h',
+    orphanOnly: true,
+  },
+
+  // npx/npm exec — orphaned
+  {
+    name: 'npm-exec',
+    match: /npm\s+exec|npx\s/,
+    minAge: 0,
+    orphanOnly: true,
+  },
+
+  // Node processes with AI tool paths — orphan + age/memory gated
+  {
+    name: 'node-ai-path',
+    match: /node\b.*(?:\.claude[/\\]|[/\\]mcp[/\\]|[/\\]agent[/\\])/,
+    minAge: 0,
+    maxOrphanAge: '24h',
+    memThreshold: '500MB',
+    orphanOnly: true,
+  },
+
+  // TypeScript runners — orphan + AI tool related
+  {
+    name: 'tsx',
+    match: /\btsx\b/,
+    minAge: 0,
+    maxOrphanAge: '24h',
+    orphanOnly: true,
+  },
+  {
+    name: 'ts-node',
+    match: /ts-node/,
+    minAge: 0,
+    maxOrphanAge: '24h',
+    orphanOnly: true,
+  },
+  {
+    name: 'bun',
+    match: /\bbun\b.*(?:\.claude|mcp|agent)/,
+    minAge: 0,
+    maxOrphanAge: '24h',
+    orphanOnly: true,
+  },
+  {
+    name: 'deno',
+    match: /\bdeno\b.*(?:\.claude|mcp|agent)/,
+    minAge: 0,
+    maxOrphanAge: '24h',
+    orphanOnly: true,
+  },
+];
+
+/**
+ * Match a command line against known patterns.
+ * Returns the first matching pattern or null.
+ */
+function matchPattern(cmdline) {
+  for (const pattern of PATTERNS) {
+    if (pattern.match.test(cmdline)) {
+      return pattern;
+    }
+  }
+  return null;
+}
+
+module.exports = { PATTERNS, matchPattern };

package/src/detector/whitelist.js

@@ -0,0 +1,178 @@
+'use strict';
+
+const { execSync } = require('child_process');
+const os = require('os');
+const fs = require('fs');
+
+const platform = os.platform();
+
+// Daemon managers that indicate intentionally long-running processes
+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)
+ *
+ * Returns { protected: boolean, reason: string }
+ */
+function isWhitelisted(proc, config) {
+  // 1. Config whitelist — match by PID or name substring
+  if (config.whitelist && config.whitelist.length > 0) {
+    for (const entry of config.whitelist) {
+      if (typeof entry === 'number' && proc.pid === entry) {
+        return { protected: true, reason: `config-whitelist-pid:${entry}` };
+      }
+      if (typeof entry === 'string' && proc.cmd.includes(entry)) {
+        return { protected: true, reason: `config-whitelist-pattern:${entry}` };
+      }
+    }
+  }
+
+  // 2. Daemon manager ancestor
+  if (hasDaemonAncestor(proc.pid)) {
+    return { protected: true, reason: 'daemon-managed' };
+  }
+
+  // 3. Docker container (Linux only)
+  if (isInDocker(proc.pid)) {
+    return { protected: true, reason: 'docker-container' };
+  }
+
+  // 4. nohup-launched
+  if (isNohup(proc.cmd)) {
+    return { protected: true, reason: 'nohup-launched' };
+  }
+
+  // 5. VS Code child with grace period
+  const vscodeGrace = 48 * 60 * 60 * 1000; // 48 hours
+  if (isVSCodeChild(proc.pid) && proc.age < vscodeGrace) {
+    return { protected: true, reason: 'vscode-child-grace' };
+  }
+
+  return { protected: false, reason: '' };
+}
+
+/**
+ * Walk process tree upward looking for daemon manager ancestors.
+ */
+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;
+}
+
+/**
+ * Check if a process is running inside a Docker container.
+ * Linux only: compares PID namespace with init (PID 1).
+ */
+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');
+    return procNs !== initNs;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if the command line suggests nohup launch.
+ */
+function isNohup(cmdline) {
+  return /\bnohup\b/.test(cmdline);
+}
+
+/**
+ * Check if a process is a child of VS Code.
+ */
+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;
+}
+
+module.exports = { isWhitelisted, hasDaemonAncestor, isInDocker, isNohup, isVSCodeChild };

package/src/installer/hook.js

@@ -0,0 +1,136 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+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';
+
+/**
+ * Install a Claude Code SessionEnd hook that runs zclean on session end.
+ *
+ * Claude Code hooks use a matcher + hooks array format:
+ * {
+ *   "hooks": {
+ *     "Stop": [
+ *       {
+ *         "matcher": "",
+ *         "hooks": [
+ *           { "type": "command", "command": "..." }
+ *         ]
+ *       }
+ *     ]
+ *   }
+ * }
+ *
+ * This is idempotent — won't duplicate if already registered.
+ *
+ * @returns {{ installed: boolean, message: string }}
+ */
+function installHook() {
+  // Check if Claude Code settings directory exists
+  const claudeDir = path.dirname(CLAUDE_SETTINGS_PATH);
+  if (!fs.existsSync(claudeDir)) {
+    return {
+      installed: false,
+      message: `Claude Code config directory not found: ${claudeDir}`,
+    };
+  }
+
+  // Load or create settings
+  let settings = {};
+  if (fs.existsSync(CLAUDE_SETTINGS_PATH)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(CLAUDE_SETTINGS_PATH, 'utf-8'));
+    } catch {
+      return {
+        installed: false,
+        message: `Failed to parse ${CLAUDE_SETTINGS_PATH}. Please fix the JSON and retry.`,
+      };
+    }
+  }
+
+  // Ensure hooks structure
+  if (!settings.hooks) settings.hooks = {};
+  if (!Array.isArray(settings.hooks.Stop)) settings.hooks.Stop = [];
+
+  // Check if already installed (handle both old flat format and new matcher format)
+  const existing = settings.hooks.Stop.find(
+    (h) =>
+      h.id === HOOK_ID ||
+      (h.command && h.command.includes('zclean')) ||
+      (Array.isArray(h.hooks) && h.hooks.some((sub) => sub.command && sub.command.includes('zclean')))
+  );
+  if (existing) {
+    return {
+      installed: true,
+      message: 'Hook already registered in Claude Code settings.',
+    };
+  }
+
+  // Add hook using the matcher + hooks array format required by Claude Code
+  settings.hooks.Stop.push({
+    matcher: '',
+    hooks: [
+      {
+        type: 'command',
+        command: HOOK_COMMAND,
+      },
+    ],
+  });
+
+  // Write back
+  fs.writeFileSync(CLAUDE_SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+
+  return {
+    installed: true,
+    message: `Hook registered: ${CLAUDE_SETTINGS_PATH}`,
+  };
+}
+
+/**
+ * Remove the zclean hook from Claude Code settings.
+ *
+ * @returns {{ removed: boolean, message: string }}
+ */
+function removeHook() {
+  if (!fs.existsSync(CLAUDE_SETTINGS_PATH)) {
+    return { removed: false, message: 'Claude Code settings not found.' };
+  }
+
+  let settings;
+  try {
+    settings = JSON.parse(fs.readFileSync(CLAUDE_SETTINGS_PATH, 'utf-8'));
+  } catch {
+    return { removed: false, message: 'Failed to parse settings.' };
+  }
+
+  if (!settings.hooks || !Array.isArray(settings.hooks.Stop)) {
+    return { removed: false, message: 'No hooks found.' };
+  }
+
+  const before = settings.hooks.Stop.length;
+  settings.hooks.Stop = settings.hooks.Stop.filter(
+    (h) =>
+      h.id !== HOOK_ID &&
+      !(h.command && h.command.includes('zclean')) &&
+      !(Array.isArray(h.hooks) && h.hooks.some((sub) => sub.command && sub.command.includes('zclean')))
+  );
+
+  if (settings.hooks.Stop.length === before) {
+    return { removed: false, message: 'Hook was not registered.' };
+  }
+
+  // Clean up empty structures
+  if (settings.hooks.Stop.length === 0) delete settings.hooks.Stop;
+  if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+
+  fs.writeFileSync(CLAUDE_SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+
+  return { removed: true, message: 'Hook removed from Claude Code settings.' };
+}
+
+module.exports = { installHook, removeHook };