@tikoci/rosetta 0.6.8 → 0.7.1

package/README.md

@@ -275,22 +275,19 @@ Ask your AI assistant questions like:
 
 ## MCP Tools
 
-The server exposes 16 tools designed to work together — agents start with `routeros_search` and drill into specific data as needed:
+The server exposes 13 tools designed to work together — agents start with `routeros_search` and drill into specific data as needed:
 
 | Tool | What it does |
 |------|-------------|
-| `routeros_search` | **Start here.** Full-text search across all documentation pages |
+| `routeros_search` | **Start here.** Unified search with input classifier — returns pages + related callouts, videos, properties, changelogs, devices, skills |
 | `routeros_get_page` | Full page content by ID or title, section-aware for large pages |
 | `routeros_lookup_property` | Property by exact name — type, default, description |
-| `routeros_search_properties` | FTS across 4,860 property names and descriptions |
 | `routeros_command_tree` | Browse the command hierarchy (`/ip/firewall/filter` style) |
-| `routeros_search_callouts` | Search warnings, notes, and tips |
 | `routeros_search_changelogs` | Changelogs filtered by version range, category, breaking flag |
 | `routeros_command_version_check` | Which RouterOS versions include a command path |
 | `routeros_command_diff` | Added/removed commands between two RouterOS versions |
 | `routeros_device_lookup` | Hardware specs — filter by architecture, RAM, PoE, wireless, etc. |
 | `routeros_search_tests` | Cross-device ethernet and IPSec benchmarks |
-| `routeros_search_videos` | YouTube transcript search with chapter timestamps |
 | `routeros_dude_search` | FTS across archived Dude wiki docs (separate from RouterOS search) |
 | `routeros_dude_get_page` | Full Dude wiki page by ID or title, with screenshot metadata |
 | `routeros_stats` | Database health and coverage stats |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tikoci/rosetta",
-  "version": "0.6.8",
+  "version": "0.7.1",
   "description": "RouterOS documentation as SQLite FTS5 — RAG search + command glossary via MCP",
   "type": "module",
   "license": "MIT",

package/src/browse.ts

@@ -20,7 +20,8 @@ import type {
   DeviceResult,
   DeviceTestRow,
   DudeSearchResult,
-  SearchResponse,
+  GlossaryEntry,
+  SearchAllResponse,
   SearchResult,
   SectionTocEntry,
   VideoSearchResult,
@@ -35,14 +36,16 @@ import {
   getPage,
   getSkill,
   getTestResultMeta,
+  listGlossary,
   listSkills,
+  lookupGlossary,
   lookupProperty,
+  searchAll,
   searchCallouts,
   searchChangelogs,
   searchDevices,
   searchDeviceTests,
   searchDude,
-  searchPages,
   searchProperties,
   searchVideos,
 } from "./query.ts";
@@ -192,7 +195,7 @@ function waitForKey(): Promise<string> {
 
 type Context =
   | { type: "home" }
-  | { type: "search"; response: SearchResponse; results: SearchResult[] }
+  | { type: "search"; response: SearchAllResponse; results: SearchResult[] }
   | { type: "page"; pageId: number; title: string; commandPath?: string }
   | { type: "sections"; pageId: number; title: string; sections: SectionTocEntry[] }
   | { type: "commands"; path: string }
@@ -271,18 +274,22 @@ function renderWelcome(): string {
   return box(lines, "rosetta");
 }
 
-function renderSearchResults(resp: SearchResponse): string {
+function renderSearchResults(resp: SearchAllResponse): string {
   const out: string[] = [];
-  const modeNote = resp.fallbackMode === "or" ? dim(" (OR fallback)") : "";
-  out.push(`  ${bold(String(resp.results.length))} of ${resp.total} results for ${cyan(`"${resp.query}"`)}${modeNote}`);
+  const modeNote = resp.fallback_mode === "or" ? dim(" (OR fallback)") : "";
+  out.push(`  ${bold(String(resp.pages.length))} of ${resp.total_pages} page results for ${cyan(`"${resp.query}"`)}${modeNote}`);
+
+  // Classifier signals — compact one-line summary when anything fired
+  const classLine = renderClassified(resp.classified);
+  if (classLine) out.push(`  ${dim("classified:")} ${classLine}`);
   if (resp.note) {
     out.push(`  ${yellow("Hint:")} ${resp.note}`);
   }
   out.push("");
 
   const w = termWidth();
-  for (let i = 0; i < resp.results.length; i++) {
-    const r = resp.results[i];
+  for (let i = 0; i < resp.pages.length; i++) {
+    const r = resp.pages[i];
     const num = dim(`${String(i + 1).padStart(3)}  `);
     const title = bold(truncate(r.title, 30));
     const path = dim(truncate(r.path, Math.max(20, w - 55)));
@@ -301,6 +308,23 @@ function renderSearchResults(resp: SearchResponse): string {
     out.push("");
   }
 
+  // Related block — compact summary of side-query hits
+  const related = renderRelated(resp.related, w);
+  if (related.length > 0) {
+    out.push(`  ${bold("related")}`);
+    out.push(...related);
+    out.push("");
+  }
+
+  // Next-steps block — always render the top 3 suggestions
+  if (resp.next_steps.length > 0) {
+    out.push(`  ${bold("next")}`);
+    for (const step of resp.next_steps.slice(0, 3)) {
+      out.push(`       ${dim("→")} ${step}`);
+    }
+    out.push("");
+  }
+
   // Navigation hints
   const hints = [
     `${cyan("[N]")} view page`,
@@ -312,6 +336,62 @@ function renderSearchResults(resp: SearchResponse): string {
   return out.join("\n");
 }
 
+/** One-line summary of classifier output — empty string if nothing fired. */
+function renderClassified(c: SearchAllResponse["classified"]): string {
+  const parts: string[] = [];
+  if (c.command_path) parts.push(`path=${cyan(c.command_path)}`);
+  if (c.version) parts.push(`version=${magenta(c.version)}`);
+  if (c.device) parts.push(`device=${yellow(c.device)}`);
+  if (c.property) parts.push(`property=${green(c.property)}`);
+  if (c.topics.length > 0) parts.push(`topics=[${c.topics.join(",")}]`);
+  if (c.command_fragment) {
+    if (c.command_fragment.verbs.length > 0) parts.push(`verbs=[${c.command_fragment.verbs.join(",")}]`);
+    if (c.command_fragment.pairs.length > 0) {
+      const pairs = c.command_fragment.pairs.map((p) => `${p.key}=${p.value}`).join(" ");
+      parts.push(`args={${pairs}}`);
+    }
+  }
+  return parts.join("  ");
+}
+
+/** Render related sections as one line each. */
+function renderRelated(related: SearchAllResponse["related"], w: number): string[] {
+  const out: string[] = [];
+  if (related.command_node) {
+    const n = related.command_node;
+    const link = n.linked_page ? ` → page #${n.linked_page.id} "${n.linked_page.title}"` : "";
+    out.push(`       ${dim("cmd")}  ${cyan(n.path)} (${n.type})${link}`);
+  }
+  if (related.commands?.length) {
+    const names = related.commands.map((c) => c.name).join(", ");
+    out.push(`       ${dim("children")}  ${truncate(names, w - 16)}`);
+  }
+  if (related.properties?.length) {
+    const props = related.properties.map((p) => p.name).join(", ");
+    out.push(`       ${dim("props")}  ${truncate(props, w - 14)}`);
+  }
+  if (related.devices?.length) {
+    const devs = related.devices.map((d) => d.product_name).join(", ");
+    out.push(`       ${dim("devices")}  ${truncate(devs, w - 16)}`);
+  }
+  if (related.changelogs?.length) {
+    const first = related.changelogs[0];
+    out.push(`       ${dim("changelog")}  ${first.version} ${first.category}: ${truncate(first.description, w - 40)}`);
+  }
+  if (related.videos?.length) {
+    const v = related.videos[0];
+    out.push(`       ${dim("video")}  ${truncate(v.title, w - 14)}`);
+  }
+  if (related.callouts?.length) {
+    const c = related.callouts[0];
+    out.push(`       ${dim("callout")}  ${c.type}: ${truncate(c.excerpt, w - 20)}`);
+  }
+  if (related.skills?.length) {
+    out.push(`       ${dim("skill")}  ${related.skills[0].name}`);
+  }
+  return out;
+}
+
 function renderPage(page: NonNullable<ReturnType<typeof getPage>>): string {
   const out: string[] = [];
   const w = termWidth();
@@ -890,6 +970,7 @@ function renderHelp(): string {
   cmd("page <id|title>", "", "View full page", "routeros_get_page");
   cmd("prop <name>", "p", "Look up property (scoped to current page)", "routeros_lookup_property");
   cmd("props <query>", "sp", "Search properties by FTS", "routeros_search_properties");
+  cmd("glossary [term]", "g", "Look up RouterOS jargon / list glossary");
   cmd("cmd [path]", "tree", "Browse command tree", "routeros_command_tree");
   cmd("device <query>", "dev", "Look up device specs", "routeros_device_lookup");
   cmd("tests [device] [type]", "", "Cross-device benchmarks", "routeros_search_tests");
@@ -1001,6 +1082,12 @@ async function dispatch(input: string): Promise<void> {
       return;
     }
 
+    case "g":
+    case "glossary": {
+      await doGlossary(rest);
+      return;
+    }
+
     case "cmd":
     case "tree": {
       const path = rest || (ctx.type === "commands" ? ctx.path : "");
@@ -1193,14 +1280,9 @@ async function handleNumberSelect(idx: number): Promise<void> {
 // ── Action functions ──
 
 async function doSearch(query: string): Promise<void> {
-  const resp = searchPages(query);
-  if (resp.results.length === 0) {
-    const extra = resp.note ? ` ${yellow("Hint:")} ${resp.note}` : "";
-    console.log(`  ${dim("No results.")} Try: ${cyan("props")} ${query}, ${cyan("cal")} ${query}, ${cyan("vid")} ${query}${extra}`);
-    return;
-  }
+  const resp = searchAll(query);
   await paged(renderSearchResults(resp));
-  pushCtx({ type: "search", response: resp, results: resp.results });
+  pushCtx({ type: "search", response: resp, results: resp.pages });
 }
 
 async function doPage(idOrTitle: string, sectionName?: string): Promise<void> {
@@ -1265,6 +1347,44 @@ async function doSearchProperties(query: string): Promise<void> {
   pushCtx({ type: "properties", query, results: results.map(p => ({ name: p.name, page_id: p.page_id, page_title: p.page_title })) });
 }
 
+async function doGlossary(rest: string): Promise<void> {
+  if (!rest) {
+    // List all glossary entries grouped by category
+    const entries = listGlossary();
+    if (entries.length === 0) {
+      console.log(dim("  Glossary is empty."));
+      return;
+    }
+    const grouped = new Map<string, GlossaryEntry[]>();
+    for (const e of entries) {
+      const list = grouped.get(e.category) || [];
+      list.push(e);
+      grouped.set(e.category, list);
+    }
+    const lines: string[] = [`  ${bold("Glossary")} ${dim(`(${entries.length} terms)`)}\n`];
+    for (const [cat, items] of grouped) {
+      lines.push(`  ${yellow(cat.toUpperCase())}`);
+      for (const e of items) {
+        const aliases = e.aliases ? ` ${dim(`(${e.aliases})`)}` : "";
+        lines.push(`    ${cyan(e.term)}${aliases} — ${e.definition}`);
+      }
+      lines.push("");
+    }
+    await paged(lines.join("\n"));
+    return;
+  }
+  // Look up a specific term
+  const entry = lookupGlossary(rest);
+  if (!entry) {
+    console.log(dim(`  Term "${rest}" not in glossary.`));
+    console.log(`  Try: ${cyan("glossary")} ${dim("(no args)")} to see all terms, or ${cyan("s")} ${rest}`);
+    return;
+  }
+  const aliases = entry.aliases ? `\n  ${dim("Aliases:")} ${entry.aliases}` : "";
+  const hint = entry.search_hint ? `\n  ${dim("Search:")} ${cyan(entry.search_hint)}` : "";
+  console.log(`\n  ${bold(entry.term)} ${dim(`[${entry.category}]`)}\n  ${entry.definition}${aliases}${hint}\n`);
+}
+
 async function doCommandTree(path: string): Promise<void> {
   // Extract optional @version suffix: "cmd /ip/address @7.15" or "cmd /ip add @7.20"
   let version: string | undefined;

package/src/classify.test.ts

@@ -0,0 +1,205 @@
+/**
+ * classify.test.ts — Table-driven unit tests for the input classifier.
+ *
+ * Pure-function module — no DB required. Covers each detector in the DESIGN.md
+ * detector table plus real overlap cases (topic + version, command-path + topic).
+ */
+import { describe, expect, test } from "bun:test";
+
+import { classifyQuery } from "./classify.ts";
+
+type Expectation = {
+  version?: string;
+  topics?: string[];        // must be a subset of detected topics (order-insensitive)
+  topicsExact?: string[];   // exact match on detected topics (order-sensitive)
+  command_path?: string;
+  fragment_pairs?: Array<{ key: string; value: string }>;
+  fragment_verbs?: string[];
+  device?: string;
+  property?: string;
+  none?: boolean;           // assert no signals detected
+};
+
+const CASES: Array<{ name: string; input: string; expect: Expectation }> = [
+  // --- Empty / noise ---
+  { name: "empty input", input: "", expect: { none: true } },
+  { name: "whitespace only", input: "   \t  ", expect: { none: true } },
+
+  // --- Topic detection (KNOWN_TOPICS) ---
+  { name: "single topic — bgp", input: "bgp neighbor configuration", expect: { topics: ["bgp"] } },
+  { name: "two topics — dhcp + server synonym", input: "dhcp server lease timeout", expect: { topics: ["dhcp"] } },
+  { name: "firewall + filter compound", input: "how do I configure firewall filter", expect: { topics: ["firewall", "filter"] } },
+  { name: "routing + ospf", input: "routing ospf area configuration", expect: { topics: ["routing", "ospf"] } },
+  { name: "wireguard topic", input: "wireguard peer setup", expect: { topics: ["wireguard"] } },
+  { name: "ipv6 topic", input: "ipv6 address configuration", expect: { topics: ["ipv6"] } },
+
+  // --- Version detection ---
+  { name: "stable version 7.22", input: "what changed in 7.22", expect: { version: "7.22" } },
+  { name: "patch version 7.22.1", input: "7.22.1 release notes", expect: { version: "7.22.1" } },
+  { name: "beta version 7.23beta2", input: "whats new in 7.23beta2", expect: { version: "7.23beta2" } },
+  { name: "rc version 7.22rc1", input: "7.22rc1 bug", expect: { version: "7.22rc1" } },
+  { name: "version with v prefix", input: "v7.22 changelog", expect: { version: "7.22" } },
+  { name: "first-match wins on two versions", input: "compare 7.21 and 7.22", expect: { version: "7.21" } },
+
+  // --- Topic + version overlap (DESIGN.md canonical example) ---
+  {
+    name: "topic + version + general",
+    input: "bgp 7.22 route reflection",
+    expect: { topics: ["bgp", "route"], version: "7.22" },
+  },
+  {
+    name: "changelog-like topic+version",
+    input: "firewall raw 7.22 breaking",
+    expect: { topics: ["firewall", "raw"], version: "7.22" },
+  },
+
+  // --- Command path detection ---
+  {
+    name: "absolute slash path",
+    input: "/ip/firewall/filter",
+    expect: { command_path: "/ip/firewall/filter", topics: ["ip", "firewall", "filter"] },
+  },
+  {
+    name: "space-separated absolute path",
+    input: "/ip firewall filter",
+    expect: { command_path: "/ip/firewall/filter" },
+  },
+  {
+    name: "path without leading slash",
+    input: "ip firewall filter",
+    expect: { command_path: "/ip/firewall/filter" },
+  },
+  {
+    name: "system scheduler path",
+    input: "/system/scheduler",
+    expect: { command_path: "/system/scheduler", topics: ["system"] },
+  },
+  {
+    name: "ipv6 firewall raw",
+    input: "/ipv6/firewall/raw",
+    expect: { command_path: "/ipv6/firewall/raw", topics: ["ipv6", "firewall", "raw"] },
+  },
+
+  // --- Command fragment (key=value, verbs) ---
+  {
+    name: "add with two pairs",
+    input: "add chain=forward action=accept",
+    expect: {
+      fragment_pairs: [{ key: "chain", value: "forward" }, { key: "action", value: "accept" }],
+      fragment_verbs: ["add"],
+    },
+  },
+  {
+    name: "set disabled=no",
+    input: "set disabled=no",
+    expect: {
+      fragment_pairs: [{ key: "disabled", value: "no" }],
+      fragment_verbs: ["set"],
+    },
+  },
+  {
+    name: "print without pairs",
+    input: "print detail",
+    expect: { fragment_verbs: ["print"] },
+  },
+
+  // --- Device model ---
+  { name: "RB model", input: "RB1100AHx4 specs", expect: { device: "RB1100AHx4" } },
+  { name: "CCR with dashes", input: "CCR2216-1G-12XS-2XQ throughput", expect: { device: "CCR2216-1G-12XS-2XQ" } },
+  { name: "CRS switch", input: "CRS354 port count", expect: { device: "CRS354" } },
+  { name: "hEX", input: "hEX S performance", expect: { device: "hEX" } },
+  { name: "hAP ax", input: "hAP ax specs", expect: { device: "hAP" } },
+  { name: "cAP ac", input: "cAP ac indoor", expect: { device: "cAP" } },
+  { name: "SXTsq", input: "SXTsq 5 config", expect: { device: "SXTsq" } },
+
+  // --- Property name candidate (single short lowercase token) ---
+  { name: "property — chain", input: "chain", expect: { property: "chain" } },
+  { name: "property — fastpath", input: "fastpath", expect: { property: "fastpath" } },
+  {
+    name: "single known-topic token is NOT classified as property",
+    input: "bgp",
+    expect: { topics: ["bgp"] },
+  },
+
+  // --- Non-exclusive / complex inputs ---
+  {
+    name: "device + topic",
+    input: "RB5009 wireguard performance",
+    expect: { device: "RB5009", topics: ["wireguard"] },
+  },
+  {
+    name: "container add with verb",
+    input: "container add remote-image",
+    expect: { topics: ["container"], fragment_verbs: ["add"] },
+  },
+];
+
+describe("classifyQuery", () => {
+  for (const { name, input, expect: want } of CASES) {
+    test(name, () => {
+      const result = classifyQuery(input);
+
+      if (want.none) {
+        expect(result.version).toBeUndefined();
+        expect(result.command_path).toBeUndefined();
+        expect(result.command_fragment).toBeUndefined();
+        expect(result.device).toBeUndefined();
+        expect(result.property).toBeUndefined();
+        expect(result.topics).toEqual([]);
+        return;
+      }
+
+      if (want.version !== undefined) expect(result.version).toBe(want.version);
+      if (want.command_path !== undefined) expect(result.command_path).toBe(want.command_path);
+      if (want.device !== undefined) expect(result.device).toBe(want.device);
+      if (want.property !== undefined) expect(result.property).toBe(want.property);
+
+      if (want.topics !== undefined) {
+        for (const t of want.topics) {
+          expect(result.topics).toContain(t);
+        }
+      }
+      if (want.topicsExact !== undefined) expect(result.topics).toEqual(want.topicsExact);
+
+      if (want.fragment_pairs !== undefined) {
+        expect(result.command_fragment?.pairs).toEqual(want.fragment_pairs);
+      }
+      if (want.fragment_verbs !== undefined) {
+        expect(result.command_fragment?.verbs).toEqual(want.fragment_verbs);
+      }
+    });
+  }
+
+  test("multi-word input never fires property detector", () => {
+    const result = classifyQuery("chain forward policy");
+    expect(result.property).toBeUndefined();
+  });
+
+  test("property detector yields to command_path", () => {
+    // "interface" is a top-level command and a known topic — path wins over property
+    const result = classifyQuery("interface");
+    expect(result.property).toBeUndefined();
+  });
+
+  test("property detector yields to device", () => {
+    const result = classifyQuery("RB5009");
+    expect(result.property).toBeUndefined();
+    expect(result.device).toBe("RB5009");
+  });
+
+  test("version regex doesn't swallow arbitrary decimals", () => {
+    const result = classifyQuery("interface stats show 5.0 Gbps");
+    expect(result.version).toBeUndefined();
+  });
+
+  test("topics are deduplicated", () => {
+    const result = classifyQuery("firewall firewall filter firewall");
+    const firewallCount = result.topics.filter((t) => t === "firewall").length;
+    expect(firewallCount).toBe(1);
+  });
+
+  test("topics capped at 5", () => {
+    const result = classifyQuery("bgp ospf rip dhcp dns routing wireguard ipsec");
+    expect(result.topics.length).toBeLessThanOrEqual(5);
+  });
+});