2026-05-08 08:42:17 +00:00
|
|
|
// 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().
|
|
|
|
|
//
|
refactor(cli): drop aiclient package; align AGENTS.md with mainstream
Survey of 10 mainstream CLIs (gh, lark, stripe, vercel, supabase, aws,
azure, gcloud, openai/codex, github-copilot-cli) showed env-gated
per-command --help blurbs are a Stripe-only pattern; gh uses env detect
for telemetry only, and lark relies on installed agent Skills + MCP.
Our cmd/mcp/serve already covers the dominant 2025/26 path, so
internal/aiclient/ (136 LOC + 38 callsites) is net maintenance burden
without precedent.
- Drop internal/aiclient/ entirely (annotations + detect + tests)
- Remove 38 SetAgentHelp callsites + agentAwareHelpFunc / SetHelpFunc
wiring in cmd/root.go
- Migrate 4 command-level rules to standard Long help (visible to all,
not env-gated): doc upload mode mutex, kb edit at-least-one,
kb pin idempotent, search chunks channel mutex
- Rewrite AGENTS.md as a developer guide (gh-style 6 H2 / 167 lines):
audience preamble + Build / Architecture / Command Structure /
Testing / Code Style / Error Handling. Drops sections absent in
surveyed projects (Commit & PR Conventions, Who Uses This CLI)
- Clean 14 internal doc refs (ADR-N, spec §X, v0.X) in source comments
and docs that pointed at docs/superpowers/ — that directory is
local-only / uncommitted, so refs are dead for outside readers
- Drop forward-looking "once v0.2 ships" from README
2026-05-14 18:16:45 +00:00
|
|
|
// ClassifyHTTPError is dynamic - callers don't pass a literal CodeXxx
|
refactor(cli): v0.3 cross-cutting cleanup
Cross-cutting findings surfaced by the branch-completion review.
Perf bug:
- Factory.Client closure was not memoized. Factory.ResolveKB internally
calls f.Client() to resolve --kb name → id, then the command's RunE
calls f.Client() again. Two SDK clients, two keyring reads, two
AuthRetryTransport allocations per name-resolved invocation, with
*independent* token state (a refresh in one was invisible to the
other). Switched to sync.Once like Secrets already does.
Silent bug bait:
- cmdutil.NormalizeHost docstring claimed CodeInputMissingFlag for the
empty case; code returned CodeInputInvalidArgument. Aligned doc to
code (present-but-empty is a bad value, not a missing flag).
Agent contract gaps:
- Five user-facing subcommands lacked SetAgentHelp: auth login /
logout / list / status and chat. Added concise strings with error-
code call-outs so agents can branch without parsing human strings.
Helper extraction (≥3 callers):
- text.KnowledgeDisplayName(fileName, title, id) — byte-identical
formatter that was in both cmd/doc/list.go and cmd/search/docs.go.
Takes fields directly so internal/text stays SDK-free.
- cmdutil.WrapHTTP(cause, fmt, args...) *Error — replaces the
`Wrapf(ClassifyHTTPError(err), err, ...)` pattern across 24 SDK
call sites. Sed-driven migration; off-pattern shapes in chat.go
(used streamErr) and cmdutil/kb.go (in-package) hand-edited.
Contract test gains a comment update: post-migration the dominant
pattern is WrapHTTP which the AST scanner skips entirely (only
NewError/Wrapf selectors inspected); ClassifyHTTPErrorOutputs()
bridge still covers the dynamic codes those paths can yield.
UX consistency:
- cmd/doc/list.go --page-size help now reads "Items per page
(1..1000)" matching cmd/session/list.go. The bounds validation
already enforced 1..1000; the help text was the last drift.
Comment-discipline sweep:
- Deleted the WHAT-only "*Options captures `weknora ...` flag state"
docstring across 23 files (context, kb, auth, doc, session, search,
chat, doctor, link). Where the line carried a real WHY clause
(kb/delete, doc/delete, session/delete, kb/edit), kept the WHY and
dropped only the leading WHAT phrase.
- Stripped third-party project-name attribution from inline comments
and one user-visible flag-help string across ~40 files in cli/cmd
and cli/internal (plus 4 test-file comments). Removed phrases like
"Mirrors `gh X`", "borrowed from lark-cli", "kubectl-style",
"gcloud `--project`", "Stripe pattern", and the embedded GitHub
URLs pointing at those projects. Behavioral descriptions and the
WHY behind each comment are preserved; only the upstream-name
attribution is gone. Inspiration / north-star references belong in
cli/AGENTS.md (the design doc) and commit messages, not scattered
through every file.
Triggered by an audit round that surfaced several false / fragile
parity claims (e.g. "Mirrors `gh repo edit`" — gh repo edit has no
--name flag; "matches gcloud `--project` id-or-name" — gcloud's
--project accepts ID only). Rather than fix them one by one, the
whole category of in-comment external-project references was
stripped uniformly.
2026-05-12 15:42:20 +00:00
|
|
|
// 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
|
refactor(cli): drop aiclient package; align AGENTS.md with mainstream
Survey of 10 mainstream CLIs (gh, lark, stripe, vercel, supabase, aws,
azure, gcloud, openai/codex, github-copilot-cli) showed env-gated
per-command --help blurbs are a Stripe-only pattern; gh uses env detect
for telemetry only, and lark relies on installed agent Skills + MCP.
Our cmd/mcp/serve already covers the dominant 2025/26 path, so
internal/aiclient/ (136 LOC + 38 callsites) is net maintenance burden
without precedent.
- Drop internal/aiclient/ entirely (annotations + detect + tests)
- Remove 38 SetAgentHelp callsites + agentAwareHelpFunc / SetHelpFunc
wiring in cmd/root.go
- Migrate 4 command-level rules to standard Long help (visible to all,
not env-gated): doc upload mode mutex, kb edit at-least-one,
kb pin idempotent, search chunks channel mutex
- Rewrite AGENTS.md as a developer guide (gh-style 6 H2 / 167 lines):
audience preamble + Build / Architecture / Command Structure /
Testing / Code Style / Error Handling. Drops sections absent in
surveyed projects (Commit & PR Conventions, Who Uses This CLI)
- Clean 14 internal doc refs (ADR-N, spec §X, v0.X) in source comments
and docs that pointed at docs/superpowers/ — that directory is
local-only / uncommitted, so refs are dead for outside readers
- Drop forward-looking "once v0.2 ships" from README
2026-05-14 18:16:45 +00:00
|
|
|
// switch can return - added to the registered set so the AST scanner
|
refactor(cli): v0.3 cross-cutting cleanup
Cross-cutting findings surfaced by the branch-completion review.
Perf bug:
- Factory.Client closure was not memoized. Factory.ResolveKB internally
calls f.Client() to resolve --kb name → id, then the command's RunE
calls f.Client() again. Two SDK clients, two keyring reads, two
AuthRetryTransport allocations per name-resolved invocation, with
*independent* token state (a refresh in one was invisible to the
other). Switched to sync.Once like Secrets already does.
Silent bug bait:
- cmdutil.NormalizeHost docstring claimed CodeInputMissingFlag for the
empty case; code returned CodeInputInvalidArgument. Aligned doc to
code (present-but-empty is a bad value, not a missing flag).
Agent contract gaps:
- Five user-facing subcommands lacked SetAgentHelp: auth login /
logout / list / status and chat. Added concise strings with error-
code call-outs so agents can branch without parsing human strings.
Helper extraction (≥3 callers):
- text.KnowledgeDisplayName(fileName, title, id) — byte-identical
formatter that was in both cmd/doc/list.go and cmd/search/docs.go.
Takes fields directly so internal/text stays SDK-free.
- cmdutil.WrapHTTP(cause, fmt, args...) *Error — replaces the
`Wrapf(ClassifyHTTPError(err), err, ...)` pattern across 24 SDK
call sites. Sed-driven migration; off-pattern shapes in chat.go
(used streamErr) and cmdutil/kb.go (in-package) hand-edited.
Contract test gains a comment update: post-migration the dominant
pattern is WrapHTTP which the AST scanner skips entirely (only
NewError/Wrapf selectors inspected); ClassifyHTTPErrorOutputs()
bridge still covers the dynamic codes those paths can yield.
UX consistency:
- cmd/doc/list.go --page-size help now reads "Items per page
(1..1000)" matching cmd/session/list.go. The bounds validation
already enforced 1..1000; the help text was the last drift.
Comment-discipline sweep:
- Deleted the WHAT-only "*Options captures `weknora ...` flag state"
docstring across 23 files (context, kb, auth, doc, session, search,
chat, doctor, link). Where the line carried a real WHY clause
(kb/delete, doc/delete, session/delete, kb/edit), kept the WHY and
dropped only the leading WHAT phrase.
- Stripped third-party project-name attribution from inline comments
and one user-visible flag-help string across ~40 files in cli/cmd
and cli/internal (plus 4 test-file comments). Removed phrases like
"Mirrors `gh X`", "borrowed from lark-cli", "kubectl-style",
"gcloud `--project`", "Stripe pattern", and the embedded GitHub
URLs pointing at those projects. Behavioral descriptions and the
WHY behind each comment are preserved; only the upstream-name
attribution is gone. Inspiration / north-star references belong in
cli/AGENTS.md (the design doc) and commit messages, not scattered
through every file.
Triggered by an audit round that surfaced several false / fragile
parity claims (e.g. "Mirrors `gh repo edit`" — gh repo edit has no
--name flag; "matches gcloud `--project` id-or-name" — gcloud's
--project accepts ID only). Rather than fix them one by one, the
whole category of in-comment external-project references was
stripped uniformly.
2026-05-12 15:42:20 +00:00
|
|
|
// doesn't false-positive on them.
|
2026-05-08 08:42:17 +00:00
|
|
|
//
|
refactor(cli): drop aiclient package; align AGENTS.md with mainstream
Survey of 10 mainstream CLIs (gh, lark, stripe, vercel, supabase, aws,
azure, gcloud, openai/codex, github-copilot-cli) showed env-gated
per-command --help blurbs are a Stripe-only pattern; gh uses env detect
for telemetry only, and lark relies on installed agent Skills + MCP.
Our cmd/mcp/serve already covers the dominant 2025/26 path, so
internal/aiclient/ (136 LOC + 38 callsites) is net maintenance burden
without precedent.
- Drop internal/aiclient/ entirely (annotations + detect + tests)
- Remove 38 SetAgentHelp callsites + agentAwareHelpFunc / SetHelpFunc
wiring in cmd/root.go
- Migrate 4 command-level rules to standard Long help (visible to all,
not env-gated): doc upload mode mutex, kb edit at-least-one,
kb pin idempotent, search chunks channel mutex
- Rewrite AGENTS.md as a developer guide (gh-style 6 H2 / 167 lines):
audience preamble + Build / Architecture / Command Structure /
Testing / Code Style / Error Handling. Drops sections absent in
surveyed projects (Commit & PR Conventions, Who Uses This CLI)
- Clean 14 internal doc refs (ADR-N, spec §X, v0.X) in source comments
and docs that pointed at docs/superpowers/ — that directory is
local-only / uncommitted, so refs are dead for outside readers
- Drop forward-looking "once v0.2 ships" from README
2026-05-14 18:16:45 +00:00
|
|
|
// Limitations:
|
2026-05-08 08:42:17 +00:00
|
|
|
// - Only literal cmdutil.CodeXxx idents are detected; codes assigned to
|
|
|
|
|
// a local variable then passed are NOT scanned (rare pattern).
|
refactor(cli): v0.3 cross-cutting cleanup
Cross-cutting findings surfaced by the branch-completion review.
Perf bug:
- Factory.Client closure was not memoized. Factory.ResolveKB internally
calls f.Client() to resolve --kb name → id, then the command's RunE
calls f.Client() again. Two SDK clients, two keyring reads, two
AuthRetryTransport allocations per name-resolved invocation, with
*independent* token state (a refresh in one was invisible to the
other). Switched to sync.Once like Secrets already does.
Silent bug bait:
- cmdutil.NormalizeHost docstring claimed CodeInputMissingFlag for the
empty case; code returned CodeInputInvalidArgument. Aligned doc to
code (present-but-empty is a bad value, not a missing flag).
Agent contract gaps:
- Five user-facing subcommands lacked SetAgentHelp: auth login /
logout / list / status and chat. Added concise strings with error-
code call-outs so agents can branch without parsing human strings.
Helper extraction (≥3 callers):
- text.KnowledgeDisplayName(fileName, title, id) — byte-identical
formatter that was in both cmd/doc/list.go and cmd/search/docs.go.
Takes fields directly so internal/text stays SDK-free.
- cmdutil.WrapHTTP(cause, fmt, args...) *Error — replaces the
`Wrapf(ClassifyHTTPError(err), err, ...)` pattern across 24 SDK
call sites. Sed-driven migration; off-pattern shapes in chat.go
(used streamErr) and cmdutil/kb.go (in-package) hand-edited.
Contract test gains a comment update: post-migration the dominant
pattern is WrapHTTP which the AST scanner skips entirely (only
NewError/Wrapf selectors inspected); ClassifyHTTPErrorOutputs()
bridge still covers the dynamic codes those paths can yield.
UX consistency:
- cmd/doc/list.go --page-size help now reads "Items per page
(1..1000)" matching cmd/session/list.go. The bounds validation
already enforced 1..1000; the help text was the last drift.
Comment-discipline sweep:
- Deleted the WHAT-only "*Options captures `weknora ...` flag state"
docstring across 23 files (context, kb, auth, doc, session, search,
chat, doctor, link). Where the line carried a real WHY clause
(kb/delete, doc/delete, session/delete, kb/edit), kept the WHY and
dropped only the leading WHAT phrase.
- Stripped third-party project-name attribution from inline comments
and one user-visible flag-help string across ~40 files in cli/cmd
and cli/internal (plus 4 test-file comments). Removed phrases like
"Mirrors `gh X`", "borrowed from lark-cli", "kubectl-style",
"gcloud `--project`", "Stripe pattern", and the embedded GitHub
URLs pointing at those projects. Behavioral descriptions and the
WHY behind each comment are preserved; only the upstream-name
attribution is gone. Inspiration / north-star references belong in
cli/AGENTS.md (the design doc) and commit messages, not scattered
through every file.
Triggered by an audit round that surfaced several false / fragile
parity claims (e.g. "Mirrors `gh repo edit`" — gh repo edit has no
--name flag; "matches gcloud `--project` id-or-name" — gcloud's
--project accepts ID only). Rather than fix them one by one, the
whole category of in-comment external-project references was
stripped uniformly.
2026-05-12 15:42:20 +00:00
|
|
|
// - cmdutil.WrapHTTP(...) and cmdutil.ClassifyHTTPError(...) call
|
refactor(cli): drop aiclient package; align AGENTS.md with mainstream
Survey of 10 mainstream CLIs (gh, lark, stripe, vercel, supabase, aws,
azure, gcloud, openai/codex, github-copilot-cli) showed env-gated
per-command --help blurbs are a Stripe-only pattern; gh uses env detect
for telemetry only, and lark relies on installed agent Skills + MCP.
Our cmd/mcp/serve already covers the dominant 2025/26 path, so
internal/aiclient/ (136 LOC + 38 callsites) is net maintenance burden
without precedent.
- Drop internal/aiclient/ entirely (annotations + detect + tests)
- Remove 38 SetAgentHelp callsites + agentAwareHelpFunc / SetHelpFunc
wiring in cmd/root.go
- Migrate 4 command-level rules to standard Long help (visible to all,
not env-gated): doc upload mode mutex, kb edit at-least-one,
kb pin idempotent, search chunks channel mutex
- Rewrite AGENTS.md as a developer guide (gh-style 6 H2 / 167 lines):
audience preamble + Build / Architecture / Command Structure /
Testing / Code Style / Error Handling. Drops sections absent in
surveyed projects (Commit & PR Conventions, Who Uses This CLI)
- Clean 14 internal doc refs (ADR-N, spec §X, v0.X) in source comments
and docs that pointed at docs/superpowers/ — that directory is
local-only / uncommitted, so refs are dead for outside readers
- Drop forward-looking "once v0.2 ships" from README
2026-05-14 18:16:45 +00:00
|
|
|
// expressions are skipped - the ClassifyHTTPErrorOutputs bridge
|
refactor(cli): v0.3 cross-cutting cleanup
Cross-cutting findings surfaced by the branch-completion review.
Perf bug:
- Factory.Client closure was not memoized. Factory.ResolveKB internally
calls f.Client() to resolve --kb name → id, then the command's RunE
calls f.Client() again. Two SDK clients, two keyring reads, two
AuthRetryTransport allocations per name-resolved invocation, with
*independent* token state (a refresh in one was invisible to the
other). Switched to sync.Once like Secrets already does.
Silent bug bait:
- cmdutil.NormalizeHost docstring claimed CodeInputMissingFlag for the
empty case; code returned CodeInputInvalidArgument. Aligned doc to
code (present-but-empty is a bad value, not a missing flag).
Agent contract gaps:
- Five user-facing subcommands lacked SetAgentHelp: auth login /
logout / list / status and chat. Added concise strings with error-
code call-outs so agents can branch without parsing human strings.
Helper extraction (≥3 callers):
- text.KnowledgeDisplayName(fileName, title, id) — byte-identical
formatter that was in both cmd/doc/list.go and cmd/search/docs.go.
Takes fields directly so internal/text stays SDK-free.
- cmdutil.WrapHTTP(cause, fmt, args...) *Error — replaces the
`Wrapf(ClassifyHTTPError(err), err, ...)` pattern across 24 SDK
call sites. Sed-driven migration; off-pattern shapes in chat.go
(used streamErr) and cmdutil/kb.go (in-package) hand-edited.
Contract test gains a comment update: post-migration the dominant
pattern is WrapHTTP which the AST scanner skips entirely (only
NewError/Wrapf selectors inspected); ClassifyHTTPErrorOutputs()
bridge still covers the dynamic codes those paths can yield.
UX consistency:
- cmd/doc/list.go --page-size help now reads "Items per page
(1..1000)" matching cmd/session/list.go. The bounds validation
already enforced 1..1000; the help text was the last drift.
Comment-discipline sweep:
- Deleted the WHAT-only "*Options captures `weknora ...` flag state"
docstring across 23 files (context, kb, auth, doc, session, search,
chat, doctor, link). Where the line carried a real WHY clause
(kb/delete, doc/delete, session/delete, kb/edit), kept the WHY and
dropped only the leading WHAT phrase.
- Stripped third-party project-name attribution from inline comments
and one user-visible flag-help string across ~40 files in cli/cmd
and cli/internal (plus 4 test-file comments). Removed phrases like
"Mirrors `gh X`", "borrowed from lark-cli", "kubectl-style",
"gcloud `--project`", "Stripe pattern", and the embedded GitHub
URLs pointing at those projects. Behavioral descriptions and the
WHY behind each comment are preserved; only the upstream-name
attribution is gone. Inspiration / north-star references belong in
cli/AGENTS.md (the design doc) and commit messages, not scattered
through every file.
Triggered by an audit round that surfaced several false / fragile
parity claims (e.g. "Mirrors `gh repo edit`" — gh repo edit has no
--name flag; "matches gcloud `--project` id-or-name" — gcloud's
--project accepts ID only). Rather than fix them one by one, the
whole category of in-comment external-project references was
stripped uniformly.
2026-05-12 15:42:20 +00:00
|
|
|
// covers their dynamic codes.
|
2026-05-08 08:42:17 +00:00
|
|
|
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
|
refactor(cli): drop aiclient package; align AGENTS.md with mainstream
Survey of 10 mainstream CLIs (gh, lark, stripe, vercel, supabase, aws,
azure, gcloud, openai/codex, github-copilot-cli) showed env-gated
per-command --help blurbs are a Stripe-only pattern; gh uses env detect
for telemetry only, and lark relies on installed agent Skills + MCP.
Our cmd/mcp/serve already covers the dominant 2025/26 path, so
internal/aiclient/ (136 LOC + 38 callsites) is net maintenance burden
without precedent.
- Drop internal/aiclient/ entirely (annotations + detect + tests)
- Remove 38 SetAgentHelp callsites + agentAwareHelpFunc / SetHelpFunc
wiring in cmd/root.go
- Migrate 4 command-level rules to standard Long help (visible to all,
not env-gated): doc upload mode mutex, kb edit at-least-one,
kb pin idempotent, search chunks channel mutex
- Rewrite AGENTS.md as a developer guide (gh-style 6 H2 / 167 lines):
audience preamble + Build / Architecture / Command Structure /
Testing / Code Style / Error Handling. Drops sections absent in
surveyed projects (Commit & PR Conventions, Who Uses This CLI)
- Clean 14 internal doc refs (ADR-N, spec §X, v0.X) in source comments
and docs that pointed at docs/superpowers/ — that directory is
local-only / uncommitted, so refs are dead for outside readers
- Drop forward-looking "once v0.2 ships" from README
2026-05-14 18:16:45 +00:00
|
|
|
// - bridge handles those.
|
2026-05-08 08:42:17 +00:00
|
|
|
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 {
|
refactor(cli): drop aiclient package; align AGENTS.md with mainstream
Survey of 10 mainstream CLIs (gh, lark, stripe, vercel, supabase, aws,
azure, gcloud, openai/codex, github-copilot-cli) showed env-gated
per-command --help blurbs are a Stripe-only pattern; gh uses env detect
for telemetry only, and lark relies on installed agent Skills + MCP.
Our cmd/mcp/serve already covers the dominant 2025/26 path, so
internal/aiclient/ (136 LOC + 38 callsites) is net maintenance burden
without precedent.
- Drop internal/aiclient/ entirely (annotations + detect + tests)
- Remove 38 SetAgentHelp callsites + agentAwareHelpFunc / SetHelpFunc
wiring in cmd/root.go
- Migrate 4 command-level rules to standard Long help (visible to all,
not env-gated): doc upload mode mutex, kb edit at-least-one,
kb pin idempotent, search chunks channel mutex
- Rewrite AGENTS.md as a developer guide (gh-style 6 H2 / 167 lines):
audience preamble + Build / Architecture / Command Structure /
Testing / Code Style / Error Handling. Drops sections absent in
surveyed projects (Commit & PR Conventions, Who Uses This CLI)
- Clean 14 internal doc refs (ADR-N, spec §X, v0.X) in source comments
and docs that pointed at docs/superpowers/ — that directory is
local-only / uncommitted, so refs are dead for outside readers
- Drop forward-looking "once v0.2 ships" from README
2026-05-14 18:16:45 +00:00
|
|
|
// Unknown ident name - record as bogus so the test fails with
|
2026-05-08 08:42:17 +00:00
|
|
|
// 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.
|
refactor(cli): drop aiclient package; align AGENTS.md with mainstream
Survey of 10 mainstream CLIs (gh, lark, stripe, vercel, supabase, aws,
azure, gcloud, openai/codex, github-copilot-cli) showed env-gated
per-command --help blurbs are a Stripe-only pattern; gh uses env detect
for telemetry only, and lark relies on installed agent Skills + MCP.
Our cmd/mcp/serve already covers the dominant 2025/26 path, so
internal/aiclient/ (136 LOC + 38 callsites) is net maintenance burden
without precedent.
- Drop internal/aiclient/ entirely (annotations + detect + tests)
- Remove 38 SetAgentHelp callsites + agentAwareHelpFunc / SetHelpFunc
wiring in cmd/root.go
- Migrate 4 command-level rules to standard Long help (visible to all,
not env-gated): doc upload mode mutex, kb edit at-least-one,
kb pin idempotent, search chunks channel mutex
- Rewrite AGENTS.md as a developer guide (gh-style 6 H2 / 167 lines):
audience preamble + Build / Architecture / Command Structure /
Testing / Code Style / Error Handling. Drops sections absent in
surveyed projects (Commit & PR Conventions, Who Uses This CLI)
- Clean 14 internal doc refs (ADR-N, spec §X, v0.X) in source comments
and docs that pointed at docs/superpowers/ — that directory is
local-only / uncommitted, so refs are dead for outside readers
- Drop forward-looking "once v0.2 ships" from README
2026-05-14 18:16:45 +00:00
|
|
|
// Keep in sync with cmdutil.AllCodes() - adding a new const here is the same
|
2026-05-08 08:42:17 +00:00
|
|
|
// 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
|
refactor(cli): symmetric envelope infrastructure (supersedes e623e820)
Re-introduce the agent-first symmetric envelope deleted in commit
e623e820 (2026-05-15). Under the v0.7 constraint that AI agents are
primary consumers, the bare-JSON shape can't carry protocol channels
(_notice / risk / meta / request_id / profile) that agents need.
Errors-on-stderr and typed exit codes from e623e820 are preserved;
the envelope wraps the success/error payloads on top.
- cli/internal/output/envelope.go (new): Envelope / ErrorEnvelope /
Meta / ErrDetail / RiskDetail structs; WriteEnvelope +
WriteErrorEnvelope writers; PendingNotice plumbing for the open-map
_notice channel (reserved infra; producer wiring planned for v0.8).
- cli/internal/output/envelope_test.go (new): 7 tests covering
success / error / TTY indent / Notice / Risk shapes.
- cmdutil.Error extended with RetryCommand (directly-executable
argv distinct from prose Hint), RetryAfterSeconds (HTTP
Retry-After), *RiskInfo (nested level+action; ErrInternalServer-
vs-NotFound distinction), Detail (open structured payload),
Silent (suppress stderr emit while preserving Code for ExitCode).
- ErrorToDetail single source of envelope.error construction; reused
by stderr PrintError, MCP StructuredContent, and batch per-item
error path.
- WithHint / WithRetryCommand / WithRetryAfter / WithDetail /
WithRisk builders. IsCancelled helper. AsError unwrap helper.
- defaultHint covers ~21 codes; defaultRetryCommand symmetric
counterpart for 6 keyway codes. DefaultHint / DefaultRetryCommand
exported wrappers for cross-package callers.
- ClassifyHTTPError tightened: rescues HTTP 500 with structured
server-side code 1003 (ErrNotFound) into resource.not_found.
Server's generic 1007 (ErrInternalServer) bucket stays as
server.error — including it would mis-route validation failures
(e.g. SQLSTATE 22001) as not-found.
- PrintError dual-mode: text/human → prose with code:msg / hint /
retry lines; json/ndjson → envelope on stderr. Mode pinned by
root PersistentPreRunE via SetFormatMode. resolveFormatEarly()
scans argv before cobra dispatch so cobra-side validators
(unknown flag, arg-count) still surface as envelope when
--format json is in effect. Silent typed errors short-circuit
the stderr emit. FlagError mapped to input.invalid_argument for
the envelope (exit code stays 2 via FlagError class).
- Unknown-subcommand guard installed recursively at the root:
parents with subcommands but no Run/RunE get a typed RunE that
emits input.unknown_subcommand envelope with
detail.{unknown, command_path, available[]} and
retry_command "<parent> --help". cobra.ArbitraryArgs bypasses
legacyArgs validation so the guard receives unmatched argv.
- cmdutil.Error.Error() returns "<code>: <message>[: <cause>]" for
chain debugging; ErrorToDetail strips the code prefix from
envelope.message since the separate type field carries it
(prevents the doubled-prefix "code: code: ..." that agents would
see).
Spec: docs/superpowers/specs/2026-05-20-weknora-cli-v0.7-design.md §0 / §4
2026-05-21 10:40:06 +00:00
|
|
|
case "CodeInputConfirmationRequired":
|
|
|
|
|
return cmdutil.CodeInputConfirmationRequired, true
|
|
|
|
|
case "CodeInputUnknownSubcommand":
|
|
|
|
|
return cmdutil.CodeInputUnknownSubcommand, true
|
2026-05-08 08:42:17 +00:00
|
|
|
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
|
refactor(cli): symmetric envelope infrastructure (supersedes e623e820)
Re-introduce the agent-first symmetric envelope deleted in commit
e623e820 (2026-05-15). Under the v0.7 constraint that AI agents are
primary consumers, the bare-JSON shape can't carry protocol channels
(_notice / risk / meta / request_id / profile) that agents need.
Errors-on-stderr and typed exit codes from e623e820 are preserved;
the envelope wraps the success/error payloads on top.
- cli/internal/output/envelope.go (new): Envelope / ErrorEnvelope /
Meta / ErrDetail / RiskDetail structs; WriteEnvelope +
WriteErrorEnvelope writers; PendingNotice plumbing for the open-map
_notice channel (reserved infra; producer wiring planned for v0.8).
- cli/internal/output/envelope_test.go (new): 7 tests covering
success / error / TTY indent / Notice / Risk shapes.
- cmdutil.Error extended with RetryCommand (directly-executable
argv distinct from prose Hint), RetryAfterSeconds (HTTP
Retry-After), *RiskInfo (nested level+action; ErrInternalServer-
vs-NotFound distinction), Detail (open structured payload),
Silent (suppress stderr emit while preserving Code for ExitCode).
- ErrorToDetail single source of envelope.error construction; reused
by stderr PrintError, MCP StructuredContent, and batch per-item
error path.
- WithHint / WithRetryCommand / WithRetryAfter / WithDetail /
WithRisk builders. IsCancelled helper. AsError unwrap helper.
- defaultHint covers ~21 codes; defaultRetryCommand symmetric
counterpart for 6 keyway codes. DefaultHint / DefaultRetryCommand
exported wrappers for cross-package callers.
- ClassifyHTTPError tightened: rescues HTTP 500 with structured
server-side code 1003 (ErrNotFound) into resource.not_found.
Server's generic 1007 (ErrInternalServer) bucket stays as
server.error — including it would mis-route validation failures
(e.g. SQLSTATE 22001) as not-found.
- PrintError dual-mode: text/human → prose with code:msg / hint /
retry lines; json/ndjson → envelope on stderr. Mode pinned by
root PersistentPreRunE via SetFormatMode. resolveFormatEarly()
scans argv before cobra dispatch so cobra-side validators
(unknown flag, arg-count) still surface as envelope when
--format json is in effect. Silent typed errors short-circuit
the stderr emit. FlagError mapped to input.invalid_argument for
the envelope (exit code stays 2 via FlagError class).
- Unknown-subcommand guard installed recursively at the root:
parents with subcommands but no Run/RunE get a typed RunE that
emits input.unknown_subcommand envelope with
detail.{unknown, command_path, available[]} and
retry_command "<parent> --help". cobra.ArbitraryArgs bypasses
legacyArgs validation so the guard receives unmatched argv.
- cmdutil.Error.Error() returns "<code>: <message>[: <cause>]" for
chain debugging; ErrorToDetail strips the code prefix from
envelope.message since the separate type field carries it
(prevents the doubled-prefix "code: code: ..." that agents would
see).
Spec: docs/superpowers/specs/2026-05-20-weknora-cli-v0.7-design.md §0 / §4
2026-05-21 10:40:06 +00:00
|
|
|
case "CodeLocalProfileNotFound":
|
|
|
|
|
return cmdutil.CodeLocalProfileNotFound, true
|
2026-05-10 18:43:55 +00:00
|
|
|
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
|
2026-05-17 17:38:01 +00:00
|
|
|
case "CodeOperationTimeout":
|
|
|
|
|
return cmdutil.CodeOperationTimeout, true
|
|
|
|
|
case "CodeOperationFailed":
|
|
|
|
|
return cmdutil.CodeOperationFailed, true
|
|
|
|
|
case "CodeOperationCancelled":
|
|
|
|
|
return cmdutil.CodeOperationCancelled, true
|
2026-06-26 12:40:59 +00:00
|
|
|
case "CodeInternalError":
|
|
|
|
|
return cmdutil.CodeInternalError, true
|
2026-05-08 08:42:17 +00:00
|
|
|
}
|
|
|
|
|
return "", false
|
|
|
|
|
}
|