pompelmi 1.11.0 → 1.12.0

package/README.md

@@ -21,12 +21,28 @@
 
 ---
 
+## Quick Start
+
+```bash
+# Scan a file
+npx pompelmi scan ./uploads/file.pdf
+
+# Scan a directory
+npx pompelmi scan ./uploads --recursive
+
+# Output as JSON
+npx pompelmi scan ./uploads --json
+```
+
+---
+
 ## Documentation
 
 | Guide | Description |
 |-------|-------------|
 | [Getting Started](./docs/getting-started.md) | Installation, prerequisites, quickstart examples |
 | [API Reference](./docs/api.md) | Full function signatures, options, verdicts, error conditions |
+| [CLI Reference](./docs/cli.html) | Terminal commands, options, examples |
 | [S3 Integration](./docs/s3.md) | Scan S3 objects directly, IAM setup, Lambda pattern |
 | [Docker / Remote Scanning](./docs/docker.md) | TCP sidecar, UNIX socket mount, docker-compose patterns |
 | [GitHub Action](./docs/github-action.md) | CI scanning, inputs/outputs, caching, example workflows |
@@ -56,6 +72,7 @@ Most integrations require parsing ClamAV's stdout with regex, managing a clamd d
 
 ## Features
 
+- Standalone CLI — scan files from any terminal with `npx pompelmi scan`
 - Single `scan(filePath, [options])` function — works locally or against a remote clamd instance
 - `scanBuffer(buffer, [options])` — scan in-memory Buffers directly, no temp file required in TCP mode
 - `scanStream(stream, [options])` — scan a Readable stream directly. In TCP mode, streamed to clamd with no disk I/O.

package/bin/pompelmi.js

@@ -0,0 +1,403 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const readline = require('readline');
+
+const pkg = require('../package.json');
+
+// ── Logo ──────────────────────────────────────────────────────────────────────
+
+async function printLogo() {
+  try {
+    const terminalImage = (await import('terminal-image')).default;
+    const imgPath = path.join(__dirname, '../src/grapefruit.png');
+    if (fs.existsSync(imgPath)) {
+      const image = await terminalImage.file(imgPath, {
+        width: '20%',
+        height: '20%',
+        preserveAspectRatio: true,
+      });
+      process.stdout.write(image);
+    }
+  } catch (_) {}
+  console.log('\x1b[33m  pompelmi\x1b[0m — ClamAV Antivirus Scanning for Node.js');
+  console.log('\x1b[90m  v' + pkg.version + ' • Zero dependencies • TCP • UNIX socket • GitHub Action\x1b[0m\n');
+}
+
+// ── Argument parsing ──────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const opts = {
+    command: null,
+    target: null,
+    host: undefined,
+    port: undefined,
+    socket: undefined,
+    timeout: 15000,
+    retries: 0,
+    json: false,
+    quiet: false,
+    delete: false,
+    recursive: true,
+  };
+
+  let i = 0;
+  while (i < args.length) {
+    const a = args[i];
+    if (a === 'scan' || a === 'watch' || a === 'version' || a === 'help') {
+      opts.command = a;
+    } else if (a === '--json') {
+      opts.json = true;
+    } else if (a === '--quiet' || a === '-q') {
+      opts.quiet = true;
+    } else if (a === '--recursive' || a === '-r') {
+      opts.recursive = true;
+    } else if (a === '--delete') {
+      opts.delete = true;
+    } else if (a === '--host') {
+      opts.host = args[++i];
+    } else if (a === '--port') {
+      opts.port = parseInt(args[++i], 10);
+    } else if (a === '--socket') {
+      opts.socket = args[++i];
+    } else if (a === '--timeout') {
+      opts.timeout = parseInt(args[++i], 10);
+    } else if (a === '--retries') {
+      opts.retries = parseInt(args[++i], 10);
+    } else if (!a.startsWith('-') && opts.command && !opts.target) {
+      opts.target = a;
+    }
+    i++;
+  }
+
+  return opts;
+}
+
+// ── Scan options builder ──────────────────────────────────────────────────────
+
+function buildScanOpts(opts) {
+  const o = { timeout: opts.timeout, retries: opts.retries };
+  if (opts.host !== undefined) o.host = opts.host;
+  if (opts.port !== undefined) o.port = opts.port;
+  if (opts.socket !== undefined) o.socket = opts.socket;
+  return o;
+}
+
+// ── Progress bar ──────────────────────────────────────────────────────────────
+
+function progressBar(done, total, infected) {
+  const pct = total === 0 ? 0 : Math.floor((done / total) * 100);
+  const filled = Math.floor(pct / 5);
+  const empty = 20 - filled;
+  const bar = '█'.repeat(filled) + '░'.repeat(empty);
+  return `  Scanning... [${bar}] ${pct}% • ${done}/${total} files • ${infected} infected`;
+}
+
+// ── Box drawing output ────────────────────────────────────────────────────────
+
+function boxLine(content, width) {
+  const padded = content.padEnd(width - 4);
+  return `│  ${padded}  │`;
+}
+
+function printResults(results, elapsed, opts) {
+  if (opts.json) {
+    const out = {
+      scanned: results.length,
+      infected: results.filter(r => r.verdict === 'infected').length,
+      errors: results.filter(r => r.verdict === 'error').length,
+      time: Math.round(elapsed / 100) / 10,
+      results: results.map(r => {
+        const o = { file: r.file, verdict: r.verdict };
+        if (r.viruses) o.viruses = r.viruses;
+        return o;
+      }),
+    };
+    console.log(JSON.stringify(out, null, 2));
+    return;
+  }
+
+  const W = 46;
+  const top    = '┌' + '─'.repeat(W) + '┐';
+  const sep    = '├' + '─'.repeat(W) + '┤';
+  const bottom = '└' + '─'.repeat(W) + '┘';
+
+  const infected = results.filter(r => r.verdict === 'infected').length;
+  const secs     = (elapsed / 1000).toFixed(1);
+
+  console.log(top);
+  console.log(boxLine('🍊 pompelmi scan results', W));
+  console.log(sep);
+
+  for (const r of results) {
+    if (opts.quiet && r.verdict === 'clean') continue;
+    const short = r.file.length > 30 ? '...' + r.file.slice(-27) : r.file;
+    if (r.verdict === 'clean') {
+      console.log(boxLine(`\x1b[32m✅ CLEAN\x1b[0m     ${short}`, W + 9));
+    } else if (r.verdict === 'infected') {
+      console.log(boxLine(`\x1b[31m🚨 INFECTED\x1b[0m  ${short}`, W + 9));
+      if (r.viruses && r.viruses.length) {
+        const vname = r.viruses[0] || '';
+        console.log(boxLine(`\x1b[90m     └─ ${vname}\x1b[0m`, W + 8));
+      }
+    } else {
+      console.log(boxLine(`\x1b[33m⚠️  ERROR\x1b[0m    ${short}`, W + 12));
+    }
+  }
+
+  console.log(sep);
+  const summary = `Scanned: ${results.length}  • Infected: ${infected} • Time: ${secs}s`;
+  console.log(boxLine(summary, W));
+  console.log(bottom);
+}
+
+// ── Scan a single file ────────────────────────────────────────────────────────
+
+async function scanOne(filePath, scanOpts) {
+  const { scan }    = require('../src/ClamAVScanner.js');
+  const { Verdict } = require('../src/verdicts.js');
+  try {
+    const v = await scan(filePath, scanOpts);
+    if (v === Verdict.Clean)     return { file: filePath, verdict: 'clean' };
+    if (v === Verdict.Malicious) return { file: filePath, verdict: 'infected', viruses: [] };
+    return { file: filePath, verdict: 'error' };
+  } catch (err) {
+    if (/ECONNREFUSED|ENOTFOUND|ETIMEDOUT|unreachable/i.test(err.message)) {
+      return { file: filePath, verdict: 'error', _clamdUnreachable: true };
+    }
+    return { file: filePath, verdict: 'error' };
+  }
+}
+
+// ── Collect files from path ───────────────────────────────────────────────────
+
+function collectFiles(target) {
+  const stat = fs.statSync(target);
+  if (stat.isFile()) return [target];
+  const entries = fs.readdirSync(target, { recursive: true });
+  return entries
+    .map(e => path.join(target, e))
+    .filter(f => { try { return fs.statSync(f).isFile(); } catch { return false; } });
+}
+
+// ── Ask confirmation ──────────────────────────────────────────────────────────
+
+function confirm(question) {
+  return new Promise(resolve => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, ans => {
+      rl.close();
+      resolve(ans.trim().toLowerCase() === 'y' || ans.trim().toLowerCase() === 'yes');
+    });
+  });
+}
+
+// ── Commands ──────────────────────────────────────────────────────────────────
+
+async function cmdScan(opts) {
+  if (!opts.target) {
+    console.error('Usage: pompelmi scan <file|dir> [options]');
+    process.exit(2);
+  }
+
+  const target = path.resolve(opts.target);
+  if (!fs.existsSync(target)) {
+    console.error(`Error: path not found: ${target}`);
+    process.exit(2);
+  }
+
+  if (!opts.json && !opts.quiet) await printLogo();
+
+  const files = collectFiles(target);
+  const scanOpts = buildScanOpts(opts);
+  const results = [];
+  const start = Date.now();
+  let infectedCount = 0;
+
+  for (let i = 0; i < files.length; i++) {
+    if (!opts.json && !opts.quiet && files.length > 1) {
+      process.stdout.write('\r' + progressBar(i, files.length, infectedCount));
+    }
+    const r = await scanOne(files[i], scanOpts);
+    if (r.verdict === 'infected') infectedCount++;
+    results.push(r);
+  }
+
+  if (!opts.json && !opts.quiet && files.length > 1) {
+    process.stdout.write('\r' + progressBar(files.length, files.length, infectedCount) + '\n');
+  }
+
+  const elapsed = Date.now() - start;
+
+  if (opts.delete) {
+    const infected = results.filter(r => r.verdict === 'infected');
+    if (infected.length > 0) {
+      if (!opts.json) {
+        console.log(`\nFound ${infected.length} infected file(s):`);
+        for (const r of infected) console.log(`  ${r.file}`);
+      }
+      const ok = await confirm('Delete these files? [y/N] ');
+      if (ok) {
+        for (const r of infected) {
+          try { fs.unlinkSync(r.file); if (!opts.json) console.log(`  Deleted: ${r.file}`); }
+          catch (e) { if (!opts.json) console.log(`  Failed to delete: ${r.file}: ${e.message}`); }
+        }
+      }
+    }
+  }
+
+  printResults(results, elapsed, opts);
+
+  const hasInfected = results.some(r => r.verdict === 'infected');
+  const hasError    = results.some(r => r.verdict === 'error');
+  const clamdDown   = results.some(r => r._clamdUnreachable);
+
+  if (clamdDown) process.exit(3);
+  if (hasInfected) process.exit(1);
+  if (hasError)    process.exit(2);
+  process.exit(0);
+}
+
+async function cmdWatch(opts) {
+  if (!opts.target) {
+    console.error('Usage: pompelmi watch <dir> [options]');
+    process.exit(2);
+  }
+
+  const target = path.resolve(opts.target);
+  if (!fs.existsSync(target)) {
+    console.error(`Error: directory not found: ${target}`);
+    process.exit(2);
+  }
+
+  if (!opts.json && !opts.quiet) await printLogo();
+
+  const { watch } = require('../src/Watcher.js');
+  const scanOpts = buildScanOpts(opts);
+
+  let scanned = 0, clean = 0, infected = 0;
+
+  function status() {
+    process.stdout.write(
+      `\rWatching ${target} • Scanned: ${scanned} • Clean: ${clean} • Infected: ${infected}  `
+    );
+  }
+
+  status();
+
+  watch(target, scanOpts, {
+    onClean(fp) {
+      scanned++; clean++;
+      if (!opts.quiet) process.stdout.write(`\n\x1b[32m✅ CLEAN\x1b[0m  ${fp}\n`);
+      status();
+    },
+    onMalicious(fp) {
+      scanned++; infected++;
+      process.stdout.write(`\n\x1b[31m🚨 INFECTED\x1b[0m  ${fp}\n`);
+      status();
+    },
+    onError(err) {
+      scanned++;
+      if (!opts.quiet) process.stdout.write(`\n\x1b[33m⚠️ ERROR\x1b[0m  ${err.message}\n`);
+      status();
+    },
+  });
+
+  process.on('SIGINT', () => { process.stdout.write('\n'); process.exit(0); });
+}
+
+function cmdVersion() {
+  console.log(pkg.version);
+}
+
+function cmdHelp() {
+  console.log(`
+pompelmi v${pkg.version} — ClamAV Antivirus Scanning for Node.js
+
+USAGE
+  pompelmi <command> [options]
+
+COMMANDS
+  scan <file|dir>    Scan a file or directory for viruses
+  watch <dir>        Watch a directory and auto-scan new/modified files
+  version            Print version number
+  help               Show this help message
+
+SCAN OPTIONS
+  --recursive, -r    Scan directory recursively (default: true)
+  --host <host>      clamd host (default: localhost, uses local clamscan if omitted)
+  --port <port>      clamd port (default: 3310)
+  --socket <path>    UNIX socket path (e.g. /run/clamav/clamd.sock)
+  --timeout <ms>     Connection timeout in ms (default: 15000)
+  --retries <n>      Auto-retry on connection failure (default: 0)
+  --json             Output results as JSON (no logo, no colors)
+  --quiet, -q        Only print infected files and summary
+  --delete           Delete infected files after confirmation
+
+WATCH OPTIONS
+  --host, --port, --socket, --timeout   (same as scan)
+
+EXIT CODES
+  0   All files clean
+  1   Virus found
+  2   Scan error
+  3   clamd unreachable
+
+EXAMPLES
+  # Scan a single file (local clamscan)
+  pompelmi scan ./upload.pdf
+
+  # Scan a directory recursively
+  pompelmi scan ./uploads --recursive
+
+  # Scan via clamd over TCP
+  pompelmi scan ./uploads --host 127.0.0.1 --port 3310
+
+  # Scan via UNIX socket
+  pompelmi scan ./uploads --socket /run/clamav/clamd.sock
+
+  # JSON output for scripting
+  pompelmi scan ./uploads --json
+
+  # Watch a directory
+  pompelmi watch ./uploads --host 127.0.0.1 --port 3310
+
+  # Use with npx (no install required)
+  npx pompelmi scan ./uploads
+`);
+}
+
+// ── Entry point ───────────────────────────────────────────────────────────────
+
+async function main() {
+  const opts = parseArgs(process.argv);
+
+  if (!opts.command || opts.command === 'help') {
+    await printLogo();
+    cmdHelp();
+    process.exit(0);
+  }
+
+  if (opts.command === 'version') {
+    cmdVersion();
+    process.exit(0);
+  }
+
+  if (opts.command === 'scan') {
+    await cmdScan(opts);
+    return;
+  }
+
+  if (opts.command === 'watch') {
+    await cmdWatch(opts);
+    return;
+  }
+}
+
+main().catch(err => {
+  console.error('\x1b[31mError:\x1b[0m', err.message);
+  process.exit(2);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pompelmi",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "ClamAV for humans — scan any file and get back Clean, Malicious, or ScanError. No daemons. No cloud. No native bindings.",
   "license": "ISC",
   "author": "pompelmi contributors",
@@ -33,6 +33,9 @@
   "type": "commonjs",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
+  "bin": {
+    "pompelmi": "./bin/pompelmi.js"
+  },
   "scripts": {
     "test": "node --test test/unit.test.js && node test/scan.test.js",
     "lint": "eslint src/"
@@ -40,7 +43,9 @@
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },
-  "dependencies": {},
+  "dependencies": {
+    "terminal-image": "^4.3.0"
+  },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "eslint": "^10.2.0",