From 6d8c8650cdbd4af1b87aaf183589e9362aa65612 Mon Sep 17 00:00:00 2001 From: nullkey Date: Thu, 28 May 2026 04:28:48 +0800 Subject: [PATCH] feat(cli): --dry-run + risk metadata + validation parity on 19 mutations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two intertwined agent safety nets that share the same files: 1. --dry-run flag for offline preview of mutation commands 2. Risk: metadata + SetRisk helper for destructive command surfaces Coverage (19 mutation commands with --dry-run): kb.create/edit/delete agent.create/edit/delete doc.create/upload/fetch/delete doc.delete_all (special variant) session.delete chunk.delete profile.add/remove auth.refresh/logout link unlink api.{post,put,patch,delete} (api.get + --dry-run rejected, exit 2) Envelope additions (omitempty in non-dry-run paths): meta.dry_run: bool true when --dry-run was used meta.plan: map {action, args} per the per-command taxonomy Risk: metadata -------------- cmdutil.SetRisk(cmd, action) stamps cobra.Annotations with risk.level=destructive + risk.action= on the 9 destructive commands. The SetAgentHelp wrapper prepends a "Risk: (destructive)" line in the default text help path so agents see a clear warning before parsing Usage. WEKNORA_AGENT_HELP=1 JSON path stays unchanged — structured agent-help already carries warnings[]. Validation parity with the live path ------------------------------------ Every pure-local validation (flag presence, mutual exclusion, enum bounds, URL/regex format, ResolveKBLocal for KB resolution that does not require an SDK call) runs BEFORE the dry-run gate. This matches the industry-standard "preview shows what live would do" contract: --dry-run accepts exactly the same invocations the live path accepts and rejects exactly the same invocations the live path rejects, modulo the side-effecting work itself. The side-effecting work (SDK calls, file writes, keyring writes, server- side name → id resolution) is what --dry-run actually gates. Each mutation file pairs its RunE validation block with a regression test under *_dry_run_test.go / dryrun_validation_test.go so future refactors don't reintroduce the gap. Helper surface -------------- - HandleDryRun(cmd, dryRun, plan) extracts the early-return so the 19 RunE call sites stay 3 lines each. - EmitDryRun routes through FormatOptions.Emit, inheriting _notice / TTY indent / --jq filtering for free. - ResolveKBLocal mirrors ResolveKB but never calls the SDK; dry-run paths use it so the plan reports the raw --kb value (UUID or name) without a name → id lookup. Streaming commands (chat, session ask, session continue-stream) are deliberately excluded: a buffered plan makes no sense for an event stream. Lock semantics in the dry-run path: - destructive + --dry-run: exit 0, no exit-10 confirmation prompt - --dry-run + -y: byte-identical envelope to --dry-run alone - --dry-run + --jq: filter applies to the preview envelope normally --- cli/cmd/agent/create.go | 12 ++ cli/cmd/agent/delete.go | 14 +- cli/cmd/agent/edit.go | 62 +++++- cli/cmd/agent/edit_dry_run_test.go | 46 +++++ cli/cmd/api/api.go | 53 +++++ cli/cmd/api/api_dry_run_test.go | 127 ++++++++++++ cli/cmd/api/api_test.go | 11 +- cli/cmd/auth/dryrun_validation_test.go | 124 ++++++++++++ cli/cmd/auth/logout.go | 42 +++- cli/cmd/auth/refresh.go | 45 ++++- cli/cmd/chunk/delete.go | 15 +- cli/cmd/doc/create.go | 26 ++- cli/cmd/doc/delete.go | 47 +++-- cli/cmd/doc/dryrun_validation_test.go | 142 ++++++++++++++ cli/cmd/doc/fetch.go | 26 ++- cli/cmd/doc/upload.go | 49 ++++- cli/cmd/kb/create.go | 22 +++ cli/cmd/kb/create_dry_run_test.go | 99 ++++++++++ cli/cmd/kb/delete.go | 16 +- cli/cmd/kb/delete_dry_run_test.go | 61 ++++++ cli/cmd/kb/edit.go | 33 +++- cli/cmd/kb/edit_dry_run_test.go | 30 +++ cli/cmd/link/dryrun_validation_test.go | 106 ++++++++++ cli/cmd/link/link.go | 22 ++- cli/cmd/link/unlink.go | 29 ++- cli/cmd/profile/add.go | 48 ++++- cli/cmd/profile/dryrun_validation_test.go | 105 ++++++++++ cli/cmd/profile/remove.go | 27 ++- cli/cmd/session/delete.go | 16 +- cli/internal/cmdutil/agenthelp.go | 11 +- cli/internal/cmdutil/dryrun.go | 128 +++++++++++++ cli/internal/cmdutil/dryrun_test.go | 224 ++++++++++++++++++++++ cli/internal/cmdutil/factory.go | 27 +++ cli/internal/cmdutil/risk.go | 46 +++++ cli/internal/cmdutil/risk_help_test.go | 75 ++++++++ cli/internal/cmdutil/risk_test.go | 54 ++++++ cli/internal/output/envelope.go | 4 + 37 files changed, 1974 insertions(+), 50 deletions(-) create mode 100644 cli/cmd/agent/edit_dry_run_test.go create mode 100644 cli/cmd/api/api_dry_run_test.go create mode 100644 cli/cmd/auth/dryrun_validation_test.go create mode 100644 cli/cmd/doc/dryrun_validation_test.go create mode 100644 cli/cmd/kb/create_dry_run_test.go create mode 100644 cli/cmd/kb/delete_dry_run_test.go create mode 100644 cli/cmd/kb/edit_dry_run_test.go create mode 100644 cli/cmd/link/dryrun_validation_test.go create mode 100644 cli/cmd/profile/dryrun_validation_test.go create mode 100644 cli/internal/cmdutil/dryrun.go create mode 100644 cli/internal/cmdutil/dryrun_test.go create mode 100644 cli/internal/cmdutil/risk.go create mode 100644 cli/internal/cmdutil/risk_help_test.go create mode 100644 cli/internal/cmdutil/risk_test.go diff --git a/cli/cmd/agent/create.go b/cli/cmd/agent/create.go index 5fa669bf..d0cfdc13 100644 --- a/cli/cmd/agent/create.go +++ b/cli/cmd/agent/create.go @@ -42,6 +42,7 @@ type CreateOptions struct { ConfigFileBody io.Reader ConfigFileKind string // "yaml" or "json" GenerateSkeleton bool + DryRun bool flags createFlagSet // populated in PreRunE for *Set bits } @@ -144,6 +145,16 @@ func NewCmdCreate(f *cmdutil.Factory) *cobra.Command { return err } fopts.ResolveDefault(iostreams.IO.IsStdoutTTY()) + planArgs := map[string]any{"name": opts.Name} + if configFile != "" { + planArgs["config"] = configFile + } + if handled, err := cmdutil.HandleDryRun(cmd, opts.DryRun, cmdutil.DryRunPlan{ + Action: "agent.create", + Args: planArgs, + }); handled { + return err + } cli, err := f.Client() if err != nil { return err @@ -174,6 +185,7 @@ func NewCmdCreate(f *cmdutil.Factory) *cobra.Command { cmd.Flags().BoolVar(&opts.GenerateSkeleton, "generate-skeleton", false, "Emit blank AgentConfig YAML to stdout and exit") cmdutil.AddFormatFlag(cmd, agentViewFields...) + cmdutil.AddDryRunFlag(cmd, &opts.DryRun) return cmd } diff --git a/cli/cmd/agent/delete.go b/cli/cmd/agent/delete.go index 61d6526a..4660c804 100644 --- a/cli/cmd/agent/delete.go +++ b/cli/cmd/agent/delete.go @@ -18,6 +18,7 @@ var agentDeleteFields = []string{"id", "deleted"} type DeleteOptions struct { AgentID string Yes bool // sourced from the global -y/--yes persistent flag + DryRun bool } // DeleteService is the narrow SDK surface this command depends on. @@ -71,6 +72,14 @@ func NewCmdDelete(f *cmdutil.Factory) *cobra.Command { fopts.ResolveDefault(iostreams.IO.IsStdoutTTY()) opts.AgentID = args[0] opts.Yes, _ = cmd.Flags().GetBool("yes") + if handled, err := cmdutil.HandleDryRun(cmd, opts.DryRun, cmdutil.DryRunPlan{ + Action: "agent.delete", + Args: map[string]any{ + "agent_id": opts.AgentID, + }, + }); handled { + return err + } cli, err := f.Client() if err != nil { return err @@ -79,6 +88,8 @@ func NewCmdDelete(f *cmdutil.Factory) *cobra.Command { }, } cmdutil.AddFormatFlag(cmd, agentDeleteFields...) + cmdutil.AddDryRunFlag(cmd, &opts.DryRun) + cmdutil.SetRisk(cmd, "agent.delete") cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{ UsedFor: "permanently delete a custom agent", RequiredFlags: []string{" (positional)"}, @@ -87,7 +98,8 @@ func NewCmdDelete(f *cmdutil.Factory) *cobra.Command { "weknora agent delete ag_abc -y --format json", }, Warnings: []string{ - "agent delete removes the configured agent and its workflow. Never auto-add -y.", + "Requires explicit user approval (exit 10 / input.confirmation_required); never auto-add -y.", + "agent delete is irreversible; loses the agent + its KB binding + custom skills.", }, }) return cmd diff --git a/cli/cmd/agent/edit.go b/cli/cmd/agent/edit.go index 08e0b5fb..346ec835 100644 --- a/cli/cmd/agent/edit.go +++ b/cli/cmd/agent/edit.go @@ -42,6 +42,7 @@ type EditOptions struct { KBSelectionMode string ConfigFileBody io.Reader ConfigFileKind string // "yaml" or "json" + DryRun bool flags editFlagSet } @@ -149,6 +150,62 @@ func NewCmdEdit(f *cmdutil.Factory) *cobra.Command { return err } fopts.ResolveDefault(iostreams.IO.IsStdoutTTY()) + // Validate "at least one update flag" before the dry-run gate so + // --dry-run rejects identically to the live path. Same typed + // Error as runEdit (kept there for direct-call callers). + if !editHasAnyFlag(opts) { + return &cmdutil.Error{ + Code: cmdutil.CodeInputInvalidArgument, + Message: "agent edit requires at least one flag", + Hint: "pass at least one update flag (e.g., --name, --add-kb, --description) or --config-file", + } + } + if opts.DryRun { + planArgs := map[string]any{"agent_id": opts.AgentID} + if opts.flags.nameSet { + planArgs["name"] = opts.Name + } + if opts.flags.descriptionSet { + planArgs["description"] = opts.Description + } + if opts.flags.modelSet { + planArgs["model"] = opts.Model + } + if opts.flags.agentModeSet { + planArgs["agent_mode"] = opts.AgentMode + } + if opts.flags.rerankModelSet { + planArgs["rerank_model"] = opts.RerankModel + } + if opts.flags.temperatureSet { + planArgs["temperature"] = opts.Temperature + } + if opts.flags.addKBsSet { + planArgs["add_kb"] = opts.AddKBs + } + if opts.flags.removeKBsSet { + planArgs["remove_kb"] = opts.RemoveKBs + } + if opts.flags.kbSelectionModeSet { + planArgs["kb_selection_mode"] = opts.KBSelectionMode + } + if opts.flags.configFileSet { + planArgs["config_file"] = configFile + } + if opts.flags.systemPromptSet { + if systemPromptFile != "" { + planArgs["system_prompt_file"] = systemPromptFile + } else { + planArgs["system_prompt"] = opts.SystemPrompt + } + } + if handled, err := cmdutil.HandleDryRun(cmd, true, cmdutil.DryRunPlan{ + Action: "agent.edit", + Args: planArgs, + }); handled { + return err + } + } yes, _ := cmd.Flags().GetBool("yes") // Build the retry command from the flags the user actually passed. retryCmd := buildAgentEditRetryCmd(cmd, opts.AgentID) @@ -181,6 +238,8 @@ func NewCmdEdit(f *cmdutil.Factory) *cobra.Command { cmd.Flags().StringVar(&configFile, "config-file", "", "Full AgentConfig YAML or JSON (REPLACES current config baseline; surgical flags then apply on top)") cmdutil.AddFormatFlag(cmd, agentViewFields...) + cmdutil.AddDryRunFlag(cmd, &opts.DryRun) + cmdutil.SetRisk(cmd, "agent.edit") cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{ UsedFor: "surgically edit a custom agent's configuration", RequiredFlags: []string{" (positional)", "at least one edit flag (--name, --add-kb, etc.)"}, @@ -190,7 +249,8 @@ func NewCmdEdit(f *cmdutil.Factory) *cobra.Command { "weknora agent edit ag_abc --config-file ./tuned.yaml", }, Warnings: []string{ - "agent edit can change tool allowlist / KB scope. Surface the exit-10 prompt to the user — only proceed after explicit approval.", + "Requires explicit user approval (exit 10 / input.confirmation_required); never auto-add -y.", + "agent edit overwrites config; fetch-then-update protects unmentioned fields, but bad input still saved.", }, }) return cmd diff --git a/cli/cmd/agent/edit_dry_run_test.go b/cli/cmd/agent/edit_dry_run_test.go new file mode 100644 index 00000000..216ec339 --- /dev/null +++ b/cli/cmd/agent/edit_dry_run_test.go @@ -0,0 +1,46 @@ +package agentcmd + +import ( + "errors" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/Tencent/WeKnora/cli/internal/cmdutil" + "github.com/Tencent/WeKnora/cli/internal/iostreams" + "github.com/Tencent/WeKnora/cli/internal/prompt" + sdk "github.com/Tencent/WeKnora/client" +) + +// agentDryRunFactory builds a Factory whose Client closure panics if invoked — +// dry-run must early-exit before any SDK call. +func agentDryRunFactory(t *testing.T) *cmdutil.Factory { + t.Helper() + return &cmdutil.Factory{ + Client: func() (*sdk.Client, error) { + t.Fatal("dry-run path must not call Factory.Client(); SDK side effect leaked") + return nil, nil + }, + Prompter: func() prompt.Prompter { + t.Fatal("dry-run path must not call Factory.Prompter(); confirm-prompt side effect leaked") + return nil + }, + } +} + +// TestAgentEdit_DryRun_RejectsNoFlag: --dry-run must reject the same +// "no update flag supplied" invocation the live path rejects. Before the +// fix the editHasAnyFlag check lived in runEdit() (live-only), reached only +// after HandleDryRun early-exited. +func TestAgentEdit_DryRun_RejectsNoFlag(t *testing.T) { + iostreams.SetForTest(t) + f := agentDryRunFactory(t) + root := withRootHarnessAgent(NewCmdEdit(f), "ag_abc", "--dry-run", "--format", "json") + err := root.Execute() + require.Error(t, err, "dry-run must reject identically to live path") + + var typed *cmdutil.Error + require.True(t, errors.As(err, &typed), "expected *cmdutil.Error, got %T %v", err, err) + assert.Equal(t, cmdutil.CodeInputInvalidArgument, typed.Code) +} diff --git a/cli/cmd/api/api.go b/cli/cmd/api/api.go index 8fc669f4..f22535d3 100644 --- a/cli/cmd/api/api.go +++ b/cli/cmd/api/api.go @@ -33,6 +33,7 @@ type Options struct { Method string Input string // --input: file path, "-" for stdin Yes bool + DryRun bool StdinReader io.Reader // overridden by tests; defaults to iostreams.IO.In } @@ -72,6 +73,43 @@ Examples: return err } fopts.ResolveDefault(iostreams.IO.IsStdoutTTY()) + if opts.DryRun { + // --dry-run on the raw escape-hatch is only meaningful when a + // would-be mutation exists to preview. GET (default or explicit) + // is read-only with no side effect, so previewing it is a + // likely user error — signal it via FlagError exit 2 with the + // concrete repair. Use resolveMethod so --input auto-promotes + // GET → POST identically to the live path. + method := resolveMethod(opts) + if method == http.MethodGet { + return cmdutil.NewFlagError(fmt.Errorf( + "--dry-run requires explicit -X POST/PUT/PATCH/DELETE; default GET is read-only with no side effect to preview")) + } + var body any + if opts.Input != "" { + contents, err := readInput(opts) + if err != nil { + return err + } + // Best-effort JSON decode so the plan body surfaces a + // structured object (agents grep meta.plan.body for shape); + // fall back to raw string when the payload isn't JSON. + var parsed any + if json.Unmarshal(contents, &parsed) == nil { + body = parsed + } else { + body = string(contents) + } + } + if handled, err := cmdutil.HandleDryRun(c, true, cmdutil.DryRunPlan{ + Action: "api." + strings.ToLower(method), + Method: method, + Path: args[0], + Body: body, + }); handled { + return err + } + } method := resolveMethod(opts) // Escape-hatch DELETE through `weknora api` is just as destructive // as `weknora kb delete` - exit-10 protocol must apply (cli/README.md). @@ -92,6 +130,21 @@ Examples: cmd.Flags().StringVar(&opts.Input, "input", "", "Read request body from file (use `-` for stdin)") cmd.Flags().Bool("paginate", false, "Follow offset-based pagination (?page=N&page_size=M), merging all pages into a single {data, total} JSON response.") cmdutil.AddFormatFlag(cmd, apiFields...) + cmdutil.AddDryRunFlag(cmd, &opts.DryRun) + cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{ + UsedFor: "raw HTTP passthrough to weknora-server API endpoints when typed subcommands are insufficient", + RequiredFlags: []string{"path (positional)"}, + Examples: []string{ + "weknora api /api/v1/knowledge-bases", + "weknora api -X DELETE /api/v1/knowledge-bases/kb_x -y", + "echo '{\"name\":\"foo\"}' | weknora api -X POST /api/v1/knowledge-bases --input -", + }, + Output: "raw server response body or envelope on error", + Warnings: []string{ + "Note: -X DELETE/PUT/PATCH on existing resources may trigger exit 10 / input.confirmation_required at runtime; -X GET/POST are unguarded.", + "Raw HTTP passthrough; agents should prefer typed subcommands (kb/doc/session/...) when available.", + }, + }) return cmd } diff --git a/cli/cmd/api/api_dry_run_test.go b/cli/cmd/api/api_dry_run_test.go new file mode 100644 index 00000000..a8e84397 --- /dev/null +++ b/cli/cmd/api/api_dry_run_test.go @@ -0,0 +1,127 @@ +package api + +import ( + "encoding/json" + "errors" + "strings" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/Tencent/WeKnora/cli/internal/cmdutil" + "github.com/Tencent/WeKnora/cli/internal/iostreams" + "github.com/Tencent/WeKnora/cli/internal/prompt" + sdk "github.com/Tencent/WeKnora/client" +) + +// apiDryRunFactory builds a Factory whose Client closure panics if invoked — +// dry-run must early-exit before any SDK call. +func apiDryRunFactory(t *testing.T) *cmdutil.Factory { + t.Helper() + return &cmdutil.Factory{ + Client: func() (*sdk.Client, error) { + t.Fatal("dry-run path must not call Factory.Client(); SDK side effect leaked") + return nil, nil + }, + Prompter: func() prompt.Prompter { + t.Fatal("dry-run path must not call Factory.Prompter(); confirm-prompt side effect leaked") + return nil + }, + } +} + +// TestApi_DryRunWithGet_FlagError: default-method GET + --dry-run must return +// FlagError (exit 2). The only meaningful target for --dry-run on `api` is a +// mutation method; allowing GET to silently succeed would let agents waste a +// round-trip previewing a no-op. +func TestApi_DryRunWithGet_FlagError(t *testing.T) { + iostreams.SetForTest(t) + root := withRootHarness(NewCmd(apiDryRunFactory(t)), + "/api/v1/knowledge-bases", "--dry-run") + err := root.Execute() + require.Error(t, err, "GET + --dry-run must error") + + var fe *cmdutil.FlagError + require.True(t, errors.As(err, &fe), "expected *cmdutil.FlagError, got %T %v", err, err) + assert.Equal(t, 2, cmdutil.ExitCode(err), "FlagError must map to exit 2") + assert.Contains(t, err.Error(), "explicit -X POST/PUT/PATCH/DELETE", + "error message must point users to the concrete repair") +} + +// TestApi_DryRunWithExplicitGet_FlagError: explicit `-X GET` + --dry-run is +// also rejected. The reject condition is "method is GET", not "method flag is +// unset"; passing -X GET explicitly must produce the same error so users +// can't bypass the guard by being verbose. +func TestApi_DryRunWithExplicitGet_FlagError(t *testing.T) { + iostreams.SetForTest(t) + root := withRootHarness(NewCmd(apiDryRunFactory(t)), + "/api/v1/knowledge-bases", "-X", "GET", "--dry-run") + err := root.Execute() + require.Error(t, err, "explicit -X GET + --dry-run must error") + + var fe *cmdutil.FlagError + require.True(t, errors.As(err, &fe), "expected *cmdutil.FlagError, got %T %v", err, err) + assert.Equal(t, 2, cmdutil.ExitCode(err)) +} + +// TestApi_DryRunWithInputAutoPromotes_EmitsPlan: --input on its own (no +// explicit -X) must auto-promote GET → POST in the dry-run path too, +// matching the live behavior in resolveMethod. Before the fix the dry-run +// branch built `method` directly from `strings.ToUpper(opts.Method)`, which +// is empty when -X is unset, then defaulted to GET — so --input was ignored +// at preview time, producing the misleading "GET is read-only" error. +func TestApi_DryRunWithInputAutoPromotes_EmitsPlan(t *testing.T) { + out, _ := iostreams.SetForTest(t) + iostreams.IO.In = strings.NewReader(`{}`) + root := withRootHarness(NewCmd(apiDryRunFactory(t)), + "/api/v1/knowledge-bases", "--input", "-", "--dry-run", "--format", "json") + require.NoError(t, root.Execute(), "--input + --dry-run must succeed (POST auto-promotion)") + + var env struct { + OK bool `json:"ok"` + Meta struct { + DryRun bool `json:"dry_run"` + Plan map[string]any `json:"plan"` + } `json:"meta"` + } + require.NoError(t, json.Unmarshal(out.Bytes(), &env), "expected valid JSON envelope, got %q", out.String()) + assert.True(t, env.OK) + assert.True(t, env.Meta.DryRun) + assert.Equal(t, "api.post", env.Meta.Plan["action"], "plan.action must reflect auto-promoted POST") + assert.Equal(t, "POST", env.Meta.Plan["method"]) +} + +// TestApi_DryRunWithPost_EmitsPlan: POST + --dry-run + --input - must emit +// the standard envelope with action=api.post, method/path echoed, and the +// stdin body parsed as JSON under plan.body. No SDK call expected (factory +// would panic if Client() were touched). +func TestApi_DryRunWithPost_EmitsPlan(t *testing.T) { + out, _ := iostreams.SetForTest(t) + cmd := NewCmd(apiDryRunFactory(t)) + // StdinReader is on Options; set it via the recovered options binding by + // running through the root harness with --input - and trusting iostreams.IO.In. + // Simplest path: write to IO.In directly via SetForTest's reader swap. + iostreams.IO.In = strings.NewReader(`{"name":"foo"}`) + root := withRootHarness(cmd, + "/api/v1/knowledge-bases", "-X", "POST", "--input", "-", "--dry-run", "--format", "json") + require.NoError(t, root.Execute(), "POST + --dry-run must succeed (exit 0) without SDK") + + var env struct { + OK bool `json:"ok"` + Meta struct { + DryRun bool `json:"dry_run"` + Plan map[string]any `json:"plan"` + } `json:"meta"` + } + require.NoError(t, json.Unmarshal(out.Bytes(), &env), "expected valid JSON envelope, got %q", out.String()) + assert.True(t, env.OK) + assert.True(t, env.Meta.DryRun) + assert.Equal(t, "api.post", env.Meta.Plan["action"], "plan.action must lowercase the method") + assert.Equal(t, "POST", env.Meta.Plan["method"], "plan.method must be uppercase") + assert.Equal(t, "/api/v1/knowledge-bases", env.Meta.Plan["path"]) + // Body decoded as JSON object (best-effort) for downstream agent inspection. + body, ok := env.Meta.Plan["body"].(map[string]any) + require.True(t, ok, "plan.body must be a JSON object when --input is valid JSON, got %T", env.Meta.Plan["body"]) + assert.Equal(t, "foo", body["name"]) +} diff --git a/cli/cmd/api/api_test.go b/cli/cmd/api/api_test.go index 4f92f413..c7b1b7ff 100644 --- a/cli/cmd/api/api_test.go +++ b/cli/cmd/api/api_test.go @@ -239,12 +239,15 @@ func TestAPI_PathWithoutSlash(t *testing.T) { } // withRootHarness wraps `weknora api ...` under a synthetic root cmd that -// registers the global `-y/--yes` persistent flag (mirrors addGlobalFlags in -// cmd/root.go). Required because api's NewCmd doesn't register --yes itself -// - it inherits from root in production. +// registers the global persistent flags (mirrors addGlobalFlags in +// cmd/root.go). Required because api's NewCmd doesn't register --yes / +// --format / --jq itself — it inherits them from root in production. func withRootHarness(api *cobra.Command, args ...string) *cobra.Command { root := &cobra.Command{Use: "weknora"} - root.PersistentFlags().BoolP("yes", "y", false, "") + pf := root.PersistentFlags() + pf.BoolP("yes", "y", false, "") + pf.String("format", "", "") + pf.StringP("jq", "q", "", "") root.AddCommand(api) root.SetArgs(append([]string{"api"}, args...)) root.SetContext(context.Background()) diff --git a/cli/cmd/auth/dryrun_validation_test.go b/cli/cmd/auth/dryrun_validation_test.go new file mode 100644 index 00000000..1d6c226c --- /dev/null +++ b/cli/cmd/auth/dryrun_validation_test.go @@ -0,0 +1,124 @@ +// Package auth — dryrun_validation_test.go asserts that --dry-run on +// auth subcommands rejects identically to the live path. Before the +// surrounding fix, validation lived in runX() and was reached only after +// HandleDryRun short-circuited, so --dry-run accepted invocations the live +// path would reject. +package auth + +import ( + "context" + "errors" + "testing" + + "github.com/spf13/cobra" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "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/prompt" + "github.com/Tencent/WeKnora/cli/internal/secrets" + sdk "github.com/Tencent/WeKnora/client" +) + +// authDryRunFactory builds a Factory whose Client closure panics if invoked — +// dry-run must early-exit before any SDK call. Config is supplied via the cfg +// argument so each test gets isolated state. +func authDryRunFactory(t *testing.T, cfg *config.Config) *cmdutil.Factory { + t.Helper() + return &cmdutil.Factory{ + Config: func() (*config.Config, error) { return cfg, nil }, + Client: func() (*sdk.Client, error) { + t.Fatal("dry-run path must not call Factory.Client(); SDK side effect leaked") + return nil, nil + }, + Prompter: func() prompt.Prompter { + t.Fatal("dry-run path must not call Factory.Prompter(); confirm-prompt side effect leaked") + return nil + }, + Secrets: func() (secrets.Store, error) { return secrets.NewMemStore(), nil }, + } +} + +// withRootHarnessAuth wraps an auth subcommand under a synthetic root cmd +// that registers the global persistent flags. +func withRootHarnessAuth(sub *cobra.Command, args ...string) *cobra.Command { + root := &cobra.Command{Use: "weknora"} + pf := root.PersistentFlags() + pf.BoolP("yes", "y", false, "") + pf.String("format", "", "") + pf.StringP("jq", "q", "", "") + root.AddCommand(sub) + root.SetArgs(append([]string{sub.Name()}, args...)) + root.SetContext(context.Background()) + root.SilenceErrors = true + root.SilenceUsage = true + return root +} + +// TestAuthLogout_DryRun_RejectsNoProfiles: empty config → live path returns +// auth.unauthenticated; --dry-run must do the same. +func TestAuthLogout_DryRun_RejectsNoProfiles(t *testing.T) { + iostreams.SetForTest(t) + cfg := &config.Config{} + root := withRootHarnessAuth(NewCmdLogout(authDryRunFactory(t, cfg)), + "--dry-run", "--format", "json") + err := root.Execute() + require.Error(t, err, "dry-run must reject empty config") + var typed *cmdutil.Error + require.True(t, errors.As(err, &typed), "expected *cmdutil.Error, got %T %v", err, err) + assert.Equal(t, cmdutil.CodeAuthUnauthenticated, typed.Code) +} + +// TestAuthLogout_DryRun_RejectsUnknownName: --name on a profile that doesn't +// exist → live path returns local.profile_not_found; --dry-run must do the +// same. +func TestAuthLogout_DryRun_RejectsUnknownName(t *testing.T) { + iostreams.SetForTest(t) + cfg := &config.Config{ + CurrentProfile: "prod", + Profiles: map[string]config.Profile{"prod": {Host: "https://prod"}}, + } + root := withRootHarnessAuth(NewCmdLogout(authDryRunFactory(t, cfg)), + "--name", "ghost", "--dry-run", "--format", "json") + err := root.Execute() + require.Error(t, err, "dry-run must reject unknown --name") + var typed *cmdutil.Error + require.True(t, errors.As(err, &typed), "expected *cmdutil.Error, got %T %v", err, err) + assert.Equal(t, cmdutil.CodeLocalProfileNotFound, typed.Code) +} + +// TestAuthRefresh_DryRun_RejectsNoCurrentProfile: no current profile → live +// path returns auth.unauthenticated; --dry-run must do the same. +func TestAuthRefresh_DryRun_RejectsNoCurrentProfile(t *testing.T) { + iostreams.SetForTest(t) + cfg := &config.Config{} + root := withRootHarnessAuth(NewCmdRefresh(authDryRunFactory(t, cfg)), + "--dry-run", "--format", "json") + err := root.Execute() + require.Error(t, err) + var typed *cmdutil.Error + require.True(t, errors.As(err, &typed)) + assert.Equal(t, cmdutil.CodeAuthUnauthenticated, typed.Code) +} + +// TestAuthRefresh_DryRun_RejectsMissingRefreshToken: API-key-only profile → +// live path returns input.invalid_argument ("no refresh token"); --dry-run +// must do the same. +func TestAuthRefresh_DryRun_RejectsMissingRefreshToken(t *testing.T) { + iostreams.SetForTest(t) + cfg := &config.Config{ + CurrentProfile: "prod", + Profiles: map[string]config.Profile{ + "prod": {Host: "https://prod", APIKeyRef: "k"}, + }, + } + root := withRootHarnessAuth(NewCmdRefresh(authDryRunFactory(t, cfg)), + "--dry-run", "--format", "json") + err := root.Execute() + require.Error(t, err) + var typed *cmdutil.Error + require.True(t, errors.As(err, &typed)) + assert.Equal(t, cmdutil.CodeInputInvalidArgument, typed.Code) +} diff --git a/cli/cmd/auth/logout.go b/cli/cmd/auth/logout.go index a61dbc2d..a50ce63e 100644 --- a/cli/cmd/auth/logout.go +++ b/cli/cmd/auth/logout.go @@ -13,9 +13,10 @@ import ( ) type LogoutOptions struct { - Name string // --name: target a specific profile (default: current) - All bool // --all: clear every profile - Yes bool // sourced from the global -y/--yes persistent flag + Name string // --name: target a specific profile (default: current) + All bool // --all: clear every profile + Yes bool // sourced from the global -y/--yes persistent flag + DryRun bool } // authLogoutFields enumerates the fields surfaced for `--format json` discovery @@ -53,13 +54,45 @@ accepted until it expires.`, } fopts.ResolveDefault(iostreams.IO.IsStdoutTTY()) opts.Yes, _ = c.Flags().GetBool("yes") + // Pure-local validation runs before the dry-run gate so --dry-run + // rejects identically to the live path. Same typed errors as + // runLogout (kept there for direct-call callers). + cfg, cfgErr := f.Config() + if cfgErr != nil { + return cfgErr + } + if len(cfg.Profiles) == 0 { + return cmdutil.NewError(cmdutil.CodeAuthUnauthenticated, "no profiles configured; nothing to log out") + } + if opts.Name != "" { + if err := cmdutil.ValidateProfileName(opts.Name); err != nil { + return err + } + } + if _, err := pickLogoutTargets(opts, cfg); err != nil { + return err + } + if opts.DryRun { + planArgs := map[string]any{"name": opts.Name} + if opts.All { + planArgs = map[string]any{"all": true} + } + if handled, err := cmdutil.HandleDryRun(c, true, cmdutil.DryRunPlan{ + Action: "auth.logout", + Args: planArgs, + }); handled { + return err + } + } return runLogout(opts, fopts, f) }, } cmd.Flags().StringVar(&opts.Name, "name", "", "Profile to log out (defaults to the current profile)") cmd.Flags().BoolVar(&opts.All, "all", false, "Log out of every configured profile") cmdutil.AddFormatFlag(cmd, authLogoutFields...) + cmdutil.AddDryRunFlag(cmd, &opts.DryRun) cmd.MarkFlagsMutuallyExclusive("name", "all") + cmdutil.SetRisk(cmd, "auth.logout") cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{ UsedFor: "clear stored credentials for one profile (or all) and remove the profile from config", Examples: []string{ @@ -68,7 +101,8 @@ accepted until it expires.`, "weknora auth logout --all", }, Warnings: []string{ - "auth logout drops stored credentials. The user will need to re-authenticate. Confirm scope before invoking.", + "Requires explicit user approval (exit 10 / input.confirmation_required); never auto-add -y.", + "auth logout clears local credentials for this profile; server-side session continues until expiry.", }, }) return cmd diff --git a/cli/cmd/auth/refresh.go b/cli/cmd/auth/refresh.go index cbbc6adb..6e898fc2 100644 --- a/cli/cmd/auth/refresh.go +++ b/cli/cmd/auth/refresh.go @@ -12,7 +12,8 @@ import ( ) type RefreshOptions struct { - Name string // --name: target profile (defaults to current) + Name string // --name: target profile (defaults to current) + DryRun bool } // authRefreshFields enumerates the fields surfaced for `--format json` discovery @@ -53,11 +54,53 @@ refresh semantic. Rotate the key in the server UI instead.`, return err } fopts.ResolveDefault(iostreams.IO.IsStdoutTTY()) + // Pure-local validation runs before the dry-run gate so --dry-run + // rejects identically to the live path. Same typed errors as + // runRefresh (kept there for direct-call callers). + cfg, cfgErr := f.Config() + if cfgErr != nil { + return cfgErr + } + name := opts.Name + if name == "" { + name = cfg.CurrentProfile + } + if name == "" { + return cmdutil.NewError(cmdutil.CodeAuthUnauthenticated, + "no current profile configured; run `weknora auth login` to set one up") + } + prof, ok := cfg.Profiles[name] + if !ok { + return cmdutil.NewError(cmdutil.CodeLocalProfileNotFound, + fmt.Sprintf("profile not found: %s", name)) + } + if prof.Host == "" { + return cmdutil.NewError(cmdutil.CodeLocalConfigCorrupt, + fmt.Sprintf("profile %q has no host", name)) + } + if prof.RefreshRef == "" { + hint := "api-key profiles can't be refreshed - rotate the key in the server UI and run `weknora auth login --with-token`" + if prof.APIKeyRef == "" { + hint = "no refresh token stored - run `weknora auth login` to authenticate" + } + return &cmdutil.Error{ + Code: cmdutil.CodeInputInvalidArgument, + Message: fmt.Sprintf("profile %q has no refresh token", name), + Hint: hint, + } + } + if handled, err := cmdutil.HandleDryRun(c, opts.DryRun, cmdutil.DryRunPlan{ + Action: "auth.refresh", + Args: map[string]any{}, + }); handled { + return err + } return runRefresh(c.Context(), opts, fopts, f, defaultRefresher) }, } cmd.Flags().StringVar(&opts.Name, "name", "", "Profile to refresh (defaults to the current profile)") cmdutil.AddFormatFlag(cmd, authRefreshFields...) + cmdutil.AddDryRunFlag(cmd, &opts.DryRun) return cmd } diff --git a/cli/cmd/chunk/delete.go b/cli/cmd/chunk/delete.go index 0351f08d..ee2a211e 100644 --- a/cli/cmd/chunk/delete.go +++ b/cli/cmd/chunk/delete.go @@ -20,6 +20,7 @@ type DeleteOptions struct { ChunkID string // single-id path DocID string // required: SDK DeleteChunk takes both ids in the route Yes bool // sourced from the global -y/--yes persistent flag + DryRun bool } // DeleteService is the narrow SDK surface this command depends on. @@ -83,6 +84,15 @@ func NewCmdDelete(f *cmdutil.Factory) *cobra.Command { } fopts.ResolveDefault(iostreams.IO.IsStdoutTTY()) opts.Yes, _ = c.Flags().GetBool("yes") + if handled, err := cmdutil.HandleDryRun(c, opts.DryRun, cmdutil.DryRunPlan{ + Action: "chunk.delete", + Args: map[string]any{ + "chunk_ids": args, + "doc": opts.DocID, + }, + }); handled { + return err + } cli, err := f.Client() if err != nil { return err @@ -114,6 +124,8 @@ func NewCmdDelete(f *cmdutil.Factory) *cobra.Command { cmd.Flags().StringVar(&opts.DocID, "doc", "", "Parent document id (SDK knowledge_id) the chunks live under") _ = cmd.MarkFlagRequired("doc") cmdutil.AddFormatFlag(cmd, chunkDeleteFields...) + cmdutil.AddDryRunFlag(cmd, &opts.DryRun) + cmdutil.SetRisk(cmd, "chunk.delete") cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{ UsedFor: "permanently delete one or more chunks from a document", RequiredFlags: []string{"... (positional, at least one)", "--doc "}, @@ -123,7 +135,8 @@ func NewCmdDelete(f *cmdutil.Factory) *cobra.Command { "weknora chunk delete chunk_abc --doc doc_xyz -y --format json", }, Warnings: []string{ - "chunk delete removes a chunk from a doc permanently. Never auto-add -y unless the user explicitly approves the specific chunk id.", + "Requires explicit user approval (exit 10 / input.confirmation_required); never auto-add -y.", + "chunk delete is irreversible; loses the chunk + breaks RAG retrieval coherence for downstream queries.", }, }) return cmd diff --git a/cli/cmd/doc/create.go b/cli/cmd/doc/create.go index 92ce564f..aecffbc4 100644 --- a/cli/cmd/doc/create.go +++ b/cli/cmd/doc/create.go @@ -29,6 +29,7 @@ type CreateOptions struct { Name string // --name: document title TagID string // --tag-id: associate with a tag Channel string // --channel: ingestion-channel tag (default "api") + DryRun bool } // CreateService is the narrow SDK surface for `doc create`. @@ -66,11 +67,31 @@ don't require a file upload or remote URL. KB resolution follows the standard return err } fopts.ResolveDefault(iostreams.IO.IsStdoutTTY()) - kbID, err := f.ResolveKB(c) + if opts.DryRun { + // ResolveKBLocal validates the KB is set via flag / env / + // project link without an SDK call; the plan reports the + // raw --kb value (UUID or name) for agent inspection. + kbID, err := f.ResolveKBLocal(c) + if err != nil { + return err + } + if handled, err := cmdutil.HandleDryRun(c, true, cmdutil.DryRunPlan{ + Action: "doc.create", + Args: map[string]any{ + "text": opts.Text, + "name": opts.Name, + "kb": kbID, + }, + }); handled { + return err + } + } + cli, err := f.Client() if err != nil { return err } - cli, err := f.Client() + // Live path resolves --kb name → id via the SDK. + kbID, err := f.ResolveKB(c) if err != nil { return err } @@ -84,6 +105,7 @@ don't require a file upload or remote URL. KB resolution follows the standard cmd.Flags().StringVar(&opts.Channel, "channel", "", "Ingestion-channel tag recorded server-side (default \"api\")") _ = cmd.MarkFlagRequired("text") cmdutil.AddFormatFlag(cmd, docCreateFields...) + cmdutil.AddDryRunFlag(cmd, &opts.DryRun) return cmd } diff --git a/cli/cmd/doc/delete.go b/cli/cmd/doc/delete.go index bb791a23..eb91aad7 100644 --- a/cli/cmd/doc/delete.go +++ b/cli/cmd/doc/delete.go @@ -19,9 +19,10 @@ import ( var docDeleteFields = []string{"id", "deleted"} type DeleteOptions struct { - Yes bool // sourced from the global -y/--yes persistent flag (see cli/cmd/root.go) - All bool // delete all docs in --kb - KB string // required when --all + Yes bool // sourced from the global -y/--yes persistent flag (see cli/cmd/root.go) + All bool // delete all docs in --kb + KB string // required when --all + DryRun bool } // DeleteService is the narrow SDK surface this command depends on. @@ -86,11 +87,10 @@ without the user's explicit go-ahead.`, } fopts.ResolveDefault(iostreams.IO.IsStdoutTTY()) opts.Yes, _ = c.Flags().GetBool("yes") - cli, err := f.Client() - if err != nil { - return err - } - + // Structural validation (pure-local) must run before the dry-run + // gate so --dry-run rejects the same invalid invocations the live + // path rejects. Same typed errors are kept below the gate for + // safety (in case of future callers that bypass RunE). if opts.All { if opts.KB == "" { return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, "--all requires --kb="). @@ -100,11 +100,30 @@ without the user's explicit go-ahead.`, if len(args) > 0 { return cmdutil.NewFlagError(fmt.Errorf("--all is exclusive with positional doc ids")) } - return runDeleteAll(c.Context(), opts, fopts, cli, f.Prompter()) - } - if len(args) == 0 { + } else if len(args) == 0 { return cmdutil.NewFlagError(fmt.Errorf("doc id(s) required (or use --all --kb=)")) } + if opts.DryRun { + plan := cmdutil.DryRunPlan{ + Action: "doc.delete", + Args: map[string]any{"doc_ids": args}, + } + if opts.All { + plan.Action = "doc.delete_all" + plan.Args = map[string]any{"all": true, "kb": opts.KB} + } + if handled, err := cmdutil.HandleDryRun(c, true, plan); handled { + return err + } + } + cli, err := f.Client() + if err != nil { + return err + } + + if opts.All { + return runDeleteAll(c.Context(), opts, fopts, cli, f.Prompter()) + } // Single-id uses the simpler code path (bare {id, deleted}). if len(args) == 1 { return runDelete(c.Context(), opts, fopts, cli, f.Prompter(), args[0]) @@ -132,6 +151,8 @@ without the user's explicit go-ahead.`, cmd.Flags().BoolVar(&opts.All, "all", false, "delete all documents in the KB specified by --kb") cmd.Flags().StringVar(&opts.KB, "kb", "", "knowledge base ID (required with --all)") cmdutil.AddFormatFlag(cmd, docDeleteFields...) + cmdutil.AddDryRunFlag(cmd, &opts.DryRun) + cmdutil.SetRisk(cmd, "doc.delete") cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{ UsedFor: "permanently delete one or more documents from a knowledge base", RequiredFlags: []string{"... (positional) | --all --kb="}, @@ -141,7 +162,9 @@ without the user's explicit go-ahead.`, "weknora doc delete --all --kb=kb_x -y --format json", }, Warnings: []string{ - "doc delete is irreversible. --all --kb= atomically clears every document in the KB; that is especially destructive. Never auto-add -y; surface the exit-10 prompt to the user and only retry after explicit approval.", + "Requires explicit user approval (exit 10 / input.confirmation_required); never auto-add -y.", + "doc delete is irreversible; loses the document + its chunks + embeddings.", + "--all empties the entire KB; thousands of documents may be lost in one operation.", }, }) return cmd diff --git a/cli/cmd/doc/dryrun_validation_test.go b/cli/cmd/doc/dryrun_validation_test.go new file mode 100644 index 00000000..865c8fd3 --- /dev/null +++ b/cli/cmd/doc/dryrun_validation_test.go @@ -0,0 +1,142 @@ +// Package doc — dryrun_validation_test.go asserts that --dry-run on +// doc subcommands rejects identically to the live path (industry standard: +// gh / kubectl / lark all validate before previewing). Before the surrounding +// fix, validation lived in runX() and was reached only after HandleDryRun +// short-circuited, so --dry-run silently emitted plan envelopes for inputs +// the live path would reject — agents got false-positive previews. +package doc + +import ( + "context" + "errors" + "testing" + + "github.com/spf13/cobra" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/Tencent/WeKnora/cli/internal/cmdutil" + "github.com/Tencent/WeKnora/cli/internal/iostreams" + "github.com/Tencent/WeKnora/cli/internal/prompt" + sdk "github.com/Tencent/WeKnora/client" +) + +// docDryRunFactory builds a Factory whose Client closure panics if invoked — +// dry-run must early-exit before any SDK call. Factory.ResolveKB is a method +// that short-circuits when --kb is a uuid (IsKBID), so the tests below pass +// a literal uuid to avoid the Client()-based name lookup path. +func docDryRunFactory(t *testing.T) *cmdutil.Factory { + t.Helper() + return &cmdutil.Factory{ + Client: func() (*sdk.Client, error) { + t.Fatal("dry-run path must not call Factory.Client(); SDK side effect leaked") + return nil, nil + }, + Prompter: func() prompt.Prompter { + t.Fatal("dry-run path must not call Factory.Prompter(); confirm-prompt side effect leaked") + return nil + }, + } +} + +// withRootHarnessDoc wraps a doc subcommand under a synthetic root cmd that +// registers the global persistent flags (mirrors addGlobalFlags in +// cmd/root.go). +func withRootHarnessDoc(sub *cobra.Command, args ...string) *cobra.Command { + root := &cobra.Command{Use: "weknora"} + pf := root.PersistentFlags() + pf.BoolP("yes", "y", false, "") + pf.String("format", "", "") + pf.StringP("jq", "q", "", "") + root.AddCommand(sub) + root.SetArgs(append([]string{sub.Name()}, args...)) + root.SetContext(context.Background()) + root.SilenceErrors = true + root.SilenceUsage = true + return root +} + +// TestDocDelete_DryRun_RejectsAllWithoutKB: --all without --kb is rejected +// on the live path; --dry-run must do the same. +func TestDocDelete_DryRun_RejectsAllWithoutKB(t *testing.T) { + iostreams.SetForTest(t) + root := withRootHarnessDoc(NewCmdDelete(docDryRunFactory(t)), + "--all", "--dry-run", "--format", "json") + err := root.Execute() + require.Error(t, err) + var typed *cmdutil.Error + require.True(t, errors.As(err, &typed), "expected *cmdutil.Error, got %T %v", err, err) + assert.Equal(t, cmdutil.CodeInputInvalidArgument, typed.Code) +} + +// TestDocDelete_DryRun_RejectsAllWithIDs: --all + positional ids is mutually +// exclusive; --dry-run must reject the same. +func TestDocDelete_DryRun_RejectsAllWithIDs(t *testing.T) { + iostreams.SetForTest(t) + root := withRootHarnessDoc(NewCmdDelete(docDryRunFactory(t)), + "doc_a", "--all", "--kb", "00000000-0000-0000-0000-000000000001", "--dry-run", "--format", "json") + err := root.Execute() + require.Error(t, err) + // FlagError ⇒ exit 2. + assert.Equal(t, 2, cmdutil.ExitCode(err)) +} + +// TestDocDelete_DryRun_RejectsNoIDsNoAll: no positional ids and no --all is +// rejected on the live path; --dry-run must do the same. +func TestDocDelete_DryRun_RejectsNoIDsNoAll(t *testing.T) { + iostreams.SetForTest(t) + root := withRootHarnessDoc(NewCmdDelete(docDryRunFactory(t)), + "--dry-run", "--format", "json") + err := root.Execute() + require.Error(t, err) + assert.Equal(t, 2, cmdutil.ExitCode(err)) +} + +// TestDocFetch_DryRun_RejectsInvalidURL: malformed URL is rejected on the +// live path via cmdutil.ValidateHTTPURL; --dry-run must do the same. +func TestDocFetch_DryRun_RejectsInvalidURL(t *testing.T) { + iostreams.SetForTest(t) + root := withRootHarnessDoc(NewCmdFetch(docDryRunFactory(t)), + "not-a-url", "--kb", "00000000-0000-0000-0000-000000000001", "--dry-run", "--format", "json") + err := root.Execute() + require.Error(t, err, "dry-run must reject malformed URL") +} + +// TestDocUpload_DryRun_RejectsMissingPositional: positional file path is +// required (or --recursive); --dry-run must reject identically. +func TestDocUpload_DryRun_RejectsMissingPositional(t *testing.T) { + iostreams.SetForTest(t) + root := withRootHarnessDoc(NewCmdUpload(docDryRunFactory(t)), + "--kb", "00000000-0000-0000-0000-000000000001", "--dry-run", "--format", "json") + err := root.Execute() + require.Error(t, err, "dry-run must reject missing positional file path") +} + +// TestDocUpload_DryRun_RejectsBadMetadata: --metadata key=value enforces +// the `key=value` shape; --dry-run must reject malformed values too. +func TestDocUpload_DryRun_RejectsBadMetadata(t *testing.T) { + iostreams.SetForTest(t) + root := withRootHarnessDoc(NewCmdUpload(docDryRunFactory(t)), + "./somefile", "--kb", "00000000-0000-0000-0000-000000000001", "--metadata", "no-equals-sign", + "--dry-run", "--format", "json") + err := root.Execute() + require.Error(t, err, "dry-run must reject malformed --metadata") + var typed *cmdutil.Error + require.True(t, errors.As(err, &typed)) + assert.Equal(t, cmdutil.CodeInputInvalidArgument, typed.Code) +} + +// TestDocUpload_DryRun_RejectsBadEnableMultimodel: --enable-multimodel +// expects a parseable tri-bool; --dry-run must reject the same garbage +// values the live path rejects. +func TestDocUpload_DryRun_RejectsBadEnableMultimodel(t *testing.T) { + iostreams.SetForTest(t) + root := withRootHarnessDoc(NewCmdUpload(docDryRunFactory(t)), + "./somefile", "--kb", "00000000-0000-0000-0000-000000000001", "--enable-multimodel=garbage", + "--dry-run", "--format", "json") + err := root.Execute() + require.Error(t, err) + var typed *cmdutil.Error + require.True(t, errors.As(err, &typed)) + assert.Equal(t, cmdutil.CodeInputInvalidArgument, typed.Code) +} diff --git a/cli/cmd/doc/fetch.go b/cli/cmd/doc/fetch.go index 7d944c2f..28ede79d 100644 --- a/cli/cmd/doc/fetch.go +++ b/cli/cmd/doc/fetch.go @@ -32,6 +32,7 @@ type FetchOptions struct { TagID string // --tag-id: associate the new entry with a tag Channel string // --channel: ingestion-channel tag (default "api") EnableMultimodel *bool // tri-state: nil = server default + DryRun bool } // FetchService is the narrow SDK surface for `doc fetch`. @@ -82,7 +83,8 @@ Server-side ingestion knobs: return err } fopts.ResolveDefault(iostreams.IO.IsStdoutTTY()) - // Tri-state --enable-multimodel: nil = unset (server default). + // Pure-local validation runs before the dry-run gate so --dry-run + // rejects identically to the live path. if c.Flags().Changed("enable-multimodel") { raw, _ := c.Flags().GetString("enable-multimodel") v, perr := parseTriBool(raw) @@ -94,11 +96,28 @@ Server-side ingestion knobs: if err := cmdutil.ValidateHTTPURL("", opts.URL); err != nil { return err } - kbID, err := f.ResolveKB(c) + if opts.DryRun { + // Local-only KB resolution: plan reports the raw --kb value + // (UUID or name) without an SDK lookup. + kbID, err := f.ResolveKBLocal(c) + if err != nil { + return err + } + if handled, err := cmdutil.HandleDryRun(c, true, cmdutil.DryRunPlan{ + Action: "doc.fetch", + Args: map[string]any{ + "url": opts.URL, + "kb": kbID, + }, + }); handled { + return err + } + } + cli, err := f.Client() if err != nil { return err } - cli, err := f.Client() + kbID, err := f.ResolveKB(c) if err != nil { return err } @@ -114,6 +133,7 @@ Server-side ingestion knobs: cmd.Flags().String("enable-multimodel", "", "Toggle multimodal extraction (true|false); unset ⇒ server default") cmd.Flags().Lookup("enable-multimodel").NoOptDefVal = "true" cmdutil.AddFormatFlag(cmd, docFetchFields...) + cmdutil.AddDryRunFlag(cmd, &opts.DryRun) return cmd } diff --git a/cli/cmd/doc/upload.go b/cli/cmd/doc/upload.go index e5b9aefe..448e7825 100644 --- a/cli/cmd/doc/upload.go +++ b/cli/cmd/doc/upload.go @@ -49,6 +49,8 @@ type UploadOptions struct { // Channel overrides the ingestion-channel tag recorded server-side. // Empty ⇒ uploadChannel ("api"). Free-form: server validates. Channel string + + DryRun bool } // UploadService is the narrow SDK surface this command depends on. @@ -107,10 +109,11 @@ Server-side ingestion knobs: return err } fopts.ResolveDefault(iostreams.IO.IsStdoutTTY()) - // Translate the tri-state --enable-multimodel flag into the - // *bool the SDK expects. Cobra's BoolVar can't distinguish - // "unset" from "false", so we register a String flag and read - // Changed() + the raw value here. + // Pure-local validation runs before the dry-run gate so --dry-run + // rejects identically to the live path. Filesystem stat + // (validateUploadPath) and recursive directory enumeration are + // intentionally skipped under --dry-run — those are side-effect-ish + // reads the preview is allowed to defer. if c.Flags().Changed("enable-multimodel") { raw, _ := c.Flags().GetString("enable-multimodel") v, perr := parseTriBool(raw) @@ -122,11 +125,44 @@ Server-side ingestion knobs: if err := validateUploadFlags(opts, args); err != nil { return err } - kbID, err := f.ResolveKB(c) + // Validate --metadata key=value shape upfront; same typed Error as + // runUpload (kept there for direct-call callers / batch paths). + if _, err := parseMetadataKV(opts.Metadata); err != nil { + return err + } + if opts.DryRun { + // Local-only KB resolution: plan reports the raw --kb value + // without an SDK lookup. + kbID, err := f.ResolveKBLocal(c) + if err != nil { + return err + } + filePath := args[0] + planArgs := map[string]any{ + "file": filePath, + "kb": kbID, + } + // recursive vs single-file is the blast-radius switch + // (N docs vs 1); surface it on the plan so agents can + // decide whether to gate on user approval. + if opts.Recursive { + planArgs["recursive"] = true + } + if opts.Glob != "" { + planArgs["glob"] = opts.Glob + } + if handled, err := cmdutil.HandleDryRun(c, true, cmdutil.DryRunPlan{ + Action: "doc.upload", + Args: planArgs, + }); handled { + return err + } + } + cli, err := f.Client() if err != nil { return err } - cli, err := f.Client() + kbID, err := f.ResolveKB(c) if err != nil { return err } @@ -151,6 +187,7 @@ Server-side ingestion knobs: cmd.Flags().StringSliceVar(&opts.Metadata, "metadata", nil, "Attach metadata `key=value` (repeatable; empty value allowed, last-wins on duplicate keys)") cmd.Flags().StringVar(&opts.Channel, "channel", "", "Ingestion-channel tag recorded server-side (default \"api\")") cmdutil.AddFormatFlag(cmd, docUploadFields...) + cmdutil.AddDryRunFlag(cmd, &opts.DryRun) return cmd } diff --git a/cli/cmd/kb/create.go b/cli/cmd/kb/create.go index ac278ea9..def0290c 100644 --- a/cli/cmd/kb/create.go +++ b/cli/cmd/kb/create.go @@ -31,6 +31,7 @@ type CreateOptions struct { Description string EmbeddingModel string StorageProvider string + DryRun bool } // storageProviderValues mirrors the server enum in @@ -58,6 +59,26 @@ func NewCmdCreate(f *cmdutil.Factory) *cobra.Command { } fopts.ResolveDefault(iostreams.IO.IsStdoutTTY()) opts.Name = args[0] + // Validate --storage-provider enum before the dry-run gate so + // --dry-run rejects identically to the live path. Same typed + // FlagError as runCreate (kept there for direct-call callers). + if opts.StorageProvider != "" { + v := strings.ToLower(strings.TrimSpace(opts.StorageProvider)) + if !slices.Contains(storageProviderValues, v) { + return cmdutil.NewFlagError(fmt.Errorf( + "invalid --storage-provider %q: must be %s", + opts.StorageProvider, strings.Join(storageProviderValues, " | "))) + } + } + if handled, err := cmdutil.HandleDryRun(c, opts.DryRun, cmdutil.DryRunPlan{ + Action: "kb.create", + Args: map[string]any{ + "name": opts.Name, + "description": opts.Description, + }, + }); handled { + return err + } cli, err := f.Client() if err != nil { return err @@ -70,6 +91,7 @@ func NewCmdCreate(f *cmdutil.Factory) *cobra.Command { cmd.Flags().StringVar(&opts.StorageProvider, "storage-provider", "", "Storage provider for documents in this KB: "+strings.Join(storageProviderValues, " | ")+" (optional; server default when unset)") cmdutil.AddFormatFlag(cmd, kbCreateFields...) + cmdutil.AddDryRunFlag(cmd, &opts.DryRun) return cmd } diff --git a/cli/cmd/kb/create_dry_run_test.go b/cli/cmd/kb/create_dry_run_test.go new file mode 100644 index 00000000..ebd2662f --- /dev/null +++ b/cli/cmd/kb/create_dry_run_test.go @@ -0,0 +1,99 @@ +package kb + +import ( + "context" + "encoding/json" + "testing" + + "github.com/spf13/cobra" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/Tencent/WeKnora/cli/internal/cmdutil" + "github.com/Tencent/WeKnora/cli/internal/iostreams" + "github.com/Tencent/WeKnora/cli/internal/prompt" + sdk "github.com/Tencent/WeKnora/client" +) + +// kbDryRunFactory builds a Factory whose Client closure panics if invoked — +// dry-run must early-exit before any SDK call. Prompter is similarly trapped: +// dry-run is non-interactive by contract. +func kbDryRunFactory(t *testing.T) *cmdutil.Factory { + t.Helper() + return &cmdutil.Factory{ + Client: func() (*sdk.Client, error) { + t.Fatal("dry-run path must not call Factory.Client(); SDK side effect leaked") + return nil, nil + }, + Prompter: func() prompt.Prompter { + t.Fatal("dry-run path must not call Factory.Prompter(); confirm-prompt side effect leaked") + return nil + }, + } +} + +// withRootHarness wraps a kb command under a synthetic root cmd that +// registers the global persistent flags (mirrors addGlobalFlags in +// cmd/root.go). Required because kb subcommands inherit --yes / --format / +// --jq from root in production. +func withRootHarness(sub *cobra.Command, args ...string) *cobra.Command { + root := &cobra.Command{Use: "weknora"} + pf := root.PersistentFlags() + pf.BoolP("yes", "y", false, "") + pf.String("format", "", "") + pf.StringP("jq", "q", "", "") + root.AddCommand(sub) + root.SetArgs(append([]string{sub.Name()}, args...)) + root.SetContext(context.Background()) + root.SilenceErrors = true + root.SilenceUsage = true + return root +} + +// TestKBCreate_DryRun_EmitsPlan: --dry-run on `kb create` must emit the +// standard dry-run envelope (ok:true, meta.dry_run:true, meta.plan.action) and +// must NOT touch the SDK. Verifies that the cobra-layer early-exit runs before +// f.Client() and that the plan shape matches the envelope contract. +func TestKBCreate_DryRun_EmitsPlan(t *testing.T) { + out, _ := iostreams.SetForTest(t) + f := kbDryRunFactory(t) + root := withRootHarness(NewCmdCreate(f), + "foo", "--description", "bar", "--dry-run", "--format", "json") + require.NoError(t, root.Execute(), "dry-run must succeed (exit 0) without SDK") + + var env struct { + OK bool `json:"ok"` + Meta struct { + DryRun bool `json:"dry_run"` + Plan map[string]any `json:"plan"` + } `json:"meta"` + Data any `json:"data"` + } + require.NoError(t, json.Unmarshal(out.Bytes(), &env), "expected valid JSON envelope, got %q", out.String()) + assert.True(t, env.OK, "envelope.ok must be true on dry-run success") + assert.True(t, env.Meta.DryRun, "meta.dry_run must be true") + assert.Equal(t, "kb.create", env.Meta.Plan["action"], "plan.action must be kb.create") + // plan.args contains the user-provided flags so agents can diff "what would happen". + planArgs, ok := env.Meta.Plan["args"].(map[string]any) + require.True(t, ok, "plan.args must be a map, got %T", env.Meta.Plan["args"]) + assert.Equal(t, "foo", planArgs["name"], "plan.args.name must echo positional ") + assert.Equal(t, "bar", planArgs["description"], "plan.args.description must echo --description") + assert.Nil(t, env.Data, "data must be omitted on dry-run (no real result)") +} + +// TestKBCreate_DryRun_RejectsInvalidStorageProvider: --dry-run must reject +// the same invalid --storage-provider value the live path rejects. Before +// the fix the enum check lived only in runCreate(), which HandleDryRun +// short-circuited past — so --dry-run silently accepted "garbage". +func TestKBCreate_DryRun_RejectsInvalidStorageProvider(t *testing.T) { + iostreams.SetForTest(t) + f := kbDryRunFactory(t) + root := withRootHarness(NewCmdCreate(f), + "foo", "--storage-provider", "garbage", "--dry-run", "--format", "json") + err := root.Execute() + require.Error(t, err, "dry-run must reject invalid --storage-provider") + + // runCreate emits a FlagError (exit 2) for this — make sure dry-run preserves + // that exact mapping. + assert.Equal(t, 2, cmdutil.ExitCode(err), "FlagError must map to exit 2") +} diff --git a/cli/cmd/kb/delete.go b/cli/cmd/kb/delete.go index da98a6a6..6e682b56 100644 --- a/cli/cmd/kb/delete.go +++ b/cli/cmd/kb/delete.go @@ -16,7 +16,8 @@ import ( var kbDeleteFields = []string{"id", "deleted"} type DeleteOptions struct { - Yes bool // sourced from the global -y/--yes persistent flag (see cli/cmd/root.go addGlobalFlags) + 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. @@ -59,6 +60,14 @@ exactly to guard against unintended deletes.`, } fopts.ResolveDefault(iostreams.IO.IsStdoutTTY()) opts.Yes, _ = c.Flags().GetBool("yes") + if handled, err := cmdutil.HandleDryRun(c, opts.DryRun, cmdutil.DryRunPlan{ + Action: "kb.delete", + Args: map[string]any{ + "kb_ids": args, + }, + }); handled { + return err + } cli, err := f.Client() if err != nil { return err @@ -67,6 +76,8 @@ exactly to guard against unintended deletes.`, }, } cmdutil.AddFormatFlag(cmd, kbDeleteFields...) + cmdutil.AddDryRunFlag(cmd, &opts.DryRun) + cmdutil.SetRisk(cmd, "kb.delete") cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{ UsedFor: "permanently delete a knowledge base and all its contents", RequiredFlags: []string{" (positional)"}, @@ -75,7 +86,8 @@ exactly to guard against unintended deletes.`, "weknora kb delete kb_abc -y --format json", }, Warnings: []string{ - "kb delete is irreversible; whole KB + docs + chunks gone. Never auto-add -y; surface the exit-10 prompt to the user and only retry after explicit approval.", + "Requires explicit user approval (exit 10 / input.confirmation_required); never auto-add -y.", + "kb delete is irreversible; whole KB + docs + chunks gone.", }, }) return cmd diff --git a/cli/cmd/kb/delete_dry_run_test.go b/cli/cmd/kb/delete_dry_run_test.go new file mode 100644 index 00000000..9ba8ba34 --- /dev/null +++ b/cli/cmd/kb/delete_dry_run_test.go @@ -0,0 +1,61 @@ +package kb + +import ( + "encoding/json" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/Tencent/WeKnora/cli/internal/cmdutil" + "github.com/Tencent/WeKnora/cli/internal/iostreams" +) + +// TestKBDelete_DryRun_NoExit10: --dry-run must bypass ConfirmDestructive. +// Non-TTY without -y normally yields exit 10 (CodeInputConfirmationRequired); +// with --dry-run it must early-exit successfully (exit 0) because no real +// delete happens — preview implies no execution, so the confirmation gate +// is irrelevant. +func TestKBDelete_DryRun_NoExit10(t *testing.T) { + out, _ := iostreams.SetForTest(t) // non-TTY + f := kbDryRunFactory(t) + root := withRootHarness(NewCmdDelete(f), "kb_to_preview", "--dry-run", "--format", "json") + err := root.Execute() + require.NoError(t, err, "dry-run must succeed (exit 0); ConfirmDestructive must be skipped") + assert.Equal(t, 0, cmdutil.ExitCode(err), "exit code must be 0, not 10 (confirmation_required)") + + var env struct { + OK bool `json:"ok"` + Meta struct { + DryRun bool `json:"dry_run"` + Plan map[string]any `json:"plan"` + } `json:"meta"` + } + require.NoError(t, json.Unmarshal(out.Bytes(), &env), "expected valid JSON envelope, got %q", out.String()) + assert.True(t, env.OK) + assert.True(t, env.Meta.DryRun) + assert.Equal(t, "kb.delete", env.Meta.Plan["action"]) +} + +// TestKBDelete_DryRunWithYes_EquivalentToDryRunAlone: -y is a no-op when +// --dry-run is set (no real delete happens, so no confirmation gate to skip). +// The envelope shape must match the dry-run-alone case exactly so agents can +// rely on the plan output regardless of whether the human pre-approved. +func TestKBDelete_DryRunWithYes_EquivalentToDryRunAlone(t *testing.T) { + // First invocation: --dry-run alone. + outA, _ := iostreams.SetForTest(t) + rootA := withRootHarness(NewCmdDelete(kbDryRunFactory(t)), + "kb_to_preview", "--dry-run", "--format", "json") + require.NoError(t, rootA.Execute()) + gotA := outA.String() + + // Second invocation: --dry-run + -y. + outB, _ := iostreams.SetForTest(t) + rootB := withRootHarness(NewCmdDelete(kbDryRunFactory(t)), + "kb_to_preview", "--dry-run", "-y", "--format", "json") + require.NoError(t, rootB.Execute(), "--dry-run + -y must succeed identically to --dry-run alone") + gotB := outB.String() + + assert.JSONEq(t, gotA, gotB, + "--dry-run output must be identical with or without -y; -y is a no-op under dry-run") +} diff --git a/cli/cmd/kb/edit.go b/cli/cmd/kb/edit.go index ca6a27a8..923b515c 100644 --- a/cli/cmd/kb/edit.go +++ b/cli/cmd/kb/edit.go @@ -34,6 +34,7 @@ type EditOptions struct { Name *string Description *string Yes bool // sourced from global -y/--yes persistent flag + DryRun bool } // EditService is the narrow SDK surface this command depends on. GetKnowledgeBase @@ -75,11 +76,36 @@ to the user first.`, if c.Flag("description").Changed { opts.Description = &desc } + id := args[0] + // Validate pure-local "at least one mutation flag" before the + // dry-run gate so --dry-run rejects identically to the live path + // (industry standard: gh / kubectl / lark all validate before + // preview). Same typed Error as runEdit so live behavior is + // unchanged, just earlier. + if opts.Name == nil && opts.Description == nil { + return &cmdutil.Error{ + Code: cmdutil.CodeInputMissingFlag, + Message: "kb edit requires at least one of --name or --description", + Hint: "pass --name and/or --description ", + } + } + planArgs := map[string]any{"kb": id} + if opts.Name != nil { + planArgs["name"] = *opts.Name + } + if opts.Description != nil { + planArgs["description"] = *opts.Description + } + if handled, err := cmdutil.HandleDryRun(c, opts.DryRun, cmdutil.DryRunPlan{ + Action: "kb.edit", + Args: planArgs, + }); handled { + return err + } cli, err := f.Client() if err != nil { return err } - id := args[0] // Build a retry command from the flags the user actually passed so // agents can re-invoke with -y after explicit human approval. retryCmd := buildKBEditRetryCmd(c, id) @@ -92,6 +118,8 @@ to the user first.`, cmd.Flags().StringVar(&name, "name", "", "New name (omit to leave unchanged)") cmd.Flags().StringVar(&desc, "description", "", "New description (omit to leave unchanged)") cmdutil.AddFormatFlag(cmd, kbEditFields...) + cmdutil.AddDryRunFlag(cmd, &opts.DryRun) + cmdutil.SetRisk(cmd, "kb.edit") cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{ UsedFor: "update a knowledge base's name or description", RequiredFlags: []string{" (positional)", "--name or --description (at least one)"}, @@ -100,7 +128,8 @@ to the user first.`, "weknora kb edit kb_abc --description \"Updated desc\" --format json -y", }, Warnings: []string{ - "kb edit can change KB ownership / model config. Surface the exit-10 prompt to the user — only proceed after explicit approval.", + "Requires explicit user approval (exit 10 / input.confirmation_required); never auto-add -y.", + "kb edit overwrites fields; SDK uses fetch-then-update to avoid clobbering, but malformed input can still corrupt config.", }, }) return cmd diff --git a/cli/cmd/kb/edit_dry_run_test.go b/cli/cmd/kb/edit_dry_run_test.go new file mode 100644 index 00000000..c3e88460 --- /dev/null +++ b/cli/cmd/kb/edit_dry_run_test.go @@ -0,0 +1,30 @@ +package kb + +import ( + "errors" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/Tencent/WeKnora/cli/internal/cmdutil" + "github.com/Tencent/WeKnora/cli/internal/iostreams" +) + +// TestKBEdit_DryRun_RejectsNoMutationFlag: --dry-run must reject the same +// "no mutation flag supplied" invocation the live path rejects. Before the +// fix the validation lived in runEdit() (the live-only callee) and was +// reached only after HandleDryRun early-exited, so --dry-run silently +// emitted a no-op plan envelope. Industry standard (gh / kubectl / lark) +// validates before previewing. +func TestKBEdit_DryRun_RejectsNoMutationFlag(t *testing.T) { + iostreams.SetForTest(t) + f := kbDryRunFactory(t) + root := withRootHarness(NewCmdEdit(f), "kb_abc", "--dry-run", "--format", "json") + err := root.Execute() + require.Error(t, err, "dry-run must reject identically to live path") + + var typed *cmdutil.Error + require.True(t, errors.As(err, &typed), "expected *cmdutil.Error, got %T %v", err, err) + assert.Equal(t, cmdutil.CodeInputMissingFlag, typed.Code, "must use the same code runEdit emits") +} diff --git a/cli/cmd/link/dryrun_validation_test.go b/cli/cmd/link/dryrun_validation_test.go new file mode 100644 index 00000000..fc516a8d --- /dev/null +++ b/cli/cmd/link/dryrun_validation_test.go @@ -0,0 +1,106 @@ +// Package linkcmd — dryrun_validation_test.go asserts that --dry-run on +// link / unlink rejects identically to the live path. Before the surrounding +// fix, validation lived in runX() and was reached only after HandleDryRun +// short-circuited, so --dry-run accepted invocations the live path rejects. +package linkcmd + +import ( + "context" + "errors" + "os" + "testing" + + "github.com/spf13/cobra" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "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/prompt" + sdk "github.com/Tencent/WeKnora/client" +) + +// linkDryRunFactory builds a Factory whose Client closure panics if invoked — +// dry-run must early-exit before any SDK call. +func linkDryRunFactory(t *testing.T, cfg *config.Config) *cmdutil.Factory { + t.Helper() + return &cmdutil.Factory{ + Config: func() (*config.Config, error) { return cfg, nil }, + Client: func() (*sdk.Client, error) { + t.Fatal("dry-run path must not call Factory.Client(); SDK side effect leaked") + return nil, nil + }, + Prompter: func() prompt.Prompter { + t.Fatal("dry-run path must not call Factory.Prompter(); confirm-prompt side effect leaked") + return nil + }, + } +} + +// withRootHarnessLink wraps a link subcommand under a synthetic root cmd +// that registers the global persistent flags. +func withRootHarnessLink(sub *cobra.Command, args ...string) *cobra.Command { + root := &cobra.Command{Use: "weknora"} + pf := root.PersistentFlags() + pf.BoolP("yes", "y", false, "") + pf.String("format", "", "") + pf.StringP("jq", "q", "", "") + root.AddCommand(sub) + root.SetArgs(append([]string{sub.Name()}, args...)) + root.SetContext(context.Background()) + root.SilenceErrors = true + root.SilenceUsage = true + return root +} + +// TestLink_DryRun_RejectsNoCurrentProfile: link with no active profile → +// live path returns auth.unauthenticated; --dry-run must do the same. +func TestLink_DryRun_RejectsNoCurrentProfile(t *testing.T) { + iostreams.SetForTest(t) + cfg := &config.Config{} + root := withRootHarnessLink(NewCmd(linkDryRunFactory(t, cfg)), + "--kb", "00000000-0000-0000-0000-000000000001", "--dry-run", "--format", "json") + err := root.Execute() + require.Error(t, err, "dry-run must reject when no current profile") + var typed *cmdutil.Error + require.True(t, errors.As(err, &typed), "expected *cmdutil.Error, got %T %v", err, err) + assert.Equal(t, cmdutil.CodeAuthUnauthenticated, typed.Code) +} + +// TestLink_DryRun_RejectsNoKBNoTTY: --kb omitted on non-TTY → live path +// returns local.kb_id_required; --dry-run must do the same. +func TestLink_DryRun_RejectsNoKBNoTTY(t *testing.T) { + iostreams.SetForTest(t) // non-TTY + cfg := &config.Config{ + CurrentProfile: "prod", + Profiles: map[string]config.Profile{"prod": {Host: "https://prod"}}, + } + root := withRootHarnessLink(NewCmd(linkDryRunFactory(t, cfg)), + "--dry-run", "--format", "json") + err := root.Execute() + require.Error(t, err, "dry-run must reject missing --kb on non-TTY") + var typed *cmdutil.Error + require.True(t, errors.As(err, &typed)) + assert.Equal(t, cmdutil.CodeKBIDRequired, typed.Code) +} + +// TestUnlink_DryRun_RejectsMissingLink: cwd has no .weknora/project.yaml → +// live path returns input.invalid_argument; --dry-run must do the same. +func TestUnlink_DryRun_RejectsMissingLink(t *testing.T) { + iostreams.SetForTest(t) + // Change to an empty temp dir so projectlink.Discover finds nothing. + tmp := t.TempDir() + prev, err := os.Getwd() + require.NoError(t, err) + require.NoError(t, os.Chdir(tmp)) + t.Cleanup(func() { _ = os.Chdir(prev) }) + + root := withRootHarnessLink(NewCmdUnlink(), + "--dry-run", "--format", "json") + err = root.Execute() + require.Error(t, err, "dry-run must reject when no project link present") + var typed *cmdutil.Error + require.True(t, errors.As(err, &typed)) + assert.Equal(t, cmdutil.CodeInputInvalidArgument, typed.Code) +} diff --git a/cli/cmd/link/link.go b/cli/cmd/link/link.go index e76b6483..a4ac4d85 100644 --- a/cli/cmd/link/link.go +++ b/cli/cmd/link/link.go @@ -24,7 +24,8 @@ import ( var linkFields = []string{"profile", "kb_id", "kb_name", "project_link_path"} type Options struct { - KB string // --kb: KB UUID or name; empty triggers interactive prompt on TTY + KB string // --kb: KB UUID or name; empty triggers interactive prompt on TTY + DryRun bool } // linkResult is the typed payload emitted under data. @@ -62,11 +63,30 @@ user explicitly asked to bind this directory; don't run it as a side effect.`, return err } fopts.ResolveDefault(iostreams.IO.IsStdoutTTY()) + // Pure-local validation runs before the dry-run gate so --dry-run + // rejects identically to the live path. resolveProfile only reads + // config; the non-TTY-without-`--kb` check is a flag-shape error. + // Same typed errors as runLink (kept there for direct callers). + if _, err := resolveProfile(f); err != nil { + return err + } + if opts.KB == "" && !iostreams.IO.IsStdoutTTY() { + return cmdutil.NewError(cmdutil.CodeKBIDRequired, "--kb is required (no TTY for interactive prompt)") + } + if handled, err := cmdutil.HandleDryRun(c, opts.DryRun, cmdutil.DryRunPlan{ + Action: "link", + Args: map[string]any{ + "kb": opts.KB, + }, + }); handled { + return err + } return runLink(c.Context(), opts, fopts, f) }, } cmd.Flags().StringVar(&opts.KB, "kb", "", "Knowledge base UUID or name; omit on a TTY for interactive prompt") cmdutil.AddFormatFlag(cmd, linkFields...) + cmdutil.AddDryRunFlag(cmd, &opts.DryRun) return cmd } diff --git a/cli/cmd/link/unlink.go b/cli/cmd/link/unlink.go index 7cf841a0..b614bab0 100644 --- a/cli/cmd/link/unlink.go +++ b/cli/cmd/link/unlink.go @@ -15,7 +15,9 @@ import ( // `unlink`. Tracks the small unlinkResult struct. var unlinkFields = []string{"project_link_path"} -type UnlinkOptions struct{} +type UnlinkOptions struct { + DryRun bool +} // unlinkResult is the typed payload emitted under data. type unlinkResult struct { @@ -45,10 +47,35 @@ is present anywhere in the parent chain.`, return err } fopts.ResolveDefault(iostreams.IO.IsStdoutTTY()) + // Pure-local validation runs before the dry-run gate so --dry-run + // rejects identically to the live path. projectlink.Discover only + // reads the filesystem (no SDK / network). + cwd, cwdErr := os.Getwd() + if cwdErr != nil { + return cmdutil.Wrapf(cmdutil.CodeLocalFileIO, cwdErr, "get cwd") + } + _, found, discErr := projectlink.Discover(cwd) + if discErr != nil { + return cmdutil.Wrapf(cmdutil.CodeLocalFileIO, discErr, "discover project link") + } + if !found { + return &cmdutil.Error{ + Code: cmdutil.CodeInputInvalidArgument, + Message: fmt.Sprintf("no %s/%s found at or above %s", projectlink.DirName, projectlink.FileName, cwd), + Hint: "run `weknora link --kb ` first, or check you're in the right directory", + } + } + if handled, err := cmdutil.HandleDryRun(c, opts.DryRun, cmdutil.DryRunPlan{ + Action: "unlink", + Args: map[string]any{}, + }); handled { + return err + } return runUnlink(opts, fopts) }, } cmdutil.AddFormatFlag(cmd, unlinkFields...) + cmdutil.AddDryRunFlag(cmd, &opts.DryRun) return cmd } diff --git a/cli/cmd/profile/add.go b/cli/cmd/profile/add.go index ea48bc0a..1ab42c24 100644 --- a/cli/cmd/profile/add.go +++ b/cli/cmd/profile/add.go @@ -11,8 +11,9 @@ import ( ) type AddOptions struct { - Host string - User string + Host string + User string + DryRun bool } // profileAddFields enumerates the fields surfaced for `--format json` discovery on @@ -56,16 +57,51 @@ adds leave the current profile untouched.`, return err } fopts.ResolveDefault(iostreams.IO.IsStdoutTTY()) - return runAdd(opts, fopts, args[0]) + // Pure-local validation runs before the dry-run gate so --dry-run + // rejects identically to the live path. Same typed errors as runAdd + // (kept there for direct-call callers). + name := args[0] + if err := cmdutil.ValidateProfileName(name); err != nil { + return err + } + host, err := cmdutil.NormalizeHost(opts.Host) + if err != nil { + return err + } + cfg, err := config.Load() + if err != nil { + return err + } + if _, exists := cfg.Profiles[name]; exists { + return &cmdutil.Error{ + Code: cmdutil.CodeResourceAlreadyExists, + Message: fmt.Sprintf("profile %q already exists", name), + Hint: fmt.Sprintf("use a different name, or run `weknora profile remove %s` first", name), + } + } + if handled, err := cmdutil.HandleDryRun(c, opts.DryRun, cmdutil.DryRunPlan{ + Action: "profile.add", + Args: map[string]any{ + "name": name, + "host": host, + }, + }); handled { + return err + } + return runAddWithConfig(opts, fopts, name, host, cfg) }, } 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 'profile list' (optional, cosmetic only)") cmdutil.AddFormatFlag(cmd, profileAddFields...) + cmdutil.AddDryRunFlag(cmd, &opts.DryRun) _ = cmd.MarkFlagRequired("host") return cmd } +// runAdd is the legacy direct-call entrypoint: revalidates inputs and loads +// config. Preserved for tests / external callers that bypass the cobra layer. +// The cobra RunE path validates earlier and delegates to runAddWithConfig. func runAdd(opts *AddOptions, fopts *cmdutil.FormatOptions, name string) error { if err := cmdutil.ValidateProfileName(name); err != nil { return err @@ -86,6 +122,12 @@ func runAdd(opts *AddOptions, fopts *cmdutil.FormatOptions, name string) error { Hint: fmt.Sprintf("use a different name, or run `weknora profile remove %s` first", name), } } + return runAddWithConfig(opts, fopts, name, host, cfg) +} + +// runAddWithConfig performs the side-effectful write. Inputs are assumed to be +// pre-validated (ValidateProfileName, NormalizeHost, dup-check) by the caller. +func runAddWithConfig(opts *AddOptions, fopts *cmdutil.FormatOptions, name, host string, cfg *config.Config) error { if cfg.Profiles == nil { cfg.Profiles = map[string]config.Profile{} } diff --git a/cli/cmd/profile/dryrun_validation_test.go b/cli/cmd/profile/dryrun_validation_test.go new file mode 100644 index 00000000..50c70c11 --- /dev/null +++ b/cli/cmd/profile/dryrun_validation_test.go @@ -0,0 +1,105 @@ +// Package profilecmd — dryrun_validation_test.go asserts that --dry-run on +// profile subcommands rejects identically to the live path. Before the +// surrounding fix, validation lived in runX() and was reached only after +// HandleDryRun short-circuited, so --dry-run accepted invocations the live +// path would reject. +package profilecmd + +import ( + "context" + "errors" + "testing" + + "github.com/spf13/cobra" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "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/prompt" + "github.com/Tencent/WeKnora/cli/internal/secrets" + sdk "github.com/Tencent/WeKnora/client" +) + +// profileDryRunFactory builds a Factory whose Client closure panics if +// invoked — dry-run must early-exit before any SDK call. +func profileDryRunFactory(t *testing.T) *cmdutil.Factory { + t.Helper() + return &cmdutil.Factory{ + Client: func() (*sdk.Client, error) { + t.Fatal("dry-run path must not call Factory.Client(); SDK side effect leaked") + return nil, nil + }, + Prompter: func() prompt.Prompter { + t.Fatal("dry-run path must not call Factory.Prompter(); confirm-prompt side effect leaked") + return nil + }, + Secrets: func() (secrets.Store, error) { return secrets.NewMemStore(), nil }, + } +} + +// withRootHarnessProfile wraps a profile subcommand under a synthetic root +// cmd that registers the global persistent flags. +func withRootHarnessProfile(sub *cobra.Command, args ...string) *cobra.Command { + root := &cobra.Command{Use: "weknora"} + pf := root.PersistentFlags() + pf.BoolP("yes", "y", false, "") + pf.String("format", "", "") + pf.StringP("jq", "q", "", "") + root.AddCommand(sub) + root.SetArgs(append([]string{sub.Name()}, args...)) + root.SetContext(context.Background()) + root.SilenceErrors = true + root.SilenceUsage = true + return root +} + +// TestProfileAdd_DryRun_RejectsDuplicate: profile already exists → live path +// returns resource.already_exists; --dry-run must do the same. +func TestProfileAdd_DryRun_RejectsDuplicate(t *testing.T) { + t.Setenv("XDG_CONFIG_HOME", t.TempDir()) + iostreams.SetForTest(t) + require.NoError(t, config.Save(&config.Config{ + CurrentProfile: "prod", + Profiles: map[string]config.Profile{"prod": {Host: "https://prod"}}, + })) + + root := withRootHarnessProfile(NewCmdAdd(profileDryRunFactory(t)), + "prod", "--host", "https://other.example.com", "--dry-run", "--format", "json") + err := root.Execute() + require.Error(t, err, "dry-run must reject duplicate profile name") + var typed *cmdutil.Error + require.True(t, errors.As(err, &typed), "expected *cmdutil.Error, got %T %v", err, err) + assert.Equal(t, cmdutil.CodeResourceAlreadyExists, typed.Code) +} + +// TestProfileAdd_DryRun_RejectsInvalidName: shell-unsafe profile name → live +// path returns input.invalid_argument; --dry-run must do the same. +func TestProfileAdd_DryRun_RejectsInvalidName(t *testing.T) { + t.Setenv("XDG_CONFIG_HOME", t.TempDir()) + iostreams.SetForTest(t) + + root := withRootHarnessProfile(NewCmdAdd(profileDryRunFactory(t)), + "bad name", "--host", "https://x.example.com", "--dry-run", "--format", "json") + err := root.Execute() + require.Error(t, err, "dry-run must reject invalid profile name") +} + +// TestProfileRemove_DryRun_RejectsUnknownName: removing a nonexistent profile +// returns local.profile_not_found on the live path; --dry-run must too. +func TestProfileRemove_DryRun_RejectsUnknownName(t *testing.T) { + t.Setenv("XDG_CONFIG_HOME", t.TempDir()) + iostreams.SetForTest(t) + require.NoError(t, config.Save(&config.Config{ + Profiles: map[string]config.Profile{"prod": {Host: "https://prod"}}, + })) + + root := withRootHarnessProfile(NewCmdRemove(profileDryRunFactory(t)), + "ghost", "--dry-run", "--format", "json") + err := root.Execute() + require.Error(t, err, "dry-run must reject unknown profile name") + var typed *cmdutil.Error + require.True(t, errors.As(err, &typed), "expected *cmdutil.Error, got %T %v", err, err) + assert.Equal(t, cmdutil.CodeLocalProfileNotFound, typed.Code) +} diff --git a/cli/cmd/profile/remove.go b/cli/cmd/profile/remove.go index 454d9a72..5f02e02a 100644 --- a/cli/cmd/profile/remove.go +++ b/cli/cmd/profile/remove.go @@ -13,7 +13,8 @@ import ( ) type RemoveOptions struct { - Yes bool // sourced from the global -y/--yes persistent flag (matches `kb delete`) + Yes bool // sourced from the global -y/--yes persistent flag (matches `kb delete`) + DryRun bool } // profileRemoveFields enumerates the fields surfaced for `--format json` discovery on @@ -57,6 +58,25 @@ in scripted / --format json invocations (exit code 10; see cli/README.md).`, } fopts.ResolveDefault(iostreams.IO.IsStdoutTTY()) opts.Yes, _ = c.Flags().GetBool("yes") + // Pure-local existence check runs before the dry-run gate so + // --dry-run rejects unknown profile names identically to the live + // path. Same notFoundError as runRemove (kept there for direct + // callers). + cfg, cfgErr := config.Load() + if cfgErr != nil { + return cfgErr + } + if _, exists := cfg.Profiles[args[0]]; !exists { + return notFoundError(args[0], cfg) + } + if handled, err := cmdutil.HandleDryRun(c, opts.DryRun, cmdutil.DryRunPlan{ + Action: "profile.remove", + Args: map[string]any{ + "name": args[0], + }, + }); handled { + return err + } store, err := f.Secrets() if err != nil { return err @@ -65,6 +85,8 @@ in scripted / --format json invocations (exit code 10; see cli/README.md).`, }, } cmdutil.AddFormatFlag(cmd, profileRemoveFields...) + cmdutil.AddDryRunFlag(cmd, &opts.DryRun) + cmdutil.SetRisk(cmd, "profile.remove") cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{ UsedFor: "remove a named profile and its stored credentials", RequiredFlags: []string{" (positional)"}, @@ -73,7 +95,8 @@ in scripted / --format json invocations (exit code 10; see cli/README.md).`, "weknora profile remove production -y", }, Warnings: []string{ - "profile remove drops the named profile and its stored credentials. Never auto-add -y.", + "Requires explicit user approval (exit 10 / input.confirmation_required); never auto-add -y.", + "profile remove deletes local credentials + config; the server-side token is not revoked (use 'auth logout' on server instead).", }, }) return cmd diff --git a/cli/cmd/session/delete.go b/cli/cmd/session/delete.go index db2bbe9a..1803e812 100644 --- a/cli/cmd/session/delete.go +++ b/cli/cmd/session/delete.go @@ -18,7 +18,8 @@ import ( var sessionDeleteFields = []string{"id", "deleted"} type DeleteOptions struct { - Yes bool // sourced from the global -y/--yes persistent flag + Yes bool // sourced from the global -y/--yes persistent flag + DryRun bool } // DeleteService is the narrow SDK surface this command depends on. @@ -67,6 +68,14 @@ without the user's explicit go-ahead.`, return err } fopts.ResolveDefault(iostreams.IO.IsStdoutTTY()) + if handled, err := cmdutil.HandleDryRun(c, opts.DryRun, cmdutil.DryRunPlan{ + Action: "session.delete", + Args: map[string]any{ + "session_ids": args, + }, + }); handled { + return err + } cli, err := f.Client() if err != nil { return err @@ -96,6 +105,8 @@ without the user's explicit go-ahead.`, }, } cmdutil.AddFormatFlag(cmd, sessionDeleteFields...) + cmdutil.AddDryRunFlag(cmd, &opts.DryRun) + cmdutil.SetRisk(cmd, "session.delete") cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{ UsedFor: "permanently delete one or more chat sessions and their messages", RequiredFlags: []string{"... (positional, at least one)"}, @@ -105,7 +116,8 @@ without the user's explicit go-ahead.`, "weknora session delete s_abc -y --format json", }, Warnings: []string{ - "session delete drops chat history for that session permanently. Never auto-add -y.", + "Requires explicit user approval (exit 10 / input.confirmation_required); never auto-add -y.", + "session delete is irreversible; loses the conversation + all messages + tool call history.", }, }) return cmd diff --git a/cli/internal/cmdutil/agenthelp.go b/cli/internal/cmdutil/agenthelp.go index be47f8f3..5eafb4dc 100644 --- a/cli/internal/cmdutil/agenthelp.go +++ b/cli/internal/cmdutil/agenthelp.go @@ -36,8 +36,9 @@ type AgentHelp struct { // Routing: // - WEKNORA_AGENT_HELP=1: emit the AgentHelp JSON blob to stdout and // return — agents get clean parseable JSON, no trailing prose. -// - Otherwise: render the normal human help, then append an -// "AI agents:" block when Warnings is non-empty. +// - Otherwise (human help path): if cmd has risk annotations from SetRisk, +// prepend "Risk: ()" line; then render the normal human +// help via origHelp; then append the "AI agents:" Warnings block. func SetAgentHelp(cmd *cobra.Command, ah AgentHelp) { origHelp := cmd.HelpFunc() cmd.SetHelpFunc(func(c *cobra.Command, args []string) { @@ -45,6 +46,12 @@ func SetAgentHelp(cmd *cobra.Command, ah AgentHelp) { emitAgentHelp(c.OutOrStdout(), ah) return } + // Prepend Risk: line in the default (human) branch only; the + // JSON branch above already carries warnings[]. Skip silently if + // the command has no risk annotations. + if level, action, ok := GetRisk(c); ok { + fmt.Fprintf(c.OutOrStdout(), "Risk: %s (%s)\n\n", action, level) + } origHelp(c, args) if len(ah.Warnings) > 0 { w := c.OutOrStdout() diff --git a/cli/internal/cmdutil/dryrun.go b/cli/internal/cmdutil/dryrun.go new file mode 100644 index 00000000..3c4265dd --- /dev/null +++ b/cli/internal/cmdutil/dryrun.go @@ -0,0 +1,128 @@ +// Package-level note: +// +// AddDryRunFlag + EmitDryRun + DryRunPlan + HandleDryRun support the +// --dry-run contract for mutation commands: +// - Each mutation cobra command registers --dry-run via AddDryRunFlag. +// - RunE early-exits (BEFORE ConfirmDestructive / Factory.Client() / +// ResolveKB) when opts.DryRun is true, calling EmitDryRun with a +// DryRunPlan describing the would-be action. +// - The api command additionally rejects --dry-run on GET (FlagError). +// +// Side-effect suppression: the dry-run path must NOT call the SDK, write +// the keyring, write .weknora/project.yaml, or write download files. +package cmdutil + +import ( + "encoding/json" + "fmt" + "io" + + "github.com/spf13/cobra" + + "github.com/Tencent/WeKnora/cli/internal/iostreams" + "github.com/Tencent/WeKnora/cli/internal/output" +) + +// DryRunPlan describes the would-be action for envelope meta.plan. +// Field tags use omitempty for api-extra fields so mutation commands +// emit only {action, args} and api commands emit {action, method, path, body}. +type DryRunPlan struct { + Action string `json:"action"` + Args map[string]any `json:"args,omitempty"` + Method string `json:"method,omitempty"` + Path string `json:"path,omitempty"` + Body any `json:"body,omitempty"` +} + +// AddDryRunFlag registers --dry-run on a cobra command, binding to a bool +// pointer. A bool is sufficient because the CLI is single-tenant and +// self-hosted — there is no client/server distinction to encode. +func AddDryRunFlag(cmd *cobra.Command, dest *bool) { + cmd.Flags().BoolVar(dest, "dry-run", false, + "Preview the action without executing (offline; no SDK calls, no file IO)") +} + +// EmitDryRun writes the dry-run envelope to w via FormatOptions.Emit, so the +// envelope inherits the standard _notice injection, TTY indent, --jq filter, +// and profile fields like every other success envelope. fopts may be nil for +// callers that have no resolved FormatOptions (tests, error paths); a JSON-mode +// default is used in that case. +// +// The envelope shape is {ok:true, meta:{dry_run:true, plan:{...}}, ...}; data +// is intentionally omitted (omitempty on Envelope.Data) since dry-run produced +// no real data. +// +// Caller must ensure NO side effects occurred before this point: no SDK call, +// no file write, no keyring touch. +func EmitDryRun(w io.Writer, fopts *FormatOptions, plan DryRunPlan) error { + planMap, err := planToMap(plan) + if err != nil { + return fmt.Errorf("dry-run: encode plan: %w", err) + } + meta := &output.Meta{ + DryRun: true, + Plan: planMap, + } + if fopts == nil { + fopts = &FormatOptions{Mode: FormatJSON} + } + // NDJSON mode is meaningless for a single dry-run envelope (the contract + // emits exactly one object). Fall back to JSON envelope shape so meta.plan + // is surfaced; this matches what every other mutation emit does. + if fopts.Mode == FormatNDJSON { + jsonOpts := *fopts + jsonOpts.Mode = FormatJSON + return jsonOpts.Emit(w, nil, meta) + } + return fopts.Emit(w, nil, meta) +} + +// HandleDryRun bundles the dry-run preamble for mutation command RunE: +// FormatOptions resolution + envelope emit. Returns (handled, err) — when +// handled is true, RunE should return err immediately without doing any +// SDK / Factory.Client() / ResolveKB / ConfirmDestructive work. +// +// Pattern: +// +// if handled, err := cmdutil.HandleDryRun(cmd, opts.DryRun, cmdutil.DryRunPlan{ +// Action: "kb.create", +// Args: map[string]any{"name": opts.Name}, +// }); handled { +// return err +// } +// +// The helper invokes ONLY local config reads (CheckFormatFlag, +// IsStdoutTTY) — no SDK calls, no keyring writes, no file IO. Safe to +// call before any other RunE logic. +// +// The helper re-resolves FormatOptions internally so callsites stay +// single-statement; this is intentionally redundant with the outer +// CheckFormatFlag the non-dry-run success path still needs. The duplication +// is cheap (local flag read) and is the price of consolidating the dry-run +// preamble into one helper. +func HandleDryRun(cmd *cobra.Command, dryRun bool, plan DryRunPlan) (handled bool, err error) { + if !dryRun { + return false, nil + } + fopts, err := CheckFormatFlag(cmd) + if err != nil { + return true, err + } + fopts.ResolveDefault(iostreams.IO.IsStdoutTTY()) + return true, EmitDryRun(iostreams.IO.Out, fopts, plan) +} + +// planToMap converts a DryRunPlan to map[string]any so it can populate +// output.Meta.Plan (which is open-typed). Goes through json to honor the +// omitempty tags so api-only fields don't leak into mutation envelopes. +func planToMap(plan DryRunPlan) (map[string]any, error) { + b, err := json.Marshal(plan) + if err != nil { + return nil, err + } + var m map[string]any + if err := json.Unmarshal(b, &m); err != nil { + return nil, err + } + return m, nil +} diff --git a/cli/internal/cmdutil/dryrun_test.go b/cli/internal/cmdutil/dryrun_test.go new file mode 100644 index 00000000..e7186d67 --- /dev/null +++ b/cli/internal/cmdutil/dryrun_test.go @@ -0,0 +1,224 @@ +package cmdutil + +import ( + "bytes" + "encoding/json" + "testing" + + "github.com/spf13/cobra" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/Tencent/WeKnora/cli/internal/iostreams" + "github.com/Tencent/WeKnora/cli/internal/output" +) + +func TestAddDryRunFlag_RegistersFlag(t *testing.T) { + cmd := &cobra.Command{Use: "create"} + var dryRun bool + AddDryRunFlag(cmd, &dryRun) + flag := cmd.Flags().Lookup("dry-run") + require.NotNil(t, flag, "expected --dry-run flag registered") + assert.Equal(t, "false", flag.DefValue, "default should be false") +} + +func TestEmitDryRun_EmitsEnvelopeWithPlan(t *testing.T) { + var buf bytes.Buffer + plan := DryRunPlan{ + Action: "kb.create", + Args: map[string]any{ + "name": "foo", + "description": "bar", + }, + } + err := EmitDryRun(&buf, &FormatOptions{Mode: FormatJSON}, plan) + require.NoError(t, err) + + var got map[string]any + require.NoError(t, json.Unmarshal(buf.Bytes(), &got)) + + assert.Equal(t, true, got["ok"]) + assert.NotContains(t, got, "data", "data should be omitempty when nil") + + meta, ok := got["meta"].(map[string]any) + require.True(t, ok, "expected meta object") + assert.Equal(t, true, meta["dry_run"]) + + planOut, ok := meta["plan"].(map[string]any) + require.True(t, ok, "expected meta.plan object") + assert.Equal(t, "kb.create", planOut["action"]) + + args, ok := planOut["args"].(map[string]any) + require.True(t, ok) + assert.Equal(t, "foo", args["name"]) + assert.Equal(t, "bar", args["description"]) +} + +func TestEmitDryRun_ApiPlanShape(t *testing.T) { + var buf bytes.Buffer + plan := DryRunPlan{ + Action: "api.post", + Method: "POST", + Path: "/api/v1/knowledge-bases", + Body: map[string]any{"name": "foo"}, + } + err := EmitDryRun(&buf, &FormatOptions{Mode: FormatJSON}, plan) + require.NoError(t, err) + + var got map[string]any + require.NoError(t, json.Unmarshal(buf.Bytes(), &got)) + + planOut := got["meta"].(map[string]any)["plan"].(map[string]any) + assert.Equal(t, "api.post", planOut["action"]) + assert.Equal(t, "POST", planOut["method"]) + assert.Equal(t, "/api/v1/knowledge-bases", planOut["path"]) + + body, ok := planOut["body"].(map[string]any) + require.True(t, ok) + assert.Equal(t, "foo", body["name"]) +} + +func TestEmitDryRun_InjectsNotice(t *testing.T) { + // Regression: dry-run envelope must carry the same _notice channel as + // every other success envelope. PendingNotice is the system-level hook + // used for deprecation / version_skew / security signals. + output.PendingNotice = func() map[string]any { + return map[string]any{"deprecation": "use weknora kb create-v2"} + } + t.Cleanup(func() { output.PendingNotice = nil }) + + var buf bytes.Buffer + err := EmitDryRun(&buf, &FormatOptions{Mode: FormatJSON}, + DryRunPlan{Action: "kb.create", Args: map[string]any{"name": "x"}}) + require.NoError(t, err) + + var got map[string]any + require.NoError(t, json.Unmarshal(buf.Bytes(), &got)) + notice, ok := got["_notice"].(map[string]any) + require.True(t, ok, "expected _notice field on dry-run envelope; got %v", got) + assert.Equal(t, "use weknora kb create-v2", notice["deprecation"]) +} + +func TestEmitDryRun_HonorsTTYIndent(t *testing.T) { + var buf bytes.Buffer + err := EmitDryRun(&buf, &FormatOptions{Mode: FormatJSON, TTY: true}, + DryRunPlan{Action: "kb.create"}) + require.NoError(t, err) + got := buf.String() + assert.Contains(t, got, "\n \"", "TTY=true should produce indented JSON; got %q", got) +} + +func TestEmitDryRun_HonorsJQ(t *testing.T) { + // jq runs against the full envelope, so the user can project any + // envelope field (.meta.dry_run, .meta.plan.action, etc.). Routing + // through FormatOptions.Emit is what makes this work. + var buf bytes.Buffer + err := EmitDryRun(&buf, &FormatOptions{Mode: FormatJSON, JQ: ".meta.plan"}, + DryRunPlan{Action: "kb.create", Args: map[string]any{"name": "foo"}}) + require.NoError(t, err) + var got map[string]any + require.NoError(t, json.Unmarshal(buf.Bytes(), &got)) + assert.Equal(t, "kb.create", got["action"]) + args, ok := got["args"].(map[string]any) + require.True(t, ok) + assert.Equal(t, "foo", args["name"]) + // Sanity: jq output should NOT carry the surrounding envelope fields. + assert.NotContains(t, got, "ok") + assert.NotContains(t, got, "meta") +} + +func TestEmitDryRun_NilFormatOptionsDefaultsJSON(t *testing.T) { + var buf bytes.Buffer + err := EmitDryRun(&buf, nil, DryRunPlan{Action: "kb.create"}) + require.NoError(t, err) + var got map[string]any + require.NoError(t, json.Unmarshal(buf.Bytes(), &got)) + assert.Equal(t, true, got["ok"]) + meta, ok := got["meta"].(map[string]any) + require.True(t, ok) + assert.Equal(t, true, meta["dry_run"]) +} + +func TestEmitDryRun_NDJSONFallsBackToJSON(t *testing.T) { + // NDJSON mode is meaningless for a single dry-run envelope; the helper + // should fall back to JSON envelope shape so meta.plan is surfaced. + var buf bytes.Buffer + err := EmitDryRun(&buf, &FormatOptions{Mode: FormatNDJSON}, + DryRunPlan{Action: "kb.create"}) + require.NoError(t, err) + var got map[string]any + require.NoError(t, json.Unmarshal(buf.Bytes(), &got)) + assert.Equal(t, true, got["ok"]) + meta, ok := got["meta"].(map[string]any) + require.True(t, ok) + assert.Equal(t, true, meta["dry_run"]) +} + +func TestHandleDryRun_NotDryRun_SkipsAndReturnsHandledFalse(t *testing.T) { + // dryRun=false short-circuits before any flag read / IO touch; helper + // returns (false, nil) so RunE proceeds to the live SDK path. + cmd := &cobra.Command{Use: "x"} + var dryRun bool + AddDryRunFlag(cmd, &dryRun) + handled, err := HandleDryRun(cmd, false, DryRunPlan{Action: "kb.create"}) + assert.False(t, handled, "handled must be false when dryRun=false") + assert.NoError(t, err) +} + +func TestHandleDryRun_DryRun_EmitsEnvelopeAndReturnsHandledTrue(t *testing.T) { + // dryRun=true → helper resolves FormatOptions, emits the envelope to + // iostreams.IO.Out, and returns (true, nil). RunE returns the error + // immediately without touching SDK. + out, _ := iostreams.SetForTest(t) + cmd := &cobra.Command{Use: "x"} + var dryRun bool + AddDryRunFlag(cmd, &dryRun) + // --format is a persistent root flag in production; for the unit test + // we register it locally so CheckFormatFlag has something to read. + cmd.Flags().String("format", "", "") + cmd.Flags().String("jq", "", "") + require.NoError(t, cmd.Flags().Set("format", "json")) + + handled, err := HandleDryRun(cmd, true, DryRunPlan{ + Action: "kb.create", + Args: map[string]any{"name": "foo"}, + }) + assert.True(t, handled, "handled must be true when dryRun=true") + require.NoError(t, err) + + var got map[string]any + require.NoError(t, json.Unmarshal(out.Bytes(), &got)) + assert.Equal(t, true, got["ok"]) + meta, ok := got["meta"].(map[string]any) + require.True(t, ok) + assert.Equal(t, true, meta["dry_run"]) + plan, ok := meta["plan"].(map[string]any) + require.True(t, ok) + assert.Equal(t, "kb.create", plan["action"]) +} + +func TestHandleDryRun_InvalidFormat_ReturnsHandledTrueWithError(t *testing.T) { + // Invalid --format must propagate as (true, FlagError) so the caller + // returns immediately; otherwise a broken --format would silently fall + // through to the live SDK path. + _, _ = iostreams.SetForTest(t) + cmd := &cobra.Command{Use: "x"} + var dryRun bool + AddDryRunFlag(cmd, &dryRun) + cmd.Flags().String("format", "", "") + require.NoError(t, cmd.Flags().Set("format", "garbage")) + + handled, err := HandleDryRun(cmd, true, DryRunPlan{Action: "kb.create"}) + assert.True(t, handled, "handled must be true even on flag error so RunE stops") + require.Error(t, err) +} + +func TestEmitDryRun_PopulatesProfile(t *testing.T) { + SetProfile("staging") + t.Cleanup(func() { SetProfile("") }) + + var buf bytes.Buffer + err := EmitDryRun(&buf, &FormatOptions{Mode: FormatJSON}, DryRunPlan{Action: "kb.create"}) + require.NoError(t, err) + assert.Contains(t, buf.String(), `"profile":"staging"`, "expected profile field; got %q", buf.String()) +} diff --git a/cli/internal/cmdutil/factory.go b/cli/internal/cmdutil/factory.go index d294e111..dba21519 100644 --- a/cli/internal/cmdutil/factory.go +++ b/cli/internal/cmdutil/factory.go @@ -230,6 +230,33 @@ func (f *Factory) ResolveKB(cmd *cobra.Command) (string, error) { return "", NewError(CodeKBIDRequired, "kb is required") } +// ResolveKBLocal mirrors ResolveKB but never calls the SDK. When --kb is a +// name (not a UUID) it returns the raw value as-is instead of looking up the +// id server-side. Intended for dry-run paths where SDK side effects must be +// avoided; the dry-run plan reports the user-supplied identifier verbatim, +// and the live execution path resolves the name → id at call time. +func (f *Factory) ResolveKBLocal(cmd *cobra.Command) (string, error) { + if v, _ := cmd.Flags().GetString("kb"); v != "" { + return v, nil + } + if v := os.Getenv("WEKNORA_KB_ID"); v != "" { + return v, nil + } + cwd, err := os.Getwd() + if err == nil { + if path, found, derr := projectlink.Discover(cwd); derr == nil && found { + p, lerr := projectlink.Load(path) + if lerr != nil { + return "", Wrapf(CodeProjectLinkCorrupt, lerr, "read project link") + } + if p.KBID != "" { + return p.KBID, nil + } + } + } + return "", NewError(CodeKBIDRequired, "kb is required") +} + // ApplyLogLevel resolves --log-level / WEKNORA_LOG_LEVEL (in priority order) // and applies the result to the SDK's debug logger. Intended to be called // from the root command's PersistentPreRunE so the resolved level is in diff --git a/cli/internal/cmdutil/risk.go b/cli/internal/cmdutil/risk.go new file mode 100644 index 00000000..173604e1 --- /dev/null +++ b/cli/internal/cmdutil/risk.go @@ -0,0 +1,46 @@ +// Package-level note: +// +// SetRisk attaches risk metadata to a destructive cobra command via cobra +// annotations. The SetAgentHelp wrapper in agenthelp.go reads these +// annotations and prepends a "Risk: ()" line at the top +// of human help output. +// +// envelope.error.risk.action is emitted separately by the +// ConfirmDestructive callsite argument and does NOT read these annotations. +package cmdutil + +import "github.com/spf13/cobra" + +// RiskDestructive is the only level value currently emitted. The annotation +// key reserves "read" / "write" for future use. +const RiskDestructive = "destructive" + +// SetRisk writes risk metadata to a cobra command's annotations. +// Idempotent: re-calling with the same action overwrites cleanly. +// +// nil-map guard: cobra.Command.Annotations is `map[string]string` and +// defaults to nil. Writing to a nil map panics, so we allocate first. +func SetRisk(cmd *cobra.Command, action string) { + if cmd.Annotations == nil { + cmd.Annotations = make(map[string]string) + } + cmd.Annotations["risk.level"] = RiskDestructive + cmd.Annotations["risk.action"] = action +} + +// GetRisk reads risk metadata. Returns (level, action, ok). ok=false when +// either the annotations map is nil or risk.action key is missing. +// +// Reading from a nil map is safe in Go (returns zero value); we still +// check map-existence explicitly for clarity. +func GetRisk(cmd *cobra.Command) (level, action string, ok bool) { + if cmd.Annotations == nil { + return "", "", false + } + action, ok = cmd.Annotations["risk.action"] + if !ok { + return "", "", false + } + level = cmd.Annotations["risk.level"] + return level, action, true +} diff --git a/cli/internal/cmdutil/risk_help_test.go b/cli/internal/cmdutil/risk_help_test.go new file mode 100644 index 00000000..365a30cc --- /dev/null +++ b/cli/internal/cmdutil/risk_help_test.go @@ -0,0 +1,75 @@ +package cmdutil + +import ( + "bytes" + "strings" + "testing" + + "github.com/spf13/cobra" + "github.com/stretchr/testify/assert" +) + +func TestSetAgentHelp_PrependsRiskWhenAnnotated(t *testing.T) { + cmd := &cobra.Command{ + Use: "delete", + Short: "Delete a knowledge base.", + Long: "Delete a knowledge base.\n\nThis is irreversible.", + } + SetRisk(cmd, "kb.delete") + SetAgentHelp(cmd, AgentHelp{ + UsedFor: "remove a KB and all its docs/chunks", + Warnings: []string{"never auto -y"}, + }) + + var buf bytes.Buffer + cmd.SetOut(&buf) + cmd.SetErr(&buf) + t.Setenv("WEKNORA_AGENT_HELP", "") + + cmd.HelpFunc()(cmd, []string{}) + + out := buf.String() + assert.True(t, strings.HasPrefix(out, "Risk: kb.delete (destructive)\n\n"), + "expected Risk: line at top; got:\n%s", out) + assert.Contains(t, out, "AI agents:", "expected AI agents block still present") + assert.Contains(t, out, "- never auto -y", "expected Warnings preserved") +} + +func TestSetAgentHelp_NoRiskWhenUnannotated(t *testing.T) { + cmd := &cobra.Command{ + Use: "list", + Short: "List knowledge bases.", + Long: "List knowledge bases.", + } + // NO SetRisk call — cmd.Annotations stays nil + SetAgentHelp(cmd, AgentHelp{UsedFor: "list KBs"}) + + var buf bytes.Buffer + cmd.SetOut(&buf) + cmd.SetErr(&buf) + t.Setenv("WEKNORA_AGENT_HELP", "") + + cmd.HelpFunc()(cmd, []string{}) + + out := buf.String() + assert.False(t, strings.HasPrefix(out, "Risk:"), + "expected NO Risk: line when not SetRisk'd; got:\n%s", out) +} + +func TestSetAgentHelp_JSONPathUnaffectedByRisk(t *testing.T) { + cmd := &cobra.Command{Use: "delete"} + SetRisk(cmd, "kb.delete") + SetAgentHelp(cmd, AgentHelp{UsedFor: "x", Warnings: []string{"w1"}}) + + var buf bytes.Buffer + cmd.SetOut(&buf) + cmd.SetErr(&buf) + t.Setenv("WEKNORA_AGENT_HELP", "1") + + cmd.HelpFunc()(cmd, []string{}) + + out := buf.String() + assert.False(t, strings.HasPrefix(out, "Risk:"), + "JSON path should NOT contain Risk: prefix; got:\n%s", out) + assert.Contains(t, out, `"used_for": "x"`, "expected JSON body emitted") +} diff --git a/cli/internal/cmdutil/risk_test.go b/cli/internal/cmdutil/risk_test.go new file mode 100644 index 00000000..d65a2ea8 --- /dev/null +++ b/cli/internal/cmdutil/risk_test.go @@ -0,0 +1,54 @@ +package cmdutil + +import ( + "testing" + + "github.com/spf13/cobra" + "github.com/stretchr/testify/assert" +) + +func TestSetRisk_WritesAnnotations(t *testing.T) { + cmd := &cobra.Command{Use: "delete"} + SetRisk(cmd, "kb.delete") + assert.Equal(t, "destructive", cmd.Annotations["risk.level"]) + assert.Equal(t, "kb.delete", cmd.Annotations["risk.action"]) +} + +func TestSetRisk_NilMapGuard(t *testing.T) { + cmd := &cobra.Command{Use: "delete"} + // cmd.Annotations is nil by default + assert.Nil(t, cmd.Annotations) + SetRisk(cmd, "agent.delete") + // Should not panic; should initialize map + assert.NotNil(t, cmd.Annotations) + assert.Equal(t, "agent.delete", cmd.Annotations["risk.action"]) +} + +func TestGetRisk_ReturnsWritten(t *testing.T) { + cmd := &cobra.Command{Use: "delete"} + SetRisk(cmd, "doc.delete") + level, action, ok := GetRisk(cmd) + assert.True(t, ok) + assert.Equal(t, "destructive", level) + assert.Equal(t, "doc.delete", action) +} + +func TestGetRisk_NotFound(t *testing.T) { + cmd := &cobra.Command{Use: "list"} + level, action, ok := GetRisk(cmd) + assert.False(t, ok) + assert.Empty(t, level) + assert.Empty(t, action) +} + +func TestGetRisk_NilAnnotationsMap(t *testing.T) { + cmd := &cobra.Command{Use: "list"} + // Annotations is nil — should not panic, return ok=false + assert.Nil(t, cmd.Annotations) + _, _, ok := GetRisk(cmd) + assert.False(t, ok) +} + +func TestRiskDestructive_Const(t *testing.T) { + assert.Equal(t, "destructive", RiskDestructive) +} diff --git a/cli/internal/output/envelope.go b/cli/internal/output/envelope.go index df235b89..b5fc6d28 100644 --- a/cli/internal/output/envelope.go +++ b/cli/internal/output/envelope.go @@ -38,6 +38,10 @@ type Meta struct { // Non-batch commands leave these nil so they are omitted from the envelope. Successes *int `json:"successes,omitempty"` // batch ops Failures *int `json:"failures,omitempty"` // batch ops + // Dry-run preview fields. Populated by EmitDryRun (cmdutil/dryrun.go) + // when --dry-run is set on a mutation command; omitted otherwise. + DryRun bool `json:"dry_run,omitempty"` // true when --dry-run; omitted otherwise + Plan map[string]any `json:"plan,omitempty"` // would-call shape; open map (action required, other fields command-specific) } // ErrDetail describes a structured error. Embedded in ErrorEnvelope.Error