@rawsql-ts/ztd-cli 0.20.0 → 0.20.3

package/dist/commands/init.js

@@ -0,0 +1,1508 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createConsolePrompter = createConsolePrompter;
+exports.runInitCommand = runInitCommand;
+exports.resolvePackageManagerShellExecutable = resolvePackageManagerShellExecutable;
+exports.findAncestorPnpmWorkspaceRoot = findAncestorPnpmWorkspaceRoot;
+exports.resolvePnpmWorkspaceGuard = resolvePnpmWorkspaceGuard;
+exports.resolveInitInstallStrategy = resolveInitInstallStrategy;
+exports.buildPackageManagerArgs = buildPackageManagerArgs;
+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");
+const node_path_1 = __importDefault(require("node:path"));
+const promises_1 = __importDefault(require("node:readline/promises"));
+const fs_1 = require("../utils/fs");
+const agents_1 = require("../utils/agents");
+const ztdProjectConfig_1 = require("../utils/ztdProjectConfig");
+const ztdConfig_1 = require("./ztdConfig");
+const pull_1 = require("./pull");
+const agentCli_1 = require("../utils/agentCli");
+const agentSafety_1 = require("../utils/agentSafety");
+/**
+ * Create a readline-backed prompter that reads from stdin/stdout.
+ */
+function createConsolePrompter() {
+    const rl = promises_1.default.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        terminal: process.stdout.isTTY
+    });
+    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) {
+                console.log(question);
+                for (let i = 0; i < choices.length; i += 1) {
+                    console.log(`  ${i + 1}. ${choices[i]}`);
+                }
+                const answer = await requestLine('Select an option: ');
+                const selected = Number(answer);
+                if (Number.isFinite(selected) && selected >= 1 && selected <= choices.length) {
+                    return selected - 1;
+                }
+                console.log('Please choose a valid option number.');
+            }
+        },
+        async promptInput(question, example) {
+            while (true) {
+                const answer = await requestLine(`${question}${example ? ` (${example})` : ''}: `);
+                if (answer.length > 0) {
+                    return answer;
+                }
+                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();
+                if (answer === '') {
+                    return false;
+                }
+                if (answer === 'y' || answer === 'yes') {
+                    return true;
+                }
+                if (answer === 'n' || answer === 'no') {
+                    return false;
+                }
+                console.log('Please respond with y(es) or n(o).');
+            }
+        },
+        close() {
+            rl.close();
+        }
+    };
+}
+const STACK_DEV_DEPENDENCIES = {
+    '@rawsql-ts/sql-contract': '0.2.0',
+    '@rawsql-ts/ztd-cli': '0.17.0'
+};
+const LOCAL_SOURCE_STACK_PACKAGE_DIRS = {
+    '@rawsql-ts/sql-contract': node_path_1.default.join('packages', 'sql-contract')
+};
+const ZOD_DEPENDENCY = {
+    zod: '^4.3.6'
+};
+const ARKTYPE_DEPENDENCY = {
+    arktype: '2.2.0'
+};
+async function gatherOptionalFeatures(prompter, _dependencies, validatorOverride, aiGuidanceOverride) {
+    if (validatorOverride) {
+        return {
+            validator: validatorOverride,
+            aiGuidance: aiGuidanceOverride !== null && aiGuidanceOverride !== void 0 ? aiGuidanceOverride : false
+        };
+    }
+    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,
+        aiGuidance: aiGuidanceOverride !== null && aiGuidanceOverride !== void 0 ? aiGuidanceOverride : false
+    };
+}
+const README_TEMPLATE = 'README.md';
+const README_WEBAPI_TEMPLATE = 'README.webapi.md';
+const CONTEXT_TEMPLATE = 'CONTEXT.md';
+const CONTEXT_WEBAPI_TEMPLATE = 'CONTEXT.webapi.md';
+const PROMPT_DOGFOOD_WEBAPI_TEMPLATE = 'PROMPT_DOGFOOD.webapi.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 LOCAL_SOURCE_GUARD_TEMPLATE = 'scripts/local-source-guard.mjs';
+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 TESTKIT_CLIENT_WEBAPI_TEMPLATE = 'tests/support/testkit-client.webapi.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 SQL_CLIENT_ADAPTERS_TEMPLATE = 'src/db/sql-client-adapters.ts';
+const SQL_CLIENT_WEBAPI_TEMPLATE = 'src/infrastructure/db/sql-client.ts';
+const SQL_CLIENT_ADAPTERS_WEBAPI_TEMPLATE = 'src/infrastructure/db/sql-client-adapters.ts';
+const REPOSITORY_TELEMETRY_TYPES_TEMPLATE = 'src/infrastructure/telemetry/types.ts';
+const REPOSITORY_TELEMETRY_CONSOLE_TEMPLATE = 'src/infrastructure/telemetry/consoleRepositoryTelemetry.ts';
+const REPOSITORY_TELEMETRY_ENTRY_TEMPLATE = 'src/infrastructure/telemetry/repositoryTelemetry.ts';
+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 WEBAPI_DOMAIN_README_TEMPLATE = 'src/domain/README.md';
+const WEBAPI_APPLICATION_README_TEMPLATE = 'src/application/README.md';
+const WEBAPI_PRESENTATION_HTTP_README_TEMPLATE = 'src/presentation/http/README.md';
+const WEBAPI_INFRASTRUCTURE_README_TEMPLATE = 'src/infrastructure/README.md';
+const WEBAPI_PERSISTENCE_README_TEMPLATE = 'src/infrastructure/persistence/README.md';
+const WEBAPI_VIEWS_REPO_README_TEMPLATE = 'src/infrastructure/persistence/repositories/views/README.md';
+const WEBAPI_TABLES_REPO_README_TEMPLATE = 'src/infrastructure/persistence/repositories/tables/README.md';
+const JOBS_README_TEMPLATE = 'src/jobs/README.md';
+const ZTD_README_TEMPLATE = 'ztd/README.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);
+};
+function resolveInitScaffoldLayout(rootDir, appShape) {
+    if (appShape === 'webapi') {
+        return {
+            appShape,
+            readmeTemplate: README_WEBAPI_TEMPLATE,
+            contextTemplate: CONTEXT_WEBAPI_TEMPLATE,
+            promptDogfoodPath: node_path_1.default.join(rootDir, 'PROMPT_DOGFOOD.md'),
+            promptDogfoodTemplate: PROMPT_DOGFOOD_WEBAPI_TEMPLATE,
+            sqlClientTemplate: SQL_CLIENT_WEBAPI_TEMPLATE,
+            sqlClientAdaptersTemplate: SQL_CLIENT_ADAPTERS_WEBAPI_TEMPLATE,
+            testkitClientTemplate: TESTKIT_CLIENT_WEBAPI_TEMPLATE,
+            viewsRepoReadmeTemplate: WEBAPI_VIEWS_REPO_README_TEMPLATE,
+            tablesRepoReadmeTemplate: WEBAPI_TABLES_REPO_README_TEMPLATE,
+            viewsRepoReadmePath: node_path_1.default.join(rootDir, 'src', 'infrastructure', 'persistence', 'repositories', 'views', 'README.md'),
+            tablesRepoReadmePath: node_path_1.default.join(rootDir, 'src', 'infrastructure', 'persistence', 'repositories', 'tables', 'README.md'),
+            jobsReadmePath: null,
+            jobsReadmeTemplate: null,
+            domainReadmePath: node_path_1.default.join(rootDir, 'src', 'domain', 'README.md'),
+            domainReadmeTemplate: WEBAPI_DOMAIN_README_TEMPLATE,
+            applicationReadmePath: node_path_1.default.join(rootDir, 'src', 'application', 'README.md'),
+            applicationReadmeTemplate: WEBAPI_APPLICATION_README_TEMPLATE,
+            presentationHttpReadmePath: node_path_1.default.join(rootDir, 'src', 'presentation', 'http', 'README.md'),
+            presentationHttpReadmeTemplate: WEBAPI_PRESENTATION_HTTP_README_TEMPLATE,
+            infrastructureReadmePath: node_path_1.default.join(rootDir, 'src', 'infrastructure', 'README.md'),
+            infrastructureReadmeTemplate: WEBAPI_INFRASTRUCTURE_README_TEMPLATE,
+            persistenceReadmePath: node_path_1.default.join(rootDir, 'src', 'infrastructure', 'persistence', 'README.md'),
+            persistenceReadmeTemplate: WEBAPI_PERSISTENCE_README_TEMPLATE,
+            sqlClientPath: node_path_1.default.join(rootDir, 'src', 'infrastructure', 'db', 'sql-client.ts'),
+            sqlClientAdaptersPath: node_path_1.default.join(rootDir, 'src', 'infrastructure', 'db', 'sql-client-adapters.ts')
+        };
+    }
+    return {
+        appShape,
+        readmeTemplate: README_TEMPLATE,
+        contextTemplate: CONTEXT_TEMPLATE,
+        promptDogfoodPath: null,
+        promptDogfoodTemplate: null,
+        sqlClientTemplate: SQL_CLIENT_TEMPLATE,
+        sqlClientAdaptersTemplate: SQL_CLIENT_ADAPTERS_TEMPLATE,
+        testkitClientTemplate: TESTKIT_CLIENT_TEMPLATE,
+        viewsRepoReadmeTemplate: VIEWS_REPO_README_TEMPLATE,
+        tablesRepoReadmeTemplate: TABLES_REPO_README_TEMPLATE,
+        viewsRepoReadmePath: node_path_1.default.join(rootDir, 'src', 'repositories', 'views', 'README.md'),
+        tablesRepoReadmePath: node_path_1.default.join(rootDir, 'src', 'repositories', 'tables', 'README.md'),
+        jobsReadmePath: node_path_1.default.join(rootDir, 'src', 'jobs', 'README.md'),
+        jobsReadmeTemplate: JOBS_README_TEMPLATE,
+        domainReadmePath: null,
+        domainReadmeTemplate: null,
+        applicationReadmePath: null,
+        applicationReadmeTemplate: null,
+        presentationHttpReadmePath: null,
+        presentationHttpReadmeTemplate: null,
+        infrastructureReadmePath: null,
+        infrastructureReadmeTemplate: null,
+        persistenceReadmePath: null,
+        persistenceReadmeTemplate: null,
+        sqlClientPath: node_path_1.default.join(rootDir, 'src', 'db', 'sql-client.ts'),
+        sqlClientAdaptersPath: node_path_1.default.join(rootDir, 'src', 'db', 'sql-client-adapters.ts')
+    };
+}
+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.
+        node_path_1.default.resolve(__dirname, '..', '..', '..', 'templates'),
+        // Support legacy layouts that copied templates into dist/.
+        node_path_1.default.resolve(__dirname, '..', '..', 'templates'),
+        // Support running tests directly from the monorepo source tree.
+        node_path_1.default.resolve(process.cwd(), 'packages', 'ztd-cli', 'templates')
+    ];
+    // Pick the first directory that contains the expected template entrypoint.
+    for (const candidate of candidates) {
+        if ((0, node_fs_1.existsSync)(node_path_1.default.join(candidate, README_TEMPLATE))) {
+            return candidate;
+        }
+    }
+    return candidates[0];
+}
+// Resolve templates from a shipped directory so `ztd init` works after `npm install`.
+const TEMPLATE_DIRECTORY = resolveTemplateDirectory();
+const DEFAULT_DEPENDENCIES = {
+    ensureDirectory: fs_1.ensureDirectory,
+    writeFile: (filePath, contents) => (0, node_fs_1.writeFileSync)(filePath, contents, 'utf8'),
+    fileExists: (filePath) => (0, node_fs_1.existsSync)(filePath),
+    runPullSchema: pull_1.runPullSchema,
+    runGenerateZtdConfig: ztdConfig_1.runGenerateZtdConfig,
+    checkPgDump: () => {
+        var _a;
+        const executable = (_a = process.env.PG_DUMP_PATH) !== null && _a !== void 0 ? _a : 'pg_dump';
+        const result = (0, node_child_process_1.spawnSync)(executable, ['--version'], { stdio: 'ignore' });
+        return result.status === 0 && !result.error;
+    },
+    log: (message) => {
+        console.log(message);
+    },
+    copyAgentsTemplate: agents_1.copyAgentsTemplate,
+    installPackages: ({ rootDir, kind, packages, packageManager }) => {
+        var _a, _b;
+        // Use the Windows shim executables so spawnSync finds the package manager in PATH.
+        const executable = resolvePackageManagerExecutable(packageManager);
+        const shellExecutable = resolvePackageManagerShellExecutable(executable, packageManager);
+        const args = buildPackageManagerArgs(kind, packageManager, packages, rootDir);
+        if (args.length === 0) {
+            return;
+        }
+        const isWin32 = process.platform === 'win32';
+        // Prefer shell execution for .cmd/.bat on Windows to avoid a guaranteed failure.
+        const preferShell = isWin32 && /\.(cmd|bat)$/i.test(executable);
+        const baseSpawnOptions = {
+            cwd: rootDir,
+            stdio: 'inherit',
+            shell: false
+        };
+        const shellSpawnOptions = {
+            ...baseSpawnOptions,
+            shell: true
+        };
+        let result = (0, node_child_process_1.spawnSync)(preferShell ? shellExecutable : executable, args, preferShell ? shellSpawnOptions : baseSpawnOptions);
+        if (result.error && isWin32 && !preferShell) {
+            // Retry with cmd.exe only on Windows so .cmd shims resolve reliably.
+            result = (0, node_child_process_1.spawnSync)(shellExecutable, args, shellSpawnOptions);
+        }
+        if ((result.error || result.status !== 0) && executable !== packageManager) {
+            // Retry with the bare command name in case a resolved path is rejected.
+            result = (0, node_child_process_1.spawnSync)(packageManager, args, baseSpawnOptions);
+            if (result.error && isWin32) {
+                // Final fallback to shell when the bare command still fails on Windows.
+                result = (0, node_child_process_1.spawnSync)(packageManager, args, shellSpawnOptions);
+            }
+        }
+        if (result.error || result.status !== 0) {
+            const base = `Failed to run ${packageManager} ${args.join(' ')}`;
+            const reason = result.error
+                ? `: ${result.error.message}`
+                : ` (exit code: ${(_a = result.status) !== null && _a !== void 0 ? _a : 'unknown'}, signal: ${(_b = result.signal) !== null && _b !== void 0 ? _b : 'none'})`;
+            throw new Error(`${base}${reason}`);
+        }
+    }
+};
+/**
+ * Run the interactive `ztd init` workflow and return the resulting summary.
+ */
+async function runInitCommand(prompter, options) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
+    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 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]
+        };
+    }
+    // Determine workflow: use explicit flag, non-interactive default, or prompt.
+    let workflow;
+    if (options === null || options === void 0 ? void 0 : options.workflow) {
+        workflow = options.workflow;
+    }
+    else if (overwritePolicy.nonInteractive) {
+        workflow = 'demo';
+    }
+    else {
+        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)'
+        ]);
+        workflow = workflowChoice === 0 ? 'pg_dump' : workflowChoice === 1 ? 'empty' : 'demo';
+    }
+    if (overwritePolicy.nonInteractive && workflow === 'pg_dump') {
+        throw new Error('Non-interactive mode does not support the pg_dump workflow (requires connection string prompt).');
+    }
+    const schemaName = normalizeSchemaName(ztdProjectConfig_1.DEFAULT_ZTD_CONFIG.ddl.defaultSchema);
+    const schemaFileName = `${sanitizeSchemaFileName(schemaName)}.sql`;
+    const appShape = (_e = options === null || options === void 0 ? void 0 : options.appShape) !== null && _e !== void 0 ? _e : 'default';
+    const scaffoldLayout = resolveInitScaffoldLayout(rootDir, appShape);
+    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'),
+        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'),
+        localSourceGuardScript: node_path_1.default.join(rootDir, 'scripts', 'local-source-guard.mjs'),
+        smokeValidationTest: node_path_1.default.join(rootDir, ztdProjectConfig_1.DEFAULT_ZTD_CONFIG.testsDir, 'smoke.validation.test.ts'),
+        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'),
+        context: node_path_1.default.join(rootDir, 'CONTEXT.md'),
+        promptDogfood: (_f = scaffoldLayout.promptDogfoodPath) !== null && _f !== void 0 ? _f : node_path_1.default.join(rootDir, 'PROMPT_DOGFOOD.md'),
+        internalAgentsManifest: node_path_1.default.join(rootDir, '.ztd', 'agents', 'manifest.json'),
+        internalAgentsRoot: node_path_1.default.join(rootDir, '.ztd', 'agents', 'root.md'),
+        internalAgentsSrc: node_path_1.default.join(rootDir, '.ztd', 'agents', 'src.md'),
+        internalAgentsTests: node_path_1.default.join(rootDir, '.ztd', 'agents', 'tests.md'),
+        internalAgentsZtd: node_path_1.default.join(rootDir, '.ztd', 'agents', 'ztd.md'),
+        sqlReadme: node_path_1.default.join(rootDir, 'src', 'sql', 'README.md'),
+        viewsRepoReadme: scaffoldLayout.viewsRepoReadmePath,
+        tablesRepoReadme: scaffoldLayout.tablesRepoReadmePath,
+        jobsReadme: (_g = scaffoldLayout.jobsReadmePath) !== null && _g !== void 0 ? _g : node_path_1.default.join(rootDir, 'src', 'jobs', 'README.md'),
+        domainReadme: (_h = scaffoldLayout.domainReadmePath) !== null && _h !== void 0 ? _h : node_path_1.default.join(rootDir, 'src', 'domain', 'README.md'),
+        applicationReadme: (_j = scaffoldLayout.applicationReadmePath) !== null && _j !== void 0 ? _j : node_path_1.default.join(rootDir, 'src', 'application', 'README.md'),
+        presentationHttpReadme: (_k = scaffoldLayout.presentationHttpReadmePath) !== null && _k !== void 0 ? _k : node_path_1.default.join(rootDir, 'src', 'presentation', 'http', 'README.md'),
+        infrastructureReadme: (_l = scaffoldLayout.infrastructureReadmePath) !== null && _l !== void 0 ? _l : node_path_1.default.join(rootDir, 'src', 'infrastructure', 'README.md'),
+        persistenceReadme: (_m = scaffoldLayout.persistenceReadmePath) !== null && _m !== void 0 ? _m : node_path_1.default.join(rootDir, 'src', 'infrastructure', 'persistence', 'README.md'),
+        sqlClient: scaffoldLayout.sqlClientPath,
+        sqlClientAdapters: scaffoldLayout.sqlClientAdaptersPath,
+        repositoryTelemetryTypes: node_path_1.default.join(rootDir, 'src', 'infrastructure', 'telemetry', 'types.ts'),
+        repositoryTelemetryConsole: node_path_1.default.join(rootDir, 'src', 'infrastructure', 'telemetry', 'consoleRepositoryTelemetry.ts'),
+        repositoryTelemetryEntry: node_path_1.default.join(rootDir, 'src', 'infrastructure', 'telemetry', 'repositoryTelemetry.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'),
+        ztdDocsReadme: node_path_1.default.join(rootDir, 'ztd', 'README.md'),
+        gitignore: node_path_1.default.join(rootDir, '.gitignore'),
+        editorconfig: node_path_1.default.join(rootDir, '.editorconfig'),
+        prettierignore: node_path_1.default.join(rootDir, '.prettierignore'),
+        prettier: node_path_1.default.join(rootDir, '.prettierrc'),
+        package: node_path_1.default.join(rootDir, 'package.json')
+    };
+    const relativePath = (key) => node_path_1.default.relative(rootDir, absolutePaths[key]).replace(/\\/g, '/') || absolutePaths[key];
+    const summaries = {};
+    const scaffoldProfile = resolveInitScaffoldProfile(rootDir, options === null || options === void 0 ? void 0 : options.localSourceRoot);
+    // Ask how the user prefers to populate the initial schema.
+    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, overwritePolicy, async () => {
+            dependencies.ensureDirectory(node_path_1.default.dirname(absolutePaths.schema));
+            await dependencies.runPullSchema({
+                url: connectionString,
+                out: node_path_1.default.dirname(absolutePaths.schema),
+                schemas: [schemaName]
+            });
+        });
+        summaries.schema = schemaSummary;
+    }
+    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, 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, 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, overwritePolicy, () => {
+        (0, ztdProjectConfig_1.writeZtdProjectConfig)(rootDir, {
+            ddl: {
+                defaultSchema: schemaName,
+                searchPath: [schemaName]
+            }
+        });
+    });
+    summaries.config = configSummary;
+    const validatorOverride = (_o = options === null || options === void 0 ? void 0 : options.validator) !== null && _o !== void 0 ? _o : (overwritePolicy.nonInteractive ? 'zod' : undefined);
+    const optionalFeatures = await gatherOptionalFeatures(prompter, dependencies, validatorOverride, options === null || options === void 0 ? void 0 : options.withAiGuidance);
+    // Emit supporting documentation that describes the workflow for contributors.
+    const readmeSummary = await writeTemplateFile(rootDir, absolutePaths.readme, relativePath('readme'), scaffoldLayout.readmeTemplate, dependencies, prompter, overwritePolicy, true);
+    if (readmeSummary) {
+        summaries.readme = readmeSummary;
+    }
+    if (optionalFeatures.aiGuidance) {
+        const contextSummary = await writeTemplateFile(rootDir, absolutePaths.context, relativePath('context'), scaffoldLayout.contextTemplate, dependencies, prompter, overwritePolicy, true);
+        if (contextSummary) {
+            summaries.context = contextSummary;
+        }
+    }
+    if (optionalFeatures.aiGuidance && scaffoldLayout.promptDogfoodTemplate) {
+        const promptDogfoodSummary = await writeTemplateFile(rootDir, absolutePaths.promptDogfood, relativePath('promptDogfood'), scaffoldLayout.promptDogfoodTemplate, dependencies, prompter, overwritePolicy, true);
+        if (promptDogfoodSummary) {
+            summaries.promptDogfood = promptDogfoodSummary;
+        }
+    }
+    if (optionalFeatures.aiGuidance) {
+        for (const summary of (0, agents_1.writeInternalAgentsArtifacts)(rootDir)) {
+            if (summary.relativePath === relativePath('internalAgentsManifest')) {
+                summaries.internalAgentsManifest = summary;
+            }
+            else if (summary.relativePath === relativePath('internalAgentsRoot')) {
+                summaries.internalAgentsRoot = summary;
+            }
+            else if (summary.relativePath === relativePath('internalAgentsSrc')) {
+                summaries.internalAgentsSrc = summary;
+            }
+            else if (summary.relativePath === relativePath('internalAgentsTests')) {
+                summaries.internalAgentsTests = summary;
+            }
+            else if (summary.relativePath === relativePath('internalAgentsZtd')) {
+                summaries.internalAgentsZtd = summary;
+            }
+        }
+    }
+    const ztdDocsReadmeSummary = await writeTemplateFile(rootDir, absolutePaths.ztdDocsReadme, relativePath('ztdDocsReadme'), ZTD_README_TEMPLATE, dependencies, prompter, overwritePolicy);
+    if (ztdDocsReadmeSummary) {
+        summaries.ztdDocsReadme = ztdDocsReadmeSummary;
+    }
+    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'), scaffoldLayout.viewsRepoReadmeTemplate, dependencies, prompter, overwritePolicy);
+    if (viewsRepoReadmeSummary) {
+        summaries.viewsRepoReadme = viewsRepoReadmeSummary;
+    }
+    const tablesRepoReadmeSummary = await writeTemplateFile(rootDir, absolutePaths.tablesRepoReadme, relativePath('tablesRepoReadme'), scaffoldLayout.tablesRepoReadmeTemplate, dependencies, prompter, overwritePolicy);
+    if (tablesRepoReadmeSummary) {
+        summaries.tablesRepoReadme = tablesRepoReadmeSummary;
+    }
+    if (scaffoldLayout.jobsReadmeTemplate) {
+        const jobsReadmeSummary = await writeTemplateFile(rootDir, absolutePaths.jobsReadme, relativePath('jobsReadme'), scaffoldLayout.jobsReadmeTemplate, dependencies, prompter, overwritePolicy);
+        if (jobsReadmeSummary) {
+            summaries.jobsReadme = jobsReadmeSummary;
+        }
+    }
+    if (scaffoldLayout.domainReadmeTemplate) {
+        const domainReadmeSummary = await writeTemplateFile(rootDir, absolutePaths.domainReadme, relativePath('domainReadme'), scaffoldLayout.domainReadmeTemplate, dependencies, prompter, overwritePolicy);
+        if (domainReadmeSummary) {
+            summaries.domainReadme = domainReadmeSummary;
+        }
+    }
+    if (scaffoldLayout.applicationReadmeTemplate) {
+        const applicationReadmeSummary = await writeTemplateFile(rootDir, absolutePaths.applicationReadme, relativePath('applicationReadme'), scaffoldLayout.applicationReadmeTemplate, dependencies, prompter, overwritePolicy);
+        if (applicationReadmeSummary) {
+            summaries.applicationReadme = applicationReadmeSummary;
+        }
+    }
+    if (scaffoldLayout.presentationHttpReadmeTemplate) {
+        const presentationHttpReadmeSummary = await writeTemplateFile(rootDir, absolutePaths.presentationHttpReadme, relativePath('presentationHttpReadme'), scaffoldLayout.presentationHttpReadmeTemplate, dependencies, prompter, overwritePolicy);
+        if (presentationHttpReadmeSummary) {
+            summaries.presentationHttpReadme = presentationHttpReadmeSummary;
+        }
+    }
+    if (scaffoldLayout.infrastructureReadmeTemplate) {
+        const infrastructureReadmeSummary = await writeTemplateFile(rootDir, absolutePaths.infrastructureReadme, relativePath('infrastructureReadme'), scaffoldLayout.infrastructureReadmeTemplate, dependencies, prompter, overwritePolicy);
+        if (infrastructureReadmeSummary) {
+            summaries.infrastructureReadme = infrastructureReadmeSummary;
+        }
+    }
+    if (scaffoldLayout.persistenceReadmeTemplate) {
+        const persistenceReadmeSummary = await writeTemplateFile(rootDir, absolutePaths.persistenceReadme, relativePath('persistenceReadme'), scaffoldLayout.persistenceReadmeTemplate, dependencies, prompter, overwritePolicy);
+        if (persistenceReadmeSummary) {
+            summaries.persistenceReadme = persistenceReadmeSummary;
+        }
+    }
+    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;
+    }
+    if (scaffoldProfile.dependencyProfile === 'local-source') {
+        const localSourceGuardSummary = await writeDocFile(absolutePaths.localSourceGuardScript, relativePath('localSourceGuardScript'), buildLocalSourceGuardContents(absolutePaths.localSourceGuardScript, scaffoldProfile), dependencies, prompter, overwritePolicy);
+        if (localSourceGuardSummary) {
+            summaries.localSourceGuardScript = localSourceGuardSummary;
+        }
+    }
+    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'), scaffoldLayout.sqlClientTemplate, dependencies);
+    if (sqlClientSummary) {
+        summaries.sqlClient = sqlClientSummary;
+        // Only scaffold the pg adapter alongside the SqlClient interface.
+        const sqlClientAdaptersSummary = writeOptionalTemplateFile(absolutePaths.sqlClientAdapters, relativePath('sqlClientAdapters'), scaffoldLayout.sqlClientAdaptersTemplate, dependencies);
+        if (sqlClientAdaptersSummary) {
+            summaries.sqlClientAdapters = sqlClientAdaptersSummary;
+        }
+        // Repository telemetry stays application-owned, but the scaffold can
+        // provide a default structured seam that repositories depend on.
+        const repositoryTelemetryTypesSummary = writeOptionalTemplateFile(absolutePaths.repositoryTelemetryTypes, relativePath('repositoryTelemetryTypes'), REPOSITORY_TELEMETRY_TYPES_TEMPLATE, dependencies);
+        if (repositoryTelemetryTypesSummary) {
+            summaries.repositoryTelemetryTypes = repositoryTelemetryTypesSummary;
+        }
+        const repositoryTelemetryConsoleSummary = writeOptionalTemplateFile(absolutePaths.repositoryTelemetryConsole, relativePath('repositoryTelemetryConsole'), REPOSITORY_TELEMETRY_CONSOLE_TEMPLATE, dependencies);
+        if (repositoryTelemetryConsoleSummary) {
+            summaries.repositoryTelemetryConsole = repositoryTelemetryConsoleSummary;
+        }
+        const repositoryTelemetryEntrySummary = writeOptionalTemplateFile(absolutePaths.repositoryTelemetryEntry, relativePath('repositoryTelemetryEntry'), REPOSITORY_TELEMETRY_ENTRY_TEMPLATE, dependencies);
+        if (repositoryTelemetryEntrySummary) {
+            summaries.repositoryTelemetryEntry = repositoryTelemetryEntrySummary;
+        }
+    }
+    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'), scaffoldLayout.testkitClientTemplate, dependencies, prompter, overwritePolicy);
+    if (testkitSummary) {
+        summaries.testkitClient = testkitSummary;
+    }
+    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, overwritePolicy);
+    if (vitestConfigSummary) {
+        summaries.vitestConfig = vitestConfigSummary;
+    }
+    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) {
+        summaries.editorconfig = editorconfigSummary;
+    }
+    const prettierSummary = copyTemplateFileIfMissing(rootDir, relativePath('prettier'), '.prettierrc', dependencies);
+    if (prettierSummary) {
+        summaries.prettier = prettierSummary;
+    }
+    const gitignoreSummary = copyTemplateFileIfMissing(rootDir, relativePath('gitignore'), '.gitignore', dependencies);
+    if (gitignoreSummary) {
+        summaries.gitignore = gitignoreSummary;
+    }
+    const prettierignoreSummary = copyTemplateFileIfMissing(rootDir, relativePath('prettierignore'), '.prettierignore', dependencies);
+    if (prettierignoreSummary) {
+        summaries.prettierignore = prettierignoreSummary;
+    }
+    const packageSummary = ensurePackageJsonFormatting(rootDir, relativePath('package'), dependencies, optionalFeatures, scaffoldProfile);
+    if (packageSummary) {
+        summaries.package = packageSummary;
+    }
+    await ensureTemplateDependenciesInstalled(rootDir, absolutePaths, summaries, dependencies);
+    const nextSteps = buildNextSteps(normalizeRelative(rootDir, absolutePaths.schema), workflow, rootDir, scaffoldProfile, appShape);
+    const summaryLines = buildSummaryLines(summaries, optionalFeatures, nextSteps, scaffoldProfile);
+    summaryLines.forEach(dependencies.log);
+    return {
+        summary: summaryLines.join('\n'),
+        files: Object.values(summaries)
+    };
+}
+function resolvePackageManagerExecutable(packageManager) {
+    var _a;
+    const override = process.env.ZTD_PACKAGE_MANAGER_PATH;
+    if (override) {
+        return override;
+    }
+    if (process.platform !== 'win32') {
+        return packageManager;
+    }
+    // Prefer .cmd shims first on Windows so they take precedence over extension-less files.
+    const cmdFallbacks = {
+        npm: 'npm.cmd',
+        pnpm: 'pnpm.cmd',
+        yarn: 'yarn.cmd'
+    };
+    const cmdResolved = resolveExecutableInPath(cmdFallbacks[packageManager]);
+    if (cmdResolved) {
+        return cmdResolved;
+    }
+    // Fall back to the extension-less name if no cmd shim is found.
+    const resolved = resolveExecutableInPath(packageManager);
+    if (resolved) {
+        return resolved;
+    }
+    return (_a = cmdFallbacks[packageManager]) !== null && _a !== void 0 ? _a : packageManager;
+}
+function resolvePackageManagerShellExecutable(executable, packageManager, platform = process.platform) {
+    if (platform !== 'win32') {
+        return executable;
+    }
+    // `shell: true` delegates through cmd.exe, which splits unquoted absolute paths with spaces.
+    // Use the shim basename so the shell resolves it from PATH without truncating at `C:\Program`.
+    if (/\.(cmd|bat)$/i.test(executable) && node_path_1.default.win32.isAbsolute(executable)) {
+        return node_path_1.default.win32.basename(executable);
+    }
+    return executable || packageManager;
+}
+function resolveExecutableInPath(executable) {
+    var _a, _b, _c;
+    const pathValue = (_b = (_a = process.env.PATH) !== null && _a !== void 0 ? _a : process.env.Path) !== null && _b !== void 0 ? _b : '';
+    if (!pathValue) {
+        return null;
+    }
+    const pathEntries = pathValue
+        .split(node_path_1.default.delimiter)
+        .map((entry) => {
+        const trimmed = entry.trim();
+        if (process.platform !== 'win32') {
+            return trimmed;
+        }
+        if (trimmed.startsWith('"') && trimmed.endsWith('"') && trimmed.length >= 2) {
+            return trimmed.slice(1, -1);
+        }
+        return trimmed;
+    })
+        .filter(Boolean);
+    const hasExtension = node_path_1.default.extname(executable).length > 0;
+    const extensions = process.platform === 'win32'
+        ? ((_c = process.env.PATHEXT) !== null && _c !== void 0 ? _c : '.EXE;.CMD;.BAT;.COM')
+            .split(';')
+            .map((ext) => ext.trim())
+            .filter(Boolean)
+        : [''];
+    // Check each PATH entry with PATHEXT so we can resolve shim executables.
+    for (const entry of pathEntries) {
+        if (hasExtension) {
+            const candidate = node_path_1.default.join(entry, executable);
+            if ((0, node_fs_1.existsSync)(candidate)) {
+                return candidate;
+            }
+            continue;
+        }
+        for (const ext of extensions) {
+            const candidate = node_path_1.default.join(entry, `${executable}${ext}`);
+            if ((0, node_fs_1.existsSync)(candidate)) {
+                return candidate;
+            }
+        }
+    }
+    return null;
+}
+function findAncestorPnpmWorkspaceRoot(rootDir) {
+    let cursor = node_path_1.default.resolve(rootDir);
+    while (true) {
+        const parentDir = node_path_1.default.dirname(cursor);
+        if (parentDir === cursor) {
+            return null;
+        }
+        cursor = parentDir;
+        if ((0, node_fs_1.existsSync)(node_path_1.default.join(cursor, 'pnpm-workspace.yaml'))) {
+            return cursor;
+        }
+    }
+}
+function resolvePnpmWorkspaceGuard(rootDir, packageManager) {
+    if (packageManager !== 'pnpm') {
+        return { workspaceRoot: null, shouldIgnoreWorkspace: false };
+    }
+    const workspaceRoot = findAncestorPnpmWorkspaceRoot(rootDir);
+    return {
+        workspaceRoot,
+        shouldIgnoreWorkspace: workspaceRoot !== null,
+    };
+}
+function buildManualInstallCommand(kind, packageManager, packages, rootDir) {
+    return [packageManager, ...buildPackageManagerArgs(kind, packageManager, packages, rootDir)].join(' ');
+}
+function resolveInitInstallStrategy(rootDir, packageManager, environment) {
+    var _a, _b;
+    const workspaceGuard = resolvePnpmWorkspaceGuard(rootDir, packageManager);
+    const installCommand = packageManager === 'pnpm' && workspaceGuard.shouldIgnoreWorkspace
+        ? 'pnpm install --ignore-workspace'
+        : `${packageManager} install`;
+    const platform = (_a = environment === null || environment === void 0 ? void 0 : environment.platform) !== null && _a !== void 0 ? _a : process.platform;
+    // npm_command is provided by npm/pnpm for lifecycle and exec invocations, which we use as a fallback in real CLI runs.
+    const npmCommand = (_b = environment === null || environment === void 0 ? void 0 : environment.npmCommand) !== null && _b !== void 0 ? _b : process.env.npm_command;
+    return {
+        installCommand,
+        workspaceGuard,
+        shouldDeferAutoInstall: platform === 'win32' && packageManager === 'pnpm' && npmCommand === 'exec'
+    };
+}
+function buildPackageManagerArgs(kind, packageManager, packages, rootDir) {
+    const pnpmWorkspaceGuard = rootDir !== undefined ? resolvePnpmWorkspaceGuard(rootDir, packageManager) : { shouldIgnoreWorkspace: false };
+    if (kind === 'install') {
+        return packageManager === 'pnpm' && pnpmWorkspaceGuard.shouldIgnoreWorkspace
+            ? ['install', '--ignore-workspace']
+            : ['install'];
+    }
+    if (packages.length === 0) {
+        return [];
+    }
+    if (packageManager === 'npm') {
+        return ['install', '-D', ...packages];
+    }
+    return packageManager === 'pnpm' && pnpmWorkspaceGuard.shouldIgnoreWorkspace
+        ? ['add', '-D', ...packages, '--ignore-workspace']
+        : ['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();
+    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, _b;
+    const packageJsonPath = node_path_1.default.join(rootDir, 'package.json');
+    if (!dependencies.fileExists(packageJsonPath)) {
+        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);
+    const installStrategy = resolveInitInstallStrategy(rootDir, packageManager);
+    if (installStrategy.workspaceGuard.shouldIgnoreWorkspace) {
+        dependencies.log(`Detected parent pnpm workspace at ${installStrategy.workspaceGuard.workspaceRoot}. Running pnpm with --ignore-workspace so this initialized project keeps isolated installs.`);
+    }
+    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) {
+        if (installStrategy.shouldDeferAutoInstall) {
+            const manualAddCommand = buildManualInstallCommand('devDependencies', packageManager, missingPackages, rootDir);
+            dependencies.log(`Skipping automatic ${manualAddCommand} because Windows pnpm exec can break the current ztd process after package.json changes. Next: run ${manualAddCommand} manually.`);
+            return;
+        }
+        dependencies.log(`Installing devDependencies referenced by templates (${packageManager}): ${missingPackages.join(', ')}`);
+        await dependencies.installPackages({
+            rootDir,
+            kind: 'devDependencies',
+            packages: missingPackages,
+            packageManager
+        });
+        return;
+    }
+    // Avoid mutating the current pnpm exec shim on Windows while it is still executing this command.
+    if (((_a = summaries.package) === null || _a === void 0 ? void 0 : _a.outcome) === 'created' || ((_b = summaries.package) === null || _b === void 0 ? void 0 : _b.outcome) === 'overwritten') {
+        if (installStrategy.shouldDeferAutoInstall) {
+            dependencies.log(`Skipping automatic ${installStrategy.installCommand} because Windows pnpm exec can break the current ztd process after package.json changes. Next: run ${installStrategy.installCommand} manually.`);
+            return;
+        }
+        dependencies.log(`Running ${installStrategy.installCommand} to sync dependencies.`);
+        await dependencies.installPackages({ rootDir, kind: 'install', packages: [], packageManager });
+    }
+}
+function copyTemplateFileIfMissing(rootDir, relative, templateName, dependencies) {
+    const templatePath = node_path_1.default.join(TEMPLATE_DIRECTORY, templateName);
+    // Skip copying when the CLI package does not include the requested template.
+    if (!(0, node_fs_1.existsSync)(templatePath)) {
+        return null;
+    }
+    const targetPath = node_path_1.default.join(rootDir, relative);
+    // Avoid overwriting a file that the project already maintains.
+    if (dependencies.fileExists(targetPath)) {
+        return null;
+    }
+    dependencies.ensureDirectory(node_path_1.default.dirname(targetPath));
+    // Emit the template content so the generated project gets the same formatting defaults.
+    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, optionalFeatures, scaffoldProfile) {
+    var _a, _b;
+    const packagePath = node_path_1.default.join(rootDir, 'package.json');
+    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'
+    };
+    if (scaffoldProfile.dependencyProfile === 'local-source') {
+        // Route test and typecheck through the local-source guard so parent workspaces cannot silently hijack execution.
+        requiredScripts.test = 'node ./scripts/local-source-guard.mjs test';
+        requiredScripts.typecheck = 'node ./scripts/local-source-guard.mjs typecheck';
+        requiredScripts.ztd = 'node ./scripts/local-source-guard.mjs ztd';
+    }
+    // Ensure the canonical formatting and lint scripts exist without overwriting custom commands.
+    for (const [name, value] of Object.entries(requiredScripts)) {
+        if (name in scripts) {
+            continue;
+        }
+        scripts[name] = value;
+        changed = true;
+    }
+    if (changed) {
+        parsed.scripts = scripts;
+    }
+    // Provide lint-staged wiring for the formatting pipeline when no configuration is present.
+    if (!('lint-staged' in parsed)) {
+        parsed['lint-staged'] = {
+            '*.{ts,tsx,js,jsx,json,md,sql}': ['pnpm format']
+        };
+        changed = true;
+    }
+    // Wire simple-git-hooks only if the user has not already customized it.
+    if (!('simple-git-hooks' in parsed)) {
+        parsed['simple-git-hooks'] = {
+            'pre-commit': 'pnpm lint-staged'
+        };
+        changed = true;
+    }
+    const devDependencies = (_b = parsed.devDependencies) !== null && _b !== void 0 ? _b : {};
+    const formattingDeps = {
+        eslint: '^9.22.0',
+        'lint-staged': '^16.2.7',
+        'prettier': '^3.7.4',
+        '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) {
+            continue;
+        }
+        devDependencies[dep] = version;
+        changed = true;
+    }
+    const stackDependencies = scaffoldProfile.dependencyProfile === 'local-source'
+        ? buildLocalSourceStackDependencies(rootDir, scaffoldProfile)
+        : {
+            ...STACK_DEV_DEPENDENCIES
+        };
+    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;
+    }
+    parsed.devDependencies = devDependencies;
+    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: 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, 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, 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 --force 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, 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, 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, overwritePolicy);
+}
+function resolveTemplateTarget(rootDir, absolutePath, relative, dependencies, allowFallback) {
+    if (!dependencies.fileExists(absolutePath)) {
+        return { absolutePath, relativePath: relative };
+    }
+    if (!allowFallback || !isRootMarkdown(relative)) {
+        dependencies.log(`Skipping template ${relative} because the target file already exists.`);
+        return null;
+    }
+    // When the preferred destination already exists, try emitting a sibling with a "_ztd" suffix.
+    const parsed = node_path_1.default.parse(absolutePath);
+    const fallbackAbsolute = node_path_1.default.join(parsed.dir, `${parsed.name}_ztd${parsed.ext}`);
+    if (dependencies.fileExists(fallbackAbsolute)) {
+        const existingRelative = normalizeRelative(rootDir, fallbackAbsolute);
+        dependencies.log(`Skipping template ${relative} because both ${relative} and ${existingRelative} already exist.`);
+        return null;
+    }
+    const fallbackRelative = normalizeRelative(rootDir, fallbackAbsolute);
+    dependencies.log(`Existing ${relative} preserved; writing template as ${fallbackRelative}.`);
+    return { absolutePath: fallbackAbsolute, relativePath: fallbackRelative };
+}
+function normalizeRelative(rootDir, absolutePath) {
+    // Normalize the path relative to the project root so summaries use forward slashes.
+    const relative = normalizeCliPath(node_path_1.default.relative(rootDir, absolutePath));
+    return relative || absolutePath;
+}
+function normalizeCliPath(filePath) {
+    return filePath.replace(/\\/g, '/');
+}
+/**
+ * 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);
+    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('/');
+}
+function loadTemplate(templateName) {
+    const templatePath = node_path_1.default.join(TEMPLATE_DIRECTORY, templateName);
+    // Fail fast if the template bundle was shipped without the requested file.
+    if (!(0, node_fs_1.existsSync)(templatePath)) {
+        throw new Error(`Missing template file: ${templateName}`);
+    }
+    return (0, node_fs_1.readFileSync)(templatePath, 'utf8');
+}
+function buildLocalSourceGuardContents(absolutePath, scaffoldProfile) {
+    const template = loadTemplate(LOCAL_SOURCE_GUARD_TEMPLATE);
+    if (scaffoldProfile.dependencyProfile !== 'local-source' || !scaffoldProfile.localSourceRoot) {
+        return template.replace('__LOCAL_SOURCE_ZTD_CLI__', './packages/ztd-cli/dist/index.js');
+    }
+    const cliEntry = node_path_1.default.join(scaffoldProfile.localSourceRoot, 'packages', 'ztd-cli', 'dist', 'index.js');
+    const projectRoot = node_path_1.default.dirname(node_path_1.default.dirname(absolutePath));
+    const relativeCliEntry = normalizeCliPath(node_path_1.default.relative(projectRoot, cliEntry));
+    const cliImportPath = relativeCliEntry.startsWith('.') || relativeCliEntry.startsWith('/') ? relativeCliEntry : `./${relativeCliEntry}`;
+    return template.replace('__LOCAL_SOURCE_ZTD_CLI__', cliImportPath);
+}
+function buildNextSteps(schemaRelativePath, workflow, rootDir, scaffoldProfile, appShape) {
+    const packageManager = detectPackageManager(rootDir);
+    const installStrategy = resolveInitInstallStrategy(rootDir, packageManager);
+    const installCommand = installStrategy.installCommand;
+    const runScriptCommand = (script) => packageManager === 'npm' ? `npm run ${script}` : `${packageManager} ${script}`;
+    const runLocalSourceZtdCommand = packageManager === 'npm' ? 'npm run ztd --' : `${packageManager} ztd`;
+    const ztdCommand = packageManager === 'npm' ? 'npx ztd' : packageManager === 'yarn' ? 'yarn exec ztd' : 'pnpm exec ztd';
+    if (scaffoldProfile.dependencyProfile === 'local-source') {
+        const localSourceSteps = [
+            workflow === 'pg_dump'
+                ? `Review the dumped DDL in ${schemaRelativePath}`
+                : `If the schema file is empty, edit ${schemaRelativePath}`,
+            `Run ${installCommand}`,
+            `Run ${runScriptCommand('typecheck')}`,
+            `Run ${runScriptCommand('test')}`,
+            `Run ${runLocalSourceZtdCommand} ztd-config`,
+            'Generated QuerySpecs can keep the default @rawsql-ts/sql-contract package import.',
+            appShape === 'webapi'
+                ? 'Keep Domain, Application, and Presentation changes free from direct ZTD assumptions'
+                : 'Keep handwritten SQL and QuerySpecs aligned before adding repository code',
+            'Wire repositories to src/infrastructure/telemetry/repositoryTelemetry.ts so applications can replace the default hook',
+            'Provide a SqlClient implementation before adding SQL-backed tests'
+        ];
+        return localSourceSteps.map((step, index) => ` ${index + 1}. ${step}`);
+    }
+    const nextSteps = [
+        workflow === 'pg_dump'
+            ? `Review the dumped DDL in ${schemaRelativePath}`
+            : `If the schema file is empty, edit ${schemaRelativePath}`
+    ];
+    if (installStrategy.shouldDeferAutoInstall) {
+        nextSteps.push(`Run ${installCommand}`);
+    }
+    nextSteps.push(`Run ${ztdCommand} ztd-config`);
+    if (appShape === 'webapi') {
+        nextSteps.push('Keep WebAPI flow changes in src/domain, src/application, and src/presentation/http unless you are editing persistence infrastructure');
+    }
+    nextSteps.push('Wire repositories to src/infrastructure/telemetry/repositoryTelemetry.ts when you add SQL-backed repository classes');
+    nextSteps.push('Provide a SqlClient implementation (adapter or mock)');
+    nextSteps.push('Run tests (pnpm test or npx vitest run)');
+    // Avoid repeating the same install hint when the deferred-install path already emitted it explicitly.
+    if (installStrategy.workspaceGuard.shouldIgnoreWorkspace && !installStrategy.shouldDeferAutoInstall) {
+        nextSteps.push('This project is nested under a parent pnpm workspace; use pnpm install --ignore-workspace for manual installs.');
+    }
+    return nextSteps.map((step, index) => ` ${index + 1}. ${step}`);
+}
+function resolveInitScaffoldProfile(rootDir, localSourceRoot) {
+    if (!localSourceRoot) {
+        return { dependencyProfile: 'registry', localSourceRoot: null };
+    }
+    const resolvedRoot = node_path_1.default.resolve(rootDir, localSourceRoot);
+    // Validate every direct rawsql-ts scaffold dependency up front so local-source installs
+    // cannot silently mix local packages with registry packages.
+    for (const packageDir of Object.values(LOCAL_SOURCE_STACK_PACKAGE_DIRS)) {
+        const packageJsonPath = node_path_1.default.join(resolvedRoot, packageDir, 'package.json');
+        if (!(0, node_fs_1.existsSync)(packageJsonPath)) {
+            throw new Error(`The local-source root does not contain ${normalizeCliPath(node_path_1.default.join(packageDir, 'package.json'))}: ${normalizeCliPath(resolvedRoot)}`);
+        }
+    }
+    return {
+        dependencyProfile: 'local-source',
+        localSourceRoot: resolvedRoot
+    };
+}
+function buildLocalSourceStackDependencies(rootDir, scaffoldProfile) {
+    if (scaffoldProfile.dependencyProfile !== 'local-source' || !scaffoldProfile.localSourceRoot) {
+        return {
+            ...STACK_DEV_DEPENDENCIES
+        };
+    }
+    return Object.fromEntries(Object.entries(LOCAL_SOURCE_STACK_PACKAGE_DIRS).map(([packageName, packageDir]) => [
+        packageName,
+        toFileDependencySpecifier(rootDir, node_path_1.default.join(scaffoldProfile.localSourceRoot, packageDir))
+    ]));
+}
+function toFileDependencySpecifier(rootDir, targetDir) {
+    const relativeTarget = normalizeCliPath(node_path_1.default.relative(rootDir, targetDir));
+    const withDotPrefix = relativeTarget.startsWith('.') || relativeTarget.startsWith('/') ? relativeTarget : `./${relativeTarget}`;
+    return `file:${withDotPrefix}`;
+}
+function buildSummaryLines(summaries, optionalFeatures, nextSteps, scaffoldProfile) {
+    const orderedKeys = [
+        'schema',
+        'config',
+        'readme',
+        'context',
+        'promptDogfood',
+        'internalAgentsManifest',
+        'internalAgentsRoot',
+        'internalAgentsSrc',
+        'internalAgentsTests',
+        'internalAgentsZtd',
+        'ztdDocsReadme',
+        'sqlReadme',
+        'viewsRepoReadme',
+        'tablesRepoReadme',
+        'jobsReadme',
+        'domainReadme',
+        'applicationReadme',
+        'presentationHttpReadme',
+        'infrastructureReadme',
+        'persistenceReadme',
+        'smokeSpec',
+        'smokeCoercions',
+        'smokeRuntime',
+        'localSourceGuardScript',
+        'smokeValidationTest',
+        'testsSmoke',
+        'sqlClient',
+        'sqlClientAdapters',
+        'repositoryTelemetryTypes',
+        'repositoryTelemetryConsole',
+        'repositoryTelemetryEntry',
+        'testkitClient',
+        'globalSetup',
+        'vitestConfig',
+        'tsconfig',
+        'gitignore',
+        'editorconfig',
+        'prettierignore',
+        'prettier',
+        'package'
+    ];
+    const lines = ['ZTD project initialized.', '', 'Created:'];
+    for (const key of orderedKeys) {
+        const summary = summaries[key];
+        const note = (summary === null || summary === void 0 ? void 0 : summary.outcome) === 'created'
+            ? ''
+            : (summary === null || summary === void 0 ? void 0 : summary.outcome) === 'overwritten'
+                ? ' (overwritten existing file)'
+                : ' (existing file preserved)';
+        if (summary) {
+            lines.push(` - ${summary.relativePath}${note}`);
+        }
+    }
+    lines.push('', 'Validation configuration:');
+    const stackLine = scaffoldProfile.dependencyProfile === 'local-source'
+        ? ' - SQL catalog/mapping support via @rawsql-ts/sql-contract backed by a local file dependency in developer mode (see docs/recipes/sql-contract.md)'
+        : ' - SQL catalog/mapping support via @rawsql-ts/sql-contract (see docs/recipes/sql-contract.md)';
+    lines.push(stackLine);
+    const validatorLabel = optionalFeatures.validator === 'zod'
+        ? 'Zod (zod, docs/recipes/validation-zod.md)'
+        : 'ArkType (arktype, docs/recipes/validation-arktype.md)';
+    lines.push(` - Validator backend: ${validatorLabel}`);
+    if (optionalFeatures.aiGuidance) {
+        lines.push('', 'AI guidance:');
+        lines.push(' - Internal guidance is managed under .ztd/agents/.');
+        lines.push(' - Visible AGENTS.md files are disabled by default. Enable with: ztd agents install');
+    }
+    lines.push('', 'Next steps:', ...nextSteps);
+    return lines;
+}
+const VALID_WORKFLOWS = ['pg_dump', 'empty', 'demo'];
+const VALID_VALIDATORS = ['zod', 'arktype'];
+const VALID_APP_SHAPES = ['default', 'webapi'];
+function buildInitDryRunPlan(rootDir, options) {
+    const schemaName = normalizeSchemaName(ztdProjectConfig_1.DEFAULT_ZTD_CONFIG.ddl.defaultSchema);
+    const schemaFileName = `${sanitizeSchemaFileName(schemaName)}.sql`;
+    const scaffoldLayout = resolveInitScaffoldLayout(rootDir, options.appShape);
+    const files = [
+        'ztd.config.json',
+        node_path_1.default.join(ztdProjectConfig_1.DEFAULT_ZTD_CONFIG.ddlDir, schemaFileName),
+        node_path_1.default.join(ztdProjectConfig_1.DEFAULT_ZTD_CONFIG.testsDir, 'smoke.test.ts'),
+        node_path_1.default.join(ztdProjectConfig_1.DEFAULT_ZTD_CONFIG.testsDir, 'smoke.validation.test.ts'),
+        node_path_1.default.join(ztdProjectConfig_1.DEFAULT_ZTD_CONFIG.testsDir, 'support', 'testkit-client.ts'),
+        node_path_1.default.join(ztdProjectConfig_1.DEFAULT_ZTD_CONFIG.testsDir, 'support', 'global-setup.ts'),
+        node_path_1.default.join(ztdProjectConfig_1.DEFAULT_ZTD_CONFIG.testsDir, 'generated', 'ztd-row-map.generated.ts'),
+        node_path_1.default.join(ztdProjectConfig_1.DEFAULT_ZTD_CONFIG.testsDir, 'generated', 'ztd-layout.generated.ts'),
+        'README.md',
+        'src/sql/README.md',
+        'vitest.config.ts',
+        'tsconfig.json'
+    ];
+    if (options.withAiGuidance) {
+        files.push('.ztd/agents/manifest.json');
+        files.push('.ztd/agents/root.md');
+        files.push('.ztd/agents/src.md');
+        files.push('.ztd/agents/tests.md');
+        files.push('.ztd/agents/ztd.md');
+        files.push('CONTEXT.md');
+    }
+    if (options.appShape === 'webapi') {
+        if (options.withAiGuidance) {
+            files.push('PROMPT_DOGFOOD.md');
+        }
+        files.push('src/domain/README.md');
+        files.push('src/application/README.md');
+        files.push('src/presentation/http/README.md');
+        files.push('src/infrastructure/README.md');
+        files.push('src/infrastructure/persistence/README.md');
+        files.push('src/infrastructure/persistence/repositories/views/README.md');
+        files.push('src/infrastructure/persistence/repositories/tables/README.md');
+    }
+    else {
+        files.push('src/repositories/views/README.md');
+        files.push('src/repositories/tables/README.md');
+        files.push('src/jobs/README.md');
+    }
+    files.push(normalizeCliPath(node_path_1.default.relative(rootDir, scaffoldLayout.sqlClientPath)));
+    files.push(normalizeCliPath(node_path_1.default.relative(rootDir, scaffoldLayout.sqlClientAdaptersPath)));
+    if (options.withSqlClient) {
+        files.push(node_path_1.default.join('src', 'infrastructure', 'telemetry', 'types.ts'));
+        files.push(node_path_1.default.join('src', 'infrastructure', 'telemetry', 'consoleRepositoryTelemetry.ts'));
+        files.push(node_path_1.default.join('src', 'infrastructure', 'telemetry', 'repositoryTelemetry.ts'));
+    }
+    if (options.withAppInterface) {
+        files.splice(0, files.length, 'AGENTS.md');
+    }
+    if (options.localSourceRoot) {
+        resolveInitScaffoldProfile(rootDir, options.localSourceRoot);
+    }
+    return {
+        schemaVersion: 1,
+        workflow: options.workflow,
+        validator: options.validator,
+        dryRun: true,
+        files: files.map((file) => normalizeCliPath(file))
+    };
+}
+function validateJsonBooleanFlag(value, flagName) {
+    if (value === undefined || typeof value === 'boolean') {
+        return true;
+    }
+    console.error(`Invalid --${flagName} value in --json payload. Expected a boolean.`);
+    process.exit(1);
+}
+function registerInitCommand(program) {
+    program
+        .command('init')
+        .description('Automate project setup for Zero Table Dependency workflows')
+        .option('--app-shape <type>', 'Application scaffold shape: default or webapi (default: default)')
+        .option('--with-ai-guidance', 'Generate internal AI guidance files such as CONTEXT.md and .ztd/agents/*')
+        .option('--with-sqlclient', 'Generate a minimal SqlClient interface for repositories')
+        .option('--with-app-interface', 'Append application interface guidance to AGENTS.md only')
+        .option('--yes', 'Accept defaults without interactive prompts')
+        .option('--force', 'Allow ztd init to overwrite files it owns')
+        .option('--workflow <type>', 'Schema workflow: pg_dump, empty, or demo (default: demo)')
+        .option('--validator <type>', 'Validator backend: zod or arktype (default: zod)')
+        .option('--dry-run', 'Validate init options and emit the planned scaffold without writing files')
+        .option('--json <payload>', 'Pass init options as a JSON object')
+        .option('--local-source-root <path>', 'Link @rawsql-ts dependencies to a local monorepo root for dogfooding instead of published npm packages')
+        .action(async (options) => {
+        var _a, _b, _c;
+        const merged = options.json ? { ...options, ...(0, agentCli_1.parseJsonPayload)(options.json, '--json') } : options;
+        if (typeof merged.localSourceRoot === 'string') {
+            merged.localSourceRoot = (0, agentSafety_1.rejectEncodedTraversal)((0, agentSafety_1.rejectControlChars)(merged.localSourceRoot, '--local-source-root'), '--local-source-root');
+        }
+        // Reject stringly-typed booleans from --json so unsupported payloads cannot silently enable features.
+        validateJsonBooleanFlag(merged.yes, 'yes');
+        validateJsonBooleanFlag(merged.dryRun, 'dry-run');
+        validateJsonBooleanFlag(merged.force, 'force');
+        validateJsonBooleanFlag(merged.withAiGuidance, 'with-ai-guidance');
+        validateJsonBooleanFlag(merged.withSqlclient, 'with-sqlclient');
+        validateJsonBooleanFlag(merged.withAppInterface, 'with-app-interface');
+        // Validate --workflow value if provided.
+        if (merged.workflow && !VALID_WORKFLOWS.includes(merged.workflow)) {
+            console.error(`Invalid --workflow value: "${merged.workflow}". Must be one of: ${VALID_WORKFLOWS.join(', ')}`);
+            process.exit(1);
+        }
+        // Validate --validator value if provided.
+        if (merged.validator && !VALID_VALIDATORS.includes(merged.validator)) {
+            console.error(`Invalid --validator value: "${merged.validator}". Must be one of: ${VALID_VALIDATORS.join(', ')}`);
+            process.exit(1);
+        }
+        if (merged.appShape && !VALID_APP_SHAPES.includes(merged.appShape)) {
+            console.error(`Invalid --app-shape value: "${merged.appShape}". Must be one of: ${VALID_APP_SHAPES.join(', ')}`);
+            process.exit(1);
+        }
+        const isNonInteractive = merged.yes === true || !process.stdin.isTTY || merged.dryRun === true;
+        // When --yes is used, apply defaults for unspecified flags.
+        const workflow = (_a = merged.workflow) !== null && _a !== void 0 ? _a : (isNonInteractive ? 'demo' : undefined);
+        const validator = (_b = merged.validator) !== null && _b !== void 0 ? _b : (isNonInteractive ? 'zod' : undefined);
+        const appShape = (_c = merged.appShape) !== null && _c !== void 0 ? _c : 'default';
+        if (isNonInteractive && workflow === 'pg_dump') {
+            console.error('Non-interactive mode does not support the pg_dump workflow (requires connection string prompt).');
+            process.exit(1);
+        }
+        if (merged.dryRun === true) {
+            const plan = buildInitDryRunPlan(process.cwd(), {
+                appShape,
+                withAiGuidance: merged.withAiGuidance === true,
+                withSqlClient: merged.withSqlclient === true,
+                withAppInterface: merged.withAppInterface === true,
+                workflow: workflow !== null && workflow !== void 0 ? workflow : 'demo',
+                validator: validator !== null && validator !== void 0 ? validator : 'zod',
+                localSourceRoot: merged.localSourceRoot
+            });
+            if ((0, agentCli_1.isJsonOutput)()) {
+                (0, agentCli_1.writeCommandEnvelope)('init', plan);
+            }
+            else {
+                process.stdout.write(`${JSON.stringify(plan, null, 2)}\n`);
+            }
+            return;
+        }
+        const prompter = createConsolePrompter();
+        try {
+            await runInitCommand(prompter, {
+                appShape,
+                withAiGuidance: merged.withAiGuidance === true,
+                withSqlClient: merged.withSqlclient === true,
+                withAppInterface: merged.withAppInterface === true,
+                forceOverwrite: merged.force === true,
+                nonInteractive: isNonInteractive,
+                workflow,
+                validator,
+                localSourceRoot: merged.localSourceRoot
+            });
+        }
+        finally {
+            prompter.close();
+        }
+    });
+}
+//# sourceMappingURL=init.js.map