@mintlify/cli 4.0.1122 → 4.0.1124

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/cli",
-  "version": "4.0.1122",
+  "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": "794b8b7473bf08e20dea96efe72921c44a52b194"
+  "gitHead": "8bfaa040d399554049b90d0780deebcfc26a624c"
 }

package/src/cli.tsx

@@ -44,7 +44,6 @@ import { scoreHandler } from './score/index.js';
 import { status, getCliSubdomains } from './status.js';
 import { trackTelemetryPreferenceChange } from './telemetry/track.js';
 import { update } from './update.js';
-import { addWorkflow } from './workflow.js';
 
 export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
   const telemetryMiddleware = createTelemetryMiddleware();
@@ -554,22 +553,6 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
           }
         }
       )
-      .command(
-        'workflow',
-        'Add a workflow to your documentation repository',
-        () => undefined,
-        async () => {
-          try {
-            await addWorkflow();
-            await terminate(0);
-          } catch (error) {
-            addLog(
-              <ErrorLog message={error instanceof Error ? error.message : 'error occurred'} />
-            );
-            await terminate(1);
-          }
-        }
-      )
       .command('analytics', 'View analytics for your documentation', analyticsBuilder)
       .command(
         'score <url>',

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;
 };

package/__test__/workflow.test.ts

@@ -1,320 +0,0 @@
-import * as previewing from '@mintlify/previewing';
-import fse from 'fs-extra';
-import path from 'path';
-
-import { addWorkflow, slugify, buildFrontmatter, isValidCron } from '../src/workflow.js';
-
-const FAKE_PROJECT = '/fake/project';
-const WORKFLOWS_DIR = path.join(FAKE_PROJECT, '.mintlify', 'workflows');
-
-vi.mock('@inquirer/prompts', () => ({
-  select: vi.fn(),
-  input: vi.fn(),
-  editor: vi.fn(),
-}));
-
-vi.mock('@mintlify/previewing', () => ({
-  addLog: vi.fn(),
-  addLogs: vi.fn(),
-  SuccessLog: vi.fn(),
-}));
-
-vi.mock('fs-extra', () => ({
-  default: {
-    pathExists: vi.fn(),
-    ensureDir: vi.fn().mockResolvedValue(undefined),
-    writeFile: vi.fn().mockResolvedValue(undefined),
-  },
-}));
-
-vi.mock('../src/helpers.js', () => ({
-  CMD_EXEC_PATH: '/fake/project',
-  isAI: () =>
-    !process.stdin.isTTY || process.env.CLAUDECODE === '1' || process.env.TERM_PROGRAM === 'claude',
-}));
-
-const addLogSpy = vi.mocked(previewing.addLog);
-
-describe('slugify', () => {
-  it('converts spaces to hyphens', () => {
-    expect(slugify('Update changelog')).toBe('update-changelog');
-  });
-
-  it('replaces special characters with hyphens', () => {
-    expect(slugify('My Workflow!@#$%')).toBe('my-workflow');
-  });
-
-  it('replaces slashes with hyphens like the dashboard', () => {
-    expect(slugify('a/b')).toBe('a-b');
-  });
-
-  it('collapses multiple hyphens', () => {
-    expect(slugify('a   b---c')).toBe('a-b-c');
-  });
-
-  it('trims leading and trailing hyphens', () => {
-    expect(slugify('  --hello--  ')).toBe('hello');
-  });
-
-  it('lowercases the result', () => {
-    expect(slugify('UPPER CASE')).toBe('upper-case');
-  });
-
-  it('handles single word', () => {
-    expect(slugify('deploy')).toBe('deploy');
-  });
-});
-
-describe('isValidCron', () => {
-  it('accepts standard 5-field expressions', () => {
-    expect(isValidCron('0 9 * * 1')).toBe(true);
-    expect(isValidCron('*/15 * * * *')).toBe(true);
-    expect(isValidCron('0 0 1 1 *')).toBe(true);
-  });
-
-  it('accepts ranges and lists', () => {
-    expect(isValidCron('0 9-17 * * 1-5')).toBe(true);
-    expect(isValidCron('0,30 * * * *')).toBe(true);
-  });
-
-  it('rejects invalid expressions', () => {
-    expect(isValidCron('0 xd f gasf')).toBe(false);
-    expect(isValidCron('not a cron')).toBe(false);
-    expect(isValidCron('')).toBe(false);
-  });
-
-  it('rejects wrong number of fields', () => {
-    expect(isValidCron('* * *')).toBe(false);
-    expect(isValidCron('* * * * * *')).toBe(false);
-  });
-});
-
-describe('buildFrontmatter', () => {
-  it('builds cron trigger frontmatter', () => {
-    const result = buildFrontmatter({
-      name: 'Update changelog',
-      triggerType: 'cron',
-      cronExpression: '0 9 * * 1',
-      automerge: false,
-    });
-    expect(result).toBe('---\nname: "Update changelog"\non:\n  cron: "0 9 * * 1"\n---');
-  });
-
-  it('builds push trigger frontmatter with repos', () => {
-    const result = buildFrontmatter({
-      name: 'Deploy docs',
-      triggerType: 'push',
-      triggerRepos: ['org/docs', 'org/api'],
-      automerge: false,
-    });
-    expect(result).toBe(
-      '---\nname: "Deploy docs"\non:\n  push:\n    - repo: "org/docs"\n    - repo: "org/api"\n---'
-    );
-  });
-
-  it('builds push trigger with no repos', () => {
-    const result = buildFrontmatter({
-      name: 'Deploy',
-      triggerType: 'push',
-      automerge: false,
-    });
-    expect(result).toBe('---\nname: "Deploy"\non:\n  push:\n---');
-  });
-
-  it('includes context repos', () => {
-    const result = buildFrontmatter({
-      name: 'Test',
-      triggerType: 'cron',
-      cronExpression: '0 9 * * 1',
-      contextRepos: ['org/repo1', 'org/repo2'],
-      automerge: false,
-    });
-    expect(result).toContain('context:\n  - repo: "org/repo1"\n  - repo: "org/repo2"');
-  });
-
-  it('includes automerge only when true', () => {
-    const result = buildFrontmatter({
-      name: 'Test',
-      triggerType: 'cron',
-      cronExpression: '0 9 * * 1',
-      automerge: true,
-    });
-    expect(result).toContain('automerge: true');
-  });
-
-  it('omits automerge when false', () => {
-    const result = buildFrontmatter({
-      name: 'Test',
-      triggerType: 'cron',
-      cronExpression: '0 9 * * 1',
-      automerge: false,
-    });
-    expect(result).not.toContain('automerge');
-  });
-
-  it('escapes quotes in name', () => {
-    const result = buildFrontmatter({
-      name: 'My "Test" Workflow',
-      triggerType: 'cron',
-      cronExpression: '0 9 * * 1',
-      automerge: false,
-    });
-    expect(result).toContain('name: "My \\"Test\\" Workflow"');
-  });
-});
-
-describe('addWorkflow', () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it('throws when docs.json does not exist', async () => {
-    vi.mocked(fse.pathExists).mockResolvedValue(false as never);
-
-    await expect(addWorkflow()).rejects.toThrow(
-      'docs.json not found in the current directory. Please run this command from your docs repository root.'
-    );
-  });
-
-  it('outputs AI usage message when not interactive', async () => {
-    vi.mocked(fse.pathExists).mockResolvedValue(true as never);
-    const originalIsTTY = process.stdin.isTTY;
-    process.stdin.isTTY = false;
-
-    await addWorkflow();
-
-    expect(previewing.addLogs).toHaveBeenCalled();
-
-    process.stdin.isTTY = originalIsTTY;
-  });
-
-  it('throws when workflow name has no alphanumeric characters', async () => {
-    vi.mocked(fse.pathExists).mockResolvedValue(true as never);
-    const originalIsTTY = process.stdin.isTTY;
-    const originalClaudeCode = process.env.CLAUDECODE;
-    process.stdin.isTTY = true;
-    delete process.env.CLAUDECODE;
-
-    const { input } = await import('@inquirer/prompts');
-    vi.mocked(input).mockResolvedValueOnce('!!!');
-
-    await expect(addWorkflow()).rejects.toThrow(
-      'Workflow name must contain at least one alphanumeric character.'
-    );
-
-    process.stdin.isTTY = originalIsTTY;
-    if (originalClaudeCode === undefined) {
-      delete process.env.CLAUDECODE;
-    } else {
-      process.env.CLAUDECODE = originalClaudeCode;
-    }
-  });
-
-  it('throws when workflow file already exists', async () => {
-    // pathExists returns true for both docs.json and the workflow file
-    vi.mocked(fse.pathExists).mockResolvedValue(true as never);
-    const originalIsTTY = process.stdin.isTTY;
-    const originalClaudeCode = process.env.CLAUDECODE;
-    process.stdin.isTTY = true;
-    delete process.env.CLAUDECODE;
-
-    const { input, select, editor } = await import('@inquirer/prompts');
-    vi.mocked(input)
-      .mockResolvedValueOnce('My Workflow') // workflow name
-      .mockResolvedValueOnce('0 9 * * 1') // cron expression
-      .mockResolvedValueOnce(''); // context repos
-    vi.mocked(select)
-      .mockResolvedValueOnce('cron') // trigger type
-      .mockResolvedValueOnce('no'); // automerge
-    vi.mocked(editor).mockResolvedValueOnce('Do the thing');
-
-    const expectedRelative = path.join('.mintlify', 'workflows', 'my-workflow.md');
-    await expect(addWorkflow()).rejects.toThrow(
-      `A workflow already exists at ${expectedRelative}. Please choose a different name or delete the existing file.`
-    );
-    expect(fse.writeFile).not.toHaveBeenCalled();
-
-    process.stdin.isTTY = originalIsTTY;
-    if (originalClaudeCode === undefined) {
-      delete process.env.CLAUDECODE;
-    } else {
-      process.env.CLAUDECODE = originalClaudeCode;
-    }
-  });
-
-  it('creates cron workflow file with correct content', async () => {
-    // true for docs.json, false for workflow file existence check
-    vi.mocked(fse.pathExists)
-      .mockResolvedValueOnce(true as never)
-      .mockResolvedValueOnce(false as never);
-    const originalIsTTY = process.stdin.isTTY;
-    const originalClaudeCode = process.env.CLAUDECODE;
-    process.stdin.isTTY = true;
-    delete process.env.CLAUDECODE;
-
-    const { input, select, editor } = await import('@inquirer/prompts');
-    vi.mocked(input)
-      .mockResolvedValueOnce('My Test Workflow') // workflow name
-      .mockResolvedValueOnce('0 9 * * 1') // cron expression
-      .mockResolvedValueOnce(''); // context repos
-    vi.mocked(select)
-      .mockResolvedValueOnce('cron') // trigger type
-      .mockResolvedValueOnce('no'); // automerge
-    vi.mocked(editor).mockResolvedValueOnce('Do the thing');
-
-    await addWorkflow();
-
-    expect(fse.ensureDir).toHaveBeenCalledWith(WORKFLOWS_DIR);
-    expect(fse.writeFile).toHaveBeenCalledWith(
-      path.join(WORKFLOWS_DIR, 'my-test-workflow.md'),
-      '---\nname: "My Test Workflow"\non:\n  cron: "0 9 * * 1"\n---\n\nDo the thing\n'
-    );
-    const expectedRelative = path.join('.mintlify', 'workflows', 'my-test-workflow.md');
-    expect(addLogSpy).toHaveBeenCalledWith(
-      expect.objectContaining({
-        props: { message: `Workflow created at ${expectedRelative}` },
-      })
-    );
-
-    process.stdin.isTTY = originalIsTTY;
-    if (originalClaudeCode === undefined) {
-      delete process.env.CLAUDECODE;
-    } else {
-      process.env.CLAUDECODE = originalClaudeCode;
-    }
-  });
-
-  it('creates push trigger workflow with automerge and context', async () => {
-    vi.mocked(fse.pathExists)
-      .mockResolvedValueOnce(true as never)
-      .mockResolvedValueOnce(false as never);
-    const originalIsTTY = process.stdin.isTTY;
-    const originalClaudeCode = process.env.CLAUDECODE;
-    process.stdin.isTTY = true;
-    delete process.env.CLAUDECODE;
-
-    const { input, select, editor } = await import('@inquirer/prompts');
-    vi.mocked(input)
-      .mockResolvedValueOnce('Deploy Docs') // workflow name
-      .mockResolvedValueOnce('org/docs') // trigger repos
-      .mockResolvedValueOnce('org/server'); // context repos
-    vi.mocked(select)
-      .mockResolvedValueOnce('push') // trigger type
-      .mockResolvedValueOnce('yes'); // automerge
-    vi.mocked(editor).mockResolvedValueOnce('Deploy the docs');
-
-    await addWorkflow();
-
-    expect(fse.writeFile).toHaveBeenCalledWith(
-      path.join(WORKFLOWS_DIR, 'deploy-docs.md'),
-      '---\nname: "Deploy Docs"\non:\n  push:\n    - repo: "org/docs"\ncontext:\n  - repo: "org/server"\nautomerge: true\n---\n\nDeploy the docs\n'
-    );
-
-    process.stdin.isTTY = originalIsTTY;
-    if (originalClaudeCode === undefined) {
-      delete process.env.CLAUDECODE;
-    } else {
-      process.env.CLAUDECODE = originalClaudeCode;
-    }
-  });
-});