feat(cli): add internal/{text,compat} packages and acceptance scaffold (PR-6)

text/      gh-style display-width string helpers (Truncate / FuzzyAgo / Pluralize)
compat/    server-CLI version skew probe (kubectl) + 24h TTL cache (gh internal/update)
acceptance/contract/  helpers_test.go for in-process cobra exec + golden assert
                      (uses iostreams.SetForTest singleton replacement; no t.Parallel)
cmdutil/errors.go: AllCodes() + ClassifyHTTPErrorOutputs() bridge for the
                   contract test suite (no behavior change in error handling)

go-runewidth promoted from indirect to direct (used by text.Truncate for
display-width-aware CJK truncation).

acceptance/contract/helpers_test.go forward-references cmd.NewRootCmd which
is exported in PR-7 — that file does not compile until then by design.
This commit is contained in:
nullkey
2026-05-08 15:44:32 +08:00
committed by lyingbug
parent b7388f10e1
commit 92d78dea72
17 changed files with 733 additions and 1 deletions
+72
View File
@@ -0,0 +1,72 @@
package compat
import (
"errors"
"fmt"
"os"
"path/filepath"
"time"
"gopkg.in/yaml.v3"
)
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
}
// LoadCache reads the cached Info. Returns (info, fresh, err).
//
// info == nil when no cache exists (err == nil)
// fresh == false 当 cache 不存在 / TTL 过期
func LoadCache() (*Info, bool, error) {
p, err := cachePath()
if err != nil {
return nil, false, err
}
data, err := os.ReadFile(p)
if errors.Is(err, os.ErrNotExist) {
return nil, false, nil
}
if err != nil {
return nil, false, fmt.Errorf("read cache: %w", err)
}
var info Info
if err := yaml.Unmarshal(data, &info); err != nil {
return nil, false, fmt.Errorf("parse cache: %w", err)
}
fresh := time.Since(info.ProbedAt) < ttl
return &info, fresh, nil
}
// SaveCache atomically writes Info to the cache file (mode 0600).
func SaveCache(info *Info) error {
p, err := cachePath()
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
}
+68
View File
@@ -0,0 +1,68 @@
package compat_test
import (
"path/filepath"
"testing"
"time"
"github.com/Tencent/WeKnora/cli/internal/compat"
)
func TestCache_RoundTrip(t *testing.T) {
dir := t.TempDir()
t.Setenv("XDG_CACHE_HOME", dir)
want := &compat.Info{ServerVersion: "1.2.3", ProbedAt: time.Now().UTC().Truncate(time.Second)}
if err := compat.SaveCache(want); err != nil {
t.Fatalf("SaveCache: %v", err)
}
got, fresh, err := compat.LoadCache()
if err != nil {
t.Fatalf("LoadCache: %v", err)
}
if !fresh {
t.Error("just-saved cache should be fresh")
}
if got == nil || got.ServerVersion != want.ServerVersion {
t.Errorf("ServerVersion = %v, want %q", got, want.ServerVersion)
}
// 文件应在 $XDG_CACHE_HOME/weknora/server-info.yaml
p := filepath.Join(dir, "weknora", "server-info.yaml")
if _, err := filepath.Abs(p); err != nil {
t.Errorf("path resolution: %v", err)
}
}
func TestCache_Stale(t *testing.T) {
dir := t.TempDir()
t.Setenv("XDG_CACHE_HOME", dir)
old := &compat.Info{ServerVersion: "1.2.3", ProbedAt: time.Now().Add(-25 * time.Hour)}
if err := compat.SaveCache(old); err != nil {
t.Fatalf("SaveCache: %v", err)
}
_, fresh, err := compat.LoadCache()
if err != nil {
t.Fatalf("LoadCache: %v", err)
}
if fresh {
t.Error("25h old cache should be stale")
}
}
func TestCache_Missing(t *testing.T) {
t.Setenv("XDG_CACHE_HOME", t.TempDir())
info, fresh, err := compat.LoadCache()
if err != nil {
t.Fatalf("LoadCache should not error on missing: %v", err)
}
if fresh {
t.Error("missing cache must not be fresh")
}
if info != nil {
t.Errorf("missing cache info should be nil, got %v", info)
}
}
+83
View File
@@ -0,0 +1,83 @@
package compat
import (
"fmt"
"strconv"
"strings"
)
// Level is the client-server version compat level.
type Level int
const (
OK Level = iota // 兼容
SoftWarn // 服务器旧, 部分新功能不可用
HardError // 不兼容, 需升级 CLI 或 server
)
func (l Level) String() string {
switch l {
case OK:
return "ok"
case SoftWarn:
return "soft_warn"
case HardError:
return "hard_error"
}
return "unknown"
}
// Compat compares client/server version. v0.x 阶段允许漂移:
//
// 同 major, client minor ≤ server minor → OK
// 同 major, client minor > server minor → SoftWarn (server 旧, 部分新功能不可用)
// 不同 major → HardError
// 字符串 unparseable → OK (容错, 不阻塞)
// "(unknown)" / "" → OK (dev build / server 字段缺失)
func Compat(serverVer, cliVer string) (Level, string) {
sMaj, sMin, ok := parseSemver(serverVer)
if !ok {
return OK, ""
}
cMaj, cMin, ok := parseSemver(cliVer)
if !ok {
return OK, ""
}
if sMaj != cMaj {
return HardError, fmt.Sprintf("incompatible: client %s vs server %s — upgrade required", cliVer, serverVer)
}
if cMin > sMin {
return SoftWarn, fmt.Sprintf("server is older (server %s, client %s); some new features may be unavailable", serverVer, cliVer)
}
return OK, ""
}
// parseSemver extracts (major, minor) from "X.Y.Z" or "X.Y.Z-suffix".
// Accepts the leading "v" common in `git describe` output and Tencent/WeKnora
// tag conventions ("v0.1.0"), since both server `/system/info.version` and
// the CLI's own ldflags-injected build.Version may carry it.
// Returns ok=false 当字符串无法识别 (空 / "(unknown)" / 非数字)。
func parseSemver(s string) (major, minor int, ok bool) {
if s == "" || s == "(unknown)" {
return 0, 0, false
}
// 接受 "v" 前缀 (kubectl / gh 同款宽容):git describe + Tencent tag 都带 v
s = strings.TrimPrefix(s, "v")
// 去掉 prerelease/build metadata
if i := strings.IndexAny(s, "-+"); i >= 0 {
s = s[:i]
}
parts := strings.SplitN(s, ".", 3)
if len(parts) < 2 {
return 0, 0, false
}
maj, err := strconv.Atoi(parts[0])
if err != nil {
return 0, 0, false
}
min, err := strconv.Atoi(parts[1])
if err != nil {
return 0, 0, false
}
return maj, min, true
}
+46
View File
@@ -0,0 +1,46 @@
package compat_test
import (
"strings"
"testing"
"github.com/Tencent/WeKnora/cli/internal/compat"
)
func TestCompat(t *testing.T) {
tests := []struct {
name string
serverVer string
cliVer string
wantLevel compat.Level
wantHintHas string
}{
{"equal", "1.2.3", "1.2.3", compat.OK, ""},
{"client minor lower", "1.5.0", "1.2.0", compat.OK, ""},
{"client minor higher", "1.2.0", "1.5.0", compat.SoftWarn, "server is older"},
{"different major", "1.9.9", "2.0.0", compat.HardError, "incompatible"},
{"client unset", "1.2.3", "(unknown)", compat.OK, ""}, // dev build, 不报警
{"server unset", "", "1.2.3", compat.OK, ""},
{"malformed server", "garbage", "1.2.3", compat.OK, ""}, // 不阻塞
// "v" prefix tolerance (git describe + Tencent tag convention)
{"v-prefix both", "v1.2.0", "v1.5.0", compat.SoftWarn, "server is older"},
{"v-prefix server only", "v1.9.9", "2.0.0", compat.HardError, "incompatible"},
{"v-prefix cli only", "1.9.9", "v2.0.0", compat.HardError, "incompatible"},
// Hint must be empty when level == OK (no false positives)
{"OK hint empty", "1.2.3", "1.2.3", compat.OK, ""},
}
for _, tt := range tests {
gotLevel, gotHint := compat.Compat(tt.serverVer, tt.cliVer)
if gotLevel != tt.wantLevel {
t.Errorf("%s: Level = %v, want %v", tt.name, gotLevel, tt.wantLevel)
}
if tt.wantHintHas != "" && !strings.Contains(gotHint, tt.wantHintHas) {
t.Errorf("%s: hint = %q, should contain %q", tt.name, gotHint, tt.wantHintHas)
}
if tt.wantLevel == compat.OK && gotHint != "" {
t.Errorf("%s: OK level should have empty hint, got %q", tt.name, gotHint)
}
}
}
+40
View File
@@ -0,0 +1,40 @@
// Package compat probes server `/system/info` and decides client-server
// version skew level. Used by `weknora doctor` 的 server_version 检查项。
//
// Mirrors gh internal/update/update.go cache pattern (24h TTL state file)
// and kubectl pkg/version/skew_warning.go three-tier compat semantics
// (major-mismatch=hard / minor-mismatch=soft / equal=ok).
package compat
import (
"context"
"fmt"
"time"
sdk "github.com/Tencent/WeKnora/client"
)
// Info is the cached server version snapshot.
type Info struct {
ServerVersion string `yaml:"server_version"`
EngineInfo map[string]string `yaml:"engine_info,omitempty"`
ProbedAt time.Time `yaml:"probed_at"`
}
// ProbeService is the narrow SDK surface compat depends on (testability via
// fake; mirrors v0.0 service interface pattern).
type ProbeService interface {
GetSystemInfo(ctx context.Context) (*sdk.SystemInfo, error)
}
// Probe calls server /system/info and returns a fresh Info snapshot.
func Probe(ctx context.Context, c ProbeService) (*Info, error) {
resp, err := c.GetSystemInfo(ctx)
if err != nil {
return nil, fmt.Errorf("probe server: %w", err)
}
return &Info{
ServerVersion: resp.Version,
ProbedAt: time.Now(),
}, nil
}
+41
View File
@@ -0,0 +1,41 @@
package compat_test
import (
"context"
"errors"
"testing"
"github.com/Tencent/WeKnora/cli/internal/compat"
sdk "github.com/Tencent/WeKnora/client"
)
type fakeProbeClient struct {
info *sdk.SystemInfo
err error
}
func (f *fakeProbeClient) GetSystemInfo(ctx context.Context) (*sdk.SystemInfo, error) {
return f.info, f.err
}
func TestProbe_Success(t *testing.T) {
c := &fakeProbeClient{info: &sdk.SystemInfo{Version: "1.2.3"}}
got, err := compat.Probe(context.Background(), c)
if err != nil {
t.Fatalf("Probe: %v", err)
}
if got.ServerVersion != "1.2.3" {
t.Errorf("ServerVersion = %q, want %q", got.ServerVersion, "1.2.3")
}
if got.ProbedAt.IsZero() {
t.Error("ProbedAt should be set")
}
}
func TestProbe_Error(t *testing.T) {
c := &fakeProbeClient{err: errors.New("HTTP error 500: down")}
_, err := compat.Probe(context.Background(), c)
if err == nil {
t.Fatal("expected error")
}
}