@pruddiman/hem 0.0.1-beta-5671db0

package/dist/auth.d.ts

@@ -0,0 +1,372 @@
+/**
+ * Authentication detection, first-run prompt, free model fetch, and preferences I/O.
+ * Implements US3 (Smart Authentication with Zero-Friction Onboarding).
+ */
+import React from "react";
+import type { OpencodeClient } from "@opencode-ai/sdk";
+import type { AuthState, FreeModelInfo, ModelSelection, ProjectConfig, UserPreferences } from "./types.js";
+/** Directory where Hem stores user preferences. */
+export declare const CONFIG_DIR: string;
+/** Full path to the preferences file. */
+export declare const PREFERENCES_PATH: string;
+/**
+ * Load user preferences from `~/.config/hem/preferences.json`.
+ *
+ * - Returns `null` if the file does not exist.
+ * - Auto-creates the `~/.config/hem/` directory if missing.
+ * - Handles JSON parse errors gracefully by returning `null`.
+ *
+ * @param configDir — Override for the config directory (used in tests).
+ *
+ * Reference: FR-023, plan.md lines 197-205.
+ */
+export declare function loadPreferences(configDir?: string): Promise<UserPreferences | null>;
+/**
+ * Save user preferences to `~/.config/hem/preferences.json`.
+ *
+ * Writes formatted JSON (2-space indent) for human readability.
+ * Auto-creates the `~/.config/hem/` directory if missing.
+ *
+ * @param prefs — The preferences object to persist.
+ * @param configDir — Override for the config directory (used in tests).
+ *
+ * Reference: FR-023, plan.md lines 197-205.
+ */
+export declare function savePreferences(prefs: UserPreferences, configDir?: string): Promise<void>;
+/** Default directory for project-local Hem configuration. */
+export declare const PROJECT_CONFIG_DIR: string;
+/** Full path to the project config file. */
+export declare const PROJECT_CONFIG_PATH: string;
+/**
+ * Load project-local configuration from `{cwd}/.hem/config.json`.
+ *
+ * - Returns `null` if the file does not exist.
+ * - Auto-creates the `.hem/` directory if missing.
+ * - Handles JSON parse errors gracefully by returning `null`.
+ *
+ * @param configDir — Override for the config directory (used in tests).
+ */
+export declare function loadProjectConfig(configDir?: string): Promise<ProjectConfig | null>;
+/**
+ * Save project-local configuration to `{cwd}/.hem/config.json`.
+ *
+ * Writes formatted JSON (2-space indent) for human readability.
+ * Auto-creates the `.hem/` directory if missing.
+ *
+ * @param config — The project config object to persist.
+ * @param configDir — Override for the config directory (used in tests).
+ */
+export declare function saveProjectConfig(config: ProjectConfig, configDir?: string): Promise<void>;
+/** URL for the Opencode model catalog. */
+export declare const ZEN_CATALOG_URL = "https://opencode.ai/zen/v1/models";
+/** Error message when the Zen catalog is unreachable. */
+export declare const ZEN_FETCH_ERROR: string;
+/**
+ * Custom error class thrown when the Opencode model catalog cannot be
+ * reached (network error, timeout, non-200 status, invalid JSON).
+ *
+ * Used to distinguish catalog connectivity failures from other errors so
+ * callers (e.g., `handleGenerate`) can present a clear, actionable message.
+ *
+ * Reference: spec.md line 122, contracts/cli-interface.md lines 212-214.
+ */
+export declare class ZenCatalogError extends Error {
+    constructor(cause?: unknown);
+}
+/**
+ * Classify a model's data retention policy from its privacy metadata.
+ *
+ * - If a "zero-retention" field exists (truthy) → `"zero-retention"`
+ * - If "training" is mentioned in any privacy-related string → `"may-train"`
+ * - Otherwise → `"unknown"`
+ *
+ * @internal
+ */
+export declare function classifyRetention(model: Record<string, any>): {
+    retention: FreeModelInfo["dataRetention"];
+    note: string;
+};
+/**
+ * Fetch free models from the Opencode model catalog.
+ *
+ * 1. Fetches from `https://opencode.ai/zen/v1/models` using the global `fetch` API.
+ * 2. Filters models where `pricing.input === 0 && pricing.output === 0`.
+ * 3. Classifies each model's data retention from privacy metadata.
+ * 4. Maps to `FreeModelInfo[]` with `providerID` always `"opencode"`.
+ * 5. Returns sorted with zero-retention models first.
+ *
+ * @param fetchFn — Override for the fetch function (used in tests).
+ *
+ * Reference: FR-024, FR-025, plan.md lines 216-233.
+ */
+export declare function fetchFreeModels(fetchFn?: typeof globalThis.fetch): Promise<FreeModelInfo[]>;
+/**
+ * Warning message template when a stored model is no longer available.
+ *
+ * Placeholders: `{providerID}` and `{modelID}` are replaced at runtime.
+ *
+ * Reference: spec.md line 123, contracts/cli-interface.md lines 208-209.
+ */
+export declare const INVALID_MODEL_WARNING: string;
+/**
+ * Validate that a stored model selection still corresponds to an available
+ * provider/model combination.
+ *
+ * Calls `client.config.providers()` and checks whether:
+ *   1. A provider with the stored `providerID` exists.
+ *   2. If that provider exposes a `models` map, the stored `modelID` is
+ *      present in it — unless the modelID is `"default"`, which is always
+ *      valid (it defers to the provider's default model).
+ *
+ * @param client — OpenCode SDK client instance.
+ * @param prefs  — User preferences containing the stored model selection.
+ * @returns `true` if the stored model is valid, `false` otherwise.
+ *
+ * Reference: spec.md line 123, contracts/cli-interface.md lines 208-209.
+ */
+export declare function validateStoredModel(client: OpencodeClient, prefs: UserPreferences): Promise<boolean>;
+/**
+ * List available models for a provider by querying the OpenCode provider metadata.
+ * Returns [] if the provider has no models map or the API call fails.
+ */
+export declare function listProviderModels(client: OpencodeClient, providerID: string): Promise<{
+    id: string;
+    name: string;
+    providerID?: string;
+}[]>;
+/**
+ * Error message template when authentication has expired.
+ *
+ * Placeholder: `{providerName}` is replaced at runtime with the provider
+ * identifier (e.g., "anthropic").
+ *
+ * Reference: spec.md line 124, contracts/cli-interface.md lines 205-206.
+ */
+export declare const AUTH_EXPIRED_ERROR: string;
+/**
+ * Custom error class thrown when an auth expiry is detected during
+ * the generation pipeline. Carries the provider name for the error
+ * message so callers can format the `AUTH_EXPIRED_ERROR` template.
+ */
+export declare class AuthExpiredError extends Error {
+    /** The provider whose credentials have expired. */
+    readonly providerName: string;
+    constructor(providerName: string, cause?: unknown);
+}
+/**
+ * Determine whether an error indicates expired or invalid authentication.
+ *
+ * Checks for HTTP 401 (Unauthorized) and 403 (Forbidden) status codes
+ * in common error shapes returned by LLM provider APIs:
+ *   - `error.status` — fetch-style Response errors
+ *   - `error.statusCode` — Node.js HTTP errors
+ *   - `error.code` — string codes like `"unauthorized"` / `"forbidden"`
+ *   - `error.message` — substring match for "401", "403", "unauthorized",
+ *     "forbidden", "expired", "invalid.*key", "authentication"
+ *
+ * @param error — The error to inspect (any type).
+ * @returns `true` if the error looks like an auth expiry / invalid credentials.
+ *
+ * Reference: spec.md line 124, contracts/cli-interface.md lines 205-206.
+ */
+export declare function isAuthExpired(error: unknown): boolean;
+/**
+ * Error message template when an API key is invalid or rejected.
+ *
+ * Placeholder: `{providerID}` is replaced at runtime with the provider
+ * identifier (e.g., "anthropic").
+ *
+ * Reference: spec.md line 127, contracts/cli-interface.md.
+ */
+export declare const INVALID_API_KEY_ERROR: string;
+/**
+ * Custom error class thrown when an API key is rejected by the provider.
+ *
+ * Used to distinguish API-key-specific auth failures from generic
+ * auth expiry (e.g., OAuth token expired). Carries the `providerID`
+ * so callers (e.g., `handleGenerate`) can format a clear, actionable
+ * error message.
+ *
+ * Reference: spec.md line 127.
+ */
+export declare class InvalidApiKeyError extends Error {
+    /** The provider that rejected the API key. */
+    readonly providerID: string;
+    constructor(providerID: string, cause?: unknown);
+}
+/**
+ * Inject an API key for a provider into the OpenCode SDK, bypassing OAuth
+ * and all interactive prompts.
+ *
+ * The `model` string must be in `provider/model-name` format (e.g.,
+ * `"anthropic/claude-sonnet-4"`). The provider ID is extracted as
+ * everything before the first `/`.
+ *
+ * @param client — OpenCode SDK client instance.
+ * @param model  — Model identifier in `provider/model` format.
+ * @param apiKey — API key to inject for the provider.
+ *
+ * Reference: FR-022a, plan.md lines 146-148, spec.md scenario 7.
+ */
+export declare function injectApiKey(client: OpencodeClient, model: string, apiKey: string): Promise<void>;
+/**
+ * Detect the current authentication state by querying the OpenCode SDK client.
+ *
+ * - Calls `client.config.providers()` to get the list of connected providers.
+ * - Maps them to `ConnectedProvider[]`.
+ * - Determines `hasCredentials` (true if any provider is connected).
+ * - Loads preferences via `loadPreferences()`.
+ * - Sets `isFirstRun` to true if no preferences exist AND no credentials detected.
+ * - Returns a complete `AuthState` object.
+ *
+ * @param client — OpenCode SDK client instance.
+ * @param configDir — Override for the config directory (used in tests).
+ *
+ * Reference: FR-020, plan.md lines 148-151.
+ */
+export declare function detectAuthState(client: OpencodeClient, configDir?: string): Promise<AuthState>;
+/**
+ * Resolve human-readable model and provider labels by querying the OpenCode
+ * provider metadata.
+ *
+ * When `model` has `modelID === "default"`, looks up the actual default model
+ * from the `default` map returned by `client.provider.list()`.
+ * When an explicit model is set, uses the metadata to find the human-readable name.
+ * Falls back to capitalized-ID logic if the lookup fails or the API call errors.
+ *
+ * @param client — OpenCode SDK client instance.
+ * @param model — The current resolved model selection (may be undefined).
+ * @returns An object with `modelLabel` and `providerLabel` strings.
+ */
+export declare function resolveActualModel(client: OpencodeClient, model?: ModelSelection): Promise<{
+    modelLabel: string;
+    providerLabel: string;
+}>;
+/**
+ * Render an Ink component and wait for a result via a callback.
+ *
+ * Wraps Ink's `render()` in a Promise that resolves when the component
+ * invokes the callback. The Ink instance is cleaned up automatically.
+ *
+ * @param createComponent — A function that receives a `resolve` callback
+ *   and returns a React element to render.
+ * @returns The value passed to the callback by the component.
+ *
+ * @internal
+ */
+export declare function renderAndWait<T>(createComponent: (resolve: (value: T) => void) => React.ReactElement): Promise<T>;
+/**
+ * Handle the "api-key" sub-flow of the first-run prompt.
+ *
+ * Renders the `ApiKeyInput` component to collect a provider ID and API key,
+ * then injects the key into the OpenCode SDK via `client.auth.set()`.
+ *
+ * @param client — OpenCode SDK client instance.
+ * @returns A `ModelSelection` with the chosen provider and a placeholder model ID.
+ *
+ * @internal
+ */
+export declare function handleApiKeyFlow(client: OpencodeClient): Promise<ModelSelection>;
+/**
+ * Handle the OAuth sub-flow of the first-run prompt.
+ *
+ * 1. Calls `client.config.providers()` to get a list of available OAuth providers.
+ * 2. Renders a provider selection prompt using Ink (list provider names,
+ *    let user pick one) via the `OAuthProviderSelect` component.
+ * 3. Initiates OAuth by calling `client.provider.auth({ path: { id } })`
+ *    (the SDK's OAuth authorize endpoint for the selected provider).
+ * 4. Waits for the callback/completion.
+ * 5. Returns a `ModelSelection` with the provider's default model.
+ *
+ * @param client — OpenCode SDK client instance.
+ * @returns A `ModelSelection` with the provider's default model.
+ *
+ * Reference: FR-018, plan.md lines 176-178.
+ */
+export declare function handleOAuthFlow(client: OpencodeClient): Promise<ModelSelection>;
+/**
+ * Handle the "free models" sub-flow of the first-run prompt.
+ *
+ * Fetches free models from the Opencode catalog via `fetchFreeModels()`,
+ * renders the `FreeModelPicker` with the results, and returns the user's
+ * selection as a `ModelSelection`.
+ *
+ * @param client — OpenCode SDK client instance (unused; models are fetched
+ *   from the public Zen catalog).
+ * @param models — Optional list of free models (used for testing to skip
+ *   the network fetch).
+ * @returns A `ModelSelection` with the chosen free model.
+ *
+ * Reference: FR-024, FR-025, plan.md lines 180-195.
+ */
+export declare function handleFreeModelSelection(_client: OpencodeClient, models?: FreeModelInfo[]): Promise<ModelSelection>;
+/**
+ * Orchestrate the first-run authentication flow.
+ *
+ * Renders the `AuthPrompt` component, waits for the user's choice, and
+ * dispatches to the appropriate sub-flow:
+ *   - "oauth"   → `handleOAuthFlow(client)`
+ *   - "api-key" → renders `ApiKeyInput` and calls `client.auth.set()`
+ *   - "free"    → `handleFreeModelSelection(client)`
+ *   - "exit"    → returns null
+ *
+ * After successful authentication, saves the chosen model to preferences
+ * via `savePreferences()`.
+ *
+ * @param client — OpenCode SDK client instance.
+ * @param configDir — Override for the config directory (used in tests).
+ * @returns The chosen `ModelSelection`, or `null` if the user chose to exit.
+ *
+ * Reference: FR-018, FR-020, plan.md lines 140-196.
+ */
+export declare function handleFirstRun(client: OpencodeClient, configDir?: string): Promise<ModelSelection | null>;
+/**
+ * Handle `hem auth login` — interactive auth, standalone (no generation).
+ *
+ * Runs the same interactive flow as `handleFirstRun` but standalone:
+ * the user picks a method (OAuth, API key, free, or exit), authenticates,
+ * and preferences are saved. No documentation generation follows.
+ *
+ * @param client — OpenCode SDK client instance.
+ * @param configDir — Override for the config directory (used in tests).
+ *
+ * Reference: FR-021, contracts/cli-interface.md lines 14-19.
+ */
+export declare function handleAuthLogin(client: OpencodeClient, configDir?: string): Promise<void>;
+/**
+ * Handle `hem auth list` — show connected providers with status.
+ *
+ * Calls `client.config.providers()`, formats and prints connected providers
+ * with status (checkmark + name + auth method) per `contracts/cli-interface.md`
+ * lines 132-143, also shows the default model from preferences.
+ *
+ * Output format:
+ * ```
+ *   Connected providers:
+ *     ✓ anthropic    Claude Pro/Max (OAuth)
+ *     ✓ opencode     Zen API Key
+ *
+ *   Default model: anthropic/claude-sonnet-4
+ * ```
+ *
+ * @param client — OpenCode SDK client instance.
+ * @param configDir — Override for the config directory (used in tests).
+ * @param writeFn — Override for the output function (used in tests).
+ *
+ * Reference: FR-021, contracts/cli-interface.md lines 132-143.
+ */
+export declare function handleAuthList(client: OpencodeClient, configDir?: string, writeFn?: (msg: string) => void): Promise<void>;
+/**
+ * Handle `hem auth logout` — remove credentials.
+ *
+ * If `target` is provided, removes credentials for that specific provider.
+ * If no `target`, removes all credentials by iterating over connected providers.
+ * Prints a confirmation message.
+ *
+ * @param client — OpenCode SDK client instance.
+ * @param target — Optional provider ID to remove. If omitted, removes all.
+ * @param writeFn — Override for the output function (used in tests).
+ *
+ * Reference: FR-021, contracts/cli-interface.md lines 14-19, 141-143.
+ */
+export declare function handleAuthLogout(client: OpencodeClient, target?: string, writeFn?: (msg: string) => void): Promise<void>;