@hypequery/cli 1.22.0 → 1.24.0

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}**. Unless opted out, the CLI sends command/crash lifecycle events, init and generation metrics, and dev/MCP session events to the first-party ingest proxy; debug mode prints them instead. 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`;
+}