@mintlify/cli 4.0.1067 → 4.0.1068

package/__test__/telemetry.test.ts

@@ -0,0 +1,313 @@
+import fs from 'fs';
+import * as fsExtra from 'fs-extra';
+import os from 'os';
+
+import { isTelemetryEnabled, setTelemetryEnabled } from '../src/config.js';
+import { TELEMETRY_ASYNC_TIMEOUT_MS } from '../src/constants.js';
+import { getDistinctId } from '../src/telemetry/distinctId.js';
+import {
+  createTelemetryMiddleware,
+  getSanitizedCommandForTelemetry,
+} from '../src/telemetry/middleware.js';
+import * as trackModule from '../src/telemetry/track.js';
+import { trackCommand, trackTelemetryPreferenceChange } from '../src/telemetry/track.js';
+
+vi.mock('fs-extra', () => ({ ensureDir: vi.fn().mockResolvedValue(undefined) }));
+
+const mockCaptureImmediate = vi.fn().mockResolvedValue(undefined);
+
+vi.mock('../src/telemetry/client.js', () => ({
+  getPostHogClient: () => ({ captureImmediate: mockCaptureImmediate }),
+  shutdownPostHog: vi.fn(),
+}));
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('createTelemetryMiddleware', () => {
+  beforeEach(() => {
+    vi.spyOn(trackModule, 'trackCommand').mockResolvedValue(undefined);
+  });
+
+  it('only tracks once when middleware runs multiple times for the same parse', async () => {
+    const middleware = createTelemetryMiddleware();
+    await middleware({ _: ['dev'] });
+    await middleware({ _: ['dev'] });
+    expect(trackModule.trackCommand).toHaveBeenCalledTimes(1);
+  });
+
+  it('tracks again for a new middleware instance (new cli invocation)', async () => {
+    await createTelemetryMiddleware()({ _: ['dev'] });
+    expect(trackModule.trackCommand).toHaveBeenCalledTimes(1);
+    await createTelemetryMiddleware()({ _: ['build'] });
+    expect(trackModule.trackCommand).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe('getSanitizedCommandForTelemetry', () => {
+  it('includes known scrape subcommands', () => {
+    expect(getSanitizedCommandForTelemetry(['scrape', 'page', 'https://example.com'])).toBe(
+      'scrape page'
+    );
+    expect(getSanitizedCommandForTelemetry(['scrape', 'site', 'https://example.com'])).toBe(
+      'scrape site'
+    );
+    expect(getSanitizedCommandForTelemetry(['scrape', 'openapi', './spec.yaml'])).toBe(
+      'scrape openapi'
+    );
+  });
+
+  it('strips positional args from all other commands', () => {
+    expect(getSanitizedCommandForTelemetry(['scrape', 'https://example.com'])).toBe('scrape');
+    expect(getSanitizedCommandForTelemetry(['openapi-check', 'https://swagger.io/spec.json'])).toBe(
+      'openapi-check'
+    );
+    expect(getSanitizedCommandForTelemetry(['rename', 'a.mdx', 'b.mdx'])).toBe('rename');
+    expect(getSanitizedCommandForTelemetry(['new', './my-docs'])).toBe('new');
+  });
+});
+
+describe('isTelemetryEnabled', () => {
+  const savedEnv = process.env;
+
+  beforeEach(() => {
+    process.env = { ...savedEnv };
+    delete process.env.MINTLIFY_TELEMETRY_DISABLED;
+    delete process.env.DO_NOT_TRACK;
+    delete process.env.CLI_TEST_MODE;
+  });
+
+  afterEach(() => {
+    process.env = savedEnv;
+  });
+
+  it('is enabled by default when config file does not exist', () => {
+    vi.spyOn(fs, 'readFileSync').mockImplementation(() => {
+      throw Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+    });
+    expect(isTelemetryEnabled()).toBe(true);
+  });
+
+  it('is disabled when config file has telemetryEnabled: false', () => {
+    vi.spyOn(fs, 'readFileSync').mockReturnValue(JSON.stringify({ telemetryEnabled: false }));
+    expect(isTelemetryEnabled()).toBe(false);
+  });
+
+  it('is enabled when config file has telemetryEnabled: true', () => {
+    vi.spyOn(fs, 'readFileSync').mockReturnValue(JSON.stringify({ telemetryEnabled: true }));
+    expect(isTelemetryEnabled()).toBe(true);
+  });
+
+  it('is disabled via CLI_TEST_MODE=true', () => {
+    process.env.CLI_TEST_MODE = 'true';
+    expect(isTelemetryEnabled()).toBe(false);
+  });
+
+  it('is disabled via MINTLIFY_TELEMETRY_DISABLED=1', () => {
+    process.env.MINTLIFY_TELEMETRY_DISABLED = '1';
+    expect(isTelemetryEnabled()).toBe(false);
+  });
+
+  it('is disabled via DO_NOT_TRACK=1', () => {
+    process.env.DO_NOT_TRACK = '1';
+    expect(isTelemetryEnabled()).toBe(false);
+  });
+});
+
+describe('setTelemetryEnabled', () => {
+  beforeEach(() => {
+    vi.mocked(fsExtra.ensureDir).mockResolvedValue(undefined);
+  });
+
+  it('writes telemetryEnabled into config.json', async () => {
+    vi.spyOn(fs, 'readFileSync').mockImplementation(() => {
+      throw Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+    });
+    const writeSpy = vi.spyOn(fs, 'writeFileSync').mockImplementation(() => undefined);
+
+    await setTelemetryEnabled(false);
+
+    expect(fsExtra.ensureDir).toHaveBeenCalledWith(expect.stringContaining('mintlify'));
+    expect(writeSpy).toHaveBeenCalledWith(
+      expect.stringContaining('config.json'),
+      JSON.stringify({ telemetryEnabled: false }, null, 2)
+    );
+  });
+
+  it('merges with existing config fields', async () => {
+    vi.spyOn(fs, 'readFileSync').mockReturnValue(JSON.stringify({ someOtherSetting: true }));
+    const writeSpy = vi.spyOn(fs, 'writeFileSync').mockImplementation(() => undefined);
+
+    await setTelemetryEnabled(false);
+
+    expect(writeSpy).toHaveBeenCalledWith(
+      expect.stringContaining('config.json'),
+      JSON.stringify({ someOtherSetting: true, telemetryEnabled: false }, null, 2)
+    );
+  });
+});
+
+describe('getDistinctId', () => {
+  it('returns the persisted UUID', () => {
+    const id = '550e8400-e29b-41d4-a716-446655440000';
+    vi.spyOn(fs, 'readFileSync').mockReturnValue(id);
+    expect(getDistinctId()).toBe(id);
+  });
+
+  it('generates and persists a new UUID when none exists', () => {
+    vi.spyOn(fs, 'readFileSync').mockImplementation(() => {
+      throw new Error('ENOENT');
+    });
+    vi.spyOn(fs, 'mkdirSync').mockImplementation(() => undefined);
+    const writeSpy = vi.spyOn(fs, 'writeFileSync').mockImplementation(() => undefined);
+
+    const id = getDistinctId();
+    expect(id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+    expect(writeSpy).toHaveBeenCalledWith(expect.stringContaining('anonymous-id'), id, {
+      flag: 'wx',
+    });
+  });
+
+  it('overwrites anonymous-id when it exists but is not a valid UUID', () => {
+    vi.spyOn(fs, 'readFileSync').mockReturnValue('not-a-uuid');
+    vi.spyOn(fs, 'mkdirSync').mockImplementation(() => undefined);
+    const writeSpy = vi.spyOn(fs, 'writeFileSync').mockImplementation((...args) => {
+      const opts = args[2] as { flag?: string } | undefined;
+      if (opts?.flag === 'wx') {
+        throw Object.assign(new Error('EEXIST'), { code: 'EEXIST' });
+      }
+    });
+
+    const id = getDistinctId();
+    expect(id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+    expect(writeSpy).toHaveBeenCalledWith(expect.stringContaining('anonymous-id'), id, {
+      flag: 'wx',
+    });
+    expect(writeSpy).toHaveBeenCalledWith(expect.stringContaining('anonymous-id'), id);
+  });
+
+  it('reuses the same id when the file cannot be persisted (stable machine fallback)', () => {
+    vi.spyOn(fs, 'readFileSync').mockImplementation(() => {
+      throw new Error('ENOENT');
+    });
+    vi.spyOn(fs, 'mkdirSync').mockImplementation(() => undefined);
+    vi.spyOn(fs, 'writeFileSync').mockImplementation(() => {
+      throw new Error('EACCES');
+    });
+
+    const a = getDistinctId();
+    const b = getDistinctId();
+    expect(a).toBe(b);
+    expect(a).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+  });
+});
+
+describe('trackCommand', () => {
+  const savedEnv = process.env;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockCaptureImmediate.mockResolvedValue(undefined);
+    process.env = { ...savedEnv };
+    delete process.env.CLI_TEST_MODE;
+    delete process.env.MINTLIFY_TELEMETRY_DISABLED;
+    delete process.env.DO_NOT_TRACK;
+    vi.spyOn(fs, 'readFileSync').mockReturnValue(JSON.stringify({ telemetryEnabled: true }));
+  });
+
+  afterEach(() => {
+    process.env = savedEnv;
+  });
+
+  it('captures event when telemetry is enabled', async () => {
+    await trackCommand({ command: 'dev', cliVersion: '1.0.0' });
+
+    expect(mockCaptureImmediate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        event: 'cli.command.executed',
+        properties: expect.objectContaining({
+          command: 'dev',
+          cli_version: '1.0.0',
+          os: os.platform(),
+        }),
+      })
+    );
+  });
+
+  it('does not capture when config has telemetryEnabled: false', async () => {
+    vi.spyOn(fs, 'readFileSync').mockReturnValue(JSON.stringify({ telemetryEnabled: false }));
+    await trackCommand({ command: 'dev' });
+    expect(mockCaptureImmediate).not.toHaveBeenCalled();
+  });
+
+  it('does not capture when MINTLIFY_TELEMETRY_DISABLED is set', async () => {
+    process.env.MINTLIFY_TELEMETRY_DISABLED = '1';
+    await trackCommand({ command: 'dev' });
+    expect(mockCaptureImmediate).not.toHaveBeenCalled();
+  });
+
+  it('resolves when captureImmediate hangs after timeout', async () => {
+    mockCaptureImmediate.mockImplementation(() => new Promise(() => {}));
+    vi.useFakeTimers();
+    try {
+      const done = trackCommand({ command: 'dev' });
+      await vi.advanceTimersByTimeAsync(TELEMETRY_ASYNC_TIMEOUT_MS);
+      await expect(done).resolves.toBeUndefined();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+describe('trackTelemetryPreferenceChange', () => {
+  const savedEnv = process.env;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockCaptureImmediate.mockResolvedValue(undefined);
+    process.env = { ...savedEnv };
+    delete process.env.CLI_TEST_MODE;
+    delete process.env.MINTLIFY_TELEMETRY_DISABLED;
+  });
+
+  afterEach(() => {
+    process.env = savedEnv;
+  });
+
+  it('captures cli.telemetry.preference_changed when enabling', async () => {
+    await trackTelemetryPreferenceChange({ enabled: true });
+
+    expect(mockCaptureImmediate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        event: 'cli.telemetry.preference_changed',
+        properties: expect.objectContaining({ enabled: true, os: os.platform() }),
+      })
+    );
+  });
+
+  it('captures cli.telemetry.preference_changed when disabling', async () => {
+    await trackTelemetryPreferenceChange({ enabled: false });
+
+    expect(mockCaptureImmediate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        event: 'cli.telemetry.preference_changed',
+        properties: expect.objectContaining({ enabled: false, os: os.platform() }),
+      })
+    );
+  });
+
+  it('fires even when MINTLIFY_TELEMETRY_DISABLED is set (captures opt-out)', async () => {
+    process.env.MINTLIFY_TELEMETRY_DISABLED = '1';
+    await trackTelemetryPreferenceChange({ enabled: false });
+    expect(mockCaptureImmediate).toHaveBeenCalledWith(
+      expect.objectContaining({ event: 'cli.telemetry.preference_changed' })
+    );
+  });
+
+  it('does not capture when CLI_TEST_MODE is set', async () => {
+    process.env.CLI_TEST_MODE = 'true';
+    await trackTelemetryPreferenceChange({ enabled: true });
+    expect(mockCaptureImmediate).not.toHaveBeenCalled();
+  });
+});

package/__test__/utils.ts

@@ -1,13 +1,18 @@
 import { cli } from '../src/cli.js';
 
-/**
- * Programmatically set arguments and execute the CLI script
- *
- * @param {...string} args - Additional command arguments.
- */
 export async function runCommand(...args: string[]) {
+  const prevCliTestMode = process.env.CLI_TEST_MODE;
+  process.env.CLI_TEST_MODE = 'true';
   process.argv = ['node', 'cli.js', ...args];
-  return cli({ packageName: 'mint' });
+  try {
+    return await cli({ packageName: 'mint' });
+  } finally {
+    if (prevCliTestMode === undefined) {
+      delete process.env.CLI_TEST_MODE;
+    } else {
+      process.env.CLI_TEST_MODE = prevCliTestMode;
+    }
+  }
 }
 
 export const mockValidOpenApiDocument = {

package/bin/cli.js

@@ -17,19 +17,37 @@ import path from 'path';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 import { accessibilityCheck } from './accessibilityCheck.js';
+import { setTelemetryEnabled } from './config.js';
 import { checkPort, checkForMintJson, checkNodeVersion, upgradeConfig, checkForDocsJson, getVersions, suppressConsoleWarnings, terminate, readLocalOpenApiFile, } from './helpers.js';
 import { init } from './init.js';
 import { mdxLinter } from './mdxLinter.js';
 import { migrateMdx } from './migrateMdx.js';
 import { scrapeSite, scrapePage, scrapeOpenApi } from './scrape.js';
+import { createTelemetryMiddleware } from './telemetry/middleware.js';
+import { trackTelemetryPreferenceChange } from './telemetry/track.js';
 import { update } from './update.js';
 import { addWorkflow } from './workflow.js';
 export const cli = ({ packageName = 'mint' }) => {
+    const telemetryMiddleware = createTelemetryMiddleware();
     render(_jsx(Logs, {}));
     return (yargs(hideBin(process.argv))
         .scriptName(packageName)
+        .option('telemetry', {
+        type: 'boolean',
+        alias: 't',
+        description: 'Enable or disable anonymous usage telemetry',
+    })
+        .middleware((argv) => __awaiter(void 0, void 0, void 0, function* () {
+        if (argv.telemetry !== undefined && argv._.length === 0) {
+            yield setTelemetryEnabled(argv.telemetry);
+            yield trackTelemetryPreferenceChange({ enabled: argv.telemetry });
+            addLog(_jsx(SuccessLog, { message: `telemetry ${argv.telemetry ? 'enabled' : 'disabled'}` }));
+            yield terminate(0);
+        }
+    }), true)
         .middleware(checkNodeVersion)
         .middleware(suppressConsoleWarnings)
+        .middleware(telemetryMiddleware)
         .command('dev', 'initialize a local preview environment', (yargs) => yargs
         .option('open', {
         type: 'boolean',
@@ -412,5 +430,5 @@ export const cli = ({ packageName = 'mint' }) => {
         // Alias option flags --help = -h, default --version = -v
         .alias('h', 'help')
         .alias('v', 'version')
-        .parse());
+        .parseAsync());
 };

package/bin/config.js

@@ -0,0 +1,42 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import fs from 'fs';
+import { ensureDir } from 'fs-extra';
+import { CLI_CONFIG_FILE, CONFIG_DIR } from './constants.js';
+function readConfig() {
+    try {
+        const raw = fs.readFileSync(CLI_CONFIG_FILE, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch (_a) {
+        return {};
+    }
+}
+function writeConfig(updates) {
+    return __awaiter(this, void 0, void 0, function* () {
+        yield ensureDir(CONFIG_DIR);
+        const existing = readConfig();
+        fs.writeFileSync(CLI_CONFIG_FILE, JSON.stringify(Object.assign(Object.assign({}, existing), updates), null, 2));
+    });
+}
+export function isTelemetryEnabled() {
+    if (process.env.CLI_TEST_MODE === 'true')
+        return false;
+    if (process.env.MINTLIFY_TELEMETRY_DISABLED === '1')
+        return false;
+    if (process.env.DO_NOT_TRACK === '1')
+        return false;
+    return readConfig().telemetryEnabled !== false;
+}
+export function setTelemetryEnabled(enabled) {
+    return __awaiter(this, void 0, void 0, function* () {
+        yield writeConfig({ telemetryEnabled: enabled });
+    });
+}

package/bin/constants.js

@@ -1,3 +1,7 @@
 import os from 'os';
+import path from 'path';
 export const HOME_DIR = os.homedir();
 export const CMD_EXEC_PATH = process.cwd();
+export const CONFIG_DIR = path.join(HOME_DIR, '.config', 'mintlify');
+export const CLI_CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+export const TELEMETRY_ASYNC_TIMEOUT_MS = 10000;

package/bin/helpers.js

@@ -22,6 +22,7 @@ import { promisify } from 'node:util';
 import path from 'path';
 import yargs from 'yargs';
 import { CMD_EXEC_PATH } from './constants.js';
+import { shutdownPostHog } from './telemetry/client.js';
 export const checkPort = (argv) => __awaiter(void 0, void 0, void 0, function* () {
     const initialPort = typeof argv.port === 'number' ? argv.port : 3000;
     if (initialPort === (yield detect(initialPort)))
@@ -157,6 +158,7 @@ export const readLocalOpenApiFile = (filename) => __awaiter(void 0, void 0, void
 export const terminate = (code) => __awaiter(void 0, void 0, void 0, function* () {
     // Wait for the logs to be fully rendered before exiting
     yield new Promise((resolve) => setTimeout(resolve, 50));
+    yield shutdownPostHog();
     process.exit(code);
 });
 export const execAsync = promisify(exec);

package/bin/start.js

@@ -1,5 +1,36 @@
 #!/usr/bin/env node
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 var _a;
 import { cli } from './cli.js';
+import { shutdownPostHog } from './telemetry/client.js';
 const packageName = (_a = process.env.MINTLIFY_PACKAGE_NAME) !== null && _a !== void 0 ? _a : 'mint';
-void cli({ packageName });
+cli({ packageName }).catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});
+function shutdown(exitCode) {
+    return __awaiter(this, void 0, void 0, function* () {
+        yield shutdownPostHog();
+        process.exit(exitCode);
+    });
+}
+process.once('beforeExit', () => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        yield shutdownPostHog();
+    }
+    catch (_a) { }
+}));
+process.on('SIGINT', () => {
+    void shutdown(130);
+});
+process.on('SIGTERM', () => {
+    void shutdown(143);
+});

package/bin/telemetry/client.js

@@ -0,0 +1,39 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { PostHog } from 'posthog-node';
+import { TELEMETRY_ASYNC_TIMEOUT_MS } from '../constants.js';
+const POSTHOG_API_KEY = 'phc_eNuN6Ojnk9O7uWfC17z12AK85fNR0BY6IiGVy0Gfwzw';
+const POSTHOG_HOST = 'https://ph.mintlify.com';
+let client = null;
+export function getPostHogClient() {
+    if (!client) {
+        client = new PostHog(POSTHOG_API_KEY, {
+            host: POSTHOG_HOST,
+        });
+    }
+    return client;
+}
+export function shutdownPostHog() {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!client)
+            return;
+        try {
+            yield Promise.race([
+                client.shutdown(),
+                new Promise((resolve) => {
+                    const t = setTimeout(resolve, TELEMETRY_ASYNC_TIMEOUT_MS);
+                    t.unref();
+                }),
+            ]);
+        }
+        catch (_a) { }
+        client = null;
+    });
+}

package/bin/telemetry/distinctId.js

@@ -0,0 +1,62 @@
+import crypto from 'crypto';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { CONFIG_DIR } from '../constants.js';
+const ID_FILE = path.join(CONFIG_DIR, 'anonymous-id');
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+function readValidIdFromFile() {
+    try {
+        const raw = fs.readFileSync(ID_FILE, 'utf-8').trim();
+        if (UUID_RE.test(raw))
+            return raw;
+    }
+    catch (_a) { }
+    return null;
+}
+function stableMachineDistinctId() {
+    var _a, _b;
+    const h = crypto.createHash('sha256');
+    h.update(os.hostname());
+    h.update('\0');
+    h.update(os.homedir());
+    h.update('\0');
+    h.update((_b = (_a = process.env.USER) !== null && _a !== void 0 ? _a : process.env.USERNAME) !== null && _b !== void 0 ? _b : '');
+    const hex = h.digest('hex').slice(0, 32);
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+function tryPersistId(id) {
+    fs.mkdirSync(path.dirname(ID_FILE), { recursive: true });
+    fs.writeFileSync(ID_FILE, id, { flag: 'wx' });
+}
+export function getDistinctId() {
+    var _a, _b, _c;
+    const existing = readValidIdFromFile();
+    if (existing)
+        return existing;
+    const randomId = crypto.randomUUID();
+    try {
+        tryPersistId(randomId);
+        return (_a = readValidIdFromFile()) !== null && _a !== void 0 ? _a : randomId;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'EEXIST') {
+            const concurrent = readValidIdFromFile();
+            if (concurrent)
+                return concurrent;
+            try {
+                fs.writeFileSync(ID_FILE, randomId);
+            }
+            catch (_d) { }
+            return (_b = readValidIdFromFile()) !== null && _b !== void 0 ? _b : randomId;
+        }
+    }
+    const stable = stableMachineDistinctId();
+    try {
+        fs.mkdirSync(path.dirname(ID_FILE), { recursive: true });
+        fs.writeFileSync(ID_FILE, stable);
+    }
+    catch (_e) { }
+    return (_c = readValidIdFromFile()) !== null && _c !== void 0 ? _c : stable;
+}

package/bin/telemetry/middleware.js

@@ -0,0 +1,39 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { getVersions } from '../helpers.js';
+import { trackCommand } from './track.js';
+const SCRAPE_SUBCOMMANDS = new Set(['page', 'site', 'openapi']);
+export function getSanitizedCommandForTelemetry(_) {
+    const parts = _.filter((p) => typeof p === 'string');
+    if (parts.length === 0)
+        return '';
+    const first = parts[0];
+    const second = parts[1];
+    if (first === 'scrape' && second !== undefined && SCRAPE_SUBCOMMANDS.has(second)) {
+        return `scrape ${second}`;
+    }
+    return first;
+}
+export function createTelemetryMiddleware() {
+    let tracked = false;
+    return function telemetryMiddleware(argv) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const command = argv._[0];
+            if (typeof command === 'string') {
+                if (tracked)
+                    return;
+                tracked = true;
+                const sanitizedCommand = getSanitizedCommandForTelemetry(argv._);
+                const { cli: cliVersion } = getVersions();
+                void trackCommand({ command: sanitizedCommand, cliVersion });
+            }
+        });
+    };
+}