@tikoci/rosetta 0.6.6 → 0.6.8

package/src/extract-skills.ts

@@ -0,0 +1,390 @@
+#!/usr/bin/env bun
+/**
+ * extract-skills.ts — Extract agent skill guides from tikoci/routeros-skills.
+ *
+ * Fetches SKILL.md files and reference documents from GitHub (or a local path),
+ * parses YAML frontmatter, and populates skills + skill_references tables.
+ *
+ * Usage:
+ *   bun run src/extract-skills.ts                                    # Fetch from GitHub API
+ *   bun run src/extract-skills.ts /path/to/routeros-skills           # Use local directory
+ *   bun run src/extract-skills.ts --from-cache                       # Re-extract from cached skills/ dir
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { db, initDb } from "./db.ts";
+
+// ── Configuration ──
+
+const PROJECT_ROOT = join(import.meta.dirname, "..");
+const CACHE_DIR = join(PROJECT_ROOT, "skills");
+
+const GITHUB_REPO = "tikoci/routeros-skills";
+const GITHUB_API_BASE = `https://api.github.com/repos/${GITHUB_REPO}`;
+const GITHUB_RAW_BASE = `https://raw.githubusercontent.com/${GITHUB_REPO}`;
+
+const FROM_CACHE = process.argv.includes("--from-cache");
+
+/** Local path override: first non-flag CLI arg */
+const localPath = process.argv.slice(2).find((a) => !a.startsWith("--"));
+
+// ── Types ──
+
+interface SkillData {
+  name: string;
+  description: string;
+  content: string;
+  sourceUrl: string;
+  references: Array<{
+    path: string;
+    filename: string;
+    content: string;
+  }>;
+}
+
+// ── YAML frontmatter parsing (minimal — no dependency) ──
+
+function parseFrontmatter(markdown: string): { meta: Record<string, string>; content: string } {
+  const match = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+  if (!match) return { meta: {}, content: markdown };
+
+  const meta: Record<string, string> = {};
+  for (const line of match[1].split("\n")) {
+    const colonIdx = line.indexOf(":");
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    let value = line.slice(colonIdx + 1).trim();
+    // Strip surrounding quotes
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    meta[key] = value;
+  }
+  return { meta, content: match[2] };
+}
+
+function countWords(text: string): number {
+  return text.split(/\s+/).filter(Boolean).length;
+}
+
+// ── GitHub API fetching ──
+
+async function getDefaultBranchSha(): Promise<string> {
+  const res = await fetch(`${GITHUB_API_BASE}/commits/HEAD`, {
+    headers: { Accept: "application/vnd.github.v3+json" },
+  });
+  if (!res.ok) throw new Error(`Failed to get HEAD SHA: HTTP ${res.status}`);
+  const data = (await res.json()) as { sha: string };
+  return data.sha;
+}
+
+async function listSkillDirs(sha: string): Promise<string[]> {
+  const res = await fetch(`${GITHUB_API_BASE}/contents/?ref=${sha}`, {
+    headers: { Accept: "application/vnd.github.v3+json" },
+  });
+  if (!res.ok) throw new Error(`Failed to list repo contents: HTTP ${res.status}`);
+  const entries = (await res.json()) as Array<{ name: string; type: string }>;
+  return entries
+    .filter((e) => e.type === "dir" && e.name.startsWith("routeros-"))
+    .map((e) => e.name);
+}
+
+async function fetchRawFile(sha: string, path: string): Promise<string | null> {
+  const url = `${GITHUB_RAW_BASE}/${sha}/${path}`;
+  const res = await fetch(url);
+  if (!res.ok) {
+    if (res.status === 404) return null;
+    throw new Error(`Failed to fetch ${path}: HTTP ${res.status}`);
+  }
+  return res.text();
+}
+
+async function listReferences(sha: string, skillName: string): Promise<string[]> {
+  const res = await fetch(`${GITHUB_API_BASE}/contents/${skillName}/references?ref=${sha}`, {
+    headers: { Accept: "application/vnd.github.v3+json" },
+  });
+  if (!res.ok) {
+    if (res.status === 404) return [];
+    throw new Error(`Failed to list references for ${skillName}: HTTP ${res.status}`);
+  }
+  const entries = (await res.json()) as Array<{ name: string; type: string }>;
+  return entries.filter((e) => e.type === "file" && e.name.endsWith(".md")).map((e) => e.name);
+}
+
+async function extractFromGitHub(): Promise<{ skills: SkillData[]; sha: string }> {
+  console.log(`Fetching skills from GitHub: ${GITHUB_REPO}`);
+  const sha = await getDefaultBranchSha();
+  console.log(`  HEAD SHA: ${sha.slice(0, 12)}`);
+
+  const skillDirs = await listSkillDirs(sha);
+  console.log(`  Found ${skillDirs.length} skill directories`);
+
+  const skills: SkillData[] = [];
+
+  for (const dir of skillDirs) {
+    const skillMd = await fetchRawFile(sha, `${dir}/SKILL.md`);
+    if (!skillMd) {
+      console.warn(`  ⚠ ${dir}/SKILL.md not found, skipping`);
+      continue;
+    }
+
+    const { meta, content } = parseFrontmatter(skillMd);
+    const skill: SkillData = {
+      name: meta.name || dir,
+      description: meta.description || "",
+      content,
+      sourceUrl: `https://github.com/${GITHUB_REPO}/blob/${sha}/${dir}/SKILL.md`,
+      references: [],
+    };
+
+    // Fetch references
+    const refFiles = await listReferences(sha, dir);
+    for (const refFile of refFiles) {
+      const refContent = await fetchRawFile(sha, `${dir}/references/${refFile}`);
+      if (refContent) {
+        skill.references.push({
+          path: `references/${refFile}`,
+          filename: refFile,
+          content: refContent,
+        });
+      }
+    }
+
+    skills.push(skill);
+    console.log(`  ✓ ${skill.name} (${countWords(content)} words, ${skill.references.length} refs)`);
+  }
+
+  // Cache to skills/ directory
+  cacheSkills(skills, sha);
+
+  return { skills, sha };
+}
+
+// ── Local path extraction ──
+
+function extractFromLocal(dirPath: string): { skills: SkillData[]; sha: string } {
+  console.log(`Extracting skills from local path: ${dirPath}`);
+
+  // Try to get git SHA
+  let sha = "local";
+  try {
+    const gitResult = Bun.spawnSync(["git", "rev-parse", "HEAD"], { cwd: dirPath });
+    if (gitResult.exitCode === 0) {
+      sha = gitResult.stdout.toString().trim();
+      console.log(`  Git SHA: ${sha.slice(0, 12)}`);
+    }
+  } catch { /* not a git repo, that's fine */ }
+
+  const entries = readdirSync(dirPath, { withFileTypes: true });
+  const skillDirs = entries.filter((e) => e.isDirectory() && e.name.startsWith("routeros-")).map((e) => e.name);
+  console.log(`  Found ${skillDirs.length} skill directories`);
+
+  const skills: SkillData[] = [];
+
+  for (const dir of skillDirs) {
+    const skillPath = join(dirPath, dir, "SKILL.md");
+    if (!existsSync(skillPath)) {
+      console.warn(`  ⚠ ${dir}/SKILL.md not found, skipping`);
+      continue;
+    }
+
+    const skillMd = readFileSync(skillPath, "utf-8");
+    const { meta, content } = parseFrontmatter(skillMd);
+    const skill: SkillData = {
+      name: meta.name || dir,
+      description: meta.description || "",
+      content,
+      sourceUrl: `https://github.com/${GITHUB_REPO}/blob/${sha}/${dir}/SKILL.md`,
+      references: [],
+    };
+
+    // Load references
+    const refsDir = join(dirPath, dir, "references");
+    if (existsSync(refsDir)) {
+      const refEntries = readdirSync(refsDir, { withFileTypes: true });
+      for (const ref of refEntries) {
+        if (ref.isFile() && ref.name.endsWith(".md")) {
+          skill.references.push({
+            path: `references/${ref.name}`,
+            filename: ref.name,
+            content: readFileSync(join(refsDir, ref.name), "utf-8"),
+          });
+        }
+      }
+    }
+
+    skills.push(skill);
+    console.log(`  ✓ ${skill.name} (${countWords(content)} words, ${skill.references.length} refs)`);
+  }
+
+  // Cache to skills/ directory
+  cacheSkills(skills, sha);
+
+  return { skills, sha };
+}
+
+// ── Cache management ──
+
+function cacheSkills(skills: SkillData[], sha: string) {
+  mkdirSync(CACHE_DIR, { recursive: true });
+
+  // Write metadata
+  const metadata = {
+    sha,
+    extracted_at: new Date().toISOString(),
+    skills: skills.map((s) => ({
+      name: s.name,
+      description: s.description,
+      word_count: countWords(s.content),
+      ref_count: s.references.length,
+    })),
+  };
+  writeFileSync(join(CACHE_DIR, "metadata.json"), JSON.stringify(metadata, null, 2));
+
+  // Write each skill
+  for (const skill of skills) {
+    const skillDir = join(CACHE_DIR, skill.name);
+    mkdirSync(skillDir, { recursive: true });
+
+    // Write SKILL.md with frontmatter reconstructed
+    const frontmatter = `---\nname: ${skill.name}\ndescription: "${skill.description}"\n---\n`;
+    writeFileSync(join(skillDir, "SKILL.md"), frontmatter + skill.content);
+
+    // Write references
+    if (skill.references.length > 0) {
+      const refsDir = join(skillDir, "references");
+      mkdirSync(refsDir, { recursive: true });
+      for (const ref of skill.references) {
+        writeFileSync(join(refsDir, ref.filename), ref.content);
+      }
+    }
+  }
+
+  console.log(`  Cached ${skills.length} skills to ${CACHE_DIR}/`);
+}
+
+function extractFromCache(): { skills: SkillData[]; sha: string } {
+  console.log(`Extracting skills from cache: ${CACHE_DIR}/`);
+
+  if (!existsSync(join(CACHE_DIR, "metadata.json"))) {
+    throw new Error(`No cached skills found at ${CACHE_DIR}/metadata.json — run without --from-cache first`);
+  }
+
+  const metadata = JSON.parse(readFileSync(join(CACHE_DIR, "metadata.json"), "utf-8"));
+  const sha = metadata.sha || "cached";
+
+  const skills: SkillData[] = [];
+  const entries = readdirSync(CACHE_DIR, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !entry.name.startsWith("routeros-")) continue;
+
+    const skillPath = join(CACHE_DIR, entry.name, "SKILL.md");
+    if (!existsSync(skillPath)) continue;
+
+    const skillMd = readFileSync(skillPath, "utf-8");
+    const { meta, content } = parseFrontmatter(skillMd);
+    const skill: SkillData = {
+      name: meta.name || entry.name,
+      description: meta.description || "",
+      content,
+      sourceUrl: `https://github.com/${GITHUB_REPO}/blob/${sha}/${entry.name}/SKILL.md`,
+      references: [],
+    };
+
+    // Load cached references
+    const refsDir = join(CACHE_DIR, entry.name, "references");
+    if (existsSync(refsDir)) {
+      const refEntries = readdirSync(refsDir, { withFileTypes: true });
+      for (const ref of refEntries) {
+        if (ref.isFile() && ref.name.endsWith(".md")) {
+          skill.references.push({
+            path: `references/${ref.name}`,
+            filename: ref.name,
+            content: readFileSync(join(refsDir, ref.name), "utf-8"),
+          });
+        }
+      }
+    }
+
+    skills.push(skill);
+    console.log(`  ✓ ${skill.name} (${countWords(content)} words, ${skill.references.length} refs)`);
+  }
+
+  return { skills, sha };
+}
+
+// ── Database population ──
+
+function populateDb(skills: SkillData[], sha: string) {
+  const now = new Date().toISOString();
+
+  // Idempotent: delete existing data (respect FK order)
+  db.run("DELETE FROM skill_references");
+  db.run("DELETE FROM skills");
+
+  const insertSkill = db.prepare(`
+    INSERT INTO skills (name, description, content, source_repo, source_sha, source_url, word_count, extracted_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+
+  const insertRef = db.prepare(`
+    INSERT INTO skill_references (skill_id, path, filename, content, word_count)
+    VALUES (?, ?, ?, ?, ?)
+  `);
+
+  const getSkillId = db.prepare("SELECT id FROM skills WHERE name = ?");
+
+  let totalWords = 0;
+  let totalRefs = 0;
+
+  for (const skill of skills) {
+    const wordCount = countWords(skill.content);
+    totalWords += wordCount;
+
+    insertSkill.run(
+      skill.name,
+      skill.description,
+      skill.content,
+      GITHUB_REPO,
+      sha,
+      skill.sourceUrl,
+      wordCount,
+      now,
+    );
+
+    const row = getSkillId.get(skill.name) as { id: number };
+    const skillId = row.id;
+
+    for (const ref of skill.references) {
+      const refWordCount = countWords(ref.content);
+      totalWords += refWordCount;
+      totalRefs++;
+      insertRef.run(skillId, ref.path, ref.filename, ref.content, refWordCount);
+    }
+  }
+
+  console.log(`\nPopulated DB: ${skills.length} skills, ${totalRefs} references, ${totalWords} total words`);
+}
+
+// ── Main ──
+
+async function main() {
+  initDb();
+
+  let skills: SkillData[];
+  let sha: string;
+
+  if (FROM_CACHE) {
+    ({ skills, sha } = extractFromCache());
+  } else if (localPath) {
+    ({ skills, sha } = extractFromLocal(localPath));
+  } else {
+    ({ skills, sha } = await extractFromGitHub());
+  }
+
+  populateDb(skills, sha);
+}
+
+await main();

package/src/mcp.ts

@@ -183,6 +183,8 @@ const {
   exportDeviceTestsCsv,
   fetchCurrentVersions,
   getPage,
+  getSkill,
+  listSkills,
   lookupProperty,
   searchCallouts,
   searchChangelogs,
@@ -437,6 +439,81 @@ ORDER BY version, sort_order;
   }),
 );
 
+// ── Skills resources (community-created agent guides from tikoci/routeros-skills) ──
+
+server.registerResource(
+  "skills-list",
+  "rosetta://skills",
+  {
+    title: "RouterOS Agent Skills",
+    description: "List of available RouterOS agent skill guides — community-created, AI-generated/human-reviewed supplemental content from tikoci/routeros-skills. NOT official MikroTik documentation.",
+    mimeType: "text/markdown",
+  },
+  async () => {
+    const skills = listSkills();
+    const lines = [
+      "# RouterOS Agent Skills",
+      "",
+      "⚠️ Community-created content from tikoci/routeros-skills — NOT official MikroTik documentation.",
+      "AI-generated, human-reviewed. May contain errors. Verify with routeros_search/routeros_get_page.",
+      "",
+      `${skills.length} skills available:`,
+      "",
+      ...skills.map(s => `- **${s.name}** — ${s.description} (${s.word_count} words, ${s.ref_count} refs) → \`rosetta://skills/${s.name}\``),
+    ];
+    return {
+      contents: [{
+        uri: "rosetta://skills",
+        mimeType: "text/markdown",
+        text: lines.join("\n"),
+      }],
+    };
+  },
+);
+
+// Register individual skill resources using resource templates
+// MCP resource templates allow `rosetta://skills/{name}` pattern matching
+{
+  const skills = listSkills();
+  for (const skill of skills) {
+    server.registerResource(
+      `skill-${skill.name}`,
+      `rosetta://skills/${skill.name}`,
+      {
+        title: `Skill: ${skill.name}`,
+        description: skill.description,
+        mimeType: "text/markdown",
+      },
+      async () => {
+        const detail = getSkill(skill.name);
+        if (!detail) {
+          return { contents: [{ uri: `rosetta://skills/${skill.name}`, mimeType: "text/plain", text: `Skill '${skill.name}' not found.` }] };
+        }
+        const lines = [
+          detail.provenance,
+          "",
+          `# ${detail.name}`,
+          "",
+          detail.content,
+        ];
+        if (detail.references.length > 0) {
+          lines.push("", "---", "", "## Reference Files", "");
+          for (const ref of detail.references) {
+            lines.push(`### ${ref.filename}`, "", ref.content, "");
+          }
+        }
+        return {
+          contents: [{
+            uri: `rosetta://skills/${detail.name}`,
+            mimeType: "text/markdown",
+            text: lines.join("\n"),
+          }],
+        };
+      },
+    );
+  }
+}
+
 // ---- routeros_search ----
 
 server.registerTool(
@@ -651,6 +728,7 @@ arguments). Each child includes its type and linked documentation page if availa
 Useful for discovering what's available under a command path.
 
 Optionally filter by RouterOS version to check what exists in a specific release.
+Optionally filter by CPU architecture (x86/arm64) to see platform-specific commands.
 Command data covers versions 7.9–7.23beta2. No v6 data.
 
 Workflow — combine with other tools:
@@ -662,7 +740,8 @@ Workflow — combine with other tools:
 Examples:
 - path: "/ip" → address, arp, dhcp-client, dhcp-server, firewall, route, etc.
 - path: "/ip/firewall" → filter, nat, mangle, raw, address-list, etc.
-- path: "", version: "7.15" → top-level menus as of RouterOS 7.15`,
+- path: "", version: "7.15" → top-level menus as of RouterOS 7.15
+- path: "/interface", arch: "arm64" → shows arm64-specific interfaces (wifi-qcom, ethernet/switch)`,
     inputSchema: {
       path: z
         .string()
@@ -673,13 +752,17 @@ Examples:
         .string()
         .optional()
         .describe("RouterOS version to filter by (e.g., '7.15'). Omit for latest."),
+      arch: z
+        .string()
+        .optional()
+        .describe("Filter by CPU architecture: 'x86' or 'arm64'. Omit to show all (including arch-specific nodes)."),
     },
   },
-  async ({ path, version }) => {
+  async ({ path, version, arch }) => {
     const cmdPath = path?.trim() || "";
     const results = version
-      ? browseCommandsAtVersion(cmdPath, version)
-      : browseCommands(cmdPath);
+      ? browseCommandsAtVersion(cmdPath, version, arch)
+      : browseCommands(cmdPath, arch);
 
     if (results.length === 0) {
       return {
@@ -700,7 +783,10 @@ server.registerTool(
     description: `Get database statistics for the RouterOS documentation index.
 
 Returns page count, property count, callout count, changelog count, command count, link coverage,
-version range, and documentation export date.
+version range, documentation export date, and available agent skills.
+
+Skills: Community-created agent guides from tikoci/routeros-skills are available as MCP resources
+at rosetta://skills/{name}. Use the resource listing to browse available skills.
 
 Knowledge boundaries:
 - Documentation: March 2026 Confluence HTML export (317 pages), aligned with long-term ~7.22
@@ -713,8 +799,17 @@ Knowledge boundaries:
   },
   async () => {
     const stats = getDbStats();
+    const skills = listSkills();
+    const statsWithSkills = {
+      ...stats,
+      skills: {
+        count: skills.length,
+        available: skills.map(s => s.name),
+        note: "Community-created agent guides from tikoci/routeros-skills. Access via rosetta://skills/{name} resources.",
+      },
+    };
     return {
-      content: [{ type: "text", text: JSON.stringify(stats, null, 2) }],
+      content: [{ type: "text", text: JSON.stringify(statsWithSkills, null, 2) }],
     };
   },
 );
@@ -1103,10 +1198,14 @@ Without a prefix, a major-version diff can list hundreds of added paths.
         .string()
         .optional()
         .describe("Optional: scope the diff to a command subtree (e.g., '/ip/firewall', '/routing/bgp', '/interface/bridge')"),
+      arch: z
+        .string()
+        .optional()
+        .describe("Filter by CPU architecture: 'x86' or 'arm64'. Omit to diff all commands regardless of architecture."),
     },
   },
-  async ({ from_version, to_version, path_prefix }) => {
-    const result = diffCommandVersions(from_version, to_version, path_prefix);
+  async ({ from_version, to_version, path_prefix, arch }) => {
+    const result = diffCommandVersions(from_version, to_version, path_prefix, arch);
     if (result.added_count === 0 && result.removed_count === 0) {
       const hint = [
         result.note ?? null,

package/src/paths.ts

@@ -55,11 +55,18 @@ export function resolveBaseDir(srcDir: string): string {
 
 /**
  * Resolve the full path to ros-help.db.
- * DB_PATH env var overrides all detection logic.
+ * Priority: DB_PATH env var → --db CLI flag → auto-detect.
  */
 export function resolveDbPath(srcDir: string): string {
   const envPath = process.env.DB_PATH?.trim();
   if (envPath) return envPath;
+
+  // --db flag parsed at init time so ESM static imports don't race it
+  const dbArgIdx = process.argv.indexOf("--db");
+  if (dbArgIdx !== -1 && process.argv[dbArgIdx + 1]) {
+    return process.argv[dbArgIdx + 1];
+  }
+
   return path.join(resolveBaseDir(srcDir), "ros-help.db");
 }
 
@@ -79,7 +86,7 @@ export function detectMode(srcDir: string): InvocationMode {
  * Stamped into the DB via `PRAGMA user_version` by initDb() and checked at MCP
  * startup to detect stale DBs for bunx users who auto-update the package.
  */
-export const SCHEMA_VERSION = 2;
+export const SCHEMA_VERSION = 4;
 
 /**
  * Resolve the version string.