flipstream 0.4.0 → 0.6.0

package/dist/lib/planner/diagnose.js

@@ -0,0 +1,50 @@
+import { parseCatalogIndex, parseCatalogSource } from './catalog.js';
+import { didYouMean } from './suggest.js';
+import { describeProblems, diagnoseUnknownNames } from './vocabulary.js';
+export async function attachVocabularyDiagnosis(error, options) {
+    const upstream = error.details.upstreamCode;
+    if (upstream === undefined || !upstream.startsWith('UNKNOWN_'))
+        return;
+    // Structural guard, not just the planner's vocabulary discipline: a
+    // retryable failure (429/5xx) must never trigger an immediate follow-up
+    // fetch against a service that just asked us to back off.
+    if (error.details.retryable === true)
+        return;
+    const source = options.body?.source;
+    const sourceName = typeof source === 'string' && /^[\w.-]{1,64}$/.test(source) ? source : undefined;
+    try {
+        if (upstream === 'UNKNOWN_SOURCE') {
+            if (sourceName === undefined)
+                return;
+            const index = parseCatalogIndex(await options.fetchCatalog());
+            const suggestion = didYouMean(sourceName, index.sources.map((entry) => entry.name).filter((name) => name.length > 0));
+            // The next command must be RUNNABLE: never the name the planner just
+            // rejected — the bare index when there is no better idea, the suggested
+            // source when there is.
+            error.withDetails({
+                hint: suggestion === undefined
+                    ? `Unknown source "${sourceName}" — list the real ones first.`
+                    : `Unknown source "${sourceName}" — did you mean "${suggestion}"?`,
+                next: [`${options.bin} catalog${suggestion === undefined ? '' : ` ${suggestion}`}`],
+                retryable: false,
+            });
+            return;
+        }
+        if (sourceName === undefined)
+            return;
+        const catalog = parseCatalogSource(await options.fetchCatalog(sourceName));
+        // An empty vocabulary means we did NOT get a catalog: a 200 carrying an
+        // HTML interstitial or a drifted shape parses to empty arrays, and diffing
+        // against that would accuse every CORRECT name in the request.
+        if (catalog.dimensions.length === 0 && catalog.metrics.length === 0) {
+            options.onSkip?.('catalog response carried no vocabulary');
+            return;
+        }
+        const problems = diagnoseUnknownNames(options.body, catalog);
+        if (problems.length > 0)
+            error.withDetails({ hint: describeProblems(problems) });
+    }
+    catch (error_) {
+        options.onSkip?.(error_ instanceof Error ? error_.message : String(error_));
+    }
+}

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

@@ -0,0 +1,14 @@
+import { CliError } from '../errors.js';
+export interface PlannerFailure {
+    code: string;
+    message: string;
+}
+export declare function parsePlannerFailure(bodyText: string): PlannerFailure | undefined;
+export declare function plannerCode(bodyText: string): string;
+export interface CatalogContext {
+    bin: string;
+    source?: string;
+    url: string;
+}
+export declare function mapCatalogError(error: unknown, context: CatalogContext): CliError;
+export declare function mapPlannerError(error: unknown): CliError;

package/dist/lib/planner/errors.js

@@ -0,0 +1,129 @@
+import { mapDataError, rateLimited } from '../api/errors.js';
+import { AuthFailedError, CliError, DataHttpError, NetworkError, retryPolicy, UsageError } from '../errors.js';
+import { ExitCode } from '../exit-codes.js';
+import { redact } from '../output/redact.js';
+const MESSAGE_MAX = 500;
+// The planner's codes are SCREAMING_SNAKE enum members. Anything else is not a
+// planner code and gets no trust: `code` flows to stdout as `upstream_code`,
+// so this shape check is what keeps that field bounded and unable to smuggle
+// tokens/ANSI — the one envelope field that would otherwise skip redaction.
+const CODE_SHAPE = /^[A-Z][A-Z0-9_]{0,63}$/;
+// The planner's own error envelope is {code, message} — NOT the {error,
+// error_description} of OAuth nor the {detail} of FastAPI's own validation, so
+// api/errors.ts cannot read it. `detail` (which names tables and columns) is
+// logged server-side and never returned, so there is nothing else to look for.
+export function parsePlannerFailure(bodyText) {
+    let parsed;
+    try {
+        parsed = JSON.parse(bodyText);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return undefined;
+    const record = parsed;
+    if (typeof record.code !== 'string' || !CODE_SHAPE.test(record.code))
+        return undefined;
+    return {
+        code: record.code,
+        message: typeof record.message === 'string' ? record.message.slice(0, MESSAGE_MAX) : '',
+    };
+}
+// The service's own error code for a response body, or '' when this did not come
+// from the planner. Telling those apart is the difference between "typo" and
+// "wrong build" — see the two 404s the catalog command distinguishes.
+export function plannerCode(bodyText) {
+    return parsePlannerFailure(bodyText)?.code ?? '';
+}
+// A catalog failure, with the ONE distinction the generic mapper cannot make.
+//
+// Two different 404s reach this endpoint and they send you to different places:
+// the planner's own UNKNOWN_SOURCE names a source that is not in the catalog (a
+// typo), while FastAPI's bare "Not Found" means the route does not exist at all
+// (an older deployment). Collapsing them into "not found" is how you spend an
+// afternoon checking spelling against a build that never had the endpoint.
+export function mapCatalogError(error, context) {
+    if (!(error instanceof DataHttpError) || error.status !== 404)
+        return mapPlannerError(error);
+    if (plannerCode(error.bodyText) === 'UNKNOWN_SOURCE') {
+        return new CliError(`No catalog entry for '${context.source ?? ''}' — run \`${context.bin} catalog\` to list them.`, 'not_found', ExitCode.GENERIC).withDetails({
+            hint: 'The source name is a catalog key, not a table name.',
+            next: [`${context.bin} catalog`],
+            retryable: false,
+            upstreamCode: 'UNKNOWN_SOURCE',
+        });
+    }
+    const path = context.source === undefined ? '/catalog' : `/catalog/${context.source}`;
+    return new CliError(`${context.url} serves no ${path} — is it running a build that has one?`, 'not_found', ExitCode.GENERIC);
+}
+// Map a planner failure onto the E3 error model. Falls through to mapDataError for
+// anything that is not a recognisable planner envelope, so transport failures,
+// timeouts and already-typed CliErrors keep their existing behaviour.
+//
+// Every planner `message` is built from PUBLIC vocabulary only — the logical names
+// the caller already sent us — which is why it is safe to surface verbatim
+// (redacted defensively all the same).
+export function mapPlannerError(error) {
+    if (!(error instanceof DataHttpError))
+        return mapDataError(error);
+    const failure = parsePlannerFailure(error.bodyText);
+    if (!failure)
+        return mapDataError(error);
+    // Every planner-mapped error carries the planner's own code verbatim (#96):
+    // ENGINE_FAILED and UNKNOWN_DIMENSION are different situations for an agent
+    // even when our own classification of them coincides.
+    return classifyPlannerFailure(error, failure).withDetails({ upstreamCode: failure.code });
+}
+function classifyPlannerFailure(error, failure) {
+    const message = redact(failure.message || `HTTP ${error.status}`);
+    switch (failure.code) {
+        // Unlike the generic 403 mapper (which returns a FIXED message so an upstream
+        // body cannot leak), the planner's INSUFFICIENT_SCOPE message is designed to be
+        // returned: it names the missing scope, or the roles that would do instead.
+        // That is the whole point of checking scopes at the front door rather than
+        // letting a 403 surface two services away as an opaque PULSE_SERVICE_ERROR.
+        // Deterministic auth failures: explicitly NOT retryable — re-presenting the
+        // same token gets the same answer, and `false` is the anti-retry-loop
+        // signal the envelope exists to carry.
+        case 'INSUFFICIENT_SCOPE': {
+            return new AuthFailedError(message, 'role_forbidden').withDetails({ retryable: false });
+        }
+        // The planner's own "I broke, try again" — NetworkError is retryable by
+        // class; thread the server-stated wait through when one was sent.
+        case 'INTERNAL_ERROR': {
+            return new NetworkError(message, 'data_upstream_error').withDetails(retryPolicy(error.retryAfterMs));
+        }
+        case 'INVALID_AUDIENCE': {
+            return new AuthFailedError(`invalid_target: re-bind required — ${message}`, 'invalid_target').withDetails({
+                retryable: false,
+            });
+        }
+        // TOKEN_EXPIRED reaching here means the 401->refresh->retry wrapper already
+        // refreshed successfully and the planner rejected the NEW token too — which is
+        // an auth failure, not an expiry. A refresh that cannot renew raises
+        // session_expired (exit 4) from the wrapper and never gets this far.
+        case 'INVALID_TOKEN':
+        case 'TOKEN_EXPIRED': {
+            return new AuthFailedError(message, 'data_auth_failed').withDetails({ retryable: false });
+        }
+        default: {
+            break;
+        }
+    }
+    // ENGINE_FAILED carries the engine's status: 502 for transport/5xx, 400 when the
+    // engine itself refused. Classify on the status rather than the code so a
+    // retryable upstream failure is exit 7 and a bad request stays exit 1.
+    if (error.status >= 500) {
+        return new NetworkError(message, 'data_upstream_error').withDetails(retryPolicy(error.retryAfterMs));
+    }
+    if (error.status === 429)
+        return rateLimited(message, error.retryAfterMs);
+    if (error.status === 404)
+        return new CliError(message, 'not_found', ExitCode.GENERIC);
+    // A 422 is FastAPI refusing the body shape (`extra="forbid"`), which means WE
+    // emitted something the contract does not allow — a usage error on our side.
+    if (error.status === 422)
+        return new UsageError(message);
+    return new CliError(message, 'data_request_failed', ExitCode.GENERIC);
+}

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

@@ -0,0 +1,8 @@
+export type FilterEntry = Record<string, unknown>;
+export interface SortSpec {
+    by: string;
+    dir: 'asc' | 'desc';
+}
+export declare function parseFilter(raw: string): FilterEntry;
+export declare function describeSelections(entries: FilterEntry[]): string[];
+export declare function parseSort(spec: string): SortSpec;

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;
 }