@mintlify/cli 4.0.1106 → 4.0.1107

package/__test__/init.test.ts

@@ -1,3 +1,6 @@
+import { input, select } from '@inquirer/prompts';
+
+import { isAI } from '../src/helpers.js';
 import { init } from '../src/init.js';
 
 vi.mock('@inquirer/prompts', () => ({
@@ -5,6 +8,10 @@ vi.mock('@inquirer/prompts', () => ({
   input: vi.fn(),
 }));
 
+vi.mock('../src/helpers.js', () => ({
+  isAI: vi.fn().mockReturnValue(false),
+}));
+
 vi.mock('@mintlify/previewing', () => ({
   addLogs: vi.fn(),
   addLog: vi.fn(),
@@ -32,6 +39,7 @@ vi.mock('fs-extra', () => ({
     remove: vi.fn().mockResolvedValue(undefined),
     readJson: vi.fn().mockResolvedValue({ theme: 'quill', name: 'Test' }),
     writeJson: vi.fn().mockResolvedValue(undefined),
+    pathExists: vi.fn().mockResolvedValue(true),
   },
 }));
 
@@ -42,12 +50,19 @@ vi.mock('adm-zip', () => ({
 }));
 
 global.fetch = vi.fn().mockResolvedValue({
+  ok: true,
   arrayBuffer: () => Promise.resolve(new ArrayBuffer(0)),
+  json: () => Promise.resolve([]),
 });
 
 describe('init', () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValue({
+      ok: true,
+      arrayBuffer: () => Promise.resolve(new ArrayBuffer(0)),
+      json: () => Promise.resolve([]),
+    });
   });
 
   describe('path traversal prevention', () => {
@@ -70,18 +85,35 @@ describe('init', () => {
     });
 
     it('allows current directory (.)', async () => {
-      // Should not throw for current directory
       await expect(init('.', false, 'quill', 'Test')).resolves.not.toThrow();
     });
 
     it('allows subdirectory paths', async () => {
-      // Should not throw for subdirectory
       await expect(init('docs', false, 'quill', 'Test')).resolves.not.toThrow();
     });
 
     it('allows nested subdirectory paths', async () => {
-      // Should not throw for nested subdirectory
       await expect(init('docs/api', false, 'quill', 'Test')).resolves.not.toThrow();
     });
   });
+
+  describe('AI agent guard for template without name', () => {
+    it('does not call interactive prompts when AI uses --template without --name', async () => {
+      vi.mocked(isAI).mockReturnValue(true);
+
+      await init('.', false, undefined, undefined, 'some-template');
+
+      expect(input).not.toHaveBeenCalled();
+      expect(select).not.toHaveBeenCalled();
+    });
+
+    it('does not call interactive prompts when AI omits both --template and --theme', async () => {
+      vi.mocked(isAI).mockReturnValue(true);
+
+      await init('.', false, undefined, 'MyProject');
+
+      expect(input).not.toHaveBeenCalled();
+      expect(select).not.toHaveBeenCalled();
+    });
+  });
 });

package/bin/cli.js

@@ -381,14 +381,18 @@ export const cli = ({ packageName = 'mint' }) => {
         .option('name', {
         type: 'string',
         description: 'Name of the documentation project',
+    })
+        .option('template', {
+        type: 'string',
+        description: 'Use a template as a starting point',
     })
         .option('force', {
         type: 'boolean',
         default: false,
         description: 'Create the documentation in a subdirectory',
-    }), (_a) => __awaiter(void 0, [_a], void 0, function* ({ directory, theme, name, force }) {
+    }), (_a) => __awaiter(void 0, [_a], void 0, function* ({ directory, theme, name, force, template }) {
         try {
-            yield init(directory, force, theme, name);
+            yield init(directory, force, theme, name, template);
             yield terminate(0);
         }
         catch (error) {

package/bin/init.js

@@ -15,82 +15,145 @@ import AdmZip from 'adm-zip';
 import fse from 'fs-extra';
 import { Box, Text } from 'ink';
 import { isAI } from './helpers.js';
+import { fetchAvailableTemplates, installFromTemplate, promptForTemplate, validateTemplateName, } from './templates.js';
 const sendOnboardingMessage = (installDir) => {
     addLogs(_jsx(Text, { bold: true, children: "Documentation Setup!" }), _jsx(Text, { children: "To see your docs run" }), _jsxs(Box, { children: [_jsx(Text, { color: "blue", children: "cd" }), _jsxs(Text, { children: [" ", installDir] })] }), _jsx(Text, { color: "blue", children: "mint dev" }));
 };
-const sendUsageMessageForAI = (directory, contentsOccupied, themes) => {
-    addLogs(_jsx(Text, { children: "Agent Detected - sending AI friendly prompt" }), _jsx(Text, { children: '<system-message>' }), _jsx(Text, { children: "Example usage of `mint new [directory] --theme [theme] --name [Name Of Project] --force`." }), _jsx(Text, { children: "This tool will auto create the directory if the directory does not exist." }), _jsx(Text, { children: "Ask the user what mintlify theme to use, what directory, and what the name of the Project is." }), _jsxs(Text, { children: ["You should provide them with default options for these values. Themes available", ' ', JSON.stringify(themes)] }), _jsxs(Text, { children: ["You chose Directory \"", directory, "\" before, feel free to just use that without asking the user as well!"] }), _jsx(Text, { children: "If the user is asking you to create docs for them then you should use your AskQuestion tool" }), contentsOccupied ? (_jsxs(Text, { children: ["The directory ", directory, " specified is currently occupied. You will need to either install the docs as a subdirectory or as a subdirectory or a different directory. Ask the user if it should be installed in a different directory (This cli will create the directory if it doesn't exist, or installed at the root level potentially overridding files (pass the --force) option for this."] })) : undefined, _jsx(Text, { children: '</system-message>' }));
+const sendUsageMessageForAI = (directory, contentsOccupied, themes, templateNames) => {
+    const templateInfo = templateNames === undefined
+        ? 'Unable to fetch templates — use --template flag if you know the name'
+        : templateNames.length > 0
+            ? `Templates: ${JSON.stringify(templateNames)}`
+            : 'No templates are currently available';
+    addLogs(_jsx(Text, { children: "Agent Detected - sending AI friendly prompt" }), _jsx(Text, { children: '<system-message>' }), _jsx(Text, { children: "Help the user set up a Mintlify docs site with `mint new`. Ask each step one at a time unless the user asks you to skip questions or use your best judgment." }), _jsx(Text, { children: [
+            `- [ ] Pick a theme or clone a template? (${templateInfo})`,
+            `- [ ] If template: which one? If theme: which one? (Themes: ${JSON.stringify(themes)})`,
+            '- [ ] Project name?',
+            `- [ ] Directory? (default: "${directory}", auto-created if needed)${contentsOccupied ? ` ⚠️ "${directory}" is occupied — subdirectory, overwrite (--force), or different path?` : ''}`,
+        ].join('\n') }), _jsx(Text, { children: "Command: `mint new [dir] --theme [theme] --name [name]` or `mint new [dir] --template [template] --name [name]`. --theme optionally overrides a template default. --force overwrites non-empty dirs. Use AskQuestion to present choices." }), _jsx(Text, { children: '</system-message>' }));
 };
-export function init(installDir, force, theme, name) {
+function sendAIUsageMessage(directory, contentsOccupied, themes) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const templateNames = yield fetchAvailableTemplates().catch(() => undefined);
+        sendUsageMessageForAI(directory, contentsOccupied, themes, templateNames);
+    });
+}
+function resolveInstallDir(installDir, force, contentsOccupied) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!contentsOccupied)
+            return installDir;
+        if (isAI()) {
+            if (force)
+                return installDir;
+            return undefined;
+        }
+        const choice = yield select({
+            message: `Directory ${installDir} is not empty. What would you like to do?`,
+            choices: [
+                { name: 'Create in a subdirectory', value: 'subdir' },
+                { name: 'Overwrite current directory (may lose contents)', value: 'overwrite' },
+                { name: 'Cancel', value: 'cancel' },
+            ],
+        });
+        if (choice === 'cancel')
+            return undefined;
+        if (choice === 'subdir') {
+            const subdir = yield input({
+                message: 'Subdirectory name:',
+                default: 'docs',
+            });
+            if (!subdir || subdir.trim() === '') {
+                throw new Error('Subdirectory name cannot be empty');
+            }
+            const resolved = installDir === '.' ? subdir : `${installDir}/${subdir}`;
+            validatePathWithinCwd(resolved, process.cwd());
+            return resolved;
+        }
+        return installDir;
+    });
+}
+function promptForProjectName(installDir, currentName) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (currentName)
+            return currentName;
+        const defaultProject = installDir === '.' ? 'Mintlify' : installDir;
+        return input({ message: 'Project Name', default: defaultProject });
+    });
+}
+function promptForApproach() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const approach = yield select({
+            message: 'How would you like to set up your docs?',
+            choices: [
+                { name: 'Pick a theme', value: 'theme' },
+                { name: 'Clone a template', value: 'template' },
+            ],
+        });
+        if (approach === 'template')
+            return promptForTemplate();
+        return undefined;
+    });
+}
+export function init(installDir, force, theme, name, template) {
     return __awaiter(this, void 0, void 0, function* () {
-        // Validate path is within current working directory to prevent path traversal
         validatePathWithinCwd(installDir);
-        let selectedTheme = theme;
-        let projectName = name;
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const themes = docsConfigSchema.options.map((option) => {
             return option.shape.theme._def.value;
         });
         const dirContents = yield fse.readdir(installDir).catch(() => []);
         const contentsOccupied = dirContents.length > 0;
-        if ((!theme || !name) && isAI()) {
-            sendUsageMessageForAI(installDir, contentsOccupied, themes);
+        if (isAI() && (!name || (!template && !theme))) {
+            yield sendAIUsageMessage(installDir, contentsOccupied, themes);
             return;
         }
-        if (contentsOccupied && isAI() && !force) {
-            sendUsageMessageForAI(installDir, contentsOccupied, themes);
+        if (isAI() && contentsOccupied && !force) {
+            yield sendAIUsageMessage(installDir, contentsOccupied, themes);
             return;
         }
-        if (contentsOccupied && !isAI()) {
-            const choice = yield select({
-                message: `Directory ${installDir} is not empty. What would you like to do?`,
-                choices: [
-                    { name: 'Create in a subdirectory', value: 'subdir' },
-                    { name: 'Overwrite current directory (may lose contents)', value: 'overwrite' },
-                    { name: 'Cancel', value: 'cancel' },
-                ],
-            });
-            if (choice === 'cancel') {
+        const selectedTemplate = template
+            ? yield validateTemplateName(template).then(() => template)
+            : !isAI() && !theme
+                ? yield promptForApproach()
+                : undefined;
+        if (selectedTemplate) {
+            const resolved = yield resolveInstallDir(installDir, force, contentsOccupied);
+            if (resolved === undefined) {
+                if (isAI())
+                    yield sendAIUsageMessage(installDir, contentsOccupied, themes);
                 return;
             }
-            if (choice === 'subdir') {
-                const subdir = yield input({
-                    message: 'Subdirectory name:',
-                    default: 'docs',
-                });
-                if (!subdir || subdir.trim() === '') {
-                    throw new Error('Subdirectory name cannot be empty');
-                }
-                installDir = installDir === '.' ? subdir : `${installDir}/${subdir}`;
-                // Re-validate after subdirectory is appended
-                validatePathWithinCwd(installDir, process.cwd());
-            }
+            const projectName = yield promptForProjectName(resolved, name);
+            yield fse.ensureDir(resolved);
+            yield installFromTemplate(resolved, selectedTemplate, projectName, theme);
+            sendOnboardingMessage(resolved);
+            return;
+        }
+        // Standard theme-based path
+        const resolved = yield resolveInstallDir(installDir, force, contentsOccupied);
+        if (resolved === undefined) {
+            if (isAI())
+                yield sendAIUsageMessage(installDir, contentsOccupied, themes);
+            return;
         }
+        let projectName = name;
+        let selectedTheme = theme;
         if (!isAI() && (!selectedTheme || !projectName)) {
-            const defaultProject = projectName !== undefined ? projectName : installDir === '.' ? 'Mintlify' : installDir;
-            if (!projectName) {
-                projectName = yield input({
-                    message: 'Project Name',
-                    default: defaultProject,
-                });
-            }
+            projectName = yield promptForProjectName(resolved, projectName);
             if (!selectedTheme) {
                 selectedTheme = yield select({
                     message: 'Theme',
-                    choices: themes.map((t) => ({
-                        name: t,
-                        value: t,
-                    })),
+                    choices: themes.map((t) => ({ name: t, value: t })),
                 });
             }
         }
         if (projectName === undefined || selectedTheme === undefined) {
-            sendUsageMessageForAI(installDir, contentsOccupied, themes);
+            yield sendAIUsageMessage(resolved, contentsOccupied, themes);
             return;
         }
-        yield fse.ensureDir(installDir);
-        yield install(installDir, projectName, selectedTheme);
-        sendOnboardingMessage(installDir);
+        yield fse.ensureDir(resolved);
+        yield install(resolved, projectName, selectedTheme);
+        sendOnboardingMessage(resolved);
     });
 }
 const install = (installDir, projectName, theme) => __awaiter(void 0, void 0, void 0, function* () {

package/bin/templates.js

@@ -0,0 +1,127 @@
+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 { jsx as _jsx } from "react/jsx-runtime";
+import { select } from '@inquirer/prompts';
+import { addLog, SpinnerLog, removeLastLog } from '@mintlify/previewing';
+import AdmZip from 'adm-zip';
+import fse from 'fs-extra';
+import path from 'path';
+const TEMPLATES_REPO_OWNER = 'mintlify';
+const TEMPLATES_REPO_NAME = 'templates';
+const TEMPLATES_REPO_BRANCH = 'main';
+export function fetchAvailableTemplates() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const url = `https://api.github.com/repos/${TEMPLATES_REPO_OWNER}/${TEMPLATES_REPO_NAME}/contents/?ref=${TEMPLATES_REPO_BRANCH}`;
+        const response = yield fetch(url, {
+            headers: { Accept: 'application/vnd.github.v3+json' },
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch templates: ${response.status} ${response.statusText}`);
+        }
+        const entries = (yield response.json());
+        return entries.filter((entry) => entry.type === 'dir').map((entry) => entry.name);
+    });
+}
+export function validateTemplateName(templateName) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!templateName ||
+            templateName === '.' ||
+            templateName === '..' ||
+            templateName.includes('/')) {
+            throw new Error(`Invalid template name: "${templateName}".`);
+        }
+        const url = `https://api.github.com/repos/${TEMPLATES_REPO_OWNER}/${TEMPLATES_REPO_NAME}/contents/${encodeURIComponent(templateName)}?ref=${TEMPLATES_REPO_BRANCH}`;
+        const response = yield fetch(url, {
+            headers: { Accept: 'application/vnd.github.v3+json' },
+        });
+        if (!response.ok) {
+            const available = yield fetchAvailableTemplates().catch(() => []);
+            const suggestion = available.length > 0 ? ` Available templates: ${available.join(', ')}` : '';
+            throw new Error(`Template "${templateName}" not found in ${TEMPLATES_REPO_OWNER}/${TEMPLATES_REPO_NAME}.${suggestion}`);
+        }
+        const entries = (yield response.json());
+        const hasDocsJson = entries.some((entry) => entry.name === 'docs.json');
+        if (!hasDocsJson) {
+            throw new Error(`Template "${templateName}" is not a valid Mintlify template (missing docs.json).`);
+        }
+        return templateName;
+    });
+}
+export function promptForTemplate() {
+    return __awaiter(this, void 0, void 0, function* () {
+        addLog(_jsx(SpinnerLog, { message: "fetching available templates..." }));
+        let templateNames;
+        try {
+            templateNames = yield fetchAvailableTemplates();
+        }
+        catch (_a) {
+            removeLastLog();
+            throw new Error('Failed to fetch templates. Please check your network connection and try again.');
+        }
+        removeLastLog();
+        if (templateNames.length === 0) {
+            throw new Error('No templates are currently available.');
+        }
+        return select({
+            message: 'Choose a template',
+            choices: templateNames.map((t) => ({ name: t, value: t })),
+        });
+    });
+}
+export function installFromTemplate(installDir, templateName, projectName, theme) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const zipPath = path.join(installDir, '__template__.zip');
+        const extractDir = path.join(installDir, '__template_extract__');
+        try {
+            addLog(_jsx(SpinnerLog, { message: `downloading template "${templateName}"...` }));
+            try {
+                const zipUrl = `https://github.com/${TEMPLATES_REPO_OWNER}/${TEMPLATES_REPO_NAME}/archive/refs/heads/${TEMPLATES_REPO_BRANCH}.zip`;
+                const response = yield fetch(zipUrl);
+                if (!response.ok) {
+                    throw new Error(`Failed to download templates archive: ${response.status}`);
+                }
+                const buffer = yield response.arrayBuffer();
+                yield fse.writeFile(zipPath, Buffer.from(buffer));
+            }
+            finally {
+                removeLastLog();
+            }
+            addLog(_jsx(SpinnerLog, { message: "extracting template..." }));
+            try {
+                const zip = new AdmZip(zipPath);
+                zip.extractAllTo(extractDir, true);
+            }
+            finally {
+                removeLastLog();
+            }
+            const repoRoot = path.join(extractDir, `${TEMPLATES_REPO_NAME}-${TEMPLATES_REPO_BRANCH}`);
+            const templateDir = path.join(repoRoot, templateName);
+            if (!(yield fse.pathExists(templateDir))) {
+                throw new Error(`Template directory "${templateName}" not found in the downloaded archive.`);
+            }
+            yield fse.copy(templateDir, installDir, { overwrite: true });
+        }
+        finally {
+            yield fse.remove(zipPath).catch(() => { });
+            yield fse.remove(extractDir).catch(() => { });
+        }
+        const docsJsonPath = path.join(installDir, 'docs.json');
+        if (yield fse.pathExists(docsJsonPath)) {
+            const docsConfig = yield fse.readJson(docsJsonPath);
+            if (projectName) {
+                docsConfig.name = projectName;
+            }
+            if (theme) {
+                docsConfig.theme = theme;
+            }
+            yield fse.writeJson(docsJsonPath, docsConfig, { spaces: 2 });
+        }
+    });
+}