@hypequery/cli 1.22.0 → 1.24.0

package/dist/commands/init.js

@@ -1,3 +1,9 @@
+import { countBucket } from '../utils/telemetry/buckets.js';
+import { normalizeInitDatabase, normalizeInitStyle, normalizeAuthMode, parseTableList } from '../utils/init-options.js';
+import { getChdbGitignoreEntry } from '../utils/chdb-gitignore-entry.js';
+import { InitFunnel } from '../utils/telemetry/init-funnel.js';
+import { exitWith } from '../utils/command-exit.js';
+import { telemetryErrorCode } from '../utils/telemetry/error-code.js';
 import { mkdir, writeFile, readFile, access } from 'node:fs/promises';
 import path from 'node:path';
 import ora from 'ora';
@@ -19,50 +25,6 @@ import { generateDatasets } from '../generators/dataset-generator.js';
 import { installScaffoldDependencies } from '../utils/dependency-installer.js';
 import { logDatasetGenerationWarnings } from '../utils/dataset-generation-warnings.js';
 import { formatRegenerateDatasetsCommand } from '../utils/regenerate-datasets-command.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';
-}
-function normalizeAuthMode(auth) {
-    if (!auth || auth === 'none') {
-        return 'none';
-    }
-    if (auth === 'context') {
-        return 'context';
-    }
-    throw new Error(`Unsupported auth mode "${auth}". Use "none" or "context".`);
-}
-function parseTableList(value) {
-    const parsed = value
-        ?.split(',')
-        .map((table) => table.trim())
-        .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) => {
@@ -117,7 +79,7 @@ async function testChdbConnection(chdbPath) {
     const tableCount = await getTableCount('chdb', { chdbPath });
     spinner.succeed(`Embedded chDB ready (${chdbPath ? `${tableCount} tables in ${chdbPath}` : 'in-memory session'})`);
     logger.newline();
-    return { ok: true };
+    return { ok: true, tableCount };
 }
 async function testConnection(connectionConfig) {
     const spinner = ora('Testing connection...').start();
@@ -146,19 +108,40 @@ async function testConnection(connectionConfig) {
     return { hasValidConnection: true, tableCount };
 }
 export async function initCommand(options = {}) {
+    const funnel = new InitFunnel({
+        interactive: !(options.noInteractive === true || options.interactive === false),
+        force: options.force === true,
+        skip_connection: options.skipConnection === true,
+    });
+    try {
+        await runInit(options, funnel);
+    }
+    catch (error) {
+        funnel.fail(error);
+        throw error;
+    }
+}
+async function runInit(options, funnel) {
     const noInteractive = options.noInteractive === true || options.interactive === false;
     logger.newline();
     logger.header('Welcome to hypequery!');
-    if (!noInteractive && !(await hasProjectPackageJson())) {
+    const packageJsonPresent = await hasProjectPackageJson();
+    funnel.update({ package_json_present: packageJsonPresent });
+    if (!noInteractive && !packageJsonPresent) {
         logger.warn(`package.json not found in ${process.cwd()}`);
         const shouldContinue = await confirmWithoutPackageJson(process.cwd());
         if (!shouldContinue) {
             logger.info('Setup cancelled. Run init from your project directory.');
+            funnel.cancel();
             return;
         }
         logger.newline();
     }
+    funnel.attempt('database_selected');
     const database = normalizeInitDatabase(options.database ?? (noInteractive ? undefined : await promptInitDatabase()));
+    funnel.update({ database });
+    funnel.reach('database_selected');
+    funnel.attempt('connection_tested');
     logger.info(database === 'chdb'
         ? "Let's set up your analytics layer on embedded ClickHouse (chDB)."
         : "Let's set up your analytics layer.");
@@ -179,28 +162,31 @@ export async function initCommand(options = {}) {
         connectionConfig = await resolveConnectionConfig(options);
         // Handle user skipping connection details
         if (!connectionConfig) {
+            funnel.update({ connection_result: 'skipped' });
             logger.info('Skipping database connection for now.');
             logger.newline();
         }
         else if (options.skipConnection) {
+            funnel.update({ connection_result: 'skipped' });
             logger.info('Skipping database connection test (requested).');
             logger.newline();
         }
         else {
-            const { hasValidConnection: valid } = await testConnection(connectionConfig);
+            const { hasValidConnection: valid, tableCount } = await testConnection(connectionConfig);
             hasValidConnection = valid;
+            funnel.update({ connection_result: valid ? 'ok' : 'failed', ...(valid ? { table_count_bucket: countBucket(tableCount) } : {}) });
             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, database });
+                    return runInit({ ...options, database }, funnel);
                 }
                 const continueWithout = await promptContinueWithoutDb();
                 if (!continueWithout) {
                     logger.info('Setup cancelled');
-                    process.exit(0);
+                    exitWith(0, 'cancelled');
                 }
                 logger.newline();
                 logger.info('Continuing without database connection.');
@@ -210,6 +196,9 @@ export async function initCommand(options = {}) {
             }
         }
     }
+    if (database === 'clickhouse')
+        funnel.reach('connection_tested');
+    funnel.attempt('style_selected');
     // Step 4: Get output directory
     let outputDir = options.path;
     if (!outputDir && !noInteractive) {
@@ -219,6 +208,13 @@ export async function initCommand(options = {}) {
         outputDir = 'analytics';
     }
     const resolvedOutputDir = path.resolve(process.cwd(), outputDir);
+    try {
+        await access(resolvedOutputDir);
+        funnel.update({ analytics_directory_present: true });
+    }
+    catch {
+        funnel.update({ analytics_directory_present: false });
+    }
     let style = normalizeInitStyle(options.style);
     if (!options.style && !noInteractive) {
         style = await promptInitStyle();
@@ -227,6 +223,9 @@ export async function initCommand(options = {}) {
     if (!options.auth && !noInteractive) {
         auth = normalizeAuthMode(await promptInitAuthMode());
     }
+    funnel.update({ style, auth });
+    funnel.reach('style_selected');
+    funnel.attempt('files_written');
     // Step 5: Check for existing files
     const filesToCreate = [
         path.join(resolvedOutputDir, 'client.ts'),
@@ -257,21 +256,25 @@ export async function initCommand(options = {}) {
         const shouldOverwrite = noInteractive ? false : await confirmOverwrite(existingFiles);
         if (!shouldOverwrite) {
             logger.info('Setup cancelled');
-            process.exit(0);
+            exitWith(0, 'cancelled');
         }
         logger.newline();
     }
     if (database === 'chdb') {
         // All prompts and overwrite checks are complete, so installing packages
         // here cannot leave a cancelled scaffold with unexpected dependencies.
+        funnel.attempt('dependencies_installed');
         await installScaffoldDependencies(style, 'chdb');
+        funnel.attempt('connection_tested');
         if (options.skipConnection) {
+            funnel.update({ connection_result: 'skipped' });
             logger.info('Skipping embedded chDB test (requested).');
             logger.newline();
         }
         else {
             const chdbTest = await testChdbConnection(chdbPath);
             hasValidConnection = chdbTest.ok;
+            funnel.update({ connection_result: chdbTest.ok ? 'ok' : 'failed', ...(chdbTest.ok ? { table_count_bucket: countBucket(chdbTest.tableCount) } : { chdb_failure_reason: chdbTest.reason === 'not-installed' ? 'not_installed' : 'engine_error' }) });
             if (!chdbTest.ok) {
                 chdbFailureReason = chdbTest.reason;
             }
@@ -284,7 +287,7 @@ export async function initCommand(options = {}) {
                 const continueWithout = await promptContinueWithoutDb();
                 if (!continueWithout) {
                     logger.info('Setup cancelled');
-                    process.exit(0);
+                    exitWith(0, 'cancelled');
                 }
                 logger.newline();
                 logger.info('Continuing without a working embedded engine.');
@@ -292,8 +295,11 @@ export async function initCommand(options = {}) {
             }
         }
     }
+    if (database === 'chdb')
+        funnel.reach('connection_tested');
+    funnel.attempt('files_written');
     // Step 6: Ask about example query (only if we have a valid connection)
-    let generateExample = !options.noExample && hasValidConnection;
+    let generateExample = !(options.noExample || options.example === false) && hasValidConnection;
     let selectedTable = null;
     let discoveredTables = null;
     if (generateExample && !noInteractive && hasValidConnection) {
@@ -304,6 +310,8 @@ export async function initCommand(options = {}) {
             generateExample = selectedTable !== null;
         }
     }
+    // Undefined when no selection was made: non-interactive runs then write a placeholder.
+    let tableSelection = options.allTables ? 'all' : options.tables ? 'list' : options.excludeTables ? 'exclude' : undefined;
     let datasetTables = parseTableList(options.tables);
     const excludedDatasetTables = parseTableList(options.excludeTables);
     if (style === 'datasets' &&
@@ -312,16 +320,18 @@ export async function initCommand(options = {}) {
         !datasetTables &&
         !noInteractive) {
         discoveredTables ??= await getTables(database, { chdbPath });
+        tableSelection = 'prompt';
         datasetTables = await promptDatasetTableSelection(discoveredTables, selectedTable ? [selectedTable] : []);
     }
     logger.newline();
+    funnel.update({ example: generateExample, ...(style === 'datasets' && tableSelection ? { table_selection: tableSelection } : {}) });
     // Step 7: Create directory
     await mkdir(resolvedOutputDir, { recursive: true });
     // 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
+        funnel.update({ env_file: 'skipped' });
     }
     else if (connectionConfig) {
         const envPath = path.join(process.cwd(), '.env');
@@ -330,10 +340,12 @@ export async function initCommand(options = {}) {
             const existingEnv = await readFile(envPath, 'utf-8');
             const newEnv = appendToEnv(existingEnv, generateEnvTemplate(connectionConfig));
             await writeFile(envPath, newEnv);
+            funnel.update({ env_file: newEnv === existingEnv ? 'unchanged' : 'updated' });
             logger.success('Updated .env');
         }
         else {
             await writeFile(envPath, generateEnvTemplate(connectionConfig));
+            funnel.update({ env_file: 'created' });
             logger.success('Created .env');
         }
     }
@@ -347,8 +359,10 @@ export async function initCommand(options = {}) {
             username: 'YOUR_USERNAME',
             password: 'YOUR_PASSWORD',
         };
+        funnel.update({ env_file: 'unchanged' });
         if (!envExists) {
             await writeFile(envPath, generateEnvTemplate(placeholderConfig));
+            funnel.update({ env_file: 'created' });
             logger.success('Created .env (configure your credentials)');
         }
     }
@@ -364,7 +378,7 @@ export async function initCommand(options = {}) {
         catch (error) {
             typeSpinner.fail('Failed to generate types');
             logger.error(error instanceof Error ? error.message : String(error));
-            process.exit(1);
+            exitWith(1, 'failure', telemetryErrorCode(error));
         }
     }
     else {
@@ -406,6 +420,8 @@ export interface IntrospectedSchema {
                     ? { client: getChdbTypeGenerationClient(chdbPath) }
                     : {}),
             });
+            if (generated)
+                funnel.update({ datasets_generated_bucket: countBucket(generated.tables.length) });
             logDatasetGenerationWarnings(generated?.warnings);
             generatedAnyDatasets = true;
             generatedSelectedDataset = selectedTable !== null && (options.allTables === true ||
@@ -413,6 +429,7 @@ export interface IntrospectedSchema {
         }
         else {
             await writeFile(datasetsPath, generateDatasetsPlaceholderTemplate({ auth }));
+            funnel.update({ datasets_generated_bucket: '0' });
             if (hasValidConnection) {
                 logger.info('Skipped dataset generation. Run `'
                     + formatRegenerateDatasetsCommand({ outputDir, auth, tables: 'table1,table2' })
@@ -443,23 +460,30 @@ export interface IntrospectedSchema {
     const gitignorePath = path.join(process.cwd(), '.gitignore');
     const gitignoreExists = await hasGitignore();
     const chdbGitignoreEntry = database === 'chdb'
-        ? getChdbGitignoreEntry(chdbPath)
+        ? getChdbGitignoreEntry(chdbPath, process.cwd())
         : undefined;
     const gitignoreEntries = chdbGitignoreEntry ? [chdbGitignoreEntry] : [];
     if (gitignoreExists) {
         const existingGitignore = await readFile(gitignorePath, 'utf-8');
         const newGitignore = appendToGitignore(existingGitignore, gitignoreEntries);
+        funnel.update({ gitignore: 'unchanged' });
         if (newGitignore !== existingGitignore) {
             await writeFile(gitignorePath, newGitignore);
+            funnel.update({ gitignore: 'updated' });
             logger.success('Updated .gitignore');
         }
     }
     else {
         await writeFile(gitignorePath, appendToGitignore('', gitignoreEntries));
+        funnel.update({ gitignore: 'created' });
         logger.success('Created .gitignore');
     }
+    funnel.reach('files_written');
+    funnel.attempt('dependencies_installed');
     // Step 13: Ensure required hypequery packages are installed
     await installScaffoldDependencies(style, database);
+    funnel.reach('dependencies_installed');
+    funnel.attempt('completed');
     // Step 14: Success message
     logger.newline();
     logger.header('Setup complete!');
@@ -525,6 +549,7 @@ export interface IntrospectedSchema {
             : 'In-memory chDB is process-local; use --chdb-path <dir> for later type generation');
         logger.newline();
     }
+    funnel.reach('completed');
     logger.info('Docs: https://hypequery.com/docs');
     logger.newline();
 }

package/dist/commands/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/commands/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAQvF,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAEnF,MAAM,WAAW,UAAU;IACzB,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qFAAqF;IACrF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7C,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE;QACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,SAAS,EAAE,OAAO,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAClC,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACjC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAC/E,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;CACpD;AAoED,wBAAsB,UAAU,CAC9B,IAAI,CAAC,EAAE,MAAM,EACb,OAAO,GAAE,UAAe,EACxB,YAAY,GAAE,eAAoB,GACjC,OAAO,CAAC,IAAI,CAAC,CAkEf"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/commands/mcp.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AASvF,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAMnF,MAAM,WAAW,UAAU;IACzB,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qFAAqF;IACrF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7C,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE;QACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,SAAS,EAAE,OAAO,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAClC,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACjC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAC/E,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;CACpD;AAoED,wBAAsB,UAAU,CAC9B,IAAI,CAAC,EAAE,MAAM,EACb,OAAO,GAAE,UAAe,EACxB,YAAY,GAAE,eAAoB,GACjC,OAAO,CAAC,IAAI,CAAC,CA0Ef"}

package/dist/commands/mcp.js

@@ -1,12 +1,18 @@
+import { exitWith } from '../utils/command-exit.js';
 import { runMcpUntilSignal } from '../utils/mcp-lifecycle.js';
 import { routeConsoleOutputToStderr } from '../utils/mcp-console.js';
 import { readServeMcpSource, tenantScopedDatasets } from '../utils/mcp-source.js';
 import path from 'node:path';
 import { findApiFileForPath, findQueriesFile } from '../utils/find-files.js';
 import { loadApiModule } from '../utils/load-api.js';
+import { importFromProject } from '../utils/project-root.js';
 import { logger } from '../utils/logger.js';
 import { MCP_API_KEY_VARIABLE } from '../utils/hosted-endpoints.js';
 import { checkRemoteMcp } from '../utils/mcp-remote-check.js';
+import { McpSession } from '../utils/telemetry/mcp-session.js';
+import { countBucket } from '../utils/telemetry/buckets.js';
+import { entryType } from '../utils/telemetry/session-config.js';
+import { updateCommandTelemetry, setCommandTelemetryError } from '../utils/telemetry/command-context.js';
 function fail(message, hints = []) {
     logger.error(message);
     if (hints.length > 0) {
@@ -15,7 +21,7 @@ function fail(message, hints = []) {
             logger.indent(hint);
     }
     logger.newline();
-    process.exit(1);
+    exitWith(1, 'failure', 'validation_failed');
 }
 /** `--self-test --url`: initialize and list tools against a hosted endpoint. */
 async function remoteSelfTest(url, dependencies) {
@@ -48,7 +54,7 @@ function entrypointNotFound() {
     logger.info('Or specify the file explicitly:');
     logger.indent('hypequery mcp ./path/to/api.ts');
     logger.newline();
-    process.exit(1);
+    exitWith(1, 'failure', 'entrypoint_not_found');
 }
 function noDatasets(file) {
     logger.error(`${path.relative(process.cwd(), file)} does not register any datasets`);
@@ -56,7 +62,7 @@ function noDatasets(file) {
     logger.info('MCP exposes datasets and named metrics, so add them to defineServe:');
     logger.indent('defineServe({ queryBuilder: db, datasets: { orders: Orders } })');
     logger.newline();
-    process.exit(1);
+    exitWith(1, 'failure', 'no_datasets');
 }
 async function resolveEntrypoint(file, options) {
     const resolved = file
@@ -70,6 +76,8 @@ function resolveSource(api, file) {
     return readServeMcpSource(api) ?? noDatasets(file);
 }
 export async function mcpCommand(file, options = {}, dependencies = {}) {
+    const telemetry = new McpSession();
+    updateCommandTelemetry('mcp', { mode: options.selfTest ? 'self_test' : 'serve', hosted: !!options.url, tenant_used: !!options.tenant });
     if (options.url && !options.selfTest) {
         fail('--url is only used with --self-test.', [
             'MCP clients connect to the hosted endpoint directly; this command serves a local project.',
@@ -83,12 +91,21 @@ export async function mcpCommand(file, options = {}, dependencies = {}) {
         }
         const entrypoint = await resolveEntrypoint(file, options);
         const loadApi = dependencies.loadApi ?? loadApiModule;
-        const source = resolveSource(await loadApi(entrypoint), entrypoint);
+        let api;
+        try {
+            api = await loadApi(entrypoint);
+        }
+        catch (error) {
+            setCommandTelemetryError('load_error');
+            throw error;
+        }
+        const source = resolveSource(api, entrypoint);
         const datasets = source.datasets;
         const names = Object.keys(datasets).sort();
         if (names.length === 0)
             noDatasets(entrypoint);
         const scoped = tenantScopedDatasets(datasets);
+        updateCommandTelemetry('mcp', { dataset_count_bucket: countBucket(names.length), tenant_dataset_count_bucket: countBucket(scoped.length) });
         if (scoped.length > 0 && !options.tenant) {
             // Fail closed rather than serving a tenant-scoped dataset unscoped.
             logger.error(`--tenant is required for tenant-scoped datasets: ${scoped.join(', ')}`);
@@ -96,14 +113,14 @@ export async function mcpCommand(file, options = {}, dependencies = {}) {
             logger.info('MCP has no request to resolve a tenant from, so it must be given one:');
             logger.indent('hypequery mcp --tenant acme');
             logger.newline();
-            process.exit(1);
+            exitWith(1, 'failure', 'tenant_required');
         }
         const analytics = source.resolveAnalytics();
         if (options.selfTest) {
             // Serving needs the optional `@hypequery/mcp` peer. Without this check
             // the self-test passed and the real command then failed on import.
             try {
-                await (dependencies.loadMcp ?? (() => import('@hypequery/mcp')))();
+                await (dependencies.loadMcp ?? (() => loadMcpPackage(entrypoint)))();
             }
             catch {
                 fail('@hypequery/mcp is not installed, so this project cannot be served over MCP.', [
@@ -119,13 +136,15 @@ export async function mcpCommand(file, options = {}, dependencies = {}) {
             logger.info('The entrypoint is ready to serve over MCP.');
             return;
         }
-        const start = dependencies.start ?? defaultStart;
+        const start = dependencies.start ?? ((config) => defaultStart(entrypoint, config, telemetry));
         await runMcpUntilSignal(async () => {
             const server = await start({
                 datasets,
                 analytics,
                 ...(options.tenant ? { tenantId: options.tenant } : {}),
             });
+            telemetry.start({ entry_type: entryType(entrypoint, file), mode: 'serve', dataset_count_bucket: countBucket(names.length),
+                tenant_used: !!options.tenant, tenant_dataset_count_bucket: countBucket(scoped.length) });
             process.stderr.write(`hypequery MCP serving ${names.length} dataset(s): ${names.join(', ')}\n`);
             return server;
         });
@@ -134,9 +153,27 @@ export async function mcpCommand(file, options = {}, dependencies = {}) {
         restoreConsole();
     }
 }
-async function defaultStart(config) {
+/**
+ * Prefers the project's own `@hypequery/mcp`, so `npx -y @hypequery/cli mcp`
+ * run from another directory still finds the optional peer.
+ */
+function loadMcpPackage(entrypoint) {
+    return importFromProject('@hypequery/mcp', entrypoint, () => import('@hypequery/mcp'));
+}
+async function defaultStart(entrypoint, config, telemetry) {
     // Imported lazily so `--self-test` and the argument errors above do not pay
     // for the MCP SDK, and so the CLI still loads when it is not installed.
-    const { startStdioMCPServer } = await import('@hypequery/mcp');
-    return startStdioMCPServer(config);
+    // The project's own copy, so a client launching from another directory
+    // still finds the optional peer; the executor stays telemetry-instrumented.
+    const { createMCPExecutor, createMCPProtocolServer, connectMCPServerStdio } = await loadMcpPackage(entrypoint);
+    const executor = createMCPExecutor(config);
+    const server = createMCPProtocolServer({ executor: telemetry.instrument(executor) });
+    try {
+        await connectMCPServerStdio(server);
+    }
+    catch (error) {
+        await server.close().catch(() => undefined);
+        throw error;
+    }
+    return server;
 }

package/dist/commands/telemetry.d.ts

@@ -0,0 +1,3 @@
+import { type TelemetryResolutionOptions } from '../utils/telemetry/opt-out.js';
+export declare function telemetryCommand(action?: string, options?: TelemetryResolutionOptions): Promise<void>;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/commands/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/commands/telemetry.ts"],"names":[],"mappings":"AAEA,OAAO,EAAyB,KAAK,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAEvG,wBAAsB,gBAAgB,CACpC,MAAM,SAAW,EACjB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CAef"}

package/dist/commands/telemetry.js

@@ -0,0 +1,19 @@
+import { TelemetryConfigStore } from '../utils/telemetry/config-store.js';
+import { TELEMETRY_DOCS_URL } from '../utils/telemetry/config-schema.js';
+import { resolveTelemetryState } from '../utils/telemetry/opt-out.js';
+export async function telemetryCommand(action = 'status', options = {}) {
+    if (!['status', 'enable', 'disable'].includes(action)) {
+        throw new Error('Usage: hypequery telemetry [status|enable|disable]');
+    }
+    if (action !== 'status') {
+        const config = await new TelemetryConfigStore(options).setEnabled(action === 'enable');
+        if (!config) {
+            throw new Error('Could not save telemetry settings. To disable for this run, set HYPEQUERY_TELEMETRY_DISABLED=1 or DO_NOT_TRACK=1, or pass --no-telemetry.');
+        }
+        console.log(`Telemetry ${config.enabled ? 'enabled' : 'disabled'} in saved settings.`);
+    }
+    const state = await resolveTelemetryState(options);
+    console.log(`Telemetry: ${state.enabled ? 'enabled' : 'disabled'} (source: ${state.source})`);
+    console.log(`Install ID: ${state.config?.install_id ?? 'unavailable'}`);
+    console.log(`Learn more: ${TELEMETRY_DOCS_URL}`);
+}

package/dist/generators/chdb.d.ts

@@ -1,8 +1,11 @@
+import { type GenerateTypesOptions } from '../typegen/index.js';
 export interface ChdbGeneratorOptions {
     outputPath: string;
     includeTables?: string[];
     excludeTables?: string[];
     chdbPath?: string;
+    onColumn?: GenerateTypesOptions['onColumn'];
+    onUnsupportedType?: GenerateTypesOptions['onUnsupportedType'];
 }
 /**
  * Same generator as ClickHouse — the introspection SQL (SHOW TABLES,

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

@@ -1 +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,qBAUpE"}
+{"version":3,"file":"chdb.d.ts","sourceRoot":"","sources":["../../src/generators/chdb.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAG/E,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;IAClB,QAAQ,CAAC,EAAE,oBAAoB,CAAC,UAAU,CAAC,CAAC;IAC5C,iBAAiB,CAAC,EAAE,oBAAoB,CAAC,mBAAmB,CAAC,CAAC;CAC/D;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,qBAYpE"}

package/dist/generators/chdb.js

@@ -10,6 +10,8 @@ export async function generateChdbTypes(options) {
         client: getChdbTypeGenerationClient(options.chdbPath),
         generatedBy: 'hypequery',
         includeUsageExample: false,
+        ...(options.onColumn ? { onColumn: options.onColumn } : {}),
+        ...(options.onUnsupportedType ? { onUnsupportedType: options.onUnsupportedType } : {}),
         ...(options.includeTables ? { includeTables: options.includeTables } : {}),
         ...(options.excludeTables ? { excludeTables: options.excludeTables } : {}),
     };

package/dist/generators/clickhouse.d.ts

@@ -1,8 +1,10 @@
-import { clickhouseToTsType } from '../typegen/index.js';
+import { clickhouseToTsType, type GenerateTypesOptions } from '../typegen/index.js';
 export interface ClickHouseGeneratorOptions {
     outputPath: string;
     includeTables?: string[];
     excludeTables?: string[];
+    onColumn?: GenerateTypesOptions['onColumn'];
+    onUnsupportedType?: GenerateTypesOptions['onUnsupportedType'];
 }
 export { clickhouseToTsType };
 export declare function generateClickHouseTypes(options: ClickHouseGeneratorOptions): Promise<string[]>;

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

@@ -1 +1 @@
-{"version":3,"file":"clickhouse.d.ts","sourceRoot":"","sources":["../../src/generators/clickhouse.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAGnB,MAAM,qBAAqB,CAAC;AAG7B,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAE9B,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,0BAA0B,qBAUhF"}
+{"version":3,"file":"clickhouse.d.ts","sourceRoot":"","sources":["../../src/generators/clickhouse.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAElB,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAG7B,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,oBAAoB,CAAC,UAAU,CAAC,CAAC;IAC5C,iBAAiB,CAAC,EAAE,oBAAoB,CAAC,mBAAmB,CAAC,CAAC;CAC/D;AAED,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAE9B,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,0BAA0B,qBAYhF"}

package/dist/generators/clickhouse.js

@@ -6,6 +6,8 @@ export async function generateClickHouseTypes(options) {
         client: getClickHouseClient(),
         generatedBy: 'hypequery',
         includeUsageExample: false,
+        ...(options.onColumn ? { onColumn: options.onColumn } : {}),
+        ...(options.onUnsupportedType ? { onUnsupportedType: options.onUnsupportedType } : {}),
         ...(options.includeTables ? { includeTables: options.includeTables } : {}),
         ...(options.excludeTables ? { excludeTables: options.excludeTables } : {}),
     };

package/dist/typegen/generate-types.d.ts

@@ -33,6 +33,9 @@ export interface GenerateTypesOptions {
     generatedBy?: string;
     /** Append the historical usage-example comment block. */
     includeUsageExample?: boolean;
+    /** Optional aggregate-observation hooks; errors never affect generation. */
+    onColumn?: () => void;
+    onUnsupportedType?: (type: string) => void;
 }
 /**
  * Generates the TypeScript type definition source from a ClickHouse client.

package/dist/typegen/generate-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-types.d.ts","sourceRoot":"","sources":["../../src/typegen/generate-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH;;;GAGG;AACH,MAAM,WAAW,8BAA8B;IAC7C,KAAK,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,aAAa,CAAA;KAAE,GAAG,OAAO,CAAC;QAChE,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;KAChD,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,oBAAoB;IACnC,6EAA6E;IAC7E,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,qCAAqC;IACrC,MAAM,EAAE,8BAA8B,CAAC;IACvC,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AA0HD;;GAEG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,8BAA8B,EACtC,OAAO,GAAE,IAAI,CAAC,oBAAoB,EAAE,QAAQ,CAAM,GACjD,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,MAAM,EAAE,CAAC,CAYnB"}
+{"version":3,"file":"generate-types.d.ts","sourceRoot":"","sources":["../../src/typegen/generate-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH;;;GAGG;AACH,MAAM,WAAW,8BAA8B;IAC7C,KAAK,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,aAAa,CAAA;KAAE,GAAG,OAAO,CAAC;QAChE,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;KAChD,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,oBAAoB;IACnC,6EAA6E;IAC7E,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,qCAAqC;IACrC,MAAM,EAAE,8BAA8B,CAAC;IACvC,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C;AA2HD;;GAEG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,8BAA8B,EACtC,OAAO,GAAE,IAAI,CAAC,oBAAoB,EAAE,QAAQ,CAAM,GACjD,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,MAAM,EAAE,CAAC,CAYnB"}

package/dist/typegen/generate-types.js

@@ -72,7 +72,11 @@ export interface IntrospectedSchema {`;
         const columns = await describeTable(client, table.name);
         typeDefinitions += `export interface ${capitalizeFirstLetter(table.name)}Record {`;
         for (const column of columns) {
-            const tsType = clickhouseToTsType(column.type);
+            try {
+                options.onColumn?.();
+            }
+            catch { /* Preserve type output. */ }
+            const tsType = clickhouseToTsType(column.type, options.onUnsupportedType);
             typeDefinitions += `\n  '${column.name}': ${tsType};`;
         }
         typeDefinitions += '\n}\n\n';

package/dist/typegen/type-parsing.d.ts

@@ -2,5 +2,5 @@
  * Converts a ClickHouse type string, as returned by `DESCRIBE TABLE`, into the
  * equivalent TypeScript type string.
  */
-export declare const clickhouseToTsType: (type: string) => string;
+export declare const clickhouseToTsType: (type: string, onUnsupported?: (type: string) => void) => string;
 //# sourceMappingURL=type-parsing.d.ts.map

package/dist/typegen/type-parsing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"type-parsing.d.ts","sourceRoot":"","sources":["../../src/typegen/type-parsing.ts"],"names":[],"mappings":"AAwLA;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,KAAG,MA6CjD,CAAC"}
+{"version":3,"file":"type-parsing.d.ts","sourceRoot":"","sources":["../../src/typegen/type-parsing.ts"],"names":[],"mappings":"AAwLA;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,EAAE,gBAAgB,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,KAAG,MA8CzF,CAAC"}