From c9b837dfcef08f7738378e92833056f5f4a03947 Mon Sep 17 00:00:00 2001 From: nullkey Date: Wed, 13 May 2026 14:25:05 +0800 Subject: [PATCH] docs(cli): sync README + AGENTS.md, add cli/CHANGELOG.md, clear stale e2e refs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit v0.3 feature commits didn't update the docs alongside; this commit syncs them and introduces a CLI-local changelog so v0.3+ release notes stop crowding the project root file. cli/CHANGELOG.md (new): - Subsystem-local pattern, mirroring mcp-server/CHANGELOG.md. CLI versions independently from server / frontend cadence; reduces merge-conflict surface on the shared root file. - Scope: Added + SDK additions only. v0.3-internal dev churn (--top-k → --limit, kb clear-contents → kb empty, link --context introduce-then-drop, internal Go type-name leaks) never reached a shipped release so it doesn't belong in Changed / Fixed sections. mcp-server's v1.0.0 changelog is Added-only for the same reason. - v0.0–v0.2 history stays in the project root CHANGELOG.md; cross-referenced from the top of cli/CHANGELOG.md. Stale --help / quickstart examples fixed in cli/cmd/root.go, cli/README.md, and cli/AGENTS.md — all three showed the dropped bare `weknora search "" --kb=...` form; updated to `search chunks ...`. AGENTS.md updates: - Verb canon table gained edit / empty / download / pin / unpin / add / remove. - `auth` subtree description gained `refresh` and the transparent 401-retry transport (replacing the now-inverted "deferred to v0.3" sentence). - `search` and `session` subtree paragraphs added; top-level verb list gained `context` and `session`. cli/README.md top-level command list gained `session`; `search` short retitled to the parent description ("Search across chunks, knowledge bases, documents, or sessions") since search is now a pure dispatcher. Pre-existing stale e2e refs swept up while syncing: - cli/acceptance/doc.go listed e2e/ under "Future v0.2+:" — moved into the present-tense Sub-packages block. - envelope_test.go preamble "Deferred to v0.2 e2e" rephrased to "Deferred to the e2e harness" so it isn't pinned to a past version. Not changed (out of scope, flagged for future PRs): - envelope_test.go "Implemented count: 16" vs the actual 14 named entries — could be a different counting rule; verify with PR-8 author before editing. - envelope_test.go context_use deferred-cases narrative is loose (context_use.success IS golden-pinned today) but rewriting needs careful re-derivation of which error scenarios are still deferred. - cli/README.md:50 "once v0.2 ships" — v0.2-PR-original wording; not load-bearing once a release tag exists. No project-root CHANGELOG.md change in this commit. --- cli/AGENTS.md | 33 ++++++++++--- cli/CHANGELOG.md | 63 ++++++++++++++++++++++++ cli/README.md | 5 +- cli/acceptance/contract/envelope_test.go | 2 +- cli/acceptance/doc.go | 4 +- cli/cmd/root.go | 2 +- 6 files changed, 94 insertions(+), 15 deletions(-) create mode 100644 cli/CHANGELOG.md diff --git a/cli/AGENTS.md b/cli/AGENTS.md index 16ea5466..15ef0586 100644 --- a/cli/AGENTS.md +++ b/cli/AGENTS.md @@ -98,18 +98,35 @@ The command tree follows ` ` (gh style). Verbs are: | `list` | Multi-resource read | `kb list` | | `view` | Single-resource read | `kb view ` | | `create` | Create resource | `kb create --name X` | -| `delete` | Destructive remove | `kb delete -y` | +| `edit` | Partial update (only sent fields change) | `kb edit --description X` | +| `delete` | Destructive remove (KB itself) | `kb delete -y` | +| `empty` | Bulk-delete contents, preserve container | `kb empty -y` | | `upload` | Bulk write content | `doc upload ` | +| `download` | Stream resource to disk | `doc download -O file` | +| `pin` / `unpin` | Toggle "pinned" state (idempotent) | `kb pin ` | | `use` | Switch active selection | `context use ` | +| `add` / `remove` | Manage local config entries | `context add staging --host ...` | -`auth` subtree: `login` / `logout` / `list` / `status`. Mirrors gh's -`auth login / logout / status / switch / list`-style surface; weknora uses -`context use` instead of `auth switch` because contexts carry host + tenant -on top of credentials. Token refresh is deferred to v0.3 (will land as -transparent 401 retry in the SDK plus an explicit `auth refresh` command). +`auth` subtree: `login` / `logout` / `list` / `status` / `refresh`. Mirrors +gh's `auth login / logout / status / switch / list`-style surface; weknora +uses `context use` instead of `auth switch` because contexts carry host + +tenant on top of credentials. `auth refresh` exchanges the stored refresh +token for a new access + refresh pair (OAuth refresh-token grant); it +errors with `input.invalid_argument` on API-key contexts which have no +refresh semantic. Transparent 401 → refresh → retry is wired into the +SDK transport (`cli/internal/cmdutil/authretry.go`) with singleflight +de-dup, so most callers never need to invoke `auth refresh` explicitly. + +`search` subtree: verb-noun (gh `search code/repos/issues/...` shape) — +`search chunks "" --kb X` for hybrid retrieval, `search kb ""` / +`search docs "" --kb X` / `search sessions ""` for client-side +substring filtering on the listing endpoints. + +`session` subtree: `list` / `view` / `delete` for chat session +management. Sessions are the durable wrapper around `chat` invocations. Top-level RAG / connectivity verbs: `chat`, `search`, `api`, `link`, -`auth`, `doctor`, `version`. +`auth`, `context`, `session`, `doctor`, `version`. `doctor` is a deliberate divergence from gh / lark (neither ships a health-check command); the precedent is `flutter doctor` / `brew doctor`. @@ -211,7 +228,7 @@ release will introduce a `precondition.*` namespace (server returns HTTP 412 with a typed remediation body before opening the SSE / streaming response): - `weknora chat` when no chat model is configured for the active tenant -- `weknora search` when no retriever / vector store is configured +- `weknora search chunks` when no retriever / vector store is configured - `weknora doc upload` when no storage engine is selected for the KB Workaround until then: if a chat / search / upload call times out without diff --git a/cli/CHANGELOG.md b/cli/CHANGELOG.md new file mode 100644 index 00000000..b3e2aba2 --- /dev/null +++ b/cli/CHANGELOG.md @@ -0,0 +1,63 @@ +# Changelog — `weknora` CLI + +All notable changes to the `weknora` CLI (the binary under `cli/` in this +repository) will be documented in this file. + +The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) +and the CLI follows [Semantic Versioning](https://semver.org/) independently +of the WeKnora server / frontend release cadence. + +Earlier history (v0.0 through v0.2) is recorded in the project root +[CHANGELOG.md](../CHANGELOG.md) under the entries that introduced the CLI. + +## [Unreleased] + +### v0.3 — extended management surface and a `session` subtree + +#### Added +- `context add` / `context list` / `context remove` — first-class CRUD over + connection targets (previously implicit via `auth login --name`). + Removing the *current* context requires explicit `-y` (exit-10 protocol) + because subsequent commands have no default target. +- `auth refresh` — exchanges the stored refresh token for a new access + + refresh pair (OAuth refresh-token grant). Transparent 401 → refresh → + retry is also wired into the SDK transport with singleflight de-dup, so + most callers never need to invoke this explicitly. +- `kb edit` — partial-update edit with only-sent-fields semantics + (`*string` options so unset fields stay unset in the PUT body). +- `kb pin` / `kb unpin` — idempotent pin/unpin toggle; no-op when already + in the target state (emits `_meta.warnings`, no server call). +- `kb empty` — bulk-delete documents while preserving the KB record and + its config. High-risk-write; exit-10 confirmation in non-TTY / `--json` + paths; `--dry-run` emits `risk` + `dry_run:true`. +- `doc download` — stream a knowledge file to disk (`-O FILE` / + `-O -` for stdout) with `--clobber` controlling overwrite. Rejects + server-supplied path-like filenames; partial writes on error are + cleaned up. +- `doc upload --recursive --glob '*.md'` — walk a directory and upload + every match. Per-file `OK` / `FAIL` progress lines on the human path; + aggregated `uploaded[]` / `failed[]` envelope on `--json`. Exit code + typed to the first failure's class on partial failure. +- `search chunks` / `search kb` / `search docs` / `search sessions` — + verb-noun subtree (gh `search code/repos/issues/…` shape). `search + chunks` is hybrid (vector + keyword) retrieval; the other three are + client-side substring filters useful for discovering identifiers. + All four take `--limit N` / `-L N` (1..1000) to cap returned rows. +- `session list` / `session view` / `session delete` — chat session + management. +- `api --input FILE` / `api --input -` — body source for raw HTTP + passthrough (file or stdin); mutually exclusive with `--data`. +- Completion smoke test guards against cobra bumps silently breaking + bash / zsh / fish / powershell completion. + +#### SDK additions (Go client at `client/`, strictly additive) +- `OpenKnowledgeFile(ctx, id) (filename, body io.ReadCloser, err)` — new + primitive returning the body as a stream plus the server-suggested + Content-Disposition filename. `DownloadKnowledgeFile` is now a thin + wrapper (signature unchanged, gained partial-file-on-error cleanup). +- `WithTransport(http.RoundTripper) ClientOption` — lets the CLI install + the 401-retry transport. +- `PathAuthLogin` / `PathAuthRefresh` constants — so HTTP middleware + doesn't re-hardcode the literals. +- `IsPinned bool` field on `KnowledgeBase` (server already returned it; + SDK just hadn't modeled it). diff --git a/cli/README.md b/cli/README.md index 005e3a16..523c1175 100644 --- a/cli/README.md +++ b/cli/README.md @@ -18,7 +18,8 @@ Available Commands: doctor Run 4 self-checks: base URL, auth, server version, credential storage kb Manage knowledge bases link Bind the current directory to a knowledge base - search Hybrid (vector + keyword) chunk retrieval against a knowledge base + search Search across chunks, knowledge bases, documents, or sessions + session Manage chat sessions version Show CLI build metadata ``` @@ -69,7 +70,7 @@ weknora link --kb my-knowledge-base weknora doc upload notes.md # 6. Search -weknora search "what is reciprocal rank fusion?" +weknora search chunks "what is reciprocal rank fusion?" # 7. Ask the LLM (streams to terminal) weknora chat "summarise the design doc" diff --git a/cli/acceptance/contract/envelope_test.go b/cli/acceptance/contract/envelope_test.go index 6db376fc..9e659129 100644 --- a/cli/acceptance/contract/envelope_test.go +++ b/cli/acceptance/contract/envelope_test.go @@ -17,7 +17,7 @@ // (--with-token) + keyring-aware // Secrets store; helpers_test // (PR-6) does not yet expose a -// stdin hook. Deferred to v0.2 e2e. +// stdin hook. Deferred to the e2e harness. // - auth_login.error_auth_unauthenticated — same setup as above; deferred // together. // - context_use.error_local_context_not_found — `context use` has no --json diff --git a/cli/acceptance/doc.go b/cli/acceptance/doc.go index 298a25e0..b9e27076 100644 --- a/cli/acceptance/doc.go +++ b/cli/acceptance/doc.go @@ -6,9 +6,7 @@ // // Sub-packages: // contract/ — envelope JSON shape golden + error.code registry consistency -// -// Future v0.2+: // e2e/ — real WeKnora server blackbox tests (testscript-style) // -// Mirrors gh's acceptance/ + kubernetes test/e2e/ pattern (spec §4.5). +// Layout convention follows spec §4.5. package acceptance diff --git a/cli/cmd/root.go b/cli/cmd/root.go index 4ef5daf0..e258a6ec 100644 --- a/cli/cmd/root.go +++ b/cli/cmd/root.go @@ -139,7 +139,7 @@ hybrid searches against a WeKnora server from your shell or an AI agent.`, Example: ` weknora auth login --host=https://kb.example.com # one-time setup weknora kb list # list knowledge bases weknora kb view # show one - weknora search "your question" --kb= # hybrid retrieval + weknora search chunks "your question" --kb= # hybrid retrieval weknora doctor --json # health check (agent-readable)`, SilenceUsage: true, SilenceErrors: true,