@readme/cli 0.1.0 → 0.3.0

package/src/commands/oas-validate.js

@@ -1,9 +1,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
+
 import OASNormalize from 'oas-normalize';
-import { findOasFiles, extractOperations } from './oas-sync.js';
-import * as styles from '../utils/styles.js';
+
 import { writeGithubActionsOutputs } from '../utils/gha-output.js';
+import * as styles from '../utils/styles.js';
+
+import { findOasFiles, extractOperations } from './oas-sync.js';
 
 export const command = 'oas:validate';
 export const order = 3;
@@ -114,7 +117,7 @@ export async function validateOas({ cwd, dereference = false } = {}) {
       continue;
     }
 
-    const errors = normalizerResult.valid ? [] : (normalizerResult.errors || []);
+    const errors = normalizerResult.valid ? [] : normalizerResult.errors || [];
     const warnings = normalizerResult.warnings || [];
 
     if (dereference) {
@@ -158,9 +161,7 @@ export async function validateOasFiles(gitRoot, { dereference = false } = {}) {
 
   for (const r of summary.results) {
     const meta = `${r.filename} · ${r.version} · ${r.opCount} ${r.opCount === 1 ? 'endpoint' : 'endpoints'}`;
-    const dot = r.errors.length > 0
-      ? styles.err('●')
-      : r.warnings.length > 0 ? styles.warn('●') : styles.success('●');
+    const dot = r.errors.length > 0 ? styles.err('●') : r.warnings.length > 0 ? styles.warn('●') : styles.success('●');
 
     console.log();
     console.log(`  ${dot} ${styles.bold(r.title)} ${styles.dim(`(${meta})`)}`);
@@ -224,7 +225,9 @@ export async function run(options, _cmd, ctx) {
     styles.error(`${parts.join(' and ')} across ${fileCount} ${fileCount === 1 ? 'spec' : 'specs'}.`);
     process.exit(1);
   } else if (totalWarnings > 0) {
-    styles.warning(`${totalValid} of ${fileCount} specs valid with ${totalWarnings} ${totalWarnings === 1 ? 'warning' : 'warnings'}.`);
+    styles.warning(
+      `${totalValid} of ${fileCount} specs valid with ${totalWarnings} ${totalWarnings === 1 ? 'warning' : 'warnings'}.`,
+    );
   } else {
     styles.ok(`${fileCount} ${fileCount === 1 ? 'spec' : 'specs'} validated — all good!`);
   }

package/src/commands/pretty.js

@@ -1,72 +1,73 @@
-import fs from 'node:fs'
-import path from 'node:path'
-import { createRequire } from 'node:module'
-import { query } from '@anthropic-ai/claude-agent-sdk'
-import { InvalidArgumentError, Option } from 'commander'
-import matter from 'gray-matter'
-import { collectFiles } from '../utils/lint.js'
-import { prettifyPagePrompt, prettifyPageOutputSchema } from '../prompts/index.js'
-import { printHeader, isAgenticCli } from '../utils/eyes.js'
-import { MultiSpinner } from '../utils/multi-spinner.js'
-import { runPool } from '../utils/promise-pool.js'
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { InvalidArgumentError, Option } from 'commander';
+
+import { prettifyPagePrompt, prettifyPageOutputSchema } from '../prompts/index.js';
+import { makeContainment, PathEscapeError } from '../utils/containment.js';
+import { printHeader, isAgenticCli } from '../utils/eyes.js';
+import { collectFiles } from '../utils/lint.js';
+import { parseFrontmatter, toFrontmatter, frontmatterWriteError } from '../utils/markdown.js';
 import {
   listLocalComponents,
   listMarketplaceComponents,
   installComponent,
   readCachedReadme,
   summarizeReadme,
-} from '../utils/marketplace.js'
-import * as styles from '../utils/styles.js'
+} from '../utils/marketplace.js';
+import { MultiSpinner } from '../utils/multi-spinner.js';
+import { runPool } from '../utils/promise-pool.js';
+import * as styles from '../utils/styles.js';
 
-const require = createRequire(import.meta.url)
-const pkg = require('../../package.json')
+const require = createRequire(import.meta.url);
+const pkg = require('../../package.json');
 
 /**
  * Native ReadMe MDX tags that don't need a marketplace install — the renderer
  * supports them out of the box. We exclude these from auto-install detection.
  */
-const NATIVE_TAGS = new Set([
-  'Tabs', 'Tab',
-  'Accordion',
-  'Cards', 'Card',
-  'Columns', 'Column',
-  'Image',
-])
+const NATIVE_TAGS = new Set(['Tabs', 'Tab', 'Accordion', 'Cards', 'Card', 'Columns', 'Column', 'Image']);
 
 /**
  * Pull every PascalCase tag name out of a block of mdx. Matches both
  * `<Foo ... />` and `<Foo>...</Foo>`. Returns a Set of unique names.
  */
 function extractUsedTags(mdx) {
-  const tags = new Set()
-  const re = /<([A-Z][A-Za-z0-9]*)\b/g
-  let m
-  while ((m = re.exec(mdx)) !== null) tags.add(m[1])
-  return tags
+  const tags = new Set();
+  const re = /<([A-Z][A-Za-z0-9]*)\b/g;
+  let m;
+  while ((m = re.exec(mdx)) !== null) tags.add(m[1]);
+  return tags;
 }
 
-export const command = 'pretty [file]'
-export const order = 2
-export const description = 'Polish docs into ReadMe-ready MDX with Claude'
-export const beta = true
+export const command = 'pretty [file]';
+export const order = 2;
+export const description = 'Polish docs into ReadMe-ready MDX with Claude';
+export const beta = true;
 
 export function args(cmd) {
-  cmd.addOption(new Option('-m, --model <name>', 'Claude model alias: haiku, sonnet, opus').choices(['haiku', 'sonnet', 'opus']).default('sonnet'))
-
-  cmd.option('--dry-run', 'Show what would change without writing files')
-  cmd.option('--no-auto-install', 'Don\'t auto-install marketplace components used in output')
+  cmd.addOption(
+    new Option('-m, --model <name>', 'Claude model alias: haiku, sonnet, opus')
+      .choices(['haiku', 'sonnet', 'opus'])
+      .default('sonnet'),
+  );
+
+  cmd.option('--dry-run', 'Show what would change without writing files');
+  cmd.option('--no-auto-install', "Don't auto-install marketplace components used in output");
   cmd.option(
     '-j, --jobs <n>',
     'Number of files to prettify in parallel',
-    (raw) => {
-      const n = Number(raw)
+    raw => {
+      const n = Number(raw);
       if (!Number.isInteger(n) || n < 1) {
-        throw new InvalidArgumentError('must be a positive integer')
+        throw new InvalidArgumentError('must be a positive integer');
       }
-      return n
+      return n;
     },
     1,
-  )
+  );
 }
 
 /**
@@ -76,41 +77,41 @@ export function args(cmd) {
  * through to the next strategy.
  */
 async function fetchWithRetry(url, { headers = {}, retries = 3, baseDelayMs = 1000 } = {}) {
-  const maxAttempts = retries + 1
-  let lastError
+  const maxAttempts = retries + 1;
+  let lastError;
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     try {
       const res = await fetch(url, {
         redirect: 'follow',
         headers: { 'User-Agent': 'readme-cli-pretty', ...headers },
-      })
+      });
       if (!res.ok) {
-        const err = new Error(`HTTP ${res.status} ${res.statusText}`)
-        err.status = res.status
-        throw err
+        const err = new Error(`HTTP ${res.status} ${res.statusText}`);
+        err.status = res.status;
+        throw err;
       }
-      return await res.text()
+      return await res.text();
     } catch (err) {
-      lastError = err
-      if (err.status && err.status >= 400 && err.status < 500) break
+      lastError = err;
+      if (err.status && err.status >= 400 && err.status < 500) break;
       if (attempt < maxAttempts) {
-        const delay = baseDelayMs * Math.pow(2, attempt - 1)
-        await new Promise((resolve) => setTimeout(resolve, delay))
+        const delay = baseDelayMs * 2 ** (attempt - 1);
+        await new Promise(resolve => setTimeout(resolve, delay));
       }
     }
   }
-  throw lastError
+  throw lastError;
 }
 
 function withMdExtension(url) {
   try {
-    const u = new URL(url)
-    if (u.pathname.endsWith('.md')) return null
-    u.pathname = u.pathname.replace(/\/$/, '') + '.md'
-    return u.toString()
+    const u = new URL(url);
+    if (u.pathname.endsWith('.md')) return null;
+    u.pathname = `${u.pathname.replace(/\/$/, '')}.md`;
+    return u.toString();
   } catch {
-    if (url.endsWith('.md')) return null
-    return url.replace(/\/$/, '') + '.md'
+    if (url.endsWith('.md')) return null;
+    return `${url.replace(/\/$/, '')}.md`;
   }
 }
 
@@ -122,21 +123,21 @@ function withMdExtension(url) {
  * Each strategy gets its own retry budget for transient failures.
  */
 async function fetchImport(url, opts = {}) {
-  const strategies = []
-  const mdUrl = withMdExtension(url)
-  if (mdUrl) strategies.push({ url: mdUrl })
-  strategies.push({ url, headers: { Accept: 'text/markdown' } })
-  strategies.push({ url })
+  const strategies = [];
+  const mdUrl = withMdExtension(url);
+  if (mdUrl) strategies.push({ url: mdUrl });
+  strategies.push({ url, headers: { Accept: 'text/markdown' } });
+  strategies.push({ url });
 
-  let lastError
+  let lastError;
   for (const strategy of strategies) {
     try {
-      return await fetchWithRetry(strategy.url, { ...opts, headers: strategy.headers })
+      return await fetchWithRetry(strategy.url, { ...opts, headers: strategy.headers });
     } catch (err) {
-      lastError = err
+      lastError = err;
     }
   }
-  throw new Error(`failed to fetch ${url}: ${lastError?.message || lastError}`)
+  throw new Error(`failed to fetch ${url}: ${lastError?.message || lastError}`);
 }
 
 /**
@@ -152,10 +153,14 @@ async function fetchImport(url, opts = {}) {
  */
 async function prettifyPage({ source, title, relativePath, model, localComponents, availableComponents }) {
   const { systemPrompt, userPrompt } = prettifyPagePrompt({
-    source, title, relativePath, localComponents, availableComponents,
-  })
-
-  let structured
+    source,
+    title,
+    relativePath,
+    localComponents,
+    availableComponents,
+  });
+
+  let structured;
   for await (const message of query({
     prompt: userPrompt,
     options: {
@@ -167,131 +172,145 @@ async function prettifyPage({ source, title, relativePath, model, localComponent
   })) {
     if (message.type === 'result') {
       if (message.subtype !== 'success') {
-        throw new Error(`${message.subtype}${message.error?.message ? ' — ' + message.error.message : ''}`)
+        throw new Error(`${message.subtype}${message.error?.message ? ` — ${message.error.message}` : ''}`);
       }
-      structured = message.structured_output
-      break
+      structured = message.structured_output;
+      break;
     }
   }
 
   if (!structured || typeof structured !== 'object') {
-    throw new Error('agent returned no structured output')
+    throw new Error('agent returned no structured output');
   }
 
-  let oasPartial = null
+  let oasPartial = null;
   if (typeof structured.oasPartialJson === 'string' && structured.oasPartialJson.length > 0) {
     try {
-      oasPartial = JSON.parse(structured.oasPartialJson)
+      oasPartial = JSON.parse(structured.oasPartialJson);
     } catch (e) {
-      throw new Error(`invalid oasPartialJson (${e.message}); first 200 chars: ${structured.oasPartialJson.slice(0, 200)}`)
+      throw new Error(
+        `invalid oasPartialJson (${e.message}); first 200 chars: ${structured.oasPartialJson.slice(0, 200)}`,
+        { cause: e },
+      );
     }
   }
 
-  return { body: structured.body, isApiRef: structured.isApiRef, oasPartial }
+  return { body: structured.body, isApiRef: structured.isApiRef, oasPartial };
 }
 
 export async function run(file, options, _cmd, ctx) {
-  const { gitRoot } = ctx
+  const { gitRoot } = ctx;
 
   if (!isAgenticCli()) {
-    printHeader({ version: pkg.version, binName: styles.binName(), indent: '  ' })
-    console.log()
+    printHeader({ version: pkg.version, binName: styles.binName(), indent: '  ' });
+    console.log();
   }
 
-  let files
+  // Lexical `path.relative` treats a symlink inside the repo as inside it,
+  // and the later write follows the link. Same check `oas:sync` uses.
+  const assertContained = makeContainment(gitRoot, { label: 'repository' });
+
+  let files;
   if (file) {
-    const absFile = path.resolve(file)
+    const absFile = path.resolve(file);
     if (!fs.existsSync(absFile)) {
-      styles.error(`File not found: ${styles.bold(file)}`)
-      process.exit(1)
+      styles.error(`File not found: ${styles.bold(file)}`);
+      process.exit(1);
     }
-    const relFile = path.relative(gitRoot, absFile)
-    if (relFile.startsWith('..') || path.isAbsolute(relFile)) {
-      styles.error(`File must be inside the repo: ${styles.bold(file)}`)
-      process.exit(1)
+
+    try {
+      assertContained(absFile);
+    } catch (err) {
+      if (!(err instanceof PathEscapeError)) throw err;
+      styles.error(err.message);
+      process.exit(1);
     }
-    files = [relFile]
+
+    files = [path.relative(gitRoot, absFile)];
   } else {
-    files = collectFiles(gitRoot)
+    files = collectFiles(gitRoot);
   }
 
   if (files.length === 0) {
-    styles.warning('No docs files found to prettify.')
-    return
+    styles.warning('No docs files found to prettify.');
+    return;
   }
 
-  const localComponents = listLocalComponents(gitRoot)
-  const localNames = new Set(localComponents.map((c) => c.name))
+  const localComponents = listLocalComponents(gitRoot);
+  const localNames = new Set(localComponents.map(c => c.name));
 
   // Pull the full marketplace catalog so Claude knows what else it can use.
   // Summaries come from disk cache (populated by `readme components list`);
   // we don't fetch readmes here to keep the prompt path fast.
-  let marketplace = []
+  let marketplace = [];
   if (options.autoInstall !== false) {
     try {
-      marketplace = await listMarketplaceComponents()
+      marketplace = await listMarketplaceComponents();
     } catch (err) {
-      styles.warning(`Could not load marketplace catalog: ${err.message} (continuing without it)`)
+      styles.warning(`Could not load marketplace catalog: ${err.message} (continuing without it)`);
     }
   }
-  const marketplaceNames = new Set(marketplace.map((c) => c.name))
+  const marketplaceNames = new Set(marketplace.map(c => c.name));
   const availableComponents = marketplace
-    .filter((c) => !localNames.has(c.name))
-    .map((c) => ({ name: c.name, summary: summarizeReadme(readCachedReadme(c.name)) }))
+    .filter(c => !localNames.has(c.name))
+    .map(c => ({ name: c.name, summary: summarizeReadme(readCachedReadme(c.name)) }));
 
   // Concurrent workers may both try to install the same component. Coalesce
   // duplicate installs through a Map<tag, Promise> — the second caller awaits
   // the first's install instead of clobbering it.
-  const inFlightInstalls = new Map()
-  const autoInstalled = new Set()
+  const inFlightInstalls = new Map();
+  const autoInstalled = new Set();
   function ensureInstalled(tag) {
-    if (inFlightInstalls.has(tag)) return inFlightInstalls.get(tag)
+    if (inFlightInstalls.has(tag)) return inFlightInstalls.get(tag);
     const p = (async () => {
-      await installComponent(gitRoot, tag)
-      localNames.add(tag)
-      autoInstalled.add(tag)
-    })()
-    inFlightInstalls.set(tag, p)
-    return p
+      await installComponent(gitRoot, tag);
+      localNames.add(tag);
+      autoInstalled.add(tag);
+    })();
+    inFlightInstalls.set(tag, p);
+    return p;
   }
 
   styles.info(
-    `Prettifying ${styles.bold(String(files.length))} file${files.length === 1 ? '' : 's'} with ${styles.bold(options.model)}${options.jobs > 1 ? ` (${styles.bold('-j ' + options.jobs)})` : ''}${options.dryRun ? styles.dim(' (dry run)') : ''}.`,
-  )
+    `Prettifying ${styles.bold(String(files.length))} file${files.length === 1 ? '' : 's'} with ${styles.bold(options.model)}${options.jobs > 1 ? ` (${styles.bold(`-j ${options.jobs}`)})` : ''}${options.dryRun ? styles.dim(' (dry run)') : ''}.`,
+  );
   if (localComponents.length > 0) {
     styles.info(
-      `Found ${styles.bold(String(localComponents.length))} local component${localComponents.length === 1 ? '' : 's'} in ${styles.bold('./components/')}: ${localComponents.map((c) => c.name).join(', ')}`,
-    )
+      `Found ${styles.bold(String(localComponents.length))} local component${localComponents.length === 1 ? '' : 's'} in ${styles.bold('./components/')}: ${localComponents.map(c => c.name).join(', ')}`,
+    );
   }
   if (options.autoInstall !== false && availableComponents.length > 0) {
     styles.info(
       `${styles.bold(String(availableComponents.length))} additional marketplace component${availableComponents.length === 1 ? '' : 's'} will be auto-installed if used.`,
-    )
+    );
   }
-  console.log()
+  console.log();
 
-  let updated = 0
-  let unchanged = 0
-  const failures = []
+  let updated = 0;
+  let unchanged = 0;
+  const failures = [];
 
-  const rows = Math.min(options.jobs, files.length)
-  const multi = new MultiSpinner({ rows, color: 'blue' })
-  multi.start()
+  const rows = Math.min(options.jobs, files.length);
+  const multi = new MultiSpinner({ rows, color: 'blue' });
+  multi.start();
 
   await runPool(files, options.jobs, async (relativePath, _i, workerIdx) => {
-    multi.setLine(workerIdx, relativePath)
+    multi.setLine(workerIdx, relativePath);
 
     try {
-      const filePath = path.join(gitRoot, relativePath)
-      const original = fs.readFileSync(filePath, 'utf-8')
-      const parsed = matter(original)
-
-      let source = parsed.content
-      const importUrl = parsed.data?.['x-import']
+      const filePath = path.join(gitRoot, relativePath);
+      assertContained(filePath);
+      const original = fs.readFileSync(filePath, 'utf-8');
+      const parsed = parseFrontmatter(original);
+      const parseError = frontmatterWriteError(parsed);
+      if (parseError) throw parseError;
+
+      let source = parsed.content;
+      const importUrl = parsed.data?.['x-import'];
       if (importUrl) {
-        multi.setLine(workerIdx, `${relativePath} ${styles.dim(`(fetching ${importUrl})`)}`)
-        source = await fetchImport(importUrl)
-        multi.setLine(workerIdx, relativePath)
+        multi.setLine(workerIdx, `${relativePath} ${styles.dim(`(fetching ${importUrl})`)}`);
+        source = await fetchImport(importUrl);
+        multi.setLine(workerIdx, relativePath);
       }
 
       const result = await prettifyPage({
@@ -301,10 +320,10 @@ export async function run(file, options, _cmd, ctx) {
         model: options.model,
         localComponents,
         availableComponents: options.autoInstall === false ? [] : availableComponents,
-      })
+      });
 
       if (typeof result?.body !== 'string') {
-        throw new Error('response missing "body" field')
+        throw new TypeError('response missing "body" field');
       }
 
       // Auto-install marketplace components Claude used in the body. We do
@@ -312,59 +331,63 @@ export async function run(file, options, _cmd, ctx) {
       // together — and we share the inFlightInstalls map across workers so a
       // tag is only fetched once.
       if (options.autoInstall !== false && !options.dryRun) {
-        const used = extractUsedTags(result.body)
+        const used = extractUsedTags(result.body);
         for (const tag of used) {
-          if (NATIVE_TAGS.has(tag)) continue
-          if (localNames.has(tag)) continue
-          if (!marketplaceNames.has(tag)) continue
+          if (NATIVE_TAGS.has(tag)) continue;
+          if (localNames.has(tag)) continue;
+          if (!marketplaceNames.has(tag)) continue;
           try {
-            multi.setLine(workerIdx, `${relativePath} ${styles.dim(`(installing <${tag}>)`)}`)
-            await ensureInstalled(tag)
+            multi.setLine(workerIdx, `${relativePath} ${styles.dim(`(installing <${tag}>)`)}`);
+            await ensureInstalled(tag);
           } catch (err) {
-            failures.push({ relativePath, message: `auto-install <${tag}> failed: ${err.message}` })
+            failures.push({ relativePath, message: `auto-install <${tag}> failed: ${err.message}` });
           }
         }
-        multi.setLine(workerIdx, relativePath)
+        multi.setLine(workerIdx, relativePath);
       }
 
-      const newFm = { ...parsed.data }
-      delete newFm.hidden
-      delete newFm['x-import']
-      if (result.excerpt && !newFm.excerpt) newFm.excerpt = result.excerpt
-      const next = matter.stringify(result.body, newFm)
+      const newFm = { ...parsed.data };
+      delete newFm.hidden;
+      delete newFm['x-import'];
+      if (result.excerpt && !newFm.excerpt) newFm.excerpt = result.excerpt;
+      const next = toFrontmatter(newFm, result.body);
 
       if (next === original) {
-        unchanged++
-        if (!process.stderr.isTTY) multi.log(`  ${styles.dim('·')} ${relativePath}`)
+        unchanged++;
+        if (!process.stderr.isTTY) multi.log(`  ${styles.dim('·')} ${relativePath}`);
       } else {
-        if (!options.dryRun) fs.writeFileSync(filePath, next, 'utf-8')
-        updated++
-        if (!process.stderr.isTTY) multi.log(`  ${styles.success('✓')} ${relativePath}`)
+        if (!options.dryRun) fs.writeFileSync(filePath, next, 'utf-8');
+        updated++;
+        if (!process.stderr.isTTY) multi.log(`  ${styles.success('✓')} ${relativePath}`);
       }
     } catch (err) {
-      failures.push({ relativePath, message: err.message || String(err) })
+      failures.push({ relativePath, message: err.message || String(err) });
       if (!process.stderr.isTTY) {
-        multi.log(`  ${styles.err('●')} ${relativePath} ${styles.dim('— ' + (err.message || String(err)))}`)
+        multi.log(`  ${styles.err('●')} ${relativePath} ${styles.dim(`— ${err.message || String(err)}`)}`);
       }
     } finally {
-      multi.clearLine(workerIdx)
+      multi.clearLine(workerIdx);
     }
-  })
+  });
 
-  multi.stop()
+  multi.stop();
 
-  console.log()
-  const verb = options.dryRun ? 'would update' : 'updated'
-  styles.ok(`${styles.bold(String(updated))} ${verb} · ${styles.bold(String(unchanged))} unchanged${failures.length ? ` · ${styles.bold(String(failures.length))} failed` : ''}`)
+  console.log();
+  const verb = options.dryRun ? 'would update' : 'updated';
+  styles.ok(
+    `${styles.bold(String(updated))} ${verb} · ${styles.bold(String(unchanged))} unchanged${failures.length ? ` · ${styles.bold(String(failures.length))} failed` : ''}`,
+  );
   if (autoInstalled.size > 0) {
-    styles.ok(`Auto-installed ${styles.bold(String(autoInstalled.size))} component${autoInstalled.size === 1 ? '' : 's'}: ${[...autoInstalled].join(', ')}`)
+    styles.ok(
+      `Auto-installed ${styles.bold(String(autoInstalled.size))} component${autoInstalled.size === 1 ? '' : 's'}: ${[...autoInstalled].join(', ')}`,
+    );
   }
 
   if (failures.length > 0) {
-    console.log()
+    console.log();
     for (const f of failures) {
-      console.log(`  ${styles.err('●')} ${styles.bold(f.relativePath)} ${styles.dim('— ' + f.message)}`)
+      console.log(`  ${styles.err('●')} ${styles.bold(f.relativePath)} ${styles.dim(`— ${f.message}`)}`);
     }
-    process.exit(1)
+    process.exit(1);
   }
 }