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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (129) hide show
  1. package/README.md +361 -89
  2. package/dist/cli.cjs +131 -35
  3. package/dist/cli.cjs.map +1 -1
  4. package/dist/cli.mjs +118 -22
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/dev-env.cjs +12 -0
  7. package/dist/dev-env.cjs.map +1 -0
  8. package/dist/dev-env.d.cts +1 -0
  9. package/dist/dev-env.d.mts +1 -0
  10. package/dist/dev-env.mjs +14 -0
  11. package/dist/dev-env.mjs.map +1 -0
  12. package/dist/index.cjs +51 -10
  13. package/dist/index.cjs.map +1 -0
  14. package/dist/index.d.cts +198 -84
  15. package/dist/index.d.mts +198 -84
  16. package/dist/index.mjs +32 -2
  17. package/dist/index.mjs.map +1 -0
  18. package/dist/jest-teardown.cjs +18 -0
  19. package/dist/jest-teardown.cjs.map +1 -0
  20. package/dist/jest-teardown.d.cts +13 -0
  21. package/dist/jest-teardown.d.mts +14 -0
  22. package/dist/jest-teardown.mjs +18 -0
  23. package/dist/jest-teardown.mjs.map +1 -0
  24. package/dist/jest-template.cjs +44 -0
  25. package/dist/jest-template.cjs.map +1 -0
  26. package/dist/jest-template.d.cts +31 -0
  27. package/dist/jest-template.d.mts +31 -0
  28. package/dist/jest-template.mjs +38 -0
  29. package/dist/jest-template.mjs.map +1 -0
  30. package/dist/jest.cjs +12 -15
  31. package/dist/jest.cjs.map +1 -1
  32. package/dist/jest.d.cts +10 -7
  33. package/dist/jest.d.mts +10 -6
  34. package/dist/jest.mjs +12 -10
  35. package/dist/jest.mjs.map +1 -1
  36. package/dist/lease-B3TuX92y.d.mts +24 -0
  37. package/dist/lease-DS1SX8U_.mjs +221 -0
  38. package/dist/lease-DS1SX8U_.mjs.map +1 -0
  39. package/dist/lease-WlmOnNDi.cjs +310 -0
  40. package/dist/lease-WlmOnNDi.cjs.map +1 -0
  41. package/dist/lease-t4I9JahV.d.cts +24 -0
  42. package/dist/lifecycle-BbrvFQvg.cjs +953 -0
  43. package/dist/lifecycle-BbrvFQvg.cjs.map +1 -0
  44. package/dist/lifecycle-BvIx0xqq.mjs +781 -0
  45. package/dist/lifecycle-BvIx0xqq.mjs.map +1 -0
  46. package/dist/load-dev-env-BULkXyen.mjs +10 -0
  47. package/dist/load-dev-env-BULkXyen.mjs.map +1 -0
  48. package/dist/load-dev-env-Bl6Ddv1U.cjs +15 -0
  49. package/dist/load-dev-env-Bl6Ddv1U.cjs.map +1 -0
  50. package/dist/load-mode-env-CX9vd56X.cjs +39 -0
  51. package/dist/load-mode-env-CX9vd56X.cjs.map +1 -0
  52. package/dist/load-mode-env-Ce9ujisN.mjs +28 -0
  53. package/dist/load-mode-env-Ce9ujisN.mjs.map +1 -0
  54. package/dist/load-test-env-BqtA6V-d.mjs +18 -0
  55. package/dist/load-test-env-BqtA6V-d.mjs.map +1 -0
  56. package/dist/load-test-env-Dcgh6YHV.cjs +23 -0
  57. package/dist/load-test-env-Dcgh6YHV.cjs.map +1 -0
  58. package/dist/naming-C2nGVxPk.d.cts +39 -0
  59. package/dist/naming-C2nGVxPk.d.mts +39 -0
  60. package/dist/nx.cjs +25 -18
  61. package/dist/nx.cjs.map +1 -1
  62. package/dist/nx.d.cts +9 -20
  63. package/dist/nx.d.mts +9 -20
  64. package/dist/nx.mjs +18 -18
  65. package/dist/nx.mjs.map +1 -1
  66. package/dist/status-4Uz6A3LB.cjs +31 -0
  67. package/dist/status-4Uz6A3LB.cjs.map +1 -0
  68. package/dist/status-Dcnpgnlz.mjs +26 -0
  69. package/dist/status-Dcnpgnlz.mjs.map +1 -0
  70. package/dist/studio-DIFw1qWC.mjs +173 -0
  71. package/dist/studio-DIFw1qWC.mjs.map +1 -0
  72. package/dist/studio-oJE30_PO.cjs +208 -0
  73. package/dist/studio-oJE30_PO.cjs.map +1 -0
  74. package/dist/tasks-CNHvvlsN.cjs +67 -0
  75. package/dist/tasks-CNHvvlsN.cjs.map +1 -0
  76. package/dist/tasks-CjaZRi_G.d.mts +19 -0
  77. package/dist/tasks-D5iWIdlo.mjs +38 -0
  78. package/dist/tasks-D5iWIdlo.mjs.map +1 -0
  79. package/dist/tasks-DdQoP9We.d.cts +19 -0
  80. package/dist/template-BiJ-0TIF.mjs +88 -0
  81. package/dist/template-BiJ-0TIF.mjs.map +1 -0
  82. package/dist/template-CXMpODzK.cjs +105 -0
  83. package/dist/template-CXMpODzK.cjs.map +1 -0
  84. package/dist/template-mode-BTUsdBtA.mjs +94 -0
  85. package/dist/template-mode-BTUsdBtA.mjs.map +1 -0
  86. package/dist/template-mode-CzyVwHsi.d.cts +31 -0
  87. package/dist/template-mode-CzyVwHsi.d.mts +31 -0
  88. package/dist/template-mode-JTOxrEgE.cjs +105 -0
  89. package/dist/template-mode-JTOxrEgE.cjs.map +1 -0
  90. package/dist/test-env.cjs +16 -0
  91. package/dist/test-env.cjs.map +1 -0
  92. package/dist/test-env.d.cts +1 -0
  93. package/dist/test-env.d.mts +1 -0
  94. package/dist/test-env.mjs +18 -0
  95. package/dist/test-env.mjs.map +1 -0
  96. package/dist/vite-plus.cjs +113 -35
  97. package/dist/vite-plus.cjs.map +1 -1
  98. package/dist/vite-plus.d.cts +26 -46
  99. package/dist/vite-plus.d.mts +26 -46
  100. package/dist/vite-plus.mjs +110 -32
  101. package/dist/vite-plus.mjs.map +1 -1
  102. package/dist/vitest-template.cjs +48 -0
  103. package/dist/vitest-template.cjs.map +1 -0
  104. package/dist/vitest-template.d.cts +31 -0
  105. package/dist/vitest-template.d.mts +31 -0
  106. package/dist/vitest-template.mjs +42 -0
  107. package/dist/vitest-template.mjs.map +1 -0
  108. package/dist/vitest.cjs +10 -10
  109. package/dist/vitest.cjs.map +1 -1
  110. package/dist/vitest.d.cts +7 -3
  111. package/dist/vitest.d.mts +7 -2
  112. package/dist/vitest.mjs +10 -5
  113. package/dist/vitest.mjs.map +1 -1
  114. package/package.json +46 -13
  115. package/scripts/autopg-version +1 -0
  116. package/scripts/ci-install-autopg.sh +73 -0
  117. package/scripts/postinstall.js +35 -9
  118. package/dist/constants-BY97wXjA.mjs +0 -24
  119. package/dist/constants-BY97wXjA.mjs.map +0 -1
  120. package/dist/constants-CNZn5Xro.cjs +0 -41
  121. package/dist/constants-CNZn5Xro.cjs.map +0 -1
  122. package/dist/lifecycle-BGYtVXtx.cjs +0 -743
  123. package/dist/lifecycle-BGYtVXtx.cjs.map +0 -1
  124. package/dist/lifecycle-CT_8AWPv.mjs +0 -577
  125. package/dist/lifecycle-CT_8AWPv.mjs.map +0 -1
  126. package/dist/tasks-13P6tMth.mjs +0 -16
  127. package/dist/tasks-13P6tMth.mjs.map +0 -1
  128. package/dist/tasks-B8ryV9xo.cjs +0 -21
  129. package/dist/tasks-B8ryV9xo.cjs.map +0 -1
package/dist/index.cjs CHANGED
@@ -1,26 +1,67 @@
1
1
  Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
- const require_lifecycle = require("./lifecycle-BGYtVXtx.cjs");
2
+ const require_lifecycle = require("./lifecycle-BbrvFQvg.cjs");
3
+ const require_lease = require("./lease-WlmOnNDi.cjs");
4
+ const require_template = require("./template-CXMpODzK.cjs");
5
+ const require_load_test_env = require("./load-test-env-Dcgh6YHV.cjs");
6
+ const require_load_dev_env = require("./load-dev-env-Bl6Ddv1U.cjs");
7
+ const require_status = require("./status-4Uz6A3LB.cjs");
8
+ //#region src/adapters/acquire-task.ts
9
+ /** Run acquireIfNeeded, then optional afterAcquire (migrate / db:ready). */
10
+ function createAcquireTask(options) {
11
+ return async () => {
12
+ const result = await require_lifecycle.acquireIfNeeded({
13
+ root: options.root,
14
+ mode: options.mode,
15
+ setEnv: options.setEnv !== false,
16
+ force: options.force
17
+ });
18
+ if (result.status !== "acquired" || !options.afterAcquire) return;
19
+ await options.afterAcquire({
20
+ databaseUrl: result.databaseUrl,
21
+ adminUrl: result.adminUrl,
22
+ databaseName: result.databaseName,
23
+ roleName: result.roleName,
24
+ root: result.root,
25
+ mode: result.mode,
26
+ port: result.port
27
+ });
28
+ };
29
+ }
30
+ //#endregion
31
+ exports.CLI_NAME = require_lease.CLI_NAME;
3
32
  exports.INSTALL_HINT = require_lifecycle.INSTALL_HINT;
4
33
  exports.ROLE_PASSWORD_SCHEME = require_lifecycle.ROLE_PASSWORD_SCHEME;
34
+ exports.STATE_DIRNAME = require_lease.STATE_DIRNAME;
35
+ exports.acquire = require_lifecycle.acquire;
36
+ exports.acquireIfNeeded = require_lifecycle.acquireIfNeeded;
37
+ exports.applyDatabaseUrlEnv = require_lifecycle.applyDatabaseUrlEnv;
38
+ exports.buildCloneDatabaseName = require_lifecycle.buildCloneDatabaseName;
5
39
  exports.buildDatabaseName = require_lifecycle.buildDatabaseName;
6
40
  exports.buildDatabaseUrl = require_lifecycle.buildDatabaseUrl;
7
41
  exports.buildRoleName = require_lifecycle.buildRoleName;
42
+ exports.cloneFromTemplate = require_template.cloneFromTemplate;
43
+ exports.cloneFromTemplateIfNeeded = require_template.cloneFromTemplateIfNeeded;
44
+ exports.createAcquireTask = createAcquireTask;
8
45
  exports.discoverHost = require_lifecycle.discoverHost;
9
46
  exports.dispose = require_lifecycle.dispose;
10
- exports.ensure = require_lifecycle.ensure;
11
- exports.ensureHostRunning = require_lifecycle.ensureHostRunning;
12
- exports.ensureIfNeeded = require_lifecycle.ensureIfNeeded;
47
+ exports.envFilePath = require_lease.envFilePath;
13
48
  exports.gc = require_lifecycle.gc;
14
49
  exports.isCedarPgManagedUrl = require_lifecycle.isCedarPgManagedUrl;
15
50
  exports.isExternalDatabaseEscapeHatch = require_lifecycle.isExternalDatabaseEscapeHatch;
16
- exports.isOrphanLease = require_lifecycle.isOrphanLease;
51
+ exports.isOrphanLease = require_lease.isOrphanLease;
52
+ exports.loadDevEnv = require_load_dev_env.loadDevEnv;
53
+ exports.loadTestEnv = require_load_test_env.loadTestEnv;
54
+ exports.markTemplate = require_template.markTemplate;
17
55
  exports.parseHostStatus = require_lifecycle.parseHostStatus;
18
- exports.parseLease = require_lifecycle.parseLease;
19
- exports.readLease = require_lifecycle.readLease;
56
+ exports.parseLease = require_lease.parseLease;
57
+ exports.readLease = require_lease.readLease;
20
58
  exports.requireAutopgBin = require_lifecycle.requireAutopgBin;
59
+ exports.resolveAcquireSkip = require_lifecycle.resolveAcquireSkip;
21
60
  exports.resolveAutopgBin = require_lifecycle.resolveAutopgBin;
22
- exports.resolveEnsureSkip = require_lifecycle.resolveEnsureSkip;
23
- exports.resolveRoot = require_lifecycle.resolveRoot;
24
- exports.resolveWorktreeIdentity = require_lifecycle.resolveWorktreeIdentity;
61
+ exports.resolveDevStatus = require_status.resolveDevStatus;
62
+ exports.resolveRoot = require_lease.resolveRoot;
63
+ exports.resolveWorktreeIdentity = require_lease.resolveWorktreeIdentity;
25
64
  exports.rolePasswordFor = require_lifecycle.rolePasswordFor;
26
65
  exports.urlFromLease = require_lifecycle.urlFromLease;
66
+
67
+ //# sourceMappingURL=index.cjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.cjs","names":["acquireIfNeeded"],"sources":["../src/adapters/acquire-task.ts"],"sourcesContent":["import { acquireIfNeeded, type AcquireResult } from \"../core/lifecycle.ts\";\nimport type { DbMode } from \"../core/naming.ts\";\n\nexport type AcquireTaskContext = Pick<\n AcquireResult,\n \"databaseUrl\" | \"adminUrl\" | \"databaseName\" | \"roleName\" | \"root\" | \"mode\" | \"port\"\n>;\n\nexport type CreateAcquireTaskOptions = {\n mode: DbMode;\n root?: string;\n /** Ignore external-URL escape hatch (`CEDAR_PG_FORCE=1` also works). */\n force?: boolean;\n setEnv?: boolean;\n /** App-owned migrate/seed after a successful acquire. */\n afterAcquire?: (ctx: AcquireTaskContext) => void | Promise<void>;\n};\n\n/** Run acquireIfNeeded, then optional afterAcquire (migrate / db:ready). */\nexport function createAcquireTask(options: CreateAcquireTaskOptions): () => Promise<void> {\n return async () => {\n const result = await acquireIfNeeded({\n root: options.root,\n mode: options.mode,\n setEnv: options.setEnv !== false,\n force: options.force,\n });\n if (result.status !== \"acquired\" || !options.afterAcquire) return;\n await options.afterAcquire({\n databaseUrl: result.databaseUrl,\n adminUrl: result.adminUrl,\n databaseName: result.databaseName,\n roleName: result.roleName,\n root: result.root,\n mode: result.mode,\n port: result.port,\n });\n };\n}\n"],"mappings":";;;;;;;;;AAmBA,SAAgB,kBAAkB,SAAwD;CACxF,OAAO,YAAY;EACjB,MAAM,SAAS,MAAMA,kBAAAA,gBAAgB;GACnC,MAAM,QAAQ;GACd,MAAM,QAAQ;GACd,QAAQ,QAAQ,WAAW;GAC3B,OAAO,QAAQ;EACjB,CAAC;EACD,IAAI,OAAO,WAAW,cAAc,CAAC,QAAQ,cAAc;EAC3D,MAAM,QAAQ,aAAa;GACzB,aAAa,OAAO;GACpB,UAAU,OAAO;GACjB,cAAc,OAAO;GACrB,UAAU,OAAO;GACjB,MAAM,OAAO;GACb,MAAM,OAAO;GACb,MAAM,OAAO;EACf,CAAC;CACH;AACF"}
package/dist/index.d.cts CHANGED
@@ -1,59 +1,10 @@
1
- //#region src/core/worktree.d.ts
2
- type WorktreeIdentity = {
3
- /** Absolute path to the worktree / project root. */
4
- root: string;
5
- /** Basename of the git common dir / main checkout (e.g. `cedar`). */
6
- repoSlug: string;
7
- /** Basename of this worktree directory (e.g. `feat-auth`). */
8
- worktreeSlug: string;
9
- /** First 8 hex chars of sha256(absolute root). */
10
- pathHash: string;
11
- };
12
- /**
13
- * Resolve the project / worktree root.
14
- * Explicit `root` wins (app project path). Otherwise prefer git toplevel, then cwd.
15
- */
16
- declare function resolveRoot(root?: string): string;
17
- /**
18
- * Identify repo + worktree for observable DB naming.
19
- */
20
- declare function resolveWorktreeIdentity(root?: string): WorktreeIdentity;
21
- //#endregion
22
- //#region src/core/naming.d.ts
23
- type DbMode = "dev" | "test";
24
- /**
25
- * Build an observable Postgres database name:
26
- * cpg_<repoSlug>_<worktreeSlug>_<mode>_<pathHash8>
27
- *
28
- * Never drops `mode` or `pathHash`. Truncates slugs to fit ≤63 chars.
29
- */
30
- declare function buildDatabaseName(identity: WorktreeIdentity, mode: DbMode): string;
31
- declare function buildRoleName(databaseName: string): string;
32
- //#endregion
33
- //#region src/core/lease.d.ts
34
- type Lease = {
35
- schemaVersion: 1;
36
- mode: DbMode;
37
- root: string;
38
- repoSlug: string;
39
- worktreeSlug: string;
40
- pathHash: string;
41
- databaseName: string;
42
- roleName: string;
43
- port: number;
44
- pid: number;
45
- createdAt: string;
46
- };
47
- /** Narrow-parse a lease; reject incomplete or wrong-version records. */
48
- declare function parseLease(raw: unknown): Lease | null;
49
- declare function readLease(root: string, mode: DbMode): Lease | null;
50
- declare function isOrphanLease(lease: Lease): boolean;
51
- //#endregion
1
+ 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";
2
+ import { a as readLease, i as parseLease, n as envFilePath, r as isOrphanLease, t as Lease } from "./lease-t4I9JahV.cjs";
52
3
  //#region src/core/policy.d.ts
53
4
  /**
54
- * Shared ensure skip policy for test-runner adapters and Cedar CLI bridges.
5
+ * Shared acquire skip policy for test-runner adapters and Cedar CLI bridges.
55
6
  */
56
- type EnsureSkip = {
7
+ type AcquireSkip = {
57
8
  skip: false;
58
9
  } | {
59
10
  skip: true;
@@ -63,45 +14,55 @@ type EnsureSkip = {
63
14
  reason: "external-url";
64
15
  databaseUrl: string;
65
16
  };
66
- type ResolveEnsureSkipInput = {
17
+ type ResolveAcquireSkipInput = {
67
18
  /** Candidate URL (TEST_DATABASE_URL for tests, DATABASE_URL for dev). */
68
19
  url?: string;
69
20
  /** When true, never skip (CEDAR_PG_FORCE=1). */
70
21
  force?: boolean;
71
22
  /**
72
- * When true, skip ensure entirely.
23
+ * When true, skip acquire entirely.
73
24
  * Defaults from CEDAR_PG=0|false (opt-out adapters). Pass `false` for Cedar opt-in flows.
74
25
  */
75
26
  disabled?: boolean;
76
27
  };
28
+ /**
29
+ * Inject DATABASE_URL (and TEST_DATABASE_URL for test mode) from a resolved URL.
30
+ * Single env path for acquire, clone, and external-url skip.
31
+ */
32
+ declare function applyDatabaseUrlEnv(databaseUrl: string, options?: {
33
+ mode?: "dev" | "test";
34
+ }): void;
77
35
  /**
78
36
  * True when the URL looks like a cedarpg provisioned database (`cpg_*` name/role).
79
- * These must never be treated as an external escape hatch; always re-ensure so
37
+ * These must never be treated as an external escape hatch; always re-acquire so
80
38
  * disposed/stale shell env cannot skip provisioning.
81
39
  */
82
40
  declare function isCedarPgManagedUrl(url: string | undefined): boolean;
83
41
  /**
84
- * True when `url` is a real external database and ensure should be skipped.
85
- * Sqlite `file:` URLs and cedarpg `cpg_*` URLs are not external.
42
+ * True when `url` is a real external database and acquire should be skipped.
43
+ * Sqlite `file:` URLs, cedarpg `cpg_*` URLs, and unset template placeholders
44
+ * are not external.
86
45
  */
87
46
  declare function isExternalDatabaseEscapeHatch(url: string | undefined): boolean;
88
47
  /**
89
- * Decide whether ensure should run.
48
+ * Decide whether acquire should run.
90
49
  * Adapters may call with no args (env defaults). Cedar opt-in should pass `disabled: false`
91
50
  * and the relevant `url` (`DATABASE_URL` or `TEST_DATABASE_URL`).
92
51
  */
93
- declare function resolveEnsureSkip(input?: ResolveEnsureSkipInput): EnsureSkip;
52
+ declare function resolveAcquireSkip(input?: ResolveAcquireSkipInput): AcquireSkip;
94
53
  //#endregion
95
54
  //#region src/core/lifecycle.d.ts
96
55
  declare function urlFromLease(lease: Lease): string;
97
- type EnsureOptions = {
56
+ type AcquireOptions = {
98
57
  root?: string;
99
58
  mode: DbMode;
100
59
  /** Inject DATABASE_URL / TEST_DATABASE_URL into process.env (default true). */
101
60
  setEnv?: boolean;
102
61
  };
103
- type EnsureResult = {
62
+ type AcquireResult = {
104
63
  databaseUrl: string;
64
+ /** Superuser URL for privileged DDL (mark template, CREATE DATABASE … TEMPLATE). */
65
+ adminUrl: string;
105
66
  databaseName: string;
106
67
  roleName: string;
107
68
  repoSlug: string;
@@ -113,14 +74,14 @@ type EnsureResult = {
113
74
  dispose: () => Promise<void>;
114
75
  };
115
76
  /**
116
- * Ensure a worktree-scoped database exists and return connection info.
77
+ * Acquire a worktree-scoped database and return connection info.
117
78
  *
118
79
  * - `dev`: keep DB across restarts.
119
80
  * - `test`: DROP when `dispose()` is awaited (callers / test runners own teardown).
120
81
  */
121
- declare function ensure(options: EnsureOptions): Promise<EnsureResult>;
122
- type EnsureIfNeededOptions = EnsureOptions & ResolveEnsureSkipInput;
123
- type EnsureIfNeededResult = {
82
+ declare function acquire(options: AcquireOptions): Promise<AcquireResult>;
83
+ type AcquireIfNeededOptions = AcquireOptions & ResolveAcquireSkipInput;
84
+ type AcquireIfNeededResult = {
124
85
  status: "skipped";
125
86
  reason: "disabled";
126
87
  } | {
@@ -128,13 +89,13 @@ type EnsureIfNeededResult = {
128
89
  reason: "external-url";
129
90
  databaseUrl: string;
130
91
  } | ({
131
- status: "ensured";
132
- } & EnsureResult);
92
+ status: "acquired";
93
+ } & AcquireResult);
133
94
  /**
134
- * Resolve skip policy then ensure. Single entry for hosts (Cedar CLI, Jest, Vitest).
135
- * On external-url skip, sets DATABASE_URL when `setEnv` is not false.
95
+ * Resolve skip policy then acquire. Single entry for hosts (Cedar CLI, Jest, Vitest).
96
+ * On external-url skip, applies DATABASE_URL / TEST_DATABASE_URL when `setEnv` is not false.
136
97
  */
137
- declare function ensureIfNeeded(options: EnsureIfNeededOptions): Promise<EnsureIfNeededResult>;
98
+ declare function acquireIfNeeded(options: AcquireIfNeededOptions): Promise<AcquireIfNeededResult>;
138
99
  type DisposeOptions = {
139
100
  root?: string;
140
101
  mode?: DbMode;
@@ -142,24 +103,170 @@ type DisposeOptions = {
142
103
  type DisposeResult = {
143
104
  dropped: true;
144
105
  databaseName: string;
106
+ droppedDatabases: string[];
145
107
  } | {
146
108
  dropped: false;
147
109
  reason: "no-lease" | "host-unavailable";
148
110
  };
149
111
  /**
150
- * DROP the worktree database for the given mode (default: test).
151
- * No-ops without a valid lease (never invents a name to DROP).
112
+ * Role-scoped suite teardown: DROP every database owned by the lease role
113
+ * (TEMPLATE + clones), then DROP ROLE and forget the lease. Unsets `IS_TEMPLATE`
114
+ * as needed. This is not per-clone cleanup — use `CloneResult.dropClone` for that.
115
+ * No-ops without a valid lease; never invents a DROP target beyond role ownership.
152
116
  * If the host is unavailable, leaves the lease so dispose/gc can retry.
153
117
  */
154
118
  declare function dispose(options?: DisposeOptions): Promise<DisposeResult>;
155
119
  /**
156
120
  * Drop databases whose registered worktree root no longer exists on disk.
157
- * Registry entries are removed only after a successful DROP.
121
+ * Registry entries are removed only after a successful DROP (owned DBs + lease DB).
158
122
  */
159
123
  declare function gc(): Promise<{
160
124
  dropped: string[];
161
125
  }>;
162
126
  //#endregion
127
+ //#region src/core/template.d.ts
128
+ type MarkTemplateOptions = {
129
+ root?: string;
130
+ mode: DbMode;
131
+ /** Superuser URL from `acquire`; when omitted, discovers/starts the host. */
132
+ adminUrl?: string;
133
+ };
134
+ /**
135
+ * After migrations, mark the leased DB as a PostgreSQL TEMPLATE so workers can clone it.
136
+ * Requires a lease from `acquire` (no datname override).
137
+ */
138
+ declare function markTemplate(options: MarkTemplateOptions): Promise<{
139
+ databaseName: string;
140
+ adminUrl: string;
141
+ }>;
142
+ type CloneFromTemplateOptions = {
143
+ root?: string;
144
+ mode: DbMode;
145
+ /** Superuser URL from `acquire`; when omitted, discovers/starts the host. */
146
+ adminUrl?: string;
147
+ /**
148
+ * Suffix for the clone datname (e.g. Jest worker id).
149
+ * Defaults to `<pid>_<base36 time>`.
150
+ */
151
+ name?: string;
152
+ /**
153
+ * Inject DATABASE_URL / TEST_DATABASE_URL for this clone (default false).
154
+ * Host `cloneFromTemplateIfNeeded` defaults true; worker adapters pass true explicitly.
155
+ */
156
+ setEnv?: boolean;
157
+ };
158
+ type CloneResult = {
159
+ databaseUrl: string;
160
+ adminUrl: string;
161
+ databaseName: string;
162
+ roleName: string;
163
+ templateName: string;
164
+ port: number;
165
+ /**
166
+ * DROP this clone only (leaves TEMPLATE + role if still owned elsewhere).
167
+ * Not suite teardown — use role-scoped `dispose` for that.
168
+ */
169
+ dropClone: () => Promise<void>;
170
+ };
171
+ /**
172
+ * Clone the leased TEMPLATE database via admin (`CREATE DATABASE … TEMPLATE`).
173
+ * Reuses the template role so `databaseUrl` passwords stay valid (scheme v2).
174
+ * Provider rejects when the leased DB is not marked TEMPLATE.
175
+ * Port comes from the lease; admin URL is passed through or rediscovered.
176
+ */
177
+ declare function cloneFromTemplate(options: CloneFromTemplateOptions): Promise<CloneResult>;
178
+ type CloneFromTemplateIfNeededOptions = CloneFromTemplateOptions & ResolveAcquireSkipInput;
179
+ type CloneFromTemplateIfNeededResult = {
180
+ status: "skipped";
181
+ reason: "disabled";
182
+ } | {
183
+ status: "skipped";
184
+ reason: "external-url";
185
+ databaseUrl: string;
186
+ } | ({
187
+ status: "cloned";
188
+ } & CloneResult);
189
+ /**
190
+ * Resolve skip policy then clone. Host entry for worker adapters (same skip
191
+ * semantics as `acquireIfNeeded`). Defaults `setEnv` on for skip and clone paths.
192
+ */
193
+ declare function cloneFromTemplateIfNeeded(options: CloneFromTemplateIfNeededOptions): Promise<CloneFromTemplateIfNeededResult>;
194
+ //#endregion
195
+ //#region src/core/constants.d.ts
196
+ /**
197
+ * Product identity vs frozen crypto.
198
+ *
199
+ * State dirs follow the CLI name (`.cedarpg`): product-owned, not nested under
200
+ * autopg's `~/.autopg/` (host owns that) and not a generic `.pg` (collision-prone).
201
+ * Password salt is an opaque crypto constant; bump ROLE_PASSWORD_SCHEME to change it.
202
+ */
203
+ /** User-facing CLI binary (`package.json` bin) and log prefix */
204
+ declare const CLI_NAME = "cedarpg";
205
+ /**
206
+ * Worktree-local state dir and home-registry parent (`~/.cedarpg/registry`).
207
+ * Frozen for lease/gc discovery after first alpha consumers appear.
208
+ */
209
+ declare const STATE_DIRNAME = ".cedarpg";
210
+ //#endregion
211
+ //#region src/adapters/load-mode-env.d.ts
212
+ type LoadModeEnvOptions = {
213
+ root?: string;
214
+ /** Overwrite existing `process.env` keys (default: only fill undefined). */
215
+ overwrite?: boolean;
216
+ };
217
+ //#endregion
218
+ //#region src/adapters/load-test-env.d.ts
219
+ type LoadTestEnvOptions = LoadModeEnvOptions;
220
+ /**
221
+ * Load `.cedarpg/test.env` into `process.env` (worker-side).
222
+ *
223
+ * Jest (and optional Vitest `setupFiles`) run tests in a different process than
224
+ * `globalSetup`, so `setEnv` in acquire does not reach workers — the env file does.
225
+ *
226
+ * No-ops unless a matching `test.json` lease exists, so a leftover env after dispose
227
+ * cannot inject a dropped DATABASE_URL.
228
+ */
229
+ declare function loadTestEnv(rootOrOptions?: string | LoadTestEnvOptions): void;
230
+ //#endregion
231
+ //#region src/adapters/load-dev-env.d.ts
232
+ type LoadDevEnvOptions = LoadModeEnvOptions;
233
+ /** Load `.cedarpg/dev.env` into `process.env`. Use `{ overwrite: true }` to beat `.env`. */
234
+ declare function loadDevEnv(rootOrOptions?: string | LoadDevEnvOptions): void;
235
+ //#endregion
236
+ //#region src/adapters/acquire-task.d.ts
237
+ type AcquireTaskContext = Pick<AcquireResult, "databaseUrl" | "adminUrl" | "databaseName" | "roleName" | "root" | "mode" | "port">;
238
+ type CreateAcquireTaskOptions = {
239
+ mode: DbMode;
240
+ root?: string;
241
+ /** Ignore external-URL escape hatch (`CEDAR_PG_FORCE=1` also works). */
242
+ force?: boolean;
243
+ setEnv?: boolean;
244
+ /** App-owned migrate/seed after a successful acquire. */
245
+ afterAcquire?: (ctx: AcquireTaskContext) => void | Promise<void>;
246
+ };
247
+ /** Run acquireIfNeeded, then optional afterAcquire (migrate / db:ready). */
248
+ declare function createAcquireTask(options: CreateAcquireTaskOptions): () => Promise<void>;
249
+ //#endregion
250
+ //#region src/core/status.d.ts
251
+ type ResolveDevStatusOptions = {
252
+ root?: string;
253
+ mode?: DbMode;
254
+ };
255
+ type DevStatus = {
256
+ ok: true;
257
+ mode: DbMode;
258
+ root: string;
259
+ lease: Lease;
260
+ databaseUrl: string;
261
+ envPath: string;
262
+ } | {
263
+ ok: false;
264
+ mode: DbMode;
265
+ root: string;
266
+ };
267
+ /** Read-only lease snapshot for CLI / Vite panel (no acquire, no host). */
268
+ declare function resolveDevStatus(options?: ResolveDevStatusOptions): DevStatus;
269
+ //#endregion
163
270
  //#region src/providers/autopg.d.ts
164
271
  type AutopgDiscovery = {
165
272
  port: number;
@@ -167,29 +274,36 @@ type AutopgDiscovery = {
167
274
  bin: string;
168
275
  };
169
276
  declare const INSTALL_HINT: string;
170
- /** Password scheme v1: sha256(PASSWORD_SALT_PREFIX + "\\0" + databaseName) hex[:32]. Frozen for URL rebuild. */
171
- declare const ROLE_PASSWORD_SCHEME: "v1";
277
+ /** Password scheme v2: sha256(PASSWORD_SALT_PREFIX + "\\0" + roleName) hex[:32]. Frozen for URL rebuild. */
278
+ declare const ROLE_PASSWORD_SCHEME: "v2";
172
279
  declare function resolveAutopgBin(): string | null;
173
280
  declare function requireAutopgBin(): string;
174
281
  /**
175
- * Parse `autopg status --json` output. Requires a numeric port and running !== false.
282
+ * Parse `autopg status --json` → the **registered** port. Throws only when the
283
+ * output is not autopg status JSON.
284
+ *
285
+ * Registration is not liveness: autopg reports a port for a stopped host too,
286
+ * and its `status` string is supervisor-specific (pm2 `online`, systemd-user /
287
+ * launchd differ). Liveness is a TCP accept on the port, proven by the caller —
288
+ * `acquire` does that before it connects.
176
289
  */
177
290
  declare function parseHostStatus(json: string): {
178
291
  port: number;
179
292
  };
180
293
  /**
181
- * Discover a live autopg host via `autopg status --json`. Throws if the host is not proven live.
294
+ * Discover the registered autopg host (port + admin URL) via `autopg status --json`.
295
+ * Throws when autopg cannot be queried; does **not** prove a listener — probe TCP
296
+ * (or use `acquire`, which does) before connecting.
182
297
  */
183
298
  declare function discoverHost(bin?: string): AutopgDiscovery;
184
- /**
185
- * Ensure the host postmaster is up. Runs `autopg install` only after status fails, then re-discovers.
186
- */
187
- declare function ensureHostRunning(bin?: string): AutopgDiscovery;
188
299
  /**
189
300
  * Deterministic local-only password for an app role (Prisma/TCP need it;
190
301
  * autopg hba uses `password` for 127.0.0.1).
302
+ *
303
+ * Keyed by `roleName` (not databaseName) so TEMPLATE clones that reuse the
304
+ * same role keep working when `buildDatabaseUrl` is called with a new database.
191
305
  */
192
- declare function rolePasswordFor(databaseName: string): string;
306
+ declare function rolePasswordFor(roleName: string): string;
193
307
  declare function buildDatabaseUrl(opts: {
194
308
  port: number;
195
309
  databaseName: string;
@@ -197,5 +311,5 @@ declare function buildDatabaseUrl(opts: {
197
311
  password?: string;
198
312
  }): string;
199
313
  //#endregion
200
- 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 };
314
+ 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 DevStatus, type DisposeOptions, type DisposeResult, INSTALL_HINT, type Lease, type LoadDevEnvOptions, type LoadTestEnvOptions, type MarkTemplateOptions, ROLE_PASSWORD_SCHEME, type ResolveAcquireSkipInput, type ResolveDevStatusOptions, 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, resolveDevStatus, resolveRoot, resolveWorktreeIdentity, rolePasswordFor, urlFromLease };
201
315
  //# sourceMappingURL=index.d.cts.map