vibe-usage-cli 0.0.0-stage → 0.1.1

package/build/core/launch.js

@@ -0,0 +1,256 @@
+// Starts provider tools for the user: a CLI in a new terminal window, or a desktop app.
+// Arguments are always passed as arrays; nothing is concatenated into a shell command line.
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { findBinary, TOOL_INSTALLS, unpackedPath, windowsAppPath, windowsPowerShell } from "../providers/common.js";
+import { CLAUDE_FILES, DEFAULT_ACCOUNT_ID as CLAUDE_DEFAULT_ACCOUNT_ID } from "../providers/claude.js";
+import { findCursorAgent } from "../providers/cursor.js";
+import { CLAUDE_EFFORT_LEVELS, CLAUDE_PERMISSION_MODES, isOneOf, MODEL_ID_PATTERN, PROFILE_DIRS, PROFILE_ENV } from "../shared/catalog.js";
+import { prepareClaudeProfile } from "./claude-profile.js";
+import { applyEnvironment, environmentChanges } from "./environment.js";
+import { AppError } from "./errors.js";
+import { claudeLaunchWarnings } from "./selection.js";
+import { isDirectory, isFile, readJson, writeFileAtomic } from "./files.js";
+import { hasControlChars } from "./model.js";
+import { validateConfigDir } from "./settings.js";
+const LAUNCHER_DIR = 'launchers';
+const MAC_OPEN = '/usr/bin/open';
+const TERMINAL_SCRIPT = unpackedPath(path.resolve(import.meta.dirname, '../launchers/terminal.ps1'));
+const DETACHED = { shell: false, detached: true, stdio: 'ignore' };
+export function shellQuote(value) {
+    if (hasControlChars(value))
+        throw new AppError('invalid_argument');
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+function waitForSpawn(child) {
+    return new Promise((resolve, reject) => {
+        child.once('spawn', () => {
+            child.unref();
+            resolve();
+        });
+        child.once('error', error => {
+            reject(new AppError('launch_failed', {}, { cause: error }));
+        });
+    });
+}
+// A one-off script Terminal runs; it removes itself once started, so none accumulate.
+async function writeMacLauncher({ cwd, command, changes, title, dataDir }) {
+    const dir = path.join(dataDir, LAUNCHER_DIR);
+    const script = path.join(dir, `${path.basename(command[0])}-${randomBytes(6).toString('hex')}.command`);
+    const lines = [
+        '#!/bin/zsh',
+        `rm -f -- ${shellQuote(script)}`,
+        `cd -- ${shellQuote(cwd)} || exit 1`,
+        changes.unset.length ? `unset ${changes.unset.join(' ')}` : '',
+        ...Object.entries(changes.set).map(([name, value]) => `export ${name}=${shellQuote(value)}`),
+        title ? `printf '%s\\n' ${shellQuote(title)}` : '',
+        `exec ${command.map(shellQuote).join(' ')}`
+    ].filter(Boolean);
+    await fsp.mkdir(dir, { recursive: true });
+    await fsp.writeFile(script, `${lines.join('\n')}\n`, { mode: 0o700 });
+    return script;
+}
+// NUL cannot occur inside an argument, so it separates them unambiguously.
+const encodeArguments = (args) => Buffer.from(args.join('\0'), 'utf8').toString('base64');
+// Opens `binary args…` in a new terminal window inside `cwd`.
+export async function openInTerminal({ cwd, binary, args, env, title, handoff, dataDir, platform = process.platform, spawnProcess = spawn }) {
+    if (args.some(arg => arg.includes('\0')))
+        throw new AppError('invalid_argument');
+    const changes = environmentChanges(env);
+    if (platform === 'darwin') {
+        const script = await writeMacLauncher({ cwd, command: [binary, ...args], changes, title, dataDir });
+        return waitForSpawn(spawnProcess(MAC_OPEN, ['-a', 'Terminal', script], DETACHED));
+    }
+    if (platform === 'win32') {
+        // A detached process gets no console, and PowerShell exits without one; the hidden
+        // script opens the tool's window itself (see terminal.ps1 -NewWindow).
+        const psArgs = [
+            '-NoLogo',
+            '-NoProfile',
+            '-NonInteractive',
+            '-ExecutionPolicy',
+            'Bypass',
+            '-File',
+            TERMINAL_SCRIPT,
+            '-WorkingDirectory',
+            cwd,
+            '-Executable',
+            binary,
+            ...(title ? ['-Title', title] : []),
+            ...(args.length ? ['-ArgumentsBase64', encodeArguments(args)] : []),
+            ...(handoff ? ['-Handoff', handoff] : []),
+            '-NewWindow'
+        ];
+        return waitForSpawn(spawnProcess(windowsPowerShell(), psArgs, {
+            shell: false,
+            stdio: 'ignore',
+            windowsHide: true,
+            env: applyEnvironment(changes, process.env, platform)
+        }));
+    }
+    throw new AppError('unsupported_platform');
+}
+// Opens the tool's desktop app, on the project folder when there is one.
+export async function openDesktopApp({ providerId, cwd, platform = process.platform, env = process.env, home = os.homedir(), spawnProcess = spawn }) {
+    const { app } = TOOL_INSTALLS[providerId];
+    if (!app)
+        throw new AppError('unsupported_platform');
+    const project = cwd ? [cwd] : [];
+    if (platform === 'darwin')
+        return waitForSpawn(spawnProcess(MAC_OPEN, ['-a', app.mac, ...project], DETACHED));
+    if (platform === 'win32') {
+        const executable = windowsAppPath(app, env, home);
+        if (!(await isFile(executable)))
+            throw new AppError('app_not_found', { app: app.mac });
+        return waitForSpawn(spawnProcess(executable, project, DETACHED));
+    }
+    throw new AppError('unsupported_platform');
+}
+// The environment that points a tool at the account's profile folder, for launches and
+// sign-ins alike. The default Claude profile must run with CLAUDE_CONFIG_DIR unset: setting
+// it, even to the default directory, selects a different Keychain entry on macOS.
+// Resuming a long session idle for over an hour, Claude Code asks whether to compact it or go
+// on. A session the app resumes may do so unattended, so for it that threshold is moved out
+// of reach (ten years). The user's own resumes keep the question.
+export const CLAUDE_RESUME_THRESHOLD_ENV = 'CLAUDE_CODE_RESUME_THRESHOLD_MINUTES';
+export const RESUME_WITHOUT_QUESTION = String(10 * 365 * 24 * 60);
+export function profileEnvironment(account) {
+    if (account.providerId === 'claude') {
+        const isDefault = account.id === CLAUDE_DEFAULT_ACCOUNT_ID || account.configDirExplicit === false;
+        return isDefault ? { unset: [PROFILE_ENV.claude] } : { set: { [PROFILE_ENV.claude]: validateConfigDir(account.configDir) } };
+    }
+    if (account.providerId === 'codex' && account.configDir)
+        return { set: { [PROFILE_ENV.codex]: validateConfigDir(account.configDir) } };
+    return {};
+}
+// Session ids are UUIDs; anything else (a flag, say) never reaches the command line.
+const SESSION_ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9-]{0,127}$/;
+const optional = (flag, value) => (value ? [flag, value] : []);
+const trailing = (value) => (value ? [value] : []);
+// How each provider's CLI starts with an optional model and initial prompt; null when the
+// provider only exists as a desktop app.
+const LAUNCHERS = {
+    async claude({ account, model, prompt, resume, permissionMode, effort }) {
+        if (!account?.configDir)
+            throw new AppError('account_not_found');
+        const env = profileEnvironment(account);
+        return {
+            binary: await findBinary('claude'),
+            args: [
+                ...optional('--resume', resume),
+                ...optional('--model', model),
+                ...optional('--permission-mode', permissionMode),
+                ...optional('--effort', effort),
+                ...trailing(prompt)
+            ],
+            env: resume ? { ...env, set: { ...env.set, [CLAUDE_RESUME_THRESHOLD_ENV]: RESUME_WITHOUT_QUESTION } } : env
+        };
+    },
+    async codex({ account, model, prompt }) {
+        return {
+            binary: await findBinary('codex'),
+            args: [...optional('-m', model), ...trailing(prompt)],
+            env: account ? profileEnvironment(account) : {}
+        };
+    },
+    async cursor({ model, prompt }) {
+        // Only the Cursor Agent CLI runs a task in a terminal; without it the app is opened.
+        const binary = await findCursorAgent();
+        return binary ? { binary, args: ['--trust', ...optional('--model', model), ...trailing(prompt)], env: {} } : null;
+    },
+    antigravity: () => Promise.resolve(null)
+};
+// Model ids come from settings, the UI or the command line, so they are checked here,
+// synchronously, before anything is looked up.
+export function launchPlan(providerId, options) {
+    if (options.model && !MODEL_ID_PATTERN.test(options.model))
+        throw new AppError('invalid_argument');
+    if (options.resume !== undefined && (providerId !== 'claude' || !SESSION_ID_PATTERN.test(options.resume)))
+        throw new AppError('invalid_argument');
+    if (options.permissionMode !== undefined && (providerId !== 'claude' || !isOneOf(CLAUDE_PERMISSION_MODES, options.permissionMode)))
+        throw new AppError('invalid_argument');
+    if (options.effort !== undefined && (providerId !== 'claude' || !isOneOf(CLAUDE_EFFORT_LEVELS, options.effort)))
+        throw new AppError('invalid_argument');
+    return LAUNCHERS[providerId](options);
+}
+// A project folder from the user: a valid local path to an existing directory.
+export async function projectDirectory(dir) {
+    const directory = validateConfigDir(dir);
+    if (!(await isDirectory(directory)))
+        throw new AppError('folder_not_found');
+    return directory;
+}
+async function preparedLaunch({ providerId, account, cwd, model, prompt, resume, permissionMode, effort, accounts, homeDir }) {
+    const directory = await projectDirectory(cwd);
+    const plan = await launchPlan(providerId, { account, model, prompt, resume, permissionMode, effort });
+    // Unprepared, the session would wait at Claude Code's first-run questions; they can still
+    // be answered there, so a failure to prepare it does not stop the launch.
+    if (plan && providerId === 'claude' && account && accounts)
+        await prepareClaudeProfile(account, accounts, directory, homeDir).catch(() => undefined);
+    return { directory, plan };
+}
+export async function launchTool(launch) {
+    const { providerId, dataDir, title, platform, spawnProcess, handoff } = launch;
+    const { directory, plan } = await preparedLaunch(launch);
+    if (!plan) {
+        await openDesktopApp({ providerId, cwd: directory, platform, spawnProcess });
+        return { mode: 'app' };
+    }
+    await openInTerminal({ cwd: directory, ...plan, title, handoff, dataDir, platform, spawnProcess });
+    return { mode: 'terminal' };
+}
+// Writes the command a tab opened with `handoff` runs next, once its tool exits (see
+// terminal.ps1). False when the tool has no command line to run there.
+export async function writeHandoff(file, launch) {
+    const { directory, plan } = await preparedLaunch(launch);
+    if (!plan)
+        return false;
+    if (plan.args.some(arg => arg.includes('\0')))
+        throw new AppError('invalid_argument');
+    const { set, unset } = environmentChanges(plan.env);
+    const next = {
+        workingDirectory: directory,
+        executable: plan.binary,
+        title: launch.title,
+        argumentsBase64: encodeArguments(plan.args),
+        set,
+        unset
+    };
+    await writeFileAtomic(file, JSON.stringify(next));
+    return true;
+}
+// Sign-in flows: each CLI handles its own login; desktop apps sign in inside the app.
+// Plain `claude` only asks to sign in when no credentials exist; expired ones open a session.
+const LOGIN_ARGS = { claude: ['auth', 'login'], codex: ['login'] };
+export async function openSignIn({ providerId, account, dataDir, cwd, platform, spawnProcess }) {
+    const args = LOGIN_ARGS[providerId];
+    if (!args)
+        return openDesktopApp({ providerId, platform, spawnProcess });
+    const env = account ? profileEnvironment(account) : {};
+    return openInTerminal({ cwd, binary: await findBinary(providerId), args, env, dataDir, platform, spawnProcess });
+}
+// Claude settings files that can override the selected profile's identity, keyed by name.
+export async function loadClaudeSettingsFiles(projectDir, configDir) {
+    const files = {};
+    const read = async (dir, file) => {
+        files[`${path.basename(dir)}/${file}`] = await readJson(path.join(dir, file));
+    };
+    if (projectDir) {
+        const projectSettings = path.join(projectDir, PROFILE_DIRS.claude);
+        await read(projectSettings, CLAUDE_FILES.settings);
+        await read(projectSettings, CLAUDE_FILES.localSettings);
+    }
+    if (configDir)
+        await read(configDir, CLAUDE_FILES.settings);
+    return files;
+}
+// What to warn about before starting the tool signed in as `account` in `projectDir`. Only
+// Claude Code has settings that can override the chosen profile.
+export async function launchWarnings(snapshot, account, { projectDir, model }) {
+    if (account.providerId !== 'claude')
+        return [];
+    return claudeLaunchWarnings(snapshot, account, { model, settingsFiles: await loadClaudeSettingsFiles(projectDir, account.configDir) });
+}

package/build/core/measurements.d.ts

@@ -0,0 +1,11 @@
+import type { MeasuredAccount, QuotaWindow } from '../shared/types.ts';
+export declare const MEASUREMENTS_FILE = "measurements.json";
+export interface SavedMeasurement {
+    configDir: string | null;
+    fetchedAt: string;
+    plan?: string;
+    windows: QuotaWindow[];
+}
+export declare function loadMeasurements(file: string, now?: number): Promise<Map<string, SavedMeasurement>>;
+export declare function measurementOf(account: MeasuredAccount): SavedMeasurement | null;
+export declare function saveMeasurements(file: string, saved: ReadonlyMap<string, SavedMeasurement>): Promise<void>;

package/build/core/measurements.js

@@ -0,0 +1,75 @@
+// The last good reading of each account, kept on disk. After a restart the app shows it,
+// labelled stale, until the first fresh read: a source that is rate limited or offline at that
+// moment then leaves the last known quota in view instead of an empty card. Only what the
+// readings say about quota is kept, never tokens, emails or names.
+import { hasKey } from "../shared/i18n/index.js";
+import { isObject, readJson, writeFileAtomic } from "./files.js";
+import { normalizeWindow } from "./model.js";
+import { DURATION_MS } from "../shared/catalog.js";
+export const MEASUREMENTS_FILE = 'measurements.json';
+// A reading older than this says too little about the quota now to be worth showing.
+const KEPT_READING_MAX_AGE_MS = 7 * DURATION_MS.DAY;
+const MAX_WINDOWS = 50;
+// A message key from the file counts only when it is one the app knows.
+const isKnownKey = (value) => typeof value === 'string' && hasKey(value);
+function savedWindow(value) {
+    if (!isObject(value) || typeof value.id !== 'string')
+        return null;
+    const n = isObject(value.labelParams) ? value.labelParams.n : undefined;
+    return normalizeWindow({
+        id: value.id,
+        usedPercent: value.usedPercent,
+        remainingPercent: value.remainingPercent,
+        resetsAt: value.resetsAt,
+        ...(typeof value.label === 'string' ? { label: value.label } : {}),
+        ...(isKnownKey(value.labelKey) ? { labelKey: value.labelKey } : {}),
+        ...(typeof n === 'number' && Number.isFinite(n) ? { labelParams: { n } } : {}),
+        ...(isKnownKey(value.detailKey) ? { detailKey: value.detailKey } : {}),
+        ...(isKnownKey(value.valueKey) ? { valueKey: value.valueKey } : {}),
+        ...(typeof value.durationMinutes === 'number' ? { durationMinutes: value.durationMinutes } : {}),
+        ...(typeof value.scope === 'string' ? { scope: value.scope } : {}),
+        active: value.active,
+        ...(typeof value.group === 'string' ? { group: value.group } : {}),
+        ...(value.section === 'details' ? { section: 'details' } : {}),
+        ...(value.partial === true ? { partial: true } : {}),
+        except: value.except,
+        amounts: value.amounts
+    });
+}
+// The saved readings by account id; a damaged or foreign file gives none.
+export async function loadMeasurements(file, now = Date.now()) {
+    const document = await readJson(file);
+    const saved = new Map();
+    if (!isObject(document) || !isObject(document.accounts))
+        return saved;
+    for (const [id, entry] of Object.entries(document.accounts)) {
+        if (!isObject(entry) || typeof entry.fetchedAt !== 'string' || !Array.isArray(entry.windows))
+            continue;
+        const at = Date.parse(entry.fetchedAt);
+        if (!Number.isFinite(at) || at > now || now - at > KEPT_READING_MAX_AGE_MS)
+            continue;
+        const windows = entry.windows
+            .slice(0, MAX_WINDOWS)
+            .map(savedWindow)
+            .filter(w => w !== null);
+        if (!windows.length)
+            continue;
+        saved.set(id, {
+            configDir: typeof entry.configDir === 'string' ? entry.configDir : null,
+            fetchedAt: new Date(at).toISOString(),
+            ...(typeof entry.plan === 'string' ? { plan: entry.plan } : {}),
+            windows
+        });
+    }
+    return saved;
+}
+// The reading worth keeping from an account: a good one, without what was carried over.
+export function measurementOf(account) {
+    const windows = account.windows.filter(w => !w.stale).map(({ exhaustsAt: _forecast, ...window }) => window);
+    if (account.status !== 'ok' || !account.fetchedAt || !windows.length)
+        return null;
+    return { configDir: account.configDir ?? null, fetchedAt: account.fetchedAt, ...(account.plan ? { plan: account.plan } : {}), windows };
+}
+export function saveMeasurements(file, saved) {
+    return writeFileAtomic(file, JSON.stringify({ version: 1, accounts: Object.fromEntries(saved) }));
+}

package/build/core/model-families.d.ts

@@ -0,0 +1,12 @@
+declare const MODEL_TIERS: readonly ["flagship", "balanced", "fast"];
+export type ModelTier = (typeof MODEL_TIERS)[number];
+export declare const nameMatchesFamily: (name: string, family: string) => boolean;
+export declare const tierFamilies: (tier: ModelTier) => string[];
+export declare function modelTier(model: string): ModelTier | undefined;
+export declare function quotaScopeFamily(model: string | undefined): {
+    name: string;
+    scopeRequired: boolean;
+} | undefined;
+export declare const CLAUDE_ALIASES: readonly string[];
+export declare function claudeAlias(tier: ModelTier): string;
+export {};

package/build/core/model-families.js

@@ -0,0 +1,61 @@
+// What the app knows about model families. No provider publishes a model's tier or which
+// quota covers it, so this is matched by name; this table is the only place that knows it.
+// From the most capable to the fastest.
+const MODEL_TIERS = ['flagship', 'balanced', 'fast'];
+// Within a tier, the most preferred family first.
+const MODEL_FAMILIES = {
+    opus: { tier: 'flagship', quotaScope: true, claudeAlias: true },
+    fable: { tier: 'flagship', quotaScope: true, scopeRequired: true, claudeAlias: true },
+    terra: { tier: 'flagship' },
+    sol: { tier: 'flagship' },
+    pro: { tier: 'flagship' },
+    'grok-4': { tier: 'flagship' },
+    sonnet: { tier: 'balanced', quotaScope: true, claudeAlias: true },
+    luna: { tier: 'balanced' },
+    flash: { tier: 'balanced' },
+    composer: { tier: 'balanced' },
+    haiku: { tier: 'fast', quotaScope: true, claudeAlias: true },
+    mini: { tier: 'fast' },
+    nano: { tier: 'fast' },
+    lite: { tier: 'fast' },
+    spark: { tier: 'fast' },
+    gemini: { quotaScope: true },
+    gpt: { quotaScope: true }
+};
+const FAMILIES = Object.entries(MODEL_FAMILIES).map(([name, family]) => ({ name, ...family }));
+// Whether a model or quota scope name belongs to the family: as a word of its own, so that
+// "gemini" is not taken for "mini".
+export const nameMatchesFamily = (name, family) => familyPosition(name, family) >= 0;
+// Where the family's name stands in a name as a word of its own; -1 when it does not.
+function familyPosition(name, family) {
+    const match = new RegExp(`(^|[^a-z])${RegExp.escape(family)}([^a-z]|$)`).exec(name.toLowerCase());
+    return match ? match.index + (match[1] ?? '').length : -1;
+}
+// The tier's families, most preferred first.
+export const tierFamilies = (tier) => FAMILIES.filter(f => f.tier === tier).map(f => f.name);
+// A model's tier: a name naming several families takes the last one, as a variant is named after
+// its base (`gemini-2.5-flash-lite` is the lite one, `gpt-5.4-mini` the mini one).
+export function modelTier(model) {
+    let tier;
+    let last = -1;
+    for (const family of FAMILIES) {
+        const at = family.tier ? familyPosition(model, family.name) : -1;
+        if (at > last)
+            [tier, last] = [family.tier, at];
+    }
+    return tier;
+}
+// The family a provider would report the model's own quota under, if any.
+export function quotaScopeFamily(model) {
+    const family = model ? FAMILIES.find(f => f.quotaScope && nameMatchesFamily(model, f.name)) : undefined;
+    return family ? { name: family.name, scopeRequired: family.scopeRequired === true } : undefined;
+}
+// The names Claude Code takes for its newest model of a family, most capable first.
+export const CLAUDE_ALIASES = MODEL_TIERS.flatMap(tier => FAMILIES.filter(f => f.tier === tier && f.claudeAlias).map(f => f.name));
+// Claude Code's alias for the newest model of the tier.
+export function claudeAlias(tier) {
+    const alias = FAMILIES.find(f => f.tier === tier && f.claudeAlias);
+    if (!alias)
+        throw new Error(`no Claude Code alias for the ${tier} tier`);
+    return alias.name;
+}

package/build/core/model.d.ts

@@ -0,0 +1,32 @@
+import type { MessageKey } from '../shared/i18n/index.ts';
+import type { QuotaWindow } from '../shared/types.ts';
+export declare const percent: (value: unknown) => number | null;
+export declare function isoDate(value: unknown): string | null;
+export declare function isoFromUnixSeconds(value: unknown): string | null;
+export declare const hasControlChars: (value: string) => boolean;
+export declare function safeText(value: unknown, fallback?: string, max?: number): string;
+export declare const normalizeEmail: (value: string) => string;
+export declare function safeEmail(value: unknown): string | undefined;
+export declare function safePlan(value: unknown): string | undefined;
+export interface WindowInput {
+    id: string;
+    usedPercent?: unknown;
+    remainingPercent?: unknown;
+    resetsAt?: unknown;
+    label?: string;
+    labelKey?: MessageKey;
+    labelParams?: {
+        n: number;
+    };
+    detailKey?: MessageKey;
+    valueKey?: MessageKey | undefined;
+    durationMinutes?: number;
+    scope?: string;
+    active?: unknown;
+    group?: string;
+    section?: 'details';
+    partial?: boolean;
+    except?: unknown;
+    amounts?: unknown;
+}
+export declare function normalizeWindow(input: WindowInput): QuotaWindow;

package/build/core/model.js

@@ -0,0 +1,86 @@
+import { MODEL_ID_PATTERN } from "../shared/catalog.js";
+import { asArray, isObject } from "./files.js";
+export const percent = (value) => typeof value === 'number' && Number.isFinite(value) ? Math.max(0, Math.min(100, value)) : null;
+const toIso = (date) => (Number.isFinite(date.getTime()) ? date.toISOString() : null);
+// An ISO timestamp from a date string or a Date; null for anything else.
+export function isoDate(value) {
+    return (typeof value === 'string' && value !== '') || value instanceof Date ? toIso(new Date(value)) : null;
+}
+export function isoFromUnixSeconds(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? toIso(new Date(value * 1000)) : null;
+}
+// Control characters never belong in a name, path, id or token the app shows or passes on.
+// eslint-disable-next-line no-control-regex -- matching control characters is the purpose
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/g;
+// `search` and `replace` ignore lastIndex, so the shared global pattern carries no state.
+export const hasControlChars = (value) => value.search(CONTROL_CHARS) !== -1;
+const stripControlChars = (value) => value.replace(CONTROL_CHARS, '');
+const TEXT_MAX_LENGTH = 160;
+export function safeText(value, fallback = '', max = TEXT_MAX_LENGTH) {
+    return typeof value === 'string' ? stripControlChars(value).slice(0, max) : fallback;
+}
+// An e-mail address a tool recorded for its signed-in account, shown as the account's name.
+const EMAIL = /^[^\s@]{1,128}@[^\s@]{1,127}$/;
+// The one form e-mail addresses are compared and kept in.
+export const normalizeEmail = (value) => value.trim().toLowerCase();
+export function safeEmail(value) {
+    const email = typeof value === 'string' ? normalizeEmail(value) : '';
+    return EMAIL.test(email) && !hasControlChars(email) ? email : undefined;
+}
+// Plan names come from the provider and are shown as a badge; anything unusual is dropped.
+const PLAN_NAME = /^[a-zA-Z][a-zA-Z0-9_ -]{0,40}$/;
+export function safePlan(value) {
+    return typeof value === 'string' && PLAN_NAME.test(value) ? value : undefined;
+}
+const AMOUNT_FIELDS = ['used', 'limit', 'remaining', 'bonus'];
+function safeAmounts(input) {
+    if (!isObject(input))
+        return undefined;
+    const amounts = {};
+    for (const field of AMOUNT_FIELDS) {
+        const value = input[field];
+        if (typeof value === 'number' && Number.isFinite(value))
+            amounts[field] = value;
+    }
+    return Object.keys(amounts).length ? amounts : undefined;
+}
+// A window with only contract fields. Unknown numbers and resets stay unknown; a used or a
+// remaining percentage implies the other.
+export function normalizeWindow(input) {
+    let usedPercent = percent(input.usedPercent);
+    let remainingPercent = percent(input.remainingPercent);
+    if (usedPercent === null && remainingPercent !== null)
+        usedPercent = 100 - remainingPercent;
+    if (remainingPercent === null && usedPercent !== null)
+        remainingPercent = 100 - usedPercent;
+    const window = { id: safeText(input.id, 'unknown'), usedPercent, remainingPercent, resetsAt: isoDate(input.resetsAt) };
+    if (input.label)
+        window.label = safeText(input.label);
+    if (input.labelKey)
+        window.labelKey = input.labelKey;
+    if (input.labelParams)
+        window.labelParams = input.labelParams;
+    if (input.detailKey)
+        window.detailKey = input.detailKey;
+    if (input.valueKey)
+        window.valueKey = input.valueKey;
+    if (input.durationMinutes !== undefined && Number.isFinite(input.durationMinutes))
+        window.durationMinutes = input.durationMinutes;
+    if (input.scope)
+        window.scope = safeText(input.scope);
+    if (typeof input.active === 'boolean')
+        window.active = input.active;
+    if (input.group === 'team')
+        window.group = 'team';
+    if (input.section === 'details')
+        window.section = 'details';
+    if (input.partial === true)
+        window.partial = true;
+    const except = asArray(input.except).filter((m) => typeof m === 'string' && MODEL_ID_PATTERN.test(m));
+    if (window.partial && except.length)
+        window.except = except.map(m => m.toLowerCase());
+    const amounts = safeAmounts(input.amounts);
+    if (amounts)
+        window.amounts = amounts;
+    return window;
+}

package/build/core/models.d.ts

@@ -0,0 +1,25 @@
+import { type ModelTier } from './model-families.ts';
+import type { ProviderId } from '../shared/catalog.ts';
+import type { ModelCatalog } from '../shared/ipc.ts';
+import type { Account } from '../shared/types.ts';
+export interface ModelLocation {
+    homeDir?: string | undefined;
+    cacheDir?: string | undefined;
+    accounts?: readonly Account[] | undefined;
+}
+export declare function parseCursorModelList(output: string): string[];
+export interface CursorRefresh {
+    cacheDir?: string;
+    force?: boolean;
+    binary?: string;
+    now?: number;
+}
+export declare function refreshCursorModels({ cacheDir, force, binary, now }?: CursorRefresh): Promise<string[] | null>;
+export declare function discoverModels({ homeDir, cacheDir, accounts }?: ModelLocation): ModelCatalog;
+export declare const resolveModelTier: (modelName: string | null | undefined) => ModelTier;
+export interface ModelMapping {
+    tier: ModelTier;
+    targetModel: string | null;
+    source: 'preference' | 'same' | 'tier';
+}
+export declare function getMappedModel(sourceModel: string | null | undefined, targetProvider: ProviderId, preferences?: Partial<Record<ProviderId, string>>, location?: ModelLocation): ModelMapping;