@rawsql-ts/ztd-cli 0.15.0 → 0.16.0

package/templates/AGENTS.md

@@ -4,7 +4,7 @@ This application uses **Zero Table Dependency (ZTD)** as an internal development
 ZTD is not part of the application's runtime behavior; rather, it provides a framework for:
 
 - Maintaining consistent SQL across the project
-- Keeping schema, domain specifications, and enums synchronized
+- Keeping schema metadata and generated artifacts synchronized
 - Ensuring deterministic SQL unit tests
 - Enabling structured collaboration between humans and AI
 
@@ -36,6 +36,7 @@ After any code change, TypeScript type checking **must** be performed and must p
 - If generated files are involved, run generators first, then re-run typecheck.
 - If typecheck fails, fix errors by root cause, not only the first reported error.
 - A change is not considered complete unless typecheck is green.
+CI pipelines SHOULD run `npx ztd ztd-config` before typecheck and tests (recommended).
 
 Rationale:  
 In ZTD-based development, many schema or SQL inconsistencies surface first as TypeScript errors via generated row maps and DTOs.
@@ -47,6 +48,13 @@ Type checking is a primary correctness signal, not an optional step.
 
 The `src/` directory should contain pure TypeScript logic that operates on the row interfaces generated by `tests/generated/ztd-row-map.generated.ts`. Tests should import the row map, repositories should import DTOs, and fixtures must stay under `tests/`. Keep production code decoupled from the generated row map to preserve the distinction between implementation and test scaffolding.
 
+### Runtime dependency boundaries (important)
+
+- Code under `src/` MUST NOT import anything from `tests/` or `tests/generated/`.
+- Generated row-maps are test-only artifacts and MUST NEVER influence runtime behavior.
+- Mapper and writer runtime utilities MUST NOT depend on ZTD internals or generated helpers.
+- All schema compatibility checks (column existence, enum coverage, forbidden columns, etc.) MUST be enforced in tests, never in production code.
+
 ### Repository Classes: What to Care About
 
 #### Scope and Responsibility
@@ -63,15 +71,19 @@ Rules:
 - Tests must call repository methods, not raw SQL files or SQL strings.
 - ZTD fixtures are the only allowed source of database state in tests.
 - A repository change without tests is considered incomplete.
+- Every repository or test modification must be followed by `pnpm --filter <package> test` (replace `<package>` with the template package name).
+  - `tests/support/global-setup.ts` already uses `@testcontainers/postgresql`, so the suite stands up a Postgres container automatically whenever `DATABASE_URL` is absent.
+  - If the suite fails, fix the root cause and rerun the command until it passes before considering the repository change complete.
 
 Rationale:  
 ZTD derives much of its value from deterministic, repository-level tests.
 Without tests, schema drift and SQL inconsistencies cannot be detected.
 
 #### SQL Management
-- Prefer keeping SQL in separate `.sql` files.
-  - If no explicit instruction is given, separate SQL into files by default.
-- Repository classes should reference SQL files by name, not inline long SQL strings.
+- Keep every SELECT statement in a dedicated `.sql` file under `src/sql/` (match the repository name, e.g. `src/sql/user-accounts.sql`).
+  - Load the SQL via `fs.readFileSync` or similar helpers so the repository never embeds long SQL strings inline.
+  - Inline SQL is forbidden unless a human explicitly requests an override; follow the `.sql` file convention by default.
+  - Repository classes should reference those SQL files; the file name should match the repository class or the query method to keep the code/spec alignment clear.
 
 #### Specifications and Documentation
 - If a markdown file with the same base name as the repository or SQL exists, read it before implementation.
@@ -97,6 +109,32 @@ Without tests, schema drift and SQL inconsistencies cannot be detected.
 - Do not introduce intermediate `*Row` types when SQL already returns DTO-compatible shapes.
 - Define separate Row types only when SQL intentionally returns database-shaped (snake_case) rows, and always convert them explicitly.
 
+---
+
+### Mapper + writer guardrails (template-specific)
+
+- In this project, `src/repositories/user-accounts.ts` is the authoritative mapper for the columns defined by the DDL; it MUST enumerate those columns explicitly so downstream logic never infers metadata at runtime.
+- Writer helpers in the same module MUST emit SQL for `public.user_account` only and MUST remain limited to the explicit insert/update/delete helpers shown there; DO NOT introduce ad-hoc schema discovery.
+- `tests/writer-constraints.test.ts` MUST consume `userAccountWriterColumnSets` together with `tests/generated/ztd-row-map.generated.ts` so CUD callers only reference columns that exist on `public.user_account`.
+- When the schema of `public.user_account` changes, update `src/repositories/user-accounts.ts` column metadata, keep `tests/writer-constraints.test.ts` expectations aligned, and re-run `npx ztd ztd-config` so the generated row map stays synchronized with the tests.
+
+#### Writer safety contract (important)
+
+- Allowed:
+  - Insert, update, and delete helpers tied to a single table with explicitly enumerated column sets.
+  - Explicit `RETURNING` clauses that list permitted columns.
+  - Patch-style updates that only touch writable columns listed in `userAccountWriterColumnSets`.
+- Forbidden:
+  - Generic writers that accept arbitrary table or column names.
+  - Runtime schema or enum discovery (e.g., querying `information_schema`) to drive writer column lists.
+  - Writers that embed joins or subqueries beyond simple `RETURNING` clauses.
+If these constraints are insufficient, write the SQL manually.
+
+#### Mapper strictness policy
+
+- Mapping is strict by default: SQL must return exactly the DTO-shaped results that `src/repositories/user-accounts.ts` exposes; missing or mismatched columns are bugs that tests MUST surface.
+- Non-strict behaviors (coercions, key transforms, etc.) MUST be enabled explicitly via named presets or configuration; relying on implicit or silent defaults is prohibited.
+
 ### Sequence / identity column policy (important)
 
 - Sequence / identity columns (auto-generated IDs) are infrastructure concerns.
@@ -133,19 +171,15 @@ Testing under ZTD follows dedicated, directory-scoped rules.
   /ddl
     *.sql               <- physical schema definitions
 
-  /domain-specs
-    *.md                <- one behavioral SELECT per file (one SQL block)
-
-  /enums
-    *.md                <- one enum definition per file (one SQL block)
-
   README.md             <- documentation for the layout
-  AGENTS.md             <- combined guidance for DDL, enums, and specs
+  AGENTS.md             <- combined guidance for DDL
 
 /src                    <- application & repository logic
 /tests                  <- ZTD tests, fixtures, row-maps
 ```
 
+Only `ztd/ddl` is part of the template contract. Do not create or assume any other `ztd` subdirectories unless the project explicitly adds them.
+
 The file `tests/generated/ztd-layout.generated.ts` ensures ZTD CLI always points to the correct directories.
 
 ---
@@ -153,8 +187,7 @@ The file `tests/generated/ztd-layout.generated.ts` ensures ZTD CLI always points
 # Protected directories and edit ownership (important)
 
 - DDL editing is human-led: `ztd/ddl/`
-- Domain specs editing is human-led: `ztd/domain-specs/`
-- Enums editing is human-led: `ztd/enums/`
+- `ztd/ddl` is the sole human-owned directory inside `/ztd`; other directories must not be assumed or created without explicit instructions.
 - Application code is shared ownership: `src/`
 - Tests are shared ownership: `tests/`
   - Detailed test constraints live in `templates/tests/AGENTS.md`.
@@ -169,21 +202,17 @@ Additionally:
 
 ### 1. Humans own the definitions
 - Physical schema (DDL)
-- Domain semantics (domain-specs)
-- Enumerations (enums)
 - Repository interfaces
 
 ### 2. AI assists with implementation
 - Generating repository SQL
 - Updating fixtures
 - Producing intermediate TypeScript structures
-- Ensuring SQL adheres to DDL, enums, and domain-specs
+- Ensuring SQL adheres to DDL
 
 ### 3. ZTD enforces consistency
 ZTD tests verify that:
 - SQL logic matches DDL shapes
-- SQL semantics match domain-specs
-- SQL values match enumerations
 
 If anything diverges, ZTD failures surface immediately and deterministically.
 
@@ -213,11 +242,11 @@ Changing method signatures, adding new repository methods, etc.
 
 1. Modify the repository interface or implementation in `/src`.
 2. Use AI assistance to generate or update the SQL implementation.
-3. If the generated SQL conflicts with domain-specs or enums, update definitions first.
+3. If the generated SQL conflicts with DDL or other human-maintained references, update the authoritative source first.
 4. Run ZTD tests.
 5. Regenerate config if SQL output shape changed.
 
-Flow: Interface to SQL to Specs (if needed) to Tests
+Flow: Interface to SQL to Tests
 
 ---
 
@@ -226,31 +255,19 @@ Bug fixes, refactoring, rewriting queries.
 
 1. Edit SQL inside the repository.
 2. Run ZTD tests.
-3. If intended behavior changes, update the appropriate file in `ztd/domain-specs/`.
+3. If intended behavior changes, coordinate any necessary DDL updates before adjusting dependent code.
 4. Update fixtures as needed.
 5. Regenerate config if result shape changed.
 
-Flow: SQL to Domain-specs to Tests
-
----
-
-# Workflow D - Starting From Enum or Domain Specification Changes
-Business rule changes or conceptual model updates.
-
-Flow: Specs or Enums to SQL to Tests to (DDL if required)
+Flow: SQL to Tests
 
 ---
 
 # Combined Real-World Examples
 
-- Adding a new contract state:
-  enums to domain-spec to SQL to config to tests
-
-- Adding a new table:
-  DDL to config to SQL to fixtures to tests
-
-- Fixing business logic:
-  SQL to domain-spec to tests
+- Adding a new contract state: DDL to SQL to config to tests
+- Adding a new table: DDL to SQL to fixtures/tests
+- Fixing business logic: SQL to tests
 
 ZTD ensures the development always converges into a consistent, validated workflow.
 
@@ -261,8 +278,6 @@ ZTD ensures the development always converges into a consistent, validated workfl
 Humans maintain:
 
 - Schema definitions (`ztd/ddl`)
-- Domain logic definitions (`ztd/domain-specs`)
-- Domain enumerations (`ztd/enums`)
 - Repository interfaces and architectural decisions
 - Acceptance and review of AI-generated patches
 
@@ -274,12 +289,10 @@ Humans decide what is correct.
 
 AI must:
 
-- Use domain-specs as the semantic source of truth
-- Use enums as the canonical vocabulary source
-- Use DDL as the physical structure constraint
-- Generate SQL consistent with all definitions
-- Update fixtures when needed
-- Never modify `ztd/AGENTS.md` or `ztd/README.md` without explicit instruction
+- Use DDL as the physical structure constraint and never assume any additional `ztd` directories exist unless explicitly added.
+- Generate SQL consistent with DDL.
+- Update fixtures when needed.
+- Never modify `ztd/AGENTS.md` or `ztd/README.md` without explicit instruction.
 
 AI decides how to implement, but not what is correct.
 

package/templates/README.md

@@ -5,31 +5,28 @@ This project organizes all SQL‑related artifacts under the `ztd/` directory, s
 ```
 /ztd
   /ddl
-    *.sql            <- schema definitions
-  /domain-specs
-    *.md             <- one behavior per file (one SQL block)
-  /enums
-    *.md             <- one enum per file (one SQL block)
+    *.sql            <- schema definitions (required)
   README.md          <- documentation for the layout
-  AGENTS.md          <- combined guidance for people and agents
+  AGENTS.md          <- combined guidance for DDL
 
 /src                 <- application & repository code
 /tests               <- ZTD tests, fixtures, generated maps
 ```
 
+Only `ztd/ddl` is part of the template contract. Do not create or assume other `ztd` subdirectories unless the project explicitly adds them.
+
 ## Generated files (important)
 
 `tests/generated/` is auto-generated and must never be committed to git.
-
-After cloning the repository (or in a clean environment), run:
+After cloning the repository (or in a clean environment), run (strongly recommended):
 
 ```bash
 npx ztd ztd-config
 ```
 
-If TypeScript reports missing modules or type errors because `tests/generated/` is missing, run `npx ztd ztd-config`.
+If TypeScript reports missing modules or type errors because `tests/generated/` is missing, rerun `npx ztd ztd-config`.
 
-`tests/generated/ztd-layout.generated.ts` declares the directories above so the CLI and your tests always point at the correct files.
+`tests/generated/ztd-layout.generated.ts` declares the directories above so the CLI and your tests always point at the intended files. The authoritative directory remains `ztd/ddl/`; do not read or assume additional `ztd` subdirectories.
 
 ---
 
@@ -60,12 +57,21 @@ export function getSqlClient(): SqlClient {
 
 ---
 
+# Mapper + writer sample
+
+- This scaffold already exposes `src/repositories/user-accounts.ts`, which maps `public.user_account` rows together with optional `public.user_profile` data through `@rawsql-ts/sql-contract/mapper` and emits insert/update/remove helpers via `@rawsql-ts/sql-contract/writer`.
+- The SQL used here is defined in `src/repositories/user-accounts.ts`; the template tests exercise that implementation and `ztd/ddl` is the authoritative source for every column and constraint.
+- Two template tests demonstrate how to run the stitch:
+  - `tests/user-profiles.test.ts` seeds fixtures, executes the query through the mapper, and verifies the DTO shape.
+  - `tests/writer-constraints.test.ts` reads `userAccountWriterColumnSets` plus `tests/generated/ztd-row-map.generated.ts` so writer callers stay within the approved column set when referencing `public.user_account`.
+- Regenerate `tests/generated/ztd-row-map.generated.ts` (`npx ztd ztd-config`) before running the example tests so the row map reflects any schema changes.
+- The example tests require a real PostgreSQL connection via `DATABASE_URL`; they automatically skip when the variable is missing so local tooling stays fast.
+
 # Principles
 
 ### 1. Humans own the *definitions*
 - DDL (physical schema)
-- Domain specifications (business logic -> SQL semantics)
-- Enums (canonical domain values)
+  Only `ztd/ddl` is part of the template contract; other subdirectories should not be assumed.
 
 ### 2. AI owns the *implementation*
 - Repository SQL generation
@@ -75,9 +81,8 @@ export function getSqlClient(): SqlClient {
 
 ### 3. ZTD ensures these stay in sync
 ZTD acts as the consistency layer ensuring:
-- DDL ↔ SQL shape consistency
-- domain-specs ↔ query logic consistency
-- enums ↔ code‑level constants consistency
+- DDL → SQL shape consistency
+- Do not rely on other directories unless the project explicitly adds them.
 
 If any part diverges, ZTD tests fail deterministically.
 
@@ -115,22 +120,22 @@ Different tasks start from different entry points. Choose the workflow that matc
 
 1. Modify the repository interface or class in `/src`.
 2. Allow AI to generate the SQL needed to satisfy the interface.
-3. If the query contradicts domain-specs or enums, update specs first.
+3. If the query contradicts DDL, reconcile the authoritative definition before continuing.
 4. Run ZTD tests to confirm logic is consistent.
 5. Regenerate ZTD config if result shapes changed.
 
 **Flow:**  
-**repository interface -> SQL -> (update specs if needed) -> tests**
+**repository interface -> SQL -> tests**
 
 ---
 
-# Workflow C — Starting From *Repository SQL Logic Changes*  
+# Workflow C — Starting From Repository SQL Logic Changes
 (Fixing a bug, optimizing logic, rewriting a query)
 
 1. Edit SQL inside the repository.
-2. Run existing ZTD tests.
-3. If the intended behavior changes, update `ztd/domain-specs/`.
-4. Update fixtures if necessary.
+2. Run ZTD tests.
+3. If the intended behavior changes, update the DDL before adjusting dependent logic and keep documentation aligned with the confirmed schema.
+4. Update fixtures as necessary.
 5. If SQL result shape changed, run:
 
    ```bash
@@ -138,62 +143,30 @@ Different tasks start from different entry points. Choose the workflow that matc
    ```
 
 **Flow:**  
-**SQL -> domain-specs (if needed) -> fixtures/tests**
-
----
-
-# Workflow D — Starting From *Enums or Domain Spec Changes*  
-(Business rules change, new status added, new definition created)
-
-## For enums:
-
-1. Update the relevant `.md` file under `ztd/enums/`.
-2. Regenerate row-map:
-
-   ```bash
-   npx ztd ztd-config
-   ```
-
-3. Update SQL referencing enum values.
-4. Update domain-specs or repository SQL if behaviors change.
-5. Update fixtures and tests.
-
-## For domain-specs:
-
-1. Modify the `.md` spec in `ztd/domain-specs/`.
-2. Update SQL in `/src` to follow the new semantics.
-3. Update tests and fixtures.
-4. Update DDL only if the new behavior requires schema changes.
-
-**Flow:**  
-**spec/enums -> SQL -> tests -> (DDL if required)**
+**SQL -> fixtures/tests**
 
 ---
 
 # Combined Real‑World Flow Examples
 
 - **Add a new contract status**  
-  enums -> domain-spec -> SQL -> config -> tests
+  DDL -> SQL -> config -> tests
 
 - **Add a new table**  
   DDL -> config -> SQL -> fixtures -> tests
 
 - **Fix business logic**  
-  SQL -> domain-spec -> tests
-
-ZTD ensures all changes converge into the same consistency pipeline.
+  SQL -> tests
 
+ZTD ensures all changes converge into a consistent, validated workflow.
 ---
 
 # Human Responsibilities
 
-Humans maintain:
-
-- Business logic definitions (`domain-specs`)
-- Physical schema (`ddl`)
-- Domain vocabularies (`enums`)
-- High‑level repository interfaces
-- Acceptance of AI-generated changes
+- Humans maintain:
+  - Physical schema (`ddl`)
+  - High‑level repository interfaces
+  - Acceptance of AI-generated changes
 
 Humans decide “what is correct.”
 
@@ -203,12 +176,11 @@ Humans decide “what is correct.”
 
 AI must:
 
-- Use domain-specs as the **semantic source of truth**
-- Use enums as the **canonical vocabulary source**
-- Use DDL as the **physical shape constraint**
-- Generate repository SQL consistent with all three
-- Regenerate fixtures and tests as instructed
-- Never modify `ztd/AGENTS.md` or `ztd/README.md` unless explicitly asked
+  - Use DDL as the **physical shape constraint** and primary source of truth.
+  - Do not assume any additional `ztd` directories exist unless a human explicitly creates them.
+  - Generate repository SQL consistent with DDL and the documented behavior.
+  - Regenerate fixtures and tests as instructed.
+  - Never modify `ztd/AGENTS.md` or `ztd/README.md` unless explicitly asked.
 
 AI decides “how to implement” within those constraints.
 
@@ -237,3 +209,9 @@ ZTD is the verification engine guaranteeing correctness.
 ZTD enables a workflow where **humans define meaning**, **AI writes implementation**, and **tests guarantee correctness**.
 
 The project layout and workflows above ensure long-term maintainability, clarity, and full reproducibility of SQL logic independent of physical database state.
+
+## Recommended local verification
+
+- `npx ztd ztd-config` (Recommended)
+- `pnpm -C packages/ztd-cli test` (Recommended)
+- `templates/tests/user-profiles.test.ts` runs only when `DATABASE_URL` is configured; otherwise it skips automatically.

package/templates/dist/drivers/pg-testkit/src/driver/PgTestkitClient.d.ts

@@ -0,0 +1,38 @@
+import type { QueryResult, QueryResultRow } from 'pg';
+import type { CreatePgTestkitClientOptions, PgQueryInput, PgQueryable, TableRowsFixture } from '../types';
+/**
+ * Lightweight client that rewrites CRUD/SELECT statements into fixture-backed SELECTs
+ * and delegates execution to a real `pg` connection.
+ *
+ * Consumers can use this in place of `pg.Client` during tests; production code can stay
+ * unaware of pg-testkit as long as it relies on the standard `query` API.
+ */
+export declare class PgTestkitClient {
+    private readonly options;
+    private readonly scopedRows?;
+    private connection?;
+    private readonly rewriter;
+    private readonly tableNameResolver;
+    constructor(options: CreatePgTestkitClientOptions, scopedRows?: TableRowsFixture[] | undefined, seedConnection?: PgQueryable);
+    /**
+     * Executes SQL after rewriting it to use fixture-backed CTEs. CRUD statements are converted
+     * to result-producing SELECTs; unsupported DDL is ignored.
+     *
+     * @param textOrConfig SQL text or pg QueryConfig
+     * @param values Optional positional parameters
+     * @returns pg-style QueryResult with rows simulated from fixtures
+     */
+    query<T extends QueryResultRow = QueryResultRow>(textOrConfig: PgQueryInput, values?: unknown[]): Promise<QueryResult<T>>;
+    /**
+     * Derives a scoped client that overlays additional fixtures while reusing the same connection.
+     */
+    withFixtures(fixtures: TableRowsFixture[]): PgTestkitClient;
+    /**
+     * Disposes the underlying connection or returns it to the pool if `release` is available.
+     */
+    close(): Promise<void>;
+    private getConnection;
+    private buildEmptyResult;
+}
+/** Factory that instantiates a `PgTestkitClient` with the provided fixture-driven options. */
+export declare const createPgTestkitClient: (options: CreatePgTestkitClientOptions) => PgTestkitClient;

package/templates/dist/drivers/pg-testkit/src/driver/PgTestkitClient.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPgTestkitClient = exports.PgTestkitClient = void 0;
+const testkit_core_1 = require("@rawsql-ts/testkit-core");
+const fixtureValidation_1 = require("../utils/fixtureValidation");
+const fixtureState_1 = require("../utils/fixtureState");
+/**
+ * Lightweight client that rewrites CRUD/SELECT statements into fixture-backed SELECTs
+ * and delegates execution to a real `pg` connection.
+ *
+ * Consumers can use this in place of `pg.Client` during tests; production code can stay
+ * unaware of pg-testkit as long as it relies on the standard `query` API.
+ */
+class PgTestkitClient {
+    constructor(options, scopedRows, seedConnection) {
+        var _a, _b;
+        this.options = options;
+        this.scopedRows = scopedRows;
+        // Keep a resolver around so every fixture/DDL lookup uses the same schema rules.
+        this.tableNameResolver = new testkit_core_1.TableNameResolver({
+            defaultSchema: options.defaultSchema,
+            searchPath: options.searchPath,
+        });
+        // Align DDL metadata and explicit overrides under the shared resolver rules.
+        const fixturesState = (0, fixtureState_1.resolveFixtureState)({
+            ddl: options.ddl,
+            tableDefinitions: options.tableDefinitions,
+            tableRows: options.tableRows,
+        }, this.tableNameResolver);
+        // Combine the base and scoped fixtures so they are validated exactly once through the resolver.
+        const mergedTableRows = [...((_a = options.tableRows) !== null && _a !== void 0 ? _a : []), ...(scopedRows !== null && scopedRows !== void 0 ? scopedRows : [])];
+        (0, fixtureValidation_1.validateFixtureRowsAgainstTableDefinitions)(mergedTableRows, fixturesState.tableDefinitions, 'tableRows', this.tableNameResolver);
+        const fixtureStore = new testkit_core_1.DefaultFixtureProvider(fixturesState.tableDefinitions, fixturesState.tableRows, this.tableNameResolver);
+        this.rewriter = new testkit_core_1.ResultSelectRewriter(fixtureStore, (_b = options.missingFixtureStrategy) !== null && _b !== void 0 ? _b : 'error', options.formatterOptions, this.tableNameResolver);
+        this.connection = seedConnection;
+    }
+    /**
+     * Executes SQL after rewriting it to use fixture-backed CTEs. CRUD statements are converted
+     * to result-producing SELECTs; unsupported DDL is ignored.
+     *
+     * @param textOrConfig SQL text or pg QueryConfig
+     * @param values Optional positional parameters
+     * @returns pg-style QueryResult with rows simulated from fixtures
+     */
+    async query(textOrConfig, values) {
+        var _a, _b, _c;
+        const sql = typeof textOrConfig === 'string' ? textOrConfig : textOrConfig.text;
+        if (!sql) {
+            throw new Error('Query text is required for pg-testkit execution.');
+        }
+        // Rewrite CRUD and SELECT statements into fixture-backed SELECT queries.
+        const rewritten = this.rewriter.rewrite(sql, this.scopedRows);
+        if (!rewritten.sql) {
+            return this.buildEmptyResult('NOOP');
+        }
+        // Align caller-supplied parameters with the rewritten placeholders to keep numbering contiguous.
+        const incomingParams = typeof textOrConfig === 'string'
+            ? values
+            : (_a = values !== null && values !== void 0 ? values : textOrConfig.values) !== null && _a !== void 0 ? _a : textOrConfig.params;
+        const normalizeResult = (0, testkit_core_1.alignRewrittenParameters)(rewritten.sql, incomingParams);
+        const payload = typeof textOrConfig === 'string'
+            ? normalizeResult.sql
+            : { ...textOrConfig, text: normalizeResult.sql, values: normalizeResult.params };
+        const connection = await this.getConnection();
+        (_c = (_b = this.options).onExecute) === null || _c === void 0 ? void 0 : _c.call(_b, normalizeResult.sql, normalizeResult.params, rewritten.fixturesApplied);
+        const rawResult = typeof payload === 'string'
+            ? await connection.query(payload, normalizeResult.params)
+            : await connection.query(payload);
+        return (0, testkit_core_1.applyCountWrapper)(rawResult, rewritten.sourceCommand, rewritten.isCountWrapper);
+    }
+    /**
+     * Derives a scoped client that overlays additional fixtures while reusing the same connection.
+     */
+    withFixtures(fixtures) {
+        return new PgTestkitClient(this.options, fixtures, this.connection);
+    }
+    /**
+     * Disposes the underlying connection or returns it to the pool if `release` is available.
+     */
+    async close() {
+        if (!this.connection) {
+            return;
+        }
+        const closable = this.connection;
+        this.connection = undefined;
+        if (typeof closable.release === 'function') {
+            closable.release();
+            return;
+        }
+        if (typeof closable.end === 'function') {
+            await closable.end();
+        }
+    }
+    async getConnection() {
+        if (this.connection) {
+            return this.connection;
+        }
+        this.connection = await this.options.connectionFactory();
+        return this.connection;
+    }
+    buildEmptyResult(command) {
+        return {
+            command,
+            rowCount: 0,
+            oid: 0,
+            rows: [],
+            fields: [],
+        };
+    }
+}
+exports.PgTestkitClient = PgTestkitClient;
+/** Factory that instantiates a `PgTestkitClient` with the provided fixture-driven options. */
+const createPgTestkitClient = (options) => {
+    return new PgTestkitClient(options);
+};
+exports.createPgTestkitClient = createPgTestkitClient;
+//# sourceMappingURL=PgTestkitClient.js.map

package/templates/dist/drivers/pg-testkit/src/driver/PgTestkitClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PgTestkitClient.js","sourceRoot":"","sources":["../../../../../../../drivers/pg-testkit/src/driver/PgTestkitClient.ts"],"names":[],"mappings":"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"}

package/templates/dist/drivers/pg-testkit/src/driver/createPgTestkitPool.d.ts

@@ -0,0 +1,4 @@
+import { Pool } from 'pg';
+import type { CreatePgTestkitPoolOptions, TableRowsFixture } from '../types';
+/** Builds a pool whose clients rewrite CRUD traffic through pg-testkit while leaving transactions alone. */
+export declare const createPgTestkitPool: (connectionString: string, ...fixturesOrOptions: Array<TableRowsFixture | CreatePgTestkitPoolOptions>) => Pool;

package/templates/dist/drivers/pg-testkit/src/driver/createPgTestkitPool.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPgTestkitPool = void 0;
+const pg_1 = require("pg");
+const PgTestkitClient_1 = require("./PgTestkitClient");
+const TRANSACTION_COMMAND_RE = /^\s*(BEGIN|COMMIT|ROLLBACK|SAVEPOINT|RELEASE)/i;
+const isPoolOptions = (value) => {
+    return (typeof value === 'object' &&
+        value !== null &&
+        ('ddl' in value || 'tableRows' in value || 'tableDefinitions' in value));
+};
+/** Builds a pool whose clients rewrite CRUD traffic through pg-testkit while leaving transactions alone. */
+const createPgTestkitPool = (connectionString, ...fixturesOrOptions) => {
+    var _a;
+    const hasOptions = fixturesOrOptions.length > 0 && isPoolOptions(fixturesOrOptions[fixturesOrOptions.length - 1]);
+    const poolOptions = hasOptions
+        ? fixturesOrOptions[fixturesOrOptions.length - 1]
+        : undefined;
+    const baseFixtures = hasOptions
+        ? fixturesOrOptions.slice(0, -1)
+        : fixturesOrOptions;
+    // Combine ad-hoc rows with option-provided ones so callers can mix styles.
+    const combinedFixtures = [...baseFixtures, ...((_a = poolOptions === null || poolOptions === void 0 ? void 0 : poolOptions.tableRows) !== null && _a !== void 0 ? _a : [])];
+    class TestkitClient extends pg_1.Client {
+        constructor() {
+            super(...arguments);
+            this.testkit = (0, PgTestkitClient_1.createPgTestkitClient)({
+                connectionFactory: async () => this.buildRawConnection(),
+                tableRows: combinedFixtures,
+                ddl: poolOptions === null || poolOptions === void 0 ? void 0 : poolOptions.ddl,
+                tableDefinitions: poolOptions === null || poolOptions === void 0 ? void 0 : poolOptions.tableDefinitions,
+                defaultSchema: poolOptions === null || poolOptions === void 0 ? void 0 : poolOptions.defaultSchema,
+                searchPath: poolOptions === null || poolOptions === void 0 ? void 0 : poolOptions.searchPath,
+            });
+        }
+        buildRawConnection() {
+            const baseQuery = pg_1.Client.prototype.query;
+            // Forward rewritten SQL to the original pg client so transactional commands stay bound to the pool.
+            const rawConnection = {
+                query: (queryTextOrConfig, values) => baseQuery.call(this, queryTextOrConfig, values),
+            };
+            return rawConnection;
+        }
+        query(...args) {
+            var _a;
+            const [queryTextOrConfig, valuesOrCallback, callbackOrUndefined] = args;
+            const callback = typeof valuesOrCallback === 'function' ? valuesOrCallback : callbackOrUndefined;
+            const values = typeof valuesOrCallback === 'function' ? undefined : valuesOrCallback;
+            const sqlText = typeof queryTextOrConfig === 'string' ? queryTextOrConfig : queryTextOrConfig.text;
+            const configPayload = typeof queryTextOrConfig === 'string' ? undefined : queryTextOrConfig;
+            const normalizedValues = (_a = values !== null && values !== void 0 ? values : configPayload === null || configPayload === void 0 ? void 0 : configPayload.values) !== null && _a !== void 0 ? _a : configPayload === null || configPayload === void 0 ? void 0 : configPayload.params;
+            // Allow explicit transaction control to reach Pg without interference.
+            if (sqlText && TRANSACTION_COMMAND_RE.test(sqlText)) {
+                return pg_1.Client.prototype.query.apply(this, args);
+            }
+            const execution = this.testkit.query(queryTextOrConfig, normalizedValues);
+            // Surface callback behavior when the caller provided the older pg query signature.
+            if (typeof callback === 'function') {
+                execution
+                    .then((result) => callback(null, result))
+                    .catch((error) => callback(error, undefined));
+                return undefined;
+            }
+            return execution;
+        }
+    }
+    const poolConfig = { connectionString, Client: TestkitClient };
+    return new pg_1.Pool(poolConfig);
+};
+exports.createPgTestkitPool = createPgTestkitPool;
+//# sourceMappingURL=createPgTestkitPool.js.map