@mintlify/cli 4.0.1802 → 4.0.1804

package/__test__/agent-deployment.test.ts

@@ -33,6 +33,21 @@ describe('agent deployment API', () => {
       docsPath: '',
     });
   });
+  it('requests a base when the project type is workspace', async () => {
+    const request = vi.fn().mockResolvedValue(response({ ...ready, orgSlug: 'acme' }, 201));
+    vi.stubGlobal('fetch', request);
+    expect(
+      await provisionAgentSite('https://api.example.com', 'access', {
+        subdomain: 'requested',
+        projectType: 'workspace',
+      })
+    ).toEqual({ ...ready, orgSlug: 'acme', created: true });
+    expect(JSON.parse(request.mock.calls[0]?.[1].body)).toEqual({
+      subdomain: 'requested',
+      projectType: 'workspace',
+      docsPath: '',
+    });
+  });
   it('returns an existing site as an update, not a new creation', async () => {
     vi.stubGlobal('fetch', vi.fn().mockResolvedValue(response(existing, 409)));
     expect(await provision()).toEqual({ ...existing, created: false });

package/__test__/deploy-github-setup.test.ts

@@ -66,6 +66,7 @@ beforeEach(async () => {
   });
   vi.mocked(prepareAgentDeployment).mockResolvedValue({
     status: 'ready',
+    projectType: 'site',
     site,
     write: { remote: site.remote, branch: 'main', token: 'write', tokenExpiresAt: site.expiresAt },
     created: false,

package/__test__/deploy-instructions.test.ts

@@ -74,6 +74,7 @@ describe('deploy help and claim handoff', () => {
     const text = deploymentInstructions(
       {
         status: 'ready',
+        projectType: 'site',
         created: true,
         site,
         credentials,
@@ -95,6 +96,52 @@ describe('deploy help and claim handoff', () => {
     expect(text).not.toContain('claim-secret');
     expect(text).not.toContain('write-secret');
   });
+  it('gives base claim, clone, and push steps without site build or GitHub hints', () => {
+    const write = {
+      remote: site.remote,
+      branch: site.branch,
+      token: 'write-secret',
+      tokenExpiresAt: site.expiresAt,
+    };
+    const text = deploymentInstructions({
+      status: 'ready',
+      projectType: 'workspace',
+      created: true,
+      site,
+      credentials,
+      write,
+    });
+    expect(text).toContain('mint deploy --base --email <their-email>');
+    expect(text).toContain('mint claim --code <code>');
+    expect(text).toContain(
+      `git -c http.${site.remote}.extraHeader="Authorization: Bearer write-secret" clone ${site.remote} ${site.subdomain}`
+    );
+    expect(text).toContain(`mint deploy --base --push ${site.subdomain}`);
+    expect(text).not.toContain('Git examples');
+    expect(text.indexOf('--push')).toBeLessThan(text.indexOf('mint claim --code'));
+    expect(text).not.toContain('build');
+    expect(text).not.toContain('--github');
+  });
+  it('gives the base claim link when one was created', () => {
+    const text = deploymentInstructions(
+      {
+        status: 'ready',
+        projectType: 'workspace',
+        created: true,
+        site,
+        credentials,
+        write: {
+          remote: site.remote,
+          branch: site.branch,
+          token: 't',
+          tokenExpiresAt: site.expiresAt,
+        },
+      },
+      'https://claim.example.com/x'
+    );
+    expect(text).toContain('Send the user this link: https://claim.example.com/x');
+    expect(text).not.toContain('--email <their-email>');
+  });
   it('documents the command in root help and explains that it does not push files', () => {
     expect(renderWelcome({ packageName: 'mint', signedIn: false })).toContain('deploy');
     expect(DEPLOY_HELP).toContain('Commit and push the documentation yourself');
@@ -102,5 +149,7 @@ describe('deploy help and claim handoff', () => {
     expect(DEPLOY_HELP).toContain('mint claim --code <code>');
     expect(renderWelcome({ packageName: 'mint', signedIn: false })).toContain('claim --email');
     expect(DEPLOY_HELP).toContain('ask the user for their email');
+    expect(DEPLOY_HELP).toContain('--base cannot be combined with --github');
+    expect(DEPLOY_HELP).toContain('mint deploy --base --push <clone-directory>');
   });
 });

package/__test__/deploy.test.ts

@@ -5,6 +5,7 @@ import * as auth from '../src/agent-auth.js';
 import * as storage from '../src/agent-credentials.js';
 import * as deployment from '../src/agent-deployment.js';
 import * as config from '../src/config.js';
+import { DASHBOARD_URL } from '../src/constants.js';
 import { prepareAgentDeployment, formatDeployment } from '../src/deploy.js';
 import { trackEvent } from '../src/telemetry/track.js';
 
@@ -100,6 +101,20 @@ describe('mint deploy', () => {
     const result = await prepareAgentDeployment({ ...options, apiUrl }, warn);
     expect(formatDeployment(result, apiUrl)).toContain(`Site: ${siteUrl}`);
   });
+  it('provisions a base and prints its editor link instead of a site URL', async () => {
+    vi.mocked(deployment.provisionAgentSite).mockResolvedValue({ ...site, orgSlug: 'acme' });
+    const result = await prepareAgentDeployment({ ...options, base: true }, warn);
+    expect(deployment.provisionAgentSite).toHaveBeenCalledWith(options.apiUrl, 'access', {
+      subdomain: 'requested',
+      orgName: undefined,
+      projectType: 'workspace',
+    });
+    const text = formatDeployment(result, options.apiUrl);
+    expect(text).toContain(`Editor: ${new URL('/acme/allocated/editor', DASHBOARD_URL)}`);
+    expect(text).not.toContain('Site:');
+    expect(text).not.toContain('build');
+    expect(text).not.toContain('Write token');
+  });
   it('fails before provisioning when credentials cannot be saved', async () => {
     vi.mocked(storage.saveAgentCredentials).mockRejectedValue(new Error('disk full'));
     await expect(prepareAgentDeployment(options, warn)).rejects.toThrow('disk full');

package/bin/agent-deployment.js

@@ -17,6 +17,7 @@ const readySchema = z.object({
     remote: z.url(),
     branch: z.literal('main'),
     expiresAt: z.iso.datetime(),
+    orgSlug: z.string().min(1).optional(),
 });
 const existingSchema = z.discriminatedUnion('status', [
     readySchema.extend({ code: z.literal('deployment_already_exists') }),

package/bin/cli.js

@@ -23,10 +23,11 @@ import { comingSoon } from './comingSoon.js';
 import { setTelemetryEnabled } from './config.js';
 import { getConfigValue, setConfigValue, clearConfigValue } from './config.js';
 import { API_URL } from './constants.js';
+import { pushBaseCheckout } from './deploy-base.js';
 import { deployFromGithubActions, isGithubActions } from './deploy-github-actions.js';
 import { formatGithubSetup, setupGithubDeployment } from './deploy-github-setup.js';
 import { DEPLOY_HELP, deploymentInstructions } from './deploy-instructions.js';
-import { formatDeployment, prepareAgentDeployment } from './deploy.js';
+import { agentEditorUrl, formatDeployment, prepareAgentDeployment } from './deploy.js';
 import { FEEDBACK_CATEGORIES, feedback } from './feedback.js';
 import { formatHandler } from './format.js';
 import { checkPort, checkNodeVersion, autoUpgradeIfNeeded, getVersions, isAI, suppressConsoleWarnings, terminate, } from './helpers.js';
@@ -187,10 +188,22 @@ export const cli = ({ packageName = 'mint' }) => {
         default: false,
         description: 'With --github, overwrite an existing .github/workflows/mintlify.yml',
     })
+        .option('base', {
+        type: 'boolean',
+        description: 'Provision a base, edited in the Mintlify editor, instead of a docs site',
+    })
+        .option('push', {
+        type: 'string',
+        description: 'With --base, rebase this clone onto main and push it to the base',
+    })
+        .implies('push', 'base')
+        .conflicts('push', 'email')
         .conflicts('github', 'email')
+        .conflicts('base', 'github')
         .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')
+        .example('$0 deploy --base --subdomain my-base', 'Provision a base and get its editor link')
         .example('$0 deploy --github --subdomain my-docs', 'Deploy the site from GitHub Actions on every push to the default branch')
         .example('$0 deploy --subdomain my-docs', 'In GitHub Actions with id-token: write, push the current commit to a trusted site')
         .epilog(DEPLOY_HELP), (argv) => __awaiter(void 0, void 0, void 0, function* () {
@@ -220,9 +233,16 @@ export const cli = ({ packageName = 'mint' }) => {
                 subdomain: argv.subdomain,
                 orgName: argv.orgName,
                 newSite: argv.new,
+                base: argv.base,
             }, (message) => {
                 process.stderr.write(`Warning: ${message}\n`);
             }, (message) => process.stderr.write(`${message}\n`));
+            if (argv.push && result.status === 'ready') {
+                yield pushBaseCheckout(argv.push, result.write);
+                process.stdout.write(`Pushed ${argv.push} to the base.\nEditor: ${agentEditorUrl(result.site)}\n`);
+                yield terminate(0);
+                return;
+            }
             process.stdout.write(`${formatDeployment(result, API_URL)}\n`);
             let claimUrl;
             if (argv.email && result.status === 'ready') {

package/bin/deploy-base.js

@@ -0,0 +1,20 @@
+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 { git } from './deploy-github-actions.js';
+export function pushBaseCheckout(checkout, write) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const env = Object.assign(Object.assign({}, process.env), { GIT_CONFIG_COUNT: '1', GIT_CONFIG_KEY_0: `http.${write.remote}.extraHeader`, GIT_CONFIG_VALUE_0: `Authorization: Bearer ${write.token}` });
+        yield git(['fetch', write.remote, write.branch], checkout, env);
+        yield git(['rebase', 'FETCH_HEAD'], checkout, env).catch(() => {
+            throw new Error(`Could not rebase ${checkout} onto the latest ${write.branch}. Resolve the conflicts, run git rebase --continue, then rerun mint deploy --base --push ${checkout}.`);
+        });
+        yield git(['push', write.remote, `HEAD:refs/heads/${write.branch}`], checkout, env);
+    });
+}

package/bin/deploy-github-actions.js

@@ -41,7 +41,7 @@ function getGithubOidcToken(env, audience) {
         return parsed.data.value;
     });
 }
-function git(args, cwd, env) {
+export function git(args, cwd, env) {
     return new Promise((resolve, reject) => {
         const child = spawn('git', args, { cwd, env, stdio: ['ignore', 'pipe', 'inherit'] });
         let out = '';

package/bin/deploy-instructions.js

@@ -7,15 +7,44 @@ export const DEPLOY_HELP = [
     '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.',
+    'Pass --base to provision a base instead of a docs site. The output has the claim steps, a clone command, and the editor link; there is no site URL. Commit in the clone, then run mint deploy --base --push <clone-directory> to publish. --base cannot be combined with --github.',
     '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.',
 ];
+const baseClaimStep = (claimUrl) => claimUrl
+    ? [
+        `3. Claim the base last. Send the user this link: ${claimUrl}`,
+        '   They sign in and get a code. When they give it to you, run: mint claim --code <code>',
+    ]
+    : [
+        '3. Claim the base last. Ask the user for their email (never invent one), then run:',
+        '   mint deploy --base --email <their-email>',
+        '   Send the user the claim link it prints. They sign in and get a code. When they give it to you, run: mint claim --code <code>',
+    ];
+function baseInstructions(result, claimUrl) {
+    const { site, write } = result;
+    const checkout = site.subdomain;
+    return [
+        '\nNext steps:',
+        `1. Clone the base into ./${checkout}:`,
+        `   git -c http.${write.remote}.extraHeader="Authorization: Bearer ${write.token}" clone ${write.remote} ${checkout}`,
+        `   The clone command works until ${write.tokenExpiresAt}. Run mint deploy --base again for a fresh one.`,
+        `2. Commit your changes in ./${checkout}, then publish them:`,
+        `   mint deploy --base --push ${checkout}`,
+        '   This rebases onto the latest main and pushes. Do not run git push yourself.',
+        ...baseClaimStep(claimUrl),
+        '   After the claim, the user opens the base at the editor link above and edits it there. The CLI can no longer push to it.',
+        'Run every mint command from this directory (or repeat --directory).',
+    ].join('\n');
+}
 export function deploymentInstructions(result, claimUrl) {
     if (result.status !== 'ready')
         return '';
+    if (result.projectType === 'workspace')
+        return baseInstructions(result, claimUrl);
     return [
         '\nNext steps:',
         '1. Clone the hosted repository into a separate directory. Do not replace the user’s existing Git remote.',

package/bin/deploy.js

@@ -12,6 +12,7 @@ import { discoverAgentAuth, exchangeAgentToken, getAgentIdentity, registerAgent,
 import { loadAgentCredentials, saveAgentCredentials, } from './agent-credentials.js';
 import { getAgentWriteToken, provisionAgentSite, } from './agent-deployment.js';
 import { getAgentSiteMetadata, setAgentSiteMetadata } from './config.js';
+import { DASHBOARD_URL } from './constants.js';
 import { trackEvent } from './telemetry/track.js';
 export function prepareAgentDeployment(options_1, warn_1) {
     return __awaiter(this, arguments, void 0, function* (options, warn, progress = () => { }) {
@@ -33,6 +34,7 @@ export function prepareAgentDeployment(options_1, warn_1) {
         if (!subdomain)
             throw new Error('Choose a site name with --subdomain <name>.');
         const discovery = yield discoverAgentAuth(apiUrl);
+        const projectType = options.base ? 'workspace' : 'site';
         const save = (credentials) => saveAgentCredentials(apiUrl, directory, credentials);
         for (let attempt = 0; attempt < 2; attempt++) {
             const credentials = saved !== null && saved !== void 0 ? saved : (yield registerAgent(discovery));
@@ -47,11 +49,8 @@ export function prepareAgentDeployment(options_1, warn_1) {
                 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,
-            });
+            progress(`Provisioning the ${options.base ? 'base' : 'site'} and repository...`);
+            const site = yield provisionAgentSite(apiUrl, authenticated.accessToken, Object.assign({ subdomain, orgName: options.orgName }, (options.base && { projectType })));
             if (site.status === 'expired') {
                 warn('The previous anonymous site expired. Creating a new registration and site.');
                 saved = null;
@@ -71,7 +70,14 @@ export function prepareAgentDeployment(options_1, warn_1) {
             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 };
+            return {
+                status: 'ready',
+                projectType,
+                site,
+                write,
+                created: site.created,
+                credentials: authenticated,
+            };
         }
         throw new Error('The new anonymous site is already expired. Please retry later.');
     });
@@ -82,10 +88,27 @@ export function agentSiteUrl(apiUrl, subdomain) {
         : 'mintlify.site';
     return new URL(`https://${subdomain}.${domain}`).toString();
 }
+export function agentEditorUrl(site) {
+    return site.orgSlug
+        ? new URL(`/${site.orgSlug}/${site.subdomain}/editor`, DASHBOARD_URL).toString()
+        : new URL(DASHBOARD_URL).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 access = [
+        `Repository: ${site.remote}`,
+        `Branch: ${site.branch}`,
+        `Write token: ${write.token}`,
+        `Write token expires: ${write.tokenExpiresAt}`,
+    ];
+    if (result.projectType === 'workspace')
+        return [
+            result.created ? 'Base provisioned.' : 'Using the existing anonymous base.',
+            `Editor: ${agentEditorUrl(site)}`,
+            `Expires: ${site.expiresAt}. Claim it before then or it is deleted.`,
+        ].join('\n');
     const siteUrl = agentSiteUrl(apiUrl, site.subdomain);
     return [
         result.created
@@ -93,10 +116,7 @@ export function formatDeployment(result, apiUrl) {
             : '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}`,
+        ...access,
         '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');