@mintlify/cli 4.0.604 → 4.0.605

package/bin/update.js

@@ -7,17 +7,16 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { getTargetMintVersion, downloadTargetMint } from '@mintlify/previewing';
-import { execSync } from 'node:child_process';
-import { buildLogger, getLatestCliVersion, getVersions } from './helpers.js';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { getTargetMintVersion, downloadTargetMint, SpinnerLog, SuccessLog, ErrorLog, addLog, clearLogs, } from '@mintlify/previewing';
+import { execAsync, getLatestCliVersion, getVersions } from './helpers.js';
 export const update = (_a) => __awaiter(void 0, [_a], void 0, function* ({ packageName, silent, }) {
-    let logger = undefined;
     if (!silent) {
-        logger = buildLogger(`Updating ${packageName} to the latest version...`);
+        addLog(_jsx(SpinnerLog, { message: "updating..." }));
     }
     const { cli: existingCliVersion, client: existingClientVersion } = getVersions();
     const latestCliVersion = getLatestCliVersion(packageName);
-    const latestClientVersion = yield getTargetMintVersion(logger);
+    const latestClientVersion = yield getTargetMintVersion();
     const isUpToDate = existingCliVersion &&
         existingClientVersion &&
         latestClientVersion &&
@@ -25,44 +24,45 @@ export const update = (_a) => __awaiter(void 0, [_a], void 0, function* ({ packa
         latestCliVersion.trim() === existingCliVersion.trim() &&
         latestClientVersion.trim() === existingClientVersion.trim();
     if (isUpToDate) {
-        if (!silent && logger) {
-            logger.succeed('Already up to date.');
+        if (!silent) {
+            addLog(_jsx(SuccessLog, { message: "already up to date" }));
         }
         return;
     }
     if (existingCliVersion && latestCliVersion.trim() !== existingCliVersion.trim()) {
         try {
-            if (logger) {
-                logger.text = `Updating ${packageName} package...`;
+            if (!silent) {
+                clearLogs();
+                addLog(_jsx(SpinnerLog, { message: `updating ${packageName} package...` }));
             }
-            execSync(`npm install -g ${packageName}@latest --silent`);
+            yield execAsync(`npm install -g ${packageName}@latest --silent`);
         }
         catch (err) {
-            if (logger) {
-                logger.fail(`Failed to update ${packageName}@latest`);
+            if (!silent) {
+                addLog(_jsx(ErrorLog, { message: `failed to update ${packageName}@latest` }));
             }
-            process.exit(1);
+            return;
         }
     }
     if (latestClientVersion && latestClientVersion !== existingClientVersion) {
         try {
-            if (logger) {
-                logger.text = `Updating Mintlify client to ${latestClientVersion}...`;
+            if (!silent) {
+                addLog(_jsx(SpinnerLog, { message: `updating mintlify client to ${latestClientVersion}...` }));
             }
             yield downloadTargetMint({
-                logger,
                 targetVersion: latestClientVersion,
                 existingVersion: existingClientVersion !== null && existingClientVersion !== void 0 ? existingClientVersion : null,
             });
         }
         catch (err) {
-            if (logger) {
-                logger.fail(`Failed to update Mintlify client to ${latestClientVersion}`);
+            if (!silent) {
+                addLog(_jsx(ErrorLog, { message: `failed to update mintlify client to ${latestClientVersion}` }));
             }
-            process.exit(1);
+            return;
         }
     }
-    if (logger) {
-        logger.succeed(`Updated ${packageName} to the latest version: ${latestCliVersion}`);
+    if (!silent) {
+        clearLogs();
+        addLog(_jsx(SuccessLog, { message: `updated ${packageName} to the latest version: ${latestCliVersion}` }));
     }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/cli",
-  "version": "4.0.604",
+  "version": "4.0.605",
   "description": "The Mintlify CLI",
   "engines": {
     "node": ">=18.0.0"
@@ -26,7 +26,7 @@
     "mintlify": "bin/index.js"
   },
   "scripts": {
-    "dev": "yarn build && node bin/index.js dev",
+    "dev": "yarn build && NODE_NO_WARNINGS=1 node bin/index.js",
     "prepare": "npm run build",
     "build": "tsc --project tsconfig.build.json",
     "clean:build": "rimraf bin",
@@ -40,17 +40,18 @@
   },
   "dependencies": {
     "@mintlify/common": "1.0.435",
-    "@mintlify/link-rot": "3.0.554",
+    "@mintlify/link-rot": "3.0.555",
     "@mintlify/models": "0.0.202",
-    "@mintlify/prebuild": "1.0.550",
-    "@mintlify/previewing": "4.0.593",
+    "@mintlify/prebuild": "1.0.551",
+    "@mintlify/previewing": "4.0.594",
     "@mintlify/validation": "0.1.402",
     "chalk": "^5.2.0",
     "detect-port": "^1.5.1",
     "fs-extra": "^11.2.0",
+    "ink": "^6.0.1",
     "inquirer": "^12.3.0",
     "js-yaml": "^4.1.0",
-    "ora": "^6.1.2",
+    "react": "^19.1.0",
     "semver": "^7.7.2",
     "yargs": "^17.6.0"
   },
@@ -72,5 +73,5 @@
     "vitest": "^2.0.4",
     "vitest-mock-process": "^1.0.4"
   },
-  "gitHead": "4447c377f16c9771e9ff3b740d1e1cfd1b039451"
+  "gitHead": "5bd2ef4133962495f8e9c4ae006862a1ea23671c"
 }

package/src/cli.tsx

@@ -0,0 +1,255 @@
+import { validate, getOpenApiDocumentFromUrl, isAllowedLocalSchemaUrl } from '@mintlify/common';
+import { getBrokenInternalLinks, renameFilesAndUpdateLinksInContent } from '@mintlify/link-rot';
+import {
+  addLog,
+  dev,
+  ErrorLog,
+  SpinnerLog,
+  SuccessLog,
+  Logs,
+  clearLogs,
+  BrokenLinksLog,
+} from '@mintlify/previewing';
+import { render, Text } from 'ink';
+import path from 'path';
+import semver from 'semver';
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+
+import { LOCAL_LINKED_VERSION, MINIMUM_CLI_VERSION } from './constants.js';
+import {
+  checkPort,
+  checkForMintJson,
+  checkNodeVersion,
+  upgradeConfig,
+  checkForDocsJson,
+  getCliVersion,
+  getVersions,
+  suppressConsoleWarnings,
+  terminate,
+  readLocalOpenApiFile,
+} from './helpers.js';
+import { update } from './update.js';
+
+export const cli = () => {
+  render(<Logs />);
+
+  return (
+    yargs(hideBin(process.argv))
+      .middleware(checkNodeVersion)
+      .middleware(suppressConsoleWarnings)
+      .command(
+        'dev',
+        'initialize a local preview environment',
+        (yargs) =>
+          yargs
+            .option('open', {
+              type: 'boolean',
+              default: true,
+              description: 'open a local preview in the browser',
+            })
+            .option('local-schema', {
+              type: 'boolean',
+              default: false,
+              hidden: true,
+              description:
+                'use a locally hosted schema file (note: only https protocol is supported in production)',
+            })
+            .option('client-version', {
+              type: 'string',
+              hidden: true,
+              description: 'the version of the client to use for cli testing',
+            })
+            .usage('usage: mintlify dev [options]')
+            .example('mintlify dev', 'run with default settings (opens in browser)')
+            .example('mintlify dev --no-open', 'run without opening in browser'),
+        async (argv) => {
+          const port = await checkPort(argv);
+          const packageName = process.argv[1]?.split('/').pop() ?? 'mintlify';
+          const cliVersion = getCliVersion();
+          if (
+            cliVersion &&
+            cliVersion !== LOCAL_LINKED_VERSION &&
+            semver.lt(cliVersion, MINIMUM_CLI_VERSION)
+          ) {
+            await update({ packageName, silent: true });
+          }
+          if (port != undefined) {
+            await dev({
+              ...argv,
+              port,
+              packageName,
+              cliVersion: cli,
+            });
+          } else {
+            addLog(<ErrorLog message="no available port found" />);
+            await terminate(1);
+          }
+        }
+      )
+      .command(
+        'openapi-check <filename>',
+        'check if an OpenAPI spec is valid',
+        (yargs) =>
+          yargs
+            .positional('filename', {
+              describe:
+                'the filename of the OpenAPI spec (e.g. ./openapi.yaml) or the URL to the OpenAPI spec (e.g. https://petstore3.swagger.io/api/v3/openapi.json)',
+              type: 'string',
+              demandOption: true,
+            })
+            .option('local-schema', {
+              type: 'boolean',
+              default: false,
+              description:
+                'use a locally hosted schema file (note: only https protocol is supported in production)',
+            }),
+        async ({ filename, 'local-schema': localSchema }) => {
+          try {
+            if (isAllowedLocalSchemaUrl(filename, localSchema)) {
+              await getOpenApiDocumentFromUrl(filename);
+              addLog(<SuccessLog message="OpenAPI definition is valid." />);
+              await terminate(0);
+            }
+            const document = await readLocalOpenApiFile(filename);
+
+            if (!document) {
+              throw new Error(
+                'failed to parse OpenAPI spec: could not parse file correctly, please check for any syntax errors.'
+              );
+            }
+            await validate(document);
+            addLog(<SuccessLog message="OpenAPI definition is valid." />);
+          } catch (err) {
+            addLog(<ErrorLog message={err instanceof Error ? err.message : 'unknown error'} />);
+            await terminate(1);
+          }
+
+          await terminate(0);
+        }
+      )
+      .command(
+        'broken-links',
+        'check for invalid internal links',
+        () => undefined,
+        async () => {
+          const hasMintJson = await checkForMintJson();
+          if (!hasMintJson) {
+            await checkForDocsJson();
+          }
+
+          addLog(<SpinnerLog message="checking for broken links..." />);
+          try {
+            const brokenLinks = await getBrokenInternalLinks();
+            if (brokenLinks.length === 0) {
+              clearLogs();
+              addLog(<SuccessLog message="no broken links found" />);
+              await terminate(0);
+            }
+
+            const brokenLinksByFile: Record<string, string[]> = {};
+            brokenLinks.forEach((mdxPath) => {
+              const filename = path.join(mdxPath.relativeDir, mdxPath.filename);
+              const brokenLinksForFile = brokenLinksByFile[filename];
+              if (brokenLinksForFile) {
+                brokenLinksForFile.push(mdxPath.originalPath);
+              } else {
+                brokenLinksByFile[filename] = [mdxPath.originalPath];
+              }
+            });
+            clearLogs();
+            addLog(<BrokenLinksLog brokenLinksByFile={brokenLinksByFile} />);
+          } catch (err) {
+            addLog(<ErrorLog message={err instanceof Error ? err.message : 'unknown error'} />);
+            await terminate(1);
+          }
+
+          await terminate(0);
+        }
+      )
+      .command(
+        'rename <from> <to>',
+        'rename a file and update all internal link references',
+        (yargs) =>
+          yargs
+            .positional('from', {
+              describe: 'the file to rename',
+              type: 'string',
+            })
+            .positional('to', {
+              describe: 'the new name for the file',
+              type: 'string',
+            })
+            .demandOption(['from', 'to'])
+            .option('force', {
+              type: 'boolean',
+              default: false,
+              description: 'rename files and skip errors',
+            })
+            .epilog('example: `mintlify rename introduction.mdx overview.mdx`'),
+        async ({ from, to, force }) => {
+          const hasMintJson = await checkForMintJson();
+          if (!hasMintJson) {
+            await checkForDocsJson();
+          }
+          await renameFilesAndUpdateLinksInContent(from, to, force);
+          await terminate(0);
+        }
+      )
+      .command(
+        'update',
+        'update the CLI to the latest version',
+        () => undefined,
+        async () => {
+          const packageName = process.argv[1]?.split('/').pop() ?? 'mintlify';
+          await update({ packageName });
+          await terminate(0);
+        }
+      )
+      .command(
+        'upgrade',
+        'upgrade mint.json file to docs.json (current format)',
+        () => undefined,
+        async () => {
+          const hasMintJson = await checkForMintJson();
+          if (!hasMintJson) {
+            await checkForDocsJson();
+          }
+          await upgradeConfig();
+        }
+      )
+      .command(
+        ['version', 'v'],
+        'display the current version of the CLI and client',
+        () => undefined,
+        async () => {
+          const { cli, client } = getVersions();
+          addLog(
+            <Text>
+              <Text bold color="green">
+                cli version
+              </Text>{' '}
+              {cli}
+            </Text>
+          );
+          addLog(
+            <Text>
+              <Text bold color="green">
+                client version
+              </Text>{' '}
+              {client}
+            </Text>
+          );
+        }
+      )
+      // Print the help menu when the user enters an invalid command.
+      .strictCommands()
+      .demandCommand(1, 'unknown command. see above for the list of supported commands.')
+
+      // Alias option flags --help = -h, default --version = -v
+      .alias('h', 'help')
+      .alias('v', 'version')
+
+      .parse()
+  );
+};

package/src/{helpers.ts → helpers.tsx}

@@ -1,14 +1,22 @@
 import { getConfigPath } from '@mintlify/prebuild';
 import { MintConfigUpdater } from '@mintlify/prebuild';
-import { getClientVersion } from '@mintlify/previewing';
+import {
+  addLog,
+  ErrorLog,
+  getClientVersion,
+  SuccessLog,
+  InfoLog,
+  SpinnerLog,
+  removeLastLog,
+} from '@mintlify/previewing';
 import { upgradeToDocsConfig } from '@mintlify/validation';
-import Chalk from 'chalk';
 import detect from 'detect-port';
 import fse from 'fs-extra';
 import fs from 'fs/promises';
 import inquirer from 'inquirer';
-import { execSync } from 'node:child_process';
-import Ora, { Ora as OraType } from 'ora';
+import yaml from 'js-yaml';
+import { exec, execSync } from 'node:child_process';
+import { promisify } from 'node:util';
 import path from 'path';
 import type { ArgumentsCamelCase } from 'yargs';
 import yargs from 'yargs';
@@ -20,7 +28,7 @@ export const checkPort = async (argv: ArgumentsCamelCase): Promise<number | unde
   if (initialPort === (await detect(initialPort))) return initialPort;
 
   for (let port = initialPort + 1; port < initialPort + 10; port++) {
-    console.log(`Port ${port - 1} is already in use. Trying ${port} instead.`);
+    addLog(<InfoLog message={`port ${port - 1} is already in use. trying ${port} instead`} />);
     if (port === (await detect(port))) return port;
   }
 };
@@ -34,19 +42,14 @@ export const checkNodeVersion = async () => {
   const majorVersion = parseInt(versionArr[0]!, 10);
 
   if (majorVersion < 18) {
-    const logger = buildLogger();
-    logger.fail(
-      `Mintlify requires a node version >= 18.0.0 (current version ${nodeVersionString}). Try removing the mintlify package, upgrading node, reinstalling mintlify, and running again.`
+    addLog(
+      <ErrorLog
+        message={`mintlify requires a node version >= 18.0.0 (current version ${nodeVersionString}). try removing the mintlify package, upgrading node, reinstalling mintlify, and running again.`}
+      />
     );
-    process.exit(1);
   }
 };
 
-export const buildLogger = (startText = ''): OraType => {
-  const logger = Ora().start(startText);
-  return logger;
-};
-
 export const checkForMintJson = async () => {
   return !!(await getConfigPath(CMD_EXEC_PATH, 'mint'));
 };
@@ -54,15 +57,15 @@ export const checkForMintJson = async () => {
 export const checkForDocsJson = async () => {
   const docsJsonPath = path.join(CMD_EXEC_PATH, 'docs.json');
   if (!(await fse.pathExists(docsJsonPath))) {
-    console.log('New docs.json file is available.');
+    addLog(<InfoLog message="new docs.json file is available" />);
     const promptResult = await inquirer.prompt([
       {
         type: 'list',
         name: 'action',
-        message: 'Would you like to upgrade your mint.json to docs.json?',
+        message: 'would you like to upgrade your mint.json to docs.json?',
         choices: [
-          { name: 'Continue (use existing mint.json)', value: 'continue' },
-          { name: 'Upgrade (migrate from mint.json -> docs.json)', value: 'upgrade' },
+          { name: 'upgrade (migrate from mint.json to docs.json)', value: 'upgrade' },
+          { name: 'continue (use existing mint.json)', value: 'continue' },
         ],
       },
     ]);
@@ -70,11 +73,11 @@ export const checkForDocsJson = async () => {
     const { action } = promptResult;
 
     if (action === 'continue') {
-      console.log('Proceeding with the existing mint.json...');
+      addLog(<InfoLog message="proceeding with the existing mint.json..." />);
     }
 
     if (action === 'upgrade') {
-      console.log('Upgrading docs.json...');
+      addLog(<SpinnerLog message="upgrading docs.json..." />);
       await upgradeConfig();
     }
   }
@@ -91,10 +94,11 @@ export const upgradeConfig = async () => {
       shouldUpgradeTheme: true,
     });
     await fs.writeFile(docsJsonPath, JSON.stringify(upgradedDocsConfig, null, 2));
-    console.log(Chalk.green('✅ Your mint.json file has been upgraded to v2 (docs.json).'));
+    removeLastLog();
+    addLog(<SuccessLog message="mint.json file has been upgraded to docs.json." />);
   } catch (err) {
-    console.error(Chalk.red(err));
-    process.exit(1);
+    removeLastLog();
+    addLog(<ErrorLog message={err instanceof Error ? err.message : 'an unknown error occurred'} />);
   }
 };
 
@@ -153,3 +157,20 @@ export const suppressConsoleWarnings = (): void => {
     originalConsoleWarn.apply(console, args);
   };
 };
+
+export const readLocalOpenApiFile = async (
+  filename: string
+): Promise<Record<string, unknown> | undefined> => {
+  const pathname = path.resolve(process.cwd(), filename);
+  const file = await fs.readFile(pathname, 'utf-8');
+  const document = yaml.load(file) as Record<string, unknown> | undefined;
+  return document;
+};
+
+export const terminate = async (code: number) => {
+  // Wait for the logs to be fully rendered before exiting
+  await new Promise((resolve) => setTimeout(resolve, 50));
+  process.exit(code);
+};
+
+export const execAsync = promisify(exec);

package/src/update.tsx

@@ -0,0 +1,79 @@
+import {
+  getTargetMintVersion,
+  downloadTargetMint,
+  SpinnerLog,
+  SuccessLog,
+  ErrorLog,
+  addLog,
+  clearLogs,
+} from '@mintlify/previewing';
+
+import { execAsync, getLatestCliVersion, getVersions } from './helpers.js';
+
+export const update = async ({
+  packageName,
+  silent,
+}: {
+  packageName: string;
+  silent?: boolean;
+}) => {
+  if (!silent) {
+    addLog(<SpinnerLog message="updating..." />);
+  }
+  const { cli: existingCliVersion, client: existingClientVersion } = getVersions();
+  const latestCliVersion = getLatestCliVersion(packageName);
+  const latestClientVersion = await getTargetMintVersion();
+  const isUpToDate =
+    existingCliVersion &&
+    existingClientVersion &&
+    latestClientVersion &&
+    latestCliVersion &&
+    latestCliVersion.trim() === existingCliVersion.trim() &&
+    latestClientVersion.trim() === existingClientVersion.trim();
+
+  if (isUpToDate) {
+    if (!silent) {
+      addLog(<SuccessLog message="already up to date" />);
+    }
+    return;
+  }
+
+  if (existingCliVersion && latestCliVersion.trim() !== existingCliVersion.trim()) {
+    try {
+      if (!silent) {
+        clearLogs();
+        addLog(<SpinnerLog message={`updating ${packageName} package...`} />);
+      }
+      await execAsync(`npm install -g ${packageName}@latest --silent`);
+    } catch (err) {
+      if (!silent) {
+        addLog(<ErrorLog message={`failed to update ${packageName}@latest`} />);
+      }
+      return;
+    }
+  }
+
+  if (latestClientVersion && latestClientVersion !== existingClientVersion) {
+    try {
+      if (!silent) {
+        addLog(<SpinnerLog message={`updating mintlify client to ${latestClientVersion}...`} />);
+      }
+      await downloadTargetMint({
+        targetVersion: latestClientVersion,
+        existingVersion: existingClientVersion ?? null,
+      });
+    } catch (err) {
+      if (!silent) {
+        addLog(<ErrorLog message={`failed to update mintlify client to ${latestClientVersion}`} />);
+      }
+      return;
+    }
+  }
+
+  if (!silent) {
+    clearLogs();
+    addLog(
+      <SuccessLog message={`updated ${packageName} to the latest version: ${latestCliVersion}`} />
+    );
+  }
+};

package/tsconfig.json

@@ -2,8 +2,9 @@
   "extends": "@mintlify/ts-config",
   "compilerOptions": {
     "outDir": "bin",
-    "types": ["vitest/globals"]
+    "types": ["vitest/globals"],
+    "jsx": "react-jsx"
   },
-  "include": ["**/*.ts"],
+  "include": ["**/*.ts", "src/**/*.tsx"],
   "exclude": ["node_modules", "bin"]
 }