@mintlify/cli 4.0.1741 → 4.0.1742

package/bin/validate/command.js

@@ -21,6 +21,7 @@ var __rest = (this && this.__rest) || function (s, e) {
 import { jsx as _jsx } from "react/jsx-runtime";
 import { addLog, checkBuild, clearLogs, ErrorLog, SpinnerLog } from '@mintlify/previewing';
 import path from 'node:path';
+import { format } from 'node:util';
 import { CMD_EXEC_PATH, errorMessage, getVersions, terminate } from '../helpers.js';
 import { resolveExplicitFiles } from '../resolveFiles.js';
 import { sendPublishPrompt } from '../signup.js';
@@ -32,6 +33,26 @@ export const splitList = (values) => values.flatMap((value) => value
     .split(',')
     .map((item) => item.trim())
     .filter(Boolean));
+const write = (text) => new Promise((resolve) => {
+    process.stdout.write(text, () => resolve());
+});
+/**
+ * Writes console output straight to stderr, so --format json leaves stdout to the report. Ink
+ * patches console and redraws on stdout, so redirecting to console.error isn't enough.
+ */
+const consoleToStderr = () => {
+    const original = {
+        log: console.log,
+        info: console.info,
+        warn: console.warn,
+        error: console.error,
+    };
+    const toStderr = (...args) => {
+        process.stderr.write(`${format(...args)}\n`);
+    };
+    console.log = console.info = console.warn = console.error = toStderr;
+    return () => Object.assign(console, original);
+};
 const resolveSelection = (baseDir, values) => __awaiter(void 0, void 0, void 0, function* () {
     const args = (values !== null && values !== void 0 ? values : []).map(String).filter(Boolean);
     if (args.length === 0)
@@ -42,13 +63,16 @@ const resolveSelection = (baseDir, values) => __awaiter(void 0, void 0, void 0,
 /** mint validate: one pass over every selected rule, then the strict build when nothing failed. */
 export const validateHandler = (argv_1, packageName_1, ...args_1) => __awaiter(void 0, [argv_1, packageName_1, ...args_1], void 0, function* (argv, packageName, baseDir = CMD_EXEC_PATH) {
     var _a;
+    const json = argv.format === 'json';
+    const restoreConsole = json ? consoleToStderr() : undefined;
     try {
         const rules = selectRules({
             enable: argv.enable,
             disable: (_a = argv.disable) !== null && _a !== void 0 ? _a : [],
         });
         const selected = yield resolveSelection(baseDir, argv.files);
-        addLog(_jsx(SpinnerLog, { message: "validating..." }));
+        if (!json)
+            addLog(_jsx(SpinnerLog, { message: "validating..." }));
         const _b = yield checkSite(baseDir, rules, {
             selected,
             localSchema: argv['local-schema'],
@@ -67,7 +91,8 @@ export const validateHandler = (argv_1, packageName_1, ...args_1) => __awaiter(v
             build = { ran: false, reason: 'errors found' };
         }
         else {
-            addLog(_jsx(SpinnerLog, { message: "building..." }));
+            if (!json)
+                addLog(_jsx(SpinnerLog, { message: "building..." }));
             const { cli: cliVersion } = getVersions(packageName);
             site.build = yield checkBuild(Object.assign(Object.assign({}, argv), { _: [], $0: packageName, packageName,
                 cliVersion, disableOpenapi: !rules.some(({ group }) => group === 'openapi') }));
@@ -75,16 +100,28 @@ export const validateHandler = (argv_1, packageName_1, ...args_1) => __awaiter(v
             build = { ran: true, passed: site.build.passed };
         }
         const report = toReport(diagnostics, build, argv.fix ? fixed : undefined);
-        clearLogs();
-        logReport(report);
-        if (report.passed && build.ran && build.passed)
-            yield sendPublishPrompt();
+        if (json) {
+            restoreConsole === null || restoreConsole === void 0 ? void 0 : restoreConsole();
+            yield write(`${JSON.stringify(report)}\n`);
+        }
+        else {
+            clearLogs();
+            logReport(report);
+            if (report.passed && build.ran && build.passed)
+                yield sendPublishPrompt();
+        }
         yield terminate(report.passed ? EXIT.passed : EXIT.failed);
     }
     catch (error) {
         // Bad arguments and crashes alike mean validate could not run
-        clearLogs();
-        addLog(_jsx(ErrorLog, { message: errorMessage(error) }));
+        if (json) {
+            restoreConsole === null || restoreConsole === void 0 ? void 0 : restoreConsole();
+            process.stderr.write(`Error: ${errorMessage(error)}\n`);
+        }
+        else {
+            clearLogs();
+            addLog(_jsx(ErrorLog, { message: errorMessage(error) }));
+        }
         yield terminate(EXIT.crashed);
     }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/cli",
-  "version": "4.0.1741",
+  "version": "4.0.1742",
   "description": "The Mintlify CLI",
   "engines": {
     "node": ">=18.0.0"
@@ -46,11 +46,11 @@
   "dependencies": {
     "@inquirer/prompts": "7.9.0",
     "@mintlify/common": "1.0.1307",
-    "@mintlify/link-rot": "3.0.1537",
+    "@mintlify/link-rot": "3.0.1538",
     "@mintlify/models": "0.0.379",
     "@mintlify/og": "0.0.106",
     "@mintlify/prebuild": "1.0.1474",
-    "@mintlify/previewing": "4.0.1555",
+    "@mintlify/previewing": "4.0.1556",
     "@mintlify/validation": "0.1.944",
     "adm-zip": "0.6.0",
     "chalk": "5.2.0",
@@ -101,5 +101,5 @@
     "vitest": "2.1.9",
     "vitest-mock-process": "1.0.4"
   },
-  "gitHead": "4e0cdb6a51f1b140f02f0579f9e4c32592220434"
+  "gitHead": "d186b90eab824aece48724f71d3b71f2cdebdbe2"
 }

package/src/cli.tsx

@@ -406,6 +406,13 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
               default: false,
               description: 'Apply the fixes and check again',
             })
+            .option('format', {
+              type: 'string',
+              choices: ['text', 'json'] as const,
+              default: 'text' as const,
+              description:
+                'Output format; json prints one report ({ passed, summary, diagnostics, build }) and nothing else on stdout, and errors to stderr',
+            })
             .usage('usage: mint validate [options]')
             .epilogue(
               [
@@ -415,6 +422,10 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
               ].join('\n')
             )
             .example('mint validate', 'run every check and the build')
+            .example(
+              'mint validate --no-build --format json',
+              'fast offline check for scripts and agents'
+            )
             .example(
               'mint validate --files "guides/**/*.mdx" --fix',
               'check some pages and apply fixes'

package/src/validate/command.tsx

@@ -1,5 +1,6 @@
 import { addLog, checkBuild, clearLogs, ErrorLog, SpinnerLog } from '@mintlify/previewing';
 import path from 'node:path';
+import { format } from 'node:util';
 
 import { CMD_EXEC_PATH, errorMessage, getVersions, terminate } from '../helpers.js';
 import { resolveExplicitFiles } from '../resolveFiles.js';
@@ -17,6 +18,7 @@ export type ValidateArgs = {
   enable?: string[];
   disable?: string[];
   fix: boolean;
+  format: 'text' | 'json';
 };
 
 export const EXIT = { passed: 0, failed: 1, crashed: 2 } as const;
@@ -29,6 +31,29 @@ export const splitList = (values: string[]) =>
       .filter(Boolean)
   );
 
+const write = (text: string) =>
+  new Promise<void>((resolve) => {
+    process.stdout.write(text, () => resolve());
+  });
+
+/**
+ * Writes console output straight to stderr, so --format json leaves stdout to the report. Ink
+ * patches console and redraws on stdout, so redirecting to console.error isn't enough.
+ */
+const consoleToStderr = () => {
+  const original = {
+    log: console.log,
+    info: console.info,
+    warn: console.warn,
+    error: console.error,
+  };
+  const toStderr = (...args: unknown[]) => {
+    process.stderr.write(`${format(...args)}\n`);
+  };
+  console.log = console.info = console.warn = console.error = toStderr;
+  return () => Object.assign(console, original);
+};
+
 const resolveSelection = async (baseDir: string, values: (string | number)[] | undefined) => {
   const args = (values ?? []).map(String).filter(Boolean);
   if (args.length === 0) return undefined;
@@ -46,13 +71,15 @@ export const validateHandler = async (
   packageName: string,
   baseDir = CMD_EXEC_PATH
 ) => {
+  const json = argv.format === 'json';
+  const restoreConsole = json ? consoleToStderr() : undefined;
   try {
     const rules = selectRules({
       enable: argv.enable,
       disable: argv.disable ?? [],
     });
     const selected = await resolveSelection(baseDir, argv.files);
-    addLog(<SpinnerLog message="validating..." />);
+    if (!json) addLog(<SpinnerLog message="validating..." />);
 
     const { site, fixed, ...checked } = await checkSite(baseDir, rules, {
       selected,
@@ -70,7 +97,7 @@ export const validateHandler = async (
     } else if (diagnostics.some(({ severity }) => severity === 'error')) {
       build = { ran: false, reason: 'errors found' };
     } else {
-      addLog(<SpinnerLog message="building..." />);
+      if (!json) addLog(<SpinnerLog message="building..." />);
       const { cli: cliVersion } = getVersions(packageName);
       site.build = await checkBuild({
         ...argv,
@@ -85,14 +112,24 @@ export const validateHandler = async (
     }
 
     const report = toReport(diagnostics, build, argv.fix ? fixed : undefined);
-    clearLogs();
-    logReport(report);
-    if (report.passed && build.ran && build.passed) await sendPublishPrompt();
+    if (json) {
+      restoreConsole?.();
+      await write(`${JSON.stringify(report)}\n`);
+    } else {
+      clearLogs();
+      logReport(report);
+      if (report.passed && build.ran && build.passed) await sendPublishPrompt();
+    }
     await terminate(report.passed ? EXIT.passed : EXIT.failed);
   } catch (error) {
     // Bad arguments and crashes alike mean validate could not run
-    clearLogs();
-    addLog(<ErrorLog message={errorMessage(error)} />);
+    if (json) {
+      restoreConsole?.();
+      process.stderr.write(`Error: ${errorMessage(error)}\n`);
+    } else {
+      clearLogs();
+      addLog(<ErrorLog message={errorMessage(error)} />);
+    }
     await terminate(EXIT.crashed);
   }
 };