2026-05-06 06:22:36 +00:00
|
|
|
// Package cmd holds the cobra command tree. main.go calls Execute().
|
|
|
|
|
package cmd
|
|
|
|
|
|
|
|
|
|
import (
|
2026-05-17 17:38:16 +00:00
|
|
|
"context"
|
2026-05-06 06:22:36 +00:00
|
|
|
"fmt"
|
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
|
|
|
"os"
|
|
|
|
|
"sort"
|
2026-05-06 06:22:36 +00:00
|
|
|
"strings"
|
|
|
|
|
|
|
|
|
|
"github.com/spf13/cobra"
|
|
|
|
|
|
2026-05-14 15:28:14 +00:00
|
|
|
agentcmd "github.com/Tencent/WeKnora/cli/cmd/agent"
|
2026-05-10 18:44:13 +00:00
|
|
|
apicmd "github.com/Tencent/WeKnora/cli/cmd/api"
|
2026-05-06 06:23:45 +00:00
|
|
|
"github.com/Tencent/WeKnora/cli/cmd/auth"
|
2026-05-10 18:44:13 +00:00
|
|
|
chatcmd "github.com/Tencent/WeKnora/cli/cmd/chat"
|
2026-05-15 17:22:14 +00:00
|
|
|
chunkcmd "github.com/Tencent/WeKnora/cli/cmd/chunk"
|
2026-06-26 12:40:59 +00:00
|
|
|
configcmd "github.com/Tencent/WeKnora/cli/cmd/config"
|
2026-05-10 18:44:06 +00:00
|
|
|
"github.com/Tencent/WeKnora/cli/cmd/doc"
|
2026-05-08 08:13:58 +00:00
|
|
|
"github.com/Tencent/WeKnora/cli/cmd/doctor"
|
|
|
|
|
"github.com/Tencent/WeKnora/cli/cmd/kb"
|
2026-05-10 18:43:55 +00:00
|
|
|
linkcmd "github.com/Tencent/WeKnora/cli/cmd/link"
|
2026-06-26 12:40:59 +00:00
|
|
|
messagecmd "github.com/Tencent/WeKnora/cli/cmd/message"
|
2026-05-14 15:28:14 +00:00
|
|
|
mcpcmd "github.com/Tencent/WeKnora/cli/cmd/mcp"
|
2026-06-26 12:40:59 +00:00
|
|
|
modelcmd "github.com/Tencent/WeKnora/cli/cmd/model"
|
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
|
|
|
profilecmd "github.com/Tencent/WeKnora/cli/cmd/profile"
|
2026-05-06 06:24:11 +00:00
|
|
|
"github.com/Tencent/WeKnora/cli/cmd/search"
|
2026-05-12 15:34:33 +00:00
|
|
|
sessioncmd "github.com/Tencent/WeKnora/cli/cmd/session"
|
2026-06-26 12:40:59 +00:00
|
|
|
skillscmd "github.com/Tencent/WeKnora/cli/cmd/skills"
|
2026-05-06 06:22:36 +00:00
|
|
|
"github.com/Tencent/WeKnora/cli/internal/build"
|
|
|
|
|
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
|
|
|
|
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
|
|
|
|
)
|
|
|
|
|
|
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
|
|
|
// resolveFormatEarly scans raw argv for --format before cobra's command
|
|
|
|
|
// dispatch. This ensures globalFormatMode is set before any cobra-side
|
|
|
|
|
// validator fires (unknown flag, arg count, etc.), so PrintError routes
|
|
|
|
|
// those errors through the JSON envelope when --format json is in effect.
|
|
|
|
|
//
|
|
|
|
|
// Call order: resolveFormatEarly → cobra Execute → PersistentPreRunE (which
|
|
|
|
|
// re-runs CheckFormatFlag and calls SetFormatMode again with the same value).
|
|
|
|
|
func resolveFormatEarly(args []string) {
|
|
|
|
|
var mode string
|
|
|
|
|
for i, a := range args {
|
|
|
|
|
if a == "--format" && i+1 < len(args) {
|
|
|
|
|
mode = strings.ToLower(args[i+1])
|
|
|
|
|
break
|
|
|
|
|
}
|
|
|
|
|
if strings.HasPrefix(a, "--format=") {
|
|
|
|
|
mode = strings.ToLower(strings.TrimPrefix(a, "--format="))
|
|
|
|
|
break
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
if mode == "" {
|
|
|
|
|
if v := os.Getenv("WEKNORA_FORMAT"); v != "" {
|
|
|
|
|
mode = strings.ToLower(v)
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
switch mode {
|
2026-05-29 12:06:53 +00:00
|
|
|
case "ndjson", "text":
|
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
|
|
|
cmdutil.SetFormatMode(mode)
|
|
|
|
|
default:
|
2026-05-29 12:06:53 +00:00
|
|
|
// "json", "" (no flag/env), or an invalid value all route the cobra-side
|
|
|
|
|
// error through the JSON envelope. Cobra parse errors fire before
|
|
|
|
|
// PersistentPreRunE runs ResolveDefault, so we apply the same default
|
|
|
|
|
// here (DefaultFormatMode) — otherwise the error path would emit prose
|
|
|
|
|
// while the success path emits the envelope.
|
|
|
|
|
cmdutil.SetFormatMode(string(cmdutil.DefaultFormatMode))
|
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
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
2026-05-06 06:22:36 +00:00
|
|
|
// Execute is the entry point invoked by main(). Returns the process exit code.
|
2026-05-17 17:38:16 +00:00
|
|
|
// The passed context is wired to OS signals (SIGINT / SIGTERM) by main so
|
|
|
|
|
// commands that respect cmd.Context() can run their cancellation cleanup.
|
|
|
|
|
func Execute(ctx context.Context) int {
|
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
|
|
|
// Resolve --format early so cobra-side errors (unknown flag, arg-count
|
|
|
|
|
// violations) still route through PrintError's JSON envelope path when
|
|
|
|
|
// --format json is in effect. PersistentPreRunE will call SetFormatMode
|
|
|
|
|
// again after full flag parse - idempotent when the value matches.
|
|
|
|
|
resolveFormatEarly(os.Args[1:])
|
2026-05-08 08:13:58 +00:00
|
|
|
root := NewRootCmd(cmdutil.New())
|
2026-05-17 17:38:16 +00:00
|
|
|
if err := root.ExecuteContext(ctx); err != nil {
|
2026-05-15 18:42:18 +00:00
|
|
|
// Errors go to stderr. Stdout stays
|
refactor(cli): delete envelope infrastructure, errors to stderr
Removes the entire envelope machinery now that every success path
emits bare JSON:
- cli/internal/format/envelope.go (Envelope, Success, Failure,
SuccessWithRisk, WriteEnvelope, Meta, Notice, UpdateNotice,
VersionSkewNotice, Risk, RiskLevel, ErrorBody) + tests.
- cli/internal/format/filter.go envelope-specific helpers
(WriteEnvelopeFiltered, marshalEnvelope, applyFieldFilter,
filterDataPayload, filterObjectData); the reusable
filterArrayItems / filterObjectKeys / writeJQ stay for bare.go.
- cli/internal/cmdutil/exporter.go + tests (envelope-only).
- cli/internal/cmdutil/PrintErrorEnvelope + ToErrorBody +
operationRiskOf + Error.OperationRisk field + OperationRisk struct.
Error path: all errors now go to stderr via cmdutil.PrintError in
`code: message\nhint: ...` form, regardless of --json. Stdout stays
empty (or holds the partial-success the command already wrote) so
downstream `--json | jq` pipelines never have to filter error shapes
out of the success stream. Typed exit codes (3 auth.* / 4
resource.not_found / 5 input.* / 6 server.rate_limited / 7 server.*
+ network.* / 10 input.confirmation_required) carry the failure
class for agents that branch on it.
Acceptance contract:
- envelope_test.go → wire_test.go (TestEnvelopeGolden → TestWireGolden).
- testdata/envelopes/ → testdata/wire/.
- Error-path cases assert the typed code substring on stderr.
- Orphan whoami.*.json goldens deleted.
AGENTS.md + README.md rewritten for the bare-data contract:
- Drop envelope schema section + dry-run rule.
- Document bare JSON on stdout + `code: msg\nhint: …` on stderr.
- ADR-3 reframed around bare data and why error separation matters
for `--json | jq` pipelines.
WriteJSONFiltered short-circuits to WriteJSON when both filters are
empty (skip the marshal-buffer round-trip for the common case).
Final review pass:
- Fix wire-contract bug: `--json id,name` (space form) is broken by
pflag's NoOptDefVal; AGENTS.md / README.md / SetAgentHelp + the
field-discovery help text all switched to `--json=id,name`.
- Fix `weknora api --jq` silently ignored: api.go now routes through
WriteJSONFiltered with jopts.JQ.
- AGENTS.md: drop the false claim that `auth logout` honors `-y`
(logout is local-only with no ConfirmDestructive guard); list the
actual destructive commands instead.
- Rewrite cli/acceptance/e2e/e2e_test.go for the bare-data wire shape
(was still parsing `out["data"]` / `env["ok"]`).
- Add `JSONOptions.Emit(w, v)` helper; collapse ~33 repeated
`format.WriteJSONFiltered(iostreams.IO.Out, X, jopts.Fields,
jopts.JQ)` sites to `jopts.Emit(iostreams.IO.Out, X)` — drops the
format import from 22 cmd/* files.
- Delete single-caller `cmdutil.MustRequireFlag`; inline as
`_ = cmd.MarkFlagRequired(...)` everywhere.
- Add `_ = cmd.MarkFlagRequired("name")` to `kb create`; it was the
only write command relying on runtime --name validation while
`context add` already used the cobra-level mark.
- `context use`: register `--json` / `--jq` (was always emitting JSON
unconditionally with no human path and no flag — diverged from
every other write command); human mode now prints
`✓ Switched context to X (was Y)`.
- Replace per-package `confirmPrompter` / `scriptedConfirm` /
`errPrompter` test doubles with `testutil.ConfirmPrompter`.
- Rename `chatService` → `ChatService` (export to match siblings
`ListService` / `ViewService`); rename `printUploadSuccess` →
`renderUploadSuccess` (siblings use `render*`).
- `defaultHint(CodeResourceNotFound)`: drop the hardcoded
"list available with `weknora kb list`" — misleading on agent /
doc / session 404. Replaced with "verify the resource ID and try
again".
- Strip stale `v0.2/v0.3` / "envelope" / "v0.0/v0.1 supports only"
historical tags from production comments and a few test
descriptions.
2026-05-14 17:51:11 +00:00
|
|
|
// empty (or holds partial success the command produced) so
|
2026-05-17 17:38:16 +00:00
|
|
|
// downstream `--format json | jq` pipelines never filter error shapes
|
refactor(cli): delete envelope infrastructure, errors to stderr
Removes the entire envelope machinery now that every success path
emits bare JSON:
- cli/internal/format/envelope.go (Envelope, Success, Failure,
SuccessWithRisk, WriteEnvelope, Meta, Notice, UpdateNotice,
VersionSkewNotice, Risk, RiskLevel, ErrorBody) + tests.
- cli/internal/format/filter.go envelope-specific helpers
(WriteEnvelopeFiltered, marshalEnvelope, applyFieldFilter,
filterDataPayload, filterObjectData); the reusable
filterArrayItems / filterObjectKeys / writeJQ stay for bare.go.
- cli/internal/cmdutil/exporter.go + tests (envelope-only).
- cli/internal/cmdutil/PrintErrorEnvelope + ToErrorBody +
operationRiskOf + Error.OperationRisk field + OperationRisk struct.
Error path: all errors now go to stderr via cmdutil.PrintError in
`code: message\nhint: ...` form, regardless of --json. Stdout stays
empty (or holds the partial-success the command already wrote) so
downstream `--json | jq` pipelines never have to filter error shapes
out of the success stream. Typed exit codes (3 auth.* / 4
resource.not_found / 5 input.* / 6 server.rate_limited / 7 server.*
+ network.* / 10 input.confirmation_required) carry the failure
class for agents that branch on it.
Acceptance contract:
- envelope_test.go → wire_test.go (TestEnvelopeGolden → TestWireGolden).
- testdata/envelopes/ → testdata/wire/.
- Error-path cases assert the typed code substring on stderr.
- Orphan whoami.*.json goldens deleted.
AGENTS.md + README.md rewritten for the bare-data contract:
- Drop envelope schema section + dry-run rule.
- Document bare JSON on stdout + `code: msg\nhint: …` on stderr.
- ADR-3 reframed around bare data and why error separation matters
for `--json | jq` pipelines.
WriteJSONFiltered short-circuits to WriteJSON when both filters are
empty (skip the marshal-buffer round-trip for the common case).
Final review pass:
- Fix wire-contract bug: `--json id,name` (space form) is broken by
pflag's NoOptDefVal; AGENTS.md / README.md / SetAgentHelp + the
field-discovery help text all switched to `--json=id,name`.
- Fix `weknora api --jq` silently ignored: api.go now routes through
WriteJSONFiltered with jopts.JQ.
- AGENTS.md: drop the false claim that `auth logout` honors `-y`
(logout is local-only with no ConfirmDestructive guard); list the
actual destructive commands instead.
- Rewrite cli/acceptance/e2e/e2e_test.go for the bare-data wire shape
(was still parsing `out["data"]` / `env["ok"]`).
- Add `JSONOptions.Emit(w, v)` helper; collapse ~33 repeated
`format.WriteJSONFiltered(iostreams.IO.Out, X, jopts.Fields,
jopts.JQ)` sites to `jopts.Emit(iostreams.IO.Out, X)` — drops the
format import from 22 cmd/* files.
- Delete single-caller `cmdutil.MustRequireFlag`; inline as
`_ = cmd.MarkFlagRequired(...)` everywhere.
- Add `_ = cmd.MarkFlagRequired("name")` to `kb create`; it was the
only write command relying on runtime --name validation while
`context add` already used the cobra-level mark.
- `context use`: register `--json` / `--jq` (was always emitting JSON
unconditionally with no human path and no flag — diverged from
every other write command); human mode now prints
`✓ Switched context to X (was Y)`.
- Replace per-package `confirmPrompter` / `scriptedConfirm` /
`errPrompter` test doubles with `testutil.ConfirmPrompter`.
- Rename `chatService` → `ChatService` (export to match siblings
`ListService` / `ViewService`); rename `printUploadSuccess` →
`renderUploadSuccess` (siblings use `render*`).
- `defaultHint(CodeResourceNotFound)`: drop the hardcoded
"list available with `weknora kb list`" — misleading on agent /
doc / session 404. Replaced with "verify the resource ID and try
again".
- Strip stale `v0.2/v0.3` / "envelope" / "v0.0/v0.1 supports only"
historical tags from production comments and a few test
descriptions.
2026-05-14 17:51:11 +00:00
|
|
|
// out of the success stream. The typed exit code (3/4/5/6/7/10)
|
|
|
|
|
// carries the error class.
|
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
|
|
|
mapped := MapCobraError(err)
|
|
|
|
|
cmdutil.PrintError(iostreams.IO.Err, mapped)
|
|
|
|
|
return cmdutil.ExitCode(mapped)
|
2026-05-06 06:22:36 +00:00
|
|
|
}
|
refactor(cli): delete envelope infrastructure, errors to stderr
Removes the entire envelope machinery now that every success path
emits bare JSON:
- cli/internal/format/envelope.go (Envelope, Success, Failure,
SuccessWithRisk, WriteEnvelope, Meta, Notice, UpdateNotice,
VersionSkewNotice, Risk, RiskLevel, ErrorBody) + tests.
- cli/internal/format/filter.go envelope-specific helpers
(WriteEnvelopeFiltered, marshalEnvelope, applyFieldFilter,
filterDataPayload, filterObjectData); the reusable
filterArrayItems / filterObjectKeys / writeJQ stay for bare.go.
- cli/internal/cmdutil/exporter.go + tests (envelope-only).
- cli/internal/cmdutil/PrintErrorEnvelope + ToErrorBody +
operationRiskOf + Error.OperationRisk field + OperationRisk struct.
Error path: all errors now go to stderr via cmdutil.PrintError in
`code: message\nhint: ...` form, regardless of --json. Stdout stays
empty (or holds the partial-success the command already wrote) so
downstream `--json | jq` pipelines never have to filter error shapes
out of the success stream. Typed exit codes (3 auth.* / 4
resource.not_found / 5 input.* / 6 server.rate_limited / 7 server.*
+ network.* / 10 input.confirmation_required) carry the failure
class for agents that branch on it.
Acceptance contract:
- envelope_test.go → wire_test.go (TestEnvelopeGolden → TestWireGolden).
- testdata/envelopes/ → testdata/wire/.
- Error-path cases assert the typed code substring on stderr.
- Orphan whoami.*.json goldens deleted.
AGENTS.md + README.md rewritten for the bare-data contract:
- Drop envelope schema section + dry-run rule.
- Document bare JSON on stdout + `code: msg\nhint: …` on stderr.
- ADR-3 reframed around bare data and why error separation matters
for `--json | jq` pipelines.
WriteJSONFiltered short-circuits to WriteJSON when both filters are
empty (skip the marshal-buffer round-trip for the common case).
Final review pass:
- Fix wire-contract bug: `--json id,name` (space form) is broken by
pflag's NoOptDefVal; AGENTS.md / README.md / SetAgentHelp + the
field-discovery help text all switched to `--json=id,name`.
- Fix `weknora api --jq` silently ignored: api.go now routes through
WriteJSONFiltered with jopts.JQ.
- AGENTS.md: drop the false claim that `auth logout` honors `-y`
(logout is local-only with no ConfirmDestructive guard); list the
actual destructive commands instead.
- Rewrite cli/acceptance/e2e/e2e_test.go for the bare-data wire shape
(was still parsing `out["data"]` / `env["ok"]`).
- Add `JSONOptions.Emit(w, v)` helper; collapse ~33 repeated
`format.WriteJSONFiltered(iostreams.IO.Out, X, jopts.Fields,
jopts.JQ)` sites to `jopts.Emit(iostreams.IO.Out, X)` — drops the
format import from 22 cmd/* files.
- Delete single-caller `cmdutil.MustRequireFlag`; inline as
`_ = cmd.MarkFlagRequired(...)` everywhere.
- Add `_ = cmd.MarkFlagRequired("name")` to `kb create`; it was the
only write command relying on runtime --name validation while
`context add` already used the cobra-level mark.
- `context use`: register `--json` / `--jq` (was always emitting JSON
unconditionally with no human path and no flag — diverged from
every other write command); human mode now prints
`✓ Switched context to X (was Y)`.
- Replace per-package `confirmPrompter` / `scriptedConfirm` /
`errPrompter` test doubles with `testutil.ConfirmPrompter`.
- Rename `chatService` → `ChatService` (export to match siblings
`ListService` / `ViewService`); rename `printUploadSuccess` →
`renderUploadSuccess` (siblings use `render*`).
- `defaultHint(CodeResourceNotFound)`: drop the hardcoded
"list available with `weknora kb list`" — misleading on agent /
doc / session 404. Replaced with "verify the resource ID and try
again".
- Strip stale `v0.2/v0.3` / "envelope" / "v0.0/v0.1 supports only"
historical tags from production comments and a few test
descriptions.
2026-05-14 17:51:11 +00:00
|
|
|
return 0
|
2026-05-06 06:22:36 +00:00
|
|
|
}
|
|
|
|
|
|
2026-05-08 08:42:17 +00:00
|
|
|
// MapCobraError tags the textually-emitted cobra errors as cmdutil.FlagError
|
2026-05-06 06:22:36 +00:00
|
|
|
// so they exit 2 like other user invocation mistakes. SetFlagErrorFunc handles
|
|
|
|
|
// flag parse errors at parse time; this catches positional/Args validation
|
|
|
|
|
// errors and unknown subcommands that propagate as plain errors.
|
|
|
|
|
//
|
|
|
|
|
// Pinned to cobra v1.10 message formats (cobra/args.go: ExactArgs / NoArgs;
|
|
|
|
|
// cobra/command.go: required-flag / unknown-command). TestMapCobraError_PinnedPrefixes
|
|
|
|
|
// guards against a silent break on cobra bumps.
|
2026-05-08 08:42:17 +00:00
|
|
|
//
|
refactor(cli): delete envelope infrastructure, errors to stderr
Removes the entire envelope machinery now that every success path
emits bare JSON:
- cli/internal/format/envelope.go (Envelope, Success, Failure,
SuccessWithRisk, WriteEnvelope, Meta, Notice, UpdateNotice,
VersionSkewNotice, Risk, RiskLevel, ErrorBody) + tests.
- cli/internal/format/filter.go envelope-specific helpers
(WriteEnvelopeFiltered, marshalEnvelope, applyFieldFilter,
filterDataPayload, filterObjectData); the reusable
filterArrayItems / filterObjectKeys / writeJQ stay for bare.go.
- cli/internal/cmdutil/exporter.go + tests (envelope-only).
- cli/internal/cmdutil/PrintErrorEnvelope + ToErrorBody +
operationRiskOf + Error.OperationRisk field + OperationRisk struct.
Error path: all errors now go to stderr via cmdutil.PrintError in
`code: message\nhint: ...` form, regardless of --json. Stdout stays
empty (or holds the partial-success the command already wrote) so
downstream `--json | jq` pipelines never have to filter error shapes
out of the success stream. Typed exit codes (3 auth.* / 4
resource.not_found / 5 input.* / 6 server.rate_limited / 7 server.*
+ network.* / 10 input.confirmation_required) carry the failure
class for agents that branch on it.
Acceptance contract:
- envelope_test.go → wire_test.go (TestEnvelopeGolden → TestWireGolden).
- testdata/envelopes/ → testdata/wire/.
- Error-path cases assert the typed code substring on stderr.
- Orphan whoami.*.json goldens deleted.
AGENTS.md + README.md rewritten for the bare-data contract:
- Drop envelope schema section + dry-run rule.
- Document bare JSON on stdout + `code: msg\nhint: …` on stderr.
- ADR-3 reframed around bare data and why error separation matters
for `--json | jq` pipelines.
WriteJSONFiltered short-circuits to WriteJSON when both filters are
empty (skip the marshal-buffer round-trip for the common case).
Final review pass:
- Fix wire-contract bug: `--json id,name` (space form) is broken by
pflag's NoOptDefVal; AGENTS.md / README.md / SetAgentHelp + the
field-discovery help text all switched to `--json=id,name`.
- Fix `weknora api --jq` silently ignored: api.go now routes through
WriteJSONFiltered with jopts.JQ.
- AGENTS.md: drop the false claim that `auth logout` honors `-y`
(logout is local-only with no ConfirmDestructive guard); list the
actual destructive commands instead.
- Rewrite cli/acceptance/e2e/e2e_test.go for the bare-data wire shape
(was still parsing `out["data"]` / `env["ok"]`).
- Add `JSONOptions.Emit(w, v)` helper; collapse ~33 repeated
`format.WriteJSONFiltered(iostreams.IO.Out, X, jopts.Fields,
jopts.JQ)` sites to `jopts.Emit(iostreams.IO.Out, X)` — drops the
format import from 22 cmd/* files.
- Delete single-caller `cmdutil.MustRequireFlag`; inline as
`_ = cmd.MarkFlagRequired(...)` everywhere.
- Add `_ = cmd.MarkFlagRequired("name")` to `kb create`; it was the
only write command relying on runtime --name validation while
`context add` already used the cobra-level mark.
- `context use`: register `--json` / `--jq` (was always emitting JSON
unconditionally with no human path and no flag — diverged from
every other write command); human mode now prints
`✓ Switched context to X (was Y)`.
- Replace per-package `confirmPrompter` / `scriptedConfirm` /
`errPrompter` test doubles with `testutil.ConfirmPrompter`.
- Rename `chatService` → `ChatService` (export to match siblings
`ListService` / `ViewService`); rename `printUploadSuccess` →
`renderUploadSuccess` (siblings use `render*`).
- `defaultHint(CodeResourceNotFound)`: drop the hardcoded
"list available with `weknora kb list`" — misleading on agent /
doc / session 404. Replaced with "verify the resource ID and try
again".
- Strip stale `v0.2/v0.3` / "envelope" / "v0.0/v0.1 supports only"
historical tags from production comments and a few test
descriptions.
2026-05-14 17:51:11 +00:00
|
|
|
// Exported so the acceptance/contract test helper can reuse the mapping
|
|
|
|
|
// when replicating Execute()'s stderr error-path in-process.
|
2026-05-08 08:42:17 +00:00
|
|
|
func MapCobraError(err error) error {
|
2026-05-06 06:22:36 +00:00
|
|
|
if err == nil {
|
|
|
|
|
return nil
|
|
|
|
|
}
|
|
|
|
|
msg := err.Error()
|
|
|
|
|
for _, prefix := range cobraFlagErrorPrefixes {
|
|
|
|
|
if strings.HasPrefix(msg, prefix) {
|
|
|
|
|
return cmdutil.NewFlagError(err)
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
return err
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// cobraFlagErrorPrefixes lists the text prefixes cobra uses for invocation
|
|
|
|
|
// problems we want to surface as exit 2. Pinned per cobra v1.10.
|
|
|
|
|
var cobraFlagErrorPrefixes = []string{
|
|
|
|
|
"unknown command ",
|
|
|
|
|
"required flag(s)",
|
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
|
|
|
"accepts ", // ExactArgs / RangeArgs / etc. - `accepts N arg(s), received M`
|
2026-05-06 06:22:36 +00:00
|
|
|
"requires at least", // MinimumNArgs
|
|
|
|
|
"requires at most", // MaximumNArgs
|
|
|
|
|
"unknown flag",
|
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
|
|
|
"invalid argument \"", // pflag type-coercion: `invalid argument "foo" for "--flag" flag`
|
2026-05-06 06:22:36 +00:00
|
|
|
}
|
|
|
|
|
|
2026-05-08 08:13:58 +00:00
|
|
|
// NewRootCmd builds the cobra tree. Splitting it from Execute() lets tests
|
2026-05-10 18:44:41 +00:00
|
|
|
// drive the tree directly with their own factory. Exported so the
|
2026-05-08 08:13:58 +00:00
|
|
|
// acceptance/contract suite can construct the tree in-process.
|
|
|
|
|
func NewRootCmd(f *cmdutil.Factory) *cobra.Command {
|
2026-05-06 06:22:36 +00:00
|
|
|
v, commit, date := build.Info()
|
|
|
|
|
cmd := &cobra.Command{
|
2026-05-08 08:42:17 +00:00
|
|
|
Use: "weknora",
|
docs(cli): README / AGENTS.md / CHANGELOG + CI parity test
Wire-contract documentation and the CI check that keeps it honest.
* cli/README.md gains a verbatim --help block (top-level + subtrees),
an Exit codes table covering 0/1/2/3/4/5/6/7/10/124/130, a "Status
vs check" verb-pair subtable, and a "doc wait" paragraph spelling out
the four exit codes (0 / 1 / 124 / 130). The api passthrough note
trims storage provider out of the deep-config list now that
kb create --storage-provider is a polished flag.
* cli/AGENTS.md becomes the contributor guide: build/test, CRUD flag
conventions, the status/check verb pattern, long-poll wait commands,
the SetAgentHelp pattern, and a full Error code reference with 35
typed codes mapped to namespaces, exit codes, retryable / hint
guidance. Reference section is bracketed by HTML markers so a CI
parity test can keep it in sync with AllCodes().
* cli/internal/cmdutil/errors_doc_test.go enforces parity: every code
in AllCodes() must appear in AGENTS.md inside the markers, and
AGENTS.md must not reference codes that no longer exist. Fails CI
if a new typed code is added without documentation.
* CHANGELOG.md gets the v0.6 entry: BREAKING (--json / --no-stream /
WEKNORA_SDK_DEBUG / kb create --name), Added (--format / --jq /
doc wait / --log-level / kb-and-agent status & check / multi-id
delete / api --paginate / MCP schema extension / SetAgentHelp /
signal-aware ctx / kb create --storage-provider / new operation.*
namespace), Changed (multi-id partial-failure exit code, doc upload
FlagError, --log-level FlagError, multi-id stdout cleanup, README /
AGENTS.md changes), with a Migration from v0.5 section walking
every BREAKING through its v0.6 replacement.
2026-05-17 17:38:42 +00:00
|
|
|
Short: "WeKnora CLI",
|
|
|
|
|
Long: `Command-line client for the WeKnora RAG server. Manage knowledge bases
|
|
|
|
|
and documents, run hybrid search, chat with grounded answers, or expose
|
|
|
|
|
a curated read-only MCP tool surface for AI agents.`,
|
2026-05-29 12:06:53 +00:00
|
|
|
Example: ` weknora profile add prod --host=https://kb.example.com --use
|
|
|
|
|
weknora auth login
|
docs(cli): README / AGENTS.md / CHANGELOG + CI parity test
Wire-contract documentation and the CI check that keeps it honest.
* cli/README.md gains a verbatim --help block (top-level + subtrees),
an Exit codes table covering 0/1/2/3/4/5/6/7/10/124/130, a "Status
vs check" verb-pair subtable, and a "doc wait" paragraph spelling out
the four exit codes (0 / 1 / 124 / 130). The api passthrough note
trims storage provider out of the deep-config list now that
kb create --storage-provider is a polished flag.
* cli/AGENTS.md becomes the contributor guide: build/test, CRUD flag
conventions, the status/check verb pattern, long-poll wait commands,
the SetAgentHelp pattern, and a full Error code reference with 35
typed codes mapped to namespaces, exit codes, retryable / hint
guidance. Reference section is bracketed by HTML markers so a CI
parity test can keep it in sync with AllCodes().
* cli/internal/cmdutil/errors_doc_test.go enforces parity: every code
in AllCodes() must appear in AGENTS.md inside the markers, and
AGENTS.md must not reference codes that no longer exist. Fails CI
if a new typed code is added without documentation.
* CHANGELOG.md gets the v0.6 entry: BREAKING (--json / --no-stream /
WEKNORA_SDK_DEBUG / kb create --name), Added (--format / --jq /
doc wait / --log-level / kb-and-agent status & check / multi-id
delete / api --paginate / MCP schema extension / SetAgentHelp /
signal-aware ctx / kb create --storage-provider / new operation.*
namespace), Changed (multi-id partial-failure exit code, doc upload
FlagError, --log-level FlagError, multi-id stdout cleanup, README /
AGENTS.md changes), with a Migration from v0.5 section walking
every BREAKING through its v0.6 replacement.
2026-05-17 17:38:42 +00:00
|
|
|
weknora kb list
|
|
|
|
|
weknora chat "summarise the design doc"
|
|
|
|
|
weknora doctor --format json`,
|
2026-05-06 06:22:36 +00:00
|
|
|
SilenceUsage: true,
|
|
|
|
|
SilenceErrors: true,
|
|
|
|
|
// Version makes cobra auto-register a `--version` global flag that
|
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
|
|
|
// prints this string. We accept both `--version` and a `version`
|
2026-05-17 17:38:16 +00:00
|
|
|
// subcommand; the subcommand still owns the richer `--format json` output
|
refactor(cli): delete envelope infrastructure, errors to stderr
Removes the entire envelope machinery now that every success path
emits bare JSON:
- cli/internal/format/envelope.go (Envelope, Success, Failure,
SuccessWithRisk, WriteEnvelope, Meta, Notice, UpdateNotice,
VersionSkewNotice, Risk, RiskLevel, ErrorBody) + tests.
- cli/internal/format/filter.go envelope-specific helpers
(WriteEnvelopeFiltered, marshalEnvelope, applyFieldFilter,
filterDataPayload, filterObjectData); the reusable
filterArrayItems / filterObjectKeys / writeJQ stay for bare.go.
- cli/internal/cmdutil/exporter.go + tests (envelope-only).
- cli/internal/cmdutil/PrintErrorEnvelope + ToErrorBody +
operationRiskOf + Error.OperationRisk field + OperationRisk struct.
Error path: all errors now go to stderr via cmdutil.PrintError in
`code: message\nhint: ...` form, regardless of --json. Stdout stays
empty (or holds the partial-success the command already wrote) so
downstream `--json | jq` pipelines never have to filter error shapes
out of the success stream. Typed exit codes (3 auth.* / 4
resource.not_found / 5 input.* / 6 server.rate_limited / 7 server.*
+ network.* / 10 input.confirmation_required) carry the failure
class for agents that branch on it.
Acceptance contract:
- envelope_test.go → wire_test.go (TestEnvelopeGolden → TestWireGolden).
- testdata/envelopes/ → testdata/wire/.
- Error-path cases assert the typed code substring on stderr.
- Orphan whoami.*.json goldens deleted.
AGENTS.md + README.md rewritten for the bare-data contract:
- Drop envelope schema section + dry-run rule.
- Document bare JSON on stdout + `code: msg\nhint: …` on stderr.
- ADR-3 reframed around bare data and why error separation matters
for `--json | jq` pipelines.
WriteJSONFiltered short-circuits to WriteJSON when both filters are
empty (skip the marshal-buffer round-trip for the common case).
Final review pass:
- Fix wire-contract bug: `--json id,name` (space form) is broken by
pflag's NoOptDefVal; AGENTS.md / README.md / SetAgentHelp + the
field-discovery help text all switched to `--json=id,name`.
- Fix `weknora api --jq` silently ignored: api.go now routes through
WriteJSONFiltered with jopts.JQ.
- AGENTS.md: drop the false claim that `auth logout` honors `-y`
(logout is local-only with no ConfirmDestructive guard); list the
actual destructive commands instead.
- Rewrite cli/acceptance/e2e/e2e_test.go for the bare-data wire shape
(was still parsing `out["data"]` / `env["ok"]`).
- Add `JSONOptions.Emit(w, v)` helper; collapse ~33 repeated
`format.WriteJSONFiltered(iostreams.IO.Out, X, jopts.Fields,
jopts.JQ)` sites to `jopts.Emit(iostreams.IO.Out, X)` — drops the
format import from 22 cmd/* files.
- Delete single-caller `cmdutil.MustRequireFlag`; inline as
`_ = cmd.MarkFlagRequired(...)` everywhere.
- Add `_ = cmd.MarkFlagRequired("name")` to `kb create`; it was the
only write command relying on runtime --name validation while
`context add` already used the cobra-level mark.
- `context use`: register `--json` / `--jq` (was always emitting JSON
unconditionally with no human path and no flag — diverged from
every other write command); human mode now prints
`✓ Switched context to X (was Y)`.
- Replace per-package `confirmPrompter` / `scriptedConfirm` /
`errPrompter` test doubles with `testutil.ConfirmPrompter`.
- Rename `chatService` → `ChatService` (export to match siblings
`ListService` / `ViewService`); rename `printUploadSuccess` →
`renderUploadSuccess` (siblings use `render*`).
- `defaultHint(CodeResourceNotFound)`: drop the hardcoded
"list available with `weknora kb list`" — misleading on agent /
doc / session 404. Replaced with "verify the resource ID and try
again".
- Strip stale `v0.2/v0.3` / "envelope" / "v0.0/v0.1 supports only"
historical tags from production comments and a few test
descriptions.
2026-05-14 17:51:11 +00:00
|
|
|
// (build commit + date).
|
2026-05-06 06:22:36 +00:00
|
|
|
Version: fmt.Sprintf("%s (commit %s, built %s)", v, commit, date),
|
2026-05-17 17:38:16 +00:00
|
|
|
PersistentPreRunE: func(c *cobra.Command, args []string) error {
|
2026-06-26 12:40:59 +00:00
|
|
|
// Input hygiene: reject control / ANSI-escape / Bidi / zero-width
|
|
|
|
|
// characters in positional args and supplied flag values before any
|
|
|
|
|
// work. CLI inputs are untrusted (agent- or content-sourced), and a
|
|
|
|
|
// smuggled escape stored in a resource name would fire in a human's
|
|
|
|
|
// terminal on a later list/view. Returns input.invalid_argument (exit 5).
|
|
|
|
|
if err := cmdutil.CheckSafeArgs(args, c.Flags()); err != nil {
|
|
|
|
|
return err
|
|
|
|
|
}
|
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
|
|
|
// Propagate the global --profile flag (or WEKNORA_PROFILE env) into
|
|
|
|
|
// the Factory for this invocation only - single-shot override, no disk write.
|
|
|
|
|
// Flag takes precedence over env; env takes precedence over config file.
|
|
|
|
|
if v, _ := c.Flags().GetString("profile"); v != "" {
|
|
|
|
|
f.ProfileOverride = v
|
|
|
|
|
} else if v := os.Getenv("WEKNORA_PROFILE"); v != "" {
|
|
|
|
|
f.ProfileOverride = v
|
2026-05-08 08:42:17 +00:00
|
|
|
}
|
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
|
|
|
// Pin --format mode for cmdutil.PrintError envelope vs prose decision.
|
|
|
|
|
// Safe on commands that don't register --format: CheckFormatFlag returns
|
|
|
|
|
// {Mode:""}, ResolveDefault falls back to TTY detection.
|
|
|
|
|
if fopts, err := cmdutil.CheckFormatFlag(c); err == nil && fopts != nil {
|
|
|
|
|
fopts.FromEnv()
|
|
|
|
|
fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
|
|
|
|
|
cmdutil.SetFormatMode(string(fopts.Mode))
|
|
|
|
|
}
|
|
|
|
|
// Record the resolved profile for envelope.profile and NDJSON init.profile.
|
|
|
|
|
cmdutil.SetProfile(f.ActiveProfile())
|
2026-05-17 17:38:16 +00:00
|
|
|
// Resolve --log-level / WEKNORA_LOG_LEVEL and apply to the SDK
|
|
|
|
|
// debug logger before any SDK call is made. Returns a typed error
|
|
|
|
|
// when --log-level was passed explicitly with an invalid value
|
|
|
|
|
// (matches --format validation strictness).
|
|
|
|
|
return f.ApplyLogLevel(c, iostreams.IO.Err)
|
2026-05-06 06:22:36 +00:00
|
|
|
},
|
|
|
|
|
}
|
|
|
|
|
// Match `weknora version` line format so both forms output the same.
|
|
|
|
|
cmd.SetVersionTemplate("weknora {{.Version}}\n")
|
|
|
|
|
addGlobalFlags(cmd)
|
|
|
|
|
// Wrap cobra's flag-parsing errors as FlagError so cmdutil.ExitCode maps
|
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
|
|
|
// them to exit 2. "unknown command" errors are detected by message prefix
|
|
|
|
|
// in Execute() since cobra emits them as plain errors.
|
2026-05-06 06:22:36 +00:00
|
|
|
cmd.SetFlagErrorFunc(func(c *cobra.Command, err error) error {
|
|
|
|
|
return cmdutil.NewFlagError(err)
|
|
|
|
|
})
|
|
|
|
|
|
|
|
|
|
cmd.AddCommand(newVersionCmd(f))
|
2026-05-06 06:23:45 +00:00
|
|
|
cmd.AddCommand(auth.NewCmdAuth(f))
|
2026-05-06 06:24:11 +00:00
|
|
|
cmd.AddCommand(search.NewCmdSearch(f))
|
2026-05-08 08:13:58 +00:00
|
|
|
cmd.AddCommand(doctor.NewCmd(f))
|
|
|
|
|
cmd.AddCommand(kb.NewCmd(f))
|
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
|
|
|
cmd.AddCommand(profilecmd.NewCmd(f))
|
2026-06-26 12:40:59 +00:00
|
|
|
cmd.AddCommand(configcmd.NewCmd(f))
|
2026-05-10 18:43:55 +00:00
|
|
|
cmd.AddCommand(linkcmd.NewCmd(f))
|
feat(cli): doc view + unlink (fill v0.3 design-gap audit)
Final design-pass audit on the v0.3 surface flagged two real gaps.
(A) doc view <id> was missing. Every other resource subtree exposes
a view verb (kb view, session view) for inspecting a single record,
but doc — which has the richest metadata of the three (title, file
name, type, size, parse_status, embedding_model, processed_at,
error_message) — had no single-doc surface. Users wanting one
doc's metadata had to `doc list | grep`.
Implementation mirrors kb view: narrow ViewService(GetKnowledge)
interface, --json envelope path, human KEY: VALUE renderer. Optional
fields are omitted rather than rendered as "-" so the panel is
dense. Tested: human renderer, title fallback when FileName empty,
omit-empty contract, JSON envelope shape, 404 classification.
(B) link had no counterpart. Once .weknora/project.yaml is written,
the only way to clear it was `rm` by hand. Both vercel and netlify
ship `unlink` as a top-level verb; not having one was a
discoverability gap. Top-level rather than `link --clear` follows
the verb-noun convention of the rest of the surface — the verb
stands alone and the operation isn't parameterised.
unlink walks up from cwd via projectlink.Discover (the same
parent-chain logic Factory.ResolveKB uses on the read side), so a
user in a subdirectory of a linked project can unlink without
cd-ing up. Errors with input.invalid_argument when no link is
found anywhere in the chain. Idempotent under racy concurrent
removal: os.ErrNotExist on os.Remove falls through to a Success
envelope since the post-condition holds either way.
projectlink package gained Remove() alongside Save / Load /
Discover so unlink doesn't reimplement the idempotent-remove
pattern inline.
Top-level registration in cmd/root.go, alongside link.
cli/AGENTS.md verb canon line adds unlink to the locally-introduced
list. cli/CHANGELOG.md gains an Added entry for each.
5 unit tests for view + 4 for unlink (cwd / walk-up / no-link
error / JSON envelope). Full suite green.
Intentionally deferred:
- session edit (rename a session): sessions auto-name from the
first prompt; polish rather than a gap.
- link --clear as an alternative to unlink: top-level unlink is
the documented form; aliases would just multiply the surface.
2026-05-13 08:40:43 +00:00
|
|
|
cmd.AddCommand(linkcmd.NewCmdUnlink())
|
2026-05-10 18:44:06 +00:00
|
|
|
cmd.AddCommand(doc.NewCmd(f))
|
2026-05-10 18:44:13 +00:00
|
|
|
cmd.AddCommand(apicmd.NewCmd(f))
|
|
|
|
|
cmd.AddCommand(chatcmd.NewCmd(f))
|
2026-05-12 15:34:33 +00:00
|
|
|
cmd.AddCommand(sessioncmd.NewCmd(f))
|
2026-06-26 12:40:59 +00:00
|
|
|
cmd.AddCommand(messagecmd.NewCmd(f))
|
2026-05-14 15:28:14 +00:00
|
|
|
cmd.AddCommand(agentcmd.NewCmd(f))
|
2026-06-26 12:40:59 +00:00
|
|
|
cmd.AddCommand(modelcmd.NewCmd(f))
|
2026-05-15 17:22:14 +00:00
|
|
|
cmd.AddCommand(chunkcmd.NewCmdChunk(f))
|
2026-05-14 15:28:14 +00:00
|
|
|
cmd.AddCommand(mcpcmd.NewCmd(f))
|
2026-06-26 12:40:59 +00:00
|
|
|
cmd.AddCommand(skillscmd.NewCmd(f))
|
|
|
|
|
cmd.AddCommand(newCmdExitCodes())
|
|
|
|
|
cmd.AddCommand(newCmdSchema())
|
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
|
|
|
installUnknownSubcommandGuard(cmd)
|
2026-05-06 06:22:36 +00:00
|
|
|
return cmd
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// addGlobalFlags registers persistent flags available on every subcommand.
|
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
|
|
|
// Only flags whose behavior is actually wired are listed - a flag that
|
2026-05-08 08:42:17 +00:00
|
|
|
// accepts values but does nothing is a worse contract than no flag.
|
2026-05-06 06:22:36 +00:00
|
|
|
func addGlobalFlags(cmd *cobra.Command) {
|
|
|
|
|
pf := cmd.PersistentFlags()
|
|
|
|
|
pf.BoolP("yes", "y", false, "Skip confirmation prompts on destructive operations")
|
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
|
|
|
pf.String("profile", "", "Override the active profile for this invocation (no disk write)")
|
2026-05-17 17:38:16 +00:00
|
|
|
// --log-level is registered as a persistent (global) flag because the SDK
|
|
|
|
|
// debug logger is initialised once at factory time before any command runs,
|
|
|
|
|
// so the flag must be visible on all subcommands. Unlike --format (which
|
|
|
|
|
// only some commands honour and is registered per-command, Method D),
|
|
|
|
|
// --log-level applies uniformly to all SDK calls.
|
|
|
|
|
cmdutil.AddLogLevelFlag(cmd)
|
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
|
|
|
// --format and --jq are persistent globals so unknown-subcommand paths
|
|
|
|
|
// (e.g. `weknora fooo --format json`) reach the typed-envelope guard
|
|
|
|
|
// instead of being rejected as "unknown flag" exit 2 by cobra. Commands
|
|
|
|
|
// that don't produce JSON output (e.g. `completion bash`) ignore the flag
|
|
|
|
|
// rather than error — the unified agent contract is worth the trade.
|
feat(cli)!: v0.10 reliability, agent-UX, and command-surface hardening
A hardening + finalization pass over the agent-first CLI: correctness fixes,
richer machine-readable signals, flag/naming consistency, and a symmetric
config surface. Pre-1.0, so it includes breaking renames.
Correctness:
- agent update: resolve/validate --model/--rerank-model (was storing a bogus
name verbatim, corrupting config.model_id).
- doctor: honor WEKNORA_HOST / WEKNORA_API_KEY (headless path no longer reports
"no host configured").
- session ask / MCP session_ask: text answer was empty on non-TTY — the agent
stream sets Done=true on an intermediate agent_query frame before the answer,
and AgentAccumulator treated the first Done as terminal. Terminate on the
`complete` event (new sdk.AgentResponseTypeComplete), not a per-frame Done.
- batch exit codes: any per-item failure collapses to operation.failed (exit 1),
including `doc upload --recursive` partial failures — a permanent per-file
failure (e.g. a duplicate) no longer surfaces as a retryable exit 7 an agent
would loop on; per-item typed errors stay in the envelope.
Agent-first signals & discovery:
- error.exit_code in the envelope (type + exit_code disambiguate the
input.invalid_argument exit-2-vs-5 split in one JSON read).
- meta.hint on empty content search and on draft doc create; doc wait fails fast
on a never-parsing draft instead of hanging to --timeout.
- retrieval-readiness is visible in the natural flow: kb status / kb check emit
retrieval_ready, and kb create hints the fix when no embedding model is bound
— an unconfigured KB no longer looks silently healthy.
- schema contract completeness: every leaf declares output + >=1 example
(drift-guarded); output strings match the meta actually emitted; chunk list
and search docs now emit meta.total_count (both previously dropped it).
- schema tolerates a quoted multi-word command label; zero-state auth — and
`link` with no profile — point at profile setup / the headless WEKNORA_KB_ID
path instead of looping on `auth login`.
- id-addressed reads tolerate a redundant --kb (doc view/wait, chunk list/view
accept and ignore it, declared in schema) so a carried-over --kb doesn't
exit 2; streaming commands warn that --jq does not apply to an NDJSON stream.
- keep JSON-always as the default; --jq hints spell out the .data path.
Consistency & gating:
- doc create: drop the deprecated --name alias (--title only; pre-1.0 break).
- chunk list --limit aligned to 1..10000; model list --limit/-L with
has_more/total_count; api write-gates -X PUT/PATCH (exit 10); skills install
expands a leading ~.
- docs corrected: search docs / doc list --keyword help is case-insensitive
(server does LOWER LIKE); AGENTS.md risk-action list (no phantom kb.init; add
model.update / kb.config.set) and batch example (failed item carries `error`);
session resume --message id comes from `message list`, not the stream.
- auth/profile ergonomics: env credentials are now first-class — `auth token`
prints the active WEKNORA_API_KEY / WEKNORA_TOKEN, and auth login/logout/refresh
give an env-aware message instead of looping on "run auth login". `auth logout`
clears credentials but keeps the profile registered (host preserved for
re-login); deleting a profile is `profile remove`'s job (clean logout/remove
separation, matching gh / lark).
Config surface (symmetric read/write, in-place model edits):
- kb config now returns a secret-free KBModelConfigView (was {}); `kb config`
reads, new `kb config set` writes; `kb init` removed (misnomer).
- kb create --chat-model: retrieval-ready in one step.
- model update: edit a model in place (id preserved, references survive) —
rotate --api-key-stdin, change base-url / display-name / etc.
- session continue-stream renamed to session resume.
Docs: AGENTS.md is the single wire-contract source; CHANGELOG slimmed; stale
kb-init / continue-stream references removed; skill wire-vocab guard extended.
AGENTS.md / weknora-shared SKILL document retrieval_ready (a KB needs an
embedding model to be searchable), that --jq does not apply to NDJSON
streams, and the env-credential-first auth path; the KB quickstart example
now creates a retrieval-ready KB.
2026-07-02 07:53:51 +00:00
|
|
|
pf.String("format", "", "Output format: text | json | ndjson (default: json; env: WEKNORA_FORMAT)")
|
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
|
|
|
pf.StringP("jq", "q", "", "Filter JSON output using a jq `expression` (requires --format json|ndjson)")
|
2026-05-06 06:22:36 +00:00
|
|
|
}
|
|
|
|
|
|
2026-05-17 17:38:16 +00:00
|
|
|
// versionFields enumerates the fields surfaced for `--format json` discovery on
|
refactor(cli): delete envelope infrastructure, errors to stderr
Removes the entire envelope machinery now that every success path
emits bare JSON:
- cli/internal/format/envelope.go (Envelope, Success, Failure,
SuccessWithRisk, WriteEnvelope, Meta, Notice, UpdateNotice,
VersionSkewNotice, Risk, RiskLevel, ErrorBody) + tests.
- cli/internal/format/filter.go envelope-specific helpers
(WriteEnvelopeFiltered, marshalEnvelope, applyFieldFilter,
filterDataPayload, filterObjectData); the reusable
filterArrayItems / filterObjectKeys / writeJQ stay for bare.go.
- cli/internal/cmdutil/exporter.go + tests (envelope-only).
- cli/internal/cmdutil/PrintErrorEnvelope + ToErrorBody +
operationRiskOf + Error.OperationRisk field + OperationRisk struct.
Error path: all errors now go to stderr via cmdutil.PrintError in
`code: message\nhint: ...` form, regardless of --json. Stdout stays
empty (or holds the partial-success the command already wrote) so
downstream `--json | jq` pipelines never have to filter error shapes
out of the success stream. Typed exit codes (3 auth.* / 4
resource.not_found / 5 input.* / 6 server.rate_limited / 7 server.*
+ network.* / 10 input.confirmation_required) carry the failure
class for agents that branch on it.
Acceptance contract:
- envelope_test.go → wire_test.go (TestEnvelopeGolden → TestWireGolden).
- testdata/envelopes/ → testdata/wire/.
- Error-path cases assert the typed code substring on stderr.
- Orphan whoami.*.json goldens deleted.
AGENTS.md + README.md rewritten for the bare-data contract:
- Drop envelope schema section + dry-run rule.
- Document bare JSON on stdout + `code: msg\nhint: …` on stderr.
- ADR-3 reframed around bare data and why error separation matters
for `--json | jq` pipelines.
WriteJSONFiltered short-circuits to WriteJSON when both filters are
empty (skip the marshal-buffer round-trip for the common case).
Final review pass:
- Fix wire-contract bug: `--json id,name` (space form) is broken by
pflag's NoOptDefVal; AGENTS.md / README.md / SetAgentHelp + the
field-discovery help text all switched to `--json=id,name`.
- Fix `weknora api --jq` silently ignored: api.go now routes through
WriteJSONFiltered with jopts.JQ.
- AGENTS.md: drop the false claim that `auth logout` honors `-y`
(logout is local-only with no ConfirmDestructive guard); list the
actual destructive commands instead.
- Rewrite cli/acceptance/e2e/e2e_test.go for the bare-data wire shape
(was still parsing `out["data"]` / `env["ok"]`).
- Add `JSONOptions.Emit(w, v)` helper; collapse ~33 repeated
`format.WriteJSONFiltered(iostreams.IO.Out, X, jopts.Fields,
jopts.JQ)` sites to `jopts.Emit(iostreams.IO.Out, X)` — drops the
format import from 22 cmd/* files.
- Delete single-caller `cmdutil.MustRequireFlag`; inline as
`_ = cmd.MarkFlagRequired(...)` everywhere.
- Add `_ = cmd.MarkFlagRequired("name")` to `kb create`; it was the
only write command relying on runtime --name validation while
`context add` already used the cobra-level mark.
- `context use`: register `--json` / `--jq` (was always emitting JSON
unconditionally with no human path and no flag — diverged from
every other write command); human mode now prints
`✓ Switched context to X (was Y)`.
- Replace per-package `confirmPrompter` / `scriptedConfirm` /
`errPrompter` test doubles with `testutil.ConfirmPrompter`.
- Rename `chatService` → `ChatService` (export to match siblings
`ListService` / `ViewService`); rename `printUploadSuccess` →
`renderUploadSuccess` (siblings use `render*`).
- `defaultHint(CodeResourceNotFound)`: drop the hardcoded
"list available with `weknora kb list`" — misleading on agent /
doc / session 404. Replaced with "verify the resource ID and try
again".
- Strip stale `v0.2/v0.3` / "envelope" / "v0.0/v0.1 supports only"
historical tags from production comments and a few test
descriptions.
2026-05-14 17:51:11 +00:00
|
|
|
// `version`. Mirrors the version object payload.
|
feat(cli): --json field-select, --jq, auth token, doc --from-url
Output ergonomics:
- `--json` accepts a comma-separated field list (gh-parity); selects
named keys from the per-command payload. Bare `--json` keeps the
full shape.
- `--jq <expr>` evaluates a gojq expression over the JSON; pairs with
`--json field-list` so projection runs before jq.
- `--version` is a global cobra flag in addition to the `version`
subcommand; both render the same line.
- Per-command `--help` now renders the available JSON field list under
"JSON fields available via `--json id,name,...`" (field-discovery
parity with gh / kubectl `-o jsonpath`).
New commands:
- `auth token` — print the active context's credential to stdout for
shell command substitution (`WEKNORA_TOKEN=$(weknora auth token)`).
Default: raw secret, no trailing newline. `--json` emits
`{token, mode, context}`.
- `doc upload --from-url <URL>` — ingest a remote URL via the SDK
`CreateKnowledgeFromURL`. `--name` forwarded as `FileName` so the
server's known-extension heuristic upgrades crawl-mode to
file-download-mode where appropriate.
Includes the simplify post-review polish pass (field-filter unit
tests, --json/--jq compose check, agent_help copy fixes).
2026-05-14 15:28:14 +00:00
|
|
|
var versionFields = []string{"version", "commit", "date"}
|
|
|
|
|
|
2026-05-06 06:22:36 +00:00
|
|
|
// newVersionCmd is the only leaf command shipped in the foundation PR. It
|
|
|
|
|
// doubles as the smoke test that proves Factory + iostreams + cobra wiring works.
|
|
|
|
|
func newVersionCmd(f *cmdutil.Factory) *cobra.Command {
|
|
|
|
|
cmd := &cobra.Command{
|
|
|
|
|
Use: "version",
|
|
|
|
|
Short: "Show CLI build metadata",
|
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
|
|
|
Args: cobra.NoArgs,
|
2026-05-06 06:22:36 +00:00
|
|
|
RunE: func(c *cobra.Command, args []string) error {
|
2026-05-17 17:38:16 +00:00
|
|
|
fopts, err := cmdutil.CheckFormatFlag(c)
|
feat(cli): --json field-select, --jq, auth token, doc --from-url
Output ergonomics:
- `--json` accepts a comma-separated field list (gh-parity); selects
named keys from the per-command payload. Bare `--json` keeps the
full shape.
- `--jq <expr>` evaluates a gojq expression over the JSON; pairs with
`--json field-list` so projection runs before jq.
- `--version` is a global cobra flag in addition to the `version`
subcommand; both render the same line.
- Per-command `--help` now renders the available JSON field list under
"JSON fields available via `--json id,name,...`" (field-discovery
parity with gh / kubectl `-o jsonpath`).
New commands:
- `auth token` — print the active context's credential to stdout for
shell command substitution (`WEKNORA_TOKEN=$(weknora auth token)`).
Default: raw secret, no trailing newline. `--json` emits
`{token, mode, context}`.
- `doc upload --from-url <URL>` — ingest a remote URL via the SDK
`CreateKnowledgeFromURL`. `--name` forwarded as `FileName` so the
server's known-extension heuristic upgrades crawl-mode to
file-download-mode where appropriate.
Includes the simplify post-review polish pass (field-filter unit
tests, --json/--jq compose check, agent_help copy fixes).
2026-05-14 15:28:14 +00:00
|
|
|
if err != nil {
|
|
|
|
|
return err
|
|
|
|
|
}
|
2026-05-17 17:38:16 +00:00
|
|
|
fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
|
2026-05-06 06:22:36 +00:00
|
|
|
v, commit, date := build.Info()
|
2026-05-17 17:38:16 +00:00
|
|
|
if fopts.WantsJSON() {
|
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
|
|
|
return fopts.Emit(c.OutOrStdout(), map[string]string{
|
|
|
|
|
"version": v,
|
|
|
|
|
"commit": commit,
|
|
|
|
|
"date": date,
|
|
|
|
|
}, nil)
|
2026-05-06 06:22:36 +00:00
|
|
|
}
|
|
|
|
|
fmt.Fprintf(c.OutOrStdout(), "weknora %s (commit %s, built %s)\n", v, commit, date)
|
|
|
|
|
return nil
|
|
|
|
|
},
|
|
|
|
|
}
|
2026-05-17 17:38:16 +00:00
|
|
|
cmdutil.AddFormatFlag(cmd, versionFields...)
|
2026-05-29 12:06:53 +00:00
|
|
|
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
|
|
|
|
UsedFor: "show CLI build metadata (version, commit, build date)",
|
|
|
|
|
Examples: []string{"weknora version --format json"},
|
|
|
|
|
Output: "envelope.data is {version, commit, date}",
|
|
|
|
|
})
|
2026-05-06 06:22:36 +00:00
|
|
|
return cmd
|
|
|
|
|
}
|
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
|
|
|
|
|
|
|
|
// installUnknownSubcommandGuard recursively attaches a RunE that emits a typed
|
|
|
|
|
// envelope error when a parent command is invoked with no matching subcommand
|
|
|
|
|
// (e.g. `weknora kb bogus`). Without this, cobra falls back to a free-form
|
|
|
|
|
// "unknown command" string error via legacyArgs validation.
|
|
|
|
|
//
|
|
|
|
|
// cobra's legacyArgs (args.go) fires at Find() time when Args == nil:
|
|
|
|
|
// for root commands it rejects any unrecognised positional before RunE runs.
|
|
|
|
|
// Setting cobra.ArbitraryArgs bypasses that check so our RunE receives the
|
|
|
|
|
// unknown arg and can emit the typed envelope instead.
|
|
|
|
|
func installUnknownSubcommandGuard(cmd *cobra.Command) {
|
|
|
|
|
if cmd.HasSubCommands() && cmd.Run == nil && cmd.RunE == nil {
|
|
|
|
|
cmd.RunE = unknownSubcommandRunE
|
|
|
|
|
cmd.Args = cobra.ArbitraryArgs
|
|
|
|
|
}
|
|
|
|
|
for _, c := range cmd.Commands() {
|
|
|
|
|
installUnknownSubcommandGuard(c)
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
func unknownSubcommandRunE(cmd *cobra.Command, args []string) error {
|
|
|
|
|
// Group command invoked with no subcommand (e.g. `weknora kb`):
|
|
|
|
|
// show help rather than emit a confusing `unknown ""` error.
|
|
|
|
|
if len(args) == 0 {
|
|
|
|
|
return cmd.Help()
|
|
|
|
|
}
|
|
|
|
|
unknown := args[0]
|
|
|
|
|
available := availableSubcommandNames(cmd)
|
2026-06-26 12:40:59 +00:00
|
|
|
// Lead with a "did you mean" when there's a plausible typo, so an agent
|
|
|
|
|
// gets a single actionable fix instead of scanning the whole list.
|
|
|
|
|
hint := fmt.Sprintf("available subcommands: %s", strings.Join(available, ", "))
|
|
|
|
|
suggestions := cmdutil.SuggestClosest(unknown, available)
|
|
|
|
|
if len(suggestions) > 0 {
|
|
|
|
|
hint = fmt.Sprintf("did you mean: %s? (available: %s)",
|
|
|
|
|
strings.Join(suggestions, ", "), strings.Join(available, ", "))
|
|
|
|
|
}
|
|
|
|
|
detail := map[string]any{
|
|
|
|
|
"unknown": unknown,
|
|
|
|
|
"command_path": cmd.CommandPath(),
|
|
|
|
|
"available": available,
|
|
|
|
|
}
|
|
|
|
|
if len(suggestions) > 0 {
|
|
|
|
|
detail["suggestions"] = suggestions
|
|
|
|
|
}
|
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
|
|
|
return cmdutil.NewError(
|
|
|
|
|
cmdutil.CodeInputUnknownSubcommand,
|
|
|
|
|
fmt.Sprintf("unknown subcommand %q for %q", unknown, cmd.CommandPath()),
|
|
|
|
|
).
|
2026-06-26 12:40:59 +00:00
|
|
|
WithHint(hint).
|
|
|
|
|
WithRetryArgv(append(strings.Fields(cmd.CommandPath()), "--help")).
|
|
|
|
|
WithDetail(detail)
|
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
|
|
|
}
|
|
|
|
|
|
|
|
|
|
func availableSubcommandNames(cmd *cobra.Command) []string {
|
|
|
|
|
var names []string
|
|
|
|
|
for _, c := range cmd.Commands() {
|
|
|
|
|
if c.Hidden || c.Name() == "help" || c.Name() == "completion" {
|
|
|
|
|
continue
|
|
|
|
|
}
|
|
|
|
|
names = append(names, c.Name())
|
|
|
|
|
}
|
|
|
|
|
sort.Strings(names)
|
|
|
|
|
return names
|
|
|
|
|
}
|