anvil-engineering-workbench 1.1.0 → 1.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,52 @@
1
1
  # ANVIL Changelog
2
2
 
3
+ ## 1.1.2 — MCP Ecosystem Hardening, Compact Tool Telemetry, Empirical Token Benchmarking & Inline Suppression Union
4
+
5
+ ANVIL 1.1.2 delivers comprehensive MCP ecosystem readiness, compact tool responses saving 90%+ model context tokens, empirical token footprint measurement, cross-platform Windows ESM fixes, and inline suppression rule unioning:
6
+
7
+ ### Features & MCP Improvements
8
+ - **Compact MCP Responses by Default (`detail: false`):**
9
+ - Core inspection tools (`anvil_inspect_project`, `anvil_map_architecture`, `anvil_change_risk`, `anvil_git_intelligence`, `anvil_quality_audit`, `anvil_security_audit`, `anvil_clean_preview`) return concise summaries by default, protecting AI agent context windows.
10
+ - Every tool response includes structured telemetry in `_meta: { characterCount, estimatedTokens, compact, hint }`.
11
+ - Passing `detail: true` returns the full AST graph, itemized findings, and file breakdowns on demand.
12
+ - **Model-Optimized Tool Descriptions:**
13
+ - Enriched tool schemas in `src/mcp/server.ts` with explicit model directives detailing when to call, what data is returned, and boundary guarantees (read-only, no code execution).
14
+ - **Empirical Token Footprint Benchmark (`npm run bench`):**
15
+ - Introduced reproducible benchmark script (`scripts/measure-token-footprint.ts`) measuring unassisted file loading (~220,000 tokens) vs ANVIL compact MCP output (~2,189 tokens), achieving 96–99% context token reduction across realistic engineering tasks.
16
+ - **Agent Ecosystem Assets:**
17
+ - Added root `AGENTS.md` (operating guide for Cursor, Claude Code, Copilot, Windsurf, Antigravity).
18
+ - Added standard `llms.txt` and `public/llms.txt` documentation for AI search indexing.
19
+ - Added official MCP registry manifests `server.json` and `.well-known/mcp/server.json`, plus `smithery.yaml`.
20
+ - **Dynamic MCP Server Versioning:**
21
+ - MCP server dynamically resolves its version from `package.json` (`resolveVersion()`), verified in CI.
22
+ - **Cross-Platform CLI & Safe Auto-Start:**
23
+ - Fixed Windows ESM path resolution in `src/cli.ts` by using `pathToFileURL(script).href`.
24
+ - Guarded `anvil mcp`: displays usage and setup commands safely without hanging stdin on non-TTY calls; server runs only on explicit `anvil mcp start`.
25
+ - **Inline Suppression Rule Unioning:**
26
+ - Fixed regression in `code-review.ts` so that when both `anvil-disable-next-line` and `anvil-disable-line` apply to the same line, their suppressed rule sets and justification reasons are unioned rather than overwriting.
27
+ - **Accurate Sandbox Advisory Warnings:**
28
+ - Made sandbox resource fields (`profile`, `maxMemory`, etc.) optional in policy schema so advisory warnings are emitted only when users explicitly define resource ceilings.
29
+
30
+ ## 1.1.1 — Governance Hardening: Disallowed Tools Matcher, SARIF inSource Suppressions & Suppression Reason Enforcement
31
+
32
+ ANVIL 1.1.1 introduces strict governance hardening, accurate disallowed tool evaluation, full SARIF in-source suppression metadata, and release consistency checks:
33
+
34
+ ### Features & Governance Hardening
35
+ - **Exact Command & Script Matching for `sandbox.disallowedTools`:**
36
+ - Evaluates `package.json` scripts directly for prohibited command invocations (e.g. `rm`, `curl`, `wget`, `nc`) using exact command boundary patterns.
37
+ - Matches active finding code execution snippets using word boundary regexes instead of substring searches on human-readable diagnostic messages, eliminating false positives on words such as "format" or "information".
38
+ - **SARIF v2.1.0 In-Source Suppressions (`suppressions: [{ kind: "inSource" }]`):**
39
+ - Exported SARIF reports now include all inline-suppressed findings (`// anvil-disable-line`, etc.) tagged with standard OASIS SARIF `inSource` suppression metadata, preserving visibility in GitHub Code Scanning instead of vanishing silently.
40
+ - Justification reasons documented via `-- reason` or `: reason` are captured and attached as `suppressions[].justification`.
41
+ - **Mandatory Justification Reasons (`quality.requireSuppressionReason`):**
42
+ - New policy rule `quality.requireSuppressionReason: true` enforces that every inline suppression comment provides an explicit justification reason (e.g., `// anvil-disable-line ANVIL-R001 -- safe regex description`), failing the gate if justifications are omitted.
43
+ - **Sandbox Limits Advisory Notices & Schema Clarification:**
44
+ - Dynamic container resource limits (`profile`, `requireRootless`, `maxMemory`, `maxCpus`, `maxProcesses`) generate clear advisory warnings in `anvil gate` output explaining that they govern containerized verification runs (`container-sandbox`) rather than static code review gates.
45
+ - **Triage Documentation Precision:**
46
+ - Updated all reproduction commands in `docs/false-positive-analysis.md` to reference the canonical package name `npx anvil-engineering-workbench gate .`.
47
+ - **Automated Action & Package Version Synchronization:**
48
+ - Added release workflow and CI assertions verifying `action.yml` default version remains in 100% sync with `package.json` and git tags.
49
+
3
50
  ## 1.1.0 — Enterprise Adoption Readiness: Policy-as-Code, Fail-Closed CI Gate & Content-Hashed Baseline Engine
4
51
 
5
52
  ANVIL 1.1.0 delivers enterprise-grade CI/CD adoption readiness, policy-as-code enforcement, deterministic baseline suppression, and verified supply-chain hygiene:
@@ -32,6 +79,8 @@ ANVIL 1.1.0 delivers enterprise-grade CI/CD adoption readiness, policy-as-code e
32
79
  - Added `.git-blame-ignore-revs` ignoring repository-wide formatting commits.
33
80
  - Linked `lint` script to run both typechecking and Prettier verification.
34
81
 
82
+ ## 1.0.9 — Release Pipeline Resilience & Idempotent npm Publishing
83
+
35
84
  ANVIL 1.0.9 brings release pipeline resilience and fixes CI action resolution:
36
85
  - **Idempotent npm Publishing:** Added automated verification check in `.github/workflows/release.yml` preventing duplicate publish failures if an existing version is already present on the npm registry.
37
86
  - **Workflow Action Pinning Fix:** Resolved exact immutable commit SHAs for CodeQL Analysis and GitHub Pages deployment actions.
package/README.md CHANGED
@@ -49,7 +49,7 @@
49
49
  ---
50
50
 
51
51
  > [!NOTE]
52
- > **ANVIL v1.1.0 — AI harness foundation.** The local CLI, local dashboard, agent orchestration, MCP server, provider adapters, GitHub Action, automated self-healing cleaner, byte-accurate rollback (`anvil undo`), pre-commit hooks (`anvil hook install`), AI harness wizard (`anvil mcp setup`), Architecture Decision Records (`anvil adr`), Security & Secret Scanner (`anvil security --fix`), deterministic CI quality & security gate (`anvil gate` with SARIF v2.1.0 and policy-as-code), and live interactive workflow DAG runner are available. See [Current capabilities and boundaries](#current-capabilities-and-boundaries).
52
+ > **ANVIL v1.1.2 — AI harness foundation.** The local CLI, local dashboard, agent orchestration, MCP server, provider adapters, GitHub Action, automated self-healing cleaner, byte-accurate rollback (`anvil undo`), pre-commit hooks (`anvil hook install`), AI harness wizard (`anvil mcp setup`), Architecture Decision Records (`anvil adr`), Security & Secret Scanner (`anvil security --fix`), deterministic CI quality & security gate (`anvil gate` with SARIF v2.1.0 and policy-as-code), and live interactive workflow DAG runner are available. See [Current capabilities and boundaries](#current-capabilities-and-boundaries).
53
53
 
54
54
  ## What is ANVIL?
55
55
 
@@ -104,7 +104,7 @@ npm install --global anvil-engineering-workbench
104
104
  Or install directly from the GitHub repository:
105
105
 
106
106
  ```bash
107
- npm install --global git+https://github.com/anvil-workbench/ANVIL.git#v1.1.0
107
+ npm install --global git+https://github.com/anvil-workbench/ANVIL.git#v1.1.2
108
108
  ```
109
109
 
110
110
  Verify the installation:
@@ -150,7 +150,7 @@ npm --version
150
150
  git --version
151
151
 
152
152
  # Install ANVIL
153
- npm install --global git+https://github.com/anvil-workbench/ANVIL.git#v1.1.0
153
+ npm install --global git+https://github.com/anvil-workbench/ANVIL.git#v1.1.2
154
154
 
155
155
  # Move into your project
156
156
  cd C:\Users\YourName\Projects\my-project
@@ -463,65 +463,75 @@ ANVIL includes a local Claude Code CLI provider adapter. It uses the CLI install
463
463
 
464
464
  See [Claude Code integration](docs/integrations/claude-code.md).
465
465
 
466
- ### Cursor and MCP
466
+ ### Model Context Protocol (MCP) Server
467
467
 
468
- Cursor can connect to ANVIL through the local stdio MCP server using Cursor's MCP configuration. This is **MCP interoperability**, not a native Cursor extension.
468
+ ANVIL includes a zero-cloud Model Context Protocol (MCP) server that exposes codebase intelligence, architecture graphs, change risk, and security audits to AI developer tools such as **Claude Code, Cursor, Windsurf, VS Code, and Google Antigravity**.
469
469
 
470
- Example project configuration:
470
+ #### 1-Minute Quick Setup
471
471
 
472
+ **Claude Code (Single command):**
473
+ ```bash
474
+ claude mcp add anvil -- npx -y anvil-engineering-workbench mcp start
475
+ ```
476
+
477
+ **Cursor (`.cursor/mcp.json`):**
472
478
  ```json
473
479
  {
474
480
  "mcpServers": {
475
- "ANVIL": {
476
- "command": "node",
477
- "args": ["C:/path/to/ANVIL/dist/mcp/server.js"],
481
+ "anvil": {
482
+ "command": "npx",
483
+ "args": ["-y", "anvil-engineering-workbench", "mcp", "start"],
478
484
  "env": {
479
- "ANVIL_WORKSPACE": "C:/path/to/your-project"
485
+ "ANVIL_WORKSPACE": "${workspaceFolder}"
480
486
  }
481
487
  }
482
488
  }
483
489
  }
484
490
  ```
485
491
 
486
- Build ANVIL before using the compiled server:
487
-
492
+ **Interactive Multi-Editor Setup Wizard:**
488
493
  ```bash
489
- npm run build
494
+ # Auto-configures Cursor, VS Code, Windsurf, and Claude Code
495
+ anvil mcp setup --client all
490
496
  ```
491
497
 
492
- Adjust the paths for your machine. See [Cursor MCP documentation](https://docs.cursor.com/context/mcp).
498
+ #### Token Efficiency & Context Protection
493
499
 
494
- ### MCP server
500
+ AI coding models have bounded context windows. Loading dozens of raw source files just to inspect architecture or evaluate change risk wastes thousands of tokens.
495
501
 
496
- ANVIL provides a Model Context Protocol server over stdio:
502
+ ANVIL executes analysis entirely locally on CPU without LLM calls. By default, tools return **compact summaries** (`detail: false`), saving up to **90%+ of tokens** compared to unassisted mass file loading. Every response includes `_meta` character and token estimation metrics. Pass `detail: true` to any inspection tool if complete line-by-line graphs are needed.
497
503
 
498
- ```bash
499
- npm run build
500
- ANVIL_WORKSPACE=/absolute/path/to/project npm run mcp
501
- ```
504
+ See [Token Benchmark Results](docs/token-benchmark-results.md) for reproducible measurements on this repository.
502
505
 
503
- The current MCP server exposes bounded, read-only tools:
506
+ #### Available MCP Tools
504
507
 
505
- | Tool | Function |
506
- |---|---|
507
- | `anvil_inspect_project` | Inspect project structure and tooling |
508
- | `anvil_map_architecture` | Map source files and imports |
509
- | `anvil_search_code` | Search supported project source |
510
- | `anvil_list_files` | List supported workspace files |
511
- | `anvil_read_file` | Read a bounded text/source file |
512
- | `anvil_quality_audit` | Run static project-quality checks |
513
- | `anvil_git_intelligence` | Analyze Git changes and impact |
514
- | `anvil_list_agents` | List built-in and workspace agent roles |
515
- | `anvil_create_review_plan` | Create a draft engineering review plan |
516
- | `anvil_agent_intelligence` | Score agent performance from benchmark history |
517
- | `anvil_project_health` | Unified health snapshot & telemetry |
518
- | `anvil_change_risk` | Risk analysis for pending changes |
519
- | `anvil_dependency_impact` | Dependency blast radius & impact analysis |
520
- | `anvil_security_audit` | Scan secrets, tokens, and script risks |
508
+ All tools are read-only, bounded, and execute locally within your workspace boundaries:
509
+
510
+ | Tool | Function | Compact Default |
511
+ |---|---|:---:|
512
+ | `anvil_inspect_project` | Project inventory: languages, frameworks, scripts, dependencies | Yes (`detail: false`) |
513
+ | `anvil_map_architecture` | Multi-language AST import graph across TS, Python, Go, Rust, Java, C++ | Yes (`detail: false`) |
514
+ | `anvil_change_risk` | Blast radius, downstream affected modules, and candidate test targets | Yes (`detail: false`) |
515
+ | `anvil_git_intelligence` | Working-tree git diff, uncommitted changes, and heuristic commit risk | Yes (`detail: false`) |
516
+ | `anvil_quality_audit` | Fast static project-quality checks across manifests and tests | Yes (`detail: false`) |
517
+ | `anvil_security_audit` | Deep scan for hardcoded secrets, API keys, and sensitive tokens | Yes (`detail: false`) |
518
+ | `anvil_clean_preview` | Safe preview scan of OS junk, build caches, and orphan source files | Yes (`detail: false`) |
519
+ | `anvil_search_code` | Search supported project source excluding .env and dependencies | - |
520
+ | `anvil_list_files` | List supported workspace files (bounded to 200 entries) | - |
521
+ | `anvil_read_file` | Read bounded text/source file (max 128 KiB, traversal protected) | - |
522
+ | `anvil_project_health` | Unified 0–100 health score & letter grade (A–F) | - |
523
+ | `anvil_list_agents` | List built-in and workspace specialist-agent roles | - |
524
+ | `anvil_create_review_plan` | Create a draft multi-specialist engineering review plan | - |
525
+ | `anvil_agent_intelligence` | Score agent performance from historical benchmark matrices | - |
526
+ | `anvil_remediation_plan` | Advisory dependency remediation plan with approval guardrails | - |
527
+ | `anvil_project_memory` | Read saved project decisions and architecture constraints | - |
528
+ | `anvil_agent_security_audit` | Audit agent instructions and permissions for injection risks | - |
529
+ | `anvil_dependency_impact` | Dependency blast radius & undeclared import analysis | - |
530
+ | `anvil_doctor` | Diagnostic health checks on Node runtime, Git, Docker, and policy | - |
521
531
 
522
532
  MCP workspace paths are constrained to the configured workspace root. Hidden paths, generated/dependency directories, secret-like filenames and symlinks are excluded or rejected. Reads are bounded. The MCP server does not expose arbitrary shell execution, project-file writes, patch application or test execution.
523
533
 
524
- Some workspace browsing/search operations require an explicit restricted-mode allowlist in `.anvil/permissions.json`; the default proposal-only policy denies them.
534
+ Some workspace browsing/search operations require an explicit restricted-mode allowlist in `.anvil/permissions.json`; the default proposal-only policy denies them. See [MCP Server Guide](docs/mcp-server.md).
525
535
 
526
536
  ### GitHub Action
527
537
 
@@ -540,9 +550,9 @@ jobs:
540
550
  runs-on: ubuntu-latest
541
551
  steps:
542
552
  - uses: actions/checkout@v4
543
- - uses: anvil-workbench/ANVIL@v1.1.0
553
+ - uses: anvil-workbench/ANVIL@v1.1.2
544
554
  with:
545
- version: v1.1.0
555
+ version: v1.1.2
546
556
  project-path: .
547
557
  operation: gate
548
558
  ```
package/dist/cli.js CHANGED
@@ -1,5 +1,6 @@
1
1
  #!/usr/bin/env node
2
2
  import path from "node:path";
3
+ import { readFileSync } from "node:fs";
3
4
  import { spawn } from "node:child_process";
4
5
  import os from "node:os";
5
6
  import { mkdtemp, rm, mkdir, writeFile } from "node:fs/promises";
@@ -131,7 +132,18 @@ function readAgentDurationBudgets() {
131
132
  }
132
133
  return budgets;
133
134
  }
134
- const VERSION = "1.0.7";
135
+ function resolveVersion() {
136
+ try {
137
+ const pkgUrl = new URL("../package.json", import.meta.url);
138
+ const raw = readFileSync(pkgUrl, "utf-8");
139
+ const parsed = JSON.parse(raw);
140
+ if (typeof parsed.version === "string")
141
+ return parsed.version;
142
+ }
143
+ catch { }
144
+ return "1.1.1";
145
+ }
146
+ const VERSION = resolveVersion();
135
147
  const HELP = `
136
148
  ANVIL — The AI Engineering Workbench
137
149
 
@@ -1239,9 +1251,10 @@ async function main(args) {
1239
1251
  }
1240
1252
  process.stdout.write(`\nYour AI harness is ready to use ANVIL tools!\n`);
1241
1253
  }
1242
- else if (subcommand === "server" || subcommand === "start") {
1254
+ else if (subcommand === "server" || subcommand === "start" || subcommand === "run") {
1255
+ const { pathToFileURL } = await import("node:url");
1243
1256
  const script = resolveMcpServerScript();
1244
- await import(script);
1257
+ await import(pathToFileURL(script).href);
1245
1258
  }
1246
1259
  else {
1247
1260
  const script = resolveMcpServerScript();
@@ -1437,6 +1450,7 @@ Exit codes:
1437
1450
  const sarifOutput = generateSarif({
1438
1451
  activeFindings: evaluation.activeFindings,
1439
1452
  suppressedFindings: evaluation.suppressedFindings,
1453
+ inlineSuppressions: evaluation.inlineSuppressions,
1440
1454
  filterSuppressed: true,
1441
1455
  targetRoot: target,
1442
1456
  });
@@ -1454,9 +1468,11 @@ Exit codes:
1454
1468
  policySource: evaluation.policySource,
1455
1469
  baselineSource: evaluation.baselineSource,
1456
1470
  violations: evaluation.violations,
1471
+ warnings: evaluation.warnings,
1457
1472
  summary: evaluation.summary,
1458
1473
  activeFindings: evaluation.activeFindings,
1459
1474
  suppressedFindings: evaluation.suppressedFindings,
1475
+ inlineSuppressions: evaluation.inlineSuppressions,
1460
1476
  }, null, 2) + "\n");
1461
1477
  }
1462
1478
  else {
@@ -1473,7 +1489,17 @@ Exit codes:
1473
1489
  if (evaluation.summary.suppressedByBaseline > 0) {
1474
1490
  lines.push(` Suppressed by baseline: ${evaluation.summary.suppressedByBaseline}`);
1475
1491
  }
1492
+ if (evaluation.summary.inlineSuppressions > 0) {
1493
+ lines.push(` Inline suppressions: ${evaluation.summary.inlineSuppressions}`);
1494
+ }
1476
1495
  lines.push(``);
1496
+ if (evaluation.warnings && evaluation.warnings.length > 0) {
1497
+ lines.push(`Advisory Notices:`);
1498
+ for (const w of evaluation.warnings) {
1499
+ lines.push(` ⚠ ${w}`);
1500
+ }
1501
+ lines.push(``);
1502
+ }
1477
1503
  if (evaluation.violations.length > 0) {
1478
1504
  lines.push(`Policy Violations:`);
1479
1505
  for (const v of evaluation.violations) {