feat(cli): contract test suite + dependabot (PR-8)

cli/acceptance/contract/:
  envelope_test.go    — 16 envelope golden cases (9 commands × {success/error
                        variants}; 3 cases dropped with rationale: doctor.success
                        non-offline has unstable timing detail; auth_login.* needs
                        stdin/keyring scaffold deferred to v0.2; context_use.error
                        needs leaf-local --json deferred to follow-up)
  errorcodes_test.go  — single-direction AST scan of cli/cmd/ extracting first
                        arg of cmdutil.NewError / cmdutil.Wrapf calls;
                        ClassifyHTTPError dynamic-classify bridged via
                        cmdutil.ClassifyHTTPErrorOutputs() per spec §4.3.
  testdata/envelopes/ — 16 JSON golden files

helpers_test.go (PR-6 scaffold) extended:
  runCmd now wires cobra Out/Err sinks (version uses c.OutOrStdout) AND
  replicates cmd.Execute()'s error-envelope path so error-case goldens are
  populated. Without this, every error scenario's golden was 0 bytes.

cli/cmd/root.go: mapCobraError → MapCobraError, wantsJSONOutput → WantsJSONOutput
                 (exported so the contract test helper can replicate Execute()'s
                 envelope-printing path without calling Execute() itself).
                 root_test.go updated to use new exported names.

.github/dependabot.yml (新增):gomod /cli + github-actions weekly,gh-style
                              ignore semver-major to avoid noise. Open-source
                              dependency safety,independent of release cadence.

v0.1 不发布到任何分发平台 (release infra 推迟到发布窗口 milestone)。
This commit is contained in:
nullkey
2026-05-08 16:42:17 +08:00
committed by lyingbug
parent cf84bf2a38
commit bb592a59a6
38 changed files with 1245 additions and 197 deletions
+57 -1
View File
@@ -47,14 +47,28 @@ func ExitCode(err error) int {
return 1
}
// PrintError writes err to w as one human-readable line. The envelope-aware
// PrintError writes err to w in human-readable form. The envelope-aware
// JSON formatter is in `internal/format`; this helper is the human path used
// when no command produced its own output.
//
// Typed *Error values surface their Hint as a second line so users see the
// actionable next-step (matches envelope.error.hint visibility in --json).
// Falls through to defaultHint when caller didn't set one.
func PrintError(w io.Writer, err error) {
if err == nil || errors.Is(err, SilentError) {
return
}
fmt.Fprintln(w, err.Error())
var typed *Error
if errors.As(err, &typed) {
hint := typed.Hint
if hint == "" {
hint = defaultHint(typed.Code)
}
if hint != "" {
fmt.Fprintf(w, "hint: %s\n", hint)
}
}
}
// PrintErrorEnvelope writes err as a JSON envelope on w. Used in agent mode /
@@ -79,6 +93,9 @@ func ToErrorBody(err error) *format.ErrorBody {
body.Code = string(typed.Code)
body.Message = typed.Message
body.Hint = typed.Hint
if body.Hint == "" {
body.Hint = defaultHint(typed.Code)
}
body.Retryable = typed.Retryable
// Surface the wrapped cause so agents see the actual server / SDK
// error string, not just the wrap message ("hybrid search"). Stripe's
@@ -98,3 +115,42 @@ func ToErrorBody(err error) *format.ErrorBody {
body.Code = string(CodeServerError)
return body
}
// 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.
//
// Empty string for codes without a stable canonical hint.
func defaultHint(code ErrorCode) string {
switch code {
case CodeAuthUnauthenticated, CodeAuthBadCredential:
return "run `weknora auth login`"
case CodeAuthTokenExpired:
return "your session expired; run `weknora auth login` to re-authenticate"
case CodeAuthForbidden:
return "active context lacks permission for this resource"
case CodeAuthCrossTenantBlocked, CodeAuthTenantMismatch:
return "verify tenant context with `weknora whoami`"
case CodeNetworkError:
return "check base URL reachability with `weknora doctor`"
case CodeServerIncompatibleVersion:
return "run `weknora doctor` to see version skew details"
case CodeServerRateLimited:
return "rate-limited; retry after a few seconds"
case CodeServerTimeout:
return "request timed out; retry, or run `weknora doctor` to check connectivity"
case CodeResourceNotFound:
return "verify the resource ID; list available with `weknora kb list`"
case CodeInputInvalidArgument, CodeInputMissingFlag:
return "see `weknora <command> --help` for valid usage"
case CodeLocalKeychainDenied:
return "verify keyring access; falls back to file storage"
case CodeLocalConfigCorrupt:
return "remove ~/.config/weknora/config.yaml and re-run `weknora auth login`"
case CodeLocalFileIO:
return "check file permissions under $XDG_CONFIG_HOME/weknora/"
}
return ""
}
+22 -1
View File
@@ -37,6 +37,12 @@ type Factory struct {
Client func() (*sdk.Client, error)
Prompter func() prompt.Prompter
Secrets func() (secrets.Store, error)
// ContextOverride, if non-empty, replaces config.CurrentContext for this
// invocation only — set by the global --context flag in PersistentPreRun.
// Buildable Config() / Client() honor it without writing to disk; matches
// spec §1.2 "weknora --context foo kb list = single-shot override".
ContextOverride string
}
// New constructs a production Factory wired to real config / SDK client.
@@ -51,7 +57,22 @@ func New() *Factory {
secretsErr error
)
f := &Factory{}
f.Config = func() (*config.Config, error) { return config.Load() }
f.Config = func() (*config.Config, error) {
cfg, err := config.Load()
if err != nil {
// Map raw fs / parse errors to typed codes so envelopes don't
// surface bare `server.error` for what's actually a local IO /
// corrupt-config problem.
if errors.Is(err, config.ErrCorrupt) {
return nil, Wrapf(CodeLocalConfigCorrupt, err, "config malformed")
}
return nil, Wrapf(CodeLocalFileIO, err, "load config")
}
if f.ContextOverride != "" {
cfg.CurrentContext = f.ContextOverride
}
return cfg, nil
}
f.Client = func() (*sdk.Client, error) { return buildClient(f) }
f.Prompter = func() prompt.Prompter {
if iostreams.IO.IsStdoutTTY() && iostreams.IO.IsStderrTTY() {
+44
View File
@@ -2,6 +2,7 @@ package cmdutil
import (
"errors"
"os"
"testing"
"github.com/stretchr/testify/assert"
@@ -64,6 +65,49 @@ func TestNew_FoundationDefaults(t *testing.T) {
assert.Equal(t, CodeAuthUnauthenticated, typed.Code)
}
// TestFactory_ContextOverride verifies the global --context flag mechanism:
// f.ContextOverride replaces config.CurrentContext for this invocation only,
// without writing to disk. Spec §1.2.
func TestFactory_ContextOverride(t *testing.T) {
dir := t.TempDir()
t.Setenv("XDG_CONFIG_HOME", dir)
// Seed config with two contexts; CurrentContext = "default"
cfgPath := dir + "/weknora/config.yaml"
require.NoError(t, os.MkdirAll(dir+"/weknora", 0o700))
require.NoError(t, os.WriteFile(cfgPath, []byte(`
current_context: default
contexts:
default:
host: https://default.example
other:
host: https://other.example
`), 0o600))
f := New()
t.Run("no override: returns CurrentContext from disk", func(t *testing.T) {
f.ContextOverride = ""
cfg, err := f.Config()
require.NoError(t, err)
assert.Equal(t, "default", cfg.CurrentContext)
})
t.Run("override applied: ContextOverride wins over disk", func(t *testing.T) {
f.ContextOverride = "other"
cfg, err := f.Config()
require.NoError(t, err)
assert.Equal(t, "other", cfg.CurrentContext)
})
t.Run("override does not persist to disk", func(t *testing.T) {
// Reload from disk: should still be "default" (the original).
raw, err := os.ReadFile(cfgPath)
require.NoError(t, err)
assert.Contains(t, string(raw), "current_context: default")
})
}
// TestTypedPredicates exercises the namespace and code matchers.
func TestTypedPredicates(t *testing.T) {
t.Run("IsAuthError matches auth.* prefix", func(t *testing.T) {
+4 -25
View File
@@ -4,24 +4,17 @@ import (
"errors"
"fmt"
"os"
"path/filepath"
"time"
"gopkg.in/yaml.v3"
"github.com/Tencent/WeKnora/cli/internal/xdg"
)
const ttl = 24 * time.Hour
// cachePath returns $XDG_CACHE_HOME/weknora/server-info.yaml,fallback ~/.cache/weknora/.
func cachePath() (string, error) {
if x := os.Getenv("XDG_CACHE_HOME"); x != "" {
return filepath.Join(x, "weknora", "server-info.yaml"), nil
}
home, err := os.UserHomeDir()
if err != nil {
return "", fmt.Errorf("locate home dir: %w", err)
}
return filepath.Join(home, ".cache", "weknora", "server-info.yaml"), nil
return xdg.Path("XDG_CACHE_HOME", ".cache", "server-info.yaml")
}
// LoadCache reads the cached Info. Returns (info, fresh, err).
@@ -54,19 +47,5 @@ func SaveCache(info *Info) error {
if err != nil {
return err
}
if err := os.MkdirAll(filepath.Dir(p), 0700); err != nil {
return fmt.Errorf("mkdir cache dir: %w", err)
}
data, err := yaml.Marshal(info)
if err != nil {
return fmt.Errorf("marshal cache: %w", err)
}
tmp := p + ".tmp"
if err := os.WriteFile(tmp, data, 0600); err != nil {
return fmt.Errorf("write tmp cache: %w", err)
}
if err := os.Rename(tmp, p); err != nil {
return fmt.Errorf("rename cache: %w", err)
}
return nil
return xdg.WriteAtomicYAML(p, info)
}
+6 -29
View File
@@ -10,9 +10,10 @@ import (
"errors"
"fmt"
"os"
"path/filepath"
"gopkg.in/yaml.v3"
"github.com/Tencent/WeKnora/cli/internal/xdg"
)
// Config is the on-disk schema. Empty zero-value is valid (returned when the
@@ -45,19 +46,9 @@ type Context struct {
var ErrCorrupt = errors.New("config: file is malformed")
// Path returns the absolute config file path.
//
// We honor XDG_CONFIG_HOME on every OS (CLI convention — gh, kubectl, helm
// all do this even on macOS, where os.UserConfigDir would otherwise return
// ~/Library/Application Support). Falls back to ~/.config/weknora.
// Honors XDG_CONFIG_HOME via internal/xdg.
func Path() (string, error) {
if x := os.Getenv("XDG_CONFIG_HOME"); x != "" {
return filepath.Join(x, "weknora", "config.yaml"), nil
}
home, err := os.UserHomeDir()
if err != nil {
return "", fmt.Errorf("locate home dir: %w", err)
}
return filepath.Join(home, ".config", "weknora", "config.yaml"), nil
return xdg.Path("XDG_CONFIG_HOME", ".config", "config.yaml")
}
// Load reads the config file. If it does not exist, returns a zero-value
@@ -82,25 +73,11 @@ func Load() (*Config, error) {
return &c, nil
}
// Save writes the config atomically (write temp + rename) with mode 0600.
// Save writes the config atomically with mode 0600 via internal/xdg.WriteAtomicYAML.
func Save(c *Config) error {
p, err := Path()
if err != nil {
return err
}
if err := os.MkdirAll(filepath.Dir(p), 0o700); err != nil {
return fmt.Errorf("mkdir config dir: %w", err)
}
data, err := yaml.Marshal(c)
if err != nil {
return fmt.Errorf("marshal config: %w", err)
}
tmp := p + ".tmp"
if err := os.WriteFile(tmp, data, 0o600); err != nil {
return fmt.Errorf("write config: %w", err)
}
if err := os.Rename(tmp, p); err != nil {
return fmt.Errorf("rename config: %w", err)
}
return nil
return xdg.WriteAtomicYAML(p, c)
}
+3 -8
View File
@@ -13,6 +13,8 @@ import (
"os"
"path/filepath"
"strings"
"github.com/Tencent/WeKnora/cli/internal/xdg"
)
// ErrNotFound is returned when the requested secret does not exist.
@@ -50,14 +52,7 @@ func NewFileStore() (*FileStore, error) {
}
func defaultRoot() (string, error) {
if x := os.Getenv("XDG_CONFIG_HOME"); x != "" {
return filepath.Join(x, "weknora", "secrets"), nil
}
home, err := os.UserHomeDir()
if err != nil {
return "", fmt.Errorf("locate home dir: %w", err)
}
return filepath.Join(home, ".config", "weknora", "secrets"), nil
return xdg.Path("XDG_CONFIG_HOME", ".config", "secrets")
}
func (f *FileStore) path(context, key string) string {
+86
View File
@@ -0,0 +1,86 @@
// Package xdg consolidates the XDG-rooted file path lookup and atomic-write
// idioms used by config / compat / secrets / future stores.
//
// Before extraction these patterns were copy-pasted across cli/internal/{config,
// compat, secrets}; reuse review surfaced 3× duplication of Path and 2× of the
// tmp+rename atomic-write recipe. Centralizing here means a single place to fix
// behavior (mode bits, fallback dirs, mkdir order, error wrapping) and one less
// thing to copy when v0.2 adds project-link / state stores.
package xdg
import (
"fmt"
"os"
"path/filepath"
"gopkg.in/yaml.v3"
)
// Path resolves an XDG-rooted file. envVar is one of "XDG_CONFIG_HOME" /
// "XDG_CACHE_HOME" / "XDG_DATA_HOME". fallbackDir is the dot-prefixed dir
// under $HOME used when the env var is unset (".config" / ".cache" / etc.).
// parts join under "weknora/" inside the chosen root.
//
// Honors the XDG vars on every OS (CLI convention — gh / kubectl / helm all
// do this even on macOS, where os.UserConfigDir would otherwise return
// ~/Library/Application Support).
func Path(envVar, fallbackDir string, parts ...string) (string, error) {
if x := os.Getenv(envVar); x != "" {
return filepath.Join(append([]string{x, "weknora"}, parts...)...), nil
}
home, err := os.UserHomeDir()
if err != nil {
return "", fmt.Errorf("locate home dir: %w", err)
}
return filepath.Join(append([]string{home, fallbackDir, "weknora"}, parts...)...), nil
}
// WriteAtomicYAML marshals v to YAML and writes it atomically at p with mode
// 0600 (user-only). Creates parent dirs with mode 0700. Atomicity via
// CreateTemp + chmod + rename so partial writes never expose a half-baked
// file and concurrent writers never trample each other's tmp.
//
// 0600 is the appropriate floor even for non-secret stores (cache, project
// link) since they may sit alongside secrets in the same dir tree.
//
// On any failure after the tmp is created, the tmp is cleaned up so we don't
// litter the dir with `*.tmp.NNNN` artifacts on crash / cross-device errors.
func WriteAtomicYAML(p string, v any) error {
dir := filepath.Dir(p)
if err := os.MkdirAll(dir, 0o700); err != nil {
return fmt.Errorf("mkdir %s: %w", dir, err)
}
data, err := yaml.Marshal(v)
if err != nil {
return fmt.Errorf("marshal: %w", err)
}
// CreateTemp picks a unique name in dir so concurrent calls never collide
// on a shared `<p>.tmp`. Pattern reserves the suffix slot.
tmp, err := os.CreateTemp(dir, filepath.Base(p)+".tmp.*")
if err != nil {
return fmt.Errorf("create tmp in %s: %w", dir, err)
}
tmpName := tmp.Name()
// Best-effort cleanup on any failure path; no-op once Rename succeeds.
committed := false
defer func() {
if !committed {
_ = os.Remove(tmpName)
}
}()
if _, err := tmp.Write(data); err != nil {
_ = tmp.Close()
return fmt.Errorf("write %s: %w", tmpName, err)
}
if err := tmp.Close(); err != nil {
return fmt.Errorf("close %s: %w", tmpName, err)
}
if err := os.Chmod(tmpName, 0o600); err != nil {
return fmt.Errorf("chmod %s: %w", tmpName, err)
}
if err := os.Rename(tmpName, p); err != nil {
return fmt.Errorf("rename %s -> %s: %w", tmpName, p, err)
}
committed = true
return nil
}
+59
View File
@@ -0,0 +1,59 @@
package xdg_test
import (
"os"
"path/filepath"
"runtime"
"strings"
"testing"
"github.com/Tencent/WeKnora/cli/internal/xdg"
)
func TestPath_HonorsEnv(t *testing.T) {
dir := t.TempDir()
t.Setenv("XDG_CONFIG_HOME", dir)
got, err := xdg.Path("XDG_CONFIG_HOME", ".config", "config.yaml")
if err != nil {
t.Fatalf("Path: %v", err)
}
want := filepath.Join(dir, "weknora", "config.yaml")
if got != want {
t.Errorf("got %q, want %q", got, want)
}
}
func TestPath_FallsBackToHome(t *testing.T) {
t.Setenv("XDG_CACHE_HOME", "")
got, err := xdg.Path("XDG_CACHE_HOME", ".cache", "server-info.yaml")
if err != nil {
t.Fatalf("Path: %v", err)
}
if !filepath.IsAbs(got) {
t.Errorf("expected absolute path, got %q", got)
}
if !strings.Contains(got, ".cache") || !strings.Contains(got, "weknora") {
t.Errorf("expected ~/.cache/weknora prefix, got %q", got)
}
}
func TestWriteAtomicYAML_RoundTrip(t *testing.T) {
dir := t.TempDir()
p := filepath.Join(dir, "sub", "file.yaml")
type doc struct {
Name string `yaml:"name"`
}
if err := xdg.WriteAtomicYAML(p, &doc{Name: "alice"}); err != nil {
t.Fatalf("WriteAtomicYAML: %v", err)
}
if _, err := os.Stat(p); err != nil {
t.Fatalf("file not written: %v", err)
}
if runtime.GOOS != "windows" {
info, _ := os.Stat(p)
if mode := info.Mode().Perm(); mode != 0o600 {
t.Errorf("mode = %v, want 0600", mode)
}
}
}