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).
This commit is contained in:
@@ -0,0 +1,109 @@
|
||||
package cmdutil
|
||||
|
||||
import (
|
||||
"errors"
|
||||
"sort"
|
||||
"strings"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
"github.com/spf13/pflag"
|
||||
)
|
||||
|
||||
// JSONOptions captures the resolved --json + --jq state after CheckJSONFlags.
|
||||
// A non-nil value means the user requested JSON output; Fields restricts
|
||||
// data.items[*] when len(Fields) > 0; JQ is a jq expression applied to the
|
||||
// final envelope JSON.
|
||||
type JSONOptions struct {
|
||||
Fields []string
|
||||
JQ string
|
||||
}
|
||||
|
||||
// Enabled reports whether the caller asked for JSON output. Convenience
|
||||
// shorthand for `opts != nil`.
|
||||
func (o *JSONOptions) Enabled() bool { return o != nil }
|
||||
|
||||
// jsonNoOptSentinel marks a bare `--json` (no comma-separated values
|
||||
// after it). pflag's NoOptDefVal mechanism stores this sentinel into the
|
||||
// slice; CheckJSONFlags then maps it to "no field filter" (full envelope).
|
||||
//
|
||||
// This is a documented divergence from gh CLI, where bare `--json` errors
|
||||
// with a field-list discovery prompt. weknora's envelope is itself the
|
||||
// machine-readable contract (carries typed error.code / _meta / risk),
|
||||
// so `--json` bare always producing the full envelope keeps v0.3 caller
|
||||
// scripts and the typical agent pipe-to-jq pattern working. Field
|
||||
// discovery moves to per-command `--help` "JSON fields:" sections.
|
||||
const jsonNoOptSentinel = "\x00json-no-value"
|
||||
|
||||
// AddJSONFlags registers --json and --jq on cmd.
|
||||
//
|
||||
// - `--json` → full envelope (no field filter)
|
||||
// - `--json id,name` → envelope with data.items[*] / data restricted
|
||||
// to listed fields
|
||||
// - `--jq <expr>` → applies a jq expression after marshaling;
|
||||
// requires --json to be set explicitly
|
||||
//
|
||||
// `fields` is the set of available fields the user may pass; rendered in
|
||||
// the command's help. Pass nil to skip the help annotation (uncommon).
|
||||
func AddJSONFlags(cmd *cobra.Command, fields []string) {
|
||||
f := cmd.Flags()
|
||||
f.StringSlice("json", nil, "Output JSON envelope; bare `--json` for full, `--json=id,name` for filtered fields")
|
||||
f.Lookup("json").NoOptDefVal = jsonNoOptSentinel
|
||||
f.StringP("jq", "q", "", "Filter JSON output using a jq `expression` (requires --json)")
|
||||
|
||||
if len(fields) > 0 {
|
||||
sorted := append([]string(nil), fields...)
|
||||
sort.Strings(sorted)
|
||||
// Append to Long without overwriting per-command prose.
|
||||
hdr := "\n\nJSON fields available via `--json id,name,...`:\n " +
|
||||
strings.Join(sorted, "\n ")
|
||||
if cmd.Long != "" {
|
||||
cmd.Long += hdr
|
||||
} else {
|
||||
cmd.Long = strings.TrimSpace(cmd.Short) + hdr
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// CheckJSONFlags resolves the --json + --jq state from cmd. Returns:
|
||||
// - (nil, nil) neither flag set (human output mode)
|
||||
// - (*JSONOptions, nil) --json set (possibly with --jq)
|
||||
// - (nil, error) --jq without --json (plain error, exit 1)
|
||||
//
|
||||
// Bare `--json` yields Fields == nil (full envelope). Explicit field list
|
||||
// yields Fields == []string{"id", "name", ...} (filter applied).
|
||||
//
|
||||
// gh divergence: gh errors on bare --json with a discovery prompt. weknora
|
||||
// treats bare --json as "full envelope, no filter" because the envelope is
|
||||
// the contract.
|
||||
func CheckJSONFlags(cmd *cobra.Command) (*JSONOptions, error) {
|
||||
f := cmd.Flags()
|
||||
jsonFlag := f.Lookup("json")
|
||||
jqFlag := f.Lookup("jq")
|
||||
if jsonFlag == nil {
|
||||
return nil, nil
|
||||
}
|
||||
if jsonFlag.Changed {
|
||||
sv, ok := jsonFlag.Value.(pflag.SliceValue)
|
||||
if !ok {
|
||||
return nil, errors.New("internal: --json flag is not a StringSlice")
|
||||
}
|
||||
raw := sv.GetSlice()
|
||||
opts := &JSONOptions{}
|
||||
// Strip the bare-flag sentinel if present.
|
||||
for _, v := range raw {
|
||||
if v == jsonNoOptSentinel {
|
||||
continue
|
||||
}
|
||||
opts.Fields = append(opts.Fields, v)
|
||||
}
|
||||
if jqFlag != nil {
|
||||
opts.JQ = jqFlag.Value.String()
|
||||
}
|
||||
return opts, nil
|
||||
}
|
||||
if jqFlag != nil && jqFlag.Changed {
|
||||
// gh parity: plain error, exit 1 (not FlagError → exit 2).
|
||||
return nil, errors.New("cannot use `--jq` without specifying `--json`")
|
||||
}
|
||||
return nil, nil
|
||||
}
|
||||
Reference in New Issue
Block a user