@mintlify/cli 4.0.1109 → 4.0.1111

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/cli",
-  "version": "4.0.1109",
+  "version": "4.0.1111",
   "description": "The Mintlify CLI",
   "engines": {
     "node": ">=18.0.0"
@@ -93,5 +93,5 @@
     "vitest": "2.1.9",
     "vitest-mock-process": "1.0.4"
   },
-  "gitHead": "b1b4d6293cb62b84161652d8a26e509941f562b5"
+  "gitHead": "38703fc288945eaeaea97ea561f5ff35b15fd6e4"
 }

package/src/cli.tsx

@@ -15,7 +15,7 @@ import {
 import { render, Text } from 'ink';
 import fs from 'node:fs/promises';
 import path from 'path';
-import yargs from 'yargs';
+import yargs, { type Argv } from 'yargs';
 import { hideBin } from 'yargs/helpers';
 
 import { accessibilityCheck } from './accessibilityCheck.js';
@@ -40,6 +40,7 @@ import { logout } from './logout.js';
 import { mdxLinter } from './mdxLinter.js';
 import { createTelemetryMiddleware } from './middlewares/telemetryMiddleware.js';
 import { checkOpenApiFile, getOpenApiFilenamesFromDocsConfig } from './openApiCheck.js';
+import { scoreHandler } from './score/index.js';
 import { status, getCliSubdomains } from './status.js';
 import { trackTelemetryPreferenceChange } from './telemetry/track.js';
 import { update } from './update.js';
@@ -570,6 +571,24 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
         }
       )
       .command('analytics', 'View analytics for your documentation', analyticsBuilder)
+      .command(
+        'score <url>',
+        'Run agent readiness checks on a docs site',
+        (yargs: Argv) =>
+          yargs
+            .positional('url', {
+              type: 'string',
+              demandOption: true,
+              description: 'URL of the docs site to check',
+            })
+            .option('format', {
+              type: 'string',
+              choices: ['table', 'plain', 'json'] as const,
+              description: 'Output format',
+            })
+            .example('mint score docs.example.com', 'Run agent readiness checks'),
+        scoreHandler
+      )
       // Coming soon commands — visible in help, tracked via telemetry to gauge interest.
       .command(
         'ai',

package/src/middlewares/telemetryMiddleware.ts

@@ -3,15 +3,39 @@ import { getVersions } from '../helpers.js';
 import { trackCommand } from '../telemetry/track.js';
 
 const SCRAPE_SUBCOMMANDS = new Set(['page', 'site', 'openapi']);
+const ANALYTICS_SUBCOMMANDS = new Set(['stats', 'search', 'feedback', 'conversation']);
+const CONFIG_SUBCOMMANDS = new Set(['set', 'get', 'clear']);
+const CONVERSATION_SUBCOMMANDS = new Set(['list', 'view', 'buckets']);
+const BUCKETS_SUBCOMMANDS = new Set(['list', 'view']);
 
 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];
+  const third = parts[2];
+
   if (first === 'scrape' && second !== undefined && SCRAPE_SUBCOMMANDS.has(second)) {
     return `scrape ${second}`;
   }
+
+  if (first === 'config' && second !== undefined && CONFIG_SUBCOMMANDS.has(second)) {
+    return `config ${second}`;
+  }
+
+  if (first === 'analytics' && second !== undefined && ANALYTICS_SUBCOMMANDS.has(second)) {
+    if (second === 'conversation' && third !== undefined) {
+      if (CONVERSATION_SUBCOMMANDS.has(third)) {
+        const fourth = parts[3];
+        if (third === 'buckets' && fourth !== undefined && BUCKETS_SUBCOMMANDS.has(fourth)) {
+          return `analytics conversation buckets ${fourth}`;
+        }
+        return `analytics conversation ${third}`;
+      }
+    }
+    return `analytics ${second}`;
+  }
+
   return first;
 }
 

package/src/score/client.ts

@@ -0,0 +1,19 @@
+import { authenticatedFetch } from '../authenticatedFetch.js';
+import { API_URL } from '../constants.js';
+import type { ScoreResponse } from './types.js';
+
+export async function getScore(url: string): Promise<ScoreResponse> {
+  const endpoint = new URL(`${API_URL}/api/cli/score`);
+  endpoint.searchParams.set('url', url);
+
+  const res = await authenticatedFetch(endpoint.toString(), {
+    headers: { Accept: 'application/json' },
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new Error(`API error (${res.status}): ${body || res.statusText}`);
+  }
+
+  return res.json() as Promise<ScoreResponse>;
+}

package/src/score/index.tsx

@@ -0,0 +1,104 @@
+import { addLog, ErrorLog, SpinnerLog, removeLastLog } from '@mintlify/previewing';
+import chalk from 'chalk';
+import { Text } from 'ink';
+
+import { terminate } from '../helpers.js';
+import { trackEvent } from '../telemetry/track.js';
+import { getScore } from './client.js';
+import type { Check } from './types.js';
+
+type OutputFormat = 'table' | 'plain' | 'json';
+
+function resolveFormat(argv: { format?: string }): OutputFormat {
+  if (argv.format === 'table' || argv.format === 'plain' || argv.format === 'json')
+    return argv.format;
+  return 'table';
+}
+
+function statusIcon(pass: boolean): string {
+  return pass ? chalk.green('✓') : chalk.red('✗');
+}
+
+function formatCheckName(name: string): string {
+  return name
+    .replace(/([A-Z])/g, ' $1')
+    .replace(/^./, (c) => c.toUpperCase())
+    .trim();
+}
+
+function renderChecks(checks: Check[], indent = 0): string[] {
+  const lines: string[] = [];
+  const pad = '  '.repeat(indent + 1);
+  for (const check of checks) {
+    lines.push(`${pad}${statusIcon(check.pass)}  ${formatCheckName(check.name)}`);
+    if (check.children && check.children.length > 0) {
+      lines.push(...renderChecks(check.children, indent + 1));
+    }
+  }
+  return lines;
+}
+
+function renderPlain(checks: Check[], prefix = ''): string[] {
+  const lines: string[] = [];
+  for (const check of checks) {
+    lines.push(`${prefix}${check.pass ? 'PASS' : 'FAIL'}\t${check.name}`);
+    if (check.children && check.children.length > 0) {
+      lines.push(...renderPlain(check.children, prefix + '  '));
+    }
+  }
+  return lines;
+}
+
+function output(format: OutputFormat, text: string) {
+  if (format === 'table') {
+    addLog(<Text>{text}</Text>);
+  } else {
+    process.stdout.write(text + '\n');
+  }
+}
+
+export const scoreHandler = async (argv: { url: string; format?: string }) => {
+  const format = resolveFormat(argv);
+  try {
+    if (format === 'table') addLog(<SpinnerLog message="Running agent readiness checks..." />);
+    const data = await getScore(argv.url);
+    void trackEvent('cli.score.executed', {
+      url: argv.url,
+      score: data.overallScore,
+      format,
+    });
+    if (format === 'table') removeLastLog();
+
+    if (format === 'json') {
+      output(format, JSON.stringify(data, null, 2));
+      await terminate(0);
+      return;
+    }
+
+    if (format === 'plain') {
+      const lines = [`SCORE\t${data.overallScore}`, ...renderPlain(data.checks)];
+      output(format, lines.join('\n'));
+      await terminate(0);
+      return;
+    }
+
+    const scoreColor =
+      data.overallScore >= 70 ? 'green' : data.overallScore >= 40 ? 'yellow' : 'red';
+    const lines: string[] = [];
+    lines.push(chalk.bold(`\nAgent Readiness Score — ${data.url}\n`));
+    lines.push(`  Score: ${chalk[scoreColor].bold(`${data.overallScore}%`)}\n`);
+    lines.push(chalk.bold('  Checks'));
+    lines.push(...renderChecks(data.checks));
+    output(format, lines.join('\n'));
+    await terminate(0);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'unknown error';
+    if (format === 'table') {
+      removeLastLog();
+      addLog(<ErrorLog message={message} />);
+    } else {
+      process.stderr.write(`Error: ${message}\n`);
+    }
+    await terminate(1);
+  }
+};

package/src/score/types.ts

@@ -0,0 +1,12 @@
+export type Check = {
+  name: string;
+  pass: boolean;
+  metadata?: Record<string, unknown>;
+  children?: Check[];
+};
+
+export type ScoreResponse = {
+  url: string;
+  overallScore: number;
+  checks: Check[];
+};

package/src/telemetry/track.ts

@@ -77,6 +77,25 @@ 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;
+
+  try {
+    const { cli: cliVersion } = getVersions();
+    await captureWithTimeout(event, {
+      ...properties,
+      cli_version: cliVersion,
+      os: os.platform(),
+      arch: os.arch(),
+      node_version: process.version,
+      is_ai_agent: isAI(),
+    });
+  } catch {}
+}
+
 export async function trackTelemetryPreferenceChange(options: { enabled: boolean }): Promise<void> {
   if (process.env.CLI_TEST_MODE === 'true') return;