@mintlify/cli 4.0.1084 → 4.0.1086

package/src/analytics/output.ts

@@ -0,0 +1,97 @@
+import chalk from 'chalk';
+
+export type OutputFormat = 'table' | 'plain' | 'json' | 'graph';
+
+export function resolveFormat(argv: { format?: string; agent?: boolean }): OutputFormat {
+  if (argv.agent || process.env.CLAUDECODE === '1') return 'json';
+  if (
+    argv.format === 'table' ||
+    argv.format === 'plain' ||
+    argv.format === 'json' ||
+    argv.format === 'graph'
+  )
+    return argv.format;
+  return 'plain';
+}
+
+export function formatPlainTable(headers: string[], rows: string[][]): string {
+  if (rows.length === 0) return '';
+
+  const colWidths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map((r) => (r[i] ?? '').length))
+  );
+
+  const headerLine = headers.map((h, i) => h.toUpperCase().padEnd(colWidths[i]!)).join('\t');
+  const bodyLines = rows.map((row) => row.map((cell, i) => cell.padEnd(colWidths[i]!)).join('\t'));
+
+  return [headerLine, ...bodyLines].join('\n');
+}
+
+export function formatPrettyTable(headers: string[], rows: string[][]): string {
+  if (rows.length === 0) return chalk.dim('  No data found.');
+
+  const colWidths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map((r) => (r[i] ?? '').length))
+  );
+
+  const headerLine = headers.map((h, i) => chalk.bold(h.padEnd(colWidths[i]!))).join('  ');
+  const separator = chalk.dim(colWidths.map((w) => '\u2500'.repeat(w)).join('\u2500\u2500'));
+  const bodyLines = rows.map((row) => row.map((cell, i) => cell.padEnd(colWidths[i]!)).join('  '));
+
+  return [headerLine, separator, ...bodyLines].join('\n');
+}
+
+function gradientBar(len: number, rgb: [number, number, number]): string {
+  let result = '';
+  for (let i = 0; i < len; i++) {
+    const t = len === 1 ? 1 : i / (len - 1);
+    const dim = 0.3 + t * 0.7;
+    const r = Math.round(rgb[0] * dim);
+    const g = Math.round(rgb[1] * dim);
+    const b = Math.round(rgb[2] * dim);
+    result += chalk.rgb(r, g, b)('\u2588');
+  }
+  return result;
+}
+
+const COLOR_MAP: Record<string, [number, number, number]> = {
+  cyan: [0, 255, 255],
+  magenta: [255, 0, 255],
+  yellow: [255, 255, 0],
+  green: [0, 255, 100],
+  blue: [80, 140, 255],
+  red: [255, 80, 80],
+};
+
+export function formatBarChart(
+  items: { label: string; value: number; color?: string }[],
+  opts: { maxWidth?: number } = {}
+): string {
+  if (items.length === 0) return chalk.dim('  No data found.');
+
+  const maxWidth = opts.maxWidth ?? 40;
+  const maxVal = Math.max(...items.map((i) => i.value), 1);
+  const maxLabel = Math.max(...items.map((i) => i.label.length));
+  const maxValStr = Math.max(...items.map((i) => i.value.toLocaleString('en-US').length));
+
+  return items
+    .map((item) => {
+      const barLen = Math.round((item.value / maxVal) * maxWidth);
+      const rgb = COLOR_MAP[item.color ?? 'cyan'] ?? COLOR_MAP.cyan!;
+      const bar = barLen > 0 ? gradientBar(barLen, rgb) : '';
+      const pad = ' '.repeat(maxWidth - barLen);
+      return `  ${item.label.padEnd(maxLabel)}  ${bar}${pad} ${item.value.toLocaleString('en-US').padStart(maxValStr)}`;
+    })
+    .join('\n');
+}
+
+export function formatOutput(
+  format: OutputFormat,
+  headers: string[],
+  rows: string[][],
+  jsonData: unknown
+): string {
+  if (format === 'json') return JSON.stringify(jsonData, null, 2);
+  if (format === 'plain') return formatPlainTable(headers, rows);
+  return formatPrettyTable(headers, rows);
+}

package/src/analytics/types.ts

@@ -0,0 +1,132 @@
+export interface KpiResponse {
+  humanVisitors: number;
+  humanViews: number;
+  humanAssistant: number;
+  humanSearches: number;
+  humanFeedback: number;
+  agentVisitors: number;
+  agentViews: number;
+  agentMcpSearches: number;
+}
+
+export interface BucketSummary {
+  id: string;
+  questionSummary: string;
+  size: number;
+  status: string;
+  lastAsked: string | null;
+  lastOccurredAt: string | null;
+  createdAt: string;
+}
+
+export interface BucketsResponse {
+  data: BucketSummary[];
+  pagination: { total: number };
+}
+
+export interface BucketThread {
+  id: string;
+  firstUserMessage: string | null;
+  feedback: { up: number; down: number };
+  resolutionStatus: string | null;
+  length: number;
+  createdAt: string;
+  lastMessageAt: string | null;
+}
+
+export interface BucketThreadsResponse {
+  data: BucketThread[];
+  pagination: { total: number; hasMore: boolean; nextCursor: string | null };
+}
+
+export interface FeedbackItem {
+  id: string;
+  path: string;
+  comment: string | null;
+  createdAt: string | null;
+  source: string;
+  status: string;
+  helpful?: boolean;
+  contact?: string;
+  code?: string;
+  filename?: string;
+  lang?: string;
+}
+
+export interface FeedbackResponse {
+  feedback: FeedbackItem[];
+  nextCursor: string | null;
+  hasMore: boolean;
+}
+
+export interface FeedbackByPageItem {
+  path: string;
+  thumbsUp: number;
+  thumbsDown: number;
+  code: number;
+  total: number;
+}
+
+export interface FeedbackByPageResponse {
+  feedback: FeedbackByPageItem[];
+  hasMore: boolean;
+}
+
+export interface ConversationSource {
+  title: string;
+  url: string;
+}
+
+export interface Conversation {
+  id: string;
+  timestamp: string;
+  query: string;
+  response: string;
+  sources: ConversationSource[];
+  queryCategory: string | null;
+}
+
+export interface ConversationResponse {
+  conversations: Conversation[];
+  nextCursor: string | null;
+  hasMore: boolean;
+}
+
+export interface SearchRow {
+  searchQuery: string;
+  hits: number;
+  ctr: number;
+  topClickedPage: string | null;
+  lastSearchedAt: string;
+}
+
+export interface SearchResponse {
+  searches: SearchRow[];
+  totalSearches: number;
+  nextCursor: string | null;
+}
+
+export interface TrafficTotals {
+  human: number;
+  ai: number;
+  total: number;
+}
+
+export interface TrafficRow {
+  path: string;
+  human: number;
+  ai: number;
+  total: number;
+}
+
+export interface ViewsResponse {
+  totals: TrafficTotals;
+  views: TrafficRow[];
+  hasMore: boolean;
+}
+
+export interface VisitorsResponse {
+  totals: TrafficTotals;
+  visitors: TrafficRow[];
+  hasMore: boolean;
+}

package/src/callbackServer.ts

@@ -0,0 +1,64 @@
+import { CALLBACK_PORT, DASHBOARD_URL } from './constants.js';
+
+export async function startCallbackServer(): Promise<{
+  codePromise: Promise<string>;
+  close: () => void;
+}> {
+  const { default: http } = await import('http');
+
+  let resolveCode: (code: string) => void;
+  let rejectCode: (err: Error) => void;
+  let closed = false;
+
+  const codePromise = new Promise<string>((res, rej) => {
+    resolveCode = res;
+    rejectCode = rej;
+  });
+
+  const server = http.createServer((req, res) => {
+    res.setHeader('Access-Control-Allow-Origin', DASHBOARD_URL);
+    res.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    if (req.method === 'POST') {
+      let body = '';
+      req.on('data', (chunk) => {
+        body += chunk;
+      });
+      req.on('end', () => {
+        try {
+          const { code } = JSON.parse(body) as { code: string };
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: true }));
+          closed = true;
+          server.close();
+          resolveCode(code);
+        } catch {
+          res.writeHead(400);
+          res.end(JSON.stringify({ error: 'invalid body' }));
+        }
+      });
+    } else {
+      res.writeHead(405);
+      res.end();
+    }
+  });
+
+  server.listen(CALLBACK_PORT, 'localhost');
+
+  const close = () => {
+    if (!closed) {
+      closed = true;
+      server.close();
+      rejectCode(new Error('Login cancelled'));
+    }
+  };
+
+  return { codePromise, close };
+}

package/src/cli.tsx

@@ -19,9 +19,11 @@ import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 
 import { accessibilityCheck } from './accessibilityCheck.js';
+import { analyticsBuilder } from './analytics/index.js';
 import { setTelemetryEnabled } from './config.js';
-import { CMD_EXEC_PATH } from './constants.js';
+import { getConfigValue, setConfigValue, clearConfigValue } from './config.js';
 import {
+  CMD_EXEC_PATH,
   checkPort,
   checkNodeVersion,
   autoUpgradeIfNeeded,
@@ -315,7 +317,7 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
       )
       .command(
         'status',
-        false,
+        'View current authentication status',
         () => undefined,
         async () => {
           await status();
@@ -324,7 +326,7 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
       )
       .command(
         'logout',
-        false,
+        'logout of your mintlify account',
         () => undefined,
         async () => {
           await logout();
@@ -333,13 +335,98 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
       )
       .command(
         'login',
-        false,
+        'authenticate your account to mintlify',
         () => undefined,
         async () => {
           await login();
           await terminate(0);
         }
       )
+      .command('config', 'manage CLI configuration', (yargs) =>
+        yargs
+          .command(
+            'set <key> <value>',
+            'set a configuration value',
+            (yargs) =>
+              yargs
+                .positional('key', {
+                  type: 'string',
+                  demandOption: true,
+                  description: 'Config key (e.g. subdomain)',
+                })
+                .positional('value', {
+                  type: 'string',
+                  demandOption: true,
+                  description: 'Config value',
+                }),
+            async (argv) => {
+              const validKeys = ['subdomain', 'dateFrom', 'dateTo'];
+              if (!validKeys.includes(argv.key)) {
+                addLog(
+                  <ErrorLog
+                    message={`Unknown config key: "${argv.key}". Valid keys: ${validKeys.join(', ')}`}
+                  />
+                );
+                await terminate(1);
+                return;
+              }
+              await setConfigValue(argv.key, argv.value);
+              addLog(<SuccessLog message={`${argv.key} = "${argv.value}"`} />);
+              await terminate(0);
+            }
+          )
+          .command(
+            'get <key>',
+            'get a configuration value',
+            (yargs) =>
+              yargs.positional('key', {
+                type: 'string',
+                demandOption: true,
+                description: 'Config key (e.g. subdomain, dateFrom, dateTo)',
+              }),
+            async (argv) => {
+              const validKeys = ['subdomain', 'dateFrom', 'dateTo'];
+              if (!validKeys.includes(argv.key)) {
+                addLog(
+                  <ErrorLog
+                    message={`Unknown config key: "${argv.key}". Valid keys: ${validKeys.join(', ')}`}
+                  />
+                );
+                await terminate(1);
+                return;
+              }
+              const val = getConfigValue(argv.key);
+              addLog(<Text>{val ?? 'not set'}</Text>);
+              await terminate(0);
+            }
+          )
+          .command(
+            'clear <key>',
+            'remove a configuration value',
+            (yargs) =>
+              yargs.positional('key', {
+                type: 'string',
+                demandOption: true,
+                description: 'Config key (e.g. subdomain, dateFrom, dateTo)',
+              }),
+            async (argv) => {
+              const validKeys = ['subdomain', 'dateFrom', 'dateTo'];
+              if (!validKeys.includes(argv.key)) {
+                addLog(
+                  <ErrorLog
+                    message={`Unknown config key: "${argv.key}". Valid keys: ${validKeys.join(', ')}`}
+                  />
+                );
+                await terminate(1);
+                return;
+              }
+              await clearConfigValue(argv.key);
+              addLog(<SuccessLog message={`${argv.key} cleared`} />);
+              await terminate(0);
+            }
+          )
+          .demandCommand(1, 'specify a subcommand: set, get, or clear')
+      )
       .command(
         'update',
         'update the CLI to the latest version',
@@ -463,6 +550,7 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
           }
         }
       )
+      .command('analytics', 'view analytics for your documentation', analyticsBuilder)
       // Print the help menu when the user enters an invalid command.
       .strictCommands()
       .demandCommand(1, 'unknown command. see above for the list of supported commands.')

package/src/config.ts

@@ -5,6 +5,9 @@ import { CLI_CONFIG_FILE, CONFIG_DIR } from './constants.js';
 
 interface MintlifyConfig {
   telemetryEnabled?: boolean;
+  subdomain?: string;
+  dateFrom?: string;
+  dateTo?: string;
 }
 
 function readConfig(): MintlifyConfig {
@@ -32,3 +35,16 @@ export function isTelemetryEnabled(): boolean {
 export async function setTelemetryEnabled(enabled: boolean): Promise<void> {
   await writeConfig({ telemetryEnabled: enabled });
 }
+
+export function getConfigValue(key: string): string | undefined {
+  const config = readConfig();
+  return config[key as keyof MintlifyConfig] as string | undefined;
+}
+
+export async function setConfigValue(key: string, value: string): Promise<void> {
+  await writeConfig({ [key]: value });
+}
+
+export async function clearConfigValue(key: string): Promise<void> {
+  await writeConfig({ [key]: undefined });
+}

package/src/constants.ts

@@ -1,14 +1,33 @@
+import { LOCAL_LINKED_CLI_VERSION } from '@mintlify/previewing';
 import os from 'os';
 import path from 'path';
 
+import { getCliVersion } from './helpers.js';
+
 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;
 
-export const DASHBOARD_URL = process.env.MINTLIFY_DASHBOARD_URL ?? 'http://localhost:3000';
-export const TOKEN_ENDPOINT =
+export const CALLBACK_PORT = 11582;
+
+const IS_LOCAL_BUILD =
+  process.env.CLI_TEST_MODE === 'true' ? true : getCliVersion() == LOCAL_LINKED_CLI_VERSION;
+
+export const API_URL =
+  process.env.MINTLIFY_API_URL ??
+  (IS_LOCAL_BUILD ? 'http://localhost:5000' : 'https://leaves.mintlify.com');
+export const DASHBOARD_URL =
+  process.env.MINTLIFY_DASHBOARD_URL ??
+  (IS_LOCAL_BUILD ? 'http://localhost:3000' : 'https://dashboard.mintlify.com');
+
+const DEV_TOKEN_ENDPOINT =
   'https://test.stytch.com/v1/public/project-test-2d86347b-dfdb-4609-be69-12d8146220bd/oauth2/token';
-export const STYTCH_CLIENT_ID = 'connected-app-test-b597afb3-304a-420f-bc13-dacca566c59f';
+const DEV_STYTCH_CLIENT_ID = 'connected-app-test-b597afb3-304a-420f-bc13-dacca566c59f';
+const PROD_TOKEN_ENDPOINT =
+  'https://api.stytch.com/v1/public/project-live-731b7a04-9ac3-4923-90b8-0806d4aa29d4/oauth2/token';
+const PROD_STYTCH_CLIENT_ID = 'connected-app-live-d813eedd-dbb0-434b-a1f9-2ce69e5efc49';
+
+export const TOKEN_ENDPOINT = IS_LOCAL_BUILD ? DEV_TOKEN_ENDPOINT : PROD_TOKEN_ENDPOINT;
+export const STYTCH_CLIENT_ID = IS_LOCAL_BUILD ? DEV_STYTCH_CLIENT_ID : PROD_STYTCH_CLIENT_ID;

package/src/helpers.tsx

@@ -23,9 +23,10 @@ import path from 'path';
 import type { ArgumentsCamelCase } from 'yargs';
 import yargs from 'yargs';
 
-import { CMD_EXEC_PATH } from './constants.js';
 import { shutdownPostHog } from './telemetry/client.js';
 
+export const CMD_EXEC_PATH = process.cwd();
+
 export const checkPort = async (argv: ArgumentsCamelCase): Promise<number | undefined> => {
   const initialPort = typeof argv.port === 'number' ? argv.port : 3000;
   if (initialPort === (await detect(initialPort))) return initialPort;

package/src/keyring.ts

@@ -4,7 +4,9 @@ const REFRESH_TOKEN_ACCOUNT = 'refresh_token';
 
 async function getKeytar(): Promise<typeof import('keytar')> {
   try {
-    return await import('keytar');
+    const mod = await import('keytar');
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- ESM wraps CJS in { default: ... } at runtime despite types
+    return mod.default ?? mod;
   } catch {
     throw new Error(
       'keytar is required for credential storage but is not installed. Install it with: npm install keytar'

package/src/login.tsx

@@ -10,6 +10,7 @@ import {
   randomState,
 } from 'openid-client';
 
+import { startCallbackServer } from './callbackServer.js';
 import { DASHBOARD_URL, STYTCH_CLIENT_ID, TOKEN_ENDPOINT } from './constants.js';
 import { storeCredentials } from './keyring.js';
 
@@ -36,6 +37,8 @@ export async function login(): Promise<void> {
   authorizeUrl.searchParams.set('code_challenge', codeChallenge);
   const url = authorizeUrl.toString();
 
+  const { codePromise, close: closeServer } = await startCallbackServer();
+
   addLog(
     <Box flexDirection="column" gap={1} paddingY={1}>
       <Text bold>
@@ -60,7 +63,7 @@ export async function login(): Promise<void> {
   // Let ink finish rendering before inquirer takes over stdout
   await new Promise((resolve) => setTimeout(resolve, 50));
 
-  const code = await input({
+  const inputPromise = input({
     message: '█',
     theme: {
       prefix: chalk.dim(' │'),
@@ -70,6 +73,19 @@ export async function login(): Promise<void> {
     },
   });
 
+  let code: string;
+  try {
+    code = await Promise.race([codePromise, inputPromise]);
+  } catch {
+    closeServer();
+    inputPromise.cancel();
+    addLog(<Text color="red">✖ Login cancelled.</Text>);
+    return;
+  }
+
+  closeServer();
+  inputPromise.cancel();
+
   const res = await fetch(TOKEN_ENDPOINT, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
@@ -95,6 +111,5 @@ export async function login(): Promise<void> {
 
   const token = body as TokenResponse;
   await storeCredentials(token.access_token, token.refresh_token);
-
   addLog(<Text color="green">✔ Logged in successfully.</Text>);
 }

package/src/status.tsx

@@ -2,10 +2,9 @@ import { addLog } from '@mintlify/previewing';
 import { Text } from 'ink';
 import { z } from 'zod';
 
+import { API_URL } from './constants.js';
 import { getAccessToken } from './keyring.js';
 
-const API_URL = process.env.MINTLIFY_API_URL ?? 'http://localhost:5000';
-
 const StatusResponseSchema = z.object({
   user: z.object({ email: z.string() }),
   org: z.object({ name: z.string() }),

package/src/telemetry/client.ts

@@ -1,6 +1,6 @@
 import { PostHog } from 'posthog-node';
 
-import { TELEMETRY_ASYNC_TIMEOUT_MS } from '../constants.js';
+const TELEMETRY_ASYNC_TIMEOUT_MS = 10_000;
 
 const POSTHOG_API_KEY = 'phc_eNuN6Ojnk9O7uWfC17z12AK85fNR0BY6IiGVy0Gfwzw';
 const POSTHOG_HOST = 'https://ph.mintlify.com';

package/src/workflow.tsx

@@ -4,7 +4,7 @@ import fse from 'fs-extra';
 import { Text } from 'ink';
 import path from 'path';
 
-import { CMD_EXEC_PATH } from './constants.js';
+import { CMD_EXEC_PATH } from './helpers.js';
 
 export function slugify(name: string): string {
   return name