prev-cli 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 lagz0ne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,502 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { parseArgs } from "util";
+
+// src/vite/start.ts
+import { createServer as createServer2, build, preview } from "vite";
+
+// src/vite/config.ts
+import react from "@vitejs/plugin-react-swc";
+import tailwindcss from "@tailwindcss/vite";
+import mdx from "@mdx-js/rollup";
+import remarkGfm from "remark-gfm";
+import rehypeHighlight from "rehype-highlight";
+import rehypeMermaid from "rehype-mermaid";
+import path4 from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+
+// src/utils/cache.ts
+import { createHash } from "crypto";
+import { readdir, rm, stat, mkdir } from "fs/promises";
+import { exec } from "child_process";
+import { promisify } from "util";
+import path from "path";
+import os from "os";
+var execAsync = promisify(exec);
+var DEFAULT_CACHE_ROOT = path.join(os.homedir(), ".cache/prev");
+async function getCacheDir(rootDir, branch) {
+  const resolvedBranch = branch ?? await getCurrentBranch(rootDir);
+  const hash = createHash("sha1").update(`${rootDir}:${resolvedBranch}`).digest("hex").slice(0, 12);
+  return path.join(DEFAULT_CACHE_ROOT, hash);
+}
+async function getCurrentBranch(rootDir) {
+  try {
+    const { stdout } = await execAsync("git branch --show-current", { cwd: rootDir });
+    return stdout.trim() || "detached";
+  } catch {
+    return "no-git";
+  }
+}
+async function cleanCache(options) {
+  const cacheRoot = options.cacheRoot ?? DEFAULT_CACHE_ROOT;
+  const maxAge = options.maxAgeDays * 24 * 60 * 60 * 1000;
+  const now = Date.now();
+  let dirs;
+  try {
+    dirs = await readdir(cacheRoot);
+  } catch {
+    return 0;
+  }
+  let removed = 0;
+  for (const dir of dirs) {
+    const fullPath = path.join(cacheRoot, dir);
+    try {
+      const info = await stat(fullPath);
+      if (info.isDirectory() && now - info.mtimeMs > maxAge) {
+        await rm(fullPath, { recursive: true });
+        removed++;
+      }
+    } catch {}
+  }
+  return removed;
+}
+async function ensureCacheDir(rootDir) {
+  const cacheDir = await getCacheDir(rootDir);
+  await mkdir(cacheDir, { recursive: true });
+  return cacheDir;
+}
+
+// src/vite/pages.ts
+import fg from "fast-glob";
+import { readFile } from "fs/promises";
+import path2 from "path";
+function fileToRoute(file) {
+  const withoutExt = file.replace(/\.mdx?$/, "");
+  if (withoutExt === "index") {
+    return "/";
+  }
+  if (withoutExt.endsWith("/index")) {
+    return "/" + withoutExt.slice(0, -6);
+  }
+  return "/" + withoutExt;
+}
+async function scanPages(rootDir) {
+  const files = await fg.glob("**/*.mdx", {
+    cwd: rootDir,
+    ignore: ["node_modules/**", "dist/**", ".cache/**"]
+  });
+  const pages = [];
+  for (const file of files) {
+    const fullPath = path2.join(rootDir, file);
+    const content = await readFile(fullPath, "utf-8");
+    const title = extractTitle(content, file);
+    pages.push({
+      route: fileToRoute(file),
+      title,
+      file
+    });
+  }
+  return pages.sort((a, b) => a.route.localeCompare(b.route));
+}
+function extractTitle(content, file) {
+  const match = content.match(/^#\s+(.+)$/m);
+  if (match) {
+    return match[1].trim();
+  }
+  const basename = path2.basename(file, path2.extname(file));
+  if (basename === "index") {
+    const dirname = path2.dirname(file);
+    return dirname === "." ? "Home" : capitalize(path2.basename(dirname));
+  }
+  return capitalize(basename);
+}
+function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1).replace(/-/g, " ");
+}
+function buildSidebarTree(pages) {
+  const tree = [];
+  const map = new Map;
+  for (const page of pages) {
+    const segments = page.route.split("/").filter(Boolean);
+    if (segments.length === 0) {
+      tree.push({ title: page.title, route: page.route });
+    } else if (segments.length === 1) {
+      const item = { title: page.title, route: page.route };
+      map.set(segments[0], item);
+      tree.push(item);
+    } else {
+      const parentKey = segments[0];
+      let parent = map.get(parentKey);
+      if (!parent) {
+        parent = { title: capitalize(parentKey), children: [] };
+        map.set(parentKey, parent);
+        tree.push(parent);
+      }
+      if (!parent.children) {
+        parent.children = [];
+      }
+      parent.children.push({ title: page.title, route: page.route });
+    }
+  }
+  return tree;
+}
+
+// src/vite/plugins/pages-plugin.ts
+var VIRTUAL_MODULE_ID = "virtual:prev-pages";
+var RESOLVED_VIRTUAL_MODULE_ID = "\x00" + VIRTUAL_MODULE_ID;
+function pagesPlugin(rootDir) {
+  return {
+    name: "prev-pages",
+    resolveId(id) {
+      if (id === VIRTUAL_MODULE_ID) {
+        return RESOLVED_VIRTUAL_MODULE_ID;
+      }
+    },
+    async load(id) {
+      if (id === RESOLVED_VIRTUAL_MODULE_ID) {
+        const pages = await scanPages(rootDir);
+        const sidebar = buildSidebarTree(pages);
+        return `
+          export const pages = ${JSON.stringify(pages)};
+          export const sidebar = ${JSON.stringify(sidebar)};
+        `;
+      }
+    },
+    handleHotUpdate({ file, server }) {
+      if (file.endsWith(".mdx")) {
+        const mod = server.moduleGraph.getModuleById(RESOLVED_VIRTUAL_MODULE_ID);
+        if (mod) {
+          server.moduleGraph.invalidateModule(mod);
+          return [mod];
+        }
+      }
+    }
+  };
+}
+
+// src/vite/plugins/entry-plugin.ts
+import path3 from "path";
+import { fileURLToPath } from "url";
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from "fs";
+function findCliRoot() {
+  let dir = path3.dirname(fileURLToPath(import.meta.url));
+  for (let i = 0;i < 10; i++) {
+    const pkgPath = path3.join(dir, "package.json");
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        if (pkg.name === "prev-cli") {
+          return dir;
+        }
+      } catch {}
+    }
+    const parent = path3.dirname(dir);
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  return path3.dirname(path3.dirname(fileURLToPath(import.meta.url)));
+}
+var cliRoot = findCliRoot();
+var srcRoot = path3.join(cliRoot, "src");
+function getHtml(entryPath, forBuild = false) {
+  const scriptSrc = forBuild ? entryPath : `/@fs${entryPath}`;
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Documentation</title>
+  <!-- Preconnect to Google Fonts for faster loading -->
+  <link rel="preconnect" href="https://fonts.googleapis.com" />
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+  <!-- Preload critical fonts -->
+  <link rel="preload" href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,400;0,9..40,500;0,9..40,600;0,9..40,700&family=IBM+Plex+Mono:wght@400;500&display=swap" as="style" />
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,400;0,9..40,500;0,9..40,600;0,9..40,700&family=IBM+Plex+Mono:wght@400;500&display=swap" />
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="${scriptSrc}"></script>
+</body>
+</html>`;
+}
+function entryPlugin(rootDir) {
+  const entryPath = path3.join(srcRoot, "theme/entry.tsx");
+  let tempHtmlPath = null;
+  return {
+    name: "prev-entry",
+    config(config, { command }) {
+      if (command === "build" && rootDir) {
+        tempHtmlPath = path3.join(rootDir, "index.html");
+        writeFileSync(tempHtmlPath, getHtml(entryPath, true));
+        return {
+          build: {
+            rollupOptions: {
+              input: tempHtmlPath
+            }
+          }
+        };
+      }
+    },
+    buildEnd() {
+      if (tempHtmlPath && existsSync(tempHtmlPath)) {
+        unlinkSync(tempHtmlPath);
+        tempHtmlPath = null;
+      }
+    },
+    configureServer(server) {
+      const html = getHtml(entryPath, false);
+      server.middlewares.use(async (req, res, next) => {
+        const url = req.url || "/";
+        if (url === "/" || !url.includes(".") && !url.startsWith("/@")) {
+          try {
+            const transformed = await server.transformIndexHtml(url, html);
+            res.setHeader("Content-Type", "text/html");
+            res.statusCode = 200;
+            res.end(transformed);
+            return;
+          } catch (e) {
+            console.error("Entry plugin error:", e);
+            next();
+            return;
+          }
+        }
+        next();
+      });
+    }
+  };
+}
+
+// src/vite/config.ts
+function findCliRoot2() {
+  let dir = path4.dirname(fileURLToPath2(import.meta.url));
+  for (let i = 0;i < 10; i++) {
+    const pkgPath = path4.join(dir, "package.json");
+    if (existsSync2(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync2(pkgPath, "utf-8"));
+        if (pkg.name === "prev-cli") {
+          return dir;
+        }
+      } catch {}
+    }
+    const parent = path4.dirname(dir);
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  return path4.dirname(path4.dirname(fileURLToPath2(import.meta.url)));
+}
+var cliRoot2 = findCliRoot2();
+var cliNodeModules = path4.join(cliRoot2, "node_modules");
+var srcRoot2 = path4.join(cliRoot2, "src");
+async function createViteConfig(options) {
+  const { rootDir, mode, port } = options;
+  const cacheDir = await ensureCacheDir(rootDir);
+  return {
+    root: rootDir,
+    mode,
+    cacheDir,
+    plugins: [
+      mdx({
+        remarkPlugins: [remarkGfm],
+        rehypePlugins: [
+          rehypeHighlight,
+          [rehypeMermaid, { strategy: "img-svg" }]
+        ]
+      }),
+      react(),
+      tailwindcss(),
+      pagesPlugin(rootDir),
+      entryPlugin(rootDir)
+    ],
+    resolve: {
+      alias: {
+        "@prev/ui": path4.join(srcRoot2, "ui"),
+        "@prev/theme": path4.join(srcRoot2, "theme"),
+        react: path4.join(cliNodeModules, "react"),
+        "react-dom": path4.join(cliNodeModules, "react-dom"),
+        "react-router-dom": path4.join(cliNodeModules, "react-router-dom")
+      }
+    },
+    optimizeDeps: {
+      entries: [],
+      include: [
+        "react",
+        "react-dom",
+        "react-dom/client",
+        "react-router-dom",
+        "react/jsx-runtime",
+        "react/jsx-dev-runtime"
+      ],
+      exclude: [
+        "clsx",
+        "class-variance-authority",
+        "tailwind-merge"
+      ]
+    },
+    ssr: {
+      noExternal: true
+    },
+    server: {
+      port,
+      strictPort: false,
+      fs: {
+        allow: [rootDir, cliRoot2]
+      }
+    },
+    preview: {
+      port,
+      strictPort: false
+    },
+    build: {
+      outDir: path4.join(rootDir, "dist")
+    }
+  };
+}
+
+// src/utils/port.ts
+import { createServer } from "net";
+async function getRandomPort(minPort = 3000, maxPort = 9000) {
+  const port = Math.floor(Math.random() * (maxPort - minPort + 1)) + minPort;
+  if (await isPortAvailable(port)) {
+    return port;
+  }
+  return findAvailablePort(minPort, maxPort);
+}
+function isPortAvailable(port) {
+  return new Promise((resolve) => {
+    const server = createServer();
+    server.once("error", () => {
+      resolve(false);
+    });
+    server.once("listening", () => {
+      server.close();
+      resolve(true);
+    });
+    server.listen(port, "127.0.0.1");
+  });
+}
+async function findAvailablePort(minPort, maxPort) {
+  for (let port = minPort;port <= maxPort; port++) {
+    if (await isPortAvailable(port)) {
+      return port;
+    }
+  }
+  throw new Error(`No available port found between ${minPort} and ${maxPort}`);
+}
+
+// src/vite/start.ts
+async function startDev(rootDir, options = {}) {
+  const port = options.port ?? await getRandomPort();
+  const config = await createViteConfig({
+    rootDir,
+    mode: "development",
+    port
+  });
+  const server = await createServer2(config);
+  await server.listen();
+  console.log();
+  console.log(`  prev dev server running at:`);
+  server.printUrls();
+  console.log();
+  return server;
+}
+async function buildSite(rootDir) {
+  const config = await createViteConfig({
+    rootDir,
+    mode: "production"
+  });
+  await build(config);
+  console.log();
+  console.log(`  Build complete. Output in ./dist`);
+  console.log();
+}
+async function previewSite(rootDir, options = {}) {
+  const port = options.port ?? await getRandomPort();
+  const config = await createViteConfig({
+    rootDir,
+    mode: "production",
+    port
+  });
+  const server = await preview(config);
+  console.log();
+  console.log(`  Preview server running at:`);
+  server.printUrls();
+  console.log();
+  return server;
+}
+
+// src/cli.ts
+var { values, positionals } = parseArgs({
+  args: process.argv.slice(2),
+  options: {
+    port: { type: "string", short: "p" },
+    days: { type: "string", short: "d" },
+    help: { type: "boolean", short: "h" }
+  },
+  allowPositionals: true
+});
+var command = positionals[0] || "dev";
+var rootDir = process.cwd();
+function printHelp() {
+  console.log(`
+prev - Zero-config documentation site generator
+
+Usage:
+  prev [command] [options]
+
+Commands:
+  dev       Start development server (default)
+  build     Build for production
+  preview   Preview production build
+  clean     Remove old cache directories
+
+Options:
+  -p, --port <port>   Specify port (dev/preview)
+  -d, --days <days>   Cache age threshold for clean (default: 30)
+  -h, --help          Show this help message
+
+Examples:
+  prev                Start dev server on random port
+  prev dev -p 3000    Start dev server on port 3000
+  prev build          Build static site to ./dist
+  prev clean          Remove caches older than 30 days
+  prev clean -d 7     Remove caches older than 7 days
+`);
+}
+async function main() {
+  if (values.help) {
+    printHelp();
+    process.exit(0);
+  }
+  const port = values.port ? parseInt(values.port, 10) : undefined;
+  const days = values.days ? parseInt(values.days, 10) : 30;
+  try {
+    switch (command) {
+      case "dev":
+        await startDev(rootDir, { port });
+        break;
+      case "build":
+        await buildSite(rootDir);
+        break;
+      case "preview":
+        await previewSite(rootDir, { port });
+        break;
+      case "clean":
+        const removed = await cleanCache({ maxAgeDays: days });
+        console.log(`Removed ${removed} cache(s) older than ${days} days`);
+        break;
+      default:
+        console.error(`Unknown command: ${command}`);
+        printHelp();
+        process.exit(1);
+    }
+  } catch (error) {
+    console.error("Error:", error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}
+main();

package/dist/theme/App.d.ts

@@ -0,0 +1 @@
+export declare function App(): import("react/jsx-runtime").JSX.Element;

package/dist/theme/Layout.d.ts

@@ -0,0 +1,2 @@
+import './styles.css';
+export declare function Layout(): import("react/jsx-runtime").JSX.Element;

package/dist/theme/Sidebar.d.ts

@@ -0,0 +1 @@
+export declare function Sidebar(): import("react/jsx-runtime").JSX.Element;

package/dist/theme/entry.d.ts

@@ -0,0 +1 @@
+import './styles.css';

package/dist/ui/button.d.ts

@@ -0,0 +1,10 @@
+import * as React from 'react';
+import { type VariantProps } from 'class-variance-authority';
+declare const buttonVariants: (props?: ({
+    variant?: "default" | "link" | "destructive" | "outline" | "secondary" | "ghost" | null | undefined;
+    size?: "default" | "sm" | "lg" | "icon" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
+}
+declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
+export { Button, buttonVariants };

package/dist/ui/card.d.ts

@@ -0,0 +1,8 @@
+import * as React from 'react';
+declare const Card: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+declare const CardHeader: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+declare const CardTitle: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLHeadingElement> & React.RefAttributes<HTMLParagraphElement>>;
+declare const CardDescription: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLParagraphElement> & React.RefAttributes<HTMLParagraphElement>>;
+declare const CardContent: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+declare const CardFooter: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+export { Card, CardHeader, CardFooter, CardTitle, CardDescription, CardContent };

package/dist/ui/index.d.ts

@@ -0,0 +1,3 @@
+export { Button, buttonVariants } from './button';
+export { Card, CardHeader, CardFooter, CardTitle, CardDescription, CardContent } from './card';
+export { cn } from './utils';

package/dist/ui/utils.d.ts

@@ -0,0 +1,2 @@
+import { type ClassValue } from 'clsx';
+export declare function cn(...inputs: ClassValue[]): string;

package/dist/utils/cache.d.ts

@@ -0,0 +1,7 @@
+export declare function getCacheDir(rootDir: string, branch?: string): Promise<string>;
+export declare function getCurrentBranch(rootDir: string): Promise<string>;
+export declare function cleanCache(options: {
+    maxAgeDays: number;
+    cacheRoot?: string;
+}): Promise<number>;
+export declare function ensureCacheDir(rootDir: string): Promise<string>;

package/dist/utils/port.d.ts

@@ -0,0 +1,2 @@
+export declare function getRandomPort(minPort?: number, maxPort?: number): Promise<number>;
+export declare function isPortAvailable(port: number): Promise<boolean>;

package/dist/vite/config.d.ts

@@ -0,0 +1,7 @@
+import type { InlineConfig } from 'vite';
+export interface ConfigOptions {
+    rootDir: string;
+    mode: 'development' | 'production';
+    port?: number;
+}
+export declare function createViteConfig(options: ConfigOptions): Promise<InlineConfig>;

package/dist/vite/pages.d.ts

@@ -0,0 +1,13 @@
+export interface Page {
+    route: string;
+    title: string;
+    file: string;
+}
+export interface SidebarItem {
+    title: string;
+    route?: string;
+    children?: SidebarItem[];
+}
+export declare function fileToRoute(file: string): string;
+export declare function scanPages(rootDir: string): Promise<Page[]>;
+export declare function buildSidebarTree(pages: Page[]): SidebarItem[];

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

@@ -0,0 +1,2 @@
+import type { Plugin } from 'vite';
+export declare function entryPlugin(rootDir?: string): Plugin;

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

@@ -0,0 +1,2 @@
+import type { Plugin } from 'vite';
+export declare function pagesPlugin(rootDir: string): Plugin;

package/dist/vite/start.d.ts

@@ -0,0 +1,6 @@
+export interface DevOptions {
+    port?: number;
+}
+export declare function startDev(rootDir: string, options?: DevOptions): Promise<import("vite").ViteDevServer>;
+export declare function buildSite(rootDir: string): Promise<void>;
+export declare function previewSite(rootDir: string, options?: DevOptions): Promise<import("vite").PreviewServer>;

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "prev-cli",
+  "version": "0.1.1",
+  "description": "Transform MDX directories into beautiful documentation websites",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "prev": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src/theme",
+    "src/ui"
+  ],
+  "keywords": [
+    "documentation",
+    "mdx",
+    "markdown",
+    "cli",
+    "static-site",
+    "vite",
+    "react"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lagz0ne/prev-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lagz0ne/prev-cli/issues"
+  },
+  "homepage": "https://github.com/lagz0ne/prev-cli#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "bun build src/cli.ts --outdir dist --target node --packages external && tsc --emitDeclarationOnly",
+    "dev": "tsc --watch",
+    "test": "bun test src",
+    "test:integration": "bun run build && bun test test/integration.test.ts",
+    "test:all": "bun run test && bun run test:integration"
+  },
+  "dependencies": {
+    "@mdx-js/rollup": "^3.0.0",
+    "@tailwindcss/vite": "^4.0.0",
+    "@vitejs/plugin-react-swc": "^4.2.2",
+    "class-variance-authority": "^0.7.0",
+    "clsx": "^2.1.0",
+    "fast-glob": "^3.3.0",
+    "lucide-react": "^0.460.0",
+    "playwright": "^1.57.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-router-dom": "^7.0.0",
+    "rehype-highlight": "^7.0.0",
+    "rehype-mermaid": "^3.0.0",
+    "remark-gfm": "^4.0.0",
+    "rolldown-vite": "^7.3.0",
+    "tailwind-merge": "^2.5.0",
+    "tailwindcss": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "bun-types": "^1.3.5",
+    "typescript": "^5.7.0"
+  }
+}

package/src/theme/App.tsx

@@ -0,0 +1,33 @@
+import React from 'react'
+import { BrowserRouter, Routes, Route } from 'react-router-dom'
+import { Layout } from './Layout'
+import { pages } from 'virtual:prev-pages'
+
+// Dynamic imports for MDX pages
+const pageModules = import.meta.glob('/**/*.mdx', { eager: true })
+
+function getPageComponent(file: string) {
+  const mod = pageModules[`/${file}`] as { default: React.ComponentType }
+  return mod?.default
+}
+
+export function App() {
+  return (
+    <BrowserRouter>
+      <Routes>
+        <Route element={<Layout />}>
+          {pages.map((page: { route: string; file: string }) => {
+            const Component = getPageComponent(page.file)
+            return Component ? (
+              <Route
+                key={page.route}
+                path={page.route}
+                element={<Component />}
+              />
+            ) : null
+          })}
+        </Route>
+      </Routes>
+    </BrowserRouter>
+  )
+}

package/src/theme/Layout.tsx

@@ -0,0 +1,19 @@
+import React from 'react'
+import { Outlet } from 'react-router-dom'
+import { Sidebar } from './Sidebar'
+import './styles.css'
+
+export function Layout() {
+  return (
+    <div className="min-h-screen bg-background text-foreground">
+      <div className="flex">
+        <Sidebar />
+        <main className="flex-1 p-8 max-w-4xl animate-fade-in">
+          <article className="prose max-w-none">
+            <Outlet />
+          </article>
+        </main>
+      </div>
+    </div>
+  )
+}

package/src/theme/Sidebar.tsx

@@ -0,0 +1,75 @@
+import React from 'react'
+import { Link, useLocation } from 'react-router-dom'
+import { sidebar } from 'virtual:prev-pages'
+import { cn } from '../ui/utils'
+
+interface SidebarItem {
+  title: string
+  route?: string
+  children?: SidebarItem[]
+}
+
+export function Sidebar() {
+  const location = useLocation()
+
+  return (
+    <aside className="w-64 border-r border-sidebar-border bg-sidebar p-4 min-h-screen sticky top-0">
+      <nav>
+        <ul className="space-y-1">
+          {(sidebar as SidebarItem[]).map((item, i) => (
+            <SidebarItemComponent
+              key={i}
+              item={item}
+              currentPath={location.pathname}
+            />
+          ))}
+        </ul>
+      </nav>
+    </aside>
+  )
+}
+
+function SidebarItemComponent({
+  item,
+  currentPath
+}: {
+  item: SidebarItem
+  currentPath: string
+}) {
+  const isActive = item.route === currentPath
+
+  if (item.children) {
+    return (
+      <li className="mt-4 first:mt-0">
+        <span className="font-semibold text-xs text-sidebar-foreground/60 uppercase tracking-wider">
+          {item.title}
+        </span>
+        <ul className="ml-3 mt-2 space-y-1">
+          {item.children.map((child, i) => (
+            <SidebarItemComponent
+              key={i}
+              item={child}
+              currentPath={currentPath}
+            />
+          ))}
+        </ul>
+      </li>
+    )
+  }
+
+  return (
+    <li>
+      <Link
+        to={item.route || '/'}
+        className={cn(
+          'block py-1.5 px-2 rounded-md text-sm transition-colors',
+          isActive
+            ? 'bg-sidebar-accent text-sidebar-accent-foreground font-medium'
+            : 'text-sidebar-foreground/70 hover:text-sidebar-foreground hover:bg-sidebar-accent/50'
+        )}
+      >
+        {item.title}
+      </Link>
+    </li>
+  )
+}

package/src/theme/entry.tsx

@@ -0,0 +1,10 @@
+import React from 'react'
+import { createRoot } from 'react-dom/client'
+import './styles.css'
+import { App } from './App'
+
+const container = document.getElementById('root')
+if (container) {
+  const root = createRoot(container)
+  root.render(<App />)
+}

package/src/theme/styles.css

@@ -0,0 +1,274 @@
+/* Fonts loaded via HTML preload for better performance */
+@import "tailwindcss";
+
+@custom-variant dark (&:is(.dark *));
+
+/* Scan CLI source files for Tailwind classes */
+@source "../theme";
+@source "../ui";
+
+/*
+  Design OS - Refined Utility Design System
+  A professional, editorial-inspired aesthetic with warm neutrals
+  Using Tailwind's stone palette for warmth
+*/
+@theme {
+  /* Font families - DM Sans for clean, geometric type */
+  --font-display: "DM Sans", system-ui, sans-serif;
+  --font-body: "DM Sans", system-ui, sans-serif;
+  --font-sans: "DM Sans", system-ui, sans-serif;
+  --font-mono: "IBM Plex Mono", ui-monospace, monospace;
+}
+
+/* Shadcn theme integration */
+@theme inline {
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-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);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+}
+
+/*
+  Light theme - Warm Stone palette
+  Professional, editorial aesthetic with warmth
+*/
+:root {
+  --radius: 0.5rem;
+  /* Backgrounds & Foregrounds - Stone palette for warmth */
+  --background: oklch(0.985 0.001 106.424); /* stone-50 #FAFAF9 */
+  --foreground: oklch(0.216 0.006 56.043); /* stone-900 #1C1917 */
+  --card: oklch(1 0 0); /* white */
+  --card-foreground: oklch(0.216 0.006 56.043); /* stone-900 */
+  --popover: oklch(1 0 0); /* white */
+  --popover-foreground: oklch(0.216 0.006 56.043); /* stone-900 */
+  /* Primary - Stone dark */
+  --primary: oklch(0.216 0.006 56.043); /* stone-900 */
+  --primary-foreground: oklch(0.985 0.001 106.424); /* stone-50 */
+  /* Secondary - Stone light */
+  --secondary: oklch(0.970 0.001 106.424); /* stone-100 */
+  --secondary-foreground: oklch(0.216 0.006 56.043); /* stone-900 */
+  /* Muted - Stone for subdued text */
+  --muted: oklch(0.970 0.001 106.424); /* stone-100 */
+  --muted-foreground: oklch(0.444 0.011 73.639); /* stone-600 #57534E */
+  /* Accent - Lime green for subtle pops */
+  --accent: oklch(0.970 0.001 106.424); /* stone-100 */
+  --accent-foreground: oklch(0.216 0.006 56.043); /* stone-900 */
+  /* Destructive - Rose */
+  --destructive: oklch(0.586 0.253 17.585); /* rose-600 */
+  /* Borders & Inputs - Stone very light */
+  --border: oklch(0.923 0.003 48.717); /* stone-200 #E7E5E4 */
+  --input: oklch(0.923 0.003 48.717); /* stone-200 */
+  --ring: oklch(0.553 0.013 58.071); /* stone-500 */
+  /* Chart colors */
+  --chart-1: oklch(0.532 0.157 131.589); /* lime-600 #65A30D */
+  --chart-2: oklch(0.6 0.118 184.704); /* teal-600 */
+  --chart-3: oklch(0.398 0.07 227.392); /* cyan-800 */
+  --chart-4: oklch(0.828 0.189 84.429); /* yellow-400 */
+  --chart-5: oklch(0.769 0.188 70.08); /* amber-400 */
+  /* Sidebar - Stone */
+  --sidebar: oklch(0.985 0.001 106.424); /* stone-50 */
+  --sidebar-foreground: oklch(0.216 0.006 56.043); /* stone-900 */
+  --sidebar-primary: oklch(0.216 0.006 56.043); /* stone-900 */
+  --sidebar-primary-foreground: oklch(0.985 0.001 106.424); /* stone-50 */
+  --sidebar-accent: oklch(0.970 0.001 106.424); /* stone-100 */
+  --sidebar-accent-foreground: oklch(0.216 0.006 56.043); /* stone-900 */
+  --sidebar-border: oklch(0.923 0.003 48.717); /* stone-200 */
+  --sidebar-ring: oklch(0.553 0.013 58.071); /* stone-500 */
+}
+
+/*
+  Dark theme - Warm Stone dark palette
+*/
+.dark {
+  /* Backgrounds & Foregrounds - Stone dark */
+  --background: oklch(0.216 0.006 56.043); /* stone-900 #1C1917 */
+  --foreground: oklch(0.985 0.001 106.424); /* stone-50 */
+  --card: oklch(0.268 0.007 34.298); /* stone-800 #292524 */
+  --card-foreground: oklch(0.985 0.001 106.424); /* stone-50 */
+  --popover: oklch(0.268 0.007 34.298); /* stone-800 */
+  --popover-foreground: oklch(0.985 0.001 106.424); /* stone-50 */
+  /* Primary - Stone light */
+  --primary: oklch(0.923 0.003 48.717); /* stone-200 */
+  --primary-foreground: oklch(0.216 0.006 56.043); /* stone-900 */
+  /* Secondary - Stone dark */
+  --secondary: oklch(0.318 0.008 43.185); /* stone-700 */
+  --secondary-foreground: oklch(0.985 0.001 106.424); /* stone-50 */
+  /* Muted - Stone dark */
+  --muted: oklch(0.318 0.008 43.185); /* stone-700 */
+  --muted-foreground: oklch(0.709 0.01 56.259); /* stone-400 #A8A29E */
+  /* Accent - Stone dark */
+  --accent: oklch(0.318 0.008 43.185); /* stone-700 */
+  --accent-foreground: oklch(0.985 0.001 106.424); /* stone-50 */
+  /* Destructive - Rose lighter for dark mode */
+  --destructive: oklch(0.712 0.194 13.428); /* rose-400 */
+  /* Borders & Inputs - Stone dark */
+  --border: oklch(0.370 0.010 67.558); /* stone-600 */
+  --input: oklch(0.370 0.010 67.558); /* stone-600 */
+  --ring: oklch(0.553 0.013 58.071); /* stone-500 */
+  /* Chart colors - brighter for dark mode */
+  --chart-1: oklch(0.648 0.2 131.684); /* lime-500 */
+  --chart-2: oklch(0.696 0.17 162.48); /* emerald-400 */
+  --chart-3: oklch(0.769 0.188 70.08); /* amber-400 */
+  --chart-4: oklch(0.627 0.265 303.9); /* purple-500 */
+  --chart-5: oklch(0.645 0.246 16.439); /* rose-500 */
+  /* Sidebar - Stone dark */
+  --sidebar: oklch(0.268 0.007 34.298); /* stone-800 */
+  --sidebar-foreground: oklch(0.985 0.001 106.424); /* stone-50 */
+  --sidebar-primary: oklch(0.648 0.2 131.684); /* lime-500 */
+  --sidebar-primary-foreground: oklch(0.216 0.006 56.043); /* stone-900 */
+  --sidebar-accent: oklch(0.318 0.008 43.185); /* stone-700 */
+  --sidebar-accent-foreground: oklch(0.985 0.001 106.424); /* stone-50 */
+  --sidebar-border: oklch(0.370 0.010 67.558); /* stone-600 */
+  --sidebar-ring: oklch(0.553 0.013 58.071); /* stone-500 */
+}
+
+/* Base layer styles */
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground font-sans antialiased;
+  }
+  h1, h2, h3, h4, h5, h6 {
+    font-family: var(--font-display);
+    @apply font-semibold tracking-tight;
+  }
+  code, pre, kbd {
+    font-family: var(--font-mono);
+  }
+}
+
+/* Subtle page fade-in animation */
+@layer utilities {
+  .animate-fade-in {
+    animation: fade-in 200ms ease-out;
+  }
+
+  @keyframes fade-in {
+    from {
+      opacity: 0;
+    }
+    to {
+      opacity: 1;
+    }
+  }
+
+  .animate-collapse-down {
+    animation: collapse-down 200ms ease-out;
+  }
+
+  .animate-collapse-up {
+    animation: collapse-up 200ms ease-out;
+  }
+
+  @keyframes collapse-down {
+    from {
+      height: 0;
+    }
+    to {
+      height: var(--radix-collapsible-content-height);
+    }
+  }
+
+  @keyframes collapse-up {
+    from {
+      height: var(--radix-collapsible-content-height);
+    }
+    to {
+      height: 0;
+    }
+  }
+}
+
+/* Prose styling with stone palette */
+@layer base {
+  .prose {
+    --tw-prose-body: var(--foreground);
+    --tw-prose-headings: var(--foreground);
+    --tw-prose-lead: var(--muted-foreground);
+    --tw-prose-links: var(--primary);
+    --tw-prose-bold: var(--foreground);
+    --tw-prose-counters: var(--muted-foreground);
+    --tw-prose-bullets: var(--muted-foreground);
+    --tw-prose-hr: var(--border);
+    --tw-prose-quotes: var(--foreground);
+    --tw-prose-quote-borders: var(--border);
+    --tw-prose-captions: var(--muted-foreground);
+    --tw-prose-kbd: var(--foreground);
+    --tw-prose-kbd-shadows: var(--ring);
+    --tw-prose-code: var(--foreground);
+    --tw-prose-pre-code: var(--foreground);
+    --tw-prose-pre-bg: var(--muted);
+    --tw-prose-th-borders: var(--border);
+    --tw-prose-td-borders: var(--border);
+  }
+
+  .prose :where(code):not(:where([class~="not-prose"], [class~="not-prose"] *)) {
+    @apply bg-muted px-1.5 py-0.5 rounded-sm text-sm font-mono;
+  }
+
+  .prose :where(code):not(:where([class~="not-prose"], [class~="not-prose"] *))::before,
+  .prose :where(code):not(:where([class~="not-prose"], [class~="not-prose"] *))::after {
+    content: none;
+  }
+
+  .prose :where(pre):not(:where([class~="not-prose"], [class~="not-prose"] *)) {
+    @apply bg-muted border border-border rounded-lg;
+  }
+
+  .prose :where(a):not(:where([class~="not-prose"], [class~="not-prose"] *)) {
+    @apply text-foreground font-medium underline underline-offset-4 decoration-border hover:decoration-foreground transition-colors;
+  }
+
+  .prose :where(h1, h2, h3, h4, h5, h6):not(:where([class~="not-prose"], [class~="not-prose"] *)) {
+    @apply font-display;
+  }
+
+  .prose :where(blockquote):not(:where([class~="not-prose"], [class~="not-prose"] *)) {
+    @apply border-l-4 border-border pl-4 italic text-muted-foreground;
+  }
+
+  .prose :where(table):not(:where([class~="not-prose"], [class~="not-prose"] *)) {
+    @apply w-full border-collapse;
+  }
+
+  .prose :where(th):not(:where([class~="not-prose"], [class~="not-prose"] *)) {
+    @apply border-b border-border px-4 py-2 text-left font-semibold;
+  }
+
+  .prose :where(td):not(:where([class~="not-prose"], [class~="not-prose"] *)) {
+    @apply border-b border-border px-4 py-2;
+  }
+}

package/src/ui/button.tsx

@@ -0,0 +1,48 @@
+import * as React from 'react'
+import { cva, type VariantProps } from 'class-variance-authority'
+import { cn } from './utils'
+
+const buttonVariants = cva(
+  'inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
+  {
+    variants: {
+      variant: {
+        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
+        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
+        outline: 'border border-input bg-background hover:bg-accent hover:text-accent-foreground',
+        secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+        ghost: 'hover:bg-accent hover:text-accent-foreground',
+        link: 'text-primary underline-offset-4 hover:underline',
+      },
+      size: {
+        default: 'h-10 px-4 py-2',
+        sm: 'h-9 rounded-md px-3',
+        lg: 'h-11 rounded-md px-8',
+        icon: 'h-10 w-10',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+      size: 'default',
+    },
+  }
+)
+
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {}
+
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant, size, ...props }, ref) => {
+    return (
+      <button
+        className={cn(buttonVariants({ variant, size, className }))}
+        ref={ref}
+        {...props}
+      />
+    )
+  }
+)
+Button.displayName = 'Button'
+
+export { Button, buttonVariants }

package/src/ui/card.tsx

@@ -0,0 +1,78 @@
+import * as React from 'react'
+import { cn } from './utils'
+
+const Card = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn(
+      'rounded-lg border bg-card text-card-foreground shadow-sm',
+      className
+    )}
+    {...props}
+  />
+))
+Card.displayName = 'Card'
+
+const CardHeader = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn('flex flex-col space-y-1.5 p-6', className)}
+    {...props}
+  />
+))
+CardHeader.displayName = 'CardHeader'
+
+const CardTitle = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLHeadingElement>
+>(({ className, ...props }, ref) => (
+  <h3
+    ref={ref}
+    className={cn(
+      'text-2xl font-semibold leading-none tracking-tight',
+      className
+    )}
+    {...props}
+  />
+))
+CardTitle.displayName = 'CardTitle'
+
+const CardDescription = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, ...props }, ref) => (
+  <p
+    ref={ref}
+    className={cn('text-sm text-muted-foreground', className)}
+    {...props}
+  />
+))
+CardDescription.displayName = 'CardDescription'
+
+const CardContent = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div ref={ref} className={cn('p-6 pt-0', className)} {...props} />
+))
+CardContent.displayName = 'CardContent'
+
+const CardFooter = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn('flex items-center p-6 pt-0', className)}
+    {...props}
+  />
+))
+CardFooter.displayName = 'CardFooter'
+
+export { Card, CardHeader, CardFooter, CardTitle, CardDescription, CardContent }

package/src/ui/index.ts

@@ -0,0 +1,10 @@
+export { Button, buttonVariants } from './button'
+export {
+  Card,
+  CardHeader,
+  CardFooter,
+  CardTitle,
+  CardDescription,
+  CardContent
+} from './card'
+export { cn } from './utils'

package/src/ui/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}