feat: add kgb (Known Good Binaries) command group

[sbneto]

TL;DR

• New kgb (Known Good Binaries) command group: create / get / delete (no update), wrapping the SDK's known_good_create/get/delete.
• A known_good(...) formatter in TextOutput and JSONOutput.
• Wired into the top-level CLI; lifecycle tests recorded against the live e2e stack.

Context

Adds the CLI surface for the Known Good Binaries feature on top of the already-merged polyswarm-api SDK methods. A known-good entry is keyed on its sha256 — create records a feed (--source) as having flagged the hash; get and delete take the same sha256. Authorization is enforced server-side (internal-only); the CLI does not gate it.

Changes

• src/polyswarm/client/kgb.py — new kgb group + create/get/delete. create takes sha256 + required --source, optional --sha1/--md5/--filename/--mimetype/--metadata (JSON). Community flows from the global -c.
• src/polyswarm/client/polyswarm.py — register the group.
• formatters/base.py + text.py + json.py — known_good(...) renderer (text guards the optional fields so the minimal delete response renders cleanly).
• specs/02-commands.md, specs/03-formatters.md — catalogue + formatter-interface updates.

Tests

• tests/kgb_test.py — CliRunner lifecycle (create → get → delete, text + json, plus get-after-delete 404), recorded against the live e2e stack via VCR; distinct sha256 per test (first-run-safe). Full suite green (replay + live).

[claude]

Review — PR #248 (kgb Known Good Binaries)

Largely clean against the documented conventions: targets develop ✓, no version bump ✓, singular *_create/get/delete rendered directly (not iterated) per specs/05-sdk-contract.md ✓, formatter added to all three of base.py/json.py/text.py in sync per AGENTS.md step 3 ✓, and specs/02-commands.md + 03-formatters.md updated in the same PR ✓.

A few items worth action, none blocking:

1. (Correctness — confirm) Delete-path text rendering depends on SDK attribute semantics.
From the cassettes, the delete result is {deleted, sha256} only — no sources/artifact_instance_id/created keys. But TextOutput.known_good reads those as attributes (if result.sources:, if result.artifact_instance_id:, if result.created:). This renders cleanly only if the SDK KnownGood resource yields None for absent keys rather than raising AttributeError. The deleted field is read via result.json.get(...) — not as an attribute — which is a tell that the typed attributes are the expected fields and deleted is not one of them. If test_kgb_create_get_delete_text genuinely passes with exit 0 (its delete branch asserts it), the SDK returns None and this is fine — just flagging the one thing the rendering quietly relies on. Reading all four via result.json.get(...) would be more robust and consistent with the deleted line.

2. (Minor) --metadata accepts any valid JSON, not just an object.
json.loads(metadata) only rejects invalid JSON; --metadata '"x"' or --metadata 5 parse fine and get forwarded, despite the help text and the BadParameter message both saying "JSON object". An isinstance(metadata, dict) check would make the message truthful.

3. (Test coverage) The only CLI-owned logic — the --metadata parse + BadParameter branch — is untested.
All three tests are VCR happy / server-error paths; none exercises the bad---metadata branch (the one piece of logic that lives in the CLI rather than the SDK). An SDK-mocked unit test (mock.patch('polyswarm_api.api.PolyswarmAPI.known_good_create'), per specs/04-testing.md) asserting a non-zero exit on malformed --metadata would cover it. The optional --sha1/--md5/--filename/--mimetype/--metadata flags also are not passed by any test, so their wiring into the SDK call is unverified.

Items 2–3 are small; item 1 is just a confirmation if the suite is green.

[claude]

Review — PR #248 (kgb command group)

Clean against gitflow (base develop, no version bump) and the formatter-sync rule (base/json/text all gain known_good, both specs updated). A few items:

1. Missing test for the only non-passthrough logic (--metadata parsing) — test coverage

create is the one command with real CLI logic beyond a passthrough: the json.loads(metadata) block and its click.BadParameter error path (client/kgb.py). Neither is exercised — the happy path (a valid JSON object parsed and forwarded as structured data) and the error path (invalid JSON to BadParameter, exit 2). The cassette tests never pass --metadata. Per specs/04-testing.md this needs no cassette: an SDK-boundary mock (mock.patch(polyswarm_api.api.PolyswarmAPI.known_good_create)) asserting the forwarded metadata kwarg plus the exit-2 case is the right tool. Worth adding before merge.

2. SDK version pin — confirm the floor (spec 05 invariant)

The PR relies on known_good_create/get/delete and the body says the SDK methods are already-merged. The pin stays polyswarm_api>=4.0.0,<5.0.0 and there is no ## Requires section. Per specs/05-sdk-contract.md: Floor it at the lowest SDK version that exposes every method/behaviour the CLI relies on. Please confirm known_good_* actually ships in 4.0.0; if it landed in a later 4.x, raise the floor — otherwise a pinned-low install will AttributeError at runtime. If the surface is only on the SDK develop branch and not yet released, link it under ## Requires.

3. Minor: PR body says --source, code uses a positional SOURCE

The PR description (create takes sha256 + required --source) does not match the implementation (@click.argument(source, required=True)) or the tests (kgb create SHA nsrl). Code and tests are self-consistent; just fix the description (or switch to the documented flag).

Nothing blocking on correctness — the minimal delete-response render and the 404-to-exit-1 path are both covered by replay, so the guarded optional-field access in text.known_good is exercised.

[claude]

Review — PR #248 (kgb / Known Good Binaries)

Checked against AGENTS.md, specs/02-commands.md, specs/03-formatters.md, specs/04-testing.md, specs/05-sdk-contract.md. Well-scoped and follows the documented conventions: new top-level group wired into polyswarm_cli, known_good added to base/text/json in sync, both specs updated in the same PR, base is develop, no version bump. Cassettes carry polyswarm_api/4.0.0, so the known_good_* methods exist at the pin floor (>=4.0.0) — no ## Requires/pin bump needed.

One actionable item — the --metadata branch is untested (specs/04 §"What to test", item 1). The JSON parse + click.BadParameter re-raise in create (kgb.py) is the only non-trivial client-side logic in the PR, and none of the three tests pass --metadata — so neither the happy path (valid JSON parsed and forwarded as structured data) nor the bad-JSON error path is exercised. This is a natural SDK-boundary mock test (mock.patch('polyswarm_api.api.PolyswarmAPI.known_good_create'), assert the parsed metadata= kwarg; plus a case asserting a usage error on --metadata 'not json') — no cassette required, per the style-1 guidance in specs/04.

Non-blocking notes:

• get/delete lack the docstring that create has — cosmetic.
• Delete is only rendered in text format; JSON known_good on the minimal {sha256, deleted} shape is uncovered. Low value given the renderer just dumps result.json.

Nothing else needs action.