@userreason/cli 0.1.0 → 0.2.0

package/dist/telemetry.js

@@ -0,0 +1,304 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readdir, rename, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { configDirectory } from './config.js';
+import { apiUrl } from './contracts.js';
+import { commandCatalog } from './catalog.js';
+export const WIZARD_FLOW_VERSION = '2026-10-26.1';
+export const WIZARD_CONTENT_VERSION = '2026-10-26.1';
+export const WIZARD_STEPS = ['run', 'authentication', 'target_selection', 'options', 'sdk_install', 'cli_install', 'initialization', 'configuration_check', 'agent_note', 'agent_skill', 'cli_access', 'global_cli'];
+export const WIZARD_PHASES = ['eligible', 'offered', 'selected', 'declined', 'applied', 'failed', 'skipped', 'already_present', 'cancelled', 'started', 'completed'];
+export const TELEMETRY_REASONS = ['not_requested', 'installation_pending', 'already_present', 'up_to_date', 'unsupported', 'existing_content_preserved', 'permission_denied', 'validation_failed', 'network_error', 'operation_failed', 'user_cancelled', 'explicit_skip', 'packages_current'];
+const idPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const versionPattern = /^[A-Za-z0-9][A-Za-z0-9.+_-]{0,63}$/;
+const ttl = 7 * 24 * 60 * 60 * 1000;
+const maximumRecords = 160;
+const maximumFileBytes = 128 * 1024;
+const commands = new Set([...commandCatalog.map(item => item.command), 'unknown', 'help']);
+const directory = () => join(configDirectory(), 'telemetry');
+const disabledEnvironment = () => /^(1|true|yes)$/i.test(process.env.UR_TELEMETRY_DISABLED ?? '') || process.env.DO_NOT_TRACK === '1';
+const number = (value, max = 86_400_000) => typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= max;
+const duration = (value) => Math.min(86_400_000, Math.max(0, Math.round(value)));
+/** Read only regular, bounded files. Local analytics state must never follow a symlink. */
+async function readJson(path) {
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size > maximumFileBytes)
+            throw new Error('Invalid telemetry state');
+        return JSON.parse(await handle.readFile('utf8'));
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function ensureDirectory() {
+    await mkdir(directory(), { recursive: true, mode: 0o700 });
+    const stat = await lstat(directory());
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error('Invalid telemetry directory');
+}
+async function atomicJson(path, value) {
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        const file = await open(temporary, 'wx', 0o600);
+        try {
+            await file.writeFile(JSON.stringify(value) + '\n');
+        }
+        finally {
+            await file.close();
+        }
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true }).catch(() => { });
+    }
+}
+export async function telemetryEnabled() {
+    if (disabledEnvironment())
+        return false;
+    try {
+        return (await readJson(join(directory(), 'preferences.json'))).enabled !== false;
+    }
+    catch (error) {
+        return error.code === 'ENOENT';
+    }
+}
+export async function setTelemetryEnabled(enabled) {
+    await ensureDirectory();
+    await atomicJson(join(directory(), 'preferences.json'), { enabled });
+    if (!enabled)
+        for (const entry of (await readdir(directory())).slice(0, 512)) {
+            if (/^(?:queue-[a-f0-9]{64}\.json(?:\.lock)?|installation\.json)$/.test(entry))
+                await rm(join(directory(), entry), { force: true }).catch(() => { });
+        }
+}
+export function telemetryCommand(positionals, help = false) {
+    if (help || !positionals.length)
+        return 'help';
+    // Only compare against our static catalog; never emit a caller-provided argument.
+    return [...commands].filter(item => item !== 'unknown' && item !== 'help')
+        .sort((left, right) => right.length - left.length)
+        .find(item => item.split(' ').every((word, index) => positionals[index] === word)) ?? 'unknown';
+}
+function validRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const record = value;
+    const common = ['event_id', 'occurred_at', 'run_id', 'surface', 'release_version', 'execution_mode', 'workspace_id', 'site_id', 'source_site_environment'];
+    const allowed = record.event === 'ur.wizard.step' ? [...common, 'event', 'flow_version', 'content_version', 'step_id', 'phase', 'duration_ms', 'reason', 'selection_source', 'framework', 'package_manager', 'resumed', 'guidance_file'] : [...common, 'event', 'command', 'success_count', 'failure_count', 'total_duration_ms', 'max_duration_ms'];
+    if (Object.keys(record).some(key => !allowed.includes(key)) || !idPattern.test(record.event_id) || !idPattern.test(record.run_id) || !versionPattern.test(record.release_version) || !['interactive', 'agent', 'ci', 'noninteractive'].includes(record.execution_mode))
+        return false;
+    if (!Number.isFinite(Date.parse(record.occurred_at)) || Date.now() - Date.parse(record.occurred_at) > ttl || Date.parse(record.occurred_at) > Date.now() + 300_000)
+        return false;
+    if ((record.workspace_id && !idPattern.test(record.workspace_id)) || (record.site_id && (!record.workspace_id || !idPattern.test(record.site_id))) || (record.source_site_environment && !['development', 'production'].includes(record.source_site_environment)))
+        return false;
+    if (record.event === 'ur.wizard.step')
+        return record.surface === 'wizard' && WIZARD_STEPS.includes(record.step_id) && WIZARD_PHASES.includes(record.phase) && versionPattern.test(record.flow_version) && versionPattern.test(record.content_version)
+            && (record.duration_ms === undefined || number(record.duration_ms)) && (record.reason === undefined || TELEMETRY_REASONS.includes(record.reason))
+            && (record.selection_source === undefined || ['prompt', 'flag', 'default'].includes(record.selection_source))
+            && (record.framework === undefined || ['react', 'next', 'vue', 'vanilla'].includes(record.framework))
+            && (record.package_manager === undefined || ['npm', 'pnpm', 'yarn'].includes(record.package_manager))
+            && (record.resumed === undefined || typeof record.resumed === 'boolean') && (record.guidance_file === undefined || ['AGENTS.md', 'CLAUDE.md'].includes(record.guidance_file));
+    return record.event === 'ur.cli.usage' && record.surface === 'cli' && commands.has(record.command)
+        && Number.isSafeInteger(record.success_count) && number(record.success_count, 10000) && Number.isSafeInteger(record.failure_count) && number(record.failure_count, 10000)
+        && record.success_count + record.failure_count > 0 && number(record.total_duration_ms, 864000000000) && number(record.max_duration_ms) && record.total_duration_ms >= record.max_duration_ms;
+}
+/** A best-effort recorder. Credentials stay in memory and never enter the spool or payload. */
+export class ToolTelemetry {
+    options;
+    runId = randomUUID();
+    pending = [];
+    session = null;
+    context = {};
+    wizardContext = {};
+    active = true;
+    fetcher;
+    origin;
+    constructor(options) {
+        this.options = options;
+        this.fetcher = options.fetcher ?? fetch;
+        this.origin = apiUrl(options.apiUrl);
+        this.active = !options.disabled && !disabledEnvironment() && versionPattern.test(options.releaseVersion);
+    }
+    configure(input) {
+        if (input.apiUrl)
+            this.origin = apiUrl(input.apiUrl);
+        if (input.context)
+            this.context = { ...input.context };
+        if (input.wizard)
+            this.wizardContext = { ...this.wizardContext, ...input.wizard };
+    }
+    setSession(session) { this.session = session?.apiUrl === this.origin && session.expiresAt > Date.now() ? session : null; }
+    observeCredentials(credentials) {
+        return {
+            load: async () => { const session = await credentials.load(); this.setSession(session); return session; },
+            save: async (session) => { await credentials.save(session); this.setSession(session); },
+            clear: async () => { await credentials.clear(); this.setSession(null); },
+        };
+    }
+    scope() { return this.session ? createHash('sha256').update(`user:${this.session.userId}`).digest('hex') : 'anonymous'; }
+    common() {
+        return { event_id: randomUUID(), occurred_at: new Date().toISOString(), run_id: this.runId, surface: this.options.surface, release_version: this.options.releaseVersion, execution_mode: this.options.executionMode,
+            // Target IDs are included only with authenticated records. They are still verified at ingestion.
+            ...(this.session ? this.context : { source_site_environment: this.context.source_site_environment }) };
+    }
+    step(step_id, phase, details = {}) {
+        if (!this.active || this.options.surface !== 'wizard' || this.pending.length >= maximumRecords)
+            return;
+        const record = { ...this.common(), ...this.wizardContext, ...details, event: 'ur.wizard.step', flow_version: WIZARD_FLOW_VERSION, content_version: WIZARD_CONTENT_VERSION, step_id, phase };
+        if (record.duration_ms !== undefined)
+            record.duration_ms = duration(record.duration_ms);
+        if (validRecord(record))
+            this.pending.push({ scope: this.scope(), record });
+    }
+    command(command, success, durationMs) {
+        if (!this.active || this.options.surface !== 'cli')
+            return;
+        const record = { ...this.common(), event: 'ur.cli.usage', command: commands.has(command) ? command : 'unknown', success_count: success ? 1 : 0, failure_count: success ? 0 : 1, total_duration_ms: duration(durationMs), max_duration_ms: duration(durationMs) };
+        if (validRecord(record))
+            this.pending.push({ scope: this.scope(), record });
+    }
+    /** Save a bounded checkpoint without introducing a network call into a wizard step. */
+    checkpoint() { return this.flush(false, true); }
+    async flush(force = false, storeOnly = false) {
+        if (!this.active)
+            return;
+        try {
+            if (!await telemetryEnabled()) {
+                this.pending = [];
+                return;
+            }
+            await ensureDirectory();
+            const scopes = new Set(['anonymous', this.scope(), ...this.pending.map(item => item.scope)]);
+            for (const scope of scopes) {
+                const currentScope = this.scope();
+                // An old user partition may be saved, but never sent with a new account's token.
+                const authorized = scope === 'anonymous' || (scope === currentScope && this.session && this.session.expiresAt > Date.now());
+                const key = createHash('sha256').update(`${this.origin}\n${scope}`).digest('hex');
+                const path = join(directory(), `queue-${key}.json`), lockPath = `${path}.lock`;
+                let lock;
+                try {
+                    lock = await open(lockPath, 'wx', 0o600);
+                }
+                catch {
+                    // Uploads last at most 1.5 s; a much older lock belongs to an interrupted process.
+                    try {
+                        if (Date.now() - (await lstat(lockPath)).mtimeMs > 30_000)
+                            await rm(lockPath);
+                    }
+                    catch { /* Another process owns or removed it. */ }
+                    continue;
+                }
+                try {
+                    const queued = this.pending.filter(item => item.scope === scope).map(item => item.record);
+                    let state = { schema_version: 1, installation_id: await this.installationId(), last_attempt: 0, frozen_ids: [], records: [] };
+                    try {
+                        const saved = await readJson(path);
+                        if (saved.schema_version === 1 && idPattern.test(saved.installation_id) && Array.isArray(saved.records))
+                            state = { ...state, last_attempt: number(saved.last_attempt, Number.MAX_SAFE_INTEGER) ? saved.last_attempt : 0, frozen_ids: Array.isArray(saved.frozen_ids) ? saved.frozen_ids.filter(id => typeof id === 'string' && idPattern.test(id)).slice(0, maximumRecords) : [], records: saved.records.filter(validRecord) };
+                    }
+                    catch { /* Missing, malformed or unsafe state is discarded. */ }
+                    state.records = this.aggregate([...state.records, ...queued], new Set(state.frozen_ids)).slice(-maximumRecords);
+                    state.frozen_ids = state.frozen_ids.filter(id => state.records.some(record => record.event_id === id));
+                    await atomicJson(path, state);
+                    this.pending = this.pending.filter(item => item.scope !== scope);
+                    if (!state.records.length || storeOnly || this.options.offline || !authorized || (!force && Date.now() - state.last_attempt < (this.options.minimumIntervalMs ?? 60_000)))
+                        continue;
+                    const records = [];
+                    for (const record of state.records.slice(0, 50)) {
+                        const candidate = { schema_version: 1, installation_id: state.installation_id, records: [...records, record] };
+                        if (Buffer.byteLength(JSON.stringify(candidate)) > 30_000)
+                            break;
+                        records.push(record);
+                    }
+                    if (!records.length)
+                        continue;
+                    state.last_attempt = Date.now();
+                    // A timed-out upload may already have arrived. Never mutate a record after its first attempt.
+                    state.frozen_ids = [...new Set([...state.frozen_ids, ...records.map(record => record.event_id)])];
+                    await atomicJson(path, state);
+                    const response = await this.fetcher(`${this.origin}/v1/telemetry/developer-tools`, { method: 'POST', headers: { 'Content-Type': 'application/json', ...(scope !== 'anonymous' && this.session ? { Authorization: `Bearer ${this.session.accessToken}` } : {}) }, redirect: 'error', signal: AbortSignal.timeout(scope === 'anonymous' ? 500 : 1500), body: JSON.stringify({ schema_version: 1, installation_id: state.installation_id, records }) });
+                    await response.body?.cancel().catch(() => { });
+                    if (response.ok) {
+                        state.records = state.records.slice(records.length);
+                        state.frozen_ids = state.frozen_ids.filter(id => state.records.some(record => record.event_id === id));
+                        await atomicJson(path, state);
+                    }
+                }
+                catch { /* A failed anonymous upload must not discard the authenticated partition. */ }
+                finally {
+                    await lock.close();
+                    await rm(lockPath, { force: true }).catch(() => { });
+                }
+            }
+            await this.cleanup();
+        }
+        catch { /* Telemetry must not change command results, output or exit status. */ }
+    }
+    aggregate(records, frozen) {
+        const result = [], aggregates = new Map();
+        for (const record of records) {
+            if (record.event !== 'ur.cli.usage' || frozen.has(record.event_id)) {
+                result.push(record);
+                continue;
+            }
+            const key = JSON.stringify([record.command, record.release_version, record.execution_mode, record.workspace_id, record.site_id, record.source_site_environment]);
+            const previous = aggregates.get(key);
+            if (!previous || previous.success_count + record.success_count > 10000 || previous.failure_count + record.failure_count > 10000 || previous.total_duration_ms + record.total_duration_ms > 864000000000) {
+                const next = { ...record };
+                aggregates.set(key, next);
+                result.push(next);
+            }
+            else {
+                previous.success_count += record.success_count;
+                previous.failure_count += record.failure_count;
+                previous.total_duration_ms += record.total_duration_ms;
+                previous.max_duration_ms = Math.max(previous.max_duration_ms, record.max_duration_ms);
+            }
+        }
+        return result;
+    }
+    async installationId() {
+        const path = join(directory(), 'installation.json');
+        try {
+            const state = await readJson(path);
+            if (state.id && idPattern.test(state.id))
+                return state.id;
+        }
+        catch { /* Create a random installation id if absent. */ }
+        const id = randomUUID();
+        try {
+            const file = await open(path, 'wx', 0o600);
+            try {
+                await file.writeFile(JSON.stringify({ id }));
+            }
+            finally {
+                await file.close();
+            }
+            return id;
+        }
+        catch {
+            const state = await readJson(path);
+            if (state.id && idPattern.test(state.id))
+                return state.id;
+            throw new Error('Invalid installation identity');
+        }
+    }
+    async cleanup() {
+        const entries = (await readdir(directory())).filter(name => /^queue-[a-f0-9]{64}\.json$/.test(name)).slice(0, 512);
+        const files = await Promise.all(entries.map(async (name) => ({ path: join(directory(), name), stat: await lstat(join(directory(), name)) })));
+        files.sort((a, b) => b.stat.mtimeMs - a.stat.mtimeMs);
+        for (const [index, { path, stat }] of files.entries()) {
+            if (stat.isSymbolicLink() || Date.now() - stat.mtimeMs > ttl || index >= 32) {
+                try {
+                    await lstat(`${path}.lock`);
+                }
+                catch {
+                    await rm(path, { force: true });
+                }
+            }
+        }
+    }
+}

package/dist/ui.d.ts

@@ -0,0 +1,75 @@
+type Role = 'accent' | 'good' | 'warn' | 'danger' | 'muted' | 'code' | 'faint';
+export declare const stripAnsi: (value: string) => string;
+export declare const textWidth: (value: string) => number;
+/** 0 none, 1 sixteen colours, 2 256 colours, 3 truecolor. Honours NO_COLOR and FORCE_COLOR. */
+export type ColorLevel = 0 | 1 | 2 | 3;
+export declare function detectColorLevel({ stream, env, off }?: {
+    stream?: {
+        isTTY?: boolean;
+    };
+    env?: NodeJS.ProcessEnv;
+    off?: boolean;
+}): ColorLevel;
+export declare function detectAgentHarness(env?: NodeJS.ProcessEnv): string | null;
+export interface UiKit {
+    level: ColorLevel;
+    c: Record<Role | 'bold', (text: string) => string>;
+    S: {
+        info: string;
+        done: string;
+        ask: string;
+        warn: string;
+        error: string;
+        section: string;
+        bar: string;
+        rule: string;
+        arrow: string;
+        dot: string;
+        frames: string[];
+    };
+    symbol: {
+        info: string;
+        done: string;
+        ask: string;
+        warn: string;
+        error: string;
+    };
+    cols(rows: [string, string?][], options?: {
+        gap?: number;
+    }): string[];
+    table(head: string[], rows: string[][]): string[];
+    json(value: unknown, indent?: number): string;
+    header(options: {
+        mode: string;
+        version: string;
+        detail?: string | string[];
+        trademark?: boolean;
+    }): string[];
+}
+export declare function createUiKit({ level, light, ascii, stream }?: {
+    level?: ColorLevel;
+    light?: boolean;
+    ascii?: boolean;
+    stream?: {
+        isTTY?: boolean;
+    };
+}): UiKit;
+/** Stable word prefixes for piped, CI and agent output, so lines can be filtered with grep. */
+export type PlainKind = 'info' | 'done' | 'warn' | 'error' | 'skip' | 'next';
+export declare const plainLine: (kind: PlainKind, text: string) => string;
+/**
+ * A one-line spinner. Unlike clack's it leaves no guide line behind, so a finished task can be replaced
+ * by a single result line. Without a terminal it prints nothing while it runs.
+ */
+export interface Spinner {
+    start(message: string): void;
+    message(message: string): void;
+    stop(finalLine?: string): void;
+}
+export declare function createSpinner(kit: UiKit, stream?: {
+    isTTY?: boolean;
+    write(chunk: string): unknown;
+}, options?: {
+    onCancel?: () => void;
+}): Spinner;
+export {};

package/dist/ui.js

@@ -0,0 +1,107 @@
+// Terminal presentation shared by the CLI and the installation wizard: palette, symbols, colour and
+// agent detection, aligned columns, tables, highlighted JSON and a one-line spinner. Pure code: it
+// reads no files and makes no network requests, so discovery commands stay permission-safe.
+const ESC = '\x1b[';
+const DARK = { accent: [141, 151, 238], good: [76, 195, 138], warn: [240, 163, 94], danger: [242, 119, 125], muted: [139, 139, 150], code: [134, 212, 217], faint: [92, 92, 102] };
+const LIGHT = { accent: [64, 73, 168], good: [24, 121, 78], warn: [180, 72, 12], danger: [194, 42, 50], muted: [95, 96, 104], code: [11, 111, 120], faint: [170, 170, 180] };
+const DARK256 = { accent: 105, good: 78, warn: 215, danger: 210, muted: 245, code: 116, faint: 240 };
+const LIGHT256 = { accent: 61, good: 29, warn: 130, danger: 160, muted: 241, code: 30, faint: 248 };
+const DARK16 = { accent: 94, good: 32, warn: 33, danger: 31, muted: 90, code: 36, faint: 90 };
+const LIGHT16 = { accent: 34, good: 32, warn: 33, danger: 31, muted: 90, code: 36, faint: 90 };
+export const stripAnsi = (value) => String(value).replace(/\x1b\[[0-9;]*m/g, '');
+export const textWidth = (value) => [...stripAnsi(value)].length;
+export function detectColorLevel({ stream = process.stdout, env = process.env, off = false } = {}) {
+    if (off || (env.NO_COLOR ?? '') !== '' || env.FORCE_COLOR === '0')
+        return 0;
+    const forced = (env.FORCE_COLOR ?? '') !== '';
+    if (!forced && (!stream.isTTY || env.TERM === 'dumb'))
+        return 0;
+    if (/truecolor|24bit/i.test(env.COLORTERM ?? ''))
+        return 3;
+    if (/256/.test(env.TERM ?? '') || env.TERM_PROGRAM === 'Apple_Terminal')
+        return 2;
+    return 1;
+}
+/** The variable that identified an agent harness or CI run, from the same set cf checks; null in a person's terminal. */
+const HARNESS = ['CLAUDECODE', 'CURSOR_AGENT', 'GEMINI_CLI', 'OPENCODE', 'CODEX_THREAD_ID', 'AMP_CURRENT_THREAD_ID', 'AI_AGENT', 'CI'];
+export function detectAgentHarness(env = process.env) {
+    return HARNESS.find(key => { const value = env[key]; return value && !['0', 'false', 'no', 'off'].includes(value.toLowerCase()); }) ?? null;
+}
+export function createUiKit({ level, light = false, ascii = false, stream = process.stdout } = {}) {
+    const lv = level ?? detectColorLevel({ stream });
+    const rgb = light ? LIGHT : DARK, p256 = light ? LIGHT256 : DARK256, p16 = light ? LIGHT16 : DARK16;
+    const open = (role) => (lv === 3 ? `${ESC}38;2;${rgb[role].join(';')}m` : lv === 2 ? `${ESC}38;5;${p256[role]}m` : `${ESC}${p16[role]}m`);
+    const paint = (role) => (text) => (lv === 0 ? String(text) : `${open(role)}${text}${ESC}39m`);
+    const c = {
+        accent: paint('accent'), good: paint('good'), warn: paint('warn'), danger: paint('danger'),
+        muted: paint('muted'), code: paint('code'), faint: paint('faint'),
+        bold: (text) => (lv === 0 ? String(text) : `${ESC}1m${text}${ESC}22m`),
+    };
+    const S = ascii
+        ? { info: '*', done: '+', ask: 'o', warn: '!', error: 'x', section: '+', bar: '|', rule: '-', arrow: '>', dot: '-', frames: ['-', '\\', '|', '/'] }
+        : { info: '●', done: '◆', ask: '◇', warn: '▲', error: '■', section: '├', bar: '│', rule: '─', arrow: '›', dot: '·', frames: ['◒', '◐', '◓', '◑'] };
+    const symbol = { info: c.accent(S.info), done: c.good(S.done), ask: c.accent(S.ask), warn: c.warn(S.warn), error: c.danger(S.error) };
+    const cols = (rows, { gap = 2 } = {}) => {
+        const first = Math.max(0, ...rows.map(([left]) => textWidth(left)));
+        return rows.map(([left, right]) => (right === undefined ? left : `${left}${' '.repeat(first - textWidth(left) + gap)}${c.muted(right)}`));
+    };
+    const table = (head, rows) => {
+        const sizes = head.map((title, i) => Math.max(textWidth(title), ...rows.map(row => textWidth(row[i] ?? ''))));
+        const line = (cells) => cells.map((cell, i) => (i === cells.length - 1 ? cell : cell + ' '.repeat((sizes[i] ?? 0) - textWidth(cell) + 2))).join('');
+        return [c.muted(line(head)), ...rows.map(line)];
+    };
+    const json = (value, indent = 2) => {
+        const text = JSON.stringify(value, null, indent);
+        if (lv === 0)
+            return text;
+        return text
+            .replace(/"((?:[^"\\]|\\.)*)":/g, (_, key) => `${c.accent(`"${key}"`)}:`)
+            .replace(/: "((?:[^"\\]|\\.)*)"/g, (_, val) => `: ${c.good(`"${val}"`)}`)
+            .replace(/: (-?\d+\.?\d*|true|false)/g, (_, val) => `: ${c.warn(val)}`)
+            .replace(/: (null)/g, (_, val) => `: ${c.muted(val)}`);
+    };
+    // The trademark sign belongs to the terminal header only: never in plain, piped, JSON or ASCII output.
+    const header = ({ mode, version, detail, trademark = false }) => {
+        const brand = trademark && !ascii ? 'UserReason™' : 'userreason';
+        const lines = [`${c.bold(c.accent(brand))}  ${c.muted(`${mode} ${S.dot} v${version}`)}`];
+        for (const line of [detail ?? []].flat())
+            lines.push(c.muted(line));
+        lines.push(c.faint(S.rule.repeat(54)));
+        return lines;
+    };
+    return { level: lv, c, S, symbol, cols, table, json, header };
+}
+export const plainLine = (kind, text) => `${kind.padEnd(6)} ${stripAnsi(text)}`;
+export function createSpinner(kit, stream = process.stderr, options = {}) {
+    const live = Boolean(stream.isTTY);
+    let timer, frame = 0, text = '', started = 0;
+    const draw = () => {
+        const seconds = Math.floor((Date.now() - started) / 1000);
+        stream.write(`\r${ESC}2K${kit.c.accent(kit.S.frames[frame++ % kit.S.frames.length])}  ${text}${seconds > 0 ? kit.c.muted(` ${kit.S.dot} ${seconds}s`) : ''}`);
+    };
+    const restore = () => stream.write(`\r${ESC}2K${ESC}?25h`);
+    const interrupt = () => { clearInterval(timer); restore(); options.onCancel?.(); process.exit(130); };
+    return {
+        start(message) {
+            text = message;
+            started = Date.now();
+            if (!live)
+                return;
+            stream.write(`${ESC}?25l`);
+            draw();
+            timer = setInterval(draw, 90);
+            process.once('SIGINT', interrupt);
+        },
+        message(message) { text = message; },
+        /** Remove the spinner line; optionally print a final line in its place. */
+        stop(finalLine) {
+            if (live) {
+                clearInterval(timer);
+                process.off('SIGINT', interrupt);
+                restore();
+            }
+            if (finalLine)
+                stream.write(`${finalLine}\n`);
+        },
+    };
+}

package/dist/views.d.ts

@@ -0,0 +1,51 @@
+import type { Account, Grant, Site, Workspace } from './contracts.js';
+import { type UiKit } from './ui.js';
+/** "89 days", "5 hours", "12 minutes" until a timestamp, or null once it has passed. */
+export declare function expiresIn(iso: string, now?: number): string | null;
+/** "all workspaces, expires in 90 days" for the line printed once access is approved. */
+export declare function grantSummary(grant: Pick<Grant, 'all_workspaces' | 'workspace_ids' | 'workspace_id' | 'expires_at'> | undefined, now?: number): string;
+export interface WhoamiResult {
+    user?: Account['user'];
+    workspaces?: Workspace[];
+    grants?: Grant[];
+    api_url: string;
+    project?: ({
+        file?: string;
+        site?: Site;
+        access?: string;
+        next_step?: string;
+    }) | null;
+}
+export declare function whoamiView(kit: UiKit, result: WhoamiResult, options: {
+    development: boolean;
+    now?: number;
+}): string[];
+export declare function sitesView(kit: UiKit, sites: Site[], workspace?: string): string[];
+export declare function workspacesView(kit: UiKit, workspaces: Workspace[]): string[];
+interface PromptRow {
+    id?: unknown;
+    name?: unknown;
+    status?: unknown;
+    revision?: unknown;
+}
+export declare function promptsView(kit: UiKit, page: {
+    items?: PromptRow[];
+    next?: unknown;
+}, site?: string): string[];
+interface OverviewPrompt {
+    name?: unknown;
+    impressions?: unknown;
+    responses?: unknown;
+    status?: unknown;
+}
+export declare function resultsOverviewView(kit: UiKit, overview: {
+    range?: {
+        days?: number;
+    };
+    totals?: {
+        impressions?: number;
+        responses?: number;
+    };
+    prompts?: OverviewPrompt[];
+}, site?: string): string[];
+export {};

package/dist/views.js

@@ -0,0 +1,93 @@
+import { textWidth } from './ui.js';
+const plural = (count, word) => `${count} ${word}${count === 1 ? '' : 's'}`;
+/** "89 days", "5 hours", "12 minutes" until a timestamp, or null once it has passed. */
+export function expiresIn(iso, now = Date.now()) {
+    const ms = Date.parse(iso) - now;
+    if (!Number.isFinite(ms) || ms <= 0)
+        return null;
+    const minutes = Math.ceil(ms / 60_000), hours = Math.ceil(ms / 3_600_000), days = Math.floor(ms / 86_400_000);
+    return minutes < 60 ? plural(minutes, 'minute') : hours < 48 ? plural(hours, 'hour') : plural(days, 'day');
+}
+const domains = (site) => (site.allowed_origins.length ? site.allowed_origins.map(value => value.replace(/^https?:\/\//, '')).join(', ') : 'any domain');
+const environmentLabel = (apiUrl, development) => `${development ? 'development' : 'production'} API (${apiUrl.replace(/^https?:\/\//, '')})`;
+/** What a grant covers, in words: its workspaces. */
+function grantScope(grant) {
+    if (grant.all_workspaces)
+        return 'all workspaces';
+    const count = grant.workspace_ids?.length ?? (grant.workspace_id ? 1 : 0);
+    return count > 0 ? plural(count, 'workspace') : 'this account';
+}
+/** "all workspaces, expires in 90 days" for the line printed once access is approved. */
+export function grantSummary(grant, now = Date.now()) {
+    if (!grant)
+        return '';
+    const left = expiresIn(grant.expires_at, now);
+    return [grantScope(grant), left ? `expires in ${left}` : ''].filter(Boolean).join(', ');
+}
+export function whoamiView(kit, result, options) {
+    const { c, S } = kit;
+    const row = (name, text) => `  ${name.padEnd(14)}${text}`;
+    const email = result.user?.email ?? result.user?.name ?? result.user?.id ?? 'signed in';
+    const environment = environmentLabel(result.api_url, options.development);
+    const lines = [`${c.bold(email)}${' '.repeat(Math.max(2, 46 - textWidth(email)))}${c.muted(environment)}`, ''];
+    lines.push(c.bold('Workspaces'));
+    const workspaces = result.workspaces ?? [];
+    lines.push(...(workspaces.length ? workspaces.map(workspace => row(workspace.name, c.muted(workspace.role ?? 'member'))) : [row('none', c.muted('create one with userreason workspace create --name NAME'))]));
+    lines.push(c.bold('Access'));
+    const active = (result.grants ?? []).filter(grant => !grant.revoked_at && expiresIn(grant.expires_at, options.now));
+    if (!active.length)
+        lines.push(row('none', c.muted('run userreason access --open to approve access')));
+    for (const grant of active) {
+        lines.push(row('CLI access', `${grantScope(grant)} ${c.muted(`${S.dot} expires in ${expiresIn(grant.expires_at, options.now)}`)}`));
+        lines.push(row('', c.code(grant.scopes.join('  '))));
+    }
+    if (result.project) {
+        lines.push(c.bold('Project'));
+        const { site, access, file, next_step } = result.project;
+        if (site)
+            lines.push(row(site.name, `${c.muted(`(${site.environment}, ${domains(site)})`)} ${S.dot} ${c.good('access approved')}`));
+        else
+            lines.push(row('this project', `${c.muted(`(${access ?? 'no access'})`)}${next_step ? ` ${S.dot} ${c.code(next_step)}` : ''}`));
+        if (file)
+            lines.push(row('', c.muted(file)));
+    }
+    return lines;
+}
+export function sitesView(kit, sites, workspace) {
+    const { c } = kit;
+    const title = c.bold(workspace ? `Sites in ${workspace}` : 'Sites');
+    if (!sites.length)
+        return [title, '', c.muted('No sites yet. Create one with userreason site create --name NAME.')];
+    return [title, '', ...kit.table(['NAME', 'ENVIRONMENT', 'DOMAINS', 'ID'], sites.map(site => [site.name, site.environment, domains(site), c.code(site.id)]))];
+}
+export function workspacesView(kit, workspaces) {
+    const { c } = kit;
+    if (!workspaces.length)
+        return [c.bold('Workspaces'), '', c.muted('No workspaces yet. Create one with userreason workspace create --name NAME.')];
+    return [c.bold('Workspaces'), '', ...kit.table(['NAME', 'ROLE', 'ID'], workspaces.map(workspace => [workspace.name, workspace.role ?? 'member', c.code(workspace.id)]))];
+}
+export function promptsView(kit, page, site) {
+    const { c } = kit;
+    const title = `${c.bold('Surveys')}${site ? ` ${c.muted(`(${site})`)}` : ''}`;
+    const items = Array.isArray(page.items) ? page.items : [];
+    if (!items.length)
+        return [title, '', c.muted('No surveys yet. Create one with userreason prompt create --file PROMPT.json.')];
+    const status = (value) => { const text = String(value ?? ''); return text === 'published' || text === 'active' ? c.good(text) : c.muted(text); };
+    const lines = [title, '', ...kit.table(['NAME', 'STATUS', 'REV', 'ID'], items.map(item => [String(item.name ?? ''), status(item.status), String(item.revision ?? ''), c.code(String(item.id ?? ''))]))];
+    if (page.next)
+        lines.push('', c.muted(`More: add --after ${String(page.next)}`));
+    return lines;
+}
+export function resultsOverviewView(kit, overview, site) {
+    const { c } = kit;
+    const days = overview.range?.days;
+    const detail = [site, days ? `last ${plural(days, 'day')}` : ''].filter(Boolean).join(', ');
+    const title = `${c.bold('Results')}${detail ? ` ${c.muted(`(${detail})`)}` : ''}`;
+    const prompts = Array.isArray(overview.prompts) ? overview.prompts : [];
+    const number = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : 0);
+    const rate = (shown, answered) => (shown > 0 ? `${Math.round((answered / shown) * 100)}%` : '–');
+    const table = (rows) => (rows.length ? kit.table(['SURVEY', 'SHOWN', 'ANSWERED', 'RATE'], rows) : [c.muted('No surveys in this range.')]);
+    const rows = prompts.map(prompt => [String(prompt.name ?? ''), number(prompt.impressions).toLocaleString('en'), number(prompt.responses).toLocaleString('en'), rate(number(prompt.impressions), number(prompt.responses))]);
+    const total = overview.totals && prompts.length > 1 ? [c.muted(`Total: ${number(overview.totals.impressions).toLocaleString('en')} shown, ${number(overview.totals.responses).toLocaleString('en')} answered (${rate(number(overview.totals.impressions), number(overview.totals.responses))})`)] : [];
+    return [title, '', ...table(rows), ...(total.length ? ['', ...total] : [])];
+}

package/dist/workos.d.ts

@@ -17,5 +17,5 @@ export declare function login(config: ClientConfig, credentials: Credentials, on
     sleep?: typeof sleep;
     now?: () => number;
 }): Promise<Session>;
-export declare function refresh(config: ClientConfig, credentials: Credentials, current: Session, fetcher?: Fetch): Promise<Session>;
+export declare function refresh(config: ClientConfig, credentials: Credentials, current: Session, fetcher?: Fetch, signal?: AbortSignal): Promise<Session>;
 export {};