fix(usage): reject invalid output modes

src/commands/usage.test.ts

@@ -7,6 +7,7 @@
 import { mkdtempSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { Command } from 'commander';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { writeProfile } from '../lib/credentials.js';
 import type { UsageDeps, UsageResponse } from './usage.js';
@@ -310,4 +311,21 @@ describe('createUsageCommand wiring', () => {
     // Commander's helpInformation() includes the command description.
     expect(helpText).toContain('credit balance');
   });
+
+  it('rejects unsupported global --output modes instead of falling back to text', async () => {
+    const root = new Command('testsprite')
+      .exitOverride()
+      .option('--output <mode>', 'Output format (json|text)', 'text')
+      .option('--dry-run', 'Skip the network and emit a canned response', false);
+
+    root.addCommand(createUsageCommand(makeCapture().deps));
+
+    await expect(
+      root.parseAsync(['usage', '--output', 'yaml', '--dry-run'], { from: 'user' }),
+    ).rejects.toMatchObject({
+      code: 'VALIDATION_ERROR',
+      exitCode: 5,
+      details: { field: 'output' },
+    });
+  });
 });

src/commands/usage.ts

@@ -20,6 +20,7 @@ import {
   type CommonOptions as FactoryCommonOptions,
 } from '../lib/client-factory.js';
 import { loadConfig } from '../lib/config.js';
+import { localValidationError } from '../lib/errors.js';
 import { resolvePortalBase } from '../lib/facade.js';
 import type { FetchImpl } from '../lib/http.js';
 import { GLOBAL_OPTS_HINT, Output, type OutputMode } from '../lib/output.js';
@@ -214,9 +215,13 @@ function resolveCommonOptions(command: Command): CommonOptions {
   const globals = command.optsWithGlobals() as Partial<CommonOptions> & {
     requestTimeout?: string;
   };
+  const rawOutput = globals.output;
+  if (rawOutput !== undefined && rawOutput !== 'json' && rawOutput !== 'text') {
+    throw localValidationError('output', 'must be one of: json, text', ['json', 'text']);
+  }
   return {
     profile: globals.profile ?? 'default',
-    output: globals.output ?? 'text',
+    output: (globals.output as OutputMode | undefined) ?? 'text',
     endpointUrl: globals.endpointUrl,
     debug: globals.debug ?? false,
     verbose: globals.verbose ?? false,