@mintlify/cli 4.0.1763 → 4.0.1765

package/__test__/migrate.test.ts

@@ -0,0 +1,186 @@
+import { isBuiltInComponent } from '@mintlify/common';
+import { addLog } from '@mintlify/previewing';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { mockProcessExit } from 'vitest-mock-process';
+
+import { windowsCompatibleSpawnOptions } from '../src/helpers.js';
+import {
+  agentArgs,
+  agents,
+  listMigrationDocs,
+  migrateWithAgent,
+  migrationInstructions,
+} from '../src/migrate.js';
+import { runCommand } from './utils.js';
+
+vi.mock('node:child_process', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('node:child_process')>()),
+  spawn: vi.fn(),
+}));
+vi.mock('@mintlify/previewing', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('@mintlify/previewing')>()),
+  addLog: vi.fn(),
+}));
+
+const spawnMock = vi.mocked(spawn);
+const child = (emit: (child: EventEmitter) => void) => {
+  spawnMock.mockImplementationOnce(() => {
+    const proc = new EventEmitter();
+    setImmediate(() => emit(proc));
+    return proc as ChildProcess;
+  });
+};
+const enoent = (proc: EventEmitter) =>
+  proc.emit('error', Object.assign(new Error('spawn ENOENT'), { code: 'ENOENT' }));
+
+const root = path.join(__dirname, '../migrate');
+const names = (section: string) =>
+  readdirSync(path.join(root, section))
+    .filter((file) => file.endsWith('.md'))
+    .map((file) => file.slice(0, -3));
+const read = (...segments: string[]) => readFileSync(path.join(root, ...segments), 'utf8');
+const docs = [
+  'index.md',
+  ...names('topics').map((name) => `topics/${name}.md`),
+  ...names('sources').map((name) => `sources/${name}.md`),
+];
+const prose = (markdown: string) => markdown.replace(/^(`{3,}).*\n[\s\S]*?^\1\s*$/gm, '');
+
+const template = [
+  '## Detect',
+  '## Get the source',
+  '### From the repo',
+  '### From an export',
+  '### From the live site',
+  '## Config → docs.json',
+  '## Navigation',
+  '## Content conversion',
+  '## Assets',
+  '## URLs and redirects',
+  '## Known gaps',
+];
+
+const components = (text: string) => [...text.matchAll(/<([A-Z][\w.]+)/g)].map(([, name]) => name!);
+const targets = (markdown: string) =>
+  prose(markdown)
+    .split('\n')
+    .flatMap((line) =>
+      line.startsWith('|')
+        ? [line.split('|').slice(1)]
+        : line.split(/[;.] /).map((clause) => clause.split('→'))
+    )
+    .flatMap(([source = '', ...rest]) =>
+      components(rest.join(' ')).filter((name) => !components(source).includes(name))
+    );
+
+const exit = mockProcessExit();
+
+describe('migrate', () => {
+  it('lists topics and sources from disk', () => {
+    expect(listMigrationDocs('topics')).toEqual(names('topics').sort());
+    expect(listMigrationDocs('sources')).toEqual(names('sources').sort());
+    expect(listMigrationDocs('sources')).toContain('nuxt');
+  });
+
+  it('prints the overview with every topic and source', () => {
+    const output = migrationInstructions({});
+    expect(output.startsWith(read('index.md').trimEnd())).toBe(true);
+    expect(output).toContain(`Topics: ${names('topics').sort().join(', ')}.`);
+    expect(output).toContain(`Sources: ${names('sources').sort().join(', ')}.`);
+  });
+
+  it('appends the source guide to the overview', () => {
+    const output = migrationInstructions({ from: 'nuxt' });
+    expect(output.startsWith(read('index.md').trimEnd())).toBe(true);
+    expect(output.endsWith(read('sources', 'nuxt.md'))).toBe(true);
+  });
+
+  it('prints only the topic', () => {
+    expect(migrationInstructions({ topic: 'verify' })).toBe(read('topics', 'verify.md'));
+  });
+
+  it.each(names('sources'))('source %s follows the template', (name) => {
+    const headings = prose(read('sources', `${name}.md`)).match(/^#{1,3} .*/gm) ?? [];
+    expect(headings[0]).toMatch(/^# \S/);
+    expect(headings.slice(1)).toEqual(template);
+  });
+
+  it.each(docs)('%s references only existing topics and sources', (doc) => {
+    for (const [, flag, name] of read(doc).matchAll(/--(topic|from) ([a-z][\w-]*)/g)) {
+      expect(names(flag === 'topic' ? 'topics' : 'sources'), `${doc}: --${flag} ${name}`).toContain(
+        name
+      );
+    }
+  });
+
+  it.each(docs)('%s maps only to Mintlify components', (doc) => {
+    expect(targets(read(doc)).filter((name) => !isBuiltInComponent(name))).toEqual([]);
+  });
+
+  it('rejects unknown values with the valid choices', async () => {
+    const stderr = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    await runCommand('migrate', '--from', 'nope').catch(() => undefined);
+    const output = stderr.mock.calls.map(([chunk]) => String(chunk)).join('');
+    expect(output).toContain('nope');
+    expect(output).toContain('nuxt');
+    stderr.mockRestore();
+  });
+
+  it('offers every agent as an --agent choice', async () => {
+    const stderr = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    await runCommand('migrate', '--agent', 'nope').catch(() => undefined);
+    const output = stderr.mock.calls.map(([chunk]) => String(chunk)).join('');
+    expect(output).toContain(
+      `Choices: ${Object.keys(agents)
+        .map((name) => `"${name}"`)
+        .join(', ')}`
+    );
+    stderr.mockRestore();
+  });
+
+  const base = 'Migrate a documentation site to Mintlify in the current directory. Run';
+  const plain = `${base} \`mint migrate\` and follow the instructions it prints.`;
+  const nuxt = `${base} \`mint migrate --from nuxt\` and follow the instructions it prints.`;
+
+  it.each([
+    ['claude', [plain], [nuxt]],
+    ['codex', [plain], [nuxt]],
+    ['cursor', [plain], [nuxt]],
+    ['gemini', ['-i', plain], ['-i', nuxt]],
+  ] as const)('%s builds its argv', (name, without, withFrom) => {
+    expect(agentArgs(name)).toEqual(without);
+    expect(agentArgs(name, 'nuxt')).toEqual(withFrom);
+  });
+
+  it('--claude runs claude', async () => {
+    child((proc) => proc.emit('close', 0));
+    await runCommand('migrate', '--claude', '--from', 'nuxt');
+    expect(spawnMock).toHaveBeenCalledWith(
+      'claude',
+      [windowsCompatibleSpawnOptions.shell ? `"${nuxt}"` : nuxt],
+      expect.objectContaining({ stdio: 'inherit' })
+    );
+    expect(exit).toHaveBeenCalledWith(0);
+  });
+
+  it('rejects a missing binary with its install command', async () => {
+    child(enoent);
+    await expect(migrateWithAgent('gemini')).rejects.toThrow(
+      `gemini not found. Install it with: ${agents.gemini.install}`
+    );
+  });
+
+  it('prints the install command and exits nonzero for a missing binary', async () => {
+    child(enoent);
+    await runCommand('migrate', '--agent', 'cursor');
+    expect(vi.mocked(addLog)).toHaveBeenCalledWith(
+      expect.objectContaining({
+        props: { message: `cursor-agent not found. Install it with: ${agents.cursor.install}` },
+      })
+    );
+    expect(exit).toHaveBeenCalledWith(1);
+  });
+});

package/__test__/validateRules.test.ts

@@ -838,6 +838,42 @@ describe('validate rules', () => {
     expect(hasErrors(result.issues)).toBe(true);
   });
 
+  it('suggests escaping a < that cannot start a tag', async () => {
+    write(dir, {
+      'index.mdx': '---\ntitle: Home\n---\n\nLatency is <5ms.\n',
+      'end.mdx': '---\ntitle: End\n---\n\nThe last one <\n',
+    });
+
+    const { issues } = await check(dir, {});
+
+    expect(issues.map(({ file, line, column, message }) => [file, line, column, message])).toEqual([
+      [
+        'end.mdx',
+        5,
+        15,
+        "Unexpected end of file before name, expected a character that can start a name, such as a letter, `$`, or `_`; if this < isn't a tag, escape it as \\< (other checks were skipped for this file)",
+      ],
+      [
+        'index.mdx',
+        5,
+        13,
+        "Unexpected character `5` (U+0035) before name, expected a character that can start a name, such as a letter, `$`, or `_`; if this < isn't a tag, escape it as \\< (other checks were skipped for this file)",
+      ],
+    ]);
+  });
+
+  it('does not suggest escaping < for other parse errors', async () => {
+    write(dir, {
+      'index.mdx': '---\ntitle: Home\n---\n\nReturns a List<String>.\n',
+      'math.mdx': '---\ntitle: Math\n---\n\nTotal {1 <}\n',
+    });
+
+    const { issues } = await check(dir, {});
+
+    expect(issues.map(({ rule }) => rule)).toEqual(['parse-error', 'parse-error']);
+    for (const { message } of issues) expect(message).not.toContain('escape it');
+  });
+
   it('still runs parse-error when --rules picks only other rules', async () => {
     write(dir, { 'index.mdx': '---\ntitle: Home\n---\n\n<Note>\nunclosed\n' });
 

package/bin/cli.js

@@ -35,6 +35,7 @@ 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, } from './migrate.js';
 import { ogCommand } from './og.js';
 import { buildOverlayRegistryForCheck, checkOpenApiFile } from './openApiCheck.js';
 import { scoreHandler } from './score/index.js';
@@ -683,6 +684,40 @@ export const cli = ({ packageName = 'mint' }) => {
         .command('format', 'Format MDX files in the current directory', (yargs) => yargs
         .usage('usage: mint format')
         .example('mint format', 'format all MDX files in the current directory'), formatHandler)
+        .command('migrate', 'Print instructions for migrating a docs site to Mintlify', (yargs) => 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),
+        description: 'Run the migration with a coding agent',
+    })
+        .option('claude', {
+        type: 'boolean',
+        description: 'Alias for --agent claude',
+    }), (argv) => __awaiter(void 0, void 0, void 0, function* () {
+        var _a;
+        const agent = (_a = argv.agent) !== null && _a !== void 0 ? _a : (argv.claude ? 'claude' : undefined);
+        if (agent) {
+            try {
+                return yield terminate(yield migrateWithAgent(agent, argv.from));
+            }
+            catch (error) {
+                addLog(_jsx(ErrorLog, { message: error instanceof Error ? error.message : String(error) }));
+                return yield terminate(1);
+            }
+        }
+        yield new Promise((resolve) => process.stdout.write(migrationInstructions(argv), () => resolve()));
+        yield terminate(0);
+    }))
         // Coming soon commands — visible in help, tracked via telemetry to gauge interest.
         .command('ai', '[Coming soon] AI-powered documentation (run mint ai to vote)', () => undefined, comingSoon('ai', packageName))
         .command('mcp', '[Coming soon] MCP server for documentation (run mint mcp to vote)', () => undefined, comingSoon('mcp', packageName))

package/bin/migrate.js

@@ -0,0 +1,54 @@
+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';
+const root = fileURLToPath(new URL('../migrate', import.meta.url));
+const read = (...segments) => readFileSync(path.join(root, ...segments), 'utf8');
+export const listMigrationDocs = (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 }) => {
+    if (topic)
+        return read('topics', `${topic}.md`);
+    if (from)
+        return `${overview()}\n\n${read('sources', `${from}.md`)}`;
+    return `${overview()}\n`;
+};
+const prompt = (from) => `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) => [prompt],
+        install: 'npm install -g @anthropic-ai/claude-code',
+    },
+    codex: {
+        bin: 'codex',
+        args: (prompt) => [prompt],
+        install: 'npm install -g @openai/codex',
+    },
+    cursor: {
+        bin: 'cursor-agent',
+        args: (prompt) => [prompt],
+        install: 'curl https://cursor.com/install -fsS | bash',
+    },
+    gemini: {
+        bin: 'gemini',
+        args: (prompt) => ['-i', prompt],
+        install: 'npm install -g @google/gemini-cli',
+    },
+};
+export const agentArgs = (name, from) => agents[name].args(prompt(from));
+export const migrateWithAgent = (name, from) => 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, Object.assign({ stdio: 'inherit' }, windowsCompatibleSpawnOptions));
+    child.on('error', (error) => reject(error.code === 'ENOENT' ? new Error(`${bin} not found. Install it with: ${install}`) : error));
+    child.on('close', (code) => resolve(code !== null && code !== void 0 ? code : 1));
+});