feat(cli): doc delete multi-id + api --paginate + paginate fixes + batch deletes

Batch-write surface and pagination consistency:

* weknora doc delete <doc-id> [<doc-id>...] — positional multi-id, default
  keep-going on failure. Single -y confirms entire batch.
* weknora session delete <session-id> [<session-id>...] — same shape.
* weknora chunk delete <chunk-id> [<chunk-id>...] --doc <doc-id> — multi-id
  with shared --doc parent.
* Multi-id partial-failure rolls up as operation.failed (exit 1), not
  server.error (exit 7) — failures are operation outcomes, not transient
  transport issues, and the retry-with-backoff hint for server.* would
  mislead callers.
* weknora api <path> --paginate — auto-walks offset pagination and merges
  pages into a single {data, total} JSON response.
* Paginate truncation fix across 6 list/follower call sites.
* All doc / search / chunk / session / kb list commands migrated to
  FormatOptions API.

Multi-id RunE only emits the {ok, failed} envelope when the operation
actually ran — pre-flight failures (e.g. confirmation_required) leave
stdout empty per the wire contract.

doc upload's missing-positional-or-flag check is wrapped as FlagError so
the exit code (2) matches the convention used by other commands that
require a positional argument directly.
This commit is contained in:
nullkey
2026-05-18 01:38:30 +08:00
committed by lyingbug
parent 0e081aec5c
commit 34bb0b5096
33 changed files with 1259 additions and 406 deletions
+103 -34
View File
@@ -3,6 +3,7 @@ package chunkcmd
import (
"context"
"fmt"
"io"
"github.com/spf13/cobra"
@@ -12,13 +13,12 @@ import (
)
// chunkDeleteFields enumerates the JSON discovery fields for `chunk delete`.
// Result payload is a tiny {id, deleted} object — mirrors `kb delete` /
// `agent delete`.
// Tracks the single-id result struct; multi-id mode emits MultiDeleteResult.
var chunkDeleteFields = []string{"id", "deleted"}
type DeleteOptions struct {
ChunkID string
DocID string // required: SDK DeleteChunk takes both ids in the route.
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
}
@@ -27,27 +27,44 @@ type DeleteService interface {
DeleteChunk(ctx context.Context, docID, chunkID string) error
}
// deleteResult is the typed payload emitted on success in JSON mode.
// deleteResult is the typed payload emitted on single-id success in JSON mode.
type deleteResult struct {
ID string `json:"id"`
Deleted bool `json:"deleted"`
}
// Delete is NOT idempotent on a missing id — it surfaces resource.not_found
// (exit 4). Idempotent-already-true semantics are reserved for `unlink`-style
// local cleanups, not server-side resource removal. Mirrors `agent delete`
// and `kb delete`.
const chunkDeleteLong = `Permanently delete a chunk from a document.
// MultiDeleteResult is the payload for multi-id deletes. All chunks share the
// same --doc parent (server route is DELETE /chunks/{doc}/{id}).
type MultiDeleteResult struct {
OK []string `json:"ok"`
Failed []FailedItem `json:"failed,omitempty"`
}
Requires both the chunk id (positional) and the parent document id
(--doc) because the server route encodes both: DELETE /chunks/{doc}/{id}.
The CLI does not auto-resolve doc id from the chunk id because doing so
would add a round-trip and open a race with the ingest pipeline (a chunk
could move between documents between resolve and delete).
// FailedItem records an id that failed to delete along with its error message.
type FailedItem struct {
ID string `json:"id"`
Code string `json:"code,omitempty"`
Message string `json:"message"`
}
Prompts for confirmation by default when stdout is a TTY and --json is
not set. Pass -y/--yes (the global flag) to skip the prompt (required in
agent / CI / piped contexts).
const chunkDeleteLong = `Permanently delete one or more chunks from a document.
Requires both the chunk id(s) (positional, repeatable) and the parent
document id (--doc) because the server route encodes both:
DELETE /chunks/{doc}/{id}. All chunks in a multi-id call must share the
same --doc. The CLI does not auto-resolve doc id from chunk id because
that would add a round-trip and open a race with the ingest pipeline
(a chunk could move between documents between resolve and delete).
Single-id: one confirm prompt, exit 0/1.
Multi-id:
• Default keep-going: failed deletes do NOT stop the run; failures collected.
• One -y/--yes confirms all chunks.
• Exit 0 if all succeed; exit 1 if any failed.
Prompts for confirmation by default when stdout is a TTY and JSON output
is not set. Pass -y/--yes (the global flag) to skip the prompt (required
in agent / CI / piped contexts).
Typed exit codes:
resource.not_found no chunk with the given id under that doc (exit 4)
@@ -59,49 +76,101 @@ and writes input.confirmation_required to stderr. NEVER auto-pass -y
without the user's explicit go-ahead — the exit-10 protocol exists
exactly to guard against unintended deletes.`
const chunkDeleteExample = ` weknora chunk delete chunk_abc --doc doc_xyz # interactive confirm
weknora chunk delete chunk_abc --doc doc_xyz -y # no prompt
weknora chunk delete chunk_abc --doc doc_xyz -y --json # bare {id, deleted:true} JSON`
const chunkDeleteExample = ` weknora chunk delete chunk_abc --doc doc_xyz # interactive confirm
weknora chunk delete chunk_abc --doc doc_xyz -y # no prompt
weknora chunk delete chunk_abc --doc doc_xyz -y --format json # bare {id, deleted:true} JSON
weknora chunk delete c1 c2 c3 --doc doc_xyz -y # delete 3 chunks under same doc, keep-going`
// NewCmdDelete builds `weknora chunk delete <chunk-id> --doc <doc-id>`.
// NewCmdDelete builds `weknora chunk delete <chunk-id> [<chunk-id>...] --doc <doc-id>`.
func NewCmdDelete(f *cmdutil.Factory) *cobra.Command {
opts := &DeleteOptions{}
cmd := &cobra.Command{
Use: "delete <chunk-id> --doc <doc-id>",
Short: "Delete a chunk from a document (scoped)",
Use: "delete <chunk-id> [<chunk-id>...] --doc <doc-id>",
Short: "Delete one or more chunks from a document (scoped)",
Long: chunkDeleteLong,
Example: chunkDeleteExample,
Args: cobra.ExactArgs(1),
Args: cobra.MinimumNArgs(1),
RunE: func(c *cobra.Command, args []string) error {
jopts, err := cmdutil.CheckJSONFlags(c)
fopts, err := cmdutil.CheckFormatFlag(c)
if err != nil {
return err
}
opts.ChunkID = args[0]
fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
opts.Yes, _ = c.Flags().GetBool("yes")
cli, err := f.Client()
if err != nil {
return err
}
return runDelete(c.Context(), opts, jopts, cli, f.Prompter())
if len(args) == 1 {
opts.ChunkID = args[0]
return runDelete(c.Context(), opts, fopts, cli, f.Prompter())
}
res, runErr := runMultiDelete(c.Context(), opts, fopts, cli, f.Prompter(), args)
// Only emit when the operation actually ran. Pre-flight errors
// (e.g. confirmation_required) must leave stdout empty per the
// wire contract in README.md.
if len(res.OK) > 0 || len(res.Failed) > 0 {
if emitErr := emitMultiDelete(res, fopts, iostreams.IO.Out); emitErr != nil {
return emitErr
}
}
return runErr
},
}
cmd.Flags().StringVar(&opts.DocID, "doc", "", "Parent document id (SDK knowledge_id) the chunk lives under")
cmd.Flags().StringVar(&opts.DocID, "doc", "", "Parent document id (SDK knowledge_id) the chunks live under")
_ = cmd.MarkFlagRequired("doc")
cmdutil.AddJSONFlags(cmd, chunkDeleteFields)
cmdutil.AddFormatFlag(cmd, chunkDeleteFields...)
return cmd
}
func runDelete(ctx context.Context, opts *DeleteOptions, jopts *cmdutil.JSONOptions, svc DeleteService, p prompt.Prompter) error {
if err := cmdutil.ConfirmDestructive(p, opts.Yes, jopts.Enabled(), "chunk", opts.ChunkID); err != nil {
func runDelete(ctx context.Context, opts *DeleteOptions, fopts *cmdutil.FormatOptions, svc DeleteService, p prompt.Prompter) error {
if err := cmdutil.ConfirmDestructive(p, opts.Yes, fopts.WantsJSON(), "chunk", opts.ChunkID); err != nil {
return err
}
if err := svc.DeleteChunk(ctx, opts.DocID, opts.ChunkID); err != nil {
return cmdutil.WrapHTTP(err, "delete chunk %s", opts.ChunkID)
}
if jopts.Enabled() {
return jopts.Emit(iostreams.IO.Out, deleteResult{ID: opts.ChunkID, Deleted: true})
if fopts.WantsJSON() {
return fopts.Emit(iostreams.IO.Out, deleteResult{ID: opts.ChunkID, Deleted: true})
}
fmt.Fprintf(iostreams.IO.Out, "✓ Deleted chunk %s\n", opts.ChunkID)
return nil
}
// runMultiDelete iterates chunkIDs sequentially under opts.DocID, keep-going
// on error: a single failure does not abort the run.
func runMultiDelete(ctx context.Context, opts *DeleteOptions, fopts *cmdutil.FormatOptions, svc DeleteService, p prompt.Prompter, chunkIDs []string) (*MultiDeleteResult, error) {
if err := cmdutil.ConfirmDestructiveBatch(p, opts.Yes, fopts.WantsJSON(), "chunk", len(chunkIDs)); err != nil {
return &MultiDeleteResult{}, err
}
res := &MultiDeleteResult{}
for _, id := range chunkIDs {
if err := svc.DeleteChunk(ctx, opts.DocID, id); err != nil {
res.Failed = append(res.Failed, FailedItem{ID: id, Message: err.Error()})
continue
}
res.OK = append(res.OK, id)
}
if len(res.Failed) > 0 {
return res, cmdutil.NewError(cmdutil.CodeOperationFailed, fmt.Sprintf("%d/%d delete(s) failed", len(res.Failed), len(chunkIDs)))
}
return res, nil
}
// emitMultiDelete renders per --format. Mirrors doc / session delete.
func emitMultiDelete(res *MultiDeleteResult, fopts *cmdutil.FormatOptions, w io.Writer) error {
switch fopts.Mode {
case cmdutil.FormatJSON, cmdutil.FormatNDJSON:
return fopts.Emit(w, res)
case cmdutil.FormatText, "":
for _, id := range res.OK {
fmt.Fprintf(w, "OK %s\n", id)
}
for _, f := range res.Failed {
fmt.Fprintf(w, "FAIL %s: %s\n", f.ID, f.Message)
}
return nil
default:
return fmt.Errorf("unsupported --format %q for chunk delete", fopts.Mode)
}
}
+72 -6
View File
@@ -29,7 +29,7 @@ func TestDelete_NonTTY_NoYes_ExitTen(t *testing.T) {
svc := &fakeChunkDeleteSvc{}
err := runDelete(context.Background(),
&DeleteOptions{ChunkID: "c1", DocID: "doc_abc", Yes: false},
&cmdutil.JSONOptions{}, svc, &testutil.ConfirmPrompter{})
&cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc, &testutil.ConfirmPrompter{})
require.Error(t, err)
var typed *cmdutil.Error
require.ErrorAs(t, err, &typed)
@@ -43,7 +43,7 @@ func TestDelete_WithYes_PassesBothIDs(t *testing.T) {
svc := &fakeChunkDeleteSvc{}
require.NoError(t, runDelete(context.Background(),
&DeleteOptions{ChunkID: "c1", DocID: "doc_abc", Yes: true},
&cmdutil.JSONOptions{}, svc, &testutil.ConfirmPrompter{}))
&cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc, &testutil.ConfirmPrompter{}))
assert.Equal(t, "doc_abc", svc.gotDocID)
assert.Equal(t, "c1", svc.gotChunkID)
}
@@ -61,7 +61,7 @@ func TestDelete_404_PropagatesNotFound(t *testing.T) {
svc := &fakeChunkDeleteSvc{err: errors.New("HTTP error 404: not found")}
err := runDelete(context.Background(),
&DeleteOptions{ChunkID: "missing", DocID: "doc_abc", Yes: true},
&cmdutil.JSONOptions{}, svc, &testutil.ConfirmPrompter{})
&cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc, &testutil.ConfirmPrompter{})
require.Error(t, err)
var typed *cmdutil.Error
require.ErrorAs(t, err, &typed)
@@ -74,7 +74,7 @@ func TestDelete_TTY_ConfirmYes_Calls(t *testing.T) {
p := &testutil.ConfirmPrompter{Answer: true}
require.NoError(t, runDelete(context.Background(),
&DeleteOptions{ChunkID: "c1", DocID: "doc_abc"},
nil, svc, p))
&cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc, p))
assert.True(t, p.Asked)
assert.Equal(t, "c1", svc.gotChunkID)
}
@@ -85,7 +85,7 @@ func TestDelete_TTY_ConfirmNo_Aborts(t *testing.T) {
p := &testutil.ConfirmPrompter{Answer: false}
err := runDelete(context.Background(),
&DeleteOptions{ChunkID: "c1", DocID: "doc_abc"},
nil, svc, p)
&cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc, p)
require.Error(t, err)
var typed *cmdutil.Error
require.ErrorAs(t, err, &typed)
@@ -99,8 +99,74 @@ func TestDelete_JSON_BareObject(t *testing.T) {
svc := &fakeChunkDeleteSvc{}
require.NoError(t, runDelete(context.Background(),
&DeleteOptions{ChunkID: "c1", DocID: "doc_abc", Yes: true},
&cmdutil.JSONOptions{}, svc, &testutil.ConfirmPrompter{}))
&cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc, &testutil.ConfirmPrompter{}))
body := out.String()
assert.Contains(t, body, `"id":"c1"`)
assert.Contains(t, body, `"deleted":true`)
}
// ---------------------------------------------------------------------------
// Multi-id (all chunks share --doc, keep-going on failure)
// ---------------------------------------------------------------------------
// fakeMultiChunkDeleteSvc records (docID, chunkID) pairs and can fail-on
// selected chunkIDs.
type fakeMultiChunkDeleteSvc struct {
deleted []string // chunk ids successfully deleted
docIDs []string // doc id observed for each call
failOn map[string]error
}
func (f *fakeMultiChunkDeleteSvc) DeleteChunk(_ context.Context, docID, chunkID string) error {
f.docIDs = append(f.docIDs, docID)
if e, ok := f.failOn[chunkID]; ok {
return e
}
f.deleted = append(f.deleted, chunkID)
return nil
}
func TestMultiDelete_AllSucceed_SharedDoc(t *testing.T) {
_, _ = iostreams.SetForTest(t)
svc := &fakeMultiChunkDeleteSvc{}
res, err := runMultiDelete(context.Background(),
&DeleteOptions{DocID: "doc_xyz", Yes: true}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc, &testutil.ConfirmPrompter{},
[]string{"c1", "c2", "c3"})
require.NoError(t, err)
assert.Equal(t, []string{"c1", "c2", "c3"}, res.OK)
assert.Empty(t, res.Failed)
// All calls observed the same --doc.
for _, d := range svc.docIDs {
assert.Equal(t, "doc_xyz", d)
}
}
func TestMultiDelete_PartialFailure_KeepsGoing(t *testing.T) {
_, _ = iostreams.SetForTest(t)
svc := &fakeMultiChunkDeleteSvc{failOn: map[string]error{"c2": errors.New("HTTP error 404: not found")}}
res, err := runMultiDelete(context.Background(),
&DeleteOptions{DocID: "doc_xyz", Yes: true}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc, &testutil.ConfirmPrompter{},
[]string{"c1", "c2", "c3"})
require.Error(t, err)
var typed *cmdutil.Error
require.ErrorAs(t, err, &typed)
assert.Equal(t, cmdutil.CodeOperationFailed, typed.Code)
assert.Equal(t, []string{"c1", "c3"}, res.OK, "keep-going: c3 still attempted after c2 failed")
assert.Len(t, res.Failed, 1)
assert.Equal(t, "c2", res.Failed[0].ID)
}
func TestMultiDelete_NonTTY_NoYes_RequiresConfirmation(t *testing.T) {
_, _ = iostreams.SetForTest(t)
svc := &fakeMultiChunkDeleteSvc{}
res, err := runMultiDelete(context.Background(),
&DeleteOptions{DocID: "doc_xyz"}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc, &testutil.ConfirmPrompter{},
[]string{"c1", "c2"})
require.Error(t, err)
var typed *cmdutil.Error
require.ErrorAs(t, err, &typed)
assert.Equal(t, cmdutil.CodeInputConfirmationRequired, typed.Code)
assert.Equal(t, 10, cmdutil.ExitCode(err))
assert.Empty(t, res.OK)
assert.Empty(t, svc.deleted)
}
+11 -10
View File
@@ -22,7 +22,7 @@ const (
previewWidth = 80
)
// chunkListFields enumerates the fields surfaced for `--json` discovery on
// chunkListFields enumerates the fields surfaced for `--format json` discovery on
// `chunk list`. Mirrors sdk.Chunk json tags — all 23 fields are projectable
// because chunk list returns bare SDK objects.
var chunkListFields = []string{
@@ -48,7 +48,7 @@ type ListOptions struct {
// Default 50 chosen as domain-tuned for chunk enumeration (RAG debug).
Limit int
// AllPages walks server pages internally until total exhausted or
// --limit hit. Mirrors session list / doc list canon.
// --limit hit. Mirrors the session list / doc list pagination pattern.
AllPages bool
}
@@ -73,7 +73,7 @@ specific document.`
const chunkListExample = ` weknora chunk list --doc doc_abc
weknora chunk list --doc doc_abc --all-pages --page-size 100
weknora chunk list --doc doc_abc --json | jq '.[] | {id, chunk_index}'`
weknora chunk list --doc doc_abc --format json | jq '.[] | {id, chunk_index}'`
// NewCmdList builds `weknora chunk list --doc <doc-id>`.
func NewCmdList(f *cmdutil.Factory) *cobra.Command {
@@ -85,15 +85,16 @@ func NewCmdList(f *cmdutil.Factory) *cobra.Command {
Example: chunkListExample,
Args: cobra.NoArgs,
RunE: func(c *cobra.Command, _ []string) error {
jopts, err := cmdutil.CheckJSONFlags(c)
fopts, err := cmdutil.CheckFormatFlag(c)
if err != nil {
return err
}
fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
cli, err := f.Client()
if err != nil {
return err
}
return runList(c.Context(), opts, jopts, cli)
return runList(c.Context(), opts, fopts, cli)
},
}
cmd.Flags().StringVar(&opts.DocID, "doc", "", "Document id (SDK knowledge_id) to enumerate chunks for")
@@ -101,11 +102,11 @@ func NewCmdList(f *cmdutil.Factory) *cobra.Command {
cmd.Flags().IntVarP(&opts.Limit, "limit", "L", defaultLimit, "Maximum results to return (1..1000)")
cmd.Flags().IntVar(&opts.PageSize, "page-size", defaultPageSize, "Items per server batch (1..1000)")
cmd.Flags().BoolVar(&opts.AllPages, "all-pages", false, "Walk all server pages until exhausted (or --limit hit)")
cmdutil.AddJSONFlags(cmd, chunkListFields)
cmdutil.AddFormatFlag(cmd, chunkListFields...)
return cmd
}
func runList(ctx context.Context, opts *ListOptions, jopts *cmdutil.JSONOptions, svc ListService) error {
func runList(ctx context.Context, opts *ListOptions, fopts *cmdutil.FormatOptions, svc ListService) error {
if opts.Limit < 1 || opts.Limit > maxLimit {
return &cmdutil.Error{
Code: cmdutil.CodeInputInvalidArgument,
@@ -132,7 +133,7 @@ func runList(ctx context.Context, opts *ListOptions, jopts *cmdutil.JSONOptions,
accum = accum[:opts.Limit]
break
}
if len(chunks) == 0 || int64(page*opts.PageSize) >= total {
if len(chunks) == 0 || int64(len(accum)) >= total {
break
}
}
@@ -151,8 +152,8 @@ func runList(ctx context.Context, opts *ListOptions, jopts *cmdutil.JSONOptions,
items = items[:opts.Limit]
}
if jopts.Enabled() {
return jopts.Emit(iostreams.IO.Out, items)
if fopts.WantsJSON() {
return fopts.Emit(iostreams.IO.Out, items)
}
if len(items) == 0 {
+10 -10
View File
@@ -47,7 +47,7 @@ func TestList_Happy(t *testing.T) {
totals: []int64{2}, errs: []error{nil},
}
opts := &ListOptions{DocID: "doc_abc", Limit: 50, PageSize: 50}
require.NoError(t, runList(context.Background(), opts, &cmdutil.JSONOptions{}, svc))
require.NoError(t, runList(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc))
require.Len(t, svc.calls, 1)
assert.Equal(t, "doc_abc", svc.calls[0].docID)
assert.Equal(t, 1, svc.calls[0].page)
@@ -75,7 +75,7 @@ func TestList_AllPages_StopsOnEmptyPage(t *testing.T) {
errs: []error{nil, nil, nil},
}
opts := &ListOptions{DocID: "doc_abc", AllPages: true, PageSize: 2, Limit: 1000}
require.NoError(t, runList(context.Background(), opts, &cmdutil.JSONOptions{}, svc))
require.NoError(t, runList(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc))
assert.Equal(t, 3, len(svc.calls), "must stop on empty page, not loop forever")
}
@@ -93,7 +93,7 @@ func TestList_AllPages_StopsOnTotalExhausted(t *testing.T) {
errs: []error{nil, nil},
}
opts := &ListOptions{DocID: "doc_abc", AllPages: true, PageSize: 2, Limit: 1000}
require.NoError(t, runList(context.Background(), opts, &cmdutil.JSONOptions{}, svc))
require.NoError(t, runList(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc))
// After page 2: page*pageSize=4 >= total=3 → stop. No 3rd request.
assert.Equal(t, 2, len(svc.calls), "must stop when total exhausted, no extra empty probe")
}
@@ -113,7 +113,7 @@ func TestList_AllPages_LimitTruncatesAccumulated(t *testing.T) {
errs: []error{nil, nil, nil},
}
opts := &ListOptions{DocID: "doc_abc", AllPages: true, PageSize: 2, Limit: 3}
require.NoError(t, runList(context.Background(), opts, &cmdutil.JSONOptions{}, svc))
require.NoError(t, runList(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc))
// After page 2: accum=4 >= limit=3 → stop. Third page never requested.
assert.LessOrEqual(t, len(svc.calls), 2, "must not walk past limit-hit point")
// Result must be exactly --limit items (server returned 4, sliced to 3).
@@ -127,7 +127,7 @@ func TestList_AllPages_LimitTruncatesAccumulated(t *testing.T) {
func TestList_LimitInvalid(t *testing.T) {
svc := &fakeListSvc{}
for _, lim := range []int{0, -1, 1001} {
err := runList(context.Background(), &ListOptions{DocID: "d", Limit: lim, PageSize: 50}, &cmdutil.JSONOptions{}, svc)
err := runList(context.Background(), &ListOptions{DocID: "d", Limit: lim, PageSize: 50}, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc)
require.Error(t, err, "expect error for --limit %d", lim)
assert.Contains(t, err.Error(), "input.invalid_argument")
}
@@ -136,7 +136,7 @@ func TestList_LimitInvalid(t *testing.T) {
func TestList_PageSizeInvalid(t *testing.T) {
svc := &fakeListSvc{}
for _, ps := range []int{0, -1, 1001} {
err := runList(context.Background(), &ListOptions{DocID: "d", Limit: 50, PageSize: ps}, &cmdutil.JSONOptions{}, svc)
err := runList(context.Background(), &ListOptions{DocID: "d", Limit: 50, PageSize: ps}, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc)
require.Error(t, err)
assert.Contains(t, err.Error(), "input.invalid_argument")
}
@@ -158,7 +158,7 @@ func TestList_Human_TableHeader(t *testing.T) {
}},
totals: []int64{1}, errs: []error{nil},
}
require.NoError(t, runList(context.Background(), &ListOptions{DocID: "doc_abc", Limit: 50, PageSize: 50}, nil, svc))
require.NoError(t, runList(context.Background(), &ListOptions{DocID: "doc_abc", Limit: 50, PageSize: 50}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc))
body := out.String()
for _, want := range []string{"CHUNK_ID", "INDEX", "TYPE", "ENABLED", "PREVIEW", "UPDATED", "c1", "text"} {
assert.Contains(t, body, want)
@@ -172,7 +172,7 @@ func TestList_Human_PreviewTruncatedTo80(t *testing.T) {
pages: [][]sdk.Chunk{{{ID: "c1", Content: long, ChunkType: "text", IsEnabled: true}}},
totals: []int64{1}, errs: []error{nil},
}
require.NoError(t, runList(context.Background(), &ListOptions{DocID: "doc_abc", Limit: 50, PageSize: 50}, nil, svc))
require.NoError(t, runList(context.Background(), &ListOptions{DocID: "doc_abc", Limit: 50, PageSize: 50}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc))
body := out.String()
// 80-col preview means we never see the 100th `a` from the content (only column truncation kicks in).
assert.NotContains(t, body, strings.Repeat("a", 100), "preview must be truncated to ~80 chars")
@@ -186,7 +186,7 @@ func TestList_JSON_BareArray(t *testing.T) {
}},
totals: []int64{1}, errs: []error{nil},
}
require.NoError(t, runList(context.Background(), &ListOptions{DocID: "doc_abc", Limit: 50, PageSize: 50}, &cmdutil.JSONOptions{}, svc))
require.NoError(t, runList(context.Background(), &ListOptions{DocID: "doc_abc", Limit: 50, PageSize: 50}, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc))
var got []sdk.Chunk
require.NoError(t, json.Unmarshal(out.Bytes(), &got))
require.Len(t, got, 1)
@@ -200,6 +200,6 @@ func TestList_JSON_BareArray(t *testing.T) {
func TestList_EmptyResultRendersBareArray(t *testing.T) {
out, _ := iostreams.SetForTest(t)
svc := &fakeListSvc{pages: [][]sdk.Chunk{{}}, totals: []int64{0}, errs: []error{nil}}
require.NoError(t, runList(context.Background(), &ListOptions{DocID: "doc_abc", Limit: 50, PageSize: 50}, &cmdutil.JSONOptions{}, svc))
require.NoError(t, runList(context.Background(), &ListOptions{DocID: "doc_abc", Limit: 50, PageSize: 50}, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc))
assert.Equal(t, "[]\n", out.String())
}
+12 -11
View File
@@ -12,7 +12,7 @@ import (
sdk "github.com/Tencent/WeKnora/client"
)
// chunkViewFields enumerates the 23 SDK Chunk fields surfaced for `--json`
// chunkViewFields enumerates the 23 SDK Chunk fields surfaced for `--format json`
// discovery. JSON is bare SDK pass-through, so keys are snake_case
// (`knowledge_id`, `knowledge_base_id`) even though the human KV labels
// them as `doc_id` / `kb_id`.
@@ -35,9 +35,9 @@ type ViewOptions struct {
const chunkViewLong = `Show a single chunk with all SDK fields.
Human output is a key-value block; pass --json for the bare 23-field SDK
Human output is a key-value block; pass --format json for the bare 23-field SDK
Chunk object. Content renders verbatim regardless of size — pipe to
less or use --json for large chunks. WeKnora chunks are typically bounded
less or use --format json for large chunks. WeKnora chunks are typically bounded
by the ingest pipeline (~1000 tokens / a few KB), so unconditional full
rendering is reasonable.
@@ -54,8 +54,8 @@ Typed exit codes:
resource.not_found no chunk with the given id (exit 4)`
const chunkViewExample = ` weknora chunk view chunk_abc
weknora chunk view chunk_abc --json | jq '.content'
weknora chunk view chunk_abc --json=id,chunk_index,is_enabled`
weknora chunk view chunk_abc --format json | jq '.content'
weknora chunk view chunk_abc --format json --jq '{id, chunk_index, is_enabled}'`
// NewCmdView builds `weknora chunk view <chunk-id>`.
func NewCmdView(f *cmdutil.Factory) *cobra.Command {
@@ -67,29 +67,30 @@ func NewCmdView(f *cmdutil.Factory) *cobra.Command {
Example: chunkViewExample,
Args: cobra.ExactArgs(1),
RunE: func(c *cobra.Command, args []string) error {
jopts, err := cmdutil.CheckJSONFlags(c)
fopts, err := cmdutil.CheckFormatFlag(c)
if err != nil {
return err
}
fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
opts.ChunkID = args[0]
cli, err := f.Client()
if err != nil {
return err
}
return runView(c.Context(), opts, jopts, cli)
return runView(c.Context(), opts, fopts, cli)
},
}
cmdutil.AddJSONFlags(cmd, chunkViewFields)
cmdutil.AddFormatFlag(cmd, chunkViewFields...)
return cmd
}
func runView(ctx context.Context, opts *ViewOptions, jopts *cmdutil.JSONOptions, svc ViewService) error {
func runView(ctx context.Context, opts *ViewOptions, fopts *cmdutil.FormatOptions, svc ViewService) error {
ch, err := svc.GetChunkByIDOnly(ctx, opts.ChunkID)
if err != nil {
return cmdutil.WrapHTTP(err, "fetch chunk %s", opts.ChunkID)
}
if jopts.Enabled() {
return jopts.Emit(iostreams.IO.Out, ch)
if fopts.WantsJSON() {
return fopts.Emit(iostreams.IO.Out, ch)
}
renderChunk(iostreams.IO.Out, ch)
return nil
+6 -6
View File
@@ -37,7 +37,7 @@ func TestView_Happy_RendersAllFields(t *testing.T) {
CreatedAt: "2026-05-15T11:00:00Z",
UpdatedAt: "2026-05-15T12:00:00Z",
}}
require.NoError(t, runView(context.Background(), &ViewOptions{ChunkID: "c1"}, nil, svc))
require.NoError(t, runView(context.Background(), &ViewOptions{ChunkID: "c1"}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc))
body := out.String()
assert.Contains(t, body, "c1")
assert.Contains(t, body, "doc_abc")
@@ -51,10 +51,10 @@ func TestView_HumanLabels_DocAndKB(t *testing.T) {
svc := &fakeViewSvc{resp: &sdk.Chunk{
ID: "c1", KnowledgeID: "doc_abc", KnowledgeBaseID: "kb_abc",
}}
require.NoError(t, runView(context.Background(), &ViewOptions{ChunkID: "c1"}, nil, svc))
require.NoError(t, runView(context.Background(), &ViewOptions{ChunkID: "c1"}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc))
body := out.String()
// Human KV uses friendlier DOC_ID / KB_ID labels (the SDK's
// knowledge_id / knowledge_base_id are kept only in --json output).
// knowledge_id / knowledge_base_id are kept only in --format json output).
assert.Contains(t, body, "doc_id")
assert.Contains(t, body, "kb_id")
assert.NotContains(t, body, "knowledge_id")
@@ -64,7 +64,7 @@ func TestView_HumanLabels_DocAndKB(t *testing.T) {
func TestView_OmitsZeroOrEmpty(t *testing.T) {
out, _ := iostreams.SetForTest(t)
svc := &fakeViewSvc{resp: &sdk.Chunk{ID: "c_min", Content: "x"}}
require.NoError(t, runView(context.Background(), &ViewOptions{ChunkID: "c_min"}, nil, svc))
require.NoError(t, runView(context.Background(), &ViewOptions{ChunkID: "c_min"}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc))
body := out.String()
// status / start_at / end_at all zero → must be omitted from the human KV.
assert.NotContains(t, body, "status:")
@@ -80,7 +80,7 @@ func TestView_JSON_BareSDKShape(t *testing.T) {
svc := &fakeViewSvc{resp: &sdk.Chunk{
ID: "c_json", KnowledgeID: "doc_abc", KnowledgeBaseID: "kb_abc",
}}
require.NoError(t, runView(context.Background(), &ViewOptions{ChunkID: "c_json"}, &cmdutil.JSONOptions{}, svc))
require.NoError(t, runView(context.Background(), &ViewOptions{ChunkID: "c_json"}, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc))
var got sdk.Chunk
require.NoError(t, json.Unmarshal(out.Bytes(), &got))
assert.Equal(t, "c_json", got.ID)
@@ -95,7 +95,7 @@ func TestView_JSON_BareSDKShape(t *testing.T) {
func TestView_404(t *testing.T) {
_, _ = iostreams.SetForTest(t)
svc := &fakeViewSvc{err: errors.New("HTTP error 404: not found")}
err := runView(context.Background(), &ViewOptions{ChunkID: "missing"}, nil, svc)
err := runView(context.Background(), &ViewOptions{ChunkID: "missing"}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc)
require.Error(t, err)
assert.Contains(t, err.Error(), "resource.not_found")
}