@rawsql-ts/ztd-cli 0.16.0 → 0.19.0

package/templates/README.md

@@ -1,217 +1,46 @@
-# Zero Table Dependency Project
-
-This project organizes all SQL‑related artifacts under the `ztd/` directory, separating concerns so both humans and AI can collaborate effectively without interfering with each other's responsibilities.
-
-```
-/ztd
-  /ddl
-    *.sql            <- schema definitions (required)
-  README.md          <- documentation for the layout
-  AGENTS.md          <- combined guidance for DDL
-
-/src                 <- application & repository code
-/tests               <- ZTD tests, fixtures, generated maps
-```
-
-Only `ztd/ddl` is part of the template contract. Do not create or assume other `ztd` subdirectories unless the project explicitly adds them.
-
-## Generated files (important)
-
-`tests/generated/` is auto-generated and must never be committed to git.
-After cloning the repository (or in a clean environment), run (strongly recommended):
-
-```bash
-npx ztd ztd-config
-```
-
-If TypeScript reports missing modules or type errors because `tests/generated/` is missing, rerun `npx ztd ztd-config`.
-
-`tests/generated/ztd-layout.generated.ts` declares the directories above so the CLI and your tests always point at the intended files. The authoritative directory remains `ztd/ddl/`; do not read or assume additional `ztd` subdirectories.
-
----
-
-# Optional SqlClient seam
-
-If this project was initialized with `npx ztd init --with-sqlclient`, you'll also have `src/db/sql-client.ts`.
-It defines a minimal `SqlClient` interface that repositories can depend on:
-
-- Use it for tutorials and greenfield projects to keep repository SQL decoupled from drivers.
-- Skip it when you already have a database abstraction (Prisma, Drizzle, Kysely, custom adapters).
-- For `pg`, adapt `client.query(...)` so it returns a plain `T[]` row array that matches the interface.
-- Prefer a shared client per worker process so tests and scripts do not reconnect on every query.
-- Do not share a live connection across parallel workers; each worker should own its own shared client.
-
-Example (driver-agnostic):
-
-```ts
-let sharedClient: SqlClient | undefined;
-
-export function getSqlClient(): SqlClient {
-  if (!sharedClient) {
-    // Create the client once using your chosen driver (pg, mysql, etc.).
-    sharedClient = createSqlClientOnce();
-  }
-  return sharedClient;
-}
-```
-
----
-
-# Mapper + writer sample
-
-- This scaffold already exposes `src/repositories/user-accounts.ts`, which maps `public.user_account` rows together with optional `public.user_profile` data through `@rawsql-ts/sql-contract/mapper` and emits insert/update/remove helpers via `@rawsql-ts/sql-contract/writer`.
-- The SQL used here is defined in `src/repositories/user-accounts.ts`; the template tests exercise that implementation and `ztd/ddl` is the authoritative source for every column and constraint.
-- Two template tests demonstrate how to run the stitch:
-  - `tests/user-profiles.test.ts` seeds fixtures, executes the query through the mapper, and verifies the DTO shape.
-  - `tests/writer-constraints.test.ts` reads `userAccountWriterColumnSets` plus `tests/generated/ztd-row-map.generated.ts` so writer callers stay within the approved column set when referencing `public.user_account`.
-- Regenerate `tests/generated/ztd-row-map.generated.ts` (`npx ztd ztd-config`) before running the example tests so the row map reflects any schema changes.
-- The example tests require a real PostgreSQL connection via `DATABASE_URL`; they automatically skip when the variable is missing so local tooling stays fast.
-
-# Principles
-
-### 1. Humans own the *definitions*
-- DDL (physical schema)
-  Only `ztd/ddl` is part of the template contract; other subdirectories should not be assumed.
-
-### 2. AI owns the *implementation*
-- Repository SQL generation
-- Test fixture updates
-- Intermediate TypeScript structures
-- SQL rewriting, parameter binding, shape resolution
-
-### 3. ZTD ensures these stay in sync
-ZTD acts as the consistency layer ensuring:
-- DDL → SQL shape consistency
-- Do not rely on other directories unless the project explicitly adds them.
-
-If any part diverges, ZTD tests fail deterministically.
-
----
-
-# Workflow Overview
-
-Different tasks start from different entry points. Choose the workflow that matches what you want to change.
-
----
-
-# Workflow A — Starting From *DDL Changes*  
-(Adding tables/columns, changing constraints)
-
-1. Edit files under `ztd/ddl/`.
-2. Run:
-
-   ```bash
-   npx ztd ztd-config
-   ```
-
-   This regenerates `tests/generated/ztd-row-map.generated.ts` from the new schema.
-
-3. Update repository SQL so it matches the new schema.
-4. Update fixtures if shapes changed.
-5. Run tests. Any schema mismatch will fail fast.
-
-**Flow:**  
-**DDL -> repository SQL -> fixtures/tests -> application**
-
----
-
-# Workflow B — Starting From *Repository Interface Changes*  
-(Adding a method, changing return types, etc.)
-
-1. Modify the repository interface or class in `/src`.
-2. Allow AI to generate the SQL needed to satisfy the interface.
-3. If the query contradicts DDL, reconcile the authoritative definition before continuing.
-4. Run ZTD tests to confirm logic is consistent.
-5. Regenerate ZTD config if result shapes changed.
-
-**Flow:**  
-**repository interface -> SQL -> tests**
-
----
-
-# Workflow C — Starting From Repository SQL Logic Changes
-(Fixing a bug, optimizing logic, rewriting a query)
-
-1. Edit SQL inside the repository.
-2. Run ZTD tests.
-3. If the intended behavior changes, update the DDL before adjusting dependent logic and keep documentation aligned with the confirmed schema.
-4. Update fixtures as necessary.
-5. If SQL result shape changed, run:
-
-   ```bash
-   npx ztd ztd-config
-   ```
-
-**Flow:**  
-**SQL -> fixtures/tests**
-
----
-
-# Combined Real‑World Flow Examples
-
-- **Add a new contract status**  
-  DDL -> SQL -> config -> tests
-
-- **Add a new table**  
-  DDL -> config -> SQL -> fixtures -> tests
-
-- **Fix business logic**  
-  SQL -> tests
-
-ZTD ensures all changes converge into a consistent, validated workflow.
----
-
-# Human Responsibilities
-
-- Humans maintain:
-  - Physical schema (`ddl`)
-  - High‑level repository interfaces
-  - Acceptance of AI-generated changes
-
-Humans decide “what is correct.”
-
----
-
-# AI Responsibilities
-
-AI must:
-
-  - Use DDL as the **physical shape constraint** and primary source of truth.
-  - Do not assume any additional `ztd` directories exist unless a human explicitly creates them.
-  - Generate repository SQL consistent with DDL and the documented behavior.
-  - Regenerate fixtures and tests as instructed.
-  - Never modify `ztd/AGENTS.md` or `ztd/README.md` unless explicitly asked.
-
-AI decides “how to implement” within those constraints.
-
----
-
-# ZTD CLI Responsibilities
-
-ZTD CLI:
-
-- Parses DDL files to build accurate table/column shapes
-- Rewrites SQL with fixture-based CTE shadowing (via testkit adapters)
-- Generates `ztd-row-map.generated.ts`
-- Produces deterministic, parallelizable tests
-
-ZTD is the verification engine guaranteeing correctness.
-
-## Traditional execution mode
-
-- Set `ZTD_EXECUTION_MODE=traditional` or pass `{ mode: 'traditional', traditional: { isolation: 'schema', cleanup: 'drop_schema' } }` when you need to run the tests against a real Postgres schema (locking, isolation, constraints). The helper still applies the DDL inside `ztd/ddl/`, loads the fixture rows into the schema, optionally executes `setupSql`, and carries out the chosen cleanup strategy (`drop_schema`, `custom_sql`, or `none`).
-- Use `isolation: 'none'` if you need to target a schema that is already defined or if your SQL embeds schema qualifiers explicitly.
-
----
-
-# Summary
-
-ZTD enables a workflow where **humans define meaning**, **AI writes implementation**, and **tests guarantee correctness**.
-
-The project layout and workflows above ensure long-term maintainability, clarity, and full reproducibility of SQL logic independent of physical database state.
-
-## Recommended local verification
-
-- `npx ztd ztd-config` (Recommended)
-- `pnpm -C packages/ztd-cli test` (Recommended)
-- `templates/tests/user-profiles.test.ts` runs only when `DATABASE_URL` is configured; otherwise it skips automatically.
+# Zero Table Dependency Project
+
+This project uses Zero Table Dependency (ZTD) to keep SQL, DDL, and tests aligned.
+
+Conceptual model:
+- `ztd-cli` implicitly uses only `ZTD_TEST_DATABASE_URL`.
+- `DATABASE_URL` and other runtime or deployment database settings are outside the ownership of `ztd-cli`.
+- Any non-ZTD database target must be passed explicitly via `--url` or `--db-*`.
+- `ztd-cli` may generate migration SQL artifacts, but it does not apply them.
+
+Quick boundary table:
+- `ZTD_TEST_DATABASE_URL`: owned by `ztd-cli` for ZTD tests and verification
+- `DATABASE_URL`: runtime or deployment concern, not read automatically by `ztd-cli`
+- `--url` / complete `--db-*`: explicit target inspection only
+
+Key folders:
+- ztd/ddl: schema files (source of truth)
+- src: application SQL and repositories
+- tests: ZTD tests and support
+
+Next steps:
+1. Update `ztd/ddl/<schema>.sql` if needed.
+2. Run `pnpm exec ztd ztd-config` (or `npx ztd ztd-config` if you prefer npm-style invocation).
+3. Run `pnpm exec ztd model-gen --probe-mode ztd <sql-file> --out <spec-file>` when you want a QuerySpec scaffold from the local DDL snapshot.
+4. Wire repositories to `src/infrastructure/telemetry/repositoryTelemetry.ts` so application code can replace the default telemetry hook.
+5. Provide a SqlClient implementation.
+6. Run tests (`pnpm test` or `npx vitest run`).
+7. Use `ZTD_TEST_DATABASE_URL` for ZTD-owned test and verification workflows.
+8. Use `ztd model-gen --probe-mode live`, `ztd ddl pull`, or `ztd ddl diff` only for explicit target inspection by passing `--url` or a complete `--db-*` flag set.
+9. If you generate migration SQL artifacts, apply them with your deployment tooling instead of `ztd-cli`.
+
+If this project was scaffolded with `ztd init --local-source-root <monorepo-root>`, first run `pnpm install` (or `pnpm install --ignore-workspace` when nested under another `pnpm-workspace.yaml`), then `pnpm typecheck`, then `pnpm test`, then `pnpm ztd ztd-config`. For generated QuerySpecs, prefer `pnpm ztd model-gen --probe-mode ztd --import-style relative` so imports keep using the local shim.
+
+For schema-change impact checks, `npx ztd query uses` defaults to the `impact` view. Table add / column add checks usually work with the default scan, while table rename / column rename / column type change checks often benefit from `--exclude-generated` so review-only specs under `src/catalog/specs/generated` do not add noise. The flag is optional and does not change the default scan set.
+
+If you later switch this scaffold into a layered WebAPI shape, add a prompt-dogfooding guide similar to `PROMPT_DOGFOOD.md` so generic transport requests can be checked for accidental ZTD leakage.
+
+Examples:
+
+```bash
+pnpm exec ztd query uses table public.sale_items --exclude-generated
+pnpm exec ztd query uses table public.sale_lines --exclude-generated
+pnpm exec ztd query uses column public.products.title --exclude-generated
+pnpm exec ztd query uses column public.sale_items.quantity --exclude-generated
+pnpm exec ztd query uses table public.sale_lines --view detail --exclude-generated
+```

package/templates/README.webapi.md

@@ -0,0 +1,38 @@
+# Zero Table Dependency WebAPI Project
+
+This scaffold separates WebAPI concerns into explicit layers so transport and use-case work do not accidentally inherit persistence-specific rules.
+
+Conceptual model:
+- `ztd-cli` implicitly uses only `ZTD_TEST_DATABASE_URL`.
+- Projects often also have a runtime or deployment database setting such as `DATABASE_URL`, but `ztd-cli` does not read it automatically.
+- Any non-ZTD database target must be passed explicitly via `--url` or `--db-*`.
+- `ztd-cli` may generate migration SQL artifacts, but it does not apply them.
+
+Quick boundary table:
+- `ZTD_TEST_DATABASE_URL`: owned by `ztd-cli` for ZTD tests and verification
+- `DATABASE_URL`: runtime or deployment concern, not read automatically by `ztd-cli`
+- `--url` / complete `--db-*`: explicit target inspection only
+
+Key folders:
+- `src/domain`: domain types and business rules with no direct ZTD dependency
+- `src/application`: use cases and orchestration over domain-facing ports
+- `src/presentation/http`: HTTP handlers, request parsing, and response shaping
+- `src/infrastructure/persistence`: repositories, SQL assets, and QuerySpec wiring
+- `src/sql`, `src/catalog`, `ztd/ddl`: ZTD-owned persistence assets
+- `tests`: smoke tests and test support
+
+Prompt dogfooding:
+- See `PROMPT_DOGFOOD.md` when you want to verify that generic WebAPI requests stay out of persistence-specific ZTD guidance unless repository or SQL work is explicitly requested.
+
+Next steps:
+1. Update `ztd/ddl/<schema>.sql` if needed.
+2. Run `pnpm exec ztd ztd-config` (or `npx ztd ztd-config` if you prefer npm-style invocation).
+3. Keep `src/domain`, `src/application`, and `src/presentation/http` free from direct SQL or DDL concerns.
+4. Use `pnpm exec ztd model-gen --probe-mode ztd <sql-file> --out <spec-file>` when you want a QuerySpec scaffold from the local DDL snapshot.
+5. Wire repositories to `src/infrastructure/telemetry/repositoryTelemetry.ts` only when you add SQL-backed repository classes.
+6. Provide a SqlClient implementation in `src/infrastructure/db`.
+7. Run tests (`pnpm test` or `npx vitest run`) with `ZTD_TEST_DATABASE_URL` when SQL-backed verification needs a managed test database.
+8. Treat `ddl pull` and `ddl diff` as explicit target inspection commands that require `--url` or a complete `--db-*` flag set.
+9. If you generate migration SQL artifacts, apply them outside `ztd-cli`.
+
+If this project was scaffolded with `ztd init --local-source-root <monorepo-root>`, first run `pnpm install` (or `pnpm install --ignore-workspace` when nested under another `pnpm-workspace.yaml`), then `pnpm typecheck`, then `pnpm test`, then `pnpm ztd ztd-config`. For generated QuerySpecs, prefer `pnpm ztd model-gen --probe-mode ztd --import-style relative` so imports keep using the local shim.

package/templates/scripts/local-source-guard.mjs

@@ -0,0 +1,189 @@
+import { createRequire } from 'node:module';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const projectRoot = process.cwd();
+const command = process.argv[2];
+
+if (command !== 'test' && command !== 'typecheck' && command !== 'ztd') {
+  console.error('local-source guard expects "test", "typecheck", or "ztd".');
+  process.exit(1);
+}
+
+if (command === 'ztd') {
+  const cliEntry = path.resolve(projectRoot, '__LOCAL_SOURCE_ZTD_CLI__');
+  const requestedSubcommand = process.argv.slice(3).join(' ').trim() || '(none)';
+  if (!existsSync(cliEntry)) {
+    console.error(
+      [
+        '[local-source guard] ztd cannot run against the local source checkout yet.',
+        '',
+        `What happened:`,
+        `- Requested subcommand: ${requestedSubcommand}`,
+        `- Project root: ${normalizePath(projectRoot)}`,
+        `- The local CLI entry was not found at ${normalizePath(cliEntry)}.`,
+        '',
+        'Next steps:',
+        '1. Build the local CLI package (for example: pnpm --filter @rawsql-ts/ztd-cli build)',
+        '2. Confirm this scaffold still points at the intended rawsql-ts monorepo root',
+        '3. Re-run pnpm ztd <subcommand>'
+      ].join('\n')
+    );
+    process.exit(1);
+  }
+
+  const cliArgs = process.argv.slice(3);
+  const result = spawnSync(process.execPath, [cliEntry, ...cliArgs], {
+    cwd: projectRoot,
+    stdio: 'inherit',
+    shell: false
+  });
+
+  // Surface execution failures explicitly so local-source dogfooding does not
+  // collapse permission, spawn, and signal problems into the same exit code.
+  if (result.error) {
+    console.error('[local-source guard] Failed to launch the local ztd CLI entry.');
+    console.error(`- Message: ${result.error.message}`);
+    if (result.error.stack) {
+      console.error(result.error.stack);
+    }
+    process.exit(1);
+  }
+
+  if (result.signal) {
+    console.error('[local-source guard] The local ztd CLI entry was terminated by signal.');
+    console.error(`- Signal: ${result.signal}`);
+    process.exit(1);
+  }
+
+  process.exit(result.status ?? 1);
+}
+
+const workspaceRoot = findAncestorPnpmWorkspaceRoot(projectRoot);
+const installCommand = workspaceRoot ? 'pnpm install --ignore-workspace' : 'pnpm install';
+const rerunCommand = command === 'test' ? 'pnpm test' : 'pnpm typecheck';
+const fallbackCommand = command === 'test' ? 'npx vitest run' : 'npx tsc --noEmit';
+const binaryName = process.platform === 'win32'
+  ? command === 'test'
+    ? 'vitest.cmd'
+    : 'tsc.cmd'
+  : command === 'test'
+  ? 'vitest'
+  : 'tsc';
+const binaryArgs = command === 'test' ? ['run'] : ['--noEmit'];
+const binaryPath = path.join(projectRoot, 'node_modules', '.bin', binaryName);
+const packageChecks = command === 'test'
+  ? ['vitest/package.json', 'zod/package.json', '@rawsql-ts/sql-contract/package.json']
+  : ['typescript/package.json', 'zod/package.json', '@rawsql-ts/sql-contract/package.json'];
+
+const resolutionIssues = inspectResolution(packageChecks);
+if (!existsSync(binaryPath) || resolutionIssues.length > 0) {
+  printGuidance({
+    command,
+    installCommand,
+    rerunCommand,
+    fallbackCommand,
+    workspaceRoot,
+    binaryPath,
+    resolutionIssues
+  });
+  process.exit(1);
+}
+
+const result = spawnSync(binaryPath, binaryArgs, {
+  cwd: projectRoot,
+  stdio: 'inherit',
+  shell: process.platform === 'win32'
+});
+process.exit(result.status ?? 1);
+
+function inspectResolution(specifiers) {
+  const projectRequire = createRequire(path.join(projectRoot, 'package.json'));
+  const issues = [];
+
+  for (const specifier of specifiers) {
+    try {
+      const resolvedPath = specifier.endsWith('/package.json')
+        ? resolveInstalledPackageManifest(specifier)
+        : projectRequire.resolve(specifier);
+      if (!isInsideProject(resolvedPath)) {
+        issues.push(`${specifier} resolved outside this scaffold: ${normalizePath(resolvedPath)}`);
+      }
+    } catch {
+      issues.push(`${specifier} is not installed in this scaffold`);
+    }
+  }
+
+  return issues;
+}
+
+function resolveInstalledPackageManifest(specifier) {
+  const manifestRelativePath = path.join('node_modules', ...specifier.split('/'));
+  const manifestPath = path.join(projectRoot, manifestRelativePath);
+  if (!existsSync(manifestPath)) {
+    throw new Error(`${specifier} manifest is missing`);
+  }
+  return manifestPath;
+}
+
+function isInsideProject(filePath) {
+  const relativePath = path.relative(projectRoot, filePath);
+  return relativePath.length === 0 || (!relativePath.startsWith('..') && !path.isAbsolute(relativePath));
+}
+
+function normalizePath(filePath) {
+  return filePath.replace(/\\/g, '/');
+}
+
+function findAncestorPnpmWorkspaceRoot(rootDir) {
+  let cursor = path.resolve(rootDir);
+  while (true) {
+    const parentDir = path.dirname(cursor);
+    if (parentDir === cursor) {
+      return null;
+    }
+    cursor = parentDir;
+    if (existsSync(path.join(cursor, 'pnpm-workspace.yaml'))) {
+      return cursor;
+    }
+  }
+}
+
+function printGuidance({
+  command,
+  installCommand,
+  rerunCommand,
+  fallbackCommand,
+  workspaceRoot,
+  binaryPath,
+  resolutionIssues
+}) {
+  const commandLabel = command === 'test' ? 'pnpm test' : 'pnpm typecheck';
+  const lines = [
+    `[local-source guard] ${commandLabel} cannot run against this scaffold yet.`,
+    '',
+    'What happened:',
+    `- The local binary was not found at ${normalizePath(binaryPath)} or required packages resolved outside this project.`,
+  ];
+
+  if (workspaceRoot) {
+    lines.push(`- This project sits under pnpm workspace ${normalizePath(workspaceRoot)}, so pnpm may still be using the parent workspace context.`);
+  }
+
+  if (resolutionIssues.length > 0) {
+    lines.push('- Resolution details:');
+    for (const issue of resolutionIssues) {
+      lines.push(`  - ${issue}`);
+    }
+  }
+
+  lines.push(
+    '',
+    'Next steps:',
+    `1. Run ${installCommand}`,
+    `2. Re-run ${rerunCommand}`,
+    `3. If pnpm still looks absorbed by the parent workspace, try ${fallbackCommand}`
+  );
+  console.error(lines.join('\n'));
+}

package/templates/src/AGENTS.md

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

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

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

@@ -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}.`);
+}