flipstream 0.5.0 → 0.6.0

package/dist/lib/planner/filters.js

@@ -0,0 +1,74 @@
+import { UsageError } from '../errors.js';
+export function parseFilter(raw) {
+    const at = raw.indexOf('=');
+    const column = at === -1 ? '' : raw.slice(0, at).trim();
+    if (at === -1 || column.length === 0) {
+        throw new UsageError(`--filter must be written col=value, got '${raw}'`);
+    }
+    const value = raw.slice(at + 1);
+    // Verbatim JSON — the escape hatch for everything the shorthand will not say.
+    if (value.startsWith('[') || value.startsWith('{')) {
+        try {
+            return { [column]: JSON.parse(value) };
+        }
+        catch {
+            throw new UsageError(`--filter '${raw}' is not valid JSON.`);
+        }
+    }
+    // Refused rather than guessed: the two spellings route to different tables.
+    if (value.length === 0) {
+        throw new UsageError(`--filter '${raw}' has no value; write ${column}=[] for no selection or ${column}=[""] for a ` +
+            'selection of the empty string — they route differently.');
+    }
+    if (value.includes('..')) {
+        const cut = value.indexOf('..');
+        const from = value.slice(0, cut);
+        const to = value.slice(cut + 2);
+        // Either bound may be absent; the pair keeps its position either way.
+        return { [column]: { from: from || null, to: to || null } };
+    }
+    return { [column]: value.split(',') };
+}
+// Human narration of the selection-length reading, one line per LIST
+// selection (ranges are not selections and say nothing). Lives HERE because
+// this module owns the length predicate ([] inactive / non-empty active) —
+// a command restating it is how the two would drift (E11-2 review).
+//
+// The copy is deliberately conditional ("if <col> is routing-relevant"):
+// only translate.py knows which columns actually route, and this narration
+// echoes the encoding, it never decides. Values are echoed (capped) because
+// `[""]` and a real value both read "1 value" otherwise — and `[""]` is the
+// exact trap the module refuses shorthand for.
+const PREVIEW_VALUES = 3;
+const PREVIEW_CHARS = 32;
+export function describeSelections(entries) {
+    const lines = [];
+    for (const entry of entries) {
+        for (const [column, selection] of Object.entries(entry)) {
+            if (!Array.isArray(selection))
+                continue;
+            if (selection.length === 0) {
+                lines.push(`filter ${column}: [] — read as an INACTIVE selection; if ${column} is routing-relevant, ` +
+                    'the planner answers from the summary table');
+                continue;
+            }
+            const preview = selection
+                .slice(0, PREVIEW_VALUES)
+                .map((value) => JSON.stringify(value).slice(0, PREVIEW_CHARS))
+                .join(', ');
+            const more = selection.length > PREVIEW_VALUES ? ` +${selection.length - PREVIEW_VALUES} more` : '';
+            lines.push(`filter ${column}: ${selection.length} value${selection.length === 1 ? '' : 's'} (${preview}${more}) — ` +
+                `read as an ACTIVE selection; if ${column} is routing-relevant, the planner answers from its dimension table`);
+        }
+    }
+    return lines;
+}
+export function parseSort(spec) {
+    const at = spec.indexOf(':');
+    const by = at === -1 ? spec : spec.slice(0, at);
+    const dir = at === -1 ? 'asc' : spec.slice(at + 1);
+    if (dir !== 'asc' && dir !== 'desc') {
+        throw new UsageError(`--sort direction must be asc or desc, got '${dir}'`);
+    }
+    return { by, dir };
+}

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

@@ -0,0 +1,24 @@
+import { type FilterEntry, type SortSpec } from './filters.js';
+export interface LogicalRequest {
+    connection_id: string;
+    dimensions: string[];
+    filters: FilterEntry[];
+    metrics: string[];
+    offset: number;
+    rows: number;
+    sort?: SortSpec[];
+    source: string;
+    table?: string;
+}
+export interface RequestFlags {
+    connectionId?: string;
+    dimensions?: string[];
+    filters?: string[];
+    metrics?: string[];
+    offset?: number;
+    rows?: number;
+    sort?: string[];
+    source?: string;
+    table?: string;
+}
+export declare function buildLogicalRequest(flags: RequestFlags, bin?: string): LogicalRequest;

package/dist/lib/planner/request.js

@@ -0,0 +1,51 @@
+import { UsageError } from '../errors.js';
+import { parseFilter, parseSort } from './filters.js';
+export function buildLogicalRequest(flags, bin = 'flipstream') {
+    // Name EXACTLY what is missing (never "A and B are required" when A was given),
+    // and point at the command that produces the missing value (E11-1, #100).
+    const { connectionId, source } = flags;
+    if (!source && !connectionId) {
+        throw new UsageError('Missing --source and --connection-id (or pass a full JSON body via --body / --body-file).', 'missing_source_and_connection_id').withDetails({
+            docs: 'docs/AGENT-CONTRACT.md#the-query-request-shape-logicalrequest',
+            hint: 'Pick a source from the catalog and a connection id from your connections.',
+            next: [`${bin} catalog`, `${bin} connections list --json`],
+            retryable: false,
+        });
+    }
+    if (!source) {
+        throw new UsageError('Missing --source.', 'missing_source').withDetails({
+            docs: 'docs/AGENT-CONTRACT.md#the-query-request-shape-logicalrequest',
+            hint: 'List the queryable sources, then pass one as --source.',
+            next: [`${bin} catalog`],
+            retryable: false,
+        });
+    }
+    if (!connectionId) {
+        throw new UsageError('Missing --connection-id.', 'missing_connection_id').withDetails({
+            docs: 'docs/AGENT-CONTRACT.md#the-query-request-shape-logicalrequest',
+            hint: 'List your connections and pass one of their ids (or its name).',
+            next: [`${bin} connections list --json`],
+            retryable: false,
+        });
+    }
+    const body = {
+        connection_id: connectionId,
+        dimensions: flags.dimensions ?? [],
+        // One entry per --filter: the list carries ORDER and REPEATS on purpose, so
+        // two filters on the same column stay two entries and the planner decides
+        // whether they merge or conflict.
+        filters: (flags.filters ?? []).map((raw) => parseFilter(raw)),
+        metrics: flags.metrics ?? [],
+        offset: flags.offset ?? 0,
+        rows: flags.rows ?? 100,
+        source,
+    };
+    if (flags.sort && flags.sort.length > 0)
+        body.sort = flags.sort.map((spec) => parseSort(spec));
+    // The passthrough gate, not a routing override — absent unless explicitly given.
+    // For a MODELLED source the planner ignores it rather than rejecting it, which
+    // is what lets a source become modelled without any caller changing.
+    if (flags.table !== undefined)
+        body.table = flags.table;
+    return body;
+}

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

@@ -0,0 +1,2 @@
+export declare function editDistance(a: string, b: string): number;
+export declare function didYouMean(input: string, candidates: readonly string[], maxDistance?: number): string | undefined;

package/dist/lib/planner/suggest.js

@@ -0,0 +1,45 @@
+// "Did you mean" for catalog names (E11-3, #102). Wrangler ships this for
+// command names but never wired it to values; we wire it to the vocabulary the
+// planner actually rejects: sources, dimensions, metrics, filter keys.
+//
+// The scaling heuristic is ported from wrangler's did-you-mean verbatim in
+// spirit: a candidate only qualifies when the edit distance is within BOTH the
+// caller's ceiling AND two-thirds of the shorter name's length — which is what
+// stops a 2-letter metric from "matching" an unrelated 3-letter typo.
+// Classic Levenshtein, O(a.length * b.length); names are short.
+export function editDistance(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j++) {
+            const substitution = (previous[j - 1] ?? 0) + (a[i - 1] === b[j - 1] ? 0 : 1);
+            current.push(Math.min((previous[j] ?? 0) + 1, (current[j - 1] ?? 0) + 1, substitution));
+        }
+        previous = current;
+    }
+    return previous[b.length] ?? 0;
+}
+// The closest candidate within the scaled threshold, or undefined when nothing
+// is close enough — no suggestion beats a wrong suggestion.
+export function didYouMean(input, candidates, maxDistance = 3) {
+    const needle = input.toLowerCase();
+    let best;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const candidate of candidates) {
+        const distance = editDistance(needle, candidate.toLowerCase());
+        // Scale the ceiling down for short names so e.g. "xy" never matches an
+        // unrelated two-letter metric two edits away.
+        const ceiling = Math.min(maxDistance, Math.floor((Math.min(needle.length, candidate.length) * 2) / 3));
+        if (distance <= ceiling && distance < bestDistance) {
+            best = candidate;
+            bestDistance = distance;
+        }
+    }
+    return best;
+}

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

@@ -0,0 +1,9 @@
+import { type CatalogSource } from './catalog.js';
+export interface NameProblem {
+    kind: 'dimension' | 'filter key' | 'metric' | 'sort field';
+    name: string;
+    suggestion?: string;
+    wrongKind?: 'dimension' | 'metric';
+}
+export declare function diagnoseUnknownNames(body: unknown, catalog: CatalogSource): NameProblem[];
+export declare function describeProblems(problems: NameProblem[]): string;

package/dist/lib/planner/vocabulary.js

@@ -0,0 +1,95 @@
+import { didYouMean } from './suggest.js';
+function strings(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}
+function filterKeys(value) {
+    if (!Array.isArray(value))
+        return [];
+    const keys = [];
+    for (const entry of value) {
+        if (typeof entry === 'object' && entry !== null && !Array.isArray(entry)) {
+            keys.push(...Object.keys(entry));
+        }
+    }
+    return keys;
+}
+function sortFields(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((entry) => (typeof entry === 'object' && entry !== null ? entry.by : undefined))
+        .filter((by) => typeof by === 'string');
+}
+export function diagnoseUnknownNames(body, catalog) {
+    const names = (body ?? {});
+    // Empty-string names are catalog parsing artifacts, never suggestions.
+    const dimensionNames = new Set(catalog.dimensions.map((item) => item.name).filter((name) => name.length > 0));
+    const metricNames = new Set(catalog.metrics.map((item) => item.name).filter((name) => name.length > 0));
+    const problems = [];
+    const seen = new Set();
+    const push = (problem) => {
+        // Dedupe per (kind, name): the same typo twice is one problem — but the
+        // same name wrong as a dimension AND as a filter key stays two.
+        const key = `${problem.kind} ${problem.name}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        problems.push(problem);
+    };
+    for (const name of strings(names.dimensions)) {
+        if (dimensionNames.has(name))
+            continue;
+        if (metricNames.has(name))
+            push({ kind: 'dimension', name, wrongKind: 'metric' });
+        else
+            push({ kind: 'dimension', name, suggestion: didYouMean(name, [...dimensionNames]) });
+    }
+    for (const name of strings(names.metrics)) {
+        if (metricNames.has(name))
+            continue;
+        if (dimensionNames.has(name))
+            push({ kind: 'metric', name, wrongKind: 'dimension' });
+        else
+            push({ kind: 'metric', name, suggestion: didYouMean(name, [...metricNames]) });
+    }
+    // Filter keys are dimension names in the logical contract (open question for
+    // the planner whether metric filters are ever legal — the wrongKind copy
+    // below stays honest either way).
+    for (const name of filterKeys(names.filters)) {
+        if (dimensionNames.has(name))
+            continue;
+        if (metricNames.has(name))
+            push({ kind: 'filter key', name, wrongKind: 'metric' });
+        else
+            push({ kind: 'filter key', name, suggestion: didYouMean(name, [...dimensionNames]) });
+    }
+    // Sort fields may reference either kind.
+    for (const name of sortFields(names.sort)) {
+        if (dimensionNames.has(name) || metricNames.has(name))
+            continue;
+        push({ kind: 'sort field', name, suggestion: didYouMean(name, [...dimensionNames, ...metricNames]) });
+    }
+    return problems;
+}
+const HINT_MAX_PROBLEMS = 5;
+// ONE imperative hint (the contract's definition of `hint`): what to change,
+// capped, with the catalog rule kept — the diagnosis must never displace the
+// rule the caller most needs at the moment they broke it.
+export function describeProblems(problems) {
+    const clauses = problems.slice(0, HINT_MAX_PROBLEMS).map((problem) => {
+        if (problem.wrongKind !== undefined) {
+            const flag = problem.wrongKind === 'metric' ? '-m' : '-d';
+            if (problem.kind === 'filter key') {
+                return `"${problem.name}" is a ${problem.wrongKind}, not a filterable dimension`;
+            }
+            return `"${problem.name}" is a ${problem.wrongKind} — pass it with ${flag}`;
+        }
+        if (problem.suggestion !== undefined) {
+            return `replace ${problem.kind} "${problem.name}" with "${problem.suggestion}"`;
+        }
+        return (`${problem.kind} "${problem.name}" is not in this source's published catalog ` +
+            '(per-connection custom dimensions are not listed there)');
+    });
+    const more = problems.length > HINT_MAX_PROBLEMS ? `; …and ${problems.length - HINT_MAX_PROBLEMS} more` : '';
+    return `${clauses.join('; ')}${more} — every name must come from the catalog (no aliases).`;
+}

package/dist/lib/skills/install.d.ts

@@ -0,0 +1,24 @@
+export interface AgentTarget {
+    detected: string[];
+    id: string;
+    name: string;
+    skillsDir: string;
+}
+export declare const SUPPORTED_AGENTS: AgentTarget[];
+export declare function packagedSkillPath(): string;
+export declare function resolveTargets(options?: {
+    explicit?: string[];
+    home?: string;
+}): AgentTarget[];
+export interface InstalledEntry {
+    agent: string;
+    backup?: string;
+    path: string;
+    status: 'installed' | 'unchanged' | 'updated';
+}
+export interface InstallResult {
+    installed: InstalledEntry[];
+}
+export declare function installSkill(targets: AgentTarget[], options?: {
+    home?: string;
+}): InstallResult;

package/dist/lib/skills/install.js

@@ -0,0 +1,69 @@
+import { detectAgenticEnvironment } from 'am-i-vibing';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// The agents with a known global skills layout. An entry is only ever written
+// under the user's own home directory.
+export const SUPPORTED_AGENTS = [
+    { detected: ['claude-code'], id: 'claude-code', name: 'Claude Code', skillsDir: join('.claude', 'skills') },
+    { detected: ['codex'], id: 'codex', name: 'Codex', skillsDir: join('.codex', 'skills') },
+    { detected: ['cursor', 'cursor-agent'], id: 'cursor', name: 'Cursor', skillsDir: join('.cursor', 'skills') },
+    { detected: ['opencode'], id: 'opencode', name: 'OpenCode', skillsDir: join('.config', 'opencode', 'skills') },
+];
+// The packaged skill: <package root>/skill/SKILL.md, resolved relative to this
+// module so it works from dist in the published tarball and from src in dev.
+export function packagedSkillPath() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return join(here, '..', '..', '..', 'skill', 'SKILL.md');
+}
+// Which agents to install for: the one DRIVING this process (env detection),
+// plus any whose global directory already exists on this machine. Explicit ids
+// override everything.
+export function resolveTargets(options = {}) {
+    const home = options.home ?? homedir();
+    if (options.explicit !== undefined && options.explicit.length > 0) {
+        return SUPPORTED_AGENTS.filter((agent) => options.explicit?.includes(agent.id));
+    }
+    // checkProcesses: false EXPLICITLY — env detection only. The dependency's
+    // current default agrees, but the property is load-bearing (no exec, no
+    // startup cost) so we assert it rather than inherit it.
+    const detection = detectAgenticEnvironment({ checkProcesses: false });
+    const driving = detection.type === 'agent' ? detection.id : null;
+    return SUPPORTED_AGENTS.filter((agent) => (driving !== null && agent.detected.includes(driving)) || existsSync(join(home, dirname(agent.skillsDir))));
+}
+// Copy the skill into each target's global skills dir. NEVER destroys local
+// edits silently: an identical existing file is left untouched (`unchanged`),
+// a differing one is preserved as SKILL.md.bak before the refresh (`updated`)
+// — "yes, install" is not "yes, destroy my edits" (E11-5 review).
+export function installSkill(targets, options = {}) {
+    const home = options.home ?? homedir();
+    const skill = readFileSync(packagedSkillPath(), 'utf8');
+    const installed = [];
+    for (const target of targets) {
+        const dir = join(home, target.skillsDir, 'flipstream');
+        mkdirSync(dir, { recursive: true });
+        const path = join(dir, 'SKILL.md');
+        let existing = null;
+        try {
+            existing = readFileSync(path, 'utf8');
+        }
+        catch {
+            // No existing file — plain install.
+        }
+        if (existing === skill) {
+            installed.push({ agent: target.id, path, status: 'unchanged' });
+            continue;
+        }
+        if (existing !== null) {
+            const backup = `${path}.bak`;
+            writeFileSync(backup, existing);
+            writeFileSync(path, skill);
+            installed.push({ agent: target.id, backup, path, status: 'updated' });
+            continue;
+        }
+        writeFileSync(path, skill);
+        installed.push({ agent: target.id, path, status: 'installed' });
+    }
+    return { installed };
+}

package/dist/lib/store/keyring.d.ts

@@ -5,12 +5,15 @@ export interface TokenStore {
     available(): boolean;
     clear(host: string): void;
     load(host: string): Credentials | null;
+    reload(host: string): Credentials | null;
     save(host: string, creds: Credentials): void;
 }
 export declare class KeyringStore implements TokenStore {
+    #private;
     accessTokenIfFresh(host: string): null | string;
     available(): boolean;
     clear(host: string): void;
     load(host: string): Credentials | null;
+    reload(host: string): Credentials | null;
     save(host: string, creds: Credentials): void;
 }

package/dist/lib/store/keyring.js

@@ -7,7 +7,37 @@ import { freshAccessToken, keyOf, parseCredentials } from './credentials.js';
 export const KEYRING_SERVICE = 'io.flipstream.cli';
 // TokenStore backed by the OS keychain. The whole Credentials JSON is the single
 // secret per host (keyed by host).
+//
+// Reads are CACHED for the life of the process. Without this, one command touches
+// the keychain several times — the auth gate reads it, then every authed request
+// re-reads it through withFreshToken, and a paginated call re-reads it per page.
+// On macOS each read is a separate access, so a user who granted "Allow" rather
+// than "Always Allow" gets prompted once per read: two dialogs for `catalog`,
+// three for `query`, more for anything that paginates or resolves a name.
+//
+// This costs nothing in EXPOSURE: the credentials are already in memory the moment
+// they are read — they have to be, to go in an Authorization header — so holding
+// them for the rest of a short-lived CLI process reveals nothing new. Nothing is
+// written to disk, and the cache dies with the process.
+//
+// It does cost COHERENCE, and that is worth stating plainly rather than glossing.
+// Another CLI process can log out or rotate tokens underneath us, and this cache
+// will not notice. Two consequences, handled differently:
+//
+//   Deleting someone else's session — handled. A failed refresh compare-and-deletes
+//   (see auth/refresh.ts): it re-reads past this cache and only clears when the
+//   stored token is still the one it tried. That race predates the cache; caching
+//   only widened the window.
+//
+//   Using a token after a concurrent `auth logout` — accepted. Logout REVOKES
+//   upstream, so a stale cached token gets a 401 from the server rather than data,
+//   surfacing as data_auth_failed. Re-reading before every request would fix it and
+//   would also undo the entire point of caching, for a case that already fails
+//   safely.
 export class KeyringStore {
+    // `null` is cached too: "this host has no credentials" is an answer worth
+    // remembering, or a logged-out run re-reads on every check.
+    #cache = new Map();
     accessTokenIfFresh(host) {
         return freshAccessToken(this.load(host));
     }
@@ -23,6 +53,7 @@ export class KeyringStore {
         }
     }
     clear(host) {
+        this.#cache.set(host, null);
         try {
             new Entry(KEYRING_SERVICE, keyOf(host)).deletePassword();
         }
@@ -31,15 +62,27 @@ export class KeyringStore {
         }
     }
     load(host) {
+        const cached = this.#cache.get(host);
+        if (cached !== undefined)
+            return cached;
+        return this.reload(host);
+    }
+    reload(host) {
+        let creds = null;
         try {
             const secret = new Entry(KEYRING_SERVICE, keyOf(host)).getPassword();
-            return secret ? parseCredentials(secret) : null;
+            creds = secret ? parseCredentials(secret) : null;
         }
         catch {
-            return null;
+            creds = null;
         }
+        this.#cache.set(host, creds);
+        return creds;
     }
     save(host, creds) {
         new Entry(KEYRING_SERVICE, keyOf(host)).setPassword(JSON.stringify(creds));
+        // Keep the cache authoritative: a refresh saves rotated tokens mid-command,
+        // and a later read must see them rather than the ones it started with.
+        this.#cache.set(host, creds);
     }
 }

package/dist/lib/store/memory-store.d.ts

@@ -6,5 +6,6 @@ export declare class MemoryStore implements TokenStore {
     available(): boolean;
     clear(host: string): void;
     load(host: string): Credentials | null;
+    reload(host: string): Credentials | null;
     save(host: string, creds: Credentials): void;
 }

package/dist/lib/store/memory-store.js

@@ -15,6 +15,11 @@ export class MemoryStore {
     load(host) {
         return this.entries.get(keyOf(host)) ?? null;
     }
+    // No cache here, so a forced re-read is the same read. Present so the interface
+    // is honest and tests exercise the same call sites as the real store.
+    reload(host) {
+        return this.load(host);
+    }
     save(host, creds) {
         this.entries.set(keyOf(host), creds);
     }