@cjhyy/code-shell-core 0.5.0-rc.0

package/dist/onboarding.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Onboarding data layer — provider catalog, env detection, key validation,
+ * settings persistence. The interactive flow itself is rendered by Ink
+ * (see src/ui/components/OnboardingPrompt.tsx); this module only exposes
+ * pure(-ish) helpers it consumes, so there's a single input stack.
+ */
+export interface OnboardingResult {
+    /**
+     * Pool alias key (e.g. "deepseek-v4-pro"). The engine uses this to switch
+     * the active model — callers should NOT re-derive an alias from `model`
+     * (the old modelKey() helper folded multiple model ids to one key, which
+     * silently shadowed entries in the pool).
+     */
+    key: string;
+    provider: string;
+    model: string;
+    apiKey: string;
+    baseUrl: string;
+}
+export interface ProviderDef {
+    id: string;
+    name: string;
+    envKey: string;
+    provider: string;
+    baseUrl: string;
+    keyUrl: string;
+    keyPrefix: string;
+    /**
+     * The catalog of model IDs to register for this provider. The first
+     * entry doubles as the zero-config default — auto-activated when the
+     * user boots with just an env key (no onboarding). Users override by
+     * picking in the wizard or running `/model`.
+     */
+    models: string[];
+    /** When true, skip API key prompt (e.g. local providers like Ollama). */
+    noKey?: boolean;
+}
+export declare const PROVIDERS: ProviderDef[];
+/**
+ * Resolve the model list a provider should expose right now. For
+ * OpenRouter this comes from the snapshot; for direct providers it
+ * stays hardcoded (snapshot doesn't carry their native IDs).
+ */
+export declare function resolveProviderModels(provider: ProviderDef): string[];
+export interface DetectedEnvKey {
+    provider: ProviderDef;
+    envKey: string;
+    apiKey: string;
+}
+/**
+ * Scan environment for known provider API keys.
+ * Returns one entry per provider that has its envKey set.
+ */
+export declare function detectEnvKeys(): DetectedEnvKey[];
+/** Mask a key for display: "sk-517f...b594" */
+export declare function maskKey(key: string): string;
+/**
+ * Find a provider definition that matches a given API key.
+ * Checks key prefix first, then env var match, then baseUrl.
+ */
+export declare function detectProviderFromApiKey(apiKey: string, baseUrl?: string): ProviderDef | undefined;
+export declare function validateApiKey(baseUrl: string, apiKey: string): Promise<boolean>;
+/**
+ * Resolve an API key from the canonical fallback chain.
+ * Priority: 1) command-line option  2) settings.json  3) all provider env vars
+ */
+export declare function resolveApiKey(optionsApiKey?: string, settingsApiKey?: string): string | undefined;
+/**
+ * Look up a previously-persisted API key for a given provider in
+ * ~/.code-shell/settings.json. Matches by baseUrl (each ProviderDef.baseUrl
+ * is unique, while `provider` is a generic kind like "openai" shared across
+ * multiple endpoints).
+ *
+ * Returns the first match found in: settings.models[] (preferred — newer),
+ * then settings.model (legacy top-level). undefined when nothing matches.
+ */
+export declare function findSavedKeyForProvider(provider: ProviderDef): {
+    apiKey: string;
+    baseUrl: string;
+} | undefined;
+/**
+ * Return the list of model IDs previously saved under this provider
+ * (matched by baseUrl). Used by the onboarding wizard to pre-populate the
+ * "model pool" step with the user's prior choices instead of resetting to
+ * just the provider's first model.
+ */
+export declare function loadSavedModelsForProvider(provider: ProviderDef): string[];
+export declare function hasApiKey(): boolean;
+/**
+ * Resolve a model's max-output-token budget. Lookup order:
+ *   1. KNOWN_MAX_OUTPUT (covers direct providers like Anthropic/DeepSeek
+ *      whose IDs aren't in the OpenRouter snapshot)
+ *   2. OpenRouter snapshot (covers `vendor/model` style IDs)
+ *   3. undefined — caller falls back to its own default
+ *
+ * Returns undefined (not 0) when nothing is known, so callers can use
+ * `?? defaultValue` semantics.
+ */
+export declare function resolveMaxOutput(model: string): number | undefined;
+/**
+ * Resolve a model's context window size. Lookup order:
+ *   1. KNOWN_CONTEXT_WINDOWS (covers direct providers like DeepSeek)
+ *   2. OpenRouter snapshot (covers `vendor/model` style IDs)
+ *   3. undefined — unknown
+ */
+export declare function resolveContextWindow(model: string): number | undefined;
+/**
+ * Derive a pool key in `provider-model` form. Single source of truth for
+ * model alias generation — replaces the old modelKey() function which
+ * folded same-family models to one key (e.g. v4-flash and v4-pro both
+ * collapsed to "deepseek"), causing the pool to silently shadow entries.
+ *
+ *   ("deepseek", "deepseek-v4-pro")  → "deepseek-v4-pro"
+ *   ("openai",   "openai/gpt-5")      → "openai-gpt-5"
+ *   ("anthropic","claude-opus-4-7")   → "anthropic-claude-opus-4-7"
+ *
+ * If the model id already starts with `<provider>-` (e.g. "deepseek-v4-pro"
+ * under provider "deepseek"), the prefix isn't duplicated.
+ *
+ * `used` is a set of already-taken keys; collisions are resolved with a
+ * `-2`, `-3`, ... suffix.
+ */
+export declare function deriveModelPoolKey(providerKind: string, modelId: string, used?: string[]): string;
+/**
+ * Build model pool entries from a provider's model list.
+ */
+export declare function buildModelPool(provider: ProviderDef, apiKey: string): Array<{
+    key: string;
+    label: string;
+    provider: string;
+    model: string;
+    baseUrl: string;
+    apiKey: string;
+    maxOutputTokens?: number;
+    maxContextTokens?: number;
+}>;
+export declare function modelDisplayName(model: string): string;
+export declare function saveSettings(result: OnboardingResult, providerDef?: ProviderDef, poolModels?: string[]): void;
+/**
+ * Append-only persistence for the new ProviderModelFlow-based onboarding.
+ *
+ * Writes the new shape:
+ *   - settings.activeKey      — primary source of truth for active model
+ *   - settings.models[]       — self-describing entries (key, provider,
+ *                                model, baseUrl, apiKey, maxOutput, maxContext)
+ *   - settings.providers[]    — credential source for the wizard
+ *   - settings.model.*        — legacy mirror of the active entry, kept in
+ *                                sync so legacy boot paths (cli/main.ts,
+ *                                repl.ts, run.ts) keep working without
+ *                                each having to learn about activeKey
+ *
+ * Append-only: never removes existing entries. To start over use /logout.
+ * Writes atomically via tmp+rename.
+ */
+export declare function appendOnboardingResult(opts: {
+    /** Alias key the engine should switch to after writing. Matches one of addedModels[].key. */
+    activeKey: string;
+    /** Active entry's fields, used to mirror into the legacy settings.model.* block. */
+    activeMirror: {
+        provider: string;
+        model: string;
+        apiKey: string;
+        baseUrl: string;
+    };
+    addedProvider?: {
+        key: string;
+        label?: string;
+        kind: string;
+        baseUrl: string;
+        apiKey?: string;
+        protocol?: string;
+        modelsPath?: string;
+    };
+    addedModels: Array<{
+        key: string;
+        label?: string;
+        providerKey?: string;
+        /** LLM client/protocol ("openai"/"anthropic"). New canonical name. */
+        protocol?: string;
+        /** Legacy mirror of `protocol`. Both are written so legacy readers keep working. */
+        provider?: string;
+        model: string;
+        baseUrl: string;
+        apiKey?: string;
+        maxContextTokens?: number;
+        maxOutputTokens?: number;
+    }>;
+}): void;
+export declare function saveArenaSettingsByKeys(keys: string[]): void;