@mintlify/cli 4.0.1655 → 4.0.1657

package/src/agent-harness/types.ts

@@ -1,239 +0,0 @@
-import { z } from 'zod';
-
-export type HarnessAgent = 'claude' | 'codex';
-
-export interface DocsPage {
-  file: string;
-  blockCount: number;
-}
-
-export type CommandStatus = 'passed' | 'failed' | 'cancelled';
-
-export interface CommandResult {
-  id: string;
-  phase: 'setup' | 'test';
-  status: CommandStatus;
-  executable: string;
-  args: string[];
-  cwd: string;
-  durationMs: number;
-  exitCode: number | null;
-  stdout: string;
-  stderr: string;
-  error?: string;
-}
-
-export type TaskStatus = 'passed' | 'failed' | 'agent_error' | 'cancelled';
-
-export interface TaskResult {
-  id: string;
-  agent: HarnessAgent;
-  file: string;
-  directory: string;
-  generatedFiles: string[];
-  testable: boolean;
-  attempts: number;
-  tokens: number;
-  status: TaskStatus;
-  error?: string;
-  commands: CommandResult[];
-}
-
-export interface CodeTestReport {
-  version: 1;
-  runId: string;
-  status: 'passed' | 'completed' | 'failed' | 'cancelled';
-  docsRoot: string;
-  outputDirectory: string;
-  reportPath: string;
-  agents: HarnessAgent[];
-  model: string;
-  selectedFiles: string[];
-  startedAt: string;
-  completedAt: string;
-  durationMs: number;
-  tasks: TaskResult[];
-  /** Set when the run finished but could not be saved to `.mintlify/test` history. */
-  historyError?: string;
-}
-
-export interface TestRunSummary {
-  runId: string;
-  status: CodeTestReport['status'];
-  agents: HarnessAgent[];
-  model: string;
-  selectedFiles: string[];
-  startedAt: string;
-  completedAt: string;
-  durationMs: number;
-  reportPath: string;
-  outputDirectory: string;
-  counts: {
-    passed: number;
-    failed: number;
-    cancelled: number;
-    agentErrors: number;
-  };
-}
-
-export interface TestRunsIndex {
-  version: 1;
-  runs: TestRunSummary[];
-}
-
-export type TaskPhase =
-  | 'checking'
-  | 'checked'
-  | 'not_testable'
-  | 'generating'
-  | 'generated'
-  | 'agent_error'
-  | 'running'
-  | 'passed'
-  | 'failed'
-  | 'cancelled';
-
-export interface TaskUpdate {
-  id: string;
-  agent: HarnessAgent;
-  file: string;
-  directory: string;
-  generatedFiles: string[];
-  phase: TaskPhase;
-  tokens: number;
-  /** Why the task ended in `agent_error` or `failed`; the first line is shown in the UI. */
-  error?: string;
-}
-
-export interface TestGenerationResult {
-  status: 'succeeded' | 'failed';
-  agent: HarnessAgent;
-  model: string;
-  attemptCount: number;
-  tokenCount: number;
-  durationMs: number;
-  generatedFileCount: number;
-}
-
-export interface RunSave {
-  version: 1;
-  runId: string;
-  agents: HarnessAgent[];
-  model: string;
-  selectedFiles: string[];
-  createdAt: string;
-}
-
-export interface RunCodeTestsOptions {
-  path: string;
-  agents: HarnessAgent[];
-  model: string;
-  selectedFiles: string[];
-  outputDirectory: string;
-  runId: string | null;
-  concurrency: number;
-  commandTimeoutMs: number;
-  signal: AbortSignal;
-  onTaskUpdate: (update: TaskUpdate) => void;
-  onGenerationResult?: (result: TestGenerationResult) => void;
-}
-
-const identifier = z.string().trim().min(1).max(120);
-
-const commandSchema = z
-  .object({
-    id: identifier.optional(),
-    executable: z.string().trim().min(1).max(512),
-    args: z.array(z.string().max(10_000)).max(100),
-    cwd: z.string().max(1_024).optional(),
-    timeoutMs: z
-      .number()
-      .int()
-      .min(1_000)
-      .max(30 * 60 * 1_000)
-      .optional(),
-  })
-  .strict();
-
-const manifestFileSchema = z
-  .object({
-    version: z.literal(1),
-    generatedFiles: z.array(z.string().min(1).max(1_024)).max(1_000),
-    setupCommands: z.array(commandSchema).max(50),
-    testCommands: z.array(commandSchema).max(200),
-  })
-  .strict();
-
-type ManifestFile = z.infer<typeof manifestFileSchema>;
-type ManifestFileCommand = ManifestFile['testCommands'][number];
-
-export type ManifestCommand = Omit<ManifestFileCommand, 'id'> & { id: string };
-
-export interface GeneratedTestManifest {
-  version: 1;
-  generatedFiles: string[];
-  setupCommands: ManifestCommand[];
-  testCommands: ManifestCommand[];
-}
-
-/**
- * Agents often copy the manifest example verbatim and omit command ids. The id only needs to be
- * unique within the manifest, so assign `setup-N` / `test-N` instead of rejecting the whole page.
- */
-export function assignCommandIds(manifest: ManifestFile): GeneratedTestManifest {
-  const taken = new Set(
-    [...manifest.setupCommands, ...manifest.testCommands]
-      .map((command) => command.id)
-      .filter((id): id is string => id !== undefined)
-  );
-  const withIds = (commands: ManifestFileCommand[], phase: 'setup' | 'test'): ManifestCommand[] => {
-    let next = 1;
-    return commands.map((command) => {
-      if (command.id !== undefined) return { ...command, id: command.id };
-      let id = `${phase}-${next}`;
-      while (taken.has(id)) {
-        next += 1;
-        id = `${phase}-${next}`;
-      }
-      taken.add(id);
-      next += 1;
-      return { ...command, id };
-    });
-  };
-  return {
-    version: manifest.version,
-    generatedFiles: manifest.generatedFiles,
-    setupCommands: withIds(manifest.setupCommands, 'setup'),
-    testCommands: withIds(manifest.testCommands, 'test'),
-  };
-}
-
-export const manifestSchema = manifestFileSchema.transform(assignCommandIds);
-
-export const testCheckSchema = z
-  .object({
-    version: z.literal(1),
-    testable: z.boolean(),
-    reason: z
-      .string()
-      .max(2_000)
-      .optional()
-      .transform((value) => (value?.trim() ? value.trim() : undefined)),
-  })
-  .strict();
-
-export type TestCheck = z.infer<typeof testCheckSchema>;
-
-export interface GeneratedTask {
-  id: string;
-  agent: HarnessAgent;
-  docsRoot: string;
-  file: string;
-  directory: string;
-  attempts: number;
-  tokens: number;
-  testable?: boolean;
-  manifest?: GeneratedTestManifest;
-  generatedFiles?: string[];
-  error?: string;
-}

package/src/mintTest.tsx

@@ -1,138 +0,0 @@
-import path from 'node:path';
-
-import {
-  DEFAULT_COMMAND_TIMEOUT_MS,
-  DEFAULT_CONCURRENCY,
-  clearRunSave,
-  countReport,
-  discoverCodeBlocks,
-  loadLatestTestRun,
-  loadRunSave,
-  runCodeTests,
-  type RunSave,
-} 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 {
-  trackMintTestGenerationResult,
-  trackMintTestRunCompleted,
-  trackMintTestRunStarted,
-} from './mintTestTelemetry.js';
-import { firstLine, taskProblemLabel } from './mintTestText.js';
-import { formatDuration, runMintTestUi } from './mintTestUi.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 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 };
-      }
-    }
-    const lastReport = await loadLatestTestRun(docsRoot);
-
-    if (interactive) {
-      const exitCode = await runMintTestUi({
-        targetPath,
-        docsRoot,
-        pages,
-        autoSelectedFiles,
-        totalPages,
-        save,
-        lastReport,
-      });
-      await terminate(exitCode);
-      return;
-    }
-
-    const agents = save?.agents ?? ['claude'];
-    const model = save?.model ?? 'claude-opus-4-8';
-    const selectedFiles = save?.selectedFiles ?? autoSelectedFiles;
-    const resumed = save !== null;
-    if (save) process.stdout.write(`resuming run ${save.runId}\n`);
-    void trackMintTestRunStarted({
-      mode: 'non_interactive',
-      resumed,
-      agents,
-      model,
-      selectedPageCount: new Set(selectedFiles).size,
-      totalPageCount: totalPages,
-    });
-    const report = await runCodeTests({
-      path: targetPath,
-      agents,
-      model,
-      selectedFiles,
-      outputDirectory,
-      runId: save?.runId ?? null,
-      concurrency: DEFAULT_CONCURRENCY,
-      commandTimeoutMs: DEFAULT_COMMAND_TIMEOUT_MS,
-      signal: new AbortController().signal,
-      onTaskUpdate: () => {},
-      onGenerationResult: (result) => {
-        void trackMintTestGenerationResult({
-          ...result,
-          mode: 'non_interactive',
-          resumed,
-        });
-      },
-    });
-    await trackMintTestRunCompleted(report, {
-      mode: 'non_interactive',
-      resumed,
-      totalPageCount: totalPages,
-    });
-    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`);
-    for (const task of report.tasks) {
-      if (task.status !== 'failed' && task.status !== 'agent_error') continue;
-      const reason = firstLine(task.error);
-      process.stdout.write(
-        `  ✗ ${task.file}: ${taskProblemLabel(task.status)}${reason ? ` (${reason})` : ''}\n`
-      );
-      process.stdout.write(`    output: ${task.directory}\n`);
-    }
-    if (report.historyError) process.stderr.write(`warning: ${report.historyError}\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/mintTestFilePreview.ts

@@ -1,32 +0,0 @@
-import fs from 'node:fs/promises';
-
-export const PREVIEW_BYTE_LIMIT = 64 * 1024;
-
-export type FilePreview = { binary: true } | { binary: false; text: string; truncated: boolean };
-
-export async function readFilePreview(filePath: string): Promise<FilePreview> {
-  const buffer = new Uint8Array(PREVIEW_BYTE_LIMIT + 1);
-  const file = await fs.open(filePath, 'r');
-  let bytesRead = 0;
-
-  try {
-    while (bytesRead < buffer.length) {
-      const result = await file.read(buffer, bytesRead, buffer.length - bytesRead, bytesRead);
-      if (result.bytesRead === 0) break;
-      bytesRead += result.bytesRead;
-    }
-  } finally {
-    await file.close();
-  }
-
-  const contents = buffer.subarray(0, bytesRead);
-  if (contents.includes(0)) return { binary: true };
-
-  return {
-    binary: false,
-    text: new TextDecoder()
-      .decode(contents.subarray(0, PREVIEW_BYTE_LIMIT))
-      .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, '�'),
-    truncated: bytesRead > PREVIEW_BYTE_LIMIT,
-  };
-}

package/src/mintTestNav.ts

@@ -1,31 +0,0 @@
-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/mintTestTelemetry.ts

@@ -1,101 +0,0 @@
-import {
-  countReport,
-  type CodeTestReport,
-  type HarnessAgent,
-  type TestGenerationResult,
-} from './agent-harness/index.js';
-import { trackEvent } from './telemetry/track.js';
-
-export type MintTestMode = 'interactive' | 'non_interactive';
-
-export interface MintTestRunStartedOptions {
-  mode: MintTestMode;
-  resumed: boolean;
-  agents: HarnessAgent[];
-  model: string;
-  selectedPageCount: number;
-  totalPageCount: number;
-}
-
-export interface MintTestRunCompletedOptions {
-  mode: MintTestMode;
-  resumed: boolean;
-  totalPageCount: number;
-}
-
-export interface MintTestGenerationResultOptions extends TestGenerationResult {
-  mode: MintTestMode;
-  resumed: boolean;
-}
-
-export async function trackMintTestRunStarted({
-  mode,
-  resumed,
-  agents,
-  model,
-  selectedPageCount,
-  totalPageCount,
-}: MintTestRunStartedOptions): Promise<void> {
-  await trackEvent('cli.test.started', {
-    mode,
-    resumed,
-    agents,
-    model,
-    selected_page_count: selectedPageCount,
-    total_page_count: totalPageCount,
-  });
-}
-
-export async function trackMintTestRunCompleted(
-  report: CodeTestReport,
-  { mode, resumed, totalPageCount }: MintTestRunCompletedOptions
-): Promise<void> {
-  const counts = countReport(report.tasks);
-  const skippedCheckCount = report.tasks.filter(
-    (task) => !task.testable && task.status === 'passed'
-  ).length;
-  const tokenCount = report.tasks.reduce((total, task) => total + task.tokens, 0);
-  const runnableCheckCount = report.tasks.filter((task) => task.testable).length;
-
-  await trackEvent('cli.test.completed', {
-    mode,
-    resumed,
-    status: report.status,
-    agents: report.agents,
-    model: report.model,
-    selected_page_count: new Set(report.selectedFiles).size,
-    total_page_count: totalPageCount,
-    total_check_count: report.tasks.length,
-    runnable_check_count: runnableCheckCount,
-    passed_check_count: counts.passed - skippedCheckCount,
-    failed_check_count: counts.failed,
-    skipped_check_count: skippedCheckCount,
-    agent_error_check_count: counts.agentErrors,
-    cancelled_check_count: counts.cancelled,
-    token_count: tokenCount,
-    duration_ms: report.durationMs,
-  });
-}
-
-export async function trackMintTestGenerationResult({
-  status,
-  mode,
-  resumed,
-  agent,
-  model,
-  attemptCount,
-  tokenCount,
-  durationMs,
-  generatedFileCount,
-}: MintTestGenerationResultOptions): Promise<void> {
-  await trackEvent(`cli.test.generation.${status}`, {
-    mode,
-    resumed,
-    agent,
-    model,
-    attempt_count: attemptCount,
-    token_count: tokenCount,
-    duration_ms: durationMs,
-    generated_file_count: generatedFileCount,
-  });
-}

package/src/mintTestText.ts

@@ -1,35 +0,0 @@
-export interface FooterSegment {
-  key: string;
-  action: string;
-}
-
-/**
- * Split a footer hint such as `↑/↓/j/k move · Enter exit` into key/action pairs so the key can
- * be rendered bold and the action plain.
- */
-export function footerSegments(text: string): FooterSegment[] {
-  return text
-    .split(' · ')
-    .map((segment) => segment.trim())
-    .filter((segment) => segment.length > 0)
-    .map((segment) => {
-      const split = segment.indexOf(' ');
-      if (split === -1) return { key: segment, action: '' };
-      return { key: segment.slice(0, split), action: segment.slice(split + 1).trim() };
-    });
-}
-
-/** First non-empty line of a multi-line message, trimmed to fit a terminal row. */
-export function firstLine(text: string | undefined, maxLength = 160): string {
-  if (!text) return '';
-  const line = text
-    .split(/\r?\n/)
-    .map((candidate) => candidate.trim())
-    .find((candidate) => candidate.length > 0);
-  if (!line) return '';
-  return line.length > maxLength ? `${line.slice(0, maxLength - 1)}…` : line;
-}
-
-export function taskProblemLabel(status: 'failed' | 'agent_error'): string {
-  return status === 'agent_error' ? 'test could not be generated' : 'tests failed';
-}

package/src/mintTestTree.ts

@@ -1,134 +0,0 @@
-import type { DocsPage } from './agent-harness/index.js';
-
-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;
-}