z-clean 0.1.1 → 0.3.0

package/bin/zclean.js

@@ -2,11 +2,25 @@
 'use strict';
 
 const os = require('os');
-const { scan } = require('../src/scanner');
+const { scan, hasScanErrors } = require('../src/scanner');
 const { killZombies } = require('../src/killer');
-const { loadConfig, saveConfig, readLogs, pruneLogs, CONFIG_FILE, DEFAULT_CONFIG, appendLog } = require('../src/config');
+const {
+  loadConfig,
+  saveConfig,
+  readLogs,
+  pruneLogs,
+  DEFAULT_CONFIG,
+  appendLog,
+  getCumulativeStats,
+  getConfigFile,
+} = require('../src/config');
 const { reportDryRun, reportKill, reportStatus, reportLogs, reportConfig, c, bold } = require('../src/reporter');
 const { installHook, removeHook } = require('../src/installer/hook');
+const { runHistory, runProtect } = require('../src/commands/trust');
+const { installScheduler, uninstallScheduler } = require('../src/commands/scheduler');
+const { runDoctor } = require('../src/doctor');
+const { runAudit } = require('../src/audit');
+const { runCache } = require('../src/cache');
 
 // Platform-specific installers (lazy loaded)
 const platform = os.platform();
@@ -58,12 +72,30 @@ async function main() {
     case 'logs':
       return cmdLogs(config);
 
+    case 'history':
+      return runHistory(flags);
+
+    case 'protect':
+      return runProtect(config, flags, positional);
+
     case 'uninstall':
       return cmdUninstall();
 
     case 'config':
       return cmdConfig(config);
 
+    case 'doctor':
+      return cmdDoctor(config);
+
+    case 'report':
+      return cmdAudit(config, 'report');
+
+    case 'audit':
+      return cmdAudit(config, 'audit');
+
+    case 'cache':
+      return cmdCache();
+
     case null:
       // Default: scan (dry-run unless --yes)
       return cmdScan(config);
@@ -82,13 +114,21 @@ async function main() {
  * Dry-run unless --yes is passed.
  */
 function cmdScan(config) {
-  const sessionPid = flags['session-pid'] ? parseInt(flags['session-pid'], 10) : null;
+  const sessionPid = parseSessionPidFlag();
   const force = flags.yes || flags.y;
 
   console.log(bold('\n  zclean') + c('gray', ' — scanning for zombie processes...\n'));
 
   const zombies = scan(config, { sessionPid });
 
+  if (hasScanErrors(zombies)) {
+    reportDryRun(zombies);
+    appendLog({ action: 'scan-failed', errors: zombies.errors.length });
+    pruneLogs(config);
+    process.exitCode = 1;
+    return;
+  }
+
   if (force) {
     // Kill mode
     if (zombies.length === 0) {
@@ -98,9 +138,13 @@ function cmdScan(config) {
     }
     appendLog({ action: 'scan', found: zombies.length });
     const results = killZombies(zombies, config);
+    results.cumulative = getCumulativeStats();
     reportKill(results);
   } else {
     // Dry-run mode
+    if (config.dryRunDefault === false) {
+      console.log(c('yellow', '  dryRunDefault=false is not an auto-kill switch; pass --yes to clean.\n'));
+    }
     reportDryRun(zombies);
     if (zombies.length > 0) {
       appendLog({ action: 'dry-run', found: zombies.length });
@@ -121,9 +165,9 @@ function cmdInit(config) {
   const existingConfig = loadConfig();
   if (JSON.stringify(existingConfig) === JSON.stringify(DEFAULT_CONFIG)) {
     saveConfig(DEFAULT_CONFIG);
-    console.log(c('green', '  Config created:') + ` ${CONFIG_FILE}`);
+    console.log(c('green', '  Config created:') + ` ${getConfigFile()}`);
   } else {
-    console.log(c('gray', '  Config exists:') + ` ${CONFIG_FILE}`);
+    console.log(c('gray', '  Config exists:') + ` ${getConfigFile()}`);
   }
 
   // 2. Install Claude Code hook
@@ -132,7 +176,7 @@ function cmdInit(config) {
   console.log(`${hookIcon} ${hookResult.message}`);
 
   // 3. Install platform-specific scheduler
-  installScheduler();
+  installScheduler(platform);
 
   console.log();
 }
@@ -144,6 +188,7 @@ function cmdStatus(config) {
   const zombies = scan(config);
   const logs = readLogs(100);
   reportStatus(zombies, logs);
+  if (hasScanErrors(zombies)) process.exitCode = 1;
 }
 
 /**
@@ -165,7 +210,7 @@ function cmdUninstall() {
   console.log(`  Hook: ${hookResult.message}`);
 
   // Remove scheduler
-  uninstallScheduler();
+  uninstallScheduler(platform);
 
   console.log(c('gray', `\n  Config and logs preserved at ~/.zclean/`));
   console.log(c('gray', `  To fully remove: rm -rf ~/.zclean\n`));
@@ -175,69 +220,48 @@ function cmdUninstall() {
  * config: Show current config.
  */
 function cmdConfig(config) {
-  reportConfig(config, CONFIG_FILE);
+  reportConfig(config, getConfigFile());
 }
 
-// ─── Platform Scheduler Install/Uninstall ───────────────────────────────────
+/**
+ * doctor: Self-diagnosis — check if zclean is properly set up and running.
+ */
+function cmdDoctor(config) {
+  const report = runDoctor(config, { json: Boolean(flags.json) });
+  if (report.exitCode !== 0) process.exitCode = report.exitCode;
+}
 
-function installScheduler() {
-  switch (platform) {
-    case 'darwin': {
-      const { installLaunchd } = require('../src/installer/launchd');
-      const result = installLaunchd();
-      const icon = result.installed ? c('green', '  Scheduler:') : c('yellow', '  Scheduler:');
-      console.log(`${icon} ${result.message}`);
-      break;
-    }
-    case 'linux': {
-      const { installSystemd } = require('../src/installer/systemd');
-      const result = installSystemd();
-      const icon = result.installed ? c('green', '  Scheduler:') : c('yellow', '  Scheduler:');
-      console.log(`${icon} ${result.message}`);
-      break;
-    }
-    case 'win32': {
-      const { installTaskScheduler } = require('../src/installer/taskscheduler');
-      const result = installTaskScheduler();
-      const icon = result.installed ? c('green', '  Scheduler:') : c('yellow', '  Scheduler:');
-      console.log(`${icon} ${result.message}`);
-      break;
-    }
-    default:
-      console.log(c('yellow', `  Scheduler: Unsupported platform (${platform}). Install a cron job manually.`));
-  }
+function cmdAudit(config, commandName = 'audit') {
+  const sessionPid = parseSessionPidFlag();
+  const report = runAudit(config, { json: Boolean(flags.json), sessionPid, commandName });
+  if (!report.risk.enumerationComplete) process.exitCode = 1;
 }
 
-function uninstallScheduler() {
-  switch (platform) {
-    case 'darwin': {
-      const { removeLaunchd } = require('../src/installer/launchd');
-      const result = removeLaunchd();
-      console.log(`  Scheduler: ${result.message}`);
-      break;
-    }
-    case 'linux': {
-      const { removeSystemd } = require('../src/installer/systemd');
-      const result = removeSystemd();
-      console.log(`  Scheduler: ${result.message}`);
-      break;
-    }
-    case 'win32': {
-      const { removeTaskScheduler } = require('../src/installer/taskscheduler');
-      const result = removeTaskScheduler();
-      console.log(`  Scheduler: ${result.message}`);
-      break;
-    }
-    default:
-      console.log(c('yellow', `  Scheduler: Remove manually for ${platform}.`));
+function cmdCache() {
+  runCache({
+    root: typeof flags.path === 'string' ? flags.path : process.cwd(),
+    yes: Boolean(flags.yes || flags.y),
+    json: Boolean(flags.json),
+  });
+}
+
+function parseSessionPidFlag() {
+  if (flags['session-pid'] === undefined) return null;
+  if (flags['session-pid'] === true || flags['session-pid'] === '') {
+    console.error(c('red', '  --session-pid must be a positive integer'));
+    process.exit(1);
   }
+  const pid = Number(flags['session-pid']);
+  if (Number.isInteger(pid) && pid > 0) return pid;
+  console.error(c('red', '  --session-pid must be a positive integer'));
+  process.exit(1);
 }
 
 // ─── Help ───────────────────────────────────────────────────────────────────
 
 function printHelp() {
   console.log(`
-  ${bold('zclean')} — Automatic zombie process cleaner for AI coding tools
+  ${bold('zclean')} — AI coding runtime hygiene for agent sessions
 
   ${bold('Usage:')}
     zclean                Scan for zombies (dry-run)
@@ -245,19 +269,31 @@ function printHelp() {
     zclean init           Install hooks + scheduler
     zclean status         Show current zombies and last cleanup
     zclean logs           Show recent cleanup history
+    zclean history [--json]       Show cleanup history
+    zclean protect list [--json]  Show protected whitelist entries
+    zclean protect add <entry>    Add a whitelist entry
+    zclean protect remove <entry|--index=N>
+                          Remove a whitelist entry
     zclean uninstall      Remove hooks + scheduler
     zclean config         Show current configuration
+    zclean doctor [--json]        Check if zclean is properly set up
+    zclean report [--json] Show AI runtime hygiene report
+    zclean audit [--json]  Alias for report
+    zclean cache [--json]  Show safe workspace cache candidates
+    zclean cache --yes     Remove supported workspace cache directories
 
   ${bold('Options:')}
     --yes, -y             Kill found zombies (default: dry-run)
     --session-pid=PID     Filter by parent session PID
+    --path=DIR            Workspace path for zclean cache
+    --json                Print machine-readable output for supported commands
     --version, -v         Show version
     --help, -h            Show this help
 
   ${bold('Config:')}  ~/.zclean/config.json
   ${bold('Logs:')}    ~/.zclean/history.jsonl
 
-  ${bold('Docs:')}    https://github.com/whynowlab/zclean
+  ${bold('Docs:')}    https://github.com/TheStack-ai/zclean
 `);
 }
 

package/package.json

@@ -1,12 +1,49 @@
 {
   "name": "z-clean",
-  "version": "0.1.1",
-  "description": "Automatic zombie process cleaner for AI coding tools (Claude Code, Codex)",
-  "bin": { "zclean": "./bin/zclean.js" },
-  "keywords": ["claude-code", "codex", "cleanup", "zombie", "orphan", "process", "ai-tools", "mcp"],
-  "author": "whynowlab",
+  "version": "0.3.0",
+  "description": "AI coding runtime hygiene reports, zombie cleanup, and safe workspace cache cleanup",
+  "bin": {
+    "zclean": "bin/zclean.js"
+  },
+  "scripts": {
+    "test": "node --test test/patterns.test.js test/scanner.test.js test/process-tree.test.js test/killer.test.js test/config.test.js test/installer-fallback.test.js test/cli.test.js test/cli-history-protect.test.js test/cli-doctor.test.js test/audit.test.js test/cache.test.js",
+    "syntax": "node -e \"const fs=require('node:fs');const path=require('node:path');const {execFileSync}=require('node:child_process');const files=['bin/zclean.js'];function walk(dir){if(!fs.existsSync(dir))return;for(const entry of fs.readdirSync(dir,{withFileTypes:true})){const file=path.join(dir,entry.name);if(entry.isDirectory())walk(file);else if(entry.name.endsWith('.js'))files.push(file);}}for(const dir of ['src','test','scripts'])walk(dir);for(const file of files)execFileSync(process.execPath,['-c',file],{stdio:'inherit'});\"",
+    "smoke": "node scripts/smoke.js",
+    "pack:check": "npm pack --dry-run --json"
+  },
+  "keywords": [
+    "claude-code",
+    "codex",
+    "cleanup",
+    "zombie",
+    "orphan",
+    "process",
+    "ai-tools",
+    "mcp",
+    "cache-cleaner",
+    "developer-tools",
+    "ai-coding"
+  ],
+  "author": "TheStack-ai",
   "license": "MIT",
-  "repository": { "type": "git", "url": "https://github.com/whynowlab/zclean.git" },
-  "engines": { "node": ">=18" },
-  "files": ["bin/", "src/", "LICENSE", "README.md"]
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TheStack-ai/zclean.git"
+  },
+  "bugs": {
+    "url": "https://github.com/TheStack-ai/zclean/issues"
+  },
+  "homepage": "https://github.com/TheStack-ai/zclean#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "assets/zclean-hero.png",
+    "LICENSE",
+    "README.md",
+    "README.ko.md",
+    "README.zh.md"
+  ]
 }

package/src/audit-actions.js

@@ -0,0 +1,88 @@
+'use strict';
+
+function buildRecommendations({ zombieCount, errors, warnings, commandName }) {
+  if (errors.length > 0) {
+    return [
+      'Run `zclean doctor` before cleaning; process enumeration is incomplete.',
+      `Do not trust a zero-candidate ${commandName} until enumeration errors are resolved.`,
+    ];
+  }
+
+  const recommendations = [
+    'Review candidates before cleanup. Manual cleanup still requires `zclean --yes`.',
+  ];
+  if (zombieCount > 0) {
+    recommendations.push('Run `zclean --yes` only after confirming these are leftover AI coding runtimes.');
+  } else {
+    recommendations.push('No AI runtime leftovers are currently visible.');
+  }
+  if (warnings.length > 0) {
+    recommendations.push('Review scan warnings; some candidates may need manual attribution.');
+  }
+  recommendations.push(`Use \`zclean ${commandName} --json\` for dashboards, CI notes, or local automation.`);
+  return recommendations;
+}
+
+function buildNextActions({ zombieCount, errors, warnings, commandName }) {
+  if (errors.length > 0) {
+    return [
+      {
+        id: 'run-doctor',
+        priority: 'high',
+        command: 'zclean doctor',
+        description: 'Fix process enumeration before trusting the report.',
+      },
+      {
+        id: 'avoid-cleanup',
+        priority: 'high',
+        command: null,
+        description: `Do not run cleanup from this ${commandName} result while enumeration is incomplete.`,
+      },
+    ];
+  }
+
+  const actions = [];
+  if (zombieCount > 0) {
+    actions.push({
+      id: 'review-top-candidates',
+      priority: 'high',
+      command: null,
+      description: 'Review topCandidates, largestCandidate, and oldestCandidate before cleanup.',
+    });
+    actions.push({
+      id: 'manual-cleanup-requires-yes',
+      priority: 'high',
+      command: 'zclean --yes',
+      description: 'Cleanup remains opt-in and requires an explicit --yes run after review.',
+    });
+  } else {
+    actions.push({
+      id: 'monitor-runtime-hygiene',
+      priority: 'normal',
+      command: `zclean ${commandName}`,
+      description: 'No AI runtime leftovers are visible; rerun the report when sessions change.',
+    });
+  }
+
+  if (warnings.length > 0) {
+    actions.push({
+      id: 'review-warnings',
+      priority: 'normal',
+      command: null,
+      description: 'Review scan warnings before making cleanup decisions.',
+    });
+  }
+
+  actions.push({
+    id: 'export-json',
+    priority: 'low',
+    command: `zclean ${commandName} --json`,
+    description: 'Use the JSON report for local dashboards, CI notes, or automation.',
+  });
+  return actions;
+}
+
+module.exports = {
+  buildNextActions,
+  buildRecommendations,
+};

package/src/audit-candidates.js

@@ -0,0 +1,86 @@
+'use strict';
+
+function buildCandidateReview(item) {
+  const memory = item.mem || 0;
+  const age = item.age || 0;
+  const riskScore = Math.min(100, 30 + Math.floor(memory / (100 * 1024 * 1024)) * 5 + Math.floor(age / 3600000));
+  return {
+    pid: item.pid,
+    name: item.name || item.pattern || 'unknown',
+    pattern: item.pattern || item.name || 'unknown',
+    memoryBytes: memory,
+    ageMs: age,
+    reason: item.reason || '',
+    risk: {
+      score: riskScore,
+      level: riskScore >= 75 ? 'high' : riskScore >= 50 ? 'medium' : 'low',
+    },
+  };
+}
+
+function groupCandidatesByPattern(candidates) {
+  const grouped = {};
+  for (const candidate of candidates) {
+    grouped[candidate.pattern] = (grouped[candidate.pattern] || 0) + 1;
+  }
+  return grouped;
+}
+
+function groupCandidateSourcesByPattern(candidates) {
+  const grouped = {};
+  for (const candidate of candidates) {
+    const pattern = candidate.pattern;
+    if (!grouped[pattern]) {
+      grouped[pattern] = {
+        count: 0,
+        memoryBytes: 0,
+        pids: [],
+      };
+    }
+    grouped[pattern].count++;
+    grouped[pattern].memoryBytes += candidate.memoryBytes;
+    grouped[pattern].pids.push(candidate.pid);
+  }
+  return grouped;
+}
+
+function sortCandidatesByRisk(candidates) {
+  return [...candidates].sort((left, right) => {
+    if (right.risk.score !== left.risk.score) return right.risk.score - left.risk.score;
+    if (right.memoryBytes !== left.memoryBytes) return right.memoryBytes - left.memoryBytes;
+    if (right.ageMs !== left.ageMs) return right.ageMs - left.ageMs;
+    return (left.pid || 0) - (right.pid || 0);
+  });
+}
+
+function pickCandidate(candidates, field) {
+  if (candidates.length === 0) return null;
+  return candidates.reduce((best, candidate) => {
+    if (candidate[field] > best[field]) return candidate;
+    if (candidate[field] === best[field] && (candidate.pid || 0) < (best.pid || 0)) return candidate;
+    return best;
+  });
+}
+
+function calculateScore(candidates, warnings, errors) {
+  if (errors.length > 0) return 0;
+  const candidatePenalty = candidates.reduce((sum, item) => sum + Math.min(20, Math.ceil(item.risk.score / 10)), 0);
+  const warningPenalty = warnings.length * 5;
+  return Math.max(0, 100 - candidatePenalty - warningPenalty);
+}
+
+function riskLevel(candidateCount, warningCount) {
+  if (candidateCount === 0 && warningCount === 0) return 'clean';
+  if (candidateCount <= 2 && warningCount === 0) return 'watch';
+  return 'attention';
+}
+
+module.exports = {
+  buildCandidateReview,
+  calculateScore,
+  groupCandidateSourcesByPattern,
+  groupCandidatesByPattern,
+  pickCandidate,
+  riskLevel,
+  sortCandidatesByRisk,
+};

package/src/audit-history.js

@@ -0,0 +1,69 @@
+'use strict';
+
+function buildHistory(logs, stats) {
+  const lastCleanup = logs.filter((entry) => entry.action === 'cleanup-summary').pop() || null;
+  return {
+    totalKilled: stats.totalKilled || 0,
+    totalMemFreed: stats.totalMemFreed || 0,
+    weekKilled: stats.weekKilled || 0,
+    weekMemFreed: stats.weekMemFreed || 0,
+    lastRun: stats.lastRun || (lastCleanup ? lastCleanup.timestamp : null),
+    lastDryRun: findLastTimestamp(logs, 'dry-run'),
+    recentFailures: findRecentFailures(logs),
+    recent: summarizeLogs(logs),
+  };
+}
+
+function findLastTimestamp(logs, action) {
+  const entry = logs.filter((item) => item.action === action && item.timestamp).pop();
+  return entry ? entry.timestamp : null;
+}
+
+function findRecentFailures(logs) {
+  return logs
+    .filter((entry) => entry.action === 'scan-failed' || entry.action === 'kill-failed' || (entry.action === 'cleanup-summary' && entry.failed > 0))
+    .slice(-5)
+    .map((entry) => ({
+      timestamp: entry.timestamp || null,
+      action: entry.action,
+      pid: entry.pid || null,
+      message: entry.message || entry.error || null,
+      failed: entry.failed || 0,
+    }));
+}
+
+function summarizeLogs(logs) {
+  const summary = {
+    dryRuns: 0,
+    scans: 0,
+    scanFailures: 0,
+    cleanupSummaries: 0,
+    failedKills: 0,
+  };
+
+  for (const entry of logs) {
+    switch (entry.action) {
+      case 'dry-run':
+        summary.dryRuns++;
+        break;
+      case 'scan':
+        summary.scans++;
+        break;
+      case 'scan-failed':
+        summary.scanFailures++;
+        break;
+      case 'cleanup-summary':
+        summary.cleanupSummaries++;
+        break;
+      case 'kill-failed':
+        summary.failedKills++;
+        break;
+    }
+  }
+
+  return summary;
+}
+
+module.exports = {
+  buildHistory,
+};

package/src/audit-printer.js

@@ -0,0 +1,83 @@
+'use strict';
+
+const { c, bold, formatBytes, formatDuration } = require('./reporter');
+
+function reportAudit(report, options = {}) {
+  const commandName = options.commandName || 'audit';
+  console.log(bold(`\n  zclean ${commandName}`) + c('gray', ' - AI runtime hygiene review\n'));
+  console.log(`  Score:       ${formatRiskScore(report.risk)}`);
+  console.log(`  Status:      ${report.summary.status}`);
+  console.log(`  Candidates:  ${report.summary.zombieCount}`);
+  console.log(`  Memory:      ${formatBytes(report.summary.reclaimableBytes)} reclaimable`);
+  console.log('  Scope:       AI coding runtime hygiene plus safe workspace caches; not app uninstall or whole-disk cleanup');
+  console.log();
+
+  console.log(c('cyan', '  Safety'));
+  console.log(`    Manual scans are dry-run: ${report.proGradeReview.guardrails.dryRunDefault ? 'yes' : 'configured false, but --yes is still required'}`);
+  console.log(`    Cleanup requires --yes:  ${report.proGradeReview.guardrails.cleanupRequiresYes ? 'yes' : 'no'}`);
+  console.log(`    Whitelist entries:       ${report.proGradeReview.guardrails.whitelistCount}`);
+  console.log(`    Custom AI dirs:          ${report.proGradeReview.guardrails.customAiDirCount}`);
+  console.log(`    Telemetry:               none`);
+  console.log();
+
+  if (!report.risk.enumerationComplete) {
+    console.log(c('red', '  Enumeration incomplete'));
+    for (const error of report.diagnostics.errors) {
+      console.log(`    ${formatDiagnostic(error)}`);
+    }
+    console.log();
+  }
+
+  if (report.diagnostics.warnings.length > 0) {
+    console.log(c('yellow', '  Warnings'));
+    for (const warning of report.diagnostics.warnings) {
+      console.log(`    ${formatDiagnostic(warning)}`);
+    }
+    console.log();
+  }
+
+  if (report.proGradeReview.candidates.length > 0) {
+    console.log(c('cyan', '  Top candidates'));
+    for (const item of report.proGradeReview.topCandidates.slice(0, 5)) {
+      console.log(`    PID ${String(item.pid).padStart(6)}  ${item.pattern.padEnd(16)}  ${formatBytes(item.memoryBytes).padStart(8)}  ${formatDuration(item.ageMs).padStart(6)}`);
+      console.log(`      ${item.reason}`);
+    }
+    console.log();
+  }
+
+  console.log(c('cyan', '  Recent history'));
+  console.log(`    This week:  ${report.history.weekKilled} cleaned, ${formatBytes(report.history.weekMemFreed)} freed`);
+  console.log(`    All time:   ${report.history.totalKilled} cleaned, ${formatBytes(report.history.totalMemFreed)} freed`);
+  console.log(`    Last run:   ${report.history.lastRun || 'never'}`);
+  console.log(`    Last dry-run: ${report.history.lastDryRun || 'never'}`);
+  console.log(`    Recent failures: ${report.history.recentFailures.length}`);
+  console.log();
+
+  console.log(c('cyan', '  Positioning'));
+  console.log(`    ${report.differentiation}`);
+  console.log();
+
+  console.log(c('cyan', '  Recommendations'));
+  for (const action of report.nextActions) {
+    const command = action.command ? ` (${action.command})` : '';
+    console.log(`    - [${action.priority}] ${action.description}${command}`);
+  }
+  console.log();
+}
+
+function formatRiskScore(risk) {
+  const text = `${risk.score}/100 (${risk.level})`;
+  if (risk.level === 'clean' || risk.level === 'watch') return c('green', text);
+  if (risk.level === 'unknown') return c('red', text);
+  return c('yellow', text);
+}
+
+function formatDiagnostic(item) {
+  if (typeof item === 'string') return item;
+  const code = item.code ? `${item.code}: ` : '';
+  return `${code}${item.message || 'scan diagnostic'}`;
+}
+
+module.exports = {
+  reportAudit,
+};