@readme/cli 0.0.26 → 0.0.27

package/src/utils/lint.js

@@ -1,6 +1,6 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import fs from 'node:fs'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
 
 const TARGET_PATTERNS = [
   { dir: 'custom_blocks', ext: ['.mdx', '.md'] },
@@ -8,28 +8,28 @@ const TARGET_PATTERNS = [
   { dir: 'reference', ext: '.md' },
   { dir: 'custom_pages', ext: '.md' },
   { dir: 'recipes', ext: '.md' },
-];
+]
 
 /**
  * Collect all target files from the repo root.
  */
 export function collectFiles(gitRoot) {
-  const files = [];
+  const files = []
 
   for (const { dir, ext } of TARGET_PATTERNS) {
-    const dirPath = path.join(gitRoot, dir);
-    if (!fs.existsSync(dirPath)) continue;
+    const dirPath = path.join(gitRoot, dir)
+    if (!fs.existsSync(dirPath)) continue
 
-    const exts = Array.isArray(ext) ? ext : [ext];
-    const entries = fs.readdirSync(dirPath, { recursive: true });
+    const exts = Array.isArray(ext) ? ext : [ext]
+    const entries = fs.readdirSync(dirPath, { recursive: true })
     for (const entry of entries) {
       if (exts.some((e) => entry.endsWith(e))) {
-        files.push(path.join(dir, entry));
+        files.push(path.join(dir, entry))
       }
     }
   }
 
-  return files.sort();
+  return files.sort()
 }
 
 /**
@@ -38,18 +38,18 @@ export function collectFiles(gitRoot) {
  * `validateAll()` for cross-file checks (like ordering).
  */
 async function loadValidators() {
-  const validatorsDir = path.join(path.dirname(new URL(import.meta.url).pathname), '..', 'validators');
-  const files = fs.readdirSync(validatorsDir).filter((f) => f.endsWith('.js'));
-  const validators = [];
+  const validatorsDir = path.join(path.dirname(new URL(import.meta.url).pathname), '..', 'validators')
+  const files = fs.readdirSync(validatorsDir).filter((f) => f.endsWith('.js'))
+  const validators = []
 
   for (const file of files) {
-    const mod = await import(pathToFileURL(path.join(validatorsDir, file)).href);
+    const mod = await import(pathToFileURL(path.join(validatorsDir, file)).href)
     if (mod.name && (mod.validate || mod.validateAll)) {
-      validators.push(mod);
+      validators.push(mod)
     }
   }
 
-  return validators;
+  return validators
 }
 
 /**
@@ -57,43 +57,43 @@ async function loadValidators() {
  * Each result has { file, rule, message, severity? } where severity defaults to 'error'.
  * Calls `onFile(relativePath)` before processing each file (for progress reporting).
  */
-export async function runValidators(files, gitRoot, { onFile, onBeforeCrossFile, fix } = {}) {
-  const validators = await loadValidators();
-  const results = [];
+export async function runValidators(files, gitRoot, { onFile, onBeforeCrossFile, fix, nonInteractive } = {}) {
+  const validators = await loadValidators()
+  const results = []
 
   // Per-file validators.
   for (const relativePath of files) {
-    if (onFile) onFile(relativePath);
+    if (onFile) onFile(relativePath)
 
-    const filePath = path.join(gitRoot, relativePath);
-    const content = fs.readFileSync(filePath, 'utf-8');
+    const filePath = path.join(gitRoot, relativePath)
+    const content = fs.readFileSync(filePath, 'utf-8')
 
     for (const validator of validators) {
-      if (!validator.validate) continue;
-      const result = validator.validate({ filePath, content, relativePath, fix });
+      if (!validator.validate) continue
+      const result = validator.validate({ filePath, content, relativePath, fix })
       if (result) {
         if (Array.isArray(result)) {
-          results.push(...result);
+          results.push(...result)
         } else {
-          results.push(result);
+          results.push(result)
         }
       }
     }
   }
 
   // Cross-file validators — stop the spinner first so interactive prompts work.
-  if (onBeforeCrossFile) onBeforeCrossFile();
+  if (onBeforeCrossFile) onBeforeCrossFile()
   for (const validator of validators) {
-    if (!validator.validateAll) continue;
-    const result = await validator.validateAll(files, gitRoot, { fix });
+    if (!validator.validateAll) continue
+    const result = await validator.validateAll(files, gitRoot, { fix, nonInteractive })
     if (result) {
       if (Array.isArray(result)) {
-        results.push(...result);
+        results.push(...result)
       } else {
-        results.push(result);
+        results.push(result)
       }
     }
   }
 
-  return results;
+  return results
 }

package/src/utils/marketplace.js

@@ -0,0 +1,208 @@
+/**
+ * Talks to the readmeio/marketplace repo: lists the available MDX components,
+ * fetches a single component's files (the .mdx source + its readme.md), and
+ * caches everything on disk so we're not hitting GitHub on every command.
+ *
+ * Components are read at https://github.com/readmeio/marketplace/tree/main/components
+ * and copied into the user's local `components/` folder. The marketplace
+ * `.mdx` files are the canonical source — they hold the JSX export plus an
+ * example invocation at the bottom.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const REPO = 'readmeio/marketplace';
+const BRANCH = 'main';
+const COMPONENTS_PATH = 'components';
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+
+const CACHE_DIR = path.join(os.homedir(), '.cache', 'readme-cli', 'marketplace');
+
+function ensureCacheDir() {
+  fs.mkdirSync(CACHE_DIR, { recursive: true });
+}
+
+function cachePath(name) {
+  return path.join(CACHE_DIR, name);
+}
+
+function readCache(name, maxAgeMs = CACHE_TTL_MS) {
+  const file = cachePath(name);
+  try {
+    const stat = fs.statSync(file);
+    if (Date.now() - stat.mtimeMs > maxAgeMs) return null;
+    return fs.readFileSync(file, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(name, contents) {
+  ensureCacheDir();
+  fs.writeFileSync(cachePath(name), contents, 'utf-8');
+}
+
+async function fetchText(url) {
+  const res = await fetch(url, {
+    headers: { 'User-Agent': '@readme/cli', Accept: 'application/vnd.github.v3+json' },
+  });
+  if (!res.ok) {
+    throw new Error(`GET ${url} → ${res.status} ${res.statusText}`);
+  }
+  return res.text();
+}
+
+/**
+ * Returns the list of marketplace components as an array of:
+ *   { name, mdxUrl, readmeUrl, htmlUrl }
+ * Hidden entries (e.g. `.ExampleComponent`) are filtered out.
+ */
+export async function listMarketplaceComponents({ force = false } = {}) {
+  const cacheKey = 'index.json';
+  if (!force) {
+    const cached = readCache(cacheKey);
+    if (cached) {
+      try { return JSON.parse(cached); } catch { /* fall through */ }
+    }
+  }
+
+  const url = `https://api.github.com/repos/${REPO}/contents/${COMPONENTS_PATH}?ref=${BRANCH}`;
+  const body = await fetchText(url);
+  const entries = JSON.parse(body);
+
+  const components = entries
+    .filter((e) => e.type === 'dir' && !e.name.startsWith('.'))
+    .map((e) => ({
+      name: e.name,
+      htmlUrl: `https://github.com/${REPO}/tree/${BRANCH}/${COMPONENTS_PATH}/${e.name}`,
+      mdxUrl: `https://raw.githubusercontent.com/${REPO}/${BRANCH}/${COMPONENTS_PATH}/${e.name}/${e.name}.mdx`,
+      readmeUrl: `https://raw.githubusercontent.com/${REPO}/${BRANCH}/${COMPONENTS_PATH}/${e.name}/readme.md`,
+    }));
+
+  writeCache(cacheKey, JSON.stringify(components, null, 2));
+  return components;
+}
+
+/**
+ * Fetch the .mdx + readme.md for a single component. Returns:
+ *   { name, mdx, readme, htmlUrl }
+ * `readme` may be null if the component has no readme.md.
+ */
+export async function fetchMarketplaceComponent(name, { force = false } = {}) {
+  const components = await listMarketplaceComponents({ force });
+  const match = components.find((c) => c.name.toLowerCase() === name.toLowerCase());
+  if (!match) {
+    throw new Error(`Component "${name}" not found in marketplace.`);
+  }
+
+  const mdxCacheKey = `${match.name}.mdx`;
+  const readmeCacheKey = `${match.name}.readme.md`;
+
+  let mdx = !force && readCache(mdxCacheKey);
+  if (!mdx) {
+    mdx = await fetchText(match.mdxUrl);
+    writeCache(mdxCacheKey, mdx);
+  }
+
+  let readme = !force && readCache(readmeCacheKey);
+  if (!readme) {
+    try {
+      readme = await fetchText(match.readmeUrl);
+      writeCache(readmeCacheKey, readme);
+    } catch {
+      readme = null;
+    }
+  }
+
+  return { name: match.name, mdx, readme, htmlUrl: match.htmlUrl };
+}
+
+/**
+ * Pull the one-line summary out of a component's readme.md. We look for the
+ * first non-empty paragraph after the `## Overview` heading, falling back to
+ * the first non-heading line. Returns "" if nothing usable is found.
+ */
+export function summarizeReadme(readme) {
+  if (!readme) return '';
+  const lines = readme.split('\n');
+  let inOverview = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (/^##\s+overview/i.test(line)) { inOverview = true; continue; }
+    if (inOverview && line && !line.startsWith('#') && !line.startsWith('![')) {
+      return line.replace(/[*_`]/g, '').slice(0, 140);
+    }
+  }
+  // Fallback: first non-heading, non-image line.
+  for (const line of lines) {
+    const t = line.trim();
+    if (t && !t.startsWith('#') && !t.startsWith('![') && !t.startsWith('<')) {
+      return t.replace(/[*_`]/g, '').slice(0, 140);
+    }
+  }
+  return '';
+}
+
+/**
+ * Pull the first example invocation block out of a component's mdx. Components
+ * conventionally end with a bare `<ComponentName ... />` line below the React
+ * export — return that. Returns the full mdx as a fallback.
+ */
+export function extractExample(mdx, name) {
+  const re = new RegExp(`^<${name}[\\s\\S]*?(?:/>|</${name}>)\\s*$`, 'm');
+  const match = mdx.match(re);
+  return match ? match[0] : '';
+}
+
+/**
+ * Returns the absolute path to the local `components/` folder for a repo
+ * (relative to gitRoot). Does not create it.
+ */
+export function localComponentsDir(gitRoot) {
+  return path.join(gitRoot, 'components');
+}
+
+/**
+ * Read a previously-cached readme for a component without hitting the network.
+ * Returns null if there's nothing cached. Used so we can show short
+ * descriptions in prompts/lists without slowing down the command on a cold
+ * cache.
+ */
+export function readCachedReadme(name) {
+  return readCache(`${name}.readme.md`, Infinity);
+}
+
+/**
+ * Install a marketplace component into the user's local components/ folder.
+ * Used by both the `components add` subcommand and the auto-install path in
+ * `pretty`. Returns the destination path on success.
+ */
+export async function installComponent(gitRoot, name, { force = false } = {}) {
+  const comp = await fetchMarketplaceComponent(name, { force });
+  const dest = localComponentsDir(gitRoot);
+  fs.mkdirSync(dest, { recursive: true });
+  const file = path.join(dest, `${comp.name}.mdx`);
+  fs.writeFileSync(file, comp.mdx, 'utf-8');
+  return { name: comp.name, file, mdx: comp.mdx };
+}
+
+/**
+ * List components that have been copied into the user's local components/
+ * folder. Returns an array of { name, file, source } where `source` is the
+ * raw mdx contents.
+ */
+export function listLocalComponents(gitRoot) {
+  const dir = localComponentsDir(gitRoot);
+  if (!fs.existsSync(dir)) return [];
+
+  const out = [];
+  for (const entry of fs.readdirSync(dir)) {
+    if (!entry.endsWith('.mdx')) continue;
+    const file = path.join(dir, entry);
+    const source = fs.readFileSync(file, 'utf-8');
+    out.push({ name: entry.replace(/\.mdx$/, ''), file, source });
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}

package/src/utils/multi-spinner.js

@@ -0,0 +1,71 @@
+import { createLogUpdate } from 'log-update';
+import cliSpinners from 'cli-spinners';
+import chalk from 'chalk';
+
+/**
+ * Multi-row spinner. Renders `rows` labeled lines, repainted in unison at the
+ * spinner's tick interval. Cleared rows render as blank lines (the live region
+ * keeps a fixed height). Falls back to no-op render + line-buffered `log()`
+ * in non-TTY environments.
+ */
+export class MultiSpinner {
+  constructor({ rows, color = 'blue', stream = process.stderr } = {}) {
+    this.rows = Math.max(0, rows);
+    this.color = color;
+    this.stream = stream;
+    this.isTTY = !!stream.isTTY;
+    this.lines = new Array(this.rows).fill('');
+    this.frame = 0;
+    this.spinner = cliSpinners.dots;
+    this.timer = null;
+    this.update = null;
+  }
+
+  start() {
+    if (!this.isTTY) return;
+    this.update = createLogUpdate(this.stream);
+    this._render();
+    this.timer = setInterval(() => this._render(), this.spinner.interval);
+  }
+
+  setLine(rowIdx, text) {
+    if (!this.isTTY) return;
+    if (rowIdx < 0 || rowIdx >= this.rows) return;
+    this.lines[rowIdx] = text;
+  }
+
+  clearLine(rowIdx) {
+    this.setLine(rowIdx, '');
+  }
+
+  log(text) {
+    if (this.isTTY && this.update) {
+      this.update.persist(text);
+    } else {
+      this.stream.write(text + '\n');
+    }
+  }
+
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (this.update) {
+      this.update.clear();
+      this.update.done();
+      this.update = null;
+    }
+  }
+
+  _render() {
+    if (!this.update) return;
+    const glyph = this.spinner.frames[this.frame % this.spinner.frames.length];
+    const colorize = chalk[this.color] ?? ((s) => s);
+    const out = this.lines
+      .map((text) => (text ? `${colorize(glyph)} ${text}` : ''))
+      .join('\n');
+    this.update(out);
+    this.frame++;
+  }
+}

package/src/utils/promise-pool.js

@@ -0,0 +1,17 @@
+/**
+ * Run `worker` over `items` with at most `concurrency` calls in flight.
+ * Each worker pulls the next item from a shared cursor; finishes when none left.
+ * `worker(item, index, workerIdx)` is responsible for catching its own errors —
+ * an uncaught rejection will propagate up and abort other in-flight workers.
+ */
+export async function runPool(items, concurrency, worker) {
+  let cursor = 0;
+  const next = () => (cursor < items.length ? cursor++ : -1);
+  const lanes = Math.max(1, Math.min(concurrency, items.length));
+  const workers = Array.from({ length: lanes }, (_, workerIdx) => (async () => {
+    for (let i = next(); i !== -1; i = next()) {
+      await worker(items[i], i, workerIdx);
+    }
+  })());
+  await Promise.all(workers);
+}

package/src/validators/numbering.js

@@ -1,68 +1,65 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import readline from 'node:readline';
-import * as styles from '../utils/styles.js';
+import fs from 'node:fs'
+import path from 'node:path'
+import readline from 'node:readline'
+import * as styles from '../utils/styles.js'
 
-export const name = 'numbering';
+export const name = 'numbering'
 
-const SUFFIX_RE = /-(\d+)$/;
+const SUFFIX_RE = /-(\d+)$/
 
 function prompt(question) {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
   return new Promise((resolve) => {
     rl.question(question, (answer) => {
-      rl.close();
-      resolve(answer.trim().toLowerCase());
-    });
-  });
+      rl.close()
+      resolve(answer.trim().toLowerCase())
+    })
+  })
 }
 
 function updateOrderYaml(fromPath, toPath) {
-  const dir = path.dirname(fromPath);
-  const orderFile = path.join(dir, '_order.yaml');
-  if (!fs.existsSync(orderFile)) return;
+  const dir = path.dirname(fromPath)
+  const orderFile = path.join(dir, '_order.yaml')
+  if (!fs.existsSync(orderFile)) return
 
-  const oldSlug = path.basename(fromPath).replace(/\.(md|mdx)$/, '');
-  const newSlug = path.basename(toPath).replace(/\.(md|mdx)$/, '');
+  const oldSlug = path.basename(fromPath).replace(/\.(md|mdx)$/, '')
+  const newSlug = path.basename(toPath).replace(/\.(md|mdx)$/, '')
 
-  const content = fs.readFileSync(orderFile, 'utf-8');
-  const updated = content.replace(
-    new RegExp(`^(- )${oldSlug.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`, 'm'),
-    `$1${newSlug}`,
-  );
+  const content = fs.readFileSync(orderFile, 'utf-8')
+  const updated = content.replace(new RegExp(`^(- )${oldSlug.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`, 'm'), `$1${newSlug}`)
 
   if (updated !== content) {
-    fs.writeFileSync(orderFile, updated);
+    fs.writeFileSync(orderFile, updated)
   }
 }
 
-export async function validateAll(files, gitRoot, { fix } = {}) {
-  const results = [];
-  const renames = [];
+export async function validateAll(files, gitRoot, { fix, nonInteractive } = {}) {
+  const results = []
+  const renames = []
 
   // Collect all slugs (filenames without ext) and directory names across the repo.
-  const allSlugs = new Set();
-  const allDirs = new Set();
+  const allSlugs = new Set()
+  const allDirs = new Set()
   for (const relPath of files) {
-    allSlugs.add(path.basename(relPath).replace(/\.(md|mdx)$/, ''));
-    const parts = relPath.split('/');
+    allSlugs.add(path.basename(relPath).replace(/\.(md|mdx)$/, ''))
+    const parts = relPath.split('/')
     for (let i = 0; i < parts.length - 1; i++) {
-      allDirs.add(parts[i]);
+      allDirs.add(parts[i])
     }
   }
 
   // Check files: if slug ends with -N and the base slug doesn't exist anywhere, warn.
   for (const relPath of files) {
-    const slug = path.basename(relPath).replace(/\.(md|mdx)$/, '');
-    const match = slug.match(SUFFIX_RE);
-    if (!match) continue;
+    const slug = path.basename(relPath).replace(/\.(md|mdx)$/, '')
+    const match = slug.match(SUFFIX_RE)
+    if (!match) continue
 
-    const baseSlug = slug.slice(0, -match[0].length);
+    const baseSlug = slug.slice(0, -match[0].length)
     if (!allSlugs.has(baseSlug)) {
-      const ext = path.extname(relPath);
-      const from = path.join(gitRoot, relPath);
-      const toRel = path.join(path.dirname(relPath), `${baseSlug}${ext}`);
-      const to = path.join(gitRoot, toRel);
+      const ext = path.extname(relPath)
+      const from = path.join(gitRoot, relPath)
+      const toRel = path.join(path.dirname(relPath), `${baseSlug}${ext}`)
+      const to = path.join(gitRoot, toRel)
 
       results.push({
         file: relPath,
@@ -70,29 +67,29 @@ export async function validateAll(files, gitRoot, { fix } = {}) {
         severity: 'warning',
         fixable: true,
         message: `Unnecessary suffix: "${slug}${ext}" should be renamed to "${baseSlug}${ext}"`,
-      });
-      renames.push({ from, to, label: `${relPath} → ${toRel}` });
+      })
+      renames.push({ from, to, label: `${relPath} → ${toRel}` })
     }
   }
 
   // Check directories: if a dir name ends with -N and the base dir doesn't exist, warn.
-  const warnedDirs = new Set();
+  const warnedDirs = new Set()
   for (const relPath of files) {
-    const parts = relPath.split('/');
+    const parts = relPath.split('/')
     for (let i = 0; i < parts.length - 1; i++) {
-      const dirName = parts[i];
-      if (warnedDirs.has(dirName)) continue;
+      const dirName = parts[i]
+      if (warnedDirs.has(dirName)) continue
 
-      const match = dirName.match(SUFFIX_RE);
-      if (!match) continue;
+      const match = dirName.match(SUFFIX_RE)
+      if (!match) continue
 
-      const baseName = dirName.slice(0, -match[0].length);
+      const baseName = dirName.slice(0, -match[0].length)
       if (!allDirs.has(baseName)) {
-        warnedDirs.add(dirName);
-        const dirPath = parts.slice(0, i + 1).join('/');
-        const baseDirPath = [...parts.slice(0, i), baseName].join('/');
-        const from = path.join(gitRoot, dirPath);
-        const to = path.join(gitRoot, baseDirPath);
+        warnedDirs.add(dirName)
+        const dirPath = parts.slice(0, i + 1).join('/')
+        const baseDirPath = [...parts.slice(0, i), baseName].join('/')
+        const from = path.join(gitRoot, dirPath)
+        const to = path.join(gitRoot, baseDirPath)
 
         results.push({
           file: dirPath,
@@ -100,37 +97,38 @@ export async function validateAll(files, gitRoot, { fix } = {}) {
           severity: 'warning',
           fixable: true,
           message: `Unnecessary suffix: "${dirName}" folder should be renamed to "${baseName}"`,
-        });
-        renames.push({ from, to, label: `${dirPath}/ → ${baseDirPath}/` });
+        })
+        renames.push({ from, to, label: `${dirPath}/ → ${baseDirPath}/` })
       }
     }
   }
 
   // Interactive rename when --fix is passed.
   if (fix && renames.length > 0) {
-    console.log();
-    console.log(`  The following will be renamed:`);
+    console.log()
+    console.log(`  The following will be renamed:`)
     for (const r of renames) {
-      console.log(`    ${styles.dim(r.label)}`);
+      console.log(`    ${styles.dim(r.label)}`)
     }
-    console.log();
-    console.log(`  ${styles.warn('Note:')} Renaming changes slugs, which could break existing URLs.`);
-    console.log();
+    console.log()
+    console.log(`  ${styles.warn('Note:')} Renaming changes slugs, which could break existing URLs.`)
+    console.log()
 
-    const answer = await prompt(`  Rename ${renames.length} ${renames.length === 1 ? 'path' : 'paths'}? (y/N) `);
+    // assume yes if non-interactive, otherwise prompt for confirmation
+    const answer = nonInteractive ? 'yes' : await prompt(`  Rename ${renames.length} ${renames.length === 1 ? 'path' : 'paths'}? (y/N) `)
 
     if (answer === 'y' || answer === 'yes') {
       // Sort longest path first so nested dirs get renamed before parents.
-      renames.sort((a, b) => b.from.length - a.from.length);
+      renames.sort((a, b) => b.from.length - a.from.length)
       for (const r of renames) {
-        fs.renameSync(r.from, r.to);
-        updateOrderYaml(r.from, r.to);
+        fs.renameSync(r.from, r.to)
+        updateOrderYaml(r.from, r.to)
       }
       for (const r of results) {
-        r.message += ' (fixed)';
+        r.message += ' (fixed)'
       }
     }
   }
 
-  return results.length > 0 ? results : null;
+  return results.length > 0 ? results : null
 }