naro-cli 0.7.0 → 0.8.0

package/README.md

@@ -86,6 +86,12 @@ naro db enable                     Create the project's database (Cloudflare D1)
 naro db info                       Status, size, table count, limits
 naro db query "select 1"           Run SQL; --file query.sql, or pipe stdin
 naro db push [--dry-run]           Apply pending ./migrations (asks first; --yes in CI)
+naro db dump --output backup.sql   SQL dump, streamed from Cloudflare (stdout without
+                                   --output); --schema-only | --data-only, --table a,b
+naro db restore --bookmark <id>    Time Travel, last 30 days (or --timestamp <time>);
+                                   asks first, prints the command that undoes it
+naro db pull                       Existing database, no migrations yet: writes its schema
+                                   as migrations/0001_remote_schema.sql, recorded as applied
 naro migration new create_users    Creates migrations/0001_create_users.sql
 naro migration list                Local files vs the d1_migrations ledger
 naro gen types --output src/db.d.ts  TypeScript types for the schema
@@ -108,6 +114,14 @@ An apex (`example.com`) is added as a pair by default because most registrars
 goes on `www.example.com` and the apex answers with a 308 redirect to it.
 `--no-www` registers the apex alone.
 
+`naro db dump` asks Cloudflare for the dump and streams it straight from
+Cloudflare's storage to the file — the bytes never pass through naro. While the
+export runs, Cloudflare holds every other query to the database, so dump a busy
+production database when a short pause is acceptable. It ends with the bookmark
+the dump reflects; `naro db restore --bookmark <that>` brings the database back
+to it. A restore rolls back everything written after that point — the
+`d1_migrations` ledger included — and prints the bookmark that undoes it.
+
 ## Machine-readable output (CI / AI agents)
 
 Every command supports `--json`: stdout carries exactly one JSON object,

package/dist/{chunk-E2M6CQL7.js → chunk-ONALKL7O.js}

@@ -18833,6 +18833,9 @@ var LogsApi = class {
     return body.entries;
   }
 };
+var EXPORT_FIRST_POLL_MS = 1e3;
+var EXPORT_MAX_POLL_MS = 5e3;
+var EXPORT_TIMEOUT_MS = 15 * 6e4;
 var DbApi = class {
   constructor(client) {
     this.client = client;
@@ -18903,9 +18906,127 @@ var DbApi = class {
       }
     );
   }
+  /**
+   * The current Time Travel bookmark, or the one `timestamp` (RFC 3339 with a
+   * timezone, or Unix seconds) names. The server checks the range - the last
+   * 30 days, not before the database existed - before asking Cloudflare.
+   */
+  async bookmark(projectId, options = {}) {
+    const query = options.timestamp === void 0 ? "" : `?timestamp=${encodeURIComponent(options.timestamp)}`;
+    const body = await this.client.request(
+      this.path(projectId, `/bookmark${query}`),
+      { context: "Read bookmark" }
+    );
+    return { bookmark: body.bookmark, timestamp: body.timestamp };
+  }
+  /**
+   * Rolls the database back to a bookmark or a timestamp - rows, schema and
+   * the migration ledger alike - and cancels queries in flight. Restoring to
+   * `previousBookmark` undoes it.
+   */
+  async restore(projectId, target) {
+    const given = target;
+    const body = await this.client.request(
+      this.path(projectId, "/restore"),
+      {
+        method: "POST",
+        body: {
+          ...given.bookmark !== void 0 ? { bookmark: given.bookmark } : {},
+          ...given.timestamp !== void 0 ? { timestamp: given.timestamp } : {}
+        },
+        context: "Restore database"
+      }
+    );
+    return { bookmark: body.bookmark, previousBookmark: body.previousBookmark };
+  }
+  /**
+   * One step of an export: starts it, or - with the first step's
+   * `atBookmark` as `currentBookmark` - polls it. See `export` for the loop.
+   */
+  async exportStep(projectId, options = {}) {
+    const body = await this.client.request(
+      this.path(projectId, "/export"),
+      {
+        method: "POST",
+        // Only the keys given: the server validates each one it sees.
+        body: {
+          ...options.schemaOnly !== void 0 ? { schemaOnly: options.schemaOnly } : {},
+          ...options.dataOnly !== void 0 ? { dataOnly: options.dataOnly } : {},
+          ...options.tables !== void 0 ? { tables: options.tables } : {},
+          ...options.currentBookmark !== void 0 ? { currentBookmark: options.currentBookmark } : {}
+        },
+        context: "Export database"
+      }
+    );
+    return body.export;
+  }
+  /**
+   * Exports the database and polls until the dump is ready. The server takes
+   * one Cloudflare step per call - a big database runs for minutes, longer
+   * than a Worker should wait - so the loop is here: 1 s, then 1.5x per poll
+   * up to 5 s. Cloudflare holds every other query to the database while the
+   * export runs.
+   *
+   * On TIMEOUT the export is still running at Cloudflare; nothing was
+   * cancelled.
+   */
+  async export(projectId, options = {}, wait = {}) {
+    const timeoutMs = wait.timeoutMs ?? EXPORT_TIMEOUT_MS;
+    const sleep2 = wait.sleep ?? ((ms) => new Promise((resolve10) => setTimeout(resolve10, ms)));
+    const given = wait.pollIntervalMs;
+    const firstPollMs = given !== void 0 && Number.isFinite(given) && given > 0 ? given : EXPORT_FIRST_POLL_MS;
+    const maxPollMs = Math.max(EXPORT_MAX_POLL_MS, firstPollMs);
+    const startedAt = Date.now();
+    let step = await this.exportStep(projectId, options);
+    wait.onProgress?.(step);
+    const currentBookmark = step.atBookmark;
+    const polled = {
+      ...options,
+      ...step.tables !== void 0 ? { tables: step.tables } : {}
+    };
+    let intervalMs = firstPollMs;
+    while (step.status !== "complete") {
+      if (Date.now() - startedAt >= timeoutMs) {
+        throw new NaroError(
+          "TIMEOUT",
+          `The export was still running after ${String(Math.round(timeoutMs / 6e4))} minutes. Cloudflare keeps it going; run naro db dump again later.`,
+          { details: { atBookmark: currentBookmark } }
+        );
+      }
+      await sleep2(intervalMs);
+      intervalMs = Math.min(intervalMs * 1.5, maxPollMs);
+      step = await this.exportStep(projectId, { ...polled, currentBookmark });
+      wait.onProgress?.(step);
+    }
+    return step;
+  }
+  /**
+   * Records the remote schema as the already-applied migration `name` and
+   * returns its SQL - a baseline for a database that has none. Refused with
+   * DATABASE_HAS_MIGRATIONS when the ledger has rows, DATABASE_EMPTY when
+   * there is no schema. The caller writes the file.
+   */
+  async pull(projectId, input) {
+    return this.client.request(this.path(projectId, "/pull"), {
+      method: "POST",
+      body: { name: input.name },
+      context: "Pull schema"
+    });
+  }
 };
 
 // ../../packages/sdk/src/database.ts
+var BOOKMARK_RE = /^[0-9a-f]{8}-[0-9a-f]{8}-[0-9a-f]{8}-[0-9a-f]{32}$/;
+var BOOKMARK_FORMAT_MESSAGE = "bookmark must look like 00000001-00000008-000050ed-272153b8520cfb93b49834d93a1a1ab3 (four hyphen-separated hex groups, 59 characters).";
+function isBookmark(value) {
+  return typeof value === "string" && BOOKMARK_RE.test(value);
+}
+var RESTORE_OUTCOME_UNKNOWN_CODES = /* @__PURE__ */ new Set([
+  "DATABASE_RESTORE_FAILED",
+  "DATABASE_UNAVAILABLE",
+  "TIMEOUT",
+  "NETWORK_ERROR"
+]);
 var MAX_CELL_CHARS = 60;
 function formatCell(value) {
   if (value === null || value === void 0) return "NULL";
@@ -19905,6 +20026,9 @@ export {
   openBrowser,
   isTerminalStatus,
   NaroClient,
+  BOOKMARK_FORMAT_MESSAGE,
+  isBookmark,
+  RESTORE_OUTCOME_UNKNOWN_CODES,
   renderRows,
   summarizeStatement,
   serializeDotenv,

package/dist/deploy.js

@@ -5,7 +5,7 @@ import {
   parseDotenv,
   readProjectEnv,
   slugify
-} from "./chunk-E2M6CQL7.js";
+} from "./chunk-ONALKL7O.js";
 export {
   deployDirectory,
   eventsObserver,

package/dist/index.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import {
+  BOOKMARK_FORMAT_MESSAGE,
   NaroClient,
   NaroError,
+  RESTORE_OUTCOME_UNKNOWN_CODES,
   clearSession,
   compareMigrations,
   controlPlaneUrl,
@@ -10,6 +12,7 @@ import {
   detectGitInfo,
   ensureGitignoreHasNaro,
   generateTypes,
+  isBookmark,
   isExpired,
   isNaroError,
   isTerminalStatus,
@@ -33,7 +36,7 @@ import {
   summarizeStatement,
   toNaroError,
   writeProjectLink
-} from "./chunk-E2M6CQL7.js";
+} from "./chunk-ONALKL7O.js";
 
 // src/args.ts
 var BOOLEAN_FLAGS = {
@@ -52,7 +55,9 @@ var BOOLEAN_FLAGS = {
   "--reveal": "reveal",
   "--wait": "wait",
   "--no-www": "noWww",
-  "--dry-run": "dryRun"
+  "--dry-run": "dryRun",
+  "--schema-only": "schemaOnly",
+  "--data-only": "dataOnly"
 };
 var STRING_FLAGS = {
   "--token": "token",
@@ -67,8 +72,15 @@ var STRING_FLAGS = {
   "--level": "level",
   "--file": "file",
   "--output": "output",
-  "--dir": "dir"
+  "--dir": "dir",
+  "--table": "table",
+  "--timestamp": "timestamp",
+  "--bookmark": "bookmark"
 };
+function listFlag(value) {
+  if (value === void 0) return [];
+  return value.split(",").map((piece) => piece.trim()).filter((piece) => piece.length > 0);
+}
 function parseArgs(argv) {
   const flags = {
     json: false,
@@ -220,7 +232,7 @@ var TtyPrompter = class {
     });
     try {
       return await new Promise(
-        (resolve3) => rl.question(question, resolve3)
+        (resolve4) => rl.question(question, resolve4)
       );
     } finally {
       rl.close();
@@ -241,7 +253,7 @@ var TtyPrompter = class {
     });
     try {
       const answer = new Promise(
-        (resolve3) => rl.question(question, resolve3)
+        (resolve4) => rl.question(question, resolve4)
       );
       muted = true;
       const value = await answer;
@@ -353,7 +365,7 @@ function createContext(flags, positionals = []) {
 
 // src/router.ts
 import { readFileSync as readFileSync3 } from "fs";
-import { dirname as dirname2, join as join3 } from "path";
+import { dirname as dirname3, join as join4 } from "path";
 import { fileURLToPath } from "url";
 
 // src/commands/auth.ts
@@ -566,11 +578,474 @@ async function runDbQuery(context, deps = processStdin) {
   context.output.result({ projectId, result }, lines);
 }
 
-// src/commands/git.ts
+// src/commands/db-backup.ts
+import {
+  createWriteStream,
+  mkdirSync as mkdirSync2,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync as writeFileSync2
+} from "fs";
+import { basename, dirname, join as join2, resolve as resolve2 } from "path";
+import { Transform } from "stream";
+import { pipeline } from "stream/promises";
+
+// src/commands/migration.ts
+import { mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
+import { join, relative } from "path";
+var processStdin2 = {
+  stdinIsTty: () => process.stdin.isTTY === true,
+  readStdin
+};
+function migrationsDir(context) {
+  return resolveMigrationsDir({
+    baseDir: context.cwd,
+    rootDirectory: context.flags.root,
+    dir: context.flags.dir
+  });
+}
+function relativeToCwd(context, path) {
+  const rel = relative(context.cwd, path);
+  return rel === "" ? "." : rel;
+}
+async function appliedMigrations(client, projectId) {
+  try {
+    return await client.db.migrations(projectId);
+  } catch (error) {
+    if (isNaroError(error) && error.code === "DATABASE_NOT_READY") return [];
+    throw error;
+  }
+}
+function printable(text) {
+  let out = "";
+  for (const char of text) {
+    const code = char.charCodeAt(0);
+    const control = code < 32 || code >= 127 && code <= 159;
+    out += control ? "?" : char;
+  }
+  return out;
+}
+function warningLine(warning) {
+  if (warning === "out-of-order")
+    return "  \u26A0 older than an applied migration \u2014 db push will still apply it";
+  if (warning === "ledger-name-missing-extension")
+    return "  \u26A0 recorded without .sql in the ledger";
+  return null;
+}
+async function runMigrationNew(context, deps = processStdin2) {
+  const [name] = context.positionalOrThrow(
+    1,
+    "Usage: naro migration new <name>"
+  );
+  const dir = migrationsDir(context);
+  const fileName = nextMigrationFileName(
+    listMigrationFiles(dir),
+    name
+  );
+  mkdirSync(dir, { recursive: true });
+  const piped = !deps.stdinIsTty() ? await deps.readStdin() : "";
+  const fromStdin = piped.length > 0;
+  const body = fromStdin ? piped.endsWith("\n") ? piped : `${piped}
+` : `-- Migration: ${fileName}
+`;
+  const path = join(dir, fileName);
+  writeFileSync(path, body, { flag: "wx" });
+  const relPath = relativeToCwd(context, path);
+  context.output.result({ file: fileName, path: relPath, fromStdin }, [
+    `\u2705 Created ${relPath}`
+  ]);
+}
+async function runMigrationList(context) {
+  const client = await context.client();
+  const projectId = await context.resolveProjectId();
+  const dir = migrationsDir(context);
+  const local = listMigrationFiles(dir);
+  const ledger = await appliedMigrations(client, projectId);
+  const migrations = compareMigrations(local, ledger);
+  const relDir = relativeToCwd(context, dir);
+  const lines = migrations.length === 0 ? ["No migrations yet. Create one with `naro migration new <name>`."] : [
+    `Migrations in ${relDir} (${String(migrations.length)}):`,
+    ...migrations.flatMap((row) => {
+      const line = `  ${row.status.padEnd(12)}${printable(row.name)}${row.appliedAt ? `  ${printable(row.appliedAt)}` : ""}`;
+      const warning = warningLine(row.warning);
+      return warning ? [line, warning] : [line];
+    })
+  ];
+  context.output.result({ projectId, dir: relDir, migrations }, lines);
+}
+async function runMigrationUp(context) {
+  const client = await context.client();
+  const projectId = await context.resolveProjectId();
+  const dir = migrationsDir(context);
+  const local = listMigrationFiles(dir);
+  const ledger = await appliedMigrations(client, projectId);
+  const pending = compareMigrations(local, ledger).filter((row) => row.status === "pending").map((row) => row.name);
+  if (pending.length === 0) {
+    context.output.result({ projectId, applied: [], pending: [] }, [
+      "No pending migrations."
+    ]);
+    return;
+  }
+  if (context.flags.dryRun) {
+    context.output.result({ projectId, dryRun: true, pending }, [
+      `Pending migrations (${String(pending.length)}):`,
+      ...pending.map((name) => `  ${printable(name)}`)
+    ]);
+    return;
+  }
+  context.output.log(`Pending migrations (${String(pending.length)}):`);
+  for (const name of pending) context.output.log(`  ${printable(name)}`);
+  await confirmOrAbort(
+    context,
+    `Apply ${String(pending.length)} migration(s) to the project database? Each file is applied all-or-nothing; a failure stops the run.`
+  );
+  const applied = [];
+  for (const name of pending) {
+    const sql = readFileSync2(join(dir, name), "utf8");
+    try {
+      await client.db.applyMigration(projectId, { name, sql });
+    } catch (error) {
+      if (!isNaroError(error)) throw error;
+      const shown = context.output.json ? name : printable(name);
+      throw new NaroError(error.code, `${shown}: ${error.message}`, {
+        ...error.status === void 0 ? {} : { status: error.status },
+        details: { ...error.details, migration: name, applied },
+        cause: error
+      });
+    }
+    context.output.log(`\u2713 ${printable(name)}`);
+    applied.push(name);
+  }
+  context.output.result({ projectId, applied, pending: [] }, [
+    `\u2705 Applied ${String(applied.length)} migration(s).`
+  ]);
+}
+
+// src/commands/db-backup.ts
 var defaults = {
+  fetch: (input, init) => fetch(input, init),
+  stdout: process.stdout,
+  sleep: (ms) => new Promise((done) => setTimeout(done, ms)),
+  writeFile: (path, data) => {
+    mkdirSync2(dirname(path), { recursive: true });
+    writeFileSync2(path, data, { flag: "wx" });
+  }
+};
+var EXPORT_NOTICE = "Exporting the project database. Cloudflare holds other queries to this database until the export finishes.";
+function reasonOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function withoutUrl(text, url) {
+  return text.split(url).join("the signed URL").replace(/\S*X-Amz-Signature=\S*/gi, "the signed URL");
+}
+function downloadFailed(url, reason, original) {
+  const scrubbed = withoutUrl(reason, url);
+  let cause;
+  if (original !== void 0) {
+    cause = new Error(scrubbed);
+    if (original instanceof Error) {
+      cause.name = original.name;
+      if (original.stack !== void 0)
+        cause.stack = withoutUrl(original.stack, url);
+    }
+  }
+  return new NaroError(
+    "DATABASE_UNAVAILABLE",
+    `Could not download the dump (${scrubbed}). Run naro db dump again.`,
+    cause === void 0 ? {} : { cause }
+  );
+}
+function writeFailed(shown, error) {
+  return new NaroError(
+    "INTERNAL_ERROR",
+    `Could not write ${shown}: ${reasonOf(error)}.`,
+    { cause: error }
+  );
+}
+var DownloadStreamError = class extends Error {
+  constructor(original) {
+    super(reasonOf(original));
+    this.original = original;
+    this.name = "DownloadStreamError";
+  }
+};
+async function openDownload(deps, url) {
+  let response;
+  try {
+    response = await deps.fetch(url);
+  } catch (error) {
+    throw downloadFailed(url, reasonOf(error), error);
+  }
+  if (!response.ok || response.body === null) {
+    await response.body?.cancel().catch(() => {
+    });
+    throw downloadFailed(url, `HTTP ${String(response.status)}`);
+  }
+  return response.body;
+}
+async function* chunksOf(body) {
+  const reader = body.getReader();
+  const read = async () => {
+    try {
+      return await reader.read();
+    } catch (error) {
+      throw new DownloadStreamError(error);
+    }
+  };
+  try {
+    for (; ; ) {
+      const next = await read();
+      if (next.done) return;
+      yield next.value;
+    }
+  } finally {
+    await reader.cancel().catch(() => {
+    });
+  }
+}
+async function streamInto(body, destination, end) {
+  let bytes = 0;
+  const counter = new Transform({
+    transform(chunk, _encoding, done) {
+      bytes += chunk.length;
+      done(null, chunk);
+    }
+  });
+  await pipeline(chunksOf(body), counter, destination, { end });
+  return bytes;
+}
+function streamFailed(error, url, shown) {
+  return error instanceof DownloadStreamError ? downloadFailed(url, reasonOf(error.original), error.original) : writeFailed(shown, error);
+}
+function refuseDirectory(path, shown) {
+  let isDirectory = false;
+  try {
+    isDirectory = statSync(path, { throwIfNoEntry: false })?.isDirectory() ?? false;
+  } catch {
+  }
+  if (isDirectory)
+    throw new NaroError(
+      "VALIDATION_FAILED",
+      `--output ${shown} is a directory. Pass a file path.`
+    );
+}
+function makeOutputDirectory(path, shown) {
+  try {
+    mkdirSync2(dirname(path), { recursive: true });
+  } catch (error) {
+    throw writeFailed(shown, error);
+  }
+}
+async function downloadToFile(deps, url, path, shown) {
+  const body = await openDownload(deps, url);
+  const partial = join2(
+    dirname(path),
+    `.${basename(path)}.${String(process.pid)}.part`
+  );
+  try {
+    const bytes = await streamInto(body, createWriteStream(partial), true);
+    renameSync(partial, path);
+    return bytes;
+  } catch (error) {
+    try {
+      rmSync(partial, { force: true });
+    } catch {
+    }
+    throw streamFailed(error, url, shown);
+  }
+}
+async function downloadToStdout(deps, url) {
+  const body = await openDownload(deps, url);
+  try {
+    return await streamInto(body, deps.stdout, false);
+  } catch (error) {
+    throw streamFailed(error, url, "stdout");
+  }
+}
+async function runDbDump(context, overrides = {}) {
+  const deps = { ...defaults, ...overrides };
+  const { flags } = context;
+  if (flags.schemaOnly && flags.dataOnly)
+    throw new NaroError(
+      "VALIDATION_FAILED",
+      "Pass --schema-only or --data-only, not both."
+    );
+  if (flags.json && flags.output === void 0)
+    throw new NaroError(
+      "VALIDATION_FAILED",
+      "--json needs --output: the dump and the JSON result would share stdout."
+    );
+  const tables = listFlag(flags.table);
+  if (flags.table !== void 0 && tables.length === 0)
+    throw new NaroError(
+      "VALIDATION_FAILED",
+      "--table needs at least one table name."
+    );
+  const options = {
+    ...flags.schemaOnly ? { schemaOnly: true } : {},
+    ...flags.dataOnly ? { dataOnly: true } : {},
+    ...tables.length > 0 ? { tables } : {}
+  };
+  const output = flags.output === void 0 ? null : { path: resolve2(context.cwd, flags.output), shown: flags.output };
+  if (output) refuseDirectory(output.path, output.shown);
+  const client = await context.client();
+  const projectId = await context.resolveProjectId();
+  if (output) makeOutputDirectory(output.path, output.shown);
+  context.output.warn(EXPORT_NOTICE);
+  const step = await client.db.export(projectId, options, {
+    sleep: deps.sleep
+  });
+  const file = step.file;
+  if (file === null)
+    throw new NaroError(
+      "DATABASE_UNAVAILABLE",
+      "Could not download the dump (Cloudflare finished the export without a file). Run naro db dump again."
+    );
+  const bytes = output === null ? await downloadToStdout(deps, file.url) : await downloadToFile(deps, file.url, output.path, output.shown);
+  const bookmark = step.atBookmark;
+  if (!context.output.json) {
+    context.output.warn(
+      `\u2713 Wrote ${flags.output ?? "stdout"} (${humanSize(bytes)}) at bookmark ${bookmark}.`
+    );
+    context.output.warn(
+      `  naro db restore --bookmark ${bookmark} returns the database to this point.`
+    );
+  }
+  context.output.result({ output: flags.output, bytes, atBookmark: bookmark });
+}
+async function bookmarkNow(context, client, projectId) {
+  try {
+    const { bookmark } = await client.db.bookmark(projectId);
+    return isBookmark(bookmark) ? bookmark : null;
+  } catch (error) {
+    context.output.debugLog(
+      `Could not read the current bookmark before restoring: ${reasonOf(error)}`
+    );
+    return null;
+  }
+}
+function withWayBack(context, error, before) {
+  if (before === null || !isNaroError(error) || !RESTORE_OUTCOME_UNKNOWN_CODES.has(error.code))
+    return error;
+  if (!context.output.json)
+    context.output.warn(
+      `Before this attempt the database was at bookmark ${before}. If the restore ran anyway, naro db restore --bookmark ${before} undoes it.`
+    );
+  return new NaroError(error.code, error.message, {
+    ...error.status === void 0 ? {} : { status: error.status },
+    details: { ...error.details, previousBookmark: before },
+    cause: error
+  });
+}
+async function runDbRestore(context) {
+  const { bookmark, timestamp } = context.flags;
+  const given = bookmark !== void 0 && timestamp === void 0 ? { bookmark } : timestamp !== void 0 && bookmark === void 0 ? { timestamp } : null;
+  if (given === null)
+    throw new NaroError(
+      "VALIDATION_FAILED",
+      "Pass --timestamp <time> or --bookmark <id> (exactly one)."
+    );
+  if ("bookmark" in given && !isBookmark(given.bookmark))
+    throw new NaroError("VALIDATION_FAILED", BOOKMARK_FORMAT_MESSAGE);
+  const client = await context.client();
+  const projectId = await context.resolveProjectId();
+  let target;
+  let at = null;
+  if ("bookmark" in given) {
+    target = given.bookmark;
+  } else {
+    const resolved = await client.db.bookmark(projectId, {
+      timestamp: given.timestamp
+    });
+    target = resolved.bookmark;
+    at = resolved.timestamp ?? given.timestamp;
+  }
+  const label = at === null ? `bookmark ${target}` : `${at} (bookmark ${target})`;
+  if (context.flags.dryRun) {
+    context.output.result(
+      {
+        dryRun: true,
+        bookmark: target,
+        ...at === null ? {} : { timestamp: at }
+      },
+      [`Would restore to ${label}. Nothing was changed.`]
+    );
+    return;
+  }
+  await confirmOrAbort(
+    context,
+    `Restore the project database to ${label}? Everything written after that point is rolled back \u2014 migration history included \u2014 and queries running right now are cancelled.`
+  );
+  const before = await bookmarkNow(context, client, projectId);
+  let restored;
+  try {
+    restored = await client.db.restore(projectId, { bookmark: target });
+  } catch (error) {
+    throw withWayBack(context, error, before);
+  }
+  context.output.result(
+    {
+      bookmark: restored.bookmark,
+      previousBookmark: restored.previousBookmark
+    },
+    [
+      `\u2713 Restored the project database to bookmark ${restored.bookmark}.`,
+      `  To undo: naro db restore --bookmark ${restored.previousBookmark}`
+    ]
+  );
+}
+async function runDbPull(context, overrides = {}) {
+  const deps = { ...defaults, ...overrides };
+  const dir = migrationsDir(context);
+  const existing = listMigrationFiles(dir);
+  if (existing.length > 0)
+    throw new NaroError(
+      "VALIDATION_FAILED",
+      `${relativeToCwd(context, dir)} already has ${String(existing.length)} migration file(s). naro db pull only baselines a project without migrations; to see the current schema, run naro db dump --schema-only.`
+    );
+  const name = nextMigrationFileName(existing, "remote_schema");
+  const path = join2(dir, name);
+  const shown = relativeToCwd(context, path);
+  const client = await context.client();
+  const projectId = await context.resolveProjectId();
+  await confirmOrAbort(
+    context,
+    `Write ${shown} with the database's current schema and record it as already applied?`
+  );
+  const pulled = await client.db.pull(projectId, { name });
+  try {
+    deps.writeFile(path, `${pulled.sql}
+`);
+  } catch (error) {
+    if (!context.output.json) context.output.log(pulled.sql);
+    throw new NaroError(
+      "INTERNAL_ERROR",
+      `Recorded ${pulled.name} as applied but could not write ${shown}: ${reasonOf(error)}. The SQL is on stdout \u2014 save it as that file.`,
+      {
+        details: { migration: pulled.name, path: shown, sql: pulled.sql },
+        cause: error
+      }
+    );
+  }
+  context.output.result(
+    {
+      projectId,
+      name: pulled.name,
+      path: shown,
+      statements: pulled.statements
+    },
+    [
+      `\u2713 Wrote ${shown} (${String(pulled.statements)} ${pulled.statements === 1 ? "statement" : "statements"}) and recorded it as applied.`
+    ]
+  );
+}
+
+// src/commands/git.ts
+var defaults2 = {
   detectRemote: async (dir) => (await detectGitInfo(dir)).repositoryUrl,
   openBrowser,
-  sleep: (ms) => new Promise((resolve3) => setTimeout(resolve3, ms))
+  sleep: (ms) => new Promise((resolve4) => setTimeout(resolve4, ms))
 };
 function connected(context, project) {
   const branch = project.defaultBranch;
@@ -589,7 +1064,7 @@ function connected(context, project) {
   );
 }
 async function runGitConnect(context, overrides = {}) {
-  const deps = { ...defaults, ...overrides };
+  const deps = { ...defaults2, ...overrides };
   const { output } = context;
   const explicit = context.positionals[0];
   let fullName;
@@ -676,7 +1151,7 @@ async function runGitDisconnect(context) {
   ]);
 }
 async function offerAutoDeploy(context, projectId, overrides) {
-  const deps = { ...defaults, ...overrides };
+  const deps = { ...defaults2, ...overrides };
   if (overrides.canPrompt === false) return;
   try {
     if (readProjectLink(context.cwd)?.autoDeployDeclined === true) return;
@@ -1057,8 +1532,8 @@ async function runInspect(context) {
 }
 
 // src/commands/domains.ts
-var defaults2 = {
-  sleep: (ms) => new Promise((resolve3) => setTimeout(resolve3, ms)),
+var defaults3 = {
+  sleep: (ms) => new Promise((resolve4) => setTimeout(resolve4, ms)),
   now: () => Date.now()
 };
 var FIRST_DELAY_MS = 5e3;
@@ -1206,7 +1681,7 @@ async function verifyAll(client, projectId, hostname, auto = false) {
   return verified;
 }
 async function runDomainsVerify(context, overrides = {}) {
-  const deps = { ...defaults2, ...overrides };
+  const deps = { ...defaults3, ...overrides };
   const client = await context.client();
   const projectId = await context.resolveProjectId();
   const hostname = context.positionals[0];
@@ -1301,8 +1776,8 @@ async function runDomainsRemove(context) {
 }
 
 // src/commands/env.ts
-import { existsSync, writeFileSync } from "fs";
-import { join } from "path";
+import { existsSync, writeFileSync as writeFileSync3 } from "fs";
+import { join as join3 } from "path";
 var TARGETS = /* @__PURE__ */ new Set(["production", "preview", "all"]);
 var KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 function parseTarget(value) {
@@ -1405,12 +1880,12 @@ async function runEnvPull(context) {
   const vars = Object.fromEntries(
     selected.map((row) => [row.key, row.value ?? ""])
   );
-  const path = join(context.cwd, file);
+  const path = join3(context.cwd, file);
   if (existsSync(path) && isInteractive() && !context.flags.yes && !context.flags.json) {
     const confirmed = await context.prompter.confirm(`Overwrite ${file}?`);
     if (!confirmed) throw new NaroError("CANCELED", "Canceled.");
   }
-  writeFileSync(
+  writeFileSync3(
     path,
     `# Pulled from Naro (${surface}) \u2014 do not commit secrets.
 ${serializeDotenv(vars)}`,
@@ -1423,141 +1898,8 @@ ${serializeDotenv(vars)}`,
 }
 
 // src/commands/gen.ts
-import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync3 } from "fs";
-import { dirname, resolve as resolve2 } from "path";
-
-// src/commands/migration.ts
-import { mkdirSync, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
-import { join as join2, relative } from "path";
-var processStdin2 = {
-  stdinIsTty: () => process.stdin.isTTY === true,
-  readStdin
-};
-function migrationsDir(context) {
-  return resolveMigrationsDir({
-    baseDir: context.cwd,
-    rootDirectory: context.flags.root,
-    dir: context.flags.dir
-  });
-}
-function relativeToCwd(context, path) {
-  const rel = relative(context.cwd, path);
-  return rel === "" ? "." : rel;
-}
-async function appliedMigrations(client, projectId) {
-  try {
-    return await client.db.migrations(projectId);
-  } catch (error) {
-    if (isNaroError(error) && error.code === "DATABASE_NOT_READY") return [];
-    throw error;
-  }
-}
-function printable(text) {
-  let out = "";
-  for (const char of text) {
-    const code = char.charCodeAt(0);
-    const control = code < 32 || code >= 127 && code <= 159;
-    out += control ? "?" : char;
-  }
-  return out;
-}
-function warningLine(warning) {
-  if (warning === "out-of-order")
-    return "  \u26A0 older than an applied migration \u2014 db push will still apply it";
-  if (warning === "ledger-name-missing-extension")
-    return "  \u26A0 recorded without .sql in the ledger";
-  return null;
-}
-async function runMigrationNew(context, deps = processStdin2) {
-  const [name] = context.positionalOrThrow(
-    1,
-    "Usage: naro migration new <name>"
-  );
-  const dir = migrationsDir(context);
-  const fileName = nextMigrationFileName(
-    listMigrationFiles(dir),
-    name
-  );
-  mkdirSync(dir, { recursive: true });
-  const piped = !deps.stdinIsTty() ? await deps.readStdin() : "";
-  const fromStdin = piped.length > 0;
-  const body = fromStdin ? piped.endsWith("\n") ? piped : `${piped}
-` : `-- Migration: ${fileName}
-`;
-  const path = join2(dir, fileName);
-  writeFileSync2(path, body, { flag: "wx" });
-  const relPath = relativeToCwd(context, path);
-  context.output.result({ file: fileName, path: relPath, fromStdin }, [
-    `\u2705 Created ${relPath}`
-  ]);
-}
-async function runMigrationList(context) {
-  const client = await context.client();
-  const projectId = await context.resolveProjectId();
-  const dir = migrationsDir(context);
-  const local = listMigrationFiles(dir);
-  const ledger = await appliedMigrations(client, projectId);
-  const migrations = compareMigrations(local, ledger);
-  const relDir = relativeToCwd(context, dir);
-  const lines = migrations.length === 0 ? ["No migrations yet. Create one with `naro migration new <name>`."] : [
-    `Migrations in ${relDir} (${String(migrations.length)}):`,
-    ...migrations.flatMap((row) => {
-      const line = `  ${row.status.padEnd(12)}${printable(row.name)}${row.appliedAt ? `  ${printable(row.appliedAt)}` : ""}`;
-      const warning = warningLine(row.warning);
-      return warning ? [line, warning] : [line];
-    })
-  ];
-  context.output.result({ projectId, dir: relDir, migrations }, lines);
-}
-async function runMigrationUp(context) {
-  const client = await context.client();
-  const projectId = await context.resolveProjectId();
-  const dir = migrationsDir(context);
-  const local = listMigrationFiles(dir);
-  const ledger = await appliedMigrations(client, projectId);
-  const pending = compareMigrations(local, ledger).filter((row) => row.status === "pending").map((row) => row.name);
-  if (pending.length === 0) {
-    context.output.result({ projectId, applied: [], pending: [] }, [
-      "No pending migrations."
-    ]);
-    return;
-  }
-  if (context.flags.dryRun) {
-    context.output.result({ projectId, dryRun: true, pending }, [
-      `Pending migrations (${String(pending.length)}):`,
-      ...pending.map((name) => `  ${printable(name)}`)
-    ]);
-    return;
-  }
-  context.output.log(`Pending migrations (${String(pending.length)}):`);
-  for (const name of pending) context.output.log(`  ${printable(name)}`);
-  await confirmOrAbort(
-    context,
-    `Apply ${String(pending.length)} migration(s) to the project database? Each file is applied all-or-nothing; a failure stops the run.`
-  );
-  const applied = [];
-  for (const name of pending) {
-    const sql = readFileSync2(join2(dir, name), "utf8");
-    try {
-      await client.db.applyMigration(projectId, { name, sql });
-    } catch (error) {
-      if (!isNaroError(error)) throw error;
-      const shown = context.output.json ? name : printable(name);
-      throw new NaroError(error.code, `${shown}: ${error.message}`, {
-        ...error.status === void 0 ? {} : { status: error.status },
-        details: { ...error.details, migration: name, applied },
-        cause: error
-      });
-    }
-    context.output.log(`\u2713 ${printable(name)}`);
-    applied.push(name);
-  }
-  context.output.result({ projectId, applied, pending: [] }, [
-    `\u2705 Applied ${String(applied.length)} migration(s).`
-  ]);
-}
-
-// src/commands/gen.ts
+import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync4 } from "fs";
+import { dirname as dirname2, resolve as resolve3 } from "path";
 async function runGenTypes(context) {
   const client = await context.client();
   const projectId = await context.resolveProjectId();
@@ -1572,9 +1914,9 @@ async function runGenTypes(context) {
     );
   const extra = undescribed.length > 0 ? { undescribed } : {};
   if (context.flags.output) {
-    const path = resolve2(context.cwd, context.flags.output);
-    mkdirSync2(dirname(path), { recursive: true });
-    writeFileSync3(path, types);
+    const path = resolve3(context.cwd, context.flags.output);
+    mkdirSync3(dirname2(path), { recursive: true });
+    writeFileSync4(path, types);
     context.output.result(
       {
         projectId,
@@ -1596,7 +1938,7 @@ async function runGenTypes(context) {
 // src/commands/logs.ts
 var FOLLOW_INTERVAL_MS = 3e3;
 function sleep(ms) {
-  return new Promise((resolve3) => setTimeout(resolve3, ms));
+  return new Promise((resolve4) => setTimeout(resolve4, ms));
 }
 function formatBuildLog(log) {
   return `[${log.stage}] ${log.level === "ERROR" ? "\u2717 " : ""}${log.message}`;
@@ -1884,6 +2226,12 @@ Usage:
   naro db info                       Database status, size, table count and limits
   naro db query <sql> | --file <f>   Run SQL against it (reads stdin when piped)
   naro db push [--dry-run]           Apply pending migrations from ./migrations (asks first; --yes to skip)
+  naro db dump [--output <f>]        Download a SQL dump of the database (stdout by default)
+       [--schema-only|--data-only] [--table a,b]  Cloudflare holds other queries until it finishes
+  naro db restore --bookmark <id>    Roll the database back (Time Travel, last 30 days; asks first)
+       | --timestamp <time> [--dry-run]  prints the command that undoes it
+  naro db pull [--dir <d>]           Write the remote schema as migrations/0001_remote_schema.sql
+                                     and record it as applied - a baseline (asks first)
   naro migration new <name>          Create migrations/NNNN_<name>.sql (stdin becomes the body when piped)
   naro migration list                Local vs applied migrations
   naro migration up [--dry-run]      Same as db push
@@ -1905,9 +2253,14 @@ Global options:
   --wait          Poll until the domain goes live (naro domains verify)
   --no-www        Register the apex alone (naro domains add)
   --file <path>   SQL file to run (naro db query)
-  --dry-run       List pending migrations without applying (naro db push)
-  --output <file> Write to a file instead of stdout (naro gen types)
+  --dry-run       Show what would change without changing it (naro db push, db restore)
+  --output <file> Write to a file instead of stdout (naro gen types, db dump)
   --dir <path>    Migrations directory (default ./migrations, or <--root>/migrations)
+  --schema-only   Dump the schema without rows (naro db dump)
+  --data-only     Dump rows without the schema (naro db dump)
+  --table <a,b>   Dump only these tables, comma-separated (naro db dump)
+  --bookmark <id> Restore point: a bookmark from db dump or db restore (naro db restore)
+  --timestamp <time>  Restore point: RFC 3339 with a timezone, or Unix seconds (naro db restore)
   --debug         Verbose diagnostics
 
 Credentials: \`naro login\` opens a browser (GitHub). CI: NARO_TOKEN=$(naro token).
@@ -2000,6 +2353,12 @@ function route(parsed) {
           return { handler: runDbQuery, positionals: positionals.slice(1) };
         case "push":
           return { handler: runMigrationUp, positionals: positionals.slice(1) };
+        case "dump":
+          return { handler: runDbDump, positionals: positionals.slice(1) };
+        case "restore":
+          return { handler: runDbRestore, positionals: positionals.slice(1) };
+        case "pull":
+          return { handler: runDbPull, positionals: positionals.slice(1) };
         default:
           return null;
       }
@@ -2045,7 +2404,7 @@ function version() {
   try {
     const pkg = JSON.parse(
       readFileSync3(
-        join3(dirname2(fileURLToPath(import.meta.url)), "..", "package.json"),
+        join4(dirname3(fileURLToPath(import.meta.url)), "..", "package.json"),
         "utf8"
       )
     );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "naro-cli",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "bin": {
     "naro": "./dist/index.js"
@@ -33,9 +33,9 @@
     "typescript": "7.0.2",
     "vitest": "3.2.7",
     "@next-deploy/build": "0.1.0",
-    "@next-deploy/core": "0.1.0",
+    "@next-deploy/config": "0.1.0",
     "@next-deploy/sdk": "0.1.0",
-    "@next-deploy/config": "0.1.0"
+    "@next-deploy/core": "0.1.0"
   },
   "scripts": {
     "build": "tsup && pnpm build:types",