@rawsql-ts/ztd-cli 0.14.4 → 0.16.0

package/templates/dist/ztd-cli/templates/tests/user-profiles.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-profiles.test.js","sourceRoot":"","sources":["../../../../tests/user-profiles.test.ts"],"names":[],"mappings":";;AAAA,mCAAgD;AAEhD,6EAI2C;AAC3C,6DAA+D;AAC/D,qEAAqE;AAErE,SAAS,iBAAiB;IACxB,OAAO;QACL;YACE,eAAe,EAAE,CAAC;YAClB,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,mBAAmB;YAC1B,YAAY,EAAE,cAAc;YAC5B,UAAU,EAAE,sBAAsB;YAClC,UAAU,EAAE,sBAAsB;SACnC;QACD;YACE,eAAe,EAAE,CAAC;YAClB,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,mBAAmB;YAC1B,YAAY,EAAE,eAAe;YAC7B,UAAU,EAAE,sBAAsB;YAClC,UAAU,EAAE,sBAAsB;SACnC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB;IACxB,OAAO;QACL;YACE,UAAU,EAAE,GAAG;YACf,eAAe,EAAE,CAAC;YAClB,GAAG,EAAE,oCAAoC;YACzC,OAAO,EAAE,qBAAqB;YAC9B,QAAQ,EAAE,IAAI;SACf;KACF,CAAC;AACJ,CAAC;AAED,SAAS,aAAa;IACpB,OAAO;QACL,IAAA,oCAAY,EACV,qBAAqB,EACrB,iBAAiB,EAAE,EACnB,oCAAY,CAAC,qBAAqB,CAAC,CACpC;QACD,IAAA,oCAAY,EACV,qBAAqB,EACrB,iBAAiB,EAAE,EACnB,oCAAY,CAAC,qBAAqB,CAAC,CACpC;KACF,CAAC;AACJ,CAAC;AAED,IAAA,iBAAQ,EAAC,qBAAqB,EAAE,GAAG,EAAE;IACnC,IAAA,aAAI,EAAC,4CAA4C,EAAE,KAAK,IAAI,EAAE;QAC5D,MAAM,QAAQ,GAAG,aAAa,EAAE,CAAC;QACjC,MAAM,MAAM,GAAG,MAAM,IAAA,oCAAmB,EAAC,QAAQ,CAAC,CAAC;QACnD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAA,gCAAgB,EAAC,MAAM,CAAC,CAAC;YAC9C,IAAA,eAAM,EAAC,MAAM,CAAC,CAAC,OAAO,CAAC;gBACrB;oBACE,aAAa,EAAE,CAAC;oBAChB,QAAQ,EAAE,OAAO;oBACjB,KAAK,EAAE,mBAAmB;oBAC1B,WAAW,EAAE,cAAc;oBAC3B,SAAS,EAAE,IAAI,IAAI,CAAC,sBAAsB,CAAC;oBAC3C,SAAS,EAAE,IAAI,IAAI,CAAC,sBAAsB,CAAC;oBAC3C,OAAO,EAAE;wBACP,SAAS,EAAE,GAAG;wBACd,aAAa,EAAE,CAAC;wBAChB,GAAG,EAAE,oCAAoC;wBACzC,OAAO,EAAE,qBAAqB;wBAC9B,QAAQ,EAAE,IAAI;qBACf;iBACF;gBACD;oBACE,aAAa,EAAE,CAAC;oBAChB,QAAQ,EAAE,OAAO;oBACjB,KAAK,EAAE,mBAAmB;oBAC1B,WAAW,EAAE,eAAe;oBAC5B,SAAS,EAAE,IAAI,IAAI,CAAC,sBAAsB,CAAC;oBAC3C,SAAS,EAAE,IAAI,IAAI,CAAC,sBAAsB,CAAC;oBAC3C,OAAO,EAAE,SAAS;iBACnB;aACF,CAAC,CAAC;QACL,CAAC;gBAAS,CAAC;YACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/templates/dist/ztd-cli/templates/tests/writer-constraints.test.d.ts

@@ -0,0 +1 @@
+export {};

package/templates/dist/ztd-cli/templates/tests/writer-constraints.test.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const ztd_row_map_generated_1 = require("./generated/ztd-row-map.generated");
+const user_accounts_1 = require("../src/repositories/user-accounts");
+const userColumns = new Set(Object.keys(ztd_row_map_generated_1.tableSchemas['public.user_account'].columns));
+(0, vitest_1.describe)('user_account writer columns', () => {
+    (0, vitest_1.test)('insert columns must exist on the canonical table', () => {
+        const { insertColumns } = user_accounts_1.userAccountWriterColumnSets;
+        const missing = insertColumns.filter((column) => !userColumns.has(column));
+        (0, vitest_1.expect)(missing).toEqual([]);
+        (0, vitest_1.expect)(insertColumns).toEqual(vitest_1.expect.arrayContaining(['username', 'email', 'display_name']));
+    });
+    (0, vitest_1.test)('update columns stay within allowed set and avoid immutable columns', () => {
+        const { updateColumns, immutableColumns } = user_accounts_1.userAccountWriterColumnSets;
+        const missing = updateColumns.filter((column) => !userColumns.has(column));
+        (0, vitest_1.expect)(missing).toEqual([]);
+        (0, vitest_1.expect)(updateColumns).not.toEqual(vitest_1.expect.arrayContaining([...immutableColumns]));
+    });
+    (0, vitest_1.test)('immutable columns reflect the DDL and are not targetted by updates', () => {
+        const { immutableColumns, updateColumns } = user_accounts_1.userAccountWriterColumnSets;
+        const missing = immutableColumns.filter((column) => !userColumns.has(column));
+        (0, vitest_1.expect)(missing).toEqual([]);
+        immutableColumns.forEach((column) => {
+            (0, vitest_1.expect)(updateColumns).not.toContain(column);
+        });
+    });
+});
+//# sourceMappingURL=writer-constraints.test.js.map

package/templates/dist/ztd-cli/templates/tests/writer-constraints.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer-constraints.test.js","sourceRoot":"","sources":["../../../../tests/writer-constraints.test.ts"],"names":[],"mappings":";;AAAA,mCAAgD;AAChD,6EAAiE;AACjE,qEAAgF;AAEhF,MAAM,WAAW,GAAG,IAAI,GAAG,CACzB,MAAM,CAAC,IAAI,CAAC,oCAAY,CAAC,qBAAqB,CAAC,CAAC,OAAO,CAAC,CACzD,CAAC;AAEF,IAAA,iBAAQ,EAAC,6BAA6B,EAAE,GAAG,EAAE;IAC3C,IAAA,aAAI,EAAC,kDAAkD,EAAE,GAAG,EAAE;QAC5D,MAAM,EAAE,aAAa,EAAE,GAAG,2CAA2B,CAAC;QACtD,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;QAC3E,IAAA,eAAM,EAAC,OAAO,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC5B,IAAA,eAAM,EAAC,aAAa,CAAC,CAAC,OAAO,CAC3B,eAAM,CAAC,eAAe,CAAC,CAAC,UAAU,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,CAC9D,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,IAAA,aAAI,EAAC,oEAAoE,EAAE,GAAG,EAAE;QAC9E,MAAM,EAAE,aAAa,EAAE,gBAAgB,EAAE,GAAG,2CAA2B,CAAC;QACxE,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;QAC3E,IAAA,eAAM,EAAC,OAAO,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC5B,IAAA,eAAM,EAAC,aAAa,CAAC,CAAC,GAAG,CAAC,OAAO,CAC/B,eAAM,CAAC,eAAe,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAC9C,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,IAAA,aAAI,EAAC,oEAAoE,EAAE,GAAG,EAAE;QAC9E,MAAM,EAAE,gBAAgB,EAAE,aAAa,EAAE,GAAG,2CAA2B,CAAC;QACxE,MAAM,OAAO,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;QAC9E,IAAA,eAAM,EAAC,OAAO,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC5B,gBAAgB,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE;YAClC,IAAA,eAAM,EAAC,aAAa,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAC9C,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/templates/dist/ztd-cli/templates/tests/ztd-layout.generated.d.ts

@@ -0,0 +1,7 @@
+declare const _default: {
+    ztdRootDir: string;
+    ddlDir: string;
+    enumsDir: string;
+    domainSpecsDir: string;
+};
+export default _default;

package/templates/dist/ztd-cli/templates/tests/ztd-layout.generated.js

@@ -0,0 +1,10 @@
+"use strict";
+// GENERATED FILE. DO NOT EDIT.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = {
+    ztdRootDir: 'ztd',
+    ddlDir: 'ztd/ddl',
+    enumsDir: 'ztd/enums',
+    domainSpecsDir: 'ztd/domain-specs',
+};
+//# sourceMappingURL=ztd-layout.generated.js.map

package/templates/dist/ztd-cli/templates/tests/ztd-layout.generated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ztd-layout.generated.js","sourceRoot":"","sources":["../../../../tests/ztd-layout.generated.ts"],"names":[],"mappings":";AAAA,+BAA+B;;AAE/B,kBAAe;IACb,UAAU,EAAE,KAAK;IACjB,MAAM,EAAE,SAAS;IACjB,QAAQ,EAAE,WAAW;IACrB,cAAc,EAAE,kBAAkB;CACnC,CAAC"}

package/templates/src/db/sql-client.ts

@@ -10,7 +10,7 @@ export type SqlQueryRows<T> = Promise<T[]>;
  * Minimal SQL client interface required by the repository layer.
  *
  * - Production: adapt `pg` (or other drivers) to normalize results into `T[]`
- * - Tests: compatible with `pg-testkit` clients returned by `createTestkitClient()`
+ * - Tests: compatible with the `testkit-postgres` pipeline exposed by `@rawsql-ts/adapter-node-pg` clients returned by `createTestkitClient()`
  *
  * Connection strategy note:
  * - Prefer a shared client per worker process for performance.

package/templates/src/repositories/user-accounts.ts

@@ -0,0 +1,179 @@
+import type { SqlClient } from '../db/sql-client';
+import { createMapper, entity, toRowsExecutor } from '@rawsql-ts/mapper-core';
+import { insert, Key, remove, update } from '@rawsql-ts/writer-core';
+
+const userAccountTable = 'public.user_account';
+
+type UserProfileRow = {
+  profileId: number;
+  userAccountId: number;
+  bio: string | null;
+  website: string | null;
+  verified: boolean;
+};
+
+/**
+ * DTO that represents a user account with its optional profile information.
+ * @property {number} userAccountId The primary key for the user account.
+ * @property {string} username The canonical username.
+ * @property {string} email The account email address.
+ * @property {string} displayName The account display name.
+ * @property {Date} createdAt When the account was created.
+ * @property {Date} updatedAt When the account was last updated.
+ * @property {UserProfileRow} [profile] Optional profile payload joined from user_profile.
+ */
+export type UserAccountWithProfile = {
+  userAccountId: number;
+  username: string;
+  email: string;
+  displayName: string;
+  createdAt: Date;
+  updatedAt: Date;
+  profile?: UserProfileRow;
+};
+
+// Map the joined profile columns so we can hydrate nested objects later.
+const profileMapping = entity<UserProfileRow>({
+  name: 'userProfile',
+  key: 'profileId',
+  columnMap: {
+    profileId: 'profile_id',
+    userAccountId: 'profile_user_account_id',
+    bio: 'bio',
+    website: 'website',
+    verified: 'verified',
+  },
+});
+
+const userAccountMapping = entity<UserAccountWithProfile>({
+  name: 'userAccount',
+  key: 'userAccountId',
+  columnMap: {
+    userAccountId: 'user_account_id',
+    username: 'username',
+    email: 'email',
+    displayName: 'display_name',
+    createdAt: 'created_at',
+    updatedAt: 'updated_at',
+  },
+}).belongsTo('profile', profileMapping, 'userAccountId', { optional: true });
+
+const userProfilesSql = `
+SELECT
+  u.user_account_id,
+  u.username,
+  u.email,
+  u.display_name,
+  u.created_at,
+  u.updated_at,
+  p.profile_id,
+  p.user_account_id AS profile_user_account_id,
+  p.bio,
+  p.website,
+  p.verified
+FROM public.user_account u
+LEFT JOIN public.user_profile p ON p.user_account_id = u.user_account_id
+ORDER BY u.user_account_id, p.profile_id;
+`;
+
+// Build a mapper that can translate snake_case columns into camelCase DTOs.
+const createMapperForClient = (client: SqlClient) =>
+  createMapper(
+    toRowsExecutor((sql, params: unknown[] = []) =>
+      client.query<Record<string, unknown>>(sql, params),
+    ),
+    {
+      // The explicit column maps enumerate the nested entity columns while keyTransform handles generic snake_to_camel conversions.
+      keyTransform: 'snake_to_camel',
+      coerceDates: true,
+    },
+  );
+
+/**
+ * Queries all user accounts together with their associated profiles.
+ * @param {SqlClient} client Client proxy that executes the mapper SQL.
+ * @returns {Promise<UserAccountWithProfile[]>} The joined account-with-profile rows.
+ */
+export async function listUserProfiles(
+  client: SqlClient,
+): Promise<UserAccountWithProfile[]> {
+  const mapper = createMapperForClient(client);
+  return mapper.query(userProfilesSql, [], userAccountMapping);
+}
+
+/**
+ * Parameters required to insert a new user account.
+ * @property {string} username The requested username.
+ * @property {string} email The requested email address.
+ * @property {string} displayName The requested display name.
+ */
+export type NewUserAccount = {
+  username: string;
+  email: string;
+  displayName: string;
+};
+
+/**
+ * Payload describing the display name change for an existing account.
+ * @property {string} displayName The new display name to persist.
+ */
+export type DisplayNameUpdatePayload = {
+  displayName: string;
+};
+
+/**
+ * Builds an insert statement for the user_account writer.
+ * @param {NewUserAccount} input The normalized fields for the new account.
+ * @returns {ReturnType<typeof insert>} A well-formed insert statement for the user_account writer.
+ */
+export function buildInsertUserAccount(
+  input: NewUserAccount,
+): ReturnType<typeof insert> {
+  return insert(userAccountTable, {
+    username: input.username,
+    email: input.email,
+    display_name: input.displayName,
+  });
+}
+
+/**
+ * Builds an update statement that refreshes the display name and timestamp.
+ * @param {Key} key The unique key identifying the row to update.
+ * @param {DisplayNameUpdatePayload} payload The new display name payload.
+ * @returns {ReturnType<typeof update>} A writer update statement that refreshes the display name and updated_at timestamp.
+ */
+export function buildUpdateDisplayName(
+  key: Key,
+  payload: DisplayNameUpdatePayload,
+): ReturnType<typeof update> {
+  return update(
+    userAccountTable,
+    {
+      // Persist the new display name and bump the timestamp along with it.
+      display_name: payload.displayName,
+      updated_at: new Date(),
+    },
+    key,
+  );
+}
+
+/**
+ * Builds a delete statement for the specified user account key.
+ * @param {Key} key Identifies the row to remove.
+ * @returns {ReturnType<typeof remove>} A writer delete statement for the matching user account.
+ */
+export function buildRemoveUserAccount(key: Key): ReturnType<typeof remove> {
+  return remove(userAccountTable, key);
+}
+
+/**
+ * Column sets that writer tests use to ensure only approved columns are touched.
+ * @property {readonly string[]} insertColumns Columns allowed for new account inserts.
+ * @property {readonly string[]} updateColumns Columns permitted during updates.
+ * @property {readonly string[]} immutableColumns Columns that must remain unchanged.
+ */
+export const userAccountWriterColumnSets = {
+  insertColumns: ['username', 'email', 'display_name'] as const,
+  updateColumns: ['display_name', 'updated_at'] as const,
+  immutableColumns: ['user_account_id', 'created_at'] as const,
+};

package/templates/tests/AGENTS.md

@@ -8,9 +8,21 @@ Tests are a shared workspace for humans and AI, but must respect ZTD-specific co
 ## Default execution mode (important)
 
 - The default execution mode for tests is **ZTD**.
+- ZTD tests run through the new `createTestkitProvider` helper, which keeps a single
+  shared backend connection per worker and wraps each scenario in a rollback
+  transaction by default.
 - Do not switch to Traditional mode unless explicitly instructed by a human.
 - Do not set `ZTD_EXECUTION_MODE=traditional` or pass `{ mode: "traditional" }` to `createTestkitClient()` without explicit instruction.
+- When you need session-level changes (temporary tables, `SET` commands, etc.), opt
+  into per-test isolation via `provider.perTest()` or by passing `{ strategy:
+  'perTest' }` to `provider.withRepositoryFixture`. Shared mode otherwise keeps the
+  default behavior fast and deterministic.
 - If instructions are ambiguous, assume ZTD mode and proceed.
+- Tests MUST NOT mix ZTD mode and Traditional mode within the same test suite.
+- Traditional mode is reserved for integration-style validation; it is not a convenience or performance workaround.
+- Every repository/test change must be followed by `pnpm --filter <package> test` (substitute the real template package name).
+  - `tests/support/global-setup.ts` already uses `@testcontainers/postgresql`, so a disposable Postgres container spins up automatically whenever `DATABASE_URL` is absent.
+  - If the suite fails, resolve the failure and rerun until it succeeds before considering the change complete.
 
 ---
 
@@ -37,6 +49,8 @@ If a required type is missing:
 - Export the correct type from `src/`.
 
 Do not invent substitute models.
+- Tests MUST treat `tests/generated/ztd-row-map.generated.ts` as the single source of truth for table-shaped rows.
+- If a column exists in the database but not in the row map, the schema is considered outdated until regenerated.
 
 ---
 
@@ -58,6 +72,8 @@ Preferred patterns:
 If behavior depends on transactions, isolation, or shared mutable state:
 - That test does not belong in ZTD unit tests.
 - Move it to an integration test and explicitly request Traditional mode.
+- A single repository method call is the maximum scope of observation in ZTD tests.
+- Tests that validate cross-call effects, workflows, or lifecycle transitions do not belong in ZTD tests.
 
 ---
 
@@ -67,23 +83,51 @@ If behavior depends on transactions, isolation, or shared mutable state:
 - Keep fixtures minimal and intention-revealing.
 - Do not add rows or columns unrelated to the test intent.
 - Do not simulate application-side logic in fixtures.
+- Fixtures must satisfy non-nullable columns and required constraints derived from DDL.
+- Fixtures MUST NOT encode business rules, defaults, or derived values.
+- Fixtures exist only to satisfy schema constraints and make SQL executable.
 
 ---
 
 ## Assertions (important)
 
 - Assert only on relevant fields.
-- Do not assert implicit ordering.
+- Do not assert implicit ordering unless the repository contract explicitly guarantees it
+  (e.g. the query includes a defined `ORDER BY`).
 - Do not assert specific values of auto-generated IDs.
-- Assert existence, type, or relative differences instead.
+- Assert existence, type, cardinality, or relative differences instead.
 
 ---
 
-## Repository boundaries
+## Repository boundaries (important)
 
 - Tests should verify observable behavior of repository methods.
 - Do not duplicate SQL logic or business rules inside tests.
 - Do not test internal helper functions or private implementation details.
+- Tests must match the repository method contract exactly
+  (return type, nullability, and error behavior).
+- Tests MUST NOT compensate for mapper or writer limitations by reimplementing logic in the test itself.
+
+---
+
+## Test helper and resource lifecycle (important)
+
+- Any test helper that creates a client, connection, or testkit instance
+  **must guarantee cleanup**.
+- Always close resources using `try/finally` or a dedicated helper
+  (e.g. `withRepository`).
+- Do not rely on test success paths to release resources.
+
+---
+
+## Test file conventions (important)
+
+- Do not assume Vitest globals are available.
+- Explicitly import `describe`, `it`, and `expect` from `vitest`
+  unless the project explicitly documents global usage.
+- Avoid implicit `any` in tests and helpers.
+  - Explicitly type fixtures and helper parameters
+    (e.g. `Parameters<typeof createTestkitClient>[0]`).
 
 ---
 
@@ -93,7 +137,9 @@ If behavior depends on transactions, isolation, or shared mutable state:
 - However:
   - Do not redefine models.
   - Do not change schema assumptions.
-  - Do not edit `ztd/ddl`, `ztd/domain-specs`, or `ztd/enums` from tests.
+- Do not edit `ztd/ddl`. `ztd/ddl` is the only authoritative `ztd` directory; do not create or assume additional `ztd` subdirectories without explicit instruction.
+- The only authoritative source for tests is `ztd/ddl`.
+- Tests may fail when `ztd/` definitions change; tests MUST be updated to reflect those changes, not the other way around.
 
 ---
 
@@ -105,10 +151,17 @@ If behavior depends on transactions, isolation, or shared mutable state:
 
 ---
 
+## Writer metadata guardrail (template-specific)
+
+- `tests/writer-constraints.test.ts` reads `userAccountWriterColumnSets` together with `tests/generated/ztd-row-map.generated.ts` to ensure every writer column actually exists on `public.user_account`.
+- Run `npx ztd ztd-config` before executing the template tests so the generated row map reflects your current schema changes.
+- When new columns appear in the writer helpers, adjust `userAccountWriterColumnSets`, rerun the row-map generator, and update the constraint test expectations.
+- These tests exist to enforce column correctness at test time so writer helpers remain runtime-safe and schema-agnostic.
+
 ## Guiding principle
 
-ZTD tests exist to validate **SQL semantics in isolation**.
-They are not integration tests, migration tests, or transaction tests.
+ZTD tests exist to validate **repository behavior derived from SQL semantics in isolation**.
+They are not integration tests, migration tests, or transaction tests.      
 
 Prefer:
 - Clear intent

package/templates/tests/support/global-setup.ts

@@ -3,7 +3,7 @@ import { PostgreSqlContainer } from '@testcontainers/postgresql';
 /**
  * Vitest global setup.
  *
- * ZTD tests are safe to run in parallel against a single Postgres instance because pg-testkit
+ * ZTD tests are safe to run in parallel against a single Postgres instance because testkit-postgres
  * rewrites CRUD into fixture-backed SELECT queries (no physical tables are created/mutated).
  *
  * This setup starts exactly one disposable Postgres container when DATABASE_URL is not provided,

package/templates/tests/support/testkit-client.ts

@@ -1,13 +1,13 @@
 // ZTD testkit helper - AUTO GENERATED
-// ztd-cli emits this file during project bootstrapping to wire pg-testkit.
+// ztd-cli emits this file during project bootstrapping to wire @rawsql-ts/adapter-node-pg adapters.
 // Regenerate via npx ztd init (choose overwrite when prompted); avoid manual edits.
 
 import { existsSync, promises as fsPromises } from 'node:fs';
 import path from 'node:path';
 import { Client, types } from 'pg';
 import type { ClientConfig, QueryResultRow } from 'pg';
-import { createPgTestkitClient } from '@rawsql-ts/pg-testkit';
-import type { PgQueryInput, PgQueryable } from '@rawsql-ts/pg-testkit';
+import { createPgTestkitClient } from '@rawsql-ts/adapter-node-pg';
+import type { PgQueryInput, PgQueryable } from '@rawsql-ts/adapter-node-pg';
 import type { TableFixture } from '@rawsql-ts/testkit-core';
 
 const ddlDirectories = [path.resolve(__dirname, '../../ztd/ddl')];
@@ -172,7 +172,7 @@ async function getPgQueryable(): Promise<PgQueryable> {
 
   const client = await getPgClient();
 
-  // Wrap the pg.Client to expose only the subset needed by pg-testkit.
+  // Wrap the pg.Client to expose only the subset needed by @rawsql-ts/adapter-node-pg.
   const wrappedQueryable: PgQueryable = {
     query: <T extends QueryResultRow>(textOrConfig: PgQueryInput, values?: unknown[]) =>
       client.query<T>(textOrConfig as never, values),

package/templates/tests/user-profiles.test.ts

@@ -0,0 +1,161 @@
+import { describe, expect, test, afterAll } from 'vitest';
+import type { TableFixture, TestkitProvider } from '@rawsql-ts/testkit-core';
+import { createTestkitProvider } from '@rawsql-ts/testkit-core';
+import { createPgTestkitClient } from '@rawsql-ts/pg-testkit';
+import { Pool } from 'pg';
+import path from 'node:path';
+import {
+  tableFixture,
+  tableSchemas,
+  TestRowMap,
+} from './generated/ztd-row-map.generated';
+import { listUserProfiles } from '../src/repositories/user-accounts';
+
+const ddlDirectories = [path.resolve(__dirname, '../ztd/ddl')];
+const skipReason = 'DATABASE_URL is not configured';
+const configuredDatabaseUrl = process.env.DATABASE_URL?.trim();
+const suiteTitle = configuredDatabaseUrl
+  ? 'user profile mapper'
+  : `user profile mapper (skipped: ${skipReason})`;
+const describeUserProfile = configuredDatabaseUrl
+  ? describe
+  : (describe.skip as typeof describe);
+let pool: Pool | undefined;
+let providerPromise: Promise<TestkitProvider> | undefined;
+
+// Lazily initialize the test provider so missing DATABASE_URL values do not trigger side effects.
+function getProvider(): Promise<TestkitProvider> {
+  if (providerPromise) {
+    return providerPromise;
+  }
+
+  const databaseUrl = process.env.DATABASE_URL?.trim();
+  if (!databaseUrl) {
+    throw new Error(
+      'Cannot initialize the repository testkit provider without DATABASE_URL.',
+    );
+  }
+
+  pool = new Pool({ connectionString: databaseUrl });
+  const activePool = pool;
+  providerPromise = createTestkitProvider({
+    connectionFactory: () => activePool.connect(),
+    resourceFactory: async (connection, fixtures) =>
+      createPgTestkitClient({
+        connectionFactory: () => connection,
+        tableRows: fixtures,
+        ddl: { directories: ddlDirectories },
+      }),
+    releaseResource: async (client) => {
+      await client.close();
+    },
+    disposeConnection: async (connection) => {
+      if (typeof connection.release === 'function') {
+        connection.release();
+        return;
+      }
+      if (typeof connection.end === 'function') {
+        await connection.end();
+      }
+    },
+  });
+
+  return providerPromise;
+}
+
+afterAll(async () => {
+  // Close resources only when initialization actually happened.
+  if (!providerPromise) {
+    return;
+  }
+
+  const provider = await providerPromise;
+  await provider.close();
+  if (pool) {
+    await pool.end();
+  }
+});
+
+function buildUserAccounts(): TestRowMap['public.user_account'][] {
+  return [
+    {
+      user_account_id: 1,
+      username: 'alpha',
+      email: 'alpha@example.com',
+      display_name: 'Alpha Tester',
+      created_at: '2025-12-01T08:00:00Z',
+      updated_at: '2025-12-01T09:00:00Z',
+    },
+    {
+      user_account_id: 2,
+      username: 'bravo',
+      email: 'bravo@example.com',
+      display_name: 'Bravo Builder',
+      created_at: '2025-12-02T10:00:00Z',
+      updated_at: '2025-12-02T11:00:00Z',
+    },
+  ];
+}
+
+function buildUserProfiles(): TestRowMap['public.user_profile'][] {
+  return [
+    {
+      profile_id: 101,
+      user_account_id: 1,
+      bio: 'Lead engineer and mapper advocate.',
+      website: 'https://example.com',
+      verified: true,
+    },
+  ];
+}
+
+function buildFixtures(): TableFixture[] {
+  return [
+    tableFixture(
+      'public.user_account',
+      buildUserAccounts(),
+      tableSchemas['public.user_account'],
+    ),
+    tableFixture(
+      'public.user_profile',
+      buildUserProfiles(),
+      tableSchemas['public.user_profile'],
+    ),
+  ];
+}
+
+describeUserProfile(suiteTitle, () => {
+  test('listUserProfiles hydrates optional profiles', async () => {
+    const fixtures = buildFixtures();
+    const provider = await getProvider();
+    await provider.withRepositoryFixture(fixtures, async (client) => {
+      const result = await listUserProfiles(client);
+      expect(result).toEqual([
+        {
+          userAccountId: 1,
+          username: 'alpha',
+          email: 'alpha@example.com',
+          displayName: 'Alpha Tester',
+          createdAt: new Date('2025-12-01T08:00:00Z'),
+          updatedAt: new Date('2025-12-01T09:00:00Z'),
+          profile: {
+            profileId: 101,
+            userAccountId: 1,
+            bio: 'Lead engineer and mapper advocate.',
+            website: 'https://example.com',
+            verified: true,
+          },
+        },
+        {
+          userAccountId: 2,
+          username: 'bravo',
+          email: 'bravo@example.com',
+          displayName: 'Bravo Builder',
+          createdAt: new Date('2025-12-02T10:00:00Z'),
+          updatedAt: new Date('2025-12-02T11:00:00Z'),
+          profile: undefined,
+        },
+      ]);
+    });
+  });
+});

package/templates/tests/writer-constraints.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from 'vitest';
+import { tableSchemas } from './generated/ztd-row-map.generated';
+import { userAccountWriterColumnSets } from '../src/repositories/user-accounts';
+
+const userColumns = new Set(
+  Object.keys(tableSchemas['public.user_account'].columns),
+);
+
+describe('user_account writer columns', () => {
+  test('insert columns must exist on the canonical table', () => {
+    const { insertColumns } = userAccountWriterColumnSets;
+    const missing = insertColumns.filter((column) => !userColumns.has(column));
+    expect(missing, `Missing columns: ${missing.join(', ')}`).toEqual([]);
+    expect(insertColumns).toEqual(
+      expect.arrayContaining(['username', 'email', 'display_name']),
+    );
+  });
+
+  test('writer column sets align with the canonical table', () => {
+    const { updateColumns, immutableColumns } = userAccountWriterColumnSets;
+    const missingUpdates = updateColumns.filter((column) => !userColumns.has(column));
+    expect(missingUpdates, `Missing update columns: ${missingUpdates.join(', ')}`).toEqual([]);
+    const missingImmutables = immutableColumns.filter((column) => !userColumns.has(column));
+    expect(missingImmutables, `Missing immutable columns: ${missingImmutables.join(', ')}`).toEqual([]);
+    immutableColumns.forEach((column) => {
+      expect(
+        updateColumns,
+        `Immutable column "${column}" should never appear in updateColumns`,
+      ).not.toContain(column);
+    });
+  });
+});

package/templates/tests/ztd-layout.generated.ts

@@ -3,6 +3,4 @@
 export default {
   ztdRootDir: 'ztd',
   ddlDir: 'ztd/ddl',
-  enumsDir: 'ztd/enums',
-  domainSpecsDir: 'ztd/domain-specs',
 };

package/templates/tsconfig.json

@@ -1,9 +1,8 @@
 {
   "extends": "../../../tsconfig.json",
   "compilerOptions": {
-    "rootDir": ".",
     "outDir": "dist",
     "tsBuildInfoFile": "dist/.tsbuildinfo"
   },
-  "include": ["tests/**/*.ts"]
+  "include": ["src/**/*.ts", "tests/**/*.ts"]
 }