@rawsql-ts/ztd-cli 0.16.0 → 0.17.0

package/dist/commands/init.js

@@ -5,6 +5,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createConsolePrompter = createConsolePrompter;
 exports.runInitCommand = runInitCommand;
+exports.normalizeSchemaName = normalizeSchemaName;
+exports.sanitizeSchemaFileName = sanitizeSchemaFileName;
 exports.registerInitCommand = registerInitCommand;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
@@ -15,7 +17,6 @@ const agents_1 = require("../utils/agents");
 const ztdProjectConfig_1 = require("../utils/ztdProjectConfig");
 const ztdConfig_1 = require("./ztdConfig");
 const pull_1 = require("./pull");
-const options_1 = require("./options");
 /**
  * Create a readline-backed prompter that reads from stdin/stdout.
  */
@@ -28,6 +29,11 @@ function createConsolePrompter() {
     async function requestLine(question) {
         return (await rl.question(question)).trim();
     }
+    async function requestLineWithDefault(question, defaultValue, example) {
+        const prompt = `${question}${example ? ` (${example})` : ''} [default: ${defaultValue}]: `;
+        const answer = await requestLine(prompt);
+        return answer.length > 0 ? answer : defaultValue;
+    }
     return {
         async selectChoice(question, choices) {
             while (true) {
@@ -52,6 +58,9 @@ function createConsolePrompter() {
                 console.log('This value cannot be empty.');
             }
         },
+        async promptInputWithDefault(question, defaultValue, example) {
+            return requestLineWithDefault(question, defaultValue, example);
+        },
         async confirm(question) {
             while (true) {
                 const answer = (await requestLine(`${question} (y/N): `)).toLowerCase();
@@ -72,37 +81,64 @@ function createConsolePrompter() {
         }
     };
 }
-const SAMPLE_SCHEMA = `
-CREATE TABLE public.user_account (
-  user_account_id bigserial PRIMARY KEY,
-  username text NOT NULL,
-  email text NOT NULL UNIQUE,
-  display_name text NOT NULL,
-  created_at timestamptz NOT NULL DEFAULT now(),
-  updated_at timestamptz NOT NULL DEFAULT now()
-);
-
-CREATE TABLE public.user_profile (
-  profile_id bigserial PRIMARY KEY,
-  user_account_id bigint NOT NULL REFERENCES public.user_account(user_account_id),
-  bio text,
-  website text,
-  verified boolean NOT NULL DEFAULT false
-);
-`;
+const MANDATORY_TESTKIT_DEPENDENCIES = {
+    '@rawsql-ts/adapter-node-pg': '^0.15.1',
+    '@rawsql-ts/testkit-postgres': '^0.15.1'
+};
+const SQL_CONTRACT_DEPENDENCY = {
+    '@rawsql-ts/sql-contract': '^0.1.0'
+};
+const ZOD_DEPENDENCY = {
+    zod: '^4.3.6'
+};
+const ARKTYPE_DEPENDENCY = {
+    arktype: '^2.1.29'
+};
+async function gatherOptionalFeatures(prompter, _dependencies) {
+    const validatorChoice = await prompter.selectChoice('Runtime DTO validation is required for ZTD tests. Which validator backend should we install?', ['Zod (zod, recommended)', 'ArkType (arktype)']);
+    const validator = validatorChoice === 0 ? 'zod' : 'arktype';
+    return { validator };
+}
 const README_TEMPLATE = 'README.md';
-const TESTS_CONFIG_TEMPLATE = 'tests/ztd-layout.generated.ts';
 const TESTS_AGENTS_TEMPLATE = 'tests/AGENTS.md';
+const TESTS_SUPPORT_AGENTS_TEMPLATE = 'tests/support/AGENTS.md';
+const TESTS_GENERATED_AGENTS_TEMPLATE = 'tests/generated/AGENTS.md';
+const SMOKE_SPEC_ZOD_TEMPLATE = 'src/catalog/specs/_smoke.spec.zod.ts';
+const SMOKE_SPEC_ARKTYPE_TEMPLATE = 'src/catalog/specs/_smoke.spec.arktype.ts';
+const SMOKE_COERCIONS_TEMPLATE = 'src/catalog/runtime/_coercions.ts';
+const SMOKE_RUNTIME_TEMPLATE = 'src/catalog/runtime/_smoke.runtime.ts';
+const SMOKE_VALIDATION_TEST_TEMPLATE = 'tests/smoke.validation.test.ts';
+const TESTS_SMOKE_TEMPLATE = 'tests/smoke.test.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 TSCONFIG_TEMPLATE = 'tsconfig.json';
 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 the testkit-postgres stack'
-];
+const SQL_README_TEMPLATE = 'src/sql/README.md';
+const VIEWS_REPO_README_TEMPLATE = 'src/repositories/views/README.md';
+const TABLES_REPO_README_TEMPLATE = 'src/repositories/tables/README.md';
+const JOBS_README_TEMPLATE = 'src/jobs/README.md';
+const SRC_AGENTS_TEMPLATE = 'src/AGENTS.md';
+const SRC_CATALOG_AGENTS_TEMPLATE = 'src/catalog/AGENTS.md';
+const SRC_CATALOG_RUNTIME_AGENTS_TEMPLATE = 'src/catalog/runtime/AGENTS.md';
+const SRC_CATALOG_SPECS_AGENTS_TEMPLATE = 'src/catalog/specs/AGENTS.md';
+const SRC_SQL_AGENTS_TEMPLATE = 'src/sql/AGENTS.md';
+const SRC_REPOS_AGENTS_TEMPLATE = 'src/repositories/AGENTS.md';
+const VIEWS_REPO_AGENTS_TEMPLATE = 'src/repositories/views/AGENTS.md';
+const TABLES_REPO_AGENTS_TEMPLATE = 'src/repositories/tables/AGENTS.md';
+const JOBS_AGENTS_TEMPLATE = 'src/jobs/AGENTS.md';
+const ZTD_AGENTS_TEMPLATE = 'ztd/AGENTS.md';
+const ZTD_README_TEMPLATE = 'ztd/README.md';
+const ZTD_DDL_AGENTS_TEMPLATE = 'ztd/ddl/AGENTS.md';
+const ZTD_DDL_DEMO_TEMPLATE = 'ztd/ddl/demo.sql';
+const EMPTY_SCHEMA_COMMENT = (schemaName) => [
+    `-- DDL for schema "${schemaName}".`,
+    '-- Add CREATE TABLE statements here.',
+    ''
+].join('\n');
+const DEMO_SCHEMA_TEMPLATE = (_schemaName) => {
+    return loadTemplate(ZTD_DDL_DEMO_TEMPLATE);
+};
 const AGENTS_FILE_CANDIDATES = ['AGENTS.md', 'AGENTS_ztd.md'];
 const APP_INTERFACE_SECTION_MARKER = '## Application Interface Guidance';
 const APP_INTERFACE_SECTION = `---
@@ -197,26 +233,67 @@ const DEFAULT_DEPENDENCIES = {
  * Run the interactive `ztd init` workflow and return the resulting summary.
  */
 async function runInitCommand(prompter, options) {
-    var _a, _b;
+    var _a, _b, _c, _d;
     const rootDir = (_a = options === null || options === void 0 ? void 0 : options.rootDir) !== null && _a !== void 0 ? _a : process.cwd();
     const dependencies = {
         ...DEFAULT_DEPENDENCIES,
         ...((_b = options === null || options === void 0 ? void 0 : options.dependencies) !== null && _b !== void 0 ? _b : {})
     };
-    const schemaFileName = `${ztdProjectConfig_1.DEFAULT_ZTD_CONFIG.ddl.defaultSchema}.sql`;
+    const overwritePolicy = {
+        force: (_c = options === null || options === void 0 ? void 0 : options.forceOverwrite) !== null && _c !== void 0 ? _c : false,
+        nonInteractive: (_d = options === null || options === void 0 ? void 0 : options.nonInteractive) !== null && _d !== void 0 ? _d : false
+    };
+    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 workflowChoice = await prompter.selectChoice('How do you want to start your database workflow?', [
+        'Pull schema from Postgres (pg_dump)',
+        'Create empty scaffold (I will write DDL)',
+        'Create scaffold with demo DDL (no app code)'
+    ]);
+    const workflow = workflowChoice === 0 ? 'pg_dump' : workflowChoice === 1 ? 'empty' : 'demo';
+    const schemaName = normalizeSchemaName(ztdProjectConfig_1.DEFAULT_ZTD_CONFIG.ddl.defaultSchema);
+    const schemaFileName = `${sanitizeSchemaFileName(schemaName)}.sql`;
     const absolutePaths = {
         schema: node_path_1.default.join(rootDir, ztdProjectConfig_1.DEFAULT_ZTD_CONFIG.ddlDir, schemaFileName),
         config: node_path_1.default.join(rootDir, 'ztd.config.json'),
-        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'),
+        smokeSpec: node_path_1.default.join(rootDir, 'src', 'catalog', 'specs', '_smoke.spec.ts'),
+        smokeCoercions: node_path_1.default.join(rootDir, 'src', 'catalog', 'runtime', '_coercions.ts'),
+        smokeRuntime: node_path_1.default.join(rootDir, 'src', 'catalog', 'runtime', '_smoke.runtime.ts'),
+        smokeValidationTest: node_path_1.default.join(rootDir, ztdProjectConfig_1.DEFAULT_ZTD_CONFIG.testsDir, 'smoke.validation.test.ts'),
         testsAgents: node_path_1.default.join(rootDir, ztdProjectConfig_1.DEFAULT_ZTD_CONFIG.testsDir, 'AGENTS.md'),
+        testsSupportAgents: node_path_1.default.join(rootDir, ztdProjectConfig_1.DEFAULT_ZTD_CONFIG.testsDir, 'support', 'AGENTS.md'),
+        testsGeneratedAgents: node_path_1.default.join(rootDir, ztdProjectConfig_1.DEFAULT_ZTD_CONFIG.testsDir, 'generated', 'AGENTS.md'),
+        testsSmoke: node_path_1.default.join(rootDir, ztdProjectConfig_1.DEFAULT_ZTD_CONFIG.testsDir, 'smoke.test.ts'),
         readme: node_path_1.default.join(rootDir, 'README.md'),
+        sqlReadme: node_path_1.default.join(rootDir, 'src', 'sql', 'README.md'),
+        viewsRepoReadme: node_path_1.default.join(rootDir, 'src', 'repositories', 'views', 'README.md'),
+        tablesRepoReadme: node_path_1.default.join(rootDir, 'src', 'repositories', 'tables', 'README.md'),
+        jobsReadme: node_path_1.default.join(rootDir, 'src', 'jobs', 'README.md'),
+        srcAgents: node_path_1.default.join(rootDir, 'src', 'AGENTS.md'),
+        srcCatalogAgents: node_path_1.default.join(rootDir, 'src', 'catalog', 'AGENTS.md'),
+        srcCatalogRuntimeAgents: node_path_1.default.join(rootDir, 'src', 'catalog', 'runtime', 'AGENTS.md'),
+        srcCatalogSpecsAgents: node_path_1.default.join(rootDir, 'src', 'catalog', 'specs', 'AGENTS.md'),
+        srcSqlAgents: node_path_1.default.join(rootDir, 'src', 'sql', 'AGENTS.md'),
+        srcReposAgents: node_path_1.default.join(rootDir, 'src', 'repositories', 'AGENTS.md'),
+        viewsRepoAgents: node_path_1.default.join(rootDir, 'src', 'repositories', 'views', 'AGENTS.md'),
+        tablesRepoAgents: node_path_1.default.join(rootDir, 'src', 'repositories', 'tables', 'AGENTS.md'),
+        jobsAgents: node_path_1.default.join(rootDir, 'src', 'jobs', 'AGENTS.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'),
+        tsconfig: node_path_1.default.join(rootDir, 'tsconfig.json'),
         ztdDocsAgent: node_path_1.default.join(rootDir, 'ztd', 'AGENTS.md'),
         ztdDocsReadme: node_path_1.default.join(rootDir, 'ztd', 'README.md'),
+        ztdDdlAgents: node_path_1.default.join(rootDir, 'ztd', 'ddl', 'AGENTS.md'),
         agents: node_path_1.default.join(rootDir, 'AGENTS.md'),
         gitignore: node_path_1.default.join(rootDir, '.gitignore'),
         editorconfig: node_path_1.default.join(rootDir, '.editorconfig'),
@@ -226,111 +303,170 @@ 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) {
+    if (workflow === 'pg_dump') {
         // Database-first path: pull the schema before writing any DDL files.
         if (!dependencies.checkPgDump()) {
             throw new Error('Unable to find pg_dump. Install Postgres or set PG_DUMP_PATH before running ztd init.');
         }
         const connectionString = await prompter.promptInput('Enter the Postgres connection string for your database', 'postgres://user:pass@host:5432/db');
-        const schemaSummary = await writeFileWithConsent(absolutePaths.schema, relativePath('schema'), dependencies, prompter, async () => {
+        const schemaSummary = await writeFileWithConsent(absolutePaths.schema, relativePath('schema'), dependencies, prompter, overwritePolicy, async () => {
             dependencies.ensureDirectory(node_path_1.default.dirname(absolutePaths.schema));
             await dependencies.runPullSchema({
                 url: connectionString,
-                out: node_path_1.default.dirname(absolutePaths.schema)
+                out: node_path_1.default.dirname(absolutePaths.schema),
+                schemas: [schemaName]
             });
         });
         summaries.schema = schemaSummary;
     }
-    else {
+    else if (workflow === 'empty') {
         // Manual path: seed the DDL directory with a starter schema so ztd-config can run.
-        const schemaSummary = await writeFileWithConsent(absolutePaths.schema, relativePath('schema'), dependencies, prompter, async () => {
+        const schemaSummary = await writeFileWithConsent(absolutePaths.schema, relativePath('schema'), dependencies, prompter, overwritePolicy, async () => {
+            dependencies.ensureDirectory(node_path_1.default.dirname(absolutePaths.schema));
+            dependencies.writeFile(absolutePaths.schema, EMPTY_SCHEMA_COMMENT(schemaName));
+        });
+        summaries.schema = schemaSummary;
+    }
+    else {
+        const schemaSummary = await writeFileWithConsent(absolutePaths.schema, relativePath('schema'), dependencies, prompter, overwritePolicy, async () => {
             dependencies.ensureDirectory(node_path_1.default.dirname(absolutePaths.schema));
-            dependencies.writeFile(absolutePaths.schema, SAMPLE_SCHEMA);
+            dependencies.writeFile(absolutePaths.schema, DEMO_SCHEMA_TEMPLATE(schemaName));
         });
         summaries.schema = schemaSummary;
     }
     // Seed the ztd.config.json defaults so downstream tooling knows where ddl/tests live.
-    const configSummary = await writeFileWithConsent(absolutePaths.config, relativePath('config'), dependencies, prompter, () => {
-        (0, ztdProjectConfig_1.writeZtdProjectConfig)(rootDir);
+    const configSummary = await writeFileWithConsent(absolutePaths.config, relativePath('config'), dependencies, prompter, overwritePolicy, () => {
+        (0, ztdProjectConfig_1.writeZtdProjectConfig)(rootDir, {
+            ddl: {
+                defaultSchema: schemaName,
+                searchPath: [schemaName]
+            }
+        });
     });
     summaries.config = configSummary;
-    const projectConfig = (0, ztdProjectConfig_1.loadZtdProjectConfig)(rootDir);
-    const ztdConfigTarget = await confirmOverwriteIfExists(absolutePaths.ztdConfig, relativePath('ztdConfig'), dependencies, prompter);
-    if (ztdConfigTarget.write) {
-        // Regenerate tests/generated/ztd-row-map.generated.ts so TestRowMap reflects the DDL snapshot.
-        dependencies.ensureDirectory(node_path_1.default.dirname(absolutePaths.ztdConfig));
-        await dependencies.runGenerateZtdConfig({
-            directories: [node_path_1.default.resolve(node_path_1.default.dirname(absolutePaths.schema))],
-            extensions: options_1.DEFAULT_EXTENSIONS,
-            out: absolutePaths.ztdConfig,
-            defaultSchema: projectConfig.ddl.defaultSchema,
-            searchPath: projectConfig.ddl.searchPath,
-            ddlLint: projectConfig.ddlLint
-        });
-    }
-    else {
-        dependencies.log('Skipping ZTD config generation; existing tests/generated/ztd-row-map.generated.ts preserved.');
-    }
-    summaries.ztdConfig = {
-        relativePath: relativePath('ztdConfig'),
-        outcome: ztdConfigTarget.existed
-            ? ztdConfigTarget.write
-                ? 'overwritten'
-                : 'unchanged'
-            : 'created'
-    };
+    const optionalFeatures = await gatherOptionalFeatures(prompter, dependencies);
     // Emit supporting documentation that describes the workflow for contributors.
-    const readmeSummary = await writeTemplateFile(rootDir, absolutePaths.readme, relativePath('readme'), README_TEMPLATE, dependencies, prompter, true);
+    const readmeSummary = await writeTemplateFile(rootDir, absolutePaths.readme, relativePath('readme'), README_TEMPLATE, dependencies, prompter, overwritePolicy, true);
     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 ztdDocsAgentSummary = await writeTemplateFile(rootDir, absolutePaths.ztdDocsAgent, relativePath('ztdDocsAgent'), ZTD_AGENTS_TEMPLATE, dependencies, prompter, overwritePolicy);
+    if (ztdDocsAgentSummary) {
+        summaries.ztdDocsAgent = ztdDocsAgentSummary;
+    }
+    const ztdDocsReadmeSummary = await writeTemplateFile(rootDir, absolutePaths.ztdDocsReadme, relativePath('ztdDocsReadme'), ZTD_README_TEMPLATE, dependencies, prompter, overwritePolicy);
+    if (ztdDocsReadmeSummary) {
+        summaries.ztdDocsReadme = ztdDocsReadmeSummary;
+    }
+    const ztdDdlAgentsSummary = await writeTemplateFile(rootDir, absolutePaths.ztdDdlAgents, relativePath('ztdDdlAgents'), ZTD_DDL_AGENTS_TEMPLATE, dependencies, prompter, overwritePolicy);
+    if (ztdDdlAgentsSummary) {
+        summaries.ztdDdlAgents = ztdDdlAgentsSummary;
+    }
+    const srcAgentsSummary = await writeTemplateFile(rootDir, absolutePaths.srcAgents, relativePath('srcAgents'), SRC_AGENTS_TEMPLATE, dependencies, prompter, overwritePolicy);
+    if (srcAgentsSummary) {
+        summaries.srcAgents = srcAgentsSummary;
+    }
+    const srcCatalogAgentsSummary = await writeTemplateFile(rootDir, absolutePaths.srcCatalogAgents, relativePath('srcCatalogAgents'), SRC_CATALOG_AGENTS_TEMPLATE, dependencies, prompter, overwritePolicy);
+    if (srcCatalogAgentsSummary) {
+        summaries.srcCatalogAgents = srcCatalogAgentsSummary;
+    }
+    const srcCatalogRuntimeAgentsSummary = await writeTemplateFile(rootDir, absolutePaths.srcCatalogRuntimeAgents, relativePath('srcCatalogRuntimeAgents'), SRC_CATALOG_RUNTIME_AGENTS_TEMPLATE, dependencies, prompter, overwritePolicy);
+    if (srcCatalogRuntimeAgentsSummary) {
+        summaries.srcCatalogRuntimeAgents = srcCatalogRuntimeAgentsSummary;
+    }
+    const srcCatalogSpecsAgentsSummary = await writeTemplateFile(rootDir, absolutePaths.srcCatalogSpecsAgents, relativePath('srcCatalogSpecsAgents'), SRC_CATALOG_SPECS_AGENTS_TEMPLATE, dependencies, prompter, overwritePolicy);
+    if (srcCatalogSpecsAgentsSummary) {
+        summaries.srcCatalogSpecsAgents = srcCatalogSpecsAgentsSummary;
+    }
+    const srcSqlAgentsSummary = await writeTemplateFile(rootDir, absolutePaths.srcSqlAgents, relativePath('srcSqlAgents'), SRC_SQL_AGENTS_TEMPLATE, dependencies, prompter, overwritePolicy);
+    if (srcSqlAgentsSummary) {
+        summaries.srcSqlAgents = srcSqlAgentsSummary;
+    }
+    const srcReposAgentsSummary = await writeTemplateFile(rootDir, absolutePaths.srcReposAgents, relativePath('srcReposAgents'), SRC_REPOS_AGENTS_TEMPLATE, dependencies, prompter, overwritePolicy);
+    if (srcReposAgentsSummary) {
+        summaries.srcReposAgents = srcReposAgentsSummary;
+    }
+    const viewsRepoAgentsSummary = await writeTemplateFile(rootDir, absolutePaths.viewsRepoAgents, relativePath('viewsRepoAgents'), VIEWS_REPO_AGENTS_TEMPLATE, dependencies, prompter, overwritePolicy);
+    if (viewsRepoAgentsSummary) {
+        summaries.viewsRepoAgents = viewsRepoAgentsSummary;
+    }
+    const tablesRepoAgentsSummary = await writeTemplateFile(rootDir, absolutePaths.tablesRepoAgents, relativePath('tablesRepoAgents'), TABLES_REPO_AGENTS_TEMPLATE, dependencies, prompter, overwritePolicy);
+    if (tablesRepoAgentsSummary) {
+        summaries.tablesRepoAgents = tablesRepoAgentsSummary;
+    }
+    const jobsAgentsSummary = await writeTemplateFile(rootDir, absolutePaths.jobsAgents, relativePath('jobsAgents'), JOBS_AGENTS_TEMPLATE, dependencies, prompter, overwritePolicy);
+    if (jobsAgentsSummary) {
+        summaries.jobsAgents = jobsAgentsSummary;
+    }
+    const sqlReadmeSummary = await writeTemplateFile(rootDir, absolutePaths.sqlReadme, relativePath('sqlReadme'), SQL_README_TEMPLATE, dependencies, prompter, overwritePolicy);
+    if (sqlReadmeSummary) {
+        summaries.sqlReadme = sqlReadmeSummary;
+    }
+    const viewsRepoReadmeSummary = await writeTemplateFile(rootDir, absolutePaths.viewsRepoReadme, relativePath('viewsRepoReadme'), VIEWS_REPO_README_TEMPLATE, dependencies, prompter, overwritePolicy);
+    if (viewsRepoReadmeSummary) {
+        summaries.viewsRepoReadme = viewsRepoReadmeSummary;
+    }
+    const tablesRepoReadmeSummary = await writeTemplateFile(rootDir, absolutePaths.tablesRepoReadme, relativePath('tablesRepoReadme'), TABLES_REPO_README_TEMPLATE, dependencies, prompter, overwritePolicy);
+    if (tablesRepoReadmeSummary) {
+        summaries.tablesRepoReadme = tablesRepoReadmeSummary;
     }
-    const testkitSummary = await writeTemplateFile(rootDir, absolutePaths.testkitClient, relativePath('testkitClient'), TESTKIT_CLIENT_TEMPLATE, dependencies, prompter);
+    const jobsReadmeSummary = await writeTemplateFile(rootDir, absolutePaths.jobsReadme, relativePath('jobsReadme'), JOBS_README_TEMPLATE, dependencies, prompter, overwritePolicy);
+    if (jobsReadmeSummary) {
+        summaries.jobsReadme = jobsReadmeSummary;
+    }
+    const smokeSpecTemplate = optionalFeatures.validator === 'zod' ? SMOKE_SPEC_ZOD_TEMPLATE : SMOKE_SPEC_ARKTYPE_TEMPLATE;
+    const smokeSpecSummary = await writeTemplateFile(rootDir, absolutePaths.smokeSpec, relativePath('smokeSpec'), smokeSpecTemplate, dependencies, prompter, overwritePolicy);
+    if (smokeSpecSummary) {
+        summaries.smokeSpec = smokeSpecSummary;
+    }
+    const smokeCoercionsSummary = await writeTemplateFile(rootDir, absolutePaths.smokeCoercions, relativePath('smokeCoercions'), SMOKE_COERCIONS_TEMPLATE, dependencies, prompter, overwritePolicy);
+    if (smokeCoercionsSummary) {
+        summaries.smokeCoercions = smokeCoercionsSummary;
+    }
+    const smokeRuntimeSummary = await writeTemplateFile(rootDir, absolutePaths.smokeRuntime, relativePath('smokeRuntime'), SMOKE_RUNTIME_TEMPLATE, dependencies, prompter, overwritePolicy);
+    if (smokeRuntimeSummary) {
+        summaries.smokeRuntime = smokeRuntimeSummary;
+    }
+    const smokeValidationTestSummary = await writeTemplateFile(rootDir, absolutePaths.smokeValidationTest, relativePath('smokeValidationTest'), SMOKE_VALIDATION_TEST_TEMPLATE, dependencies, prompter, overwritePolicy);
+    if (smokeValidationTestSummary) {
+        summaries.smokeValidationTest = smokeValidationTestSummary;
+    }
+    const sqlClientSummary = writeOptionalTemplateFile(absolutePaths.sqlClient, relativePath('sqlClient'), SQL_CLIENT_TEMPLATE, dependencies);
+    if (sqlClientSummary) {
+        summaries.sqlClient = sqlClientSummary;
+    }
+    const testsAgentsSummary = await writeTemplateFile(rootDir, absolutePaths.testsAgents, relativePath('testsAgents'), TESTS_AGENTS_TEMPLATE, dependencies, prompter, overwritePolicy);
+    if (testsAgentsSummary) {
+        summaries.testsAgents = testsAgentsSummary;
+    }
+    const testsSupportAgentsSummary = await writeTemplateFile(rootDir, absolutePaths.testsSupportAgents, relativePath('testsSupportAgents'), TESTS_SUPPORT_AGENTS_TEMPLATE, dependencies, prompter, overwritePolicy);
+    if (testsSupportAgentsSummary) {
+        summaries.testsSupportAgents = testsSupportAgentsSummary;
+    }
+    const testsGeneratedAgentsSummary = await writeTemplateFile(rootDir, absolutePaths.testsGeneratedAgents, relativePath('testsGeneratedAgents'), TESTS_GENERATED_AGENTS_TEMPLATE, dependencies, prompter, overwritePolicy);
+    if (testsGeneratedAgentsSummary) {
+        summaries.testsGeneratedAgents = testsGeneratedAgentsSummary;
+    }
+    const testsSmokeSummary = await writeTemplateFile(rootDir, absolutePaths.testsSmoke, relativePath('testsSmoke'), TESTS_SMOKE_TEMPLATE, dependencies, prompter, overwritePolicy);
+    if (testsSmokeSummary) {
+        summaries.testsSmoke = testsSmokeSummary;
+    }
+    const testkitSummary = await writeTemplateFile(rootDir, absolutePaths.testkitClient, relativePath('testkitClient'), TESTKIT_CLIENT_TEMPLATE, dependencies, prompter, overwritePolicy);
     if (testkitSummary) {
         summaries.testkitClient = testkitSummary;
     }
-    const globalSetupSummary = await writeTemplateFile(rootDir, absolutePaths.globalSetup, relativePath('globalSetup'), GLOBAL_SETUP_TEMPLATE, dependencies, prompter);
+    const globalSetupSummary = await writeTemplateFile(rootDir, absolutePaths.globalSetup, relativePath('globalSetup'), GLOBAL_SETUP_TEMPLATE, dependencies, prompter, overwritePolicy);
     if (globalSetupSummary) {
         summaries.globalSetup = globalSetupSummary;
     }
-    const vitestConfigSummary = await writeTemplateFile(rootDir, absolutePaths.vitestConfig, relativePath('vitestConfig'), VITEST_CONFIG_TEMPLATE, dependencies, prompter);
+    const vitestConfigSummary = await writeTemplateFile(rootDir, absolutePaths.vitestConfig, relativePath('vitestConfig'), VITEST_CONFIG_TEMPLATE, dependencies, prompter, overwritePolicy);
     if (vitestConfigSummary) {
         summaries.vitestConfig = vitestConfigSummary;
     }
-    const testsConfigSummary = await writeTemplateFile(rootDir, absolutePaths.testsConfig, relativePath('testsConfig'), TESTS_CONFIG_TEMPLATE, dependencies, prompter);
-    if (testsConfigSummary) {
-        summaries.testsConfig = testsConfigSummary;
-    }
-    // Ensure the generated tests guidance lands beside the generated layout config.
-    const testsAgentsSummary = await writeTemplateFile(rootDir, absolutePaths.testsAgents, relativePath('testsAgents'), TESTS_AGENTS_TEMPLATE, dependencies, prompter);
-    if (testsAgentsSummary) {
-        summaries.testsAgents = testsAgentsSummary;
-    }
-    // Seed the shared guidance that lives inside the ztd/ directory so contributors see the new instructions.
-    const ztdDocsAgentSummary = await writeTemplateFile(rootDir, absolutePaths.ztdDocsAgent, relativePath('ztdDocsAgent'), 'ztd/AGENTS.md', dependencies, prompter);
-    if (ztdDocsAgentSummary) {
-        summaries.ztdDocsAgent = ztdDocsAgentSummary;
-    }
-    // Provide the companion README inside ztd/ so maintainers understand the schema expectations and doc layout.
-    const ztdDocsReadmeSummary = await writeTemplateFile(rootDir, absolutePaths.ztdDocsReadme, relativePath('ztdDocsReadme'), 'ztd/README.md', dependencies, prompter);
-    if (ztdDocsReadmeSummary) {
-        summaries.ztdDocsReadme = ztdDocsReadmeSummary;
+    const tsconfigSummary = await writeTemplateFile(rootDir, absolutePaths.tsconfig, relativePath('tsconfig'), TSCONFIG_TEMPLATE, dependencies, prompter, overwritePolicy);
+    if (tsconfigSummary) {
+        summaries.tsconfig = tsconfigSummary;
     }
     const editorconfigSummary = copyTemplateFileIfMissing(rootDir, relativePath('editorconfig'), '.editorconfig', dependencies);
     if (editorconfigSummary) {
@@ -348,7 +484,7 @@ async function runInitCommand(prompter, options) {
     if (prettierignoreSummary) {
         summaries.prettierignore = prettierignoreSummary;
     }
-    const packageSummary = ensurePackageJsonFormatting(rootDir, relativePath('package'), dependencies);
+    const packageSummary = ensurePackageJsonFormatting(rootDir, relativePath('package'), dependencies, optionalFeatures);
     if (packageSummary) {
         summaries.package = packageSummary;
     }
@@ -358,7 +494,8 @@ async function runInitCommand(prompter, options) {
         summaries.agents = agentsRelative;
     }
     await ensureTemplateDependenciesInstalled(rootDir, absolutePaths, summaries, dependencies);
-    const summaryLines = buildSummaryLines(summaries);
+    const nextSteps = buildNextSteps(normalizeRelative(rootDir, absolutePaths.schema), workflow);
+    const summaryLines = buildSummaryLines(summaries, optionalFeatures, nextSteps);
     summaryLines.forEach(dependencies.log);
     return {
         summary: summaryLines.join('\n'),
@@ -534,7 +671,7 @@ function listDeclaredPackages(rootDir) {
     return declared;
 }
 function listTemplateReferencedPackages(absolutePaths, summaries) {
-    const packages = new Set(['@rawsql-ts/testkit-postgres', '@rawsql-ts/adapter-node-pg']);
+    const packages = new Set();
     const touchedKeys = Object.entries(summaries)
         .filter((entry) => Boolean(entry[1]))
         .filter(([, summary]) => summary.outcome === 'created' || summary.outcome === 'overwritten')
@@ -557,7 +694,7 @@ async function ensureTemplateDependenciesInstalled(rootDir, absolutePaths, summa
     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.');
+        dependencies.log('Skipping dependency installation because package.json is missing. Next: run pnpm init (or npm init), install dependencies, then run npx ztd ztd-config.');
         return;
     }
     const packageManager = detectPackageManager(rootDir);
@@ -612,18 +749,22 @@ function writeOptionalTemplateFile(absolutePath, relative, templateName, depende
     dependencies.writeFile(absolutePath, (0, node_fs_1.readFileSync)(templatePath, 'utf8'));
     return { relativePath: relative, outcome: 'created' };
 }
-function ensurePackageJsonFormatting(rootDir, relative, dependencies) {
+function ensurePackageJsonFormatting(rootDir, relative, dependencies, optionalFeatures) {
     var _a, _b;
     const packagePath = node_path_1.default.join(rootDir, 'package.json');
-    // Skip wiring defaults when the project does not yet have a package manifest.
-    if (!dependencies.fileExists(packagePath)) {
-        return null;
-    }
-    const document = (0, node_fs_1.readFileSync)(packagePath, 'utf8');
-    const parsed = JSON.parse(document);
+    const packageExists = dependencies.fileExists(packagePath);
+    const parsed = packageExists
+        ? JSON.parse((0, node_fs_1.readFileSync)(packagePath, 'utf8'))
+        : {
+            name: inferPackageName(rootDir),
+            version: '0.0.0',
+            private: true
+        };
     let changed = false;
     const scripts = (_a = parsed.scripts) !== null && _a !== void 0 ? _a : {};
     const requiredScripts = {
+        test: 'vitest run',
+        typecheck: 'tsc --noEmit',
         format: 'prettier . --write',
         lint: 'eslint .',
         'lint:fix': 'eslint . --fix'
@@ -661,6 +802,11 @@ function ensurePackageJsonFormatting(rootDir, relative, dependencies) {
         'prettier-plugin-sql': '^0.19.2',
         'simple-git-hooks': '^2.13.1'
     };
+    const testingDeps = {
+        vitest: '^4.0.7',
+        typescript: '^5.8.2',
+        '@types/node': '^22.13.10'
+    };
     // Add the formatting toolchain dependencies that back the scripts and hooks.
     for (const [dep, version] of Object.entries(formattingDeps)) {
         if (dep in devDependencies) {
@@ -669,6 +815,31 @@ function ensurePackageJsonFormatting(rootDir, relative, dependencies) {
         devDependencies[dep] = version;
         changed = true;
     }
+    const stackDependencies = {
+        ...MANDATORY_TESTKIT_DEPENDENCIES,
+        ...SQL_CONTRACT_DEPENDENCY
+    };
+    if (optionalFeatures.validator === 'zod') {
+        Object.assign(stackDependencies, ZOD_DEPENDENCY);
+    }
+    else {
+        Object.assign(stackDependencies, ARKTYPE_DEPENDENCY);
+    }
+    // Ensure test and typecheck toolchain dependencies are present for a runnable scaffold.
+    for (const [dep, version] of Object.entries(testingDeps)) {
+        if (dep in devDependencies) {
+            continue;
+        }
+        devDependencies[dep] = version;
+        changed = true;
+    }
+    for (const [dep, version] of Object.entries(stackDependencies)) {
+        if (dep in devDependencies) {
+            continue;
+        }
+        devDependencies[dep] = version;
+        changed = true;
+    }
     if (!changed) {
         return null;
     }
@@ -676,42 +847,56 @@ function ensurePackageJsonFormatting(rootDir, relative, dependencies) {
     dependencies.ensureDirectory(node_path_1.default.dirname(packagePath));
     // Persist the updated manifest so the new scripts and tools are available immediately.
     dependencies.writeFile(packagePath, `${JSON.stringify(parsed, null, 2)}\n`);
-    return { relativePath: relative, outcome: 'overwritten' };
+    return { relativePath: relative, outcome: packageExists ? 'overwritten' : 'created' };
+}
+function inferPackageName(rootDir) {
+    const baseName = node_path_1.default.basename(rootDir).toLowerCase();
+    const normalized = baseName.replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+    if (normalized.length > 0) {
+        return normalized;
+    }
+    return 'ztd-project';
 }
-async function writeFileWithConsent(absolutePath, relative, dependencies, prompter, writer) {
-    const { existed, write } = await confirmOverwriteIfExists(absolutePath, relative, dependencies, prompter);
+async function writeFileWithConsent(absolutePath, relative, dependencies, prompter, overwritePolicy, writer) {
+    const { existed, write } = await confirmOverwriteIfExists(absolutePath, relative, dependencies, prompter, overwritePolicy);
     if (!write) {
         return { relativePath: relative, outcome: 'unchanged' };
     }
     await writer();
     return { relativePath: relative, outcome: existed ? 'overwritten' : 'created' };
 }
-async function confirmOverwriteIfExists(absolutePath, relative, dependencies, prompter) {
+async function confirmOverwriteIfExists(absolutePath, relative, dependencies, prompter, overwritePolicy) {
     const existed = dependencies.fileExists(absolutePath);
     if (!existed) {
         return { existed: false, write: true };
     }
+    if (overwritePolicy.force) {
+        return { existed: true, write: true };
+    }
+    if (overwritePolicy.nonInteractive) {
+        throw new Error(`File ${relative} already exists. Re-run with --yes to overwrite or remove the file before running ztd init.`);
+    }
     const overwrite = await prompter.confirm(`File ${relative} already exists. Overwrite?`);
     if (!overwrite) {
         return { existed: true, write: false };
     }
     return { existed: true, write: true };
 }
-async function writeDocFile(absolutePath, relative, contents, dependencies, prompter) {
-    const summary = await writeFileWithConsent(absolutePath, relative, dependencies, prompter, () => {
+async function writeDocFile(absolutePath, relative, contents, dependencies, prompter, overwritePolicy) {
+    const summary = await writeFileWithConsent(absolutePath, relative, dependencies, prompter, overwritePolicy, () => {
         dependencies.ensureDirectory(node_path_1.default.dirname(absolutePath));
         dependencies.writeFile(absolutePath, contents);
     });
     return summary;
 }
-async function writeTemplateFile(rootDir, absolutePath, relative, templateName, dependencies, prompter, allowFallback) {
+async function writeTemplateFile(rootDir, absolutePath, relative, templateName, dependencies, prompter, overwritePolicy, allowFallback) {
     const templateTarget = resolveTemplateTarget(rootDir, absolutePath, relative, dependencies, allowFallback);
     if (!templateTarget) {
         return null;
     }
     // Load shared documentation templates so every new project gets the same guidance.
     const contents = loadTemplate(templateName);
-    return writeDocFile(templateTarget.absolutePath, templateTarget.relativePath, contents, dependencies, prompter);
+    return writeDocFile(templateTarget.absolutePath, templateTarget.relativePath, contents, dependencies, prompter, overwritePolicy);
 }
 function resolveTemplateTarget(rootDir, absolutePath, relative, dependencies, allowFallback) {
     if (!dependencies.fileExists(absolutePath)) {
@@ -738,6 +923,25 @@ function normalizeRelative(rootDir, absolutePath) {
     const relative = node_path_1.default.relative(rootDir, absolutePath).replace(/\\/g, '/');
     return relative || absolutePath;
 }
+/**
+ * Normalizes a schema identifier into the canonical lowercase form used by ztd-cli file naming.
+ * Empty input falls back to the configured default schema.
+ */
+function normalizeSchemaName(value) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return ztdProjectConfig_1.DEFAULT_ZTD_CONFIG.ddl.defaultSchema;
+    }
+    return trimmed.replace(/^"|"$/g, '').toLowerCase();
+}
+/**
+ * Sanitizes a normalized schema identifier so it can be used as a filesystem-safe file stem.
+ * Returns `schema` when all characters are stripped by sanitization.
+ */
+function sanitizeSchemaFileName(schemaName) {
+    const sanitized = schemaName.replace(/[^a-z0-9_-]/g, '_').replace(/^_+|_+$/g, '');
+    return sanitized || 'schema';
+}
 function resolveOrCreateAgentsFile(rootDir, dependencies) {
     // Prefer materializing the bundled template before looking for existing attention files.
     const templateTarget = dependencies.copyAgentsTemplate(rootDir);
@@ -780,20 +984,51 @@ function loadTemplate(templateName) {
     }
     return (0, node_fs_1.readFileSync)(templatePath, 'utf8');
 }
-function buildSummaryLines(summaries) {
+function buildNextSteps(schemaRelativePath, workflow) {
+    const stepOne = workflow === 'pg_dump'
+        ? ` 1. Review the dumped DDL in ${schemaRelativePath}`
+        : ` 1. If the schema file is empty, edit ${schemaRelativePath}`;
+    return [
+        stepOne,
+        ' 2. Run npx ztd ztd-config',
+        ' 3. Provide a SqlClient implementation (adapter or mock)',
+        ' 4. Run tests (pnpm test or npx vitest run)'
+    ];
+}
+function buildSummaryLines(summaries, optionalFeatures, nextSteps) {
     const orderedKeys = [
         'schema',
         'config',
-        'testsConfig',
-        'testsAgents',
-        'ztdConfig',
         'readme',
+        'ztdDocsAgent',
+        'ztdDocsReadme',
+        'ztdDdlAgents',
+        'srcAgents',
+        'srcCatalogAgents',
+        'srcCatalogRuntimeAgents',
+        'srcCatalogSpecsAgents',
+        'srcSqlAgents',
+        'srcReposAgents',
+        'viewsRepoAgents',
+        'tablesRepoAgents',
+        'jobsAgents',
+        'sqlReadme',
+        'viewsRepoReadme',
+        'tablesRepoReadme',
+        'jobsReadme',
+        'smokeSpec',
+        'smokeCoercions',
+        'smokeRuntime',
+        'smokeValidationTest',
+        'testsAgents',
+        'testsSupportAgents',
+        'testsGeneratedAgents',
+        'testsSmoke',
         'sqlClient',
         'testkitClient',
         'globalSetup',
         'vitestConfig',
-        'ztdDocsAgent',
-        'ztdDocsReadme',
+        'tsconfig',
         'agents',
         'gitignore',
         'editorconfig',
@@ -813,7 +1048,13 @@ function buildSummaryLines(summaries) {
             lines.push(` - ${summary.relativePath}${note}`);
         }
     }
-    lines.push('', 'Next steps:', ...NEXT_STEPS);
+    lines.push('', 'Validation configuration:');
+    lines.push(' - SQL catalog/mapping support via @rawsql-ts/sql-contract (see docs/recipes/sql-contract.md)');
+    const validatorLabel = optionalFeatures.validator === 'zod'
+        ? 'Zod (zod, docs/recipes/validation-zod.md)'
+        : 'ArkType (arktype, docs/recipes/validation-arktype.md)';
+    lines.push(` - Validator backend: ${validatorLabel}`);
+    lines.push('', 'Next steps:', ...nextSteps);
     return lines;
 }
 function registerInitCommand(program) {
@@ -822,12 +1063,16 @@ function registerInitCommand(program) {
         .description('Automate project setup for Zero Table Dependency workflows')
         .option('--with-sqlclient', 'Generate a minimal SqlClient interface for repositories')
         .option('--with-app-interface', 'Append application interface guidance to AGENTS.md only')
+        .option('--yes', 'Overwrite existing scaffold files without prompting')
         .action(async (options) => {
+        var _a;
         const prompter = createConsolePrompter();
         try {
             await runInitCommand(prompter, {
                 withSqlClient: options.withSqlclient,
-                withAppInterface: options.withAppInterface
+                withAppInterface: options.withAppInterface,
+                forceOverwrite: (_a = options.yes) !== null && _a !== void 0 ? _a : false,
+                nonInteractive: !process.stdin.isTTY
             });
         }
         finally {