@mintlify/cli 4.0.1109 → 4.0.1110

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/cli",
-  "version": "4.0.1109",
+  "version": "4.0.1110",
   "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": "f976151a777e02bf8190efa6389757169e8b4ef1"
 }

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/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,98 @@
+import { addLog, ErrorLog, SpinnerLog, removeLastLog } from '@mintlify/previewing';
+import chalk from 'chalk';
+import { Text } from 'ink';
+
+import { terminate } from '../helpers.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);
+    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[];
+};