ytstats 0.1.0

package/src/errors.js

@@ -0,0 +1,233 @@
+import { diagnose, DIAGNOSTICS } from './diagnostics.js';
+
+/**
+ * Stable machine-readable error codes. These are part of the public contract:
+ * scripts consuming ytstats JSON branch on `error.code`, so treat them as API.
+ */
+export const ERROR_CODES = {
+  MISSING_CREDENTIALS: 'MISSING_CREDENTIALS',
+  INVALID_CREDENTIALS: 'INVALID_CREDENTIALS',
+  NOT_AUTHENTICATED: 'NOT_AUTHENTICATED',
+  AUTH_FAILED: 'AUTH_FAILED',
+  AUTH_TIMEOUT: 'AUTH_TIMEOUT',
+  ACCESS_DENIED: 'ACCESS_DENIED',
+  API_NOT_ENABLED: 'API_NOT_ENABLED',
+  NO_YOUTUBE_CHANNEL: 'NO_YOUTUBE_CHANNEL',
+  QUOTA_EXCEEDED: 'QUOTA_EXCEEDED',
+  QUERY_NOT_SUPPORTED: 'QUERY_NOT_SUPPORTED',
+  NOT_FOUND: 'NOT_FOUND',
+  INVALID_INPUT: 'INVALID_INPUT',
+  API_ERROR: 'API_ERROR',
+  UNKNOWN: 'UNKNOWN',
+};
+
+/** Process exit codes, one per broad failure class. */
+export const EXIT_CODES = {
+  OK: 0,
+  GENERAL: 1,
+  AUTH: 2,
+  INPUT: 3,
+  API: 4,
+};
+
+export class YtStatsError extends Error {
+  constructor(message, { code = ERROR_CODES.UNKNOWN, exitCode, hint, cause, details, diagnostic } = {}) {
+    super(message);
+    this.name = 'YtStatsError';
+    this.code = code;
+    this.exitCode = exitCode ?? defaultExitCode(code);
+    if (hint) this.hint = hint;
+    if (cause) this.cause = cause;
+    if (details) this.details = details;
+    // The diagnostic is what reaches the caller; message/hint are for humans.
+    if (diagnostic) this.diagnostic = diagnostic;
+  }
+}
+
+/**
+ * Throw a fully-specified diagnostic.
+ * Preferred over `new YtStatsError(...)` everywhere a failure is anticipated.
+ */
+export function fail(definition, context = {}) {
+  const d = diagnose(definition, context);
+  return new YtStatsError(`${d.title}: ${d.detail}`, {
+    code: d.code,
+    exitCode: d.remediation ? undefined : ERROR_CODES.UNKNOWN,
+    hint: d.remediation?.summary,
+    diagnostic: d,
+  });
+}
+
+function defaultExitCode(code) {
+  switch (code) {
+    case ERROR_CODES.MISSING_CREDENTIALS:
+    case ERROR_CODES.INVALID_CREDENTIALS:
+    case ERROR_CODES.NOT_AUTHENTICATED:
+    case ERROR_CODES.AUTH_FAILED:
+    case ERROR_CODES.AUTH_TIMEOUT:
+    case ERROR_CODES.ACCESS_DENIED:
+    case ERROR_CODES.NO_YOUTUBE_CHANNEL:
+      return EXIT_CODES.AUTH;
+    case ERROR_CODES.INVALID_INPUT:
+      return EXIT_CODES.INPUT;
+    case ERROR_CODES.API_NOT_ENABLED:
+    case ERROR_CODES.QUOTA_EXCEEDED:
+    case ERROR_CODES.QUERY_NOT_SUPPORTED:
+    case ERROR_CODES.API_ERROR:
+      return EXIT_CODES.API;
+    default:
+      return EXIT_CODES.GENERAL;
+  }
+}
+
+export const SETUP_GUIDE = [
+  'Set up your own Google Cloud credentials (takes about 5 minutes):',
+  '',
+  '  1. Create/select a project:  https://console.cloud.google.com/projectcreate',
+  '  2. Enable these three APIs in that project:',
+  '       YouTube Data API v3      https://console.cloud.google.com/apis/library/youtube.googleapis.com',
+  '       YouTube Analytics API    https://console.cloud.google.com/apis/library/youtubeanalytics.googleapis.com',
+  '       YouTube Reporting API    https://console.cloud.google.com/apis/library/youtubereporting.googleapis.com',
+  '  3. Configure the OAuth consent screen (External) and add yourself as a test user:',
+  '       https://console.cloud.google.com/apis/credentials/consent',
+  '  4. Create credentials > OAuth client ID > Application type: Desktop app, then download the JSON:',
+  '       https://console.cloud.google.com/apis/credentials',
+  '  5. ytstats login --client-secret /path/to/client_secret_XXX.json',
+  '',
+  'Your credentials stay on this machine. ytstats has no server and no shared client ID.',
+].join('\n');
+
+/**
+ * Classify a Google API failure into a precise diagnostic.
+ *
+ * The ordering matters: the most specific signals (reason codes, message
+ * fingerprints) are checked before the generic HTTP status buckets, because a
+ * 403 can mean four unrelated things.
+ */
+export function diagnoseGoogleError(err) {
+  if (err instanceof YtStatsError && err.diagnostic) return err.diagnostic;
+
+  const status = err?.response?.status ?? err?.status;
+  const apiErr = err?.response?.data?.error;
+  const reason = apiErr?.errors?.[0]?.reason || err?.errors?.[0]?.reason;
+  const message =
+    apiErr?.message ||
+    err?.response?.data?.error_description ||
+    (typeof apiErr === 'string' ? apiErr : '') ||
+    err?.message ||
+    '';
+  const detail = message || `HTTP ${status ?? 'unknown'}`;
+
+  // Network-level failures never reach an HTTP status.
+  const netCode = err?.code;
+  if (['ENOTFOUND', 'ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'EAI_AGAIN', 'EPROTO', 'UND_ERR_CONNECT_TIMEOUT'].includes(netCode)
+      || /fetch failed|request to .* failed|getaddrinfo|socket hang up|network/i.test(message)) {
+    return diagnose(DIAGNOSTICS.NETWORK_UNREACHABLE, { detail });
+  }
+
+  if (reason === 'accessNotConfigured' || /has not been used in project|is disabled|API has not been used/i.test(message)) {
+    return diagnose(DIAGNOSTICS.API_NOT_ENABLED, { detail });
+  }
+
+  if (reason === 'NoLinkedYouTubeAccount' || /NoLinkedYouTubeAccount/i.test(message)) {
+    return diagnose(DIAGNOSTICS.AUTH_NO_CHANNEL, { detail });
+  }
+
+  if (reason === 'quotaExceeded' || /quota.*exceed/i.test(message)) {
+    return diagnose(DIAGNOSTICS.API_QUOTA_EXCEEDED, { detail });
+  }
+
+  if (reason === 'rateLimitExceeded' || reason === 'userRateLimitExceeded' || status === 429) {
+    return diagnose(DIAGNOSTICS.API_RATE_LIMITED, { detail });
+  }
+
+  if (/query is not supported/i.test(message)) {
+    return diagnose(DIAGNOSTICS.API_QUERY_NOT_SUPPORTED, { detail });
+  }
+
+  // invalid_grant is the single most common auth failure and has a specific fix.
+  if (/invalid_grant/i.test(message)) {
+    return diagnose(/revok/i.test(message) ? DIAGNOSTICS.AUTH_TOKEN_REVOKED : DIAGNOSTICS.AUTH_TOKEN_EXPIRED, { detail });
+  }
+
+  if (/token has been revoked|Token has been expired or revoked/i.test(message)) {
+    return diagnose(DIAGNOSTICS.AUTH_TOKEN_REVOKED, { detail });
+  }
+
+  if (status === 401 || /Invalid Credentials|unauthorized/i.test(message)) {
+    return diagnose(DIAGNOSTICS.AUTH_TOKEN_EXPIRED, { detail });
+  }
+
+  if (status === 403) return diagnose(DIAGNOSTICS.API_FORBIDDEN, { detail });
+  if (status === 404) return diagnose(DIAGNOSTICS.API_NOT_FOUND, { detail });
+  if (status >= 500) return diagnose(DIAGNOSTICS.API_UNAVAILABLE, { detail });
+  if (status === 400) return diagnose(DIAGNOSTICS.API_QUERY_NOT_SUPPORTED, { detail });
+
+  return diagnose(DIAGNOSTICS.UNEXPECTED, { detail });
+}
+
+/**
+ * Map a Google API error onto a typed YtStatsError carrying a diagnostic.
+ */
+export function mapGoogleError(err) {
+  if (err instanceof YtStatsError) return err;
+
+  const d = diagnoseGoogleError(err);
+  return new YtStatsError(`${d.title}: ${d.detail}`, {
+    code: legacyCodeFor(d.code),
+    hint: d.remediation.summary,
+    diagnostic: d,
+    cause: err,
+  });
+}
+
+/** Bridge new diagnostic codes back to the original ERROR_CODES vocabulary. */
+function legacyCodeFor(code) {
+  const map = {
+    AUTH_NO_CREDENTIALS: ERROR_CODES.MISSING_CREDENTIALS,
+    AUTH_CREDENTIALS_MALFORMED: ERROR_CODES.INVALID_CREDENTIALS,
+    AUTH_CREDENTIALS_NOT_FOUND: ERROR_CODES.INVALID_CREDENTIALS,
+    AUTH_SERVICE_ACCOUNT: ERROR_CODES.INVALID_CREDENTIALS,
+    AUTH_NO_TOKENS: ERROR_CODES.NOT_AUTHENTICATED,
+    AUTH_TOKEN_EXPIRED: ERROR_CODES.NOT_AUTHENTICATED,
+    AUTH_TOKEN_REVOKED: ERROR_CODES.NOT_AUTHENTICATED,
+    AUTH_ACCOUNT_UNKNOWN: ERROR_CODES.NOT_AUTHENTICATED,
+    AUTH_CONSENT_DECLINED: ERROR_CODES.ACCESS_DENIED,
+    AUTH_TIMEOUT: ERROR_CODES.AUTH_TIMEOUT,
+    AUTH_STATE_MISMATCH: ERROR_CODES.AUTH_FAILED,
+    AUTH_NO_CHANNEL: ERROR_CODES.NO_YOUTUBE_CHANNEL,
+    API_NOT_ENABLED: ERROR_CODES.API_NOT_ENABLED,
+    API_QUOTA_EXCEEDED: ERROR_CODES.QUOTA_EXCEEDED,
+    API_RATE_LIMITED: ERROR_CODES.QUOTA_EXCEEDED,
+    API_QUERY_NOT_SUPPORTED: ERROR_CODES.QUERY_NOT_SUPPORTED,
+    API_FORBIDDEN: ERROR_CODES.ACCESS_DENIED,
+    API_NOT_FOUND: ERROR_CODES.NOT_FOUND,
+    API_UNAVAILABLE: ERROR_CODES.API_ERROR,
+    NETWORK_UNREACHABLE: ERROR_CODES.API_ERROR,
+  };
+  return map[code] ?? ERROR_CODES.UNKNOWN;
+}
+
+const SECRET_PATTERNS = [
+  /GOCSPX-[A-Za-z0-9_-]+/g,           // Google client secrets
+  /\bya29\.[A-Za-z0-9._-]+/g,          // Google access tokens
+  /\b1\/\/[A-Za-z0-9._-]{20,}/g,       // Google refresh tokens
+  /\b4\/[0-9A-Za-z_-]{20,}/g,          // Google authorization codes
+  // Deliberately NOT matching a bare "code" field: every diagnostic carries
+  // `"code": "AUTH_NO_TOKENS"`, which is public API and must survive redaction.
+  /"(client_secret|clientSecret|refresh_token|access_token|code_verifier|codeVerifier|authorization_code)"\s*:\s*"[^"]*"/g,
+  /[?&](code|code_verifier|client_secret)=[^&\s"]+/g,
+];
+
+/**
+ * Strip anything that looks like a secret out of text destined for logs or JSON
+ * output. Belt-and-braces: we also never deliberately log these values.
+ */
+export function redact(text) {
+  if (typeof text !== 'string') return text;
+  let out = text;
+  for (const re of SECRET_PATTERNS) {
+    out = out.replace(re, m => (m.startsWith('"') ? m.replace(/:\s*"[^"]*"/, ': "[REDACTED]"') : '[REDACTED]'));
+  }
+  return out;
+}

package/src/fetch-all.js

@@ -0,0 +1,181 @@
+import * as data from './api/data.js';
+import * as analytics from './api/analytics.js';
+import * as reporting from './api/reporting.js';
+import { daysBetween } from './dates.js';
+import { YtStatsError, ERROR_CODES } from './errors.js';
+
+/** Real implementations; tests inject fakes. */
+function defaultFetchers() {
+  return {
+    fetchChannel: data.fetchChannel,
+    fetchAllVideoIds: data.fetchAllVideoIds,
+    fetchVideos: data.fetchVideos,
+    fetchDailyAnalytics: analytics.fetchDailyAnalytics,
+    fetchCardMetrics: analytics.fetchCardMetrics,
+    fetchVideoAnalytics: analytics.fetchVideoAnalytics,
+    fetchTrafficSources: analytics.fetchTrafficSources,
+    fetchDemographics: analytics.fetchDemographics,
+    fetchDeviceTypes: analytics.fetchDeviceTypes,
+    fetchContentTypes: analytics.fetchContentTypes,
+    fetchSearchTerms: analytics.fetchSearchTerms,
+    fetchGeography: analytics.fetchGeography,
+    fetchPlaybackLocations: analytics.fetchPlaybackLocations,
+    fetchTrafficSourceDetails: analytics.fetchTrafficSourceDetails,
+    fetchAudienceRetention: analytics.fetchAudienceRetention,
+    fetchReach: reporting.fetchReach,
+  };
+}
+
+const DEFAULT_RETENTION_LIMIT = 50;
+
+/** Auth problems are fatal everywhere; degrading past them yields a useless document. */
+const FATAL_CODES = new Set([
+  ERROR_CODES.NOT_AUTHENTICATED,
+  ERROR_CODES.MISSING_CREDENTIALS,
+  ERROR_CODES.INVALID_CREDENTIALS,
+  ERROR_CODES.NO_YOUTUBE_CHANNEL,
+  ERROR_CODES.QUOTA_EXCEEDED,
+]);
+
+/**
+ * Pull every dimension in one pass.
+ *
+ * Individual analytics steps degrade rather than abort: YouTube rejects certain
+ * metric/dimension combinations for some channels, and losing demographics should
+ * not cost you the other twelve datasets. Whatever failed is reported in
+ * `warnings` so the caller can tell "no data" from "not fetched".
+ */
+export async function fetchAll(apis, {
+  range,
+  fetchers: injected,
+  retention = true,
+  retentionLimit = DEFAULT_RETENTION_LIMIT,
+  reach = false,
+  onProgress,
+} = {}) {
+  const f = { ...defaultFetchers(), ...injected };
+  const { startDate, endDate } = range;
+  const period = { startDate, endDate };
+
+  const warnings = [];
+  const notes = [];
+  const progress = msg => onProgress?.(msg);
+
+  async function step(name, fn, fallback) {
+    progress(`Fetching ${name}...`);
+    try {
+      return await fn();
+    } catch (err) {
+      if (FATAL_CODES.has(err?.code)) throw err;
+      warnings.push({
+        step: name,
+        code: err?.code ?? ERROR_CODES.UNKNOWN,
+        message: err?.message ?? String(err),
+      });
+      return fallback;
+    }
+  }
+
+  // Channel identity is the one hard requirement — everything else keys off it.
+  progress('Fetching channel...');
+  const channel = await f.fetchChannel(apis);
+  if (!channel) {
+    throw new YtStatsError('No YouTube channel found for the signed-in account.', {
+      code: ERROR_CODES.NO_YOUTUBE_CHANNEL,
+      hint: 'Sign in with the Google account that owns the channel: `ytstats logout` then `ytstats login`.',
+    });
+  }
+
+  progress('Listing videos...');
+  const videoIds = await step('videoIds', () => f.fetchAllVideoIds(apis, channel.uploadsPlaylistId), []);
+  const videos = await step('videos', () => f.fetchVideos(apis, videoIds), []);
+
+  const [daily, cards] = await Promise.all([
+    step('daily', () => f.fetchDailyAnalytics(apis, period), []),
+    step('cardMetrics', () => f.fetchCardMetrics(apis, period), []),
+  ]);
+
+  const [
+    videoAnalytics, trafficSources, demographics, deviceTypes,
+    contentTypes, searchTerms, geography, playbackLocations,
+  ] = await Promise.all([
+    step('videoAnalytics', () => f.fetchVideoAnalytics(apis, period), []),
+    step('trafficSources', () => f.fetchTrafficSources(apis, period), []),
+    step('demographics', () => f.fetchDemographics(apis, period), []),
+    step('deviceTypes', () => f.fetchDeviceTypes(apis, period), []),
+    step('contentTypes', () => f.fetchContentTypes(apis, period), []),
+    step('searchTerms', () => f.fetchSearchTerms(apis, period), []),
+    step('geography', () => f.fetchGeography(apis, period), []),
+    step('playbackLocations', () => f.fetchPlaybackLocations(apis, period), []),
+  ]);
+
+  // Only drill into traffic source types the channel actually has.
+  const detailTypes = trafficSources.map(t => t.sourceType).filter(Boolean);
+  const detailResults = await Promise.all(
+    detailTypes.map(sourceType =>
+      step(`trafficSourceDetails:${sourceType}`,
+        () => f.fetchTrafficSourceDetails(apis, { ...period, sourceType }),
+        []),
+    ),
+  );
+
+  const audienceRetention = {};
+  if (retention && videos.length) {
+    // One API call per video, so cap it — newest first, since that is what anyone
+    // analysing retention actually cares about.
+    const ordered = [...videos].sort(
+      (a, b) => String(b.publishedAt ?? '').localeCompare(String(a.publishedAt ?? '')),
+    );
+    const targets = ordered.slice(0, retentionLimit);
+    if (targets.length < videos.length) {
+      notes.push(`Audience retention fetched for ${targets.length} of ${videos.length} videos (most recent first). Use --retention-limit to change.`);
+    }
+
+    for (const [i, video] of targets.entries()) {
+      progress(`Fetching retention ${i + 1}/${targets.length}...`);
+      const curve = await step(`retention:${video.id}`,
+        () => f.fetchAudienceRetention(apis, { ...period, videoId: video.id }),
+        null);
+      if (curve?.length) audienceRetention[video.id] = curve;
+    }
+  }
+
+  const result = {
+    channel,
+    videos,
+    daily: mergeByDate(daily, cards),
+    videoAnalytics,
+    trafficSources,
+    trafficSourceDetails: detailResults.flat(),
+    demographics,
+    deviceTypes,
+    contentTypes,
+    searchTerms,
+    geography,
+    playbackLocations,
+    audienceRetention,
+  };
+
+  if (reach) {
+    result.reach = await step('reach', () => f.fetchReach(apis, { onProgress }), { pending: true, rows: [] });
+  }
+
+  return {
+    period: { ...period, days: daysBetween(startDate, endDate) },
+    warnings,
+    notes,
+    data: result,
+  };
+}
+
+/** Fold the card-metrics rows into the daily rows sharing their date. */
+function mergeByDate(daily, extra) {
+  if (!extra?.length) return daily;
+  const index = new Map(extra.map(row => [row.date, row]));
+  return daily.map(row => {
+    const match = index.get(row.date);
+    if (!match) return row;
+    const { date, ...rest } = match;
+    return { ...row, ...rest };
+  });
+}

package/src/index.js

@@ -0,0 +1,44 @@
+/**
+ * Programmatic API.
+ *
+ * The CLI is the public contract, but importing the library avoids a process
+ * spawn and a JSON round-trip when you are already in Node:
+ *
+ *   import { getAuthenticatedClient, createApis, fetchAll, resolveDateRange } from 'ytstats';
+ *
+ *   const { client } = getAuthenticatedClient();
+ *   const result = await fetchAll(createApis(client), { range: resolveDateRange({ days: 90 }) });
+ */
+export { getAuthenticatedClient, login, logout } from './auth/session.js';
+export {
+  resolveCredentials,
+  saveCredentials,
+  clearCredentials,
+  loadStoredCredentials,
+  discoverClientSecretFile,
+  parseClientSecret,
+} from './auth/credentials.js';
+export {
+  loadAccount,
+  listAccounts,
+  saveAccount,
+  removeAccount,
+  setDefaultAccount,
+  clearAllAccounts,
+  migrateLegacyTokens,
+} from './auth/tokens.js';
+export { SCOPES } from './auth/oauth.js';
+
+export { createApis } from './api/client.js';
+export * as data from './api/data.js';
+export * as analytics from './api/analytics.js';
+export * as reporting from './api/reporting.js';
+export * from './api/transforms.js';
+
+export { fetchAll } from './fetch-all.js';
+export { resolveDateRange, daysBetween, toIsoDate } from './dates.js';
+export { configDir } from './config/store.js';
+export { renderEnvelope, createReporter } from './output.js';
+export { YtStatsError, ERROR_CODES, EXIT_CODES, mapGoogleError, diagnoseGoogleError, fail, redact } from './errors.js';
+export { DIAGNOSTICS, diagnose, isDiagnostic, SEVERITY, EXIT } from './diagnostics.js';
+export { buildProgram, main } from './cli.js';

package/src/output.js

@@ -0,0 +1,168 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { diagnose, isDiagnostic, exitCodeFor, DIAGNOSTICS, SEVERITY, EXIT } from './diagnostics.js';
+export { SEVERITY, EXIT };
+import { redact } from './errors.js';
+
+const pkg = JSON.parse(
+  fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf-8'),
+);
+
+/**
+ * The output contract.
+ *
+ *   stdout  exactly one JSON document, always, success or failure
+ *   stderr  human-readable progress; safe to discard entirely
+ *
+ * The envelope is shape-invariant: every key is present on every response, so a
+ * consumer never has to branch on whether a field exists. On failure `data` is
+ * null (never partial, never absent) and `errors` is non-empty.
+ *
+ *   { ok, command, fetchedAt, data, errors[], warnings[], nextSteps[], meta }
+ */
+
+const HELP_COMMAND = 'ytstats --help';
+
+export function renderEnvelope({
+  command,
+  data = null,
+  errors = [],
+  warnings = [],
+  compact = false,
+  fetchedAt,
+} = {}) {
+  const errorList = errors.map(toDiagnostic).filter(d => d.severity === SEVERITY.ERROR);
+  const warningList = [
+    ...warnings.map(toDiagnostic),
+    ...errors.map(toDiagnostic).filter(d => d.severity === SEVERITY.WARNING),
+  ];
+
+  const ok = errorList.length === 0;
+
+  const envelope = {
+    ok,
+    command: command ?? null,
+    fetchedAt: fetchedAt ?? new Date().toISOString(),
+    // Never hand back half a dataset alongside an error: a consumer that reads
+    // `data` without checking `ok` would silently act on partial results.
+    data: ok ? (data ?? null) : null,
+    errors: errorList,
+    warnings: warningList,
+    nextSteps: buildNextSteps([...errorList, ...warningList]),
+    meta: {
+      version: pkg.version,
+      exitCode: exitCodeFor([...errorList, ...warningList]),
+      helpCommand: HELP_COMMAND,
+      docs: 'https://www.npmjs.com/package/ytstats',
+    },
+  };
+
+  const json = JSON.stringify(envelope, null, compact ? undefined : 2);
+  return redact(json);
+}
+
+/** Accept a diagnostic, a YtStatsError carrying one, or any stray throw. */
+function toDiagnostic(value) {
+  if (isDiagnostic(value)) return value;
+
+  if (value?.diagnostic && isDiagnostic(value.diagnostic)) return value.diagnostic;
+
+  if (value instanceof Error) {
+    return diagnose(DIAGNOSTICS.UNEXPECTED, { detail: value.message });
+  }
+
+  return diagnose(DIAGNOSTICS.UNEXPECTED, { detail: String(value) });
+}
+
+/**
+ * Flatten remediation into an ordered, deduplicated list of things to do next.
+ * Errors first, warnings after — an agent should fix what blocked it before
+ * acting on advisories.
+ */
+function buildNextSteps(diagnostics) {
+  const steps = [];
+  const seen = new Set();
+
+  const push = text => {
+    const value = String(text).trim();
+    if (value && !seen.has(value)) {
+      seen.add(value);
+      steps.push(value);
+    }
+  };
+
+  const ordered = [
+    ...diagnostics.filter(d => d.severity === SEVERITY.ERROR),
+    ...diagnostics.filter(d => d.severity === SEVERITY.WARNING),
+  ];
+
+  for (const d of ordered) {
+    for (const cmd of d.remediation.commands ?? []) push(`${cmd.run}  # ${cmd.description}`);
+    if (!d.remediation.commands?.length) push(d.remediation.summary);
+  }
+
+  return steps;
+}
+
+/**
+ * Reporter bound to a pair of sinks. Injecting them keeps stream discipline
+ * directly testable rather than relying on process-level capture.
+ */
+export function createReporter({
+  stdout = s => process.stdout.write(s + '\n'),
+  stderr = s => process.stderr.write(s + '\n'),
+  quiet = false,
+  compact = false,
+  exitZero = false,
+} = {}) {
+  const warningsBuffer = [];
+
+  const reporter = {
+    /** Human-facing progress. Never stdout. */
+    progress(message) {
+      if (!quiet) stderr(redact(String(message)));
+    },
+
+    /**
+     * Attach a non-fatal diagnostic to the eventual envelope, and echo it for
+     * humans. Warnings never make `ok` false and never affect the exit code.
+     *
+     * Severity is forced to 'warning' here: routing a diagnostic through warn()
+     * IS the decision that it is non-fatal. Without this, `doctor` — whose whole
+     * job is to report auth problems it found — would exit 2 while reporting
+     * ok:true, which is incoherent.
+     */
+    warn(diagnostic) {
+      const d = { ...toDiagnostic(diagnostic), severity: SEVERITY.WARNING };
+      warningsBuffer.push(d);
+      if (!quiet) stderr(redact(`warning: ${d.title} — ${d.detail}`));
+      return d;
+    },
+
+    /** Terminal success. Emits the one and only stdout document. */
+    succeed(command, data, opts = {}) {
+      stdout(renderEnvelope({ command, data, warnings: warningsBuffer, compact, ...opts }));
+      return exitZero ? EXIT.OK : exitCodeFor(warningsBuffer);
+    },
+
+    /** Terminal failure. Envelope to stdout, guidance to stderr. Returns the exit code. */
+    fail(command, errors, opts = {}) {
+      const list = (Array.isArray(errors) ? errors : [errors]).map(toDiagnostic);
+      stdout(renderEnvelope({ command, errors: [...list, ...warningsBuffer], compact, ...opts }));
+
+      if (!quiet) {
+        for (const d of list) {
+          stderr(redact(`error [${d.code}]: ${d.title}`));
+          stderr(redact(`  ${d.detail}`));
+          if (d.remediation.summary) stderr(redact(`  fix: ${d.remediation.summary}`));
+          for (const cmd of d.remediation.commands ?? []) stderr(redact(`    $ ${cmd.run}`));
+        }
+      }
+
+      return exitZero ? EXIT.OK : exitCodeFor(list);
+    },
+  };
+
+  return reporter;
+}