@mintlify/cli 4.0.1123 → 4.0.1124

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/cli",
-  "version": "4.0.1123",
+  "version": "4.0.1124",
   "description": "The Mintlify CLI",
   "engines": {
     "node": ">=18.0.0"
@@ -93,5 +93,5 @@
     "vitest": "2.1.9",
     "vitest-mock-process": "1.0.4"
   },
-  "gitHead": "511d45e72c42590140bd4568456f75bc65658752"
+  "gitHead": "8bfaa040d399554049b90d0780deebcfc26a624c"
 }

package/src/score/client.ts

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

package/src/score/index.tsx

@@ -4,11 +4,14 @@ 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';
+import { fetchScoreBySlug, resolveScoreForUrl } from './client.js';
+import type { Check, ScoreResponse } from './types.js';
 
 type OutputFormat = 'table' | 'plain' | 'json';
 
+const POLL_INTERVAL_MS = 3_000;
+const POLL_TIMEOUT_MS = 120_000;
+
 function resolveFormat(argv: { format?: string }): OutputFormat {
   if (argv.format === 'table' || argv.format === 'plain' || argv.format === 'json')
     return argv.format;
@@ -49,6 +52,21 @@ function renderPlain(checks: Check[], prefix = ''): string[] {
   return lines;
 }
 
+function renderTable(score: ScoreResponse, opts?: { stale?: boolean }): string {
+  const scoreColor =
+    score.overallScore >= 70 ? 'green' : score.overallScore >= 40 ? 'yellow' : 'red';
+  const header = opts?.stale
+    ? chalk.bold(`\nAgent Readiness Score — ${score.canonicalUrl}`) +
+      chalk.dim(` (last run ${new Date(score.computedAt).toLocaleString()})\n`)
+    : chalk.bold(`\nAgent Readiness Score — ${score.canonicalUrl}\n`);
+
+  const lines: string[] = [header];
+  lines.push(`  Score: ${chalk[scoreColor].bold(`${score.overallScore}%`)}\n`);
+  lines.push(chalk.bold('  Checks'));
+  lines.push(...renderChecks(score.checks));
+  return lines.join('\n');
+}
+
 function output(format: OutputFormat, text: string) {
   if (format === 'table') {
     addLog(<Text>{text}</Text>);
@@ -57,39 +75,80 @@ function output(format: OutputFormat, text: string) {
   }
 }
 
+async function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function pollForScore(
+  slug: string,
+  afterIso: string | null,
+  onAttempt?: () => void
+): Promise<ScoreResponse> {
+  const deadline = Date.now() + POLL_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    await sleep(POLL_INTERVAL_MS);
+    onAttempt?.();
+    const score = await fetchScoreBySlug(slug);
+    if (!score) continue;
+    if (afterIso === null) return score;
+    if (new Date(score.computedAt).getTime() > new Date(afterIso).getTime()) return score;
+  }
+  throw new Error(`Score did not complete within ${POLL_TIMEOUT_MS / 1000}s`);
+}
+
 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') addLog(<SpinnerLog message="Checking agent readiness..." />);
+    const resolved = await resolveScoreForUrl(argv.url);
+
+    let final: ScoreResponse;
+
+    if (resolved.status === 'ready') {
+      const score = await fetchScoreBySlug(resolved.slug);
+      if (format === 'table') removeLastLog();
+      if (!score) throw new Error('Score was unexpectedly unavailable');
+      final = score;
+    } else if (resolved.status === 'stale_refresh_queued') {
+      const stale = await fetchScoreBySlug(resolved.slug);
+      if (format === 'table') removeLastLog();
+      if (!stale) throw new Error('Stale score was unexpectedly unavailable');
+
+      if (format === 'table') {
+        output('table', renderTable(stale, { stale: true }));
+        addLog(<SpinnerLog message="Refreshing score in the background..." />);
+      } else {
+        process.stderr.write('Refreshing score in the background...\n');
+      }
+      final = await pollForScore(resolved.slug, stale.computedAt);
+      if (format === 'table') removeLastLog();
+    } else {
+      if (format === 'table') {
+        removeLastLog();
+        addLog(<SpinnerLog message="Queued a new scoring run. Waiting for first result..." />);
+      } else {
+        process.stderr.write('Queued a new scoring run. Waiting for first result...\n');
+      }
+      final = await pollForScore(resolved.slug, null);
+      if (format === 'table') removeLastLog();
+    }
+
     void trackEvent('cli.score.executed', {
       url: argv.url,
-      score: data.overallScore,
+      score: final.overallScore,
       format,
+      status: resolved.status,
     });
-    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, JSON.stringify(final, null, 2));
+    } else if (format === 'plain') {
+      const lines = [`SCORE\t${final.overallScore}`, ...renderPlain(final.checks)];
       output(format, lines.join('\n'));
-      await terminate(0);
-      return;
+    } else {
+      output(format, renderTable(final));
     }
 
-    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';

package/src/score/types.ts

@@ -5,8 +5,22 @@ export type Check = {
   children?: Check[];
 };
 
+export type ResolveStatus = 'ready' | 'stale_refresh_queued' | 'queued';
+
+export type ResolveResult = {
+  canonicalUrl: string;
+  slug: string;
+  status: ResolveStatus;
+  trackedSiteId: string;
+};
+
 export type ScoreResponse = {
-  url: string;
-  overallScore: number;
+  canonicalUrl: string;
   checks: Check[];
+  computedAt: string;
+  name: string;
+  overallScore: number;
+  passedChecks: number;
+  slug: string;
+  totalChecks: number;
 };