@rawsql-ts/ztd-cli 0.17.0 → 0.19.0

package/templates/src/AGENTS.md

@@ -1,26 +1,26 @@
-# src AGENTS
-
-This directory is runtime application code.
-
-## Boundaries
-
-- Code under "src/" MUST NOT import from:
-  - "tests/"
-  - "tests/generated/"
-  - any test-only helpers
-- Runtime code MUST NOT depend on ZTD internals.
-- Generated artifacts are test-only signals, not runtime dependencies.
-
-## Implementation principles
-
-- Keep modules small and explicit.
-- Prefer explicit contracts over inference.
-- Favor deterministic behavior and clear error surfaces.
-
-## Verification (required)
-
-After changes:
-- Run the project typecheck command (example: "pnpm typecheck").
-- Run relevant tests (example: "pnpm test" or a filtered command).
-
-If you touched SQL contracts or catalog specs, run tests that exercise them.
+# Package Scope
+- Applies to `packages/ztd-cli/templates/src`.
+- Governs runtime application code emitted by template generation across both generic and WebAPI-oriented layouts.
+
+# Policy
+## REQUIRED
+- Runtime code under `src/` MUST remain independent from `tests/` and `tests/generated/` imports.
+- Runtime code MUST remain independent from ZTD internals.
+- Runtime modules MUST use explicit contracts and deterministic failure surfaces.
+- Domain, application, and presentation layers MUST stay free from direct SQL/DDL ownership when those directories exist.
+
+## ALLOWED
+- Runtime modules MAY use project typecheck and filtered test commands for validation.
+
+## PROHIBITED
+- Importing test-only helpers into runtime code.
+- Treating generated artifacts as runtime dependencies.
+
+# Mandatory Workflow
+- Before committing changes under `src/`, run project typecheck and relevant tests.
+
+# Hygiene
+- Keep runtime modules explicit and small enough to preserve contract boundaries.
+
+# References
+- Parent policy: [../AGENTS.md](../AGENTS.md)

package/templates/src/application/AGENTS.md

@@ -0,0 +1,15 @@
+# Package Scope
+- Applies to `packages/ztd-cli/templates/src/application`.
+- Defines application-layer orchestration for WebAPI-oriented scaffolds.
+
+# Policy
+## REQUIRED
+- Application modules MUST orchestrate domain-facing ports and policies without embedding transport or SQL details.
+- Validation and command handling MAY live here when it stays independent from persistence mechanics.
+
+## PROHIBITED
+- Direct SQL file access.
+- Direct dependence on DDL or QuerySpec implementation details.
+
+# Mandatory Workflow
+- Application changes MUST run the relevant typecheck and behavioral tests.

package/templates/src/application/README.md

@@ -0,0 +1,6 @@
+# Application
+
+Use cases and orchestration live here.
+
+- Coordinate domain behavior and repository ports here.
+- Avoid direct ownership of SQL, DDL, and ZTD configuration in this layer.

package/templates/src/catalog/AGENTS.md

@@ -1,37 +1,28 @@
-# src/catalog AGENTS
-
-This directory is runtime code.
-
-## Purpose
-
-Catalog defines named query entry points by binding:
-- SQL assets ("src/sql/*.sql")
-- input parameter contracts
-- output DTO contracts
-- validation and mapping behavior
-- observability hooks (if supported)
-
-## Directory roles (important)
-
-- "src/catalog/specs": human-owned contracts (params + DTO + semantics)
-- "src/catalog/runtime": AI-assisted runtime wiring (executors, helpers, sinks)
-
-## Non-negotiable ownership
-
-- Specs are contracts. Do not infer, guess, widen, or narrow them.
-- Do not change params / DTO shapes in "specs" without explicit instruction.
-
-## Boundaries
-
-- Code under "src/catalog/" MUST NOT import from:
-  - "tests/"
-  - "tests/generated/"
-  - "ztd/"
-- Do not depend on ZTD internals at runtime.
-
-## Testing rule (required)
-
-Every spec MUST have tests that verify:
-- SQL executes under ZTD rewriting
-- mapping/validation behavior is correct (success and failure)
-- output DTO shape matches expectations
+# Package Scope
+- Applies to `packages/ztd-cli/templates/src/catalog`.
+- Defines runtime catalog contract boundaries between human-owned specs and runtime wiring.
+
+# Policy
+## REQUIRED
+- Catalog entrypoints MUST bind SQL assets, parameter contracts, output contracts, and runtime validation/mapping.
+- `src/catalog/specs` MUST be treated as human-owned contracts.
+- `src/catalog/runtime` MUST implement runtime wiring only.
+- Code in `src/catalog` MUST remain independent from `tests`, `tests/generated`, and `ztd` imports.
+- Each spec MUST be covered by tests for rewrite execution, mapping/validation outcomes, and output shape.
+
+## ALLOWED
+- Runtime catalog code MAY add observability hooks where contract behavior is unchanged.
+
+## PROHIBITED
+- Changing spec params/DTO contracts without explicit instruction.
+- Runtime dependency on ZTD internals.
+
+# Mandatory Workflow
+- Catalog spec or runtime changes MUST run tests that exercise affected specs.
+
+# Hygiene
+- Preserve clear separation between `specs` and `runtime` responsibilities.
+
+# References
+- Specs contract: [./specs/AGENTS.md](./specs/AGENTS.md)
+- Runtime contract: [./runtime/AGENTS.md](./runtime/AGENTS.md)

package/templates/src/catalog/runtime/AGENTS.md

@@ -1,75 +1,28 @@
-# src/catalog/runtime AGENTS
-
-This directory contains runtime wiring for catalog specs:
-- parameter validation entrypoints
-- row-to-DTO mapping
-- output validation
-
-## Runtime classification
-
-- This is a runtime directory.
-- Code here is executed/loaded by the application.
-
-## Responsibilities (critical)
-
-- Runtime MUST be the only place that:
-  - validates unknown inputs into typed params
-  - maps SQL rows (snake_case) into DTO objects
-  - validates DTO outputs before returning to repositories
-- Runtime output validation MUST follow the output contract type (DTO or scalar).
-- Command outputs MAY be scalar identifiers or `void`; DTO mapping is required only when the output contract is DTO.
-
-Repositories MUST call runtime helpers (ensure*/map*) and MUST NOT bypass them.
-
-## Validator requirement (required)
-
-- A validator library (zod or arktype) is always available.
-- Runtime MUST apply validators for:
-  - input params (unknown -> typed)
-  - outputs (mapped DTO -> validated DTO)
-
-Do not rely on TypeScript types alone.
-
-## SQL row normalization (important)
-
-SQL drivers may return different runtime representations for the same column types.
-Runtime MUST normalize driver-dependent values before validating DTOs.
-
-Required normalization rules:
-- Timestamp columns (e.g. timestamptz) may arrive as Date or string.
-  - Runtime MUST use `timestampFromDriver` from `@rawsql-ts/sql-contract`.
-  - Do NOT re-implement `normalizeTimestamp` locally.
-  - Do NOT call `new Date(...)` directly for driver-dependent timestamp normalization.
-- Numeric columns may arrive as number, string, or bigint depending on driver.
-  - Normalization rules MUST be explicit per contract and MUST NOT be silent.
-
-Never force SQL assets to encode driver-specific behavior.
-
-## Mapping rules (required)
-
-- Keep SQL assets snake_case and DTO-independent.
-- Mapping occurs in runtime:
-  - snake_case row -> DTO-shaped object
-  - apply normalization
-  - validate via spec-owned validator
-- DTO camelCase aliases in SQL are forbidden.
-
-## Entry points (recommended)
-
-Prefer these patterns:
-- `ensureXxxParams(value: unknown): XxxParams` (validate inputs)
-- `mapXxxRowToDto(row: XxxSqlRow): XxxDto` (normalize + validate outputs)
-
-The `map*` functions MUST always validate before returning.
-
-## Error behavior (required)
-
-- Validation errors must fail fast with clear messages.
-- Do not swallow validator errors.
-- Do not silently coerce invalid values unless explicitly defined by the contract.
-
-## Boundaries
-
-- Do not perform database I/O here.
-- Do not import from "tests/" or "tests/generated/".
-- Do not define human-owned contracts here; they live in "src/catalog/specs".
+# Package Scope
+- Applies to `packages/ztd-cli/templates/src/catalog/runtime`.
+- Defines runtime validation, normalization, and row-to-DTO mapping behavior.
+
+# Policy
+## REQUIRED
+- Runtime MUST be the only layer that validates unknown input into typed params and validates output contracts.
+- Runtime MUST map snake_case SQL rows into DTO objects using explicit normalization rules.
+- Timestamp normalization MUST use `timestampFromDriver`.
+- Numeric normalization rules MUST be explicit per contract.
+- Runtime helpers (`ensure*`, `map*`) MUST validate before returning values.
+
+## ALLOWED
+- Command outputs MAY be scalar identifiers or `void` when the contract output is non-DTO.
+
+## PROHIBITED
+- Database I/O in runtime mapping modules.
+- Importing from `tests/` or `tests/generated/`.
+- Defining or editing human-owned contracts in runtime modules.
+
+# Mandatory Workflow
+- Runtime changes MUST run tests that cover normalization and validator failure paths.
+
+# Hygiene
+- Do not swallow validator errors or silently coerce unsupported values.
+
+# References
+- Parent catalog policy: [../AGENTS.md](../AGENTS.md)

package/templates/src/catalog/runtime/_coercions.local-source.ts

@@ -0,0 +1,30 @@
+// Runtime coercions run BEFORE validator schemas.
+// See docs/recipes/mapping-vs-validation.md for pipeline details.
+export function normalizeTimestamp(value: unknown, fieldName?: string): Date {
+  const fieldLabel = fieldName?.trim() ? ` for "${fieldName}"` : '';
+
+  // Preserve valid Date instances while rejecting invalid dates eagerly.
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) {
+      throw new Error(`Invalid Date value${fieldLabel}.`);
+    }
+    return value;
+  }
+
+  // Parse driver-returned timestamp strings after trimming transport whitespace.
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      throw new Error(`Expected a non-empty timestamp string${fieldLabel}.`);
+    }
+
+    const timestamp = Date.parse(trimmed);
+    if (Number.isNaN(timestamp)) {
+      throw new Error(`Invalid timestamp string${fieldLabel}: "${value}".`);
+    }
+    return new Date(timestamp);
+  }
+
+  const actualType = value === null ? 'null' : typeof value;
+  throw new Error(`Expected Date or timestamp string${fieldLabel}, received ${actualType}.`);
+}

package/templates/src/catalog/runtime/_coercions.ts

@@ -1 +1,30 @@
-export { timestampFromDriver as normalizeTimestamp } from '@rawsql-ts/sql-contract';
+// Runtime coercions run BEFORE validator schemas.
+// See docs/recipes/mapping-vs-validation.md for pipeline details.
+export function normalizeTimestamp(value: unknown, fieldName?: string): Date {
+  const fieldLabel = fieldName?.trim() ? ` for "${fieldName}"` : '';
+
+  // Preserve valid Date instances while rejecting invalid dates eagerly.
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) {
+      throw new Error(`Invalid Date value${fieldLabel}.`);
+    }
+    return value;
+  }
+
+  // Parse driver-returned timestamp strings after trimming transport whitespace.
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      throw new Error(`Expected a non-empty timestamp string${fieldLabel}.`);
+    }
+
+    const timestamp = Date.parse(trimmed);
+    if (Number.isNaN(timestamp)) {
+      throw new Error(`Invalid timestamp string${fieldLabel}: "${value}".`);
+    }
+    return new Date(timestamp);
+  }
+
+  const actualType = value === null ? 'null' : typeof value;
+  throw new Error(`Expected Date or timestamp string${fieldLabel}, received ${actualType}.`);
+}

package/templates/src/catalog/runtime/_smoke.runtime.ts

@@ -1,21 +1,21 @@
-import { parseSmokeOutput, type SmokeOutput } from '../specs/_smoke.spec';
-import { normalizeTimestamp } from './_coercions';
-
-/**
- * Validate runtime output against the catalog smoke invariant.
- */
-export function ensureSmokeOutput(value: unknown): SmokeOutput {
-  // Normalize driver-dependent timestamp representations before contract validation.
-  if (isRecord(value) && 'createdAt' in value) {
-    return parseSmokeOutput({
-      ...value,
-      createdAt: normalizeTimestamp(value.createdAt, 'createdAt')
-    });
-  }
-
-  return parseSmokeOutput(value);
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null;
-}
+import { parseSmokeOutput, type SmokeOutput } from '../specs/_smoke.spec';
+import { normalizeTimestamp } from './_coercions';
+
+/**
+ * Validate runtime output against the catalog smoke invariant.
+ */
+export function ensureSmokeOutput(value: unknown): SmokeOutput {
+  // Normalize driver-dependent timestamp representations before contract validation.
+  if (isRecord(value) && 'createdAt' in value) {
+    return parseSmokeOutput({
+      ...value,
+      createdAt: normalizeTimestamp(value.createdAt, 'createdAt')
+    });
+  }
+
+  return parseSmokeOutput(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}

package/templates/src/catalog/specs/AGENTS.md

@@ -1,48 +1,41 @@
-# src/catalog/specs AGENTS
-
-This directory defines query and command specifications (contracts).
-
-## Runtime classification
-
-- This is a runtime directory.
-- Contents are human-owned contracts, not implementation details.
-
-## Ownership (critical)
-
-- Specs are human-owned.
-- Input parameters are part of the domain contract.
-- Output DTO shapes are part of the domain contract.
-- Cardinality and semantics are part of the domain contract.
-
-AI MUST NOT:
-- infer missing parameters
-- widen or narrow DTO shapes
-- change nullability or optionality
-- change CUD return shape implicitly
-
-Changes require explicit human instruction.
-
-## Validator requirement (required)
-
-- A validator library (zod or arktype) is always available.
-- Every spec MUST define validators for its public inputs/outputs.
-- Validators are part of the contract and are human-owned.
-
-## Driver variability policy (important)
-
-Specs MUST NOT require SQL assets to encode driver-specific workarounds.
-
-- Specs may acknowledge that SQL rows can vary in representation by driver
-  (e.g. timestamps as Date or string).
-- Normalization for driver-dependent values is implemented in catalog runtime,
-  then validated against the spec.
-
-Contracts define the final DTO shape.
-Runtime defines normalization steps to reach that shape.
-
-## What does NOT belong here
-
-- No executors
-- No database connections
-- No ZTD internals
-- No SQL camelCase aliasing rules (SQL rules live under src/sql)
+# Package Scope
+- Applies to `packages/ztd-cli/templates/src/catalog/specs`.
+- Defines human-owned query/command contracts for params, DTOs, and semantics.
+
+# Policy
+## REQUIRED
+- Specs MUST define public input and output validators.
+- Specs MUST preserve declared parameter shape, DTO shape, nullability, cardinality, and semantics.
+- Driver-dependent normalization behavior MUST be specified for runtime handling, not SQL workaround encoding.
+
+## ALLOWED
+- Specs MAY acknowledge driver representation variance when runtime normalization is defined.
+
+## PROHIBITED
+- Inferring or modifying contract shape without explicit instruction.
+- Adding executors, DB connections, or ZTD internal dependencies.
+
+# Mandatory Workflow
+- Contract changes MUST run tests that validate success and failure paths.
+
+## Generating initial output types
+
+Use `npx ztd model-gen <sql-file> --probe-mode ztd --out src/catalog/specs/<spec-file>.ts` to derive the first QuerySpec scaffold from the local DDL snapshot.
+
+- SQL assets are expected to use named parameters (`:name`).
+- `ztd model-gen` is names-first and derives `sqlFile` / `spec id` from the SQL path under `src/sql` by default.
+- `ztd model-gen --probe-mode ztd` is the recommended fast-loop path when the referenced schema already exists in `ztd/ddl/*.sql`.
+- In `--probe-mode ztd`, unqualified table references follow the configured `defaultSchema` / `searchPath` priority from `ztd.config.json`.
+- The CLI default remains `--probe-mode live` for backward compatibility, but project guidance should treat `--probe-mode ztd` as the preferred inner-loop mode.
+- `ztd model-gen --probe-mode ztd` uses the ZTD-owned test database from `ZTD_TEST_DATABASE_URL`.
+- `ztd model-gen --probe-mode live` is an explicit target inspection path and MUST be used with `--url` or a complete `--db-*` flag set.
+- `DATABASE_URL` is a runtime concern and is not read implicitly by `ztd-cli`.
+- Positional placeholders are legacy and should be rewritten whenever possible.
+- Use `--allow-positional` only when a legacy SQL asset cannot be rewritten immediately.
+- Review the generated file before commit: confirm imports, nullability, cardinality, rowMapping key, runtime normalization, and example values.
+
+# Hygiene
+- Keep contract definitions isolated from runtime wiring and SQL implementation logic.
+
+# References
+- Parent catalog policy: [../AGENTS.md](../AGENTS.md)

package/templates/src/catalog/specs/_smoke.spec.arktype.ts

@@ -1,21 +1,21 @@
-import { type } from 'arktype';
-
-/**
- * Validator invariant contract used to prove runtime validation wiring.
- *
- * This file is intentionally minimal and domain-agnostic.
- */
-export const smokeOutputSchema = type({
-  id: 'number.integer',
-  createdAt: 'Date'
-});
-
-export type SmokeOutput = ReturnType<typeof smokeOutputSchema>;
-
-/**
- * Parse and validate an unknown runtime payload.
- */
-export function parseSmokeOutput(value: unknown): SmokeOutput {
-  smokeOutputSchema.assert(value);
-  return value as SmokeOutput;
-}
+import { type } from 'arktype';
+
+/**
+ * Validator invariant contract used to prove runtime validation wiring.
+ *
+ * This file is intentionally minimal and domain-agnostic.
+ */
+export const smokeOutputSchema = type({
+  id: 'number.integer',
+  createdAt: 'Date'
+});
+
+export type SmokeOutput = ReturnType<typeof smokeOutputSchema>;
+
+/**
+ * Parse and validate an unknown runtime payload.
+ */
+export function parseSmokeOutput(value: unknown): SmokeOutput {
+  smokeOutputSchema.assert(value);
+  return value as SmokeOutput;
+}

package/templates/src/catalog/specs/_smoke.spec.zod.ts

@@ -1,20 +1,20 @@
-import { z } from 'zod';
-
-/**
- * Validator invariant contract used to prove runtime validation wiring.
- *
- * This file is intentionally minimal and domain-agnostic.
- */
-export const smokeOutputSchema = z.object({
-  id: z.number().int(),
-  createdAt: z.date()
-});
-
-export type SmokeOutput = z.infer<typeof smokeOutputSchema>;
-
-/**
- * Parse and validate an unknown runtime payload.
- */
-export function parseSmokeOutput(value: unknown): SmokeOutput {
-  return smokeOutputSchema.parse(value);
-}
+import { z } from 'zod';
+
+/**
+ * Validator invariant contract used to prove runtime validation wiring.
+ *
+ * This file is intentionally minimal and domain-agnostic.
+ */
+export const smokeOutputSchema = z.object({
+  id: z.number().int(),
+  createdAt: z.date()
+});
+
+export type SmokeOutput = z.infer<typeof smokeOutputSchema>;
+
+/**
+ * Parse and validate an unknown runtime payload.
+ */
+export function parseSmokeOutput(value: unknown): SmokeOutput {
+  return smokeOutputSchema.parse(value);
+}

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

@@ -0,0 +1,32 @@
+import type { SqlClient } from './sql-client';
+
+/**
+ * Adapt a `pg`-style queryable (Client or Pool) into a SqlClient.
+ *
+ * pg's `query()` returns `QueryResult<T>` with a `.rows` property.
+ * This helper unwraps the result so it satisfies the `SqlClient` contract.
+ *
+ * Usage:
+ *   const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ *   const client = fromPg(pool);
+ *   const users = await client.query<{ id: number }>('SELECT id ...', []);
+ */
+export function fromPg(
+  queryable: {
+    query(text: string, values?: readonly unknown[]): Promise<{ rows: Record<string, unknown>[] }>;
+  }
+): SqlClient {
+  return {
+    query<T extends Record<string, unknown> = Record<string, unknown>>(
+      text: string,
+      values?: readonly unknown[] | Record<string, unknown>
+    ): Promise<T[]> {
+      if (values != null && !Array.isArray(values)) {
+        throw new Error('fromPg adapter does not support named parameter objects; use positional parameter arrays');
+      }
+      return queryable
+        .query(text, values as readonly unknown[])
+        .then((result) => result.rows as T[]);
+    }
+  };
+}

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

@@ -1,24 +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 this interface to your preferred driver (pg, mysql2, etc.) and normalize the results to `T[]`.
- * - Tests: replace the implementation with a mock, a fixture helper, or an adapter that follows this contract.
- *
- * Connection strategy note:
- * - Prefer a shared client per worker process for better performance.
- * - Do not share a live client across parallel workers without proper synchronization.
- */
-export type SqlClient = {
-  query<T extends Record<string, unknown> = Record<string, unknown>>(
-    text: string,
-    values?: readonly unknown[] | Record<string, unknown>
-  ): SqlQueryRows<T>;
-};
+/**
+ * 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 this interface to your preferred driver (pg, mysql2, etc.) and normalize the results to `T[]`.
+ * - Tests: replace the implementation with a mock, a fixture helper, or an adapter that follows this contract.
+ *
+ * Connection strategy note:
+ * - Prefer a shared client per worker process for better performance.
+ * - Do not share a live client across parallel workers without proper synchronization.
+ */
+export type SqlClient = {
+  query<T extends Record<string, unknown> = Record<string, unknown>>(
+    text: string,
+    values?: readonly unknown[] | Record<string, unknown>
+  ): SqlQueryRows<T>;
+};

package/templates/src/domain/AGENTS.md

@@ -0,0 +1,15 @@
+# Package Scope
+- Applies to `packages/ztd-cli/templates/src/domain`.
+- Defines the domain layer for WebAPI-oriented scaffolds.
+
+# Policy
+## REQUIRED
+- Domain code MUST remain independent from SQL, DDL, QuerySpecs, and generated test artifacts.
+- Domain modules MUST express business rules in transport-agnostic types.
+
+## PROHIBITED
+- Importing `src/sql`, `src/catalog`, `ztd`, or telemetry scaffolds into domain code.
+- Encoding HTTP or persistence concerns in domain rules.
+
+# Mandatory Workflow
+- Domain changes MUST run the relevant typecheck and unit tests.

package/templates/src/domain/README.md

@@ -0,0 +1,6 @@
+# Domain
+
+Domain types, invariants, and business rules live here.
+
+- Do not import SQL files, QuerySpecs, or ZTD-generated artifacts into this layer.
+- Prefer ports or plain interfaces for dependencies on application or infrastructure code.