2026-05-12 15:38:01 +00:00
|
|
|
package search
|
|
|
|
|
|
|
|
|
|
import (
|
|
|
|
|
"context"
|
refactor(cli): envelope sweep — Emit shape, batch ops, MCP StructuredContent, api flag cleanup
Sweep every CLI output path through the v0.7 envelope contract.
FormatOptions.Emit signature changes to (w, data, meta *output.Meta)
so list commands surface meta.count / has_more in the wire envelope.
TTY indent decision plumbed via FormatOptions.TTY (set by
ResolveDefault). --format and --jq promoted to persistent root flags
so unknown-subcommand paths still reach the typed-envelope guard
(per-command registration would have rejected --format on unknown
commands as cobra-prose exit 2). WEKNORA_FORMAT env-var fallback
honored before TTY-resolved default. AddFormatFlag retained for the
per-command --jq field-hint Long-text addendum.
~55 production Emit call sites swept across cli/cmd/**: list paths
populate meta.count; mutation paths pass nil meta; envelope.profile
threaded via globalProfile. Existing JSON-shape tests migrated to
decode the envelope wrapper.
Multi-target batch operations get a unified shape via new helpers:
- output.BatchItem + output.WriteBatchEnvelope (§4.5 per-item ok
pattern; data:[{id, ok, result?|error?}], meta:{count, successes*,
failures*}; Successes/Failures *int so explicit zero survives
omitempty in all-fail case).
- cmdutil.RunBatch + cmdutil.EmitBatch + cmdutil.DeletedAtNow +
cmdutil.ClassifyContextErr collapse the three previously-duplicated
multi-delete pipelines (doc / chunk / session) into one call site
pattern. doc upload --recursive uses the same helpers with a per-
file resultFn. Summary error sets Silent:true so the stderr
envelope path doesn't duplicate the stdout batch detail (exit 1
preserved via Code → ExitCode).
ConfirmDestructive / ConfirmDestructiveBatch extended with action +
retryCmd parameters. Every destructive command (kb delete, kb edit,
doc delete, doc delete --all, agent delete, agent edit, session
delete, chunk delete, auth logout, api -X DELETE) now attaches
error.risk.{level:"destructive", action:"<noun.verb>"} +
error.retry_command on the exit-10 envelope. kb edit / agent edit
also gain the destructive guard wiring (CHANGELOG listed them as
gated but they were silently executing without -y).
MCP tool handlers' 31 error paths return CallToolResult with
IsError + Content text fallback + StructuredContent (envelope.error
shape via cmdutil.ErrorToDetail). Handler Out type changed from
typed *sdk.X to any so the go-sdk auto-marshal doesn't overwrite
StructuredContent with a zero-struct on error returns. Success path
manually populates CallToolResult.StructuredContent via successResult
helper.
weknora api cleanup:
- -d/--data flag removed; body via --input <file> or --input -
(stdin) only. Aligns with gh / curl convention.
- HTTP method whitelist removed; any non-empty method accepted.
- HTTP Retry-After header → cmdutil.Error.RetryAfterSeconds →
envelope.error.retry_after_seconds.
- runAPIPaginated raw-passthrough fallback now wraps response in
envelope so --paginate never emits bare JSON to stdout.
Test sweep: ~60 cmd/** tests migrated to decode envelope shape.
9 wire-contract goldens updated under cli/acceptance/testdata/wire/.
Spec: docs/superpowers/specs/2026-05-20-weknora-cli-v0.7-design.md §4 / §5
2026-05-21 10:41:56 +00:00
|
|
|
"encoding/json"
|
2026-05-12 15:38:01 +00:00
|
|
|
"errors"
|
|
|
|
|
"testing"
|
|
|
|
|
"time"
|
|
|
|
|
|
|
|
|
|
"github.com/stretchr/testify/assert"
|
|
|
|
|
"github.com/stretchr/testify/require"
|
|
|
|
|
|
|
|
|
|
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
|
|
|
|
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
|
|
|
|
sdk "github.com/Tencent/WeKnora/client"
|
|
|
|
|
)
|
|
|
|
|
|
2026-05-15 18:38:48 +00:00
|
|
|
// fakeDocsSearchSvc scripts paginated ListKnowledgeWithFilter responses.
|
|
|
|
|
// Pages are indexed 1-based; items keyed by page. The last-received filter
|
|
|
|
|
// is captured so tests can assert opts.Query was threaded as filter.Keyword.
|
2026-05-12 15:38:01 +00:00
|
|
|
type fakeDocsSearchSvc struct {
|
2026-05-15 18:38:48 +00:00
|
|
|
pages map[int][]sdk.Knowledge
|
|
|
|
|
total int64
|
|
|
|
|
err error
|
|
|
|
|
calls []int // page numbers requested, for assertions
|
|
|
|
|
lastFilter sdk.KnowledgeListFilter
|
2026-05-12 15:38:01 +00:00
|
|
|
}
|
|
|
|
|
|
2026-05-15 18:38:48 +00:00
|
|
|
func (f *fakeDocsSearchSvc) ListKnowledgeWithFilter(_ context.Context, kbID string, page, pageSize int, filter sdk.KnowledgeListFilter) ([]sdk.Knowledge, int64, error) {
|
2026-05-12 15:38:01 +00:00
|
|
|
f.calls = append(f.calls, page)
|
2026-05-15 18:38:48 +00:00
|
|
|
f.lastFilter = filter
|
2026-05-12 15:38:01 +00:00
|
|
|
if f.err != nil {
|
|
|
|
|
return nil, 0, f.err
|
|
|
|
|
}
|
|
|
|
|
return f.pages[page], f.total, nil
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
func TestDocsSearch_Substring(t *testing.T) {
|
|
|
|
|
out, _ := iostreams.SetForTest(t)
|
2026-05-15 18:38:48 +00:00
|
|
|
// Server applies the keyword filter pre-pagination; the fake simulates
|
|
|
|
|
// that by only returning the matching items (d1/d3, not d2).
|
2026-05-12 15:38:01 +00:00
|
|
|
svc := &fakeDocsSearchSvc{
|
|
|
|
|
pages: map[int][]sdk.Knowledge{
|
|
|
|
|
1: {
|
|
|
|
|
{ID: "d1", Title: "Q3 Forecast", FileName: "q3.pdf", UpdatedAt: mustTime(t, "2026-05-10T00:00:00Z")},
|
|
|
|
|
{ID: "d3", Title: "Q3 retro", FileName: "retro.pdf", UpdatedAt: mustTime(t, "2026-05-11T00:00:00Z")},
|
|
|
|
|
},
|
|
|
|
|
},
|
2026-05-15 18:38:48 +00:00
|
|
|
total: 2,
|
2026-05-12 15:38:01 +00:00
|
|
|
}
|
2026-05-21 10:43:18 +00:00
|
|
|
require.NoError(t, runDocsSearch(context.Background(), &DocsSearchOptions{Query: "q3", KBID: "kb1", Limit: 20, PageSize: docsPageSize, AllPages: true}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc))
|
2026-05-15 18:38:48 +00:00
|
|
|
assert.Equal(t, "q3", svc.lastFilter.Keyword, "query must be threaded as filter.Keyword")
|
2026-05-12 15:38:01 +00:00
|
|
|
got := out.String()
|
|
|
|
|
assert.Contains(t, got, "d1")
|
|
|
|
|
assert.Contains(t, got, "d3")
|
2026-05-15 18:38:48 +00:00
|
|
|
assert.NotContains(t, got, "d2")
|
2026-05-12 15:38:01 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
|
|
func TestDocsSearch_MatchesFileName(t *testing.T) {
|
|
|
|
|
out, _ := iostreams.SetForTest(t)
|
|
|
|
|
svc := &fakeDocsSearchSvc{
|
|
|
|
|
pages: map[int][]sdk.Knowledge{1: {{ID: "d1", Title: "Untitled", FileName: "report.pdf"}}},
|
|
|
|
|
total: 1,
|
|
|
|
|
}
|
2026-05-21 10:43:18 +00:00
|
|
|
require.NoError(t, runDocsSearch(context.Background(), &DocsSearchOptions{Query: "report", KBID: "kb1", Limit: 20, PageSize: docsPageSize, AllPages: true}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc))
|
2026-05-12 15:38:01 +00:00
|
|
|
assert.Contains(t, out.String(), "d1")
|
|
|
|
|
}
|
|
|
|
|
|
2026-05-15 18:38:48 +00:00
|
|
|
// TestDocsSearch_PaginatesUntilTotal walks server-paginated results.
|
|
|
|
|
// Server-side filter has already been applied, so every returned item
|
|
|
|
|
// is in the result set; the runner just walks pages until total exhausted
|
|
|
|
|
// or --limit hit. With limit > total matches, we expect 2 pages.
|
2026-05-12 15:38:01 +00:00
|
|
|
func TestDocsSearch_PaginatesUntilTotal(t *testing.T) {
|
|
|
|
|
out, _ := iostreams.SetForTest(t)
|
|
|
|
|
page1 := make([]sdk.Knowledge, docsPageSize)
|
|
|
|
|
for i := range page1 {
|
2026-05-15 18:38:48 +00:00
|
|
|
page1[i] = sdk.Knowledge{ID: "p1", Title: "needle"}
|
2026-05-12 15:38:01 +00:00
|
|
|
}
|
|
|
|
|
page2 := []sdk.Knowledge{{ID: "found", Title: "needle here"}}
|
|
|
|
|
svc := &fakeDocsSearchSvc{
|
|
|
|
|
pages: map[int][]sdk.Knowledge{1: page1, 2: page2},
|
|
|
|
|
total: int64(docsPageSize) + 1,
|
|
|
|
|
}
|
2026-05-21 10:43:18 +00:00
|
|
|
require.NoError(t, runDocsSearch(context.Background(), &DocsSearchOptions{Query: "needle", KBID: "kb1", Limit: docsPageSize + 1, PageSize: docsPageSize, AllPages: true}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc))
|
2026-05-12 15:38:01 +00:00
|
|
|
assert.Contains(t, out.String(), "found")
|
2026-05-15 18:38:48 +00:00
|
|
|
assert.Equal(t, []int{1, 2}, svc.calls, "must page past the first batch when more items reported")
|
2026-05-12 15:38:01 +00:00
|
|
|
}
|
|
|
|
|
|
refactor(cli): v0.3 cross-cutting cleanup
Cross-cutting findings surfaced by the branch-completion review.
Perf bug:
- Factory.Client closure was not memoized. Factory.ResolveKB internally
calls f.Client() to resolve --kb name → id, then the command's RunE
calls f.Client() again. Two SDK clients, two keyring reads, two
AuthRetryTransport allocations per name-resolved invocation, with
*independent* token state (a refresh in one was invisible to the
other). Switched to sync.Once like Secrets already does.
Silent bug bait:
- cmdutil.NormalizeHost docstring claimed CodeInputMissingFlag for the
empty case; code returned CodeInputInvalidArgument. Aligned doc to
code (present-but-empty is a bad value, not a missing flag).
Agent contract gaps:
- Five user-facing subcommands lacked SetAgentHelp: auth login /
logout / list / status and chat. Added concise strings with error-
code call-outs so agents can branch without parsing human strings.
Helper extraction (≥3 callers):
- text.KnowledgeDisplayName(fileName, title, id) — byte-identical
formatter that was in both cmd/doc/list.go and cmd/search/docs.go.
Takes fields directly so internal/text stays SDK-free.
- cmdutil.WrapHTTP(cause, fmt, args...) *Error — replaces the
`Wrapf(ClassifyHTTPError(err), err, ...)` pattern across 24 SDK
call sites. Sed-driven migration; off-pattern shapes in chat.go
(used streamErr) and cmdutil/kb.go (in-package) hand-edited.
Contract test gains a comment update: post-migration the dominant
pattern is WrapHTTP which the AST scanner skips entirely (only
NewError/Wrapf selectors inspected); ClassifyHTTPErrorOutputs()
bridge still covers the dynamic codes those paths can yield.
UX consistency:
- cmd/doc/list.go --page-size help now reads "Items per page
(1..1000)" matching cmd/session/list.go. The bounds validation
already enforced 1..1000; the help text was the last drift.
Comment-discipline sweep:
- Deleted the WHAT-only "*Options captures `weknora ...` flag state"
docstring across 23 files (context, kb, auth, doc, session, search,
chat, doctor, link). Where the line carried a real WHY clause
(kb/delete, doc/delete, session/delete, kb/edit), kept the WHY and
dropped only the leading WHAT phrase.
- Stripped third-party project-name attribution from inline comments
and one user-visible flag-help string across ~40 files in cli/cmd
and cli/internal (plus 4 test-file comments). Removed phrases like
"Mirrors `gh X`", "borrowed from lark-cli", "kubectl-style",
"gcloud `--project`", "Stripe pattern", and the embedded GitHub
URLs pointing at those projects. Behavioral descriptions and the
WHY behind each comment are preserved; only the upstream-name
attribution is gone. Inspiration / north-star references belong in
cli/AGENTS.md (the design doc) and commit messages, not scattered
through every file.
Triggered by an audit round that surfaced several false / fragile
parity claims (e.g. "Mirrors `gh repo edit`" — gh repo edit has no
--name flag; "matches gcloud `--project` id-or-name" — gcloud's
--project accepts ID only). Rather than fix them one by one, the
whole category of in-comment external-project references was
stripped uniformly.
2026-05-12 15:42:20 +00:00
|
|
|
func TestDocsSearch_StopsAtLimit(t *testing.T) {
|
2026-05-12 15:38:01 +00:00
|
|
|
_, _ = iostreams.SetForTest(t)
|
|
|
|
|
page1 := make([]sdk.Knowledge, 50)
|
|
|
|
|
for i := range page1 {
|
|
|
|
|
page1[i] = sdk.Knowledge{ID: "match", Title: "needle"}
|
|
|
|
|
}
|
|
|
|
|
svc := &fakeDocsSearchSvc{pages: map[int][]sdk.Knowledge{1: page1}, total: 1000}
|
2026-05-21 10:43:18 +00:00
|
|
|
require.NoError(t, runDocsSearch(context.Background(), &DocsSearchOptions{Query: "needle", KBID: "kb1", Limit: 3, PageSize: docsPageSize, AllPages: true}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc))
|
refactor(cli): v0.3 cross-cutting cleanup
Cross-cutting findings surfaced by the branch-completion review.
Perf bug:
- Factory.Client closure was not memoized. Factory.ResolveKB internally
calls f.Client() to resolve --kb name → id, then the command's RunE
calls f.Client() again. Two SDK clients, two keyring reads, two
AuthRetryTransport allocations per name-resolved invocation, with
*independent* token state (a refresh in one was invisible to the
other). Switched to sync.Once like Secrets already does.
Silent bug bait:
- cmdutil.NormalizeHost docstring claimed CodeInputMissingFlag for the
empty case; code returned CodeInputInvalidArgument. Aligned doc to
code (present-but-empty is a bad value, not a missing flag).
Agent contract gaps:
- Five user-facing subcommands lacked SetAgentHelp: auth login /
logout / list / status and chat. Added concise strings with error-
code call-outs so agents can branch without parsing human strings.
Helper extraction (≥3 callers):
- text.KnowledgeDisplayName(fileName, title, id) — byte-identical
formatter that was in both cmd/doc/list.go and cmd/search/docs.go.
Takes fields directly so internal/text stays SDK-free.
- cmdutil.WrapHTTP(cause, fmt, args...) *Error — replaces the
`Wrapf(ClassifyHTTPError(err), err, ...)` pattern across 24 SDK
call sites. Sed-driven migration; off-pattern shapes in chat.go
(used streamErr) and cmdutil/kb.go (in-package) hand-edited.
Contract test gains a comment update: post-migration the dominant
pattern is WrapHTTP which the AST scanner skips entirely (only
NewError/Wrapf selectors inspected); ClassifyHTTPErrorOutputs()
bridge still covers the dynamic codes those paths can yield.
UX consistency:
- cmd/doc/list.go --page-size help now reads "Items per page
(1..1000)" matching cmd/session/list.go. The bounds validation
already enforced 1..1000; the help text was the last drift.
Comment-discipline sweep:
- Deleted the WHAT-only "*Options captures `weknora ...` flag state"
docstring across 23 files (context, kb, auth, doc, session, search,
chat, doctor, link). Where the line carried a real WHY clause
(kb/delete, doc/delete, session/delete, kb/edit), kept the WHY and
dropped only the leading WHAT phrase.
- Stripped third-party project-name attribution from inline comments
and one user-visible flag-help string across ~40 files in cli/cmd
and cli/internal (plus 4 test-file comments). Removed phrases like
"Mirrors `gh X`", "borrowed from lark-cli", "kubectl-style",
"gcloud `--project`", "Stripe pattern", and the embedded GitHub
URLs pointing at those projects. Behavioral descriptions and the
WHY behind each comment are preserved; only the upstream-name
attribution is gone. Inspiration / north-star references belong in
cli/AGENTS.md (the design doc) and commit messages, not scattered
through every file.
Triggered by an audit round that surfaced several false / fragile
parity claims (e.g. "Mirrors `gh repo edit`" — gh repo edit has no
--name flag; "matches gcloud `--project` id-or-name" — gcloud's
--project accepts ID only). Rather than fix them one by one, the
whole category of in-comment external-project references was
stripped uniformly.
2026-05-12 15:42:20 +00:00
|
|
|
// Must not request page 2 because limit was hit mid-page.
|
2026-05-12 15:38:01 +00:00
|
|
|
assert.Equal(t, []int{1}, svc.calls)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
func TestDocsSearch_JSON(t *testing.T) {
|
|
|
|
|
out, _ := iostreams.SetForTest(t)
|
|
|
|
|
svc := &fakeDocsSearchSvc{
|
|
|
|
|
pages: map[int][]sdk.Knowledge{1: {{ID: "d1", Title: "match"}}},
|
|
|
|
|
total: 1,
|
|
|
|
|
}
|
2026-05-17 17:38:30 +00:00
|
|
|
require.NoError(t, runDocsSearch(context.Background(), &DocsSearchOptions{Query: "match", KBID: "kb1", Limit: 20, PageSize: docsPageSize, AllPages: true}, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc))
|
refactor(cli): drop --dry-run + introduce bare-JSON output path
Two intertwined mainstream-alignment moves bundled because they share
the migration target (every command's --json path):
1. Drop --dry-run entirely. Survey of comparable API-wrapper CLIs
(gh, aws, stripe, lark): none expose --dry-run. The mainstream that
does (kubectl/git/helm/ansible) operates on declarative manifests
or local state where the preview is materially different from the
executed action. WeKnora's CLI just echoed the same parameters
that would have gone on the wire — the preview added no real
signal over `--help` + reading the call site. Removes:
- root --dry-run persistent flag + cmdutil/dryrun.go
- DryRun fields + EmitDryRun calls in 12 write commands
- format.Envelope.DryRun field
- 8 corresponding *_test.go cases
- --dry-run mention from README.md and CHANGELOG.md
- "dry_run":false from 16 golden envelopes
2. Migrate every --json output to bare data:
- New format.WriteJSON / WriteJSONFiltered helpers
(cli/internal/format/bare.go) share filterArrayItems /
filterObjectKeys / writeJQ with the (still-live for now) envelope
filter helpers.
- Read commands (kb/doc/session list+view, search chunks/docs/
sessions/kb, auth list/status, agent list/view, context list,
doctor) emit bare arrays / objects on stdout.
- Write commands (kb create/edit/delete/pin/empty, doc upload/
upload_recursive/delete, session delete, auth login/logout/
refresh/token, link/unlink, context add/use/remove, agent
invoke, chat, api, version) emit bare result objects. Risk
classification dropped — the resource + exit code already
convey the action.
Per-command shape changes:
list / search → []T (was {ok, data:{items:[…]}})
view → T (was {ok, data:T, _meta:…})
create / edit → T
delete / pin / etc. → {id, …action result…}
doctor → {summary, checks}
api → {status, headers, body}
_meta dropped on the read path:
pagination (page/page_size/total/has_more) — agents iterate with
--all-pages or accept --limit (gh CLI parity);
kb_id / context echo — caller already knows what it asked for.
Acceptance contract goldens regenerated for the new bare shape.
Error envelope on stdout (PrintErrorEnvelope) stays live for now —
the envelope-infra deletion lands in the next commit.
2026-05-14 15:28:14 +00:00
|
|
|
got := out.String()
|
refactor(cli): envelope sweep — Emit shape, batch ops, MCP StructuredContent, api flag cleanup
Sweep every CLI output path through the v0.7 envelope contract.
FormatOptions.Emit signature changes to (w, data, meta *output.Meta)
so list commands surface meta.count / has_more in the wire envelope.
TTY indent decision plumbed via FormatOptions.TTY (set by
ResolveDefault). --format and --jq promoted to persistent root flags
so unknown-subcommand paths still reach the typed-envelope guard
(per-command registration would have rejected --format on unknown
commands as cobra-prose exit 2). WEKNORA_FORMAT env-var fallback
honored before TTY-resolved default. AddFormatFlag retained for the
per-command --jq field-hint Long-text addendum.
~55 production Emit call sites swept across cli/cmd/**: list paths
populate meta.count; mutation paths pass nil meta; envelope.profile
threaded via globalProfile. Existing JSON-shape tests migrated to
decode the envelope wrapper.
Multi-target batch operations get a unified shape via new helpers:
- output.BatchItem + output.WriteBatchEnvelope (§4.5 per-item ok
pattern; data:[{id, ok, result?|error?}], meta:{count, successes*,
failures*}; Successes/Failures *int so explicit zero survives
omitempty in all-fail case).
- cmdutil.RunBatch + cmdutil.EmitBatch + cmdutil.DeletedAtNow +
cmdutil.ClassifyContextErr collapse the three previously-duplicated
multi-delete pipelines (doc / chunk / session) into one call site
pattern. doc upload --recursive uses the same helpers with a per-
file resultFn. Summary error sets Silent:true so the stderr
envelope path doesn't duplicate the stdout batch detail (exit 1
preserved via Code → ExitCode).
ConfirmDestructive / ConfirmDestructiveBatch extended with action +
retryCmd parameters. Every destructive command (kb delete, kb edit,
doc delete, doc delete --all, agent delete, agent edit, session
delete, chunk delete, auth logout, api -X DELETE) now attaches
error.risk.{level:"destructive", action:"<noun.verb>"} +
error.retry_command on the exit-10 envelope. kb edit / agent edit
also gain the destructive guard wiring (CHANGELOG listed them as
gated but they were silently executing without -y).
MCP tool handlers' 31 error paths return CallToolResult with
IsError + Content text fallback + StructuredContent (envelope.error
shape via cmdutil.ErrorToDetail). Handler Out type changed from
typed *sdk.X to any so the go-sdk auto-marshal doesn't overwrite
StructuredContent with a zero-struct on error returns. Success path
manually populates CallToolResult.StructuredContent via successResult
helper.
weknora api cleanup:
- -d/--data flag removed; body via --input <file> or --input -
(stdin) only. Aligns with gh / curl convention.
- HTTP method whitelist removed; any non-empty method accepted.
- HTTP Retry-After header → cmdutil.Error.RetryAfterSeconds →
envelope.error.retry_after_seconds.
- runAPIPaginated raw-passthrough fallback now wraps response in
envelope so --paginate never emits bare JSON to stdout.
Test sweep: ~60 cmd/** tests migrated to decode envelope shape.
9 wire-contract goldens updated under cli/acceptance/testdata/wire/.
Spec: docs/superpowers/specs/2026-05-20-weknora-cli-v0.7-design.md §4 / §5
2026-05-21 10:41:56 +00:00
|
|
|
var env struct {
|
|
|
|
|
OK bool `json:"ok"`
|
|
|
|
|
Data []sdk.Knowledge `json:"data"`
|
|
|
|
|
}
|
|
|
|
|
require.NoError(t, json.Unmarshal([]byte(got), &env), "expected valid JSON envelope, got: %q", got)
|
|
|
|
|
assert.True(t, env.OK, "envelope.ok must be true")
|
refactor(cli): drop --dry-run + introduce bare-JSON output path
Two intertwined mainstream-alignment moves bundled because they share
the migration target (every command's --json path):
1. Drop --dry-run entirely. Survey of comparable API-wrapper CLIs
(gh, aws, stripe, lark): none expose --dry-run. The mainstream that
does (kubectl/git/helm/ansible) operates on declarative manifests
or local state where the preview is materially different from the
executed action. WeKnora's CLI just echoed the same parameters
that would have gone on the wire — the preview added no real
signal over `--help` + reading the call site. Removes:
- root --dry-run persistent flag + cmdutil/dryrun.go
- DryRun fields + EmitDryRun calls in 12 write commands
- format.Envelope.DryRun field
- 8 corresponding *_test.go cases
- --dry-run mention from README.md and CHANGELOG.md
- "dry_run":false from 16 golden envelopes
2. Migrate every --json output to bare data:
- New format.WriteJSON / WriteJSONFiltered helpers
(cli/internal/format/bare.go) share filterArrayItems /
filterObjectKeys / writeJQ with the (still-live for now) envelope
filter helpers.
- Read commands (kb/doc/session list+view, search chunks/docs/
sessions/kb, auth list/status, agent list/view, context list,
doctor) emit bare arrays / objects on stdout.
- Write commands (kb create/edit/delete/pin/empty, doc upload/
upload_recursive/delete, session delete, auth login/logout/
refresh/token, link/unlink, context add/use/remove, agent
invoke, chat, api, version) emit bare result objects. Risk
classification dropped — the resource + exit code already
convey the action.
Per-command shape changes:
list / search → []T (was {ok, data:{items:[…]}})
view → T (was {ok, data:T, _meta:…})
create / edit → T
delete / pin / etc. → {id, …action result…}
doctor → {summary, checks}
api → {status, headers, body}
_meta dropped on the read path:
pagination (page/page_size/total/has_more) — agents iterate with
--all-pages or accept --limit (gh CLI parity);
kb_id / context echo — caller already knows what it asked for.
Acceptance contract goldens regenerated for the new bare shape.
Error envelope on stdout (PrintErrorEnvelope) stays live for now —
the envelope-infra deletion lands in the next commit.
2026-05-14 15:28:14 +00:00
|
|
|
assert.Contains(t, got, `"id":"d1"`)
|
2026-05-12 15:38:01 +00:00
|
|
|
}
|
|
|
|
|
|
feat(cli)!: v0.10 reliability, agent-UX, and command-surface hardening
A hardening + finalization pass over the agent-first CLI: correctness fixes,
richer machine-readable signals, flag/naming consistency, and a symmetric
config surface. Pre-1.0, so it includes breaking renames.
Correctness:
- agent update: resolve/validate --model/--rerank-model (was storing a bogus
name verbatim, corrupting config.model_id).
- doctor: honor WEKNORA_HOST / WEKNORA_API_KEY (headless path no longer reports
"no host configured").
- session ask / MCP session_ask: text answer was empty on non-TTY — the agent
stream sets Done=true on an intermediate agent_query frame before the answer,
and AgentAccumulator treated the first Done as terminal. Terminate on the
`complete` event (new sdk.AgentResponseTypeComplete), not a per-frame Done.
- batch exit codes: any per-item failure collapses to operation.failed (exit 1),
including `doc upload --recursive` partial failures — a permanent per-file
failure (e.g. a duplicate) no longer surfaces as a retryable exit 7 an agent
would loop on; per-item typed errors stay in the envelope.
Agent-first signals & discovery:
- error.exit_code in the envelope (type + exit_code disambiguate the
input.invalid_argument exit-2-vs-5 split in one JSON read).
- meta.hint on empty content search and on draft doc create; doc wait fails fast
on a never-parsing draft instead of hanging to --timeout.
- retrieval-readiness is visible in the natural flow: kb status / kb check emit
retrieval_ready, and kb create hints the fix when no embedding model is bound
— an unconfigured KB no longer looks silently healthy.
- schema contract completeness: every leaf declares output + >=1 example
(drift-guarded); output strings match the meta actually emitted; chunk list
and search docs now emit meta.total_count (both previously dropped it).
- schema tolerates a quoted multi-word command label; zero-state auth — and
`link` with no profile — point at profile setup / the headless WEKNORA_KB_ID
path instead of looping on `auth login`.
- id-addressed reads tolerate a redundant --kb (doc view/wait, chunk list/view
accept and ignore it, declared in schema) so a carried-over --kb doesn't
exit 2; streaming commands warn that --jq does not apply to an NDJSON stream.
- keep JSON-always as the default; --jq hints spell out the .data path.
Consistency & gating:
- doc create: drop the deprecated --name alias (--title only; pre-1.0 break).
- chunk list --limit aligned to 1..10000; model list --limit/-L with
has_more/total_count; api write-gates -X PUT/PATCH (exit 10); skills install
expands a leading ~.
- docs corrected: search docs / doc list --keyword help is case-insensitive
(server does LOWER LIKE); AGENTS.md risk-action list (no phantom kb.init; add
model.update / kb.config.set) and batch example (failed item carries `error`);
session resume --message id comes from `message list`, not the stream.
- auth/profile ergonomics: env credentials are now first-class — `auth token`
prints the active WEKNORA_API_KEY / WEKNORA_TOKEN, and auth login/logout/refresh
give an env-aware message instead of looping on "run auth login". `auth logout`
clears credentials but keeps the profile registered (host preserved for
re-login); deleting a profile is `profile remove`'s job (clean logout/remove
separation, matching gh / lark).
Config surface (symmetric read/write, in-place model edits):
- kb config now returns a secret-free KBModelConfigView (was {}); `kb config`
reads, new `kb config set` writes; `kb init` removed (misnomer).
- kb create --chat-model: retrieval-ready in one step.
- model update: edit a model in place (id preserved, references survive) —
rotate --api-key-stdin, change base-url / display-name / etc.
- session continue-stream renamed to session resume.
Docs: AGENTS.md is the single wire-contract source; CHANGELOG slimmed; stale
kb-init / continue-stream references removed; skill wire-vocab guard extended.
AGENTS.md / weknora-shared SKILL document retrieval_ready (a KB needs an
embedding model to be searchable), that --jq does not apply to NDJSON
streams, and the env-credential-first auth path; the KB quickstart example
now creates a retrieval-ready KB.
2026-07-02 07:53:51 +00:00
|
|
|
// TestDocsSearch_JSON_EmitsTotalCount pins that search docs surfaces the
|
|
|
|
|
// server's full match total as meta.total_count (server-side keyword filter, so
|
|
|
|
|
// total is the real match count) — parity with doc/session/chunk list.
|
|
|
|
|
func TestDocsSearch_JSON_EmitsTotalCount(t *testing.T) {
|
|
|
|
|
out, _ := iostreams.SetForTest(t)
|
|
|
|
|
svc := &fakeDocsSearchSvc{
|
|
|
|
|
pages: map[int][]sdk.Knowledge{1: {{ID: "d1", Title: "match"}, {ID: "d2", Title: "match2"}}},
|
|
|
|
|
total: 9, // server reports 9 total matches; we display the first page
|
|
|
|
|
}
|
|
|
|
|
require.NoError(t, runDocsSearch(context.Background(),
|
|
|
|
|
&DocsSearchOptions{Query: "match", KBID: "kb1", Limit: 20, PageSize: docsPageSize, AllPages: false},
|
|
|
|
|
&cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc))
|
|
|
|
|
var env struct {
|
|
|
|
|
Meta struct {
|
|
|
|
|
Count *int `json:"count"`
|
|
|
|
|
TotalCount *int `json:"total_count"`
|
|
|
|
|
} `json:"meta"`
|
|
|
|
|
}
|
|
|
|
|
require.NoError(t, json.Unmarshal(out.Bytes(), &env))
|
|
|
|
|
require.NotNil(t, env.Meta.TotalCount, "search docs must emit meta.total_count")
|
|
|
|
|
assert.Equal(t, 9, *env.Meta.TotalCount)
|
|
|
|
|
}
|
|
|
|
|
|
2026-05-12 15:38:01 +00:00
|
|
|
func TestDocsSearch_NetworkError(t *testing.T) {
|
|
|
|
|
_, _ = iostreams.SetForTest(t)
|
|
|
|
|
svc := &fakeDocsSearchSvc{err: errors.New("HTTP error 404: kb not found")}
|
2026-05-21 10:43:18 +00:00
|
|
|
err := runDocsSearch(context.Background(), &DocsSearchOptions{Query: "x", KBID: "missing", Limit: 20, PageSize: docsPageSize, AllPages: true}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc)
|
2026-05-12 15:38:01 +00:00
|
|
|
require.Error(t, err)
|
|
|
|
|
var typed *cmdutil.Error
|
|
|
|
|
require.ErrorAs(t, err, &typed)
|
|
|
|
|
assert.Equal(t, cmdutil.CodeResourceNotFound, typed.Code)
|
|
|
|
|
}
|
|
|
|
|
|
2026-05-15 17:23:11 +00:00
|
|
|
// TestSearchDocs_AllPagesFlag_DefaultsTrue_WalksAllPages locks in that the
|
|
|
|
|
// historic walk-all-pages behavior is preserved when the new --all-pages flag
|
|
|
|
|
// is left at its default (true). Three pages of fake data, all match the
|
|
|
|
|
// substring; the run must request every page.
|
|
|
|
|
func TestSearchDocs_AllPagesFlag_DefaultsTrue_WalksAllPages(t *testing.T) {
|
|
|
|
|
_, _ = iostreams.SetForTest(t)
|
|
|
|
|
svc := &fakeDocsSearchSvc{
|
|
|
|
|
pages: map[int][]sdk.Knowledge{
|
|
|
|
|
1: {{ID: "d1", Title: "needle"}, {ID: "d2", Title: "needle"}},
|
|
|
|
|
2: {{ID: "d3", Title: "needle"}},
|
|
|
|
|
3: {},
|
|
|
|
|
},
|
|
|
|
|
total: 3,
|
|
|
|
|
}
|
|
|
|
|
opts := &DocsSearchOptions{Query: "needle", KBID: "kb_abc", Limit: 100, PageSize: 2, AllPages: true}
|
2026-05-17 17:38:30 +00:00
|
|
|
require.NoError(t, runDocsSearch(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc))
|
2026-05-15 17:23:11 +00:00
|
|
|
assert.GreaterOrEqual(t, len(svc.calls), 2, "must walk multi pages by default")
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// TestSearchDocs_AllPagesFalse_StopsAtFirstPage asserts that --all-pages=false
|
|
|
|
|
// caps server round-trips at one, even when the server reports far more
|
|
|
|
|
// items available. New v0.5 opt-out for the walk-all default.
|
|
|
|
|
func TestSearchDocs_AllPagesFalse_StopsAtFirstPage(t *testing.T) {
|
|
|
|
|
_, _ = iostreams.SetForTest(t)
|
|
|
|
|
svc := &fakeDocsSearchSvc{
|
|
|
|
|
pages: map[int][]sdk.Knowledge{1: {{ID: "d1", Title: "needle"}, {ID: "d2", Title: "needle"}}},
|
|
|
|
|
total: 100,
|
|
|
|
|
}
|
|
|
|
|
opts := &DocsSearchOptions{Query: "needle", KBID: "kb_abc", Limit: 100, PageSize: 2, AllPages: false}
|
2026-05-17 17:38:30 +00:00
|
|
|
require.NoError(t, runDocsSearch(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc))
|
2026-05-15 17:23:11 +00:00
|
|
|
assert.Len(t, svc.calls, 1, "must stop at first page when --all-pages=false")
|
|
|
|
|
}
|
|
|
|
|
|
2026-05-15 18:38:48 +00:00
|
|
|
// TestSearchDocs_KeywordPassedToFilter pins the v0.5 switch from client-side
|
|
|
|
|
// substring filtering to server-side ?keyword= via ListKnowledgeWithFilter.
|
|
|
|
|
// The query argument must arrive on the filter struct (not a discarded
|
|
|
|
|
// client-side variable).
|
|
|
|
|
func TestSearchDocs_KeywordPassedToFilter(t *testing.T) {
|
|
|
|
|
_, _ = iostreams.SetForTest(t)
|
|
|
|
|
svc := &fakeDocsSearchSvc{pages: map[int][]sdk.Knowledge{1: {{ID: "d1"}}}, total: 1}
|
2026-05-21 10:43:18 +00:00
|
|
|
require.NoError(t, runDocsSearch(context.Background(), &DocsSearchOptions{Query: "my-query", KBID: "kb1", Limit: 20, PageSize: docsPageSize, AllPages: true}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc))
|
2026-05-15 18:38:48 +00:00
|
|
|
assert.Equal(t, "my-query", svc.lastFilter.Keyword, "Query must be threaded as filter.Keyword on ListKnowledgeWithFilter")
|
|
|
|
|
// Other filter fields must be empty - search docs only forwards the keyword.
|
|
|
|
|
assert.Empty(t, svc.lastFilter.ParseStatus)
|
|
|
|
|
assert.Empty(t, svc.lastFilter.FileType)
|
|
|
|
|
assert.Empty(t, svc.lastFilter.Source)
|
|
|
|
|
assert.Empty(t, svc.lastFilter.TagID)
|
|
|
|
|
}
|
|
|
|
|
|
2026-05-15 17:23:11 +00:00
|
|
|
// TestSearchDocs_PageSizeBound asserts the 1..1000 range guard mirrors the
|
2026-05-17 17:38:30 +00:00
|
|
|
// session/doc list cap. Out-of-range values must produce
|
2026-05-15 17:23:11 +00:00
|
|
|
// input.invalid_argument and never reach the SDK.
|
|
|
|
|
func TestSearchDocs_PageSizeBound(t *testing.T) {
|
|
|
|
|
for _, ps := range []int{0, -1, 1001} {
|
2026-05-17 17:38:30 +00:00
|
|
|
err := runDocsSearch(context.Background(), &DocsSearchOptions{Query: "t", KBID: "k", Limit: 50, PageSize: ps}, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, &fakeDocsSearchSvc{})
|
2026-05-15 17:23:11 +00:00
|
|
|
require.Error(t, err)
|
|
|
|
|
var typed *cmdutil.Error
|
|
|
|
|
require.ErrorAs(t, err, &typed)
|
|
|
|
|
assert.Equal(t, cmdutil.CodeInputInvalidArgument, typed.Code, "page_size=%d", ps)
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
2026-05-12 15:38:01 +00:00
|
|
|
func mustTime(t *testing.T, s string) time.Time {
|
|
|
|
|
t.Helper()
|
|
|
|
|
v, err := time.Parse(time.RFC3339, s)
|
|
|
|
|
require.NoError(t, err)
|
|
|
|
|
return v
|
|
|
|
|
}
|
2026-05-29 12:06:30 +00:00
|
|
|
|
|
|
|
|
// TestDocsSearch_HasMore asserts the meta.has_more truncation signal: true when
|
|
|
|
|
// more matches than --limit exist (over-fetch detects it, data trimmed to
|
|
|
|
|
// --limit), absent/false when the full result set fits. Mirrors the list
|
|
|
|
|
// commands' contract so an agent can tell its search was capped.
|
|
|
|
|
func TestDocsSearch_HasMore(t *testing.T) {
|
|
|
|
|
page := make([]sdk.Knowledge, 10)
|
|
|
|
|
for i := range page {
|
|
|
|
|
page[i] = sdk.Knowledge{ID: "match", Title: "needle"}
|
|
|
|
|
}
|
|
|
|
|
type meta struct {
|
|
|
|
|
Count int `json:"count"`
|
|
|
|
|
HasMore bool `json:"has_more"`
|
|
|
|
|
}
|
|
|
|
|
parse := func(t *testing.T, s string) meta {
|
|
|
|
|
var env struct {
|
|
|
|
|
Meta meta `json:"meta"`
|
|
|
|
|
}
|
|
|
|
|
require.NoError(t, json.Unmarshal([]byte(s), &env), "got %q", s)
|
|
|
|
|
return env.Meta
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
t.Run("truncated -> has_more true, data trimmed", func(t *testing.T) {
|
|
|
|
|
out, _ := iostreams.SetForTest(t)
|
|
|
|
|
svc := &fakeDocsSearchSvc{pages: map[int][]sdk.Knowledge{1: page}, total: 10}
|
|
|
|
|
require.NoError(t, runDocsSearch(context.Background(),
|
|
|
|
|
&DocsSearchOptions{Query: "needle", KBID: "kb1", Limit: 3, PageSize: docsPageSize, AllPages: true},
|
|
|
|
|
&cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc))
|
|
|
|
|
m := parse(t, out.String())
|
|
|
|
|
assert.Equal(t, 3, m.Count, "data must be trimmed to --limit")
|
|
|
|
|
assert.True(t, m.HasMore, "has_more must be true when results exceed --limit")
|
|
|
|
|
})
|
|
|
|
|
|
|
|
|
|
t.Run("fits -> has_more false", func(t *testing.T) {
|
|
|
|
|
out, _ := iostreams.SetForTest(t)
|
|
|
|
|
svc := &fakeDocsSearchSvc{pages: map[int][]sdk.Knowledge{1: page[:2]}, total: 2}
|
|
|
|
|
require.NoError(t, runDocsSearch(context.Background(),
|
|
|
|
|
&DocsSearchOptions{Query: "needle", KBID: "kb1", Limit: 20, PageSize: docsPageSize, AllPages: true},
|
|
|
|
|
&cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc))
|
|
|
|
|
m := parse(t, out.String())
|
|
|
|
|
assert.Equal(t, 2, m.Count)
|
|
|
|
|
assert.False(t, m.HasMore, "has_more must be false/absent when results fit under --limit")
|
|
|
|
|
})
|
|
|
|
|
}
|
2026-05-29 12:06:53 +00:00
|
|
|
|
|
|
|
|
// TestNewCmdDocs_NoKBUsesResolver mirrors the chunks guard: `search docs`
|
|
|
|
|
// without --kb resolves the KB through the shared flag→env→project-link
|
|
|
|
|
// chain (Factory.ResolveKB), not cobra's required-flag check. With nothing
|
|
|
|
|
// to resolve it reports the typed local.kb_id_required, not a usage error.
|
|
|
|
|
func TestNewCmdDocs_NoKBUsesResolver(t *testing.T) {
|
|
|
|
|
iostreams.SetForTest(t)
|
|
|
|
|
t.Setenv("WEKNORA_KB_ID", "")
|
|
|
|
|
t.Chdir(t.TempDir())
|
|
|
|
|
cmd := NewCmdDocs(&cmdutil.Factory{
|
|
|
|
|
Client: func() (*sdk.Client, error) { return nil, errors.New("client should not be built") },
|
|
|
|
|
})
|
|
|
|
|
cmd.SetArgs([]string{"some query"}) // query but no --kb
|
|
|
|
|
cmd.SilenceErrors = true
|
|
|
|
|
cmd.SilenceUsage = true
|
|
|
|
|
err := cmd.Execute()
|
|
|
|
|
require.Error(t, err)
|
|
|
|
|
assert.NotContains(t, err.Error(), `required flag(s) "kb"`)
|
|
|
|
|
typed := cmdutil.AsError(err)
|
|
|
|
|
require.NotNil(t, typed)
|
|
|
|
|
assert.Equal(t, cmdutil.CodeKBIDRequired, typed.Code)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// TestNewCmdDocs_HonorsKBEnv proves the env fallback is wired for search docs.
|
|
|
|
|
func TestNewCmdDocs_HonorsKBEnv(t *testing.T) {
|
|
|
|
|
iostreams.SetForTest(t)
|
|
|
|
|
t.Setenv("WEKNORA_KB_ID", "kb_from_env")
|
|
|
|
|
cmd := NewCmdDocs(&cmdutil.Factory{
|
|
|
|
|
Client: func() (*sdk.Client, error) { return nil, errors.New("client boom") },
|
|
|
|
|
})
|
|
|
|
|
cmd.SetArgs([]string{"some query"}) // no --kb; env supplies it
|
|
|
|
|
cmd.SilenceErrors = true
|
|
|
|
|
cmd.SilenceUsage = true
|
|
|
|
|
err := cmd.Execute()
|
|
|
|
|
require.Error(t, err)
|
|
|
|
|
assert.NotContains(t, err.Error(), "kb is required")
|
|
|
|
|
assert.Contains(t, err.Error(), "client boom")
|
|
|
|
|
}
|