b3-dict 0.0.0-stage → 0.2.0

package/dist/lib/ask.js

@@ -0,0 +1,54 @@
+import { createOpenAI } from '@ai-sdk/openai';
+import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+import { generateText, Output } from 'ai';
+import { AnswerEnvelope } from './envelope.js';
+import { classify } from './policy.js';
+import { err, ok } from './types.js';
+// Room for a three-sense meaning in Vietnamese; the exemplars run 200–300 tokens.
+export const MAX_OUTPUT_TOKENS = 2500;
+const TIMEOUT_MS = 60_000;
+// Prompt rules validated by the answer-shape prototype (27 calls, 6 models).
+const SYSTEM = [
+    'You are a dictionary assistant for a Vietnamese developer.',
+    'The user asks freeform questions (often mixed English/Vietnamese) about English words, phrases, idioms, or usage.',
+    'Classify the question into exactly one kind:',
+    '- word-check: asking whether something is a real English word/term, or what the correct word is.',
+    '- meaning: asking what a word/phrase/idiom means.',
+    '- interpretation: asking how to understand a specific passage, joke, or sentence in context.',
+    'All *Vi fields must be in Vietnamese. Keep quoted English inside examples/nuances as-is. Be concise; dictionary register, not chatty.',
+    'Rules: suggestions is empty when the word IS valid. synonyms must never include the term itself. subject must quote the interpreted text verbatim. Fields not used by the chosen kind are null.',
+].join('\n');
+function modelFor({ route, model, apiKey }) {
+    if (route === 'openai')
+        return createOpenAI({ apiKey })(model);
+    const openrouter = createOpenRouter({ apiKey });
+    // OpenAI's endpoints on OpenRouter refuse to run with reasoning off (HTTP 400), and their models
+    // already fit the output cap, so they get no reasoning option.
+    if (model.startsWith('openai/'))
+        return openrouter(model);
+    // A dictionary lookup doesn't need the model to think first. Reasoning models like glm-4.6 spend
+    // the whole output budget on reasoning and never get to the envelope; non-reasoning models ignore this.
+    return openrouter(model, { reasoning: { enabled: false, effort: 'none' } });
+}
+// One model call, no retries of its own: retry policy lives in policy.ts.
+export function createAsk(config) {
+    const model = modelFor(config);
+    return async (query) => {
+        try {
+            const { output } = await generateText({
+                model,
+                system: SYSTEM,
+                prompt: query,
+                maxOutputTokens: MAX_OUTPUT_TOKENS,
+                maxRetries: 0,
+                abortSignal: AbortSignal.timeout(TIMEOUT_MS),
+                output: Output.object({ schema: AnswerEnvelope }),
+            });
+            return ok(output);
+        }
+        catch (e) {
+            return err(classify(e));
+        }
+    };
+}
+//# sourceMappingURL=ask.js.map

package/dist/lib/ask.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask.js","sourceRoot":"","sources":["../../src/lib/ask.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,IAAI,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,GAAG,EAAE,EAAE,EAAe,MAAM,YAAY,CAAC;AAElD,kFAAkF;AAClF,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC;AACtC,MAAM,UAAU,GAAG,MAAM,CAAC;AAE1B,6EAA6E;AAC7E,MAAM,MAAM,GAAG;IACb,4DAA4D;IAC5D,mHAAmH;IACnH,8CAA8C;IAC9C,kGAAkG;IAClG,mDAAmD;IACnD,8FAA8F;IAC9F,uIAAuI;IACvI,iMAAiM;CAClM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,SAAS,QAAQ,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAU;IAChD,IAAI,KAAK,KAAK,QAAQ;QAAE,OAAO,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;IAC/D,MAAM,UAAU,GAAG,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;IAChD,iGAAiG;IACjG,+DAA+D;IAC/D,IAAI,KAAK,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC;IAC1D,iGAAiG;IACjG,wGAAwG;IACxG,OAAO,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;AAC9E,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,SAAS,CAAC,MAAc;IACtC,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,OAAO,KAAK,EAAE,KAAK,EAAE,EAAE;QACrB,IAAI,CAAC;YACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,YAAY,CAAC;gBACpC,KAAK;gBACL,MAAM,EAAE,MAAM;gBACd,MAAM,EAAE,KAAK;gBACb,eAAe,EAAE,iBAAiB;gBAClC,UAAU,EAAE,CAAC;gBACb,WAAW,EAAE,WAAW,CAAC,OAAO,CAAC,UAAU,CAAC;gBAC5C,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;aAClD,CAAC,CAAC;YACH,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC;QACpB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/lib/config.d.ts

@@ -0,0 +1,8 @@
+import { type Config, type ConfigProblem, type Result, type Route } from './types.js';
+export declare const DEFAULT_MODEL: Record<Route, string>;
+export declare const MODEL_CHOICES: Record<Route, readonly string[]>;
+type Env = Record<string, string | undefined>;
+export declare function checkModel(route: Route, id: string): Result<string, ConfigProblem>;
+export declare function resolveConfig(env: Env, modelFlag?: string, saved?: string): Result<Config, ConfigProblem>;
+export declare const keyVarFor: (route: Route) => string;
+export {};

package/dist/lib/config.js

@@ -0,0 +1,52 @@
+import { err, ok, ROUTES } from './types.js';
+export const DEFAULT_MODEL = {
+    openrouter: 'qwen/qwen3-235b-a22b-2507',
+    openai: 'gpt-5-mini',
+};
+// What the TUI's model picker offers, default first. Every one has answered a real lookup.
+export const MODEL_CHOICES = {
+    openrouter: [DEFAULT_MODEL.openrouter, 'qwen/qwen3-30b-a3b-instruct-2507', 'z-ai/glm-4.6', 'openai/gpt-5-mini'],
+    openai: [DEFAULT_MODEL.openai],
+};
+const KEY_VAR = {
+    openrouter: 'OPENROUTER_API_KEY',
+    openai: 'OPENAI_API_KEY',
+};
+const read = (env, name) => env[name]?.trim() || undefined;
+const isRoute = (value) => ROUTES.includes(value);
+// A model id as the route will serve it. A slash id is an OpenRouter id; a bare name resolves on
+// whichever route is active, so on OpenRouter it means OpenAI's model of that name.
+export function checkModel(route, id) {
+    const model = id.trim();
+    if (model.includes('/')) {
+        return route === 'openrouter' ? ok(model) : err({ code: 'model-needs-openrouter', model });
+    }
+    return ok(route === 'openrouter' ? `openai/${model}` : model);
+}
+// Which model wins: the one-shot --model, then B3_DICT_MODEL, then the model picked in the TUI
+// (saved), then the route's default. A saved model the route can't serve is skipped, not an error:
+// the user didn't ask for it on this run.
+export function resolveConfig(env, modelFlag, saved) {
+    const keys = {
+        openrouter: read(env, KEY_VAR.openrouter),
+        openai: read(env, KEY_VAR.openai),
+    };
+    if (!keys.openrouter && !keys.openai)
+        return err({ code: 'no-key' });
+    const forced = read(env, 'B3_DICT_PROVIDER')?.toLowerCase();
+    if (forced !== undefined && !isRoute(forced))
+        return err({ code: 'bad-provider', value: forced });
+    const route = forced ?? (keys.openrouter ? 'openrouter' : 'openai');
+    const apiKey = keys[route];
+    if (!apiKey)
+        return err({ code: 'route-key-missing', route });
+    const requested = modelFlag?.trim() || read(env, 'B3_DICT_MODEL');
+    if (requested) {
+        const model = checkModel(route, requested);
+        return model.ok ? ok({ route, apiKey, model: model.data }) : model;
+    }
+    const remembered = saved?.trim() ? checkModel(route, saved) : undefined;
+    return ok({ route, apiKey, model: remembered?.ok ? remembered.data : DEFAULT_MODEL[route] });
+}
+export const keyVarFor = (route) => KEY_VAR[route];
+//# sourceMappingURL=config.js.map

package/dist/lib/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"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"}

package/dist/lib/db.d.ts

@@ -0,0 +1,27 @@
+import Database from 'better-sqlite3';
+import type { Kind } from './envelope.js';
+import { type Result, type Route } from './types.js';
+export type Db = Database.Database;
+export type LookupRow = {
+    id: string;
+    query_text: string;
+    kind: Kind;
+    answer_json: string;
+    route: Route;
+    model: string;
+    created_at: string;
+    saved: boolean;
+    saved_at: string | null;
+};
+export type NewLookup = Omit<LookupRow, 'saved' | 'saved_at'>;
+export type ListRow = Omit<LookupRow, 'answer_json' | 'route' | 'model'>;
+export type ListKind = 'history' | 'wordbook';
+export type Counts = Record<ListKind, number>;
+export declare const normalizeQuery: (text: string) => string;
+export declare function openDb(path: string): Result<Db>;
+export declare function findCached(db: Db, queryText: string): Result<LookupRow | undefined>;
+export declare function insertLookup(db: Db, row: NewLookup): Result<LookupRow>;
+export declare function setSaved(db: Db, id: string, saved: boolean, now: Date): Result<LookupRow>;
+export declare function listLookups(db: Db, which: ListKind): Result<ListRow[]>;
+export declare function countLookups(db: Db): Result<Counts>;
+export declare function getLookup(db: Db, id: string): Result<LookupRow | undefined>;

package/dist/lib/db.js

@@ -0,0 +1,98 @@
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import Database from 'better-sqlite3';
+import { err, messageOf, ok } from './types.js';
+const fromRaw = (raw) => ({ ...raw, saved: raw.saved === 1 });
+const LIST_SQL = {
+    history: 'SELECT id, query_text, kind, created_at, saved, saved_at FROM lookups ORDER BY created_at DESC, rowid DESC',
+    wordbook: 'SELECT id, query_text, kind, created_at, saved, saved_at FROM lookups WHERE saved = 1 ORDER BY saved_at DESC, rowid DESC',
+};
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS lookups (
+    id          TEXT PRIMARY KEY,
+    query_text  TEXT NOT NULL,
+    kind        TEXT NOT NULL,
+    answer_json TEXT NOT NULL,
+    route       TEXT NOT NULL,
+    model       TEXT NOT NULL,
+    created_at  TEXT NOT NULL,
+    saved       INTEGER NOT NULL DEFAULT 0,
+    saved_at    TEXT NULL
+  )
+`;
+// The cache key: same words, whatever the spacing or line breaks. Case still counts.
+export const normalizeQuery = (text) => text.trim().replace(/\s+/g, ' ');
+export function openDb(path) {
+    try {
+        if (path !== ':memory:')
+            mkdirSync(dirname(path), { recursive: true });
+        const db = new Database(path);
+        db.pragma('journal_mode = WAL');
+        db.function('norm_ws', { deterministic: true }, (text) => normalizeQuery(String(text)));
+        db.exec(SCHEMA);
+        return ok(db);
+    }
+    catch (e) {
+        return err(messageOf(e));
+    }
+}
+export function findCached(db, queryText) {
+    try {
+        const row = db
+            .prepare('SELECT * FROM lookups WHERE norm_ws(query_text) = ? ORDER BY created_at DESC, rowid DESC LIMIT 1')
+            .get(normalizeQuery(queryText));
+        return ok(row && fromRaw(row));
+    }
+    catch (e) {
+        return err(messageOf(e));
+    }
+}
+export function insertLookup(db, row) {
+    try {
+        db.prepare(`INSERT INTO lookups (id, query_text, kind, answer_json, route, model, created_at)
+       VALUES (@id, @query_text, @kind, @answer_json, @route, @model, @created_at)`).run(row);
+        return ok({ ...row, saved: false, saved_at: null });
+    }
+    catch (e) {
+        return err(messageOf(e));
+    }
+}
+// The wordbook is this flag: a saved lookup is a wordbook entry.
+export function setSaved(db, id, saved, now) {
+    try {
+        const row = db
+            .prepare('UPDATE lookups SET saved = ?, saved_at = ? WHERE id = ? RETURNING *')
+            .get(saved ? 1 : 0, saved ? now.toISOString() : null, id);
+        return row ? ok(fromRaw(row)) : err(`no lookup with id ${id}`);
+    }
+    catch (e) {
+        return err(messageOf(e));
+    }
+}
+export function listLookups(db, which) {
+    try {
+        return ok(db.prepare(LIST_SQL[which]).all().map(fromRaw));
+    }
+    catch (e) {
+        return err(messageOf(e));
+    }
+}
+export function countLookups(db) {
+    try {
+        const row = db.prepare('SELECT COUNT(*) AS history, COALESCE(SUM(saved), 0) AS wordbook FROM lookups').get();
+        return ok({ history: row.history, wordbook: row.wordbook });
+    }
+    catch (e) {
+        return err(messageOf(e));
+    }
+}
+export function getLookup(db, id) {
+    try {
+        const row = db.prepare('SELECT * FROM lookups WHERE id = ?').get(id);
+        return ok(row && fromRaw(row));
+    }
+    catch (e) {
+        return err(messageOf(e));
+    }
+}
+//# sourceMappingURL=db.js.map

package/dist/lib/db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.js","sourceRoot":"","sources":["../../src/lib/db.ts"],"names":[],"mappings":"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"}

package/dist/lib/envelope.d.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import { type Result } from './types.js';
+export declare const KINDS: readonly ["word-check", "meaning", "interpretation"];
+export type Kind = (typeof KINDS)[number];
+export declare const AnswerEnvelope: z.ZodObject<{
+    kind: z.ZodEnum<{
+        "word-check": "word-check";
+        meaning: "meaning";
+        interpretation: "interpretation";
+    }>;
+    term: z.ZodNullable<z.ZodString>;
+    isWord: z.ZodNullable<z.ZodBoolean>;
+    verdictVi: z.ZodNullable<z.ZodString>;
+    suggestions: z.ZodNullable<z.ZodArray<z.ZodObject<{
+        term: z.ZodString;
+        reasonVi: z.ZodString;
+    }, z.core.$strip>>>;
+    ipa: z.ZodNullable<z.ZodString>;
+    entries: z.ZodNullable<z.ZodArray<z.ZodObject<{
+        partOfSpeech: z.ZodString;
+        glossVi: z.ZodString;
+        register: z.ZodNullable<z.ZodString>;
+        examples: z.ZodArray<z.ZodObject<{
+            text: z.ZodString;
+            glossVi: z.ZodString;
+        }, z.core.$strip>>;
+        synonyms: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>>;
+    subject: z.ZodNullable<z.ZodString>;
+    explanationVi: z.ZodNullable<z.ZodString>;
+    nuances: z.ZodNullable<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type Answer = z.infer<typeof AnswerEnvelope>;
+export declare function checkContent(a: Answer): string | null;
+export declare const displayTerm: (answer: Answer, query: string) => string;
+export declare const bareIpa: (ipa: string) => string;
+export declare function parseStored(answerJson: string): Result<Answer>;

package/dist/lib/envelope.js

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import { err, messageOf, ok } from './types.js';
+export const KINDS = ['word-check', 'meaning', 'interpretation'];
+// Flat on purpose: every field present, null when the kind doesn't use it.
+// A discriminated union breaks OpenAI strict structured outputs (top-level oneOf).
+export const AnswerEnvelope = z.object({
+    kind: z.enum(KINDS),
+    // word-check
+    term: z.string().nullable(),
+    isWord: z.boolean().nullable(),
+    verdictVi: z.string().nullable(),
+    suggestions: z
+        .array(z.object({
+        term: z.string(),
+        reasonVi: z.string().describe('why this is the right word, in Vietnamese'),
+    }))
+        .max(3)
+        .nullable(),
+    // meaning
+    ipa: z.string().nullable(),
+    entries: z
+        .array(z.object({
+        partOfSpeech: z.string(),
+        glossVi: z.string().describe('Vietnamese meaning'),
+        register: z.string().nullable().describe('formal / slang / idiom / technical…'),
+        examples: z
+            .array(z.object({
+            text: z.string().describe('English example sentence'),
+            glossVi: z.string().describe('Vietnamese gloss of the example'),
+        }))
+            .max(2),
+        synonyms: z.array(z.string()).max(4),
+    }))
+        .max(3)
+        .nullable(),
+    // interpretation
+    subject: z.string().nullable().describe('the text being interpreted, verbatim'),
+    explanationVi: z.string().nullable().describe('Vietnamese explanation of meaning/intent'),
+    nuances: z.array(z.string()).max(3).nullable().describe('wordplay, tone, register notes'),
+});
+const blank = (s) => s === null || s.trim() === '';
+// An envelope can pass the schema and still say nothing. Returns what's missing, or null.
+export function checkContent(a) {
+    switch (a.kind) {
+        case 'word-check':
+            if (a.isWord === null)
+                return 'word-check without isWord';
+            if (blank(a.verdictVi))
+                return 'word-check without verdictVi';
+            return null;
+        case 'meaning':
+            if (!a.entries?.some((e) => !blank(e.glossVi)))
+                return 'meaning without any glossVi';
+            return null;
+        case 'interpretation':
+            if (blank(a.explanationVi))
+                return 'interpretation without explanationVi';
+            return null;
+    }
+}
+// The headline term: what the model named, or the question itself.
+export const displayTerm = (answer, query) => answer.term?.trim() || query.trim();
+// Models send IPA with or without slashes; renderers add their own.
+export const bareIpa = (ipa) => ipa.replace(/^\/|\/$/g, '');
+export function parseStored(answerJson) {
+    try {
+        const parsed = AnswerEnvelope.safeParse(JSON.parse(answerJson));
+        return parsed.success ? ok(parsed.data) : err(parsed.error.message);
+    }
+    catch (e) {
+        return err(messageOf(e));
+    }
+}
+//# sourceMappingURL=envelope.js.map

package/dist/lib/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/lib/envelope.ts"],"names":[],"mappings":"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"}

package/dist/lib/lookup.d.ts

@@ -0,0 +1,25 @@
+import { type Db, type LookupRow } from './db.js';
+import { type Answer } from './envelope.js';
+import { type RetryEvent } from './policy.js';
+import { type Failure, type Result, type Route } from './types.js';
+export type Ask = (query: string) => Promise<Result<Answer, Failure>>;
+export type LookupDeps = {
+    db: Db;
+    ask: Ask;
+    sleep: (ms: number) => Promise<void>;
+    now: () => Date;
+    newId: () => string;
+    onRetry?: (event: RetryEvent) => void;
+};
+export type LookupRequest = {
+    query: string;
+    route: Route;
+    model: string;
+    fresh: boolean;
+};
+export type LookupOutcome = {
+    answer: Answer;
+    entry: LookupRow;
+    cached: boolean;
+};
+export declare function lookup(request: LookupRequest, deps: LookupDeps): Promise<Result<LookupOutcome, Failure>>;

package/dist/lib/lookup.js

@@ -0,0 +1,41 @@
+import { findCached, insertLookup } from './db.js';
+import { checkContent, parseStored } from './envelope.js';
+import { runWithPolicy } from './policy.js';
+import { err, ok } from './types.js';
+// One lookup, start to finish: reuse a stored answer, or ask the model and store what comes back.
+// Failures write nothing, so history and the cache only ever hold answers that render.
+export async function lookup(request, deps) {
+    const { query, route, model, fresh } = request;
+    if (!fresh) {
+        const cached = findCached(deps.db, query);
+        if (!cached.ok)
+            return err({ reason: 'unexpected', detail: cached.error });
+        if (cached.data) {
+            const stored = parseStored(cached.data.answer_json);
+            if (stored.ok)
+                return ok({ answer: stored.data, entry: cached.data, cached: true });
+        }
+    }
+    const asked = await runWithPolicy(async () => {
+        const result = await deps.ask(query);
+        if (!result.ok)
+            return result;
+        const missing = checkContent(result.data);
+        return missing ? err({ reason: 'bad-output', detail: `empty answer (${missing})` }) : result;
+    }, deps);
+    if (!asked.ok)
+        return asked;
+    const inserted = insertLookup(deps.db, {
+        id: deps.newId(),
+        query_text: query,
+        kind: asked.data.kind,
+        answer_json: JSON.stringify(asked.data),
+        route,
+        model,
+        created_at: deps.now().toISOString(),
+    });
+    if (!inserted.ok)
+        return err({ reason: 'unexpected', detail: inserted.error });
+    return ok({ answer: asked.data, entry: inserted.data, cached: false });
+}
+//# sourceMappingURL=lookup.js.map

package/dist/lib/lookup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup.js","sourceRoot":"","sources":["../../src/lib/lookup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAA2B,MAAM,SAAS,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,WAAW,EAAe,MAAM,eAAe,CAAC;AACvE,OAAO,EAAE,aAAa,EAAmB,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,GAAG,EAAE,EAAE,EAAyC,MAAM,YAAY,CAAC;AAiB5E,kGAAkG;AAClG,uFAAuF;AACvF,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,OAAsB,EAAE,IAAgB;IACnE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IAE/C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;QAC1C,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,OAAO,GAAG,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;QAC3E,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;YAChB,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YACpD,IAAI,MAAM,CAAC,EAAE;gBAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QACtF,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,KAAK,IAAI,EAAE;QAC3C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,OAAO,MAAM,CAAC;QAC9B,MAAM,OAAO,GAAG,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC1C,OAAO,OAAO,CAAC,CAAC,CAAC,GAAG,CAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,iBAAiB,OAAO,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACxG,CAAC,EAAE,IAAI,CAAC,CAAC;IACT,IAAI,CAAC,KAAK,CAAC,EAAE;QAAE,OAAO,KAAK,CAAC;IAE5B,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,EAAE,EAAE;QACrC,EAAE,EAAE,IAAI,CAAC,KAAK,EAAE;QAChB,UAAU,EAAE,KAAK;QACjB,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI;QACrB,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC;QACvC,KAAK;QACL,KAAK;QACL,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;KACrC,CAAC,CAAC;IACH,IAAI,CAAC,QAAQ,CAAC,EAAE;QAAE,OAAO,GAAG,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAE/E,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;AACzE,CAAC"}

package/dist/lib/messages.d.ts

@@ -0,0 +1,90 @@
+import type { Origin } from './model.js';
+import type { RetryEvent } from './policy.js';
+import type { Config, ConfigProblem, Failure, Route } from './types.js';
+export declare const KEY_URL: Record<Route, string>;
+export declare const HELP = "B3 Dict \u2014 h\u1ECFi v\u1EC1 t\u1EEB, th\u00E0nh ng\u1EEF, c\u00E1ch d\u00F9ng ti\u1EBFng Anh; tr\u1EA3 l\u1EDDi b\u1EB1ng ti\u1EBFng Vi\u1EC7t.\n\nC\u00E1ch d\u00F9ng:\n  b3dict                        m\u1EDF giao di\u1EC7n h\u1ECFi \u0111\u00E1p\n  b3dict \"<c\u00E2u h\u1ECFi>\" [tu\u1EF3 ch\u1ECDn]  h\u1ECFi m\u1ED9t l\u1EA7n r\u1ED3i tho\u00E1t\n\nV\u00ED d\u1EE5:\n  b3dict \"take for granted\"\n  b3dict \"Is draggable an English word?\"\n  b3dict \"pragmatic\" --model z-ai/glm-4.6\n\nTu\u1EF3 ch\u1ECDn:\n  --fresh         b\u1ECF qua \u0111\u00E1p \u00E1n \u0111\u00E3 l\u01B0u, h\u1ECFi l\u1EA1i model\n  --model <id>    d\u00F9ng model n\u00E0y cho m\u1ED9t l\u1EA7n h\u1ECFi (lu\u00F4n h\u1ECFi l\u1EA1i model)\n  --json          in nguy\u00EAn answer envelope d\u1EA1ng JSON\n  -h, --help      hi\u1EC7n tr\u1EE3 gi\u00FAp\n  -V, --version   hi\u1EC7n phi\u00EAn b\u1EA3n\n\nM\u00E3 tho\u00E1t:\n  0 th\u00E0nh c\u00F4ng \u00B7 1 l\u1ED7i kh\u00F4ng r\u00F5 \u00B7 2 l\u1ED7i c\u00E1ch d\u00F9ng\n  3 l\u1ED7i c\u1EA5u h\u00ECnh (key, provider, model) \u00B7 4 l\u1ED7i provider";
+export declare const CLI: {
+    readonly unknownOption: (name: string) => string;
+    readonly badArguments: (detail: string) => string;
+    readonly missingQuery: "Thiếu câu hỏi. Ví dụ: b3dict \"take for granted\"";
+    readonly missingModel: "--model cần một tên model. Ví dụ: --model z-ai/glm-4.6";
+    readonly dbOpenFailed: (path: string, detail: string) => string;
+    readonly unknownError: (detail: string) => string;
+    readonly settingsIgnored: (path: string, detail: string) => string;
+};
+export declare const backTo: (origin?: Origin) => string;
+export declare const TUI: {
+    readonly subtitle: "AI-first dictionary";
+    readonly needsTerminal: "Giao diện b3dict cần chạy trong terminal. Muốn hỏi một lần: b3dict \"<câu hỏi>\"";
+    readonly setupHeading: "Setup";
+    readonly homeHeading: "Home";
+    readonly countFailed: (detail: string) => string;
+    readonly homeInstruction: "Hỏi về từ, thành ngữ, cách dùng. Trộn tiếng Việt và English đều được.";
+    readonly homeHintsEmpty: "gõ câu hỏi rồi enter · ↓ menu · esc thoát";
+    readonly homeHints: "enter hỏi · ↓ menu · esc xoá ô · ctrl+c thoát";
+    readonly homeMenuHints: "↑↓ chọn · enter mở · esc về ô gõ · q thoát";
+    readonly homeMenuTitle: "── hoặc chọn: ──";
+    readonly menuLabel: {
+        readonly history: "History ";
+        readonly wordbook: "Wordbook";
+        readonly model: "Model   ";
+        readonly help: "Help    ";
+    };
+    readonly listHeading: {
+        readonly history: "History";
+        readonly wordbook: "Wordbook";
+    };
+    readonly listCount: {
+        readonly history: (n: number) => string;
+        readonly wordbook: (n: number) => string;
+    };
+    readonly listEmpty: {
+        readonly history: "Chưa có lookup nào. Về home và gõ một câu hỏi.";
+        readonly wordbook: "Chưa lưu từ nào. Bấm s trên một đáp án để lưu ★.";
+    };
+    readonly listHints: {
+        readonly history: "↑↓ di chuyển · enter mở · s lưu/bỏ ★ · esc về home · q thoát";
+        readonly wordbook: "↑↓ di chuyển · enter mở · s bỏ lưu · esc về home · q thoát";
+    };
+    readonly listEmptyHints: "esc về home · q thoát";
+    readonly listFailed: (detail: string) => string;
+    readonly moreAbove: (n: number) => string;
+    readonly moreBelow: (n: number) => string;
+    readonly savedAgo: (age: string) => string;
+    readonly asking: (model: string) => string;
+    readonly askingHints: (backTo: string) => string;
+    readonly cached: "đáp án đã lưu từ trước";
+    readonly answerHints: (saved: boolean, backTo: string) => string;
+    readonly saveFailed: (detail: string) => string;
+    readonly failedHints: (backTo: string) => string;
+    readonly setupHints: "esc thoát";
+    readonly modelHeading: "Model";
+    readonly modelInstruction: "Model trả lời các câu hỏi sau. Đáp án đã lưu vẫn dùng lại; r để hỏi lại bằng model mới.";
+    readonly modelDefault: "mặc định";
+    readonly modelNotes: Record<string, string>;
+    readonly modelInUse: "✓ đang dùng";
+    readonly customRow: "Khác: gõ id model…";
+    readonly customExample: "Id trên OpenRouter, ví dụ z-ai/glm-4.6. Tên trần như gpt-5-nano là model của OpenAI.";
+    readonly customRejected: (model: string) => string;
+    readonly pinned: (model: string) => string;
+    readonly pickerHints: "↑↓ chọn · enter dùng · esc về home · q thoát";
+    readonly customHints: "enter dùng · esc huỷ";
+    readonly settingsSaveFailed: (detail: string) => string;
+    readonly helpHeading: "Help";
+    readonly helpHints: "esc về home · q thoát";
+    readonly isWord: "✓ từ có thật";
+    readonly notWord: "✗ không phải từ chuẩn";
+};
+export type HelpPaths = {
+    env: string;
+    settings: string;
+    db: string;
+};
+export type HelpSection = {
+    title: string;
+    rows: [string, string][];
+};
+export declare const helpSections: (paths: HelpPaths) => HelpSection[];
+export declare function configProblemText(problem: ConfigProblem, envPath: string): string;
+export declare function failureText(failure: Failure, config: Config, query: string): string;
+export declare function retryText(event: RetryEvent): string;