@rawsql-ts/ztd-cli 0.16.0 → 0.19.0

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

@@ -0,0 +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;
+}

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

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

@@ -0,0 +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;
+}

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

@@ -0,0 +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);
+}

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 `pg` (or other drivers) to normalize results into `T[]`
- * - Tests: compatible with the `testkit-postgres` pipeline exposed by `@rawsql-ts/adapter-node-pg` clients returned by `createTestkitClient()`
- *
- * Connection strategy note:
- * - Prefer a shared client per worker process for performance.
- * - Do not share a live client across parallel workers.
- */
-export type SqlClient = {
-  query<T extends Record<string, unknown> = Record<string, unknown>>(
-    text: string,
-    values?: readonly 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.

package/templates/src/infrastructure/AGENTS.md

@@ -0,0 +1,14 @@
+# Package Scope
+- Applies to `packages/ztd-cli/templates/src/infrastructure`.
+- Defines infrastructure adapters for WebAPI-oriented scaffolds.
+
+# Policy
+## REQUIRED
+- Infrastructure code MUST adapt external systems to application or domain-facing contracts.
+- Persistence-specific ZTD workflow rules MUST stay in `src/infrastructure/persistence` and related assets.
+
+## PROHIBITED
+- Treating infrastructure rules as domain or application rules.
+
+# Mandatory Workflow
+- Infrastructure changes MUST run targeted tests for adapter behavior.

package/templates/src/infrastructure/README.md

@@ -0,0 +1,6 @@
+# Infrastructure
+
+Infrastructure adapters live here.
+
+- Database, telemetry, and persistence integration belong here.
+- Keep domain and application contracts stable while swapping implementations.

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/src/infrastructure/db/sql-client.ts

@@ -0,0 +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 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.
+ *
+ * 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/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

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

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

package/templates/src/local/sql-contract.ts

@@ -0,0 +1 @@
+export * from '@rawsql-ts/sql-contract';

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`.