From 1b20b06f5e4e05f9e5353cc6c03c7390a2cf6daa Mon Sep 17 00:00:00 2001 From: nullkey Date: Thu, 14 May 2026 23:28:14 +0800 Subject: [PATCH] feat(cli): --json field-select, --jq, auth token, doc --from-url MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Output ergonomics: - `--json` accepts a comma-separated field list (gh-parity); selects named keys from the per-command payload. Bare `--json` keeps the full shape. - `--jq ` evaluates a gojq expression over the JSON; pairs with `--json field-list` so projection runs before jq. - `--version` is a global cobra flag in addition to the `version` subcommand; both render the same line. - Per-command `--help` now renders the available JSON field list under "JSON fields available via `--json id,name,...`" (field-discovery parity with gh / kubectl `-o jsonpath`). New commands: - `auth token` — print the active context's credential to stdout for shell command substitution (`WEKNORA_TOKEN=$(weknora auth token)`). Default: raw secret, no trailing newline. `--json` emits `{token, mode, context}`. - `doc upload --from-url ` — ingest a remote URL via the SDK `CreateKnowledgeFromURL`. `--name` forwarded as `FileName` so the server's known-extension heuristic upgrades crawl-mode to file-download-mode where appropriate. Includes the simplify post-review polish pass (field-filter unit tests, --json/--jq compose check, agent_help copy fixes). --- .../testdata/envelopes/search.success.json | 2 +- cli/cmd/api/api.go | 26 ++- cli/cmd/api/api_test.go | 16 +- cli/cmd/auth/auth.go | 29 ++- cli/cmd/auth/auth_test.go | 7 +- cli/cmd/auth/list.go | 44 ++-- cli/cmd/auth/list_test.go | 28 +-- cli/cmd/auth/login.go | 53 +++-- cli/cmd/auth/login_test.go | 10 +- cli/cmd/auth/logout.go | 27 ++- cli/cmd/auth/logout_test.go | 12 +- cli/cmd/auth/refresh.go | 24 ++- cli/cmd/auth/refresh_test.go | 16 +- cli/cmd/auth/status.go | 29 ++- cli/cmd/auth/status_test.go | 10 +- cli/cmd/auth/token.go | 129 +++++++++++ cli/cmd/auth/token_test.go | 203 ++++++++++++++++++ cli/cmd/chat/chat.go | 59 +++-- cli/cmd/chat/chat_test.go | 30 +-- cli/cmd/context/add.go | 35 +-- cli/cmd/context/add_test.go | 10 +- cli/cmd/context/list.go | 26 ++- cli/cmd/context/list_test.go | 7 +- cli/cmd/context/remove.go | 34 +-- cli/cmd/context/remove_test.go | 12 +- cli/cmd/doc/delete.go | 29 ++- cli/cmd/doc/delete_test.go | 18 +- cli/cmd/doc/list.go | 26 ++- cli/cmd/doc/list_test.go | 16 +- cli/cmd/doc/upload.go | 171 +++++++++++---- cli/cmd/doc/upload_recursive.go | 22 +- cli/cmd/doc/upload_recursive_test.go | 28 ++- cli/cmd/doc/upload_test.go | 133 +++++++++++- cli/cmd/doc/view.go | 26 ++- cli/cmd/doc/view_test.go | 10 +- cli/cmd/doctor/doctor.go | 26 ++- cli/cmd/doctor/doctor_test.go | 14 +- cli/cmd/kb/create.go | 32 ++- cli/cmd/kb/create_test.go | 16 +- cli/cmd/kb/delete.go | 29 ++- cli/cmd/kb/delete_test.go | 24 +-- cli/cmd/kb/edit.go | 31 ++- cli/cmd/kb/edit_test.go | 14 +- cli/cmd/kb/empty.go | 31 +-- cli/cmd/kb/empty_test.go | 10 +- cli/cmd/kb/list.go | 34 ++- cli/cmd/kb/list_test.go | 56 ++++- cli/cmd/kb/pin.go | 30 ++- cli/cmd/kb/pin_test.go | 16 +- cli/cmd/kb/view.go | 28 ++- cli/cmd/kb/view_test.go | 6 +- cli/cmd/link/link.go | 28 ++- cli/cmd/link/link_test.go | 10 +- cli/cmd/link/unlink.go | 27 ++- cli/cmd/link/unlink_test.go | 8 +- cli/cmd/root.go | 57 ++--- cli/cmd/root_test.go | 9 +- cli/cmd/search/chunks.go | 33 ++- cli/cmd/search/chunks_test.go | 24 +-- cli/cmd/search/docs.go | 45 +++- cli/cmd/search/docs_test.go | 12 +- cli/cmd/search/kb.go | 42 +++- cli/cmd/search/kb_test.go | 16 +- cli/cmd/search/sessions.go | 37 +++- cli/cmd/search/sessions_test.go | 8 +- cli/cmd/session/delete.go | 35 +-- cli/cmd/session/delete_test.go | 12 +- cli/cmd/session/list.go | 25 ++- cli/cmd/session/list_test.go | 16 +- cli/cmd/session/view.go | 26 ++- cli/cmd/session/view_test.go | 8 +- cli/go.mod | 9 +- cli/go.sum | 14 +- cli/internal/cmdutil/errors.go | 2 +- cli/internal/cmdutil/exit.go | 2 +- cli/internal/cmdutil/factory.go | 13 +- cli/internal/cmdutil/host.go | 24 ++- cli/internal/cmdutil/jsonflags.go | 109 ++++++++++ cli/internal/cmdutil/jsonflags_test.go | 190 ++++++++++++++++ cli/internal/format/filter.go | 202 +++++++++++++++++ cli/internal/format/filter_test.go | 196 +++++++++++++++++ 81 files changed, 2351 insertions(+), 642 deletions(-) create mode 100644 cli/cmd/auth/token.go create mode 100644 cli/cmd/auth/token_test.go create mode 100644 cli/internal/cmdutil/jsonflags.go create mode 100644 cli/internal/cmdutil/jsonflags_test.go create mode 100644 cli/internal/format/filter.go create mode 100644 cli/internal/format/filter_test.go diff --git a/cli/acceptance/testdata/envelopes/search.success.json b/cli/acceptance/testdata/envelopes/search.success.json index 298c89c9..b63d909d 100644 --- a/cli/acceptance/testdata/envelopes/search.success.json +++ b/cli/acceptance/testdata/envelopes/search.success.json @@ -1 +1 @@ -{"ok":true,"data":[{"id":"chunk-1","content":"first chunk content","knowledge_id":"doc-1","chunk_index":0,"knowledge_title":"Doc 1","start_at":0,"end_at":0,"seq":0,"score":0.92,"match_type":0,"chunk_type":"","image_info":"","metadata":null,"knowledge_filename":"","knowledge_source":"","knowledge_channel":""},{"id":"chunk-2","content":"second chunk content","knowledge_id":"doc-2","chunk_index":1,"knowledge_title":"Doc 2","start_at":0,"end_at":0,"seq":0,"score":0.81,"match_type":1,"chunk_type":"","image_info":"","metadata":null,"knowledge_filename":"","knowledge_source":"","knowledge_channel":""}],"_meta":{"kb_id":"11111111-1111-4111-8111-111111111111"},"dry_run":false} +{"ok":true,"data":{"items":[{"id":"chunk-1","content":"first chunk content","knowledge_id":"doc-1","chunk_index":0,"knowledge_title":"Doc 1","start_at":0,"end_at":0,"seq":0,"score":0.92,"match_type":0,"chunk_type":"","image_info":"","metadata":null,"knowledge_filename":"","knowledge_source":"","knowledge_channel":""},{"id":"chunk-2","content":"second chunk content","knowledge_id":"doc-2","chunk_index":1,"knowledge_title":"Doc 2","start_at":0,"end_at":0,"seq":0,"score":0.81,"match_type":1,"chunk_type":"","image_info":"","metadata":null,"knowledge_filename":"","knowledge_source":"","knowledge_channel":""}]},"_meta":{"kb_id":"11111111-1111-4111-8111-111111111111"},"dry_run":false} diff --git a/cli/cmd/api/api.go b/cli/cmd/api/api.go index 71e8b35a..1132d3ee 100644 --- a/cli/cmd/api/api.go +++ b/cli/cmd/api/api.go @@ -25,11 +25,15 @@ import ( sdk "github.com/Tencent/WeKnora/client" ) +// apiFields is intentionally a marker — api wraps arbitrary HTTP responses +// whose schema the CLI doesn't know, so the `--json id,name` field-filter +// is a no-op here. The marker shows up in --help so users can tell. +var apiFields = []string{""} + type Options struct { Method string Data string Input string // --input: file path, "-" for stdin - JSONOut bool DryRun bool Yes bool StdinReader io.Reader // overridden by tests; defaults to iostreams.IO.In @@ -66,31 +70,35 @@ Examples: RunE: func(c *cobra.Command, args []string) error { opts.DryRun = cmdutil.IsDryRun(c) opts.Yes, _ = c.Flags().GetBool("yes") + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } method := resolveMethod(opts) // Escape-hatch DELETE through `weknora api` is just as destructive // as `weknora kb delete` — exit-10 protocol must apply (AGENTS.md). // Dry-run is read-only preview, so it skips confirmation. if !opts.DryRun && method == http.MethodDelete { - if err := cmdutil.ConfirmDestructive(f.Prompter(), opts.Yes, opts.JSONOut, "endpoint", args[0]); err != nil { + if err := cmdutil.ConfirmDestructive(f.Prompter(), opts.Yes, jopts.Enabled(), "endpoint", args[0]); err != nil { return err } } if opts.DryRun { - return runAPI(c.Context(), opts, nil, method, args[0]) + return runAPI(c.Context(), opts, jopts, nil, method, args[0]) } cli, err := f.Client() if err != nil { return err } - return runAPI(c.Context(), opts, cli, method, args[0]) + return runAPI(c.Context(), opts, jopts, cli, method, args[0]) }, } cmd.Flags().StringVarP(&opts.Method, "method", "X", "", "HTTP method (default: GET, or POST when a body is supplied)") cmd.Flags().StringVarP(&opts.Data, "data", "d", "", "Request body as raw string (e.g. JSON)") cmd.Flags().StringVar(&opts.Input, "input", "", "Read request body from file (use `-` for stdin)") - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Wrap response in JSON envelope (status/headers/body)") + cmdutil.AddJSONFlags(cmd, apiFields) cmd.MarkFlagsMutuallyExclusive("data", "input") - agent.SetAgentHelp(cmd, "Raw HTTP passthrough to the WeKnora server. Use when no typed command exists for the endpoint. Headers (auth / tenant / request-id) are injected from the active context. Without --json the response body streams to stdout verbatim. With --json: data is {status, headers, body} where body is the parsed JSON if response is JSON, else the raw string. Non-2xx responses surface as a typed error (4xx → input.invalid_argument / auth.* / resource.not_found per ClassifyHTTPStatus; 5xx → server.error / network.error). DELETE through `weknora api` triggers exit-10 confirm just like `weknora kb delete`. Mutual exclusion: --data and --input cannot both be set (input.invalid_argument).") + agent.SetAgentHelp(cmd, "Raw HTTP passthrough to the WeKnora server. Use when no typed command exists for the endpoint. Headers (auth / tenant / request-id) are injected from the active context. Without --json the response body streams to stdout verbatim. With --json: data is {status, headers, body} where body is the parsed JSON if response is JSON, else the raw string. NOTE: --json field filtering (`--json id,name`) is NOT supported for api passthrough — the response shape varies per endpoint and the CLI cannot pre-project unknown schemas; any field list is ignored. Use --jq for arbitrary reshape. Non-2xx responses surface as a typed error (4xx → input.invalid_argument / auth.* / resource.not_found per ClassifyHTTPStatus; 5xx → server.error / network.error). DELETE through `weknora api` triggers exit-10 confirm just like `weknora kb delete`. Mutual exclusion: --data and --input cannot both be set (input.invalid_argument).") return cmd } @@ -133,7 +141,7 @@ func resolveMethod(opts *Options) string { // caller is responsible for resolving the method (defaults / auto-POST) // and uppercasing it; runAPI guards against unsupported values like // `-X PATCH-INVALID` reaching the wire. -func runAPI(ctx context.Context, opts *Options, svc Service, method, path string) error { +func runAPI(ctx context.Context, opts *Options, jopts *cmdutil.JSONOptions, svc Service, method, path string) error { switch method { case http.MethodGet, http.MethodPost, http.MethodPut, http.MethodPatch, http.MethodDelete, http.MethodHead: @@ -169,7 +177,7 @@ func runAPI(ctx context.Context, opts *Options, svc Service, method, path string if body != nil { preview["body"] = body } - return cmdutil.EmitDryRun(opts.JSONOut, preview, nil, + return cmdutil.EmitDryRun(jopts.Enabled(), preview, nil, &format.Risk{Level: level, Action: fmt.Sprintf("%s %s", method, path)}) } @@ -192,7 +200,7 @@ func runAPI(ctx context.Context, opts *Options, svc Service, method, path string } out := iostreams.IO.Out - if opts.JSONOut { + if jopts.Enabled() { // Best-effort decode: if response body is valid JSON, surface the // parsed structure under .data.body so envelope consumers can drill // in; otherwise fall back to the raw string. diff --git a/cli/cmd/api/api_test.go b/cli/cmd/api/api_test.go index 7e16afe9..82a5f060 100644 --- a/cli/cmd/api/api_test.go +++ b/cli/cmd/api/api_test.go @@ -40,7 +40,7 @@ func TestAPI_GetSuccess(t *testing.T) { }) defer stop() - if err := runAPI(context.Background(), &Options{}, cli, "GET", "/api/v1/foo"); err != nil { + if err := runAPI(context.Background(), &Options{}, nil, cli, "GET", "/api/v1/foo"); err != nil { t.Fatalf("runAPI: %v", err) } got := out.String() @@ -62,7 +62,7 @@ func TestAPI_GetSuccess_JSON(t *testing.T) { }) defer stop() - if err := runAPI(context.Background(), &Options{JSONOut: true}, cli, "GET", "/api/v1/foo"); err != nil { + if err := runAPI(context.Background(), &Options{}, &cmdutil.JSONOptions{}, cli, "GET", "/api/v1/foo"); err != nil { t.Fatalf("runAPI: %v", err) } var env struct { @@ -104,7 +104,7 @@ func TestAPI_PostWithData(t *testing.T) { defer stop() opts := &Options{Data: `{"name":"foo"}`} - if err := runAPI(context.Background(), opts, cli, "POST", "/api/v1/things"); err != nil { + if err := runAPI(context.Background(), opts, nil, cli, "POST", "/api/v1/things"); err != nil { t.Fatalf("runAPI: %v", err) } if seenMethod != http.MethodPost || seenPath != "/api/v1/things" { @@ -133,7 +133,7 @@ func TestAPI_InputFile(t *testing.T) { defer stop() opts := &Options{Input: tmp} - if err := runAPI(context.Background(), opts, cli, "POST", "/api/v1/x"); err != nil { + if err := runAPI(context.Background(), opts, nil, cli, "POST", "/api/v1/x"); err != nil { t.Fatalf("runAPI: %v", err) } if string(seenBody) != payload { @@ -154,7 +154,7 @@ func TestAPI_InputDash_Stdin(t *testing.T) { payload := `{"k":"from-stdin"}` opts := &Options{Input: "-", StdinReader: strings.NewReader(payload)} - if err := runAPI(context.Background(), opts, cli, "POST", "/api/v1/x"); err != nil { + if err := runAPI(context.Background(), opts, nil, cli, "POST", "/api/v1/x"); err != nil { t.Fatalf("runAPI: %v", err) } if string(seenBody) != payload { @@ -170,7 +170,7 @@ func TestAPI_NotFound(t *testing.T) { }) defer stop() - err := runAPI(context.Background(), &Options{}, cli, "GET", "/api/v1/missing") + err := runAPI(context.Background(), &Options{}, nil, cli, "GET", "/api/v1/missing") if err == nil { t.Fatal("expected error for 404") } @@ -182,7 +182,7 @@ func TestAPI_NotFound(t *testing.T) { func TestAPI_InvalidMethod(t *testing.T) { _, _ = iostreams.SetForTest(t) // No server needed: validation should fail before dispatch. - err := runAPI(context.Background(), &Options{}, nil, "FOO", "/api/v1/things") + err := runAPI(context.Background(), &Options{}, nil, nil, "FOO", "/api/v1/things") if err == nil { t.Fatal("expected error for unsupported method") } @@ -194,7 +194,7 @@ func TestAPI_InvalidMethod(t *testing.T) { func TestAPI_PathWithoutSlash(t *testing.T) { _, _ = iostreams.SetForTest(t) - err := runAPI(context.Background(), &Options{}, nil, "GET", "api/v1/things") + err := runAPI(context.Background(), &Options{}, nil, nil, "GET", "api/v1/things") if err == nil { t.Fatal("expected error for missing leading slash") } diff --git a/cli/cmd/auth/auth.go b/cli/cmd/auth/auth.go index 67a4efa8..4b2e149e 100644 --- a/cli/cmd/auth/auth.go +++ b/cli/cmd/auth/auth.go @@ -1,5 +1,5 @@ // Package auth holds the cobra commands for authentication -// (login / logout / list / refresh / status). +// (login / logout / list / refresh / status / token). package auth import ( @@ -8,6 +8,32 @@ import ( "github.com/Tencent/WeKnora/cli/internal/cmdutil" ) +// Credential-mode tokens used in the JSON envelope of auth list / login / +// status / token. The string names describe the HTTP credential type rather +// than the login flow (e.g. JWT → bearer regardless of whether it was +// obtained via password or refresh) so an agent can branch directly on the +// header to construct: `Authorization: Bearer ` (ModeBearer) or +// `X-API-Key: ` (ModeAPIKey). +const ( + ModeBearer = "bearer" + ModeAPIKey = "api-key" + ModeUnknown = "unknown" +) + +// modeFromRefs maps the per-context TokenRef / APIKeyRef presence to a +// canonical credential-mode token. Bearer wins when both are present — +// matches the precedence in cmdutil.buildClient. +func modeFromRefs(apiKeyRef, tokenRef string) string { + switch { + case tokenRef != "": + return ModeBearer + case apiKeyRef != "": + return ModeAPIKey + default: + return ModeUnknown + } +} + // NewCmdAuth builds the `weknora auth` command tree and registers its // subcommands. Called from cli/cmd/root.go. func NewCmdAuth(f *cmdutil.Factory) *cobra.Command { @@ -27,5 +53,6 @@ func NewCmdAuth(f *cmdutil.Factory) *cobra.Command { cmd.AddCommand(NewCmdList(f)) cmd.AddCommand(NewCmdRefresh(f)) cmd.AddCommand(NewCmdStatus(f)) + cmd.AddCommand(NewCmdToken(f)) return cmd } diff --git a/cli/cmd/auth/auth_test.go b/cli/cmd/auth/auth_test.go index e883dc48..bbbeafc4 100644 --- a/cli/cmd/auth/auth_test.go +++ b/cli/cmd/auth/auth_test.go @@ -46,7 +46,7 @@ func TestNewCmdLogin_InvokesRunF(t *testing.T) { f := &cmdutil.Factory{ Secrets: func() (secrets.Store, error) { return store, nil }, } - cmd := NewCmdLogin(f, func(_ context.Context, opts *LoginOptions, _ *cmdutil.Factory, _ LoginService) error { + cmd := NewCmdLogin(f, func(_ context.Context, opts *LoginOptions, _ *cmdutil.JSONOptions, _ *cmdutil.Factory, _ LoginService) error { called = true assert.Equal(t, "https://kb.example.com", opts.Host) assert.True(t, opts.WithToken) @@ -76,7 +76,7 @@ func TestPersistAPIKey_WritesContext(t *testing.T) { Context: "ci", APIKey: "sk-zzz", } - require.NoError(t, persistAPIKey(opts, f)) + require.NoError(t, persistAPIKey(opts, &cmdutil.JSONOptions{}, f)) v, _ := store.Get("ci", "api_key") assert.Equal(t, "sk-zzz", v) cfg, _ := f.Config() @@ -98,14 +98,13 @@ func TestPersistJWT_StoresBothTokens(t *testing.T) { opts := &LoginOptions{ Host: "https://x", Context: "p", - JSONOut: true, } resp := &sdk.LoginResponse{ Token: "jwt-acc", RefreshToken: "jwt-ref", User: &sdk.AuthUser{Email: "a@b.c", TenantID: 7}, } - require.NoError(t, persistJWT(opts, f, resp)) + require.NoError(t, persistJWT(opts, &cmdutil.JSONOptions{}, f, resp)) a, _ := store.Get("p", "access") r, _ := store.Get("p", "refresh") assert.Equal(t, "jwt-acc", a) diff --git a/cli/cmd/auth/list.go b/cli/cmd/auth/list.go index d5a74ea9..a307eaaa 100644 --- a/cli/cmd/auth/list.go +++ b/cli/cmd/auth/list.go @@ -13,15 +13,19 @@ import ( "github.com/Tencent/WeKnora/cli/internal/iostreams" ) -type ListOptions struct { - JSONOut bool +type ListOptions struct{} + +// authListFields enumerates the fields surfaced for `--json` discovery on +// `auth list`. Each entry is a per-context summary row. +var authListFields = []string{ + "name", "host", "user", "mode", "current", } type listEntry struct { Name string `json:"name"` Host string `json:"host"` User string `json:"user,omitempty"` - Mode string `json:"mode"` // "api-key" / "password" / "unknown" + Mode string `json:"mode"` // ModeBearer / ModeAPIKey / ModeUnknown Current bool `json:"current"` } @@ -29,21 +33,24 @@ type listEntry struct { // row per registered context, marking the active one. Reads only // ~/.config/weknora/config.yaml — no network, no keyring touch. func NewCmdList(f *cmdutil.Factory) *cobra.Command { - opts := &ListOptions{} cmd := &cobra.Command{ Use: "list", Short: "List configured authentication contexts", Args: cobra.NoArgs, RunE: func(c *cobra.Command, _ []string) error { - return runList(opts, f) + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } + return runList(jopts, f) }, } - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, authListFields) agent.SetAgentHelp(cmd, "Lists configured auth contexts (name/host/user/mode/current). Read-only, no network, no keyring access. Use to confirm context names before --context or `auth login --name`.") return cmd } -func runList(opts *ListOptions, f *cmdutil.Factory) error { +func runList(jopts *cmdutil.JSONOptions, f *cmdutil.Factory) error { cfg, err := f.Config() if err != nil { return err @@ -54,15 +61,16 @@ func runList(opts *ListOptions, f *cmdutil.Factory) error { Name: name, Host: c.Host, User: c.User, - Mode: inferMode(c.APIKeyRef, c.TokenRef), + Mode: modeFromRefs(c.APIKeyRef, c.TokenRef), Current: name == cfg.CurrentContext, }) } sort.Slice(entries, func(i, j int) bool { return entries[i].Name < entries[j].Name }) - if opts.JSONOut { - return cmdutil.NewJSONExporter().Write(iostreams.IO.Out, - format.Success(entries, &format.Meta{Context: cfg.CurrentContext})) + if jopts.Enabled() { + return format.WriteEnvelopeFiltered(iostreams.IO.Out, + format.Success(entries, &format.Meta{Context: cfg.CurrentContext}), + jopts.Fields, jopts.JQ) } if len(entries) == 0 { fmt.Fprintln(iostreams.IO.Out, "No contexts configured. Run `weknora auth login` to create one.") @@ -80,17 +88,3 @@ func runList(opts *ListOptions, f *cmdutil.Factory) error { return tw.Flush() } -// inferMode reports which credential shape the context was logged in with. -// A context with both refs set (which shouldn't happen with the current -// login flow but might appear in hand-edited configs) is treated as -// password — JWT wins because it's the more capable mode. -func inferMode(apiKeyRef, tokenRef string) string { - switch { - case tokenRef != "": - return "password" - case apiKeyRef != "": - return "api-key" - default: - return "unknown" - } -} diff --git a/cli/cmd/auth/list_test.go b/cli/cmd/auth/list_test.go index 3caf671c..7a8d24cc 100644 --- a/cli/cmd/auth/list_test.go +++ b/cli/cmd/auth/list_test.go @@ -28,15 +28,15 @@ func TestList_HumanRender(t *testing.T) { "staging": {Host: "https://staging", APIKeyRef: "keychain://staging/api_key"}, }, } - require.NoError(t, runList(&ListOptions{}, newListFactory(cfg))) + require.NoError(t, runList(nil, newListFactory(cfg))) got := out.String() // One row per context, current marked with `*`. assert.Contains(t, got, "* prod") assert.Contains(t, got, " staging") // Mode column. - assert.Contains(t, got, "password") - assert.Contains(t, got, "api-key") + assert.Contains(t, got, ModeBearer) + assert.Contains(t, got, ModeAPIKey) // Sorted alphabetically — prod after staging? No: "prod" < "staging". assert.Less(t, strings.Index(got, "prod"), strings.Index(got, "staging"), "contexts should render sorted by name") @@ -44,7 +44,7 @@ func TestList_HumanRender(t *testing.T) { func TestList_Empty(t *testing.T) { out, _ := iostreams.SetForTest(t) - require.NoError(t, runList(&ListOptions{}, newListFactory(&config.Config{}))) + require.NoError(t, runList(nil, newListFactory(&config.Config{}))) assert.Contains(t, out.String(), "No contexts configured") } @@ -57,7 +57,7 @@ func TestList_JSONEnvelope(t *testing.T) { "staging": {Host: "https://staging", APIKeyRef: "key"}, }, } - require.NoError(t, runList(&ListOptions{JSONOut: true}, newListFactory(cfg))) + require.NoError(t, runList(&cmdutil.JSONOptions{}, newListFactory(cfg))) var env struct { OK bool `json:"ok"` @@ -73,17 +73,17 @@ func TestList_JSONEnvelope(t *testing.T) { // Sorted: prod < staging. assert.Equal(t, "prod", env.Data[0].Name) assert.True(t, env.Data[0].Current) - assert.Equal(t, "password", env.Data[0].Mode) + assert.Equal(t, ModeBearer, env.Data[0].Mode) assert.Equal(t, "staging", env.Data[1].Name) assert.False(t, env.Data[1].Current) - assert.Equal(t, "api-key", env.Data[1].Mode) + assert.Equal(t, ModeAPIKey, env.Data[1].Mode) } -func TestList_InferModeUnknown(t *testing.T) { - // Hand-edited config with neither ref set — surface "unknown" rather than - // pretending the context is a valid login. - assert.Equal(t, "unknown", inferMode("", "")) - assert.Equal(t, "password", inferMode("", "tok")) - assert.Equal(t, "api-key", inferMode("key", "")) - assert.Equal(t, "password", inferMode("key", "tok"), "JWT wins when both set") +func TestModeFromRefs(t *testing.T) { + // Hand-edited config with neither ref set — surface "unknown" rather + // than pretending the context is a valid login. + assert.Equal(t, ModeUnknown, modeFromRefs("", "")) + assert.Equal(t, ModeBearer, modeFromRefs("", "tok")) + assert.Equal(t, ModeAPIKey, modeFromRefs("key", "")) + assert.Equal(t, ModeBearer, modeFromRefs("key", "tok"), "JWT wins when both set") } diff --git a/cli/cmd/auth/login.go b/cli/cmd/auth/login.go index dd15baeb..3fdcf6a8 100644 --- a/cli/cmd/auth/login.go +++ b/cli/cmd/auth/login.go @@ -16,6 +16,14 @@ import ( sdk "github.com/Tencent/WeKnora/client" ) +// authLoginFields enumerates the fields surfaced for `--json` discovery on +// `auth login`. The post-login summary has no token values — they stay in the +// keyring; agents who need to verify the credential should re-run +// `auth status`. +var authLoginFields = []string{ + "context", "host", "mode", "user", "tenant_id", +} + // LoginOptions is the configuration captured from flags + prompts. type LoginOptions struct { Host string // --host @@ -24,7 +32,6 @@ type LoginOptions struct { APIKey string // populated by --with-token from stdin Email string Password string - JSONOut bool StdinReader io.Reader // override for tests } @@ -37,7 +44,7 @@ type LoginService interface { // NewCmdLogin builds the `weknora auth login` command. runF is the testable // entrypoint (left nil for production; see cli/cmd/auth/login_test.go). -func NewCmdLogin(f *cmdutil.Factory, runF func(context.Context, *LoginOptions, *cmdutil.Factory, LoginService) error) *cobra.Command { +func NewCmdLogin(f *cmdutil.Factory, runF func(context.Context, *LoginOptions, *cmdutil.JSONOptions, *cmdutil.Factory, LoginService) error) *cobra.Command { opts := &LoginOptions{} cmd := &cobra.Command{ Use: "login", @@ -49,6 +56,10 @@ Credentials are persisted to the OS keyring when available; otherwise to a the current_context in ~/.config/weknora/config.yaml.`, Args: cobra.NoArgs, RunE: func(c *cobra.Command, args []string) error { + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } run := runF if run == nil { run = runLogin @@ -57,13 +68,13 @@ the current_context in ~/.config/weknora/config.yaml.`, if opts.StdinReader == nil { opts.StdinReader = iostreams.IO.In } - return run(c.Context(), opts, f, svc) + return run(c.Context(), opts, jopts, f, svc) }, } cmd.Flags().StringVar(&opts.Host, "host", "", "WeKnora server URL, e.g. https://kb.example.com") cmd.Flags().StringVar(&opts.Context, "name", "default", "Context name to register in config.yaml") cmd.Flags().BoolVar(&opts.WithToken, "with-token", false, "Read an API key from stdin instead of prompting for password") - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, authLoginFields) cmdutil.MustRequireFlag(cmd, "host") agent.SetAgentHelp(cmd, "Authenticates and stores credentials. --with-token reads an API key from stdin (no password prompt, agent-safe). Otherwise email/password prompts fire — non-TTY callers must pipe `--with-token` or pre-set --name. Errors: auth.bad_credential on wrong password; input.invalid_argument on bad --host; input.missing_flag when --with-token has empty stdin.") return cmd @@ -78,7 +89,7 @@ func loginServiceFor(host string) LoginService { return sdk.NewClient(host) } -func runLogin(ctx context.Context, opts *LoginOptions, f *cmdutil.Factory, svc LoginService) error { +func runLogin(ctx context.Context, opts *LoginOptions, jopts *cmdutil.JSONOptions, f *cmdutil.Factory, svc LoginService) error { if err := validateHost(opts.Host); err != nil { return err } @@ -92,7 +103,7 @@ func runLogin(ctx context.Context, opts *LoginOptions, f *cmdutil.Factory, svc L return cmdutil.NewError(cmdutil.CodeInputMissingFlag, "--with-token requires an API key piped to stdin") } opts.APIKey = key - return persistAPIKey(opts, f) + return persistAPIKey(opts, jopts, f) } // Interactive: prompt for email + password. @@ -125,11 +136,11 @@ func runLogin(ctx context.Context, opts *LoginOptions, f *cmdutil.Factory, svc L return cmdutil.NewError(cmdutil.CodeAuthBadCredential, fmt.Sprintf("login refused: %s", resp.Message)) } - return persistJWT(opts, f, resp) + return persistJWT(opts, jopts, f, resp) } // persistAPIKey saves the --with-token API key and writes the context. -func persistAPIKey(opts *LoginOptions, f *cmdutil.Factory) error { +func persistAPIKey(opts *LoginOptions, jopts *cmdutil.JSONOptions, f *cmdutil.Factory) error { store, err := f.Secrets() if err != nil { return err @@ -137,14 +148,14 @@ func persistAPIKey(opts *LoginOptions, f *cmdutil.Factory) error { if err := store.Set(opts.Context, "api_key", opts.APIKey); err != nil { return cmdutil.Wrapf(cmdutil.CodeLocalKeychainDenied, err, "save api key") } - return saveContextRef(opts, f, &config.Context{ + return saveContextRef(opts, jopts, f, &config.Context{ Host: opts.Host, APIKeyRef: store.Ref(opts.Context, "api_key"), }, nil) } // persistJWT saves access + refresh tokens and writes the context. -func persistJWT(opts *LoginOptions, f *cmdutil.Factory, resp *sdk.LoginResponse) error { +func persistJWT(opts *LoginOptions, jopts *cmdutil.JSONOptions, f *cmdutil.Factory, resp *sdk.LoginResponse) error { store, err := f.Secrets() if err != nil { return err @@ -166,7 +177,7 @@ func persistJWT(opts *LoginOptions, f *cmdutil.Factory, resp *sdk.LoginResponse) c.User = resp.User.Email c.TenantID = resp.User.TenantID } - return saveContextRef(opts, f, c, resp.User) + return saveContextRef(opts, jopts, f, c, resp.User) } // loginResult is the typed payload emitted by `--json`. mode is derived from @@ -174,13 +185,13 @@ func persistJWT(opts *LoginOptions, f *cmdutil.Factory, resp *sdk.LoginResponse) type loginResult struct { Context string `json:"context"` Host string `json:"host"` - Mode string `json:"mode"` // "password" or "api-key" + Mode string `json:"mode"` // ModeBearer or ModeAPIKey User string `json:"user,omitempty"` TenantID uint64 `json:"tenant_id,omitempty"` } // saveContextRef writes the context to config.yaml and prints success. -func saveContextRef(opts *LoginOptions, f *cmdutil.Factory, ctx *config.Context, user *sdk.AuthUser) error { +func saveContextRef(opts *LoginOptions, jopts *cmdutil.JSONOptions, f *cmdutil.Factory, ctx *config.Context, user *sdk.AuthUser) error { cfg, err := f.Config() if err != nil { return err @@ -193,17 +204,19 @@ func saveContextRef(opts *LoginOptions, f *cmdutil.Factory, ctx *config.Context, if err := config.Save(cfg); err != nil { return cmdutil.Wrapf(cmdutil.CodeLocalFileIO, err, "save config") } - if opts.JSONOut { - result := loginResult{Context: opts.Context, Host: opts.Host, Mode: "api-key"} + if jopts.Enabled() { + result := loginResult{Context: opts.Context, Host: opts.Host, Mode: ModeAPIKey} if user != nil { - result.Mode = "password" + result.Mode = ModeBearer result.User = user.Email result.TenantID = user.TenantID } - return cmdutil.NewJSONExporter().Write(iostreams.IO.Out, format.Success(result, &format.Meta{ - Context: opts.Context, - TenantID: ctx.TenantID, - })) + return format.WriteEnvelopeFiltered(iostreams.IO.Out, + format.Success(result, &format.Meta{ + Context: opts.Context, + TenantID: ctx.TenantID, + }), + jopts.Fields, jopts.JQ) } who := opts.Context if user != nil { diff --git a/cli/cmd/auth/login_test.go b/cli/cmd/auth/login_test.go index ad65b076..474d633b 100644 --- a/cli/cmd/auth/login_test.go +++ b/cli/cmd/auth/login_test.go @@ -61,7 +61,7 @@ func TestRunLogin_PasswordMode(t *testing.T) { Host: "https://kb.example.com", Context: "prod", } - require.NoError(t, runLogin(context.Background(), opts, f, svc)) + require.NoError(t, runLogin(context.Background(), opts, nil, f, svc)) assert.Equal(t, "a@b.c", svc.got.email) assert.Equal(t, "secret", svc.got.password) @@ -79,7 +79,7 @@ func TestRunLogin_WithToken(t *testing.T) { WithToken: true, StdinReader: strings.NewReader(" sk-1234 \n"), } - require.NoError(t, runLogin(context.Background(), opts, f, nil)) + require.NoError(t, runLogin(context.Background(), opts, nil, f, nil)) got, _ := store.Get("ci", "api_key") assert.Equal(t, "sk-1234", got) } @@ -93,7 +93,7 @@ func TestRunLogin_WithToken_Empty(t *testing.T) { WithToken: true, StdinReader: strings.NewReader(""), } - err := runLogin(context.Background(), opts, f, nil) + err := runLogin(context.Background(), opts, nil, f, nil) require.Error(t, err) assert.Contains(t, err.Error(), "input.missing_flag") } @@ -101,7 +101,7 @@ func TestRunLogin_WithToken_Empty(t *testing.T) { func TestRunLogin_BadHost(t *testing.T) { iostreams.SetForTest(t) f, _ := newTestFactoryWithConfig(t, prompt.AgentPrompter{}) - err := runLogin(context.Background(), &LoginOptions{Host: "ftp://nope"}, f, nil) + err := runLogin(context.Background(), &LoginOptions{Host: "ftp://nope"}, nil, f, nil) require.Error(t, err) assert.Contains(t, err.Error(), "input.invalid_argument") } @@ -110,7 +110,7 @@ func TestRunLogin_LoginRefused(t *testing.T) { iostreams.SetForTest(t) f, _ := newTestFactoryWithConfig(t, scriptedPrompter{email: "a@b.c", password: "x"}) svc := &fakeLoginService{resp: &sdk.LoginResponse{Success: false, Message: "bad password"}} - err := runLogin(context.Background(), &LoginOptions{Host: "https://x", Context: "p"}, f, svc) + err := runLogin(context.Background(), &LoginOptions{Host: "https://x", Context: "p"}, nil, f, svc) require.Error(t, err) assert.Contains(t, err.Error(), "auth.bad_credential") } diff --git a/cli/cmd/auth/logout.go b/cli/cmd/auth/logout.go index cd21ba5a..ee3af23f 100644 --- a/cli/cmd/auth/logout.go +++ b/cli/cmd/auth/logout.go @@ -15,11 +15,15 @@ import ( ) type LogoutOptions struct { - Name string // --name: target a specific context (default: current) - All bool // --all: clear every context - JSONOut bool + Name string // --name: target a specific context (default: current) + All bool // --all: clear every context } +// authLogoutFields enumerates the fields surfaced for `--json` discovery +// on `auth logout`. The result is the list of context names that were +// logged out. +var authLogoutFields = []string{"removed"} + // logoutResult is the typed payload emitted under data. type logoutResult struct { Removed []string `json:"removed"` @@ -44,18 +48,22 @@ accepted until it expires.`, weknora auth logout --all`, Args: cobra.NoArgs, RunE: func(c *cobra.Command, _ []string) error { - return runLogout(opts, f) + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } + return runLogout(opts, jopts, f) }, } cmd.Flags().StringVar(&opts.Name, "name", "", "Context to log out (defaults to the current context)") cmd.Flags().BoolVar(&opts.All, "all", false, "Log out of every configured context") - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, authLogoutFields) cmd.MarkFlagsMutuallyExclusive("name", "all") agent.SetAgentHelp(cmd, "Clears local credentials only; the server-side token / api-key continues to be valid until expired or rotated. Returns data.removed: [...names]. Errors: auth.unauthenticated when no contexts configured.") return cmd } -func runLogout(opts *LogoutOptions, f *cmdutil.Factory) error { +func runLogout(opts *LogoutOptions, jopts *cmdutil.JSONOptions, f *cmdutil.Factory) error { cfg, err := f.Config() if err != nil { return err @@ -88,9 +96,10 @@ func runLogout(opts *LogoutOptions, f *cmdutil.Factory) error { return cmdutil.Wrapf(cmdutil.CodeLocalFileIO, err, "save config") } - if opts.JSONOut { - return cmdutil.NewJSONExporter().Write(iostreams.IO.Out, - format.Success(logoutResult{Removed: targets}, nil)) + if jopts.Enabled() { + return format.WriteEnvelopeFiltered(iostreams.IO.Out, + format.Success(logoutResult{Removed: targets}, nil), + jopts.Fields, jopts.JQ) } fmt.Fprintf(iostreams.IO.Out, "✓ Logged out of %d context(s): %s\n", len(targets), strings.Join(targets, ", ")) return nil diff --git a/cli/cmd/auth/logout_test.go b/cli/cmd/auth/logout_test.go index 9e2a922f..97fc23d4 100644 --- a/cli/cmd/auth/logout_test.go +++ b/cli/cmd/auth/logout_test.go @@ -45,7 +45,7 @@ func TestLogout_CurrentContext(t *testing.T) { "staging": {Host: "https://staging", APIKeyRef: store.Ref("staging", "api_key")}, }, } - require.NoError(t, runLogout(&LogoutOptions{}, newLogoutFactory(t, cfg, store))) + require.NoError(t, runLogout(&LogoutOptions{}, nil, newLogoutFactory(t, cfg, store))) assert.Empty(t, cfg.CurrentContext, "current_context should clear when removed") assert.NotContains(t, cfg.Contexts, "prod") @@ -73,7 +73,7 @@ func TestLogout_NamedContext(t *testing.T) { "staging": {Host: "https://staging", APIKeyRef: store.Ref("staging", "api_key")}, }, } - require.NoError(t, runLogout(&LogoutOptions{Name: "staging"}, newLogoutFactory(t, cfg, store))) + require.NoError(t, runLogout(&LogoutOptions{Name: "staging"}, nil, newLogoutFactory(t, cfg, store))) assert.Equal(t, "prod", cfg.CurrentContext, "current_context untouched when removing other") assert.NotContains(t, cfg.Contexts, "staging") @@ -91,7 +91,7 @@ func TestLogout_All(t *testing.T) { "staging": {Host: "https://staging"}, }, } - require.NoError(t, runLogout(&LogoutOptions{All: true}, newLogoutFactory(t, cfg, store))) + require.NoError(t, runLogout(&LogoutOptions{All: true}, nil, newLogoutFactory(t, cfg, store))) assert.Empty(t, cfg.Contexts) assert.Empty(t, cfg.CurrentContext) @@ -101,7 +101,7 @@ func TestLogout_NoContexts(t *testing.T) { isolateConfig(t) _, _ = iostreams.SetForTest(t) cfg := &config.Config{} - err := runLogout(&LogoutOptions{}, newLogoutFactory(t, cfg, secrets.NewMemStore())) + err := runLogout(&LogoutOptions{}, nil, newLogoutFactory(t, cfg, secrets.NewMemStore())) require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) @@ -115,7 +115,7 @@ func TestLogout_UnknownName(t *testing.T) { CurrentContext: "prod", Contexts: map[string]config.Context{"prod": {Host: "https://prod"}}, } - err := runLogout(&LogoutOptions{Name: "ghost"}, newLogoutFactory(t, cfg, secrets.NewMemStore())) + err := runLogout(&LogoutOptions{Name: "ghost"}, nil, newLogoutFactory(t, cfg, secrets.NewMemStore())) require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) @@ -128,7 +128,7 @@ func TestLogout_NoCurrentNoFlag(t *testing.T) { cfg := &config.Config{ Contexts: map[string]config.Context{"prod": {Host: "https://prod"}}, } - err := runLogout(&LogoutOptions{}, newLogoutFactory(t, cfg, secrets.NewMemStore())) + err := runLogout(&LogoutOptions{}, nil, newLogoutFactory(t, cfg, secrets.NewMemStore())) require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) diff --git a/cli/cmd/auth/refresh.go b/cli/cmd/auth/refresh.go index c4884373..9822dc63 100644 --- a/cli/cmd/auth/refresh.go +++ b/cli/cmd/auth/refresh.go @@ -14,10 +14,13 @@ import ( ) type RefreshOptions struct { - Name string // --name: target context (defaults to current) - JSONOut bool + Name string // --name: target context (defaults to current) } +// authRefreshFields enumerates the fields surfaced for `--json` discovery +// on `auth refresh`. Token values are intentionally omitted — see refreshResult. +var authRefreshFields = []string{"context"} + // refreshResult is the typed payload emitted under data on success. Token // values are intentionally NOT included — emitting them would leak secrets // into stdout / agent transcripts. Agents needing to verify the new token @@ -47,11 +50,15 @@ refresh semantic. Rotate the key in the server UI instead.`, weknora auth refresh --name staging # refresh a specific context`, Args: cobra.NoArgs, RunE: func(c *cobra.Command, _ []string) error { - return runRefresh(c.Context(), opts, f, defaultRefresher) + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } + return runRefresh(c.Context(), opts, jopts, f, defaultRefresher) }, } cmd.Flags().StringVar(&opts.Name, "name", "", "Context to refresh (defaults to the current context)") - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, authRefreshFields) agent.SetAgentHelp(cmd, "Renews the access token using the stored refresh token. Errors with auth.token_expired when refresh itself is rejected — surface the hint to re-run auth login.") return cmd } @@ -63,7 +70,7 @@ func defaultRefresher(host string) cmdutil.Refresher { return sdk.NewClient(host) } -func runRefresh(ctx context.Context, opts *RefreshOptions, f *cmdutil.Factory, refresherFor func(host string) cmdutil.Refresher) error { +func runRefresh(ctx context.Context, opts *RefreshOptions, jopts *cmdutil.JSONOptions, f *cmdutil.Factory, refresherFor func(host string) cmdutil.Refresher) error { cfg, err := f.Config() if err != nil { return err @@ -105,9 +112,10 @@ func runRefresh(ctx context.Context, opts *RefreshOptions, f *cmdutil.Factory, r return err } - if opts.JSONOut { - return format.WriteEnvelope(iostreams.IO.Out, - format.Success(refreshResult{Context: name}, &format.Meta{Context: name})) + if jopts.Enabled() { + return format.WriteEnvelopeFiltered(iostreams.IO.Out, + format.Success(refreshResult{Context: name}, &format.Meta{Context: name}), + jopts.Fields, jopts.JQ) } fmt.Fprintf(iostreams.IO.Out, "✓ Refreshed access token for context %s\n", name) return nil diff --git a/cli/cmd/auth/refresh_test.go b/cli/cmd/auth/refresh_test.go index 0a72378b..1017f25a 100644 --- a/cli/cmd/auth/refresh_test.go +++ b/cli/cmd/auth/refresh_test.go @@ -73,7 +73,7 @@ func TestRefresh_Happy(t *testing.T) { AccessToken: "new-access", RefreshToken: "new-refresh", }} - require.NoError(t, runRefresh(context.Background(), &RefreshOptions{}, f, stubSvc(svc))) + require.NoError(t, runRefresh(context.Background(), &RefreshOptions{}, nil, f, stubSvc(svc))) assert.Equal(t, "old-refresh", svc.gotTok, "must pass stored refresh token to SDK") gotAccess, _ := store.Get("prod", "access") @@ -98,7 +98,7 @@ func TestRefresh_NamedContext(t *testing.T) { svc := &fakeRefreshService{resp: &sdk.RefreshTokenResponse{ Success: true, AccessToken: "new-stg-access", RefreshToken: "new-stg-refresh", }} - require.NoError(t, runRefresh(context.Background(), &RefreshOptions{Name: "staging"}, f, stubSvc(svc))) + require.NoError(t, runRefresh(context.Background(), &RefreshOptions{Name: "staging"}, nil, f, stubSvc(svc))) assert.Equal(t, "stg-refresh", svc.gotTok, "--name=staging must refresh the staging context, not current") // current is untouched @@ -110,7 +110,7 @@ func TestRefresh_NamedContext(t *testing.T) { func TestRefresh_NoCurrentContext(t *testing.T) { iostreams.SetForTest(t) f := newRefreshFactory(t, &config.Config{}, secrets.NewMemStore()) - err := runRefresh(context.Background(), &RefreshOptions{}, f, stubSvc(&fakeRefreshService{})) + err := runRefresh(context.Background(), &RefreshOptions{}, nil, f, stubSvc(&fakeRefreshService{})) require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) @@ -126,7 +126,7 @@ func TestRefresh_APIKeyContext(t *testing.T) { Contexts: map[string]config.Context{"ci": {Host: "https://kb", APIKeyRef: "mem://ci/api_key"}}, } f := newRefreshFactory(t, cfg, store) - err := runRefresh(context.Background(), &RefreshOptions{}, f, stubSvc(&fakeRefreshService{})) + err := runRefresh(context.Background(), &RefreshOptions{}, nil, f, stubSvc(&fakeRefreshService{})) require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) @@ -144,7 +144,7 @@ func TestRefresh_NoRefreshTokenStored(t *testing.T) { } // MemStore is empty — RefreshRef points to a slot that doesn't exist. f := newRefreshFactory(t, cfg, secrets.NewMemStore()) - err := runRefresh(context.Background(), &RefreshOptions{}, f, stubSvc(&fakeRefreshService{})) + err := runRefresh(context.Background(), &RefreshOptions{}, nil, f, stubSvc(&fakeRefreshService{})) require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) @@ -162,7 +162,7 @@ func TestRefresh_ServerRefused(t *testing.T) { } f := newRefreshFactory(t, cfg, store) svc := &fakeRefreshService{resp: &sdk.RefreshTokenResponse{Success: false, Message: "refresh token expired"}} - err := runRefresh(context.Background(), &RefreshOptions{}, f, stubSvc(svc)) + err := runRefresh(context.Background(), &RefreshOptions{}, nil, f, stubSvc(svc)) require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) @@ -185,7 +185,7 @@ func TestRefresh_TransportError(t *testing.T) { } f := newRefreshFactory(t, cfg, store) svc := &fakeRefreshService{err: errors.New("connection reset")} - err := runRefresh(context.Background(), &RefreshOptions{}, f, stubSvc(svc)) + err := runRefresh(context.Background(), &RefreshOptions{}, nil, f, stubSvc(svc)) require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) @@ -205,7 +205,7 @@ func TestRefresh_JSONOutput(t *testing.T) { } f := newRefreshFactory(t, cfg, store) svc := &fakeRefreshService{resp: &sdk.RefreshTokenResponse{Success: true, AccessToken: "a", RefreshToken: "r"}} - require.NoError(t, runRefresh(context.Background(), &RefreshOptions{JSONOut: true}, f, stubSvc(svc))) + require.NoError(t, runRefresh(context.Background(), &RefreshOptions{}, &cmdutil.JSONOptions{}, f, stubSvc(svc))) var env format.Envelope require.NoError(t, json.Unmarshal(out.Bytes(), &env)) diff --git a/cli/cmd/auth/status.go b/cli/cmd/auth/status.go index 7b6f470a..31a2baf5 100644 --- a/cli/cmd/auth/status.go +++ b/cli/cmd/auth/status.go @@ -13,8 +13,10 @@ import ( sdk "github.com/Tencent/WeKnora/client" ) -type StatusOptions struct { - JSONOut bool +// authStatusFields enumerates the fields surfaced for `--json` discovery +// on `auth status`. Single-resource shape: filter applies to data itself. +var authStatusFields = []string{ + "context", "user_id", "email", "tenant_id", "tenant_name", } // StatusService is the narrow SDK surface auth status depends on. @@ -33,25 +35,28 @@ type statusResult struct { // NewCmdStatus builds the `weknora auth status` command. func NewCmdStatus(f *cmdutil.Factory) *cobra.Command { - opts := &StatusOptions{} cmd := &cobra.Command{ Use: "status", Short: "Show the active context, principal, and token state", Args: cobra.NoArgs, RunE: func(c *cobra.Command, args []string) error { + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } cli, err := f.Client() if err != nil { return err } - return runStatus(c.Context(), opts, f, cli) + return runStatus(c.Context(), jopts, f, cli) }, } - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, authStatusFields) agent.SetAgentHelp(cmd, "Live-checks the active credential by calling /auth/me. Returns {context, user_id, email, tenant_id, tenant_name}. Errors: auth.unauthenticated when token is invalid or missing (run `auth login` / `auth refresh`).") return cmd } -func runStatus(ctx context.Context, opts *StatusOptions, f *cmdutil.Factory, svc StatusService) error { +func runStatus(ctx context.Context, jopts *cmdutil.JSONOptions, f *cmdutil.Factory, svc StatusService) error { if svc == nil { return cmdutil.NewError(cmdutil.CodeAuthUnauthenticated, "no SDK client available; run `weknora auth login`") } @@ -67,7 +72,7 @@ func runStatus(ctx context.Context, opts *StatusOptions, f *cmdutil.Factory, svc return err } - if opts.JSONOut { + if jopts.Enabled() { var tenantID uint64 result := statusResult{Context: cfg.CurrentContext} if user != nil { @@ -79,10 +84,12 @@ func runStatus(ctx context.Context, opts *StatusOptions, f *cmdutil.Factory, svc if tenant != nil { result.TenantName = tenant.Name } - return cmdutil.NewJSONExporter().Write(iostreams.IO.Out, format.Success(result, &format.Meta{ - Context: cfg.CurrentContext, - TenantID: tenantID, - })) + return format.WriteEnvelopeFiltered(iostreams.IO.Out, + format.Success(result, &format.Meta{ + Context: cfg.CurrentContext, + TenantID: tenantID, + }), + jopts.Fields, jopts.JQ) } host := "" diff --git a/cli/cmd/auth/status_test.go b/cli/cmd/auth/status_test.go index 0c65f5a2..6bfc96a9 100644 --- a/cli/cmd/auth/status_test.go +++ b/cli/cmd/auth/status_test.go @@ -52,7 +52,7 @@ func TestRunStatus_HumanOutput(t *testing.T) { &sdk.AuthTenant{ID: 7, Name: "Acme"}, ), } - require.NoError(t, runStatus(context.Background(), &StatusOptions{}, f, svc)) + require.NoError(t, runStatus(context.Background(), nil, f, svc)) got := out.String() assert.Contains(t, got, "context: prod") assert.Contains(t, got, "host: https://kb.example.com") @@ -69,14 +69,14 @@ func TestRunStatus_JSONOutput(t *testing.T) { })) f := &cmdutil.Factory{Config: func() (*config.Config, error) { return config.Load() }} svc := &fakeStatusService{resp: newCurrentUserResponse(&sdk.AuthUser{ID: "u1", Email: "a@b.c", TenantID: 7}, nil)} - require.NoError(t, runStatus(context.Background(), &StatusOptions{JSONOut: true}, f, svc)) + require.NoError(t, runStatus(context.Background(), &cmdutil.JSONOptions{}, f, svc)) assert.True(t, strings.HasPrefix(out.String(), `{"ok":true`), "got: %q", out.String()) assert.Contains(t, out.String(), `"email":"a@b.c"`) } func TestRunStatus_NoSDKClient(t *testing.T) { iostreams.SetForTest(t) - err := runStatus(context.Background(), &StatusOptions{}, &cmdutil.Factory{}, nil) + err := runStatus(context.Background(), nil, &cmdutil.Factory{}, nil) require.Error(t, err) assert.True(t, cmdutil.IsAuthError(err)) } @@ -86,7 +86,7 @@ func TestRunStatus_SDKError_Transport(t *testing.T) { testutil.XDGTempDir(t) require.NoError(t, config.Save(&config.Config{CurrentContext: "p", Contexts: map[string]config.Context{"p": {Host: "https://x"}}})) f := &cmdutil.Factory{Config: func() (*config.Config, error) { return config.Load() }} - err := runStatus(context.Background(), &StatusOptions{}, f, &fakeStatusService{err: assert.AnError}) + err := runStatus(context.Background(), nil, f, &fakeStatusService{err: assert.AnError}) require.Error(t, err) // Non-HTTP errors (DNS / TCP) are transport problems, not auth problems — // classify network.error so retry logic / exit code 7 / IsTransient apply. @@ -98,7 +98,7 @@ func TestRunStatus_SDKError_HTTP401(t *testing.T) { testutil.XDGTempDir(t) require.NoError(t, config.Save(&config.Config{CurrentContext: "p", Contexts: map[string]config.Context{"p": {Host: "https://x"}}})) f := &cmdutil.Factory{Config: func() (*config.Config, error) { return config.Load() }} - err := runStatus(context.Background(), &StatusOptions{}, f, &fakeStatusService{err: errors.New("HTTP error 401: invalid token")}) + err := runStatus(context.Background(), nil, f, &fakeStatusService{err: errors.New("HTTP error 401: invalid token")}) require.Error(t, err) assert.True(t, cmdutil.IsAuthError(err)) } diff --git a/cli/cmd/auth/token.go b/cli/cmd/auth/token.go new file mode 100644 index 00000000..c069340f --- /dev/null +++ b/cli/cmd/auth/token.go @@ -0,0 +1,129 @@ +package auth + +import ( + "fmt" + + "github.com/spf13/cobra" + + "github.com/Tencent/WeKnora/cli/internal/agent" + "github.com/Tencent/WeKnora/cli/internal/cmdutil" + "github.com/Tencent/WeKnora/cli/internal/format" + "github.com/Tencent/WeKnora/cli/internal/iostreams" +) + +// authTokenFields lists fields available for `auth token --json=` projection. +// Single-resource envelope shape (data is the token result, not data.items). +var authTokenFields = []string{"token", "mode", "context"} + +type tokenResult struct { + Token string `json:"token"` + Mode string `json:"mode"` // ModeBearer (JWT) or ModeAPIKey + Context string `json:"context"` +} + +// NewCmdToken builds `weknora auth token`. Prints the active context's +// credential to stdout for use in shell pipelines, e.g. +// +// WEKNORA_TOKEN=$(weknora auth token) +// curl -H "Authorization: Bearer $WEKNORA_TOKEN" ... # JWT mode +// curl -H "X-API-Key: $WEKNORA_TOKEN" ... # api-key mode +// +// Mirrors gh's `gh auth token`. The user is responsible for constructing +// the appropriate header — `auth list` shows which mode each context uses. +// +// Default output: raw token on stdout, no trailing newline (clean $(...)). +// `--json[=fields]` wraps in envelope {token, mode, context}. +func NewCmdToken(f *cmdutil.Factory) *cobra.Command { + cmd := &cobra.Command{ + Use: "token", + Short: "Print the active context's credential to stdout", + Long: `Print the active context's credential to stdout, with no trailing +newline, suitable for shell command substitution. + +The credential is the long-lived API key (mode: api-key) or the access JWT +(mode: bearer), depending on how the context was created. Run ` + "`weknora auth list`" + ` +to see which mode each context uses, and construct the matching HTTP header: + + Authorization: Bearer # bearer mode + X-API-Key: # api-key mode + +` + "`--context `" + ` (global flag) selects a non-active context to read from.`, + Example: ` WEKNORA_TOKEN=$(weknora auth token) + weknora auth token --context staging + weknora auth token --json`, + Args: cobra.NoArgs, + RunE: func(c *cobra.Command, _ []string) error { + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } + return runToken(f, jopts) + }, + } + cmdutil.AddJSONFlags(cmd, authTokenFields) + agent.SetAgentHelp(cmd, "Prints the active context's credential to stdout for scripting. Default: raw secret, no trailing newline. With --json: envelope {token, mode, context}. Errors: auth.unauthenticated when no active context or no stored credential (run `auth login`); local.keychain_denied when the keyring rejects the read.") + return cmd +} + +func runToken(f *cmdutil.Factory, jopts *cmdutil.JSONOptions) error { + cfg, err := f.Config() + if err != nil { + return err + } + ctxName := cfg.CurrentContext + if f.ContextOverride != "" { + ctxName = f.ContextOverride + } + if ctxName == "" { + return cmdutil.NewError(cmdutil.CodeAuthUnauthenticated, + "no current context configured") + } + ctx, ok := cfg.Contexts[ctxName] + if !ok { + return cmdutil.NewError(cmdutil.CodeLocalContextNotFound, + fmt.Sprintf("context %q not found", ctxName)) + } + + store, err := f.Secrets() + if err != nil { + return cmdutil.Wrapf(cmdutil.CodeLocalKeychainDenied, err, "init secrets store") + } + + // Resolve the stored credential. Prefer bearer (JWT) when both refs + // are present — JWT is the more capable mode and what `buildClient` + // uses for the Authorization header (see factory.go buildClient). + var token, mode string + switch { + case ctx.TokenRef != "": + v, ferr := cmdutil.LoadSecret(store, ctxName, "access") + if ferr != nil { + return ferr + } + token, mode = v, ModeBearer + case ctx.APIKeyRef != "": + v, ferr := cmdutil.LoadSecret(store, ctxName, "api_key") + if ferr != nil { + return ferr + } + token, mode = v, ModeAPIKey + default: + return cmdutil.NewError(cmdutil.CodeAuthUnauthenticated, + fmt.Sprintf("context %q has no stored credential; run `weknora auth login`", ctxName)) + } + + if token == "" { + return cmdutil.NewError(cmdutil.CodeAuthUnauthenticated, + fmt.Sprintf("context %q credential is empty in keyring; run `weknora auth login`", ctxName)) + } + + if jopts.Enabled() { + return format.WriteEnvelopeFiltered(iostreams.IO.Out, + format.Success(tokenResult{Token: token, Mode: mode, Context: ctxName}, + &format.Meta{Context: ctxName}), + jopts.Fields, jopts.JQ) + } + + // No trailing newline — clean $(weknora auth token) substitution. + fmt.Fprint(iostreams.IO.Out, token) + return nil +} diff --git a/cli/cmd/auth/token_test.go b/cli/cmd/auth/token_test.go new file mode 100644 index 00000000..25ac4f0c --- /dev/null +++ b/cli/cmd/auth/token_test.go @@ -0,0 +1,203 @@ +package auth + +import ( + "encoding/json" + "strings" + "testing" + + "github.com/Tencent/WeKnora/cli/internal/cmdutil" + "github.com/Tencent/WeKnora/cli/internal/config" + "github.com/Tencent/WeKnora/cli/internal/iostreams" + "github.com/Tencent/WeKnora/cli/internal/secrets" +) + +// tokenTestFactory wires a config + in-memory secrets store the same way +// the production Factory does, so runToken exercises the real LoadSecret +// path. +func tokenTestFactory(t *testing.T, cfg *config.Config, store *secrets.MemStore) *cmdutil.Factory { + t.Helper() + f := &cmdutil.Factory{ + Config: func() (*config.Config, error) { return cfg, nil }, + Secrets: func() (secrets.Store, error) { return store, nil }, + } + return f +} + +func TestAuthToken_BearerMode_PlainOutput(t *testing.T) { + cfg := &config.Config{ + CurrentContext: "prod", + Contexts: map[string]config.Context{ + "prod": {Host: "https://kb.example.com", TokenRef: "prod:access", RefreshRef: "prod:refresh"}, + }, + } + store := secrets.NewMemStore() + _ = store.Set("prod", "access", "jwt-token-xyz") + + out, _ := iostreams.SetForTest(t) + err := runToken(tokenTestFactory(t, cfg, store), nil) + if err != nil { + t.Fatalf("runToken: %v", err) + } + got := out.String() + if got != "jwt-token-xyz" { + t.Errorf("expected raw token, got %q", got) + } + if strings.HasSuffix(got, "\n") { + t.Errorf("output must NOT end with newline (clean $(...) substitution); got %q", got) + } +} + +func TestAuthToken_APIKeyMode_PlainOutput(t *testing.T) { + cfg := &config.Config{ + CurrentContext: "ci", + Contexts: map[string]config.Context{ + "ci": {Host: "https://kb.example.com", APIKeyRef: "ci:api_key"}, + }, + } + store := secrets.NewMemStore() + _ = store.Set("ci", "api_key", "sk_test_apikey_42") + + out, _ := iostreams.SetForTest(t) + if err := runToken(tokenTestFactory(t, cfg, store), nil); err != nil { + t.Fatalf("runToken: %v", err) + } + if got := out.String(); got != "sk_test_apikey_42" { + t.Errorf("expected api-key value, got %q", got) + } +} + +func TestAuthToken_JSON(t *testing.T) { + cfg := &config.Config{ + CurrentContext: "prod", + Contexts: map[string]config.Context{ + "prod": {Host: "https://kb.example.com", TokenRef: "prod:access"}, + }, + } + store := secrets.NewMemStore() + _ = store.Set("prod", "access", "jwt-xyz") + + out, _ := iostreams.SetForTest(t) + if err := runToken(tokenTestFactory(t, cfg, store), &cmdutil.JSONOptions{}); err != nil { + t.Fatalf("runToken: %v", err) + } + var env struct { + OK bool `json:"ok"` + Data struct { + Token string `json:"token"` + Mode string `json:"mode"` + Context string `json:"context"` + } `json:"data"` + } + if err := json.Unmarshal(out.Bytes(), &env); err != nil { + t.Fatalf("parse: %v\n%s", err, out.String()) + } + if !env.OK { + t.Errorf("ok=false") + } + if env.Data.Token != "jwt-xyz" || env.Data.Mode != "bearer" || env.Data.Context != "prod" { + t.Errorf("envelope payload wrong: %+v", env.Data) + } +} + +func TestAuthToken_JSON_FieldFilter(t *testing.T) { + cfg := &config.Config{ + CurrentContext: "ci", + Contexts: map[string]config.Context{ + "ci": {Host: "https://kb.example.com", APIKeyRef: "ci:api_key"}, + }, + } + store := secrets.NewMemStore() + _ = store.Set("ci", "api_key", "sk_42") + + out, _ := iostreams.SetForTest(t) + jopts := &cmdutil.JSONOptions{Fields: []string{"token"}} + if err := runToken(tokenTestFactory(t, cfg, store), jopts); err != nil { + t.Fatalf("runToken: %v", err) + } + var env struct { + Data map[string]any `json:"data"` + } + if err := json.Unmarshal(out.Bytes(), &env); err != nil { + t.Fatalf("parse: %v", err) + } + if _, has := env.Data["mode"]; has { + t.Errorf("mode should be filtered out: %+v", env.Data) + } + if env.Data["token"] != "sk_42" { + t.Errorf("token wrong: %+v", env.Data) + } +} + +func TestAuthToken_NoCurrentContext(t *testing.T) { + cfg := &config.Config{} + store := secrets.NewMemStore() + iostreams.SetForTest(t) + err := runToken(tokenTestFactory(t, cfg, store), nil) + if err == nil { + t.Fatal("expected error, got nil") + } + if !cmdutil.IsAuthError(err) { + t.Errorf("want auth.* code, got %v", err) + } +} + +func TestAuthToken_ContextOverride(t *testing.T) { + cfg := &config.Config{ + CurrentContext: "prod", + Contexts: map[string]config.Context{ + "prod": {Host: "https://prod.example.com", TokenRef: "prod:access"}, + "staging": {Host: "https://staging.example.com", APIKeyRef: "staging:api_key"}, + }, + } + store := secrets.NewMemStore() + _ = store.Set("prod", "access", "prod-jwt") + _ = store.Set("staging", "api_key", "staging-key") + + f := tokenTestFactory(t, cfg, store) + f.ContextOverride = "staging" + + out, _ := iostreams.SetForTest(t) + if err := runToken(f, nil); err != nil { + t.Fatalf("runToken: %v", err) + } + if got := out.String(); got != "staging-key" { + t.Errorf("expected staging-key (override), got %q", got) + } +} + +func TestAuthToken_NoStoredCredential(t *testing.T) { + cfg := &config.Config{ + CurrentContext: "prod", + Contexts: map[string]config.Context{ + "prod": {Host: "https://kb.example.com", TokenRef: "prod:access"}, + }, + } + store := secrets.NewMemStore() + // no Set — keyring is empty + iostreams.SetForTest(t) + err := runToken(tokenTestFactory(t, cfg, store), nil) + if err == nil { + t.Fatal("expected auth.unauthenticated, got nil") + } + if !cmdutil.IsAuthError(err) { + t.Errorf("want auth.*, got %v", err) + } +} + +func TestAuthToken_ContextWithNoCredentialRefs(t *testing.T) { + cfg := &config.Config{ + CurrentContext: "empty", + Contexts: map[string]config.Context{ + "empty": {Host: "https://kb.example.com"}, // no TokenRef or APIKeyRef + }, + } + store := secrets.NewMemStore() + iostreams.SetForTest(t) + err := runToken(tokenTestFactory(t, cfg, store), nil) + if err == nil { + t.Fatal("expected auth.unauthenticated, got nil") + } + if !cmdutil.IsAuthError(err) { + t.Errorf("want auth.*, got %v", err) + } +} diff --git a/cli/cmd/chat/chat.go b/cli/cmd/chat/chat.go index e839ed29..4e336595 100644 --- a/cli/cmd/chat/chat.go +++ b/cli/cmd/chat/chat.go @@ -36,12 +36,17 @@ import ( sdk "github.com/Tencent/WeKnora/client" ) +// chatFields enumerates the fields surfaced for `--json` discovery on `chat`. +// Mirrors the chatData struct json tags. +var chatFields = []string{ + "answer", "references", "session_id", "assistant_message_id", "kb_id", "query", +} + type Options struct { Query string KBID string SessionID string NoStream bool - JSONOut bool } // chatService is the narrow SDK surface this command depends on. *sdk.Client @@ -56,12 +61,12 @@ type chatService interface { // continue a conversation: the answer text, retrieval references, and the // session pointer to thread follow-ups. type chatData struct { - Answer string `json:"answer"` + Answer string `json:"answer"` References []*sdk.SearchResult `json:"references"` - SessionID string `json:"session_id"` - AssistantMessageID string `json:"assistant_message_id,omitempty"` - KBID string `json:"kb_id"` - Query string `json:"query"` + SessionID string `json:"session_id"` + AssistantMessageID string `json:"assistant_message_id,omitempty"` + KBID string `json:"kb_id"` + Query string `json:"query"` } // NewCmd builds `weknora chat `. @@ -72,20 +77,24 @@ func NewCmd(f *cmdutil.Factory) *cobra.Command { Short: "Ask a streaming RAG question against a knowledge base", Long: `Send a query to the WeKnora knowledge-chat endpoint and stream the answer back. By default a fresh session is created on first invocation; pass ---session-id to continue an existing conversation. +--session to continue an existing conversation. Modes: TTY (default): live token streaming + reference footer Pipe / --no-stream / --json: buffered, emitted once on completion`, Example: ` weknora chat "What is RRF?" --kb a32a63ff-fb36-4874-bcaa-30f48570a694 weknora chat "Summarise this design doc" --kb my-kb --json - weknora chat "Continue?" --session-id sess_abc`, + weknora chat "Continue?" --session sess_abc`, Args: cobra.MinimumNArgs(1), RunE: func(c *cobra.Command, args []string) error { opts.Query = strings.TrimSpace(strings.Join(args, " ")) if opts.Query == "" { return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, "query argument cannot be empty") } + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } kbID, err := f.ResolveKB(c) if err != nil { return err @@ -95,20 +104,20 @@ Modes: if err != nil { return err } - return runChat(c.Context(), opts, cli) + return runChat(c.Context(), opts, jopts, cli) }, } cmd.Flags().String("kb", "", "Knowledge base UUID or name (overrides project link / env)") - cmd.Flags().StringVar(&opts.SessionID, "session-id", "", "Continue an existing chat session (skip auto-create)") + cmd.Flags().StringVar(&opts.SessionID, "session", "", "Continue an existing chat session (skip auto-create)") cmd.Flags().BoolVar(&opts.NoStream, "no-stream", false, "Buffer the full answer before printing (forces accumulate mode)") - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Emit a single JSON envelope (implies --no-stream)") - agent.SetAgentHelp(cmd, "Streams an LLM answer over SSE. Agent / non-TTY callers should pass --json so the full {answer, references, session_id, assistant_message_id} envelope is emitted at completion (no partial chunks). Pass --session-id to thread follow-ups. Errors: server.session_create_failed when auto-create fails; local.sse_stream_aborted on mid-stream disconnect.") + cmdutil.AddJSONFlags(cmd, chatFields) + agent.SetAgentHelp(cmd, "Streams an LLM answer over SSE. Agent / non-TTY callers should pass --json so the full {answer, references, session_id, assistant_message_id} envelope is emitted at completion (no partial chunks). Pass --session to thread follow-ups. Errors: server.session_create_failed when auto-create fails; local.sse_stream_aborted on mid-stream disconnect.") return cmd } // runChat is the testable core: validate, ensure a session, dispatch the // stream, and route output. Returns a typed error suitable for the envelope. -func runChat(ctx context.Context, opts *Options, svc chatService) error { +func runChat(ctx context.Context, opts *Options, jopts *cmdutil.JSONOptions, svc chatService) error { if opts.Query == "" { return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, "query argument cannot be empty") } @@ -121,6 +130,8 @@ func runChat(ctx context.Context, opts *Options, svc chatService) error { return cmdutil.NewError(cmdutil.CodeServerError, "chat: no SDK client available") } + jsonOut := jopts.Enabled() + sessionID := opts.SessionID autoCreated := false if sessionID == "" { @@ -142,14 +153,14 @@ func runChat(ctx context.Context, opts *Options, svc chatService) error { // 1. an interactive stdout (tty) // 2. no --no-stream // 3. no --json (envelope is single-record by definition) - streamMode := iostreams.IO.IsStdoutTTY() && !opts.NoStream && !opts.JSONOut + streamMode := iostreams.IO.IsStdoutTTY() && !opts.NoStream && !jsonOut // Surface the auto-created session ID up-front so a user who hits ^C // mid-stream still has the pointer to resume — no need to scroll back // past tokens. Skipped in JSON mode (it ends up in the envelope) and - // when the caller already supplied --session-id. - if autoCreated && !opts.JSONOut { - fmt.Fprintf(iostreams.IO.Err, "session: %s (use --session-id to continue)\n", sessionID) + // when the caller already supplied --session. + if autoCreated && !jsonOut { + fmt.Fprintf(iostreams.IO.Err, "session: %s (use --session to continue)\n", sessionID) } req := &sdk.KnowledgeQARequest{ @@ -176,10 +187,10 @@ func runChat(ctx context.Context, opts *Options, svc chatService) error { if streamErr != nil { // Re-surface the auto-created session id on failure so a user who // missed the start-of-stream notice (it scrolls past mid-stream - // tokens, especially on ^C) can still recover with --session-id. + // tokens, especially on ^C) can still recover with --session. // Skipped in JSON mode — the envelope carries it in .data.session_id. - if autoCreated && !opts.JSONOut { - fmt.Fprintf(iostreams.IO.Err, "session: %s (resume with --session-id %s)\n", sessionID, sessionID) + if autoCreated && !jsonOut { + fmt.Fprintf(iostreams.IO.Err, "session: %s (resume with --session %s)\n", sessionID, sessionID) } // Context cancelled (Ctrl-C) → user-aborted, exit 130 lineage. if errors.Is(streamErr, context.Canceled) || errors.Is(ctx.Err(), context.Canceled) { @@ -209,7 +220,7 @@ func runChat(ctx context.Context, opts *Options, svc chatService) error { answer := acc.Result() references := acc.References - if opts.JSONOut { + if jsonOut { // Prefer the SDK-echoed session id (acc.SessionID) but fall back to // our local sessionID — agents must always see a usable pointer. sid := acc.SessionID @@ -224,7 +235,11 @@ func runChat(ctx context.Context, opts *Options, svc chatService) error { KBID: opts.KBID, Query: opts.Query, } - return cmdutil.NewJSONExporter().Write(iostreams.IO.Out, format.Success(data, &format.Meta{KBID: opts.KBID})) + return format.WriteEnvelopeFiltered( + iostreams.IO.Out, + format.Success(data, &format.Meta{KBID: opts.KBID}), + jopts.Fields, jopts.JQ, + ) } // Human / non-JSON paths: streaming mode already wrote the answer body diff --git a/cli/cmd/chat/chat_test.go b/cli/cmd/chat/chat_test.go index 118bbf32..dd3ffe62 100644 --- a/cli/cmd/chat/chat_test.go +++ b/cli/cmd/chat/chat_test.go @@ -73,7 +73,7 @@ func TestChat_StreamMode(t *testing.T) { }, } opts := &Options{Query: "hi", KBID: "kb_1"} - if err := runChat(context.Background(), opts, svc); err != nil { + if err := runChat(context.Background(), opts, nil, svc); err != nil { t.Fatalf("runChat: %v", err) } got := out.String() @@ -111,8 +111,8 @@ func TestChat_JSONMode(t *testing.T) { {ResponseType: sdk.ResponseTypeComplete, Done: true}, }, } - opts := &Options{Query: "q", KBID: "kb_42", JSONOut: true} - if err := runChat(context.Background(), opts, svc); err != nil { + opts := &Options{Query: "q", KBID: "kb_42"} + if err := runChat(context.Background(), opts, &cmdutil.JSONOptions{}, svc); err != nil { t.Fatalf("runChat: %v", err) } @@ -174,7 +174,7 @@ func TestChat_NoStreamFlag(t *testing.T) { }, } opts := &Options{Query: "q", KBID: "kb", NoStream: true} - if err := runChat(context.Background(), opts, svc); err != nil { + if err := runChat(context.Background(), opts, nil, svc); err != nil { t.Fatalf("runChat: %v", err) } written = out.String() @@ -193,7 +193,7 @@ func TestChat_NonTTY_AccumulateMode(t *testing.T) { }, } opts := &Options{Query: "q", KBID: "kb"} - if err := runChat(context.Background(), opts, svc); err != nil { + if err := runChat(context.Background(), opts, nil, svc); err != nil { t.Fatalf("runChat: %v", err) } if !strings.Contains(out.String(), "piped") { @@ -207,18 +207,18 @@ func TestChat_SessionIDProvided(t *testing.T) { streamEvents: []*sdk.StreamResponse{{ResponseType: sdk.ResponseTypeComplete, Done: true}}, } opts := &Options{Query: "q", KBID: "kb", SessionID: "sess_existing"} - if err := runChat(context.Background(), opts, svc); err != nil { + if err := runChat(context.Background(), opts, nil, svc); err != nil { t.Fatalf("runChat: %v", err) } if svc.createCalled { - t.Error("CreateSession must NOT be invoked when --session-id is provided") + t.Error("CreateSession must NOT be invoked when --session is provided") } if svc.gotSessionID != "sess_existing" { t.Errorf("stream sessionID: got %q want sess_existing", svc.gotSessionID) } // No auto-create message because the user supplied the id. if strings.Contains(errBuf.String(), "session:") { - t.Errorf("unexpected session hint emitted with explicit --session-id: %q", errBuf.String()) + t.Errorf("unexpected session hint emitted with explicit --session: %q", errBuf.String()) } } @@ -227,7 +227,7 @@ func TestChat_KBIDRequired(t *testing.T) { svc := &fakeChatService{} // Run with KBID empty (bypassing the cobra resolver). opts := &Options{Query: "q"} - err := runChat(context.Background(), opts, svc) + err := runChat(context.Background(), opts, nil, svc) if err == nil { t.Fatal("expected error, got nil") } @@ -247,7 +247,7 @@ func TestChat_EmptyQuery(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakeChatService{} opts := &Options{Query: "", KBID: "kb"} - err := runChat(context.Background(), opts, svc) + err := runChat(context.Background(), opts, nil, svc) if err == nil { t.Fatal("expected error, got nil") } @@ -268,7 +268,7 @@ func TestChat_SDKError_PreStream(t *testing.T) { streamErr: errors.New("HTTP error 401: token rejected"), } opts := &Options{Query: "q", KBID: "kb"} - err := runChat(context.Background(), opts, svc) + err := runChat(context.Background(), opts, nil, svc) if err == nil { t.Fatal("expected error, got nil") } @@ -290,7 +290,7 @@ func TestChat_SDKError_MidStream_AbortsAsSSE(t *testing.T) { streamErr: errors.New("connection reset"), } opts := &Options{Query: "q", KBID: "kb"} - err := runChat(context.Background(), opts, svc) + err := runChat(context.Background(), opts, nil, svc) if err == nil { t.Fatal("expected error, got nil") } @@ -309,7 +309,7 @@ func TestChat_ContextCancelled(t *testing.T) { cancel() // simulate Ctrl-C delivered before the SDK returns. svc := &fakeChatService{streamErr: context.Canceled} opts := &Options{Query: "q", KBID: "kb"} - err := runChat(ctx, opts, svc) + err := runChat(ctx, opts, nil, svc) if err == nil { t.Fatal("expected error, got nil") } @@ -328,7 +328,7 @@ func TestChat_SessionCreateFails(t *testing.T) { createSessionErr: errors.New("dial tcp: connection refused"), } opts := &Options{Query: "q", KBID: "kb"} - err := runChat(context.Background(), opts, svc) + err := runChat(context.Background(), opts, nil, svc) if err == nil { t.Fatal("expected error, got nil") } @@ -353,7 +353,7 @@ func TestChat_SessionCreate404SurfacesNotFound(t *testing.T) { createSessionErr: errors.New("HTTP error 404: tenant not found"), } opts := &Options{Query: "q", KBID: "kb"} - err := runChat(context.Background(), opts, svc) + err := runChat(context.Background(), opts, nil, svc) if err == nil { t.Fatal("expected error, got nil") } diff --git a/cli/cmd/context/add.go b/cli/cmd/context/add.go index d8e2a375..996e8b27 100644 --- a/cli/cmd/context/add.go +++ b/cli/cmd/context/add.go @@ -14,9 +14,14 @@ import ( ) type AddOptions struct { - Host string - User string - JSONOut bool + Host string + User string +} + +// contextAddFields enumerates the fields surfaced for `--json` discovery on +// `context add`. The result describes the newly-registered context. +var contextAddFields = []string{ + "name", "host", "user", "current", } // addResult is the typed payload emitted under data on success. @@ -49,18 +54,22 @@ adds leave the current context untouched.`, weknora context add prod --host https://prod.example.com --user alice@example.com`, Args: cobra.ExactArgs(1), RunE: func(c *cobra.Command, args []string) error { - return runAdd(opts, args[0]) + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } + return runAdd(opts, jopts, args[0]) }, } cmd.Flags().StringVar(&opts.Host, "host", "", "Server base URL, e.g. https://kb.example.com (required)") cmd.Flags().StringVar(&opts.User, "user", "", "Account email shown in 'context list' (optional, cosmetic only)") - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, contextAddFields) _ = cmd.MarkFlagRequired("host") agent.SetAgentHelp(cmd, "Adds a context. First context added auto-becomes current. Errors with resource.already_exists if name collides; input.invalid_argument if --host is not an absolute http(s) URL.") return cmd } -func runAdd(opts *AddOptions, name string) error { +func runAdd(opts *AddOptions, jopts *cmdutil.JSONOptions, name string) error { if err := validateName(name); err != nil { return err } @@ -93,12 +102,14 @@ func runAdd(opts *AddOptions, name string) error { } risk := &format.Risk{Level: format.RiskWrite, Action: fmt.Sprintf("add context %s", name)} - if opts.JSONOut { - return format.WriteEnvelope(iostreams.IO.Out, format.SuccessWithRisk( - addResult{Name: name, Host: host, User: opts.User, Current: wasFirst}, - &format.Meta{Context: cfg.CurrentContext}, - risk, - )) + if jopts.Enabled() { + return format.WriteEnvelopeFiltered(iostreams.IO.Out, + format.SuccessWithRisk( + addResult{Name: name, Host: host, User: opts.User, Current: wasFirst}, + &format.Meta{Context: cfg.CurrentContext}, + risk, + ), + jopts.Fields, jopts.JQ) } if wasFirst { fmt.Fprintf(iostreams.IO.Out, "✓ Added context %s (now current). Run `weknora auth login --name %s` to attach credentials.\n", name, name) diff --git a/cli/cmd/context/add_test.go b/cli/cmd/context/add_test.go index 862557a1..8038cab6 100644 --- a/cli/cmd/context/add_test.go +++ b/cli/cmd/context/add_test.go @@ -15,7 +15,7 @@ func TestAdd_HappyPath(t *testing.T) { t.Setenv("XDG_CONFIG_HOME", t.TempDir()) out, _ := iostreams.SetForTest(t) - if err := runAdd(&AddOptions{Host: "https://my.example.com", User: "alice@example.com"}, "staging"); err != nil { + if err := runAdd(&AddOptions{Host: "https://my.example.com", User: "alice@example.com"}, nil, "staging"); err != nil { t.Fatalf("runAdd: %v", err) } @@ -54,7 +54,7 @@ func TestAdd_DuplicateName(t *testing.T) { t.Fatalf("Save: %v", err) } - err := runAdd(&AddOptions{Host: "https://new.example.com"}, "staging") + err := runAdd(&AddOptions{Host: "https://new.example.com"}, nil, "staging") if err == nil { t.Fatal("expected error on duplicate name") } @@ -83,7 +83,7 @@ func TestAdd_BadHost(t *testing.T) { "http://", // missing host } for _, h := range bad { - err := runAdd(&AddOptions{Host: h}, "staging") + err := runAdd(&AddOptions{Host: h}, nil, "staging") if err == nil { t.Errorf("host=%q: expected error", h) continue @@ -111,7 +111,7 @@ func TestAdd_SecondContextDoesNotChangeCurrent(t *testing.T) { t.Fatalf("Save: %v", err) } - if err := runAdd(&AddOptions{Host: "https://stg.example.com"}, "staging"); err != nil { + if err := runAdd(&AddOptions{Host: "https://stg.example.com"}, nil, "staging"); err != nil { t.Fatalf("runAdd: %v", err) } got, _ := config.Load() @@ -124,7 +124,7 @@ func TestAdd_JSON(t *testing.T) { t.Setenv("XDG_CONFIG_HOME", t.TempDir()) out, _ := iostreams.SetForTest(t) - if err := runAdd(&AddOptions{Host: "https://my.example.com", JSONOut: true}, "staging"); err != nil { + if err := runAdd(&AddOptions{Host: "https://my.example.com"}, &cmdutil.JSONOptions{}, "staging"); err != nil { t.Fatalf("runAdd: %v", err) } var env format.Envelope diff --git a/cli/cmd/context/list.go b/cli/cmd/context/list.go index 52ab34e8..cda520e4 100644 --- a/cli/cmd/context/list.go +++ b/cli/cmd/context/list.go @@ -14,8 +14,12 @@ import ( "github.com/Tencent/WeKnora/cli/internal/iostreams" ) -type ListOptions struct { - JSONOut bool +type ListOptions struct{} + +// contextListFields enumerates the fields surfaced for `--json` discovery on +// `context list`. Each entry is a per-context summary row. +var contextListFields = []string{ + "name", "host", "user", "current", } type listEntry struct { @@ -28,7 +32,6 @@ type listEntry struct { // NewCmdList builds `weknora context list`. Per-host enumeration with an // active marker. Reads only config.yaml — no network, no keyring touch. func NewCmdList(f *cmdutil.Factory) *cobra.Command { - opts := &ListOptions{} cmd := &cobra.Command{ Use: "list", Short: "List configured contexts", @@ -41,15 +44,19 @@ run "weknora auth list" for that. "context list" is the catalog of *where* the CLI can talk to; "auth list" is the catalog of *how*.`, Args: cobra.NoArgs, RunE: func(c *cobra.Command, _ []string) error { - return runList(opts) + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } + return runList(jopts) }, } - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, contextListFields) agent.SetAgentHelp(cmd, "Lists CLI contexts (name/host/user/current). Read-only, no network. Use this before context use to verify the target name exists.") return cmd } -func runList(opts *ListOptions) error { +func runList(jopts *cmdutil.JSONOptions) error { cfg, err := config.Load() if err != nil { return err @@ -65,9 +72,10 @@ func runList(opts *ListOptions) error { } sort.Slice(entries, func(i, j int) bool { return entries[i].Name < entries[j].Name }) - if opts.JSONOut { - return format.WriteEnvelope(iostreams.IO.Out, - format.Success(entries, &format.Meta{Context: cfg.CurrentContext})) + if jopts.Enabled() { + return format.WriteEnvelopeFiltered(iostreams.IO.Out, + format.Success(entries, &format.Meta{Context: cfg.CurrentContext}), + jopts.Fields, jopts.JQ) } if len(entries) == 0 { fmt.Fprintln(iostreams.IO.Out, "No contexts configured. Run `weknora auth login` (or `weknora context add`) to create one.") diff --git a/cli/cmd/context/list_test.go b/cli/cmd/context/list_test.go index 8a057d31..2377e03e 100644 --- a/cli/cmd/context/list_test.go +++ b/cli/cmd/context/list_test.go @@ -5,6 +5,7 @@ import ( "strings" "testing" + "github.com/Tencent/WeKnora/cli/internal/cmdutil" "github.com/Tencent/WeKnora/cli/internal/config" "github.com/Tencent/WeKnora/cli/internal/format" "github.com/Tencent/WeKnora/cli/internal/iostreams" @@ -14,7 +15,7 @@ func TestList_Empty(t *testing.T) { t.Setenv("XDG_CONFIG_HOME", t.TempDir()) out, _ := iostreams.SetForTest(t) - if err := runList(&ListOptions{}); err != nil { + if err := runList(nil); err != nil { t.Fatalf("runList: %v", err) } if !strings.Contains(out.String(), "No contexts") { @@ -38,7 +39,7 @@ func TestList_MultipleSorted(t *testing.T) { t.Fatalf("Save: %v", err) } - if err := runList(&ListOptions{}); err != nil { + if err := runList(nil); err != nil { t.Fatalf("runList: %v", err) } got := out.String() @@ -75,7 +76,7 @@ func TestList_JSON(t *testing.T) { t.Fatalf("Save: %v", err) } - if err := runList(&ListOptions{JSONOut: true}); err != nil { + if err := runList(&cmdutil.JSONOptions{}); err != nil { t.Fatalf("runList: %v", err) } diff --git a/cli/cmd/context/remove.go b/cli/cmd/context/remove.go index 8e87ff72..7ea3ca42 100644 --- a/cli/cmd/context/remove.go +++ b/cli/cmd/context/remove.go @@ -15,9 +15,14 @@ import ( ) type RemoveOptions struct { - Yes bool // sourced from the global -y/--yes persistent flag (matches `kb delete`) - JSONOut bool - DryRun bool + Yes bool // sourced from the global -y/--yes persistent flag (matches `kb delete`) + DryRun bool +} + +// contextRemoveFields enumerates the fields surfaced for `--json` discovery on +// `context remove`. The result reports the disposition of the removed entry. +var contextRemoveFields = []string{ + "name", "removed", "was_current", } // removeResult is the typed payload emitted under data on success. @@ -49,21 +54,25 @@ in scripted / --json invocations (exit code 10; see cli/AGENTS.md).`, weknora context remove production -y # remove current → confirm`, Args: cobra.ExactArgs(1), RunE: func(c *cobra.Command, args []string) error { + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } opts.Yes, _ = c.Flags().GetBool("yes") opts.DryRun = cmdutil.IsDryRun(c) store, err := f.Secrets() if err != nil { return err } - return runRemove(opts, args[0], store, f.Prompter()) + return runRemove(opts, jopts, args[0], store, f.Prompter()) }, } - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, contextRemoveFields) agent.SetAgentHelp(cmd, "Removes a context entry. Removing the current context requires -y in non-TTY/--json (exit-10). Always best-effort clears keyring refs.") return cmd } -func runRemove(opts *RemoveOptions, name string, store secrets.Store, p prompt.Prompter) error { +func runRemove(opts *RemoveOptions, jopts *cmdutil.JSONOptions, name string, store secrets.Store, p prompt.Prompter) error { cfg, err := config.Load() if err != nil { return err @@ -75,8 +84,9 @@ func runRemove(opts *RemoveOptions, name string, store secrets.Store, p prompt.P wasCurrent := name == cfg.CurrentContext risk := riskForRemove(name, wasCurrent) + jsonOut := jopts.Enabled() if opts.DryRun { - return cmdutil.EmitDryRun(opts.JSONOut, + return cmdutil.EmitDryRun(jsonOut, removeResult{Name: name, Removed: false, WasCurrent: wasCurrent}, &format.Meta{Context: cfg.CurrentContext}, risk) @@ -84,7 +94,7 @@ func runRemove(opts *RemoveOptions, name string, store secrets.Store, p prompt.P // Confirmation only fires for removing the current context — non-current // remove uses the same low-friction policy as `auth logout`. if wasCurrent { - if err := cmdutil.ConfirmDestructive(p, opts.Yes, opts.JSONOut, "current context", name); err != nil { + if err := cmdutil.ConfirmDestructive(p, opts.Yes, jsonOut, "current context", name); err != nil { return err } } @@ -101,10 +111,10 @@ func runRemove(opts *RemoveOptions, name string, store secrets.Store, p prompt.P clearContextSecrets(store, ctx, name) result := removeResult{Name: name, Removed: true, WasCurrent: wasCurrent} - if opts.JSONOut { - return format.WriteEnvelope(iostreams.IO.Out, format.SuccessWithRisk( - result, &format.Meta{Context: cfg.CurrentContext}, risk, - )) + if jsonOut { + return format.WriteEnvelopeFiltered(iostreams.IO.Out, + format.SuccessWithRisk(result, &format.Meta{Context: cfg.CurrentContext}, risk), + jopts.Fields, jopts.JQ) } if wasCurrent { fmt.Fprintf(iostreams.IO.Out, "✓ Removed context %s (current context cleared — run `weknora context use ` to pick another)\n", name) diff --git a/cli/cmd/context/remove_test.go b/cli/cmd/context/remove_test.go index d6cae8b2..4c454c8a 100644 --- a/cli/cmd/context/remove_test.go +++ b/cli/cmd/context/remove_test.go @@ -52,7 +52,7 @@ func TestRemove_NonCurrent_NoPromptNeeded(t *testing.T) { store := seedStore(t, "staging", "api_key") p := &testutil.ConfirmPrompter{} - if err := runRemove(&RemoveOptions{}, "staging", store, p); err != nil { + if err := runRemove(&RemoveOptions{}, nil, "staging", store, p); err != nil { t.Fatalf("runRemove: %v", err) } if p.Asked { @@ -84,7 +84,7 @@ func TestRemove_NotFound_WithDidYouMean(t *testing.T) { t.Fatalf("Save: %v", err) } - err := runRemove(&RemoveOptions{}, "prodution", secrets.NewMemStore(), &testutil.ConfirmPrompter{}) + err := runRemove(&RemoveOptions{}, nil, "prodution", secrets.NewMemStore(), &testutil.ConfirmPrompter{}) if err == nil { t.Fatal("expected not-found error") } @@ -116,7 +116,7 @@ func TestRemove_Current_NonTTY_NoYes_RequiresConfirmation(t *testing.T) { } store := seedStore(t, "production", "access") - err := runRemove(&RemoveOptions{}, "production", store, &testutil.ConfirmPrompter{}) + err := runRemove(&RemoveOptions{}, nil, "production", store, &testutil.ConfirmPrompter{}) if err == nil { t.Fatal("expected confirmation-required error") } @@ -155,7 +155,7 @@ func TestRemove_Current_WithYes_ClearsCurrent(t *testing.T) { } store := seedStore(t, "production", "access") - if err := runRemove(&RemoveOptions{Yes: true}, "production", store, &testutil.ConfirmPrompter{}); err != nil { + if err := runRemove(&RemoveOptions{Yes: true}, nil, "production", store, &testutil.ConfirmPrompter{}); err != nil { t.Fatalf("runRemove: %v", err) } got, _ := config.Load() @@ -184,7 +184,7 @@ func TestRemove_Current_TTY_PromptNo(t *testing.T) { } p := &testutil.ConfirmPrompter{Answer: false} - err := runRemove(&RemoveOptions{}, "production", secrets.NewMemStore(), p) + err := runRemove(&RemoveOptions{}, nil, "production", secrets.NewMemStore(), p) if err == nil { t.Fatal("expected user-aborted error") } @@ -219,7 +219,7 @@ func TestRemove_DryRun(t *testing.T) { } store := seedStore(t, "production", "access") - if err := runRemove(&RemoveOptions{DryRun: true, JSONOut: true}, "production", store, &testutil.ConfirmPrompter{}); err != nil { + if err := runRemove(&RemoveOptions{DryRun: true}, &cmdutil.JSONOptions{}, "production", store, &testutil.ConfirmPrompter{}); err != nil { t.Fatalf("runRemove dry-run: %v", err) } var env format.Envelope diff --git a/cli/cmd/doc/delete.go b/cli/cmd/doc/delete.go index 7e1f756d..95f543fe 100644 --- a/cli/cmd/doc/delete.go +++ b/cli/cmd/doc/delete.go @@ -13,10 +13,13 @@ import ( "github.com/Tencent/WeKnora/cli/internal/prompt" ) +// docDeleteFields enumerates the fields surfaced for `--json` discovery on +// `doc delete`. The result payload is a small {id, deleted} object. +var docDeleteFields = []string{"id", "deleted"} + type DeleteOptions struct { - Yes bool // sourced from the global -y/--yes persistent flag (see cli/cmd/root.go) - JSONOut bool - DryRun bool + Yes bool // sourced from the global -y/--yes persistent flag (see cli/cmd/root.go) + DryRun bool } // DeleteService is the narrow SDK surface this command depends on. @@ -50,31 +53,35 @@ without the user's explicit go-ahead.`, weknora doc delete doc_abc -y --json # envelope output`, Args: cobra.ExactArgs(1), RunE: func(c *cobra.Command, args []string) error { + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } opts.Yes, _ = c.Flags().GetBool("yes") opts.DryRun = cmdutil.IsDryRun(c) if opts.DryRun { - return runDelete(c.Context(), opts, nil, f.Prompter(), args[0]) + return runDelete(c.Context(), opts, jopts, nil, f.Prompter(), args[0]) } cli, err := f.Client() if err != nil { return err } - return runDelete(c.Context(), opts, cli, f.Prompter(), args[0]) + return runDelete(c.Context(), opts, jopts, cli, f.Prompter(), args[0]) }, } - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, docDeleteFields) agent.SetAgentHelp(cmd, "Destructively deletes one document by id. ALWAYS pass -y/--yes in agent mode (no TTY ⇒ confirm prompt fails). Returns data: {id, deleted:true}.") return cmd } -func runDelete(ctx context.Context, opts *DeleteOptions, svc DeleteService, p prompt.Prompter, id string) error { +func runDelete(ctx context.Context, opts *DeleteOptions, jopts *cmdutil.JSONOptions, svc DeleteService, p prompt.Prompter, id string) error { if opts.DryRun { - return cmdutil.EmitDryRun(opts.JSONOut, + return cmdutil.EmitDryRun(jopts.Enabled(), deleteResult{ID: id, Deleted: false}, nil, &format.Risk{Level: format.RiskHighRiskWrite, Action: fmt.Sprintf("delete document %s", id)}) } - if err := cmdutil.ConfirmDestructive(p, opts.Yes, opts.JSONOut, "document", id); err != nil { + if err := cmdutil.ConfirmDestructive(p, opts.Yes, jopts.Enabled(), "document", id); err != nil { return err } @@ -82,9 +89,9 @@ func runDelete(ctx context.Context, opts *DeleteOptions, svc DeleteService, p pr return cmdutil.WrapHTTP(err, "delete document %s", id) } - if opts.JSONOut { + if jopts.Enabled() { risk := &format.Risk{Level: format.RiskHighRiskWrite, Action: fmt.Sprintf("deleted document %s", id)} - return format.WriteEnvelope(iostreams.IO.Out, format.SuccessWithRisk(deleteResult{ID: id, Deleted: true}, nil, risk)) + return format.WriteEnvelopeFiltered(iostreams.IO.Out, format.SuccessWithRisk(deleteResult{ID: id, Deleted: true}, nil, risk), jopts.Fields, jopts.JQ) } fmt.Fprintf(iostreams.IO.Out, "✓ Deleted document %s\n", id) return nil diff --git a/cli/cmd/doc/delete_test.go b/cli/cmd/doc/delete_test.go index de705098..8f39528f 100644 --- a/cli/cmd/doc/delete_test.go +++ b/cli/cmd/doc/delete_test.go @@ -49,7 +49,7 @@ func TestDelete_Success_WithForce(t *testing.T) { opts := &DeleteOptions{Yes: true} // Force=true short-circuits the confirm path; the prompter must not be // consulted, so any value works. - require.NoError(t, runDelete(context.Background(), opts, svc, scriptedConfirm{confirmReturn: false}, "doc_abc")) + require.NoError(t, runDelete(context.Background(), opts, nil, svc, scriptedConfirm{confirmReturn: false}, "doc_abc")) assert.Equal(t, "doc_abc", svc.got) assert.Equal(t, 1, svc.calls) @@ -60,8 +60,8 @@ func TestDelete_Success_WithForce(t *testing.T) { func TestDelete_Success_JSON(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakeDeleteSvc{} - opts := &DeleteOptions{Yes: true, JSONOut: true} - require.NoError(t, runDelete(context.Background(), opts, svc, scriptedConfirm{confirmReturn: true}, "doc_abc")) + opts := &DeleteOptions{Yes: true} + require.NoError(t, runDelete(context.Background(), opts, &cmdutil.JSONOptions{}, svc, scriptedConfirm{confirmReturn: true}, "doc_abc")) got := out.String() assert.True(t, strings.HasPrefix(got, `{"ok":true`), "envelope should start with ok:true; got %q", got) @@ -72,7 +72,7 @@ func TestDelete_Success_JSON(t *testing.T) { func TestDelete_NotFound_404(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakeDeleteSvc{err: errors.New("HTTP error 404: not found")} - err := runDelete(context.Background(), &DeleteOptions{Yes: true}, svc, scriptedConfirm{}, "doc_missing") + err := runDelete(context.Background(), &DeleteOptions{Yes: true}, nil, svc, scriptedConfirm{}, "doc_missing") require.Error(t, err) var typed *cmdutil.Error @@ -83,7 +83,7 @@ func TestDelete_NotFound_404(t *testing.T) { func TestDelete_HTTPError_500(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakeDeleteSvc{err: errors.New("HTTP error 500: internal")} - err := runDelete(context.Background(), &DeleteOptions{Yes: true}, svc, scriptedConfirm{}, "doc_x") + err := runDelete(context.Background(), &DeleteOptions{Yes: true}, nil, svc, scriptedConfirm{}, "doc_x") require.Error(t, err) var typed *cmdutil.Error @@ -94,7 +94,7 @@ func TestDelete_HTTPError_500(t *testing.T) { func TestDelete_ConfirmYes(t *testing.T) { out, _ := iostreams.SetForTestWithTTY(t) svc := &fakeDeleteSvc{} - err := runDelete(context.Background(), &DeleteOptions{Yes: false}, svc, scriptedConfirm{confirmReturn: true}, "doc_abc") + err := runDelete(context.Background(), &DeleteOptions{Yes: false}, nil, svc, scriptedConfirm{confirmReturn: true}, "doc_abc") require.NoError(t, err) assert.Equal(t, 1, svc.calls, "user said yes ⇒ delete proceeds") assert.Contains(t, out.String(), "✓") @@ -103,7 +103,7 @@ func TestDelete_ConfirmYes(t *testing.T) { func TestDelete_ConfirmNo(t *testing.T) { _, errBuf := iostreams.SetForTestWithTTY(t) svc := &fakeDeleteSvc{} - err := runDelete(context.Background(), &DeleteOptions{Yes: false}, svc, scriptedConfirm{confirmReturn: false}, "doc_abc") + err := runDelete(context.Background(), &DeleteOptions{Yes: false}, nil, svc, scriptedConfirm{confirmReturn: false}, "doc_abc") require.Error(t, err) assert.Equal(t, 0, svc.calls, "user said no ⇒ SDK must NOT be called") @@ -119,7 +119,7 @@ func TestDelete_ConfirmNo(t *testing.T) { func TestDelete_AgentPrompterErrors(t *testing.T) { _, _ = iostreams.SetForTestWithTTY(t) svc := &fakeDeleteSvc{} - err := runDelete(context.Background(), &DeleteOptions{Yes: false}, svc, errPrompter{}, "doc_abc") + err := runDelete(context.Background(), &DeleteOptions{Yes: false}, nil, svc, errPrompter{}, "doc_abc") require.Error(t, err) assert.Equal(t, 0, svc.calls) @@ -135,7 +135,7 @@ func TestDelete_AgentPrompterErrors(t *testing.T) { func TestDelete_NoYes_NonTTY_RequiresConfirmation(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakeDeleteSvc{} - err := runDelete(context.Background(), &DeleteOptions{Yes: false}, svc, errPrompter{}, "doc_abc") + err := runDelete(context.Background(), &DeleteOptions{Yes: false}, nil, svc, errPrompter{}, "doc_abc") require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) diff --git a/cli/cmd/doc/list.go b/cli/cmd/doc/list.go index df78858c..2541ca05 100644 --- a/cli/cmd/doc/list.go +++ b/cli/cmd/doc/list.go @@ -17,10 +17,20 @@ import ( sdk "github.com/Tencent/WeKnora/client" ) +// docListFields enumerates the fields surfaced for `--json` discovery on +// `doc list`. These are the per-item (Knowledge) fields, not the envelope +// wrappers (items/page/total/kb_id) — filtering applies to data.items[*]. +var docListFields = []string{ + "id", "knowledge_base_id", "tag_id", "type", "title", "description", + "source", "channel", "parse_status", "summary_status", "enable_status", + "embedding_model_id", "file_name", "file_type", "file_size", "file_hash", + "file_path", "storage_size", + "created_at", "updated_at", "processed_at", "error_message", +} + type ListOptions struct { Page int PageSize int - JSONOut bool } // ListService is the narrow SDK surface this command depends on. @@ -61,6 +71,10 @@ backend storage order is not guaranteed and varies between deployments.`, weknora doc list --page 2 --json # paginated envelope output`, Args: cobra.NoArgs, RunE: func(c *cobra.Command, _ []string) error { + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } kbID, err := f.ResolveKB(c) if err != nil { return err @@ -69,7 +83,7 @@ backend storage order is not guaranteed and varies between deployments.`, if err != nil { return err } - return runList(c.Context(), opts, cli, kbID) + return runList(c.Context(), opts, jopts, cli, kbID) }, } // --kb is read by Factory.ResolveKB; declare it here so cobra parses the @@ -77,12 +91,12 @@ backend storage order is not guaranteed and varies between deployments.`, cmd.Flags().String("kb", "", "Knowledge base UUID or name (overrides env / project link)") cmd.Flags().IntVar(&opts.Page, "page", 1, "Page number (1-based)") cmd.Flags().IntVar(&opts.PageSize, "page-size", 20, "Items per page (1..1000)") - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, docListFields) agent.SetAgentHelp(cmd, "Lists docs in the resolved KB. Returns data: {items, page, page_size, total, kb_id}; pass --kb when not running inside a project.") return cmd } -func runList(ctx context.Context, opts *ListOptions, svc ListService, kbID string) error { +func runList(ctx context.Context, opts *ListOptions, jopts *cmdutil.JSONOptions, svc ListService, kbID string) error { if opts.Page < 1 { return &cmdutil.Error{ Code: cmdutil.CodeInputInvalidArgument, @@ -116,8 +130,8 @@ func runList(ctx context.Context, opts *ListOptions, svc ListService, kbID strin Total: total, KBID: kbID, } - if opts.JSONOut { - return format.WriteEnvelope(iostreams.IO.Out, format.Success(r, &format.Meta{KBID: kbID})) + if jopts.Enabled() { + return format.WriteEnvelopeFiltered(iostreams.IO.Out, format.Success(r, &format.Meta{KBID: kbID}), jopts.Fields, jopts.JQ) } if len(items) == 0 { diff --git a/cli/cmd/doc/list_test.go b/cli/cmd/doc/list_test.go index d51b87ac..e37470d8 100644 --- a/cli/cmd/doc/list_test.go +++ b/cli/cmd/doc/list_test.go @@ -56,7 +56,7 @@ func TestList_Success_Human(t *testing.T) { } svc := &fakeListSvc{items: items, total: 2} opts := &ListOptions{Page: 1, PageSize: 20} - require.NoError(t, runList(context.Background(), opts, svc, "kb_xxx")) + require.NoError(t, runList(context.Background(), opts, nil, svc, "kb_xxx")) assert.Equal(t, "kb_xxx", svc.got.kbID) assert.Equal(t, 1, svc.got.page) @@ -74,8 +74,8 @@ func TestList_Success_Human(t *testing.T) { func TestList_Success_JSON(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakeListSvc{items: []sdk.Knowledge{{ID: "doc1", FileName: "a.pdf"}}, total: 1} - opts := &ListOptions{Page: 1, PageSize: 20, JSONOut: true} - require.NoError(t, runList(context.Background(), opts, svc, "kb_xxx")) + opts := &ListOptions{Page: 1, PageSize: 20} + require.NoError(t, runList(context.Background(), opts, &cmdutil.JSONOptions{}, svc, "kb_xxx")) got := out.String() assert.True(t, strings.HasPrefix(got, `{"ok":true`), "envelope should start with ok:true; got %q", got) @@ -91,15 +91,15 @@ func TestList_Empty_Human(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakeListSvc{items: nil, total: 0} opts := &ListOptions{Page: 1, PageSize: 20} - require.NoError(t, runList(context.Background(), opts, svc, "kb_xxx")) + require.NoError(t, runList(context.Background(), opts, nil, svc, "kb_xxx")) assert.Contains(t, out.String(), "(no documents)") } func TestList_Empty_JSON(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakeListSvc{items: nil, total: 0} - opts := &ListOptions{Page: 1, PageSize: 20, JSONOut: true} - require.NoError(t, runList(context.Background(), opts, svc, "kb_xxx")) + opts := &ListOptions{Page: 1, PageSize: 20} + require.NoError(t, runList(context.Background(), opts, &cmdutil.JSONOptions{}, svc, "kb_xxx")) got := out.String() assert.Contains(t, got, `"items":[]`, "items must serialize as [] not null") @@ -110,7 +110,7 @@ func TestList_HTTPError_500(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakeListSvc{err: errors.New("HTTP error 500: internal")} opts := &ListOptions{Page: 1, PageSize: 20} - err := runList(context.Background(), opts, svc, "kb_xxx") + err := runList(context.Background(), opts, nil, svc, "kb_xxx") require.Error(t, err) var typed *cmdutil.Error @@ -188,7 +188,7 @@ func TestList_SortByUpdatedDesc(t *testing.T) { {ID: "new", FileName: "new.pdf", UpdatedAt: now.Add(-1 * time.Hour)}, } svc := &fakeListSvc{items: items, total: 2} - require.NoError(t, runList(context.Background(), &ListOptions{Page: 1, PageSize: 20}, svc, "kb_xxx")) + require.NoError(t, runList(context.Background(), &ListOptions{Page: 1, PageSize: 20}, nil, svc, "kb_xxx")) got := out.String() newIdx := strings.Index(got, "new.pdf") diff --git a/cli/cmd/doc/upload.go b/cli/cmd/doc/upload.go index 4c757cce..6705b38b 100644 --- a/cli/cmd/doc/upload.go +++ b/cli/cmd/doc/upload.go @@ -2,6 +2,7 @@ package doc import ( "context" + "errors" "fmt" "os" @@ -19,11 +20,22 @@ import ( // and "wechat" (mini-program). The server uses this only for analytics. const uploadChannel = "api" +// docUploadFields enumerates the fields surfaced for `--json` discovery on +// `doc upload`. The single-file upload result is the full Knowledge struct; +// these are its top-level json tags. +var docUploadFields = []string{ + "id", "knowledge_base_id", "tag_id", "type", "title", "description", + "source", "channel", "parse_status", "summary_status", "enable_status", + "embedding_model_id", "file_name", "file_type", "file_size", "file_hash", + "file_path", "storage_size", + "created_at", "updated_at", "processed_at", "error_message", +} + type UploadOptions struct { Name string Recursive bool // --recursive: positional arg is a directory; walk + upload each match Glob string // --glob: filename pattern under --recursive (default "*") - JSONOut bool + FromURL string // --from-url: ingest a remote URL via SDK CreateKnowledgeFromURL DryRun bool } @@ -37,6 +49,11 @@ type UploadService interface { enableMultimodel *bool, customFileName, channel string, ) (*sdk.Knowledge, error) + CreateKnowledgeFromURL( + ctx context.Context, + kbID string, + req sdk.CreateKnowledgeFromURLRequest, + ) (*sdk.Knowledge, error) } // NewCmdUpload builds `weknora doc upload `. @@ -59,47 +76,138 @@ Use --recursive --glob to upload a directory tree (see Examples).`, weknora doc upload notes.md --kb a32a63ff-fb36-4874-bcaa-30f48570a694 weknora doc upload notes.md --kb my-kb weknora doc upload q3.pdf --name "Q3 Marketing Report.pdf" - weknora doc upload ./docs --recursive --glob '*.pdf'`, - Args: cobra.ExactArgs(1), + weknora doc upload ./docs --recursive --glob '*.pdf' + weknora doc upload --from-url https://example.com/whitepaper.pdf + weknora doc upload --from-url https://example.com/article.html --name "Q3 Article"`, + Args: cobra.MaximumNArgs(1), RunE: func(c *cobra.Command, args []string) error { - path := args[0] + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } opts.DryRun = cmdutil.IsDryRun(c) + if err := validateUploadFlags(opts, args); err != nil { + return err + } kbID, err := f.ResolveKB(c) if err != nil { return err } - if opts.Recursive { - if opts.DryRun { - return runUploadRecursive(c.Context(), opts, nil, kbID, path) - } - cli, err := f.Client() + + // Resolve the SDK client once; dry-run paths take nil and never + // dereference it. Hoisting avoids three near-identical + // `cli, err := f.Client()` blocks across the dispatch branches. + var cli UploadService + if !opts.DryRun { + sdkCli, err := f.Client() if err != nil { return err } - return runUploadRecursive(c.Context(), opts, cli, kbID, path) + cli = sdkCli } - if err := validateUploadPath(path); err != nil { - return err + + switch { + case opts.FromURL != "": + return runUploadFromURL(c.Context(), opts, jopts, cli, kbID) + case opts.Recursive: + return runUploadRecursive(c.Context(), opts, jopts, cli, kbID, args[0]) + default: + if err := validateUploadPath(args[0]); err != nil { + return err + } + return runUpload(c.Context(), opts, jopts, cli, kbID, args[0]) } - if opts.DryRun { - return runUpload(c.Context(), opts, nil, kbID, path) - } - cli, err := f.Client() - if err != nil { - return err - } - return runUpload(c.Context(), opts, cli, kbID, path) }, } cmd.Flags().String("kb", "", "Knowledge base UUID or name (overrides env / project link)") cmd.Flags().StringVar(&opts.Name, "name", "", "Custom file name to record (defaults to base name)") cmd.Flags().BoolVar(&opts.Recursive, "recursive", false, "Treat the positional argument as a directory to walk") cmd.Flags().StringVar(&opts.Glob, "glob", "*", "Filename pattern to filter when --recursive (e.g. '*.pdf')") - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") - agent.SetAgentHelp(cmd, "Uploads to the resolved KB. Default: one regular file (refuses dir/non-regular). With --recursive: walks the directory, filters by --glob, uploads each match sequentially with per-file OK/FAIL output. Exit 1 on any per-file failure, exit 0 only on full success. Returns data: single Knowledge object (default) or aggregate report (recursive).") + cmd.Flags().StringVar(&opts.FromURL, "from-url", "", "Ingest a remote `URL` (HTTP/HTTPS) instead of a local file") + cmdutil.AddJSONFlags(cmd, docUploadFields) + agent.SetAgentHelp(cmd, "Uploads to the resolved KB. Default: one local regular file. With --recursive: walks the directory, filters by --glob, uploads each match. With --from-url: ingests a remote URL (mutually exclusive with the positional file / --recursive / --glob). Returns data: single Knowledge object (file or URL) or aggregate report (recursive). Errors: resource.already_exists when the URL was previously ingested.") return cmd } +// validateUploadFlags enforces mutual exclusion between the three input +// modes (positional file path / --recursive directory walk / --from-url +// remote ingest) and validates the URL when --from-url is set. +func validateUploadFlags(opts *UploadOptions, args []string) error { + hasPath := len(args) == 1 + hasURL := opts.FromURL != "" + if hasURL { + if hasPath { + return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, + "cannot pass a file path with --from-url; choose one input mode") + } + if opts.Recursive { + return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, + "--recursive cannot be combined with --from-url") + } + return cmdutil.ValidateHTTPURL("--from-url", opts.FromURL) + } + if !hasPath { + return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, + "a file path is required (or pass --from-url)") + } + return nil +} + +// runUploadFromURL ingests a remote URL via SDK CreateKnowledgeFromURL. +// `--name` becomes the FileName hint so the server's "known file extension" +// detection upgrades crawl-mode to file-download-mode when appropriate. +func runUploadFromURL(ctx context.Context, opts *UploadOptions, jopts *cmdutil.JSONOptions, svc UploadService, kbID string) error { + if opts.DryRun { + return cmdutil.EmitDryRun(jopts.Enabled(), + map[string]string{"from_url": opts.FromURL, "kb_id": kbID, "name": opts.Name}, + &format.Meta{KBID: kbID}, + &format.Risk{Level: format.RiskWrite, Action: fmt.Sprintf("ingest URL %s into kb %s", opts.FromURL, kbID)}) + } + + req := sdk.CreateKnowledgeFromURLRequest{ + URL: opts.FromURL, + FileName: opts.Name, + Channel: uploadChannel, + } + k, err := svc.CreateKnowledgeFromURL(ctx, kbID, req) + if err != nil { + if errors.Is(err, sdk.ErrDuplicateURL) { + // Server returns 409 with the existing knowledge entry's data. + // Surface as resource.already_exists; the data payload (if any) + // is observable via err's wrap chain — but the typed code is + // what agents branch on. + return cmdutil.Wrapf(cmdutil.CodeResourceAlreadyExists, err, + "URL already ingested into this knowledge base") + } + return cmdutil.WrapHTTP(err, "ingest URL %s", opts.FromURL) + } + + return printUploadSuccess(k, jopts, kbID, "ingested", "Ingested", opts.FromURL, opts.Name, opts.FromURL) +} + +// printUploadSuccess emits the post-upload result envelope (--json path) +// or the human checkmark line. Shared by single-file upload and URL ingest; +// the verb (upload/ingest), risk-action verb (uploaded/ingested), and the +// fallback display source (local path vs source URL) are the only varying +// pieces. +func printUploadSuccess(k *sdk.Knowledge, jopts *cmdutil.JSONOptions, kbID, riskVerb, humanVerb, source, customName, fallbackDisplay string) error { + if jopts.Enabled() { + risk := &format.Risk{Level: format.RiskWrite, Action: fmt.Sprintf("%s %s", riskVerb, source)} + return format.WriteEnvelopeFiltered(iostreams.IO.Out, + format.SuccessWithRisk(k, &format.Meta{KBID: kbID}, risk), + jopts.Fields, jopts.JQ) + } + displayed := customName + if displayed == "" { + displayed = k.FileName + } + if displayed == "" { + displayed = fallbackDisplay + } + fmt.Fprintf(iostreams.IO.Out, "✓ %s %q (id: %s)\n", humanVerb, displayed, k.ID) + return nil +} + // validateUploadPath checks that path exists and refers to a regular file. // Symlinks and directories are rejected up-front so users get a typed error // instead of an opaque SDK failure mid-upload. os.Stat (not Lstat) is used @@ -121,9 +229,9 @@ func validateUploadPath(path string) error { return nil } -func runUpload(ctx context.Context, opts *UploadOptions, svc UploadService, kbID, path string) error { +func runUpload(ctx context.Context, opts *UploadOptions, jopts *cmdutil.JSONOptions, svc UploadService, kbID, path string) error { if opts.DryRun { - return cmdutil.EmitDryRun(opts.JSONOut, + return cmdutil.EmitDryRun(jopts.Enabled(), map[string]string{"file": path, "kb_id": kbID, "name": opts.Name}, &format.Meta{KBID: kbID}, &format.Risk{Level: format.RiskWrite, Action: fmt.Sprintf("upload %s to kb %s", path, kbID)}) @@ -133,18 +241,5 @@ func runUpload(ctx context.Context, opts *UploadOptions, svc UploadService, kbID if err != nil { return cmdutil.WrapHTTP(err, "upload %s", path) } - - if opts.JSONOut { - risk := &format.Risk{Level: format.RiskWrite, Action: fmt.Sprintf("uploaded %s", path)} - return format.WriteEnvelope(iostreams.IO.Out, format.SuccessWithRisk(k, &format.Meta{KBID: kbID}, risk)) - } - displayed := opts.Name - if displayed == "" { - displayed = k.FileName - } - if displayed == "" { - displayed = path - } - fmt.Fprintf(iostreams.IO.Out, "✓ Uploaded %q (id: %s)\n", displayed, k.ID) - return nil + return printUploadSuccess(k, jopts, kbID, "uploaded", "Uploaded", path, opts.Name, path) } diff --git a/cli/cmd/doc/upload_recursive.go b/cli/cmd/doc/upload_recursive.go index 4d1350f7..e63e574c 100644 --- a/cli/cmd/doc/upload_recursive.go +++ b/cli/cmd/doc/upload_recursive.go @@ -25,7 +25,7 @@ type uploadOutcome struct { // in one run. Exit semantics: nil error on full success, a typed *cmdutil.Error // when ≥1 file failed (the typed code mirrors the first failure's // classification so callers can still branch). -func runUploadRecursive(ctx context.Context, opts *UploadOptions, svc UploadService, kbID, dir string) error { +func runUploadRecursive(ctx context.Context, opts *UploadOptions, jopts *cmdutil.JSONOptions, svc UploadService, kbID, dir string) error { if opts.Name != "" { return &cmdutil.Error{ Code: cmdutil.CodeInputInvalidArgument, @@ -62,9 +62,9 @@ func runUploadRecursive(ctx context.Context, opts *UploadOptions, svc UploadServ return cmdutil.Wrapf(cmdutil.CodeLocalFileIO, err, "walk %s", dir) } if len(matches) == 0 { - if opts.JSONOut { - return format.WriteEnvelope(iostreams.IO.Out, format.Success( - recursiveResult{KBID: kbID}, &format.Meta{KBID: kbID})) + if jopts.Enabled() { + return format.WriteEnvelopeFiltered(iostreams.IO.Out, format.Success( + recursiveResult{KBID: kbID}, &format.Meta{KBID: kbID}), jopts.Fields, jopts.JQ) } fmt.Fprintf(iostreams.IO.Out, "(no files matched %q under %s)\n", opts.Glob, dir) return nil @@ -75,7 +75,7 @@ func runUploadRecursive(ctx context.Context, opts *UploadOptions, svc UploadServ for _, m := range matches { previews = append(previews, uploadOutcome{Path: m}) } - return cmdutil.EmitDryRun(opts.JSONOut, + return cmdutil.EmitDryRun(jopts.Enabled(), recursiveResult{KBID: kbID, Uploaded: previews}, &format.Meta{KBID: kbID}, &format.Risk{Level: format.RiskWrite, Action: fmt.Sprintf("upload %d file(s) to kb %s", len(matches), kbID)}) @@ -93,7 +93,7 @@ func runUploadRecursive(ctx context.Context, opts *UploadOptions, svc UploadServ failed = append(failed, uploadOutcome{Path: p, Error: err.Error()}) // Per-file progress lines are human progress signal; suppress // under --json so they don't precede the envelope on stdout. - if !opts.JSONOut { + if !jopts.Enabled() { fmt.Fprintf(iostreams.IO.Out, "FAIL %s: %v\n", filepath.Base(p), err) } continue @@ -103,16 +103,16 @@ func runUploadRecursive(ctx context.Context, opts *UploadOptions, svc UploadServ id = k.ID } uploaded = append(uploaded, uploadOutcome{Path: p, ID: id}) - if !opts.JSONOut { + if !jopts.Enabled() { fmt.Fprintf(iostreams.IO.Out, "OK %s (id: %s)\n", filepath.Base(p), id) } } - if opts.JSONOut { + if jopts.Enabled() { result := recursiveResult{KBID: kbID, Uploaded: uploaded, Failed: failed} risk := &format.Risk{Level: format.RiskWrite, Action: fmt.Sprintf("upload %d file(s) to kb %s", len(matches), kbID)} - if err := format.WriteEnvelope(iostreams.IO.Out, - format.SuccessWithRisk(result, &format.Meta{KBID: kbID}, risk)); err != nil { + if err := format.WriteEnvelopeFiltered(iostreams.IO.Out, + format.SuccessWithRisk(result, &format.Meta{KBID: kbID}, risk), jopts.Fields, jopts.JQ); err != nil { return err } } else { @@ -128,7 +128,7 @@ func runUploadRecursive(ctx context.Context, opts *UploadOptions, svc UploadServ return &cmdutil.Error{ Code: firstFailCode, Message: fmt.Sprintf("%d of %d uploads failed", len(failed), len(matches)), - Silent: opts.JSONOut, + Silent: jopts.Enabled(), } } return nil diff --git a/cli/cmd/doc/upload_recursive_test.go b/cli/cmd/doc/upload_recursive_test.go index 38704674..28c399da 100644 --- a/cli/cmd/doc/upload_recursive_test.go +++ b/cli/cmd/doc/upload_recursive_test.go @@ -42,6 +42,16 @@ func (s *scriptedUploadSvc) CreateKnowledgeFromFile( return r.k, r.err } +// CreateKnowledgeFromURL satisfies UploadService but is unused by the +// recursive-walk path. Recursive upload only goes through CreateKnowledgeFromFile. +func (s *scriptedUploadSvc) CreateKnowledgeFromURL( + _ context.Context, + _ string, + _ sdk.CreateKnowledgeFromURLRequest, +) (*sdk.Knowledge, error) { + return nil, nil +} + func mkTree(t *testing.T, base string, names ...string) { t.Helper() for _, n := range names { @@ -58,7 +68,7 @@ func TestUploadRecursive_WalksAllFiles(t *testing.T) { svc := &scriptedUploadSvc{} opts := &UploadOptions{Recursive: true, Glob: "*"} - require.NoError(t, runUploadRecursive(context.Background(), opts, svc, "kb_xxx", dir)) + require.NoError(t, runUploadRecursive(context.Background(), opts, nil, svc, "kb_xxx", dir)) sort.Strings(svc.called) assert.Equal(t, []string{"a.pdf", "b.pdf", "c.pdf"}, svc.called) @@ -75,7 +85,7 @@ func TestUploadRecursive_GlobFilter(t *testing.T) { svc := &scriptedUploadSvc{} opts := &UploadOptions{Recursive: true, Glob: "*.pdf"} - require.NoError(t, runUploadRecursive(context.Background(), opts, svc, "kb_xxx", dir)) + require.NoError(t, runUploadRecursive(context.Background(), opts, nil, svc, "kb_xxx", dir)) sort.Strings(svc.called) assert.Equal(t, []string{"doc.pdf", "keep.pdf"}, svc.called) @@ -93,7 +103,7 @@ func TestUploadRecursive_PartialFailure_Exits1(t *testing.T) { "bad.pdf": {err: errors.New("HTTP error 500: internal")}, }} opts := &UploadOptions{Recursive: true, Glob: "*"} - err := runUploadRecursive(context.Background(), opts, svc, "kb_xxx", dir) + err := runUploadRecursive(context.Background(), opts, nil, svc, "kb_xxx", dir) require.Error(t, err) var typed *cmdutil.Error @@ -116,7 +126,7 @@ func TestUploadRecursive_NoMatches(t *testing.T) { svc := &scriptedUploadSvc{} opts := &UploadOptions{Recursive: true, Glob: "*.pdf"} - require.NoError(t, runUploadRecursive(context.Background(), opts, svc, "kb_xxx", dir)) + require.NoError(t, runUploadRecursive(context.Background(), opts, nil, svc, "kb_xxx", dir)) assert.Len(t, svc.called, 0) assert.Contains(t, strings.ToLower(out.String()), "no files matched") } @@ -125,7 +135,7 @@ func TestUploadRecursive_NotADirectory(t *testing.T) { _, _ = iostreams.SetForTest(t) path := writeTempFile(t, "single.pdf") svc := &scriptedUploadSvc{} - err := runUploadRecursive(context.Background(), &UploadOptions{Recursive: true, Glob: "*"}, svc, "kb_xxx", path) + err := runUploadRecursive(context.Background(), &UploadOptions{Recursive: true, Glob: "*"}, nil, svc, "kb_xxx", path) require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) @@ -139,7 +149,7 @@ func TestUploadRecursive_RejectsNameFlag(t *testing.T) { mkTree(t, dir, "a.pdf") svc := &scriptedUploadSvc{} opts := &UploadOptions{Recursive: true, Glob: "*", Name: "single-name.pdf"} - err := runUploadRecursive(context.Background(), opts, svc, "kb_xxx", dir) + err := runUploadRecursive(context.Background(), opts, nil, svc, "kb_xxx", dir) require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) @@ -158,8 +168,8 @@ func TestUploadRecursive_JSON_Envelope(t *testing.T) { }{ "bad.pdf": {err: errors.New("HTTP error 500: internal")}, }} - opts := &UploadOptions{Recursive: true, Glob: "*", JSONOut: true} - err := runUploadRecursive(context.Background(), opts, svc, "kb_xxx", dir) + opts := &UploadOptions{Recursive: true, Glob: "*"} + err := runUploadRecursive(context.Background(), opts, &cmdutil.JSONOptions{}, svc, "kb_xxx", dir) require.Error(t, err) // partial failure → typed error body := out.String() @@ -188,7 +198,7 @@ func TestUploadRecursive_DryRun(t *testing.T) { mkTree(t, dir, "a.pdf", "b.pdf") svc := &scriptedUploadSvc{} opts := &UploadOptions{Recursive: true, Glob: "*", DryRun: true} - require.NoError(t, runUploadRecursive(context.Background(), opts, svc, "kb_xxx", dir)) + require.NoError(t, runUploadRecursive(context.Background(), opts, nil, svc, "kb_xxx", dir)) assert.Len(t, svc.called, 0, "dry-run must not call SDK") got := out.String() assert.Contains(t, got, "would upload 2") diff --git a/cli/cmd/doc/upload_test.go b/cli/cmd/doc/upload_test.go index b7ebb055..c3c3b45b 100644 --- a/cli/cmd/doc/upload_test.go +++ b/cli/cmd/doc/upload_test.go @@ -18,12 +18,15 @@ import ( // fakeUploadSvc captures call arguments and returns canned responses. type fakeUploadSvc struct { - resp *sdk.Knowledge - err error - got struct { + resp *sdk.Knowledge + err error + urlResp *sdk.Knowledge + urlErr error + got struct { kbID, filePath, customName, channel string metadata map[string]string enableMultimodel *bool + urlReq sdk.CreateKnowledgeFromURLRequest } } @@ -43,6 +46,16 @@ func (f *fakeUploadSvc) CreateKnowledgeFromFile( return f.resp, f.err } +func (f *fakeUploadSvc) CreateKnowledgeFromURL( + _ context.Context, + kbID string, + req sdk.CreateKnowledgeFromURLRequest, +) (*sdk.Knowledge, error) { + f.got.kbID = kbID + f.got.urlReq = req + return f.urlResp, f.urlErr +} + // writeTempFile creates a regular file under t.TempDir() with sample content. func writeTempFile(t *testing.T, name string) string { t.Helper() @@ -56,7 +69,7 @@ func TestUpload_Success_Human(t *testing.T) { path := writeTempFile(t, "report.pdf") svc := &fakeUploadSvc{resp: &sdk.Knowledge{ID: "doc_99", FileName: "report.pdf"}} opts := &UploadOptions{} - require.NoError(t, runUpload(context.Background(), opts, svc, "kb_xxx", path)) + require.NoError(t, runUpload(context.Background(), opts, nil, svc, "kb_xxx", path)) assert.Equal(t, "kb_xxx", svc.got.kbID) assert.Equal(t, path, svc.got.filePath) @@ -78,7 +91,7 @@ func TestUpload_Success_CustomName(t *testing.T) { path := writeTempFile(t, "q3.pdf") svc := &fakeUploadSvc{resp: &sdk.Knowledge{ID: "doc_88", FileName: "q3.pdf"}} opts := &UploadOptions{Name: "Q3 Marketing Report.pdf"} - require.NoError(t, runUpload(context.Background(), opts, svc, "kb_xxx", path)) + require.NoError(t, runUpload(context.Background(), opts, nil, svc, "kb_xxx", path)) assert.Equal(t, "Q3 Marketing Report.pdf", svc.got.customName) } @@ -86,8 +99,8 @@ func TestUpload_Success_JSON(t *testing.T) { out, _ := iostreams.SetForTest(t) path := writeTempFile(t, "a.md") svc := &fakeUploadSvc{resp: &sdk.Knowledge{ID: "doc_77", FileName: "a.md"}} - opts := &UploadOptions{JSONOut: true} - require.NoError(t, runUpload(context.Background(), opts, svc, "kb_xxx", path)) + opts := &UploadOptions{} + require.NoError(t, runUpload(context.Background(), opts, &cmdutil.JSONOptions{}, svc, "kb_xxx", path)) got := out.String() assert.True(t, strings.HasPrefix(got, `{"ok":true`), "envelope should start with ok:true; got %q", got) @@ -100,7 +113,7 @@ func TestUpload_HTTPError_500(t *testing.T) { _, _ = iostreams.SetForTest(t) path := writeTempFile(t, "x.txt") svc := &fakeUploadSvc{err: errors.New("HTTP error 500: internal")} - err := runUpload(context.Background(), &UploadOptions{}, svc, "kb_xxx", path) + err := runUpload(context.Background(), &UploadOptions{}, nil, svc, "kb_xxx", path) require.Error(t, err) var typed *cmdutil.Error @@ -112,7 +125,7 @@ func TestUpload_HTTPError_409Conflict(t *testing.T) { _, _ = iostreams.SetForTest(t) path := writeTempFile(t, "dup.pdf") svc := &fakeUploadSvc{err: errors.New("HTTP error 409: file exists")} - err := runUpload(context.Background(), &UploadOptions{}, svc, "kb_xxx", path) + err := runUpload(context.Background(), &UploadOptions{}, nil, svc, "kb_xxx", path) require.Error(t, err) var typed *cmdutil.Error @@ -155,3 +168,105 @@ func TestValidateUploadPath_SymlinkToFileAccepted(t *testing.T) { // os.Stat (not Lstat) should follow the symlink and report regular file. require.NoError(t, validateUploadPath(link)) } + +// --from-url tests (4-N1). + +func TestUploadFromURL_Success_Human(t *testing.T) { + out, _ := iostreams.SetForTest(t) + svc := &fakeUploadSvc{urlResp: &sdk.Knowledge{ID: "doc_url_1", FileName: "whitepaper.pdf"}} + opts := &UploadOptions{FromURL: "https://example.com/whitepaper.pdf"} + require.NoError(t, runUploadFromURL(context.Background(), opts, nil, svc, "kb_xxx")) + + assert.Equal(t, "kb_xxx", svc.got.kbID) + assert.Equal(t, "https://example.com/whitepaper.pdf", svc.got.urlReq.URL) + assert.Equal(t, "api", svc.got.urlReq.Channel) + assert.Contains(t, out.String(), "Ingested") + assert.Contains(t, out.String(), "doc_url_1") +} + +func TestUploadFromURL_WithName_Passes_AsFileName(t *testing.T) { + _, _ = iostreams.SetForTest(t) + svc := &fakeUploadSvc{urlResp: &sdk.Knowledge{ID: "doc_url_2"}} + opts := &UploadOptions{FromURL: "https://example.com/article.html", Name: "Q3 Article"} + require.NoError(t, runUploadFromURL(context.Background(), opts, nil, svc, "kb_xxx")) + assert.Equal(t, "Q3 Article", svc.got.urlReq.FileName, + "--name must be forwarded as FileName (server uses it for file-vs-crawl mode hint)") +} + +func TestUploadFromURL_JSON_Envelope(t *testing.T) { + out, _ := iostreams.SetForTest(t) + svc := &fakeUploadSvc{urlResp: &sdk.Knowledge{ID: "doc_url_3", FileName: "ok.pdf"}} + jopts := &cmdutil.JSONOptions{} + require.NoError(t, runUploadFromURL(context.Background(), + &UploadOptions{FromURL: "https://example.com/ok.pdf"}, jopts, svc, "kb_xxx")) + assert.Contains(t, out.String(), `"ok":true`) + assert.Contains(t, out.String(), `"id":"doc_url_3"`) + assert.Contains(t, out.String(), `"risk":{"level":"write"`) +} + +func TestUploadFromURL_DryRun(t *testing.T) { + out, _ := iostreams.SetForTest(t) + svc := &fakeUploadSvc{} // must not be called + jopts := &cmdutil.JSONOptions{} + opts := &UploadOptions{FromURL: "https://example.com/x.pdf", DryRun: true} + require.NoError(t, runUploadFromURL(context.Background(), opts, jopts, svc, "kb_xxx")) + got := out.String() + assert.Contains(t, got, `"dry_run":true`) + assert.Contains(t, got, `"from_url"`) + assert.Empty(t, svc.got.urlReq.URL, "SDK call must NOT fire on --dry-run") +} + +func TestUploadFromURL_DuplicateURLMaps_resource_already_exists(t *testing.T) { + _, _ = iostreams.SetForTest(t) + svc := &fakeUploadSvc{ + urlResp: &sdk.Knowledge{ID: "doc_existing"}, + urlErr: sdk.ErrDuplicateURL, + } + err := runUploadFromURL(context.Background(), + &UploadOptions{FromURL: "https://example.com/dup.pdf"}, nil, svc, "kb_xxx") + require.Error(t, err) + var typed *cmdutil.Error + require.ErrorAs(t, err, &typed) + assert.Equal(t, cmdutil.CodeResourceAlreadyExists, typed.Code) +} + +func TestValidateUploadFlags_FromURL_OK(t *testing.T) { + require.NoError(t, validateUploadFlags(&UploadOptions{FromURL: "https://example.com/x.pdf"}, nil)) +} + +func TestValidateUploadFlags_FromURL_WithPositional_Rejected(t *testing.T) { + err := validateUploadFlags(&UploadOptions{FromURL: "https://example.com/x.pdf"}, []string{"/tmp/x.pdf"}) + require.Error(t, err) + var typed *cmdutil.Error + require.ErrorAs(t, err, &typed) + assert.Equal(t, cmdutil.CodeInputInvalidArgument, typed.Code) +} + +func TestValidateUploadFlags_FromURL_WithRecursive_Rejected(t *testing.T) { + err := validateUploadFlags(&UploadOptions{FromURL: "https://example.com/x.pdf", Recursive: true}, nil) + require.Error(t, err) + var typed *cmdutil.Error + require.ErrorAs(t, err, &typed) + assert.Equal(t, cmdutil.CodeInputInvalidArgument, typed.Code) +} + +func TestValidateUploadFlags_FromURL_BadScheme(t *testing.T) { + err := validateUploadFlags(&UploadOptions{FromURL: "file:///etc/passwd"}, nil) + require.Error(t, err) + var typed *cmdutil.Error + require.ErrorAs(t, err, &typed) + assert.Equal(t, cmdutil.CodeInputInvalidArgument, typed.Code) +} + +func TestValidateUploadFlags_FromURL_NoHost(t *testing.T) { + err := validateUploadFlags(&UploadOptions{FromURL: "https://"}, nil) + require.Error(t, err) +} + +func TestValidateUploadFlags_NoPathOrURL_Rejected(t *testing.T) { + err := validateUploadFlags(&UploadOptions{}, nil) + require.Error(t, err) + var typed *cmdutil.Error + require.ErrorAs(t, err, &typed) + assert.Equal(t, cmdutil.CodeInputInvalidArgument, typed.Code) +} diff --git a/cli/cmd/doc/view.go b/cli/cmd/doc/view.go index da6931d0..24d5bb2f 100644 --- a/cli/cmd/doc/view.go +++ b/cli/cmd/doc/view.go @@ -14,10 +14,18 @@ import ( sdk "github.com/Tencent/WeKnora/client" ) -type ViewOptions struct { - JSONOut bool +// docViewFields enumerates the fields surfaced for `--json` discovery on +// `doc view`. Lists the Knowledge struct top-level json tags. +var docViewFields = []string{ + "id", "knowledge_base_id", "tag_id", "type", "title", "description", + "source", "channel", "parse_status", "summary_status", "enable_status", + "embedding_model_id", "file_name", "file_type", "file_size", "file_hash", + "file_path", "storage_size", + "created_at", "updated_at", "processed_at", "error_message", } +type ViewOptions struct{} + // ViewService is the narrow SDK surface this command depends on. type ViewService interface { GetKnowledge(ctx context.Context, id string) (*sdk.Knowledge, error) @@ -33,25 +41,29 @@ func NewCmdView(f *cmdutil.Factory) *cobra.Command { weknora doc view doc_abc --json`, Args: cobra.ExactArgs(1), RunE: func(c *cobra.Command, args []string) error { + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } cli, err := f.Client() if err != nil { return err } - return runView(c.Context(), opts, cli, args[0]) + return runView(c.Context(), opts, jopts, cli, args[0]) }, } - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, docViewFields) agent.SetAgentHelp(cmd, "Returns the full Knowledge object for one document: id, kb_id, file metadata, parse_status, processed_at, error_message. Use this instead of paging through `doc list` when you have the doc id.") return cmd } -func runView(ctx context.Context, opts *ViewOptions, svc ViewService, id string) error { +func runView(ctx context.Context, opts *ViewOptions, jopts *cmdutil.JSONOptions, svc ViewService, id string) error { doc, err := svc.GetKnowledge(ctx, id) if err != nil { return cmdutil.WrapHTTP(err, "get document %q", id) } - if opts.JSONOut { - return format.WriteEnvelope(iostreams.IO.Out, format.Success(doc, &format.Meta{KBID: doc.KnowledgeBaseID})) + if jopts.Enabled() { + return format.WriteEnvelopeFiltered(iostreams.IO.Out, format.Success(doc, &format.Meta{KBID: doc.KnowledgeBaseID}), jopts.Fields, jopts.JQ) } w := iostreams.IO.Out fmt.Fprintf(w, "ID: %s\n", doc.ID) diff --git a/cli/cmd/doc/view_test.go b/cli/cmd/doc/view_test.go index 5d459b78..30f049ac 100644 --- a/cli/cmd/doc/view_test.go +++ b/cli/cmd/doc/view_test.go @@ -39,7 +39,7 @@ func TestView_Human_RendersExpectedFields(t *testing.T) { UpdatedAt: time.Date(2026, 1, 2, 0, 0, 0, 0, time.UTC), ProcessedAt: &processed, }} - if err := runView(context.Background(), &ViewOptions{}, svc, "doc_abc"); err != nil { + if err := runView(context.Background(), &ViewOptions{}, nil, svc, "doc_abc"); err != nil { t.Fatalf("runView: %v", err) } got := out.String() @@ -59,7 +59,7 @@ func TestView_Human_RendersExpectedFields(t *testing.T) { func TestView_Human_TitleFallback(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakeViewSvc{doc: &sdk.Knowledge{ID: "doc_url", Title: "Pasted article", FileName: ""}} - if err := runView(context.Background(), &ViewOptions{}, svc, "doc_url"); err != nil { + if err := runView(context.Background(), &ViewOptions{}, nil, svc, "doc_url"); err != nil { t.Fatalf("runView: %v", err) } got := out.String() @@ -77,7 +77,7 @@ func TestView_Human_OmitsEmptyFields(t *testing.T) { ID: "doc_abc", FileName: "x.txt", }} - if err := runView(context.Background(), &ViewOptions{}, svc, "doc_abc"); err != nil { + if err := runView(context.Background(), &ViewOptions{}, nil, svc, "doc_abc"); err != nil { t.Fatalf("runView: %v", err) } // Line-prefix match (not substring): "ERROR:" as a substring could @@ -97,7 +97,7 @@ func TestView_Human_OmitsEmptyFields(t *testing.T) { func TestView_JSON_EmitsEnvelope(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakeViewSvc{doc: &sdk.Knowledge{ID: "doc_abc", FileName: "x.txt", KnowledgeBaseID: "kb1"}} - if err := runView(context.Background(), &ViewOptions{JSONOut: true}, svc, "doc_abc"); err != nil { + if err := runView(context.Background(), &ViewOptions{}, &cmdutil.JSONOptions{}, svc, "doc_abc"); err != nil { t.Fatalf("runView: %v", err) } got := out.String() @@ -111,7 +111,7 @@ func TestView_JSON_EmitsEnvelope(t *testing.T) { func TestView_NotFound_ClassifiedAs404(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakeViewSvc{err: errors.New("HTTP error 404: not found")} - err := runView(context.Background(), &ViewOptions{}, svc, "missing") + err := runView(context.Background(), &ViewOptions{}, nil, svc, "missing") if err == nil { t.Fatal("expected error") } diff --git a/cli/cmd/doctor/doctor.go b/cli/cmd/doctor/doctor.go index 30694c01..b4566f76 100644 --- a/cli/cmd/doctor/doctor.go +++ b/cli/cmd/doctor/doctor.go @@ -39,10 +39,13 @@ import ( sdk "github.com/Tencent/WeKnora/client" ) +// doctorFields enumerates the fields surfaced for `--json` discovery on +// `doctor`. Items here refer to data.checks[*] entries (Check struct). +var doctorFields = []string{"name", "status", "details", "hint"} + type Options struct { NoCache bool Offline bool - JSONOut bool } // Status is the per-check outcome on the wire (JSON Marshal still emits the @@ -100,13 +103,17 @@ func NewCmd(f *cmdutil.Factory) *cobra.Command { Short: "Run 4 self-checks: base URL, auth, server version, credential storage", Args: cobra.NoArgs, RunE: func(c *cobra.Command, _ []string) error { + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } svc, err := buildServices(f) if err != nil { return err } cliVer, _, _ := build.Info() r := runChecks(c.Context(), opts, svc, cliVer) - emit(opts, r) + emit(jopts, r) // v0.2 exit-code policy: fail → exit 1; warn / ok / skip → exit 0. // SilentError suppresses both the human "error: ..." line and the // error envelope printer, so the data envelope already written by @@ -119,7 +126,7 @@ func NewCmd(f *cmdutil.Factory) *cobra.Command { } cmd.Flags().BoolVar(&opts.NoCache, "no-cache", false, "Bypass server-info cache (located at $XDG_CACHE_HOME/weknora/server-info.yaml); force re-probe") cmd.Flags().BoolVar(&opts.Offline, "offline", false, "Skip network checks; only verify local keyring/file storage (credential_storage check still runs)") - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, doctorFields) agent.SetAgentHelp(cmd, "Returns 4 health checks. AGENT short-circuit: read data.summary.all_passed; if false, inspect data.checks[].status (ok/warn/fail/skip). exit 1 only when any status=fail; warn does not change envelope.ok.") return cmd } @@ -329,12 +336,13 @@ func summarize(cs []Check) Summary { // rather than calling format.Success because envelope.ok must reflect "no // fail" — warn does not flip it (per package doc), but fail does. We can't // use format.Failure either, since that drops the data field. -func emit(opts *Options, r Result) { - if opts.JSONOut { - _ = format.WriteEnvelope(iostreams.IO.Out, format.Envelope{ - OK: r.Summary.Failed == 0, - Data: r, - }) +func emit(jopts *cmdutil.JSONOptions, r Result) { + if jopts.Enabled() { + _ = format.WriteEnvelopeFiltered( + iostreams.IO.Out, + format.Envelope{OK: r.Summary.Failed == 0, Data: r}, + jopts.Fields, jopts.JQ, + ) return } for _, c := range r.Checks { diff --git a/cli/cmd/doctor/doctor_test.go b/cli/cmd/doctor/doctor_test.go index 455c428b..b2213654 100644 --- a/cli/cmd/doctor/doctor_test.go +++ b/cli/cmd/doctor/doctor_test.go @@ -67,7 +67,7 @@ func TestDoctor_AllOK(t *testing.T) { systemInfo: &sdk.SystemInfo{Version: "1.0.0"}, userResp: goodUserResp(), } - r := runChecks(context.Background(), &Options{JSONOut: true}, svc, "1.0.0") + r := runChecks(context.Background(), &Options{}, svc, "1.0.0") if !r.Summary.AllPassed { t.Errorf("expected all_passed, got summary %+v", r.Summary) } @@ -77,7 +77,7 @@ func TestDoctor_AllOK(t *testing.T) { if r.Summary.Failed != 0 || r.Summary.Skipped != 0 { t.Errorf("expected 0 fail / 0 skip, got %+v", r.Summary) } - emit(&Options{JSONOut: true}, r) + emit(&cmdutil.JSONOptions{}, r) if !strings.Contains(out.String(), `"all_passed":true`) { t.Errorf("envelope should embed all_passed=true, got %q", out.String()) } @@ -280,7 +280,7 @@ func TestDoctor_VersionSkewWarns(t *testing.T) { // Envelope ok stays true (warn is non-blocking). out, _ := iostreams.SetForTest(t) - emit(&Options{JSONOut: true}, r) + emit(&cmdutil.JSONOptions{}, r) if !strings.Contains(out.String(), `"ok":true`) { t.Errorf("envelope.ok must be true on warn-only run, got %q", out.String()) } @@ -381,7 +381,7 @@ func TestDoctor_EmitEnvelope_OK_WhenWarnOnly(t *testing.T) { {Name: "credential_storage", Status: StatusOK}, }, } - emit(&Options{JSONOut: true}, r) + emit(&cmdutil.JSONOptions{}, r) got := out.String() if !strings.Contains(got, `"ok":true`) { t.Errorf("envelope.ok must be true on warn-only result, got %q", got) @@ -400,7 +400,7 @@ func TestDoctor_EmitEnvelope_NotOK_OnFail(t *testing.T) { {Name: "credential_storage", Status: StatusOK}, }, } - emit(&Options{JSONOut: true}, r) + emit(&cmdutil.JSONOptions{}, r) got := out.String() if !strings.Contains(got, `"ok":false`) { t.Errorf("envelope.ok must be false when any check fails, got %q", got) @@ -418,7 +418,7 @@ func TestDoctor_HumanMarker_Warn(t *testing.T) { {Name: "server_version", Status: StatusWarn, Details: "older"}, }, } - emit(&Options{JSONOut: false}, r) + emit(nil, r) got := out.String() if !strings.Contains(got, "⚠") { t.Errorf("human output should contain ⚠ glyph for warn, got %q", got) @@ -443,7 +443,7 @@ func TestDoctor_WarnedField_OmittedAtZero(t *testing.T) { {Name: "credential_storage", Status: StatusOK}, }, } - emit(&Options{JSONOut: true}, r) + emit(&cmdutil.JSONOptions{}, r) got := out.String() if strings.Contains(got, `"warned"`) { t.Errorf("envelope should omit `warned` field when zero, got %q", got) diff --git a/cli/cmd/kb/create.go b/cli/cmd/kb/create.go index c7fe5366..4e8473ba 100644 --- a/cli/cmd/kb/create.go +++ b/cli/cmd/kb/create.go @@ -14,11 +14,23 @@ import ( sdk "github.com/Tencent/WeKnora/client" ) +// kbCreateFields enumerates the fields surfaced for `--json` discovery on +// `kb create`. The result is the full KnowledgeBase struct; these mirror its +// top-level json tags. Nested config objects are intentionally omitted — +// users wanting them can drop --json (no filter) or use --jq. +var kbCreateFields = []string{ + "id", "name", "type", "description", + "is_temporary", "is_pinned", + "embedding_model_id", "summary_model_id", + "knowledge_count", "chunk_count", + "is_processing", "processing_count", + "created_at", "updated_at", +} + type CreateOptions struct { Name string Description string EmbeddingModel string - JSONOut bool DryRun bool } @@ -36,26 +48,30 @@ func NewCmdCreate(f *cmdutil.Factory) *cobra.Command { Short: "Create a new knowledge base", Args: cobra.NoArgs, RunE: func(c *cobra.Command, _ []string) error { + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } opts.DryRun = cmdutil.IsDryRun(c) if opts.DryRun { - return runCreate(c.Context(), opts, nil) // service unused on dry-run + return runCreate(c.Context(), opts, jopts, nil) // service unused on dry-run } cli, err := f.Client() if err != nil { return err } - return runCreate(c.Context(), opts, cli) + return runCreate(c.Context(), opts, jopts, cli) }, } cmd.Flags().StringVar(&opts.Name, "name", "", "Knowledge base name (required)") cmd.Flags().StringVar(&opts.Description, "description", "", "Knowledge base description (optional)") cmd.Flags().StringVar(&opts.EmbeddingModel, "embedding-model", "", "Embedding model ID (optional; server picks default when unset)") - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, kbCreateFields) agent.SetAgentHelp(cmd, "Creates a knowledge base under the active context. --name is required; --description and --embedding-model are optional. Returns data: full KnowledgeBase object including the new id.") return cmd } -func runCreate(ctx context.Context, opts *CreateOptions, svc CreateService) error { +func runCreate(ctx context.Context, opts *CreateOptions, jopts *cmdutil.JSONOptions, svc CreateService) error { // Validate locally before any HTTP — keeps `input.invalid_argument` // distinct from a server-side 400. if strings.TrimSpace(opts.Name) == "" { @@ -71,7 +87,7 @@ func runCreate(ctx context.Context, opts *CreateOptions, svc CreateService) erro } if opts.DryRun { - return cmdutil.EmitDryRun(opts.JSONOut, req, nil, + return cmdutil.EmitDryRun(jopts.Enabled(), req, nil, &format.Risk{Level: format.RiskWrite, Action: fmt.Sprintf("create knowledge base %q", opts.Name)}) } @@ -80,9 +96,9 @@ func runCreate(ctx context.Context, opts *CreateOptions, svc CreateService) erro return cmdutil.WrapHTTP(err, "create knowledge base") } - if opts.JSONOut { + if jopts.Enabled() { risk := &format.Risk{Level: format.RiskWrite, Action: fmt.Sprintf("created knowledge base %s", created.ID)} - return format.WriteEnvelope(iostreams.IO.Out, format.SuccessWithRisk(created, &format.Meta{KBID: created.ID}, risk)) + return format.WriteEnvelopeFiltered(iostreams.IO.Out, format.SuccessWithRisk(created, &format.Meta{KBID: created.ID}, risk), jopts.Fields, jopts.JQ) } fmt.Fprintf(iostreams.IO.Out, "✓ Created knowledge base %q (id: %s)\n", created.Name, created.ID) return nil diff --git a/cli/cmd/kb/create_test.go b/cli/cmd/kb/create_test.go index 58a5b301..c3a907cb 100644 --- a/cli/cmd/kb/create_test.go +++ b/cli/cmd/kb/create_test.go @@ -39,7 +39,7 @@ func TestCreate_Success_Human(t *testing.T) { Description: "team docs", EmbeddingModel: "model_x", } - require.NoError(t, runCreate(context.Background(), opts, svc)) + require.NoError(t, runCreate(context.Background(), opts, nil, svc)) // Body sent to SDK matches flags. require.NotNil(t, svc.got) @@ -59,7 +59,7 @@ func TestCreate_Success_OmitsEmbeddingModelWhenEmpty(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakeCreateSvc{resp: &sdk.KnowledgeBase{ID: "kb_x", Name: "n"}} opts := &CreateOptions{Name: "n"} - require.NoError(t, runCreate(context.Background(), opts, svc)) + require.NoError(t, runCreate(context.Background(), opts, nil, svc)) require.NotNil(t, svc.got) assert.Equal(t, "", svc.got.EmbeddingModelID, "embedding-model unset ⇒ empty in request") @@ -68,7 +68,7 @@ func TestCreate_Success_OmitsEmbeddingModelWhenEmpty(t *testing.T) { func TestCreate_NameRequired(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakeCreateSvc{} - err := runCreate(context.Background(), &CreateOptions{}, svc) + err := runCreate(context.Background(), &CreateOptions{}, nil, svc) require.Error(t, err) var typed *cmdutil.Error @@ -80,7 +80,7 @@ func TestCreate_NameRequired(t *testing.T) { func TestCreate_NameWhitespaceOnly(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakeCreateSvc{} - err := runCreate(context.Background(), &CreateOptions{Name: " "}, svc) + err := runCreate(context.Background(), &CreateOptions{Name: " "}, nil, svc) require.Error(t, err) var typed *cmdutil.Error @@ -91,7 +91,7 @@ func TestCreate_NameWhitespaceOnly(t *testing.T) { func TestCreate_HTTPError_500(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakeCreateSvc{err: errors.New("HTTP error 500: internal")} - err := runCreate(context.Background(), &CreateOptions{Name: "x"}, svc) + err := runCreate(context.Background(), &CreateOptions{Name: "x"}, nil, svc) require.Error(t, err) var typed *cmdutil.Error @@ -102,7 +102,7 @@ func TestCreate_HTTPError_500(t *testing.T) { func TestCreate_HTTPError_409Conflict(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakeCreateSvc{err: errors.New("HTTP error 409: name exists")} - err := runCreate(context.Background(), &CreateOptions{Name: "dup"}, svc) + err := runCreate(context.Background(), &CreateOptions{Name: "dup"}, nil, svc) require.Error(t, err) var typed *cmdutil.Error @@ -113,8 +113,8 @@ func TestCreate_HTTPError_409Conflict(t *testing.T) { func TestCreate_JSONOutput(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakeCreateSvc{resp: &sdk.KnowledgeBase{ID: "kb_99", Name: "Eng"}} - opts := &CreateOptions{Name: "Eng", JSONOut: true} - require.NoError(t, runCreate(context.Background(), opts, svc)) + opts := &CreateOptions{Name: "Eng"} + require.NoError(t, runCreate(context.Background(), opts, &cmdutil.JSONOptions{}, svc)) got := out.String() assert.True(t, strings.HasPrefix(got, `{"ok":true`), "envelope should start with ok:true; got %q", got) diff --git a/cli/cmd/kb/delete.go b/cli/cmd/kb/delete.go index 7e84f210..f63c9a9e 100644 --- a/cli/cmd/kb/delete.go +++ b/cli/cmd/kb/delete.go @@ -13,10 +13,13 @@ import ( "github.com/Tencent/WeKnora/cli/internal/prompt" ) +// kbDeleteFields enumerates the fields surfaced for `--json` discovery on +// `kb delete`. The result payload is a small {id, deleted} object. +var kbDeleteFields = []string{"id", "deleted"} + type DeleteOptions struct { - Yes bool // sourced from the global -y/--yes persistent flag (see cli/cmd/root.go addGlobalFlags) - JSONOut bool - DryRun bool + Yes bool // sourced from the global -y/--yes persistent flag (see cli/cmd/root.go addGlobalFlags) + DryRun bool } // DeleteService is the narrow SDK surface this command depends on. @@ -53,31 +56,35 @@ guard against unintended deletes.`, weknora kb delete kb_abc -y --json # envelope output`, Args: cobra.ExactArgs(1), RunE: func(c *cobra.Command, args []string) error { + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } opts.Yes, _ = c.Flags().GetBool("yes") opts.DryRun = cmdutil.IsDryRun(c) if opts.DryRun { - return runDelete(c.Context(), opts, nil, f.Prompter(), args[0]) + return runDelete(c.Context(), opts, jopts, nil, f.Prompter(), args[0]) } cli, err := f.Client() if err != nil { return err } - return runDelete(c.Context(), opts, cli, f.Prompter(), args[0]) + return runDelete(c.Context(), opts, jopts, cli, f.Prompter(), args[0]) }, } - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, kbDeleteFields) agent.SetAgentHelp(cmd, "Destructively deletes a knowledge base by id. ALWAYS pass -y/--yes in agent mode (no TTY ⇒ confirm prompt fails). Returns data: {id, deleted:true}.") return cmd } -func runDelete(ctx context.Context, opts *DeleteOptions, svc DeleteService, p prompt.Prompter, id string) error { +func runDelete(ctx context.Context, opts *DeleteOptions, jopts *cmdutil.JSONOptions, svc DeleteService, p prompt.Prompter, id string) error { if opts.DryRun { - return cmdutil.EmitDryRun(opts.JSONOut, + return cmdutil.EmitDryRun(jopts.Enabled(), deleteResult{ID: id, Deleted: false}, &format.Meta{KBID: id}, &format.Risk{Level: format.RiskHighRiskWrite, Action: fmt.Sprintf("delete knowledge base %s", id)}) } - if err := cmdutil.ConfirmDestructive(p, opts.Yes, opts.JSONOut, "knowledge base", id); err != nil { + if err := cmdutil.ConfirmDestructive(p, opts.Yes, jopts.Enabled(), "knowledge base", id); err != nil { return err } @@ -85,9 +92,9 @@ func runDelete(ctx context.Context, opts *DeleteOptions, svc DeleteService, p pr return cmdutil.WrapHTTP(err, "delete knowledge base %s", id) } - if opts.JSONOut { + if jopts.Enabled() { risk := &format.Risk{Level: format.RiskHighRiskWrite, Action: fmt.Sprintf("deleted knowledge base %s", id)} - return format.WriteEnvelope(iostreams.IO.Out, format.SuccessWithRisk(deleteResult{ID: id, Deleted: true}, &format.Meta{KBID: id}, risk)) + return format.WriteEnvelopeFiltered(iostreams.IO.Out, format.SuccessWithRisk(deleteResult{ID: id, Deleted: true}, &format.Meta{KBID: id}, risk), jopts.Fields, jopts.JQ) } fmt.Fprintf(iostreams.IO.Out, "✓ Deleted knowledge base %s\n", id) return nil diff --git a/cli/cmd/kb/delete_test.go b/cli/cmd/kb/delete_test.go index 6cf74ebc..091faa65 100644 --- a/cli/cmd/kb/delete_test.go +++ b/cli/cmd/kb/delete_test.go @@ -46,7 +46,7 @@ func TestDelete_Success_WithForce(t *testing.T) { svc := &fakeDeleteSvc{} p := &confirmPrompter{} opts := &DeleteOptions{Yes: true} - require.NoError(t, runDelete(context.Background(), opts, svc, p, "kb_force")) + require.NoError(t, runDelete(context.Background(), opts, nil, svc, p, "kb_force")) assert.True(t, svc.called) assert.Equal(t, "kb_force", svc.gotID) @@ -59,7 +59,7 @@ func TestDelete_NotFound(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakeDeleteSvc{err: errors.New("HTTP error 404: not found")} p := &confirmPrompter{} - err := runDelete(context.Background(), &DeleteOptions{Yes: true}, svc, p, "kb_missing") + err := runDelete(context.Background(), &DeleteOptions{Yes: true}, nil, svc, p, "kb_missing") require.Error(t, err) var typed *cmdutil.Error @@ -74,7 +74,7 @@ func TestDelete_NonTTY_NoYes_RequiresConfirmation(t *testing.T) { iostreams.SetForTest(t) svc := &fakeDeleteSvc{} p := &confirmPrompter{} - err := runDelete(context.Background(), &DeleteOptions{}, svc, p, "kb_nontty") + err := runDelete(context.Background(), &DeleteOptions{}, nil, svc, p, "kb_nontty") require.Error(t, err) var typed *cmdutil.Error @@ -89,8 +89,8 @@ func TestDelete_JSONOutput(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakeDeleteSvc{} p := &confirmPrompter{} - opts := &DeleteOptions{Yes: true, JSONOut: true} - require.NoError(t, runDelete(context.Background(), opts, svc, p, "kb_json")) + opts := &DeleteOptions{Yes: true} + require.NoError(t, runDelete(context.Background(), opts, &cmdutil.JSONOptions{}, svc, p, "kb_json")) got := out.String() assert.True(t, strings.HasPrefix(got, `{"ok":true`), "envelope should start with ok:true; got %q", got) @@ -106,7 +106,7 @@ func TestDelete_ConfirmYes(t *testing.T) { _, _ = iostreams.SetForTestWithTTY(t) svc := &fakeDeleteSvc{} p := &confirmPrompter{answer: true} - require.NoError(t, runDelete(context.Background(), &DeleteOptions{}, svc, p, "kb_yes")) + require.NoError(t, runDelete(context.Background(), &DeleteOptions{}, nil, svc, p, "kb_yes")) assert.True(t, p.asked, "confirm prompt should fire on TTY without --force") assert.True(t, svc.called, "answer=yes ⇒ delete proceeds") @@ -117,7 +117,7 @@ func TestDelete_ConfirmNo(t *testing.T) { _, errBuf := iostreams.SetForTestWithTTY(t) svc := &fakeDeleteSvc{} p := &confirmPrompter{answer: false} - err := runDelete(context.Background(), &DeleteOptions{}, svc, p, "kb_no") + err := runDelete(context.Background(), &DeleteOptions{}, nil, svc, p, "kb_no") require.Error(t, err) var typed *cmdutil.Error @@ -132,7 +132,7 @@ func TestDelete_ConfirmPrompterError(t *testing.T) { _, _ = iostreams.SetForTestWithTTY(t) svc := &fakeDeleteSvc{} p := &confirmPrompter{err: prompt.ErrAgentNoPrompt} - err := runDelete(context.Background(), &DeleteOptions{}, svc, p, "kb_err") + err := runDelete(context.Background(), &DeleteOptions{}, nil, svc, p, "kb_err") require.Error(t, err) var typed *cmdutil.Error @@ -148,8 +148,8 @@ func TestDelete_JSONOut_NoYes_RequiresConfirmation(t *testing.T) { iostreams.SetForTestWithTTY(t) svc := &fakeDeleteSvc{} p := &confirmPrompter{} - opts := &DeleteOptions{JSONOut: true} - err := runDelete(context.Background(), opts, svc, p, "kb_jtty") + opts := &DeleteOptions{} + err := runDelete(context.Background(), opts, &cmdutil.JSONOptions{}, svc, p, "kb_jtty") require.Error(t, err) var typed *cmdutil.Error @@ -166,8 +166,8 @@ func TestDelete_JSONOut_WithYes_Proceeds(t *testing.T) { out, _ := iostreams.SetForTestWithTTY(t) svc := &fakeDeleteSvc{} p := &confirmPrompter{} - opts := &DeleteOptions{Yes: true, JSONOut: true} - require.NoError(t, runDelete(context.Background(), opts, svc, p, "kb_jtty")) + opts := &DeleteOptions{Yes: true} + require.NoError(t, runDelete(context.Background(), opts, &cmdutil.JSONOptions{}, svc, p, "kb_jtty")) assert.False(t, p.asked, "-y must skip the prompt") assert.True(t, svc.called) diff --git a/cli/cmd/kb/edit.go b/cli/cmd/kb/edit.go index 28bf5a5f..5d6e3bc9 100644 --- a/cli/cmd/kb/edit.go +++ b/cli/cmd/kb/edit.go @@ -13,6 +13,18 @@ import ( sdk "github.com/Tencent/WeKnora/client" ) +// kbEditFields enumerates the fields surfaced for `--json` discovery on +// `kb edit`. The result is the updated KnowledgeBase; mirrors the kb +// top-level json tags. +var kbEditFields = []string{ + "id", "name", "type", "description", + "is_temporary", "is_pinned", + "embedding_model_id", "summary_model_id", + "knowledge_count", "chunk_count", + "is_processing", "processing_count", + "created_at", "updated_at", +} + type EditOptions struct { // Name/Description are *string so we can distinguish "unset" from "set to // empty". An unset field is omitted from the SDK request — only fields the @@ -21,7 +33,6 @@ type EditOptions struct { // clear the description. Name *string Description *string - JSONOut bool DryRun bool } @@ -45,6 +56,10 @@ func NewCmdEdit(f *cmdutil.Factory) *cobra.Command { Short: "Edit a knowledge base's name or description", Args: cobra.ExactArgs(1), RunE: func(c *cobra.Command, args []string) error { + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } if c.Flag("name").Changed { opts.Name = &name } @@ -53,23 +68,23 @@ func NewCmdEdit(f *cmdutil.Factory) *cobra.Command { } opts.DryRun = cmdutil.IsDryRun(c) if opts.DryRun { - return runEdit(c.Context(), opts, nil, args[0]) + return runEdit(c.Context(), opts, jopts, nil, args[0]) } cli, err := f.Client() if err != nil { return err } - return runEdit(c.Context(), opts, cli, args[0]) + return runEdit(c.Context(), opts, jopts, cli, args[0]) }, } cmd.Flags().StringVar(&name, "name", "", "New name (omit to leave unchanged)") cmd.Flags().StringVar(&desc, "description", "", "New description (omit to leave unchanged)") - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, kbEditFields) agent.SetAgentHelp(cmd, "Edits a knowledge base. At least one of --name/--description is required. Fields not passed are preserved server-side. Returns the updated KnowledgeBase.") return cmd } -func runEdit(ctx context.Context, opts *EditOptions, svc EditService, id string) error { +func runEdit(ctx context.Context, opts *EditOptions, jopts *cmdutil.JSONOptions, svc EditService, id string) error { if opts.Name == nil && opts.Description == nil { return &cmdutil.Error{ Code: cmdutil.CodeInputMissingFlag, @@ -89,7 +104,7 @@ func runEdit(ctx context.Context, opts *EditOptions, svc EditService, id string) if opts.Description != nil { preview.Description = *opts.Description } - return cmdutil.EmitDryRun(opts.JSONOut, preview, &format.Meta{KBID: id}, risk) + return cmdutil.EmitDryRun(jopts.Enabled(), preview, &format.Meta{KBID: id}, risk) } // Fetch current state so we can fill in fields the user didn't touch. @@ -114,8 +129,8 @@ func runEdit(ctx context.Context, opts *EditOptions, svc EditService, id string) if err != nil { return cmdutil.WrapHTTP(err, "edit knowledge base %s", id) } - if opts.JSONOut { - return format.WriteEnvelope(iostreams.IO.Out, format.SuccessWithRisk(updated, &format.Meta{KBID: id}, risk)) + if jopts.Enabled() { + return format.WriteEnvelopeFiltered(iostreams.IO.Out, format.SuccessWithRisk(updated, &format.Meta{KBID: id}, risk), jopts.Fields, jopts.JQ) } fmt.Fprintf(iostreams.IO.Out, "✓ Updated knowledge base %s\n", id) return nil diff --git a/cli/cmd/kb/edit_test.go b/cli/cmd/kb/edit_test.go index a6d42f66..39e54bb4 100644 --- a/cli/cmd/kb/edit_test.go +++ b/cli/cmd/kb/edit_test.go @@ -44,7 +44,7 @@ func (f *fakeEditSvc) UpdateKnowledgeBase(_ context.Context, id string, req *sdk func TestEdit_RequiresAtLeastOneFlag(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakeEditSvc{} - err := runEdit(context.Background(), &EditOptions{}, svc, "kb_abc") + err := runEdit(context.Background(), &EditOptions{}, nil, svc, "kb_abc") require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) @@ -65,7 +65,7 @@ func TestEdit_OnlyName_PreservesCurrentDescription(t *testing.T) { } opts := &EditOptions{} opts.Name = stringPtr("new") - require.NoError(t, runEdit(context.Background(), opts, svc, "kb_abc")) + require.NoError(t, runEdit(context.Background(), opts, nil, svc, "kb_abc")) assert.Equal(t, "kb_abc", svc.gotID) require.NotNil(t, svc.gotReq) @@ -84,7 +84,7 @@ func TestEdit_OnlyDescription_PreservesCurrentName(t *testing.T) { } opts := &EditOptions{} opts.Description = stringPtr("new desc") - require.NoError(t, runEdit(context.Background(), opts, svc, "kb_abc")) + require.NoError(t, runEdit(context.Background(), opts, nil, svc, "kb_abc")) require.NotNil(t, svc.gotReq) assert.Equal(t, "new desc", svc.gotReq.Description) @@ -97,16 +97,16 @@ func TestEdit_BothFlags(t *testing.T) { opts := &EditOptions{} opts.Name = stringPtr("renamed") opts.Description = stringPtr("new desc") - require.NoError(t, runEdit(context.Background(), opts, svc, "kb_abc")) + require.NoError(t, runEdit(context.Background(), opts, nil, svc, "kb_abc")) assert.Equal(t, "renamed", svc.gotReq.Name) assert.Equal(t, "new desc", svc.gotReq.Description) } func TestEdit_DryRun_JSON(t *testing.T) { out, _ := iostreams.SetForTest(t) - opts := &EditOptions{DryRun: true, JSONOut: true} + opts := &EditOptions{DryRun: true} opts.Name = stringPtr("preview") - require.NoError(t, runEdit(context.Background(), opts, nil, "kb_abc")) + require.NoError(t, runEdit(context.Background(), opts, &cmdutil.JSONOptions{}, nil, "kb_abc")) body := out.String() assert.True(t, strings.HasPrefix(body, `{"ok":true`)) @@ -121,7 +121,7 @@ func TestEdit_NotFound(t *testing.T) { svc := &fakeEditSvc{currentErr: errors.New("HTTP error 404: not found")} opts := &EditOptions{} opts.Name = stringPtr("x") - err := runEdit(context.Background(), opts, svc, "kb_missing") + err := runEdit(context.Background(), opts, nil, svc, "kb_missing") require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) diff --git a/cli/cmd/kb/empty.go b/cli/cmd/kb/empty.go index 3a88825d..327deea2 100644 --- a/cli/cmd/kb/empty.go +++ b/cli/cmd/kb/empty.go @@ -14,10 +14,13 @@ import ( sdk "github.com/Tencent/WeKnora/client" ) +// kbEmptyFields enumerates the fields surfaced for `--json` discovery on +// `kb empty`. The result payload is {id, deleted_count}. +var kbEmptyFields = []string{"id", "deleted_count"} + type EmptyOptions struct { - Yes bool - JSONOut bool - DryRun bool + Yes bool + DryRun bool } type EmptyService interface { @@ -49,31 +52,35 @@ piped contexts. Without -y the CLI exits 10 in non-interactive mode.`, weknora kb empty kb_abc -y --json # agent-friendly`, Args: cobra.ExactArgs(1), RunE: func(c *cobra.Command, args []string) error { + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } opts.Yes, _ = c.Flags().GetBool("yes") opts.DryRun = cmdutil.IsDryRun(c) if opts.DryRun { - return runEmpty(c.Context(), opts, nil, f.Prompter(), args[0]) + return runEmpty(c.Context(), opts, jopts, nil, f.Prompter(), args[0]) } cli, err := f.Client() if err != nil { return err } - return runEmpty(c.Context(), opts, cli, f.Prompter(), args[0]) + return runEmpty(c.Context(), opts, jopts, cli, f.Prompter(), args[0]) }, } - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, kbEmptyFields) agent.SetAgentHelp(cmd, "Destructively empties a knowledge base (deletes all documents, preserves the KB record + config). ALWAYS pass -y/--yes in agent mode (non-TTY ⇒ confirm fails). Returns data: {id, deleted_count}. Async — items may still be processing server-side after the call returns.") return cmd } -func runEmpty(ctx context.Context, opts *EmptyOptions, svc EmptyService, p prompt.Prompter, id string) error { +func runEmpty(ctx context.Context, opts *EmptyOptions, jopts *cmdutil.JSONOptions, svc EmptyService, p prompt.Prompter, id string) error { risk := &format.Risk{Level: format.RiskHighRiskWrite, Action: fmt.Sprintf("empty knowledge base %s", id)} if opts.DryRun { - return cmdutil.EmitDryRun(opts.JSONOut, emptyResult{ID: id}, &format.Meta{KBID: id}, risk) + return cmdutil.EmitDryRun(jopts.Enabled(), emptyResult{ID: id}, &format.Meta{KBID: id}, risk) } - if err := cmdutil.ConfirmDestructive(p, opts.Yes, opts.JSONOut, "all contents of knowledge base", id); err != nil { + if err := cmdutil.ConfirmDestructive(p, opts.Yes, jopts.Enabled(), "all contents of knowledge base", id); err != nil { return err } @@ -86,10 +93,10 @@ func runEmpty(ctx context.Context, opts *EmptyOptions, svc EmptyService, p promp deleted = resp.DeletedCount } - if opts.JSONOut { - return format.WriteEnvelope(iostreams.IO.Out, format.SuccessWithRisk( + if jopts.Enabled() { + return format.WriteEnvelopeFiltered(iostreams.IO.Out, format.SuccessWithRisk( emptyResult{ID: id, DeletedCount: deleted}, &format.Meta{KBID: id}, risk, - )) + ), jopts.Fields, jopts.JQ) } fmt.Fprintf(iostreams.IO.Out, "✓ Emptied knowledge base %s (%d document(s) cleared)\n", id, deleted) return nil diff --git a/cli/cmd/kb/empty_test.go b/cli/cmd/kb/empty_test.go index 543cb82a..41fc83c2 100644 --- a/cli/cmd/kb/empty_test.go +++ b/cli/cmd/kb/empty_test.go @@ -38,7 +38,7 @@ func (f *fakeEmptySvc) ClearKnowledgeBaseContents(_ context.Context, id string) func TestEmpty_WithYes(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakeEmptySvc{resp: &sdk.ClearKnowledgeBaseContentsResponse{DeletedCount: 42}} - require.NoError(t, runEmpty(context.Background(), &EmptyOptions{Yes: true}, svc, &testutil.ConfirmPrompter{}, "kb_abc")) + require.NoError(t, runEmpty(context.Background(), &EmptyOptions{Yes: true}, nil, svc, &testutil.ConfirmPrompter{}, "kb_abc")) assert.True(t, svc.called) assert.Equal(t, "kb_abc", svc.gotID) body := out.String() @@ -49,7 +49,7 @@ func TestEmpty_WithYes(t *testing.T) { func TestEmpty_NonTTY_NoYes_RequiresConfirmation(t *testing.T) { iostreams.SetForTest(t) svc := &fakeEmptySvc{} - err := runEmpty(context.Background(), &EmptyOptions{}, svc, &testutil.ConfirmPrompter{}, "kb_abc") + err := runEmpty(context.Background(), &EmptyOptions{}, nil, svc, &testutil.ConfirmPrompter{}, "kb_abc") require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) @@ -62,7 +62,7 @@ func TestEmpty_TTY_ConfirmNo(t *testing.T) { _, errBuf := iostreams.SetForTestWithTTY(t) svc := &fakeEmptySvc{} p := &testutil.ConfirmPrompter{Answer: false} - err := runEmpty(context.Background(), &EmptyOptions{}, svc, p, "kb_abc") + err := runEmpty(context.Background(), &EmptyOptions{}, nil, svc, p, "kb_abc") require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) @@ -74,7 +74,7 @@ func TestEmpty_TTY_ConfirmNo(t *testing.T) { func TestEmpty_NotFound(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakeEmptySvc{err: errors.New("HTTP error 404: not found")} - err := runEmpty(context.Background(), &EmptyOptions{Yes: true}, svc, &testutil.ConfirmPrompter{}, "kb_missing") + err := runEmpty(context.Background(), &EmptyOptions{Yes: true}, nil, svc, &testutil.ConfirmPrompter{}, "kb_missing") require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) @@ -84,7 +84,7 @@ func TestEmpty_NotFound(t *testing.T) { func TestEmpty_DryRun_JSON(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakeEmptySvc{} - require.NoError(t, runEmpty(context.Background(), &EmptyOptions{DryRun: true, JSONOut: true}, svc, &testutil.ConfirmPrompter{}, "kb_dry")) + require.NoError(t, runEmpty(context.Background(), &EmptyOptions{DryRun: true}, &cmdutil.JSONOptions{}, svc, &testutil.ConfirmPrompter{}, "kb_dry")) body := out.String() assert.True(t, strings.HasPrefix(body, `{"ok":true`)) assert.Contains(t, body, `"dry_run":true`) diff --git a/cli/cmd/kb/list.go b/cli/cmd/kb/list.go index 2a2762e6..81842874 100644 --- a/cli/cmd/kb/list.go +++ b/cli/cmd/kb/list.go @@ -17,8 +17,17 @@ import ( sdk "github.com/Tencent/WeKnora/client" ) -type ListOptions struct { - JSONOut bool +// kbListFields enumerates the fields surfaced for `--json` discovery on +// `kb list`. Nested config structs (chunking / image / FAQ / VLM / storage +// / extract) are intentionally omitted — users wanting those can use `--jq` +// against the full envelope. +var kbListFields = []string{ + "id", "name", "type", "description", + "is_temporary", "is_pinned", + "embedding_model_id", "summary_model_id", + "knowledge_count", "chunk_count", + "is_processing", "processing_count", + "created_at", "updated_at", } // ListService is the narrow SDK surface this command depends on. @@ -33,25 +42,28 @@ type listResult struct { // NewCmdList builds `weknora kb list`. func NewCmdList(f *cmdutil.Factory) *cobra.Command { - opts := &ListOptions{} cmd := &cobra.Command{ Use: "list", Short: "List knowledge bases visible to the active context", Args: cobra.NoArgs, RunE: func(c *cobra.Command, _ []string) error { + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } cli, err := f.Client() if err != nil { return err } - return runList(c.Context(), opts, cli) + return runList(c.Context(), jopts, cli) }, } - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") - agent.SetAgentHelp(cmd, "Lists all knowledge bases. Returns data.items: [{id, name, ...}]; empty array when none.") + cmdutil.AddJSONFlags(cmd, kbListFields) + agent.SetAgentHelp(cmd, "Lists all knowledge bases. Returns data.items: [{id, name, ...}]; empty array when none. Use `--json` (bare) for the field list, `--json id,name` to project, or `--jq` for arbitrary reshape.") return cmd } -func runList(ctx context.Context, opts *ListOptions, svc ListService) error { +func runList(ctx context.Context, jopts *cmdutil.JSONOptions, svc ListService) error { items, err := svc.ListKnowledgeBases(ctx) if err != nil { return cmdutil.WrapHTTP(err, "list knowledge bases") @@ -66,8 +78,12 @@ func runList(ctx context.Context, opts *ListOptions, svc ListService) error { return items[i].UpdatedAt.After(items[j].UpdatedAt) }) - if opts.JSONOut { - return format.WriteEnvelope(iostreams.IO.Out, format.Success(listResult{Items: items}, nil)) + if jopts.Enabled() { + return format.WriteEnvelopeFiltered( + iostreams.IO.Out, + format.Success(listResult{Items: items}, nil), + jopts.Fields, jopts.JQ, + ) } if len(items) == 0 { diff --git a/cli/cmd/kb/list_test.go b/cli/cmd/kb/list_test.go index b61715e4..ca7d5a13 100644 --- a/cli/cmd/kb/list_test.go +++ b/cli/cmd/kb/list_test.go @@ -2,10 +2,12 @@ package kb import ( "context" + "encoding/json" "strings" "testing" "time" + "github.com/Tencent/WeKnora/cli/internal/cmdutil" "github.com/Tencent/WeKnora/cli/internal/iostreams" sdk "github.com/Tencent/WeKnora/client" ) @@ -21,7 +23,7 @@ func (f *fakeListSvc) ListKnowledgeBases(ctx context.Context) ([]sdk.KnowledgeBa func TestList_Empty_Human(t *testing.T) { out, _ := iostreams.SetForTest(t) - if err := runList(context.Background(), &ListOptions{}, &fakeListSvc{items: []sdk.KnowledgeBase{}}); err != nil { + if err := runList(context.Background(), nil, &fakeListSvc{items: []sdk.KnowledgeBase{}}); err != nil { t.Fatalf("runList: %v", err) } if !strings.Contains(out.String(), "(no knowledge bases)") { @@ -31,7 +33,8 @@ func TestList_Empty_Human(t *testing.T) { func TestList_Empty_JSON(t *testing.T) { out, _ := iostreams.SetForTest(t) - if err := runList(context.Background(), &ListOptions{JSONOut: true}, &fakeListSvc{items: []sdk.KnowledgeBase{}}); err != nil { + jopts := &cmdutil.JSONOptions{} + if err := runList(context.Background(), jopts, &fakeListSvc{items: []sdk.KnowledgeBase{}}); err != nil { t.Fatalf("runList: %v", err) } got := out.String() @@ -50,7 +53,7 @@ func TestList_NonEmpty_Human_RenderColumns(t *testing.T) { {ID: "kb1", Name: "Marketing", KnowledgeCount: 5, UpdatedAt: now.Add(-3 * time.Hour)}, {ID: "kb2", Name: "Engineering", KnowledgeCount: 1, UpdatedAt: now.Add(-2 * 24 * time.Hour)}, } - if err := runList(context.Background(), &ListOptions{}, &fakeListSvc{items: items}); err != nil { + if err := runList(context.Background(), nil, &fakeListSvc{items: items}); err != nil { t.Fatalf("runList: %v", err) } got := out.String() @@ -60,3 +63,50 @@ func TestList_NonEmpty_Human_RenderColumns(t *testing.T) { } } } + +func TestList_JSON_FieldFilter(t *testing.T) { + out, _ := iostreams.SetForTest(t) + now := time.Now() + items := []sdk.KnowledgeBase{ + {ID: "kb1", Name: "Marketing", Description: "MKT desc", UpdatedAt: now}, + } + jopts := &cmdutil.JSONOptions{Fields: []string{"id", "name"}} + if err := runList(context.Background(), jopts, &fakeListSvc{items: items}); err != nil { + t.Fatalf("runList: %v", err) + } + var env struct { + OK bool `json:"ok"` + Data struct { + Items []map[string]any `json:"items"` + } `json:"data"` + } + if err := json.Unmarshal(out.Bytes(), &env); err != nil { + t.Fatalf("parse: %v\n%s", err, out.String()) + } + if len(env.Data.Items) != 1 { + t.Fatalf("expected 1 item, got %d", len(env.Data.Items)) + } + item := env.Data.Items[0] + if item["id"] != "kb1" || item["name"] != "Marketing" { + t.Errorf("kept fields wrong: %+v", item) + } + if _, has := item["description"]; has { + t.Errorf("description should be dropped, got: %+v", item) + } +} + +func TestList_JSON_JQ(t *testing.T) { + out, _ := iostreams.SetForTest(t) + now := time.Now() + items := []sdk.KnowledgeBase{ + {ID: "kb1", Name: "Marketing", UpdatedAt: now}, + {ID: "kb2", Name: "Engineering", UpdatedAt: now.Add(-time.Hour)}, + } + jopts := &cmdutil.JSONOptions{JQ: ".data.items | length"} + if err := runList(context.Background(), jopts, &fakeListSvc{items: items}); err != nil { + t.Fatalf("runList: %v", err) + } + if got := strings.TrimSpace(out.String()); got != "2" { + t.Errorf("expected '2', got %q", got) + } +} diff --git a/cli/cmd/kb/pin.go b/cli/cmd/kb/pin.go index 1d9eb17d..6d1dd4b8 100644 --- a/cli/cmd/kb/pin.go +++ b/cli/cmd/kb/pin.go @@ -13,9 +13,13 @@ import ( sdk "github.com/Tencent/WeKnora/client" ) +// kbPinFields enumerates the fields surfaced for `--json` discovery on +// `kb pin` / `kb unpin`. The toggle result is the KnowledgeBase; the user- +// relevant fields here are the id and the new pin state. +var kbPinFields = []string{"id", "is_pinned"} + type PinOptions struct { - JSONOut bool - DryRun bool + DryRun bool } // PinService is the narrow SDK surface this command depends on. The CLI @@ -43,23 +47,27 @@ func newPinCmd(f *cmdutil.Factory, use string, want bool, short string) *cobra.C Short: short, Args: cobra.ExactArgs(1), RunE: func(c *cobra.Command, args []string) error { + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } opts.DryRun = cmdutil.IsDryRun(c) if opts.DryRun { - return runPin(c.Context(), opts, nil, args[0], want) + return runPin(c.Context(), opts, jopts, nil, args[0], want) } cli, err := f.Client() if err != nil { return err } - return runPin(c.Context(), opts, cli, args[0], want) + return runPin(c.Context(), opts, jopts, cli, args[0], want) }, } - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, kbPinFields) agent.SetAgentHelp(cmd, fmt.Sprintf("Idempotent %s: reads current pin state, toggles only if different. No-op when already in the requested state.", use)) return cmd } -func runPin(ctx context.Context, opts *PinOptions, svc PinService, id string, want bool) error { +func runPin(ctx context.Context, opts *PinOptions, jopts *cmdutil.JSONOptions, svc PinService, id string, want bool) error { verb := "pin" if !want { verb = "unpin" @@ -70,7 +78,7 @@ func runPin(ctx context.Context, opts *PinOptions, svc PinService, id string, wa // Dry-run can't introspect state without a network call by design (see // kb/delete.go for the same convention). Report what *would* run if // state diverged; agents can disambiguate via a subsequent `kb view`. - return cmdutil.EmitDryRun(opts.JSONOut, struct { + return cmdutil.EmitDryRun(jopts.Enabled(), struct { ID string `json:"id"` Want bool `json:"want_pinned"` }{id, want}, &format.Meta{KBID: id}, risk) @@ -88,9 +96,9 @@ func runPin(ctx context.Context, opts *PinOptions, svc PinService, id string, wa // No-op path: tell agents what happened. The risk-write classification // was the *requested* operation, not what occurred — surface it via a // _meta.warning so audit logs don't count a write that wasn't made. - if opts.JSONOut { + if jopts.Enabled() { meta := &format.Meta{KBID: id, Warnings: []string{fmt.Sprintf("already %s — no server call made", state)}} - return format.WriteEnvelope(iostreams.IO.Out, format.Success(current, meta)) + return format.WriteEnvelopeFiltered(iostreams.IO.Out, format.Success(current, meta), jopts.Fields, jopts.JQ) } fmt.Fprintf(iostreams.IO.Out, "✓ %s is already %s\n", id, state) return nil @@ -100,8 +108,8 @@ func runPin(ctx context.Context, opts *PinOptions, svc PinService, id string, wa if err != nil { return cmdutil.WrapHTTP(err, "%s knowledge base %s", verb, id) } - if opts.JSONOut { - return format.WriteEnvelope(iostreams.IO.Out, format.SuccessWithRisk(updated, &format.Meta{KBID: id}, risk)) + if jopts.Enabled() { + return format.WriteEnvelopeFiltered(iostreams.IO.Out, format.SuccessWithRisk(updated, &format.Meta{KBID: id}, risk), jopts.Fields, jopts.JQ) } state := "pinned" if !updated.IsPinned { diff --git a/cli/cmd/kb/pin_test.go b/cli/cmd/kb/pin_test.go index b14429cd..50734652 100644 --- a/cli/cmd/kb/pin_test.go +++ b/cli/cmd/kb/pin_test.go @@ -44,7 +44,7 @@ func (f *fakePinSvc) TogglePinKnowledgeBase(_ context.Context, id string) (*sdk. func TestPin_UnpinnedToPinned_CallsToggle(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakePinSvc{current: sdk.KnowledgeBase{IsPinned: false}} - require.NoError(t, runPin(context.Background(), &PinOptions{}, svc, "kb_abc", true)) + require.NoError(t, runPin(context.Background(), &PinOptions{}, nil, svc, "kb_abc", true)) assert.True(t, svc.toggleCalled, "must call toggle when current state differs") assert.Contains(t, out.String(), "kb_abc") } @@ -52,7 +52,7 @@ func TestPin_UnpinnedToPinned_CallsToggle(t *testing.T) { func TestPin_AlreadyPinned_NoOp(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakePinSvc{current: sdk.KnowledgeBase{IsPinned: true}} - require.NoError(t, runPin(context.Background(), &PinOptions{}, svc, "kb_abc", true)) + require.NoError(t, runPin(context.Background(), &PinOptions{}, nil, svc, "kb_abc", true)) assert.False(t, svc.toggleCalled, "already pinned ⇒ must not call toggle") assert.Contains(t, out.String(), "already pinned") } @@ -60,14 +60,14 @@ func TestPin_AlreadyPinned_NoOp(t *testing.T) { func TestUnpin_PinnedToUnpinned_CallsToggle(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakePinSvc{current: sdk.KnowledgeBase{IsPinned: true}} - require.NoError(t, runPin(context.Background(), &PinOptions{}, svc, "kb_abc", false)) + require.NoError(t, runPin(context.Background(), &PinOptions{}, nil, svc, "kb_abc", false)) assert.True(t, svc.toggleCalled) } func TestUnpin_AlreadyUnpinned_NoOp(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakePinSvc{current: sdk.KnowledgeBase{IsPinned: false}} - require.NoError(t, runPin(context.Background(), &PinOptions{}, svc, "kb_abc", false)) + require.NoError(t, runPin(context.Background(), &PinOptions{}, nil, svc, "kb_abc", false)) assert.False(t, svc.toggleCalled, "already unpinned ⇒ must not call toggle") assert.Contains(t, out.String(), "already unpinned") } @@ -75,7 +75,7 @@ func TestUnpin_AlreadyUnpinned_NoOp(t *testing.T) { func TestPin_NotFound(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakePinSvc{getErr: errors.New("HTTP error 404: not found")} - err := runPin(context.Background(), &PinOptions{}, svc, "kb_missing", true) + err := runPin(context.Background(), &PinOptions{}, nil, svc, "kb_missing", true) require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) @@ -89,7 +89,7 @@ func TestPin_ToggleError(t *testing.T) { current: sdk.KnowledgeBase{IsPinned: false}, toggleErr: errors.New("HTTP error 500: internal"), } - err := runPin(context.Background(), &PinOptions{}, svc, "kb_abc", true) + err := runPin(context.Background(), &PinOptions{}, nil, svc, "kb_abc", true) require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) @@ -99,7 +99,7 @@ func TestPin_ToggleError(t *testing.T) { func TestPin_DryRun_StateDiffers(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakePinSvc{current: sdk.KnowledgeBase{IsPinned: false}} - require.NoError(t, runPin(context.Background(), &PinOptions{DryRun: true, JSONOut: true}, svc, "kb_abc", true)) + require.NoError(t, runPin(context.Background(), &PinOptions{DryRun: true}, &cmdutil.JSONOptions{}, svc, "kb_abc", true)) assert.False(t, svc.toggleCalled, "dry-run must not call toggle") body := out.String() assert.Contains(t, body, `"dry_run":true`) @@ -109,7 +109,7 @@ func TestPin_DryRun_StateDiffers(t *testing.T) { func TestPin_JSON(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakePinSvc{current: sdk.KnowledgeBase{IsPinned: false}} - require.NoError(t, runPin(context.Background(), &PinOptions{JSONOut: true}, svc, "kb_abc", true)) + require.NoError(t, runPin(context.Background(), &PinOptions{}, &cmdutil.JSONOptions{}, svc, "kb_abc", true)) body := out.String() assert.Contains(t, body, `"is_pinned":true`) assert.Contains(t, body, `"id":"kb_abc"`) diff --git a/cli/cmd/kb/view.go b/cli/cmd/kb/view.go index e14e3f8d..41d1bdd9 100644 --- a/cli/cmd/kb/view.go +++ b/cli/cmd/kb/view.go @@ -14,10 +14,20 @@ import ( sdk "github.com/Tencent/WeKnora/client" ) -type ViewOptions struct { - JSONOut bool +// kbViewFields enumerates the fields surfaced for `--json` discovery on +// `kb view`. Lists the KnowledgeBase top-level json tags; nested config +// structs are omitted (use --jq for those). +var kbViewFields = []string{ + "id", "name", "type", "description", + "is_temporary", "is_pinned", + "embedding_model_id", "summary_model_id", + "knowledge_count", "chunk_count", + "is_processing", "processing_count", + "created_at", "updated_at", } +type ViewOptions struct{} + // ViewService is the narrow SDK surface this command depends on. type ViewService interface { GetKnowledgeBase(ctx context.Context, id string) (*sdk.KnowledgeBase, error) @@ -31,25 +41,29 @@ func NewCmdView(f *cmdutil.Factory) *cobra.Command { Short: "Show a knowledge base by ID", Args: cobra.ExactArgs(1), RunE: func(c *cobra.Command, args []string) error { + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } cli, err := f.Client() if err != nil { return err } - return runView(c.Context(), opts, cli, args[0]) + return runView(c.Context(), opts, jopts, cli, args[0]) }, } - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, kbViewFields) agent.SetAgentHelp(cmd, "Returns details of one knowledge base by ID (config + counts).") return cmd } -func runView(ctx context.Context, opts *ViewOptions, svc ViewService, id string) error { +func runView(ctx context.Context, opts *ViewOptions, jopts *cmdutil.JSONOptions, svc ViewService, id string) error { kb, err := svc.GetKnowledgeBase(ctx, id) if err != nil { return cmdutil.WrapHTTP(err, "get knowledge base %q", id) } - if opts.JSONOut { - return format.WriteEnvelope(iostreams.IO.Out, format.Success(kb, nil)) + if jopts.Enabled() { + return format.WriteEnvelopeFiltered(iostreams.IO.Out, format.Success(kb, nil), jopts.Fields, jopts.JQ) } // Human: KEY: VALUE w := iostreams.IO.Out diff --git a/cli/cmd/kb/view_test.go b/cli/cmd/kb/view_test.go index 81863af8..6b606e35 100644 --- a/cli/cmd/kb/view_test.go +++ b/cli/cmd/kb/view_test.go @@ -25,7 +25,7 @@ func TestGet_OK_Human(t *testing.T) { svc := &fakeGetSvc{kb: &sdk.KnowledgeBase{ ID: "kb1", Name: "Marketing", KnowledgeCount: 12, ChunkCount: 245, }} - if err := runView(context.Background(), &ViewOptions{}, svc, "kb1"); err != nil { + if err := runView(context.Background(), &ViewOptions{}, nil, svc, "kb1"); err != nil { t.Fatalf("runGet: %v", err) } got := out.String() @@ -39,7 +39,7 @@ func TestGet_OK_Human(t *testing.T) { func TestGet_OK_JSON(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakeGetSvc{kb: &sdk.KnowledgeBase{ID: "kb1", Name: "Marketing"}} - if err := runView(context.Background(), &ViewOptions{JSONOut: true}, svc, "kb1"); err != nil { + if err := runView(context.Background(), &ViewOptions{}, &cmdutil.JSONOptions{}, svc, "kb1"); err != nil { t.Fatalf("runGet: %v", err) } got := out.String() @@ -54,7 +54,7 @@ func TestGet_OK_JSON(t *testing.T) { func TestGet_NotFound(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakeGetSvc{err: errors.New("HTTP error 404: not found")} - err := runView(context.Background(), &ViewOptions{}, svc, "missing") + err := runView(context.Background(), &ViewOptions{}, nil, svc, "missing") if err == nil { t.Fatal("expected error") } diff --git a/cli/cmd/link/link.go b/cli/cmd/link/link.go index 2f0b8c79..53256385 100644 --- a/cli/cmd/link/link.go +++ b/cli/cmd/link/link.go @@ -21,9 +21,12 @@ import ( "github.com/Tencent/WeKnora/cli/internal/projectlink" ) +// linkFields enumerates the fields surfaced for `--json` discovery on +// `link`. Tracks the small linkResult struct. +var linkFields = []string{"context", "kb_id", "kb_name", "project_link_path"} + type Options struct { - KB string // --kb: KB UUID or name; empty triggers interactive prompt on TTY - JSONOut bool // --json + KB string // --kb: KB UUID or name; empty triggers interactive prompt on TTY } // linkResult is the typed payload emitted under data. @@ -56,16 +59,20 @@ user explicitly asked to bind this directory; don't run it as a side effect.`, weknora link # interactive (TTY)`, Args: cobra.NoArgs, RunE: func(c *cobra.Command, _ []string) error { - return runLink(c.Context(), opts, f) + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } + return runLink(c.Context(), opts, jopts, f) }, } cmd.Flags().StringVar(&opts.KB, "kb", "", "Knowledge base UUID or name; omit on a TTY for interactive prompt") - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, linkFields) agent.SetAgentHelp(cmd, "Writes .weknora/project.yaml binding cwd to a KB. Pass --kb (id or name) for non-interactive use. Always overwrites.") return cmd } -func runLink(ctx context.Context, opts *Options, f *cmdutil.Factory) error { +func runLink(ctx context.Context, opts *Options, jopts *cmdutil.JSONOptions, f *cmdutil.Factory) error { cwd, err := os.Getwd() if err != nil { return cmdutil.Wrapf(cmdutil.CodeLocalFileIO, err, "get cwd") @@ -97,11 +104,12 @@ func runLink(ctx context.Context, opts *Options, f *cmdutil.Factory) error { KBName: kbName, ProjectLinkPath: linkPath, } - if opts.JSONOut { - return format.WriteEnvelope(iostreams.IO.Out, format.Success(r, &format.Meta{ - Context: ctxName, - KBID: kbID, - })) + if jopts.Enabled() { + return format.WriteEnvelopeFiltered( + iostreams.IO.Out, + format.Success(r, &format.Meta{Context: ctxName, KBID: kbID}), + jopts.Fields, jopts.JQ, + ) } if kbName != "" { fmt.Fprintf(iostreams.IO.Out, "✓ Linked %s to %s (kb=%s, id=%s)\n", linkPath, ctxName, kbName, kbID) diff --git a/cli/cmd/link/link_test.go b/cli/cmd/link/link_test.go index 176c6a74..cccf058c 100644 --- a/cli/cmd/link/link_test.go +++ b/cli/cmd/link/link_test.go @@ -65,7 +65,7 @@ func TestLink_ByID(t *testing.T) { f := newFactory("default", nil) opts := &Options{KB: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa"} - require.NoError(t, runLink(context.Background(), opts, f)) + require.NoError(t, runLink(context.Background(), opts, nil, f)) linkPath := filepath.Join(dir, ".weknora", "project.yaml") p, err := projectlink.Load(linkPath) @@ -87,7 +87,7 @@ func TestLink_ByName(t *testing.T) { cli := sdk.NewClient(srv.URL) f := newFactory("default", cli) opts := &Options{KB: "foo"} - require.NoError(t, runLink(context.Background(), opts, f)) + require.NoError(t, runLink(context.Background(), opts, nil, f)) p, err := projectlink.Load(filepath.Join(dir, ".weknora", "project.yaml")) require.NoError(t, err) @@ -103,7 +103,7 @@ func TestLink_KBNotFound(t *testing.T) { cli := sdk.NewClient(srv.URL) f := newFactory("default", cli) opts := &Options{KB: "missing"} - err := runLink(context.Background(), opts, f) + err := runLink(context.Background(), opts, nil, f) require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) @@ -123,7 +123,7 @@ func TestLink_OverwritesExisting(t *testing.T) { f := newFactory("default", nil) opts := &Options{KB: "22222222-2222-4222-8222-222222222222"} - require.NoError(t, runLink(context.Background(), opts, f)) + require.NoError(t, runLink(context.Background(), opts, nil, f)) p, err := projectlink.Load(linkPath) require.NoError(t, err) @@ -140,7 +140,7 @@ func TestLink_NonInteractive_NoKB(t *testing.T) { f := newFactory("default", nil) opts := &Options{} // no KB - err := runLink(context.Background(), opts, f) + err := runLink(context.Background(), opts, nil, f) require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) diff --git a/cli/cmd/link/unlink.go b/cli/cmd/link/unlink.go index b21c189a..9ca23e81 100644 --- a/cli/cmd/link/unlink.go +++ b/cli/cmd/link/unlink.go @@ -13,9 +13,11 @@ import ( "github.com/Tencent/WeKnora/cli/internal/projectlink" ) -type UnlinkOptions struct { - JSONOut bool -} +// unlinkFields enumerates the fields surfaced for `--json` discovery on +// `unlink`. Tracks the small unlinkResult struct. +var unlinkFields = []string{"project_link_path"} + +type UnlinkOptions struct{} // unlinkResult is the typed payload emitted under data. type unlinkResult struct { @@ -40,15 +42,19 @@ is present anywhere in the parent chain.`, weknora unlink --json # envelope output (CI / agents)`, Args: cobra.NoArgs, RunE: func(c *cobra.Command, _ []string) error { - return runUnlink(opts) + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } + return runUnlink(opts, jopts) }, } - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, unlinkFields) agent.SetAgentHelp(cmd, "Removes .weknora/project.yaml (the cwd → KB binding). Walks up from cwd. Errors with input.invalid_argument when no link is present in the parent chain.") return cmd } -func runUnlink(opts *UnlinkOptions) error { +func runUnlink(opts *UnlinkOptions, jopts *cmdutil.JSONOptions) error { cwd, err := os.Getwd() if err != nil { return cmdutil.Wrapf(cmdutil.CodeLocalFileIO, err, "get cwd") @@ -67,9 +73,12 @@ func runUnlink(opts *UnlinkOptions) error { if err := projectlink.Remove(linkPath); err != nil { return cmdutil.Wrapf(cmdutil.CodeLocalFileIO, err, "remove %s", linkPath) } - if opts.JSONOut { - return format.WriteEnvelope(iostreams.IO.Out, format.Success( - unlinkResult{ProjectLinkPath: linkPath}, nil)) + if jopts.Enabled() { + return format.WriteEnvelopeFiltered( + iostreams.IO.Out, + format.Success(unlinkResult{ProjectLinkPath: linkPath}, nil), + jopts.Fields, jopts.JQ, + ) } fmt.Fprintf(iostreams.IO.Out, "✓ Unlinked %s\n", linkPath) return nil diff --git a/cli/cmd/link/unlink_test.go b/cli/cmd/link/unlink_test.go index fee1e926..bc5ed459 100644 --- a/cli/cmd/link/unlink_test.go +++ b/cli/cmd/link/unlink_test.go @@ -32,7 +32,7 @@ func TestUnlink_RemovesLinkInCwd(t *testing.T) { linkPath := mkLinkFile(t, tmp) t.Chdir(tmp) - if err := runUnlink(&UnlinkOptions{}); err != nil { + if err := runUnlink(&UnlinkOptions{}, nil); err != nil { t.Fatalf("runUnlink: %v", err) } if _, err := os.Stat(linkPath); !os.IsNotExist(err) { @@ -50,7 +50,7 @@ func TestUnlink_WalksUpFromSubdir(t *testing.T) { } t.Chdir(sub) - if err := runUnlink(&UnlinkOptions{}); err != nil { + if err := runUnlink(&UnlinkOptions{}, nil); err != nil { t.Fatalf("runUnlink: %v", err) } if _, err := os.Stat(linkPath); !os.IsNotExist(err) { @@ -63,7 +63,7 @@ func TestUnlink_NoLink_Errors(t *testing.T) { tmp := t.TempDir() t.Chdir(tmp) - err := runUnlink(&UnlinkOptions{}) + err := runUnlink(&UnlinkOptions{}, nil) if err == nil { t.Fatal("expected error when no link present") } @@ -85,7 +85,7 @@ func TestUnlink_JSON_Envelope(t *testing.T) { mkLinkFile(t, tmp) t.Chdir(tmp) - if err := runUnlink(&UnlinkOptions{JSONOut: true}); err != nil { + if err := runUnlink(&UnlinkOptions{}, &cmdutil.JSONOptions{}); err != nil { t.Fatalf("runUnlink: %v", err) } got := out.String() diff --git a/cli/cmd/root.go b/cli/cmd/root.go index abae26a7..4ff4d178 100644 --- a/cli/cmd/root.go +++ b/cli/cmd/root.go @@ -4,7 +4,6 @@ package cmd import ( "fmt" "os" - "strconv" "strings" "github.com/spf13/cobra" @@ -57,7 +56,9 @@ func Execute() int { // Exported so the acceptance/contract test helper can replicate Execute()'s // envelope-printing path without having to call os.Exit-bound Execute() itself. func WantsJSONOutput(cmd *cobra.Command) bool { - if v, err := cmd.Flags().GetBool("json"); err == nil && v { + // --json is StringSlice in v0.4 (gh-style field filter). Non-empty + // slice OR a "Changed=true" flag indicates the user requested JSON. + if f := cmd.Flags().Lookup("json"); f != nil && f.Changed { return true } return argsRequestJSON(os.Args[1:]) @@ -65,31 +66,26 @@ func WantsJSONOutput(cmd *cobra.Command) bool { // argsRequestJSON scans a flag-only slice for --json in the forms pflag // accepts. Used as a fallback when cobra short-circuits before flag parsing -// (unknown command / unknown flag at root). Mirrors only the subset of pflag -// bool parsing relevant here — `--json=false` is treated as not-JSON, -// matching pflag. +// (unknown command / unknown flag at root). Recognizes `--json` bare, +// `--json id,name`, and `--json=id,name` forms. func argsRequestJSON(args []string) bool { - for _, a := range args { + for i, a := range args { switch { case a == "--json": return true case strings.HasPrefix(a, "--json="): - if isPflagTruthy(strings.TrimPrefix(a, "--json=")) { - return true - } + return true + default: + // `--json id,name` — split into two args; we don't try to + // distinguish "next arg is a value" vs "next arg is a flag" + // here, since false positives just mean we emit JSON for an + // error that would otherwise be human (still parseable). + _ = i } } return false } -// isPflagTruthy mirrors pflag's bool parsing for "--flag=" tokens. -// pflag delegates to strconv.ParseBool, which accepts 1/t/T/TRUE/true/True -// as truthy and 0/f/F/FALSE/false/False as falsy. Anything else errors. -func isPflagTruthy(v string) bool { - b, err := strconv.ParseBool(v) - return err == nil && b -} - // MapCobraError tags the textually-emitted cobra errors as cmdutil.FlagError // so they exit 2 like other user invocation mistakes. SetFlagErrorFunc handles // flag parse errors at parse time; this catches positional/Args validation @@ -213,27 +209,38 @@ func agentAwareHelpFunc(orig func(*cobra.Command, []string)) func(*cobra.Command } } +// versionFields enumerates the fields surfaced for `--json` discovery on +// `version`. Mirrors the version envelope payload. +var versionFields = []string{"version", "commit", "date"} + // newVersionCmd is the only leaf command shipped in the foundation PR. It // doubles as the smoke test that proves Factory + iostreams + cobra wiring works. func newVersionCmd(f *cmdutil.Factory) *cobra.Command { - var jsonOut bool cmd := &cobra.Command{ Use: "version", Short: "Show CLI build metadata", Args: cobra.NoArgs, RunE: func(c *cobra.Command, args []string) error { + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } v, commit, date := build.Info() - if jsonOut { - return cmdutil.NewJSONExporter().Write(c.OutOrStdout(), format.Success(map[string]string{ - "version": v, - "commit": commit, - "date": date, - }, nil)) + if jopts.Enabled() { + return format.WriteEnvelopeFiltered( + c.OutOrStdout(), + format.Success(map[string]string{ + "version": v, + "commit": commit, + "date": date, + }, nil), + jopts.Fields, jopts.JQ, + ) } fmt.Fprintf(c.OutOrStdout(), "weknora %s (commit %s, built %s)\n", v, commit, date) return nil }, } - cmd.Flags().BoolVar(&jsonOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, versionFields) return cmd } diff --git a/cli/cmd/root_test.go b/cli/cmd/root_test.go index 938fe5c6..38cd66ac 100644 --- a/cli/cmd/root_test.go +++ b/cli/cmd/root_test.go @@ -139,6 +139,9 @@ func TestRoot_ContextFlagPropagation(t *testing.T) { } func TestArgsRequestJSON(t *testing.T) { + // v0.4 R-1: --json is now StringSlice (gh-style field filter). Any + // `--json` token in args means the user wants JSON output, regardless + // of value (boolean string parsing dropped). cases := []struct { name string args []string @@ -146,10 +149,8 @@ func TestArgsRequestJSON(t *testing.T) { }{ {"empty", nil, false}, {"--json bare", []string{"version", "--json"}, true}, - {"--json=true", []string{"version", "--json=true"}, true}, - {"--json=1", []string{"version", "--json=1"}, true}, - {"--json=TRUE", []string{"version", "--json=TRUE"}, true}, - {"--json=false", []string{"version", "--json=false"}, false}, + {"--json=id,name", []string{"kb", "list", "--json=id,name"}, true}, + {"--json=anything", []string{"version", "--json=foo"}, true}, {"unrelated", []string{"bogus", "--kb", "x"}, false}, } for _, tc := range cases { diff --git a/cli/cmd/search/chunks.go b/cli/cmd/search/chunks.go index 0fbd130e..c312c823 100644 --- a/cli/cmd/search/chunks.go +++ b/cli/cmd/search/chunks.go @@ -14,6 +14,15 @@ import ( sdk "github.com/Tencent/WeKnora/client" ) +// chunksFields enumerates the fields surfaced for `--json` discovery on +// `search chunks`. Lists data.items[*] (SearchResult) fields. +var chunksFields = []string{ + "id", "content", "knowledge_id", "chunk_index", "knowledge_title", + "start_at", "end_at", "seq", "score", "match_type", "chunk_type", + "image_info", "metadata", "knowledge_filename", "knowledge_source", + "knowledge_channel", "matched_content", +} + type ChunksOptions struct { Query string KB string // raw --kb (UUID or name) @@ -23,7 +32,11 @@ type ChunksOptions struct { KeywordThreshold float64 NoVector bool NoKeyword bool - JSONOut bool +} + +// chunksResult is the typed payload emitted under data.items. +type chunksResult struct { + Items []*sdk.SearchResult `json:"items"` } // ChunksService is the narrow SDK surface used by runChunks. *sdk.Client @@ -54,6 +67,10 @@ func NewCmdChunks(f *cmdutil.Factory) *cobra.Command { if opts.Limit < 1 || opts.Limit > 1000 { return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, "--limit must be between 1 and 1000") } + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } cli, err := f.Client() if err != nil { return err @@ -63,7 +80,7 @@ func NewCmdChunks(f *cmdutil.Factory) *cobra.Command { return err } opts.KBID = kbID - return runChunks(c.Context(), opts, cli) + return runChunks(c.Context(), opts, jopts, cli) }, } bindChunksFlags(cmd, opts) @@ -81,7 +98,7 @@ func bindChunksFlags(cmd *cobra.Command, opts *ChunksOptions) { cmd.Flags().Float64Var(&opts.KeywordThreshold, "keyword-threshold", 0, "Keyword retrieval score floor (per-channel, pre-fusion); 0 = no filter") cmd.Flags().BoolVar(&opts.NoVector, "no-vector", false, "Disable the vector channel") cmd.Flags().BoolVar(&opts.NoKeyword, "no-keyword", false, "Disable the keyword channel") - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, chunksFields) } // validate checks the option set before any SDK call. Limit bounds are @@ -97,7 +114,7 @@ func (o *ChunksOptions) validate() error { return nil } -func runChunks(ctx context.Context, opts *ChunksOptions, svc ChunksService) error { +func runChunks(ctx context.Context, opts *ChunksOptions, jopts *cmdutil.JSONOptions, svc ChunksService) error { if err := opts.validate(); err != nil { return err } @@ -127,8 +144,12 @@ func runChunks(ctx context.Context, opts *ChunksOptions, svc ChunksService) erro results = results[:opts.Limit] } - if opts.JSONOut { - return format.WriteEnvelope(iostreams.IO.Out, format.Success(results, &format.Meta{KBID: opts.KBID})) + if jopts.Enabled() { + return format.WriteEnvelopeFiltered( + iostreams.IO.Out, + format.Success(chunksResult{Items: results}, &format.Meta{KBID: opts.KBID}), + jopts.Fields, jopts.JQ, + ) } return renderChunkResults(results, opts.KBID) } diff --git a/cli/cmd/search/chunks_test.go b/cli/cmd/search/chunks_test.go index 094f7025..8ba45df8 100644 --- a/cli/cmd/search/chunks_test.go +++ b/cli/cmd/search/chunks_test.go @@ -34,7 +34,7 @@ func TestRunSearch_HumanOutput(t *testing.T) { {Score: 0.81, Content: "second chunk", KnowledgeID: "doc-2", MatchType: sdk.MatchTypeKeyword}, }} opts := &ChunksOptions{Query: "hello", KBID: "kb_abc", Limit: 5} - require.NoError(t, runChunks(context.Background(), opts, svc)) + require.NoError(t, runChunks(context.Background(), opts, nil, svc)) assert.Equal(t, "kb_abc", svc.gotKB) assert.Equal(t, "hello", svc.gotQ) @@ -52,15 +52,15 @@ func TestRunSearch_JSONIncludesMatchType(t *testing.T) { svc := &fakeChunksSvc{results: []*sdk.SearchResult{ {Score: 0.9, Content: "x", MatchType: sdk.MatchTypeKeyword}, }} - require.NoError(t, runChunks(context.Background(), &ChunksOptions{Query: "q", KBID: "kb1", JSONOut: true}, svc)) + require.NoError(t, runChunks(context.Background(), &ChunksOptions{Query: "q", KBID: "kb1"}, &cmdutil.JSONOptions{}, svc)) assert.Contains(t, out.String(), `"match_type":1`) } func TestRunSearch_JSONOutput(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakeChunksSvc{results: []*sdk.SearchResult{{Score: 0.9, Content: "x"}}} - opts := &ChunksOptions{Query: "q", KBID: "kb1", Limit: 1, JSONOut: true} - require.NoError(t, runChunks(context.Background(), opts, svc)) + opts := &ChunksOptions{Query: "q", KBID: "kb1", Limit: 1} + require.NoError(t, runChunks(context.Background(), opts, &cmdutil.JSONOptions{}, svc)) assert.True(t, strings.HasPrefix(out.String(), `{"ok":true`), "got: %q", out.String()) assert.Contains(t, out.String(), `"kb_id":"kb1"`) } @@ -68,7 +68,7 @@ func TestRunSearch_JSONOutput(t *testing.T) { func TestRunSearch_EmptyResults(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakeChunksSvc{results: nil} - require.NoError(t, runChunks(context.Background(), &ChunksOptions{Query: "q", KBID: "kb1"}, svc)) + require.NoError(t, runChunks(context.Background(), &ChunksOptions{Query: "q", KBID: "kb1"}, nil, svc)) assert.Contains(t, out.String(), "(no results)") } @@ -84,7 +84,7 @@ func TestRunSearch_LimitHardCap(t *testing.T) { {Score: 0, Content: "enrichment parent"}, // server-padded {Score: 0, Content: "enrichment nearby"}, // server-padded }} - require.NoError(t, runChunks(context.Background(), &ChunksOptions{Query: "q", KBID: "kb1", Limit: 3}, svc)) + require.NoError(t, runChunks(context.Background(), &ChunksOptions{Query: "q", KBID: "kb1", Limit: 3}, nil, svc)) got := out.String() assert.Contains(t, got, "3 result(s)") assert.NotContains(t, got, "enrichment parent") @@ -93,7 +93,7 @@ func TestRunSearch_LimitHardCap(t *testing.T) { func TestRunSearch_BothChannelsDisabled(t *testing.T) { iostreams.SetForTest(t) - err := runChunks(context.Background(), &ChunksOptions{Query: "q", KBID: "kb1", NoVector: true, NoKeyword: true}, &fakeChunksSvc{}) + err := runChunks(context.Background(), &ChunksOptions{Query: "q", KBID: "kb1", NoVector: true, NoKeyword: true}, nil, &fakeChunksSvc{}) require.Error(t, err) assert.Contains(t, err.Error(), "input.invalid_argument") } @@ -101,7 +101,7 @@ func TestRunSearch_BothChannelsDisabled(t *testing.T) { func TestRunSearch_ServiceError_Transport(t *testing.T) { iostreams.SetForTest(t) svc := &fakeChunksSvc{err: assert.AnError} - err := runChunks(context.Background(), &ChunksOptions{Query: "q", KBID: "kb1"}, svc) + err := runChunks(context.Background(), &ChunksOptions{Query: "q", KBID: "kb1"}, nil, svc) require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) @@ -112,7 +112,7 @@ func TestRunSearch_ServiceError_Transport(t *testing.T) { func TestRunSearch_ServiceError_HTTPNotFound(t *testing.T) { iostreams.SetForTest(t) svc := &fakeChunksSvc{err: errors.New("HTTP error 404: knowledge base not found")} - err := runChunks(context.Background(), &ChunksOptions{Query: "q", KBID: "missing"}, svc) + err := runChunks(context.Background(), &ChunksOptions{Query: "q", KBID: "missing"}, nil, svc) require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) @@ -126,7 +126,7 @@ func TestIndent(t *testing.T) { func TestRunSearch_NilService(t *testing.T) { iostreams.SetForTest(t) - err := runChunks(context.Background(), &ChunksOptions{Query: "q", KBID: "kb1"}, nil) + err := runChunks(context.Background(), &ChunksOptions{Query: "q", KBID: "kb1"}, nil, nil) require.Error(t, err) assert.Contains(t, err.Error(), "server.error") } @@ -162,7 +162,7 @@ func TestRunSearch_NoVectorPassedThrough(t *testing.T) { svc := &capturingChunksSvc{capture: func(p *sdk.SearchParams) { got = p }} require.NoError(t, runChunks(context.Background(), &ChunksOptions{ Query: "q", KBID: "kb1", NoVector: true, - }, svc)) + }, nil, svc)) require.NotNil(t, got) assert.True(t, got.DisableVectorMatch) assert.False(t, got.DisableKeywordsMatch) @@ -174,7 +174,7 @@ func TestRunSearch_NoKeywordPassedThrough(t *testing.T) { svc := &capturingChunksSvc{capture: func(p *sdk.SearchParams) { got = p }} require.NoError(t, runChunks(context.Background(), &ChunksOptions{ Query: "q", KBID: "kb1", NoKeyword: true, - }, svc)) + }, nil, svc)) require.NotNil(t, got) assert.True(t, got.DisableKeywordsMatch) assert.False(t, got.DisableVectorMatch) diff --git a/cli/cmd/search/docs.go b/cli/cmd/search/docs.go index 25863117..c97cd63c 100644 --- a/cli/cmd/search/docs.go +++ b/cli/cmd/search/docs.go @@ -22,12 +22,26 @@ import ( // 1000 (per the doc/list bound this branch already added). const docsPageSize = 200 +// docsFields enumerates the fields surfaced for `--json` discovery on +// `search docs`. Mirrors sdk.Knowledge json tags. +var docsFields = []string{ + "id", "tenant_id", "knowledge_base_id", "tag_id", "type", "title", + "description", "source", "channel", "parse_status", "summary_status", + "enable_status", "embedding_model_id", "file_name", "file_type", + "file_size", "file_hash", "file_path", "storage_size", "metadata", + "created_at", "updated_at", "processed_at", "error_message", +} + type DocsSearchOptions struct { - Query string - KB string // raw --kb (UUID or name) - KBID string // resolved id; populated before listing - Limit int - JSONOut bool + Query string + KB string // raw --kb (UUID or name) + KBID string // resolved id; populated before listing + Limit int +} + +// docsResult is the typed payload emitted under data.items. +type docsResult struct { + Items []sdk.Knowledge `json:"items"` } // DocsSearchService is the narrow SDK surface this command depends on. @@ -57,6 +71,10 @@ func NewCmdDocs(f *cmdutil.Factory) *cobra.Command { if opts.Limit < 1 || opts.Limit > 1000 { return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, "--limit must be between 1 and 1000") } + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } cli, err := f.Client() if err != nil { return err @@ -66,18 +84,18 @@ func NewCmdDocs(f *cmdutil.Factory) *cobra.Command { return err } opts.KBID = kbID - return runDocsSearch(c.Context(), opts, cli) + return runDocsSearch(c.Context(), opts, jopts, cli) }, } cmd.Flags().StringVar(&opts.KB, "kb", "", "Knowledge base UUID or name (required)") cmd.Flags().IntVarP(&opts.Limit, "limit", "L", 20, "Maximum results to return") - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, docsFields) _ = cmd.MarkFlagRequired("kb") agent.SetAgentHelp(cmd, "Lists documents in --kb whose title or file_name contains the query. Pages through the KB sequentially; stops once limit hits found. Returns the full Knowledge object so agents can derive id / file_size / processed_at without a second call.") return cmd } -func runDocsSearch(ctx context.Context, opts *DocsSearchOptions, svc DocsSearchService) error { +func runDocsSearch(ctx context.Context, opts *DocsSearchOptions, jopts *cmdutil.JSONOptions, svc DocsSearchService) error { needle := strings.ToLower(opts.Query) var matches []sdk.Knowledge @@ -103,8 +121,15 @@ func runDocsSearch(ctx context.Context, opts *DocsSearchOptions, svc DocsSearchS done: sortKnowledgeByRecency(matches) - if opts.JSONOut { - return format.WriteEnvelope(iostreams.IO.Out, format.Success(matches, &format.Meta{KBID: opts.KBID})) + if jopts.Enabled() { + if matches == nil { + matches = []sdk.Knowledge{} + } + return format.WriteEnvelopeFiltered( + iostreams.IO.Out, + format.Success(docsResult{Items: matches}, &format.Meta{KBID: opts.KBID}), + jopts.Fields, jopts.JQ, + ) } if len(matches) == 0 { fmt.Fprintln(iostreams.IO.Out, "(no matches)") diff --git a/cli/cmd/search/docs_test.go b/cli/cmd/search/docs_test.go index 0ac93211..0e891ed3 100644 --- a/cli/cmd/search/docs_test.go +++ b/cli/cmd/search/docs_test.go @@ -45,7 +45,7 @@ func TestDocsSearch_Substring(t *testing.T) { }, total: 3, } - require.NoError(t, runDocsSearch(context.Background(), &DocsSearchOptions{Query: "q3", KBID: "kb1", Limit: 20}, svc)) + require.NoError(t, runDocsSearch(context.Background(), &DocsSearchOptions{Query: "q3", KBID: "kb1", Limit: 20}, nil, svc)) got := out.String() assert.Contains(t, got, "d1") assert.Contains(t, got, "d3") @@ -58,7 +58,7 @@ func TestDocsSearch_MatchesFileName(t *testing.T) { pages: map[int][]sdk.Knowledge{1: {{ID: "d1", Title: "Untitled", FileName: "report.pdf"}}}, total: 1, } - require.NoError(t, runDocsSearch(context.Background(), &DocsSearchOptions{Query: "report", KBID: "kb1", Limit: 20}, svc)) + require.NoError(t, runDocsSearch(context.Background(), &DocsSearchOptions{Query: "report", KBID: "kb1", Limit: 20}, nil, svc)) assert.Contains(t, out.String(), "d1") } @@ -73,7 +73,7 @@ func TestDocsSearch_PaginatesUntilTotal(t *testing.T) { pages: map[int][]sdk.Knowledge{1: page1, 2: page2}, total: int64(docsPageSize) + 1, } - require.NoError(t, runDocsSearch(context.Background(), &DocsSearchOptions{Query: "needle", KBID: "kb1", Limit: 20}, svc)) + require.NoError(t, runDocsSearch(context.Background(), &DocsSearchOptions{Query: "needle", KBID: "kb1", Limit: 20}, nil, svc)) assert.Contains(t, out.String(), "found") assert.Equal(t, []int{1, 2}, svc.calls, "must page past the first batch when no match on page 1") } @@ -85,7 +85,7 @@ func TestDocsSearch_StopsAtLimit(t *testing.T) { page1[i] = sdk.Knowledge{ID: "match", Title: "needle"} } svc := &fakeDocsSearchSvc{pages: map[int][]sdk.Knowledge{1: page1}, total: 1000} - require.NoError(t, runDocsSearch(context.Background(), &DocsSearchOptions{Query: "needle", KBID: "kb1", Limit: 3}, svc)) + require.NoError(t, runDocsSearch(context.Background(), &DocsSearchOptions{Query: "needle", KBID: "kb1", Limit: 3}, nil, svc)) // Must not request page 2 because limit was hit mid-page. assert.Equal(t, []int{1}, svc.calls) } @@ -96,7 +96,7 @@ func TestDocsSearch_JSON(t *testing.T) { pages: map[int][]sdk.Knowledge{1: {{ID: "d1", Title: "match"}}}, total: 1, } - require.NoError(t, runDocsSearch(context.Background(), &DocsSearchOptions{Query: "match", KBID: "kb1", Limit: 20, JSONOut: true}, svc)) + require.NoError(t, runDocsSearch(context.Background(), &DocsSearchOptions{Query: "match", KBID: "kb1", Limit: 20}, &cmdutil.JSONOptions{}, svc)) var env format.Envelope require.NoError(t, json.Unmarshal(out.Bytes(), &env)) require.True(t, env.OK) @@ -106,7 +106,7 @@ func TestDocsSearch_JSON(t *testing.T) { func TestDocsSearch_NetworkError(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakeDocsSearchSvc{err: errors.New("HTTP error 404: kb not found")} - err := runDocsSearch(context.Background(), &DocsSearchOptions{Query: "x", KBID: "missing", Limit: 20}, svc) + err := runDocsSearch(context.Background(), &DocsSearchOptions{Query: "x", KBID: "missing", Limit: 20}, nil, svc) require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) diff --git a/cli/cmd/search/kb.go b/cli/cmd/search/kb.go index e06fea55..428a5ee2 100644 --- a/cli/cmd/search/kb.go +++ b/cli/cmd/search/kb.go @@ -17,10 +17,25 @@ import ( sdk "github.com/Tencent/WeKnora/client" ) +// kbSearchFields enumerates the fields surfaced for `--json` discovery on +// `search kb`. Subset of KnowledgeBase suitable for list/filter results. +var kbSearchFields = []string{ + "id", "name", "type", "description", + "is_temporary", "is_pinned", + "embedding_model_id", "summary_model_id", + "knowledge_count", "chunk_count", + "is_processing", "processing_count", + "created_at", "updated_at", +} + type KBSearchOptions struct { - Query string - Limit int - JSONOut bool + Query string + Limit int +} + +// kbSearchResult is the typed payload emitted under data.items. +type kbSearchResult struct { + Items []sdk.KnowledgeBase `json:"items"` } // KBSearchService is the narrow SDK surface this command depends on. @@ -50,20 +65,24 @@ func NewCmdKB(f *cmdutil.Factory) *cobra.Command { if opts.Limit < 1 || opts.Limit > 1000 { return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, "--limit must be between 1 and 1000") } + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } cli, err := f.Client() if err != nil { return err } - return runKBSearch(c.Context(), opts, cli) + return runKBSearch(c.Context(), opts, jopts, cli) }, } cmd.Flags().IntVarP(&opts.Limit, "limit", "L", 20, "Maximum results to return") - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, kbSearchFields) agent.SetAgentHelp(cmd, "Lists KBs whose name or description contains the query (case-insensitive). Useful to discover --kb identifiers before running search chunks / doc list.") return cmd } -func runKBSearch(ctx context.Context, opts *KBSearchOptions, svc KBSearchService) error { +func runKBSearch(ctx context.Context, opts *KBSearchOptions, jopts *cmdutil.JSONOptions, svc KBSearchService) error { items, err := svc.ListKnowledgeBases(ctx) if err != nil { return cmdutil.WrapHTTP(err, "list knowledge bases") @@ -73,8 +92,15 @@ func runKBSearch(ctx context.Context, opts *KBSearchOptions, svc KBSearchService matches = matches[:opts.Limit] } - if opts.JSONOut { - return format.WriteEnvelope(iostreams.IO.Out, format.Success(matches, nil)) + if jopts.Enabled() { + if matches == nil { + matches = []sdk.KnowledgeBase{} + } + return format.WriteEnvelopeFiltered( + iostreams.IO.Out, + format.Success(kbSearchResult{Items: matches}, nil), + jopts.Fields, jopts.JQ, + ) } if len(matches) == 0 { fmt.Fprintln(iostreams.IO.Out, "(no matches)") diff --git a/cli/cmd/search/kb_test.go b/cli/cmd/search/kb_test.go index e0b2e9e2..8fce7669 100644 --- a/cli/cmd/search/kb_test.go +++ b/cli/cmd/search/kb_test.go @@ -32,7 +32,7 @@ func TestKBSearch_Substring(t *testing.T) { {ID: "kb2", Name: "Engineering Docs", KnowledgeCount: 50}, {ID: "kb3", Name: "Marketing Q4 Plan", KnowledgeCount: 5}, }} - require.NoError(t, runKBSearch(context.Background(), &KBSearchOptions{Query: "marketing", Limit: 20}, svc)) + require.NoError(t, runKBSearch(context.Background(), &KBSearchOptions{Query: "marketing", Limit: 20}, nil, svc)) got := out.String() assert.Contains(t, got, "kb1") assert.Contains(t, got, "kb3") @@ -44,7 +44,7 @@ func TestKBSearch_CaseInsensitive(t *testing.T) { svc := &fakeKBSearchSvc{items: []sdk.KnowledgeBase{ {ID: "kb1", Name: "ENGINEERING"}, }} - require.NoError(t, runKBSearch(context.Background(), &KBSearchOptions{Query: "engineering", Limit: 20}, svc)) + require.NoError(t, runKBSearch(context.Background(), &KBSearchOptions{Query: "engineering", Limit: 20}, nil, svc)) assert.Contains(t, out.String(), "kb1") } @@ -53,7 +53,7 @@ func TestKBSearch_MatchesDescription(t *testing.T) { svc := &fakeKBSearchSvc{items: []sdk.KnowledgeBase{ {ID: "kb1", Name: "Engineering", Description: "all marketing docs are here"}, }} - require.NoError(t, runKBSearch(context.Background(), &KBSearchOptions{Query: "marketing", Limit: 20}, svc)) + require.NoError(t, runKBSearch(context.Background(), &KBSearchOptions{Query: "marketing", Limit: 20}, nil, svc)) assert.Contains(t, out.String(), "kb1") } @@ -64,7 +64,7 @@ func TestKBSearch_SortByNameLength(t *testing.T) { {ID: "kb_short", Name: "marketing"}, {ID: "kb_mid", Name: "marketing 2024"}, }} - require.NoError(t, runKBSearch(context.Background(), &KBSearchOptions{Query: "marketing", Limit: 20}, svc)) + require.NoError(t, runKBSearch(context.Background(), &KBSearchOptions{Query: "marketing", Limit: 20}, nil, svc)) got := out.String() // Order: shortest name first. iShort := strings.Index(got,"kb_short") @@ -80,7 +80,7 @@ func TestKBSearch_LimitHardCap(t *testing.T) { {ID: "a", Name: "match-a"}, {ID: "b", Name: "match-b"}, {ID: "c", Name: "match-c"}, {ID: "d", Name: "match-d"}, }} - require.NoError(t, runKBSearch(context.Background(), &KBSearchOptions{Query: "match", Limit: 2}, svc)) + require.NoError(t, runKBSearch(context.Background(), &KBSearchOptions{Query: "match", Limit: 2}, nil, svc)) got := out.String() count := 0 for _, id := range []string{"a", "b", "c", "d"} { @@ -94,14 +94,14 @@ func TestKBSearch_LimitHardCap(t *testing.T) { func TestKBSearch_NoMatches(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakeKBSearchSvc{items: []sdk.KnowledgeBase{{Name: "foo"}}} - require.NoError(t, runKBSearch(context.Background(), &KBSearchOptions{Query: "bar", Limit: 20}, svc)) + require.NoError(t, runKBSearch(context.Background(), &KBSearchOptions{Query: "bar", Limit: 20}, nil, svc)) assert.Contains(t, out.String(), "(no matches)") } func TestKBSearch_JSON(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakeKBSearchSvc{items: []sdk.KnowledgeBase{{ID: "kb1", Name: "marketing"}}} - require.NoError(t, runKBSearch(context.Background(), &KBSearchOptions{Query: "marketing", Limit: 20, JSONOut: true}, svc)) + require.NoError(t, runKBSearch(context.Background(), &KBSearchOptions{Query: "marketing", Limit: 20}, &cmdutil.JSONOptions{}, svc)) var env format.Envelope require.NoError(t, json.Unmarshal(out.Bytes(), &env)) @@ -112,7 +112,7 @@ func TestKBSearch_JSON(t *testing.T) { func TestKBSearch_NetworkError(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakeKBSearchSvc{err: errors.New("HTTP error 401: unauthenticated")} - err := runKBSearch(context.Background(), &KBSearchOptions{Query: "x", Limit: 20}, svc) + err := runKBSearch(context.Background(), &KBSearchOptions{Query: "x", Limit: 20}, nil, svc) require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) diff --git a/cli/cmd/search/sessions.go b/cli/cmd/search/sessions.go index 1c719888..4a76ecae 100644 --- a/cli/cmd/search/sessions.go +++ b/cli/cmd/search/sessions.go @@ -19,10 +19,20 @@ import ( const sessionsPageSize = 200 +// sessionsSearchFields enumerates the fields surfaced for `--json` discovery +// on `search sessions`. Mirrors sdk.Session json tags. +var sessionsSearchFields = []string{ + "id", "tenant_id", "title", "description", "created_at", "updated_at", +} + type SessionsSearchOptions struct { - Query string - Limit int - JSONOut bool + Query string + Limit int +} + +// sessionsSearchResult is the typed payload emitted under data.items. +type sessionsSearchResult struct { + Items []sdk.Session `json:"items"` } // SessionsSearchService is the narrow SDK surface this command depends on. @@ -50,20 +60,24 @@ func NewCmdSessions(f *cmdutil.Factory) *cobra.Command { if opts.Limit < 1 || opts.Limit > 1000 { return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, "--limit must be between 1 and 1000") } + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } cli, err := f.Client() if err != nil { return err } - return runSessionsSearch(c.Context(), opts, cli) + return runSessionsSearch(c.Context(), opts, jopts, cli) }, } cmd.Flags().IntVarP(&opts.Limit, "limit", "L", 20, "Maximum results to return") - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, sessionsSearchFields) agent.SetAgentHelp(cmd, "Lists chat sessions whose title or description contains the query. Pages through the tenant sequentially; stops once limit matches found. Returns full Session objects so agents can pivot to session view/delete by id.") return cmd } -func runSessionsSearch(ctx context.Context, opts *SessionsSearchOptions, svc SessionsSearchService) error { +func runSessionsSearch(ctx context.Context, opts *SessionsSearchOptions, jopts *cmdutil.JSONOptions, svc SessionsSearchService) error { needle := strings.ToLower(opts.Query) var matches []sdk.Session @@ -87,8 +101,15 @@ func runSessionsSearch(ctx context.Context, opts *SessionsSearchOptions, svc Ses done: sortSessionsByRecency(matches) - if opts.JSONOut { - return format.WriteEnvelope(iostreams.IO.Out, format.Success(matches, nil)) + if jopts.Enabled() { + if matches == nil { + matches = []sdk.Session{} + } + return format.WriteEnvelopeFiltered( + iostreams.IO.Out, + format.Success(sessionsSearchResult{Items: matches}, nil), + jopts.Fields, jopts.JQ, + ) } if len(matches) == 0 { fmt.Fprintln(iostreams.IO.Out, "(no matches)") diff --git a/cli/cmd/search/sessions_test.go b/cli/cmd/search/sessions_test.go index 8c82494e..eea23c6f 100644 --- a/cli/cmd/search/sessions_test.go +++ b/cli/cmd/search/sessions_test.go @@ -38,7 +38,7 @@ func TestSessionsSearch_TitleAndDescription(t *testing.T) { }}, total: 3, } - require.NoError(t, runSessionsSearch(context.Background(), &SessionsSearchOptions{Query: "design", Limit: 20}, svc)) + require.NoError(t, runSessionsSearch(context.Background(), &SessionsSearchOptions{Query: "design", Limit: 20}, nil, svc)) got := out.String() assert.Contains(t, got, "s1") assert.Contains(t, got, "s2") @@ -51,7 +51,7 @@ func TestSessionsSearch_NoMatches(t *testing.T) { pages: map[int][]sdk.Session{1: {{Title: "foo"}}}, total: 1, } - require.NoError(t, runSessionsSearch(context.Background(), &SessionsSearchOptions{Query: "missing", Limit: 20}, svc)) + require.NoError(t, runSessionsSearch(context.Background(), &SessionsSearchOptions{Query: "missing", Limit: 20}, nil, svc)) assert.Contains(t, out.String(), "(no matches)") } @@ -62,14 +62,14 @@ func TestSessionsSearch_PaginatesAndStopsAtLimit(t *testing.T) { page1[i] = sdk.Session{ID: "m", Title: "needle"} } svc := &fakeSessionsSearchSvc{pages: map[int][]sdk.Session{1: page1}, total: 1000} - require.NoError(t, runSessionsSearch(context.Background(), &SessionsSearchOptions{Query: "needle", Limit: 5}, svc)) + require.NoError(t, runSessionsSearch(context.Background(), &SessionsSearchOptions{Query: "needle", Limit: 5}, nil, svc)) assert.Equal(t, []int{1}, svc.calls, "stops paging when limit reached") } func TestSessionsSearch_NetworkError(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakeSessionsSearchSvc{err: errors.New("HTTP error 500: internal")} - err := runSessionsSearch(context.Background(), &SessionsSearchOptions{Query: "x", Limit: 20}, svc) + err := runSessionsSearch(context.Background(), &SessionsSearchOptions{Query: "x", Limit: 20}, nil, svc) require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) diff --git a/cli/cmd/session/delete.go b/cli/cmd/session/delete.go index 0ed32912..de7e84ba 100644 --- a/cli/cmd/session/delete.go +++ b/cli/cmd/session/delete.go @@ -13,10 +13,13 @@ import ( "github.com/Tencent/WeKnora/cli/internal/prompt" ) +// sessionDeleteFields enumerates the fields surfaced for `--json` discovery on +// `session delete`. Tracks the small result struct. +var sessionDeleteFields = []string{"id", "deleted"} + type DeleteOptions struct { - Yes bool // sourced from the global -y/--yes persistent flag - JSONOut bool - DryRun bool + Yes bool // sourced from the global -y/--yes persistent flag + DryRun bool } // DeleteService is the narrow SDK surface this command depends on. @@ -52,30 +55,34 @@ without the user's explicit go-ahead.`, RunE: func(c *cobra.Command, args []string) error { opts.Yes, _ = c.Flags().GetBool("yes") opts.DryRun = cmdutil.IsDryRun(c) + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } if opts.DryRun { - return runDelete(c.Context(), opts, nil, f.Prompter(), args[0]) + return runDelete(c.Context(), opts, jopts, nil, f.Prompter(), args[0]) } cli, err := f.Client() if err != nil { return err } - return runDelete(c.Context(), opts, cli, f.Prompter(), args[0]) + return runDelete(c.Context(), opts, jopts, cli, f.Prompter(), args[0]) }, } - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, sessionDeleteFields) agent.SetAgentHelp(cmd, "Destructively deletes a chat session by id. ALWAYS pass -y/--yes in agent mode (no TTY ⇒ confirm prompt fails). Returns data: {id, deleted:true}.") return cmd } -func runDelete(ctx context.Context, opts *DeleteOptions, svc DeleteService, p prompt.Prompter, id string) error { +func runDelete(ctx context.Context, opts *DeleteOptions, jopts *cmdutil.JSONOptions, svc DeleteService, p prompt.Prompter, id string) error { risk := &format.Risk{Level: format.RiskHighRiskWrite, Action: fmt.Sprintf("delete session %s", id)} if opts.DryRun { - return cmdutil.EmitDryRun(opts.JSONOut, + return cmdutil.EmitDryRun(jopts.Enabled(), deleteResult{ID: id, Deleted: false}, nil, risk) } - if err := cmdutil.ConfirmDestructive(p, opts.Yes, opts.JSONOut, "session", id); err != nil { + if err := cmdutil.ConfirmDestructive(p, opts.Yes, jopts.Enabled(), "session", id); err != nil { return err } @@ -83,10 +90,12 @@ func runDelete(ctx context.Context, opts *DeleteOptions, svc DeleteService, p pr return cmdutil.WrapHTTP(err, "delete session %s", id) } - if opts.JSONOut { - return format.WriteEnvelope(iostreams.IO.Out, format.SuccessWithRisk( - deleteResult{ID: id, Deleted: true}, nil, risk, - )) + if jopts.Enabled() { + return format.WriteEnvelopeFiltered( + iostreams.IO.Out, + format.SuccessWithRisk(deleteResult{ID: id, Deleted: true}, nil, risk), + jopts.Fields, jopts.JQ, + ) } fmt.Fprintf(iostreams.IO.Out, "✓ Deleted session %s\n", id) return nil diff --git a/cli/cmd/session/delete_test.go b/cli/cmd/session/delete_test.go index b6e735a9..48a70c14 100644 --- a/cli/cmd/session/delete_test.go +++ b/cli/cmd/session/delete_test.go @@ -31,7 +31,7 @@ func TestDelete_WithYes(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakeDeleteSvc{} p := &testutil.ConfirmPrompter{} - require.NoError(t, runDelete(context.Background(), &DeleteOptions{Yes: true}, svc, p, "s_abc")) + require.NoError(t, runDelete(context.Background(), &DeleteOptions{Yes: true}, nil, svc, p, "s_abc")) assert.True(t, svc.called) assert.Equal(t, "s_abc", svc.gotID) assert.False(t, p.Asked, "-y must skip prompt") @@ -41,7 +41,7 @@ func TestDelete_WithYes(t *testing.T) { func TestDelete_NotFound(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakeDeleteSvc{err: errors.New("HTTP error 404: not found")} - err := runDelete(context.Background(), &DeleteOptions{Yes: true}, svc, &testutil.ConfirmPrompter{}, "s_missing") + err := runDelete(context.Background(), &DeleteOptions{Yes: true}, nil, svc, &testutil.ConfirmPrompter{}, "s_missing") require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) @@ -51,7 +51,7 @@ func TestDelete_NotFound(t *testing.T) { func TestDelete_NonTTY_NoYes_RequiresConfirmation(t *testing.T) { iostreams.SetForTest(t) svc := &fakeDeleteSvc{} - err := runDelete(context.Background(), &DeleteOptions{}, svc, &testutil.ConfirmPrompter{}, "s_x") + err := runDelete(context.Background(), &DeleteOptions{}, nil, svc, &testutil.ConfirmPrompter{}, "s_x") require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) @@ -64,7 +64,7 @@ func TestDelete_TTY_ConfirmYes(t *testing.T) { _, _ = iostreams.SetForTestWithTTY(t) svc := &fakeDeleteSvc{} p := &testutil.ConfirmPrompter{Answer: true} - require.NoError(t, runDelete(context.Background(), &DeleteOptions{}, svc, p, "s_yes")) + require.NoError(t, runDelete(context.Background(), &DeleteOptions{}, nil, svc, p, "s_yes")) assert.True(t, p.Asked) assert.True(t, svc.called) } @@ -73,7 +73,7 @@ func TestDelete_TTY_ConfirmNo(t *testing.T) { _, errBuf := iostreams.SetForTestWithTTY(t) svc := &fakeDeleteSvc{} p := &testutil.ConfirmPrompter{Answer: false} - err := runDelete(context.Background(), &DeleteOptions{}, svc, p, "s_no") + err := runDelete(context.Background(), &DeleteOptions{}, nil, svc, p, "s_no") require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) @@ -85,7 +85,7 @@ func TestDelete_TTY_ConfirmNo(t *testing.T) { func TestDelete_DryRun_JSON(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakeDeleteSvc{} - require.NoError(t, runDelete(context.Background(), &DeleteOptions{DryRun: true, JSONOut: true}, svc, &testutil.ConfirmPrompter{}, "s_dry")) + require.NoError(t, runDelete(context.Background(), &DeleteOptions{DryRun: true}, &cmdutil.JSONOptions{}, svc, &testutil.ConfirmPrompter{}, "s_dry")) body := out.String() assert.True(t, strings.HasPrefix(body, `{"ok":true`)) assert.Contains(t, body, `"dry_run":true`) diff --git a/cli/cmd/session/list.go b/cli/cmd/session/list.go index 79c5e281..68c6c36b 100644 --- a/cli/cmd/session/list.go +++ b/cli/cmd/session/list.go @@ -22,10 +22,15 @@ const ( maxPageSize = 1000 ) +// sessionListFields enumerates the fields surfaced for `--json` discovery on +// `session list`. Mirrors sdk.Session json tags. +var sessionListFields = []string{ + "id", "tenant_id", "title", "description", "created_at", "updated_at", +} + type ListOptions struct { Page int PageSize int - JSONOut bool } // ListService is the narrow SDK surface this command depends on. @@ -47,21 +52,25 @@ func NewCmdList(f *cmdutil.Factory) *cobra.Command { Short: "List chat sessions for the active context", Args: cobra.NoArgs, RunE: func(c *cobra.Command, _ []string) error { + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } cli, err := f.Client() if err != nil { return err } - return runList(c.Context(), opts, cli) + return runList(c.Context(), opts, jopts, cli) }, } cmd.Flags().IntVar(&opts.Page, "page", defaultPage, "Page number (1-indexed)") cmd.Flags().IntVar(&opts.PageSize, "page-size", defaultPageSize, "Items per page (1..1000)") - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, sessionListFields) agent.SetAgentHelp(cmd, "Lists chat sessions. _meta.has_more is set when more pages exist; bump --page and retry to walk them.") return cmd } -func runList(ctx context.Context, opts *ListOptions, svc ListService) error { +func runList(ctx context.Context, opts *ListOptions, jopts *cmdutil.JSONOptions, svc ListService) error { if opts.Page < 1 { return &cmdutil.Error{ Code: cmdutil.CodeInputInvalidArgument, @@ -83,9 +92,13 @@ func runList(ctx context.Context, opts *ListOptions, svc ListService) error { items = []sdk.Session{} // JSON [] not null } - if opts.JSONOut { + if jopts.Enabled() { meta := &format.Meta{HasMore: opts.Page*opts.PageSize < total} - return format.WriteEnvelope(iostreams.IO.Out, format.Success(listResult{Items: items}, meta)) + return format.WriteEnvelopeFiltered( + iostreams.IO.Out, + format.Success(listResult{Items: items}, meta), + jopts.Fields, jopts.JQ, + ) } if len(items) == 0 { diff --git a/cli/cmd/session/list_test.go b/cli/cmd/session/list_test.go index 6eeb0167..c3351716 100644 --- a/cli/cmd/session/list_test.go +++ b/cli/cmd/session/list_test.go @@ -34,7 +34,7 @@ func (f *fakeListService) GetSessionsByTenant(_ context.Context, page, pageSize func TestList_Empty(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakeListService{items: nil, total: 0} - require.NoError(t, runList(context.Background(), &ListOptions{Page: 1, PageSize: 30}, svc)) + require.NoError(t, runList(context.Background(), &ListOptions{Page: 1, PageSize: 30}, nil, svc)) assert.Contains(t, out.String(), "no sessions") } @@ -47,7 +47,7 @@ func TestList_Table(t *testing.T) { }, total: 2, } - require.NoError(t, runList(context.Background(), &ListOptions{Page: 1, PageSize: 30}, svc)) + require.NoError(t, runList(context.Background(), &ListOptions{Page: 1, PageSize: 30}, nil, svc)) got := out.String() assert.Contains(t, got, "s_1") assert.Contains(t, got, "Design review") @@ -64,7 +64,7 @@ func TestList_JSON_WithMeta(t *testing.T) { }, total: 47, } - require.NoError(t, runList(context.Background(), &ListOptions{Page: 2, PageSize: 10, JSONOut: true}, svc)) + require.NoError(t, runList(context.Background(), &ListOptions{Page: 2, PageSize: 10}, &cmdutil.JSONOptions{}, svc)) var env format.Envelope require.NoError(t, json.Unmarshal(out.Bytes(), &env)) @@ -86,7 +86,7 @@ func TestList_JSON_LastPage_NoHasMore(t *testing.T) { items: []sdk.Session{{ID: "s_1"}}, total: 11, } - require.NoError(t, runList(context.Background(), &ListOptions{Page: 2, PageSize: 10, JSONOut: true}, svc)) + require.NoError(t, runList(context.Background(), &ListOptions{Page: 2, PageSize: 10}, &cmdutil.JSONOptions{}, svc)) // page*size = 20 ≥ total 11 → has_more must be false (omitempty drops the key) body := out.String() assert.NotContains(t, body, `"has_more":true`) @@ -95,7 +95,7 @@ func TestList_JSON_LastPage_NoHasMore(t *testing.T) { func TestList_NilItems_RendersAsEmptyArray(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakeListService{items: nil, total: 0} - require.NoError(t, runList(context.Background(), &ListOptions{Page: 1, PageSize: 30, JSONOut: true}, svc)) + require.NoError(t, runList(context.Background(), &ListOptions{Page: 1, PageSize: 30}, &cmdutil.JSONOptions{}, svc)) assert.Contains(t, out.String(), `"items":[]`) } @@ -112,7 +112,7 @@ func TestList_BadPagination(t *testing.T) { } for _, tc := range cases { t.Run(tc.name, func(t *testing.T) { - err := runList(context.Background(), &ListOptions{Page: tc.page, PageSize: tc.size}, &fakeListService{}) + err := runList(context.Background(), &ListOptions{Page: tc.page, PageSize: tc.size}, nil, &fakeListService{}) require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) @@ -124,7 +124,7 @@ func TestList_BadPagination(t *testing.T) { func TestList_NetworkError_TypedCode(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakeListService{err: errors.New("HTTP error 401: unauthenticated")} - err := runList(context.Background(), &ListOptions{Page: 1, PageSize: 30}, svc) + err := runList(context.Background(), &ListOptions{Page: 1, PageSize: 30}, nil, svc) require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) @@ -135,6 +135,6 @@ func TestList_NetworkError_TypedCode(t *testing.T) { func TestList_NonASCIITitle(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakeListService{items: []sdk.Session{{ID: "s_zh", Title: strings.Repeat("中文", 50)}}, total: 1} - require.NoError(t, runList(context.Background(), &ListOptions{Page: 1, PageSize: 30}, svc)) + require.NoError(t, runList(context.Background(), &ListOptions{Page: 1, PageSize: 30}, nil, svc)) assert.Contains(t, out.String(), "s_zh") } diff --git a/cli/cmd/session/view.go b/cli/cmd/session/view.go index 53187388..72ce7545 100644 --- a/cli/cmd/session/view.go +++ b/cli/cmd/session/view.go @@ -14,10 +14,14 @@ import ( sdk "github.com/Tencent/WeKnora/client" ) -type ViewOptions struct { - JSONOut bool +// sessionViewFields enumerates the fields surfaced for `--json` discovery on +// `session view`. Mirrors sdk.Session json tags. +var sessionViewFields = []string{ + "id", "tenant_id", "title", "description", "created_at", "updated_at", } +type ViewOptions struct{} + // ViewService is the narrow SDK surface this command depends on. type ViewService interface { GetSession(ctx context.Context, id string) (*sdk.Session, error) @@ -34,25 +38,33 @@ func NewCmdView(f *cmdutil.Factory) *cobra.Command { Short: "Show a chat session by ID", Args: cobra.ExactArgs(1), RunE: func(c *cobra.Command, args []string) error { + jopts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } cli, err := f.Client() if err != nil { return err } - return runView(c.Context(), opts, cli, args[0]) + return runView(c.Context(), opts, jopts, cli, args[0]) }, } - cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.AddJSONFlags(cmd, sessionViewFields) agent.SetAgentHelp(cmd, "Shows a chat session's metadata (title, description, timestamps). Errors with resource.not_found if id is unknown.") return cmd } -func runView(ctx context.Context, opts *ViewOptions, svc ViewService, id string) error { +func runView(ctx context.Context, opts *ViewOptions, jopts *cmdutil.JSONOptions, svc ViewService, id string) error { s, err := svc.GetSession(ctx, id) if err != nil { return cmdutil.WrapHTTP(err, "get session %q", id) } - if opts.JSONOut { - return format.WriteEnvelope(iostreams.IO.Out, format.Success(s, nil)) + if jopts.Enabled() { + return format.WriteEnvelopeFiltered( + iostreams.IO.Out, + format.Success(s, nil), + jopts.Fields, jopts.JQ, + ) } w := iostreams.IO.Out fmt.Fprintf(w, "ID: %s\n", s.ID) diff --git a/cli/cmd/session/view_test.go b/cli/cmd/session/view_test.go index 1c15b82c..09cd2c43 100644 --- a/cli/cmd/session/view_test.go +++ b/cli/cmd/session/view_test.go @@ -37,7 +37,7 @@ func TestView_Human(t *testing.T) { CreatedAt: "2026-05-10T09:00:00Z", UpdatedAt: "2026-05-12T14:00:00Z", }} - require.NoError(t, runView(context.Background(), &ViewOptions{}, svc, "s_abc")) + require.NoError(t, runView(context.Background(), &ViewOptions{}, nil, svc, "s_abc")) got := out.String() for _, want := range []string{"s_abc", "Design review", "RAG chunking strategy review", "2026-05-12"} { assert.Contains(t, got, want) @@ -48,7 +48,7 @@ func TestView_Human(t *testing.T) { func TestView_JSON(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakeViewService{s: &sdk.Session{ID: "s_abc", Title: "T", UpdatedAt: "2026-05-12T14:00:00Z"}} - require.NoError(t, runView(context.Background(), &ViewOptions{JSONOut: true}, svc, "s_abc")) + require.NoError(t, runView(context.Background(), &ViewOptions{}, &cmdutil.JSONOptions{}, svc, "s_abc")) var env format.Envelope require.NoError(t, json.Unmarshal(out.Bytes(), &env)) @@ -60,7 +60,7 @@ func TestView_JSON(t *testing.T) { func TestView_NotFound(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakeViewService{err: errors.New("HTTP error 404: not found")} - err := runView(context.Background(), &ViewOptions{}, svc, "s_missing") + err := runView(context.Background(), &ViewOptions{}, nil, svc, "s_missing") require.Error(t, err) var typed *cmdutil.Error require.ErrorAs(t, err, &typed) @@ -70,7 +70,7 @@ func TestView_NotFound(t *testing.T) { func TestView_OmitsEmptyDescription(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakeViewService{s: &sdk.Session{ID: "s_min", Title: "Bare"}} - require.NoError(t, runView(context.Background(), &ViewOptions{}, svc, "s_min")) + require.NoError(t, runView(context.Background(), &ViewOptions{}, nil, svc, "s_min")) // Empty Description should not produce an empty `DESC:` line. for line := range strings.SplitSeq(out.String(), "\n") { if strings.HasPrefix(line, "DESC:") { diff --git a/cli/go.mod b/cli/go.mod index 22e3ce9b..1ad044d4 100644 --- a/cli/go.mod +++ b/cli/go.mod @@ -7,9 +7,11 @@ toolchain go1.24.4 require ( github.com/Tencent/WeKnora/client v0.0.0-00010101000000-000000000000 github.com/charmbracelet/huh v1.0.0 + github.com/itchyny/gojq v0.12.19 github.com/mattn/go-isatty v0.0.22 github.com/mattn/go-runewidth v0.0.23 github.com/spf13/cobra v1.10.2 + github.com/spf13/pflag v1.0.10 github.com/stretchr/testify v1.11.1 github.com/zalando/go-keyring v0.2.8 gopkg.in/yaml.v3 v3.0.1 @@ -27,13 +29,15 @@ require ( github.com/charmbracelet/x/cellbuf v0.0.13 // indirect github.com/charmbracelet/x/exp/strings v0.0.0-20240722160745-212f7b056ed0 // indirect github.com/charmbracelet/x/term v0.2.1 // indirect - github.com/clipperhouse/uax29/v2 v2.2.0 // indirect + github.com/clipperhouse/stringish v0.1.1 // indirect + github.com/clipperhouse/uax29/v2 v2.3.0 // indirect github.com/danieljoos/wincred v1.2.3 // indirect github.com/davecgh/go-spew v1.1.1 // indirect github.com/dustin/go-humanize v1.0.1 // indirect github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect github.com/godbus/dbus/v5 v5.2.2 // indirect github.com/inconshreveable/mousetrap v1.1.0 // indirect + github.com/itchyny/timefmt-go v0.1.8 // indirect github.com/lucasb-eyer/go-colorful v1.2.0 // indirect github.com/mattn/go-localereader v0.0.1 // indirect github.com/mitchellh/hashstructure/v2 v2.0.2 // indirect @@ -42,10 +46,9 @@ require ( github.com/muesli/termenv v0.16.0 // indirect github.com/pmezard/go-difflib v1.0.0 // indirect github.com/rivo/uniseg v0.4.7 // indirect - github.com/spf13/pflag v1.0.10 // indirect github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect golang.org/x/sync v0.15.0 // indirect - golang.org/x/sys v0.33.0 // indirect + golang.org/x/sys v0.38.0 // indirect golang.org/x/text v0.23.0 // indirect ) diff --git a/cli/go.sum b/cli/go.sum index d544fbba..44f05d34 100644 --- a/cli/go.sum +++ b/cli/go.sum @@ -36,8 +36,10 @@ github.com/charmbracelet/x/termios v0.1.1 h1:o3Q2bT8eqzGnGPOYheoYS8eEleT5ZVNYNy8 github.com/charmbracelet/x/termios v0.1.1/go.mod h1:rB7fnv1TgOPOyyKRJ9o+AsTU/vK5WHJ2ivHeut/Pcwo= github.com/charmbracelet/x/xpty v0.1.2 h1:Pqmu4TEJ8KeA9uSkISKMU3f+C1F6OGBn8ABuGlqCbtI= github.com/charmbracelet/x/xpty v0.1.2/go.mod h1:XK2Z0id5rtLWcpeNiMYBccNNBrP2IJnzHI0Lq13Xzq4= -github.com/clipperhouse/uax29/v2 v2.2.0 h1:ChwIKnQN3kcZteTXMgb1wztSgaU+ZemkgWdohwgs8tY= -github.com/clipperhouse/uax29/v2 v2.2.0/go.mod h1:EFJ2TJMRUaplDxHKj1qAEhCtQPW2tJSwu5BF98AuoVM= +github.com/clipperhouse/stringish v0.1.1 h1:+NSqMOr3GR6k1FdRhhnXrLfztGzuG+VuFDfatpWHKCs= +github.com/clipperhouse/stringish v0.1.1/go.mod h1:v/WhFtE1q0ovMta2+m+UbpZ+2/HEXNWYXQgCt4hdOzA= +github.com/clipperhouse/uax29/v2 v2.3.0 h1:SNdx9DVUqMoBuBoW3iLOj4FQv3dN5mDtuqwuhIGpJy4= +github.com/clipperhouse/uax29/v2 v2.3.0/go.mod h1:Wn1g7MK6OoeDT0vL+Q0SQLDz/KpfsVRgg6W7ihQeh4g= github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g= github.com/creack/pty v1.1.24 h1:bJrF4RRfyJnbTJqzRLHzcGaZK1NeM5kTC9jGgovnR1s= github.com/creack/pty v1.1.24/go.mod h1:08sCNb52WyoAwi2QDyzUCTgcvVFhUzewun7wtTfvcwE= @@ -53,6 +55,10 @@ github.com/godbus/dbus/v5 v5.2.2 h1:TUR3TgtSVDmjiXOgAAyaZbYmIeP3DPkld3jgKGV8mXQ= github.com/godbus/dbus/v5 v5.2.2/go.mod h1:3AAv2+hPq5rdnr5txxxRwiGjPXamgoIHgz9FPBfOp3c= github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8= github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= +github.com/itchyny/gojq v0.12.19 h1:ttXA0XCLEMoaLOz5lSeFOZ6u6Q3QxmG46vfgI4O0DEs= +github.com/itchyny/gojq v0.12.19/go.mod h1:5galtVPDywX8SPSOrqjGxkBeDhSxEW1gSxoy7tn1iZY= +github.com/itchyny/timefmt-go v0.1.8 h1:1YEo1JvfXeAHKdjelbYr/uCuhkybaHCeTkH8Bo791OI= +github.com/itchyny/timefmt-go v0.1.8/go.mod h1:5E46Q+zj7vbTgWY8o5YkMeYb4I6GeWLFnetPy5oBrAI= github.com/lucasb-eyer/go-colorful v1.2.0 h1:1nnpGOrhyZZuNyfu1QjKiUICQ74+3FNCN69Aj6K7nkY= github.com/lucasb-eyer/go-colorful v1.2.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0= github.com/mattn/go-isatty v0.0.22 h1:j8l17JJ9i6VGPUFUYoTUKPSgKe/83EYU2zBC7YNKMw4= @@ -93,8 +99,8 @@ golang.org/x/exp v0.0.0-20231006140011-7918f672742d/go.mod h1:ldy0pHrwJyGW56pPQz golang.org/x/sync v0.15.0 h1:KWH3jNZsfyT6xfAfKiz6MRNmd46ByHDYaZ7KSkCtdW8= golang.org/x/sync v0.15.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA= golang.org/x/sys v0.0.0-20210809222454-d867a43fc93e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= -golang.org/x/sys v0.33.0 h1:q3i8TbbEz+JRD9ywIRlyRAQbM0qF7hu24q3teo2hbuw= -golang.org/x/sys v0.33.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k= +golang.org/x/sys v0.38.0 h1:3yZWxaJjBmCWXqhN1qh02AkOnCQ1poK6oF+a7xWL6Gc= +golang.org/x/sys v0.38.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks= golang.org/x/text v0.23.0 h1:D71I7dUrlY+VX0gQShAThNGHFxZ13dGLBHQLVl1mJlY= golang.org/x/text v0.23.0/go.mod h1:/BLNzu4aZCJ1+kcD0DNRotWKage4q2rGVAg4o22unh4= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM= diff --git a/cli/internal/cmdutil/errors.go b/cli/internal/cmdutil/errors.go index 42a3014d..9d1fe98e 100644 --- a/cli/internal/cmdutil/errors.go +++ b/cli/internal/cmdutil/errors.go @@ -46,7 +46,7 @@ const ( CodeNetworkError ErrorCode = "network.error" // CodeSessionCreateFailed marks a chat invocation where the auto-created // session POST failed. Surfaced as a typed code distinct from generic - // server.error so agents can retry with their own --session-id. + // server.error so agents can retry with their own --session. CodeSessionCreateFailed ErrorCode = "server.session_create_failed" // local.* — config / file / keychain on the user's machine diff --git a/cli/internal/cmdutil/exit.go b/cli/internal/cmdutil/exit.go index b32108e9..835af3b7 100644 --- a/cli/internal/cmdutil/exit.go +++ b/cli/internal/cmdutil/exit.go @@ -195,7 +195,7 @@ func defaultHint(code ErrorCode) string { case CodeSSEStreamAborted: return "the streaming answer was cut off mid-flight; retry, or pass --no-stream to buffer the full response" case CodeSessionCreateFailed: - return "could not create a chat session; pass --session-id to reuse an existing session" + return "could not create a chat session; pass --session to reuse an existing session" } return "" } diff --git a/cli/internal/cmdutil/factory.go b/cli/internal/cmdutil/factory.go index 208d6b44..feb5ff0b 100644 --- a/cli/internal/cmdutil/factory.go +++ b/cli/internal/cmdutil/factory.go @@ -139,7 +139,7 @@ func buildClient(f *Factory) (*sdk.Client, error) { // authenticated invocation. var accessToken string if ctx.TokenRef != "" { - if access, err := loadSecret(store, ctxName, "access"); err != nil { + if access, err := LoadSecret(store, ctxName, "access"); err != nil { return nil, err } else if access != "" { accessToken = access @@ -147,7 +147,7 @@ func buildClient(f *Factory) (*sdk.Client, error) { } } if ctx.APIKeyRef != "" { - if apiKey, err := loadSecret(store, ctxName, "api_key"); err != nil { + if apiKey, err := LoadSecret(store, ctxName, "api_key"); err != nil { return nil, err } else if apiKey != "" { opts = append(opts, sdk.WithAPIKey(apiKey)) @@ -213,9 +213,12 @@ func (f *Factory) ResolveKB(cmd *cobra.Command) (string, error) { return "", NewError(CodeKBIDRequired, "kb is required") } -// loadSecret returns the stored value for (context, key); ErrNotFound becomes -// ("", nil) so callers can treat "not configured" as success. -func loadSecret(store secrets.Store, context, key string) (string, error) { +// LoadSecret fetches a named secret for the given context from the keyring. +// Returns ("", nil) when the secret is absent (ErrNotFound); a real keyring +// access failure surfaces as CodeLocalKeychainDenied. Used by buildClient +// to assemble SDK auth options and by `auth token` to expose the raw +// credential for shell scripting. +func LoadSecret(store secrets.Store, context, key string) (string, error) { v, err := store.Get(context, key) if errors.Is(err, secrets.ErrNotFound) { return "", nil diff --git a/cli/internal/cmdutil/host.go b/cli/internal/cmdutil/host.go index dd6f0f5f..9576445e 100644 --- a/cli/internal/cmdutil/host.go +++ b/cli/internal/cmdutil/host.go @@ -21,19 +21,31 @@ func NormalizeHost(host string) (string, error) { if host == "" { return "", NewError(CodeInputInvalidArgument, "--host must not be empty") } - u, err := url.Parse(host) + if err := ValidateHTTPURL("--host", host); err != nil { + return "", err + } + return host, nil +} + +// ValidateHTTPURL applies the same http/https URL rules NormalizeHost uses, +// but parameterized by flagLabel so error messages name the caller's flag +// (e.g. "--host", "--from-url"). Returns CodeInputInvalidArgument on any +// failure. Empty `value` is not pre-checked here — callers that distinguish +// "missing" from "malformed" should test for empty before calling. +func ValidateHTTPURL(flagLabel, value string) error { + u, err := url.Parse(value) if err != nil { - return "", NewError(CodeInputInvalidArgument, fmt.Sprintf("--host %q is not a valid URL: %v", host, err)) + return NewError(CodeInputInvalidArgument, fmt.Sprintf("%s %q is not a valid URL: %v", flagLabel, value, err)) } if u.Scheme != "http" && u.Scheme != "https" { - return "", &Error{ + return &Error{ Code: CodeInputInvalidArgument, - Message: fmt.Sprintf("--host scheme must be http or https, got %q", u.Scheme), + Message: fmt.Sprintf("%s scheme must be http or https, got %q", flagLabel, u.Scheme), Hint: "example: https://kb.example.com", } } if u.Host == "" { - return "", NewError(CodeInputInvalidArgument, fmt.Sprintf("--host %q is missing the host portion", host)) + return NewError(CodeInputInvalidArgument, fmt.Sprintf("%s %q is missing the host portion", flagLabel, value)) } - return host, nil + return nil } diff --git a/cli/internal/cmdutil/jsonflags.go b/cli/internal/cmdutil/jsonflags.go new file mode 100644 index 00000000..34c93a50 --- /dev/null +++ b/cli/internal/cmdutil/jsonflags.go @@ -0,0 +1,109 @@ +package cmdutil + +import ( + "errors" + "sort" + "strings" + + "github.com/spf13/cobra" + "github.com/spf13/pflag" +) + +// JSONOptions captures the resolved --json + --jq state after CheckJSONFlags. +// A non-nil value means the user requested JSON output; Fields restricts +// data.items[*] when len(Fields) > 0; JQ is a jq expression applied to the +// final envelope JSON. +type JSONOptions struct { + Fields []string + JQ string +} + +// Enabled reports whether the caller asked for JSON output. Convenience +// shorthand for `opts != nil`. +func (o *JSONOptions) Enabled() bool { return o != nil } + +// jsonNoOptSentinel marks a bare `--json` (no comma-separated values +// after it). pflag's NoOptDefVal mechanism stores this sentinel into the +// slice; CheckJSONFlags then maps it to "no field filter" (full envelope). +// +// This is a documented divergence from gh CLI, where bare `--json` errors +// with a field-list discovery prompt. weknora's envelope is itself the +// machine-readable contract (carries typed error.code / _meta / risk), +// so `--json` bare always producing the full envelope keeps v0.3 caller +// scripts and the typical agent pipe-to-jq pattern working. Field +// discovery moves to per-command `--help` "JSON fields:" sections. +const jsonNoOptSentinel = "\x00json-no-value" + +// AddJSONFlags registers --json and --jq on cmd. +// +// - `--json` → full envelope (no field filter) +// - `--json id,name` → envelope with data.items[*] / data restricted +// to listed fields +// - `--jq ` → applies a jq expression after marshaling; +// requires --json to be set explicitly +// +// `fields` is the set of available fields the user may pass; rendered in +// the command's help. Pass nil to skip the help annotation (uncommon). +func AddJSONFlags(cmd *cobra.Command, fields []string) { + f := cmd.Flags() + f.StringSlice("json", nil, "Output JSON envelope; bare `--json` for full, `--json=id,name` for filtered fields") + f.Lookup("json").NoOptDefVal = jsonNoOptSentinel + f.StringP("jq", "q", "", "Filter JSON output using a jq `expression` (requires --json)") + + if len(fields) > 0 { + sorted := append([]string(nil), fields...) + sort.Strings(sorted) + // Append to Long without overwriting per-command prose. + hdr := "\n\nJSON fields available via `--json id,name,...`:\n " + + strings.Join(sorted, "\n ") + if cmd.Long != "" { + cmd.Long += hdr + } else { + cmd.Long = strings.TrimSpace(cmd.Short) + hdr + } + } +} + +// CheckJSONFlags resolves the --json + --jq state from cmd. Returns: +// - (nil, nil) neither flag set (human output mode) +// - (*JSONOptions, nil) --json set (possibly with --jq) +// - (nil, error) --jq without --json (plain error, exit 1) +// +// Bare `--json` yields Fields == nil (full envelope). Explicit field list +// yields Fields == []string{"id", "name", ...} (filter applied). +// +// gh divergence: gh errors on bare --json with a discovery prompt. weknora +// treats bare --json as "full envelope, no filter" because the envelope is +// the contract. +func CheckJSONFlags(cmd *cobra.Command) (*JSONOptions, error) { + f := cmd.Flags() + jsonFlag := f.Lookup("json") + jqFlag := f.Lookup("jq") + if jsonFlag == nil { + return nil, nil + } + if jsonFlag.Changed { + sv, ok := jsonFlag.Value.(pflag.SliceValue) + if !ok { + return nil, errors.New("internal: --json flag is not a StringSlice") + } + raw := sv.GetSlice() + opts := &JSONOptions{} + // Strip the bare-flag sentinel if present. + for _, v := range raw { + if v == jsonNoOptSentinel { + continue + } + opts.Fields = append(opts.Fields, v) + } + if jqFlag != nil { + opts.JQ = jqFlag.Value.String() + } + return opts, nil + } + if jqFlag != nil && jqFlag.Changed { + // gh parity: plain error, exit 1 (not FlagError → exit 2). + return nil, errors.New("cannot use `--jq` without specifying `--json`") + } + return nil, nil +} diff --git a/cli/internal/cmdutil/jsonflags_test.go b/cli/internal/cmdutil/jsonflags_test.go new file mode 100644 index 00000000..ef618b58 --- /dev/null +++ b/cli/internal/cmdutil/jsonflags_test.go @@ -0,0 +1,190 @@ +package cmdutil_test + +import ( + "bytes" + "errors" + "strings" + "testing" + + "github.com/spf13/cobra" + + "github.com/Tencent/WeKnora/cli/internal/cmdutil" +) + +var testFields = []string{"id", "name", "kb_id", "updated_at"} + +func newTestCmd(t *testing.T, captured **cmdutil.JSONOptions) *cobra.Command { + t.Helper() + cmd := &cobra.Command{ + Use: "test", + SilenceErrors: true, + SilenceUsage: true, + RunE: func(c *cobra.Command, args []string) error { + opts, err := cmdutil.CheckJSONFlags(c) + if err != nil { + return err + } + *captured = opts + return nil + }, + } + cmdutil.AddJSONFlags(cmd, testFields) + return cmd +} + +func TestAddJSONFlags_BareYieldsFullEnvelopeOpts(t *testing.T) { + // `--json` bare → Enabled() with empty Fields → caller emits full envelope. + var captured *cmdutil.JSONOptions + cmd := newTestCmd(t, &captured) + cmd.SetArgs([]string{"--json"}) + cmd.SetOut(&bytes.Buffer{}) + cmd.SetErr(&bytes.Buffer{}) + + if err := cmd.Execute(); err != nil { + t.Fatalf("Execute() err = %v", err) + } + if !captured.Enabled() { + t.Fatalf("expected Enabled, got nil") + } + if len(captured.Fields) != 0 { + t.Errorf("bare --json must produce empty Fields, got %v", captured.Fields) + } +} + +func TestAddJSONFlags_FieldsFlagParsing(t *testing.T) { + // NoOptDefVal sentinel means the `=` form is required for value passing. + // Space form `--json id,name` parses as bare + positional, which is + // documented divergence from gh CLI to keep bare-envelope semantics. + cases := []struct { + args []string + want []string + }{ + {[]string{"--json=id,name"}, []string{"id", "name"}}, + {[]string{"--json=id,name,kb_id"}, []string{"id", "name", "kb_id"}}, + {[]string{"--json=id"}, []string{"id"}}, + } + for _, tc := range cases { + t.Run(strings.Join(tc.args, " "), func(t *testing.T) { + var captured *cmdutil.JSONOptions + cmd := newTestCmd(t, &captured) + cmd.SetArgs(tc.args) + cmd.SetOut(&bytes.Buffer{}) + cmd.SetErr(&bytes.Buffer{}) + + if err := cmd.Execute(); err != nil { + t.Fatalf("Execute() err = %v", err) + } + if captured == nil { + t.Fatalf("expected JSONOptions captured, got nil") + } + if !equalSlice(captured.Fields, tc.want) { + t.Errorf("Fields = %v, want %v", captured.Fields, tc.want) + } + if captured.JQ != "" { + t.Errorf("JQ should be empty, got %q", captured.JQ) + } + }) + } +} + +func TestAddJSONFlags_NoFlagsSet(t *testing.T) { + var captured *cmdutil.JSONOptions + cmd := newTestCmd(t, &captured) + cmd.SetArgs([]string{}) + cmd.SetOut(&bytes.Buffer{}) + cmd.SetErr(&bytes.Buffer{}) + + if err := cmd.Execute(); err != nil { + t.Fatalf("Execute() err = %v", err) + } + if captured != nil { + t.Errorf("expected nil JSONOptions for human mode, got %+v", captured) + } +} + +func TestAddJSONFlags_JQWithoutJSON(t *testing.T) { + var captured *cmdutil.JSONOptions + cmd := newTestCmd(t, &captured) + cmd.SetArgs([]string{"--jq", ".data.items[]"}) + cmd.SetOut(&bytes.Buffer{}) + cmd.SetErr(&bytes.Buffer{}) + + err := cmd.Execute() + if err == nil { + t.Fatalf("expected mutual-dep error, got nil") + } + want := "cannot use `--jq` without specifying `--json`" + if err.Error() != want { + t.Errorf("wrong message.\nwant: %q\ngot: %q", want, err.Error()) + } + // Must NOT be a FlagError — gh emits this as a plain error so exit + // code stays 1, not 2. + var fe *cmdutil.FlagError + if errors.As(err, &fe) { + t.Errorf("error should not be FlagError; gh treats this as exit 1") + } +} + +func TestAddJSONFlags_JQWithJSON(t *testing.T) { + var captured *cmdutil.JSONOptions + cmd := newTestCmd(t, &captured) + cmd.SetArgs([]string{"--json=id,name", "--jq", ".data.items[0].id"}) + cmd.SetOut(&bytes.Buffer{}) + cmd.SetErr(&bytes.Buffer{}) + + if err := cmd.Execute(); err != nil { + t.Fatalf("Execute() err = %v", err) + } + if captured == nil { + t.Fatalf("expected JSONOptions, got nil") + } + if !equalSlice(captured.Fields, []string{"id", "name"}) { + t.Errorf("Fields = %v, want [id name]", captured.Fields) + } + if captured.JQ != ".data.items[0].id" { + t.Errorf("JQ = %q, want %q", captured.JQ, ".data.items[0].id") + } +} + +func TestAddJSONFlags_JQShortFlag(t *testing.T) { + // gh uses -q as shorthand for --jq. + var captured *cmdutil.JSONOptions + cmd := newTestCmd(t, &captured) + cmd.SetArgs([]string{"--json=id", "-q", ".data"}) + cmd.SetOut(&bytes.Buffer{}) + cmd.SetErr(&bytes.Buffer{}) + + if err := cmd.Execute(); err != nil { + t.Fatalf("Execute() err = %v", err) + } + if captured == nil || captured.JQ != ".data" { + t.Errorf("expected JQ=.data, got %+v", captured) + } +} + +func TestAddJSONFlags_HelpListsFields(t *testing.T) { + cmd := &cobra.Command{Use: "test", Short: "A test command"} + cmdutil.AddJSONFlags(cmd, []string{"name", "id", "updated_at"}) + if !strings.Contains(cmd.Long, "JSON fields available") { + t.Errorf("expected help to include 'JSON fields available'; got Long=%q", cmd.Long) + } + // Fields should appear alphabetically sorted. + idAt := strings.Index(cmd.Long, "id") + nameAt := strings.Index(cmd.Long, "name") + updatedAt := strings.Index(cmd.Long, "updated_at") + if !(idAt < nameAt && nameAt < updatedAt) { + t.Errorf("fields not sorted in Long: idAt=%d nameAt=%d updatedAt=%d", idAt, nameAt, updatedAt) + } +} + +func equalSlice(a, b []string) bool { + if len(a) != len(b) { + return false + } + for i := range a { + if a[i] != b[i] { + return false + } + } + return true +} diff --git a/cli/internal/format/filter.go b/cli/internal/format/filter.go new file mode 100644 index 00000000..78bcca3a --- /dev/null +++ b/cli/internal/format/filter.go @@ -0,0 +1,202 @@ +package format + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + + "github.com/itchyny/gojq" +) + +// WriteEnvelopeFiltered serializes env to w, optionally restricting +// data.items[*] (for list envelopes) or data (for single-resource envelopes) +// to the named fields, then applying a jq expression on the result. +// +// - len(fields) == 0 → no field filter (full envelope) +// - jqExpr == "" → no jq filter (just write the envelope) +// +// The envelope structure (ok / data / error / _meta / risk / dry_run / _notice) +// is preserved across field filtering — only Data is rewritten. jq operates +// on the entire envelope JSON so users can `--jq '.data.items[].id'`. +func WriteEnvelopeFiltered(w io.Writer, env Envelope, fields []string, jqExpr string) error { + raw, err := marshalEnvelope(env) + if err != nil { + return err + } + if len(fields) > 0 { + raw, err = applyFieldFilter(raw, fields) + if err != nil { + return err + } + } + if jqExpr != "" { + return writeJQ(w, raw, jqExpr) + } + _, err = w.Write(raw) + return err +} + +// marshalEnvelope returns the canonical newline-terminated envelope JSON used +// by the non-filtered path. Identical to WriteEnvelope but as bytes. +func marshalEnvelope(env Envelope) ([]byte, error) { + var buf bytes.Buffer + enc := json.NewEncoder(&buf) + enc.SetEscapeHTML(false) + if err := enc.Encode(env); err != nil { + return nil, err + } + return buf.Bytes(), nil +} + +// applyFieldFilter rewrites envelope.data so that nested objects keep only +// the named keys. The shape rules: +// +// - data is an object with `items` (the standard list envelope shape): +// filter each items[*] to the named fields. +// - data is an object without `items` (single-resource envelope): +// filter data itself. +// - data is an array (uncommon — currently no command produces this, but +// defensive): filter each [*]. +// - data is nil / scalar: unchanged. +// +// Unknown field names are silently ignored (consistent with gh — users may +// pass an aspirational field set across heterogenous list outputs). +func applyFieldFilter(envelopeJSON []byte, fields []string) ([]byte, error) { + var raw map[string]json.RawMessage + if err := json.Unmarshal(envelopeJSON, &raw); err != nil { + return nil, fmt.Errorf("field filter: parse envelope: %w", err) + } + dataRaw, ok := raw["data"] + if !ok || len(dataRaw) == 0 || string(dataRaw) == "null" { + return envelopeJSON, nil + } + + filtered, err := filterDataPayload(dataRaw, fields) + if err != nil { + return nil, err + } + raw["data"] = filtered + + var buf bytes.Buffer + enc := json.NewEncoder(&buf) + enc.SetEscapeHTML(false) + if err := enc.Encode(raw); err != nil { + return nil, err + } + return buf.Bytes(), nil +} + +// filterDataPayload dispatches on the shape of the data JSON value. +func filterDataPayload(dataRaw json.RawMessage, fields []string) (json.RawMessage, error) { + trimmed := bytes.TrimSpace(dataRaw) + if len(trimmed) == 0 { + return dataRaw, nil + } + switch trimmed[0] { + case '{': + return filterObjectData(dataRaw, fields) + case '[': + return filterArrayItems(dataRaw, fields) + default: + // scalar (number / string / bool / null) — nothing to filter + return dataRaw, nil + } +} + +// filterObjectData filters either data.items[*] (list shape) or data (single +// resource). +func filterObjectData(dataRaw json.RawMessage, fields []string) (json.RawMessage, error) { + var obj map[string]json.RawMessage + if err := json.Unmarshal(dataRaw, &obj); err != nil { + return nil, fmt.Errorf("field filter: parse data object: %w", err) + } + if items, ok := obj["items"]; ok { + filtered, err := filterArrayItems(items, fields) + if err != nil { + return nil, err + } + obj["items"] = filtered + return json.Marshal(obj) + } + // Single-resource envelope: filter the data object itself. + return filterObjectKeys(dataRaw, fields) +} + +// filterArrayItems applies filterObjectKeys to each element of an array. +// Non-object elements (e.g. an array of strings) are passed through. +func filterArrayItems(arrayRaw json.RawMessage, fields []string) (json.RawMessage, error) { + var items []json.RawMessage + if err := json.Unmarshal(arrayRaw, &items); err != nil { + return nil, fmt.Errorf("field filter: parse data items: %w", err) + } + for i, item := range items { + trimmed := bytes.TrimSpace(item) + if len(trimmed) == 0 || trimmed[0] != '{' { + continue + } + filtered, err := filterObjectKeys(item, fields) + if err != nil { + return nil, err + } + items[i] = filtered + } + return json.Marshal(items) +} + +// filterObjectKeys produces a new object containing only the listed keys +// that were present in the source. +func filterObjectKeys(objRaw json.RawMessage, fields []string) (json.RawMessage, error) { + var src map[string]json.RawMessage + if err := json.Unmarshal(objRaw, &src); err != nil { + return nil, fmt.Errorf("field filter: parse object keys: %w", err) + } + dst := make(map[string]json.RawMessage, len(fields)) + for _, k := range fields { + if v, ok := src[k]; ok { + dst[k] = v + } + } + return json.Marshal(dst) +} + +// writeJQ evaluates expr against envelopeJSON and writes each result line by +// line to w. Mirrors gh's pkg/export/filter.go semantics: results that are +// strings render without quotes; everything else uses encoding/json. +// +// Returns input.invalid_argument-shaped errors via plain errors.New + fmt; +// the caller is responsible for wrapping with cmdutil.NewError if it wants +// the typed envelope code. +func writeJQ(w io.Writer, envelopeJSON []byte, expr string) error { + query, err := gojq.Parse(expr) + if err != nil { + return fmt.Errorf("jq parse: %w", err) + } + var input any + if err := json.Unmarshal(envelopeJSON, &input); err != nil { + return fmt.Errorf("jq input parse: %w", err) + } + iter := query.Run(input) + for { + v, ok := iter.Next() + if !ok { + return nil + } + if e, ok := v.(error); ok { + return fmt.Errorf("jq eval: %w", e) + } + if s, ok := v.(string); ok { + if _, err := fmt.Fprintln(w, s); err != nil { + return err + } + continue + } + out, err := json.Marshal(v) + if err != nil { + return err + } + if _, err := w.Write(append(out, '\n')); err != nil { + return err + } + } +} diff --git a/cli/internal/format/filter_test.go b/cli/internal/format/filter_test.go new file mode 100644 index 00000000..8e31d9f9 --- /dev/null +++ b/cli/internal/format/filter_test.go @@ -0,0 +1,196 @@ +package format_test + +import ( + "bytes" + "encoding/json" + "strings" + "testing" + + "github.com/Tencent/WeKnora/cli/internal/format" +) + +func TestWriteEnvelopeFiltered_NoFilter(t *testing.T) { + env := format.Success(map[string]any{"items": []any{ + map[string]any{"id": "1", "name": "alpha"}, + }}, &format.Meta{KBID: "kb_x"}) + buf := &bytes.Buffer{} + if err := format.WriteEnvelopeFiltered(buf, env, nil, ""); err != nil { + t.Fatalf("err = %v", err) + } + var got map[string]any + if err := json.Unmarshal(buf.Bytes(), &got); err != nil { + t.Fatalf("parse: %v", err) + } + if got["ok"] != true { + t.Errorf("ok = %v, want true", got["ok"]) + } +} + +func TestWriteEnvelopeFiltered_FieldsOnListItems(t *testing.T) { + env := format.Success(map[string]any{"items": []any{ + map[string]any{"id": "1", "name": "alpha", "kb_id": "kb_x", "updated_at": "2026-01-01"}, + map[string]any{"id": "2", "name": "beta", "kb_id": "kb_x", "updated_at": "2026-01-02"}, + }}, nil) + + buf := &bytes.Buffer{} + if err := format.WriteEnvelopeFiltered(buf, env, []string{"id", "name"}, ""); err != nil { + t.Fatalf("err = %v", err) + } + + var got struct { + OK bool `json:"ok"` + Data struct { + Items []map[string]string `json:"items"` + } `json:"data"` + } + if err := json.Unmarshal(buf.Bytes(), &got); err != nil { + t.Fatalf("parse: %v\n%s", err, buf.String()) + } + if len(got.Data.Items) != 2 { + t.Fatalf("items len = %d, want 2", len(got.Data.Items)) + } + for i, item := range got.Data.Items { + if _, has := item["kb_id"]; has { + t.Errorf("item[%d] should not have kb_id: %v", i, item) + } + if _, has := item["updated_at"]; has { + t.Errorf("item[%d] should not have updated_at: %v", i, item) + } + if item["id"] == "" || item["name"] == "" { + t.Errorf("item[%d] missing required keys: %v", i, item) + } + } +} + +func TestWriteEnvelopeFiltered_FieldsOnSingleObject(t *testing.T) { + env := format.Success(map[string]any{ + "id": "kb_x", + "name": "Engineering", + "owner": "alice", + }, nil) + + buf := &bytes.Buffer{} + if err := format.WriteEnvelopeFiltered(buf, env, []string{"id", "name"}, ""); err != nil { + t.Fatalf("err = %v", err) + } + + var got struct { + Data map[string]string `json:"data"` + } + if err := json.Unmarshal(buf.Bytes(), &got); err != nil { + t.Fatalf("parse: %v\n%s", err, buf.String()) + } + if _, has := got.Data["owner"]; has { + t.Errorf("should not have owner: %v", got.Data) + } + if got.Data["id"] != "kb_x" || got.Data["name"] != "Engineering" { + t.Errorf("missing kept fields: %v", got.Data) + } +} + +func TestWriteEnvelopeFiltered_UnknownFieldSilent(t *testing.T) { + env := format.Success(map[string]any{"id": "1"}, nil) + buf := &bytes.Buffer{} + if err := format.WriteEnvelopeFiltered(buf, env, []string{"id", "nonexistent"}, ""); err != nil { + t.Fatalf("err = %v", err) + } + var got struct { + Data map[string]string `json:"data"` + } + if err := json.Unmarshal(buf.Bytes(), &got); err != nil { + t.Fatalf("parse: %v", err) + } + if got.Data["id"] != "1" { + t.Errorf("id missing: %v", got.Data) + } + if _, has := got.Data["nonexistent"]; has { + t.Errorf("nonexistent should be silently dropped: %v", got.Data) + } +} + +func TestWriteEnvelopeFiltered_PreservesEnvelopeFields(t *testing.T) { + // Even with field filter, meta/risk/dry_run/error must be preserved. + env := format.Success(map[string]any{"items": []any{ + map[string]any{"id": "1", "name": "x", "kb_id": "kb"}, + }}, &format.Meta{KBID: "kb_x", RequestID: "req_123"}) + + buf := &bytes.Buffer{} + if err := format.WriteEnvelopeFiltered(buf, env, []string{"id"}, ""); err != nil { + t.Fatalf("err = %v", err) + } + var got struct { + OK bool `json:"ok"` + Meta *format.Meta `json:"_meta"` + Data struct { + Items []map[string]any `json:"items"` + } `json:"data"` + DryRun bool `json:"dry_run"` + } + if err := json.Unmarshal(buf.Bytes(), &got); err != nil { + t.Fatalf("parse: %v\n%s", err, buf.String()) + } + if got.Meta == nil || got.Meta.RequestID != "req_123" { + t.Errorf("_meta lost or mangled: %+v", got.Meta) + } +} + +func TestWriteEnvelopeFiltered_JQOnly(t *testing.T) { + env := format.Success(map[string]any{"items": []any{ + map[string]any{"id": "1", "name": "alpha"}, + map[string]any{"id": "2", "name": "beta"}, + }}, nil) + + buf := &bytes.Buffer{} + if err := format.WriteEnvelopeFiltered(buf, env, nil, ".data.items[].id"); err != nil { + t.Fatalf("err = %v", err) + } + // gh CLI parity: string results render without JSON quotes + // (see https://github.com/cli/cli/blob/trunk/pkg/export/filter.go). + lines := strings.Split(strings.TrimRight(buf.String(), "\n"), "\n") + if len(lines) != 2 { + t.Fatalf("expected 2 lines, got %d: %q", len(lines), buf.String()) + } + if lines[0] != "1" || lines[1] != "2" { + t.Errorf("wrong output: %q", buf.String()) + } +} + +func TestWriteEnvelopeFiltered_FieldsAndJQ(t *testing.T) { + env := format.Success(map[string]any{"items": []any{ + map[string]any{"id": "1", "name": "alpha", "kb_id": "kb"}, + map[string]any{"id": "2", "name": "beta", "kb_id": "kb"}, + }}, nil) + + buf := &bytes.Buffer{} + if err := format.WriteEnvelopeFiltered(buf, env, []string{"id", "name"}, ".data.items | length"); err != nil { + t.Fatalf("err = %v", err) + } + out := strings.TrimSpace(buf.String()) + if out != "2" { + t.Errorf("expected '2', got %q", out) + } +} + +func TestWriteEnvelopeFiltered_JQParseError(t *testing.T) { + env := format.Success(map[string]any{"x": 1}, nil) + buf := &bytes.Buffer{} + err := format.WriteEnvelopeFiltered(buf, env, nil, ".[invalid jq") + if err == nil { + t.Fatal("expected parse error, got nil") + } + if !strings.Contains(err.Error(), "jq parse") { + t.Errorf("expected 'jq parse' in error, got %q", err.Error()) + } +} + +func TestWriteEnvelopeFiltered_ScalarDataPassThrough(t *testing.T) { + // Defensive: scalar data should not crash field filter. + env := format.Success("just a string", nil) + buf := &bytes.Buffer{} + if err := format.WriteEnvelopeFiltered(buf, env, []string{"id"}, ""); err != nil { + t.Fatalf("err = %v", err) + } + if !strings.Contains(buf.String(), `"just a string"`) { + t.Errorf("scalar data lost: %s", buf.String()) + } +}