mcpgawk 0.1.7__tar.gz → 0.1.8__tar.gz

{mcpgawk-0.1.7 → mcpgawk-0.1.8}/.github/workflows/publish-pypi.yml

@@ -75,4 +75,16 @@ jobs:
           TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
         run: |
           python -m pip install twine
-          twine upload dist/*
+          # --skip-existing + retry: on 2026-07-23 (0.1.7) upload.pypi.org connect-timeouts made
+          # twine exit 1 AFTER both artefacts had already landed — a RED run over a SUCCESSFUL
+          # publish, and a plain re-run would then fail with "file already exists". --skip-existing
+          # makes a retry idempotent (already-uploaded files are skipped, not errored); the loop
+          # rides out a transient network blip instead of failing the whole release on it.
+          for attempt in 1 2 3; do
+            if twine upload --non-interactive --skip-existing dist/*; then
+              echo "upload ok (attempt $attempt)"; exit 0
+            fi
+            echo "::warning::twine upload attempt $attempt failed (likely a transient upload.pypi.org timeout) — retrying"
+            sleep 20
+          done
+          echo "::error::twine upload failed after 3 attempts"; exit 1

{mcpgawk-0.1.7 → mcpgawk-0.1.8}/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 All notable changes to mcpgawk. Format: [Keep a Changelog](https://keepachangelog.com/); versioning: [SemVer](https://semver.org/).
 
+## [0.1.8] — 2026-07-26
+
+One command. The paid capabilities are now subcommands of `mcpgawk`, not a separate binary.
+
+### Changed
+
+- **`mcpgawk --help` now lists the gawk Platform capabilities** (`verify`, `enforce`, `monitor`,
+  `build`) so you can see what a subscription adds without installing anything. Running one on a
+  free install prints a single line explaining what it is and where to get it, and exits 3 — no
+  Python traceback, and never a silent success.
+- **The free scanner is unchanged and stays free.** `mcpgawk scan` needs no licence, no account and
+  no network beyond the servers you point it at. Nothing in this release adds a paid dependency:
+  the paid engine is not in this package and the import that reaches for it is optional.
+
+### Why one command
+
+The paid tier used to install a second executable named `gawk`. That name belongs to **GNU AWK** —
+it owns `/usr/bin/gawk` across the Debian family and supplies `/usr/bin/awk` there through the
+alternatives system, so shipping our own `gawk` could break a machine's `awk`. Debian Policy §10.1
+requires a rename when two packages claim one path, and Homebrew's `gawk` formula *is* GNU awk.
+Projects that hit this before us all retreated: ast-grep deprecated its colliding `sg`, `fd` ships
+as `fdfind`, `bat` as `batcat`.
+
+One command plus a licence unlock is also the ordinary shape for this kind of tool — Semgrep, Snyk,
+GitLab and Terraform all do it. "gawk" remains the brand (gawk.dev); `mcpgawk` is the command.
+
+## [0.1.7] — 2026-07-23
+
+Engine sync release. Dispatch-aware drift, credential-safe fleet URLs, sturdier baselines.
+
+### Added
+
+- `fingerprint.py` — one shared surface-fingerprint used by both drift and the fleet view, so the
+  two can no longer disagree about whether a server changed.
+
+### Changed
+
+- **Fleet URLs are redacted for display.** A secret-named query parameter (`apiKey=`, `token=`) or
+  userinfo in a server URL no longer renders in the fleet listing. The real URL is untouched for
+  connecting — only what gets shown is masked.
+- Drift and history handling hardened around dispatch-style servers and baseline recording.
+
 ## [0.1.6] — 2026-07-22
 
 The drift release. Everything here is about one question a fresh look at your machine can never

{mcpgawk-0.1.7 → mcpgawk-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpgawk
-Version: 0.1.7
+Version: 0.1.8
 Summary: A local-first CLI that measures what an MCP server costs and what it can do. Nothing leaves your machine.
 Project-URL: Homepage, https://mcp.gawk.dev
 Project-URL: Documentation, https://mcp.gawk.dev

{mcpgawk-0.1.7 → mcpgawk-0.1.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mcpgawk"
-version = "0.1.7"
+version = "0.1.8"
 description = "A local-first CLI that measures what an MCP server costs and what it can do. Nothing leaves your machine."
 readme = "README.md"
 requires-python = ">=3.10"

mcpgawk-0.1.8/src/mcpgawk/baseline.py

@@ -0,0 +1,155 @@
+"""The one answer to "what did this server look like when I trusted it".
+
+The product kept three memories of that: `history.py` (scan), `packages/verify/src/pins.ts`
+(verify) and `monitor/store.py` (the daemon). You could approve a server in one and still be told
+it had drifted by another, which is why no flow felt joined up — there wasn't one spine, there were
+three.
+
+This is the spine. It is deliberately a NARROW VIEW over the store that already exists
+(`history.json`) rather than a fourth file: a new store would have to be migrated into, kept in
+sync, and would itself become another memory to disagree with. The canonical record was already
+there — `servers[key]["approved"]` — it simply had no name and no reader outside scan.
+
+What makes one shared baseline possible at all is that the fingerprint is now identical everywhere:
+`fingerprint.surface_pin` is computed by scan (through `measure`), by monitor, and — since the
+schema-2.0 change — byte-for-byte by verify in TypeScript. Before that, sharing a baseline would
+have meant sharing a number the three pillars each interpreted differently.
+
+Shape (stable, and the contract other runtimes read through `mcpgawk baseline --json`):
+
+    {"schema": "gawk.baseline/1",
+     "servers": {"<key>": {"pin": "<16-hex>", "tools": {"<name>": "<hash>"},
+                           "approved_at": "<iso8601>", "aliases": [...]}}}
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from . import history
+
+#: Bumped only when the exported shape changes incompatibly. Readers check it rather than guessing.
+SCHEMA = "gawk.baseline/1"
+
+
+def approved_record(key: str, path: str | None = None) -> dict[str, Any] | None:
+    """The full approved record for one server, or None if nothing has been approved yet."""
+    store = history.load(path or history.default_path())
+    return history.approved(store, key)
+
+
+def approved_pin(key: str, path: str | None = None) -> str | None:
+    """The approved whole-surface pin — the single value every pillar compares against.
+
+    None means "never approved", which is NOT the same as "approved as empty": a caller that
+    conflates them reports drift against a baseline that does not exist, on a server the operator
+    has never looked at. Trust-on-first-use is scan's job (see history.record); this only reports.
+    """
+    rec = approved_record(key, path)
+    return (rec or {}).get("pin")
+
+
+def approved_tools(key: str, path: str | None = None) -> dict[str, str]:
+    """`{tool name: hash}` from the approved record. Empty dict when nothing is approved."""
+    rec = approved_record(key, path) or {}
+    tools = rec.get("tools")
+    return dict(tools) if isinstance(tools, dict) else {}
+
+
+def approved_annotations(key: str, path: str | None = None) -> dict[str, dict[str, Any]]:
+    """`{tool name: annotations}` as they were WHEN APPROVED.
+
+    The distinction that makes this worth having: `enforce` can already derive a policy from the
+    annotations a server declares at connect time — but that is the server's CURRENT claim about
+    itself. A server that quietly flips `readOnlyHint` to true would have the guard relax to match
+    it. Deriving from the approved record instead means the policy reflects the operator's decision,
+    and a server changing its story does not change what it is allowed to do.
+
+    Records store typed keys (`tool.read_file`) because a prompt and a tool may share a name; only
+    tools carry scopes, so only tools come back.
+    """
+    rec = approved_record(key, path) or {}
+    raw = rec.get("annotations")
+    if not isinstance(raw, dict):
+        return {}
+    out: dict[str, dict[str, Any]] = {}
+    for ident, ann in raw.items():
+        if not isinstance(ident, str) or not ident.startswith("tool."):
+            continue
+        if isinstance(ann, dict):
+            out[ident[len("tool."):]] = dict(ann)
+    return out
+
+
+def export(path: str | None = None) -> dict[str, Any]:
+    """The whole approved baseline, in the shape other runtimes read.
+
+    Only APPROVED state crosses this boundary — never the sighting history. What a server looked
+    like last Tuesday is scan's business; what the operator has agreed to trust is everyone's.
+    """
+    store = history.load(path or history.default_path())
+    out: dict[str, Any] = {}
+    for key, entry in (store.get("servers") or {}).items():
+        if not isinstance(entry, dict):
+            continue
+        rec = entry.get("approved")
+        if not isinstance(rec, dict):
+            continue  # seen but never approved — deliberately absent, not exported as empty
+        out[key] = {
+            "pin": rec.get("pin"),
+            "tools": dict(rec.get("tools") or {}),
+            "approved_at": rec.get("measured_at"),
+            "aliases": list(entry.get("aliases") or []),
+            "annotations": {
+                ident[len("tool."):]: dict(ann)
+                for ident, ann in (rec.get("annotations") or {}).items()
+                if isinstance(ident, str) and ident.startswith("tool.") and isinstance(ann, dict)
+            },
+        }
+    return {"schema": SCHEMA, "servers": out}
+
+
+def publish(key: str, *, pin: str, tools: dict[str, str], approved_at: str,
+            alias: str | None = None, path: str | None = None) -> None:
+    """Write an approval INTO the spine from another pillar.
+
+    The read path (`export`) alone makes the spine a one-way mirror: verify and monitor could see
+    what scan approved, but an operator approving a drift in `gawk-monitor approve` left scan still
+    reporting it. A shared baseline that only one pillar can move is three memories again, with
+    extra steps.
+
+    Deliberately narrow — pin, per-tool hashes, when. A monitor Snapshot carries more (grade,
+    signals, verification state) and that stays in monitor's own store: the spine is the answer to
+    "what surface did we agree to trust", not a general-purpose replica.
+    """
+    p = path or history.default_path()
+    with history.locked(p):
+        store = history.load(p)
+        entry = store.setdefault("servers", {}).setdefault(key, {})
+        entry["approved"] = {
+            **(entry.get("approved") or {}),
+            "measured_at": approved_at,
+            "pin": pin,
+            "tools": dict(tools),
+        }
+        if alias:
+            entry["aliases"] = sorted(set(entry.get("aliases", [])) | {alias})
+        history.save(store, p)
+
+
+def resolve(name: str, path: str | None = None) -> str | None:
+    """Map a name the user typed to the key the baseline is stored under.
+
+    A server's identity key and the name it is configured under in an AI tool are not the same
+    string, and the same server is routinely configured under different names in different tools.
+    Without this, `approve slack` in one pillar and a lookup of `slack-mcp` in another miss each
+    other and the shared baseline silently does nothing.
+    """
+    store = history.load(path or history.default_path())
+    servers = store.get("servers") or {}
+    if name in servers:
+        return name
+    for key, entry in servers.items():
+        if isinstance(entry, dict) and name in (entry.get("aliases") or []):
+            return key
+    return None

{mcpgawk-0.1.7 → mcpgawk-0.1.8}/src/mcpgawk/cli.py

@@ -127,7 +127,16 @@ def build_parser() -> argparse.ArgumentParser:
 
     Whether tracking defaults on is a product invariant (ADR-0012 N2), not a detail — asserting it
     needs a parser you can build without running a scan."""
-    p = argparse.ArgumentParser(prog="mcpgawk", description="gawk at an MCP server before you trust it")
+    p = argparse.ArgumentParser(
+        prog="mcpgawk",
+        description="gawk at an MCP server before you trust it",
+        epilog=(
+            "gawk Platform capabilities (£29/month — https://mcp.gawk.dev/pricing.html):\n"
+            + "".join(f"  {c:<9} {d}\n" for c, d in PLATFORM_CAPABILITIES.items())
+            + "Run `mcpgawk <capability>` once subscribed; scan stays free and open-source."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
     sub = p.add_subparsers(dest="cmd", required=True)
     s = sub.add_parser("scan", help="measure MCP server(s) locally")
     s.add_argument("config", nargs="?", help="path to an mcp.json config")
@@ -175,6 +184,18 @@ def build_parser() -> argparse.ArgumentParser:
     # The other half of a sticky alarm. Drift now re-reports on every scan until acknowledged
     # (ADR-0012 N1), so there MUST be an obvious way to acknowledge it — an alarm a user cannot
     # clear is one they will silence with --no-track, which costs them the baseline entirely.
+    b = sub.add_parser(
+        "baseline",
+        help="print the approved baseline — what you have agreed to trust, per server",
+        description=(
+            "The shared baseline every pillar compares against. `verify` and `monitor` read this "
+            "so that approving a server once is approving it everywhere, instead of each keeping "
+            "its own memory and contradicting the others."
+        ),
+    )
+    b.add_argument("--json", action="store_true", help="machine-readable (the cross-runtime shape)")
+    b.add_argument("--server", metavar="NAME", help="one server (name or alias) instead of all")
+
     a = sub.add_parser("approve",
                        help="accept a server's current tools as the trusted baseline (clears DRIFT)")
     a.add_argument("server", nargs="?",
@@ -185,6 +206,48 @@ def build_parser() -> argparse.ArgumentParser:
     return p
 
 
+def _baseline(args) -> int:
+    """Print what the operator has agreed to trust — the spine other pillars read.
+
+    Only approved state is exported. A sighting is not a baseline: printing the last thing seen
+    would hand verify and monitor the poisoned surface as though it were trusted, which is the
+    exact failure ADR-0012 exists to prevent.
+    """
+    from . import baseline as _baseline_mod
+
+    data = _baseline_mod.export(getattr(args, "history", None))
+    servers = data["servers"]
+
+    if args.server:
+        key = _baseline_mod.resolve(args.server, getattr(args, "history", None))
+        if key is None or key not in servers:
+            print(f"mcpgawk: nothing approved for '{args.server}'. "
+                  f"Run `mcpgawk scan`, then `mcpgawk approve {args.server}`.", file=sys.stderr)
+            return 2
+        servers = {key: servers[key]}
+        data = {**data, "servers": servers}
+
+    if args.json:
+        print(json.dumps(data, indent=2, sort_keys=True))
+        return 0
+
+    if not servers:
+        print("Nothing approved yet. Run `mcpgawk scan`, then `mcpgawk approve <server>` to set "
+              "the baseline that verify and monitor will compare against.")
+        return 0
+
+    print(f"Approved baseline — {len(servers)} server(s). "
+          f"verify and monitor compare against exactly this.\n")
+    for key in sorted(servers):
+        rec = servers[key]
+        alias = f" ({', '.join(rec['aliases'])})" if rec.get("aliases") else ""
+        print(f"  {key}{alias}")
+        print(f"    pin        {rec.get('pin') or '—'}")
+        print(f"    tools      {len(rec.get('tools') or {})}")
+        print(f"    approved   {rec.get('approved_at') or '—'}")
+    return 0
+
+
 def _approve(args) -> int:
     """`mcpgawk approve` — move the trusted baseline forward, deliberately."""
     path = history.default_path()
@@ -222,10 +285,70 @@ def _approve(args) -> int:
     return 0
 
 
+# The paid capabilities, reachable as `mcpgawk <capability>` when gawk Platform is installed.
+#
+# ONE BINARY, on purpose (2026-07-26). Two reasons, both load-bearing:
+#   1. `gawk` cannot be an executable name. It is GNU AWK — it owns /usr/bin/gawk across the
+#      Debian family and supplies /usr/bin/awk there through the alternatives system, so our own
+#      `gawk` on PATH risks breaking a machine's `awk`. Debian Policy §10.1 requires one of two
+#      colliding programs to be renamed; Homebrew's `gawk` formula is GNU awk, so the name is
+#      simply unavailable. Everyone who tried this retreated: ast-grep deprecated `sg`, fd ships
+#      as `fdfind`, bat as `batcat`.
+#   2. A second binary for the paid tier is against convention anyway. Semgrep, Snyk, GitLab and
+#      Terraform all keep ONE command and unlock with a licence/login. A separate binary is only
+#      conventional when the paid thing is a different artefact (Docker Desktop). Ours isn't — it
+#      is more analysis on the same inputs.
+#
+# They are listed in `--help` even when unavailable: a free user should be able to SEE what the
+# subscription adds without installing anything, and get one honest line if they try it.
+PLATFORM_CAPABILITIES = {
+    "verify": "run a server in a no-egress sandbox and reproduce misbehaviour",
+    "enforce": "guard a live server, call by call",
+    "monitor": "watch a server for drift after you approved it",
+    "build": "generate a server from an OpenAPI spec (in development)",
+}
+
+_PLATFORM_UNAVAILABLE = (
+    "mcpgawk {cap}: {desc}.\n"
+    "This is a gawk Platform capability and it isn't installed in this environment.\n"
+    "  £29/month, 7-day free trial — https://mcp.gawk.dev/pricing.html\n"
+    "  Already subscribed? Your purchase email has the install instructions.\n"
+    "The free scanner (`mcpgawk scan`) stays free and open-source either way."
+)
+
+
+def _run_platform_capability(capability: str, rest: list[str]) -> int:
+    """Delegate to gawk Platform if it is installed, else say so honestly and exit 3.
+
+    The import is deliberately OPTIONAL and local: the free scanner is published to PyPI on its
+    own and must never depend on, or ship, the paid engine. A paid install supersedes the free
+    distribution in place (same distribution name), which is the GitLab CE→EE shape.
+    """
+    try:
+        from gawk_platform.cli import run_pillar
+    except ImportError:
+        print(
+            _PLATFORM_UNAVAILABLE.format(capability=capability, cap=capability,
+                                         desc=PLATFORM_CAPABILITIES[capability]),
+            file=sys.stderr,
+        )
+        return 3  # the same "not licensed / not available" code every paid entry point returns
+    return run_pillar(capability, rest)
+
+
 def main(argv: list[str] | None = None) -> int:
+    # Intercept the paid capabilities BEFORE argparse: their arguments are the pillar's own, and
+    # the free parser must not try to validate them.
+    raw = list(sys.argv[1:] if argv is None else argv)
+    if raw and raw[0] in PLATFORM_CAPABILITIES:
+        return _run_platform_capability(raw[0], raw[1:])
+
     p = build_parser()
     args = p.parse_args(argv)
 
+    if args.cmd == "baseline":
+        return _baseline(args)
+
     if args.cmd == "approve":
         return _approve(args)
 

mcpgawk-0.1.8/tests/test_baseline_spine.py

@@ -0,0 +1,108 @@
+"""One baseline, read by every pillar.
+
+The product kept three memories of "what did this server look like when I trusted it":
+history.py (scan), packages/verify/src/pins.ts (verify) and monitor/store.py (the daemon). You
+could approve a server in one and still be told it had drifted by another — which is why no flow
+felt joined up. This is the shared view they all read.
+
+Deliberately a NARROW VIEW over history.json rather than a fourth file: a new store would need
+migrating into, keeping in sync, and would itself become another memory to disagree with.
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from mcpgawk import baseline, history
+
+REC = {
+    "measured_at": "2026-07-27T10:00:00Z",
+    "pin": "abc123def4567890",
+    "tools": {"read_file": "9c98141c4c35", "write_file": "aac5a0de16f1"},
+}
+
+
+@pytest.fixture
+def store(tmp_path: Path) -> str:
+    return str(tmp_path / "history.json")
+
+
+def test_nothing_is_approved_until_someone_approves_it(store):
+    history.record("srv", REC, path=store)
+    # First sighting is trust-on-first-use in scan, so this IS approved; a second, different
+    # sighting must NOT move it.
+    history.record("srv", {**REC, "pin": "ffffffffffffffff"}, path=store)
+    assert baseline.approved_pin("srv", store) == REC["pin"], "a sighting is not an approval"
+
+
+def test_approve_moves_the_shared_baseline(store):
+    history.record("srv", REC, path=store)
+    moved = {**REC, "pin": "ffffffffffffffff", "tools": {"read_file": "111111111111"}}
+    history.record("srv", moved, path=store)
+    history.approve("srv", path=store)
+    assert baseline.approved_pin("srv", store) == "ffffffffffffffff"
+    assert baseline.approved_tools("srv", store) == {"read_file": "111111111111"}
+
+
+def test_a_name_the_user_typed_resolves_to_the_key_it_is_stored_under(store):
+    """Identity key and configured name are different strings, and the same server is routinely
+    configured under different names in different tools. Without this the shared baseline silently
+    does nothing for half the fleet."""
+    history.record("mcp:abc123", REC, path=store, alias="slack")
+    assert baseline.resolve("slack", store) == "mcp:abc123"
+    assert baseline.resolve("mcp:abc123", store) == "mcp:abc123"
+    assert baseline.resolve("never-heard-of-it", store) is None
+
+
+def test_export_carries_only_approved_state(store):
+    """A sighting must never cross the boundary: handing verify the last thing SEEN would give it
+    the poisoned surface as though it were trusted."""
+    history.record("approved-one", REC, path=store)
+    history.approve("approved-one", path=store)
+
+    raw = json.loads(Path(store).read_text())
+    raw["servers"]["seen-only"] = {"seen": [REC]}          # sighted, never approved
+    Path(store).write_text(json.dumps(raw))
+
+    data = baseline.export(store)
+    assert data["schema"] == baseline.SCHEMA
+    assert "approved-one" in data["servers"]
+    assert "seen-only" not in data["servers"]
+
+
+def test_never_approved_is_none_not_empty(store):
+    """'Never approved' and 'approved as empty' must not collapse: the second reports drift on a
+    server the operator has never looked at."""
+    assert baseline.approved_pin("unknown", store) is None
+    assert baseline.approved_tools("unknown", store) == {}
+
+
+def test_the_cli_emits_the_cross_runtime_shape(store, tmp_path):
+    """`mcpgawk baseline --json` is the contract verify reads. If this shape moves, verify breaks."""
+    history.record("srv", REC, path=store)
+    history.approve("srv", path=store)
+
+    r = subprocess.run(
+        [sys.executable, "-m", "mcpgawk.cli", "baseline", "--json"],
+        capture_output=True, text=True, timeout=60,
+        env={"PATH": "/usr/bin:/bin", "MCPGAWK_HISTORY": store, "HOME": str(tmp_path)},
+    )
+    assert r.returncode == 0, r.stdout + r.stderr
+    data = json.loads(r.stdout)
+    assert data["schema"] == "gawk.baseline/1"
+    assert data["servers"]["srv"]["tools"] == REC["tools"]
+    assert data["servers"]["srv"]["pin"] == REC["pin"]
+
+
+def test_asking_for_an_unapproved_server_fails_loudly(store, tmp_path):
+    r = subprocess.run(
+        [sys.executable, "-m", "mcpgawk.cli", "baseline", "--server", "nope"],
+        capture_output=True, text=True, timeout=60,
+        env={"PATH": "/usr/bin:/bin", "MCPGAWK_HISTORY": store, "HOME": str(tmp_path)},
+    )
+    assert r.returncode == 2
+    assert "nothing approved" in r.stderr.lower()

mcpgawk-0.1.8/tests/test_free_cli_platform_hint.py

@@ -0,0 +1,70 @@
+"""What a FREE install does when someone types a paid capability.
+
+Public-safe by construction: this file must never import gawk_platform, because it is synced into
+the public mcpgawk repo where the paid engine does not exist. It covers the path every free user
+can hit — `mcpgawk verify ...` with nothing but the free scanner installed.
+
+The shape it locks: ONE binary. `gawk` cannot be an executable name (it is GNU AWK, which owns
+/usr/bin/gawk across the Debian family and supplies /usr/bin/awk there via the alternatives
+system), and one-command-plus-licence-unlock is the convention for this product type — Semgrep,
+Snyk, GitLab, Terraform all do it. So the paid capabilities live under `mcpgawk`, and a free user
+must get ONE honest line, never an ImportError traceback and never a silent success.
+"""
+from __future__ import annotations
+
+import builtins
+
+import pytest
+
+from mcpgawk import cli as free_cli
+
+
+@pytest.fixture
+def no_platform(monkeypatch):
+    """Simulate a free-only install even when the paid engine happens to be importable."""
+    real_import = builtins.__import__
+
+    def _import(name, *a, **kw):
+        if name.startswith("gawk_platform"):
+            raise ImportError("No module named 'gawk_platform'")
+        return real_import(name, *a, **kw)
+
+    monkeypatch.setattr(builtins, "__import__", _import)
+
+
+def test_paid_capabilities_are_advertised_in_free_help():
+    """A free user should SEE what the subscription adds without installing anything."""
+    help_text = free_cli.build_parser().format_help()
+    for capability in free_cli.PLATFORM_CAPABILITIES:
+        assert capability in help_text
+    assert "gawk Platform" in help_text
+    assert "pricing" in help_text
+
+
+@pytest.mark.parametrize("capability", ["verify", "enforce", "monitor", "build"])
+def test_paid_capability_on_a_free_install_exits_3_with_one_actionable_line(
+    capability, no_platform, capsys
+):
+    rc = free_cli.main([capability, "whatever.json"])
+
+    assert rc == 3, "the same 'not available/not licensed' code every paid entry point returns"
+    err = capsys.readouterr().err
+    assert "gawk Platform" in err
+    assert "pricing.html" in err
+    assert "free" in err.lower(), "must reassure that the free scanner is unaffected"
+    assert "Traceback" not in err
+
+
+def test_the_hint_never_leaks_a_python_import_error(no_platform, capsys):
+    """An ImportError reaching the user is the failure mode this replaced."""
+    free_cli.main(["verify"])
+    err = capsys.readouterr().err
+    assert "ImportError" not in err
+    assert "gawk_platform" not in err, "internal module names are not a customer-facing detail"
+
+
+def test_free_scan_is_unaffected_by_the_paid_dispatch(no_platform):
+    """The whole point of the free tier: scan needs no licence and no platform."""
+    with pytest.raises(SystemExit) as exc:
+        free_cli.main(["scan", "--help"])
+    assert exc.value.code == 0