feat: add hidden --org/--project global flags for LLM compatibility (#856)

## Summary
- Add hidden `--org` and `--project` global flags that silently map to
`SENTRY_ORG` / `SENTRY_PROJECT` env vars, recovering from the most
common LLM-generated error pattern (old `sentry-cli` syntax)
- Flags are injected into every command via the existing global-flags
infrastructure, stripped before `func()` runs, and not shown in `--help`
- Commands that define their own `--org` or `--project` (e.g. `release
create --project`) keep their own semantics — the compat shim skips
injection

## Motivation

LLMs trained on the older Rust-based `sentry-cli` consistently generate
commands like:

```
sentry issue list --org sentry --project cli
```

Instead of showing a confusing "No flag registered for --org" error, we
silently accept these flags and let the existing resolution chain handle
the values.

## Design decisions

- **No short aliases** (`-o`, `-p`): `-p` conflicts with `release create
-p project`. Omit both for consistency. LLMs generate long-form anyway.
- **Flags overwrite env vars**: `--org sentry` wins over
`SENTRY_ORG=other` because explicit CLI flags are highest-priority user
intent.
- **`log.debug()` only**: silent compat shim, not a deprecation warning.
- **Refactored `mergeGlobalFlags()`**: extracted flag-merging logic to
keep `buildCommand` under Biome's cognitive complexity limit.

Author: BYK

AGENTS.md

@@ -38,6 +38,7 @@ import {
 } from "@stricli/core";
 import type { Writer } from "../types/index.js";
 import { getAuthConfig } from "./db/auth.js";
+import { getEnv } from "./env.js";
 import { AuthError, CliError, OutputError } from "./errors.js";
 import { warning } from "./formatters/colors.js";
 import { parseFieldsList } from "./formatters/json.js";
@@ -58,6 +59,7 @@ import { GLOBAL_FLAGS } from "./global-flags.js";
 import {
   LOG_LEVEL_NAMES,
   type LogLevelName,
+  logger,
   parseLogLevel,
   setLogLevel,
 } from "./logger.js";
@@ -238,6 +240,40 @@ export const FIELDS_FLAG = {
   optional: true as const,
 } as const;
 
+// ---------------------------------------------------------------------------
+// Hidden org/project compat flags (LLM error recovery)
+// ---------------------------------------------------------------------------
+
+/**
+ * Hidden `--org` flag injected into every command by {@link buildCommand}.
+ *
+ * Backward-compatibility shim for the older `sentry-cli` that accepted
+ * `--org` on every command. LLMs trained on the old CLI generate this flag.
+ * The value is written to `SENTRY_ORG` so the existing resolution chain
+ * in `resolve-target.ts` picks it up at priority #2 (env vars).
+ */
+const ORG_FLAG = {
+  kind: "parsed" as const,
+  parse: String,
+  brief: "Organization slug",
+  optional: true as const,
+  hidden: true as const,
+} as const;
+
+/**
+ * Hidden `--project` flag injected into every command by {@link buildCommand}.
+ *
+ * Same backward-compatibility shim as `--org`. Written to `SENTRY_PROJECT`
+ * before the command's `func` runs.
+ */
+const PROJECT_FLAG = {
+  kind: "parsed" as const,
+  parse: String,
+  brief: "Project slug",
+  optional: true as const,
+  hidden: true as const,
+} as const;
+
 /** The flag key for the injected --log-level flag (always stripped) */
 const LOG_LEVEL_KEY = "log-level";
 
@@ -261,6 +297,44 @@ export function applyLoggingFlags(
   }
 }
 
+const orgProjectLog = logger.withTag("compat-flags");
+
+/**
+ * Write `--org` / `--project` flag values to environment variables.
+ *
+ * Called by the {@link buildCommand} wrapper before the command's `func()`
+ * runs. The values are written to `SENTRY_ORG` and `SENTRY_PROJECT` so
+ * the existing resolution chain in `resolve-target.ts` picks them up at
+ * priority #2 (env vars). Overwrites existing env vars because explicit
+ * CLI flags are highest-priority user intent.
+ *
+ * Empty and whitespace-only values are treated as "not provided" — they
+ * fall through to the rest of the resolution chain rather than overwriting
+ * a real pre-existing env var with garbage. This matters for LLM-generated
+ * commands that occasionally emit `--org ""` or stray whitespace.
+ *
+ * Skipped when the command defines its own `--org` / `--project` flag
+ * (e.g., `release create --project`) — those are passed through to `func()`.
+ */
+export function applyOrgProjectFlags(
+  org: string | undefined,
+  project: string | undefined,
+  commandOwnsOrg: boolean,
+  commandOwnsProject: boolean
+): void {
+  const env = getEnv();
+  const orgTrimmed = org?.trim();
+  const projectTrimmed = project?.trim();
+  if (orgTrimmed && !commandOwnsOrg) {
+    orgProjectLog.debug(`--org flag → SENTRY_ORG=${orgTrimmed}`);
+    env.SENTRY_ORG = orgTrimmed;
+  }
+  if (projectTrimmed && !commandOwnsProject) {
+    orgProjectLog.debug(`--project flag → SENTRY_PROJECT=${projectTrimmed}`);
+    env.SENTRY_PROJECT = projectTrimmed;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // buildCommand — the single entry point for all Sentry CLI commands
 // ---------------------------------------------------------------------------
@@ -342,6 +416,70 @@ function enrichDocsWithSchema(
   };
 }
 
+/**
+ * Global flag defaults keyed by flag name.
+ * Used by {@link mergeGlobalFlags} to inject flags when the command
+ * doesn't define its own.
+ */
+const GLOBAL_FLAG_DEFAULTS: Record<string, unknown> = {
+  [LOG_LEVEL_KEY]: LOG_LEVEL_FLAG,
+  verbose: VERBOSE_FLAG,
+  org: ORG_FLAG,
+  project: PROJECT_FLAG,
+};
+
+/** Flags that are always stripped (command never sees them). */
+const ALWAYS_STRIP = new Set([LOG_LEVEL_KEY]);
+
+/**
+ * Merge global flags into a command's existing flags.
+ *
+ * For each global flag, if the command doesn't already define it, the
+ * default shape is injected and its key is added to the returned
+ * `stripKeys` set (so the wrapper strips it before calling `func`).
+ *
+ * @returns The merged flags, ownership booleans, and keys to strip.
+ */
+function mergeGlobalFlags(
+  existingFlags: Record<string, unknown>,
+  // biome-ignore lint/suspicious/noExplicitAny: OutputConfig type is erased at the builder level
+  outputConfig?: OutputConfig<any>
+): {
+  mergedFlags: Record<string, unknown>;
+  commandOwnsOrg: boolean;
+  commandOwnsProject: boolean;
+  stripKeys: Set<string>;
+} {
+  const commandOwnsJson = "json" in existingFlags;
+  const commandOwnsOrg = "org" in existingFlags;
+  const commandOwnsProject = "project" in existingFlags;
+
+  const mergedFlags: Record<string, unknown> = { ...existingFlags };
+  const stripKeys = new Set<string>(ALWAYS_STRIP);
+
+  for (const [name, shape] of Object.entries(GLOBAL_FLAG_DEFAULTS)) {
+    if (!(name in existingFlags)) {
+      mergedFlags[name] = shape;
+      stripKeys.add(name);
+    }
+  }
+
+  // Inject --json and --fields when output config is set
+  if (outputConfig) {
+    if (!commandOwnsJson) {
+      mergedFlags.json = JSON_FLAG;
+    }
+    mergedFlags.fields = buildFieldsFlag(outputConfig);
+  }
+
+  return {
+    mergedFlags,
+    commandOwnsOrg,
+    commandOwnsProject,
+    stripKeys,
+  };
+}
+
 export function buildCommand<
   const FLAGS extends BaseFlags = NonNullable<unknown>,
   const ARGS extends BaseArgs = [],
@@ -354,34 +492,15 @@ export function buildCommand<
   const requiresAuth = builderArgs.auth !== false;
   const skipRcUrlCheck = builderArgs.skipRcUrlCheck === true;
 
-  // Merge logging flags into the command's flag definitions.
-  // Quoted keys produce kebab-case CLI flags: "log-level" → --log-level
+  // Merge global flags into the command's flag definitions.
   const existingParams = (builderArgs.parameters ?? {}) as Record<
     string,
     unknown
   >;
   const existingFlags = (existingParams.flags ?? {}) as Record<string, unknown>;
 
-  // If the command already defines --verbose (e.g. api command), don't override it.
-  const commandOwnsVerbose = "verbose" in existingFlags;
-  // If the command already defines --json (e.g. custom brief), don't override it.
-  const commandOwnsJson = "json" in existingFlags;
-
-  const mergedFlags: Record<string, unknown> = {
-    ...existingFlags,
-    [LOG_LEVEL_KEY]: LOG_LEVEL_FLAG,
-  };
-  if (!commandOwnsVerbose) {
-    mergedFlags.verbose = VERBOSE_FLAG;
-  }
-
-  // Inject --json and --fields when output config is set
-  if (outputConfig) {
-    if (!commandOwnsJson) {
-      mergedFlags.json = JSON_FLAG;
-    }
-    mergedFlags.fields = buildFieldsFlag(outputConfig);
-  }
+  const { mergedFlags, commandOwnsOrg, commandOwnsProject, stripKeys } =
+    mergeGlobalFlags(existingFlags, outputConfig);
 
   // Enrich fullDescription with JSON fields when schema is registered.
   // This makes field info visible in Stricli's --help output.
@@ -443,19 +562,16 @@ export function buildCommand<
 
   /**
    * Strip injected flags from the raw Stricli-parsed flags object.
-   * --log-level is always stripped. --verbose is stripped only when we
-   * injected it (not when the command defines its own). --fields is
-   * pre-parsed from comma-string to string[] when output: { human: ... }.
+   * Global flags we injected (tracked in `stripKeys` from
+   * {@link mergeGlobalFlags}) are removed. --fields is pre-parsed from
+   * comma-string to string[] when output: { human: ... }.
    */
   function cleanRawFlags(
     raw: Record<string, unknown>
   ): Record<string, unknown> {
     const clean: Record<string, unknown> = {};
     for (const [key, value] of Object.entries(raw)) {
-      if (key === LOG_LEVEL_KEY) {
-        continue;
-      }
-      if (key === "verbose" && !commandOwnsVerbose) {
+      if (stripKeys.has(key)) {
         continue;
       }
       clean[key] = value;
@@ -558,6 +674,15 @@ export function buildCommand<
       flags.verbose as boolean
     );
 
+    // Map --org / --project compat flags to env vars before anything
+    // else reads them (auth guard, org/project resolution, etc.)
+    applyOrgProjectFlags(
+      flags.org as string | undefined,
+      flags.project as string | undefined,
+      commandOwnsOrg,
+      commandOwnsProject
+    );
+
     const cleanFlags = cleanRawFlags(flags as Record<string, unknown>);
     setFlagContext(cleanFlags);
     if (args.length > 0) {

src/lib/command.ts

@@ -40,4 +40,10 @@ export const GLOBAL_FLAGS: readonly GlobalFlagDef[] = [
   { name: "log-level", short: null, kind: "value" },
   { name: "json", short: null, kind: "boolean" },
   { name: "fields", short: null, kind: "value" },
+  // Hidden compat shims: LLMs trained on the older sentry-cli generate
+  // `--org` and `--project` flags. We silently accept them and map to
+  // SENTRY_ORG / SENTRY_PROJECT env vars so the resolution chain handles them.
+  // No short aliases: -p conflicts with release create's -p (--project).
+  { name: "org", short: null, kind: "value" },
+  { name: "project", short: null, kind: "value" },
 ];

src/lib/global-flags.ts

@@ -21,6 +21,8 @@ const GLOBAL_FLAG_TOKENS = [
   "-v",
   "--log-level",
   "--fields",
+  "--org",
+  "--project",
 ] as const;
 
 /** Tokens that should never be hoisted */
@@ -62,6 +64,8 @@ const HOISTABLE_SET = new Set([
   "-v",
   "--log-level",
   "--fields",
+  "--org",
+  "--project",
 ]);
 
 function isHoistableToken(token: string): boolean {
@@ -120,7 +124,12 @@ describe("property: hoistGlobalFlags", () => {
 
   test("hoisted tokens appear after all non-hoisted tokens", () => {
     /** Value-taking flags whose next token also gets hoisted */
-    const VALUE_TAKING = new Set(["--log-level", "--fields"]);
+    const VALUE_TAKING = new Set([
+      "--log-level",
+      "--fields",
+      "--org",
+      "--project",
+    ]);
 
     fcAssert(
       property(argvArb, (argv) => {

test/lib/argv-hoist.property.test.ts

@@ -176,6 +176,58 @@ describe("hoistGlobalFlags", () => {
     ]);
   });
 
+  // -------------------------------------------------------------------------
+  // Value flag: --org (compat)
+  // -------------------------------------------------------------------------
+
+  test("hoists --org with separate value", () => {
+    expect(hoistGlobalFlags(["--org", "sentry", "issue", "list"])).toEqual([
+      "issue",
+      "list",
+      "--org",
+      "sentry",
+    ]);
+  });
+
+  test("hoists --org=sentry as single token", () => {
+    expect(hoistGlobalFlags(["--org=sentry", "issue", "list"])).toEqual([
+      "issue",
+      "list",
+      "--org=sentry",
+    ]);
+  });
+
+  // -------------------------------------------------------------------------
+  // Value flag: --project (compat)
+  // -------------------------------------------------------------------------
+
+  test("hoists --project with separate value", () => {
+    expect(hoistGlobalFlags(["--project", "cli", "issue", "list"])).toEqual([
+      "issue",
+      "list",
+      "--project",
+      "cli",
+    ]);
+  });
+
+  test("hoists --project=cli as single token", () => {
+    expect(hoistGlobalFlags(["--project=cli", "issue", "list"])).toEqual([
+      "issue",
+      "list",
+      "--project=cli",
+    ]);
+  });
+
+  // -------------------------------------------------------------------------
+  // Combined: --org + --project (compat)
+  // -------------------------------------------------------------------------
+
+  test("hoists --org and --project together", () => {
+    expect(
+      hoistGlobalFlags(["--org", "sentry", "--project", "cli", "issue", "list"])
+    ).toEqual(["issue", "list", "--org", "sentry", "--project", "cli"]);
+  });
+
   // -------------------------------------------------------------------------
   // Multiple flags
   // -------------------------------------------------------------------------