@tikoci/rosetta 0.8.11 → 0.8.12

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/package.json

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

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}.`);
     }
   }

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

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) {