pompelmi 1.17.0 → 1.19.0

package/README.md

@@ -11,6 +11,7 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/pompelmi"><img src="https://img.shields.io/npm/v/pompelmi.svg" alt="npm version"></a>
   <a href="https://www.npmjs.com/package/pompelmi"><img src="https://img.shields.io/npm/dw/pompelmi" alt="weekly downloads"></a>
+  <a href="https://hub.docker.com/r/justsouichi/pompelmi-scanner"><img src="https://img.shields.io/docker/pulls/justsouichi/pompelmi-scanner" alt="Docker Pulls"></a>
   <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="zero dependencies">
   <img src="https://img.shields.io/badge/license-ISC-blue" alt="license">
   <a href="https://github.com/pompelmi/pompelmi/actions/workflows/ci.yml"><img src="https://github.com/pompelmi/pompelmi/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
@@ -73,6 +74,10 @@ 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`
+- **Official Docker image** — `justsouichi/pompelmi-scanner` on Docker Hub: ClamAV + HTTP scan API in one pull ([docs](./docs/docker-image.html))
+- **Security scorecard** — grade your upload security A–F with `npx pompelmi scorecard` ([docs](./docs/scorecard.html))
+- **VS Code extension** — scan files directly from the IDE (scaffold in `packages/vscode/`) ([docs](./docs/vscode.html))
+- **Quarantine mode** — `watch ./uploads --quarantine ./quarantine` auto-moves infected files with sidecar JSON
 - HTML security dashboard — generate beautiful scan reports with `--report` ([docs](./docs/dashboard.html))
 - SVG share card — shareable scan result card with `--share-card` ([docs](./docs/dashboard.html#share-card))
 - GitHub App — one-click installation for organizations, zero-config PR scanning ([docs](./docs/github-app.html))
@@ -85,6 +90,10 @@ Most integrations require parsing ClamAV's stdout with regex, managing a clamd d
 - `watch(dirPath, [options], callbacks)` — watch a directory and auto-scan new/modified files (300 ms debounce)
 - `notify(webhookUrl, scanResult, [options])` — send a POST webhook notification when a virus is detected; optional HMAC-SHA256 signing via `X-Pompelmi-Signature`; zero extra dependencies
 - `createScanner([options])` — EventEmitter-based scanner; call `.scan(filePath)` or `.scanDirectory(dirPath)` and listen to `'clean'`, `'malicious'`, `'scanError'`, and `'error'` events
+- **SHA256 scan cache** — `createCache([options])` — skip rescanning known-clean files; LRU eviction, configurable TTL, optional file-backed persistence; zero extra dependencies ([docs](./docs/cache.html))
+- **Scan policies** — `createPolicy(rules)` — unified size, MIME type, extension, and virus rules in one object; Express middleware and NestJS guard included ([docs](./docs/policy.html))
+- **Multi-engine scanning** — `createMultiEngine(options)` — combine ClamAV and VirusTotal with `any`/`all`/`majority` consensus; per-engine verdict breakdown; zero extra dependencies ([docs](./docs/multi-engine.html))
+- **Directory streaming** — `scanDirectory.stream(dirPath)` — async-iterable progress events (`progress` / `result` / `complete`) for real-time UI feedback
 - Auto-retry on connection error — `retries` and `retryDelay` options on every scan function
 - Symbol-based verdicts (`Verdict.Clean` / `Verdict.Malicious` / `Verdict.ScanError`) — typo-proof comparisons
 - Full clamd support via the INSTREAM protocol — TCP (`host`/`port`) or UNIX socket (`socket`) with configurable timeout
@@ -617,6 +626,8 @@ Please read [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) before contributing. To r
 - [x] Cloudflare Workers support — `@pompelmi/cloudflare` ships in v1.17.0
 - [x] NestJS official module — `PompelmiModule.forRoot()` with injectable `PompelmiService`
 
+**Pompelmi Cloud** is on the horizon — a hosted REST API for file scanning with zero infrastructure to manage. Drop-in HTTP endpoint, no ClamAV to maintain, no daemon to run. [Join the waitlist](https://pompelmi.app/cloud.html) to be notified when it launches.
+
 ---
 
 ## License

package/bin/pompelmi.js

@@ -71,12 +71,14 @@ function parseArgs(argv) {
     reportOutput: null,
     shareCard: false,
     shareCardOutput: null,
+    quarantine: null,
+    scorecardConfig: null,
   };
 
   let i = 0;
   while (i < args.length) {
     const a = args[i];
-    if (a === 'scan' || a === 'watch' || a === 'version' || a === 'help') {
+    if (a === 'scan' || a === 'watch' || a === 'version' || a === 'help' || a === 'scorecard') {
       opts.command = a;
     } else if (a === '--json') {
       opts.json = true;
@@ -104,6 +106,10 @@ function parseArgs(argv) {
       const next = args[++i];
       if (next && next.endsWith('.svg')) opts.shareCardOutput = next;
       else opts.reportOutput = next;
+    } else if (a === '--quarantine') {
+      opts.quarantine = args[++i];
+    } else if (a === '--config') {
+      opts.scorecardConfig = args[++i];
     } else if (!a.startsWith('-') && opts.command && !opts.target) {
       opts.target = a;
     }
@@ -333,7 +339,9 @@ async function cmdWatch(opts) {
   if (!opts.json && !opts.quiet) await printLogo();
 
   const { watch } = require('../src/Watcher.js');
-  const scanOpts = buildScanOpts(opts);
+  const quarantineDir = opts.quarantine ? path.resolve(opts.quarantine) : null;
+  const watchOpts = { ...buildScanOpts(opts) };
+  if (quarantineDir) watchOpts.quarantine = quarantineDir;
 
   let scanned = 0, clean = 0, infected = 0;
 
@@ -345,7 +353,7 @@ async function cmdWatch(opts) {
 
   status();
 
-  watch(target, scanOpts, {
+  watch(target, watchOpts, {
     onClean(fp) {
       scanned++; clean++;
       if (!opts.quiet) process.stdout.write(`\n\x1b[32m✅ CLEAN\x1b[0m  ${fp}\n`);
@@ -354,6 +362,7 @@ async function cmdWatch(opts) {
     onMalicious(fp) {
       scanned++; infected++;
       process.stdout.write(`\n\x1b[31m🚨 INFECTED\x1b[0m  ${fp}\n`);
+      if (quarantineDir && !opts.quiet) process.stdout.write(`   Quarantined to ${quarantineDir}\n`);
       status();
     },
     onError(err) {
@@ -366,6 +375,44 @@ async function cmdWatch(opts) {
   process.on('SIGINT', () => { process.stdout.write('\n'); process.exit(0); });
 }
 
+async function cmdScorecard(opts) {
+  let config = {};
+  if (opts.scorecardConfig) {
+    const cfgPath = path.resolve(opts.scorecardConfig);
+    if (!fs.existsSync(cfgPath)) {
+      console.error(`Error: config file not found: ${cfgPath}`);
+      process.exit(2);
+    }
+    config = require(cfgPath);
+  }
+
+  const { generateScorecard } = require('../src/Scorecard.js');
+  const scorecard = await generateScorecard(config);
+
+  const gradeColor = { A: '\x1b[32m', B: '\x1b[32m', C: '\x1b[33m', D: '\x1b[33m', F: '\x1b[31m' };
+  const color = gradeColor[scorecard.grade] || '\x1b[0m';
+  const reset = '\x1b[0m';
+
+  if (!opts.quiet) await printLogo();
+
+  console.log(`\n  Upload Security Scorecard\n`);
+  console.log(`  Grade: ${color}${scorecard.grade}${reset}   Score: ${scorecard.score}/100\n`);
+
+  for (const f of scorecard.findings) {
+    const icon = f.status === 'pass' ? '\x1b[32m✓\x1b[0m' : '\x1b[31m✗\x1b[0m';
+    console.log(`  ${icon}  ${f.check.padEnd(40)} (weight: ${f.weight})`);
+  }
+
+  if (scorecard.recommendations.length > 0) {
+    console.log(`\n  Recommendations:`);
+    for (const r of scorecard.recommendations) {
+      console.log(`    • ${r}`);
+    }
+  }
+
+  console.log('');
+}
+
 function cmdVersion() {
   console.log(pkg.version);
 }
@@ -380,6 +427,7 @@ USAGE
 COMMANDS
   scan <file|dir>    Scan a file or directory for viruses
   watch <dir>        Watch a directory and auto-scan new/modified files
+  scorecard          Grade your upload security configuration (A-F)
   version            Print version number
   help               Show this help message
 
@@ -400,6 +448,10 @@ SCAN OPTIONS
 
 WATCH OPTIONS
   --host, --port, --socket, --timeout   (same as scan)
+  --quarantine <dir>  Move infected files to this directory (auto-created)
+
+SCORECARD OPTIONS
+  --config <file>     Path to a pompelmi.config.js file with your upload config
 
 EXIT CODES
   0   All files clean
@@ -428,6 +480,12 @@ EXAMPLES
 
   # Use with npx (no install required)
   npx pompelmi scan ./uploads
+
+  # Watch a directory with quarantine
+  pompelmi watch ./uploads --quarantine ./quarantine
+
+  # Grade your upload security config
+  npx pompelmi scorecard --config ./pompelmi.config.js
 `);
 }
 
@@ -456,6 +514,11 @@ async function main() {
     await cmdWatch(opts);
     return;
   }
+
+  if (opts.command === 'scorecard') {
+    await cmdScorecard(opts);
+    return;
+  }
 }
 
 main().catch(err => {

package/docker/Dockerfile

@@ -0,0 +1,18 @@
+FROM node:20-slim
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+      clamav clamav-freshclam curl && \
+    rm -rf /var/lib/apt/lists/* && \
+    sed -i 's/^Example/#Example/' /etc/clamav/freshclam.conf && \
+    mkdir -p /var/lib/clamav /run/clamav /uploads
+
+WORKDIR /app
+RUN npm install -g pompelmi
+
+COPY docker/entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+EXPOSE 3310 8080
+
+ENTRYPOINT ["/entrypoint.sh"]

package/docker/README.md

@@ -0,0 +1,62 @@
+# justsouichi/pompelmi-scanner Docker Image
+
+Official Docker image for pompelmi — ClamAV antivirus scanning for Node.js.
+
+The image ships with:
+- ClamAV + clamd pre-installed
+- freshclam for automatic definition updates on startup
+- A minimal HTTP API server on port 8080
+
+## Quick start
+
+```bash
+docker pull justsouichi/pompelmi-scanner
+docker run -p 8080:8080 justsouichi/pompelmi-scanner
+```
+
+## Scan a file
+
+```bash
+curl -F "file=@./document.pdf" http://localhost:8080/scan
+```
+
+Response:
+
+```json
+{ "verdict": "clean", "file": "document.pdf", "viruses": [] }
+```
+
+For an infected file the verdict is `"malicious"`.
+
+## Endpoints
+
+| Method | Path      | Description                                             |
+|--------|-----------|---------------------------------------------------------|
+| POST   | /scan     | Accepts `multipart/form-data` with a `file` field. Returns `{ verdict, file, viruses }` |
+| GET    | /health   | Returns `{ status: "ok", clamd: "running" }` |
+| GET    | /stats    | Returns scan statistics (total, clean, infected, errors, uptime) |
+
+## Docker Compose
+
+```yaml
+services:
+  pompelmi:
+    image: justsouichi/pompelmi-scanner
+    ports:
+      - "8080:8080"
+    volumes:
+      - /uploads:/uploads
+    restart: unless-stopped
+```
+
+## Environment
+
+The container exposes two ports:
+- **8080** — HTTP scan API
+- **3310** — clamd TCP socket (for direct clamd connections from other containers)
+
+## Building locally
+
+```bash
+docker build -f docker/Dockerfile -t justsouichi/pompelmi-scanner .
+```

package/docker/entrypoint.sh

@@ -0,0 +1,148 @@
+#!/bin/sh
+set -e
+
+# ── Update ClamAV virus definitions ──────────────────────────────────────────
+echo "[pompelmi] Updating ClamAV definitions via freshclam..."
+freshclam --quiet || echo "[pompelmi] freshclam failed — continuing with existing definitions"
+
+# ── Start clamd in background ─────────────────────────────────────────────────
+echo "[pompelmi] Starting clamd..."
+clamd &
+CLAMD_PID=$!
+
+# Wait for clamd socket/port to be ready
+echo "[pompelmi] Waiting for clamd to be ready..."
+for i in $(seq 1 30); do
+  if clamdscan --no-summary /dev/null 2>/dev/null; then
+    echo "[pompelmi] clamd is ready"
+    break
+  fi
+  sleep 1
+done
+
+# ── Stats counters (stored in files for simplicity) ───────────────────────────
+STATS_DIR=/tmp/pompelmi-stats
+mkdir -p "$STATS_DIR"
+echo 0 > "$STATS_DIR/total"
+echo 0 > "$STATS_DIR/clean"
+echo 0 > "$STATS_DIR/infected"
+echo 0 > "$STATS_DIR/errors"
+
+# ── Minimal HTTP server ───────────────────────────────────────────────────────
+# Uses Node.js (already available from the base image)
+node - <<'EOF'
+'use strict';
+
+const http      = require('http');
+const fs        = require('fs');
+const os        = require('os');
+const path      = require('path');
+const { execSync, exec } = require('child_process');
+const { scanBuffer } = require('pompelmi');
+const { Verdict } = require('pompelmi');
+
+const PORT = 8080;
+const STATS = { total: 0, clean: 0, infected: 0, errors: 0, startedAt: new Date().toISOString() };
+
+function parseMultipart(req) {
+  return new Promise((resolve, reject) => {
+    const boundary = (req.headers['content-type'] || '').split('boundary=')[1];
+    if (!boundary) return reject(new Error('Missing multipart boundary'));
+
+    const chunks = [];
+    req.on('data', c => chunks.push(c));
+    req.on('error', reject);
+    req.on('end', () => {
+      const body   = Buffer.concat(chunks);
+      const delim  = Buffer.from('\r\n--' + boundary);
+      const parts  = [];
+      let start    = body.indexOf('--' + boundary);
+
+      while (start !== -1) {
+        const headerEnd = body.indexOf('\r\n\r\n', start);
+        if (headerEnd === -1) break;
+        const headerStr = body.slice(start, headerEnd).toString();
+        const nameMatch = headerStr.match(/name="([^"]+)"/);
+        const fileMatch = headerStr.match(/filename="([^"]+)"/);
+        const dataStart = headerEnd + 4;
+        const nextDelim = body.indexOf(delim, dataStart);
+        const dataEnd   = nextDelim === -1 ? body.indexOf('\r\n--' + boundary + '--', dataStart) : nextDelim;
+        if (dataEnd === -1) break;
+        parts.push({
+          name:     nameMatch  ? nameMatch[1]  : '',
+          filename: fileMatch  ? fileMatch[1]  : '',
+          data:     body.slice(dataStart, dataEnd),
+        });
+        start = body.indexOf('--' + boundary, dataEnd);
+        if (body.slice(start, start + boundary.length + 6).toString().includes('--\r\n')) break;
+      }
+      resolve(parts);
+    });
+  });
+}
+
+function isClamdRunning() {
+  try { execSync('clamdscan --no-summary /dev/null 2>/dev/null'); return true; }
+  catch { return false; }
+}
+
+const server = http.createServer(async (req, res) => {
+  res.setHeader('Content-Type', 'application/json');
+
+  if (req.method === 'GET' && req.url === '/health') {
+    res.writeHead(200);
+    return res.end(JSON.stringify({ status: 'ok', clamd: isClamdRunning() ? 'running' : 'unavailable' }));
+  }
+
+  if (req.method === 'GET' && req.url === '/stats') {
+    res.writeHead(200);
+    return res.end(JSON.stringify({ ...STATS, uptime: process.uptime() }));
+  }
+
+  if (req.method === 'POST' && req.url === '/scan') {
+    try {
+      const parts = await parseMultipart(req);
+      const filePart = parts.find(p => p.filename);
+      if (!filePart) {
+        res.writeHead(400);
+        return res.end(JSON.stringify({ error: 'No file field in request' }));
+      }
+
+      STATS.total++;
+      const verdict = await scanBuffer(filePart.data);
+
+      let result;
+      if (verdict === Verdict.Clean) {
+        STATS.clean++;
+        result = { verdict: 'clean', file: filePart.filename, viruses: [] };
+      } else if (verdict === Verdict.Malicious) {
+        STATS.infected++;
+        result = { verdict: 'malicious', file: filePart.filename, viruses: [] };
+      } else {
+        STATS.errors++;
+        result = { verdict: 'error', file: filePart.filename, viruses: [] };
+      }
+
+      res.writeHead(200);
+      return res.end(JSON.stringify(result));
+    } catch (err) {
+      STATS.errors++;
+      res.writeHead(500);
+      return res.end(JSON.stringify({ error: err.message }));
+    }
+  }
+
+  res.writeHead(404);
+  res.end(JSON.stringify({ error: 'Not found' }));
+});
+
+server.listen(PORT, () => {
+  console.log(`[pompelmi] HTTP scan server listening on port ${PORT}`);
+  console.log(`[pompelmi] POST /scan   — scan a file`);
+  console.log(`[pompelmi] GET  /health — health check`);
+  console.log(`[pompelmi] GET  /stats  — scan statistics`);
+});
+
+process.on('SIGTERM', () => { server.close(); process.exit(0); });
+process.on('SIGINT',  () => { server.close(); process.exit(0); });
+EOF

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pompelmi",
-  "version": "1.17.0",
+  "version": "1.19.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",

package/packages/vscode/README.md

@@ -0,0 +1,61 @@
+# pompelmi — VS Code Extension
+
+Scan files for viruses directly from VS Code using pompelmi and ClamAV.
+
+## Requirements
+
+- [ClamAV](https://www.clamav.net/) installed (or clamd running via Docker)
+- Node.js and npm available in your PATH
+
+## Installation
+
+Install from the VS Code Marketplace:
+
+1. Open VS Code
+2. Press `Ctrl+P` (or `Cmd+P` on macOS)
+3. Run: `ext install pompelmi.pompelmi`
+
+## Usage
+
+### Scan a single file
+
+Right-click any file in the Explorer sidebar and select **"Scan with pompelmi"**.
+
+Results appear as VS Code notifications:
+
+- `✅ file.pdf — Clean`
+- `🚨 malware.exe — INFECTED (Win.Malware.Agent)`
+
+### Scan the workspace
+
+Open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and run:
+
+```
+pompelmi: Scan Workspace
+```
+
+### Configure
+
+Run `pompelmi: Configure` from the Command Palette to open settings.
+
+## Settings
+
+| Setting           | Default     | Description                              |
+|-------------------|-------------|------------------------------------------|
+| `pompelmi.host`   | `localhost` | clamd host                               |
+| `pompelmi.port`   | `3310`      | clamd port                               |
+| `pompelmi.socket` | *(empty)*   | clamd UNIX socket path (takes precedence over host/port) |
+
+## Using with Docker
+
+Start clamd via the official pompelmi Docker image:
+
+```bash
+docker run -p 3310:3310 -p 8080:8080 justsouichi/pompelmi-scanner
+```
+
+Then set `pompelmi.host` to `localhost` and `pompelmi.port` to `3310`.
+
+## License
+
+ISC © pompelmi contributors

package/packages/vscode/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "pompelmi",
+  "displayName": "pompelmi — Antivirus File Scanner",
+  "description": "Scan files for viruses directly from VS Code using pompelmi and ClamAV.",
+  "version": "0.1.0",
+  "publisher": "pompelmi",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pompelmi/pompelmi.git"
+  },
+  "engines": {
+    "vscode": "^1.85.0"
+  },
+  "categories": ["Other", "Linters"],
+  "keywords": ["antivirus", "clamav", "security", "malware", "virus"],
+  "icon": "icon.png",
+  "activationEvents": [
+    "onCommand:pompelmi.scanFile"
+  ],
+  "main": "./src/extension.js",
+  "contributes": {
+    "commands": [
+      {
+        "command": "pompelmi.scanFile",
+        "title": "Scan with pompelmi",
+        "category": "pompelmi"
+      },
+      {
+        "command": "pompelmi.scanWorkspace",
+        "title": "Scan Workspace",
+        "category": "pompelmi"
+      },
+      {
+        "command": "pompelmi.configure",
+        "title": "Configure pompelmi",
+        "category": "pompelmi"
+      }
+    ],
+    "menus": {
+      "explorer/context": [
+        {
+          "command": "pompelmi.scanFile",
+          "when": "resourceScheme == 'file'",
+          "group": "7_modification"
+        }
+      ]
+    },
+    "configuration": {
+      "title": "pompelmi",
+      "properties": {
+        "pompelmi.host": {
+          "type": "string",
+          "default": "localhost",
+          "description": "clamd host"
+        },
+        "pompelmi.port": {
+          "type": "number",
+          "default": 3310,
+          "description": "clamd port"
+        },
+        "pompelmi.socket": {
+          "type": "string",
+          "default": "",
+          "description": "clamd UNIX socket path (e.g. /run/clamav/clamd.sock)"
+        }
+      }
+    }
+  }
+}

package/packages/vscode/src/extension.js

@@ -0,0 +1,109 @@
+'use strict';
+
+const { execFile } = require('child_process');
+const path         = require('path');
+
+function getScanOptions(vscode) {
+  const cfg    = vscode.workspace.getConfiguration('pompelmi');
+  const host   = cfg.get('host', 'localhost');
+  const port   = cfg.get('port', 3310);
+  const socket = cfg.get('socket', '');
+  const args   = ['scan'];
+  if (socket) { args.push('--socket', socket); }
+  else        { args.push('--host', host, '--port', String(port)); }
+  args.push('--json');
+  return args;
+}
+
+function runScan(filePath, args, callback) {
+  const allArgs = [...args, filePath];
+  execFile('npx', ['pompelmi', ...allArgs], { timeout: 30000 }, (err, stdout) => {
+    if (err && !stdout) return callback(err, null);
+    try {
+      const result = JSON.parse(stdout);
+      callback(null, result);
+    } catch {
+      callback(new Error('Failed to parse pompelmi output'), null);
+    }
+  });
+}
+
+function activate(context) {
+  const vscode = require('vscode');
+
+  const scanFileCmd = vscode.commands.registerCommand('pompelmi.scanFile', async (uri) => {
+    const filePath = uri ? uri.fsPath : vscode.window.activeTextEditor?.document.uri.fsPath;
+    if (!filePath) {
+      vscode.window.showErrorMessage('pompelmi: No file selected.');
+      return;
+    }
+
+    const args = getScanOptions(vscode);
+    vscode.window.withProgress(
+      { location: vscode.ProgressLocation.Notification, title: `pompelmi: scanning ${path.basename(filePath)}...` },
+      () => new Promise(resolve => {
+        runScan(filePath, args, (err, result) => {
+          resolve();
+          if (err) {
+            vscode.window.showErrorMessage(`pompelmi error: ${err.message}`);
+            return;
+          }
+          const r = result?.results?.[0];
+          if (!r) {
+            vscode.window.showErrorMessage('pompelmi: unexpected response');
+            return;
+          }
+          if (r.verdict === 'clean') {
+            vscode.window.showInformationMessage(`✅ ${path.basename(filePath)} — Clean`);
+          } else if (r.verdict === 'infected') {
+            const virus = r.viruses?.[0] ? ` (${r.viruses[0]})` : '';
+            vscode.window.showErrorMessage(`🚨 ${path.basename(filePath)} — INFECTED${virus}`);
+          } else {
+            vscode.window.showWarningMessage(`⚠️ ${path.basename(filePath)} — Scan error`);
+          }
+        });
+      })
+    );
+  });
+
+  const scanWorkspaceCmd = vscode.commands.registerCommand('pompelmi.scanWorkspace', async () => {
+    const folders = vscode.workspace.workspaceFolders;
+    if (!folders || folders.length === 0) {
+      vscode.window.showErrorMessage('pompelmi: No workspace folder open.');
+      return;
+    }
+
+    const args = getScanOptions(vscode);
+    const dirPath = folders[0].uri.fsPath;
+
+    vscode.window.withProgress(
+      { location: vscode.ProgressLocation.Notification, title: 'pompelmi: scanning workspace...' },
+      () => new Promise(resolve => {
+        runScan(dirPath, args, (err, result) => {
+          resolve();
+          if (err) {
+            vscode.window.showErrorMessage(`pompelmi error: ${err.message}`);
+            return;
+          }
+          const infected = result?.infected ?? 0;
+          const scanned  = result?.scanned  ?? 0;
+          if (infected === 0) {
+            vscode.window.showInformationMessage(`✅ Workspace scan complete — ${scanned} files scanned, all clean.`);
+          } else {
+            vscode.window.showErrorMessage(`🚨 Workspace scan — ${infected} infected file(s) found out of ${scanned} scanned.`);
+          }
+        });
+      })
+    );
+  });
+
+  const configureCmd = vscode.commands.registerCommand('pompelmi.configure', () => {
+    vscode.commands.executeCommand('workbench.action.openSettings', 'pompelmi');
+  });
+
+  context.subscriptions.push(scanFileCmd, scanWorkspaceCmd, configureCmd);
+}
+
+function deactivate() {}
+
+module.exports = { activate, deactivate };