@cedarjs/pg 0.1.0-alpha.0

package/dist/index.d.cts

@@ -0,0 +1,201 @@
+//#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
+//#region src/core/policy.d.ts
+/**
+ * Shared ensure skip policy for test-runner adapters and Cedar CLI bridges.
+ */
+type EnsureSkip = {
+  skip: false;
+} | {
+  skip: true;
+  reason: "disabled";
+} | {
+  skip: true;
+  reason: "external-url";
+  databaseUrl: string;
+};
+type ResolveEnsureSkipInput = {
+  /** 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.
+   * Defaults from CEDAR_PG=0|false (opt-out adapters). Pass `false` for Cedar opt-in flows.
+   */
+  disabled?: boolean;
+};
+/**
+ * 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
+ * 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.
+ */
+declare function isExternalDatabaseEscapeHatch(url: string | undefined): boolean;
+/**
+ * Decide whether ensure 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;
+//#endregion
+//#region src/core/lifecycle.d.ts
+declare function urlFromLease(lease: Lease): string;
+type EnsureOptions = {
+  root?: string;
+  mode: DbMode;
+  /** Inject DATABASE_URL / TEST_DATABASE_URL into process.env (default true). */
+  setEnv?: boolean;
+};
+type EnsureResult = {
+  databaseUrl: string;
+  databaseName: string;
+  roleName: string;
+  repoSlug: string;
+  worktreeSlug: string;
+  pathHash: string;
+  root: string;
+  mode: DbMode;
+  port: number;
+  dispose: () => Promise<void>;
+};
+/**
+ * Ensure a worktree-scoped database exists 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 = {
+  status: "skipped";
+  reason: "disabled";
+} | {
+  status: "skipped";
+  reason: "external-url";
+  databaseUrl: string;
+} | ({
+  status: "ensured";
+} & EnsureResult);
+/**
+ * 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.
+ */
+declare function ensureIfNeeded(options: EnsureIfNeededOptions): Promise<EnsureIfNeededResult>;
+type DisposeOptions = {
+  root?: string;
+  mode?: DbMode;
+};
+type DisposeResult = {
+  dropped: true;
+  databaseName: 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).
+ * 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.
+ */
+declare function gc(): Promise<{
+  dropped: string[];
+}>;
+//#endregion
+//#region src/providers/autopg.d.ts
+type AutopgDiscovery = {
+  port: number;
+  adminUrl: string;
+  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";
+declare function resolveAutopgBin(): string | null;
+declare function requireAutopgBin(): string;
+/**
+ * Parse `autopg status --json` output. Requires a numeric port and running !== false.
+ */
+declare function parseHostStatus(json: string): {
+  port: number;
+};
+/**
+ * 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).
+ */
+declare function rolePasswordFor(databaseName: string): string;
+declare function buildDatabaseUrl(opts: {
+  port: number;
+  databaseName: string;
+  roleName: string;
+  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 };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -0,0 +1,201 @@
+//#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
+//#region src/core/policy.d.ts
+/**
+ * Shared ensure skip policy for test-runner adapters and Cedar CLI bridges.
+ */
+type EnsureSkip = {
+  skip: false;
+} | {
+  skip: true;
+  reason: "disabled";
+} | {
+  skip: true;
+  reason: "external-url";
+  databaseUrl: string;
+};
+type ResolveEnsureSkipInput = {
+  /** 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.
+   * Defaults from CEDAR_PG=0|false (opt-out adapters). Pass `false` for Cedar opt-in flows.
+   */
+  disabled?: boolean;
+};
+/**
+ * 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
+ * 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.
+ */
+declare function isExternalDatabaseEscapeHatch(url: string | undefined): boolean;
+/**
+ * Decide whether ensure 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;
+//#endregion
+//#region src/core/lifecycle.d.ts
+declare function urlFromLease(lease: Lease): string;
+type EnsureOptions = {
+  root?: string;
+  mode: DbMode;
+  /** Inject DATABASE_URL / TEST_DATABASE_URL into process.env (default true). */
+  setEnv?: boolean;
+};
+type EnsureResult = {
+  databaseUrl: string;
+  databaseName: string;
+  roleName: string;
+  repoSlug: string;
+  worktreeSlug: string;
+  pathHash: string;
+  root: string;
+  mode: DbMode;
+  port: number;
+  dispose: () => Promise<void>;
+};
+/**
+ * Ensure a worktree-scoped database exists 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 = {
+  status: "skipped";
+  reason: "disabled";
+} | {
+  status: "skipped";
+  reason: "external-url";
+  databaseUrl: string;
+} | ({
+  status: "ensured";
+} & EnsureResult);
+/**
+ * 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.
+ */
+declare function ensureIfNeeded(options: EnsureIfNeededOptions): Promise<EnsureIfNeededResult>;
+type DisposeOptions = {
+  root?: string;
+  mode?: DbMode;
+};
+type DisposeResult = {
+  dropped: true;
+  databaseName: 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).
+ * 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.
+ */
+declare function gc(): Promise<{
+  dropped: string[];
+}>;
+//#endregion
+//#region src/providers/autopg.d.ts
+type AutopgDiscovery = {
+  port: number;
+  adminUrl: string;
+  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";
+declare function resolveAutopgBin(): string | null;
+declare function requireAutopgBin(): string;
+/**
+ * Parse `autopg status --json` output. Requires a numeric port and running !== false.
+ */
+declare function parseHostStatus(json: string): {
+  port: number;
+};
+/**
+ * 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).
+ */
+declare function rolePasswordFor(databaseName: string): string;
+declare function buildDatabaseUrl(opts: {
+  port: number;
+  databaseName: string;
+  roleName: string;
+  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 };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { C as buildDatabaseName, S as readLease, _ as isCedarPgManagedUrl, a as urlFromLease, b as isOrphanLease, c as buildDatabaseUrl, d as parseHostStatus, f as requireAutopgBin, g as resolveWorktreeIdentity, h as resolveRoot, i as gc, l as discoverHost, m as rolePasswordFor, n as ensure, o as INSTALL_HINT, p as resolveAutopgBin, r as ensureIfNeeded, s as ROLE_PASSWORD_SCHEME, t as dispose, u as ensureHostRunning, v as isExternalDatabaseEscapeHatch, w as buildRoleName, x as parseLease, y as resolveEnsureSkip } from "./lifecycle-PbTXNC2Z.mjs";
+export { INSTALL_HINT, ROLE_PASSWORD_SCHEME, buildDatabaseName, buildDatabaseUrl, buildRoleName, discoverHost, dispose, ensure, ensureHostRunning, ensureIfNeeded, gc, isCedarPgManagedUrl, isExternalDatabaseEscapeHatch, isOrphanLease, parseHostStatus, parseLease, readLease, requireAutopgBin, resolveAutopgBin, resolveEnsureSkip, resolveRoot, resolveWorktreeIdentity, rolePasswordFor, urlFromLease };

package/dist/jest.cjs

@@ -0,0 +1,28 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+const require_lifecycle = require("./lifecycle-D10usEjM.cjs");
+//#region src/adapters/jest.ts
+/**
+* Jest globalSetup — call from jest config:
+* ```js
+* globalSetup: require.resolve('@cedarjs/pg/jest')
+* ```
+* Pair with `teardown` from this module as globalTeardown.
+*/
+async function globalSetup() {
+	await require_lifecycle.ensureIfNeeded({
+		mode: "test",
+		setEnv: true
+	});
+}
+/** Lease-gated dispose — no skip re-check (env may flip mid-suite). */
+async function teardown() {
+	await require_lifecycle.dispose({ mode: "test" });
+}
+//#endregion
+exports.default = globalSetup;
+exports.teardown = teardown;
+
+//# sourceMappingURL=jest.cjs.map

package/dist/jest.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"jest.cjs","names":["ensureIfNeeded","dispose"],"sources":["../src/adapters/jest.ts"],"sourcesContent":["import { dispose, ensureIfNeeded } from \"../core/lifecycle.ts\";\n\n/**\n * Jest globalSetup — call from jest config:\n * ```js\n * globalSetup: require.resolve('@cedarjs/pg/jest')\n * ```\n * Pair with `teardown` from this module as globalTeardown.\n */\nexport default async function globalSetup(): Promise<void> {\n  await ensureIfNeeded({\n    mode: \"test\",\n    setEnv: true,\n  });\n}\n\n/** Lease-gated dispose — no skip re-check (env may flip mid-suite). */\nexport async function teardown(): Promise<void> {\n  await dispose({ mode: \"test\" });\n}\n"],"mappings":";;;;;;;;;;;;;AASA,eAA8B,cAA6B;CACzD,MAAMA,kBAAAA,eAAe;EACnB,MAAM;EACN,QAAQ;CACV,CAAC;AACH;;AAGA,eAAsB,WAA0B;CAC9C,MAAMC,kBAAAA,QAAQ,EAAE,MAAM,OAAO,CAAC;AAChC"}

package/dist/jest.d.cts

@@ -0,0 +1,14 @@
+//#region src/adapters/jest.d.ts
+/**
+ * Jest globalSetup — call from jest config:
+ * ```js
+ * globalSetup: require.resolve('@cedarjs/pg/jest')
+ * ```
+ * Pair with `teardown` from this module as globalTeardown.
+ */
+declare function globalSetup(): Promise<void>;
+/** Lease-gated dispose — no skip re-check (env may flip mid-suite). */
+declare function teardown(): Promise<void>;
+//#endregion
+export { globalSetup as default, teardown };
+//# sourceMappingURL=jest.d.cts.map

package/dist/jest.d.mts

@@ -0,0 +1,14 @@
+//#region src/adapters/jest.d.ts
+/**
+ * Jest globalSetup — call from jest config:
+ * ```js
+ * globalSetup: require.resolve('@cedarjs/pg/jest')
+ * ```
+ * Pair with `teardown` from this module as globalTeardown.
+ */
+declare function globalSetup(): Promise<void>;
+/** Lease-gated dispose — no skip re-check (env may flip mid-suite). */
+declare function teardown(): Promise<void>;
+//#endregion
+export { globalSetup as default, teardown };
+//# sourceMappingURL=jest.d.mts.map

package/dist/jest.mjs

@@ -0,0 +1,23 @@
+import { r as ensureIfNeeded, t as dispose } from "./lifecycle-PbTXNC2Z.mjs";
+//#region src/adapters/jest.ts
+/**
+* Jest globalSetup — call from jest config:
+* ```js
+* globalSetup: require.resolve('@cedarjs/pg/jest')
+* ```
+* Pair with `teardown` from this module as globalTeardown.
+*/
+async function globalSetup() {
+	await ensureIfNeeded({
+		mode: "test",
+		setEnv: true
+	});
+}
+/** Lease-gated dispose — no skip re-check (env may flip mid-suite). */
+async function teardown() {
+	await dispose({ mode: "test" });
+}
+//#endregion
+export { globalSetup as default, teardown };
+
+//# sourceMappingURL=jest.mjs.map

package/dist/jest.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"jest.mjs","names":[],"sources":["../src/adapters/jest.ts"],"sourcesContent":["import { dispose, ensureIfNeeded } from \"../core/lifecycle.ts\";\n\n/**\n * Jest globalSetup — call from jest config:\n * ```js\n * globalSetup: require.resolve('@cedarjs/pg/jest')\n * ```\n * Pair with `teardown` from this module as globalTeardown.\n */\nexport default async function globalSetup(): Promise<void> {\n  await ensureIfNeeded({\n    mode: \"test\",\n    setEnv: true,\n  });\n}\n\n/** Lease-gated dispose — no skip re-check (env may flip mid-suite). */\nexport async function teardown(): Promise<void> {\n  await dispose({ mode: \"test\" });\n}\n"],"mappings":";;;;;;;;;AASA,eAA8B,cAA6B;CACzD,MAAM,eAAe;EACnB,MAAM;EACN,QAAQ;CACV,CAAC;AACH;;AAGA,eAAsB,WAA0B;CAC9C,MAAM,QAAQ,EAAE,MAAM,OAAO,CAAC;AAChC"}