@hypequery/cli 1.22.0 → 1.24.0

package/dist/utils/telemetry/dev-session.js

@@ -0,0 +1,25 @@
+import { countBucket } from './buckets.js';
+import { startCommandSession } from './command-context.js';
+import { telemetryErrorCode } from './error-code.js';
+import { devSessionConfig } from './session-config.js';
+/** Counters only: no retained API, reload paths, errors, queries, or requests. */
+export class DevSession {
+    reloads = 0;
+    reloadErrors = 0;
+    failures = {};
+    start(resolved, explicit, options) {
+        startCommandSession('dev', devSessionConfig(resolved, explicit, options), () => this.snapshot());
+    }
+    reload() { this.reloads++; }
+    reloadFailed() { this.reloadErrors++; }
+    loadFailed(error) {
+        const code = telemetryErrorCode(error);
+        const stable = code === 'unknown' ? 'load_error' : code;
+        this.failures[stable] = (this.failures[stable] ?? 0) + 1;
+        return stable;
+    }
+    snapshot() {
+        return { reload_count_bucket: countBucket(this.reloads), reload_error_count_bucket: countBucket(this.reloadErrors),
+            load_failures: Object.fromEntries(Object.entries(this.failures).map(([code, count]) => [code, countBucket(count)])) };
+    }
+}

package/dist/utils/telemetry/domains.d.ts

@@ -0,0 +1,69 @@
+/** Stable domains: never populate these from user-provided names or messages. */
+export declare const COUNT_BUCKETS: readonly ["0", "1", "2-5", "6-20", "21-100", "101+"];
+export declare const DURATION_BUCKETS: readonly ["<100ms", "100ms-1s", "1s-10s", "10s-1m", "1m-10m", "10m-1h", "1h+"];
+export declare const ERROR_CODES: readonly ["unknown", "connection_failed", "auth_failed", "entrypoint_not_found", "compile_error", "prompt_cancelled", "validation_failed", "cloud_network_error", "cloud_rejected", "not_installed", "engine_error", "no_tables", "no_datasets", "tenant_required", "load_error", "output_missing", "output_out_of_date", "unknown_command", "unknown_option"];
+export declare const OUTCOMES: readonly ["success", "failure", "cancelled", "interrupted"];
+export declare const DATABASES: readonly ["clickhouse", "chdb", "bigquery", "unknown"];
+export declare const COMMANDS: readonly ["init", "dev", "mcp", "generate", "generate:types", "generate:datasets", "generate:manifest", "login", "logout", "deploy", "deployment:build", "deployment:validate", "deployment:release", "deployment:submit", "deployment:status", "pull", "diff", "help", "version", "telemetry", "unknown"];
+export type TelemetryCommand = typeof COMMANDS[number];
+/** Canonical long names, including negated flags. Values and aliases never leave the CLI. */
+export declare const COMMAND_FLAGS: {
+    readonly init: readonly ["--path", "--style", "--database", "--chdb-path", "--auth", "--all-tables", "--tables", "--exclude-tables", "--no-example", "--no-interactive", "--force", "--skip-connection"];
+    readonly dev: readonly ["--port", "--hostname", "--no-watch", "--no-cache", "--cache", "--redis-url", "--open", "--cors", "--path", "--quiet"];
+    readonly mcp: readonly ["--path", "--tenant", "--self-test", "--url"];
+    readonly generate: readonly ["--output", "--path", "--tables", "--database", "--chdb-path"];
+    readonly 'generate:types': readonly ["--output", "--path", "--tables", "--database", "--chdb-path"];
+    readonly 'generate:datasets': readonly ["--output", "--path", "--tables", "--exclude-tables", "--tenant-column", "--force", "--check", "--diff"];
+    readonly 'generate:manifest': readonly ["--output"];
+    readonly login: readonly ["--cloud-url", "--environment"];
+    readonly logout: readonly [];
+    readonly deploy: readonly ["--bundle-output", "--release-output", "--project", "--environment", "--no-source", "--endpoint", "--replace-restored", "--mcp-config"];
+    readonly 'deployment:build': readonly ["--bundle-output", "--no-source"];
+    readonly 'deployment:validate': readonly [];
+    readonly 'deployment:release': readonly ["--project", "--environment", "--output"];
+    readonly 'deployment:submit': readonly ["--release", "--endpoint", "--replace-restored"];
+    readonly 'deployment:status': readonly ["--project", "--environment", "--endpoint", "--mcp-config"];
+    readonly pull: readonly ["--output", "--project", "--environment", "--endpoint"];
+    readonly diff: readonly ["--project", "--environment", "--endpoint"];
+    readonly help: readonly [];
+    readonly version: readonly [];
+    readonly telemetry: readonly [];
+    readonly unknown: readonly [];
+};
+export declare const GLOBAL_FLAGS: readonly ["--no-telemetry", "--help", "--version"];
+/** Options that consume the next argument as their value; that value is never a flag. */
+export declare const VALUE_FLAGS: {
+    readonly init: readonly ["--path", "--style", "--database", "--chdb-path", "--auth", "--tables", "--exclude-tables"];
+    readonly dev: readonly ["--port", "--hostname", "--cache", "--redis-url", "--path"];
+    readonly mcp: readonly ["--path", "--tenant", "--url"];
+    readonly generate: readonly ["--output", "--path", "--tables", "--database", "--chdb-path"];
+    readonly 'generate:types': readonly ["--output", "--path", "--tables", "--database", "--chdb-path"];
+    readonly 'generate:datasets': readonly ["--output", "--path", "--tables", "--exclude-tables", "--tenant-column"];
+    readonly 'generate:manifest': readonly ["--output"];
+    readonly login: readonly ["--cloud-url", "--environment"];
+    readonly logout: readonly [];
+    readonly deploy: readonly ["--bundle-output", "--release-output", "--project", "--environment", "--endpoint"];
+    readonly 'deployment:build': readonly ["--bundle-output"];
+    readonly 'deployment:validate': readonly [];
+    readonly 'deployment:release': readonly ["--project", "--environment", "--output"];
+    readonly 'deployment:submit': readonly ["--release", "--endpoint"];
+    readonly 'deployment:status': readonly ["--project", "--environment", "--endpoint"];
+    readonly pull: readonly ["--output", "--project", "--environment", "--endpoint"];
+    readonly diff: readonly ["--project", "--environment", "--endpoint"];
+    readonly help: readonly [];
+    readonly version: readonly [];
+    readonly telemetry: readonly [];
+    readonly unknown: readonly [];
+};
+export type TelemetryFlag = typeof COMMAND_FLAGS[TelemetryCommand][number] | typeof GLOBAL_FLAGS[number];
+export declare const SHORT_FLAGS: {
+    readonly '-o': "--output";
+    readonly '-p': "--port";
+    readonly '-h': "--hostname";
+    readonly '-q': "--quiet";
+    readonly '-V': "--version";
+};
+export declare const HYPEQUERY_PACKAGES: readonly ["@hypequery/clickhouse", "@hypequery/datasets", "@hypequery/serve", "@hypequery/react", "@hypequery/cli", "@hypequery/mcp", "@hypequery/protocol", "@hypequery/protocol-conformance", "@hypequery/deployment"];
+export declare const WARNING_CODES: readonly ["tenant-key-candidate", "tenant-column-missing"];
+export declare const TYPE_FAMILIES: readonly ["AggregateFunction", "SimpleAggregateFunction", "Variant", "Dynamic", "Object", "JSON", "Nested", "Tuple", "Map", "Array", "Nullable", "LowCardinality", "Decimal", "Enum", "DateTime", "DateTime64", "unknown"];
+//# sourceMappingURL=domains.d.ts.map

package/dist/utils/telemetry/domains.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domains.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/domains.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,eAAO,MAAM,aAAa,sDAAuD,CAAC;AAClF,eAAO,MAAM,gBAAgB,gFAAiF,CAAC;AAC/G,eAAO,MAAM,WAAW,gWAKd,CAAC;AACX,eAAO,MAAM,QAAQ,6DAA8D,CAAC;AACpF,eAAO,MAAM,SAAS,wDAAyD,CAAC;AAChF,eAAO,MAAM,QAAQ,4SAKX,CAAC;AACX,MAAM,MAAM,gBAAgB,GAAG,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC;AAEvD,6FAA6F;AAC7F,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;CAmBsC,CAAC;AACjE,eAAO,MAAM,YAAY,oDAAqD,CAAC;AAC/E,yFAAyF;AACzF,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;CAmBoE,CAAC;AAC7F,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,gBAAgB,CAAC,CAAC,MAAM,CAAC,GAAG,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC;AACzG,eAAO,MAAM,WAAW;;;;;;CAAwG,CAAC;AACjI,eAAO,MAAM,kBAAkB,0NAA2N,CAAC;AAC3P,eAAO,MAAM,aAAa,4DAA6D,CAAC;AACxF,eAAO,MAAM,aAAa,4NAA6N,CAAC"}

package/dist/utils/telemetry/domains.js

@@ -0,0 +1,64 @@
+/** Stable domains: never populate these from user-provided names or messages. */
+export const COUNT_BUCKETS = ['0', '1', '2-5', '6-20', '21-100', '101+'];
+export const DURATION_BUCKETS = ['<100ms', '100ms-1s', '1s-10s', '10s-1m', '1m-10m', '10m-1h', '1h+'];
+export const ERROR_CODES = [
+    'unknown', 'connection_failed', 'auth_failed', 'entrypoint_not_found', 'compile_error',
+    'prompt_cancelled', 'validation_failed', 'cloud_network_error', 'cloud_rejected',
+    'not_installed', 'engine_error', 'no_tables', 'no_datasets', 'tenant_required',
+    'load_error', 'output_missing', 'output_out_of_date', 'unknown_command', 'unknown_option',
+];
+export const OUTCOMES = ['success', 'failure', 'cancelled', 'interrupted'];
+export const DATABASES = ['clickhouse', 'chdb', 'bigquery', 'unknown'];
+export const COMMANDS = [
+    'init', 'dev', 'mcp', 'generate', 'generate:types', 'generate:datasets',
+    'generate:manifest', 'login', 'logout', 'deploy', 'deployment:build',
+    'deployment:validate', 'deployment:release', 'deployment:submit', 'deployment:status',
+    'pull', 'diff', 'help', 'version', 'telemetry', 'unknown',
+];
+/** Canonical long names, including negated flags. Values and aliases never leave the CLI. */
+export const COMMAND_FLAGS = {
+    init: ['--path', '--style', '--database', '--chdb-path', '--auth', '--all-tables', '--tables', '--exclude-tables', '--no-example', '--no-interactive', '--force', '--skip-connection'],
+    dev: ['--port', '--hostname', '--no-watch', '--no-cache', '--cache', '--redis-url', '--open', '--cors', '--path', '--quiet'],
+    mcp: ['--path', '--tenant', '--self-test', '--url'],
+    generate: ['--output', '--path', '--tables', '--database', '--chdb-path'],
+    'generate:types': ['--output', '--path', '--tables', '--database', '--chdb-path'],
+    'generate:datasets': ['--output', '--path', '--tables', '--exclude-tables', '--tenant-column', '--force', '--check', '--diff'],
+    'generate:manifest': ['--output'],
+    login: ['--cloud-url', '--environment'],
+    logout: [],
+    deploy: ['--bundle-output', '--release-output', '--project', '--environment', '--no-source', '--endpoint', '--replace-restored', '--mcp-config'],
+    'deployment:build': ['--bundle-output', '--no-source'],
+    'deployment:validate': [],
+    'deployment:release': ['--project', '--environment', '--output'],
+    'deployment:submit': ['--release', '--endpoint', '--replace-restored'],
+    'deployment:status': ['--project', '--environment', '--endpoint', '--mcp-config'],
+    pull: ['--output', '--project', '--environment', '--endpoint'],
+    diff: ['--project', '--environment', '--endpoint'],
+    help: [], version: [], telemetry: [], unknown: [],
+};
+export const GLOBAL_FLAGS = ['--no-telemetry', '--help', '--version'];
+/** Options that consume the next argument as their value; that value is never a flag. */
+export const VALUE_FLAGS = {
+    init: ['--path', '--style', '--database', '--chdb-path', '--auth', '--tables', '--exclude-tables'],
+    dev: ['--port', '--hostname', '--cache', '--redis-url', '--path'],
+    mcp: ['--path', '--tenant', '--url'],
+    generate: ['--output', '--path', '--tables', '--database', '--chdb-path'],
+    'generate:types': ['--output', '--path', '--tables', '--database', '--chdb-path'],
+    'generate:datasets': ['--output', '--path', '--tables', '--exclude-tables', '--tenant-column'],
+    'generate:manifest': ['--output'],
+    login: ['--cloud-url', '--environment'],
+    logout: [],
+    deploy: ['--bundle-output', '--release-output', '--project', '--environment', '--endpoint'],
+    'deployment:build': ['--bundle-output'],
+    'deployment:validate': [],
+    'deployment:release': ['--project', '--environment', '--output'],
+    'deployment:submit': ['--release', '--endpoint'],
+    'deployment:status': ['--project', '--environment', '--endpoint'],
+    pull: ['--output', '--project', '--environment', '--endpoint'],
+    diff: ['--project', '--environment', '--endpoint'],
+    help: [], version: [], telemetry: [], unknown: [],
+};
+export const SHORT_FLAGS = { '-o': '--output', '-p': '--port', '-h': '--hostname', '-q': '--quiet', '-V': '--version' };
+export const HYPEQUERY_PACKAGES = ['@hypequery/clickhouse', '@hypequery/datasets', '@hypequery/serve', '@hypequery/react', '@hypequery/cli', '@hypequery/mcp', '@hypequery/protocol', '@hypequery/protocol-conformance', '@hypequery/deployment'];
+export const WARNING_CODES = ['tenant-key-candidate', 'tenant-column-missing'];
+export const TYPE_FAMILIES = ['AggregateFunction', 'SimpleAggregateFunction', 'Variant', 'Dynamic', 'Object', 'JSON', 'Nested', 'Tuple', 'Map', 'Array', 'Nullable', 'LowCardinality', 'Decimal', 'Enum', 'DateTime', 'DateTime64', 'unknown'];

package/dist/utils/telemetry/endpoint.d.ts

@@ -0,0 +1,3 @@
+/** HTTPS, or HTTP for loopback testing only; rejects credentials, query strings and fragments. */
+export declare function telemetryEndpoint(raw: string | undefined): URL | null;
+//# sourceMappingURL=endpoint.d.ts.map

package/dist/utils/telemetry/endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/endpoint.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,GAAG,GAAG,IAAI,CAQrE"}

package/dist/utils/telemetry/endpoint.js

@@ -0,0 +1,15 @@
+/** HTTPS, or HTTP for loopback testing only; rejects credentials, query strings and fragments. */
+export function telemetryEndpoint(raw) {
+    if (!raw)
+        return null;
+    try {
+        const url = new URL(raw);
+        const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+        if ((url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) || url.username || url.password || url.search || url.hash)
+            return null;
+        return url;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/utils/telemetry/environment.d.ts

@@ -0,0 +1,27 @@
+import { COMMON_PROPERTIES } from './catalog.js';
+import type { Properties } from './schema.js';
+import { type ProjectContext, type ReadLocalFile } from './project-context.js';
+type Common = Properties<typeof COMMON_PROPERTIES>;
+export declare const CI_SIGNALS: readonly [readonly ["GITHUB_ACTIONS", "github_actions"], readonly ["GITLAB_CI", "gitlab"], readonly ["CIRCLECI", "circleci"], readonly ["BUILDKITE", "buildkite"], readonly ["JENKINS_URL", "jenkins"], readonly ["VERCEL", "vercel"], readonly ["NETLIFY", "netlify"], readonly ["TF_BUILD", "azure"], readonly ["BITBUCKET_BUILD_NUMBER", "bitbucket"], readonly ["TEAMCITY_VERSION", "teamcity"], readonly ["TRAVIS", "travis"], readonly ["CODEBUILD_BUILD_ID", "codebuild"]];
+export declare function ciContext(env: Readonly<Record<string, string | undefined>>): Pick<Common, 'is_ci' | 'ci_name'>;
+export declare function packageManagerContext(env: Readonly<Record<string, string | undefined>>, executable: string): Pick<Common, 'package_manager' | 'package_manager_major' | 'invoked_via'>;
+export declare function installedPackages(context: ProjectContext, read: ReadLocalFile): Common['hypequery_packages'];
+export declare function environmentDatabase(env: Readonly<Record<string, string | undefined>>, context: ProjectContext): Common['database'];
+export interface EnvironmentOptions {
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly read?: ReadLocalFile;
+    readonly platform?: string;
+    readonly arch?: string;
+    readonly nodeVersion?: string;
+    readonly cliVersion?: string;
+    readonly executable?: string;
+    readonly isTTY?: boolean;
+    readonly database?: string;
+    /** Monotonic clock for the local-read budget. Defaults to `performance.now`. */
+    readonly now?: () => number;
+}
+/** Total wall-clock budget for local file probes; telemetry must never slow the CLI. */
+export declare const READ_BUDGET_MS = 5;
+export declare function collectEnvironment(context: ProjectContext, options?: EnvironmentOptions): Omit<Common, 'install_id' | 'session_id' | 'project_id' | 'is_first_run'>;
+export {};
+//# sourceMappingURL=environment.d.ts.map

package/dist/utils/telemetry/environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/environment.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAwB,MAAM,cAAc,CAAC;AAEvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAAkC,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI/G,KAAK,MAAM,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC;AACnD,eAAO,MAAM,UAAU,mdAKb,CAAC;AAEX,wBAAgB,SAAS,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC,CAI9G;AAED,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,EACjD,UAAU,EAAE,MAAM,GACjB,IAAI,CAAC,MAAM,EAAE,iBAAiB,GAAG,uBAAuB,GAAG,aAAa,CAAC,CAY3E;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,GAAG,MAAM,CAAC,oBAAoB,CAAC,CAkB5G;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM,CAAC,UAAU,CAAC,CAMlI;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC5D,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,wFAAwF;AACxF,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,GAAE,kBAAuB,GAAG,IAAI,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,GAAG,YAAY,GAAG,cAAc,CAAC,CAyBvK"}

package/dist/utils/telemetry/environment.js

@@ -0,0 +1,95 @@
+import path from 'node:path';
+import { COMMON_PROPERTIES, EVENT_SCHEMA_VERSION } from './catalog.js';
+import { HYPEQUERY_PACKAGES, DATABASES } from './domains.js';
+import { matchesTelemetryFormat } from './value-formats.js';
+import { readPackage, readTelemetryFile } from './project-context.js';
+import { detectDatabaseFromEnvironment } from '../detect-database-environment.js';
+import { performance } from 'node:perf_hooks';
+export const CI_SIGNALS = [
+    ['GITHUB_ACTIONS', 'github_actions'], ['GITLAB_CI', 'gitlab'], ['CIRCLECI', 'circleci'],
+    ['BUILDKITE', 'buildkite'], ['JENKINS_URL', 'jenkins'], ['VERCEL', 'vercel'],
+    ['NETLIFY', 'netlify'], ['TF_BUILD', 'azure'], ['BITBUCKET_BUILD_NUMBER', 'bitbucket'],
+    ['TEAMCITY_VERSION', 'teamcity'], ['TRAVIS', 'travis'], ['CODEBUILD_BUILD_ID', 'codebuild'],
+];
+export function ciContext(env) {
+    const match = CI_SIGNALS.find(([key]) => env[key] && env[key] !== 'false' && env[key] !== '0');
+    const ci = !!match || !!(env.CI && env.CI !== 'false' && env.CI !== '0');
+    return { is_ci: ci, ci_name: match?.[1] ?? (ci ? 'unknown' : 'none') };
+}
+export function packageManagerContext(env, executable) {
+    const match = env.npm_config_user_agent?.match(/^(npm|pnpm|yarn|bun)\/(\d{1,3})(?:\.|\s|$)/);
+    const executableManager = env.npm_execpath?.replace(/\\/g, '/').split('/').pop()?.match(/^(npm-cli|pnpm|yarn|bun)(?:[-.].*)?$/)?.[1];
+    const manager = (match?.[1] ?? (executableManager === 'npm-cli' ? 'npm' : executableManager));
+    const script = executable.replace(/\\/g, '/');
+    const invoked = /\/_npx\//.test(script) ? 'npx'
+        : /(?:\/dlx\/|\/dlx-)/.test(script) && manager === 'pnpm' ? 'pnpm_dlx'
+            : env.npm_command === 'exec' && manager === 'npm' ? 'npx'
+                : manager === 'bun' && /(?:bunx|\.bun\/install\/cache)/.test(script) ? 'bunx'
+                    : /(?:\/lib\/node_modules\/|\/bin\/hypequery(?:\.js)?$)/.test(script) ? 'global'
+                        : /\/node_modules\/(?:\.bin\/|@hypequery\/cli\/)/.test(script) ? 'local_bin' : 'unknown';
+    return { package_manager: manager ?? 'unknown', ...(match ? { package_manager_major: match[2] } : {}), invoked_via: invoked };
+}
+export function installedPackages(context, read) {
+    const result = {};
+    const pkg = context.package;
+    if (!pkg || !context.directory)
+        return undefined;
+    for (const name of HYPEQUERY_PACKAGES) {
+        const declared = [pkg.dependencies, pkg.devDependencies, pkg.peerDependencies, pkg.optionalDependencies]
+            .some(section => !!section && typeof section === 'object' && Object.hasOwn(section, name));
+        if (!declared)
+            continue;
+        const locations = [...new Set([context.directory, context.rootDirectory].filter((directory) => !!directory))];
+        const resolved = locations.map(directory => readPackage(path.join(directory, 'node_modules', name, 'package.json'), read)?.version)
+            .find(version => matchesTelemetryFormat('version', version));
+        const sections = [pkg.dependencies, pkg.devDependencies, pkg.peerDependencies, pkg.optionalDependencies];
+        const spec = sections.map(section => section?.[name]).find(value => typeof value === 'string');
+        // Dependency specs are never forwarded. Only a validated exact release is eligible.
+        result[name] = matchesTelemetryFormat('version', resolved) ? resolved
+            : matchesTelemetryFormat('version', spec) ? spec : 'unknown';
+    }
+    return Object.keys(result).length ? result : undefined;
+}
+export function environmentDatabase(env, context) {
+    const detected = detectDatabaseFromEnvironment(env);
+    if (detected)
+        return detected;
+    const pkg = context.package;
+    if ([pkg?.dependencies, pkg?.devDependencies].some(section => !!section && typeof section === 'object' && Object.hasOwn(section, 'chdb')))
+        return 'chdb';
+    return 'unknown';
+}
+/** Total wall-clock budget for local file probes; telemetry must never slow the CLI. */
+export const READ_BUDGET_MS = 5;
+export function collectEnvironment(context, options = {}) {
+    const env = options.env ?? process.env;
+    const now = options.now ?? (() => performance.now());
+    const deadline = now() + READ_BUDGET_MS;
+    const read = file => {
+        if (now() >= deadline)
+            return undefined;
+        try {
+            return (options.read ?? readTelemetryFile)(file);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const os = options.platform ?? process.platform;
+    const arch = options.arch ?? process.arch;
+    const node = (options.nodeVersion ?? process.versions.node).split('.').slice(0, 2).join('.');
+    const packages = installedPackages(context, read);
+    const docker = read('/.dockerenv') !== undefined || /(?:docker|containerd|kubepods)/.test(read('/proc/1/cgroup') ?? '');
+    const wsl = !!env.WSL_DISTRO_NAME || /microsoft/i.test(read('/proc/sys/kernel/osrelease') ?? '');
+    return {
+        schema_version: EVENT_SCHEMA_VERSION,
+        cli_version: matchesTelemetryFormat('version', options.cliVersion) ? options.cliVersion : 'unknown',
+        node_version: matchesTelemetryFormat('node_version', node) ? node : 'unknown',
+        os: COMMON_PROPERTIES.os.values.includes(os) ? os : 'unknown',
+        arch: COMMON_PROPERTIES.arch.values.includes(arch) ? arch : 'unknown',
+        ...ciContext(env), is_tty: options.isTTY ?? !!process.stderr.isTTY, is_docker: docker, is_wsl: wsl,
+        ...packageManagerContext(env, options.executable ?? process.argv[1] ?? ''),
+        ...(packages ? { hypequery_packages: packages } : {}),
+        database: DATABASES.includes(options.database ?? '') ? options.database : environmentDatabase(env, context),
+    };
+}

package/dist/utils/telemetry/error-code.d.ts

@@ -0,0 +1,4 @@
+import { ERROR_CODES } from './domains.js';
+export declare function telemetryErrorCode(error: unknown): typeof ERROR_CODES[number];
+export declare function exceptionClass(error: unknown): 'Error' | 'TypeError' | 'RangeError' | 'SyntaxError' | 'ReferenceError' | 'URIError' | 'EvalError' | 'AggregateError' | 'unknown';
+//# sourceMappingURL=error-code.d.ts.map

package/dist/utils/telemetry/error-code.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-code.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/error-code.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,WAAW,CAAC,MAAM,CAAC,CAuB7E;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,WAAW,GAAG,YAAY,GAAG,aAAa,GAAG,gBAAgB,GAAG,UAAU,GAAG,WAAW,GAAG,gBAAgB,GAAG,SAAS,CAShL"}

package/dist/utils/telemetry/error-code.js

@@ -0,0 +1,57 @@
+import { isPromptCancelled } from '../prompts.js';
+import { CommandExit } from '../command-exit.js';
+import { ERROR_CODES } from './domains.js';
+export function telemetryErrorCode(error) {
+    if (error instanceof CommandExit)
+        return error.errorCode ?? 'unknown';
+    if (isPromptCancelled(error))
+        return 'prompt_cancelled';
+    if (!error || typeof error !== 'object')
+        return 'unknown';
+    try {
+        const code = error.code;
+        if (typeof code === 'string') {
+            if (ERROR_CODES.includes(code))
+                return code;
+            if (['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND', 'EAI_AGAIN'].includes(code))
+                return 'connection_failed';
+            if (['UNAUTHORIZED', 'FORBIDDEN', 'AUTHENTICATION_FAILED'].includes(code))
+                return 'auth_failed';
+            if (code === 'commander.unknownCommand')
+                return 'unknown_command';
+            if (code === 'commander.unknownOption')
+                return 'unknown_option';
+            if (code.startsWith('commander.'))
+                return 'validation_failed';
+        }
+        // Some existing libraries expose only messages. Classify locally and discard
+        // the text; the returned value is always from the closed catalog.
+        if (error instanceof Error) {
+            if (/authentication failed|unauthorized|forbidden/i.test(error.message))
+                return 'auth_failed';
+            if (/build failed|compilation failed|transform failed/i.test(error.message))
+                return 'compile_error';
+            if (/ECONNREFUSED|ECONNRESET|ENOTFOUND|ETIMEDOUT|fetch failed|network error/i.test(error.message))
+                return 'connection_failed';
+        }
+    }
+    catch { /* No error content is retained. */ }
+    return 'unknown';
+}
+export function exceptionClass(error) {
+    if (error instanceof TypeError)
+        return 'TypeError';
+    if (error instanceof RangeError)
+        return 'RangeError';
+    if (error instanceof SyntaxError)
+        return 'SyntaxError';
+    if (error instanceof ReferenceError)
+        return 'ReferenceError';
+    if (error instanceof URIError)
+        return 'URIError';
+    if (error instanceof EvalError)
+        return 'EvalError';
+    if (error instanceof AggregateError)
+        return 'AggregateError';
+    return error instanceof Error ? 'Error' : 'unknown';
+}

package/dist/utils/telemetry/flags.d.ts

@@ -0,0 +1,5 @@
+import { type TelemetryCommand, type TelemetryFlag } from './domains.js';
+export declare function knownCommand(input: string): TelemetryCommand;
+/** Call with Commander's raw args for the selected command, never its option values. */
+export declare function flagNames(command: TelemetryCommand, args: readonly string[]): TelemetryFlag[];
+//# sourceMappingURL=flags.d.ts.map

package/dist/utils/telemetry/flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/flags.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmE,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAE1I,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAE5D;AAED,wFAAwF;AACxF,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,aAAa,EAAE,CA8B7F"}

package/dist/utils/telemetry/flags.js

@@ -0,0 +1,41 @@
+import { COMMANDS, COMMAND_FLAGS, GLOBAL_FLAGS, SHORT_FLAGS, VALUE_FLAGS } from './domains.js';
+export function knownCommand(input) {
+    return COMMANDS.includes(input) ? input : 'unknown';
+}
+/** Call with Commander's raw args for the selected command, never its option values. */
+export function flagNames(command, args) {
+    const allowed = [...COMMAND_FLAGS[command], ...GLOBAL_FLAGS];
+    const takesValue = VALUE_FLAGS[command];
+    const flags = new Set();
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === '--')
+            break;
+        if (/^-[^-].+/.test(arg)) {
+            for (const [position, letter] of [...arg.slice(1)].entries()) {
+                const short = `-${letter}`;
+                const canonical = short === '-h' && command !== 'dev' ? '--help' : SHORT_FLAGS[short];
+                if (!canonical || !allowed.includes(canonical))
+                    break;
+                flags.add(canonical);
+                if (takesValue.includes(canonical)) {
+                    // A value is either attached (-p4000) or the next argument (-p 4000).
+                    if (position === arg.length - 2)
+                        index++;
+                    break;
+                }
+            }
+            continue;
+        }
+        const name = arg.split('=', 1)[0];
+        const canonical = name === '-h' && command !== 'dev'
+            ? '--help' : SHORT_FLAGS[name] ?? name;
+        if (allowed.includes(canonical))
+            flags.add(canonical);
+        // Commander takes the next argument as a required value even when it starts
+        // with "-", so it must not be read as flags (`--output -help.ts`).
+        if (takesValue.includes(canonical) && !arg.includes('='))
+            index++;
+    }
+    return [...flags].sort();
+}

package/dist/utils/telemetry/generation-metrics.d.ts

@@ -0,0 +1,15 @@
+import type { DatasetGenerationWarning } from '../../generators/dataset-generator.js';
+import type { CommandMetrics } from './command-context.js';
+export declare function warningBuckets(warnings?: readonly DatasetGenerationWarning[]): NonNullable<CommandMetrics<'generate:datasets'>['warning_counts']>;
+/** Only inspect already produced manifest data and the loaded registry. */
+export declare function manifestMetrics(api: unknown, manifest: unknown): CommandMetrics<'generate:manifest'>;
+/** Reduces fallback type expressions immediately to a closed family domain. */
+export declare class TypeGenerationMetrics {
+    private columns;
+    private unsupported;
+    private families;
+    column(): void;
+    fallback(type: string): void;
+    snapshot(): CommandMetrics<'generate'>;
+}
+//# sourceMappingURL=generation-metrics.d.ts.map

package/dist/utils/telemetry/generation-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generation-metrics.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/generation-metrics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AAGtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,wBAAgB,cAAc,CAAC,QAAQ,GAAE,SAAS,wBAAwB,EAAO,GAAG,WAAW,CAAC,cAAc,CAAC,mBAAmB,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAErJ;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,GAAG,cAAc,CAAC,mBAAmB,CAAC,CAQpG;AAED,+EAA+E;AAC/E,qBAAa,qBAAqB;IAChC,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,QAAQ,CAA2C;IAE3D,MAAM,IAAI,IAAI;IAEd,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAO5B,QAAQ,IAAI,cAAc,CAAC,UAAU,CAAC;CAIvC"}

package/dist/utils/telemetry/generation-metrics.js

@@ -0,0 +1,35 @@
+import { TYPE_FAMILIES, WARNING_CODES } from './domains.js';
+import { countBucket } from './buckets.js';
+export function warningBuckets(warnings = []) {
+    return Object.fromEntries(WARNING_CODES.map(code => [code, countBucket(warnings.filter(warning => warning.kind === code).length)]));
+}
+/** Only inspect already produced manifest data and the loaded registry. */
+export function manifestMetrics(api, manifest) {
+    try {
+        const queries = Object.getOwnPropertyDescriptor(api, 'queries')?.value;
+        return {
+            ...(queries && typeof queries === 'object' ? { query_count_bucket: countBucket(Object.keys(queries).length) } : {}),
+            ...(manifest && typeof manifest === 'object' ? { endpoint_count_bucket: countBucket(Object.keys(manifest).length) } : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+/** Reduces fallback type expressions immediately to a closed family domain. */
+export class TypeGenerationMetrics {
+    columns = 0;
+    unsupported = 0;
+    families = new Set();
+    column() { this.columns++; }
+    fallback(type) {
+        this.unsupported++;
+        const name = /^\s*([A-Za-z][A-Za-z0-9_]*)/.exec(type)?.[1];
+        const family = TYPE_FAMILIES.find(value => value === name) ?? 'unknown';
+        this.families.add(family);
+    }
+    snapshot() {
+        return { column_count_bucket: countBucket(this.columns), unsupported_type_count_bucket: countBucket(this.unsupported),
+            unsupported_type_families: TYPE_FAMILIES.filter(family => this.families.has(family)) };
+    }
+}

package/dist/utils/telemetry/identity.d.ts

@@ -0,0 +1,12 @@
+import type { TelemetryConfig } from './config-schema.js';
+import type { ProjectContext } from './project-context.js';
+/** HQ-233: shared across installs; the proxy must re-key this digest before storage. */
+export declare const PROJECT_HASH_SALT = "hypequery.cli.project.v1:";
+export declare function normalizeProjectRemote(input: string): string | undefined;
+export declare function projectId(context: ProjectContext): string | undefined;
+export declare function invocationIdentity(config: TelemetryConfig, context: ProjectContext): {
+    project_id?: string | undefined;
+    install_id: string;
+    session_id: `${string}-${string}-${string}-${string}-${string}`;
+};
+//# sourceMappingURL=identity.d.ts.map

package/dist/utils/telemetry/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/identity.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,wFAAwF;AACxF,eAAO,MAAM,iBAAiB,8BAA8B,CAAC;AAE7D,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAoBxE;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAMrE;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc;;;;EAGlF"}

package/dist/utils/telemetry/identity.js

@@ -0,0 +1,42 @@
+import { createHash, randomUUID } from 'node:crypto';
+/** HQ-233: shared across installs; the proxy must re-key this digest before storage. */
+export const PROJECT_HASH_SALT = 'hypequery.cli.project.v1:';
+export function normalizeProjectRemote(input) {
+    try {
+        const raw = input.trim();
+        let url;
+        // SCP-style SSH remotes have no URL scheme. Local file paths are not signals.
+        if (/^(?:[^/@\s]+@)?[^/:\s]+:[^\\\s]+$/.test(raw) && !raw.includes('://')) {
+            const match = raw.match(/^(?:[^/@\s]+@)?([^/:\s]+):(.+)$/);
+            if (match[1].length === 1)
+                return undefined; // Windows drive path.
+            url = new URL(`ssh://${match[1]}/${match[2]}`);
+        }
+        else {
+            url = new URL(raw);
+        }
+        if (!['https:', 'http:', 'ssh:', 'git:'].includes(url.protocol))
+            return undefined;
+        const repo = url.pathname.replace(/^\/+|\/+$/g, '').replace(/\.git$/i, '');
+        if (!url.hostname || !repo)
+            return undefined;
+        const standardPort = { 'ssh:': '22', 'git:': '9418', 'https:': '443', 'http:': '80' }[url.protocol];
+        const port = url.port && url.port !== standardPort ? `:${url.port}` : '';
+        // Credentials, query, fragment and transport are excluded before hashing.
+        return `${url.hostname.toLowerCase()}${port}/${repo}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function projectId(context) {
+    const remote = context.remote ? normalizeProjectRemote(context.remote) : undefined;
+    const name = (context.rootPackage ?? context.package)?.name;
+    const signal = remote ? `remote:${remote}` : typeof name === 'string' && name.trim()
+        ? `package:${name.trim()}` : undefined;
+    return signal ? createHash('sha256').update(PROJECT_HASH_SALT).update(signal).digest('hex') : undefined;
+}
+export function invocationIdentity(config, context) {
+    const project = projectId(context);
+    return { install_id: config.install_id, session_id: randomUUID(), ...(project ? { project_id: project } : {}) };
+}

package/dist/utils/telemetry/init-funnel.d.ts

@@ -0,0 +1,15 @@
+import { type CommandMetrics } from './command-context.js';
+type InitStage = NonNullable<CommandMetrics<'init'>['stage_reached']>;
+/** Tracks actual progress even when embedded setup tests its connection later. */
+export declare class InitFunnel {
+    private reached;
+    private attempted;
+    constructor(metrics: CommandMetrics<'init'>);
+    update(metrics: CommandMetrics<'init'>): void;
+    attempt(stage: InitStage): void;
+    reach(stage: InitStage): void;
+    cancel(): void;
+    fail(error: unknown): void;
+}
+export {};
+//# sourceMappingURL=init-funnel.d.ts.map

package/dist/utils/telemetry/init-funnel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-funnel.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/init-funnel.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkD,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3G,KAAK,SAAS,GAAG,WAAW,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC;AAGtE,kFAAkF;AAClF,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,SAAS,CAAwB;gBAE7B,OAAO,EAAE,cAAc,CAAC,MAAM,CAAC;IAI3C,MAAM,CAAC,OAAO,EAAE,cAAc,CAAC,MAAM,CAAC,GAAG,IAAI;IAE7C,OAAO,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAE/B,KAAK,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAK7B,MAAM,IAAI,IAAI;IAEd,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;CAI3B"}

package/dist/utils/telemetry/init-funnel.js

@@ -0,0 +1,25 @@
+import { CommandExit } from '../command-exit.js';
+import { isPromptCancelled } from '../prompts.js';
+import { cancelCommandTelemetry, updateCommandTelemetry } from './command-context.js';
+const stages = ['started', 'database_selected', 'connection_tested', 'style_selected', 'files_written', 'dependencies_installed', 'completed'];
+/** Tracks actual progress even when embedded setup tests its connection later. */
+export class InitFunnel {
+    reached = 'started';
+    attempted = 'started';
+    constructor(metrics) {
+        this.update({ ...metrics, stage_reached: this.reached });
+    }
+    update(metrics) { updateCommandTelemetry('init', metrics); }
+    attempt(stage) { this.attempted = stage; }
+    reach(stage) {
+        if (stages.indexOf(stage) > stages.indexOf(this.reached))
+            this.reached = stage;
+        this.update({ stage_reached: this.reached });
+    }
+    cancel() { cancelCommandTelemetry(); }
+    fail(error) {
+        if (isPromptCancelled(error) || error instanceof CommandExit && error.outcome !== 'failure')
+            return;
+        this.update({ failed_stage: this.attempted });
+    }
+}