@rawsql-ts/ztd-cli 0.13.3 → 0.14.0

package/README.md

@@ -16,6 +16,8 @@ For actual test execution:
 pnpm add -D @rawsql-ts/pg-testkit
 ```
 
+If you run `npx ztd init`, the CLI will automatically add and install the devDependencies referenced by the generated templates (Postgres defaults to `@rawsql-ts/pg-testkit`).
+
 Then use the CLI through `npx ztd` or the installed `ztd` bin.
 
 ## Getting Started (Fast Path)
@@ -26,6 +28,21 @@ Then use the CLI through `npx ztd` or the installed `ztd` bin.
    npx ztd init
    ```
 
+   For tutorials and greenfield projects, we recommend the optional SQL client seam:
+
+  ```bash
+  npx ztd init --with-sqlclient
+  ```
+
+  Use `--with-sqlclient` when you want a minimal `SqlClient` boundary for repositories. Skip it if your project
+  already has a database abstraction (Prisma, Drizzle, Kysely, custom adapters) to avoid duplicating layers.
+
+  ```bash
+  npx ztd init --with-app-interface
+  ```
+
+  Use `--with-app-interface` to append the application interface guidance block to `AGENTS.md` without generating the ZTD layout or touching other files.
+
 2. Put your schema into `ztd/ddl/`:
 
    - Edit the starter file (default): `ztd/ddl/public.sql`, or
@@ -58,12 +75,13 @@ You can introduce ZTD incrementally; existing tests and ORMs can remain untouche
 - `ztd/ddl/<schema>.sql` (starter schema files you can edit or replace; the default schema is `public.sql`)
 - `tests/generated/ztd-row-map.generated.ts` (auto-generated `TestRowMap`, the canonical test type contract; do not commit)
 - `tests/support/testkit-client.ts` (auto-generated helper that boots a database client, wires a driver, and shares fixtures across the suite)
-- `ztd.config.json` (CLI defaults and resolver hints: `dialect`, `ddlDir`, `testsDir`, plus `ddl.defaultSchema`/`ddl.searchPath` for resolving unqualified tables)
+- `ztd.config.json` (CLI defaults and resolver hints: `dialect`, `ddlDir`, `testsDir`, `ddlLint`, plus `ddl.defaultSchema`/`ddl.searchPath` for resolving unqualified tables)
 - `tests/generated/ztd-layout.generated.ts` (generated layout snapshot; do not commit)
 - `tests/support/global-setup.ts` (shared test setup used by the generated testkit client)
 - `README.md` describing the workflow and commands
-- `AGENTS.md` (copied from the package template unless the project already has one)
+- `AGENTS.md` (copied from the package template unless the project already has one; `--with-app-interface` adds the application interface guidance block at the end)
 - `ztd/AGENTS.md` and `ztd/README.md` (folder-specific instructions that describe the new schema/domain layout)
+- `src/db/sql-client.ts` (optional; generated only with `--with-sqlclient`)
 - Optional guide stubs under `src/` and `tests/` if requested
 
 The resulting project follows the "DDL -> ztd-config -> tests" flow so you can regenerate everything from SQL-first artifacts.
@@ -74,6 +92,12 @@ The resulting project follows the "DDL -> ztd-config -> tests" flow so you can r
 
 Creates a ZTD-ready project layout (DDL folder, config, generated layout, and test support stubs). It does not connect to your database.
 
+Use `--with-sqlclient` to scaffold a minimal repository-facing SQL client for tutorials and new projects. It is opt-in
+to avoid colliding with existing database layers. If you use `pg`, adapt `client.query(...)` so it returns a plain row
+array (`T[]`) that satisfies the generated `SqlClient` interface.
+
+Use `--with-app-interface` to append the application interface guidance block to `AGENTS.md`. This documentation-only option leaves every other file untouched, making it easy to apply the guidance to existing repositories without rerunning the full layout generator.
+
 ### `ztd ztd-config`
 
 Reads every `.sql` file under the configured DDL directory and produces the generated artifacts under `tests/generated/`:
@@ -142,6 +166,143 @@ Driver responsibilities live in companion packages such as `@rawsql-ts/pg-testki
 
 The driver sits downstream of `testkit-core` and applies the rewrite + fixture pipeline before running any database interaction. Install the driver, configure it in your tests, and point it at the row map from `tests/generated/ztd-row-map.generated.ts`.
 
+### SQL rewrite logging (generated `testkit-client.ts`)
+
+The `tests/support/testkit-client.ts` helper generated by `ztd init` can emit structured logs that show the SQL before and after pg-testkit rewrites it.
+
+Enable it via environment variables:
+
+- `ZTD_SQL_LOG=1` (or `true`/`yes`): log original + rewritten SQL
+- `ZTD_SQL_LOG_PARAMS=1` (or `true`/`yes`): include parameters in the logs
+
+You can also enable/disable logging per call by passing `ZtdSqlLogOptions` as the second argument to `createTestkitClient`.
+
+## Benchmark summary
+
+### Purpose
+
+This benchmark executes the same repository implementation with two different supporting stacks: the Traditional schema/migration workflow (schema setup + seed + query + cleanup) and the ZTD fixture-backed workflow (repository query → rewrite → fixture materialization). The comparison highlights:
+
+- End-to-end wall-clock time including runner startup.
+- DB execution time and SQL count so Traditional’s higher SQL volume is explicit.
+- ZTD rewrite and fixture breakdowns so the internal costs of the pg-testkit pipeline are visible.
+- Parallelism effects, runner startup costs, and where the break-even point lies as suite size grows.
+
+### Assumptions and environment
+
+This benchmark compares ZTD-style repository tests against a traditional migration-based workflow while exercising the same repository methods. All numbers are measured with the test runner included unless stated otherwise.
+
+#### Environment (measured run)
+
+- Node.js: v22.14.0
+- OS: Windows 10 (build 26100)
+- CPU: AMD Ryzen 7 7800X3D (16 logical cores)
+- Database: PostgreSQL 18.1 (containerized; `testcontainers`)
+- Parallel workers: 4
+- Report date: 2025-12-20
+
+#### Benchmark shape
+
+- Repository test cases: 3 (`customer_summary`, `product_ranking`, `sales_summary`)
+- Each test performs: 1 repository call (1 SQL execution per test case)
+- The Traditional workflow wraps every repository execution with migration, seeding, and cleanup SQL, whereas the ZTD workflow captures the same query, feeds it to pg-testkit, and replays the rewritten/select-only statements backed by fixtures.
+- Suite sizes shown in the report:
+  - 3 tests (baseline)
+  - 30 tests (the same 3 cases repeated to approximate a larger suite)
+
+The 30-test suite exists to show how runner overhead amortizes as the number of executed tests grows, while keeping the tested SQL and data constant.
+
+#### What is included / excluded
+
+- **Runner-included runs (main comparison):** wall-clock time including `pnpm` + `vitest` startup and test execution.
+- **Steady-state section:** measures incremental cost per iteration after the runner is warm (first iteration excluded), to approximate watch/CI-like “many tests per single runner invocation”.
+- **Container startup:** excluded (the Postgres container is shared across runs).
+
+#### Fairness / bias notes (important)
+
+This benchmark intentionally measures the **Traditional** workflow under favorable assumptions:
+
+- **Traditional SQL construction cost is treated as zero**: queries are hard-coded raw SQL strings (no ORM/query-builder generation time).
+- **Traditional migration/DDL generation cost is treated as zero**: schema/migration SQL is also written directly (no ORM schema DSL or migration generation time).
+
+In contrast, the **ZTD** benchmark includes the repository layer’s normal SQL usage:
+
+- **ZTD includes SQL construction time as exercised by the repository layer** (i.e., whatever the test code does to produce the SQL text), in addition to rewrite/fixture overhead.
+
+Because real-world ORM workflows usually add both query generation and migration generation overhead on top of what is measured here, this setup should be interpreted as a **lower bound for Traditional** and a relatively conservative comparison against ZTD.
+
+### Results (runner included)
+
+#### End-to-end runtime
+
+| Suite size | Scenario | Workers | Avg Total (ms) | Avg Startup (ms) | Avg Execution (ms) | Startup % | Avg ms/test | Avg SQL Count | Avg DB (ms) |
+| ---: | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| 3 | Traditional | 1 | 1951.08 | 1013.22 | 937.86 | 51.8% | 650.36 | 36 | 123.06 |
+| 3 | Traditional | 4 | 1301.56 | 967.02 | 334.54 | 74.3% | 433.85 | 36 | 39.06 |
+| 3 | ZTD | 1 | 2283.66 | 979.91 | 1303.74 | 42.9% | 761.22 | 3 | 11.34 |
+| 3 | ZTD | 4 | 1430.64 | 957.75 | 472.89 | 66.9% | 476.88 | 3 | 3.81 |
+| 30 | Traditional | 1 | 3085.48 | 1018.71 | 2066.77 | 33.0% | 102.85 | 360 | 1009.85 |
+| 30 | Traditional | 4 | 1788.35 | 996.66 | 791.68 | 55.8% | 59.61 | 360 | 392.83 |
+| 30 | ZTD | 1 | 2480.84 | 957.91 | 1522.94 | 38.6% | 82.69 | 30 | 44.82 |
+| 30 | ZTD | 4 | 1507.46 | 944.57 | 562.88 | 62.7% | 50.25 | 30 | 17.69 |
+
+### What this shows
+- **Small suites (3 tests) are dominated by runner startup.** At this scale, Traditional is faster (both serial and 4-worker), because fixed startup overhead and per-test harness work overwhelm ZTD’s per-test savings.
+- **As suite size grows (30 tests), ZTD becomes faster end-to-end.**
+  - Serial: ZTD 2480.84 ms vs Traditional 3085.48 ms
+  - 4 workers: ZTD 1507.46 ms vs Traditional 1788.35 ms
+- **Parallel execution helps both approaches**, but the improvement is constrained by startup overhead:
+  - With 4 workers, the startup share rises (more of the total becomes fixed runner cost), so scaling is not linear.
+
+### Break-even intuition (where ZTD starts to win)
+
+From these results, the practical break-even is **between 3 and 30 tests** under the current environment and runner-included setup.
+
+Why:
+- Traditional has high per-test DB work (many SQL statements + significant DB time).
+- ZTD has low per-test DB work (few SQL statements), but adds rewrite + fixture overhead.
+- Once the suite is large enough that **execution dominates startup**, ZTD’s reduced DB work overtakes its rewrite/fixture costs.
+
+### ZTD cost structure (what is expensive)
+
+ZTD’s incremental work per test is primarily:
+- **SQL-to-ZTD rewrite time**
+- **Fixture materialization time**
+- **DB query time** (typically small compared to Traditional)
+
+A concrete view is easiest in the steady-state section below, where the runner is warm.
+
+### Steady-state (runner warm) incremental cost
+
+This approximates watch/CI iterations where the runner has already started (first repetition excluded as warmup).
+
+| Suite | Workers | Avg incremental time per iteration (ms) | Avg SQL Count | Avg DB time (ms) | Avg rewrite (ms) | Avg fixture (ms) |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| Traditional (30 tests) | 1 | 1260.20 | 360 | 1039.98 | - | - |
+| ZTD (30 tests) | 1 | 93.73 | 30 | 30.08 | 32.00 | 20.42 |
+| ZTD (30 tests) | 4 | 91.14 | 30 | 29.95 | 30.75 | 19.40 |
+
+### What this shows
+- Traditional steady-state is dominated by DB time (~1040 ms out of ~1260 ms).
+- ZTD steady-state is dominated by **rewrite (~31 ms) + fixture (~20 ms)**; DB time is ~30 ms.
+- Parallelism has limited impact in ZTD steady-state here because the per-iteration work is already small and may be bounded by coordination / shared overheads.
+
+### Conclusion
+
+- **Runner included (realistic)**:
+  - For very small suites, startup dominates and Traditional can be faster.
+  - For larger suites, ZTD wins end-to-end due to dramatically lower DB work and SQL count.
+- **Parallel execution matters**, but it mainly reduces the execution portion; runner startup becomes the limiting floor.
+- **ZTD’s main costs are rewrite and fixture preparation**, not DB time. This is good news: optimizing rewrite/fixture logic is the highest-leverage path for further speedups.
+
+To regenerate the report, run:
+
+```bash
+pnpm ztd:bench
+```
+
+The report is written to `tmp/bench/report.md`.
+
 ## Concepts (Why ZTD?)
 
 ### What is ZTD?

package/dist/commands/init.d.ts

@@ -1,6 +1,8 @@
 import { Command } from 'commander';
 import { type ZtdConfigGenerationOptions } from './ztdConfig';
 import { type PullSchemaOptions } from './pull';
+type PackageManager = 'pnpm' | 'npm' | 'yarn';
+type PackageInstallKind = 'devDependencies' | 'install';
 export interface Prompter {
     selectChoice(question: string, choices: string[]): Promise<number>;
     promptInput(question: string, example?: string): Promise<string>;
@@ -25,10 +27,19 @@ export interface ZtdConfigWriterDependencies {
     checkPgDump: () => boolean;
     log: (message: string) => void;
     copyAgentsTemplate: (rootDir: string) => string | null;
+    installPackages: (options: {
+        rootDir: string;
+        kind: PackageInstallKind;
+        packages: string[];
+        packageManager: PackageManager;
+    }) => Promise<void> | void;
 }
 export interface InitCommandOptions {
     rootDir?: string;
     dependencies?: Partial<ZtdConfigWriterDependencies>;
+    withSqlClient?: boolean;
+    withAppInterface?: boolean;
 }
 export declare function runInitCommand(prompter: Prompter, options?: InitCommandOptions): Promise<InitResult>;
 export declare function registerInitCommand(program: Command): void;
+export {};

package/dist/commands/init.js

@@ -79,12 +79,26 @@ const TESTS_CONFIG_TEMPLATE = 'tests/ztd-layout.generated.ts';
 const TESTKIT_CLIENT_TEMPLATE = 'tests/support/testkit-client.ts';
 const GLOBAL_SETUP_TEMPLATE = 'tests/support/global-setup.ts';
 const VITEST_CONFIG_TEMPLATE = 'vitest.config.ts';
+const SQL_CLIENT_TEMPLATE = 'src/db/sql-client.ts';
 const NEXT_STEPS = [
     ' 1. Review the schema files under ztd/ddl/<schema>.sql',
     ' 2. Inspect tests/generated/ztd-layout.generated.ts for the SQL layout',
     ' 3. Run npx ztd ztd-config',
     ' 4. Run ZTD tests with pg-testkit'
 ];
+const AGENTS_FILE_CANDIDATES = ['AGENTS.md', 'AGENTS_ztd.md'];
+const APP_INTERFACE_SECTION_MARKER = '## Application Interface Guidance';
+const APP_INTERFACE_SECTION = `---
+## Application Interface Guidance
+
+1. Repository interfaces follow Command in, Domain out so commands capture inputs and repositories return domain shapes.
+2. Command definitions and validation stay unified to prevent divergence between surface APIs and SQL expectations.
+3. Input validation relies on zod v4 or later and happens at the repository boundary before any SQL runs.
+4. Only validated inputs reach SQL execution; reject raw external objects as soon as possible.
+5. Domain models live under a dedicated src/domain location so semantics stay centralized.
+6. Build the CRUD behavior first and revisit repository interfaces during review, not before the SQL works.
+7. Guard every behavioral change with unit tests so regression risks stay low.
+`;
 function resolveTemplateDirectory() {
     const candidates = [
         // Prefer the installed package layout: <pkg>/dist/commands → <pkg>/templates.
@@ -119,7 +133,21 @@ const DEFAULT_DEPENDENCIES = {
     log: (message) => {
         console.log(message);
     },
-    copyAgentsTemplate: agents_1.copyAgentsTemplate
+    copyAgentsTemplate: agents_1.copyAgentsTemplate,
+    installPackages: ({ rootDir, kind, packages, packageManager }) => {
+        // Use the Windows shim executables so spawnSync finds the package manager in PATH.
+        const executable = resolvePackageManagerExecutable(packageManager);
+        const args = buildPackageManagerArgs(kind, packageManager, packages);
+        if (args.length === 0) {
+            return;
+        }
+        const result = (0, node_child_process_1.spawnSync)(executable, args, { cwd: rootDir, stdio: 'inherit' });
+        if (result.error || result.status !== 0) {
+            const base = `Failed to run ${packageManager} ${args.join(' ')}`;
+            const reason = result.error ? `: ${result.error.message}` : '';
+            throw new Error(`${base}${reason}`);
+        }
+    }
 };
 async function runInitCommand(prompter, options) {
     var _a, _b;
@@ -135,6 +163,7 @@ async function runInitCommand(prompter, options) {
         ztdConfig: node_path_1.default.join(rootDir, ztdProjectConfig_1.DEFAULT_ZTD_CONFIG.testsDir, 'generated', 'ztd-row-map.generated.ts'),
         testsConfig: node_path_1.default.join(rootDir, ztdProjectConfig_1.DEFAULT_ZTD_CONFIG.testsDir, 'generated', 'ztd-layout.generated.ts'),
         readme: node_path_1.default.join(rootDir, 'README.md'),
+        sqlClient: node_path_1.default.join(rootDir, 'src', 'db', 'sql-client.ts'),
         testkitClient: node_path_1.default.join(rootDir, ztdProjectConfig_1.DEFAULT_ZTD_CONFIG.testsDir, 'support', 'testkit-client.ts'),
         globalSetup: node_path_1.default.join(rootDir, ztdProjectConfig_1.DEFAULT_ZTD_CONFIG.testsDir, 'support', 'global-setup.ts'),
         vitestConfig: node_path_1.default.join(rootDir, 'vitest.config.ts'),
@@ -149,6 +178,15 @@ async function runInitCommand(prompter, options) {
     };
     const relativePath = (key) => node_path_1.default.relative(rootDir, absolutePaths[key]).replace(/\\/g, '/') || absolutePaths[key];
     const summaries = {};
+    if (options === null || options === void 0 ? void 0 : options.withAppInterface) {
+        // Provide the documentation-only path before triggering any scaffolding work.
+        const summary = await appendAppInterfaceGuidance(rootDir, dependencies);
+        dependencies.log(`Appended application interface guidance to ${summary.relativePath}.`);
+        return {
+            summary: `App interface guidance appended to ${summary.relativePath}.`,
+            files: [summary]
+        };
+    }
     // Ask how the user prefers to populate the initial schema.
     const workflow = await prompter.selectChoice('How do you want to start your database workflow?', ['Pull schema from Postgres (DDL-first)', 'Write DDL manually']);
     if (workflow === 0) {
@@ -189,7 +227,8 @@ async function runInitCommand(prompter, options) {
             extensions: options_1.DEFAULT_EXTENSIONS,
             out: absolutePaths.ztdConfig,
             defaultSchema: projectConfig.ddl.defaultSchema,
-            searchPath: projectConfig.ddl.searchPath
+            searchPath: projectConfig.ddl.searchPath,
+            ddlLint: projectConfig.ddlLint
         });
     }
     else {
@@ -208,6 +247,12 @@ async function runInitCommand(prompter, options) {
     if (readmeSummary) {
         summaries.readme = readmeSummary;
     }
+    if (options === null || options === void 0 ? void 0 : options.withSqlClient) {
+        const sqlClientSummary = writeOptionalTemplateFile(absolutePaths.sqlClient, relativePath('sqlClient'), SQL_CLIENT_TEMPLATE, dependencies);
+        if (sqlClientSummary) {
+            summaries.sqlClient = sqlClientSummary;
+        }
+    }
     const testkitSummary = await writeTemplateFile(rootDir, absolutePaths.testkitClient, relativePath('testkitClient'), TESTKIT_CLIENT_TEMPLATE, dependencies, prompter);
     if (testkitSummary) {
         summaries.testkitClient = testkitSummary;
@@ -234,6 +279,10 @@ async function runInitCommand(prompter, options) {
     if (ztdDocsReadmeSummary) {
         summaries.ztdDocsReadme = ztdDocsReadmeSummary;
     }
+    const ztdRootDir = node_path_1.default.join(rootDir, 'ztd');
+    // Ensure the domain-specs and enums anchors exist so contributors immediately see where those artifacts belong.
+    dependencies.ensureDirectory(node_path_1.default.join(ztdRootDir, 'domain-specs'));
+    dependencies.ensureDirectory(node_path_1.default.join(ztdRootDir, 'enums'));
     const editorconfigSummary = copyTemplateFileIfMissing(rootDir, relativePath('editorconfig'), '.editorconfig', dependencies);
     if (editorconfigSummary) {
         summaries.editorconfig = editorconfigSummary;
@@ -259,6 +308,7 @@ async function runInitCommand(prompter, options) {
     if (agentsRelative) {
         summaries.agents = agentsRelative;
     }
+    await ensureTemplateDependenciesInstalled(rootDir, absolutePaths, summaries, dependencies);
     const summaryLines = buildSummaryLines(summaries);
     summaryLines.forEach(dependencies.log);
     return {
@@ -267,19 +317,165 @@ async function runInitCommand(prompter, options) {
     };
 }
 async function ensureAgentsFile(rootDir, fallbackRelative, dependencies) {
-    const templateTarget = dependencies.copyAgentsTemplate(rootDir);
-    if (templateTarget) {
-        const relative = node_path_1.default.relative(rootDir, templateTarget).replace(/\\/g, '/');
-        return { relativePath: relative || fallbackRelative, outcome: 'created' };
+    const resolution = resolveOrCreateAgentsFile(rootDir, dependencies);
+    if (!resolution) {
+        return null;
     }
-    const candidates = ['AGENTS.md', 'AGENTS_ztd.md'];
-    for (const candidate of candidates) {
-        const candidatePath = node_path_1.default.join(rootDir, candidate);
-        if (dependencies.fileExists(candidatePath)) {
-            return { relativePath: candidate, outcome: 'unchanged' };
+    const relative = normalizeRelative(rootDir, resolution.absolutePath);
+    return {
+        relativePath: relative || fallbackRelative,
+        outcome: resolution.created ? 'created' : 'unchanged'
+    };
+}
+function resolvePackageManagerExecutable(packageManager) {
+    if (process.platform !== 'win32') {
+        return packageManager;
+    }
+    if (packageManager === 'npm') {
+        return 'npm.cmd';
+    }
+    if (packageManager === 'pnpm') {
+        return 'pnpm.cmd';
+    }
+    if (packageManager === 'yarn') {
+        return 'yarn.cmd';
+    }
+    return packageManager;
+}
+function buildPackageManagerArgs(kind, packageManager, packages) {
+    if (kind === 'install') {
+        return ['install'];
+    }
+    if (packages.length === 0) {
+        return [];
+    }
+    if (packageManager === 'npm') {
+        return ['install', '-D', ...packages];
+    }
+    return ['add', '-D', ...packages];
+}
+function detectPackageManager(rootDir) {
+    // Prefer lockfiles to avoid guessing when multiple package managers are installed.
+    if ((0, node_fs_1.existsSync)(node_path_1.default.join(rootDir, 'pnpm-lock.yaml'))) {
+        return 'pnpm';
+    }
+    if ((0, node_fs_1.existsSync)(node_path_1.default.join(rootDir, 'yarn.lock'))) {
+        return 'yarn';
+    }
+    if ((0, node_fs_1.existsSync)(node_path_1.default.join(rootDir, 'package-lock.json'))) {
+        return 'npm';
+    }
+    // Fall back to pnpm because rawsql-ts itself standardizes on pnpm.
+    return 'pnpm';
+}
+function extractPackageName(specifier) {
+    if (specifier.startsWith('.') ||
+        specifier.startsWith('/') ||
+        specifier.startsWith('node:') ||
+        specifier.startsWith('#')) {
+        return null;
+    }
+    if (specifier.startsWith('@')) {
+        const [scope, name] = specifier.split('/');
+        if (!scope || !name) {
+            return null;
         }
+        return `${scope}/${name}`;
+    }
+    const [name] = specifier.split('/');
+    return name || null;
+}
+function listReferencedPackagesFromSource(source) {
+    const packages = new Set();
+    const patterns = [
+        // Capture ESM imports and re-exports, including `import type`.
+        /\bfrom\s+['"]([^'"]+)['"]/g,
+        // Capture dynamic imports.
+        /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+        // Capture CommonJS requires.
+        /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g
+    ];
+    for (const pattern of patterns) {
+        for (const match of source.matchAll(pattern)) {
+            const specifier = match[1];
+            if (!specifier) {
+                continue;
+            }
+            const packageName = extractPackageName(specifier);
+            if (!packageName) {
+                continue;
+            }
+            packages.add(packageName);
+        }
+    }
+    return [...packages];
+}
+function listDeclaredPackages(rootDir) {
+    const packagePath = node_path_1.default.join(rootDir, 'package.json');
+    if (!(0, node_fs_1.existsSync)(packagePath)) {
+        return new Set();
+    }
+    const parsed = JSON.parse((0, node_fs_1.readFileSync)(packagePath, 'utf8'));
+    const keys = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+    const declared = new Set();
+    for (const key of keys) {
+        const record = parsed[key];
+        if (!record || typeof record !== 'object') {
+            continue;
+        }
+        for (const name of Object.keys(record)) {
+            declared.add(name);
+        }
+    }
+    return declared;
+}
+function listTemplateReferencedPackages(absolutePaths, summaries) {
+    const packages = new Set(['@rawsql-ts/pg-testkit']);
+    const touchedKeys = Object.entries(summaries)
+        .filter((entry) => Boolean(entry[1]))
+        .filter(([, summary]) => summary.outcome === 'created' || summary.outcome === 'overwritten')
+        .map(([key]) => key);
+    for (const key of touchedKeys) {
+        const filePath = absolutePaths[key];
+        if (!filePath.endsWith('.ts') && !filePath.endsWith('.tsx') && !filePath.endsWith('.js')) {
+            continue;
+        }
+        if (!(0, node_fs_1.existsSync)(filePath)) {
+            continue;
+        }
+        // Parse template output after it is written so the detected packages match the emitted scaffold exactly.
+        const contents = (0, node_fs_1.readFileSync)(filePath, 'utf8');
+        listReferencedPackagesFromSource(contents).forEach((name) => packages.add(name));
+    }
+    return [...packages].sort();
+}
+async function ensureTemplateDependenciesInstalled(rootDir, absolutePaths, summaries, dependencies) {
+    var _a;
+    const packageJsonPath = node_path_1.default.join(rootDir, 'package.json');
+    if (!dependencies.fileExists(packageJsonPath)) {
+        dependencies.log('Skipping dependency installation because package.json is missing.');
+        return;
+    }
+    const packageManager = detectPackageManager(rootDir);
+    const referencedPackages = listTemplateReferencedPackages(absolutePaths, summaries);
+    const declaredPackages = listDeclaredPackages(rootDir);
+    // Install only packages that are not declared yet to avoid unintentionally bumping pinned versions.
+    const missingPackages = referencedPackages.filter((name) => !declaredPackages.has(name));
+    if (missingPackages.length > 0) {
+        dependencies.log(`Installing devDependencies referenced by templates (${packageManager}): ${missingPackages.join(', ')}`);
+        await dependencies.installPackages({
+            rootDir,
+            kind: 'devDependencies',
+            packages: missingPackages,
+            packageManager
+        });
+        return;
+    }
+    // If package.json was updated earlier in the init run, run install so the new entries resolve in node_modules.
+    if (((_a = summaries.package) === null || _a === void 0 ? void 0 : _a.outcome) === 'overwritten') {
+        dependencies.log(`Running ${packageManager} install to sync dependencies.`);
+        await dependencies.installPackages({ rootDir, kind: 'install', packages: [], packageManager });
     }
-    return null;
 }
 function copyTemplateFileIfMissing(rootDir, relative, templateName, dependencies) {
     const templatePath = node_path_1.default.join(TEMPLATE_DIRECTORY, templateName);
@@ -297,6 +493,21 @@ function copyTemplateFileIfMissing(rootDir, relative, templateName, dependencies
     dependencies.writeFile(targetPath, (0, node_fs_1.readFileSync)(templatePath, 'utf8'));
     return { relativePath: relative, outcome: 'created' };
 }
+function writeOptionalTemplateFile(absolutePath, relative, templateName, dependencies) {
+    const templatePath = node_path_1.default.join(TEMPLATE_DIRECTORY, templateName);
+    // Skip when the template is missing from the installed package.
+    if (!(0, node_fs_1.existsSync)(templatePath)) {
+        return null;
+    }
+    if (dependencies.fileExists(absolutePath)) {
+        // Preserve existing files for opt-in scaffolds without prompting.
+        dependencies.log(`Skipping ${relative} because the file already exists.`);
+        return { relativePath: relative, outcome: 'unchanged' };
+    }
+    dependencies.ensureDirectory(node_path_1.default.dirname(absolutePath));
+    dependencies.writeFile(absolutePath, (0, node_fs_1.readFileSync)(templatePath, 'utf8'));
+    return { relativePath: relative, outcome: 'created' };
+}
 function ensurePackageJsonFormatting(rootDir, relative, dependencies) {
     var _a, _b;
     const packagePath = node_path_1.default.join(rootDir, 'package.json');
@@ -423,6 +634,37 @@ function normalizeRelative(rootDir, absolutePath) {
     const relative = node_path_1.default.relative(rootDir, absolutePath).replace(/\\/g, '/');
     return relative || absolutePath;
 }
+function resolveOrCreateAgentsFile(rootDir, dependencies) {
+    // Prefer materializing the bundled template before looking for existing attention files.
+    const templateTarget = dependencies.copyAgentsTemplate(rootDir);
+    if (templateTarget) {
+        return { absolutePath: templateTarget, created: true };
+    }
+    for (const candidate of AGENTS_FILE_CANDIDATES) {
+        const candidatePath = node_path_1.default.join(rootDir, candidate);
+        if (dependencies.fileExists(candidatePath)) {
+            return { absolutePath: candidatePath, created: false };
+        }
+    }
+    return null;
+}
+async function appendAppInterfaceGuidance(rootDir, dependencies) {
+    const resolution = resolveOrCreateAgentsFile(rootDir, dependencies);
+    if (!resolution) {
+        throw new Error('Failed to locate or create an AGENTS file for application guidance.');
+    }
+    const relativePath = normalizeRelative(rootDir, resolution.absolutePath);
+    const existingContents = (0, node_fs_1.readFileSync)(resolution.absolutePath, 'utf8');
+    // Skip appending when the guidance section already exists to avoid duplicates.
+    if (existingContents.includes(APP_INTERFACE_SECTION_MARKER)) {
+        return { relativePath, outcome: 'unchanged' };
+    }
+    // Ensure the appended block is separated by blank lines for readability.
+    const baseline = existingContents.endsWith('\n') ? existingContents : `${existingContents}\n`;
+    const spacer = baseline.endsWith('\n\n') ? '' : '\n';
+    dependencies.writeFile(resolution.absolutePath, `${baseline}${spacer}${APP_INTERFACE_SECTION}\n`);
+    return { relativePath, outcome: 'overwritten' };
+}
 function isRootMarkdown(relative) {
     return relative.toLowerCase().endsWith('.md') && !relative.includes('/');
 }
@@ -441,6 +683,7 @@ function buildSummaryLines(summaries) {
         'testsConfig',
         'ztdConfig',
         'readme',
+        'sqlClient',
         'testkitClient',
         'globalSetup',
         'vitestConfig',
@@ -472,10 +715,15 @@ function registerInitCommand(program) {
     program
         .command('init')
         .description('Automate project setup for Zero Table Dependency workflows')
-        .action(async () => {
+        .option('--with-sqlclient', 'Generate a minimal SqlClient interface for repositories')
+        .option('--with-app-interface', 'Append application interface guidance to AGENTS.md only')
+        .action(async (options) => {
         const prompter = createConsolePrompter();
         try {
-            await runInitCommand(prompter);
+            await runInitCommand(prompter, {
+                withSqlClient: options.withSqlclient,
+                withAppInterface: options.withAppInterface
+            });
         }
         finally {
             prompter.close();