@justyork/repo-mind 0.8.1 → 0.9.0

package/README.md

@@ -45,7 +45,7 @@ Then ask your agent a project question — it should call `search_docs` / `get_d
 | `repo-mind check` | Validate frontmatter schema and `related:` links |
 | `repo-mind prepare` | Add frontmatter to legacy markdown (`--all` for batch) |
 | `repo-mind sync-links` | Convert markdown links to wikilinks; sync `related:` |
-| `repo-mind export` | Write `agents.md` to repo root |
+| `repo-mind export` | Write `agents-export.md` flat dump to repo root |
 | `repo-mind publish` | Publish active drafts to `docs/`; `--pr` opens a GitHub pull request |
 | `repo-mind mcp` | Start the MCP stdio server |
 | `repo-mind ui` | Confluence-style workspace over `docs/` (127.0.0.1:3847) |
@@ -64,17 +64,44 @@ Confluence-style workspace over **`docs/`**:
 npm run build
 repo-mind ui              # http://127.0.0.1:3847
 repo-mind ui --port 4000 --cwd /path/to/project
+
+# Local development (uses this repo's dist/, includes latest .env loader):
+npm run ui
+node dist/cli.js ui
 ```
 
+`repo-mind ui` loads `REPOMIND_*` variables from the nearest `.env` (starting at cwd and the docs project root). If you installed `@justyork/repo-mind` globally, run `npm link` in this repo after `npm run build` so `repo-mind ui` uses the local build.
+
 - **Catalog tree** — docs by domain (`Product`, `Technical`, …) and type
 - **Prepare** — recursively find markdown without frontmatter; add schema in one click
 - **Drafts + Publish** — SQLite drafts, publish to `docs/*.md`
-- **Health** — schema check, publish queue, export `agents.md`
+- **Health** — schema check, publish queue, export `agents-export.md`
 - **Graph** — full-page view at `/graph.html`
+- **Ask** — documentation assistant (BYOK): floating chat button, natural-language Q&A with source links
 - **Theme** — light (default) / dark toggle
 
 Binds **127.0.0.1** only. MCP reads published files in `docs/` only (not SQLite drafts).
 
+### Ask assistant (BYOK)
+
+Click the **chat icon** in the bottom-right corner to open the documentation assistant. Answers are grounded in published `docs/` via the same retrieval path as MCP (`search_docs` → `get_doc`). Each answer includes links to source pages (`?slug=`).
+
+Configure your provider API key in **Ask → Settings** (stored in browser `localStorage` only) or set a team default:
+
+Or set a team default in project `.env` (loaded automatically by `repo-mind ui`):
+
+```bash
+REPOMIND_ASK_API_KEY=sk-...
+REPOMIND_ASK_PROVIDER=openai
+REPOMIND_UI_PASSWORD=your-password
+```
+
+| Variable | Description |
+|----------|-------------|
+| `REPOMIND_ASK_API_KEY` | Optional server default API key |
+| `REPOMIND_ASK_PROVIDER` | `openai` (default) or `anthropic` |
+| `REPOMIND_ASK_MODEL` | Override model (default: `gpt-4o-mini` / `claude-3-5-haiku-latest`) |
+
 ## MCP tools
 
 - `list_docs` — filter by type, status, tag

package/dist/ask/ask.d.ts

@@ -0,0 +1,7 @@
+import type { DocIndex } from '../index/doc-index.js';
+import type { AskRequest, AskResponse, CompleteAskFn } from './types.js';
+export interface AskDocsOptions {
+    completeFn?: CompleteAskFn;
+}
+/** Answers a documentation question using retrieval + optional LLM synthesis. */
+export declare function askDocs(index: DocIndex, input: AskRequest, options?: AskDocsOptions): Promise<AskResponse>;

package/dist/ask/ask.js

@@ -0,0 +1,68 @@
+import { resolveAskApiKey } from './config.js';
+import { ensureCitations } from './citations.js';
+import { completeAsk, defaultModelForProvider, resolveAskProvider, } from './llm.js';
+import { buildAskSystemPrompt, buildAskUserPrompt } from './prompt.js';
+import { retrieveAskContext } from './retrieve.js';
+import { buildAskGreetingReply, buildAskNotFoundReply } from './suggestions.js';
+import { isAskSmallTalk } from './small-talk.js';
+const MAX_HISTORY_TURNS = 6;
+function resolveProvider(requestProvider) {
+    if (requestProvider) {
+        return requestProvider;
+    }
+    return resolveAskProvider(process.env.REPOMIND_ASK_PROVIDER);
+}
+function resolveModel(provider, requestModel) {
+    const trimmed = requestModel?.trim();
+    if (trimmed) {
+        return trimmed;
+    }
+    const fromEnv = process.env.REPOMIND_ASK_MODEL?.trim();
+    if (fromEnv) {
+        return fromEnv;
+    }
+    return defaultModelForProvider(provider);
+}
+function buildAskMessages(question, sources, history) {
+    const messages = [{ role: 'system', content: buildAskSystemPrompt(sources.length > 0) }];
+    for (const turn of (history ?? []).slice(-MAX_HISTORY_TURNS)) {
+        messages.push({ role: turn.role, content: turn.content });
+    }
+    messages.push({ role: 'user', content: buildAskUserPrompt(question, sources) });
+    return messages;
+}
+/** Answers a documentation question using retrieval + optional LLM synthesis. */
+export async function askDocs(index, input, options = {}) {
+    const question = input.question?.trim() ?? '';
+    if (!question) {
+        throw new Error('question is required');
+    }
+    const apiKey = resolveAskApiKey(input.apiKey);
+    if (!apiKey) {
+        throw new Error('API key is required — set it in Ask settings or REPOMIND_ASK_API_KEY');
+    }
+    const sources = retrieveAskContext(index, question);
+    if (sources.length === 0 && isAskSmallTalk(question)) {
+        return {
+            answer: buildAskGreetingReply(index, question),
+            sources: [],
+            notFound: false,
+        };
+    }
+    if (sources.length === 0) {
+        return {
+            answer: buildAskNotFoundReply(index, question),
+            sources: [],
+            notFound: true,
+        };
+    }
+    const provider = resolveProvider(input.provider);
+    const model = resolveModel(provider, input.model);
+    const completeFn = options.completeFn ?? completeAsk;
+    const rawAnswer = await completeFn(provider, apiKey, model, buildAskMessages(question, sources, input.history));
+    return {
+        answer: sources.length > 0 ? ensureCitations(rawAnswer, sources) : rawAnswer,
+        sources,
+        notFound: sources.length === 0,
+    };
+}

package/dist/ask/citations.d.ts

@@ -0,0 +1,6 @@
+import type { AskSource } from './types.js';
+/** Extracts slug values from markdown links using ?slug= query params. */
+export declare function extractCitedSlugs(markdown: string): string[];
+export declare function hasCitationForSources(answer: string, sources: AskSource[]): boolean;
+export declare function appendSourcesBlock(answer: string, sources: AskSource[]): string;
+export declare function ensureCitations(answer: string, sources: AskSource[]): string;

package/dist/ask/citations.js

@@ -0,0 +1,40 @@
+const SLUG_LINK_PATTERN = /\?slug=([^)\s"&]+)/gi;
+/** Extracts slug values from markdown links using ?slug= query params. */
+export function extractCitedSlugs(markdown) {
+    const slugs = new Set();
+    for (const match of markdown.matchAll(SLUG_LINK_PATTERN)) {
+        const raw = match[1];
+        if (!raw) {
+            continue;
+        }
+        try {
+            slugs.add(decodeURIComponent(raw));
+        }
+        catch {
+            slugs.add(raw);
+        }
+    }
+    return [...slugs];
+}
+export function hasCitationForSources(answer, sources) {
+    if (sources.length === 0) {
+        return true;
+    }
+    const cited = new Set(extractCitedSlugs(answer));
+    return sources.some((source) => cited.has(source.slug));
+}
+export function appendSourcesBlock(answer, sources) {
+    if (sources.length === 0) {
+        return answer;
+    }
+    const trimmed = answer.trimEnd();
+    const links = sources.map((source) => `- [${source.title}](?slug=${encodeURIComponent(source.slug)})`);
+    const block = ['', '## Sources', '', ...links].join('\n');
+    return `${trimmed}${block}`;
+}
+export function ensureCitations(answer, sources) {
+    if (hasCitationForSources(answer, sources)) {
+        return answer;
+    }
+    return appendSourcesBlock(answer, sources);
+}

package/dist/ask/config.d.ts

@@ -0,0 +1,9 @@
+import type { LlmProvider } from './types.js';
+export interface AskServerConfig {
+    serverConfigured: boolean;
+    provider: LlmProvider;
+    model: string;
+}
+/** Public ask config for the UI (never exposes the API key). */
+export declare function getAskServerConfig(): AskServerConfig;
+export declare function resolveAskApiKey(requestKey: string | undefined): string | null;

package/dist/ask/config.js

@@ -0,0 +1,19 @@
+import { defaultModelForProvider, resolveAskProvider } from './llm.js';
+/** Public ask config for the UI (never exposes the API key). */
+export function getAskServerConfig() {
+    const provider = resolveAskProvider(process.env.REPOMIND_ASK_PROVIDER);
+    const envModel = process.env.REPOMIND_ASK_MODEL?.trim();
+    return {
+        serverConfigured: Boolean(process.env.REPOMIND_ASK_API_KEY?.trim()),
+        provider,
+        model: envModel || defaultModelForProvider(provider),
+    };
+}
+export function resolveAskApiKey(requestKey) {
+    const fromEnv = process.env.REPOMIND_ASK_API_KEY?.trim();
+    if (fromEnv) {
+        return fromEnv;
+    }
+    const fromRequest = requestKey?.trim();
+    return fromRequest || null;
+}

package/dist/ask/llm.d.ts

@@ -0,0 +1,8 @@
+import type { CompleteAskFn, LlmMessage, LlmProvider } from './types.js';
+export declare const DEFAULT_OPENAI_MODEL = "gpt-4o-mini";
+export declare const DEFAULT_ANTHROPIC_MODEL = "claude-3-5-haiku-latest";
+export declare function defaultModelForProvider(provider: LlmProvider): string;
+export declare function resolveAskProvider(value: string | undefined): LlmProvider;
+export declare function callOpenAi(apiKey: string, model: string, messages: LlmMessage[]): Promise<string>;
+export declare function callAnthropic(apiKey: string, model: string, messages: LlmMessage[]): Promise<string>;
+export declare const completeAsk: CompleteAskFn;

package/dist/ask/llm.js

@@ -0,0 +1,110 @@
+const OPENAI_URL = 'https://api.openai.com/v1/chat/completions';
+const ANTHROPIC_URL = 'https://api.anthropic.com/v1/messages';
+const ANTHROPIC_VERSION = '2023-06-01';
+export const DEFAULT_OPENAI_MODEL = 'gpt-4o-mini';
+export const DEFAULT_ANTHROPIC_MODEL = 'claude-3-5-haiku-latest';
+export function defaultModelForProvider(provider) {
+    switch (provider) {
+        case 'openai':
+            return DEFAULT_OPENAI_MODEL;
+        case 'anthropic':
+            return DEFAULT_ANTHROPIC_MODEL;
+        default: {
+            const _exhaustive = provider;
+            return _exhaustive;
+        }
+    }
+}
+export function resolveAskProvider(value) {
+    if (value === 'anthropic') {
+        return 'anthropic';
+    }
+    return 'openai';
+}
+async function readApiError(res) {
+    try {
+        const body = (await res.json());
+        if (typeof body.error === 'string') {
+            return body.error;
+        }
+        if (body.error && typeof body.error.message === 'string') {
+            return body.error.message;
+        }
+    }
+    catch {
+        // ignore parse errors
+    }
+    return `HTTP ${res.status}`;
+}
+export async function callOpenAi(apiKey, model, messages) {
+    const res = await fetch(OPENAI_URL, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            model,
+            messages,
+            temperature: 0.4,
+        }),
+    });
+    if (!res.ok) {
+        throw new Error(`OpenAI API error: ${await readApiError(res)}`);
+    }
+    const data = (await res.json());
+    const content = data.choices?.[0]?.message?.content?.trim();
+    if (!content) {
+        throw new Error('OpenAI API returned an empty response');
+    }
+    return content;
+}
+export async function callAnthropic(apiKey, model, messages) {
+    const system = messages.find((message) => message.role === 'system')?.content ?? '';
+    const chatMessages = messages
+        .filter((message) => message.role !== 'system')
+        .map((message) => ({
+        role: message.role === 'assistant' ? 'assistant' : 'user',
+        content: message.content,
+    }));
+    const res = await fetch(ANTHROPIC_URL, {
+        method: 'POST',
+        headers: {
+            'x-api-key': apiKey,
+            'anthropic-version': ANTHROPIC_VERSION,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            model,
+            max_tokens: 2048,
+            system,
+            messages: chatMessages,
+            temperature: 0.4,
+        }),
+    });
+    if (!res.ok) {
+        throw new Error(`Anthropic API error: ${await readApiError(res)}`);
+    }
+    const data = (await res.json());
+    const text = data.content
+        ?.filter((block) => block.type === 'text')
+        .map((block) => block.text ?? '')
+        .join('')
+        .trim();
+    if (!text) {
+        throw new Error('Anthropic API returned an empty response');
+    }
+    return text;
+}
+export const completeAsk = async (provider, apiKey, model, messages) => {
+    switch (provider) {
+        case 'openai':
+            return callOpenAi(apiKey, model, messages);
+        case 'anthropic':
+            return callAnthropic(apiKey, model, messages);
+        default: {
+            const _exhaustive = provider;
+            return _exhaustive;
+        }
+    }
+};

package/dist/ask/prompt.d.ts

@@ -0,0 +1,5 @@
+import type { AskSource } from './types.js';
+export declare const NOT_FOUND_ANSWER_RU = "\u041D\u0435 \u043D\u0430\u0448\u0451\u043B \u0432 \u0434\u043E\u043A\u0443\u043C\u0435\u043D\u0442\u0430\u0446\u0438\u0438.";
+export declare const NOT_FOUND_ANSWER_EN = "Not found in the documentation.";
+export declare function buildAskSystemPrompt(hasSources: boolean): string;
+export declare function buildAskUserPrompt(question: string, sources: AskSource[]): string;

package/dist/ask/prompt.js

@@ -0,0 +1,39 @@
+export const NOT_FOUND_ANSWER_RU = 'Не нашёл в документации.';
+export const NOT_FOUND_ANSWER_EN = 'Not found in the documentation.';
+export function buildAskSystemPrompt(hasSources) {
+    const lines = [
+        'You are a helpful documentation assistant for RepoMind.',
+        'Answer in a clear, conversational tone.',
+        'Reply in the same language as the user question.',
+    ];
+    if (hasSources) {
+        lines.push('Use ONLY the provided source excerpts to answer documentation questions.', 'Synthesize a helpful explanation for the user — do not dump raw excerpts or bullet lists of sources without explanation.', 'If the sources do not contain enough information, say clearly that you could not find it in the documentation.', 'Always cite sources inline using markdown links: [Page Title](?slug=slug-name).', 'Use the exact slug from each source block.', 'Do not invent facts, APIs, or pages that are not in the sources.');
+    }
+    else {
+        lines.push('No documentation excerpts were retrieved for this message.', 'If the user is greeting you or making small talk, reply briefly and explain that you can answer questions about the project documentation in docs/.', 'If they asked a documentation question, say you could not find relevant pages and suggest more specific keywords.', 'Do not invent documentation content.');
+    }
+    return lines.join(' ');
+}
+export function buildAskUserPrompt(question, sources) {
+    if (sources.length === 0) {
+        return [
+            '## Sources',
+            '',
+            '_No matching documentation pages were retrieved._',
+            '',
+            '## Question',
+            '',
+            question.trim(),
+        ].join('\n');
+    }
+    const blocks = sources.map((source) => `### ${source.title} (slug: ${source.slug})\n\n${source.excerpt}`);
+    return [
+        '## Sources',
+        '',
+        blocks.join('\n\n---\n\n'),
+        '',
+        '## Question',
+        '',
+        question.trim(),
+    ].join('\n');
+}

package/dist/ask/retrieve.d.ts

@@ -0,0 +1,4 @@
+import type { DocIndex } from '../index/doc-index.js';
+import type { AskSource } from './types.js';
+/** Retrieves top matching published docs for an ask question. */
+export declare function retrieveAskContext(index: DocIndex, question: string): AskSource[];

package/dist/ask/retrieve.js

@@ -0,0 +1,38 @@
+import { getDoc } from '../tools/get-doc.js';
+import { searchDocsForAsk } from './search.js';
+const TOP_N = 5;
+const EXCERPT_CHARS = 1200;
+function excerpt(body, maxChars = EXCERPT_CHARS) {
+    const trimmed = body.trim();
+    if (trimmed.length <= maxChars) {
+        return trimmed;
+    }
+    return `${trimmed.slice(0, maxChars)}…`;
+}
+function titleFromDoc(slug, frontmatter) {
+    if (typeof frontmatter?.title === 'string' && frontmatter.title.trim()) {
+        return frontmatter.title.trim();
+    }
+    return slug;
+}
+/** Retrieves top matching published docs for an ask question. */
+export function retrieveAskContext(index, question) {
+    const query = question.trim();
+    if (!query) {
+        return [];
+    }
+    const hits = searchDocsForAsk(index, query);
+    const sources = [];
+    for (const hit of hits.slice(0, TOP_N)) {
+        const doc = getDoc(index, hit.slug);
+        if (!doc.found || !doc.body) {
+            continue;
+        }
+        sources.push({
+            slug: hit.slug,
+            title: titleFromDoc(hit.slug, doc.frontmatter),
+            excerpt: excerpt(doc.body),
+        });
+    }
+    return sources;
+}

package/dist/ask/search.d.ts

@@ -0,0 +1,7 @@
+import type { DocIndex } from '../index/doc-index.js';
+import { type SearchDocsResult } from '../tools/search-docs.js';
+/** Extracts meaningful search terms from a natural-language question. */
+export declare function extractAskSearchTerms(question: string): string[];
+export declare function searchDocsWithOrTerms(index: DocIndex, terms: string[]): SearchDocsResult[];
+/** Relaxed search tuned for natural-language ask questions. */
+export declare function searchDocsForAsk(index: DocIndex, question: string): SearchDocsResult[];

package/dist/ask/search.js

@@ -0,0 +1,232 @@
+import { searchDocs } from '../tools/search-docs.js';
+const STOP_WORDS = new Set([
+    'a',
+    'an',
+    'the',
+    'is',
+    'are',
+    'was',
+    'were',
+    'be',
+    'been',
+    'being',
+    'what',
+    'how',
+    'why',
+    'when',
+    'where',
+    'who',
+    'which',
+    'do',
+    'does',
+    'did',
+    'can',
+    'could',
+    'should',
+    'would',
+    'will',
+    'to',
+    'of',
+    'in',
+    'on',
+    'at',
+    'for',
+    'and',
+    'or',
+    'but',
+    'not',
+    'with',
+    'about',
+    'from',
+    'into',
+    'me',
+    'my',
+    'i',
+    'you',
+    'your',
+    'we',
+    'our',
+    'it',
+    'its',
+    'this',
+    'that',
+    'these',
+    'those',
+    'there',
+    'tell',
+    'please',
+    'explain',
+    'describe',
+    'как',
+    'что',
+    'где',
+    'когда',
+    'почему',
+    'кто',
+    'какой',
+    'какая',
+    'какие',
+    'какое',
+    'каков',
+    'какова',
+    'каково',
+    'это',
+    'этот',
+    'эта',
+    'эти',
+    'тот',
+    'та',
+    'те',
+    'в',
+    'во',
+    'на',
+    'с',
+    'со',
+    'по',
+    'для',
+    'из',
+    'у',
+    'о',
+    'об',
+    'от',
+    'до',
+    'при',
+    'про',
+    'над',
+    'под',
+    'и',
+    'или',
+    'не',
+    'ни',
+    'ли',
+    'же',
+    'бы',
+    'мне',
+    'меня',
+    'мой',
+    'моя',
+    'мои',
+    'твой',
+    'твоя',
+    'твои',
+    'наш',
+    'наша',
+    'наши',
+    'расскажи',
+    'рассказать',
+    'объясни',
+    'объяснить',
+    'покажи',
+    'показать',
+    'найди',
+    'найти',
+    'есть',
+    'быть',
+    'был',
+    'была',
+    'были',
+]);
+const TERM_PATTERN = /[a-z0-9\u0400-\u04ff]+/gi;
+function uniqueTerms(terms) {
+    const seen = new Set();
+    const result = [];
+    for (const term of terms) {
+        const normalized = term.toLowerCase();
+        if (!normalized || seen.has(normalized)) {
+            continue;
+        }
+        seen.add(normalized);
+        result.push(normalized);
+    }
+    return result;
+}
+/** Extracts meaningful search terms from a natural-language question. */
+export function extractAskSearchTerms(question) {
+    const raw = question.match(TERM_PATTERN) ?? [];
+    const meaningful = raw.filter((term) => term.length >= 3 && !STOP_WORDS.has(term.toLowerCase()));
+    if (meaningful.length > 0) {
+        return uniqueTerms(meaningful);
+    }
+    return uniqueTerms(raw.filter((term) => term.length >= 2 && !STOP_WORDS.has(term.toLowerCase())));
+}
+function scoreDocForTerms(doc, terms) {
+    const titleLower = doc.title.toLowerCase();
+    const bodyLower = doc.body.toLowerCase();
+    const tagsLower = doc.tags.map((tag) => tag.toLowerCase());
+    let score = 0;
+    let matches = 0;
+    for (const term of terms) {
+        let termScore = 0;
+        if (tagsLower.some((tag) => tag.includes(term))) {
+            termScore = 3;
+        }
+        if (titleLower.includes(term)) {
+            termScore = Math.max(termScore, 2);
+        }
+        if (bodyLower.includes(term)) {
+            termScore = Math.max(termScore, 1);
+        }
+        if (termScore > 0) {
+            matches += 1;
+            score += termScore;
+        }
+    }
+    if (matches === 0) {
+        return null;
+    }
+    if (matches === terms.length) {
+        score += 2;
+    }
+    return score;
+}
+export function searchDocsWithOrTerms(index, terms) {
+    if (terms.length === 0) {
+        return [];
+    }
+    const docs = index.refresh();
+    const results = [];
+    for (const doc of docs) {
+        const score = scoreDocForTerms(doc, terms);
+        if (score === null) {
+            continue;
+        }
+        const snippetSource = terms.find((term) => doc.body.toLowerCase().includes(term)) ?? terms[0];
+        const lowerBody = doc.body.toLowerCase();
+        const indexOf = lowerBody.indexOf(snippetSource);
+        const snippet = indexOf >= 0
+            ? doc.body
+                .slice(Math.max(0, indexOf - 40), Math.min(doc.body.length, indexOf + snippetSource.length + 40))
+                .replace(/\s+/g, ' ')
+                .trim()
+            : doc.body.slice(0, 120).replace(/\s+/g, ' ').trim();
+        results.push({
+            slug: doc.slug,
+            title: doc.title,
+            snippet,
+            score,
+        });
+    }
+    return results
+        .sort((a, b) => b.score - a.score || a.slug.localeCompare(b.slug))
+        .slice(0, 20);
+}
+/** Relaxed search tuned for natural-language ask questions. */
+export function searchDocsForAsk(index, question) {
+    const trimmed = question.trim();
+    if (!trimmed) {
+        return [];
+    }
+    const strict = searchDocs(index, { query: trimmed });
+    if (strict.length > 0) {
+        return strict;
+    }
+    const terms = extractAskSearchTerms(trimmed);
+    if (terms.length === 0) {
+        return [];
+    }
+    const andQuery = searchDocs(index, { query: terms.join(' ') });
+    if (andQuery.length > 0) {
+        return andQuery;
+    }
+    return searchDocsWithOrTerms(index, terms);
+}

package/dist/ask/small-talk.d.ts

@@ -0,0 +1,2 @@
+/** Detects short greetings or small talk that should not trigger doc-not-found. */
+export declare function isAskSmallTalk(question: string): boolean;