@mintlify/cli 4.0.1701 → 4.0.1703

package/bin/agent-credentials.js

@@ -0,0 +1,54 @@
+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 { createHash } from 'node:crypto';
+import path from 'node:path';
+import { z } from 'zod';
+import { getKeytar } from './keyring.js';
+const service = 'mintlify-agent';
+export const agentCredentialsSchema = z.object({
+    registrationId: z.string().min(1),
+    issuer: z.url(),
+    assertion: z.string().min(1),
+    claimToken: z.string().min(1),
+    accessToken: z.string().min(1).optional(),
+    accessTokenExpiresAt: z.number().optional(),
+});
+function projectAccount(apiUrl, directory) {
+    return `project:${createHash('sha256')
+        .update(JSON.stringify([new URL(apiUrl).origin, path.resolve(directory)]))
+        .digest('hex')}`;
+}
+function registrationAccount(apiUrl, registrationId) {
+    return `${new URL(apiUrl).origin}:${registrationId}`;
+}
+export function loadAgentCredentials(apiUrl, directory) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const keytar = yield getKeytar();
+        const registrationId = yield keytar.getPassword(service, projectAccount(apiUrl, directory));
+        if (!registrationId)
+            return null;
+        const value = yield keytar.getPassword(service, registrationAccount(apiUrl, registrationId));
+        if (!value)
+            throw new Error('Saved agent credentials are missing. Use --new to create another site.');
+        const credentials = agentCredentialsSchema.parse(JSON.parse(value));
+        if (credentials.registrationId !== registrationId) {
+            throw new Error('Saved agent credentials do not match this project.');
+        }
+        return credentials;
+    });
+}
+export function saveAgentCredentials(apiUrl, directory, credentials) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const value = agentCredentialsSchema.parse(credentials);
+        const keytar = yield getKeytar();
+        yield keytar.setPassword(service, registrationAccount(apiUrl, value.registrationId), JSON.stringify(value));
+        yield keytar.setPassword(service, projectAccount(apiUrl, directory), value.registrationId);
+    });
+}

package/bin/agent-deployment.js

@@ -0,0 +1,73 @@
+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 { setTimeout } from 'node:timers/promises';
+import { z } from 'zod';
+import { agentRequest, agentResponse } from './agent-http.js';
+const readySchema = z.object({
+    status: z.literal('ready'),
+    deploymentId: z.string().min(1),
+    subdomain: z.string().min(1),
+    remote: z.url(),
+    branch: z.literal('main'),
+    expiresAt: z.iso.datetime(),
+});
+const existingSchema = z.discriminatedUnion('status', [
+    readySchema.extend({ code: z.literal('deployment_already_exists') }),
+    z.object({
+        status: z.literal('provisioning'),
+        code: z.literal('deployment_already_exists'),
+        deploymentId: z.string().optional(),
+        subdomain: z.string().optional(),
+    }),
+    z.object({
+        status: z.literal('expired'),
+        code: z.literal('deployment_already_exists'),
+        deploymentId: z.string(),
+        subdomain: z.string(),
+        expiresAt: z.iso.datetime().optional(),
+    }),
+]);
+const writeTokenSchema = z.object({
+    remote: z.url(),
+    branch: z.literal('main'),
+    token: z.string().min(1),
+    tokenExpiresAt: z.iso.datetime(),
+});
+export function provisionAgentSite(apiUrl, accessToken, settings) {
+    return __awaiter(this, void 0, void 0, function* () {
+        for (let attempt = 0; attempt < 4; attempt++) {
+            const response = yield agentRequest(`${apiUrl}/api/agent/deployments/provision`, {
+                method: 'POST',
+                headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
+                body: JSON.stringify(Object.assign(Object.assign({}, settings), { docsPath: '' })),
+            });
+            if (response.status !== 409) {
+                return Object.assign(Object.assign({}, (yield agentResponse(response, readySchema))), { created: true });
+            }
+            const body = yield response.json().catch(() => null);
+            const parsed = existingSchema.safeParse(body);
+            if (!parsed.success)
+                throw new Error('The deployment service returned an unexpected response.');
+            if (parsed.data.status !== 'provisioning')
+                return Object.assign(Object.assign({}, parsed.data), { created: false });
+            if (attempt < 3)
+                yield setTimeout(1000 * (attempt + 1));
+        }
+        throw new Error('Your site is still provisioning. Run the same command again.');
+    });
+}
+export function getAgentWriteToken(apiUrl, accessToken) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return agentResponse(yield agentRequest(`${apiUrl}/api/agent/deployments/token`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${accessToken}` },
+        }), writeTokenSchema);
+    });
+}

package/bin/agent-http.js

@@ -0,0 +1,45 @@
+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 { z } from 'zod';
+const errorSchema = z.object({ code: z.string().optional(), error: z.string().optional() });
+export class AgentApiError extends Error {
+    constructor(status, code) {
+        super(`Agent request failed (HTTP ${status}).${code ? ` Code: ${code}.` : ''}`);
+        this.status = status;
+        this.code = code;
+    }
+}
+export function agentRequest(url, init) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            const timeout = AbortSignal.timeout(30000);
+            const signal = (init === null || init === void 0 ? void 0 : init.signal) ? AbortSignal.any([init.signal, timeout]) : timeout;
+            return yield fetch(url, Object.assign(Object.assign({}, init), { redirect: 'error', signal }));
+        }
+        catch (_a) {
+            throw new Error('Could not reach the agent service. Retry the same command.');
+        }
+    });
+}
+export function agentResponse(response, schema) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const body = yield response.json().catch(() => null);
+        if (!response.ok) {
+            const error = errorSchema.safeParse(body);
+            const code = error.success ? ((_a = error.data.code) !== null && _a !== void 0 ? _a : error.data.error) : undefined;
+            throw new AgentApiError(response.status, (_b = code === null || code === void 0 ? void 0 : code.match(/^[a-z_]{1,80}$/)) === null || _b === void 0 ? void 0 : _b[0]);
+        }
+        const parsed = schema.safeParse(body);
+        if (!parsed.success)
+            throw new Error('The agent service returned an unexpected response.');
+        return parsed.data;
+    });
+}

package/bin/cli.js

@@ -18,11 +18,14 @@ import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 import { accessibilityCheck } from './accessibilityCheck.js';
 import { addDomain } from './addDomain.js';
+import { createAgentClaimLink } from './agent-claim.js';
 import { analyticsBuilder } from './analytics/index.js';
 import { comingSoon } from './comingSoon.js';
 import { setTelemetryEnabled } from './config.js';
 import { getConfigValue, setConfigValue, clearConfigValue } from './config.js';
 import { API_URL } from './constants.js';
+import { DEPLOY_HELP, deploymentInstructions } from './deploy-instructions.js';
+import { formatDeployment, prepareAgentDeployment } from './deploy.js';
 import { formatHandler } from './format.js';
 import { CMD_EXEC_PATH, checkPort, checkNodeVersion, autoUpgradeIfNeeded, findDocsRoot, getVersions, isAI, suppressConsoleWarnings, terminate, } from './helpers.js';
 import { init } from './init.js';
@@ -94,6 +97,59 @@ export const cli = ({ packageName = 'mint' }) => {
         .middleware(checkNodeVersion)
         .middleware(suppressConsoleWarnings)
         .middleware(telemetryMiddleware)
+        .command('deploy', 'Provision an anonymous docs site and get Git push instructions', (yargs) => yargs
+        .option('subdomain', {
+        type: 'string',
+        description: 'Requested site name; required for the first deployment or --new',
+    })
+        .option('org-name', { type: 'string', description: 'Organization display name' })
+        .option('directory', {
+        type: 'string',
+        default: '.',
+        description: 'Documentation directory associated with this site',
+    })
+        .option('new', {
+        type: 'boolean',
+        default: false,
+        description: 'Create a new registration and site',
+    })
+        .option('email', {
+        type: 'string',
+        description: 'User email for an optional claim link',
+    })
+        .example('$0 deploy --subdomain my-docs', 'Provision a site without signing in')
+        .example('$0 deploy --email you@example.com', 'Get repository access and a claim link for the current site')
+        .example('$0 deploy --new --subdomain another-site', 'Create another anonymous site')
+        .epilog(DEPLOY_HELP), (argv) => __awaiter(void 0, void 0, void 0, function* () {
+        try {
+            const result = yield prepareAgentDeployment({
+                apiUrl: API_URL,
+                directory: argv.directory,
+                subdomain: argv.subdomain,
+                orgName: argv.orgName,
+                newSite: argv.new,
+            }, (message) => {
+                process.stderr.write(`Warning: ${message}\n`);
+            }, (message) => process.stderr.write(`${message}\n`));
+            process.stdout.write(`${formatDeployment(result, API_URL)}\n`);
+            let claimUrl;
+            if (argv.email && result.status === 'ready') {
+                try {
+                    process.stderr.write('Creating the claim link...\n');
+                    claimUrl = yield createAgentClaimLink(API_URL, result.credentials, argv.email);
+                }
+                catch (_a) {
+                    process.stderr.write('Warning: Could not create the claim link. Your site is provisioned; retry with --email later.\n');
+                }
+            }
+            process.stdout.write(`${deploymentInstructions(result, claimUrl)}\n`);
+            yield terminate(0);
+        }
+        catch (error) {
+            process.stderr.write(`${error instanceof Error ? error.message : 'Deployment failed.'}\n`);
+            yield terminate(1);
+        }
+    }))
         .command('dev', 'Initialize a local preview environment', (yargs) => yargs
         .option('open', {
         type: 'boolean',

package/bin/config.js

@@ -9,7 +9,19 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 import fs from 'fs';
 import { ensureDir } from 'fs-extra';
+import { z } from 'zod';
 import { CLI_CONFIG_FILE, CONFIG_DIR } from './constants.js';
+const agentSiteMetadataSchema = z.object({ registrationId: z.string(), subdomain: z.string() });
+export function getAgentSiteMetadata(key) {
+    var _a;
+    const parsed = agentSiteMetadataSchema.safeParse((_a = readConfig().agentSites) === null || _a === void 0 ? void 0 : _a[key]);
+    return parsed.success ? parsed.data : undefined;
+}
+export function setAgentSiteMetadata(key, site) {
+    return __awaiter(this, void 0, void 0, function* () {
+        yield writeConfig({ agentSites: Object.assign(Object.assign({}, readConfig().agentSites), { [key]: site }) });
+    });
+}
 function readConfig() {
     try {
         const raw = fs.readFileSync(CLI_CONFIG_FILE, 'utf-8');

package/bin/deploy-instructions.js

@@ -0,0 +1,39 @@
+import { API_URL } from './constants.js';
+export const DEPLOY_HELP = [
+    'No login is required. This command provisions a temporary site and returns repository access. Commit and push the documentation yourself; the CLI does not upload files.',
+    'Run from your documentation directory, or pass --directory. Put docs.json, pages, and assets at the hosted repository root.',
+    'Run again from the same documentation directory for the current anonymous site and a fresh write token. Use --new --subdomain <name> to create another site.',
+    'Claimed sites are managed in the dashboard. Confirmed expired sites start a new anonymous registration.',
+    '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.',
+    'The output contains a short-lived write token. Do not paste it into public logs or save it in a Git remote.',
+].join('\n\n');
+export function deploymentInstructions(result, claimUrl) {
+    if (result.status !== 'ready')
+        return '';
+    return [
+        '\nNext steps:',
+        '1. Clone the hosted repository into a separate directory. Do not replace the user’s existing Git remote.',
+        '2. Copy the selected documentation into its root, including docs.json, .md/.mdx pages, images, and other required assets. Exclude credentials, .env files, node_modules, and .git.',
+        '3. Commit the documentation. For subsequent updates, fetch the hosted main branch and commit on top of it. Do not force-push.',
+        '4. Push to main. Supply the write token as an HTTP Authorization: Bearer header for this Git operation only; never embed it in the remote URL or persist it in Git config.',
+        '5. If the write token expires, run mint deploy again from the same documentation directory to obtain a fresh token.',
+        'A successful push starts the normal build. Provisioning and Git success do not confirm build success.',
+        '',
+        'Git examples (POSIX shell): set REPOSITORY_URL and WRITE_TOKEN from the output above. Set CHECKOUT_DIR to a new directory outside the source documentation directory. Keep the token private and do not enable shell tracing.',
+        'GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0="http.${REPOSITORY_URL}.extraHeader" GIT_CONFIG_VALUE_0="Authorization: Bearer ${WRITE_TOKEN}" git clone "$REPOSITORY_URL" "$CHECKOUT_DIR"',
+        'After copying and committing the documentation:',
+        'GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0="http.${REPOSITORY_URL}.extraHeader" GIT_CONFIG_VALUE_0="Authorization: Bearer ${WRITE_TOKEN}" git -C "$CHECKOUT_DIR" push origin HEAD:main',
+        'These settings apply only to that Git process. Use the same authentication settings for later fetches.',
+        '',
+        ...(claimUrl
+            ? [
+                `Claim link for the user: ${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.',
+                `Follow the claim-completion instructions at ${API_URL}/api/agent/auth.md. This document includes the WorkOS steps and the authenticated Mintlify signup request.`,
+            ]
+            : [
+                '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.',
+            ]),
+    ].join('\n');
+}

package/bin/deploy.js

@@ -0,0 +1,97 @@
+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 path from 'node:path';
+import { discoverAgentAuth, exchangeAgentToken, getAgentIdentity, registerAgent, } from './agent-auth.js';
+import { loadAgentCredentials, saveAgentCredentials, } from './agent-credentials.js';
+import { getAgentWriteToken, provisionAgentSite, } from './agent-deployment.js';
+import { getAgentSiteMetadata, setAgentSiteMetadata } from './config.js';
+export function prepareAgentDeployment(options_1, warn_1) {
+    return __awaiter(this, arguments, void 0, function* (options, warn, progress = () => { }) {
+        var _a;
+        const { apiUrl } = options;
+        const directory = path.resolve(options.directory);
+        const metadataKey = JSON.stringify([new URL(apiUrl).origin, directory]);
+        const previous = getAgentSiteMetadata(metadataKey);
+        progress('Authenticating agent...');
+        let saved = options.newSite
+            ? null
+            : yield loadAgentCredentials(apiUrl, directory).catch(() => {
+                if (previous)
+                    throw new Error('Could not read this site’s saved credentials. Unlock your keyring or use --new for another site.');
+                warn('Could not read the keyring. Continuing with a new registration for this run.');
+                return null;
+            });
+        const subdomain = (_a = options.subdomain) !== null && _a !== void 0 ? _a : (options.newSite ? undefined : previous === null || previous === void 0 ? void 0 : previous.subdomain);
+        if (!subdomain)
+            throw new Error('Choose a site name with --subdomain <name>.');
+        const discovery = yield discoverAgentAuth(apiUrl);
+        const save = (credentials) => __awaiter(this, void 0, void 0, function* () {
+            try {
+                yield saveAgentCredentials(apiUrl, directory, credentials);
+            }
+            catch (_a) {
+                warn('Could not save agent credentials to the keyring. Continuing for this run; later commands may not recover access.');
+            }
+        });
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const credentials = saved !== null && saved !== void 0 ? saved : (yield registerAgent(discovery));
+            yield save(credentials);
+            const authenticated = yield exchangeAgentToken(discovery, credentials);
+            yield save(authenticated);
+            const identity = yield getAgentIdentity(apiUrl, authenticated.accessToken);
+            if (identity.registrationId !== credentials.registrationId)
+                throw new Error('Agent identity does not match the saved registration.');
+            if (identity.identityType === 'user_bound')
+                return { status: 'claimed' };
+            progress('Provisioning the site and repository...');
+            const site = yield provisionAgentSite(apiUrl, authenticated.accessToken, {
+                subdomain,
+                orgName: options.orgName,
+            });
+            if (site.status === 'expired') {
+                warn('The previous anonymous site expired. Creating a new registration and site.');
+                saved = null;
+                continue;
+            }
+            yield setAgentSiteMetadata(metadataKey, {
+                registrationId: credentials.registrationId,
+                subdomain: site.subdomain,
+            }).catch(() => warn('Could not save the site name locally. Provide --subdomain on your next invocation.'));
+            progress('Getting repository write access...');
+            const write = yield getAgentWriteToken(apiUrl, authenticated.accessToken);
+            if (write.remote !== site.remote)
+                throw new Error('Repository credentials do not match the provisioned site.');
+            return { status: 'ready', site, write, created: site.created, credentials: authenticated };
+        }
+        throw new Error('The new anonymous site is already expired. Please retry later.');
+    });
+}
+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();
+    return [
+        result.created
+            ? 'Repository provisioned; push required to build the site.'
+            : 'Using the existing anonymous repository; push any changes to build the site.',
+        `Site: ${siteUrl}`,
+        `Expires: ${site.expiresAt}`,
+        `Repository: ${site.remote}`,
+        `Branch: ${site.branch}`,
+        `Write token: ${write.token}`,
+        `Write token expires: ${write.tokenExpiresAt}`,
+        'Commit and push your documentation to this repository to start the build.',
+        'The site link becomes available after the push and build complete.',
+    ].join('\n');
+}

package/bin/keyring.js

@@ -11,7 +11,7 @@ const SERVICE = 'mintlify';
 const ACCESS_TOKEN_ACCOUNT = 'access_token';
 const REFRESH_TOKEN_ACCOUNT = 'refresh_token';
 const USER_EMAIL_ACCOUNT = 'user_email';
-function getKeytar() {
+export function getKeytar() {
     return __awaiter(this, void 0, void 0, function* () {
         var _a;
         try {