prev-cli 0.15.0 → 0.16.0

package/dist/cli.js

@@ -2,8 +2,8 @@
 
 // src/cli.ts
 import { parseArgs } from "util";
-import path8 from "path";
-import { existsSync as existsSync6, mkdirSync as mkdirSync2, writeFileSync as writeFileSync3, rmSync as rmSync3, readFileSync as readFileSync4 } from "fs";
+import path9 from "path";
+import { existsSync as existsSync7, mkdirSync as mkdirSync2, writeFileSync as writeFileSync4, rmSync as rmSync3, readFileSync as readFileSync5 } from "fs";
 import { fileURLToPath as fileURLToPath3 } from "url";
 
 // src/vite/start.ts
@@ -15,9 +15,9 @@ import react from "@vitejs/plugin-react-swc";
 import mdx from "@mdx-js/rollup";
 import remarkGfm from "remark-gfm";
 import rehypeHighlight from "rehype-highlight";
-import path6 from "path";
+import path7 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import { existsSync as existsSync4, readFileSync as readFileSync3 } from "fs";
+import { existsSync as existsSync5, readFileSync as readFileSync4 } from "fs";
 
 // src/utils/cache.ts
 import { createHash } from "crypto";
@@ -74,6 +74,7 @@ async function ensureCacheDir(rootDir) {
 import fg from "fast-glob";
 import { readFile } from "fs/promises";
 import path2 from "path";
+import picomatch from "picomatch";
 function parseValue(value) {
   const trimmed = value.trim();
   if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
@@ -187,6 +188,9 @@ async function scanPages(rootDir, options = {}) {
     if (Object.keys(frontmatter).length > 0) {
       page.frontmatter = frontmatter;
     }
+    if (frontmatter.hidden === true) {
+      page.hidden = true;
+    }
     pages.push(page);
   }
   return pages.sort((a, b) => a.route.localeCompare(b.route));
@@ -378,13 +382,19 @@ async function scanPreviews(rootDir) {
   if (!existsSync2(previewsDir)) {
     return [];
   }
-  const htmlFiles = await fg2.glob("**/index.html", {
+  const entryFiles = await fg2.glob("**/{index.html,App.tsx,App.jsx,index.tsx,index.jsx}", {
     cwd: previewsDir,
     ignore: ["node_modules/**"]
   });
-  return htmlFiles.map((file) => {
+  const previewDirs = new Map;
+  for (const file of entryFiles) {
     const dir = path4.dirname(file);
-    const name = dir === "." ? path4.basename(path4.dirname(path4.join(previewsDir, file))) : dir;
+    if (!previewDirs.has(dir)) {
+      previewDirs.set(dir, file);
+    }
+  }
+  return Array.from(previewDirs.entries()).map(([dir, file]) => {
+    const name = dir === "." ? path4.basename(previewsDir) : dir;
     return {
       name,
       route: `/_preview/${name}`,
@@ -612,6 +622,99 @@ function previewsPlugin(rootDir) {
   };
 }
 
+// src/vite/plugins/config-plugin.ts
+var VIRTUAL_CONFIG_ID = "virtual:prev-config";
+var RESOLVED_CONFIG_ID = "\x00" + VIRTUAL_CONFIG_ID;
+function createConfigPlugin(config) {
+  return {
+    name: "prev-config",
+    enforce: "pre",
+    resolveId(id) {
+      if (id === VIRTUAL_CONFIG_ID) {
+        return RESOLVED_CONFIG_ID;
+      }
+    },
+    load(id) {
+      if (id === RESOLVED_CONFIG_ID) {
+        return `export const config = ${JSON.stringify(config)};`;
+      }
+    }
+  };
+}
+
+// src/config/schema.ts
+var defaultConfig = {
+  theme: "system",
+  contentWidth: "constrained",
+  hidden: [],
+  order: {}
+};
+function validateConfig(raw) {
+  const config = { ...defaultConfig };
+  if (raw && typeof raw === "object") {
+    const obj = raw;
+    if (obj.theme === "light" || obj.theme === "dark" || obj.theme === "system") {
+      config.theme = obj.theme;
+    }
+    if (obj.contentWidth === "constrained" || obj.contentWidth === "full") {
+      config.contentWidth = obj.contentWidth;
+    }
+    if (Array.isArray(obj.hidden)) {
+      config.hidden = obj.hidden.filter((h) => typeof h === "string");
+    }
+    if (obj.order && typeof obj.order === "object") {
+      config.order = {};
+      for (const [key, value] of Object.entries(obj.order)) {
+        if (Array.isArray(value)) {
+          config.order[key] = value.filter((v) => typeof v === "string");
+        }
+      }
+    }
+  }
+  return config;
+}
+// src/config/loader.ts
+import { readFileSync as readFileSync3, existsSync as existsSync4, writeFileSync as writeFileSync3 } from "fs";
+import path6 from "path";
+import yaml from "js-yaml";
+function findConfigFile(rootDir) {
+  const yamlPath = path6.join(rootDir, ".prev.yaml");
+  const ymlPath = path6.join(rootDir, ".prev.yml");
+  if (existsSync4(yamlPath))
+    return yamlPath;
+  if (existsSync4(ymlPath))
+    return ymlPath;
+  return null;
+}
+function loadConfig(rootDir) {
+  const configPath = findConfigFile(rootDir);
+  if (!configPath) {
+    return defaultConfig;
+  }
+  try {
+    const content = readFileSync3(configPath, "utf-8");
+    const raw = yaml.load(content);
+    return validateConfig(raw);
+  } catch (error) {
+    console.warn(`Warning: Failed to parse ${configPath}:`, error);
+    return defaultConfig;
+  }
+}
+function saveConfig(rootDir, config) {
+  const configPath = findConfigFile(rootDir) || path6.join(rootDir, ".prev.yaml");
+  const content = yaml.dump(config, {
+    indent: 2,
+    lineWidth: -1,
+    quotingType: '"',
+    forceQuotes: false
+  });
+  writeFileSync3(configPath, content, "utf-8");
+}
+function updateOrder(rootDir, pathKey, order) {
+  const config = loadConfig(rootDir);
+  config.order[pathKey] = order;
+  saveConfig(rootDir, config);
+}
 // src/vite/config.ts
 function createFriendlyLogger() {
   const logger = createLogger("info", { allowClearScreen: false });
@@ -667,35 +770,35 @@ function createFriendlyLogger() {
   };
 }
 function findCliRoot2() {
-  let dir = path6.dirname(fileURLToPath2(import.meta.url));
+  let dir = path7.dirname(fileURLToPath2(import.meta.url));
   for (let i = 0;i < 10; i++) {
-    const pkgPath = path6.join(dir, "package.json");
-    if (existsSync4(pkgPath)) {
+    const pkgPath = path7.join(dir, "package.json");
+    if (existsSync5(pkgPath)) {
       try {
-        const pkg = JSON.parse(readFileSync3(pkgPath, "utf-8"));
+        const pkg = JSON.parse(readFileSync4(pkgPath, "utf-8"));
         if (pkg.name === "prev-cli") {
           return dir;
         }
       } catch {}
     }
-    const parent = path6.dirname(dir);
+    const parent = path7.dirname(dir);
     if (parent === dir)
       break;
     dir = parent;
   }
-  return path6.dirname(path6.dirname(fileURLToPath2(import.meta.url)));
+  return path7.dirname(path7.dirname(fileURLToPath2(import.meta.url)));
 }
 function findNodeModules(cliRoot2) {
-  const localNodeModules = path6.join(cliRoot2, "node_modules");
-  if (existsSync4(path6.join(localNodeModules, "react"))) {
+  const localNodeModules = path7.join(cliRoot2, "node_modules");
+  if (existsSync5(path7.join(localNodeModules, "react"))) {
     return localNodeModules;
   }
   let dir = cliRoot2;
   for (let i = 0;i < 10; i++) {
-    const parent = path6.dirname(dir);
+    const parent = path7.dirname(dir);
     if (parent === dir)
       break;
-    if (path6.basename(parent) === "node_modules" && existsSync4(path6.join(parent, "react"))) {
+    if (path7.basename(parent) === "node_modules" && existsSync5(path7.join(parent, "react"))) {
       return parent;
     }
     dir = parent;
@@ -704,10 +807,11 @@ function findNodeModules(cliRoot2) {
 }
 var cliRoot2 = findCliRoot2();
 var cliNodeModules = findNodeModules(cliRoot2);
-var srcRoot2 = path6.join(cliRoot2, "src");
+var srcRoot2 = path7.join(cliRoot2, "src");
 async function createViteConfig(options) {
   const { rootDir, mode, port, include } = options;
   const cacheDir = await ensureCacheDir(rootDir);
+  const config = loadConfig(rootDir);
   return {
     root: rootDir,
     mode,
@@ -720,16 +824,44 @@ async function createViteConfig(options) {
         rehypePlugins: [rehypeHighlight]
       }),
       react(),
+      createConfigPlugin(config),
       pagesPlugin(rootDir, { include }),
       entryPlugin(rootDir),
       previewsPlugin(rootDir),
+      {
+        name: "prev-config-api",
+        configureServer(server) {
+          server.middlewares.use("/__prev/config", async (req, res) => {
+            if (req.method === "POST") {
+              let body = "";
+              req.on("data", (chunk) => {
+                body += chunk;
+              });
+              req.on("end", () => {
+                try {
+                  const { path: pathKey, order } = JSON.parse(body);
+                  updateOrder(rootDir, pathKey, order);
+                  res.statusCode = 200;
+                  res.end(JSON.stringify({ success: true }));
+                } catch (e) {
+                  res.statusCode = 400;
+                  res.end(JSON.stringify({ error: String(e) }));
+                }
+              });
+              return;
+            }
+            res.statusCode = 405;
+            res.end();
+          });
+        }
+      },
       {
         name: "prev-preview-server",
         resolveId(id) {
           if (id.startsWith("/_preview/")) {
             const relativePath = id.slice("/_preview/".length);
-            const previewsDir = path6.join(rootDir, "previews");
-            const resolved = path6.resolve(previewsDir, relativePath);
+            const previewsDir = path7.join(rootDir, "previews");
+            const resolved = path7.resolve(previewsDir, relativePath);
             if (resolved.startsWith(previewsDir)) {
               return resolved;
             }
@@ -739,9 +871,9 @@ async function createViteConfig(options) {
           server.middlewares.use(async (req, res, next) => {
             const urlPath = req.url?.split("?")[0] || "";
             if (urlPath === "/_preview-runtime") {
-              const templatePath = path6.join(srcRoot2, "preview-runtime/template.html");
-              if (existsSync4(templatePath)) {
-                const html = readFileSync3(templatePath, "utf-8");
+              const templatePath = path7.join(srcRoot2, "preview-runtime/template.html");
+              if (existsSync5(templatePath)) {
+                const html = readFileSync4(templatePath, "utf-8");
                 res.setHeader("Content-Type", "text/html");
                 res.end(html);
                 return;
@@ -749,18 +881,18 @@ async function createViteConfig(options) {
             }
             if (urlPath.startsWith("/_preview-config/")) {
               const previewName = decodeURIComponent(urlPath.slice("/_preview-config/".length));
-              const previewsDir = path6.join(rootDir, "previews");
-              const previewDir = path6.resolve(previewsDir, previewName);
+              const previewsDir = path7.join(rootDir, "previews");
+              const previewDir = path7.resolve(previewsDir, previewName);
               if (!previewDir.startsWith(previewsDir)) {
                 res.statusCode = 403;
                 res.end("Forbidden");
                 return;
               }
-              if (existsSync4(previewDir)) {
+              if (existsSync5(previewDir)) {
                 try {
-                  const config = await buildPreviewConfig(previewDir);
+                  const config2 = await buildPreviewConfig(previewDir);
                   res.setHeader("Content-Type", "application/json");
-                  res.end(JSON.stringify(config));
+                  res.end(JSON.stringify(config2));
                   return;
                 } catch (err) {
                   console.error("Error building preview config:", err);
@@ -771,17 +903,17 @@ async function createViteConfig(options) {
               }
             }
             if (urlPath.startsWith("/_preview/")) {
-              const isHtmlRequest = !path6.extname(urlPath) || urlPath.endsWith("/");
+              const isHtmlRequest = !path7.extname(urlPath) || urlPath.endsWith("/");
               if (isHtmlRequest) {
                 const previewName = decodeURIComponent(urlPath.slice("/_preview/".length).replace(/\/$/, ""));
-                const previewsDir = path6.join(rootDir, "previews");
-                const htmlPath = path6.resolve(previewsDir, previewName, "index.html");
+                const previewsDir = path7.join(rootDir, "previews");
+                const htmlPath = path7.resolve(previewsDir, previewName, "index.html");
                 if (!htmlPath.startsWith(previewsDir)) {
                   return next();
                 }
-                if (existsSync4(htmlPath)) {
+                if (existsSync5(htmlPath)) {
                   try {
-                    let html = readFileSync3(htmlPath, "utf-8");
+                    let html = readFileSync4(htmlPath, "utf-8");
                     const previewBase = `/_preview/${previewName}/`;
                     html = html.replace(/(src|href)=["']\.\/([^"']+)["']/g, `$1="${previewBase}$2"`);
                     const transformed = await server.transformIndexHtml(req.url, html);
@@ -802,14 +934,14 @@ async function createViteConfig(options) {
     ],
     resolve: {
       alias: {
-        "@prev/ui": path6.join(srcRoot2, "ui"),
-        "@prev/theme": path6.join(srcRoot2, "theme"),
-        react: path6.join(cliNodeModules, "react"),
-        "react-dom": path6.join(cliNodeModules, "react-dom"),
-        "@tanstack/react-router": path6.join(cliNodeModules, "@tanstack/react-router"),
-        mermaid: path6.join(cliNodeModules, "mermaid"),
-        dayjs: path6.join(cliNodeModules, "dayjs"),
-        "@terrastruct/d2": path6.join(cliNodeModules, "@terrastruct/d2")
+        "@prev/ui": path7.join(srcRoot2, "ui"),
+        "@prev/theme": path7.join(srcRoot2, "theme"),
+        react: path7.join(cliNodeModules, "react"),
+        "react-dom": path7.join(cliNodeModules, "react-dom"),
+        "@tanstack/react-router": path7.join(cliNodeModules, "@tanstack/react-router"),
+        mermaid: path7.join(cliNodeModules, "mermaid"),
+        dayjs: path7.join(cliNodeModules, "dayjs"),
+        "@terrastruct/d2": path7.join(cliNodeModules, "@terrastruct/d2")
       },
       dedupe: [
         "react",
@@ -842,8 +974,8 @@ async function createViteConfig(options) {
       },
       warmup: {
         clientFiles: [
-          path6.join(srcRoot2, "theme/entry.tsx"),
-          path6.join(srcRoot2, "theme/styles.css")
+          path7.join(srcRoot2, "theme/entry.tsx"),
+          path7.join(srcRoot2, "theme/styles.css")
         ]
       }
     },
@@ -852,12 +984,12 @@ async function createViteConfig(options) {
       strictPort: false
     },
     build: {
-      outDir: path6.join(rootDir, "dist"),
+      outDir: path7.join(rootDir, "dist"),
       reportCompressedSize: false,
       chunkSizeWarningLimit: 1e4,
       rollupOptions: {
         input: {
-          main: path6.join(srcRoot2, "theme/index.html")
+          main: path7.join(srcRoot2, "theme/index.html")
         }
       }
     }
@@ -897,8 +1029,8 @@ async function findAvailablePort(minPort, maxPort) {
 
 // src/vite/start.ts
 import { exec as exec2 } from "child_process";
-import { existsSync as existsSync5, rmSync as rmSync2 } from "fs";
-import path7 from "path";
+import { existsSync as existsSync6, rmSync as rmSync2 } from "fs";
+import path8 from "path";
 function printWelcome(type) {
   console.log();
   console.log("  ✨ prev");
@@ -931,14 +1063,14 @@ function openBrowser(url) {
   console.log(`  ↗ Opened ${url}`);
 }
 function clearCache(rootDir) {
-  const viteCacheDir = path7.join(rootDir, ".vite");
-  const nodeModulesVite = path7.join(rootDir, "node_modules", ".vite");
+  const viteCacheDir = path8.join(rootDir, ".vite");
+  const nodeModulesVite = path8.join(rootDir, "node_modules", ".vite");
   let cleared = 0;
-  if (existsSync5(viteCacheDir)) {
+  if (existsSync6(viteCacheDir)) {
     rmSync2(viteCacheDir, { recursive: true });
     cleared++;
   }
-  if (existsSync5(nodeModulesVite)) {
+  if (existsSync6(nodeModulesVite)) {
     rmSync2(nodeModulesVite, { recursive: true });
     cleared++;
   }
@@ -1031,15 +1163,15 @@ async function previewSite(rootDir, options = {}) {
 // src/cli.ts
 function getVersion() {
   try {
-    let dir = path8.dirname(fileURLToPath3(import.meta.url));
+    let dir = path9.dirname(fileURLToPath3(import.meta.url));
     for (let i = 0;i < 5; i++) {
-      const pkgPath = path8.join(dir, "package.json");
-      if (existsSync6(pkgPath)) {
-        const pkg = JSON.parse(readFileSync4(pkgPath, "utf-8"));
+      const pkgPath = path9.join(dir, "package.json");
+      if (existsSync7(pkgPath)) {
+        const pkg = JSON.parse(readFileSync5(pkgPath, "utf-8"));
         if (pkg.name === "prev-cli")
           return pkg.version;
       }
-      dir = path8.dirname(dir);
+      dir = path9.dirname(dir);
     }
   } catch {}
   return "unknown";
@@ -1057,7 +1189,7 @@ var { values, positionals } = parseArgs({
   allowPositionals: true
 });
 var command = positionals[0] || "dev";
-var rootDir = path8.resolve(values.cwd || positionals[1] || ".");
+var rootDir = path9.resolve(values.cwd || positionals[1] || ".");
 function printHelp() {
   console.log(`
 prev - Zero-config documentation site generator
@@ -1078,6 +1210,33 @@ Options:
   -h, --help             Show this help message
   -v, --version          Show version number
 
+Floating Toolbar:
+  A draggable pill at the bottom of the screen with:
+    - TOC button: Opens navigation panel (dropdown on desktop, overlay on mobile)
+    - Previews button: Links to /previews catalog (if previews exist)
+    - Width toggle: Switch between constrained and full-width content
+    - Theme toggle: Switch between light and dark mode
+
+Configuration (.prev.yaml):
+  Create a .prev.yaml file in your docs root to customize behavior:
+
+    theme: system          # light | dark | system (default: system)
+    contentWidth: constrained  # constrained | full (default: constrained)
+    hidden:                # Glob patterns for pages to hide
+      - "internal/**"
+      - "wip-*.md"
+    order:                 # Custom page ordering
+      "/":
+        - "getting-started.md"
+        - "guides/"
+
+  Pages can also be hidden via frontmatter:
+    ---
+    hidden: true
+    ---
+
+  Drag pages in the TOC panel to reorder - changes auto-save to config.
+
 Previews:
   Previews must be in the previews/ directory at your project root.
   Each preview is a subfolder with React components:
@@ -1121,15 +1280,15 @@ Examples:
 `);
 }
 function clearViteCache(rootDir2) {
-  const viteCacheDir = path8.join(rootDir2, ".vite");
-  const nodeModulesVite = path8.join(rootDir2, "node_modules", ".vite");
+  const viteCacheDir = path9.join(rootDir2, ".vite");
+  const nodeModulesVite = path9.join(rootDir2, "node_modules", ".vite");
   let cleared = 0;
-  if (existsSync6(viteCacheDir)) {
+  if (existsSync7(viteCacheDir)) {
     rmSync3(viteCacheDir, { recursive: true });
     cleared++;
     console.log(`  ✓ Removed .vite/`);
   }
-  if (existsSync6(nodeModulesVite)) {
+  if (existsSync7(nodeModulesVite)) {
     rmSync3(nodeModulesVite, { recursive: true });
     cleared++;
     console.log(`  ✓ Removed node_modules/.vite/`);
@@ -1142,8 +1301,8 @@ function clearViteCache(rootDir2) {
   }
 }
 function createPreview(rootDir2, name) {
-  const previewDir = path8.join(rootDir2, "previews", name);
-  if (existsSync6(previewDir)) {
+  const previewDir = path9.join(rootDir2, "previews", name);
+  if (existsSync7(previewDir)) {
     console.error(`Preview "${name}" already exists at: ${previewDir}`);
     process.exit(1);
   }
@@ -1268,8 +1427,8 @@ export default function App() {
   .dark\\:text-white { color: #fff; }
 }
 `;
-  writeFileSync3(path8.join(previewDir, "App.tsx"), appTsx);
-  writeFileSync3(path8.join(previewDir, "styles.css"), stylesCss);
+  writeFileSync4(path9.join(previewDir, "App.tsx"), appTsx);
+  writeFileSync4(path9.join(previewDir, "styles.css"), stylesCss);
   console.log(`
   ✨ Created preview: previews/${name}/
 

package/dist/config/index.d.ts

@@ -0,0 +1,2 @@
+export { type PrevConfig, defaultConfig, validateConfig } from './schema';
+export { loadConfig, saveConfig, updateOrder, findConfigFile } from './loader';

package/dist/config/loader.d.ts

@@ -0,0 +1,5 @@
+import type { PrevConfig } from './schema';
+export declare function findConfigFile(rootDir: string): string | null;
+export declare function loadConfig(rootDir: string): PrevConfig;
+export declare function saveConfig(rootDir: string, config: PrevConfig): void;
+export declare function updateOrder(rootDir: string, pathKey: string, order: string[]): void;

package/dist/config/schema.d.ts

@@ -0,0 +1,8 @@
+export interface PrevConfig {
+    theme: 'light' | 'dark' | 'system';
+    contentWidth: 'constrained' | 'full';
+    hidden: string[];
+    order: Record<string, string[]>;
+}
+export declare const defaultConfig: PrevConfig;
+export declare function validateConfig(raw: unknown): PrevConfig;

package/dist/vite/pages.d.ts

@@ -9,6 +9,7 @@ export interface Page {
     file: string;
     description?: string;
     frontmatter?: Frontmatter;
+    hidden?: boolean;
 }
 export interface SidebarItem {
     title: string;
@@ -25,6 +26,8 @@ export declare function parseFrontmatter(content: string): {
 export declare function fileToRoute(file: string): string;
 export interface ScanOptions {
     include?: string[];
+    hidden?: string[];
 }
 export declare function scanPages(rootDir: string, options?: ScanOptions): Promise<Page[]>;
+export declare function filterVisiblePages(pages: Page[], hiddenPatterns: string[]): Page[];
 export declare function buildSidebarTree(pages: Page[]): SidebarItem[];

package/dist/vite/plugins/config-plugin.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from 'vite';
+import type { PrevConfig } from '../../config';
+export declare function createConfigPlugin(config: PrevConfig): Plugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prev-cli",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Transform MDX directories into beautiful documentation websites",
   "type": "module",
   "license": "MIT",
@@ -42,6 +42,7 @@
   "dependencies": {
     "@mdx-js/react": "^3.1.1",
     "@mdx-js/rollup": "^3.0.0",
+    "@tabler/icons-react": "^3.36.1",
     "@tailwindcss/vite": "^4.0.0",
     "@tanstack/react-router": "^1.145.7",
     "@terrastruct/d2": "^0.1.33",
@@ -51,8 +52,10 @@
     "fast-glob": "^3.3.0",
     "fumadocs-core": "^16.4.3",
     "fumadocs-ui": "^16.4.3",
+    "js-yaml": "^4.1.1",
     "lucide-react": "^0.460.0",
     "mermaid": "^11.0.0",
+    "picomatch": "^4.0.3",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-router-dom": "^7.0.0",
@@ -63,7 +66,9 @@
     "tailwindcss": "^4.0.0"
   },
   "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
+    "@types/picomatch": "^4.0.2",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "bun-types": "^1.3.5",