@tikoci/rosetta 0.8.10 → 0.8.11

package/package.json

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

package/src/mcp.ts

@@ -61,44 +61,23 @@ 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 { downloadDb, hasMinimumDbContent, probeDb, cleanupStaleTempArtifacts } = 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 stale .tmp.* artifacts from previous failed runs, regardless of
+  // whether a download is needed this time.
+  cleanupStaleTempArtifacts(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`);
@@ -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,13 @@ 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("tryUnlinkDbSidecars(tmpPath)");
   });
 
   test("no DB open uses { readonly: true } (WAL-shm init trap on macOS)", () => {

package/src/setup.test.ts

@@ -20,7 +20,14 @@ afterAll(() => {
   } catch {}
 });
 
-const { dbDownloadUrls, probeDb, releaseDownloadLock, tryAcquireDownloadLock, waitForUsableDb } = await import("./setup.ts");
+const {
+  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 +122,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 +144,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", () => {
@@ -199,3 +222,23 @@ 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);
+    }
+  });
+});

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";
 
@@ -53,15 +56,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,6 +96,8 @@ export function probeDb(dbPath: string): {
   commands: number;
   releaseTag: string | null;
 } | null {
+  if (!looksLikeSqliteFile(dbPath)) return null;
+
   try {
     const { default: sqlite } = require("bun:sqlite");
     const check = new sqlite(dbPath);
@@ -102,8 +123,12 @@ export function probeDb(dbPath: string): {
   }
 }
 
-function isUsableDbProbe(probe: DbProbe | null): probe is DbProbe {
-  return !!probe && probe.schemaVersion === SCHEMA_VERSION && probe.pages >= MIN_PAGES && probe.commands >= MIN_COMMANDS;
+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 +148,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 +196,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,13 +213,59 @@ export async function waitForUsableDb(
   return false;
 }
 
+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 {
+    entries = readdirSync(dir);
+  } catch {
+    return 0;
+  }
+
+  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;
+}
+
 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;
-    if (code !== "EEXIST" && code !== "EPERM") throw e;
+    // Windows can return EBUSY, EPERM, or EEXIST when the destination is open.
+    if (code !== "EBUSY" && code !== "EEXIST" && code !== "EPERM") throw e;
   }
 
   tryUnlink(dbPath);
@@ -230,21 +300,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 +332,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,14 +409,14 @@ 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}). ` +
             `This usually means the cached package version is older than the published DB. ` +
@@ -350,7 +427,7 @@ export async function downloadDb(
         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 +438,19 @@ export async function downloadDb(
 
       // Validation passed — drop stale WAL/SHM and atomically swap.
       try {
-        tryUnlink(`${dbPath}-wal`);
-        tryUnlink(`${dbPath}-shm`);
+        tryUnlinkDbSidecars(tmpPath);
+        tryUnlinkDbSidecars(dbPath);
         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 +458,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 +483,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 +498,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 +511,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 +520,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 +532,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);
   }