@justyork/repo-mind 0.3.0

package/dist/commands/setup.js

@@ -0,0 +1,84 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+const NPM_PACKAGE_NAME = '@justyork/repo-mind';
+const MCP_SERVER_NAME = 'repo-mind';
+const CLAUDE_SNIPPET = '\n<!-- repo-mind -->\nProject knowledge lives in `docs/`. Use repo-mind MCP (`search_docs`, `get_doc`, `get_glossary_term`) — the same files humans edit in `repo-mind ui`.\n<!-- /repo-mind -->\n';
+export function runSetup(options = {}) {
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    const setupCursor = options.cursor ?? !options.claude;
+    const setupClaude = options.claude ?? !options.cursor;
+    const actions = [];
+    if (setupCursor) {
+        const cursorPath = resolveCursorConfigPath(cwd);
+        mergeMcpConfig(cursorPath, options.force ?? false);
+        actions.push(`Cursor MCP config: ${cursorPath}`);
+    }
+    if (setupClaude) {
+        const claudePath = path.join(os.homedir(), '.claude.json');
+        mergeClaudeConfig(claudePath, options.force ?? false);
+        actions.push(`Claude Code MCP config: ${claudePath}`);
+    }
+    const claudeMdPath = path.join(cwd, 'CLAUDE.md');
+    appendClaudeSnippet(claudeMdPath);
+    actions.push(`CLAUDE.md snippet: ${claudeMdPath}`);
+    for (const action of actions) {
+        console.log(action);
+    }
+    return 0;
+}
+function resolveCursorConfigPath(cwd) {
+    const projectConfig = path.join(cwd, '.cursor', 'mcp.json');
+    if (fs.existsSync(path.dirname(projectConfig))) {
+        return projectConfig;
+    }
+    return path.join(os.homedir(), '.cursor', 'mcp.json');
+}
+function mergeMcpConfig(configPath, force) {
+    const config = readJson(configPath);
+    config.mcpServers ??= {};
+    if (config.mcpServers[MCP_SERVER_NAME] && !force) {
+        console.warn(`warning: ${MCP_SERVER_NAME} already configured in ${configPath} (use --force to replace)`);
+        return;
+    }
+    config.mcpServers[MCP_SERVER_NAME] = {
+        command: 'npx',
+        args: ['-y', NPM_PACKAGE_NAME, 'mcp'],
+    };
+    writeJson(configPath, config);
+}
+function mergeClaudeConfig(configPath, force) {
+    const config = readJson(configPath);
+    config.mcpServers ??= {};
+    if (config.mcpServers[MCP_SERVER_NAME] && !force) {
+        console.warn(`warning: ${MCP_SERVER_NAME} already configured in ${configPath} (use --force to replace)`);
+        return;
+    }
+    config.mcpServers[MCP_SERVER_NAME] = {
+        command: 'npx',
+        args: ['-y', NPM_PACKAGE_NAME, 'mcp'],
+    };
+    writeJson(configPath, config);
+}
+function appendClaudeSnippet(claudeMdPath) {
+    if (fs.existsSync(claudeMdPath)) {
+        const existing = fs.readFileSync(claudeMdPath, 'utf8');
+        if (existing.includes('<!-- repo-mind -->')) {
+            return;
+        }
+        fs.appendFileSync(claudeMdPath, CLAUDE_SNIPPET, 'utf8');
+        return;
+    }
+    fs.writeFileSync(claudeMdPath, `# CLAUDE.md${CLAUDE_SNIPPET}`, 'utf8');
+}
+function readJson(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return {};
+    }
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+function writeJson(filePath, value) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+export { CLAUDE_SNIPPET, MCP_SERVER_NAME, NPM_PACKAGE_NAME };

package/dist/commands/sync-links.d.ts

@@ -0,0 +1,7 @@
+export interface SyncLinksCommandOptions {
+    cwd?: string;
+    dryRun?: boolean;
+    convertBody?: boolean;
+    syncRelated?: boolean;
+}
+export declare function runSyncLinks(options?: SyncLinksCommandOptions): number;

package/dist/commands/sync-links.js

@@ -0,0 +1,41 @@
+import path from 'node:path';
+import { DocIndex } from '../index/doc-index.js';
+import { syncAllDocLinks } from '../prepare/auto-links.js';
+function printSyncLinksResult(result, dryRun) {
+    const verb = dryRun ? 'Would update' : 'Updated';
+    let changedCount = 0;
+    for (const file of result.files) {
+        if (file.skipped) {
+            continue;
+        }
+        if (!file.changed) {
+            continue;
+        }
+        changedCount += 1;
+        const parts = [];
+        if (file.convertedLinks > 0) {
+            parts.push(`${file.convertedLinks} markdown link(s) → wikilink`);
+        }
+        if (file.addedRelated.length > 0) {
+            parts.push(`related +${file.addedRelated.join(', ')}`);
+        }
+        console.log(`${verb}: ${file.relativePath}${parts.length > 0 ? ` (${parts.join('; ')})` : ''}`);
+    }
+    const unchanged = result.files.filter((file) => !file.skipped && !file.changed).length;
+    console.log(`${verb} ${changedCount} file(s), ${unchanged} unchanged`);
+}
+export function runSyncLinks(options = {}) {
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    const index = new DocIndex(cwd);
+    if (!index.getKnowledgeRoot()) {
+        console.error('no docs/ found — run `repo-mind init` or create a docs/ directory');
+        return 1;
+    }
+    const result = syncAllDocLinks(index, {
+        dryRun: options.dryRun,
+        convertMarkdownLinks: options.convertBody ?? true,
+        syncRelated: options.syncRelated ?? true,
+    });
+    printSyncLinksResult(result, options.dryRun === true);
+    return 0;
+}

package/dist/commands/ui.d.ts

@@ -0,0 +1,5 @@
+export interface UiCommandOptions {
+    cwd?: string;
+    port?: number;
+}
+export declare function runUi(options?: UiCommandOptions): Promise<number>;

package/dist/commands/ui.js

@@ -0,0 +1,83 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { DocIndex } from '../index/doc-index.js';
+import { closeAllDocsEventStreams } from '../ui/api-handlers.js';
+import { DocsWatcher } from '../ui/docs-watcher.js';
+import { openDraftsDb } from '../ui/db/drafts-db.js';
+import { destroyUiServerConnections, resolveUiStaticDir, startUiServer } from '../ui/server.js';
+export async function runUi(options = {}) {
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    const port = options.port ?? 3847;
+    const index = new DocIndex(cwd);
+    if (!index.getKnowledgeRoot()) {
+        console.error('no docs/ found — run `repo-mind init` or create a docs/ directory');
+        return 1;
+    }
+    const staticDir = resolveUiStaticDir();
+    const indexHtml = path.join(staticDir, 'index.html');
+    if (!fs.existsSync(indexHtml)) {
+        console.warn('warning: ui/dist not found — run `npm run build:ui` in the repo-mind package');
+    }
+    try {
+        const draftsDb = openDraftsDb(index.getKnowledgeRoot());
+        const docsWatcher = new DocsWatcher(index);
+        docsWatcher.start(index.getKnowledgeRoot());
+        const server = await startUiServer({
+            host: '127.0.0.1',
+            port,
+            index,
+            staticDir,
+            draftsDb,
+            docsWatcher,
+        });
+        const docCount = index.refresh().length;
+        const draftCount = draftsDb.listActive().length;
+        console.log(`RepoMind UI at http://127.0.0.1:${port} (${docCount} docs, ${draftCount} drafts)`);
+        console.log('Press Ctrl+C to stop');
+        await new Promise((resolve) => {
+            let shuttingDown = false;
+            const finishShutdown = () => {
+                closeAllDocsEventStreams();
+                destroyUiServerConnections(server);
+                try {
+                    draftsDb.close();
+                }
+                catch {
+                    // ignore close errors during shutdown
+                }
+                server.close(() => {
+                    resolve();
+                });
+            };
+            const shutdown = () => {
+                if (shuttingDown) {
+                    console.log('\nForce exit.');
+                    process.exit(1);
+                    return;
+                }
+                shuttingDown = true;
+                console.log('\nShutting down...');
+                const forceTimer = setTimeout(() => {
+                    finishShutdown();
+                }, 2_000);
+                forceTimer.unref();
+                void docsWatcher.stop().finally(() => {
+                    clearTimeout(forceTimer);
+                    finishShutdown();
+                });
+            };
+            process.on('SIGINT', shutdown);
+            process.on('SIGTERM', shutdown);
+        });
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes('EADDRINUSE')) {
+            console.error(`port ${port} is in use — try --port <other>`);
+            return 1;
+        }
+        console.error(message);
+        return 1;
+    }
+}

package/dist/index/asset-file.d.ts

@@ -0,0 +1,4 @@
+export declare const IMAGE_EXTENSIONS: readonly [".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg"];
+export declare function isImageFileName(name: string): boolean;
+export declare function mimeTypeForImagePath(relativePath: string): string | null;
+export declare function assetApiPath(relativePath: string): string;

package/dist/index/asset-file.js

@@ -0,0 +1,26 @@
+export const IMAGE_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg'];
+const IMAGE_MIME_TYPES = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+};
+export function isImageFileName(name) {
+    const lower = name.toLowerCase();
+    return IMAGE_EXTENSIONS.some((ext) => lower.endsWith(ext));
+}
+export function mimeTypeForImagePath(relativePath) {
+    const lower = relativePath.toLowerCase();
+    for (const ext of IMAGE_EXTENSIONS) {
+        if (lower.endsWith(ext)) {
+            return IMAGE_MIME_TYPES[ext] ?? null;
+        }
+    }
+    return null;
+}
+export function assetApiPath(relativePath) {
+    const normalized = relativePath.replace(/\\/g, '/').replace(/^\/+/, '');
+    return `/api/assets/${normalized.split('/').map(encodeURIComponent).join('/')}`;
+}

package/dist/index/doc-index.d.ts

@@ -0,0 +1,21 @@
+import { type DocRecord, type DocType } from './types.js';
+/** Primary project knowledge directory — single source of truth for humans and agents. */
+export declare const KNOWLEDGE_DIR = "docs";
+export declare function discoverKnowledgeRoot(startDir: string): string | null;
+export declare function listKnowledgeFiles(knowledgeRoot: string): string[];
+export declare function listMarkdownFiles(knowledgeRoot: string): string[];
+export declare class DocIndex {
+    private readonly startDir;
+    private knowledgeRoot;
+    private readonly cache;
+    constructor(startDir?: string);
+    getKnowledgeRoot(): string | null;
+    rediscover(): void;
+    refresh(): DocRecord[];
+    getDocs(): DocRecord[];
+    getDocBySlug(slug: string): DocRecord | null;
+    getDocByRelativePath(relativePath: string): DocRecord | null;
+    getDocsByType(type: DocType): DocRecord[];
+    listUnprepared(): DocRecord[];
+}
+export declare function firstParagraph(body: string): string;

package/dist/index/doc-index.js

@@ -0,0 +1,231 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import fg from 'fast-glob';
+import matter from 'gray-matter';
+import { contentKindFromRelativePath } from './knowledge-file.js';
+import { inferTypeFromRelative, resolveDomain } from './path-inference.js';
+import { isValidSlug, slugFromRelativePath } from './slug.js';
+import { isDocStatus, isDocType, } from './types.js';
+/** Primary project knowledge directory — single source of truth for humans and agents. */
+export const KNOWLEDGE_DIR = 'docs';
+const GLOB_IGNORE = ['**/.repo-mind/**', '**/.worktrees/**'];
+export function discoverKnowledgeRoot(startDir) {
+    let current = path.resolve(startDir);
+    while (true) {
+        const candidate = path.join(current, KNOWLEDGE_DIR);
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
+            return candidate;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}
+function normalizeStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((item) => typeof item === 'string');
+}
+function inferSlug(relative, data, inferredType) {
+    if (typeof data.slug === 'string' && isValidSlug(data.slug)) {
+        return data.slug;
+    }
+    const basename = path.basename(relative).replace(/\.(md|ya?ml|json)$/i, '');
+    if (inferredType !== 'wiki-page' && isValidSlug(basename)) {
+        return basename;
+    }
+    return slugFromRelativePath(relative);
+}
+function titleFromBasename(basename) {
+    return basename
+        .replace(/[-_]/g, ' ')
+        .replace(/\b\w/g, (char) => char.toUpperCase());
+}
+function buildFrontmatter(relativeNorm, data, type, slug, status, title) {
+    return {
+        type,
+        slug,
+        status,
+        domain: resolveDomain(relativeNorm, data.domain),
+        title,
+        tags: normalizeStringArray(data.tags),
+        related: normalizeStringArray(data.related),
+        owner: typeof data.owner === 'string' ? data.owner : undefined,
+        updated: typeof data.updated === 'string' ? data.updated : undefined,
+    };
+}
+function parseStructuredFile(filePath, knowledgeRoot, contentKind) {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const relative = path.relative(knowledgeRoot, filePath).replace(/\\/g, '/');
+    const inferredType = inferTypeFromRelative(relative);
+    const slug = slugFromRelativePath(relative);
+    const basename = path.basename(relative).replace(/\.(ya?ml|json)$/i, '');
+    const title = titleFromBasename(basename);
+    const domain = resolveDomain(relative, undefined);
+    const frontmatter = {
+        type: inferredType,
+        slug,
+        status: 'accepted',
+        domain,
+        title,
+        tags: [],
+        related: [],
+    };
+    return {
+        path: filePath,
+        relativePath: relative,
+        slug,
+        type: inferredType,
+        domain,
+        status: 'accepted',
+        title,
+        tags: [],
+        related: [],
+        body: raw,
+        frontmatter,
+        prepared: false,
+        contentKind,
+    };
+}
+function parseKnowledgeFile(filePath, knowledgeRoot) {
+    const relative = path.relative(knowledgeRoot, filePath).replace(/\\/g, '/');
+    const contentKind = contentKindFromRelativePath(relative);
+    if (contentKind === 'markdown') {
+        return parseDoc(filePath, knowledgeRoot);
+    }
+    if (contentKind === 'yaml' || contentKind === 'json') {
+        return parseStructuredFile(filePath, knowledgeRoot, contentKind);
+    }
+    const _exhaustive = contentKind;
+    return _exhaustive;
+}
+function parseDoc(filePath, knowledgeRoot) {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const parsed = matter(raw);
+    const data = parsed.data;
+    const relative = path.relative(knowledgeRoot, filePath);
+    const relativeNorm = relative.replace(/\\/g, '/');
+    const inferredType = inferTypeFromRelative(relativeNorm);
+    const type = isDocType(data.type) ? data.type : inferredType;
+    const slug = inferSlug(relativeNorm, data, type);
+    const status = isDocStatus(data.status) ? data.status : 'accepted';
+    const title = typeof data.title === 'string'
+        ? data.title
+        : slug.replace(/-/g, ' ').replace(/\b\w/g, (char) => char.toUpperCase());
+    const prepared = typeof data.type === 'string' && isDocType(data.type);
+    const frontmatter = buildFrontmatter(relativeNorm, data, type, slug, status, title);
+    return {
+        path: filePath,
+        relativePath: relativeNorm,
+        slug,
+        type,
+        domain: frontmatter.domain ?? resolveDomain(relativeNorm, undefined),
+        status,
+        title,
+        tags: frontmatter.tags ?? [],
+        related: frontmatter.related ?? [],
+        body: parsed.content.trim(),
+        frontmatter,
+        prepared,
+        contentKind: 'markdown',
+    };
+}
+export function listKnowledgeFiles(knowledgeRoot) {
+    const pattern = path.join(knowledgeRoot, '**/*.{md,yml,yaml,json}').replace(/\\/g, '/');
+    return fg.sync(pattern, {
+        absolute: true,
+        onlyFiles: true,
+        ignore: GLOB_IGNORE,
+    });
+}
+export function listMarkdownFiles(knowledgeRoot) {
+    const pattern = path.join(knowledgeRoot, '**/*.md').replace(/\\/g, '/');
+    return fg.sync(pattern, {
+        absolute: true,
+        onlyFiles: true,
+        ignore: GLOB_IGNORE,
+    });
+}
+export class DocIndex {
+    startDir;
+    knowledgeRoot;
+    cache = new Map();
+    constructor(startDir = process.cwd()) {
+        this.startDir = path.resolve(startDir);
+        this.knowledgeRoot = discoverKnowledgeRoot(this.startDir);
+    }
+    getKnowledgeRoot() {
+        return this.knowledgeRoot;
+    }
+    rediscover() {
+        this.knowledgeRoot = discoverKnowledgeRoot(this.startDir);
+        this.cache.clear();
+    }
+    refresh() {
+        if (!this.knowledgeRoot) {
+            this.cache.clear();
+            return [];
+        }
+        const files = listKnowledgeFiles(this.knowledgeRoot);
+        const seen = new Set();
+        for (const filePath of files) {
+            seen.add(filePath);
+            const stat = fs.statSync(filePath);
+            const cached = this.cache.get(filePath);
+            if (cached && cached.mtimeMs === stat.mtimeMs) {
+                continue;
+            }
+            const record = parseKnowledgeFile(filePath, this.knowledgeRoot);
+            if (record) {
+                this.cache.set(filePath, { mtimeMs: stat.mtimeMs, record });
+            }
+            else {
+                this.cache.delete(filePath);
+            }
+        }
+        for (const filePath of [...this.cache.keys()]) {
+            if (!seen.has(filePath)) {
+                this.cache.delete(filePath);
+            }
+        }
+        return this.getDocs();
+    }
+    getDocs() {
+        return [...this.cache.values()].map((entry) => entry.record);
+    }
+    getDocBySlug(slug) {
+        this.refresh();
+        const matches = this.getDocs().filter((doc) => doc.slug === slug);
+        if (matches.length !== 1) {
+            return null;
+        }
+        return matches[0] ?? null;
+    }
+    getDocByRelativePath(relativePath) {
+        this.refresh();
+        const normalized = relativePath.replace(/\\/g, '/').replace(/^\/+/, '');
+        const matches = this.getDocs().filter((doc) => doc.relativePath === normalized);
+        if (matches.length !== 1) {
+            return null;
+        }
+        return matches[0] ?? null;
+    }
+    getDocsByType(type) {
+        this.refresh();
+        return this.getDocs().filter((doc) => doc.type === type);
+    }
+    listUnprepared() {
+        this.refresh();
+        return this.getDocs().filter((doc) => !doc.prepared);
+    }
+}
+export function firstParagraph(body) {
+    const paragraphs = body
+        .split(/\n\s*\n/)
+        .map((paragraph) => paragraph.trim())
+        .filter(Boolean);
+    return paragraphs[0] ?? '';
+}

package/dist/index/knowledge-file.d.ts

@@ -0,0 +1,4 @@
+export type ContentKind = 'markdown' | 'yaml' | 'json';
+export declare function isKnowledgeFileName(name: string): boolean;
+export declare function contentKindFromRelativePath(relativePath: string): ContentKind;
+export declare function stripKnowledgeExtension(relativePath: string): string;

package/dist/index/knowledge-file.js

@@ -0,0 +1,17 @@
+const KNOWLEDGE_FILE_PATTERN = /\.(md|ya?ml|json)$/i;
+export function isKnowledgeFileName(name) {
+    return KNOWLEDGE_FILE_PATTERN.test(name);
+}
+export function contentKindFromRelativePath(relativePath) {
+    const lower = relativePath.toLowerCase();
+    if (lower.endsWith('.json')) {
+        return 'json';
+    }
+    if (lower.endsWith('.yaml') || lower.endsWith('.yml')) {
+        return 'yaml';
+    }
+    return 'markdown';
+}
+export function stripKnowledgeExtension(relativePath) {
+    return relativePath.replace(/\\/g, '/').replace(/\.(md|ya?ml|json)$/i, '');
+}

package/dist/index/link-index.d.ts

@@ -0,0 +1,41 @@
+import type { DocRecord } from './types.js';
+export type LinkKind = 'related' | 'wikilink' | 'parent_of';
+export interface LinkEdge {
+    from: string;
+    to: string;
+    kind: LinkKind;
+    /** Unresolved wikilink target when `to` is not a known slug. */
+    rawTarget?: string;
+}
+export interface BacklinkEntry {
+    from: string;
+    kind: LinkKind;
+}
+export interface LinkIndexSnapshot {
+    edges: LinkEdge[];
+    backlinks: Map<string, BacklinkEntry[]>;
+    brokenTargets: Set<string>;
+}
+export declare function parseWikilinkTargets(body: string): string[];
+interface SlugLookups {
+    slugSet: Set<string>;
+    titleToSlug: Map<string, string>;
+}
+export declare function resolveWikilinkTarget(raw: string, lookups: SlugLookups): {
+    slug: string | null;
+    broken: boolean;
+};
+export declare function buildLinkIndex(docs: DocRecord[], extraEdges?: LinkEdge[]): LinkIndexSnapshot;
+export declare function getOutboundSlugs(snapshot: LinkIndexSnapshot, fromSlug: string): string[];
+export interface LinkHealthSummary {
+    orphanSlugs: string[];
+    brokenTargets: string[];
+    oneWayCount: number;
+}
+export declare function computeLinkHealth(snapshot: LinkIndexSnapshot, docs: DocRecord[]): LinkHealthSummary;
+export declare function getBacklinksForSlug(snapshot: LinkIndexSnapshot, slug: string, docsBySlug: Map<string, DocRecord>): Array<{
+    slug: string;
+    title: string;
+    kind: BacklinkEntry['kind'];
+}>;
+export {};