refactor(cli): drop --dry-run + introduce bare-JSON output path

Two intertwined mainstream-alignment moves bundled because they share
the migration target (every command's --json path):

1. Drop --dry-run entirely. Survey of comparable API-wrapper CLIs
   (gh, aws, stripe, lark): none expose --dry-run. The mainstream that
   does (kubectl/git/helm/ansible) operates on declarative manifests
   or local state where the preview is materially different from the
   executed action. WeKnora's CLI just echoed the same parameters
   that would have gone on the wire — the preview added no real
   signal over `--help` + reading the call site. Removes:
   - root --dry-run persistent flag + cmdutil/dryrun.go
   - DryRun fields + EmitDryRun calls in 12 write commands
   - format.Envelope.DryRun field
   - 8 corresponding *_test.go cases
   - --dry-run mention from README.md and CHANGELOG.md
   - "dry_run":false from 16 golden envelopes

2. Migrate every --json output to bare data:
   - New format.WriteJSON / WriteJSONFiltered helpers
     (cli/internal/format/bare.go) share filterArrayItems /
     filterObjectKeys / writeJQ with the (still-live for now) envelope
     filter helpers.
   - Read commands (kb/doc/session list+view, search chunks/docs/
     sessions/kb, auth list/status, agent list/view, context list,
     doctor) emit bare arrays / objects on stdout.
   - Write commands (kb create/edit/delete/pin/empty, doc upload/
     upload_recursive/delete, session delete, auth login/logout/
     refresh/token, link/unlink, context add/use/remove, agent
     invoke, chat, api, version) emit bare result objects. Risk
     classification dropped — the resource + exit code already
     convey the action.

Per-command shape changes:
   list / search       → []T   (was {ok, data:{items:[…]}})
   view                → T     (was {ok, data:T, _meta:…})
   create / edit       → T
   delete / pin / etc. → {id, …action result…}
   doctor              → {summary, checks}
   api                 → {status, headers, body}

_meta dropped on the read path:
   pagination (page/page_size/total/has_more) — agents iterate with
   --all-pages or accept --limit (gh CLI parity);
   kb_id / context echo — caller already knows what it asked for.

Acceptance contract goldens regenerated for the new bare shape.
Error envelope on stdout (PrintErrorEnvelope) stays live for now —
the envelope-infra deletion lands in the next commit.
This commit is contained in:
nullkey
2026-05-14 23:28:14 +08:00
committed by lyingbug
parent bdc589e1c0
commit cc8254f862
95 changed files with 579 additions and 911 deletions
+12 -39
View File
@@ -36,7 +36,6 @@ type UploadOptions struct {
Recursive bool // --recursive: positional arg is a directory; walk + upload each match
Glob string // --glob: filename pattern under --recursive (default "*")
FromURL string // --from-url: ingest a remote URL via SDK CreateKnowledgeFromURL
DryRun bool
}
// UploadService is the narrow SDK surface this command depends on.
@@ -85,7 +84,6 @@ Use --recursive --glob to upload a directory tree (see Examples).`,
if err != nil {
return err
}
opts.DryRun = cmdutil.IsDryRun(c)
if err := validateUploadFlags(opts, args); err != nil {
return err
}
@@ -93,17 +91,9 @@ Use --recursive --glob to upload a directory tree (see Examples).`,
if err != nil {
return err
}
// Resolve the SDK client once; dry-run paths take nil and never
// dereference it. Hoisting avoids three near-identical
// `cli, err := f.Client()` blocks across the dispatch branches.
var cli UploadService
if !opts.DryRun {
sdkCli, err := f.Client()
if err != nil {
return err
}
cli = sdkCli
cli, err := f.Client()
if err != nil {
return err
}
switch {
@@ -157,13 +147,6 @@ func validateUploadFlags(opts *UploadOptions, args []string) error {
// `--name` becomes the FileName hint so the server's "known file extension"
// detection upgrades crawl-mode to file-download-mode when appropriate.
func runUploadFromURL(ctx context.Context, opts *UploadOptions, jopts *cmdutil.JSONOptions, svc UploadService, kbID string) error {
if opts.DryRun {
return cmdutil.EmitDryRun(jopts.Enabled(),
map[string]string{"from_url": opts.FromURL, "kb_id": kbID, "name": opts.Name},
&format.Meta{KBID: kbID},
&format.Risk{Level: format.RiskWrite, Action: fmt.Sprintf("ingest URL %s into kb %s", opts.FromURL, kbID)})
}
req := sdk.CreateKnowledgeFromURLRequest{
URL: opts.FromURL,
FileName: opts.Name,
@@ -182,20 +165,17 @@ func runUploadFromURL(ctx context.Context, opts *UploadOptions, jopts *cmdutil.J
return cmdutil.WrapHTTP(err, "ingest URL %s", opts.FromURL)
}
return printUploadSuccess(k, jopts, kbID, "ingested", "Ingested", opts.FromURL, opts.Name, opts.FromURL)
return printUploadSuccess(k, jopts, "Ingested", opts.Name, opts.FromURL)
}
// printUploadSuccess emits the post-upload result envelope (--json path)
// or the human checkmark line. Shared by single-file upload and URL ingest;
// the verb (upload/ingest), risk-action verb (uploaded/ingested), and the
// fallback display source (local path vs source URL) are the only varying
// pieces.
func printUploadSuccess(k *sdk.Knowledge, jopts *cmdutil.JSONOptions, kbID, riskVerb, humanVerb, source, customName, fallbackDisplay string) error {
// printUploadSuccess emits the post-upload result. JSON path is the bare
// Knowledge object; human path prints a checkmark line. Shared by single-
// file upload and URL ingest; humanVerb varies (uploaded/ingested) and
// fallbackDisplay covers the case when the server-recorded file_name is
// blank (URL ingest pre-redirect).
func printUploadSuccess(k *sdk.Knowledge, jopts *cmdutil.JSONOptions, humanVerb, customName, fallbackDisplay string) error {
if jopts.Enabled() {
risk := &format.Risk{Level: format.RiskWrite, Action: fmt.Sprintf("%s %s", riskVerb, source)}
return format.WriteEnvelopeFiltered(iostreams.IO.Out,
format.SuccessWithRisk(k, &format.Meta{KBID: kbID}, risk),
jopts.Fields, jopts.JQ)
return format.WriteJSONFiltered(iostreams.IO.Out, k, jopts.Fields, jopts.JQ)
}
displayed := customName
if displayed == "" {
@@ -230,16 +210,9 @@ func validateUploadPath(path string) error {
}
func runUpload(ctx context.Context, opts *UploadOptions, jopts *cmdutil.JSONOptions, svc UploadService, kbID, path string) error {
if opts.DryRun {
return cmdutil.EmitDryRun(jopts.Enabled(),
map[string]string{"file": path, "kb_id": kbID, "name": opts.Name},
&format.Meta{KBID: kbID},
&format.Risk{Level: format.RiskWrite, Action: fmt.Sprintf("upload %s to kb %s", path, kbID)})
}
k, err := svc.CreateKnowledgeFromFile(ctx, kbID, path, nil /*metadata*/, nil /*enableMultimodel*/, opts.Name, uploadChannel)
if err != nil {
return cmdutil.WrapHTTP(err, "upload %s", path)
}
return printUploadSuccess(k, jopts, kbID, "uploaded", "Uploaded", path, opts.Name, path)
return printUploadSuccess(k, jopts, "Uploaded", opts.Name, path)
}