refactor(cli): align command surface with gh CLI conventions (ADR-3)

Audited the v0.0~v0.2 21-command surface against gh / kubectl / cargo /
npm / git / docker / flyctl / vercel / supabase / brew. WeKnora was
cherry-picking from multiple heritages, producing an inconsistent feel:
the kb subtree mixed gh verbs (create / delete / list) with a kubectl
verb (get); confirmation flag duplicated --force (docker/kubectl) with
global -y/--yes (gh/vercel/npm); the --agent flag stretched Stripe's
telemetry-tag pattern into a behavior-mode switch that no mainstream
CLI does.

ADR-3 picks gh as the primary north star. Documented deviations remain
for project-link (vercel/cargo), chat (openai-cli), context (kubectl-
light), and doctor (brew/flutter). The decision and its deviations are
documented self-contained in cli/AGENTS.md.

Surface changes:

  - kb get → kb view (gh repo view convention); "get" kept as cobra Alias
    for v0.0/v0.1 callers — see https://cli.github.com/manual/gh_repo_view.

  - kb delete --force / doc delete --force removed in favor of the global
    -y/--yes persistent flag (gh repo delete --yes convention). One
    mechanism skips destructive prompts; ConfirmDestructive's parameter
    renamed `force` → `yes` to match.

  - --agent omnibus mode-switch removed. Stripe's DetectAIAgent (the
    cited inspiration) only tags User-Agent for telemetry, never flips
    behavior; gh / kubectl / aws / docker / flyctl all decline this kind
    of flag. The 7-env auto-detect list is reduced to the two entries
    Stripe also recognizes (CLAUDECODE, CURSOR_AGENT) — the other five
    had no agent-documented source. ApplyAgentSugar / ShouldUseAgentMode
    and the dead --no-interactive / --no-progress globals are deleted
    entirely.

  - DetectAIAgent and SetAgentHelp annotations are kept: env detection
    now only triggers AGENT-targeted help text rendering (no behavior
    change), matching Stripe's narrower scope.

Tests: 27 cli packages green (acceptance/contract still pins kb get
golden; the alias keeps it valid).
This commit is contained in:
nullkey
2026-05-11 02:44:20 +08:00
committed by lyingbug
parent 3fb3583a92
commit 9d2e740753
14 changed files with 96 additions and 249 deletions
+13 -11
View File
@@ -13,9 +13,10 @@ import (
"github.com/Tencent/WeKnora/cli/internal/prompt"
)
// DeleteOptions captures `weknora doc delete` flags.
// DeleteOptions captures `weknora doc delete` flags. Yes is sourced from the
// global -y/--yes persistent flag (gh-style; see cli/cmd/root.go).
type DeleteOptions struct {
Force bool
Yes bool
JSONOut bool
}
@@ -31,20 +32,22 @@ type deleteResult struct {
Deleted bool `json:"deleted"`
}
// NewCmdDelete builds `weknora doc delete`.
// NewCmdDelete builds `weknora doc delete`. Mirrors `gh repo delete --yes`
// confirmation pattern via the global -y/--yes persistent flag.
func NewCmdDelete(f *cmdutil.Factory) *cobra.Command {
opts := &DeleteOptions{}
cmd := &cobra.Command{
Use: "delete <id>",
Short: "Delete a document from a knowledge base",
Long: `Permanently deletes one document. Prompts for confirmation by default
when stdout is a TTY and --json is not set; pass --force to skip the prompt
(required in agent / CI / piped contexts).`,
Example: ` weknora doc delete doc_abc # interactive confirm
weknora doc delete doc_abc --force # no prompt
weknora doc delete doc_abc --force --json # envelope output`,
when stdout is a TTY and --json is not set; pass -y/--yes (global flag) to skip
the prompt (required in agent / CI / piped contexts).`,
Example: ` weknora doc delete doc_abc # interactive confirm
weknora doc delete doc_abc -y # no prompt
weknora doc delete doc_abc -y --json # envelope output`,
Args: cobra.ExactArgs(1),
RunE: func(c *cobra.Command, args []string) error {
opts.Yes, _ = c.Flags().GetBool("yes")
cli, err := f.Client()
if err != nil {
return err
@@ -52,14 +55,13 @@ when stdout is a TTY and --json is not set; pass --force to skip the prompt
return runDelete(c.Context(), opts, cli, f.Prompter(), args[0])
},
}
cmd.Flags().BoolVar(&opts.Force, "force", false, "Skip confirmation prompt")
cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope")
agent.SetAgentHelp(cmd, "Destructively deletes one document by id. ALWAYS pass --force in agent mode (no TTY ⇒ confirm prompt fails). Returns data: {id, deleted:true}.")
agent.SetAgentHelp(cmd, "Destructively deletes one document by id. ALWAYS pass -y/--yes in agent mode (no TTY ⇒ confirm prompt fails). Returns data: {id, deleted:true}.")
return cmd
}
func runDelete(ctx context.Context, opts *DeleteOptions, svc DeleteService, p prompt.Prompter, id string) error {
if err := cmdutil.ConfirmDestructive(p, opts.Force, opts.JSONOut, "document", id); err != nil {
if err := cmdutil.ConfirmDestructive(p, opts.Yes, opts.JSONOut, "document", id); err != nil {
return err
}
+8 -8
View File
@@ -46,7 +46,7 @@ func (errPrompter) Confirm(string, bool) (bool, error) {
func TestDelete_Success_WithForce(t *testing.T) {
out, _ := iostreams.SetForTest(t)
svc := &fakeDeleteSvc{}
opts := &DeleteOptions{Force: true}
opts := &DeleteOptions{Yes: true}
// Force=true short-circuits the confirm path; the prompter must not be
// consulted, so any value works.
require.NoError(t, runDelete(context.Background(), opts, svc, scriptedConfirm{confirmReturn: false}, "doc_abc"))
@@ -60,7 +60,7 @@ func TestDelete_Success_WithForce(t *testing.T) {
func TestDelete_Success_JSON(t *testing.T) {
out, _ := iostreams.SetForTest(t)
svc := &fakeDeleteSvc{}
opts := &DeleteOptions{Force: true, JSONOut: true}
opts := &DeleteOptions{Yes: true, JSONOut: true}
require.NoError(t, runDelete(context.Background(), opts, svc, scriptedConfirm{confirmReturn: true}, "doc_abc"))
got := out.String()
@@ -72,7 +72,7 @@ func TestDelete_Success_JSON(t *testing.T) {
func TestDelete_NotFound_404(t *testing.T) {
_, _ = iostreams.SetForTest(t)
svc := &fakeDeleteSvc{err: errors.New("HTTP error 404: not found")}
err := runDelete(context.Background(), &DeleteOptions{Force: true}, svc, scriptedConfirm{}, "doc_missing")
err := runDelete(context.Background(), &DeleteOptions{Yes: true}, svc, scriptedConfirm{}, "doc_missing")
require.Error(t, err)
var typed *cmdutil.Error
@@ -83,7 +83,7 @@ func TestDelete_NotFound_404(t *testing.T) {
func TestDelete_HTTPError_500(t *testing.T) {
_, _ = iostreams.SetForTest(t)
svc := &fakeDeleteSvc{err: errors.New("HTTP error 500: internal")}
err := runDelete(context.Background(), &DeleteOptions{Force: true}, svc, scriptedConfirm{}, "doc_x")
err := runDelete(context.Background(), &DeleteOptions{Yes: true}, svc, scriptedConfirm{}, "doc_x")
require.Error(t, err)
var typed *cmdutil.Error
@@ -94,7 +94,7 @@ func TestDelete_HTTPError_500(t *testing.T) {
func TestDelete_ConfirmYes(t *testing.T) {
out, _ := iostreams.SetForTestWithTTY(t)
svc := &fakeDeleteSvc{}
err := runDelete(context.Background(), &DeleteOptions{Force: false}, svc, scriptedConfirm{confirmReturn: true}, "doc_abc")
err := runDelete(context.Background(), &DeleteOptions{Yes: false}, svc, scriptedConfirm{confirmReturn: true}, "doc_abc")
require.NoError(t, err)
assert.Equal(t, 1, svc.calls, "user said yes ⇒ delete proceeds")
assert.Contains(t, out.String(), "✓")
@@ -103,7 +103,7 @@ func TestDelete_ConfirmYes(t *testing.T) {
func TestDelete_ConfirmNo(t *testing.T) {
_, errBuf := iostreams.SetForTestWithTTY(t)
svc := &fakeDeleteSvc{}
err := runDelete(context.Background(), &DeleteOptions{Force: false}, svc, scriptedConfirm{confirmReturn: false}, "doc_abc")
err := runDelete(context.Background(), &DeleteOptions{Yes: false}, svc, scriptedConfirm{confirmReturn: false}, "doc_abc")
require.Error(t, err)
assert.Equal(t, 0, svc.calls, "user said no ⇒ SDK must NOT be called")
@@ -119,7 +119,7 @@ func TestDelete_ConfirmNo(t *testing.T) {
func TestDelete_AgentPrompterErrors(t *testing.T) {
_, _ = iostreams.SetForTestWithTTY(t)
svc := &fakeDeleteSvc{}
err := runDelete(context.Background(), &DeleteOptions{Force: false}, svc, errPrompter{}, "doc_abc")
err := runDelete(context.Background(), &DeleteOptions{Yes: false}, svc, errPrompter{}, "doc_abc")
require.Error(t, err)
assert.Equal(t, 0, svc.calls)
@@ -136,7 +136,7 @@ func TestDelete_AgentPrompterErrors(t *testing.T) {
func TestDelete_NoForce_NonTTY_Proceeds(t *testing.T) {
_, _ = iostreams.SetForTest(t)
svc := &fakeDeleteSvc{}
err := runDelete(context.Background(), &DeleteOptions{Force: false}, svc, errPrompter{}, "doc_abc")
err := runDelete(context.Background(), &DeleteOptions{Yes: false}, svc, errPrompter{}, "doc_abc")
require.NoError(t, err, "non-TTY non-json invocation should proceed without prompting")
assert.Equal(t, 1, svc.calls)
}
+14 -10
View File
@@ -13,9 +13,10 @@ import (
"github.com/Tencent/WeKnora/cli/internal/prompt"
)
// DeleteOptions captures `weknora kb delete` flags.
// DeleteOptions captures `weknora kb delete` flags. Yes is sourced from the
// global -y/--yes persistent flag (gh-style; see cli/cmd/root.go addGlobalFlags).
type DeleteOptions struct {
Force bool
Yes bool
JSONOut bool
}
@@ -31,7 +32,10 @@ type deleteResult struct {
Deleted bool `json:"deleted"`
}
// NewCmdDelete builds `weknora kb delete`.
// NewCmdDelete builds `weknora kb delete`. Mirrors `gh repo delete --yes`
// (https://cli.github.com/manual/gh_repo_delete) on the confirmation
// pattern — the global -y/--yes persistent flag is the single skip-prompt
// switch.
func NewCmdDelete(f *cmdutil.Factory) *cobra.Command {
opts := &DeleteOptions{}
cmd := &cobra.Command{
@@ -40,12 +44,13 @@ func NewCmdDelete(f *cmdutil.Factory) *cobra.Command {
Long: `Permanently deletes a knowledge base and all its contents.
Prompts for confirmation by default when stdout is a TTY and --json is not set.
Pass --force to skip the prompt (required in agent / CI / piped contexts).`,
Example: ` weknora kb delete kb_abc # interactive confirm
weknora kb delete kb_abc --force # no prompt
weknora kb delete kb_abc --force --json # envelope output`,
Pass -y/--yes (global flag) to skip the prompt (required in agent / CI / piped contexts).`,
Example: ` weknora kb delete kb_abc # interactive confirm
weknora kb delete kb_abc -y # no prompt
weknora kb delete kb_abc -y --json # envelope output`,
Args: cobra.ExactArgs(1),
RunE: func(c *cobra.Command, args []string) error {
opts.Yes, _ = c.Flags().GetBool("yes")
cli, err := f.Client()
if err != nil {
return err
@@ -53,14 +58,13 @@ Pass --force to skip the prompt (required in agent / CI / piped contexts).`,
return runDelete(c.Context(), opts, cli, f.Prompter(), args[0])
},
}
cmd.Flags().BoolVar(&opts.Force, "force", false, "Skip confirmation prompt")
cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope")
agent.SetAgentHelp(cmd, "Destructively deletes a knowledge base by id. ALWAYS pass --force in agent mode (no TTY ⇒ confirm prompt fails). Returns data: {id, deleted:true}.")
agent.SetAgentHelp(cmd, "Destructively deletes a knowledge base by id. ALWAYS pass -y/--yes in agent mode (no TTY ⇒ confirm prompt fails). Returns data: {id, deleted:true}.")
return cmd
}
func runDelete(ctx context.Context, opts *DeleteOptions, svc DeleteService, p prompt.Prompter, id string) error {
if err := cmdutil.ConfirmDestructive(p, opts.Force, opts.JSONOut, "knowledge base", id); err != nil {
if err := cmdutil.ConfirmDestructive(p, opts.Yes, opts.JSONOut, "knowledge base", id); err != nil {
return err
}
+3 -3
View File
@@ -45,7 +45,7 @@ func TestDelete_Success_WithForce(t *testing.T) {
out, _ := iostreams.SetForTest(t)
svc := &fakeDeleteSvc{}
p := &confirmPrompter{}
opts := &DeleteOptions{Force: true}
opts := &DeleteOptions{Yes: true}
require.NoError(t, runDelete(context.Background(), opts, svc, p, "kb_force"))
assert.True(t, svc.called)
@@ -59,7 +59,7 @@ func TestDelete_NotFound(t *testing.T) {
_, _ = iostreams.SetForTest(t)
svc := &fakeDeleteSvc{err: errors.New("HTTP error 404: not found")}
p := &confirmPrompter{}
err := runDelete(context.Background(), &DeleteOptions{Force: true}, svc, p, "kb_missing")
err := runDelete(context.Background(), &DeleteOptions{Yes: true}, svc, p, "kb_missing")
require.Error(t, err)
var typed *cmdutil.Error
@@ -84,7 +84,7 @@ func TestDelete_JSONOutput(t *testing.T) {
out, _ := iostreams.SetForTest(t)
svc := &fakeDeleteSvc{}
p := &confirmPrompter{}
opts := &DeleteOptions{Force: true, JSONOut: true}
opts := &DeleteOptions{Yes: true, JSONOut: true}
require.NoError(t, runDelete(context.Background(), opts, svc, p, "kb_json"))
got := out.String()
+1 -1
View File
@@ -16,7 +16,7 @@ func NewCmd(f *cmdutil.Factory) *cobra.Command {
Run: func(c *cobra.Command, _ []string) { _ = c.Help() },
}
cmd.AddCommand(NewCmdList(f))
cmd.AddCommand(NewCmdGet(f))
cmd.AddCommand(NewCmdView(f))
cmd.AddCommand(NewCmdCreate(f))
cmd.AddCommand(NewCmdDelete(f))
return cmd
+16 -13
View File
@@ -14,37 +14,40 @@ import (
sdk "github.com/Tencent/WeKnora/client"
)
// GetOptions captures `weknora kb get` flags.
type GetOptions struct {
// ViewOptions captures `weknora kb view` flags.
type ViewOptions struct {
JSONOut bool
}
// GetService is the narrow SDK surface this command depends on.
type GetService interface {
// ViewService is the narrow SDK surface this command depends on.
type ViewService interface {
GetKnowledgeBase(ctx context.Context, id string) (*sdk.KnowledgeBase, error)
}
// NewCmdGet builds `weknora kb get <id>`.
func NewCmdGet(f *cmdutil.Factory) *cobra.Command {
opts := &GetOptions{}
// NewCmdView builds `weknora kb view <id>`. The `get` alias is kept for one
// minor release so v0.0/v0.1 callers don't break; the help text shows `view`
// as primary, mirroring `gh repo view` (https://cli.github.com/manual/gh_repo_view).
func NewCmdView(f *cmdutil.Factory) *cobra.Command {
opts := &ViewOptions{}
cmd := &cobra.Command{
Use: "get <id>",
Short: "Show a knowledge base by ID",
Args: cobra.ExactArgs(1),
Use: "view <id>",
Aliases: []string{"get"},
Short: "Show a knowledge base by ID",
Args: cobra.ExactArgs(1),
RunE: func(c *cobra.Command, args []string) error {
cli, err := f.Client()
if err != nil {
return err
}
return runGet(c.Context(), opts, cli, args[0])
return runView(c.Context(), opts, cli, args[0])
},
}
cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope")
agent.SetAgentHelp(cmd, "Returns details of one knowledge base by ID (config + counts).")
agent.SetAgentHelp(cmd, "Returns details of one knowledge base by ID (config + counts). Aliased as `kb get` for v0.0/v0.1 compat.")
return cmd
}
func runGet(ctx context.Context, opts *GetOptions, svc GetService, id string) error {
func runView(ctx context.Context, opts *ViewOptions, svc ViewService, id string) error {
kb, err := svc.GetKnowledgeBase(ctx, id)
if err != nil {
return cmdutil.Wrapf(cmdutil.ClassifyHTTPError(err), err, "get knowledge base %q", id)
@@ -25,7 +25,7 @@ func TestGet_OK_Human(t *testing.T) {
svc := &fakeGetSvc{kb: &sdk.KnowledgeBase{
ID: "kb1", Name: "Marketing", KnowledgeCount: 12, ChunkCount: 245,
}}
if err := runGet(context.Background(), &GetOptions{}, svc, "kb1"); err != nil {
if err := runView(context.Background(), &ViewOptions{}, svc, "kb1"); err != nil {
t.Fatalf("runGet: %v", err)
}
got := out.String()
@@ -39,7 +39,7 @@ func TestGet_OK_Human(t *testing.T) {
func TestGet_OK_JSON(t *testing.T) {
out, _ := iostreams.SetForTest(t)
svc := &fakeGetSvc{kb: &sdk.KnowledgeBase{ID: "kb1", Name: "Marketing"}}
if err := runGet(context.Background(), &GetOptions{JSONOut: true}, svc, "kb1"); err != nil {
if err := runView(context.Background(), &ViewOptions{JSONOut: true}, svc, "kb1"); err != nil {
t.Fatalf("runGet: %v", err)
}
got := out.String()
@@ -54,7 +54,7 @@ func TestGet_OK_JSON(t *testing.T) {
func TestGet_NotFound(t *testing.T) {
_, _ = iostreams.SetForTest(t)
svc := &fakeGetSvc{err: errors.New("HTTP error 404: not found")}
err := runGet(context.Background(), &GetOptions{}, svc, "missing")
err := runView(context.Background(), &ViewOptions{}, svc, "missing")
if err == nil {
t.Fatal("expected error")
}
+6 -9
View File
@@ -42,7 +42,7 @@ func Execute() int {
return 0
}
err = MapCobraError(err)
if agent.ShouldUseAgentMode(cmd) || WantsJSONOutput(cmd) {
if WantsJSONOutput(cmd) {
cmdutil.PrintErrorEnvelope(iostreams.IO.Out, err)
} else {
cmdutil.PrintError(iostreams.IO.Err, err)
@@ -143,7 +143,7 @@ func NewRootCmd(f *cmdutil.Factory) *cobra.Command {
hybrid searches against a WeKnora server from your shell or an AI agent.`,
Example: ` weknora auth login --host=https://kb.example.com # one-time setup
weknora kb list # list knowledge bases
weknora kb get <id> # show one
weknora kb view <id> # show one
weknora search "your question" --kb=<id> # hybrid retrieval
weknora doctor --json # health check (agent-readable)`,
SilenceUsage: true,
@@ -154,7 +154,6 @@ hybrid searches against a WeKnora server from your shell or an AI agent.`,
// subcommand still owns the richer `--json` envelope output.
Version: fmt.Sprintf("%s (commit %s, built %s)", v, commit, date),
PersistentPreRun: func(c *cobra.Command, args []string) {
agent.ApplyAgentSugar(c)
// Propagate the global --context flag into the Factory for this
// invocation only. Spec §1.2: single-shot override, no disk write.
if v, _ := c.Flags().GetString("context"); v != "" {
@@ -196,20 +195,18 @@ hybrid searches against a WeKnora server from your shell or an AI agent.`,
// v0.7's compat probe consumer.
func addGlobalFlags(cmd *cobra.Command) {
pf := cmd.PersistentFlags()
pf.Bool("agent", false, "Agent mode: envelope JSON output + no interactive prompts + no progress UI")
pf.Bool("no-interactive", false, "Refuse interactive prompts; missing input becomes a hard error")
pf.Bool("no-progress", false, "Suppress progress bars and spinners")
pf.BoolP("yes", "y", false, "Skip confirmation prompts on destructive operations")
pf.String("context", "", "Override the active context for this invocation (no disk write)")
}
// agentAwareHelpFunc wraps cobra's default help to append the AI agent guidance
// (Annotations[agent.AIAgentHelpKey]) only when agent mode is active.
// Stripe pkg/cmd/templates.go pattern.
// (Annotations[agent.AIAgentHelpKey]) only when an AI coding agent env var is
// detected (CLAUDECODE / CURSOR_AGENT). Help-only render — no behavior switch.
// Stripe pkg/cmd/templates.go pattern, but reduced from mode-switch (v0.2 ADR-3).
func agentAwareHelpFunc(orig func(*cobra.Command, []string)) func(*cobra.Command, []string) {
return func(c *cobra.Command, args []string) {
orig(c, args)
if !agent.ShouldUseAgentMode(c) {
if agent.DetectAIAgent() == "" {
return
}
extra := agent.FormatAgentGuidance(c)
+19 -8
View File
@@ -1,5 +1,16 @@
// Package agent handles AI agent integration: --agent flag sugar, env detection,
// and per-command help annotations.
// Package agent handles AI agent integration: env-based detection (used to
// trigger AGENT-targeted help text) and per-command help annotations.
//
// v0.2: removed the omnibus `--agent` flag + ApplyAgentSugar mode-switch
// (audited as over-design — see docs/superpowers/specs/2026-05-09 ADR-3).
// Mainstream CLIs (gh / kubectl / aws / docker / flyctl) deliberately don't
// have a single mode-switch flag; per-command --json + TTY auto-detect cover
// 95% of cases. WeKnora now follows that convention.
//
// What remains here: a small env-detect for known coding agents, used purely
// to render the AGENT-targeted help section (no behavior change). Patterned
// after Stripe's DetectAIAgent (https://github.com/stripe/stripe-cli/tree/master/pkg/useragent),
// which Stripe uses only for User-Agent telemetry tagging.
package agent
import "os"
@@ -9,18 +20,18 @@ import "os"
type AIAgentName string
// aiAgentEnvs maps environment variable presence to a coding agent name.
// Modeled on Stripe's pkg/useragent/useragent.go DetectAIAgent.
// Cropped to the entries the Stripe CLI also recognizes (verified against
// stripe-cli/pkg/useragent/useragent.go). The earlier 7-entry list (CODEX_*,
// AIDER_PROMPT, CONTINUE_GLOBAL_DIR, OPENCODE_RUNNING, GEMINICODER_PROFILE)
// did not have official agent docs backing those env names; removed in v0.2
// to avoid maintaining an unverified hardcoded list. New entries should
// document the source URL.
var aiAgentEnvs = []struct {
env string
name AIAgentName
}{
{"CLAUDECODE", "claude-code"},
{"CURSOR_AGENT", "cursor"},
{"CODEX_PROMPT_HOSTNAME", "codex"},
{"AIDER_PROMPT", "aider"},
{"CONTINUE_GLOBAL_DIR", "continue"},
{"OPENCODE_RUNNING", "opencode"},
{"GEMINICODER_PROFILE", "gemini-coder"},
}
// DetectAIAgent returns the first known agent name whose env var is set to a
+3 -31
View File
@@ -28,11 +28,9 @@ func TestDetectAIAgent(t *testing.T) {
{name: "unrelated env", set: map[string]string{"PATH": "/usr/bin"}, want: ""},
{name: "claude code", set: map[string]string{"CLAUDECODE": "1"}, want: "claude-code"},
{name: "cursor", set: map[string]string{"CURSOR_AGENT": "yes"}, want: "cursor"},
{name: "codex", set: map[string]string{"CODEX_PROMPT_HOSTNAME": "host"}, want: "codex"},
{name: "aider", set: map[string]string{"AIDER_PROMPT": "y"}, want: "aider"},
{name: "continue", set: map[string]string{"CONTINUE_GLOBAL_DIR": "/tmp"}, want: "continue"},
{name: "opencode", set: map[string]string{"OPENCODE_RUNNING": "1"}, want: "opencode"},
{name: "gemini-coder", set: map[string]string{"GEMINICODER_PROFILE": "default"}, want: "gemini-coder"},
// Other entries (codex / aider / continue / opencode / gemini-coder)
// were dropped in v0.2 ADR-3 — env names had no official agent docs.
// New entries should arrive with a documented source URL.
{
name: "first-match precedence",
set: map[string]string{"CLAUDECODE": "1", "CURSOR_AGENT": "1"},
@@ -62,29 +60,3 @@ func TestDetectAIAgent(t *testing.T) {
}
}
func TestShouldUseAgentMode_Triggers(t *testing.T) {
t.Run("WEKNORA_AGENT=1 triggers", func(t *testing.T) {
clearAgentEnv(t)
t.Setenv("WEKNORA_AGENT", "1")
assert.True(t, ShouldUseAgentMode(nil))
})
t.Run("WEKNORA_AGENT=true triggers", func(t *testing.T) {
clearAgentEnv(t)
t.Setenv("WEKNORA_AGENT", "true")
assert.True(t, ShouldUseAgentMode(nil))
})
t.Run("WEKNORA_AGENT=0 does not trigger", func(t *testing.T) {
clearAgentEnv(t)
t.Setenv("WEKNORA_AGENT", "0")
assert.False(t, ShouldUseAgentMode(nil))
})
t.Run("AI agent env triggers", func(t *testing.T) {
clearAgentEnv(t)
t.Setenv("CLAUDECODE", "1")
assert.True(t, ShouldUseAgentMode(nil))
})
t.Run("no triggers", func(t *testing.T) {
clearAgentEnv(t)
assert.False(t, ShouldUseAgentMode(nil))
})
}
-56
View File
@@ -1,56 +0,0 @@
package agent
import (
"os"
"github.com/spf13/cobra"
)
// agentSugarFlags lists the flags ApplyAgentSugar sets to their agent-friendly
// defaults when triggered. Each entry is no-op'd at runtime if the leaf hasn't
// registered the flag (e.g. version doesn't have --no-progress).
var agentSugarFlags = []struct{ name, value string }{
{"json", "true"},
{"no-interactive", "true"},
{"no-progress", "true"},
}
// ApplyAgentSugar evaluates --agent / WEKNORA_AGENT / env-based AI agent
// detection, then sets json / no-interactive / no-progress to their
// agent-friendly defaults unless the user already set them.
func ApplyAgentSugar(cmd *cobra.Command) {
if !ShouldUseAgentMode(cmd) {
return
}
for _, kv := range agentSugarFlags {
if f := cmd.Flags().Lookup(kv.name); f != nil && !cmd.Flags().Changed(kv.name) {
_ = cmd.Flags().Set(kv.name, kv.value)
}
}
}
// ShouldUseAgentMode returns true if any of the three triggers are active:
// (1) --agent flag, (2) WEKNORA_AGENT=1 env, (3) a known agent env var is set.
func ShouldUseAgentMode(cmd *cobra.Command) bool {
if cmd != nil {
if v, err := cmd.Flags().GetBool("agent"); err == nil && v {
return true
}
}
if truthy(os.Getenv("WEKNORA_AGENT")) {
return true
}
return DetectAIAgent() != ""
}
// truthy treats any non-empty value other than "0" / "false" / "FALSE" as
// truthy. This is wider than strconv.ParseBool by design — users set
// WEKNORA_AGENT=1, =true, or =yes interchangeably across CI shells.
func truthy(v string) bool {
switch v {
case "", "0", "false", "FALSE":
return false
default:
return true
}
}
-87
View File
@@ -1,87 +0,0 @@
package agent
import (
"testing"
"github.com/spf13/cobra"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)
// newTestCmd returns a cobra command with the flags ApplyAgentSugar
// expects to be present (`--agent`, `--json`, `--no-interactive`,
// `--no-progress`).
func newTestCmd() *cobra.Command {
c := &cobra.Command{Use: "x"}
c.Flags().Bool("agent", false, "")
c.Flags().Bool("json", false, "")
c.Flags().Bool("no-interactive", false, "")
c.Flags().Bool("no-progress", false, "")
return c
}
func TestApplyAgentSugar_AgentFlagSet(t *testing.T) {
c := newTestCmd()
require.NoError(t, c.Flags().Set("agent", "true"))
ApplyAgentSugar(c)
j, _ := c.Flags().GetBool("json")
assert.True(t, j)
ni, _ := c.Flags().GetBool("no-interactive")
assert.True(t, ni)
np, _ := c.Flags().GetBool("no-progress")
assert.True(t, np)
}
func TestApplyAgentSugar_NoTrigger(t *testing.T) {
clearAgentEnv(t)
c := newTestCmd()
ApplyAgentSugar(c)
j, _ := c.Flags().GetBool("json")
assert.False(t, j, "without --agent or env, --json must remain unset")
}
func TestApplyAgentSugar_ExplicitJSONFalseWins(t *testing.T) {
clearAgentEnv(t)
c := newTestCmd()
require.NoError(t, c.Flags().Set("agent", "true"))
require.NoError(t, c.Flags().Set("json", "false"))
ApplyAgentSugar(c)
j, _ := c.Flags().GetBool("json")
assert.False(t, j, "explicit --json=false must override agent sugar")
}
func TestFormatAgentGuidance(t *testing.T) {
c := &cobra.Command{Use: "x"}
assert.Equal(t, "", FormatAgentGuidance(c))
SetAgentHelp(c, " use --idempotency-key for safe retries ")
assert.Equal(t, "use --idempotency-key for safe retries", FormatAgentGuidance(c))
}
func TestSetAgentHelp_InitsAnnotations(t *testing.T) {
c := &cobra.Command{Use: "x"}
assert.Nil(t, c.Annotations)
SetAgentHelp(c, "blurb")
require.NotNil(t, c.Annotations)
assert.Equal(t, "blurb", c.Annotations[AIAgentHelpKey])
}
func TestTruthy(t *testing.T) {
cases := []struct {
in string
want bool
}{
{"", false},
{"0", false},
{"false", false},
{"FALSE", false},
{"1", true},
{"true", true},
{"yes", true},
{"anything-else", true},
}
for _, tc := range cases {
t.Run(tc.in, func(t *testing.T) {
assert.Equal(t, tc.want, truthy(tc.in))
})
}
}
+8 -8
View File
@@ -11,10 +11,10 @@ import (
// (e.g. delete) when the call is interactive, and proceeds without
// prompting otherwise. Behavior matrix:
//
// force=true → proceed (skip prompt; explicit user opt-in)
// yes=true → proceed (skip prompt; explicit user opt-in via -y)
// non-TTY stdout → proceed (no UI to ask; safer to follow the call
// than to break scripts/CI that don't pass
// --force every time)
// -y every time)
// jsonOut=true → proceed (envelope mode is by definition scripted,
// a prompt would deadlock the consumer)
// TTY + interactive → prompt; user-yes proceeds, user-no returns
@@ -22,12 +22,12 @@ import (
// prompter error → returns CodeInputMissingFlag (rare; AgentPrompter
// path or stdin closed mid-prompt)
//
// Callers that want a hard fail in non-TTY contexts should validate at the
// command layer (e.g. require --force when stdout is not a terminal). The
// agent-help text on each destructive command says "ALWAYS pass --force in
// agent mode" — this is the documented contract, not an enforcement here.
func ConfirmDestructive(p prompt.Prompter, force, jsonOut bool, what, id string) error {
if force || !iostreams.IO.IsStdoutTTY() || jsonOut {
// `yes` should be sourced from the persistent global -y/--yes flag (see
// addGlobalFlags in cli/cmd/root.go). Mirrors gh's `--yes` semantics on
// destructive commands: gh repo delete --yes
// (https://cli.github.com/manual/gh_repo_delete).
func ConfirmDestructive(p prompt.Prompter, yes, jsonOut bool, what, id string) error {
if yes || !iostreams.IO.IsStdoutTTY() || jsonOut {
return nil
}
ok, err := p.Confirm(fmt.Sprintf("Delete %s %s? This cannot be undone.", what, id), false)
+2 -1
View File
@@ -55,7 +55,8 @@ type ErrorBody struct {
}
// WriteEnvelope serializes env as one-line JSON to w. Used for non-TTY output
// and for `--format json` / `--agent` modes.
// and for `--json` per-command mode (the omnibus `--agent` mode-switch was
// removed in v0.2 ADR-3; see docs/superpowers/specs/2026-05-09).
func WriteEnvelope(w io.Writer, env Envelope) error {
enc := json.NewEncoder(w)
enc.SetEscapeHTML(false)