readthemanual 0.0.1

package/dist/db.js

@@ -0,0 +1,153 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openDb = openDb;
+exports.clearDocs = clearDocs;
+exports.insertSection = insertSection;
+exports.search = search;
+exports.getDocument = getDocument;
+exports.listDocuments = listDocuments;
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const DEFAULT_DB_PATH = path_1.default.join(os_1.default.homedir(), ".local", "rtm", "rtm.db");
+function openDb(dbPath = DEFAULT_DB_PATH) {
+    const dir = path_1.default.dirname(dbPath);
+    if (!fs_1.default.existsSync(dir)) {
+        try {
+            fs_1.default.mkdirSync(dir, { recursive: true });
+        }
+        catch (err) {
+            if (err.code === "EACCES") {
+                console.error(`Error: No write permission to ${dir}\n` +
+                    `If installed globally, run with sudo or install locally.`);
+                process.exit(1);
+            }
+            throw err;
+        }
+    }
+    const db = new better_sqlite3_1.default(dbPath);
+    db.pragma("journal_mode = WAL");
+    db.pragma("foreign_keys = ON");
+    initSchema(db);
+    return db;
+}
+function initSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS docs (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      file_path TEXT NOT NULL,
+      heading TEXT NOT NULL,
+      content TEXT NOT NULL,
+      language TEXT NOT NULL DEFAULT 'en'
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_docs_path ON docs(file_path);
+    CREATE INDEX IF NOT EXISTS idx_docs_lang ON docs(language);
+
+    CREATE VIRTUAL TABLE IF NOT EXISTS docs_fts USING fts5(
+      heading,
+      content,
+      content='docs',
+      content_rowid='id',
+      tokenize='porter unicode61'
+    );
+
+    CREATE TRIGGER IF NOT EXISTS docs_ai AFTER INSERT ON docs BEGIN
+      INSERT INTO docs_fts(rowid, heading, content)
+      VALUES (new.id, new.heading, new.content);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS docs_ad AFTER DELETE ON docs BEGIN
+      INSERT INTO docs_fts(docs_fts, rowid, heading, content)
+      VALUES ('delete', old.id, old.heading, old.content);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS docs_au AFTER UPDATE ON docs BEGIN
+      INSERT INTO docs_fts(docs_fts, rowid, heading, content)
+      VALUES ('delete', old.id, old.heading, old.content);
+      INSERT INTO docs_fts(rowid, heading, content)
+      VALUES (new.id, new.heading, new.content);
+    END;
+  `);
+}
+function clearDocs(db) {
+    db.exec("DELETE FROM docs");
+}
+function insertSection(db, section) {
+    const stmt = db.prepare("INSERT INTO docs (file_path, heading, content, language) VALUES (?, ?, ?, ?)");
+    const result = stmt.run(section.file_path, section.heading, section.content, section.language);
+    return Number(result.lastInsertRowid);
+}
+function sanitizeFtsQuery(query) {
+    const tokens = query
+        .replace(/"/g, "")
+        .split(/\s+/)
+        .filter(Boolean);
+    if (tokens.length === 0)
+        return '""';
+    return tokens.map((t) => `"${t}"`).join(" ");
+}
+function search(db, query, opts = {}) {
+    const limit = opts.limit ?? 20;
+    const ftsQuery = sanitizeFtsQuery(query);
+    let countSql = `
+    SELECT COUNT(*) as total
+    FROM docs_fts
+    JOIN docs d ON d.id = docs_fts.rowid
+    WHERE docs_fts MATCH ?
+  `;
+    let sql = `
+    SELECT
+      d.id, d.file_path, d.heading, d.content, d.language,
+      docs_fts.rank AS rank,
+      snippet(docs_fts, 1, '<mark>', '</mark>', '...', 40) AS snippet
+    FROM docs_fts
+    JOIN docs d ON d.id = docs_fts.rowid
+    WHERE docs_fts MATCH ?
+  `;
+    const params = [ftsQuery];
+    const countParams = [ftsQuery];
+    if (opts.sourcePrefix) {
+        countSql += " AND d.file_path LIKE ?";
+        sql += " AND d.file_path LIKE ?";
+        params.push(opts.sourcePrefix + "%");
+        countParams.push(opts.sourcePrefix + "%");
+    }
+    if (opts.language) {
+        countSql += " AND d.language = ?";
+        sql += " AND d.language = ?";
+        params.push(opts.language);
+        countParams.push(opts.language);
+    }
+    sql += " ORDER BY docs_fts.rank LIMIT ?";
+    params.push(limit);
+    const { total } = db.prepare(countSql).get(...countParams);
+    const results = db.prepare(sql).all(...params);
+    return { results, total };
+}
+function getDocument(db, id) {
+    return (db.prepare("SELECT * FROM docs WHERE id = ?").get(id) ?? null);
+}
+function listDocuments(db, opts = {}) {
+    const limit = opts.limit ?? 100;
+    const offset = opts.offset ?? 0;
+    let countSql = "SELECT COUNT(*) as total FROM docs";
+    let sql = "SELECT id, file_path, heading, language FROM docs";
+    const params = [];
+    const countParams = [];
+    if (opts.language) {
+        countSql += " WHERE language = ?";
+        sql += " WHERE language = ?";
+        params.push(opts.language);
+        countParams.push(opts.language);
+    }
+    sql += " ORDER BY file_path, id LIMIT ? OFFSET ?";
+    params.push(limit, offset);
+    const { total } = db.prepare(countSql).get(...countParams);
+    const docs = db.prepare(sql).all(...params);
+    return { docs, total };
+}

package/dist/ingest.d.ts

@@ -0,0 +1,9 @@
+export declare function ingest(opts: {
+    dbPath?: string;
+    source?: string;
+    allLangs?: boolean;
+    verbose?: boolean;
+}): Promise<{
+    filesProcessed: number;
+    sectionsInserted: number;
+}>;

package/dist/ingest.js

@@ -0,0 +1,163 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ingest = ingest;
+const db_1 = require("./db");
+const config_1 = require("./config");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+async function fetchTree(repo, branch) {
+    const url = `https://api.github.com/repos/${repo}/git/trees/${branch}?recursive=1`;
+    const res = await fetch(url, {
+        headers: {
+            Accept: "application/vnd.github.v3+json",
+            ...(process.env.GITHUB_TOKEN
+                ? { Authorization: `token ${process.env.GITHUB_TOKEN}` }
+                : {}),
+        },
+    });
+    if (!res.ok)
+        throw new Error(`GitHub tree API: ${res.status} ${res.statusText}`);
+    const data = (await res.json());
+    return data.tree;
+}
+async function fetchRawFile(repo, branch, filePath) {
+    const url = `https://raw.githubusercontent.com/${repo}/${branch}/${filePath}`;
+    const res = await fetch(url);
+    if (!res.ok)
+        throw new Error(`Failed to fetch ${filePath}: ${res.status}`);
+    return res.text();
+}
+function detectLanguage(filePath) {
+    const match = filePath.match(/^docs\/i18n\/([a-z]{2}(?:-[A-Z]{2})?)\//);
+    if (match)
+        return match[1];
+    return "en";
+}
+function splitByHeadings(markdown) {
+    const lines = markdown.split("\n");
+    const sections = [];
+    let currentHeading = "(intro)";
+    let currentLines = [];
+    for (const line of lines) {
+        const headingMatch = line.match(/^(#{1,3})\s+(.+)/);
+        if (headingMatch) {
+            if (currentLines.length > 0) {
+                const content = currentLines.join("\n").trim();
+                if (content.length > 0) {
+                    sections.push({ heading: currentHeading, content });
+                }
+            }
+            currentHeading = headingMatch[2];
+            currentLines = [];
+        }
+        else {
+            currentLines.push(line);
+        }
+    }
+    if (currentLines.length > 0) {
+        const content = currentLines.join("\n").trim();
+        if (content.length > 0) {
+            sections.push({ heading: currentHeading, content });
+        }
+    }
+    return sections;
+}
+async function ingestSource(db, source, opts) {
+    const log = opts.verbose ? console.log : () => { };
+    const repo = source.repo;
+    const branch = source.branch ?? "main";
+    const docsPrefix = source.docsPrefix ?? "docs/";
+    const config = (0, config_1.loadConfig)();
+    const docsDir = (0, config_1.getDocsDir)(config, source.name);
+    log(`[${source.name}] Fetching tree from ${repo}@${branch}...`);
+    const tree = await fetchTree(repo, branch);
+    const mdFiles = tree.filter((entry) => {
+        if (entry.type !== "blob")
+            return false;
+        if (!entry.path.startsWith(docsPrefix))
+            return false;
+        if (!entry.path.endsWith(".md"))
+            return false;
+        if (/\.(jpg|png|svg|gif)$/i.test(entry.path))
+            return false;
+        if (!opts.allLangs) {
+            const lang = detectLanguage(entry.path);
+            if (lang !== "en")
+                return false;
+        }
+        return true;
+    });
+    log(`[${source.name}] Found ${mdFiles.length} markdown files.`);
+    // Save docs locally
+    fs_1.default.rmSync(docsDir, { recursive: true, force: true });
+    fs_1.default.mkdirSync(docsDir, { recursive: true });
+    let filesProcessed = 0;
+    let sectionsInserted = 0;
+    const allSections = [];
+    const batchSize = 10;
+    for (let i = 0; i < mdFiles.length; i += batchSize) {
+        const batch = mdFiles.slice(i, i + batchSize);
+        const results = await Promise.all(batch.map(async (entry) => {
+            const content = await fetchRawFile(repo, branch, entry.path);
+            return { path: entry.path, content };
+        }));
+        for (const { path: filePath, content } of results) {
+            // Strip docsPrefix so we don't get docs/docs/ nesting
+            const relativePath = filePath.startsWith(docsPrefix)
+                ? filePath.slice(docsPrefix.length)
+                : filePath;
+            // Write raw markdown to disk
+            const localPath = path_1.default.join(docsDir, relativePath);
+            fs_1.default.mkdirSync(path_1.default.dirname(localPath), { recursive: true });
+            fs_1.default.writeFileSync(localPath, content, "utf-8");
+            const lang = detectLanguage(filePath);
+            const sections = splitByHeadings(content);
+            for (const section of sections) {
+                allSections.push({
+                    file_path: `${source.name}/${relativePath}`,
+                    heading: section.heading,
+                    content: section.content,
+                    language: lang,
+                });
+            }
+            filesProcessed++;
+            log(`  [${filesProcessed}/${mdFiles.length}] ${filePath} (${sections.length} sections)`);
+        }
+    }
+    const insertMany = db.transaction((sections) => {
+        for (const s of sections) {
+            (0, db_1.insertSection)(db, s);
+        }
+    });
+    insertMany(allSections);
+    sectionsInserted = allSections.length;
+    return { filesProcessed, sectionsInserted };
+}
+async function ingest(opts) {
+    const config = (0, config_1.loadConfig)();
+    const dbPath = opts.dbPath ?? (0, config_1.getDbPath)(config);
+    const db = (0, db_1.openDb)(dbPath);
+    const log = opts.verbose ? console.log : () => { };
+    // Filter to a single source if requested
+    const sources = opts.source
+        ? config.sources.filter((s) => s.name === opts.source)
+        : config.sources;
+    if (sources.length === 0) {
+        const available = config.sources.map((s) => s.name).join(", ");
+        throw new Error(`Source "${opts.source}" not found in config. Available: ${available}`);
+    }
+    (0, db_1.clearDocs)(db);
+    let totalFiles = 0;
+    let totalSections = 0;
+    for (const source of sources) {
+        const result = await ingestSource(db, source, opts);
+        totalFiles += result.filesProcessed;
+        totalSections += result.sectionsInserted;
+    }
+    db.close();
+    log(`Done. ${totalFiles} files, ${totalSections} sections indexed from ${sources.length} source(s).`);
+    return { filesProcessed: totalFiles, sectionsInserted: totalSections };
+}

package/dist/mcp.d.ts

@@ -0,0 +1,3 @@
+export declare function startMcp(opts: {
+    dbPath?: string;
+}): Promise<void>;

package/dist/mcp.js

@@ -0,0 +1,105 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startMcp = startMcp;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const zod_1 = require("zod");
+const db_1 = require("./db");
+const config_1 = require("./config");
+const path_1 = __importDefault(require("path"));
+async function startMcp(opts) {
+    const config = (0, config_1.loadConfig)();
+    const dbPath = opts.dbPath ?? (0, config_1.getDbPath)(config);
+    const db = (0, db_1.openDb)(dbPath);
+    const server = new mcp_js_1.McpServer({
+        name: "rtm",
+        version: "0.0.1",
+    });
+    server.registerTool("search", {
+        title: "Search docs",
+        description: "Full-text search across indexed documentation. Returns matching sections with snippets.",
+        inputSchema: {
+            query: zod_1.z.string().describe("Search query"),
+            source: zod_1.z.string().optional().describe("Source name to scope search (default: last used source)"),
+            language: zod_1.z.string().optional().describe("Filter by language code (e.g. 'en')"),
+            limit: zod_1.z.number().optional().describe("Max results (default: 10)"),
+        },
+    }, async ({ query, source, language, limit }) => {
+        const cfg = (0, config_1.loadConfig)();
+        const sourceName = source ?? (0, config_1.getDefaultSource)(cfg);
+        const { results, total } = (0, db_1.search)(db, query, {
+            language,
+            limit: limit ?? 10,
+            sourcePrefix: sourceName ? `${sourceName}/` : undefined,
+        });
+        const text = results.length === 0
+            ? "No results found."
+            : results.map((r) => {
+                const fullPath = path_1.default.join(cfg.dataDir, r.file_path);
+                const clean = r.snippet.replace(/<\/?mark>/g, "");
+                return `[${r.id}] ${r.heading}\n  ${fullPath}\n  ${clean}`;
+            }).join("\n\n") + `\n\n${results.length} of ${total} match(es)`;
+        return { content: [{ type: "text", text }] };
+    });
+    server.registerTool("get_document", {
+        title: "Get document",
+        description: "Retrieve a full document section by its ID.",
+        inputSchema: {
+            id: zod_1.z.number().describe("Document section ID"),
+        },
+    }, async ({ id }) => {
+        const doc = (0, db_1.getDocument)(db, id);
+        if (!doc) {
+            return { content: [{ type: "text", text: `Document ${id} not found.` }] };
+        }
+        const cfg = (0, config_1.loadConfig)();
+        const fullPath = path_1.default.join(cfg.dataDir, doc.file_path);
+        return {
+            content: [{
+                    type: "text",
+                    text: `# ${doc.heading}\n${fullPath} (${doc.language})\n\n${doc.content}`,
+                }],
+        };
+    });
+    server.registerTool("list_sources", {
+        title: "List sources",
+        description: "List configured documentation sources.",
+        inputSchema: {},
+    }, async () => {
+        const cfg = (0, config_1.loadConfig)();
+        const defaultSrc = (0, config_1.getDefaultSource)(cfg);
+        const lines = cfg.sources.map((s) => {
+            const marker = s.name === defaultSrc ? " (default)" : "";
+            return `- ${s.name}: ${s.repo}@${s.branch ?? "main"}${marker}`;
+        });
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    });
+    server.registerTool("list_documents", {
+        title: "List documents",
+        description: "List indexed document sections.",
+        inputSchema: {
+            language: zod_1.z.string().optional().describe("Filter by language"),
+            limit: zod_1.z.number().optional().describe("Max results (default: 50)"),
+            offset: zod_1.z.number().optional().describe("Offset for pagination"),
+        },
+    }, async ({ language, limit, offset }) => {
+        const result = (0, db_1.listDocuments)(db, {
+            language,
+            limit: limit ?? 50,
+            offset: offset ?? 0,
+        });
+        const cfg = (0, config_1.loadConfig)();
+        const lines = result.docs.map((d) => {
+            const fullPath = path_1.default.join(cfg.dataDir, d.file_path);
+            return `[${d.id}] ${fullPath} — ${d.heading}`;
+        });
+        const text = lines.join("\n") + `\n\n${result.docs.length} of ${result.total} total`;
+        return { content: [{ type: "text", text }] };
+    });
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error("rtm MCP server running on stdio");
+}

package/dist/server.d.ts

@@ -0,0 +1,7 @@
+import { Hono } from "hono";
+import type Database from "better-sqlite3";
+export declare function createApp(db: Database.Database): Hono;
+export declare function startServer(opts: {
+    dbPath?: string;
+    port?: number;
+}): Promise<void>;

package/dist/server.js

@@ -0,0 +1,111 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApp = createApp;
+exports.startServer = startServer;
+const hono_1 = require("hono");
+const node_server_1 = require("@hono/node-server");
+const db_1 = require("./db");
+function rpcError(id, code, message) {
+    return { jsonrpc: "2.0", id, error: { code, message } };
+}
+function rpcResult(id, result) {
+    return { jsonrpc: "2.0", id, result };
+}
+function handleRpc(db, req) {
+    const { id, method, params } = req;
+    switch (method) {
+        case "search": {
+            const query = params?.query;
+            if (typeof query !== "string" || query.trim().length === 0) {
+                return rpcError(id, -32602, "params.query is required and must be a non-empty string");
+            }
+            const language = typeof params?.language === "string" ? params.language : undefined;
+            const limit = typeof params?.limit === "number" ? params.limit : undefined;
+            const { results, total } = (0, db_1.search)(db, query, { language, limit });
+            return rpcResult(id, { results, total, count: results.length });
+        }
+        case "get_document": {
+            const docId = params?.id;
+            if (typeof docId !== "number") {
+                return rpcError(id, -32602, "params.id is required and must be a number");
+            }
+            const doc = (0, db_1.getDocument)(db, docId);
+            if (!doc) {
+                return rpcError(id, -32602, `Document with id ${docId} not found`);
+            }
+            return rpcResult(id, doc);
+        }
+        case "list_documents": {
+            const language = typeof params?.language === "string" ? params.language : undefined;
+            const limit = typeof params?.limit === "number" ? params.limit : undefined;
+            const offset = typeof params?.offset === "number" ? params.offset : undefined;
+            const result = (0, db_1.listDocuments)(db, { language, limit, offset });
+            return rpcResult(id, result);
+        }
+        default:
+            return rpcError(id, -32601, `Method '${method}' not found`);
+    }
+}
+function createApp(db) {
+    const app = new hono_1.Hono();
+    app.post("/rpc", async (c) => {
+        let body;
+        try {
+            body = await c.req.json();
+        }
+        catch {
+            return c.json(rpcError(null, -32700, "Parse error"), 200);
+        }
+        // Batch support
+        if (Array.isArray(body)) {
+            const responses = body.map((req) => {
+                if (!isValidRequest(req)) {
+                    return rpcError(req?.id ?? null, -32600, "Invalid JSON-RPC request");
+                }
+                return handleRpc(db, req);
+            });
+            return c.json(responses, 200);
+        }
+        if (!isValidRequest(body)) {
+            return c.json(rpcError(body?.id ?? null, -32600, "Invalid JSON-RPC request"), 200);
+        }
+        return c.json(handleRpc(db, body), 200);
+    });
+    // Health check
+    app.get("/health", (c) => c.json({ status: "ok" }));
+    return app;
+}
+function isValidRequest(obj) {
+    if (typeof obj !== "object" || obj === null)
+        return false;
+    const r = obj;
+    return r.jsonrpc === "2.0" && typeof r.method === "string";
+}
+const net_1 = __importDefault(require("net"));
+function isPortInUse(port) {
+    return new Promise((resolve) => {
+        const server = net_1.default.createServer();
+        server.once("error", () => resolve(true));
+        server.once("listening", () => {
+            server.close();
+            resolve(false);
+        });
+        server.listen(port);
+    });
+}
+async function startServer(opts) {
+    const port = opts.port ?? 3777;
+    if (await isPortInUse(port)) {
+        console.error(`Port ${port} is already in use. Another instance may be running.`);
+        process.exit(1);
+    }
+    const db = (0, db_1.openDb)(opts.dbPath);
+    const app = createApp(db);
+    (0, node_server_1.serve)({ fetch: app.fetch, port }, () => {
+        console.log(`rtm server listening on http://localhost:${port}`);
+        console.log(`JSON-RPC endpoint: POST http://localhost:${port}/rpc`);
+    });
+}