@hypequery/cli 1.22.0 → 1.23.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/catalog.ts"],"names":[],"mappings":"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"}

package/dist/utils/telemetry/catalog.js

@@ -0,0 +1,154 @@
+import { COMMANDS, COMMAND_FLAGS, COUNT_BUCKETS, DATABASES, DURATION_BUCKETS, ERROR_CODES, GLOBAL_FLAGS, HYPEQUERY_PACKAGES, OUTCOMES, TYPE_FAMILIES, WARNING_CODES } from './domains.js';
+import { boolean, enumeration, enumList, fieldsFor, formatted, optional, record } from './schema.js';
+const count = (description) => enumeration(description, COUNT_BUCKETS);
+export const EVENT_SCHEMA_VERSION = 1;
+const cache = enumeration('Which cache providers are adopted?', ['none', 'memory', 'redis', 'unknown']);
+const entry = enumeration('Which entrypoint convention is used? Never the path.', ['hypequery.ts', 'api.ts', 'queries.ts', 'explicit_file', 'unknown']);
+const output = boolean('Was a custom output location supplied? Never the path.');
+const stages = ['started', 'database_selected', 'connection_tested', 'style_selected', 'files_written', 'dependencies_installed', 'completed'];
+export const COMMON_PROPERTIES = {
+    schema_version: enumeration('Which event contract does this payload use?', [EVENT_SCHEMA_VERSION]),
+    cli_version: formatted('Which CLI releases are in use?', 'version'),
+    node_version: formatted('Which Node major.minor releases need support?', 'node_version'),
+    os: enumeration('Which operating systems need support?', ['darwin', 'linux', 'win32', 'aix', 'freebsd', 'openbsd', 'sunos', 'android', 'unknown']),
+    arch: enumeration('Which CPU architectures need support?', ['arm', 'arm64', 'ia32', 'x64', 'loong64', 'mips', 'mipsel', 'ppc', 'ppc64', 'riscv64', 's390', 's390x', 'unknown']),
+    is_ci: boolean('How much usage happens in CI?'),
+    ci_name: enumeration('Which CI providers need support?', ['none', 'github_actions', 'gitlab', 'circleci', 'buildkite', 'jenkins', 'vercel', 'netlify', 'azure', 'bitbucket', 'teamcity', 'travis', 'codebuild', 'unknown']),
+    is_tty: boolean('How much usage is interactive?'),
+    is_docker: boolean('How much usage runs in containers?'),
+    is_wsl: boolean('How much usage runs in WSL?'),
+    package_manager: enumeration('Which package managers need support?', ['npm', 'pnpm', 'yarn', 'bun', 'unknown']),
+    package_manager_major: optional(formatted('Which package-manager major releases need support?', 'major_version')),
+    invoked_via: enumeration('How is the CLI invoked?', ['npx', 'pnpm_dlx', 'bunx', 'global', 'local_bin', 'unknown']),
+    install_id: formatted('Count active installations without hardware or account identifiers.', 'uuid'),
+    project_id: optional(formatted('Count active projects across installations; omit when no signal exists.', 'hash')),
+    session_id: formatted('Group events from the same invocation.', 'uuid'),
+    is_first_run: boolean('How many installations are new?'),
+    hypequery_packages: optional(record('Which toolkit packages and exact versions are adopted? No project dependencies or names.', fieldsFor(HYPEQUERY_PACKAGES, optional(formatted('Installed exact release version, or unknown.', 'version'))))),
+    database: enumeration('Which database backends merit investment?', DATABASES),
+};
+const generation = {
+    chdb_path_given: optional(boolean('Is persistent embedded ClickHouse adopted?')),
+    tables_filter_used: optional(boolean('Are targeted type-generation workflows used?')),
+    table_count_bucket: optional(count('How large are introspected schemas?')),
+    column_count_bucket: optional(count('How many columns need type generation?')),
+    unsupported_type_count_bucket: optional(count('How often does type mapping need improvement?')),
+    unsupported_type_families: optional(enumList('Which built-in type families need mapping? Never full type expressions.', TYPE_FAMILIES)),
+    custom_output: optional(output),
+};
+const INSTRUMENTED = ['init', 'dev', 'mcp', 'generate', 'generate:types', 'generate:datasets', 'generate:manifest', 'help'];
+/** Command-specific completion fields; absence means that stage was not reached. */
+export const COMMAND_PROPERTIES = {
+    init: {
+        stage_reached: optional(enumeration('Where does onboarding stop?', stages)),
+        failed_stage: optional(enumeration('Which onboarding stage needs reliability work?', stages)),
+        style: optional(enumeration('Which scaffold style is adopted?', ['queries', 'datasets'])),
+        auth: optional(enumeration('Is context authentication adopted?', ['none', 'context'])),
+        interactive: optional(boolean('How much onboarding is interactive?')),
+        force: optional(boolean('How often are scaffold files overwritten?')),
+        example: optional(boolean('Are example queries requested?')),
+        skip_connection: optional(boolean('Are offline scaffolds used?')),
+        connection_result: optional(enumeration('Where does connection setup fail?', ['ok', 'failed', 'skipped'])),
+        chdb_failure_reason: optional(enumeration('Does embedded onboarding fail at installation or execution?', ['not_installed', 'engine_error'])),
+        table_count_bucket: optional(count('How large are onboarding schemas?')),
+        datasets_generated_bucket: optional(count('How many datasets are scaffolded?')),
+        table_selection: optional(enumeration('Which table-selection workflows are used?', ['all', 'list', 'exclude', 'prompt'])),
+        env_file: optional(enumeration('Does onboarding create or update environment config?', ['created', 'updated', 'unchanged', 'skipped'])),
+        gitignore: optional(enumeration('Does onboarding create or update ignore config?', ['created', 'updated', 'unchanged', 'skipped'])),
+        package_json_present: optional(boolean('Does onboarding start in an existing project?')),
+        analytics_directory_present: optional(boolean('Does onboarding reuse an analytics directory?')),
+    },
+    dev: {},
+    mcp: {
+        mode: optional(enumeration('Is MCP used for validation or serving?', ['self_test', 'serve'])),
+        hosted: optional(boolean('Is MCP self-test targeting a hosted endpoint?')),
+        dataset_count_bucket: optional(count('How many datasets are exposed to agents?')),
+        tenant_used: optional(boolean('Is a trusted tenant supplied? Never its value.')),
+        tenant_dataset_count_bucket: optional(count('How many datasets require tenant scope?')),
+    },
+    generate: generation,
+    'generate:types': generation,
+    'generate:datasets': {
+        mode: optional(enumeration('Are datasets generated locally or checked in CI?', ['write', 'check', 'diff'])),
+        check_result: optional(enumeration('Does CI find stale dataset definitions?', ['up_to_date', 'out_of_date', 'missing'])),
+        force: optional(boolean('Are existing definitions replaced?')),
+        tenant_column_used: optional(boolean('Is tenant isolation explicitly scaffolded? Never the column.')),
+        tables_filter_used: optional(boolean('Is include filtering adopted?')),
+        exclude_filter_used: optional(boolean('Is exclude filtering adopted?')),
+        datasets_generated_bucket: optional(count('How many dataset definitions are generated?')),
+        warning_counts: optional(record('Which tenant-scaffolding warnings need improvement?', fieldsFor(WARNING_CODES, optional(count('Bucketed warning occurrences.'))))),
+    },
+    'generate:manifest': {
+        query_count_bucket: optional(count('How much query-based React integration is adopted?')),
+        endpoint_count_bucket: optional(count('How much endpoint-based React integration is adopted?')),
+        custom_output: optional(output),
+    },
+    // Other commands report only the common completion fields until they are
+    // instrumented; each instrumentation change adds its command's fields here.
+    ...Object.fromEntries(COMMANDS.filter(command => !INSTRUMENTED.includes(command)).map(command => [command, {}])),
+    help: { help_topic: optional(enumeration('Which command help needs improvement? Unknown input becomes unknown.', ['root', ...COMMANDS])) },
+};
+export const SESSION_START_PROPERTIES = {
+    dev: {
+        entry_type: entry,
+        watch: boolean('Is file watching used?'),
+        cache_provider: cache,
+        cors: boolean('Is cross-origin development adopted?'),
+        open: boolean('Is the browser opened automatically?'),
+        custom_port: boolean('Is a non-default port selected? Never its number or hostname.'),
+        quiet: boolean('Is quiet startup adopted?'),
+    },
+    mcp: {
+        entry_type: entry,
+        mode: enumeration('Is MCP serving or validating?', ['self_test', 'serve']),
+        dataset_count_bucket: count('How many datasets are exposed to agents?'),
+        tenant_used: boolean('Is tenant scope supplied? Never its value.'),
+        tenant_dataset_count_bucket: count('How many exposed datasets require tenant scope?'),
+    },
+};
+export const SESSION_END_PROPERTIES = {
+    dev: {
+        reload_count_bucket: count('How heavily is hot reload used?'),
+        reload_error_count_bucket: count('How often does hot reload fail?'),
+        load_failures: record('Which load failures need reliability work?', fieldsFor(ERROR_CODES, optional(count('Bucketed failures by stable code.')))),
+    },
+    mcp: {
+        tool_call_counts: record('Which MCP tool kinds are adopted? No names or arguments.', fieldsFor(['list', 'describe', 'query'], count('Bucketed calls by built-in tool kind.'))),
+        error_count_bucket: count('How often do MCP sessions encounter errors?'),
+    },
+};
+export const EVENT_CATALOG = {
+    cli_command_completed: {
+        purpose: 'Measure command adoption, onboarding drop-off and release reliability. Exactly once per invocation; never emit for telemetry disable.',
+        properties: {
+            command: enumeration('Which known command was requested? Raw unknown input is never retained.', COMMANDS),
+            flags_used: enumList('Which documented flags are adopted? Canonical names only, never values.', [...new Set([...Object.values(COMMAND_FLAGS).flat(), ...GLOBAL_FLAGS])]),
+            outcome: enumeration('Which commands fail, succeed or are aborted?', OUTCOMES),
+            duration_bucket: enumeration('Which commands need performance work?', DURATION_BUCKETS),
+            error_code: optional(enumeration('Which known failures need reliability work?', ERROR_CODES)),
+        },
+        variants: COMMAND_PROPERTIES,
+    },
+    cli_session_started: {
+        purpose: 'Measure development-server and MCP session configuration; never emit on every reload or request.',
+        properties: { command: enumeration('Which long-running command starts?', ['dev', 'mcp']) },
+        variants: SESSION_START_PROPERTIES,
+    },
+    cli_session_ended: {
+        purpose: 'Measure session duration and aggregated usage on shutdown, without individual requests or tool arguments.',
+        properties: {
+            command: enumeration('Which long-running command ends?', ['dev', 'mcp']),
+            outcome: enumeration('How did the session end?', OUTCOMES),
+            duration_bucket: enumeration('How long are development and agent sessions?', DURATION_BUCKETS),
+        },
+        variants: SESSION_END_PROPERTIES,
+    },
+    cli_crash: {
+        purpose: 'Measure uncaught failures by stable class and code, with no messages or stacks.',
+        properties: {
+            command: enumeration('Which command crashed?', COMMANDS),
+            exception_class: enumeration('Which built-in exception classes need investigation?', ['Error', 'TypeError', 'RangeError', 'SyntaxError', 'ReferenceError', 'URIError', 'EvalError', 'AggregateError', 'unknown']),
+            error_code: enumeration('Which known failure caused the crash?', ERROR_CODES),
+        },
+    },
+};

package/dist/utils/telemetry/command-context.d.ts

@@ -0,0 +1,17 @@
+import type { COMMAND_PROPERTIES, SESSION_START_PROPERTIES, SESSION_END_PROPERTIES } from './catalog.js';
+import type { Properties } from './schema.js';
+import type { CommandLifecycle } from './lifecycle.js';
+import type { DATABASES, ERROR_CODES } from './domains.js';
+export type CommandMetrics<C extends keyof typeof COMMAND_PROPERTIES> = Properties<typeof COMMAND_PROPERTIES[C]> & {
+    database?: typeof DATABASES[number];
+};
+export type SessionCommand = keyof typeof SESSION_START_PROPERTIES;
+export type SessionStart<C extends SessionCommand> = Properties<typeof SESSION_START_PROPERTIES[C]>;
+export type SessionEnd<C extends SessionCommand> = Properties<typeof SESSION_END_PROPERTIES[C]>;
+/** Command callbacks and their asynchronous work share only this invocation. */
+export declare function withCommandTelemetry<T>(lifecycle: CommandLifecycle, action: () => T): T;
+export declare function updateCommandTelemetry<C extends keyof typeof COMMAND_PROPERTIES>(command: C, metrics: CommandMetrics<C>): void;
+export declare function cancelCommandTelemetry(): void;
+export declare function startCommandSession<C extends SessionCommand>(command: C, start: SessionStart<C>, end: () => SessionEnd<C>): void;
+export declare function setCommandTelemetryError(code: typeof ERROR_CODES[number]): void;
+//# sourceMappingURL=command-context.d.ts.map

package/dist/utils/telemetry/command-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-context.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/command-context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACzG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3D,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,OAAO,kBAAkB,IAAI,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,CAAC,CAAC,GAAG;IAAE,QAAQ,CAAC,EAAE,OAAO,SAAS,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC;AAC3J,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,wBAAwB,CAAC;AACnE,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,cAAc,IAAI,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAC,CAAC,CAAC,CAAC;AACpG,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,cAAc,IAAI,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC;AAGhG,gFAAgF;AAChF,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAEvF;AAED,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,MAAM,OAAO,kBAAkB,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI,CAE9H;AAED,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C;AAED,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,cAAc,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAEhI;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,OAAO,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,CAE/E"}

package/dist/utils/telemetry/command-context.js

@@ -0,0 +1,30 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+const context = new AsyncLocalStorage();
+/** Command callbacks and their asynchronous work share only this invocation. */
+export function withCommandTelemetry(lifecycle, action) {
+    return context.run(lifecycle, action);
+}
+export function updateCommandTelemetry(command, metrics) {
+    try {
+        context.getStore()?.update(command, metrics);
+    }
+    catch { /* Metrics never affect commands. */ }
+}
+export function cancelCommandTelemetry() {
+    try {
+        context.getStore()?.cancel();
+    }
+    catch { /* Preserve cancellation behavior. */ }
+}
+export function startCommandSession(command, start, end) {
+    try {
+        context.getStore()?.startSession(command, start, end);
+    }
+    catch { /* Sessions never affect commands. */ }
+}
+export function setCommandTelemetryError(code) {
+    try {
+        context.getStore()?.setError(code);
+    }
+    catch { /* Preserve command errors. */ }
+}

package/dist/utils/telemetry/config-schema.d.ts

@@ -0,0 +1,12 @@
+export declare const TELEMETRY_SCHEMA_VERSION = 1;
+export declare const TELEMETRY_DOCS_URL = "https://hypequery.com/docs/telemetry";
+export interface TelemetryConfig {
+    readonly schema_version: typeof TELEMETRY_SCHEMA_VERSION;
+    readonly enabled: boolean;
+    readonly install_id: string;
+    readonly notice_shown_at?: string;
+    readonly disabled_cli_versions?: readonly string[];
+}
+/** Reject malformed or future settings rather than silently enabling telemetry. */
+export declare function parseTelemetryConfig(input: string): TelemetryConfig | null;
+//# sourceMappingURL=config-schema.d.ts.map

package/dist/utils/telemetry/config-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-schema.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/config-schema.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAC1C,eAAO,MAAM,kBAAkB,yCAAyC,CAAC;AAEzE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,cAAc,EAAE,OAAO,wBAAwB,CAAC;IACzD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpD;AAED,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAyB1E"}

package/dist/utils/telemetry/config-schema.js

@@ -0,0 +1,33 @@
+import { matchesTelemetryFormat } from './value-formats.js';
+export const TELEMETRY_SCHEMA_VERSION = 1;
+export const TELEMETRY_DOCS_URL = 'https://hypequery.com/docs/telemetry';
+/** Reject malformed or future settings rather than silently enabling telemetry. */
+export function parseTelemetryConfig(input) {
+    try {
+        const value = JSON.parse(input);
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return null;
+        const config = value;
+        if (config.schema_version !== TELEMETRY_SCHEMA_VERSION
+            || typeof config.enabled !== 'boolean'
+            || typeof config.install_id !== 'string'
+            || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(config.install_id)
+            || (config.notice_shown_at !== undefined
+                && (typeof config.notice_shown_at !== 'string'
+                    || !Number.isFinite(Date.parse(config.notice_shown_at))))
+            || (config.disabled_cli_versions !== undefined
+                && (!Array.isArray(config.disabled_cli_versions) || config.disabled_cli_versions.length > 20
+                    || !config.disabled_cli_versions.every(version => matchesTelemetryFormat('version', version)))))
+            return null;
+        return {
+            schema_version: TELEMETRY_SCHEMA_VERSION,
+            enabled: config.enabled,
+            install_id: config.install_id,
+            ...(config.notice_shown_at ? { notice_shown_at: config.notice_shown_at } : {}),
+            ...(config.disabled_cli_versions ? { disabled_cli_versions: config.disabled_cli_versions } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/utils/telemetry/config-store.d.ts

@@ -0,0 +1,35 @@
+import { type TelemetryConfig } from './config-schema.js';
+import { type SettingsLockIdentity } from './settings-lock.js';
+export interface TelemetryConfigDependencies {
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly platform?: NodeJS.Platform;
+    readonly configDirectory?: string;
+    /** Lock owner identity; tests use it to model separate processes. */
+    readonly lockIdentity?: SettingsLockIdentity;
+}
+/**
+ * Waits, bounded, for in-progress settings writes to release their lock. The
+ * executable calls this before exiting, including on signals: process.exit()
+ * skips `finally` blocks, and a stranded lock would make every later
+ * preference change fail until someone removed it by hand.
+ */
+export declare function settleTelemetrySettings(timeoutMs?: number): Promise<void>;
+export declare class TelemetryConfigStore {
+    private readonly dependencies;
+    private readonly env;
+    private readonly platform;
+    constructor(dependencies?: TelemetryConfigDependencies);
+    private directory;
+    /** Read/create settings only when collection is allowed. All failures fail closed. */
+    load(): Promise<TelemetryConfig | null>;
+    /** Inspect without creating an identity or changing a disabled installation. */
+    peek(): Promise<TelemetryConfig | null>;
+    setEnabled(enabled: boolean): Promise<TelemetryConfig | null>;
+    /** Serialize display and persistence so concurrent interactive runs show one notice. */
+    showNotice(write: () => Promise<void>, now?: Date): Promise<TelemetryConfig | null>;
+    /** Kill switch from an HTTP 410. One immediate lock attempt; never waits for another writer. */
+    disableVersion(version: string): Promise<TelemetryConfig | null>;
+    private update;
+    private locked;
+}
+//# sourceMappingURL=config-store.d.ts.map

package/dist/utils/telemetry/config-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-store.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/config-store.ts"],"names":[],"mappings":"AAIA,OAAO,EAAkD,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1G,OAAO,EAA0C,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAEvG,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC5D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IACpC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,qEAAqE;IACrE,QAAQ,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAC;CAC9C;AAKD;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAAC,SAAS,SAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ5E;AAED,qBAAa,oBAAoB;IAInB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAHzC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA+C;IACnE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;gBAEd,YAAY,GAAE,2BAAgC;YAK7D,SAAS;IAUvB,sFAAsF;IAChF,IAAI,IAAI,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAI7C,gFAAgF;IAC1E,IAAI,IAAI,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAWvC,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAInE,wFAAwF;IAClF,UAAU,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,OAAa,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAQ/F,gGAAgG;IAC1F,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAQtE,OAAO,CAAC,MAAM;YAYA,MAAM;CAkDrB"}

package/dist/utils/telemetry/config-store.js

@@ -0,0 +1,147 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { configDirectory } from '../config-directory.js';
+import { parseTelemetryConfig, TELEMETRY_SCHEMA_VERSION } from './config-schema.js';
+import { matchesTelemetryFormat } from './value-formats.js';
+import { acquireSettingsLock } from './settings-lock.js';
+/** Settings writes in progress; each holds the cross-process lock until it settles. */
+const activeWrites = new Set();
+/**
+ * Waits, bounded, for in-progress settings writes to release their lock. The
+ * executable calls this before exiting, including on signals: process.exit()
+ * skips `finally` blocks, and a stranded lock would make every later
+ * preference change fail until someone removed it by hand.
+ */
+export async function settleTelemetrySettings(timeoutMs = 250) {
+    if (activeWrites.size === 0)
+        return;
+    let timer;
+    await Promise.race([
+        Promise.allSettled([...activeWrites]),
+        new Promise(resolve => { timer = setTimeout(resolve, timeoutMs); timer.unref(); }),
+    ]);
+    clearTimeout(timer);
+}
+export class TelemetryConfigStore {
+    dependencies;
+    env;
+    platform;
+    constructor(dependencies = {}) {
+        this.dependencies = dependencies;
+        this.env = dependencies.env ?? process.env;
+        this.platform = dependencies.platform ?? process.platform;
+    }
+    async directory() {
+        if (this.dependencies.configDirectory)
+            return this.dependencies.configDirectory;
+        const home = this.platform === 'win32' ? this.env.USERPROFILE : this.env.HOME;
+        const explicit = this.env.HYPEQUERY_CONFIG_DIR
+            || (this.platform === 'win32' ? this.env.APPDATA || this.env.LOCALAPPDATA
+                : this.platform !== 'darwin' ? this.env.XDG_CONFIG_HOME : undefined);
+        if (!explicit && (!home || !(await stat(home)).isDirectory()))
+            return null;
+        return configDirectory(this.env, this.platform, home ?? '');
+    }
+    /** Read/create settings only when collection is allowed. All failures fail closed. */
+    async load() {
+        return this.update();
+    }
+    /** Inspect without creating an identity or changing a disabled installation. */
+    async peek() {
+        try {
+            const directory = await this.directory();
+            return directory
+                ? parseTelemetryConfig(await readFile(path.join(directory, 'telemetry.json'), 'utf8'))
+                : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async setEnabled(enabled) {
+        return this.update(enabled);
+    }
+    /** Serialize display and persistence so concurrent interactive runs show one notice. */
+    async showNotice(write, now = new Date()) {
+        return this.update(undefined, async (config) => {
+            if (!config.enabled || config.notice_shown_at)
+                return config;
+            await write();
+            return { ...config, notice_shown_at: now.toISOString() };
+        });
+    }
+    /** Kill switch from an HTTP 410. One immediate lock attempt; never waits for another writer. */
+    async disableVersion(version) {
+        if (!matchesTelemetryFormat('version', version))
+            return null;
+        return this.update(undefined, async (config) => ({
+            ...config,
+            disabled_cli_versions: [...new Set([...(config.disabled_cli_versions ?? []), version])].slice(-20),
+        }), 1, true);
+    }
+    update(enabled, mutate, lockAttempts = 20, requireExisting = false) {
+        const write = this.locked(enabled, mutate, lockAttempts, requireExisting);
+        activeWrites.add(write);
+        void write.finally(() => activeWrites.delete(write));
+        return write;
+    }
+    async locked(enabled, mutate, lockAttempts, requireExisting) {
+        let lock = null;
+        let temporary;
+        try {
+            const directory = await this.directory();
+            if (!directory)
+                return null;
+            await mkdir(directory, { recursive: true, mode: 0o700 });
+            // Serialize read-modify-write across processes, including first identity
+            // creation. A live writer's lock fails closed however long it is held; a
+            // lock whose owner process has died is taken over (see settings-lock.ts).
+            lock = await acquireSettingsLock(directory, lockAttempts, this.dependencies.lockIdentity);
+            if (!lock)
+                return null;
+            const file = path.join(directory, 'telemetry.json');
+            let previous = null;
+            try {
+                previous = parseTelemetryConfig(await readFile(file, 'utf8'));
+                // Explicit enable/disable can repair settings; ordinary commands cannot.
+                if (!previous && enabled === undefined)
+                    return null;
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            // The kill switch only amends settings that collection already created.
+            if (!previous && requireExisting)
+                return null;
+            let config = {
+                schema_version: TELEMETRY_SCHEMA_VERSION,
+                install_id: previous?.install_id ?? randomUUID(),
+                enabled: enabled ?? previous?.enabled ?? true,
+                ...(previous?.notice_shown_at ? { notice_shown_at: previous.notice_shown_at } : {}),
+                ...(previous?.disabled_cli_versions ? { disabled_cli_versions: previous.disabled_cli_versions } : {}),
+            };
+            if (previous && enabled === undefined)
+                config = previous;
+            if (mutate)
+                config = await mutate(config);
+            if (previous && enabled === undefined && (!mutate || config === previous))
+                return previous;
+            temporary = `${file}.${randomUUID()}.tmp`;
+            await writeFile(temporary, `${JSON.stringify(config, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+            await rename(temporary, file);
+            return config;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            if (temporary)
+                await unlink(temporary).catch(() => undefined);
+            // Releases only this writer's ownership, never a lock taken over by another.
+            if (lock)
+                await lock.release();
+        }
+    }
+}

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

@@ -0,0 +1,13 @@
+import { type PostJson } from './post-json.js';
+/** Runs in the detached sender, so this budget never delays the CLI's own exit. */
+export declare const DELIVERY_TIMEOUT_MS = 5000;
+export interface DeliveryOptions {
+    /** Injectable for tests; defaults to an exit-safe node:http(s) POST. */
+    readonly post?: PostJson;
+    readonly timeoutMs?: number;
+    /** The proxy owns the real PostHog API key. 410 disables this CLI version. */
+    readonly onDisabled?: () => Promise<unknown>;
+}
+/** One bounded attempt with no retries; every failure is swallowed. */
+export declare function deliverBatch(url: URL, body: string, options?: DeliveryOptions): Promise<void>;
+//# sourceMappingURL=delivery.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"delivery.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/delivery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAEzD,mFAAmF;AACnF,eAAO,MAAM,mBAAmB,OAAQ,CAAC;AAEzC,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9C;AAED,uEAAuE;AACvE,wBAAsB,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAevG"}

package/dist/utils/telemetry/delivery.js

@@ -0,0 +1,26 @@
+import { postJson } from './post-json.js';
+/** Runs in the detached sender, so this budget never delays the CLI's own exit. */
+export const DELIVERY_TIMEOUT_MS = 5_000;
+/** One bounded attempt with no retries; every failure is swallowed. */
+export async function deliverBatch(url, body, options = {}) {
+    let timer;
+    const controller = new AbortController();
+    try {
+        const timeout = new Promise(resolve => {
+            timer = setTimeout(() => { controller.abort(); resolve(); }, options.timeoutMs ?? DELIVERY_TIMEOUT_MS);
+            timer.unref();
+        });
+        const request = (async () => {
+            const status = await (options.post ?? postJson)(url, body, controller.signal);
+            if (status === 410 && !controller.signal.aborted)
+                await options.onDisabled?.();
+        })().catch(() => undefined);
+        await Promise.race([request, timeout]);
+    }
+    catch { /* DNS/TLS/HTTP/abort/synchronous failures are dropped. */ }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        controller.abort();
+    }
+}

package/dist/utils/telemetry/detached-dispatch.d.ts

@@ -0,0 +1,12 @@
+/** Hands one serialized batch to delivery; must return without waiting on the network. */
+export type DispatchBatch = (url: URL, body: string) => void;
+export declare const BATCH_DIRECTORY_PREFIX = "hypequery-telemetry-";
+export declare const BATCH_FILE = "batch.json";
+/**
+ * The CLI's exit budget is too short for a TLS handshake plus a serverless cold
+ * start, so a detached child delivers the batch and the command exits at once.
+ * The batch travels through a private temporary file: argv and env are capped
+ * near 32 KiB on Windows, and pipe writes still buffered at exit are lost.
+ */
+export declare const dispatchDetached: DispatchBatch;
+//# sourceMappingURL=detached-dispatch.d.ts.map

package/dist/utils/telemetry/detached-dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detached-dispatch.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/detached-dispatch.ts"],"names":[],"mappings":"AAMA,0FAA0F;AAC1F,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AAE7D,eAAO,MAAM,sBAAsB,yBAAyB,CAAC;AAC7D,eAAO,MAAM,UAAU,eAAe,CAAC;AAOvC;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,aAW9B,CAAC"}

package/dist/utils/telemetry/detached-dispatch.js

@@ -0,0 +1,33 @@
+import { spawn } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const BATCH_DIRECTORY_PREFIX = 'hypequery-telemetry-';
+export const BATCH_FILE = 'batch.json';
+const SENDER = fileURLToPath(new URL('./detached-sender.js', import.meta.url));
+function removeQuietly(directory) {
+    try {
+        rmSync(directory, { recursive: true, force: true });
+    }
+    catch { /* A stray temporary file is harmless. */ }
+}
+/**
+ * The CLI's exit budget is too short for a TLS handshake plus a serverless cold
+ * start, so a detached child delivers the batch and the command exits at once.
+ * The batch travels through a private temporary file: argv and env are capped
+ * near 32 KiB on Windows, and pipe writes still buffered at exit are lost.
+ */
+export const dispatchDetached = (url, body) => {
+    const directory = mkdtempSync(path.join(tmpdir(), BATCH_DIRECTORY_PREFIX));
+    try {
+        writeFileSync(path.join(directory, BATCH_FILE), JSON.stringify({ endpoint: url.href, body }), { mode: 0o600, flag: 'wx' });
+        const child = spawn(process.execPath, [SENDER, directory], { detached: true, stdio: 'ignore', windowsHide: true });
+        child.on('error', () => { removeQuietly(directory); });
+        child.unref();
+    }
+    catch (error) {
+        removeQuietly(directory);
+        throw error;
+    }
+};

package/dist/utils/telemetry/detached-sender.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=detached-sender.d.ts.map

package/dist/utils/telemetry/detached-sender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detached-sender.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/detached-sender.ts"],"names":[],"mappings":""}

package/dist/utils/telemetry/detached-sender.js

@@ -0,0 +1,31 @@
+import { readFile, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { getCliVersion } from '../cli-version.js';
+import { deliverBatch } from './delivery.js';
+import { BATCH_DIRECTORY_PREFIX, BATCH_FILE } from './detached-dispatch.js';
+import { telemetryEndpoint } from './endpoint.js';
+/** Entry point of the child started by dispatchDetached; the CLI never imports it. */
+async function send(directory) {
+    if (!directory || !path.basename(directory).startsWith(BATCH_DIRECTORY_PREFIX))
+        return;
+    let batch;
+    try {
+        batch = JSON.parse(await readFile(path.join(directory, BATCH_FILE), 'utf8'));
+    }
+    finally {
+        await rm(directory, { recursive: true, force: true });
+    }
+    if (!batch || typeof batch !== 'object')
+        return;
+    const { endpoint, body } = batch;
+    const url = telemetryEndpoint(typeof endpoint === 'string' ? endpoint : undefined);
+    if (!url || typeof body !== 'string')
+        return;
+    await deliverBatch(url, body, {
+        onDisabled: async () => {
+            const { TelemetryConfigStore } = await import('./config-store.js');
+            return new TelemetryConfigStore().disableVersion(getCliVersion());
+        },
+    });
+}
+await send(process.argv[2]).catch(() => undefined);

package/dist/utils/telemetry/dev-session.d.ts

@@ -0,0 +1,15 @@
+import type { DevOptions } from '../../commands/dev.js';
+import { type SessionEnd } from './command-context.js';
+import type { ERROR_CODES } from './domains.js';
+/** Counters only: no retained API, reload paths, errors, queries, or requests. */
+export declare class DevSession {
+    private reloads;
+    private reloadErrors;
+    private failures;
+    start(resolved: string, explicit: string | undefined, options: DevOptions): void;
+    reload(): void;
+    reloadFailed(): void;
+    loadFailed(error: unknown): typeof ERROR_CODES[number];
+    snapshot(): SessionEnd<'dev'>;
+}
+//# sourceMappingURL=dev-session.d.ts.map

package/dist/utils/telemetry/dev-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-session.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/dev-session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD,OAAO,EAAuB,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAG5E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,kFAAkF;AAClF,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,QAAQ,CAA2D;IAE3E,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI;IAIhF,MAAM,IAAI,IAAI;IACd,YAAY,IAAI,IAAI;IAEpB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,WAAW,CAAC,MAAM,CAAC;IAOtD,QAAQ,IAAI,UAAU,CAAC,KAAK,CAAC;CAI9B"}