@hypequery/cli 1.21.2 → 1.23.0

package/dist/utils/live-deployment.js

@@ -3,7 +3,12 @@ import path from 'node:path';
 import { DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS, validateProtocolDeploymentReleaseTarget, } from '@hypequery/protocol';
 const SHA256_PATTERN = /^[0-9a-f]{64}$/;
 const MAX_RESPONSE_BYTES = Math.ceil(DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS.maxSourceBytes * 1.4) + 1_000_000;
-function liveUrl(endpoint, target, resource) {
+/**
+ * The Cloud target resource beside a submissions endpoint, or undefined when
+ * the endpoint is not a Cloud submissions URL. Refuses anything but https (or
+ * loopback http) so a credential is never sent in the clear.
+ */
+export function liveUrl(endpoint, target, resource) {
     const url = new URL(endpoint);
     if (!/\/v1\/deployments\/submissions\/?$/.test(url.pathname)) {
         return undefined;

package/dist/utils/load-api.d.ts

@@ -1,4 +1,6 @@
 export declare function loadApiModule(modulePath: string): Promise<any>;
 export declare function loadModule(modulePath: string): Promise<any>;
+/** Remove this process's bundles; the CLI awaits this before it exits. */
+export declare function cleanupLoadedApiArtifacts(): Promise<void>;
 export declare function findNearestTsconfig(filePath: string): Promise<string | null>;
 //# sourceMappingURL=load-api.d.ts.map

package/dist/utils/load-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load-api.d.ts","sourceRoot":"","sources":["../../src/utils/load-api.ts"],"names":[],"mappings":"AAaA,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,gBA2DrD;AAED,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,gBAkClD;AA0JD,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,0BA8BzD"}
+{"version":3,"file":"load-api.d.ts","sourceRoot":"","sources":["../../src/utils/load-api.ts"],"names":[],"mappings":"AAgBA,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,gBA2DrD;AAED,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,gBAwClD;AAuED,0EAA0E;AAC1E,wBAAsB,yBAAyB,kBAE9C;AAqED,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,0BA8BzD"}

package/dist/utils/load-api.js

@@ -1,8 +1,11 @@
 import { pathToFileURL } from 'node:url';
-import { access, mkdtemp, rm, mkdir, writeFile } from 'node:fs/promises';
+import { rmdirSync, rmSync } from 'node:fs';
+import { access, mkdtemp, mkdir, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { build } from 'esbuild';
+import { loadEnvFiles } from './load-env-files.js';
+import { findProjectRoot } from './project-root.js';
 if (typeof process.setMaxListeners === 'function') {
     process.setMaxListeners(0);
 }
@@ -68,6 +71,11 @@ export async function loadModule(modulePath) {
         const relativePath = path.relative(process.cwd(), resolved);
         throw new Error(`File not found: ${relativePath}`);
     }
+    // The CLI loaded the launch directory's env files at startup. An entry in
+    // another project (`hypequery mcp /abs/path/api.ts`) reads its connection
+    // settings from that project's env files, so load those too before its
+    // client module runs. Values already set keep precedence.
+    await loadEnvFiles(await findProjectRoot(resolved));
     const extension = path.extname(resolved).toLowerCase();
     const isTypeScript = TYPESCRIPT_EXTENSIONS.has(extension);
     const moduleUrl = isTypeScript
@@ -92,23 +100,26 @@ export async function loadModule(modulePath) {
     }
 }
 const globalState = globalThis;
-let tempDirPromise = globalState.__hypequeryCliTempDirPromise ?? null;
-const tempFiles = globalState.__hypequeryCliTempFiles ?? new Set();
-const tempDirs = globalState.__hypequeryCliTempDirs ?? new Set();
+// One bundle directory per project root, keyed by that root.
+const tempDirPromises = globalState.__hypequeryCliTempDirPromises ??= new Map();
+const tempFiles = globalState.__hypequeryCliTempFiles ??= new Set();
+const tempDirs = globalState.__hypequeryCliTempDirs ??= new Set();
+const tempRoots = globalState.__hypequeryCliTempRoots ??= new Set();
 let cleanupHooksInstalled = globalState.__hypequeryCliCleanupInstalled ?? false;
-if (!globalState.__hypequeryCliTempFiles) {
-    globalState.__hypequeryCliTempFiles = tempFiles;
-}
-if (!globalState.__hypequeryCliTempDirs) {
-    globalState.__hypequeryCliTempDirs = tempDirs;
-}
-function ensureTempDir() {
+/**
+ * The bundle has to live inside the entry's project: its bare imports
+ * (`@hypequery/serve`, ...) resolve from the bundle's location, and the
+ * process's working directory may be anywhere (MCP clients launch from `/`).
+ */
+function ensureTempDir(projectRoot) {
     installCleanupHooks();
-    if (!tempDirPromise) {
-        tempDirPromise = (async () => {
-            const projectTempRoot = path.join(process.cwd(), '.hypequery', 'tmp');
+    let promise = tempDirPromises.get(projectRoot);
+    if (!promise) {
+        promise = (async () => {
+            const projectTempRoot = path.join(projectRoot, '.hypequery', 'tmp');
             try {
                 await mkdir(projectTempRoot, { recursive: true });
+                tempRoots.add(projectTempRoot);
                 const dir = await mkdtemp(path.join(projectTempRoot, 'bundle-'));
                 tempDirs.add(dir);
                 return dir;
@@ -119,65 +130,53 @@ function ensureTempDir() {
                 return fallbackDir;
             }
         })();
-        globalState.__hypequeryCliTempDirPromise = tempDirPromise;
+        tempDirPromises.set(projectRoot, promise);
     }
-    return tempDirPromise;
+    return promise;
 }
-async function cleanupTempFiles() {
-    if (tempFiles.size === 0)
-        return;
-    await Promise.all(Array.from(tempFiles).map(async (file) => {
+// Synchronous so it completes inside an 'exit' handler.
+function cleanupTempArtifacts() {
+    for (const target of [...tempFiles, ...tempDirs]) {
         try {
-            await rm(file, { force: true });
+            rmSync(target, { recursive: true, force: true });
         }
         catch {
             // ignore cleanup failures
         }
-    }));
+    }
     tempFiles.clear();
-}
-async function cleanupTempDirs() {
-    if (tempDirs.size === 0)
-        return;
-    await Promise.all(Array.from(tempDirs).map(async (dir) => {
+    tempDirs.clear();
+    tempDirPromises.clear();
+    // Only remove the shared tmp root once empty: another hypequery process in the
+    // same project (e.g. `hypequery dev` beside an MCP client) may still use it.
+    for (const root of tempRoots) {
         try {
-            await rm(dir, { recursive: true, force: true });
+            rmdirSync(root);
         }
         catch {
-            // ignore cleanup failures
+            // not empty or already gone
         }
-    }));
-    tempDirs.clear();
-    const projectTempRoot = path.join(process.cwd(), '.hypequery', 'tmp');
-    try {
-        await rm(projectTempRoot, { recursive: true, force: true });
-    }
-    catch {
-        // ignore cleanup failures
     }
+    tempRoots.clear();
 }
-async function cleanupTempArtifacts() {
-    await cleanupTempFiles();
-    await cleanupTempDirs();
+/** Remove this process's bundles; the CLI awaits this before it exits. */
+export async function cleanupLoadedApiArtifacts() {
+    cleanupTempArtifacts();
 }
 function installCleanupHooks() {
     if (cleanupHooksInstalled)
         return;
     cleanupHooksInstalled = true;
     globalState.__hypequeryCliCleanupInstalled = true;
-    process.once('exit', () => {
-        cleanupTempArtifacts().catch(() => undefined);
-    });
-    ['SIGINT', 'SIGTERM'].forEach(signal => {
-        process.once(signal, () => {
-            cleanupTempArtifacts().catch(() => undefined);
-            process.exit();
-        });
-    });
+    // Synchronous, so it still completes when this is the last thing to run.
+    process.once('exit', cleanupTempArtifacts);
+    // Signal shutdown belongs to the CLI/owning server. Exiting from a module
+    // cleanup listener bypassed server teardown and the bounded telemetry flush.
 }
 async function bundleTypeScriptModule(entryPath) {
     const relativePath = path.relative(process.cwd(), entryPath);
     const tsconfigPath = await findNearestTsconfig(entryPath);
+    const projectRoot = await findProjectRoot(entryPath);
     try {
         const result = await build({
             entryPoints: [entryPath],
@@ -188,7 +187,7 @@ async function bundleTypeScriptModule(entryPath) {
             sourcemap: 'inline',
             write: false,
             logLevel: 'silent',
-            absWorkingDir: process.cwd(),
+            absWorkingDir: projectRoot,
             packages: 'external',
             tsconfig: tsconfigPath ?? undefined,
             loader: {
@@ -202,7 +201,7 @@ async function bundleTypeScriptModule(entryPath) {
         if (!output) {
             throw new Error('esbuild produced no output');
         }
-        const tempDir = await ensureTempDir();
+        const tempDir = await ensureTempDir(projectRoot);
         const timestamp = Date.now();
         const tempFile = path.join(tempDir, `${path.basename(entryPath, path.extname(entryPath))}-${timestamp}.mjs`);
         const contents = `${output.text}\n` +

package/dist/utils/load-env-files.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Loads the `.env*` cascade from `directory` into `process.env`.
+ *
+ * `dotenv` never overwrites a variable that is already set, so a real
+ * environment variable beats every file, and a directory loaded earlier (the
+ * launch directory, at startup) beats one loaded later. Each directory is read
+ * once per process; `hypequery dev` reloads the API on every change.
+ */
+export declare function loadEnvFiles(directory: string): Promise<void>;
+//# sourceMappingURL=load-env-files.d.ts.map

package/dist/utils/load-env-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-env-files.d.ts","sourceRoot":"","sources":["../../src/utils/load-env-files.ts"],"names":[],"mappings":"AAKA;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAcnE"}

package/dist/utils/load-env-files.js

@@ -0,0 +1,27 @@
+import path from 'node:path';
+import { envFiles } from './env-files.js';
+const loadedDirectories = new Set();
+/**
+ * Loads the `.env*` cascade from `directory` into `process.env`.
+ *
+ * `dotenv` never overwrites a variable that is already set, so a real
+ * environment variable beats every file, and a directory loaded earlier (the
+ * launch directory, at startup) beats one loaded later. Each directory is read
+ * once per process; `hypequery dev` reloads the API on every change.
+ */
+export async function loadEnvFiles(directory) {
+    const resolved = path.resolve(directory);
+    if (loadedDirectories.has(resolved))
+        return;
+    loadedDirectories.add(resolved);
+    try {
+        const { config } = await import('dotenv');
+        for (const file of envFiles(process.env.NODE_ENV)) {
+            // Missing files are a no-op.
+            config({ path: path.join(resolved, file) });
+        }
+    }
+    catch {
+        // dotenv is optional; continue if not available
+    }
+}

package/dist/utils/mcp-remote-check.d.ts

@@ -0,0 +1,19 @@
+export type RemoteMcpCheck = {
+    readonly ok: true;
+    readonly tools: number;
+    readonly server?: string;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * A non-destructive check of a hosted MCP endpoint: initialize, then list
+ * tools. It never calls a tool, so it runs no query and changes nothing.
+ * The key is sent only as a bearer header and never included in the result.
+ */
+export declare function checkRemoteMcp(input: {
+    readonly url: string;
+    readonly key: string;
+    readonly fetch?: typeof fetch;
+}): Promise<RemoteMcpCheck>;
+//# sourceMappingURL=mcp-remote-check.d.ts.map

package/dist/utils/mcp-remote-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-remote-check.d.ts","sourceRoot":"","sources":["../../src/utils/mcp-remote-check.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACvE;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAkCpD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE;IAC1C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CAC/B,GAAG,OAAO,CAAC,cAAc,CAAC,CAsD1B"}

package/dist/utils/mcp-remote-check.js

@@ -0,0 +1,96 @@
+import { readMcpResponse } from './mcp-response.js';
+const PROTOCOL_VERSION = '2025-06-18';
+const TIMEOUT_MS = 15_000;
+const SUPPORTED_PROTOCOL_VERSIONS = new Set(['2025-03-26', PROTOCOL_VERSION, '2025-11-25']);
+async function rpc(fetchFn, url, key, message, session, protocolVersion = PROTOCOL_VERSION) {
+    const response = await fetchFn(url, {
+        method: 'POST',
+        headers: {
+            authorization: `Bearer ${key}`,
+            'content-type': 'application/json',
+            accept: 'application/json, text/event-stream',
+            'mcp-protocol-version': protocolVersion,
+            ...(session ? { 'mcp-session-id': session } : {}),
+        },
+        body: JSON.stringify(message),
+        redirect: 'error',
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    const body = await readMcpResponse(response, message.id);
+    return { response, body };
+}
+function refusal(status) {
+    if (status === 401)
+        return 'the API key was refused (401). Check HYPEQUERY_API_KEY.';
+    if (status === 403)
+        return 'the API key may not use MCP here (403). Check its scopes.';
+    if (status === 404)
+        return 'no MCP endpoint is published at this URL (404).';
+    return `the endpoint answered HTTP ${status}.`;
+}
+/**
+ * A non-destructive check of a hosted MCP endpoint: initialize, then list
+ * tools. It never calls a tool, so it runs no query and changes nothing.
+ * The key is sent only as a bearer header and never included in the result.
+ */
+export async function checkRemoteMcp(input) {
+    const fetchFn = input.fetch ?? fetch;
+    let url;
+    try {
+        url = new URL(input.url);
+    }
+    catch {
+        return { ok: false, reason: 'the URL is not valid.' };
+    }
+    const loopback = url.hostname === 'localhost' || url.hostname === '127.0.0.1';
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) {
+        return { ok: false, reason: 'the URL must use https, so the API key is not sent in the clear.' };
+    }
+    try {
+        const init = await rpc(fetchFn, url.href, input.key, {
+            jsonrpc: '2.0',
+            id: 1,
+            method: 'initialize',
+            params: {
+                protocolVersion: PROTOCOL_VERSION,
+                capabilities: {},
+                clientInfo: { name: 'hypequery-cli-self-test', version: '1.0.0' },
+            },
+        });
+        if (!init.response.ok)
+            return { ok: false, reason: refusal(init.response.status) };
+        if (!init.body?.result)
+            return { ok: false, reason: 'initialize returned no result.' };
+        const protocolVersion = init.body.result.protocolVersion;
+        if (typeof protocolVersion !== 'string' || !SUPPORTED_PROTOCOL_VERSIONS.has(protocolVersion)) {
+            return { ok: false, reason: 'initialize returned an unsupported protocol version.' };
+        }
+        const session = init.response.headers.get('mcp-session-id') ?? undefined;
+        const initialized = await rpc(fetchFn, url.href, input.key, {
+            jsonrpc: '2.0',
+            method: 'notifications/initialized',
+        }, session, protocolVersion);
+        if (!initialized.response.ok)
+            return { ok: false, reason: refusal(initialized.response.status) };
+        const listed = await rpc(fetchFn, url.href, input.key, {
+            jsonrpc: '2.0',
+            id: 2,
+            method: 'tools/list',
+        }, session, protocolVersion);
+        if (!listed.response.ok)
+            return { ok: false, reason: refusal(listed.response.status) };
+        const tools = listed.body?.result?.tools;
+        if (!Array.isArray(tools))
+            return { ok: false, reason: 'tools/list returned no tools.' };
+        const server = init.body.result.serverInfo?.name;
+        return { ok: true, tools: tools.length, ...(typeof server === 'string' ? { server } : {}) };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: error?.name === 'TimeoutError'
+                ? 'the endpoint did not answer in time.'
+                : 'the endpoint could not be reached.',
+        };
+    }
+}

package/dist/utils/mcp-response.d.ts

@@ -0,0 +1,3 @@
+/** Read a JSON-RPC response, including responses delivered over an SSE stream. */
+export declare function readMcpResponse(response: Response, requestId: unknown): Promise<Record<string, any> | null>;
+//# sourceMappingURL=mcp-response.d.ts.map

package/dist/utils/mcp-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-response.d.ts","sourceRoot":"","sources":["../../src/utils/mcp-response.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,wBAAsB,eAAe,CACnC,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,OAAO,GACjB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC,CAiDrC"}

package/dist/utils/mcp-response.js

@@ -0,0 +1,58 @@
+/** Read a JSON-RPC response, including responses delivered over an SSE stream. */
+export async function readMcpResponse(response, requestId) {
+    if (!response.ok || requestId === undefined) {
+        await response.body?.cancel();
+        return null;
+    }
+    const contentType = response.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase();
+    if (contentType !== 'text/event-stream') {
+        try {
+            const body = await response.json();
+            return body?.jsonrpc === '2.0' && body.id === requestId ? body : null;
+        }
+        catch (error) {
+            if (error?.name === 'TimeoutError' || error?.name === 'AbortError') {
+                throw error;
+            }
+            return null;
+        }
+    }
+    if (!response.body)
+        return null;
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let pending = '';
+    let data = [];
+    try {
+        for (;;) {
+            const chunk = await reader.read();
+            pending += decoder.decode(chunk.value, { stream: !chunk.done });
+            let newline;
+            while ((newline = /\r\n|\r|\n/.exec(pending))) {
+                // A CR at the chunk boundary may be the first half of CRLF.
+                if (!chunk.done && newline[0] === '\r' && newline.index === pending.length - 1)
+                    break;
+                const line = pending.slice(0, newline.index);
+                pending = pending.slice(newline.index + newline[0].length);
+                if (line === '') {
+                    if (data.length > 0) {
+                        const body = JSON.parse(data.join('\n'));
+                        data = [];
+                        if (body?.jsonrpc === '2.0' && body.id === requestId
+                            && ('result' in body || 'error' in body))
+                            return body;
+                    }
+                }
+                else if (line === 'data' || line.startsWith('data:')) {
+                    data.push(line === 'data' ? '' : line.slice(5).replace(/^ /, ''));
+                }
+            }
+            if (chunk.done)
+                return null;
+        }
+    }
+    finally {
+        await reader.cancel();
+        reader.releaseLock();
+    }
+}

package/dist/utils/project-root.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Finds the directory that owns `filePath`: the nearest ancestor with a
+ * `package.json`, or the file's own directory when there is none. Bare imports
+ * in the file resolve from here, whatever the process's working directory is.
+ */
+export declare function findProjectRoot(filePath: string): Promise<string>;
+/**
+ * Imports `specifier` as `fromFile` would see it, so a package installed in the
+ * user's project is found even when the CLI runs from elsewhere (for example
+ * through `npx -y @hypequery/cli`). Falls back to `fallback` — the CLI's own
+ * resolution — when the project does not have the package.
+ */
+export declare function importFromProject<T>(specifier: string, fromFile: string, fallback: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=project-root.d.ts.map

package/dist/utils/project-root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-root.d.ts","sourceRoot":"","sources":["../../src/utils/project-root.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAcvE;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,CAAC,CAAC,CAQZ"}

package/dist/utils/project-root.js

@@ -0,0 +1,41 @@
+import { access } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+/**
+ * Finds the directory that owns `filePath`: the nearest ancestor with a
+ * `package.json`, or the file's own directory when there is none. Bare imports
+ * in the file resolve from here, whatever the process's working directory is.
+ */
+export async function findProjectRoot(filePath) {
+    const start = path.dirname(path.resolve(filePath));
+    let dir = start;
+    while (true) {
+        try {
+            await access(path.join(dir, 'package.json'));
+            return dir;
+        }
+        catch {
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                return start;
+            dir = parent;
+        }
+    }
+}
+/**
+ * Imports `specifier` as `fromFile` would see it, so a package installed in the
+ * user's project is found even when the CLI runs from elsewhere (for example
+ * through `npx -y @hypequery/cli`). Falls back to `fallback` — the CLI's own
+ * resolution — when the project does not have the package.
+ */
+export async function importFromProject(specifier, fromFile, fallback) {
+    let resolved;
+    try {
+        resolved = createRequire(path.resolve(fromFile)).resolve(specifier);
+    }
+    catch {
+        return fallback();
+    }
+    return import(/* @vite-ignore */ pathToFileURL(resolved).href);
+}

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

@@ -0,0 +1,5 @@
+import { COUNT_BUCKETS, DURATION_BUCKETS } from './domains.js';
+/** Invalid measurements are omitted rather than coerced into a misleading bucket. */
+export declare function countBucket(count: number): typeof COUNT_BUCKETS[number] | undefined;
+export declare function durationBucket(milliseconds: number): typeof DURATION_BUCKETS[number] | undefined;
+//# sourceMappingURL=buckets.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"buckets.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/buckets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAE/D,qFAAqF;AACrF,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAQnF;AAED,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,gBAAgB,CAAC,MAAM,CAAC,GAAG,SAAS,CAIhG"}

package/dist/utils/telemetry/buckets.js

@@ -0,0 +1,23 @@
+import { DURATION_BUCKETS } from './domains.js';
+/** Invalid measurements are omitted rather than coerced into a misleading bucket. */
+export function countBucket(count) {
+    if (!Number.isSafeInteger(count) || count < 0)
+        return undefined;
+    if (count === 0)
+        return '0';
+    if (count === 1)
+        return '1';
+    if (count <= 5)
+        return '2-5';
+    if (count <= 20)
+        return '6-20';
+    if (count <= 100)
+        return '21-100';
+    return '101+';
+}
+export function durationBucket(milliseconds) {
+    if (!Number.isFinite(milliseconds) || milliseconds < 0)
+        return undefined;
+    const boundaries = [100, 1_000, 10_000, 60_000, 600_000, 3_600_000];
+    return DURATION_BUCKETS[boundaries.findIndex(boundary => milliseconds < boundary)] ?? '1h+';
+}

package/dist/utils/telemetry/catalog-docs.d.ts

@@ -0,0 +1,3 @@
+/** Generated section only; the public page retains its human-written policy and controls. */
+export declare function renderTelemetryCatalog(): string;
+//# sourceMappingURL=catalog-docs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-docs.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/catalog-docs.ts"],"names":[],"mappings":"AA6BA,6FAA6F;AAC7F,wBAAgB,sBAAsB,IAAI,MAAM,CA4B/C"}

package/dist/utils/telemetry/catalog-docs.js

@@ -0,0 +1,52 @@
+import { COMMON_PROPERTIES, EVENT_CATALOG, EVENT_SCHEMA_VERSION } from './catalog.js';
+import { VALUE_FORMATS } from './value-formats.js';
+import { COMMAND_FLAGS, GLOBAL_FLAGS } from './domains.js';
+function domain(field) {
+    switch (field.kind) {
+        case 'boolean': return '`true`, `false`';
+        case 'enum': return field.values.map(value => `\`${value}\``).join(', ');
+        case 'enum_list': return `Unique list of: ${field.values.map(value => `\`${value}\``).join(', ')}`;
+        case 'record': return 'Object with only the documented keys below';
+        case 'format': return VALUE_FORMATS[field.format].description;
+    }
+}
+function rows(fields, prefix = '') {
+    return Object.entries(fields).flatMap(([name, field]) => {
+        const key = `${prefix}${name}`;
+        return [
+            `| \`${key}\` | ${field.optional ? 'Optional' : 'Required'} | ${domain(field)} | ${field.description} |`,
+            ...(field.kind === 'record' ? rows(field.fields, `${key}.`) : []),
+        ];
+    });
+}
+function table(fields) {
+    return ['| Property | Presence | Allowed values | Question answered |', '| --- | --- | --- | --- |', ...rows(fields)].join('\n');
+}
+/** Generated section only; the public page retains its human-written policy and controls. */
+export function renderTelemetryCatalog() {
+    const parts = [
+        '{/* Generated by pnpm --filter @hypequery/cli telemetry:docs. Do not edit this section by hand. */}',
+        '## Event reference',
+        `Schema version: **${EVENT_SCHEMA_VERSION}**. Default collection is inactive. Debug or explicitly configured ingest mode emits command/crash lifecycle events, init and generation metrics, and dev/MCP session events. Cloud command and project-feature instrumentation follows separately.`,
+        'Unknown events, properties, record keys, flag names, enum values, and malformed identities or versions are rejected. No argument values, paths, names, SQL, messages, stacks, hosts, tenants, or credentials are permitted.',
+        'Counts use inclusive integer ranges: 0, 1, 2–5, 6–20, 21–100, and 101 or more. Duration and nonzero size buckets include their lower bound and exclude their upper bound. Raw counts, durations, ports and byte sizes are never sent.',
+        '### Common properties',
+        'Every event includes these fields. Unknown environment details use the documented unknown value; unavailable optional fields are omitted.',
+        table(COMMON_PROPERTIES),
+    ];
+    for (const [name, definition] of Object.entries(EVENT_CATALOG)) {
+        parts.push(`### \`${name}\``, definition.purpose, table(definition.properties));
+        if ('variants' in definition) {
+            for (const [command, fields] of Object.entries(definition.variants)) {
+                parts.push(`#### \`${name}\`: \`${command}\``);
+                if (name === 'cli_command_completed') {
+                    const flags = [...COMMAND_FLAGS[command], ...GLOBAL_FLAGS];
+                    parts.push(`Allowed \`flags_used\`: ${flags.map(flag => `\`${flag}\``).join(', ')}. The two type-generation aliases remain distinct command values.`);
+                }
+                parts.push(Object.keys(fields).length ? table(fields) : 'No additional properties.');
+            }
+        }
+    }
+    parts.push('MCP client identity/version is excluded from v1 pending the privacy decision. Auth strategies are recorded only as none/configured/unknown, since user-supplied functions have no safe built-in type identifier.', 'Cache scopes are classified only as unscoped/tenant/explicit/unknown from configuration presence. Explicit scopes are user content and are never read into a payload.', 'Project IDs follow HQ-233: the CLI uses the shared global salt, then the ingest proxy re-keys the digest with a server-side HMAC secret before storage. A hash is a pseudonymous project signal, not proof of anonymity. Cloud accounts are never linked to install IDs.');
+    return `${parts.join('\n\n')}\n`;
+}