@rawsql-ts/ztd-cli 0.15.0 → 0.17.0

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,148 +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)
+- This is a non-runtime directory.
+- Code here is never part of application runtime.
 
-- 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.
+## Core principles
 
----
+- This project uses ZTD (Zero Table Dependency).
+- DDL and fixtures define the test world.
+- Tests must be deterministic and parallel-safe.
 
-## Use generated types only (important)
+## What to test (important)
 
-- 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/`.
+- 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
 
-Forbidden example:
+- Tests MUST NOT enforce repository behavior that contradicts repository contracts.
+- Tests MUST NOT require follow-up SELECTs after UPDATE or DELETE by default.
 
-```typescript
-type CategoryTestRow = {
-  category_id: number;
-  parent_id: number | null;
-  name: string;
-};
-```
+## CUD test policy (important)
 
-If a required type is missing:
-- Regenerate generated artifacts (`npx ztd ztd-config`), or
-- Export the correct type from `src/`.
+- 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.
 
-Do not invent substitute models.
+## Generated artifacts
 
----
+- "tests/generated/" is auto-generated.
+- Do not edit generated files by hand.
+- Regenerate before debugging type errors.
 
-## Stateless test design (important)
+## Boundaries
 
-- ZTD tests are **stateless by design**.
-- Do not write tests that depend on state accumulating across multiple repository calls.
+- Tests may import from "src/".
+- Runtime code under "src/" MUST NOT import from "tests/" or "tests/generated/".
 
-Forbidden patterns include:
-- Updating the same record in multiple steps and verifying later state
-- Calling multiple repository methods assuming earlier calls affected the database
+## Test runner requirements (required)
 
-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
+- 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.
 
-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.
+Do not add tests that assume manual setup steps.
 
----
+## Initialization invariant
 
-## Fixtures (important)
-
-- 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.
-
----
-
-## 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).
-
----
-
-## 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/domain-specs`, or `ztd/enums` from tests.
-
----
-
-## Conflict resolution
-
-- If test requirements conflict with ZTD constraints:
-  - Stop and ask for clarification.
-  - Do not silently switch modes or weaken assertions.
-
----
-
-## 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 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.
+ * 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;
 }
-