@rawsql-ts/ztd-cli 0.16.0 → 0.19.0

package/templates/src/repositories/AGENTS.md

@@ -0,0 +1,30 @@
+# Package Scope
+- Applies to `packages/ztd-cli/templates/src/repositories`.
+- Defines runtime repository responsibilities for SQL execution orchestration.
+
+# Policy
+## REQUIRED
+- Repositories MUST load SQL assets from `src/sql` through shared loader infrastructure.
+- Repositories MUST use catalog runtime helpers (`ensure*`, `map*`) for input/output validation.
+- Repository CUD behavior MUST follow contract rules for `RETURNING`, rowCount handling, and explicit unsupported-driver failures.
+- Repository modules MUST reference SQL by stable logical keys.
+- Repository constructors SHOULD accept an optional telemetry dependency from `src/infrastructure/telemetry/repositoryTelemetry.ts`.
+- Public repository methods MUST be covered by tests.
+
+## ALLOWED
+- SELECT methods MAY return `T | null` or `T[]` according to contract cardinality.
+
+## PROHIBITED
+- Embedding business rules or contract inference in repositories.
+- Inline SQL strings or ad-hoc SQL file path resolution.
+- Follow-up SELECT workarounds to emulate CUD success semantics.
+
+# Mandatory Workflow
+- Repository changes MUST run tests covering mapping, rowCount behavior, and error surfaces.
+
+# Hygiene
+- Error messages MUST include operation identifiers and relevant parameters.
+
+# References
+- Tables repository policy: [./tables/AGENTS.md](./tables/AGENTS.md)
+- Views repository policy: [./views/AGENTS.md](./views/AGENTS.md)

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

@@ -0,0 +1,29 @@
+# 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

@@ -0,0 +1,5 @@
+# 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

@@ -0,0 +1,25 @@
+# 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

@@ -0,0 +1,5 @@
+# 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

@@ -0,0 +1,30 @@
+# 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

@@ -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,29 @@
-# AGENTS: ZTD Test Guidelines
-
-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.
-
----
-
-## 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.
-
----
-
-## Use generated types only (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/`.
-
-Forbidden example:
-
-```typescript
-type CategoryTestRow = {
-  category_id: number;
-  parent_id: number | null;
-  name: string;
-};
-```
-
-If a required type is missing:
-- Regenerate generated artifacts (`npx ztd ztd-config`), or
-- 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.
-
----
-
-## Stateless test design (important)
-
-- ZTD tests are **stateless by design**.
-- Do not write tests that depend on state accumulating across multiple repository calls.
-
-Forbidden patterns include:
-- Updating the same record in multiple steps and verifying later state
-- Calling multiple repository methods assuming earlier calls affected the database
-
-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
-
-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.
-
----
-
-## 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.
-- 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
+# 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

@@ -0,0 +1,23 @@
+# 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

@@ -0,0 +1,25 @@
+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

@@ -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,24 @@
+# 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,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.
- */
-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();
-  };
-}
-
+/**
+ * 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;
+}