feat(package): on-demand package scan commands (FOU-221)

[abhisek]

What

Adds the safedep package scan command family — the CLI surface for SafeDep Cloud's on-demand package scanning (safedep/api#177, PackageScanService).

safedep package scan run   <package-ref>          # submit + wait for verdict
safedep package scan get    <package-ref> | --scan-id ID
safedep package scan list  [--ecosystem/--name/--version]
safedep package scan show   <package-ref> | --scan-id ID

A package is any external software component in a supported ecosystem — OSS libraries, VS Code / OpenVSX extensions, GitHub repositories, and more — hence the deliberately generic package domain noun.

Design

• Identity layer. A target is resolved from the explicit --ecosystem/--name/--version triple (canonical, forward-compatible) or a PURL / GitHub URL (sugar) via dry/api/pb. Ecosystem is mandatory — the backend routes the scan by it — so a resolved ECOSYSTEM_UNSPECIFIED is rejected client-side with guidance rather than forwarded. --ecosystem maps through the generated enum value map, so new ecosystems need at most a dependency bump, never CLI code.
• run waits by default (capped backoff poll + spinner in rich mode); --wait=false submits only. A MALWARE verdict expands the full report inline in table mode; plain/json keep a stable headline shape so the agent contract does not change with the verdict. The idempotency key derives from the target so repeat runs dedupe server-side; --rescan forces a fresh scan.
• get/show take a package-ref by default (newest scan for the target), with --scan-id as the direct path for agent orchestration. show omits empty report sections so non-library component reports do not render hollow tables.
• Output follows the repo's Renderable contract (table/plain/json) with verdict badges (malware/inconclusive/benign).

Verbs

No new verbs: run, get, list, show are all already in the allow-list. verbs.go unchanged.

API bump

Bumps the safedep/api generated bindings to pick up PackageScanService. The same bump widened the MalwareAnalysisService client interface, so the jfrog integration test fake gains the new Internal* methods (test-only change).

Docs

One page per leaf under docs/cmd/, linked from the README command index, per DEVGUIDE.

Testing

• make build, make test, golangci-lint run ./..., and the convention tests (go test ./internal/cmd/ -run Conventions) all pass locally.
• Table-driven unit tests cover target resolution (explicit / PURL / custom PURL types / UNSPECIFIED rejection / missing version), the run wait/no-wait/rescan/timeout/malware-report paths, get by ref vs scan-id, list filter building, and show not-completed handling and section rendering.

🤖 Generated with Claude Code

[safedep]

SafeDep Report Summary

Package Details

Package	Malware	Vulnerability	Risky License	Report
buf.build/gen/go/safedep/api/grpc/go @ v1.6.2-20260721112344-78a866a85e69.1 go.mod				🔗
buf.build/gen/go/safedep/api/protocolbuffers/go @ v1.36.11-20260721112344-78a866a85e69.1 go.mod				🔗

View complete scan results →

_{This report is generated by SafeDep Github App}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2f0c02f9ae

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".