@mintlify/cli 4.0.1734 → 4.0.1736

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/bin/agent-claim.js

@@ -45,8 +45,8 @@ 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 = () => { }) {
+export function claimDeployment(options_1) {
+    return __awaiter(this, arguments, void 0, function* (options, progress = () => { }) {
         var _a, _b;
         const { apiUrl, directory } = options;
         const code = (_a = options.code) === null || _a === void 0 ? void 0 : _a.trim();
@@ -66,14 +66,7 @@ export function claimDeployment(options_1, warn_1) {
         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.');
-            }
-        });
+        const save = (value) => saveAgentCredentials(apiUrl, directory, value);
         if (!credentials.claimVerified) {
             progress('Completing the WorkOS claim...');
             const completed = yield agentResponse(yield agentRequest(`${discovery.agent_auth.claim_endpoint.replace(/\/$/, '')}/complete`, {

package/bin/agent-credentials.js

@@ -7,11 +7,25 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 import { createHash } from 'node:crypto';
+import fs from 'node:fs/promises';
 import path from 'node:path';
 import { z } from 'zod';
+import { CONFIG_DIR } from './constants.js';
 import { getKeytar } from './keyring.js';
 const service = 'mintlify-agent';
+const fallbackFile = () => path.join(CONFIG_DIR, 'agent-credentials.json');
 export const agentCredentialsSchema = z.object({
     registrationId: z.string().min(1),
     issuer: z.url(),
@@ -29,13 +43,69 @@ function projectAccount(apiUrl, directory) {
 function registrationAccount(apiUrl, registrationId) {
     return `${new URL(apiUrl).origin}:${registrationId}`;
 }
+function readFallback() {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            return z
+                .record(z.string(), z.string())
+                .parse(JSON.parse(yield fs.readFile(fallbackFile(), 'utf-8')));
+        }
+        catch (_a) {
+            return {};
+        }
+    });
+}
+function writeFallback(entries) {
+    return __awaiter(this, void 0, void 0, function* () {
+        yield fs.mkdir(CONFIG_DIR, { recursive: true });
+        const temp = `${fallbackFile()}.${process.pid}.tmp`;
+        yield fs.writeFile(temp, JSON.stringify(entries, null, 2), { mode: 0o600 });
+        yield fs.chmod(temp, 0o600);
+        yield fs.rename(temp, fallbackFile());
+    });
+}
+function getSecret(account) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let keyringError;
+        try {
+            const value = yield (yield getKeytar()).getPassword(service, account);
+            if (value)
+                return value;
+        }
+        catch (error) {
+            keyringError = error;
+        }
+        const value = (yield readFallback())[account];
+        if (value)
+            return value;
+        if (keyringError)
+            throw keyringError;
+        return null;
+    });
+}
+function setSecret(account, value) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            yield (yield getKeytar()).setPassword(service, account, value);
+        }
+        catch (_a) {
+            yield writeFallback(Object.assign(Object.assign({}, (yield readFallback())), { [account]: value }));
+            yield getKeytar()
+                .then((keytar) => keytar.deletePassword(service, account))
+                .catch(() => { });
+            return;
+        }
+        const _b = yield readFallback(), _c = account, stale = _b[_c], rest = __rest(_b, [typeof _c === "symbol" ? _c : _c + ""]);
+        if (stale)
+            yield writeFallback(rest).catch(() => { });
+    });
+}
 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));
+        const registrationId = yield getSecret(projectAccount(apiUrl, directory));
         if (!registrationId)
             return null;
-        const value = yield keytar.getPassword(service, registrationAccount(apiUrl, registrationId));
+        const value = yield getSecret(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));
@@ -48,8 +118,7 @@ export function loadAgentCredentials(apiUrl, directory) {
 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);
+        yield setSecret(registrationAccount(apiUrl, value.registrationId), JSON.stringify(value));
+        yield setSecret(projectAccount(apiUrl, directory), value.registrationId);
     });
 }

package/bin/cli.js

@@ -115,7 +115,7 @@ export const cli = ({ packageName = 'mint' }) => {
         .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`));
+            const message = yield claimDeployment({ apiUrl: API_URL, directory: argv.directory, code: argv.code, email: argv.email }, (message) => process.stderr.write(`${message}\n`));
             process.stdout.write(`${message}\n`);
             yield terminate(0);
         }

package/bin/deploy.js

@@ -33,14 +33,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 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.');
-            }
-        });
+        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));
             void trackEvent('agent_signup.discovered', { registration_id: credentials.registrationId });