Files
Enterprise-Knowledge-Base/cli/internal/format/envelope.go
T
nullkey 9d2e740753 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).
2026-05-12 13:20:42 +08:00

75 lines
2.6 KiB
Go

// Package format renders command output: JSON envelope, jq, template, table.
//
// Non-TTY default = JSON envelope (ADR-5). Envelope schema is the contract
// shared with `weknora mcp serve` tools and external agents.
package format
import (
"encoding/json"
"io"
)
// Envelope is the canonical success/failure shape returned by every command.
type Envelope struct {
OK bool `json:"ok"`
Data any `json:"data,omitempty"`
Error *ErrorBody `json:"error,omitempty"`
Meta *Meta `json:"_meta,omitempty"`
}
// Meta carries non-payload context fields useful to agents and observability.
type Meta struct {
Context string `json:"context,omitempty"`
TenantID uint64 `json:"tenant_id,omitempty"`
KBID string `json:"kb_id,omitempty"`
RequestID string `json:"request_id,omitempty"`
NextCursor string `json:"next_cursor,omitempty"`
HasMore bool `json:"has_more,omitempty"`
Warnings []string `json:"warnings,omitempty"`
AppliedFilters []string `json:"applied_filters,omitempty"`
}
// RiskLevel classifies an error by the kind of operation that produced it.
// Agents use this to decide whether to retry, escalate, or stop.
type RiskLevel string
const (
RiskRead RiskLevel = "read"
RiskMutating RiskLevel = "mutating"
RiskDestructive RiskLevel = "destructive"
)
// ErrorBody is the failure shape. `code` is a stable namespaced ID (e.g.
// "auth.unauthenticated"); `hint` is an actionable next step; `risk` flags
// destructive intent for agent self-governance.
type ErrorBody struct {
Code string `json:"code"`
Message string `json:"message"`
Hint string `json:"hint,omitempty"`
RequestID string `json:"request_id,omitempty"`
Context string `json:"context,omitempty"`
Risk RiskLevel `json:"risk,omitempty"`
Retryable bool `json:"retryable,omitempty"`
ConsoleURL string `json:"console_url,omitempty"`
Details map[string]any `json:"details,omitempty"`
}
// WriteEnvelope serializes env as one-line JSON to w. Used for non-TTY output
// 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)
return enc.Encode(env)
}
// Success constructs a success envelope.
func Success(data any, meta *Meta) Envelope {
return Envelope{OK: true, Data: data, Meta: meta}
}
// Failure constructs a failure envelope.
func Failure(err *ErrorBody) Envelope {
return Envelope{OK: false, Error: err}
}