@mintlify/cli 4.0.1733 → 4.0.1735

package/__test__/agent-claim.test.ts

@@ -54,7 +54,7 @@ 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(await claimDeployment(options)).toContain('successfully');
     expect(fetchMock).toHaveBeenCalledWith(
       `${issuer}/agent/identity/claim/complete`,
       expect.objectContaining({
@@ -83,11 +83,11 @@ describe('claim command', () => {
     fetchMock.mockImplementation((url, init) =>
       url.endsWith('/signup') ? response({ code: 'unavailable' }, 503) : implementation(url, init)
     );
-    await expect(claimDeployment(options, vi.fn())).rejects.toThrow('503');
+    await expect(claimDeployment(options)).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(await claimDeployment(options)).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 () => {
@@ -97,25 +97,22 @@ describe('claim command', () => {
         ? response({ code: 'invalid_user_code' }, 400)
         : implementation(url, init)
     );
-    await expect(claimDeployment(options, vi.fn())).rejects.toThrow('invalid_user_code');
+    await expect(claimDeployment(options)).rejects.toThrow('invalid_user_code');
     expect(saveAgentCredentials).not.toHaveBeenCalled();
     expect(trackEvent).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('fails before signup when credentials cannot be saved', async () => {
+    vi.mocked(saveAgentCredentials).mockRejectedValue(new Error('disk full'));
+    await expect(claimDeployment(options)).rejects.toThrow('disk full');
+    expect(fetchMock.mock.calls.some(([url]) => url.endsWith('/signup'))).toBe(false);
   });
   it('creates only a claim link for --email', async () => {
-    const output = await claimDeployment(
-      { apiUrl, directory: '/docs', email: 'person@example.com' },
-      vi.fn()
-    );
+    const output = await claimDeployment({
+      apiUrl,
+      directory: '/docs',
+      email: 'person@example.com',
+    });
     expect(new URL(output.match(/https?:\/\/\S+/)![0]).searchParams.get('registration')).toBe(
       'reg'
     );
@@ -128,15 +125,13 @@ describe('claim command', () => {
   });
   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');
+    await expect(claimDeployment(options)).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'
-      );
+      await expect(claimDeployment({ ...options, ...override })).rejects.toThrow('Provide either');
       expect(fetchMock).not.toHaveBeenCalled();
     }
   );
@@ -145,7 +140,7 @@ describe('claim command', () => {
       ...original,
       issuer: 'https://other.example.com',
     });
-    await expect(claimDeployment(options, vi.fn())).rejects.toThrow('another issuer');
+    await expect(claimDeployment(options)).rejects.toThrow('another issuer');
     expect(fetchMock.mock.calls).toHaveLength(2);
   });
   it('does not report success if signup returns an anonymous identity', async () => {
@@ -155,6 +150,6 @@ describe('claim command', () => {
         ? response({ orgId: 'org', claimed: false })
         : implementation(url, init)
     );
-    await expect(claimDeployment(options, vi.fn())).rejects.toThrow('unexpected response');
+    await expect(claimDeployment(options)).rejects.toThrow('unexpected response');
   });
 });

package/__test__/agent-credentials.test.ts

@@ -1,8 +1,21 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 const entries = new Map<string, string>();
-const keytar = vi.hoisted(() => ({ getPassword: vi.fn(), setPassword: vi.fn() }));
+const keytar = vi.hoisted(() => ({
+  getPassword: vi.fn(),
+  setPassword: vi.fn(),
+  deletePassword: vi.fn(),
+}));
 vi.mock('../src/keyring.js', () => ({ getKeytar: async () => keytar }));
+const configDir = vi.hoisted(() => ({ path: '' }));
+vi.mock('../src/constants.js', () => ({
+  get CONFIG_DIR() {
+    return configDir.path;
+  },
+}));
 
 import { loadAgentCredentials, saveAgentCredentials } from '../src/agent-credentials.js';
 
@@ -17,12 +30,16 @@ describe('agent credentials', () => {
   beforeEach(() => {
     entries.clear();
     vi.resetAllMocks();
+    configDir.path = fs.mkdtempSync(path.join(os.tmpdir(), 'mint-agent-'));
     keytar.getPassword.mockImplementation(
       async (service, account) => entries.get(`${service}/${account}`) ?? null
     );
     keytar.setPassword.mockImplementation(async (service, account, value) => {
       entries.set(`${service}/${account}`, value);
     });
+    keytar.deletePassword.mockImplementation(async (service, account) =>
+      entries.delete(`${service}/${account}`)
+    );
   });
 
   it('isolates projects and environments from each other and human credentials', async () => {
@@ -45,12 +62,82 @@ describe('agent credentials', () => {
     expect(entries.has('mintlify-agent/https://api.example.com:reg_1')).toBe(true);
   });
 
-  it('does not switch the project pointer when storing the credential fails', async () => {
+  it('falls back to a local file when the keyring cannot be written or read', async () => {
+    keytar.setPassword.mockRejectedValue(new Error('locked'));
+    await saveAgentCredentials('https://api.example.com', '/docs', credentials);
+    expect(entries.size).toBe(0);
+    const file = path.join(configDir.path, 'agent-credentials.json');
+    if (process.platform !== 'win32') expect(fs.statSync(file).mode & 0o777).toBe(0o600);
+    keytar.getPassword.mockRejectedValue(new Error('locked'));
+    expect(await loadAgentCredentials('https://api.example.com', '/docs')).toEqual(credentials);
+  });
+
+  it('removes stale fallback entries once the keyring is writable again', async () => {
     keytar.setPassword.mockRejectedValueOnce(new Error('locked'));
+    await saveAgentCredentials('https://api.example.com', '/docs', credentials);
+    await saveAgentCredentials('https://api.example.com', '/docs', {
+      ...credentials,
+      assertion: 'next',
+    });
+    expect((await loadAgentCredentials('https://api.example.com', '/docs'))?.assertion).toBe(
+      'next'
+    );
+    const file = path.join(configDir.path, 'agent-credentials.json');
+    expect(JSON.parse(fs.readFileSync(file, 'utf-8'))).toEqual({});
+  });
+
+  it('reads the keyring before the fallback file', async () => {
+    await saveAgentCredentials('https://api.example.com', '/docs', credentials);
+    fs.writeFileSync(
+      path.join(configDir.path, 'agent-credentials.json'),
+      JSON.stringify({
+        'https://api.example.com:reg_1': JSON.stringify({ ...credentials, assertion: 'stale' }),
+      })
+    );
+    expect(await loadAgentCredentials('https://api.example.com', '/docs')).toEqual(credentials);
+  });
+
+  it('ignores a corrupt fallback file when the keyring has the credentials', async () => {
+    await saveAgentCredentials('https://api.example.com', '/docs', credentials);
+    fs.writeFileSync(path.join(configDir.path, 'agent-credentials.json'), '{');
+    expect(await loadAgentCredentials('https://api.example.com', '/docs')).toEqual(credentials);
+  });
+
+  it('drops the stale keyring entry when a write falls back to the file', async () => {
+    await saveAgentCredentials('https://api.example.com', '/docs', credentials);
+    keytar.setPassword.mockRejectedValueOnce(new Error('locked'));
+    await saveAgentCredentials('https://api.example.com', '/docs', {
+      ...credentials,
+      assertion: 'next',
+    });
+    expect((await loadAgentCredentials('https://api.example.com', '/docs'))?.assertion).toBe(
+      'next'
+    );
+  });
+
+  it('succeeds when the keyring write works but fallback cleanup fails', async () => {
+    keytar.setPassword.mockRejectedValueOnce(new Error('locked'));
+    await saveAgentCredentials('https://api.example.com', '/docs', credentials);
+    fs.chmodSync(configDir.path, 0o500);
+    await expect(
+      saveAgentCredentials('https://api.example.com', '/docs', {
+        ...credentials,
+        assertion: 'next',
+      })
+    ).resolves.toBeUndefined();
+    fs.chmodSync(configDir.path, 0o700);
+    expect((await loadAgentCredentials('https://api.example.com', '/docs'))?.assertion).toBe(
+      'next'
+    );
+  });
+
+  it('fails when neither the keyring nor the local file can be written', async () => {
+    keytar.setPassword.mockRejectedValue(new Error('locked'));
+    configDir.path = path.join(configDir.path, 'not-a-directory');
+    fs.writeFileSync(configDir.path, '');
     await expect(
       saveAgentCredentials('https://api.example.com', '/docs', credentials)
-    ).rejects.toThrow('locked');
-    expect(keytar.setPassword).toHaveBeenCalledTimes(1);
+    ).rejects.toThrow();
   });
 
   it('preserves read failures instead of treating them as an absent registration', async () => {

package/__test__/deploy.test.ts

@@ -82,12 +82,10 @@ describe('mint deploy', () => {
     const result = await prepareAgentDeployment({ ...options, apiUrl }, warn);
     expect(formatDeployment(result, apiUrl)).toContain(`Site: ${siteUrl}`);
   });
-  it('continues provisioning after keyring save failure', async () => {
-    vi.mocked(storage.saveAgentCredentials).mockRejectedValue(new Error('locked'));
-    const result = await prepareAgentDeployment(options, warn);
-    expect(result.status).toBe('ready');
-    expect(warn).toHaveBeenCalledWith(expect.stringContaining('Continuing for this run'));
-    expect(formatDeployment(result, options.apiUrl)).toContain('https://allocated.mintlify.site');
+  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');
+    expect(deployment.provisionAgentSite).not.toHaveBeenCalled();
   });
   it('persists the exchanged access token for later commands', async () => {
     await prepareAgentDeployment(options, warn);

package/__test__/validateCommand.test.ts

@@ -0,0 +1,141 @@
+import { addLog, validateBuild } from '@mintlify/previewing';
+import fs from 'fs-extra';
+import path from 'node:path';
+import { mockProcessExit } from 'vitest-mock-process';
+
+import { runCommand } from './utils.js';
+
+const { dir } = vi.hoisted(() => ({
+  dir: `${process.env.TMPDIR ?? '/tmp'}/validate-command-${process.pid}`,
+}));
+
+vi.mock('../src/helpers.js', async (importOriginal) => {
+  const mod = await importOriginal<typeof import('../src/helpers.js')>();
+  return { ...mod, CMD_EXEC_PATH: dir, autoUpgradeIfNeeded: vi.fn() };
+});
+
+vi.mock('@mintlify/previewing', async (importOriginal) => {
+  const mod = await importOriginal<typeof import('@mintlify/previewing')>();
+  return { ...mod, addLog: vi.fn(), validateBuild: vi.fn() };
+});
+
+const processExitMock = mockProcessExit();
+
+const HOME = '---\ntitle: Home\n---\n\nBody\n';
+
+const writeSite = (files: Record<string, string>, config: Record<string, unknown> = {}) => {
+  fs.emptyDirSync(dir);
+  fs.writeJSONSync(path.join(dir, 'docs.json'), {
+    theme: 'mint',
+    name: 'Test',
+    colors: { primary: '#000000' },
+    navigation: { pages: ['index'] },
+    ...config,
+  });
+  for (const [file, content] of Object.entries(files)) {
+    fs.outputFileSync(path.join(dir, file), content);
+  }
+};
+
+const logged = () => JSON.stringify(vi.mocked(addLog).mock.calls);
+
+describe('mint validate', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(validateBuild).mockResolvedValue(undefined as never);
+  });
+
+  afterAll(() => {
+    fs.removeSync(dir);
+  });
+
+  it('logs lint findings by file and exits 1 before the build', async () => {
+    writeSite({
+      'index.mdx': '---\ntitle: Home\n---\n\nline<br>\n',
+      'other.mdx': '---\ntitle: Other\n---\n\nText {broken\n',
+    });
+
+    await runCommand('validate');
+
+    const text = logged();
+    expect(text).toContain('index.mdx');
+    expect(text).toContain('must be self-closed');
+    expect(text).toContain('other.mdx');
+    expect(text).toContain('other checks were skipped for this file');
+    expect(text).toContain('2 errors');
+    expect(validateBuild).not.toHaveBeenCalled();
+    expect(processExitMock).toHaveBeenCalledWith(1);
+  });
+
+  it('continues into the build when the lint pass is clean', async () => {
+    writeSite({ 'index.mdx': HOME });
+
+    await runCommand('validate');
+
+    expect(validateBuild).toHaveBeenCalledWith(
+      expect.objectContaining({ packageName: 'mint' }),
+      expect.any(Function)
+    );
+    expect(processExitMock).not.toHaveBeenCalled();
+  });
+
+  it('keeps --disable-openapi working', async () => {
+    writeSite({ 'index.mdx': HOME }, { api: { openapi: 'missing.json' } });
+
+    await runCommand('validate', '--disable-openapi');
+
+    expect(validateBuild).toHaveBeenCalled();
+  });
+
+  it('turns rules and groups on and off', async () => {
+    writeSite({ 'index.mdx': '---\ntitle: Home\n---\n\nline<br>\n' });
+
+    await runCommand('validate', '--disable', 'content');
+    expect(logged()).toContain('parse-error');
+    expect(logged()).not.toContain('void-tags');
+
+    vi.clearAllMocks();
+    await runCommand('validate', '--disable', 'all', '--enable', 'void-tags');
+    expect(logged()).toContain('void-tags');
+    expect(processExitMock).toHaveBeenCalledWith(1);
+  });
+
+  it('rejects unknown rules and disabling parse-error', async () => {
+    writeSite({ 'index.mdx': HOME });
+
+    await runCommand('validate', '--disable', 'nope');
+    expect(logged()).toContain('unknown rule or group');
+    expect(processExitMock).toHaveBeenLastCalledWith(1);
+
+    await runCommand('validate', '--disable', 'parse-error');
+    expect(logged()).toContain("parse-error always runs and can't be disabled");
+    expect(processExitMock).toHaveBeenLastCalledWith(1);
+    expect(validateBuild).not.toHaveBeenCalled();
+  });
+
+  it('limits page findings to --files', async () => {
+    writeSite(
+      {
+        'index.mdx': '---\ntitle: Home\n---\n\nline<br>\n',
+        'other.mdx': '---\ntitle: Other\n---\n\nline<br>\n\nmore<hr>\n',
+      },
+      { navigation: { pages: ['index', 'other'] } }
+    );
+
+    await runCommand('validate', '--files', 'other.mdx');
+
+    expect(logged()).toContain('other.mdx');
+    expect(logged()).not.toContain('index.mdx');
+    expect(processExitMock).toHaveBeenCalledWith(1);
+  });
+
+  it('rejects --files that match nothing', async () => {
+    writeSite({ 'index.mdx': HOME });
+
+    await runCommand('validate', '--files', 'missing.mdx');
+
+    expect(logged()).toContain('No matching files');
+    expect(processExitMock).toHaveBeenCalledWith(1);
+    expect(validateBuild).not.toHaveBeenCalled();
+  });
+});

package/__test__/validateEngine.test.ts

@@ -0,0 +1,46 @@
+import { selectRules, UsageError } from '../src/validate/engine.js';
+import { RULES } from '../src/validate/rules/index.js';
+import { GROUPS } from '../src/validate/types.js';
+
+const ids = (rules: { id: string }[]) => rules.map(({ id }) => id);
+
+describe('selectRules', () => {
+  it('starts from every rule; --disable all empties the selection', () => {
+    expect(ids(selectRules({}))).toEqual(ids(RULES));
+    expect(ids(selectRules({ disable: ['all'] }))).toEqual([]);
+  });
+
+  it('turns on the rules of an enabled group', () => {
+    const content = ids(selectRules({ disable: ['all'], enable: ['content'] }));
+
+    expect(content).toEqual(['void-tags']);
+  });
+
+  it('applies --enable after --disable', () => {
+    expect(ids(selectRules({ disable: ['content'], enable: ['void-tags'] }))).toContain(
+      'void-tags'
+    );
+    expect(ids(selectRules({ disable: ['content'] }))).not.toContain('void-tags');
+  });
+
+  it('rejects unknown names and naming parse-error', () => {
+    expect(() => selectRules({ enable: ['nope'] })).toThrow(UsageError);
+    expect(() => selectRules({ disable: ['parse-error'] })).toThrow(
+      "parse-error always runs and can't be disabled"
+    );
+    expect(() => selectRules({ enable: ['parse-error'] })).toThrow(
+      "parse-error always runs and can't be disabled"
+    );
+  });
+
+  it('gives every rule a known group, a severity and a description', () => {
+    for (const rule of RULES) {
+      expect(GROUPS).toContain(rule.group);
+      expect(['error', 'warning']).toContain(rule.severity);
+      expect(rule.description).not.toBe('');
+      expect(rule.id).not.toBe('parse-error');
+      expect(GROUPS as string[]).not.toContain(rule.id);
+    }
+    expect(new Set(ids(RULES)).size).toBe(RULES.length);
+  });
+});