z-clean 0.3.1 → 0.3.2

package/README.ko.md

@@ -55,17 +55,34 @@ AI 코딩 도구는 작업 중 많은 임시 런타임을 만듭니다.
 
 ## 설치
 
+먼저 설치나 정리 없이 읽기 전용 audit을 실행하세요:
+
 ```bash
-npm install -g z-clean
-zclean init
+npx --yes z-clean audit
 ```
 
-설치 없이 1회 실행:
+정리 전에 후보를 검토하세요:
 
 ```bash
 npx --yes z-clean
+npx --yes z-clean report
+```
+
+계속 사용하려면 전역 설치하세요:
+
+```bash
+npm install -g z-clean
+zclean report
 ```
 
+자동 실행은 선택 사항입니다:
+
+```bash
+zclean init
+```
+
+`zclean init`은 Claude Code session hook과 OS scheduler를 설치합니다. dry-run 결과를 확인한 후에만 실행하세요. 상주 daemon을 설치하지는 않습니다.
+
 ## 자주 쓰는 명령
 
 ```bash

package/README.md

@@ -15,7 +15,7 @@ AI coding runtime hygiene
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18-339933?style=flat-square&logo=node.js&logoColor=white)](#)
 [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey?style=flat-square)](#platform-status)
 [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-blue?style=flat-square)](#)
-[![Tests](https://img.shields.io/badge/tests-101%20passing-brightgreen?style=flat-square)](#)
+[![Tests](https://img.shields.io/badge/tests-105%20passing-brightgreen?style=flat-square)](#)
 [![GitHub stars](https://img.shields.io/github/stars/TheStack-ai/zclean?style=flat-square)](https://github.com/TheStack-ai/zclean)
 [![Mentioned in Awesome Claude Code Toolkit](https://awesome.re/mentioned-badge.svg)](https://github.com/rohitg00/awesome-claude-code-toolkit)
 
@@ -51,22 +51,24 @@ The goal is narrower: **AI coding cleanup and developer workspace hygiene**.
 
 ## Quick Start
 
+Start with a read-only audit. This does not install hooks, schedule jobs, or clean anything:
+
 ```bash
-npm install -g z-clean
-zclean init
+npx --yes z-clean audit
 ```
 
-One-off dry run without installation:
+Review the candidates before cleaning:
 
 ```bash
 npx --yes z-clean
+npx --yes z-clean report
 ```
 
-Review before cleaning:
+Install the CLI when you are ready to keep using it:
 
 ```bash
+npm install -g z-clean
 zclean report
-zclean report --json
 ```
 
 Clean only when you decide:
@@ -76,6 +78,14 @@ zclean --yes
 zclean cache --yes
 ```
 
+Optional automation:
+
+```bash
+zclean init
+```
+
+`zclean init` installs the Claude Code session hook and the native OS scheduler. Run it only after reviewing the dry-run output. It does not install a persistent daemon.
+
 ## Why developers use it
 
 AI coding tools spawn many short-lived runtimes while they work:

package/README.zh.md

@@ -55,17 +55,34 @@ AI 编程工具在工作时会启动很多临时运行时：
 
 ## 安装
 
+先运行只读 audit；它不会安装 hook、创建定时任务或执行清理：
+
 ```bash
-npm install -g z-clean
-zclean init
+npx --yes z-clean audit
 ```
 
-无需安装的一次性运行：
+清理前先查看候选项：
 
 ```bash
 npx --yes z-clean
+npx --yes z-clean report
+```
+
+准备长期使用时再全局安装：
+
+```bash
+npm install -g z-clean
+zclean report
 ```
 
+自动运行是可选项：
+
+```bash
+zclean init
+```
+
+`zclean init` 会安装 Claude Code session hook 和原生 OS scheduler。请先检查 dry-run 结果；它不会安装常驻 daemon。
+
 ## 常用命令
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "z-clean",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "AI coding runtime hygiene reports, zombie cleanup, and safe workspace cache cleanup",
   "bin": {
     "zclean": "bin/zclean.js"

package/src/config.js

@@ -3,6 +3,14 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const {
+  appendPrivateFile,
+  sanitizeHistoryEntry,
+  sanitizeHistoryFile,
+  secureDirectory,
+  secureFile,
+  writePrivateFile,
+} = require('./storage-security');
 
 const CONFIG_DIR_ENV = 'ZCLEAN_CONFIG_DIR';
 
@@ -68,10 +76,7 @@ function parseMemory(str) {
  * Ensure the config directory exists.
  */
 function ensureConfigDir() {
-  const configDir = getConfigDir();
-  if (!fs.existsSync(configDir)) {
-    fs.mkdirSync(configDir, { recursive: true });
-  }
+  secureDirectory(getConfigDir());
 }
 
 /**
@@ -79,8 +84,10 @@ function ensureConfigDir() {
  */
 function loadConfig() {
   ensureConfigDir();
+  sanitizeHistoryFile(getLogFile());
   const configFile = getConfigFile();
   if (fs.existsSync(configFile)) {
+    secureFile(configFile);
     try {
       const raw = fs.readFileSync(configFile, 'utf-8');
       const userConfig = JSON.parse(raw);
@@ -98,7 +105,7 @@ function loadConfig() {
  */
 function saveConfig(config) {
   ensureConfigDir();
-  fs.writeFileSync(getConfigFile(), JSON.stringify(config, null, 2) + '\n', 'utf-8');
+  writePrivateFile(getConfigFile(), JSON.stringify(config, null, 2) + '\n');
 }
 
 /**
@@ -107,8 +114,8 @@ function saveConfig(config) {
  */
 function appendLog(entry) {
   ensureConfigDir();
-  const line = JSON.stringify({ timestamp: new Date().toISOString(), ...entry }) + '\n';
-  fs.appendFileSync(getLogFile(), line, 'utf-8');
+  const sanitized = sanitizeHistoryEntry({ timestamp: new Date().toISOString(), ...entry });
+  appendPrivateFile(getLogFile(), JSON.stringify(sanitized) + '\n');
 }
 
 /**
@@ -122,7 +129,7 @@ function readLogs(limit = 50) {
     return lines
       .slice(-limit)
       .map((line) => {
-        try { return JSON.parse(line); } catch { return null; }
+        try { return sanitizeHistoryEntry(JSON.parse(line)); } catch { return null; }
       })
       .filter(Boolean);
   } catch {
@@ -140,15 +147,15 @@ function pruneLogs(config) {
 
   const cutoff = Date.now() - retentionMs;
   const lines = fs.readFileSync(logFile, 'utf-8').trim().split('\n').filter(Boolean);
-  const kept = lines.filter((line) => {
+  const kept = lines.flatMap((line) => {
     try {
-      const entry = JSON.parse(line);
-      return new Date(entry.timestamp).getTime() >= cutoff;
+      const entry = sanitizeHistoryEntry(JSON.parse(line));
+      return new Date(entry.timestamp).getTime() >= cutoff ? [JSON.stringify(entry)] : [];
     } catch {
-      return false;
+      return [];
     }
   });
-  fs.writeFileSync(logFile, kept.join('\n') + (kept.length ? '\n' : ''), 'utf-8');
+  writePrivateFile(logFile, kept.join('\n') + (kept.length ? '\n' : ''));
 }
 
 /**

package/src/killer.js

@@ -56,7 +56,6 @@ function killZombies(zombies, config) {
         action: 'kill',
         pid: proc.pid,
         name: proc.name,
-        cmd: proc.cmd,
         reason: proc.reason,
         memFreed: proc.mem,
       });
@@ -69,7 +68,6 @@ function killZombies(zombies, config) {
         action: 'kill-failed',
         pid: proc.pid,
         name: proc.name,
-        cmd: proc.cmd,
         error: killResult.error,
       });
     }

package/src/process-diagnostic.js

@@ -0,0 +1,17 @@
+'use strict';
+
+function providerDiagnostic(provider, code, error) {
+  return {
+    code,
+    provider,
+    message: diagnosticMessage(error),
+  };
+}
+
+function diagnosticMessage(error) {
+  const stderr = error && error.stderr ? String(error.stderr).trim() : '';
+  const fallback = error instanceof Error ? error.message : String(error || '');
+  return (stderr || fallback).replace(/\s+/g, ' ').slice(0, 500);
+}
+
+module.exports = { providerDiagnostic };

package/src/storage-security.js

@@ -0,0 +1,65 @@
+'use strict';
+
+const fs = require('fs');
+
+const SENSITIVE_HISTORY_FIELDS = ['args', 'argv', 'cmd', 'command', 'commandLine'];
+
+function secureDirectory(directory) {
+  if (!fs.existsSync(directory)) {
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  }
+  if (process.platform !== 'win32') fs.chmodSync(directory, 0o700);
+}
+
+function writePrivateFile(file, content) {
+  fs.writeFileSync(file, content, { encoding: 'utf-8', mode: 0o600 });
+  secureFile(file);
+}
+
+function appendPrivateFile(file, content) {
+  fs.appendFileSync(file, content, { encoding: 'utf-8', mode: 0o600 });
+  secureFile(file);
+}
+
+function secureFile(file) {
+  if (process.platform !== 'win32') fs.chmodSync(file, 0o600);
+}
+
+function sanitizeHistoryEntry(entry) {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return entry;
+  const sanitized = { ...entry };
+  for (const field of SENSITIVE_HISTORY_FIELDS) delete sanitized[field];
+  return sanitized;
+}
+
+function sanitizeHistoryFile(file) {
+  if (!fs.existsSync(file)) return;
+
+  const raw = fs.readFileSync(file, 'utf-8');
+  const lines = raw.split(/\r?\n/).filter(Boolean);
+  let changed = false;
+  const sanitized = lines.map((line) => {
+    try {
+      const next = JSON.stringify(sanitizeHistoryEntry(JSON.parse(line)));
+      if (next !== line) changed = true;
+      return next;
+    } catch {
+      return line;
+    }
+  });
+
+  if (changed) {
+    writePrivateFile(file, sanitized.join('\n') + (sanitized.length ? '\n' : ''));
+  } else {
+    secureFile(file);
+  }
+}
+
+module.exports = {
+  appendPrivateFile,
+  sanitizeHistoryEntry,
+  sanitizeHistoryFile,
+  secureDirectory,
+  secureFile,
+  writePrivateFile,
+};

package/src/windows-processes.js

@@ -1,16 +1,34 @@
 'use strict';
 
+const { providerDiagnostic } = require('./process-diagnostic');
+
 function normalizePid(pid) {
   const parsed = Number(pid);
   return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
 }
 
 function readWMICProcesses(runtime) {
+  try {
+    runtime.execSync('where wmic', {
+      encoding: 'utf-8',
+      timeout: 5000,
+      maxBuffer: 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch {
+    return { processes: [], warnings: [] };
+  }
+
   let output;
   try {
     output = runtime.execSync(
       'wmic process get ProcessId,ParentProcessId,CommandLine,WorkingSetSize,CreationDate /format:csv',
-      { encoding: 'utf-8', timeout: 15000, maxBuffer: 10 * 1024 * 1024 }
+      {
+        encoding: 'utf-8',
+        timeout: 15000,
+        maxBuffer: 10 * 1024 * 1024,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      }
     );
   } catch (err) {
     return {
@@ -35,7 +53,12 @@ function readCIMProcesses(runtime) {
   try {
     output = runtime.execSync(
       'powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -Command "Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,CommandLine,WorkingSetSize,CreationDate | ConvertTo-Json -Compress"',
-      { encoding: 'utf-8', timeout: 15000, maxBuffer: 10 * 1024 * 1024 }
+      {
+        encoding: 'utf-8',
+        timeout: 15000,
+        maxBuffer: 10 * 1024 * 1024,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      }
     );
   } catch (err) {
     return {
@@ -63,7 +86,12 @@ function readWindowsProcess(pid, runtime) {
   try {
     output = runtime.execSync(
       `powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -Command "Get-CimInstance Win32_Process -Filter 'ProcessId = ${safePid}' | Select-Object ProcessId,CommandLine,CreationDate | ConvertTo-Json -Compress"`,
-      { encoding: 'utf-8', timeout: 5000, maxBuffer: 1024 * 1024 }
+      {
+        encoding: 'utf-8',
+        timeout: 5000,
+        maxBuffer: 1024 * 1024,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      }
     );
   } catch {
     return null;
@@ -87,7 +115,12 @@ function windowsProcessExists(pid, runtime) {
   try {
     const output = runtime.execSync(
       `powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -Command "Get-CimInstance Win32_Process -Filter 'ProcessId = ${safePid}' | Select-Object ProcessId | ConvertTo-Json -Compress"`,
-      { encoding: 'utf-8', timeout: 3000, maxBuffer: 1024 * 1024 }
+      {
+        encoding: 'utf-8',
+        timeout: 3000,
+        maxBuffer: 1024 * 1024,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      }
     );
     return parseJsonRows(String(output || '')).some((row) => Number(readField(row, 'ProcessId')) === safePid);
   } catch {
@@ -238,14 +271,6 @@ function parseCsvLine(line) {
   return parts;
 }
 
-function providerDiagnostic(provider, code, err) {
-  return {
-    code,
-    provider,
-    message: err instanceof Error ? err.message : String(err || ''),
-  };
-}
-
 module.exports = {
   normalizePid,
   readCIMProcesses,