pompelmi 1.5.0 → 1.7.0

package/README.md

@@ -6,33 +6,27 @@
 
 <p align="center"><strong>ClamAV antivirus scanning for Node.js — clean, typed, zero dependencies.</strong></p>
 
-<p align="center">
-  <img src="https://img.shields.io/npm/v/pompelmi.svg" alt="npm version">
-  <img src="https://img.shields.io/npm/dw/pompelmi" alt="npm downloads">
-  <img src="https://img.shields.io/badge/license-ISC-blue.svg" alt="license">
-  <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="dependencies">
-</p>
+<br>
 
 <p align="center">
-  <img src="https://github.com/pompelmi/pompelmi/actions/workflows/ci.yml/badge.svg" alt="Node.js CI">
-  <img src="https://github.com/pompelmi/pompelmi/actions/workflows/release.yml/badge.svg" alt="npm publish">
+  <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>
+  <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>
+  <a href="https://github.com/pompelmi/pompelmi/actions/workflows/release.yml"><img src="https://github.com/pompelmi/pompelmi/actions/workflows/release.yml/badge.svg" alt="npm publish"></a>
 </p>
 
-<p align="center">
-  <img src="https://img.shields.io/badge/express-available-black?logo=express" alt="Express">
-  <img src="https://img.shields.io/badge/fastify-available-black?logo=fastify" alt="Fastify">
-  <img src="https://img.shields.io/badge/nestjs-available-red?logo=nestjs" alt="NestJS">
-  <img src="https://img.shields.io/badge/koa-available-lightgrey?logo=node.js" alt="Koa">
-  <img src="https://img.shields.io/badge/hono-available-orange" alt="Hono">
-  <img src="https://img.shields.io/badge/next.js-available-black?logo=next.js" alt="Next.js">
-  <img src="https://img.shields.io/badge/sveltekit-available-red?logo=svelte" alt="SvelteKit">
-  <img src="https://img.shields.io/badge/remix-available-black?logo=remix" alt="Remix">
-  <img src="https://img.shields.io/badge/docker-available-blue?logo=docker" alt="Docker">
-</p>
+---
 
-<p align="center">
-  <img src="https://img.shields.io/github/stars/pompelmi/pompelmi?style=social" alt="GitHub stars">
-</p>
+## 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 |
+| [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 |
 
 ---
 
@@ -43,7 +37,7 @@ pompelmi is a minimal Node.js wrapper around [ClamAV](https://www.clamav.net/) t
 It supports two scanning modes:
 
 - **Local** — spawns `clamscan` as a child process and maps its exit code to a verdict. No stdout parsing, no regex.
-- **Remote / Docker** — streams the file to a running `clamd` daemon over TCP using the ClamAV `INSTREAM` protocol.
+- **Remote / Docker / UNIX socket** — streams the file to a running `clamd` daemon over TCP or a UNIX domain socket using the ClamAV `INSTREAM` protocol.
 
 No cloud. No daemon required for local mode. No native bindings. Zero runtime dependencies.
 
@@ -64,7 +58,7 @@ Most integrations require parsing ClamAV's stdout with regex, managing a clamd d
 - `scanStream(stream, [options])` — scan a Readable stream directly. In TCP mode, streamed to clamd with no disk I/O.
 - `scanDirectory(dirPath, [options])` — recursively scan every file in a directory, returns clean/malicious/errors arrays
 - Symbol-based verdicts (`Verdict.Clean` / `Verdict.Malicious` / `Verdict.ScanError`) — typo-proof comparisons
-- Full TCP/clamd support via the INSTREAM protocol with configurable host, port, and timeout
+- Full clamd support via the INSTREAM protocol — TCP (`host`/`port`) or UNIX socket (`socket`) with configurable timeout
 - Built-in helpers to install ClamAV and update virus definitions programmatically
 - Works with Express, Fastify, and any other Node.js HTTP framework
 - Zero runtime dependencies — ships nothing but source code
@@ -280,17 +274,19 @@ if (result === Verdict.ScanError) console.warn('Scan incomplete.');
 
 ## Docker / Remote Scanning
 
-Pass `host` and `port` to switch from the local `clamscan` CLI to the clamd TCP daemon. Everything else — the returned verdicts, error types — is identical.
+Pass `host` and `port` (or `socket`) to switch from the local `clamscan` CLI to the clamd daemon. Everything else — the returned verdicts, error types — is identical.
 
+**TCP:**
 ```js
-const result = await scan('/path/to/file.zip', {
-  host:    '127.0.0.1',
-  port:    3310,
-  timeout: 30_000, // socket idle timeout, ms — default 15 000
-});
+const result = await scan('/path/to/file.zip', { host: '127.0.0.1', port: 3310 });
 ```
 
-pompelmi uses the ClamAV `INSTREAM` protocol: the file is streamed in 64 KB chunks, each prefixed with a 4-byte big-endian length header, terminated by four zero bytes. The response line (`stream: OK`, `stream: <name> FOUND`, or an error) is mapped to the same verdict Symbols.
+**UNIX socket:**
+```js
+const result = await scan('/path/to/file.zip', { socket: '/run/clamav/clamd.sock' });
+```
+
+See **[docs/docker.md](./docs/docker.md)** for Docker Compose examples, UNIX socket volume mounts, `scanBuffer` / `scanStream` in clamd mode, and connection retry patterns.
 
 ---
 
@@ -300,215 +296,137 @@ pompelmi has no configuration file or environment variables. All options are pas
 
 | Option    | Type     | Default         | Description                            |
 |-----------|----------|-----------------|----------------------------------------|
+| `socket`  | `string` | —               | Path to a clamd UNIX domain socket (e.g. `/run/clamav/clamd.sock`). Takes precedence over `host`/`port` when set. |
 | `host`    | `string` | —               | clamd hostname. Enables TCP mode when set. |
 | `port`    | `number` | `3310`          | clamd port.                            |
-| `timeout` | `number` | `15000`         | Socket idle timeout in milliseconds (TCP mode only). |
+| `timeout` | `number` | `15000`         | Socket idle timeout in milliseconds (clamd mode only). |
 
-When neither `host` nor `port` is provided, pompelmi spawns `clamscan --no-summary <filePath>` locally.
+When none of `socket`, `host`, or `port` is provided, pompelmi spawns `clamscan --no-summary <filePath>` locally.
 
 ---
 
 ## API Reference
 
-### `scan(filePath, [options])`
-
-```ts
-scan(
-  filePath: string,
-  options?: { host?: string; port?: number; timeout?: number }
-): Promise<symbol>
-```
+See **[docs/api.md](./docs/api.md)** for the full reference: function signatures, options table, verdict Symbols, error conditions, and error handling patterns.
 
-**Returns** a Promise that resolves to one of:
+**Quick summary:**
 
-| Verdict             | ClamAV exit code / response | Meaning                                                                 |
-|---------------------|-----------------------------|-------------------------------------------------------------------------|
-| `Verdict.Clean`     | `0` / `stream: OK`          | No threats found.                                                       |
-| `Verdict.Malicious` | `1` / `<name> FOUND`        | A known virus or malware signature was matched.                         |
-| `Verdict.ScanError` | `2` / other response        | Scan failed — I/O error, encrypted archive, permission denied. Treat file as untrusted. |
+| Function | Input | clamd mode disk I/O |
+|----------|-------|---------------------|
+| `scan(filePath, [options])` | File path on disk | None (streamed) |
+| `scanBuffer(buffer, [options])` | `Buffer` | None (streamed) |
+| `scanStream(stream, [options])` | Node.js `Readable` | None (streamed) |
+| `scanDirectory(dirPath, [options])` | Directory path | None (streamed) |
 
-**Rejects** with an `Error` in these cases:
+All four functions accept the same `options` object and resolve to the same three verdict Symbols:
 
-| Condition                             | Error message                     |
-|---------------------------------------|-----------------------------------|
-| `filePath` is not a string            | `filePath must be a string`       |
-| File does not exist                   | `File not found: <path>`          |
-| `clamscan` not in PATH                | `ENOENT` (from the OS)            |
-| ClamAV returns an unknown exit code   | `Unexpected exit code: N`         |
-| Process killed by signal              | `Process killed by signal: <SIG>` |
-| clamd connection timed out            | `clamd connection timed out after Nms` |
-
-Each `Verdict` Symbol exposes a `.description` property for safe serialisation:
-
-```js
-Verdict.Clean.description     // 'Clean'
-Verdict.Malicious.description // 'Malicious'
-Verdict.ScanError.description // 'ScanError'
-```
+| Symbol | Meaning |
+|--------|---------|
+| `Verdict.Clean` | No threats found |
+| `Verdict.Malicious` | Known signature matched |
+| `Verdict.ScanError` | Scan could not complete — treat as untrusted |
 
 ---
 
-### `scanBuffer(buffer, [options])`
-
-```ts
-scanBuffer(
-  buffer: Buffer,
-  options?: { host?: string; port?: number; timeout?: number }
-): Promise<symbol>
-```
-
-| Parameter | Type | Description |
-|---|---|---|
-| `buffer` | `Buffer` | The in-memory buffer to scan |
-| `options` | `object` | Same options as `scan()` — host, port, timeout |
-
-**Returns** the same three Symbol verdicts as `scan()`: `Verdict.Clean`, `Verdict.Malicious`, `Verdict.ScanError`.
-
-**Rejects** with the same error types as `scan()` where applicable, plus:
-
-| Condition | Error message |
-|---|---|
-| `buffer` is not a Buffer | `buffer must be a Buffer` |
-| `buffer` is empty | `buffer is empty` |
-
-In TCP mode (`host` or `port` provided), the buffer is streamed directly to clamd via the INSTREAM protocol — no data is written to disk. In local mode, a temp file is written to `os.tmpdir()` and deleted automatically in a `finally` block regardless of outcome.
+## Installing ClamAV
 
----
+```bash
+# macOS
+brew install clamav && freshclam
 
-### `scanStream(stream, [options])`
+# Linux (Debian / Ubuntu)
+sudo apt-get install -y clamav clamav-daemon && sudo freshclam
 
-```ts
-scanStream(
-  stream: Readable,
-  options?: { host?: string; port?: number; timeout?: number }
-): Promise<symbol>
+# Windows (Chocolatey)
+choco install clamav -y
 ```
 
-| Parameter | Type | Description |
-|---|---|---|
-| `stream` | `Readable` | Node.js Readable stream to scan |
-| `options` | `object` | Same options as `scan()` — host, port, timeout |
-
-**Returns** the same three Symbol verdicts as `scan()`: `Verdict.Clean`, `Verdict.Malicious`, `Verdict.ScanError`.
-
-**Rejects** with the same error types as `scan()` where applicable, plus:
-
-| Condition | Error message |
-|---|---|
-| `stream` is not a Readable | `stream must be a Readable` |
-| Stream emits error | propagated as-is |
-
-In TCP mode (`host` or `port` provided), the stream is piped directly to clamd via the INSTREAM protocol — no data is written to disk. In local mode, the stream is piped to a temp file in `os.tmpdir()` that is deleted automatically in a `finally` block.
-
 ---
 
-### `scanDirectory(dirPath, [options])`
-
-```ts
-scanDirectory(
-  dirPath: string,
-  options?: { host?: string; port?: number; timeout?: number }
-): Promise<{ clean: string[], malicious: string[], errors: string[] }>
-```
-
-Recursively scans every file in `dirPath` and returns three arrays of absolute paths.
-
-| Field | Type | Description |
-|---|---|---|
-| `clean` | `string[]` | Paths of files with no threats found |
-| `malicious` | `string[]` | Paths of files with a matched signature |
-| `errors` | `string[]` | Paths of files that could not be scanned |
-
-Per-file scan failures are caught and collected into `errors` — the function never throws because of an individual file.
+## Examples
 
-**Rejects** with an `Error` in these cases:
+The [`examples/`](./examples/) directory contains standalone runnable scripts. Each can be run with `node examples/<name>.js`.
 
-| Condition | Error message |
-|---|---|
-| `dirPath` is not a string | `dirPath must be a string` |
-| Directory does not exist | `Directory not found: <path>` |
+| File | Description |
+|------|-------------|
+| `basic-scan.js` | Scan a single file and log the verdict |
+| `scan-on-upload-express.js` | Express route: scan before saving |
+| `scan-on-upload-fastify.js` | Fastify route: same pattern |
+| `scan-with-options.js` | Remote clamd with custom host, port, timeout |
+| `handle-scan-error.js` | Handle every verdict including hard rejections |
+| `delete-on-malicious.js` | Auto-delete file if malicious |
+| `quarantine-on-malicious.js` | Move infected file to a quarantine folder |
+| `scan-multiple-files.js` | Concurrent scans with Promise.all |
+| `scan-directory.js` | Recursively scan every file in a directory |
+| `scan-buffer.js` | Scan an in-memory Buffer (multer memoryStorage) |
+| `scan-stream.js` | Scan a Readable stream (S3, HTTP, pipes) |
+| `rest-api-server.js` | Minimal HTTP server exposing POST /scan |
+| `s3-scan-before-upload.js` | Scan locally, then upload to S3 only if clean |
+| `cli-scan.js` | CLI tool: scan file paths, exit non-zero on threats |
+| `scan-with-timeout.js` | Timeout patterns for local and remote scanning |
+| `scan-pdf.js` | PDF upload with extension validation |
+| `scan-image.js` | Image upload with extension validation |
+| `scan-zip.js` | ZIP archive scan (ClamAV recurses automatically) |
+| `install-clamav.js` | Programmatic ClamAV installation |
+| `update-virus-database.js` | Programmatic virus DB update |
+| `typescript-usage.ts` | TypeScript example with inline type declarations |
 
 ---
 
-### `ClamAVInstaller()` _(internal)_
+## GitHub Action
 
-Installs ClamAV using the platform's native package manager. Resolves immediately if ClamAV is already installed.
+[![GitHub Marketplace](https://img.shields.io/badge/Marketplace-Pompelmi%20ClamAV%20Scanner-blue?logo=github)](https://github.com/marketplace/actions/pompelmi-clamav-scanner)
 
-```ts
-ClamAVInstaller(): Promise<string>
-```
+Scan any repository for viruses on every push or pull request — ClamAV is bundled inside a Docker container, virus definitions are auto-updated at runtime, and no external services are required.
 
-| Platform | Package manager | Command                                   |
-|----------|-----------------|-------------------------------------------|
-| macOS    | Homebrew        | `brew install clamav`                     |
-| Linux    | apt-get         | `sudo apt-get install -y clamav clamav-daemon` |
-| Windows  | Chocolatey      | `choco install clamav -y`                 |
-
----
+### Minimal usage
 
-### `updateClamAVDatabase()` _(internal)_
-
-Runs `freshclam` to download or refresh the virus definition database. Skips if the database file is already present.
+```yaml
+- uses: actions/checkout@v4
 
-```ts
-updateClamAVDatabase(): Promise<string>
+- name: Virus scan
+  uses: pompelmi/pompelmi@v1.7.0
 ```
 
-| Platform | Database path                         |
-|----------|---------------------------------------|
-| macOS    | `/usr/local/share/clamav/main.cvd`    |
-| Linux    | `/var/lib/clamav/main.cvd`            |
-| Windows  | `C:\ProgramData\ClamAV\main.cvd`      |
-
----
-
-## Installing ClamAV
-
-```bash
-# macOS
-brew install clamav && freshclam
-
-# Linux (Debian / Ubuntu)
-sudo apt-get install -y clamav clamav-daemon && sudo freshclam
+### Full example
 
-# Windows (Chocolatey)
-choco install clamav -y
+```yaml
+- uses: actions/checkout@v4
+
+- name: Virus scan
+  id: scan
+  uses: pompelmi/pompelmi@v1.7.0
+  with:
+    path: 'uploads/'        # scan a subdirectory instead of the whole workspace
+    fail-on-virus: 'true'   # fail the workflow step on detection (default)
+
+- name: Print infected files
+  if: always()
+  run: echo "${{ steps.scan.outputs.infected-files }}"
 ```
 
----
+### Inputs
 
-## Examples
+| Input | Description | Default |
+|-------|-------------|---------|
+| `path` | Directory or file to scan | `.` (full workspace) |
+| `fail-on-virus` | Fail the workflow step when infected files are found | `true` |
 
-The [`examples/`](./examples/) directory contains standalone runnable scripts. Each can be run directly with `node examples/<name>.js`.
+### Outputs
 
-| File | Description |
-|------|-------------|
-| [`basic-scan.js`](examples/basic-scan.js) | Scan a single file and log the verdict |
-| [`scan-on-upload-express.js`](examples/scan-on-upload-express.js) | Express route: scan before saving |
-| [`scan-on-upload-fastify.js`](examples/scan-on-upload-fastify.js) | Fastify route: same pattern |
-| [`scan-with-options.js`](examples/scan-with-options.js) | Remote clamd with custom host, port, timeout |
-| [`handle-scan-error.js`](examples/handle-scan-error.js) | Handle every verdict including hard rejections |
-| [`delete-on-malicious.js`](examples/delete-on-malicious.js) | Auto-delete file if malicious |
-| [`quarantine-on-malicious.js`](examples/quarantine-on-malicious.js) | Move infected file to a quarantine folder |
-| [`scan-multiple-files.js`](examples/scan-multiple-files.js) | Concurrent scans with `Promise.all` |
-| [`scan-directory.js`](examples/scan-directory.js) | Recursively scan every file in a directory |
-| [`scan-buffer.js`](examples/scan-buffer.js) | Scan an in-memory Buffer via a temp-file shim |
-| [`scan-stream.js`](examples/scan-stream.js) | Scan an S3 getObject Readable stream with scanStream() |
-| [`rest-api-server.js`](examples/rest-api-server.js) | Minimal HTTP server exposing `POST /scan` |
-| [`s3-scan-before-upload.js`](examples/s3-scan-before-upload.js) | Scan locally, then upload to S3 only if clean |
-| [`cli-scan.js`](examples/cli-scan.js) | CLI tool: scan file paths, exit non-zero on threats |
-| [`scan-with-timeout.js`](examples/scan-with-timeout.js) | Timeout patterns for local and remote scanning |
-| [`scan-pdf.js`](examples/scan-pdf.js) | PDF upload with extension validation |
-| [`scan-image.js`](examples/scan-image.js) | Image upload with extension validation |
-| [`scan-zip.js`](examples/scan-zip.js) | ZIP archive scan (ClamAV recurses automatically) |
-| [`install-clamav.js`](examples/install-clamav.js) | Programmatic ClamAV installation |
-| [`update-virus-database.js`](examples/update-virus-database.js) | Programmatic virus DB update |
-| [`typescript-usage.ts`](examples/typescript-usage.ts) | TypeScript example with inline type declarations |
+| Output | Description |
+|--------|-------------|
+| `infected-files` | Newline-separated list of infected file paths (empty when clean) |
+| `status` | `"clean"` or `"infected"` |
+
+A ready-to-copy workflow is available at [`.github/workflows/action-example.yml`](./.github/workflows/action-example.yml). Full reference — inputs, outputs, layer caching, and more examples — in **[docs/github-action.md](./docs/github-action.md)**.
 
 ---
 
 ## Contributing
 
+Full documentation and guides are available in the [Wiki](https://github.com/pompelmi/pompelmi/wiki).
+
 ```bash
 # 1. Clone and install dev dependencies
 git clone https://github.com/pompelmi/pompelmi.git

package/action/Dockerfile

@@ -0,0 +1,24 @@
+FROM node:20-slim
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+        clamav \
+        clamav-freshclam \
+    && rm -rf /var/lib/apt/lists/* \
+    && sed -i 's/^Example/#Example/' /etc/clamav/freshclam.conf \
+    && mkdir -p /var/lib/clamav /run/clamav
+
+WORKDIR /action
+
+# Bundle the pompelmi library from this repository
+COPY src/ ./src/
+COPY package.json ./
+
+# Action scripts
+COPY action/entrypoint.sh ./entrypoint.sh
+COPY action/scanner.js    ./scanner.js
+RUN chmod +x ./entrypoint.sh
+
+ENTRYPOINT ["/action/entrypoint.sh"]

package/action/entrypoint.sh

@@ -0,0 +1,23 @@
+#!/bin/sh
+set -e
+
+SCAN_PATH="${1:-.}"
+FAIL_ON_VIRUS="${2:-true}"
+
+# Resolve relative paths against the GitHub workspace mount point
+WORKSPACE="${GITHUB_WORKSPACE:-/github/workspace}"
+case "$SCAN_PATH" in
+    /*) FULL_PATH="$SCAN_PATH" ;;
+    *)  FULL_PATH="${WORKSPACE}/${SCAN_PATH}" ;;
+esac
+
+echo "::group::Updating ClamAV virus definitions (freshclam)"
+# Remove any stale lock left from previous container runs
+rm -f /run/clamav/freshclam.pid /run/lock/freshclam 2>/dev/null || true
+freshclam --quiet 2>&1 \
+    && echo "Definitions updated successfully." \
+    || echo "Warning: freshclam update failed — scanning with cached definitions."
+echo "::endgroup::"
+
+echo "Scanning: ${FULL_PATH}"
+exec node /action/scanner.js "${FULL_PATH}" "${FAIL_ON_VIRUS}"

package/action/scanner.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const { scan, scanDirectory, Verdict } = require('./src/index.js');
+
+const scanPath    = process.argv[2] || '.';
+const failOnVirus = process.argv[3] !== 'false';
+
+async function main() {
+    const resolved = path.resolve(scanPath);
+
+    if (!fs.existsSync(resolved)) {
+        console.error(`::error::Path not found: ${resolved}`);
+        process.exit(2);
+    }
+
+    let clean = [], malicious = [], errors = [];
+    const stat = fs.statSync(resolved);
+
+    if (stat.isDirectory()) {
+        const result = await scanDirectory(resolved);
+        clean     = result.clean;
+        malicious = result.malicious;
+        errors    = result.errors;
+    } else {
+        const verdict = await scan(resolved);
+        if (verdict === Verdict.Clean)          clean.push(resolved);
+        else if (verdict === Verdict.Malicious) malicious.push(resolved);
+        else                                    errors.push(resolved);
+    }
+
+    const total  = clean.length + malicious.length + errors.length;
+    const status = malicious.length > 0 ? 'infected' : 'clean';
+
+    // --- GitHub outputs ---
+    const outputFile = process.env.GITHUB_OUTPUT;
+    if (outputFile) {
+        const lines = [
+            `status=${status}`,
+            `infected-files<<POMPELMI_EOF`,
+            malicious.join('\n'),
+            `POMPELMI_EOF`,
+        ].join('\n') + '\n';
+        fs.appendFileSync(outputFile, lines);
+    }
+
+    // --- Job summary ---
+    const summaryFile = process.env.GITHUB_STEP_SUMMARY;
+    if (summaryFile) {
+        const icon = status === 'clean' ? '✅' : '❌';
+        const rows = [
+            `## ${icon} ClamAV Scan Results`,
+            '',
+            `| Metric | Count |`,
+            `|--------|-------|`,
+            `| Files scanned | ${total} |`,
+            `| Clean | ${clean.length} |`,
+            `| Infected | **${malicious.length}** |`,
+            `| Errors | ${errors.length} |`,
+        ];
+        if (malicious.length > 0) {
+            rows.push('', '### Infected Files', '');
+            malicious.forEach(f => rows.push(`- \`${f}\``));
+        }
+        fs.appendFileSync(summaryFile, rows.join('\n') + '\n');
+    }
+
+    // --- Console ---
+    console.log(`\nScan complete — ${total} file(s) scanned`);
+    console.log(`  Clean:    ${clean.length}`);
+    console.log(`  Infected: ${malicious.length}`);
+    console.log(`  Errors:   ${errors.length}`);
+    console.log(`  Status:   ${status.toUpperCase()}`);
+
+    if (malicious.length > 0) {
+        console.error('\nInfected files:');
+        malicious.forEach(f => console.error(`  ${f}`));
+        if (failOnVirus) {
+            console.error('\n::error::Virus(es) detected — failing workflow.');
+            process.exit(1);
+        }
+    }
+}
+
+main().catch(err => {
+    console.error(`::error::Scanner crashed: ${err.message}`);
+    process.exit(2);
+});

package/action.yml

@@ -0,0 +1,29 @@
+name: 'Pompelmi ClamAV Scanner'
+description: 'Scan for viruses with ClamAV (bundled) — no daemon, no cloud, zero external dependencies'
+author: 'pompelmi'
+branding:
+  icon: 'shield'
+  color: 'orange'
+
+inputs:
+  path:
+    description: 'Directory or file to scan (default: full workspace)'
+    required: false
+    default: '.'
+  fail-on-virus:
+    description: 'Fail the workflow step when infected files are found'
+    required: false
+    default: 'true'
+
+outputs:
+  infected-files:
+    description: 'Newline-separated list of infected file paths (empty when clean)'
+  status:
+    description: '"clean" or "infected"'
+
+runs:
+  using: 'docker'
+  image: './action/Dockerfile'
+  args:
+    - ${{ inputs.path }}
+    - ${{ inputs.fail-on-virus }}