@tikoci/rosetta 0.8.13 → 0.9.2

package/README.md

@@ -1,6 +1,6 @@
 # rosetta
 
-MCP server that gives AI assistants searchable access to the complete [MikroTik RouterOS documentation](https://help.mikrotik.com/docs/spaces/ROS/overview) — 317 pages, 4,860 properties, 40,000-entry command tree, hardware specs for 144 products, 518 YouTube video transcripts, and direct links to help.mikrotik.com.
+MCP server that gives AI assistants searchable access to MikroTik RouterOS documentation — 317 legacy Confluence-export pages, 4,860 properties, 40,000-entry command tree, hardware specs for 144 products, 518 YouTube video transcripts, and direct links to source docs. MikroTik's current help system is the Docusaurus site at <https://manual.mikrotik.com>; rosetta's prose-doc extraction still needs a major migration away from the retired Confluence export.
 
 If you need MikroTik docs, you likely have a MikroTik. Install rosetta once as a container on your router using [RouterOS /app](#install-on-mikrotik-app), and any AI assistant on the network can use it. Or [run it locally](#install-locally-with-bun) on your workstation. **No AI required** — rosetta includes a [terminal browser](#browse-without-ai) for searching the database directly.
 
@@ -12,7 +12,7 @@ Instead of vector embeddings, rosetta uses **SQLite [FTS5](https://www.sqlite.or
 
 | Data Source | Coverage |
 |-------------|----------|
-| Documentation pages | 317 pages (~515K words) from help.mikrotik.com |
+| Documentation pages | 317 pages (~515K words) from the retired help.mikrotik.com Confluence export |
 | Property definitions | 4,860 with types, defaults, descriptions |
 | Command tree | 5,114 commands, 551 dirs, 34K arguments |
 | Version history | 46 RouterOS versions tracked (7.9–7.23beta2) |
@@ -21,13 +21,13 @@ Instead of vector embeddings, rosetta uses **SQLite [FTS5](https://www.sqlite.or
 | YouTube transcripts | 518 videos, ~1,890 chapter-level segments |
 | Callout blocks | 1,034 warnings, notes, and tips |
 
-Documentation covers RouterOS **v7 only**, aligned with the long-term release (~7.22) at export time.
+Documentation covers RouterOS **v7 only**, aligned with the long-term release (~7.22) at the March 2026 Confluence-export time. Future official doc updates are expected on <https://manual.mikrotik.com>, including a Docusaurus CLI Reference generated from `/console/inspect` data.
 
 ---
 
 ## Install on MikroTik (/app)
 
-RouterOS 7.22+ includes the [/app](https://help.mikrotik.com/docs/spaces/ROS/pages/328068) feature for running containers directly on the router. This is the simplest way to deploy rosetta — install once, and any AI assistant on your network can connect to the MCP endpoint URL shown in the router UI.
+RouterOS 7.22+ includes the [/app](https://manual.mikrotik.com/docs/CLI%20Reference/container/app) feature for running containers directly on the router. This is the simplest way to deploy rosetta — install once, and any AI assistant on your network can connect to the MCP endpoint URL shown in the router UI.
 
 **Requirements:** RouterOS 7.22+, x86 or ARM64 architecture (CCR, RB5009, hAP ax series, CHR, etc.), container package installed, device-mode enabled.
 
@@ -49,7 +49,7 @@ After reboot:
 /system/device-mode/update mode=advanced container=yes
 ```
 
-See MikroTik's [Container documentation](https://help.mikrotik.com/docs/spaces/ROS/pages/Container) for full prerequisites and troubleshooting.
+See MikroTik's [Container documentation](https://manual.mikrotik.com/docs/Extended%20features/Container/) for full prerequisites and troubleshooting.
 
 ### 2. Add the rosetta app
 

package/package.json

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

package/src/extract-skills.test.ts

@@ -0,0 +1,39 @@
+import { afterEach, describe, expect, test } from "bun:test";
+
+process.env.DB_PATH = ":memory:";
+
+const { githubApiHeaders } = await import("./extract-skills.ts");
+
+describe("extract-skills GitHub API headers", () => {
+  afterEach(() => {
+    delete process.env.GITHUB_TOKEN;
+    delete process.env.GH_TOKEN;
+  });
+
+  test("keeps unauthenticated headers when no token is configured", () => {
+    delete process.env.GITHUB_TOKEN;
+    delete process.env.GH_TOKEN;
+
+    expect(githubApiHeaders()).toEqual({
+      Accept: "application/vnd.github.v3+json",
+    });
+  });
+
+  test("uses GITHUB_TOKEN for authenticated API requests", () => {
+    process.env.GITHUB_TOKEN = "test-token";
+
+    expect(githubApiHeaders()).toEqual({
+      Accept: "application/vnd.github.v3+json",
+      Authorization: "Bearer test-token",
+    });
+  });
+
+  test("falls back to GH_TOKEN for local authenticated runs", () => {
+    process.env.GH_TOKEN = "gh-token";
+
+    expect(githubApiHeaders()).toEqual({
+      Accept: "application/vnd.github.v3+json",
+      Authorization: "Bearer gh-token",
+    });
+  });
+});

package/src/extract-skills.ts

@@ -70,9 +70,16 @@ function countWords(text: string): number {
 
 // ── GitHub API fetching ──
 
+export function githubApiHeaders(): Record<string, string> {
+  const headers: Record<string, string> = { Accept: "application/vnd.github.v3+json" };
+  const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+  if (token) headers.Authorization = `Bearer ${token}`;
+  return headers;
+}
+
 async function getDefaultBranchSha(): Promise<string> {
   const res = await fetch(`${GITHUB_API_BASE}/commits/HEAD`, {
-    headers: { Accept: "application/vnd.github.v3+json" },
+    headers: githubApiHeaders(),
   });
   if (!res.ok) throw new Error(`Failed to get HEAD SHA: HTTP ${res.status}`);
   const data = (await res.json()) as { sha: string };
@@ -81,7 +88,7 @@ async function getDefaultBranchSha(): Promise<string> {
 
 async function listSkillDirs(sha: string): Promise<string[]> {
   const res = await fetch(`${GITHUB_API_BASE}/contents/?ref=${sha}`, {
-    headers: { Accept: "application/vnd.github.v3+json" },
+    headers: githubApiHeaders(),
   });
   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 }>;
@@ -102,7 +109,7 @@ async function fetchRawFile(sha: string, path: string): Promise<string | null> {
 
 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" },
+    headers: githubApiHeaders(),
   });
   if (!res.ok) {
     if (res.status === 404) return [];
@@ -387,4 +394,6 @@ async function main() {
   populateDb(skills, sha);
 }
 
-await main();
+if (import.meta.main) {
+  await main();
+}

package/src/mcp-stdio-client.test.ts

@@ -109,10 +109,7 @@ describe.skipIf(!hasTestDb && !dbWasExplicitlyConfigured)(
     });
 
     const transportErrors: Error[] = [];
-    let resolveClosed!: () => void;
-    const closeSeen = new Promise<void>((resolve) => {
-      resolveClosed = resolve;
-    });
+    const { promise: closeSeen, resolve: resolveClosed } = Promise.withResolvers<void>();
     let closeCount = 0;
 
     client = new Client({ name: "stdio-test-client", version: "1.0.0" });

package/src/release.test.ts

@@ -411,7 +411,13 @@ describe("release.yml", () => {
 
   test("extracts agent skills in CI", () => {
     const src = readText(".github/workflows/release.yml");
-    expect(src).toContain("extract-skills.ts");
+    const skillsIdx = mustIndex(src, "Extract agent skills from GitHub");
+    const linkIdx = mustIndex(src, "Link commands to pages");
+    const skillsBlock = src.slice(skillsIdx, linkIdx);
+
+    expect(skillsBlock).toContain("extract-skills.ts");
+    expect(skillsBlock).toContain("GITHUB_TOKEN");
+    expect(skillsBlock).toContain("$" + "{{ github.token }}");
   });
 
   test("runs quality gate before release", () => {
@@ -436,6 +442,26 @@ describe("release.yml", () => {
     expect(earlyTestIdx).toBeLessThan(downloadIdx);
   });
 
+  test("preflights npm publish access before release side effects", () => {
+    const src = readText(".github/workflows/release.yml");
+    const preflightIdx = mustIndex(src, "Verify npm publish access");
+    const downloadIdx = mustIndex(src, "Download HTML export");
+    const ociIdx = mustIndex(src, "Build and push OCI images");
+    const releaseIdx = mustIndex(src, "Create or update GitHub Release");
+    const publishIdx = mustIndex(src, "Publish to npm");
+    const preflightBlock = src.slice(preflightIdx, downloadIdx);
+
+    expect(preflightIdx).toBeLessThan(downloadIdx);
+    expect(preflightIdx).toBeLessThan(ociIdx);
+    expect(preflightIdx).toBeLessThan(releaseIdx);
+    expect(preflightIdx).toBeLessThan(publishIdx);
+    expect(preflightBlock).toContain("NODE_AUTH_TOKEN");
+    expect(preflightBlock).toContain("npm whoami");
+    expect(preflightBlock).toContain("npm access list collaborators");
+    expect(preflightBlock).toContain("read-write access");
+    expect(preflightBlock).toContain("npm view");
+  });
+
   test("keeps post-extraction DB-wipe guard after extraction", () => {
     const src = readText(".github/workflows/release.yml");
     const linkIdx = mustIndex(src, "Link commands to pages");
@@ -510,6 +536,8 @@ describe("release.yml", () => {
     const clobberIdx = mustIndex(src, "gh release upload");
     expect(src.slice(clobberIdx, clobberIdx + 120)).toContain("--clobber");
     expect(republishBranchIdx).toBeLessThan(clobberIdx);
+    expect(src).toContain('elif gh release view "$VERSION"');
+    expect(src).toContain("updated before npm publish retry");
 
     expect(src).toContain("if: inputs.republish_assets != true");
     expect(src).toContain("if: inputs.republish_assets == true");
@@ -542,7 +570,7 @@ describe("release.yml", () => {
 
   test("publishes to npm", () => {
     const src = readText(".github/workflows/release.yml");
-    expect(src).toContain("npm publish");
+    expect(src).toContain("npm publish --access public --registry https://registry.npmjs.org/");
     expect(src).toContain("NPM_TOKEN");
   });
 
@@ -566,7 +594,7 @@ describe("release.yml", () => {
     const validateIdx = src.indexOf("Validate DB has expected content");
     const buildIdx = src.indexOf("Build release artifacts");
     const releaseIdx = src.indexOf("gh release create");
-    const npmIdx = src.indexOf("npm publish");
+    const npmIdx = src.indexOf("Publish to npm");
     expect(validateIdx).toBeGreaterThan(0);
     expect(validateIdx).toBeLessThan(buildIdx);
     expect(validateIdx).toBeLessThan(releaseIdx);

package/src/setup.ts

@@ -11,6 +11,7 @@ import { execSync } from "node:child_process";
 import {
   closeSync,
   existsSync,
+  fstatSync,
   openSync,
   readdirSync,
   readSync,
@@ -24,6 +25,7 @@ import { gunzipSync } from "bun";
 import { detectMode, resolveBaseDir, resolveDbPath, resolveVersion, SCHEMA_VERSION } from "./paths.ts";
 
 declare const REPO_URL: string;
+const REPLACE_DB_TIMEOUT_MS = 30_000;
 
 const GITHUB_REPO =
   typeof REPO_URL !== "undefined" ? REPO_URL : "tikoci/rosetta";
@@ -72,14 +74,12 @@ function dbHasData(dbPath: string): boolean {
 }
 
 function looksLikeSqliteFile(dbPath: string): boolean {
-  if (!existsSync(dbPath)) return false;
-
   let fd: number | null = null;
   try {
-    const stats = statSync(dbPath);
+    fd = openSync(dbPath, "r");
+    const stats = fstatSync(fd);
     if (!stats.isFile() || stats.size < SQLITE_MAGIC.length) return false;
 
-    fd = openSync(dbPath, "r");
     const header = Buffer.alloc(SQLITE_MAGIC.length);
     const bytesRead = readSync(fd, header, 0, header.byteLength, 0);
     return bytesRead === header.byteLength && header.toString("utf8") === SQLITE_MAGIC;
@@ -301,7 +301,7 @@ function isReplaceRaceError(e: unknown): boolean {
 }
 
 async function replaceDbFile(tmpPath: string, dbPath: string): Promise<void> {
-  const deadline = Date.now() + 30_000;
+  const deadline = Date.now() + REPLACE_DB_TIMEOUT_MS;
   let lastError: unknown = null;
 
   while (Date.now() <= deadline) {
@@ -310,7 +310,6 @@ async function replaceDbFile(tmpPath: string, dbPath: string): Promise<void> {
       return;
     } catch (e) {
       if (!isReplaceRaceError(e)) throw e;
-      lastError = e;
     }
 
     tryUnlink(dbPath);
@@ -475,8 +474,8 @@ export async function downloadDb(
         cleanupDbArtifacts(tmpPath);
         lastError = new Error(
             `Downloaded DB schema=${probe.schemaVersion} does not match this rosetta build (expected ${SCHEMA_VERSION}). ` +
-            `This usually means the cached package version is older than the published DB. ` +
-            `Run: bunx @tikoci/rosetta@latest --refresh`,
+            `This usually means your MCP client is still using a cached older package version. ` +
+          `Restart the MCP client to let bunx re-resolve the latest package, or run: bunx @tikoci/rosetta@latest --refresh`,
         );
         if (isLast) throw lastError;
         log(`  ${lastError.message}`);