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:
+9
-9
@@ -50,13 +50,15 @@ func NewCmdList(f *cmdutil.Factory) *cobra.Command {
|
||||
Use: "list",
|
||||
Short: "List documents in a knowledge base",
|
||||
Long: `Lists documents (uploaded files / web pages / inline text) in the
|
||||
resolved knowledge base. KB id resolution follows the standard 5-level chain:
|
||||
--kb-id flag > --kb name > WEKNORA_KB_ID env > .weknora/project.yaml > error.
|
||||
resolved knowledge base. KB resolution follows the standard 4-level chain:
|
||||
--kb flag > WEKNORA_KB_ID env > .weknora/project.yaml > error. The --kb
|
||||
flag accepts either a kb_<id> or a name (resolved via list).
|
||||
|
||||
Default sort is updated_at desc so the most recent uploads surface first;
|
||||
backend storage order is not guaranteed and varies between deployments.`,
|
||||
Example: ` weknora doc list # uses project link / env
|
||||
weknora doc list --kb-id kb_abc # explicit
|
||||
weknora doc list --kb kb_abc # explicit id
|
||||
weknora doc list --kb my-kb # resolved by name
|
||||
weknora doc list --page 2 --json # paginated envelope output`,
|
||||
Args: cobra.NoArgs,
|
||||
RunE: func(c *cobra.Command, _ []string) error {
|
||||
@@ -71,15 +73,13 @@ backend storage order is not guaranteed and varies between deployments.`,
|
||||
return runList(c.Context(), opts, cli, kbID)
|
||||
},
|
||||
}
|
||||
// --kb-id / --kb are read by Factory.ResolveKB; declare them here so
|
||||
// Cobra parses the values into the command's flag set.
|
||||
cmd.Flags().String("kb-id", "", "Knowledge base id (overrides env / project link)")
|
||||
cmd.Flags().String("kb", "", "Knowledge base name (resolved to id)")
|
||||
// --kb is read by Factory.ResolveKB; declare it here so cobra parses the
|
||||
// value into the command's flag set.
|
||||
cmd.Flags().String("kb", "", "Knowledge base id (kb_…) or name (overrides env / project link)")
|
||||
cmd.Flags().IntVar(&opts.Page, "page", 1, "Page number (1-based)")
|
||||
cmd.Flags().IntVar(&opts.PageSize, "page-size", 20, "Items per page")
|
||||
cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope")
|
||||
cmd.MarkFlagsMutuallyExclusive("kb-id", "kb")
|
||||
agent.SetAgentHelp(cmd, "Lists docs in the resolved KB. Returns data: {items, page, page_size, total, kb_id}; pass --kb-id when not running inside a project.")
|
||||
agent.SetAgentHelp(cmd, "Lists docs in the resolved KB. Returns data: {items, page, page_size, total, kb_id}; pass --kb when not running inside a project.")
|
||||
return cmd
|
||||
}
|
||||
|
||||
|
||||
+11
-11
@@ -135,7 +135,7 @@ func TestList_KBIDRequired(t *testing.T) {
|
||||
}
|
||||
cmd := NewCmdList(f)
|
||||
cmd.SetContext(context.Background())
|
||||
cmd.SetArgs([]string{}) // no --kb-id, no --kb
|
||||
cmd.SetArgs([]string{}) // no --kb
|
||||
cmd.SilenceErrors = true
|
||||
cmd.SilenceUsage = true
|
||||
err := cmd.Execute()
|
||||
@@ -146,9 +146,9 @@ func TestList_KBIDRequired(t *testing.T) {
|
||||
assert.Equal(t, cmdutil.CodeKBIDRequired, typed.Code)
|
||||
}
|
||||
|
||||
// TestList_KBIDFlagWiredToResolveKB confirms that a --kb-id passed at the
|
||||
// cobra layer reaches Factory.ResolveKB and skips the Client() call.
|
||||
func TestList_KBIDFlagWiredToResolveKB(t *testing.T) {
|
||||
// TestList_KBFlagWiredToResolveKB confirms that --kb=kb_<id> passed at the
|
||||
// cobra layer reaches Factory.ResolveKB and short-circuits without listing.
|
||||
func TestList_KBFlagWiredToResolveKB(t *testing.T) {
|
||||
chdirIsolated(t)
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
|
||||
@@ -162,20 +162,20 @@ func TestList_KBIDFlagWiredToResolveKB(t *testing.T) {
|
||||
return nil, errors.New("forced-after-resolvekb")
|
||||
},
|
||||
}
|
||||
// With --kb-id supplied, ResolveKB short-circuits without consulting the
|
||||
// client. The RunE then asks for the client to run the actual list — that
|
||||
// call triggers the forced error. Surfacing "forced-after-resolvekb"
|
||||
// (rather than CodeKBIDRequired) is the proof point that --kb-id was
|
||||
// honored.
|
||||
// With --kb=kb_<id> supplied, ResolveKB short-circuits on the prefix
|
||||
// match without consulting the client. The RunE then asks for the client
|
||||
// to run the actual list — that call triggers the forced error.
|
||||
// Surfacing "forced-after-resolvekb" (rather than CodeKBIDRequired) is
|
||||
// the proof point that --kb was honored.
|
||||
cmd := NewCmdList(f)
|
||||
cmd.SetContext(context.Background())
|
||||
cmd.SetArgs([]string{"--kb-id", "kb_explicit"})
|
||||
cmd.SetArgs([]string{"--kb", "kb_explicit"})
|
||||
cmd.SilenceErrors = true
|
||||
cmd.SilenceUsage = true
|
||||
err := cmd.Execute()
|
||||
require.Error(t, err, "expected client construction error")
|
||||
assert.Contains(t, err.Error(), "forced-after-resolvekb",
|
||||
"should surface the Client closure error, not a kb-id-required error")
|
||||
"should surface the Client closure error, not a kb-required error")
|
||||
}
|
||||
|
||||
// pinning the sort order: most-recent-first regardless of input order.
|
||||
|
||||
@@ -45,8 +45,9 @@ func NewCmdUpload(f *cmdutil.Factory) *cobra.Command {
|
||||
Use: "upload <file>",
|
||||
Short: "Upload a local file to the knowledge base",
|
||||
Long: `Uploads a file (PDF / DOCX / Markdown / TXT / etc.) to the resolved
|
||||
knowledge base. KB id resolution follows the standard 5-level chain:
|
||||
--kb-id flag > --kb name > WEKNORA_KB_ID env > .weknora/project.yaml > error.
|
||||
knowledge base. KB resolution follows the standard 4-level chain:
|
||||
--kb flag > WEKNORA_KB_ID env > .weknora/project.yaml > error. The --kb
|
||||
flag accepts either a kb_<id> or a name (resolved via list).
|
||||
|
||||
Pass --name to override the recorded file name (useful when the local file
|
||||
has a generic name like "report.pdf" but you want to surface it as e.g.
|
||||
@@ -55,7 +56,8 @@ has a generic name like "report.pdf" but you want to surface it as e.g.
|
||||
v0.2 ships single-file upload only; --recursive / --glob and progress UI are
|
||||
planned for v0.3.`,
|
||||
Example: ` weknora doc upload report.pdf
|
||||
weknora doc upload notes.md --kb-id kb_abc
|
||||
weknora doc upload notes.md --kb kb_abc
|
||||
weknora doc upload notes.md --kb my-kb
|
||||
weknora doc upload q3.pdf --name "Q3 Marketing Report.pdf"`,
|
||||
Args: cobra.ExactArgs(1),
|
||||
RunE: func(c *cobra.Command, args []string) error {
|
||||
@@ -78,12 +80,10 @@ planned for v0.3.`,
|
||||
return runUpload(c.Context(), opts, cli, kbID, path)
|
||||
},
|
||||
}
|
||||
cmd.Flags().String("kb-id", "", "Knowledge base id (overrides env / project link)")
|
||||
cmd.Flags().String("kb", "", "Knowledge base name (resolved to id)")
|
||||
cmd.Flags().String("kb", "", "Knowledge base id (kb_…) or name (overrides env / project link)")
|
||||
cmd.Flags().StringVar(&opts.Name, "name", "", "Custom file name to record (defaults to base name)")
|
||||
cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope")
|
||||
cmd.MarkFlagsMutuallyExclusive("kb-id", "kb")
|
||||
agent.SetAgentHelp(cmd, "Uploads one local file to the resolved KB. Refuses non-regular files (dir / symlink). Returns data: Knowledge object with id, parse_status. Pass --kb-id outside a linked project.")
|
||||
agent.SetAgentHelp(cmd, "Uploads one local file to the resolved KB. Refuses non-regular files (dir / symlink). Returns data: Knowledge object with id, parse_status. Pass --kb outside a linked project.")
|
||||
return cmd
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user