@chimix/agentscan 0.3.0 → 0.5.0

package/README.md

@@ -5,8 +5,8 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/checks-23-111111?style=flat-square" alt="23 checks">
-  <img src="https://img.shields.io/badge/tests-183%20passing-111111?style=flat-square" alt="183 tests">
+  <img src="https://img.shields.io/badge/checks-26-111111?style=flat-square" alt="26 checks">
+  <img src="https://img.shields.io/badge/tests-226%20passing-111111?style=flat-square" alt="226 tests">
   <img src="https://img.shields.io/badge/network-none-111111?style=flat-square" alt="No network">
   <img src="https://img.shields.io/badge/writes-none-111111?style=flat-square" alt="Writes nothing">
   <img src="https://img.shields.io/badge/runs%20on-node%20%C2%B7%20bun-111111?style=flat-square" alt="Node or Bun">
@@ -15,7 +15,7 @@
 </p>
 
 <p align="center">
-  <strong>23 checks &middot; 3.4k lines &middot; 0 network calls &middot; every check sourced to a published spec line</strong><br>
+  <strong>26 checks &middot; 4.1k lines &middot; 0 network calls &middot; every check sourced to a published spec line</strong><br>
   <sub>Alpha. An earlier build reported 37 findings across 17 real projects of which <strong>25 were false</strong> — two checks had been written from what real projects looked like instead of from the spec. Both were deleted, and every check that survived is recorded in <a href="docs/spec/">docs/spec/</a> with the URL it came from and the date it was read. That story is the reason this tool exists in its current shape.</sub>
 </p>
 
@@ -47,12 +47,11 @@ think you have has silently not existed for six weeks.
 ```console
 $ agentscan check
 
-WARN    hook:PreToolUse:.claude/hooks/guard-destructive-bash.js
-        rule:hook.missing-script
-        PreToolUse hook points at a script that does not exist
-        evidence: hook PreToolUse @ …/.claude/settings.json
+ERROR   rule:hook.missing-script
+        PreToolUse hook points at a script that does not exist: .claude/hooks/guard-destructive-bash.js
+          PreToolUse @ .claude/settings.json · .claude/hooks/guard-destructive-bash.js
 
-Summary: 6 warn · 4 info hidden (--verbose) · score 40/100
+Summary: 1 error · score 90/100
 ```
 
 That is the whole category: **a config file asserting something that is not true
@@ -65,7 +64,7 @@ No AI, no network, no heuristics. Read the config, read the disk, compare:
 ```
 1. Discover    .claude/ .agents/ .mcp.json AGENTS.md skills-lock.json
 2. Extract     immutable facts — never re-read during checking
-3. Check       23 checks, each against one published spec line
+3. Check       26 checks, each against one published spec line
 4. Report      text · --json · --output prompt (handoff for a fixing agent)
 ```
 
@@ -84,8 +83,16 @@ A check here has to point at a spec line. If it cannot, it does not ship.
 
 ## Try it in 30 seconds
 
-Run it against any project. It reads that project, writes nothing, and never
-leaves your machine:
+No project handy? Run the built-in demo — it builds a throwaway fixture with the
+killer case (a `PreToolUse` hook pointing at a missing script), prints the human
+report, and deletes the fixture:
+
+```bash
+npx @chimix/agentscan@latest demo
+```
+
+Against a real project, it reads that tree, writes nothing, and never leaves
+your machine:
 
 ```bash
 cd ~/your-project
@@ -104,8 +111,9 @@ bun add -d @chimix/agentscan     # then: bunx agentscan check
 ```
 
 Point it at a project that actually has agent config — a `.claude/` directory,
-an `.mcp.json`, an `AGENTS.md`. On a project with none of those it will
-correctly find nothing and say so.
+an `.mcp.json`, an `AGENTS.md`. A directory with agent config and no
+`package.json` is still scannable. On a directory with neither it exits with a
+clear error.
 
 ```bash
 # what it could possibly report, before you run it
@@ -152,6 +160,7 @@ bunx agentscan check --verbose       # include KEEP and info-severity findings
 bunx agentscan check --fail-on warning
 bunx agentscan check --global        # also scan global skill dirs
 
+bunx agentscan demo                  # one-shot fixture (no project required)
 bunx agentscan explain <findingId>   # detail one finding
 bunx agentscan rules                 # every check + rule id that can fire
 bunx agentscan init                  # write .agentscanrc.json
@@ -164,6 +173,7 @@ Flags for `check`:
 | `--json` | JSON report (alias for `--output json`) |
 | `--output <format>` | `human` (default) · `json` · `prompt` |
 | `--copy` | Also copy the report to the system clipboard |
+| `--no-color` | Never colour, even on a terminal (`NO_COLOR=1` does the same) |
 | `--quiet` | Summary line only |
 | `--verbose` | Show KEEP + info-severity findings |
 | `--fail-on <level>` | `never` (default) · `warning` · `error` |
@@ -176,28 +186,39 @@ Flags for `check`:
 ## Sample output
 
 ```text
-agentscan v0.3.0 — touchagency
+  ┌─────┐   40/100  broken  ·  touchagency
+  │ ✕ ✕ │   ██████████░░░░░░░░░░░░░░░
+  │  ⌒  │   6 error · 4 info hidden (--verbose)
+  └─────┘
+
+agentscan v0.5.0 — touchagency
 
 Scanned: 46 deps · 54 skills · 1 mcp · 2 agents · packageManager=bun
 
-WARN    rule:hook.missing-script  ×6
-        PreToolUse hook points at a script that does not exist
+ERROR   rule:hook.missing-script  ×6
+        Hook points at a script that does not exist
           PostToolUse @ .claude/settings.json · .claude/hooks/notify-related-tests.js
           PreToolUse @ .claude/settings.json · .claude/hooks/guard-destructive-bash.js
           PreToolUse @ .claude/settings.json · .claude/hooks/protect-artists-json.js
           PreToolUse @ .claude/settings.json · .claude/hooks/protect-env.js
 
-Summary: 6 warn · 4 info hidden (--verbose) · score 40/100 broken
+Summary: 6 error · 4 info hidden (--verbose) · score 40/100 broken
 ```
 
-The `Stack:` line is orientation only — which project, how big. The summary lists
-only actions that actually occurred; a clean project prints `Summary: no findings`.
+On a terminal the header is coloured green, yellow or red and the face tracks
+the score. Redirect or pipe it and you get exactly the text above, with no
+escape sequences — the header box is dropped too, so `--json`, `--output
+prompt`, CI logs and `--copy` are unchanged by any of this.
+
+The `Scanned:` line is orientation only — which project, how big. The summary
+lists severities (error / warning / info); a clean project prints
+`Summary: no findings`. Score and `--fail-on` still use severity under the hood.
 
 JSON shape (abridged):
 
 ```json
 {
-  "version": "0.1.0",
+  "version": "0.5.0",
   "root": "/path/to/project",
   "factsSummary": {
     "packageManager": "bun",
@@ -381,7 +402,7 @@ Every check lives in `src/checks/` and runs on every `check`. `agentscan rules`
 lists all of them with their ids; `agentscan explain <id>` details any finding.
 
 Most validate one discovered item against its own file on disk. The five
-`budget.*` / `policy.*` entries at the bottom judge aggregate size instead —
+`budget.*` entries at the bottom judge aggregate size instead —
 they are all **info**, they are sourced to `docs/spec/thresholds.md`, and they
 are retuned through `thresholds` in `.agentscanrc.json` rather than switched
 off.
@@ -391,10 +412,14 @@ off.
 | `config.unreadable` | error | A config file that is not valid JSON, so whatever it declares is silently not in effect |
 | `hook.missing-script` | error | A registered hook whose script does not exist — it never runs |
 | `hook.unknown-event` | error | A hook registered under an event name that is never dispatched |
-| `agent.missing-frontmatter` | warning | An agent definition with no `---` block |
-| `agent.missing-description` | info | Agent frontmatter has no `description`, so it will not be dispatched on its own |
-| `mcp.no-launch` | error | An MCP server with neither `command` nor `url`; its tools are never available |
-| `mcp.url-without-type` | error | A remote MCP server with a `url` but no `type` — read as stdio, fails, and is skipped |
+| `agent.missing-frontmatter` | error | An agent definition with no `---` block |
+| `agent.missing-description` | error | Agent frontmatter has no `description` |
+| `agent.missing-name` | error | Agent frontmatter has no `name` |
+| `agent.invalid-name` | error | Agent name is not lowercase letters, numbers, and hyphens |
+| `agent.duplicate-name` | error | Multiple agent files declare the same name |
+| `mcp.no-launch` | error | An MCP server with neither `command` nor `url` — unlaunchable by schema |
+| `mcp.command-missing` | error | An MCP `command` that is a path-like value whose file does not exist on disk |
+| `mcp.url-without-type` | error | A remote MCP server with a `url` but no `type` — read as stdio, misconfigured by schema, and skipped |
 | `mcp.hardcoded-secret` | error | A token-shaped literal in MCP config (the value is never echoed back) |
 | `mcp.literal-env` | warning | Long literal `env` values that should be `${VAR}` |
 | `skill.missing-skill-md` | warning | A directory under a skill path with no `SKILL.md` |
@@ -408,9 +433,8 @@ off.
 | `skill.no-lockfile` | info | Skills present with no lockfile at all (only with `requireLock`) |
 
 Agent definitions are checked for structure only. An agent's frontmatter `name`
-is a display name — 16 of 34 real files declare one that differs from the
-filename, and nothing keys on the filename — so it is deliberately not compared,
-and a test guards against re-adding that check. Model identifiers and tool names
+is not compared to the filename; it must simply be a valid lowercase identifier
+and unique. Model identifiers and tool names
 are likewise not validated: both would need a hardcoded list, which is the shape
 that already shipped a false error. See [plans/003](plans/003-validate-agent-definitions.md).
 
@@ -422,13 +446,14 @@ references measured across 17 projects, 1645 resolved skill-relative and 12 only
 at the root. Fenced code blocks are stripped first: a path in an example is
 illustration, not a pointer.
 
-`hook.missing-script` is deliberately conservative. A command is only resolved
-when it is a single invocation with a path-like argument; shell programs
-(`a && b`, `$(...)`, pipes) are skipped, because a hook written as
-`[ ! -f x ] || node x` already handles the missing file and flagging it would be
-a false positive. `node -e "<code>"` is never treated as a path. Only
-`$CLAUDE_PROJECT_DIR` is expanded — other variables are left alone rather than
-guessed at.
+`hook.missing-script` and `mcp.command-missing` are deliberately conservative.
+A value is only resolved when it is path-like and the answer is certain; shell
+programs (`a && b`, `$(...)`, pipes), bare PATH binaries (`npx`, `uvx`), and
+unresolved env vars are skipped. A false "broken" on a working `npx` server
+would be worse than silence. `node -e "<code>"` is never treated as a path.
+Only `$CLAUDE_PROJECT_DIR` is expanded — other variables are left alone rather
+than guessed at. Schema checks judge misconfiguration, not whether a correctly
+shaped entry will start at runtime.
 
 Checks are written against the published specs, not against what happens to
 appear in real projects. Two that were written the other way round shipped as
@@ -450,7 +475,9 @@ When adding a check, add its spec line there first.
   the `computedHash` in `skills-lock.json` is the obvious `refresh` source; the
   hash algorithm used by the installing tool is not documented here, and it is
   not reproducible from `SKILL.md` bytes alone, so it is not implemented.
-- **Bun only.** `import.meta.dir` / `import.meta.main`; it will not run on Node.
+- **Runtime split.** Source development and the composite Action use Bun; the
+  published `dist/cli.js` runs on Node 20.11+ or Bun. The source entrypoint uses
+  Bun's `import.meta.dir` / `import.meta.main` and is not the Node entrypoint.
 - Policy files are read up to 100 KB, so `policyLines` undercounts past that.
 
 ## Development
@@ -469,14 +496,34 @@ bun run src/cli.ts check tests/fixtures/lock-drift
 | `test` | `bun test` |
 | `check` | `bun run src/cli.ts check` |
 
+### Release checklist
+
+Before publishing a release:
+
+1. Confirm `package.json` and `src/version.ts` contain the same version.
+2. Run `bun run build`, then verify `node dist/cli.js --version` prints it.
+3. Run `bun run typecheck`, `bun test`, and `bun run spec:check`.
+4. Refresh the test-count badge and version examples above from that release run.
+
 ## Design docs
 
 **This README is the source of truth for current behavior.** The documents under
 `docs/superpowers/specs/` are the original design and are **superseded** —
-several decisions changed while building: Bun-only runtime, the dep-to-skill map
-and its "orphan" heuristic dropped in favour of `skills-lock.json`, budget
-checks added, structural checks added, and the YAML rule engine deleted
-(`plans/010`). Read them as history, not as behavior.
+several decisions changed while building: the original Bun-only runtime claim was
+superseded by a Node-compatible published bundle, the dep-to-skill map and its
+"orphan" heuristic dropped in favour of `skills-lock.json`, budget checks added,
+structural checks added, and the YAML rule engine deleted (`plans/010`). Read
+them as history, not as behavior.
+
+## Skill
+
+A Cursor / Agent Skills file lives at [`skills/agentscan/SKILL.md`](skills/agentscan/SKILL.md). Copy the folder so the agent runs the audit before it edits hooks or claims a guard is in place:
+
+```bash
+cp -R skills/agentscan .cursor/skills/agentscan
+# or: .agents/skills/agentscan
+# or: .claude/skills/agentscan
+```
 
 ## License