c87e35b34b
Code-reuse polish (post-implementation review pass): - Extract text.OneLine(maxWidth, s) helper combining preview-row normalization (newline/CR/tab → space) with text.Truncate's UTF-8-safe truncation. Replaces agent/view.go truncate1Line (ASCII '...' + byte-slice CJK-unsafe) and chunk/list.go singleLine. - Lift cmdutil.OpenInput(path) for the '-' = stdin / else os.Open pattern shared across agent create/edit and the api command. Replaces agent/create.go's private openInput. - Strip inline doc-spec parentheticals from source comments — those belong in commit messages and project docs, not in source where they rot. Pre-PR audit fixes: - doc upload: reject `--metadata` paired with `--from-url` as input.invalid_argument up-front (the URL-ingest request type has no metadata field server-side, so the pair would otherwise silently drop). Long help and CHANGELOG updated to call out the asymmetry. - doc upload (file path): map sdk.ErrDuplicateFile sentinel to resource.already_exists. The sentinel arrives with no "HTTP error <n>:" prefix because the SDK short-circuits on file-hash before reading the HTTP status, so the previous WrapHTTP fall-through misclassified it as network.error with a misleading "check base URL reachability" hint. The --from-url branch already handled ErrDuplicateURL this way; this closes the asymmetry. Caught by e2e re-upload of an already-ingested file; regression test added. - README exit-10 enumeration adds `agent delete` and `chunk delete` (these were missing alongside the v0.5 destructive verbs they were meant to gate). Docs sync: - cli/README.md: command tree now includes the chunk subtree; adds agent / chunk lines to the 5-minute quickstart; adds a "Contributing / Reporting issues" section pointing at the repo's SECURITY.md and AGENTS.md; drops third-party CLI parallels from the surface description. - cli/AGENTS.md: "Command surface design SOP" gains the flag-vs-escape-hatch step. "CRUD command flag canon" renamed to the hard-required-flags pattern with the contrast (TTY-prompts-fill) defined inline rather than via opaque shorthand. - cli/CHANGELOG.md: search docs case-sensitivity shift promoted to its own #### Breaking changes subsection. MCP doc_list filter count corrected from 5 to 6. Drops the bogus go.mod yaml.v3 entry (yaml.v3 was already a dependency on main; v0.5 added zero go.mod lines). Replaces internal-Go identifiers (fuzzyTime, NoOptDefVal) with user-language and drops the § section-symbol jargon.
10 KiB
10 KiB
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 and the CLI follows Semantic Versioning independently of the WeKnora server / frontend release cadence.
CLI history before v0.3 is recorded in the project root CHANGELOG.md under the release that introduced the CLI.
[Unreleased]
v0.5 — agent CRUD, chunk subtree, MCP chunk_list, audit-driven cleanup
Added
weknora agent create <name> --model <id>/agent edit <id>/agent delete <id>— hybrid surface (hot-path flags for the common fields +--config-fileYAML/JSON for the long tail +--generate-skeletontemplate emit).--from <agent-id>copies from an existing agent.weknora chunk list --doc <doc-id>/chunk view <chunk-id>/chunk delete <chunk-id> --doc <doc-id>— new subtree for RAG retrieval debug. Paginated with v0.4--limit/--page-size/--all-pagescanon.weknora mcp serveaddschunk_listas the 10th curated tool.weknora agent view <id>human output now renders all 34 AgentConfig fields (previously 7), grouped into 10 presentation sections.--all-pages/--page-sizeonsearch docsandsearch sessions(catching up withsession list/doc listcanon from v0.3+v0.4).weknora doc listgains--keyword/--file-type/--source/--tag-id/--start-time/--end-time(RFC3339) — matches the SDK'sKnowledgeListFiltersurface. Time flags reject malformed input withinput.invalid_argument.- MCP
doc_listtool gains the same 6 filter fields (keyword,file_type,source,tag_id,start_time,end_time) so agents have parity with the CLI. weknora session view --full(with--limit, default 50, bounds 1..1000) loads chat history viaLoadMessagesand renders messages inline after session metadata. JSON mode projects messages into amessagesarray.--limitwithout--fullerrors withinput.invalid_argument.weknora kb viewhuman render now includesTYPE,PINNED(badge, only when set),TEMPORARY(badge),PROCESSING(with doc count, only when active),SUMMARY MODEL, andCREATED. Nested config structs stay JSON-only.weknora doc viewhuman render expands to includeTITLE(when distinct from filename),DESC,SOURCE,CHANNEL,TAG,STORAGE(human-readable bytes),SUMMARY,ENABLED, andHASH(12-char prefix). All omit-empty.weknora doc uploadgains--enable-multimodel(tri-state: unset/true/false), repeatable--metadata key=value, and--channelflags.--enable-multimodeland--channelapply to file /--recursive/--from-url;--metadatais file /--recursiveonly (the URL-ingest request carries no metadata field server-side, so passing it with--from-urlis rejected up-front asinput.invalid_argument). URL mode additionally accepts--title,--file-type, and--tag-id. Threads through to the SDK'sCreateKnowledgeFromFile/CreateKnowledgeFromURLsignatures (previously hardcoded to nil/"api" and dropped URL extras).
Fixed
- MCP
search_chunkstool:limitarg now correctly threads intoSearchParams.MatchCount. Previously the server's default cap won, silently capping below the requested limit. search sessionshuman time format: now renders a relative duration ("2 hours ago") matchingsession list, instead of raw RFC3339.doc upload(file path): re-uploading a file already ingested into the KB now surfaces asresource.already_exists(exit 1) instead of the misleadingnetwork.error("check base URL reachability"). The SDK returns itsErrDuplicateFilesentinel with noHTTP error <n>:prefix because the duplicate is detected via file-hash short-circuit, not by HTTP status; the previous fall-through toWrapHTTPtherefore misclassified it. The--from-urlbranch already handled the symmetricErrDuplicateURLcorrectly.
Breaking changes
weknora search docsnow applies the keyword filter server-side viaListKnowledgeWithFilter(was: page through every doc and substring-match client-side). Smaller wire payload on large KBs. The match is now case-sensitive (server usesLIKE %keyword%), whereas the previous client-side path lowered both sides. Callers that relied on case-insensitive matching (e.g.search docs Q3findingq3 retro) must lower-case the query themselves, or fall back toweknora apiwith a custom filter.
Changed
cli/AGENTS.mdMCP curation rationale rewritten: curated read-only is a deliberate product call gated on the absence of server-side per-token scope. When server-side scope ships, mutation tools can land in the MCP surface.cli/AGENTS.mdadds "Command surface design SOP" and "CRUD command flag canon" sections for future contributors. The design-SOP section includes a step reminding contributors to decide flag-vs-escape-hatch per field rather than trying to flag-mirror every SDK capability.cli/README.mdnow documents theweknora apiraw HTTP passthrough as the canonical escape hatch for deep KB config, per-requestchat/agent invokeoverrides, and operations without a CLI verb.
v0.4 — output contract hardening and mainstream alignment
Breaking changes
- Dropped the JSON envelope.
stdoutnow emits bare typed data ({...}or[...]); errors are written tostderrascode: msgwith an actionablehint:line. Pipelines using--json | jqno longer have to filter out an envelope wrapper. - Dropped
--dry-run. Destructive writes still require-y/--yes; non-TTY callers that omit-yexit with code 10 andinput.confirmation_requiredso an agent must surface the prompt to a human before retrying. - Dropped the per-command AI footer that rendered when AI-coding-agent
env detection fired. The same machine-readable guidance now lives in
the standard
--help(visible to all callers) and inmcp serve's tool descriptions.
Added
weknora mcp serve— curated read-only stdio MCP server exposing 9 tools (kb_list,kb_view,doc_list,doc_view,doc_download,search_chunks,chat,agent_list,agent_invoke). Destructive verbs are intentionally excluded.weknora agent list/agent view/agent invoke— manage and call WeKnora's server-side Custom Agent resources.weknora auth token— print the active credential tostdoutfor scripting (raw secret by default;--jsonemits{token, mode, context}).weknora doc upload --from-url— ingest a remote URL.--json=fields,...field projection and--jq <expr>filtering on every command that emits JSON.--limitand--all-pageson list / search commands for bounded output and explicit pagination control.- Per-resource filter flags:
kb list --pinned,doc list --status,session list --since.
Changed
- Go toolchain bumped from 1.24 to 1.26.
auth login --with-tokenvalidates the supplied key against/auth/mebefore persisting, and prints an advisory if the keyring is unavailable and credentials fall back to a 0600 file under$XDG_CONFIG_HOME/weknora/secrets/.- AGENTS.md rewritten as a developer guide (~170 lines, 6 H2 sections).
v0.3 — extended management surface and a session subtree
Added
context add/context list/context remove— first-class CRUD over connection targets (previously implicit viaauth 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 (*stringoptions 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 /--jsonpaths.doc view <id>— show one document's metadata (title, file name, type, size, parse status, embedding model, processed-at, error message). Counterpart tokb viewandsession view.doc download— stream a knowledge file to disk (-O FILE/-O -for stdout) with--clobbercontrolling 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-fileOK/FAILprogress lines on the human path; aggregateduploaded[]/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 (ghsearch code/repos/issues/…shape).search chunksis 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.unlink— remove the cwd's.weknora/project.yamlso subsequent commands stop auto-resolving--kbfrom it. Walks up from cwd so a user in a subdirectory can unlink without cd-ing to the project root.- 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.DownloadKnowledgeFileis 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/PathAuthRefreshconstants — so HTTP middleware doesn't re-hardcode the literals.IsPinned boolfield onKnowledgeBase(server already returned it; SDK just hadn't modeled it).