flipstream 0.4.0

package/dist/lib/auth/revoke.d.ts

@@ -0,0 +1,8 @@
+export interface RevokeParams {
+    clientId: string;
+    revocationEndpoint: string;
+    timeoutMs?: number;
+    token: string;
+    tokenTypeHint?: 'access_token' | 'refresh_token';
+}
+export declare function revokeToken(params: RevokeParams): Promise<boolean>;

package/dist/lib/auth/revoke.js

@@ -0,0 +1,28 @@
+// Best-effort RFC 7009 token revocation. Revoking the refresh token invalidates
+// its associated access tokens server-side. Returns whether the server confirmed
+// the revocation (HTTP 2xx) — never throws, so logout can always proceed to clear
+// local credentials regardless of network/server state.
+export async function revokeToken(params) {
+    const body = new URLSearchParams({ client_id: params.clientId, token: params.token });
+    if (params.tokenTypeHint)
+        body.set('token_type_hint', params.tokenTypeHint);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), params.timeoutMs ?? 10_000);
+    try {
+        const response = await fetch(params.revocationEndpoint, {
+            body: body.toString(),
+            headers: { accept: 'application/json', 'content-type': 'application/x-www-form-urlencoded' },
+            method: 'POST',
+            signal: controller.signal,
+        });
+        // RFC 7009: the server returns 200 for both a successful revocation and an
+        // already-invalid/unknown token, so 2xx is the success signal either way.
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/lib/auth/session.d.ts

@@ -0,0 +1,6 @@
+import type { TokenStore } from '../store/keyring.js';
+export interface SessionOptions {
+    store?: TokenStore;
+    timeoutMs?: number;
+}
+export declare function getFreshAccessToken(host: string, options?: SessionOptions): Promise<null | string>;

package/dist/lib/auth/session.js

@@ -0,0 +1,13 @@
+import { createStore } from '../store/index.js';
+import { refresh } from './refresh.js';
+// The access token a caller should use for host: the cached token when still
+// fresh (no HTTP), otherwise a transparently silent-refreshed one. Returns null
+// when not logged in or the refresh failed. This is the single seam the data
+// client (E4) uses to obtain a bearer token.
+export async function getFreshAccessToken(host, options = {}) {
+    const store = options.store ?? createStore();
+    const cached = store.accessTokenIfFresh(host);
+    if (cached)
+        return cached;
+    return refresh(host, { store, timeoutMs: options.timeoutMs });
+}

package/dist/lib/command/admin.d.ts

@@ -0,0 +1,4 @@
+import { type AdminClient } from '../api/admin-client.js';
+import { type TokenStore } from '../store/keyring.js';
+export declare function authedAdminClient(host: string, store: TokenStore, timeoutMs?: number): AdminClient;
+export declare function renderConnectionsTable(records: Array<Record<string, unknown>>): void;

package/dist/lib/command/admin.js

@@ -0,0 +1,30 @@
+import { createAuthedAdminClient } from '../api/admin-client.js';
+import { refresh } from '../auth/refresh.js';
+import { renderTable } from '../output/table.js';
+// Build the authed admin client for a command. The admin host == the OAuth issuer
+// (where creds live), so one host serves both creds/refresh and the admin calls;
+// reuses the single withFreshToken 401->refresh->retry wrapper.
+export function authedAdminClient(host, store, timeoutMs) {
+    return createAuthedAdminClient({
+        accessTokenIfFresh: (authHost) => store.accessTokenIfFresh(authHost),
+        authHost: host,
+        host,
+        refresh: (authHost) => refresh(authHost, { store, timeoutMs }),
+        timeoutMs,
+    });
+}
+// The connections human table — shared by `connections list` and `ws connections`.
+// Falls back to the workspace id when its name couldn't be resolved.
+export function renderConnectionsTable(records) {
+    const rows = records.map((record) => ({
+        ...record,
+        client_name: record.client_name ?? record.client_id ?? '—',
+    }));
+    renderTable(rows, [
+        { key: 'client_name', name: 'Workspace' },
+        { key: 'name', name: 'Connection' },
+        { key: 'type', name: 'Type' },
+        { key: 'active', name: 'Active' },
+        { key: 'id', name: 'ID' },
+    ], 'No connections.');
+}

package/dist/lib/command/base.d.ts

@@ -0,0 +1,28 @@
+import { Command, type Interfaces } from '@oclif/core';
+export type BaseFlags<T extends typeof Command> = Interfaces.InferredFlags<(typeof BaseCommand)['baseFlags'] & T['flags']>;
+export type BaseArgs<T extends typeof Command> = Interfaces.InferredArgs<T['args']>;
+export declare abstract class BaseCommand<T extends typeof Command> extends Command {
+    static baseFlags: {
+        host: Interfaces.OptionFlag<string | undefined, Interfaces.CustomOptions>;
+        ndjson: Interfaces.BooleanFlag<boolean>;
+        timeout: Interfaces.OptionFlag<number | undefined, Interfaces.CustomOptions>;
+        verbose: Interfaces.BooleanFlag<boolean>;
+    };
+    static enableJsonFlag: boolean;
+    protected args: BaseArgs<T>;
+    protected flags: BaseFlags<T>;
+    protected catch(error: Error & {
+        exitCode?: number;
+    }): Promise<never>;
+    init(): Promise<void>;
+    protected resolvedHost(): string;
+    protected respond<D>(data: D, human: (data: D) => void): D;
+    protected respondList<R>(envelope: {
+        count: number;
+        records: R[];
+    }, human: (records: R[]) => void): {
+        count: number;
+        records: R[];
+    };
+    protected verboseLog(message: string): void;
+}

package/dist/lib/command/base.js

@@ -0,0 +1,75 @@
+import { Command, Flags } from '@oclif/core';
+import { resolveHost } from '../config/xdg.js';
+import { renderError, UsageError } from '../errors.js';
+import { renderNdjson } from '../output/ndjson.js';
+import { redact } from '../output/redact.js';
+// Repo-wide clig.dev conventions in one place (E3-5). Every command extends this:
+//   - stdout = data, stderr = help/prompts/progress/diagnostics
+//   - --json (machine JSON, oclif-serialized) / --ndjson (one object per line),
+//     mutually exclusive
+//   - shared --host/-H, --verbose/--debug (redacted, stderr-only), --timeout
+//   - errors routed through the redacting renderError
+export class BaseCommand extends Command {
+    static baseFlags = {
+        host: Flags.string({ char: 'H', description: 'OAuth provider host (defaults to the prod issuer).' }),
+        ndjson: Flags.boolean({ description: 'Stream output as NDJSON (one compact JSON object per line).' }),
+        timeout: Flags.integer({ description: 'Network timeout in milliseconds.' }),
+        verbose: Flags.boolean({ aliases: ['debug'], description: 'Print redacted diagnostics to stderr.' }),
+    };
+    static enableJsonFlag = true;
+    args;
+    flags;
+    // Centralized error rendering: redacted, machine {error:{code,message}} under
+    // --json/--ndjson, a human line otherwise. Replaces oclif's default reporter.
+    async catch(error) {
+        const machine = this.jsonEnabled() || Boolean(this.flags?.ndjson);
+        this.exit(renderError(error, { json: machine }));
+    }
+    async init() {
+        await super.init();
+        const { args, flags } = await this.parse({
+            args: this.ctor.args,
+            baseFlags: super.ctor.baseFlags,
+            enableJsonFlag: this.ctor.enableJsonFlag,
+            flags: this.ctor.flags,
+            strict: this.ctor.strict,
+        });
+        this.flags = flags;
+        this.args = args;
+        // --json and --ndjson both claim stdout; refuse the ambiguous combination.
+        // UsageError carries exit 2 (oclif's {exit:2} would map to GENERIC instead).
+        if (this.jsonEnabled() && this.flags.ndjson) {
+            throw new UsageError('--json and --ndjson are mutually exclusive.');
+        }
+    }
+    // The resolved active host (flag > config.defaultHost > DEFAULT_HOST).
+    resolvedHost() {
+        return resolveHost({ hostFlag: this.flags.host });
+    }
+    // Emit `data` in the active output mode. Under --json oclif auto-serializes the
+    // run() return value (so this only returns); under --ndjson it streams; else it
+    // invokes the human formatter. Always returns `data` for the oclif --json path.
+    respond(data, human) {
+        if (this.flags.ndjson)
+            renderNdjson(data);
+        else if (!this.jsonEnabled())
+            human(data);
+        return data;
+    }
+    // List output: under --ndjson stream the RECORDS (one per line); under --json
+    // oclif returns the full {count, records} envelope; else invoke the human
+    // formatter. Returns the envelope for the oclif --json path.
+    respondList(envelope, human) {
+        if (this.flags.ndjson)
+            renderNdjson(envelope.records);
+        else if (!this.jsonEnabled())
+            human(envelope.records);
+        return envelope;
+    }
+    // Verbose diagnostics: stderr only (never stdout — protects --json/NDJSON) and
+    // always redacted (never leaks a token).
+    verboseLog(message) {
+        if (this.flags.verbose)
+            process.stderr.write(`${redact(message)}\n`);
+    }
+}

package/dist/lib/command/crash.d.ts

@@ -0,0 +1,2 @@
+export declare function formatCrash(value: unknown): string;
+export declare function installCrashHandlers(): void;

package/dist/lib/command/crash.js

@@ -0,0 +1,37 @@
+import { redact } from '../output/redact.js';
+let installed = false;
+// Redact an arbitrary thrown/rejected value for safe emit. Strings, Error stacks,
+// and objects (e.g. a fetch request object carrying an Authorization header) all
+// pass through the JSON-aware redactor so no token reaches stderr.
+export function formatCrash(value) {
+    if (typeof value === 'string')
+        return redact(value);
+    if (value instanceof Error)
+        return redact(value.stack ?? value.message);
+    try {
+        return JSON.stringify(redact(value));
+    }
+    catch {
+        return redact(String(value));
+    }
+}
+// Last-resort safety net for tokens that would otherwise reach stderr via an
+// unhandled rejection / uncaught exception (e.g. a stack embedding a request
+// object with an Authorization header). Redacts, emits, then exits non-zero.
+// Installed only by the real CLI entrypoints (bin/*) — NOT in-process under the
+// test runner, where a global process.exit handler would be hazardous. Idempotent.
+export function installCrashHandlers() {
+    if (installed)
+        return;
+    installed = true;
+    process.on('uncaughtException', (error) => {
+        process.stderr.write(`${formatCrash(error)}\n`);
+        // eslint-disable-next-line n/no-process-exit -- last-resort safety net, must hard-exit
+        process.exit(1);
+    });
+    process.on('unhandledRejection', (reason) => {
+        process.stderr.write(`${formatCrash(reason)}\n`);
+        // eslint-disable-next-line n/no-process-exit -- last-resort safety net, must hard-exit
+        process.exit(1);
+    });
+}

package/dist/lib/command/flags.d.ts

@@ -0,0 +1,7 @@
+export declare const paginationFlags: {
+    all: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+    offset: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+    q: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    sort: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+};

package/dist/lib/command/flags.js

@@ -0,0 +1,10 @@
+import { Flags } from '@oclif/core';
+// Shared pagination/filter flags for admin list commands (E7-1b). `limit`
+// defaults to 50 to force the {count, records} shape; `--all` drains every page.
+export const paginationFlags = {
+    all: Flags.boolean({ description: 'Fetch every page (drains pagination).' }),
+    limit: Flags.integer({ default: 50, description: 'Page size.' }),
+    offset: Flags.integer({ default: 0, description: 'Starting offset.' }),
+    q: Flags.string({ description: 'Free-text filter.' }),
+    sort: Flags.string({ description: 'Sort field.' }),
+};

package/dist/lib/config/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const DEFAULT_HOST = "https://pulse.admin.api.flipstream.io";
+export declare const DATA_HOST = "https://pulse.data.query.api.flipstream.io";
+export declare const ADMIN_HOST = "https://pulse.admin.api.flipstream.io";
+export declare const OAUTH_CLI_CLIENT_ID = "a975d9be-5ad6-44a5-8c1f-b95b995f3f70";
+export declare const CONTRACT_VERSION = "1";

package/dist/lib/config/constants.js

@@ -0,0 +1,20 @@
+// The OAuth provider / issuer (prod-only). Right-trim of trailing slash is the
+// canonical form; resolveHost() guarantees it.
+export const DEFAULT_HOST = 'https://pulse.admin.api.flipstream.io';
+// The data API host (the /query path is appended by the data client in E4).
+export const DATA_HOST = 'https://pulse.data.query.api.flipstream.io';
+// The admin API host (E7). Today it is the SAME origin as the AUTH issuer
+// (unified auth — the stored bearer is accepted here), so it aliases DEFAULT_HOST;
+// kept as its own constant in case the admin API splits to a distinct origin later.
+export const ADMIN_HOST = DEFAULT_HOST;
+// The CLI's fixed first-party public OAuth client_id (RFC 8252 native app).
+// NON-SECRET: a public client has no secret — PKCE (S256) is the security
+// boundary — so this is safe to ship in source. Every login reuses this ONE
+// pre-provisioned first-party client (no per-login Dynamic Client Registration,
+// hence nothing accumulates server-side). The provider pins the same value via
+// its `ensure-first-party-client` provisioning. Prod value; override for non-prod
+// environments with FLIPSTREAM_OAUTH_CLIENT_ID.
+export const OAUTH_CLI_CLIENT_ID = 'a975d9be-5ad6-44a5-8c1f-b95b995f3f70';
+// The agent-facing output/exit-code contract version. Bumped when the JSON shape,
+// exit codes, or flags change in a way agents must notice. Surfaced by `version`.
+export const CONTRACT_VERSION = '1';

package/dist/lib/config/xdg.d.ts

@@ -0,0 +1,21 @@
+export interface HostConfig {
+    clientId?: string;
+    expiresAt?: number;
+    redirectUri?: string;
+    scopes?: string[];
+}
+export interface Config {
+    defaultHost?: string;
+    hosts?: Record<string, HostConfig>;
+}
+export declare function configDir(): string;
+export declare function configPath(): string;
+export declare function readConfig(): Config;
+export declare function writeConfig(partial: Partial<Config>): Config;
+export declare function rememberHost(host: string, meta?: HostConfig): void;
+export declare function forgetHost(host: string): void;
+export declare function knownHosts(): string[];
+export declare function removeConfigDir(): boolean;
+export declare function resolveHost(options?: {
+    hostFlag?: string;
+}): string;

package/dist/lib/config/xdg.js

@@ -0,0 +1,97 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { DEFAULT_HOST } from './constants.js';
+// Defense-in-depth: any key that looks like a credential is stripped before a
+// write, so a token can never be persisted to the (non-secret) config file.
+const SECRET_KEY_PATTERN = /token|secret|verifier|code|authorization/i;
+export function configDir() {
+    const xdg = process.env.XDG_CONFIG_HOME?.trim();
+    const base = xdg && xdg.length > 0 ? xdg : join(homedir(), '.config');
+    return join(base, 'flipstream-cli');
+}
+export function configPath() {
+    return join(configDir(), 'config.json');
+}
+// Read the config; returns a default object (never throws) on a missing file or
+// invalid JSON.
+export function readConfig() {
+    try {
+        return JSON.parse(readFileSync(configPath(), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function stripSecrets(value) {
+    if (Array.isArray(value))
+        return value.map((item) => stripSecrets(item));
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [key, val] of Object.entries(value)) {
+            if (SECRET_KEY_PATTERN.test(key))
+                continue;
+            out[key] = stripSecrets(val);
+        }
+        return out;
+    }
+    return value;
+}
+function rstrip(host) {
+    return host.replace(/\/+$/, '');
+}
+// Write the full config atomically (tmp + rename), dir 0700 / file 0600. Secret-
+// named keys are stripped, never written.
+function persist(config) {
+    const safe = stripSecrets(config);
+    mkdirSync(configDir(), { recursive: true });
+    chmodSync(configDir(), 0o700);
+    const tmp = `${configPath()}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(safe, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tmp, configPath());
+    chmodSync(configPath(), 0o600);
+    return safe;
+}
+// Merge `partial` into the existing config and persist. `hosts` is merged by key.
+export function writeConfig(partial) {
+    const current = readConfig();
+    const merged = { ...current, ...partial };
+    if (current.hosts || partial.hosts) {
+        merged.hosts = { ...current.hosts, ...partial.hosts };
+    }
+    return persist(merged);
+}
+// Record a host in the NON-secret known-hosts index. The keychain API is
+// account-keyed (no enumerate-by-service), so this index is how logout/clear-all
+// learn which hosts exist. `meta` carries only non-secret fields (HostConfig).
+export function rememberHost(host, meta = {}) {
+    writeConfig({ hosts: { [rstrip(host)]: meta } });
+}
+// Remove a host from the known-hosts index (no-op if absent).
+export function forgetHost(host) {
+    const config = readConfig();
+    const key = rstrip(host);
+    if (!config.hosts || !(key in config.hosts))
+        return;
+    const hosts = { ...config.hosts };
+    delete hosts[key];
+    persist({ ...config, hosts });
+}
+// Every host in the known-hosts index.
+export function knownHosts() {
+    return Object.keys(readConfig().hosts ?? {});
+}
+// Delete the entire XDG config dir. Returns whether it existed (for idempotency).
+export function removeConfigDir() {
+    const dir = configDir();
+    if (!existsSync(dir))
+        return false;
+    rmSync(dir, { force: true, recursive: true });
+    return true;
+}
+// Resolve the active host: --host/-H flag > config.defaultHost > DEFAULT_HOST,
+// always right-trimmed of trailing slashes.
+export function resolveHost(options = {}) {
+    const raw = options.hostFlag ?? readConfig().defaultHost ?? DEFAULT_HOST;
+    return raw.replace(/\/+$/, '');
+}

package/dist/lib/errors.d.ts

@@ -0,0 +1,38 @@
+export declare class CliError extends Error {
+    readonly code: string;
+    readonly exitCode: number;
+    constructor(message: string, code: string, exitCode: number);
+}
+export declare class AuthRequiredError extends CliError {
+    constructor(message?: string, code?: 'not_logged_in' | 'session_expired');
+    static notLoggedIn(message?: string): AuthRequiredError;
+    static sessionExpired(message?: string): AuthRequiredError;
+}
+export declare class AuthFailedError extends CliError {
+    constructor(message: string, code?: string);
+}
+export declare class NetworkError extends CliError {
+    constructor(message: string, code?: string);
+}
+export declare class TimeoutError extends CliError {
+    constructor(message: string, code?: string);
+}
+export declare class UsageError extends CliError {
+    constructor(message: string, code?: string);
+}
+export declare class DiscoveryError extends NetworkError {
+    constructor(message: string);
+}
+export declare class LoopbackError extends CliError {
+    constructor(message: string, code?: string, exitCode?: number);
+    static timeout(message?: string): LoopbackError;
+}
+export declare class DataHttpError extends CliError {
+    readonly bodyText: string;
+    readonly status: number;
+    constructor(status: number, bodyText: string);
+}
+export declare function toExitCode(error: unknown): number;
+export declare function renderError(error: unknown, options?: {
+    json?: boolean;
+}): number;

package/dist/lib/errors.js

@@ -0,0 +1,122 @@
+import { ExitCode } from './exit-codes.js';
+import { redact } from './output/redact.js';
+// Base class for every CLI error. Carries a stable string `code` (for agent
+// branching under --json) and the deterministic `exitCode` from ExitCode.
+export class CliError extends Error {
+    code;
+    exitCode;
+    constructor(message, code, exitCode) {
+        super(message);
+        this.name = 'CliError';
+        this.code = code;
+        this.exitCode = exitCode;
+    }
+}
+// Not authenticated (or session expired) — exit 4. Two distinct codes let an
+// agent tell "never logged in" apart from "token expired, re-login".
+export class AuthRequiredError extends CliError {
+    constructor(message = 'Not logged in', code = 'not_logged_in') {
+        super(message, code, ExitCode.AUTH_REQUIRED);
+        this.name = 'AuthRequiredError';
+    }
+    static notLoggedIn(message = 'Not logged in. Run `flipstream auth login`.') {
+        return new AuthRequiredError(message, 'not_logged_in');
+    }
+    static sessionExpired(message = 'Session expired. Run `flipstream auth login`.') {
+        return new AuthRequiredError(message, 'session_expired');
+    }
+}
+// Authentication attempt failed (bad state/iss, token exchange rejected) — exit 5.
+export class AuthFailedError extends CliError {
+    constructor(message, code = 'auth_failed') {
+        super(message, code, ExitCode.AUTH_FAILED);
+        this.name = 'AuthFailedError';
+    }
+}
+// Network/transport failure (incl. discovery) — exit 7.
+export class NetworkError extends CliError {
+    constructor(message, code = 'network_error') {
+        super(message, code, ExitCode.NETWORK);
+        this.name = 'NetworkError';
+    }
+}
+// Operation timed out (e.g. user never finished the browser flow) — exit 8.
+export class TimeoutError extends CliError {
+    constructor(message, code = 'timeout') {
+        super(message, code, ExitCode.TIMEOUT);
+        this.name = 'TimeoutError';
+    }
+}
+// Bad invocation — exit 2 (aligns with oclif's usage exit).
+export class UsageError extends CliError {
+    constructor(message, code = 'usage') {
+        super(message, code, ExitCode.USAGE);
+        this.name = 'UsageError';
+    }
+}
+// Discovery (RFC 8414) failure — a NetworkError with a faithful name (ported
+// from the reference flow's DiscoveryError).
+export class DiscoveryError extends NetworkError {
+    constructor(message) {
+        super(message, 'discovery_failed');
+        this.name = 'DiscoveryError';
+    }
+}
+// Loopback callback failure. Exit code varies: a timeout is TIMEOUT(8); a
+// state/iss/code validation failure is AUTH_FAILED(5).
+export class LoopbackError extends CliError {
+    constructor(message, code = 'loopback_failed', exitCode = ExitCode.AUTH_FAILED) {
+        super(message, code, exitCode);
+        this.name = 'LoopbackError';
+    }
+    static timeout(message = 'Timed out waiting for the browser authorization to complete.') {
+        return new LoopbackError(message, 'loopback_timeout', ExitCode.TIMEOUT);
+    }
+}
+// A non-2xx response from the DATA host. Transport-only carrier (E4-1): it holds
+// the status + raw body so the E4-2 retry wrapper can detect 401 and the E4-3
+// mapper can assign a deterministic exit code. Default exit is GENERIC until E4-3.
+export class DataHttpError extends CliError {
+    bodyText;
+    status;
+    constructor(status, bodyText) {
+        super(`Data request failed: HTTP ${status}`, 'data_http_error', ExitCode.GENERIC);
+        this.name = 'DataHttpError';
+        this.status = status;
+        this.bodyText = bodyText;
+    }
+}
+// Map any thrown value to a deterministic exit code. Known CliErrors carry their
+// own; ported errors that don't extend CliError are matched by name for
+// forward-compatibility; everything else is GENERIC(1).
+export function toExitCode(error) {
+    if (error instanceof CliError)
+        return error.exitCode;
+    if (error instanceof Error) {
+        if (error.name === 'DiscoveryError')
+            return ExitCode.NETWORK;
+        if (error.name === 'LoopbackError') {
+            return /tim(e|ed) ?out/i.test(error.message) ? ExitCode.TIMEOUT : ExitCode.AUTH_FAILED;
+        }
+    }
+    return ExitCode.GENERIC;
+}
+// Render an error (redacted) and return its exit code. AGENT CONTRACT: under
+// --json/--ndjson the error envelope IS the machine output, so a single
+// {error:{code,message,exit}} JSON document is written to STDOUT — this is what
+// makes `<cmd> --json 2>/dev/null | jq .` work on failure paths too. Human mode
+// writes a line to STDERR. Both routes pass the message through redaction so
+// tokens never leak.
+export function renderError(error, options = {}) {
+    const exitCode = toExitCode(error);
+    const code = error instanceof CliError ? error.code : error instanceof Error ? error.name : 'error';
+    const rawMessage = error instanceof Error ? error.message : String(error);
+    const message = redact(rawMessage);
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify({ error: { code, exit: exitCode, message } })}\n`);
+    }
+    else {
+        process.stderr.write(`Error: ${message}\n`);
+    }
+    return exitCode;
+}

package/dist/lib/exit-codes.d.ts

@@ -0,0 +1,10 @@
+export declare const ExitCode: {
+    readonly SUCCESS: 0;
+    readonly GENERIC: 1;
+    readonly USAGE: 2;
+    readonly AUTH_REQUIRED: 4;
+    readonly AUTH_FAILED: 5;
+    readonly NETWORK: 7;
+    readonly TIMEOUT: 8;
+};
+export type ExitCodeValue = (typeof ExitCode)[keyof typeof ExitCode];

package/dist/lib/exit-codes.js

@@ -0,0 +1,13 @@
+// Single source of truth for CLI exit codes. Agents branch on these, so they
+// are a stable contract across every command (E1/E2/E4 import this, never
+// redefine it). oclif reserves exit 2 for flag-parse/usage errors, so our
+// custom codes start at 4 to avoid collision.
+export const ExitCode = {
+    SUCCESS: 0,
+    GENERIC: 1,
+    USAGE: 2,
+    AUTH_REQUIRED: 4,
+    AUTH_FAILED: 5,
+    NETWORK: 7,
+    TIMEOUT: 8,
+};

package/dist/lib/help.d.ts

@@ -0,0 +1,4 @@
+import { Help } from '@oclif/core';
+export default class FlipstreamHelp extends Help {
+    protected showRootHelp(): Promise<void>;
+}

package/dist/lib/help.js

@@ -0,0 +1,14 @@
+import { Help } from '@oclif/core';
+// Custom root help: append an agent-discovery hint so a coding agent reading
+// `flipstream --help` is pointed straight at the machine-readable catalog. Only
+// the ROOT help is extended — per-command help (and `oclif readme`) is unchanged.
+export default class FlipstreamHelp extends Help {
+    async showRootHelp() {
+        await super.showRootHelp();
+        this.log('');
+        this.log('FOR AGENTS');
+        this.log('  Run `flipstream commands --json` for the full machine-readable command');
+        this.log('  catalog (ids, summaries, flags, args, aliases) — one call, the whole surface.');
+        this.log('  Output/exit-code contract: docs/AGENT-CONTRACT.md.');
+    }
+}

package/dist/lib/output/ndjson.d.ts

@@ -0,0 +1 @@
+export declare function renderNdjson(value: unknown): void;

package/dist/lib/output/ndjson.js

@@ -0,0 +1,16 @@
+// Write NDJSON (newline-delimited JSON): one compact JSON object per line, no
+// enclosing array, no blank lines. An array/iterable emits one line per item; a
+// single object emits exactly one line. stdout = data only (RFC-ish streaming).
+export function renderNdjson(value) {
+    if (value === null || value === undefined)
+        return;
+    const rows = isIterable(value) ? value : [value];
+    let out = '';
+    for (const row of rows)
+        out += `${JSON.stringify(row)}\n`;
+    process.stdout.write(out);
+}
+function isIterable(value) {
+    return (Array.isArray(value) ||
+        (typeof value === 'object' && value !== null && typeof value[Symbol.iterator] === 'function'));
+}

package/dist/lib/output/redact.d.ts

@@ -0,0 +1 @@
+export declare function redact(value: unknown): unknown;