flipstream 0.4.0 → 0.6.0

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

@@ -1,5 +1,7 @@
 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 PLANNER_HOST = "https://query.flipstream.io";
 export declare const ADMIN_HOST = "https://pulse.admin.api.flipstream.io";
+export declare const PULSE_FE_HOST = "https://pulse.flipstream.io";
 export declare const OAUTH_CLI_CLIENT_ID = "a975d9be-5ad6-44a5-8c1f-b95b995f3f70";
-export declare const CONTRACT_VERSION = "1";
+export declare const CONTRACT_VERSION = "3";

package/dist/lib/config/constants.js

@@ -2,11 +2,24 @@
 // 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).
+// This is pulse-data, the raw SQL engine. As of E8 the CLI targets the QUERY
+// PLANNER instead, which proxies to this host with the caller's own token.
 export const DATA_HOST = 'https://pulse.data.query.api.flipstream.io';
+// The query-planner host (E8) — resolves a LOGICAL query (source + dimensions +
+// metrics + filters) into a physical request for pulse-data, asking data-model
+// which table answers it. Serves GET /health, GET /catalog, GET /catalog/{source}
+// and POST /query. It has no identity of its own: it verifies the caller's bearer
+// and forwards that same token onward, so a query runs with the caller's
+// authority and can never reach data they could not reach directly.
+export const PLANNER_HOST = 'https://query.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 Pulse web app. The CLI never calls it — it only builds links INTO it, so a
+// refusal can say where to go and not just what went wrong. The workspace segment
+// is the client_id short-UUID encoded (see api/short-uuid.ts).
+export const PULSE_FE_HOST = 'https://pulse.flipstream.io';
 // 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
@@ -17,4 +30,4 @@ export const ADMIN_HOST = DEFAULT_HOST;
 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';
+export const CONTRACT_VERSION = '3';

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

@@ -7,6 +7,7 @@ export interface HostConfig {
 export interface Config {
     defaultHost?: string;
     hosts?: Record<string, HostConfig>;
+    plannerUrl?: string;
 }
 export declare function configDir(): string;
 export declare function configPath(): string;
@@ -19,3 +20,6 @@ export declare function removeConfigDir(): boolean;
 export declare function resolveHost(options?: {
     hostFlag?: string;
 }): string;
+export declare function resolvePlannerUrl(options?: {
+    urlFlag?: string;
+}): string;

package/dist/lib/config/xdg.js

@@ -1,7 +1,8 @@
 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';
+import { UsageError } from '../errors.js';
+import { DEFAULT_HOST, PLANNER_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;
@@ -95,3 +96,57 @@ export function resolveHost(options = {}) {
     const raw = options.hostFlag ?? readConfig().defaultHost ?? DEFAULT_HOST;
     return raw.replace(/\/+$/, '');
 }
+const LOOPBACK = new Set(['127.0.0.1', '::1', 'localhost']);
+const TRUSTED_SUFFIX = '.flipstream.io';
+// Is this a host we may present the user's bearer token to?
+//
+// The planner URL is NOT like --host. Pointing --host somewhere else is harmless
+// by accident: credentials are loaded FOR that host, so a wrong one simply has
+// none and the command exits 4 before anything is sent. The planner URL is
+// independent of the issuer — the token comes from the real auth host and is then
+// sent wherever this resolves to. So `--url http://attacker.example` would hand a
+// production token to an attacker, and `http://` would put it on the wire in
+// cleartext.
+//
+// Allowed: loopback on any scheme (your own machine, which is where a locally-run
+// planner lives), and HTTPS on flipstream.io. Everything else must be opted into
+// explicitly, because the cost of being wrong here is a leaked credential.
+function isTrustedPlannerHost(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return false;
+    }
+    const host = url.hostname.toLowerCase();
+    if (LOOPBACK.has(host))
+        return true;
+    if (url.protocol !== 'https:')
+        return false;
+    return host === 'flipstream.io' || host.endsWith(TRUSTED_SUFFIX);
+}
+// Resolve the query-planner base URL: --url flag > FLIPSTREAM_PLANNER_URL >
+// config.plannerUrl > PLANNER_HOST. The env override is what lets you point at a
+// locally-run planner (`uvicorn … --port 8080`) without editing config, mirroring
+// QUERY_PLANNER_URL in the planner repo's own reference client.
+//
+// Every source is checked, not just the flag: an env var or a stale config entry
+// sends the token just as effectively as a typed flag, and the config file is the
+// one a caller is least likely to look at.
+export function resolvePlannerUrl(options = {}) {
+    const env = process.env.FLIPSTREAM_PLANNER_URL?.trim();
+    const raw = options.urlFlag ?? (env && env.length > 0 ? env : undefined) ?? readConfig().plannerUrl ?? PLANNER_HOST;
+    const url = raw.replace(/\/+$/, '');
+    // The escape hatch is deliberately awkward and deliberately named: a self-hosted
+    // planner is a real case, but it should be a decision someone made on purpose,
+    // not something a generated command line falls into.
+    if (process.env.FLIPSTREAM_ALLOW_ANY_PLANNER === '1')
+        return url;
+    if (!isTrustedPlannerHost(url)) {
+        throw new UsageError(`Refusing to send your access token to '${url}'. The planner URL must be HTTPS on ` +
+            'flipstream.io, or a loopback address for local development. Set ' +
+            'FLIPSTREAM_ALLOW_ANY_PLANNER=1 to override this deliberately.', 'untrusted_planner_url');
+    }
+    return url;
+}

package/dist/lib/errors.d.ts

@@ -1,7 +1,19 @@
+export interface CliErrorDetails {
+    docs?: string;
+    hint?: string;
+    next?: string[];
+    retryable?: boolean;
+    retryAfterMs?: number;
+    upstreamCode?: string;
+}
+export declare function retryPolicy(retryAfterMs?: number): CliErrorDetails;
 export declare class CliError extends Error {
+    #private;
     readonly code: string;
     readonly exitCode: number;
     constructor(message: string, code: string, exitCode: number);
+    get details(): Readonly<CliErrorDetails>;
+    withDetails(details: CliErrorDetails): this;
 }
 export declare class AuthRequiredError extends CliError {
     constructor(message?: string, code?: 'not_logged_in' | 'session_expired');
@@ -29,10 +41,17 @@ export declare class LoopbackError extends CliError {
 }
 export declare class DataHttpError extends CliError {
     readonly bodyText: string;
+    readonly retryAfterMs: number | undefined;
     readonly status: number;
-    constructor(status: number, bodyText: string);
+    constructor(status: number, bodyText: string, retryAfterMs?: number);
 }
 export declare function toExitCode(error: unknown): number;
+export declare function classifyError(error: unknown): {
+    code: string;
+    details: CliErrorDetails;
+    exitCode: number;
+    message: string;
+};
 export declare function renderError(error: unknown, options?: {
     json?: boolean;
 }): number;

package/dist/lib/errors.js

@@ -1,16 +1,42 @@
 import { ExitCode } from './exit-codes.js';
 import { redact } from './output/redact.js';
+import { sanitizeTerminal } from './output/sanitize.js';
+// {retryable: true} + the server-stated wait — the one shape every retryable
+// mapping site uses, so the policy pair can never half-apply.
+export function retryPolicy(retryAfterMs) {
+    return { retryable: true, retryAfterMs };
+}
 // Base class for every CLI error. Carries a stable string `code` (for agent
 // branching under --json) and the deterministic `exitCode` from ExitCode.
+// `details` is read-only from outside; withDetails is the ONLY mutator, so the
+// merge semantics below cannot be bypassed by direct assignment.
 export class CliError extends Error {
     code;
     exitCode;
+    #details = {};
     constructor(message, code, exitCode) {
         super(message);
         this.name = 'CliError';
         this.code = code;
         this.exitCode = exitCode;
     }
+    get details() {
+        return this.#details;
+    }
+    // Merge remediation details in. Scalars: later wins. `next`: CONCATENATED
+    // (deduped) — enrichment layers add commands, they never silently replace an
+    // earlier layer's guidance. An empty `next` normalizes to absent so there is
+    // exactly one representation of "no suggestion".
+    withDetails(details) {
+        const merged = { ...this.#details, ...details };
+        const next = [...(this.#details.next ?? []), ...(details.next ?? [])];
+        if (next.length > 0)
+            merged.next = [...new Set(next)];
+        else
+            delete merged.next;
+        this.#details = merged;
+        return this;
+    }
 }
 // Not authenticated (or session expired) — exit 4. Two distinct codes let an
 // agent tell "never logged in" apart from "token expired, re-login".
@@ -20,10 +46,18 @@ export class AuthRequiredError extends CliError {
         this.name = 'AuthRequiredError';
     }
     static notLoggedIn(message = 'Not logged in. Run `flipstream auth login`.') {
-        return new AuthRequiredError(message, 'not_logged_in');
+        return new AuthRequiredError(message, 'not_logged_in').withDetails({
+            hint: 'Log in once; the session then refreshes itself.',
+            next: ['flipstream auth login'],
+            retryable: false,
+        });
     }
     static sessionExpired(message = 'Session expired. Run `flipstream auth login`.') {
-        return new AuthRequiredError(message, 'session_expired');
+        return new AuthRequiredError(message, 'session_expired').withDetails({
+            hint: 'The refresh token could not renew the session — a new login is needed.',
+            next: ['flipstream auth login'],
+            retryable: false,
+        });
     }
 }
 // Authentication attempt failed (bad state/iss, token exchange rejected) — exit 5.
@@ -33,18 +67,24 @@ export class AuthFailedError extends CliError {
         this.name = 'AuthFailedError';
     }
 }
-// Network/transport failure (incl. discovery) — exit 7.
+// Network/transport failure (incl. discovery) — exit 7. Retryable BY CLASS:
+// the contract names transport as retryable, and a class default is how the
+// fourteenth mapping site can't forget it (per-site literals are how the first
+// thirteen almost did).
 export class NetworkError extends CliError {
     constructor(message, code = 'network_error') {
         super(message, code, ExitCode.NETWORK);
         this.name = 'NetworkError';
+        this.withDetails({ retryable: true });
     }
 }
 // Operation timed out (e.g. user never finished the browser flow) — exit 8.
+// Retryable by class, like NetworkError.
 export class TimeoutError extends CliError {
     constructor(message, code = 'timeout') {
         super(message, code, ExitCode.TIMEOUT);
         this.name = 'TimeoutError';
+        this.withDetails({ retryable: true });
     }
 }
 // Bad invocation — exit 2 (aligns with oclif's usage exit).
@@ -78,12 +118,17 @@ export class LoopbackError extends CliError {
 // mapper can assign a deterministic exit code. Default exit is GENERIC until E4-3.
 export class DataHttpError extends CliError {
     bodyText;
+    // Milliseconds from the response's Retry-After header, when one was sent.
+    // Carried structurally so the mapper can put it in the envelope rather than
+    // requiring consumers to parse it out of a human-readable message (E11-1).
+    retryAfterMs;
     status;
-    constructor(status, bodyText) {
+    constructor(status, bodyText, retryAfterMs) {
         super(`Data request failed: HTTP ${status}`, 'data_http_error', ExitCode.GENERIC);
         this.name = 'DataHttpError';
         this.status = status;
         this.bodyText = bodyText;
+        this.retryAfterMs = retryAfterMs;
     }
 }
 // Map any thrown value to a deterministic exit code. Known CliErrors carry their
@@ -98,9 +143,33 @@ export function toExitCode(error) {
         if (error.name === 'LoopbackError') {
             return /tim(e|ed) ?out/i.test(error.message) ? ExitCode.TIMEOUT : ExitCode.AUTH_FAILED;
         }
+        // oclif parse/usage errors (missing or unknown flag, bad arg) carry their own
+        // exit — honor it so a missing required flag is exit 2 ("bad invocation").
+        const oclifExit = error.oclif?.exit;
+        if (typeof oclifExit === 'number' && oclifExit > 0)
+            return oclifExit;
     }
     return ExitCode.GENERIC;
 }
+// One classification for every consumer of a thrown value: the renderer below,
+// and the E11-6 sidecar's command-failed entry. Message comes back REDACTED.
+export function classifyError(error) {
+    const exitCode = toExitCode(error);
+    let code = 'error';
+    if (error instanceof CliError)
+        code = error.code;
+    else if (exitCode === ExitCode.USAGE)
+        code = 'usage'; // oclif parse/usage errors
+    else if (error instanceof Error)
+        code = error.name;
+    const rawMessage = error instanceof Error ? error.message : String(error);
+    return {
+        code,
+        details: error instanceof CliError ? error.details : {},
+        exitCode,
+        message: redact(rawMessage),
+    };
+}
 // 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
@@ -108,15 +177,65 @@ export function toExitCode(error) {
 // 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`);
+    const { code, details, exitCode, message } = classifyError(error);
+    if (options.json)
+        writeJsonEnvelope(code, exitCode, message, details);
+    else
+        writeHumanError(message, details);
+    return exitCode;
+}
+// Machine mode is left byte-faithful: JSON.stringify already escapes control
+// characters, so the document stays valid and an agent sees exactly what the
+// service said. Envelope v3 fields are ADDITIVE and absent unless set, so a
+// pre-E11 consumer sees the exact same document it always did.
+function writeJsonEnvelope(code, exitCode, message, details) {
+    const envelope = { code, exit: exitCode, message };
+    // EVERY details string is redacted here, unconditionally — not because any
+    // current producer is untrusted, but so "no upstream content reaches stdout
+    // unredacted" is an invariant of the writer rather than an audit result.
+    if (details.hint !== undefined)
+        envelope.hint = redact(details.hint);
+    if (details.next !== undefined && details.next.length > 0) {
+        envelope.next = details.next.map((command) => redact(command));
     }
-    else {
-        process.stderr.write(`Error: ${message}\n`);
+    if (details.docs !== undefined)
+        envelope.docs = redact(details.docs);
+    if (details.retryable !== undefined)
+        envelope.retryable = details.retryable;
+    // The contract promises retry_after_ms only ever appears alongside
+    // retryable: true — enforce it here so the code makes the doc's promise.
+    if (details.retryable === true && details.retryAfterMs !== undefined) {
+        envelope.retry_after_ms = details.retryAfterMs;
+    }
+    if (details.upstreamCode !== undefined)
+        envelope.upstream_code = redact(details.upstreamCode);
+    process.stdout.write(`${JSON.stringify({ error: envelope })}\n`);
+}
+// Human mode goes to a terminal, where a service-supplied message could carry
+// ANSI/OSC sequences that rewrite the display or reach terminal features.
+function writeHumanError(message, details) {
+    process.stderr.write(`Error: ${sanitizeTerminal(message)}\n`);
+    if (details.hint !== undefined) {
+        process.stderr.write(`  hint: ${sanitizeTerminal(redact(details.hint))}\n`);
+    }
+    for (const command of details.next ?? []) {
+        process.stderr.write(`  next: ${sanitizeTerminal(command)}\n`);
+    }
+    if (details.docs !== undefined)
+        process.stderr.write(`  docs: ${sanitizeTerminal(details.docs)}\n`);
+    if (details.retryable === true) {
+        const wait = details.retryAfterMs === undefined ? '' : ` after ${Math.ceil(details.retryAfterMs / 1000)}s`;
+        process.stderr.write(`  retry: yes — safe to retry${wait}\n`);
+    }
+    else if (details.retryable === false) {
+        // The anti-retry-loop notice (E11-4). The copy follows the data: when a
+        // `next:` step exists the INVOCATION is usually fine (not_logged_in — run
+        // the other command first, then re-run this one unchanged); only without
+        // one is "change the invocation" the right instruction. `retry: yes/no`
+        // is a stable stderr discriminator; the JSON envelope stays the contract.
+        const hasNext = (details.next ?? []).length > 0;
+        process.stderr.write(hasNext
+            ? '  retry: no — not retryable as-is; run the next: step above, then re-run this command\n'
+            : '  retry: no — re-running this unchanged will fail again; change the invocation, or report it\n');
     }
-    return exitCode;
 }

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

@@ -0,0 +1,27 @@
+import { UsageError } from '../errors.js';
+export declare class NoDefaultValueProvided extends UsageError {
+    constructor(unblockFlag?: string);
+}
+export interface DialogStreams {
+    input?: NodeJS.ReadableStream & {
+        isTTY?: boolean;
+    };
+    output?: NodeJS.WritableStream & {
+        isTTY?: boolean;
+    };
+}
+export declare function readAnswer(promptText: string, streams?: DialogStreams): Promise<string>;
+export interface ConfirmOptions {
+    defaultValue?: boolean;
+    fallbackValue?: boolean;
+    streams?: DialogStreams;
+    unblockFlag?: string;
+}
+export declare function confirm(question: string, options?: ConfirmOptions): Promise<boolean>;
+export interface PromptTextOptions {
+    defaultValue?: string;
+    fallbackValue?: string;
+    streams?: DialogStreams;
+    unblockFlag?: string;
+}
+export declare function promptText(question: string, options?: PromptTextOptions): Promise<string>;

package/dist/lib/output/dialogs.js

@@ -0,0 +1,94 @@
+import { createInterface } from 'node:readline';
+import { UsageError } from '../errors.js';
+import { isNonInteractiveOrCI } from './interactivity.js';
+import { sanitizeTerminal } from './sanitize.js';
+// Prompt primitives (E11-4, #103), ported from wrangler's dialogs.ts semantics:
+//
+//   - `defaultValue`  is the HUMAN pre-selection (what Enter means at a TTY).
+//   - `fallbackValue` is what happens when NO human is present. These are
+//     different questions — conflating them is the classic bug (a destructive
+//     prompt whose Enter-default of "yes" silently becomes the CI answer).
+//   - Non-interactive runs NEVER hang and NEVER decide silently: the question
+//     AND the chosen fallback are printed to stderr.
+//   - No safe fallback -> typed NoDefaultValueProvided (exit 2) naming the flag
+//     that unblocks, thrown immediately instead of blocking forever.
+//   - EOF and Ctrl-C at an interactive prompt SETTLE: a readline that closes
+//     without an answer rejects (prompt_aborted, exit 2) — never a silent
+//     exit 0 and never an unresolved await.
+//
+// All prompt text goes to STDERR: prompts are conversation, never data.
+// This module is the ONE prompt chokepoint (headless.ts paste-back included)
+// the way redact.ts is for secrets.
+export class NoDefaultValueProvided extends UsageError {
+    constructor(unblockFlag = '--yes') {
+        super(`This prompt cannot be answered in a non-interactive context. Pass ${unblockFlag} (or run interactively).`, 'non_interactive');
+        this.name = 'NoDefaultValueProvided';
+        this.withDetails({
+            hint: `Re-run with ${unblockFlag} to accept, or run from an interactive terminal.`,
+            retryable: false,
+        });
+    }
+}
+function announceFallback(question, fallback, output) {
+    output.write(`? ${sanitizeTerminal(question)}\n`);
+    output.write(`Using fallback value in non-interactive context: ${sanitizeTerminal(fallback)}\n`);
+}
+// One readline question that ALWAYS settles: resolves with the answer, or
+// rejects when the interface closes unanswered (EOF, Ctrl-C — readline in
+// terminal mode swallows SIGINT and just closes, so `close` is the one signal
+// both paths share).
+export async function readAnswer(promptText, streams = {}) {
+    const input = streams.input ?? process.stdin;
+    const output = streams.output ?? process.stderr;
+    const rl = createInterface({ input, output });
+    try {
+        return await new Promise((resolve, reject) => {
+            let answered = false;
+            rl.on('SIGINT', () => rl.close());
+            rl.on('close', () => {
+                if (!answered) {
+                    reject(new UsageError('Prompt aborted — no answer on stdin.', 'prompt_aborted').withDetails({ retryable: false }));
+                }
+            });
+            rl.question(promptText, (answer) => {
+                answered = true;
+                resolve(answer);
+            });
+        });
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function confirm(question, options = {}) {
+    const { defaultValue = true, fallbackValue, streams = {}, unblockFlag } = options;
+    const output = streams.output ?? process.stderr;
+    if (isNonInteractiveOrCI(process.env, { stderr: streams.output ?? process.stderr, stdin: streams.input ?? process.stdin })) {
+        if (fallbackValue === undefined)
+            throw new NoDefaultValueProvided(unblockFlag);
+        announceFallback(question, fallbackValue ? 'yes' : 'no', output);
+        return fallbackValue;
+    }
+    const suffix = defaultValue ? '[Y/n]' : '[y/N]';
+    const answer = (await readAnswer(`? ${sanitizeTerminal(question)} ${suffix} `, streams)).trim().toLowerCase();
+    if (answer === '')
+        return defaultValue;
+    return answer === 'y' || answer === 'yes';
+}
+// NOTE: an interactive empty answer with no defaultValue resolves to '' — the
+// caller owns validation/re-prompting; this primitive never loops.
+export async function promptText(question, options = {}) {
+    const { defaultValue, fallbackValue, streams = {}, unblockFlag } = options;
+    const output = streams.output ?? process.stderr;
+    if (isNonInteractiveOrCI(process.env, { stderr: streams.output ?? process.stderr, stdin: streams.input ?? process.stdin })) {
+        if (fallbackValue === undefined)
+            throw new NoDefaultValueProvided(unblockFlag);
+        announceFallback(question, fallbackValue, output);
+        return fallbackValue;
+    }
+    const suffix = defaultValue === undefined ? '' : ` (${sanitizeTerminal(defaultValue)})`;
+    const answer = (await readAnswer(`? ${sanitizeTerminal(question)}${suffix} `, streams)).trim();
+    if (answer === '')
+        return defaultValue ?? '';
+    return answer;
+}

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

@@ -0,0 +1,11 @@
+export interface InteractivityProbe {
+    stderr?: {
+        isTTY?: boolean;
+    };
+    stdin?: {
+        isTTY?: boolean;
+    };
+}
+export declare function isInteractive(probe?: InteractivityProbe): boolean;
+export declare function isCI(env?: NodeJS.ProcessEnv): boolean;
+export declare function isNonInteractiveOrCI(env?: NodeJS.ProcessEnv, probe?: InteractivityProbe): boolean;

package/dist/lib/output/interactivity.js

@@ -0,0 +1,48 @@
+// Three-tier interactivity (E11-4, #103) — three DIFFERENT questions, ported
+// from wrangler's split, including the tier most CLIs miss:
+//
+//   isInteractive()        gates CAPABILITIES  (prompts can be answered and
+//                                               SEEN — stdin for answers,
+//                                               stderr because that is where
+//                                               prompts go in this repo)
+//   isNonInteractiveOrCI() gates DECISIONS     (ask, or fall back + announce)
+//   isCI()                 gates DISCLOSURE    (public build logs — redact
+//                                               account identifiers there, but
+//                                               NOT for a local non-interactive
+//                                               agent, which is non-interactive
+//                                               yet not public)
+//
+// A fourth tier — "an LLM is driving", detectable via am-i-vibing — is
+// DEFERRED to E11-5 (#104), which introduces that dependency; agents that
+// allocate a pty can look interactive until then. The escape hatch below
+// (FLIPSTREAM_NO_INPUT) exists for exactly that gap: any wrapper can force the
+// deterministic no-prompt path regardless of what the TTY claims.
+// stdin (can the user answer?) AND stderr (can they SEE the prompt?). stdout
+// is deliberately not consulted: piping stdout is this CLI's DESIGNED usage
+// (`query --json > out.json`), and a human at a terminal doing that can still
+// be prompted — the prompt stream is not the data stream here, which is why
+// this diverges from wrangler's stdin+stdout pair.
+export function isInteractive(probe = {}) {
+    const stdin = probe.stdin ?? process.stdin;
+    const stderr = probe.stderr ?? process.stderr;
+    return Boolean(stdin.isTTY) && Boolean(stderr.isTTY);
+}
+// CI by VALUE, not mere presence: `CI=false`/`CI=0` count as not-CI. This
+// deliberately diverges from ci-info (which treats presence as truth, `false`
+// excepted) — a stale `export CI=true` nearly deploying to the wrong account
+// is the failure class wrangler#9001 documents, and honoring an explicit
+// opt-out is the fix. Vendors that never set CI get explicit checks.
+export function isCI(env = process.env) {
+    const value = env.CI;
+    if (value !== undefined && value !== '' && value !== 'false' && value !== '0')
+        return true;
+    // CI vendors that do not set CI= at all.
+    return Boolean(env.JENKINS_URL ?? env.BUILD_ID ?? env.TEAMCITY_VERSION ?? env.bamboo_buildKey);
+}
+export function isNonInteractiveOrCI(env = process.env, probe = {}) {
+    // The explicit force-deterministic switch: never prompt, take fallbacks.
+    if (env.FLIPSTREAM_NO_INPUT !== undefined && env.FLIPSTREAM_NO_INPUT !== '' && env.FLIPSTREAM_NO_INPUT !== '0') {
+        return true;
+    }
+    return !isInteractive(probe) || isCI(env);
+}

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

@@ -1 +1,2 @@
+export declare function maskAccount(account: string): string;
 export declare function redact(value: unknown): unknown;

package/dist/lib/output/redact.js

@@ -29,6 +29,18 @@ const JWT_SHAPE = /eyJ[\w-]*\.[\w-]+\.[\w-]+/g;
 function redactString(value) {
     return value.replaceAll(SECRET_PARAMS, `$1$2=${MASK}`).replaceAll(JWT_SHAPE, MASK);
 }
+// Account mask for PUBLIC-log contexts (E11-4's CI disclosure tier):
+// 'michel@flipstream.io' -> '***@flipstream.io'; anything not email-shaped ->
+// '***'. The local part is dropped ENTIRELY — on a small team an initial plus
+// the domain identifies exactly one person, which defeats the point. This is
+// deliberately NOT part of redact(): an account name is not a secret, and the
+// human line is the only consumer — --json keeps the stable value by contract.
+export function maskAccount(account) {
+    const at = account.lastIndexOf('@');
+    if (at > 0 && at < account.length - 1)
+        return `***${account.slice(at)}`;
+    return '***';
+}
 // Return a redacted deep copy of `value` (never mutates the input). Applied to
 // every log/debug/error path so tokens never reach stdout/stderr/logs.
 export function redact(value) {

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

@@ -0,0 +1,3 @@
+export declare function currentRunLogPath(): null | string;
+export declare function resetRunLog(): void;
+export declare function appendRunLog(line: string): void;