z-clean 0.1.1

package/src/installer/launchd.js

@@ -0,0 +1,166 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+const PLIST_NAME = 'com.zclean.hourly';
+const PLIST_DIR = path.join(os.homedir(), 'Library', 'LaunchAgents');
+const PLIST_PATH = path.join(PLIST_DIR, `${PLIST_NAME}.plist`);
+
+/**
+ * Resolve the full path to the zclean binary.
+ * Tries: npx global, npm global, local install.
+ */
+function resolveZcleanBin() {
+  // If installed globally via npm
+  try {
+    const npmBin = execSync('npm bin -g', { encoding: 'utf-8', timeout: 5000 }).trim();
+    const globalPath = path.join(npmBin, 'zclean');
+    if (fs.existsSync(globalPath)) return globalPath;
+  } catch { /* ignore */ }
+
+  // Check common locations
+  const candidates = [
+    path.join(os.homedir(), '.local', 'bin', 'zclean'),
+    '/usr/local/bin/zclean',
+    path.join(os.homedir(), 'node_modules', '.bin', 'zclean'),
+  ];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+
+  // Fallback to npx
+  return 'npx zclean';
+}
+
+/**
+ * Generate the launchd plist XML.
+ */
+function generatePlist(binPath) {
+  const parts = binPath.split(' ');
+  const programArgs = parts
+    .concat(['--yes'])
+    .map((arg) => `      <string>${arg}</string>`)
+    .join('\n');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${PLIST_NAME}</string>
+
+    <key>ProgramArguments</key>
+    <array>
+${programArgs}
+    </array>
+
+    <key>StartInterval</key>
+    <integer>3600</integer>
+
+    <key>RunAtLoad</key>
+    <false/>
+
+    <key>StandardOutPath</key>
+    <string>${path.join(os.homedir(), '.zclean', 'launchd.log')}</string>
+
+    <key>StandardErrorPath</key>
+    <string>${path.join(os.homedir(), '.zclean', 'launchd.log')}</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:${path.join(os.homedir(), '.local', 'bin')}</string>
+    </dict>
+</dict>
+</plist>
+`;
+}
+
+/**
+ * Install the launchd agent.
+ *
+ * @returns {{ installed: boolean, message: string }}
+ */
+function installLaunchd() {
+  if (os.platform() !== 'darwin') {
+    return { installed: false, message: 'launchd is macOS only.' };
+  }
+
+  // Ensure LaunchAgents directory exists
+  if (!fs.existsSync(PLIST_DIR)) {
+    fs.mkdirSync(PLIST_DIR, { recursive: true });
+  }
+
+  const binPath = resolveZcleanBin();
+  const plist = generatePlist(binPath);
+
+  // Unload existing if present
+  if (fs.existsSync(PLIST_PATH)) {
+    try {
+      execSync(`launchctl bootout gui/${process.getuid()} ${PLIST_PATH}`, {
+        encoding: 'utf-8',
+        timeout: 5000,
+      });
+    } catch {
+      // Might not be loaded
+    }
+  }
+
+  // Write plist
+  fs.writeFileSync(PLIST_PATH, plist, 'utf-8');
+
+  // Load
+  try {
+    execSync(`launchctl bootstrap gui/${process.getuid()} ${PLIST_PATH}`, {
+      encoding: 'utf-8',
+      timeout: 5000,
+    });
+  } catch (err) {
+    return {
+      installed: true,
+      message: `Plist written to ${PLIST_PATH} but launchctl load failed: ${err.message}. Try: launchctl bootstrap gui/$(id -u) ${PLIST_PATH}`,
+    };
+  }
+
+  return {
+    installed: true,
+    message: `Hourly launchd agent installed: ${PLIST_PATH}`,
+  };
+}
+
+/**
+ * Remove the launchd agent.
+ *
+ * @returns {{ removed: boolean, message: string }}
+ */
+function removeLaunchd() {
+  if (os.platform() !== 'darwin') {
+    return { removed: false, message: 'launchd is macOS only.' };
+  }
+
+  if (!fs.existsSync(PLIST_PATH)) {
+    return { removed: false, message: 'Plist not found. Already uninstalled.' };
+  }
+
+  try {
+    execSync(`launchctl bootout gui/${process.getuid()} ${PLIST_PATH}`, {
+      encoding: 'utf-8',
+      timeout: 5000,
+    });
+  } catch {
+    // Might not be loaded
+  }
+
+  fs.unlinkSync(PLIST_PATH);
+
+  return {
+    removed: true,
+    message: `launchd agent removed: ${PLIST_PATH}`,
+  };
+}
+
+module.exports = { installLaunchd, removeLaunchd, PLIST_PATH };

package/src/installer/systemd.js

@@ -0,0 +1,162 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+const SYSTEMD_USER_DIR = path.join(os.homedir(), '.config', 'systemd', 'user');
+const SERVICE_NAME = 'zclean';
+const SERVICE_PATH = path.join(SYSTEMD_USER_DIR, `${SERVICE_NAME}.service`);
+const TIMER_PATH = path.join(SYSTEMD_USER_DIR, `${SERVICE_NAME}.timer`);
+
+/**
+ * Resolve the full path to the zclean binary.
+ */
+function resolveZcleanBin() {
+  try {
+    const npmBin = execSync('npm bin -g', { encoding: 'utf-8', timeout: 5000 }).trim();
+    const globalPath = path.join(npmBin, 'zclean');
+    if (fs.existsSync(globalPath)) return globalPath;
+  } catch { /* ignore */ }
+
+  const candidates = [
+    path.join(os.homedir(), '.local', 'bin', 'zclean'),
+    '/usr/local/bin/zclean',
+    path.join(os.homedir(), '.local', 'share', 'npm', 'bin', 'zclean'),
+  ];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+
+  return path.join(os.homedir(), '.local', 'bin', 'zclean');
+}
+
+/**
+ * Generate the systemd service unit file.
+ */
+function generateService(binPath) {
+  return `[Unit]
+Description=zclean - AI coding tool zombie process cleaner
+Documentation=https://github.com/whynowlab/zclean
+
+[Service]
+Type=oneshot
+ExecStart=${binPath} --yes
+Environment=PATH=/usr/local/bin:/usr/bin:/bin:%h/.local/bin
+StandardOutput=append:%h/.zclean/systemd.log
+StandardError=append:%h/.zclean/systemd.log
+`;
+}
+
+/**
+ * Generate the systemd timer unit file.
+ */
+function generateTimer() {
+  return `[Unit]
+Description=Run zclean hourly
+Documentation=https://github.com/whynowlab/zclean
+
+[Timer]
+OnCalendar=hourly
+Persistent=true
+RandomizedDelaySec=300
+
+[Install]
+WantedBy=timers.target
+`;
+}
+
+/**
+ * Install the systemd user timer.
+ *
+ * @returns {{ installed: boolean, message: string }}
+ */
+function installSystemd() {
+  if (os.platform() !== 'linux') {
+    return { installed: false, message: 'systemd is Linux only.' };
+  }
+
+  // Ensure systemd user directory exists
+  if (!fs.existsSync(SYSTEMD_USER_DIR)) {
+    fs.mkdirSync(SYSTEMD_USER_DIR, { recursive: true });
+  }
+
+  const binPath = resolveZcleanBin();
+
+  // Write service and timer files
+  fs.writeFileSync(SERVICE_PATH, generateService(binPath), 'utf-8');
+  fs.writeFileSync(TIMER_PATH, generateTimer(), 'utf-8');
+
+  // Reload and enable
+  const messages = [];
+  try {
+    execSync('systemctl --user daemon-reload', { encoding: 'utf-8', timeout: 5000 });
+    execSync(`systemctl --user enable --now ${SERVICE_NAME}.timer`, {
+      encoding: 'utf-8',
+      timeout: 5000,
+    });
+    messages.push(`Timer installed and enabled: ${TIMER_PATH}`);
+  } catch (err) {
+    messages.push(`Files written but systemctl failed: ${err.message}`);
+    messages.push(`Try manually: systemctl --user enable --now ${SERVICE_NAME}.timer`);
+  }
+
+  // Check linger
+  try {
+    const lingerDir = `/var/lib/systemd/linger/${os.userInfo().username}`;
+    if (!fs.existsSync(lingerDir)) {
+      messages.push(`Note: enable linger for timer to run without login: loginctl enable-linger ${os.userInfo().username}`);
+    }
+  } catch {
+    messages.push(`Note: run 'loginctl enable-linger' to ensure timer runs without login session.`);
+  }
+
+  return {
+    installed: true,
+    message: messages.join('\n'),
+  };
+}
+
+/**
+ * Remove the systemd user timer and service.
+ *
+ * @returns {{ removed: boolean, message: string }}
+ */
+function removeSystemd() {
+  if (os.platform() !== 'linux') {
+    return { removed: false, message: 'systemd is Linux only.' };
+  }
+
+  // Disable timer
+  try {
+    execSync(`systemctl --user disable --now ${SERVICE_NAME}.timer`, {
+      encoding: 'utf-8',
+      timeout: 5000,
+    });
+  } catch {
+    // Might not be running
+  }
+
+  // Remove files
+  let removed = false;
+  for (const filepath of [SERVICE_PATH, TIMER_PATH]) {
+    if (fs.existsSync(filepath)) {
+      fs.unlinkSync(filepath);
+      removed = true;
+    }
+  }
+
+  // Reload daemon
+  try {
+    execSync('systemctl --user daemon-reload', { encoding: 'utf-8', timeout: 5000 });
+  } catch { /* ignore */ }
+
+  return {
+    removed,
+    message: removed ? 'systemd timer and service removed.' : 'Files not found. Already uninstalled.',
+  };
+}
+
+module.exports = { installSystemd, removeSystemd, SERVICE_PATH, TIMER_PATH };

package/src/installer/taskscheduler.js

@@ -0,0 +1,102 @@
+'use strict';
+
+const { execSync } = require('child_process');
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+
+const TASK_NAME = 'zclean-hourly';
+
+/**
+ * Resolve the full path to the zclean binary on Windows.
+ */
+function resolveZcleanBin() {
+  // Check npm global
+  try {
+    const npmPrefix = execSync('npm prefix -g', { encoding: 'utf-8', timeout: 5000 }).trim();
+    const candidate = path.join(npmPrefix, 'zclean.cmd');
+    if (fs.existsSync(candidate)) return candidate;
+    const candidate2 = path.join(npmPrefix, 'node_modules', '.bin', 'zclean.cmd');
+    if (fs.existsSync(candidate2)) return candidate2;
+  } catch { /* ignore */ }
+
+  // Check AppData local
+  const appData = process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming');
+  const npmGlobal = path.join(appData, 'npm', 'zclean.cmd');
+  if (fs.existsSync(npmGlobal)) return npmGlobal;
+
+  return 'npx zclean';
+}
+
+/**
+ * Install a Windows Task Scheduler hourly task.
+ *
+ * Uses `schtasks /create` with user-scoped hourly task.
+ *
+ * @returns {{ installed: boolean, message: string }}
+ */
+function installTaskScheduler() {
+  if (os.platform() !== 'win32') {
+    return { installed: false, message: 'Task Scheduler is Windows only.' };
+  }
+
+  const binPath = resolveZcleanBin();
+
+  // Build schtasks command
+  // /SC HOURLY — run every hour
+  // /TN — task name
+  // /TR — task to run
+  // /F — force overwrite if exists
+  const command = [
+    'schtasks', '/create',
+    '/TN', `"${TASK_NAME}"`,
+    '/SC', 'HOURLY',
+    '/TR', `"${binPath} --yes"`,
+    '/F',
+  ].join(' ');
+
+  try {
+    execSync(command, { encoding: 'utf-8', timeout: 10000 });
+    return {
+      installed: true,
+      message: `Task Scheduler task created: ${TASK_NAME} (hourly)`,
+    };
+  } catch (err) {
+    return {
+      installed: false,
+      message: `Failed to create scheduled task: ${err.message}\nTry running as administrator.`,
+    };
+  }
+}
+
+/**
+ * Remove the Windows Task Scheduler task.
+ *
+ * @returns {{ removed: boolean, message: string }}
+ */
+function removeTaskScheduler() {
+  if (os.platform() !== 'win32') {
+    return { removed: false, message: 'Task Scheduler is Windows only.' };
+  }
+
+  try {
+    execSync(`schtasks /delete /TN "${TASK_NAME}" /F`, {
+      encoding: 'utf-8',
+      timeout: 10000,
+    });
+    return {
+      removed: true,
+      message: `Task Scheduler task removed: ${TASK_NAME}`,
+    };
+  } catch (err) {
+    if (err.message.includes('does not exist') || err.message.includes('ERROR')) {
+      return { removed: false, message: 'Task not found. Already uninstalled.' };
+    }
+    return {
+      removed: false,
+      message: `Failed to remove task: ${err.message}`,
+    };
+  }
+}
+
+module.exports = { installTaskScheduler, removeTaskScheduler, TASK_NAME };

package/src/killer.js

@@ -0,0 +1,248 @@
+'use strict';
+
+const { execSync } = require('child_process');
+const os = require('os');
+const { appendLog } = require('./config');
+
+const platform = os.platform();
+
+/**
+ * Safely kill a list of zombie processes.
+ *
+ * Before killing each process, re-verifies:
+ *   1. PID still exists
+ *   2. Process start time matches scan time
+ *   3. Command line matches scan
+ *
+ * Kill sequence:
+ *   macOS/Linux: SIGTERM -> wait -> SIGKILL
+ *   Windows: taskkill -> wait -> taskkill /F
+ *
+ * @param {Array} zombies — array from scanner.scan()
+ * @param {object} config — loaded config
+ * @returns {{ killed: Array, failed: Array, skipped: Array }}
+ */
+function killZombies(zombies, config) {
+  const timeout = (config.sigterm_timeout || 10) * 1000;
+  const results = { killed: [], failed: [], skipped: [] };
+
+  for (const proc of zombies) {
+    // Re-verify before killing
+    const verification = verifyProcess(proc);
+    if (!verification.valid) {
+      results.skipped.push({
+        ...proc,
+        skipReason: verification.reason,
+      });
+      continue;
+    }
+
+    // Attempt kill
+    const killResult = killProcess(proc.pid, timeout);
+
+    if (killResult.success) {
+      results.killed.push(proc);
+      // Log for manual recovery
+      appendLog({
+        action: 'kill',
+        pid: proc.pid,
+        name: proc.name,
+        cmd: proc.cmd,
+        reason: proc.reason,
+        memFreed: proc.mem,
+      });
+    } else {
+      results.failed.push({
+        ...proc,
+        error: killResult.error,
+      });
+      appendLog({
+        action: 'kill-failed',
+        pid: proc.pid,
+        name: proc.name,
+        cmd: proc.cmd,
+        error: killResult.error,
+      });
+    }
+  }
+
+  // Log summary
+  appendLog({
+    action: 'cleanup-summary',
+    total: zombies.length,
+    killed: results.killed.length,
+    failed: results.failed.length,
+    skipped: results.skipped.length,
+    totalMemFreed: results.killed.reduce((sum, p) => sum + p.mem, 0),
+  });
+
+  return results;
+}
+
+/**
+ * Re-verify a process before killing it.
+ * Ensures we don't kill a recycled PID or wrong process.
+ */
+function verifyProcess(proc) {
+  if (platform === 'win32') {
+    return verifyProcessWindows(proc);
+  }
+  return verifyProcessUnix(proc);
+}
+
+function verifyProcessUnix(proc) {
+  try {
+    // Check if PID still exists and get its command line
+    const cmd = execSync(`ps -o command= -p ${proc.pid}`, {
+      encoding: 'utf-8',
+      timeout: 5000,
+    }).trim();
+
+    if (!cmd) {
+      return { valid: false, reason: 'process-gone' };
+    }
+
+    // Verify command line matches (at least partially)
+    // Use first 50 chars to handle truncation
+    const scanPrefix = proc.cmd.substring(0, 50);
+    const currentPrefix = cmd.substring(0, 50);
+    if (scanPrefix !== currentPrefix) {
+      return { valid: false, reason: 'cmd-mismatch' };
+    }
+
+    // Verify start time if available
+    if (proc.startTime) {
+      try {
+        const lstart = execSync(`ps -o lstart= -p ${proc.pid}`, {
+          encoding: 'utf-8',
+          timeout: 5000,
+        }).trim();
+        const currentStart = new Date(lstart).toISOString();
+        if (currentStart !== proc.startTime) {
+          return { valid: false, reason: 'start-time-mismatch' };
+        }
+      } catch {
+        // Can't verify start time — proceed with caution
+      }
+    }
+
+    return { valid: true, reason: 'verified' };
+  } catch {
+    return { valid: false, reason: 'process-gone' };
+  }
+}
+
+function verifyProcessWindows(proc) {
+  try {
+    const output = execSync(
+      `wmic process where ProcessId=${proc.pid} get CommandLine /value`,
+      { encoding: 'utf-8', timeout: 5000 }
+    ).trim();
+
+    const match = output.match(/CommandLine=(.+)/);
+    if (!match) {
+      return { valid: false, reason: 'process-gone' };
+    }
+
+    const currentCmd = match[1].trim();
+    const scanPrefix = proc.cmd.substring(0, 50);
+    const currentPrefix = currentCmd.substring(0, 50);
+
+    if (scanPrefix !== currentPrefix) {
+      return { valid: false, reason: 'cmd-mismatch' };
+    }
+
+    return { valid: true, reason: 'verified' };
+  } catch {
+    return { valid: false, reason: 'process-gone' };
+  }
+}
+
+/**
+ * Kill a process with graceful shutdown sequence.
+ *
+ * macOS/Linux: SIGTERM → wait → SIGKILL
+ * Windows: taskkill → wait → taskkill /F
+ */
+function killProcess(pid, timeoutMs) {
+  if (platform === 'win32') {
+    return killProcessWindows(pid, timeoutMs);
+  }
+  return killProcessUnix(pid, timeoutMs);
+}
+
+function killProcessUnix(pid, timeoutMs) {
+  try {
+    // Send SIGTERM
+    process.kill(pid, 'SIGTERM');
+  } catch (err) {
+    if (err.code === 'ESRCH') {
+      // Already dead
+      return { success: true, method: 'already-dead' };
+    }
+    return { success: false, error: `SIGTERM failed: ${err.message}` };
+  }
+
+  // Wait for graceful shutdown
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      // process.kill(pid, 0) throws if process doesn't exist
+      process.kill(pid, 0);
+      // Still alive — busy wait in small increments
+      const waitUntil = Date.now() + 500;
+      while (Date.now() < waitUntil) {
+        // Spin wait — we can't use setTimeout synchronously
+      }
+    } catch {
+      // Process is gone
+      return { success: true, method: 'sigterm' };
+    }
+  }
+
+  // Process survived SIGTERM — send SIGKILL
+  try {
+    process.kill(pid, 'SIGKILL');
+    return { success: true, method: 'sigkill' };
+  } catch (err) {
+    if (err.code === 'ESRCH') {
+      return { success: true, method: 'died-during-kill' };
+    }
+    return { success: false, error: `SIGKILL failed: ${err.message}` };
+  }
+}
+
+function killProcessWindows(pid, timeoutMs) {
+  try {
+    // Graceful kill
+    execSync(`taskkill /PID ${pid}`, { encoding: 'utf-8', timeout: 5000 });
+  } catch {
+    // Might fail — try force kill directly
+  }
+
+  // Wait
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      execSync(`wmic process where ProcessId=${pid} get ProcessId /value`, {
+        encoding: 'utf-8',
+        timeout: 3000,
+      });
+      // Still alive — wait
+      const waitUntil = Date.now() + 500;
+      while (Date.now() < waitUntil) { /* spin */ }
+    } catch {
+      return { success: true, method: 'taskkill' };
+    }
+  }
+
+  // Force kill
+  try {
+    execSync(`taskkill /F /PID ${pid}`, { encoding: 'utf-8', timeout: 5000 });
+    return { success: true, method: 'taskkill-force' };
+  } catch (err) {
+    return { success: false, error: `Force kill failed: ${err.message}` };
+  }
+}
+
+module.exports = { killZombies, verifyProcess, killProcess };