@cedarjs/pg 0.1.0-alpha.1 → 0.2.0-alpha.0

package/dist/index.d.cts

@@ -1,59 +1,10 @@
-//#region src/core/worktree.d.ts
-type WorktreeIdentity = {
-  /** Absolute path to the worktree / project root. */
-  root: string;
-  /** Basename of the git common dir / main checkout (e.g. `cedar`). */
-  repoSlug: string;
-  /** Basename of this worktree directory (e.g. `feat-auth`). */
-  worktreeSlug: string;
-  /** First 8 hex chars of sha256(absolute root). */
-  pathHash: string;
-};
-/**
- * Resolve the project / worktree root.
- * Explicit `root` wins (app project path). Otherwise prefer git toplevel, then cwd.
- */
-declare function resolveRoot(root?: string): string;
-/**
- * Identify repo + worktree for observable DB naming.
- */
-declare function resolveWorktreeIdentity(root?: string): WorktreeIdentity;
-//#endregion
-//#region src/core/naming.d.ts
-type DbMode = "dev" | "test";
-/**
- * Build an observable Postgres database name:
- *   cpg_<repoSlug>_<worktreeSlug>_<mode>_<pathHash8>
- *
- * Never drops `mode` or `pathHash`. Truncates slugs to fit ≤63 chars.
- */
-declare function buildDatabaseName(identity: WorktreeIdentity, mode: DbMode): string;
-declare function buildRoleName(databaseName: string): string;
-//#endregion
-//#region src/core/lease.d.ts
-type Lease = {
-  schemaVersion: 1;
-  mode: DbMode;
-  root: string;
-  repoSlug: string;
-  worktreeSlug: string;
-  pathHash: string;
-  databaseName: string;
-  roleName: string;
-  port: number;
-  pid: number;
-  createdAt: string;
-};
-/** Narrow-parse a lease; reject incomplete or wrong-version records. */
-declare function parseLease(raw: unknown): Lease | null;
-declare function readLease(root: string, mode: DbMode): Lease | null;
-declare function isOrphanLease(lease: Lease): boolean;
-//#endregion
+import { a as WorktreeIdentity, i as buildRoleName, n as buildCloneDatabaseName, o as resolveRoot, r as buildDatabaseName, s as resolveWorktreeIdentity, t as DbMode } from "./naming-C2nGVxPk.cjs";
+import { a as readLease, i as parseLease, n as envFilePath, r as isOrphanLease, t as Lease } from "./lease-t4I9JahV.cjs";
 //#region src/core/policy.d.ts
 /**
- * Shared ensure skip policy for test-runner adapters and Cedar CLI bridges.
+ * Shared acquire skip policy for test-runner adapters and Cedar CLI bridges.
  */
-type EnsureSkip = {
+type AcquireSkip = {
   skip: false;
 } | {
   skip: true;
@@ -63,45 +14,55 @@ type EnsureSkip = {
   reason: "external-url";
   databaseUrl: string;
 };
-type ResolveEnsureSkipInput = {
+type ResolveAcquireSkipInput = {
   /** Candidate URL (TEST_DATABASE_URL for tests, DATABASE_URL for dev). */
   url?: string;
   /** When true, never skip (CEDAR_PG_FORCE=1). */
   force?: boolean;
   /**
-   * When true, skip ensure entirely.
+   * When true, skip acquire entirely.
    * Defaults from CEDAR_PG=0|false (opt-out adapters). Pass `false` for Cedar opt-in flows.
    */
   disabled?: boolean;
 };
+/**
+ * Inject DATABASE_URL (and TEST_DATABASE_URL for test mode) from a resolved URL.
+ * Single env path for acquire, clone, and external-url skip.
+ */
+declare function applyDatabaseUrlEnv(databaseUrl: string, options?: {
+  mode?: "dev" | "test";
+}): void;
 /**
  * True when the URL looks like a cedarpg provisioned database (`cpg_*` name/role).
- * These must never be treated as an external escape hatch; always re-ensure so
+ * These must never be treated as an external escape hatch; always re-acquire so
  * disposed/stale shell env cannot skip provisioning.
  */
 declare function isCedarPgManagedUrl(url: string | undefined): boolean;
 /**
- * True when `url` is a real external database and ensure should be skipped.
- * Sqlite `file:` URLs and cedarpg `cpg_*` URLs are not external.
+ * True when `url` is a real external database and acquire should be skipped.
+ * Sqlite `file:` URLs, cedarpg `cpg_*` URLs, and unset template placeholders
+ * are not external.
  */
 declare function isExternalDatabaseEscapeHatch(url: string | undefined): boolean;
 /**
- * Decide whether ensure should run.
+ * Decide whether acquire should run.
  * Adapters may call with no args (env defaults). Cedar opt-in should pass `disabled: false`
  * and the relevant `url` (`DATABASE_URL` or `TEST_DATABASE_URL`).
  */
-declare function resolveEnsureSkip(input?: ResolveEnsureSkipInput): EnsureSkip;
+declare function resolveAcquireSkip(input?: ResolveAcquireSkipInput): AcquireSkip;
 //#endregion
 //#region src/core/lifecycle.d.ts
 declare function urlFromLease(lease: Lease): string;
-type EnsureOptions = {
+type AcquireOptions = {
   root?: string;
   mode: DbMode;
   /** Inject DATABASE_URL / TEST_DATABASE_URL into process.env (default true). */
   setEnv?: boolean;
 };
-type EnsureResult = {
+type AcquireResult = {
   databaseUrl: string;
+  /** Superuser URL for privileged DDL (mark template, CREATE DATABASE … TEMPLATE). */
+  adminUrl: string;
   databaseName: string;
   roleName: string;
   repoSlug: string;
@@ -113,14 +74,14 @@ type EnsureResult = {
   dispose: () => Promise<void>;
 };
 /**
- * Ensure a worktree-scoped database exists and return connection info.
+ * Acquire a worktree-scoped database and return connection info.
  *
  * - `dev`: keep DB across restarts.
  * - `test`: DROP when `dispose()` is awaited (callers / test runners own teardown).
  */
-declare function ensure(options: EnsureOptions): Promise<EnsureResult>;
-type EnsureIfNeededOptions = EnsureOptions & ResolveEnsureSkipInput;
-type EnsureIfNeededResult = {
+declare function acquire(options: AcquireOptions): Promise<AcquireResult>;
+type AcquireIfNeededOptions = AcquireOptions & ResolveAcquireSkipInput;
+type AcquireIfNeededResult = {
   status: "skipped";
   reason: "disabled";
 } | {
@@ -128,13 +89,13 @@ type EnsureIfNeededResult = {
   reason: "external-url";
   databaseUrl: string;
 } | ({
-  status: "ensured";
-} & EnsureResult);
+  status: "acquired";
+} & AcquireResult);
 /**
- * Resolve skip policy then ensure. Single entry for hosts (Cedar CLI, Jest, Vitest).
- * On external-url skip, sets DATABASE_URL when `setEnv` is not false.
+ * Resolve skip policy then acquire. Single entry for hosts (Cedar CLI, Jest, Vitest).
+ * On external-url skip, applies DATABASE_URL / TEST_DATABASE_URL when `setEnv` is not false.
  */
-declare function ensureIfNeeded(options: EnsureIfNeededOptions): Promise<EnsureIfNeededResult>;
+declare function acquireIfNeeded(options: AcquireIfNeededOptions): Promise<AcquireIfNeededResult>;
 type DisposeOptions = {
   root?: string;
   mode?: DbMode;
@@ -142,24 +103,150 @@ type DisposeOptions = {
 type DisposeResult = {
   dropped: true;
   databaseName: string;
+  droppedDatabases: string[];
 } | {
   dropped: false;
   reason: "no-lease" | "host-unavailable";
 };
 /**
- * DROP the worktree database for the given mode (default: test).
- * No-ops without a valid lease (never invents a name to DROP).
+ * Role-scoped suite teardown: DROP every database owned by the lease role
+ * (TEMPLATE + clones), then DROP ROLE and forget the lease. Unsets `IS_TEMPLATE`
+ * as needed. This is not per-clone cleanup — use `CloneResult.dropClone` for that.
+ * No-ops without a valid lease; never invents a DROP target beyond role ownership.
  * If the host is unavailable, leaves the lease so dispose/gc can retry.
  */
 declare function dispose(options?: DisposeOptions): Promise<DisposeResult>;
 /**
  * Drop databases whose registered worktree root no longer exists on disk.
- * Registry entries are removed only after a successful DROP.
+ * Registry entries are removed only after a successful DROP (owned DBs + lease DB).
  */
 declare function gc(): Promise<{
   dropped: string[];
 }>;
 //#endregion
+//#region src/core/template.d.ts
+type MarkTemplateOptions = {
+  root?: string;
+  mode: DbMode;
+  /** Superuser URL from `acquire`; when omitted, discovers/starts the host. */
+  adminUrl?: string;
+};
+/**
+ * After migrations, mark the leased DB as a PostgreSQL TEMPLATE so workers can clone it.
+ * Requires a lease from `acquire` (no datname override).
+ */
+declare function markTemplate(options: MarkTemplateOptions): Promise<{
+  databaseName: string;
+  adminUrl: string;
+}>;
+type CloneFromTemplateOptions = {
+  root?: string;
+  mode: DbMode;
+  /** Superuser URL from `acquire`; when omitted, discovers/starts the host. */
+  adminUrl?: string;
+  /**
+   * Suffix for the clone datname (e.g. Jest worker id).
+   * Defaults to `<pid>_<base36 time>`.
+   */
+  name?: string;
+  /**
+   * Inject DATABASE_URL / TEST_DATABASE_URL for this clone (default false).
+   * Host `cloneFromTemplateIfNeeded` defaults true; worker adapters pass true explicitly.
+   */
+  setEnv?: boolean;
+};
+type CloneResult = {
+  databaseUrl: string;
+  adminUrl: string;
+  databaseName: string;
+  roleName: string;
+  templateName: string;
+  port: number;
+  /**
+   * DROP this clone only (leaves TEMPLATE + role if still owned elsewhere).
+   * Not suite teardown — use role-scoped `dispose` for that.
+   */
+  dropClone: () => Promise<void>;
+};
+/**
+ * Clone the leased TEMPLATE database via admin (`CREATE DATABASE … TEMPLATE`).
+ * Reuses the template role so `databaseUrl` passwords stay valid (scheme v2).
+ * Provider rejects when the leased DB is not marked TEMPLATE.
+ * Port comes from the lease; admin URL is passed through or rediscovered.
+ */
+declare function cloneFromTemplate(options: CloneFromTemplateOptions): Promise<CloneResult>;
+type CloneFromTemplateIfNeededOptions = CloneFromTemplateOptions & ResolveAcquireSkipInput;
+type CloneFromTemplateIfNeededResult = {
+  status: "skipped";
+  reason: "disabled";
+} | {
+  status: "skipped";
+  reason: "external-url";
+  databaseUrl: string;
+} | ({
+  status: "cloned";
+} & CloneResult);
+/**
+ * Resolve skip policy then clone. Host entry for worker adapters (same skip
+ * semantics as `acquireIfNeeded`). Defaults `setEnv` on for skip and clone paths.
+ */
+declare function cloneFromTemplateIfNeeded(options: CloneFromTemplateIfNeededOptions): Promise<CloneFromTemplateIfNeededResult>;
+//#endregion
+//#region src/core/constants.d.ts
+/**
+ * Product identity vs frozen crypto.
+ *
+ * State dirs follow the CLI name (`.cedarpg`): product-owned, not nested under
+ * autopg's `~/.autopg/` (host owns that) and not a generic `.pg` (collision-prone).
+ * Password salt is an opaque crypto constant; bump ROLE_PASSWORD_SCHEME to change it.
+ */
+/** User-facing CLI binary (`package.json` bin) and log prefix */
+declare const CLI_NAME = "cedarpg";
+/**
+ * Worktree-local state dir and home-registry parent (`~/.cedarpg/registry`).
+ * Frozen for lease/gc discovery after first alpha consumers appear.
+ */
+declare const STATE_DIRNAME = ".cedarpg";
+//#endregion
+//#region src/adapters/load-mode-env.d.ts
+type LoadModeEnvOptions = {
+  root?: string;
+  /** Overwrite existing `process.env` keys (default: only fill undefined). */
+  overwrite?: boolean;
+};
+//#endregion
+//#region src/adapters/load-test-env.d.ts
+type LoadTestEnvOptions = LoadModeEnvOptions;
+/**
+ * Load `.cedarpg/test.env` into `process.env` (worker-side).
+ *
+ * Jest (and optional Vitest `setupFiles`) run tests in a different process than
+ * `globalSetup`, so `setEnv` in acquire does not reach workers — the env file does.
+ *
+ * No-ops unless a matching `test.json` lease exists, so a leftover env after dispose
+ * cannot inject a dropped DATABASE_URL.
+ */
+declare function loadTestEnv(rootOrOptions?: string | LoadTestEnvOptions): void;
+//#endregion
+//#region src/adapters/load-dev-env.d.ts
+type LoadDevEnvOptions = LoadModeEnvOptions;
+/** Load `.cedarpg/dev.env` into `process.env`. Use `{ overwrite: true }` to beat `.env`. */
+declare function loadDevEnv(rootOrOptions?: string | LoadDevEnvOptions): void;
+//#endregion
+//#region src/adapters/acquire-task.d.ts
+type AcquireTaskContext = Pick<AcquireResult, "databaseUrl" | "adminUrl" | "databaseName" | "roleName" | "root" | "mode" | "port">;
+type CreateAcquireTaskOptions = {
+  mode: DbMode;
+  root?: string;
+  /** Ignore external-URL escape hatch (`CEDAR_PG_FORCE=1` also works). */
+  force?: boolean;
+  setEnv?: boolean;
+  /** App-owned migrate/seed after a successful acquire. */
+  afterAcquire?: (ctx: AcquireTaskContext) => void | Promise<void>;
+};
+/** Run acquireIfNeeded, then optional afterAcquire (migrate / db:ready). */
+declare function createAcquireTask(options: CreateAcquireTaskOptions): () => Promise<void>;
+//#endregion
 //#region src/providers/autopg.d.ts
 type AutopgDiscovery = {
   port: number;
@@ -167,8 +254,8 @@ type AutopgDiscovery = {
   bin: string;
 };
 declare const INSTALL_HINT: string;
-/** Password scheme v1: sha256(PASSWORD_SALT_PREFIX + "\\0" + databaseName) hex[:32]. Frozen for URL rebuild. */
-declare const ROLE_PASSWORD_SCHEME: "v1";
+/** Password scheme v2: sha256(PASSWORD_SALT_PREFIX + "\\0" + roleName) hex[:32]. Frozen for URL rebuild. */
+declare const ROLE_PASSWORD_SCHEME: "v2";
 declare function resolveAutopgBin(): string | null;
 declare function requireAutopgBin(): string;
 /**
@@ -181,15 +268,14 @@ declare function parseHostStatus(json: string): {
  * Discover a live autopg host via `autopg status --json`. Throws if the host is not proven live.
  */
 declare function discoverHost(bin?: string): AutopgDiscovery;
-/**
- * Ensure the host postmaster is up. Runs `autopg install` only after status fails, then re-discovers.
- */
-declare function ensureHostRunning(bin?: string): AutopgDiscovery;
 /**
  * Deterministic local-only password for an app role (Prisma/TCP need it;
  * autopg hba uses `password` for 127.0.0.1).
+ *
+ * Keyed by `roleName` (not databaseName) so TEMPLATE clones that reuse the
+ * same role keep working when `buildDatabaseUrl` is called with a new database.
  */
-declare function rolePasswordFor(databaseName: string): string;
+declare function rolePasswordFor(roleName: string): string;
 declare function buildDatabaseUrl(opts: {
   port: number;
   databaseName: string;
@@ -197,5 +283,5 @@ declare function buildDatabaseUrl(opts: {
   password?: string;
 }): string;
 //#endregion
-export { type DbMode, type DisposeOptions, type DisposeResult, type EnsureIfNeededOptions, type EnsureIfNeededResult, type EnsureOptions, type EnsureResult, type EnsureSkip, INSTALL_HINT, type Lease, ROLE_PASSWORD_SCHEME, type ResolveEnsureSkipInput, type WorktreeIdentity, buildDatabaseName, buildDatabaseUrl, buildRoleName, discoverHost, dispose, ensure, ensureHostRunning, ensureIfNeeded, gc, isCedarPgManagedUrl, isExternalDatabaseEscapeHatch, isOrphanLease, parseHostStatus, parseLease, readLease, requireAutopgBin, resolveAutopgBin, resolveEnsureSkip, resolveRoot, resolveWorktreeIdentity, rolePasswordFor, urlFromLease };
+export { type AcquireIfNeededOptions, type AcquireIfNeededResult, type AcquireOptions, type AcquireResult, type AcquireSkip, type AcquireTaskContext, type AutopgDiscovery, CLI_NAME, type CloneFromTemplateIfNeededOptions, type CloneFromTemplateIfNeededResult, type CloneFromTemplateOptions, type CloneResult, type CreateAcquireTaskOptions, type DbMode, type DisposeOptions, type DisposeResult, INSTALL_HINT, type Lease, type LoadDevEnvOptions, type LoadTestEnvOptions, type MarkTemplateOptions, ROLE_PASSWORD_SCHEME, type ResolveAcquireSkipInput, STATE_DIRNAME, type WorktreeIdentity, acquire, acquireIfNeeded, applyDatabaseUrlEnv, buildCloneDatabaseName, buildDatabaseName, buildDatabaseUrl, buildRoleName, cloneFromTemplate, cloneFromTemplateIfNeeded, createAcquireTask, discoverHost, dispose, envFilePath, gc, isCedarPgManagedUrl, isExternalDatabaseEscapeHatch, isOrphanLease, loadDevEnv, loadTestEnv, markTemplate, parseHostStatus, parseLease, readLease, requireAutopgBin, resolveAcquireSkip, resolveAutopgBin, resolveRoot, resolveWorktreeIdentity, rolePasswordFor, urlFromLease };
 //# sourceMappingURL=index.d.cts.map