From 35c79281c80f3b46e799fe63c1ae9d9bf2ea3d17 Mon Sep 17 00:00:00 2001 From: nullkey Date: Wed, 13 May 2026 16:40:43 +0800 Subject: [PATCH] feat(cli): doc view + unlink (fill v0.3 design-gap audit) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Final design-pass audit on the v0.3 surface flagged two real gaps. (A) doc view was missing. Every other resource subtree exposes a view verb (kb view, session view) for inspecting a single record, but doc — which has the richest metadata of the three (title, file name, type, size, parse_status, embedding_model, processed_at, error_message) — had no single-doc surface. Users wanting one doc's metadata had to `doc list | grep`. Implementation mirrors kb view: narrow ViewService(GetKnowledge) interface, --json envelope path, human KEY: VALUE renderer. Optional fields are omitted rather than rendered as "-" so the panel is dense. Tested: human renderer, title fallback when FileName empty, omit-empty contract, JSON envelope shape, 404 classification. (B) link had no counterpart. Once .weknora/project.yaml is written, the only way to clear it was `rm` by hand. Both vercel and netlify ship `unlink` as a top-level verb; not having one was a discoverability gap. Top-level rather than `link --clear` follows the verb-noun convention of the rest of the surface — the verb stands alone and the operation isn't parameterised. unlink walks up from cwd via projectlink.Discover (the same parent-chain logic Factory.ResolveKB uses on the read side), so a user in a subdirectory of a linked project can unlink without cd-ing up. Errors with input.invalid_argument when no link is found anywhere in the chain. Idempotent under racy concurrent removal: os.ErrNotExist on os.Remove falls through to a Success envelope since the post-condition holds either way. projectlink package gained Remove() alongside Save / Load / Discover so unlink doesn't reimplement the idempotent-remove pattern inline. Top-level registration in cmd/root.go, alongside link. cli/AGENTS.md verb canon line adds unlink to the locally-introduced list. cli/CHANGELOG.md gains an Added entry for each. 5 unit tests for view + 4 for unlink (cwd / walk-up / no-link error / JSON envelope). Full suite green. Intentionally deferred: - session edit (rename a session): sessions auto-name from the first prompt; polish rather than a gap. - link --clear as an alternative to unlink: top-level unlink is the documented form; aliases would just multiply the surface. --- cli/AGENTS.md | 2 +- cli/CHANGELOG.md | 7 ++ cli/cmd/doc/doc.go | 6 +- cli/cmd/doc/view.go | 87 +++++++++++++++++ cli/cmd/doc/view_test.go | 121 ++++++++++++++++++++++++ cli/cmd/link/unlink.go | 76 +++++++++++++++ cli/cmd/link/unlink_test.go | 97 +++++++++++++++++++ cli/cmd/root.go | 1 + cli/internal/projectlink/projectlink.go | 10 ++ 9 files changed, 404 insertions(+), 3 deletions(-) create mode 100644 cli/cmd/doc/view.go create mode 100644 cli/cmd/doc/view_test.go create mode 100644 cli/cmd/link/unlink.go create mode 100644 cli/cmd/link/unlink_test.go diff --git a/cli/AGENTS.md b/cli/AGENTS.md index 5f7404ff..78710995 100644 --- a/cli/AGENTS.md +++ b/cli/AGENTS.md @@ -207,7 +207,7 @@ agent-aware error model. Documented deviations: misconfigured embeddings / storage / credentials, so a structured 4-status diagnostic is the agent-readable surface for that. -Verb canon (gh-canonical): `list / view / create / edit / delete / upload / download / pin / unpin / use`. Locally introduced for resource semantics gh lacks: `empty` (bulk-delete contents preserving the container), `refresh` (token), `add` / `remove` (context CRUD), `link` (project bind). +Verb canon (gh-canonical): `list / view / create / edit / delete / upload / download / pin / unpin / use`. Locally introduced for resource semantics gh lacks: `empty` (bulk-delete contents preserving the container), `refresh` (token), `add` / `remove` (context CRUD), `link` / `unlink` (project bind / unbind). **ADR-4 — Factory closures + narrow Service interfaces.** `cmdutil.Factory` exposes four lazy closures (Config / Client / Prompter / Secrets) that diff --git a/cli/CHANGELOG.md b/cli/CHANGELOG.md index b3e2aba2..fdc1c5e1 100644 --- a/cli/CHANGELOG.md +++ b/cli/CHANGELOG.md @@ -30,6 +30,9 @@ Earlier history (v0.0 through v0.2) is recorded in the project root - `kb empty` — bulk-delete documents while preserving the KB record and its config. High-risk-write; exit-10 confirmation in non-TTY / `--json` paths; `--dry-run` emits `risk` + `dry_run:true`. +- `doc view ` — show one document's metadata (title, file name, + type, size, parse status, embedding model, processed-at, error + message). Counterpart to `kb view` and `session view`. - `doc download` — stream a knowledge file to disk (`-O FILE` / `-O -` for stdout) with `--clobber` controlling overwrite. Rejects server-supplied path-like filenames; partial writes on error are @@ -47,6 +50,10 @@ Earlier history (v0.0 through v0.2) is recorded in the project root management. - `api --input FILE` / `api --input -` — body source for raw HTTP passthrough (file or stdin); mutually exclusive with `--data`. +- `unlink` — remove the cwd's `.weknora/project.yaml` so subsequent + commands stop auto-resolving `--kb` from it. Walks up from cwd so a + user in a subdirectory can unlink without cd-ing to the project root + (mirrors `vercel unlink` / `netlify unlink`). - Completion smoke test guards against cobra bumps silently breaking bash / zsh / fish / powershell completion. diff --git a/cli/cmd/doc/doc.go b/cli/cmd/doc/doc.go index 0080fb60..6dc4c1e6 100644 --- a/cli/cmd/doc/doc.go +++ b/cli/cmd/doc/doc.go @@ -1,5 +1,6 @@ -// Package doc implements the `weknora doc` subtree (list / upload / download -// / delete). Upload also supports --recursive / --glob for bulk ingestion. +// Package doc implements the `weknora doc` subtree (list / view / upload / +// download / delete). Upload also supports --recursive / --glob for bulk +// ingestion. // // "Doc" is the CLI noun; the underlying SDK type is `Knowledge`. The renaming // is deliberate: end-users think of a knowledge entry as the document they @@ -22,6 +23,7 @@ func NewCmd(f *cmdutil.Factory) *cobra.Command { Run: func(c *cobra.Command, _ []string) { _ = c.Help() }, } cmd.AddCommand(NewCmdList(f)) + cmd.AddCommand(NewCmdView(f)) cmd.AddCommand(NewCmdUpload(f)) cmd.AddCommand(NewCmdDownload(f)) cmd.AddCommand(NewCmdDelete(f)) diff --git a/cli/cmd/doc/view.go b/cli/cmd/doc/view.go new file mode 100644 index 00000000..da6931d0 --- /dev/null +++ b/cli/cmd/doc/view.go @@ -0,0 +1,87 @@ +package doc + +import ( + "context" + "fmt" + + "github.com/spf13/cobra" + + "github.com/Tencent/WeKnora/cli/internal/agent" + "github.com/Tencent/WeKnora/cli/internal/cmdutil" + "github.com/Tencent/WeKnora/cli/internal/format" + "github.com/Tencent/WeKnora/cli/internal/iostreams" + "github.com/Tencent/WeKnora/cli/internal/text" + sdk "github.com/Tencent/WeKnora/client" +) + +type ViewOptions struct { + JSONOut bool +} + +// ViewService is the narrow SDK surface this command depends on. +type ViewService interface { + GetKnowledge(ctx context.Context, id string) (*sdk.Knowledge, error) +} + +// NewCmdView builds `weknora doc view `. +func NewCmdView(f *cmdutil.Factory) *cobra.Command { + opts := &ViewOptions{} + cmd := &cobra.Command{ + Use: "view ", + Short: "Show a document by ID", + Example: ` weknora doc view doc_abc + weknora doc view doc_abc --json`, + Args: cobra.ExactArgs(1), + RunE: func(c *cobra.Command, args []string) error { + cli, err := f.Client() + if err != nil { + return err + } + return runView(c.Context(), opts, cli, args[0]) + }, + } + cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + agent.SetAgentHelp(cmd, "Returns the full Knowledge object for one document: id, kb_id, file metadata, parse_status, processed_at, error_message. Use this instead of paging through `doc list` when you have the doc id.") + return cmd +} + +func runView(ctx context.Context, opts *ViewOptions, svc ViewService, id string) error { + doc, err := svc.GetKnowledge(ctx, id) + if err != nil { + return cmdutil.WrapHTTP(err, "get document %q", id) + } + if opts.JSONOut { + return format.WriteEnvelope(iostreams.IO.Out, format.Success(doc, &format.Meta{KBID: doc.KnowledgeBaseID})) + } + w := iostreams.IO.Out + fmt.Fprintf(w, "ID: %s\n", doc.ID) + fmt.Fprintf(w, "NAME: %s\n", text.KnowledgeDisplayName(doc.FileName, doc.Title, doc.ID)) + if doc.KnowledgeBaseID != "" { + fmt.Fprintf(w, "KB: %s\n", doc.KnowledgeBaseID) + } + if doc.FileType != "" { + fmt.Fprintf(w, "TYPE: %s\n", doc.FileType) + } + if doc.FileSize > 0 { + fmt.Fprintf(w, "SIZE: %s\n", formatSize(doc.FileSize)) + } + if doc.ParseStatus != "" { + fmt.Fprintf(w, "STATUS: %s\n", doc.ParseStatus) + } + if doc.EmbeddingModelID != "" { + fmt.Fprintf(w, "EMBEDDING: %s\n", doc.EmbeddingModelID) + } + if !doc.CreatedAt.IsZero() { + fmt.Fprintf(w, "CREATED: %s\n", doc.CreatedAt.Format("2006-01-02 15:04:05")) + } + if !doc.UpdatedAt.IsZero() { + fmt.Fprintf(w, "UPDATED: %s\n", doc.UpdatedAt.Format("2006-01-02 15:04:05")) + } + if doc.ProcessedAt != nil && !doc.ProcessedAt.IsZero() { + fmt.Fprintf(w, "PROCESSED: %s\n", doc.ProcessedAt.Format("2006-01-02 15:04:05")) + } + if doc.ErrorMessage != "" { + fmt.Fprintf(w, "ERROR: %s\n", doc.ErrorMessage) + } + return nil +} diff --git a/cli/cmd/doc/view_test.go b/cli/cmd/doc/view_test.go new file mode 100644 index 00000000..5d459b78 --- /dev/null +++ b/cli/cmd/doc/view_test.go @@ -0,0 +1,121 @@ +package doc + +import ( + "context" + "errors" + "strings" + "testing" + "time" + + "github.com/Tencent/WeKnora/cli/internal/cmdutil" + "github.com/Tencent/WeKnora/cli/internal/iostreams" + sdk "github.com/Tencent/WeKnora/client" +) + +// fakeViewSvc scripts a GetKnowledge response. Tests bypass cobra and call +// runView directly with this fake injected. +type fakeViewSvc struct { + doc *sdk.Knowledge + err error +} + +func (f *fakeViewSvc) GetKnowledge(_ context.Context, _ string) (*sdk.Knowledge, error) { + return f.doc, f.err +} + +func TestView_Human_RendersExpectedFields(t *testing.T) { + out, _ := iostreams.SetForTest(t) + processed := time.Date(2026, 1, 2, 3, 4, 5, 0, time.UTC) + svc := &fakeViewSvc{doc: &sdk.Knowledge{ + ID: "doc_abc", + KnowledgeBaseID: "kb1", + FileName: "policy.pdf", + Title: "Policy", + FileType: "pdf", + FileSize: 2048, + ParseStatus: "completed", + EmbeddingModelID: "text-embedding-3", + CreatedAt: time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC), + UpdatedAt: time.Date(2026, 1, 2, 0, 0, 0, 0, time.UTC), + ProcessedAt: &processed, + }} + if err := runView(context.Background(), &ViewOptions{}, svc, "doc_abc"); err != nil { + t.Fatalf("runView: %v", err) + } + got := out.String() + for _, want := range []string{ + "ID:", "doc_abc", "NAME:", "policy.pdf", "KB:", "kb1", + "TYPE:", "pdf", "SIZE:", "STATUS:", "completed", + "EMBEDDING:", "text-embedding-3", "PROCESSED:", + } { + if !strings.Contains(got, want) { + t.Errorf("missing %q in:\n%s", want, got) + } + } +} + +// A doc with no FileName falls back to Title for the NAME line — same +// ordering as `doc list` (KnowledgeDisplayName precedence). +func TestView_Human_TitleFallback(t *testing.T) { + out, _ := iostreams.SetForTest(t) + svc := &fakeViewSvc{doc: &sdk.Knowledge{ID: "doc_url", Title: "Pasted article", FileName: ""}} + if err := runView(context.Background(), &ViewOptions{}, svc, "doc_url"); err != nil { + t.Fatalf("runView: %v", err) + } + got := out.String() + if !strings.Contains(got, "Pasted article") { + t.Errorf("expected Title fallback in NAME line; got:\n%s", got) + } +} + +// Optional fields (ProcessedAt nil, ErrorMessage empty, EmbeddingModelID +// empty) must not produce empty KEY: lines — the formatter omits them +// rather than printing "PROCESSED: -". +func TestView_Human_OmitsEmptyFields(t *testing.T) { + out, _ := iostreams.SetForTest(t) + svc := &fakeViewSvc{doc: &sdk.Knowledge{ + ID: "doc_abc", + FileName: "x.txt", + }} + if err := runView(context.Background(), &ViewOptions{}, svc, "doc_abc"); err != nil { + t.Fatalf("runView: %v", err) + } + // Line-prefix match (not substring): "ERROR:" as a substring could + // also appear inside `STATUS: error` if a future test seeds + // ParseStatus="error". Splitting by newline pins the assertion to the + // label column. + lines := strings.Split(out.String(), "\n") + for _, prefix := range []string{"PROCESSED:", "EMBEDDING:", "ERROR:"} { + for _, l := range lines { + if strings.HasPrefix(l, prefix) { + t.Errorf("expected no line beginning with %q (empty field), got: %q", prefix, l) + } + } + } +} + +func TestView_JSON_EmitsEnvelope(t *testing.T) { + out, _ := iostreams.SetForTest(t) + svc := &fakeViewSvc{doc: &sdk.Knowledge{ID: "doc_abc", FileName: "x.txt", KnowledgeBaseID: "kb1"}} + if err := runView(context.Background(), &ViewOptions{JSONOut: true}, svc, "doc_abc"); err != nil { + t.Fatalf("runView: %v", err) + } + got := out.String() + for _, want := range []string{`"ok":true`, `"id":"doc_abc"`, `"file_name":"x.txt"`, `"knowledge_base_id":"kb1"`} { + if !strings.Contains(got, want) { + t.Errorf("missing %q in:\n%s", want, got) + } + } +} + +func TestView_NotFound_ClassifiedAs404(t *testing.T) { + _, _ = iostreams.SetForTest(t) + svc := &fakeViewSvc{err: errors.New("HTTP error 404: not found")} + err := runView(context.Background(), &ViewOptions{}, svc, "missing") + if err == nil { + t.Fatal("expected error") + } + if !cmdutil.IsNotFound(err) { + t.Errorf("expected resource.not_found, got %v", err) + } +} diff --git a/cli/cmd/link/unlink.go b/cli/cmd/link/unlink.go new file mode 100644 index 00000000..b21c189a --- /dev/null +++ b/cli/cmd/link/unlink.go @@ -0,0 +1,76 @@ +package linkcmd + +import ( + "fmt" + "os" + + "github.com/spf13/cobra" + + "github.com/Tencent/WeKnora/cli/internal/agent" + "github.com/Tencent/WeKnora/cli/internal/cmdutil" + "github.com/Tencent/WeKnora/cli/internal/format" + "github.com/Tencent/WeKnora/cli/internal/iostreams" + "github.com/Tencent/WeKnora/cli/internal/projectlink" +) + +type UnlinkOptions struct { + JSONOut bool +} + +// unlinkResult is the typed payload emitted under data. +type unlinkResult struct { + ProjectLinkPath string `json:"project_link_path"` +} + +// NewCmdUnlink builds `weknora unlink`. Walks up from cwd so a user in +// a subdirectory of a linked project can unlink without cd-ing up first. +func NewCmdUnlink() *cobra.Command { + opts := &UnlinkOptions{} + cmd := &cobra.Command{ + Use: "unlink", + Short: "Remove the directory's knowledge-base binding", + Long: `Removes the .weknora/project.yaml that ` + "`weknora link`" + ` previously +wrote, so subsequent commands no longer auto-resolve --kb from the link. + +Walks up from the current directory until a link is found, mirroring the +discovery that ` + "`--kb`" + ` resolution uses; you do not need to cd to the +project root to unlink. Errors with input.invalid_argument when no link +is present anywhere in the parent chain.`, + Example: ` weknora unlink # remove the binding for this project + weknora unlink --json # envelope output (CI / agents)`, + Args: cobra.NoArgs, + RunE: func(c *cobra.Command, _ []string) error { + return runUnlink(opts) + }, + } + cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + agent.SetAgentHelp(cmd, "Removes .weknora/project.yaml (the cwd → KB binding). Walks up from cwd. Errors with input.invalid_argument when no link is present in the parent chain.") + return cmd +} + +func runUnlink(opts *UnlinkOptions) error { + cwd, err := os.Getwd() + if err != nil { + return cmdutil.Wrapf(cmdutil.CodeLocalFileIO, err, "get cwd") + } + linkPath, found, err := projectlink.Discover(cwd) + if err != nil { + return cmdutil.Wrapf(cmdutil.CodeLocalFileIO, err, "discover project link") + } + if !found { + return &cmdutil.Error{ + Code: cmdutil.CodeInputInvalidArgument, + Message: fmt.Sprintf("no %s/%s found at or above %s", projectlink.DirName, projectlink.FileName, cwd), + Hint: "run `weknora link --kb ` first, or check you're in the right directory", + } + } + if err := projectlink.Remove(linkPath); err != nil { + return cmdutil.Wrapf(cmdutil.CodeLocalFileIO, err, "remove %s", linkPath) + } + if opts.JSONOut { + return format.WriteEnvelope(iostreams.IO.Out, format.Success( + unlinkResult{ProjectLinkPath: linkPath}, nil)) + } + fmt.Fprintf(iostreams.IO.Out, "✓ Unlinked %s\n", linkPath) + return nil +} diff --git a/cli/cmd/link/unlink_test.go b/cli/cmd/link/unlink_test.go new file mode 100644 index 00000000..fee1e926 --- /dev/null +++ b/cli/cmd/link/unlink_test.go @@ -0,0 +1,97 @@ +package linkcmd + +import ( + "errors" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/Tencent/WeKnora/cli/internal/cmdutil" + "github.com/Tencent/WeKnora/cli/internal/iostreams" + "github.com/Tencent/WeKnora/cli/internal/projectlink" +) + +// mkLinkFile seeds .weknora/project.yaml in dir so the unlink path has +// something to remove. Returns the absolute file path. +func mkLinkFile(t *testing.T, dir string) string { + t.Helper() + full := filepath.Join(dir, projectlink.DirName, projectlink.FileName) + if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil { + t.Fatalf("mkdir: %v", err) + } + if err := projectlink.Save(full, &projectlink.Project{Context: "default", KBID: "kb_abc"}); err != nil { + t.Fatalf("save: %v", err) + } + return full +} + +func TestUnlink_RemovesLinkInCwd(t *testing.T) { + _, _ = iostreams.SetForTest(t) + tmp := t.TempDir() + linkPath := mkLinkFile(t, tmp) + t.Chdir(tmp) + + if err := runUnlink(&UnlinkOptions{}); err != nil { + t.Fatalf("runUnlink: %v", err) + } + if _, err := os.Stat(linkPath); !os.IsNotExist(err) { + t.Errorf("link file should be gone, got err=%v", err) + } +} + +func TestUnlink_WalksUpFromSubdir(t *testing.T) { + _, _ = iostreams.SetForTest(t) + root := t.TempDir() + linkPath := mkLinkFile(t, root) + sub := filepath.Join(root, "deep", "nested") + if err := os.MkdirAll(sub, 0o755); err != nil { + t.Fatalf("mkdir sub: %v", err) + } + t.Chdir(sub) + + if err := runUnlink(&UnlinkOptions{}); err != nil { + t.Fatalf("runUnlink: %v", err) + } + if _, err := os.Stat(linkPath); !os.IsNotExist(err) { + t.Errorf("parent link file should be gone, got err=%v", err) + } +} + +func TestUnlink_NoLink_Errors(t *testing.T) { + _, _ = iostreams.SetForTest(t) + tmp := t.TempDir() + t.Chdir(tmp) + + err := runUnlink(&UnlinkOptions{}) + if err == nil { + t.Fatal("expected error when no link present") + } + var typed *cmdutil.Error + if !errors.As(err, &typed) { + t.Fatalf("expected *cmdutil.Error, got %T", err) + } + if typed.Code != cmdutil.CodeInputInvalidArgument { + t.Errorf("expected CodeInputInvalidArgument, got %s", typed.Code) + } + if !strings.Contains(typed.Message, projectlink.DirName) { + t.Errorf("error message should name the missing path; got %q", typed.Message) + } +} + +func TestUnlink_JSON_Envelope(t *testing.T) { + out, _ := iostreams.SetForTest(t) + tmp := t.TempDir() + mkLinkFile(t, tmp) + t.Chdir(tmp) + + if err := runUnlink(&UnlinkOptions{JSONOut: true}); err != nil { + t.Fatalf("runUnlink: %v", err) + } + got := out.String() + for _, want := range []string{`"ok":true`, `"project_link_path"`, projectlink.DirName} { + if !strings.Contains(got, want) { + t.Errorf("missing %q in envelope:\n%s", want, got) + } + } +} diff --git a/cli/cmd/root.go b/cli/cmd/root.go index e258a6ec..abae26a7 100644 --- a/cli/cmd/root.go +++ b/cli/cmd/root.go @@ -174,6 +174,7 @@ hybrid searches against a WeKnora server from your shell or an AI agent.`, cmd.AddCommand(kb.NewCmd(f)) cmd.AddCommand(contextcmd.NewCmd(f)) cmd.AddCommand(linkcmd.NewCmd(f)) + cmd.AddCommand(linkcmd.NewCmdUnlink()) cmd.AddCommand(doc.NewCmd(f)) cmd.AddCommand(apicmd.NewCmd(f)) cmd.AddCommand(chatcmd.NewCmd(f)) diff --git a/cli/internal/projectlink/projectlink.go b/cli/internal/projectlink/projectlink.go index 3a5e56d7..344f4873 100644 --- a/cli/internal/projectlink/projectlink.go +++ b/cli/internal/projectlink/projectlink.go @@ -83,3 +83,13 @@ func Load(path string) (*Project, error) { func Save(path string, p *Project) error { return xdg.WriteAtomicYAML(path, p) } + +// Remove deletes the project link at path. A missing file is reported as +// success so callers can stay idempotent under concurrent-removal races +// — the post-condition (no file at path) holds in either case. +func Remove(path string) error { + if err := os.Remove(path); err != nil && !errors.Is(err, os.ErrNotExist) { + return fmt.Errorf("remove project link: %w", err) + } + return nil +}