@pruddiman/hem 0.0.1-beta-5671db0

package/dist/auth.js

@@ -0,0 +1,1072 @@
+/**
+ * Authentication detection, first-run prompt, free model fetch, and preferences I/O.
+ * Implements US3 (Smart Authentication with Zero-Friction Onboarding).
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import React from "react";
+import { render } from "ink";
+import { AuthPrompt, ApiKeyInput, FreeModelPicker, OAuthProviderSelect, OAuthWaiting, } from "./progress.js";
+// ── Constants ──────────────────────────────────────────────────────────
+/** Directory where Hem stores user preferences. */
+export const CONFIG_DIR = join(homedir(), ".config", "hem");
+/** Full path to the preferences file. */
+export const PREFERENCES_PATH = join(CONFIG_DIR, "preferences.json");
+// ── Preferences I/O ────────────────────────────────────────────────────
+/**
+ * Resolve the preferences file path.
+ * Uses the provided `configDir` override (for testing) or the default `CONFIG_DIR`.
+ */
+function resolvePreferencesPath(configDir) {
+    const dir = configDir ?? CONFIG_DIR;
+    return { dir, filePath: join(dir, "preferences.json") };
+}
+/**
+ * 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 async function loadPreferences(configDir) {
+    const { dir, filePath } = resolvePreferencesPath(configDir);
+    // Ensure the config directory exists (idempotent).
+    await mkdir(dir, { recursive: true });
+    try {
+        const raw = await readFile(filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        return parsed;
+    }
+    catch {
+        // File doesn't exist or JSON is malformed — both are non-fatal.
+        return 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 async function savePreferences(prefs, configDir) {
+    const { dir, filePath } = resolvePreferencesPath(configDir);
+    // Ensure the config directory exists (idempotent).
+    await mkdir(dir, { recursive: true });
+    await writeFile(filePath, JSON.stringify(prefs, null, 2) + "\n", "utf-8");
+}
+// ── Project Config I/O ─────────────────────────────────────────────────
+/** Default directory for project-local Hem configuration. */
+export const PROJECT_CONFIG_DIR = join(process.cwd(), ".hem");
+/** Full path to the project config file. */
+export const PROJECT_CONFIG_PATH = join(PROJECT_CONFIG_DIR, "config.json");
+/**
+ * Resolve the project config file path.
+ * Uses the provided `configDir` override (for testing) or the default `PROJECT_CONFIG_DIR`.
+ */
+function resolveProjectConfigPath(configDir) {
+    const dir = configDir ?? PROJECT_CONFIG_DIR;
+    return { dir, filePath: join(dir, "config.json") };
+}
+/**
+ * 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 async function loadProjectConfig(configDir) {
+    const { dir, filePath } = resolveProjectConfigPath(configDir);
+    // Ensure the config directory exists (idempotent).
+    await mkdir(dir, { recursive: true });
+    try {
+        const raw = await readFile(filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        return parsed;
+    }
+    catch {
+        // File doesn't exist or JSON is malformed — both are non-fatal.
+        return 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 async function saveProjectConfig(config, configDir) {
+    const { dir, filePath } = resolveProjectConfigPath(configDir);
+    // Ensure the config directory exists (idempotent).
+    await mkdir(dir, { recursive: true });
+    await writeFile(filePath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+// ── Free Model Fetching ────────────────────────────────────────────────
+/** URL for the Opencode model catalog. */
+export const ZEN_CATALOG_URL = "https://opencode.ai/zen/v1/models";
+/** Path to the on-disk model catalog cache (TTL: 24 hours). */
+const CATALOG_CACHE_PATH = join(CONFIG_DIR, "model-catalog-cache.json");
+/** How long a cached model catalog is considered fresh (ms). */
+const CATALOG_CACHE_TTL_MS = 24 * 60 * 60 * 1_000;
+/** Error message when the Zen catalog is unreachable. */
+export const ZEN_FETCH_ERROR = "Could not reach Opencode model catalog.\n" +
+    "  Check your internet connection, or log in with an existing provider:\n" +
+    "  npx @pruddiman/hem auth login\n";
+/**
+ * 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 class ZenCatalogError extends Error {
+    constructor(cause) {
+        super(ZEN_FETCH_ERROR);
+        this.name = "ZenCatalogError";
+        if (cause !== undefined) {
+            this.cause = cause;
+        }
+    }
+}
+/**
+ * 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 function classifyRetention(model) {
+    const privacy = model.privacy ?? model.data_policy ?? {};
+    // Check for a zero-retention indicator.
+    if (privacy["zero-retention"] ||
+        privacy["zero_retention"] ||
+        privacy.zeroRetention) {
+        return {
+            retention: "zero-retention",
+            note: typeof privacy.note === "string"
+                ? privacy.note
+                : "Zero data retention policy.",
+        };
+    }
+    // Check for training mentions in any privacy/policy string values.
+    const privacyStr = JSON.stringify(privacy).toLowerCase();
+    if (privacyStr.includes("training") || privacyStr.includes("train")) {
+        return {
+            retention: "may-train",
+            note: typeof privacy.note === "string"
+                ? privacy.note
+                : "Data may be used for training.",
+        };
+    }
+    return {
+        retention: "unknown",
+        note: typeof privacy.note === "string"
+            ? privacy.note
+            : "Data retention policy unknown.",
+    };
+}
+/**
+ * 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 async function fetchFreeModels(fetchFn = globalThis.fetch) {
+    // Only use the on-disk cache when the real global fetch is in use.
+    // Tests pass a custom fetchFn and must always hit the network mock.
+    const useCache = fetchFn === globalThis.fetch;
+    if (useCache) {
+        try {
+            const raw = await readFile(CATALOG_CACHE_PATH, "utf-8");
+            const cached = JSON.parse(raw);
+            if (typeof cached.ts === "number" &&
+                Array.isArray(cached.models) &&
+                Date.now() - cached.ts < CATALOG_CACHE_TTL_MS) {
+                return cached.models;
+            }
+        }
+        catch {
+            // Cache miss or parse error — fall through to network fetch
+        }
+    }
+    let response;
+    try {
+        response = await fetchFn(ZEN_CATALOG_URL);
+    }
+    catch (err) {
+        throw new ZenCatalogError(err);
+    }
+    if (!response.ok) {
+        throw new ZenCatalogError();
+    }
+    let data;
+    try {
+        data = await response.json();
+    }
+    catch (err) {
+        throw new ZenCatalogError(err);
+    }
+    // The API may return models at the top level as an array, or nested under a key.
+    const models = Array.isArray(data)
+        ? data
+        : Array.isArray(data.models)
+            ? data.models
+            : Array.isArray(data.data)
+                ? data.data
+                : [];
+    // Filter to free models (pricing.input === 0 && pricing.output === 0).
+    const freeModels = models.filter((m) => {
+        const pricing = m.pricing ?? {};
+        return pricing.input === 0 && pricing.output === 0;
+    });
+    // Map to FreeModelInfo[].
+    const result = freeModels.map((m) => {
+        const { retention, note } = classifyRetention(m);
+        return {
+            id: (m.id ?? m.model_id ?? ""),
+            name: (m.name ?? m.display_name ?? m.id ?? ""),
+            providerID: "opencode",
+            dataRetention: retention,
+            retentionNote: note,
+        };
+    });
+    // Sort: zero-retention first, then may-train, then unknown.
+    const retentionOrder = {
+        "zero-retention": 0,
+        "may-train": 1,
+        unknown: 2,
+    };
+    result.sort((a, b) => (retentionOrder[a.dataRetention] ?? 2) -
+        (retentionOrder[b.dataRetention] ?? 2));
+    // Write cache (fire-and-forget; errors are silent)
+    if (useCache) {
+        const cache = { ts: Date.now(), models: result };
+        mkdir(CONFIG_DIR, { recursive: true })
+            .then(() => writeFile(CATALOG_CACHE_PATH, JSON.stringify(cache, null, 2), "utf-8"))
+            .catch(() => { });
+    }
+    return result;
+}
+// ── Stored Model Validation ────────────────────────────────────────────
+/**
+ * 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 const INVALID_MODEL_WARNING = 'Model "{providerID}/{modelID}" is no longer available.\n' +
+    "  Run `npx @pruddiman/hem` without --model to select a new model.\n";
+/**
+ * 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 async function validateStoredModel(client, prefs) {
+    // No model stored → nothing to validate.
+    if (!prefs.model) {
+        return true;
+    }
+    const { providerID, modelID } = prefs.model;
+    const result = await client.config.providers();
+    const sdkProviders = result.data?.providers ?? [];
+    // Handle the opencode meta-provider with an encoded sub-provider in modelID.
+    // When the user selects "opencode" provider + a sub-provider model via `hem config`,
+    // the modelID is stored as "subProvider/modelID" (e.g. "github-copilot/opus-4.6").
+    // "opencode" is not a real entry in the SDK provider list, so we validate by
+    // splitting the modelID and checking the sub-provider instead.
+    if (providerID === "opencode" && modelID !== "default" && modelID.includes("/")) {
+        const slash = modelID.indexOf("/");
+        const subProviderID = modelID.slice(0, slash);
+        const subModelID = modelID.slice(slash + 1);
+        const subProvider = sdkProviders.find((p) => p.id === subProviderID);
+        if (!subProvider)
+            return false;
+        if (subProvider.models &&
+            typeof subProvider.models === "object" &&
+            Object.keys(subProvider.models).length > 0) {
+            return subModelID in subProvider.models;
+        }
+        return true;
+    }
+    // Check if the provider exists.
+    const provider = sdkProviders.find((p) => p.id === providerID);
+    if (!provider) {
+        return false;
+    }
+    // If the modelID is "default", it's always valid (defers to provider default).
+    if (modelID === "default") {
+        return true;
+    }
+    // If the provider has a models map, check if the model is in it.
+    // If there's no models map (or it's empty), we assume the provider
+    // supports any model and validation passes.
+    if (provider.models &&
+        typeof provider.models === "object" &&
+        Object.keys(provider.models).length > 0) {
+        return modelID in provider.models;
+    }
+    // No models map → assume valid (can't verify further).
+    return true;
+}
+// ── Provider Model Listing ─────────────────────────────────────────────
+/**
+ * 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 async function listProviderModels(client, providerID) {
+    try {
+        const result = await client.config.providers();
+        // Tolerate either {data: {providers}} (typed SDK shape) or a bare
+        // {providers} object — older SDK versions and some test mocks return the
+        // latter, and the cost of supporting both is one small cast.
+        const data = (result.data ?? result);
+        const allProviders = data.providers ?? [];
+        // For the "opencode" meta-provider, flatten models from all sub-providers
+        // (e.g. anthropic, openai) so the user can pick any available model.
+        if (providerID === "opencode") {
+            return allProviders
+                .flatMap((p) => {
+                if (!p.models || typeof p.models !== "object")
+                    return [];
+                return Object.entries(p.models).map(([modelId, meta]) => ({
+                    id: modelId,
+                    name: `${p.name ?? p.id} \u2014 ${meta?.name ?? modelId}`,
+                    providerID: p.id,
+                }));
+            })
+                .sort((a, b) => a.name.localeCompare(b.name));
+        }
+        const provider = allProviders.find((p) => p.id === providerID);
+        if (!provider?.models || typeof provider.models !== "object")
+            return [];
+        return Object.entries(provider.models)
+            .map(([id, meta]) => ({ id, name: meta?.name ?? id }))
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+    catch {
+        return [];
+    }
+}
+// ── Auth Expiry Detection ──────────────────────────────────────────────
+/**
+ * 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 const AUTH_EXPIRED_ERROR = 'Authentication expired for {providerName}.\n' +
+    "  Run `npx @pruddiman/hem auth login` to re-authenticate.\n";
+/**
+ * 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 class AuthExpiredError extends Error {
+    /** The provider whose credentials have expired. */
+    providerName;
+    constructor(providerName, cause) {
+        super(AUTH_EXPIRED_ERROR.replace("{providerName}", providerName));
+        this.name = "AuthExpiredError";
+        this.providerName = providerName;
+        if (cause !== undefined) {
+            this.cause = cause;
+        }
+    }
+}
+/**
+ * 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 function isAuthExpired(error) {
+    if (error === null || error === undefined) {
+        return false;
+    }
+    // Handle non-object primitive errors (strings, numbers, etc.)
+    if (typeof error !== "object") {
+        const str = String(error).toLowerCase();
+        return (str.includes("401") ||
+            str.includes("403") ||
+            str.includes("unauthorized") ||
+            str.includes("forbidden") ||
+            str.includes("authentication") ||
+            str.includes("expired"));
+    }
+    const err = error;
+    // Check numeric status / statusCode fields (HTTP response codes).
+    if (err.status === 401 || err.status === 403) {
+        return true;
+    }
+    if (err.statusCode === 401 || err.statusCode === 403) {
+        return true;
+    }
+    // Check string code fields (SDK / provider error codes).
+    if (typeof err.code === "string") {
+        const code = err.code.toLowerCase();
+        if (code === "unauthorized" ||
+            code === "forbidden" ||
+            code === "authentication_error" ||
+            code === "invalid_api_key" ||
+            code === "expired_token") {
+            return true;
+        }
+    }
+    // Check the error message for common auth failure keywords.
+    if (typeof err.message === "string") {
+        const msg = err.message.toLowerCase();
+        if (msg.includes("401") ||
+            msg.includes("403") ||
+            msg.includes("unauthorized") ||
+            msg.includes("forbidden") ||
+            msg.includes("authentication") ||
+            msg.includes("expired") ||
+            /invalid\s*(api[_\s-]?)?key/i.test(err.message)) {
+            return true;
+        }
+    }
+    return false;
+}
+// ── Invalid API Key ────────────────────────────────────────────────────
+/**
+ * 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 const INVALID_API_KEY_ERROR = 'Authentication failed for provider "{providerID}".\n' +
+    "  Please verify your API key is correct and has not expired.\n";
+/**
+ * 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 class InvalidApiKeyError extends Error {
+    /** The provider that rejected the API key. */
+    providerID;
+    constructor(providerID, cause) {
+        super(INVALID_API_KEY_ERROR.replace("{providerID}", providerID));
+        this.name = "InvalidApiKeyError";
+        this.providerID = providerID;
+        if (cause !== undefined) {
+            this.cause = cause;
+        }
+    }
+}
+// ── API Key Injection ──────────────────────────────────────────────────
+/**
+ * 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 async function injectApiKey(client, model, apiKey) {
+    // Extract the provider ID (everything before the first "/").
+    const slashIndex = model.indexOf("/");
+    if (slashIndex <= 0) {
+        throw new Error(`Invalid model format: "${model}". Expected "provider/model-name" (e.g., "anthropic/claude-sonnet-4").`);
+    }
+    const providerID = model.slice(0, slashIndex);
+    await client.auth.set({
+        path: { id: providerID },
+        body: { type: "api", key: apiKey },
+    });
+}
+// ── Auth Detection ─────────────────────────────────────────────────────
+/**
+ * Map an OpenCode SDK provider `source` field to a `ConnectedProvider.authMethod`.
+ *
+ * SDK sources: "env" | "config" | "custom" | "api"
+ *   - "env"    → user exported an env var (e.g., ANTHROPIC_API_KEY)
+ *   - "api"    → credentials injected via `client.auth.set()` (API key or OAuth)
+ *   - "config" → set in opencode.json config file
+ *   - "custom" → custom provider configuration
+ *
+ * We conservatively map "api" → "api-key" and everything else → "env-var",
+ * except "config" which also maps to "api-key" (explicit user configuration).
+ */
+function mapSourceToAuthMethod(source) {
+    switch (source) {
+        case "api":
+        case "config":
+            return "api-key";
+        case "env":
+            return "env-var";
+        case "custom":
+            return "oauth";
+        default:
+            return "env-var";
+    }
+}
+/**
+ * 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 async function detectAuthState(client, configDir) {
+    // Query the SDK for connected providers.
+    const result = await client.config.providers();
+    const sdkProviders = result.data?.providers ?? [];
+    // Filter to providers that have credentials (a key or env vars set).
+    // A provider with a `key` field populated has active credentials.
+    // We also consider providers whose `source` indicates explicit auth.
+    const connectedProviders = sdkProviders
+        .filter((p) => (p.key !== undefined && p.key !== null && p.key !== "") ||
+        p.source === "custom" || p.source === "api" || p.source === "config")
+        .map((p) => ({
+        id: p.id,
+        name: p.name,
+        authMethod: mapSourceToAuthMethod(p.source ?? "env"),
+    }));
+    // Detect GitHub Copilot credentials from environment variables.
+    // This complements (does not replace) the SDK-based detection above.
+    const copilotToken = process.env.COPILOT_GITHUB_TOKEN ||
+        process.env.GH_TOKEN ||
+        process.env.GITHUB_TOKEN;
+    if (copilotToken &&
+        !connectedProviders.some((p) => p.id === "github-copilot")) {
+        connectedProviders.push({
+            id: "github-copilot",
+            name: "GitHub Copilot",
+            authMethod: "env-var",
+        });
+    }
+    const hasCredentials = connectedProviders.length > 0;
+    // Load user preferences.
+    const preferences = await loadPreferences(configDir);
+    // Determine if this is a first run: no preferences AND no credentials.
+    const isFirstRun = preferences === null && !hasCredentials;
+    // Resolve the active model from preferences (if available).
+    const activeModel = preferences?.model ?? undefined;
+    return {
+        hasCredentials,
+        connectedProviders,
+        activeModel,
+        isFirstRun,
+    };
+}
+/**
+ * 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 async function resolveActualModel(client, model) {
+    // Fallback label builder (matches existing logic in index.ts).
+    const fallback = () => {
+        if (!model) {
+            return { modelLabel: "default", providerLabel: "Default" };
+        }
+        const providerLabel = model.providerID.charAt(0).toUpperCase() + model.providerID.slice(1);
+        return {
+            modelLabel: `${model.providerID}/${model.modelID}`,
+            providerLabel,
+        };
+    };
+    if (!model) {
+        return fallback();
+    }
+    try {
+        const result = await client.provider.list();
+        // Tolerate either {data: {...}} (typed SDK shape) or a bare object —
+        // older SDK versions and some test mocks return the latter.
+        const data = (result.data ?? result);
+        const allProviders = data.all ?? [];
+        const defaultMap = data.default ?? {};
+        let providerID = model.providerID;
+        let modelID = model.modelID;
+        // When the model is "default", resolve via the default map.
+        if (modelID === "default") {
+            // Find the first connected provider's default, or use the providerID from the model.
+            const connected = data.connected ?? [];
+            if (providerID === "opencode" && connected.length > 0) {
+                // Use the first connected provider's default model.
+                for (const connID of connected) {
+                    if (defaultMap[connID]) {
+                        providerID = connID;
+                        modelID = defaultMap[connID];
+                        break;
+                    }
+                }
+            }
+            else {
+                const fallback = defaultMap[providerID];
+                if (fallback) {
+                    modelID = fallback;
+                }
+            }
+        }
+        // Look up the provider metadata for human-readable names.
+        const providerMeta = allProviders.find((p) => p.id === providerID);
+        const providerLabel = providerMeta?.name
+            ?? (providerID.charAt(0).toUpperCase() + providerID.slice(1));
+        // Look up the model metadata for a human-readable name.
+        const modelMeta = providerMeta?.models?.[modelID];
+        const modelLabel = modelMeta?.name
+            ?? `${providerID}/${modelID}`;
+        return { modelLabel, providerLabel };
+    }
+    catch {
+        return fallback();
+    }
+}
+// ── First-Run Flow ─────────────────────────────────────────────────────
+/**
+ * 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 function renderAndWait(createComponent) {
+    return new Promise((resolve) => {
+        let instance;
+        const handleResolve = (value) => {
+            // Unmount Ink once we have a result.
+            instance?.unmount();
+            resolve(value);
+        };
+        instance = render(createComponent(handleResolve));
+    });
+}
+/**
+ * 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 async function handleApiKeyFlow(client) {
+    // Get the list of available providers for the selection menu.
+    const result = await client.config.providers();
+    const sdkProviders = result.data?.providers ?? [];
+    const providerIds = sdkProviders.map((p) => p.id);
+    // If no providers are available, fall back to a default set.
+    const availableProviders = providerIds.length > 0
+        ? providerIds
+        : ["anthropic", "openai", "google"];
+    // Render the ApiKeyInput component and wait for user submission.
+    const { providerId, key } = await renderAndWait((resolve) => React.createElement(ApiKeyInput, {
+        providers: availableProviders,
+        onSubmit: (providerId, key) => resolve({ providerId, key }),
+    }));
+    // Inject the API key into the SDK.
+    await client.auth.set({
+        path: { id: providerId },
+        body: { type: "api", key },
+    });
+    return {
+        providerID: providerId,
+        modelID: "default",
+    };
+}
+/**
+ * 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 async function handleOAuthFlow(client) {
+    // Step 1: Get available providers from the SDK.
+    const result = await client.config.providers();
+    const sdkProviders = result.data?.providers ?? [];
+    if (sdkProviders.length === 0) {
+        throw new Error("No OAuth providers available. Use an API key or free models instead.");
+    }
+    // Map SDK providers to OAuthProviderOption[].
+    const providerOptions = sdkProviders.map((p) => ({
+        id: p.id,
+        name: (p.name ?? p.id),
+    }));
+    // Step 2: Render provider selection prompt and wait for user's choice.
+    const selectedProvider = await renderAndWait((resolve) => React.createElement(OAuthProviderSelect, {
+        providers: providerOptions,
+        onSelect: resolve,
+    }));
+    // Step 3: Initiate OAuth for the selected provider.
+    // The SDK returns an authorization URL and handles the callback.
+    let oauthResult;
+    try {
+        oauthResult = await client.provider.oauth.authorize({
+            path: { id: selectedProvider.id },
+        });
+    }
+    catch (err) {
+        throw new Error(`OAuth authentication failed for ${selectedProvider.name}: ${err?.message ?? "Unknown error"}`);
+    }
+    // Step 4: If the SDK returns a URL, show the waiting UI.
+    // The SDK wraps responses in { data, request, response }.
+    const oauthData = oauthResult?.data;
+    if (oauthData?.url) {
+        // Render a waiting indicator while OAuth completes in the browser.
+        // The SDK call itself waits for completion, so this is purely informational.
+        const waitInstance = render(React.createElement(OAuthWaiting, {
+            providerName: selectedProvider.name,
+            url: oauthData.url,
+        }));
+        // If the SDK provides a wait/callback mechanism, wait for it.
+        if (typeof oauthData.wait === "function") {
+            try {
+                await oauthData.wait();
+            }
+            finally {
+                waitInstance.unmount();
+            }
+        }
+        else {
+            // The OAuth flow completed synchronously or the SDK handles it internally.
+            waitInstance.unmount();
+        }
+    }
+    // Step 5: Return a ModelSelection with the provider's default model.
+    return {
+        providerID: selectedProvider.id,
+        modelID: "default",
+    };
+}
+/**
+ * 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 async function handleFreeModelSelection(_client, models) {
+    // Use provided models (for testing) or fetch dynamically from the Zen catalog.
+    const availableModels = models ?? await fetchFreeModels();
+    const selectedModel = await renderAndWait((resolve) => React.createElement(FreeModelPicker, {
+        models: availableModels,
+        onSelect: resolve,
+    }));
+    return {
+        providerID: selectedModel.providerID,
+        modelID: selectedModel.id,
+    };
+}
+/**
+ * Run the interactive auth prompt and dispatch to the chosen sub-flow.
+ *
+ * Shared logic used by both `handleFirstRun()` and `handleAuthLogin()`.
+ * 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.
+ *
+ * @internal
+ */
+async function runAuthPrompt(client, configDir) {
+    // Step 1: Show the auth prompt and get the user's choice.
+    const choice = await renderAndWait((resolve) => React.createElement(AuthPrompt, { onSelect: resolve }));
+    // Step 2: Dispatch based on choice.
+    let modelSelection = null;
+    switch (choice) {
+        case "oauth":
+            modelSelection = await handleOAuthFlow(client);
+            break;
+        case "api-key":
+            modelSelection = await handleApiKeyFlow(client);
+            break;
+        case "free":
+            modelSelection = await handleFreeModelSelection(client);
+            break;
+        case "exit":
+            return null;
+    }
+    // Step 3: Save preferences with the chosen model.
+    if (modelSelection !== null) {
+        const prefs = {
+            model: modelSelection,
+            agreedToFreeModelTerms: choice === "free",
+            lastUsedAt: new Date().toISOString(),
+        };
+        await savePreferences(prefs, configDir);
+    }
+    // Step 4: Return the model selection.
+    return 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 async function handleFirstRun(client, configDir) {
+    return runAuthPrompt(client, configDir);
+}
+// ── Auth Subcommands ───────────────────────────────────────────────────
+/**
+ * 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 async function handleAuthLogin(client, configDir) {
+    const result = await runAuthPrompt(client, configDir);
+    if (result === null) {
+        // User chose "exit" — nothing to do.
+        return;
+    }
+    // Auth was successful. Preferences are already saved by runAuthPrompt.
+}
+/**
+ * Format an auth method for display.
+ *
+ * Maps the internal `ConnectedProvider.authMethod` value to a human-readable
+ * string matching the contract format:
+ *   - "oauth"   → "(OAuth)"
+ *   - "api-key" → "API Key"
+ *   - "env-var" → "(env var)"
+ *
+ * @internal
+ */
+function formatAuthMethod(authMethod) {
+    switch (authMethod) {
+        case "oauth":
+            return "(OAuth)";
+        case "api-key":
+            return "API Key";
+        case "env-var":
+            return "(env var)";
+    }
+}
+/**
+ * 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 async function handleAuthList(client, configDir, writeFn = (msg) => process.stdout.write(msg)) {
+    // Query the SDK for connected providers.
+    const result = await client.config.providers();
+    const sdkProviders = result.data?.providers ?? [];
+    // Filter to providers with credentials (API key or OAuth/custom source).
+    const connectedProviders = sdkProviders
+        .filter((p) => (p.key !== undefined && p.key !== null && p.key !== "") ||
+        p.source === "custom" || p.source === "api" || p.source === "config")
+        .map((p) => ({
+        id: p.id,
+        name: p.name,
+        authMethod: mapSourceToAuthMethod(p.source ?? "env"),
+    }));
+    // Load user preferences for the default model.
+    const preferences = await loadPreferences(configDir);
+    // Output the list.
+    writeFn("\n");
+    if (connectedProviders.length === 0) {
+        writeFn("  No providers connected.\n");
+        writeFn("  Run `npx @pruddiman/hem auth login` to set up authentication.\n");
+    }
+    else {
+        writeFn("  Connected providers:\n");
+        // Find the longest provider ID for alignment.
+        const maxIdLen = connectedProviders.reduce((max, p) => Math.max(max, p.id.length), 0);
+        for (const provider of connectedProviders) {
+            const padding = " ".repeat(Math.max(1, maxIdLen - provider.id.length + 4));
+            const method = formatAuthMethod(provider.authMethod);
+            writeFn(`    \u2713 ${provider.id}${padding}${provider.name} ${method}\n`);
+        }
+    }
+    writeFn("\n");
+    // Show the default model if set in preferences.
+    if (preferences?.model) {
+        writeFn(`  Default model: ${preferences.model.providerID}/${preferences.model.modelID}\n`);
+    }
+    else {
+        writeFn("  Default model: (none)\n");
+    }
+    writeFn("\n");
+}
+/**
+ * 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 async function handleAuthLogout(client, target, writeFn = (msg) => process.stdout.write(msg)) {
+    // The OpenCode SDK's typed `client.auth.remove` only handles MCP auth
+    // (URL `/mcp/{name}/auth`). There is no SDK method for removing
+    // provider credentials at `/auth/{id}` — only `set`. We call the
+    // server endpoint via the underlying HTTP client to keep the
+    // existing behavior; cast is necessary because the typed surface
+    // does not expose this. See SDK gen/sdk.gen.d.ts.
+    const removeProviderAuth = (id) => client.auth.remove({ path: { id } });
+    if (target) {
+        // Remove credentials for a specific provider.
+        await removeProviderAuth(target);
+        writeFn(`\n  \u2713 Removed credentials for ${target}.\n\n`);
+    }
+    else {
+        // Remove all credentials: query providers, then remove each one.
+        const result = await client.config.providers();
+        const sdkProviders = result.data?.providers ?? [];
+        const connectedProviders = sdkProviders.filter((p) => (p.key !== undefined && p.key !== null && p.key !== "") ||
+            p.source === "custom" || p.source === "api" || p.source === "config");
+        if (connectedProviders.length === 0) {
+            writeFn("\n  No credentials to remove.\n\n");
+            return;
+        }
+        for (const provider of connectedProviders) {
+            await removeProviderAuth(provider.id);
+        }
+        writeFn(`\n  \u2713 Removed all credentials (${connectedProviders.length} provider${connectedProviders.length === 1 ? "" : "s"}).\n\n`);
+    }
+}