Kjell Tore Guttormsen 001090261e fix(plugin-health): make the command able to read what the scanner found

Dogfooding `/config-audit plugin-health` against a fasit registered before the
run: 11 of 12 predictions confirmed, 1 refuted with evidence, 0 deviations.
The command's default path could not produce the report it documents.

M-BUG-21 (third arm): the argument loop ended in
`else if (!args[i].startsWith('-')) targetPath = args[i]` with no unknown-flag
branch, so `--output-file /tmp/x.json` was dropped and its value became the scan
target. Worse than in drift-cli: a non-existent path discovers no plugins, so the
scanner answered "No plugins found" (info) with exit 0 — a reassuring answer, not
an error. Unknown options and a value-less `--output-file` now exit 3.

M-BUG-33: the scanner had no `--output-file` and its default-mode report goes to
stderr, which `commands/plugin-health.md` discards with `2>/dev/null` before
telling the agent to read stdout. Zero bytes captured.

M-BUG-34: per-plugin rows and the grade formula never left `scan()` — the only
grade code, `formatPluginHealthReport`, had no caller — and cross-plugin findings
were flattened behind a `category` they share with per-plugin findings. The
mandated table and Cross-Plugin section were unbuildable, so the command had to
fabricate them. `scanDetailed()` now returns them; `scan()`'s frozen v5.0.0
envelope is unchanged by construction.

M-BUG-35: `.claude-plugin/marketplace.json` was flagged as an unknown file. It is
the documented catalog location, and `"source": "./"` makes the repo root its own
plugin, so one `.claude-plugin/` legitimately holds both.

Also: `commands/posture.md` ran both optional scanners in default mode under
`2>/dev/null` and read stdout — the same class as feature-gap.md:133 in the fix
chunk. A CLI-side flag fix does not close its callers.

Tests 1420 -> 1432, red first. Frozen v5.0.0 snapshots untouched.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XhhZ8zg1amR7YCAPqiZWdt

2026-07-31 21:08:32 +02:00

3.3 KiB

Raw Blame History

name	description	argument-hint	allowed-tools	model
config-audit:plugin-health	Audit plugin configuration quality — validates structure, frontmatter, and cross-plugin coherence	[plugin-path]	Read, Glob, Grep, Bash	sonnet

Config-Audit: Plugin Health

Audit Claude Code plugin structure and quality — validates plugin.json, CLAUDE.md, command/agent frontmatter, and detects cross-plugin conflicts.

Arguments

$ARGUMENTS may contain a path to a specific plugin directory
If omitted: scans all plugins in the marketplace root
--raw: pass-through to the scanner; produces v5.0.0 verbatim envelope (bypasses the humanizer) for byte-stable diff tooling

Implementation

Step 1: Discover plugins and greet

If a specific path is given, scan only that plugin. Otherwise, find all plugins using Glob for **/.claude-plugin/plugin.json.

Tell the user:

## Plugin Health Check

Auditing {N} plugin(s) for structure, frontmatter quality, and cross-plugin conflicts...

Step 2: Run scanner

Run silently for each plugin. Default mode writes a humanized JSON payload to --output-file where each PLH finding carries userImpactCategory, userActionLanguage, and relevanceContext alongside the v5.0.0 fields. --raw is passed through verbatim when present, and prints the byte-stable v5.0.0 envelope on stdout instead.

TMPFILE="/tmp/config-audit-plugin-health-$$.json"
RAW_FLAG=""
if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
node ${CLAUDE_PLUGIN_ROOT}/scanners/plugin-health-scanner.mjs <path> --output-file "$TMPFILE" $RAW_FLAG 2>/dev/null; echo $?

Read $TMPFILE with the Read tool. Exit codes 0, 1 and 2 are normal; only 3 is a real error.

The payload carries three things the report needs:

plugins[] — one row per plugin: name, declaredName, commandCount, agentCount, findingCount, score, grade. Use these for the table; never estimate a grade yourself.
cross_plugin_findings[] — the namespace-collision and shared-command-name findings, already separated from the per-plugin ones (they also carry crossPlugin: true in findings).
findings[] — every finding, humanized.

Step 3: Present results

### Plugin Health Report

| Plugin | Grade | Commands | Agents | Status |
|--------|-------|----------|--------|--------|
| {plugins[].name} | {plugins[].grade} ({plugins[].score}) | {plugins[].commandCount} | {plugins[].agentCount} | {Good/Issues found} |
| ... | ... | ... | ... | ... |

{If cross-plugin issues:}
#### Cross-Plugin Issues ({count})
| Issue | Plugins | Recommendation |
|-------|---------|----------------|
| ... | ... | ... |

{If findings:}
#### Findings by Plugin

**{plugin-name}** ({finding_count} findings):
1. [{userActionLanguage}] {humanized title} ({id}) — {humanized recommendation}
2. ...

Group findings within each plugin by userImpactCategory (e.g., "Configuration mistake", "Conflict") and lead each line with userActionLanguage ("Fix this now", "Fix soon", "Optional cleanup"). The humanizer already produced the plain-language title/recommendation strings — render them verbatim, do not paraphrase.

Step 4: Suggest next steps

### What's next

- Fix structural issues based on recommendations above
- `/config-audit posture` — Full configuration posture assessment
- `/config-audit fix` — Auto-fix deterministic issues

3.3 KiB Raw Blame History