{
  "markdown": "# aiglare\n\n**Lint your AI features for governance guardrails — where can the model do something you can't undo?**\n\n[![npm](https://img.shields.io/npm/v/@nugehs/aiglare?style=flat-square)](https://www.npmjs.com/package/@nugehs/aiglare) [![CI](https://img.shields.io/github/actions/workflow/status/nugehs/aiglare/ci.yml?style=flat-square&label=CI)](https://github.com/nugehs/aiglare/actions/workflows/ci.yml) [![license: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE) [![node](https://img.shields.io/node/v/@nugehs/aiglare?style=flat-square)](https://www.npmjs.com/package/@nugehs/aiglare)\n\n**Live site:** [nugehs.github.io/aiglare-web](https://nugehs.github.io/aiglare-web/)\n\n![aiglare demo](aiglare-demo.gif)\n\nPoint it at any JS/TS repo and it finds every place an LLM/AI output reaches a user or triggers a side-effect (payment, booking, email, database write) — then flags which of those have no confidence handling, no fallback, no output validation, and no human-in-the-loop.\n\nMost AI incidents aren't model failures. They're governance failures: the model output flowed straight to a user or an irreversible action with nothing in between. This tool makes those paths visible, and lets you block them in CI.\n\n```\nnpx @nugehs/aiglare                                        # audit current repo\nnpx @nugehs/aiglare ./src --ci                             # fail the build on a red side-effectful surface\nnpx @nugehs/aiglare --compliance all --format html         # HTML evidence report for auditors\nnpx @nugehs/aiglare --compliance soc2,eu-ai-act --format lint --ci  # compliance linter in CI\n```\n\n## What it reports\n\nEach AI surface is classified by **sink** — where the output goes:\n\n- `user-facing` — returned from a route/controller, or rendered in a component\n- `side-effectful` — feeds a payment, booking, email, db/file write, or shell\n- `internal` — logged or cached only\n\n…and scored on five **guardrail** dimensions: confidence handling, fallback/uncertain path, output validation, human-in-the-loop (for side-effects), and error isolation.\n\n| Severity | Meaning |\n|----------|---------|\n| 🔴 red   | model output hits a user or a side-effect with no guardrails — review now |\n| 🟡 amber | partial coverage |\n| 🟢 green | guardrails present |\n\nThe CI gate (`--ci`) fails only on **red + side-effectful** surfaces — the \"AI auto-triggers an irreversible action with no confirmation\" case — so it's safe to adopt without drowning a team in warnings.\n\n## Compliance reports\n\nPass `--compliance` to map every finding to specific regulatory controls, then pick your output format:\n\n```bash\n# HTML evidence report — branded, collapsible per-framework sections, guardrail matrix\naiglare --compliance all --format html > report.html\n\n# ESLint-style linter — pipe into CI, editors, or reviewers\naiglare --compliance soc2,eu-ai-act --format lint\n\n# Markdown evidence doc — ready to hand to an auditor\naiglare --compliance all --format markdown > AUDIT.md\n\n# Guardrail linter (no framework) — rule IDs like guardrail/human-in-loop\naiglare --format lint\n```\n\n**Supported frameworks:**\n\n| Framework | Controls mapped |\n|-----------|----------------|\n| `soc2` | SOC 2 Trust Services Criteria — CC7.2, CC7.4, CC9.1, A1.2, PI1.2, PI1.3 |\n| `eu-ai-act` | EU AI Act — Art. 9, 13, 14, 17 |\n| `nist` | NIST AI RMF — GOVERN-1.2, MAP-2.3, MEASURE-2.5/2.6, MANAGE-1.3/2.2 |\n| `owasp` | OWASP LLM Top 10 — LLM02, LLM04, LLM08, LLM09 |\n\nUse `all` to include every framework. Each surface in `--json` output gains a `violations[]` array with the framework, control ID, description, and error/warning level.\n\n**Multi-repo:** pass multiple paths for a single combined report:\n\n```bash\naiglare ./api ./web --compliance all --format html > report.html\n```\n\n## Provider-agnostic\n\nDetection is driven by a [provider registry](src/providers.js) covering OpenAI, Anthropic, Google, Cohere, Mistral, Replicate, the Vercel AI SDK, LangChain/LangGraph, Ollama, AWS Bedrock, Cloudflare Workers AI, and Hugging Face — plus raw `fetch`/`axios` calls to known inference hosts. Adding a provider is a one-line PR.\n\n## Optional: repoctx acceleration\n\nIf a [repoctx](https://github.com/nugehs/repoctx) index (`.dev-context/index.json`) is present, the tool uses it automatically to prioritize likely AI files and sharpen sink classification via repoctx's `kind`/`domain` data (e.g. a file repoctx marks as a `controller` route is correctly treated as user-facing even when the native scanner can't see the call graph). Without it, a built-in TypeScript-compiler scanner does the same job at lower fidelity. **Same tool, two fidelity levels** — standalone for everyone, richer for repoctx users.\n\n## MCP server\n\naiglare ships a built-in [Model Context Protocol](https://modelcontextprotocol.io) server so agents can run audits directly:\n\n```bash\naiglare mcp        # stdio JSON-RPC server (no SDK dependency)\n```\n\nIt exposes three tools:\n\n| Tool | What it does |\n|------|--------------|\n| `ai_surface_audit` | Full audit of a repo (`path`, optional `sinks`, `severity`) → the same structured report as `--json` |\n| `ai_surface_gate` | CI-gate verdict for a repo: `passed` + count of blocking red side-effectful surfaces |\n| `list_providers` | The provider registry the scanner detects |\n\nRegister it with an MCP host (Claude Desktop, Cursor, VS Code, …):\n\n```json\n{\n  \"mcpServers\": {\n    \"aiglare\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@nugehs/aiglare\", \"mcp\"]\n    }\n  }\n}\n```\n\n## aiglare vs alternatives\n\n| Approach | What it does | Where aiglare differs |\n| --- | --- | --- |\n| guardrails-ai / NeMo Guardrails / runtime validators | Validate or correct each model output at runtime, per call | aiglare is static analysis: it finds the AI surfaces that have **no guardrail at all**, before anything runs — then you add a runtime validator there |\n| semgrep / custom lint rules | General-purpose static rules you write and maintain yourself | aiglare ships the AI-specific knowledge out of the box: a provider registry, sink classification, and five guardrail dimensions — zero rule-writing |\n| Manual AI-feature review | Catches nuance a scanner cannot | aiglare gives reviewers the complete inventory of AI surfaces and a severity triage, so review time goes where the risk is |\n\nThese are complementary: aiglare tells you *where* a guardrail is missing; runtime validators are *how* you add one.\n\n## Run a 1-week pilot\n\nWant to evaluate aiglare on a real codebase before adopting the CI gate? [PILOT.md](PILOT.md) is a step-by-step one-week runbook: install, first audit on a backend and a frontend repo, reading the report, tuning `--severity`/`--sinks`, and deciding whether to turn on `--ci`.\n\n## Honest limitations\n\nThis is static, advisory analysis — a linter, not a verifier. It produces false positives (a guardrail two call-hops away can be missed) and false negatives (a `confidence` variable that doesn't actually gate anything reads as present). Treat output as *surfaces to review*, not *violations*. The single-file native scanner cannot follow the call graph; the repoctx adapter exists precisely to close that gap.\n\n## Options\n\n```\naiglare [path...] [options]\n  --compliance <fw>   Map findings to compliance controls.\n                      Comma-separated: soc2, eu-ai-act, nist, owasp, or \"all\"\n  --format <fmt>      Output format: terminal (default), json, lint, markdown, html\n  --json              JSON output (alias for --format json)\n  --ci                Exit non-zero on a red side-effectful surface\n  --severity <lvl>    Show only red, or amber-and-worse\n  --sinks <list>      Filter: user-facing,side-effectful,internal\n\naiglare mcp           Start the MCP server (stdio)\n```\n\nThe MCP tool `ai_surface_audit` accepts an optional `compliance` array — each surface in the response includes a `violations[]` array when set.\n\n## License\n\nMIT\n\n---\n\n## Part of the toolchain\n\n**aiglare** is one of four tools that form a deterministic trust layer for AI-assisted development. Each answers a question people keep handing to an LLM — with static analysis instead.\n\n- [repoctx](https://www.npmjs.com/package/@nugehs/repoctx) — context: what does this change actually touch?\n- [tieline](https://www.npmjs.com/package/@nugehs/tieline) — contracts: did the front end and back end quietly stop agreeing?\n- [bouncer](https://www.npmjs.com/package/@nugehs/bouncer) — compliance: could you defend this to Ofcom?\n- **aiglare** (this tool) — governance: where can the model do something you can't undo?\n\nMore at [segunolumbe.com](https://segunolumbe.com). *static analysis, never the model.*\n",
  "bytes": 8614,
  "sha": "a9eb2605035134b60f36a2e42acbfb8f5a5cf718be263b028c5c02c085707ec0",
  "repo_slug": "nugehs/aiglare",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_nugehs_aiglare_d94f6a84/readme"
}