@mintlify/cli 4.0.1315 → 4.0.1317

package/__test__/deslop/client.test.ts

@@ -0,0 +1,167 @@
+import { checkPage, checkPages } from '../../src/deslop/client.js';
+import type { DeslopCheckedResponse } from '../../src/deslop/types.js';
+
+vi.mock('../../src/keyring.js', () => ({
+  getAccessToken: vi.fn().mockResolvedValue(null),
+  getRefreshToken: vi.fn().mockResolvedValue(null),
+  storeCredentials: vi.fn().mockResolvedValue(undefined),
+}));
+
+const mockFetch = vi.fn();
+global.fetch = mockFetch;
+
+beforeEach(() => {
+  vi.stubEnv('MINTLIFY_SESSION_TOKEN', 'test-token');
+  vi.stubEnv('MINTLIFY_API_URL', 'http://test-server:5000');
+  mockFetch.mockReset();
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+const checked: DeslopCheckedResponse = {
+  path: 'docs/foo.mdx',
+  skipped: null,
+  predictionShort: 'AI',
+  fractionAi: 0.8,
+  fractionAiAssisted: 0.1,
+  fractionHuman: 0.1,
+  windows: [],
+  creditsCharged: 1,
+};
+
+function mockOk(data: unknown) {
+  mockFetch.mockResolvedValueOnce({
+    ok: true,
+    status: 200,
+    json: () => Promise.resolve(data),
+  });
+}
+
+function mockStatus(status: number, body: string) {
+  mockFetch.mockResolvedValueOnce({
+    ok: false,
+    status,
+    statusText: 'Error',
+    text: () => Promise.resolve(body),
+  });
+}
+
+function calledUrl(): URL {
+  const arg = mockFetch.mock.calls[0]![0];
+  return new URL(typeof arg === 'string' ? arg : String(arg));
+}
+
+function calledInit(): RequestInit {
+  return mockFetch.mock.calls[0]![1] as RequestInit;
+}
+
+describe('checkPage auth', () => {
+  it('throws when no session token is set', async () => {
+    vi.stubEnv('MINTLIFY_SESSION_TOKEN', '');
+    await expect(checkPage('docs', 'a.mdx', '# hi')).rejects.toThrow('Not authenticated');
+  });
+
+  it('sends bearer token header', async () => {
+    mockOk(checked);
+    await checkPage('docs', 'a.mdx', '# hi');
+    expect(mockFetch).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({
+        headers: expect.objectContaining({ Authorization: 'Bearer test-token' }),
+      })
+    );
+  });
+});
+
+describe('checkPage request', () => {
+  it('POSTs path and content to the deslop route with the subdomain', async () => {
+    mockOk(checked);
+    const result = await checkPage('docs', 'docs/foo.mdx', '# Hello\n');
+
+    const url = calledUrl();
+    expect(url.pathname).toBe('/api/cli/deslop');
+    expect(url.searchParams.get('subdomain')).toBe('docs');
+    const init = calledInit();
+    expect(init.method).toBe('POST');
+    expect(init.body).toBe(JSON.stringify({ path: 'docs/foo.mdx', content: '# Hello\n' }));
+    expect(init.headers).toMatchObject({ 'Content-Type': 'application/json' });
+    expect(result).toMatchObject({ path: 'docs/foo.mdx', predictionShort: 'AI' });
+  });
+
+  it('maps 402 to an out-of-credits message', async () => {
+    mockStatus(402, '{"error":"insufficient_credits"}');
+    await expect(checkPage('docs', 'a.mdx', 'x')).rejects.toThrow(
+      'Out of AI credits — upgrade or top up in the Mintlify dashboard.'
+    );
+  });
+
+  it('maps 503 to an unavailable message', async () => {
+    mockStatus(503, '{"error":"deslop_unavailable"}');
+    await expect(checkPage('docs', 'a.mdx', 'x')).rejects.toThrow(
+      'Deslop is temporarily unavailable, try again shortly.'
+    );
+  });
+
+  it('throws a generic API error for other failures', async () => {
+    mockStatus(500, 'boom');
+    await expect(checkPage('docs', 'a.mdx', 'x')).rejects.toThrow('API error (500): boom');
+  });
+});
+
+describe('checkPages', () => {
+  it('records a per-file error without aborting the batch', async () => {
+    mockFetch.mockImplementation((_url: string, init: RequestInit) => {
+      const body = JSON.parse(String(init.body)) as { path: string };
+      if (body.path === 'docs/bad.mdx') {
+        return Promise.reject(new Error('socket hang up'));
+      }
+      return Promise.resolve({
+        ok: true,
+        status: 200,
+        json: () => Promise.resolve({ ...checked, path: body.path }),
+      });
+    });
+
+    const pages = [
+      { path: 'docs/a.mdx', content: 'a' },
+      { path: 'docs/bad.mdx', content: 'b' },
+      { path: 'docs/c.mdx', content: 'c' },
+    ];
+    const results = await checkPages('docs', pages);
+
+    expect(results).toHaveLength(3);
+    expect(results[0]).toMatchObject({ file: 'docs/a.mdx', response: { path: 'docs/a.mdx' } });
+    expect(results[1]).toEqual({ file: 'docs/bad.mdx', error: 'socket hang up' });
+    expect(results[2]).toMatchObject({ file: 'docs/c.mdx', response: { path: 'docs/c.mdx' } });
+  });
+
+  it('preserves input order for more pages than the concurrency limit', async () => {
+    mockFetch.mockImplementation((_url: string, init: RequestInit) => {
+      const body = JSON.parse(String(init.body)) as { path: string };
+      const delay = body.path === 'p0.mdx' ? 30 : 1;
+      return new Promise((resolve) =>
+        setTimeout(
+          () =>
+            resolve({
+              ok: true,
+              status: 200,
+              json: () => Promise.resolve({ ...checked, path: body.path }),
+            }),
+          delay
+        )
+      );
+    });
+
+    const pages = Array.from({ length: 9 }, (_, i) => ({ path: `p${i}.mdx`, content: 'x' }));
+    const results = await checkPages('docs', pages);
+
+    expect(results).toHaveLength(9);
+    results.forEach((result, i) => {
+      expect(result.file).toBe(`p${i}.mdx`);
+      expect(result).toMatchObject({ response: { path: `p${i}.mdx` } });
+    });
+    expect(mockFetch).toHaveBeenCalledTimes(9);
+  });
+});

package/__test__/deslop/resolveFiles.test.ts

@@ -0,0 +1,183 @@
+import { categorizeFilePaths } from '@mintlify/prebuild';
+import { execFile } from 'node:child_process';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { resolveChangedFiles, resolveExplicitFiles } from '../../src/deslop/resolveFiles.js';
+
+vi.mock('node:child_process', () => ({ execFile: vi.fn() }));
+
+vi.mock('@mintlify/prebuild', () => ({
+  getMintIgnore: vi.fn().mockResolvedValue([]),
+  categorizeFilePaths: vi.fn().mockResolvedValue({ contentFilenames: [] }),
+}));
+
+const mockExecFile = vi.mocked(execFile);
+const mockCategorize = vi.mocked(categorizeFilePaths);
+
+type GitCallback = (error: Error | null, stdout: string, stderr: string) => void;
+
+function mockGit(outputs: Record<string, string | Error>) {
+  mockExecFile.mockImplementation(((
+    _file: string,
+    args: string[],
+    _options: unknown,
+    callback: GitCallback
+  ) => {
+    const key = args.join(' ');
+    const value = outputs[key];
+    if (value === undefined) {
+      callback(new Error(`unexpected git command: ${key}`), '', '');
+    } else if (value instanceof Error) {
+      callback(value, '', '');
+    } else {
+      callback(null, value, '');
+    }
+  }) as never);
+}
+
+let baseDir: string;
+
+async function writeFixture(rel: string) {
+  const filePath = path.join(baseDir, rel);
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, '# fixture\n');
+}
+
+beforeEach(async () => {
+  baseDir = await fs.mkdtemp(path.join(os.tmpdir(), 'deslop-test-'));
+  mockExecFile.mockReset();
+  mockCategorize.mockClear();
+  mockCategorize.mockResolvedValue({ contentFilenames: [] } as never);
+});
+
+afterEach(async () => {
+  await fs.rm(baseDir, { recursive: true, force: true });
+});
+
+describe('resolveExplicitFiles', () => {
+  it('resolves literal paths', async () => {
+    await writeFixture('docs/a.mdx');
+    await expect(resolveExplicitFiles(baseDir, ['docs/a.mdx'])).resolves.toEqual(['docs/a.mdx']);
+  });
+
+  it('normalizes leading ./', async () => {
+    await writeFixture('docs/a.md');
+    await expect(resolveExplicitFiles(baseDir, ['./docs/a.md'])).resolves.toEqual(['docs/a.md']);
+  });
+
+  it('errors listing paths that matched nothing', async () => {
+    await writeFixture('docs/a.mdx');
+    await expect(
+      resolveExplicitFiles(baseDir, ['docs/a.mdx', 'docs/missing.mdx', 'nope/*.mdx'])
+    ).rejects.toThrow('No matching files for: docs/missing.mdx, nope/*.mdx');
+  });
+
+  it('accepts existing literal paths regardless of extension', async () => {
+    await writeFixture('README.txt');
+    await expect(resolveExplicitFiles(baseDir, ['README.txt'])).resolves.toEqual(['README.txt']);
+  });
+
+  it('rejects a directory passed as a literal path', async () => {
+    await fs.mkdir(path.join(baseDir, 'docs'), { recursive: true });
+    await expect(resolveExplicitFiles(baseDir, ['docs'])).rejects.toThrow('No matching files');
+  });
+
+  it('expands globs recursively and keeps only docs files', async () => {
+    await writeFixture('docs/a.mdx');
+    await writeFixture('docs/nested/deep/b.mdx');
+    await writeFixture('docs/nested/notes.txt');
+    await writeFixture('top.md');
+
+    await expect(resolveExplicitFiles(baseDir, ['docs/**/*.mdx'])).resolves.toEqual([
+      'docs/a.mdx',
+      'docs/nested/deep/b.mdx',
+    ]);
+    await expect(resolveExplicitFiles(baseDir, ['*.md'])).resolves.toEqual(['top.md']);
+  });
+
+  it('dedupes overlapping literal and glob matches', async () => {
+    await writeFixture('docs/a.mdx');
+    await expect(resolveExplicitFiles(baseDir, ['docs/a.mdx', 'docs/*.mdx'])).resolves.toEqual([
+      'docs/a.mdx',
+    ]);
+  });
+});
+
+describe('resolveChangedFiles', () => {
+  it('throws a friendly error outside a git repo', async () => {
+    mockGit({ 'rev-parse --is-inside-work-tree': new Error('not a git repository') });
+    await expect(resolveChangedFiles(baseDir)).rejects.toThrow(
+      'Not a git repository, so changed pages cannot be detected. Pass explicit paths: `mint deslop <files..>`.'
+    );
+  });
+
+  it('unions diff and untracked files, keeping existing docs pages in the content set', async () => {
+    await writeFixture('docs.json');
+    await writeFixture('docs/a.mdx');
+    await writeFixture('docs/b.md');
+    mockGit({
+      'rev-parse --is-inside-work-tree': 'true\n',
+      '-c core.quotePath=false diff --name-only --relative HEAD':
+        'docs/a.mdx\nsrc/code.ts\ndocs/gone.mdx\n',
+      '-c core.quotePath=false ls-files --others --exclude-standard': 'docs/b.md\nREADME.txt\n',
+    });
+    mockCategorize.mockResolvedValue({
+      contentFilenames: ['/docs/a.mdx', 'docs/b.md', '/docs/c.mdx'],
+    } as never);
+
+    await expect(resolveChangedFiles(baseDir)).resolves.toEqual(['docs/a.mdx', 'docs/b.md']);
+  });
+
+  it('skips the content-set filter outside a docs repo', async () => {
+    await writeFixture('README.md');
+    mockGit({
+      'rev-parse --is-inside-work-tree': 'true\n',
+      '-c core.quotePath=false diff --name-only --relative HEAD': 'README.md\nsrc/code.ts\n',
+      '-c core.quotePath=false ls-files --others --exclude-standard': '',
+    });
+
+    await expect(resolveChangedFiles(baseDir)).resolves.toEqual(['README.md']);
+    expect(mockCategorize).not.toHaveBeenCalled();
+  });
+
+  it('excludes changed pages missing from the content set (mintignored)', async () => {
+    await writeFixture('docs.json');
+    await writeFixture('docs/a.mdx');
+    await writeFixture('internal/secret.mdx');
+    mockGit({
+      'rev-parse --is-inside-work-tree': 'true\n',
+      '-c core.quotePath=false diff --name-only --relative HEAD':
+        'docs/a.mdx\ninternal/secret.mdx\n',
+      '-c core.quotePath=false ls-files --others --exclude-standard': '',
+    });
+    mockCategorize.mockResolvedValue({ contentFilenames: ['docs/a.mdx'] } as never);
+
+    await expect(resolveChangedFiles(baseDir)).resolves.toEqual(['docs/a.mdx']);
+  });
+
+  it('fails closed when the content set cannot be resolved in a docs repo', async () => {
+    await writeFixture('docs.json');
+    await writeFixture('docs/a.mdx');
+    mockGit({
+      'rev-parse --is-inside-work-tree': 'true\n',
+      '-c core.quotePath=false diff --name-only --relative HEAD': 'docs/a.mdx\n',
+      '-c core.quotePath=false ls-files --others --exclude-standard': '',
+    });
+    mockCategorize.mockRejectedValue(new Error('bad docs.json'));
+
+    await expect(resolveChangedFiles(baseDir)).rejects.toThrow('Could not read docs.json');
+  });
+
+  it('returns empty without scanning content when nothing changed', async () => {
+    mockGit({
+      'rev-parse --is-inside-work-tree': 'true\n',
+      '-c core.quotePath=false diff --name-only --relative HEAD': 'src/code.ts\n',
+      '-c core.quotePath=false ls-files --others --exclude-standard': '',
+    });
+
+    await expect(resolveChangedFiles(baseDir)).resolves.toEqual([]);
+    expect(mockCategorize).not.toHaveBeenCalled();
+  });
+});

package/__test__/deslop/whitespace.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from 'vitest';
+
+import { normalizeWhitespace, summarizeWhitespace } from '../../src/deslop/whitespace.js';
+
+describe('normalizeWhitespace', () => {
+  it('strips trailing whitespace and collapses blank-line runs', () => {
+    const { fixed, counts } = normalizeWhitespace('Line one.   \n\n\n\n\nLine two.\n');
+    expect(fixed).toBe('Line one.\n\nLine two.\n');
+    expect(counts.trailing).toBe(1);
+    expect(counts.blankRuns).toBe(1);
+  });
+
+  it('replaces unicode spaces and removes zero-width characters in prose', () => {
+    const { fixed, counts } = normalizeWhitespace('Non breaking and zero​width here.\n');
+    expect(fixed).toBe('Non breaking and zerowidth here.\n');
+    expect(counts.unicodeSpaces).toBe(1);
+    expect(counts.zeroWidth).toBe(1);
+  });
+
+  it('collapses internal double spaces but preserves leading indentation', () => {
+    const { fixed } = normalizeWhitespace('  - item  with   gaps\n');
+    expect(fixed).toBe('  - item with gaps\n');
+  });
+
+  it('leaves fenced code blocks byte-for-byte', () => {
+    const input = 'Prose  here.\n\n```js\nconst  x   = 1;   \n\n\n\ny;\n```\n\nMore  prose.\n';
+    const { fixed } = normalizeWhitespace(input);
+    expect(fixed).toContain('const  x   = 1;   \n\n\n\ny;');
+    expect(fixed).toContain('Prose here.');
+    expect(fixed).toContain('More prose.');
+  });
+
+  it('preserves whitespace inside 4+-backtick fences (extended fences)', () => {
+    const input =
+      'Prose  here.\n\n````md\n```js\nconst  x = 1;   \n```\n\n\n\ny;\n````\n\nMore  prose.\n';
+    const { fixed } = normalizeWhitespace(input);
+    expect(fixed).toContain('const  x = 1;   \n```\n\n\n\ny;');
+    expect(fixed).toContain('More prose.');
+  });
+
+  it('leaves YAML frontmatter untouched', () => {
+    const input = '---\ntitle:   Spaced Title\n---\n\nBody  text.\n';
+    const { fixed } = normalizeWhitespace(input);
+    expect(fixed).toContain('title:   Spaced Title');
+    expect(fixed).toContain('Body text.');
+  });
+
+  it('reports no change for already-clean content', () => {
+    const clean = 'A tidy line.\n\nAnother tidy line.\n';
+    const { changed } = normalizeWhitespace(clean);
+    expect(changed).toBe(false);
+  });
+
+  it('preserves inline code spans (no collapse/trim inside backticks)', () => {
+    const { fixed } = normalizeWhitespace('Run `npm  install   x` then relax  now.\n');
+    expect(fixed).toBe('Run `npm  install   x` then relax now.\n');
+  });
+
+  it('strips trailing whitespace on CRLF lines and keeps the CR', () => {
+    const { fixed, counts } = normalizeWhitespace('First line.  \r\nSecond.\r\n');
+    expect(fixed).toBe('First line.\r\nSecond.\r\n');
+    expect(counts.trailing).toBe(1);
+  });
+
+  it('counts collapsed internal spaces so a space-only fix still registers', () => {
+    const { changed, counts } = normalizeWhitespace('one  two   three\n');
+    expect(changed).toBe(true);
+    expect(counts.spaces).toBe(1);
+    expect(summarizeWhitespace(counts)).toContain('collapsed spaces');
+  });
+
+  it('summarizes counts or returns null when clean', () => {
+    expect(
+      summarizeWhitespace({
+        trailing: 2,
+        blankRuns: 0,
+        unicodeSpaces: 0,
+        zeroWidth: 1,
+        spaces: 0,
+        finalNewline: false,
+      })
+    ).toBe('2 trailing, 1 zero-width chars');
+    expect(
+      summarizeWhitespace({
+        trailing: 0,
+        blankRuns: 0,
+        unicodeSpaces: 0,
+        zeroWidth: 0,
+        spaces: 0,
+        finalNewline: false,
+      })
+    ).toBeNull();
+  });
+});

package/bin/cli.js

@@ -20,12 +20,14 @@ 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, checkNodeVersion, autoUpgradeIfNeeded, getVersions, isAI, suppressConsoleWarnings, terminate, } from './helpers.js';
 import { init } from './init.js';
 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';
@@ -490,6 +492,42 @@ export const cli = ({ packageName = 'mint' }) => {
     })
         .example('mint score', 'Run agent readiness checks on your default subdomain')
         .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) => 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'],
+        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', '[Coming soon] AI-powered documentation (run mint ai to vote)', () => undefined, comingSoon('ai', packageName))
         .command('test', '[Coming soon] Test your documentation (run mint test to vote)', () => undefined, comingSoon('test', packageName))

package/bin/deslop/client.js

@@ -0,0 +1,74 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { authenticatedFetch } from '../authenticatedFetch.js';
+import { API_URL } from '../constants.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 function checkPage(subdomain, pagePath, content) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const endpoint = new URL(`${API_URL}/api/cli/deslop`);
+        endpoint.searchParams.set('subdomain', subdomain);
+        const res = yield 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 = yield res.text().catch(() => '');
+            throw new Error(`API error (${res.status}): ${body || res.statusText}`);
+        }
+        return res.json();
+    });
+}
+export function checkPages(subdomain_1, pages_1) {
+    return __awaiter(this, arguments, void 0, function* (subdomain, pages, concurrency = DEFAULT_CONCURRENCY) {
+        const results = new Array(pages.length);
+        let next = 0;
+        let aborted = false;
+        const worker = () => __awaiter(this, void 0, void 0, function* () {
+            while (next < pages.length && !aborted) {
+                const index = next++;
+                const page = pages[index];
+                try {
+                    const response = yield 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;
+                }
+            }
+        });
+        yield 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;
+    });
+}