@tikoci/rosetta 0.8.10 → 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.10",
+  "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,47 +61,26 @@ 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 } = await import("./setup.ts");
-  const { default: sqlite } = await import("bun:sqlite");
+  const { cleanupAbandonedTempArtifacts, downloadDb, hasMinimumDbContent, probeDb } = await import("./setup.ts");
 
   const dbPath = resolveDbPath(import.meta.dirname);
   const runningVersion = resolveVersion(import.meta.dirname);
 
-  /** Probe an existing DB. Returns null if the file is missing or unreadable.
-   *  Do NOT pass { readonly: true } — freshly written SQLite WAL-mode files fail
-   *  to open readonly on macOS until a read-write connection initialises the WAL
-   *  shared-memory file. Same gotcha as setup.ts::probeDb. */
-  function probe(): { pages: number; schemaVersion: number; releaseTag: string | null } | null {
-    try {
-      const check = new sqlite(dbPath);
-      const pages = (check.prepare("SELECT COUNT(*) AS c FROM pages").get() as { c: number }).c;
-      const ver = (check.prepare("PRAGMA user_version").get() as { user_version: number }).user_version;
-      let releaseTag: string | null = null;
-      try {
-        const meta = check.prepare("SELECT value FROM db_meta WHERE key = 'release_tag'").get() as { value: string } | null;
-        releaseTag = meta?.value ?? null;
-      } catch {
-        // db_meta missing on pre-v5 DBs — leave null
-      }
-      check.close();
-      return { pages, schemaVersion: ver, releaseTag };
-    } catch {
-      return null;
-    }
-  }
+  // 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 = probe();
+  let p = probeDb(dbPath);
 
   // Case 1: DB missing or empty → first-time download.
-  if (!p || p.pages === 0) {
+  if (!hasMinimumDbContent(p)) {
     log(`No usable database at ${dbPath} — downloading...`);
     try {
-      await downloadDb(dbPath, log);
+      p = await downloadDb(dbPath, log);
       log("Database downloaded successfully.");
-      p = probe();
     } 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}.`);
     }
   }
@@ -110,8 +89,8 @@ async function ensureDbReady(log: (msg: string) => void): Promise<void> {
     throw new Error(`Database probe failed after download: ${dbPath}`);
   }
 
-  if (p.pages === 0) {
-    throw new Error(`Database remained empty after recovery: ${dbPath}`);
+  if (!hasMinimumDbContent(p)) {
+    throw new Error(`Database remained incomplete after recovery: ${dbPath}`);
   }
 
   // Case 2: Schema mismatch → re-download, then re-probe and fail hard if
@@ -122,27 +101,25 @@ async function ensureDbReady(log: (msg: string) => void): Promise<void> {
         `Re-downloading database...`,
     );
     try {
-      await downloadDb(dbPath, log);
+      p = await downloadDb(dbPath, log);
     } catch (e) {
       log(`✗ Auto-recovery download failed: ${e instanceof Error ? e.message : e}`);
       log(
         `  This rosetta build (v${runningVersion}) cannot use the existing DB. ` +
-          `Close other rosetta clients, then run \`bun pm cache rm && bunx @tikoci/rosetta --refresh\`.`,
+          `Close other rosetta clients and run: bunx @tikoci/rosetta@latest --refresh`,
       );
       throw new Error(`Unable to recover an incompatible database at ${dbPath}.`);
     }
-    const p2 = probe();
-    if (!p2 || p2.schemaVersion !== SCHEMA_VERSION) {
+    if (!p || !hasMinimumDbContent(p) || p.schemaVersion !== SCHEMA_VERSION) {
       log(
-        `✗ Still incompatible after re-download (DB=${p2?.schemaVersion ?? "unreadable"}, expected=${SCHEMA_VERSION}).`,
+        `✗ Still incompatible after re-download (DB=${p?.schemaVersion ?? "unreadable"}, expected=${SCHEMA_VERSION}).`,
       );
       log(
         `  The published database does not match this rosetta build (v${runningVersion}). ` +
-          `Run \`bun pm cache rm && bunx @tikoci/rosetta --refresh\` to update both the package and the DB.`,
+          `Run: bunx @tikoci/rosetta@latest --refresh`,
       );
       throw new Error(`Database remained incompatible after recovery: ${dbPath}`);
     }
-    p = p2;
   }
 
   // Quietly emit a one-line provenance banner so MCP-client logs show what's loaded.

package/src/release.test.ts

@@ -219,7 +219,20 @@ describe("setup.ts", () => {
   test("mcp.ts aborts startup instead of continuing with an empty DB", () => {
     const src = readText("src/mcp.ts");
     expect(src).toContain("Unable to start rosetta without a usable database");
-    expect(src).toContain("Database remained empty after recovery");
+    expect(src).toContain("Database remained incomplete after recovery");
+  });
+
+  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)", () => {

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";
 
@@ -20,7 +20,15 @@ afterAll(() => {
   } catch {}
 });
 
-const { dbDownloadUrls, probeDb, releaseDownloadLock, tryAcquireDownloadLock, waitForUsableDb } = await import("./setup.ts");
+const {
+  cleanupAbandonedTempArtifacts,
+  cleanupStaleTempArtifacts,
+  dbDownloadUrls,
+  probeDb,
+  releaseDownloadLock,
+  tryAcquireDownloadLock,
+  waitForUsableDb,
+} = await import("./setup.ts");
 const { SCHEMA_VERSION } = await import("./paths.ts");
 
 function writeUsableDb(dbFile: string, releaseTag = "v0.0.0-test"): void {
@@ -115,6 +123,20 @@ describe("download lock helpers", () => {
     expect(probe?.pages).toBe(100);
     expect(probe?.commands).toBe(1000);
   });
+
+  test("waitForUsableDb does not create a missing canonical DB while waiting", async () => {
+    const dbFile = path.join(tmp, "wait-no-create.db");
+    const lock = tryAcquireDownloadLock(dbFile);
+    expect(lock).not.toBeNull();
+
+    const waiter = waitForUsableDb(dbFile, () => {}, 2_000);
+    await Bun.sleep(100);
+    expect(existsSync(dbFile)).toBe(false);
+
+    releaseDownloadLock(lock);
+    expect(await waiter).toBe(false);
+    expect(existsSync(dbFile)).toBe(false);
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -123,7 +145,9 @@ describe("download lock helpers", () => {
 
 describe("probeDb", () => {
   test("returns null for a missing file", () => {
-    expect(probeDb(path.join(tmp, "does-not-exist.db"))).toBeNull();
+    const missing = path.join(tmp, "does-not-exist.db");
+    expect(probeDb(missing)).toBeNull();
+    expect(existsSync(missing)).toBe(false);
   });
 
   test("returns null for a non-SQLite file", () => {
@@ -155,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.
@@ -199,3 +236,59 @@ describe("probeDb", () => {
     expect(probe?.releaseTag).toBeNull();
   });
 });
+
+describe("cleanupStaleTempArtifacts", () => {
+  test("removes stale temp DB files and sidecars", () => {
+    const dbFile = path.join(tmp, "cleanup.db");
+    const artifacts = [
+      `${dbFile}.tmp.111`,
+      `${dbFile}.tmp.111-wal`,
+      `${dbFile}.tmp.111-shm`,
+    ];
+
+    for (const artifact of artifacts) {
+      writeFileSync(artifact, "x");
+    }
+
+    expect(cleanupStaleTempArtifacts(dbFile, -1)).toBe(3);
+    for (const artifact of artifacts) {
+      expect(existsSync(artifact)).toBe(false);
+    }
+  });
+});
+
+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

@@ -12,11 +12,14 @@ import {
   closeSync,
   existsSync,
   openSync,
+  readdirSync,
+  readSync,
   renameSync,
   statSync,
   unlinkSync,
   writeFileSync,
 } from "node:fs";
+import path from "node:path";
 import { gunzipSync } from "bun";
 import { detectMode, resolveBaseDir, resolveDbPath, resolveVersion, SCHEMA_VERSION } from "./paths.ts";
 
@@ -44,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;
@@ -53,15 +68,31 @@ type DownloadLockHandle = {
  *  Opens read-write — see probeDb's note: freshly written WAL-mode files can
  *  fail to open readonly on macOS when the .shm file is missing. */
 function dbHasData(dbPath: string): boolean {
+  return hasMinimumDbContent(probeDb(dbPath));
+}
+
+function looksLikeSqliteFile(dbPath: string): boolean {
   if (!existsSync(dbPath)) return false;
+
+  let fd: number | null = null;
   try {
-    const { default: sqlite } = require("bun:sqlite");
-    const check = new sqlite(dbPath);
-    const row = check.prepare("SELECT COUNT(*) AS c FROM pages").get() as { c: number };
-    check.close();
-    return row.c > 0;
+    const stats = statSync(dbPath);
+    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;
   } catch {
     return false;
+  } finally {
+    if (fd !== null) {
+      try {
+        closeSync(fd);
+      } catch {
+        // best-effort cleanup
+      }
+    }
   }
 }
 
@@ -77,20 +108,22 @@ export function probeDb(dbPath: string): {
   commands: number;
   releaseTag: string | null;
 } | 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,
@@ -99,11 +132,32 @@ 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 isUsableDbProbe(probe: DbProbe | null): probe is DbProbe {
-  return !!probe && probe.schemaVersion === SCHEMA_VERSION && probe.pages >= MIN_PAGES && probe.commands >= MIN_COMMANDS;
+function sqliteGet<T>(db: SQLiteDatabase, sql: string): T {
+  const stmt = db.prepare(sql);
+  try {
+    return stmt.get() as T;
+  } finally {
+    stmt.finalize();
+  }
+}
+
+export function hasMinimumDbContent(probe: DbProbe | null): probe is DbProbe {
+  return !!probe && probe.pages >= MIN_PAGES && probe.commands >= MIN_COMMANDS;
+}
+
+export function isUsableDbProbe(probe: DbProbe | null): probe is DbProbe {
+  return hasMinimumDbContent(probe) && probe.schemaVersion === SCHEMA_VERSION;
 }
 
 function lockPathFor(dbPath: string): string {
@@ -123,11 +177,11 @@ export function tryAcquireDownloadLock(dbPath: string): DownloadLockHandle | nul
       const fd = openSync(lockPath, "wx");
       writeFileSync(
         fd,
-        JSON.stringify({
+        `${JSON.stringify({
           pid: process.pid,
           created_at: new Date().toISOString(),
           db_path: dbPath,
-        }) + "\n",
+        })}\n`,
       );
       return { fd, path: lockPath };
     } catch (e) {
@@ -171,10 +225,9 @@ export async function waitForUsableDb(
   let announced = false;
 
   while (Date.now() < deadline) {
-    const probe = probeDb(dbPath);
-    if (isUsableDbProbe(probe)) return true;
-
-    if (!existsSync(lockPath)) return false;
+    if (!existsSync(lockPath)) {
+      return isUsableDbProbe(probeDb(dbPath));
+    }
 
     if (!announced) {
       log(`  Another rosetta process is preparing ${dbPath}; waiting...`);
@@ -189,17 +242,90 @@ export async function waitForUsableDb(
   return false;
 }
 
-function replaceDbFile(tmpPath: string, dbPath: string): void {
+function tryUnlinkDbSidecars(dbPath: string): void {
+  tryUnlink(`${dbPath}-wal`);
+  tryUnlink(`${dbPath}-shm`);
+}
+
+function cleanupDbArtifacts(dbPath: string): void {
+  tryUnlinkDbSidecars(dbPath);
+  tryUnlink(dbPath);
+}
+
+export function cleanupStaleTempArtifacts(dbPath: string, staleMs = DOWNLOAD_LOCK_STALE_MS): number {
+  const dir = path.dirname(dbPath);
+  const prefix = `${path.basename(dbPath)}.tmp.`;
+  const now = Date.now();
+  let removed = 0;
+
+  let entries: string[];
   try {
-    renameSync(tmpPath, dbPath);
-    return;
-  } catch (e) {
-    const code = e instanceof Error && "code" in e ? e.code : undefined;
-    if (code !== "EEXIST" && code !== "EPERM") throw e;
+    entries = readdirSync(dir);
+  } catch {
+    return 0;
   }
 
-  tryUnlink(dbPath);
-  renameSync(tmpPath, dbPath);
+  for (const entry of entries) {
+    if (!entry.startsWith(prefix)) continue;
+
+    const fullPath = path.join(dir, entry);
+    try {
+      const ageMs = now - statSync(fullPath).mtimeMs;
+      if (ageMs <= staleMs) continue;
+    } catch {
+      continue;
+    }
+
+    try {
+      unlinkSync(fullPath);
+      removed++;
+    } catch {
+      // best-effort cleanup
+    }
+  }
+
+  return removed;
+}
+
+export function cleanupAbandonedTempArtifacts(dbPath: string): number {
+  if (existsSync(lockPathFor(dbPath))) {
+    return cleanupStaleTempArtifacts(dbPath);
+  }
+  return cleanupStaleTempArtifacts(dbPath, -1);
+}
+
+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.
@@ -230,21 +356,23 @@ export function dbDownloadUrls(version: string): string[] {
 export async function downloadDb(
   dbPath: string,
   log: (msg: string) => void = console.log,
-) {
+): Promise<DbProbe> {
   let lock = tryAcquireDownloadLock(dbPath);
   if (!lock) {
     const reused = await waitForUsableDb(dbPath, log);
     if (reused) {
       const probe = probeDb(dbPath);
-      if (probe) log(`  Reused existing database: ${formatProbeSummary(probe)}`);
-      return;
+      if (probe) {
+        log(`  Reused existing database: ${formatProbeSummary(probe)}`);
+        return probe;
+      }
     }
 
     // Re-probe once — the lock may have been released with a healthy DB
     const fallbackProbe = probeDb(dbPath);
     if (isUsableDbProbe(fallbackProbe)) {
       log(`  Reused existing database: ${formatProbeSummary(fallbackProbe)}`);
-      return;
+      return fallbackProbe;
     }
 
     lock = tryAcquireDownloadLock(dbPath);
@@ -260,6 +388,11 @@ export async function downloadDb(
   let lastError: Error | null = null;
 
   try {
+    const cleaned = cleanupStaleTempArtifacts(dbPath);
+    if (cleaned > 0) {
+      log(`  Removed ${cleaned} stale temp DB artifact${cleaned === 1 ? "" : "s"}.`);
+    }
+
     for (let i = 0; i < urls.length; i++) {
       const url = urls[i];
       const isLast = i === urls.length - 1;
@@ -332,25 +465,25 @@ export async function downloadDb(
 
       const probe = probeDb(tmpPath);
       if (!probe) {
-        tryUnlink(tmpPath);
+        cleanupDbArtifacts(tmpPath);
         lastError = new Error("Downloaded DB failed to open with SQLite");
         if (isLast) throw lastError;
         log(`  ${lastError.message} — trying fallback...`);
         continue;
       }
       if (probe.schemaVersion !== SCHEMA_VERSION) {
-        tryUnlink(tmpPath);
+        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}`);
         continue;
       }
       if (probe.pages < MIN_PAGES || probe.commands < MIN_COMMANDS) {
-        tryUnlink(tmpPath);
+        cleanupDbArtifacts(tmpPath);
         lastError = new Error(
           `Downloaded DB content looks incomplete (pages=${probe.pages}, commands=${probe.commands})`,
         );
@@ -361,25 +494,19 @@ export async function downloadDb(
 
       // Validation passed — drop stale WAL/SHM and atomically swap.
       try {
-        tryUnlink(`${dbPath}-wal`);
-        tryUnlink(`${dbPath}-shm`);
-        replaceDbFile(tmpPath, dbPath);
+        tryUnlinkDbSidecars(tmpPath);
+        tryUnlinkDbSidecars(dbPath);
+        await replaceDbFile(tmpPath, dbPath);
       } catch (e) {
         const existingProbe = probeDb(dbPath);
-        if (
-          existingProbe &&
-          existingProbe.schemaVersion === probe.schemaVersion &&
-          existingProbe.releaseTag === probe.releaseTag &&
-          existingProbe.pages >= MIN_PAGES &&
-          existingProbe.commands >= MIN_COMMANDS
-        ) {
-          tryUnlink(tmpPath);
+        if (hasMinimumDbContent(existingProbe) && existingProbe.schemaVersion === probe.schemaVersion && existingProbe.releaseTag === probe.releaseTag) {
+          cleanupDbArtifacts(tmpPath);
           log(`  Another rosetta process already installed the same database.`);
           log(`  Reused existing database: ${formatProbeSummary(existingProbe)}`);
-          return;
+          return existingProbe;
         }
 
-        tryUnlink(tmpPath);
+        cleanupDbArtifacts(tmpPath);
         throw e;
       }
 
@@ -387,7 +514,7 @@ export async function downloadDb(
       const tagInfo = probe.releaseTag ? ` (release ${probe.releaseTag})` : "";
       log(`  Wrote ${sizeMB} MB to ${dbPath}${tagInfo}`);
       log(`  Validated: schema v${probe.schemaVersion}, ${probe.pages} pages, ${probe.commands} commands.`);
-      return;
+      return probe;
     }
 
     throw lastError ?? new Error("Database download failed for unknown reasons");
@@ -412,17 +539,13 @@ function tryUnlink(p: string): void {
  */
 export async function refreshDb(log: (msg: string) => void = console.log): Promise<boolean> {
   const dbPath = resolveDbPath(import.meta.dirname);
+  let probe: DbProbe;
   try {
-    await downloadDb(dbPath, log);
+    probe = await downloadDb(dbPath, log);
   } catch (e) {
     log(`✗ Refresh failed: ${e instanceof Error ? e.message : e}`);
     return false;
   }
-  const probe = probeDb(dbPath);
-  if (!probe) {
-    log(`✗ Post-download probe failed`);
-    return false;
-  }
   const tagInfo = probe.releaseTag ? ` (release ${probe.releaseTag})` : "";
   log(`✓ Database ready${tagInfo}: ${probe.pages} pages, ${probe.commands} commands, schema v${probe.schemaVersion}`);
   return true;
@@ -431,6 +554,7 @@ export async function refreshDb(log: (msg: string) => void = console.log): Promi
 export async function runSetup(force = false) {
   const mode = detectMode(import.meta.dirname);
   const dbPath = resolveDbPath(import.meta.dirname);
+  let downloadedProbe: DbProbe | null = null;
 
   console.log(`rosetta ${RELEASE_VERSION}`);
   console.log(`  ${link("https://github.com/tikoci/rosetta")}`);
@@ -443,7 +567,7 @@ export async function runSetup(force = false) {
     console.log(`  (use --refresh or --setup --force to re-download)`);
   } else {
     try {
-      await downloadDb(dbPath);
+      downloadedProbe = await downloadDb(dbPath);
     } catch (e) {
       console.error(`✗ Database download failed: ${e instanceof Error ? e.message : e}`);
       process.exit(1);
@@ -452,7 +576,7 @@ export async function runSetup(force = false) {
 
   // ── Validate DB ──
   console.log();
-  const probe = probeDb(dbPath);
+  const probe = downloadedProbe ?? probeDb(dbPath);
   if (!probe) {
     console.error(`✗ Database validation failed: cannot open ${dbPath}`);
     const retryCmd = mode === "compiled" ? "rosetta" : mode === "package" ? "bunx @tikoci/rosetta" : "bun run src/setup.ts";
@@ -464,7 +588,7 @@ export async function runSetup(force = false) {
       `✗ DB schema version is ${probe.schemaVersion}, expected ${SCHEMA_VERSION}.`,
     );
     console.error(
-      `  Cached package may be out of date. Run \`bun pm cache rm\` and relaunch.`,
+      `  Package may be out of date. Run: bunx @tikoci/rosetta@latest --refresh`,
     );
     process.exit(1);
   }