@writechoice/mint-cli 0.0.3 → 0.0.5

package/README.md

@@ -83,16 +83,10 @@ writechoice check links docs.example.com -f path/to/file.mdx
 # Validate links in a specific directory
 writechoice check links docs.example.com -d path/to/docs
 
-# Use short aliases for common flags
-writechoice check links docs.example.com -v -o my_report.json
-
 # Dry run (extract links without validating)
 writechoice check links docs.example.com --dry-run
 
-# Verbose output
-writechoice check links docs.example.com -v
-
-# Quiet mode (only generate report)
+# Quiet mode (suppress terminal output, only generate report)
 writechoice check links docs.example.com --quiet
 
 # Custom output path for report
@@ -123,14 +117,15 @@ writechoice check links docs.example.com --fix-from-report custom_report.json
 | `--dir <path>`             | `-d`  | Validate links in a specific directory                                   | -                   |
 | `--output <path>`          | `-o`  | Output path for JSON report                                              | `links_report.json` |
 | `--dry-run`                | -     | Extract and show links without validating                                | `false`             |
-| `--verbose`                | `-v`  | Print detailed progress information                                      | `false`             |
-| `--quiet`                  | -     | Suppress stdout output (only generate report)                            | `false`             |
+| `--quiet`                  | -     | Suppress terminal output (only generate report)                          | `false`             |
 | `--concurrency <number>`   | `-c`  | Number of concurrent browser tabs                                        | `25`                |
 | `--headless`               | -     | Run browser in headless mode                                             | `true`              |
 | `--no-headless`            | -     | Show browser window (for debugging)                                      | -                   |
 | `--fix`                    | -     | Automatically fix anchor links in MDX files                              | `false`             |
 | `--fix-from-report [path]` | -     | Fix anchor links from report file (optional path)                        | `links_report.json` |
 
+**Note:** Detailed progress output is shown by default. Use `--quiet` to suppress terminal output.
+
 ## How It Works
 
 ### Link Extraction
@@ -273,16 +268,22 @@ The default concurrency is set to 25 concurrent browser tabs. Adjust this based
 
 ## Examples
 
-### Validate all links with verbose output
+### Validate all links (with progress output)
+
+```bash
+writechoice check links docs.example.com
+```
+
+### Validate quietly (suppress terminal output)
 
 ```bash
-writechoice check links docs.example.com -v
+writechoice check links docs.example.com --quiet
 ```
 
 ### Validate and fix issues in one command
 
 ```bash
-writechoice check links docs.example.com --fix -v
+writechoice check links docs.example.com --fix
 ```
 
 ### Two-step fix workflow
@@ -301,7 +302,7 @@ writechoice check links docs.example.com --fix-from-report
 ### Validate specific directory
 
 ```bash
-writechoice check links docs.example.com -d docs/api -v
+writechoice check links docs.example.com -d docs/api
 ```
 
 ## Troubleshooting

package/bin/cli.js

@@ -17,7 +17,7 @@ const program = new Command();
 program
   .name("writechoice")
   .description("CLI tool for Mintlify documentation validation and utilities")
-  .version(packageJson.version, "-V, --version", "Output the current version");
+  .version(packageJson.version, "-v, --version", "Output the current version");
 
 // Validate command
 const check = program.command("check").description("Validation commands for documentation");
@@ -30,8 +30,7 @@ check
   .option("-d, --dir <path>", "Validate links in a specific directory")
   .option("-o, --output <path>", "Output path for JSON report", "links_report.json")
   .option("--dry-run", "Extract and show links without validating")
-  .option("-v, --verbose", "Print detailed progress information")
-  .option("--quiet", "Suppress stdout output (only generate report)")
+  .option("--quiet", "Suppress terminal output (only generate report)")
   .option("-c, --concurrency <number>", "Number of concurrent browser tabs", "25")
   .option("--headless", "Run browser in headless mode (default)", true)
   .option("--no-headless", "Show browser window (for debugging)")
@@ -39,6 +38,8 @@ check
   .option("--fix-from-report [path]", "Fix anchor links from report file (default: links_report.json)")
   .action(async (baseUrl, options) => {
     const { validateLinks } = await import("../src/commands/validate/links.js");
+    // Verbose is now default (true unless --quiet is specified)
+    options.verbose = !options.quiet;
     await validateLinks(baseUrl, options);
   });
 
@@ -51,10 +52,7 @@ program
 
     try {
       // Get latest version from npm
-      const latestVersion = execSync(
-        `npm view ${packageJson.name} version`,
-        { encoding: "utf-8" }
-      ).trim();
+      const latestVersion = execSync(`npm view ${packageJson.name} version`, { encoding: "utf-8" }).trim();
 
       const currentVersion = packageJson.version;
 
@@ -83,10 +81,10 @@ program
 // Check for updates on every command (non-blocking)
 async function checkForUpdates() {
   try {
-    const latestVersion = execSync(
-      `npm view ${packageJson.name} version 2>/dev/null`,
-      { encoding: "utf-8", timeout: 2000 }
-    ).trim();
+    const latestVersion = execSync(`npm view ${packageJson.name} version 2>/dev/null`, {
+      encoding: "utf-8",
+      timeout: 2000,
+    }).trim();
 
     const currentVersion = packageJson.version;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@writechoice/mint-cli",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "CLI tool for Mintlify documentation validation and utilities",
   "main": "src/index.js",
   "type": "module",

package/src/commands/validate/links.js

@@ -6,11 +6,11 @@
  * JavaScript-rendered Mintlify pages.
  */
 
-import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'fs';
-import { join, relative, resolve, dirname } from 'path';
-import { fileURLToPath } from 'url';
-import { chromium } from 'playwright';
-import chalk from 'chalk';
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from "fs";
+import { join, relative, resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+import { chromium } from "playwright";
+import chalk from "chalk";
 import {
   cleanHeadingText,
   toKebabCase,
@@ -20,15 +20,15 @@ import {
   findLineNumber,
   removeCodeBlocksAndFrontmatter,
   resolvePath as resolvePathUtil,
-} from '../../utils/helpers.js';
+} from "../../utils/helpers.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
 // Configuration
-const DEFAULT_BASE_URL = 'https://docs.nebius.com';
-const EXCLUDED_DIRS = ['snippets'];
-const MDX_DIRS = ['.'];
+const DEFAULT_BASE_URL = "https://docs.nebius.com";
+const EXCLUDED_DIRS = ["snippets"];
+const MDX_DIRS = ["."];
 const DEFAULT_TIMEOUT = 30000; // 30 seconds
 const DEFAULT_CONCURRENCY = 25;
 
@@ -75,7 +75,7 @@ class ValidationResult {
     actualHeading = null,
     actualHeadingKebab = null,
     errorMessage = null,
-    validationTimeMs = 0
+    validationTimeMs = 0,
   ) {
     this.source = source;
     this.targetUrl = targetUrl;
@@ -106,10 +106,10 @@ function urlToFilePath(url, baseUrl, repoRoot) {
     }
   }
 
-  path = path.replace(/^\/+/, '');
+  path = path.replace(/^\/+/, "");
 
-  if (!path || path === '/') {
-    const indexPath = join(repoRoot, 'index.mdx');
+  if (!path || path === "/") {
+    const indexPath = join(repoRoot, "index.mdx");
     return existsSync(indexPath) ? indexPath : null;
   }
 
@@ -118,7 +118,7 @@ function urlToFilePath(url, baseUrl, repoRoot) {
     return mdxPath;
   }
 
-  const indexPath = join(repoRoot, path, 'index.mdx');
+  const indexPath = join(repoRoot, path, "index.mdx");
   if (existsSync(indexPath)) {
     return indexPath;
   }
@@ -132,44 +132,44 @@ function resolvePath(mdxFilePath, href, baseUrl, repoRoot) {
   }
 
   let path, anchor;
-  if (href.includes('#')) {
-    [path, anchor] = href.split('#', 2);
+  if (href.includes("#")) {
+    [path, anchor] = href.split("#", 2);
   } else {
     path = href;
-    anchor = '';
+    anchor = "";
   }
 
   if (!path && anchor) {
     const relPath = relative(repoRoot, mdxFilePath);
-    const urlPath = relPath.replace(/\.mdx$/, '');
+    const urlPath = relPath.replace(/\.mdx$/, "");
     const fullUrl = normalizeUrl(`${baseUrl}/${urlPath}`);
     return `${fullUrl}#${anchor}`;
   }
 
   let fullUrl;
 
-  if (path.startsWith('/')) {
+  if (path.startsWith("/")) {
     fullUrl = normalizeUrl(baseUrl + path);
   } else {
     const mdxDir = dirname(mdxFilePath);
 
-    if (path.startsWith('./')) {
+    if (path.startsWith("./")) {
       path = path.slice(2);
     }
 
     const resolved = resolve(mdxDir, path);
 
     const relToRoot = relative(repoRoot, resolved);
-    if (relToRoot.startsWith('..')) {
+    if (relToRoot.startsWith("..")) {
       return null;
     }
 
-    const urlPath = relToRoot.replace(/\.mdx$/, '');
+    const urlPath = relToRoot.replace(/\.mdx$/, "");
     fullUrl = normalizeUrl(`${baseUrl}/${urlPath}`);
   }
 
   if (anchor) {
-    fullUrl += '#' + anchor;
+    fullUrl += "#" + anchor;
   }
 
   return fullUrl;
@@ -179,7 +179,7 @@ function resolvePath(mdxFilePath, href, baseUrl, repoRoot) {
 
 function extractMdxHeadings(filePath) {
   try {
-    const content = readFileSync(filePath, 'utf-8');
+    const content = readFileSync(filePath, "utf-8");
     const { cleanedContent } = removeCodeBlocksAndFrontmatter(content);
 
     const headingPattern = /^#{1,6}\s+(.+)$/gm;
@@ -189,7 +189,7 @@ function extractMdxHeadings(filePath) {
     while ((match = headingPattern.exec(cleanedContent)) !== null) {
       let headingText = match[1].trim();
       // Remove any trailing {#custom-id} syntax if present
-      headingText = headingText.replace(/\s*\{#[^}]+\}\s*$/, '');
+      headingText = headingText.replace(/\s*\{#[^}]+\}\s*$/, "");
       headings.push(headingText);
     }
 
@@ -206,7 +206,7 @@ function extractLinksFromFile(filePath, baseUrl, repoRoot, verbose = false) {
 
   let content;
   try {
-    content = readFileSync(filePath, 'utf-8');
+    content = readFileSync(filePath, "utf-8");
   } catch (error) {
     console.error(`Error reading ${filePath}: ${error.message}`);
     return [];
@@ -234,8 +234,8 @@ function extractLinksFromFile(filePath, baseUrl, repoRoot, verbose = false) {
   const markdownMatches = [...cleanedContent.matchAll(LINK_PATTERNS.markdown)];
   for (const match of markdownMatches) {
     // Check if this is actually an image by looking at the character before '['
-    const charBefore = match.index > 0 ? cleanedContent[match.index - 1] : '';
-    if (charBefore === '!') {
+    const charBefore = match.index > 0 ? cleanedContent[match.index - 1] : "";
+    if (charBefore === "!") {
       // This is a markdown image ![alt](url), skip it
       continue;
     }
@@ -252,21 +252,13 @@ function extractLinksFromFile(filePath, baseUrl, repoRoot, verbose = false) {
         findLineNumber(content, match.index),
         linkText.trim(),
         href,
-        'markdown'
+        "markdown",
       );
 
-      const [basePath, anchor = ''] = targetUrl.split('#');
+      const [basePath, anchor = ""] = targetUrl.split("#");
       const expectedSlug = new URL(targetUrl).pathname;
 
-      links.push(
-        new Link(
-          location,
-          targetUrl,
-          basePath,
-          anchor || null,
-          expectedSlug
-        )
-      );
+      links.push(new Link(location, targetUrl, basePath, anchor || null, expectedSlug));
     }
   }
 
@@ -285,21 +277,13 @@ function extractLinksFromFile(filePath, baseUrl, repoRoot, verbose = false) {
         findLineNumber(content, match.index),
         linkText.trim(),
         href,
-        'html'
+        "html",
       );
 
-      const [basePath, anchor = ''] = targetUrl.split('#');
+      const [basePath, anchor = ""] = targetUrl.split("#");
       const expectedSlug = new URL(targetUrl).pathname;
 
-      links.push(
-        new Link(
-          location,
-          targetUrl,
-          basePath,
-          anchor || null,
-          expectedSlug
-        )
-      );
+      links.push(new Link(location, targetUrl, basePath, anchor || null, expectedSlug));
     }
   }
 
@@ -318,21 +302,13 @@ function extractLinksFromFile(filePath, baseUrl, repoRoot, verbose = false) {
         findLineNumber(content, match.index),
         linkText.trim(),
         href,
-        'jsx'
+        "jsx",
       );
 
-      const [basePath, anchor = ''] = targetUrl.split('#');
+      const [basePath, anchor = ""] = targetUrl.split("#");
       const expectedSlug = new URL(targetUrl).pathname;
 
-      links.push(
-        new Link(
-          location,
-          targetUrl,
-          basePath,
-          anchor || null,
-          expectedSlug
-        )
-      );
+      links.push(new Link(location, targetUrl, basePath, anchor || null, expectedSlug));
     }
   }
 
@@ -351,21 +327,13 @@ function extractLinksFromFile(filePath, baseUrl, repoRoot, verbose = false) {
         findLineNumber(content, match.index),
         linkText.trim(),
         href,
-        'jsx'
+        "jsx",
       );
 
-      const [basePath, anchor = ''] = targetUrl.split('#');
+      const [basePath, anchor = ""] = targetUrl.split("#");
       const expectedSlug = new URL(targetUrl).pathname;
 
-      links.push(
-        new Link(
-          location,
-          targetUrl,
-          basePath,
-          anchor || null,
-          expectedSlug
-        )
-      );
+      links.push(new Link(location, targetUrl, basePath, anchor || null, expectedSlug));
     }
   }
 
@@ -378,9 +346,7 @@ function findMdxFiles(repoRoot, directory = null, file = null) {
     return existsSync(fullPath) ? [fullPath] : [];
   }
 
-  const searchDirs = directory
-    ? [resolve(repoRoot, directory)]
-    : MDX_DIRS.map(d => join(repoRoot, d));
+  const searchDirs = directory ? [resolve(repoRoot, directory)] : MDX_DIRS.map((d) => join(repoRoot, d));
 
   const files = [];
 
@@ -393,10 +359,10 @@ function findMdxFiles(repoRoot, directory = null, file = null) {
       const stat = statSync(fullPath);
 
       if (stat.isDirectory()) {
-        if (!EXCLUDED_DIRS.some(excluded => fullPath.includes(excluded))) {
+        if (!EXCLUDED_DIRS.some((excluded) => fullPath.includes(excluded))) {
           walkDir(fullPath);
         }
-      } else if (entry.endsWith('.mdx')) {
+      } else if (entry.endsWith(".mdx")) {
         files.push(fullPath);
       }
     }
@@ -411,7 +377,7 @@ function findMdxFiles(repoRoot, directory = null, file = null) {
 
 // Playwright Validation Functions
 
-async function validateAnchor(page, link, baseUrl, repoRoot, verbose = false, progress = '') {
+async function validateAnchor(page, link, baseUrl, repoRoot, verbose = false, progress = "") {
   const startTime = Date.now();
 
   try {
@@ -423,12 +389,12 @@ async function validateAnchor(page, link, baseUrl, repoRoot, verbose = false, pr
     const mdxFilePath = urlToFilePath(link.basePath, baseUrl, repoRoot);
     if (mdxFilePath && existsSync(mdxFilePath)) {
       const mdxHeadings = extractMdxHeadings(mdxFilePath);
-      const mdxHeadingsKebab = mdxHeadings.map(h => toKebabCase(h));
+      const mdxHeadingsKebab = mdxHeadings.map((h) => toKebabCase(h));
 
       if (mdxHeadingsKebab.includes(link.anchor)) {
-        const heading = mdxHeadings.find(h => toKebabCase(h) === link.anchor);
+        const heading = mdxHeadings.find((h) => toKebabCase(h) === link.anchor);
         if (verbose) {
-          console.log(`${progress}      ✓ Anchor validated locally in MDX file`);
+          console.log(`                   ✓ Anchor validated locally in MDX file`);
         }
         return new ValidationResult(
           link.source,
@@ -436,20 +402,20 @@ async function validateAnchor(page, link, baseUrl, repoRoot, verbose = false, pr
           link.basePath,
           link.anchor,
           link.expectedSlug,
-          'success',
+          "success",
           link.basePath,
           heading,
           link.anchor,
           null,
-          Date.now() - startTime
+          Date.now() - startTime,
         );
       } else if (verbose) {
-        console.log(`${progress}      Anchor not found in local MDX, checking online...`);
+        console.log(`                   Anchor not found in local MDX, checking online...`);
       }
     }
 
     // Navigate to base page
-    await page.goto(link.basePath, { waitUntil: 'networkidle', timeout: DEFAULT_TIMEOUT });
+    await page.goto(link.basePath, { waitUntil: "networkidle", timeout: DEFAULT_TIMEOUT });
 
     // Try to find heading by anchor
     let heading = await page.$(`#${link.anchor}`);
@@ -465,12 +431,12 @@ async function validateAnchor(page, link, baseUrl, repoRoot, verbose = false, pr
         link.basePath,
         link.anchor,
         link.expectedSlug,
-        'failure',
+        "failure",
         null,
         null,
         null,
         `Anchor #${link.anchor} not found on page`,
-        Date.now() - startTime
+        Date.now() - startTime,
       );
     }
 
@@ -482,7 +448,7 @@ async function validateAnchor(page, link, baseUrl, repoRoot, verbose = false, pr
     // Extract headings from the TARGET MDX file to verify
     const mdxFilePath2 = urlToFilePath(link.basePath, baseUrl, repoRoot);
     const mdxHeadings = mdxFilePath2 ? extractMdxHeadings(mdxFilePath2) : [];
-    const mdxHeadingsKebab = mdxHeadings.map(h => toKebabCase(h));
+    const mdxHeadingsKebab = mdxHeadings.map((h) => toKebabCase(h));
 
     const matchesMdx = mdxHeadingsKebab.includes(actualKebab);
 
@@ -494,12 +460,12 @@ async function validateAnchor(page, link, baseUrl, repoRoot, verbose = false, pr
           link.basePath,
           link.anchor,
           link.expectedSlug,
-          'success',
+          "success",
           link.basePath,
           actualTextClean,
           actualKebab,
           null,
-          Date.now() - startTime
+          Date.now() - startTime,
         );
       } else {
         return new ValidationResult(
@@ -508,12 +474,12 @@ async function validateAnchor(page, link, baseUrl, repoRoot, verbose = false, pr
           link.basePath,
           link.anchor,
           link.expectedSlug,
-          'failure',
+          "failure",
           null,
           actualTextClean,
           actualKebab,
           `Anchor "#${link.anchor}" matches page heading "${actualTextClean}" but this heading is not found in the MDX file`,
-          Date.now() - startTime
+          Date.now() - startTime,
         );
       }
     } else {
@@ -524,12 +490,12 @@ async function validateAnchor(page, link, baseUrl, repoRoot, verbose = false, pr
           link.basePath,
           link.anchor,
           link.expectedSlug,
-          'failure',
+          "failure",
           null,
           actualTextClean,
           actualKebab,
           `Expected anchor "#${link.anchor}" but page heading "${actualTextClean}" should use "#${actualKebab}"`,
-          Date.now() - startTime
+          Date.now() - startTime,
         );
       } else {
         return new ValidationResult(
@@ -538,12 +504,12 @@ async function validateAnchor(page, link, baseUrl, repoRoot, verbose = false, pr
           link.basePath,
           link.anchor,
           link.expectedSlug,
-          'failure',
+          "failure",
           null,
           actualTextClean,
           actualKebab,
           `Expected anchor "#${link.anchor}" but found heading "${actualTextClean}" (#${actualKebab}) which is not in the MDX file`,
-          Date.now() - startTime
+          Date.now() - startTime,
         );
       }
     }
@@ -554,17 +520,17 @@ async function validateAnchor(page, link, baseUrl, repoRoot, verbose = false, pr
       link.basePath,
       link.anchor,
       link.expectedSlug,
-      'error',
+      "error",
       null,
       null,
       null,
       `Error validating anchor: ${error.message}`,
-      Date.now() - startTime
+      Date.now() - startTime,
     );
   }
 }
 
-async function validateNormalLink(page, link, baseUrl, repoRoot, verbose = false, progress = '') {
+async function validateNormalLink(page, link, baseUrl, repoRoot, verbose = false, progress = "") {
   const startTime = Date.now();
 
   try {
@@ -576,7 +542,7 @@ async function validateNormalLink(page, link, baseUrl, repoRoot, verbose = false
     const mdxFilePath = urlToFilePath(link.targetUrl, baseUrl, repoRoot);
     if (mdxFilePath && existsSync(mdxFilePath)) {
       if (verbose) {
-        console.log(`${progress}      ✓ Link validated locally (file exists)`);
+        console.log(`                   ✓ Link validated locally (file exists)`);
       }
       return new ValidationResult(
         link.source,
@@ -584,19 +550,19 @@ async function validateNormalLink(page, link, baseUrl, repoRoot, verbose = false
         link.basePath,
         link.anchor,
         link.expectedSlug,
-        'success',
+        "success",
         link.targetUrl,
         null,
         null,
         null,
-        Date.now() - startTime
+        Date.now() - startTime,
       );
     } else if (verbose) {
-      console.log(`${progress}      File not found locally, checking online...`);
+      console.log(`                   File not found locally, checking online...`);
     }
 
     // Navigate to the target URL
-    const response = await page.goto(link.targetUrl, { waitUntil: 'networkidle', timeout: DEFAULT_TIMEOUT });
+    const response = await page.goto(link.targetUrl, { waitUntil: "networkidle", timeout: DEFAULT_TIMEOUT });
 
     if (!response) {
       return new ValidationResult(
@@ -605,12 +571,12 @@ async function validateNormalLink(page, link, baseUrl, repoRoot, verbose = false
         link.basePath,
         link.anchor,
         link.expectedSlug,
-        'error',
+        "error",
         null,
         null,
         null,
-        'No response received',
-        Date.now() - startTime
+        "No response received",
+        Date.now() - startTime,
       );
     }
 
@@ -623,12 +589,12 @@ async function validateNormalLink(page, link, baseUrl, repoRoot, verbose = false
         link.basePath,
         link.anchor,
         link.expectedSlug,
-        'failure',
+        "failure",
         actualUrl,
         null,
         null,
         `HTTP ${response.status()}: ${response.statusText()}`,
-        Date.now() - startTime
+        Date.now() - startTime,
       );
     }
 
@@ -638,12 +604,12 @@ async function validateNormalLink(page, link, baseUrl, repoRoot, verbose = false
       link.basePath,
       link.anchor,
       link.expectedSlug,
-      'success',
+      "success",
       actualUrl,
       null,
       null,
       null,
-      Date.now() - startTime
+      Date.now() - startTime,
     );
   } catch (error) {
     return new ValidationResult(
@@ -652,17 +618,17 @@ async function validateNormalLink(page, link, baseUrl, repoRoot, verbose = false
       link.basePath,
       link.anchor,
       link.expectedSlug,
-      'error',
+      "error",
       null,
       null,
       null,
       `Error validating link: ${error.message}`,
-      Date.now() - startTime
+      Date.now() - startTime,
     );
   }
 }
 
-async function validateLink(page, link, baseUrl, repoRoot, verbose = false, progress = '') {
+async function validateLink(page, link, baseUrl, repoRoot, verbose = false, progress = "") {
   if (link.anchor) {
     return await validateAnchor(page, link, baseUrl, repoRoot, verbose, progress);
   } else {
@@ -677,14 +643,16 @@ async function validateLinksAsync(links, baseUrl, repoRoot, concurrency, headles
   try {
     browser = await chromium.launch({ headless });
   } catch (error) {
-    if (error.message.includes('Executable doesn\'t exist') ||
-        error.message.includes('Browser was not installed') ||
-        error.message.includes('browserType.launch')) {
-      console.error(chalk.red('\n✗ Playwright browsers are not installed!'));
-      console.error(chalk.yellow('\nTo install Playwright browsers, run:'));
-      console.error(chalk.cyan('  npx playwright install chromium\n'));
-      console.error('Or install all browsers with:');
-      console.error(chalk.cyan('  npx playwright install\n'));
+    if (
+      error.message.includes("Executable doesn't exist") ||
+      error.message.includes("Browser was not installed") ||
+      error.message.includes("browserType.launch")
+    ) {
+      console.error(chalk.red("\n✗ Playwright browsers are not installed!"));
+      console.error(chalk.yellow("\nTo install Playwright browsers, run:"));
+      console.error(chalk.cyan("  npx playwright install chromium\n"));
+      console.error("Or install all browsers with:");
+      console.error(chalk.cyan("  npx playwright install\n"));
       process.exit(1);
     }
     throw error;
@@ -696,7 +664,7 @@ async function validateLinksAsync(links, baseUrl, repoRoot, concurrency, headles
   async function validateWithSemaphore(link) {
     counter++;
     const current = counter;
-    const progress = verbose ? `[${current}/${links.length}] ` : '';
+    const progress = verbose ? `[${current}/${links.length}] ` : "";
 
     const context = await browser.newContext();
     const page = await context.newPage();
@@ -716,7 +684,7 @@ async function validateLinksAsync(links, baseUrl, repoRoot, concurrency, headles
   // Process links with concurrency control
   for (let i = 0; i < links.length; i += concurrency) {
     const batch = links.slice(i, i + concurrency);
-    const batchResults = await Promise.all(batch.map(link => validateWithSemaphore(link)));
+    const batchResults = await Promise.all(batch.map((link) => validateWithSemaphore(link)));
     results.push(...batchResults);
   }
 
@@ -735,7 +703,7 @@ function fixLinksFromReport(reportPath, repoRoot, verbose = false) {
 
   let reportData;
   try {
-    reportData = JSON.parse(readFileSync(reportPath, 'utf-8'));
+    reportData = JSON.parse(readFileSync(reportPath, "utf-8"));
   } catch (error) {
     console.error(`Error reading report file: ${error.message}`);
     return {};
@@ -745,7 +713,7 @@ function fixLinksFromReport(reportPath, repoRoot, verbose = false) {
 
   if (Object.keys(resultsByFile).length === 0) {
     if (verbose) {
-      console.log('No failures found in report.');
+      console.log("No failures found in report.");
     }
     return {};
   }
@@ -762,15 +730,13 @@ function fixLinksFromReport(reportPath, repoRoot, verbose = false) {
       continue;
     }
 
-    const fixableFailures = failures.filter(
-      f => f.status === 'failure' && f.actual_heading_kebab && f.anchor
-    );
+    const fixableFailures = failures.filter((f) => f.status === "failure" && f.actual_heading_kebab && f.anchor);
 
     if (fixableFailures.length === 0) continue;
 
     try {
-      const content = readFileSync(fullPath, 'utf-8');
-      let lines = content.split('\n');
+      const content = readFileSync(fullPath, "utf-8");
+      let lines = content.split("\n");
       let modified = false;
       let fixesCount = 0;
 
@@ -791,7 +757,7 @@ function fixLinksFromReport(reportPath, repoRoot, verbose = false) {
         const newAnchor = failure.actual_heading_kebab;
         const linkType = failure.source.link_type;
 
-        const pathPart = oldHref.includes('#') ? oldHref.split('#')[0] : oldHref;
+        const pathPart = oldHref.includes("#") ? oldHref.split("#")[0] : oldHref;
         const newHref = pathPart ? `${pathPart}#${newAnchor}` : `#${newAnchor}`;
 
         if (oldHref === newHref) {
@@ -803,14 +769,14 @@ function fixLinksFromReport(reportPath, repoRoot, verbose = false) {
 
         let replaced = false;
 
-        if (linkType === 'markdown') {
+        if (linkType === "markdown") {
           const oldPattern = `(${oldHref})`;
           const newPattern = `(${newHref})`;
           if (line.includes(oldPattern)) {
             line = line.replace(oldPattern, newPattern);
             replaced = true;
           }
-        } else if (linkType === 'html' || linkType === 'jsx') {
+        } else if (linkType === "html" || linkType === "jsx") {
           for (const quote of ['"', "'"]) {
             const oldPattern = `href=${quote}${oldHref}${quote}`;
             const newPattern = `href=${quote}${newHref}${quote}`;
@@ -838,8 +804,8 @@ function fixLinksFromReport(reportPath, repoRoot, verbose = false) {
       }
 
       if (modified) {
-        const newContent = lines.join('\n');
-        writeFileSync(fullPath, newContent, 'utf-8');
+        const newContent = lines.join("\n");
+        writeFileSync(fullPath, newContent, "utf-8");
         fixesApplied[filePath] = fixesCount;
 
         if (verbose) {
@@ -860,7 +826,7 @@ function fixLinks(results, repoRoot, verbose = false) {
   const failuresByFile = {};
 
   for (const result of results) {
-    if (result.status !== 'failure' || !result.actualHeadingKebab || !result.anchor) {
+    if (result.status !== "failure" || !result.actualHeadingKebab || !result.anchor) {
       continue;
     }
 
@@ -885,8 +851,8 @@ function fixLinks(results, repoRoot, verbose = false) {
     }
 
     try {
-      const content = readFileSync(fullPath, 'utf-8');
-      let lines = content.split('\n');
+      const content = readFileSync(fullPath, "utf-8");
+      let lines = content.split("\n");
       let modified = false;
       let fixesCount = 0;
 
@@ -906,7 +872,7 @@ function fixLinks(results, repoRoot, verbose = false) {
         const oldHref = failure.source.rawHref;
         const linkType = failure.source.linkType;
 
-        const pathPart = oldHref.includes('#') ? oldHref.split('#')[0] : oldHref;
+        const pathPart = oldHref.includes("#") ? oldHref.split("#")[0] : oldHref;
         const newHref = pathPart ? `${pathPart}#${failure.actualHeadingKebab}` : `#${failure.actualHeadingKebab}`;
 
         if (oldHref === newHref) {
@@ -918,14 +884,14 @@ function fixLinks(results, repoRoot, verbose = false) {
 
         let replaced = false;
 
-        if (linkType === 'markdown') {
+        if (linkType === "markdown") {
           const oldPattern = `(${oldHref})`;
           const newPattern = `(${newHref})`;
           if (line.includes(oldPattern)) {
             line = line.replace(oldPattern, newPattern);
             replaced = true;
           }
-        } else if (linkType === 'html' || linkType === 'jsx') {
+        } else if (linkType === "html" || linkType === "jsx") {
           for (const quote of ['"', "'"]) {
             const oldPattern = `href=${quote}${oldHref}${quote}`;
             const newPattern = `href=${quote}${newHref}${quote}`;
@@ -953,8 +919,8 @@ function fixLinks(results, repoRoot, verbose = false) {
       }
 
       if (modified) {
-        const newContent = lines.join('\n');
-        writeFileSync(fullPath, newContent, 'utf-8');
+        const newContent = lines.join("\n");
+        writeFileSync(fullPath, newContent, "utf-8");
         fixesApplied[filePath] = fixesCount;
 
         if (verbose) {
@@ -975,9 +941,9 @@ function fixLinks(results, repoRoot, verbose = false) {
 
 function generateReport(results, config, outputPath) {
   const total = results.length;
-  const success = results.filter(r => r.status === 'success').length;
-  const failure = results.filter(r => r.status === 'failure').length;
-  const error = results.filter(r => r.status === 'error').length;
+  const success = results.filter((r) => r.status === "success").length;
+  const failure = results.filter((r) => r.status === "failure").length;
+  const error = results.filter((r) => r.status === "error").length;
 
   const summaryByFile = {};
   for (const result of results) {
@@ -992,7 +958,7 @@ function generateReport(results, config, outputPath) {
 
   const resultsByFile = {};
   for (const result of results) {
-    if (result.status === 'success') continue;
+    if (result.status === "success") continue;
 
     const filePath = result.source.filePath;
     if (!resultsByFile[filePath]) {
@@ -1015,7 +981,7 @@ function generateReport(results, config, outputPath) {
     results_by_file: resultsByFile,
   };
 
-  writeFileSync(outputPath, JSON.stringify(report, null, 2), 'utf-8');
+  writeFileSync(outputPath, JSON.stringify(report, null, 2), "utf-8");
 
   return report;
 }
@@ -1028,19 +994,14 @@ export async function validateLinks(baseUrl, options) {
   // Handle --fix-from-report mode
   if (options.fixFromReport !== undefined) {
     // If flag is passed with a path, use that path; otherwise use default
-    const reportPath = typeof options.fixFromReport === 'string' && options.fixFromReport
-      ? options.fixFromReport
-      : 'links_report.json';
+    const reportPath =
+      typeof options.fixFromReport === "string" && options.fixFromReport ? options.fixFromReport : "links_report.json";
 
     if (!options.quiet) {
       console.log(`Applying fixes from report: ${reportPath}`);
     }
 
-    const fixesApplied = fixLinksFromReport(
-      reportPath,
-      repoRoot,
-      options.verbose && !options.quiet
-    );
+    const fixesApplied = fixLinksFromReport(reportPath, repoRoot, options.verbose && !options.quiet);
 
     if (!options.quiet) {
       if (Object.keys(fixesApplied).length > 0) {
@@ -1049,9 +1010,9 @@ export async function validateLinks(baseUrl, options) {
         for (const [filePath, count] of Object.entries(fixesApplied)) {
           console.log(`  ${filePath}: ${count} fix(es)`);
         }
-        console.log('\nRun validation again to verify the fixes.');
+        console.log("\nRun validation again to verify the fixes.");
       } else {
-        console.log('\nNo fixable issues found in report.');
+        console.log("\nNo fixable issues found in report.");
       }
     }
 
@@ -1060,20 +1021,20 @@ export async function validateLinks(baseUrl, options) {
 
   // Normalize base URL - add https:// if not present
   let normalizedBaseUrl = baseUrl;
-  if (!normalizedBaseUrl.startsWith('http://') && !normalizedBaseUrl.startsWith('https://')) {
-    normalizedBaseUrl = 'https://' + normalizedBaseUrl;
+  if (!normalizedBaseUrl.startsWith("http://") && !normalizedBaseUrl.startsWith("https://")) {
+    normalizedBaseUrl = "https://" + normalizedBaseUrl;
   }
   // Remove trailing slash
-  normalizedBaseUrl = normalizedBaseUrl.replace(/\/+$/, '');
+  normalizedBaseUrl = normalizedBaseUrl.replace(/\/+$/, "");
 
   if (options.verbose && !options.quiet) {
-    console.log('Finding MDX files...');
+    console.log("Finding MDX files...");
   }
 
   const mdxFiles = findMdxFiles(repoRoot, options.dir, options.file);
 
   if (mdxFiles.length === 0) {
-    console.error('No MDX files found.');
+    console.error("No MDX files found.");
     process.exit(1);
   }
 
@@ -1082,7 +1043,7 @@ export async function validateLinks(baseUrl, options) {
   }
 
   if (options.verbose && !options.quiet) {
-    console.log('Extracting links...');
+    console.log("Extracting links...");
   }
 
   const allLinks = [];
@@ -1092,7 +1053,7 @@ export async function validateLinks(baseUrl, options) {
   }
 
   if (allLinks.length === 0) {
-    console.log('No internal links found.');
+    console.log("No internal links found.");
     return;
   }
 
@@ -1101,7 +1062,7 @@ export async function validateLinks(baseUrl, options) {
   }
 
   if (options.dryRun) {
-    console.log('\nExtracted links:');
+    console.log("\nExtracted links:");
     allLinks.forEach((link, i) => {
       console.log(`\n${i + 1}. ${link.source.filePath}:${link.source.lineNumber}`);
       console.log(`   Text: ${link.source.linkText}`);
@@ -1117,7 +1078,7 @@ export async function validateLinks(baseUrl, options) {
   const startTime = Date.now();
 
   if (!options.quiet) {
-    console.log('\nValidating links...');
+    console.log("\nValidating links...");
   }
 
   const results = await validateLinksAsync(
@@ -1126,14 +1087,14 @@ export async function validateLinks(baseUrl, options) {
     repoRoot,
     parseInt(options.concurrency) || DEFAULT_CONCURRENCY,
     options.headless !== false,
-    options.verbose && !options.quiet
+    options.verbose && !options.quiet,
   );
 
   const executionTime = (Date.now() - startTime) / 1000;
 
   if (options.fix) {
     if (!options.quiet) {
-      console.log('\nApplying fixes...');
+      console.log("\nApplying fixes...");
     }
 
     const fixesApplied = fixLinks(results, repoRoot, options.verbose && !options.quiet);
@@ -1145,9 +1106,9 @@ export async function validateLinks(baseUrl, options) {
         for (const [filePath, count] of Object.entries(fixesApplied)) {
           console.log(`  ${filePath}: ${count} fix(es)`);
         }
-        console.log('\nRun validation again to verify the fixes.');
+        console.log("\nRun validation again to verify the fixes.");
       } else {
-        console.log('\nNo fixable issues found.');
+        console.log("\nNo fixable issues found.");
       }
     }
   }
@@ -1160,23 +1121,23 @@ export async function validateLinks(baseUrl, options) {
     execution_time_seconds: Math.round(executionTime * 100) / 100,
   };
 
-  const report = generateReport(results, config, options.output || 'links_report.json');
+  const report = generateReport(results, config, options.output || "links_report.json");
 
   if (!options.quiet) {
-    console.log(`\n${'='.repeat(60)}`);
-    console.log('VALIDATION SUMMARY');
-    console.log('='.repeat(60));
+    console.log(`\n${"=".repeat(60)}`);
+    console.log("VALIDATION SUMMARY");
+    console.log("=".repeat(60));
     console.log(`Total links:    ${report.summary.total_links}`);
-    console.log(`Success:        ${chalk.green(report.summary.success + ' ✓')}`);
-    console.log(`Failure:        ${chalk.red(report.summary.failure + ' ✗')}`);
-    console.log(`Error:          ${chalk.yellow(report.summary.error + ' ⚠')}`);
+    console.log(`Success:        ${chalk.green(report.summary.success + " ✓")}`);
+    console.log(`Failure:        ${chalk.red(report.summary.failure + " ✗")}`);
+    console.log(`Error:          ${chalk.yellow(report.summary.error + " ⚠")}`);
     console.log(`Execution time: ${executionTime.toFixed(2)}s`);
-    console.log(`\nReport saved to: ${options.output || 'links_report.json'}`);
+    console.log(`\nReport saved to: ${options.output || "links_report.json"}`);
 
     if (report.summary.failure > 0 || report.summary.error > 0) {
-      console.log(`\n${'='.repeat(60)}`);
-      console.log('ISSUES FOUND');
-      console.log('='.repeat(60));
+      console.log(`\n${"=".repeat(60)}`);
+      console.log("ISSUES FOUND");
+      console.log("=".repeat(60));
       let shown = 0;
 
       for (const [filePath, fileResults] of Object.entries(report.results_by_file)) {
@@ -1196,7 +1157,9 @@ export async function validateLinks(baseUrl, options) {
 
       if (shown < report.summary.failure + report.summary.error) {
         const remaining = report.summary.failure + report.summary.error - shown;
-        console.log(`\n... and ${remaining} more issues. See ${options.output || 'links_report.json'} for full details.`);
+        console.log(
+          `\n... and ${remaining} more issues. See ${options.output || "links_report.json"} for full details.`,
+        );
       }
     }
   }