@happyvertical/sql 0.80.0 → 0.80.1

package/dist/backup/index.js

@@ -1,212 +1,234 @@
+import { a as dropPostgresDatabase, l as redactDatabaseUrl, n as assertCanImportDatabase, o as dumpPostgresDatabase, r as createPostgresDatabase, t as assertCanExportDatabase, u as restorePostgresDatabase } from "../chunks/postgres-cli-DzZcXSIG.js";
 import { execFile } from "node:child_process";
-import { readFile, writeFile, rename, mkdir, rm, access } from "node:fs/promises";
-import { homedir } from "node:os";
+import { access, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
-import { a as assertCanExportDatabase, f as dumpPostgresDatabase, r as redactDatabaseUrl, b as assertCanImportDatabase, e as dropPostgresDatabase, c as createPostgresDatabase, g as restorePostgresDatabase } from "../chunks/postgres-cli-Cr6bBZ3q.js";
-const BACKUP_KIND = "happyvertical-backup";
-const BACKUP_VERSION = 1;
-const DEFAULT_DUMP_FILE = "database.dump";
-const DEFAULT_FILES_DIR = "files";
-const DEFAULT_MANIFEST_FILE = "manifest.json";
+import { homedir } from "node:os";
+//#region src/backup/manifest.ts
+/**
+* Backup manifest shape and helpers.
+*
+* The manifest is the source-of-truth for what's in a backup directory:
+* which database it came from, when, at what commit, and any
+* app-specific metadata that the caller chose to attach via the `extra`
+* field. Bumping `BACKUP_VERSION` is the way to evolve the shape — older
+* backups will fail `readBackupManifest` until upgraded.
+*/
+var BACKUP_KIND = "happyvertical-backup";
+var BACKUP_VERSION = 1;
+var DEFAULT_DUMP_FILE = "database.dump";
+var DEFAULT_FILES_DIR = "files";
+var DEFAULT_MANIFEST_FILE = "manifest.json";
+/**
+* Read a backup manifest from `backupPath/manifest.json` and validate
+* that it matches this package's kind+version. Throws (with the path
+* included) on mismatch — that's almost always a real problem worth
+* surfacing, not silently tolerating.
+*/
 async function readBackupManifest(backupPath) {
-  const manifestPath = join(resolve(backupPath), DEFAULT_MANIFEST_FILE);
-  const manifest = JSON.parse(
-    await readFile(manifestPath, "utf8")
-  );
-  if (manifest.kind !== BACKUP_KIND || manifest.version !== BACKUP_VERSION) {
-    throw new Error(
-      `Unsupported backup manifest at ${manifestPath} (kind=${manifest.kind}, version=${manifest.version}).`
-    );
-  }
-  return manifest;
+	const manifestPath = join(resolve(backupPath), DEFAULT_MANIFEST_FILE);
+	const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+	if (manifest.kind !== "happyvertical-backup" || manifest.version !== 1) throw new Error(`Unsupported backup manifest at ${manifestPath} (kind=${manifest.kind}, version=${manifest.version}).`);
+	return manifest;
 }
 async function writeBackupManifest(backupPath, manifest) {
-  const targetPath = join(backupPath, DEFAULT_MANIFEST_FILE);
-  const tempPath = join(
-    backupPath,
-    `.manifest.${process.pid}.${Date.now().toString(36)}.tmp`
-  );
-  await writeFile(tempPath, `${JSON.stringify(manifest, null, 2)}
-`, {
-    mode: 384
-  });
-  await rename(tempPath, targetPath);
+	const targetPath = join(backupPath, DEFAULT_MANIFEST_FILE);
+	const tempPath = join(backupPath, `.manifest.${process.pid}.${Date.now().toString(36)}.tmp`);
+	await writeFile(tempPath, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 384 });
+	await rename(tempPath, targetPath);
 }
+/**
+* Filesystem-safe timestamp suitable for backup directory names — same
+* shape as `Date.toISOString()` but with `:` and `.` swapped to `-` so
+* the value is a valid path segment on Windows and friendly to shell
+* tab-completion everywhere else.
+*/
 function timestampForBackup(date = /* @__PURE__ */ new Date()) {
-  return date.toISOString().replace(/[:.]/g, "-");
+	return date.toISOString().replace(/[:.]/g, "-");
 }
+//#endregion
+//#region src/backup/index.ts
+/**
+* Backup orchestration — composes the pg shell-out helpers in
+* `../postgres-cli` with caller-supplied hooks for file storage,
+* app-specific manifest extras, and post-restore steps.
+*
+* Decoupled from `@happyvertical/files` on purpose: callers that want a
+* file-storage backup pass an `onBackup` callback that does the copy
+* however they prefer (local cp, S3 sync, WebDAV walk). That keeps this
+* subpath usable by apps that only need the database half.
+*/
+/** Default root for backups. Override via $HAPPYVERTICAL_BACKUP_DIR or `backupRoot`. */
 function defaultBackupRoot() {
-  return process.env.HAPPYVERTICAL_BACKUP_DIR ?? join(homedir(), ".local", "share", "happyvertical", "backups");
+	return process.env.HAPPYVERTICAL_BACKUP_DIR ?? join(homedir(), ".local", "share", "happyvertical", "backups");
 }
+/**
+* Take a postgres dump and (optionally) a snapshot of file storage,
+* writing both plus a manifest into a fresh timestamped directory.
+*
+* Returns the directory path and the manifest. The manifest's `extra`
+* field carries whatever `onBackup` returned.
+*
+* **Failure model:** the function is all-or-nothing. If any step after
+* the initial directory creation throws — `dumpPostgresDatabase`,
+* `onBackup`, `onDatabaseMetadata`, `getGitSha`, or the final manifest
+* write — the partial backup directory is removed (best-effort)
+* before the original error is re-thrown. Callers therefore never see
+* a backup directory on disk without a complete manifest, which would
+* otherwise poison later `restoreBackup` calls with confusing
+* "no manifest" errors and leak a partial dump containing sensitive
+* data. If cleanup itself fails, that error is logged via
+* `console.warn` and swallowed so it doesn't mask the original.
+*/
 async function exportBackup(options) {
-  assertCanExportDatabase(options.databaseUrl, options);
-  const label = validateLabel(options.label ?? "backup");
-  const backupPath = await createUniqueBackupDir(
-    options.backupRoot ?? defaultBackupRoot(),
-    label
-  );
-  try {
-    const dumpPath = join(backupPath, DEFAULT_DUMP_FILE);
-    await dumpPostgresDatabase(options.databaseUrl, dumpPath);
-    const filesDir = join(backupPath, DEFAULT_FILES_DIR);
-    let filesInfo = {
-      directory: DEFAULT_FILES_DIR,
-      exported: false,
-      count: 0,
-      bytes: 0,
-      reason: "Skipped by skipFiles.",
-      storageConfig: options.filesStorageConfig
-    };
-    let extra;
-    if (!options.skipFiles && options.onBackup) {
-      await mkdir(filesDir, { recursive: true, mode: 448 });
-      const result = await options.onBackup({
-        backupPath,
-        databaseUrl: options.databaseUrl,
-        filesDir
-      });
-      if (result !== void 0 && result !== null) extra = result;
-      filesInfo = {
-        directory: DEFAULT_FILES_DIR,
-        exported: true,
-        count: 0,
-        bytes: 0,
-        storageConfig: options.filesStorageConfig
-      };
-    }
-    const metadata = options.onDatabaseMetadata ? await options.onDatabaseMetadata({ databaseUrl: options.databaseUrl }) : void 0;
-    const manifest = {
-      kind: BACKUP_KIND,
-      version: BACKUP_VERSION,
-      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      gitSha: await getGitSha(options.gitCwd),
-      source: label,
-      database: {
-        dumpFile: DEFAULT_DUMP_FILE,
-        url: redactDatabaseUrl(options.databaseUrl),
-        metadata
-      },
-      files: filesInfo,
-      extra
-    };
-    await writeBackupManifest(backupPath, manifest);
-    return { backupPath, manifest };
-  } catch (error) {
-    try {
-      await rm(backupPath, { recursive: true, force: true });
-    } catch (cleanupError) {
-      console.warn(
-        `exportBackup: failed to clean up partial backup at ${backupPath}:`,
-        cleanupError instanceof Error ? cleanupError.message : String(cleanupError)
-      );
-    }
-    throw error;
-  }
+	assertCanExportDatabase(options.databaseUrl, options);
+	const label = validateLabel(options.label ?? "backup");
+	const backupPath = await createUniqueBackupDir(options.backupRoot ?? defaultBackupRoot(), label);
+	try {
+		const dumpPath = join(backupPath, DEFAULT_DUMP_FILE);
+		await dumpPostgresDatabase(options.databaseUrl, dumpPath);
+		const filesDir = join(backupPath, DEFAULT_FILES_DIR);
+		let filesInfo = {
+			directory: DEFAULT_FILES_DIR,
+			exported: false,
+			count: 0,
+			bytes: 0,
+			reason: "Skipped by skipFiles.",
+			storageConfig: options.filesStorageConfig
+		};
+		let extra;
+		if (!options.skipFiles && options.onBackup) {
+			await mkdir(filesDir, {
+				recursive: true,
+				mode: 448
+			});
+			const result = await options.onBackup({
+				backupPath,
+				databaseUrl: options.databaseUrl,
+				filesDir
+			});
+			if (result !== void 0 && result !== null) extra = result;
+			filesInfo = {
+				directory: DEFAULT_FILES_DIR,
+				exported: true,
+				count: 0,
+				bytes: 0,
+				storageConfig: options.filesStorageConfig
+			};
+		}
+		const metadata = options.onDatabaseMetadata ? await options.onDatabaseMetadata({ databaseUrl: options.databaseUrl }) : void 0;
+		const manifest = {
+			kind: BACKUP_KIND,
+			version: 1,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			gitSha: await getGitSha(options.gitCwd),
+			source: label,
+			database: {
+				dumpFile: DEFAULT_DUMP_FILE,
+				url: redactDatabaseUrl(options.databaseUrl),
+				metadata
+			},
+			files: filesInfo,
+			extra
+		};
+		await writeBackupManifest(backupPath, manifest);
+		return {
+			backupPath,
+			manifest
+		};
+	} catch (error) {
+		try {
+			await rm(backupPath, {
+				recursive: true,
+				force: true
+			});
+		} catch (cleanupError) {
+			console.warn(`exportBackup: failed to clean up partial backup at ${backupPath}:`, cleanupError instanceof Error ? cleanupError.message : String(cleanupError));
+		}
+		throw error;
+	}
 }
+/**
+* Restore a backup directory into `databaseUrl` and, if `onRestore` is
+* provided, run the file-storage half. The caller controls everything
+* after the dump completes (file copy, migrations, doctor) via the hook.
+*/
 async function restoreBackup(options) {
-  const backupPath = resolve(options.backupPath);
-  const manifest = await readBackupManifest(backupPath);
-  assertCanImportDatabase(options.databaseUrl, options);
-  const dumpPath = join(
-    backupPath,
-    validateManifestPathSegment(
-      manifest.database.dumpFile,
-      "database dump file"
-    )
-  );
-  const filesDir = join(
-    backupPath,
-    validateManifestPathSegment(manifest.files.directory, "files directory")
-  );
-  await restorePostgresDatabase(options.databaseUrl, dumpPath);
-  if (!options.skipFiles && options.onRestore && manifest.files.exported) {
-    await options.onRestore({
-      backupPath,
-      databaseUrl: options.databaseUrl,
-      filesDir,
-      manifest
-    });
-  }
-  return manifest;
+	const backupPath = resolve(options.backupPath);
+	const manifest = await readBackupManifest(backupPath);
+	assertCanImportDatabase(options.databaseUrl, options);
+	const dumpPath = join(backupPath, validateManifestPathSegment(manifest.database.dumpFile, "database dump file"));
+	const filesDir = join(backupPath, validateManifestPathSegment(manifest.files.directory, "files directory"));
+	await restorePostgresDatabase(options.databaseUrl, dumpPath);
+	if (!options.skipFiles && options.onRestore && manifest.files.exported) await options.onRestore({
+		backupPath,
+		databaseUrl: options.databaseUrl,
+		filesDir,
+		manifest
+	});
+	return manifest;
 }
+/**
+* Drop-and-recreate the target database, then run `restoreBackup`.
+* Local-only: explicitly refuses non-local URLs without an escape hatch
+* (this is a destructive operation by design).
+*/
 async function resetLocalDatabaseFromBackup(options) {
-  assertCanImportDatabase(options.databaseUrl, { allowProduction: false });
-  const backupPath = resolve(options.backupPath);
-  const manifest = await readBackupManifest(backupPath);
-  const dumpFile = validateManifestPathSegment(
-    manifest.database.dumpFile,
-    "database dump file"
-  );
-  validateManifestPathSegment(manifest.files.directory, "files directory");
-  await access(join(backupPath, dumpFile));
-  await dropPostgresDatabase(options.databaseUrl);
-  await createPostgresDatabase(options.databaseUrl);
-  return restoreBackup({ ...options, allowProduction: false });
+	assertCanImportDatabase(options.databaseUrl, { allowProduction: false });
+	const backupPath = resolve(options.backupPath);
+	const manifest = await readBackupManifest(backupPath);
+	const dumpFile = validateManifestPathSegment(manifest.database.dumpFile, "database dump file");
+	validateManifestPathSegment(manifest.files.directory, "files directory");
+	await access(join(backupPath, dumpFile));
+	await dropPostgresDatabase(options.databaseUrl);
+	await createPostgresDatabase(options.databaseUrl);
+	return restoreBackup({
+		...options,
+		allowProduction: false
+	});
 }
 async function getGitSha(cwd = process.cwd()) {
-  try {
-    return await new Promise((resolvePromise, reject) => {
-      execFile("git", ["rev-parse", "HEAD"], { cwd }, (error, stdout) => {
-        if (error) {
-          reject(error);
-          return;
-        }
-        resolvePromise(stdout.trim());
-      });
-    });
-  } catch {
-    return null;
-  }
+	try {
+		return await new Promise((resolvePromise, reject) => {
+			execFile("git", ["rev-parse", "HEAD"], { cwd }, (error, stdout) => {
+				if (error) {
+					reject(error);
+					return;
+				}
+				resolvePromise(stdout.trim());
+			});
+		});
+	} catch {
+		return null;
+	}
 }
 function validateLabel(label) {
-  if (!label || label === "." || label === ".." || /[\\/]/u.test(label)) {
-    throw new Error(
-      `Backup label "${label}" is invalid. Labels must be a single path-safe segment.`
-    );
-  }
-  return label;
+	if (!label || label === "." || label === ".." || /[\\/]/u.test(label)) throw new Error(`Backup label "${label}" is invalid. Labels must be a single path-safe segment.`);
+	return label;
 }
 function validateManifestPathSegment(value, field) {
-  if (!value || value === "." || value === ".." || /[\\/]/u.test(value)) {
-    throw new Error(
-      `Backup manifest ${field} is invalid: "${value}". It must be a single path segment.`
-    );
-  }
-  return value;
+	if (!value || value === "." || value === ".." || /[\\/]/u.test(value)) throw new Error(`Backup manifest ${field} is invalid: "${value}". It must be a single path segment.`);
+	return value;
 }
 async function createUniqueBackupDir(backupRoot, label) {
-  const root = resolve(backupRoot);
-  await mkdir(root, { recursive: true, mode: 448 });
-  const baseName = `${label}-${timestampForBackup()}`;
-  for (let attempt = 0; attempt < 64; attempt += 1) {
-    const suffix = attempt === 0 ? "" : `-${attempt.toString(36)}`;
-    const candidate = join(root, `${baseName}${suffix}`);
-    try {
-      await mkdir(candidate, { mode: 448 });
-      return candidate;
-    } catch (error) {
-      if (error.code === "EEXIST") {
-        continue;
-      }
-      throw error;
-    }
-  }
-  throw new Error(
-    `Failed to create a unique backup directory under ${root} for label "${label}".`
-  );
+	const root = resolve(backupRoot);
+	await mkdir(root, {
+		recursive: true,
+		mode: 448
+	});
+	const baseName = `${label}-${timestampForBackup()}`;
+	for (let attempt = 0; attempt < 64; attempt += 1) {
+		const candidate = join(root, `${baseName}${attempt === 0 ? "" : `-${attempt.toString(36)}`}`);
+		try {
+			await mkdir(candidate, { mode: 448 });
+			return candidate;
+		} catch (error) {
+			if (error.code === "EEXIST") continue;
+			throw error;
+		}
+	}
+	throw new Error(`Failed to create a unique backup directory under ${root} for label "${label}".`);
 }
-export {
-  BACKUP_KIND,
-  BACKUP_VERSION,
-  DEFAULT_DUMP_FILE,
-  DEFAULT_FILES_DIR,
-  DEFAULT_MANIFEST_FILE,
-  defaultBackupRoot,
-  exportBackup,
-  readBackupManifest,
-  resetLocalDatabaseFromBackup,
-  restoreBackup,
-  timestampForBackup,
-  writeBackupManifest
-};
-//# sourceMappingURL=index.js.map
+//#endregion
+export { BACKUP_KIND, BACKUP_VERSION, DEFAULT_DUMP_FILE, DEFAULT_FILES_DIR, DEFAULT_MANIFEST_FILE, defaultBackupRoot, exportBackup, readBackupManifest, resetLocalDatabaseFromBackup, restoreBackup, timestampForBackup, writeBackupManifest };
+
+//# sourceMappingURL=index.js.map

package/dist/backup/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../src/backup/manifest.ts","../../src/backup/index.ts"],"sourcesContent":["/**\n * Backup manifest shape and helpers.\n *\n * The manifest is the source-of-truth for what's in a backup directory:\n * which database it came from, when, at what commit, and any\n * app-specific metadata that the caller chose to attach via the `extra`\n * field. Bumping `BACKUP_VERSION` is the way to evolve the shape — older\n * backups will fail `readBackupManifest` until upgraded.\n */\nimport { readFile, rename, writeFile } from 'node:fs/promises';\nimport { join, resolve } from 'node:path';\n\nexport const BACKUP_KIND = 'happyvertical-backup' as const;\nexport const BACKUP_VERSION = 1 as const;\nexport const DEFAULT_DUMP_FILE = 'database.dump';\nexport const DEFAULT_FILES_DIR = 'files';\nexport const DEFAULT_MANIFEST_FILE = 'manifest.json';\n\nexport interface BackupManifestDatabase {\n  /** File name of the pg_dump archive within the backup directory. */\n  dumpFile: string;\n  /** Redacted URL the dump was taken from. */\n  url: string;\n  /** Caller-supplied diagnostic metadata (row counts, schema count, etc.). */\n  metadata?: Record<string, unknown>;\n}\n\nexport interface BackupManifestFiles {\n  /** Directory name within the backup that holds copied file storage. */\n  directory: string;\n  exported: boolean;\n  count: number;\n  bytes: number;\n  reason?: string;\n  /** Redacted provider config, if the caller chose to record it. */\n  storageConfig?: unknown;\n}\n\nexport interface BackupManifest {\n  kind: typeof BACKUP_KIND;\n  version: typeof BACKUP_VERSION;\n  timestamp: string;\n  gitSha: string | null;\n  /** Free-form label (e.g. 'current', 'prod', 'pre-migration'). */\n  source: string;\n  database: BackupManifestDatabase;\n  files: BackupManifestFiles;\n  /** Opaque slot for app-specific extension (resume publish status, etc.). */\n  extra?: unknown;\n}\n\n/**\n * Read a backup manifest from `backupPath/manifest.json` and validate\n * that it matches this package's kind+version. Throws (with the path\n * included) on mismatch — that's almost always a real problem worth\n * surfacing, not silently tolerating.\n */\nexport async function readBackupManifest(\n  backupPath: string,\n): Promise<BackupManifest> {\n  const manifestPath = join(resolve(backupPath), DEFAULT_MANIFEST_FILE);\n  const manifest = JSON.parse(\n    await readFile(manifestPath, 'utf8'),\n  ) as BackupManifest;\n  if (manifest.kind !== BACKUP_KIND || manifest.version !== BACKUP_VERSION) {\n    throw new Error(\n      `Unsupported backup manifest at ${manifestPath} (kind=${manifest.kind}, version=${manifest.version}).`,\n    );\n  }\n  return manifest;\n}\n\nexport async function writeBackupManifest(\n  backupPath: string,\n  manifest: BackupManifest,\n): Promise<void> {\n  const targetPath = join(backupPath, DEFAULT_MANIFEST_FILE);\n  const tempPath = join(\n    backupPath,\n    `.manifest.${process.pid}.${Date.now().toString(36)}.tmp`,\n  );\n  await writeFile(tempPath, `${JSON.stringify(manifest, null, 2)}\\n`, {\n    mode: 0o600,\n  });\n  await rename(tempPath, targetPath);\n}\n\n/**\n * Filesystem-safe timestamp suitable for backup directory names — same\n * shape as `Date.toISOString()` but with `:` and `.` swapped to `-` so\n * the value is a valid path segment on Windows and friendly to shell\n * tab-completion everywhere else.\n */\nexport function timestampForBackup(date = new Date()): string {\n  return date.toISOString().replace(/[:.]/g, '-');\n}\n","/**\n * Backup orchestration — composes the pg shell-out helpers in\n * `../postgres-cli` with caller-supplied hooks for file storage,\n * app-specific manifest extras, and post-restore steps.\n *\n * Decoupled from `@happyvertical/files` on purpose: callers that want a\n * file-storage backup pass an `onBackup` callback that does the copy\n * however they prefer (local cp, S3 sync, WebDAV walk). That keeps this\n * subpath usable by apps that only need the database half.\n */\nimport { execFile } from 'node:child_process';\nimport { access, mkdir, rm } from 'node:fs/promises';\nimport { homedir } from 'node:os';\nimport { join, resolve } from 'node:path';\nimport {\n  assertCanExportDatabase,\n  assertCanImportDatabase,\n  createPostgresDatabase,\n  dropPostgresDatabase,\n  dumpPostgresDatabase,\n  redactDatabaseUrl,\n  restorePostgresDatabase,\n} from '../postgres-cli';\nimport {\n  BACKUP_KIND,\n  BACKUP_VERSION,\n  type BackupManifest,\n  type BackupManifestFiles,\n  DEFAULT_DUMP_FILE,\n  DEFAULT_FILES_DIR,\n  readBackupManifest,\n  timestampForBackup,\n  writeBackupManifest,\n} from './manifest';\n\nexport {\n  BACKUP_KIND,\n  BACKUP_VERSION,\n  type BackupManifest,\n  type BackupManifestDatabase,\n  type BackupManifestFiles,\n  DEFAULT_DUMP_FILE,\n  DEFAULT_FILES_DIR,\n  DEFAULT_MANIFEST_FILE,\n  readBackupManifest,\n  timestampForBackup,\n  writeBackupManifest,\n} from './manifest';\n\nexport interface ExportBackupContext {\n  backupPath: string;\n  /**\n   * The raw, credential-bearing database URL the caller passed to\n   * `exportBackup`. The hook needs the raw form to open its own\n   * connection, but **do not log this value verbatim** — it contains\n   * credentials. Run it through `redactDatabaseUrl` (exported from\n   * `@happyvertical/sql`) before including it in any output. The\n   * manifest's `database.url` field is redacted; only `databaseUrl`\n   * here is raw.\n   */\n  databaseUrl: string;\n  /**\n   * Local directory the caller should copy file storage into.\n   * Already exists by the time `onBackup` runs.\n   */\n  filesDir: string;\n}\n\nexport interface ExportBackupResult<Extra = unknown> {\n  /** Absolute path to the backup directory. */\n  backupPath: string;\n  /** The manifest that was written. */\n  manifest: BackupManifest & { extra?: Extra };\n}\n\nexport interface ExportBackupOptions<Extra = unknown> {\n  databaseUrl: string;\n  /** Override the parent dir for the timestamped backup. Defaults to ~/.local/share/happyvertical/backups. */\n  backupRoot?: string;\n  /** Prefix the timestamp with this label (e.g. 'prod', 'pre-migration'). Defaults to 'backup'. */\n  label?: string;\n  /** Allow exporting from a non-local DB without --allow-production. */\n  allowProduction?: boolean;\n  /** Allow exporting from a local DB even though `prod: true` is set. */\n  allowLocal?: boolean;\n  /** Caller is running a prod-flavored export. */\n  prod?: boolean;\n  /** Skip the file-storage half entirely (no `onBackup` invoked). */\n  skipFiles?: boolean;\n  /**\n   * Caller-supplied hook for backing up file storage. Receives the\n   * already-created backup/files directory; whatever it returns is\n   * recorded as `extra` on the manifest.\n   */\n  onBackup?: (ctx: ExportBackupContext) => Promise<Extra | void>;\n  /**\n   * Caller-supplied hook for filling the database half of the manifest\n   * with diagnostic metadata (row counts, schema count, etc.) — runs\n   * after the dump completes. As with `onBackup`, the `databaseUrl`\n   * passed in is the raw credential-bearing form — redact via\n   * `redactDatabaseUrl` before logging.\n   */\n  onDatabaseMetadata?: (ctx: {\n    /** Raw URL — see warning on {@link ExportBackupContext.databaseUrl}. */\n    databaseUrl: string;\n  }) => Promise<Record<string, unknown>>;\n  /** Recorded as `files.storageConfig` on the manifest after redaction by the caller. */\n  filesStorageConfig?: unknown;\n  /** Working dir used when discovering the git sha. Defaults to process.cwd(). */\n  gitCwd?: string;\n}\n\nexport interface RestoreBackupContext {\n  backupPath: string;\n  /** Raw URL — see warning on {@link ExportBackupContext.databaseUrl}. */\n  databaseUrl: string;\n  filesDir: string;\n  manifest: BackupManifest;\n}\n\nexport interface RestoreBackupOptions {\n  databaseUrl: string;\n  backupPath: string;\n  allowProduction?: boolean;\n  /** Skip the file-storage half (no `onRestore` invoked). */\n  skipFiles?: boolean;\n  /**\n   * Caller-supplied hook for restoring file storage from\n   * `backupPath/<files.directory>`. Runs after the pg_restore completes.\n   */\n  onRestore?: (ctx: RestoreBackupContext) => Promise<void>;\n}\n\nexport interface ResetLocalOptions\n  extends Omit<RestoreBackupOptions, 'allowProduction'> {}\n\n/** Default root for backups. Override via $HAPPYVERTICAL_BACKUP_DIR or `backupRoot`. */\nexport function defaultBackupRoot(): string {\n  return (\n    process.env.HAPPYVERTICAL_BACKUP_DIR ??\n    join(homedir(), '.local', 'share', 'happyvertical', 'backups')\n  );\n}\n\n/**\n * Take a postgres dump and (optionally) a snapshot of file storage,\n * writing both plus a manifest into a fresh timestamped directory.\n *\n * Returns the directory path and the manifest. The manifest's `extra`\n * field carries whatever `onBackup` returned.\n *\n * **Failure model:** the function is all-or-nothing. If any step after\n * the initial directory creation throws — `dumpPostgresDatabase`,\n * `onBackup`, `onDatabaseMetadata`, `getGitSha`, or the final manifest\n * write — the partial backup directory is removed (best-effort)\n * before the original error is re-thrown. Callers therefore never see\n * a backup directory on disk without a complete manifest, which would\n * otherwise poison later `restoreBackup` calls with confusing\n * \"no manifest\" errors and leak a partial dump containing sensitive\n * data. If cleanup itself fails, that error is logged via\n * `console.warn` and swallowed so it doesn't mask the original.\n */\nexport async function exportBackup<Extra = unknown>(\n  options: ExportBackupOptions<Extra>,\n): Promise<ExportBackupResult<Extra>> {\n  assertCanExportDatabase(options.databaseUrl, options);\n\n  const label = validateLabel(options.label ?? 'backup');\n  const backupPath = await createUniqueBackupDir(\n    options.backupRoot ?? defaultBackupRoot(),\n    label,\n  );\n\n  try {\n    const dumpPath = join(backupPath, DEFAULT_DUMP_FILE);\n    await dumpPostgresDatabase(options.databaseUrl, dumpPath);\n\n    const filesDir = join(backupPath, DEFAULT_FILES_DIR);\n    let filesInfo: BackupManifestFiles = {\n      directory: DEFAULT_FILES_DIR,\n      exported: false,\n      count: 0,\n      bytes: 0,\n      reason: 'Skipped by skipFiles.',\n      storageConfig: options.filesStorageConfig,\n    };\n    let extra: Extra | undefined;\n\n    if (!options.skipFiles && options.onBackup) {\n      await mkdir(filesDir, { recursive: true, mode: 0o700 });\n      const result = await options.onBackup({\n        backupPath,\n        databaseUrl: options.databaseUrl,\n        filesDir,\n      });\n      if (result !== undefined && result !== null) extra = result as Extra;\n      filesInfo = {\n        directory: DEFAULT_FILES_DIR,\n        exported: true,\n        count: 0,\n        bytes: 0,\n        storageConfig: options.filesStorageConfig,\n      };\n    }\n\n    const metadata = options.onDatabaseMetadata\n      ? await options.onDatabaseMetadata({ databaseUrl: options.databaseUrl })\n      : undefined;\n\n    const manifest: BackupManifest & { extra?: Extra } = {\n      kind: BACKUP_KIND,\n      version: BACKUP_VERSION,\n      timestamp: new Date().toISOString(),\n      gitSha: await getGitSha(options.gitCwd),\n      source: label,\n      database: {\n        dumpFile: DEFAULT_DUMP_FILE,\n        url: redactDatabaseUrl(options.databaseUrl),\n        metadata,\n      },\n      files: filesInfo,\n      extra,\n    };\n\n    await writeBackupManifest(backupPath, manifest);\n    return { backupPath, manifest };\n  } catch (error) {\n    // Partial state on disk would either confuse later restoreBackup\n    // calls (no manifest → cryptic ENOENT) or leak sensitive dump\n    // contents. Remove the directory; if cleanup fails, log but don't\n    // mask the original error.\n    try {\n      await rm(backupPath, { recursive: true, force: true });\n    } catch (cleanupError) {\n      console.warn(\n        `exportBackup: failed to clean up partial backup at ${backupPath}:`,\n        cleanupError instanceof Error\n          ? cleanupError.message\n          : String(cleanupError),\n      );\n    }\n    throw error;\n  }\n}\n\n/**\n * Restore a backup directory into `databaseUrl` and, if `onRestore` is\n * provided, run the file-storage half. The caller controls everything\n * after the dump completes (file copy, migrations, doctor) via the hook.\n */\nexport async function restoreBackup(\n  options: RestoreBackupOptions,\n): Promise<BackupManifest> {\n  const backupPath = resolve(options.backupPath);\n  const manifest = await readBackupManifest(backupPath);\n  assertCanImportDatabase(options.databaseUrl, options);\n  const dumpPath = join(\n    backupPath,\n    validateManifestPathSegment(\n      manifest.database.dumpFile,\n      'database dump file',\n    ),\n  );\n  const filesDir = join(\n    backupPath,\n    validateManifestPathSegment(manifest.files.directory, 'files directory'),\n  );\n\n  await restorePostgresDatabase(options.databaseUrl, dumpPath);\n\n  // Skip `onRestore` for DB-only backups: if the backup was taken with\n  // `skipFiles: true` or no `onBackup` hook, the manifest records\n  // `files.exported: false` and the `files/` directory may not exist on\n  // disk. Calling a generic restore hook anyway would either crash\n  // after the database has already been restored, or — worse — let\n  // the hook clear target file storage before discovering there's\n  // nothing to restore from.\n  if (!options.skipFiles && options.onRestore && manifest.files.exported) {\n    await options.onRestore({\n      backupPath,\n      databaseUrl: options.databaseUrl,\n      filesDir,\n      manifest,\n    });\n  }\n\n  return manifest;\n}\n\n/**\n * Drop-and-recreate the target database, then run `restoreBackup`.\n * Local-only: explicitly refuses non-local URLs without an escape hatch\n * (this is a destructive operation by design).\n */\nexport async function resetLocalDatabaseFromBackup(\n  options: ResetLocalOptions,\n): Promise<BackupManifest> {\n  assertCanImportDatabase(options.databaseUrl, { allowProduction: false });\n\n  // Validate the backup BEFORE dropping the local database. A mistyped\n  // backupPath, missing dump file, or corrupted manifest field would\n  // otherwise destroy the existing database (drop + create) and only\n  // then fail when restoreBackup tries to read those values — leaving\n  // the developer with an empty local DB and a confusing ENOENT error.\n  //\n  // Validates every manifest field restoreBackup later relies on\n  // (`database.dumpFile` AND `files.directory`), and verifies the dump\n  // file actually exists on disk. The drop only happens if all of that\n  // is sound.\n  const backupPath = resolve(options.backupPath);\n  const manifest = await readBackupManifest(backupPath);\n  const dumpFile = validateManifestPathSegment(\n    manifest.database.dumpFile,\n    'database dump file',\n  );\n  validateManifestPathSegment(manifest.files.directory, 'files directory');\n  await access(join(backupPath, dumpFile));\n\n  await dropPostgresDatabase(options.databaseUrl);\n  await createPostgresDatabase(options.databaseUrl);\n  return restoreBackup({ ...options, allowProduction: false });\n}\n\nasync function getGitSha(cwd: string = process.cwd()): Promise<string | null> {\n  try {\n    return await new Promise<string>((resolvePromise, reject) => {\n      execFile('git', ['rev-parse', 'HEAD'], { cwd }, (error, stdout) => {\n        if (error) {\n          reject(error);\n          return;\n        }\n        resolvePromise(stdout.trim());\n      });\n    });\n  } catch {\n    return null;\n  }\n}\n\nfunction validateLabel(label: string): string {\n  if (!label || label === '.' || label === '..' || /[\\\\/]/u.test(label)) {\n    throw new Error(\n      `Backup label \"${label}\" is invalid. Labels must be a single path-safe segment.`,\n    );\n  }\n  return label;\n}\n\nfunction validateManifestPathSegment(value: string, field: string): string {\n  if (!value || value === '.' || value === '..' || /[\\\\/]/u.test(value)) {\n    throw new Error(\n      `Backup manifest ${field} is invalid: \"${value}\". It must be a single path segment.`,\n    );\n  }\n  return value;\n}\n\nasync function createUniqueBackupDir(\n  backupRoot: string,\n  label: string,\n): Promise<string> {\n  const root = resolve(backupRoot);\n  await mkdir(root, { recursive: true, mode: 0o700 });\n\n  const baseName = `${label}-${timestampForBackup()}`;\n  for (let attempt = 0; attempt < 64; attempt += 1) {\n    const suffix = attempt === 0 ? '' : `-${attempt.toString(36)}`;\n    const candidate = join(root, `${baseName}${suffix}`);\n    try {\n      await mkdir(candidate, { mode: 0o700 });\n      return candidate;\n    } catch (error) {\n      if ((error as NodeJS.ErrnoException).code === 'EEXIST') {\n        continue;\n      }\n      throw error;\n    }\n  }\n\n  throw new Error(\n    `Failed to create a unique backup directory under ${root} for label \"${label}\".`,\n  );\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/backup/manifest.ts","../../src/backup/index.ts"],"sourcesContent":["/**\n * Backup manifest shape and helpers.\n *\n * The manifest is the source-of-truth for what's in a backup directory:\n * which database it came from, when, at what commit, and any\n * app-specific metadata that the caller chose to attach via the `extra`\n * field. Bumping `BACKUP_VERSION` is the way to evolve the shape — older\n * backups will fail `readBackupManifest` until upgraded.\n */\nimport { readFile, rename, writeFile } from 'node:fs/promises';\nimport { join, resolve } from 'node:path';\n\nexport const BACKUP_KIND = 'happyvertical-backup' as const;\nexport const BACKUP_VERSION = 1 as const;\nexport const DEFAULT_DUMP_FILE = 'database.dump';\nexport const DEFAULT_FILES_DIR = 'files';\nexport const DEFAULT_MANIFEST_FILE = 'manifest.json';\n\nexport interface BackupManifestDatabase {\n  /** File name of the pg_dump archive within the backup directory. */\n  dumpFile: string;\n  /** Redacted URL the dump was taken from. */\n  url: string;\n  /** Caller-supplied diagnostic metadata (row counts, schema count, etc.). */\n  metadata?: Record<string, unknown>;\n}\n\nexport interface BackupManifestFiles {\n  /** Directory name within the backup that holds copied file storage. */\n  directory: string;\n  exported: boolean;\n  count: number;\n  bytes: number;\n  reason?: string;\n  /** Redacted provider config, if the caller chose to record it. */\n  storageConfig?: unknown;\n}\n\nexport interface BackupManifest {\n  kind: typeof BACKUP_KIND;\n  version: typeof BACKUP_VERSION;\n  timestamp: string;\n  gitSha: string | null;\n  /** Free-form label (e.g. 'current', 'prod', 'pre-migration'). */\n  source: string;\n  database: BackupManifestDatabase;\n  files: BackupManifestFiles;\n  /** Opaque slot for app-specific extension (resume publish status, etc.). */\n  extra?: unknown;\n}\n\n/**\n * Read a backup manifest from `backupPath/manifest.json` and validate\n * that it matches this package's kind+version. Throws (with the path\n * included) on mismatch — that's almost always a real problem worth\n * surfacing, not silently tolerating.\n */\nexport async function readBackupManifest(\n  backupPath: string,\n): Promise<BackupManifest> {\n  const manifestPath = join(resolve(backupPath), DEFAULT_MANIFEST_FILE);\n  const manifest = JSON.parse(\n    await readFile(manifestPath, 'utf8'),\n  ) as BackupManifest;\n  if (manifest.kind !== BACKUP_KIND || manifest.version !== BACKUP_VERSION) {\n    throw new Error(\n      `Unsupported backup manifest at ${manifestPath} (kind=${manifest.kind}, version=${manifest.version}).`,\n    );\n  }\n  return manifest;\n}\n\nexport async function writeBackupManifest(\n  backupPath: string,\n  manifest: BackupManifest,\n): Promise<void> {\n  const targetPath = join(backupPath, DEFAULT_MANIFEST_FILE);\n  const tempPath = join(\n    backupPath,\n    `.manifest.${process.pid}.${Date.now().toString(36)}.tmp`,\n  );\n  await writeFile(tempPath, `${JSON.stringify(manifest, null, 2)}\\n`, {\n    mode: 0o600,\n  });\n  await rename(tempPath, targetPath);\n}\n\n/**\n * Filesystem-safe timestamp suitable for backup directory names — same\n * shape as `Date.toISOString()` but with `:` and `.` swapped to `-` so\n * the value is a valid path segment on Windows and friendly to shell\n * tab-completion everywhere else.\n */\nexport function timestampForBackup(date = new Date()): string {\n  return date.toISOString().replace(/[:.]/g, '-');\n}\n","/**\n * Backup orchestration — composes the pg shell-out helpers in\n * `../postgres-cli` with caller-supplied hooks for file storage,\n * app-specific manifest extras, and post-restore steps.\n *\n * Decoupled from `@happyvertical/files` on purpose: callers that want a\n * file-storage backup pass an `onBackup` callback that does the copy\n * however they prefer (local cp, S3 sync, WebDAV walk). That keeps this\n * subpath usable by apps that only need the database half.\n */\nimport { execFile } from 'node:child_process';\nimport { access, mkdir, rm } from 'node:fs/promises';\nimport { homedir } from 'node:os';\nimport { join, resolve } from 'node:path';\nimport {\n  assertCanExportDatabase,\n  assertCanImportDatabase,\n  createPostgresDatabase,\n  dropPostgresDatabase,\n  dumpPostgresDatabase,\n  redactDatabaseUrl,\n  restorePostgresDatabase,\n} from '../postgres-cli';\nimport {\n  BACKUP_KIND,\n  BACKUP_VERSION,\n  type BackupManifest,\n  type BackupManifestFiles,\n  DEFAULT_DUMP_FILE,\n  DEFAULT_FILES_DIR,\n  readBackupManifest,\n  timestampForBackup,\n  writeBackupManifest,\n} from './manifest';\n\nexport {\n  BACKUP_KIND,\n  BACKUP_VERSION,\n  type BackupManifest,\n  type BackupManifestDatabase,\n  type BackupManifestFiles,\n  DEFAULT_DUMP_FILE,\n  DEFAULT_FILES_DIR,\n  DEFAULT_MANIFEST_FILE,\n  readBackupManifest,\n  timestampForBackup,\n  writeBackupManifest,\n} from './manifest';\n\nexport interface ExportBackupContext {\n  backupPath: string;\n  /**\n   * The raw, credential-bearing database URL the caller passed to\n   * `exportBackup`. The hook needs the raw form to open its own\n   * connection, but **do not log this value verbatim** — it contains\n   * credentials. Run it through `redactDatabaseUrl` (exported from\n   * `@happyvertical/sql`) before including it in any output. The\n   * manifest's `database.url` field is redacted; only `databaseUrl`\n   * here is raw.\n   */\n  databaseUrl: string;\n  /**\n   * Local directory the caller should copy file storage into.\n   * Already exists by the time `onBackup` runs.\n   */\n  filesDir: string;\n}\n\nexport interface ExportBackupResult<Extra = unknown> {\n  /** Absolute path to the backup directory. */\n  backupPath: string;\n  /** The manifest that was written. */\n  manifest: BackupManifest & { extra?: Extra };\n}\n\nexport interface ExportBackupOptions<Extra = unknown> {\n  databaseUrl: string;\n  /** Override the parent dir for the timestamped backup. Defaults to ~/.local/share/happyvertical/backups. */\n  backupRoot?: string;\n  /** Prefix the timestamp with this label (e.g. 'prod', 'pre-migration'). Defaults to 'backup'. */\n  label?: string;\n  /** Allow exporting from a non-local DB without --allow-production. */\n  allowProduction?: boolean;\n  /** Allow exporting from a local DB even though `prod: true` is set. */\n  allowLocal?: boolean;\n  /** Caller is running a prod-flavored export. */\n  prod?: boolean;\n  /** Skip the file-storage half entirely (no `onBackup` invoked). */\n  skipFiles?: boolean;\n  /**\n   * Caller-supplied hook for backing up file storage. Receives the\n   * already-created backup/files directory; whatever it returns is\n   * recorded as `extra` on the manifest.\n   */\n  onBackup?: (ctx: ExportBackupContext) => Promise<Extra | void>;\n  /**\n   * Caller-supplied hook for filling the database half of the manifest\n   * with diagnostic metadata (row counts, schema count, etc.) — runs\n   * after the dump completes. As with `onBackup`, the `databaseUrl`\n   * passed in is the raw credential-bearing form — redact via\n   * `redactDatabaseUrl` before logging.\n   */\n  onDatabaseMetadata?: (ctx: {\n    /** Raw URL — see warning on {@link ExportBackupContext.databaseUrl}. */\n    databaseUrl: string;\n  }) => Promise<Record<string, unknown>>;\n  /** Recorded as `files.storageConfig` on the manifest after redaction by the caller. */\n  filesStorageConfig?: unknown;\n  /** Working dir used when discovering the git sha. Defaults to process.cwd(). */\n  gitCwd?: string;\n}\n\nexport interface RestoreBackupContext {\n  backupPath: string;\n  /** Raw URL — see warning on {@link ExportBackupContext.databaseUrl}. */\n  databaseUrl: string;\n  filesDir: string;\n  manifest: BackupManifest;\n}\n\nexport interface RestoreBackupOptions {\n  databaseUrl: string;\n  backupPath: string;\n  allowProduction?: boolean;\n  /** Skip the file-storage half (no `onRestore` invoked). */\n  skipFiles?: boolean;\n  /**\n   * Caller-supplied hook for restoring file storage from\n   * `backupPath/<files.directory>`. Runs after the pg_restore completes.\n   */\n  onRestore?: (ctx: RestoreBackupContext) => Promise<void>;\n}\n\nexport interface ResetLocalOptions\n  extends Omit<RestoreBackupOptions, 'allowProduction'> {}\n\n/** Default root for backups. Override via $HAPPYVERTICAL_BACKUP_DIR or `backupRoot`. */\nexport function defaultBackupRoot(): string {\n  return (\n    process.env.HAPPYVERTICAL_BACKUP_DIR ??\n    join(homedir(), '.local', 'share', 'happyvertical', 'backups')\n  );\n}\n\n/**\n * Take a postgres dump and (optionally) a snapshot of file storage,\n * writing both plus a manifest into a fresh timestamped directory.\n *\n * Returns the directory path and the manifest. The manifest's `extra`\n * field carries whatever `onBackup` returned.\n *\n * **Failure model:** the function is all-or-nothing. If any step after\n * the initial directory creation throws — `dumpPostgresDatabase`,\n * `onBackup`, `onDatabaseMetadata`, `getGitSha`, or the final manifest\n * write — the partial backup directory is removed (best-effort)\n * before the original error is re-thrown. Callers therefore never see\n * a backup directory on disk without a complete manifest, which would\n * otherwise poison later `restoreBackup` calls with confusing\n * \"no manifest\" errors and leak a partial dump containing sensitive\n * data. If cleanup itself fails, that error is logged via\n * `console.warn` and swallowed so it doesn't mask the original.\n */\nexport async function exportBackup<Extra = unknown>(\n  options: ExportBackupOptions<Extra>,\n): Promise<ExportBackupResult<Extra>> {\n  assertCanExportDatabase(options.databaseUrl, options);\n\n  const label = validateLabel(options.label ?? 'backup');\n  const backupPath = await createUniqueBackupDir(\n    options.backupRoot ?? defaultBackupRoot(),\n    label,\n  );\n\n  try {\n    const dumpPath = join(backupPath, DEFAULT_DUMP_FILE);\n    await dumpPostgresDatabase(options.databaseUrl, dumpPath);\n\n    const filesDir = join(backupPath, DEFAULT_FILES_DIR);\n    let filesInfo: BackupManifestFiles = {\n      directory: DEFAULT_FILES_DIR,\n      exported: false,\n      count: 0,\n      bytes: 0,\n      reason: 'Skipped by skipFiles.',\n      storageConfig: options.filesStorageConfig,\n    };\n    let extra: Extra | undefined;\n\n    if (!options.skipFiles && options.onBackup) {\n      await mkdir(filesDir, { recursive: true, mode: 0o700 });\n      const result = await options.onBackup({\n        backupPath,\n        databaseUrl: options.databaseUrl,\n        filesDir,\n      });\n      if (result !== undefined && result !== null) extra = result as Extra;\n      filesInfo = {\n        directory: DEFAULT_FILES_DIR,\n        exported: true,\n        count: 0,\n        bytes: 0,\n        storageConfig: options.filesStorageConfig,\n      };\n    }\n\n    const metadata = options.onDatabaseMetadata\n      ? await options.onDatabaseMetadata({ databaseUrl: options.databaseUrl })\n      : undefined;\n\n    const manifest: BackupManifest & { extra?: Extra } = {\n      kind: BACKUP_KIND,\n      version: BACKUP_VERSION,\n      timestamp: new Date().toISOString(),\n      gitSha: await getGitSha(options.gitCwd),\n      source: label,\n      database: {\n        dumpFile: DEFAULT_DUMP_FILE,\n        url: redactDatabaseUrl(options.databaseUrl),\n        metadata,\n      },\n      files: filesInfo,\n      extra,\n    };\n\n    await writeBackupManifest(backupPath, manifest);\n    return { backupPath, manifest };\n  } catch (error) {\n    // Partial state on disk would either confuse later restoreBackup\n    // calls (no manifest → cryptic ENOENT) or leak sensitive dump\n    // contents. Remove the directory; if cleanup fails, log but don't\n    // mask the original error.\n    try {\n      await rm(backupPath, { recursive: true, force: true });\n    } catch (cleanupError) {\n      console.warn(\n        `exportBackup: failed to clean up partial backup at ${backupPath}:`,\n        cleanupError instanceof Error\n          ? cleanupError.message\n          : String(cleanupError),\n      );\n    }\n    throw error;\n  }\n}\n\n/**\n * Restore a backup directory into `databaseUrl` and, if `onRestore` is\n * provided, run the file-storage half. The caller controls everything\n * after the dump completes (file copy, migrations, doctor) via the hook.\n */\nexport async function restoreBackup(\n  options: RestoreBackupOptions,\n): Promise<BackupManifest> {\n  const backupPath = resolve(options.backupPath);\n  const manifest = await readBackupManifest(backupPath);\n  assertCanImportDatabase(options.databaseUrl, options);\n  const dumpPath = join(\n    backupPath,\n    validateManifestPathSegment(\n      manifest.database.dumpFile,\n      'database dump file',\n    ),\n  );\n  const filesDir = join(\n    backupPath,\n    validateManifestPathSegment(manifest.files.directory, 'files directory'),\n  );\n\n  await restorePostgresDatabase(options.databaseUrl, dumpPath);\n\n  // Skip `onRestore` for DB-only backups: if the backup was taken with\n  // `skipFiles: true` or no `onBackup` hook, the manifest records\n  // `files.exported: false` and the `files/` directory may not exist on\n  // disk. Calling a generic restore hook anyway would either crash\n  // after the database has already been restored, or — worse — let\n  // the hook clear target file storage before discovering there's\n  // nothing to restore from.\n  if (!options.skipFiles && options.onRestore && manifest.files.exported) {\n    await options.onRestore({\n      backupPath,\n      databaseUrl: options.databaseUrl,\n      filesDir,\n      manifest,\n    });\n  }\n\n  return manifest;\n}\n\n/**\n * Drop-and-recreate the target database, then run `restoreBackup`.\n * Local-only: explicitly refuses non-local URLs without an escape hatch\n * (this is a destructive operation by design).\n */\nexport async function resetLocalDatabaseFromBackup(\n  options: ResetLocalOptions,\n): Promise<BackupManifest> {\n  assertCanImportDatabase(options.databaseUrl, { allowProduction: false });\n\n  // Validate the backup BEFORE dropping the local database. A mistyped\n  // backupPath, missing dump file, or corrupted manifest field would\n  // otherwise destroy the existing database (drop + create) and only\n  // then fail when restoreBackup tries to read those values — leaving\n  // the developer with an empty local DB and a confusing ENOENT error.\n  //\n  // Validates every manifest field restoreBackup later relies on\n  // (`database.dumpFile` AND `files.directory`), and verifies the dump\n  // file actually exists on disk. The drop only happens if all of that\n  // is sound.\n  const backupPath = resolve(options.backupPath);\n  const manifest = await readBackupManifest(backupPath);\n  const dumpFile = validateManifestPathSegment(\n    manifest.database.dumpFile,\n    'database dump file',\n  );\n  validateManifestPathSegment(manifest.files.directory, 'files directory');\n  await access(join(backupPath, dumpFile));\n\n  await dropPostgresDatabase(options.databaseUrl);\n  await createPostgresDatabase(options.databaseUrl);\n  return restoreBackup({ ...options, allowProduction: false });\n}\n\nasync function getGitSha(cwd: string = process.cwd()): Promise<string | null> {\n  try {\n    return await new Promise<string>((resolvePromise, reject) => {\n      execFile('git', ['rev-parse', 'HEAD'], { cwd }, (error, stdout) => {\n        if (error) {\n          reject(error);\n          return;\n        }\n        resolvePromise(stdout.trim());\n      });\n    });\n  } catch {\n    return null;\n  }\n}\n\nfunction validateLabel(label: string): string {\n  if (!label || label === '.' || label === '..' || /[\\\\/]/u.test(label)) {\n    throw new Error(\n      `Backup label \"${label}\" is invalid. Labels must be a single path-safe segment.`,\n    );\n  }\n  return label;\n}\n\nfunction validateManifestPathSegment(value: string, field: string): string {\n  if (!value || value === '.' || value === '..' || /[\\\\/]/u.test(value)) {\n    throw new Error(\n      `Backup manifest ${field} is invalid: \"${value}\". It must be a single path segment.`,\n    );\n  }\n  return value;\n}\n\nasync function createUniqueBackupDir(\n  backupRoot: string,\n  label: string,\n): Promise<string> {\n  const root = resolve(backupRoot);\n  await mkdir(root, { recursive: true, mode: 0o700 });\n\n  const baseName = `${label}-${timestampForBackup()}`;\n  for (let attempt = 0; attempt < 64; attempt += 1) {\n    const suffix = attempt === 0 ? '' : `-${attempt.toString(36)}`;\n    const candidate = join(root, `${baseName}${suffix}`);\n    try {\n      await mkdir(candidate, { mode: 0o700 });\n      return candidate;\n    } catch (error) {\n      if ((error as NodeJS.ErrnoException).code === 'EEXIST') {\n        continue;\n      }\n      throw error;\n    }\n  }\n\n  throw new Error(\n    `Failed to create a unique backup directory under ${root} for label \"${label}\".`,\n  );\n}\n"],"mappings":"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"}