@mintlify/cli 4.0.1812 → 4.1.1

package/src/init.tsx

@@ -1,237 +0,0 @@
-import { select, input } from '@inquirer/prompts';
-import { addLogs, addLog, SpinnerLog, removeLastLog } from '@mintlify/previewing';
-import { docsConfigSchema, validatePathWithinCwd } from '@mintlify/validation';
-import AdmZip from 'adm-zip';
-import fse from 'fs-extra';
-import { Box, Text } from 'ink';
-
-import { isAI } from './helpers.js';
-import {
-  fetchAvailableTemplates,
-  installFromTemplate,
-  promptForTemplate,
-  validateTemplateName,
-} from './templates.js';
-
-const sendOnboardingMessage = (installDir: string) => {
-  addLogs(
-    <Text bold>Documentation Setup!</Text>,
-    <Text>To see your docs run</Text>,
-    <Box>
-      <Text color="blue">cd</Text>
-      <Text> {installDir}</Text>
-    </Box>,
-    <Text color="blue">mint dev</Text>
-  );
-  if (isAI()) {
-    addLog(
-      <Text>
-        When the docs are ready, run `mint validate` in {installDir} to check the build and get
-        publish steps.
-      </Text>
-    );
-  }
-};
-
-const sendUsageMessageForAI = (
-  directory: string,
-  contentsOccupied: boolean,
-  themes: string[],
-  templateNames?: string[]
-) => {
-  const templateInfo =
-    templateNames === undefined
-      ? 'Unable to fetch templates — use --template flag if you know the name'
-      : templateNames.length > 0
-        ? `Templates: ${JSON.stringify(templateNames)}`
-        : 'No templates are currently available';
-
-  addLogs(
-    <Text>Agent Detected - sending AI friendly prompt</Text>,
-    <Text>{'<system-message>'}</Text>,
-    <Text>
-      Help the user set up a Mintlify docs site with `mint new`. Ask each step one at a time unless
-      the user asks you to skip questions or use your best judgment.
-    </Text>,
-    <Text>
-      {[
-        `- [ ] Pick a theme or clone a template? (${templateInfo})`,
-        `- [ ] If template: which one? If theme: which one? (Themes: ${JSON.stringify(themes)})`,
-        '- [ ] Project name?',
-        `- [ ] Directory? (default: "${directory}", auto-created if needed)${contentsOccupied ? ` ⚠️ "${directory}" is occupied — subdirectory, overwrite (--force), or different path?` : ''}`,
-      ].join('\n')}
-    </Text>,
-    <Text>
-      Command: `mint new [dir] --theme [theme] --name [name]` or `mint new [dir] --template
-      [template] --name [name]`. --theme optionally overrides a template default. --force overwrites
-      non-empty dirs. Use AskQuestion to present choices.
-    </Text>,
-    <Text>{'</system-message>'}</Text>
-  );
-};
-
-async function sendAIUsageMessage(directory: string, contentsOccupied: boolean, themes: string[]) {
-  const templateNames = await fetchAvailableTemplates().catch(() => undefined);
-  sendUsageMessageForAI(directory, contentsOccupied, themes, templateNames);
-}
-
-async function resolveInstallDir(
-  installDir: string,
-  force: boolean,
-  contentsOccupied: boolean
-): Promise<string | undefined> {
-  if (!contentsOccupied) return installDir;
-
-  if (isAI()) {
-    if (force) return installDir;
-    return undefined;
-  }
-
-  const choice = await select({
-    message: `Directory ${installDir} is not empty. What would you like to do?`,
-    choices: [
-      { name: 'Create in a subdirectory', value: 'subdir' as const },
-      { name: 'Overwrite current directory (may lose contents)', value: 'overwrite' as const },
-      { name: 'Cancel', value: 'cancel' as const },
-    ],
-  });
-
-  if (choice === 'cancel') return undefined;
-
-  if (choice === 'subdir') {
-    const subdir = await input({
-      message: 'Subdirectory name:',
-      default: 'docs',
-    });
-    if (!subdir || subdir.trim() === '') {
-      throw new Error('Subdirectory name cannot be empty');
-    }
-    const resolved = installDir === '.' ? subdir : `${installDir}/${subdir}`;
-    validatePathWithinCwd(resolved, process.cwd());
-    return resolved;
-  }
-
-  return installDir;
-}
-
-async function promptForProjectName(installDir: string, currentName?: string): Promise<string> {
-  if (currentName) return currentName;
-  const defaultProject = installDir === '.' ? 'Mintlify' : installDir;
-  return input({ message: 'Project Name', default: defaultProject });
-}
-
-async function promptForApproach(): Promise<string | undefined> {
-  const approach = await select({
-    message: 'How would you like to set up your docs?',
-    choices: [
-      { name: 'Pick a theme', value: 'theme' as const },
-      { name: 'Clone a template', value: 'template' as const },
-    ],
-  });
-
-  if (approach === 'template') return promptForTemplate();
-  return undefined;
-}
-
-export async function init(
-  installDir: string,
-  force: boolean,
-  theme?: string,
-  name?: string,
-  template?: string
-): Promise<void> {
-  validatePathWithinCwd(installDir);
-
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const themes: string[] = docsConfigSchema.options.map((option: any) => {
-    return option.shape.theme._def.value as string;
-  });
-
-  const dirContents = await fse.readdir(installDir).catch(() => [] as string[]);
-  const contentsOccupied = dirContents.length > 0;
-
-  if (isAI() && (!name || (!template && !theme))) {
-    await sendAIUsageMessage(installDir, contentsOccupied, themes);
-    return;
-  }
-
-  if (isAI() && contentsOccupied && !force) {
-    await sendAIUsageMessage(installDir, contentsOccupied, themes);
-    return;
-  }
-
-  const selectedTemplate = template
-    ? await validateTemplateName(template).then(() => template)
-    : !isAI() && !theme
-      ? await promptForApproach()
-      : undefined;
-
-  if (selectedTemplate) {
-    const resolved = await resolveInstallDir(installDir, force, contentsOccupied);
-    if (resolved === undefined) {
-      if (isAI()) await sendAIUsageMessage(installDir, contentsOccupied, themes);
-      return;
-    }
-
-    const projectName = await promptForProjectName(resolved, name);
-    await fse.ensureDir(resolved);
-    await installFromTemplate(resolved, selectedTemplate, projectName, theme);
-    sendOnboardingMessage(resolved);
-    return;
-  }
-
-  // Standard theme-based path
-  const resolved = await resolveInstallDir(installDir, force, contentsOccupied);
-  if (resolved === undefined) {
-    if (isAI()) await sendAIUsageMessage(installDir, contentsOccupied, themes);
-    return;
-  }
-
-  let projectName = name;
-  let selectedTheme = theme;
-
-  if (!isAI() && (!selectedTheme || !projectName)) {
-    projectName = await promptForProjectName(resolved, projectName);
-
-    if (!selectedTheme) {
-      selectedTheme = await select({
-        message: 'Theme',
-        choices: themes.map((t) => ({ name: t, value: t })),
-      });
-    }
-  }
-
-  if (projectName === undefined || selectedTheme === undefined) {
-    await sendAIUsageMessage(resolved, contentsOccupied, themes);
-    return;
-  }
-
-  await fse.ensureDir(resolved);
-  await install(resolved, projectName, selectedTheme);
-  sendOnboardingMessage(resolved);
-}
-
-const install = async (installDir: string, projectName: string, theme: string) => {
-  addLog(<SpinnerLog message="downloading starter template..." />);
-  const response = await fetch('https://github.com/mintlify/starter/archive/refs/heads/main.zip');
-  const buffer = await response.arrayBuffer();
-  await fse.writeFile(installDir + '/starter.zip', Buffer.from(buffer));
-  removeLastLog();
-
-  addLog(<SpinnerLog message="extracting..." />);
-  new AdmZip(installDir + '/starter.zip').extractAllTo(installDir, true);
-  removeLastLog();
-
-  await fse.copy(installDir + '/starter-main', installDir, {
-    overwrite: true,
-    filter: (src) => !src.includes('starter-main/starter-main'),
-  });
-  await fse.remove(installDir + '/starter.zip');
-  await fse.remove(installDir + '/starter-main');
-
-  const docsJsonPath = installDir + '/docs.json';
-  const docsConfig = await fse.readJson(docsJsonPath);
-  docsConfig.theme = theme;
-  docsConfig.name = projectName;
-  await fse.writeJson(docsJsonPath, docsConfig, { spaces: 2 });
-};

package/src/instructions.ts

@@ -1,99 +0,0 @@
-export const INSTRUCTIONS_URL = 'https://www.mintlify.com/docs/mint-instructions';
-
-export const TOPICS: { name: string; when: string }[] = [
-  {
-    name: 'overview',
-    when: 'Start here: how Mintlify works and facts agents most often get wrong',
-  },
-  {
-    name: 'new-site',
-    when: 'New docs site, first publish, no account, claim a site, login, no docs.json yet',
-  },
-  {
-    name: 'write',
-    when: 'Before creating a page or writing more than a sentence or two; changelogs',
-  },
-  {
-    name: 'write components',
-    when: 'Adding or changing components: callouts, cards, steps, tabs, accordions, fields',
-  },
-  { name: 'configure', when: 'Changing docs.json: theme, colors, logo, favicon, required fields' },
-  {
-    name: 'configure navigation',
-    when: 'Changing navigation: groups, tabs, anchors, dropdowns, products, versions, languages',
-  },
-  {
-    name: 'configure settings',
-    when: 'navbar, footer, banner, SEO, search, integrations, contextual menu, redirects, 404',
-  },
-  {
-    name: 'configure customization',
-    when: 'Themes, fonts, CSS, JavaScript, or React snippets',
-  },
-  { name: 'api-docs', when: 'API documentation: OpenAPI, AsyncAPI, GraphQL, playground' },
-  {
-    name: 'api-docs sdk',
-    when: 'SDK reference pages, x-codeSamples, oneOf/anyOf, multiple responses, hiding endpoints',
-  },
-  {
-    name: 'publish',
-    when: 'Deploying, "is it live", previews, rollbacks, MCP, llms.txt, skill.md, Markdown export',
-  },
-  {
-    name: 'publish domain',
-    when: 'Custom domain (mint add-domain), /docs subpath, reverse proxy, CSP',
-  },
-  {
-    name: 'publish repo',
-    when: 'Monorepo, multi-repo, GitHub/GitLab/Bitbucket, offline export, self-host',
-  },
-  {
-    name: 'publish analytics',
-    when: 'mint analytics, feedback, search data, analytics integrations',
-  },
-  {
-    name: 'publish assistant',
-    when: 'AI assistant, widget, Assistant.md, skills, narration, own model',
-  },
-  { name: 'access', when: 'Private docs, reader login, user groups, personalization' },
-  { name: 'access team', when: 'Team members, roles, SSO, SCIM, audit logs, session security' },
-  {
-    name: 'automate',
-    when: 'Keep docs in sync with code: agent, Autopilot, automations, Slack, CI',
-  },
-  {
-    name: 'migrate',
-    when: 'Moving docs from Docusaurus, GitBook, ReadMe, Fern, Document360, Confluence, Markdown',
-  },
-  { name: 'troubleshoot', when: 'An error, a failed build or deploy, or the site looks wrong' },
-];
-
-export const formatTopics = (): string => {
-  const width = Math.max(...TOPICS.map(({ name }) => name.length)) + 2;
-  return [
-    'Usage: mint instructions <topic> [subtopic]',
-    '',
-    ...TOPICS.map(({ name, when }) => `  ${name.padEnd(width)}${when}`),
-    '',
-  ].join('\n');
-};
-
-export const instructionsUrl = (topics: string[]): string =>
-  `${INSTRUCTIONS_URL}/${topics.map(encodeURIComponent).join('/')}.md`;
-
-export const stripDocsPreamble = (markdown: string): string =>
-  markdown.replace(/^(?:>.*\n|\s*\n)*/, '');
-
-export async function fetchInstructions(topics: string[]): Promise<string> {
-  const url = instructionsUrl(topics);
-  const response = await fetch(url);
-  if (response.status === 404) {
-    throw new Error(
-      `no instructions for "${topics.join(' ')}". Run \`mint instructions\` to list topics.`
-    );
-  }
-  if (!response.ok) {
-    throw new Error(`failed to fetch ${url}: ${response.status} ${response.statusText}`);
-  }
-  return stripDocsPreamble(await response.text());
-}

package/src/keyring.ts

@@ -1,65 +0,0 @@
-const SERVICE = 'mintlify';
-const ACCESS_TOKEN_ACCOUNT = 'access_token';
-const REFRESH_TOKEN_ACCOUNT = 'refresh_token';
-const USER_EMAIL_ACCOUNT = 'user_email';
-
-export async function getKeytar(): Promise<typeof import('keytar')> {
-  try {
-    const mod = await import('keytar');
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- ESM wraps CJS in { default: ... } at runtime despite types
-    return mod.default ?? mod;
-  } catch {
-    throw new Error(
-      'keytar is required for credential storage but is not installed. Install it with: npm install keytar'
-    );
-  }
-}
-
-export async function storeCredentials(
-  accessToken: string,
-  refreshToken: string,
-  userEmail?: string | null
-): Promise<void> {
-  const keytar = await getKeytar();
-  await Promise.all([
-    keytar.setPassword(SERVICE, ACCESS_TOKEN_ACCOUNT, accessToken),
-    keytar.setPassword(SERVICE, REFRESH_TOKEN_ACCOUNT, refreshToken),
-  ]);
-
-  try {
-    if (userEmail === null) {
-      await keytar.deletePassword(SERVICE, USER_EMAIL_ACCOUNT);
-    } else if (userEmail !== undefined) {
-      await keytar.setPassword(SERVICE, USER_EMAIL_ACCOUNT, userEmail);
-    }
-  } catch {}
-}
-
-export async function getAccessToken(): Promise<string | null> {
-  const keytar = await getKeytar();
-  return keytar.getPassword(SERVICE, ACCESS_TOKEN_ACCOUNT);
-}
-
-export async function getRefreshToken(): Promise<string | null> {
-  const keytar = await getKeytar();
-  return keytar.getPassword(SERVICE, REFRESH_TOKEN_ACCOUNT);
-}
-
-export async function getUserEmail(): Promise<string | null> {
-  const keytar = await getKeytar();
-  return keytar.getPassword(SERVICE, USER_EMAIL_ACCOUNT);
-}
-
-export async function storeUserEmail(userEmail: string): Promise<void> {
-  const keytar = await getKeytar();
-  await keytar.setPassword(SERVICE, USER_EMAIL_ACCOUNT, userEmail);
-}
-
-export async function clearCredentials(): Promise<void> {
-  const keytar = await getKeytar();
-  await Promise.all([
-    keytar.deletePassword(SERVICE, ACCESS_TOKEN_ACCOUNT),
-    keytar.deletePassword(SERVICE, REFRESH_TOKEN_ACCOUNT),
-    keytar.deletePassword(SERVICE, USER_EMAIL_ACCOUNT).catch(() => false),
-  ]);
-}

package/src/login.tsx

@@ -1,166 +0,0 @@
-import { input, search } from '@inquirer/prompts';
-import { addLog, ErrorLog, InfoLog, SuccessLog } from '@mintlify/previewing';
-import chalk from 'chalk';
-import { Box, Text } from 'ink';
-import open from 'open';
-import {
-  calculatePKCECodeChallenge,
-  randomNonce,
-  randomPKCECodeVerifier,
-  randomState,
-} from 'openid-client';
-
-import { startCallbackServer } from './callbackServer.js';
-import { setConfigValue } from './config.js';
-import { DASHBOARD_URL, TOKEN_ENDPOINT } from './constants.js';
-import { getEmailFromIdToken } from './idToken.js';
-import { storeCredentials } from './keyring.js';
-import { getCliSubdomains } from './status.js';
-import { trackLoginAttempt, trackLoginFailed, trackLoginSuccess } from './telemetry/track.js';
-
-export interface TokenResponse {
-  access_token: string;
-  id_token: string;
-  refresh_token: string;
-  token_type: 'bearer';
-  expires_in: number;
-  request_id: string;
-  status_code: number;
-}
-
-export async function login(): Promise<void> {
-  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 authorizeUrl = new URL('/api/cli/oauth/authorize', DASHBOARD_URL);
-  authorizeUrl.searchParams.set('state', state);
-  authorizeUrl.searchParams.set('code_challenge', codeChallenge);
-  const url = authorizeUrl.toString();
-
-  void trackLoginAttempt();
-
-  const { codePromise, close: closeServer } = await startCallbackServer();
-
-  addLog(
-    <Box flexDirection="column" gap={1} paddingY={1}>
-      <Text bold>
-        <Text color="green">◆ </Text>A browser window will open for Mintlify authentication
-      </Text>
-      <Box flexDirection="column" paddingLeft={3} gap={1}>
-        <Text dimColor>If your browser doesn't open automatically, copy this URL:</Text>
-        <Text dimColor>{url}</Text>
-      </Box>
-    </Box>
-  );
-
-  open(url).catch(() => {});
-
-  addLog(
-    <Box flexDirection="column" paddingLeft={1} marginTop={1}>
-      <Text dimColor>╭─ Paste the authorization code from your browser</Text>
-      <Text dimColor>│</Text>
-    </Box>
-  );
-
-  // Let ink finish rendering before inquirer takes over stdout
-  await new Promise((resolve) => setTimeout(resolve, 50));
-
-  const inputPromise = input({
-    message: '█',
-    theme: {
-      prefix: chalk.dim(' │'),
-      style: {
-        answer: (text: string) => chalk.cyan(text),
-      },
-    },
-  });
-
-  let code: string;
-  try {
-    code = await Promise.race([codePromise, inputPromise]);
-  } catch {
-    closeServer();
-    inputPromise.cancel();
-    addLog(<ErrorLog message="login cancelled" />);
-    return;
-  }
-
-  closeServer();
-  inputPromise.cancel();
-
-  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';
-    void trackLoginFailed(reason);
-    addLog(<ErrorLog message={`login failed: ${reason}`} />);
-    return;
-  }
-
-  const token = body as TokenResponse;
-  await storeCredentials(
-    token.access_token,
-    token.refresh_token,
-    getEmailFromIdToken(token.id_token) ?? null
-  );
-  void trackLoginSuccess();
-  addLog(<SuccessLog message="logged in successfully" />);
-  await promptSubdomainSelection(token.access_token);
-}
-
-function isPromptCancellationError(error: unknown): boolean {
-  return error instanceof Error && error.name === 'ExitPromptError';
-}
-
-async function promptSubdomainSelection(accessToken: string): Promise<void> {
-  const subdomains = await getCliSubdomains(accessToken);
-  if (subdomains.length === 0) return;
-
-  if (subdomains.length === 1) {
-    await setConfigValue('subdomain', subdomains[0]!);
-    addLog(<InfoLog message={`default project set to ${subdomains[0]}`} />);
-    return;
-  }
-
-  await new Promise((resolve) => setTimeout(resolve, 50));
-
-  let chosen: string;
-  try {
-    chosen = await search<string>({
-      message: 'Select a default project',
-      source: (term) => {
-        const results = term
-          ? subdomains.filter((s) => s.toLowerCase().includes(term.toLowerCase()))
-          : subdomains;
-        return results.map((s) => ({ name: s, value: s }));
-      },
-    });
-  } catch (error) {
-    if (isPromptCancellationError(error)) {
-      addLog(
-        <InfoLog
-          message={`No project set. To set a default project, run ${chalk.bold('mintlify config set subdomain <subdomain>')}`}
-        />
-      );
-      return;
-    }
-    throw error;
-  }
-
-  await setConfigValue('subdomain', chosen);
-  addLog(<InfoLog message={`default project set to ${chosen}`} />);
-}

package/src/logout.tsx

@@ -1,8 +0,0 @@
-import { addLog, SuccessLog } from '@mintlify/previewing';
-
-import { clearCredentials } from './keyring.js';
-
-export async function logout(): Promise<void> {
-  await clearCredentials();
-  addLog(<SuccessLog message="logged out successfully" />);
-}