@rawsql-ts/ztd-cli 0.15.0 → 0.17.0

package/templates/tests/ztd-layout.generated.ts

@@ -3,6 +3,4 @@
 export default {
   ztdRootDir: 'ztd',
   ddlDir: 'ztd/ddl',
-  enumsDir: 'ztd/enums',
-  domainSpecsDir: 'ztd/domain-specs',
 };

package/templates/tsconfig.json

@@ -1,9 +1,15 @@
 {
-  "extends": "../../../tsconfig.json",
   "compilerOptions": {
-    "rootDir": ".",
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
     "outDir": "dist",
     "tsBuildInfoFile": "dist/.tsbuildinfo"
   },
-  "include": ["tests/**/*.ts"]
+  "include": ["src/**/*.ts", "tests/**/*.ts"]
 }

package/templates/ztd/AGENTS.md

@@ -1,149 +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.
+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`.
+## 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:
-  - `ztd/domain-specs`
-  - `ztd/enums`
-
-If there is uncertainty, stop and request clarification instead of guessing.
-
----
-
-## Domain Specifications (`ztd/domain-specs/`)
-
-You are an AI agent that **reads** domain specifications to understand business semantics.
-
-### Purpose
-
-Each file in this directory defines **one domain behavior**.
-These files explain *what the data means*, not how the application is implemented.
-
-### Instructions
-
-- Treat each Markdown file as defining exactly **one behavior**.
-- Use the embedded SQL block as the **reference SELECT**.
-- Only the first top-level SQL block is executable logic.
-- Parameters may be written as `:named` placeholders.
-  - When generating executable SQL, bind them as positional placeholders (`$1`, `$2`, `?`).
-- **Never modify files in this directory unless explicitly instructed.**
-
-### Rules (strict)
-
-- Never ignore the human-written explanation above the SQL block.
-- Keep exactly one executable SQL block per file.
-- Do not reorder, optimize, or “simplify” SQL unless explicitly instructed.
-- Preserve the exact semantics described by humans.
-- This directory defines **what is correct behavior**.
-  - Your role is to reproduce that behavior elsewhere (`src/`, `tests/`), not reinterpret it.
-
-If meaning is ambiguous, defer to human judgment and ask.
-
----
-
-## Domain Enums (`ztd/enums/`)
-
-You are an AI assistant responsible for **reading and using** domain enum definitions.
-
-### Purpose
-
-This directory defines canonical value sets such as:
-
-- Status codes
-- Category types
-- Plan tiers
-
-These enums are the **only allowed vocabulary** for such concepts.
-
-### Behavior Guidelines (strict)
-
-- Never invent enum values.
-- Never hardcode magic numbers or strings.
-- Never modify or add enum definitions unless explicitly instructed by a human.
-
-### SQL Rules
-
-- Each file contains exactly one executable SQL block.
-- Enum definitions follow this canonical pattern:
-
-```sql
-select v.*
-from (
-  values
-    (1, 'some_code', 'some_label')
-) v(key, value, display_name);
-```
-
-- `key` and `value` are authoritative.
-- Additional columns (e.g. `display_name`, `ranking`) may be used for:
-  - UI display
-  - Sorting
-  - Documentation
-
-### Use in Code Generation
-
-- Always reference enums when generating:
-  - SQL WHERE conditions
-  - Constants
-  - Conditional logic
-- When translating logic from `ztd/domain-specs`, resolve enum references through this directory.
-- Maintain full consistency with naming and intent.
-
-If a required enum does not exist, stop and ask for human clarification.
-
----
-
-## Absolute Restrictions (important)
-
-- AI must not modify anything under `ztd/` by default.
-- DDL, domain-specs, and enums are **human-led artifacts**.
-- AI may assist by:
-  - Reading
-  - Explaining
-  - Proposing diffs
-- AI may apply changes **only** with explicit instruction.
-
-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,84 +1,6 @@
-# ZTD Definitions
+# ztd/
 
-This directory hosts the schema, domain-spec, and enum definitions that feed native ZTD workflows.
+This directory stores ZTD schema artifacts.
 
-## DDL Definitions
-
-The ztd/ddl/ directory stores **Data Definition Language (DDL)** files that describe the database schema. These files include CREATE TABLE, ALTER TABLE, index declarations, and constraint definitions. ZTD treats the SQL files here as the single source of truth for schemas, so both humans and AI must reference this directory when evolving the structure.
-
-### Allowed Content and Structure
-
-- **Schema Definition Files:** Core table structures live in ztd/ddl/ using CREATE TABLE statements, but you may also add related DDL such as ALTER TABLE commands or explicit index declarations that contribute to the schema contract.
-- **Semantic Flexibility:** The directory supports multiple ways to describe schema changes (e.g., altering tables inline or via subsequent ALTER TABLE statements). The key is clarity and correctness so the CLI tooling can interpret the intended shape.
-
-### File Format and Execution
-
-- **Executable SQL Scripts:** Every file should be valid PostgreSQL with semicolon-terminated statements and a consistent dependency ordering.
-- **Integration with ZTD CLI:** The CLI parses these files to understand schema shapes. Treat this directory as authoritative: every schema change should be captured here as if it were applied to a clean database.
-
-### Maintenance Guidelines
-
-- **Human-Maintained Schema:** Developers own the schema structure; AI tooling may only assist with targeted edits.
-- **Conventions:** Follow the established naming, formatting, and typing patterns. Include comments to explain non-obvious schema choices.
-
-### Relationships
-
-- /ztd/domain-specs: Translates schema structures into behavioral expectations.
-- /ztd/enums: Provides the enum sets referenced by constraints or column defaults.
-
-## Domain Specifications
-
-The ztd/domain-specs/ directory documents key domain behaviors as human-readable specifications.
-
-### Purpose
-
-Each Markdown file describes one business concept, explains it in natural language, and pairs it with an example SELECT query inside a fenced SQL block. These specifications help AI agents understand **what** the domain logic should do without prescribing implementation details.
-
-### Format and Best Practices
-
-- One file per concept with a prose explanation followed by an example SELECT.
-- Keep exactly one executable SQL block per file (one file = one behavior).
-- Named parameters (e.g., :as_of) signal intent; you may translate them into positional placeholders when generating code.
-- Focus on semantics—use Markdown structuring (tables, bullets, etc.) to clarify the behavior.
-- Always update the description before touching the SQL when the behavior evolves.
-
-### Relationships
-
-- /ztd/ddl: Supplies the physical schema that backs the behavior.
-- /ztd/enums: Provides the vocabularies referenced in the domain logic.
-
-## Domain Enums
-
-The ztd/enums/ directory contains enumerated value sets such as statuses, tiers, or lifecycle states.
-
-### Purpose
-
-These enums are human-maintained and support:
-
-- AI-assisted SQL/code generation
-- TypeScript constant generation
-- Schema enforcement (e.g., CHECK constraints)
-- Frontend label rendering via display names
-
-### Format and Structure
-
-- The folder uses Markdown to keep the definitions readable.
-- Each enum is documented in a single file using SELECT ... FROM (VALUES ...) blocks with explicit column aliases.
-
-### Required Structure
-
-- Each row must include at least key and value columns.
-- Optional metadata like display_name, 
-ranking, or sort_order may be added for UI/logic purposes.
-
-### Guidelines
-
-- Keep naming conventions consistent and avoid duplicate value identifiers across unrelated enums.
-- Ensure compatibility with /ztd/domain-specs and /ztd/ddl when expanding enums.
-- Preserve human-readable display_name values as needed for front-end contexts.
-
-### Relationships
-
-- /ztd/ddl: Referenced by constraints or lookup tables.
-- /ztd/domain-specs: Provides the vocabulary for behavioral rules.
-- src/: Maps enums to generated constants or query logic.
+- `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.';