@mintlify/cli 4.0.1434 → 4.0.1438

package/bin/agent-harness/tasks/checkTestability.js

@@ -0,0 +1,226 @@
+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());
+    });
+};
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import z from 'zod';
+import { buildCheckPrompt, CHECK_JSON_INSTRUCTION, CHECK_SYSTEM_PROMPT, CHECK_TOOL_INSTRUCTION, } from '../buildTaskPrompt.js';
+import { loadClaudeAgentSdk, loadCodexSdk } from '../loadAgentSdk.js';
+import { testCheckSchema, } from '../types.js';
+const CHECK_FILENAME = 'mint-test-check.json';
+const CHECK_MODEL = 'claude-haiku-4-5-20251001';
+function readValidCheck(directory) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            const check = testCheckSchema.parse(JSON.parse(yield fs.readFile(path.join(directory, CHECK_FILENAME), 'utf8')));
+            return validateCheck(check).length === 0 ? check : null;
+        }
+        catch (_a) {
+            return null;
+        }
+    });
+}
+function validateCheck(check) {
+    return !check.testable && !check.reason ? ['Not-testable page needs a reason'] : [];
+}
+function parseJsonReply(reply) {
+    var _a;
+    const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(reply);
+    const raw = (_a = fenced === null || fenced === void 0 ? void 0 : fenced[1]) !== null && _a !== void 0 ? _a : reply;
+    const start = raw.indexOf('{');
+    const end = raw.lastIndexOf('}');
+    if (start === -1 || end === -1)
+        throw new Error('Reply contained no JSON object');
+    return JSON.parse(raw.slice(start, end + 1));
+}
+function runTestabilityCheck(_a) {
+    return __awaiter(this, arguments, void 0, function* ({ file, content, agent, outputPath, signal, }) {
+        const prompt = buildCheckPrompt(file, content);
+        const workingDirectory = path.dirname(outputPath);
+        let tokens = 0;
+        let raw;
+        if (agent === 'claude') {
+            const reply = yield promptClaudeCheck({ prompt, workingDirectory, signal });
+            tokens = reply.tokens;
+            if (reply.captured === null)
+                throw new Error('agent never called report_testability');
+            raw = reply.captured;
+        }
+        else {
+            const reply = yield promptCodex({
+                prompt,
+                systemPrompt: CHECK_SYSTEM_PROMPT + CHECK_JSON_INSTRUCTION,
+                workingDirectory,
+                signal,
+            });
+            tokens = reply.tokens;
+            raw = parseJsonReply(reply.result);
+        }
+        const check = testCheckSchema.parse(raw);
+        const errors = validateCheck(check);
+        if (errors.length > 0)
+            throw new Error(errors.join('\n'));
+        yield fs.writeFile(outputPath, `${JSON.stringify(check, null, 2)}\n`);
+        return { tokens, check };
+    });
+}
+export const checkFileTestability = (task_1, _a) => __awaiter(void 0, [task_1, _a], void 0, function* (task, { onTaskUpdate, signal }) {
+    const emit = (phase, tokens) => onTaskUpdate({
+        id: task.id,
+        agent: task.agent,
+        file: task.file,
+        phase,
+        tokens,
+    });
+    let attempts = 0;
+    let tokens = 0;
+    let lastError = 'run cancelled';
+    let check = yield readValidCheck(task.directory);
+    if (!check) {
+        emit('checking', tokens);
+        const content = yield fs.readFile(path.join(task.docsRoot, task.file), 'utf8');
+        for (let attempt = 1; attempt <= 2 && !signal.aborted && !check; attempt++) {
+            attempts = attempt;
+            try {
+                const reply = yield runTestabilityCheck({
+                    file: task.file,
+                    content,
+                    agent: task.agent,
+                    outputPath: path.join(task.directory, CHECK_FILENAME),
+                    signal,
+                });
+                tokens += reply.tokens;
+                check = reply.check;
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : String(error);
+            }
+        }
+        if (!check) {
+            if (signal.aborted) {
+                emit('cancelled', tokens);
+                return Object.assign(Object.assign({}, task), { attempts, tokens, error: 'run cancelled' });
+            }
+            emit('agent_error', tokens);
+            return Object.assign(Object.assign({}, task), { attempts, tokens, error: lastError });
+        }
+    }
+    if (!check.testable) {
+        emit('not_testable', tokens);
+        return Object.assign(Object.assign({}, task), { attempts, tokens, testable: false });
+    }
+    emit('checked', tokens);
+    return Object.assign(Object.assign({}, task), { attempts, tokens, testable: true });
+});
+function promptClaudeCheck(_a) {
+    return __awaiter(this, arguments, void 0, function* ({ prompt, workingDirectory, signal, }) {
+        var _b, e_1, _c, _d;
+        const { query, tool, createSdkMcpServer } = yield loadClaudeAgentSdk();
+        const abortController = new AbortController();
+        const abort = () => abortController.abort(signal.reason);
+        if (signal.aborted)
+            abort();
+        else
+            signal.addEventListener('abort', abort, { once: true });
+        let captured = null;
+        const server = createSdkMcpServer({
+            name: 'mint-test',
+            tools: [
+                tool('report_testability', 'Report whether the documentation page is testable. Call exactly once.', {
+                    version: z.literal(1),
+                    testable: z.boolean(),
+                    reason: z.string().optional(),
+                }, (input) => __awaiter(this, void 0, void 0, function* () {
+                    captured = input;
+                    return { content: [{ type: 'text', text: 'recorded' }] };
+                })),
+            ],
+        });
+        const session = query({
+            prompt,
+            options: {
+                abortController,
+                allowedTools: ['mcp__mint-test__report_testability'],
+                cwd: workingDirectory,
+                mcpServers: { 'mint-test': server },
+                model: CHECK_MODEL,
+                permissionMode: 'dontAsk',
+                persistSession: false,
+                settingSources: [],
+                strictMcpConfig: true,
+                systemPrompt: CHECK_SYSTEM_PROMPT + CHECK_TOOL_INSTRUCTION,
+                tools: [],
+            },
+        });
+        try {
+            try {
+                for (var _e = true, session_1 = __asyncValues(session), session_1_1; session_1_1 = yield session_1.next(), _b = session_1_1.done, !_b; _e = true) {
+                    _d = session_1_1.value;
+                    _e = false;
+                    const message = _d;
+                    if (message.type !== 'result')
+                        continue;
+                    if (message.subtype !== 'success' || message.is_error) {
+                        const details = message.subtype === 'success' ? message.result : message.errors.join('; ');
+                        throw new Error(details || `Claude stopped with ${message.subtype}`);
+                    }
+                    const usage = message.usage;
+                    return {
+                        tokens: usage.input_tokens +
+                            usage.output_tokens +
+                            usage.cache_creation_input_tokens +
+                            usage.cache_read_input_tokens,
+                        captured,
+                    };
+                }
+            }
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (!_e && !_b && (_c = session_1.return)) yield _c.call(session_1);
+                }
+                finally { if (e_1) throw e_1.error; }
+            }
+            throw new Error('Claude finished without returning a result');
+        }
+        finally {
+            signal.removeEventListener('abort', abort);
+            session.close();
+        }
+    });
+}
+function promptCodex(_a) {
+    return __awaiter(this, arguments, void 0, function* ({ prompt, systemPrompt, workingDirectory, signal, }) {
+        const { Codex } = yield loadCodexSdk();
+        const thread = new Codex().startThread({
+            approvalPolicy: 'never',
+            networkAccessEnabled: true,
+            sandboxMode: 'workspace-write',
+            skipGitRepoCheck: true,
+            workingDirectory,
+        });
+        const result = yield thread.run(`${systemPrompt}\n\n${prompt}`, { signal });
+        const usage = result.usage;
+        const tokens = usage
+            ? usage.input_tokens +
+                usage.cached_input_tokens +
+                usage.cache_write_input_tokens +
+                usage.output_tokens +
+                usage.reasoning_output_tokens
+            : 0;
+        return { tokens, result: result.finalResponse };
+    });
+}

package/bin/agent-harness/types.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+const identifier = z.string().trim().min(1).max(120);
+const commandSchema = z
+    .object({
+    id: identifier,
+    executable: z.string().trim().min(1).max(512),
+    args: z.array(z.string().max(10000)).max(100),
+    cwd: z.string().max(1024).optional(),
+    timeoutMs: z
+        .number()
+        .int()
+        .min(1000)
+        .max(30 * 60 * 1000)
+        .optional(),
+})
+    .strict();
+export const manifestSchema = z
+    .object({
+    version: z.literal(1),
+    generatedFiles: z.array(z.string().min(1).max(1024)).max(1000),
+    setupCommands: z.array(commandSchema).max(50),
+    testCommands: z.array(commandSchema).max(200),
+})
+    .strict();
+export const testCheckSchema = z
+    .object({
+    version: z.literal(1),
+    testable: z.boolean(),
+    reason: z
+        .string()
+        .max(2000)
+        .optional()
+        .transform((value) => ((value === null || value === void 0 ? void 0 : value.trim()) ? value.trim() : undefined)),
+})
+    .strict();

package/bin/cli.js

@@ -31,6 +31,7 @@ import { login } from './login.js';
 import { logout } from './logout.js';
 import { mdxLinter } from './mdxLinter.js';
 import { createTelemetryMiddleware } from './middlewares/telemetryMiddleware.js';
+import { mintTestHandler } from './mintTest.js';
 import { checkOpenApiFile, getOpenApiFilenamesFromDocsConfig } from './openApiCheck.js';
 import { resolveExplicitFiles } from './resolveFiles.js';
 import { scoreHandler } from './score/index.js';
@@ -69,12 +70,15 @@ const showWelcome = (packageName) => __awaiter(void 0, void 0, void 0, function*
     yield terminate(0);
 });
 export const cli = ({ packageName = 'mint' }) => {
-    if (shouldShowWelcome(hideBin(process.argv))) {
+    const commandArguments = hideBin(process.argv);
+    if (shouldShowWelcome(commandArguments)) {
         return showWelcome(packageName);
     }
     const telemetryMiddleware = createTelemetryMiddleware();
-    render(_jsx(Logs, {}));
-    return (yargs(hideBin(process.argv))
+    if (commandArguments.find((argument) => !argument.startsWith('-')) !== 'test') {
+        render(_jsx(Logs, {}));
+    }
+    return (yargs(commandArguments)
         .scriptName(packageName)
         .option('telemetry', {
         type: 'boolean',
@@ -196,6 +200,9 @@ export const cli = ({ packageName = 'mint' }) => {
         const { cli: cliVersion } = getVersions(packageName);
         yield validateBuild(Object.assign(Object.assign({}, argv), { packageName,
             cliVersion }));
+    }))
+        .command('test', 'Test runnable code blocks with a local coding agent', (yargs) => yargs.usage('usage: mint test'), () => __awaiter(void 0, void 0, void 0, function* () {
+        yield mintTestHandler();
     }))
         .command('export', 'Export a static site for air-gapped deployment', (yargs) => yargs
         .option('output', {
@@ -551,7 +558,6 @@ export const cli = ({ packageName = 'mint' }) => {
         .example('mint format', 'format all MDX files in the current directory'), formatHandler)
         // 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))
         .command('mcp', '[Coming soon] MCP server for documentation (run mint mcp to vote)', () => undefined, comingSoon('mcp', packageName))
         // Print the help menu when the user enters an invalid command.
         .strictCommands()

package/bin/mintTest.js

@@ -0,0 +1,96 @@
+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 path from 'node:path';
+import { DEFAULT_COMMAND_TIMEOUT_MS, DEFAULT_CONCURRENCY, clearRunSave, discoverCodeBlocks, loadRunSave, runCodeTests, } from './agent-harness/index.js';
+import { CMD_EXEC_PATH, findDocsRoot, isAI, terminate } from './helpers.js';
+import { getAccessToken } from './keyring.js';
+import { fileInNavPaths, loadDocsNavScope } from './mintTestNav.js';
+import { countReport, formatDuration, runMintTestUi } from './mintTestUi.js';
+import { getCliStatus } from './status.js';
+export function mintTestHandler() {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d;
+        try {
+            const accessToken = yield getAccessToken().catch(() => null);
+            if (!accessToken) {
+                process.stderr.write('not logged in. Run `mint login` to authenticate.\n');
+                yield terminate(1);
+                return;
+            }
+            const cliStatus = yield getCliStatus(accessToken);
+            if ((cliStatus === null || cliStatus === void 0 ? void 0 : cliStatus.org.name.toLowerCase()) !== 'mintlify') {
+                process.stderr.write('mint test is not available for your organization.\n');
+                yield terminate(1);
+                return;
+            }
+            const targetPath = yield findDocsRoot(CMD_EXEC_PATH);
+            const interactive = process.stdin.isTTY === true &&
+                process.stdout.isTTY === true &&
+                !isAI() &&
+                !process.env.CI &&
+                process.env.CLI_TEST_MODE !== 'true';
+            const { docsRoot, pages: discoveredPages } = yield discoverCodeBlocks(targetPath);
+            const scope = yield loadDocsNavScope(docsRoot);
+            const pages = scope
+                ? discoveredPages.filter((page) => fileInNavPaths(page.file, scope.navPaths))
+                : discoveredPages;
+            const autoSelectedFiles = (scope ? pages.filter((page) => fileInNavPaths(page.file, scope.autoSelectedPaths)) : pages).map((page) => page.file);
+            const totalPages = scope ? scope.navPaths.size : pages.length;
+            const outputDirectory = path.join(docsRoot, 'tests', 'mint-test');
+            let save = yield loadRunSave(outputDirectory);
+            if (save) {
+                const known = new Set(pages.map((page) => page.file));
+                const selectedFiles = save.selectedFiles.filter((file) => known.has(file));
+                if (selectedFiles.length === 0) {
+                    yield clearRunSave(outputDirectory);
+                    save = null;
+                }
+                else {
+                    save = Object.assign(Object.assign({}, save), { selectedFiles });
+                }
+            }
+            if (interactive) {
+                const exitCode = yield runMintTestUi({
+                    targetPath,
+                    docsRoot,
+                    pages,
+                    autoSelectedFiles,
+                    totalPages,
+                    save,
+                });
+                yield terminate(exitCode);
+                return;
+            }
+            if (save)
+                process.stdout.write(`resuming run ${save.runId}\n`);
+            const report = yield runCodeTests({
+                path: targetPath,
+                agents: (_a = save === null || save === void 0 ? void 0 : save.agents) !== null && _a !== void 0 ? _a : ['claude'],
+                model: (_b = save === null || save === void 0 ? void 0 : save.model) !== null && _b !== void 0 ? _b : 'claude-opus-4-8',
+                selectedFiles: (_c = save === null || save === void 0 ? void 0 : save.selectedFiles) !== null && _c !== void 0 ? _c : autoSelectedFiles,
+                outputDirectory,
+                runId: (_d = save === null || save === void 0 ? void 0 : save.runId) !== null && _d !== void 0 ? _d : null,
+                concurrency: DEFAULT_CONCURRENCY,
+                commandTimeoutMs: DEFAULT_COMMAND_TIMEOUT_MS,
+                signal: new AbortController().signal,
+                onTaskUpdate: () => { },
+            });
+            const counts = countReport(report.tasks);
+            process.stdout.write(`mint test ${report.status}: ${counts.passed} passed, ${counts.failed} failed, ${counts.agentErrors} agent errors\n`);
+            process.stdout.write(`finished in ${formatDuration(report.durationMs)}\n`);
+            process.stdout.write(`report: ${report.reportPath}\n`);
+            yield terminate(report.status === 'passed' ? 0 : 1);
+        }
+        catch (error) {
+            process.stderr.write(`mint test failed: ${error instanceof Error ? error.message : 'unknown error'}\n`);
+            yield terminate(1);
+        }
+    });
+}

package/bin/mintTestNav.js

@@ -0,0 +1,35 @@
+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 { getAllPathsInDocsNav } from '@mintlify/common';
+import { getConfigObj } from '@mintlify/prebuild';
+export function loadDocsNavScope(docsRoot) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const config = (yield getConfigObj(docsRoot, 'docs').catch(() => null));
+        const navigation = config === null || config === void 0 ? void 0 : config.navigation;
+        if (!navigation)
+            return null;
+        const navPaths = new Set(getAllPathsInDocsNav(navigation));
+        if (navPaths.size === 0)
+            return null;
+        const firstLanguage = 'languages' in navigation ? navigation.languages[0] : null;
+        const autoSelectedPaths = firstLanguage ? new Set(getAllPathsInDocsNav(firstLanguage)) : navPaths;
+        return { navPaths, autoSelectedPaths };
+    });
+}
+export function navCandidatesForFile(file) {
+    const base = file.replace(/\.mdx?$/i, '');
+    const candidates = [base];
+    if (base.endsWith('/index'))
+        candidates.push(base.slice(0, -'/index'.length));
+    return candidates;
+}
+export function fileInNavPaths(file, paths) {
+    return navCandidatesForFile(file).some((candidate) => paths.has(candidate));
+}

package/bin/mintTestTree.js

@@ -0,0 +1,94 @@
+function buildTree(pages) {
+    var _a;
+    const root = { id: 'dir:', kind: 'directory', label: '.', blockCount: 0, children: [] };
+    const directories = new Map([['', root]]);
+    for (const page of pages) {
+        const parts = page.file.split('/');
+        let parent = root;
+        let directoryPath = '';
+        for (const part of parts.slice(0, -1)) {
+            directoryPath = directoryPath ? `${directoryPath}/${part}` : part;
+            let directory = directories.get(directoryPath);
+            if (!directory) {
+                directory = {
+                    id: `dir:${directoryPath}`,
+                    kind: 'directory',
+                    label: part,
+                    blockCount: 0,
+                    children: [],
+                };
+                directories.set(directoryPath, directory);
+                parent.children.push(directory);
+            }
+            parent = directory;
+        }
+        parent.children.push({
+            id: `file:${page.file}`,
+            kind: 'file',
+            label: (_a = parts[parts.length - 1]) !== null && _a !== void 0 ? _a : page.file,
+            file: page.file,
+            blockCount: page.blockCount,
+            children: [],
+        });
+    }
+    const sumBlocks = (node) => {
+        if (node.kind === 'file')
+            return node.blockCount;
+        node.blockCount = node.children.reduce((total, child) => total + sumBlocks(child), 0);
+        return node.blockCount;
+    };
+    sumBlocks(root);
+    const sortChildren = (node) => {
+        node.children.sort((left, right) => {
+            if (left.kind !== right.kind)
+                return left.kind === 'directory' ? -1 : 1;
+            return left.label.localeCompare(right.label);
+        });
+        for (const child of node.children)
+            sortChildren(child);
+    };
+    sortChildren(root);
+    return root;
+}
+function descendantFiles(node) {
+    if (node.kind === 'file')
+        return node.file ? [node.file] : [];
+    return node.children.flatMap(descendantFiles);
+}
+function selectionState(files, selectedFiles) {
+    if (files.length === 0)
+        return 'none';
+    const selectedCount = files.filter((file) => selectedFiles.has(file)).length;
+    if (selectedCount === 0)
+        return 'none';
+    return selectedCount === files.length ? 'all' : 'some';
+}
+export function visibleScopeRows(pages, expandedDirectories, selectedFiles) {
+    const root = buildTree(pages);
+    const rows = [];
+    const visit = (node, depth) => {
+        const files = descendantFiles(node);
+        const expanded = node.kind === 'directory' ? expandedDirectories.has(node.id) : undefined;
+        rows.push(Object.assign(Object.assign(Object.assign({ id: node.id, kind: node.kind, label: node.label, depth }, (node.file ? { file: node.file } : {})), { blockCount: node.blockCount, selectableFiles: files, selection: selectionState(files, selectedFiles) }), (expanded !== undefined ? { expanded } : {})));
+        if (node.kind === 'directory' && expanded) {
+            for (const child of node.children)
+                visit(child, depth + 1);
+        }
+    };
+    for (const child of root.children)
+        visit(child, 0);
+    return rows;
+}
+export function toggleScopeSelection(selectedFiles, row) {
+    const next = new Set(selectedFiles);
+    if (row.selectableFiles.length === 0)
+        return next;
+    const shouldSelect = row.selectableFiles.some((file) => !next.has(file));
+    for (const file of row.selectableFiles) {
+        if (shouldSelect)
+            next.add(file);
+        else
+            next.delete(file);
+    }
+    return next;
+}