@mintlify/cli 4.0.1762 → 4.0.1764

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/agent-setup-config.js

@@ -0,0 +1,141 @@
+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 { applyEdits, modify, parse } from 'jsonc-parser';
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { parse as parseToml } from 'smol-toml';
+export const ADMIN_MCP_NAME = 'mintlify-admin';
+export const ADMIN_MCP_URL = 'https://mcp.mintlify.com';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readConfig(file) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            return yield fs.readFile(file, 'utf8');
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        }
+    });
+}
+function configPath(agent, options) {
+    var _a;
+    const env = (_a = options.env) !== null && _a !== void 0 ? _a : process.env;
+    if (agent === 'codex') {
+        let directory = path.join(options.cwd, '.codex');
+        if (options.global)
+            directory = env.CODEX_HOME || path.join(options.homeDir, '.codex');
+        return path.join(directory, 'config.toml');
+    }
+    if (agent === 'cursor') {
+        const directory = options.global ? options.homeDir : options.cwd;
+        return path.join(directory, '.cursor', 'mcp.json');
+    }
+    if (options.global) {
+        if (env.CLAUDE_CONFIG_DIR) {
+            throw new Error('CLAUDE_CONFIG_DIR is set. Configure Claude Code with: claude mcp add --scope user --transport http mintlify-admin https://mcp.mintlify.com');
+        }
+        return path.join(options.homeDir, '.claude.json');
+    }
+    return path.join(options.cwd, '.mcp.json');
+}
+export function prepareMcpConfig(agent, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const requestedPath = configPath(agent, options);
+        const file = yield fs.realpath(requestedPath).catch((error) => {
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+                return requestedPath;
+            throw error;
+        });
+        const original = yield readConfig(file);
+        const source = original !== null && original !== void 0 ? original : '';
+        const key = agent === 'codex' ? 'mcp_servers' : 'mcpServers';
+        let config;
+        try {
+            if (agent === 'codex') {
+                config = parseToml(source);
+            }
+            else {
+                const errors = [];
+                config = parse(source || '{}', errors, { allowTrailingComma: true });
+                if (errors.length > 0)
+                    throw new Error('Invalid JSON');
+            }
+        }
+        catch (_a) {
+            throw new Error(`Cannot parse ${file}. Fix its configuration before running setup.`);
+        }
+        if (!isRecord(config))
+            throw new Error(`Expected an object in ${file}.`);
+        const servers = config[key];
+        if (servers !== undefined && !isRecord(servers)) {
+            throw new Error(`Expected ${key} to be an object in ${file}.`);
+        }
+        const existing = servers === null || servers === void 0 ? void 0 : servers[ADMIN_MCP_NAME];
+        if (existing !== undefined) {
+            if (!isRecord(existing) || existing.url !== ADMIN_MCP_URL || existing.command !== undefined) {
+                throw new Error(`${ADMIN_MCP_NAME} already has a different configuration in ${file}. Rename or remove that entry before running setup.`);
+            }
+            if (agent === 'claude-code' && existing.type !== 'http') {
+                throw new Error(`Set type to "http" for ${ADMIN_MCP_NAME} in ${file} before running setup.`);
+            }
+            return { path: file, original, contents: undefined };
+        }
+        const newline = source.includes('\r\n') ? '\r\n' : '\n';
+        let contents;
+        if (agent === 'codex') {
+            contents = `${source}${newline}[mcp_servers.${ADMIN_MCP_NAME}]${newline}url = "${ADMIN_MCP_URL}"${newline}`;
+            try {
+                parseToml(contents);
+            }
+            catch (_b) {
+                throw new Error(`Cannot safely extend ${file}. Add [mcp_servers.${ADMIN_MCP_NAME}] with url = "${ADMIN_MCP_URL}" manually.`);
+            }
+        }
+        else {
+            const server = { url: ADMIN_MCP_URL };
+            if (agent === 'claude-code')
+                server.type = 'http';
+            contents = applyEdits(source || '{}', modify(source || '{}', [key, ADMIN_MCP_NAME], server, {
+                formattingOptions: { insertSpaces: true, tabSize: 2, eol: newline },
+            }));
+            if (!contents.endsWith(newline))
+                contents += newline;
+        }
+        return { path: file, original, contents };
+    });
+}
+export function writeMcpConfig(plan) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if ((yield readConfig(plan.path)) !== plan.original) {
+            throw new Error(`${plan.path} changed during setup. Run setup again to preserve those changes.`);
+        }
+        if (plan.contents === undefined)
+            return;
+        yield fs.mkdir(path.dirname(plan.path), { recursive: true, mode: 0o700 });
+        let mode = 0o600;
+        if (plan.original !== undefined)
+            mode = (yield fs.stat(plan.path)).mode;
+        const temporaryPath = `${plan.path}.${randomUUID()}.tmp`;
+        try {
+            yield fs.writeFile(temporaryPath, plan.contents, { mode, flag: 'wx' });
+            if (plan.original !== undefined)
+                yield fs.chmod(temporaryPath, mode);
+            yield fs.rename(temporaryPath, plan.path);
+        }
+        finally {
+            yield fs.rm(temporaryPath, { force: true });
+        }
+    });
+}

package/bin/agent-setup.js

@@ -0,0 +1,146 @@
+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 { checkbox } from '@inquirer/prompts';
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { stripVTControlCharacters } from 'node:util';
+import { ADMIN_MCP_NAME, ADMIN_MCP_URL, prepareMcpConfig, writeMcpConfig, } from './agent-setup-config.js';
+import { detectAgent } from './agent.js';
+export const SETUP_AGENTS = ['claude-code', 'codex', 'cursor'];
+const AGENT_LABELS = {
+    'claude-code': 'Claude Code',
+    codex: 'Codex',
+    cursor: 'Cursor',
+};
+function isSetupAgent(value) {
+    return SETUP_AGENTS.some((agent) => agent === value);
+}
+function detectedAgents() {
+    const homeDir = os.homedir();
+    const current = detectAgent();
+    return SETUP_AGENTS.filter((agent) => {
+        if (agent === 'codex') {
+            return (current === 'codex_cli' ||
+                existsSync(process.env.CODEX_HOME || path.join(homeDir, '.codex')));
+        }
+        if (agent === 'claude-code') {
+            return (current === 'claude_code' ||
+                existsSync(process.env.CLAUDE_CONFIG_DIR || path.join(homeDir, '.claude')));
+        }
+        return (current === 'cursor' || current === 'cursor-cli' || existsSync(path.join(homeDir, '.cursor')));
+    });
+}
+export function installSkills(agents, global) {
+    const args = [
+        '--yes',
+        'skills@1.7.4',
+        'add',
+        'https://mintlify.com/docs',
+        '--agent',
+        ...agents,
+        '--yes',
+    ];
+    if (global)
+        args.push('--global');
+    return new Promise((resolve, reject) => {
+        const child = spawn('npx', args, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            shell: process.platform === 'win32',
+        });
+        let output = '';
+        const recordOutput = (chunk) => {
+            output = (output + chunk.toString()).slice(-65536);
+        };
+        child.stdout.on('data', (chunk) => {
+            recordOutput(chunk);
+            process.stdout.write(chunk.toString());
+        });
+        child.stderr.on('data', (chunk) => {
+            recordOutput(chunk);
+            process.stderr.write(chunk.toString());
+        });
+        child.on('error', () => reject(new Error('Could not run npx. Install npm and run setup again.')));
+        child.on('close', (code, signal) => {
+            if (code !== 0 || /Failed to install\s+\d+/.test(stripVTControlCharacters(output))) {
+                reject(new Error(`Skills installation failed (${signal !== null && signal !== void 0 ? signal : code}). Review the installer output and run setup again.`));
+            }
+            else {
+                resolve();
+            }
+        });
+    });
+}
+export function setupAgent(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const [major = 0, minor = 0] = process.versions.node.split('.').map(Number);
+        if (major < 22 || (major === 22 && minor < 20)) {
+            throw new Error('mint agent setup requires Node.js 22.20 or later to install skills. Upgrade Node.js and try again.');
+        }
+        const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+        let agents = [];
+        for (const agent of (_a = options.agents) !== null && _a !== void 0 ? _a : []) {
+            if (!isSetupAgent(agent))
+                throw new Error(`Unsupported agent: ${agent}`);
+            if (!agents.includes(agent))
+                agents.push(agent);
+        }
+        if (agents.length === 0) {
+            const detected = detectedAgents();
+            if (!interactive) {
+                agents = detected;
+            }
+            else {
+                agents = yield checkbox({
+                    message: 'Which agents should use Mintlify?',
+                    choices: SETUP_AGENTS.map((agent) => ({
+                        name: AGENT_LABELS[agent],
+                        value: agent,
+                        checked: detected.includes(agent),
+                    })),
+                    required: true,
+                });
+            }
+        }
+        if (agents.length === 0) {
+            throw new Error('No supported agents detected. Pass --agent claude-code, codex, or cursor.');
+        }
+        const location = { cwd: process.cwd(), homeDir: os.homedir(), global: options.global };
+        const plans = yield Promise.all(agents.map((agent) => prepareMcpConfig(agent, location)));
+        const scope = options.global ? 'your user account' : 'this project';
+        process.stdout.write(`Setting up Mintlify skills and Admin MCP for ${scope}.\n`);
+        yield installSkills(agents, options.global);
+        for (const plan of plans) {
+            yield writeMcpConfig(plan);
+            const action = plan.contents === undefined ? 'Already configured' : 'Configured';
+            process.stdout.write(`${action}: ${plan.path}\n`);
+        }
+        process.stdout.write('\nAdmin MCP is configured. Complete OAuth sign-in to grant account and project access:\n');
+        for (const agent of agents) {
+            if (agent === 'codex') {
+                let command = `codex mcp login ${ADMIN_MCP_NAME}`;
+                if (!options.global) {
+                    const config = `mcp_servers.${ADMIN_MCP_NAME}.url='${ADMIN_MCP_URL}'`;
+                    command = `codex -c "${config}" mcp login ${ADMIN_MCP_NAME}`;
+                }
+                process.stdout.write(`  Codex: run ${command}. Trust the project before using its MCP configuration.\n`);
+            }
+            else if (agent === 'claude-code') {
+                process.stdout.write(`  Claude Code: open /mcp and authenticate ${ADMIN_MCP_NAME}. Approve the project server if prompted.\n`);
+            }
+            else {
+                process.stdout.write(`  Cursor: open MCP settings and connect ${ADMIN_MCP_NAME}.\n`);
+            }
+        }
+        process.stdout.write('Setup: https://mintlify.com/docs/ai/mintlify-mcp\n');
+    });
+}

package/bin/cli.js

@@ -16,6 +16,7 @@ import { hideBin } from 'yargs/helpers';
 import { accessibilityCheck } from './accessibilityCheck.js';
 import { addDomain } from './addDomain.js';
 import { claimDeployment, createAgentClaimLink } from './agent-claim.js';
+import { SETUP_AGENTS, setupAgent } from './agent-setup.js';
 import { analyticsBuilder } from './analytics/index.js';
 import { brokenLinksHandler } from './brokenLinks.js';
 import { comingSoon } from './comingSoon.js';
@@ -34,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';
@@ -100,6 +102,35 @@ export const cli = ({ packageName = 'mint' }) => {
         .middleware(checkNodeVersion)
         .middleware(suppressConsoleWarnings)
         .middleware(telemetryMiddleware)
+        .command('agent', 'Set up AI coding agents for Mintlify', (yargs) => yargs
+        .command('setup', 'Install Mintlify skills and configure Admin MCP', (yargs) => yargs
+        .exitProcess(false)
+        .option('agent', {
+        alias: 'a',
+        type: 'string',
+        array: true,
+        choices: SETUP_AGENTS,
+        description: 'Agents to configure (defaults to interactive selection)',
+    })
+        .option('global', {
+        alias: 'g',
+        type: 'boolean',
+        default: false,
+        description: 'Set up agents for your user account instead of this project',
+    })
+        .example('$0 agent setup', 'Choose agents and set up the current project')
+        .example('$0 agent setup --agent codex --global', 'Set up Codex for your user account')
+        .epilog('Requires Node.js 22.20 or later and npm. Admin MCP requires a separate OAuth sign-in in each agent.'), (argv) => __awaiter(void 0, void 0, void 0, function* () {
+        try {
+            yield setupAgent({ agents: argv.agent, global: argv.global });
+            yield terminate(0);
+        }
+        catch (error) {
+            process.stderr.write(`${error instanceof Error ? error.message : 'Agent setup failed.'}\n`);
+            yield terminate(1);
+        }
+    }))
+        .demandCommand(1, 'Run mint agent setup to configure your coding agents.'))
         .command('claim', 'Claim a site created with mint deploy', (yargs) => yargs
         .option('email', { type: 'string', description: 'User email for a claim link' })
         .option('code', {
@@ -653,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));
+});