@rawsql-ts/ztd-cli 0.16.0 → 0.17.0

package/templates/tsconfig.json

@@ -1,6 +1,13 @@
 {
-  "extends": "../../../tsconfig.json",
   "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
     "outDir": "dist",
     "tsBuildInfoFile": "dist/.tsbuildinfo"
   },

package/templates/ztd/AGENTS.md

@@ -1,74 +1,18 @@
-# AGENTS: Zero Table Dependency Definitions
+# ztd AGENTS
 
-This file defines **protected, human-led domains** under the `ztd/` directory.
-AI must treat these directories as authoritative sources of truth and must not modify them without explicit instruction.
-These rules govern the `ztd/` contents after project initialization and apply regardless of mapper, writer, or runtime architecture decisions.
+This directory contains ZTD inputs and related documentation.
 
----
+## Core rule
 
-## Generated files (important)
+- "ztd/ddl/" is the only human-owned source of truth inside "ztd/".
+- Do not create new subdirectories under "ztd/" unless explicitly instructed.
 
-- `tests/generated/` is auto-generated and must never be committed.
-- After cloning the repository (or in a clean environment), run `npx ztd ztd-config`.
-- If TypeScript reports missing modules or type errors because `tests/generated/` is missing, run `npx ztd ztd-config`.
-- Generated artifacts exist solely to support validation and testing and MUST NEVER influence definitions under `ztd/`.
+## Boundaries
 
----
+- Runtime code must not depend on "ztd/".
+- Tests may reference DDL and generated outputs via ZTD tooling.
 
-## DDL Specifications (`ztd/ddl/`)
+## Editing policy
 
-You are an AI assistant responsible for **reading and respecting** the contents of this directory.
-
-### Purpose
-
-This directory contains all canonical definitions of database structure, including:
-
-- CREATE TABLE
-- ALTER TABLE
-- Constraints
-- Indexes
-
-It is the **single source of truth** for the physical database schema as interpreted by ztd-cli.
-
-### Behavior Rules (strict)
-
-- **Never modify files in this directory unless explicitly instructed by a human.**
-- Do not apply “helpful” refactors, cleanups, or formatting changes on your own.
-- You may propose edits or review changes when asked, but you must not apply them without approval.
-- All DDL statements must be:
-  - Valid PostgreSQL syntax
-  - Explicitly semicolon-terminated
-- Do not reorder statements; dependency and execution order matters.
-- Preserve all human-authored:
-  - Naming
-  - Formatting
-  - Comments
-  - Structural intent
-- When asked to extend existing definitions:
-  - Do not remove or rewrite existing columns or comments unless explicitly told.
-  - Maintain column order and constraint style.
-  - Do not introduce schema changes that conflict with existing constraints or indexes.
-- The `public.user_account` and `public.user_profile` tables exist to support the mapper/writer sample; any modification to those tables is a maintenance obligation that requires concurrent updates to `src/repositories/user-accounts.ts` and `tests/writer-constraints.test.ts` so the workflow keeps functioning.
-- DDL defines physical truth only and MUST NEVER be reshaped to accommodate mapper, writer, or test tooling.
-- Runtime convenience is never a valid reason to alter DDL.
-
-If there is uncertainty, stop and request clarification instead of guessing.
-
----
-
-- Only `ztd/ddl` is part of the canonical `ztd` contract; do not create or assume additional subdirectories without explicit human direction.
-
----
-
-## Absolute Restrictions (important)
-
-- AI must not modify anything under `ztd/` by default.
-- DDL is the only **human-led artifact** in this directory.
-- AI may assist by:
-  - Reading
-  - Explaining
-  - Proposing diffs
-- AI may apply changes **only** with explicit instruction.
-- No tooling limitation, test strategy, or runtime design justifies modifying `ztd/` artifacts.
-
-Violation of these rules leads to silent corruption of domain meaning and is unacceptable.
+- Avoid modifying "ztd/README.md" unless explicitly asked.
+- Prefer adding rules to "ztd/ddl/AGENTS.md" for DDL-related guidance.

package/templates/ztd/README.md

@@ -1,15 +1,6 @@
-# ZTD Definitions
+# ztd/
 
-This directory hosts the schema definitions under `ztd/ddl/`. Every DDL file in that folder is the single source of truth for database objects; parser tools and tests read these files to learn table structures, columns, indexes, and constraints.
+This directory stores ZTD schema artifacts.
 
-## DDL Guidelines
-
-- Place every schema definition under `ztd/ddl/` with valid PostgreSQL and semicolon-terminated statements.
-- Keep the files deterministic: avoid generated output, enforce column ordering, and document any non-obvious constraints with comments.
-- When you rename or drop a column, update the corresponding DDL file rather than trying to patch test artifacts manually.
-- Treat `ztd/ddl/` as a human-maintained catalog; AI may assist but must not invent or diverge from the files stored there.
-
-## Workflow expectations
-
-- Regenerate `tests/generated/ztd-row-map.generated.ts` via `npx ztd ztd-config` whenever the DDL changes.
-- Do not assume any other subdirectories under `/ztd` exist unless a human has explicitly created them for a specific purpose.
+- `ztd/ddl/<schema>.sql` is the source of truth for schema.
+- Run `npx ztd ztd-config` to regenerate `tests/generated` outputs.

package/templates/ztd/ddl/AGENTS.md

@@ -0,0 +1,34 @@
+# ztd/ddl AGENTS
+
+This folder contains physical schema definitions (DDL). Human-led.
+
+## Ownership
+
+- Humans own DDL semantics.
+- AI may assist with mechanical edits, but must not invent domain rules.
+
+## Conventions (Postgres-oriented)
+
+- Table names: singular (example: "user", "order", "invoice")
+- Primary key: "serial8" (bigserial) by default
+- Timestamps: default "current_timestamp" where applicable
+
+## Comments (required)
+
+Add comments for tables and important columns.
+
+Postgres syntax:
+- "comment on table <schema>.<table> is '...';"
+- "comment on column <schema>.<table>.<column> is '...';"
+
+## Constraints
+
+- Prefer explicit NOT NULL where appropriate.
+- Prefer explicit unique constraints for business keys.
+- Foreign keys are allowed, but keep them intentional and explain rationale in comments.
+
+## File strategy
+
+- Keep schema DDL in a clear and reviewable form.
+- If using one file per schema (example: "public.sql"), keep it consistent.
+- Avoid random splitting unless there is a strong reason.

package/templates/ztd/ddl/demo.sql

@@ -0,0 +1,74 @@
+create table "user" (
+  user_id     serial8 primary key,
+  user_name   text not null,
+  email       text not null,
+  created_at  timestamptz not null default current_timestamp
+);
+
+comment on table "user" is
+  'User master. Referenced by task_assignment.';
+
+comment on column "user".user_id is
+  'Primary key of user.';
+comment on column "user".user_name is
+  'Display name of the user.';
+comment on column "user".email is
+  'Email address of the user.';
+comment on column "user".created_at is
+  'Timestamp when the user was created.';
+
+create table task (
+  task_id     serial8 primary key,
+  title       text not null,
+  status      text not null,
+  priority    integer not null,
+  due_date    date,
+  created_at  timestamptz not null default current_timestamp
+);
+
+comment on table task is
+  'Task entity. Current assignee is derived from task_assignment history.';
+
+comment on column task.task_id is
+  'Primary key of task.';
+comment on column task.title is
+  'Short description of the task.';
+comment on column task.status is
+  'Task status. Example: open, in_progress, done.';
+comment on column task.priority is
+  'Priority of the task. Higher value means higher priority.';
+comment on column task.due_date is
+  'Optional due date of the task.';
+comment on column task.created_at is
+  'Timestamp when the task was created.';
+
+create table task_assignment (
+  task_assignment_id serial8 primary key,
+  task_id            bigint not null,
+  user_id            bigint not null,
+  assigned_at        timestamptz not null default current_timestamp
+);
+
+comment on table task_assignment is
+  'Assignment history of tasks. Latest assigned_at defines current assignee.';
+
+comment on column task_assignment.task_assignment_id is
+  'Primary key of task_assignment.';
+comment on column task_assignment.task_id is
+  'Referenced task identifier.';
+comment on column task_assignment.user_id is
+  'Referenced user identifier.';
+comment on column task_assignment.assigned_at is
+  'Timestamp when the task was assigned to the user.';
+
+create index idx_task_assignment_task
+  on task_assignment(task_id);
+
+create index idx_task_assignment_task_time
+  on task_assignment(task_id, assigned_at desc);
+
+comment on index idx_task_assignment_task is
+  'Index for joining task_assignment by task_id.';
+
+comment on index idx_task_assignment_task_time is
+  'Index for resolving latest assignment per task.';

package/templates/src/repositories/user-accounts.ts

@@ -1,179 +0,0 @@
-import type { SqlClient } from '../db/sql-client';
-import { createMapper, entity, toRowsExecutor } from '@rawsql-ts/mapper-core';
-import { insert, Key, remove, update } from '@rawsql-ts/writer-core';
-
-const userAccountTable = 'public.user_account';
-
-type UserProfileRow = {
-  profileId: number;
-  userAccountId: number;
-  bio: string | null;
-  website: string | null;
-  verified: boolean;
-};
-
-/**
- * DTO that represents a user account with its optional profile information.
- * @property {number} userAccountId The primary key for the user account.
- * @property {string} username The canonical username.
- * @property {string} email The account email address.
- * @property {string} displayName The account display name.
- * @property {Date} createdAt When the account was created.
- * @property {Date} updatedAt When the account was last updated.
- * @property {UserProfileRow} [profile] Optional profile payload joined from user_profile.
- */
-export type UserAccountWithProfile = {
-  userAccountId: number;
-  username: string;
-  email: string;
-  displayName: string;
-  createdAt: Date;
-  updatedAt: Date;
-  profile?: UserProfileRow;
-};
-
-// Map the joined profile columns so we can hydrate nested objects later.
-const profileMapping = entity<UserProfileRow>({
-  name: 'userProfile',
-  key: 'profileId',
-  columnMap: {
-    profileId: 'profile_id',
-    userAccountId: 'profile_user_account_id',
-    bio: 'bio',
-    website: 'website',
-    verified: 'verified',
-  },
-});
-
-const userAccountMapping = entity<UserAccountWithProfile>({
-  name: 'userAccount',
-  key: 'userAccountId',
-  columnMap: {
-    userAccountId: 'user_account_id',
-    username: 'username',
-    email: 'email',
-    displayName: 'display_name',
-    createdAt: 'created_at',
-    updatedAt: 'updated_at',
-  },
-}).belongsTo('profile', profileMapping, 'userAccountId', { optional: true });
-
-const userProfilesSql = `
-SELECT
-  u.user_account_id,
-  u.username,
-  u.email,
-  u.display_name,
-  u.created_at,
-  u.updated_at,
-  p.profile_id,
-  p.user_account_id AS profile_user_account_id,
-  p.bio,
-  p.website,
-  p.verified
-FROM public.user_account u
-LEFT JOIN public.user_profile p ON p.user_account_id = u.user_account_id
-ORDER BY u.user_account_id, p.profile_id;
-`;
-
-// Build a mapper that can translate snake_case columns into camelCase DTOs.
-const createMapperForClient = (client: SqlClient) =>
-  createMapper(
-    toRowsExecutor((sql, params: unknown[] = []) =>
-      client.query<Record<string, unknown>>(sql, params),
-    ),
-    {
-      // The explicit column maps enumerate the nested entity columns while keyTransform handles generic snake_to_camel conversions.
-      keyTransform: 'snake_to_camel',
-      coerceDates: true,
-    },
-  );
-
-/**
- * Queries all user accounts together with their associated profiles.
- * @param {SqlClient} client Client proxy that executes the mapper SQL.
- * @returns {Promise<UserAccountWithProfile[]>} The joined account-with-profile rows.
- */
-export async function listUserProfiles(
-  client: SqlClient,
-): Promise<UserAccountWithProfile[]> {
-  const mapper = createMapperForClient(client);
-  return mapper.query(userProfilesSql, [], userAccountMapping);
-}
-
-/**
- * Parameters required to insert a new user account.
- * @property {string} username The requested username.
- * @property {string} email The requested email address.
- * @property {string} displayName The requested display name.
- */
-export type NewUserAccount = {
-  username: string;
-  email: string;
-  displayName: string;
-};
-
-/**
- * Payload describing the display name change for an existing account.
- * @property {string} displayName The new display name to persist.
- */
-export type DisplayNameUpdatePayload = {
-  displayName: string;
-};
-
-/**
- * Builds an insert statement for the user_account writer.
- * @param {NewUserAccount} input The normalized fields for the new account.
- * @returns {ReturnType<typeof insert>} A well-formed insert statement for the user_account writer.
- */
-export function buildInsertUserAccount(
-  input: NewUserAccount,
-): ReturnType<typeof insert> {
-  return insert(userAccountTable, {
-    username: input.username,
-    email: input.email,
-    display_name: input.displayName,
-  });
-}
-
-/**
- * Builds an update statement that refreshes the display name and timestamp.
- * @param {Key} key The unique key identifying the row to update.
- * @param {DisplayNameUpdatePayload} payload The new display name payload.
- * @returns {ReturnType<typeof update>} A writer update statement that refreshes the display name and updated_at timestamp.
- */
-export function buildUpdateDisplayName(
-  key: Key,
-  payload: DisplayNameUpdatePayload,
-): ReturnType<typeof update> {
-  return update(
-    userAccountTable,
-    {
-      // Persist the new display name and bump the timestamp along with it.
-      display_name: payload.displayName,
-      updated_at: new Date(),
-    },
-    key,
-  );
-}
-
-/**
- * Builds a delete statement for the specified user account key.
- * @param {Key} key Identifies the row to remove.
- * @returns {ReturnType<typeof remove>} A writer delete statement for the matching user account.
- */
-export function buildRemoveUserAccount(key: Key): ReturnType<typeof remove> {
-  return remove(userAccountTable, key);
-}
-
-/**
- * Column sets that writer tests use to ensure only approved columns are touched.
- * @property {readonly string[]} insertColumns Columns allowed for new account inserts.
- * @property {readonly string[]} updateColumns Columns permitted during updates.
- * @property {readonly string[]} immutableColumns Columns that must remain unchanged.
- */
-export const userAccountWriterColumnSets = {
-  insertColumns: ['username', 'email', 'display_name'] as const,
-  updateColumns: ['display_name', 'updated_at'] as const,
-  immutableColumns: ['user_account_id', 'created_at'] as const,
-};

package/templates/tests/user-profiles.test.ts

@@ -1,161 +0,0 @@
-import { describe, expect, test, afterAll } from 'vitest';
-import type { TableFixture, TestkitProvider } from '@rawsql-ts/testkit-core';
-import { createTestkitProvider } from '@rawsql-ts/testkit-core';
-import { createPgTestkitClient } from '@rawsql-ts/pg-testkit';
-import { Pool } from 'pg';
-import path from 'node:path';
-import {
-  tableFixture,
-  tableSchemas,
-  TestRowMap,
-} from './generated/ztd-row-map.generated';
-import { listUserProfiles } from '../src/repositories/user-accounts';
-
-const ddlDirectories = [path.resolve(__dirname, '../ztd/ddl')];
-const skipReason = 'DATABASE_URL is not configured';
-const configuredDatabaseUrl = process.env.DATABASE_URL?.trim();
-const suiteTitle = configuredDatabaseUrl
-  ? 'user profile mapper'
-  : `user profile mapper (skipped: ${skipReason})`;
-const describeUserProfile = configuredDatabaseUrl
-  ? describe
-  : (describe.skip as typeof describe);
-let pool: Pool | undefined;
-let providerPromise: Promise<TestkitProvider> | undefined;
-
-// Lazily initialize the test provider so missing DATABASE_URL values do not trigger side effects.
-function getProvider(): Promise<TestkitProvider> {
-  if (providerPromise) {
-    return providerPromise;
-  }
-
-  const databaseUrl = process.env.DATABASE_URL?.trim();
-  if (!databaseUrl) {
-    throw new Error(
-      'Cannot initialize the repository testkit provider without DATABASE_URL.',
-    );
-  }
-
-  pool = new Pool({ connectionString: databaseUrl });
-  const activePool = pool;
-  providerPromise = createTestkitProvider({
-    connectionFactory: () => activePool.connect(),
-    resourceFactory: async (connection, fixtures) =>
-      createPgTestkitClient({
-        connectionFactory: () => connection,
-        tableRows: fixtures,
-        ddl: { directories: ddlDirectories },
-      }),
-    releaseResource: async (client) => {
-      await client.close();
-    },
-    disposeConnection: async (connection) => {
-      if (typeof connection.release === 'function') {
-        connection.release();
-        return;
-      }
-      if (typeof connection.end === 'function') {
-        await connection.end();
-      }
-    },
-  });
-
-  return providerPromise;
-}
-
-afterAll(async () => {
-  // Close resources only when initialization actually happened.
-  if (!providerPromise) {
-    return;
-  }
-
-  const provider = await providerPromise;
-  await provider.close();
-  if (pool) {
-    await pool.end();
-  }
-});
-
-function buildUserAccounts(): TestRowMap['public.user_account'][] {
-  return [
-    {
-      user_account_id: 1,
-      username: 'alpha',
-      email: 'alpha@example.com',
-      display_name: 'Alpha Tester',
-      created_at: '2025-12-01T08:00:00Z',
-      updated_at: '2025-12-01T09:00:00Z',
-    },
-    {
-      user_account_id: 2,
-      username: 'bravo',
-      email: 'bravo@example.com',
-      display_name: 'Bravo Builder',
-      created_at: '2025-12-02T10:00:00Z',
-      updated_at: '2025-12-02T11:00:00Z',
-    },
-  ];
-}
-
-function buildUserProfiles(): TestRowMap['public.user_profile'][] {
-  return [
-    {
-      profile_id: 101,
-      user_account_id: 1,
-      bio: 'Lead engineer and mapper advocate.',
-      website: 'https://example.com',
-      verified: true,
-    },
-  ];
-}
-
-function buildFixtures(): TableFixture[] {
-  return [
-    tableFixture(
-      'public.user_account',
-      buildUserAccounts(),
-      tableSchemas['public.user_account'],
-    ),
-    tableFixture(
-      'public.user_profile',
-      buildUserProfiles(),
-      tableSchemas['public.user_profile'],
-    ),
-  ];
-}
-
-describeUserProfile(suiteTitle, () => {
-  test('listUserProfiles hydrates optional profiles', async () => {
-    const fixtures = buildFixtures();
-    const provider = await getProvider();
-    await provider.withRepositoryFixture(fixtures, async (client) => {
-      const result = await listUserProfiles(client);
-      expect(result).toEqual([
-        {
-          userAccountId: 1,
-          username: 'alpha',
-          email: 'alpha@example.com',
-          displayName: 'Alpha Tester',
-          createdAt: new Date('2025-12-01T08:00:00Z'),
-          updatedAt: new Date('2025-12-01T09:00:00Z'),
-          profile: {
-            profileId: 101,
-            userAccountId: 1,
-            bio: 'Lead engineer and mapper advocate.',
-            website: 'https://example.com',
-            verified: true,
-          },
-        },
-        {
-          userAccountId: 2,
-          username: 'bravo',
-          email: 'bravo@example.com',
-          displayName: 'Bravo Builder',
-          createdAt: new Date('2025-12-02T10:00:00Z'),
-          updatedAt: new Date('2025-12-02T11:00:00Z'),
-          profile: undefined,
-        },
-      ]);
-    });
-  });
-});

package/templates/tests/writer-constraints.test.ts

@@ -1,32 +0,0 @@
-import { describe, expect, test } from 'vitest';
-import { tableSchemas } from './generated/ztd-row-map.generated';
-import { userAccountWriterColumnSets } from '../src/repositories/user-accounts';
-
-const userColumns = new Set(
-  Object.keys(tableSchemas['public.user_account'].columns),
-);
-
-describe('user_account writer columns', () => {
-  test('insert columns must exist on the canonical table', () => {
-    const { insertColumns } = userAccountWriterColumnSets;
-    const missing = insertColumns.filter((column) => !userColumns.has(column));
-    expect(missing, `Missing columns: ${missing.join(', ')}`).toEqual([]);
-    expect(insertColumns).toEqual(
-      expect.arrayContaining(['username', 'email', 'display_name']),
-    );
-  });
-
-  test('writer column sets align with the canonical table', () => {
-    const { updateColumns, immutableColumns } = userAccountWriterColumnSets;
-    const missingUpdates = updateColumns.filter((column) => !userColumns.has(column));
-    expect(missingUpdates, `Missing update columns: ${missingUpdates.join(', ')}`).toEqual([]);
-    const missingImmutables = immutableColumns.filter((column) => !userColumns.has(column));
-    expect(missingImmutables, `Missing immutable columns: ${missingImmutables.join(', ')}`).toEqual([]);
-    immutableColumns.forEach((column) => {
-      expect(
-        updateColumns,
-        `Immutable column "${column}" should never appear in updateColumns`,
-      ).not.toContain(column);
-    });
-  });
-});