@mintlify/cli 4.0.1725 → 4.0.1726

package/bin/deploy-github-setup.js

@@ -0,0 +1,165 @@
+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 { execFile } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+import { trustGithubRepo } from './agent-deployment.js';
+import { CLAIM_INSTRUCTIONS } from './deploy-instructions.js';
+import { agentSiteUrl, prepareAgentDeployment } from './deploy.js';
+const githubRepoSchema = z.object({
+    id: z.number().int().positive(),
+    full_name: z.string().regex(/^[\w.-]+\/[\w.-]+$/),
+    default_branch: z.string().min(1),
+});
+export const GITHUB_WORKFLOW_PATH = path.join('.github', 'workflows', 'mintlify.yml');
+function run(command, args, cwd) {
+    return new Promise((resolve, reject) => {
+        execFile(command, args, { cwd }, (error, stdout) => error ? reject(error) : resolve(String(stdout).trim()));
+    });
+}
+export function parseGithubRemote(remote) {
+    const match = remote
+        .trim()
+        .match(/^(?:https:\/\/(?:[^@/]+@)?github\.com\/|ssh:\/\/git@github\.com(?::\d+)?\/|git@github\.com:)([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/);
+    return (match === null || match === void 0 ? void 0 : match[1]) && match[2] ? { owner: match[1], repo: match[2] } : null;
+}
+export function githubWorkflow(branch, subdomain, docsPath = '') {
+    const directory = /^[\w./-]+$/.test(docsPath) ? docsPath : JSON.stringify(docsPath);
+    return [
+        'name: Deploy to Mintlify',
+        'on:',
+        '  push:',
+        `    branches: [${JSON.stringify(branch)}]`,
+        ...(docsPath
+            ? [`    paths: [${JSON.stringify(`${docsPath}/**`)}, ".github/workflows/mintlify.yml"]`]
+            : []),
+        'permissions:',
+        '  id-token: write',
+        '  contents: read',
+        'concurrency:',
+        '  group: mintlify-deploy',
+        '  cancel-in-progress: true',
+        'jobs:',
+        '  deploy:',
+        '    runs-on: ubuntu-latest',
+        '    steps:',
+        '      - uses: actions/checkout@v4',
+        `      - run: npx mint@latest deploy --subdomain ${subdomain}${docsPath ? ` --directory ${directory}` : ''}`,
+        '',
+    ].join('\n');
+}
+function readFileIfExists(file) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return fs.readFile(file, 'utf8').catch((error) => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+    });
+}
+export function writeGithubWorkflow(root_1, contents_1) {
+    return __awaiter(this, arguments, void 0, function* (root, contents, force = false) {
+        const file = path.join(root, GITHUB_WORKFLOW_PATH);
+        const existing = yield readFileIfExists(file);
+        if (existing === contents)
+            return 'unchanged';
+        if (existing !== undefined && !force) {
+            throw new Error(`${GITHUB_WORKFLOW_PATH} already exists with different contents. Pass --force to overwrite it.`);
+        }
+        yield fs.mkdir(path.dirname(file), { recursive: true });
+        yield fs.writeFile(file, contents);
+        return existing === undefined ? 'created' : 'updated';
+    });
+}
+export function findGitRoot(directory) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            return yield run('git', ['rev-parse', '--show-toplevel'], directory);
+        }
+        catch (_a) {
+            throw new Error('--github requires a Git repository. Run it inside your docs repository.');
+        }
+    });
+}
+export function resolveGithubRepo(root) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const remote = yield run('git', ['remote', 'get-url', 'origin'], root).catch(() => {
+            throw new Error('This repository has no origin remote. Add a github.com origin and retry.');
+        });
+        const parsed = parseGithubRemote(remote);
+        if (!parsed)
+            throw new Error(`The origin remote (${remote}) is not a github.com repository.`);
+        const output = yield run('gh', [
+            'api',
+            `repos/${parsed.owner}/${parsed.repo}`,
+            '--jq',
+            '{id: .id, full_name: .full_name, default_branch: .default_branch}',
+        ], root).catch((error) => {
+            if (error.code === 'ENOENT')
+                throw new Error('The GitHub CLI (gh) is required. Install it and run `gh auth login`.');
+            throw new Error(`Could not read ${parsed.owner}/${parsed.repo} with gh. Run \`gh auth login\` with access to the repository and retry.`);
+        });
+        try {
+            return githubRepoSchema.parse(JSON.parse(output));
+        }
+        catch (_a) {
+            throw new Error('gh returned an unexpected repository response.');
+        }
+    });
+}
+export function setupGithubDeployment(options_1, warn_1) {
+    return __awaiter(this, arguments, void 0, function* (options, warn, progress = () => { }) {
+        const directory = path.resolve(options.directory);
+        const root = yield findGitRoot(directory);
+        const [realRoot, realDirectory] = yield Promise.all([fs.realpath(root), fs.realpath(directory)]);
+        const docsPath = path.relative(realRoot, realDirectory).split(path.sep).join('/');
+        if (!(yield readFileIfExists(path.join(directory, 'docs.json')))) {
+            throw new Error(`No docs.json in ${directory}. Pass the docs folder with --directory.`);
+        }
+        progress('Resolving the GitHub repository...');
+        const repo = yield resolveGithubRepo(root);
+        const result = yield prepareAgentDeployment(options, warn, progress);
+        if (result.status === 'claimed') {
+            throw new Error('This site has been claimed. Setting up GitHub deploys for claimed sites is not supported yet; connect the repository from the Mintlify dashboard.');
+        }
+        const accessToken = result.credentials.accessToken;
+        if (!accessToken)
+            throw new Error('Agent authentication did not return an access token.');
+        progress(`Trusting ${repo.full_name}@${repo.default_branch} to deploy...`);
+        yield trustGithubRepo(options.apiUrl, accessToken, {
+            repositoryId: String(repo.id),
+            repository: repo.full_name,
+            branch: repo.default_branch,
+        });
+        const workflow = yield writeGithubWorkflow(root, githubWorkflow(repo.default_branch, result.site.subdomain, docsPath), options.force);
+        return {
+            siteUrl: agentSiteUrl(options.apiUrl, result.site.subdomain),
+            subdomain: result.site.subdomain,
+            repository: repo.full_name,
+            branch: repo.default_branch,
+            workflowPath: GITHUB_WORKFLOW_PATH,
+            workflow,
+        };
+    });
+}
+export function formatGithubSetup(result) {
+    return [
+        `Site: ${result.siteUrl}`,
+        `Trusted repository: ${result.repository} (branch ${result.branch})`,
+        `Workflow: ${result.workflowPath} (${result.workflow})`,
+        '',
+        'Next steps:',
+        `1. Commit and push ${result.workflowPath} to ${result.branch}.`,
+        `2. Every push to ${result.branch} then deploys ${result.subdomain} through GitHub Actions. No secrets are stored in the repository.`,
+        '',
+        ...CLAIM_INSTRUCTIONS,
+    ].join('\n');
+}

package/bin/deploy-instructions.js

@@ -6,7 +6,13 @@ export const DEPLOY_HELP = [
     'Pass --email to obtain a claim link for the user. If it is absent, ask the user for their email and rerun with --email from the same directory. Never invent an email address.',
     'To claim an existing site without provisioning, run mint claim --email <email>. Show the link to the user and ask them to return the displayed code. Then run mint claim --code <code>. Use the original documentation directory for both commands, or pass --directory.',
     'The output contains a short-lived write token. Do not paste it into public logs or save it in a Git remote.',
+    'Pass --github from the root of a GitHub repository to deploy on every push: it trusts the repository (via the gh CLI and the origin remote) to deploy the site and writes .github/workflows/mintlify.yml. Commit and push that workflow. Pass --directory to deploy a docs subdirectory of the repository as the site root. Use --force to overwrite a different existing workflow.',
+    'In GitHub Actions (GITHUB_ACTIONS=true), no agent credentials are used: the workflow needs `permissions: id-token: write`, --subdomain is required, and the current commit is force-pushed to the site from a trusted repository and branch.',
 ].join('\n\n');
+export const CLAIM_INSTRUCTIONS = [
+    'Ask the user for the email address they want to use to claim this site. Never invent an email address.',
+    'After they provide it, run mint deploy --email <their-email> from the same documentation directory (or repeat --directory). This reuses the site and returns its claim link.',
+];
 export function deploymentInstructions(result, claimUrl) {
     if (result.status !== 'ready')
         return '';
@@ -31,9 +37,6 @@ export function deploymentInstructions(result, claimUrl) {
                 'Show this link to the user. Ask them to open it, sign in, and return the displayed code. Do not sign in on their behalf.',
                 'After the user returns the code, run mint claim --code <code> from the same documentation directory (or repeat --directory). The CLI completes the claim using its saved credentials.',
             ]
-            : [
-                'Ask the user for the email address they want to use to claim this site. Never invent an email address.',
-                'After they provide it, run mint deploy --email <their-email> from the same documentation directory (or repeat --directory). This reuses the site and returns its claim link.',
-            ]),
+            : CLAIM_INSTRUCTIONS),
     ].join('\n');
 }

package/bin/deploy.js

@@ -73,14 +73,17 @@ export function prepareAgentDeployment(options_1, warn_1) {
         throw new Error('The new anonymous site is already expired. Please retry later.');
     });
 }
+export function agentSiteUrl(apiUrl, subdomain) {
+    const domain = new URL(apiUrl).hostname === 'leaves-dev.mintlify.com'
+        ? 'mint-dev.mintlify.me'
+        : 'mintlify.site';
+    return new URL(`https://${subdomain}.${domain}`).toString();
+}
 export function formatDeployment(result, apiUrl) {
     if (result.status === 'claimed')
         return 'This site has been claimed. Manage it in the Mintlify dashboard. Use mint deploy --new --subdomain <name> to create another site.';
     const { site, write } = result;
-    const domain = new URL(apiUrl).hostname === 'leaves-dev.mintlify.com'
-        ? 'mint-dev.mintlify.me'
-        : 'mintlify.site';
-    const siteUrl = new URL(`https://${site.subdomain}.${domain}`).toString();
+    const siteUrl = agentSiteUrl(apiUrl, site.subdomain);
     return [
         result.created
             ? 'Repository provisioned; push required to build the site.'