@mintlify/cli 4.0.1813 → 4.1.1

package/src/resolveFiles.ts

@@ -1,101 +0,0 @@
-import fs from 'node:fs/promises';
-import path from 'node:path';
-
-const GLOB_CHARS = /[*?]/;
-const DOCS_FILE = /\.mdx?$/i;
-const REGEX_SPECIAL = /[.+^${}()|\\[\]]/;
-const SKIPPED_DIRS = new Set(['.git', 'node_modules']);
-
-function toPosix(filePath: string): string {
-  return filePath.split(path.sep).join('/');
-}
-
-function normalizeArg(arg: string): string {
-  return toPosix(arg).replace(/^\.\//, '');
-}
-
-function globToRegExp(pattern: string): RegExp {
-  let source = '';
-  let i = 0;
-  while (i < pattern.length) {
-    const char = pattern[i]!;
-    if (char === '*') {
-      if (pattern[i + 1] === '*') {
-        if (pattern[i + 2] === '/') {
-          source += '(?:[^/]+/)*';
-          i += 3;
-        } else {
-          source += '.*';
-          i += 2;
-        }
-      } else {
-        source += '[^/]*';
-        i += 1;
-      }
-    } else if (char === '?') {
-      source += '[^/]';
-      i += 1;
-    } else {
-      source += REGEX_SPECIAL.test(char) ? `\\${char}` : char;
-      i += 1;
-    }
-  }
-  return new RegExp(`^${source}$`);
-}
-
-async function isFile(filePath: string): Promise<boolean> {
-  try {
-    return (await fs.stat(filePath)).isFile();
-  } catch {
-    return false;
-  }
-}
-
-async function walk(baseDir: string, dir = ''): Promise<string[]> {
-  const entries = await fs.readdir(path.join(baseDir, dir), { withFileTypes: true });
-  const files: string[] = [];
-  for (const entry of entries) {
-    if (SKIPPED_DIRS.has(entry.name)) continue;
-    const rel = dir ? `${dir}/${entry.name}` : entry.name;
-    if (entry.isDirectory()) {
-      files.push(...(await walk(baseDir, rel)));
-    } else {
-      files.push(rel);
-    }
-  }
-  return files;
-}
-
-export class NoMatchingFilesError extends Error {}
-
-export async function resolveExplicitFiles(baseDir: string, args: string[]): Promise<string[]> {
-  let allFiles: string[] | null = null;
-  const matched: string[] = [];
-  const unmatched: string[] = [];
-
-  for (const arg of args) {
-    const pattern = normalizeArg(arg);
-    if (GLOB_CHARS.test(pattern)) {
-      allFiles = allFiles ?? (await walk(baseDir));
-      const regex = globToRegExp(pattern);
-      const hits = allFiles.filter((file) => DOCS_FILE.test(file) && regex.test(file)).sort();
-      if (hits.length === 0) {
-        unmatched.push(arg);
-      } else {
-        matched.push(...hits);
-      }
-    } else if (await isFile(path.join(baseDir, pattern))) {
-      matched.push(pattern);
-    } else {
-      unmatched.push(arg);
-    }
-  }
-
-  if (unmatched.length > 0) {
-    throw new NoMatchingFilesError(
-      `No matching files for: ${unmatched.join(', ')} (globs match .md and .mdx files)`
-    );
-  }
-
-  return [...new Set(matched)];
-}

package/src/score/client.ts

@@ -1,36 +0,0 @@
-import { authenticatedFetch } from '../authenticatedFetch.js';
-import { API_URL } from '../constants.js';
-import type { ResolveResult, ScoreResponse } from './types.js';
-
-export async function resolveScoreForUrl(url: string): Promise<ResolveResult> {
-  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.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}`);
-  }
-
-  return res.json() as Promise<ScoreResponse>;
-}

package/src/score/index.tsx

@@ -1,205 +0,0 @@
-import { addLog, ErrorLog, SpinnerLog, removeLastLog } from '@mintlify/previewing';
-import chalk from 'chalk';
-import { Text } from 'ink';
-
-import { getConfigValue } from '../config.js';
-import { terminate } from '../helpers.js';
-import { getAccessToken } from '../keyring.js';
-import { getCliSubdomains } from '../status.js';
-import { trackEvent } from '../telemetry/track.js';
-import { fetchScoreBySlug, resolveScoreForUrl } from './client.js';
-import type { Check, CliCheckStatus, 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;
-  return 'table';
-}
-
-function statusIcon(status: CliCheckStatus): string {
-  switch (status) {
-    case 'pass':
-      return chalk.green('✓');
-    case 'warn':
-      return chalk.yellow('⚠');
-    case 'skip':
-      return chalk.dim('○');
-    case 'fail':
-    case 'error':
-      return chalk.red('✗');
-    default: {
-      const _exhaustive: never = status;
-      void _exhaustive;
-      return chalk.dim('?');
-    }
-  }
-}
-
-function plainStatusLabel(status: CliCheckStatus): string {
-  return status.toUpperCase();
-}
-
-function formatCheckName(name: string): string {
-  return name
-    .replace(/[-_]+/g, ' ')
-    .replace(/([a-z])([A-Z])/g, '$1 $2')
-    .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.status)}  ${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}${plainStatusLabel(check.status)}\t${check.name}`);
-    if (check.children && check.children.length > 0) {
-      lines.push(...renderPlain(check.children, prefix + '  '));
-    }
-  }
-  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>);
-  } else {
-    process.stdout.write(text + '\n');
-  }
-}
-
-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`);
-}
-
-async function resolveDefaultSubdomain(): Promise<string | undefined> {
-  const fromConfig = getConfigValue('subdomain');
-  if (fromConfig) return fromConfig;
-  const accessToken = await getAccessToken();
-  if (!accessToken) return undefined;
-  const subdomains = await getCliSubdomains(accessToken);
-  return subdomains[0];
-}
-
-export const scoreHandler = async (argv: { url?: string; format?: string }) => {
-  const format = resolveFormat(argv);
-  try {
-    let url = argv.url;
-    if (!url) {
-      const subdomain = await resolveDefaultSubdomain();
-      if (!subdomain) {
-        throw new Error(
-          'No URL provided and no default subdomain set. Run `mint login` to set one, or pass a URL: `mint score <url>`.'
-        );
-      }
-      url = `${subdomain}.mintlify.site`;
-    }
-    if (format === 'table') addLog(<SpinnerLog message="Checking agent readiness..." />);
-    const resolved = await resolveScoreForUrl(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,
-      score: final.overallScore,
-      format,
-      status: resolved.status,
-    });
-
-    if (format === 'json') {
-      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'));
-    } else {
-      output(format, renderTable(final));
-    }
-
-    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

@@ -1,15 +0,0 @@
-// These types are defined in `@mintlify/models/src/types/cliScoreResponse.ts`.
-// The server (mintlify/server) is the source of truth for this contract — it
-// implements the response shape in `agentReadinessScore.controller.ts` →
-// `getCliSiteScore`. Do not redefine the shape locally; update the shared
-// package (and bump the dependency in both repos) if you need to change it.
-export type {
-  CliCheckStatus,
-  CliGrade,
-  CliScoreCheck as Check,
-  CliScorePendingResponse,
-  CliScoreResolveResponse as ResolveResult,
-  CliScoreResolveStatus as ResolveStatus,
-  CliScoreResponse as ScoreResponse,
-  CliScoreResponseStatus,
-} from '@mintlify/models';

package/src/signup.tsx

@@ -1,172 +0,0 @@
-import { input } from '@inquirer/prompts';
-import { addLog, addLogs, ErrorLog, SuccessLog } from '@mintlify/previewing';
-import { Box, Text } from 'ink';
-import {
-  calculatePKCECodeChallenge,
-  randomNonce,
-  randomPKCECodeVerifier,
-  randomState,
-} from 'openid-client';
-
-import { isCI } from './agent.js';
-import { startCallbackServer } from './callbackServer.js';
-import { clearConfigValue, hasShownPublishPrompt, markPublishPromptShown } from './config.js';
-import { API_URL, TOKEN_ENDPOINT } from './constants.js';
-import { CMD_EXEC_PATH, isAI } from './helpers.js';
-import { getEmailFromIdToken } from './idToken.js';
-import { getAccessToken, storeCredentials } from './keyring.js';
-import type { TokenResponse } from './login.js';
-
-export interface SignupOptions {
-  firstName?: string;
-  lastName?: string;
-  company?: string;
-  email?: string;
-}
-
-export const AUTH_MD_URL = 'https://mintlify.com/auth.md';
-
-const sendAIUsageMessage = () => {
-  addLogs(
-    <Text>Agent Detected - sending AI friendly prompt</Text>,
-    <Text>{'<mint-cli-instructions>'}</Text>,
-    <Text>
-      Could not fetch the agent signup guide. Read {AUTH_MD_URL} directly, or create a site without
-      an account by running `mint deploy --subdomain [subdomain]` from the documentation directory
-      and following the instructions it prints.
-    </Text>,
-    <Text>
-      To hand the site to the user, ask for their email (never invent one) and run `mint claim
-      --email [email]`.
-    </Text>,
-    <Text>{'</mint-cli-instructions>'}</Text>
-  );
-};
-
-export const sendPublishPrompt = async () => {
-  if (
-    !isAI() ||
-    isCI() ||
-    process.env.MINTLIFY_SESSION_TOKEN ||
-    (await getAccessToken().catch(() => undefined))
-  ) {
-    return;
-  }
-  if (hasShownPublishPrompt(CMD_EXEC_PATH)) {
-    addLog(<Text>Not published yet. Run `mint signup` or `mint login` to publish.</Text>);
-    return;
-  }
-  addLogs(
-    <Text>{'<mint-cli-instructions>'}</Text>,
-    <Text>Ready to publish? The Starter plan is free, no credit card needed.</Text>,
-    <Text>
-      Offer to create the user's Mintlify account: run `mint signup` and follow the instructions it
-      prints.
-    </Text>,
-    <Text>Have an account: `mint login`.</Text>,
-    <Text>
-      Your site will then be live at https://[subdomain].mintlify.site (`mint status` shows the
-      exact URL).
-    </Text>,
-    <Text>{'</mint-cli-instructions>'}</Text>
-  );
-  await markPublishPromptShown(CMD_EXEC_PATH).catch(() => undefined);
-};
-
-// Agents sign up through auth.md, so give them that guide instead of the email flow.
-const sendAuthMd = async () => {
-  try {
-    const res = await fetch(AUTH_MD_URL, { signal: AbortSignal.timeout(30_000) });
-    if (!res.ok) throw new Error(`auth.md returned ${res.status}`);
-    process.stdout.write(`${await res.text()}\n`);
-  } catch {
-    sendAIUsageMessage();
-  }
-};
-
-export async function signup(options: SignupOptions = {}): Promise<void> {
-  if (isAI()) {
-    await sendAuthMd();
-    return;
-  }
-
-  const firstName = options.firstName ?? (await input({ message: 'First name' }));
-  const lastName = options.lastName ?? (await input({ message: 'Last name' }));
-  const company = options.company ?? (await input({ message: 'Company name' }));
-  const email = options.email ?? (await input({ message: 'Email' }));
-
-  const codeVerifier = randomPKCECodeVerifier();
-  const codeChallenge = await calculatePKCECodeChallenge(codeVerifier);
-  const nonce = randomNonce();
-  const clientState = randomState();
-  const state = Buffer.from(JSON.stringify({ nonce, clientState })).toString('base64url');
-
-  const { codePromise, close: closeServer } = await startCallbackServer();
-  codePromise.catch(() => {});
-
-  try {
-    const res = await fetch(`${API_URL}/api/cli-onboarding/signup`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ firstName, lastName, company, email, state, codeChallenge }),
-    });
-
-    if (!res.ok) {
-      const body = await res.json().catch(() => ({}));
-      closeServer();
-      addLog(<ErrorLog message={`signup failed: ${body.error ?? 'unknown error'}`} />);
-      return;
-    }
-  } catch {
-    closeServer();
-    addLog(<ErrorLog message="signup failed: could not reach the server" />);
-    return;
-  }
-
-  addLog(
-    <Box flexDirection="column" gap={1} paddingY={1}>
-      <Text bold>
-        <Text color="green">◆ </Text>Check your email to verify your account
-      </Text>
-      <Box flexDirection="column" paddingLeft={3} gap={1}>
-        <Text dimColor>We sent a verification link to {email}. Click it to continue.</Text>
-      </Box>
-    </Box>
-  );
-
-  let code: string;
-  try {
-    code = await codePromise;
-  } catch {
-    addLog(<ErrorLog message="signup cancelled" />);
-    return;
-  }
-
-  const res = await fetch(TOKEN_ENDPOINT, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      grant_type: 'authorization_code',
-      code,
-      code_verifier: codeVerifier,
-    }),
-  });
-
-  const body = await res.json().catch(() => ({}));
-
-  if (!res.ok) {
-    const reason = body.error_message ?? body.error ?? 'unknown error';
-    addLog(<ErrorLog message={`signup failed: ${reason}`} />);
-    return;
-  }
-
-  const token = body as TokenResponse;
-  await storeCredentials(
-    token.access_token,
-    token.refresh_token,
-    getEmailFromIdToken(token.id_token) ?? email
-  );
-  await clearConfigValue('subdomain').catch(() => undefined);
-  addLog(<SuccessLog message="account created and logged in successfully" />);
-  addLog(<Text>Continue in the browser tab where you verified your email to connect GitHub.</Text>);
-}

package/src/start.ts

@@ -1,27 +0,0 @@
-#!/usr/bin/env node
-import { cli } from './cli.js';
-import { shutdownPostHog } from './telemetry/client.js';
-
-const packageName = process.env.MINTLIFY_PACKAGE_NAME ?? 'mint';
-
-cli({ packageName }).catch((err: unknown) => {
-  console.error(err instanceof Error ? err.message : err);
-  process.exit(1);
-});
-
-async function shutdown(exitCode: number): Promise<never> {
-  await shutdownPostHog();
-  process.exit(exitCode);
-}
-
-process.once('beforeExit', async () => {
-  try {
-    await shutdownPostHog();
-  } catch {}
-});
-process.on('SIGINT', () => {
-  void shutdown(130);
-});
-process.on('SIGTERM', () => {
-  void shutdown(143);
-});

package/src/status.tsx

@@ -1,129 +0,0 @@
-import { addLog, ErrorLog } from '@mintlify/previewing';
-import { Box, Text } from 'ink';
-import { z } from 'zod';
-
-import { authenticatedFetch } from './authenticatedFetch.js';
-import { getConfigValue, setConfigValue } from './config.js';
-import { API_URL } from './constants.js';
-import { getCliVersion } from './helpers.js';
-import { getAccessToken } from './keyring.js';
-
-const StatusResponseSchema = z.object({
-  user: z.object({ email: z.string() }),
-  org: z.object({ name: z.string() }),
-  subdomains: z.array(z.string()).default([]),
-});
-
-export async function getCliStatus(
-  accessToken: string
-): Promise<z.infer<typeof StatusResponseSchema> | null> {
-  try {
-    const res = await fetch(`${API_URL}/api/cli/status`, {
-      headers: { Authorization: `Bearer ${accessToken}` },
-    });
-    if (!res.ok) return null;
-    const json = await res.json().catch(() => null);
-    const parsed = StatusResponseSchema.safeParse(json);
-    return parsed.success ? parsed.data : null;
-  } catch {
-    return null;
-  }
-}
-
-export type CliStatusResult =
-  | { ok: true; status: z.infer<typeof StatusResponseSchema> }
-  | { ok: false; reason: 'unauthenticated' | 'unreachable' | 'invalid'; detail?: string };
-
-/**
- * Like getCliStatus, but refreshes an expired session and says why it failed, so commands can
- * tell "log in again" apart from "the server is down" and from "not allowed".
- */
-export async function fetchCliStatus(signal?: AbortSignal): Promise<CliStatusResult> {
-  let res: Response;
-  try {
-    res = await authenticatedFetch(`${API_URL}/api/cli/status`, { signal });
-  } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
-    if (/not authenticated/i.test(detail)) return { ok: false, reason: 'unauthenticated' };
-    return { ok: false, reason: 'unreachable', detail };
-  }
-  if (res.status === 401 || res.status === 403) return { ok: false, reason: 'unauthenticated' };
-  if (!res.ok) return { ok: false, reason: 'unreachable', detail: `HTTP ${res.status}` };
-  const parsed = StatusResponseSchema.safeParse(await res.json().catch(() => null));
-  if (!parsed.success) return { ok: false, reason: 'invalid' };
-  return { ok: true, status: parsed.data };
-}
-
-export async function getCliSubdomains(accessToken: string): Promise<string[]> {
-  const status = await getCliStatus(accessToken);
-  return status?.subdomains ?? [];
-}
-
-export async function status(): Promise<void> {
-  const accessToken =
-    (await getAccessToken().catch(() => null)) ?? process.env.MINTLIFY_SESSION_TOKEN;
-
-  if (!accessToken) {
-    addLog(<ErrorLog message="not logged in. Run `mint login` to authenticate." />);
-    return;
-  }
-
-  try {
-    const res = await authenticatedFetch(`${API_URL}/api/cli/status`);
-
-    if (!res.ok) {
-      addLog(<ErrorLog message="not logged in. Run `mint login` to authenticate." />);
-      return;
-    }
-
-    const json = await res.json().catch(() => null);
-    const parsed = StatusResponseSchema.safeParse(json);
-
-    if (!parsed.success) {
-      addLog(<ErrorLog message="unexpected response from server. please try again." />);
-      return;
-    }
-
-    const { user, org, subdomains } = parsed.data;
-    const version = getCliVersion();
-
-    const cached = getConfigValue('subdomain');
-    const subdomain = (cached && subdomains.includes(cached) ? cached : subdomains[0]) ?? null;
-    if (subdomain && subdomain !== cached)
-      await setConfigValue('subdomain', subdomain).catch(() => undefined);
-    addLog(
-      <Box flexDirection="column" paddingY={1}>
-        {version && (
-          <Box>
-            <Box minWidth={16}>
-              <Text dimColor>Version</Text>
-            </Box>
-            <Text>{version}</Text>
-          </Box>
-        )}
-        <Box>
-          <Box minWidth={16}>
-            <Text dimColor>Email</Text>
-          </Box>
-          <Text>{user.email}</Text>
-        </Box>
-        <Box>
-          <Box minWidth={16}>
-            <Text dimColor>Organization</Text>
-          </Box>
-          <Text>{org.name}</Text>
-        </Box>
-        {subdomain && (
-          <Box>
-            <Box minWidth={16}>
-              <Text dimColor>Subdomain</Text>
-            </Box>
-            <Text>{subdomain}</Text>
-          </Box>
-        )}
-      </Box>
-    );
-  } catch (e) {
-    addLog(<ErrorLog message="unexpected response from server. please try again." />);
-  }
-}