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.
199 lines
10 KiB
Markdown
199 lines
10 KiB
Markdown
# 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.
|
|
|
|
CLI history before v0.3 is recorded in the project root
|
|
[CHANGELOG.md](../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-file` YAML/JSON for the long tail +
|
|
`--generate-skeleton` template 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-pages` canon.
|
|
- `weknora mcp serve` adds `chunk_list` as 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-size` on `search docs` and `search sessions`
|
|
(catching up with `session list` / `doc list` canon from v0.3+v0.4).
|
|
- `weknora doc list` gains `--keyword` / `--file-type` / `--source` /
|
|
`--tag-id` / `--start-time` / `--end-time` (RFC3339) — matches the
|
|
SDK's `KnowledgeListFilter` surface. Time flags reject malformed
|
|
input with `input.invalid_argument`.
|
|
- MCP `doc_list` tool 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 via `LoadMessages` and renders messages
|
|
inline after session metadata. JSON mode projects messages into a
|
|
`messages` array. `--limit` without `--full` errors with
|
|
`input.invalid_argument`.
|
|
- `weknora kb view` human render now includes `TYPE`, `PINNED` (badge,
|
|
only when set), `TEMPORARY` (badge), `PROCESSING` (with doc count,
|
|
only when active), `SUMMARY MODEL`, and `CREATED`. Nested config
|
|
structs stay JSON-only.
|
|
- `weknora doc view` human render expands to include `TITLE` (when
|
|
distinct from filename), `DESC`, `SOURCE`, `CHANNEL`, `TAG`,
|
|
`STORAGE` (human-readable bytes), `SUMMARY`, `ENABLED`, and `HASH`
|
|
(12-char prefix). All omit-empty.
|
|
- `weknora doc upload` gains `--enable-multimodel` (tri-state:
|
|
unset/true/false), repeatable `--metadata key=value`, and
|
|
`--channel` flags. `--enable-multimodel` and `--channel` apply to
|
|
file / `--recursive` / `--from-url`; `--metadata` is file /
|
|
`--recursive` only (the URL-ingest request carries no metadata
|
|
field server-side, so passing it with `--from-url` is rejected
|
|
up-front as `input.invalid_argument`). URL mode additionally
|
|
accepts `--title`, `--file-type`, and `--tag-id`. Threads through
|
|
to the SDK's `CreateKnowledgeFromFile` / `CreateKnowledgeFromURL`
|
|
signatures (previously hardcoded to nil/"api" and dropped URL
|
|
extras).
|
|
|
|
#### Fixed
|
|
- MCP `search_chunks` tool: `limit` arg now correctly threads into
|
|
`SearchParams.MatchCount`. Previously the server's default cap won,
|
|
silently capping below the requested limit.
|
|
- `search sessions` human time format: now renders a relative
|
|
duration ("2 hours ago") matching `session list`, instead of raw
|
|
RFC3339.
|
|
- `doc upload` (file path): re-uploading a file already ingested into
|
|
the KB now surfaces as `resource.already_exists` (exit 1) instead of
|
|
the misleading `network.error` ("check base URL reachability"). The
|
|
SDK returns its `ErrDuplicateFile` sentinel with no `HTTP error <n>:`
|
|
prefix because the duplicate is detected via file-hash short-circuit,
|
|
not by HTTP status; the previous fall-through to `WrapHTTP` therefore
|
|
misclassified it. The `--from-url` branch already handled the
|
|
symmetric `ErrDuplicateURL` correctly.
|
|
|
|
#### Breaking changes
|
|
- `weknora search docs` now applies the keyword filter server-side via
|
|
`ListKnowledgeWithFilter` (was: page through every doc and
|
|
substring-match client-side). Smaller wire payload on large KBs.
|
|
**The match is now case-sensitive** (server uses `LIKE %keyword%`),
|
|
whereas the previous client-side path lowered both sides. Callers
|
|
that relied on case-insensitive matching (e.g. `search docs Q3`
|
|
finding `q3 retro`) must lower-case the query themselves, or fall
|
|
back to `weknora api` with a custom filter.
|
|
|
|
#### Changed
|
|
- `cli/AGENTS.md` MCP 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.md` adds "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.md` now documents the `weknora api` raw HTTP passthrough
|
|
as the canonical escape hatch for deep KB config, per-request `chat`
|
|
/ `agent invoke` overrides, and operations without a CLI verb.
|
|
|
|
### v0.4 — output contract hardening and mainstream alignment
|
|
|
|
#### Breaking changes
|
|
- Dropped the JSON envelope. `stdout` now emits bare typed data
|
|
(`{...}` or `[...]`); errors are written to `stderr` as `code: msg`
|
|
with an actionable `hint:` line. Pipelines using `--json | jq` no
|
|
longer have to filter out an envelope wrapper.
|
|
- Dropped `--dry-run`. Destructive writes still require `-y/--yes`;
|
|
non-TTY callers that omit `-y` exit with code 10 and
|
|
`input.confirmation_required` so 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 in `mcp 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 to `stdout` for
|
|
scripting (raw secret by default; `--json` emits `{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.
|
|
- `--limit` and `--all-pages` on 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-token` validates the supplied key against
|
|
`/auth/me` before 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 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.
|
|
- `doc view <id>` — show one document's metadata (title, file name,
|
|
type, size, parse status, embedding model, processed-at, error
|
|
message). Counterpart to `kb view` and `session view`.
|
|
- `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`.
|
|
- `unlink` — remove the cwd's `.weknora/project.yaml` so subsequent
|
|
commands stop auto-resolving `--kb` from 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. `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).
|