@rawsql-ts/ztd-cli 0.17.0 → 0.20.0

package/templates/src/infrastructure/db/AGENTS.md

@@ -0,0 +1,14 @@
+# Package Scope
+- Applies to `packages/ztd-cli/templates/src/infrastructure/db`.
+- Defines SQL client seams and driver adapters for WebAPI-oriented scaffolds.
+
+# Policy
+## REQUIRED
+- Driver adapters MUST fulfill the `SqlClient` contract without leaking driver-specific result objects.
+- Connection lifecycle decisions MUST remain explicit.
+
+## PROHIBITED
+- Embedding repository business rules in DB adapter code.
+
+# Mandatory Workflow
+- DB adapter changes MUST run typecheck and adapter-focused tests.

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

@@ -0,0 +1,34 @@
+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:
+ *   // This runtime example uses DATABASE_URL for application code.
+ *   // ztd-cli itself does not read DATABASE_URL implicitly.
+ *   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/{dist/ztd-cli/templates/src → src/infrastructure}/db/sql-client.ts

@@ -7,7 +7,7 @@
 export type SqlQueryRows<T> = Promise<T[]>;
 
 /**
- * Minimal SQL client interface required by the repository layer.
+ * Minimal SQL client interface required by the persistence 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.
@@ -19,6 +19,6 @@ export type SqlQueryRows<T> = Promise<T[]>;
 export type SqlClient = {
   query<T extends Record<string, unknown> = Record<string, unknown>>(
     text: string,
-    values?: readonly unknown[]
+    values?: readonly unknown[] | Record<string, unknown>
   ): SqlQueryRows<T>;
-};
+};

package/templates/src/infrastructure/persistence/AGENTS.md

@@ -0,0 +1,18 @@
+# Package Scope
+- Applies to `packages/ztd-cli/templates/src/infrastructure/persistence`.
+- Defines persistence-layer rules for WebAPI-oriented scaffolds.
+
+# Policy
+## REQUIRED
+- ZTD-specific workflow rules apply here and in the related `src/sql`, `src/catalog`, and `ztd` assets.
+- Persistence adapters MUST keep handwritten SQL, QuerySpecs, and DDL aligned.
+- Repository code MUST rely on explicit contracts and generated/runtime helpers instead of hidden driver behavior.
+- `ZTD_TEST_DATABASE_URL` is the only implicit database owned by `ztd-cli`.
+- Non-ZTD database targets MUST be passed explicitly via `--url` or a complete `--db-*` flag set for inspection work.
+- Migration SQL artifacts MAY be generated here, but applying them remains outside `ztd-cli` ownership.
+
+## PROHIBITED
+- Leaking persistence rules into domain, application, or presentation layers.
+
+# Mandatory Workflow
+- Persistence changes MUST run `ztd ztd-config`, relevant tests, and the persistence-focused verification flow.

package/templates/src/infrastructure/persistence/README.md

@@ -0,0 +1,8 @@
+# Persistence Infrastructure
+
+This is the primary ZTD-aware layer.
+
+- Store SQL assets in `src/sql`.
+- Place QuerySpecs in `src/catalog/specs`.
+- Maintain runtime mapping helpers in `src/catalog/runtime`.
+- Keep DDL in `ztd/ddl`.

package/templates/src/infrastructure/persistence/repositories/AGENTS.md

@@ -0,0 +1,17 @@
+# Package Scope
+- Applies to `packages/ztd-cli/templates/src/infrastructure/persistence/repositories`.
+- Defines repository responsibilities for WebAPI-oriented persistence infrastructure.
+
+# Policy
+## REQUIRED
+- Repositories MUST load SQL assets from `src/sql` through shared loader infrastructure.
+- Repository CUD behavior MUST follow contract rules for `RETURNING`, rowCount handling, and explicit unsupported-driver failures.
+- Repositories MUST reference SQL by stable logical keys.
+- Constructors for repositories SHOULD accept an optional telemetry dependency from `src/infrastructure/telemetry/repositoryTelemetry.ts`.
+- Tests MUST cover every public repository method.
+
+## PROHIBITED
+- Inline SQL strings or ad-hoc SQL file path resolution.
+
+# Mandatory Workflow
+- Repository changes MUST run tests covering mapping, rowCount behavior, and error surfaces.

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

@@ -0,0 +1,20 @@
+# Package Scope
+- Applies to `packages/ztd-cli/templates/src/infrastructure/persistence/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.
+
+## 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.

package/templates/src/infrastructure/persistence/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/infrastructure/persistence/repositories/views/AGENTS.md

@@ -0,0 +1,16 @@
+# Package Scope
+- Applies to `packages/ztd-cli/templates/src/infrastructure/persistence/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.
+
+## 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.

package/templates/src/infrastructure/persistence/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/infrastructure/telemetry/AGENTS.md

@@ -0,0 +1,14 @@
+# Package Scope
+- Applies to `packages/ztd-cli/templates/src/infrastructure/telemetry`.
+- Defines repository telemetry seams and adapters.
+
+# Policy
+## REQUIRED
+- Telemetry hooks MUST remain replaceable by application-owned wiring.
+- Default telemetry behavior MUST stay conservative about query text emission.
+
+## PROHIBITED
+- Making telemetry mandatory for non-persistence layers.
+
+# Mandatory Workflow
+- Telemetry changes MUST run the focused scaffold verification tests.

package/templates/src/infrastructure/telemetry/consoleRepositoryTelemetry.ts

@@ -0,0 +1,66 @@
+import type {
+  RepositoryTelemetry,
+  RepositoryTelemetryConsoleOptions,
+  RepositoryTelemetryEvent,
+} from './types';
+
+/**
+ * Create a conservative console-backed telemetry hook for repositories.
+ *
+ * The default policy keeps SQL text disabled so applications opt in before
+ * query text is emitted to logs or forwarded to another sink.
+ */
+export function createConsoleRepositoryTelemetry(
+  options: RepositoryTelemetryConsoleOptions = {},
+): RepositoryTelemetry {
+  const logger = options.logger ?? console;
+
+  return {
+    emit(event: RepositoryTelemetryEvent): void {
+      const payload = serializeEvent(event, options.includeSqlText === true);
+      if (event.kind === 'query.execute.error') {
+        logger.error('[repository-telemetry]', payload);
+        return;
+      }
+
+      logger.info('[repository-telemetry]', payload);
+    },
+  };
+}
+
+function serializeEvent(
+  event: RepositoryTelemetryEvent,
+  includeSqlText: boolean,
+): Record<string, unknown> {
+  const payload: Record<string, unknown> = {
+    kind: event.kind,
+    timestamp: event.timestamp,
+    repositoryName: event.repositoryName,
+    methodName: event.methodName,
+  };
+
+  if (event.queryName) {
+    payload.queryName = event.queryName;
+  }
+  if (event.fallback !== undefined) {
+    payload.fallback = event.fallback;
+  }
+
+  // Keep SQL text out of default logs so applications make that policy choice.
+  if (includeSqlText && event.sqlText) {
+    payload.sqlText = event.sqlText;
+  }
+
+  if (event.kind !== 'query.execute.start') {
+    payload.durationMs = event.durationMs;
+  }
+  if (event.kind === 'query.execute.success' && event.rowCount !== undefined) {
+    payload.rowCount = event.rowCount;
+  }
+  if (event.kind === 'query.execute.error') {
+    payload.errorName = event.errorName;
+    payload.errorMessage = event.errorMessage;
+  }
+
+  return payload;
+}

package/templates/src/infrastructure/telemetry/repositoryTelemetry.ts

@@ -0,0 +1,26 @@
+import { createConsoleRepositoryTelemetry } from './consoleRepositoryTelemetry';
+import type { RepositoryTelemetry } from './types';
+
+export type {
+  RepositoryTelemetry,
+  RepositoryTelemetryConsoleOptions,
+  RepositoryTelemetryContext,
+  RepositoryTelemetryEvent,
+  RepositoryTelemetryEventKind,
+} from './types';
+
+export { createConsoleRepositoryTelemetry } from './consoleRepositoryTelemetry';
+
+export const defaultRepositoryTelemetry = createConsoleRepositoryTelemetry();
+
+/**
+ * Resolve the repository telemetry hook that application code wants to use.
+ *
+ * Repository constructors can accept an optional telemetry dependency and call
+ * this helper so the default console hook works without extra setup.
+ */
+export function resolveRepositoryTelemetry(
+  telemetry?: RepositoryTelemetry,
+): RepositoryTelemetry {
+  return telemetry ?? defaultRepositoryTelemetry;
+}

package/templates/src/infrastructure/telemetry/types.ts

@@ -0,0 +1,48 @@
+export type RepositoryTelemetryEventKind =
+  | 'query.execute.start'
+  | 'query.execute.success'
+  | 'query.execute.error';
+
+export interface RepositoryTelemetryContext {
+  repositoryName: string;
+  methodName: string;
+  queryName?: string;
+  sqlText?: string;
+  fallback?: boolean;
+}
+
+interface RepositoryTelemetryEventBase extends RepositoryTelemetryContext {
+  kind: RepositoryTelemetryEventKind;
+  timestamp: string;
+}
+
+export interface RepositoryQueryExecuteStartEvent extends RepositoryTelemetryEventBase {
+  kind: 'query.execute.start';
+}
+
+export interface RepositoryQueryExecuteSuccessEvent extends RepositoryTelemetryEventBase {
+  kind: 'query.execute.success';
+  durationMs: number;
+  rowCount?: number;
+}
+
+export interface RepositoryQueryExecuteErrorEvent extends RepositoryTelemetryEventBase {
+  kind: 'query.execute.error';
+  durationMs: number;
+  errorName: string;
+  errorMessage: string;
+}
+
+export type RepositoryTelemetryEvent =
+  | RepositoryQueryExecuteStartEvent
+  | RepositoryQueryExecuteSuccessEvent
+  | RepositoryQueryExecuteErrorEvent;
+
+export interface RepositoryTelemetry {
+  emit(event: RepositoryTelemetryEvent): void | Promise<void>;
+}
+
+export interface RepositoryTelemetryConsoleOptions {
+  includeSqlText?: boolean;
+  logger?: Pick<Console, 'info' | 'error'>;
+}

package/templates/src/jobs/AGENTS.md

@@ -1,26 +1,25 @@
-# src/jobs AGENTS
-
-This folder contains script-like operations (procedural SQL execution).
-
-## Scope
-
-- Maintenance jobs
-- Data backfills
-- Batch operations
-- Temporary-table driven workflows
-
-## Safety rules
-
-- Be explicit about transaction boundaries.
-- Prefer idempotent design (safe to rerun).
-- Emit clear logs/events at start and end of the job.
-
-## SQL usage
-
-- It is acceptable to run multiple statements in a job (including temp tables).
-- Avoid coupling job logic to tests-only helpers.
-
-## Testing
-
-- Prefer integration-style tests that verify observable outcomes.
-- If the job is heavy, test smaller units or use fixtures to limit scope.
+# Package Scope
+- Applies to `packages/ztd-cli/templates/src/jobs`.
+- Defines contract rules for procedural and batch SQL job code.
+
+# Policy
+## REQUIRED
+- Jobs MUST declare explicit transaction boundaries.
+- Jobs MUST emit start/end operational events or logs.
+- Job tests MUST validate observable outcomes.
+
+## ALLOWED
+- Jobs MAY execute multiple SQL statements, including temporary-table workflows.
+- Heavy jobs MAY split verification across integration and focused fixture tests.
+
+## PROHIBITED
+- Coupling job logic to test-only helpers.
+
+# Mandatory Workflow
+- Job changes MUST run integration-style tests for affected job paths.
+
+# Hygiene
+- Job logic MUST remain idempotent for rerun safety.
+
+# References
+- Parent runtime policy: [../AGENTS.md](../AGENTS.md)

package/templates/src/jobs/README.md

@@ -1,3 +1,3 @@
-# Jobs
-
+# Jobs
+
 Job runners that orchestrate repository or SQL workflows.

package/templates/src/presentation/AGENTS.md

@@ -0,0 +1,15 @@
+# Package Scope
+- Applies to `packages/ztd-cli/templates/src/presentation`.
+- Defines transport adapters for WebAPI-oriented scaffolds.
+
+# Policy
+## REQUIRED
+- Presentation code MUST translate external input/output without embedding domain or persistence rules.
+- Request/response contracts MUST remain explicit.
+
+## PROHIBITED
+- Direct SQL, DDL, or QuerySpec ownership.
+- Hidden business rules in controllers or handlers.
+
+# Mandatory Workflow
+- Presentation changes MUST run tests for request parsing and response shaping.

package/templates/src/presentation/http/AGENTS.md

@@ -0,0 +1,15 @@
+# Package Scope
+- Applies to `packages/ztd-cli/templates/src/presentation/http`.
+- Defines HTTP-specific transport behavior for WebAPI-oriented scaffolds.
+
+# Policy
+## REQUIRED
+- HTTP adapters MUST translate transport concerns into application-layer inputs and outputs.
+- Handler code MUST keep status codes, headers, and serialization explicit.
+
+## PROHIBITED
+- Direct SQL execution.
+- Embedding persistence-specific retries or ZTD workflow rules in handlers.
+
+# Mandatory Workflow
+- HTTP adapter changes MUST run transport-focused tests.

package/templates/src/presentation/http/README.md

@@ -0,0 +1,6 @@
+# HTTP Presentation
+
+HTTP handlers, controllers, and transport mapping live here.
+
+- Keep framework-specific code here.
+- Delegate use-case orchestration to `src/application`.

package/templates/src/repositories/AGENTS.md

@@ -1,118 +1,30 @@
-# src/repositories AGENTS
-
-This directory contains repository implementations.
-
-## Runtime classification
-
-- This is a runtime directory.
-- Code here is executed by the application.
-
-## Responsibilities
-
-Repositories orchestrate execution only.
-
-They are responsible for:
-- loading SQL assets from `src/sql`
-- validating external inputs via catalog runtime
-- binding parameters
-- calling `SqlClient`
-- mapping SQL rows to DTOs via catalog runtime
-- returning application-facing results
-
-Repositories MUST remain thin adapters over SQL.
-
-Repositories MUST NOT:
-- embed business rules
-- infer schema or DTO structure
-- compensate for driver limitations with extra queries
-
-## Contract boundaries (important)
-
-- Human-owned contracts live under "src/catalog/specs".
-- Runtime normalization and validation live under "src/catalog/runtime".
-- Repositories MUST NOT invent, infer, or modify contracts.
-
-If a contract is insufficient, update the spec/runtime first.
-
-## Mandatory runtime usage (required)
-
-Repositories MUST use catalog runtime helpers:
-- `ensure*Params` for all external inputs (`unknown -> typed`)
-- `map*RowToDto` for row-to-DTO mapping and output validation
-
-Repositories MUST NOT:
-- call spec validators directly
-- bypass runtime normalization
-- return DTOs without runtime validation
-- assume driver-specific runtime types (e.g. timestamps always `Date`)
-
-## SQL rules
-
-- SQL assets MUST remain DTO-independent.
-- SQL files MUST use snake_case column names.
-- Repositories MUST NOT push DTO aliasing into SQL.
-- Inline SQL strings are forbidden.
-- Repository SQL loading MUST be centralized in shared runtime/repository infrastructure.
-- Repositories MUST reference SQL assets by stable logical key (example: `user/insert_user.sql`).
-- Repository modules MUST NOT pass caller-relative paths (`./`, `../`) or absolute filesystem paths to SQL loaders.
-- The shared loader MUST resolve logical keys against the `src/sql` root (or catalog SQL registry), never relative to the caller file location.
-- Repository modules MUST NOT implement ad-hoc SQL file loading with `readFileSync`, `__dirname`, `import.meta.url`, or direct path resolution.
-
-## CUD default policy (important)
-
-Default policy for table-oriented CUD is:
-- CREATE SQL MAY use `RETURNING` for identifier columns only.
-- CREATE repository methods MUST return the generated identifier by default.
-- CREATE repository methods MUST NOT perform a follow-up SELECT whose purpose is DTO return shaping.
-- UPDATE/DELETE SQL MUST NOT use `RETURNING`.
-- repositories do NOT perform follow-up SELECTs after UPDATE/DELETE.
-- UPDATE/DELETE methods return `Promise<void>` by default.
-
-If a CREATE method must return a DTO, that requirement MUST be explicitly declared in catalog specs by human instruction.
-
-## CUD row count rules (non-negotiable)
-
-- UPDATE and DELETE MUST rely on driver-reported affected row counts (`rowCount` or equivalent).
-- Repositories MUST NOT use SQL `RETURNING` result presence/count as a substitute for affected row counts.
-- Repositories MUST NOT emulate affected rows using:
-  - pre-check SELECT
-  - post-check SELECT
-  - retry loops
-  - shadow queries / CTE hacks
-
-If `rowCount === 0`, repositories MUST throw an explicit error.
-
-If the driver cannot report affected row counts:
-- CUD verification is unsupported
-- tests MUST fail fast
-- do NOT add workaround logic in repositories
-
-## Read (SELECT) rules
-
-- SELECT methods may return:
-  - `T | null` for single-row queries
-  - `T[]` for multi-row queries
-- Absence of rows is NOT an error unless specified by the contract.
-
-## Error behavior
-
-- Propagate validation errors as failures.
-- Do not silently coerce invalid data.
-- Error messages SHOULD include operation name and identifying parameters.
-
-## Testing expectations
-
-- Every public repository method MUST be covered by tests.
-- Update/Delete tests MUST verify rowCount handling explicitly.
-- Repository changes without tests are incomplete.
-
-## Guiding principle
-
-Repositories execute contracts.
-They do not interpret intent.
-
-If correctness depends on extra queries to "confirm" changes:
-- the contract is wrong
-- or the driver is unsupported
-
-Fix the contract, not the repository.
+# 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)