feat(cli): --dry-run + risk metadata + validation parity on 19 mutations

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=<action> on the 9 destructive
commands. The SetAgentHelp wrapper prepends a "Risk: <action>
(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
This commit is contained in:
nullkey
2026-05-28 04:28:48 +08:00
committed by lyingbug
parent c11df51c79
commit 6d8c8650cd
37 changed files with 1974 additions and 50 deletions
+12
View File
@@ -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
}
+13 -1
View File
@@ -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{"<agent-id> (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
+61 -1
View File
@@ -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{"<agent-id> (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
+46
View File
@@ -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)
}
+53
View File
@@ -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
}
+127
View File
@@ -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"])
}
+7 -4
View File
@@ -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())
+124
View File
@@ -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)
}
+38 -4
View File
@@ -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
+44 -1
View File
@@ -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
}
+14 -1
View File
@@ -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{"<chunk-id>... (positional, at least one)", "--doc <doc-id>"},
@@ -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
+24 -2
View File
@@ -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
}
+35 -12
View File
@@ -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=<id>").
@@ -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=<id>)"))
}
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{"<doc-id>... (positional) | --all --kb=<id>"},
@@ -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=<id> 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
+142
View File
@@ -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)
}
+23 -3
View File
@@ -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("<url>", 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
}
+43 -6
View File
@@ -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
}
+22
View File
@@ -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
}
+99
View File
@@ -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 <name>")
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")
}
+14 -2
View File
@@ -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{"<kb-id> (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
+61
View File
@@ -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")
}
+31 -2
View File
@@ -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 <name> and/or --description <desc>",
}
}
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{"<kb-id> (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
+30
View File
@@ -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")
}
+106
View File
@@ -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)
}
+21 -1
View File
@@ -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
}
+28 -1
View File
@@ -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 <id>` 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
}
+45 -3
View File
@@ -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{}
}
+105
View File
@@ -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)
}
+25 -2
View File
@@ -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{"<name> (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
+14 -2
View File
@@ -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{"<session-id>... (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
+9 -2
View File
@@ -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: <action> (<level>)" 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()
+128
View File
@@ -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
}
+224
View File
@@ -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())
}
+27
View File
@@ -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
+46
View File
@@ -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: <action> (<level>)" 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
}
+75
View File
@@ -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")
}
+54
View File
@@ -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)
}
+4
View File
@@ -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