@writechoice/mint-cli 0.0.19 → 0.0.20

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.19",
+  "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,
   };
 }