@rawsql-ts/ztd-cli 0.15.0 → 0.17.0

package/dist/utils/optionalDependencies.js

@@ -0,0 +1,96 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearOptionalDependencyCache = clearOptionalDependencyCache;
+exports.ensureTestkitCoreModule = ensureTestkitCoreModule;
+exports.ensureAdapterNodePgModule = ensureAdapterNodePgModule;
+exports.ensurePgModule = ensurePgModule;
+exports.ensurePostgresContainerModule = ensurePostgresContainerModule;
+const node_path_1 = __importDefault(require("node:path"));
+const node_module_1 = require("node:module");
+const node_url_1 = require("node:url");
+const moduleCache = new Map();
+async function loadOptionalModule(cacheKey, loader, description, installHint) {
+    if (moduleCache.has(cacheKey)) {
+        return moduleCache.get(cacheKey);
+    }
+    const moduleLoader = loader()
+        .catch((error) => {
+        moduleCache.delete(cacheKey);
+        const installNote = installHint ? ` Install it via \`${installHint}\`.` : '';
+        const original = error instanceof Error ? ` (${error.message})` : '';
+        throw new Error(`${description}${installNote}${original}`);
+    });
+    moduleCache.set(cacheKey, moduleLoader);
+    return moduleLoader;
+}
+function clearOptionalDependencyCache() {
+    moduleCache.clear();
+}
+function requireFromWorkspace(specifier) {
+    const require = (0, node_module_1.createRequire)(node_path_1.default.resolve(process.cwd(), 'package.json'));
+    return require(specifier);
+}
+async function loadAdapterNodePgModule() {
+    try {
+        return requireFromWorkspace('@rawsql-ts/adapter-node-pg');
+    }
+    catch (error) {
+        // Workspace tests can run before adapter build output exists, so use source entrypoint.
+        const workspaceAdapterSrc = node_path_1.default.resolve(process.cwd(), 'packages/adapters/adapter-node-pg/src/index.ts');
+        try {
+            return (await Promise.resolve(`${(0, node_url_1.pathToFileURL)(workspaceAdapterSrc).href}`).then(s => __importStar(require(s))));
+        }
+        catch {
+            throw error;
+        }
+    }
+}
+async function ensureTestkitCoreModule() {
+    return loadOptionalModule('@rawsql-ts/testkit-core', () => Promise.resolve().then(() => __importStar(require('@rawsql-ts/testkit-core'))), 'This command requires @rawsql-ts/testkit-core so fixtures and schema metadata are available.', 'pnpm add -D @rawsql-ts/testkit-core');
+}
+async function ensureAdapterNodePgModule() {
+    return loadOptionalModule('@rawsql-ts/adapter-node-pg', loadAdapterNodePgModule, 'A database adapter (for example @rawsql-ts/adapter-node-pg) is required to execute the rewritten SQL.', 'pnpm add -D @rawsql-ts/adapter-node-pg');
+}
+async function ensurePgModule() {
+    return loadOptionalModule('pg', () => Promise.resolve().then(() => __importStar(require('pg'))), 'The SQL lint command needs a PostgreSQL driver such as pg.', 'pnpm add -D pg');
+}
+async function ensurePostgresContainerModule() {
+    return loadOptionalModule('@testcontainers/postgresql', () => Promise.resolve().then(() => __importStar(require('@testcontainers/postgresql'))), 'ztd lint wants to spin up a disposable Postgres container via @testcontainers/postgresql.', 'pnpm add -D @testcontainers/postgresql');
+}
+//# sourceMappingURL=optionalDependencies.js.map

package/dist/utils/optionalDependencies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optionalDependencies.js","sourceRoot":"","sources":["../../src/utils/optionalDependencies.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgEA,oEAEC;AAwBD,0DAOC;AAED,8DAOC;AAED,wCAOC;AAED,sEAOC;AA5HD,0DAA6B;AAC7B,6CAA4C;AAC5C,uCAAyC;AAEzC,MAAM,WAAW,GAAG,IAAI,GAAG,EAA4B,CAAC;AAExD,KAAK,UAAU,kBAAkB,CAC/B,QAAgB,EAChB,MAAwB,EACxB,WAAmB,EACnB,WAAmB;IAEnB,IAAI,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9B,OAAO,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAe,CAAC;IACjD,CAAC;IAED,MAAM,YAAY,GAAG,MAAM,EAAE;SAC1B,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;QACf,WAAW,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC7B,MAAM,WAAW,GAAG,WAAW,CAAC,CAAC,CAAC,qBAAqB,WAAW,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7E,MAAM,QAAQ,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,MAAM,IAAI,KAAK,CAAC,GAAG,WAAW,GAAG,WAAW,GAAG,QAAQ,EAAE,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;IAEL,WAAW,CAAC,GAAG,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;IACxC,OAAO,YAAY,CAAC;AACtB,CAAC;AAsCD,SAAgB,4BAA4B;IAC1C,WAAW,CAAC,KAAK,EAAE,CAAC;AACtB,CAAC;AAED,SAAS,oBAAoB,CAAI,SAAiB;IAChD,MAAM,OAAO,GAAG,IAAA,2BAAa,EAAC,mBAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,cAAc,CAAC,CAAC,CAAC;IAC3E,OAAO,OAAO,CAAC,SAAS,CAAM,CAAC;AACjC,CAAC;AAED,KAAK,UAAU,uBAAuB;IACpC,IAAI,CAAC;QACH,OAAO,oBAAoB,CAAsB,4BAA4B,CAAC,CAAC;IACjF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,wFAAwF;QACxF,MAAM,mBAAmB,GAAG,mBAAI,CAAC,OAAO,CACtC,OAAO,CAAC,GAAG,EAAE,EACb,gDAAgD,CACjD,CAAC;QACF,IAAI,CAAC;YACH,OAAO,CAAC,yBAAa,IAAA,wBAAa,EAAC,mBAAmB,CAAC,CAAC,IAAI,uCAAC,CAAwB,CAAC;QACxF,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;AACH,CAAC;AAEM,KAAK,UAAU,uBAAuB;IAC3C,OAAO,kBAAkB,CACvB,yBAAyB,EACzB,GAAG,EAAE,mDAAQ,yBAAyB,GAAC,EACvC,8FAA8F,EAC9F,qCAAqC,CACtC,CAAC;AACJ,CAAC;AAEM,KAAK,UAAU,yBAAyB;IAC7C,OAAO,kBAAkB,CACvB,4BAA4B,EAC5B,uBAAuB,EACvB,uGAAuG,EACvG,wCAAwC,CACzC,CAAC;AACJ,CAAC;AAEM,KAAK,UAAU,cAAc;IAClC,OAAO,kBAAkB,CACvB,IAAI,EACJ,GAAG,EAAE,mDAAQ,IAAI,GAAC,EAClB,4DAA4D,EAC5D,gBAAgB,CACjB,CAAC;AACJ,CAAC;AAEM,KAAK,UAAU,6BAA6B;IACjD,OAAO,kBAAkB,CACvB,4BAA4B,EAC5B,GAAG,EAAE,mDAAQ,4BAA4B,GAAC,EAC1C,2FAA2F,EAC3F,wCAAwC,CACzC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rawsql-ts/ztd-cli",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "DB-agnostic scaffolding and DDL helpers for Zero Table Dependency projects",
   "main": "dist/index.js",
   "bin": {
@@ -22,22 +22,31 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@testcontainers/postgresql": "^10.28.0",
     "chokidar": "^5.0.0",
     "commander": "^12.0.0",
-    "diff": "^5.1.0",
+    "diff": "^8.0.3",
     "fast-glob": "^3.3.3",
-    "pg": "^8.11.1",
-    "testcontainers": "^10.28.0",
-    "@rawsql-ts/pg-testkit": "0.15.0",
-    "rawsql-ts": "0.15.0",
-    "@rawsql-ts/testkit-core": "0.15.0"
+    "rawsql-ts": "^0.16.0"
+  },
+  "peerDependencies": {
+    "@rawsql-ts/adapter-node-pg": "^0.15.2"
+  },
+  "peerDependenciesMeta": {
+    "@rawsql-ts/adapter-node-pg": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@testcontainers/postgresql": "^10.28.0",
     "@types/diff": "^5.0.1",
     "@types/node": "^22.13.10",
+    "pg": "^8.11.1",
+    "testcontainers": "^10.28.0",
     "typescript": "^5.8.2",
-    "vitest": "^4.0.7"
+    "vitest": "^4.0.7",
+    "@rawsql-ts/adapter-node-pg": "^0.15.2",
+    "@rawsql-ts/testkit-core": "^0.15.1",
+    "@rawsql-ts/testkit-postgres": "^0.15.1"
   },
   "files": [
     "dist",
@@ -46,7 +55,6 @@
     "README.md"
   ],
   "scripts": {
-    "prebuild": "pnpm --filter @rawsql-ts/testkit-core build && pnpm --filter @rawsql-ts/pg-testkit build",
     "build": "tsc -p tsconfig.json",
     "test": "vitest run",
     "lint": "eslint src --ext .ts",

package/templates/AGENTS.md

@@ -1,312 +1,52 @@
-# Appendix: Development Workflow Using Zero Table Dependency (ZTD)
+# Workspace AGENTS
 
-This application uses **Zero Table Dependency (ZTD)** as an internal development workflow for writing, testing, and maintaining SQL logic.
-ZTD is not part of the application's runtime behavior; rather, it provides a framework for:
+This repository uses directory-scoped AGENTS.
+Rules live close to where the work happens.
 
-- Maintaining consistent SQL across the project
-- Keeping schema, domain specifications, and enums synchronized
-- Ensuring deterministic SQL unit tests
-- Enabling structured collaboration between humans and AI
+## Rule precedence
 
-This section documents how ZTD is used inside this repository as a development methodology.
+- The closest "AGENTS.md" to the file being edited has the highest priority.
+- Parent directories provide shared rules.
+- Child directories should only describe deltas.
 
----
+## Global non-negotiables
 
-## Defaults (important)
+- Do not guess. If something is unknown, state "Not observed" and propose the next check.
+- Do not edit generated artifacts unless explicitly instructed.
+- Respect ownership boundaries: human-owned contracts must not be changed without explicit instruction.
 
-- This project adopts **ZTD as the default development and testing methodology**.
-- ZTD is assumed unless explicitly stated otherwise.
-- Detailed rules about test execution modes are defined in `templates/tests/AGENTS.md`.
+## Runtime vs non-runtime
 
----
+- Runtime assets live under "src/": executed/loaded by the application.
+- Non-runtime assets live under "ztd/" and parts of "tests/": used for verification and generation.
 
-## Generated files (important)
+## Human-owned vs AI-assisted (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`.
+Human-owned (do not change without explicit instruction):
+- "ztd/ddl" (physical schema / DDL)
+- "src/catalog/specs" (query contracts: params + DTO + semantics)
+- "src/sql" (SQL assets; AI may propose patches, but do not rewrite intent)
 
----
+AI-assisted (implementation and verification):
+- "src/repositories"
+- "src/catalog/runtime"
+- "tests" (except "tests/generated")
 
-## TypeScript validation (required)
+Never touch by hand:
+- "tests/generated"
 
-After any code change, TypeScript type checking **must** be performed and must pass.
+## Where to read next
 
-- Run the project-appropriate typecheck command (e.g. `pnpm typecheck`).
-- If generated files are involved, run generators first, then re-run typecheck.
-- If typecheck fails, fix errors by root cause, not only the first reported error.
-- A change is not considered complete unless typecheck is green.
+- "src/catalog/AGENTS.md": catalog layout and contract boundaries
+- "src/repositories/AGENTS.md": repository responsibilities and restrictions
+- "src/sql/AGENTS.md": SQL asset rules
+- "tests/AGENTS.md": ZTD testing rules
+- "ztd/ddl/AGENTS.md": DDL authoring rules
 
-Rationale:  
-In ZTD-based development, many schema or SQL inconsistencies surface first as TypeScript errors via generated row maps and DTOs.
-Type checking is a primary correctness signal, not an optional step.
+## Test environment guarantee (important)
 
----
+- This workspace MUST be test-runnable immediately after initialization.
+- `pnpm test` (or equivalent) must not fail due to missing configuration.
+- Test runner configuration (e.g. vitest.config.ts) is considered part of the template contract.
 
-## ZTD Implementation Guide (src/)
-
-The `src/` directory should contain pure TypeScript logic that operates on the row interfaces generated by `tests/generated/ztd-row-map.generated.ts`. Tests should import the row map, repositories should import DTOs, and fixtures must stay under `tests/`. Keep production code decoupled from the generated row map to preserve the distinction between implementation and test scaffolding.
-
-### Repository Classes: What to Care About
-
-#### Scope and Responsibility
-- Repository classes are responsible for executing SQL and returning query results.
-- Avoid embedding business logic, thresholds, or data reshaping inside repositories.
-- Treat repositories as thin adapters over SQL.
-
-#### Mandatory testing rule (important)
-
-Whenever a repository class is created or modified, corresponding tests **must** be created or updated.
-
-Rules:
-- Every public repository method must be covered by tests.
-- Tests must call repository methods, not raw SQL files or SQL strings.
-- ZTD fixtures are the only allowed source of database state in tests.
-- A repository change without tests is considered incomplete.
-
-Rationale:  
-ZTD derives much of its value from deterministic, repository-level tests.
-Without tests, schema drift and SQL inconsistencies cannot be detected.
-
-#### SQL Management
-- Prefer keeping SQL in separate `.sql` files.
-  - If no explicit instruction is given, separate SQL into files by default.
-- Repository classes should reference SQL files by name, not inline long SQL strings.
-
-#### Specifications and Documentation
-- If a markdown file with the same base name as the repository or SQL exists, read it before implementation.
-  - Such files may contain repository-local specifications (e.g. decision tables, thresholds, request/response notes).
-  - Naming should be aligned (e.g. `FooRepository.ts`, `foo.sql`, `foo.md`).
-
-#### Request and Response Contracts
-- Be explicit about request parameters (types, nullability, constraints).
-- Be explicit about response shape (columns, ordering, cardinality).
-- Prefer documenting contracts in the repository-local markdown file rather than code comments when they are non-trivial.
-
-### SqlClient lifecycle policy (important)
-
-- When using `src/db/sql-client.ts`, prefer a shared `SqlClient` per worker process (singleton).
-- Avoid creating a new database connection for every query or test case.
-- Do not share a live connection across parallel workers; each worker should own its own shared client or pool.
-- If you need strict isolation, create a dedicated client for that scope and close it explicitly.
-
-### Repository SQL and DTO policy (important)
-
-- Repository SQL must return application-facing DTO shapes.
-- SQL SELECT statements should alias columns to camelCase and match the repository return types.
-- Do not introduce intermediate `*Row` types when SQL already returns DTO-compatible shapes.
-- Define separate Row types only when SQL intentionally returns database-shaped (snake_case) rows, and always convert them explicitly.
-
-### Sequence / identity column policy (important)
-
-- Sequence / identity columns (auto-generated IDs) are infrastructure concerns.
-- Do not explicitly assign values to sequence / identity columns in `INSERT` statements unless explicitly instructed.
-- Repository method inputs should omit sequence / identity columns by default.
-- Only treat an ID as input data when it represents a business rule (e.g. natural keys, externally assigned IDs).
-
-### No test-driven fallbacks in production code (important)
-
-- Do not add fallbacks in `src/` that exist only to accommodate ZTD/testkit/rewriter limitations.
-- If a query fails to be rewritten into ZTD form, do not change runtime behavior to compensate.
-- Report tooling issues with minimal reproduction and expected behavior.
-
-Rationale:  
-Production code must not diverge from intended SQL semantics due to tooling constraints.
-
----
-
-## ZTD Test Guide (tests/)
-
-Testing under ZTD follows dedicated, directory-scoped rules.
-
-- Test design, execution mode selection, and constraints are defined in:
-  - `templates/tests/AGENTS.md`
-- Tests validate repository behavior and returned DTOs.
-- Raw SQL files or SQL strings must not be tested directly.
-
----
-
-# ZTD Directory Layout
-
-```
-/ztd
-  /ddl
-    *.sql               <- physical schema definitions
-
-  /domain-specs
-    *.md                <- one behavioral SELECT per file (one SQL block)
-
-  /enums
-    *.md                <- one enum definition per file (one SQL block)
-
-  README.md             <- documentation for the layout
-  AGENTS.md             <- combined guidance for DDL, enums, and specs
-
-/src                    <- application & repository logic
-/tests                  <- ZTD tests, fixtures, row-maps
-```
-
-The file `tests/generated/ztd-layout.generated.ts` ensures ZTD CLI always points to the correct directories.
-
----
-
-# Protected directories and edit ownership (important)
-
-- DDL editing is human-led: `ztd/ddl/`
-- Domain specs editing is human-led: `ztd/domain-specs/`
-- Enums editing is human-led: `ztd/enums/`
-- Application code is shared ownership: `src/`
-- Tests are shared ownership: `tests/`
-  - Detailed test constraints live in `templates/tests/AGENTS.md`.
-
-Additionally:
-- Never modify `ztd/AGENTS.md` or `ztd/README.md` without explicit instruction.
-- When changes are required in human-led directories, prefer proposing a patch and explaining the impact before applying it.
-
----
-
-# Principles of ZTD in This Repository
-
-### 1. Humans own the definitions
-- Physical schema (DDL)
-- Domain semantics (domain-specs)
-- Enumerations (enums)
-- Repository interfaces
-
-### 2. AI assists with implementation
-- Generating repository SQL
-- Updating fixtures
-- Producing intermediate TypeScript structures
-- Ensuring SQL adheres to DDL, enums, and domain-specs
-
-### 3. ZTD enforces consistency
-ZTD tests verify that:
-- SQL logic matches DDL shapes
-- SQL semantics match domain-specs
-- SQL values match enumerations
-
-If anything diverges, ZTD failures surface immediately and deterministically.
-
----
-
-# Development Workflows
-
-Different types of changes start from different entry points. Use the workflow appropriate for your situation.
-
----
-
-# Workflow A - Starting From DDL Changes
-Modifying tables, columns, constraints, indexes.
-
-1. Edit DDL files in `ztd/ddl/`.
-2. Run `npx ztd ztd-config`.
-3. Update repository SQL to match the new schema.
-4. Update fixtures if result shapes changed.
-5. Run tests.
-
-Flow: DDL to Repository SQL to Fixtures and Tests to Application
-
----
-
-# Workflow B - Starting From Repository Interface Changes
-Changing method signatures, adding new repository methods, etc.
-
-1. Modify the repository interface or implementation in `/src`.
-2. Use AI assistance to generate or update the SQL implementation.
-3. If the generated SQL conflicts with domain-specs or enums, update definitions first.
-4. Run ZTD tests.
-5. Regenerate config if SQL output shape changed.
-
-Flow: Interface to SQL to Specs (if needed) to Tests
-
----
-
-# Workflow C - Starting From Repository SQL Logic Changes
-Bug fixes, refactoring, rewriting queries.
-
-1. Edit SQL inside the repository.
-2. Run ZTD tests.
-3. If intended behavior changes, update the appropriate file in `ztd/domain-specs/`.
-4. Update fixtures as needed.
-5. Regenerate config if result shape changed.
-
-Flow: SQL to Domain-specs to Tests
-
----
-
-# Workflow D - Starting From Enum or Domain Specification Changes
-Business rule changes or conceptual model updates.
-
-Flow: Specs or Enums to SQL to Tests to (DDL if required)
-
----
-
-# Combined Real-World Examples
-
-- Adding a new contract state:
-  enums to domain-spec to SQL to config to tests
-
-- Adding a new table:
-  DDL to config to SQL to fixtures to tests
-
-- Fixing business logic:
-  SQL to domain-spec to tests
-
-ZTD ensures the development always converges into a consistent, validated workflow.
-
----
-
-# Human Responsibilities
-
-Humans maintain:
-
-- Schema definitions (`ztd/ddl`)
-- Domain logic definitions (`ztd/domain-specs`)
-- Domain enumerations (`ztd/enums`)
-- Repository interfaces and architectural decisions
-- Acceptance and review of AI-generated patches
-
-Humans decide what is correct.
-
----
-
-# AI Responsibilities
-
-AI must:
-
-- Use domain-specs as the semantic source of truth
-- Use enums as the canonical vocabulary source
-- Use DDL as the physical structure constraint
-- Generate SQL consistent with all definitions
-- Update fixtures when needed
-- Never modify `ztd/AGENTS.md` or `ztd/README.md` without explicit instruction
-
-AI decides how to implement, but not what is correct.
-
----
-
-# ZTD CLI Responsibilities
-
-ZTD CLI:
-
-- Parses DDL to compute schema shapes
-- Rewrites SQL via CTE shadowing for testing
-- Generates `ztd-row-map.generated.ts`
-- Enables deterministic, parallel SQL unit tests
-
-ZTD is the verification engine that validates correctness beyond static typing.
-
----
-
-# Summary
-
-This appendix documents how ZTD is used strictly as an internal implementation and maintenance guide.
-It does not affect the runtime behavior of the application.
-Its purpose is ensuring:
-
-- Schema integrity
-- SQL correctness
-- Domain consistency
-- Reliable AI-assisted development
-
-With ZTD, humans define the meaning, AI writes the implementation, and tests guarantee correctness.
+If tests fail due to missing config, this is a template defect, not a user error.