@mintlify/cli 4.0.1714 → 4.0.1716

package/__test__/agent-claim.test.ts

@@ -0,0 +1,149 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { claimDeployment } from '../src/agent-claim.js';
+import { loadAgentCredentials, saveAgentCredentials } from '../src/agent-credentials.js';
+
+vi.mock('../src/agent-credentials.js', () => ({
+  loadAgentCredentials: vi.fn(),
+  saveAgentCredentials: vi.fn(),
+}));
+const issuer = 'https://auth.example.com';
+const apiUrl = 'https://api.example.com';
+const options = { apiUrl, directory: '/docs', code: 'ABCDEFGH' };
+const original = {
+  registrationId: 'reg',
+  issuer,
+  assertion: 'old-assertion',
+  claimToken: 'secret-claim',
+  accessToken: 'anonymous-token',
+  accessTokenExpiresAt: Date.now() + 300_000,
+};
+const discovery = {
+  issuer,
+  token_endpoint: `${issuer}/oauth2/token`,
+  agent_auth: {
+    identity_endpoint: `${issuer}/agent/identity`,
+    claim_endpoint: `${issuer}/agent/identity/claim`,
+    identity_types_supported: ['anonymous'],
+  },
+};
+const response = (body: unknown, status = 200) => new Response(JSON.stringify(body), { status });
+const fetchMock = vi.fn();
+beforeEach(() => {
+  vi.resetAllMocks();
+  vi.stubGlobal('fetch', fetchMock);
+  vi.mocked(loadAgentCredentials).mockResolvedValue({ ...original });
+  vi.mocked(saveAgentCredentials).mockResolvedValue(undefined);
+  fetchMock.mockImplementation(async (url: string) => {
+    if (url.endsWith('oauth-protected-resource'))
+      return response({ authorization_servers: [issuer] });
+    if (url.endsWith('oauth-authorization-server')) return response(discovery);
+    if (url.endsWith('/complete'))
+      return response({ identity: { assertion: 'claimed-assertion' } });
+    if (url.endsWith('/oauth2/token'))
+      return response({ access_token: 'claimed-token', expires_in: 300, token_type: 'Bearer' });
+    if (url.endsWith('/signup')) return response({ orgId: 'org', claimed: true });
+    if (url.endsWith('/claim'))
+      return response({ attempt: { verification_uri: `${issuer}/verify?token=attempt` } });
+    throw new Error('Unexpected endpoint');
+  });
+});
+afterEach(() => vi.unstubAllGlobals());
+
+describe('claim command', () => {
+  it('completes the existing claim, saves the new identity, and signs up with a fresh token', async () => {
+    expect(await claimDeployment(options, vi.fn())).toContain('successfully');
+    expect(fetchMock).toHaveBeenCalledWith(
+      `${issuer}/agent/identity/claim/complete`,
+      expect.objectContaining({
+        body: JSON.stringify({ claim_token: 'secret-claim', user_code: options.code }),
+      })
+    );
+    expect(fetchMock).not.toHaveBeenCalledWith(`${issuer}/agent/identity/claim`, expect.anything());
+    expect(fetchMock).toHaveBeenCalledWith(
+      `${apiUrl}/api/agent/signup`,
+      expect.objectContaining({ headers: { Authorization: 'Bearer claimed-token' } })
+    );
+    expect(vi.mocked(saveAgentCredentials).mock.calls[0]?.[2]).toMatchObject({
+      assertion: 'claimed-assertion',
+      claimVerified: true,
+      accessToken: undefined,
+    });
+    expect(vi.mocked(saveAgentCredentials).mock.invocationCallOrder[0]).toBeLessThan(
+      fetchMock.mock.invocationCallOrder[3]!
+    );
+  });
+  it('resumes after signup fails without consuming the code again', async () => {
+    const implementation = fetchMock.getMockImplementation()!;
+    fetchMock.mockImplementation((url, init) =>
+      url.endsWith('/signup') ? response({ code: 'unavailable' }, 503) : implementation(url, init)
+    );
+    await expect(claimDeployment(options, vi.fn())).rejects.toThrow('503');
+    const saved = vi.mocked(saveAgentCredentials).mock.calls[0]![2];
+    vi.mocked(loadAgentCredentials).mockResolvedValue(saved);
+    fetchMock.mockClear().mockImplementation(implementation);
+    expect(await claimDeployment(options, vi.fn())).toContain('successfully');
+    expect(fetchMock.mock.calls.some(([url]) => url.endsWith('/complete'))).toBe(false);
+  });
+  it('does not save or sign up after an invalid code', async () => {
+    const implementation = fetchMock.getMockImplementation()!;
+    fetchMock.mockImplementation((url, init) =>
+      url.endsWith('/complete')
+        ? response({ code: 'invalid_user_code' }, 400)
+        : implementation(url, init)
+    );
+    await expect(claimDeployment(options, vi.fn())).rejects.toThrow('invalid_user_code');
+    expect(saveAgentCredentials).not.toHaveBeenCalled();
+    expect(fetchMock.mock.calls.some(([url]) => url.endsWith('/signup'))).toBe(false);
+  });
+  it('warns on storage failure and continues signup without exposing secrets', async () => {
+    vi.mocked(saveAgentCredentials).mockRejectedValue(new Error('keyring unavailable'));
+    const warn = vi.fn();
+    const output = await claimDeployment(options, warn);
+    expect(output).toContain('successfully');
+    expect(warn).toHaveBeenCalled();
+    expect(JSON.stringify([output, warn.mock.calls])).not.toContain('secret-claim');
+    expect(JSON.stringify([output, warn.mock.calls])).not.toContain('claimed-assertion');
+  });
+  it('creates only a claim link for --email', async () => {
+    const output = await claimDeployment(
+      { apiUrl, directory: '/docs', email: 'person@example.com' },
+      vi.fn()
+    );
+    expect(output).toContain('mint claim --code');
+    expect(
+      fetchMock.mock.calls.some(([url]) => url.endsWith('/signup') || url.endsWith('/complete'))
+    ).toBe(false);
+  });
+  it('fails before network calls when credentials are missing', async () => {
+    vi.mocked(loadAgentCredentials).mockResolvedValue(null);
+    await expect(claimDeployment(options, vi.fn())).rejects.toThrow('No saved agent registration');
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+  it.each([{ code: undefined }, { code: ' ', email: undefined }, { email: 'person@example.com' }])(
+    'rejects missing or conflicting arguments: %o',
+    async (override) => {
+      await expect(claimDeployment({ ...options, ...override }, vi.fn())).rejects.toThrow(
+        'Provide either'
+      );
+      expect(fetchMock).not.toHaveBeenCalled();
+    }
+  );
+  it('rejects a different issuer without sending the claim token', async () => {
+    vi.mocked(loadAgentCredentials).mockResolvedValue({
+      ...original,
+      issuer: 'https://other.example.com',
+    });
+    await expect(claimDeployment(options, vi.fn())).rejects.toThrow('another issuer');
+    expect(fetchMock.mock.calls).toHaveLength(2);
+  });
+  it('does not report success if signup returns an anonymous identity', async () => {
+    const implementation = fetchMock.getMockImplementation()!;
+    fetchMock.mockImplementation((url, init) =>
+      url.endsWith('/signup')
+        ? response({ orgId: 'org', claimed: false })
+        : implementation(url, init)
+    );
+    await expect(claimDeployment(options, vi.fn())).rejects.toThrow('unexpected response');
+  });
+});

package/__test__/deploy-instructions.test.ts

@@ -5,7 +5,8 @@ import { DASHBOARD_URL } from '../src/constants.js';
 import { deploymentInstructions, DEPLOY_HELP } from '../src/deploy-instructions.js';
 import { renderWelcome } from '../src/welcome.js';
 
-vi.mock('../src/agent-auth.js', () => ({
+vi.mock('../src/agent-auth.js', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('../src/agent-auth.js')>()),
   discoverAgentAuth: async () => ({
     issuer: 'https://auth.example.com',
     agent_auth: { claim_endpoint: 'https://auth.example.com/agent/identity/claim' },
@@ -81,6 +82,8 @@ describe('deploy help and claim handoff', () => {
       'https://app.example.com/claim'
     );
     expect(text).toContain('Do not force-push');
+    expect(text).toContain('mint claim --code <code>');
+    expect(text).not.toContain('/auth.md');
     expect(text).toContain('docs.json');
     expect(text).toContain('https://app.example.com/claim');
     expect(text).not.toContain('assertion-secret');
@@ -91,6 +94,8 @@ describe('deploy help and claim handoff', () => {
     expect(renderWelcome({ packageName: 'mint', signedIn: false })).toContain('deploy');
     expect(DEPLOY_HELP).toContain('Commit and push the documentation yourself');
     expect(DEPLOY_HELP).toContain('--new');
+    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');
   });
 });

package/bin/agent-auth.js

@@ -19,9 +19,10 @@ const discoverySchema = z.object({
         identity_types_supported: z.array(z.string()),
     }),
 });
+export const agentIdentityAssertionSchema = z.object({ assertion: z.string().min(1) });
 const registrationSchema = z.object({
     id: z.string().min(1),
-    identity: z.object({ assertion: z.string().min(1) }),
+    identity: agentIdentityAssertionSchema,
     claim: z.object({ token: z.string().min(1) }),
 });
 const tokenSchema = z.object({

package/bin/agent-claim.js

@@ -8,7 +8,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { z } from 'zod';
-import { discoverAgentAuth } from './agent-auth.js';
+import { agentIdentityAssertionSchema, discoverAgentAuth, exchangeAgentToken, } from './agent-auth.js';
+import { loadAgentCredentials, saveAgentCredentials, } from './agent-credentials.js';
 import { agentRequest, agentResponse } from './agent-http.js';
 import { DASHBOARD_URL } from './constants.js';
 const claimAttemptSchema = z.object({ attempt: z.object({ verification_uri: z.url() }) });
@@ -37,3 +38,56 @@ export function createAgentClaimLink(apiUrl, credentials, email) {
         return claimUrl.toString();
     });
 }
+const completedClaimSchema = z.object({
+    identity: agentIdentityAssertionSchema,
+});
+const signupSchema = z.object({ orgId: z.string().min(1), claimed: z.literal(true) });
+export function claimDeployment(options_1, warn_1) {
+    return __awaiter(this, arguments, void 0, function* (options, warn, progress = () => { }) {
+        var _a, _b;
+        const { apiUrl, directory } = options;
+        const code = (_a = options.code) === null || _a === void 0 ? void 0 : _a.trim();
+        const email = (_b = options.email) === null || _b === void 0 ? void 0 : _b.trim();
+        if ((!code && !email) || (code && email)) {
+            throw new Error('Provide either --email <email> for a claim link or --code <code> to finish the claim.');
+        }
+        let credentials = yield loadAgentCredentials(apiUrl, directory);
+        if (!credentials)
+            throw new Error('No saved agent registration. Run from the directory used for mint deploy, or pass --directory.');
+        if (email && !credentials.claimVerified) {
+            progress('Creating the claim link...');
+            const link = yield createAgentClaimLink(apiUrl, credentials, email);
+            return `Claim link for the user: ${link}\nAsk the user to open it, sign in, and return the displayed code. Then run mint claim --code <code> from the same directory (or repeat --directory).`;
+        }
+        const discovery = yield discoverAgentAuth(apiUrl);
+        if (new URL(discovery.issuer).origin !== new URL(credentials.issuer).origin) {
+            throw new Error('Saved agent credentials belong to another issuer.');
+        }
+        const save = (value) => __awaiter(this, void 0, void 0, function* () {
+            try {
+                yield saveAgentCredentials(apiUrl, directory, value);
+            }
+            catch (_a) {
+                warn('Could not save claimed credentials to the keyring. Continuing for this run; a retry may not recover the completed claim.');
+            }
+        });
+        if (!credentials.claimVerified) {
+            progress('Completing the WorkOS claim...');
+            const completed = yield agentResponse(yield agentRequest(`${discovery.agent_auth.claim_endpoint.replace(/\/$/, '')}/complete`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ claim_token: credentials.claimToken, user_code: code }),
+            }), completedClaimSchema);
+            credentials = Object.assign(Object.assign({}, credentials), { assertion: completed.identity.assertion, claimVerified: true, accessToken: undefined, accessTokenExpiresAt: undefined });
+            yield save(credentials);
+        }
+        progress('Finishing the site claim...');
+        const authenticated = yield exchangeAgentToken(discovery, credentials);
+        yield agentResponse(yield agentRequest(`${apiUrl}/api/agent/signup`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${authenticated.accessToken}` },
+        }), signupSchema);
+        yield save(authenticated);
+        return 'Site claimed successfully. The user can now manage it in the Mintlify dashboard.';
+    });
+}

package/bin/agent-credentials.js

@@ -17,6 +17,7 @@ export const agentCredentialsSchema = z.object({
     issuer: z.url(),
     assertion: z.string().min(1),
     claimToken: z.string().min(1),
+    claimVerified: z.boolean().optional(),
     accessToken: z.string().min(1).optional(),
     accessTokenExpiresAt: z.number().optional(),
 });

package/bin/cli.js

@@ -17,7 +17,7 @@ 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 { claimDeployment, createAgentClaimLink } from './agent-claim.js';
 import { analyticsBuilder } from './analytics/index.js';
 import { brokenLinksHandler } from './brokenLinks.js';
 import { comingSoon } from './comingSoon.js';
@@ -96,6 +96,31 @@ export const cli = ({ packageName = 'mint' }) => {
         .middleware(checkNodeVersion)
         .middleware(suppressConsoleWarnings)
         .middleware(telemetryMiddleware)
+        .command('claim', 'Claim a site created with mint deploy', (yargs) => yargs
+        .option('email', { type: 'string', description: 'User email for a claim link' })
+        .option('code', {
+        type: 'string',
+        description: 'Code returned by the user from the claim page',
+    })
+        .option('directory', {
+        type: 'string',
+        default: '.',
+        description: 'Original documentation directory used for mint deploy',
+    })
+        .conflicts('code', 'email')
+        .example('$0 claim --email you@example.com', 'Get a claim link for the current site')
+        .example('$0 claim --code ABCDEFGH', 'Finish the claim with the code from the user')
+        .epilog('Run from the same directory as mint deploy, or pass --directory. Ask the user to open the claim link and return the code. The CLI reads saved credentials internally; do not read or print keychain secrets. Retry the same command if Mintlify signup fails.'), (argv) => __awaiter(void 0, void 0, void 0, function* () {
+        try {
+            const message = yield claimDeployment({ apiUrl: API_URL, directory: argv.directory, code: argv.code, email: argv.email }, (message) => process.stderr.write(`Warning: ${message}\n`), (message) => process.stderr.write(`${message}\n`));
+            process.stdout.write(`${message}\n`);
+            yield terminate(0);
+        }
+        catch (error) {
+            process.stderr.write(`${error instanceof Error ? error.message : 'Claim failed.'}\n`);
+            yield terminate(1);
+        }
+    }))
         .command('deploy', 'Provision an anonymous docs site and get Git push instructions', (yargs) => yargs
         .option('subdomain', {
         type: 'string',

package/bin/deploy-instructions.js

@@ -1,10 +1,10 @@
-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.',
+    '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.',
 ].join('\n\n');
 export function deploymentInstructions(result, claimUrl) {
@@ -29,7 +29,7 @@ export function deploymentInstructions(result, 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.`,
+                '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.',