@mintlify/cli 4.0.1763 → 4.0.1765

package/src/cli.tsx

@@ -42,6 +42,13 @@ import { login } from './login.js';
 import { logout } from './logout.js';
 import { mdxLinter } from './mdxLinter.js';
 import { createTelemetryMiddleware } from './middlewares/telemetryMiddleware.js';
+import {
+  agents,
+  listMigrationDocs,
+  migrateWithAgent,
+  migrationInstructions,
+  type AgentName,
+} from './migrate.js';
 import { ogCommand } from './og.js';
 import { buildOverlayRegistryForCheck, checkOpenApiFile } from './openApiCheck.js';
 import { scoreHandler } from './score/index.js';
@@ -930,6 +937,46 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
             .example('mint format', 'format all MDX files in the current directory'),
         formatHandler
       )
+      .command(
+        'migrate',
+        'Print instructions for migrating a docs site to Mintlify',
+        (yargs: Argv) =>
+          yargs
+            .option('from', {
+              type: 'string',
+              choices: listMigrationDocs('sources'),
+              description: 'Include instructions for a source platform',
+            })
+            .option('topic', {
+              type: 'string',
+              choices: listMigrationDocs('topics'),
+              description: 'Print a single topic',
+            })
+            .option('agent', {
+              type: 'string',
+              choices: Object.keys(agents) as AgentName[],
+              description: 'Run the migration with a coding agent',
+            })
+            .option('claude', {
+              type: 'boolean',
+              description: 'Alias for --agent claude',
+            }),
+        async (argv) => {
+          const agent = argv.agent ?? (argv.claude ? 'claude' : undefined);
+          if (agent) {
+            try {
+              return await terminate(await migrateWithAgent(agent, argv.from));
+            } catch (error) {
+              addLog(<ErrorLog message={error instanceof Error ? error.message : String(error)} />);
+              return await terminate(1);
+            }
+          }
+          await new Promise<void>((resolve) =>
+            process.stdout.write(migrationInstructions(argv), () => resolve())
+          );
+          await terminate(0);
+        }
+      )
       // Coming soon commands — visible in help, tracked via telemetry to gauge interest.
       .command(
         'ai',

package/src/migrate.ts

@@ -0,0 +1,76 @@
+import { spawn } from 'node:child_process';
+import { readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { windowsCompatibleSpawnOptions } from './helpers.js';
+
+type Section = 'topics' | 'sources';
+
+const root = fileURLToPath(new URL('../migrate', import.meta.url));
+
+const read = (...segments: string[]) => readFileSync(path.join(root, ...segments), 'utf8');
+
+export const listMigrationDocs = (section: Section) =>
+  readdirSync(path.join(root, section))
+    .filter((file) => file.endsWith('.md'))
+    .map((file) => file.slice(0, -3))
+    .sort();
+
+const overview = () =>
+  [
+    read('index.md').trimEnd(),
+    `Topics: ${listMigrationDocs('topics').join(', ')}. Run \`mint migrate --topic <name>\`.`,
+    `Sources: ${listMigrationDocs('sources').join(', ')}. Run \`mint migrate --from <name>\`.`,
+  ].join('\n\n');
+
+export const migrationInstructions = ({ from, topic }: { from?: string; topic?: string }) => {
+  if (topic) return read('topics', `${topic}.md`);
+  if (from) return `${overview()}\n\n${read('sources', `${from}.md`)}`;
+  return `${overview()}\n`;
+};
+
+const prompt = (from?: string) =>
+  `Migrate a documentation site to Mintlify in the current directory. Run \`mint migrate${from ? ` --from ${from}` : ''}\` and follow the instructions it prints.`;
+
+export const agents = {
+  claude: {
+    bin: 'claude',
+    args: (prompt: string) => [prompt],
+    install: 'npm install -g @anthropic-ai/claude-code',
+  },
+  codex: {
+    bin: 'codex',
+    args: (prompt: string) => [prompt],
+    install: 'npm install -g @openai/codex',
+  },
+  cursor: {
+    bin: 'cursor-agent',
+    args: (prompt: string) => [prompt],
+    install: 'curl https://cursor.com/install -fsS | bash',
+  },
+  gemini: {
+    bin: 'gemini',
+    args: (prompt: string) => ['-i', prompt],
+    install: 'npm install -g @google/gemini-cli',
+  },
+};
+
+export type AgentName = keyof typeof agents;
+
+export const agentArgs = (name: AgentName, from?: string) => agents[name].args(prompt(from));
+
+export const migrateWithAgent = (name: AgentName, from?: string): Promise<number> =>
+  new Promise((resolve, reject) => {
+    const { bin, install } = agents[name];
+    const args = agentArgs(name, from).map((arg) =>
+      windowsCompatibleSpawnOptions.shell ? `"${arg}"` : arg
+    );
+    const child = spawn(bin, args, { stdio: 'inherit', ...windowsCompatibleSpawnOptions });
+    child.on('error', (error: NodeJS.ErrnoException) =>
+      reject(
+        error.code === 'ENOENT' ? new Error(`${bin} not found. Install it with: ${install}`) : error
+      )
+    );
+    child.on('close', (code) => resolve(code ?? 1));
+  });

package/src/validate/files.ts

@@ -13,6 +13,7 @@ import {
   parseContent,
   relocate,
   selectEdits,
+  toOffset,
   unmapEdit,
 } from './mdx.js';
 import { PARSE_ERROR } from './rules/parseError.js';
@@ -56,16 +57,35 @@ const readFrontmatter = (content: string): Record<string, unknown> => {
 type ParseError = { line?: number; column?: number; message: string };
 
 const REASON_POSITION = /\s*\(\d+:\d+(?:-\d+:\d+)?\)$/;
+const TAG_NAME_RULES = new Set(['unexpected-character', 'unexpected-eof']);
+const ESCAPE_HINT = "; if this < isn't a tag, escape it as \\<";
 
-export const toParseError = (error: unknown): ParseError => {
+const isStrayLessThan = (
+  error: unknown,
+  content: string,
+  position: { line?: number; column?: number } | null
+) => {
+  const { source, ruleId } = (error ?? {}) as { source?: unknown; ruleId?: unknown };
+  return (
+    source === 'micromark-extension-mdx-jsx' &&
+    typeof ruleId === 'string' &&
+    TAG_NAME_RULES.has(ruleId) &&
+    position?.line != null &&
+    position.column != null &&
+    content[toOffset(content, position.line, position.column) - 1] === '<'
+  );
+};
+
+export const toParseError = (error: unknown, content = ''): ParseError => {
   const reason = (error as { reason?: unknown } | null)?.reason;
   const fallback = error instanceof Error ? error.message : 'could not parse this file';
   const text = typeof reason === 'string' ? reason : fallback;
   const position = error && typeof error === 'object' ? getErrorPosition(error) : null;
+  const hint = isStrayLessThan(error, content, position) ? ESCAPE_HINT : '';
   return {
     ...(position?.line != null && { line: position.line }),
     ...(position?.column != null && { column: position.column }),
-    message: text.replace(REASON_POSITION, ''),
+    message: text.replace(REASON_POSITION, '') + hint,
   };
 };
 
@@ -102,7 +122,7 @@ export const parseFile = (
   try {
     return { context: { ...context, tree: getAST(content, file) }, approximate: true };
   } catch (error) {
-    return { error: toParseError(error) };
+    return { error: toParseError(error, content) };
   }
 };
 

package/src/validate/mdx.ts

@@ -186,7 +186,7 @@ export const applyEdits = (content: string, edits: Edit[]): string =>
     content
   );
 
-const toOffset = (content: string, line: number, column = 1) => {
+export const toOffset = (content: string, line: number, column = 1) => {
   let offset = 0;
   for (let current = 1; current < line; current++) {
     const next = content.indexOf('\n', offset);