@justyork/repo-mind 0.3.0

package/dist/mcp/server.js

@@ -0,0 +1,155 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { getPackageVersion } from '../package-version.js';
+import { DocIndex } from '../index/doc-index.js';
+import { DOC_TYPES, DOC_STATUSES, DOC_DOMAINS } from '../index/types.js';
+import { exploreGraph } from '../tools/explore-graph.js';
+import { getDoc } from '../tools/get-doc.js';
+import { getGlossaryTerm } from '../tools/get-glossary-term.js';
+import { listDocs } from '../tools/list-docs.js';
+import { searchDocs } from '../tools/search-docs.js';
+const TOOL_NAMES = [
+    'list_docs',
+    'search_docs',
+    'get_doc',
+    'get_glossary_term',
+    'explore_graph',
+];
+function isToolName(name) {
+    return TOOL_NAMES.includes(name);
+}
+let acceptingCalls = true;
+export async function startMcpServer() {
+    const index = new DocIndex(process.cwd());
+    const server = new Server({ name: 'repo-mind', version: getPackageVersion() }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [
+            {
+                name: 'list_docs',
+                description: 'List project knowledge documents with optional filters.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        type: { type: 'string', enum: [...DOC_TYPES] },
+                        status: { type: 'string', enum: [...DOC_STATUSES] },
+                        tag: { type: 'string' },
+                        domain: { type: 'string', enum: [...DOC_DOMAINS] },
+                    },
+                },
+            },
+            {
+                name: 'search_docs',
+                description: 'Search project knowledge documents by query.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        query: { type: 'string' },
+                        type: { type: 'string', enum: [...DOC_TYPES] },
+                        domain: { type: 'string', enum: [...DOC_DOMAINS] },
+                    },
+                    required: ['query'],
+                },
+            },
+            {
+                name: 'get_doc',
+                description: 'Fetch a single document by slug.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        slug: { type: 'string' },
+                    },
+                    required: ['slug'],
+                },
+            },
+            {
+                name: 'get_glossary_term',
+                description: 'Resolve a glossary term by name.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        name: { type: 'string' },
+                    },
+                    required: ['name'],
+                },
+            },
+            {
+                name: 'explore_graph',
+                description: 'Explore related documents as a graph.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        slug: { type: 'string' },
+                        depth: { type: 'number' },
+                    },
+                    required: ['slug'],
+                },
+            },
+        ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        if (!acceptingCalls) {
+            throw new Error('Server is shutting down');
+        }
+        const args = (request.params.arguments ?? {});
+        const toolName = request.params.name;
+        if (!isToolName(toolName)) {
+            throw new Error(`Unknown tool: ${toolName}`);
+        }
+        switch (toolName) {
+            case 'list_docs':
+                return toolResult(listDocs(index, {
+                    type: typeof args.type === 'string' ? args.type : undefined,
+                    status: typeof args.status === 'string'
+                        ? args.status
+                        : undefined,
+                    tag: typeof args.tag === 'string' ? args.tag : undefined,
+                    domain: typeof args.domain === 'string'
+                        ? args.domain
+                        : undefined,
+                }));
+            case 'search_docs':
+                return toolResult(searchDocs(index, {
+                    query: typeof args.query === 'string' ? args.query : '',
+                    type: typeof args.type === 'string' ? args.type : undefined,
+                    domain: typeof args.domain === 'string'
+                        ? args.domain
+                        : undefined,
+                }));
+            case 'get_doc':
+                return toolResult(getDoc(index, typeof args.slug === 'string' ? args.slug : ''));
+            case 'get_glossary_term':
+                return toolResult(getGlossaryTerm(index, typeof args.name === 'string' ? args.name : ''));
+            case 'explore_graph':
+                return toolResult(exploreGraph(index, {
+                    slug: typeof args.slug === 'string' ? args.slug : '',
+                    depth: typeof args.depth === 'number' ? args.depth : undefined,
+                }));
+            default: {
+                const unknownTool = toolName;
+                throw new Error(`Unknown tool: ${unknownTool}`);
+            }
+        }
+    });
+    const shutdown = async () => {
+        acceptingCalls = false;
+        await server.close();
+        process.exit(0);
+    };
+    process.on('SIGTERM', () => {
+        void shutdown();
+    });
+    process.on('SIGINT', () => {
+        void shutdown();
+    });
+    process.stdin.on('close', () => {
+        void shutdown();
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+function toolResult(payload) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload) }],
+    };
+}

package/dist/package-version.d.ts

@@ -0,0 +1,2 @@
+/** Package version from repo-mind `package.json` (single source for UI + MCP). */
+export declare function getPackageVersion(): string;

package/dist/package-version.js

@@ -0,0 +1,15 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+let cachedVersion;
+/** Package version from repo-mind `package.json` (single source for UI + MCP). */
+export function getPackageVersion() {
+    if (cachedVersion) {
+        return cachedVersion;
+    }
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    const packageJsonPath = path.join(moduleDir, '..', 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    cachedVersion = typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+    return cachedVersion;
+}

package/dist/prepare/auto-links.d.ts

@@ -0,0 +1,22 @@
+import type { DocIndex } from '../index/doc-index.js';
+import type { DocRecord } from '../index/types.js';
+export interface SyncLinksOptions {
+    dryRun?: boolean;
+    /** Rewrite `[text](page.md)` as `[[slug]]` when the target resolves. */
+    convertMarkdownLinks?: boolean;
+    /** Merge outbound link slugs into frontmatter `related`. */
+    syncRelated?: boolean;
+}
+export interface SyncLinksFileResult {
+    relativePath: string;
+    convertedLinks: number;
+    addedRelated: string[];
+    changed: boolean;
+    skipped: boolean;
+    reason?: string;
+}
+export interface SyncLinksResult {
+    files: SyncLinksFileResult[];
+}
+export declare function syncDocLinks(index: DocIndex, doc: DocRecord, docs: DocRecord[], options?: SyncLinksOptions): SyncLinksFileResult;
+export declare function syncAllDocLinks(index: DocIndex, options?: SyncLinksOptions): SyncLinksResult;

package/dist/prepare/auto-links.js

@@ -0,0 +1,124 @@
+import fs from 'node:fs';
+import matter from 'gray-matter';
+import { parseWikilinkTargets, resolveWikilinkTarget } from '../index/link-index.js';
+import { slugForMarkdownHref } from '../index/resolve-md-href.js';
+const MARKDOWN_LINK_PATTERN = /\[([^\]]*)\]\(([^)]+)\)/g;
+function normalizeStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((item) => typeof item === 'string');
+}
+function buildSlugByRelative(docs) {
+    return new Map(docs.map((doc) => [doc.relativePath, doc.slug]));
+}
+function buildSlugLookups(docs) {
+    const slugSet = new Set(docs.map((doc) => doc.slug));
+    const titleToSlug = new Map();
+    for (const doc of docs) {
+        titleToSlug.set(doc.slug.toLowerCase(), doc.slug);
+        titleToSlug.set(doc.title.toLowerCase(), doc.slug);
+    }
+    return { slugSet, titleToSlug };
+}
+function collectOutboundSlugs(body, fromDoc, docs) {
+    const slugByRelative = buildSlugByRelative(docs);
+    const lookups = buildSlugLookups(docs);
+    const seen = new Set();
+    const result = [];
+    function addSlug(slug) {
+        if (!slug || slug === fromDoc.slug || seen.has(slug)) {
+            return;
+        }
+        seen.add(slug);
+        result.push(slug);
+    }
+    for (const raw of parseWikilinkTargets(body)) {
+        const resolved = resolveWikilinkTarget(raw, lookups);
+        addSlug(resolved.slug);
+    }
+    for (const match of body.matchAll(MARKDOWN_LINK_PATTERN)) {
+        const href = match[2]?.trim() ?? '';
+        addSlug(slugForMarkdownHref(fromDoc.relativePath, href, slugByRelative));
+    }
+    return result;
+}
+function convertMarkdownLinksToWikilinks(body, fromRelative, slugByRelative) {
+    let count = 0;
+    const nextBody = body.replace(MARKDOWN_LINK_PATTERN, (full, text, href) => {
+        const slug = slugForMarkdownHref(fromRelative, href.trim(), slugByRelative);
+        if (!slug) {
+            return full;
+        }
+        count += 1;
+        const label = text.trim();
+        if (!label || label.toLowerCase() === slug.toLowerCase()) {
+            return `[[${slug}]]`;
+        }
+        return `[[${label}|${slug}]]`;
+    });
+    return { body: nextBody, count };
+}
+export function syncDocLinks(index, doc, docs, options = {}) {
+    const convertMarkdownLinks = options.convertMarkdownLinks ?? true;
+    const syncRelated = options.syncRelated ?? true;
+    if (doc.contentKind !== 'markdown') {
+        return {
+            relativePath: doc.relativePath,
+            convertedLinks: 0,
+            addedRelated: [],
+            changed: false,
+            skipped: true,
+            reason: 'not markdown',
+        };
+    }
+    const raw = fs.readFileSync(doc.path, 'utf8');
+    const parsed = matter(raw);
+    const data = parsed.data;
+    let body = parsed.content;
+    const currentRelated = normalizeStringArray(data.related);
+    const slugByRelative = buildSlugByRelative(docs);
+    let convertedLinks = 0;
+    if (convertMarkdownLinks) {
+        const converted = convertMarkdownLinksToWikilinks(body, doc.relativePath, slugByRelative);
+        body = converted.body;
+        convertedLinks = converted.count;
+    }
+    const outbound = collectOutboundSlugs(body, doc, docs);
+    const relatedSet = new Set(currentRelated);
+    const addedRelated = [];
+    if (syncRelated) {
+        for (const slug of outbound) {
+            if (!relatedSet.has(slug)) {
+                relatedSet.add(slug);
+                addedRelated.push(slug);
+            }
+        }
+    }
+    const nextRelated = syncRelated ? [...relatedSet] : currentRelated;
+    const relatedChanged = syncRelated &&
+        (nextRelated.length !== currentRelated.length ||
+            nextRelated.some((slug, index) => slug !== currentRelated[index]));
+    const bodyChanged = convertedLinks > 0;
+    const changed = bodyChanged || relatedChanged;
+    if (changed && !options.dryRun) {
+        const frontmatter = {
+            ...data,
+            related: nextRelated,
+        };
+        fs.writeFileSync(doc.path, matter.stringify(body, frontmatter), 'utf8');
+        index.refresh();
+    }
+    return {
+        relativePath: doc.relativePath,
+        convertedLinks,
+        addedRelated,
+        changed,
+        skipped: false,
+    };
+}
+export function syncAllDocLinks(index, options = {}) {
+    const docs = index.refresh().filter((doc) => doc.contentKind === 'markdown');
+    const files = docs.map((doc) => syncDocLinks(index, doc, docs, options));
+    return { files };
+}

package/dist/prepare/prepare-docs.d.ts

@@ -0,0 +1,36 @@
+import type { DocIndex } from '../index/doc-index.js';
+import { type DocDomain, type DocStatus, type DocType } from '../index/types.js';
+export interface UnpreparedFile {
+    relativePath: string;
+    path: string;
+    suggestedType: DocType;
+    suggestedSlug: string;
+    suggestedTitle: string;
+}
+export interface PrepareOptions {
+    type?: DocType;
+    slug?: string;
+    title?: string;
+    status?: DocStatus;
+    domain?: DocDomain;
+}
+export interface PrepareResult {
+    path: string;
+    relativePath: string;
+    slug: string;
+    type: DocType;
+    domain: DocDomain;
+}
+export declare function listUnpreparedFiles(index: DocIndex): UnpreparedFile[];
+export declare function prepareDocFile(index: DocIndex, relativePath: string, options?: PrepareOptions): PrepareResult;
+export interface PrepareAllOptions extends PrepareOptions {
+    dryRun?: boolean;
+}
+export interface PrepareAllResult {
+    prepared: PrepareResult[];
+    skipped: Array<{
+        relativePath: string;
+        reason: string;
+    }>;
+}
+export declare function prepareAllDocs(index: DocIndex, options?: PrepareAllOptions): PrepareAllResult;

package/dist/prepare/prepare-docs.js

@@ -0,0 +1,106 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { inferTypeFromRelative, resolveDomain } from '../index/path-inference.js';
+import { isValidSlug, slugFromRelativePath } from '../index/slug.js';
+import { isDocType } from '../index/types.js';
+function titleFromSlug(slug) {
+    return slug.replace(/-/g, ' ').replace(/\b\w/g, (char) => char.toUpperCase());
+}
+export function listUnpreparedFiles(index) {
+    return index
+        .listUnprepared()
+        .filter((doc) => doc.contentKind === 'markdown')
+        .map((doc) => ({
+        relativePath: doc.relativePath,
+        path: doc.path,
+        suggestedType: doc.type,
+        suggestedSlug: doc.slug,
+        suggestedTitle: doc.title,
+    }));
+}
+export function prepareDocFile(index, relativePath, options = {}) {
+    const knowledgeRoot = index.getKnowledgeRoot();
+    if (!knowledgeRoot) {
+        throw new Error('no docs/ directory found');
+    }
+    const normalized = relativePath.replace(/\\/g, '/').replace(/^\.\//, '');
+    const absolutePath = path.resolve(knowledgeRoot, normalized);
+    const rootWithSep = knowledgeRoot.endsWith(path.sep)
+        ? knowledgeRoot
+        : `${knowledgeRoot}${path.sep}`;
+    if (!absolutePath.startsWith(rootWithSep) || !fs.existsSync(absolutePath)) {
+        throw new Error(`file not found: ${relativePath}`);
+    }
+    const raw = fs.readFileSync(absolutePath, 'utf8');
+    const parsed = matter(raw);
+    const data = parsed.data;
+    if (typeof data.type === 'string' && isDocType(data.type)) {
+        throw new Error(`file already prepared: ${relativePath}`);
+    }
+    const inferredType = options.type ?? inferTypeFromRelative(normalized);
+    const domain = options.domain ?? resolveDomain(normalized, data.domain);
+    const slug = options.slug ??
+        (typeof data.slug === 'string' && isValidSlug(data.slug)
+            ? data.slug
+            : slugFromRelativePath(normalized));
+    const title = options.title ??
+        (typeof data.title === 'string' ? data.title : titleFromSlug(slug));
+    const status = options.status ?? 'accepted';
+    const frontmatter = {
+        type: inferredType,
+        slug,
+        status,
+        domain,
+        title,
+        tags: Array.isArray(data.tags)
+            ? data.tags.filter((item) => typeof item === 'string')
+            : [],
+        related: Array.isArray(data.related)
+            ? data.related.filter((item) => typeof item === 'string')
+            : [],
+        updated: new Date().toISOString().slice(0, 10),
+    };
+    const markdown = matter.stringify(parsed.content, frontmatter);
+    fs.writeFileSync(absolutePath, markdown, 'utf8');
+    index.refresh();
+    return {
+        path: absolutePath,
+        relativePath: normalized,
+        slug,
+        type: inferredType,
+        domain,
+    };
+}
+export function prepareAllDocs(index, options = {}) {
+    const unprepared = listUnpreparedFiles(index);
+    const prepared = [];
+    const skipped = [];
+    for (const file of unprepared) {
+        if (options.dryRun) {
+            prepared.push({
+                path: file.path,
+                relativePath: file.relativePath,
+                slug: file.suggestedSlug,
+                type: file.suggestedType,
+                domain: resolveDomain(file.relativePath, undefined),
+            });
+            continue;
+        }
+        try {
+            prepared.push(prepareDocFile(index, file.relativePath, {
+                type: options.type,
+                slug: options.slug,
+                title: options.title,
+                status: options.status,
+            }));
+        }
+        catch (error) {
+            skipped.push({
+                relativePath: file.relativePath,
+                reason: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return { prepared, skipped };
+}

package/dist/tools/explore-graph.d.ts

@@ -0,0 +1,25 @@
+import type { DocIndex } from '../index/doc-index.js';
+import { type LinkIndexSnapshot } from '../index/link-index.js';
+import type { DocType } from '../index/types.js';
+export interface ExploreGraphInput {
+    slug: string;
+    depth?: number;
+}
+export interface ExploreGraphNode {
+    slug: string;
+    type: DocType;
+    title: string;
+}
+export interface ExploreGraphEdge {
+    from: string;
+    to: string;
+}
+export interface ExploreGraphResult {
+    nodes: ExploreGraphNode[];
+    edges: ExploreGraphEdge[];
+    maxDepthReached: number;
+    truncated: boolean;
+    broken_links: string[];
+}
+export declare function exploreGraph(index: DocIndex, input: ExploreGraphInput): ExploreGraphResult;
+export declare function buildLinkIndexForDocs(index: DocIndex): LinkIndexSnapshot;

package/dist/tools/explore-graph.js

@@ -0,0 +1,84 @@
+import { isValidSlug } from '../index/slug.js';
+import { buildLinkIndex, getOutboundSlugs, } from '../index/link-index.js';
+import { buildDocsTree, collectParentOfEdges } from '../ui/fs-tree.js';
+function buildSnapshot(index) {
+    const docs = index.refresh();
+    const tree = buildDocsTree(index);
+    return buildLinkIndex(docs, collectParentOfEdges(tree));
+}
+export function exploreGraph(index, input) {
+    const empty = {
+        nodes: [],
+        edges: [],
+        maxDepthReached: 0,
+        truncated: false,
+        broken_links: [],
+    };
+    if (!index.getKnowledgeRoot()) {
+        return empty;
+    }
+    if (!isValidSlug(input.slug)) {
+        return empty;
+    }
+    const rootDoc = index.getDocBySlug(input.slug);
+    if (!rootDoc) {
+        return empty;
+    }
+    let maxDepth = input.depth ?? 3;
+    if (maxDepth <= 0) {
+        maxDepth = 1;
+    }
+    const linkIndex = buildSnapshot(index);
+    const nodes = new Map();
+    const edges = [];
+    const brokenLinks = new Set(linkIndex.brokenTargets);
+    const visited = new Set();
+    let maxDepthReached = 0;
+    let truncated = false;
+    const queue = [{ slug: rootDoc.slug, depth: 0 }];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (!current || visited.has(current.slug)) {
+            continue;
+        }
+        visited.add(current.slug);
+        const doc = index.getDocBySlug(current.slug);
+        if (!doc) {
+            continue;
+        }
+        nodes.set(doc.slug, {
+            slug: doc.slug,
+            type: doc.type,
+            title: doc.title,
+        });
+        maxDepthReached = Math.max(maxDepthReached, current.depth);
+        const outbound = getOutboundSlugs(linkIndex, doc.slug);
+        if (current.depth + 1 >= maxDepth) {
+            if (outbound.length > 0) {
+                truncated = true;
+            }
+            continue;
+        }
+        for (const targetSlug of outbound) {
+            edges.push({ from: doc.slug, to: targetSlug });
+            const targetDoc = index.getDocBySlug(targetSlug);
+            if (!targetDoc) {
+                brokenLinks.add(targetSlug);
+                continue;
+            }
+            if (!visited.has(targetSlug)) {
+                queue.push({ slug: targetSlug, depth: current.depth + 1 });
+            }
+        }
+    }
+    return {
+        nodes: [...nodes.values()],
+        edges,
+        maxDepthReached,
+        truncated,
+        broken_links: [...brokenLinks],
+    };
+}
+export function buildLinkIndexForDocs(index) {
+    return buildSnapshot(index);
+}

package/dist/tools/get-doc.d.ts

@@ -0,0 +1,11 @@
+import type { DocIndex } from '../index/doc-index.js';
+import type { DocFrontmatter } from '../index/types.js';
+export interface GetDocResult {
+    found: boolean;
+    slug?: string;
+    path?: string;
+    contentKind?: 'markdown' | 'yaml' | 'json';
+    frontmatter?: DocFrontmatter;
+    body?: string;
+}
+export declare function getDoc(index: DocIndex, slug: string): GetDocResult;

package/dist/tools/get-doc.js

@@ -0,0 +1,21 @@
+import { isValidSlug } from '../index/slug.js';
+export function getDoc(index, slug) {
+    if (!index.getKnowledgeRoot()) {
+        return { found: false };
+    }
+    if (!isValidSlug(slug)) {
+        return { found: false };
+    }
+    const doc = index.getDocBySlug(slug);
+    if (!doc) {
+        return { found: false };
+    }
+    return {
+        found: true,
+        slug: doc.slug,
+        path: doc.path,
+        contentKind: doc.contentKind,
+        frontmatter: doc.frontmatter,
+        body: doc.body,
+    };
+}

package/dist/tools/get-glossary-term.d.ts

@@ -0,0 +1,9 @@
+import type { DocIndex } from '../index/doc-index.js';
+export interface GetGlossaryTermResult {
+    found: boolean;
+    slug?: string;
+    definition?: string;
+    related?: string[];
+    suggestions?: string[];
+}
+export declare function getGlossaryTerm(index: DocIndex, name: string): GetGlossaryTermResult;

package/dist/tools/get-glossary-term.js

@@ -0,0 +1,41 @@
+import { firstParagraph } from '../index/doc-index.js';
+import { searchDocs } from './search-docs.js';
+function substringMatch(name, slug, title) {
+    const needle = name.toLowerCase();
+    return slug.toLowerCase().includes(needle) || title.toLowerCase().includes(needle);
+}
+export function getGlossaryTerm(index, name) {
+    if (!index.getKnowledgeRoot()) {
+        return { found: false };
+    }
+    const trimmed = name.trim();
+    if (!trimmed) {
+        return { found: false, suggestions: [] };
+    }
+    const glossaryDocs = index.getDocsByType('glossary-term');
+    const exact = glossaryDocs.find((doc) => doc.slug.toLowerCase() === trimmed.toLowerCase());
+    if (exact) {
+        return {
+            found: true,
+            slug: exact.slug,
+            definition: firstParagraph(exact.body),
+            related: exact.related,
+        };
+    }
+    const substringHits = glossaryDocs.filter((doc) => substringMatch(trimmed, doc.slug, doc.title));
+    if (substringHits.length === 1) {
+        const hit = substringHits[0];
+        return {
+            found: true,
+            slug: hit.slug,
+            definition: firstParagraph(hit.body),
+            related: hit.related,
+        };
+    }
+    const ranked = searchDocs(index, { query: trimmed, type: 'glossary-term' });
+    const suggestions = ranked.slice(0, 3).map((result) => result.slug);
+    return {
+        found: false,
+        suggestions,
+    };
+}

package/dist/tools/list-docs.d.ts

@@ -0,0 +1,19 @@
+import type { DocIndex } from '../index/doc-index.js';
+import type { DocRecord, DocStatus, DocType, DocDomain } from '../index/types.js';
+export interface ListDocsInput {
+    type?: DocType;
+    status?: DocStatus;
+    tag?: string;
+    domain?: DocDomain;
+}
+export interface ListDocsItem {
+    slug: string;
+    type: DocType;
+    domain: DocDomain;
+    title: string;
+    status: DocStatus;
+    relativePath: string;
+    contentKind: DocRecord['contentKind'];
+}
+export declare function listDocs(index: DocIndex, input?: ListDocsInput): ListDocsItem[];
+export declare function getDocRecord(index: DocIndex, slug: string): DocRecord | null;