@brass-build/cli 0.1.0 → 0.3.0

package/src/api.ts

@@ -34,6 +34,10 @@ export interface HostingStatus {
   // Whether the edge gates the bundle behind the app's audience. A public
   // showcase turns this off so the bundle is world-loadable.
   require_access?: boolean;
+  // Whether the platform has registered this slot to serve. False means the
+  // hosted URL answers 404 however the rest of this body reads. Optional: an
+  // older api omits it, and an absent field is not a failure to report.
+  gate_settled?: boolean;
 }
 
 export interface HostingUploadUrl {
@@ -110,6 +114,28 @@ export class BrassApiError extends Error {
   }
 }
 
+// `fetch` carries no timeout of its own, so a host that accepts the connection
+// and then answers nothing holds the command open for as long as the caller
+// leaves it running. In CI that is a job that never finishes rather than a
+// failure anyone can read, so every request the CLI makes is bounded.
+const REQUEST_TIMEOUT_MS = 30_000;
+// The upload carries the whole bundle, so it is bounded far more loosely than
+// a request that carries a few hundred bytes.
+const UPLOAD_TIMEOUT_MS = 300_000;
+
+/** A failed fetch as the caller should read it, naming a timeout as one. */
+export function networkError(what: string, cause: unknown): BrassApiError {
+  const timedOut =
+    cause instanceof Error &&
+    (cause.name === 'TimeoutError' || cause.name === 'AbortError');
+  return new BrassApiError(
+    0,
+    timedOut
+      ? `Timed out ${what}.`
+      : `Network error ${what}: ${String(cause)}`,
+  );
+}
+
 export class BrassApi {
   private readonly apiBaseUrl: string;
   private readonly auth: AuthProvider;
@@ -132,7 +158,7 @@ export class BrassApi {
   private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
     const headers: Record<string, string> = {
       ...(await this.auth.headers()),
-      // Version telemetry; the api Lambda logs it so pinned CI copies
+      // Version telemetry; the platform logs it so pinned CI copies
       // stay visible in the deployed-version distribution.
       'x-brass-client': CLI_CLIENT_ID,
     };
@@ -143,9 +169,12 @@ export class BrassApi {
     }
     let response: Response;
     try {
-      response = await fetch(`${this.apiBaseUrl}${path}`, init);
+      response = await fetch(`${this.apiBaseUrl}${path}`, {
+        ...init,
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      });
     } catch (cause) {
-      throw new BrassApiError(0, `Network error reaching ${this.apiBaseUrl}: ${String(cause)}`);
+      throw networkError(`reaching ${this.apiBaseUrl}`, cause);
     }
     if (!response.ok) {
       throw new BrassApiError(response.status, await errorMessage(response));
@@ -155,10 +184,10 @@ export class BrassApi {
   }
 }
 
-// Upload bytes to a presigned S3 URL. Deliberately carries NO Brass headers
-// and no bearer: the presigned signature pins an exact header set, and a
-// stray `authorization` header would break it (the same rule the SDK's
-// `api-headers` module enforces on the document path).
+// Upload bytes to the presigned storage URL the platform handed back.
+// Deliberately carries NO Brass headers and no bearer: the presigned
+// signature pins an exact header set, so a stray `authorization` header
+// invalidates it and the upload is refused.
 export async function putPresigned(
   url: string,
   bytes: Uint8Array,
@@ -173,9 +202,10 @@ export async function putPresigned(
       // `ArrayBufferLike` is sound and satisfies fetch's `BufferSource`
       // (which pins `ArrayBufferView<ArrayBuffer>`) across lib configs.
       body: bytes as Uint8Array<ArrayBuffer>,
+      signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS),
     });
   } catch (cause) {
-    throw new BrassApiError(0, `Network error uploading the bundle: ${String(cause)}`);
+    throw networkError('uploading the bundle', cause);
   }
   if (!response.ok) {
     throw new BrassApiError(response.status, `Bundle upload failed (${response.status})`);

package/src/args.ts

@@ -7,13 +7,16 @@ export interface ParsedArgs {
   // A flag present with no value (`--json`) stores `true`; a valued flag
   // (`--doc abc` / `--doc=abc`) stores the string.
   flags: Record<string, string | true>;
+  // Boolean flags written with a value (`--json=false`). A boolean flag is on
+  // by being present, so any value behind one contradicts the flag itself, and
+  // the reading a caller expects is the opposite of the one it would get.
+  valuedBooleans: string[];
 }
 
-// Flags that never take a value, so `brass publish --yes ./dist` parses
-// `./dist` as a positional rather than the value of `--yes`.
+// Flags that never take a value, so `brass agents pull --stdout ./dir` parses
+// `./dir` as a positional rather than the value of `--stdout`.
 const BOOLEAN_FLAGS = new Set([
   'json',
-  'yes',
   'help',
   'version',
   'stdout',
@@ -52,18 +55,102 @@ export function unknownFlags(parsed: ParsedArgs): string[] {
   return Object.keys(parsed.flags).filter((name) => !KNOWN_FLAGS.has(name));
 }
 
+// The flags every command reads, whichever it is: where to talk to and what
+// to print.
+const COMMON_FLAGS = [
+  'api-url',
+  'auth-url',
+  'dashboard-url',
+  'help',
+  'json',
+  'version',
+] as const;
+
+// What each command reads beyond those, and how many positionals it takes
+// (the command word included, so `publish [dir]` is 2). A flag one command
+// reads is not thereby a flag of the next: `--wait` is the sign-in poll's
+// deadline and `publish` has its own, so `brass publish --wait 600` waits
+// exactly as long as it would have without the flag. Refusing it names the
+// mistake, where accepting it leaves the caller believing they set something.
+const COMMAND_ARGS: Record<string, { flags: readonly string[]; positionals: number }> = {
+  login: { flags: ['check', 'new', 'start', 'wait'], positionals: 1 },
+  logout: { flags: [], positionals: 1 },
+  status: { flags: ['app', 'manifest', 'token'], positionals: 2 },
+  publish: {
+    flags: [
+      'app',
+      'client-token',
+      'gate',
+      'manifest',
+      'name',
+      'org',
+      'slug',
+      'token',
+      'visibility',
+    ],
+    positionals: 2,
+  },
+  schema: { flags: ['doc', 'out', 'token'], positionals: 2 },
+  agents: { flags: ['org', 'out', 'stdout', 'token'], positionals: 2 },
+  whoami: { flags: ['token'], positionals: 1 },
+};
+
+// The flags `command` does not read, out of the ones this CLI knows. A name
+// the CLI knows nowhere is `unknownFlags`' answer and stays there, so a
+// misspelling is reported as one rather than as a flag of another command.
+// A command this CLI does not have answers for itself.
+export function flagsNotReadBy(parsed: ParsedArgs, command: string): string[] {
+  const spec = COMMAND_ARGS[command];
+  if (spec === undefined) return [];
+  const reads = new Set<string>([...COMMON_FLAGS, ...spec.flags]);
+  return Object.keys(parsed.flags).filter(
+    (name) => KNOWN_FLAGS.has(name) && !reads.has(name),
+  );
+}
+
+// The positionals past the ones `command` reads. An ignored one is the same
+// silence a flag no command reads leaves: `brass publish out dist` publishes
+// `out`, and the caller who meant `dist` is told nothing.
+export function extraPositionals(parsed: ParsedArgs, command: string): string[] {
+  const spec = COMMAND_ARGS[command];
+  if (spec === undefined) return [];
+  return parsed.positionals.slice(spec.positionals);
+}
+
+// The flags of `command` that carry a value, so a bare one is the caller
+// naming something the run then resolves a default for. `--wait` is absent
+// here because a bare `--wait` is its own answer (the default deadline).
+export function valueFlagsOf(command: string): string[] {
+  const spec = COMMAND_ARGS[command];
+  if (spec === undefined) return [];
+  return [...COMMON_FLAGS, ...spec.flags].filter(
+    (name) => !BOOLEAN_FLAGS.has(name) && name !== 'wait',
+  );
+}
+
 // Which of `names` were given without a value (`--api-url --json`, or
 // `--api-url` last on the line). The parser stores those as `true` and
 // `stringFlag` reads that as absent, so an origin flag in this state resolves
 // the production default while the command line names another stack. That is
 // the same silent retarget `unknownFlags` catches for a misspelled name.
+//
+// An EMPTY value counts, and it is the shape a caller actually reaches: a
+// script writing `--slug "$SLUG"` against an unset variable passes the flag
+// with nothing behind it. That value is not absent the way a bare flag is, so
+// it resolves no default and travels to the server as an empty string, where
+// the mistake is reported (if at all) in the server's vocabulary rather than
+// as the missing value it is.
 export function valuelessFlags(parsed: ParsedArgs, names: readonly string[]): string[] {
-  return names.filter((name) => parsed.flags[name] === true);
+  return names.filter((name) => {
+    const value = parsed.flags[name];
+    return value === true || value === '';
+  });
 }
 
 export function parseArgs(argv: readonly string[]): ParsedArgs {
   const positionals: string[] = [];
   const flags: Record<string, string | true> = {};
+  const valuedBooleans: string[] = [];
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === undefined) continue;
@@ -71,7 +158,16 @@ export function parseArgs(argv: readonly string[]): ParsedArgs {
       const body = arg.slice(2);
       const eq = body.indexOf('=');
       if (eq !== -1) {
-        flags[body.slice(0, eq)] = body.slice(eq + 1);
+        const name = body.slice(0, eq);
+        if (BOOLEAN_FLAGS.has(name)) {
+          // Recorded rather than read: `--json=false` reads as ON, which is
+          // the reverse of what the caller wrote, and `--stdout=false` would
+          // send a file's contents to stdout and write nothing.
+          valuedBooleans.push(name);
+          flags[name] = true;
+          continue;
+        }
+        flags[name] = body.slice(eq + 1);
         continue;
       }
       if (BOOLEAN_FLAGS.has(body)) {
@@ -89,7 +185,7 @@ export function parseArgs(argv: readonly string[]): ParsedArgs {
       positionals.push(arg);
     }
   }
-  return { positionals, flags };
+  return { positionals, flags, valuedBooleans };
 }
 
 // Read a flag expected to carry a string value; a bare boolean flag (no

package/src/cli.ts

@@ -6,7 +6,10 @@ import {
   parseArgs,
   stringFlag,
   boolFlag,
+  extraPositionals,
+  flagsNotReadBy,
   unknownFlags,
+  valueFlagsOf,
   valuelessFlags,
   type ParsedArgs,
 } from './args.js';
@@ -18,10 +21,15 @@ import {
   type Origins,
   type Profile,
 } from './config.js';
-import { readCredentialsFile, readPendingLogin, writeStoredCredential } from './store.js';
+import {
+  readCredentialsFile,
+  readPendingLogin,
+  writePendingLogin,
+  writeStoredCredential,
+} from './store.js';
 import { BrassApi, BrassApiError, type AppVisibility } from './api.js';
 import { serviceTokenAuth, type AuthProvider } from './auth.js';
-import { loginDevice, sessionAuth } from './session.js';
+import { loginDevice, postDeviceCancel, postSignOut, sessionAuth } from './session.js';
 import { loginStart, loginCheck } from './login.js';
 import { createLogger, type Logger } from './log.js';
 import {
@@ -31,6 +39,7 @@ import {
   whoami,
   status,
   type CommandContext,
+  type CredentialKind,
 } from './commands.js';
 import { readProjectState, resolveAppId, readManifest } from './project.js';
 
@@ -47,7 +56,7 @@ Usage:
   brass login --check        Check a started sign-in once; stores the session when approved.
                              --wait [seconds] polls until approved (default 120s), renewing
                              an expired code in place and printing the new one.
-  brass logout               Forget the stored sign-in for this environment.
+  brass logout               End the stored sign-in for this environment, here and on the server.
   brass status [dir]         Report the credential + app state and the one command to run next.
   brass publish [dir]        Build output in [dir] (default: dist) is deployed to the app's hosting.
   brass schema pull --doc <docId> [--out brass-app.json]
@@ -82,8 +91,15 @@ Publish flags:
 export async function run(argv: readonly string[]): Promise<number> {
   const parsed = parseArgs(argv);
   const command = parsed.positionals[0];
-
-  if (boolFlag(parsed, 'version') && command === undefined) {
+  // Which credential the invocation resolved, once it has. A 401 is reported
+  // in that credential's own vocabulary, so it stays undefined until
+  // `buildContext` settles it and a failure before then carries no guess.
+  let credentialKind: CredentialKind | undefined;
+
+  // Answered whichever command follows, like `--help` beside it: both are
+  // declared flags of every command (`COMMON_FLAGS`), so a caller who asks
+  // which version is installed gets the answer rather than a publish.
+  if (boolFlag(parsed, 'version')) {
     process.stdout.write(`${VERSION}\n`);
     return 0;
   }
@@ -103,6 +119,41 @@ export async function run(argv: readonly string[]): Promise<number> {
     return 1;
   }
 
+  // Then what THIS command reads, which is the same check one scope in: a
+  // flag or a positional the command ignores leaves the run differing from
+  // what the command line asked for, with nothing said. Judged from argv
+  // alone, so it answers a caller who has not signed in.
+  const misplaced = flagsNotReadBy(parsed, command);
+  if (misplaced.length > 0) {
+    const names = misplaced.map((n) => `--${n}`).join(', ');
+    process.stderr.write(
+      `error: ${names} ${misplaced.length === 1 ? 'is not a flag' : 'are not flags'} of \`brass ${command}\`\n\n${USAGE}`,
+    );
+    return 1;
+  }
+  const extra = extraPositionals(parsed, command);
+  if (extra.length > 0) {
+    const args = extra.map((p) => JSON.stringify(p)).join(', ');
+    process.stderr.write(
+      `error: unexpected ${extra.length === 1 ? 'argument' : 'arguments'} ${args} for \`brass ${command}\`\n\n${USAGE}`,
+    );
+    return 1;
+  }
+  if (parsed.valuedBooleans.length > 0) {
+    const names = parsed.valuedBooleans.map((n) => `--${n}`).join(', ');
+    process.stderr.write(
+      `error: ${names} ${parsed.valuedBooleans.length === 1 ? 'takes' : 'take'} no value\n`,
+    );
+    return 1;
+  }
+  const bare = valuelessFlags(parsed, valueFlagsOf(command));
+  if (bare.length > 0) {
+    process.stderr.write(
+      `error: Missing value for ${bare.map((n) => `--${n}`).join(', ')}\n`,
+    );
+    return 1;
+  }
+
   const json = boolFlag(parsed, 'json');
   const log = createLogger(json);
 
@@ -115,32 +166,63 @@ export async function run(argv: readonly string[]): Promise<number> {
     // (and the next step to obtain one) is a first-class outcome, not an error.
     if (command === 'status') return await runStatus(parsed, log);
 
-    const ctx = await buildContext(parsed);
-    switch (command) {
-      case 'publish':
-        log.result(await runPublish(ctx, parsed));
-        return 0;
-      case 'schema':
-        log.result(await runSchema(ctx, parsed));
-        return 0;
-      case 'agents':
-        log.result(await runAgents(ctx, parsed));
-        return 0;
-      case 'whoami':
-        log.result(await whoami(ctx));
-        return 0;
-      default:
-        process.stderr.write(`Unknown command "${command}".\n\n${USAGE}`);
-        return 1;
+    // What the caller asked for is decided from argv alone, so it is decided
+    // BEFORE a credential is resolved. A misspelt command, a missing
+    // subcommand and an invalid flag value are all answerable without one, and
+    // resolving the credential first answers every one of them with "No
+    // credential. Run `brass login`": the caller re-authenticates over a typo,
+    // and only a caller who already has a credential is ever shown the message
+    // naming the real mistake.
+    if (!isCredentialedCommand(command)) {
+      process.stderr.write(`Unknown command "${command}".\n\n${USAGE}`);
+      return 1;
     }
+    const plan = planCommand(command, parsed);
+
+    const ctx = await buildContext(parsed);
+    credentialKind = ctx.credentialKind;
+    log.result(await plan(ctx));
+    return 0;
   } catch (err) {
-    process.stderr.write(`${formatError(err)}\n`);
+    process.stderr.write(`${formatError(err, credentialKind)}\n`);
     return 1;
   }
 }
 
 type Context = CommandContext;
 
+// The commands that need a resolved credential; `login` / `logout` / `status`
+// are answered above without one.
+const CREDENTIALED_COMMANDS = ['publish', 'schema', 'agents', 'whoami'] as const;
+type CredentialedCommand = (typeof CREDENTIALED_COMMANDS)[number];
+
+function isCredentialedCommand(value: string): value is CredentialedCommand {
+  return (CREDENTIALED_COMMANDS as readonly string[]).includes(value);
+}
+
+// The work a command will do once it has a credential.
+type CommandPlan = (ctx: Context) => Promise<unknown>;
+
+// Resolve argv to that work, validating everything argv alone decides and
+// throwing on a shape the caller got wrong. Splitting the plan from the run is
+// what lets the shape be judged before a credential is resolved.
+function planCommand(command: CredentialedCommand, parsed: ParsedArgs): CommandPlan {
+  switch (command) {
+    case 'publish':
+      return planPublish(parsed);
+    case 'schema':
+      return planSchema(parsed);
+    case 'agents':
+      return planAgents(parsed);
+    case 'whoami':
+      return (ctx): Promise<unknown> => whoami(ctx);
+    default: {
+      const exhaustive: never = command;
+      throw new Error(`Unhandled command "${String(exhaustive)}"`);
+    }
+  }
+}
+
 interface Base {
   origins: Origins;
   profile: Profile;
@@ -226,6 +308,7 @@ async function runLogin(parsed: ParsedArgs, log: Logger): Promise<number> {
       profile,
       log,
       ...(boolFlag(parsed, 'new') ? { force: true } : {}),
+      ...(waitSeconds !== undefined ? { resultFollows: true } : {}),
     });
     // `--start --wait` is the whole sign-in in one command: relay the code it
     // prints, then it holds for the approval up to the deadline.
@@ -238,18 +321,55 @@ async function runLogin(parsed: ParsedArgs, log: Logger): Promise<number> {
   // The RFC 8628 device grant: open the approval page (code prefilled), print
   // the URL + code as a fallback for a headless box, and poll until approval.
   const result = await loginDevice({ authBaseUrl: origins.authBaseUrl });
-  await writeStoredCredential(profile, { session: { sid: result.sessionToken } });
+  await writeStoredCredential(profile, {
+    session: { sid: result.sessionToken, authBaseUrl: origins.authBaseUrl },
+  });
   log.success(result.email ? `Signed in as ${result.email}.` : 'Signed in.');
   log.result({ signed_in: true, ...(result.email !== undefined ? { email: result.email } : {}) });
   return 0;
 }
 
 async function runLogout(parsed: ParsedArgs, log: Logger): Promise<number> {
-  const { profile } = resolveBase(parsed);
-  await writeStoredCredential(profile, null);
-  log.success('Signed out.');
-  log.result({ signed_out: true });
-  return 0;
+  const { origins, profile } = resolveBase(parsed);
+
+  // Revoke on the server first, while the pointer is still readable. A
+  // service token belongs to an organization and is revoked in the dashboard,
+  // so only a stored session has anything to end here. The session is revoked
+  // on the auth origin it was minted on: profiles key on the api host, so the
+  // invocation's own auth flag can name a different stack, where an unknown
+  // pointer reads as already-signed-out and the real session stays live.
+  const file = await readCredentialsFile();
+  const session = file?.credentials[profile]?.session;
+  const signedOut =
+    session === undefined
+      ? true
+      : await postSignOut(session.authBaseUrl ?? origins.authBaseUrl, session.sid);
+
+  // A started sign-in is redeemable by whoever holds the device code, and a
+  // human may still approve it after this command returns, so cancelling it on
+  // the server is what a sign-out owes. The grant, too, is cancelled on the
+  // auth origin that minted it.
+  const pending = await readPendingLogin(profile);
+  const cancelled =
+    pending === null ? true : await postDeviceCancel(pending.authBaseUrl, pending.deviceCode);
+
+  // Each record is dropped only once its server side is revoked. The record
+  // is the one handle that can name the session or grant to the server, so a
+  // failed delivery keeps it, which is what makes the retry this command
+  // recommends able to revoke anything.
+  if (signedOut) await writeStoredCredential(profile, null);
+  if (cancelled) await writePendingLogin(profile, null);
+  const revoked = signedOut && cancelled;
+
+  if (revoked) {
+    log.success('Signed out.');
+  } else {
+    log.warn(
+      'Brass could not be reached to revoke the sign-in, so it is kept on this machine. Run `brass logout` again when Brass is reachable.',
+    );
+  }
+  log.result({ signed_out: revoked, revoked });
+  return revoked ? 0 : 1;
 }
 
 async function runStatus(parsed: ParsedArgs, log: Logger): Promise<number> {
@@ -317,7 +437,7 @@ async function runStatus(parsed: ParsedArgs, log: Logger): Promise<number> {
   return 0;
 }
 
-async function runPublish(ctx: Context, parsed: ParsedArgs): Promise<unknown> {
+function planPublish(parsed: ParsedArgs): CommandPlan {
   const dir = parsed.positionals[1] ?? 'dist';
   const flagApp = stringFlag(parsed, 'app');
   const envApp = process.env['BRASS_APP_ID'];
@@ -325,26 +445,29 @@ async function runPublish(ctx: Context, parsed: ParsedArgs): Promise<unknown> {
   const org = stringFlag(parsed, 'org');
   const slug = stringFlag(parsed, 'slug');
   const clientToken = stringFlag(parsed, 'client-token');
+  const manifestPath = stringFlag(parsed, 'manifest') ?? 'brass-app.json';
   const visibility = parseVisibilityFlag(stringFlag(parsed, 'visibility'));
   const requireAccess = parseGateFlag(stringFlag(parsed, 'gate'));
-  const state = await readProjectState(ctx.cwd);
-  const appId = resolveAppId({
-    ...(flagApp !== undefined ? { flagApp } : {}),
-    ...(envApp !== undefined ? { envApp } : {}),
-    state,
-    profile: ctx.profile,
-  });
-  return publish(ctx, {
-    dir,
-    manifestPath: stringFlag(parsed, 'manifest') ?? 'brass-app.json',
-    ...(appId !== null ? { appId } : {}),
-    ...(name !== undefined ? { name } : {}),
-    ...(org !== undefined ? { organizationId: org } : {}),
-    ...(clientToken !== undefined ? { clientToken } : {}),
-    ...(slug !== undefined ? { slug } : {}),
-    ...(visibility !== undefined ? { visibility } : {}),
-    ...(requireAccess !== undefined ? { requireAccess } : {}),
-  });
+  return async (ctx): Promise<unknown> => {
+    const state = await readProjectState(ctx.cwd);
+    const appId = resolveAppId({
+      ...(flagApp !== undefined ? { flagApp } : {}),
+      ...(envApp !== undefined ? { envApp } : {}),
+      state,
+      profile: ctx.profile,
+    });
+    return publish(ctx, {
+      dir,
+      manifestPath,
+      ...(appId !== null ? { appId } : {}),
+      ...(name !== undefined ? { name } : {}),
+      ...(org !== undefined ? { organizationId: org } : {}),
+      ...(clientToken !== undefined ? { clientToken } : {}),
+      ...(slug !== undefined ? { slug } : {}),
+      ...(visibility !== undefined ? { visibility } : {}),
+      ...(requireAccess !== undefined ? { requireAccess } : {}),
+    });
+  };
 }
 
 // How long `--wait` holds for the approval: bare `--wait` takes the default,
@@ -386,33 +509,48 @@ function parseGateFlag(value: string | undefined): boolean | undefined {
   return value === 'on';
 }
 
-async function runSchema(ctx: Context, parsed: ParsedArgs): Promise<unknown> {
-  const sub = parsed.positionals[1];
-  if (sub === 'pull') {
-    const docId = stringFlag(parsed, 'doc');
-    if (docId === undefined) throw new Error('brass schema pull requires --doc <docId>');
-    return schemaPull(ctx, { docId, outPath: stringFlag(parsed, 'out') ?? 'brass-app.json' });
+function planSchema(parsed: ParsedArgs): CommandPlan {
+  if (parsed.positionals[1] !== 'pull') {
+    throw new Error('Usage: brass schema pull --doc <docId> [--out brass-app.json]');
   }
-  throw new Error('Usage: brass schema pull --doc <docId> [--out brass-app.json]');
+  const docId = stringFlag(parsed, 'doc');
+  if (docId === undefined) throw new Error('brass schema pull requires --doc <docId>');
+  const outPath = stringFlag(parsed, 'out') ?? 'brass-app.json';
+  return (ctx): Promise<unknown> => schemaPull(ctx, { docId, outPath });
 }
 
-async function runAgents(ctx: Context, parsed: ParsedArgs): Promise<unknown> {
+function planAgents(parsed: ParsedArgs): CommandPlan {
   if (parsed.positionals[1] !== 'pull') {
     throw new Error(
       'Usage: brass agents pull [--out AGENTS.md | --stdout] [--org <organizationId>]',
     );
   }
+  // Both flags claim stdout: `--stdout` puts the instructions there verbatim,
+  // `--json` the result object. Together they interleave two payloads on one
+  // stream, so a caller parsing either reads the other's bytes as part of it.
+  if (boolFlag(parsed, 'stdout') && boolFlag(parsed, 'json')) {
+    throw new Error(
+      'Pass one of --stdout or --json: both write to stdout, so together neither is parseable.',
+    );
+  }
   const org = stringFlag(parsed, 'org');
-  return agentsPull(ctx, {
+  const options = {
     outPath: stringFlag(parsed, 'out') ?? 'AGENTS.md',
     ...(boolFlag(parsed, 'stdout') ? { stdout: true } : {}),
     ...(org !== undefined ? { organizationId: org } : {}),
-  });
+  };
+  return (ctx): Promise<unknown> => agentsPull(ctx, options);
 }
 
-function formatError(err: unknown): string {
+// Render a failure for the terminal, naming the fix for a 401 in the
+// vocabulary of the credential that was actually rejected. A session's
+// refusal already arrives carrying `brass login` (the refresh authors it), so
+// appending a service-token hint there tells the caller to check an
+// environment variable they never set, next to the sentence naming the real
+// fix. `status` classifies the same 401 the same way.
+function formatError(err: unknown, credentialKind?: CredentialKind): string {
   if (err instanceof BrassApiError) {
-    if (err.status === 401) {
+    if (err.status === 401 && credentialKind !== 'session') {
       return `error: ${err.message} (the credential was rejected; check BRASS_SERVICE_TOKEN or --token)`;
     }
     return `error: ${err.message}`;