@readme/cli 0.1.0 → 0.2.0

package/src/dev/app/layout.js

@@ -1,7 +1,9 @@
-import { collectSidebar } from '../lib/docs';
-import { SidebarNav, SidebarPanel } from './Sidebar';
 import '@readme/markdown/dist/main.css';
+
+import { collectSidebar } from '../lib/docs';
+
 import './globals.css';
+import { SidebarNav, SidebarPanel } from './Sidebar';
 
 export const metadata = {
   title: {
@@ -21,10 +23,13 @@ export default async function RootLayout({ children }) {
       </head>
       <body className="bg-[#000343] text-gray-900 antialiased">
         {/* Top Navigation */}
-        <header className="fixed top-0 inset-x-0 h-[48px] bg-[#000343] flex items-center px-5 z-50" style={{
-          backgroundImage: `linear-gradient(rgba(255,255,255,0.08) 1px, transparent 1px), linear-gradient(90deg, rgba(255,255,255,0.08) 1px, transparent 1px)`,
-          backgroundSize: '20px 20px',
-        }}>
+        <header
+          className="fixed top-0 inset-x-0 h-[48px] bg-[#000343] flex items-center px-5 z-50"
+          style={{
+            backgroundImage: `linear-gradient(rgba(255,255,255,0.08) 1px, transparent 1px), linear-gradient(90deg, rgba(255,255,255,0.08) 1px, transparent 1px)`,
+            backgroundSize: '20px 20px',
+          }}
+        >
           <div className="flex items-center gap-3 mr-8 shrink-0">
             <div className="flex items-center gap-2">
               <i className="fa-brands fa-readme text-[#018ef5] text-[18px] relative top-[1px]" />
@@ -50,17 +55,19 @@ export default async function RootLayout({ children }) {
 
           {/* Content */}
           <main className="ml-[300px] flex-1 min-w-0 bg-white rounded-tr-xl">
-            <div className="max-w-[820px] py-10 px-16">
-              {children}
-            </div>
+            <div className="max-w-[820px] py-10 px-16">{children}</div>
           </main>
         </div>
 
-        <style dangerouslySetInnerHTML={{ __html: `
+        <style
+          dangerouslySetInnerHTML={{
+            __html: `
           [data-sidebar-group][data-expanded="false"] .sidebar-children { display: none; }
           [data-sidebar-group][data-expanded="true"] .sidebar-children { display: block; }
           [data-sidebar-group][data-expanded="true"] .sidebar-chevron { transform: rotate(90deg); }
-        `}} />
+        `,
+          }}
+        />
         <script
           dangerouslySetInnerHTML={{
             __html: `(function(){var es=new EventSource('/__reload');es.onmessage=function(e){if(e.data==='reload')location.reload()};})();

package/src/dev/app/page.js

@@ -1,4 +1,5 @@
 import { redirect } from 'next/navigation';
+
 import { getFirstPageHref } from '../lib/docs';
 
 export const dynamic = 'force-dynamic';

package/src/dev/lib/docs.js

@@ -1,9 +1,11 @@
-import { createRequire } from 'node:module';
 import fs from 'fs';
+import { createRequire } from 'node:module';
 import path from 'path';
-import matter from 'gray-matter';
+
 import { compile, run } from '@readme/markdown';
-import yaml from 'js-yaml';
+import { load as loadYAML } from 'js-yaml';
+
+import { parseFrontmatter } from '../../utils/markdown.js';
 
 // Use createRequire to load react-dom/server at runtime,
 // bypassing Next.js App Router's static import restriction.
@@ -36,7 +38,7 @@ function walkDir(dirPath, sectionDir, depth = 0) {
   let order = [];
   const orderPath = path.join(dirPath, '_order.yaml');
   if (fs.existsSync(orderPath)) {
-    order = yaml.load(fs.readFileSync(orderPath, 'utf-8')) || [];
+    order = loadYAML(fs.readFileSync(orderPath, 'utf-8')) || [];
   }
 
   // Get all items (exclude dotfiles and _-prefixed files)
@@ -90,16 +92,14 @@ function walkDir(dirPath, sectionDir, depth = 0) {
       // If either exists, treat this as a clickable parent page.
       const indexPath = path.join(dirPath, name, 'index.md');
       const siblingMdPath = path.join(dirPath, `${name}.md`);
-      const parentPagePath = fs.existsSync(indexPath)
-        ? indexPath
-        : fs.existsSync(siblingMdPath) ? siblingMdPath : null;
+      const parentPagePath = fs.existsSync(indexPath) ? indexPath : fs.existsSync(siblingMdPath) ? siblingMdPath : null;
 
       let title = name;
       let href = null;
       let hidden = false;
       let icon = null;
       if (parentPagePath) {
-        const { data } = matter(fs.readFileSync(parentPagePath, 'utf-8'));
+        const { data } = parseFrontmatter(fs.readFileSync(parentPagePath, 'utf-8'));
         title = data.title || name;
         href = `/${sectionDir}/${encodeURIComponent(name)}`;
         hidden = !!data.hidden;
@@ -112,7 +112,7 @@ function walkDir(dirPath, sectionDir, depth = 0) {
       mdFiles.delete(name);
     } else if (isMd) {
       const filePath = path.join(dirPath, `${name}.md`);
-      const { data } = matter(fs.readFileSync(filePath, 'utf-8'));
+      const { data } = parseFrontmatter(fs.readFileSync(filePath, 'utf-8'));
       const linkUrl = data.link?.url;
       entries.push({
         title: data.title || name,
@@ -152,7 +152,7 @@ function loadCustomBlocks(docsRoot) {
 
   for (const file of files) {
     const raw = fs.readFileSync(path.join(blocksDir, file), 'utf-8');
-    const { data, content } = matter(raw);
+    const { data, content } = parseFrontmatter(raw);
     const name = data.name || path.basename(file, path.extname(file));
     sources[name] = content;
     modules[name] = run(compile(content));
@@ -202,7 +202,7 @@ export function getPage(slugArray) {
   if (!filePath) return null;
 
   const raw = fs.readFileSync(filePath, 'utf-8');
-  const { data, content } = matter(raw);
+  const { data, content } = parseFrontmatter(raw);
 
   let html;
 
@@ -254,7 +254,7 @@ function renderOasOperationPreview(specFile, operationId) {
   let spec;
   try {
     const rawSpec = fs.readFileSync(specPath, 'utf-8');
-    spec = specFile.toLowerCase().endsWith('.json') ? JSON.parse(rawSpec) : yaml.load(rawSpec);
+    spec = specFile.toLowerCase().endsWith('.json') ? JSON.parse(rawSpec) : loadYAML(rawSpec);
   } catch (e) {
     return `<p><em>Couldn't parse <code>reference/${specFile}</code>: ${escapeHtml(e.message)}</em></p>`;
   }
@@ -272,16 +272,21 @@ function renderOasOperationPreview(specFile, operationId) {
   }
 
   const { method, path: opPath, op } = found;
-  const methodColor = {
-    GET: '#22c55e', POST: '#3b82f6', PUT: '#f59e0b', PATCH: '#a855f7', DELETE: '#ef4444',
-  }[method] || '#6b7280';
+  const methodColor =
+    {
+      GET: '#22c55e',
+      POST: '#3b82f6',
+      PUT: '#f59e0b',
+      PATCH: '#a855f7',
+      DELETE: '#ef4444',
+    }[method] || '#6b7280';
 
   const parts = [];
   parts.push(
     `<div style="display: flex; gap: 0.5rem; align-items: center; margin-bottom: 1rem;">` +
-    `<span style="background: ${methodColor}; color: white; padding: 0.15rem 0.5rem; border-radius: 0.25rem; font-family: monospace; font-weight: 600; font-size: 0.85rem;">${method}</span>` +
-    `<code style="font-size: 1rem;">${escapeHtml(opPath)}</code>` +
-    `</div>`,
+      `<span style="background: ${methodColor}; color: white; padding: 0.15rem 0.5rem; border-radius: 0.25rem; font-family: monospace; font-weight: 600; font-size: 0.85rem;">${method}</span>` +
+      `<code style="font-size: 1rem;">${escapeHtml(opPath)}</code>` +
+      `</div>`,
   );
   if (op.description) parts.push(`<p>${escapeHtml(op.description)}</p>`);
 
@@ -317,7 +322,10 @@ function renderOasOperationPreview(specFile, operationId) {
 }
 
 function escapeHtml(s) {
-  return String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+  return String(s).replace(
+    /[&<>"']/g,
+    c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c],
+  );
 }
 
 function findFirstHref(items) {

package/src/dev/next.config.mjs

@@ -10,8 +10,8 @@ export default {
   // Next's SWC loader excludes `node_modules` from JSX transformation by
   // default. Marking our own package as a transpile target bypasses that.
   transpilePackages: ['@readme/cli'],
-  serverExternalPackages: ['gray-matter', 'js-yaml', '@readme/markdown'],
-  webpack: (config) => {
+  serverExternalPackages: ['js-yaml', '@readme/markdown'],
+  webpack: config => {
     // Suppress noisy cache serialization warnings from large @readme/markdown bundle
     config.infrastructureLogging = {
       ...config.infrastructureLogging,

package/src/gha.js

@@ -17,8 +17,8 @@
 // let it do what it already does, exit code included.
 
 import * as lint from './commands/lint.js';
-import * as oasValidate from './commands/oas-validate.js';
 import * as oasSync from './commands/oas-sync.js';
+import * as oasValidate from './commands/oas-validate.js';
 import { writeGithubActionsOutputs } from './utils/gha-output.js';
 
 // Each command's run(options, cmd, ctx) only ever reads specific boolean
@@ -26,8 +26,8 @@ import { writeGithubActionsOutputs } from './utils/gha-output.js';
 // (the commander Command instance normal CLI invocation would pass) — so a
 // plain options object and a null cmd are enough here.
 const COMMANDS = {
-  'lint': { run: lint.run, flags: ['json', 'github', 'fix'] },
-  'validate': { run: lint.run, flags: ['json', 'github', 'fix'] }, // alias, matches src/commands/lint.js
+  lint: { run: lint.run, flags: ['json', 'github', 'fix'] },
+  validate: { run: lint.run, flags: ['json', 'github', 'fix'] }, // alias, matches src/commands/lint.js
   'oas:validate': { run: oasValidate.run, flags: ['dereference'] },
   'oas:sync': { run: oasSync.run, flags: [] },
 };
@@ -46,7 +46,7 @@ export async function run() {
   if (!entry) {
     console.error(
       `::error::Unknown or unsupported command "${command || '(empty)'}" for the \`readme\` input. ` +
-        `Supported: ${[...new Set(Object.keys(COMMANDS).filter((k) => k !== 'validate'))].join(', ')}.`,
+        `Supported: ${[...new Set(Object.keys(COMMANDS).filter(k => k !== 'validate'))].join(', ')}.`,
     );
     writeGithubActionsOutputs({ 'has-errors': 'true' });
     process.exit(1);
@@ -72,8 +72,8 @@ export async function run() {
 
   if (badTokens.length > 0) {
     console.error(
-      `::error::Unknown option${badTokens.length > 1 ? 's' : ''} ${badTokens.map((t) => `"${t}"`).join(', ')} for "${command}". ` +
-        `Supported: ${entry.flags.length > 0 ? entry.flags.map((f) => `--${f}`).join(', ') : '(none)'}.`,
+      `::error::Unknown option${badTokens.length > 1 ? 's' : ''} ${badTokens.map(t => `"${t}"`).join(', ')} for "${command}". ` +
+        `Supported: ${entry.flags.length > 0 ? entry.flags.map(f => `--${f}`).join(', ') : '(none)'}.`,
     );
     writeGithubActionsOutputs({ 'has-errors': 'true' });
     process.exit(1);
@@ -89,7 +89,7 @@ export async function run() {
   await entry.run(options, null, { gitRoot });
 }
 
-run().catch((err) => {
+run().catch(err => {
   console.error(err);
   // A thrown error (as opposed to a command's own controlled process.exit)
   // means whatever run() was doing never reached its own

package/src/prompts/index.js

@@ -25,7 +25,7 @@ export const slotOrphansSystemPrompt = [
   'Example output: {"assignments": [0, 2, 0, 1, -1, 3]}',
   '',
   'Guidance:',
-  '- Choose the best semantic fit based on the orphan\'s title and URL path.',
+  "- Choose the best semantic fit based on the orphan's title and URL path.",
   '- Only use -1 when no existing category is plausible.',
 ].join('\n');
 
@@ -54,13 +54,18 @@ export const slotOrphansOutputSchema = {
  */
 export function buildSlotOrphansUserPrompt({ categories, orphans }) {
   const catList = categories.map((c, i) => {
-    const sample = (c.pages || []).slice(0, 3).map((p) => p.title).join(', ');
+    const sample = (c.pages || [])
+      .slice(0, 3)
+      .map(p => p.title)
+      .join(', ');
     return `${i}. ${c.title}${sample ? ` (e.g. ${sample})` : ''}`;
   });
 
   const orphanList = orphans.map((p, i) => {
     let relPath = p.url;
-    try { relPath = new URL(p.url).pathname; } catch {}
+    try {
+      relPath = new URL(p.url).pathname;
+    } catch {}
     return `${i}. ${p.title} — ${relPath}`;
   });
 
@@ -264,13 +269,17 @@ export const organizeFromScratchOutputSchema = {
 export function buildOrganizeFromScratchUserPrompt({ siteTitle, items }) {
   const compactLines = items.map((it, idx) => {
     let relPath = it.url;
-    try { relPath = new URL(it.url).pathname + new URL(it.url).search; } catch {}
+    try {
+      relPath = new URL(it.url).pathname + new URL(it.url).search;
+    } catch {}
     return `${idx}\t${it.title}\t${relPath}`;
   });
 
   let origin = '(unknown)';
   if (items.length > 0) {
-    try { origin = new URL(items[0].url).origin; } catch {}
+    try {
+      origin = new URL(items[0].url).origin;
+    } catch {}
   }
 
   return [
@@ -507,7 +516,8 @@ export function prettifyPagePrompt(input) {
  * @returns {string}
  */
 export function stripCodeFences(text) {
-  return String(text).trim()
+  return String(text)
+    .trim()
     .replace(/^```json\s*/i, '')
     .replace(/^```\s*/i, '')
     .replace(/\s*```$/, '')

package/src/utils/eyes.js

@@ -19,7 +19,15 @@ export const palettes = {
   red: { name: 'Red', body: '#EF4444', page: '#FFF5F5', pupil: '#7F1D1D', lid: '#FCA5A5' },
   teal: { name: 'Teal', body: '#14B8A6', page: '#F0FFFE', pupil: '#134E4A', lid: '#5EEAD4' },
   yellow: { name: 'Yellow', body: '#EAB308', page: '#FEFCE8', pupil: '#713F12', lid: '#FDE047' },
-  owl: { name: 'Owl', body: '#8B5A2B', page: '#FFF8EE', pupil: '#2A1000', lid: '#C4923A', nose: '#FFD700', hidden: true },
+  owl: {
+    name: 'Owl',
+    body: '#8B5A2B',
+    page: '#FFF8EE',
+    pupil: '#2A1000',
+    lid: '#C4923A',
+    nose: '#FFD700',
+    hidden: true,
+  },
 };
 
 let currentPalette = palettes.blue;
@@ -124,7 +132,21 @@ function rebuildExpressions() {
 
 export const animations = {
   blink: {
-    frames: ['right', 'right', 'right', 'right', 'right', 'right', 'half-blink', 'squint', 'closed', 'closed', 'squint', 'half-blink', 'right'],
+    frames: [
+      'right',
+      'right',
+      'right',
+      'right',
+      'right',
+      'right',
+      'half-blink',
+      'squint',
+      'closed',
+      'closed',
+      'squint',
+      'half-blink',
+      'right',
+    ],
     durations: [1500, 100, 100, 100, 100, 100, 50, 50, 50, 80, 50, 50, 100],
   },
 
@@ -134,85 +156,154 @@ export const animations = {
   },
 
   lookaround: {
-    frames: ['right', 'right', 'left', 'left', 'left', 'right', 'right', 'up-right', 'up-right', 'right', 'right', 'up-left', 'up-left', 'left', 'left', 'right'],
+    frames: [
+      'right',
+      'right',
+      'left',
+      'left',
+      'left',
+      'right',
+      'right',
+      'up-right',
+      'up-right',
+      'right',
+      'right',
+      'up-left',
+      'up-left',
+      'left',
+      'left',
+      'right',
+    ],
     durations: [600, 200, 120, 400, 200, 120, 400, 120, 400, 120, 200, 120, 400, 120, 200, 400],
   },
 
   'lookaround-blink': {
     frames: [
-      'right', 'right', 'right',
-      'left', 'left', 'left',
-      'half-blink', 'squint', 'closed', 'closed', 'squint', 'half-blink',
-      'left', 'right', 'right',
-      'up-right', 'up-right', 'right',
-      'right', 'right',
-      'up-left', 'up-left', 'left', 'left',
-      'half-blink', 'squint', 'closed', 'closed', 'squint', 'half-blink',
-      'right', 'right',
+      'right',
+      'right',
+      'right',
+      'left',
+      'left',
+      'left',
+      'half-blink',
+      'squint',
+      'closed',
+      'closed',
+      'squint',
+      'half-blink',
+      'left',
+      'right',
+      'right',
+      'up-right',
+      'up-right',
+      'right',
+      'right',
+      'right',
+      'up-left',
+      'up-left',
+      'left',
+      'left',
+      'half-blink',
+      'squint',
+      'closed',
+      'closed',
+      'squint',
+      'half-blink',
+      'right',
+      'right',
     ],
     durations: [
-      800, 200, 200,
-      120, 400, 200,
-      50, 50, 50, 80, 50, 50,
-      200, 120, 400,
-      120, 500, 120,
-      200, 200,
-      120, 500, 120, 200,
-      50, 50, 50, 80, 50, 50,
-      120, 600,
+      800, 200, 200, 120, 400, 200, 50, 50, 50, 80, 50, 50, 200, 120, 400, 120, 500, 120, 200, 200, 120, 500, 120, 200,
+      50, 50, 50, 80, 50, 50, 120, 600,
     ],
   },
 
   all: {
     frames: [
       // idle, look around
-      'right', 'right', 'right',
-      'left', 'left', 'left',
-      'right', 'right',
+      'right',
+      'right',
+      'right',
+      'left',
+      'left',
+      'left',
+      'right',
+      'right',
       // blink
-      'half-blink', 'squint', 'closed', 'closed', 'squint', 'half-blink',
+      'half-blink',
+      'squint',
+      'closed',
+      'closed',
+      'squint',
+      'half-blink',
       // look up + bounce
-      'right', 'right',
-      'up-right', 'up-right', 'right',
-      'right:up', 'right:up', 'right', 'right:up', 'right:up', 'right',
+      'right',
+      'right',
+      'up-right',
+      'up-right',
+      'right',
+      'right:up',
+      'right:up',
+      'right',
+      'right:up',
+      'right:up',
+      'right',
       // look the other way
-      'right', 'left', 'left',
-      'up-left', 'up-left', 'left',
+      'right',
+      'left',
+      'left',
+      'up-left',
+      'up-left',
+      'left',
       // blink
-      'half-blink', 'squint', 'closed', 'closed', 'squint', 'half-blink',
+      'half-blink',
+      'squint',
+      'closed',
+      'closed',
+      'squint',
+      'half-blink',
       // bounce
-      'left', 'left:up', 'left:up', 'left', 'left:up', 'left:up', 'left',
+      'left',
+      'left:up',
+      'left:up',
+      'left',
+      'left:up',
+      'left:up',
+      'left',
       // settle back + bounce
-      'right', 'right', 'right',
-      'right:up', 'right:up', 'right',
+      'right',
+      'right',
+      'right',
+      'right:up',
+      'right:up',
+      'right',
       // blink
-      'half-blink', 'squint', 'closed', 'closed', 'squint', 'half-blink',
-      'right', 'right',
+      'half-blink',
+      'squint',
+      'closed',
+      'closed',
+      'squint',
+      'half-blink',
+      'right',
+      'right',
     ],
     durations: [
       // idle, look around
-      800, 200, 200,
-      120, 400, 200,
-      120, 400,
+      800, 200, 200, 120, 400, 200, 120, 400,
       // blink
       50, 50, 50, 80, 50, 50,
       // look up + bounce
-      200, 200,
-      120, 500, 120,
-      150, 150, 150, 150, 150, 200,
+      200, 200, 120, 500, 120, 150, 150, 150, 150, 150, 200,
       // look the other way
-      300, 120, 400,
-      120, 500, 120,
+      300, 120, 400, 120, 500, 120,
       // blink
       50, 50, 50, 80, 50, 50,
       // bounce
       200, 150, 150, 150, 150, 150, 200,
       // settle back + bounce
-      120, 200, 300,
-      150, 150, 200,
+      120, 200, 300, 150, 150, 200,
       // blink
-      50, 50, 50, 80, 50, 50,
-      200, 800,
+      50, 50, 50, 80, 50, 50, 200, 800,
     ],
   },
 };
@@ -253,7 +344,7 @@ export function header(opts = {}) {
   const icon = eyes(expression);
   const gap = '  ';
 
-  const title = chalk.bold.hex(currentPalette.body)('The ReadMe CLI') + (version ? ' ' + chalk.dim(`v${version}`) : '');
+  const title = chalk.bold.hex(currentPalette.body)('The ReadMe CLI') + (version ? ` ${chalk.dim(`v${version}`)}` : '');
   const bin = binName ? chalk.white(binName) : '';
   const greetLine = greeting ? chalk.dim(greeting) : '';
 
@@ -296,7 +387,8 @@ export function animate(name, opts = {}) {
   const headerLines = [];
   if (version || bin) {
     const gap = '  ';
-    headerLines[0] = gap + chalk.bold.hex(currentPalette.body)('The ReadMe CLI') + (version ? ' ' + chalk.dim(`v${version}`) : '');
+    headerLines[0] =
+      gap + chalk.bold.hex(currentPalette.body)('The ReadMe CLI') + (version ? ` ${chalk.dim(`v${version}`)}` : '');
     headerLines[1] = gap + (bin ? chalk.white(bin) : '');
     if (subtitle) headerLines[2] = gap + subtitle;
   }
@@ -340,7 +432,7 @@ export function animate(name, opts = {}) {
       firstDraw = false;
 
       for (const line of lines) {
-        process.stdout.write(indent + line + '\n');
+        process.stdout.write(`${indent + line}\n`);
       }
 
       const duration = anim.durations[i % anim.durations.length];

package/src/utils/git.js

@@ -63,10 +63,10 @@ export function detectRemotePlatform() {
   const remotes = readRemotes();
   if (!remotes) return null;
   for (const [key, def] of Object.entries(PLATFORMS)) {
-    if (def.remoteHosts && def.remoteHosts.some((h) => remotes.toLowerCase().includes(h))) {
+    if (def.remoteHosts && def.remoteHosts.some(h => remotes.toLowerCase().includes(h))) {
       return key;
     }
-    if (def.remotePathHints && def.remotePathHints.some((p) => remotes.toLowerCase().includes(p))) {
+    if (def.remotePathHints && def.remotePathHints.some(p => remotes.toLowerCase().includes(p))) {
       return key;
     }
   }
@@ -81,7 +81,7 @@ export function detectExistingCi(gitRoot) {
   if (!gitRoot) return [];
   const found = [];
   for (const [key, def] of Object.entries(PLATFORMS)) {
-    const hit = def.fsMarkers.some((marker) => fs.existsSync(path.join(gitRoot, marker)));
+    const hit = def.fsMarkers.some(marker => fs.existsSync(path.join(gitRoot, marker)));
     if (hit) found.push(key);
   }
   return found;