Merge pull request #433 from mk3008/feat/ztd-cli-zero-deps

Refactor ztd-cli to reduce dependencies and support named parameters

Author: mk3008

.changeset/catalog-runtime-timestamp-normalization.md

@@ -0,0 +1,8 @@
+---
+"@rawsql-ts/sql-contract": minor
+"@rawsql-ts/ztd-cli": patch
+---
+
+Add a new public `timestampFromDriver(value, fieldName?)` helper in `@rawsql-ts/sql-contract` for fail-fast `Date | string` normalization of driver-returned timestamps.
+
+Update `@rawsql-ts/ztd-cli` templates to normalize runtime timestamp fields through the shared sql-contract helper (via runtime coercion wiring), add strict guardrails against local timestamp re-implementation, and expand scaffold smoke validation tests for valid and invalid timestamp strings.

.changeset/sql-first-binder.md

@@ -0,0 +1,6 @@
+---
+"@rawsql-ts/ztd-cli": minor
+"@rawsql-ts/adapter-node-pg": patch
+---
+
+Adopt SQL-first scaffolding with named-parameter SQL layout in the ZTD template, and compile named parameters to indexed placeholders in the pg adapter.

.changeset/ztd-cli-init-minimal-scaffold.md

@@ -0,0 +1,5 @@
+---
+"@rawsql-ts/ztd-cli": minor
+---
+
+Redesign `ztd init` to produce a deterministic minimal scaffold with per-folder AGENTS.md guidance and option-specific DDL seeding only (pg_dump, empty, or demo DDL).

.changeset/ztd-cli-scaffold-structure.md

@@ -0,0 +1,5 @@
+---
+"@rawsql-ts/ztd-cli": minor
+---
+
+Add the new default ZTD scaffold layout with view SQL under "src/sql/views", job SQL under "src/sql/jobs", and repositories split between "src/repositories/views" and "src/repositories/tables". The init command now supports "--yes" to overwrite existing scaffold files without prompts for non-interactive runs.

.github/workflows/pr-check.yml

@@ -32,7 +32,18 @@ jobs:
         pnpm --filter @rawsql-ts/testkit-core run build
         pnpm --filter @rawsql-ts/ztd-cli run build
 
+    - name: Detect deprecated playground
+      id: playground
+      run: |
+        if [ -d "./playgrounds/ztd-playground" ]; then
+          echo "exists=true" >> "$GITHUB_OUTPUT"
+        else
+          echo "exists=false" >> "$GITHUB_OUTPUT"
+          echo "playgrounds/ztd-playground is removed; skipping playground artifact generation."
+        fi
+
     - name: Generate ZTD artifacts (playground)
+      if: steps.playground.outputs.exists == 'true'
       working-directory: ./playgrounds/ztd-playground
       run: node ../../packages/ztd-cli/dist/index.js ztd-config
 

.gitignore

@@ -191,3 +191,4 @@ docs/.vitepress/dist
 docs/.vitepress/cache
 
 CONTINUITY.md
+playgrounds/ztd-playground/

AGENTS.md

@@ -106,6 +106,8 @@ When changing schemas or search paths, update `ztd.config.json` accordingly.
 * Use `pnpm` and `pnpm --filter <package>` for scoped tasks.
 * All identifiers, comments, and documentation must be written in English.
 * Use `./tmp` for throwaway assets.
+* In tests, do not duplicate production normalization or sanitization rules; import shared helpers from source modules whenever those helpers are deterministic and side-effect free.
+* In docs, avoid directional wording like "below" when pointing to separate recipe files; use explicit Markdown links to the target document.
 * README and driver demos must exercise the rewrite and fixture helpers located at
   `packages/sql-contract/tests/readme/support/postgres-demo.ts`.
 * Remove console debugging statements before committing.
@@ -136,6 +138,12 @@ Run the following before opening or updating a PR:
 
 ---
 
+## Validation tooling recipes
+
+- Every ZTD project installs `@rawsql-ts/sql-contract` and a validator backend during `ztd init`, so `docs/recipes/sql-contract.md` is the canonical mapping reference.
+- When both `@rawsql-ts/sql-contract` and `zod` are declared, follow the Zod validator flow in `docs/recipes/validation-zod.md`. Installing `@rawsql-ts/sql-contract-zod` is optional sugar that adds `mapper.zod` and coercion helpers on top of the same base stack.
+- When `@rawsql-ts/sql-contract` is present without `zod` but `arktype` is declared, follow the ArkType recipe in `docs/recipes/validation-arktype.md`.
+
 ## Docs Demo Updates
 
 * Rebuild the browser bundle when parser or formatter behavior changes:

docs/recipes/sql-contract.md

@@ -0,0 +1,58 @@
+---
+title: SQL catalog & mapping recipe
+---
+
+# SQL catalog & mapping recipe
+
+When `ztd init` enables runtime validation, it always installs `@rawsql-ts/sql-contract` so you can map raw SQL rows into DTOs without duplicating column metadata.
+
+## Install
+
+```bash
+pnpm add -D @rawsql-ts/sql-contract
+```
+
+## What to wire
+
+- Use `createReader` (and `createWriter` when you need CUD helpers) to wrap the executor that appears in `tests/support/testkit-client.ts`.
+- Bind domain-specific `rowMapping` definitions to the reader so DTO shapes stay explicit and reusable.
+- Refer to `tests/generated/ztd-row-map.generated.ts` for authoritative row types and `src/repositories/*` for repository contracts.
+
+### Example (`tests/support/testkit-client.ts`)
+
+```ts
+import type { SqlClient } from '../../src/db/sql-client';
+import { createReader } from '@rawsql-ts/sql-contract/mapper';
+import { rowMapping } from '@rawsql-ts/sql-contract/mapper';
+import { getSqlClient } from '../support/sql-client-factory';
+
+const executor = async (sql: string, params: readonly unknown[]) => {
+  const client: SqlClient = await getSqlClient();
+  const rows = await client.query(sql, params);
+  return rows;
+};
+
+const userMapping = rowMapping({
+  name: 'UserProfile',
+  key: 'userAccountId',
+  columnMap: {
+    userAccountId: 'user_account_id',
+    displayName: 'display_name',
+  },
+});
+
+const reader = createReader(executor);
+
+export async function listUserProfiles() {
+  return reader.bind(userMapping).list(
+    'SELECT user_account_id, display_name FROM public.user_account',
+    []
+  );
+}
+```
+
+The reader above can be used directly in tests or shared helpers so the same SQL, mapping, and fixtures power every suite.
+
+## What’s next
+
+- Wire runtime validation by following the [Zod](./validation-zod.md) or [ArkType](./validation-arktype.md) recipe. Validation is required for every ZTD project, so keep your chosen validator aligned with the reader/writer wiring.

docs/recipes/validation-arktype.md

@@ -0,0 +1,51 @@
+---
+title: Validation recipe (ArkType)
+---
+
+# Validation recipe (ArkType)
+
+Selecting ArkType as the runtime validator installs `arktype` so you can validate every DTO using its expressive schema syntax while still executing SQL through `@rawsql-ts/sql-contract`. The runtime hook uses `reader.validator(...)`, so no additional helper package is required beyond `arktype`.
+
+## Install
+
+```bash
+pnpm add -D @rawsql-ts/sql-contract arktype
+```
+
+## Example snippet
+
+```ts
+import { type } from 'arktype';
+import { createReader } from '@rawsql-ts/sql-contract/mapper';
+import { getSqlClient } from '../support/sql-client-factory';
+
+const executor = async (sql: string, params: readonly unknown[]) => {
+  const client = await getSqlClient();
+  return client.query(sql, params);
+};
+
+const reader = createReader(executor);
+
+const CustomerSchema = type({
+  customerId: 'number',
+  customerName: 'string',
+});
+
+type Customer = ReturnType<typeof CustomerSchema>;
+
+export async function listCustomers(): Promise<Customer[]> {
+  return reader
+    .validator((value) => {
+      CustomerSchema.assert(value);
+      return value as Customer;
+    })
+    .list('SELECT customer_id, customer_name FROM public.user_account', []);
+}
+```
+
+This validator wraps the ArkType schema, asserts the DTO shape, and returns the typed value so the mapper pipeline remains untouched.
+
+## Related recipes
+
+- Use the SQL contract recipe for the base reader/writer wiring (`docs/recipes/sql-contract.md`).
+- The Zod recipe describes the alternate runtime validator (`docs/recipes/validation-zod.md`).

docs/recipes/validation-zod.md

@@ -0,0 +1,48 @@
+---
+title: Validation recipe (Zod)
+---
+
+# Validation recipe (Zod)
+
+ZTD init always selects a validator backend. When Zod is chosen, you can wire schemas through `@rawsql-ts/sql-contract` without additional helpers.
+
+## Install
+
+```bash
+pnpm add -D @rawsql-ts/sql-contract zod
+```
+
+`@rawsql-ts/sql-contract` exposes `reader.validator`, which accepts Zod schemas because they implement `parse(value)` (see `ReaderValidatorInput`). For convenience you can still install `@rawsql-ts/sql-contract-zod` if you want the `reader.zod` helper and numeric coercion helpers described in its README, but the base stack only requires `zod`.
+
+## Example snippet
+
+```ts
+import { z } from 'zod';
+import { createReader } from '@rawsql-ts/sql-contract/mapper';
+import { getSqlClient } from '../support/sql-client-factory';
+
+const executor = async (sql: string, params: readonly unknown[]) => {
+  const client = await getSqlClient();
+  return client.query(sql, params);
+};
+
+const reader = createReader(executor);
+
+const CustomerSchema = z.object({
+  customerId: z.number(),
+  customerName: z.string(),
+});
+
+export async function listCustomers() {
+  return reader.validator(CustomerSchema).list(
+    'SELECT customer_id, customer_name FROM public.user_account',
+    []
+  );
+}
+```
+
+Zod validation runs after the mapper binds every row to the DTO, so schema errors surface before tests rely on the result shape.
+
+## Optional helper: @rawsql-ts/sql-contract-zod
+
+`@rawsql-ts/sql-contract-zod` depends on the core mapper and adds the `mapper.zod` helper plus Zod-aware coercion helpers such as `zNumberFromString`. Install it only if you prefer those dedicated APIs; `@rawsql-ts/sql-contract` plus `zod` covers the required validator flow.