vulnctl 0.2.0__tar.gz → 0.2.2__tar.gz

{vulnctl-0.2.0 → vulnctl-0.2.2}/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-08-01
+
+### Fixed
+
+- **Root help type column now matches Typer's own spelling.** The generated
+  "Options by command" panel derived its type column itself (`PATH`, `TEXT`),
+  which disagreed with the per-command panels on Typer 0.27+ — what a fresh
+  `pipx install vulnctl` resolves — where Typer prints `<path>`, `<str>`. It
+  now delegates to Click's metavar, so both spellings track the installed
+  version. Arguments drop the column entirely: their metavar already names
+  what they take.
+
+## [0.2.1] - 2026-08-01
+
+### Added
+
+- **Self-contained `vulnctl --help`**: the root help now ends with an
+  **Options by command** panel — every command's arguments and flags, what
+  each takes, and what it does — and an **Examples** panel covering the
+  offline, SBOM, CI-gating, filtering, and `explain` workflows. Previously the
+  root help named the three commands and nothing else, so discovering a flag
+  meant running `--help` once per command. The summary is generated by walking
+  the registered parameters, so it cannot fall out of sync with the real
+  signatures. Per-command `--help` is unchanged and remains the place for
+  defaults, value ranges, and exit codes.
+
 ## [0.2.0] - 2026-08-01
 
 Makes the output actionable and readable, and accepts GHSA identifiers
@@ -116,6 +142,8 @@ that produced it.
   sign with keyless cosign (OIDC), and publish to PyPI via trusted publishing
   (no stored token).
 
-[Unreleased]: https://github.com/NokiGuard/vulnctl/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/NokiGuard/vulnctl/compare/v0.2.2...HEAD
+[0.2.2]: https://github.com/NokiGuard/vulnctl/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/NokiGuard/vulnctl/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/NokiGuard/vulnctl/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/NokiGuard/vulnctl/releases/tag/v0.1.0

{vulnctl-0.2.0 → vulnctl-0.2.2}/CLAUDE.md

@@ -38,6 +38,7 @@ All four (pytest, ruff check, ruff format, mypy) must pass before any commit.
 ```
 src/vulnctl/
 ├── cli.py               # Typer app wiring + cache commands; thin — no business logic here
+├── cli_help.py          # root --help extras: generated flag summary + examples panels
 ├── commands.py          # enrich/explain command signatures; dispatch only
 ├── models.py            # Pydantic: Finding, Enrichment, Verdict, DecisionPath
 ├── ingest/              # cve_list.py, cyclonedx.py, spdx.py, grype.py, trivy.py

{vulnctl-0.2.0 → vulnctl-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vulnctl
-Version: 0.2.0
+Version: 0.2.2
 Summary: CLI-first vulnerability prioritization: auditable SSVC verdicts from fused threat intelligence
 Project-URL: Homepage, https://github.com/NokiGuard/vulnctl
 Author: Brian Truong

{vulnctl-0.2.0 → vulnctl-0.2.2}/docs/cli.md

@@ -1,7 +1,11 @@
 # vulnctl CLI reference
 
-Every command, argument, and option. `vulnctl --help` (and `--help` on any
-subcommand) prints the same information from the installed version.
+Every command, argument, and option. `vulnctl --help` prints the same thing
+from the installed version — an **Options by command** panel covering every
+command's flags, plus worked **Examples** — and `--help` on a subcommand
+prints that one command in full, including defaults and value ranges. The
+root summary is generated from the registered parameters, so it cannot drift
+from the real signatures.
 
 ```
 vulnctl [OPTIONS] COMMAND [ARGS]...

{vulnctl-0.2.0 → vulnctl-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vulnctl"
-version = "0.2.0"
+version = "0.2.2"
 description = "CLI-first vulnerability prioritization: auditable SSVC verdicts from fused threat intelligence"
 readme = "README.md"
 license = "Apache-2.0"

{vulnctl-0.2.0 → vulnctl-0.2.2}/src/vulnctl/cli.py

@@ -11,10 +11,12 @@ from rich.table import Table
 
 from vulnctl import commands
 from vulnctl.cache import Cache
+from vulnctl.cli_help import HelpfulGroup
 from vulnctl.commands import console
 
 app = typer.Typer(
     name="vulnctl",
+    cls=HelpfulGroup,  # root --help also lists every command's flags + examples
     help="Auditable, SSVC-based vulnerability prioritization.",
     no_args_is_help=True,
 )

vulnctl-0.2.2/src/vulnctl/cli_help.py

@@ -0,0 +1,191 @@
+"""Extra panels for the root ``vulnctl --help``.
+
+Typer's root help lists the commands but none of their flags, so a first-time
+user has to run ``--help`` once per command before they know what the tool can
+do. :class:`HelpfulGroup` appends two panels to the root help only: every
+command's parameters — walked from the registered Click objects, so the
+summary cannot drift from the real signatures — and worked examples of the
+common workflows.
+
+Per-command ``--help`` is untouched; it remains the place for defaults,
+required-ness, and env vars.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+from rich import box
+from rich.console import Console, Group, RenderableType
+from rich.padding import Padding
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+from typer.core import TyperGroup
+
+# Mirror Typer's help palette (typer.rich_utils) so the extra panels read as
+# part of the same page rather than as something bolted on.
+_STYLE_OPTION = "bold cyan"
+_STYLE_SWITCH = "bold green"
+_STYLE_TYPES = "bold yellow"
+_STYLE_BORDER = "dim"
+
+# One example per workflow the tool is built around: ad-hoc IDs, SBOM triage,
+# CI gating, filtering, and single-finding forensics.
+_EXAMPLES: tuple[tuple[str, str], ...] = (
+    (
+        "Rank two CVEs with no network, showing the path behind each verdict",
+        "vulnctl enrich CVE-2021-44228 CVE-2019-0708 --offline --show-path",
+    ),
+    (
+        "Rank an SBOM against your org context, as JSON for jq",
+        "vulnctl enrich --sbom app.cdx.json --context context.yaml -f json",
+    ),
+    (
+        "Gate CI on a Grype scan: exit 2 if anything lands on Attend or worse",
+        "grype my-image:latest -o json | vulnctl enrich --grype - --fail-on attend",
+    ),
+    (
+        "Triage the top of the pile: KEV-listed findings only",
+        "vulnctl enrich --sbom app.cdx.json --only-kev --limit 10",
+    ),
+    (
+        "Ask why one finding got its verdict, and what would change it",
+        "vulnctl explain CVE-2021-44228",
+    ),
+)
+
+
+def _metavar(param: Any, ctx: Any) -> str:
+    """What a parameter takes, spelled the way Typer's own help spells it.
+
+    Delegates to Click rather than deriving it, so the appended panel agrees
+    with the per-command panels on whatever version is installed — Typer 0.26
+    renders ``PATH``, 0.27 renders ``<path>``. Click gained the ``ctx``
+    argument in 8.2; older versions take none.
+    """
+    try:
+        return str(param.make_metavar(ctx=ctx))
+    except TypeError:
+        return str(param.make_metavar())
+
+
+def _visible_params(cmd: Any, kind: str) -> list[Any]:
+    return [
+        param
+        for param in cmd.params
+        if param.param_type_name == kind and not getattr(param, "hidden", False)
+    ]
+
+
+def _usage(path: str, cmd: Any, ctx: Any) -> str:
+    """The one-line invocation shape, e.g. ``vulnctl enrich [OPTIONS] [VULN_ID...]``."""
+    parts = [path]
+    if _visible_params(cmd, "option"):
+        parts.append("[OPTIONS]")
+    parts.extend(_metavar(param, ctx) for param in _visible_params(cmd, "argument"))
+    return " ".join(parts)
+
+
+def _param_rows(cmd: Any, ctx: Any) -> Iterator[tuple[Text, Text, str]]:
+    """Yield ``(name, value hint, help)`` for one command's arguments and options."""
+    for param in _visible_params(cmd, "argument"):
+        # No type column: an argument's metavar already names what it takes.
+        yield (
+            Text(f"  {_metavar(param, ctx)}", style=_STYLE_OPTION),
+            Text(""),
+            str(getattr(param, "help", "") or ""),
+        )
+    for param in _visible_params(cmd, "option"):
+        switch = bool(getattr(param, "is_flag", False))
+        hint = "" if switch else _metavar(param, ctx)
+        yield (
+            Text("  " + " ".join(param.opts), style=_STYLE_SWITCH if switch else _STYLE_OPTION),
+            Text(hint, style=_STYLE_TYPES),
+            str(getattr(param, "help", "") or ""),
+        )
+
+
+def _leaf_commands(group: Any, prefix: str) -> Iterator[tuple[str, str, Any]]:
+    """Walk the command tree depth-first, yielding ``(label, invocation, command)``.
+
+    ``label`` is the command as the user types it after the program name
+    (``enrich``, ``cache purge``); ``invocation`` includes the program name.
+    Subgroups recurse so nested commands are listed rather than hidden behind
+    another ``--help``.
+    """
+    for name, cmd in group.commands.items():
+        if getattr(cmd, "hidden", False):
+            continue
+        label = f"{prefix} {name}".strip()
+        subcommands = getattr(cmd, "commands", None)
+        if subcommands:
+            yield from _leaf_commands(cmd, label)
+        else:
+            yield label, name, cmd
+
+
+def _flags_panel(group: Any, prog: str, ctx: Any) -> Panel:
+    """Every command's parameters, generated from the registered Click objects."""
+    table = Table(box=None, show_header=False, pad_edge=False, padding=(0, 1))
+    table.add_column(no_wrap=True)  # command / flag
+    table.add_column(overflow="fold")  # what it takes
+    table.add_column()  # help
+
+    for index, (label, _name, cmd) in enumerate(_leaf_commands(group, "")):
+        if index:
+            table.add_row("", "", "")
+        table.add_row(
+            Text(label, style="bold"),
+            "",
+            Text(_usage(f"{prog} {label}", cmd, ctx), style="dim"),
+        )
+        for name, hint, help_text in _param_rows(cmd, ctx):
+            table.add_row(name, hint, help_text)
+
+    return Panel(
+        table,
+        title="Options by command",
+        title_align="left",
+        border_style=_STYLE_BORDER,
+        box=box.ROUNDED,
+    )
+
+
+def _examples_panel() -> Panel:
+    """Worked invocations, one per supported workflow."""
+    lines: list[RenderableType] = []
+    for comment, command in _EXAMPLES:
+        if lines:
+            lines.append(Text(""))
+        lines.append(Text(f"# {comment}", style="dim"))
+        lines.append(Text(command, style=_STYLE_OPTION))
+    return Panel(
+        Group(*lines),
+        title="Examples",
+        title_align="left",
+        border_style=_STYLE_BORDER,
+        box=box.ROUNDED,
+    )
+
+
+class HelpfulGroup(TyperGroup):
+    """Root group whose ``--help`` also lists every command's flags and examples."""
+
+    def format_help(self, ctx: Any, formatter: Any) -> None:
+        super().format_help(ctx, formatter)
+        prog = str(ctx.find_root().info_name or "vulnctl")
+        console = Console()
+        console.print(_flags_panel(self, prog, ctx))
+        console.print(_examples_panel())
+        console.print(
+            Padding(
+                Text.assemble(
+                    ("Run ", "dim"),
+                    (f"{prog} COMMAND --help", "bold"),
+                    (" for one command in full: defaults, value ranges, exit codes.", "dim"),
+                ),
+                (0, 1),
+            )
+        )

{vulnctl-0.2.0 → vulnctl-0.2.2}/tests/test_cli.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import re
 from importlib.metadata import version as pkg_version
 from pathlib import Path
 
@@ -12,6 +13,7 @@ from typer.testing import CliRunner
 
 from vulnctl.cache import Cache
 from vulnctl.cli import app
+from vulnctl.cli_help import _EXAMPLES
 
 runner = CliRunner()
 
@@ -37,6 +39,73 @@ def test_no_args_shows_help() -> None:
     assert "Usage" in result.output
 
 
+def _subcommand_flags() -> set[str]:
+    """Every option flag registered under a subcommand, walked independently.
+
+    Deliberately does not reuse ``cli_help``'s own walk — the point is to catch
+    a flag the generated root summary would miss. The root's own options are
+    excluded: they render in Typer's help panel, which forces colour under
+    GITHUB_ACTIONS (see ``test_completion_options_present``).
+    """
+    flags: set[str] = set()
+    stack = list(get_command(app).commands.values())
+    while stack:
+        cmd = stack.pop()
+        stack.extend(getattr(cmd, "commands", {}).values())
+        flags.update(
+            opt
+            for param in cmd.params
+            if param.param_type_name == "option"  # arguments carry a name, not a flag
+            for opt in param.opts
+        )
+    return flags
+
+
+def test_root_help_lists_every_subcommand_flag() -> None:
+    # `vulnctl --help` on its own has to be usable: Typer's root help names the
+    # commands but none of their flags, so cli_help appends a generated summary.
+    result = runner.invoke(app, ["--help"])
+    assert result.exit_code == 0
+    assert sorted(flag for flag in _subcommand_flags() if flag not in result.output) == []
+
+
+def test_root_help_shows_usage_shapes_and_examples() -> None:
+    result = runner.invoke(app, ["--help"])
+    assert "vulnctl enrich [OPTIONS] [VULN_ID...]" in result.output
+    assert "vulnctl explain [OPTIONS] VULN_ID" in result.output
+    assert "vulnctl cache purge [OPTIONS]" in result.output
+    assert "vulnctl enrich CVE-2021-44228 CVE-2019-0708 --offline --show-path" in result.output
+    assert "vulnctl COMMAND --help" in result.output  # pointer to per-command detail
+
+
+def test_root_help_type_column_matches_per_command_help() -> None:
+    # The type column is Click's own metavar, not a hand-derived one, so it
+    # tracks whatever spelling the installed Typer uses (0.26 prints `PATH`,
+    # 0.27 prints `<path>`) instead of disagreeing with the panels above it.
+    def plain(text: str) -> str:
+        return re.sub(r"\x1b\[[0-9;]*m", "", text)  # CI forces colour on Typer's console
+
+    def option_row(output: str) -> str:
+        # The flag also occurs inside other params' help text; take the row it
+        # heads, panel border and indent stripped.
+        rows = [ln.lstrip("│ ") for ln in plain(output).splitlines()]
+        (row,) = [ln for ln in rows if ln.startswith("--sbom")]
+        return row
+
+    metavar = option_row(runner.invoke(app, ["enrich", "--help"]).output).split()[1]
+    assert metavar.strip("<>").lower() == "path"
+    assert metavar in option_row(runner.invoke(app, ["--help"]).output)
+
+
+def test_help_examples_use_real_flags() -> None:
+    """Worked examples rot silently; assert every flag in them still exists."""
+    known = _subcommand_flags()
+    for _comment, command in _EXAMPLES:
+        tail = command.split("vulnctl", 1)[1]  # skip flags belonging to piped-in tools
+        used = {token for token in tail.split() if token.startswith("-") and token != "-"}
+        assert used <= known, f"unknown flag(s) in example: {sorted(used - known)}"
+
+
 def test_enrich_offline_renders_table_from_snapshots() -> None:
     """End-to-end offline run: bundled snapshots only, zero network."""
     result = runner.invoke(app, ["enrich", "--offline", "cve-2021-44228", "CVE-2019-0708"])

{vulnctl-0.2.0 → vulnctl-0.2.2}/uv.lock

@@ -1066,7 +1066,7 @@ wheels = [
 
 [[package]]
 name = "vulnctl"
-version = "0.2.0"
+version = "0.2.2"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },