@rawsql-ts/ztd-cli 0.13.2 → 0.14.0

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

@@ -0,0 +1,8 @@
+// GENERATED FILE. DO NOT EDIT.
+
+export default {
+  ztdRootDir: 'ztd',
+  ddlDir: 'ztd/ddl',
+  enumsDir: 'ztd/enums',
+  domainSpecsDir: 'ztd/domain-specs',
+};

package/templates/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": "dist",
+    "tsBuildInfoFile": "dist/.tsbuildinfo"
+  },
+  "include": ["tests/**/*.ts"]
+}

package/templates/vitest.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['tests/**/*.test.ts'],
+    environment: 'node',
+    globals: true,
+    globalSetup: ['tests/support/global-setup.ts'],
+    // Starting a Postgres testcontainer can exceed the default 5s timeout on some machines.
+    testTimeout: 60_000,
+    hookTimeout: 60_000,
+  },
+});

package/templates/ztd/AGENTS.md

@@ -0,0 +1,103 @@
+# AGENTS: Zero Table Dependency Definitions
+
+## Generated files (important)
+
+- `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`.
+
+## DDL Specifications
+
+You are an AI assistant responsible for reading and respecting the contents of this /ztd/ddl directory.
+
+### Purpose
+
+This directory contains all canonical definitions of database structure, including CREATE TABLE, ALTER TABLE, constraints, and indexes. It is considered the **single source of truth** for database schema as interpreted by the ztd-cli.
+
+### Behavior Rules
+
+- **Never modify files in this folder unless explicitly instructed by a human.**
+- You may propose edits, reviews, or new DDL structures when asked, but you must preserve all human-authored structure, naming, and intent.
+- All DDL statements **must be semicolon-terminated** and valid PostgreSQL syntax.
+- You must not reorder statements arbitrarily; semantic meaning and dependency order must be preserved.
+- Respect formatting conventions, identifier styles, and comments written by humans.
+- When generating new tables or columns, infer types and constraints based on other schema examples or enums (if available).
+- Maintain consistency in column ordering, naming style, and constraint patterns.
+- When adding to existing definitions, do not remove human-authored comments unless told to.
+- Do not introduce structural changes that conflict with domain-specs or enums.
+
+### Interaction with Other Sources
+
+- Refer to /ztd/domain-specs for domain logic and behavioral definitions. These dictate *what* should exist in the schema.
+- Refer to /ztd/enums for allowable value sets when defining enum-like columns or constraints.
+- Always use those definitions as context when writing or editing this schema.
+
+If uncertain, defer to human authorship and request clarification.
+
+## Domain Specifications
+
+You are an AI agent reading this directory to interpret domain logic.
+
+### Instructions
+
+- Treat each Markdown file as defining **one domain behavior**.
+- Use the embedded SQL block (`sql ... `) as the **reference SELECT**.
+- Only the first top-level SELECT block should be considered executable logic.
+- Parameters may be written in :named format (e.g., :as_of). You must bind them as positional placeholders (e.g., $1, $2, ?) in generated code.
+- Do not generate or modify files in this directory unless explicitly asked.
+
+### Assumptions
+
+- `ztd-config` parses only DDL (`ztd/ddl/**/*.sql`) to generate row shapes.
+- These specifications are for **humans and AI consumption** (documentation + reference SQL).
+- Comments and descriptions exist to help you interpret logic correctly.
+
+### Rules
+
+- Never ignore the human-written description above the SQL block.
+- Keep exactly one executable SQL block per file (one file = one behavior).
+- Do not reorder or optimize the SQL unless explicitly instructed.
+- Preserve the semantic meaning as given in the specification.
+- This folder defines **what** logic means. Your job is to reproduce that logic elsewhere (e.g., in src/ or tests).
+
+If in doubt, ask for clarification or defer to human judgment.
+
+## Domain Enums
+
+You are an AI assistant responsible for reading domain enum definitions from this folder.
+
+### Purpose
+
+This directory defines canonical value sets (enums) such as status codes and plan tiers. These definitions inform your code generation logic, constraint enforcement, and vocabulary use.
+
+### Behavior Guidelines
+
+- Read from the Markdown file containing SQL select ... from (values ...) blocks.
+- Never invent magic numbers or enum values. Always use those explicitly defined here.
+- Do not modify or append new enums unless explicitly instructed by a human.
+
+### SQL Rules
+
+- Each SQL block defines an enum set.
+- Keep exactly one executable SQL block per file (one file = one enum set).
+- All blocks follow the form:
+
+`sql
+select v.*
+from (
+  values
+    (1, 'some_code', 'some_label')
+) v(key, value, display_name);
+`
+
+- You must extract key and value pairs as the authoritative mapping.
+- display_name, 
+ranking, or other metadata may be used where helpful (e.g., UI rendering or sorting).
+
+### Use in Code Generation
+
+- Use these enums when generating SQL WHERE clauses, conditionals, or constants.
+- When translating logic from /ztd/domain-specs, map references like :status__established to corresponding values here.
+- Maintain full consistency with enum names and intent.
+
+If a required enum is missing, raise an error or ask for human clarification.

package/templates/ztd/README.md

@@ -0,0 +1,84 @@
+# ZTD Definitions
+
+This directory hosts the schema, domain-spec, and enum definitions that feed native ZTD workflows.
+
+## 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.