@rawsql-ts/ztd-cli 0.13.2 → 0.14.0

package/templates/AGENTS.md

@@ -0,0 +1,326 @@
+# Appendix: Development Workflow Using Zero Table Dependency (ZTD)
+
+This application uses **Zero Table Dependency (ZTD)** as an internal development workflow for writing, testing, and maintaining SQL logic.  
+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  
+- Ensuring deterministic SQL unit tests  
+- Enabling structured collaboration between humans and AI  
+
+This section documents how ZTD is used *inside this repository* as a development methodology.
+
+---
+
+## Generated files (important)
+
+- `tests/generated/` is auto-generated and must never be committed.
+- After cloning the repository (or in a clean environment), run `npx ztd ztd-config`.
+- If TypeScript reports missing modules or type errors because `tests/generated/` is missing, run `npx ztd ztd-config`.
+
+## ZTD Implementation Guide (src/)
+
+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.
+
+### Repository Classes: What to Care About
+
+#### Scope and Responsibility
+- Repository classes are responsible for executing SQL and returning query results.
+- Avoid embedding business logic, thresholds, or data reshaping inside repositories.
+- Treat repositories as thin adapters over SQL.
+
+#### 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.
+
+#### Specifications and Documentation
+- If a markdown file with the same base name as the repository or SQL exists, read it before implementation.
+  - Such files may contain repository-local specifications (e.g. decision tables, thresholds, request/response notes).
+  - Naming should be aligned (e.g. `FooRepository.ts`, `foo.sql`, `foo.md`).
+
+#### Request and Response Contracts
+- Be explicit about request parameters (types, nullability, constraints).
+- Be explicit about response shape (columns, ordering, cardinality).
+- Prefer documenting contracts in the repository-local markdown file rather than code comments when they are non-trivial.
+
+### SqlClient lifecycle policy (important)
+
+- When using `src/db/sql-client.ts`, prefer a shared `SqlClient` per worker process (singleton).
+- Avoid creating a new database connection for every query or test case.
+- Do not share a live connection across parallel workers; each worker should own its own shared client or pool.
+- If you need strict isolation, create a dedicated client for that scope and close it explicitly.
+
+### Repository SQL and DTO policy (important)
+
+- Repository SQL must return application-facing DTO shapes.
+- SQL SELECT statements should alias columns to camelCase and match the repository return types.
+- 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.
+
+### Sequence / identity column policy (important)
+
+- Sequence / identity columns (auto-generated IDs) are infrastructure concerns.
+- Do **not** explicitly assign values to sequence / identity columns in `INSERT` statements unless explicitly instructed.
+- Repository method inputs should omit sequence / identity columns by default.
+- Only treat an ID as input data when it represents a business rule (e.g. natural keys, externally assigned IDs).
+
+### No test-driven fallbacks in production code (important)
+
+- **Do not add fallbacks in `src/` that exist only to accommodate ZTD/testkit/rewriter limitations.**
+- If a query fails to be rewritten into ZTD form (e.g. rawsql-ts parsing/rewrite failure), **do not “paper over” it** by changing runtime behavior, adding `max(id)+1`, or introducing alternative logic paths.
+- Instead, stop and report the issue with evidence:
+  - The exact SQL that fails
+  - The error message / symptoms
+  - A minimal reproduction (smallest query that triggers the failure)
+  - The expected behavior (what ZTD/testkit should have produced)
+
+Rationale: Production code must not diverge from the intended SQL semantics due to tooling constraints. Tooling issues should be fixed in the tooling layer (rawsql-ts / ztd / testkit), not by altering runtime logic.
+
+---
+
+## ZTD Test Guide (tests/)
+
+Fixtures come from the `ztd/ddl/` definitions and power `pg-testkit`. Always import table types from `tests/generated/ztd-row-map.generated.ts` when constructing scenarios, and rerun `npx ztd ztd-config` whenever schema changes to keep the fixtures and row map synchronized.
+
+If you are working inside this repository's `ztd-playground`, regenerate the generated artifacts with `pnpm --filter ztd-playground exec ztd ztd-config`.
+
+- Set `ZTD_EXECUTION_MODE=traditional` or pass `{ mode: 'traditional', traditional: { isolation: 'schema', cleanup: 'drop_schema' } }` to `createTestkitClient()` when you must exercise real Postgres semantics (locks, isolation, constraints). Traditional mode still runs the DDL inside `ztd/ddl/`, seeds the fixtures, executes any optional `setupSql`, and honors the configured `cleanup` strategy (`drop_schema` by default, `custom_sql`, or `none` for debugging) so the environment stays tidy. Use `isolation: 'none'` when your queries explicitly reference an existing schema and you cannot rely on schema-based isolation.
+
+
+### Tests: What to Care About
+
+#### Test Intent
+- Each test should have a single clear observation point.
+- Decide whether the test verifies:
+  - Query semantics (input to output behavior), or
+  - Structural properties (ordering, filtering, boundary cases).
+
+#### Fixtures
+- Keep fixtures minimal and intention-revealing.
+- Prefer small datasets over large ones.
+- Avoid adding rows or columns that are not directly related to the test intent.
+
+#### Assertions
+- Assert only on relevant columns and values.
+- Do not rely on implicit ordering; if order matters, make it explicit in SQL and assertions.
+- Avoid custom verification logic; rely on query results and straightforward assertions.
+
+#### Relationship to Repositories
+- Tests for repositories should focus on observable behavior, not internal implementation details.
+- Avoid duplicating repository logic inside tests.
+
+### Notes
+- These guidelines are intentionally lightweight.
+- They are expected to evolve based on actual usage and failure cases.
+- If user instructions conflict with these guidelines, follow user instructions.
+
+### ID expectations in tests (important)
+
+- Do not assert auto-generated ID values (sequence / identity), such as "the next id is 11".
+- When creating rows, assert only that an ID exists and has the correct type, or that it differs from known existing IDs.
+- Only assert specific ID values when the ID is part of a business rule (not infrastructure), e.g. a natural key or a fixed, meaningful identifier.
+
+## Parallel test policy (important)
+
+- ZTD tests should be safe to run in parallel against a single Postgres instance because pg-testkit rewrites CRUD into fixture-backed SELECT queries (no physical schema changes).
+- Do not start multiple Postgres instances per test file/worker, and do not isolate tests by creating per-test databases or schemas. This is unnecessary for ZTD and adds failure modes.
+- Prefer one shared Postgres instance + multiple connections, limited only by your DB resources.
+
+---
+
+# ZTD Directory Layout
+
+```
+/ztd
+  /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
+
+/src                    <- application & repository logic
+/tests                  <- ZTD tests, fixtures, row-maps
+```
+
+The file `tests/generated/ztd-layout.generated.ts` ensures ZTD CLI always points to the correct directories.
+
+---
+
+# Principles of ZTD in This Repository
+
+### 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
+
+### 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.
+
+---
+
+# Development Workflows
+
+Different types of changes start from different entry points. Use the workflow appropriate for your situation.
+
+---
+
+# Workflow A — Starting From *DDL Changes*
+Modifying tables, columns, constraints, indexes.
+
+1. Edit DDL files in `ztd/ddl/`.
+2. Run:
+
+   ```bash
+   npx ztd ztd-config
+   ```
+
+   This regenerates `tests/generated/ztd-row-map.generated.ts` from the updated schema.
+
+3. Update repository SQL to match the new schema.
+4. Update fixtures if result shapes changed.
+5. Run tests.
+
+**Flow:** DDL -> Repository SQL -> Fixtures/Tests -> Application
+
+---
+
+# Workflow B — Starting From *Repository Interface Changes*
+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.
+4. Run ZTD tests.
+5. Regenerate config if SQL output shape changed.
+
+**Flow:** Interface -> SQL -> Specs (if needed) -> Tests
+
+---
+
+# Workflow C — Starting From *Repository SQL Logic Changes*
+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/`.
+4. Update fixtures as needed.
+5. Regenerate config if result shape changed.
+
+**Flow:** SQL -> Domain-specs -> Tests
+
+---
+
+# Workflow D — Starting From *Enum or Domain Specification Changes*
+Business rule changes or conceptual model updates.
+
+## Editing enums:
+
+1. Update the relevant `.md` file under `ztd/enums/`.
+2. Run:
+
+   ```bash
+   npx ztd ztd-config
+   ```
+
+3. Update repository SQL referencing enum values.
+4. Update fixtures/tests.
+
+## Editing domain-specs:
+
+1. Update the relevant `.md` file under `ztd/domain-specs/`.
+2. Update repository SQL to reflect the new semantics.
+3. Update or add tests.
+4. Update DDL only if the new rules require schema changes.
+
+**Flow:** Specs/Enums -> SQL -> Tests -> (DDL if required)
+
+---
+
+# Combined Real-World Examples
+
+- Adding a new contract state:  
+  enums -> domain-spec -> SQL -> config -> tests
+
+- Adding a new table:  
+  DDL -> config -> SQL -> fixtures -> tests
+
+- Fixing business logic:  
+  SQL -> domain-spec -> tests
+
+ZTD ensures the development always converges into a consistent, validated workflow.
+
+---
+
+# Human Responsibilities
+
+Humans maintain:
+
+- Schema definitions (`ztd/ddl`)
+- Domain logic definitions (`ztd/domain-specs`)
+- Domain enumerations (`ztd/enums`)
+- Repository interfaces and architectural decisions
+- Acceptance/review of AI-generated patches
+
+Humans decide **what is correct**.
+
+---
+
+# AI Responsibilities
+
+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  
+
+AI decides **how to implement**, but not **what is correct**.
+
+---
+
+# ZTD CLI Responsibilities
+
+ZTD CLI:
+
+- Parses DDL to compute schema shapes  
+- Rewrites SQL via CTE shadowing for testing  
+- Generates `ztd-row-map.generated.ts`  
+- Enables deterministic, parallel SQL unit tests  
+
+ZTD is the verification engine that validates correctness beyond static typing.
+
+---
+
+# Summary
+
+This appendix documents how ZTD is used strictly as an **internal implementation and maintenance guide**.  
+It does not affect the runtime behavior of the application.  
+Its purpose is ensuring:
+
+- Schema integrity  
+- SQL correctness  
+- Domain consistency  
+- Reliable AI-assisted development  
+
+With ZTD, **humans define the meaning**, **AI writes the implementation**, and **tests guarantee correctness**.

package/templates/README.md

@@ -0,0 +1,239 @@
+# Zero Table Dependency Project
+
+This project organizes all SQL‑related artifacts under the `ztd/` directory, separating concerns so both humans and AI can collaborate effectively without interfering with each other's responsibilities.
+
+```
+/ztd
+  /ddl
+    *.sql            <- schema definitions
+  /domain-specs
+    *.md             <- one behavior per file (one SQL block)
+  /enums
+    *.md             <- one enum per file (one SQL block)
+  README.md          <- documentation for the layout
+  AGENTS.md          <- combined guidance for people and agents
+
+/src                 <- application & repository code
+/tests               <- ZTD tests, fixtures, generated maps
+```
+
+## 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:
+
+```bash
+npx ztd ztd-config
+```
+
+If TypeScript reports missing modules or type errors because `tests/generated/` is missing, run `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.
+
+---
+
+# Optional SqlClient seam
+
+If this project was initialized with `npx ztd init --with-sqlclient`, you'll also have `src/db/sql-client.ts`.
+It defines a minimal `SqlClient` interface that repositories can depend on:
+
+- Use it for tutorials and greenfield projects to keep repository SQL decoupled from drivers.
+- Skip it when you already have a database abstraction (Prisma, Drizzle, Kysely, custom adapters).
+- For `pg`, adapt `client.query(...)` so it returns a plain `T[]` row array that matches the interface.
+- Prefer a shared client per worker process so tests and scripts do not reconnect on every query.
+- Do not share a live connection across parallel workers; each worker should own its own shared client.
+
+Example (driver-agnostic):
+
+```ts
+let sharedClient: SqlClient | undefined;
+
+export function getSqlClient(): SqlClient {
+  if (!sharedClient) {
+    // Create the client once using your chosen driver (pg, mysql, etc.).
+    sharedClient = createSqlClientOnce();
+  }
+  return sharedClient;
+}
+```
+
+---
+
+# Principles
+
+### 1. Humans own the *definitions*
+- DDL (physical schema)
+- Domain specifications (business logic -> SQL semantics)
+- Enums (canonical domain values)
+
+### 2. AI owns the *implementation*
+- Repository SQL generation
+- Test fixture updates
+- Intermediate TypeScript structures
+- SQL rewriting, parameter binding, shape resolution
+
+### 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
+
+If any part diverges, ZTD tests fail deterministically.
+
+---
+
+# Workflow Overview
+
+Different tasks start from different entry points. Choose the workflow that matches what you want to change.
+
+---
+
+# Workflow A — Starting From *DDL Changes*  
+(Adding tables/columns, changing constraints)
+
+1. Edit files under `ztd/ddl/`.
+2. Run:
+
+   ```bash
+   npx ztd ztd-config
+   ```
+
+   This regenerates `tests/generated/ztd-row-map.generated.ts` from the new schema.
+
+3. Update repository SQL so it matches the new schema.
+4. Update fixtures if shapes changed.
+5. Run tests. Any schema mismatch will fail fast.
+
+**Flow:**  
+**DDL -> repository SQL -> fixtures/tests -> application**
+
+---
+
+# Workflow B — Starting From *Repository Interface Changes*  
+(Adding a method, changing return types, etc.)
+
+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.
+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**
+
+---
+
+# 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.
+5. If SQL result shape changed, run:
+
+   ```bash
+   npx ztd ztd-config
+   ```
+
+**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)**
+
+---
+
+# Combined Real‑World Flow Examples
+
+- **Add a new contract status**  
+  enums -> domain-spec -> 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.
+
+---
+
+# 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 decide “what is correct.”
+
+---
+
+# AI Responsibilities
+
+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
+
+AI decides “how to implement” within those constraints.
+
+---
+
+# ZTD CLI Responsibilities
+
+ZTD CLI:
+
+- Parses DDL files to build accurate table/column shapes
+- Rewrites SQL with fixture-based CTE shadowing (via testkit adapters)
+- Generates `ztd-row-map.generated.ts`
+- Produces deterministic, parallelizable tests
+
+ZTD is the verification engine guaranteeing correctness.
+
+## Traditional execution mode
+
+- Set `ZTD_EXECUTION_MODE=traditional` or pass `{ mode: 'traditional', traditional: { isolation: 'schema', cleanup: 'drop_schema' } }` when you need to run the tests against a real Postgres schema (locking, isolation, constraints). The helper still applies the DDL inside `ztd/ddl/`, loads the fixture rows into the schema, optionally executes `setupSql`, and carries out the chosen cleanup strategy (`drop_schema`, `custom_sql`, or `none`).
+- Use `isolation: 'none'` if you need to target a schema that is already defined or if your SQL embeds schema qualifiers explicitly.
+
+---
+
+# Summary
+
+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.

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

@@ -0,0 +1,24 @@
+/**
+ * Promise that resolves to the array of rows produced by an SQL query.
+ * @template T Shape of each row yielded by the SQL client.
+ * @example
+ * const rows: SqlQueryRows<{ id: number; name: string }> = client.query('SELECT id, name FROM users');
+ */
+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()`
+ *
+ * Connection strategy note:
+ * - Prefer a shared client per worker process for performance.
+ * - Do not share a live client across parallel workers.
+ */
+export type SqlClient = {
+  query<T extends Record<string, unknown> = Record<string, unknown>>(
+    text: string,
+    values?: readonly unknown[]
+  ): SqlQueryRows<T>;
+};

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

@@ -0,0 +1,30 @@
+import { PostgreSqlContainer } from '@testcontainers/postgresql';
+
+/**
+ * Vitest global setup.
+ *
+ * ZTD tests are safe to run in parallel against a single Postgres instance because pg-testkit
+ * 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,
+ * and shares the resulting DATABASE_URL with all Vitest workers.
+ */
+export default async function globalSetup() {
+  const configuredUrl = process.env.DATABASE_URL;
+  if (configuredUrl && configuredUrl.length > 0) {
+    return () => undefined;
+  }
+
+  const container = new PostgreSqlContainer('postgres:18-alpine')
+    .withDatabase('ztd_playground')
+    .withUsername('postgres')
+    .withPassword('postgres');
+
+  const started = await container.start();
+  process.env.DATABASE_URL = started.getConnectionUri();
+
+  return async () => {
+    await started.stop();
+  };
+}
+