@tikoci/rosetta 0.7.3 → 0.7.4

package/package.json

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

package/src/db.ts

@@ -53,6 +53,14 @@ export function initDb() {
     applied_at TEXT NOT NULL
   );`);
 
+  // -- DB metadata (release tag, build date, source commit) --
+  // Key/value to avoid schema churn. Written by extractors / release.yml;
+  // read by MCP startup banner and the freshness-check path.
+  db.run(`CREATE TABLE IF NOT EXISTS db_meta (
+    key   TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+  );`);
+
   // -- Pages (from Confluence HTML export) --
 
   db.run(`CREATE TABLE IF NOT EXISTS pages (
@@ -767,6 +775,31 @@ export function checkSchemaVersion(): { ok: boolean; actual: number; expected: n
   return { ok: row.user_version === SCHEMA_VERSION, actual: row.user_version, expected: SCHEMA_VERSION };
 }
 
+/** Read a single row from db_meta. Returns null when the key is missing. */
+export function getDbMeta(key: string): string | null {
+  try {
+    const row = db.prepare("SELECT value FROM db_meta WHERE key = ?").get(key) as { value: string } | null;
+    return row?.value ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Upsert a single row into db_meta. */
+export function setDbMeta(key: string, value: string): void {
+  db.run("INSERT INTO db_meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value;", [key, value]);
+}
+
+/** Read all db_meta rows as a flat object. */
+export function getAllDbMeta(): Record<string, string> {
+  try {
+    const rows = db.prepare("SELECT key, value FROM db_meta").all() as Array<{ key: string; value: string }>;
+    return Object.fromEntries(rows.map((r) => [r.key, r.value]));
+  } catch {
+    return {};
+  }
+}
+
 export function getDbStats() {
   const count = (sql: string) =>
     Number((db.prepare(sql).get() as { c: number }).c ?? 0);

package/src/mcp-http.test.ts

@@ -19,6 +19,7 @@ import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { Subprocess } from "bun";
+import { SCHEMA_VERSION } from "./paths.ts";
 
 // ── Helpers ──
 
@@ -108,8 +109,12 @@ function createFixtureDb(dbPath: string): void {
     1, '/system', 'system', 'dir', NULL, 1, 'fixture command', '7.22'
   );`);
 
-  // Stamp schema version so mcp.ts doesn't trigger a 50MB auto-download
-  fixture.run("PRAGMA user_version = 1;");
+  // Stamp the current schema version so mcp.ts doesn't try to auto-download
+  // a "real" DB. Importing SCHEMA_VERSION here keeps the fixture in sync with
+  // any future bumps. Also seed db_meta so the startup banner has a release tag.
+  fixture.run(`PRAGMA user_version = ${SCHEMA_VERSION};`);
+  fixture.run("CREATE TABLE db_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);");
+  fixture.run("INSERT INTO db_meta (key, value) VALUES ('release_tag', 'v0.0.0-test');");
   fixture.close();
 }
 

package/src/mcp.ts

@@ -50,56 +50,97 @@ function link(url: string, display?: string): string {
  * Ensure the DB exists, has page data, and matches the current schema version.
  * This must run before importing db.ts/query.ts to avoid creating an empty DB file
  * on fresh installs.
+ *
+ * Failure modes are explicit:
+ *   - Missing or empty DB → download once. If download fails, return — server
+ *     will start but tool calls will surface the underlying SQL error.
+ *   - Schema mismatch → re-download once, then re-probe. If still mismatched,
+ *     fail hard with an actionable message rather than silently using a DB
+ *     that the running code can't query correctly.
  */
 async function ensureDbReady(log: (msg: string) => void): Promise<void> {
-  const { resolveDbPath, SCHEMA_VERSION } = await import("./paths.ts");
+  const { resolveDbPath, SCHEMA_VERSION, resolveVersion } = await import("./paths.ts");
   const { downloadDb } = await import("./setup.ts");
+  const { default: sqlite } = await import("bun:sqlite");
 
   const dbPath = resolveDbPath(import.meta.dirname);
+  const runningVersion = resolveVersion(import.meta.dirname);
 
-  const pageCount = (() => {
+  /** Probe an existing DB. Returns null if the file is missing or unreadable. */
+  function probe(): { pages: number; schemaVersion: number; releaseTag: string | null } | null {
     try {
-      const check = new (require("bun:sqlite").default)(dbPath, { readonly: true });
-      const row = check.prepare("SELECT COUNT(*) AS c FROM pages").get() as { c: number };
+      const check = new sqlite(dbPath, { readonly: true });
+      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 row.c;
+      return { pages, schemaVersion: ver, releaseTag };
     } catch {
-      return 0;
+      return null;
     }
-  })();
+  }
 
-  if (pageCount === 0) {
+  let p = probe();
+
+  // Case 1: DB missing or empty → first-time download.
+  if (!p || p.pages === 0) {
+    log(`No usable database at ${dbPath} — downloading...`);
     try {
       await downloadDb(dbPath, log);
       log("Database downloaded successfully.");
+      p = probe();
     } catch (e) {
-      log(`Auto-download failed: ${e}`);
-      log(`Run: ${process.argv[0]} --setup`);
+      log(`Auto-download failed: ${e instanceof Error ? e.message : e}`);
+      log(`Run: bunx @tikoci/rosetta --refresh`);
       return;
     }
   }
 
-  const dbSchemaVersion = (() => {
-    try {
-      const check = new (require("bun:sqlite").default)(dbPath, { readonly: true });
-      const row = check.prepare("PRAGMA user_version").get() as { user_version: number };
-      check.close();
-      return row.user_version;
-    } catch {
-      return SCHEMA_VERSION;
-    }
-  })();
+  if (!p) {
+    log(`Database probe failed after download.`);
+    return;
+  }
 
-  if (dbSchemaVersion !== SCHEMA_VERSION) {
-    log(`DB schema version mismatch (DB=${dbSchemaVersion}, expected=${SCHEMA_VERSION}) - re-downloading updated database...`);
+  // Case 2: Schema mismatch → re-download, then re-probe and fail hard if
+  // still wrong (don't silently boot with an incompatible schema).
+  if (p.schemaVersion !== SCHEMA_VERSION) {
+    log(
+      `DB schema mismatch: DB=${p.schemaVersion}, expected=${SCHEMA_VERSION}. ` +
+        `Re-downloading database...`,
+    );
     try {
       await downloadDb(dbPath, log);
-      log("Database updated successfully.");
     } catch (e) {
-      log(`Auto-download failed: ${e}`);
-      log(`Run: ${process.argv[0]} --refresh`);
+      log(`✗ Auto-recovery download failed: ${e instanceof Error ? e.message : e}`);
+      log(
+        `  This rosetta build (v${runningVersion}) cannot use the existing DB. ` +
+          `Run \`bun pm cache rm\` to clear the bunx cache and relaunch.`,
+      );
+      process.exit(1);
+    }
+    const p2 = probe();
+    if (!p2 || p2.schemaVersion !== SCHEMA_VERSION) {
+      log(
+        `✗ Still incompatible after re-download (DB=${p2?.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.`,
+      );
+      process.exit(1);
     }
+    p = p2;
   }
+
+  // Quietly emit a one-line provenance banner so MCP-client logs show what's loaded.
+  const tagInfo = p.releaseTag ? `, release ${p.releaseTag}` : "";
+  log(`rosetta v${runningVersion} ready (DB schema v${p.schemaVersion}, ${p.pages} pages${tagInfo}).`);
 }
 
 if (args.includes("--version") || args.includes("-v")) {
@@ -155,9 +196,11 @@ if (args.includes("--setup")) {
 }
 
 if (args.includes("--refresh")) {
-  const { runSetup } = await import("./setup.ts");
-  await runSetup(true);
-  process.exit(0);
+  // Quiet refresh: just download + validate. Skips the MCP-config printing
+  // that --setup does — users running --refresh already have a configured client.
+  const { refreshDb } = await import("./setup.ts");
+  const ok = await refreshDb();
+  process.exit(ok ? 0 : 1);
 }
 
 // ── MCP Server ──

package/src/paths.ts

@@ -85,8 +85,12 @@ export function detectMode(srcDir: string): InvocationMode {
  * Increment when making destructive schema changes (DROP/RENAME table or column).
  * Stamped into the DB via `PRAGMA user_version` by initDb() and checked at MCP
  * startup to detect stale DBs for bunx users who auto-update the package.
+ *
+ * Bump history:
+ *   v5 — added `db_meta` key/value table for release-tag provenance and
+ *        atomic-download / version-pinned-URL update flow (2026-04-21).
  */
-export const SCHEMA_VERSION = 4;
+export const SCHEMA_VERSION = 5;
 
 /**
  * Resolve the version string.

package/src/query.test.ts

@@ -1643,6 +1643,25 @@ describe("schema", () => {
     expect(result.actual).toBe(SCHEMA_VERSION);
     expect(result.expected).toBe(SCHEMA_VERSION);
   });
+
+  test("db_meta table exists with key/value shape and read/write helpers work", async () => {
+    const cols = db.prepare("PRAGMA table_info(db_meta)").all() as Array<{ name: string; type: string }>;
+    const colNames = cols.map((c) => c.name);
+    expect(colNames).toContain("key");
+    expect(colNames).toContain("value");
+
+    const { setDbMeta, getDbMeta, getAllDbMeta } = await import("./db.ts");
+    setDbMeta("release_tag", "v0.0.0-test");
+    setDbMeta("built_at", "2026-04-21T00:00:00Z");
+    expect(getDbMeta("release_tag")).toBe("v0.0.0-test");
+    expect(getDbMeta("missing_key")).toBeNull();
+    // Upsert
+    setDbMeta("release_tag", "v0.0.1-test");
+    expect(getDbMeta("release_tag")).toBe("v0.0.1-test");
+    const all = getAllDbMeta();
+    expect(all.release_tag).toBe("v0.0.1-test");
+    expect(all.built_at).toBe("2026-04-21T00:00:00Z");
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/release.test.ts

@@ -167,8 +167,66 @@ describe("setup.ts", () => {
   test("downloads from GitHub Releases URL", () => {
     const src = readText("src/setup.ts");
     expect(src).toContain("github.com/");
+    // Now uses both a version-pinned URL and a /latest/ fallback (see dbDownloadUrls).
+    expect(src).toContain("/releases/download/");
     expect(src).toContain("/releases/latest/download/ros-help.db.gz");
   });
+
+  test("validates SQLite magic bytes before writing the canonical DB path", () => {
+    const src = readText("src/setup.ts");
+    expect(src).toContain("SQLite format 3");
+  });
+
+  test("writes to a .tmp file and renames atomically", () => {
+    const src = readText("src/setup.ts");
+    expect(src).toContain(".tmp.");
+    expect(src).toContain("renameSync");
+  });
+
+  test("clears stale WAL/SHM siblings on download", () => {
+    const src = readText("src/setup.ts");
+    expect(src).toContain("-wal");
+    expect(src).toContain("-shm");
+  });
+
+  test("exports a quiet refreshDb path used by --refresh", () => {
+    const src = readText("src/setup.ts");
+    expect(src).toContain("export async function refreshDb");
+    const mcp = readText("src/mcp.ts");
+    expect(mcp).toContain("refreshDb");
+  });
+
+  test("mcp.ts fails hard on persistent schema mismatch (no silent fall-through)", () => {
+    const src = readText("src/mcp.ts");
+    // Must call process.exit on the unrecoverable schema-mismatch path
+    expect(src).toContain("Still incompatible after re-download");
+    expect(src).toMatch(/Still incompatible[\s\S]{0,400}process\.exit\(1\)/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// db_meta provenance + stamp script
+// ---------------------------------------------------------------------------
+
+describe("db_meta provenance", () => {
+  test("stamp-db-meta.ts script exists and accepts --release-tag", () => {
+    const src = readText("scripts/stamp-db-meta.ts");
+    expect(src).toContain("--release-tag");
+    expect(src).toContain("CREATE TABLE IF NOT EXISTS db_meta");
+  });
+
+  test("release.yml stamps db_meta after extraction", () => {
+    const yml = readText(".github/workflows/release.yml");
+    expect(yml).toContain("scripts/stamp-db-meta.ts");
+    expect(yml).toContain("--release-tag");
+    expect(yml).toContain("--source-commit");
+  });
+
+  test("db.ts exposes setDbMeta / getDbMeta helpers", () => {
+    const src = readText("src/db.ts");
+    expect(src).toContain("export function setDbMeta");
+    expect(src).toContain("export function getDbMeta");
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/setup.test.ts

@@ -0,0 +1,107 @@
+/**
+ * setup.test.ts — Tests for DB download helpers.
+ *
+ * Covers the parts that don't require network: URL construction and DB probing
+ * against fixture DBs written to a temp directory. The full download path is
+ * validated structurally in release.test.ts.
+ */
+
+import sqlite from "bun:sqlite";
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+const tmp = mkdtempSync(path.join(tmpdir(), "rosetta-setup-test-"));
+
+afterAll(() => {
+  try {
+    rmSync(tmp, { recursive: true, force: true });
+  } catch {}
+});
+
+const { probeDb, dbDownloadUrls } = await import("./setup.ts");
+const { SCHEMA_VERSION } = await import("./paths.ts");
+
+// ---------------------------------------------------------------------------
+// dbDownloadUrls — version pinning + latest fallback
+// ---------------------------------------------------------------------------
+
+describe("dbDownloadUrls", () => {
+  test("returns pinned + latest for a real version", () => {
+    const urls = dbDownloadUrls("0.7.3");
+    expect(urls).toHaveLength(2);
+    expect(urls[0]).toContain("/releases/download/v0.7.3/ros-help.db.gz");
+    expect(urls[1]).toContain("/releases/latest/download/ros-help.db.gz");
+  });
+
+  test("preserves the v prefix when supplied", () => {
+    const urls = dbDownloadUrls("v0.8.0");
+    expect(urls[0]).toContain("/releases/download/v0.8.0/ros-help.db.gz");
+  });
+
+  test("returns only /latest/ when version is unknown or dev", () => {
+    expect(dbDownloadUrls("unknown")).toEqual([
+      expect.stringContaining("/releases/latest/download/ros-help.db.gz"),
+    ]);
+    expect(dbDownloadUrls("dev")).toEqual([
+      expect.stringContaining("/releases/latest/download/ros-help.db.gz"),
+    ]);
+    expect(dbDownloadUrls("")).toEqual([
+      expect.stringContaining("/releases/latest/download/ros-help.db.gz"),
+    ]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// probeDb — schema / pages / commands / release_tag
+// ---------------------------------------------------------------------------
+
+describe("probeDb", () => {
+  test("returns null for a missing file", () => {
+    expect(probeDb(path.join(tmp, "does-not-exist.db"))).toBeNull();
+  });
+
+  test("returns null for a non-SQLite file", () => {
+    const garbage = path.join(tmp, "garbage.db");
+    writeFileSync(garbage, "this is not a SQLite database");
+    expect(probeDb(garbage)).toBeNull();
+  });
+
+  test("reads schema_version, page count, command count, and release_tag", () => {
+    const dbFile = path.join(tmp, "fixture.db");
+    const db = new sqlite(dbFile);
+    db.run(`PRAGMA user_version = ${SCHEMA_VERSION};`);
+    db.run("CREATE TABLE pages (id INTEGER PRIMARY KEY, title TEXT);");
+    db.run("CREATE TABLE commands (id INTEGER PRIMARY KEY, path TEXT);");
+    db.run("CREATE TABLE db_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);");
+
+    const insertPage = db.prepare("INSERT INTO pages (title) VALUES (?)");
+    for (let i = 0; i < 7; i++) insertPage.run(`page-${i}`);
+    const insertCmd = db.prepare("INSERT INTO commands (path) VALUES (?)");
+    for (let i = 0; i < 13; i++) insertCmd.run(`/cmd/${i}`);
+    db.run("INSERT INTO db_meta (key, value) VALUES ('release_tag', 'v0.0.0-test');");
+    db.close();
+
+    const probe = probeDb(dbFile);
+    expect(probe).not.toBeNull();
+    expect(probe?.schemaVersion).toBe(SCHEMA_VERSION);
+    expect(probe?.pages).toBe(7);
+    expect(probe?.commands).toBe(13);
+    expect(probe?.releaseTag).toBe("v0.0.0-test");
+  });
+
+  test("releaseTag is null when db_meta is absent (pre-v5 schema)", () => {
+    const dbFile = path.join(tmp, "no-meta.db");
+    const db = new sqlite(dbFile);
+    db.run("PRAGMA user_version = 4;");
+    db.run("CREATE TABLE pages (id INTEGER PRIMARY KEY);");
+    db.run("CREATE TABLE commands (id INTEGER PRIMARY KEY);");
+    db.close();
+
+    const probe = probeDb(dbFile);
+    expect(probe).not.toBeNull();
+    expect(probe?.schemaVersion).toBe(4);
+    expect(probe?.releaseTag).toBeNull();
+  });
+});

package/src/setup.ts

@@ -8,7 +8,7 @@
  */
 
 import { execSync } from "node:child_process";
-import { existsSync, writeFileSync } from "node:fs";
+import { existsSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { gunzipSync } from "bun";
 import { detectMode, resolveBaseDir, resolveDbPath, resolveVersion, SCHEMA_VERSION } from "./paths.ts";
 
@@ -18,6 +18,14 @@ const GITHUB_REPO =
   typeof REPO_URL !== "undefined" ? REPO_URL : "tikoci/rosetta";
 const RELEASE_VERSION = resolveVersion(import.meta.dirname);
 
+/** Minimum byte counts for a healthy DB. Validation thresholds — keep loose so
+ *  shrinking the dataset doesn't break startup, but tight enough to catch a
+ *  redirect-to-login HTML page or a partial transfer. */
+const MIN_PAGES = 100;
+const MIN_COMMANDS = 1000;
+const MIN_DECOMPRESSED_BYTES = 50 * 1024 * 1024; // 50 MB
+const SQLITE_MAGIC = "SQLite format 3\0";
+
 /** Check if a DB file exists and has actual page data */
 function dbHasData(dbPath: string): boolean {
   if (!existsSync(dbPath)) return false;
@@ -32,32 +40,215 @@ function dbHasData(dbPath: string): boolean {
   }
 }
 
-/** Download ros-help.db.gz from GitHub Releases, decompress, and write to dbPath */
+/** Open a DB read-only and return its key health metrics. Returns null on error.
+ *  Exported so tests can validate fixture DBs without depending on network. */
+export function probeDb(dbPath: string): {
+  schemaVersion: number;
+  pages: number;
+  commands: number;
+  releaseTag: string | null;
+} | null {
+  try {
+    const { default: sqlite } = require("bun:sqlite");
+    const check = new sqlite(dbPath, { readonly: true });
+    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 };
+    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 — pre-v5 schema, leave releaseTag null
+    }
+    check.close();
+    return {
+      schemaVersion: ver.user_version,
+      pages: pages.c,
+      commands: cmds.c,
+      releaseTag,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Build the version-pinned download URL. Falls back to /latest/ when no version.
+ *  Exported for test coverage. */
+export function dbDownloadUrls(version: string): string[] {
+  const latest = `https://github.com/${GITHUB_REPO}/releases/latest/download/ros-help.db.gz`;
+  // version may be "0.7.3" (from package.json) or "v0.7.3" (compiled-in). Normalize.
+  const tag = version.startsWith("v") ? version : `v${version}`;
+  if (!version || version === "unknown" || version === "dev") {
+    return [latest];
+  }
+  const pinned = `https://github.com/${GITHUB_REPO}/releases/download/${tag}/ros-help.db.gz`;
+  return [pinned, latest];
+}
+
+/**
+ * Download ros-help.db.gz from GitHub Releases atomically:
+ *   1. Try version-pinned URL first, fall back to /latest/ on 404.
+ *   2. Decompress in memory, verify SQLite magic bytes + minimum size.
+ *   3. Write to <dbPath>.tmp.<pid>, open it read-only, verify schema_version
+ *      matches the running code and pages/commands counts look healthy.
+ *   4. Atomically rename .tmp → dbPath, then delete stale .db-wal / .db-shm.
+ *
+ * On any validation failure the existing DB is left untouched and we throw —
+ * the caller decides whether to fail hard or fall back. Never produces a
+ * half-written DB file at the canonical path.
+ */
 export async function downloadDb(
   dbPath: string,
   log: (msg: string) => void = console.log,
 ) {
-  const url = `https://github.com/${GITHUB_REPO}/releases/latest/download/ros-help.db.gz`;
-  log(`Downloading database from GitHub Releases...`);
-  log(`  ${url}`);
+  const urls = dbDownloadUrls(RELEASE_VERSION);
+  let lastError: Error | null = null;
+
+  for (let i = 0; i < urls.length; i++) {
+    const url = urls[i];
+    const isLast = i === urls.length - 1;
+    log(`Downloading database from GitHub Releases...`);
+    log(`  ${url}`);
+
+    let response: Response;
+    try {
+      response = await fetch(url, { redirect: "follow" });
+    } catch (e) {
+      lastError = e as Error;
+      log(`  Network error: ${e}`);
+      if (isLast) throw lastError;
+      continue;
+    }
 
-  const response = await fetch(url, { redirect: "follow" });
-  if (!response.ok) {
-    throw new Error(`Download failed: ${response.status} ${response.statusText}`);
-  }
+    if (response.status === 404 && !isLast) {
+      log(`  Not found at this URL, trying fallback...`);
+      continue;
+    }
+    if (!response.ok) {
+      lastError = new Error(`Download failed: ${response.status} ${response.statusText}`);
+      if (isLast) throw lastError;
+      log(`  ${lastError.message} — trying fallback...`);
+      continue;
+    }
+
+    const contentLength = response.headers.get("content-length");
+    const totalMB = contentLength ? (Number(contentLength) / 1024 / 1024).toFixed(1) : "?";
+    log(`  Downloading ${totalMB} MB (compressed)...`);
+
+    const compressed = new Uint8Array(await response.arrayBuffer());
+    log(`  Decompressing...`);
+
+    let decompressed: Uint8Array;
+    try {
+      decompressed = gunzipSync(compressed);
+    } catch (e) {
+      lastError = new Error(`Gunzip failed (corrupt download or HTML error page): ${e}`);
+      if (isLast) throw lastError;
+      log(`  ${lastError.message}`);
+      continue;
+    }
+
+    // Validate magic bytes and minimum size before touching the filesystem.
+    if (decompressed.byteLength < MIN_DECOMPRESSED_BYTES) {
+      lastError = new Error(
+        `Decompressed DB too small: ${decompressed.byteLength} bytes (expected ≥ ${MIN_DECOMPRESSED_BYTES})`,
+      );
+      if (isLast) throw lastError;
+      log(`  ${lastError.message}`);
+      continue;
+    }
+    const header = new TextDecoder().decode(decompressed.subarray(0, SQLITE_MAGIC.length));
+    if (header !== SQLITE_MAGIC) {
+      lastError = new Error("Downloaded payload is not a SQLite database (magic bytes mismatch)");
+      if (isLast) throw lastError;
+      log(`  ${lastError.message}`);
+      continue;
+    }
+
+    // Write to a temp file next to the canonical DB path, validate, then rename.
+    const tmpPath = `${dbPath}.tmp.${process.pid}`;
+    try {
+      writeFileSync(tmpPath, decompressed);
+    } catch (e) {
+      lastError = new Error(`Write to ${tmpPath} failed: ${e}`);
+      throw lastError;
+    }
 
-  const contentLength = response.headers.get("content-length");
-  const totalMB = contentLength ? (Number(contentLength) / 1024 / 1024).toFixed(1) : "?";
-  log(`  Downloading ${totalMB} MB (compressed)...`);
+    const probe = probeDb(tmpPath);
+    if (!probe) {
+      tryUnlink(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);
+      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 \`bun pm cache rm\` and relaunch to pick up the latest package.`,
+      );
+      if (isLast) throw lastError;
+      log(`  ${lastError.message}`);
+      continue;
+    }
+    if (probe.pages < MIN_PAGES || probe.commands < MIN_COMMANDS) {
+      tryUnlink(tmpPath);
+      lastError = new Error(
+        `Downloaded DB content looks incomplete (pages=${probe.pages}, commands=${probe.commands})`,
+      );
+      if (isLast) throw lastError;
+      log(`  ${lastError.message} — trying fallback...`);
+      continue;
+    }
 
-  const compressed = new Uint8Array(await response.arrayBuffer());
-  log(`  Decompressing...`);
+    // Validation passed — drop stale WAL/SHM and atomically swap.
+    tryUnlink(`${dbPath}-wal`);
+    tryUnlink(`${dbPath}-shm`);
+    renameSync(tmpPath, dbPath);
 
-  const decompressed = gunzipSync(compressed);
-  writeFileSync(dbPath, decompressed);
+    const sizeMB = (decompressed.byteLength / 1024 / 1024).toFixed(1);
+    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;
+  }
+
+  throw lastError ?? new Error("Database download failed for unknown reasons");
+}
 
-  const sizeMB = (decompressed.byteLength / 1024 / 1024).toFixed(1);
-  log(`  Wrote ${sizeMB} MB to ${dbPath}`);
+/** Remove a file if it exists, swallowing all errors. */
+function tryUnlink(p: string): void {
+  try {
+    if (existsSync(p)) unlinkSync(p);
+  } catch {
+    // best-effort cleanup
+  }
+}
+
+/**
+ * Quiet refresh — download + validate + report stats. No MCP-config printing.
+ * Used by `--refresh` (and indirectly by mcp.ts when auto-recovering from a
+ * stale DB at startup). Returns true on success, false on failure.
+ */
+export async function refreshDb(log: (msg: string) => void = console.log): Promise<boolean> {
+  const dbPath = resolveDbPath(import.meta.dirname);
+  try {
+    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;
 }
 
 export async function runSetup(force = false) {
@@ -74,31 +265,36 @@ export async function runSetup(force = false) {
     console.log(`Database already exists: ${dbPath}`);
     console.log(`  (use --refresh or --setup --force to re-download)`);
   } else {
-    await downloadDb(dbPath);
+    try {
+      await downloadDb(dbPath);
+    } catch (e) {
+      console.error(`✗ Database download failed: ${e instanceof Error ? e.message : e}`);
+      process.exit(1);
+    }
   }
 
   // ── Validate DB ──
   console.log();
-  try {
-    const { default: sqlite } = await import("bun:sqlite");
-    // Note: open in read-write mode (not readonly) to allow WAL checkpoint.
-    // WAL-mode databases can fail to initialize properly in readonly mode.
-    const db = new sqlite(dbPath);
-    const row = db.prepare("SELECT COUNT(*) AS c FROM pages").get() as { c: number };
-    const cmdRow = db.prepare("SELECT COUNT(*) AS c FROM commands WHERE type='cmd'").get() as { c: number };
-    const versionRow = db.prepare("PRAGMA user_version").get() as { user_version: number };
-    db.close();
-    if (versionRow.user_version !== SCHEMA_VERSION) {
-      console.warn(`  Warning: DB schema version is ${versionRow.user_version}, expected ${SCHEMA_VERSION}.`);
-      console.warn(`  The downloaded DB may be incompatible with this version of rosetta.`);
-    }
-    console.log(`✓ Database ready (${row.c} pages, ${cmdRow.c} commands, schema v${versionRow.user_version})`);
-  } catch (e) {
-    console.error(`✗ Database validation failed: ${e}`);
+  const probe = 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";
     console.error(`  Try re-downloading with: ${retryCmd} --refresh`);
     process.exit(1);
   }
+  if (probe.schemaVersion !== SCHEMA_VERSION) {
+    console.error(
+      `✗ 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.`,
+    );
+    process.exit(1);
+  }
+  const tagInfo = probe.releaseTag ? ` (release ${probe.releaseTag})` : "";
+  console.log(
+    `✓ Database ready${tagInfo}: ${probe.pages} pages, ${probe.commands} commands, schema v${probe.schemaVersion}`,
+  );
 
   // ── Print config snippets ──
   console.log();