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:
+47
-25
@@ -1,10 +1,12 @@
|
||||
// Package api implements the `weknora api` raw HTTP passthrough command.
|
||||
//
|
||||
// Mirrors `gh api` ergonomics: 2 positionals (method, path), --data /
|
||||
// --data-file mutually exclusive body source, default raw response body to
|
||||
// stdout, --json wraps in CLI envelope. Reuses sdk.Client.Raw which already
|
||||
// applies tenant + auth headers; v0.2 does not support --header (SDK Raw
|
||||
// signature lacks header param) — that's planned for v0.3.
|
||||
// Mirrors `gh api` ergonomics: 1 positional (path) + `-X/--method` flag,
|
||||
// default GET (auto-promoted to POST when a body is supplied via --data /
|
||||
// --data-file). The two body-source flags are mutually exclusive. Default
|
||||
// raw response body to stdout; --json wraps in CLI envelope. Reuses
|
||||
// sdk.Client.Raw which already applies tenant + auth headers; v0.2 does not
|
||||
// support --header (SDK Raw signature lacks header param) — that's planned
|
||||
// for v0.3.
|
||||
package api
|
||||
|
||||
import (
|
||||
@@ -27,6 +29,7 @@ import (
|
||||
|
||||
// Options captures `weknora api` flag state.
|
||||
type Options struct {
|
||||
Method string
|
||||
Data string
|
||||
DataFile string
|
||||
JSONOut bool
|
||||
@@ -46,41 +49,45 @@ type Service interface {
|
||||
func NewCmd(f *cmdutil.Factory) *cobra.Command {
|
||||
opts := &Options{}
|
||||
cmd := &cobra.Command{
|
||||
Use: "api <method> <path>",
|
||||
Use: "api <path>",
|
||||
Short: "Make a raw API request to the WeKnora server",
|
||||
Long: `Send an HTTP request through the SDK and print the response.
|
||||
|
||||
Auth, tenant, and request-id headers are applied automatically from the active
|
||||
context. The response body is written to stdout by default; use --json to wrap
|
||||
it in the CLI envelope (status / headers / body).
|
||||
The default method is GET; passing --data / --data-file auto-promotes it to
|
||||
POST. Use -X/--method to override (DELETE / PUT / PATCH / HEAD).
|
||||
|
||||
Auth, tenant, and request-id headers are applied automatically from the
|
||||
active context. The response body is written to stdout by default; use
|
||||
--json to wrap it in the CLI envelope (status / headers / body).
|
||||
|
||||
Examples:
|
||||
weknora api GET /api/v1/knowledge-bases
|
||||
weknora api POST /api/v1/knowledge-bases --data '{"name":"foo"}'
|
||||
weknora api DELETE /api/v1/knowledge-bases/kb_xxx`,
|
||||
Args: cobra.ExactArgs(2),
|
||||
weknora api /api/v1/knowledge-bases # GET
|
||||
weknora api /api/v1/knowledge-bases --data '{"name":"foo"}' # POST (auto)
|
||||
weknora api /api/v1/knowledge-bases/kb_xxx -X DELETE`,
|
||||
Args: cobra.ExactArgs(1),
|
||||
RunE: func(c *cobra.Command, args []string) error {
|
||||
opts.DryRun = cmdutil.IsDryRun(c)
|
||||
opts.Yes, _ = c.Flags().GetBool("yes")
|
||||
method := strings.ToUpper(args[0])
|
||||
method := resolveMethod(opts)
|
||||
// Escape-hatch DELETE through `weknora api` is just as destructive
|
||||
// as `weknora kb delete` — exit-10 protocol must apply (AGENTS.md).
|
||||
// Dry-run is read-only preview, so it skips confirmation.
|
||||
if !opts.DryRun && method == "DELETE" {
|
||||
if err := cmdutil.ConfirmDestructive(f.Prompter(), opts.Yes, opts.JSONOut, "endpoint", args[1]); err != nil {
|
||||
if !opts.DryRun && method == http.MethodDelete {
|
||||
if err := cmdutil.ConfirmDestructive(f.Prompter(), opts.Yes, opts.JSONOut, "endpoint", args[0]); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
if opts.DryRun {
|
||||
return runAPI(c.Context(), opts, nil, args[0], args[1])
|
||||
return runAPI(c.Context(), opts, nil, method, args[0])
|
||||
}
|
||||
cli, err := f.Client()
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return runAPI(c.Context(), opts, cli, args[0], args[1])
|
||||
return runAPI(c.Context(), opts, cli, method, args[0])
|
||||
},
|
||||
}
|
||||
cmd.Flags().StringVarP(&opts.Method, "method", "X", "", "HTTP method (default: GET, or POST when a body is supplied)")
|
||||
cmd.Flags().StringVarP(&opts.Data, "data", "d", "", "Request body as raw string (e.g. JSON)")
|
||||
cmd.Flags().StringVar(&opts.DataFile, "data-file", "", "Read request body from file")
|
||||
cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Wrap response in JSON envelope (status/headers/body)")
|
||||
@@ -89,14 +96,29 @@ Examples:
|
||||
return cmd
|
||||
}
|
||||
|
||||
// resolveMethod implements gh's auto-method behavior: explicit -X wins;
|
||||
// otherwise body presence promotes GET → POST.
|
||||
func resolveMethod(opts *Options) string {
|
||||
if opts.Method != "" {
|
||||
return strings.ToUpper(opts.Method)
|
||||
}
|
||||
if opts.Data != "" || opts.DataFile != "" {
|
||||
return "POST"
|
||||
}
|
||||
return "GET"
|
||||
}
|
||||
|
||||
// runAPI is the testable core: validate inputs, dispatch via Service.Raw,
|
||||
// classify status, and emit either the raw body or a JSON envelope.
|
||||
func runAPI(ctx context.Context, opts *Options, svc Service, methodArg, path string) error {
|
||||
method := strings.ToUpper(methodArg)
|
||||
// classify status, and emit either the raw body or a JSON envelope. The
|
||||
// caller is responsible for resolving the method (defaults / auto-POST)
|
||||
// and uppercasing it; runAPI guards against unsupported values like
|
||||
// `-X PATCH-INVALID` reaching the wire.
|
||||
func runAPI(ctx context.Context, opts *Options, svc Service, method, path string) error {
|
||||
switch method {
|
||||
case "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD":
|
||||
case http.MethodGet, http.MethodPost, http.MethodPut,
|
||||
http.MethodPatch, http.MethodDelete, http.MethodHead:
|
||||
default:
|
||||
return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, fmt.Sprintf("unsupported method: %s", methodArg))
|
||||
return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, fmt.Sprintf("unsupported method: %s", method))
|
||||
}
|
||||
if !strings.HasPrefix(path, "/") {
|
||||
return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, fmt.Sprintf("path must start with /: %s", path))
|
||||
@@ -118,9 +140,9 @@ func runAPI(ctx context.Context, opts *Options, svc Service, methodArg, path str
|
||||
|
||||
// --dry-run only meaningful for write methods; GET/HEAD have no side
|
||||
// effect to preview, so we proceed normally even with --dry-run.
|
||||
if opts.DryRun && method != "GET" && method != "HEAD" {
|
||||
if opts.DryRun && method != http.MethodGet && method != http.MethodHead {
|
||||
level := format.RiskWrite
|
||||
if method == "DELETE" {
|
||||
if method == http.MethodDelete {
|
||||
level = format.RiskHighRiskWrite
|
||||
}
|
||||
preview := map[string]any{"method": method, "path": path}
|
||||
|
||||
Reference in New Issue
Block a user