@mintlify/cli 4.0.1106 → 4.0.1108

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/cli",
-  "version": "4.0.1106",
+  "version": "4.0.1108",
   "description": "The Mintlify CLI",
   "engines": {
     "node": ">=18.0.0"
@@ -45,10 +45,10 @@
   },
   "dependencies": {
     "@inquirer/prompts": "7.9.0",
-    "@mintlify/common": "1.0.847",
-    "@mintlify/link-rot": "3.0.1022",
-    "@mintlify/prebuild": "1.0.989",
-    "@mintlify/previewing": "4.0.1050",
+    "@mintlify/common": "1.0.848",
+    "@mintlify/link-rot": "3.0.1023",
+    "@mintlify/prebuild": "1.0.990",
+    "@mintlify/previewing": "4.0.1051",
     "@mintlify/validation": "0.1.662",
     "adm-zip": "0.5.16",
     "chalk": "5.2.0",
@@ -93,5 +93,5 @@
     "vitest": "2.1.9",
     "vitest-mock-process": "1.0.4"
   },
-  "gitHead": "a5fa5ad2f666bcf9bce7a795ff2b399fe413ea14"
+  "gitHead": "3a099d71bfdddd6d05b3366dc0ef3f4f85f04f63"
 }

package/src/cli.tsx

@@ -532,14 +532,18 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
               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',
             }),
-        async ({ directory, theme, name, force }) => {
+        async ({ directory, theme, name, force, template }) => {
           try {
-            await init(directory, force, theme, name);
+            await init(directory, force, theme, name, template);
             await terminate(0);
           } catch (error) {
             addLog(

package/src/init.tsx

@@ -6,6 +6,12 @@ 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: string) => {
   addLogs(
@@ -19,129 +25,182 @@ const sendOnboardingMessage = (installDir: string) => {
   );
 };
 
-const sendUsageMessageForAI = (directory: string, contentsOccupied: boolean, themes: string[]) => {
+const sendUsageMessageForAI = (
+  directory: string,
+  contentsOccupied: boolean,
+  themes: string[],
+  templateNames?: string[]
+) => {
+  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(
     <Text>Agent Detected - sending AI friendly prompt</Text>,
     <Text>{'<system-message>'}</Text>,
     <Text>
-      Example usage of `mint new [directory] --theme [theme] --name [Name Of Project] --force`.
-    </Text>,
-    <Text>This tool will auto create the directory if the directory does not exist.</Text>,
-    <Text>
-      Ask the user what mintlify theme to use, what directory, and what the name of the Project is.
+      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.
     </Text>,
     <Text>
-      You should provide them with default options for these values. Themes available{' '}
-      {JSON.stringify(themes)}
+      {[
+        `- [ ] 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')}
     </Text>,
     <Text>
-      You chose Directory "{directory}" before, feel free to just use that without asking the user
-      as well!
+      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.
     </Text>,
-    <Text>
-      If the user is asking you to create docs for them then you should use your AskQuestion tool
-    </Text>,
-    contentsOccupied ? (
-      <Text>
-        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.
-      </Text>
-    ) : undefined,
     <Text>{'</system-message>'}</Text>
   );
 };
 
+async function sendAIUsageMessage(directory: string, contentsOccupied: boolean, themes: string[]) {
+  const templateNames = await fetchAvailableTemplates().catch(() => undefined);
+  sendUsageMessageForAI(directory, contentsOccupied, themes, templateNames);
+}
+
+async function resolveInstallDir(
+  installDir: string,
+  force: boolean,
+  contentsOccupied: boolean
+): Promise<string | undefined> {
+  if (!contentsOccupied) return installDir;
+
+  if (isAI()) {
+    if (force) return installDir;
+    return undefined;
+  }
+
+  const choice = await select({
+    message: `Directory ${installDir} is not empty. What would you like to do?`,
+    choices: [
+      { name: 'Create in a subdirectory', value: 'subdir' as const },
+      { name: 'Overwrite current directory (may lose contents)', value: 'overwrite' as const },
+      { name: 'Cancel', value: 'cancel' as const },
+    ],
+  });
+
+  if (choice === 'cancel') return undefined;
+
+  if (choice === 'subdir') {
+    const subdir = await 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;
+}
+
+async function promptForProjectName(installDir: string, currentName?: string): Promise<string> {
+  if (currentName) return currentName;
+  const defaultProject = installDir === '.' ? 'Mintlify' : installDir;
+  return input({ message: 'Project Name', default: defaultProject });
+}
+
+async function promptForApproach(): Promise<string | undefined> {
+  const approach = await select({
+    message: 'How would you like to set up your docs?',
+    choices: [
+      { name: 'Pick a theme', value: 'theme' as const },
+      { name: 'Clone a template', value: 'template' as const },
+    ],
+  });
+
+  if (approach === 'template') return promptForTemplate();
+  return undefined;
+}
+
 export async function init(
   installDir: string,
   force: boolean,
   theme?: string,
-  name?: string
+  name?: string,
+  template?: string
 ): Promise<void> {
-  // 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: any) => {
-    return option.shape.theme._def.value;
+  const themes: string[] = docsConfigSchema.options.map((option: any) => {
+    return option.shape.theme._def.value as string;
   });
 
-  const dirContents = await fse.readdir(installDir).catch(() => []);
+  const dirContents = await fse.readdir(installDir).catch(() => [] as string[]);
   const contentsOccupied = dirContents.length > 0;
 
-  if ((!theme || !name) && isAI()) {
-    sendUsageMessageForAI(installDir, contentsOccupied, themes);
+  if (isAI() && (!name || (!template && !theme))) {
+    await sendAIUsageMessage(installDir, contentsOccupied, themes);
     return;
   }
 
-  if (contentsOccupied && isAI() && !force) {
-    sendUsageMessageForAI(installDir, contentsOccupied, themes);
+  if (isAI() && contentsOccupied && !force) {
+    await sendAIUsageMessage(installDir, contentsOccupied, themes);
     return;
   }
 
-  if (contentsOccupied && !isAI()) {
-    const choice = await 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' },
-      ],
-    });
+  const selectedTemplate = template
+    ? await validateTemplateName(template).then(() => template)
+    : !isAI() && !theme
+      ? await promptForApproach()
+      : undefined;
 
-    if (choice === 'cancel') {
+  if (selectedTemplate) {
+    const resolved = await resolveInstallDir(installDir, force, contentsOccupied);
+    if (resolved === undefined) {
+      if (isAI()) await sendAIUsageMessage(installDir, contentsOccupied, themes);
       return;
     }
 
-    if (choice === 'subdir') {
-      const subdir = await 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 = await promptForProjectName(resolved, name);
+    await fse.ensureDir(resolved);
+    await installFromTemplate(resolved, selectedTemplate, projectName, theme);
+    sendOnboardingMessage(resolved);
+    return;
   }
 
+  // Standard theme-based path
+  const resolved = await resolveInstallDir(installDir, force, contentsOccupied);
+  if (resolved === undefined) {
+    if (isAI()) await 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 = await input({
-        message: 'Project Name',
-        default: defaultProject,
-      });
-    }
+    projectName = await promptForProjectName(resolved, projectName);
 
     if (!selectedTheme) {
       selectedTheme = await select({
         message: 'Theme',
-        choices: themes.map((t: string) => ({
-          name: t,
-          value: t,
-        })),
+        choices: themes.map((t) => ({ name: t, value: t })),
       });
     }
   }
 
   if (projectName === undefined || selectedTheme === undefined) {
-    sendUsageMessageForAI(installDir, contentsOccupied, themes);
+    await sendAIUsageMessage(resolved, contentsOccupied, themes);
     return;
   }
 
-  await fse.ensureDir(installDir);
-  await install(installDir, projectName, selectedTheme);
-
-  sendOnboardingMessage(installDir);
+  await fse.ensureDir(resolved);
+  await install(resolved, projectName, selectedTheme);
+  sendOnboardingMessage(resolved);
 }
 
 const install = async (installDir: string, projectName: string, theme: string) => {

package/src/templates.tsx

@@ -0,0 +1,143 @@
+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';
+
+interface GitHubContentEntry {
+  name: string;
+  type: 'file' | 'dir';
+  path: string;
+}
+
+export async function fetchAvailableTemplates(): Promise<string[]> {
+  const url = `https://api.github.com/repos/${TEMPLATES_REPO_OWNER}/${TEMPLATES_REPO_NAME}/contents/?ref=${TEMPLATES_REPO_BRANCH}`;
+  const response = await 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: GitHubContentEntry[] = (await response.json()) as GitHubContentEntry[];
+  return entries.filter((entry) => entry.type === 'dir').map((entry) => entry.name);
+}
+
+export async function validateTemplateName(templateName: string): Promise<string> {
+  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 = await fetch(url, {
+    headers: { Accept: 'application/vnd.github.v3+json' },
+  });
+
+  if (!response.ok) {
+    const available = await 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: GitHubContentEntry[] = (await response.json()) as GitHubContentEntry[];
+  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 async function promptForTemplate(): Promise<string> {
+  addLog(<SpinnerLog message="fetching available templates..." />);
+  let templateNames: string[];
+  try {
+    templateNames = await fetchAvailableTemplates();
+  } catch {
+    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 async function installFromTemplate(
+  installDir: string,
+  templateName: string,
+  projectName?: string,
+  theme?: string
+): Promise<void> {
+  const zipPath = path.join(installDir, '__template__.zip');
+  const extractDir = path.join(installDir, '__template_extract__');
+
+  try {
+    addLog(<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 = await fetch(zipUrl);
+      if (!response.ok) {
+        throw new Error(`Failed to download templates archive: ${response.status}`);
+      }
+      const buffer = await response.arrayBuffer();
+      await fse.writeFile(zipPath, Buffer.from(buffer));
+    } finally {
+      removeLastLog();
+    }
+
+    addLog(<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 (!(await fse.pathExists(templateDir))) {
+      throw new Error(`Template directory "${templateName}" not found in the downloaded archive.`);
+    }
+
+    await fse.copy(templateDir, installDir, { overwrite: true });
+  } finally {
+    await fse.remove(zipPath).catch(() => {});
+    await fse.remove(extractDir).catch(() => {});
+  }
+
+  const docsJsonPath = path.join(installDir, 'docs.json');
+  if (await fse.pathExists(docsJsonPath)) {
+    const docsConfig = await fse.readJson(docsJsonPath);
+    if (projectName) {
+      docsConfig.name = projectName;
+    }
+    if (theme) {
+      docsConfig.theme = theme;
+    }
+    await fse.writeJson(docsJsonPath, docsConfig, { spaces: 2 });
+  }
+}