z-clean 0.1.1 → 0.3.0

package/src/audit-report.js

@@ -0,0 +1,135 @@
+'use strict';
+
+const { hasScanErrors } = require('./scanner');
+const {
+  buildCandidateReview,
+  calculateScore,
+  groupCandidateSourcesByPattern,
+  groupCandidatesByPattern,
+  pickCandidate,
+  riskLevel,
+  sortCandidatesByRisk,
+} = require('./audit-candidates');
+const { buildHistory } = require('./audit-history');
+const { buildNextActions, buildRecommendations } = require('./audit-actions');
+
+function buildAuditReport(...args) {
+  const input = normalizeBuildInput(args);
+  const config = input.config || {};
+  const zombies = Array.isArray(input.zombies) ? input.zombies : [];
+  const logs = Array.isArray(input.logs) ? input.logs : [];
+  const stats = input.stats || {};
+  const generatedAt = normalizeTime(input.now);
+  const commandName = input.commandName || 'audit';
+  const warnings = Array.isArray(input.zombies?.warnings) ? input.zombies.warnings : [];
+  const errors = Array.isArray(input.zombies?.errors) ? input.zombies.errors : [];
+  const enumerationComplete = !hasScanErrors(input.zombies || []);
+  const reclaimableBytes = zombies.reduce((sum, item) => sum + (item.mem || 0), 0);
+  const candidates = zombies.map((item) => buildCandidateReview(item));
+  const topCandidates = sortCandidatesByRisk(candidates);
+  const history = buildHistory(logs, stats);
+  const status = errors.length > 0 ? 'blocked' : zombies.length > 0 ? 'attention' : 'clean';
+  const recommendationInput = { zombieCount: zombies.length, errors, warnings, commandName };
+
+  return {
+    schemaVersion: 1,
+    generatedAt,
+    kind: 'ai-coding-runtime-hygiene',
+    notGeneralCleaner: true,
+    profile: buildProfile(),
+    differentiation: 'zclean audits AI coding runtime leftovers and safe workspace cache candidates; it does not uninstall apps, draw disk maps, or sweep the whole system.',
+    summary: {
+      status,
+      zombieCount: zombies.length,
+      reclaimableBytes,
+      warningCount: warnings.length,
+      errorCount: errors.length,
+    },
+    risk: {
+      score: calculateScore(candidates, warnings, errors),
+      level: status === 'blocked' ? 'unknown' : riskLevel(candidates.length, warnings.length),
+      enumerationComplete,
+    },
+    candidates: {
+      count: zombies.length,
+      memoryReclaimable: reclaimableBytes,
+      byPattern: groupCandidatesByPattern(candidates),
+      largestCandidate: pickCandidate(candidates, 'memoryBytes'),
+      oldestCandidate: pickCandidate(candidates, 'ageMs'),
+    },
+    candidateSources: {
+      byPattern: groupCandidateSourcesByPattern(candidates),
+    },
+    safety: buildSafety(config),
+    proGradeReview: {
+      safeToClean: enumerationComplete && zombies.length > 0,
+      candidates,
+      topCandidates,
+      guardrails: buildGuardrails(config),
+    },
+    diagnostics: {
+      warnings,
+      errors,
+    },
+    history,
+    nextActions: buildNextActions(recommendationInput),
+    recommendations: buildRecommendations(recommendationInput),
+  };
+}
+
+function normalizeBuildInput(args) {
+  if (args.length === 1 && args[0] && typeof args[0] === 'object' && Object.prototype.hasOwnProperty.call(args[0], 'zombies')) {
+    return args[0];
+  }
+
+  const [config = {}, zombies = [], logs = [], stats = {}, options = {}] = args;
+  return {
+    config,
+    zombies,
+    logs,
+    stats,
+    now: options.now,
+    commandName: options.commandName,
+  };
+}
+
+function normalizeTime(value) {
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === 'string') return value;
+  return new Date().toISOString();
+}
+
+function buildProfile() {
+  return {
+    tool: 'zclean',
+    focus: 'ai-coding-runtime-hygiene',
+    localOnly: true,
+    telemetry: false,
+    positioning: 'zclean is not a general Mac cleaner; it reviews AI coding runtime leftovers, safe workspace caches, and only cleans when explicitly asked.',
+  };
+}
+
+function buildSafety(config) {
+  return {
+    cleanupRequiresYes: true,
+    whitelistCount: Array.isArray(config.whitelist) ? config.whitelist.length : 0,
+    customAiDirsCount: Array.isArray(config.customAiDirs) ? config.customAiDirs.length : 0,
+    dryRunDefault: config.dryRunDefault !== false,
+  };
+}
+
+function buildGuardrails(config) {
+  return {
+    dryRunDefault: config.dryRunDefault !== false,
+    cleanupRequiresYes: true,
+    maxKillBatch: config.maxKillBatch || null,
+    whitelistCount: Array.isArray(config.whitelist) ? config.whitelist.length : 0,
+    customAiDirCount: Array.isArray(config.customAiDirs) ? config.customAiDirs.length : 0,
+    localOnly: true,
+    telemetry: false,
+  };
+}
+
+module.exports = {
+  buildAuditReport,
+};

package/src/audit.js

@@ -0,0 +1,35 @@
+'use strict';
+
+const { scan } = require('./scanner');
+const { readLogs, getCumulativeStats } = require('./config');
+const { buildAuditReport } = require('./audit-report');
+const { reportAudit } = require('./audit-printer');
+
+function runAudit(config, options = {}) {
+  const scanOptions = options.sessionPid ? { sessionPid: options.sessionPid } : {};
+  const zombies = options.scanResult || scan(config, scanOptions);
+  const logs = options.logs || readLogs(100);
+  const stats = options.stats || getCumulativeStats() || {};
+  const report = buildAuditReport({
+    config,
+    zombies,
+    logs,
+    stats,
+    now: options.now,
+    commandName: options.commandName,
+  });
+
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    reportAudit(report, { commandName: options.commandName });
+  }
+
+  return report;
+}
+
+module.exports = {
+  runAudit,
+  buildAuditReport,
+  reportAudit,
+};

package/src/cache.js

@@ -0,0 +1,256 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { appendLog } = require('./config');
+const { c, bold, formatBytes } = require('./reporter');
+
+const EXACT_CACHE_PATHS = new Set([
+  '.next/cache',
+  '.nuxt',
+  '.turbo',
+  '.vite',
+  '.parcel-cache',
+  '.pytest_cache',
+  '.ruff_cache',
+  '.mypy_cache',
+  'node_modules/.cache',
+]);
+
+const CACHE_DIR_NAMES = new Set(['__pycache__']);
+const CACHE_DIR_NAMES_ANYWHERE = new Set([
+  '.nuxt',
+  '.turbo',
+  '.vite',
+  '.parcel-cache',
+  '.pytest_cache',
+  '.ruff_cache',
+  '.mypy_cache',
+]);
+const SKIP_DIR_NAMES = new Set(['.git', '.hg', '.svn', '.omo', '.zclean']);
+const MAX_SCAN_DEPTH = 5;
+
+function runCache(options = {}) {
+  const root = path.resolve(options.root || process.cwd());
+  const yes = Boolean(options.yes);
+  const report = buildCacheReport({ root, yes });
+
+  if (yes && report._privateCandidates.length > 0) {
+    const result = cleanCacheTargets(report._privateCandidates);
+    report.summary.deleted = result.deleted.length;
+    report.summary.failed = result.failed.length;
+    report.deleted = result.deleted.map(toPublicCandidate);
+    report.failed = result.failed.map((item) => ({
+      ...toPublicCandidate(item),
+      error: item.error,
+    }));
+    appendLog({
+      action: 'cache-cleanup-summary',
+      deleted: report.summary.deleted,
+      failed: report.summary.failed,
+      totalBytes: report.summary.totalBytes,
+    });
+  } else if (!yes && report.candidates.length > 0) {
+    appendLog({ action: 'cache-dry-run', found: report.candidates.length, totalBytes: report.summary.totalBytes });
+  }
+
+  if (options.json) {
+    writeJson(report);
+  } else {
+    reportCacheText(report);
+  }
+
+  return report;
+}
+
+function buildCacheReport(options = {}) {
+  const root = path.resolve(options.root || process.cwd());
+  const candidates = scanCacheTargets(root);
+  const totalBytes = candidates.reduce((sum, item) => sum + item.bytes, 0);
+
+  return {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    kind: 'workspace-cache-hygiene',
+    dryRun: !options.yes,
+    workspace: path.basename(root) || '.',
+    scope: 'safe workspace cache paths only; no app uninstall or whole-disk sweep',
+    candidates: candidates.map(toPublicCandidate),
+    summary: {
+      count: candidates.length,
+      totalBytes,
+      deleted: 0,
+      failed: 0,
+    },
+    _privateCandidates: candidates,
+  };
+}
+
+function scanCacheTargets(root) {
+  if (!isDirectory(root)) return [];
+  const found = [];
+  walk(root, root, 0, found);
+  return found.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+}
+
+function walk(root, current, depth, found) {
+  if (depth > MAX_SCAN_DEPTH) return;
+  let entries;
+  try {
+    entries = fs.readdirSync(current, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.isSymbolicLink && entry.isSymbolicLink()) continue;
+
+    const absolutePath = path.join(current, entry.name);
+    const relativePath = toPosix(path.relative(root, absolutePath));
+    const isNodeModules = entry.name === 'node_modules';
+
+    if (isCachePath(relativePath, entry.name)) {
+      found.push({
+        id: cacheId(relativePath, entry.name),
+        absolutePath,
+        relativePath,
+        type: 'directory',
+        bytes: directorySize(absolutePath),
+      });
+      continue;
+    }
+
+    if (SKIP_DIR_NAMES.has(entry.name)) continue;
+    if (isNodeModules) {
+      const nodeCache = path.join(absolutePath, '.cache');
+      if (isDirectory(nodeCache)) {
+        found.push({
+          id: 'node_modules-cache',
+          absolutePath: nodeCache,
+          relativePath: toPosix(path.relative(root, nodeCache)),
+          type: 'directory',
+          bytes: directorySize(nodeCache),
+        });
+      }
+      continue;
+    }
+
+    walk(root, absolutePath, depth + 1, found);
+  }
+}
+
+function cleanCacheTargets(candidates) {
+  const deleted = [];
+  const failed = [];
+  for (const candidate of [...candidates].sort((a, b) => b.relativePath.length - a.relativePath.length)) {
+    try {
+      fs.rmSync(candidate.absolutePath, { recursive: true, force: true });
+      deleted.push(candidate);
+    } catch (err) {
+      failed.push({ ...candidate, error: err.message });
+    }
+  }
+  return { deleted, failed };
+}
+
+function isCachePath(relativePath, name) {
+  return EXACT_CACHE_PATHS.has(relativePath)
+    || relativePath.endsWith('/.next/cache')
+    || relativePath.endsWith('/node_modules/.cache')
+    || CACHE_DIR_NAMES.has(name)
+    || CACHE_DIR_NAMES_ANYWHERE.has(name);
+}
+
+function cacheId(relativePath, name) {
+  if (relativePath === 'node_modules/.cache') return 'node_modules-cache';
+  if (name === '__pycache__') return 'python-bytecode-cache';
+  return relativePath.replace(/[/.]+/g, '-').replace(/^-|-$/g, '') || 'cache';
+}
+
+function directorySize(dir) {
+  let total = 0;
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+  for (const entry of entries) {
+    const file = path.join(dir, entry.name);
+    try {
+      const stat = fs.lstatSync(file);
+      if (stat.isSymbolicLink()) continue;
+      if (stat.isDirectory()) total += directorySize(file);
+      else if (stat.isFile()) total += stat.size;
+    } catch {}
+  }
+  return total;
+}
+
+function isDirectory(value) {
+  try {
+    return fs.statSync(value).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function toPublicCandidate(candidate) {
+  return {
+    id: candidate.id,
+    relativePath: candidate.relativePath,
+    type: candidate.type,
+    bytes: candidate.bytes,
+  };
+}
+
+function writeJson(report) {
+  const publicReport = { ...report };
+  delete publicReport._privateCandidates;
+  console.log(JSON.stringify(publicReport, null, 2));
+}
+
+function reportCacheText(report) {
+  console.log(bold('\n  zclean cache') + c('gray', ' - workspace cache hygiene\n'));
+  console.log(`  Workspace:   ${report.workspace}`);
+  console.log(`  Mode:        ${report.dryRun ? 'dry-run' : 'clean'}`);
+  console.log(`  Candidates:  ${report.summary.count}`);
+  console.log(`  Reclaimable: ${formatBytes(report.summary.totalBytes)}`);
+  console.log();
+
+  if (report.candidates.length === 0) {
+    console.log(c('green', '  No supported workspace cache paths found.\n'));
+    return;
+  }
+
+  for (const item of report.candidates.slice(0, 20)) {
+    console.log(`  ${c('cyan', item.relativePath.padEnd(28))} ${formatBytes(item.bytes).padStart(10)}`);
+  }
+  if (report.candidates.length > 20) {
+    console.log(c('gray', `  ... ${report.candidates.length - 20} more`));
+  }
+  console.log();
+
+  if (report.dryRun) {
+    console.log(c('gray', '  Run zclean cache --yes to remove these cache directories.\n'));
+    return;
+  }
+
+  if (report.summary.failed > 0) {
+    console.log(c('yellow', `  Removed ${report.summary.deleted}; failed ${report.summary.failed}.\n`));
+  } else {
+    console.log(c('green', `  Removed ${report.summary.deleted} cache director${report.summary.deleted === 1 ? 'y' : 'ies'}.\n`));
+  }
+}
+
+function toPosix(value) {
+  return value.split(path.sep).join('/');
+}
+
+module.exports = {
+  buildCacheReport,
+  cleanCacheTargets,
+  runCache,
+  scanCacheTargets,
+};

package/src/commands/scheduler.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const { c } = require('../reporter');
+
+function installScheduler(platform) {
+  switch (platform) {
+    case 'darwin': {
+      const { installLaunchd } = require('../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('../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('../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 uninstallScheduler(platform) {
+  switch (platform) {
+    case 'darwin': {
+      const { removeLaunchd } = require('../installer/launchd');
+      const result = removeLaunchd();
+      console.log(`  Scheduler: ${result.message}`);
+      break;
+    }
+    case 'linux': {
+      const { removeSystemd } = require('../installer/systemd');
+      const result = removeSystemd();
+      console.log(`  Scheduler: ${result.message}`);
+      break;
+    }
+    case 'win32': {
+      const { removeTaskScheduler } = require('../installer/taskscheduler');
+      const result = removeTaskScheduler();
+      console.log(`  Scheduler: ${result.message}`);
+      break;
+    }
+    default:
+      console.log(c('yellow', `  Scheduler: Remove manually for ${platform}.`));
+  }
+}
+
+module.exports = { installScheduler, uninstallScheduler };

package/src/commands/trust.js

@@ -0,0 +1,157 @@
+'use strict';
+
+const fs = require('fs');
+const {
+  saveConfig,
+  readLogs,
+  getCumulativeStats,
+  getConfigFile,
+  getLogFile,
+  summarizeHistory,
+} = require('../config');
+const { reportLogs, c, bold } = require('../reporter');
+
+const SAFE_HISTORY_ENTRY_KEYS = new Set([
+  'action',
+  'errors',
+  'failed',
+  'found',
+  'killed',
+  'skipped',
+  'timestamp',
+  'totalMemFreed',
+]);
+
+function runHistory(flags) {
+  const logs = readLogs(50);
+  if (flags.json) {
+    console.log(JSON.stringify({
+      schemaVersion: 1,
+      generatedAt: new Date().toISOString(),
+      entries: logs.map(sanitizeHistoryEntry),
+      summary: summarizeHistory(logs, getCumulativeStats()),
+    }, null, 2));
+    return;
+  }
+  reportLogs(logs);
+}
+
+function runProtect(config, flags, positional) {
+  const subcommand = positional[1] || 'list';
+
+  switch (subcommand) {
+    case 'list':
+      return protectList(config, flags);
+    case 'add':
+      return protectAdd(config, flags, positional);
+    case 'remove':
+      return protectRemove(config, flags, positional);
+    default:
+      console.error(c('red', `  Unknown protect command: ${subcommand}`));
+      console.error(c('gray', '  Usage: zclean protect list|add|remove'));
+      process.exit(1);
+  }
+}
+
+function protectList(config, flags) {
+  const whitelist = getWhitelist(config);
+  if (flags.json) {
+    console.log(JSON.stringify({
+      schemaVersion: 1,
+      generatedAt: new Date().toISOString(),
+      whitelist,
+    }, null, 2));
+    return;
+  }
+
+  console.log(bold('\n  Protected entries\n'));
+  if (whitelist.length === 0) {
+    console.log(c('gray', '  No protected entries configured.\n'));
+    return;
+  }
+  whitelist.forEach((entry, index) => {
+    console.log(`  ${String(index + 1).padStart(2)}. ${entry}`);
+  });
+  console.log();
+}
+
+function protectAdd(config, flags, positional) {
+  const entry = normalizeProtectEntry(positional.slice(2).join(' '));
+  if (!entry) failProtect('Protection entry is required and cannot be empty.');
+
+  const writableConfig = readWritableConfig(config);
+  const whitelist = getWhitelist(writableConfig);
+  if (whitelist.includes(entry)) {
+    failProtect(`Entry is already protected: ${entry}`);
+  }
+
+  saveConfig({ ...writableConfig, whitelist: [...whitelist, entry] });
+  console.log(c('green', `  Protected: ${entry}`));
+  if (flags.reason) {
+    console.log(c('gray', '  Note: --reason is accepted for workflow notes but is not stored in config yet.'));
+  }
+}
+
+function protectRemove(config, flags, positional) {
+  const writableConfig = readWritableConfig(config);
+  const whitelist = getWhitelist(writableConfig);
+  const indexValue = flags.index;
+  let index = -1;
+  let entry = null;
+
+  if (indexValue !== undefined) {
+    index = parseProtectIndex(indexValue, whitelist.length);
+    entry = whitelist[index];
+  } else {
+    entry = normalizeProtectEntry(positional.slice(2).join(' '));
+    if (!entry) failProtect('Protection entry or --index=N is required.');
+    index = whitelist.indexOf(entry);
+    if (index === -1) failProtect(`Entry is not protected: ${entry}`);
+  }
+
+  saveConfig({ ...writableConfig, whitelist: whitelist.filter((_, current) => current !== index) });
+  console.log(c('green', `  Removed protected entry: ${entry}`));
+}
+
+function sanitizeHistoryEntry(entry) {
+  const safe = {};
+  for (const key of SAFE_HISTORY_ENTRY_KEYS) {
+    if (Object.prototype.hasOwnProperty.call(entry, key)) safe[key] = entry[key];
+  }
+  return safe;
+}
+
+function readWritableConfig(fallback) {
+  const configFile = getConfigFile();
+  if (!fs.existsSync(configFile)) return fallback;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(configFile, 'utf-8'));
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed;
+  } catch {}
+  return fallback;
+}
+
+function getWhitelist(config) {
+  return Array.isArray(config.whitelist)
+    ? config.whitelist.filter((entry) => typeof entry === 'string')
+    : [];
+}
+
+function normalizeProtectEntry(value) {
+  return String(value || '').trim();
+}
+
+function parseProtectIndex(value, length) {
+  if (value === true || value === '') failProtect('--index must be a positive integer.');
+  const index = Number(value);
+  if (!Number.isInteger(index) || index < 1) failProtect('--index must be a positive integer.');
+  if (index > length) failProtect(`Protection index out of range: ${index}`);
+  return index - 1;
+}
+
+function failProtect(message) {
+  console.error(c('red', `  ${message}`));
+  process.exit(1);
+}
+
+module.exports = { runHistory, runProtect };