@mintlify/cli 4.0.1434 → 4.0.1437

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/cli",
-  "version": "4.0.1434",
+  "version": "4.0.1437",
   "description": "The Mintlify CLI",
   "engines": {
     "node": ">=18.0.0"
@@ -45,12 +45,13 @@
   },
   "dependencies": {
     "@inquirer/prompts": "7.9.0",
-    "@mintlify/common": "1.0.1110",
-    "@mintlify/link-rot": "3.0.1312",
-    "@mintlify/models": "0.0.350",
-    "@mintlify/prebuild": "1.0.1264",
-    "@mintlify/previewing": "4.0.1336",
-    "@mintlify/validation": "0.1.841",
+    "@mintlify/agent-harness": "0.0.3",
+    "@mintlify/common": "1.0.1111",
+    "@mintlify/link-rot": "3.0.1313",
+    "@mintlify/models": "0.0.351",
+    "@mintlify/prebuild": "1.0.1265",
+    "@mintlify/previewing": "4.0.1337",
+    "@mintlify/validation": "0.1.842",
     "adm-zip": "0.6.0",
     "chalk": "5.2.0",
     "color": "4.2.3",
@@ -82,7 +83,7 @@
     "keytar": "7.9.0"
   },
   "devDependencies": {
-    "@mintlify/editor": "0.0.327",
+    "@mintlify/editor": "0.0.328",
     "@mintlify/ts-config": "2.0.2",
     "@tsconfig/recommended": "1.0.2",
     "@types/detect-port": "1.3.2",
@@ -101,5 +102,5 @@
     "vitest": "2.1.9",
     "vitest-mock-process": "1.0.4"
   },
-  "gitHead": "5cb92d6b0de80a8e282e3db6157961e56e1952a4"
+  "gitHead": "246494b8852335337e48cd0518b54abb2fb3f774"
 }

package/src/cli.tsx

@@ -44,6 +44,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';
@@ -85,15 +86,18 @@ const showWelcome = async (packageName: string): Promise<void> => {
 };
 
 export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
-  if (shouldShowWelcome(hideBin(process.argv))) {
+  const commandArguments = hideBin(process.argv);
+  if (shouldShowWelcome(commandArguments)) {
     return showWelcome(packageName);
   }
 
   const telemetryMiddleware = createTelemetryMiddleware();
-  render(<Logs />);
+  if (commandArguments.find((argument) => !argument.startsWith('-')) !== 'test') {
+    render(<Logs />);
+  }
 
   return (
-    yargs(hideBin(process.argv))
+    yargs(commandArguments)
       .scriptName(packageName)
       .option('telemetry', {
         type: 'boolean',
@@ -239,6 +243,14 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
           });
         }
       )
+      .command(
+        'test',
+        'Test runnable code blocks with a local coding agent',
+        (yargs) => yargs.usage('usage: mint test'),
+        async () => {
+          await mintTestHandler();
+        }
+      )
       .command(
         'export',
         'Export a static site for air-gapped deployment',
@@ -762,12 +774,6 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
         () => 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)',

package/src/mintTest.tsx

@@ -0,0 +1,102 @@
+import {
+  DEFAULT_COMMAND_TIMEOUT_MS,
+  DEFAULT_CONCURRENCY,
+  clearRunSave,
+  discoverCodeBlocks,
+  loadRunSave,
+  runCodeTests,
+  type RunSave,
+} from '@mintlify/agent-harness';
+import path from 'node:path';
+
+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 async function mintTestHandler(): Promise<void> {
+  try {
+    const accessToken = await getAccessToken().catch(() => null);
+    if (!accessToken) {
+      process.stderr.write('not logged in. Run `mint login` to authenticate.\n');
+      await terminate(1);
+      return;
+    }
+    const cliStatus = await getCliStatus(accessToken);
+    if (cliStatus?.org.name.toLowerCase() !== 'mintlify') {
+      process.stderr.write('mint test is not available for your organization.\n');
+      await terminate(1);
+      return;
+    }
+    const targetPath = await 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 } = await discoverCodeBlocks(targetPath);
+    const scope = await 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: RunSave | null = await 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) {
+        await clearRunSave(outputDirectory);
+        save = null;
+      } else {
+        save = { ...save, selectedFiles };
+      }
+    }
+
+    if (interactive) {
+      const exitCode = await runMintTestUi({
+        targetPath,
+        docsRoot,
+        pages,
+        autoSelectedFiles,
+        totalPages,
+        save,
+      });
+      await terminate(exitCode);
+      return;
+    }
+
+    if (save) process.stdout.write(`resuming run ${save.runId}\n`);
+    const report = await runCodeTests({
+      path: targetPath,
+      agents: save?.agents ?? ['claude'],
+      model: save?.model ?? 'claude-opus-4-8',
+      selectedFiles: save?.selectedFiles ?? autoSelectedFiles,
+      outputDirectory,
+      runId: save?.runId ?? 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`);
+    await terminate(report.status === 'passed' ? 0 : 1);
+  } catch (error) {
+    process.stderr.write(
+      `mint test failed: ${error instanceof Error ? error.message : 'unknown error'}\n`
+    );
+    await terminate(1);
+  }
+}

package/src/mintTestNav.ts

@@ -0,0 +1,31 @@
+import { getAllPathsInDocsNav } from '@mintlify/common';
+import { getConfigObj } from '@mintlify/prebuild';
+import type { DocsConfig, NavigationConfig } from '@mintlify/validation';
+
+export interface DocsNavScope {
+  navPaths: Set<string>;
+  autoSelectedPaths: Set<string>;
+}
+
+export async function loadDocsNavScope(docsRoot: string): Promise<DocsNavScope | null> {
+  const config = (await getConfigObj(docsRoot, 'docs').catch(() => null)) as DocsConfig | null;
+  const navigation = 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] as NavigationConfig | undefined) : null;
+  const autoSelectedPaths = firstLanguage ? new Set(getAllPathsInDocsNav(firstLanguage)) : navPaths;
+  return { navPaths, autoSelectedPaths };
+}
+
+export function navCandidatesForFile(file: string): string[] {
+  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: string, paths: Set<string>): boolean {
+  return navCandidatesForFile(file).some((candidate) => paths.has(candidate));
+}

package/src/mintTestTree.ts

@@ -0,0 +1,134 @@
+import type { DocsPage } from '@mintlify/agent-harness';
+
+export type ScopeSelectionState = 'all' | 'some' | 'none';
+
+export interface ScopeTreeRow {
+  id: string;
+  kind: 'directory' | 'file';
+  label: string;
+  depth: number;
+  file?: string;
+  blockCount: number;
+  selectableFiles: string[];
+  selection: ScopeSelectionState;
+  expanded?: boolean;
+}
+
+interface TreeNode {
+  id: string;
+  kind: 'directory' | 'file';
+  label: string;
+  file?: string;
+  blockCount: number;
+  children: TreeNode[];
+}
+
+function buildTree(pages: DocsPage[]): TreeNode {
+  const root: TreeNode = { id: 'dir:', kind: 'directory', label: '.', blockCount: 0, children: [] };
+  const directories = new Map<string, TreeNode>([['', 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: parts[parts.length - 1] ?? page.file,
+      file: page.file,
+      blockCount: page.blockCount,
+      children: [],
+    });
+  }
+
+  const sumBlocks = (node: TreeNode): number => {
+    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: TreeNode): void => {
+    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: TreeNode): string[] {
+  if (node.kind === 'file') return node.file ? [node.file] : [];
+  return node.children.flatMap(descendantFiles);
+}
+
+function selectionState(files: string[], selectedFiles: ReadonlySet<string>): ScopeSelectionState {
+  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: DocsPage[],
+  expandedDirectories: ReadonlySet<string>,
+  selectedFiles: ReadonlySet<string>
+): ScopeTreeRow[] {
+  const root = buildTree(pages);
+  const rows: ScopeTreeRow[] = [];
+
+  const visit = (node: TreeNode, depth: number) => {
+    const files = descendantFiles(node);
+    const expanded = node.kind === 'directory' ? expandedDirectories.has(node.id) : undefined;
+    rows.push({
+      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: ReadonlySet<string>,
+  row: ScopeTreeRow
+): Set<string> {
+  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;
+}