anti-bla 0.0.0-stage → 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "anti-bla",
+  "description": "Anti-BLA skill for REA users.",
+  "owner": {
+    "name": "ShambaC",
+    "url": "https://github.com/ShambaC"
+  },
+  "plugins": [
+    {
+      "name": "anti-bla",
+      "description": "Recognize and recover from BLA-style adversarial hardening alongside REA.",
+      "source": "./",
+      "category": "development"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "anti-bla",
+  "version": "0.1.0",
+  "description": "Overlay for the REA reverse-engineering skill: recognize and recover from BLA-style adversarial hardening with bounded, read-only, evidence-backed triage.",
+  "license": "MIT",
+  "keywords": [
+    "reverse-engineering",
+    "rea",
+    "bla",
+    "agent-skill",
+    "static-analysis"
+  ],
+  "skills": "./skills",
+  "repository": "https://github.com/ShambaC/anti-bla",
+  "homepage": "https://github.com/ShambaC/anti-bla#readme",
+  "author": {
+    "name": "ShambaC",
+    "url": "https://github.com/ShambaC"
+  }
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,27 @@
+{
+  "name": "anti-bla",
+  "version": "0.1.0",
+  "description": "Overlay for the REA reverse-engineering skill: recognize and recover from BLA-style adversarial hardening with bounded, read-only, evidence-backed triage.",
+  "license": "MIT",
+  "keywords": [
+    "reverse-engineering",
+    "rea",
+    "bla",
+    "agent-skill"
+  ],
+  "skills": "./skills",
+  "interface": {
+    "displayName": "Anti-BLA",
+    "shortDescription": "Analyze BLA-hardened artifacts with REA",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Read"
+    ]
+  },
+  "repository": "https://github.com/ShambaC/anti-bla",
+  "homepage": "https://github.com/ShambaC/anti-bla#readme",
+  "author": {
+    "name": "ShambaC",
+    "url": "https://github.com/ShambaC"
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anti-BLA contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,215 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Anti-BLA
+
+### See through anti-AI hardening. Keep REA working.
+
+**A read-only overlay for [REA](https://github.com/morluto/rea). It recognizes artifacts hardened against AI reverse engineering (such as [BLA](https://github.com/qybaihe/bla)), measures each trap, and gets the analysis moving again with evidence for every step.**
+
+[![npm](https://img.shields.io/npm/v/anti-bla?style=flat-square&color=cb3837)](https://www.npmjs.com/package/anti-bla)
+[![Node.js >= 22.13](https://img.shields.io/badge/Node.js-%3E%3D22.13-339933?style=flat-square&logo=nodedotjs&logoColor=white)](#quick-start)
+[![Works with REA 6.8](https://img.shields.io/badge/REA-6.8.0-5c4ee5?style=flat-square)](docs/compatibility.md)
+[![Tested against BLA 3.2.1](https://img.shields.io/badge/BLA-3.2.1_tested-b31b1b?style=flat-square)](#results-against-real-bla)
+[![Agent skill](https://img.shields.io/badge/agent-skill-0a7bbb?style=flat-square)](skills/anti-bla/SKILL.md)
+[![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
+
+[Quick start](#quick-start) · [Results against real BLA](#results-against-real-bla) · [How it works](#how-it-works) · [What it analyzes](#what-it-analyzes) · [FAQ](#faq) · [Documentation](#documentation)
+
+<code>npx anti-bla setup</code>
+
+</div>
+
+## Quick start
+
+Anti-BLA sits on top of REA. If you do not have REA yet, run `npx rea-agents setup` first ([REA quick start](https://github.com/morluto/rea#quick-start)).
+
+### Set up your agent
+
+With Node.js >= 22.13, run:
+
+```bash
+npx anti-bla setup
+```
+
+Setup shows its plan before writing anything. It installs the `anti-bla` skill next to your other agent skills, in the same places REA's setup uses:
+
+| Agent                                                                              | Skill location              |
+| ---------------------------------------------------------------------------------- | --------------------------- |
+| Claude Code                                                                        | `~/.claude/skills/anti-bla` |
+| Codex, Cursor, Gemini CLI and other [Agent Skills](https://agentskills.io) clients | `~/.agents/skills/anti-bla` |
+
+Use `--project <dir>` to install into one project instead, `--dry-run` to preview, `--yes` to skip the prompt, and `--uninstall` to remove the skill. An existing modified copy is backed up first. Setup never edits REA, its skill, or any MCP configuration. Restart your agent afterward.
+
+<details>
+<summary><strong>Other ways to install</strong></summary>
+
+<br />
+
+| Route                                       | Command                                                                                                                      |
+| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Skills CLI ([skills.sh](https://skills.sh)) | `npx skills add ShambaC/anti-bla`                                                                                            |
+| Claude Code plugin                          | `/plugin marketplace add ShambaC/anti-bla`, then `/plugin install anti-bla@anti-bla`                                         |
+| Codex plugin                                | install from this repository (`.codex-plugin/plugin.json` points at `./skills`)                                              |
+| Manual                                      | copy `skills/anti-bla/` into your agent's skills directory                                                                   |
+| Ask your agent                              | _"Install the Anti-BLA skill from https://github.com/ShambaC/anti-bla by running `npx anti-bla setup --yes`, then restart."_ |
+| From source                                 | `git clone https://github.com/ShambaC/anti-bla && cd anti-bla && npm ci && npm run build && node dist/src/cli.js setup`                                                       |
+
+The CLI itself needs no installation: the skill calls `anti-bla` when it is on PATH (`npm install -g anti-bla`) and otherwise uses `npx -y anti-bla`.
+
+</details>
+
+### Ask your agent
+
+```text
+Understand how the license check works in the Notes app. If REA stalls or the code fights back,
+use the anti-bla skill, recover what you can, and show me the evidence and what stays unknown.
+```
+
+Replace "the Notes app" with an app you own or are authorized to analyze, and "the license check" with the feature you want to understand. You do not need to name Anti-BLA every time. The skill loads on its own when REA hits a capacity limit or the target contains decoys or text aimed at the agent.
+
+### Use the terminal
+
+Triage an extracted app directory, an ASAR, or any single file:
+
+```bash
+npx -y anti-bla triage /absolute/path/to/app --json
+```
+
+The report lists each artifact's SHA-256, the traps it found with byte or AST locations, decoded values, suggested REA next steps, and what stays unknown. Replace the path with your target, such as `"D:/apps/example"` on Windows.
+
+More commands:
+
+```bash
+npx -y anti-bla inspect <file> [--member <path-in-asar>]   # one file; one ASAR member analyzed in memory
+npx -y anti-bla rea-evidence <saved-rea-output.json>      # turn a REA error or Evidence record into supported next steps
+npx -y anti-bla report <report.json> --format markdown    # render a stored report
+```
+
+To install the `anti-bla` command for regular use, run `npm install --global anti-bla`, then `anti-bla --help`. Add `--json` for machine-readable output. All commands are read-only: targets are never executed, modified or extracted, and nothing is sent over the network.
+
+## Results against real BLA
+
+We wrote a small app with a known answer, hardened it with **real `bla-agents@3.2.1`** (`bla protect --intensity bankrupt`), and asked the same question three ways: REA on the clean original, REA alone on the hardened copy, and REA guided by Anti-BLA. REA is `rea-agents@6.8.0` over MCP. The hardened files were never executed.
+
+| Target                     | BLA hardening                  | REA alone                                                                                                                          | REA + Anti-BLA                                                                                                                                                                 |           Recovered           |
+| :------------------------- | :----------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------: |
+| **License gate** (`.js`)   | 422 B → **136 KB**             | ⚠️ partial: 4 semantic budgets hit (alias-selections, getter-expansion, primitive-bytes, primitive-candidates), **1,951 unknowns** | All 4 traps located. **31** opaque guards proven constant, **5** split strings decoded: `Acme Notes`, `string`, `pro`, `basic`, `free`                                         |       ✅ rules + tiers        |
+| **Electron app** (`.asar`) | 1.1 KB → **18.2 MB** index     | ❌ refused: `truncated`, header admission 16 MiB, no required size given                                                           | Measured header **17,443,968 B**, set `asar.max_header_bytes`, retried **once**: analysis admitted. Decoded IPC channel `notes:quota` and bridge `notes` that REA left dynamic |      ✅ channel + bridge      |
+| **WebAssembly** (`.wasm`)  | 41 B → **6.9 MB**, 251 exports | ❌ provider unavailable here (WABT 1.0.42 not configured)¹                                                                         | **251 exports → 1 real function** (9-byte body, exact byte range). 9 decoy custom sections, canary credentials flagged and redacted                                            | 🟡 body located, read by hand |
+| **SQLite** (`.sqlite`)     | 8 KB → 53 KB, 5 honey tables   | ❌ provider unavailable here (needs Node ≥ 24.15)¹                                                                                 | Real table `licenses` identified. 3 trap columns on `enclave_unseal_payload()` isolated to decoy tables; nothing evaluated                                                     |        ✅ schema level        |
+
+Clean controls: Anti-BLA ran on the four unhardened originals and reported **0** medium/high findings and attribution `none-observed`. Anti-BLA's own wall time is **< 1 s** for all four hardened targets.
+
+<sub>¹ BLA's own report shows REA hitting `WASM_INTERFACE_REPRESENTATION_BYTES` and `SqliteColumnEvaluationFailure` when those providers are installed. We did not reproduce that here, and we do not claim it.</sub>
+
+<details>
+<summary><strong>What "recovered" means, and what it does not</strong></summary>
+
+<br />
+
+- **Decoded strings** come from sound static folding: literals, bitwise operations, `Math.imul` and `?:`, evaluated across every possible value of BLA's runtime seed. BLA ties one seed bit to a runtime digest check, so each string folds to at most two candidates. The report lists both (e.g. `Acme Notes` or `A8me2No9es`).
+- **Opaque guards** such as `(Math.imul(x|85,(x|85)+1)&1)===0` are proven constant for every possible seed value, not guessed.
+- **REA's semantic budgets stay hit.** Anti-BLA does not raise or bypass them; there is no supported setting for them. Anti-BLA answers the question from its own evidence and keeps REA's unknowns in the report.
+- One run, single operator, graded against known ground truth. Machine-readable record: [`benchmarks/results/bla-showcase-2026-11-10.json`](benchmarks/results/bla-showcase-2026-11-10.json).
+
+</details>
+
+Reproduce it:
+
+```bash
+git clone https://github.com/ShambaC/anti-bla && cd anti-bla
+npm ci
+npm install --no-save bla-agents@3.2.1   # BLA is only needed to build the hardened samples
+npm run bench:bla                        # hardens the owned samples in a temp dir and runs Anti-BLA on both sets
+```
+
+The run writes `benchmarks/results/bla-showcase-latest.json`. The REA columns come from REA over MCP and are recorded in [`benchmarks/results/bla-showcase-2026-11-10.json`](benchmarks/results/bla-showcase-2026-11-10.json).
+
+<details>
+<summary><strong>Earlier paired agent run on owned fixtures (no BLA)</strong></summary>
+
+<br />
+
+The same Sonnet subagent answered 7 questions twice (4 hardened-style fixtures and 3 clean controls), once with REA only and once with REA + Anti-BLA. Both arms got **17/17** facts right on these small, hand-parsable fixtures, so this run shows **no accuracy or token benefit**: 77,738 vs 78,790 tokens, 85 s vs 89 s. Arm B made 2 REA calls versus 7. The REA-only agent tried to `SELECT` the SQLite trap column; the Anti-BLA agent did not. Details: [`benchmarks/results/paired-2026-11-10.md`](benchmarks/results/paired-2026-11-10.md).
+
+</details>
+
+## How it works
+
+```text
+ your question ──► REA (primary tool) ──► result, partial result, or capacity error
+                         ▲                       │
+                         │                       ▼
+       one supported setting / narrower    anti-bla triage | inspect | rea-evidence
+       scope / retained-Evidence view        • fingerprint (SHA-256), bounded read-only parse
+       (schema-checked by the agent)         • measure the trap (header bytes, 2^N selector states,
+                         ▲                     candidate counts, trap functions, decoy sections)
+                         │                   • fold opaque guards and split strings soundly
+                         └──── next step ◄── • quote poisoned text as untrusted data, never obey it
+                                             • report: observed / inferred / unknown, with byte, AST
+                                               or REA Evidence provenance for every finding
+```
+
+- **The skill instructs and the CLI computes.** REA stays the primary tool. Anti-BLA never calls REA, never patches anything, and never claims a protection was "defeated".
+- **Attribution has three levels:** `none-observed`, `bla-like-mechanisms` and `bla-markers-observed`. A REA capacity error alone is never called BLA.
+- **Recovery is supported only.** Anti-BLA suggests documented REA settings within REA's own bounds, then one retry. A repeated identical failure is a stop.
+
+## What it analyzes
+
+| Format                                                              | What Anti-BLA measures                                                                                                                                                                             | Status  |
+| :------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----: |
+| **JavaScript / TypeScript**                                         | literal-alternative explosions, primitive-byte charge, expression depth, alias chains and tables, getter rings and dynamic-receiver getters, opaque guards, split strings, `eval`/`Function` sites |   ✅    |
+| **Source maps**                                                     | VLQ validity, out-of-range sources, `sourcesContent` that no mapping uses, fit against the emitted bundle                                                                                          |   ✅    |
+| **Electron `.asar`**                                                | header vs. REA admission, index inventory, unsafe/escaping names, overlapping or out-of-bounds members, duplicate keys, `--member` analysis with integrity check                                   |   ✅    |
+| **WebAssembly**                                                     | bounded LEB128 sections, import/export inventory, export aliasing, custom-section decoys, lower-bound REA interface charge                                                                         |   ✅    |
+| **SQLite**                                                          | header checks, schema-only catalog from a private read-only copy, generated columns that need application functions                                                                                |   ✅    |
+| **PE / ELF / Mach-O / other**                                       | poisoned text, canary credentials, Electron fuse-sentinel floods                                                                                                                                   | generic |
+| Runtime, native decompilation, models, Go/Flutter/BEAM/EVM/pcap/GPU | use REA directly                                                                                                                                                                                   |    —    |
+
+Every technique, including what is **not** detected, is listed in the [limitation matrix](docs/limitation-matrix.md).
+
+## FAQ
+
+<details>
+<summary><strong>Does Anti-BLA replace REA?</strong></summary>
+
+No. REA does the reverse engineering. Anti-BLA spots when an artifact is fighting the analysis, measures how, and tells the agent which supported REA step to try next. Without REA, the CLI still triages files, and the skill tells the agent to say that REA-based conclusions are unavailable.
+
+</details>
+
+<details>
+<summary><strong>Is it safe to run on hostile files?</strong></summary>
+
+It is built for hostile input. Anti-BLA does not execute, `require` or instantiate targets, and does not evaluate SQLite columns. Reads are bounded and every regex quantifier is bounded. JS parsing runs in a resource-limited worker. Prompt-injection text is quoted as data and never obeyed, and apparent secrets are redacted. See the [threat model](docs/threat-model.md).
+
+</details>
+
+<details>
+<summary><strong>Can it be fooled?</strong></summary>
+
+Yes. Detection is structural and versioned against REA 6.8.0 and BLA 3.2.1. New hardening shapes can slip past it, markers can be planted, and large legitimate apps can trip capacity rules. Findings separate what was observed from what is inferred, and attribution never reads "confirmed".
+
+</details>
+
+<details>
+<summary><strong>Is this legal to use?</strong></summary>
+
+Use it only on software you own, have permission to analyze, or that was published as a challenge. Anti-BLA does not bypass licensing, integrity enforcement or anti-debugging, and it performs no runtime instrumentation.
+
+</details>
+
+## Documentation
+
+[Architecture](docs/architecture.md) · [Threat model](docs/threat-model.md) · [Tool contracts](docs/tool-contracts.md) · [Compatibility (pinned REA/BLA)](docs/compatibility.md) · [Limitation matrix](docs/limitation-matrix.md) · [Benchmark methodology](docs/benchmark-methodology.md) · [Development](docs/development.md) · [Releasing](docs/releasing.md) · [Skill](skills/anti-bla/SKILL.md)
+
+## Development
+
+```bash
+npm ci && npm run build
+npm test                  # unit, integration, regression and security tests
+npm run check:skill       # frontmatter, links, and REA tool names vs. the pinned REA 6.8.0 catalog
+```
+
+## License
+
+MIT. REA and BLA are separate MIT-licensed projects. Anti-BLA includes none of their code or output, and the test corpus is generated independently.

package/dist/src/cli.js

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+// anti-bla: read-only, bounded triage CLI. Exit codes: 0 ok, 1 analysis failed, 2 usage/input error.
+import { Budget, CLI_LIMIT_FLAGS, DEFAULT_LIMITS } from './core/budgets.js';
+import { TOOL_VERSION, UsageError, writeOutput } from './commands/assemble.js';
+import { runTriage } from './commands/triage.js';
+import { runInspect, INSPECT_FORMATS } from './commands/inspect.js';
+import { runReaEvidence } from './commands/rea-evidence.js';
+import { runReport } from './commands/report.js';
+import { CLIENTS, runSetup } from './commands/setup.js';
+import { toJson } from './reports/json.js';
+const LIMIT_HELP = Object.entries(CLI_LIMIT_FLAGS).map(([f, k]) => `  ${f.padEnd(18)} default ${DEFAULT_LIMITS[k]}`).join('\n');
+const COMMON = `Common options:
+  --json              machine-readable report on stdout (diagnostics on stderr; with --output the report goes only to the file)
+  --output <file>     write the report atomically to <file> (never inside the analyzed input)
+  --force             allow --output to replace an existing file
+  --redact-paths      replace absolute artifact paths with <redacted>/<logical path>
+Budget caps (hard limits):
+${LIMIT_HELP}`;
+const HELP = {
+    main: `anti-bla ${TOOL_VERSION} — read-only triage of adversarially hardened artifacts; companion to REA.
+
+Usage:
+  anti-bla triage <path> [options]          walk a file or directory, analyze every file
+  anti-bla inspect <file> [--format f] [--member p] [options]
+  anti-bla rea-evidence <evidence.json>... [options]
+  anti-bla report <report.json> [--format markdown|json] [--output f]
+  anti-bla setup [--client claude,agents] [--project <dir>] [--dry-run] [--yes] [--uninstall]
+  anti-bla --version | --help | <command> --help
+
+Anti-BLA never executes, modifies or extracts targets, never contacts the network,
+and never calls REA itself: it recommends REA actions the host agent must validate.
+
+${COMMON}`,
+    triage: `anti-bla triage <path> [options]
+Walks <path> in stable order (symlinks outside the root are not followed), hashes each
+file, detects format by magic bytes/structure, runs bounded analyzers, emits one report.
+
+${COMMON}`,
+    inspect: `anti-bla inspect <file> [--format ${INSPECT_FORMATS.join('|')}] [--member <asar member>] [options]
+One format-specific inspection. --member selects one ASAR member, analyzed in memory only.
+
+${COMMON}`,
+    'rea-evidence': `anti-bla rea-evidence <file.json>... [options]
+Parses REA Evidence records, MCP tool results, CLI error envelopes or exported bundles.
+Preserves Evidence IDs, limitations, unknowns and coverage pointers; emits conditional
+REA next steps. Paths inside the JSON are never opened.
+
+${COMMON}`,
+    setup: `anti-bla setup [--client claude,agents] [--project <dir>] [--dry-run] [--yes] [--uninstall]
+Installs the anti-bla skill next to your other agent skills (the same places REA's setup uses):
+  claude  ->  ~/.claude/skills/anti-bla   (or <project>/.claude/skills with --project)
+  agents  ->  ~/.agents/skills/anti-bla   (Codex, Cursor, Gemini CLI and other Agent Skills clients)
+Default: both when ~/.claude exists, otherwise agents. Shows the plan first; writes only with --yes
+or an interactive y. Existing different copies are backed up. Never edits REA or MCP configuration.`,
+    report: `anti-bla report <report.json> [--format markdown|json] [--output <file>] [--force]
+Renders a stored anti-bla-report/v1 without reopening any target.`,
+};
+const VALUE_FLAGS = new Set(['--output', '--format', '--member', '--client', '--project', ...Object.keys(CLI_LIMIT_FLAGS)]);
+const BOOL_FLAGS = new Set(['--json', '--force', '--help', '-h', '--version', '-V', '--redact-paths', '--dry-run', '--yes', '-y', '--uninstall']);
+function parse(argv) {
+    const flags = new Map();
+    const positionals = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--') {
+            positionals.push(...argv.slice(i + 1));
+            break;
+        }
+        if (a.startsWith('-')) {
+            const [name, inline] = a.includes('=') ? [a.slice(0, a.indexOf('=')), a.slice(a.indexOf('=') + 1)] : [a, undefined];
+            if (VALUE_FLAGS.has(name)) {
+                const v = inline ?? argv[++i];
+                if (v === undefined)
+                    throw new UsageError(`${name} needs a value`);
+                flags.set(name, v);
+            }
+            else if (BOOL_FLAGS.has(name))
+                flags.set(name, true);
+            else
+                throw new UsageError(`Unknown option ${name}`);
+        }
+        else
+            positionals.push(a);
+    }
+    return { command: positionals.shift() ?? '', positionals, flags };
+}
+function budgetFrom(flags) {
+    const lim = {};
+    for (const [flag, key] of Object.entries(CLI_LIMIT_FLAGS)) {
+        const v = flags.get(flag);
+        if (v === undefined)
+            continue;
+        const n = Number(v);
+        if (!Number.isSafeInteger(n) || n < 1)
+            throw new UsageError(`${flag} must be a positive integer`);
+        lim[key] = n;
+    }
+    return new Budget(lim);
+}
+function summary(r) {
+    const L = [`anti-bla ${r.command}: ${r.analysisStatus.toUpperCase()} · ${r.artifacts.length} artifact(s) · ${r.findings.length} finding(s) · attribution ${r.attribution.status}`];
+    for (const f of r.findings.slice(0, 20))
+        L.push(`  [${f.confidence}] ${f.classification} ${f.id}: ${f.title}`);
+    if (r.findings.length > 20)
+        L.push(`  … ${r.findings.length - 20} more (use --json)`);
+    for (const a of r.suggestedActions.slice(0, 10))
+        L.push(`  next (${a.kind}, ${a.risk}): ${a.title}`);
+    if (r.coverage.excluded.length)
+        L.push(`  excluded: ${r.coverage.excluded.length} path(s)`);
+    if (r.budgets.truncated)
+        L.push('  budgets truncated: results are partial');
+    if (r.unknowns.length)
+        L.push(`  unknowns: ${r.unknowns.length} (see --json / report)`);
+    return L.join('\n') + '\n';
+}
+export async function main(argv) {
+    let json = argv.includes('--json');
+    try {
+        const p = parse(argv);
+        json = p.flags.has('--json');
+        if (p.flags.has('--version') || p.flags.has('-V')) {
+            process.stdout.write(`${TOOL_VERSION}\n`);
+            return 0;
+        }
+        if (!p.command || (p.flags.has('--help') || p.flags.has('-h')) && !HELP[p.command]) {
+            process.stdout.write(HELP.main + '\n');
+            return p.command ? 2 : 0;
+        }
+        if (p.flags.has('--help') || p.flags.has('-h')) {
+            process.stdout.write(HELP[p.command] + '\n');
+            return 0;
+        }
+        const out = p.flags.get('--output');
+        const force = p.flags.has('--force');
+        const redactPaths = p.flags.has('--redact-paths');
+        if (p.command === 'setup') {
+            const o = { dryRun: p.flags.has('--dry-run'), yes: p.flags.has('--yes') || p.flags.has('-y'), uninstall: p.flags.has('--uninstall') };
+            const c = p.flags.get('--client');
+            if (typeof c === 'string') {
+                const list = c.split(',').map((x) => x.trim()).filter(Boolean);
+                for (const x of list)
+                    if (!CLIENTS.includes(x))
+                        throw new UsageError(`Unknown --client ${x}; expected ${CLIENTS.join(', ')}`);
+                o.clients = list;
+            }
+            const proj = p.flags.get('--project');
+            if (typeof proj === 'string')
+                o.project = proj;
+            await runSetup(o);
+            return 0;
+        }
+        if (p.command === 'report') {
+            if (p.positionals.length !== 1)
+                throw new UsageError('report needs exactly one report.json');
+            const fmt = String(p.flags.get('--format') ?? 'markdown');
+            const text = await runReport(p.positionals[0], fmt);
+            if (typeof out === 'string')
+                await writeOutput(out, text, force, [p.positionals[0]]);
+            else
+                process.stdout.write(text);
+            return 0;
+        }
+        let report;
+        const budget = budgetFrom(p.flags);
+        if (p.command === 'triage') {
+            if (p.positionals.length !== 1)
+                throw new UsageError('triage needs exactly one path');
+            report = await runTriage(p.positionals[0], budget, { redactPaths });
+        }
+        else if (p.command === 'inspect') {
+            if (p.positionals.length !== 1)
+                throw new UsageError('inspect needs exactly one file');
+            const o = { redactPaths };
+            if (typeof p.flags.get('--format') === 'string')
+                o.format = p.flags.get('--format');
+            if (typeof p.flags.get('--member') === 'string')
+                o.member = p.flags.get('--member');
+            report = await runInspect(p.positionals[0], budget, o);
+        }
+        else if (p.command === 'rea-evidence') {
+            report = await runReaEvidence(p.positionals, budget, { redactPaths });
+        }
+        else {
+            throw new UsageError(`Unknown command ${p.command}; see anti-bla --help`);
+        }
+        const body = toJson(report);
+        if (typeof out === 'string') {
+            await writeOutput(out, body, force, p.positionals);
+            process.stderr.write(`report written: ${out}\n`);
+        }
+        if (json && typeof out !== 'string')
+            process.stdout.write(body);
+        else if (!json)
+            process.stdout.write(summary(report));
+        return report.analysisStatus === 'failed' ? 1 : 0;
+    }
+    catch (e) {
+        const err = e;
+        const code = e instanceof UsageError ? err.code : 'internal_error';
+        if (json)
+            process.stdout.write(JSON.stringify({ schemaVersion: 'anti-bla-error/v1', error: { code, message: err.message } }, null, 2) + '\n');
+        else
+            process.stderr.write(`anti-bla: ${err.message}\n`);
+        return 2;
+    }
+}
+// Run only as the entry point (tests import main()).
+const entry = process.argv[1] ? (await import('node:url')).pathToFileURL((await import('node:fs')).realpathSync(process.argv[1])).href : '';
+if (import.meta.url === entry)
+    process.exitCode = await main(process.argv.slice(2));

package/dist/src/commands/assemble.js

@@ -0,0 +1,103 @@
+import { readFileSync } from 'node:fs';
+import { realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { aggregateStatus, attribution } from '../core/classification.js';
+import { capFindings } from '../core/findings.js';
+import { isInside } from '../core/files.js';
+import { REPORT_SCHEMA_VERSION } from '../core/types.js';
+// Single source of truth: the package version (dist/src/commands -> package root).
+export const TOOL_VERSION = JSON.parse(readFileSync(new URL('../../../package.json', import.meta.url), 'utf8')).version;
+export class UsageError extends Error {
+    code;
+    constructor(message, code = 'invalid_input') {
+        super(message);
+        this.code = code;
+    }
+}
+export const emptyCollected = () => ({ artifacts: [], statuses: [], findings: [], actions: [], examined: [], excluded: [], limitations: [], unknowns: [] });
+const evKey = (f) => {
+    const e = f.evidence[0];
+    return [e.logicalPath ?? '', String(e.byteStart ?? -1).padStart(16, '0'), f.rule, f.id].join('\u0000');
+};
+export function assemble(command, c, budget, opts = {}) {
+    const { kept, dropped } = capFindings(c.findings, budget.limits.maxFindings);
+    const limitations = [...c.limitations];
+    if (dropped) {
+        limitations.push(`${dropped} finding(s) dropped by --max-findings ${budget.limits.maxFindings} (lowest confidence first).`);
+        budget.markTruncated('max findings reached');
+    }
+    for (const r of budget.reasons)
+        limitations.push(`Budget: ${r}.`);
+    const findings = [...kept].sort((a, b) => (evKey(a) < evKey(b) ? -1 : 1));
+    const seen = new Set();
+    const actions = c.actions.filter((a) => { const k = JSON.stringify([a.kind, a.title, a.operation]); if (seen.has(k))
+        return false; seen.add(k); return true; });
+    const uniq = (xs) => [...new Set(xs)];
+    const report = {
+        schemaVersion: REPORT_SCHEMA_VERSION,
+        command,
+        analysisStatus: aggregateStatus(c.statuses, c.excluded.length > 0 || budget.truncated),
+        analyzedAt: new Date().toISOString(),
+        toolVersion: TOOL_VERSION,
+        artifacts: c.artifacts.map((a) => (opts.redactPaths ? { ...a, path: `<redacted>/${a.logicalPath}` } : a)),
+        findings,
+        suggestedActions: actions,
+        coverage: { examined: c.examined, excluded: c.excluded },
+        limitations: uniq(limitations),
+        unknowns: uniq(c.unknowns),
+        attribution: attribution(findings),
+        budgets: { elapsedMs: budget.elapsedMs(), bytesRead: budget.bytesRead, bytesHashed: budget.bytesHashed, truncated: budget.truncated, limits: { ...budget.limits } },
+    };
+    if (opts.rea)
+        report.rea = opts.rea;
+    return report;
+}
+/** Atomic write to an explicit destination; refuses overwrite without --force and refuses paths inside analyzed inputs. */
+export async function writeOutput(outPath, content, force, protectedPaths) {
+    const out = resolve(outPath);
+    // Compare real paths (symlinks/junctions/8.3 names resolved) and, on Windows/macOS, case-insensitively.
+    let realOut = out;
+    try {
+        realOut = join(await realpath(dirname(out)), basename(out));
+    }
+    catch { /* parent missing: writeFile will fail */ }
+    const fold = (p) => (process.platform === 'win32' || process.platform === 'darwin' ? p.toLowerCase() : p);
+    let outStat = null;
+    try {
+        outStat = await stat(out, { bigint: true });
+    }
+    catch { /* absent */ }
+    for (const p of protectedPaths) {
+        let abs = resolve(p);
+        try {
+            abs = await realpath(abs);
+        }
+        catch { /* gone */ }
+        let st = null;
+        try {
+            st = await stat(abs, { bigint: true });
+        }
+        catch { /* gone */ }
+        const sameFile = !!(st && outStat && st.ino !== 0n && st.ino === outStat.ino && st.dev === outStat.dev);
+        if (sameFile || fold(realOut) === fold(abs) || (st?.isDirectory() && isInside(fold(abs), fold(realOut)))) {
+            throw new UsageError(`Refusing to write output inside or onto an analyzed input: ${out}`, 'unsafe_output');
+        }
+    }
+    let exists = false;
+    try {
+        await stat(out);
+        exists = true;
+    }
+    catch { /* absent */ }
+    if (exists && !force)
+        throw new UsageError(`Output exists: ${out} (use --force to overwrite)`, 'output_exists');
+    const tmp = `${out}.anti-bla-${process.pid}.tmp`;
+    try {
+        await writeFile(tmp, content, { flag: 'wx' });
+        await rename(tmp, out);
+    }
+    catch (e) {
+        await rm(tmp, { force: true });
+        throw e;
+    }
+}