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
+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
}