@justyork/repo-mind 0.3.0

package/dist/tools/list-docs.js

@@ -0,0 +1,35 @@
+export function listDocs(index, input = {}) {
+    const root = index.getKnowledgeRoot();
+    if (!root) {
+        return [];
+    }
+    let docs = index.refresh();
+    if (input.type) {
+        docs = docs.filter((doc) => doc.type === input.type);
+    }
+    if (input.status) {
+        docs = docs.filter((doc) => doc.status === input.status);
+    }
+    if (input.tag) {
+        const tagLower = input.tag.toLowerCase();
+        docs = docs.filter((doc) => doc.tags.some((tag) => tag.toLowerCase() === tagLower));
+    }
+    if (input.domain) {
+        docs = docs.filter((doc) => doc.domain === input.domain);
+    }
+    return docs.map((doc) => ({
+        slug: doc.slug,
+        type: doc.type,
+        domain: doc.domain,
+        title: doc.title,
+        status: doc.status,
+        relativePath: doc.relativePath,
+        contentKind: doc.contentKind,
+    }));
+}
+export function getDocRecord(index, slug) {
+    if (!index.getKnowledgeRoot()) {
+        return null;
+    }
+    return index.getDocBySlug(slug);
+}

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

@@ -0,0 +1,14 @@
+import type { DocIndex } from '../index/doc-index.js';
+import type { DocType, DocDomain } from '../index/types.js';
+export interface SearchDocsInput {
+    query: string;
+    type?: DocType;
+    domain?: DocDomain;
+}
+export interface SearchDocsResult {
+    slug: string;
+    title: string;
+    snippet: string;
+    score: number;
+}
+export declare function searchDocs(index: DocIndex, input: SearchDocsInput): SearchDocsResult[];

package/dist/tools/search-docs.js

@@ -0,0 +1,80 @@
+function tokenize(query) {
+    return query
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean)
+        .map((term) => term.toLowerCase());
+}
+function haystack(doc) {
+    return `${doc.title}\n${doc.tags.join(' ')}\n${doc.body}`.toLowerCase();
+}
+function scoreDoc(doc, terms) {
+    const titleLower = doc.title.toLowerCase();
+    const bodyLower = doc.body.toLowerCase();
+    const tagsLower = doc.tags.map((tag) => tag.toLowerCase());
+    for (const term of terms) {
+        const inTitle = titleLower.includes(term);
+        const inBody = bodyLower.includes(term);
+        const inTags = tagsLower.some((tag) => tag.includes(term));
+        if (!inTitle && !inBody && !inTags) {
+            return null;
+        }
+    }
+    let score = 0;
+    for (const term of terms) {
+        if (tagsLower.some((tag) => tag.includes(term))) {
+            score += 3;
+        }
+        if (titleLower.includes(term)) {
+            score += 2;
+        }
+        if (bodyLower.includes(term)) {
+            score += 1;
+        }
+    }
+    return score;
+}
+function makeSnippet(body, terms) {
+    const lowerBody = body.toLowerCase();
+    for (const term of terms) {
+        const index = lowerBody.indexOf(term);
+        if (index >= 0) {
+            const start = Math.max(0, index - 40);
+            const end = Math.min(body.length, index + term.length + 40);
+            return body.slice(start, end).replace(/\s+/g, ' ').trim();
+        }
+    }
+    return body.slice(0, 120).replace(/\s+/g, ' ').trim();
+}
+export function searchDocs(index, input) {
+    if (!index.getKnowledgeRoot()) {
+        return [];
+    }
+    const terms = tokenize(input.query);
+    if (terms.length === 0) {
+        return [];
+    }
+    let docs = index.refresh();
+    if (input.type) {
+        docs = docs.filter((doc) => doc.type === input.type);
+    }
+    if (input.domain) {
+        docs = docs.filter((doc) => doc.domain === input.domain);
+    }
+    const results = [];
+    for (const doc of docs) {
+        const score = scoreDoc(doc, terms);
+        if (score === null) {
+            continue;
+        }
+        results.push({
+            slug: doc.slug,
+            title: doc.title,
+            snippet: makeSnippet(doc.body, terms),
+            score,
+        });
+    }
+    return results
+        .sort((a, b) => b.score - a.score || a.slug.localeCompare(b.slug))
+        .slice(0, 20);
+}

package/dist/ui/api-handlers.d.ts

@@ -0,0 +1,12 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { DocIndex } from '../index/doc-index.js';
+import type { DocsWatcher } from './docs-watcher.js';
+export interface ApiResponse {
+    status: number;
+    body: unknown;
+}
+export declare function handleApiRequest(index: DocIndex, req: IncomingMessage, pathname: string, searchParams: URLSearchParams): ApiResponse;
+export declare function routeApi(index: DocIndex, req: IncomingMessage): ApiResponse | null;
+/** Closes live SSE streams so `server.close()` can finish during shutdown. */
+export declare function closeAllDocsEventStreams(): void;
+export declare function handleDocsEvents(req: IncomingMessage, res: ServerResponse, docsWatcher: DocsWatcher | undefined): void;

package/dist/ui/api-handlers.js

@@ -0,0 +1,223 @@
+import { URL } from 'node:url';
+import { collectCheckReport } from '../check/collect-violations.js';
+import { getPackageVersion } from '../package-version.js';
+import { computeLinkHealth, getBacklinksForSlug, } from '../index/link-index.js';
+import { isValidSlug } from '../index/slug.js';
+import { isDocStatus, isDocType } from '../index/types.js';
+import { listUnpreparedFiles } from '../prepare/prepare-docs.js';
+import { buildLinkIndexForDocs, 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';
+import { ALL_GRAPH_SLUG, exploreGraphAll } from './graph-all.js';
+import { buildDocsTree } from './fs-tree.js';
+import { readCatalogMeta } from './catalog-meta.js';
+import { computeKnowledgeStats } from './stats.js';
+import { listPageTemplates } from './templates.js';
+function jsonError(status, message) {
+    return { status, body: { error: message } };
+}
+function parseRequestUrl(req, baseUrl) {
+    const host = req.headers.host ?? '127.0.0.1';
+    return new URL(req.url ?? '/', `http://${host}${baseUrl}`);
+}
+export function handleApiRequest(index, req, pathname, searchParams) {
+    if (pathname === '/api/health') {
+        const docs = index.refresh();
+        return {
+            status: 200,
+            body: {
+                ok: true,
+                version: getPackageVersion(),
+                knowledgeRoot: index.getKnowledgeRoot(),
+                docCount: docs.length,
+            },
+        };
+    }
+    if (pathname === '/api/docs') {
+        const typeParam = searchParams.get('type');
+        const statusParam = searchParams.get('status');
+        const tag = searchParams.get('tag') ?? undefined;
+        if (typeParam && !isDocType(typeParam)) {
+            return jsonError(400, `invalid type: ${typeParam}`);
+        }
+        if (statusParam && !isDocStatus(statusParam)) {
+            return jsonError(400, `invalid status: ${statusParam}`);
+        }
+        return {
+            status: 200,
+            body: {
+                docs: listDocs(index, {
+                    type: typeParam && isDocType(typeParam) ? typeParam : undefined,
+                    status: statusParam && isDocStatus(statusParam) ? statusParam : undefined,
+                    tag,
+                }),
+            },
+        };
+    }
+    if (pathname === '/api/search') {
+        const query = searchParams.get('q') ?? '';
+        if (!query.trim()) {
+            return jsonError(400, 'query parameter q is required');
+        }
+        const typeParam = searchParams.get('type');
+        if (typeParam && !isDocType(typeParam)) {
+            return jsonError(400, `invalid type: ${typeParam}`);
+        }
+        return {
+            status: 200,
+            body: {
+                results: searchDocs(index, {
+                    query,
+                    type: typeParam && isDocType(typeParam) ? typeParam : undefined,
+                }),
+            },
+        };
+    }
+    if (pathname === '/api/stats') {
+        return { status: 200, body: computeKnowledgeStats(index) };
+    }
+    if (pathname === '/api/check') {
+        const report = collectCheckReport(index);
+        if (!report) {
+            return jsonError(404, 'no docs/ directory found');
+        }
+        return { status: 200, body: report };
+    }
+    if (pathname === '/api/tree') {
+        const tree = buildDocsTree(index);
+        if (!tree) {
+            return jsonError(404, 'no docs/ directory found');
+        }
+        return { status: 200, body: { tree, catalogMeta: readCatalogMeta(index.getKnowledgeRoot()) } };
+    }
+    if (pathname === '/api/templates') {
+        return { status: 200, body: { templates: listPageTemplates() } };
+    }
+    if (pathname === '/api/link-health') {
+        const docs = index.refresh();
+        const snapshot = buildLinkIndexForDocs(index);
+        const health = computeLinkHealth(snapshot, docs);
+        return {
+            status: 200,
+            body: {
+                orphanCount: health.orphanSlugs.length,
+                orphanSlugs: health.orphanSlugs,
+                brokenCount: health.brokenTargets.length,
+                brokenTargets: health.brokenTargets,
+                oneWayCount: health.oneWayCount,
+            },
+        };
+    }
+    const backlinksMatch = pathname.match(/^\/api\/backlinks\/([^/]+)$/);
+    if (backlinksMatch) {
+        const slug = decodeURIComponent(backlinksMatch[1] ?? '');
+        if (!isValidSlug(slug)) {
+            return jsonError(400, `invalid slug: ${slug}`);
+        }
+        const docs = index.refresh();
+        const docsBySlug = new Map(docs.map((doc) => [doc.slug, doc]));
+        if (!docsBySlug.has(slug)) {
+            return jsonError(404, `unknown slug: ${slug}`);
+        }
+        const snapshot = buildLinkIndexForDocs(index);
+        return {
+            status: 200,
+            body: {
+                slug,
+                backlinks: getBacklinksForSlug(snapshot, slug, docsBySlug),
+            },
+        };
+    }
+    if (pathname === '/api/unprepared') {
+        return { status: 200, body: { files: listUnpreparedFiles(index) } };
+    }
+    const graphMatch = pathname.match(/^\/api\/graph\/([^/]+)$/);
+    if (graphMatch) {
+        const slug = decodeURIComponent(graphMatch[1] ?? '');
+        if (slug === ALL_GRAPH_SLUG) {
+            return { status: 200, body: exploreGraphAll(index) };
+        }
+        if (!isValidSlug(slug)) {
+            return jsonError(400, `invalid slug: ${slug}`);
+        }
+        const depthParam = searchParams.get('depth');
+        const depth = depthParam ? Number.parseInt(depthParam, 10) : undefined;
+        return {
+            status: 200,
+            body: exploreGraph(index, { slug, depth }),
+        };
+    }
+    const docMatch = pathname.match(/^\/api\/docs\/([^/]+)$/);
+    if (docMatch) {
+        const slug = decodeURIComponent(docMatch[1] ?? '');
+        if (!isValidSlug(slug)) {
+            return jsonError(400, `invalid slug: ${slug}`);
+        }
+        const doc = index.getDocBySlug(slug);
+        if (!doc) {
+            return { status: 404, body: { found: false } };
+        }
+        const agentShape = doc.type === 'glossary-term'
+            ? getGlossaryTerm(index, slug)
+            : getDoc(index, slug);
+        return {
+            status: 200,
+            body: {
+                found: true,
+                slug: doc.slug,
+                path: doc.path,
+                contentKind: doc.contentKind,
+                frontmatter: doc.frontmatter,
+                body: doc.body,
+                agentShape,
+            },
+        };
+    }
+    return jsonError(404, 'not found');
+}
+export function routeApi(index, req) {
+    const url = parseRequestUrl(req, '');
+    if (!url.pathname.startsWith('/api/')) {
+        return null;
+    }
+    return handleApiRequest(index, req, url.pathname, url.searchParams);
+}
+const docsEventClients = new Set();
+/** Closes live SSE streams so `server.close()` can finish during shutdown. */
+export function closeAllDocsEventStreams() {
+    for (const res of docsEventClients) {
+        if (!res.writableEnded) {
+            res.end();
+        }
+    }
+    docsEventClients.clear();
+}
+export function handleDocsEvents(req, res, docsWatcher) {
+    if ((req.method ?? 'GET') !== 'GET') {
+        res.writeHead(405, { 'Content-Type': 'application/json; charset=utf-8' });
+        res.end(JSON.stringify({ error: 'method not allowed' }));
+        return;
+    }
+    if (!docsWatcher) {
+        res.writeHead(503, { 'Content-Type': 'application/json; charset=utf-8' });
+        res.end(JSON.stringify({ error: 'docs watcher unavailable' }));
+        return;
+    }
+    res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        Connection: 'keep-alive',
+    });
+    const sendRevision = (revision) => {
+        res.write(`data: ${JSON.stringify({ revision })}\n\n`);
+    };
+    sendRevision(docsWatcher.getRevision());
+    const unsubscribe = docsWatcher.subscribe(sendRevision);
+    docsEventClients.add(res);
+    req.on('close', () => {
+        unsubscribe();
+        docsEventClients.delete(res);
+    });
+}

package/dist/ui/catalog-meta.d.ts

@@ -0,0 +1,4 @@
+export type CatalogMetaMap = Record<string, string>;
+export declare function readCatalogMeta(knowledgeRoot: string): CatalogMetaMap;
+export declare function writeCatalogEmoji(knowledgeRoot: string, folderPath: string, emoji: string): CatalogMetaMap;
+export declare function catalogEmoji(meta: CatalogMetaMap, folderPath: string): string | null;

package/dist/ui/catalog-meta.js

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { normalizeRelativePath } from './safe-path.js';
+const META_FILE = 'catalog-meta.json';
+function metaPath(knowledgeRoot) {
+    return path.join(knowledgeRoot, '.repo-mind', META_FILE);
+}
+export function readCatalogMeta(knowledgeRoot) {
+    const filePath = metaPath(knowledgeRoot);
+    if (!fs.existsSync(filePath)) {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            return {};
+        }
+        const result = {};
+        for (const [key, value] of Object.entries(parsed)) {
+            if (typeof value === 'string') {
+                result[normalizeRelativePath(key)] = value;
+            }
+        }
+        return result;
+    }
+    catch {
+        return {};
+    }
+}
+export function writeCatalogEmoji(knowledgeRoot, folderPath, emoji) {
+    const key = normalizeRelativePath(folderPath);
+    const meta = readCatalogMeta(knowledgeRoot);
+    const trimmed = emoji.trim();
+    if (!trimmed) {
+        delete meta[key];
+    }
+    else {
+        meta[key] = trimmed.slice(0, 8);
+    }
+    const dir = path.join(knowledgeRoot, '.repo-mind');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(metaPath(knowledgeRoot), `${JSON.stringify(meta, null, 2)}\n`, 'utf8');
+    return meta;
+}
+export function catalogEmoji(meta, folderPath) {
+    return meta[normalizeRelativePath(folderPath)] ?? null;
+}

package/dist/ui/db/drafts-db.d.ts

@@ -0,0 +1,49 @@
+import type { DocType, DocStatus } from '../../index/types.js';
+export interface DraftRow {
+    id: string;
+    slug: string;
+    type: DocType;
+    status: DocStatus;
+    title: string;
+    body: string;
+    tags: string[];
+    related: string[];
+    published_path: string | null;
+    forked_from: string | null;
+    target_path: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface CreateDraftInput {
+    slug: string;
+    type: DocType;
+    title?: string;
+    body?: string;
+    tags?: string[];
+    related?: string[];
+    forked_from?: string | null;
+    target_path?: string | null;
+}
+export interface UpdateDraftInput {
+    slug?: string;
+    type?: DocType;
+    status?: DocStatus;
+    title?: string;
+    body?: string;
+    tags?: string[];
+    related?: string[];
+}
+export declare class DraftsDb {
+    private readonly db;
+    constructor(knowledgeRoot: string);
+    private ensureTargetPathColumn;
+    close(): void;
+    listActive(): DraftRow[];
+    getById(id: string): DraftRow | null;
+    getActiveBySlug(slug: string): DraftRow | null;
+    create(input: CreateDraftInput): DraftRow;
+    update(id: string, input: UpdateDraftInput): DraftRow;
+    delete(id: string): boolean;
+    markPublished(id: string, gitPath: string): DraftRow;
+}
+export declare function openDraftsDb(knowledgeRoot: string): DraftsDb;

package/dist/ui/db/drafts-db.js

@@ -0,0 +1,179 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import Database from 'better-sqlite3';
+import { randomUUID } from 'node:crypto';
+import { isDocStatus, isDocType } from '../../index/types.js';
+const SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS drafts (
+  id TEXT PRIMARY KEY,
+  slug TEXT NOT NULL,
+  type TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'draft',
+  title TEXT NOT NULL DEFAULT '',
+  body TEXT NOT NULL DEFAULT '',
+  tags_json TEXT NOT NULL DEFAULT '[]',
+  related_json TEXT NOT NULL DEFAULT '[]',
+  published_path TEXT,
+  forked_from TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_drafts_active_slug ON drafts(slug) WHERE published_path IS NULL;
+CREATE TABLE IF NOT EXISTS publish_log (
+  id TEXT PRIMARY KEY,
+  draft_id TEXT NOT NULL,
+  git_path TEXT NOT NULL,
+  published_at TEXT NOT NULL
+);
+`;
+function rowToDraft(row) {
+    return {
+        id: String(row.id),
+        slug: String(row.slug),
+        type: row.type,
+        status: row.status,
+        title: String(row.title),
+        body: String(row.body),
+        tags: JSON.parse(String(row.tags_json)),
+        related: JSON.parse(String(row.related_json)),
+        published_path: row.published_path ? String(row.published_path) : null,
+        forked_from: row.forked_from ? String(row.forked_from) : null,
+        target_path: row.target_path ? String(row.target_path) : null,
+        created_at: String(row.created_at),
+        updated_at: String(row.updated_at),
+    };
+}
+export class DraftsDb {
+    db;
+    constructor(knowledgeRoot) {
+        const dbDir = path.join(knowledgeRoot, '.repo-mind');
+        fs.mkdirSync(dbDir, { recursive: true });
+        const dbPath = path.join(dbDir, 'drafts.db');
+        this.db = new Database(dbPath);
+        this.db.pragma('journal_mode = WAL');
+        this.db.exec(SCHEMA_SQL);
+        this.ensureTargetPathColumn();
+    }
+    ensureTargetPathColumn() {
+        const columns = this.db.prepare(`PRAGMA table_info(drafts)`).all();
+        if (!columns.some((column) => column.name === 'target_path')) {
+            this.db.exec(`ALTER TABLE drafts ADD COLUMN target_path TEXT`);
+        }
+    }
+    close() {
+        this.db.close();
+    }
+    listActive() {
+        const rows = this.db
+            .prepare(`SELECT * FROM drafts WHERE published_path IS NULL ORDER BY updated_at DESC`)
+            .all();
+        return rows.map(rowToDraft);
+    }
+    getById(id) {
+        const row = this.db.prepare(`SELECT * FROM drafts WHERE id = ?`).get(id);
+        return row ? rowToDraft(row) : null;
+    }
+    getActiveBySlug(slug) {
+        const row = this.db
+            .prepare(`SELECT * FROM drafts WHERE slug = ? AND published_path IS NULL`)
+            .get(slug);
+        return row ? rowToDraft(row) : null;
+    }
+    create(input) {
+        if (!isDocType(input.type)) {
+            throw new Error(`invalid type: ${input.type}`);
+        }
+        const existing = this.getActiveBySlug(input.slug);
+        if (existing) {
+            throw new Error(`active draft already exists for slug: ${input.slug}`);
+        }
+        const now = new Date().toISOString();
+        const id = randomUUID();
+        const tags = JSON.stringify(input.tags ?? []);
+        const related = JSON.stringify(input.related ?? []);
+        this.db
+            .prepare(`INSERT INTO drafts (id, slug, type, status, title, body, tags_json, related_json, forked_from, target_path, created_at, updated_at)
+         VALUES (?, ?, ?, 'draft', ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(id, input.slug, input.type, input.title ?? input.slug, input.body ?? '', tags, related, input.forked_from ?? null, input.target_path ?? null, now, now);
+        const created = this.getById(id);
+        if (!created) {
+            throw new Error('failed to create draft');
+        }
+        return created;
+    }
+    update(id, input) {
+        const current = this.getById(id);
+        if (!current) {
+            throw new Error('draft not found');
+        }
+        if (current.published_path) {
+            throw new Error('cannot update published draft');
+        }
+        if (input.slug && input.slug !== current.slug) {
+            const collision = this.getActiveBySlug(input.slug);
+            if (collision && collision.id !== id) {
+                throw new Error(`active draft already exists for slug: ${input.slug}`);
+            }
+        }
+        if (input.type && !isDocType(input.type)) {
+            throw new Error(`invalid type: ${input.type}`);
+        }
+        if (input.status && !isDocStatus(input.status)) {
+            throw new Error(`invalid status: ${input.status}`);
+        }
+        const next = {
+            slug: input.slug ?? current.slug,
+            type: input.type ?? current.type,
+            status: input.status ?? current.status,
+            title: input.title ?? current.title,
+            body: input.body ?? current.body,
+            tags: input.tags ?? current.tags,
+            related: input.related ?? current.related,
+            updated_at: new Date().toISOString(),
+        };
+        this.db
+            .prepare(`UPDATE drafts SET slug = ?, type = ?, status = ?, title = ?, body = ?, tags_json = ?, related_json = ?, updated_at = ?
+         WHERE id = ?`)
+            .run(next.slug, next.type, next.status, next.title, next.body, JSON.stringify(next.tags), JSON.stringify(next.related), next.updated_at, id);
+        const updated = this.getById(id);
+        if (!updated) {
+            throw new Error('failed to update draft');
+        }
+        return updated;
+    }
+    delete(id) {
+        const current = this.getById(id);
+        if (!current) {
+            return false;
+        }
+        if (current.published_path) {
+            throw new Error('cannot delete published draft');
+        }
+        const result = this.db.prepare(`DELETE FROM drafts WHERE id = ?`).run(id);
+        return result.changes > 0;
+    }
+    markPublished(id, gitPath) {
+        const current = this.getById(id);
+        if (!current) {
+            throw new Error('draft not found');
+        }
+        if (current.published_path) {
+            throw new Error('draft already published');
+        }
+        const now = new Date().toISOString();
+        this.db
+            .prepare(`UPDATE drafts SET published_path = ?, updated_at = ? WHERE id = ?`)
+            .run(gitPath, now, id);
+        this.db
+            .prepare(`INSERT INTO publish_log (id, draft_id, git_path, published_at) VALUES (?, ?, ?, ?)`)
+            .run(randomUUID(), id, gitPath, now);
+        const published = this.getById(id);
+        if (!published) {
+            throw new Error('failed to mark published');
+        }
+        return published;
+    }
+}
+export function openDraftsDb(knowledgeRoot) {
+    return new DraftsDb(knowledgeRoot);
+}

package/dist/ui/diff.d.ts

@@ -0,0 +1,8 @@
+import type { DocIndex } from '../index/doc-index.js';
+import type { DraftRow } from './db/drafts-db.js';
+export interface DraftDiffResult {
+    targetPath: string | null;
+    isNew: boolean;
+    diff: string;
+}
+export declare function computeDraftDiff(index: DocIndex, draft: DraftRow): DraftDiffResult;