feat: centralize --json/--fields injection via output: "json" on buildCommand

Lift --json and --fields flag definitions out of 17 individual commands
into buildCommand's output mode system. When a command declares
output: "json", the wrapper automatically:

- Injects --json (boolean) and --fields (parsed) flags
- Pre-parses --fields from comma-string to string[] before func runs
- Respects command-owned --json flags (skips injection, still adds --fields)

Also introduces writeJsonList() helper that applies --fields filtering
to each array element inside the {data, hasMore} wrapper, fixing the
BugBot-reported issue where filtering operated on the wrapper instead
of the nested data.

Changes:
- src/lib/command.ts: JSON_FLAG, FIELDS_FLAG constants, output mode logic
- src/lib/formatters/json.ts: writeJsonList() with extra? option
- src/lib/formatters/output.ts: fields? on WriteOutputOptions
- src/lib/list-command.ts: passes output through to buildCommand
- src/lib/org-list.ts: fields on BaseListFlags, writeJsonList at wrapper site
- 17 command files: migrated to output: "json", removed manual flag defs
- 3 commands gained --fields: auth/refresh, org/view, trace/logs
- test/lib/command.test.ts: 14 new tests for json injection + fields parsing
- test/lib/formatters/json.test.ts: 17 new tests for writeJsonList

Author: BYK

AGENTS.md

@@ -648,6 +648,9 @@ mock.module("./some-module", () => ({
 <!-- lore:019cc40e-e56e-71e9-bc5d-545f97df732b -->
 * **Consola prompt cancel returns truthy Symbol, not false**: When a user cancels a \`consola\` / \`@clack/prompts\` confirmation prompt (Ctrl+C), the return value is \`Symbol(clack:cancel)\`, not \`false\`. Since Symbols are truthy in JavaScript, checking \`!confirmed\` will be \`false\` and the code falls through as if the user confirmed. Fix: use \`confirmed !== true\` (strict equality) instead of \`!confirmed\` to correctly handle cancel, false, and any other non-true values.
 
+<!-- lore:019cd379-4c6a-7a93-beae-b1d5b4df69b1 -->
+* **Dot-notation field filtering is ambiguous for keys containing dots**: The \`filterFields\` function in \`src/lib/formatters/json.ts\` uses dot-notation to address nested fields (e.g., \`metadata.value\`). This means object keys that literally contain dots are ambiguous and cannot be addressed. Property-based tests for this function must generate field name arbitraries that exclude dots — use a restricted charset like \`\[a-zA-Z0-9\_]\` in fast-check arbitraries. Counterexample found by fast-check: \`{"a":{".":false}}\` with path \`"a."\` splits into \`\["a", ""]\` and fails to resolve.
+
 <!-- lore:019cbe0d-d03e-716c-b372-b09998c07ed6 -->
 * **Stricli rejects unknown flags — pre-parsed global flags must be consumed from argv**: Stricli's arg parser is strict: any \`--flag\` not registered on a command throws \`No flag registered for --flag\`. Global flags (parsed before Stricli in bin.ts) MUST be spliced out of argv. \`--log-level\` was correctly consumed but \`--verbose\` was intentionally left in (for the \`api\` command's own \`--verbose\`). This breaks every other command. Also, \`argv.indexOf('--flag')\` doesn't match \`--flag=value\` form — must check both space-separated and equals-sign forms when pre-parsing. A Biome \`noRestrictedImports\` lint rule in \`biome.jsonc\` now blocks \`import { buildCommand } from "@stricli/core"\` at error level — only \`src/lib/command.ts\` is exempted. Other \`@stricli/core\` exports (\`buildRouteMap\`, \`run\`, etc.) are allowed.
 
@@ -659,6 +662,9 @@ mock.module("./some-module", () => ({
 <!-- lore:019cce8d-f2d6-7862-9105-7a0048f0e993 -->
 * **Property-based tests for input validators use stringMatching for forbidden char coverage**: In \`test/lib/input-validation.property.test.ts\`, forbidden-character arbitraries are built with \`stringMatching\` targeting specific regex patterns (e.g., \`/^\[^\x00-\x1f]\*\[\x00-\x1f]\[^\x00-\x1f]\*$/\` for control chars). This ensures fast-check generates strings that always contain the forbidden character while varying surrounding content. The \`biome-ignore lint/suspicious/noControlCharactersInRegex\` suppression is needed on the control char regex constant in \`input-validation.ts\`.
 
+<!-- lore:019cd379-4c71-7477-9cc6-3c0dfc7fb597 -->
+* **Shared flag constants in list-command.ts for cross-command consistency**: \`src/lib/list-command.ts\` exports shared Stricli flag definitions (\`FIELDS\_FLAG\`, \`FRESH\_FLAG\`, \`FRESH\_ALIASES\`) reused across all commands. When adding a new global-ish flag to multiple commands, define it once here as a const satisfying Stricli's flag shape, then spread into each command's \`flags\` object. The \`--fields\` flag is \`{ kind: 'parsed', parse: String, brief: '...', optional: true }\`. \`parseFieldsList()\` in \`formatters/json.ts\` handles comma-separated parsing with trim/dedup. \`writeJson()\` accepts an optional \`fields\` array and calls \`filterFields()\` before serialization.
+
 <!-- lore:019cbe44-7687-7288-81a2-662feefc28ea -->
 * **SKILL.md generator must filter hidden Stricli flags**: \`script/generate-skill.ts\` introspects Stricli's route tree to auto-generate \`plugins/sentry-cli/skills/sentry-cli/SKILL.md\`. The \`FlagDef\` type must include \`hidden?: boolean\` and \`extractFlags\` must propagate it to \`FlagInfo\`. The filter in \`generateCommandDoc\` must exclude \`f.hidden\` alongside \`help\`/\`helpAll\`. Without this, hidden flags injected by \`buildCommand\` (like \`--log-level\`, \`--verbose\`) appear on every command in the AI agent skill file. Global flags should instead be documented once in \`docs/src/content/docs/commands/index.md\` Global Options section, which the generator pulls into SKILL.md via \`loadCommandsOverview\`.
 <!-- End lore-managed section -->

src/commands/auth/refresh.ts

@@ -15,10 +15,12 @@ import {
 import { AuthError } from "../../lib/errors.js";
 import { success } from "../../lib/formatters/colors.js";
 import { formatDuration } from "../../lib/formatters/human.js";
+import { writeJson } from "../../lib/formatters/index.js";
 
 type RefreshFlags = {
   readonly json: boolean;
   readonly force: boolean;
+  readonly fields?: string[];
 };
 
 type RefreshOutput = {
@@ -50,13 +52,9 @@ Examples:
   {"success":true,"refreshed":true,"expiresIn":3600,"expiresAt":"..."}
     `.trim(),
   },
+  output: "json",
   parameters: {
     flags: {
-      json: {
-        kind: "boolean",
-        brief: "Output result as JSON",
-        default: false,
-      },
       force: {
         kind: "boolean",
         brief: "Force refresh even if token is still valid",
@@ -103,7 +101,7 @@ Examples:
     };
 
     if (flags.json) {
-      stdout.write(`${JSON.stringify(output)}\n`);
+      writeJson(stdout, output, flags.fields);
     } else if (result.refreshed) {
       stdout.write(
         `${success("✓")} Token refreshed successfully. Expires in ${formatDuration(result.expiresIn ?? 0)}.\n`

src/commands/auth/whoami.ts

@@ -12,22 +12,17 @@ import { buildCommand } from "../../lib/command.js";
 import { isAuthenticated } from "../../lib/db/auth.js";
 import { setUserInfo } from "../../lib/db/user.js";
 import { AuthError } from "../../lib/errors.js";
-import {
-  formatUserIdentity,
-  parseFieldsList,
-  writeJson,
-} from "../../lib/formatters/index.js";
+import { formatUserIdentity, writeJson } from "../../lib/formatters/index.js";
 import {
   applyFreshFlag,
-  FIELDS_FLAG,
   FRESH_ALIASES,
   FRESH_FLAG,
 } from "../../lib/list-command.js";
 
 type WhoamiFlags = {
   readonly json: boolean;
   readonly fresh: boolean;
-  readonly fields?: string;
+  readonly fields?: string[];
 };
 
 export const whoamiCommand = buildCommand({
@@ -38,22 +33,16 @@ export const whoamiCommand = buildCommand({
       "This calls the Sentry API live (not cached) so the result always reflects " +
       "the current token. Works with all token types: OAuth, API tokens, and OAuth App tokens.",
   },
+  output: "json",
   parameters: {
     flags: {
-      json: {
-        kind: "boolean",
-        brief: "Output as JSON",
-        default: false,
-      },
       fresh: FRESH_FLAG,
-      fields: FIELDS_FLAG,
     },
     aliases: FRESH_ALIASES,
   },
   async func(this: SentryContext, flags: WhoamiFlags): Promise<void> {
     applyFreshFlag(flags);
     const { stdout } = this;
-    const fields = flags.fields ? parseFieldsList(flags.fields) : undefined;
 
     if (!(await isAuthenticated())) {
       throw new AuthError("not_authenticated");
@@ -83,7 +72,7 @@ export const whoamiCommand = buildCommand({
           username: user.username ?? null,
           email: user.email ?? null,
         },
-        fields
+        flags.fields
       );
       return;
     }

src/commands/event/view.ts

@@ -22,14 +22,9 @@ import {
 import { openInBrowser } from "../../lib/browser.js";
 import { buildCommand } from "../../lib/command.js";
 import { ContextError, ResolutionError } from "../../lib/errors.js";
-import {
-  formatEventDetails,
-  parseFieldsList,
-  writeJson,
-} from "../../lib/formatters/index.js";
+import { formatEventDetails, writeJson } from "../../lib/formatters/index.js";
 import {
   applyFreshFlag,
-  FIELDS_FLAG,
   FRESH_ALIASES,
   FRESH_FLAG,
 } from "../../lib/list-command.js";
@@ -52,7 +47,7 @@ type ViewFlags = {
   readonly web: boolean;
   readonly spans: number;
   readonly fresh: boolean;
-  readonly fields?: string;
+  readonly fields?: string[];
 };
 
 type HumanOutputOptions = {
@@ -308,6 +303,7 @@ export const viewCommand = buildCommand({
       "  sentry event view <org>/<proj> <event-id> # explicit org and project\n" +
       "  sentry event view <project> <event-id>    # find project across all orgs",
   },
+  output: "json",
   parameters: {
     positional: {
       kind: "array",
@@ -319,19 +315,13 @@ export const viewCommand = buildCommand({
       },
     },
     flags: {
-      json: {
-        kind: "boolean",
-        brief: "Output as JSON",
-        default: false,
-      },
       web: {
         kind: "boolean",
         brief: "Open in browser",
         default: false,
       },
       ...spansFlag,
       fresh: FRESH_FLAG,
-      fields: FIELDS_FLAG,
     },
     aliases: { ...FRESH_ALIASES, w: "web" },
   },
@@ -342,7 +332,6 @@ export const viewCommand = buildCommand({
   ): Promise<void> {
     applyFreshFlag(flags);
     const { stdout, cwd } = this;
-    const fields = flags.fields ? parseFieldsList(flags.fields) : undefined;
 
     const log = logger.withTag("event.view");
 
@@ -396,7 +385,7 @@ export const viewCommand = buildCommand({
       const trace = spanTreeResult?.success
         ? { traceId: spanTreeResult.traceId, spans: spanTreeResult.spans }
         : null;
-      writeJson(stdout, { event, trace }, fields);
+      writeJson(stdout, { event, trace }, flags.fields);
       return;
     }
 

src/commands/issue/explain.ts

@@ -7,18 +7,13 @@
 import type { SentryContext } from "../../context.js";
 import { buildCommand } from "../../lib/command.js";
 import { ApiError } from "../../lib/errors.js";
-import {
-  parseFieldsList,
-  writeFooter,
-  writeJson,
-} from "../../lib/formatters/index.js";
+import { writeFooter, writeJson } from "../../lib/formatters/index.js";
 import {
   formatRootCauseList,
   handleSeerApiError,
 } from "../../lib/formatters/seer.js";
 import {
   applyFreshFlag,
-  FIELDS_FLAG,
   FRESH_ALIASES,
   FRESH_FLAG,
 } from "../../lib/list-command.js";
@@ -33,7 +28,7 @@ type ExplainFlags = {
   readonly json: boolean;
   readonly force: boolean;
   readonly fresh: boolean;
-  readonly fields?: string;
+  readonly fields?: string[];
 };
 
 export const explainCommand = buildCommand({
@@ -64,21 +59,16 @@ export const explainCommand = buildCommand({
       "  sentry issue explain 123456789 --json\n" +
       "  sentry issue explain 123456789 --force",
   },
+  output: "json",
   parameters: {
     positional: issueIdPositional,
     flags: {
-      json: {
-        kind: "boolean",
-        brief: "Output as JSON",
-        default: false,
-      },
       force: {
         kind: "boolean",
         brief: "Force new analysis even if one exists",
         default: false,
       },
       fresh: FRESH_FLAG,
-      fields: FIELDS_FLAG,
     },
     aliases: FRESH_ALIASES,
   },
@@ -89,7 +79,6 @@ export const explainCommand = buildCommand({
   ): Promise<void> {
     applyFreshFlag(flags);
     const { stdout, stderr, cwd } = this;
-    const fields = flags.fields ? parseFieldsList(flags.fields) : undefined;
 
     // Declare org outside try block so it's accessible in catch for error messages
     let resolvedOrg: string | undefined;
@@ -123,7 +112,7 @@ export const explainCommand = buildCommand({
 
       // Output results
       if (flags.json) {
-        writeJson(stdout, causes, fields);
+        writeJson(stdout, causes, flags.fields);
         return;
       }