flipstream 0.5.0 → 0.6.0

package/dist/lib/api/short-uuid.js

@@ -0,0 +1,30 @@
+// UUID → the 22-character short id pulse-fe puts in its URLs.
+//
+// A port of `short-uuid`'s default translator (flickrBase58), which is what
+// front_end/src/utils/routing/urlEncoding.ts uses (`uuidToShort`). Ported rather
+// than depended on: this is a fixed alphabet and one bignum conversion, and a
+// new runtime dependency on a CLI that ships five is a worse trade than 20 lines
+// with a locked-down test.
+//
+// The correctness risk here is specific and quiet: a wrong encoding does not
+// throw, it produces a plausible-looking URL that 404s. So the test carries a
+// vector captured from a REAL pulse-fe URL, not one this code generated.
+//
+// flickrBase58 omits 0/O/I/l — the characters people misread when copying a link
+// out of a terminal, which is the whole reason the alphabet exists.
+const ALPHABET = '123456789abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ';
+const SHORT_LENGTH = 22;
+// Left-padded to a fixed 22 chars, matching short-uuid: without the pad, a UUID
+// with leading zero bytes encodes shorter and the route stops resolving.
+export function uuidToShort(uuid) {
+    const hex = uuid.replaceAll('-', '');
+    let value = BigInt(`0x${hex}`);
+    const base = BigInt(ALPHABET.length);
+    let out = '';
+    while (value > 0n) {
+        const digit = Number(value % base);
+        out = `${ALPHABET[digit] ?? ''}${out}`;
+        value /= base;
+    }
+    return out.padStart(SHORT_LENGTH, ALPHABET[0] ?? '1');
+}

package/dist/lib/auth/flow.js

@@ -8,7 +8,14 @@ import { DEFAULT_REDIRECT_TIMEOUT_MS, startLoopback } from './loopback.js';
 import { generatePair } from './pkce.js';
 import { buildAuthorizeUrl } from './provider.js';
 export { decodeJwtClaimsUnverified } from './claims.js';
-const DEFAULT_SCOPES = ['read', 'write'];
+// The whole forwarding chain, not just the first hop (E8-0). The query planner
+// presents this token to pulse-data (grid_data:read), and pulse-data presents it
+// onward to pulse-admin to resolve the connection (connections:read). A caller
+// holding only the first gets a 403 raised two services away and wrapped as an
+// opaque PULSE_SERVICE_ERROR, which says nothing about what to fix.
+//
+// `read`/`write` stay for the admin API (workspaces, connections, log).
+const DEFAULT_SCOPES = ['read', 'write', 'grid_data:read', 'connections:read'];
 function tokenErrorMessage(status, body) {
     try {
         const parsed = JSON.parse(body);

package/dist/lib/auth/headless.js

@@ -1,5 +1,5 @@
-import { createInterface } from 'node:readline';
 import { LoopbackError } from '../errors.js';
+import { readAnswer } from '../output/dialogs.js';
 // True when there is no interactive browser to drive the OAuth redirect: an
 // explicit open() failure, a CI run, an SSH session, or Linux without a display.
 export function detectHeadless(probe = {}) {
@@ -44,18 +44,22 @@ export function parseRedirect(pasted, expectedState) {
     return { code, state };
 }
 // Default manual-mode reader: print the authorize URL + instructions to STDERR
-// (stdout stays clean for the eventual JSON) and read the pasted redirect from stdin.
-export function defaultPromptRedirect(authorizeUrl) {
+// (stdout stays clean for the eventual JSON) and read the pasted redirect from
+// stdin — through dialogs.readAnswer, the ONE prompt chokepoint, so EOF and
+// Ctrl-C settle (prompt_aborted) instead of leaving an unresolved promise
+// (E11-4 review: this file used to carry a second, unhardened readline).
+export async function defaultPromptRedirect(authorizeUrl) {
     process.stderr.write('\nNo browser is available here (headless / SSH / CI).\n' +
         'Open this URL in a browser on any machine and approve access:\n\n' +
         `  ${authorizeUrl}\n\n` +
         'Your browser will then try to load a http://127.0.0.1/... address that fails to\n' +
         'connect. Copy that full URL from the address bar and paste it below.\n\n');
-    const rl = createInterface({ input: process.stdin, output: process.stderr });
-    return new Promise((resolve) => {
-        rl.question('Paste the redirected URL here: ', (answer) => {
-            rl.close();
-            resolve(answer);
-        });
-    });
+    try {
+        return await readAnswer('Paste the redirected URL here: ');
+    }
+    catch {
+        // Aborted/EOF: the flow's own empty-input handling produces the right
+        // headless_no_input error with its auth exit code.
+        return '';
+    }
 }

package/dist/lib/auth/refresh.js

@@ -1,3 +1,4 @@
+import { freshAccessToken } from '../store/credentials.js';
 import { createStore } from '../store/index.js';
 import { fetchMetadata } from './discovery.js';
 // Silent refresh via the refresh_token grant. Returns the new access token, or
@@ -43,7 +44,26 @@ export async function refresh(host, options = {}) {
         clearTimeout(timer);
     }
     if (response.status >= 400 && response.status < 500) {
-        store.clear(host); // invalid_grant / revoked session — force re-login.
+        // COMPARE-AND-DELETE. A 4xx here usually means invalid_grant, and with refresh-
+        // token rotation the most likely reason is that ANOTHER process already
+        // refreshed: it exchanged this same token, got a new one, and saved it. Our
+        // token is dead — but the one now in the keychain is not, and clearing blindly
+        // would delete a working session and log the user out for no reason.
+        //
+        // Re-read past any cache and only delete if what is stored is still the token
+        // we just tried. Note this race predates the read cache: two processes could
+        // always interleave a load and a rotation.
+        const current = store.reload(host);
+        if (current !== null && current.refreshToken !== creds.refreshToken) {
+            // Someone else won the race and their session is live. HAND OFF to it rather
+            // than reporting failure: returning null here would surface as "Session
+            // expired. Run `flipstream auth login`" while perfectly good credentials sit
+            // in the keychain — telling the user to fix something that is not broken.
+            // May still be null if their access token is also stale; either way we do
+            // not clear a session we do not own.
+            return freshAccessToken(current);
+        }
+        store.clear(host); // genuinely invalid_grant / revoked session — force re-login.
         return null;
     }
     if (!response.ok)

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

@@ -11,10 +11,14 @@ export declare abstract class BaseCommand<T extends typeof Command> extends Comm
     static enableJsonFlag: boolean;
     protected args: BaseArgs<T>;
     protected flags: BaseFlags<T>;
+    private startedAtMs;
     protected catch(error: Error & {
         exitCode?: number;
     }): Promise<never>;
+    protected finally(error: Error | undefined): Promise<void>;
+    protected footer(text: string): void;
     init(): Promise<void>;
+    protected note(message: string): void;
     protected resolvedHost(): string;
     protected respond<D>(data: D, human: (data: D) => void): D;
     protected respondList<R>(envelope: {

package/dist/lib/command/base.js

@@ -1,8 +1,17 @@
 import { Command, Flags } from '@oclif/core';
+import { CONTRACT_VERSION } from '../config/constants.js';
 import { resolveHost } from '../config/xdg.js';
-import { renderError, UsageError } from '../errors.js';
+import { classifyError, renderError, UsageError } from '../errors.js';
 import { renderNdjson } from '../output/ndjson.js';
 import { redact } from '../output/redact.js';
+import { appendRunLog, currentRunLogPath } from '../output/runlog.js';
+import { sanitizeTerminal } from '../output/sanitize.js';
+import { writeOutputEntry } from '../output/sidecar.js';
+import { enableStderrTrace } from '../output/trace.js';
+// Cap on any single argv element / message written to a persistent file, so a
+// huge --body can neither balloon the log nor tear an NDJSON line under
+// concurrent O_APPEND (E11-6 review).
+const DISK_FIELD_MAX = 2000;
 // 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),
@@ -19,11 +28,65 @@ export class BaseCommand extends Command {
     static enableJsonFlag = true;
     args;
     flags;
+    // Command start, for the sidecar's duration_ms.
+    startedAtMs = 0;
     // 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 }));
+        // Sidecar + run log see every failure (E11-6): structured for the
+        // supervising process, one line for the post-mortem trail. Message is
+        // redacted and capped so it can't tear a shared NDJSON line.
+        const classified = classifyError(error);
+        const message = redact(classified.message).slice(0, DISK_FIELD_MAX);
+        appendRunLog(`command-failed ${this.id ?? ''}: [${classified.code}] ${message}`);
+        writeOutputEntry({
+            command: this.id ?? '',
+            error_code: classified.code,
+            exit: classified.exitCode,
+            log_file_path: currentRunLogPath(),
+            message,
+            type: 'command-failed',
+            version: 1,
+            ...(classified.details.retryAfterMs === undefined ? {} : { retry_after_ms: classified.details.retryAfterMs }),
+        });
+        const exitCode = renderError(error, { json: machine });
+        // The pointer to the full trace, human mode only (machine consumers get
+        // log_file_path in the sidecar entry instead — stderr stays quiet).
+        const logPath = currentRunLogPath();
+        if (!machine && logPath !== null)
+            process.stderr.write(`🪵 Logs were written to ${logPath}\n`);
+        this.exit(exitCode);
+    }
+    // Success bookkeeping for the sidecar. oclif calls finally() with undefined on
+    // the clean path (the failure entry is written in catch()), so only a success
+    // logs a result here.
+    async finally(error) {
+        if (error === undefined && this.startedAtMs > 0) {
+            writeOutputEntry({
+                command: this.id ?? '',
+                duration_ms: Date.now() - this.startedAtMs,
+                exit: 0,
+                type: 'result',
+                version: 1,
+            });
+        }
+        await super.finally(error);
+    }
+    // A multi-line guidance BLOCK on stderr, human mode only (E11-3/E11-6
+    // review): shares note()'s redact + sanitize + machine-mode gating, but
+    // emits the text verbatim without the `→ ` prefix. This is the one writer
+    // for the command footers (catalog example, connections usage, login next),
+    // so mode gating no longer depends on each call sitting inside a human
+    // closure. Newlines are preserved (it is a block); each line is sanitized.
+    footer(text) {
+        if (this.jsonEnabled() || Boolean(this.flags?.ndjson))
+            return;
+        const safe = redact(text)
+            .split('\n')
+            .map((line) => sanitizeTerminal(line))
+            .join('\n');
+        process.stderr.write(safe.endsWith('\n') ? safe : `${safe}\n`);
     }
     async init() {
         await super.init();
@@ -41,6 +104,37 @@ export class BaseCommand extends Command {
         if (this.jsonEnabled() && this.flags.ndjson) {
             throw new UsageError('--json and --ndjson are mutually exclusive.');
         }
+        // E11-6 wiring: --verbose mirrors the wire trace to stderr (the run log
+        // always gets it), and the sidecar records the session before any work.
+        // argv is REDACTED (a --body/flag can carry a token) and capped — the run
+        // log's own contract is "callers redact before appendRunLog".
+        this.startedAtMs = Date.now();
+        if (this.flags.verbose)
+            enableStderrTrace();
+        const safeArgv = redact([this.id ?? '', ...this.argv]).map((part) => part.slice(0, DISK_FIELD_MAX));
+        appendRunLog(`session ${this.config.version} contract=${CONTRACT_VERSION} argv=${JSON.stringify(safeArgv)}`);
+        writeOutputEntry({
+            argv: safeArgv,
+            cli_version: this.config.version,
+            contract_version: CONTRACT_VERSION,
+            log_file_path: currentRunLogPath(),
+            type: 'session',
+            version: 1,
+        });
+    }
+    // Context narration (E11-2, #101): resolved state and environmental inferences,
+    // one `→ ` line each, HUMAN MODE ONLY. Under --json/--ndjson these vanish
+    // entirely — stdout purity is untouchable and machine consumers branch on the
+    // envelope/sidecar, not prose. stderr, redacted, terminal-sanitized.
+    note(message) {
+        if (this.jsonEnabled() || Boolean(this.flags?.ndjson))
+            return;
+        // ONE line per note, enforced: a newline smuggled inside an interpolated
+        // value (a service-supplied connection name, a filter column) would
+        // otherwise forge additional arrow-prefixed lines — misleading context
+        // injected into the exact channel agents read (sec review, #109).
+        const line = sanitizeTerminal(redact(message)).replaceAll(/[\t\n\r]+/g, ' ');
+        process.stderr.write(`→ ${line}\n`);
     }
     // The resolved active host (flag > config.defaultHost > DEFAULT_HOST).
     resolvedHost() {
@@ -70,6 +164,6 @@ export class BaseCommand extends Command {
     // always redacted (never leaks a token).
     verboseLog(message) {
         if (this.flags.verbose)
-            process.stderr.write(`${redact(message)}\n`);
+            process.stderr.write(`${sanitizeTerminal(redact(message))}\n`);
     }
 }

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

@@ -1,3 +1,7 @@
+export declare const plannerFlags: {
+    'auth-host': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    url: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+};
 export declare const paginationFlags: {
     all: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;

package/dist/lib/command/flags.js

@@ -1,4 +1,15 @@
 import { Flags } from '@oclif/core';
+// Shared flags for the commands that target the QUERY PLANNER (E8). `--url` is
+// how you drive a locally-run planner; `--auth-host` names the issuer holding the
+// credentials, which is a DIFFERENT origin from the planner itself.
+export const plannerFlags = {
+    'auth-host': Flags.string({
+        description: 'OAuth issuer host for credentials/refresh (defaults to the prod issuer).',
+    }),
+    url: Flags.string({
+        description: 'Query-planner base URL (default: the prod planner; env FLIPSTREAM_PLANNER_URL).',
+    }),
+};
 // 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 = {

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

@@ -0,0 +1,9 @@
+import { type PlannerClient } from '../planner/client.js';
+import { type TokenStore } from '../store/keyring.js';
+export interface PlannerClientOptions {
+    authHost: string;
+    store: TokenStore;
+    timeoutMs?: number;
+    url: string;
+}
+export declare function authedPlannerClient(options: PlannerClientOptions): PlannerClient;

package/dist/lib/command/planner.js

@@ -0,0 +1,14 @@
+import { refresh } from '../auth/refresh.js';
+import { createAuthedPlannerClient } from '../planner/client.js';
+// Build the authed planner client for a command. Mirrors authedAdminClient, but
+// keeps the two origins explicit — conflating them is how a refresh ends up
+// pointed at a host that cannot issue anything.
+export function authedPlannerClient(options) {
+    return createAuthedPlannerClient({
+        accessTokenIfFresh: (host) => options.store.accessTokenIfFresh(host),
+        authHost: options.authHost,
+        refresh: (host) => refresh(host, { store: options.store, timeoutMs: options.timeoutMs }),
+        timeoutMs: options.timeoutMs,
+        url: options.url,
+    });
+}

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;