@mintlify/cli 4.0.1023 → 4.0.1025

package/__test__/workflow.test.ts

@@ -0,0 +1,318 @@
+import * as previewing from '@mintlify/previewing';
+import fse from 'fs-extra';
+import path from 'path';
+
+import { addWorkflow, slugify, buildFrontmatter, isValidCron } from '../src/workflow.js';
+
+const FAKE_PROJECT = '/fake/project';
+const WORKFLOWS_DIR = path.join(FAKE_PROJECT, '.mintlify', 'workflows');
+
+vi.mock('@inquirer/prompts', () => ({
+  select: vi.fn(),
+  input: vi.fn(),
+  editor: vi.fn(),
+}));
+
+vi.mock('@mintlify/previewing', () => ({
+  addLog: vi.fn(),
+  addLogs: vi.fn(),
+  SuccessLog: vi.fn(),
+}));
+
+vi.mock('fs-extra', () => ({
+  default: {
+    pathExists: vi.fn(),
+    ensureDir: vi.fn().mockResolvedValue(undefined),
+    writeFile: vi.fn().mockResolvedValue(undefined),
+  },
+}));
+
+vi.mock('../src/constants.js', () => ({
+  CMD_EXEC_PATH: '/fake/project',
+}));
+
+const addLogSpy = vi.mocked(previewing.addLog);
+
+describe('slugify', () => {
+  it('converts spaces to hyphens', () => {
+    expect(slugify('Update changelog')).toBe('update-changelog');
+  });
+
+  it('replaces special characters with hyphens', () => {
+    expect(slugify('My Workflow!@#$%')).toBe('my-workflow');
+  });
+
+  it('replaces slashes with hyphens like the dashboard', () => {
+    expect(slugify('a/b')).toBe('a-b');
+  });
+
+  it('collapses multiple hyphens', () => {
+    expect(slugify('a   b---c')).toBe('a-b-c');
+  });
+
+  it('trims leading and trailing hyphens', () => {
+    expect(slugify('  --hello--  ')).toBe('hello');
+  });
+
+  it('lowercases the result', () => {
+    expect(slugify('UPPER CASE')).toBe('upper-case');
+  });
+
+  it('handles single word', () => {
+    expect(slugify('deploy')).toBe('deploy');
+  });
+});
+
+describe('isValidCron', () => {
+  it('accepts standard 5-field expressions', () => {
+    expect(isValidCron('0 9 * * 1')).toBe(true);
+    expect(isValidCron('*/15 * * * *')).toBe(true);
+    expect(isValidCron('0 0 1 1 *')).toBe(true);
+  });
+
+  it('accepts ranges and lists', () => {
+    expect(isValidCron('0 9-17 * * 1-5')).toBe(true);
+    expect(isValidCron('0,30 * * * *')).toBe(true);
+  });
+
+  it('rejects invalid expressions', () => {
+    expect(isValidCron('0 xd f gasf')).toBe(false);
+    expect(isValidCron('not a cron')).toBe(false);
+    expect(isValidCron('')).toBe(false);
+  });
+
+  it('rejects wrong number of fields', () => {
+    expect(isValidCron('* * *')).toBe(false);
+    expect(isValidCron('* * * * * *')).toBe(false);
+  });
+});
+
+describe('buildFrontmatter', () => {
+  it('builds cron trigger frontmatter', () => {
+    const result = buildFrontmatter({
+      name: 'Update changelog',
+      triggerType: 'cron',
+      cronExpression: '0 9 * * 1',
+      automerge: false,
+    });
+    expect(result).toBe('---\nname: "Update changelog"\non:\n  cron: "0 9 * * 1"\n---');
+  });
+
+  it('builds push trigger frontmatter with repos', () => {
+    const result = buildFrontmatter({
+      name: 'Deploy docs',
+      triggerType: 'push',
+      triggerRepos: ['org/docs', 'org/api'],
+      automerge: false,
+    });
+    expect(result).toBe(
+      '---\nname: "Deploy docs"\non:\n  push:\n    - repo: "org/docs"\n    - repo: "org/api"\n---'
+    );
+  });
+
+  it('builds push trigger with no repos', () => {
+    const result = buildFrontmatter({
+      name: 'Deploy',
+      triggerType: 'push',
+      automerge: false,
+    });
+    expect(result).toBe('---\nname: "Deploy"\non:\n  push:\n---');
+  });
+
+  it('includes context repos', () => {
+    const result = buildFrontmatter({
+      name: 'Test',
+      triggerType: 'cron',
+      cronExpression: '0 9 * * 1',
+      contextRepos: ['org/repo1', 'org/repo2'],
+      automerge: false,
+    });
+    expect(result).toContain('context:\n  - repo: "org/repo1"\n  - repo: "org/repo2"');
+  });
+
+  it('includes automerge only when true', () => {
+    const result = buildFrontmatter({
+      name: 'Test',
+      triggerType: 'cron',
+      cronExpression: '0 9 * * 1',
+      automerge: true,
+    });
+    expect(result).toContain('automerge: true');
+  });
+
+  it('omits automerge when false', () => {
+    const result = buildFrontmatter({
+      name: 'Test',
+      triggerType: 'cron',
+      cronExpression: '0 9 * * 1',
+      automerge: false,
+    });
+    expect(result).not.toContain('automerge');
+  });
+
+  it('escapes quotes in name', () => {
+    const result = buildFrontmatter({
+      name: 'My "Test" Workflow',
+      triggerType: 'cron',
+      cronExpression: '0 9 * * 1',
+      automerge: false,
+    });
+    expect(result).toContain('name: "My \\"Test\\" Workflow"');
+  });
+});
+
+describe('addWorkflow', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('throws when docs.json does not exist', async () => {
+    vi.mocked(fse.pathExists).mockResolvedValue(false as never);
+
+    await expect(addWorkflow()).rejects.toThrow(
+      'docs.json not found in the current directory. Please run this command from your docs repository root.'
+    );
+  });
+
+  it('outputs AI usage message when not interactive', async () => {
+    vi.mocked(fse.pathExists).mockResolvedValue(true as never);
+    const originalIsTTY = process.stdin.isTTY;
+    process.stdin.isTTY = false;
+
+    await addWorkflow();
+
+    expect(previewing.addLogs).toHaveBeenCalled();
+
+    process.stdin.isTTY = originalIsTTY;
+  });
+
+  it('throws when workflow name has no alphanumeric characters', async () => {
+    vi.mocked(fse.pathExists).mockResolvedValue(true as never);
+    const originalIsTTY = process.stdin.isTTY;
+    const originalClaudeCode = process.env.CLAUDECODE;
+    process.stdin.isTTY = true;
+    delete process.env.CLAUDECODE;
+
+    const { input } = await import('@inquirer/prompts');
+    vi.mocked(input).mockResolvedValueOnce('!!!');
+
+    await expect(addWorkflow()).rejects.toThrow(
+      'Workflow name must contain at least one alphanumeric character.'
+    );
+
+    process.stdin.isTTY = originalIsTTY;
+    if (originalClaudeCode === undefined) {
+      delete process.env.CLAUDECODE;
+    } else {
+      process.env.CLAUDECODE = originalClaudeCode;
+    }
+  });
+
+  it('throws when workflow file already exists', async () => {
+    // pathExists returns true for both docs.json and the workflow file
+    vi.mocked(fse.pathExists).mockResolvedValue(true as never);
+    const originalIsTTY = process.stdin.isTTY;
+    const originalClaudeCode = process.env.CLAUDECODE;
+    process.stdin.isTTY = true;
+    delete process.env.CLAUDECODE;
+
+    const { input, select, editor } = await import('@inquirer/prompts');
+    vi.mocked(input)
+      .mockResolvedValueOnce('My Workflow') // workflow name
+      .mockResolvedValueOnce('0 9 * * 1') // cron expression
+      .mockResolvedValueOnce(''); // context repos
+    vi.mocked(select)
+      .mockResolvedValueOnce('cron') // trigger type
+      .mockResolvedValueOnce('no'); // automerge
+    vi.mocked(editor).mockResolvedValueOnce('Do the thing');
+
+    const expectedRelative = path.join('.mintlify', 'workflows', 'my-workflow.md');
+    await expect(addWorkflow()).rejects.toThrow(
+      `A workflow already exists at ${expectedRelative}. Please choose a different name or delete the existing file.`
+    );
+    expect(fse.writeFile).not.toHaveBeenCalled();
+
+    process.stdin.isTTY = originalIsTTY;
+    if (originalClaudeCode === undefined) {
+      delete process.env.CLAUDECODE;
+    } else {
+      process.env.CLAUDECODE = originalClaudeCode;
+    }
+  });
+
+  it('creates cron workflow file with correct content', async () => {
+    // true for docs.json, false for workflow file existence check
+    vi.mocked(fse.pathExists)
+      .mockResolvedValueOnce(true as never)
+      .mockResolvedValueOnce(false as never);
+    const originalIsTTY = process.stdin.isTTY;
+    const originalClaudeCode = process.env.CLAUDECODE;
+    process.stdin.isTTY = true;
+    delete process.env.CLAUDECODE;
+
+    const { input, select, editor } = await import('@inquirer/prompts');
+    vi.mocked(input)
+      .mockResolvedValueOnce('My Test Workflow') // workflow name
+      .mockResolvedValueOnce('0 9 * * 1') // cron expression
+      .mockResolvedValueOnce(''); // context repos
+    vi.mocked(select)
+      .mockResolvedValueOnce('cron') // trigger type
+      .mockResolvedValueOnce('no'); // automerge
+    vi.mocked(editor).mockResolvedValueOnce('Do the thing');
+
+    await addWorkflow();
+
+    expect(fse.ensureDir).toHaveBeenCalledWith(WORKFLOWS_DIR);
+    expect(fse.writeFile).toHaveBeenCalledWith(
+      path.join(WORKFLOWS_DIR, 'my-test-workflow.md'),
+      '---\nname: "My Test Workflow"\non:\n  cron: "0 9 * * 1"\n---\n\nDo the thing\n'
+    );
+    const expectedRelative = path.join('.mintlify', 'workflows', 'my-test-workflow.md');
+    expect(addLogSpy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        props: { message: `Workflow created at ${expectedRelative}` },
+      })
+    );
+
+    process.stdin.isTTY = originalIsTTY;
+    if (originalClaudeCode === undefined) {
+      delete process.env.CLAUDECODE;
+    } else {
+      process.env.CLAUDECODE = originalClaudeCode;
+    }
+  });
+
+  it('creates push trigger workflow with automerge and context', async () => {
+    vi.mocked(fse.pathExists)
+      .mockResolvedValueOnce(true as never)
+      .mockResolvedValueOnce(false as never);
+    const originalIsTTY = process.stdin.isTTY;
+    const originalClaudeCode = process.env.CLAUDECODE;
+    process.stdin.isTTY = true;
+    delete process.env.CLAUDECODE;
+
+    const { input, select, editor } = await import('@inquirer/prompts');
+    vi.mocked(input)
+      .mockResolvedValueOnce('Deploy Docs') // workflow name
+      .mockResolvedValueOnce('org/docs') // trigger repos
+      .mockResolvedValueOnce('org/server'); // context repos
+    vi.mocked(select)
+      .mockResolvedValueOnce('push') // trigger type
+      .mockResolvedValueOnce('yes'); // automerge
+    vi.mocked(editor).mockResolvedValueOnce('Deploy the docs');
+
+    await addWorkflow();
+
+    expect(fse.writeFile).toHaveBeenCalledWith(
+      path.join(WORKFLOWS_DIR, 'deploy-docs.md'),
+      '---\nname: "Deploy Docs"\non:\n  push:\n    - repo: "org/docs"\ncontext:\n  - repo: "org/server"\nautomerge: true\n---\n\nDeploy the docs\n'
+    );
+
+    process.stdin.isTTY = originalIsTTY;
+    if (originalClaudeCode === undefined) {
+      delete process.env.CLAUDECODE;
+    } else {
+      process.env.CLAUDECODE = originalClaudeCode;
+    }
+  });
+});

package/bin/cli.js

@@ -23,6 +23,7 @@ import { mdxLinter } from './mdxLinter.js';
 import { migrateMdx } from './migrateMdx.js';
 import { scrapeSite, scrapePage, scrapeOpenApi } from './scrape.js';
 import { update } from './update.js';
+import { addWorkflow } from './workflow.js';
 export const cli = ({ packageName = 'mint' }) => {
     render(_jsx(Logs, {}));
     return (yargs(hideBin(process.argv))
@@ -329,6 +330,16 @@ export const cli = ({ packageName = 'mint' }) => {
             addLog(_jsx(ErrorLog, { message: error instanceof Error ? error.message : 'error occurred' }));
             yield terminate(1);
         }
+    }))
+        .command('workflow', 'Add a workflow to your documentation repository', () => undefined, () => __awaiter(void 0, void 0, void 0, function* () {
+        try {
+            yield addWorkflow();
+            yield terminate(0);
+        }
+        catch (error) {
+            addLog(_jsx(ErrorLog, { message: error instanceof Error ? error.message : 'error occurred' }));
+            yield terminate(1);
+        }
     }))
         .command('scrape', 'Scrape documentation from external sites', (yargs) => yargs
         .command(['$0 <url>', 'site <url>'], 'Scrape an entire documentation site', (yargs) => yargs