@rawsql-ts/ztd-cli 0.17.0 → 0.20.0

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

@@ -1,94 +1,29 @@
-# 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 Scope
+- Applies to `packages/ztd-cli/templates/src/repositories/tables`.
+- Defines table-oriented CRUD repository contract behavior.
+
+# Policy
+## REQUIRED
+- CREATE SQL MUST use identifier-focused `RETURNING` when generated keys are required.
+- CREATE repository methods MUST return identifier-only results by default.
+- UPDATE and DELETE MUST rely on affected-row counts where available.
+- `rowCount === 0` conditions MUST surface explicitly according to contract behavior.
+- Patch contracts MUST distinguish omitted fields from explicit null values.
+- Public repository methods MUST be test-covered for mapping and CUD error behavior.
+
+## ALLOWED
+- DTO-returning CREATE behavior MAY be implemented only when explicitly required by human-authored spec.
+
+## PROHIBITED
+- UPDATE/DELETE `RETURNING`-based success emulation.
+- Follow-up SELECT workarounds for CUD verification.
+- Ambiguous patch patterns that hide omitted-vs-null intent.
+
+# Mandatory Workflow
+- Table repository changes MUST run tests for affected-row handling and explicit failure surfaces.
+
+# Hygiene
+- Keep SQL assets idiomatic and driver-neutral for table CRUD paths.
+
+# References
+- Parent repository policy: [../AGENTS.md](../AGENTS.md)

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

@@ -1,3 +1,5 @@
-# Table Repositories
-
-Write-focused repositories that execute CRUD SQL from `src/sql`.
+# Table Repositories
+
+Write-focused repositories that execute CRUD SQL from `src/sql`.
+
+Accept an optional telemetry hook from `src/infrastructure/telemetry/repositoryTelemetry.ts` and default it through `resolveRepositoryTelemetry(...)` so applications can replace the sink without editing repository internals.

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

@@ -1,25 +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 Scope
+- Applies to `packages/ztd-cli/templates/src/repositories/views`.
+- Defines read-model repository behavior for complex SELECT-only queries.
+
+# Policy
+## REQUIRED
+- Queries in this subtree MUST remain read-only.
+- Read-model DTO validation MUST run at repository/catalog boundaries.
+- Query naming MUST make cardinality assumptions explicit.
+
+## ALLOWED
+- Multi-table joins, aggregations, and purpose-built read DTOs MAY be used.
+
+## PROHIBITED
+- INSERT/UPDATE/DELETE behavior in this subtree.
+- Hidden write side effects in read-model query paths.
+
+# Mandatory Workflow
+- View repository changes MUST run tests for DTO validation and result ordering assumptions.
+
+# Hygiene
+- Preserve explicit ordering whenever test behavior depends on row order.
+
+# References
+- Parent repository policy: [../AGENTS.md](../AGENTS.md)

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

@@ -1,3 +1,5 @@
-# View Repositories
-
-Read-only repositories backed by SELECT SQL in `src/sql`.
+# View Repositories
+
+Read-only repositories backed by SELECT SQL in `src/sql`.
+
+Accept an optional telemetry hook from `src/infrastructure/telemetry/repositoryTelemetry.ts` and default it through `resolveRepositoryTelemetry(...)` so applications can bridge structured events into their own logging stack.

package/templates/src/sql/AGENTS.md

@@ -1,77 +1,30 @@
-# 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 Scope
+- Applies to `packages/ztd-cli/templates/src/sql`.
+- Defines SQL asset contract rules for runtime execution.
+
+# Policy
+## REQUIRED
+- SQL assets MUST use named parameters (`:name`).
+- SQL assets MUST stay DTO-independent and use database-oriented column naming.
+- UPDATE and DELETE statements MUST include WHERE clauses.
+- SQL files MUST remain explicit enough for repository/runtime mapping contracts.
+- CUD `RETURNING` behavior MUST follow repository contract rules.
+
+## ALLOWED
+- INSERT SQL MAY use `RETURNING` for identifiers and required DB-generated contract columns.
+
+## PROHIBITED
+- Positional placeholders in SQL asset files.
+- DTO camelCase aliasing inside SQL assets.
+- UPDATE/DELETE `RETURNING` usage.
+- SQL-side emulation of affected-row verification behavior.
+
+# Mandatory Workflow
+- SQL asset changes MUST run tests that execute the changed SQL via catalog/repository paths.
+
+# Hygiene
+- Keep SQL filenames stable and unambiguous for CRUD intent.
+- Avoid `select *` unless explicitly justified by contract behavior.
+
+# References
+- Parent runtime policy: [../AGENTS.md](../AGENTS.md)

package/templates/src/sql/README.md

@@ -1,6 +1,6 @@
-# SQL Files
-
-Store SQL statements by table or domain in subfolders.
-
-- Use named parameters (for example `:id`).
+# 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,62 +1,29 @@
-# tests AGENTS
-
-This directory contains verification code.
-
-## Runtime classification
-
-- This is a non-runtime directory.
-- Code here is never part of application runtime.
-
-## Core principles
-
-- This project uses ZTD (Zero Table Dependency).
-- DDL and fixtures define the test world.
-- Tests must be deterministic and parallel-safe.
-
-## What to test (important)
-
-- 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
-
-- Tests MUST NOT enforce repository behavior that contradicts repository contracts.
-- Tests MUST NOT require follow-up SELECTs after UPDATE or DELETE by default.
-
-## CUD test policy (important)
-
-- 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
-
-- "tests/generated/" is auto-generated.
-- Do not edit generated files by hand.
-- Regenerate before debugging type errors.
-
-## Boundaries
-
-- Tests may import from "src/".
-- Runtime code under "src/" MUST NOT import from "tests/" or "tests/generated/".
-
-## Test runner requirements (required)
-
-- 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.
-
-## Initialization invariant
-
-- 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 Scope
+- Applies to `packages/ztd-cli/templates/tests`.
+- Defines verification contract for ZTD template-generated test code.
+
+# Policy
+## REQUIRED
+- Tests MUST verify SQL execution under ZTD rewrite, mapping behavior, validation paths, and DTO shape semantics.
+- CUD tests MUST verify UPDATE/DELETE via affected-row signals.
+- CREATE tests for table repositories MUST expect identifier-only returns unless spec explicitly requires DTO return.
+- Test runner configuration MUST exist and support single-command execution.
+- Initial template state MUST include at least one executable test.
+
+## ALLOWED
+- Tests MAY import runtime modules from `src/`.
+
+## PROHIBITED
+- Runtime imports from `tests/` or `tests/generated/`.
+- Tests that require repository follow-up SELECT behavior contradicting repository contracts.
+- Manual edits to generated artifacts.
+
+# Mandatory Workflow
+- Test changes MUST run affected test suites and confirm test-runner configuration remains valid.
+
+# Hygiene
+- Regenerate `tests/generated` artifacts before diagnosing missing generated module errors.
+
+# References
+- Generated tests policy: [./generated/AGENTS.md](./generated/AGENTS.md)
+- Shared support policy: [./support/AGENTS.md](./support/AGENTS.md)

package/templates/tests/generated/AGENTS.md

@@ -1,16 +1,23 @@
-# 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 Scope
+- Applies to `packages/ztd-cli/templates/tests/generated`.
+- Governs generated test artifacts.
+
+# Policy
+## REQUIRED
+- Missing or stale generated files MUST be regenerated using project generation commands.
+
+## ALLOWED
+- Generated artifacts MAY be regenerated via `npx ztd ztd-config`.
+
+## PROHIBITED
+- Manual edits to files in this directory.
+- Committing generated artifacts when repository policy does not require them.
+
+# Mandatory Workflow
+- Run generation commands before diagnosing generated-module type errors.
+
+# Hygiene
+- Keep generated output reproducible from project tooling.
+
+# References
+- Parent tests policy: [../AGENTS.md](../AGENTS.md)

package/templates/tests/smoke.test.ts

@@ -1,5 +1,25 @@
-import { expect, test } from 'vitest';
-
-test('smoke: template test runner is wired', () => {
-  expect(true).toBe(true);
-});
+import { expect, test } from 'vitest';
+
+import { ensureSmokeOutput } from '../src/catalog/runtime/_smoke.runtime';
+import { createTestkitClient } from './support/testkit-client';
+
+test('smoke: runtime contract wiring is usable before SQL-backed tests exist', () => {
+  const output = ensureSmokeOutput({
+    id: 1,
+    createdAt: '2025-01-01T00:00:00.000Z',
+  });
+
+  expect(output.id).toBe(1);
+  expect(output.createdAt).toBeInstanceOf(Date);
+  expect(output.createdAt.toISOString()).toBe('2025-01-01T00:00:00.000Z');
+});
+
+test('smoke: SqlClient seam is either wired or fails with an actionable message', async () => {
+  try {
+    const client = await createTestkitClient();
+    expect(typeof client.query).toBe('function');
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    expect(message).toContain('Provide a SqlClient implementation here');
+  }
+});

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

@@ -1,34 +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/);
-});
+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

@@ -1,26 +1,24 @@
-# 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 Scope
+- Applies to `packages/ztd-cli/templates/tests/support`.
+- Defines shared test infrastructure contracts.
+
+# Policy
+## REQUIRED
+- Shared support helpers MUST stay minimal and explicit.
+- Shared support code MUST avoid business-rule ownership.
+- Runtime code under `src/` MUST NOT import from this folder.
+
+## ALLOWED
+- Support helpers MAY import from `src/`.
+
+## PROHIBITED
+- Embedding domain business logic into support infrastructure.
+
+# Mandatory Workflow
+- Global setup/support changes MUST run representative subset tests and at least one full test run.
+
+# Hygiene
+- Validate resource lifecycle and parallelism behavior after support-layer changes.
+
+# References
+- Parent tests policy: [../AGENTS.md](../AGENTS.md)

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

@@ -1,15 +1,15 @@
-/**
- * Vitest global setup.
- *
- * 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?.trim();
-  if (!configuredUrl) {
-    console.warn(
-      'DATABASE_URL is not configured. Install a database adapter or set DATABASE_URL before running SQL-backed tests.',
-    );
-  }
-  return () => undefined;
-}
+/**
+ * Vitest global setup.
+ *
+ * This hook warns when ZTD_TEST_DATABASE_URL is missing so the developer remembers
+ * to provide the ZTD-owned test database connection before running SQL-backed tests.
+ */
+export default async function globalSetup() {
+  const configuredUrl = process.env.ZTD_TEST_DATABASE_URL?.trim();
+  if (!configuredUrl) {
+    console.warn(
+      'ZTD_TEST_DATABASE_URL is not configured. SQL-backed tests will need a driver plus a ZTD-owned test database connection before they can run.',
+    );
+  }
+  return () => undefined;
+}