@chimix/agentscan 1.1.0 → 2.0.0

package/CHANGELOG.md

@@ -11,6 +11,397 @@ and [v0.4.0](https://github.com/SimaAlexandru99/agentscan/releases/tag/v0.4.0).
 (the published package version). A separate 1.0.1 npm tag would need an
 intermediate commit that this train does not cut.
 
+## Unreleased
+
+## 2.0.0 — 2026-11-12
+
+Breaking for configs that still name the 0.7 rule ids or the old threshold
+keys. `ignoreRules`, `ignoreFindings`, and `explain` accept only the printed
+ids (`claude.hook.missing-script`, not `hook.missing-script`).
+`thresholds.skillDescriptionBytes` and `thresholds.skills` are rejected; the
+listing budget is `thresholds.skillListingChars`. **143 checks**, **647 tests**.
+
+- Kiro agents: `.kiro/agents/**/*.json` and `*.md` on the ancestor walk, and
+  `~/.kiro/agents/` under `--global`. The name is the path relative to that
+  directory, without the extension. A nearer workspace file shadows a farther
+  workspace file and a global file with the same name. No field is required.
+  No new rule id. A `.json` and a `.md` with the same stem in one directory
+  are both kept.
+- Antigravity rules and skills. Workspace `GEMINI.md` and `.agents/GEMINI.md`,
+  one level of `.agents/rules/*.md` and legacy `.agent/rules/*.md`, and
+  `.agents/rules.json` as shape only (`inherits` and `entries` paths are not
+  opened). `--global` adds `~/.gemini/AGENTS.md`, `~/.gemini/GEMINI.md`,
+  `~/.gemini/config/AGENTS.md`, `~/.gemini/config/GEMINI.md`,
+  `~/.gemini/config/rules/*.md`, and `~/.gemini/config/skills/`. Workspace
+  `AGENTS.md` stays the portable policy file, so the 24,000-byte check does
+  not apply to it. The byte check counts the raw file, before
+  `@[label](path)` expansion. The 20,000-token aggregate is not checked.
+  Plugin rules and plugin skills stay unread, as do
+  `~/.gemini/antigravity-cli/skills/`, `~/.gemini/skills/`, and
+  `~/.gemini/antigravity/skills/`. Global skills use the Agent Skills
+  contract. New: `antigravity.rule.missing-trigger`,
+  `antigravity.rule.invalid-trigger`,
+  `antigravity.rule.missing-description`, `antigravity.rule.missing-globs`,
+  `antigravity.rule.too-large`.
+- Antigravity hooks: `.agents/hooks.json` on the ancestor walk, and
+  `~/.gemini/config/hooks.json` under `--global`. The file maps hook names to
+  definitions. Direct handlers and matcher groups are both valid. `enabled:
+  false` skips a definition. `type` defaults to `command`. Six events.
+  Plugin hooks stay unread. New: `antigravity.hook.unknown-event`,
+  `antigravity.hook.missing-script`, `antigravity.hook.invalid-group`,
+  `antigravity.hook.command-without-command`,
+  `antigravity.hook.unknown-handler-type`.
+- Codex hooks: project `.codex/hooks.json` and inline `[hooks]` in
+  `.codex/config.toml`, plus the same two files under `$CODEX_HOME` or
+  `~/.codex` with `--global`. Both files in a layer are inventoried. Fourteen
+  events. `command` and `mcp_tool` run; `prompt` and `agent` are parsed but
+  skipped; `SessionEnd` does not run `mcp_tool`. SessionEnd and Interrupt
+  timeouts must be 1–3 seconds. Other events are not timeout-checked.
+  Plugins, `requirements.toml`, and the trust gate stay unread. New:
+  `codex.hook.unknown-event`, `codex.hook.missing-script`,
+  `codex.hook.invalid-group`, `codex.hook.command-without-command`,
+  `codex.hook.mcp-tool-without-server-or-tool`,
+  `codex.hook.unknown-handler-type`, `codex.hook.incompatible-handler`,
+  `codex.hook.timeout-out-of-bounds`.
+- Cursor user MCP under `--global`: `~/.cursor/mcp.json` uses the same
+  `cursor-json` profile as the project file. A missing `version` is not a
+  finding.
+- Kiro hook triggers `SessionEnd`, `PreCompact`, and `PostCompact`, quoted
+  on the types page (2026-11-12). `PreTaskExec` and `PostTaskExec` stay:
+  that table still lists Pre/Post Task Execution and does not quote a
+  replacement token.
+- `CLAUDE_CONFIG_DIR` also relocates `~/.claude.json` to
+  `$CLAUDE_CONFIG_DIR/.claude.json` under `--global`. Unset, the file stays
+  `~/.claude.json`.
+- Devin CLI, beside the legacy Windsurf contract: `.devin/hooks.v1.json`
+  and `"hooks"` in `.devin/config.json` / `config.local.json` (user
+  `~/.config/devin/config.json` under `--global`); MCP
+  `.devin/mcp_config.json`, `.devin/mcp_config.local.json`, and a
+  `mcpServers` key still sitting in those config files. Launch is `command`
+  or `url` (`sse` is a valid transport, not a check). Skills:
+  `.devin/skills` and `--global` `~/.config/devin/skills`. New:
+  `devin.hook.unknown-event`, `devin.hook.missing-script`,
+  `devin.hook.invalid-group`, `devin.hook.command-without-command`,
+  `devin.hook.prompt-without-prompt`, `devin.hook.unknown-handler-type`,
+  `devin.mcp.no-launch`. `.windsurf/hooks.json` and
+  `~/.codeium/windsurf/mcp_config.json` stay the Cascade contract.
+  `.claude/settings.json` stays Claude.
+- Antigravity MCP: `url` is an alias of `serverUrl`. `httpUrl` alone is
+  still `antigravity.mcp.no-launch`.
+- Copilot portable user MCP under `--global`: `$COPILOT_HOME/mcp-config.json`
+  or `~/.copilot/mcp-config.json` (`mcpServers`, `command` or `url`),
+  reported as `vscode.mcp.no-launch`. `.vscode/mcp.json` stays the `servers`
+  file. Legacy Local hooks stay the eight PascalCase command-only events;
+  `version: 1` stays Copilot.
+
+- Kiro hooks (`.kiro/hooks/*.json`, `--global` `~/.kiro/hooks/`) on their
+  own profile: 13 PascalCase triggers, `command` /
+  `agent` actions, array-of-hooks files. New: `kiro.hook.unknown-event`,
+  `kiro.hook.missing-script`, `kiro.hook.command-without-command`,
+  `kiro.hook.prompt-without-prompt`, `kiro.hook.unknown-handler-type`,
+  `kiro.hook.invalid-group`. Agents are inventoried on their own walk
+  (above). Skills: `.kiro/skills` as Agent Skills.
+- Cline / Roo / Kilo / Junie skill directories (`.cline/skills`,
+  `.roo/skills`, `.kilo/skills`, `.junie/skills`, plus `--global` home
+  copies). Junie does not require `description` and does not require
+  `name` to match the folder. Cline hooks and Cline agents stay unread.
+- VS Code `.github/agents/*.agent.md` frontmatter hooks parse as
+  vscode-native. Marketplace plugin `hooks.json` stays unread.
+- `--global` Cursor `~/.cursor/hooks.json`, Gemini
+  `~/.gemini/settings.json` (hooks and MCP together), and Antigravity
+  `~/.gemini/config/mcp_config.json`. Credential siblings are never
+  opened. Copilot-consumed `.claude/settings.json` stays Claude.
+- Spec provenance: VS Code hooks-reference, geminicli.com (GitHub MCP
+  page kept for the underscore warning), both OpenCode MCP URLs.
+
+- Claude user `~/.claude/settings.json` hooks under `--global` /
+  `includeGlobal`. Same Claude schema as project settings;
+  `${CLAUDE_PROJECT_DIR}` resolves against the scanned project. Same-event
+  user and project hooks coexist. Managed policy and marketplace plugins
+  stay unread.
+- Claude user `~/.claude.json` MCP under `--global` / `includeGlobal`:
+  top-level `mcpServers` (user) and matching
+  `projects.<scanned-path>.mcpServers` (local). Absent keys are not
+  `config.unreadable`. Same-name project, user, and local servers are
+  all inventoried. Other projects' local servers stay unread.
+- Claude `--global` user agents, `CLAUDE.md`, rules, and commands
+  (`$CLAUDE_CONFIG_DIR` or `~/.claude`). `CLAUDE_CONFIG_DIR` relocates
+  that directory; `~/.claude.json` stays in the home directory.
+- Project `.claude/commands/*.md` inventoried as Claude slash commands;
+  frontmatter hooks use the skill source. In-tree plugin `skills/`,
+  root `SKILL.md`, `agents/` (no frontmatter hooks), `commands/`, and
+  `.mcp.json` (`claude-json`). Marketplace plugins stay unread.
+- Gemini CLI hooks: the `hooks` object in project `.gemini/settings.json`,
+  the same file the MCP scan already opens. Nested `{ matcher?, sequential?,
+  hooks: [...] }` groups, required `type` whose only documented value is
+  `command`, and `$GEMINI_PROJECT_DIR` script resolution. Eleven events
+  (`SessionStart`, `SessionEnd`, `BeforeAgent`, `AfterAgent`, `BeforeModel`,
+  `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`,
+  `PreCompress`, `Notification`) on their own profile — Claude's names are
+  never accepted here, and Gemini's are never validated against Claude's.
+  New: `gemini.hook.unknown-event`, `gemini.hook.missing-script`,
+  `gemini.hook.invalid-group`, `gemini.hook.command-without-command`,
+  `gemini.hook.unknown-handler-type`. User `~/.gemini/settings.json` is
+  opened under `--global` together with that file's MCP servers.
+  `/etc/gemini-cli/settings.json` and extension hooks stay unread.
+- Cursor hooks: project `.cursor/hooks.json`. Flat arrays, not Claude groups;
+  `command` required on every entry, `type` optional and defaulting to
+  `command` (`command` / `prompt`), scripts resolved against the project root
+  as the page documents. Twenty-one camelCase events across agent, Tab, and
+  app-lifecycle families. New: `cursor.hook.unknown-event`,
+  `cursor.hook.missing-script`, `cursor.hook.command-without-command`,
+  `cursor.hook.unknown-handler-type`. User `~/.cursor/hooks.json` is opened
+  under `--global`. MDM paths and dashboard-synced team hooks stay unread.
+- `spec:check` now diffs the Gemini, Cursor, and Kiro event sets against
+  their live pages, and those pages are tracked by content hash.
+- Every finding now says where its rule comes from. `StructuralCheck` gains a
+  required `source`: either `{ kind: "spec", url, capture }` naming the vendor
+  page and the `docs/spec` file holding the verbatim quote, or
+  `{ kind: "derived", detail }` stating plainly that no vendor page asserts it.
+  Required, so a new rule that cannot say where it came from does not compile.
+  `make()` copies it, with `provenance` and `lastVerified`, onto every finding.
+  - Default report: one dim line per rule group —
+    `spec-required · cursor.com/docs/hooks · read 2026-09-03`, or
+    `internal-consistency · no vendor page · agentscan inference`.
+  - `explain`: adds `provenance:`, the full `source:` URL, and `capture:`.
+  - `--json`: three new keys per finding (`provenance`, `source`,
+    `lastVerified`). Additive; no key renamed or removed.
+  - `--output prompt`: a `Source:` bullet, so a fixing agent can read the page
+    before editing the config the rule is about.
+  - `agentscan rules` gains provenance and source columns and a `--json` flag
+    (it previously accepted no flags at all).
+- All 28 pages cited by a rule are already in `SPEC_SURFACES`, so every source
+  a user sees is re-fetched and hash-compared by `bun run spec:check`. A test
+  enforces it, along with: every capture file exists, the capture names the
+  rule, `lastVerified` matches the capture's `**Read:**` date, and a
+  `spec-required` rule may not claim it has no source.
+- `bun run readme:rules` generates the README rule table from the registry;
+  a test fails the build when it drifts. This recovers the three
+  `windsurf.hook.*` rows the hand-maintained table had been missing since #13,
+  and the check count is now asserted against the registry in the three README
+  places it is written by hand. `site/lib/site.ts` deliberately stays at the
+  published release's count; the test only forbids the site advertising more
+  checks than the registry holds.
+
+### Removed
+
+- `ignoreRules`, `ignoreFindings`, and `explain` no longer accept 0.7 rule
+  ids (`hook.missing-script`, `skill.missing-frontmatter`, and the rest of
+  that set). Use the id the finding prints (`claude.hook.missing-script`).
+- `thresholds.skillDescriptionBytes` and `thresholds.skills` are rejected.
+  The listing budget key is `thresholds.skillListingChars`.
+- The README "Catches" column is the registry description. `bun run
+  readme:rules` no longer keeps a second, hand-written sentence.
+
+### Changed
+
+- An explicit `--config <path>` that does not exist now exits 2 with
+  `config file not found: <path>` instead of silently scanning with defaults.
+  A missing implicit `.agentscanrc.json` still means defaults. A config that
+  parses as JSON but breaks the schema exits 2 with
+  `Invalid config at <path>: <key>: <problem>` instead of a raw zod dump.
+
+### Fixed
+
+- 54 rules recorded a `lastVerified` older than the `**Read:**` date of the
+  capture they rest on: the 2026-09-03 re-read of those pages never reached the
+  registry. Synced, with a test that keeps the two in step.
+- Three `tests/unit/codex-mcp.test.ts` cases failed on any machine with
+  `CODEX_HOME` exported: they mock `os.homedir()`, but `codexHomeDir()`
+  correctly prefers the env override. A `tests/helpers/env.ts` preload clears
+  `CODEX_HOME`, `GROK_HOME`, `CLAUDE_CONFIG_DIR`, and `COPILOT_HOME` for the
+  whole suite; the tests that need one still set and restore it themselves.
+
+## 1.4.0 — 2026-09-02
+
+Closes two coverage gaps left after the 2026-09-02 re-verification, then
+ships everything that sat in Unreleased: the seven false-positive
+corrections, plan 038 content hashes and verbatim fixtures, and #13
+Windsurf Cascade hooks / skills. **103 checks**, **532 tests**.
+
+### Added
+
+- Copilot CLI inline `hooks` in `.github/copilot/settings.json` and
+  `.github/copilot/settings.local.json` (always `copilot-cli`, source
+  `copilot-settings`). User `$COPILOT_HOME/settings.json` or
+  `~/.copilot/settings.json` under `--global`. Same-event hooks from
+  settings and `.github/hooks` coexist. `$COPILOT_HOME` is honored for
+  user hook files too. `.claude/settings.json` stays on the Claude
+  profile. Policy and plugin hook files stay unread.
+- `mcp.literal-credential` (security, warning): secret-named string values
+  under MCP `headers`, `http_headers`, or `auth` that are not
+  interpolation. Field paths only; values never echoed. Grok `{{var}}`,
+  Gemini `%VAR%`, and the existing `${VAR}` / `${env:}` / `${input:}`
+  forms are interpolation. Token-shaped literals still fire
+  `security.hardcoded-secret` first.
+
+- `bun run spec:check` hashes the prose of every source page in
+  `scripts/spec-surfaces.ts` (35 unique URLs) and compares against
+  `scripts/spec-hashes.json`; a changed page is reported as drift with the
+  recorded date and URL. `bun run spec:record` rewrites the baseline after a
+  human has re-read the page. Page text is never stored. GitHub blob URLs are
+  fetched as raw files. Offline tests cover normalisation, hashing, and the
+  baseline file's shape.
+- Conformance fixtures carry the vendors' own examples verbatim: Claude
+  `type: "http"` / `"streamable-http"` MCP entries and the five documented
+  hook handler examples (command exec form, http, mcp_tool, prompt, agent);
+  Copilot CLI `exec`, `http`, `prompt`, and the PascalCase lifecycle names;
+  Gemini `httpUrl`, SSE `url`, and `%VAR_NAME%` env; the Command Code agents
+  page's full frontmatter example; the Agent Skills optional-fields example
+  with its referenced files; the VS Code OS-override example with its scripts.
+  With the pre-fix checks these fixtures fail on `claude-json`,
+  `copilot-hooks`, and `gemini-json`.
+- The conformance test pins a minimum fact count per fixture, so a discovery
+  regression that silently drops a file cannot keep a fixture green.
+
+### Fixed
+
+- `commandcode.mcp.invalid-transport` no longer fires on `"type":
+  "streamable-http"` in a shared `.mcp.json` — Claude Code documents it as an
+  alias for `http`. It also no longer fires on `sse` in Command Code-only
+  files, which the Command Code MCP page names as a transport it connects to
+  (skip, not a claim of support).
+- `agent-skills.skill.invalid-name` accepts lowercase letters from any script
+  (`résumé-builder`), matching the spec's "unicode lowercase alphanumeric" and
+  the `skills-ref` reference validator. Uppercase, underscores, spaces, and
+  hyphen placement are still rejected.
+- `copilot.hook.command-without-command` accepts the documented `exec` (+
+  `args`) form as a complete command handler; `exec` paths are existence-
+  checked like any other launch.
+- `copilot.hook.unknown-event` accepts the PascalCase spellings the Copilot
+  reference documents for Copilot-only events in `version: 1` files:
+  `SessionEnd`, `PostToolUseFailure`, `ErrorOccurred`, `PermissionRequest`.
+  Native VS Code files still reject them.
+- `mcp.literal-env` treats Gemini CLI's documented Windows `%VAR_NAME%` form as
+  interpolation, not a literal secret.
+- `commandcode.agent.invalid-permission-mode` accepts `inherit`, the value the
+  agents page lists as the field's default.
+
+### Changed
+
+- All `docs/spec/*.md` captures whose source page was re-read carry
+  `**Read:** 2026-09-02`; `scripts/spec-surfaces.ts` and the registry's
+  `lastVerified` match. Six discovery-only surfaces that were not re-opened
+  keep their earlier date.
+- `bun run spec:check` now also diffs the Copilot PascalCase aliases against
+  the live page, and exits 1 when any source page's content hash has moved.
+- New captured lines: Claude hook `args` exec form and `${CLAUDE_PLUGIN_DATA}`;
+  Claude sub-agent skip list; VS Code agent-scoped and plugin hook locations;
+  Command Code `reasoningEffort` (documented, invalid values fall back and
+  load — no check); Antigravity "legacy fields like `url` or `httpUrl` are not
+  supported"; Continue `uses:` cited from the config reference.
+
+### From #13 — true findings and Windsurf Cascade hooks / skills
+
+- `.agentscan-root` now stops walk-up, so a dirty `/tmp/.git` cannot become the
+  scan root for fixtures or nested checkouts.
+- Fenced `SKILL.md` examples: a bundled path on the second line of a code
+  fence is not `skill.broken-reference`.
+- Unclosed YAML `---` is `config.unreadable`, not `*.skill.missing-frontmatter`.
+- Invalid Windsurf rule YAML is not `windsurf.rule.missing-trigger`.
+- `node .` / `"."` is not a missing hook script or MCP command.
+- Skill-directory symlinks that leave the scan root are not inventoried.
+- `--global` copy names Copilot hooks and Windsurf user files; Action
+  `bun-version` defaults to `1.4.0` (CI pin).
+- Windsurf Cascade hooks: `.windsurf/hooks.json` and `--global`
+  `~/.codeium/windsurf/hooks.json`. 12 snake_case events; `command` /
+  `powershell`; `windsurf.hook.unknown-event`, `missing-script`,
+  `command-without-command`.
+- Windsurf Cascade skills: `.windsurf/skills` and `--global`
+  `~/.codeium/windsurf/skills`. Agent Skills contract (page cites
+  agentskills.io). System skill dirs unread.
+
+## 1.3.0 — 2026-08-31
+
+Native Windsurf / Cascade coverage against 2026-08-31 official docs.
+**99 checks**, **457 tests**.
+
+### Added
+
+- Spec captures `docs/spec/windsurf-rules.md`, `windsurf-agents-md.md`,
+  `windsurf-mcp.md`.
+- Workspace rules: `.devin/rules/*.md` (preferred), `.windsurf/rules/*.md`
+  (fallback), subdirectory-scoped trees, legacy `.windsurfrules`.
+  `.devin` is a scan-root signal.
+- Character budgets: `windsurf.rule.too-large` (12,000) and
+  `windsurf.rule.global-too-large` (6,000). Never `cursor.rule.too-large`.
+- `windsurf.rule.missing-trigger` on workspace `.devin` / `.windsurf` rules
+  that omit frontmatter `trigger`. Not on `.windsurfrules`,
+  `global_rules.md`, or `AGENTS.md`.
+- Portable lowercase `agents.md` (same `sourceProvider: unknown` as
+  `AGENTS.md`).
+- `--global` Cascade MCP at `~/.codeium/windsurf/mcp_config.json`
+  (`windsurf-json`). Launch is `command` or `serverUrl` or `url`.
+  `windsurf.mcp.no-launch` when none are set. Never
+  `claude.mcp.url-without-type`.
+- `--global` `~/.codeium/windsurf/memories/global_rules.md` only. Other
+  files in that memories directory stay unread.
+
+### Unread (intentional)
+
+- Devin Local CLI MCP (no published path).
+- Auto-generated memories other than `global_rules.md`.
+- System / enterprise rule directories.
+- Project MCP (none quoted).
+- Marketplace, admin allowlists, OAuth stores.
+
+## 1.2.1 — 2026-08-31
+
+Codex user MCP under `--global`. **95 checks**, **441 tests**.
+
+### Added
+
+- `$CODEX_HOME/config.toml` (default `~/.codex/config.toml`) is opened only
+  with `--global`. Same `codex-toml` shape as project `.codex/config.toml`.
+- Same-name user and project servers both stay in the inventory. The
+  published page does not quote a replace-entirely rule, so this scanner
+  does not invent `codexEffective`.
+- Spec recapture `docs/spec/codex-mcp.md` (user path, `CODEX_HOME`, unread
+  system / managed / requirements / profiles / plugins / trust / `auth.json`).
+
+### Unread (intentional)
+
+- System `/etc/codex/config.toml`, managed preferences, `requirements.toml`,
+  profile files, plugin MCP, `trust_level`.
+- User-file `project_doc_*` knobs.
+- Claude global settings; Command Code `projects/{slug}/mcp.json`.
+
+## 1.2.0 — 2026-08-31
+
+Native Grok Build provider against 2026-08-31 official docs. **95 checks**,
+**435 tests**. Compatibility with Claude or Cursor is not schema identity.
+
+### Added
+
+- Spec captures `docs/spec/grok-mcp.md`, `grok-hooks.md`, `grok-skills.md`,
+  `grok-rules.md`, `grok-agents.md`.
+- Profiles: `grok-toml` MCP, `grok` hook and skill schemas.
+  `inferHookSchemaProfile("grok")` is `"grok"`, not `"claude"`.
+- Project `.grok/config.toml` walk-up (cwd → scan boundary). User
+  `$GROK_HOME/config.toml` or `~/.grok/config.toml` under `--global`.
+  Same-name project replaces user; closer project file wins.
+  `grok.mcp.no-launch` when neither `command` nor `url` is set. Never
+  `claude.mcp.url-without-type` on `grok-toml`.
+- `.grok/hooks/*.json` and user hooks under `--global`. Fourteen events;
+  handlers `command` / `http`. Copilot `version: 1` remap is not applied.
+- `.grok/skills` (and user skills under `--global`). Frontmatter required;
+  `name` / `description` optional. Agent Skills directory-match and Claude
+  listing-budget checks do not run.
+- `.grok/rules/*.md` with no size cap. `Agents.md` and `AGENT.md` as Grok
+  instruction files beside `AGENTS.md`.
+- Conformance fixture `tests/fixtures/conformance/grok-toml/`.
+- `spec:check` drifts Grok hook event names against the live hooks page.
+
+### Unread (intentional)
+
+- Managed / requirements TOML, plugins, marketplaces, personas, LSP,
+  `sandbox.toml`, `pager.toml`.
+- `[skills] paths` (no quoted resolution base).
+- `.grok/agents/` (directory named, no filename pattern).
+- Claude / Cursor / `.mcp.json` as Grok-consumed.
+- `.gitignore` skip for instruction files.
+- Credential files (`auth.json`, `mcp_credentials.json`).
+
 ## 1.1.0 — 2026-08-31
 
 Native Command Code provider, then a correctness pass over every registered