WeKnora deployment source with the reviewed wiki identity, summary and recovery fixes

cli/acceptance/contract/errorcodes_test.go

@@ -0,0 +1,214 @@
+// cli/acceptance/contract/errorcodes_test.go
+package contract_test
+
+import (
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/Tencent/WeKnora/cli/internal/cmdutil"
+)
+
+// TestAllReferencedCodesAreRegistered scans cli/cmd/ for every literal use of
+// cmdutil.NewError(codeXxx, ...) and cmdutil.Wrapf(codeXxx, ...) and verifies
+// that codeXxx is registered in cmdutil.AllCodes().
+//
+// ClassifyHTTPError is dynamic - callers don't pass a literal CodeXxx
+// ident. Most SDK call sites go through cmdutil.WrapHTTP(err, ...) which
+// the scanner skips entirely (it only inspects NewError / Wrapf selector
+// names). A few sites still call ClassifyHTTPError directly to inspect
+// or remap the code; those are call-expression args the scanner also
+// skips. Either way, the codes those paths can yield are bridged via
+// cmdutil.ClassifyHTTPErrorOutputs(), which enumerates every code the
+// switch can return - added to the registered set so the AST scanner
+// doesn't false-positive on them.
+//
+// Limitations:
+//   - Only literal cmdutil.CodeXxx idents are detected; codes assigned to
+//     a local variable then passed are NOT scanned (rare pattern).
+//   - cmdutil.WrapHTTP(...) and cmdutil.ClassifyHTTPError(...) call
+//     expressions are skipped - the ClassifyHTTPErrorOutputs bridge
+//     covers their dynamic codes.
+func TestAllReferencedCodesAreRegistered(t *testing.T) {
+	registered := make(map[cmdutil.ErrorCode]struct{})
+	for _, c := range cmdutil.AllCodes() {
+		registered[c] = struct{}{}
+	}
+	// Bridge: ClassifyHTTPError returns these dynamically; treat them as
+	// "registered" for the purposes of the AST scan since callers pass the
+	// function call (not a literal ident) as arg0.
+	for _, c := range cmdutil.ClassifyHTTPErrorOutputs() {
+		registered[c] = struct{}{}
+	}
+
+	referenced := scanCmdDir(t, "../../cmd")
+
+	for code, locs := range referenced {
+		if _, ok := registered[code]; !ok {
+			for _, loc := range locs {
+				t.Errorf("%s: error code %q referenced but not registered in cmdutil.AllCodes()", loc, code)
+			}
+		}
+	}
+}
+
+// scanCmdDir walks cli/cmd/** for *.go files (excluding tests) and collects
+// every literal cmdutil.CodeXxx ident passed as the first arg to
+// cmdutil.NewError / cmdutil.Wrapf.
+//
+// Returns map keyed by ErrorCode value (the const's underlying string), with
+// a slice of source positions for nicer error messages.
+func scanCmdDir(t *testing.T, dir string) map[cmdutil.ErrorCode][]token.Position {
+	t.Helper()
+	out := make(map[cmdutil.ErrorCode][]token.Position)
+	fset := token.NewFileSet()
+	walkAndScan(t, fset, dir, out)
+	return out
+}
+
+func walkAndScan(t *testing.T, fset *token.FileSet, root string, out map[cmdutil.ErrorCode][]token.Position) {
+	t.Helper()
+	err := filepath.Walk(root, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+		if info.IsDir() {
+			return nil
+		}
+		if filepath.Ext(path) != ".go" {
+			return nil
+		}
+		if strings.HasSuffix(path, "_test.go") {
+			return nil
+		}
+		f, err := parser.ParseFile(fset, path, nil, 0)
+		if err != nil {
+			t.Fatalf("parse %s: %v", path, err)
+		}
+		collectErrorCodes(fset, f, out)
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("walk %s: %v", root, err)
+	}
+}
+
+func collectErrorCodes(fset *token.FileSet, f *ast.File, out map[cmdutil.ErrorCode][]token.Position) {
+	ast.Inspect(f, func(n ast.Node) bool {
+		call, ok := n.(*ast.CallExpr)
+		if !ok || len(call.Args) == 0 {
+			return true
+		}
+		sel, ok := call.Fun.(*ast.SelectorExpr)
+		if !ok {
+			return true
+		}
+		x, ok := sel.X.(*ast.Ident)
+		if !ok || x.Name != "cmdutil" {
+			return true
+		}
+		if sel.Sel.Name != "NewError" && sel.Sel.Name != "Wrapf" {
+			return true
+		}
+		// First arg should be cmdutil.CodeXxx (SelectorExpr ident).
+		// If it's a function call (e.g. cmdutil.ClassifyHTTPError(err)), skip
+		// - bridge handles those.
+		arg0Sel, ok := call.Args[0].(*ast.SelectorExpr)
+		if !ok {
+			return true
+		}
+		argX, ok := arg0Sel.X.(*ast.Ident)
+		if !ok || argX.Name != "cmdutil" {
+			return true
+		}
+		code, ok := identToErrorCode(arg0Sel.Sel.Name)
+		if !ok {
+			// Unknown ident name - record as bogus so the test fails with
+			// a clear "code referenced but not registered" message.
+			code = cmdutil.ErrorCode("UNKNOWN_REF:" + arg0Sel.Sel.Name)
+		}
+		pos := fset.Position(call.Pos())
+		out[code] = append(out[code], pos)
+		return true
+	})
+}
+
+// identToErrorCode maps an ident name like "CodeAuthUnauthenticated" to its
+// underlying ErrorCode value via a simple switch. Avoids reflect.
+// Keep in sync with cmdutil.AllCodes() - adding a new const here is the same
+// bookkeeping as adding it to AllCodes().
+func identToErrorCode(name string) (cmdutil.ErrorCode, bool) {
+	switch name {
+	case "CodeAuthUnauthenticated":
+		return cmdutil.CodeAuthUnauthenticated, true
+	case "CodeAuthTokenExpired":
+		return cmdutil.CodeAuthTokenExpired, true
+	case "CodeAuthBadCredential":
+		return cmdutil.CodeAuthBadCredential, true
+	case "CodeAuthForbidden":
+		return cmdutil.CodeAuthForbidden, true
+	case "CodeAuthCrossTenantBlocked":
+		return cmdutil.CodeAuthCrossTenantBlocked, true
+	case "CodeAuthTenantMismatch":
+		return cmdutil.CodeAuthTenantMismatch, true
+	case "CodeResourceNotFound":
+		return cmdutil.CodeResourceNotFound, true
+	case "CodeResourceAlreadyExists":
+		return cmdutil.CodeResourceAlreadyExists, true
+	case "CodeResourceLocked":
+		return cmdutil.CodeResourceLocked, true
+	case "CodeInputInvalidArgument":
+		return cmdutil.CodeInputInvalidArgument, true
+	case "CodeInputMissingFlag":
+		return cmdutil.CodeInputMissingFlag, true
+	case "CodeInputConfirmationRequired":
+		return cmdutil.CodeInputConfirmationRequired, true
+	case "CodeInputUnknownSubcommand":
+		return cmdutil.CodeInputUnknownSubcommand, true
+	case "CodeServerError":
+		return cmdutil.CodeServerError, true
+	case "CodeServerTimeout":
+		return cmdutil.CodeServerTimeout, true
+	case "CodeServerRateLimited":
+		return cmdutil.CodeServerRateLimited, true
+	case "CodeServerIncompatibleVersion":
+		return cmdutil.CodeServerIncompatibleVersion, true
+	case "CodeNetworkError":
+		return cmdutil.CodeNetworkError, true
+	case "CodeLocalConfigCorrupt":
+		return cmdutil.CodeLocalConfigCorrupt, true
+	case "CodeLocalKeychainDenied":
+		return cmdutil.CodeLocalKeychainDenied, true
+	case "CodeLocalFileIO":
+		return cmdutil.CodeLocalFileIO, true
+	case "CodeLocalProfileNotFound":
+		return cmdutil.CodeLocalProfileNotFound, true
+	case "CodeKBIDRequired":
+		return cmdutil.CodeKBIDRequired, true
+	case "CodeKBNotFound":
+		return cmdutil.CodeKBNotFound, true
+	case "CodeProjectLinkCorrupt":
+		return cmdutil.CodeProjectLinkCorrupt, true
+	case "CodeUserAborted":
+		return cmdutil.CodeUserAborted, true
+	case "CodeUploadFileNotFound":
+		return cmdutil.CodeUploadFileNotFound, true
+	case "CodeSSEStreamAborted":
+		return cmdutil.CodeSSEStreamAborted, true
+	case "CodeSessionCreateFailed":
+		return cmdutil.CodeSessionCreateFailed, true
+	case "CodeOperationTimeout":
+		return cmdutil.CodeOperationTimeout, true
+	case "CodeOperationFailed":
+		return cmdutil.CodeOperationFailed, true
+	case "CodeOperationCancelled":
+		return cmdutil.CodeOperationCancelled, true
+	case "CodeInternalError":
+		return cmdutil.CodeInternalError, true
+	}
+	return "", false
+}

cli/acceptance/contract/helpers_test.go

@@ -0,0 +1,118 @@
+// cli/acceptance/contract/helpers_test.go
+package contract_test
+
+import (
+	"bytes"
+	"context"
+	"flag"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/Tencent/WeKnora/cli/cmd"
+	"github.com/Tencent/WeKnora/cli/cmd/doctor"
+	"github.com/Tencent/WeKnora/cli/internal/cmdutil"
+	"github.com/Tencent/WeKnora/cli/internal/iostreams"
+	"github.com/Tencent/WeKnora/cli/internal/secrets"
+	sdk "github.com/Tencent/WeKnora/client"
+)
+
+// TestMain pins the doctor credential-storage outcome for the whole suite.
+// Otherwise the check probes the real OS keyring, which differs between
+// macOS dev machines (Keychain present → ok) and Linux CI runners without
+// libsecret (file fallback → warn), making golden outputs host-dependent.
+// MemStore is neither *FileStore nor a real keyring, so the doctor's
+// type-switch hits the StatusOK branch.
+func TestMain(m *testing.M) {
+	restore := doctor.SetCredStoreFactoryForTest(func() (secrets.Store, error) {
+		return secrets.NewMemStore(), nil
+	})
+	defer restore()
+	os.Exit(m.Run())
+}
+
+// update is the standard Go test golden-update flag.
+//
+//	go test -update ./acceptance/contract/...
+var update = flag.Bool("update", false, "update golden files")
+
+// newTestFactory builds a Factory whose Client returns mockClient.
+// Caller must NOT use t.Parallel() - see iostreams.SetForTest contract.
+//
+// WEKNORA_BASE_URL is set when mockServer is non-nil. buildClient does not
+// currently honor this env var (it reads from config.Host); commands that
+// need the mock URL rely on the mockClient injection above. The env is set
+// anyway for any direct net/http callers (e.g. doctor's HEAD /health).
+func newTestFactory(t *testing.T, mockServer *httptest.Server, mockClient *sdk.Client) *cmdutil.Factory {
+	t.Helper()
+	t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+	t.Setenv("XDG_CACHE_HOME", t.TempDir())
+	if mockServer != nil {
+		t.Setenv("WEKNORA_BASE_URL", mockServer.URL)
+	}
+	f := cmdutil.New()
+	if mockClient != nil {
+		f.Client = func() (*sdk.Client, error) { return mockClient, nil }
+	}
+	return f
+}
+
+// runCmd executes the root command in-process and returns captured stdout/stderr.
+// Replaces iostreams.IO singleton via SetForTest (auto-restored in t.Cleanup).
+//
+// Mirrors cmd.Execute(): wires the cobra Out / Err sinks to the same buffers
+// it returns, and re-runs cmdutil.PrintError on stderr for failure cases so
+// the contract assertion sees the typed `code: message\nhint: ...` line.
+func runCmd(t *testing.T, f *cmdutil.Factory, args ...string) (stdout, stderr string, exitCode int) {
+	t.Helper()
+	out, errBuf := iostreams.SetForTest(t)
+	root := cmd.NewRootCmd(f) // exported in cli/cmd/root.go (Task 16)
+	root.SetArgs(args)
+	root.SetContext(context.Background())
+	root.SetOut(out)
+	root.SetErr(errBuf)
+	_, err := root.ExecuteC()
+	if err != nil {
+		err = cmd.MapCobraError(err)
+		cmdutil.PrintError(iostreams.IO.Err, err)
+	}
+	return out.String(), errBuf.String(), cmdutil.ExitCode(err)
+}
+
+// assertGolden compares got against the JSON golden file at path.
+// With -update, writes got to path.
+//
+// CRLF normalization: Windows checkouts with the default core.autocrlf=true
+// turn LF in tracked text files into CRLF on disk. The command output is
+// always LF, so byte-equal would fail despite identical content.
+// .gitattributes is the primary defense (forcing LF on testdata/**/*.json),
+// but we also strip CR here so a misconfigured contributor checkout doesn't
+// break the suite locally before they push.
+func assertGolden(t *testing.T, got []byte, path string) {
+	t.Helper()
+	if *update {
+		if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {
+			t.Fatalf("mkdir testdata: %v", err)
+		}
+		if err := os.WriteFile(path, got, 0644); err != nil {
+			t.Fatalf("write golden: %v", err)
+		}
+		return
+	}
+	want, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read golden %s: %v (run with -update to create)", path, err)
+	}
+	want = stripCR(want)
+	got = stripCR(got)
+	if !bytes.Equal(want, got) {
+		t.Errorf("stdout mismatch for %s\nwant:\n%s\ngot:\n%s", path, want, got)
+	}
+}
+
+// stripCR removes CR bytes so CRLF golden files (from Windows autocrlf
+// checkout) compare equal to LF runtime output.
+func stripCR(b []byte) []byte {
+	return bytes.ReplaceAll(b, []byte{'\r'}, nil)
+}

cli/acceptance/contract/wire_test.go

@@ -0,0 +1,372 @@
+// cli/acceptance/contract/wire_test.go
+//
+// Wire contract test. Drives root cobra in-process for each scenario,
+// captures stdout + stderr, and asserts:
+//
+//   - stdout matches a JSON golden in cli/acceptance/testdata/wire/
+//   - on wantErr cases, stderr contains the expected typed error code
+//
+// Successful cases produce bare JSON on stdout (no envelope wrapper);
+// failure cases produce empty stdout (or, for `doctor`, the data object
+// the command writes before returning SilentError) and a `code: msg`
+// line on stderr.
+//
+// Cases intentionally omitted (with reason):
+//   - doctor.success                            - non-offline path emits
+//     unstable timing
+//     ("reachable in 2ms").
+//     Unit tests in cli/cmd/doctor
+//     cover the all-pass shape;
+//     doctor.success_offline is
+//     the deterministic sibling
+//     kept here.
+//   - auth_login.success                        - requires stdin pipe
+//     (--with-token) + keyring-
+//     aware Secrets store; the
+//     helper does not yet expose
+//     a stdin hook.
+//   - auth_login.error_auth_unauthenticated     - same setup as above.
+//
+// All cases use leaf-positioned --format json (e.g. `version --format json`). --format is a
+// per-leaf flag, not a global persistent flag.
+package contract_test
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/Tencent/WeKnora/cli/internal/config"
+	sdk "github.com/Tencent/WeKnora/client"
+)
+
+// wireCase declares one row in the contract matrix. Optional fields:
+//
+//	server               - mock /api/v1/* endpoints; nil means no network.
+//	preConfig            - seed config.yaml under the per-test XDG_CONFIG_HOME
+//	                       (set by newTestFactory); use for cases like
+//	                       `profile use` that read local state without an
+//	                       SDK round-trip.
+//	wantErr              - non-zero exit expected.
+//	wantStderrSubstring  - stderr must contain this substring (typically the
+//	                       typed error code, e.g. "auth.unauthenticated").
+//	                       Only meaningful when wantErr=true.
+type wireCase struct {
+	name                string
+	args                []string
+	server              http.HandlerFunc
+	preConfig           func(t *testing.T)
+	wantErr             bool
+	wantStderrSubstring string
+}
+
+// wireCases enumerates every contract scenario whose stdout is golden-pinned.
+// Order is illustrative, not load-bearing.
+var wireCases = []wireCase{
+	// 1. version.success - pure local; no client touched.
+	{
+		name: "version.success",
+		args: []string{"version", "--format", "json"},
+	},
+
+	// 2. doctor.success_offline - only credential_storage runs; the three
+	//    network checks are skipped. Stable details + summary.
+	{
+		name:   "doctor.success_offline",
+		args:   []string{"doctor", "--offline", "--format", "json"},
+		server: doctorReachable, // ensures buildServices succeeds even if probed
+	},
+
+	// 3. doctor.error_network - base_url returns 500 → ping fail → cascade
+	//    skip on auth_credential + server_version. credential_storage still
+	//    runs (independent). Contract: any check=fail bumps summary.failed
+	//    and RunE returns SilentError → exit 1 with the data object
+	//    written by emit() as the only stdout content.
+	{
+		name:    "doctor.error_network",
+		args:    []string{"doctor", "--format", "json"},
+		server:  alwaysServerError,
+		wantErr: true,
+	},
+
+	// 4-7. kb list / get - SDK paths /api/v1/knowledge-bases[/<id>]
+	{
+		name:   "kb_list.success",
+		args:   []string{"kb", "list", "--format", "json"},
+		server: kbListTwo,
+	},
+	{
+		name:   "kb_list.success_empty",
+		args:   []string{"kb", "list", "--format", "json"},
+		server: kbListEmpty,
+	},
+	{
+		name:                "kb_list.error_auth_forbidden",
+		args:                []string{"kb", "list", "--format", "json"},
+		server:              always403,
+		wantErr:             true,
+		wantStderrSubstring: "auth.forbidden",
+	},
+	{
+		name:   "kb_view.success",
+		args:   []string{"kb", "view", "kb1", "--format", "json"},
+		server: kbGetOne,
+	},
+	{
+		name:                "kb_view.error_resource_not_found",
+		args:                []string{"kb", "view", "missing", "--format", "json"},
+		server:              always404,
+		wantErr:             true,
+		wantStderrSubstring: "resource.not_found",
+	},
+
+	// 8. profile use - pure local I/O against config.yaml.
+	{
+		name: "profile_use.success",
+		args: []string{"profile", "use", "production", "--format", "json"},
+		preConfig: func(t *testing.T) {
+			cfg := &config.Config{
+				CurrentProfile: "staging",
+				Profiles: map[string]config.Profile{
+					"staging":    {Host: "https://staging.example.com"},
+					"production": {Host: "https://prod.example.com"},
+				},
+			}
+			if err := config.Save(cfg); err != nil {
+				t.Fatalf("seed config: %v", err)
+			}
+		},
+	},
+	// (profile_use.error_local_context_not_found dropped - see file header.)
+
+	// 9-10. auth status - SDK /api/v1/auth/me, plus config inspection.
+	{
+		name:   "auth_status.success",
+		args:   []string{"auth", "status", "--format", "json"},
+		server: whoamiOK,
+	},
+	{
+		name:                "auth_status.error_auth_unauthenticated",
+		args:                []string{"auth", "status", "--format", "json"},
+		server:              always401,
+		wantErr:             true,
+		wantStderrSubstring: "auth.unauthenticated",
+	},
+
+	// 11-13. search chunks - verb-noun shape, positional query, --kb required.
+	// --kb accepts either a kb_<id> (passed through) or a name (resolved via
+	// list); UUID-format detection happens client-side so callers can use
+	// either form interchangeably.
+	{
+		name:   "search.success",
+		args:   []string{"search", "chunks", "query", "--kb=11111111-1111-4111-8111-111111111111", "--limit=3", "--format", "json"},
+		server: searchTwoResults,
+	},
+	{
+		name:                "search.error_resource_not_found",
+		args:                []string{"search", "chunks", "query", "--kb=eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee", "--format", "json"},
+		server:              always404,
+		wantErr:             true,
+		wantStderrSubstring: "resource.not_found",
+	},
+	{
+		// --no-vector + --no-keyword is the input.invalid case; the KB UUID
+		// is just there to satisfy MarkFlagRequired so validation runs deep
+		// enough to hit the mutex-channel check.
+		name:                "search.error_input_invalid",
+		args:                []string{"search", "chunks", "query", "--kb=11111111-1111-4111-8111-111111111111", "--no-vector", "--no-keyword", "--format", "json"},
+		wantErr:             true,
+		wantStderrSubstring: "input.invalid_argument",
+	},
+}
+
+// TestWireGolden is the matrix-runner. Cases are sequential (the
+// iostreams singleton swap inside helpers.runCmd is package-global;
+// t.Parallel is contractually forbidden - see helpers_test.go).
+func TestWireGolden(t *testing.T) {
+	for _, tc := range wireCases {
+		t.Run(tc.name, func(t *testing.T) {
+			var ts *httptest.Server
+			var mockClient *sdk.Client
+			if tc.server != nil {
+				ts = httptest.NewServer(tc.server)
+				defer ts.Close()
+				mockClient = sdk.NewClient(ts.URL)
+			}
+			f := newTestFactory(t, ts, mockClient)
+			if tc.preConfig != nil {
+				tc.preConfig(t)
+			}
+			stdout, stderr, exit := runCmd(t, f, tc.args...)
+			if tc.wantErr && exit == 0 {
+				t.Errorf("expected non-zero exit, got 0; stdout=%q stderr=%q", stdout, stderr)
+			}
+			if !tc.wantErr && exit != 0 {
+				t.Errorf("unexpected non-zero exit %d; stdout=%q stderr=%q", exit, stdout, stderr)
+			}
+			if tc.wantStderrSubstring != "" && !strings.Contains(stderr, tc.wantStderrSubstring) {
+				t.Errorf("stderr missing %q; got %q", tc.wantStderrSubstring, stderr)
+			}
+			path := filepath.Join("..", "testdata", "wire", tc.name+".json")
+			assertGolden(t, []byte(stdout), path)
+		})
+	}
+}
+
+// ---------------------------------------------------------------------------
+// HTTP fixtures
+//
+// Handlers are intentionally permissive on path matching (HasSuffix) so they
+// work whether the SDK adds the /api/v1 prefix or not. The SDK pins the
+// /api/v1 prefix today; the suffix match keeps the fixtures resilient to
+// future route renames as long as the leaf path stays stable.
+
+// fixedTime is the deterministic timestamp embedded in KnowledgeBase fixtures.
+// time.Time marshals to RFC3339; using a fixed value keeps the golden stable.
+var fixedTime = time.Date(2025, 1, 1, 12, 0, 0, 0, time.UTC)
+
+func whoamiOK(w http.ResponseWriter, r *http.Request) {
+	if !strings.HasSuffix(r.URL.Path, "/auth/me") {
+		w.WriteHeader(http.StatusNotFound)
+		return
+	}
+	resp := sdk.CurrentUserResponse{Success: true}
+	resp.Data.User = &sdk.AuthUser{ID: "usr_abc", Email: "user@example.com", TenantID: 42}
+	resp.Data.Tenant = &sdk.AuthTenant{ID: 42, Name: "Acme"}
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(resp)
+}
+
+func always401(w http.ResponseWriter, _ *http.Request) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusUnauthorized)
+	_, _ = w.Write([]byte(`{"error":"unauthenticated"}`))
+}
+
+func always403(w http.ResponseWriter, _ *http.Request) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusForbidden)
+	_, _ = w.Write([]byte(`{"error":"forbidden"}`))
+}
+
+func always404(w http.ResponseWriter, _ *http.Request) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusNotFound)
+	_, _ = w.Write([]byte(`{"error":"not found"}`))
+}
+
+func alwaysServerError(w http.ResponseWriter, _ *http.Request) {
+	// 5xx triggers PingBaseURL failure path and SDK transport error.
+	w.WriteHeader(http.StatusInternalServerError)
+	_, _ = w.Write([]byte(`internal error`))
+}
+
+// doctorReachable serves /health 200 (so PingBaseURL would succeed if it
+// were called). doctor.success_offline still skips ping, so this handler
+// is a no-op for that case but keeps buildServices on a happy path.
+func doctorReachable(w http.ResponseWriter, _ *http.Request) {
+	w.WriteHeader(http.StatusOK)
+}
+
+func kbListTwo(w http.ResponseWriter, r *http.Request) {
+	if !strings.HasSuffix(r.URL.Path, "/knowledge-bases") {
+		w.WriteHeader(http.StatusNotFound)
+		return
+	}
+	resp := sdk.KnowledgeBaseListResponse{
+		Success: true,
+		Data: []sdk.KnowledgeBase{
+			{
+				ID:               "kb1",
+				Name:             "Onboarding Docs",
+				TenantID:         42,
+				EmbeddingModelID: "text-embedding-3",
+				CreatedAt:        fixedTime,
+				UpdatedAt:        fixedTime,
+				KnowledgeCount:   5,
+				ChunkCount:       128,
+			},
+			{
+				ID:               "kb2",
+				Name:             "API Reference",
+				TenantID:         42,
+				EmbeddingModelID: "text-embedding-3",
+				CreatedAt:        fixedTime,
+				UpdatedAt:        fixedTime,
+				KnowledgeCount:   12,
+				ChunkCount:       340,
+			},
+		},
+	}
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(resp)
+}
+
+func kbListEmpty(w http.ResponseWriter, r *http.Request) {
+	if !strings.HasSuffix(r.URL.Path, "/knowledge-bases") {
+		w.WriteHeader(http.StatusNotFound)
+		return
+	}
+	resp := sdk.KnowledgeBaseListResponse{Success: true, Data: []sdk.KnowledgeBase{}}
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(resp)
+}
+
+func kbGetOne(w http.ResponseWriter, r *http.Request) {
+	if !strings.HasSuffix(r.URL.Path, "/knowledge-bases/kb1") {
+		w.WriteHeader(http.StatusNotFound)
+		return
+	}
+	resp := sdk.KnowledgeBaseResponse{
+		Success: true,
+		Data: sdk.KnowledgeBase{
+			ID:               "kb1",
+			Name:             "Onboarding Docs",
+			Description:      "Internal onboarding handbook",
+			TenantID:         42,
+			EmbeddingModelID: "text-embedding-3",
+			CreatedAt:        fixedTime,
+			UpdatedAt:        fixedTime,
+			KnowledgeCount:   5,
+			ChunkCount:       128,
+		},
+	}
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(resp)
+}
+
+func searchTwoResults(w http.ResponseWriter, r *http.Request) {
+	if !strings.Contains(r.URL.Path, "/knowledge-bases/11111111-1111-4111-8111-111111111111/hybrid-search") {
+		w.WriteHeader(http.StatusNotFound)
+		return
+	}
+	resp := sdk.HybridSearchResponse{
+		Success: true,
+		Data: []*sdk.SearchResult{
+			{
+				ID:             "chunk-1",
+				Content:        "first chunk content",
+				KnowledgeID:    "doc-1",
+				ChunkIndex:     0,
+				KnowledgeTitle: "Doc 1",
+				Score:          0.92,
+				MatchType:      sdk.MatchTypeVector,
+			},
+			{
+				ID:             "chunk-2",
+				Content:        "second chunk content",
+				KnowledgeID:    "doc-2",
+				ChunkIndex:     1,
+				KnowledgeTitle: "Doc 2",
+				Score:          0.81,
+				MatchType:      sdk.MatchTypeKeyword,
+			},
+		},
+	}
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(resp)
+}

cli/acceptance/doc.go

@@ -0,0 +1,11 @@
+// cli/acceptance/doc.go
+//
+// Package acceptance is the cli/ subtree top-level home for cross-cutting
+// contract / integration tests. Lives outside cli/internal/ so a future
+// reviewer immediately sees "this is the contract surface - change with care".
+//
+// Sub-packages:
+//
+//	contract/    - envelope JSON shape golden + error.code registry consistency
+//	e2e/         - real WeKnora server blackbox tests (testscript-style)
+package acceptance

cli/acceptance/e2e/e2e_test.go

@@ -0,0 +1,279 @@
+//go:build acceptance_e2e
+
+// Package e2e_test drives the WeKnora CLI binary against a real running
+// server to validate the RAG closing loop end-to-end.
+//
+// Build tag isolation: //go:build acceptance_e2e excludes this file from
+// the default `go test ./...` so the e2e suite only runs when explicitly
+// requested. To run:
+//
+//	cd cli
+//	WEKNORA_E2E_HOST=https://kb.example.com \
+//	WEKNORA_E2E_TOKEN=eyJhbGc... \
+//	go test -tags=acceptance_e2e -v ./acceptance/e2e/...
+//
+// Optional WEKNORA_E2E_KB_NAME_PREFIX customizes the throwaway KB name (default
+// "cli-e2e-"). Cleanup runs even on test failure via t.Cleanup so the server
+// doesn't accumulate test debris.
+package e2e_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+// TestRAGFullLoop walks the demo MVP path: link a profile, create a KB,
+// upload a doc, wait for indexing, search it, then chat against it. Each
+// step parses the CLI's bare JSON to extract IDs for the next step -
+// validating both functional behavior and wire-contract stability.
+func TestRAGFullLoop(t *testing.T) {
+	host := mustEnv(t, "WEKNORA_E2E_HOST")
+	token := mustEnv(t, "WEKNORA_E2E_TOKEN")
+	prefix := envOr("WEKNORA_E2E_KB_NAME_PREFIX", "cli-e2e-")
+
+	bin := buildBinary(t)
+	xdg := t.TempDir()
+
+	// Inject host + token as WEKNORA_HOST / WEKNORA_TOKEN env vars. The
+	// CLI's env-credential path (buildClientFromEnv) takes precedence
+	// over profile config, so this bypasses the secrets-store dance
+	// entirely — no keychain access, no file:// ref plumbing. This is
+	// the most robust path for CI and local e2e alike.
+	env := append(os.Environ(),
+		"XDG_CONFIG_HOME="+xdg,
+		"XDG_CACHE_HOME="+filepath.Join(xdg, "cache"),
+		"WEKNORA_HOST="+host,
+		"WEKNORA_TOKEN="+token,
+		// SDK debug off - explicit so the CI run isn't noisy.
+		"WEKNORA_LOG_LEVEL=error",
+	)
+
+	// 1. kb create → KnowledgeBase object (envelope-wrapped: {ok, data})
+	// The CLI now requires explicit model binding so uploaded docs are
+	// immediately searchable. Use the server's builtin model IDs (they
+	// exist on every deployment that configures builtin_models.yaml).
+	embeddingModel := envOr("WEKNORA_E2E_EMBEDDING_MODEL", "Qwen/Qwen3-Embedding-8B")
+	chatModel := envOr("WEKNORA_E2E_CHAT_MODEL", "deepseek-ai/DeepSeek-V3.2")
+	kbName := prefix + fmt.Sprintf("%d", time.Now().UnixNano())
+	var created struct {
+		OK   bool `json:"ok"`
+		Data struct {
+			ID   string `json:"id"`
+			Name string `json:"name"`
+		} `json:"data"`
+	}
+	runJSONInto(t, bin, env, &created, "kb", "create", kbName,
+		"--embedding-model", embeddingModel,
+		"--chat-model", chatModel,
+		"--format", "json")
+	if created.Data.ID == "" {
+		t.Fatalf("kb create returned no id")
+	}
+	t.Logf("created KB: %s (%s)", created.Data.ID, kbName)
+
+	t.Cleanup(func() {
+		// Best-effort cleanup; a 404 means the KB was already gone.
+		out, err := run(bin, env, "kb", "delete", created.Data.ID, "-y", "--format", "json")
+		if err != nil {
+			t.Logf("cleanup kb delete: %v\n%s", err, out)
+		}
+	})
+
+	// 2. doc upload → Knowledge object (envelope-wrapped: {ok, data})
+	docPath := writeSampleDoc(t)
+	var uploaded struct {
+		OK   bool `json:"ok"`
+		Data struct {
+			ID string `json:"id"`
+		} `json:"data"`
+	}
+	runJSONInto(t, bin, env, &uploaded, "doc", "upload", docPath, "--kb", created.Data.ID, "--format", "json")
+	if uploaded.Data.ID == "" {
+		t.Fatalf("doc upload returned no id")
+	}
+	t.Logf("uploaded doc: %s", uploaded.Data.ID)
+
+	// 3. poll until indexing finishes (status changes from "pending" / "processing" to "ready" / similar)
+	waitDocReady(t, bin, env, created.Data.ID, uploaded.Data.ID, 90*time.Second)
+
+	// 4. search chunks → SearchResult list (envelope-wrapped: {ok, data})
+	var searchResp struct {
+		OK   bool              `json:"ok"`
+		Data []map[string]any `json:"data"`
+	}
+	runJSONInto(t, bin, env, &searchResp, "search", "chunks", "sample", "--kb", created.Data.ID, "--limit", "5", "--format", "json")
+	results := searchResp.Data
+	if len(results) == 0 {
+		t.Fatalf("search returned no results")
+	}
+	t.Logf("search returned %d results", len(results))
+
+	// 5. chat --format json → bounded answer-event envelope (--reference for citations)
+	var chatEnv struct {
+		OK   bool `json:"ok"`
+		Data struct {
+			Events []struct {
+				ResponseType        string `json:"response_type"`
+				Content             string `json:"content"`
+				KnowledgeReferences []struct {
+					ChunkID string `json:"chunk_id"`
+				} `json:"knowledge_references"`
+			} `json:"events"`
+			SessionID string `json:"session_id"`
+		} `json:"data"`
+	}
+	runJSONInto(t, bin, env, &chatEnv, "chat", "summarize the document briefly", "--kb", created.Data.ID, "--format", "json", "--reference")
+	if !chatEnv.OK {
+		t.Fatal("chat ok=false")
+	}
+	var answer strings.Builder
+	refCount := 0
+	for _, ev := range chatEnv.Data.Events {
+		if ev.ResponseType == "answer" {
+			answer.WriteString(ev.Content)
+		}
+		refCount += len(ev.KnowledgeReferences)
+	}
+	if strings.TrimSpace(answer.String()) == "" {
+		t.Fatalf("chat returned empty answer")
+	}
+	t.Logf("chat answer (%d chars), %d reference indexes", len(answer.String()), refCount)
+	if refCount == 0 {
+		// Soft warning - some servers may not surface references for every
+		// question, but the demo flow is supposed to.
+		t.Logf("warning: chat returned 0 reference indexes (server may have a different config)")
+	}
+}
+
+func mustEnv(t *testing.T, key string) string {
+	t.Helper()
+	v := os.Getenv(key)
+	if v == "" {
+		t.Skipf("e2e: %s not set; skipping (set the env var or run `gh workflow run cli-e2e.yml`)", key)
+	}
+	return v
+}
+
+func envOr(key, fallback string) string {
+	if v := os.Getenv(key); v != "" {
+		return v
+	}
+	return fallback
+}
+
+// buildBinary compiles the CLI to a temp dir once per test run. Re-using a
+// single binary across sub-cases avoids the multi-second linker cost on each
+// step and matches gh acceptance/ build behavior.
+func buildBinary(t *testing.T) string {
+	t.Helper()
+	dir := t.TempDir()
+	out := filepath.Join(dir, "weknora")
+	// Repo layout: this test sits at cli/acceptance/e2e/, so cli/ is two levels up.
+	cmd := exec.Command("go", "build", "-o", out, ".")
+	cmd.Dir = filepath.Join("..", "..")
+	cmd.Stdout = os.Stderr
+	cmd.Stderr = os.Stderr
+	if err := cmd.Run(); err != nil {
+		t.Fatalf("build cli: %v", err)
+	}
+	return out
+}
+
+// writeSampleDoc emits a small bilingual doc that gives the embedder enough
+// signal for retrieval but stays tiny so indexing finishes within the poll
+// window.
+func writeSampleDoc(t *testing.T) string {
+	t.Helper()
+	content := `WeKnora E2E Sample Document
+
+This sample document is used by the WeKnora CLI acceptance test suite to
+validate the end-to-end retrieval-augmented generation pipeline.
+
+向量检索的核心思想是把文本通过 embedding 模型映射到高维向量空间,然后通过余弦相似度
+等度量找出语义最接近的内容片段。WeKnora 支持 vector + keyword 的混合检索模式。
+
+The hybrid search mode combines vector similarity (semantic) with keyword
+matching (lexical) to balance recall and precision.
+`
+	dir := t.TempDir()
+	p := filepath.Join(dir, "sample.txt")
+	if err := os.WriteFile(p, []byte(content), 0o600); err != nil {
+		t.Fatalf("write sample: %v", err)
+	}
+	return p
+}
+
+// waitDocReady polls `doc list` until the uploaded document's status indicates
+// indexing is complete. WeKnora server uses a few status values across versions
+// ("ready", "completed", "ok") - accept any non-pending/non-processing/non-failed
+// state so we don't break on a server-side rename. Failed status fails the test
+// fast.
+func waitDocReady(t *testing.T, bin string, env []string, kbID, docID string, timeout time.Duration) {
+	t.Helper()
+	deadline := time.Now().Add(timeout)
+	tick := 2 * time.Second
+	type docItem struct {
+		ID          string `json:"id"`
+		ParseStatus string `json:"parse_status"`
+	}
+	for time.Now().Before(deadline) {
+		// doc list is envelope-wrapped: {ok, data: [...]} (bare array)
+		var resp struct {
+			OK   bool      `json:"ok"`
+			Data []docItem `json:"data"`
+		}
+		runJSONInto(t, bin, env, &resp, "doc", "list", "--kb", kbID, "--page-size", "100", "--format", "json")
+		for _, d := range resp.Data {
+			if d.ID != docID {
+				continue
+			}
+			low := strings.ToLower(d.ParseStatus)
+			switch {
+			case low == "failed", low == "error":
+				t.Fatalf("doc %s indexing failed: status=%q", docID, d.ParseStatus)
+			case low == "pending", low == "processing", low == "finalizing", low == "":
+				// keep waiting
+			default:
+				t.Logf("doc %s ready (status=%q)", docID, d.ParseStatus)
+				return
+			}
+		}
+		time.Sleep(tick)
+	}
+	t.Fatalf("doc %s did not reach ready within %s", docID, timeout)
+}
+
+// run executes the CLI and returns combined stdout. Errors include stderr +
+// exit code so failures are debuggable without re-running.
+func run(bin string, env []string, args ...string) ([]byte, error) {
+	cmd := exec.Command(bin, args...)
+	cmd.Env = env
+	var stdout, stderr bytes.Buffer
+	cmd.Stdout = &stdout
+	cmd.Stderr = &stderr
+	if err := cmd.Run(); err != nil {
+		return stdout.Bytes(), fmt.Errorf("%s %s: %v\nstderr:\n%s", filepath.Base(bin), strings.Join(args, " "), err, stderr.String())
+	}
+	return stdout.Bytes(), nil
+}
+
+// runJSONInto runs the CLI expecting bare JSON output and decodes stdout
+// into out (a struct, slice, or map pointer). Test fails on non-zero exit
+// or unparseable JSON.
+func runJSONInto(t *testing.T, bin string, env []string, out any, args ...string) {
+	t.Helper()
+	stdout, err := run(bin, env, args...)
+	if err != nil {
+		t.Fatalf("%v", err)
+	}
+	if err := json.Unmarshal(stdout, out); err != nil {
+		t.Fatalf("parse JSON from %v: %v\nstdout:\n%s", args, err, string(stdout))
+	}
+}

cli/acceptance/testdata/wire/auth_status.success.json

@@ -0,0 +1 @@
+{"ok":true,"data":{"profile":"","auth_source":"profile + keyring","user_id":"usr_abc","email":"user@example.com","tenant_id":42,"tenant_name":"Acme"}}

cli/acceptance/testdata/wire/doctor.error_network.json

@@ -0,0 +1 @@
+{"ok":true,"data":{"summary":{"all_passed":false,"passed":1,"failed":1,"skipped":2},"checks":[{"name":"base_url_reachable","status":"fail","details":"server returned 500","hint":"verify the host configured for the active profile (run `weknora profile list` / `weknora profile add <n> --host=...`) and network reachability"},{"name":"auth_credential","status":"skip","details":"prereq failed: base_url_reachable"},{"name":"server_version","status":"skip","details":"prereq failed: auth_credential"},{"name":"credential_storage","status":"ok","details":"keyring or file storage available"}]}}

cli/acceptance/testdata/wire/doctor.success_offline.json

@@ -0,0 +1 @@
+{"ok":true,"data":{"summary":{"all_passed":false,"passed":1,"failed":0,"skipped":3},"checks":[{"name":"base_url_reachable","status":"skip","details":"offline mode"},{"name":"auth_credential","status":"skip","details":"offline mode"},{"name":"server_version","status":"skip","details":"offline mode"},{"name":"credential_storage","status":"ok","details":"keyring or file storage available"}]}}

cli/acceptance/testdata/wire/kb_list.success.json

@@ -0,0 +1 @@
+{"ok":true,"data":[{"id":"kb1","name":"Onboarding Docs","type":"","is_temporary":false,"is_pinned":false,"description":"","tenant_id":42,"chunking_config":{"chunk_size":0,"chunk_overlap":0,"separators":null},"image_processing_config":{"model_id":""},"faq_config":null,"embedding_model_id":"text-embedding-3","summary_model_id":"","vlm_config":{"enabled":false,"model_id":""},"storage_provider_config":null,"storage_config":{"secret_id":"","secret_key":"","region":"","bucket_name":"","app_id":"","path_prefix":"","provider":""},"extract_config":null,"auto_tag_config":null,"created_at":"2025-01-01T12:00:00Z","updated_at":"2025-01-01T12:00:00Z","knowledge_count":5,"chunk_count":128,"is_processing":false,"processing_count":0},{"id":"kb2","name":"API Reference","type":"","is_temporary":false,"is_pinned":false,"description":"","tenant_id":42,"chunking_config":{"chunk_size":0,"chunk_overlap":0,"separators":null},"image_processing_config":{"model_id":""},"faq_config":null,"embedding_model_id":"text-embedding-3","summary_model_id":"","vlm_config":{"enabled":false,"model_id":""},"storage_provider_config":null,"storage_config":{"secret_id":"","secret_key":"","region":"","bucket_name":"","app_id":"","path_prefix":"","provider":""},"extract_config":null,"auto_tag_config":null,"created_at":"2025-01-01T12:00:00Z","updated_at":"2025-01-01T12:00:00Z","knowledge_count":12,"chunk_count":340,"is_processing":false,"processing_count":0}],"meta":{"count":2,"total_count":2}}

cli/acceptance/testdata/wire/kb_list.success_empty.json

@@ -0,0 +1 @@
+{"ok":true,"data":[],"meta":{"count":0,"total_count":0}}

cli/acceptance/testdata/wire/kb_view.success.json

@@ -0,0 +1 @@
+{"ok":true,"data":{"id":"kb1","name":"Onboarding Docs","type":"","is_temporary":false,"is_pinned":false,"description":"Internal onboarding handbook","tenant_id":42,"chunking_config":{"chunk_size":0,"chunk_overlap":0,"separators":null},"image_processing_config":{"model_id":""},"faq_config":null,"embedding_model_id":"text-embedding-3","summary_model_id":"","vlm_config":{"enabled":false,"model_id":""},"storage_provider_config":null,"storage_config":{"secret_id":"","secret_key":"","region":"","bucket_name":"","app_id":"","path_prefix":"","provider":""},"extract_config":null,"auto_tag_config":null,"created_at":"2025-01-01T12:00:00Z","updated_at":"2025-01-01T12:00:00Z","knowledge_count":5,"chunk_count":128,"is_processing":false,"processing_count":0}}

cli/acceptance/testdata/wire/profile_use.success.json

@@ -0,0 +1 @@
+{"ok":true,"data":{"current_profile":"production","previous_profile":"staging"},"profile":"staging"}

cli/acceptance/testdata/wire/search.success.json

@@ -0,0 +1 @@
+{"ok":true,"data":[{"id":"chunk-1","content":"first chunk content","knowledge_id":"doc-1","chunk_index":0,"knowledge_title":"Doc 1","start_at":0,"end_at":0,"seq":0,"score":0.92,"match_type":0,"chunk_type":"","image_info":"","metadata":null,"knowledge_filename":"","knowledge_source":"","knowledge_channel":""},{"id":"chunk-2","content":"second chunk content","knowledge_id":"doc-2","chunk_index":1,"knowledge_title":"Doc 2","start_at":0,"end_at":0,"seq":0,"score":0.81,"match_type":1,"chunk_type":"","image_info":"","metadata":null,"knowledge_filename":"","knowledge_source":"","knowledge_channel":""}],"meta":{"count":2}}

cli/acceptance/testdata/wire/version.success.json

@@ -0,0 +1 @@
+{"ok":true,"data":{"commit":"none","date":"unknown","version":"dev"}}