npm - @readme/cli - Versions diffs - 0.0.26 - Mend

@readme/cli 0.0.26

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (144) hide show

package/README.md +55 -0
package/bin/readme.js +8 -0
package/package.json +58 -0
package/src/bootstrap.js +97 -0
package/src/cli.js +189 -0
package/src/commands/dev.js +119 -0
package/src/commands/eyes.js +37 -0
package/src/commands/import.js +2565 -0
package/src/commands/lint.js +70 -0
package/src/commands/oas-sync.js +364 -0
package/src/commands/oas-validate.js +208 -0
package/src/commands/play.js +17 -0
package/src/commands/pretty.js +133 -0
package/src/commands/setup.js +256 -0
package/src/commands/versions.js +81 -0
package/src/dev/.next/app-build-manifest.json +20 -0
package/src/dev/.next/build-manifest.json +31 -0
package/src/dev/.next/cache/.rscinfo +1 -0
package/src/dev/.next/cache/next-devtools-config.json +1 -0
package/src/dev/.next/cache/webpack/client-development/0.pack.gz +0 -0
package/src/dev/.next/cache/webpack/client-development/1.pack.gz +0 -0
package/src/dev/.next/cache/webpack/client-development/10.pack.gz +0 -0
package/src/dev/.next/cache/webpack/client-development/11.pack.gz +0 -0
package/src/dev/.next/cache/webpack/client-development/2.pack.gz +0 -0
package/src/dev/.next/cache/webpack/client-development/3.pack.gz +0 -0
package/src/dev/.next/cache/webpack/client-development/3.pack.gz_ +0 -0
package/src/dev/.next/cache/webpack/client-development/4.pack.gz +0 -0
package/src/dev/.next/cache/webpack/client-development/5.pack.gz +0 -0
package/src/dev/.next/cache/webpack/client-development/5.pack.gz_ +0 -0
package/src/dev/.next/cache/webpack/client-development/6.pack.gz +0 -0
package/src/dev/.next/cache/webpack/client-development/7.pack.gz +0 -0
package/src/dev/.next/cache/webpack/client-development/7.pack.gz_ +0 -0
package/src/dev/.next/cache/webpack/client-development/8.pack.gz +0 -0
package/src/dev/.next/cache/webpack/client-development/9.pack.gz +0 -0
package/src/dev/.next/cache/webpack/client-development/index.pack.gz.old +0 -0
package/src/dev/.next/cache/webpack/client-development-fallback/0.pack.gz +0 -0
package/src/dev/.next/cache/webpack/client-development-fallback/1.pack.gz +0 -0
package/src/dev/.next/cache/webpack/client-development-fallback/index.pack.gz +0 -0
package/src/dev/.next/cache/webpack/client-development-fallback/index.pack.gz.old +0 -0
package/src/dev/.next/cache/webpack/edge-server-development/0.pack.gz +0 -0
package/src/dev/.next/cache/webpack/edge-server-development/1.pack.gz +0 -0
package/src/dev/.next/cache/webpack/edge-server-development/index.pack.gz +0 -0
package/src/dev/.next/cache/webpack/edge-server-development/index.pack.gz.old +0 -0
package/src/dev/.next/cache/webpack/server-development/0.pack.gz +0 -0
package/src/dev/.next/cache/webpack/server-development/1.pack.gz +0 -0
package/src/dev/.next/cache/webpack/server-development/10.pack.gz +0 -0
package/src/dev/.next/cache/webpack/server-development/11.pack.gz +0 -0
package/src/dev/.next/cache/webpack/server-development/12.pack.gz +0 -0
package/src/dev/.next/cache/webpack/server-development/13.pack.gz +0 -0
package/src/dev/.next/cache/webpack/server-development/14.pack.gz +0 -0
package/src/dev/.next/cache/webpack/server-development/15.pack.gz +0 -0
package/src/dev/.next/cache/webpack/server-development/2.pack.gz +0 -0
package/src/dev/.next/cache/webpack/server-development/2.pack.gz_ +0 -0
package/src/dev/.next/cache/webpack/server-development/3.pack.gz +0 -0
package/src/dev/.next/cache/webpack/server-development/3.pack.gz_ +0 -0
package/src/dev/.next/cache/webpack/server-development/4.pack.gz +0 -0
package/src/dev/.next/cache/webpack/server-development/5.pack.gz +0 -0
package/src/dev/.next/cache/webpack/server-development/6.pack.gz +0 -0
package/src/dev/.next/cache/webpack/server-development/6.pack.gz_ +0 -0
package/src/dev/.next/cache/webpack/server-development/7.pack.gz +0 -0
package/src/dev/.next/cache/webpack/server-development/7.pack.gz_ +0 -0
package/src/dev/.next/cache/webpack/server-development/8.pack.gz +0 -0
package/src/dev/.next/cache/webpack/server-development/9.pack.gz +0 -0
package/src/dev/.next/cache/webpack/server-development/9.pack.gz_ +0 -0
package/src/dev/.next/cache/webpack/server-development/index.pack.gz +0 -0
package/src/dev/.next/cache/webpack/server-development/index.pack.gz.old +0 -0
package/src/dev/.next/package.json +1 -0
package/src/dev/.next/prerender-manifest.json +11 -0
package/src/dev/.next/react-loadable-manifest.json +1 -0
package/src/dev/.next/routes-manifest.json +1 -0
package/src/dev/.next/server/app/[...slug]/page.js +360 -0
package/src/dev/.next/server/app/[...slug]/page_client-reference-manifest.js +1 -0
package/src/dev/.next/server/app/page.js +349 -0
package/src/dev/.next/server/app/page_client-reference-manifest.js +1 -0
package/src/dev/.next/server/app-paths-manifest.json +3 -0
package/src/dev/.next/server/edge-runtime-webpack.js +1151 -0
package/src/dev/.next/server/interception-route-rewrite-manifest.js +1 -0
package/src/dev/.next/server/middleware-build-manifest.js +33 -0
package/src/dev/.next/server/middleware-manifest.json +32 -0
package/src/dev/.next/server/middleware-react-loadable-manifest.js +1 -0
package/src/dev/.next/server/middleware.js +1113 -0
package/src/dev/.next/server/next-font-manifest.js +1 -0
package/src/dev/.next/server/next-font-manifest.json +1 -0
package/src/dev/.next/server/pages-manifest.json +5 -0
package/src/dev/.next/server/server-reference-manifest.js +1 -0
package/src/dev/.next/server/server-reference-manifest.json +5 -0
package/src/dev/.next/server/static/webpack/633457081244afec._.hot-update.json +1 -0
package/src/dev/.next/server/vendor-chunks/@readme.js +25 -0
package/src/dev/.next/server/vendor-chunks/@swc.js +55 -0
package/src/dev/.next/server/vendor-chunks/next.js +3659 -0
package/src/dev/.next/server/webpack-runtime.js +209 -0
package/src/dev/.next/static/chunks/app/[...slug]/loading.js +28 -0
package/src/dev/.next/static/chunks/app/[...slug]/page.js +28 -0
package/src/dev/.next/static/chunks/app/layout.js +171 -0
package/src/dev/.next/static/chunks/app/page.js +28 -0
package/src/dev/.next/static/chunks/app-pages-internals.js +182 -0
package/src/dev/.next/static/chunks/main-app.js +1882 -0
package/src/dev/.next/static/chunks/polyfills.js +1 -0
package/src/dev/.next/static/chunks/webpack.js +1393 -0
package/src/dev/.next/static/css/app/layout.css +559 -0
package/src/dev/.next/static/development/_buildManifest.js +1 -0
package/src/dev/.next/static/development/_ssgManifest.js +1 -0
package/src/dev/.next/static/webpack/633457081244afec._.hot-update.json +1 -0
package/src/dev/.next/static/webpack/ec52a3fce0f78db0.webpack.hot-update.json +1 -0
package/src/dev/.next/static/webpack/webpack.ec52a3fce0f78db0.hot-update.js +12 -0
package/src/dev/.next/trace +21 -0
package/src/dev/.next/types/app/[...slug]/page.ts +84 -0
package/src/dev/.next/types/app/layout.ts +84 -0
package/src/dev/.next/types/app/page.ts +84 -0
package/src/dev/.next/types/cache-life.d.ts +141 -0
package/src/dev/.next/types/package.json +1 -0
package/src/dev/.next/types/routes.d.ts +55 -0
package/src/dev/app/Sidebar.js +149 -0
package/src/dev/app/[...slug]/loading.js +16 -0
package/src/dev/app/[...slug]/page.js +43 -0
package/src/dev/app/globals.css +167 -0
package/src/dev/app/layout.js +73 -0
package/src/dev/app/page.js +19 -0
package/src/dev/lib/docs.js +337 -0
package/src/dev/middleware.js +7 -0
package/src/dev/next.config.mjs +22 -0
package/src/index.js +12 -0
package/src/prompts/index.js +352 -0
package/src/utils/claude.js +15 -0
package/src/utils/eyes.js +365 -0
package/src/utils/git.js +143 -0
package/src/utils/lint.js +99 -0
package/src/utils/reporter.js +319 -0
package/src/utils/setup-templates.js +323 -0
package/src/utils/styles.js +50 -0
package/src/utils/tamagotchi.js +1139 -0
package/src/utils/tips.js +90 -0
package/src/validators/components.js +230 -0
package/src/validators/content.js +53 -0
package/src/validators/duplicates.js +45 -0
package/src/validators/frontmatter.js +247 -0
package/src/validators/links.js +68 -0
package/src/validators/nesting.js +50 -0
package/src/validators/numbering.js +136 -0
package/src/validators/oas-reference.js +126 -0
package/src/validators/oas-schema.js +106 -0
package/src/validators/ordering.js +121 -0
package/src/validators/recipes.js +143 -0
package/vendor/TOOLS.md +19 -0

package/src/dev/app/globals.css ADDED Viewed

@@ -0,0 +1,167 @@
+:root {
+  /* @readme/markdown component color variables */
+  --blue-rgb: 1, 142, 245;
+  --yellow-rgb: 245, 174, 0;
+  --green-rgb: 0, 175, 80;
+  --red-rgb: 235, 55, 35;
+  --color-border-default: rgba(0, 0, 0, 0.06);
+  --color-text-default: #1a1a2e;
+  --color-text-muted: #4f5a66;
+  --color-text-minimum: #637288;
+  --markdown-radius: 8px;
+  --md-code-background: #f8fafc;
+  --md-code-text: #1e293b;
+  --md-code-radius: 8px;
+  --border-radius-lg: 8px;
+  --markdown-text: #374151;
+  --markdown-font: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  --markdown-line-height: 1.75;
+  --markdown-font-size: 15.5px;
+  --markdown-title: #0f172a;
+  --markdown-title-font: inherit;
+  --markdown-edge: #e2e8f0;
+}
+/*
+ * Content area prose styling.
+ * This targets rendered markdown injected via dangerouslySetInnerHTML
+ * where we can't apply Tailwind utility classes directly.
+ */
+.content h1 {
+  font-size: 2rem;
+  font-weight: 800;
+  letter-spacing: -0.025em;
+  line-height: 1.2;
+  color: #0f172a;
+  margin-bottom: 0.5rem;
+}
+.excerpt {
+  font-size: 1.05rem;
+  color: #64748b;
+  line-height: 1.6;
+  margin-bottom: 2rem;
+}
+.content h2 {
+  font-size: 1.45rem;
+  font-weight: 700;
+  color: #0f172a;
+  letter-spacing: -0.01em;
+  margin: 2.5rem 0 0.75rem;
+  padding-bottom: 0.5rem;
+  border-bottom: 1px solid #f1f5f9;
+}
+.content h3 {
+  font-size: 1.15rem;
+  font-weight: 600;
+  color: #1e293b;
+  margin: 2rem 0 0.5rem;
+}
+.content p {
+  font-size: 15.5px;
+  line-height: 1.75;
+  color: #374151;
+  margin-bottom: 1.25rem;
+}
+.content ul,
+.content ol {
+  margin: 0 0 1.25rem 1.5rem;
+  line-height: 1.75;
+  color: #374151;
+}
+.content li {
+  margin-bottom: 0.25rem;
+}
+.content code {
+  font-family: 'SF Mono', 'Fira Code', Menlo, Consolas, monospace;
+  font-size: 13px;
+  background: #f1f5f9;
+  color: #0f172a;
+  padding: 0.15em 0.4em;
+  border-radius: 5px;
+  font-weight: 500;
+}
+.content pre {
+  background: #0f172a;
+  color: #e2e8f0;
+  padding: 1.25rem 1.5rem;
+  border-radius: 12px;
+  overflow-x: auto;
+  margin-bottom: 1.5rem;
+  font-size: 13.5px;
+  line-height: 1.65;
+  border: 1px solid rgba(255, 255, 255, 0.06);
+}
+.content pre code {
+  background: none;
+  padding: 0;
+  color: inherit;
+  font-size: inherit;
+  font-weight: normal;
+  border-radius: 0;
+}
+.content a {
+  color: #018ef5;
+  text-decoration: none;
+  font-weight: 500;
+}
+.content a:hover {
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+.content blockquote {
+  border-left: 3px solid #018ef5;
+  padding: 0.75rem 1.25rem;
+  margin: 0 0 1.5rem;
+  color: #475569;
+  background: #f8fafc;
+  border-radius: 0 10px 10px 0;
+  font-size: 15px;
+}
+.content table {
+  width: 100%;
+  border-collapse: collapse;
+  margin-bottom: 1.5rem;
+  font-size: 14.5px;
+}
+.content th,
+.content td {
+  border: 1px solid #e2e8f0;
+  padding: 0.6rem 1rem;
+  text-align: left;
+}
+.content th {
+  background: #f8fafc;
+  font-weight: 600;
+  color: #1e293b;
+  font-size: 13px;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+}
+.content img {
+  max-width: 100%;
+  border-radius: 12px;
+  margin: 0.5rem 0;
+}
+.content hr {
+  border: none;
+  border-top: 1px solid #f1f5f9;
+  margin: 2rem 0;
+}

package/src/dev/app/layout.js ADDED Viewed

@@ -0,0 +1,73 @@
+import { collectSidebar } from '../lib/docs';
+import { SidebarNav, SidebarPanel } from './Sidebar';
+import '@readme/markdown/dist/main.css';
+import './globals.css';
+export const metadata = {
+  title: {
+    default: 'Dev Preview',
+    template: '%s | Dev Preview',
+  },
+};
+export default async function RootLayout({ children }) {
+  const sidebar = collectSidebar();
+  return (
+    <html lang="en">
+      <head>
+        <script src="https://cdn.tailwindcss.com"></script>
+        <link rel="stylesheet" href="https://kit.fontawesome.com/b331e91c9c.css" crossOrigin="anonymous" />
+      </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',
+        }}>
+          <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]" />
+              <span className="text-white/90 font-mono text-[13px] tracking-tight mr-1">dev server</span>
+            </div>
+            <span className="relative group flex items-center">
+              <span className="text-[8px] font-semibold bg-white/20 text-white/50 group-hover:bg-white/30 group-hover:text-white/70 px-1.5 py-[3px] rounded uppercase tracking-wider cursor-default transition-colors duration-150">
+                beta
+              </span>
+              <span className="pointer-events-none absolute left-1/2 -translate-x-1/2 top-full mt-5 z-[100] w-48 rounded-lg bg-gray-900 px-3 py-2 text-[11px] leading-snug text-white/80 opacity-0 group-hover:opacity-100 transition-opacity duration-150 shadow-lg">
+                This is a local preview — it won't look exactly like your published docs.
+              </span>
+            </span>
+          </div>
+          <SidebarNav sidebar={sidebar} />
+        </header>
+        <div className="flex pt-[48px] min-h-screen">
+          {/* Sidebar */}
+          <aside className="w-[300px] fixed top-[48px] left-0 bottom-0 bg-white rounded-tl-xl border-r border-gray-200 overflow-y-auto py-4 pl-5">
+            <SidebarPanel sidebar={sidebar} />
+          </aside>
+          {/* 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>
+          </main>
+        </div>
+        <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()};})();
+document.addEventListener('click',function(e){var t=e.target.closest('[data-sidebar-toggle]');if(!t)return;var g=t.closest('[data-sidebar-group]');if(!g)return;if(t.getAttribute('href')==='#'){e.preventDefault();}var ex=g.getAttribute('data-expanded')==='true';g.setAttribute('data-expanded',ex?'false':'true');});`,
+          }}
+        />
+      </body>
+    </html>
+  );
+}

package/src/dev/app/page.js ADDED Viewed

@@ -0,0 +1,19 @@
+import { redirect } from 'next/navigation';
+import { getFirstPageHref } from '../lib/docs';
+export const dynamic = 'force-dynamic';
+export default function HomePage() {
+  const firstHref = getFirstPageHref();
+  if (firstHref) {
+    redirect(firstHref);
+  }
+  return (
+    <div className="flex flex-col items-center justify-center py-24 text-center">
+      <div className="w-12 h-12 rounded-xl bg-gray-100 flex items-center justify-center text-2xl mb-4">📝</div>
+      <h1 className="text-xl font-semibold text-gray-900 mb-1">Welcome</h1>
+      <p className="text-sm text-gray-400">No documentation pages found.</p>
+    </div>
+  );
+}

package/src/dev/lib/docs.js ADDED Viewed

@@ -0,0 +1,337 @@
+import { createRequire } from 'node:module';
+import fs from 'fs';
+import path from 'path';
+import matter from 'gray-matter';
+import { compile, run } from '@readme/markdown';
+import yaml from 'js-yaml';
+// Use createRequire to load react-dom/server at runtime,
+// bypassing Next.js App Router's static import restriction.
+const _require = createRequire(import.meta.url);
+const React = _require('react');
+const { renderToStaticMarkup } = _require('react-dom/server');
+const DOCS_ROOT = process.env.DOCS_ROOT;
+const SECTIONS = [
+  { dir: 'docs', label: 'Docs' },
+  { dir: 'reference', label: 'Reference' },
+  { dir: 'custom_pages', label: 'Custom Pages' },
+  { dir: 'recipes', label: 'Recipes' },
+];
+// Max folder nesting per section — anything deeper doesn't render in ReadMe's
+// sidebar, so we mirror the cap here. Keep in sync with src/validators/nesting.js.
+const MAX_DEPTH = {
+  docs: 3,
+  reference: 3,
+  recipes: 0,
+  custom_pages: 0,
+};
+function walkDir(dirPath, sectionDir, depth = 0) {
+  if (!fs.existsSync(dirPath)) return [];
+  // Read _order.yaml for ordering
+  let order = [];
+  const orderPath = path.join(dirPath, '_order.yaml');
+  if (fs.existsSync(orderPath)) {
+    order = yaml.load(fs.readFileSync(orderPath, 'utf-8')) || [];
+  }
+  // Get all items (exclude dotfiles and _-prefixed files)
+  const items = fs.readdirSync(dirPath).filter(f => !f.startsWith('.') && !f.startsWith('_'));
+  const mdFiles = new Set(items.filter(f => f.endsWith('.md') && f !== 'index.md').map(f => f.replace(/\.md$/, '')));
+  const dirs = new Set(
+    items.filter(f => {
+      try {
+        return fs.statSync(path.join(dirPath, f)).isDirectory();
+      } catch {
+        return false;
+      }
+    }),
+  );
+  // Build ordered list: ordered items first, then any remaining
+  const allNames = new Set([...mdFiles, ...dirs]);
+  const ordered = order.filter(name => allNames.has(name));
+  const remaining = [...allNames].filter(name => !ordered.includes(name));
+  const finalOrder = [...ordered, ...remaining];
+  const entries = [];
+  for (const name of finalOrder) {
+    const isDir = dirs.has(name);
+    const isMd = mdFiles.has(name);
+    if (isDir) {
+      // Skip folders whose contents would exceed ReadMe's sidebar nesting
+      // cap — they won't render in production, so don't show them here either.
+      const maxDepth = MAX_DEPTH[sectionDir];
+      if (maxDepth !== undefined && depth + 1 > maxDepth) continue;
+      const children = walkDir(path.join(dirPath, name), sectionDir, depth + 1);
+      // ReadMeConfig pages are internal — show them without a group header
+      if (name === 'ReadMeConfig') {
+        entries.push(...children);
+        continue;
+      }
+      // A directory can represent either:
+      //   1. A pure category (no content of its own) → render as group label
+      //   2. A parent page with children → render as a clickable page with
+      //      a nested list underneath
+      //
+      // Two file layouts signal #2:
+      //   a. `<name>/index.md` — the "index" convention
+      //   b. `<parent>/<name>.md` right alongside the `<name>/` folder
+      //      (sibling convention) — the importer writes parent pages this way
+      // 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;
+      let title = name;
+      let href = null;
+      let hidden = false;
+      let icon = null;
+      if (parentPagePath) {
+        const { data } = matter(fs.readFileSync(parentPagePath, 'utf-8'));
+        title = data.title || name;
+        href = `/${sectionDir}/${encodeURIComponent(name)}`;
+        hidden = !!data.hidden;
+        icon = data.icon || null;
+      }
+      entries.push({ title, href, hidden, icon, children });
+      // If a sibling .md is providing the parent content, remove it from
+      // mdFiles so we don't also render it as a standalone page below.
+      mdFiles.delete(name);
+    } else if (isMd) {
+      const filePath = path.join(dirPath, `${name}.md`);
+      const { data } = matter(fs.readFileSync(filePath, 'utf-8'));
+      const linkUrl = data.link?.url;
+      entries.push({
+        title: data.title || name,
+        href: linkUrl || `/${sectionDir}/${encodeURIComponent(name)}`,
+        external: !!linkUrl,
+        hidden: !!data.hidden,
+        icon: data.icon || null,
+        children: [],
+      });
+    }
+  }
+  return entries;
+}
+export function collectSidebar() {
+  const sections = [];
+  for (const { dir, label } of SECTIONS) {
+    const fullPath = path.join(DOCS_ROOT, dir);
+    if (!fs.existsSync(fullPath)) continue;
+    const children = walkDir(fullPath, dir);
+    if (children.length > 0) {
+      sections.push({ title: label, dir, firstHref: findFirstHref(children), children });
+    }
+  }
+  return sections;
+}
+function loadCustomBlocks(docsRoot) {
+  const blocksDir = path.join(docsRoot, 'custom_blocks');
+  if (!fs.existsSync(blocksDir)) return { sources: {}, modules: {} };
+  const files = fs.readdirSync(blocksDir).filter(f => f.endsWith('.md') || f.endsWith('.mdx'));
+  const sources = {};
+  const modules = {};
+  for (const file of files) {
+    const raw = fs.readFileSync(path.join(blocksDir, file), 'utf-8');
+    const { data, content } = matter(raw);
+    const name = data.name || path.basename(file, path.extname(file));
+    sources[name] = content;
+    modules[name] = run(compile(content));
+  }
+  return { sources, modules };
+}
+// Recursively find a .md file matching the given slug within a directory
+function findFile(dirPath, slug) {
+  if (!fs.existsSync(dirPath)) return null;
+  // Check for slug.md directly in this directory
+  const direct = path.join(dirPath, `${slug}.md`);
+  if (fs.existsSync(direct)) return direct;
+  // Check for slug/index.md
+  const index = path.join(dirPath, slug, 'index.md');
+  if (fs.existsSync(index)) return index;
+  // Search subdirectories
+  const entries = fs.readdirSync(dirPath).filter(f => !f.startsWith('.') && !f.startsWith('_'));
+  for (const entry of entries) {
+    const full = path.join(dirPath, entry);
+    try {
+      if (fs.statSync(full).isDirectory()) {
+        const found = findFile(full, slug);
+        if (found) return found;
+      }
+    } catch {
+      // skip
+    }
+  }
+  return null;
+}
+export function getPage(slugArray) {
+  // slugArray = ['docs', 'getting-started'] or ['reference', 'getPet']
+  const [section, ...rest] = slugArray.map(s => decodeURIComponent(s));
+  const slug = rest.join('/');
+  if (!section || !slug) return null;
+  const sectionPath = path.join(DOCS_ROOT, section);
+  const filePath = findFile(sectionPath, slug);
+  if (!filePath) return null;
+  const raw = fs.readFileSync(filePath, 'utf-8');
+  const { data, content } = matter(raw);
+  let html;
+  // Reference pages stubbed by the import command (or by oas:sync) have an
+  // empty body — the real endpoint UI comes from the OAS spec at render
+  // time. The production ReadMe renderer handles this; our local dev server
+  // used to show a blank page. If we see `api.file` + `api.operationId`,
+  // render a minimal preview from the spec so the page isn't empty.
+  if (data.api?.file && data.api?.operationId && !content.trim()) {
+    html = renderOasOperationPreview(data.api.file, data.api.operationId);
+  } else {
+    try {
+      const { sources, modules } = loadCustomBlocks(DOCS_ROOT);
+      const compiled = compile(content, { components: sources });
+      const mod = run(compiled, { components: modules });
+      // Suppress React warnings about class vs className from raw HTML in markdown
+      const origError = console.error;
+      console.error = (...args) => {
+        if (typeof args[0] === 'string' && args[0].includes('Invalid DOM property')) return;
+        origError.apply(console, args);
+      };
+      html = renderToStaticMarkup(React.createElement(mod.default));
+      console.error = origError;
+    } catch {
+      html = `<p><em>Error rendering MDX. Raw content below:</em></p><pre>${content.replace(/</g, '&lt;')}</pre>`;
+    }
+  }
+  return {
+    title: data.title || slug,
+    excerpt: data.excerpt || '',
+    html,
+  };
+}
+/**
+ * Render a small HTML preview of one OAS operation — method badge, path,
+ * description, and parameter list. Not a full interactive API reference
+ * (production ReadMe handles that); just enough so dev server pages show
+ * something meaningful instead of a blank body.
+ */
+function renderOasOperationPreview(specFile, operationId) {
+  const specPath = path.join(DOCS_ROOT, 'reference', specFile);
+  if (!fs.existsSync(specPath)) {
+    return `<p><em>OAS spec not found: <code>reference/${specFile}</code></em></p>`;
+  }
+  let spec;
+  try {
+    const rawSpec = fs.readFileSync(specPath, 'utf-8');
+    spec = specFile.toLowerCase().endsWith('.json') ? JSON.parse(rawSpec) : yaml.load(rawSpec);
+  } catch (e) {
+    return `<p><em>Couldn't parse <code>reference/${specFile}</code>: ${escapeHtml(e.message)}</em></p>`;
+  }
+  let found = null;
+  for (const [pathKey, pathItem] of Object.entries(spec.paths || {})) {
+    for (const [method, op] of Object.entries(pathItem || {})) {
+      if (op && typeof op === 'object' && op.operationId === operationId) {
+        found = { method: method.toUpperCase(), path: pathKey, op };
+      }
+    }
+  }
+  if (!found) {
+    return `<p><em>Operation <code>${escapeHtml(operationId)}</code> not found in <code>${escapeHtml(specFile)}</code>.</em></p>`;
+  }
+  const { method, path: opPath, op } = found;
+  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>`,
+  );
+  if (op.description) parts.push(`<p>${escapeHtml(op.description)}</p>`);
+  if (Array.isArray(op.parameters) && op.parameters.length > 0) {
+    parts.push(`<h2>Parameters</h2>`);
+    parts.push(`<ul>`);
+    for (const p of op.parameters) {
+      const name = p.name || '(unnamed)';
+      const where = p.in ? ` <code style="color: #6b7280;">(${p.in})</code>` : '';
+      const required = p.required ? ' <strong>required</strong>' : '';
+      const desc = p.description ? ` — ${escapeHtml(p.description)}` : '';
+      parts.push(`<li><code>${escapeHtml(name)}</code>${where}${required}${desc}</li>`);
+    }
+    parts.push(`</ul>`);
+  }
+  if (op.responses && typeof op.responses === 'object') {
+    parts.push(`<h2>Responses</h2>`);
+    parts.push(`<ul>`);
+    for (const [status, resp] of Object.entries(op.responses)) {
+      const desc = resp?.description ? ` — ${escapeHtml(resp.description)}` : '';
+      parts.push(`<li><code>${escapeHtml(status)}</code>${desc}</li>`);
+    }
+    parts.push(`</ul>`);
+  }
+  parts.push(
+    `<hr style="margin: 2rem 0; border: 0; border-top: 1px solid #e5e7eb;">`,
+    `<p style="color: #6b7280; font-size: 0.875rem;"><em>Local preview rendered from the OAS spec. Full interactive API reference (try-it-out, request/response schemas, auth) renders when imported into ReadMe.</em></p>`,
+  );
+  return parts.join('\n');
+}
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+}
+function findFirstHref(items) {
+  for (const item of items) {
+    if (item.href) return item.href;
+    if (item.children?.length) {
+      const found = findFirstHref(item.children);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+export function getFirstPageHref() {
+  const sidebar = collectSidebar();
+  return findFirstHref(sidebar);
+}

package/src/dev/middleware.js ADDED Viewed

@@ -0,0 +1,7 @@
+import { NextResponse } from 'next/server';
+export function middleware(request) {
+  const response = NextResponse.next();
+  response.headers.set('x-pathname', request.nextUrl.pathname);
+  return response;
+}

package/src/dev/next.config.mjs ADDED Viewed

@@ -0,0 +1,22 @@
+import path from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/** @type {import('next').NextConfig} */
+export default {
+  outputFileTracingRoot: __dirname,
+  // When installed via `npx`, this directory lives inside `node_modules`, and
+  // 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) => {
+    // Suppress noisy cache serialization warnings from large @readme/markdown bundle
+    config.infrastructureLogging = {
+      ...config.infrastructureLogging,
+      level: 'error',
+    };
+    return config;
+  },
+};

package/src/index.js ADDED Viewed

@@ -0,0 +1,12 @@
+/**
+ * Programmatic API for `@readme/cli`.
+ *
+ * Each function mirrors the behavior of its CLI command but returns
+ * structured data and never calls `process.exit`. Callers own how to format,
+ * report, and exit on errors.
+ */
+export { lint } from './commands/lint.js';
+export { syncOas } from './commands/oas-sync.js';
+export { validateOas } from './commands/oas-validate.js';
+export { importDocs } from './commands/import.js';