feat(cli): agent-first WeKnora CLI
The `weknora` command-line client for the WeKnora RAG server. Full command surface: kb / doc / chunk / session / message / agent / model / search / chat / auth / profile / link / api / mcp / skills / config / doctor / schema / exit-codes. Agent-first wire contract: JSON envelope by default, typed error codes mapped to stable exit codes, error.retry_argv / retryable / partial-failure status, global --dry-run preview, the exit-10 confirmation protocol for writes, and control/ANSI/Bidi input hygiene. Stateless env-credential auth (WEKNORA_API_KEY / WEKNORA_TOKEN + WEKNORA_HOST) for headless/CI/agent use. A curated read-only MCP tool surface (`mcp serve`) and embedded Agent Skills (`skills install`). Extensive unit + contract-golden tests and CI.
This commit is contained in:
@@ -74,7 +74,7 @@ func runList(fopts *cmdutil.FormatOptions, f *cmdutil.Factory) error {
|
||||
sort.Slice(entries, func(i, j int) bool { return entries[i].Name < entries[j].Name })
|
||||
|
||||
if fopts.WantsJSON() {
|
||||
meta := &output.Meta{Count: len(entries)}
|
||||
meta := &output.Meta{Count: output.IntPtr(len(entries))}
|
||||
return fopts.Emit(iostreams.IO.Out, entries, meta)
|
||||
}
|
||||
if len(entries) == 0 {
|
||||
|
||||
@@ -20,7 +20,7 @@ import (
|
||||
// keyring; agents who need to verify the credential should re-run
|
||||
// `auth status`.
|
||||
var authLoginFields = []string{
|
||||
"profile", "host", "mode", "user", "tenant_id",
|
||||
"profile", "host", "mode", "email", "tenant_id",
|
||||
}
|
||||
|
||||
// LoginOptions is the configuration captured from flags + prompts. Host and
|
||||
@@ -104,7 +104,7 @@ Credentials are persisted to the OS keyring when available; otherwise to a
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "authenticate the active profile; --with-token reads an API key from stdin (non-interactive)",
|
||||
Examples: []string{`echo "$WEKNORA_API_KEY" | weknora auth login --with-token`},
|
||||
Output: "envelope.data is {profile, host, mode, user, tenant_id} on success",
|
||||
Output: "envelope.data is {profile, host, mode, email, tenant_id} on success (email matches `auth status`)",
|
||||
Warnings: []string{
|
||||
"a profile must exist and be active first (`weknora profile add <n> --host <url> --use`)",
|
||||
"password login is interactive-only (no flags) — agents must use --with-token with the key piped to stdin",
|
||||
@@ -171,7 +171,7 @@ func runLogin(ctx context.Context, opts *LoginOptions, fopts *cmdutil.FormatOpti
|
||||
}
|
||||
// Reject shell-metacharacter / path-like names up-front so opts.Profile
|
||||
// stays safe to interpolate into the keyring namespace, config.yaml
|
||||
// keys, and (later) envelope.error.retry_command. Matches `profile add`.
|
||||
// keys, and envelope.error.retry_argv. Matches `profile add`.
|
||||
if err := cmdutil.ValidateProfileName(opts.Profile); err != nil {
|
||||
return err
|
||||
}
|
||||
@@ -313,7 +313,10 @@ type loginResult struct {
|
||||
Profile string `json:"profile"`
|
||||
Host string `json:"host"`
|
||||
Mode string `json:"mode"` // ModeBearer or ModeAPIKey
|
||||
User string `json:"user,omitempty"`
|
||||
// Email is the authenticated principal's email. Named "email" (not
|
||||
// "user") so the identity field matches `auth status`, which also
|
||||
// exposes it as `email` — one key for one concept across both commands.
|
||||
Email string `json:"email,omitempty"`
|
||||
TenantID uint64 `json:"tenant_id,omitempty"`
|
||||
}
|
||||
|
||||
@@ -344,7 +347,7 @@ func saveProfileRef(opts *LoginOptions, fopts *cmdutil.FormatOptions, f *cmdutil
|
||||
// user != nil would mislabel it as bearer.
|
||||
result := loginResult{Profile: opts.Profile, Host: opts.Host, Mode: mode}
|
||||
if user != nil {
|
||||
result.User = user.Email
|
||||
result.Email = user.Email
|
||||
result.TenantID = user.TenantID
|
||||
}
|
||||
return fopts.Emit(iostreams.IO.Out, result, nil)
|
||||
|
||||
@@ -92,6 +92,7 @@ accepted until it expires.`,
|
||||
"weknora --profile staging auth logout",
|
||||
"weknora auth logout --all",
|
||||
},
|
||||
Output: "envelope.data is {removed: [profile names cleared]}",
|
||||
Warnings: []string{
|
||||
"Requires explicit user approval (exit 10 / input.confirmation_required); never auto-add -y.",
|
||||
"auth logout clears local credentials for this profile; server-side session continues until expiry.",
|
||||
@@ -116,9 +117,9 @@ func runLogout(opts *LogoutOptions, fopts *cmdutil.FormatOptions, f *cmdutil.Fac
|
||||
|
||||
// Destructive-write protocol: confirm before clearing credentials.
|
||||
scope := fmt.Sprintf("%d profile(s) [%s]", len(targets), strings.Join(targets, ", "))
|
||||
retryCmd := "weknora auth logout -y"
|
||||
retryCmd := []string{"weknora", "auth", "logout", "-y"}
|
||||
if opts.All {
|
||||
retryCmd = "weknora auth logout --all -y"
|
||||
retryCmd = []string{"weknora", "auth", "logout", "--all", "-y"}
|
||||
}
|
||||
if err := cmdutil.ConfirmDestructive(f.Prompter(), opts.Yes, fopts.WantsJSON(), "delete", "auth credentials", scope, "auth.logout", retryCmd); err != nil {
|
||||
return err
|
||||
|
||||
+26
-9
@@ -3,6 +3,8 @@ package auth
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"os"
|
||||
"strings"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
|
||||
@@ -14,7 +16,7 @@ import (
|
||||
// authStatusFields enumerates the fields surfaced for `--format json` discovery
|
||||
// on `auth status`. Single-resource shape: filter applies to data itself.
|
||||
var authStatusFields = []string{
|
||||
"profile", "user_id", "username", "email", "is_active",
|
||||
"profile", "host", "auth_source", "user_id", "username", "email", "is_active",
|
||||
"can_access_all_tenants", "tenant_id", "tenant_name",
|
||||
}
|
||||
|
||||
@@ -29,6 +31,8 @@ type StatusService interface {
|
||||
// account) without a second round-trip.
|
||||
type statusResult struct {
|
||||
Profile string `json:"profile"`
|
||||
Host string `json:"host,omitempty"`
|
||||
AuthSource string `json:"auth_source,omitempty"`
|
||||
UserID string `json:"user_id,omitempty"`
|
||||
Username string `json:"username,omitempty"`
|
||||
Email string `json:"email,omitempty"`
|
||||
@@ -68,7 +72,7 @@ usually only surfaces a hard auth failure.`,
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "show the active profile, the authenticated principal, and token state",
|
||||
Examples: []string{"weknora auth status", "weknora auth status --jq .data.tenant_id"},
|
||||
Output: "envelope.data is {profile, host, user, tenant, ...}; exit 3 if unauthenticated",
|
||||
Output: "envelope.data is {profile, host, auth_source, user_id, username, email, tenant_id, tenant_name, ...}; auth_source is 'profile + keyring' or a stateless env credential; exit 3 if unauthenticated",
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
@@ -89,8 +93,24 @@ func runStatus(ctx context.Context, fopts *cmdutil.FormatOptions, f *cmdutil.Fac
|
||||
return err
|
||||
}
|
||||
|
||||
// Effective host + auth source. Stateless env credentials
|
||||
// (WEKNORA_TOKEN/WEKNORA_API_KEY) override the profile + keyring for the
|
||||
// client, so report the host they authenticate against (WEKNORA_HOST) and
|
||||
// that they are in effect — not the bypassed config profile's host.
|
||||
host := ""
|
||||
if c, ok := cfg.Profiles[cfg.CurrentProfile]; ok {
|
||||
host = c.Host
|
||||
}
|
||||
authSource := "profile + keyring"
|
||||
if active, kind := cmdutil.EnvCredential(); active {
|
||||
authSource = kind + " env (stateless)"
|
||||
if h := strings.TrimSpace(os.Getenv("WEKNORA_HOST")); h != "" {
|
||||
host = h
|
||||
}
|
||||
}
|
||||
|
||||
if fopts.WantsJSON() {
|
||||
result := statusResult{Profile: cfg.CurrentProfile}
|
||||
result := statusResult{Profile: cfg.CurrentProfile, Host: host, AuthSource: authSource}
|
||||
if user != nil {
|
||||
result.UserID = user.ID
|
||||
result.Username = user.Username
|
||||
@@ -105,12 +125,9 @@ func runStatus(ctx context.Context, fopts *cmdutil.FormatOptions, f *cmdutil.Fac
|
||||
return fopts.Emit(iostreams.IO.Out, result, nil)
|
||||
}
|
||||
|
||||
host := ""
|
||||
if c, ok := cfg.Profiles[cfg.CurrentProfile]; ok {
|
||||
host = c.Host
|
||||
}
|
||||
fmt.Fprintf(iostreams.IO.Out, "profile: %s\n", cfg.CurrentProfile)
|
||||
fmt.Fprintf(iostreams.IO.Out, "host: %s\n", host)
|
||||
fmt.Fprintf(iostreams.IO.Out, "profile: %s\n", cfg.CurrentProfile)
|
||||
fmt.Fprintf(iostreams.IO.Out, "auth_source: %s\n", authSource)
|
||||
fmt.Fprintf(iostreams.IO.Out, "host: %s\n", host)
|
||||
if user != nil {
|
||||
fmt.Fprintf(iostreams.IO.Out, "user: %s (%s)\n", user.Email, user.ID)
|
||||
fmt.Fprintf(iostreams.IO.Out, "tenant: %d", user.TenantID)
|
||||
|
||||
@@ -54,8 +54,9 @@ func TestRunStatus_TextOutput(t *testing.T) {
|
||||
}
|
||||
require.NoError(t, runStatus(context.Background(), &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, f, svc))
|
||||
got := out.String()
|
||||
assert.Contains(t, got, "profile: prod")
|
||||
assert.Contains(t, got, "host: https://kb.example.com")
|
||||
assert.Contains(t, got, "profile: prod")
|
||||
assert.Contains(t, got, "auth_source: profile + keyring")
|
||||
assert.Contains(t, got, "host: https://kb.example.com")
|
||||
assert.Contains(t, got, "alice@example.com")
|
||||
assert.Contains(t, got, "Acme")
|
||||
}
|
||||
|
||||
@@ -57,9 +57,9 @@ to see which mode each profile uses, and construct the matching HTTP header:
|
||||
}
|
||||
// `auth token` is a scalar scripting helper (WEKNORA_TOKEN=$(...)),
|
||||
// so it defaults to the raw token — overriding the global json
|
||||
// default (gh auth token does the same; cf. doc download streaming
|
||||
// raw bytes). Explicit --format json / WEKNORA_FORMAT=json still
|
||||
// emit the {token,mode,profile} envelope.
|
||||
// default, the same way `doc download` streams raw bytes. Explicit
|
||||
// --format json / WEKNORA_FORMAT=json still emit the
|
||||
// {token,mode,profile} envelope.
|
||||
fopts.FromEnv()
|
||||
if fopts.Mode == "" {
|
||||
// --jq implies JSON (it filters the envelope); without it,
|
||||
@@ -83,7 +83,7 @@ to see which mode each profile uses, and construct the matching HTTP header:
|
||||
},
|
||||
Output: "raw token on stdout (no envelope, no trailing newline) by default; --format json emits {token, mode, profile}",
|
||||
Warnings: []string{
|
||||
"default output is the bare token, NOT the JSON envelope — it is a scripting helper (cf. `gh auth token`)",
|
||||
"default output is the bare token, NOT the JSON envelope — it is a scripting helper for shell capture",
|
||||
},
|
||||
})
|
||||
return cmd
|
||||
|
||||
Reference in New Issue
Block a user