@mintlify/cli 4.0.1437 → 4.0.1439

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/format.js

@@ -71,7 +71,7 @@ function walk(dir, ignores) {
 }
 export const formatHandler = () => __awaiter(void 0, void 0, void 0, function* () {
     var _a, e_1, _b, _c;
-    const { mdxToPm, pmToMdx } = yield import('./vendor/converter.js');
+    const { mdxToPm, pmToMdx, canonicalPmToMdxOptions } = yield import('./vendor/converter.js');
     const ignores = [...(yield getGitIgnore()), ...(yield getMintIgnore(CMD_EXEC_PATH))];
     let total = 0;
     let changed = 0;
@@ -85,8 +85,20 @@ export const formatHandler = () => __awaiter(void 0, void 0, void 0, function* (
             const relative = path.relative(CMD_EXEC_PATH, file);
             try {
                 const raw = yield fs.readFile(file, 'utf-8');
-                const { doc, frontmatter } = mdxToPm(raw, { singleDollarTextMath: false });
-                const formatted = `${pmToMdx(doc, { frontmatter })}\n`;
+                let formatted = raw;
+                let originalFrontmatterKeys = 0;
+                for (let pass = 0; pass < 3; pass++) {
+                    const { doc, frontmatter } = mdxToPm(formatted, { singleDollarTextMath: false });
+                    if (pass === 0)
+                        originalFrontmatterKeys = Object.keys(frontmatter).length;
+                    const next = `${pmToMdx(doc, Object.assign({ frontmatter }, canonicalPmToMdxOptions))}\n`;
+                    if (next === formatted)
+                        break;
+                    formatted = next;
+                }
+                if (originalFrontmatterKeys > 0 && !formatted.startsWith('---')) {
+                    throw new Error('formatting would remove frontmatter; file left untouched');
+                }
                 if (formatted !== raw) {
                     yield fs.writeFile(file, formatted);
                     changed++;

package/bin/mintTest.js

@@ -7,8 +7,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { DEFAULT_COMMAND_TIMEOUT_MS, DEFAULT_CONCURRENCY, clearRunSave, discoverCodeBlocks, loadRunSave, runCodeTests, } from '@mintlify/agent-harness';
 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';

package/bin/mintTestUi.js

@@ -8,10 +8,10 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { DEFAULT_COMMAND_TIMEOUT_MS, DEFAULT_CONCURRENCY, clearRunSave, runCodeTests, } from '@mintlify/agent-harness';
 import { Box, render, Text, useInput } from 'ink';
 import path from 'node:path';
 import { useEffect, useMemo, useRef, useState } from 'react';
+import { DEFAULT_COMMAND_TIMEOUT_MS, DEFAULT_CONCURRENCY, clearRunSave, runCodeTests, } from './agent-harness/index.js';
 import { toggleScopeSelection, visibleScopeRows } from './mintTestTree.js';
 const HARNESSES = [
     { agent: 'claude', model: 'claude-opus-4-8', label: 'Claude Opus 4.8' },