feat: self-correcting flag/command errors, global --fields, query window notes

Callers frequently guess flag and verb names by analogy with a sibling
command. The errors now carry the candidates, so the next call can be
right without a separate --help round trip:

- Unknown flag: lists the closest flag names, the command's own flags and
  the global flags (root FlagErrorFunc, inherited by curated and generated
  commands). Other flag errors pass through unchanged.
- Unknown command: suggests siblings, then single-record verb synonyms
  (get/info/infos/detail), then any leaf in the whole tree whose path
  contains the token on hyphen-token boundaries (`silence` ->
  `channel silence-rule-list`, `monit-datasource` -> `monit datasource-list`),
  and lists the level's commands. The check now runs before cobra
  dispatch, so `<group> <typo> --help` errors instead of printing the
  group's help and exiting 0.
- `--version` is accepted and prints the `version` line.

--fields is now a global output flag: json/toon output of any command is
projected to the named top-level fields (each row of a list, or the keys
of a single record), before the 16 KiB bound is applied. A name matching
no key is reported on stderr with the keys that exist; acknowledgements
and raw bodies print unchanged with a note; non-projectable shapes are an
error. Commands with their own --fields keep it.

Windowed queries announce on stderr the window they sent, in the local
timezone, with its span and its end relative to now
(`note: window ..(1h, ends in 7h)`), which makes a wrong default or a
timezone slip visible. This covers the curated windowed verbs,
monit-query's execution window, and generated --start-time/--end-time
pairs. `incident list` with only open --progress states and
`alert list --active` default to 30d instead of 24h when --since is not
given, since open records are often older than a day.

skilldoc: the dump now carries the root's flags; the validator checks the
flags of a bare `fduty --flag` example against them and takes global
flags from the dump instead of a hand-kept list.

Author: ysyneu

README.md

@@ -124,7 +124,9 @@ flashduty config set base_url URL  # Override the API endpoint
 | `--output-format` | `table` (default), `json`, or `toon` |
 | `--json` | Alias for `--output-format json` |
 | `--no-trunc` | Do not truncate long fields in table output |
+| `--fields` | Keep only these comma-separated top-level fields in `json`/`toon` output: each row of a list, or the keys of a single record |
 | `--base-url` | Override the API base URL |
+| `--version` | Print the version (same as `flashduty version`) |
 
 ## Output formats
 
@@ -134,6 +136,10 @@ flashduty config set base_url URL  # Override the API endpoint
 
 Every structured list page is capped at 16 KiB. A page that had to be reduced is reported on stderr, and list envelopes also carry `"truncated": true` in the payload. With `"emitted_rows": N`, only the first N rows were returned: re-request with a smaller `--limit` until the rows you hold reach `total`. Without it, every row is present but long values were clipped: narrow `--fields`.
 
+Commands that query a time range print the window they actually sent on stderr, in the local timezone, e.g. `note: window 2026-10-08T14:00:00+08:00..2026-10-09T14:00:00+08:00 (1d, ended now)`. stdout stays pure `json`/`toon`. `incident list --progress Triggered,Processing` and `alert list --active` default to the last 30 days when `--since` is not given, since open records can be older than a day.
+
+An unknown flag or command error lists the closest valid names and the valid choices at that level.
+
 ## Updating
 
 ```bash

README_zh.md

@@ -124,7 +124,9 @@ flashduty config set base_url URL  # 修改 API 地址
 | `--output-format` | `table`（默认）、`json` 或 `toon` |
 | `--json` | 等同 `--output-format json` |
 | `--no-trunc` | 表格输出不截断长字段 |
+| `--fields` | `json`/`toon` 输出只保留这些顶层字段（逗号分隔）：列表按行保留，单条记录保留对应 key |
 | `--base-url` | 覆盖 API 地址 |
+| `--version` | 打印版本（同 `flashduty version`） |
 
 ## 输出格式
 
@@ -134,6 +136,10 @@ flashduty config set base_url URL  # 修改 API 地址
 
 每一页结构化列表最大 16 KiB。被裁剪的页会在 stderr 上提示，列表的返回体里也会带 `"truncated": true`。同时带 `"emitted_rows": N` 表示只返回了前 N 行：用更小的 `--limit` 重新请求，直到拿到的行数达到 `total`。不带 `emitted_rows` 表示行都在，但长字段被截断：用 `--fields` 缩小字段范围。
 
+按时间范围查询的命令会在 stderr 上打印实际发出的时间窗口（本地时区），例如 `note: window 2026-10-08T14:00:00+08:00..2026-10-09T14:00:00+08:00 (1d, ended now)`；stdout 仍是纯 `json`/`toon`。`incident list --progress Triggered,Processing` 和 `alert list --active` 在没给 `--since` 时默认查最近 30 天，因为未关闭的记录可能早于一天。
+
+未知 flag 或命令的报错会列出最接近的有效名称，以及该层级所有可用的选项。
+
 ## 升级
 
 ```bash

internal/cli/alert.go

@@ -10,7 +10,6 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/flashcatcloud/flashduty-cli/internal/output"
-	"github.com/flashcatcloud/flashduty-cli/internal/timeutil"
 )
 
 func newAlertCmd() *cobra.Command {
@@ -38,13 +37,13 @@ func newAlertListCmd() *cobra.Command {
 					return fmt.Errorf("--active and --recovered are mutually exclusive")
 				}
 
-				startTime, err := timeutil.Parse(since)
-				if err != nil {
-					return fmt.Errorf("invalid --since: %w", err)
+				why := ""
+				if active && !cmd.Flags().Changed("since") {
+					since, why = openStateSince, "default --since "+openStateSince+" because of --active"
 				}
-				endTime, err := timeutil.Parse(until)
+				startTime, endTime, err := parseWindow(cmd, since, until, why)
 				if err != nil {
-					return fmt.Errorf("invalid --until: %w", err)
+					return err
 				}
 
 				req := &flashduty.AlertListRequest{
@@ -126,7 +125,7 @@ func newAlertListCmd() *cobra.Command {
 	cmd.Flags().StringVar(&alertKeys, "alert-keys", "", "Comma-separated alert deduplication keys")
 	cmd.Flags().BoolVar(&asc, "asc", false, "Sort oldest first by start time (default newest first)")
 	cmd.Flags().BoolVar(&byUpdatedAt, "by-updated-at", false, "Apply --since/--until to the last-updated time instead of the start time")
-	cmd.Flags().StringVar(&since, "since", "24h", "Start time")
+	cmd.Flags().StringVar(&since, "since", "24h", "Start time. Defaults to 30d with --active")
 	cmd.Flags().StringVar(&until, "until", "now", "End time")
 	cmd.Flags().IntVar(&limit, "limit", 20, "Max results (max 100)")
 	cmd.Flags().IntVar(&page, "page", 1, "Page number")

internal/cli/alert_event.go

@@ -8,7 +8,6 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/flashcatcloud/flashduty-cli/internal/output"
-	"github.com/flashcatcloud/flashduty-cli/internal/timeutil"
 )
 
 func newAlertEventCmd() *cobra.Command {
@@ -32,13 +31,9 @@ func newAlertEventListCmd() *cobra.Command {
 					return fmt.Errorf("--fields must name at least one field")
 				}
 
-				startTime, err := timeutil.Parse(since)
+				startTime, endTime, err := parseWindow(cmd, since, until, "")
 				if err != nil {
-					return fmt.Errorf("invalid --since: %w", err)
-				}
-				endTime, err := timeutil.Parse(until)
-				if err != nil {
-					return fmt.Errorf("invalid --until: %w", err)
+					return err
 				}
 
 				input := &flashduty.AlertEventGlobalListRequest{

internal/cli/audit.go

@@ -7,7 +7,6 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/flashcatcloud/flashduty-cli/internal/output"
-	"github.com/flashcatcloud/flashduty-cli/internal/timeutil"
 )
 
 func newAuditCmd() *cobra.Command {
@@ -28,13 +27,9 @@ func newAuditSearchCmd() *cobra.Command {
 		Long:  curatedLong("Search audit logs within a time window, optionally filtered by person, operation type, write/read, risk level and request ID. The --since/--until window must be < 90 days; --limit max is 99.", "AuditLogs", "Search"),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runCommand(cmd, args, func(ctx *RunContext) error {
-				startTime, err := timeutil.Parse(since)
+				startTime, endTime, err := parseWindow(cmd, since, until, "")
 				if err != nil {
-					return fmt.Errorf("invalid --since: %w", err)
-				}
-				endTime, err := timeutil.Parse(until)
-				if err != nil {
-					return fmt.Errorf("invalid --until: %w", err)
+					return err
 				}
 
 				input := &flashduty.AuditSearchRequest{

internal/cli/change.go

@@ -8,7 +8,6 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/flashcatcloud/flashduty-cli/internal/output"
-	"github.com/flashcatcloud/flashduty-cli/internal/timeutil"
 )
 
 func newChangeCmd() *cobra.Command {
@@ -31,13 +30,9 @@ func newChangeListCmd() *cobra.Command {
 		Long:  curatedLong("List changes recorded in the change feed. Time window must be < 31 days; --limit max is 100.", "Changes", "List"),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runCommand(cmd, args, func(ctx *RunContext) error {
-				startTime, err := timeutil.Parse(since)
+				startTime, endTime, err := parseWindow(cmd, since, until, "")
 				if err != nil {
-					return fmt.Errorf("invalid --since: %w", err)
-				}
-				endTime, err := timeutil.Parse(until)
-				if err != nil {
-					return fmt.Errorf("invalid --until: %w", err)
+					return err
 				}
 
 				// The legacy SDK clamped non-positive paging to sane defaults

internal/cli/command.go

@@ -3,7 +3,6 @@ package cli
 import (
 	"fmt"
 	"io"
-	"strings"
 
 	"github.com/flashcatcloud/go-flashduty"
 	"github.com/spf13/cobra"
@@ -41,7 +40,7 @@ func runCommand(cmd *cobra.Command, args []string, fn func(ctx *RunContext) erro
 		Cmd:     cmd,
 		Args:    args,
 		Writer:  cmd.OutOrStdout(),
-		Printer: newPrinter(cmd.OutOrStdout()),
+		Printer: newPrinter(cmd),
 		Format:  currentOutputFormat(),
 	}
 	return fn(ctx)
@@ -81,6 +80,7 @@ func (ctx *RunContext) PrintTotal(items any, cols []output.Column, total int) er
 
 // WriteResult prints a success message as plain text or JSON.
 func (ctx *RunContext) WriteResult(message string) {
+	noteFieldsNotApplied(ctx.Cmd)
 	writeResult(ctx.Writer, message)
 }
 
@@ -89,6 +89,7 @@ func (ctx *RunContext) WriteResult(message string) {
 // shell redirection (`> file.csv`) captures the bytes verbatim instead of the
 // canned "OK: POST ..." acknowledgment.
 func (ctx *RunContext) WriteRaw(body []byte) error {
+	noteFieldsNotApplied(ctx.Cmd)
 	_, err := ctx.Writer.Write(body)
 	return err
 }
@@ -101,6 +102,7 @@ func (ctx *RunContext) WriteResultJSON(data any, humanMessage string) error {
 		_, _ = fmt.Fprintln(ctx.Writer, humanMessage)
 		return nil
 	}
+	noteFieldsNotApplied(ctx.Cmd)
 	out, err := marshalStructured(data)
 	if err != nil {
 		return fmt.Errorf("failed to marshal output: %w", err)
@@ -127,26 +129,13 @@ func (ctx *RunContext) WriteResultJSON(data any, humanMessage string) error {
 // Pairing this validator with a real RunE (below) makes the group Runnable,
 // so cobra actually calls ValidateArgs with the leftover token and this
 // function gets a chance to reject it instead of it being silently dropped.
+// Cobra still answers --help before ValidateArgs, which is why Execute also
+// runs rejectUnknownSubcommand ahead of dispatch.
 func groupUnknownSubcommand(cmd *cobra.Command, args []string) error {
 	if len(args) == 0 {
 		return nil
 	}
-	// Mirrors cobra's own default (see (*Command).findSuggestions): a group
-	// built via newGroupCmd never sets this itself, so the zero value would
-	// otherwise disable the Levenshtein half of SuggestionsFor.
-	if cmd.SuggestionsMinimumDistance <= 0 {
-		cmd.SuggestionsMinimumDistance = 2
-	}
-	suggestion := ""
-	if names := cmd.SuggestionsFor(args[0]); len(names) > 0 {
-		var b strings.Builder
-		b.WriteString("\n\nDid you mean this?\n")
-		for _, name := range names {
-			fmt.Fprintf(&b, "\t%s\n", name)
-		}
-		suggestion = b.String()
-	}
-	return fmt.Errorf("unknown command %q for %q%s", args[0], cmd.CommandPath(), suggestion)
+	return unknownCommandError(cmd, args[0])
 }
 
 // newGroupCmd creates a command-group node: Use/Short (with Long/Example

internal/cli/command_test.go

@@ -73,9 +73,7 @@ func execCommand(args ...string) (string, error) {
 	buf := new(bytes.Buffer)
 	rootCmd.SetOut(buf)
 	rootCmd.SetErr(buf)
-	rootCmd.SetArgs(args)
-
-	err := rootCmd.Execute()
+	err := executeArgs(args)
 
 	// Reset the persistent flags cobra parsed so subsequent calls within the
 	// same test process do not carry stale values.
@@ -97,9 +95,7 @@ func execCommandSplit(args ...string) (stdout, stderr string, err error) {
 	errBuf := new(bytes.Buffer)
 	rootCmd.SetOut(outBuf)
 	rootCmd.SetErr(errBuf)
-	rootCmd.SetArgs(args)
-
-	err = rootCmd.Execute()
+	err = executeArgs(args)
 
 	rootCmd.SetArgs(nil)
 	rootCmd.SetOut(nil)

internal/cli/fieldproject_test.go

@@ -316,7 +316,7 @@ func TestIncidentListStructuredDefaultUsesCompactProjection(t *testing.T) {
 		stub := newGFStub(t)
 		stub.data = map[string]any{"items": []any{incidentRow()}, "total": 1}
 
-		out, err := execCommand("incident", "list", "--fields", "incident_id,title", "--output-format", "json")
+		out, _, err := execCommandSplit("incident", "list", "--fields", "incident_id,title", "--output-format", "json")
 		if err != nil {
 			t.Fatalf("execCommand: %v", err)
 		}
@@ -466,7 +466,7 @@ func TestFieldsProjectionJSON(t *testing.T) {
 			stub.data = map[string]any{"items": []any{tc.data}, "total": 1}
 
 			args := append(append([]string(nil), tc.cmd...), "--fields", strings.Join(tc.fields, ","), "--output-format", "json")
-			out, err := execCommand(args...)
+			out, _, err := execCommandSplit(args...)
 			if err != nil {
 				t.Fatalf("execCommand: %v", err)
 			}

internal/cli/gen_support.go

@@ -9,6 +9,7 @@ import (
 	"reflect"
 	"strconv"
 	"strings"
+	"time"
 
 	"github.com/spf13/cobra"
 
@@ -349,6 +350,21 @@ func printGenericResult(ctx *RunContext, data any) error {
 		return err
 	}
 	if ctx.Structured() {
+		// Size the payload as it will print: project first, then bound and
+		// print through the unprojecting printer so --fields runs once.
+		if fields := requestedFields(); len(fields) > 0 {
+			proj, err := projectOutput(ctx.Cmd, data, fields)
+			if err != nil {
+				return err
+			}
+			noteFieldsMissing(ctx.Cmd, proj)
+			data = proj.out
+			if pp, ok := ctx.Printer.(projectingPrinter); ok {
+				projected := *ctx
+				projected.Printer = pp.inner
+				ctx = &projected
+			}
+		}
 		return printBoundedGenericResult(ctx, data)
 	}
 	return renderGenericTable(ctx, data)
@@ -570,6 +586,16 @@ func genParseTimeFlagAlias(cmd *cobra.Command, name, alias, raw, aliasRaw string
 	return genParseTimeFlag(cmd, name, raw)
 }
 
+// genNoteWindow announces a generated verb's resolved --start-time/--end-time
+// window (see noteWindow), when both flags were given. A side left to --data
+// or to the server's default was not resolved by the CLI, so nothing is
+// announced rather than half a window.
+func genNoteWindow(cmd *cobra.Command, start, end int64, both bool) {
+	if both {
+		noteWindow(cmd.ErrOrStderr(), time.Unix(start, 0), time.Unix(end, 0), "")
+	}
+}
+
 // genGroup finds an existing subcommand named `name` under parent, or creates a
 // group command with that name. This lets generated commands attach to the same
 // group a curated command already owns (partial-coverage services) and lets a