@tikoci/rosetta 0.6.3 → 0.6.4

package/src/extract-html.test.ts

@@ -51,17 +51,41 @@ after
 });
 
 describe("extractPlainText", () => {
-  it("keeps heading and paragraph separated", () => {
+  it("emits heading markers", () => {
     const { document } = parseHTML("<div><h1>Basic Setup</h1><p>This is the basic VRRP configuration example.</p></div>");
     const out = extractPlainText(document.querySelector("div"));
-    expect(out).toContain("Basic Setup\nThis is the basic VRRP configuration example.");
-    expect(out).not.toContain("Basic SetupThis");
+    expect(out).toContain("# Basic Setup\nThis is the basic VRRP configuration example.");
   });
 
-  it("keeps subsection heading boundaries", () => {
+  it("emits h2 markers for subsections", () => {
     const { document } = parseHTML("<div><h2>Overview</h2><p>The Point-to-Point Protocol (PPP) provides...</p></div>");
     const out = extractPlainText(document.querySelector("div"));
-    expect(out).toContain("Overview\nThe Point-to-Point Protocol (PPP) provides...");
-    expect(out).not.toContain("OverviewThe");
+    expect(out).toContain("## Overview\nThe Point-to-Point Protocol (PPP) provides...");
+  });
+
+  it("emits list markers for ul", () => {
+    const { document } = parseHTML("<div><ul><li>First item</li><li>Second item</li></ul></div>");
+    const out = extractPlainText(document.querySelector("div"));
+    expect(out).toContain("- First item");
+    expect(out).toContain("- Second item");
+  });
+
+  it("emits numbered markers for ol", () => {
+    const { document } = parseHTML("<div><ol><li>Step one</li><li>Step two</li></ol></div>");
+    const out = extractPlainText(document.querySelector("div"));
+    expect(out).toContain("1. Step one");
+    expect(out).toContain("2. Step two");
+  });
+
+  it("wraps strong/b in **bold**", () => {
+    const { document } = parseHTML("<div><p>The <strong>disabled</strong> property controls this.</p></div>");
+    const out = extractPlainText(document.querySelector("div"));
+    expect(out).toContain("**disabled**");
+  });
+
+  it("wraps code in backticks", () => {
+    const { document } = parseHTML("<div><p>Use <code>/ip/address</code> to configure.</p></div>");
+    const out = extractPlainText(document.querySelector("div"));
+    expect(out).toContain("`/ip/address`");
   });
 });

package/src/extract-html.ts

@@ -123,13 +123,17 @@ export function sanitizeExtractedText(input: string): string {
 }
 
 /**
- * Convert a DOM subtree to readable plain text while preserving block boundaries.
- * This avoids merged tokens like "OverviewThe" caused by raw textContent collapse.
+ * Convert a DOM subtree to readable text with lightweight markdown signals.
+ * Preserves block boundaries (avoids "OverviewThe" token merge) and emits:
+ *   - Heading markers: ## Heading (matching h1–h6 level)
+ *   - List markers: - item (ul) or 1. item (ol)
+ *   - Emphasis: **bold** for <strong>/<b>, `code` for <code>
  */
 export function extractPlainText(root: Element | null): string {
   if (!root) return "";
 
   let out = "";
+  let olCounter = 0;
 
   const addBreak = () => {
     if (!out) return;
@@ -160,6 +164,78 @@ export function extractPlainText(root: Element | null): string {
       return;
     }
 
+    // Heading markers: ## Heading
+    const headingMatch = tag.match(/^h([1-6])$/);
+    if (headingMatch) {
+      addBreak();
+      const level = Number.parseInt(headingMatch[1], 10);
+      const prefix = "#".repeat(level);
+      const headingText = (el.textContent || "").replace(/\s+/g, " ").trim();
+      if (headingText) {
+        addText(`${prefix} ${headingText}`);
+      }
+      addBreak();
+      return; // don't recurse into heading children — already captured via textContent
+    }
+
+    // Ordered list: reset counter
+    if (tag === "ol") {
+      const savedCounter = olCounter;
+      olCounter = 0;
+      addBreak();
+      for (const child of el.childNodes) {
+        walk(child as unknown as Node);
+      }
+      addBreak();
+      olCounter = savedCounter;
+      return;
+    }
+
+    // Unordered list
+    if (tag === "ul") {
+      addBreak();
+      for (const child of el.childNodes) {
+        walk(child as unknown as Node);
+      }
+      addBreak();
+      return;
+    }
+
+    // List item: prefix with - or N.
+    if (tag === "li") {
+      addBreak();
+      const parentTag = (el.parentElement?.tagName || "").toLowerCase();
+      if (parentTag === "ol") {
+        olCounter++;
+        addText(`${olCounter}.`);
+      } else {
+        addText("-");
+      }
+      for (const child of el.childNodes) {
+        walk(child as unknown as Node);
+      }
+      addBreak();
+      return;
+    }
+
+    // Inline emphasis: **bold**
+    if (tag === "strong" || tag === "b") {
+      const inner = (el.textContent || "").replace(/\s+/g, " ").trim();
+      if (inner) {
+        addText(`**${inner}**`);
+      }
+      return; // don't recurse — already captured
+    }
+
+    // Inline code: `code`
+    if (tag === "code") {
+      const inner = (el.textContent || "").replace(/\s+/g, " ").trim();
+      if (inner) {
+        addText(`\`${inner}\``);
+      }
+      return; // don't recurse — already captured
+    }
+
     const isBlock = BLOCK_TAGS.has(tag);
     if (isBlock) addBreak();
 

package/src/mcp.ts

@@ -205,6 +205,8 @@ function createServer() {
 const server = new McpServer({
   name: "rosetta",
   version: RESOLVED_VERSION,
+}, {
+  instructions: "RouterOS documentation search. Start with routeros_search for any RouterOS question — it searches across pages, callouts, and properties with BM25 ranking. Drill into specific pages with routeros_get_page (by ID or title). For device hardware specs use routeros_device_lookup; for version-specific command changes use routeros_command_diff. Only v7 data exists (7.9+) — v6 is out of scope and answers will be unreliable.",
 });
 
 server.registerResource(

package/src/query.test.ts

@@ -505,6 +505,24 @@ describe("searchPages", () => {
     expect(res.ftsQuery).toBeTruthy();
     expect(res.query).toBe("dhcp server");
   });
+
+  test("returns best_section for pages with matching sections", () => {
+    // Page 3 (Bridging and Switching) has sections including "VLAN Setup" with VLAN content
+    const res = searchPages("bridge vlan");
+    const bridging = res.results.find((r) => r.id === 3);
+    expect(bridging).toBeDefined();
+    expect(bridging?.best_section).toBeDefined();
+    expect(bridging?.best_section?.heading).toBe("VLAN Setup");
+    expect(bridging?.best_section?.anchor_id).toBe("BridgingandSwitching-VLANSetup");
+    expect(bridging?.best_section?.url).toContain("#BridgingandSwitching-VLANSetup");
+  });
+
+  test("omits best_section for pages without sections", () => {
+    // Page 1 (DHCP Server) has no sections
+    const res = searchPages("dhcp lease");
+    expect(res.results.length).toBeGreaterThan(0);
+    expect(res.results[0].best_section).toBeUndefined();
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/query.ts

@@ -15,6 +15,7 @@ export type SearchResult = {
   word_count: number;
   code_lines: number;
   excerpt: string;
+  best_section?: { heading: string; anchor_id: string; url: string };
 };
 
 export type SearchResponse = {
@@ -157,6 +158,8 @@ export function searchPages(question: string, limit = DEFAULT_LIMIT): SearchResp
     fallbackMode = "or";
   }
 
+  attachBestSections(results, terms);
+
   return { query: question, ftsQuery, fallbackMode, results, total: results.length };
 }
 
@@ -179,6 +182,43 @@ function runFtsQuery(ftsQuery: string, limit: number): SearchResult[] {
   }
 }
 
+/** For each search result with sections, find the section whose text best matches the search terms. */
+function attachBestSections(results: SearchResult[], terms: string[]): void {
+  if (results.length === 0 || terms.length === 0) return;
+
+  const stmt = db.prepare(
+    `SELECT heading, anchor_id, text FROM sections WHERE page_id = ? ORDER BY sort_order`,
+  );
+
+  for (const result of results) {
+    const sections = stmt.all(result.id) as Array<{ heading: string; anchor_id: string; text: string }>;
+    if (sections.length === 0) continue;
+
+    let bestSection: (typeof sections)[0] | null = null;
+    let bestScore = 0;
+
+    for (const sec of sections) {
+      const haystack = `${sec.heading} ${sec.text}`.toLowerCase();
+      let score = 0;
+      for (const term of terms) {
+        if (haystack.includes(term)) score++;
+      }
+      if (score > bestScore) {
+        bestScore = score;
+        bestSection = sec;
+      }
+    }
+
+    if (bestSection && bestScore > 0) {
+      result.best_section = {
+        heading: bestSection.heading,
+        anchor_id: bestSection.anchor_id,
+        url: `${result.url}#${bestSection.anchor_id}`,
+      };
+    }
+  }
+}
+
 /** Section TOC entry returned when a large page would be truncated. */
 export type SectionTocEntry = {
   heading: string;