@mintlify/cli 4.0.1812 → 4.1.1

package/src/telemetry/client.ts

@@ -1,46 +0,0 @@
-import { PostHog } from 'posthog-node';
-
-const TELEMETRY_ASYNC_TIMEOUT_MS = 10_000;
-
-const POSTHOG_API_KEY = 'phc_eNuN6Ojnk9O7uWfC17z12AK85fNR0BY6IiGVy0Gfwzw';
-const POSTHOG_HOST = 'https://ph.mintlify.com';
-
-let client: PostHog | null = null;
-let pendingWork: Promise<void> = Promise.resolve();
-
-export function getPostHogClient(): PostHog {
-  if (!client) {
-    client = new PostHog(POSTHOG_API_KEY, {
-      host: POSTHOG_HOST,
-    });
-  }
-  return client;
-}
-
-export function deferShutdownUntil(work: Promise<void>): void {
-  pendingWork = Promise.allSettled([pendingWork, work]).then(() => undefined);
-}
-
-export async function shutdownPostHog(): Promise<void> {
-  try {
-    await Promise.race([
-      pendingWork,
-      new Promise<void>((resolve) => {
-        const t = setTimeout(resolve, TELEMETRY_ASYNC_TIMEOUT_MS);
-        t.unref();
-      }),
-    ]);
-  } catch {}
-
-  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

@@ -1,70 +0,0 @@
-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' });
-}
-
-let createdThisRun = false;
-
-export function isFirstRun(): boolean {
-  getDistinctId();
-  return createdThisRun;
-}
-
-export function getDistinctId(): string {
-  const existing = readValidIdFromFile();
-  if (existing) return existing;
-
-  const randomId = crypto.randomUUID();
-
-  try {
-    tryPersistId(randomId);
-    createdThisRun = true;
-    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/sessionId.ts

@@ -1,40 +0,0 @@
-import crypto from 'crypto';
-import fs from 'fs';
-import path from 'path';
-
-import { CONFIG_DIR } from '../constants.js';
-
-const SESSION_FILE = path.join(CONFIG_DIR, 'telemetry-session.json');
-const SESSION_IDLE_MS = 30 * 60 * 1000;
-
-let current: string | undefined;
-
-function uuidv7(now: number): string {
-  const bytes = crypto.randomBytes(16);
-  bytes.writeUIntBE(now, 0, 6);
-  bytes[6] = (bytes[6]! & 0x0f) | 0x70;
-  bytes[8] = (bytes[8]! & 0x3f) | 0x80;
-  const hex = bytes.toString('hex');
-  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
-}
-
-function readSession(): { id: string; lastSeenAt: number } | null {
-  try {
-    const { id, lastSeenAt } = JSON.parse(fs.readFileSync(SESSION_FILE, 'utf-8'));
-    return typeof id === 'string' && typeof lastSeenAt === 'number' ? { id, lastSeenAt } : null;
-  } catch {
-    return null;
-  }
-}
-
-export function getSessionId(now = Date.now()): string {
-  if (!current) {
-    const saved = readSession();
-    current = saved && now - saved.lastSeenAt < SESSION_IDLE_MS ? saved.id : uuidv7(now);
-  }
-  try {
-    fs.mkdirSync(CONFIG_DIR, { recursive: true });
-    fs.writeFileSync(SESSION_FILE, JSON.stringify({ id: current, lastSeenAt: now }));
-  } catch {}
-  return current;
-}

package/src/telemetry/track.ts

@@ -1,163 +0,0 @@
-import os from 'os';
-
-import { detectAgent, isCI } from '../agent.js';
-import { isTelemetryEnabled } from '../config.js';
-import { TELEMETRY_ASYNC_TIMEOUT_MS, TELEMETRY_IDENTITY_TIMEOUT_MS } from '../constants.js';
-import { getVersions } from '../helpers.js';
-import { getAccessToken, getUserEmail, storeUserEmail } from '../keyring.js';
-import { fetchCliStatus } from '../status.js';
-import { deferShutdownUntil, getPostHogClient } from './client.js';
-import { getDistinctId, isFirstRun } from './distinctId.js';
-import { getSessionId } from './sessionId.js';
-
-export interface TrackCommandOptions {
-  command: string;
-  cliVersion?: string;
-  subdomain?: string;
-}
-
-function getEnvironmentProperties(): Record<string, unknown> {
-  const agent = detectAgent();
-  return {
-    os: os.platform(),
-    arch: os.arch(),
-    node_version: process.version,
-    is_ai_agent: agent !== undefined,
-    ai_agent: agent,
-    is_ci: isCI(),
-    is_tty: Boolean(process.stdin.isTTY),
-    is_first_run: isFirstRun(),
-    $session_id: getSessionId(),
-  };
-}
-
-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();
-    }),
-  ]);
-}
-
-async function getIdentity(): Promise<{ loggedIn: boolean; email: string | null }> {
-  try {
-    const [accessToken, storedEmail] = await Promise.all([
-      getAccessToken(),
-      getUserEmail().catch(() => null),
-    ]);
-    if (!accessToken) return { loggedIn: false, email: null };
-    if (storedEmail) return { loggedIn: true, email: storedEmail };
-
-    const status = await fetchCliStatus(AbortSignal.timeout(TELEMETRY_IDENTITY_TIMEOUT_MS));
-    if (!status.ok) return { loggedIn: true, email: null };
-
-    const email = status.status.user.email;
-    await storeUserEmail(email).catch(() => {});
-    return { loggedIn: true, email };
-  } catch {
-    return { loggedIn: false, email: null };
-  }
-}
-
-async function getIdentityProperties(): Promise<Record<string, unknown>> {
-  const { loggedIn, email } = await getIdentity();
-  return { is_logged_in: loggedIn, ...(email ? { email, $set: { email } } : {}) };
-}
-
-export async function trackCommand({
-  command,
-  cliVersion,
-  subdomain,
-}: TrackCommandOptions): Promise<void> {
-  if (!isTelemetryEnabled()) return;
-
-  const work = (async () => {
-    try {
-      await captureWithTimeout('cli.command.executed', {
-        command,
-        cli_version: cliVersion,
-        ...getEnvironmentProperties(),
-        ...(await getIdentityProperties()),
-        subdomain,
-      });
-    } catch {}
-  })();
-
-  deferShutdownUntil(work);
-  await work;
-}
-
-async function trackLoginEvent(event: string, extra?: Record<string, unknown>): Promise<void> {
-  if (!isTelemetryEnabled()) return;
-
-  const work = (async () => {
-    try {
-      const { cli: cliVersion } = getVersions();
-      await captureWithTimeout(event, {
-        ...extra,
-        cli_version: cliVersion,
-        ...getEnvironmentProperties(),
-        ...(await getIdentityProperties()),
-      });
-    } catch {}
-  })();
-  deferShutdownUntil(work);
-  await work;
-}
-
-export async function trackLoginAttempt(): Promise<void> {
-  return trackLoginEvent('cli.login.attempted');
-}
-
-export async function trackLoginSuccess(): Promise<void> {
-  return trackLoginEvent('cli.login.succeeded');
-}
-
-export async function trackLoginFailed(reason: string): Promise<void> {
-  return trackLoginEvent('cli.login.failed', { reason });
-}
-
-export async function trackEvent(
-  event: string,
-  properties?: Record<string, unknown>
-): Promise<void> {
-  if (!isTelemetryEnabled()) return;
-
-  const work = (async () => {
-    try {
-      const { cli: cliVersion } = getVersions();
-      await captureWithTimeout(event, {
-        ...properties,
-        cli_version: cliVersion,
-        ...getEnvironmentProperties(),
-        ...(await getIdentityProperties()),
-      });
-    } catch {}
-  })();
-  deferShutdownUntil(work);
-  await work;
-}
-
-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,
-      ...getEnvironmentProperties(),
-    });
-  } catch {}
-}

package/src/templates.tsx

@@ -1,143 +0,0 @@
-import { select } from '@inquirer/prompts';
-import { addLog, SpinnerLog, removeLastLog } from '@mintlify/previewing';
-import AdmZip from 'adm-zip';
-import fse from 'fs-extra';
-import path from 'path';
-
-const TEMPLATES_REPO_OWNER = 'mintlify';
-const TEMPLATES_REPO_NAME = 'templates';
-const TEMPLATES_REPO_BRANCH = 'main';
-
-interface GitHubContentEntry {
-  name: string;
-  type: 'file' | 'dir';
-  path: string;
-}
-
-export async function fetchAvailableTemplates(): Promise<string[]> {
-  const url = `https://api.github.com/repos/${TEMPLATES_REPO_OWNER}/${TEMPLATES_REPO_NAME}/contents/?ref=${TEMPLATES_REPO_BRANCH}`;
-  const response = await fetch(url, {
-    headers: { Accept: 'application/vnd.github.v3+json' },
-  });
-
-  if (!response.ok) {
-    throw new Error(`Failed to fetch templates: ${response.status} ${response.statusText}`);
-  }
-
-  const entries: GitHubContentEntry[] = (await response.json()) as GitHubContentEntry[];
-  return entries.filter((entry) => entry.type === 'dir').map((entry) => entry.name);
-}
-
-export async function validateTemplateName(templateName: string): Promise<string> {
-  if (
-    !templateName ||
-    templateName === '.' ||
-    templateName === '..' ||
-    templateName.includes('/')
-  ) {
-    throw new Error(`Invalid template name: "${templateName}".`);
-  }
-
-  const url = `https://api.github.com/repos/${TEMPLATES_REPO_OWNER}/${TEMPLATES_REPO_NAME}/contents/${encodeURIComponent(templateName)}?ref=${TEMPLATES_REPO_BRANCH}`;
-  const response = await fetch(url, {
-    headers: { Accept: 'application/vnd.github.v3+json' },
-  });
-
-  if (!response.ok) {
-    const available = await fetchAvailableTemplates().catch(() => []);
-    const suggestion = available.length > 0 ? ` Available templates: ${available.join(', ')}` : '';
-    throw new Error(
-      `Template "${templateName}" not found in ${TEMPLATES_REPO_OWNER}/${TEMPLATES_REPO_NAME}.${suggestion}`
-    );
-  }
-
-  const entries: GitHubContentEntry[] = (await response.json()) as GitHubContentEntry[];
-  const hasDocsJson = entries.some((entry) => entry.name === 'docs.json');
-  if (!hasDocsJson) {
-    throw new Error(
-      `Template "${templateName}" is not a valid Mintlify template (missing docs.json).`
-    );
-  }
-
-  return templateName;
-}
-
-export async function promptForTemplate(): Promise<string> {
-  addLog(<SpinnerLog message="fetching available templates..." />);
-  let templateNames: string[];
-  try {
-    templateNames = await fetchAvailableTemplates();
-  } catch {
-    removeLastLog();
-    throw new Error(
-      'Failed to fetch templates. Please check your network connection and try again.'
-    );
-  }
-  removeLastLog();
-
-  if (templateNames.length === 0) {
-    throw new Error('No templates are currently available.');
-  }
-
-  return select({
-    message: 'Choose a template',
-    choices: templateNames.map((t) => ({ name: t, value: t })),
-  });
-}
-
-export async function installFromTemplate(
-  installDir: string,
-  templateName: string,
-  projectName?: string,
-  theme?: string
-): Promise<void> {
-  const zipPath = path.join(installDir, '__template__.zip');
-  const extractDir = path.join(installDir, '__template_extract__');
-
-  try {
-    addLog(<SpinnerLog message={`downloading template "${templateName}"...`} />);
-    try {
-      const zipUrl = `https://github.com/${TEMPLATES_REPO_OWNER}/${TEMPLATES_REPO_NAME}/archive/refs/heads/${TEMPLATES_REPO_BRANCH}.zip`;
-      const response = await fetch(zipUrl);
-      if (!response.ok) {
-        throw new Error(`Failed to download templates archive: ${response.status}`);
-      }
-      const buffer = await response.arrayBuffer();
-      await fse.writeFile(zipPath, Buffer.from(buffer));
-    } finally {
-      removeLastLog();
-    }
-
-    addLog(<SpinnerLog message="extracting template..." />);
-    try {
-      const zip = new AdmZip(zipPath);
-      zip.extractAllTo(extractDir, true);
-    } finally {
-      removeLastLog();
-    }
-
-    const repoRoot = path.join(extractDir, `${TEMPLATES_REPO_NAME}-${TEMPLATES_REPO_BRANCH}`);
-    const templateDir = path.join(repoRoot, templateName);
-
-    if (!(await fse.pathExists(templateDir))) {
-      throw new Error(`Template directory "${templateName}" not found in the downloaded archive.`);
-    }
-
-    await fse.copy(templateDir, installDir, { overwrite: true });
-  } finally {
-    await fse.remove(zipPath).catch(() => {});
-    await fse.remove(extractDir).catch(() => {});
-  }
-
-  const docsJsonPath = path.join(installDir, 'docs.json');
-  if (await fse.pathExists(docsJsonPath)) {
-    const docsConfig = await fse.readJson(docsJsonPath);
-    if (projectName) {
-      docsConfig.name = projectName;
-    }
-    if (theme) {
-      docsConfig.theme = theme;
-    }
-    await fse.writeJson(docsJsonPath, docsConfig, { spaces: 2 });
-  }
-}

package/src/tokenRefresh.ts

@@ -1,53 +0,0 @@
-import { TOKEN_ENDPOINT } from './constants.js';
-import { getEmailFromIdToken } from './idToken.js';
-import { getRefreshToken, storeCredentials } from './keyring.js';
-
-interface TokenResponse {
-  access_token: string;
-  id_token?: string;
-  refresh_token: string;
-  token_type: 'bearer';
-  expires_in: number;
-}
-
-let inflightRefresh: Promise<string | null> | null = null;
-
-export async function refreshAccessToken(): Promise<string | null> {
-  if (inflightRefresh) return inflightRefresh;
-
-  inflightRefresh = doRefresh().finally(() => {
-    inflightRefresh = null;
-  });
-
-  return inflightRefresh;
-}
-
-async function doRefresh(): Promise<string | null> {
-  try {
-    const refreshToken = await getRefreshToken();
-    if (!refreshToken) return null;
-
-    const res = await fetch(TOKEN_ENDPOINT, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        grant_type: 'refresh_token',
-        refresh_token: refreshToken,
-      }),
-    });
-
-    if (!res.ok) return null;
-
-    const body = (await res.json().catch(() => null)) as TokenResponse | null;
-    if (!body?.access_token || !body.refresh_token) return null;
-
-    await storeCredentials(
-      body.access_token,
-      body.refresh_token,
-      getEmailFromIdToken(body.id_token)
-    );
-    return body.access_token;
-  } catch {
-    return null;
-  }
-}

package/src/update.tsx

@@ -1,89 +0,0 @@
-import {
-  SpinnerLog,
-  SuccessLog,
-  ErrorLog,
-  addLog,
-  addErrorLog,
-  clearLogs,
-  getLatestClientVersion,
-  downloadTargetMint,
-  getClientVersion,
-} from '@mintlify/previewing';
-
-import {
-  assertValidPackageName,
-  execFileAsync,
-  getLatestCliVersion,
-  getVersions,
-  detectPackageManager,
-  windowsCompatibleSpawnOptions,
-} from './helpers.js';
-
-export const update = async ({ packageName }: { packageName: string }) => {
-  assertValidPackageName(packageName);
-  addLog(<SpinnerLog message="updating..." />);
-  const { cli: existingCliVersion } = getVersions(packageName);
-  const latestCliVersion = getLatestCliVersion(packageName);
-  const isUpToDate =
-    existingCliVersion && latestCliVersion && latestCliVersion.trim() === existingCliVersion.trim();
-
-  if (!isUpToDate && existingCliVersion && latestCliVersion.trim() !== existingCliVersion.trim()) {
-    const packageManager = await detectPackageManager({ packageName });
-    try {
-      clearLogs();
-      addLog(<SpinnerLog message={`updating ${packageName} package...`} />);
-
-      if (packageManager === 'pnpm') {
-        await execFileAsync(
-          'pnpm',
-          ['install', '-g', `${packageName}@latest`, '--silent'],
-          windowsCompatibleSpawnOptions
-        );
-      } else {
-        await execFileAsync(
-          'npm',
-          ['install', '-g', `${packageName}@latest`, '--silent'],
-          windowsCompatibleSpawnOptions
-        );
-      }
-    } catch (err) {
-      const errorMessage = err instanceof Error ? err.message : String(err);
-      addErrorLog(
-        <ErrorLog
-          message={`Failed to update ${packageName}@${latestCliVersion} using ${packageManager}: ${errorMessage}`}
-        />
-      );
-      return;
-    }
-  }
-
-  clearLogs();
-  addLog(<SpinnerLog message="updating client..." />);
-  let clientUpdated = false;
-  const latestClientVersion = await getLatestClientVersion();
-  if (latestClientVersion) {
-    const existingClientVersion = getClientVersion().trim();
-    if (existingClientVersion !== latestClientVersion.trim()) {
-      try {
-        await downloadTargetMint({
-          targetVersion: latestClientVersion,
-          existingVersion: existingClientVersion === 'none' ? null : existingClientVersion,
-        });
-        clientUpdated = true;
-      } catch (err) {
-        const errorMessage = err instanceof Error ? err.message : String(err);
-        addErrorLog(<ErrorLog message={`Failed to update client: ${errorMessage}`} />);
-        return;
-      }
-    }
-  }
-
-  clearLogs();
-  if (isUpToDate && !clientUpdated) {
-    addLog(<SuccessLog message="already up to date" />);
-  } else {
-    addLog(
-      <SuccessLog message={`updated ${packageName} to the latest version: ${latestCliVersion}`} />
-    );
-  }
-};