mod8-cli 0.2.0

package/dist/util/errors.js

@@ -0,0 +1,157 @@
+/**
+ * Pull a sensible short text out of the SDK error, stripping prefix noise
+ * (so we don't double-print the HTTP code) and provider-SDK wrapper text
+ * (e.g. `[GoogleGenerativeAI Error]: Error fetching from <url>:`).
+ */
+function extractRawMessage(err) {
+    let cleaned = err.message
+        // SDK wrapper prefixes
+        .replace(/^\s*\[GoogleGenerativeAI Error\]:\s*/i, '')
+        .replace(/^\s*Error fetching from\s+\S+\s*:\s*/i, '')
+        // HTTP status prefixes
+        .replace(/^\s*\[\d{3}[^\]]*\]\s*/, '') // [403 Forbidden]
+        .replace(/^\s*Status:?\s*\d{3}[\s,:-]*/i, '') // Status: 403
+        .replace(/^\s*\d{3}\s+(?=[A-Z])/, '') // bare "403 Forbidden..."
+        .replace(/^\s*Error:?\s+/i, '');
+    cleaned = cleaned.split('\n')[0].trim();
+    // Google SDK errors stuff structured detail JSON onto the same line —
+    // strip that tail so the user sees just the human-readable summary.
+    cleaned = cleaned.replace(/\s*\[?\{["']@type["'].*$/, '').trim();
+    return cleaned.slice(0, 240);
+}
+function extractCode(err) {
+    const e = err;
+    if (typeof e['status'] === 'number')
+        return e['status'];
+    if (typeof e['statusCode'] === 'number')
+        return e['statusCode'];
+    // Fall back to scanning the message — most SDK errors include the code in
+    // brackets or as a leading token.
+    const m = err.message.match(/\b(\d{3})\b/);
+    if (m) {
+        const code = Number.parseInt(m[1], 10);
+        if (code >= 400 && code < 600)
+            return code;
+    }
+    return undefined;
+}
+function extractRetryDelay(msg) {
+    const m1 = msg.match(/retry[\s-]*after\s*:?\s*(\d+)/i);
+    if (m1)
+        return Number.parseInt(m1[1], 10);
+    const m2 = msg.match(/try\s+again\s+in\s+(\d+)\s*(?:seconds?|s)\b/i);
+    if (m2)
+        return Number.parseInt(m2[1], 10);
+    const m3 = msg.match(/wait\s+(\d+)\s*(?:seconds?|s)\b/i);
+    if (m3)
+        return Number.parseInt(m3[1], 10);
+    return undefined;
+}
+function detectKind(err, code) {
+    const msg = err.message;
+    // Network/timeout get evaluated FIRST because their messages also often
+    // contain digits that look like codes.
+    if (/ENOTFOUND|ECONNREFUSED|ECONNRESET|EAI_AGAIN|fetch failed|network/i.test(msg)) {
+        return 'network';
+    }
+    if (/timeout|timed out|ETIMEDOUT/i.test(msg))
+        return 'timeout';
+    if (code === 401)
+        return 'auth';
+    if (code === 403)
+        return 'forbidden';
+    if (code === 429)
+        return 'rate-limit';
+    if (code === 402)
+        return 'no-credit';
+    if (code !== undefined && code >= 500 && code < 600)
+        return 'server';
+    if (/\bunauthor/i.test(msg) ||
+        /\bauthentication[_ -]?(?:failed|error)/i.test(msg) ||
+        /\binvalid[_ -]?api[_ -]?key\b/i.test(msg) ||
+        /\bapi[_ -]?key[_ -]?invalid\b/i.test(msg) || // Google's API_KEY_INVALID
+        /\bapi\s+key\s+(?:is\s+)?(?:not\s+valid|invalid)/i.test(msg) || // "API key not valid"
+        /\bincorrect[_ -]?api[_ -]?key\b/i.test(msg)) {
+        return 'auth';
+    }
+    if (/\bforbidden\b|\bdenied\b|\baccess\s+(?:has\s+been\s+)?denied\b|\bblocked\b|\bnot[_ -]?authorized\b/i.test(msg)) {
+        return 'forbidden';
+    }
+    if (/\brate[_ -]?limit|\btoo[_ -]many[_ -]requests\b|\brate_limit_exceeded\b/i.test(msg)) {
+        return 'rate-limit';
+    }
+    if (/\binsufficient[_ -](?:balance|credit|funds)\b|\bout[_ -]of[_ -](?:credit|balance)\b|\bpayment[_ -]required\b|\bno[_ -]balance\b|\bbilling[_ -]not[_ -]active\b|\bfree.*tier.*exceed/i.test(msg)) {
+        return 'no-credit';
+    }
+    if (/\bquota\b|\bbilling\b/i.test(msg))
+        return 'no-credit';
+    // Tightened: word boundary on "model" (so "models/<name>" in URLs DOESN'T
+    // match), bounded gap (no 200-char .* spans), and no "invalid" — too
+    // generic; was over-matching against "API key not valid" elsewhere in
+    // the same message.
+    if (/\bmodel\b[^.\n]{0,80}\b(?:not\s+found|does\s+not\s+exist|unsupported|not\s+supported|deprecated|no\s+longer\s+available)\b/i.test(msg)) {
+        return 'model';
+    }
+    if (/\b(?:not\s+found|does\s+not\s+exist|unsupported|deprecated|no\s+longer\s+available)\b[^.\n]{0,80}\bmodel\b/i.test(msg)) {
+        return 'model';
+    }
+    return 'other';
+}
+export function diagnose(err) {
+    if (!(err instanceof Error)) {
+        return { kind: 'other', rawMessage: String(err).slice(0, 240) };
+    }
+    const code = extractCode(err);
+    const kind = detectKind(err, code);
+    const rawMessage = extractRawMessage(err);
+    const retryDelaySeconds = kind === 'rate-limit' ? extractRetryDelay(err.message) : undefined;
+    const result = { kind, rawMessage };
+    if (code !== undefined)
+        result.code = code;
+    if (retryDelaySeconds !== undefined)
+        result.retryDelaySeconds = retryDelaySeconds;
+    return result;
+}
+/**
+ * Map a raw provider error into a short human-readable description.
+ * Backwards-compat shim used by the --all parallel path (which displays a
+ * single line per block, no room for the multi-line explainError output).
+ *
+ * If `provider` is supplied, the "invalid API key" path can append a
+ * `Run: mod8 keys set <provider>` remedy hint.
+ */
+export function classifyError(err, provider) {
+    if (!(err instanceof Error))
+        return String(err);
+    const msg = err.message;
+    // Already-friendly errors from our own code (e.g. getKey)
+    if (msg.startsWith('No ') && /key configured/.test(msg))
+        return msg;
+    const diag = diagnose(err);
+    switch (diag.kind) {
+        case 'auth':
+            return provider
+                ? `invalid API key. Run: mod8 keys set ${provider}`
+                : 'invalid API key';
+        case 'forbidden': {
+            const tail = diag.rawMessage ? ` — ${diag.rawMessage}` : '';
+            return `forbidden (HTTP ${diag.code ?? 403})${tail}`;
+        }
+        case 'rate-limit':
+            return diag.retryDelaySeconds
+                ? `rate limited — try again in ${diag.retryDelaySeconds}s`
+                : 'rate limited — try again shortly';
+        case 'no-credit':
+            return 'quota or billing issue — check your provider dashboard';
+        case 'server':
+            return `provider server error (HTTP ${diag.code ?? '5xx'}) — try again shortly`;
+        case 'network':
+            return 'network error — check your connection';
+        case 'timeout':
+            return 'request timed out — try again';
+        case 'model':
+            return `model not available — set MOD8_${(provider ?? '').toUpperCase()}_MODEL to override`;
+        default:
+            return diag.rawMessage || msg.split('\n')[0].slice(0, 240);
+    }
+}

package/dist/util/prompt.js

@@ -0,0 +1,111 @@
+import { createInterface } from 'readline';
+import { Writable } from 'stream';
+/**
+ * Read a line from stdin without echoing characters (password-style).
+ *
+ * - Non-TTY (piped input): plain readline.
+ * - TTY: readline in terminal mode with a muted output stream so typed/pasted
+ *   characters don't echo, but the line is still reassembled correctly when
+ *   the terminal delivers a long paste in multiple chunks.
+ *
+ * The earlier hand-rolled raw-mode reader had three bugs that combined to
+ * truncate pasted input: stdin.resume() called before the data listener was
+ * attached (first chunk could be dropped), setEncoding after resume, and no
+ * cross-chunk reassembly. readline handles all of that internally.
+ */
+/**
+ * Read a single line from stdin (echoed). Optional default returned if user
+ * presses Enter without typing.
+ */
+export async function readLine(promptText, fallback = '') {
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        terminal: process.stdin.isTTY ?? false,
+    });
+    return new Promise((resolve) => {
+        rl.question(promptText, (line) => {
+            rl.close();
+            const value = line.trim();
+            resolve(value === '' ? fallback : value);
+        });
+    });
+}
+export function maskKey(key) {
+    if (key.length <= 8)
+        return '*'.repeat(Math.max(key.length, 4));
+    return `${key.slice(0, 4)}…${key.slice(-4)}`;
+}
+export async function readSecret(promptText) {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+    if (!stdin.isTTY) {
+        const rl = createInterface({ input: stdin });
+        stdout.write(promptText);
+        return new Promise((resolve) => {
+            rl.once('line', (line) => {
+                rl.close();
+                resolve(line);
+            });
+        });
+    }
+    // Muted writable so readline's terminal mode doesn't echo characters.
+    const muted = new Writable({
+        write(_chunk, _encoding, callback) {
+            callback();
+        },
+    });
+    const rl = createInterface({
+        input: stdin,
+        output: muted,
+        terminal: true,
+    });
+    stdout.write(promptText);
+    return new Promise((resolve) => {
+        rl.once('line', (line) => {
+            rl.close();
+            stdout.write('\n');
+            resolve(line);
+        });
+        rl.once('SIGINT', () => {
+            rl.close();
+            stdout.write('\n');
+            process.exit(130);
+        });
+    });
+}
+/**
+ * Yes/no prompt. Returns true only if the answer starts with 'y' or 'Y'.
+ * Uses readline for both TTY and non-TTY so paste/edit behavior is identical.
+ */
+export async function confirm(promptText) {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+    if (!stdin.isTTY) {
+        const rl = createInterface({ input: stdin });
+        stdout.write(promptText);
+        return new Promise((resolve) => {
+            rl.once('line', (line) => {
+                rl.close();
+                resolve(/^y/i.test(line.trim()));
+            });
+        });
+    }
+    // TTY path: readline in terminal mode (chars echo so the user can see y/n)
+    const rl = createInterface({
+        input: stdin,
+        output: stdout,
+        terminal: true,
+    });
+    return new Promise((resolve) => {
+        rl.question(promptText, (answer) => {
+            rl.close();
+            resolve(/^y/i.test(answer.trim()));
+        });
+        rl.once('SIGINT', () => {
+            rl.close();
+            stdout.write('\n');
+            process.exit(130);
+        });
+    });
+}

package/dist/util/secrets.js

@@ -0,0 +1,110 @@
+/**
+ * Secret detection + masking.
+ *
+ * Used by the inline paste-key flow and as a universal sanitizer over user
+ * input: every message added to the transcript, persisted to a session, or
+ * forwarded to an LLM is run through `sanitizeKeys` so a real API key never
+ * leaves the local machine via session JSON, terminal scrollback, or
+ * subsequent LLM turns.  The full key only lives in providers.json.
+ *
+ * Detection is intentionally limited to KNOWN provider key prefixes.  That
+ * keeps false-positive risk near zero (we don't accidentally mask normal
+ * prose).  Custom providers that don't match a known prefix go through the
+ * existing `mod8 add-provider` flow.
+ */
+import { templateById } from '../providers/registry.js';
+/**
+ * Match known key shapes by prefix + a body of safe key characters.  Listed
+ * most-specific-first so `sk-ant-`/`sk-or-`/`sk-proj-` win over the generic
+ * legacy `sk-` fallback (which still has to be long enough to look like a
+ * real key — see the 32-char minimum).
+ */
+const KEY_RES = [
+    { re: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g, templateId: 'anthropic' },
+    { re: /\bsk-or-(?:v\d-)?[A-Za-z0-9_-]{20,}\b/g, templateId: 'openrouter' },
+    { re: /\bsk-proj-[A-Za-z0-9_-]{20,}\b/g, templateId: 'openai' },
+    { re: /\bgsk_[A-Za-z0-9]{20,}\b/g, templateId: 'groq' },
+    { re: /\bxai-[A-Za-z0-9]{20,}\b/g, templateId: 'xai' },
+    { re: /\bAIza[A-Za-z0-9_-]{20,}\b/g, templateId: 'google' },
+    // Legacy OpenAI / DeepSeek / Mistral — bare "sk-" with a long body. Keep
+    // this LAST so the more-specific prefixes above win.
+    { re: /\bsk-[A-Za-z0-9]{32,}\b/g, templateId: 'openai' },
+];
+/**
+ * Find the FIRST API key in a piece of text, if any.  Used by the chat REPL
+ * to detect a paste, save the provider, and replace the raw key with its
+ * masked form before storing/forwarding the message.
+ */
+export function findApiKey(text) {
+    let best = null;
+    for (const { re, templateId } of KEY_RES) {
+        re.lastIndex = 0;
+        const m = re.exec(text);
+        if (!m)
+            continue;
+        const tpl = templateById(templateId);
+        if (!tpl)
+            continue;
+        const candidate = {
+            key: m[0],
+            template: tpl,
+            start: m.index,
+            end: m.index + m[0].length,
+        };
+        // Earliest match wins; on ties, longest match (more-specific prefix).
+        if (!best ||
+            candidate.start < best.start ||
+            (candidate.start === best.start && candidate.key.length > best.key.length)) {
+            best = candidate;
+        }
+    }
+    return best;
+}
+/**
+ * Mask an API key for display.  Preserves enough of the prefix that the
+ * provider stays recognizable (e.g. `sk-ant-…AAAA`) without leaking enough
+ * material to be useful if the transcript is shared.
+ */
+export function maskApiKey(key) {
+    const trimmed = key.trim();
+    if (trimmed.length <= 12)
+        return '*'.repeat(Math.max(trimmed.length, 4));
+    const prefixLen = trimmed.startsWith('sk-ant-') ? 7
+        : trimmed.startsWith('sk-proj-') ? 8
+            : trimmed.startsWith('sk-or-') ? 6
+                : trimmed.startsWith('AIza') ? 6
+                    : trimmed.startsWith('gsk_') ? 4
+                        : trimmed.startsWith('xai-') ? 4
+                            : trimmed.startsWith('sk-') ? 3
+                                : 4;
+    return `${trimmed.slice(0, prefixLen)}…${trimmed.slice(-4)}`;
+}
+/**
+ * Replace every API key in the input with its masked form.  Idempotent —
+ * applying twice yields the same string (masked forms don't match the
+ * detection regexes).  Use this on every user message before persisting or
+ * forwarding to an LLM so a key never lands in session JSON or a remote
+ * provider's request body.
+ */
+export function sanitizeKeys(text) {
+    let out = '';
+    let cursor = 0;
+    while (cursor < text.length) {
+        const remainder = text.slice(cursor);
+        const found = findApiKey(remainder);
+        if (!found) {
+            out += remainder;
+            break;
+        }
+        out += remainder.slice(0, found.start) + maskApiKey(found.key);
+        cursor += found.end;
+    }
+    return out;
+}
+/**
+ * Convenience: did the input contain a key?  Used by the chat REPL to decide
+ * whether to surface the masking confirmation or stay silent.
+ */
+export function containsApiKey(text) {
+    return findApiKey(text) !== null;
+}

package/dist/util/text.js

@@ -0,0 +1,53 @@
+/**
+ * Small text helpers shared across the routing matchers.
+ */
+/** Levenshtein edit distance.  O(|a|·|b|) time, O(min(|a|,|b|)) space. */
+export 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];
+}
+/** Variants of "key" / synonyms.  Used to fuzzy-match typo'd nouns like "kew" / "kee" / "keey". */
+const KEY_NOUN_VARIANTS = [
+    'key', 'keys',
+    'credentials', 'credential',
+    'secret', 'secrets',
+    'token', 'tokens',
+    'apikey', 'api-key',
+];
+/**
+ * True when the word LOOKS like the user meant "key" (or a synonym) —
+ * accepts exact matches AND single-edit typos like "kew" / "kee" / "kez".
+ *
+ * Used by the paste-key intent matcher: phrases like "change the google
+ * kew" should still trigger the inline paste flow even though "kew" is
+ * mistyped.
+ */
+export function looksLikeKeyNoun(word) {
+    const lower = word.toLowerCase().replace(/[!?.,]+$/, '');
+    if (lower.length < 2 || lower.length > 16)
+        return false;
+    for (const v of KEY_NOUN_VARIANTS) {
+        if (levenshtein(lower, v) <= 1)
+            return true;
+    }
+    return false;
+}

package/dist/util/time.js

@@ -0,0 +1,25 @@
+/**
+ * Format a millisecond timestamp as "X ago".
+ */
+export function humanTimeAgo(ts) {
+    const diff = Math.max(0, Date.now() - ts);
+    const sec = Math.floor(diff / 1000);
+    const min = Math.floor(sec / 60);
+    const hr = Math.floor(min / 60);
+    const day = Math.floor(hr / 24);
+    if (sec < 60)
+        return 'just now';
+    if (min === 1)
+        return '1 minute ago';
+    if (min < 60)
+        return `${min} minutes ago`;
+    if (hr === 1)
+        return '1 hour ago';
+    if (hr < 24)
+        return `${hr} hours ago`;
+    if (day === 1)
+        return '1 day ago';
+    if (day < 30)
+        return `${day} days ago`;
+    return new Date(ts).toISOString().slice(0, 10);
+}