@hypequery/cli 1.22.0 → 1.23.0

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

@@ -0,0 +1,22 @@
+import { COMMON_PROPERTIES, type TelemetryEvent } from './catalog.js';
+import type { Properties } from './schema.js';
+import { type EnvironmentOptions } from './environment.js';
+import { type TelemetryResolutionOptions } from './opt-out.js';
+import { type TransportOptions } from './transport.js';
+export type CommonTelemetryProperties = Properties<typeof COMMON_PROPERTIES>;
+export interface InvocationOptions extends TelemetryResolutionOptions {
+    readonly cwd?: string;
+    readonly command: string;
+    readonly contextOptions?: EnvironmentOptions;
+    readonly transportOptions?: Partial<TransportOptions>;
+}
+/** One common context and transport per invocation; no automatic user-code loading. */
+export declare class TelemetryInvocation {
+    readonly common: CommonTelemetryProperties;
+    private readonly transport;
+    private constructor();
+    static create(options: InvocationOptions): Promise<TelemetryInvocation | null>;
+    record(event: TelemetryEvent): void;
+    flush(): Promise<void>;
+}
+//# sourceMappingURL=invocation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"invocation.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/invocation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAG/E,OAAO,EAAyB,KAAK,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAEtF,OAAO,EAAsB,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAG3E,MAAM,MAAM,yBAAyB,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC7E,MAAM,WAAW,iBAAkB,SAAQ,0BAA0B;IACnE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,CAAC,EAAE,kBAAkB,CAAC;IAC7C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACvD;AAED,uFAAuF;AACvF,qBAAa,mBAAmB;IAEV,QAAQ,CAAC,MAAM,EAAE,yBAAyB;IAD9D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO;WAIM,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IAuBpF,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IACnC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CACvB"}

package/dist/utils/telemetry/invocation.js

@@ -0,0 +1,46 @@
+import { collectEnvironment } from './environment.js';
+import { inspectProject } from './project-context.js';
+import { invocationIdentity } from './identity.js';
+import { resolveTelemetryState } from './opt-out.js';
+import { showTelemetryNotice } from './notice.js';
+import { TelemetryTransport } from './transport.js';
+import { getCliVersion } from '../cli-version.js';
+/** One common context and transport per invocation; no automatic user-code loading. */
+export class TelemetryInvocation {
+    common;
+    transport;
+    constructor(common, options) {
+        this.common = common;
+        this.transport = new TelemetryTransport(options);
+    }
+    static async create(options) {
+        try {
+            const env = options.env ?? process.env;
+            // Collection is staged until the first-party proxy and rollout are ready.
+            // Normal runs do not inspect projects or create identities just for telemetry.
+            if (!env.HYPEQUERY_TELEMETRY_URL && env.HYPEQUERY_TELEMETRY_DEBUG !== '1')
+                return null;
+            if (options.command === 'telemetry')
+                return null;
+            const cliVersion = options.cliVersion ?? getCliVersion();
+            const state = await resolveTelemetryState({ ...options, cliVersion });
+            if (!state.enabled || !state.config)
+                return null;
+            const project = inspectProject(options.cwd ?? process.cwd(), options.contextOptions?.read);
+            const environment = collectEnvironment(project, { ...options.contextOptions, env, cliVersion });
+            const common = { ...environment, ...invocationIdentity(state.config, project), is_first_run: state.source === 'default' };
+            const invocation = new TelemetryInvocation(common, {
+                ...options.transportOptions,
+                enabled: true, endpoint: env.HYPEQUERY_TELEMETRY_URL,
+                debug: env.HYPEQUERY_TELEMETRY_DEBUG === '1',
+            });
+            await showTelemetryNotice({ ...options, enabled: true, isTTY: common.is_tty, isCI: common.is_ci });
+            return invocation;
+        }
+        catch {
+            return null;
+        }
+    }
+    record(event) { this.transport.enqueue(event); }
+    flush() { return this.transport.flush(); }
+}

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

@@ -0,0 +1,32 @@
+import type { TelemetryCommand } from './domains.js';
+import { type InvocationOptions } from './invocation.js';
+import { CommandExit } from '../command-exit.js';
+import type { CommandMetrics, SessionCommand, SessionStart, SessionEnd } from './command-context.js';
+import type { ERROR_CODES } from './domains.js';
+export declare class CommandLifecycle {
+    private readonly args;
+    private readonly options;
+    private invocation?;
+    private completed;
+    private started;
+    private interrupted;
+    private cancelled;
+    private metrics;
+    private errorCode?;
+    private session?;
+    command: TelemetryCommand;
+    constructor(args: readonly string[], options?: Omit<InvocationOptions, 'command'>);
+    /** Never rejects: telemetry setup must not affect the command it observes. */
+    begin(command: string, database?: string): Promise<void>;
+    markInterrupted(): void;
+    update<C extends TelemetryCommand>(command: C, metrics: CommandMetrics<C>): void;
+    cancel(): void;
+    setError(code: typeof ERROR_CODES[number]): void;
+    startSession<C extends SessionCommand>(command: C, start: SessionStart<C>, end: () => SessionEnd<C>): void;
+    /** Never rejects: a telemetry failure must not change the command's exit or skip cleanup. */
+    finish(exit: CommandExit, helpTopic?: string): Promise<void>;
+    private record;
+    /** Node retains its native fatal-error output/exit; delivery here is best-effort. */
+    crash(error: unknown): void;
+}
+//# sourceMappingURL=lifecycle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/lifecycle.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD,OAAO,EAAuB,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC9E,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACrG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,qBAAa,gBAAgB;IAWf,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAqB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAV9E,OAAO,CAAC,UAAU,CAAC,CAA6B;IAChD,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,SAAS,CAAC,CAA6B;IAC/C,OAAO,CAAC,OAAO,CAAC,CAAkE;IAClF,OAAO,EAAE,gBAAgB,CAAa;gBAET,IAAI,EAAE,SAAS,MAAM,EAAE,EAAmB,OAAO,GAAE,IAAI,CAAC,iBAAiB,EAAE,SAAS,CAAM;IAEvH,8EAA8E;IACxE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY9D,eAAe,IAAI,IAAI;IAEvB,MAAM,CAAC,CAAC,SAAS,gBAAgB,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI;IAKhF,MAAM,IAAI,IAAI;IAEd,QAAQ,CAAC,IAAI,EAAE,OAAO,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI;IAEhD,YAAY,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;IAM1G,6FAA6F;IACvF,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YASpD,MAAM;IAyBpB,qFAAqF;IACrF,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;CAQ5B"}

package/dist/utils/telemetry/lifecycle.js

@@ -0,0 +1,99 @@
+import { durationBucket } from './buckets.js';
+import { flagNames, knownCommand } from './flags.js';
+import { TelemetryInvocation } from './invocation.js';
+import { CommandExit } from '../command-exit.js';
+import { exceptionClass, telemetryErrorCode } from './error-code.js';
+export class CommandLifecycle {
+    args;
+    options;
+    invocation;
+    completed = false;
+    started = performance.now();
+    interrupted = false;
+    cancelled = false;
+    metrics = {};
+    errorCode;
+    session;
+    command = 'unknown';
+    constructor(args, options = {}) {
+        this.args = args;
+        this.options = options;
+    }
+    /** Never rejects: telemetry setup must not affect the command it observes. */
+    async begin(command, database) {
+        try {
+            this.command = knownCommand(command);
+            if (this.invocation !== undefined)
+                return;
+            this.started = performance.now();
+            this.invocation = await TelemetryInvocation.create({ ...this.options, command: this.command,
+                contextOptions: { ...this.options.contextOptions, database } });
+        }
+        catch {
+            this.invocation = null;
+        }
+    }
+    markInterrupted() { this.interrupted = true; }
+    update(command, metrics) {
+        if (command !== this.command || this.completed)
+            return;
+        this.metrics = { ...this.metrics, ...Object.fromEntries(Object.entries(metrics).filter(([, value]) => value !== undefined)) };
+    }
+    cancel() { this.cancelled = true; }
+    setError(code) { this.errorCode = code; }
+    startSession(command, start, end) {
+        if (!this.invocation || this.completed || this.session || command !== this.command)
+            return;
+        this.invocation.record({ event: 'cli_session_started', properties: { ...this.invocation.common, ...start, command } });
+        this.session = { command, started: performance.now(), end };
+    }
+    /** Never rejects: a telemetry failure must not change the command's exit or skip cleanup. */
+    async finish(exit, helpTopic) {
+        if (this.completed)
+            return;
+        this.completed = true;
+        if (!this.invocation)
+            return;
+        try {
+            await this.record(exit, helpTopic);
+        }
+        catch { /* Delivery is best-effort; the command's own outcome stands. */ }
+    }
+    async record(exit, helpTopic) {
+        if (!this.invocation)
+            return;
+        const outcome = this.interrupted ? 'interrupted' : this.cancelled && exit.outcome === 'success' ? 'cancelled' : exit.outcome;
+        const errorCode = exit.errorCode && exit.errorCode !== 'unknown' ? exit.errorCode : this.errorCode ?? exit.errorCode;
+        if (this.session) {
+            try {
+                this.invocation.record({ event: 'cli_session_ended', properties: {
+                        ...this.invocation.common, ...this.session.end(), command: this.session.command, outcome,
+                        duration_bucket: durationBucket(performance.now() - this.session.started),
+                    } });
+            }
+            catch { /* Broken optional counters must not suppress command completion. */ }
+        }
+        const properties = {
+            ...this.invocation.common, ...this.metrics, command: this.command,
+            flags_used: flagNames(this.command, this.args),
+            outcome,
+            duration_bucket: durationBucket(performance.now() - this.started),
+            ...(errorCode && exit.outcome === 'failure' ? { error_code: errorCode } : exit.errorCode ? { error_code: exit.errorCode } : {}),
+            ...(this.command === 'help' ? { help_topic: helpTopic ? knownCommand(helpTopic) : 'root' } : {}),
+        };
+        // Dynamic command discrimination is validated again by the transport.
+        this.invocation.record({ event: 'cli_command_completed', properties });
+        await this.invocation.flush();
+    }
+    /** Node retains its native fatal-error output/exit; delivery here is best-effort. */
+    crash(error) {
+        try {
+            if (!this.invocation || this.completed)
+                return;
+            this.invocation.record({ event: 'cli_crash', properties: { ...this.invocation.common,
+                    command: this.command, exception_class: exceptionClass(error), error_code: telemetryErrorCode(error) } });
+            void this.finish(new CommandExit(1, 'failure', telemetryErrorCode(error))).catch(() => undefined);
+        }
+        catch { /* Preserve Node's original fatal error even for hostile thrown objects. */ }
+    }
+}

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

@@ -0,0 +1,10 @@
+import type { MCPToolExecutor } from '@hypequery/mcp';
+import { type SessionStart, type SessionEnd } from './command-context.js';
+export declare class McpSession {
+    private calls;
+    private errors;
+    start(properties: SessionStart<'mcp'>): void;
+    instrument(executor: MCPToolExecutor): MCPToolExecutor;
+    snapshot(): SessionEnd<'mcp'>;
+}
+//# sourceMappingURL=mcp-session.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-session.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/mcp-session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD,OAAO,EAAuB,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAM/F,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAAsC;IACnD,OAAO,CAAC,MAAM,CAAK;IAEnB,KAAK,CAAC,UAAU,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,IAAI;IAI5C,UAAU,CAAC,QAAQ,EAAE,eAAe,GAAG,eAAe;IAetD,QAAQ,IAAI,UAAU,CAAC,KAAK,CAAC;CAI9B"}

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

@@ -0,0 +1,36 @@
+import { countBucket } from './buckets.js';
+import { startCommandSession } from './command-context.js';
+const toolKinds = {
+    list_datasets: 'list', get_dataset_schema: 'describe', query_dataset: 'query', query_metric: 'query',
+};
+export class McpSession {
+    calls = { list: 0, describe: 0, query: 0 };
+    errors = 0;
+    start(properties) {
+        startCommandSession('mcp', properties, () => this.snapshot());
+    }
+    instrument(executor) {
+        return {
+            listTools: () => executor.listTools(), listPrompts: () => executor.listPrompts(),
+            getPrompt: (name, args) => executor.getPrompt(name, args), getManifestHash: () => executor.getManifestHash(),
+            callTool: async (name, args, signal) => {
+                if (Object.hasOwn(toolKinds, name))
+                    this.calls[toolKinds[name]]++;
+                try {
+                    const result = await executor.callTool(name, args, signal);
+                    if (result.isError)
+                        this.errors++;
+                    return result;
+                }
+                catch (error) {
+                    this.errors++;
+                    throw error;
+                }
+            },
+        };
+    }
+    snapshot() {
+        return { tool_call_counts: { list: countBucket(this.calls.list), describe: countBucket(this.calls.describe), query: countBucket(this.calls.query) },
+            error_count_bucket: countBucket(this.errors) };
+    }
+}

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

@@ -0,0 +1,11 @@
+import { type TelemetryConfigDependencies } from './config-store.js';
+export declare const TELEMETRY_NOTICE: string;
+export interface NoticeOptions extends TelemetryConfigDependencies {
+    readonly enabled: boolean;
+    readonly command: string;
+    readonly isTTY: boolean;
+    readonly isCI: boolean;
+    readonly write?: (text: string) => Promise<void>;
+}
+export declare function showTelemetryNotice(options: NoticeOptions): Promise<void>;
+//# sourceMappingURL=notice.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"notice.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/notice.ts"],"names":[],"mappings":"AACA,OAAO,EAAwB,KAAK,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAE3F,eAAO,MAAM,gBAAgB,QAMjB,CAAC;AAEb,MAAM,WAAW,aAAc,SAAQ,2BAA2B;IAChE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAClD;AAED,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAU/E"}

package/dist/utils/telemetry/notice.js

@@ -0,0 +1,24 @@
+import { TELEMETRY_DOCS_URL } from './config-schema.js';
+import { TelemetryConfigStore } from './config-store.js';
+export const TELEMETRY_NOTICE = [
+    'Hypequery collects pseudonymous CLI usage to prioritise the roadmap.',
+    'Never code, SQL, names, paths or credentials.',
+    'Disable: hypequery telemetry disable, HYPEQUERY_TELEMETRY_DISABLED=1, or DO_NOT_TRACK=1.',
+    `Details: ${TELEMETRY_DOCS_URL}`,
+    '',
+].join('\n');
+export async function showTelemetryNotice(options) {
+    if (!options.enabled || !options.isTTY || options.isCI || options.command === 'mcp' || options.command === 'telemetry')
+        return;
+    try {
+        await new TelemetryConfigStore(options).showNotice(async () => {
+            if (options.write)
+                await options.write(TELEMETRY_NOTICE);
+            else
+                await new Promise((resolve, reject) => {
+                    process.stderr.write(TELEMETRY_NOTICE, error => error ? reject(error) : resolve());
+                });
+        });
+    }
+    catch { /* A failed disclosure write must not affect the command. */ }
+}

package/dist/utils/telemetry/opt-out.d.ts

@@ -0,0 +1,16 @@
+import { type TelemetryConfigDependencies } from './config-store.js';
+import type { TelemetryConfig } from './config-schema.js';
+export type TelemetrySource = 'flag' | 'DO_NOT_TRACK' | 'HYPEQUERY_TELEMETRY_DISABLED' | 'test' | 'hypequery_ci' | 'config' | 'default' | 'config_unavailable' | 'kill_switch';
+export interface TelemetryState {
+    readonly enabled: boolean;
+    readonly source: TelemetrySource;
+    readonly config: TelemetryConfig | null;
+}
+export interface TelemetryResolutionOptions extends TelemetryConfigDependencies {
+    readonly telemetry?: boolean;
+    readonly cliVersion?: string;
+}
+/** First matching opt-out wins; customer CI is intentionally eligible. */
+export declare function telemetryOptOutSource(options: TelemetryResolutionOptions): TelemetrySource | null;
+export declare function resolveTelemetryState(options?: TelemetryResolutionOptions): Promise<TelemetryState>;
+//# sourceMappingURL=opt-out.d.ts.map

package/dist/utils/telemetry/opt-out.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"opt-out.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/opt-out.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAC3F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAG1D,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,cAAc,GAAG,8BAA8B,GAClF,MAAM,GAAG,cAAc,GAAG,QAAQ,GAAG,SAAS,GAAG,oBAAoB,GAAG,aAAa,CAAC;AAE1F,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;CACzC;AAED,MAAM,WAAW,0BAA2B,SAAQ,2BAA2B;IAC7E,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,0EAA0E;AAC1E,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,0BAA0B,GAClC,eAAe,GAAG,IAAI,CAUxB;AAED,wBAAsB,qBAAqB,CACzC,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,cAAc,CAAC,CAWzB"}

package/dist/utils/telemetry/opt-out.js

@@ -0,0 +1,32 @@
+import { TelemetryConfigStore } from './config-store.js';
+import { getCliVersion } from '../cli-version.js';
+/** First matching opt-out wins; customer CI is intentionally eligible. */
+export function telemetryOptOutSource(options) {
+    const env = options.env ?? process.env;
+    if (options.telemetry === false)
+        return 'flag';
+    if (env.DO_NOT_TRACK === '1')
+        return 'DO_NOT_TRACK';
+    if (env.HYPEQUERY_TELEMETRY_DISABLED === '1')
+        return 'HYPEQUERY_TELEMETRY_DISABLED';
+    if (env.VITEST || env.NODE_ENV === 'test')
+        return 'test';
+    if (env.GITHUB_ACTIONS === 'true' && env.GITHUB_REPOSITORY?.toLowerCase() === 'hypequery/hypequery') {
+        return 'hypequery_ci';
+    }
+    return null;
+}
+export async function resolveTelemetryState(options = {}) {
+    const store = new TelemetryConfigStore(options);
+    const source = telemetryOptOutSource(options);
+    if (source)
+        return { enabled: false, source, config: await store.peek() };
+    const existing = await store.peek();
+    const config = await store.load();
+    if (!config)
+        return { enabled: false, source: 'config_unavailable', config: null };
+    if (config.disabled_cli_versions?.includes(options.cliVersion ?? getCliVersion())) {
+        return { enabled: false, source: 'kill_switch', config };
+    }
+    return { enabled: config.enabled, source: existing ? 'config' : 'default', config };
+}

package/dist/utils/telemetry/post-json.d.ts

@@ -0,0 +1,13 @@
+/** Posts a telemetry body and resolves the HTTP status; a pending send never delays exit. */
+export type PostJson = (url: URL, body: string, signal: AbortSignal) => Promise<number>;
+/**
+ * Built-in fetch is not used: aborting it rejects on time, but its in-progress
+ * TCP or TLS connect keeps the process alive until the connect timeout (about
+ * 10 s for an unreachable host). Here abort destroys the socket, including
+ * mid-connect, so the CLI exits once the bounded flush returns. The socket stays
+ * referenced until then: unreferencing it would let the process exit before a
+ * remote endpoint even connects, silently dropping events within the budget.
+ * Node's client never follows redirects, so a 3xx response is simply returned.
+ */
+export declare const postJson: PostJson;
+//# sourceMappingURL=post-json.d.ts.map

package/dist/utils/telemetry/post-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-json.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/post-json.ts"],"names":[],"mappings":"AAGA,6FAA6F;AAC7F,MAAM,MAAM,QAAQ,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAExF;;;;;;;;GAQG;AACH,eAAO,MAAM,QAAQ,EAAE,QAiBrB,CAAC"}

package/dist/utils/telemetry/post-json.js

@@ -0,0 +1,32 @@
+import http from 'node:http';
+import https from 'node:https';
+/**
+ * Built-in fetch is not used: aborting it rejects on time, but its in-progress
+ * TCP or TLS connect keeps the process alive until the connect timeout (about
+ * 10 s for an unreachable host). Here abort destroys the socket, including
+ * mid-connect, so the CLI exits once the bounded flush returns. The socket stays
+ * referenced until then: unreferencing it would let the process exit before a
+ * remote endpoint even connects, silently dropping events within the budget.
+ * Node's client never follows redirects, so a 3xx response is simply returned.
+ */
+export const postJson = (url, body, signal) => new Promise((resolve, reject) => {
+    const client = url.protocol === 'https:' ? https : http;
+    const request = client.request(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) },
+        agent: false,
+    }, response => {
+        resolve(response.statusCode ?? 0);
+        response.resume();
+        request.destroy();
+    });
+    const abort = () => request.destroy(new Error('Telemetry request aborted'));
+    if (signal.aborted) {
+        abort();
+        return;
+    }
+    signal.addEventListener('abort', abort, { once: true });
+    request.on('error', reject);
+    request.on('close', () => signal.removeEventListener('abort', abort));
+    request.end(body);
+});

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

@@ -0,0 +1,15 @@
+export type ReadLocalFile = (file: string) => string | undefined;
+export interface ProjectContext {
+    readonly directory?: string;
+    readonly rootDirectory?: string;
+    readonly package?: Record<string, unknown>;
+    readonly rootPackage?: Record<string, unknown>;
+    readonly remote?: string;
+}
+/** Bounded regular-file reads only; local inspection never shells out or loads user code. */
+export declare function readTelemetryFile(file: string): string | undefined;
+export declare function readPackage(file: string, read: ReadLocalFile): Record<string, unknown> | undefined;
+export declare function remoteFromGitConfig(config: string | undefined): string | undefined;
+/** Finds the workspace root and linked-worktree git config within a small local I/O budget. */
+export declare function inspectProject(cwd: string, read?: ReadLocalFile, budgetMs?: number): ProjectContext;
+//# sourceMappingURL=project-context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"project-context.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/project-context.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;AACjE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,6FAA6F;AAC7F,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMlE;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAMlG;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAgBlF;AAED,+FAA+F;AAC/F,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,aAAiC,EACvC,QAAQ,SAAI,GACX,cAAc,CA6BhB"}

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

@@ -0,0 +1,86 @@
+import { readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { performance } from 'node:perf_hooks';
+/** Bounded regular-file reads only; local inspection never shells out or loads user code. */
+export function readTelemetryFile(file) {
+    try {
+        const info = statSync(file);
+        if (!info.isFile() || info.size > 64 * 1024)
+            return undefined;
+        return readFileSync(file, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readPackage(file, read) {
+    try {
+        const value = JSON.parse(read(file) ?? 'null');
+        return value && typeof value === 'object' && !Array.isArray(value)
+            ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function remoteFromGitConfig(config) {
+    let remote = false;
+    let origin = false;
+    let fallback;
+    for (const line of (config ?? '').split(/\r?\n/)) {
+        const section = line.trim().match(/^\[remote\s+"([^"]+)"\]$/);
+        if (section) {
+            remote = true;
+            origin = section[1] === 'origin';
+            continue;
+        }
+        if (line.trim().startsWith('[')) {
+            remote = false;
+            continue;
+        }
+        const url = remote ? line.match(/^\s*url\s*=\s*(.*?)\s*$/i)?.[1] : undefined;
+        if (url) {
+            const unquoted = url.startsWith('"') && url.endsWith('"') ? url.slice(1, -1) : url;
+            if (origin)
+                return unquoted;
+            fallback ??= unquoted;
+        }
+    }
+    return fallback;
+}
+/** Finds the workspace root and linked-worktree git config within a small local I/O budget. */
+export function inspectProject(cwd, read = readTelemetryFile, budgetMs = 5) {
+    const deadline = performance.now() + budgetMs;
+    let context = {};
+    try {
+        let directory = path.resolve(cwd);
+        for (let depth = 0; depth < 24 && performance.now() < deadline; depth++) {
+            const pkg = readPackage(path.join(directory, 'package.json'), read);
+            if (!context.directory && pkg)
+                context = { ...context, directory, package: pkg };
+            if (pkg && (pkg.workspaces || read(path.join(directory, 'pnpm-workspace.yaml')) !== undefined)) {
+                context = { ...context, rootDirectory: directory, rootPackage: pkg };
+            }
+            let gitDirectory = path.join(directory, '.git');
+            const gitFile = read(gitDirectory)?.match(/^gitdir:\s*(.+?)\s*$/)?.[1];
+            if (gitFile)
+                gitDirectory = path.resolve(directory, gitFile);
+            const common = read(path.join(gitDirectory, 'commondir'))?.trim();
+            if (common)
+                gitDirectory = path.resolve(gitDirectory, common);
+            const gitConfig = read(path.join(gitDirectory, 'config'));
+            if (gitConfig !== undefined) {
+                context = { ...context, remote: remoteFromGitConfig(gitConfig),
+                    rootDirectory: context.rootDirectory ?? directory,
+                    rootPackage: context.rootPackage ?? pkg };
+                break;
+            }
+            const parent = path.dirname(directory);
+            if (parent === directory)
+                break;
+            directory = parent;
+        }
+    }
+    catch { /* Optional metadata must never affect a command. */ }
+    return context;
+}

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

@@ -0,0 +1,72 @@
+import type { VALUE_FORMATS } from './value-formats.js';
+export type Field = ({
+    readonly kind: 'boolean';
+} | {
+    readonly kind: 'enum';
+    readonly values: readonly (string | number)[];
+} | {
+    readonly kind: 'enum_list';
+    readonly values: readonly string[];
+} | {
+    readonly kind: 'format';
+    readonly format: keyof typeof VALUE_FORMATS;
+} | {
+    readonly kind: 'record';
+    readonly fields: Readonly<Record<string, Field>>;
+}) & {
+    readonly description: string;
+    readonly optional?: boolean;
+};
+export type Fields = Readonly<Record<string, Field>>;
+export declare function enumeration<const V extends readonly (string | number)[]>(description: string, values: V): {
+    readonly kind: "enum";
+    readonly description: string;
+    readonly values: V;
+};
+export declare function boolean(description: string): {
+    readonly kind: "boolean";
+    readonly description: string;
+};
+export declare function enumList<const V extends readonly string[]>(description: string, values: V): {
+    readonly kind: "enum_list";
+    readonly description: string;
+    readonly values: V;
+};
+export declare function formatted<const F extends Extract<Field, {
+    kind: 'format';
+}>['format']>(description: string, format: F): {
+    readonly kind: "format";
+    readonly description: string;
+    readonly format: F;
+};
+export declare function record<const F extends Fields>(description: string, fields: F): {
+    readonly kind: "record";
+    readonly description: string;
+    readonly fields: F;
+};
+export declare function optional<const F extends Field>(field: F): F & {
+    readonly optional: true;
+};
+export declare function fieldsFor<const K extends readonly string[], const F extends Field>(keys: K, field: F): Record<K[number], F>;
+export type FieldValue<F extends Field> = F extends {
+    kind: 'boolean';
+} ? boolean : F extends {
+    kind: 'enum';
+    values: readonly (infer V)[];
+} ? V : F extends {
+    kind: 'enum_list';
+    values: readonly (infer V)[];
+} ? readonly V[] : F extends {
+    kind: 'record';
+    fields: infer R extends Fields;
+} ? Properties<R> : string;
+export type Properties<F extends Fields> = {
+    [K in keyof F as F[K] extends {
+        optional: true;
+    } ? never : K]: FieldValue<F[K]>;
+} & {
+    [K in keyof F as F[K] extends {
+        optional: true;
+    } ? K : never]?: FieldValue<F[K]>;
+};
+//# sourceMappingURL=schema.d.ts.map

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

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

package/dist/utils/telemetry/schema.js

@@ -0,0 +1,17 @@
+export function enumeration(description, values) {
+    return { kind: 'enum', description, values };
+}
+export function boolean(description) { return { kind: 'boolean', description }; }
+export function enumList(description, values) {
+    return { kind: 'enum_list', description, values };
+}
+export function formatted(description, format) {
+    return { kind: 'format', description, format };
+}
+export function record(description, fields) {
+    return { kind: 'record', description, fields };
+}
+export function optional(field) { return { ...field, optional: true }; }
+export function fieldsFor(keys, field) {
+    return Object.fromEntries(keys.map(key => [key, field]));
+}

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

@@ -0,0 +1,6 @@
+import type { DevOptions } from '../../commands/dev.js';
+import type { SessionStart } from './command-context.js';
+/** Explicit file arguments are classified without examining or retaining their path. */
+export declare function entryType(resolved: string, explicit?: string): SessionStart<'dev'>['entry_type'];
+export declare function devSessionConfig(resolved: string, explicit: string | undefined, options: DevOptions): SessionStart<'dev'>;
+//# sourceMappingURL=session-config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-config.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/session-config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,wFAAwF;AACxF,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,YAAY,CAAC,CAIhG;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,UAAU,GAAG,YAAY,CAAC,KAAK,CAAC,CAQzH"}