@mintlify/cli 4.0.1314 → 4.0.1316

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/cli",
-  "version": "4.0.1314",
+  "version": "4.0.1316",
   "description": "The Mintlify CLI",
   "engines": {
     "node": ">=18.0.0"
@@ -45,12 +45,12 @@
   },
   "dependencies": {
     "@inquirer/prompts": "7.9.0",
-    "@mintlify/common": "1.0.1023",
-    "@mintlify/link-rot": "3.0.1215",
+    "@mintlify/common": "1.0.1024",
+    "@mintlify/link-rot": "3.0.1216",
     "@mintlify/models": "0.0.339",
-    "@mintlify/prebuild": "1.0.1171",
-    "@mintlify/previewing": "4.0.1240",
-    "@mintlify/validation": "0.1.788",
+    "@mintlify/prebuild": "1.0.1172",
+    "@mintlify/previewing": "4.0.1241",
+    "@mintlify/validation": "0.1.789",
     "adm-zip": "0.5.16",
     "chalk": "5.2.0",
     "color": "4.2.3",
@@ -92,5 +92,5 @@
     "vitest": "2.1.9",
     "vitest-mock-process": "1.0.4"
   },
-  "gitHead": "51709ba9505ff6c94ca4ac6617dbe9bcf8ce68b3"
+  "gitHead": "b579437abcf745a46e1ff9744fe3cefa2c3de5e5"
 }

package/src/cli.tsx

@@ -23,6 +23,7 @@ import { comingSoon } from './comingSoon.js';
 import { setTelemetryEnabled } from './config.js';
 import { getConfigValue, setConfigValue, clearConfigValue } from './config.js';
 import { API_URL } from './constants.js';
+import { deslopHandler } from './deslop/index.js';
 import {
   CMD_EXEC_PATH,
   checkPort,
@@ -38,10 +39,11 @@ import { getAccessToken } from './keyring.js';
 import { login } from './login.js';
 import { logout } from './logout.js';
 import { mdxLinter } from './mdxLinter.js';
+import { subdomainMiddleware } from './middlewares/subdomainMiddleware.js';
 import { createTelemetryMiddleware } from './middlewares/telemetryMiddleware.js';
 import { checkOpenApiFile, getOpenApiFilenamesFromDocsConfig } from './openApiCheck.js';
 import { scoreHandler } from './score/index.js';
-import { signup } from './signup.js';
+import { sendAIUsageMessage, signup } from './signup.js';
 import { status, getCliSubdomains } from './status.js';
 import { trackTelemetryPreferenceChange } from './telemetry/track.js';
 import { update } from './update.js';
@@ -78,6 +80,12 @@ const showWelcome = async (packageName: string): Promise<void> => {
   await terminate(0);
 };
 
+// If an AI tries to run mint signup --help, it needs to get the AI custom prompt instead
+const isAISignupHelpRequest = (args: string[]): boolean => {
+  const positionals = args.filter((arg) => !arg.startsWith('-'));
+  return isAI() && positionals[0] === 'signup' && (args.includes('--help') || args.includes('-h'));
+};
+
 export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
   if (shouldShowWelcome(hideBin(process.argv))) {
     return showWelcome(packageName);
@@ -86,6 +94,11 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
   const telemetryMiddleware = createTelemetryMiddleware();
   render(<Logs />);
 
+  if (isAISignupHelpRequest(hideBin(process.argv))) {
+    sendAIUsageMessage();
+    return terminate(0);
+  }
+
   return (
     yargs(hideBin(process.argv))
       .scriptName(packageName)
@@ -656,6 +669,54 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
             .example('mint score docs.example.com', 'Run agent readiness checks on a URL'),
         scoreHandler
       )
+      .command(
+        'deslop [files..]',
+        'Detect AI-sounding prose and get humanization suggestions',
+        (yargs: Argv) =>
+          yargs
+            .middleware(subdomainMiddleware)
+            .positional('files', {
+              type: 'string',
+              array: true,
+              description: 'Files or globs to check (defaults to git-changed pages)',
+            })
+            .option('format', {
+              type: 'string',
+              choices: ['table', 'plain', 'json'] as const,
+              description: 'Output format',
+            })
+            .option('subdomain', {
+              type: 'string',
+              description: 'Documentation subdomain (default: mint config set subdomain)',
+            })
+            .option('threshold', {
+              type: 'number',
+              default: 0.5,
+              description: 'Fail a page when its AI-written fraction meets this value (0-1)',
+            })
+            .option('fix-whitespace', {
+              type: 'boolean',
+              default: false,
+              description:
+                'Normalize prose whitespace in the checked files (skips code and frontmatter)',
+            })
+            .check((argv) => {
+              if (
+                typeof argv.threshold === 'number' &&
+                (argv.threshold < 0 || argv.threshold > 1 || Number.isNaN(argv.threshold))
+              ) {
+                throw new Error('--threshold must be a number between 0 and 1');
+              }
+              return true;
+            })
+            .example('mint deslop', 'Check git-changed pages for AI-sounding prose')
+            .example('mint deslop docs/guide.mdx', 'Check a specific page')
+            .example(
+              'mint deslop "docs/**/*.mdx" --format json',
+              'Check pages by glob with agent-friendly JSON output'
+            ),
+        deslopHandler
+      )
       // Coming soon commands — visible in help, tracked via telemetry to gauge interest.
       .command(
         'ai',

package/src/deslop/client.ts

@@ -0,0 +1,77 @@
+import { authenticatedFetch } from '../authenticatedFetch.js';
+import { API_URL } from '../constants.js';
+import type { DeslopFileResult, DeslopResponse } from './types.js';
+
+const DEFAULT_CONCURRENCY = 4;
+
+// Errors that apply to the whole batch (out of credits, service down) rather
+// than a single page — hitting one means the rest will fail identically.
+class DeslopAbortError extends Error {}
+
+export async function checkPage(
+  subdomain: string,
+  pagePath: string,
+  content: string
+): Promise<DeslopResponse> {
+  const endpoint = new URL(`${API_URL}/api/cli/deslop`);
+  endpoint.searchParams.set('subdomain', subdomain);
+
+  const res = await authenticatedFetch(endpoint.toString(), {
+    method: 'POST',
+    headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+    body: JSON.stringify({ path: pagePath, content }),
+  });
+
+  if (res.status === 402) {
+    throw new DeslopAbortError('Out of AI credits — upgrade or top up in the Mintlify dashboard.');
+  }
+  if (res.status === 503) {
+    throw new DeslopAbortError('Deslop is temporarily unavailable, try again shortly.');
+  }
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new Error(`API error (${res.status}): ${body || res.statusText}`);
+  }
+
+  return res.json() as Promise<DeslopResponse>;
+}
+
+export async function checkPages(
+  subdomain: string,
+  pages: { path: string; content: string }[],
+  concurrency: number = DEFAULT_CONCURRENCY
+): Promise<DeslopFileResult[]> {
+  const results = new Array<DeslopFileResult>(pages.length);
+  let next = 0;
+  let aborted = false;
+
+  const worker = async () => {
+    while (next < pages.length && !aborted) {
+      const index = next++;
+      const page = pages[index]!;
+      try {
+        const response = await checkPage(subdomain, page.path, page.content);
+        results[index] = { file: page.path, response };
+      } catch (err) {
+        results[index] = {
+          file: page.path,
+          error: err instanceof Error ? err.message : 'unknown error',
+        };
+        if (err instanceof DeslopAbortError) aborted = true;
+      }
+    }
+  };
+
+  await Promise.all(Array.from({ length: Math.min(concurrency, pages.length) }, worker));
+
+  // Pages left unprocessed because the batch was aborted after a global failure.
+  for (let index = 0; index < pages.length; index++) {
+    if (!results[index]) {
+      results[index] = {
+        file: pages[index]!.path,
+        error: 'Not checked — stopped after a credits or availability error.',
+      };
+    }
+  }
+  return results;
+}

package/src/deslop/index.tsx

@@ -0,0 +1,286 @@
+import { addLog, ErrorLog, SpinnerLog, removeLastLog } from '@mintlify/previewing';
+import chalk from 'chalk';
+import { Text } from 'ink';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { CMD_EXEC_PATH, terminate } from '../helpers.js';
+import { trackEvent } from '../telemetry/track.js';
+import { checkPages } from './client.js';
+import { resolveChangedFiles, resolveExplicitFiles } from './resolveFiles.js';
+import type { DeslopCheckedResponse, DeslopFileResult } from './types.js';
+import { normalizeWhitespace, summarizeWhitespace } from './whitespace.js';
+
+type OutputFormat = 'table' | 'plain' | 'json';
+
+export type DeslopArgs = {
+  files?: (string | number)[];
+  format?: string;
+  subdomain?: string;
+  threshold?: number;
+  fixWhitespace?: boolean;
+};
+
+async function fixWhitespacePass(
+  files: string[],
+  apply: boolean
+): Promise<{ file: string; summary: string }[]> {
+  const changes: { file: string; summary: string }[] = [];
+  for (const file of files) {
+    const fullPath = path.join(CMD_EXEC_PATH, file);
+    const content = await fs.readFile(fullPath, 'utf-8');
+    const report = normalizeWhitespace(content);
+    const summary = summarizeWhitespace(report.counts);
+    if (!report.changed || !summary) continue;
+    if (apply) await fs.writeFile(fullPath, report.fixed);
+    changes.push({ file, summary });
+  }
+  return changes;
+}
+
+type Paint = (text: string) => string;
+
+type Palette = { green: Paint; red: Paint; dim: Paint };
+
+const identity: Paint = (text) => text;
+
+const colorPalette: Palette = { green: chalk.green, red: chalk.red, dim: chalk.dim };
+const plainPalette: Palette = { green: identity, red: identity, dim: identity };
+
+function resolveFormat(argv: { format?: string }): OutputFormat {
+  if (argv.format === 'table' || argv.format === 'plain' || argv.format === 'json')
+    return argv.format;
+  return 'table';
+}
+
+function output(format: OutputFormat, text: string) {
+  if (format === 'table') {
+    addLog(<Text>{text}</Text>);
+  } else {
+    process.stdout.write(text + '\n');
+  }
+}
+
+function requireSubdomain(subdomain: string | undefined): string {
+  if (!subdomain) {
+    throw new Error(
+      'No subdomain set. Pass --subdomain, or run `mint config set subdomain <name>`.'
+    );
+  }
+  return subdomain;
+}
+
+function flaggedFraction(response: DeslopCheckedResponse): number {
+  return response.fractionAi + response.fractionAiAssisted;
+}
+
+// A fully-human page (fraction 0) never fails, even at --threshold 0.
+function isFailing(fraction: number, threshold: number): boolean {
+  return fraction > 0 && fraction >= threshold;
+}
+
+function truncateText(text: string, max = 100): string {
+  const flat = text.replace(/\s+/g, ' ').trim();
+  return flat.length > max ? `${flat.slice(0, max)}…` : flat;
+}
+
+function renderResult(result: DeslopFileResult, threshold: number, palette: Palette): string[] {
+  if ('error' in result) {
+    return [`${palette.red('✗')} ${result.file} — ${palette.red(result.error)}`];
+  }
+  const response = result.response;
+  if (response.skipped !== null) {
+    return [`${palette.dim('○')} ${result.file} — ${palette.dim(`skipped (${response.skipped})`)}`];
+  }
+  const fraction = flaggedFraction(response);
+  const failing = isFailing(fraction, threshold);
+  const icon = failing ? palette.red('✗') : palette.green('✓');
+  const percent = Math.round(fraction * 100);
+  const lines = [`${icon} ${result.file} — ${response.predictionShort} (${percent}% AI-written)`];
+  if (!failing) return lines;
+  for (const window of response.windows) {
+    lines.push(
+      `  L${window.startLine}–${window.endLine} [${window.label} ${window.aiAssistanceScore.toFixed(2)}]`
+    );
+    lines.push(`  ${palette.dim(truncateText(window.text))}`);
+    for (const rewrite of window.rewrites ?? []) {
+      lines.push(`    ↻ ${rewrite.text}`);
+      lines.push(`      ${palette.dim(rewrite.rationale)}`);
+    }
+  }
+  return lines;
+}
+
+type Summary = {
+  checked: number;
+  passed: number;
+  failed: number;
+  skipped: number;
+  creditsCharged: number;
+  errors: number;
+};
+
+function summarize(results: DeslopFileResult[], threshold: number): Summary {
+  const summary: Summary = {
+    checked: 0,
+    passed: 0,
+    failed: 0,
+    skipped: 0,
+    creditsCharged: 0,
+    errors: 0,
+  };
+  for (const result of results) {
+    if ('error' in result) {
+      summary.errors += 1;
+      continue;
+    }
+    summary.creditsCharged += result.response.creditsCharged;
+    if (result.response.skipped !== null) {
+      summary.skipped += 1;
+      continue;
+    }
+    summary.checked += 1;
+    if (isFailing(flaggedFraction(result.response), threshold)) {
+      summary.failed += 1;
+    } else {
+      summary.passed += 1;
+    }
+  }
+  return summary;
+}
+
+function renderSummaryLine(summary: Summary, palette: Palette): string {
+  const parts = [
+    `${summary.checked} checked`,
+    palette.green(`${summary.passed} passed`),
+    summary.failed > 0 ? palette.red(`${summary.failed} failed`) : `${summary.failed} failed`,
+    palette.dim(`${summary.skipped} skipped`),
+    `${summary.creditsCharged} ${summary.creditsCharged === 1 ? 'credit' : 'credits'} used`,
+  ];
+  if (summary.errors > 0) {
+    parts.push(palette.red(`${summary.errors} ${summary.errors === 1 ? 'error' : 'errors'}`));
+  }
+  return parts.join(' · ');
+}
+
+export const deslopHandler = async (argv: DeslopArgs) => {
+  const format = resolveFormat(argv);
+  let spinnerAdded = false;
+  const threshold = typeof argv.threshold === 'number' ? argv.threshold : 0.5;
+  try {
+    const subdomain = requireSubdomain(argv.subdomain);
+    const fileArgs = (argv.files ?? []).map(String).filter(Boolean);
+    const files =
+      fileArgs.length > 0
+        ? await resolveExplicitFiles(CMD_EXEC_PATH, fileArgs)
+        : await resolveChangedFiles(CMD_EXEC_PATH);
+
+    if (files.length === 0) {
+      if (format === 'json') {
+        process.stderr.write('No changed docs pages to check.\n');
+        output(
+          format,
+          JSON.stringify(
+            {
+              threshold,
+              results: [],
+              summary: {
+                checked: 0,
+                passed: 0,
+                failed: 0,
+                skipped: 0,
+                errors: 0,
+                creditsCharged: 0,
+              },
+            },
+            null,
+            2
+          )
+        );
+      } else {
+        output(format, 'No changed docs pages to check.');
+      }
+      await terminate(0);
+      return;
+    }
+
+    const whitespaceChanges = argv.fixWhitespace ? await fixWhitespacePass(files, true) : [];
+
+    const progressMessage = `Checking ${files.length} ${files.length === 1 ? 'page' : 'pages'} for AI-sounding prose...`;
+    if (format === 'table') {
+      addLog(<SpinnerLog message={progressMessage} />);
+      spinnerAdded = true;
+    } else {
+      process.stderr.write(progressMessage + '\n');
+    }
+
+    const pages = await Promise.all(
+      files.map(async (file) => ({
+        path: file,
+        content: await fs.readFile(path.join(CMD_EXEC_PATH, file), 'utf-8'),
+      }))
+    );
+    const results = await checkPages(subdomain, pages);
+    if (spinnerAdded) {
+      removeLastLog();
+      spinnerAdded = false;
+    }
+
+    const summary = summarize(results, threshold);
+
+    void trackEvent('cli.deslop.executed', {
+      fileCount: files.length,
+      flaggedCount: summary.failed,
+      format,
+    });
+
+    if (format === 'json') {
+      output(
+        format,
+        JSON.stringify(
+          {
+            threshold,
+            results: results.map((result) =>
+              'error' in result ? { path: result.file, error: result.error } : result.response
+            ),
+            summary: {
+              checked: summary.checked,
+              passed: summary.passed,
+              failed: summary.failed,
+              skipped: summary.skipped,
+              errors: summary.errors,
+              creditsCharged: summary.creditsCharged,
+            },
+            whitespaceFixed: whitespaceChanges,
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      const palette = format === 'table' ? colorPalette : plainPalette;
+      const lines: string[] = [];
+      for (const change of whitespaceChanges) {
+        lines.push(`${palette.green('⇥')} ${change.file} — whitespace fixed (${change.summary})`);
+      }
+      if (whitespaceChanges.length) lines.push('');
+      for (const result of results) {
+        lines.push(...renderResult(result, threshold, palette));
+      }
+      lines.push('');
+      lines.push(renderSummaryLine(summary, palette));
+      output(format, lines.join('\n'));
+    }
+
+    await terminate(summary.failed > 0 || summary.errors > 0 ? 1 : 0);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'unknown error';
+    if (format === 'table') {
+      if (spinnerAdded) removeLastLog();
+      addLog(<ErrorLog message={message} />);
+    } else {
+      process.stderr.write(`Error: ${message}\n`);
+    }
+    await terminate(1);
+  }
+};

package/src/deslop/resolveFiles.ts

@@ -0,0 +1,176 @@
+import { categorizeFilePaths, getMintIgnore } from '@mintlify/prebuild';
+import { execFile } from 'node:child_process';
+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 exists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+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 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 Error(
+      `No matching files for: ${unmatched.join(', ')} (globs match .md and .mdx files)`
+    );
+  }
+
+  return [...new Set(matched)];
+}
+
+function runGit(args: string[], cwd: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile('git', args, { cwd }, (error, stdout) => {
+      if (error) reject(error);
+      else resolve(stdout);
+    });
+  });
+}
+
+function parseGitLines(stdout: string): string[] {
+  return stdout
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+export async function resolveChangedFiles(baseDir: string): Promise<string[]> {
+  try {
+    await runGit(['rev-parse', '--is-inside-work-tree'], baseDir);
+  } catch {
+    throw new Error(
+      'Not a git repository, so changed pages cannot be detected. Pass explicit paths: `mint deslop <files..>`.'
+    );
+  }
+
+  let diff: string;
+  let untracked: string;
+  try {
+    [diff, untracked] = await Promise.all([
+      runGit(['-c', 'core.quotePath=false', 'diff', '--name-only', '--relative', 'HEAD'], baseDir),
+      runGit(['-c', 'core.quotePath=false', 'ls-files', '--others', '--exclude-standard'], baseDir),
+    ]);
+  } catch {
+    throw new Error(
+      'Could not detect changed pages (does the repository have any commits?). Pass explicit paths: `mint deslop <files..>`.'
+    );
+  }
+
+  const candidates = [...new Set([...parseGitLines(diff), ...parseGitLines(untracked)])]
+    .map(normalizeArg)
+    .filter((file) => DOCS_FILE.test(file));
+
+  const existing: string[] = [];
+  for (const file of candidates) {
+    if (await exists(path.join(baseDir, file))) existing.push(file);
+  }
+  if (existing.length === 0) return [];
+
+  if (!(await exists(path.join(baseDir, 'docs.json')))) {
+    return existing;
+  }
+
+  try {
+    const mintIgnore = await getMintIgnore(baseDir);
+    const { contentFilenames } = await categorizeFilePaths(baseDir, mintIgnore);
+    const contentSet = new Set(contentFilenames.map((file) => toPosix(file).replace(/^\//, '')));
+    return existing.filter((file) => contentSet.has(file));
+  } catch {
+    // docs.json is present but its navigation could not be resolved. Fail closed
+    // rather than sending possibly-ignored files to the credit-consuming API.
+    throw new Error(
+      'Could not read docs.json to determine which pages to check. Pass explicit paths: `mint deslop <files..>`.'
+    );
+  }
+}