@tikoci/rosetta 0.8.11 → 0.8.13

package/README.md

@@ -118,7 +118,7 @@ This downloads the database and prints config snippets for all supported MCP cli
 Need to force a database reload later? Use:
 
 ```sh
-bunx @tikoci/rosetta --refresh
+bunx @tikoci/rosetta@latest --refresh
 ```
 
 ### Configure your MCP client

package/matrix/CLAUDE.md

@@ -2,6 +2,6 @@
 
 Per-device hardware specs from mikrotik.com/products/matrix. Date-stamped snapshots stored in git.
 
-See main [CLAUDE.md](../CLAUDE.md) → "Product Matrix (CSV)" under Source Details for full schema, download instructions, and column documentation.
+See [DESIGN.md](../DESIGN.md) for product-matrix provenance and naming caveats, and [MANUAL.md](../MANUAL.md) for the re-extraction workflow.
 
-Extraction: `bun run src/extract-devices.ts` (or `make extract-devices`). Idempotent — deletes and re-inserts all rows.
+Extraction: `bun run src/extract-devices.ts` (or `make extract-devices`). Idempotent — deletes and re-inserts all rows.

package/package.json

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

package/src/browse-parity.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { EXPECTED_TOOLS } from "./mcp-contract.test.ts";
+
+const ROOT = path.resolve(import.meta.dirname, "..");
+const configuredDbPath = process.env.TEST_DB_PATH?.trim();
+const DB_PATH = configuredDbPath ? path.resolve(ROOT, configuredDbPath) : path.join(ROOT, "ros-help.db");
+const hasTestDb = existsSync(DB_PATH);
+const dbWasExplicitlyConfigured = Boolean(configuredDbPath);
+const skipReason = `No populated test database at ${DB_PATH}; set TEST_DB_PATH or place ros-help.db at repo root to run this parity check.`;
+
+function stripAnsi(s: string): string {
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape matching requires control chars
+  return s.replace(/\x1b\][^\x07]*\x07/g, "").replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+function runBrowseHelp(): string {
+  if (!existsSync(DB_PATH)) {
+    throw new Error(`Expected populated test database at ${DB_PATH}.`);
+  }
+
+  const proc = Bun.spawnSync(["bun", "src/browse.ts", "--once", ".help"], {
+    cwd: ROOT,
+    env: { ...process.env, DB_PATH },
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  if (proc.exitCode !== 0) {
+    throw new Error(
+      `browse --once .help failed (exit ${proc.exitCode})\nstdout:\n${proc.stdout.toString()}\n\nstderr:\n${proc.stderr.toString()}`,
+    );
+  }
+
+  return proc.stdout.toString();
+}
+
+function extractToolDotCommands(helpOutput: string): string[] {
+  const seen = new Set<string>();
+  for (const line of stripAnsi(helpOutput).split("\n")) {
+    const match = line.match(/^\s*\.(routeros_[a-z_]+)\b/);
+    if (match) seen.add(match[1]);
+  }
+  return [...seen].sort();
+}
+
+describe.skipIf(!hasTestDb && !dbWasExplicitlyConfigured)(
+  hasTestDb || dbWasExplicitlyConfigured
+    ? "browse TUI ↔ MCP parity"
+    : `browse TUI ↔ MCP parity [skipped: ${skipReason}]`,
+  () => {
+  test("browse .help lists a dot-command for every MCP tool", () => {
+    const actual = extractToolDotCommands(runBrowseHelp());
+    expect(actual).toEqual([...EXPECTED_TOOLS].sort());
+  });
+});

package/src/cli-help.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+const ROOT = path.resolve(import.meta.dirname, "..");
+const INTENTIONAL_OMISSIONS = new Set<string>();
+
+function readText(relPath: string): string {
+  return readFileSync(path.join(ROOT, relPath), "utf-8");
+}
+
+function normalizeEntry(value: string): string {
+  const trimmed = value.trim().replace(/^`|`$/g, "");
+  return trimmed === "*(none)*" ? "(none)" : trimmed;
+}
+
+function readManualCliFlags(): string[] {
+  const manual = readText("MANUAL.md");
+  const sectionMatch = manual.match(/## CLI Flags\n\n([\s\S]*?)\n## /);
+  if (!sectionMatch) {
+    throw new Error("Could not locate CLI Flags table in MANUAL.md.");
+  }
+
+  const entries = new Set<string>();
+  for (const line of sectionMatch[1].split("\n")) {
+    if (!line.startsWith("|")) continue;
+    const cells = line.split("|").map((cell) => cell.trim()).filter(Boolean);
+    if (cells.length < 2) continue;
+    if (cells[0] === "Flag" || /^-+$/.test(cells[0])) continue;
+    entries.add(normalizeEntry(cells[0]));
+  }
+  return [...entries].sort();
+}
+
+function runHelp(): string {
+  const proc = Bun.spawnSync(["bun", "src/mcp.ts", "--help"], {
+    cwd: ROOT,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  if (proc.exitCode !== 0) {
+    throw new Error(
+      `src/mcp.ts --help failed (exit ${proc.exitCode})\nstdout:\n${proc.stdout.toString()}\n\nstderr:\n${proc.stderr.toString()}`,
+    );
+  }
+
+  return proc.stdout.toString();
+}
+
+function readHelpCliEntries(helpText: string): string[] {
+  const entries = new Set<string>();
+
+  for (const line of helpText.split("\n")) {
+    const usageMatch = line.match(/^\s*rosetta(?:\s+(.*?))?\s{2,}\S/);
+    if (usageMatch) {
+      const command = usageMatch[1]?.trim() ?? "";
+      entries.add(command === "" ? "(none)" : command);
+      continue;
+    }
+
+    const optionMatch = line.match(/^\s*(--[a-z-]+(?: <[^>]+>)?)\s{2,}\S/);
+    if (optionMatch) {
+      entries.add(optionMatch[1]);
+    }
+  }
+
+  return [...entries].sort();
+}
+
+describe("CLI help ↔ MANUAL flag parity", () => {
+  test("MANUAL CLI Flags table matches src/mcp.ts --help", () => {
+    const documented = readManualCliFlags().filter((entry) => !INTENTIONAL_OMISSIONS.has(entry));
+    const fromHelp = readHelpCliEntries(runHelp()).filter((entry) => !INTENTIONAL_OMISSIONS.has(entry));
+
+    expect(fromHelp).toEqual(documented);
+  });
+});

package/src/mcp-contract.test.ts

@@ -9,7 +9,8 @@
  *           and titles so DB refreshes don't churn snapshots.
  *
  * These are fast, deterministic, CI-runnable structural tests. No LLM calls,
- * no network. Use the real local DB (ros-help.db) for stable FTS results.
+ * no network. Block A always runs; set ROSETTA_REAL_DB_TESTS=1 to exercise
+ * Blocks B/C against a real populated DB for stable FTS results.
  *
  * When adding/removing/renaming a tool: update EXPECTED_TOOLS below AND add
  * a CHANGELOG entry under [Unreleased] → Added/Changed/Removed. The test is
@@ -20,52 +21,67 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 
 const ROOT = path.resolve(import.meta.dirname, "..");
+const runRealDbBlocks = process.env.ROSETTA_REAL_DB_TESTS === "1";
 
 // Block A (static file parse) runs unconditionally. Blocks B and C need the
-// real populated DB singleton. When another test file (extract-videos,
-// query, etc.) has already pinned the db.ts singleton to :memory:, we skip
-// the DB-dependent blocks — running `bun test src/mcp-contract.test.ts`
-// alone exercises them, and CI's `bun test` still gets Block A coverage.
-const { searchAll } = await import("./query.ts");
-const { DB_PATH, getDbStats } = await import("./db.ts");
-
-// getDbStats() throws if tables don't exist (clean checkout before any DB build).
-// Guard defensively: any failure → treat as "DB not usable" and skip B/C.
-function dbPagesOrZero(): number {
+// real populated DB singleton, but opening db.ts during the main `bun test`
+// suite can poison query.test.ts's DB-wipe guard. Keep the real-DB imports
+// behind an explicit opt-in so the shared suite stays on `:memory:` and the
+// dedicated release/real-DB runs can still exercise Blocks B/C.
+let searchAll: typeof import("./query.ts").searchAll | undefined;
+let realDbPath = ":memory:";
+let dbPages = 0;
+
+if (runRealDbBlocks) {
+  const queryModule = await import("./query.ts");
+  const dbModule = await import("./db.ts");
+  searchAll = queryModule.searchAll;
+  realDbPath = dbModule.DB_PATH;
   try {
-    return getDbStats().pages;
+    dbPages = dbModule.getDbStats().pages;
   } catch {
-    return 0;
+    dbPages = 0;
   }
 }
 
-const dbPages = dbPagesOrZero();
-const dbIsReal = DB_PATH !== ":memory:" && dbPages > 100;
+function requireSearchAll(): typeof import("./query.ts").searchAll {
+  if (!searchAll) {
+    throw new Error(
+      "searchAll unavailable; set ROSETTA_REAL_DB_TESTS=1 to enable real-DB contract blocks.",
+    );
+  }
+  return searchAll;
+}
+
+const dbIsReal = runRealDbBlocks && realDbPath !== ":memory:" && dbPages > 100;
 const skipReason = dbIsReal
   ? ""
-  : `DB singleton is "${DB_PATH}" (pages=${dbPages}); run \`bun test src/mcp-contract.test.ts\` solo against a populated DB for Blocks B/C.`;
+  : runRealDbBlocks
+    ? `DB singleton is "${realDbPath}" (pages=${dbPages}); run \`ROSETTA_REAL_DB_TESTS=1 bun test src/mcp-contract.test.ts\` against a populated DB for Blocks B/C.`
+    : "real-DB blocks are opt-in; set ROSETTA_REAL_DB_TESTS=1 and run this file against a populated DB for Blocks B/C.";
 
 // ---------------------------------------------------------------------------
 // Block A: Frozen tool registry
 // ---------------------------------------------------------------------------
 
+export const EXPECTED_TOOLS = [
+  "routeros_search",
+  "routeros_get_page",
+  "routeros_lookup_property",
+  "routeros_explain_command",
+  "routeros_command_tree",
+  "routeros_stats",
+  "routeros_search_changelogs",
+  "routeros_dude_search",
+  "routeros_dude_get_page",
+  "routeros_command_version_check",
+  "routeros_command_diff",
+  "routeros_device_lookup",
+  "routeros_search_tests",
+  "routeros_current_versions",
+] as const;
+
 describe("Frozen tool registry", () => {
-  const EXPECTED_TOOLS = [
-    "routeros_search",
-    "routeros_get_page",
-    "routeros_lookup_property",
-    "routeros_explain_command",
-    "routeros_command_tree",
-    "routeros_stats",
-    "routeros_search_changelogs",
-    "routeros_dude_search",
-    "routeros_dude_get_page",
-    "routeros_command_version_check",
-    "routeros_command_diff",
-    "routeros_device_lookup",
-    "routeros_search_tests",
-    "routeros_current_versions",
-  ];
 
   test("exactly 14 tools registered", () => {
     const mcpSrc = readFileSync(path.join(ROOT, "src/mcp.ts"), "utf-8");
@@ -74,7 +90,7 @@ describe("Frozen tool registry", () => {
     const foundTools = Array.from(toolMatches, (m) => m[1]);
 
     expect(foundTools.length).toBe(14);
-    expect(foundTools.sort()).toEqual(EXPECTED_TOOLS.sort());
+    expect(foundTools.sort()).toEqual([...EXPECTED_TOOLS].sort());
   });
 
   test("all tools have workflow arrow (→) in description", () => {
@@ -156,7 +172,7 @@ describe.skipIf(!dbIsReal)(`Token-budget guardrails${dbIsReal ? "" : ` [skipped:
 
   for (const { query, limit, budget } of QUERIES) {
     test(`"${query}" (limit=${limit}) ≤ ${budget} tokens`, () => {
-      const result = searchAll(query, limit);
+      const result = requireSearchAll()(query, limit);
       const tokens = estimateTokens(result);
 
       if (tokens > budget) {
@@ -216,7 +232,7 @@ describe.skipIf(!dbIsReal)(`Response-shape invariants${dbIsReal ? "" : ` [skippe
 
   for (const { query, limit, classifier_expected } of INVARIANTS) {
     test(`shape: "${query}"`, () => {
-      const result = searchAll(query, limit);
+      const result = requireSearchAll()(query, limit);
 
       // Top-level keys
       expect(result).toHaveProperty("query", query);

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

@@ -0,0 +1,170 @@
+/**
+ * mcp-stdio-client.test.ts — Integration test for the real MCP stdio path.
+ *
+ * Spawns `bun src/mcp.ts` via the SDK's StdioClientTransport and exercises the
+ * real client handshake, tool listing, tool calling, resource listing, and
+ * shutdown flow. This catches stdout pollution and JSON-RPC framing bugs that
+ * in-process tests cannot.
+ */
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const ROOT = path.resolve(import.meta.dirname, "..");
+const configuredDbPath = process.env.TEST_DB_PATH?.trim();
+const DB_PATH = configuredDbPath ? path.resolve(ROOT, configuredDbPath) : path.join(ROOT, "ros-help.db");
+const hasTestDb = existsSync(DB_PATH);
+const dbWasExplicitlyConfigured = Boolean(configuredDbPath);
+const skipReason = `No populated test database at ${DB_PATH}; set TEST_DB_PATH or place ros-help.db at repo root to run this integration test.`;
+
+const EXPECTED_TOOLS = [
+  "routeros_search",
+  "routeros_get_page",
+  "routeros_lookup_property",
+  "routeros_explain_command",
+  "routeros_command_tree",
+  "routeros_stats",
+  "routeros_search_changelogs",
+  "routeros_dude_search",
+  "routeros_dude_get_page",
+  "routeros_command_version_check",
+  "routeros_command_diff",
+  "routeros_device_lookup",
+  "routeros_search_tests",
+  "routeros_current_versions",
+];
+
+const FIXED_RESOURCE_URIS = [
+  "rosetta://datasets/device-test-results.csv",
+  "rosetta://datasets/devices.csv",
+  "rosetta://schema-guide.md",
+  "rosetta://schema.sql",
+  "rosetta://skills",
+];
+
+function asRecord(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Expected ${label} to be an object.`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function parseJsonToolResult(value: unknown): Record<string, unknown> {
+  const result = asRecord(value, "tool result");
+  if (!Array.isArray(result.content) || result.content.length === 0) {
+    throw new Error("Expected tool result content[0] to exist.");
+  }
+
+  const firstContent = asRecord(result.content[0], "tool result content[0]");
+  if (firstContent.type !== "text" || typeof firstContent.text !== "string") {
+    throw new Error("Expected tool result content[0] to be text.");
+  }
+
+  return asRecord(JSON.parse(firstContent.text), "parsed tool JSON");
+}
+
+function buildDiagnostics(errors: Error[], stderr: string[]): string {
+  const sections: string[] = [];
+  if (errors.length > 0) {
+    sections.push(`transport/client errors:\n${errors.map((error) => error.stack ?? error.message).join("\n\n")}`);
+  }
+  if (stderr.length > 0) {
+    sections.push(`server stderr:\n${stderr.join("")}`);
+  }
+  return sections.length > 0 ? `\n\n${sections.join("\n\n")}` : "";
+}
+
+describe.skipIf(!hasTestDb && !dbWasExplicitlyConfigured)(
+  hasTestDb || dbWasExplicitlyConfigured
+    ? "stdio transport: real MCP client"
+    : `stdio transport: real MCP client [skipped: ${skipReason}]`,
+  () => {
+  let client: Client | undefined;
+
+  afterEach(async () => {
+    if (client) {
+      await client.close().catch(() => undefined);
+      client = undefined;
+    }
+  });
+
+  test("real stdio client lists tools, calls routeros_search, lists resources, and closes cleanly", async () => {
+    if (!hasTestDb) {
+      throw new Error(`Expected populated test database at ${DB_PATH}.`);
+    }
+
+    const transport = new StdioClientTransport({
+      command: "bun",
+      args: ["src/mcp.ts"],
+      cwd: ROOT,
+      env: { ...process.env, DB_PATH },
+      stderr: "pipe",
+    });
+
+    const stderrChunks: string[] = [];
+    transport.stderr?.on("data", (chunk) => {
+      stderrChunks.push(chunk.toString());
+    });
+
+    const transportErrors: Error[] = [];
+    let resolveClosed!: () => void;
+    const closeSeen = new Promise<void>((resolve) => {
+      resolveClosed = resolve;
+    });
+    let closeCount = 0;
+
+    client = new Client({ name: "stdio-test-client", version: "1.0.0" });
+    client.onerror = (error) => {
+      transportErrors.push(error);
+    };
+    client.onclose = () => {
+      closeCount += 1;
+      resolveClosed();
+    };
+
+    await client.connect(transport);
+    expect(client.getServerVersion()?.name).toBe("rosetta");
+
+    const tools = await client.listTools();
+    const toolNames = tools.tools.map((tool) => tool.name).sort();
+    expect(toolNames).toEqual([...EXPECTED_TOOLS].sort());
+
+    const searchPayload = parseJsonToolResult(await client.callTool({
+      name: "routeros_search",
+      arguments: { query: "/ip/firewall/filter", limit: 3 },
+    }));
+    expect(Array.isArray(searchPayload.pages)).toBe(true);
+    expect((searchPayload.pages as unknown[]).length).toBeGreaterThan(0);
+    expect(searchPayload.related).toBeDefined();
+    expect(typeof searchPayload.related).toBe("object");
+    expect(Array.isArray(searchPayload.related)).toBe(false);
+    expect(Object.keys(asRecord(searchPayload.related, "routeros_search.related")).length).toBeGreaterThan(0);
+
+    const resources = await client.listResources();
+    const fixedResourceUris = resources.resources
+      .map((resource) => resource.uri)
+      .filter((uri) => !uri.startsWith("rosetta://skills/"))
+      .sort();
+    expect(fixedResourceUris).toEqual([...FIXED_RESOURCE_URIS].sort());
+
+    if (transportErrors.length > 0) {
+      throw new Error(`Unexpected stdio transport/client error before close.${buildDiagnostics(transportErrors, stderrChunks)}`);
+    }
+
+    await client.close();
+    client = undefined;
+    await Promise.race([
+      closeSeen,
+      Bun.sleep(2_000).then(() => {
+        throw new Error(`Timed out waiting for stdio client/server close.${buildDiagnostics(transportErrors, stderrChunks)}`);
+      }),
+    ]);
+
+    expect(closeCount).toBe(1);
+    if (transportErrors.length > 0) {
+      throw new Error(`Unexpected stdio transport/client error during close.${buildDiagnostics(transportErrors, stderrChunks)}`);
+    }
+  }, 60_000);
+});

package/src/mcp.ts

@@ -61,14 +61,14 @@ function link(url: string, display?: string): string {
  */
 async function ensureDbReady(log: (msg: string) => void): Promise<void> {
   const { resolveDbPath, SCHEMA_VERSION, resolveVersion } = await import("./paths.ts");
-  const { downloadDb, hasMinimumDbContent, probeDb, cleanupStaleTempArtifacts } = await import("./setup.ts");
+  const { cleanupAbandonedTempArtifacts, downloadDb, hasMinimumDbContent, probeDb } = await import("./setup.ts");
 
   const dbPath = resolveDbPath(import.meta.dirname);
   const runningVersion = resolveVersion(import.meta.dirname);
 
-  // Always clean stale .tmp.* artifacts from previous failed runs, regardless of
-  // whether a download is needed this time.
-  cleanupStaleTempArtifacts(dbPath);
+  // Always clean abandoned .tmp.* artifacts from previous failed runs when no
+  // active download lock exists, regardless of whether a download is needed now.
+  cleanupAbandonedTempArtifacts(dbPath);
 
   let p = probeDb(dbPath);
 
@@ -80,7 +80,7 @@ async function ensureDbReady(log: (msg: string) => void): Promise<void> {
       log("Database downloaded successfully.");
     } catch (e) {
       log(`Auto-download failed: ${e instanceof Error ? e.message : e}`);
-      log(`Close other rosetta clients and run: bunx @tikoci/rosetta --refresh`);
+      log(`Close other rosetta clients and run: bunx @tikoci/rosetta@latest --refresh`);
       throw new Error(`Unable to start rosetta without a usable database at ${dbPath}.`);
     }
   }
@@ -139,6 +139,8 @@ if (args.includes("--help") || args.includes("-h")) {
   console.log("  rosetta              Start MCP server (stdio transport)");
   console.log("  rosetta --http       Start with Streamable HTTP transport");
   console.log("  rosetta browse       Interactive terminal browser");
+  console.log("  rosetta browse <cmd> [args]  Run any TUI command once, then open REPL");
+  console.log("  rosetta browse --once <cmd>  Execute any TUI command and exit");
   console.log("  rosetta --setup      Download database + print MCP client config");
   console.log("  rosetta --setup --force  Re-download database");
   console.log("  rosetta --refresh    Shortcut for --setup --force");
@@ -155,6 +157,8 @@ if (args.includes("--help") || args.includes("-h")) {
   console.log("  DB_PATH  Absolute path to ros-help.db (optional)");
   console.log("  PORT     HTTP listen port (lower precedence than --port)");
   console.log("  HOST     HTTP bind address (lower precedence than --host)");
+  console.log("  TLS_CERT_PATH  TLS certificate path (lower precedence than --tls-cert)");
+  console.log("  TLS_KEY_PATH   TLS private key path (lower precedence than --tls-key)");
   console.log();
   console.log(`Quick start:  bunx @tikoci/rosetta --setup`);
   console.log(`Project:      ${link("https://github.com/tikoci/rosetta")}`);

package/src/release.test.ts

@@ -225,9 +225,16 @@ describe("setup.ts", () => {
   test("setup.ts cleans temp DB artifacts instead of accumulating stale .tmp files", () => {
     const src = readText("src/setup.ts");
     expect(src).toContain("cleanupStaleTempArtifacts");
+    expect(src).toContain("cleanupAbandonedTempArtifacts");
     expect(src).toContain("tryUnlinkDbSidecars(tmpPath)");
   });
 
+  test("setup.ts finalizes probe statements before renaming temp DBs", () => {
+    const src = readText("src/setup.ts");
+    expect(src).toContain("stmt.finalize()");
+    expect(src).toContain("sqliteGet");
+  });
+
   test("no DB open uses { readonly: true } (WAL-shm init trap on macOS)", () => {
     // Freshly-renamed WAL-mode DBs fail to open readonly on macOS until a
     // read-write connection initialises the .shm file. downloadDb explicitly
@@ -281,12 +288,8 @@ describe("Makefile", () => {
     expect(makefile).toContain("preflight:");
   });
 
-  test("has build-release target", () => {
-    expect(makefile).toContain("build-release:");
-  });
-
-  test("has release target", () => {
-    expect(makefile).toContain("release:");
+  test("has verify target", () => {
+    expect(makefile).toContain("verify:");
   });
 
   test("has extract-videos target", () => {
@@ -343,12 +346,8 @@ describe("Makefile", () => {
     expect(phonyBlock).toContain("extract-dude");
   });
 
-  test("release depends on preflight", () => {
-    expect(makefile).toMatch(/^release:.*preflight/m);
-  });
-
-  test("release depends on build-release", () => {
-    expect(makefile).toMatch(/^release:.*build-release/m);
+  test("extract target includes Dude cache import", () => {
+    expect(makefile).toMatch(/^extract:.*extract-dude-from-cache/m);
   });
 
   test("extract target includes skills", () => {
@@ -359,10 +358,6 @@ describe("Makefile", () => {
     expect(makefile).toMatch(/^extract-full:.*extract-skills/m);
   });
 
-  test("extract target includes Dude cache import", () => {
-    expect(makefile).toMatch(/^extract:.*extract-dude-from-cache/m);
-  });
-
   test("extract-full target includes Dude cache import", () => {
     expect(makefile).toMatch(/^extract-full:.*extract-dude-from-cache/m);
   });
@@ -370,12 +365,6 @@ describe("Makefile", () => {
   test("preflight checks dirty tree", () => {
     expect(makefile).toContain("git diff --quiet");
   });
-
-  test("FORCE flag controls tag behavior", () => {
-    expect(makefile).toContain("FORCE");
-    expect(makefile).toContain("git tag -f");
-    expect(makefile).toContain("--clobber");
-  });
 });
 
 // ---------------------------------------------------------------------------
@@ -474,13 +463,34 @@ describe("release.yml", () => {
   test("runs MCP contract tests against the real built DB before eval/release", () => {
     const src = readText(".github/workflows/release.yml");
     const contractIdx = src.indexOf("bun test src/mcp-contract.test.ts");
-    const evalIdx = src.indexOf("MCP retrieval eval (Phase 0, non-blocking)");
+    const evalIdx = src.indexOf("MCP retrieval eval (Phase 0)");
     const buildIdx = src.indexOf("Build release artifacts");
     expect(contractIdx).toBeGreaterThan(0);
     expect(contractIdx).toBeLessThan(evalIdx);
     expect(contractIdx).toBeLessThan(buildIdx);
   });
 
+  test("runs Phase 1 self-supervised eval against the built DB and appends a summary result", () => {
+    const src = readText(".github/workflows/release.yml");
+    const phase0Idx = mustIndex(src, "MCP retrieval eval (Phase 0)");
+    const phase1Idx = mustIndex(
+      src,
+      "MCP retrieval eval (Phase 1, self-supervised, non-blocking)",
+    );
+    const buildIdx = mustIndex(src, "Build release artifacts");
+    const phase1Block = src.slice(phase1Idx, buildIdx);
+
+    expect(phase1Idx).toBeGreaterThan(phase0Idx);
+    expect(phase1Idx).toBeLessThan(buildIdx);
+    expect(phase1Block).toContain("continue-on-error: true");
+    expect(phase1Block).toContain("bun run src/eval/self-supervised.ts");
+    expect(phase1Block).toContain(
+      "## Phase 1 retrieval eval (self-supervised)",
+    );
+    expect(phase1Block).toContain("Result: ✅ pass");
+    expect(phase1Block).toContain("Result: ⚠️ non-blocking failure");
+  });
+
   test("creates GitHub Release", () => {
     const src = readText(".github/workflows/release.yml");
     expect(src).toContain("gh release create");
@@ -536,6 +546,18 @@ describe("release.yml", () => {
     expect(src).toContain("NPM_TOKEN");
   });
 
+  test("bunx-smoke covers windows with bash steps and a runner temp log", () => {
+    const src = readText(".github/workflows/release.yml");
+    const bunxIdx = mustIndex(src, "bunx-smoke:");
+    const bumpIdx = mustIndex(src, "bump-version:");
+    const bunxBlock = src.slice(bunxIdx, bumpIdx);
+
+    expect(bunxBlock).toContain("windows-latest");
+    expect(bunxBlock).toContain("shell: bash");
+    expect(bunxBlock).toContain("RUNNER_TEMP");
+    expect(bunxBlock).not.toContain("mktemp");
+  });
+
   test("validates DB content before publishing (regression: v0.7.6 shipped 3 pages)", () => {
     const src = readText(".github/workflows/release.yml");
     // Hard guard step that hard-fails the workflow if the built DB is degenerate.

package/src/setup.test.ts

@@ -8,7 +8,7 @@
 
 import sqlite from "bun:sqlite";
 import { afterAll, describe, expect, test } from "bun:test";
-import { existsSync, mkdtempSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 
@@ -21,6 +21,7 @@ afterAll(() => {
 });
 
 const {
+  cleanupAbandonedTempArtifacts,
   cleanupStaleTempArtifacts,
   dbDownloadUrls,
   probeDb,
@@ -178,6 +179,19 @@ describe("probeDb", () => {
     expect(probe?.releaseTag).toBe("v0.0.0-test");
   });
 
+  test("closes statements so a probed temp DB can be renamed immediately", () => {
+    const dbFile = path.join(tmp, "probe-rename-source.db");
+    const renamed = path.join(tmp, "probe-rename-dest.db");
+    writeUsableDb(dbFile, "v0.0.0-rename");
+
+    const probe = probeDb(dbFile);
+    expect(probe?.releaseTag).toBe("v0.0.0-rename");
+
+    renameSync(dbFile, renamed);
+    expect(existsSync(dbFile)).toBe(false);
+    expect(probeDb(renamed)?.releaseTag).toBe("v0.0.0-rename");
+  });
+
   test("opens a freshly-renamed WAL-mode DB with no .shm sibling", () => {
     // Reproduces the exact state downloadDb leaves the DB in: journal_mode=WAL
     // on disk, but the .wal/.shm siblings are deleted just before the rename.
@@ -242,3 +256,39 @@ describe("cleanupStaleTempArtifacts", () => {
     }
   });
 });
+
+describe("cleanupAbandonedTempArtifacts", () => {
+  test("removes fresh temp artifacts when no download lock exists", () => {
+    const dbFile = path.join(tmp, "cleanup-abandoned.db");
+    const artifacts = [
+      `${dbFile}.tmp.222`,
+      `${dbFile}.tmp.222-wal`,
+      `${dbFile}.tmp.222-shm`,
+    ];
+
+    for (const artifact of artifacts) {
+      writeFileSync(artifact, "x");
+    }
+
+    expect(cleanupAbandonedTempArtifacts(dbFile)).toBe(3);
+    for (const artifact of artifacts) {
+      expect(existsSync(artifact)).toBe(false);
+    }
+  });
+
+  test("preserves fresh temp artifacts while a download lock exists", () => {
+    const dbFile = path.join(tmp, "cleanup-active.db");
+    const artifact = `${dbFile}.tmp.333`;
+    writeFileSync(artifact, "x");
+    const lock = tryAcquireDownloadLock(dbFile);
+    expect(lock).not.toBeNull();
+
+    try {
+      expect(cleanupAbandonedTempArtifacts(dbFile)).toBe(0);
+      expect(existsSync(artifact)).toBe(true);
+    } finally {
+      releaseDownloadLock(lock);
+      unlinkSync(artifact);
+    }
+  });
+});

package/src/setup.ts

@@ -47,6 +47,18 @@ type DbProbe = {
   releaseTag: string | null;
 };
 
+type SQLiteStatement = {
+  get: (...params: unknown[]) => unknown;
+  finalize: () => void;
+};
+
+type SQLiteDatabase = {
+  prepare: (sql: string) => SQLiteStatement;
+  close: () => void;
+};
+
+type SQLiteConstructor = new (path: string) => SQLiteDatabase;
+
 type DownloadLockHandle = {
   fd: number;
   path: string;
@@ -98,20 +110,20 @@ export function probeDb(dbPath: string): {
 } | null {
   if (!looksLikeSqliteFile(dbPath)) return null;
 
+  let check: SQLiteDatabase | null = null;
   try {
-    const { default: sqlite } = require("bun:sqlite");
-    const check = new sqlite(dbPath);
-    const ver = check.prepare("PRAGMA user_version").get() as { user_version: number };
-    const pages = check.prepare("SELECT COUNT(*) AS c FROM pages").get() as { c: number };
-    const cmds = check.prepare("SELECT COUNT(*) AS c FROM commands").get() as { c: number };
+    const { default: sqlite } = require("bun:sqlite") as { default: SQLiteConstructor };
+    check = new sqlite(dbPath);
+    const ver = sqliteGet<{ user_version: number }>(check, "PRAGMA user_version");
+    const pages = sqliteGet<{ c: number }>(check, "SELECT COUNT(*) AS c FROM pages");
+    const cmds = sqliteGet<{ c: number }>(check, "SELECT COUNT(*) AS c FROM commands");
     let releaseTag: string | null = null;
     try {
-      const meta = check.prepare("SELECT value FROM db_meta WHERE key = 'release_tag'").get() as { value: string } | null;
+      const meta = sqliteGet<{ value: string } | null>(check, "SELECT value FROM db_meta WHERE key = 'release_tag'");
       releaseTag = meta?.value ?? null;
     } catch {
       // db_meta missing — pre-v5 schema, leave releaseTag null
     }
-    check.close();
     return {
       schemaVersion: ver.user_version,
       pages: pages.c,
@@ -120,6 +132,23 @@ export function probeDb(dbPath: string): {
     };
   } catch {
     return null;
+  } finally {
+    if (check) {
+      try {
+        check.close();
+      } catch {
+        // best-effort cleanup; a failed probe should never leave a DB handle open
+      }
+    }
+  }
+}
+
+function sqliteGet<T>(db: SQLiteDatabase, sql: string): T {
+  const stmt = db.prepare(sql);
+  try {
+    return stmt.get() as T;
+  } finally {
+    stmt.finalize();
   }
 }
 
@@ -258,18 +287,45 @@ export function cleanupStaleTempArtifacts(dbPath: string, staleMs = DOWNLOAD_LOC
   return removed;
 }
 
-function replaceDbFile(tmpPath: string, dbPath: string): void {
-  try {
-    renameSync(tmpPath, dbPath);
-    return;
-  } catch (e) {
-    const code = e instanceof Error && "code" in e ? e.code : undefined;
-    // Windows can return EBUSY, EPERM, or EEXIST when the destination is open.
-    if (code !== "EBUSY" && code !== "EEXIST" && code !== "EPERM") throw e;
+export function cleanupAbandonedTempArtifacts(dbPath: string): number {
+  if (existsSync(lockPathFor(dbPath))) {
+    return cleanupStaleTempArtifacts(dbPath);
   }
+  return cleanupStaleTempArtifacts(dbPath, -1);
+}
 
-  tryUnlink(dbPath);
-  renameSync(tmpPath, dbPath);
+function isReplaceRaceError(e: unknown): boolean {
+  const code = e instanceof Error && "code" in e ? e.code : undefined;
+  // Windows can return EBUSY, EPERM, or EEXIST when the source or destination is open.
+  return code === "EBUSY" || code === "EEXIST" || code === "EPERM";
+}
+
+async function replaceDbFile(tmpPath: string, dbPath: string): Promise<void> {
+  const deadline = Date.now() + 30_000;
+  let lastError: unknown = null;
+
+  while (Date.now() <= deadline) {
+    try {
+      renameSync(tmpPath, dbPath);
+      return;
+    } catch (e) {
+      if (!isReplaceRaceError(e)) throw e;
+      lastError = e;
+    }
+
+    tryUnlink(dbPath);
+    try {
+      renameSync(tmpPath, dbPath);
+      return;
+    } catch (e) {
+      if (!isReplaceRaceError(e)) throw e;
+      lastError = e;
+    }
+
+    await Bun.sleep(250);
+  }
+
+  throw lastError;
 }
 
 /** Build the version-pinned download URL. Falls back to /latest/ when no version.
@@ -418,9 +474,9 @@ export async function downloadDb(
       if (probe.schemaVersion !== SCHEMA_VERSION) {
         cleanupDbArtifacts(tmpPath);
         lastError = new Error(
-          `Downloaded DB schema=${probe.schemaVersion} does not match this rosetta build (expected ${SCHEMA_VERSION}). ` +
+            `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 \`bun pm cache rm\` and relaunch to pick up the latest package.`,
+            `Run: bunx @tikoci/rosetta@latest --refresh`,
         );
         if (isLast) throw lastError;
         log(`  ${lastError.message}`);
@@ -440,7 +496,7 @@ export async function downloadDb(
       try {
         tryUnlinkDbSidecars(tmpPath);
         tryUnlinkDbSidecars(dbPath);
-        replaceDbFile(tmpPath, dbPath);
+        await replaceDbFile(tmpPath, dbPath);
       } catch (e) {
         const existingProbe = probeDb(dbPath);
         if (hasMinimumDbContent(existingProbe) && existingProbe.schemaVersion === probe.schemaVersion && existingProbe.releaseTag === probe.releaseTag) {