plugin-scanner 2.0.108__tar.gz → 2.0.109__tar.gz

{plugin_scanner-2.0.108 → plugin_scanner-2.0.109}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 2.0.108
+Version: 2.0.109
 Summary: Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows.
 Project-URL: Homepage, https://github.com/hashgraph-online/ai-plugin-scanner
 Project-URL: Repository, https://github.com/hashgraph-online/ai-plugin-scanner
@@ -302,33 +302,44 @@ The scanner evaluates only the surfaces a plugin actually exposes, then normaliz
 
 ```bash
 # Scan a plugin directory
-plugin-scanner ./my-plugin
+plugin-scanner scan ./my-plugin
 
 # Auto-detect all supported ecosystems inside a repo (default)
-plugin-scanner ./plugins-repo --ecosystem auto
+plugin-scanner scan ./plugins-repo --ecosystem auto
 
 # Scan only Claude package surfaces
-plugin-scanner ./plugins-repo --ecosystem claude
+plugin-scanner scan ./plugins-repo --ecosystem claude
 
 # List supported ecosystems
 plugin-scanner --list-ecosystems
 
 # Output JSON
-plugin-scanner ./my-plugin --json
+plugin-scanner scan ./my-plugin --format json
 
 # Write a SARIF report for GitHub code scanning
-plugin-scanner ./my-plugin --format sarif --output plugin-scanner.sarif
+plugin-scanner scan ./my-plugin --format sarif --output plugin-scanner.sarif
 
 # Fail CI on findings at or above high severity
-plugin-scanner ./my-plugin --fail-on-severity high
+plugin-scanner scan ./my-plugin --fail-on-severity high
 
 # Require Cisco skill scanning with a strict policy
-plugin-scanner ./my-plugin --cisco-skill-scan on --cisco-policy strict
+plugin-scanner scan ./my-plugin --cisco-skill-scan on --cisco-policy strict
 
 # Require optional Cisco MCP static analysis
-plugin-scanner ./my-plugin --cisco-mcp-scan on
+plugin-scanner scan ./my-plugin --cisco-mcp-scan on
 ```
 
+Use the bare `plugin-scanner ./my-plugin` form only for compatibility with older automation. New scripts and docs should
+prefer explicit subcommands so `scan`, `lint`, `verify`, `submit`, and `doctor` have predictable help, flags, and output.
+
+| Need | Command | Output contract |
+| :--- | :--- | :--- |
+| Human release summary | `plugin-scanner scan ./my-plugin` | terminal summary first, optional JSON/Markdown/SARIF with `--format` |
+| Rule-level authoring feedback | `plugin-scanner lint ./my-plugin` | human findings by default, JSON with `--format json` |
+| Runtime readiness details | `plugin-scanner verify ./my-plugin` | human pass/fail by default, JSON with `--format json` |
+| Publishable quality artifact | `plugin-scanner submit ./my-plugin --attest dist/plugin-quality.json` | writes one artifact for one plugin directory |
+| Troubleshooting bundle | `plugin-scanner doctor ./my-plugin --component mcp --bundle dist/doctor.zip` | diagnostic JSON and bundle artifacts |
+
 ## Quality Suite Commands
 
 ```bash

{plugin_scanner-2.0.108 → plugin_scanner-2.0.109}/README.md

@@ -262,33 +262,44 @@ The scanner evaluates only the surfaces a plugin actually exposes, then normaliz
 
 ```bash
 # Scan a plugin directory
-plugin-scanner ./my-plugin
+plugin-scanner scan ./my-plugin
 
 # Auto-detect all supported ecosystems inside a repo (default)
-plugin-scanner ./plugins-repo --ecosystem auto
+plugin-scanner scan ./plugins-repo --ecosystem auto
 
 # Scan only Claude package surfaces
-plugin-scanner ./plugins-repo --ecosystem claude
+plugin-scanner scan ./plugins-repo --ecosystem claude
 
 # List supported ecosystems
 plugin-scanner --list-ecosystems
 
 # Output JSON
-plugin-scanner ./my-plugin --json
+plugin-scanner scan ./my-plugin --format json
 
 # Write a SARIF report for GitHub code scanning
-plugin-scanner ./my-plugin --format sarif --output plugin-scanner.sarif
+plugin-scanner scan ./my-plugin --format sarif --output plugin-scanner.sarif
 
 # Fail CI on findings at or above high severity
-plugin-scanner ./my-plugin --fail-on-severity high
+plugin-scanner scan ./my-plugin --fail-on-severity high
 
 # Require Cisco skill scanning with a strict policy
-plugin-scanner ./my-plugin --cisco-skill-scan on --cisco-policy strict
+plugin-scanner scan ./my-plugin --cisco-skill-scan on --cisco-policy strict
 
 # Require optional Cisco MCP static analysis
-plugin-scanner ./my-plugin --cisco-mcp-scan on
+plugin-scanner scan ./my-plugin --cisco-mcp-scan on
 ```
 
+Use the bare `plugin-scanner ./my-plugin` form only for compatibility with older automation. New scripts and docs should
+prefer explicit subcommands so `scan`, `lint`, `verify`, `submit`, and `doctor` have predictable help, flags, and output.
+
+| Need | Command | Output contract |
+| :--- | :--- | :--- |
+| Human release summary | `plugin-scanner scan ./my-plugin` | terminal summary first, optional JSON/Markdown/SARIF with `--format` |
+| Rule-level authoring feedback | `plugin-scanner lint ./my-plugin` | human findings by default, JSON with `--format json` |
+| Runtime readiness details | `plugin-scanner verify ./my-plugin` | human pass/fail by default, JSON with `--format json` |
+| Publishable quality artifact | `plugin-scanner submit ./my-plugin --attest dist/plugin-quality.json` | writes one artifact for one plugin directory |
+| Troubleshooting bundle | `plugin-scanner doctor ./my-plugin --component mcp --bundle dist/doctor.zip` | diagnostic JSON and bundle artifacts |
+
 ## Quality Suite Commands
 
 ```bash

{plugin_scanner-2.0.108 → plugin_scanner-2.0.109}/docs/guard/get-started.md

@@ -76,6 +76,30 @@ Use it when you want to protect a harness before local MCP servers, skills, hook
    hol-guard device rotate
    ```
 
+## Which command should I use?
+
+| Situation | Command | What it answers |
+| :--- | :--- | :--- |
+| I need the current protection posture | `hol-guard status` | What is Guard watching, is sync connected, and what is the next action? |
+| I need setup or runtime troubleshooting | `hol-guard doctor <harness>` | Why is this harness or Guard runtime not behaving correctly? |
+| A launch was blocked or changed | `hol-guard diff <harness>` | What changed since the last recorded snapshot? |
+| I need to resolve a queued block | `hol-guard approvals` | Which requests are waiting, and how do I approve or deny them? |
+| I need decision history | `hol-guard receipts` | What decisions did Guard record locally? |
+| I need the tracked catalog | `hol-guard inventory` | Which artifacts are currently tracked and present? |
+| I need an exportable evidence artifact | `hol-guard abom` | What local AI-BOM can I attach to an audit or handoff? |
+| I need the chronological log | `hol-guard events` | What happened over time on this machine? |
+
+## Troubleshooting
+
+| Symptom | Start here | Then try |
+| :--- | :--- | :--- |
+| Guard did not find my harness | `hol-guard detect --json` | `hol-guard doctor <harness> --json` for adapter-specific warnings |
+| `hol-guard run` paused a launch | `hol-guard diff <harness>` | `hol-guard approvals`, then retry `hol-guard run <harness>` |
+| I approved a prompt and want proof | `hol-guard receipts` | `hol-guard explain <artifact-id>` for the latest receipt and diff context |
+| I need audit or handoff evidence | `hol-guard inventory` | `hol-guard abom --format json` for machine-readable export |
+| I need to understand recent activity | `hol-guard events` | Use `--name <event>` to filter a noisy local timeline |
+| Cloud sync or pairing looks wrong | `hol-guard status` | `hol-guard connect` or `hol-guard sync --json` depending on the status output |
+
 ## Evidence-first decisions
 
 Guard now scores local decisions from structured evidence, not only string heuristics. Each changed artifact carries:

{plugin_scanner-2.0.108 → plugin_scanner-2.0.109}/docs/guard/testing-matrix.md

@@ -10,6 +10,8 @@ Automated coverage in this phase includes:
 - consumer-mode JSON contract generation against scanner fixtures
 - local HTTP sync against a live in-process server instead of mocked transport
 - scheduled self-hosted harness smoke through `.github/workflows/harness-smoke.yml`
+- CLI DX contract tests for summary-first `run`, `explain`, `doctor`, `scan`, `lint`, and `verify` output
+- scanner command consistency tests for nonexistent target handling across `scan`, `lint`, `verify`, `doctor`, and `submit`
 
 Manual verification should include:
 
@@ -32,6 +34,14 @@ Manual verification should include:
 - `hol-guard install codex`
 - `hol-guard run codex --dry-run --default-action allow --json`
 - `hol-guard receipts`
+- `hol-guard explain codex:project:<artifact-name>`
+- `hol-guard diff codex`
+- `hol-guard events`
+- `hol-guard abom`
+- `plugin-scanner scan tests/fixtures/good-plugin --format json`
+- `plugin-scanner lint tests/fixtures/good-plugin --format json`
+- `plugin-scanner verify tests/fixtures/good-plugin --format json`
+- `plugin-scanner doctor tests/fixtures/good-plugin --component mcp --bundle dist/doctor.zip`
 - `codex mcp list`
 - `cursor-agent mcp list`
 - `antigravity --help`

{plugin_scanner-2.0.108 → plugin_scanner-2.0.109}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plugin-scanner"
-version = "2.0.108"
+version = "2.0.109"
 description = "Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-2.0.108 → plugin_scanner-2.0.109}/pyproject.toml.bak

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hol-guard"
-version = "2.0.108"
+version = "2.0.109"
 description = "Protect local AI harnesses with HOL Guard and run scanner checks for Codex, Claude, Cursor, Gemini, and OpenCode."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-2.0.108 → plugin_scanner-2.0.109}/src/codex_plugin_scanner/guard/cli/commands.py

@@ -150,7 +150,15 @@ _GUARD_HELP_GROUPS = (
     "  bootstrap    Detect, install, and launch the approval center\n"
     "  install      Enable Guard management for a harness\n"
     "  uninstall    Disable Guard management for a harness\n"
-    "  update       Update hol-guard in the current environment"
+    "  update       Update hol-guard in the current environment\n"
+    "\n"
+    "Command selection:\n"
+    "  Use status for current posture and the next safe step\n"
+    "  Use doctor for setup and runtime probes\n"
+    "  Use diff for changed artifacts after a blocked launch\n"
+    "  Use explain for detailed artifact evidence\n"
+    "  Use approvals for queued decisions and receipts for audit history\n"
+    "  Use events for the local timeline"
 )
 
 

{plugin_scanner-2.0.108 → plugin_scanner-2.0.109}/src/codex_plugin_scanner/guard/cli/render.py

@@ -285,37 +285,37 @@ def _render_doctor(console: Console, payload: dict[str, object]) -> None:
         )
         adapters = _coerce_dict_list(payload.get("adapters"))
         console.print(_build_harness_table(adapters))
-        return
-
-    warnings = _coerce_string_list(payload.get("warnings"))
-    summary = Table.grid(padding=(0, 1))
-    summary.add_row("Harness", f"[bold]{payload.get('harness', 'unknown')}[/bold]")
-    summary.add_row("Installed", _bool_label(bool(payload.get("installed"))))
-    summary.add_row("Command", _bool_label(bool(payload.get("command_available"))))
-    summary.add_row("Artifacts", str(len(_coerce_dict_list(payload.get("artifacts")))))
-    registry = payload.get("runtime_detector_registry")
-    if isinstance(registry, dict):
-        registry_state = "enabled" if bool(registry.get("enabled")) else "disabled"
-        timeout_ms = registry.get("timeout_ms")
-        summary.add_row("Detector registry", f"{registry_state}, {timeout_ms} ms")
-    summary.add_row("Warnings", str(len(warnings)))
-    console.print(Panel(summary, title="Guard doctor", border_style="cyan"))
-    if warnings:
-        warning_text = "\n".join(
-            textwrap.fill(
-                f"• {warning}",
-                width=72,
-                subsequent_indent="  ",
+    else:
+        warnings = _coerce_string_list(payload.get("warnings"))
+        summary = Table.grid(padding=(0, 1))
+        summary.add_row("Harness", f"[bold]{payload.get('harness', 'unknown')}[/bold]")
+        summary.add_row("Installed", _bool_label(bool(payload.get("installed"))))
+        summary.add_row("Command", _bool_label(bool(payload.get("command_available"))))
+        summary.add_row("Artifacts", str(len(_coerce_dict_list(payload.get("artifacts")))))
+        registry = payload.get("runtime_detector_registry")
+        if isinstance(registry, dict):
+            registry_state = "enabled" if bool(registry.get("enabled")) else "disabled"
+            timeout_ms = registry.get("timeout_ms")
+            summary.add_row("Detector registry", f"{registry_state}, {timeout_ms} ms")
+        summary.add_row("Warnings", str(len(warnings)))
+        console.print(Panel(summary, title="Guard doctor", border_style="cyan"))
+        if warnings:
+            warning_text = "\n".join(
+                textwrap.fill(
+                    f"• {warning}",
+                    width=72,
+                    subsequent_indent="  ",
+                )
+                for warning in warnings
             )
-            for warning in warnings
-        )
-        console.print(Panel(Text(warning_text), title="Attention", border_style="yellow"))
-    runtime_probe = payload.get("runtime_probe")
-    if isinstance(runtime_probe, dict):
-        console.print(_build_runtime_probe_panel(runtime_probe))
-    artifacts = _coerce_dict_list(payload.get("artifacts"))
-    if artifacts:
-        console.print(_build_artifact_table(artifacts))
+            console.print(Panel(Text(warning_text), title="Attention", border_style="yellow"))
+        runtime_probe = payload.get("runtime_probe")
+        if isinstance(runtime_probe, dict):
+            console.print(_build_runtime_probe_panel(runtime_probe))
+        artifacts = _coerce_dict_list(payload.get("artifacts"))
+        if artifacts:
+            console.print(_build_artifact_table(artifacts))
+    console.print(_build_diagnostic_command_panel())
 
 
 def _render_run(console: Console, payload: dict[str, object]) -> None:
@@ -481,7 +481,11 @@ def _render_advisories(console: Console, payload: dict[str, object]) -> None:
             border_style="cyan",
         )
     )
-    table = Table(box=box.SIMPLE_HEAVY, show_header=True)
+    console.print(_build_advisory_table(items))
+
+
+def _build_advisory_table(items: list[dict[str, object]], *, title: str | None = None) -> Table:
+    table = Table(title=title, box=box.SIMPLE_HEAVY, show_header=True)
     table.add_column("Publisher", style="bold")
     table.add_column("Severity")
     table.add_column("Headline")
@@ -493,7 +497,7 @@ def _render_advisories(console: Console, payload: dict[str, object]) -> None:
             str(item.get("headline") or item.get("cache_key") or "advisory"),
             str(item.get("updated_at") or "unknown"),
         )
-    console.print(table)
+    return table
 
 
 def _render_events(console: Console, payload: dict[str, object]) -> None:
@@ -1077,6 +1081,40 @@ def _render_scan(console: Console, payload: dict[str, object]) -> None:
     _render_cisco_evidence(console, payload)
 
 
+def _render_explain(console: Console, payload: dict[str, object]) -> None:
+    advisories = _coerce_dict_list(payload.get("advisories"))
+    if "artifact_snapshot" in payload:
+        console.print(Panel(_build_consumer_summary_table(payload), title="Path evidence", border_style="cyan"))
+        _render_consumer_evidence_panels(console, payload)
+        _render_cisco_evidence(console, payload)
+        if advisories:
+            console.print(_build_advisory_table(advisories, title="Matching advisories"))
+        return
+    artifact = payload.get("artifact")
+    if not isinstance(artifact, dict):
+        _render_fallback(console, payload)
+        return
+    latest_receipt = payload.get("latest_receipt")
+    latest_diff = payload.get("latest_diff")
+    body = Table.grid(padding=(0, 1))
+    body.add_row("Artifact", str(artifact.get("artifact_name") or artifact.get("artifact_id") or "unknown"))
+    body.add_row("Harness", str(artifact.get("harness") or "unknown"))
+    body.add_row("Type", str(artifact.get("artifact_type") or "artifact"))
+    body.add_row("Scope", str(artifact.get("source_scope") or "unknown"))
+    body.add_row("Present", _bool_label(bool(artifact.get("present"))))
+    if isinstance(latest_receipt, dict):
+        body.add_row("Latest decision", _action_text(str(latest_receipt.get("policy_decision") or "warn")))
+        body.add_row("Receipt time", str(latest_receipt.get("timestamp") or "unknown"))
+    if isinstance(latest_diff, dict):
+        changed_fields = ", ".join(_coerce_string_list(latest_diff.get("changed_fields"))) or "no field changes"
+        body.add_row("Latest diff", changed_fields)
+        body.add_row("Current hash", str(latest_diff.get("current_hash") or "unknown"))
+    body.add_row("Advisories", str(len(advisories)))
+    console.print(Panel(body, title="Guard artifact evidence", border_style="cyan"))
+    if advisories:
+        console.print(_build_advisory_table(advisories, title="Matching advisories"))
+
+
 def _render_preflight(console: Console, payload: dict[str, object]) -> None:
     install_verdict = payload.get("install_verdict")
     install_target = payload.get("install_target")
@@ -1209,6 +1247,21 @@ def _build_steps_panel(steps: list[dict[str, object]]) -> Panel:
     return Panel("\n\n".join(lines), title="Next steps", border_style="green")
 
 
+def _build_diagnostic_command_panel() -> Panel:
+    return Panel(
+        "\n".join(
+            (
+                "Use status for current posture: hol-guard status",
+                "Use doctor for setup and runtime probes: hol-guard doctor <harness>",
+                "Use diff for changed artifacts: hol-guard diff <harness>",
+                "Use events for the local timeline: hol-guard events",
+            )
+        ),
+        title="Which diagnostic command?",
+        border_style="blue",
+    )
+
+
 def _render_harness_detail(console: Console, detection: dict[str, object]) -> None:
     artifacts = _coerce_dict_list(detection.get("artifacts"))
     warnings = _coerce_string_list(detection.get("warnings"))
@@ -1308,13 +1361,7 @@ def _build_run_steps(payload: dict[str, object], *, blocked: bool, dry_run: bool
     approvals_command = payload.get("approvals_command")
     if blocked and dry_run:
         review_command = (
-            str(approvals_command)
-            if approval_center_url and isinstance(approvals_command, str) and approvals_command
-            else "hol-guard approvals"
-            if approval_center_url
-            else str(rerun_command)
-            if isinstance(rerun_command, str) and rerun_command
-            else f"hol-guard run {harness}"
+            str(rerun_command) if isinstance(rerun_command, str) and rerun_command else f"hol-guard run {harness}"
         )
         inspect_command = (
             str(diff_command) if isinstance(diff_command, str) and diff_command else f"hol-guard diff {harness}"
@@ -1324,12 +1371,29 @@ def _build_run_steps(payload: dict[str, object], *, blocked: bool, dry_run: bool
             if isinstance(review_hint, str) and review_hint
             else "Rerun without --dry-run to review the full blocker set and continue into the harness launch."
         )
-        return [
+        steps = [
             {
                 "title": "Resolve the blocked launch",
                 "command": review_command,
                 "detail": review_detail,
             },
+        ]
+        if approval_center_url:
+            approval_command = (
+                str(approvals_command)
+                if isinstance(approvals_command, str) and approvals_command
+                else "hol-guard approvals"
+            )
+            steps.append(
+                {
+                    "title": "Open the approvals queue",
+                    "command": approval_command,
+                    "detail": (
+                        "Review any queued approval requests after the prompt appears, then retry the guarded command."
+                    ),
+                }
+            )
+        steps.append(
             {
                 "title": "Inspect only the changed config entries (optional)",
                 "command": inspect_command,
@@ -1338,17 +1402,19 @@ def _build_run_steps(payload: dict[str, object], *, blocked: bool, dry_run: bool
                     "Guard still needs you to review."
                 ),
             },
-        ]
-    if blocked and isinstance(review_hint, str) and review_hint:
-        command = (
-            str(approvals_command)
-            if approval_center_url and isinstance(approvals_command, str) and approvals_command
-            else "hol-guard approvals"
-            if approval_center_url
-            else str(rerun_command)
-            if isinstance(rerun_command, str) and rerun_command
-            else f"hol-guard run {harness}"
         )
+        return steps
+    if blocked and isinstance(review_hint, str) and review_hint:
+        if approval_center_url:
+            command = (
+                str(approvals_command)
+                if isinstance(approvals_command, str) and approvals_command
+                else "hol-guard approvals"
+            )
+        elif isinstance(rerun_command, str) and rerun_command:
+            command = str(rerun_command)
+        else:
+            command = f"hol-guard run {harness}"
         return [{"title": "Resolve the blocked launch", "command": command, "detail": review_hint}]
     if dry_run:
         launch_command = (
@@ -1749,5 +1815,5 @@ _RENDERERS: dict[str, Any] = {
     "protect": _render_protect,
     "preflight": _render_preflight,
     "scan": _render_scan,
-    "explain": _render_scan,
+    "explain": _render_explain,
 }

{plugin_scanner-2.0.108 → plugin_scanner-2.0.109}/src/codex_plugin_scanner/version.py

@@ -1,3 +1,3 @@
 """Single source of truth for tool version."""
 
-__version__ = "2.0.108"
+__version__ = "2.0.109"

{plugin_scanner-2.0.108 → plugin_scanner-2.0.109}/tests/test_cli.py

@@ -162,6 +162,42 @@ class TestMain:
         rc = main(["/nonexistent/path/that/does/not/exist"])
         assert rc == 1
 
+    def test_scan_and_lint_reject_nonexistent_directory_consistently(self, capsys):
+        scan_rc = main(["scan", str(NONEXISTENT_PLUGIN_DIR), "--format", "json"])
+        scan_captured = capsys.readouterr()
+
+        lint_rc = main(["lint", str(NONEXISTENT_PLUGIN_DIR), "--format", "json"])
+        lint_captured = capsys.readouterr()
+
+        expected = f'Error: "{NONEXISTENT_PLUGIN_DIR}" is not a directory.'
+        assert scan_rc == 1
+        assert lint_rc == 1
+        assert expected in scan_captured.err
+        assert expected in lint_captured.err
+        assert scan_captured.out == ""
+        assert lint_captured.out == ""
+
+    def test_scanner_human_outputs_stay_summary_first(self, capsys):
+        scan_rc = main(["scan", str(FIXTURES / "good-plugin")])
+        scan_output = capsys.readouterr().out
+
+        lint_rc = main(["lint", str(FIXTURES / "good-plugin")])
+        lint_output = capsys.readouterr().out
+
+        verify_rc = main(["verify", str(FIXTURES / "good-plugin")])
+        verify_output = capsys.readouterr().out
+
+        assert scan_rc == 0
+        assert lint_rc == 0
+        assert verify_rc == 0
+        assert "Plugin Scanner" in scan_output
+        assert "Final Score" in scan_output
+        assert "Lint profile" in lint_output
+        assert "Verification: PASS" in verify_output
+        assert '"schema_version"' not in scan_output
+        assert '"policy_pass"' not in lint_output
+        assert '"verify_pass"' not in verify_output
+
     def test_invalid_top_level_command_suggests_closest_match(self, capsys):
         with pytest.raises(SystemExit) as exc_info:
             main(["verfy"])