@mintlify/cli 4.0.1067 → 4.0.1069

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/cli",
-  "version": "4.0.1067",
+  "version": "4.0.1069",
   "description": "The Mintlify CLI",
   "engines": {
     "node": ">=18.0.0"
@@ -62,6 +62,7 @@
     "inquirer": "12.3.0",
     "js-yaml": "4.1.0",
     "mdast-util-mdx-jsx": "3.2.0",
+    "posthog-node": "5.17.2",
     "react": "19.2.3",
     "semver": "7.7.2",
     "unist-util-visit": "5.0.0",
@@ -87,5 +88,5 @@
     "vitest": "2.1.9",
     "vitest-mock-process": "1.0.4"
   },
-  "gitHead": "330a8577c46d19e4581c1bf47fc31329d617eda3"
+  "gitHead": "10c9be1d7e8d3ccf3f86df9498a1e334090b401e"
 }

package/src/cli.tsx

@@ -24,12 +24,11 @@ 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,
+  autoUpgradeIfNeeded,
   getVersions,
   suppressConsoleWarnings,
   terminate,
@@ -39,17 +38,34 @@ 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' }: { packageName?: string }) => {
+  const telemetryMiddleware = createTelemetryMiddleware();
   render(<Logs />);
 
   return (
     yargs(hideBin(process.argv))
       .scriptName(packageName)
+      .option('telemetry', {
+        type: 'boolean',
+        alias: 't',
+        description: 'Enable or disable anonymous usage telemetry',
+      })
+      .middleware(async (argv) => {
+        if (argv.telemetry !== undefined && argv._.length === 0) {
+          await setTelemetryEnabled(argv.telemetry);
+          await trackTelemetryPreferenceChange({ enabled: argv.telemetry });
+          addLog(<SuccessLog message={`telemetry ${argv.telemetry ? 'enabled' : 'disabled'}`} />);
+          await terminate(0);
+        }
+      }, true)
       .middleware(checkNodeVersion)
       .middleware(suppressConsoleWarnings)
+      .middleware(telemetryMiddleware)
       .command(
         'dev',
         'initialize a local preview environment',
@@ -91,6 +107,7 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
             .example('mintlify dev', 'run with default settings (opens in browser)')
             .example('mintlify dev --no-open', 'run without opening in browser'),
         async (argv) => {
+          await autoUpgradeIfNeeded();
           const port = await checkPort(argv);
           const { cli: cliVersion } = getVersions();
           if (port != undefined) {
@@ -255,11 +272,7 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
               description: 'also check links inside <Snippet> components',
             }),
         async (argv) => {
-          const hasMintJson = await checkForMintJson();
-          if (!hasMintJson) {
-            await checkForDocsJson();
-          }
-
+          await autoUpgradeIfNeeded();
           addLog(<SpinnerLog message="checking for broken links..." />);
           try {
             const graph = await buildGraph(undefined, {
@@ -337,10 +350,7 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
             })
             .epilog('example: `mintlify rename introduction.mdx overview.mdx`'),
         async ({ from, to, force }) => {
-          const hasMintJson = await checkForMintJson();
-          if (!hasMintJson) {
-            await checkForDocsJson();
-          }
+          await autoUpgradeIfNeeded();
           await renameFilesAndUpdateLinksInContent(from, to, force);
           await terminate(0);
         }
@@ -354,18 +364,6 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
           await terminate(0);
         }
       )
-      .command(
-        'upgrade',
-        'upgrade mint.json file to docs.json (current format)',
-        () => undefined,
-        async () => {
-          const hasMintJson = await checkForMintJson();
-          if (!hasMintJson) {
-            await checkForDocsJson();
-          }
-          await upgradeConfig();
-        }
-      )
       .command(
         'migrate-mdx',
         'migrate mdx openapi endpoint pages to x-mint extensions and docs.json',
@@ -571,6 +569,6 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
       .alias('h', 'help')
       .alias('v', 'version')
 
-      .parse()
+      .parseAsync()
   );
 };

package/src/config.ts

@@ -0,0 +1,34 @@
+import fs from 'fs';
+import { ensureDir } from 'fs-extra';
+
+import { CLI_CONFIG_FILE, CONFIG_DIR } from './constants.js';
+
+interface MintlifyConfig {
+  telemetryEnabled?: boolean;
+}
+
+function readConfig(): MintlifyConfig {
+  try {
+    const raw = fs.readFileSync(CLI_CONFIG_FILE, 'utf-8');
+    return JSON.parse(raw) as MintlifyConfig;
+  } catch {
+    return {};
+  }
+}
+
+async function writeConfig(updates: Partial<MintlifyConfig>): Promise<void> {
+  await ensureDir(CONFIG_DIR);
+  const existing = readConfig();
+  fs.writeFileSync(CLI_CONFIG_FILE, JSON.stringify({ ...existing, ...updates }, null, 2));
+}
+
+export function isTelemetryEnabled(): boolean {
+  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 async function setTelemetryEnabled(enabled: boolean): Promise<void> {
+  await writeConfig({ telemetryEnabled: enabled });
+}

package/src/constants.ts

@@ -1,4 +1,9 @@
 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 = 10_000;

package/src/helpers.tsx

@@ -9,6 +9,7 @@ import {
   SpinnerLog,
   removeLastLog,
   LOCAL_LINKED_CLI_VERSION,
+  WarningLog,
 } from '@mintlify/previewing';
 import { upgradeToDocsConfig, validatePathWithinCwd } from '@mintlify/validation';
 import detect from 'detect-port';
@@ -23,6 +24,7 @@ import type { ArgumentsCamelCase } from 'yargs';
 import yargs from 'yargs';
 
 import { CMD_EXEC_PATH } from './constants.js';
+import { shutdownPostHog } from './telemetry/client.js';
 
 export const checkPort = async (argv: ArgumentsCamelCase): Promise<number | undefined> => {
   const initialPort = typeof argv.port === 'number' ? argv.port : 3000;
@@ -93,6 +95,19 @@ export const checkForDocsJson = async () => {
   }
 };
 
+export const autoUpgradeIfNeeded = async () => {
+  const hasMintJson = await checkForMintJson();
+  if (!hasMintJson) return;
+
+  const docsJsonPath = path.join(CMD_EXEC_PATH, 'docs.json');
+  const hasDocsJson = await fse.pathExists(docsJsonPath);
+  if (!hasDocsJson) {
+    addLog(<WarningLog message="Legacy mint.json detected, auto-upgrading to docs.json" />);
+    addLog(<SpinnerLog message="upgrading mint.json to docs.json..." />);
+    await upgradeConfig();
+  }
+};
+
 export const upgradeConfig = async () => {
   try {
     const mintJsonPath = path.join(CMD_EXEC_PATH, 'mint.json');
@@ -183,6 +198,7 @@ export const readLocalOpenApiFile = async (
 export const terminate = async (code: number) => {
   // Wait for the logs to be fully rendered before exiting
   await new Promise((resolve) => setTimeout(resolve, 50));
+  await shutdownPostHog();
   process.exit(code);
 };
 

package/src/start.ts

@@ -1,6 +1,27 @@
 #!/usr/bin/env node
 import { cli } from './cli.js';
+import { shutdownPostHog } from './telemetry/client.js';
 
 const packageName = process.env.MINTLIFY_PACKAGE_NAME ?? 'mint';
 
-void cli({ packageName });
+cli({ packageName }).catch((err: unknown) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+});
+
+async function shutdown(exitCode: number): Promise<never> {
+  await shutdownPostHog();
+  process.exit(exitCode);
+}
+
+process.once('beforeExit', async () => {
+  try {
+    await shutdownPostHog();
+  } catch {}
+});
+process.on('SIGINT', () => {
+  void shutdown(130);
+});
+process.on('SIGTERM', () => {
+  void shutdown(143);
+});

package/src/telemetry/client.ts

@@ -0,0 +1,31 @@
+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: PostHog | null = null;
+
+export function getPostHogClient(): PostHog {
+  if (!client) {
+    client = new PostHog(POSTHOG_API_KEY, {
+      host: POSTHOG_HOST,
+    });
+  }
+  return client;
+}
+
+export async function shutdownPostHog(): Promise<void> {
+  if (!client) return;
+  try {
+    await Promise.race([
+      client.shutdown(),
+      new Promise<void>((resolve) => {
+        const t = setTimeout(resolve, TELEMETRY_ASYNC_TIMEOUT_MS);
+        t.unref();
+      }),
+    ]);
+  } catch {}
+  client = null;
+}

package/src/telemetry/distinctId.ts

@@ -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(): string | null {
+  try {
+    const raw = fs.readFileSync(ID_FILE, 'utf-8').trim();
+    if (UUID_RE.test(raw)) return raw;
+  } catch {}
+  return null;
+}
+
+function stableMachineDistinctId(): string {
+  const h = crypto.createHash('sha256');
+  h.update(os.hostname());
+  h.update('\0');
+  h.update(os.homedir());
+  h.update('\0');
+  h.update(process.env.USER ?? process.env.USERNAME ?? '');
+  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: string): void {
+  fs.mkdirSync(path.dirname(ID_FILE), { recursive: true });
+  fs.writeFileSync(ID_FILE, id, { flag: 'wx' });
+}
+
+export function getDistinctId(): string {
+  const existing = readValidIdFromFile();
+  if (existing) return existing;
+
+  const randomId = crypto.randomUUID();
+
+  try {
+    tryPersistId(randomId);
+    return readValidIdFromFile() ?? randomId;
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === 'EEXIST') {
+      const concurrent = readValidIdFromFile();
+      if (concurrent) return concurrent;
+      try {
+        fs.writeFileSync(ID_FILE, randomId);
+      } catch {}
+      return readValidIdFromFile() ?? randomId;
+    }
+  }
+
+  const stable = stableMachineDistinctId();
+  try {
+    fs.mkdirSync(path.dirname(ID_FILE), { recursive: true });
+    fs.writeFileSync(ID_FILE, stable);
+  } catch {}
+  return readValidIdFromFile() ?? stable;
+}

package/src/telemetry/middleware.ts

@@ -0,0 +1,29 @@
+import { getVersions } from '../helpers.js';
+import { trackCommand } from './track.js';
+
+const SCRAPE_SUBCOMMANDS = new Set(['page', 'site', 'openapi']);
+
+export function getSanitizedCommandForTelemetry(_: (string | number)[]): string {
+  const parts = _.filter((p): p is string => 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(): (argv: { _: (string | number)[] }) => Promise<void> {
+  let tracked = false;
+  return async function telemetryMiddleware(argv: { _: (string | number)[] }): Promise<void> {
+    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 });
+    }
+  };
+}

package/src/telemetry/track.ts

@@ -0,0 +1,60 @@
+import os from 'os';
+
+import { isTelemetryEnabled } from '../config.js';
+import { TELEMETRY_ASYNC_TIMEOUT_MS } from '../constants.js';
+import { getVersions } from '../helpers.js';
+import { getPostHogClient } from './client.js';
+import { getDistinctId } from './distinctId.js';
+
+export interface TrackCommandOptions {
+  command: string;
+  cliVersion?: string;
+}
+
+async function captureWithTimeout(
+  event: string,
+  properties: Record<string, unknown>
+): Promise<void> {
+  await Promise.race([
+    getPostHogClient()
+      .captureImmediate({
+        distinctId: getDistinctId(),
+        event,
+        properties,
+      })
+      .catch(() => {}),
+    new Promise<void>((resolve) => {
+      const t = setTimeout(resolve, TELEMETRY_ASYNC_TIMEOUT_MS);
+      t.unref();
+    }),
+  ]);
+}
+
+export async function trackCommand({ command, cliVersion }: TrackCommandOptions): Promise<void> {
+  if (!isTelemetryEnabled()) return;
+
+  try {
+    await captureWithTimeout('cli.command.executed', {
+      command,
+      cli_version: cliVersion,
+      os: os.platform(),
+      arch: os.arch(),
+      node_version: process.version,
+    });
+  } catch {}
+}
+
+export async function trackTelemetryPreferenceChange(options: { enabled: boolean }): Promise<void> {
+  if (process.env.CLI_TEST_MODE === 'true') return;
+
+  try {
+    const { cli: cliVersion } = getVersions();
+    await captureWithTimeout('cli.telemetry.preference_changed', {
+      enabled: options.enabled,
+      cli_version: cliVersion,
+      os: os.platform(),
+      arch: os.arch(),
+      node_version: process.version,
+    });
+  } catch {}
+}

package/vitest.config.ts

@@ -4,5 +4,6 @@ export default defineConfig({
   test: {
     globals: true,
     testTimeout: 10000,
+    exclude: ['bin/**', 'node_modules/**'],
   },
 });