@writechoice/mint-cli 0.0.18 → 0.0.20

package/README.md

@@ -2,307 +2,105 @@
 
 CLI tool for Mintlify documentation validation and utilities.
 
-## Quick Start
-
-### Installation
+## Installation
 
 ```bash
 npm install -g @writechoice/mint-cli
 npx playwright install chromium
 ```
 
-### Usage
+## Quick Start
 
 ```bash
-# Check version
-writechoice --version
+# Generate a config.json with your docs URL
+writechoice config
 
-# Update to latest
-writechoice update
+# Edit config.json and set your source URL
+# "source": "https://docs.example.com"
 
-# Validate MDX parsing
+# Then run any command without arguments
 writechoice check parse
-
-# Validate links
-writechoice check links https://docs.example.com
-
-# Validate with local development server
-writechoice check links docs.example.com http://localhost:3000
-
-# Fix broken anchor links
-writechoice fix links
-
-# Fix MDX parsing errors (void tags, stray angle brackets)
-writechoice fix parse
-
-# Generate config.json template
-writechoice config
+writechoice check links
+writechoice metadata
 ```
 
 ## Commands
 
-### `config`
+### Validate
 
-Generates a config.json template file with all available options.
+| Command | Description |
+|---|---|
+| `writechoice check parse` | Validate MDX files for parsing errors |
+| `writechoice check links [baseUrl]` | Validate internal links and anchors using Playwright |
 
-```bash
-writechoice config                         # Create config.json
-writechoice config --force                 # Overwrite existing config.json
-```
-
-**Output:** Creates `config.json` in the current directory with placeholder values.
-
-### `check parse`
+### Fix
 
-Validates MDX files for parsing errors.
-
-```bash
-writechoice check parse                    # All files
-writechoice check parse -f file.mdx        # Single file
-writechoice check parse -d docs            # Specific directory
-```
+| Command | Description |
+|---|---|
+| `writechoice fix parse` | Fix void tags and stray angle brackets |
+| `writechoice fix links` | Fix broken anchor links from a validation report |
+| `writechoice fix codeblocks` | Add/remove `expandable`, `lines`, `wrap` on code blocks |
+| `writechoice fix images` | Wrap standalone images in `<Frame>` |
+| `writechoice fix inlineimages` | Convert inline images to `<InlineImage>` |
+| `writechoice fix h1` | Remove H1 headings that duplicate the frontmatter title |
 
-**Output:** Both `mdx_errors_report.json` and `mdx_errors_report.md`
-
-### `check links`
-
-Validates internal links and anchors using browser automation.
-
-```bash
-writechoice check links <baseUrl> [validationBaseUrl]
-```
-
-**Common options:**
-- `-f, --file <path>` - Validate single file
-- `-d, --dir <path>` - Validate specific directory
-- `-o, --output <path>` - Base name for reports (default: `links_report`)
-- `-c, --concurrency <number>` - Concurrent browser tabs (default: 25)
-- `--quiet` - Suppress output
-- `--dry-run` - Extract links without validating
-
-**Output:** Both `links_report.json` and `links_report.md`
-
-### `fix links`
-
-Automatically fixes broken anchor links based on validation reports.
-
-```bash
-writechoice fix links                      # Use default report
-writechoice fix links -r custom_report.json  # Use custom report
-```
-
-**Common options:**
-- `-r, --report <path>` - Path to JSON report (default: `links_report.json`)
-- `--quiet` - Suppress output
-
-**Note:** Requires JSON report from `check links` command.
-
-### `fix parse`
-
-Automatically fixes common MDX parsing errors: void HTML tags not self-closed and stray angle brackets in text.
-
-```bash
-writechoice fix parse                        # Fix from check parse report
-writechoice fix parse -f file.mdx            # Fix a single file directly
-writechoice fix parse -d docs                # Fix files in a directory
-writechoice fix parse -r custom_report.json  # Use custom report
-```
-
-**Common options:**
-- `-r, --report <path>` - Path to JSON report (default: `mdx_errors_report.json`)
-- `-f, --file <path>` - Fix a single MDX file directly
-- `-d, --dir <path>` - Fix MDX files in a directory
-- `--quiet` - Suppress output
-
-**What it fixes:**
-- Void tags: `<br>` → `<br />`, `<img src="x">` → `<img src="x" />`
-- Stray brackets: `x < 10` → `x &lt; 10`, `y > 5` → `y &gt; 5`
-
-Content inside code blocks and inline code is never modified.
-
-### `update`
-
-Update CLI to latest version.
-
-```bash
-writechoice update
-```
+### Other
 
-## Features
+| Command | Description |
+|---|---|
+| `writechoice metadata` | Fetch meta tags from live pages and write to frontmatter |
+| `writechoice config` | Generate a `config.json` template |
+| `writechoice update` | Update to the latest version |
 
-- **MDX Parsing Validation** - Catch syntax errors before deployment
-- **Link Validation** - Test links against live websites with Playwright
-- **Two-Step Anchor Validation** - Compare production vs development anchors
-- **Auto-Fix Links** - Automatically correct broken anchor links
-- **Auto-Fix Parsing** - Automatically fix void tags and stray angle brackets
-- **Dual Report Formats** - Generates both JSON (for automation) and Markdown (for humans)
-- **Configuration File** - Optional config.json for default settings
-- **CI/CD Ready** - Exit codes for pipeline integration
+All commands support `--file <path>`, `--dir <path>`, `--dry-run`, and `--quiet` where applicable.
 
-## How Two-Step Validation Works
+## Configuration
 
-For anchor links, the tool:
-
-1. **Finds the target** (Production): Navigates to production docs to identify which heading the anchor points to
-2. **Gets the anchor** (Validation): Navigates to your dev server (localhost:3000), clicks the heading, and extracts the generated anchor
-3. **Compares**: Checks if anchors match
-
-This ensures your local development environment matches production behavior.
-
-## Configuration File
-
-Create an optional `config.json` in your project root to set default values:
+Create a `config.json` in your project root to set defaults and avoid repeating arguments:
 
 ```json
 {
   "source": "https://docs.example.com",
-  "target": "http://localhost:3000",
-  "links": {
-    "concurrency": 25,
-    "quiet": false
-  },
-  "parse": {
-    "quiet": false
-  }
+  "target": "http://localhost:3000"
 }
 ```
 
-With config.json, you can run commands without arguments:
-
-```bash
-# Uses source and target from config.json
-writechoice check links
-
-# CLI args override config.json values
-writechoice check links https://staging.example.com
-```
-
-See [config.example.json](config.example.json) for all available options.
-
-## Examples
-
-```bash
-# Validate all MDX files for parsing errors
-writechoice check parse
-
-# Validate all links (uses localhost:3000 by default)
-writechoice check links https://docs.example.com
-
-# Validate with staging environment
-writechoice check links docs.example.com https://staging.example.com
-
-# Validate specific directory only
-writechoice check links docs.example.com -d api
-
-# Run quietly (only generate reports)
-writechoice check links docs.example.com --quiet
-
-# Fix broken anchor links
-writechoice fix links
-
-# Fix from custom report
-writechoice fix links -r custom_report.json
-
-# Fix MDX parsing errors
-writechoice fix parse
-
-# Fix a single file directly
-writechoice fix parse -f docs/getting-started.mdx
+Run `writechoice config` to generate a full template with all options.
 
-# Full workflow: validate -> fix -> re-validate
-writechoice check links docs.example.com
-writechoice fix links
-writechoice check links docs.example.com
-
-# Full parse workflow: validate -> fix -> re-validate
-writechoice check parse
-writechoice fix parse
-writechoice check parse
-```
+See [docs/config-file.md](docs/config-file.md) for the complete reference.
 
 ## Documentation
 
-Detailed documentation is available in the [docs/](docs/) folder:
-
-- **Commands**
-  - [config](docs/commands/config.md) - Generate config.json template
-  - [check links](docs/commands/check-links.md) - Link validation
-  - [check parse](docs/commands/check-parse.md) - MDX parsing validation
-  - [fix links](docs/commands/fix-links.md) - Auto-fix broken links
-  - [fix parse](docs/commands/fix-parse.md) - Auto-fix MDX parsing errors
-  - [update](docs/commands/update.md) - Update command
-- **Guides**
-  - [Configuration File](docs/config-file.md) - Using config.json
-  - [Configuration](docs/configuration.md) - Advanced configuration
-  - [Publishing](docs/publishing.md) - How to publish new versions
-
-## Development
-
-### Local Setup
-
-```bash
-git clone <repository-url>
-cd writechoice-mint-cli
-npm install
-npx playwright install chromium
-chmod +x bin/cli.js
-npm link
-```
-
-### Project Structure
+Full command documentation is in [docs/commands/](docs/commands/):
 
-```
-writechoice-mint-cli/
-├── bin/
-│   └── cli.js                 # CLI entry point
-├── src/
-│   ├── commands/
-│   │   ├── validate/
-│   │   │   ├── links.js       # Link validation
-│   │   │   └── mdx.js         # MDX parsing validation
-│   │   └── fix/
-│   │       ├── links.js       # Link fixing
-│   │       └── parse.js       # Parse error fixing
-│   └── utils/
-│       ├── helpers.js         # Utility functions
-│       └── reports.js         # Report generation
-├── docs/                      # Detailed documentation
-├── package.json
-└── README.md
-```
+- [check-links](docs/commands/check-links.md)
+- [check-parse](docs/commands/check-parse.md)
+- [fix-links](docs/commands/fix-links.md)
+- [fix-parse](docs/commands/fix-parse.md)
+- [fix-codeblocks](docs/commands/fix-codeblocks.md)
+- [fix-images](docs/commands/fix-images.md)
+- [fix-inlineimages](docs/commands/fix-inlineimages.md)
+- [fix-h1](docs/commands/fix-h1.md)
+- [metadata](docs/commands/metadata.md)
 
 ## Troubleshooting
 
-### Playwright Not Installed
-
+**Playwright not installed:**
 ```bash
 npx playwright install chromium
 ```
 
-### Memory Issues
-
+**Too many concurrent requests:**
 ```bash
-writechoice check links docs.example.com -c 10
+writechoice check links -c 10
 ```
 
-### Permission Errors
-
+**Permission error on install:**
 ```bash
 sudo npm install -g @writechoice/mint-cli
+# or use nvm: https://github.com/nvm-sh/nvm
 ```
 
-Or use a node version manager like [nvm](https://github.com/nvm-sh/nvm).
-
 ## License
 
-MIT
-
-## Contributing
-
-Contributions are welcome! Please open an issue or submit a pull request.
-
-## Links
-
-- [npm package](https://www.npmjs.com/package/@writechoice/mint-cli)
-- [GitHub repository](https://github.com/writechoice/mint-cli)
-- [Issue tracker](https://github.com/writechoice/mint-cli/issues)
+MIT — [GitHub](https://github.com/writechoice/mint-cli) · [npm](https://www.npmjs.com/package/@writechoice/mint-cli) · [Issues](https://github.com/writechoice/mint-cli/issues)

package/bin/cli.js

@@ -177,6 +177,7 @@ fix
   .description("Wrap standalone images in <Frame> components in MDX files")
   .option("-f, --file <path>", "Fix a single MDX file directly")
   .option("-d, --dir <path>", "Fix MDX files in a specific directory")
+  .option("--download [url]", "Download missing local images; uses source from config or provide a URL")
   .option("--dry-run", "Preview changes without writing files")
   .option("--quiet", "Suppress terminal output")
   .action(async (options) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@writechoice/mint-cli",
-  "version": "0.0.18",
+  "version": "0.0.20",
   "description": "CLI tool for Mintlify documentation validation and utilities",
   "main": "src/index.js",
   "type": "module",
@@ -9,7 +9,7 @@
     "wc": "bin/cli.js"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "node --test 'test/**/*.test.js'",
     "dev": "node bin/cli.js",
     "release": "bash publish.sh",
     "postinstall": "echo \"\\n⚠️  Don't forget to install Playwright browsers:\\n   npx playwright install chromium\\n\""

package/src/commands/fix/codeblocks.js

@@ -75,7 +75,7 @@ function splitLines(content) {
  * Processes the token list for a single code block's info string.
  * Returns { newTokens, changes }.
  */
-function processInfoTokens(tokens, lineCount, lineNum, options) {
+export function processInfoTokens(tokens, lineCount, lineNum, options) {
   const changes = [];
   let newTokens = [...tokens];
 
@@ -120,7 +120,7 @@ function processInfoTokens(tokens, lineCount, lineNum, options) {
  * Scans MDX content for fenced code blocks and applies flag fixes.
  * Returns { newContent, changes }.
  */
-function processContent(content, options) {
+export function processContent(content, options) {
   const lines = splitLines(content);
   const result = [];
   const changes = [];

package/src/commands/fix/h1.js

@@ -27,7 +27,7 @@ const H1_RE = /^\s*#\s+(.*?)\s*$/;
 /**
  * Returns the frontmatter title value, or null if not found.
  */
-function extractFrontmatterTitle(content) {
+export function extractFrontmatterTitle(content) {
   const fmMatch = FRONTMATTER_RE.exec(content);
   if (!fmMatch) return null;
   const fmText = fmMatch[0];
@@ -39,7 +39,7 @@ function extractFrontmatterTitle(content) {
  * Removes the duplicate H1 from `content` if present.
  * Returns { newContent, changed }.
  */
-function removeDuplicateH1(content, fmTitle) {
+export function removeDuplicateH1(content, fmTitle) {
   const fmMatch = FRONTMATTER_RE.exec(content);
   if (!fmMatch) return { newContent: content, changed: false };
 

package/src/commands/fix/images.js

@@ -11,8 +11,8 @@
  * - HTML tables
  */
 
-import { existsSync, readdirSync, statSync, readFileSync, writeFileSync } from "fs";
-import { join, relative, resolve } from "path";
+import { existsSync, mkdirSync, readdirSync, statSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join, relative, resolve } from "path";
 import chalk from "chalk";
 
 const EXCLUDED_DIRS = ["node_modules", ".git"];
@@ -72,7 +72,7 @@ function detokenize(text, tag, stash) {
  * Processes MDX content and wraps standalone images in <Frame> components.
  * Returns { newContent, count }.
  */
-function processContent(content) {
+export function processContent(content) {
   let text = content;
 
   // 1. Protect existing <Frame> blocks
@@ -113,6 +113,90 @@ function processContent(content) {
   return { newContent: text, count };
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Image src extraction (for --download)
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Extract all image src values from MDX content (markdown + HTML img)
+export function extractImageSrcs(content) {
+  const srcs = [];
+
+  // Markdown images: ![alt](src) — capture the URL part
+  const mdRe = /!\[[^\]]*\]\(([^)\s"']+)/g;
+  let m;
+  while ((m = mdRe.exec(content)) !== null) {
+    srcs.push(m[1]);
+  }
+
+  // HTML img tags: <img src="..." /> or <img src='...' />
+  const htmlRe = /<img\b[^>]*\bsrc=["']([^"']+)["']/gi;
+  while ((m = htmlRe.exec(content)) !== null) {
+    srcs.push(m[1]);
+  }
+
+  return srcs;
+}
+
+/**
+ * Downloads missing local images from the source URL.
+ * Only attempts images with local absolute paths (starting with /).
+ * Returns { downloaded, failed } arrays and optionally writes image_download.json.
+ */
+async function downloadMissingImages(files, repoRoot, downloadUrl, options) {
+  const base = downloadUrl.replace(/\/$/, "");
+
+  // Collect unique local srcs across all files
+  const srcSet = new Set();
+  for (const filePath of files) {
+    const content = readFileSync(filePath, "utf-8");
+    for (const src of extractImageSrcs(content)) {
+      // Only handle root-relative paths like /images/foo.png
+      if (src.startsWith("/") && !src.startsWith("//")) {
+        srcSet.add(src);
+      }
+    }
+  }
+
+  if (srcSet.size === 0) {
+    return { downloaded: [], failed: [] };
+  }
+
+  const downloaded = [];
+  const failed = [];
+
+  for (const src of srcSet) {
+    const localPath = join(repoRoot, src);
+
+    if (existsSync(localPath)) continue; // already present
+
+    const url = base + src;
+
+    try {
+      const response = await fetch(url);
+      if (!response.ok) {
+        failed.push({ src, url, reason: `HTTP ${response.status}` });
+        continue;
+      }
+
+      if (!options.dryRun) {
+        mkdirSync(dirname(localPath), { recursive: true });
+        const buffer = await response.arrayBuffer();
+        writeFileSync(localPath, Buffer.from(buffer));
+      }
+
+      downloaded.push({ src, url });
+
+      if (options.verbose) {
+        console.log(`  ${chalk.green("↓")} ${src}`);
+      }
+    } catch (err) {
+      failed.push({ src, url, reason: err.message });
+    }
+  }
+
+  return { downloaded, failed };
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // File discovery
 // ─────────────────────────────────────────────────────────────────────────────
@@ -200,7 +284,7 @@ export async function fixImages(options) {
     }
   }
 
-  // Summary
+  // Summary — wrapping
   if (!options.quiet) {
     const fileCount = Object.keys(results).length;
 
@@ -217,4 +301,57 @@ export async function fixImages(options) {
       console.log(chalk.yellow("⚠️  No unwrapped images found."));
     }
   }
+
+  // ── Download pass ──────────────────────────────────────────────────────────
+  if (!options.download) return;
+
+  if (!options.downloadUrl) {
+    console.error(chalk.red(
+      '\n✗ --download requires a source URL.\n' +
+      '  Pass it after the flag: wc fix images --download https://docs.example.com\n' +
+      '  Or set "source" in config.json'
+    ));
+    process.exit(1);
+  }
+
+  if (!options.quiet) {
+    console.log(chalk.bold("\n⬇️  Downloading missing images\n"));
+    if (options.dryRun) {
+      console.log(chalk.yellow("Dry run — images will not be saved\n"));
+    }
+  }
+
+  const { downloaded, failed } = await downloadMissingImages(files, repoRoot, options.downloadUrl, options);
+
+  if (!options.quiet) {
+    if (downloaded.length > 0) {
+      const verb = options.dryRun ? "Would download" : "Downloaded";
+      console.log(chalk.green(`\n✓ ${verb} ${downloaded.length} image(s)`));
+      if (!options.verbose) {
+        for (const { src } of downloaded) {
+          console.log(`  ${src}`);
+        }
+      }
+    }
+
+    if (failed.length > 0) {
+      console.log(chalk.red(`\n✗ Failed to download ${failed.length} image(s)`));
+      for (const { src, reason } of failed) {
+        console.log(`  ${chalk.cyan(src)}: ${reason}`);
+      }
+    }
+
+    if (downloaded.length === 0 && failed.length === 0) {
+      console.log(chalk.yellow("⚠️  No missing local images found."));
+    }
+  }
+
+  // Write report when there are failures
+  if (failed.length > 0 && !options.dryRun) {
+    const reportPath = join(repoRoot, "image_download.json");
+    writeFileSync(reportPath, JSON.stringify({ downloaded, failed }, null, 2), "utf-8");
+    if (!options.quiet) {
+      console.log(`\nReport written to ${chalk.cyan("image_download.json")}`);
+    }
+  }
 }

package/src/commands/fix/inlineimages.js

@@ -74,7 +74,7 @@ function findFrontmatterEnd(content) {
  * Ensures the InlineImage import is present in the file.
  * Inserts after frontmatter (if any) with an empty line below.
  */
-function ensureImport(content) {
+export function ensureImport(content) {
   if (content.includes(IMPORT_LINE)) return content;
 
   const fmEnd = findFrontmatterEnd(content);
@@ -158,7 +158,7 @@ function processLine(line) {
  * Processes MDX content: replaces inline images and injects the import.
  * Returns { newContent, count }.
  */
-function processContent(content) {
+export function processContent(content) {
   let text = content;
 
   // 1. Protect multi-line regions

package/src/commands/fix/parse.js

@@ -89,7 +89,7 @@ function getFilesFromReport(reportPath, repoRoot) {
  * Splits file content into protected (code) and unprotected (text) segments.
  * Returns an array of { text, protected } objects.
  */
-function segmentContent(content) {
+export function segmentContent(content) {
   const segments = [];
   let pos = 0;
   const len = content.length;
@@ -154,7 +154,7 @@ function segmentContent(content) {
  * Fixes void HTML tags in a text segment (not inside inline code).
  * Returns { text, count }.
  */
-function fixVoidTags(text) {
+export function fixVoidTags(text) {
   let count = 0;
 
   // Process the text but protect inline code spans
@@ -205,7 +205,7 @@ function replaceVoidTags(text) {
  * Fixes stray < and > in a text segment (not inside inline code or tags).
  * Returns { text, count }.
  */
-function fixStrayAngleBrackets(text) {
+export function fixStrayAngleBrackets(text) {
   let count = 0;
 
   // Process the text but protect inline code spans and valid tags

package/src/commands/metadata.js

@@ -56,7 +56,7 @@ function parseHtmlAttributes(attrStr) {
  * Looks at property, name, and itemprop attributes.
  * Returns { "og:title": "...", ... }
  */
-function extractMetaTags(html, tags) {
+export function extractMetaTags(html, tags) {
   const results = {};
   const metaRe = /<meta\s+([^>]+?)(?:\s*\/?>)/gi;
   let m;
@@ -120,7 +120,7 @@ async function runConcurrent(tasks, concurrency) {
 // URL construction
 // ─────────────────────────────────────────────────────────────────────────────
 
-function fileToUrl(filePath, scanDir, baseUrl) {
+export function fileToUrl(filePath, scanDir, baseUrl) {
   const rel = relative(scanDir, filePath)
     .replace(/\.mdx$/, "")
     .replace(/\\/g, "/");
@@ -141,7 +141,7 @@ function escapeRe(str) {
  * Formats a string value for YAML output.
  * Always produces a quoted scalar to avoid YAML interpretation issues.
  */
-function yamlValue(str) {
+export function yamlValue(str) {
   if (!str.includes('"')) return `"${str}"`;
   if (!str.includes("'")) return `'${str}'`;
   // Both quotes present — escape double quotes
@@ -153,7 +153,7 @@ function yamlValue(str) {
  * Updates existing frontmatter keys, appends missing ones.
  * Returns { newContent, updated: string[], added: string[], skipped: boolean }
  */
-function applyMetaToContent(content, metaData) {
+export function applyMetaToContent(content, metaData) {
   const fmMatch = FRONTMATTER_RE.exec(content);
   if (!fmMatch) {
     return { newContent: content, updated: [], added: [], skipped: true };

package/src/utils/config.js

@@ -171,11 +171,20 @@ export function mergeInlineImagesConfig(options, config) {
 export function mergeImagesConfig(options, config) {
   const imgConfig = config?.images || {};
 
+  // download: true if --download was passed without a URL, string if URL provided
+  const downloadFlag = options.download !== undefined ? options.download : (imgConfig.download ?? false);
+  let downloadUrl = null;
+  if (downloadFlag) {
+    downloadUrl = typeof downloadFlag === "string" ? downloadFlag : (config?.source || null);
+  }
+
   return {
     file: options.file || imgConfig.file || null,
     dir: options.dir || imgConfig.dir || null,
     dryRun: options.dryRun !== undefined ? options.dryRun : (imgConfig["dry-run"] ?? false),
     quiet: options.quiet !== undefined ? options.quiet : (imgConfig.quiet ?? false),
+    download: !!downloadFlag,
+    downloadUrl,
   };
 }