mod8-cli 0.2.0

package/dist/storage/providers.js

@@ -0,0 +1,337 @@
+/**
+ * Provider configuration store.
+ *
+ * Replaces the old keys.json with a richer providers.json keyed by provider
+ * id, each entry carrying:
+ *   - apiKey:       the BYOK secret
+ *   - apiType:      'anthropic' | 'openai-compat' | 'gemini'
+ *   - name:         display label
+ *   - baseUrl?:     for openai-compat providers (Anthropic/Gemini use SDK defaults)
+ *   - defaultModel: model id used when a turn doesn't specify one
+ *   - color:        display color (hex)
+ *   - custom:       true if user-registered (not from KNOWN_PROVIDERS)
+ *
+ * Backwards compat: on first read, if providers.json is missing but the legacy
+ * keys.json exists (with anthropic/openai/google entries), import them using
+ * built-in templates from the registry.  keys.json is left untouched on disk
+ * so existing tooling keeps working.
+ */
+import { promises as fs } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { KNOWN_PROVIDERS, PROVIDER_SYNONYMS, HIGH_CONFIDENCE_BRAND_ALIASES, templateById, pickPaletteColor, } from '../providers/registry.js';
+const CONFIG_DIR = process.env.MOD8_CONFIG_DIR ?? join(homedir(), '.config', 'mod8');
+const PROVIDERS_FILE = join(CONFIG_DIR, 'providers.json');
+const LEGACY_KEYS_FILE = join(CONFIG_DIR, 'keys.json');
+async function readProvidersFile() {
+    try {
+        const data = await fs.readFile(PROVIDERS_FILE, 'utf8');
+        const parsed = JSON.parse(data);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return {};
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+        // No providers.json yet — try migrating from legacy keys.json.
+        return migrateFromLegacy();
+    }
+}
+async function migrateFromLegacy() {
+    let legacy;
+    try {
+        const data = await fs.readFile(LEGACY_KEYS_FILE, 'utf8');
+        const parsed = JSON.parse(data);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return {};
+        legacy = parsed;
+    }
+    catch {
+        return {};
+    }
+    const out = {};
+    for (const [id, key] of Object.entries(legacy)) {
+        if (typeof key !== 'string' || !key)
+            continue;
+        const tpl = templateById(id);
+        if (!tpl)
+            continue; // unknown legacy id — skip silently
+        out[id] = entryFromTemplate(tpl, key);
+    }
+    // Persist so subsequent reads hit providers.json directly.
+    if (Object.keys(out).length > 0)
+        await writeProvidersFile(out);
+    return out;
+}
+async function writeProvidersFile(providers) {
+    await fs.mkdir(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    const data = JSON.stringify(providers, null, 2) + '\n';
+    await fs.writeFile(PROVIDERS_FILE, data, { mode: 0o600 });
+    await fs.chmod(PROVIDERS_FILE, 0o600);
+}
+export function entryFromTemplate(tpl, apiKey) {
+    const entry = {
+        apiKey,
+        apiType: tpl.apiType,
+        name: tpl.name,
+        defaultModel: tpl.defaultModel,
+        color: tpl.color,
+    };
+    if (tpl.baseUrl)
+        entry.baseUrl = tpl.baseUrl;
+    return entry;
+}
+export async function listProviders() {
+    return readProvidersFile();
+}
+export async function getProviderEntry(id) {
+    const all = await readProvidersFile();
+    return all[id];
+}
+/**
+ * Resolve the API key for a provider id, honoring env-var overrides for the
+ * three legacy providers (back-compat).  Used by the legacy single-provider
+ * call paths so existing setups keep working.
+ */
+export async function getApiKey(id) {
+    if (id === 'anthropic' && process.env.ANTHROPIC_API_KEY)
+        return process.env.ANTHROPIC_API_KEY;
+    if (id === 'openai' && process.env.OPENAI_API_KEY)
+        return process.env.OPENAI_API_KEY;
+    if (id === 'google') {
+        const k = process.env.GOOGLE_API_KEY ?? process.env.GEMINI_API_KEY;
+        if (k)
+            return k;
+    }
+    const entry = await getProviderEntry(id);
+    return entry?.apiKey;
+}
+export async function setProvider(id, entry) {
+    const all = await readProvidersFile();
+    all[id] = entry;
+    await writeProvidersFile(all);
+}
+/**
+ * Save a key for a known-template provider, preserving any user
+ * customizations on an existing entry (display name, defaultModel, baseUrl,
+ * custom flag) and only falling back to the template defaults for fields
+ * the user hasn't overridden.
+ *
+ * Used by the inline paste-key flow.  The previous behavior — overwriting
+ * the entry wholesale with template defaults — was a regression: a user
+ * who had set defaultModel="gemini-2.5-flash" would have it silently
+ * reverted to the registry default ("gemini-2.0-flash") on the next
+ * inline paste, sending them into a "model no longer available" loop.
+ */
+export async function saveKeyPreservingEntry(apiKey, template) {
+    const existing = await getProviderEntry(template.id);
+    const entry = {
+        apiKey,
+        apiType: existing?.apiType ?? template.apiType,
+        name: existing?.name ?? template.name,
+        defaultModel: existing?.defaultModel ?? template.defaultModel,
+        color: existing?.color ?? template.color,
+    };
+    const baseUrl = existing?.baseUrl ?? template.baseUrl;
+    if (baseUrl)
+        entry.baseUrl = baseUrl;
+    if (existing?.custom)
+        entry.custom = true;
+    await setProvider(template.id, entry);
+}
+export async function setProviderKey(id, apiKey) {
+    const all = await readProvidersFile();
+    if (all[id]) {
+        all[id].apiKey = apiKey;
+    }
+    else {
+        const tpl = templateById(id);
+        if (!tpl)
+            throw new Error(`unknown provider "${id}" — use mod8 add-provider for custom ones`);
+        all[id] = entryFromTemplate(tpl, apiKey);
+    }
+    await writeProvidersFile(all);
+}
+export async function removeProvider(id) {
+    const all = await readProvidersFile();
+    if (!(id in all))
+        return false;
+    delete all[id];
+    await writeProvidersFile(all);
+    return true;
+}
+export async function configuredProviderIds() {
+    const all = await readProvidersFile();
+    return Object.keys(all);
+}
+/**
+ * Resolve a "configured" provider with environment-variable key overrides
+ * applied — i.e., the entry that should actually be used for a call.
+ */
+export async function resolveConfigured(id) {
+    const entry = await getProviderEntry(id);
+    const envKey = await envKeyFor(id);
+    if (entry && envKey)
+        return { ...entry, apiKey: envKey };
+    if (entry)
+        return entry;
+    // No stored entry, but env key + known template → synthesize an entry.
+    if (envKey) {
+        const tpl = templateById(id);
+        if (tpl)
+            return entryFromTemplate(tpl, envKey);
+    }
+    return undefined;
+}
+async function envKeyFor(id) {
+    if (id === 'anthropic')
+        return process.env.ANTHROPIC_API_KEY;
+    if (id === 'openai')
+        return process.env.OPENAI_API_KEY;
+    if (id === 'google')
+        return process.env.GOOGLE_API_KEY ?? process.env.GEMINI_API_KEY;
+    return undefined;
+}
+/** Used by add-provider to pick a fresh palette color for a custom provider. */
+export async function nextPaletteColor() {
+    const all = await readProvidersFile();
+    const used = Object.values(all).map((e) => e.color);
+    return pickPaletteColor(used);
+}
+/** Treat any id appearing in KNOWN_PROVIDERS or providers.json as valid. */
+export async function isKnownOrConfigured(id) {
+    if (KNOWN_PROVIDERS.some((p) => p.id === id))
+        return true;
+    const all = await readProvidersFile();
+    return id in all;
+}
+/**
+ * Strict variant of the provider-hint resolver — matches only on id (built-in
+ * or configured), configured display name, and the curated HIGH-CONFIDENCE
+ * brand aliases (claude, gpt, grok, gemini, chatgpt — unambiguous brand
+ * names).  Used for bare-name and first-word matching.
+ *
+ * NOT included: ambiguous synonyms like "haiku", "sonnet", "opus", "bard",
+ * "llama" — those are common English/literature words and would false-
+ * positive too often.  Users can still route to those via the verb-based
+ * path (`use haiku`, `talk to llama`) which goes through full resolution.
+ */
+export async function strictResolveProviderHint(hint) {
+    const lower = hint.toLowerCase().trim();
+    if (!lower)
+        return null;
+    const stored = await readProvidersFile();
+    // 1. Configured id
+    if (stored[lower])
+        return lower;
+    // 2. Built-in id
+    if (KNOWN_PROVIDERS.some((p) => p.id === lower))
+        return lower;
+    // 3. Configured display name (case-insensitive)
+    for (const [id, entry] of Object.entries(stored)) {
+        if (entry.name.toLowerCase() === lower)
+            return id;
+    }
+    // 4. High-confidence brand alias (claude/gpt/grok/gemini/chatgpt)
+    if (HIGH_CONFIDENCE_BRAND_ALIASES[lower]) {
+        return HIGH_CONFIDENCE_BRAND_ALIASES[lower];
+    }
+    return null;
+}
+/**
+ * Map a user-supplied hint (id, display name, or known nickname) to a real
+ * provider id.  Tries, in order:
+ *   1. Exact id match against the configured store.
+ *   2. Exact id match against the built-in registry.
+ *   3. Display-name match against the configured store (case-insensitive).
+ *   4. Built-in template name match (case-insensitive).
+ *   5. PROVIDER_SYNONYMS lookup ("gpt" → "openai", "claude" → "anthropic", …).
+ *
+ * Returns the canonical id or null if nothing matched.  Does NOT verify the
+ * provider is configured (the caller should resolveConfigured() afterwards).
+ */
+export async function resolveProviderHint(hint) {
+    const lower = hint.toLowerCase().trim();
+    if (!lower)
+        return null;
+    const stored = await readProvidersFile();
+    // 1. Exact id (configured)
+    if (stored[lower])
+        return lower;
+    // 2. Exact id (built-in template)
+    if (KNOWN_PROVIDERS.some((p) => p.id === lower))
+        return lower;
+    // 3. Display name (configured)
+    for (const [id, entry] of Object.entries(stored)) {
+        if (entry.name.toLowerCase() === lower)
+            return id;
+    }
+    // 4. Display name (built-in)
+    const tplByName = KNOWN_PROVIDERS.find((p) => p.name.toLowerCase() === lower);
+    if (tplByName)
+        return tplByName.id;
+    // 5. Synonym
+    if (PROVIDER_SYNONYMS[lower])
+        return PROVIDER_SYNONYMS[lower];
+    return null;
+}
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (!a)
+        return b.length;
+    if (!b)
+        return a.length;
+    const an = a.length;
+    const bn = b.length;
+    let prev = new Array(bn + 1);
+    let curr = new Array(bn + 1);
+    for (let j = 0; j <= bn; j++)
+        prev[j] = j;
+    for (let i = 1; i <= an; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= bn; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[bn];
+}
+export async function fuzzyResolveProviderHint(hint) {
+    const lower = hint.toLowerCase().trim();
+    if (!lower)
+        return [];
+    const stored = await readProvidersFile();
+    // Candidate haystack: { resolvedId, surfaceString }
+    const candidates = [];
+    for (const id of Object.keys(stored)) {
+        candidates.push({ id, surface: id });
+    }
+    for (const [id, entry] of Object.entries(stored)) {
+        candidates.push({ id, surface: entry.name.toLowerCase() });
+    }
+    for (const tpl of KNOWN_PROVIDERS) {
+        candidates.push({ id: tpl.id, surface: tpl.id });
+        candidates.push({ id: tpl.id, surface: tpl.name.toLowerCase() });
+    }
+    for (const [alias, id] of Object.entries(HIGH_CONFIDENCE_BRAND_ALIASES)) {
+        candidates.push({ id, surface: alias });
+    }
+    const bestPerId = new Map();
+    for (const { id, surface } of candidates) {
+        const distance = levenshtein(lower, surface);
+        if (distance === 0)
+            continue; // exact match — handled by the strict resolvers
+        if (distance > 2)
+            continue; // out of fuzzy range
+        const existing = bestPerId.get(id);
+        if (!existing || distance < existing.distance) {
+            bestPerId.set(id, { id, candidate: surface, distance });
+        }
+    }
+    return Array.from(bestPerId.values()).sort((a, b) => a.distance === b.distance ? a.id.localeCompare(b.id) : a.distance - b.distance);
+}
+export const PROVIDERS_FILE_PATH = PROVIDERS_FILE;

package/dist/storage/sessions.js

@@ -0,0 +1,150 @@
+import { promises as fs } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import Anthropic from '@anthropic-ai/sdk';
+import { getKey } from './keys.js';
+const CONFIG_DIR = process.env.MOD8_CONFIG_DIR ?? join(homedir(), '.config', 'mod8');
+const SESSIONS_DIR = join(CONFIG_DIR, 'sessions');
+export const SESSION_ID_RE = /^\d{4}-\d{2}-\d{2}-[a-z0-9]{4}$/;
+export function generateSessionId(now = new Date()) {
+    const yyyy = now.getFullYear();
+    const mm = String(now.getMonth() + 1).padStart(2, '0');
+    const dd = String(now.getDate()).padStart(2, '0');
+    const date = `${yyyy}-${mm}-${dd}`;
+    const suffix = Math.random().toString(36).slice(2, 6).padEnd(4, '0');
+    return `${date}-${suffix}`;
+}
+async function ensureDir() {
+    await fs.mkdir(SESSIONS_DIR, { recursive: true, mode: 0o700 });
+}
+function pathFor(id) {
+    return join(SESSIONS_DIR, `${id}.json`);
+}
+export async function createSession() {
+    const now = Date.now();
+    const session = {
+        version: 1,
+        id: generateSessionId(),
+        title: null,
+        createdAt: now,
+        lastActivity: now,
+        messages: [],
+    };
+    await saveSession(session);
+    return session;
+}
+export async function saveSession(session) {
+    await ensureDir();
+    const target = pathFor(session.id);
+    const tmp = `${target}.tmp`;
+    const data = JSON.stringify(session, null, 2) + '\n';
+    await fs.writeFile(tmp, data, { mode: 0o600 });
+    await fs.rename(tmp, target);
+    await fs.chmod(target, 0o600);
+}
+export async function loadSession(id) {
+    if (!SESSION_ID_RE.test(id))
+        return null;
+    try {
+        const data = await fs.readFile(pathFor(id), 'utf8');
+        const parsed = JSON.parse(data);
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        return parsed;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+export async function listSessions(limit = 20) {
+    await ensureDir();
+    let files;
+    try {
+        files = await fs.readdir(SESSIONS_DIR);
+    }
+    catch {
+        return [];
+    }
+    const summaries = [];
+    for (const file of files) {
+        if (!file.endsWith('.json'))
+            continue;
+        if (file.endsWith('.tmp'))
+            continue;
+        const id = file.slice(0, -5);
+        if (!SESSION_ID_RE.test(id))
+            continue;
+        try {
+            const session = await loadSession(id);
+            if (!session)
+                continue;
+            const turnCount = session.messages.filter((m) => m.role === 'assistant').length;
+            summaries.push({
+                id: session.id,
+                title: session.title,
+                lastActivity: session.lastActivity,
+                turnCount,
+            });
+        }
+        catch {
+            // skip corrupted
+        }
+    }
+    summaries.sort((a, b) => b.lastActivity - a.lastActivity);
+    return summaries.slice(0, limit);
+}
+export async function getMostRecentSession() {
+    const summaries = await listSessions(1);
+    if (summaries.length === 0)
+        return null;
+    return loadSession(summaries[0].id);
+}
+export async function clearSessionHistory(session) {
+    session.messages = [];
+    session.title = null;
+    session.lastActivity = Date.now();
+    await saveSession(session);
+}
+/**
+ * Generate a 4-5 word title summarizing the conversation, using Haiku for cost.
+ * Returns '' on any failure (no key, network error, etc.) — caller falls back.
+ */
+export async function generateTitle(messages) {
+    const apiKey = process.env.ANTHROPIC_API_KEY ?? (await getKey('anthropic'));
+    if (!apiKey)
+        return '';
+    try {
+        const client = new Anthropic({ apiKey });
+        const truncated = messages.slice(0, 6);
+        const res = await client.messages.create({
+            model: process.env.MOD8_TITLE_MODEL ?? 'claude-haiku-4-5',
+            max_tokens: 32,
+            system: 'Generate a 4-5 word title summarizing this conversation. Output ONLY the title — no quotes, no period, no preamble. Be specific to what was discussed.',
+            messages: truncated.map((m) => ({ role: m.role, content: m.content })),
+        });
+        const text = res.content
+            .filter((b) => b.type === 'text')
+            .map((b) => b.text)
+            .join('')
+            .trim()
+            .replace(/^["']|["']$/g, '')
+            .replace(/[.!?]+$/, '');
+        return text;
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Fallback title from first user message when no AI-generated title exists.
+ */
+export function fallbackTitle(session) {
+    const firstUser = session.messages.find((m) => m.role === 'user');
+    if (!firstUser)
+        return '(empty session)';
+    const words = firstUser.content.trim().split(/\s+/).slice(0, 5).join(' ');
+    return words.length > 60 ? words.slice(0, 57) + '…' : words;
+}
+export const SESSIONS_DIR_PATH = SESSIONS_DIR;

package/dist/types.js

@@ -0,0 +1,9 @@
+export const PROVIDERS = ['anthropic', 'openai', 'google'];
+export function isProvider(s) {
+    return PROVIDERS.includes(s);
+}
+export const PROVIDER_LABELS = {
+    anthropic: 'Anthropic (Claude)',
+    openai: 'OpenAI (GPT)',
+    google: 'Google (Gemini)',
+};

package/dist/util/debug.js

@@ -0,0 +1,79 @@
+/**
+ * MOD8_DEBUG=1 instrumentation.
+ *
+ * Prints to stderr (so it never pollutes piped stdout / one-shot output).
+ * Always redacts API keys to the masked form before logging.
+ *
+ * Use cases:
+ *   - "Is the env var being respected?"           → modelResolution log
+ *   - "What URL did the SDK try to hit?"          → providerCall log
+ *   - "What did the provider actually return?"    → providerResponse log
+ *   - "Why does mod8 say 'model not available'?"  → providerError log
+ */
+import { maskApiKey } from './secrets.js';
+export function debugEnabled() {
+    return process.env.MOD8_DEBUG === '1';
+}
+function ts() {
+    const d = new Date();
+    return d.toISOString().slice(11, 23);
+}
+function emit(line) {
+    process.stderr.write(`[mod8:debug ${ts()}] ${line}\n`);
+}
+export function debugLog(message, fields) {
+    if (!debugEnabled())
+        return;
+    if (!fields) {
+        emit(message);
+        return;
+    }
+    const parts = [message];
+    for (const [k, v] of Object.entries(fields)) {
+        parts.push(`${k}=${formatValue(v)}`);
+    }
+    emit(parts.join(' '));
+}
+function formatValue(v) {
+    if (v === undefined)
+        return '(undefined)';
+    if (v === null)
+        return '(null)';
+    if (typeof v === 'string')
+        return JSON.stringify(v);
+    return String(v);
+}
+/**
+ * Approximate the URL each provider's SDK will hit.  We don't intercept the
+ * network, so this is a best-effort hint based on apiType + baseUrl + model.
+ * Useful when debugging a "why isn't my custom model getting through?"
+ * report — the URL printed here matches what the SDK actually requests.
+ */
+export function approximateProviderUrl(apiType, model, baseUrl) {
+    switch (apiType) {
+        case 'anthropic':
+            return `https://api.anthropic.com/v1/messages  (model=${model})`;
+        case 'openai-compat': {
+            const base = baseUrl ?? 'https://api.openai.com/v1';
+            return `${base.replace(/\/$/, '')}/chat/completions  (model=${model})`;
+        }
+        case 'gemini':
+            return `https://generativelanguage.googleapis.com/v1beta/models/${model}:streamGenerateContent`;
+    }
+}
+export function debugProviderCall(opts) {
+    if (!debugEnabled())
+        return;
+    emit(`provider-call providerId=${opts.providerId} apiType=${opts.apiType} model=${JSON.stringify(opts.model)} modelSource=${opts.modelSource} key=${maskApiKey(opts.apiKey)} url=${JSON.stringify(approximateProviderUrl(opts.apiType, opts.model, opts.baseUrl))} prompt=${JSON.stringify(opts.promptPreview.slice(0, 200))}`);
+}
+export function debugProviderError(providerId, err) {
+    if (!debugEnabled())
+        return;
+    const message = err instanceof Error ? err.message : String(err);
+    emit(`provider-error providerId=${providerId} message=${JSON.stringify(message.slice(0, 800))}`);
+}
+export function debugProviderResponse(providerId, model, tokens) {
+    if (!debugEnabled())
+        return;
+    emit(`provider-ok providerId=${providerId} model=${JSON.stringify(model)} input_tok=${tokens.input} output_tok=${tokens.output} latency_ms=${tokens.latencyMs}`);
+}