@hypequery/cli 1.3.1 → 1.5.0

package/dist/commands/init.js

@@ -2,8 +2,9 @@ import { mkdir, writeFile, readFile, access } from 'node:fs/promises';
 import path from 'node:path';
 import ora from 'ora';
 import { logger } from '../utils/logger.js';
-import { promptClickHouseConnection, promptOutputDirectory, promptInitStyle, promptGenerateExample, promptTableSelection, promptDatasetTableSelection, confirmOverwrite, promptRetry, promptContinueWithoutDb, } from '../utils/prompts.js';
+import { promptClickHouseConnection, promptChdbStorage, promptOutputDirectory, promptInitStyle, promptGenerateExample, promptTableSelection, promptDatasetTableSelection, confirmOverwrite, promptRetry, promptContinueWithoutDb, } from '../utils/prompts.js';
 import { validateConnection, getTableCount, getTables, } from '../utils/detect-database.js';
+import { ChdbNotInstalledError, ensureChdbInstalled, getChdbTypeGenerationClient, } from '../utils/chdb-client.js';
 import { hasEnvFile, hasGitignore } from '../utils/find-files.js';
 import { generateEnvTemplate, appendToEnv } from '../templates/env.js';
 import { generateClientTemplate } from '../templates/client.js';
@@ -14,6 +15,15 @@ import { appendToGitignore } from '../templates/gitignore.js';
 import { getTypeGenerator } from '../generators/index.js';
 import { generateDatasets } from '../generators/dataset-generator.js';
 import { installScaffoldDependencies } from '../utils/dependency-installer.js';
+function normalizeInitDatabase(database) {
+    if (!database || database === 'clickhouse') {
+        return 'clickhouse';
+    }
+    if (database === 'chdb') {
+        return 'chdb';
+    }
+    throw new Error(`Unsupported database "${database}". Use "clickhouse" or "chdb".`);
+}
 function normalizeInitStyle(style) {
     return style === 'datasets' ? 'datasets' : 'queries';
 }
@@ -33,6 +43,22 @@ function parseTableList(value) {
         .filter(Boolean);
     return parsed && parsed.length > 0 ? parsed : undefined;
 }
+function getChdbGitignoreEntry(chdbPath) {
+    if (!chdbPath || /[\0\r\n]/.test(chdbPath)) {
+        return undefined;
+    }
+    const cwd = path.resolve(process.cwd());
+    const relativePath = path.relative(cwd, path.resolve(cwd, chdbPath));
+    if (relativePath.length === 0 ||
+        relativePath === '..' ||
+        relativePath.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relativePath)) {
+        return undefined;
+    }
+    const normalizedPath = relativePath.split(path.sep).join('/');
+    const escapedPath = normalizedPath.replace(/[\\*?[\]]/g, '\\$&');
+    return `/${escapedPath}/`;
+}
 async function resolveConnectionConfig(options) {
     if (options.noInteractive) {
         const required = (keys) => {
@@ -52,6 +78,34 @@ async function resolveConnectionConfig(options) {
     }
     return promptClickHouseConnection();
 }
+async function testChdbConnection(chdbPath) {
+    const spinner = ora('Starting embedded chDB...').start();
+    try {
+        await ensureChdbInstalled();
+    }
+    catch (error) {
+        const isNotInstalled = error instanceof ChdbNotInstalledError;
+        spinner.fail(isNotInstalled ? 'chdb is not installed' : 'Embedded chDB failed to load');
+        logger.newline();
+        logger.error(error instanceof Error ? error.message : String(error));
+        logger.newline();
+        return { ok: false, reason: isNotInstalled ? 'not-installed' : 'engine-error' };
+    }
+    const isValid = await validateConnection('chdb', { chdbPath });
+    if (!isValid) {
+        spinner.fail('Embedded chDB failed to run a query');
+        logger.newline();
+        logger.info('Common issues:');
+        logger.indent('• Unsupported platform (chdb ships linux/macOS binaries; Windows needs WSL2)');
+        logger.indent(`• The session directory is locked by another process${chdbPath ? ` (${chdbPath})` : ''}`);
+        logger.newline();
+        return { ok: false, reason: 'engine-error' };
+    }
+    const tableCount = await getTableCount('chdb', { chdbPath });
+    spinner.succeed(`Embedded chDB ready (${chdbPath ? `${tableCount} tables in ${chdbPath}` : 'in-memory session'})`);
+    logger.newline();
+    return { ok: true };
+}
 async function testConnection(connectionConfig) {
     const spinner = ora('Testing connection...').start();
     process.env.CLICKHOUSE_URL = connectionConfig.host;
@@ -80,43 +134,58 @@ async function testConnection(connectionConfig) {
 }
 export async function initCommand(options = {}) {
     const noInteractive = options.noInteractive === true || options.interactive === false;
+    const database = normalizeInitDatabase(options.database);
     logger.newline();
     logger.header('Welcome to hypequery!');
-    logger.info("Let's set up your analytics layer.");
+    logger.info(database === 'chdb'
+        ? "Let's set up your analytics layer on embedded ClickHouse (chDB)."
+        : "Let's set up your analytics layer.");
     logger.newline();
     // Step 2: Get connection details
-    let connectionConfig = await resolveConnectionConfig(options);
+    let connectionConfig = null;
     let hasValidConnection = false;
-    // Handle user skipping connection details
-    if (!connectionConfig) {
-        logger.info('Skipping database connection for now.');
-        logger.newline();
-    }
-    else if (options.skipConnection) {
-        logger.info('Skipping database connection test (requested).');
-        logger.newline();
+    let chdbPath = options.chdbPath;
+    let chdbFailureReason;
+    if (database === 'chdb') {
+        // No server, no credentials — the only connection question is where the
+        // embedded session stores its data.
+        if (!chdbPath && !noInteractive) {
+            chdbPath = await promptChdbStorage();
+        }
     }
     else {
-        const { hasValidConnection: valid } = await testConnection(connectionConfig);
-        hasValidConnection = valid;
-        if (!hasValidConnection) {
-            if (noInteractive) {
-                throw new Error('Failed to connect to ClickHouse in non-interactive mode. Check your environment variables or use interactive setup.');
-            }
-            const retry = await promptRetry('Try again?');
-            if (retry) {
-                return initCommand(options);
-            }
-            const continueWithout = await promptContinueWithoutDb();
-            if (!continueWithout) {
-                logger.info('Setup cancelled');
-                process.exit(0);
-            }
+        connectionConfig = await resolveConnectionConfig(options);
+        // Handle user skipping connection details
+        if (!connectionConfig) {
+            logger.info('Skipping database connection for now.');
             logger.newline();
-            logger.info('Continuing without database connection.');
-            logger.info('You can configure the connection later in .env');
+        }
+        else if (options.skipConnection) {
+            logger.info('Skipping database connection test (requested).');
             logger.newline();
-            connectionConfig = null;
+        }
+        else {
+            const { hasValidConnection: valid } = await testConnection(connectionConfig);
+            hasValidConnection = valid;
+            if (!hasValidConnection) {
+                if (noInteractive) {
+                    throw new Error('Failed to connect to ClickHouse in non-interactive mode. Check your environment variables or use interactive setup.');
+                }
+                const retry = await promptRetry('Try again?');
+                if (retry) {
+                    return initCommand(options);
+                }
+                const continueWithout = await promptContinueWithoutDb();
+                if (!continueWithout) {
+                    logger.info('Setup cancelled');
+                    process.exit(0);
+                }
+                logger.newline();
+                logger.info('Continuing without database connection.');
+                logger.info('You can configure the connection later in .env');
+                logger.newline();
+                connectionConfig = null;
+            }
         }
     }
     // Step 4: Get output directory
@@ -166,6 +235,37 @@ export async function initCommand(options = {}) {
         }
         logger.newline();
     }
+    if (database === 'chdb') {
+        // All prompts and overwrite checks are complete, so installing packages
+        // here cannot leave a cancelled scaffold with unexpected dependencies.
+        await installScaffoldDependencies(style, 'chdb');
+        if (options.skipConnection) {
+            logger.info('Skipping embedded chDB test (requested).');
+            logger.newline();
+        }
+        else {
+            const chdbTest = await testChdbConnection(chdbPath);
+            hasValidConnection = chdbTest.ok;
+            if (!chdbTest.ok) {
+                chdbFailureReason = chdbTest.reason;
+            }
+            if (!hasValidConnection) {
+                if (noInteractive) {
+                    throw new Error(chdbFailureReason === 'not-installed'
+                        ? 'Embedded chDB failed to start in non-interactive mode. Install the chdb package and re-run.'
+                        : 'Embedded chDB failed to start in non-interactive mode. Resolve the engine error shown above and re-run.');
+                }
+                const continueWithout = await promptContinueWithoutDb();
+                if (!continueWithout) {
+                    logger.info('Setup cancelled');
+                    process.exit(0);
+                }
+                logger.newline();
+                logger.info('Continuing without a working embedded engine.');
+                logger.newline();
+            }
+        }
+    }
     // Step 6: Ask about example query (only if we have a valid connection)
     let generateExample = !options.noExample && hasValidConnection;
     let selectedTable = null;
@@ -173,7 +273,7 @@ export async function initCommand(options = {}) {
     if (generateExample && !noInteractive && hasValidConnection) {
         generateExample = await promptGenerateExample();
         if (generateExample) {
-            discoveredTables = await getTables('clickhouse');
+            discoveredTables = await getTables(database, { chdbPath });
             selectedTable = await promptTableSelection(discoveredTables);
             generateExample = selectedTable !== null;
         }
@@ -185,14 +285,19 @@ export async function initCommand(options = {}) {
         !options.allTables &&
         !datasetTables &&
         !noInteractive) {
-        discoveredTables ??= await getTables('clickhouse');
+        discoveredTables ??= await getTables(database, { chdbPath });
         datasetTables = await promptDatasetTableSelection(discoveredTables, selectedTable ? [selectedTable] : []);
     }
     logger.newline();
     // Step 7: Create directory
     await mkdir(resolvedOutputDir, { recursive: true });
-    // Step 8: Save credentials to .env (if we have connection config)
-    if (connectionConfig) {
+    // Step 8: Save credentials to .env (if we have connection config).
+    // Embedded chDB has no credentials — the storage path lives in client.ts —
+    // so the chdb scaffold writes no .env at all.
+    if (database === 'chdb') {
+        // nothing to persist
+    }
+    else if (connectionConfig) {
         const envPath = path.join(process.cwd(), '.env');
         const envExists = await hasEnvFile();
         if (envExists) {
@@ -226,8 +331,8 @@ export async function initCommand(options = {}) {
     if (hasValidConnection) {
         const typeSpinner = ora('Generating TypeScript types...').start();
         try {
-            const generator = getTypeGenerator('clickhouse');
-            await generator({ outputPath: schemaPath });
+            const generator = getTypeGenerator(database);
+            await generator({ outputPath: schemaPath, chdbPath });
             typeSpinner.succeed(`Generated TypeScript types (${path.relative(process.cwd(), schemaPath)})`);
         }
         catch (error) {
@@ -238,8 +343,11 @@ export async function initCommand(options = {}) {
     }
     else {
         // Create placeholder schema file
+        const regenerateHint = database === 'chdb'
+            ? "// Run 'npx hypequery generate --database chdb --chdb-path <dir>' after creating persistent tables"
+            : "// Run 'npx hypequery generate' after configuring your database connection";
         await writeFile(schemaPath, `// Generated by hypequery
-// Run 'npx hypequery generate' after configuring your database connection
+${regenerateHint}
 
 export interface IntrospectedSchema {
   // Your table types will appear here after generation
@@ -249,8 +357,8 @@ export interface IntrospectedSchema {
     }
     // Step 10: Create client.ts
     const clientPath = path.join(resolvedOutputDir, 'client.ts');
-    await writeFile(clientPath, generateClientTemplate());
-    logger.success(`Created ClickHouse client (${path.relative(process.cwd(), clientPath)})`);
+    await writeFile(clientPath, generateClientTemplate({ database, chdbPath }));
+    logger.success(`Created ${database === 'chdb' ? 'embedded chDB' : 'ClickHouse'} client (${path.relative(process.cwd(), clientPath)})`);
     // Step 11: Create API entrypoint
     let apiPath;
     let generatedAnyDatasets = false;
@@ -264,6 +372,9 @@ export interface IntrospectedSchema {
                 outputPath: datasetsPath,
                 includeTables: options.allTables ? undefined : datasetTables,
                 excludeTables: excludedDatasetTables,
+                ...(database === 'chdb'
+                    ? { client: getChdbTypeGenerationClient(chdbPath) }
+                    : {}),
             });
             generatedAnyDatasets = true;
             generatedSelectedDataset = selectedTable !== null && (options.allTables === true ||
@@ -295,20 +406,24 @@ export interface IntrospectedSchema {
     // Step 12: Update .gitignore
     const gitignorePath = path.join(process.cwd(), '.gitignore');
     const gitignoreExists = await hasGitignore();
+    const chdbGitignoreEntry = database === 'chdb'
+        ? getChdbGitignoreEntry(chdbPath)
+        : undefined;
+    const gitignoreEntries = chdbGitignoreEntry ? [chdbGitignoreEntry] : [];
     if (gitignoreExists) {
         const existingGitignore = await readFile(gitignorePath, 'utf-8');
-        const newGitignore = appendToGitignore(existingGitignore);
+        const newGitignore = appendToGitignore(existingGitignore, gitignoreEntries);
         if (newGitignore !== existingGitignore) {
             await writeFile(gitignorePath, newGitignore);
             logger.success('Updated .gitignore');
         }
     }
     else {
-        await writeFile(gitignorePath, appendToGitignore(''));
+        await writeFile(gitignorePath, appendToGitignore('', gitignoreEntries));
         logger.success('Created .gitignore');
     }
     // Step 13: Ensure required hypequery packages are installed
-    await installScaffoldDependencies(style);
+    await installScaffoldDependencies(style, database);
     // Step 14: Success message
     logger.newline();
     logger.header('Setup complete!');
@@ -342,6 +457,24 @@ export interface IntrospectedSchema {
             logger.newline();
         }
     }
+    else if (database === 'chdb') {
+        logger.info('Next steps:');
+        logger.newline();
+        // chdb is normally installed by the scaffold itself — only tell the user
+        // to install when that is actually what failed, not when an installed
+        // engine could not run (unsupported platform, locked session directory).
+        const firstStep = options.skipConnection
+            ? '1. Verify the embedded engine and create your tables'
+            : chdbFailureReason === 'engine-error'
+                ? '1. Resolve the engine error shown above'
+                : '1. Install the embedded engine: npm install chdb';
+        logger.indent(firstStep);
+        logger.indent(chdbPath
+            ? `2. Run: npx hypequery generate --database chdb --chdb-path ${chdbPath}`
+            : '2. Re-run init with --chdb-path <dir> if later generate commands must see your tables');
+        logger.indent('3. Run: npx hypequery dev          (to start dev server)');
+        logger.newline();
+    }
     else {
         logger.info('Next steps:');
         logger.newline();
@@ -350,6 +483,12 @@ export interface IntrospectedSchema {
         logger.indent('3. Run: npx hypequery dev          (to start dev server)');
         logger.newline();
     }
+    if (database === 'chdb' && hasValidConnection) {
+        logger.indent(chdbPath
+            ? `hypequery generate --database chdb --chdb-path ${chdbPath}   Refresh types after creating tables`
+            : 'In-memory chDB is process-local; use --chdb-path <dir> for later type generation');
+        logger.newline();
+    }
     logger.info('Docs: https://hypequery.com/docs');
     logger.newline();
 }

package/dist/generators/chdb.d.ts

@@ -0,0 +1,13 @@
+export interface ChdbGeneratorOptions {
+    outputPath: string;
+    includeTables?: string[];
+    excludeTables?: string[];
+    chdbPath?: string;
+}
+/**
+ * Same generator as ClickHouse — the introspection SQL (SHOW TABLES,
+ * DESCRIBE TABLE) is identical on the embedded engine — but the client seam
+ * is backed by a chDB session instead of an HTTP connection.
+ */
+export declare function generateChdbTypes(options: ChdbGeneratorOptions): Promise<void>;
+//# sourceMappingURL=chdb.d.ts.map

package/dist/generators/chdb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chdb.d.ts","sourceRoot":"","sources":["../../src/generators/chdb.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,iBAUpE"}

package/dist/generators/chdb.js

@@ -0,0 +1,17 @@
+import { generateTypes } from '@hypequery/clickhouse/cli';
+import { getChdbTypeGenerationClient } from '../utils/chdb-client.js';
+/**
+ * Same generator as ClickHouse — the introspection SQL (SHOW TABLES,
+ * DESCRIBE TABLE) is identical on the embedded engine — but the client seam
+ * is backed by a chDB session instead of an HTTP connection.
+ */
+export async function generateChdbTypes(options) {
+    const generatorOptions = {
+        client: getChdbTypeGenerationClient(options.chdbPath),
+        generatedBy: 'hypequery',
+        includeUsageExample: false,
+        ...(options.includeTables ? { includeTables: options.includeTables } : {}),
+        ...(options.excludeTables ? { excludeTables: options.excludeTables } : {}),
+    };
+    await generateTypes(options.outputPath, generatorOptions);
+}

package/dist/generators/dataset-generator.d.ts

@@ -4,10 +4,12 @@
  * Generates dataset DSL code from ClickHouse schema introspection.
  * This reduces quickstart friction by auto-scaffolding dataset definitions.
  */
+import type { TypeGenerationClickHouseClient } from '@hypequery/clickhouse/cli';
 export interface DatasetGeneratorOptions {
     outputPath: string;
     includeTables?: string[];
     excludeTables?: string[];
+    client?: TypeGenerationClickHouseClient;
 }
 /**
  * Generate dataset definitions from ClickHouse schema

package/dist/generators/dataset-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataset-generator.d.ts","sourceRoot":"","sources":["../../src/generators/dataset-generator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAuPD;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,iBAyDtE"}
+{"version":3,"file":"dataset-generator.d.ts","sourceRoot":"","sources":["../../src/generators/dataset-generator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,2BAA2B,CAAC;AAGhF,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,MAAM,CAAC,EAAE,8BAA8B,CAAC;CACzC;AAuPD;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,iBAyDtE"}

package/dist/generators/dataset-generator.js

@@ -199,7 +199,7 @@ ${configLines.join('\n')}
  * Generate dataset definitions from ClickHouse schema
  */
 export async function generateDatasets(options) {
-    const client = getClickHouseClient();
+    const client = options.client ?? getClickHouseClient();
     // Get all tables
     const tablesQuery = await client.query({
         query: 'SHOW TABLES',

package/dist/generators/index.d.ts

@@ -1,6 +1,7 @@
 import type { DatabaseType } from '../utils/detect-database.js';
 import { type ClickHouseGeneratorOptions } from './clickhouse.js';
-export type TypeGeneratorOptions = ClickHouseGeneratorOptions;
+import { type ChdbGeneratorOptions } from './chdb.js';
+export type TypeGeneratorOptions = ClickHouseGeneratorOptions & ChdbGeneratorOptions;
 type GeneratorFn = (options: TypeGeneratorOptions) => Promise<void>;
 export declare function getTypeGenerator(dbType: DatabaseType): GeneratorFn;
 export {};

package/dist/generators/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/generators/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAA2B,KAAK,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAE3F,MAAM,MAAM,oBAAoB,GAAG,0BAA0B,CAAC;AAE9D,KAAK,WAAW,GAAG,CAAC,OAAO,EAAE,oBAAoB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAMpE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,WAAW,CAYlE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/generators/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAA2B,KAAK,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAC3F,OAAO,EAAqB,KAAK,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAEzE,MAAM,MAAM,oBAAoB,GAAG,0BAA0B,GAAG,oBAAoB,CAAC;AAErF,KAAK,WAAW,GAAG,CAAC,OAAO,EAAE,oBAAoB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAOpE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,WAAW,CAYlE"}

package/dist/generators/index.js

@@ -1,6 +1,8 @@
 import { generateClickHouseTypes } from './clickhouse.js';
+import { generateChdbTypes } from './chdb.js';
 const generators = {
     clickhouse: generateClickHouseTypes,
+    chdb: generateChdbTypes,
 };
 export function getTypeGenerator(dbType) {
     const generator = generators[dbType];

package/dist/templates/client.d.ts

@@ -1,5 +1,10 @@
+export interface ClientTemplateOptions {
+    database?: 'clickhouse' | 'chdb';
+    /** On-disk chDB session directory; omit for an in-memory session. */
+    chdbPath?: string;
+}
 /**
- * Generate client.ts file for ClickHouse
+ * Generate client.ts file for ClickHouse (HTTP) or embedded chDB
  */
-export declare function generateClientTemplate(): string;
+export declare function generateClientTemplate(options?: ClientTemplateOptions): string;
 //# sourceMappingURL=client.d.ts.map

package/dist/templates/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/templates/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAW/C"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/templates/client.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC;IACjC,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,qBAA0B,GAAG,MAAM,CAiClF"}

package/dist/templates/client.js

@@ -1,7 +1,28 @@
 /**
- * Generate client.ts file for ClickHouse
+ * Generate client.ts file for ClickHouse (HTTP) or embedded chDB
  */
-export function generateClientTemplate() {
+export function generateClientTemplate(options = {}) {
+    if (options.database === 'chdb') {
+        // JSON.stringify produces a valid JS string literal for any path
+        // (quotes, backslashes) — raw interpolation would break the scaffold.
+        const sessionArg = options.chdbPath ? JSON.stringify(options.chdbPath) : '';
+        const safePathForComment = options.chdbPath?.replace(/[\r\n\u2028\u2029]/g, '') ?? '';
+        const storageComment = options.chdbPath
+            ? `// Embedded ClickHouse — data persists in ${safePathForComment}`
+            : '// Embedded ClickHouse — in-memory session (data is discarded on exit).\n// Pass a directory path to new Session(...) to persist between runs.';
+        return `import { createQueryBuilder } from '@hypequery/clickhouse';
+import { Session } from 'chdb';
+import { chdbAdapter } from 'chdb/hypequery';
+import type { IntrospectedSchema } from './schema.js';
+
+${storageComment}
+export const session = new Session(${sessionArg});
+
+export const db = createQueryBuilder<IntrospectedSchema>({
+  adapter: chdbAdapter({ session }),
+});
+`;
+    }
     return `import { createQueryBuilder } from '@hypequery/clickhouse';
 import type { IntrospectedSchema } from './schema.js';
 

package/dist/templates/gitignore.d.ts

@@ -9,5 +9,5 @@ export declare function hasHypequeryEntries(content: string): boolean;
 /**
  * Append hypequery entries to .gitignore
  */
-export declare function appendToGitignore(existingContent: string): string;
+export declare function appendToGitignore(existingContent: string, additionalEntries?: readonly string[]): string;
 //# sourceMappingURL=gitignore.d.ts.map

package/dist/templates/gitignore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gitignore.d.ts","sourceRoot":"","sources":["../../src/templates/gitignore.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,iBAAiB,0BAG7B,CAAC;AAEF;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAUjE"}
+{"version":3,"file":"gitignore.d.ts","sourceRoot":"","sources":["../../src/templates/gitignore.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,iBAAiB,0BAG7B,CAAC;AAQF;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,eAAe,EAAE,MAAM,EACvB,iBAAiB,GAAE,SAAS,MAAM,EAAO,GACxC,MAAM,CAuBR"}

package/dist/templates/gitignore.js

@@ -5,21 +5,35 @@ export const GITIGNORE_CONTENT = `
 # Hypequery
 .env
 `;
+function hasEntry(content, entry) {
+    return content
+        .split(/\r?\n/)
+        .some((line) => line.trim() === entry);
+}
 /**
  * Check if .gitignore already has hypequery entries
  */
 export function hasHypequeryEntries(content) {
-    return content.includes('# Hypequery') || content.includes('.env');
+    return hasEntry(content, '# Hypequery') || hasEntry(content, '.env');
 }
 /**
  * Append hypequery entries to .gitignore
  */
-export function appendToGitignore(existingContent) {
-    if (hasHypequeryEntries(existingContent)) {
+export function appendToGitignore(existingContent, additionalEntries = []) {
+    const entries = ['.env', ...additionalEntries];
+    const missingEntries = entries.filter((entry, index) => entry.length > 0 && entries.indexOf(entry) === index && !hasEntry(existingContent, entry));
+    if (missingEntries.length === 0) {
         return existingContent;
     }
-    if (!existingContent.endsWith('\n')) {
-        existingContent += '\n';
+    let updatedContent = existingContent;
+    if (updatedContent.length > 0 && !updatedContent.endsWith('\n')) {
+        updatedContent += '\n';
+    }
+    if (!hasHypequeryEntries(existingContent)) {
+        if (updatedContent.length > 0 && !updatedContent.endsWith('\n\n')) {
+            updatedContent += '\n';
+        }
+        updatedContent += '# Hypequery\n';
     }
-    return existingContent + GITIGNORE_CONTENT;
+    return `${updatedContent}${missingEntries.join('\n')}\n`;
 }

package/dist/utils/chdb-client.d.ts

@@ -0,0 +1,36 @@
+import type { TypeGenerationClickHouseClient } from '@hypequery/clickhouse/cli';
+interface ChdbSession {
+    queryAsync(sql: string, options?: {
+        format?: string;
+    }): Promise<{
+        text(): string;
+    }>;
+    close(): void;
+}
+export declare class ChdbNotInstalledError extends Error {
+    readonly code = "CHDB_NOT_INSTALLED";
+    constructor();
+}
+/**
+ * Get (or create) the embedded chDB session. `path` selects the on-disk
+ * database directory; omit it for an ephemeral in-memory session. The session
+ * is cached per path — chDB allows one active data directory per process.
+ */
+export declare function getChdbSession(dbPath?: string): Promise<ChdbSession>;
+/**
+ * The type generator only needs `query({ query, format }) → { json() }` —
+ * the `TypeGenerationClickHouseClient` seam — so the embedded session can
+ * stand in for an HTTP client without touching the generator itself.
+ */
+export declare function getChdbTypeGenerationClient(dbPath?: string): TypeGenerationClickHouseClient;
+/**
+ * Throws the actionable install-hint error when `chdb` is missing. Init calls
+ * this before the connection test so "package not installed" surfaces as its
+ * own message instead of a generic connection failure.
+ */
+export declare function ensureChdbInstalled(): Promise<void>;
+export declare function validateChdb(dbPath?: string): Promise<boolean>;
+export declare function getChdbTables(dbPath?: string): Promise<string[]>;
+export declare function closeChdbSessionForTesting(): Promise<void>;
+export {};
+//# sourceMappingURL=chdb-client.d.ts.map

package/dist/utils/chdb-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chdb-client.d.ts","sourceRoot":"","sources":["../../src/utils/chdb-client.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,2BAA2B,CAAC;AAYhF,UAAU,WAAW;IACnB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,IAAI,IAAI,MAAM,CAAA;KAAE,CAAC,CAAC;IACpF,KAAK,IAAI,IAAI,CAAC;CACf;AAKD,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,wBAAwB;;CAQtC;AA6CD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAY1E;AAYD;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,8BAA8B,CAQ3F;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAEzD;AAED,wBAAsB,YAAY,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOpE;AAED,wBAAsB,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAOtE;AAED,wBAAsB,0BAA0B,kBAM/C"}