Skip to content

feat(cli): add JSON output for extension inventory and provenance#100

Open
Adams521 wants to merge 2 commits into
RealZST:mainfrom
Adams521:feat/cli-json-provenance
Open

feat(cli): add JSON output for extension inventory and provenance#100
Adams521 wants to merge 2 commits into
RealZST:mainfrom
Adams521:feat/cli-json-provenance

Conversation

@Adams521

@Adams521 Adams521 commented Jul 6, 2026

Copy link
Copy Markdown

Why

HarnessKit already tracks rich extension inventory, source, and install metadata internally, but the CLI currently exposes this information primarily through human-readable output.

That makes it harder for terminal-first users, headless/server workflows, local scripts, debugging, and issue triage to inspect what HarnessKit already knows about installed extensions.

This PR adds machine-readable JSON output for the existing hk list and hk info <name> commands. It is intentionally limited to the current CLI semantics:

  • hk list --json mirrors the existing grouped/deduped list table.
  • hk info <name> --json mirrors the existing first-name-match detail view.

This gives users and maintainers a script-friendly way to inspect existing inventory/provenance data without introducing a new inventory model or update system.

Summary

  • Add --json output for hk list.
  • Add --json output for hk info <name>.
  • Keep existing human-readable output unchanged.
  • Use explicit CLI DTOs with schema_version: 1.
  • Keep hk list --json limited to grouped table fields.
  • Keep detailed source/install metadata in hk info <name> --json.

Details

hk list --json mirrors the current grouped/deduped table semantics and exposes only table-level fields:

  • name
  • kind
  • agents
  • pack
  • trust_score
  • enabled
  • status

It intentionally does not expose instance-level fields such as id, source_path, source, install_meta, update_eligible, update_reason, remote_revision, checked_at, check_error, or nested instances.

hk info <name> --json mirrors the current first-name-match behavior and exposes detailed metadata for the selected extension, including existing source and static install metadata fields.

Update eligibility is static and derived from the existing service::is_update_eligible rule. This PR does not perform update checks, call remotes, or expose cached update status.

Non-goals

This PR does not:

  • add check-updates
  • perform update checks
  • call git ls-remote
  • add network behavior
  • add auto-update
  • add shell hooks
  • add a source resolver
  • add a policy engine
  • add risk diffing
  • change scanner behavior
  • change store behavior
  • change service behavior
  • change manager/update behavior
  • change install behavior
  • change database schema
  • change frontend/UI behavior

Implementation notes

  • Implementation is intentionally kept in crates/hk-cli/src/main.rs.
  • JSON output uses explicit CLI DTOs rather than serializing raw Extension.
  • hk list agents --json remains unsupported and returns a stable error:
    --json is only supported for extension list output, not list agents
  • No new dependencies were added.

Validation

Automated:

  • PASS cargo fmt --check --package hk-cli
  • PASS cargo test -p hk-cli (17 tests passed)
  • PASS cargo test --workspace (hk-cli 17, hk-core 532, hk-core integration 8, hk-desktop 2, hk-web 3, hk-web integration 6)
  • PASS npm test (32 files / 249 tests passed)
  • PASS git diff --check
  • PASS hidden/bidi control grep for crates/hk-cli/src/main.rs

Manual smoke:

  • PASS cargo run -p hk-cli -- list
  • PASS cargo run -p hk-cli -- list --json
  • PASS cargo run -p hk-cli -- list --kind skill --json
  • PASS cargo run -p hk-cli -- list --agent codex --json
  • PASS cargo run -p hk-cli -- list agents
  • PASS cargo run -p hk-cli -- list agents --json (returned the expected unsupported error)
  • PASS cargo run -p hk-cli -- list --help
  • PASS cargo run -p hk-cli -- info --help

If local extensions were available:

  • PASS cargo run -p hk-cli -- info <existing-extension-name>
  • PASS cargo run -p hk-cli -- info <existing-extension-name> --json

Risk and mitigation

  • Low implementation risk: this is a CLI-only output change.
  • Human-readable output risk: mitigated by only using JSON branches when --json is passed.
  • Grouping/filter risk: mitigated by sharing the same grouped row selection behavior and testing dedupe-before-filter order.
  • DTO leakage risk: mitigated by keeping list JSON to table-level fields only.
  • Update confusion risk: mitigated by exposing only static update eligibility, not update status.
  • Network/update risk: mitigated by avoiding update manager paths and remote calls.

@Adams521 Adams521 force-pushed the feat/cli-json-provenance branch from 4f9544a to 4ec34f2 Compare July 6, 2026 14:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant