@writechoice/mint-cli 0.0.17 → 0.0.19

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

@@ -189,6 +189,25 @@ fix
     await fixImages(mergedOptions);
   });
 
+// Metadata command
+program
+  .command("metadata [baseUrl]")
+  .description("Fetch meta tags from live pages and write them into MDX frontmatter")
+  .option("-f, --file <path>", "Process a single MDX file")
+  .option("-d, --dir <path>", "Process MDX files in a specific directory")
+  .option("-c, --concurrency <number>", "Number of parallel HTTP requests", "15")
+  .option("--dry-run", "Preview changes without writing files")
+  .option("--quiet", "Suppress terminal output")
+  .action(async (baseUrl, options) => {
+    const { loadConfig, mergeMetadataConfig } = await import("../src/utils/config.js");
+    const { runMetadata } = await import("../src/commands/metadata.js");
+
+    const config = loadConfig();
+    const mergedOptions = mergeMetadataConfig({ ...options, baseUrl }, config);
+    mergedOptions.verbose = !mergedOptions.quiet;
+    await runMetadata(mergedOptions);
+  });
+
 // Config command
 program
   .command("config")

package/package.json

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

package/src/commands/metadata.js

@@ -0,0 +1,357 @@
+/**
+ * Metadata Command
+ *
+ * Fetches meta tags from live documentation pages and writes them into
+ * the frontmatter of the corresponding MDX source files.
+ *
+ * URL mapping:
+ *   baseUrl + "/" + relative-path-from-scan-dir (without .mdx)
+ *
+ * Example:
+ *   baseUrl   = https://docs.example.com
+ *   file      = docs/api/reference.mdx
+ *   scan dir  = docs/
+ *   → URL     = https://docs.example.com/api/reference
+ *
+ * Existing frontmatter keys are updated (overwritten).
+ * Missing keys are appended at the end of the frontmatter block.
+ */
+
+import { existsSync, readdirSync, statSync, readFileSync, writeFileSync } from "fs";
+import { join, relative, resolve } from "path";
+import chalk from "chalk";
+
+const EXCLUDED_DIRS = ["node_modules", ".git"];
+
+export const DEFAULT_META_TAGS = [
+  "og:title",
+  "og:description",
+  "og:image",
+  "og:url",
+  "twitter:title",
+  "twitter:description",
+  "twitter:image",
+];
+
+// ─────────────────────────────────────────────────────────────────────────────
+// HTML helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Parses an HTML attribute string into a key→value object.
+ * Handles both double and single-quoted values.
+ */
+function parseHtmlAttributes(attrStr) {
+  const attrs = {};
+  const re = /(\w[\w-]*)=(?:"([^"]*)"|'([^']*)')/g;
+  let m;
+  while ((m = re.exec(attrStr)) !== null) {
+    attrs[m[1]] = m[2] !== undefined ? m[2] : m[3];
+  }
+  return attrs;
+}
+
+/**
+ * Extracts the requested meta tag values from an HTML string.
+ * Looks at property, name, and itemprop attributes.
+ * Returns { "og:title": "...", ... }
+ */
+function extractMetaTags(html, tags) {
+  const results = {};
+  const metaRe = /<meta\s+([^>]+?)(?:\s*\/?>)/gi;
+  let m;
+  while ((m = metaRe.exec(html)) !== null) {
+    const attrs = parseHtmlAttributes(m[1]);
+    const tagName = attrs.property || attrs.name || attrs.itemprop;
+    if (tagName && tags.includes(tagName) && attrs.content && attrs.content.trim()) {
+      results[tagName] = attrs.content.trim();
+    }
+  }
+  return results;
+}
+
+/**
+ * Fetches a URL and returns the extracted meta tags.
+ */
+async function fetchMetaTags(url, tags) {
+  try {
+    const res = await fetch(url, {
+      headers: {
+        "User-Agent":
+          "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+      },
+      signal: AbortSignal.timeout(30_000),
+    });
+
+    if (!res.ok) {
+      return { error: `HTTP ${res.status}`, tags: {} };
+    }
+
+    const html = await res.text();
+    return { error: null, tags: extractMetaTags(html, tags) };
+  } catch (err) {
+    return { error: err.message, tags: {} };
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Concurrency
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Runs an array of async task factories with a maximum concurrency.
+ */
+async function runConcurrent(tasks, concurrency) {
+  const results = new Array(tasks.length);
+  const queue = tasks.map((task, idx) => ({ task, idx }));
+
+  async function worker() {
+    while (queue.length > 0) {
+      const { task, idx } = queue.shift();
+      results[idx] = await task();
+    }
+  }
+
+  await Promise.all(Array.from({ length: Math.min(concurrency, tasks.length) }, worker));
+  return results;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// URL construction
+// ─────────────────────────────────────────────────────────────────────────────
+
+function fileToUrl(filePath, scanDir, baseUrl) {
+  const rel = relative(scanDir, filePath)
+    .replace(/\.mdx$/, "")
+    .replace(/\\/g, "/");
+  return baseUrl.replace(/\/$/, "") + "/" + rel;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Frontmatter helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+
+function escapeRe(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Formats a string value for YAML output.
+ * Always produces a quoted scalar to avoid YAML interpretation issues.
+ */
+function yamlValue(str) {
+  if (!str.includes('"')) return `"${str}"`;
+  if (!str.includes("'")) return `'${str}'`;
+  // Both quotes present — escape double quotes
+  return `"${str.replace(/"/g, '\\"')}"`;
+}
+
+/**
+ * Applies meta data to the MDX file content.
+ * Updates existing frontmatter keys, appends missing ones.
+ * Returns { newContent, updated: string[], added: string[], skipped: boolean }
+ */
+function applyMetaToContent(content, metaData) {
+  const fmMatch = FRONTMATTER_RE.exec(content);
+  if (!fmMatch) {
+    return { newContent: content, updated: [], added: [], skipped: true };
+  }
+
+  let fmText = fmMatch[1];
+  const fmEnd = fmMatch[0].length;
+  const body = content.slice(fmEnd);
+
+  const updated = [];
+  const added = [];
+
+  for (const [key, value] of Object.entries(metaData)) {
+    // Keys containing colons must be quoted in YAML
+    const yamlKey = key.includes(":") ? `"${key}"` : key;
+    const newLine = `${yamlKey}: ${yamlValue(value)}`;
+
+    // Match existing key in any of its quoting variants
+    const keyEsc = escapeRe(key);
+    const existingRe = new RegExp(
+      `^(?:${keyEsc}|"${keyEsc}"|'${keyEsc}')\\s*:.*$`,
+      "m"
+    );
+
+    if (existingRe.test(fmText)) {
+      fmText = fmText.replace(existingRe, newLine);
+      updated.push(key);
+    } else {
+      fmText += `\n${newLine}`;
+      added.push(key);
+    }
+  }
+
+  const newContent = `---\n${fmText}\n---\n${body}`;
+  return { newContent, updated, added, skipped: false };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// File discovery
+// ─────────────────────────────────────────────────────────────────────────────
+
+function findMdxFiles(repoRoot, directory = null, file = null) {
+  if (file) {
+    const fullPath = resolve(repoRoot, file);
+    return existsSync(fullPath) ? [fullPath] : [];
+  }
+
+  const searchDirs = directory ? [resolve(repoRoot, directory)] : [repoRoot];
+  const mdxFiles = [];
+
+  function walkDirectory(dir) {
+    const dirName = dir.split("/").pop();
+    if (EXCLUDED_DIRS.includes(dirName)) return;
+
+    try {
+      const entries = readdirSync(dir);
+      for (const entry of entries) {
+        const fullPath = join(dir, entry);
+        const stat = statSync(fullPath);
+        if (stat.isDirectory()) {
+          walkDirectory(fullPath);
+        } else if (stat.isFile() && entry.endsWith(".mdx")) {
+          mdxFiles.push(fullPath);
+        }
+      }
+    } catch (error) {
+      console.error(`Error reading directory ${dir}: ${error.message}`);
+    }
+  }
+
+  for (const dir of searchDirs) {
+    if (existsSync(dir)) walkDirectory(dir);
+  }
+
+  return mdxFiles.sort();
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Main export
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function runMetadata(options) {
+  const repoRoot = process.cwd();
+
+  if (!options.quiet) {
+    console.log(chalk.bold("\n🏷️  Metadata Fetcher\n"));
+  }
+
+  if (!options.baseUrl) {
+    console.error(
+      chalk.red("✗ No base URL provided. Pass --base-url or set 'source' in config.json.")
+    );
+    process.exit(1);
+  }
+
+  const tags = options.tags || DEFAULT_META_TAGS;
+  const concurrency = options.concurrency || 15;
+  const scanDir = options.dir ? resolve(repoRoot, options.dir) : repoRoot;
+
+  const files = findMdxFiles(repoRoot, options.dir, options.file);
+
+  if (files.length === 0) {
+    console.error(chalk.red("✗ No MDX files found."));
+    process.exit(1);
+  }
+
+  if (!options.quiet) {
+    console.log(`Base URL  : ${options.baseUrl}`);
+    console.log(`Tags      : ${tags.join(", ")}`);
+    console.log(`Files     : ${files.length} MDX file(s)`);
+    console.log(`Concurrency: ${concurrency}\n`);
+    if (options.dryRun) {
+      console.log(chalk.yellow("Dry run — no files will be written\n"));
+    }
+  }
+
+  let processed = 0;
+  let skipped = 0;
+  let errors = 0;
+  const changed = [];
+
+  const tasks = files.map((filePath) => async () => {
+    const url = fileToUrl(filePath, scanDir, options.baseUrl);
+    const relPath = relative(repoRoot, filePath);
+
+    const { error, tags: metaData } = await fetchMetaTags(url, tags);
+
+    processed++;
+
+    if (error) {
+      if (!options.quiet) {
+        console.log(`${chalk.red("✗")} ${chalk.cyan(relPath)} — ${error}`);
+      }
+      errors++;
+      return;
+    }
+
+    if (Object.keys(metaData).length === 0) {
+      if (options.verbose) {
+        console.log(`${chalk.gray("–")} ${chalk.cyan(relPath)} — no meta tags found`);
+      }
+      skipped++;
+      return;
+    }
+
+    const content = readFileSync(filePath, "utf-8");
+    const { newContent, updated, added, skipped: noFm } = applyMetaToContent(content, metaData);
+
+    if (noFm) {
+      if (options.verbose) {
+        console.log(`${chalk.gray("–")} ${chalk.cyan(relPath)} — no frontmatter, skipped`);
+      }
+      skipped++;
+      return;
+    }
+
+    const totalChanges = updated.length + added.length;
+    if (totalChanges > 0) {
+      changed.push({ relPath, updated, added });
+      if (options.verbose) {
+        const parts = [];
+        if (updated.length) parts.push(`updated: ${updated.join(", ")}`);
+        if (added.length) parts.push(`added: ${added.join(", ")}`);
+        console.log(`${chalk.green("✓")} ${chalk.cyan(relPath)} — ${parts.join(" | ")}`);
+      }
+      if (!options.dryRun) {
+        writeFileSync(filePath, newContent, "utf-8");
+      }
+    } else {
+      if (options.verbose) {
+        console.log(`${chalk.gray("–")} ${chalk.cyan(relPath)} — already up to date`);
+      }
+      skipped++;
+    }
+  });
+
+  await runConcurrent(tasks, concurrency);
+
+  // Summary
+  if (!options.quiet) {
+    if (changed.length > 0) {
+      const verb = options.dryRun ? "Would update" : "Updated";
+      console.log(chalk.green(`\n✓ ${verb} ${changed.length} file(s)`));
+
+      if (!options.verbose) {
+        for (const { relPath, updated, added } of changed) {
+          const parts = [];
+          if (updated.length) parts.push(`updated: ${updated.length}`);
+          if (added.length) parts.push(`added: ${added.length}`);
+          console.log(`  ${chalk.cyan(relPath)} — ${parts.join(" | ")} tag(s)`);
+        }
+      }
+    } else {
+      console.log(chalk.yellow("⚠️  No files needed updating."));
+    }
+
+    if (errors > 0) {
+      console.log(chalk.yellow(`\n⚠️  ${errors} file(s) had fetch errors.`));
+    }
+  }
+}

package/src/utils/config.js

@@ -198,6 +198,30 @@ export function mergeH1Config(options, config) {
   };
 }
 
+/**
+ * Merges config file with CLI options for the metadata command
+ * CLI options take precedence over config file
+ *
+ * @param {Object} options - CLI options
+ * @param {Object|null} config - Loaded config object
+ * @returns {Object} Merged options
+ */
+export function mergeMetadataConfig(options, config) {
+  const metaConfig = config?.metadata || {};
+
+  return {
+    baseUrl: options.baseUrl || config?.source || null,
+    file: options.file || metaConfig.file || null,
+    dir: options.dir || metaConfig.dir || null,
+    concurrency: options.concurrency != null
+      ? parseInt(options.concurrency, 10)
+      : (metaConfig.concurrency ?? 15),
+    tags: metaConfig.tags || null, // null means use defaults
+    dryRun: options.dryRun !== undefined ? options.dryRun : (metaConfig["dry-run"] ?? false),
+    quiet: options.quiet !== undefined ? options.quiet : (metaConfig.quiet ?? false),
+  };
+}
+
 /**
  * Validates that required fields are present
  * @param {string|undefined} baseUrl - Base URL