Merge origin/main into feat/cli-full-coverage

Reconcile the full-OpenAPI-coverage feature with main's #26 (incident
6-char short-id resolution in detail/get + list --nums) and #27 (shell
tab-completion + install.sh auto-setup).

incident.go conflicts resolved to main's design:
- list: keep --nums (#26) plus the eval's "--since→--until window < 31d"
  help text.
- get: adopt #26's resolveIncidentArg→List-by-incident_ids body; the
  full-coverage branch's /incident/info get is superseded by #26's new
  `detail` command (which carries the no-window Info path). All 7
  incident short-id tests pass.

postmortem.go / status_page.go (deleted by the coverage branch in favor
of generated commands) kept deleted; #27's registerEnumFlag additions to
them drop with the files — generated post-mortem/status-page commands
cover those ops. completion.go + install.sh + the curated commands'
registerEnumFlag calls retained.

Author: ysyneu

README.md

@@ -126,7 +126,8 @@ flashduty config set base_url URL  # Override API endpoint
 
 | Flag | Description |
 |------|-------------|
-| `--json` | Output as JSON instead of table |
+| `--output-format` | Output format: `table` (default), `json`, or `toon` (compact, fewer tokens) |
+| `--json` | Output as JSON (alias for `--output-format json`) |
 | `--no-trunc` | Do not truncate long fields in table output |
 | `--base-url` | Override the API base URL |
 
@@ -272,12 +273,18 @@ inc_def456   High memory usage        Warning    Processing   Staging       2026
 Showing 2 results (page 1, total 2).
 ```
 
-**JSON (`--json`):** Machine-parseable, full data, no truncation.
+**JSON (`--json` / `--output-format json`):** Machine-parseable, full data, no truncation.
 
 ```bash
 flashduty incident list --json | jq '.[].title'
 ```
 
+**TOON (`--output-format toon`):** Token-Oriented Object Notation — full data, no truncation, but drops the per-row repeated keys that JSON emits for uniform arrays, so list output costs materially fewer tokens. Preferred for LLM/agent consumption. Not directly `jq`-able; use `--json` when you need to pipe into `jq`.
+
+```bash
+flashduty incident list --output-format toon
+```
+
 **No truncation (`--no-trunc`):** Table with full field content.
 
 ---

install.sh

@@ -109,6 +109,122 @@ resolve_version() {
     echo "${version}"
 }
 
+# --- shell completion (best-effort, non-intrusive) ---
+
+# The user's interactive shell decides which completion script we need —
+# completion varies by shell, not by OS/arch. Empty when it's not one we support.
+detect_shell() {
+    case "$(basename "${SHELL:-}" 2>/dev/null)" in
+        bash) echo "bash" ;;
+        zsh)  echo "zsh" ;;
+        fish) echo "fish" ;;
+        *)    echo "" ;;
+    esac
+}
+
+# Emit the completion script for the shell named in $1. Cobra bakes the root
+# command name "flashduty" into the script (#compdef / complete -c / function
+# names); when installed under a different name, rewrite every occurrence so the
+# completion binds to the actual command (the runtime dispatch line already uses
+# the typed command word, so it needs no rewrite). The `|` sed delimiter is safe
+# because a binary name can't contain it, and the rewrite is a no-op for the
+# default "flashduty".
+gen_completion() {
+    "${BIN}" completion "$1" | sed "s|flashduty|${INSTALLED_NAME}|g"
+}
+
+# Install completion for the current shell into a directory the shell already
+# auto-loads, without ever editing the user's rc files. zsh has no guaranteed
+# writable fpath dir, so it only succeeds when a standard site-functions dir is
+# already writable (e.g. a Homebrew install); otherwise we point at the binary's
+# own per-shell setup instructions.
+setup_completion() {
+    [ "${OS}" = "Windows" ] && return 0
+    sh_name=$(detect_shell)
+    [ -z "${sh_name}" ] && return 0
+    "${BIN}" completion "${sh_name}" >/dev/null 2>&1 || return 0
+
+    case "${sh_name}" in
+        fish)
+            dir="${XDG_CONFIG_HOME:-${HOME}/.config}/fish/completions"
+            mkdir -p "${dir}" 2>/dev/null || true
+            if [ -w "${dir}" ]; then
+                gen_completion fish > "${dir}/${INSTALLED_NAME}.fish" && {
+                    info "Installed fish completion to ${dir}/${INSTALLED_NAME}.fish (restart fish to load)"
+                    return 0
+                }
+            fi
+            ;;
+        bash)
+            dir="${XDG_DATA_HOME:-${HOME}/.local/share}/bash-completion/completions"
+            mkdir -p "${dir}" 2>/dev/null || true
+            if [ -w "${dir}" ]; then
+                gen_completion bash > "${dir}/${INSTALLED_NAME}" && {
+                    info "Installed bash completion to ${dir}/${INSTALLED_NAME} (needs the bash-completion package; restart bash to load)"
+                    return 0
+                }
+            fi
+            ;;
+        zsh)
+            for dir in \
+                "${HOMEBREW_PREFIX:-/opt/homebrew}/share/zsh/site-functions" \
+                "/usr/local/share/zsh/site-functions" \
+                "/usr/share/zsh/site-functions"; do
+                if [ -d "${dir}" ] && [ -w "${dir}" ]; then
+                    gen_completion zsh > "${dir}/_${INSTALLED_NAME}" && {
+                        info "Installed zsh completion to ${dir}/_${INSTALLED_NAME}"
+                        info "  Run 'rm -f ~/.zcompdump*' and restart zsh to load."
+                        return 0
+                    }
+                fi
+            done
+            ;;
+    esac
+
+    # Couldn't auto-install into an auto-loaded dir (the common zsh case: no
+    # writable fpath dir, and we never edit ~/.zshrc). Print the exact,
+    # copy-pasteable steps so the user can finish setup in one go.
+    print_manual_completion "${sh_name}"
+}
+
+# Print a concrete, copy-pasteable recipe to enable completion for $1, used when
+# setup_completion can't drop the script into an auto-loaded directory. Plain
+# stdout (no "[flashduty]" prefix) so the commands paste cleanly.
+print_manual_completion() {
+    name="${INSTALLED_NAME}"
+    info "Shell completion was not auto-installed. To enable it for $1, run:"
+    case "$1" in
+        zsh)
+            cat <<EOF
+
+  mkdir -p ~/.zsh/completions
+  ${name} completion zsh > ~/.zsh/completions/_${name}
+  echo 'fpath=(~/.zsh/completions \$fpath)' >> ~/.zshrc   # one-time
+  rm -f ~/.zcompdump* && exec zsh
+
+EOF
+            ;;
+        bash)
+            cat <<EOF
+
+  mkdir -p ~/.local/share/bash-completion/completions
+  ${name} completion bash > ~/.local/share/bash-completion/completions/${name}
+  # requires the bash-completion package; then restart bash
+
+EOF
+            ;;
+        fish)
+            cat <<EOF
+
+  mkdir -p ~/.config/fish/completions
+  ${name} completion fish > ~/.config/fish/completions/${name}.fish
+  # then restart fish
+
+EOF
+            ;;
+    esac
+}
+
 # --- main ---
 
 main() {
@@ -201,6 +317,10 @@ main() {
            info "  export PATH=\"${INSTALL_DIR}:\$PATH\"" ;;
     esac
 
+    # Best-effort shell completion; never fail the install over it.
+    BIN="${INSTALL_DIR}/${INSTALLED_NAME}"
+    setup_completion || true
+
     info "Run '${INSTALLED_NAME} version' to verify"
 }
 

internal/cli/alert.go

@@ -100,6 +100,7 @@ func newAlertListCmd() *cobra.Command {
 
 	cmd.Flags().StringVar(&severity, "severity", "", "Filter: Critical,Warning,Info")
 	cmd.Flags().BoolVar(&active, "active", false, "Show active only")
+	registerEnumFlag(cmd, "severity", severityEnum...)
 	cmd.Flags().BoolVar(&recovered, "recovered", false, "Show recovered only")
 	cmd.Flags().StringVar(&channel, "channel", "", "Comma-separated channel IDs")
 	cmd.Flags().BoolVar(&muted, "muted", false, "Show ever-muted only")

internal/cli/alert_event.go

@@ -84,6 +84,7 @@ func newAlertEventListCmd() *cobra.Command {
 
 	cmd.Flags().StringVar(&severity, "severity", "", "Filter: Critical,Warning,Info (comma-separated)")
 	cmd.Flags().StringVar(&channel, "channel", "", "Comma-separated channel IDs")
+	registerEnumFlag(cmd, "severity", severityEnum...)
 	cmd.Flags().StringVar(&integrationType, "integration-type", "", "Comma-separated integration types")
 	cmd.Flags().StringVar(&since, "since", "1h", "Start time")
 	cmd.Flags().StringVar(&until, "until", "now", "End time")

internal/cli/completion.go

@@ -0,0 +1,16 @@
+package cli
+
+import "github.com/spf13/cobra"
+
+// severityEnum is the closed set of incident/alert severities, shared by every
+// --severity flag.
+var severityEnum = []string{"Critical", "Warning", "Info"}
+
+// registerEnumFlag makes <flag>'s value tab-complete to a fixed set and
+// suppresses the default filename completion. The error only fires on an
+// unknown flag name (a programmer error), so it is ignored.
+func registerEnumFlag(cmd *cobra.Command, flag string, values ...string) {
+	_ = cmd.RegisterFlagCompletionFunc(flag, func(*cobra.Command, []string, string) ([]string, cobra.ShellCompDirective) {
+		return values, cobra.ShellCompDirectiveNoFileComp
+	})
+}

internal/cli/incident.go

@@ -2,9 +2,11 @@ package cli
 
 import (
 	"bufio"
+	"errors"
 	"fmt"
 	"io"
 	"os"
+	"regexp"
 	"strconv"
 	"strings"
 	"time"
@@ -73,7 +75,7 @@ func pastIncidentColumns() []output.Column {
 }
 
 func newIncidentListCmd() *cobra.Command {
-	var progress, severity, query, since, until string
+	var progress, severity, query, since, until, nums string
 	var channelID int64
 	var limit, page int
 
@@ -104,6 +106,9 @@ func newIncidentListCmd() *cobra.Command {
 				if channelID != 0 {
 					req.ChannelIDs = []int64{channelID}
 				}
+				if nums != "" {
+					req.Nums = parseStringSlice(nums)
+				}
 
 				result, _, err := ctx.Client.Incidents.List(cmdContext(ctx.Cmd), req)
 				if err != nil {
@@ -117,8 +122,11 @@ func newIncidentListCmd() *cobra.Command {
 
 	cmd.Flags().StringVar(&progress, "progress", "", "Filter: Triggered,Processing,Closed")
 	cmd.Flags().StringVar(&severity, "severity", "", "Filter: Critical,Warning,Info")
+	registerEnumFlag(cmd, "progress", "Triggered", "Processing", "Closed")
+	registerEnumFlag(cmd, "severity", severityEnum...)
 	cmd.Flags().Int64Var(&channelID, "channel", 0, "Filter by channel ID")
 	cmd.Flags().StringVar(&query, "query", "", "Free-text search across title/labels/content (also resolves a 24-char incident ID or 6-char incident num to a direct lookup)")
+	cmd.Flags().StringVar(&nums, "nums", "", "Comma-separated short incident ids (num, the 6-char id shown in the UI) to filter by")
 	cmd.Flags().StringVar(&since, "since", "24h", "Start time (duration, date, datetime, or unix timestamp; --since→--until window must be < 31 days)")
 	cmd.Flags().StringVar(&until, "until", "now", "End time")
 	cmd.Flags().IntVar(&limit, "limit", 20, "Max results (max 100)")
@@ -127,6 +135,62 @@ func newIncidentListCmd() *cobra.Command {
 	return cmd
 }
 
+// shortIDResolveDays bounds how far back a 6-char short id is resolved.
+// /incident/list is the only endpoint that accepts a num, and the backend caps
+// its query span at ~30 days, so older incidents can only be looked up by their
+// full 24-char id.
+const shortIDResolveDays = 30
+
+var reShortIncidentID = regexp.MustCompile(`^[0-9a-fA-F]{6}$`)
+
+// resolveIncidentArg maps a user-supplied incident argument to a full 24-char
+// incident id. A full id — or any value that isn't a 6-char short id — passes
+// through unchanged, preserving existing behavior. A 6-char short id ("num", as
+// shown in the UI) is resolved against the last shortIDResolveDays days via
+// /incident/list. A unique hit returns the full id; multiple hits return the
+// candidates (the short id is non-unique by design) so the caller can surface
+// them; no hit returns a descriptive error.
+func resolveIncidentArg(ctx *RunContext, arg string) (fullID string, candidates []flashduty.IncidentInfo, err error) {
+	if !reShortIncidentID.MatchString(arg) {
+		return arg, nil, nil
+	}
+
+	end := time.Now().Unix()
+	start := end - int64(shortIDResolveDays)*24*60*60
+	res, _, err := ctx.Client.Incidents.List(cmdContext(ctx.Cmd), &flashduty.ListIncidentsRequest{
+		Nums:      []string{strings.ToUpper(arg)},
+		StartTime: start,
+		EndTime:   end,
+	})
+	if err != nil {
+		return "", nil, err
+	}
+
+	switch len(res.Items) {
+	case 0:
+		return "", nil, fmt.Errorf(
+			"no incident with short id %q in the last %d days; older incidents must be queried by their full 24-char id",
+			arg, shortIDResolveDays)
+	case 1:
+		return res.Items[0].IncidentID, nil, nil
+	default:
+		return "", res.Items, nil
+	}
+}
+
+// ambiguousShortIDError reports a short id that resolved to more than one
+// incident, listing each candidate's full id so the caller can disambiguate.
+func ambiguousShortIDError(shortID string, candidates []flashduty.IncidentInfo) error {
+	var b strings.Builder
+	_, _ = fmt.Fprintf(&b, "short id %q matches %d incidents in the last %d days — re-run with one of these full ids:",
+		shortID, len(candidates), shortIDResolveDays)
+	for _, c := range candidates {
+		_, _ = fmt.Fprintf(&b, "\n  %s  %-8s  %-10s  %s  %s",
+			c.IncidentID, orDash(c.IncidentSeverity), orDash(c.Progress), output.FormatTime(c.StartTime), c.Title)
+	}
+	return errors.New(b.String())
+}
+
 func newIncidentGetCmd() *cobra.Command {
 	return &cobra.Command{
 		Use:   "get <id> [<id2> ...]",
@@ -135,36 +199,37 @@ func newIncidentGetCmd() *cobra.Command {
 		Args:  requireArgs("incident_id"),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runCommand(cmd, args, func(ctx *RunContext) error {
-				// Fetch each incident by ID via /incident/info: it works for
-				// any id with no time window. /incident/list cannot serve a
-				// plain get-by-id — it mandates a start/end window and caps it
-				// at 31 days, so it 400s ("StartTime is a required field") when
-				// queried by id alone.
-				items := make([]flashduty.IncidentInfo, 0, len(ctx.Args))
-				for _, id := range ctx.Args {
-					info, _, err := ctx.Client.Incidents.Info(cmdContext(ctx.Cmd), &flashduty.IncidentInfoRequest{
-						IncidentID: id,
-					})
+				ids := make([]string, 0, len(ctx.Args))
+				for _, a := range ctx.Args {
+					fullID, candidates, err := resolveIncidentArg(ctx, a)
 					if err != nil {
-						return fmt.Errorf("get incident %s: %w", id, err)
+						return err
 					}
-					if info != nil {
-						items = append(items, *info)
+					if len(candidates) > 0 {
+						return ambiguousShortIDError(a, candidates)
 					}
+					ids = append(ids, fullID)
+				}
+
+				result, _, err := ctx.Client.Incidents.List(cmdContext(ctx.Cmd), &flashduty.ListIncidentsRequest{
+					IncidentIDs: ids,
+				})
+				if err != nil {
+					return err
 				}
 
 				if ctx.Structured() {
-					return ctx.Printer.Print(items, nil)
+					return ctx.Printer.Print(result.Items, nil)
 				}
 
 				// Single incident: vertical detail view
-				if len(items) == 1 {
-					printIncidentDetail(ctx.Writer, items[0])
+				if len(ctx.Args) == 1 && len(result.Items) == 1 {
+					printIncidentDetail(ctx.Writer, result.Items[0])
 					return nil
 				}
 
 				// Multiple: table
-				return ctx.Printer.Print(items, incidentColumns())
+				return ctx.Printer.Print(result.Items, incidentColumns())
 			})
 		},
 	}
@@ -277,6 +342,7 @@ func newIncidentCreateCmd() *cobra.Command {
 	cmd.Flags().StringVar(&title, "title", "", "Incident title (required, 3-200 chars)")
 	cmd.Flags().StringVar(&severity, "severity", "", "Severity: Critical, Warning, Info (required)")
 	cmd.Flags().Int64Var(&channelID, "channel", 0, "Channel ID")
+	registerEnumFlag(cmd, "severity", severityEnum...)
 	cmd.Flags().StringVar(&description, "description", "", "Description (max 6144 chars)")
 	cmd.Flags().IntSliceVar(&assign, "assign", nil, "Person IDs to assign (use 'flashduty member list' to look up IDs)")
 
@@ -368,6 +434,7 @@ func newIncidentUpdateCmd() *cobra.Command {
 	cmd.Flags().StringVar(&description, "description", "", "New description")
 	cmd.Flags().StringVar(&severity, "severity", "", "New severity: Critical, Warning, Info")
 	cmd.Flags().StringArrayVar(&fieldFlags, "field", nil, "Custom field: key=value (repeatable)")
+	registerEnumFlag(cmd, "severity", severityEnum...)
 
 	return cmd
 }
@@ -1351,8 +1418,16 @@ func newIncidentDetailCmd() *cobra.Command {
 		Args:  requireArgs("incident_id"),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runCommand(cmd, args, func(ctx *RunContext) error {
+				fullID, candidates, err := resolveIncidentArg(ctx, ctx.Args[0])
+				if err != nil {
+					return err
+				}
+				if len(candidates) > 0 {
+					return ambiguousShortIDError(ctx.Args[0], candidates)
+				}
+
 				result, _, err := ctx.Client.Incidents.Info(cmdContext(ctx.Cmd), &flashduty.IncidentInfoRequest{
-					IncidentID: ctx.Args[0],
+					IncidentID: fullID,
 				})
 				if err != nil {
 					return err