@rawsql-ts/ztd-cli 0.16.0 → 0.17.0

package/templates/src/repositories/tables/AGENTS.md

@@ -0,0 +1,94 @@
+# src/repositories/tables AGENTS
+
+This directory contains simple CRUD-style repositories.
+
+## Runtime classification
+
+- This is a runtime directory.
+- Code here executes SQL and returns application-facing results.
+
+## Responsibilities
+
+- Execute SQL assets using defined contracts.
+- Perform explicit mapping from SQL rows to DTOs.
+- Enforce CUD semantics at the application boundary (including "0 rows" handling).
+
+## Contract ownership (important)
+
+- Input parameter types and DTO shapes are defined in specs ("src/catalog/specs").
+- Repositories MUST NOT invent or modify contracts.
+- Repositories may adapt SQL results into DTOs, but must not redefine the contract.
+
+## SQL usage rules (tables CRUD quality bar)
+
+- Repositories in this folder MUST treat SQL assets as human-maintained, idiomatic SQL.
+- Do not require SQL assets to implement driver-specific behaviors.
+- If a driver does not provide affected-row counts for UPDATE/DELETE, fail fast as unsupported.
+
+Examples:
+- Prefer a plain UPDATE statement in SQL.
+- Do not force SQL to return `affected_count` via CTE tricks.
+
+## CUD behavior rules
+
+### CREATE (INSERT)
+
+Default:
+- SQL MUST use `insert ... returning <primary_key>` when a generated key is needed.
+- Repository CREATE MUST return identifier only (scalar) per contract.
+- Repository CREATE MUST NOT perform a follow-up SELECT for DTO return shaping.
+- SQL MUST NOT return full rows or DTO-shaped payloads.
+
+Exception:
+- If a CREATE endpoint must return DTO, the spec MUST explicitly require it by human instruction.
+- Without that explicit contract, identifier-only return is mandatory.
+
+### UPDATE
+
+Default:
+- SQL: plain UPDATE without RETURNING.
+- Repository: determine success by affected row count when available.
+
+Driver variability handling:
+- If affected row count is unavailable:
+  - Treat UPDATE verification as unsupported for that driver/runtime.
+  - Throw an explicit error.
+- Do not add fallback checks or workaround logic in repositories.
+- Do not push this variability down into SQL assets.
+
+0-row rule (important):
+- Treat "0 rows updated" as a meaningful condition.
+- Default behavior is to surface it clearly (often an error), per spec.
+
+### DELETE
+
+Default:
+- SQL: plain DELETE without RETURNING.
+- Repository: determine success by affected row count when available.
+
+Driver variability handling:
+- If affected row count is unavailable:
+  - Treat DELETE verification as unsupported for that driver/runtime.
+  - Throw an explicit error.
+- Do not add fallback checks or workaround logic in repositories.
+
+0-row rule (important):
+- Treat "0 rows deleted" as a meaningful condition, per spec.
+
+## Patch updates (important)
+
+- Avoid ambiguous patterns such as `coalesce(param, column)` by default.
+- Contracts should distinguish:
+  - "not provided"
+  - "explicitly set to null"
+- If patch semantics are needed, implement them explicitly via:
+  - separate SQL variants, or
+  - explicit contract types that preserve intent.
+
+## Testing rule (required)
+
+- Every public repository method MUST be covered by tests.
+- Tests should verify:
+  - correct mapping behavior
+  - correct "0 rows" behavior for UPDATE/DELETE
+  - correct error surfaces (do not silently succeed)

package/templates/src/repositories/tables/README.md

@@ -0,0 +1,3 @@
+# Table Repositories
+
+Write-focused repositories that execute CRUD SQL from `src/sql`.

package/templates/src/repositories/views/AGENTS.md

@@ -0,0 +1,25 @@
+# src/repositories/views AGENTS
+
+This folder is for complex read-only queries.
+
+## Scope
+
+- Complex SELECT queries (joins, aggregations, window functions).
+- Read models that are not 1:1 with a single table.
+
+## Allowed
+
+- Multi-table joins and aggregations.
+- Purpose-built DTOs for read models.
+- Validation at the boundary (catalog validator or repository-level validator).
+
+## Forbidden
+
+- INSERT/UPDATE/DELETE in this folder by default.
+- Hidden write side-effects.
+
+## Guidance
+
+- Keep query intent clear in naming.
+- Document cardinality assumptions (one, many, optional).
+- Prefer stable ordering if tests rely on order.

package/templates/src/repositories/views/README.md

@@ -0,0 +1,3 @@
+# View Repositories
+
+Read-only repositories backed by SELECT SQL in `src/sql`.

package/templates/src/sql/AGENTS.md

@@ -0,0 +1,77 @@
+# src/sql AGENTS
+
+This directory contains SQL assets executed at runtime.
+
+## Runtime classification
+
+- This is a runtime directory.
+- SQL files are loaded and executed by repositories or catalog runtime.
+
+## Ownership (important)
+
+- SQL expresses domain intent and is human-owned by default.
+- AI may propose changes, but MUST NOT alter semantics or intent without explicit human instruction.
+- If a human explicitly writes or edits SQL, the human decision always takes precedence.
+
+## Parameter binding (required)
+
+- SQL assets MUST use named parameters (":name" form).
+- Positional parameters ("$1", "$2", ...) are forbidden in SQL assets.
+- Conversion from named to indexed parameters is a runtime responsibility.
+
+## DTO independence (critical)
+
+- SQL MUST NOT depend on DTO shapes.
+- CamelCase aliases (e.g. `as "userId"`) are forbidden.
+- SQL should return database-oriented column names (typically snake_case).
+- Mapping to DTOs is the responsibility of repositories or catalog runtime.
+
+## CRUD quality bar (tables) (important)
+
+For simple CRUD SQL under table-oriented areas:
+- Prefer the most direct and idiomatic SQL.
+- Do NOT encode driver limitations into SQL.
+- Avoid unnecessary CTEs or counting tricks.
+
+Examples of discouraged patterns for simple CRUD:
+- `with updated as (...) select count(*) ...`
+- returning values only to compute affected rows
+
+Affected-row handling belongs to repositories/runtime, not SQL.
+
+## CUD and RETURNING policy
+
+- INSERT SQL MAY use `RETURNING` only for identifier columns (and optionally DB-generated columns required by contract).
+- INSERT SQL MUST NOT return full rows or DTO-shaped payloads.
+- UPDATE SQL MUST NOT use `RETURNING`.
+- DELETE SQL MUST NOT use `RETURNING`.
+- SQL MUST NOT use `RETURNING` to emulate affected-row detection.
+- If affected-row counts are unavailable from the driver/runtime, treat UPDATE/DELETE verification as unsupported at the driver boundary.
+
+## Safety rules (critical)
+
+- UPDATE and DELETE MUST include a WHERE clause.
+- SQL MUST NOT rely on follow-up SELECTs in repositories to ensure correctness.
+- A missing or incorrect WHERE clause is a SQL bug and MUST surface via tests.
+
+## Naming conventions (recommended)
+
+Prefer SQL-idiomatic verbs for CRUD assets:
+- insert_<entity>.sql
+- select_<entity>_by_<key>.sql
+- select_<entities>.sql
+- update_<entity>.sql
+- delete_<entity>.sql
+
+Avoid ambiguous verbs like "create" / "get" in SQL filenames by default.
+
+## General SQL rules
+
+- Use explicit column lists.
+- Avoid `select *` unless explicitly justified.
+- Prefer stable ordering when result order matters.
+
+## Boundaries
+
+- Do not place TypeScript code in this directory.
+- Query contracts live in "src/catalog/specs".

package/templates/src/sql/README.md

@@ -0,0 +1,6 @@
+# SQL Files
+
+Store SQL statements by table or domain in subfolders.
+
+- Use named parameters (for example `:id`).
+- Keep SQL in files; repositories should load them.

package/templates/tests/AGENTS.md

@@ -1,169 +1,62 @@
-# AGENTS: ZTD Test Guidelines
+# tests AGENTS
 
-This file defines **rules and boundaries for writing tests under `tests/`**.
-Tests are a shared workspace for humans and AI, but must respect ZTD-specific constraints.
+This directory contains verification code.
 
----
+## Runtime classification
 
-## 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.
+- This is a non-runtime directory.
+- Code here is never part of application runtime.
 
----
+## Core principles
 
-## Use generated types only (important)
+- This project uses ZTD (Zero Table Dependency).
+- DDL and fixtures define the test world.
+- Tests must be deterministic and parallel-safe.
 
-- Do **not** define ad-hoc or duplicate test models.
-- For table-shaped rows, always import types from:
-  - `tests/generated/ztd-row-map.generated.ts`
-- For application-facing return values:
-  - Use DTO or domain model types already defined in `src/`.
+## What to test (important)
 
-Forbidden example:
+- Catalog specs are first-class test targets.
+- Tests should verify:
+  - SQL executes under ZTD rewriting
+  - mapping behavior
+  - validation success and failure
+  - DTO shape and semantics
 
-```typescript
-type CategoryTestRow = {
-  category_id: number;
-  parent_id: number | null;
-  name: string;
-};
-```
+- Tests MUST NOT enforce repository behavior that contradicts repository contracts.
+- Tests MUST NOT require follow-up SELECTs after UPDATE or DELETE by default.
 
-If a required type is missing:
-- Regenerate generated artifacts (`npx ztd ztd-config`), or
-- Export the correct type from `src/`.
+## CUD test policy (important)
 
-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.
+- UPDATE and DELETE success/failure MUST be verified via affected-row information
+  (e.g. rowCount or equivalent).
+- Tests MUST NOT assume UPDATE/DELETE return DTOs.
+- If the driver cannot report affected rows, CUD verification is unsupported and
+  tests MUST fail fast.
+- CREATE tests for table repositories MUST expect identifier-only returns by default.
+- Tests MUST NOT require repository follow-up SELECT after CREATE unless the catalog spec explicitly requires DTO return.
 
----
+## Generated artifacts
 
-## Stateless test design (important)
+- "tests/generated/" is auto-generated.
+- Do not edit generated files by hand.
+- Regenerate before debugging type errors.
 
-- ZTD tests are **stateless by design**.
-- Do not write tests that depend on state accumulating across multiple repository calls.
+## Boundaries
 
-Forbidden patterns include:
-- Updating the same record in multiple steps and verifying later state
-- Calling multiple repository methods assuming earlier calls affected the database
+- Tests may import from "src/".
+- Runtime code under "src/" MUST NOT import from "tests/" or "tests/generated/".
 
-Preferred patterns:
-- Verify results returned by a single statement
-- Verify `RETURNING` values
-- Verify affected row counts
-- Verify query output produced by the same call being tested
+## Test runner requirements (required)
 
-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.
+- A test runner configuration (e.g. vitest.config.ts) MUST exist.
+- Tests MUST be executable with a single command (e.g. `pnpm test`).
+- Missing test runner configuration is considered a setup error.
 
----
+Do not add tests that assume manual setup steps.
 
-## Fixtures (important)
+## Initialization invariant
 
-- Fixtures originate from `ztd/ddl/`.
-- 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 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, cardinality, or relative differences instead.
-
----
-
-## 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]`).
-
----
-
-## Edit boundaries
-
-- Tests are shared ownership: humans and AI may both edit.
-- However:
-  - Do not redefine models.
-  - Do not change schema assumptions.
-- 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.
-
----
-
-## Conflict resolution
-
-- If test requirements conflict with ZTD constraints:
-  - Stop and ask for clarification.
-  - Do not silently switch modes or weaken assertions.
-
----
-
-## 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 **repository behavior derived from SQL semantics in isolation**.
-They are not integration tests, migration tests, or transaction tests.      
-
-Prefer:
-- Clear intent
-- Single observation point
-- Deterministic outcomes
+- The initial project state MUST include:
+  - test runner configuration
+  - at least one executable test file
+- The initial test run MUST pass or fail only due to user-written logic, not setup.

package/templates/tests/generated/AGENTS.md

@@ -0,0 +1,16 @@
+# tests/generated AGENTS
+
+This directory contains generated files.
+
+## Non-negotiable
+
+- Do not edit any file in this directory by hand.
+- Do not commit generated artifacts unless the repository explicitly requires it.
+
+## Regeneration
+
+If files are missing or stale, regenerate using the project command.
+Example:
+- "npx ztd ztd-config"
+
+If TypeScript reports missing modules referencing generated files, regenerate first.

package/templates/tests/smoke.test.ts

@@ -0,0 +1,5 @@
+import { expect, test } from 'vitest';
+
+test('smoke: template test runner is wired', () => {
+  expect(true).toBe(true);
+});

package/templates/tests/smoke.validation.test.ts

@@ -0,0 +1,34 @@
+import { expect, test } from 'vitest';
+
+import { ensureSmokeOutput } from '../src/catalog/runtime/_smoke.runtime';
+
+test('validator invariant smoke passes for valid runtime output', () => {
+  const output = ensureSmokeOutput({
+    id: 1,
+    createdAt: new Date('2025-01-01T00:00:00.000Z')
+  });
+
+  expect(output).toEqual({
+    id: 1,
+    createdAt: new Date('2025-01-01T00:00:00.000Z')
+  });
+});
+
+test('validator invariant smoke normalizes valid timestamp strings', () => {
+  const output = ensureSmokeOutput({
+    id: 1,
+    createdAt: '2025-01-01T00:00:00.000Z'
+  });
+
+  expect(output.createdAt).toBeInstanceOf(Date);
+  expect(output.createdAt.toISOString()).toBe('2025-01-01T00:00:00.000Z');
+});
+
+test('validator invariant smoke fails for invalid runtime output', () => {
+  expect(() =>
+    ensureSmokeOutput({
+      id: 1,
+      createdAt: 'not-a-date'
+    })
+  ).toThrow(/Invalid timestamp string/);
+});

package/templates/tests/support/AGENTS.md

@@ -0,0 +1,26 @@
+# tests/support AGENTS
+
+This folder contains shared test infrastructure.
+
+## Scope
+
+- global setup and teardown
+- test clients and helpers for execution
+- environment/bootstrap logic
+
+## Rules
+
+- Keep helpers minimal and explicit.
+- Prefer stable interfaces used across tests.
+- Do not place business rules here.
+
+## Boundaries
+
+- Support code may import from "src/" as needed.
+- Runtime code under "src/" MUST NOT import from this folder.
+
+## Changes
+
+When modifying global setup or shared clients:
+- Re-run a representative subset of tests and at least one full run when feasible.
+- Watch for parallelism and resource lifecycle issues.

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

@@ -1,30 +1,15 @@
-import { PostgreSqlContainer } from '@testcontainers/postgresql';
-
 /**
  * Vitest global setup.
  *
- * 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,
- * and shares the resulting DATABASE_URL with all Vitest workers.
+ * This hook warns when DATABASE_URL is missing so the developer remembers to
+ * install an adapter or provide a connection before running SQL-backed tests.
  */
 export default async function globalSetup() {
-  const configuredUrl = process.env.DATABASE_URL;
-  if (configuredUrl && configuredUrl.length > 0) {
-    return () => undefined;
+  const configuredUrl = process.env.DATABASE_URL?.trim();
+  if (!configuredUrl) {
+    console.warn(
+      'DATABASE_URL is not configured. Install a database adapter or set DATABASE_URL before running SQL-backed tests.',
+    );
   }
-
-  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();
-  };
+  return () => undefined;
 }
-