@tempoxyz/mercator 0.0.374 → 0.0.394

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,45 @@
1
+ import type { ClientId } from './clients.js';
2
+ /** Closed setup event names accepted by the Mercator telemetry gateway. */
3
+ export declare const SetupTelemetryEvent: {
4
+ readonly ClientConfigured: "mercator.cli_client_configured";
5
+ readonly ClientDetected: "mercator.cli_client_detected";
6
+ readonly ReadinessChecked: "mercator.cli_readiness_checked";
7
+ readonly SetupFinished: "mercator.cli_setup_finished";
8
+ readonly SetupStarted: "mercator.cli_setup_started";
9
+ };
10
+ /** One setup event name. */
11
+ export type SetupTelemetryEvent = (typeof SetupTelemetryEvent)[keyof typeof SetupTelemetryEvent];
12
+ /** Closed outcomes shared by setup and per-client events. */
13
+ type SetupTelemetryOutcome = 'already_configured' | 'cancelled' | 'configured' | 'conflict' | 'detected' | 'failed' | 'partial' | 'planned' | 'ready' | 'reconfigured' | 'skipped' | 'started' | 'succeeded';
14
+ /** Safe failure categories that never include raw exception content. */
15
+ export type SetupFailureCategory = 'network' | 'timeout' | 'validation' | 'unknown';
16
+ /** One anonymous, bounded CLI setup fact. */
17
+ export type SetupTelemetryRecord = {
18
+ readonly client?: ClientId;
19
+ readonly event: SetupTelemetryEvent;
20
+ readonly failureCategory?: SetupFailureCategory;
21
+ readonly outcome: SetupTelemetryOutcome;
22
+ };
23
+ /** Best-effort recorder owned by one setup invocation. */
24
+ export type SetupTelemetry = {
25
+ /** Queues bounded facts without performing I/O. */
26
+ record: (...events: readonly SetupTelemetryRecord[]) => void;
27
+ /** Sends and clears queued facts without failing setup. */
28
+ flush: () => Promise<void>;
29
+ };
30
+ type SetupTelemetryOptions = {
31
+ readonly cliVersion: string;
32
+ readonly dryRun: boolean;
33
+ readonly enabled: boolean;
34
+ readonly environment?: NodeJS.ProcessEnv;
35
+ readonly fetchTelemetry?: typeof fetch;
36
+ readonly interactive: boolean;
37
+ readonly now?: () => number;
38
+ readonly randomUUID?: () => string;
39
+ readonly selectionMode: 'automatic' | 'explicit';
40
+ };
41
+ /** Creates an anonymous setup recorder with process-local correlation only. */
42
+ export declare function createSetupTelemetry(options: SetupTelemetryOptions): SetupTelemetry;
43
+ /** Maps an unexpected setup failure to a finite analytics category. */
44
+ export declare function setupFailureCategory(error: unknown): SetupFailureCategory;
45
+ export {};
@@ -0,0 +1,115 @@
1
+ import { basename } from 'node:path';
2
+ /** Anonymous gateway endpoint that accepts bounded CLI setup events. */
3
+ const CLI_TELEMETRY_URL = 'https://mercator.tempo.xyz/v1/telemetry/cli';
4
+ /** Maximum time setup may wait for one best-effort telemetry delivery. */
5
+ const TELEMETRY_TIMEOUT_MS = 1_000;
6
+ /** Closed setup event names accepted by the Mercator telemetry gateway. */
7
+ export const SetupTelemetryEvent = {
8
+ ClientConfigured: 'mercator.cli_client_configured',
9
+ ClientDetected: 'mercator.cli_client_detected',
10
+ ReadinessChecked: 'mercator.cli_readiness_checked',
11
+ SetupFinished: 'mercator.cli_setup_finished',
12
+ SetupStarted: 'mercator.cli_setup_started',
13
+ };
14
+ /** Creates an anonymous setup recorder with process-local correlation only. */
15
+ export function createSetupTelemetry(options) {
16
+ const environment = options.environment ?? process.env;
17
+ const enabled = options.enabled && telemetryEnabled(environment);
18
+ const now = options.now ?? Date.now;
19
+ const startedAt = now();
20
+ const runId = options.randomUUID ? options.randomUUID() : crypto.randomUUID();
21
+ let events = [];
22
+ return {
23
+ record(...records) {
24
+ if (!enabled)
25
+ return;
26
+ const elapsed_ms = boundedElapsed(now() - startedAt);
27
+ events.push(...records.map((event) => ({ ...event, elapsed_ms })));
28
+ },
29
+ async flush() {
30
+ if (!enabled || events.length === 0)
31
+ return;
32
+ const batch = events;
33
+ events = [];
34
+ try {
35
+ const response = await (options.fetchTelemetry ?? fetch)(CLI_TELEMETRY_URL, {
36
+ body: JSON.stringify({
37
+ architecture: telemetryArchitecture(process.arch),
38
+ cli_version: options.cliVersion,
39
+ distribution: telemetryDistribution(environment, process.execPath),
40
+ dry_run: options.dryRun,
41
+ events: batch.map(({ failureCategory, ...event }) => ({
42
+ ...event,
43
+ ...(failureCategory ? { failure_category: failureCategory } : {}),
44
+ })),
45
+ interactive: options.interactive,
46
+ platform: telemetryPlatform(process.platform),
47
+ run_id: runId,
48
+ selection_mode: options.selectionMode,
49
+ }),
50
+ headers: { 'content-type': 'application/json' },
51
+ method: 'POST',
52
+ signal: AbortSignal.timeout(TELEMETRY_TIMEOUT_MS),
53
+ });
54
+ await response.body?.cancel();
55
+ }
56
+ catch {
57
+ // Analytics must never change setup behavior or output.
58
+ }
59
+ },
60
+ };
61
+ }
62
+ /** Maps an unexpected setup failure to a finite analytics category. */
63
+ export function setupFailureCategory(error) {
64
+ if (error instanceof Error) {
65
+ if (error.name === 'AbortError' || error.name === 'TimeoutError')
66
+ return 'timeout';
67
+ if (error instanceof TypeError)
68
+ return 'network';
69
+ if (error.message.startsWith('--'))
70
+ return 'validation';
71
+ }
72
+ return 'unknown';
73
+ }
74
+ function telemetryEnabled(environment) {
75
+ if (environment.NODE_ENV === 'test' || enabledToggle(environment.CI))
76
+ return false;
77
+ if (environment.DO_NOT_TRACK === '1')
78
+ return false;
79
+ return !disabledToggle(environment.MERCATOR_TELEMETRY);
80
+ }
81
+ function telemetryPlatform(platform) {
82
+ if (platform === 'darwin')
83
+ return 'macos';
84
+ if (platform === 'win32')
85
+ return 'windows';
86
+ if (platform === 'linux')
87
+ return 'linux';
88
+ return 'other';
89
+ }
90
+ function telemetryArchitecture(architecture) {
91
+ if (architecture === 'arm64' || architecture === 'x64')
92
+ return architecture;
93
+ return 'other';
94
+ }
95
+ function telemetryDistribution(environment, executablePath) {
96
+ if (environment.MERCATOR_INSTALL_CHANNEL === 'standalone')
97
+ return 'standalone';
98
+ if (executablePath.includes('/nix/store/'))
99
+ return 'nix';
100
+ if (basename(executablePath).toLowerCase().startsWith('mercator'))
101
+ return 'standalone';
102
+ if (basename(executablePath).toLowerCase().startsWith('node'))
103
+ return 'node';
104
+ return 'unknown';
105
+ }
106
+ function boundedElapsed(value) {
107
+ return Math.min(Math.max(Math.round(value), 0), 3_600_000);
108
+ }
109
+ function enabledToggle(value) {
110
+ return (value !== undefined && !['', '0', 'false', 'no', 'off'].includes(value.toLowerCase()));
111
+ }
112
+ function disabledToggle(value) {
113
+ return value !== undefined && ['0', 'false', 'no', 'off'].includes(value.toLowerCase());
114
+ }
115
+ //# sourceMappingURL=setup-telemetry.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"setup-telemetry.js","sourceRoot":"","sources":["../src/setup-telemetry.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tempoxyz/mercator",
3
- "version": "0.0.374",
3
+ "version": "0.0.394",
4
4
  "description": "Connect agent clients to the Mercator remote MCP server",
5
5
  "type": "module",
6
6
  "bin": {