flipstream 0.4.0 → 0.6.0

package/dist/lib/output/runlog.js

@@ -0,0 +1,72 @@
+import { appendFileSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+// Per-run log file (E11-6, #105) under the XDG state dir. EVERY line offered is
+// written regardless of terminal verbosity — post-mortems need context and
+// order, not just the lines that happened to be shown. Contents pass through
+// the caller's redaction before they get here (trace.ts / base.ts).
+//
+// Lazy: no file is created until the first line, so commands that log nothing
+// leave nothing behind.
+const MAX_LOG_FILES = 20;
+function stateDir() {
+    const xdg = process.env.XDG_STATE_HOME?.trim();
+    const base = xdg && xdg.length > 0 ? xdg : join(homedir(), '.local', 'state');
+    return join(base, 'flipstream-cli', 'logs');
+}
+let runLogPath = null;
+let runLogBroken = false;
+// The current run's log path — null until something has been written.
+export function currentRunLogPath() {
+    return runLogPath;
+}
+// Test seam + long-lived-process hygiene.
+export function resetRunLog() {
+    runLogPath = null;
+    runLogBroken = false;
+}
+function timestampName() {
+    const iso = new Date().toISOString().replaceAll(':', '-').replace(/\..+$/, '');
+    return `${iso}-${process.pid}.log`;
+}
+// ISO-prefixed names sort chronologically, so pruning is a name sort — no
+// stat() calls needed.
+function prune(dir) {
+    try {
+        const logs = readdirSync(dir)
+            .filter((name) => name.endsWith('.log'))
+            .sort();
+        // +1: prune runs BEFORE the new file is created, so keep MAX-1 old ones.
+        for (const name of logs.slice(0, Math.max(0, logs.length + 1 - MAX_LOG_FILES))) {
+            rmSync(join(dir, name), { force: true });
+        }
+    }
+    catch {
+        // Pruning is hygiene, never worth failing a command over.
+    }
+}
+export function appendRunLog(line) {
+    if (runLogBroken)
+        return;
+    try {
+        if (runLogPath === null) {
+            const dir = stateDir();
+            // 0700/0600: these files hold argv and error messages that echo request
+            // payloads — not for other local users (the Python reference used 0600).
+            mkdirSync(dir, { mode: 0o700, recursive: true });
+            prune(dir);
+            const candidate = join(dir, timestampName());
+            appendFileSync(candidate, `${new Date().toISOString()} ${line}\n`, { mode: 0o600 });
+            runLogPath = candidate;
+            return;
+        }
+        appendFileSync(runLogPath, `${new Date().toISOString()} ${line}\n`);
+    }
+    catch {
+        // A read-only or exotic filesystem must never break the actual command.
+        // Null the path too: never point currentRunLogPath() at a file that the
+        // failed write means does not exist.
+        runLogBroken = true;
+        runLogPath = null;
+    }
+}

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

@@ -0,0 +1,2 @@
+export declare function sanitizeTerminal(value: string): string;
+export declare function sanitizeDeep<T>(value: T): T;

package/dist/lib/output/sanitize.js

@@ -0,0 +1,57 @@
+// Strip terminal control sequences from text the SERVER chose.
+//
+// `redact()` masks token-shaped content but leaves control bytes intact, so any
+// human-mode path that prints a service-supplied string trusts those bytes. A
+// hostile or malformed value can then rewrite what the terminal displays —
+// overwrite earlier lines, hide text, fake a prompt — or reach terminal features
+// like clipboard-setting OSC sequences.
+//
+// TWO RULES make this safe to apply broadly:
+//
+// 1. It runs on INPUT, never on rendered output. @oclif/table adds its own ANSI
+//    for borders and colour; sanitizing the finished table would strip that too.
+//    So cell VALUES are cleaned before rendering, not the rendered string.
+//
+// 2. It never touches machine output. JSON.stringify already escapes control
+//    characters, so --json is structurally safe without help — and it must stay
+//    byte-faithful to what the service sent. Redaction is the machine-mode
+//    protection; this is the human-mode one. Deliberately separate.
+// ESC- and CSI-introduced sequences: colour, cursor movement, and OSC (which can
+// carry a payload terminated by BEL or ST). Matching the introducer AND its
+// payload matters - stripping a bare ESC would leave "[31m" as visible garbage.
+// This is the well-known ansi-regex pattern, inlined rather than depended on.
+// OSC gets its own pattern because its payload is free text up to a terminator
+// (BEL, or ST as ESC-backslash / 0x9C) and can contain spaces — a window title
+// does. The generic CSI pattern below stops at the first space, which would leave
+// the tail of an OSC visible. Non-greedy, so an unterminated OSC simply does not
+// match and its ESC is removed by CONTROL instead.
+// eslint-disable-next-line no-control-regex
+const OSC = /[\u001B\u009D]\][\S\s]*?(?:\u0007|\u001B\\|\u009C)/g;
+const ANSI = 
+// eslint-disable-next-line no-control-regex
+/[\u001B\u009B][[\]()#;?]*(?:(?:(?:(?:;[\w#&./:=?@~-]+)*|[\dA-Za-z]+(?:;[\w#&./:=?@~-]*)*)?\u0007)|(?:(?:\d{1,4}(?:;\d{0,4})*)?[\dA-PR-TZcf-nqry=><~]))/g;
+// Whatever survives: C0 minus \t and \n (legitimate inside a message), DEL, and
+// C1. \r IS stripped - a carriage return overwrites the line just printed, which
+// is one of the cheaper ways to hide text. Also catches a lone ESC or CSI that
+// did not form a complete sequence above.
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u0008\u000B-\u001F\u007F-\u009F]/g;
+export function sanitizeTerminal(value) {
+    return value.replaceAll(OSC, '').replaceAll(ANSI, '').replaceAll(CONTROL, '');
+}
+// Sanitize every string in a structure, preserving its shape. Used for table rows,
+// where the values are service-supplied but the keys are ours.
+export function sanitizeDeep(value) {
+    if (typeof value === 'string')
+        return sanitizeTerminal(value);
+    if (Array.isArray(value)) {
+        return value.map((item) => sanitizeDeep(item));
+    }
+    if (value !== null && typeof value === 'object') {
+        const out = {};
+        for (const [key, val] of Object.entries(value))
+            out[key] = sanitizeDeep(val);
+        return out;
+    }
+    return value;
+}

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

@@ -0,0 +1,30 @@
+interface SessionEntry {
+    argv: string[];
+    cli_version: string;
+    contract_version: string;
+    log_file_path: null | string;
+    type: 'session';
+    version: 1;
+}
+interface ResultEntry {
+    command: string;
+    duration_ms: number;
+    exit: 0;
+    type: 'result';
+    version: 1;
+}
+interface CommandFailedEntry {
+    command: string;
+    error_code: string;
+    exit: number;
+    log_file_path: null | string;
+    message: string;
+    retry_after_ms?: number;
+    type: 'command-failed';
+    version: 1;
+}
+export type OutputEntry = CommandFailedEntry | ResultEntry | SessionEntry;
+export declare function resetSidecar(): void;
+export declare function sidecarEnabled(): boolean;
+export declare function writeOutputEntry(entry: OutputEntry): void;
+export {};

package/dist/lib/output/sidecar.js

@@ -0,0 +1,58 @@
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { redact } from './redact.js';
+let cachedPath;
+let warned = false;
+// Test seam (env changes between tests).
+export function resetSidecar() {
+    cachedPath = undefined;
+    warned = false;
+}
+function timestampName() {
+    const iso = new Date().toISOString().replaceAll(':', '-').replace(/\..+$/, '');
+    return `flipstream-output-${iso}-${process.pid}.ndjson`;
+}
+function resolvePath() {
+    const file = process.env.FLIPSTREAM_OUTPUT_FILE?.trim();
+    if (file)
+        return file;
+    const dir = process.env.FLIPSTREAM_OUTPUT_FILE_DIRECTORY?.trim();
+    if (dir) {
+        mkdirSync(dir, { mode: 0o700, recursive: true });
+        return join(dir, timestampName());
+    }
+    return null;
+}
+export function sidecarEnabled() {
+    try {
+        cachedPath ??= resolvePath();
+    }
+    catch {
+        cachedPath = null;
+    }
+    return cachedPath !== null;
+}
+// Append one entry. Failures are swallowed after one warning-free attempt —
+// a broken sidecar path must never break the actual command.
+export function writeOutputEntry(entry) {
+    try {
+        cachedPath ??= resolvePath();
+        if (cachedPath === null)
+            return;
+        const record = { ...redact(entry), timestamp: new Date().toISOString() };
+        // 0600: the sidecar holds argv and command outcomes — not for other local
+        // users. mode applies only at creation, which is what we want.
+        appendFileSync(cachedPath, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+    }
+    catch (error) {
+        // A truncated sidecar reads to the supervisor like a run that crashed
+        // before its result entry — so say so ONCE, then go quiet. Only the CLI
+        // knows the difference, and only at the moment it happens.
+        if (!warned) {
+            warned = true;
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`sidecar write failed (${cachedPath ?? 'unknown path'}): ${message}; disabling for this run\n`);
+        }
+        cachedPath = null;
+    }
+}

package/dist/lib/output/table.js

@@ -1,4 +1,5 @@
 import { makeTable } from '@oclif/table';
+import { sanitizeDeep } from './sanitize.js';
 // Render a table to STDOUT — HUMAN output ONLY. Callers invoke this from a
 // respond/respondList human formatter, which never runs under --json/--ndjson, so
 // the agent contract (machine output is pure JSON/NDJSON) is preserved. Honors
@@ -8,10 +9,13 @@ export function renderTable(data, columns, emptyMessage = '(none)') {
         process.stdout.write(`${emptyMessage}\n`);
         return;
     }
+    // Sanitize the DATA, not the rendered table: makeTable adds its own ANSI for
+    // borders and colour, so cleaning the finished string would strip that too.
+    // Every value here came from a service, so none of it may carry control bytes.
     const table = makeTable({
         borderStyle: 'vertical-with-outline',
         columns,
-        data,
+        data: sanitizeDeep(data),
         noStyle: Boolean(process.env.NO_COLOR),
         overflow: 'truncate-end',
     });

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

@@ -0,0 +1,11 @@
+export declare function enableStderrTrace(): void;
+export declare function resetTrace(): void;
+export declare function traceRequest(method: string, url: string, body?: unknown): void;
+export declare function traceFailure(method: string, url: string, reason: string, ms: number): void;
+export declare function traceResponse(response: {
+    bodyText?: string;
+    method: string;
+    ms: number;
+    status: number;
+    url: string;
+}): void;

package/dist/lib/output/trace.js

@@ -0,0 +1,89 @@
+import { redact } from './redact.js';
+import { appendRunLog, currentRunLogPath } from './runlog.js';
+import { sanitizeTerminal } from './sanitize.js';
+// Wire tracing (E11-6, #105): one line per request and response for every
+// first-party API call. Two sinks with different rules:
+//
+//   run log  — always receives every line (context + order for post-mortems)
+//   stderr   — only when enabled (FLIPSTREAM_LOG=debug or --verbose), which is
+//              also what fixes #92: trace lines are emitted AS THEY HAPPEN, so
+//              the failure path has diagnostics too, not just the happy path.
+//
+// Bodies and headers are OMITTED by default. FLIPSTREAM_LOG_SANITIZE=false
+// includes bodies — still through redact(), which is the floor that never
+// comes off (tokens never reach any sink).
+let stderrEnabled = false;
+// Called once per command from BaseCommand.init (flag) — the env var works
+// even before that, for code paths that run pre-parse.
+export function enableStderrTrace() {
+    stderrEnabled = true;
+}
+// Test seam.
+export function resetTrace() {
+    stderrEnabled = false;
+    bodyNoticeShown = false;
+}
+function debugEnv() {
+    return process.env.FLIPSTREAM_LOG === 'debug';
+}
+function includeBodies() {
+    return process.env.FLIPSTREAM_LOG_SANITIZE === 'false';
+}
+let bodyNoticeShown = false;
+function emit(line) {
+    // The run log is a file — it keeps the byte-faithful line for post-mortem.
+    // stderr is a terminal, so a body line under FLIPSTREAM_LOG_SANITIZE=false
+    // could carry cursor/erase escapes that rewrite the display; sanitize it
+    // there (every other human-facing writer already does).
+    appendRunLog(line);
+    if (stderrEnabled || debugEnv())
+        process.stderr.write(`${sanitizeTerminal(line)}\n`);
+}
+// FLIPSTREAM_LOG_SANITIZE=false writes full bodies to the run log even with no
+// on-screen tracing — so the operator learns, once, that turning off
+// sanitization also turned on persistence (E11-6 review).
+function noticeBodiesPersist() {
+    if (bodyNoticeShown || stderrEnabled || debugEnv())
+        return;
+    bodyNoticeShown = true;
+    const path = currentRunLogPath();
+    process.stderr.write(`FLIPSTREAM_LOG_SANITIZE=false: unsanitized request/response bodies are being written to ${path ?? 'the run log'}\n`);
+}
+export function traceRequest(method, url, body) {
+    emit(`-- REQUEST ${method} ${redact(url)}`);
+    if (body === undefined)
+        return;
+    if (includeBodies()) {
+        noticeBodiesPersist();
+        emit(`   body: ${JSON.stringify(redact(body))}`);
+    }
+    else {
+        emit('   body: omitted; set FLIPSTREAM_LOG_SANITIZE=false to include redacted data');
+    }
+}
+export function traceFailure(method, url, reason, ms) {
+    emit(`-- FAILED ${method} ${redact(url)} (${ms} ms): ${redact(reason)}`);
+}
+// A body STRING gets structural redaction: parsed as JSON when possible so
+// secret-NAMED keys are masked (string-level redaction only catches
+// param-style and JWT-shaped values, not `{"access_token": "..."}`).
+function redactBodyText(bodyText) {
+    try {
+        return JSON.stringify(redact(JSON.parse(bodyText)));
+    }
+    catch {
+        return redact(bodyText);
+    }
+}
+export function traceResponse(response) {
+    emit(`-- RESPONSE ${response.status} ${response.method} ${redact(response.url)} (${response.ms} ms)`);
+    if (response.bodyText === undefined || response.bodyText.length === 0)
+        return;
+    if (includeBodies()) {
+        noticeBodiesPersist();
+        emit(`   body: ${redactBodyText(response.bodyText)}`);
+    }
+    else {
+        emit('   body: omitted; set FLIPSTREAM_LOG_SANITIZE=false to include redacted data');
+    }
+}

package/dist/lib/planner/catalog.d.ts

@@ -0,0 +1,26 @@
+export interface CatalogItem {
+    description: string;
+    label: string;
+    name: string;
+    type: string;
+}
+export interface CatalogSource {
+    customDimensionsMax?: number;
+    description: string;
+    dimensions: CatalogItem[];
+    label: string;
+    metrics: CatalogItem[];
+    name: string;
+}
+export interface CatalogSourceSummary {
+    dimensions: number;
+    label: string;
+    metrics: number;
+    name: string;
+}
+export interface CatalogIndex {
+    defaultSource?: string;
+    sources: CatalogSourceSummary[];
+}
+export declare function parseCatalogIndex(payload: unknown): CatalogIndex;
+export declare function parseCatalogSource(payload: unknown): CatalogSource;

package/dist/lib/planner/catalog.js

@@ -0,0 +1,60 @@
+// Narrowing for the catalog documents the planner serves. The wire payload is
+// untrusted, so it arrives as `unknown` and every field is proven here rather
+// than asserted — the repo rule for API boundaries (see api/http.ts).
+//
+// What the planner publishes is an ALLOWLIST projection built by data-model:
+// name, label, description, format and nothing else. `field`, `agg_func`,
+// `table`, `grain`, `tier` and `routing` are absent by construction, not by
+// filtering. We deliberately do not re-filter here — inventing a second
+// allowlist would hide the day the first one breaks.
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function str(value, fallback = '') {
+    return typeof value === 'string' ? value : fallback;
+}
+function arr(value) {
+    return Array.isArray(value) ? value : [];
+}
+function parseItem(value) {
+    const record = asRecord(value) ?? {};
+    // `format` may be absent or null; its `type` is what the human table shows.
+    const format = asRecord(record.format) ?? {};
+    return {
+        description: str(record.description),
+        label: str(record.label),
+        name: str(record.name),
+        type: str(format.type),
+    };
+}
+// GET /catalog — the index of sources.
+export function parseCatalogIndex(payload) {
+    const record = asRecord(payload) ?? {};
+    const sources = arr(record.sources).map((entry) => {
+        const source = asRecord(entry) ?? {};
+        return {
+            dimensions: arr(source.dimensions).length,
+            label: str(source.label),
+            metrics: arr(source.metrics).length,
+            name: str(source.name),
+        };
+    });
+    const defaultSource = typeof record.defaultSource === 'string' ? record.defaultSource : undefined;
+    return { defaultSource, sources };
+}
+// GET /catalog/<source> — one source's full vocabulary.
+export function parseCatalogSource(payload) {
+    const record = asRecord(payload) ?? {};
+    const custom = asRecord(record.customDimensions);
+    const max = custom !== undefined && typeof custom.max === 'number' ? custom.max : undefined;
+    return {
+        customDimensionsMax: max,
+        description: str(record.description),
+        dimensions: arr(record.dimensions).map((item) => parseItem(item)),
+        label: str(record.label),
+        metrics: arr(record.metrics).map((item) => parseItem(item)),
+        name: str(record.name),
+    };
+}

package/dist/lib/planner/client.d.ts

@@ -0,0 +1,14 @@
+import { type RefreshDeps } from '../api/retry.js';
+export interface PlannerCallOptions {
+    timeoutMs?: number;
+}
+export interface PlannerClient {
+    getCatalog(source?: string, options?: PlannerCallOptions): Promise<unknown>;
+    postQuery(body: unknown, options?: PlannerCallOptions): Promise<unknown>;
+}
+export interface AuthedPlannerClientDeps extends RefreshDeps {
+    timeoutMs?: number;
+    url?: string;
+}
+export declare function createAuthedPlannerClient(deps: AuthedPlannerClientDeps): PlannerClient;
+export declare function getPlannerHealth(url: string, options?: PlannerCallOptions): Promise<unknown>;

package/dist/lib/planner/client.js

@@ -0,0 +1,47 @@
+import { requestJson } from '../api/http.js';
+import { withFreshToken } from '../api/retry.js';
+import { PLANNER_HOST } from '../config/constants.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+function rstrip(host) {
+    return host.replace(/\/+$/, '');
+}
+// The authed QUERY-PLANNER client. Transport only: it knows the two paths and
+// nothing about what a catalog document or a LogicalRequest contains.
+//
+// Wrapped in the SAME withFreshToken 401->refresh->retry-once used by the data and
+// admin clients, and refresh always targets the AUTH issuer (deps.authHost) rather
+// than the planner — the planner issues nothing, it only verifies and forwards.
+export function createAuthedPlannerClient(deps) {
+    const base = rstrip(deps.url ?? PLANNER_HOST);
+    const defaultTimeout = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    return {
+        getCatalog(source, options = {}) {
+            // encodeURIComponent so a source name can never escape the path segment.
+            const path = source === undefined ? '/catalog' : `/catalog/${encodeURIComponent(source)}`;
+            return withFreshToken(deps, (token) => requestJson({
+                method: 'GET',
+                timeoutMs: options.timeoutMs ?? defaultTimeout,
+                token,
+                url: `${base}${path}`,
+            }));
+        },
+        postQuery(body, options = {}) {
+            return withFreshToken(deps, (token) => requestJson({
+                body,
+                method: 'POST',
+                timeoutMs: options.timeoutMs ?? defaultTimeout,
+                token,
+                url: `${base}/query`,
+            }));
+        },
+    };
+}
+// GET /health — the one endpoint that takes NO token (it is open on the planner),
+// so it answers "is it me or is it them" before any auth debugging starts.
+export async function getPlannerHealth(url, options = {}) {
+    return requestJson({
+        method: 'GET',
+        timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        url: `${rstrip(url)}/health`,
+    });
+}

package/dist/lib/planner/connection.d.ts

@@ -0,0 +1,14 @@
+import { type AdminClient } from '../api/admin-client.js';
+export interface ResolveOptions {
+    note?: (message: string) => void;
+}
+export interface ResolvedConnection {
+    active: boolean;
+    clientId: string;
+    id: string;
+    name: string;
+}
+export declare function connectionsUrl(clientId: string): string;
+export declare function assertConnectionActive(connection: ResolvedConnection): void;
+export declare function resolveConnection(client: AdminClient, value: string, options?: ResolveOptions): Promise<ResolvedConnection>;
+export declare function connectionIsVisible(client: AdminClient, connectionId: string): Promise<boolean | undefined>;

package/dist/lib/planner/connection.js

@@ -0,0 +1,139 @@
+import { fetchConnections } from '../api/connections.js';
+import { isUuid } from '../api/ids.js';
+import { projectConnection } from '../api/projections.js';
+import { uuidToShort } from '../api/short-uuid.js';
+import { PULSE_FE_HOST } from '../config/constants.js';
+import { CliError, UsageError } from '../errors.js';
+import { ExitCode } from '../exit-codes.js';
+const MAX_LISTED = 10;
+// Read a string field, falling back into the projected `raw` passthrough.
+// projectConnection() promotes only its core fields (name, type, active, …), so
+// `slug` — which the admin API does carry — survives ONLY inside `raw`. Reading
+// just the top level would make slug matching silently never fire.
+// Candidate connections as "  <id>  <name>" lines, capped, so a refusal names what
+// the search found and the retry is a copy-paste rather than a second guess.
+function listed(candidates) {
+    return candidates
+        .slice(0, MAX_LISTED)
+        .map((record) => `  ${label(record, 'id')}  ${label(record, 'name')}`)
+        .join('\n');
+}
+function label(record, key) {
+    const direct = record[key];
+    if (typeof direct === 'string')
+        return direct;
+    const raw = record.raw;
+    const nested = raw?.[key];
+    return typeof nested === 'string' ? nested : '';
+}
+// A projected admin record → the few fields the query path cares about.
+// `active` defaults to TRUE when the field is missing: this check is a
+// convenience over the server's, and inventing "inactive" from an absent field
+// would block a working connection on a schema change. The server (pulse-data#49)
+// is what actually enforces this.
+function toResolved(record) {
+    const active = record.active ?? record.raw?.active;
+    return {
+        active: active !== false,
+        clientId: label(record, 'client_id'),
+        id: label(record, 'id'),
+        name: label(record, 'name'),
+    };
+}
+// Where a human goes to switch a connection back on. The workspace segment is the
+// client_id in pulse-fe's short-UUID encoding — derived from the record we already
+// hold, so building this costs no extra request.
+export function connectionsUrl(clientId) {
+    if (!isUuid(clientId))
+        return `${PULSE_FE_HOST}/client-space`;
+    return `${PULSE_FE_HOST}/client-space/${uuidToShort(clientId)}/connections`;
+}
+// Refuse a query against an inactive connection.
+//
+// This is a CONVENIENCE, not the control. It saves a round trip and turns an
+// opaque engine failure into an instruction, but the authoritative refusal lives
+// in pulse-data (#49) — a check on this side of the wire can be edited out by
+// anyone running a modified client, so it must never be the only thing standing
+// between an inactive connector and its data.
+export function assertConnectionActive(connection) {
+    if (connection.active)
+        return;
+    const where = connection.name.length > 0 ? `'${connection.name}'` : connection.id;
+    throw new CliError(`Connection ${where} is inactive, so it cannot be queried. Reactivate it at ` +
+        `${connectionsUrl(connection.clientId)}`, 'connection_inactive', ExitCode.USAGE);
+}
+// A UUID passes through; anything else is looked up by name or slug.
+//
+// Ambiguity is REFUSED rather than resolved to the first hit. Querying the wrong
+// connection returns numbers rather than an error, and numbers are the one
+// failure nobody notices — so a name that matches two connections is a usage
+// error listing both, not a coin flip.
+//
+// The lookup reads the same pulse-admin list that pulse-data resolves against,
+// with the same token and the same connections:read scope, so what resolves here
+// is exactly what the query can reach and nothing more.
+export async function resolveConnection(client, value, options = {}) {
+    // A UUID still costs one GET. It used to pass straight through, but the caller
+    // needs `active`, and skipping the lookup for the id form would make "use the
+    // UUID instead of the name" a one-word bypass of the inactive check.
+    if (isUuid(value)) {
+        const raw = await client.get(`/connections/${value}`);
+        return toResolved(projectConnection(raw));
+    }
+    const { records } = await fetchConnections(client, { all: true, limit: 50, offset: 0, q: value });
+    // Only an EXACT name/slug hit is an identity. The server's free-text results are
+    // SUGGESTIONS: 'acme' matching the single connection 'acme-staging' is not the
+    // user naming it, and resolving to it would query a connection they never asked
+    // for — which returns numbers rather than an error, and numbers are the one
+    // failure nobody notices. Refusing costs one retry; guessing costs a decision
+    // made on the wrong client's data.
+    const folded = value.toLowerCase();
+    const exact = records.filter((record) => label(record, 'name').toLowerCase() === folded || label(record, 'slug').toLowerCase() === folded);
+    if (exact.length === 0) {
+        if (records.length === 0) {
+            throw new UsageError(`No connection matches '${value}' — run \`flipstream connections list\` to see yours.`);
+        }
+        // Name what the search DID find, so the retry is a copy-paste rather than a
+        // second guess.
+        throw new UsageError(`No connection is named exactly '${value}'. Did you mean:\n${listed(records)}`);
+    }
+    if (exact.length > 1) {
+        throw new UsageError(`'${value}' matches ${exact.length} connections:\n${listed(exact)}`);
+    }
+    const found = exact[0] ?? {};
+    const resolved = toResolved(found);
+    if (resolved.id.length === 0)
+        throw new UsageError(`Connection '${value}' resolved to a record with no id.`);
+    options.note?.(`connection '${value}' → ${resolved.id} (${resolved.name})`);
+    return resolved;
+}
+// Can this token resolve that connection? `undefined` when we could not find out.
+//
+// Only ever used to EXPLAIN a failure that already happened. pulse-data resolves
+// the connection through pulse-admin as the caller, so a connection belonging to
+// another account fails there — and the planner is right not to say which, since
+// the engine's own words name tables. This asks the same question from the
+// outside, where the answer is the caller's to know.
+export async function connectionIsVisible(client, connectionId) {
+    // This id can come from an opaque --body, so it is caller-controlled and goes
+    // straight into a path. `../../oauth/token` normalises out of /connections/
+    // entirely, which would point an authenticated GET at another admin route. Same
+    // origin and the caller's own token, so the blast radius is small — but this
+    // CLI is driven by agents that may be working from untrusted content, and a
+    // non-UUID is not a connection id in any case. Undefined is also the honest
+    // answer: we cannot determine visibility for something that cannot be one.
+    if (!isUuid(connectionId))
+        return undefined;
+    try {
+        await client.get(`/connections/${connectionId}`);
+        return true;
+    }
+    catch (error) {
+        const { status } = error;
+        if (status === 404)
+            return false;
+        // 403, 5xx, a timeout: we genuinely do not know, and guessing here would put
+        // a confident wrong hint in front of a real failure.
+        return undefined;
+    }
+}

package/dist/lib/planner/diagnose.d.ts

@@ -0,0 +1,8 @@
+import { type CliError } from '../errors.js';
+export interface DiagnoseOptions {
+    bin: string;
+    body: unknown;
+    fetchCatalog: (source?: string) => Promise<unknown>;
+    onSkip?: (reason: string) => void;
+}
+export declare function attachVocabularyDiagnosis(error: CliError, options: DiagnoseOptions): Promise<void>;