WeKnora deployment source with the reviewed wiki identity, summary and recovery fixes

cli/cmd/search/docs.go

@@ -0,0 +1,196 @@
+package search
+
+import (
+	"context"
+	"fmt"
+	"sort"
+	"strings"
+	"text/tabwriter"
+
+	"github.com/spf13/cobra"
+
+	"github.com/Tencent/WeKnora/cli/internal/cmdutil"
+	"github.com/Tencent/WeKnora/cli/internal/iostreams"
+	"github.com/Tencent/WeKnora/cli/internal/output"
+	"github.com/Tencent/WeKnora/cli/internal/text"
+	sdk "github.com/Tencent/WeKnora/client"
+)
+
+// docsPageSize is the default --page-size on `search docs`: how many
+// entries to pull per ListKnowledgeWithFilter round-trip. The server
+// applies the keyword filter pre-pagination, so most KBs return in a
+// single page even at conservative sizes. Server caps page_size at 1000.
+const docsPageSize = 200
+
+// docsMaxPageSize bounds the --page-size flag, matching the session/doc list cap.
+const docsMaxPageSize = 1000
+
+// docsFields enumerates the fields surfaced for `--format json` discovery on
+// `search docs`. Mirrors sdk.Knowledge json tags.
+var docsFields = []string{
+	"id", "tenant_id", "knowledge_base_id", "tag_id", "type", "title",
+	"description", "source", "channel", "parse_status", "summary_status",
+	"enable_status", "embedding_model_id", "file_name", "file_type",
+	"file_size", "file_hash", "file_path", "storage_size", "metadata",
+	"created_at", "updated_at", "processed_at", "error_message",
+}
+
+type DocsSearchOptions struct {
+	Query string
+	KB    string // raw --kb (UUID or name)
+	KBID  string // resolved id; populated before listing
+	Limit int
+	// PageSize is the server batch size per ListKnowledgeWithFilter call
+	// (1..1000, default 200). Tunable so a caller searching a small KB
+	// can fetch everything in one round-trip, or a caller on flaky
+	// network can shorten the batch.
+	PageSize int
+	// AllPages walks server pages internally until total exhausted or
+	// --limit accumulated. Default true; setting false stops after the
+	// first page (useful for cheap previews).
+	AllPages bool
+}
+
+// DocsSearchService is the narrow SDK surface this command depends on.
+// The server applies the keyword filter pre-pagination via the
+// ?keyword= query param, so the CLI just forwards opts.Query as
+// filter.Keyword and accumulates the (already-filtered) pages.
+type DocsSearchService interface {
+	ListKnowledgeWithFilter(ctx context.Context, kbID string, page, pageSize int, filter sdk.KnowledgeListFilter) ([]sdk.Knowledge, int64, error)
+}
+
+// NewCmdDocs builds `weknora search docs "<query>" --kb <id-or-name>`.
+// Pages through the KB's documents and surfaces every entry whose title
+// or file_name contains the query as a server-side case-insensitive LIKE
+// match. Useful for finding a specific upload to download or delete.
+func NewCmdDocs(f *cmdutil.Factory) *cobra.Command {
+	opts := &DocsSearchOptions{}
+	cmd := &cobra.Command{
+		Use:   `docs "<query>"`,
+		Short: "Find documents in a knowledge base by keyword (server-side filter)",
+		Long: `Pages through the KB's documents, forwarding the query as the server-side
+keyword filter (matched against title / file_name). Useful for finding a
+specific upload to download or delete by id.
+
+The query is a case-insensitive server-side LIKE filter (the server runs
+` + "`LOWER(...) LIKE LOWER('%keyword%')`" + ` against title and file_name), so
+` + "`FALCON`" + ` and ` + "`falcon`" + ` match the same documents.
+
+By default, --all-pages=true walks every server page until --limit is
+reached or the KB is exhausted. Pass --all-pages=false to stop after one page.`,
+		Example: `  weknora search docs "Q3 forecast" --kb finance
+  weknora search docs "spec" --kb engineering --limit 5
+  weknora search docs "spec" --kb engineering --all-pages=false`,
+		Args: cobra.ExactArgs(1),
+		RunE: func(c *cobra.Command, args []string) error {
+			opts.Query = strings.TrimSpace(args[0])
+			if opts.Query == "" {
+				return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, "query argument cannot be empty")
+			}
+			if opts.Limit < 1 || opts.Limit > 1000 {
+				return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, "--limit must be between 1 and 1000")
+			}
+			fopts, err := cmdutil.CheckFormatFlag(c)
+			if err != nil {
+				return err
+			}
+			fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
+			// Resolve KB via the shared flag→env→project-link chain (same as
+			// `doc list` / `chat`), so a linked directory or WEKNORA_KB_ID
+			// works without an explicit --kb. Resolve before building the
+			// client so an unresolved KB short-circuits to local.kb_id_required
+			// without a client round-trip.
+			kbID, err := f.ResolveKB(c)
+			if err != nil {
+				return err
+			}
+			opts.KBID = kbID
+			cli, err := f.Client()
+			if err != nil {
+				return err
+			}
+			return runDocsSearch(c.Context(), opts, fopts, cli)
+		},
+	}
+	cmd.Flags().StringVar(&opts.KB, "kb", "", "Knowledge base UUID or name (overrides env / project link)")
+	cmd.Flags().IntVarP(&opts.Limit, "limit", "L", 30, "Maximum results to return")
+	cmd.Flags().IntVar(&opts.PageSize, "page-size", docsPageSize, "Items per server batch (1..1000)")
+	cmd.Flags().BoolVar(&opts.AllPages, "all-pages", true, "Walk every server page until exhausted or --limit hit")
+	cmdutil.AddFormatFlag(cmd, docsFields...)
+	cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
+		UsedFor:       "Find documents in a knowledge base by keyword (server-side LIKE filter on title/file_name). The KB comes from --kb (id or name), else WEKNORA_KB_ID, else the linked directory. Results come with meta.count; use --limit to cap and --all-pages=false to stop after one page.",
+		RequiredFlags: []string{"<query> (positional)", "--kb (or WEKNORA_KB_ID / linked directory)"},
+		Examples:      []string{`weknora search docs "spec" --kb engineering --format json`},
+		Output:        "envelope.data is an array of Knowledge objects with id, title, file_name, parse_status; meta.count is the returned count, meta.total_count the server's full match count, meta.has_more=true if more matched than --limit",
+	})
+	return cmd
+}
+
+func runDocsSearch(ctx context.Context, opts *DocsSearchOptions, fopts *cmdutil.FormatOptions, svc DocsSearchService) error {
+	if opts.PageSize < 1 || opts.PageSize > docsMaxPageSize {
+		return cmdutil.NewError(cmdutil.CodeInputInvalidArgument,
+			fmt.Sprintf("--page-size must be in 1..%d, got %d", docsMaxPageSize, opts.PageSize))
+	}
+	filter := sdk.KnowledgeListFilter{Keyword: opts.Query}
+	var matches []sdk.Knowledge
+
+	// Page through the KB until limit matches found or pagination exhausted.
+	// The server applies the keyword filter pre-pagination, so every item
+	// returned is already a match - no client-side filter needed.
+	// --all-pages=true (default) walks every server page; --all-pages=false
+	// stops after the first page. Termination counts records actually
+	// received so server-capped page_size doesn't truncate.
+	var serverTotal int64
+	for page := 1; ; page++ {
+		items, total, err := svc.ListKnowledgeWithFilter(ctx, opts.KBID, page, opts.PageSize, filter)
+		if err != nil {
+			return cmdutil.WrapHTTP(err, "list documents")
+		}
+		serverTotal = total
+		for _, k := range items {
+			matches = append(matches, k)
+			// Collect one past --limit so has_more is accurate; trimmed below.
+			if opts.Limit > 0 && len(matches) > opts.Limit {
+				goto done
+			}
+		}
+		if !opts.AllPages {
+			break
+		}
+		if int64(len(matches)) >= total || len(items) == 0 {
+			break
+		}
+	}
+done:
+	sortKnowledgeByRecency(matches)
+	truncated := opts.Limit > 0 && len(matches) > opts.Limit
+	if truncated {
+		matches = matches[:opts.Limit]
+	}
+
+	if fopts.WantsJSON() {
+		if matches == nil {
+			matches = []sdk.Knowledge{}
+		}
+		meta := &output.Meta{Count: output.IntPtr(len(matches)), TotalCount: output.IntPtr(int(serverTotal)), HasMore: truncated, Hint: emptyContentSearchHint(len(matches))}
+		return fopts.Emit(iostreams.IO.Out, matches, meta)
+	}
+	if len(matches) == 0 {
+		fmt.Fprintln(iostreams.IO.Out, "(no matches)")
+		return nil
+	}
+	tw := tabwriter.NewWriter(iostreams.IO.Out, 0, 0, 2, ' ', 0)
+	fmt.Fprintln(tw, "ID\tFILE\tTYPE\tUPDATED")
+	for _, k := range matches {
+		name := text.Truncate(50, text.KnowledgeDisplayName(k.FileName, k.Title, k.ID))
+		fmt.Fprintf(tw, "%s\t%s\t%s\t%s\n", k.ID, name, k.FileType, k.UpdatedAt.Format("2006-01-02"))
+	}
+	return tw.Flush()
+}
+
+// sortKnowledgeByRecency sorts in place by UpdatedAt desc.
+func sortKnowledgeByRecency(items []sdk.Knowledge) {
+	sort.Slice(items, func(i, j int) bool {
+		return items[i].UpdatedAt.After(items[j].UpdatedAt)
+	})
+}