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

cli/cmd/kb/pin.go

@@ -0,0 +1,137 @@
+package kb
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/spf13/cobra"
+
+	"github.com/Tencent/WeKnora/cli/internal/cmdutil"
+	"github.com/Tencent/WeKnora/cli/internal/iostreams"
+	sdk "github.com/Tencent/WeKnora/client"
+)
+
+// kbPinFields enumerates the fields surfaced for `--format json` discovery on
+// `kb pin` / `kb unpin`. The toggle result is the KnowledgeBase; the user-
+// relevant fields here are the id and the new pin state.
+var kbPinFields = []string{"id", "is_pinned"}
+
+type PinOptions struct {
+	DryRun bool
+}
+
+// PinService is the narrow SDK surface this command depends on. The CLI
+// reads current state before toggling so `pin`/`unpin` are idempotent — the
+// server endpoint is only a toggle. Pin state is read from the LIST endpoint:
+// the single-KB GET does not carry per-user pin state (pin is a per-user
+// list-ordering preference, surfaced where the user sees it — in `kb list`),
+// so the list is the canonical source.
+type PinService interface {
+	ListKnowledgeBases(ctx context.Context) ([]sdk.KnowledgeBase, error)
+	TogglePinKnowledgeBase(ctx context.Context, id string) (*sdk.KnowledgeBase, error)
+}
+
+// NewCmdPin builds `weknora kb pin <id>`.
+func NewCmdPin(f *cmdutil.Factory) *cobra.Command {
+	return newPinCmd(f, "pin", true, "Pin a knowledge base to the top of the list")
+}
+
+// NewCmdUnpin builds `weknora kb unpin <id>`.
+func NewCmdUnpin(f *cmdutil.Factory) *cobra.Command {
+	return newPinCmd(f, "unpin", false, "Unpin a knowledge base")
+}
+
+func newPinCmd(f *cmdutil.Factory, use string, want bool, short string) *cobra.Command {
+	opts := &PinOptions{}
+	cmd := &cobra.Command{
+		Use:   use + " <kb-id>",
+		Short: short,
+		Long:  short + ". Idempotent: reads the current pin state and toggles only if different, so re-running on a KB already in the target state is a no-op.",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(c *cobra.Command, args []string) error {
+			fopts, err := cmdutil.CheckFormatFlag(c)
+			if err != nil {
+				return err
+			}
+			fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
+			action := "kb.pin"
+			if !want {
+				action = "kb.unpin"
+			}
+			if handled, err := cmdutil.HandleDryRun(c, opts.DryRun, cmdutil.DryRunPlan{
+				Action: action,
+				Args:   map[string]any{"kb": args[0]},
+			}); handled {
+				return err
+			}
+			cli, err := f.Client()
+			if err != nil {
+				return err
+			}
+			return runPin(c.Context(), opts, fopts, cli, args[0], want)
+		},
+	}
+	cmdutil.AddFormatFlag(cmd, kbPinFields...)
+	cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
+	cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
+		UsedFor:       use + " a knowledge base (idempotent: a no-op if it is already in the target state)",
+		RequiredFlags: []string{"<kb-id> (positional)"},
+		Examples:      []string{"weknora kb " + use + " kb_abc"},
+		Output:        "envelope.data is the KnowledgeBase with is_pinned reflecting the new state",
+	})
+	return cmd
+}
+
+func runPin(ctx context.Context, opts *PinOptions, fopts *cmdutil.FormatOptions, svc PinService, id string, want bool) error {
+	verb := "pin"
+	if !want {
+		verb = "unpin"
+	}
+	// Read the current pin state from the list (the canonical per-user pin
+	// source); the single-KB GET doesn't carry it. This makes pin/unpin
+	// idempotent: we toggle only when the state actually needs to change.
+	kbs, err := svc.ListKnowledgeBases(ctx)
+	if err != nil {
+		return cmdutil.WrapHTTP(err, "list knowledge bases")
+	}
+	var current *sdk.KnowledgeBase
+	for i := range kbs {
+		if kbs[i].ID == id {
+			current = &kbs[i]
+			break
+		}
+	}
+	if current == nil {
+		return cmdutil.NewError(cmdutil.CodeResourceNotFound,
+			fmt.Sprintf("knowledge base not found: %s", id))
+	}
+	if current.IsPinned == want {
+		state := "pinned"
+		if !want {
+			state = "unpinned"
+		}
+		// No-op path: the resource is already in the requested state. We
+		// emit the current resource so callers see the canonical shape on
+		// both fresh-toggle and no-op paths. Text path prints a confirming
+		// line; agents observe via the unchanged is_pinned field.
+		if fopts.WantsJSON() {
+			return fopts.Emit(iostreams.IO.Out, current, nil)
+		}
+		fmt.Fprintf(iostreams.IO.Out, "✓ %s is already %s\n", id, state)
+		return nil
+	}
+
+	updated, err := svc.TogglePinKnowledgeBase(ctx, id)
+	if err != nil {
+		return cmdutil.WrapHTTP(err, "%s knowledge base %s", verb, id)
+	}
+	if fopts.WantsJSON() {
+		return fopts.Emit(iostreams.IO.Out, updated, nil)
+	}
+	state := "pinned"
+	if !updated.IsPinned {
+		state = "unpinned"
+	}
+	fmt.Fprintf(iostreams.IO.Out, "✓ %s %s\n", id, state)
+	return nil
+}