Skip to content

feat(cli): cover every OpenAPI endpoint and request-body param#968

Merged
nicoloboschi merged 1 commit intomainfrom
feat/cli-complete-openapi-coverage
Apr 10, 2026
Merged

feat(cli): cover every OpenAPI endpoint and request-body param#968
nicoloboschi merged 1 commit intomainfrom
feat/cli-complete-openapi-coverage

Conversation

@nicoloboschi
Copy link
Copy Markdown
Collaborator

Summary

  • Wires the Rust CLI up to every endpoint in the Hindsight OpenAPI spec (46/62 → 62/62) and adds new webhook, audit, and bank-template subcommands plus memory history / per-memory clear-observations, document update, operation retry, bank set-disposition / consolidation-recover.
  • Fixes previously-hardcoded request-body fields so the user can actually set them: directive --priority; mental-model --tags / --max-tokens / --trigger-refresh-after-consolidation; recall --query-timestamp; reflect --fact-types / --exclude-mental-models / --exclude-mental-model-ids; retain --document-tags.
  • Adds cli-coverage-check in hindsight-dev + a new CI job that fails any PR where a new OpenAPI endpoint or request-body field isn't wired into the CLI (or explicitly skipped in hindsight-cli/.openapi-coverage.toml with a reason). Current state: 62 operations + 89 request params covered, with 38 fields explicitly skipped for documented reasons (flattened into several flags, nested structs, or surfaced via a different subcommand).

Why

The CLI had silently fallen behind the API — 16 endpoints had no command at all (entire webhook + audit subsystems, bank templates, memory history, document update, operation retry, consolidation recovery, update_bank_disposition) and several commands hardcoded request-body fields that the API accepts. There was no automated check to catch the drift, so new endpoints kept slipping through.

How the CI check works

  • uv run cli-coverage-check (in hindsight-dev) parses hindsight-docs/static/openapi.json and cross-checks:
    1. Every operationId is called somewhere in hindsight-cli/src/**/*.rs. The progenitor-generated client methods are named identically to the OpenAPI operationId, so .<op_id>( is a strong signal.
    2. Every request-body property is present in hindsight-cli/src/main.rs as a clap command variant field or long = "..." attribute.
  • Anything that legitimately isn't exposed lives in hindsight-cli/.openapi-coverage.toml under [skip] (operation-level) or [fields.<op_id>] (field-level) — each entry must carry a reason string.
  • Stale skip entries (operation or field no longer in the spec) also fail the check.

Test plan

  • ./scripts/hooks/lint.sh passes
  • cargo build + cargo test pass (76 tests)
  • uv run cli-coverage-check reports OK: all 62 operations and 89 request params covered
  • hindsight --help shows new webhook, audit subcommands; hindsight bank --help shows new template/recover/set-disposition; hindsight memory --help shows history and clear-observations
  • CI check-cli-coverage job runs green
  • Smoke test (HINDSIGHT_CLI=... ./hindsight-cli/smoke-test.sh) exercises the new webhook / audit / bank-template / memory-history / operation-retry commands against a live API

Wires the Rust CLI up to every endpoint exposed by the Hindsight OpenAPI
spec and adds CI enforcement so new endpoints or new request-body fields
cannot slip in without matching CLI coverage.

Endpoints
- New `hindsight webhook {list,create,update,delete,deliveries}` and
  `hindsight audit {list,stats}` subcommands.
- `hindsight bank` gains `set-disposition`, `consolidation-recover`,
  `export-template`, `import-template`, `template-schema`.
- `hindsight memory` gains `history` and per-memory `clear-observations`.
- `hindsight document update`, `hindsight operation retry` added.
- Brings CLI coverage from 46/62 to 62/62 operations.

Request-body parameters
- Expose missing flags that the CLI was silently hardcoding: directive
  `--priority`; mental-model `--tags` / `--max-tokens` /
  `--trigger-refresh-after-consolidation`; recall `--query-timestamp`;
  reflect `--fact-types` / `--exclude-mental-models` /
  `--exclude-mental-model-ids`; retain `--document-tags`.

CI enforcement
- New `cli-coverage-check` entry point in `hindsight-dev` parses
  openapi.json and verifies that (a) every operationId is called from
  hindsight-cli/src/ (the progenitor client method names match the
  operationId), and (b) every request-body property is present in
  main.rs as a clap field or `long = "..."` attribute.
- Intentional non-exposures live in `hindsight-cli/.openapi-coverage.toml`
  under `[skip]` / `[fields.<op>]` with a reason each (38 documented
  field skips for flattened structs, nested structs, or fields surfaced
  via a different subcommand).
- New `check-cli-coverage` job in .github/workflows/test.yml, triggered
  on cli/core/dev/ci path changes, runs the script on every PR.
- smoke-test.sh exercises the new webhook / audit / bank-template /
  set-disposition / consolidation-recover commands.
@nicoloboschi nicoloboschi merged commit c05c491 into main Apr 10, 2026
48 of 50 checks passed
r266-tech added a commit to r266-tech/hindsight that referenced this pull request Apr 11, 2026
…commands

PR vectorize-io#968 added full OpenAPI endpoint coverage (46/62 → 62/62) but
cli.md was not updated. Add sections for:

- Webhook management (list/create/update/delete/deliveries)
- Audit logs (list with action/transport/date filters)
- Operation management (list/get/cancel/retry)
- Memory history and clear-observations
- Document update
- Bank set-disposition and consolidation-recover
- New flags on recall (--tags, --query-timestamp) and reflect (--fact-types)

Fixes vectorize-io#982
nicoloboschi pushed a commit that referenced this pull request Apr 13, 2026
…commands (#983)

PR #968 added full OpenAPI endpoint coverage (46/62 → 62/62) but
cli.md was not updated. Add sections for:

- Webhook management (list/create/update/delete/deliveries)
- Audit logs (list with action/transport/date filters)
- Operation management (list/get/cancel/retry)
- Memory history and clear-observations
- Document update
- Bank set-disposition and consolidation-recover
- New flags on recall (--tags, --query-timestamp) and reflect (--fact-types)

Fixes #982
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