WeKnora/cli/internal/agent/annotations.go

36 lines
1.1 KiB
Go
Raw Normal View History

package agent
import (
"strings"
"github.com/spf13/cobra"
)
// AIAgentHelpKey is the cobra Annotation key used to attach an AI-agent-specific
// help blurb to a command. The blurb is appended to --help output only when
// agent mode is active. Mirrors Stripe's pkg/cmd/templates.go AIAgentHelpAnnotationKey.
const AIAgentHelpKey = "ai_agent_help"
// FormatAgentGuidance returns the agent-targeted help text registered on cmd,
chore(cli): remove unused v0.0 scaffolding Foundation PR-1 reserved several internal packages and helpers as scaffolding for follow-up PRs that ended up taking different routes. Audit confirms zero production references; this commit removes them so the cli/ tree reflects what's actually shipped. Removed (148 LOC): cli/internal/safepaths/ — `Validate` / `WithinRoot` / three sentinel errors. Reserved for `weknora doc upload`'s path scrubbing; that command landed in PR-10 using its own `validateUploadPath` (os.Stat + regular-file check) — sufficient for the actual threat model (local CLI invocations). cli/internal/cmdutil/json_flags.go — `AddJSONFlags` helper + unused --jq / --template flag registration. Reserved for PR-3 "lipgloss tables / jq evaluator" which never materialized; every command directly registers BoolVar(&JSONOut, "json", ...) since v0.0 ship time. cmdutil.NewTableExporter — empty alias for jsonExporter, reserved for the same PR-3 renderer. Removed; jsonExporter stays under NewJSONExporter. cmdutil.Options marker interface — empty interface{} reserved as a convention; no command embeds or asserts against it. Stale comments fixed: - cmd/root.go: package comment updated kb (list+get) → kb (list+view+create+delete) and noted the `get` cobra alias. - cmd/root.go: dropped --no-version-check forward-reference (no such flag). - cmd/root.go: removed "(PR-7)" attribution from NewRootCmd doc comment. - cmd/kb/kb.go: same package-comment update. - cmd/chat/chat.go: replaced "PR-7" mention in --help example with a generic placeholder so cobra-rendered help is review-clean. - cmd/search/search.go: removed "Lipgloss tables arrive in PR-3" forward-reference; the inline indent helper is the shipped form. - internal/agent/annotations.go: ShouldUseAgentMode → DetectAIAgent (removed in PR-12). AGENTS.md "Known limitations" section added: Documents that chat / search / doc upload currently surface server-side precondition misses (LLM / vector store / storage engine not configured) as `network.error` with `context deadline exceeded`. A planned future release will introduce a `precondition.*` typed error namespace (server returns HTTP 412 before opening the SSE / streaming response). This documents the limitation honestly for reviewers and integrators rather than claiming a behavior we don't yet have. Tests: 27 cli packages pass (safepaths_test was the 28th — gone with the package). go vet clean.
2026-05-10 18:44:41 +00:00
// or "" if none. Render it after the standard help when DetectAIAgent() != ""
// (an AI coding agent env var is set).
func FormatAgentGuidance(cmd *cobra.Command) string {
if cmd == nil {
return ""
}
v, ok := cmd.Annotations[AIAgentHelpKey]
if !ok {
return ""
}
return strings.TrimSpace(v)
}
// SetAgentHelp is a small helper that initializes Annotations and stores the
// blurb under AIAgentHelpKey. Use it in NewCmdX constructors before returning.
func SetAgentHelp(cmd *cobra.Command, blurb string) {
if cmd.Annotations == nil {
cmd.Annotations = map[string]string{}
}
cmd.Annotations[AIAgentHelpKey] = strings.TrimSpace(blurb)
}