@bitcobblers/wod-wiki-tools 0.39.2143 → 0.40.2144

package/dist/bin/wod.cjs

@@ -1029,7 +1029,7 @@ var init_compiler = __esm({
 var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
-    VERSION = "0.39.2143";
+    VERSION = "0.40.2144";
   }
 });
 
@@ -2324,6 +2324,661 @@ function resolveDatabaseConfig(options = {}, env) {
   }
 }
 
+// src/cli/dbAdmin.ts
+init_db();
+var lifecycleSql;
+function loadSqlLifecycle() {
+  lifecycleSql ??= import(
+    /* @vite-ignore */
+    '@bitcobblers/wod-wiki-storage/sql'
+  );
+  return lifecycleSql;
+}
+function fullFs() {
+  return nodeFs();
+}
+function parseEnvContent(content) {
+  const g = globalThis;
+  const req = g.require ?? (typeof __require === "function" ? __require : void 0);
+  if (!req) throw new Error("[wod db] .env handling requires a CJS require shim (missing tsup banner?)");
+  return req("node:util").parseEnv(content);
+}
+function maskSecrets(message, ...secrets) {
+  let masked = message;
+  for (const secret of secrets) {
+    if (secret) masked = masked.split(secret).join("\u2022\u2022\u2022\u2022\u2022\u2022");
+  }
+  return masked;
+}
+var TursoManagement = class _TursoManagement {
+  constructor(organization, token, deps) {
+    this.organization = organization;
+    this.token = token;
+    this.deps = deps;
+  }
+  organization;
+  token;
+  deps;
+  /** Env-only credentials — never flags, never .env-file-only names. */
+  static fromEnv(env, deps = {}) {
+    const read = (key) => {
+      const value = env[key];
+      return value !== void 0 && value.trim() !== "" ? value.trim() : void 0;
+    };
+    const token = read("TURSO_API_TOKEN");
+    const organization = read("TURSO_ORGANIZATION");
+    if (!token || !organization) {
+      throw new Error(
+        "[wod db] management credentials required: set TURSO_API_TOKEN and TURSO_ORGANIZATION in the environment (or .env). Management tokens are never accepted as flags and never printed."
+      );
+    }
+    return new _TursoManagement(organization, token, deps);
+  }
+  async request(op, method, path, body) {
+    const base = this.deps.apiBase ?? "https://api.turso.tech";
+    let response;
+    try {
+      response = await (this.deps.fetchFn ?? fetch)(`${base}${path}`, {
+        method,
+        headers: { authorization: `Bearer ${this.token}`, ...body !== void 0 ? { "content-type": "application/json" } : {} },
+        body: body !== void 0 ? JSON.stringify(body) : void 0,
+        signal: AbortSignal.timeout(2e4)
+      });
+    } catch (error) {
+      throw new Error(`[wod db] ${op}: ${maskSecrets(error instanceof Error ? error.message : String(error), this.token)}`, { cause: error });
+    }
+    if (!response.ok) {
+      let detail = "";
+      try {
+        const parsed = await response.json();
+        if (typeof parsed === "object" && parsed !== null && "error" in parsed && typeof parsed.error === "string") {
+          detail = parsed.error;
+        }
+      } catch {
+      }
+      throw new Error(
+        `[wod db] ${op}: Turso API ${response.status} ${maskSecrets(detail || response.statusText, this.token)}`
+      );
+    }
+    if (response.status === 204) return void 0;
+    const text = await response.text();
+    if (text.trim() === "") return void 0;
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw new Error(`[wod db] ${op}: Turso API returned a non-JSON body with status ${response.status}`);
+    }
+  }
+  async getDatabase(name) {
+    try {
+      const payload = await this.request(
+        `get database ${name}`,
+        "GET",
+        `/v1/organizations/${encodeURIComponent(this.organization)}/databases/${encodeURIComponent(name)}`
+      );
+      if (typeof payload !== "object" || payload === null || !("database" in payload)) {
+        throw new Error(`[wod db] get database ${name}: Turso API payload has no database field`);
+      }
+      return toDatabaseInfo(payload.database);
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("Turso API 404")) return void 0;
+      throw error;
+    }
+  }
+  async createDatabase(input) {
+    const payload = await this.request(
+      `create database ${input.name}`,
+      "POST",
+      `/v1/organizations/${encodeURIComponent(this.organization)}/databases`,
+      input
+    );
+    if (typeof payload !== "object" || payload === null || !("database" in payload)) {
+      throw new Error(`[wod db] create database ${input.name}: Turso API payload has no database field`);
+    }
+    return toDatabaseInfo(payload.database);
+  }
+  /** Mint a database-scoped token (spec: authorization full-access|read-only). */
+  async createToken(name, authorization, expiration) {
+    const payload = await this.request(
+      `mint token for ${name}`,
+      "POST",
+      `/v1/organizations/${encodeURIComponent(this.organization)}/databases/${encodeURIComponent(name)}/auth/tokens?authorization=${authorization}&expiration=${encodeURIComponent(expiration)}`
+    );
+    if (typeof payload !== "object" || payload === null || !("jwt" in payload) || typeof payload.jwt !== "string" || payload.jwt === "") {
+      throw new Error(`[wod db] mint token for ${name}: Turso API returned no token`);
+    }
+    return payload.jwt;
+  }
+  async deleteDatabase(name) {
+    await this.request(
+      `delete database ${name}`,
+      "DELETE",
+      `/v1/organizations/${encodeURIComponent(this.organization)}/databases/${encodeURIComponent(name)}`
+    );
+  }
+};
+function toDatabaseInfo(value) {
+  if (typeof value !== "object" || value === null || !("Name" in value) || !("Hostname" in value)) {
+    throw new Error("[wod db] Turso API database payload is missing Name/Hostname");
+  }
+  const name = value.Name;
+  const hostname = value.Hostname;
+  if (typeof name !== "string" || name === "" || typeof hostname !== "string" || hostname === "") {
+    throw new Error("[wod db] Turso API database payload is missing Name/Hostname");
+  }
+  return {
+    name,
+    hostname,
+    dbId: "DbId" in value && typeof value.DbId === "string" ? value.DbId : void 0,
+    group: "group" in value && typeof value.group === "string" ? value.group : void 0
+  };
+}
+function writeSecretFile(fs, path, content) {
+  const tmp = `${path}.${nodeCrypto().randomUUID()}.tmp`;
+  const fd = fs.openSync(tmp, "wx", 384);
+  try {
+    fs.writeSync(fd, content);
+    fs.closeSync(fd);
+    fs.renameSync(tmp, path);
+  } catch (error) {
+    try {
+      fs.closeSync(fd);
+    } catch {
+    }
+    try {
+      fs.unlinkSync(tmp);
+    } catch {
+    }
+    throw error;
+  }
+}
+var CONTROL_CHARS = /[\u0000-\u001f\u007f\u0080-\u009f]/;
+function assertSafePairingFields(pairing) {
+  for (const [what, value] of [["target URL", pairing.url], ["auth token", pairing.authToken], ["database name", pairing.database]]) {
+    if (CONTROL_CHARS.test(value)) {
+      throw new Error(`[wod db] refusing: ${what} contains control characters (hostile API response)`);
+    }
+  }
+  let parsed;
+  try {
+    parsed = new URL(pairing.url);
+  } catch {
+    throw new Error("[wod db] refusing: target URL is not parseable");
+  }
+  if (parsed.protocol !== "libsql:" || parsed.hostname === "" || parsed.search !== "" || parsed.hash !== "") {
+    throw new Error("[wod db] refusing: target URL must be a plain libsql://<hostname>");
+  }
+}
+function writePairingFile(path, pairing, opts = {}) {
+  const fs = fullFs();
+  if (fs.existsSync(path) && !opts.force) {
+    throw new Error(`[wod db] refusing to overwrite existing pairing file ${path} (it contains a credential) \u2014 pass --force to replace it`);
+  }
+  assertSafePairingFields(pairing);
+  writeSecretFile(fs, path, JSON.stringify(pairing, null, 2) + "\n");
+}
+var ENV_GUARD_KEYS = [
+  "DB_DRIVER",
+  "DATABASE_URL",
+  "TURSO_DATABASE_URL",
+  "TURSO_AUTH_TOKEN",
+  "LIBSQL_AUTH_TOKEN",
+  "WOD_WIKI_DB",
+  "SQLITE_PATH",
+  "POSTGRES_HOST",
+  "POSTGRES_PORT",
+  "POSTGRES_USER",
+  "POSTGRES_PASSWORD",
+  "POSTGRES_DATABASE",
+  "POSTGRES_SSL"
+];
+function appendTursoEnv(envPath2, target, now) {
+  assertSafePairingFields({ url: target.url, authToken: target.authToken, database: "wod-wiki" });
+  const fs = fullFs();
+  const existing = fs.existsSync(envPath2) ? fs.readFileSync(envPath2, "utf8") : "";
+  const parsed = existing ? parseEnvContent(existing) : {};
+  const present = ENV_GUARD_KEYS.filter((key) => typeof parsed[key] === "string" && parsed[key].trim() !== "");
+  if (present.length > 0) {
+    throw new Error(
+      `[wod db] refusing to modify ${envPath2}: conflicting database selectors already set (${present.join(", ")}) \u2014 resolve them manually first; an appended Turso target would be ambiguous`
+    );
+  }
+  const block = `
+# wod db pair \u2014 added ${now.toISOString()}
+DB_DRIVER=turso
+TURSO_DATABASE_URL=${target.url}
+TURSO_AUTH_TOKEN=${target.authToken}
+`;
+  writeSecretFile(fs, envPath2, existing + block);
+}
+var DB_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+function assertDbName(name, what) {
+  if (!DB_NAME_PATTERN.test(name)) {
+    throw new Error(`[wod db] ${what} must match [a-z0-9][a-z0-9-]{0,63}, got "${name}"`);
+  }
+}
+function requireOutput(action, output) {
+  if (!output || output === "-") {
+    throw new Error(`[wod db ${action}] a pairing file path is required (-o <file>) \u2014 credentials are never printed`);
+  }
+  return output;
+}
+function requireSource(name, action) {
+  if (!name) {
+    throw new Error(`[wod db ${action}] missing source database name \u2014 usage: wod db ${action} <source> [options]`);
+  }
+  return name;
+}
+function requireGroup(action, group) {
+  if (!group || group.trim() === "") {
+    throw new Error(`[wod db ${action}] missing --group <name> \u2014 the Turso group must already exist`);
+  }
+  return group.trim();
+}
+function requireSourceGroup(action, info, args) {
+  if (info.group) return info.group;
+  if (args.group && args.group.trim() !== "") return args.group.trim();
+  throw new Error(`[wod db ${action}] the Turso API did not report a group for "${info.name}" \u2014 pass --group <name> explicitly`);
+}
+function requireWritersRetired(action, source, ack) {
+  if (!ack) {
+    throw new Error(
+      `[wod db ${action}] refusing to read a live source: retire its writers first (stop sync on every device), then pass --writers-retired to acknowledge "${source}" is frozen for the duration of the copy`
+    );
+  }
+}
+async function openLibsql(url, authToken, deps) {
+  const [{ createClient }, sql] = await Promise.all([
+    import(
+      /* @vite-ignore */
+      '@libsql/client'
+    ),
+    loadSqlLifecycle()
+  ]);
+  const connectionUrl = deps.databaseUrl?.(new URL(url).hostname) ?? url;
+  return sql.libsqlDatabase(createClient({ url: connectionUrl, authToken }));
+}
+async function closeQuietly(db) {
+  await db.close().catch(() => void 0);
+}
+function targetUrl(hostname) {
+  return `libsql://${hostname}`;
+}
+function snapshotValueEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a === "number" && typeof b === "number") return a === b || Number.isNaN(a) && Number.isNaN(b);
+  if (a === null || b === null || typeof a !== "object" || typeof b !== "object") return false;
+  const aBytes = a instanceof ArrayBuffer ? new Uint8Array(a) : ArrayBuffer.isView(a) ? new Uint8Array(a.buffer, a.byteOffset, a.byteLength) : void 0;
+  const bBytes = b instanceof ArrayBuffer ? new Uint8Array(b) : ArrayBuffer.isView(b) ? new Uint8Array(b.buffer, b.byteOffset, b.byteLength) : void 0;
+  if (aBytes !== void 0 || bBytes !== void 0) {
+    return aBytes !== void 0 && bBytes !== void 0 && aBytes.length === bBytes.length && aBytes.every((byte, i) => byte === bBytes[i]);
+  }
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  const aRecord = a;
+  const bRecord = b;
+  return aKeys.every((key) => key in bRecord && snapshotValueEqual(aRecord[key], bRecord[key]));
+}
+async function assertReplayMatches(sql, target, entries) {
+  const ops = [];
+  for (; ; ) {
+    const window = await sql.fetchSyncOps(target, ops.length === 0 ? 0 : ops[ops.length - 1].rev, 1e4);
+    if (window.length === 0) break;
+    ops.push(...window);
+  }
+  const expected = entries.flatMap((entry, entryIndex) => entry.ops.map((mutation, idx) => ({ opId: `${entry.id}:${idx}`, rev: entryIndex + 1, idx, at: entry.at, mutation })));
+  if (ops.length !== expected.length) {
+    throw new Error(`[wod db migrate] replay verification failed: target has ${ops.length} ops, snapshot has ${expected.length}`);
+  }
+  for (let i = 0; i < expected.length; i++) {
+    const got = ops[i];
+    const want = expected[i];
+    if (got.opId !== want.opId || got.rev !== want.rev || got.idx !== want.idx || got.at !== want.at || !snapshotValueEqual(got.mutation, want.mutation)) {
+      throw new Error(`[wod db migrate] replay verification failed at op ${i} (${want.opId}) \u2014 target diverges from the validated snapshot`);
+    }
+  }
+}
+var OPS_PER_GROUP = 200;
+function classifySource(probe, source) {
+  if (probe === "empty") throw new Error(`[wod db migrate] ${source} is empty \u2014 nothing to migrate`);
+  if (probe.kind === "unknown") throw new Error(`[wod db migrate] ${source} holds foreign data \u2014 refusing to touch it`);
+  if (probe.kind === "current") {
+    if (probe.schemaVersion === 0) throw new Error(`[wod db migrate] ${source} is an incomplete migration target (constructing marker) \u2014 it was never validated`);
+    if (probe.schemaVersion > wodWikiStorage.DB_VERSION) throw new Error(`[wod db migrate] ${source} is schema v${probe.schemaVersion}, newer than this CLI (v${wodWikiStorage.DB_VERSION}) \u2014 refusing`);
+    if (probe.schemaVersion === wodWikiStorage.DB_VERSION) throw new Error(`[wod db migrate] ${source} is already at schema v${wodWikiStorage.DB_VERSION} \u2014 nothing to migrate`);
+    return { fromVersion: probe.schemaVersion, legacy: false };
+  }
+  if (probe.schemaVersion > wodWikiStorage.DB_VERSION) {
+    throw new Error(`[wod db migrate] ${source} legacy schema v${probe.schemaVersion} is newer than this CLI (v${wodWikiStorage.DB_VERSION}) \u2014 refusing`);
+  }
+  return { fromVersion: probe.schemaVersion, legacy: true };
+}
+async function convertSource(source, fromVersion, legacy) {
+  const fake = await import(
+    /* @vite-ignore */
+    'fake-indexeddb'
+  );
+  const globals = globalThis;
+  for (const [key, value] of Object.entries(fake)) {
+    if (key !== "default") globals[key] = value;
+  }
+  globals.indexedDB = new fake.IDBFactory();
+  const idb = await import(
+    /* @vite-ignore */
+    '@bitcobblers/wod-wiki-storage/idb'
+  );
+  return idb.convertSyncSource(source, fromVersion, legacy);
+}
+function snapshotEntries(mutations, snapshotId, at) {
+  const entries = [];
+  for (let start = 0; start < mutations.length; start += OPS_PER_GROUP) {
+    entries.push({ id: `${snapshotId}-${entries.length}`, at, ops: mutations.slice(start, start + OPS_PER_GROUP) });
+  }
+  return entries;
+}
+async function runCreate(mgmt, args, deps, io, now) {
+  const output = requireOutput("create", args.output);
+  const group = requireGroup("create", args.group);
+  const dbName = args.dbName ?? `wod-wiki-v${wodWikiStorage.DB_VERSION}`;
+  assertDbName(dbName, "database name");
+  if (await mgmt.getDatabase(dbName)) {
+    throw new Error(`[wod db create] database "${dbName}" already exists \u2014 pair it with \`wod db pair ${dbName}\` or choose --name`);
+  }
+  const created = await mgmt.createDatabase({ name: dbName, group });
+  const url = targetUrl(created.hostname);
+  const token = await mgmt.createToken(dbName, "full-access", "never");
+  const db = await openLibsql(url, token, deps);
+  let probe;
+  try {
+    probe = await (await loadSqlLifecycle()).probeSyncTarget(db);
+  } finally {
+    await closeQuietly(db);
+  }
+  if (probe !== "empty") {
+    throw new Error(`[wod db create] freshly provisioned "${dbName}" probed as ${JSON.stringify(probe)}, expected empty \u2014 refusing to pair`);
+  }
+  const pairing = {
+    wodWikiPairing: 1,
+    kind: "turso",
+    url,
+    authToken: token,
+    database: dbName,
+    schemaVersion: wodWikiStorage.DB_VERSION,
+    createdAt: now.toISOString()
+  };
+  try {
+    writePairingFile(output, pairing, { force: args.force });
+    if (args.writeEnv) appendTursoEnv(envPath(args), { url, authToken: token }, now);
+  } catch (error) {
+    io.stderr(
+      `[wod db create] pairing/config write failed (${error instanceof Error ? error.message : String(error)}) \u2014 the database "${dbName}" was created and was NOT deleted; recover with \`wod db pair ${dbName} --allow-empty -o <file>\`. No settings were changed.`
+    );
+    throw error;
+  }
+  io.stdout(`[wod db create] provisioned ${dbName} (${created.hostname}, group ${group}) \u2014 empty target ready for the browser's first bootstrap`);
+  io.stdout(`[wod db create] pairing file: ${output}${args.writeEnv ? `; wrote ${envPath(args)}` : ""}`);
+}
+function envPath(args) {
+  return args.envFile ?? ".env";
+}
+async function copyNative(kind, mgmt, args, deps, io, now) {
+  const source = requireSource(args.name, kind);
+  requireWritersRetired(kind, source, args.writersRetired);
+  requireOutput(kind, args.output);
+  const info = await mgmt.getDatabase(source);
+  if (!info) throw new Error(`[wod db ${kind}] database not found: ${source}`);
+  const copyName = args.dbName ?? `${sanitizeDbName(source)}-${kind}-${stamp(now)}`;
+  assertDbName(copyName, "copy name");
+  if (copyName === source) {
+    throw new Error(`[wod db ${kind}] the copy must be a NEW database \u2014 "${copyName}" is the source itself`);
+  }
+  if (await mgmt.getDatabase(copyName)) {
+    throw new Error(`[wod db ${kind}] target "${copyName}" already exists \u2014 choose --name`);
+  }
+  const sql = await loadSqlLifecycle();
+  const group = requireSourceGroup(kind, info, args);
+  const sourceToken = await mgmt.createToken(source, "read-only", "1h");
+  const sourceDb = await openLibsql(targetUrl(info.hostname), sourceToken, deps);
+  try {
+    const before = await sql.databaseFingerprint(sourceDb);
+    const copy = await mgmt.createDatabase({
+      name: copyName,
+      group,
+      seed: { type: "database", name: source }
+    });
+    if (deps.midCopyHook) await deps.midCopyHook(copyName);
+    const copyToken = await mgmt.createToken(copyName, "read-only", "1h");
+    const copyDb = await openLibsql(targetUrl(copy.hostname), copyToken, deps);
+    let after;
+    try {
+      after = await sql.assertDatabaseCopyMatches(sourceDb, copyDb, before);
+    } finally {
+      await closeQuietly(copyDb);
+    }
+    return finishCopy(kind, mgmt, args, io, now, copy, after);
+  } finally {
+    await closeQuietly(sourceDb);
+  }
+}
+async function finishCopy(kind, mgmt, args, io, now, copy, after) {
+  io.stdout(
+    `[wod db ${kind}] native copy "${copy.name}" verified: ${after.tables} tables, ${after.rows} rows, digest ${after.digest.slice(0, 8)} \u2014 source retained unchanged`
+  );
+  if (kind === "backup" || after.sync === void 0 || after.sync.schema !== wodWikiStorage.DB_VERSION) {
+    const schemaLabel = after.sync === void 0 ? "(legacy, no sync state)" : `v${after.sync.schema}`;
+    io.stdout(
+      `[wod db ${kind}] copy is schema ${schemaLabel} \u2014 retained as a read-only archive, NOT pairable for sync. Use \`wod db restore ${copy.name}\` for a writable current-schema copy or \`wod db migrate ${copy.name}\` to convert an older schema.`
+    );
+    if (args.output && args.output !== "-") {
+      const roToken = await mgmt.createToken(copy.name, "read-only", "never");
+      writePairingFile(args.output, {
+        wodWikiPairing: 1,
+        kind: "turso",
+        url: targetUrl(copy.hostname),
+        authToken: roToken,
+        database: copy.name,
+        schemaVersion: after.sync === void 0 ? 0 : after.sync.schema,
+        createdAt: now.toISOString()
+      }, { force: args.force });
+      io.stdout(`[wod db ${kind}] read-only archive pairing file: ${args.output}`);
+    }
+    return { info: copy, fingerprint: after };
+  }
+  try {
+    await pairTarget(mgmt, args, io, now, copy.name, copy.hostname, after.sync.schema);
+  } catch (error) {
+    io.stderr(
+      `[wod db ${kind}] pairing/config write failed (${error instanceof Error ? error.message : String(error)}) \u2014 the verified copy "${copy.name}" was NOT deleted; recover with \`wod db pair ${copy.name} -o <file>\`. No settings were changed.`
+    );
+    throw error;
+  }
+  return { info: copy, fingerprint: after };
+}
+async function runMigrate(mgmt, args, deps, io, now) {
+  const source = requireSource(args.name, "migrate");
+  requireWritersRetired("migrate", source, args.writersRetired);
+  const output = requireOutput("migrate", args.output);
+  const info = await mgmt.getDatabase(source);
+  if (!info) throw new Error(`[wod db migrate] database not found: ${source}`);
+  const sql = await loadSqlLifecycle();
+  const sourceToken = await mgmt.createToken(source, "read-only", "1h");
+  const sourceDb = await openLibsql(targetUrl(info.hostname), sourceToken, deps);
+  let before;
+  let entries;
+  try {
+    before = await sql.databaseFingerprint(sourceDb);
+    const classified = classifySource(await sql.probeSyncTarget(sourceDb), source);
+    const mutations = await convertSource(sourceDb, classified.fromVersion, classified.legacy);
+    if (mutations.length === 0) {
+      throw new Error("[wod db migrate] conversion produced no rows \u2014 refusing to create an empty target");
+    }
+    entries = snapshotEntries(mutations, `m${classified.fromVersion}-${before.digest.slice(0, 8)}`, now.getTime());
+    sql.assertPolicySnapshot(entries.flatMap((entry) => entry.ops));
+  } finally {
+    await closeQuietly(sourceDb);
+  }
+  const targetName = args.dbName ?? `${sanitizeDbName(source)}-v${wodWikiStorage.DB_VERSION}`;
+  assertDbName(targetName, "target name");
+  if (targetName === source) {
+    throw new Error("[wod db migrate] the target must be a NEW database \u2014 retention keeps the source at its own name");
+  }
+  if (await mgmt.getDatabase(targetName)) {
+    throw new Error(`[wod db migrate] target "${targetName}" already exists \u2014 choose --name (a fresh, exclusively reserved target is required)`);
+  }
+  const created = await mgmt.createDatabase({ name: targetName, group: requireSourceGroup("migrate", info, args) });
+  let token;
+  let committed;
+  try {
+    token = await mgmt.createToken(targetName, "full-access", "never");
+    const target = await openLibsql(targetUrl(created.hostname), token, deps);
+    try {
+      const probe = await sql.probeSyncTarget(target);
+      if (probe !== "empty") throw new Error(`[wod db migrate] target "${targetName}" is not empty (${JSON.stringify(probe)}) \u2014 refusing`);
+      await sql.initSyncTarget(target, 0);
+      committed = await sql.applySyncBatch(target, entries, { expectSchema: 0 });
+      await assertReplayMatches(sql, target, entries);
+      const sourceDbRecheck = await openLibsql(targetUrl(info.hostname), sourceToken, deps);
+      try {
+        await sql.assertDatabaseCopyMatches(sourceDbRecheck, sourceDbRecheck, before);
+      } finally {
+        await closeQuietly(sourceDbRecheck);
+      }
+      await sql.finalizeMigrationTarget(target, wodWikiStorage.DB_VERSION, committed);
+    } finally {
+      await closeQuietly(target);
+    }
+  } catch (error) {
+    io.stderr(
+      `[wod db migrate] target "${targetName}" was left INCOMPLETE and is not pairable (constructing marker). Inspect or remove it: \`wod db delete ${targetName} --yes ${targetName}\`. The source "${source}" was not modified.`
+    );
+    throw error;
+  }
+  try {
+    writePairingFile(output, {
+      wodWikiPairing: 1,
+      kind: "turso",
+      url: targetUrl(created.hostname),
+      authToken: token,
+      database: targetName,
+      schemaVersion: wodWikiStorage.DB_VERSION,
+      createdAt: now.toISOString()
+    }, { force: args.force });
+    if (args.writeEnv) appendTursoEnv(envPath(args), { url: targetUrl(created.hostname), authToken: token }, now);
+  } catch (error) {
+    io.stderr(
+      `[wod db migrate] pairing/config write failed (${error instanceof Error ? error.message : String(error)}) \u2014 the target "${targetName}" is complete at v${wodWikiStorage.DB_VERSION} and was NOT deleted; recover with \`wod db pair ${targetName} -o <file>\`. No settings were changed.`
+    );
+    throw error;
+  }
+  io.stdout(
+    `[wod db migrate] ${source} (schema ${before.sync ? `v${before.sync.schema}` : "legacy"}) \u2192 ${targetName} at v${wodWikiStorage.DB_VERSION}: ${entries.length} groups / ${committed} committed, replay + pins + source CAS verified \u2014 source retained`
+  );
+  io.stdout(`[wod db migrate] pairing file: ${output}${args.writeEnv ? `; wrote ${envPath(args)}` : ""}`);
+}
+async function runDelete(args, io, deps) {
+  const name = requireSource(args.name, "delete");
+  if (!args.yes) {
+    throw new Error(`[wod db delete] deletion requires exact confirmation: wod db delete ${name} --yes ${name}`);
+  }
+  if (args.yes !== name) {
+    throw new Error(`[wod db delete] confirmation mismatch: --yes "${args.yes}" does not exactly match "${name}" \u2014 nothing was deleted`);
+  }
+  await TursoManagement.fromEnv(args.env, { fetchFn: deps.fetchFn }).deleteDatabase(name);
+  io.stdout(`[wod db delete] deleted ${name}`);
+}
+async function pairTarget(mgmt, args, io, now, dbName, hostname, schemaVersion) {
+  const output = requireOutput("pair", args.output);
+  const token = await mgmt.createToken(dbName, "full-access", "never");
+  const url = targetUrl(hostname);
+  writePairingFile(output, {
+    wodWikiPairing: 1,
+    kind: "turso",
+    url,
+    authToken: token,
+    database: dbName,
+    schemaVersion,
+    createdAt: now.toISOString()
+  }, { force: args.force });
+  if (args.writeEnv) appendTursoEnv(envPath(args), { url, authToken: token }, now);
+  io.stdout(`[wod db pair] ${dbName} (${hostname}) at schema v${schemaVersion} \u2014 pairing file: ${output}${args.writeEnv ? `; wrote ${envPath(args)}` : ""}`);
+}
+async function runPair(mgmt, args, deps, io, now) {
+  const name = requireSource(args.name, "pair");
+  const info = await mgmt.getDatabase(name);
+  if (!info) throw new Error(`[wod db pair] database not found: ${name}`);
+  const sql = await loadSqlLifecycle();
+  const probeToken = await mgmt.createToken(name, "read-only", "1h");
+  const db = await openLibsql(targetUrl(info.hostname), probeToken, deps);
+  let probe;
+  try {
+    await db.query("SELECT 1");
+    probe = await sql.probeSyncTarget(db);
+    if (probe !== "empty" && probe.kind === "current") {
+      const ops = [];
+      let cursor = 0;
+      for (; ; ) {
+        const window = await sql.fetchSyncOps(db, cursor, 1e4);
+        if (window.length === 0) break;
+        ops.push(...window);
+        cursor = window[window.length - 1].rev;
+      }
+      sql.assertLogPinClosure(ops);
+    }
+  } finally {
+    await closeQuietly(db);
+  }
+  if (probe === "empty") {
+    if (!args.allowEmpty) {
+      throw new Error(`[wod db pair] ${name} is empty \u2014 it is only pairable for a deliberate first bootstrap (--allow-empty), after \`wod db create\`, or once a browser initialized it`);
+    }
+    await pairTarget(mgmt, args, io, now, name, info.hostname, wodWikiStorage.DB_VERSION);
+    return;
+  }
+  if (probe.kind === "unknown") {
+    throw new Error(`[wod db pair] ${name} holds foreign data \u2014 refusing to pair`);
+  }
+  if (probe.kind === "legacy") {
+    throw new Error(`[wod db pair] ${name} is a legacy direct-Turso database (v${probe.schemaVersion}) \u2014 run \`wod db migrate ${name}\` first`);
+  }
+  if (probe.schemaVersion === 0) {
+    throw new Error(`[wod db pair] ${name} is an incomplete migration target (constructing marker) \u2014 it was never validated and stays unpairable`);
+  }
+  if (probe.schemaVersion !== wodWikiStorage.DB_VERSION) {
+    throw new Error(`[wod db pair] ${name} is schema v${probe.schemaVersion}, this CLI manages v${wodWikiStorage.DB_VERSION} \u2014 run \`wod db migrate ${name}\` first`);
+  }
+  await pairTarget(mgmt, args, io, now, name, info.hostname, probe.schemaVersion);
+}
+function sanitizeDbName(raw) {
+  const cleaned = raw.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+/, "").replace(/-+$/, "");
+  return cleaned === "" ? "wod-wiki" : cleaned.slice(0, 64).replace(/-+$/, "");
+}
+function stamp(now) {
+  return now.toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z").toLowerCase();
+}
+async function runDbCommand(args, io, deps = {}) {
+  const now = (deps.now ?? (() => /* @__PURE__ */ new Date()))();
+  const mgmt = () => TursoManagement.fromEnv(args.env, { fetchFn: deps.fetchFn });
+  switch (args.action) {
+    case "create":
+      return runCreate(mgmt(), args, deps, io, now);
+    case "backup":
+    case "restore":
+      await copyNative(args.action, mgmt(), args, deps, io, now);
+      return;
+    case "migrate":
+      return runMigrate(mgmt(), args, deps, io, now);
+    case "delete":
+      return runDelete(args, io, deps);
+    case "pair":
+      return runPair(mgmt(), args, deps, io, now);
+    default:
+      throw new Error(
+        `[wod db] unknown action "${args.action ?? ""}" \u2014 usage: wod db <create|backup|restore|migrate|delete|pair> [name] [options]`
+      );
+  }
+}
+
 // src/cli/persist.ts
 init_db();
 var registeredWidgets = wodWikiCore.KNOWN_SECTION_WIDGETS;
@@ -3142,6 +3797,9 @@ ${fence}
 var VALUE_FLAGS = [
   ["--db", "db"],
   ["--db-driver", "dbDriver"],
+  ["--group", "group"],
+  ["--name", "dbName"],
+  ["--yes", "yes"],
   ["--database-url", "databaseUrl"],
   ["--postgres-host", "postgresHost"],
   ["--postgres-port", "postgresPort"],
@@ -3248,6 +3906,18 @@ function parseCliArgs(args) {
     } else if (arg === "--scaffold") {
       result.scaffold = true;
       i++;
+    } else if (arg === "--writers-retired") {
+      result.writersRetired = true;
+      i++;
+    } else if (arg === "--allow-empty") {
+      result.allowEmpty = true;
+      i++;
+    } else if (arg === "--write-env") {
+      result.writeEnv = true;
+      i++;
+    } else if (arg === "--force") {
+      result.force = true;
+      i++;
     } else if (arg === "--template") {
       result.template = args[++i];
       i++;
@@ -3274,7 +3944,7 @@ function parseCliArgs(args) {
       if (Number.isSafeInteger(v) && v >= 0) result.seedVersion = v;
       i++;
     } else if (!result.subcommand) {
-      if (arg === "parse" || arg === "run" || arg === "query" || arg === "download" || arg === "export" || arg === "import" || arg === "publish" || arg === "build" || arg === "seed" || arg === "reset" || arg === "init" || arg === "server" || arg === "serve" || arg === "playground" || arg === "init-catalog" || arg === "help" || arg === "version") {
+      if (arg === "parse" || arg === "run" || arg === "query" || arg === "download" || arg === "export" || arg === "import" || arg === "publish" || arg === "build" || arg === "seed" || arg === "reset" || arg === "init" || arg === "db" || arg === "server" || arg === "serve" || arg === "playground" || arg === "init-catalog" || arg === "help" || arg === "version") {
         result.subcommand = arg;
       } else {
         result.target = arg;
@@ -3347,6 +4017,47 @@ USAGE:
   wod seed [options]
   wod reset [options]
   wod init            Initialize the configured database (idempotent)
+  wod db <action> [name] [options]
+                      Turso database lifecycle (management credentials from
+                      the environment only: TURSO_API_TOKEN + TURSO_ORGANIZATION;
+                      never flags, never printed):
+  wod db create [--name <db>] --group <g> -o <pairing-file>
+                      Provision a fresh empty target (default name
+                      wod-wiki-v<schema>) and write its pairing file.
+  wod db backup <source> [--name <copy>] --writers-retired -o <file>
+  wod db restore <source> [--name <copy>] --writers-retired -o <file>
+                      Native whole-database copy (Control API seed); verified
+                      row- and binary-identical before any token is minted.
+                      Backups receive read-only archive credentials. Restore
+                      copies are writable only at the current schema;
+                      older-schema copies stay read-only until migrated.
+  wod db migrate <source> [--name <target>] --writers-retired -o <file>
+                      Logical conversion to a fresh current-schema target via
+                      the shared IndexedDB adapter. The target stays
+                      unpairable (constructing marker) until replay, pin and
+                      source-immutability checks pass; the source is retained.
+  wod db delete <name> --yes <name>
+                      Delete a database \u2014 --yes must repeat the exact name.
+  wod db pair <name> [--allow-empty] -o <file> [--write-env]
+                      Mint a database-scoped token and write the pairing file
+                      for the browser Data settings (0600, exclusive create;
+                      --force replaces atomically). Refuses foreign, legacy,
+                      newer and unvalidated targets. --write-env opt-in
+                      appends DB_DRIVER/TURSO_* to the .env atomically and
+                      refuses to replace existing database settings.
+
+DB OPTIONS (for 'wod db'):
+  --name <db>         Explicit target/copy database name
+  --group <g>         Turso group for 'create' (must exist); fallback target
+                      group when the API does not report one
+  --writers-retired   Acknowledge all writers on the source were stopped
+                      before backup/restore/migrate read it
+  --allow-empty       'pair' a deliberately empty bootstrap target
+  --write-env         Opt-in .env output (atomic, refuses replacement)
+  --force             Replace an existing pairing file (stays 0600)
+  -o, --output <file> Pairing file path \u2014 REQUIRED for credential-issuing
+                      actions; credentials are never printed to stdout
+
   wod server [options]
                       Serve the app (HTTP API + packaged frontend; alias: serve)
   wod playground [options]
@@ -3475,6 +4186,7 @@ ENVIRONMENT (flags > process env > .env):
   POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER,
   POSTGRES_PASSWORD, POSTGRES_DATABASE, POSTGRES_SSL
   TURSO_DATABASE_URL, TURSO_AUTH_TOKEN, LIBSQL_AUTH_TOKEN
+  TURSO_API_TOKEN, TURSO_ORGANIZATION  wod db management credentials (env only)
   HOST, PORT, PLAYGROUND_DIST       server / playground defaults
 
 EXIT CODES:
@@ -3988,6 +4700,28 @@ async function cliMain(argv = process.argv.slice(2), io = {}) {
       }
       return 0;
     }
+    if (parsed.subcommand === "db") {
+      try {
+        await runDbCommand({
+          action: parsed.target,
+          name: parsed.target2,
+          dbName: parsed.dbName,
+          group: parsed.group,
+          yes: parsed.yes,
+          output: parsed.output,
+          writeEnv: parsed.writeEnv === true,
+          writersRetired: parsed.writersRetired === true,
+          allowEmpty: parsed.allowEmpty === true,
+          force: parsed.force === true,
+          envFile: parsed.envFile,
+          env: cliEnv()
+        }, { stdout: writeOut, stderr: writeErr }, io.dbDeps);
+        return 0;
+      } catch (error) {
+        writeErr(error instanceof Error ? error.message : String(error));
+        return 1;
+      }
+    }
     if (parsed.subcommand === "server" || parsed.subcommand === "serve" || parsed.subcommand === "playground") {
       const mode = parsed.subcommand === "playground" ? "playground" : "server";
       const { runCliServer: runCliServer2 } = await Promise.resolve().then(() => (init_server(), server_exports));