refactor(cli): align command surface with mainstream conventions
Empirical mainstream-CLI surveys (gh / kubectl / aws / gcloud / stripe /
flyctl / terraform / vercel / netlify / lark) drove five alignment
fixes — each replaces a weknora-only design choice that mainstream CLIs
do not share. No backwards-compat shims; the CLI has no v0.1 users yet.
1. Single --kb flag (was --kb-id + --kb mutually exclusive)
Survey: 0/7 mainstream CLIs use two parallel flags for "by id" vs
"by name". Single flag (gh -R, gcloud --project) or positional
(kubectl, stripe, terraform). Closest analog — gcloud --project —
collapses identifier types onto one flag.
Now: every command exposes one --kb flag; client-side prefix
detection (cmdutil.IsKBID looks for "kb_") routes id-form values
through directly and name-form values through ListKnowledgeBases.
Mirrors gcloud --project's id-or-name auto-detection.
Touched: search, chat, doc list / upload / delete, link.
Factory.ResolveKB chain trimmed from 5 levels to 4.
2. link supersedes init
Survey: only vercel and netlify ship both `init` AND `link` as
siblings, and they keep them semantically distinct. weknora's pair
wrote the same .weknora/project.yaml file with the same meaning,
differentiated only by interactivity — that's a flag concern, not
a command concern.
Now: cmd/init/ deleted. cmd/link absorbs the interactive flow:
- link --kb <id-or-name> → non-interactive write
- link on a TTY → interactive prompt (lists KBs)
- link non-TTY without --kb → CodeKBIDRequired
Always overwrites silently (matches vercel link / netlify link /
kubectl apply rather than git init's refuse-if-exists).
Dead code purged: --force flag, CodeProjectAlreadyLinked error code.
3. whoami dropped
Survey: 7/7 mainstream CLIs ship exactly one identity command —
never both a status and a whoami. gh / gcloud / stripe pick status
(config + live API); aws / kubectl / flyctl pick whoami (live API).
weknora's auth status was already a superset of whoami (host +
context + user + email + tenant_id + tenant_name vs user_id +
tenant_id), so dropping whoami preserves all functionality and
aligns with the gh / gcloud / stripe form.
4. kb get alias dropped
`view` was already primary (gh repo view / gh pr view convention);
`get` was kept as a cobra alias for v0.0/v0.1 callers. With no
v0.0/v0.1 users to break, the alias is just noise on the command
surface. Acceptance contract envelope cases renamed kb_get.* →
kb_view.*; goldens renamed in lockstep.
5. api refactored to gh shape (-X/--method, default GET, auto-POST)
gh CLI's signature is `gh api <endpoint> [--method M]` — single
positional path, method as a flag, default GET, auto-promoted to
POST when a body is supplied. weknora's previous `api <method>
<path>` inverted this and forced the method to be passed even for
GET — a needless deviation from our declared north star.
Now: `api <path> [-X METHOD] [--data ...]`. Exit-10 protocol
on the DELETE escape-hatch is preserved; -X DELETE still hits
ConfirmDestructive when -y absent.
Plus: AGENTS.md gains an explicit note that `doctor` is a deliberate
divergence from gh / lark — borrowed from `flutter doctor` / `brew
doctor` because RAG deployments routinely break on misconfigured
embeddings / storage / credentials and a 4-status structured envelope
is the cleanest surface for it.
Tests: 24 cli packages green (was 26 in PR-14; init + whoami packages
removed). Acceptance contract envelope cases for whoami removed,
kb_get → kb_view renamed, search args / mock path updated for the
kb_<id> form. e2e harness flag args updated. Factory.ResolveKB tests
rewritten for the single-flag shape. api_test driver updated for the
positional-path / -X-method shape.
This commit is contained in:
@@ -56,10 +56,9 @@ const (
|
||||
CodeLocalUnimplemented ErrorCode = "local.unimplemented"
|
||||
CodeLocalContextNotFound ErrorCode = "local.context_not_found"
|
||||
// v0.2 KB-resolution chain (spec §1.3) and project-link (spec §2.4) codes.
|
||||
CodeKBIDRequired ErrorCode = "local.kb_id_required"
|
||||
CodeKBNotFound ErrorCode = "local.kb_not_found"
|
||||
CodeProjectAlreadyLinked ErrorCode = "local.project_already_linked"
|
||||
CodeProjectLinkCorrupt ErrorCode = "local.project_link_corrupt"
|
||||
CodeKBIDRequired ErrorCode = "local.kb_id_required"
|
||||
CodeKBNotFound ErrorCode = "local.kb_not_found"
|
||||
CodeProjectLinkCorrupt ErrorCode = "local.project_link_corrupt"
|
||||
// CodeUserAborted marks a user-cancelled destructive operation (declined a
|
||||
// confirm prompt). Distinct from SilentError so envelopes still carry a
|
||||
// stable code; distinct from input.* because the user supplied valid args
|
||||
@@ -256,7 +255,7 @@ func AllCodes() []ErrorCode {
|
||||
CodeLocalConfigCorrupt, CodeLocalKeychainDenied, CodeLocalFileIO,
|
||||
CodeLocalUnimplemented, CodeLocalContextNotFound,
|
||||
CodeKBIDRequired, CodeKBNotFound,
|
||||
CodeProjectAlreadyLinked, CodeProjectLinkCorrupt,
|
||||
CodeProjectLinkCorrupt,
|
||||
CodeUserAborted, CodeUploadFileNotFound,
|
||||
CodeSSEStreamAborted, CodeSessionCreateFailed,
|
||||
// mcp
|
||||
|
||||
@@ -141,8 +141,8 @@ func ToErrorBody(err error) *format.ErrorBody {
|
||||
// defaultHint returns a canonical actionable hint for known error codes when
|
||||
// the call site didn't set one. Spec §1.4 zero-config matrix mandates
|
||||
// `auth.unauthenticated` envelopes carry "run weknora auth login" — this
|
||||
// fallback covers the broad surface (whoami / auth status / kb list / kb get
|
||||
// / search) without per-command hint plumbing.
|
||||
// fallback covers the broad surface (auth status / kb list / kb get / search)
|
||||
// without per-command hint plumbing.
|
||||
//
|
||||
// Empty string for codes without a stable canonical hint.
|
||||
func defaultHint(code ErrorCode) string {
|
||||
@@ -154,7 +154,7 @@ func defaultHint(code ErrorCode) string {
|
||||
case CodeAuthForbidden:
|
||||
return "active context lacks permission for this resource"
|
||||
case CodeAuthCrossTenantBlocked, CodeAuthTenantMismatch:
|
||||
return "verify tenant context with `weknora whoami`"
|
||||
return "verify tenant context with `weknora auth status`"
|
||||
case CodeNetworkError:
|
||||
return "check base URL reachability with `weknora doctor`"
|
||||
case CodeServerIncompatibleVersion:
|
||||
@@ -176,13 +176,11 @@ func defaultHint(code ErrorCode) string {
|
||||
case CodeLocalFileIO:
|
||||
return "check file permissions under $XDG_CONFIG_HOME/weknora/"
|
||||
case CodeKBIDRequired:
|
||||
return "run `weknora init` to link a knowledge base, or pass --kb-id"
|
||||
return "run `weknora link` to bind this directory to a knowledge base, or pass --kb"
|
||||
case CodeKBNotFound:
|
||||
return "list available with `weknora kb list`"
|
||||
case CodeProjectAlreadyLinked:
|
||||
return "use --force to overwrite, or `weknora link` to update"
|
||||
case CodeProjectLinkCorrupt:
|
||||
return "remove .weknora/project.yaml and run `weknora init` again"
|
||||
return "remove .weknora/project.yaml and run `weknora link` again"
|
||||
case CodeUserAborted:
|
||||
return "no action taken; pass -y/--yes to skip the confirmation prompt"
|
||||
case CodeUploadFileNotFound:
|
||||
|
||||
@@ -22,7 +22,9 @@ import (
|
||||
//
|
||||
// Four closures (ADR-4):
|
||||
// - Config: parses ~/.config/weknora/config.yaml (no network)
|
||||
// - Client: constructs the SDK client (network: server compat probe + cached)
|
||||
// - Client: constructs the SDK client; only Secrets is sync.Once-cached,
|
||||
// so callers should hold the returned *sdk.Client across
|
||||
// multiple SDK calls within one invocation
|
||||
// - Prompter: returns interactive prompter; agent mode returns AgentPrompter
|
||||
// - Secrets: builds the OS keyring / file fallback credential store the
|
||||
// first time it is requested (probing the keyring at startup
|
||||
@@ -147,25 +149,23 @@ func buildClient(f *Factory) (*sdk.Client, error) {
|
||||
}
|
||||
|
||||
// ResolveKB returns the active KB id for the running command, applying the
|
||||
// 5-level fallback chain (highest to lowest):
|
||||
// 1. --kb-id flag (explicit ID)
|
||||
// 2. --kb flag (name → id via ListKnowledgeBases)
|
||||
// 3. WEKNORA_KB_ID env
|
||||
// 4. .weknora/project.yaml (walk-up from cwd)
|
||||
// 5. error: kb_id required
|
||||
//
|
||||
// Sub-commands that need a KB declare both --kb-id and --kb local flags;
|
||||
// commands that don't (e.g. kb list, init) skip this method entirely.
|
||||
// 4-level fallback chain (highest to lowest):
|
||||
// 1. --kb flag (kb_<...> id passed through; anything else resolved via
|
||||
// ListKnowledgeBases as a name → id lookup; mirrors gcloud --project's
|
||||
// id-or-name auto-detection)
|
||||
// 2. WEKNORA_KB_ID env (always an explicit id)
|
||||
// 3. .weknora/project.yaml (walk-up from cwd)
|
||||
// 4. error: kb required
|
||||
func (f *Factory) ResolveKB(cmd *cobra.Command) (string, error) {
|
||||
if id, _ := cmd.Flags().GetString("kb-id"); id != "" {
|
||||
return id, nil
|
||||
}
|
||||
if name, _ := cmd.Flags().GetString("kb"); name != "" {
|
||||
if v, _ := cmd.Flags().GetString("kb"); v != "" {
|
||||
if IsKBID(v) {
|
||||
return v, nil
|
||||
}
|
||||
c, err := f.Client()
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
return ResolveKBNameToID(cmd.Context(), c, name)
|
||||
return ResolveKBNameToID(cmd.Context(), c, v)
|
||||
}
|
||||
if v := os.Getenv("WEKNORA_KB_ID"); v != "" {
|
||||
return v, nil
|
||||
@@ -182,7 +182,7 @@ func (f *Factory) ResolveKB(cmd *cobra.Command) (string, error) {
|
||||
}
|
||||
}
|
||||
}
|
||||
return "", NewError(CodeKBIDRequired, "kb id is required")
|
||||
return "", NewError(CodeKBIDRequired, "kb is required")
|
||||
}
|
||||
|
||||
// loadSecret returns the stored value for (context, key); ErrNotFound becomes
|
||||
|
||||
@@ -264,18 +264,15 @@ func (c *countingSecrets) Get(ctx, key string) (string, error) {
|
||||
return c.MemStore.Get(ctx, key)
|
||||
}
|
||||
|
||||
// makeResolveKBCmd builds a minimal cobra.Command carrying --kb-id / --kb local
|
||||
// flags so cmd.Flags().GetString lookups in ResolveKB exercise the flag path.
|
||||
func makeResolveKBCmd(t *testing.T, kbID, kbName string) *cobra.Command {
|
||||
// makeResolveKBCmd builds a minimal cobra.Command carrying the single --kb
|
||||
// local flag so cmd.Flags().GetString lookups in ResolveKB exercise the flag
|
||||
// path. The single flag accepts either a kb_<id> or a name.
|
||||
func makeResolveKBCmd(t *testing.T, kb string) *cobra.Command {
|
||||
t.Helper()
|
||||
c := &cobra.Command{Use: "x"}
|
||||
c.Flags().String("kb-id", "", "")
|
||||
c.Flags().String("kb", "", "")
|
||||
if kbID != "" {
|
||||
require.NoError(t, c.Flags().Set("kb-id", kbID))
|
||||
}
|
||||
if kbName != "" {
|
||||
require.NoError(t, c.Flags().Set("kb", kbName))
|
||||
if kb != "" {
|
||||
require.NoError(t, c.Flags().Set("kb", kb))
|
||||
}
|
||||
c.SetContext(context.Background())
|
||||
return c
|
||||
@@ -305,11 +302,11 @@ func fakeKBServer(t *testing.T, kbs []sdk.KnowledgeBase) *httptest.Server {
|
||||
return srv
|
||||
}
|
||||
|
||||
// TestResolveKB_Chain exercises the 5-level fallback chain. Each sub-test
|
||||
// TestResolveKB_Chain exercises the 4-level fallback chain. Each sub-test
|
||||
// isolates cwd / env / closure from the others.
|
||||
func TestResolveKB_Chain(t *testing.T) {
|
||||
t.Run("flag_kb_id_wins", func(t *testing.T) {
|
||||
// flag → no SDK call, no env, no disk.
|
||||
// kb_<id> form → no SDK call, no env, no disk.
|
||||
t.Setenv("WEKNORA_KB_ID", "kb_env_should_lose")
|
||||
dir := t.TempDir()
|
||||
resolveKBChdir(t, dir)
|
||||
@@ -323,7 +320,7 @@ func TestResolveKB_Chain(t *testing.T) {
|
||||
return nil, errors.New("must not be called")
|
||||
},
|
||||
}
|
||||
got, err := f.ResolveKB(makeResolveKBCmd(t, "kb_explicit", ""))
|
||||
got, err := f.ResolveKB(makeResolveKBCmd(t, "kb_explicit"))
|
||||
require.NoError(t, err)
|
||||
assert.Equal(t, "kb_explicit", got)
|
||||
assert.Equal(t, 0, clientCalls)
|
||||
@@ -338,7 +335,7 @@ func TestResolveKB_Chain(t *testing.T) {
|
||||
f := &Factory{
|
||||
Client: func() (*sdk.Client, error) { return sdk.NewClient(srv.URL), nil },
|
||||
}
|
||||
got, err := f.ResolveKB(makeResolveKBCmd(t, "", "foo"))
|
||||
got, err := f.ResolveKB(makeResolveKBCmd(t, "foo"))
|
||||
require.NoError(t, err)
|
||||
assert.Equal(t, "kb_a", got)
|
||||
})
|
||||
@@ -349,7 +346,7 @@ func TestResolveKB_Chain(t *testing.T) {
|
||||
f := &Factory{
|
||||
Client: func() (*sdk.Client, error) { return sdk.NewClient(srv.URL), nil },
|
||||
}
|
||||
_, err := f.ResolveKB(makeResolveKBCmd(t, "", "missing"))
|
||||
_, err := f.ResolveKB(makeResolveKBCmd(t, "missing"))
|
||||
require.Error(t, err)
|
||||
var typed *Error
|
||||
require.ErrorAs(t, err, &typed)
|
||||
@@ -364,7 +361,7 @@ func TestResolveKB_Chain(t *testing.T) {
|
||||
require.NoError(t, projectlink.Save(filepath.Join(dir, ".weknora", "project.yaml"), &projectlink.Project{KBID: "kb_disk_should_lose"}))
|
||||
|
||||
f := &Factory{}
|
||||
got, err := f.ResolveKB(makeResolveKBCmd(t, "", ""))
|
||||
got, err := f.ResolveKB(makeResolveKBCmd(t, ""))
|
||||
require.NoError(t, err)
|
||||
assert.Equal(t, "kb_env", got)
|
||||
})
|
||||
@@ -379,7 +376,7 @@ func TestResolveKB_Chain(t *testing.T) {
|
||||
resolveKBChdir(t, deep)
|
||||
|
||||
f := &Factory{}
|
||||
got, err := f.ResolveKB(makeResolveKBCmd(t, "", ""))
|
||||
got, err := f.ResolveKB(makeResolveKBCmd(t, ""))
|
||||
require.NoError(t, err)
|
||||
assert.Equal(t, "kb_proj", got)
|
||||
})
|
||||
@@ -391,7 +388,7 @@ func TestResolveKB_Chain(t *testing.T) {
|
||||
resolveKBChdir(t, dir)
|
||||
|
||||
f := &Factory{}
|
||||
_, err := f.ResolveKB(makeResolveKBCmd(t, "", ""))
|
||||
_, err := f.ResolveKB(makeResolveKBCmd(t, ""))
|
||||
require.Error(t, err)
|
||||
var typed *Error
|
||||
require.ErrorAs(t, err, &typed)
|
||||
|
||||
@@ -3,10 +3,21 @@ package cmdutil
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"strings"
|
||||
|
||||
sdk "github.com/Tencent/WeKnora/client"
|
||||
)
|
||||
|
||||
// kbIDPrefix is the server-emitted prefix that marks a string as a KB id
|
||||
// (rather than a KB name). The single `--kb` flag uses it for client-side
|
||||
// id-vs-name auto-detection — the same pattern gcloud uses for --project
|
||||
// (numeric id vs project-id form).
|
||||
const kbIDPrefix = "kb_"
|
||||
|
||||
// IsKBID reports whether s looks like a KB id. Used by Factory.ResolveKB and
|
||||
// any caller that accepts a single id-or-name selector value.
|
||||
func IsKBID(s string) bool { return strings.HasPrefix(s, kbIDPrefix) }
|
||||
|
||||
// KBLister is the narrow SDK surface ResolveKBNameToID depends on. The
|
||||
// production *sdk.Client satisfies it; tests inject fakes without standing
|
||||
// up an HTTP server.
|
||||
@@ -15,8 +26,8 @@ type KBLister interface {
|
||||
}
|
||||
|
||||
// ResolveKBNameToID looks up a knowledge base by name and returns its ID.
|
||||
// Used by `init`, `link`, and `Factory.ResolveKB` — a single lookup so the
|
||||
// match policy (currently exact case-sensitive) lives in one place.
|
||||
// Used by `link` and `Factory.ResolveKB` — a single lookup so the match
|
||||
// policy (currently exact case-sensitive) lives in one place.
|
||||
func ResolveKBNameToID(ctx context.Context, lister KBLister, name string) (string, error) {
|
||||
kbs, err := lister.ListKnowledgeBases(ctx)
|
||||
if err != nil {
|
||||
|
||||
Reference in New Issue
Block a user