@mintlify/cli 4.0.1765 → 4.0.1767

package/__test__/instructions.test.ts

@@ -0,0 +1,53 @@
+import {
+  fetchInstructions,
+  instructionsUrl,
+  INSTRUCTIONS_URL,
+  TOPICS,
+} from '../src/instructions.js';
+
+const docsMarkdown = [
+  '> ## Documentation Index',
+  '> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt',
+  '',
+  '> ## Agent Instructions',
+  '> Follow the quickstart.',
+  '',
+  '# Custom domain',
+  '',
+  '> Set up a custom domain.',
+  '',
+  'Body',
+].join('\n');
+
+describe('instructions', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('maps topics to docs page paths', () => {
+    expect(instructionsUrl(['publish'])).toBe(`${INSTRUCTIONS_URL}/publish.md`);
+    expect(instructionsUrl(['publish', 'domain'])).toBe(`${INSTRUCTIONS_URL}/publish/domain.md`);
+  });
+
+  it('lists only topics that map to distinct pages', () => {
+    const urls = TOPICS.map(({ name }) => instructionsUrl(name.split(' ')));
+    expect(new Set(urls).size).toBe(TOPICS.length);
+    expect(TOPICS.every(({ name }) => name.split(' ').length <= 2)).toBe(true);
+  });
+
+  it('returns the page without the docs site preamble', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(new Response(docsMarkdown));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const markdown = await fetchInstructions(['publish', 'domain']);
+
+    expect(fetchMock).toHaveBeenCalledWith(`${INSTRUCTIONS_URL}/publish/domain.md`);
+    expect(markdown).toBe('# Custom domain\n\n> Set up a custom domain.\n\nBody');
+  });
+
+  it('rejects unknown topics', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('', { status: 404 })));
+
+    await expect(fetchInstructions(['nope'])).rejects.toThrow();
+  });
+});

package/bin/cli.js

@@ -30,6 +30,7 @@ import { formatDeployment, prepareAgentDeployment } from './deploy.js';
 import { formatHandler } from './format.js';
 import { checkPort, checkNodeVersion, autoUpgradeIfNeeded, getVersions, isAI, suppressConsoleWarnings, terminate, } from './helpers.js';
 import { init } from './init.js';
+import { fetchInstructions, formatTopics } from './instructions.js';
 import { getAccessToken } from './keyring.js';
 import { login } from './login.js';
 import { logout } from './logout.js';
@@ -471,6 +472,32 @@ export const cli = ({ packageName = 'mint' }) => {
     })
         .example('mint broken-links --files introduction.mdx', 'Check a specific page')
         .example('mint broken-links --files "guides/**/*.mdx"', 'Check pages matching a glob'), (argv) => brokenLinksHandler(argv))
+        .command('instructions [topics..]', 'Print Mintlify workflow instructions for agents', (yargs) => yargs
+        .positional('topics', {
+        type: 'string',
+        array: true,
+        default: [],
+        description: 'Topic and optional subtopic',
+    })
+        .example('mint instructions', 'List topics')
+        .example('mint instructions publish domain', 'Custom domain instructions'), (_a) => __awaiter(void 0, [_a], void 0, function* ({ topics }) {
+        if (topics.length === 0) {
+            process.stdout.write(formatTopics());
+            yield terminate(0);
+            return;
+        }
+        let markdown;
+        try {
+            markdown = yield fetchInstructions(topics);
+        }
+        catch (error) {
+            addLog(_jsx(ErrorLog, { message: error instanceof Error ? error.message : String(error) }));
+            yield terminate(1);
+            return;
+        }
+        yield new Promise((resolve) => process.stdout.write(markdown, () => resolve()));
+        yield terminate(0);
+    }))
         .command('status', 'View current authentication status', () => undefined, () => __awaiter(void 0, void 0, void 0, function* () {
         yield status();
         yield terminate(0);

package/bin/instructions.js

@@ -0,0 +1,101 @@
+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());
+    });
+};
+export const INSTRUCTIONS_URL = 'https://www.mintlify.com/docs/mint-instructions';
+export const TOPICS = [
+    {
+        name: 'overview',
+        when: 'Start here: how Mintlify works and facts agents most often get wrong',
+    },
+    {
+        name: 'new-site',
+        when: 'New docs site, first publish, no account, claim a site, login, no docs.json yet',
+    },
+    {
+        name: 'write',
+        when: 'Before creating a page or writing more than a sentence or two; changelogs',
+    },
+    {
+        name: 'write components',
+        when: 'Adding or changing components: callouts, cards, steps, tabs, accordions, fields',
+    },
+    { name: 'configure', when: 'Changing docs.json: theme, colors, logo, favicon, required fields' },
+    {
+        name: 'configure navigation',
+        when: 'Changing navigation: groups, tabs, anchors, dropdowns, products, versions, languages',
+    },
+    {
+        name: 'configure settings',
+        when: 'navbar, footer, banner, SEO, search, integrations, contextual menu, redirects, 404',
+    },
+    {
+        name: 'configure customization',
+        when: 'Themes, fonts, CSS, JavaScript, or React snippets',
+    },
+    { name: 'api-docs', when: 'API documentation: OpenAPI, AsyncAPI, GraphQL, playground' },
+    {
+        name: 'api-docs sdk',
+        when: 'SDK reference pages, x-codeSamples, oneOf/anyOf, multiple responses, hiding endpoints',
+    },
+    {
+        name: 'publish',
+        when: 'Deploying, "is it live", previews, rollbacks, MCP, llms.txt, skill.md, Markdown export',
+    },
+    {
+        name: 'publish domain',
+        when: 'Custom domain (mint add-domain), /docs subpath, reverse proxy, CSP',
+    },
+    {
+        name: 'publish repo',
+        when: 'Monorepo, multi-repo, GitHub/GitLab/Bitbucket, offline export, self-host',
+    },
+    {
+        name: 'publish analytics',
+        when: 'mint analytics, feedback, search data, analytics integrations',
+    },
+    {
+        name: 'publish assistant',
+        when: 'AI assistant, widget, Assistant.md, skills, narration, own model',
+    },
+    { name: 'access', when: 'Private docs, reader login, user groups, personalization' },
+    { name: 'access team', when: 'Team members, roles, SSO, SCIM, audit logs, session security' },
+    {
+        name: 'automate',
+        when: 'Keep docs in sync with code: agent, Autopilot, automations, Slack, CI',
+    },
+    {
+        name: 'migrate',
+        when: 'Moving docs from Docusaurus, GitBook, ReadMe, Fern, Document360, Confluence, Markdown',
+    },
+    { name: 'troubleshoot', when: 'An error, a failed build or deploy, or the site looks wrong' },
+];
+export const formatTopics = () => {
+    const width = Math.max(...TOPICS.map(({ name }) => name.length)) + 2;
+    return [
+        'Usage: mint instructions <topic> [subtopic]',
+        '',
+        ...TOPICS.map(({ name, when }) => `  ${name.padEnd(width)}${when}`),
+        '',
+    ].join('\n');
+};
+export const instructionsUrl = (topics) => `${INSTRUCTIONS_URL}/${topics.map(encodeURIComponent).join('/')}.md`;
+export const stripDocsPreamble = (markdown) => markdown.replace(/^(?:>.*\n|\s*\n)*/, '');
+export function fetchInstructions(topics) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const url = instructionsUrl(topics);
+        const response = yield fetch(url);
+        if (response.status === 404) {
+            throw new Error(`no instructions for "${topics.join(' ')}". Run \`mint instructions\` to list topics.`);
+        }
+        if (!response.ok) {
+            throw new Error(`failed to fetch ${url}: ${response.status} ${response.statusText}`);
+        }
+        return stripDocsPreamble(yield response.text());
+    });
+}