Skip to content

feat(kb): vk kb list/delete/prune for 0.6.0 — clean up the 425-kb backlog#6

Merged
voidkey merged 10 commits into
mainfrom
feature/kb-subcommands
May 14, 2026
Merged

feat(kb): vk kb list/delete/prune for 0.6.0 — clean up the 425-kb backlog#6
voidkey merged 10 commits into
mainfrom
feature/kb-subcommands

Conversation

@voidkey
Copy link
Copy Markdown
Collaborator

@voidkey voidkey commented May 14, 2026

Summary

vk kb list / delete / prune — manage vectoria knowledgebases. Headline command is vk kb prune, designed to clean up the 425 accumulated kbs from vk create's one-kb-per-invocation pattern (0.5.2 closed the future leak; this PR adds the bulk-cleanup tool).

The user can now run, post-merge:

```bash
vk kb prune --pattern 'vibeknow-cli-*' --yes # actually delete CLI's own orphans
```

Safety contract (load-bearing, all integration-test-pinned)

  • Refuses to run without --pattern or --older-than (exit 2). No "delete everything" shortcut.
  • Dry-run by default: prints matched kbs without DELETE. --yes (or VIBEKNOW_ASSUME_YES=1) actually deletes.
  • Idempotent 404: counts as success (rm -f semantics).
  • Exit codes: 0 success / 2 bad input / 5 all-fail / 7 partial-success.

Diff (10 commits)

  • 0f1015f feat(vectoria): add ListKBs client method — paginated list wrapping GET /v1/knowledgebases?offset=N&limit=N
  • 772610e feat(durfmt): add ParseAge supporting Nd day-suffix shortcut — new internal/durfmt pkg parsing 7d / 24h / 1h30m
  • 6ac258a feat(kb): add subcommand skeleton + i18n keys — 17 keys in en+zh
  • 8d742ab feat(kb): vk kb list with --pattern and --older-than filters — client-side glob + age filter; text + JSON output
  • e309b83 feat(kb): vk kb delete with idempotent 404 handling
  • d558dbc feat(kb): vk kb prune with dry-run default, pattern/age filters, partial-success exit 7
  • 9d3b8a2 test(integration): kb prune dry-run-by-default, apply, filter-required — 3 end-to-end tests against mock vectoria
  • 9516ce4 docs: document vk kb subcommand family for 0.6.0 — CHANGELOG / AGENTS / README + zh
  • 6586d69 chore: bump version to 0.6.0
  • ba44016 refactor(kb): final-review fixes — exit-2 consistency, pre-flight, comment

Test plan

  • go test ./... passes (incl. 3 new integration tests for kb prune + 4 filter unit tests + 2 prune-validation unit tests + ListKBs unit test + ParseAge unit tests)
  • go build ./... clean
  • vk kb --help lists three subcommands (list, delete, prune)
  • vk version reflects 0.6.0
  • vk kb prune without filter → exit 2 with clear message
  • vk kb prune --pattern 'bogus-*' → real-backend smoke walked 5 pages, 0 matches, exit 0 (proves pagination + filter wiring against real vectoria)
  • Manual smoke (post-merge): run vk kb prune --pattern 'vibeknow-cli-*' --yes on the user's tenant; expect ~10-20 orphan kbs to be cleaned. Verify count drops via vk kb list --output json | jq .total.

Final review status

🟡 APPROVED with minor follow-ups (opus-level review). 3 of 4 important findings applied in commit ba44016. Skipped:

  • page/size client-side clamping — consistent with existing vk video list; backend already returns clear error on bad values
  • locale pinning in integration tests — cross-cutting concern, separate follow-up
  • fmt.Println vs cmd.OutOrStdout() — pre-existing pattern across the codebase
  • 0d edge case in ParseAge — documented behavior (interpreted as "no age filter")

Out of scope

  • vk kb show <id>vk kb list --pattern <exact-name> covers the common lookup; backend has no per-id GET anyway (returns 405).
  • Doc count column in vk kb list — N+1 fetches; can add --with-doc-count later if asked.
  • Auto-cleanup on each vk create — surprising side-effect; users invoke vk kb prune explicitly.

Spec / plan

  • Spec: docs/superpowers/specs/2026-05-14-kb-subcommands-design.md
  • Plan: docs/superpowers/plans/2026-05-14-kb-subcommands.md

(Both live in the untracked docs/ per team convention; not in this PR.)

voidkey added 10 commits May 14, 2026 22:07
…mment

Apply 3 of 4 important findings from final code review:

- cmd/kb/list.go: --older-than parse error and --pattern glob error
  now route through clerr.Validation so they exit 2 (matches prune's
  behavior + the documented exit-code contract). Pre-flight pattern
  syntax check moved before the HTTP call.
- cmd/kb/prune.go: pattern syntax pre-flighted at the top of RunE so
  a bad glob exits 2 before the first list-page round-trip. The
  scan-loop's per-page filterKBs() still validates as a safety net.
- cmd/kb/delete.go: document why the confirmation prompt doesn't show
  the kb name. Spec §3 imagined a per-id GET to enrich the prompt;
  the vectoria backend returns 405 Method Not Allowed for that route,
  so the spec's "fallback to UUID-only" path is the only path.

Skipped: --page/--size client-side clamping (consistent with the
existing vk video list pattern; backend returns clear error on bad
values). Locale pinning in integration tests is a cross-cutting
concern best handled in one sweep across all integration tests.
@voidkey voidkey merged commit 551aa4b into main May 14, 2026
3 checks passed
@voidkey voidkey deleted the feature/kb-subcommands branch May 14, 2026 14:42
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