@happyvertical/sql 0.74.8

package/AGENT.md

@@ -0,0 +1,33 @@
+# @happyvertical/sql
+
+<!-- BEGIN AGENT:GENERATED -->
+## Purpose
+Database interface with support for SQLite, PostgreSQL, and DuckDB
+
+## Package Map
+- Package: `@happyvertical/sql`
+- Hierarchy path: `@happyvertical/sdk > packages > sql`
+- Workspace position: `26 of 30` local packages
+- Internal dependencies: `@happyvertical/utils`
+- Internal dependents: `@happyvertical/jobs`, `@happyvertical/secrets`
+- Knowledge graph files: `AGENT.md`, `metadata.json`, `ecosystem-manifest.json`
+
+## Build & Test
+```bash
+pnpm --filter @happyvertical/sql build
+pnpm --filter @happyvertical/sql test
+pnpm --filter @happyvertical/sql clean
+```
+
+## Agent Correction Loops
+- If module resolution or export errors mention a workspace dependency, build the dependency first (`pnpm --filter @happyvertical/utils build`) and then rerun `pnpm --filter @happyvertical/sql build`.
+- If tests or exports fail after API, type, or bundle changes, run `pnpm --filter @happyvertical/sql clean` followed by `pnpm --filter @happyvertical/sql build` and `pnpm --filter @happyvertical/sql test`.
+- If failures span multiple packages or Turborepo ordering looks wrong, run `pnpm build` and `pnpm typecheck` from the repo root before retrying package-scoped commands.
+
+## Ecosystem Relationships
+- Provides: Database interface with support for SQLite, PostgreSQL, and DuckDB
+- Implements: none
+- Requires: @happyvertical/utils, @duckdb/node-api, @libsql/client, @russellthehippo/honker-node, @sqliteai/sqlite-vector, pg, sqlite-vss
+- Stability: stable (Primary package surface is described as implemented and production-oriented.)
+<!-- END AGENT:GENERATED -->
+

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,287 @@
+# @happyvertical/sql
+
+Database interface with support for SQLite (via LibSQL/Turso), PostgreSQL, DuckDB, and a JSON adapter (DuckDB-backed). Provides a unified API across all backends with template literal queries, CRUD helpers, transactions, schema synchronization, and vector search (PostgreSQL via pgvector).
+
+## Installation
+
+```bash
+pnpm add @happyvertical/sql
+```
+
+## Usage
+
+### Connecting to a Database
+
+```typescript
+import { getDatabase } from '@happyvertical/sql';
+
+// SQLite (in-memory)
+const db = await getDatabase({ type: 'sqlite', url: ':memory:' });
+
+// SQLite (file)
+const fileDb = await getDatabase({ type: 'sqlite', url: 'file:./app.db' });
+
+// LibSQL/Turso (remote)
+const tursoDb = await getDatabase({
+  type: 'sqlite',
+  url: 'libsql://your-database.turso.io',
+  authToken: process.env.TURSO_AUTH_TOKEN,
+});
+
+// PostgreSQL
+const pgDb = await getDatabase({
+  type: 'postgres',
+  url: 'postgresql://user:pass@localhost:5432/dbname',
+});
+
+// DuckDB with JSON file auto-registration
+const duckDb = await getDatabase({
+  type: 'duckdb',
+  url: ':memory:',
+  dataDir: './data',
+  autoRegisterJSON: true,
+});
+
+// JSON adapter (DuckDB-backed, reads/writes JSON files)
+const jsonDb = await getDatabase({
+  type: 'json',
+  url: './data',
+  writeStrategy: 'immediate',
+});
+```
+
+Configuration is also loaded from `HAVE_SQL_*` environment variables (e.g. `HAVE_SQL_TYPE`, `HAVE_SQL_URL`). User-provided options take precedence.
+
+### Template Literal Queries
+
+```typescript
+// Returns all rows
+const posts = await db.many`SELECT * FROM posts WHERE published = ${true}`;
+
+// Returns a single row or null
+const post = await db.single`SELECT * FROM posts WHERE id = ${postId}`;
+
+// Returns first column of first row
+const count = await db.pluck`SELECT COUNT(*) FROM posts WHERE author = ${name}`;
+
+// Executes without returning results
+await db.execute`DELETE FROM posts WHERE id = ${postId}`;
+```
+
+Shorthand aliases: `oo` (many), `oO` (single), `ox` (pluck), `xx` (execute).
+
+Interpolated values are always passed as parameterized values (never string-concatenated), with placeholder format handled per adapter (`?` for SQLite/DuckDB, `$1`/`$2` for PostgreSQL).
+
+### Raw Queries
+
+```typescript
+// Raw queries use each adapter's native placeholder syntax.
+await pgDb.query('SELECT * FROM posts WHERE id = $1', postId);
+await pgDb.query('SELECT * FROM posts WHERE id = $1', [postId]);
+await pgDb.query('SELECT * FROM posts WHERE id = ANY($1)', postIds);
+
+// Legacy ? placeholders are converted only when unambiguous.
+await pgDb.query('SELECT * FROM posts WHERE id = ?', postId);
+
+// Native operators remain safe; prefer $1 placeholders when mixing operators and values.
+await pgDb.query(`SELECT ('{"db":true}'::jsonb ? 'db') AS has_db`);
+```
+
+For PostgreSQL, a single array argument is treated as a values list unless the SQL shows a single array-typed placeholder, such as `$1::text[]`, `CAST($1 AS text[])`, `ANY($1)`, or the equivalent legacy `?` placeholder form. Transaction handles follow the same raw query behavior as the root database handle.
+
+### CRUD Helpers
+
+```typescript
+await db.insert('posts', { id: 'p1', title: 'Hello', author: 'Alice' });
+await db.insert('posts', [{ id: 'p2', title: 'A' }, { id: 'p3', title: 'B' }]);
+
+const post = await db.get('posts', { id: 'p1' });
+const recent = await db.list('posts', { author: 'Alice', 'created_at >': '2024-01-01' });
+await db.update('posts', { id: 'p1' }, { title: 'Updated' });
+await db.upsert('posts', ['id'], { id: 'p1', title: 'Upserted' });
+await db.delete('posts', { id: 'p1' });
+const total = await db.count('posts');
+const filtered = await db.count('posts', { published: true });
+
+const user = await db.getOrInsert('users', { email: 'a@b.com' }, { id: 'u1', email: 'a@b.com', name: 'A' });
+
+// Table-scoped helper
+const postsTable = db.table('posts');
+await postsTable.insert({ id: 'p4', title: 'Scoped' });
+const p = await postsTable.get({ id: 'p4' });
+```
+
+`upsert()` treats `NULL` values in conflict columns as matching existing `NULL`
+values so nullable composite keys update the existing row instead of inserting a
+duplicate. Pass `{ nullsDistinct: true }` as the fourth argument to preserve the
+database-native behavior where `NULL` conflict values are distinct.
+
+### Transactions
+
+```typescript
+// Callback-based (auto commit/rollback)
+await db.transaction(async (tx) => {
+  await tx.insert('users', { id: 'u1', name: 'Alice' });
+  await tx.insert('profiles', { user_id: 'u1', bio: 'Dev' });
+});
+
+// Manual control via beginTransaction()
+const tx = await db.beginTransaction();
+try {
+  await tx.insert('orders', { id: 'o1', total: 100 });
+  await tx.commit();
+} catch (e) {
+  await tx.rollback();
+  throw e;
+}
+```
+
+### WHERE Clause Building
+
+```typescript
+import { buildWhere } from '@happyvertical/sql';
+
+const { sql, values } = buildWhere({
+  status: 'active',
+  'price >': 100,
+  'category in': ['electronics', 'books'],
+  'name like': '%shirt%',
+  deleted_at: null,         // IS NULL
+  'updated_at !=': null,    // IS NOT NULL
+});
+// Use with raw query: db.query(`SELECT * FROM products ${sql}`, values)
+```
+
+Supports 2D array format for OR/AND compound logic:
+```typescript
+buildWhere([
+  [{ status: 'active' }, { 'price >': 100 }],
+  [{ status: 'pending' }, { priority: 'high' }],
+]);
+// WHERE (status = $1 AND price > $2) OR (status = $3 AND priority = $4)
+```
+
+### Schema Synchronization
+
+```typescript
+import { syncSchema } from '@happyvertical/sql';
+
+await syncSchema({
+  db,
+  schema: `
+    CREATE TABLE IF NOT EXISTS users (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      email TEXT UNIQUE
+    );
+  `,
+});
+
+const exists = await db.tableExists('users');
+```
+
+### Vector Search (PostgreSQL)
+
+PostgreSQL adapters expose `db.vector` when pgvector is available:
+
+```typescript
+await db.vector.ensureColumn('documents', 'embedding', 1536);
+await db.vector.ensureIndex('documents', 'embedding', { metric: 'cosine' });
+await db.vector.upsertVector('documents', { id: 'doc-1' }, 'embedding', vector);
+const results = await db.vector.search('documents', 'embedding', queryVector, { limit: 10 });
+```
+
+### Optional SQLite Capabilities
+
+SQLite keeps the existing LibSQL adapter path by default. For local development
+and tests, opt into native SQLite capabilities with `capabilities`. This switches
+the adapter to Node's built-in `node:sqlite` for local files or `:memory:` and
+rejects remote `libsql://`, `http://`, and `https://` URLs.
+
+```bash
+pnpm add -D @sqliteai/sqlite-vector @russellthehippo/honker-node
+```
+
+```typescript
+type SqliteCapabilitiesOptions = {
+  notifications?: boolean | {
+    watcherBackend?: 'polling' | 'kernel' | 'shm';
+    maxReaders?: number;
+  };
+  vector?: boolean | {
+    preload?: boolean;
+    quantization?: 'turbo4' | 'turbo3' | 'turbo2' | 'uint8' | 'int8' | '1bit';
+    maxMemory?: string;
+  };
+};
+```
+
+```typescript
+const db = await getDatabase({
+  type: 'sqlite',
+  url: 'file:./dev.db',
+  capabilities: {
+    vector: { quantization: 'turbo4', preload: true },
+    notifications: { watcherBackend: 'polling' },
+  },
+});
+
+await db.vector?.ensureColumn('documents', 'embedding', 1536);
+await db.vector?.upsertVector('documents', { id: 'doc-1' }, 'embedding', vector);
+const matches = await db.vector?.search('documents', 'embedding', queryVector, {
+  limit: 10,
+  metric: 'cosine',
+  where: 'status = $2',
+  params: ['published'],
+});
+
+const listener = db.notifications!.listen('jobs');
+await db.notifications!.notify('jobs', { id: 'job-1' });
+for await (const message of listener) {
+  console.log(message.channel, message.payload);
+  break;
+}
+await db.notifications!.waitForUpdate({ timeoutMs: 5000 });
+await db.close?.();
+```
+
+`@sqliteai/sqlite-vector` is loaded lazily through `getExtensionPath()` and only
+mutates schema when `ensureColumn()` or `ensureIndex()` is called. SQLite vector
+search uses the same `db.vector` API as PostgreSQL. `ensureIndex()` creates a
+quantized sqlite-vector index with `turbo4` by default, and filtered searches can
+keep PostgreSQL-style `$2`, `$3`, etc. placeholders in `VectorSearchOptions.where`.
+
+`@russellthehippo/honker-node` is loaded lazily as a sidecar connection to the
+same file. Honker bootstraps its `_honker_*` tables on open and requires a
+file-backed database, so `:memory:` is rejected when notifications are enabled.
+When notifications are enabled, `db.notifications` exposes `notify()`,
+`listen()`, `waitForUpdate()`, and `prune()`; call `db.close?.()` when a test or
+worker is done so watcher handles and sidecar connections are released.
+
+Both packages are optional peers. `sqlite-vector` uses a custom license declared
+as `SEE LICENSE IN LICENSE.md`; keep it opt-in and review the upstream
+[license](https://github.com/sqliteai/sqlite-vector/blob/main/LICENSE.md) before
+shipping it beyond development or test environments.
+
+## Adapters
+
+| Adapter | `type` | Backend | Notes |
+|---------|--------|---------|-------|
+| SQLite | `'sqlite'` | LibSQL (`@libsql/client`) by default; native `node:sqlite` when capabilities are enabled | Supports `:memory:`, file, and remote Turso URLs by default. Native capabilities are local-only |
+| PostgreSQL | `'postgres'` | `pg` Pool | Connection pooling, pgvector support |
+| DuckDB | `'duckdb'` | `@duckdb/node-api` | JSON file auto-registration, write-back strategies |
+| JSON | `'json'` | DuckDB in-memory | Queries JSON files as tables, connection caching |
+
+## API Overview
+
+**Factory**: `getDatabase(options)` — creates or returns a cached database connection.
+
+**Interface** (`DatabaseInterface`): `many`, `single`, `pluck`, `execute`, `query`, `insert`, `get`, `list`, `update`, `upsert`, `getOrInsert`, `delete`, `count`, `table`, `tableExists`, `syncSchema`, `transaction`, `beginTransaction`, `vector`, `notifications`, `close`.
+
+**Utilities**: `buildWhere`, `syncSchema`, `tableExists`, `escapeSqlValue`, `validateColumnName`, `formatDbError`, `convertUniqueIndexesToInlineConstraints`.
+
+**Schema**: `DatabaseSchemaManager` for JSON manifest-based schema initialization with dependency resolution.
+
+## License
+
+ISC

package/dist/backup/index.d.ts

@@ -0,0 +1,119 @@
+import { BackupManifest } from './manifest';
+export { BACKUP_KIND, BACKUP_VERSION, type BackupManifest, type BackupManifestDatabase, type BackupManifestFiles, DEFAULT_DUMP_FILE, DEFAULT_FILES_DIR, DEFAULT_MANIFEST_FILE, readBackupManifest, timestampForBackup, writeBackupManifest, } from './manifest';
+export interface ExportBackupContext {
+    backupPath: string;
+    /**
+     * The raw, credential-bearing database URL the caller passed to
+     * `exportBackup`. The hook needs the raw form to open its own
+     * connection, but **do not log this value verbatim** — it contains
+     * credentials. Run it through `redactDatabaseUrl` (exported from
+     * `@happyvertical/sql`) before including it in any output. The
+     * manifest's `database.url` field is redacted; only `databaseUrl`
+     * here is raw.
+     */
+    databaseUrl: string;
+    /**
+     * Local directory the caller should copy file storage into.
+     * Already exists by the time `onBackup` runs.
+     */
+    filesDir: string;
+}
+export interface ExportBackupResult<Extra = unknown> {
+    /** Absolute path to the backup directory. */
+    backupPath: string;
+    /** The manifest that was written. */
+    manifest: BackupManifest & {
+        extra?: Extra;
+    };
+}
+export interface ExportBackupOptions<Extra = unknown> {
+    databaseUrl: string;
+    /** Override the parent dir for the timestamped backup. Defaults to ~/.local/share/happyvertical/backups. */
+    backupRoot?: string;
+    /** Prefix the timestamp with this label (e.g. 'prod', 'pre-migration'). Defaults to 'backup'. */
+    label?: string;
+    /** Allow exporting from a non-local DB without --allow-production. */
+    allowProduction?: boolean;
+    /** Allow exporting from a local DB even though `prod: true` is set. */
+    allowLocal?: boolean;
+    /** Caller is running a prod-flavored export. */
+    prod?: boolean;
+    /** Skip the file-storage half entirely (no `onBackup` invoked). */
+    skipFiles?: boolean;
+    /**
+     * Caller-supplied hook for backing up file storage. Receives the
+     * already-created backup/files directory; whatever it returns is
+     * recorded as `extra` on the manifest.
+     */
+    onBackup?: (ctx: ExportBackupContext) => Promise<Extra | void>;
+    /**
+     * Caller-supplied hook for filling the database half of the manifest
+     * with diagnostic metadata (row counts, schema count, etc.) — runs
+     * after the dump completes. As with `onBackup`, the `databaseUrl`
+     * passed in is the raw credential-bearing form — redact via
+     * `redactDatabaseUrl` before logging.
+     */
+    onDatabaseMetadata?: (ctx: {
+        /** Raw URL — see warning on {@link ExportBackupContext.databaseUrl}. */
+        databaseUrl: string;
+    }) => Promise<Record<string, unknown>>;
+    /** Recorded as `files.storageConfig` on the manifest after redaction by the caller. */
+    filesStorageConfig?: unknown;
+    /** Working dir used when discovering the git sha. Defaults to process.cwd(). */
+    gitCwd?: string;
+}
+export interface RestoreBackupContext {
+    backupPath: string;
+    /** Raw URL — see warning on {@link ExportBackupContext.databaseUrl}. */
+    databaseUrl: string;
+    filesDir: string;
+    manifest: BackupManifest;
+}
+export interface RestoreBackupOptions {
+    databaseUrl: string;
+    backupPath: string;
+    allowProduction?: boolean;
+    /** Skip the file-storage half (no `onRestore` invoked). */
+    skipFiles?: boolean;
+    /**
+     * Caller-supplied hook for restoring file storage from
+     * `backupPath/<files.directory>`. Runs after the pg_restore completes.
+     */
+    onRestore?: (ctx: RestoreBackupContext) => Promise<void>;
+}
+export interface ResetLocalOptions extends Omit<RestoreBackupOptions, 'allowProduction'> {
+}
+/** Default root for backups. Override via $HAPPYVERTICAL_BACKUP_DIR or `backupRoot`. */
+export declare function defaultBackupRoot(): string;
+/**
+ * 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.
+ */
+export declare function exportBackup<Extra = unknown>(options: ExportBackupOptions<Extra>): Promise<ExportBackupResult<Extra>>;
+/**
+ * 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.
+ */
+export declare function restoreBackup(options: RestoreBackupOptions): Promise<BackupManifest>;
+/**
+ * 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).
+ */
+export declare function resetLocalDatabaseFromBackup(options: ResetLocalOptions): Promise<BackupManifest>;
+//# sourceMappingURL=index.d.ts.map

package/dist/backup/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/backup/index.ts"],"names":[],"mappings":"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"}

package/dist/backup/index.js

@@ -0,0 +1,212 @@
+import { execFile } from "node:child_process";
+import { readFile, writeFile, rename, mkdir, rm, access } from "node:fs/promises";
+import { homedir } from "node:os";
+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";
+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;
+}
+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);
+}
+function timestampForBackup(date = /* @__PURE__ */ new Date()) {
+  return date.toISOString().replace(/[:.]/g, "-");
+}
+function defaultBackupRoot() {
+  return process.env.HAPPYVERTICAL_BACKUP_DIR ?? join(homedir(), ".local", "share", "happyvertical", "backups");
+}
+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;
+  }
+}
+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;
+}
+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 });
+}
+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;
+  }
+}
+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;
+}
+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;
+}
+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}".`
+  );
+}
+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