@mintlify/cli 4.0.1434 → 4.0.1438

package/bin/agent-harness/buildTaskPrompt.js

@@ -0,0 +1,76 @@
+import path from 'node:path';
+export const SYSTEM_PROMPT = `# Mint test generator
+
+You will be provided a markdown page guide that contians codeblocks. Follow the guide and implement
+the code as instrucuted by the guide into a given output directory.
+
+Once finished, create a mint-test.json file in the current working directory with this shape:
+
+{
+  "version": 1,
+  "generatedFiles": ["tests/example.test.js", "tests/test_example.py"],
+  "setupCommands": [],
+  "testCommands": [
+    {
+      "executable": "node",
+      "args": ["--test", "tests/"],
+      "cwd": ".",
+      "timeoutMs": 120000
+    },
+    {
+      "executable": "python3",
+      "args": ["-m", "unittest", "discover", "-s", "tests"],
+      "cwd": ".",
+      "timeoutMs": 120000
+    }
+  ]
+}
+
+Command cwd values must be relative to the current working directory. Finish with a short plain-text summary.
+
+Rules:
+- Read only the page named in the task. You may also read docs.json and an OpenAPI file referenced by that page.
+- The output directory is already scaffolded: package.json exists with "npm test" wired to "node --test tests/", and a tests/ directory is ready. Do not recreate or rewrite this scaffolding.
+- Write JavaScript and TypeScript tests as ES modules named tests/*.test.js using the Node built-in test runner (node:test and node:assert). Write Python tests as tests/test_*.py using the standard library unittest module, run with python3 -m unittest discover -s tests.
+- Prefer the standard library over installing dependencies; add a setup command only when a test truly cannot run without one.
+- Never write README, docs, or explanation files.
+- Keep helpers inline in the test file; do not create separate helper modules.
+- Write one test file per page unless the page genuinely needs more.
+- Create every additional source file and fixture inside the current working directory.
+- Never modify the documentation source. Do not commit, push, or open a pull request.
+- Cover fenced code blocks inside Mintlify components such as CodeGroup, Tabs, Steps, RequestExample, and ResponseExample.
+- If the page has openapi frontmatter, you may resolve its spec relative to the docs root and add tests for request snippets.
+- Do not install dependencies or run the generated tests. The Mint CLI handles setup and execution.
+- Never copy secrets into a file. In your code pull secrets from .env
+`;
+export function buildTaskPrompt(docsRoot, file, directory) {
+    return `
+Use the guide at "${JSON.stringify(path.join(docsRoot, file))}"
+
+Write the required tests and mint-test.json output in the "${JSON.stringify(directory)}" directory.
+Record your report here "${JSON.stringify(file)}"`;
+}
+export const CHECK_SYSTEM_PROMPT = `# Mint test triage
+You are given a markdown page guide. Decide if the given file is able to be tested.
+
+Testable pages are pages that include any runnable code (python, typescript, bash) and any logic that could fail if the documented code was wrong
+
+Code blocks are not testable when it is used for formatting, showing logs, configuration, pseudo-code or a diff, an illustrative request or response shape, or a UI-only example.
+
+When unsure, mark it not testable.
+
+Include "reason" only when the page is not testable; omit it entirely when testable is true.`;
+export const CHECK_TOOL_INSTRUCTION = `
+
+Report your classification by calling the report_testability tool`;
+export const CHECK_JSON_INSTRUCTION = `
+
+Respond with only this JSON object and nothing else:
+{ "version": 1, "testable": false, "reason": "expected output, not runnable code" }`;
+export function buildCheckPrompt(file, fileContnet) {
+    return `Report if the file at filePath ${JSON.stringify(file)} is testable
+
+<file>
+${fileContnet}
+</file>`;
+}

package/bin/agent-harness/discoverCodeBlocks.js

@@ -0,0 +1,101 @@
+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 fs from 'node:fs/promises';
+import path from 'node:path';
+const PAGE_EXTENSIONS = new Set(['.md', '.mdx']);
+const IGNORED_DIRECTORIES = new Set(['.git', '.next', 'build', 'dist', 'node_modules']);
+const OPENING_FENCE_PATTERN = /^\s*(`{3,}|~{3,})/;
+function countFencedBlocks(content) {
+    var _a, _b;
+    const lines = content.split(/\r?\n/);
+    let count = 0;
+    for (let index = 0; index < lines.length; index++) {
+        const opening = OPENING_FENCE_PATTERN.exec((_a = lines[index]) !== null && _a !== void 0 ? _a : '');
+        const marker = opening === null || opening === void 0 ? void 0 : opening[1];
+        if (!marker)
+            continue;
+        const closingPattern = new RegExp(`^\\s*${marker[0]}{${marker.length},}\\s*$`);
+        let closingIndex = index + 1;
+        while (closingIndex < lines.length && !closingPattern.test((_b = lines[closingIndex]) !== null && _b !== void 0 ? _b : '')) {
+            closingIndex++;
+        }
+        if (closingIndex >= lines.length)
+            break;
+        count++;
+        index = closingIndex;
+    }
+    return count;
+}
+function findSiteRoot(startDirectory) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { root } = path.parse(startDirectory);
+        let directory = startDirectory;
+        let previous = null;
+        while (directory !== previous) {
+            for (const configName of ['docs.json', 'mint.json']) {
+                const stats = yield fs.stat(path.join(directory, configName)).catch(() => null);
+                if (stats === null || stats === void 0 ? void 0 : stats.isFile())
+                    return directory;
+            }
+            if (directory === root)
+                return null;
+            previous = directory;
+            directory = path.dirname(directory);
+        }
+        return null;
+    });
+}
+export function discoverCodeBlocks(inputPath) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const resolvedPath = path.resolve(inputPath);
+        const stats = yield fs.stat(resolvedPath);
+        const baseDirectory = stats.isDirectory() ? resolvedPath : path.dirname(resolvedPath);
+        const docsRoot = (_a = (yield findSiteRoot(baseDirectory))) !== null && _a !== void 0 ? _a : baseDirectory;
+        const filePaths = [];
+        if (stats.isDirectory()) {
+            const directories = [resolvedPath];
+            while (directories.length > 0) {
+                const directory = directories.pop();
+                if (!directory)
+                    break;
+                for (const entry of yield fs.readdir(directory, { withFileTypes: true })) {
+                    const entryPath = path.join(directory, entry.name);
+                    if (entry.isDirectory() &&
+                        !IGNORED_DIRECTORIES.has(entry.name) &&
+                        !(entry.name === 'mint-test' && path.basename(directory) === 'tests')) {
+                        directories.push(entryPath);
+                    }
+                    else if (entry.isFile() && PAGE_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
+                        filePaths.push(entryPath);
+                    }
+                }
+            }
+        }
+        else if (stats.isFile() && PAGE_EXTENSIONS.has(path.extname(resolvedPath).toLowerCase())) {
+            filePaths.push(resolvedPath);
+        }
+        else {
+            throw new Error(`Expected a docs directory or an MD/MDX file: ${resolvedPath}`);
+        }
+        const pages = [];
+        for (const filePath of filePaths.sort()) {
+            const content = yield fs.readFile(filePath, 'utf8');
+            const blockCount = countFencedBlocks(content);
+            if (blockCount > 0) {
+                pages.push({
+                    file: path.relative(docsRoot, filePath).split(path.sep).join('/'),
+                    blockCount,
+                });
+            }
+        }
+        return { docsRoot, pages };
+    });
+}

package/bin/agent-harness/executeCodeBlocks.js

@@ -0,0 +1,220 @@
+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 { spawn } from 'node:child_process';
+import path from 'node:path';
+import { mapWithConcurrency } from './mapWithConcurrency.js';
+const MAX_STREAM_BYTES = 128 * 1024;
+const KILL_GRACE_MS = 2000;
+const FAILURE_PRECEDENCE = ['failed', 'cancelled'];
+const SECRET_NAME_PATTERN = /(TOKEN|SECRET|PASSWORD|API_KEY|PRIVATE_KEY|CREDENTIAL)/i;
+function redactSecrets(value) {
+    let redacted = value;
+    const secrets = Object.entries(process.env)
+        .filter(([name, secret]) => SECRET_NAME_PATTERN.test(name) && typeof secret === 'string' && secret.length >= 8)
+        .map(([, secret]) => secret)
+        .sort((left, right) => right.length - left.length);
+    for (const secret of secrets)
+        redacted = redacted.split(secret).join('[REDACTED]');
+    return redacted
+        .replace(/\bBearer\s+[A-Za-z0-9._~+/-]+=*/gi, 'Bearer [REDACTED]')
+        .replace(/\b(?:sk|sess)-[A-Za-z0-9._-]{12,}\b/gi, '[REDACTED]');
+}
+function outputCollector() {
+    let output = '';
+    let bytes = 0;
+    let truncated = false;
+    return {
+        append(chunk) {
+            if (truncated)
+                return;
+            const value = chunk.toString();
+            const remaining = MAX_STREAM_BYTES - bytes;
+            if (Buffer.byteLength(value) <= remaining) {
+                output += value;
+                bytes += Buffer.byteLength(value);
+                return;
+            }
+            output += Buffer.from(value).subarray(0, Math.max(0, remaining)).toString();
+            output += '\n[mint test: output truncated]\n';
+            truncated = true;
+        },
+        value: () => output,
+    };
+}
+function unrunCommandResult(command, phase, cwd, status, error) {
+    return {
+        id: command.id,
+        phase,
+        status,
+        executable: command.executable,
+        args: command.args,
+        cwd,
+        durationMs: 0,
+        exitCode: null,
+        stdout: '',
+        stderr: '',
+        error,
+    };
+}
+function spawnCommand({ command, phase, cwd, timeoutMs, signal, docsRootForCommands, }) {
+    var _a;
+    const startedAt = Date.now();
+    const base = {
+        id: command.id,
+        phase,
+        executable: command.executable,
+        args: command.args,
+        cwd,
+    };
+    const commandTimeoutMs = (_a = command.timeoutMs) !== null && _a !== void 0 ? _a : timeoutMs;
+    return new Promise((resolve) => {
+        const stdout = outputCollector();
+        const stderr = outputCollector();
+        let completed = false;
+        let timedOut = false;
+        let cancelled = false;
+        let forceKillTimer;
+        const child = spawn(command.executable, command.args, {
+            cwd,
+            detached: true,
+            env: Object.assign(Object.assign({}, process.env), { MINT_DOCS_ROOT: docsRootForCommands }),
+            shell: false,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        child.stdout.on('data', stdout.append);
+        child.stderr.on('data', stderr.append);
+        const killTree = (killSignal) => {
+            if (child.pid) {
+                try {
+                    process.kill(-child.pid, killSignal);
+                    return;
+                }
+                catch (_a) {
+                    /* noop */
+                }
+            }
+            child.kill(killSignal);
+        };
+        const kill = () => {
+            killTree('SIGTERM');
+            forceKillTimer = setTimeout(() => killTree('SIGKILL'), KILL_GRACE_MS);
+        };
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            kill();
+        }, commandTimeoutMs);
+        const abort = () => {
+            cancelled = true;
+            kill();
+        };
+        signal.addEventListener('abort', abort, { once: true });
+        const finish = (exitCode, spawnError) => {
+            if (completed)
+                return;
+            completed = true;
+            clearTimeout(timeout);
+            if (forceKillTimer)
+                clearTimeout(forceKillTimer);
+            signal.removeEventListener('abort', abort);
+            const error = cancelled
+                ? 'run cancelled'
+                : timedOut
+                    ? `command timed out after ${commandTimeoutMs}ms`
+                    : spawnError;
+            resolve(Object.assign(Object.assign(Object.assign({}, base), { status: cancelled ? 'cancelled' : exitCode === 0 && !error ? 'passed' : 'failed', durationMs: Date.now() - startedAt, exitCode, stdout: redactSecrets(stdout.value()), stderr: redactSecrets(stderr.value()) }), (error ? { error } : {})));
+        };
+        child.once('error', (error) => finish(null, error.message));
+        child.once('close', (exitCode) => finish(exitCode));
+    });
+}
+export function executeCodeBlocks(_a) {
+    return __awaiter(this, arguments, void 0, function* ({ tasks, docsRoot, concurrency, commandTimeoutMs, signal, onTaskUpdate, }) {
+        return mapWithConcurrency(tasks, concurrency, (task) => __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const base = {
+                id: task.id,
+                agent: task.agent,
+                file: task.file,
+                directory: task.directory,
+                attempts: task.attempts,
+                tokens: task.tokens,
+            };
+            const manifest = task.manifest;
+            if (!manifest) {
+                if (!task.error) {
+                    onTaskUpdate({
+                        id: task.id,
+                        agent: task.agent,
+                        file: task.file,
+                        phase: 'not_testable',
+                        tokens: task.tokens,
+                    });
+                    return Object.assign(Object.assign({}, base), { status: 'passed', commands: [] });
+                }
+                const status = signal.aborted ? 'cancelled' : 'agent_error';
+                onTaskUpdate({
+                    id: task.id,
+                    agent: task.agent,
+                    file: task.file,
+                    phase: status,
+                    tokens: task.tokens,
+                });
+                return Object.assign(Object.assign({}, base), { status, error: task.error, commands: [] });
+            }
+            onTaskUpdate({
+                id: task.id,
+                agent: task.agent,
+                file: task.file,
+                phase: 'running',
+                tokens: task.tokens,
+            });
+            const commands = [];
+            let setupFailure;
+            const run = (command, phase) => __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                const cwd = path.resolve(task.directory, (_a = command.cwd) !== null && _a !== void 0 ? _a : '.');
+                if (signal.aborted) {
+                    return unrunCommandResult(command, phase, cwd, 'cancelled', 'run cancelled');
+                }
+                if (phase === 'test' && setupFailure) {
+                    return unrunCommandResult(command, phase, cwd, setupFailure, `a setup command ${setupFailure === 'cancelled' ? 'was cancelled' : 'failed'}`);
+                }
+                return spawnCommand({
+                    command,
+                    phase,
+                    cwd,
+                    timeoutMs: commandTimeoutMs,
+                    signal,
+                    docsRootForCommands: docsRoot,
+                });
+            });
+            for (const command of manifest.setupCommands) {
+                const result = yield run(command, 'setup');
+                commands.push(result);
+                if (result.status !== 'passed') {
+                    setupFailure = result.status;
+                    break;
+                }
+            }
+            for (const command of manifest.testCommands) {
+                commands.push(yield run(command, 'test'));
+            }
+            const status = (_a = FAILURE_PRECEDENCE.find((candidate) => commands.some((command) => command.status === candidate))) !== null && _a !== void 0 ? _a : 'passed';
+            onTaskUpdate({
+                id: task.id,
+                agent: task.agent,
+                file: task.file,
+                phase: status,
+                tokens: task.tokens,
+            });
+            return Object.assign(Object.assign({}, base), { status, commands });
+        }));
+    });
+}

package/bin/agent-harness/filterSelectedPages.js

@@ -0,0 +1,10 @@
+import path from 'node:path';
+export function filterSelectedPages(pages, selectedFiles) {
+    const selected = new Set(selectedFiles.map((file) => file.split(path.sep).join('/').replace(/^\.\//, '')));
+    const known = new Set(pages.map((page) => page.file));
+    for (const file of selected) {
+        if (!known.has(file))
+            throw new Error(`Selected docs file was not found: ${file}`);
+    }
+    return pages.filter((page) => selected.has(page.file));
+}