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:
+13
-11
@@ -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
|
||||
}
|
||||
|
||||
|
||||
@@ -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
@@ -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
|
||||
}
|
||||
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
@@ -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
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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))
|
||||
})
|
||||
}
|
||||
|
||||
@@ -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
|
||||
}
|
||||
}
|
||||
@@ -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))
|
||||
})
|
||||
}
|
||||
}
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user