@reapi/docs 0.1.0

package/bin.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { run } from './src/cli.js';
+
+run(process.argv.slice(2)).catch((err) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@reapi/docs",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "ReAPI docs CLI — local WYSIWYG preview and sync for portal docs",
+  "bin": {
+    "reapi-docs": "./bin.js"
+  },
+  "dependencies": {
+    "@tailwindcss/typography": "^0.5.20",
+    "@tailwindcss/vite": "^4.0.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "chokidar": "^4.0.3",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "tailwindcss": "^4.0.0",
+    "vite": "^6.0.0",
+    "@reapi/docs-ui": "0.1.0",
+    "@reapi/spec-ui": "0.1.0",
+    "@reapi/docs-compile": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/mdast": "^4.0.4",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.7.3"
+  },
+  "files": [
+    "bin.js",
+    "src",
+    "preview",
+    "!preview/sources.gen.css"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
+}

package/preview/app.tsx

@@ -0,0 +1,145 @@
+import { useCallback, useEffect, useState } from 'react';
+import { ApiOperation, DocsEmbedProvider, MdxContent } from '@reapi/docs-ui';
+import type { Root } from 'mdast';
+
+interface SitePayload {
+  config: { name: string; description?: string; nav: { group: string; pages: string[] }[] } | null;
+  handle: string | null;
+  pages: { path: string; title?: string }[];
+  errors: { path: string; message: string; line?: number }[];
+}
+
+interface PagePayload {
+  frontmatter: Record<string, unknown>;
+  ast: Root;
+  embeds: string[];
+  openapiRef: { api: string; method: string; path: string } | null;
+  file: string;
+}
+
+const fetchJson = async <T,>(url: string): Promise<T | null> => {
+  const res = await fetch(url);
+  return res.ok ? ((await res.json()) as T) : null;
+};
+
+function usePath(): [string, (p: string) => void] {
+  const [path, setPath] = useState(window.location.hash.slice(2) || 'index');
+  useEffect(() => {
+    const onHash = () => setPath(window.location.hash.slice(2) || 'index');
+    window.addEventListener('hashchange', onHash);
+    return () => window.removeEventListener('hashchange', onHash);
+  }, []);
+  return [path, (p) => (window.location.hash = `/${p}`)];
+}
+
+export function App() {
+  const [site, setSite] = useState<SitePayload | null>(null);
+  const [page, setPage] = useState<PagePayload | null>(null);
+  const [specs, setSpecs] = useState<Record<string, Record<string, unknown>>>({});
+  const [path] = usePath();
+
+  const load = useCallback(async () => {
+    const s = await fetchJson<SitePayload>('/__docs/site');
+    setSite(s);
+    const p = await fetchJson<PagePayload>(`/__docs/page?path=${encodeURIComponent(path)}`);
+    setPage(p);
+    if (p?.embeds.length) {
+      const entries = await Promise.all(
+        p.embeds.map(async (api) => {
+          const pub = await fetchJson<{ spec: Record<string, unknown> }>(
+            `/__docs/spec?api=${encodeURIComponent(api)}`,
+          );
+          return pub ? ([api, pub.spec] as const) : null;
+        }),
+      );
+      setSpecs(Object.fromEntries(entries.filter((e): e is [string, Record<string, unknown>] => !!e)));
+    } else {
+      setSpecs({});
+    }
+  }, [path]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  // live reload on recompile (vite ws custom event from the dev plugin)
+  useEffect(() => {
+    if (!import.meta.hot) return;
+    const handler = () => void load();
+    import.meta.hot.on('docs:update', handler);
+    return () => import.meta.hot?.off('docs:update', handler);
+  }, [load]);
+
+  if (!site) return <p className="p-10 text-sm text-muted-foreground">Loading…</p>;
+
+  const fm = (page?.frontmatter ?? {}) as { title?: string; description?: string };
+  const pageRef = page?.openapiRef ?? null;
+  const titleOf = (p: string) => site.pages.find((x) => x.path === p)?.title ?? p.split('/').pop();
+
+  return (
+    <div className="mx-auto flex max-w-6xl gap-10 px-6">
+      <aside className="sticky top-0 hidden h-screen w-60 shrink-0 overflow-y-auto py-10 md:block">
+        <p className="text-sm font-semibold">{site.config?.name ?? 'Docs preview'}</p>
+        <p className="mt-0.5 text-[11px] text-muted-foreground">local preview</p>
+        <nav className="mt-6 space-y-5">
+          {(site.config?.nav ?? []).map((group) => (
+            <div key={group.group}>
+              <p className="mb-1 px-2 text-[11px] font-semibold uppercase tracking-wider text-muted-foreground">
+                {group.group}
+              </p>
+              <ul>
+                {group.pages.map((p) => (
+                  <li key={p}>
+                    <a
+                      href={`#/${p}`}
+                      className={`block truncate rounded px-2 py-1 text-[13px] ${
+                        p === path
+                          ? 'bg-accent font-medium'
+                          : 'text-muted-foreground hover:bg-accent hover:text-foreground'
+                      }`}
+                    >
+                      {titleOf(p)}
+                    </a>
+                  </li>
+                ))}
+              </ul>
+            </div>
+          ))}
+        </nav>
+      </aside>
+
+      <main className="min-w-0 flex-1 py-10">
+        {site.errors.length > 0 && (
+          <div className="mb-6 rounded-md border border-red-200 bg-red-50 px-4 py-3 text-xs text-red-700">
+            <p className="font-semibold">{site.errors.length} compile problem(s)</p>
+            <ul className="mt-1 list-inside list-disc font-mono">
+              {site.errors.map((e, i) => (
+                <li key={i}>
+                  {e.path}
+                  {e.line ? `:${e.line}` : ''} — {e.message}
+                </li>
+              ))}
+            </ul>
+          </div>
+        )}
+        {!page ? (
+          <p className="text-sm text-muted-foreground">
+            No page at <code className="font-mono">{path}</code>. Create{' '}
+            <code className="font-mono">{path}.mdx</code> or pick one from the sidebar.
+          </p>
+        ) : (
+          <DocsEmbedProvider specs={specs}>
+            <article className="prose prose-sm max-w-3xl prose-headings:scroll-mt-20 prose-pre:rounded-md prose-pre:bg-muted prose-pre:p-3 prose-pre:text-foreground prose-code:rounded prose-code:bg-muted prose-code:px-1 prose-code:py-px prose-code:font-mono prose-code:before:content-none prose-code:after:content-none">
+              {fm.title && <h1>{fm.title}</h1>}
+              {fm.description && <p className="lead text-muted-foreground">{fm.description}</p>}
+              <MdxContent ast={page.ast} />
+              {pageRef && (
+                <ApiOperation api={pageRef.api} operation={`${pageRef.method} ${pageRef.path}`} />
+              )}
+            </article>
+          </DocsEmbedProvider>
+        )}
+      </main>
+    </div>
+  );
+}

package/preview/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>ReAPI docs preview</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/main.tsx"></script>
+  </body>
+</html>

package/preview/main.tsx

@@ -0,0 +1,5 @@
+import { createRoot } from 'react-dom/client';
+import { App } from './app';
+import './styles.css';
+
+createRoot(document.getElementById('root')!).render(<App />);

package/preview/styles.css

@@ -0,0 +1,56 @@
+@import 'tailwindcss';
+/* @source paths for the shared render packages are generated at startup
+   (dev.js) — their install location differs between the workspace (TS
+   source) and an npm install (dist). */
+@import './sources.gen.css';
+@plugin '@tailwindcss/typography';
+
+/* same tokens as the portal so the preview is faithful */
+:root {
+  --radius: 0.625rem;
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+}
+
+@theme inline {
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --font-sans: ui-sans-serif, system-ui, sans-serif;
+  --font-mono: ui-monospace, SFMono-Regular, monospace;
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground font-sans;
+  }
+}

package/src/check.js

@@ -0,0 +1,12 @@
+import { compileDir, printErrors } from './compile-dir.js';
+
+export async function checkCommand({ dir }) {
+  const { pages, errors } = await compileDir(dir);
+  console.log(`Compiled ${pages.size} page(s) from ${dir}`);
+  if (errors.length) {
+    printErrors(errors);
+    console.error(`\n${errors.length} problem(s).`);
+    process.exit(1);
+  }
+  console.log('✓ No problems — ready to push.');
+}

package/src/cli.js

@@ -0,0 +1,49 @@
+import { devCommand } from './dev.js';
+import { checkCommand } from './check.js';
+import { pushCommand } from './push.js';
+
+const HELP = `reapi-docs — ReAPI portal docs toolkit
+
+Usage:
+  reapi-docs dev    [--dir .] [--port 4747] [--api-origin URL]   local preview (WYSIWYG)
+  reapi-docs check  [--dir .]                                    compile, print errors
+  reapi-docs push   [--dir .] [--api-origin URL]                 sync to your portal
+                    (auth: REAPI_SESSION env = better-auth session token)
+
+The docs dir holds docs.json + *.mdx pages (see docs/portal.md).
+`;
+
+export function parseFlags(argv) {
+  const flags = {};
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      flags[a.slice(2)] = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : 'true';
+    } else {
+      rest.push(a);
+    }
+  }
+  return { flags, rest };
+}
+
+export async function run(argv) {
+  const [command, ...args] = argv;
+  const { flags } = parseFlags(args);
+  const options = {
+    dir: flags.dir ?? process.cwd(),
+    port: Number(flags.port ?? 4747),
+    apiOrigin: flags['api-origin'] ?? process.env.REAPI_API_ORIGIN ?? 'https://api.reapi.test',
+  };
+  switch (command) {
+    case 'dev':
+      return devCommand(options);
+    case 'check':
+      return checkCommand(options);
+    case 'push':
+      return pushCommand(options);
+    default:
+      console.log(HELP);
+      if (command && command !== 'help') process.exit(1);
+  }
+}

package/src/compile-dir.js

@@ -0,0 +1,73 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { compileMdx, normalizePagePath, parseDocsConfig, parseOpenapiRef } from '@reapi/docs-compile';
+
+const IGNORED = new Set(['node_modules', '.git', '.next', 'dist']);
+
+/** All .mdx/.md files under dir (relative paths, posix separators). */
+export async function listPageFiles(dir, prefix = '') {
+  const out = [];
+  for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith('.') || IGNORED.has(entry.name)) continue;
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      out.push(...(await listPageFiles(path.join(dir, entry.name), rel)));
+    } else if (/\.(mdx?|markdown)$/i.test(entry.name)) {
+      // repo README is for GitHub, not the site
+      if (!prefix && /^readme\.(mdx?|markdown)$/i.test(entry.name)) continue;
+      out.push(rel);
+    }
+  }
+  return out;
+}
+
+/**
+ * Compile the whole docs dir exactly like the server sync does — same
+ * compiler package, so what previews locally is what publishes.
+ * Returns { config, rawConfig, pages: Map<path, CompiledPage>, files, errors }.
+ */
+export async function compileDir(dir) {
+  const errors = [];
+  let config = null;
+  let rawConfig = null;
+
+  try {
+    const text = await fs.readFile(path.join(dir, 'docs.json'), 'utf8');
+    rawConfig = JSON.parse(text);
+    const parsed = parseDocsConfig(text);
+    config = parsed.config;
+    for (const e of parsed.errors) errors.push({ path: 'docs.json', ...e });
+  } catch (err) {
+    errors.push({ path: 'docs.json', message: `cannot read docs.json: ${err.message}` });
+  }
+
+  const files = await listPageFiles(dir);
+  const pages = new Map();
+  for (const file of files) {
+    const source = await fs.readFile(path.join(dir, file), 'utf8');
+    const compiled = compileMdx(source);
+    const slug = normalizePagePath(file);
+    // pre-parse the full-page embed ref — the browser preview must not load
+    // the node-targeted compile bundle
+    const openapiRef = parseOpenapiRef(compiled.frontmatter?.openapi);
+    pages.set(slug, { ...compiled, openapiRef, file });
+    for (const e of compiled.errors) errors.push({ path: file, ...e });
+  }
+
+  if (config) {
+    for (const group of config.nav) {
+      for (const p of group.pages) {
+        if (!pages.has(p)) errors.push({ path: 'docs.json', message: `nav page "${p}" has no matching file` });
+      }
+    }
+  }
+
+  return { config, rawConfig, pages, files, errors };
+}
+
+export function printErrors(errors) {
+  for (const e of errors) {
+    const pos = e.line ? `:${e.line}${e.column ? `:${e.column}` : ''}` : '';
+    console.error(`  ✗ ${e.path}${pos}  ${e.message}`);
+  }
+}

package/src/dev.js

@@ -0,0 +1,112 @@
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { watch } from 'chokidar';
+import { createServer } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+import { compileDir } from './compile-dir.js';
+
+const previewRoot = fileURLToPath(new URL('../preview', import.meta.url));
+
+/**
+ * Tailwind must scan the shared render packages for class names. Their
+ * location depends on how this CLI is installed (workspace TS source vs npm
+ * dist — compiled JS keeps the class strings), so resolve at runtime and
+ * generate the @source file the preview CSS imports.
+ */
+async function writeTailwindSources() {
+  const require = createRequire(import.meta.url);
+  const dirs = ['@reapi/docs-ui', '@reapi/spec-ui'].map((name) =>
+    path.dirname(require.resolve(name)),
+  );
+  const css = dirs.map((dir) => `@source '${dir.replace(/\\/g, '/')}';`).join('\n') + '\n';
+  await fs.writeFile(path.join(previewRoot, 'sources.gen.css'), css);
+}
+
+/**
+ * Local WYSIWYG preview (portal.md §6): the watcher recompiles through the
+ * SAME @reapi/docs-compile the server uses, and the preview app renders with
+ * the SAME @reapi/docs-ui the portal uses — parity is by construction, not
+ * approximation. Embed data comes from the public /pub endpoints (published
+ * APIs render live; unpublished show placeholders).
+ */
+export async function devCommand({ dir, port, apiOrigin }) {
+  await writeTailwindSources();
+  let state = await compileDir(dir);
+  const handle = typeof state.rawConfig?.handle === 'string' ? state.rawConfig.handle : null;
+
+  const docsPlugin = {
+    name: 'reapi-docs-data',
+    configureServer(server) {
+      const json = (res, status, data) => {
+        res.statusCode = status;
+        res.setHeader('Content-Type', 'application/json');
+        res.end(JSON.stringify(data));
+      };
+      server.middlewares.use(async (req, res, next) => {
+        const url = new URL(req.url, 'http://x');
+        if (url.pathname === '/__docs/site') {
+          return json(res, 200, {
+            config: state.config,
+            handle,
+            pages: [...state.pages.entries()].map(([slug, page]) => ({
+              path: slug,
+              title: page.frontmatter?.title,
+            })),
+            errors: state.errors,
+          });
+        }
+        if (url.pathname === '/__docs/page') {
+          const page = state.pages.get(url.searchParams.get('path') ?? '');
+          return page ? json(res, 200, page) : json(res, 404, { error: 'not found' });
+        }
+        if (url.pathname === '/__docs/spec') {
+          // proxy published specs for embeds (avoids CORS + local TLS trust)
+          const api = url.searchParams.get('api');
+          if (!handle || !api) return json(res, 404, { error: 'no handle/api' });
+          try {
+            const r = await fetch(`${apiOrigin}/pub/${handle}/${api}`);
+            if (!r.ok) return json(res, r.status, { error: 'not published' });
+            return json(res, 200, await r.json());
+          } catch (err) {
+            return json(res, 502, { error: String(err) });
+          }
+        }
+        next();
+      });
+    },
+  };
+
+  const server = await createServer({
+    root: previewRoot,
+    configFile: false,
+    plugins: [react(), tailwindcss(), docsPlugin],
+    resolve: { dedupe: ['react', 'react-dom'] },
+    server: { port },
+    // the preview app lives inside this package; user content is data, not code
+    optimizeDeps: { include: ['react', 'react-dom/client'] },
+  });
+
+  const recompile = async (reason) => {
+    state = await compileDir(dir);
+    server.ws.send({ type: 'custom', event: 'docs:update', data: { reason } });
+    const status = state.errors.length ? `${state.errors.length} problem(s)` : 'ok';
+    console.log(`↻ recompiled (${reason}) — ${state.pages.size} pages, ${status}`);
+  };
+
+  watch(dir, {
+    ignored: (p) => /node_modules|\.git/.test(p),
+    ignoreInitial: true,
+  }).on('all', (event, file) => {
+    if (/\.(mdx?|markdown)$|docs\.json$/i.test(file)) void recompile(path.basename(file));
+  });
+
+  await server.listen();
+  console.log(`\n  ReAPI docs preview → http://localhost:${port}`);
+  console.log(`  Watching ${dir}\n`);
+  if (state.errors.length) {
+    console.log(`  ⚠ ${state.errors.length} compile problem(s) — shown in the preview.\n`);
+  }
+}

package/src/push.js

@@ -0,0 +1,48 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { compileDir, listPageFiles, printErrors } from './compile-dir.js';
+
+/**
+ * Sync the docs dir to the server (same endpoint the GitHub webhook uses).
+ * The server re-compiles with the identical package — the local check is a
+ * convenience, the server gate is the authority.
+ */
+export async function pushCommand({ dir, apiOrigin }) {
+  const session = process.env.REAPI_SESSION;
+  if (!session) {
+    throw new Error('Set REAPI_SESSION to your session token (better-auth session cookie value).');
+  }
+
+  // fail fast locally with the same compiler
+  const { errors } = await compileDir(dir);
+  if (errors.length) {
+    printErrors(errors);
+    throw new Error(`${errors.length} problem(s) — fix them before pushing.`);
+  }
+
+  const config = await fs.readFile(path.join(dir, 'docs.json'), 'utf8');
+  const files = await listPageFiles(dir);
+  const pages = await Promise.all(
+    files.map(async (file) => ({
+      path: file,
+      content: await fs.readFile(path.join(dir, file), 'utf8'),
+    })),
+  );
+
+  const res = await fetch(`${apiOrigin}/docs-site`, {
+    method: 'PUT',
+    headers: {
+      'Content-Type': 'application/json',
+      Cookie: `__Secure-better-auth.session_token=${session}`,
+    },
+    body: JSON.stringify({ config, pages }),
+  });
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    for (const f of body.files ?? []) {
+      printErrors(f.errors.map((e) => ({ path: f.path, ...e })));
+    }
+    throw new Error(body.message ?? `push failed: ${res.status}`);
+  }
+  console.log(`✓ Synced ${body.pages} page(s) → ${body.url}`);
+}