@aravindc26/velu 0.8.0 → 0.9.1

package/src/cli.ts

@@ -1,4 +1,4 @@
-import { resolve, join, dirname } from "node:path";
+import { resolve, join, dirname, delimiter } from "node:path";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
@@ -6,6 +6,17 @@ import { fileURLToPath } from "node:url";
 const __filename = fileURLToPath(import.meta.url);
 const PACKAGE_ROOT = resolve(dirname(__filename), "..");
 const SCHEMA_PATH = join(PACKAGE_ROOT, "schema", "velu.schema.json");
+const NODE_MODULES_PATH = join(PACKAGE_ROOT, "node_modules");
+
+/** Build env that lets spawned processes resolve deps from the CLI's own node_modules */
+function engineEnv(docsDir?: string): NodeJS.ProcessEnv {
+  const existing = process.env.NODE_PATH || "";
+  return {
+    ...process.env,
+    NODE_PATH: existing ? `${NODE_MODULES_PATH}${delimiter}${existing}` : NODE_MODULES_PATH,
+    ...(docsDir ? { VELU_DOCS_DIR: docsDir } : {}),
+  };
+}
 
 // ── Help ────────────────────────────────────────────────────────────────────────
 
@@ -65,7 +76,7 @@ function init(targetDir: string) {
 
   // Example pages
   const pages: Record<string, string> = {
-    "quickstart.md": `# Quickstart\n\nWelcome to your new documentation site!\n\n## Prerequisites\n\n- Node.js 18+\n- npm\n\n## Getting Started\n\n1. Edit the markdown files in this directory\n2. Update \`velu.json\` to configure navigation\n3. Run \`velu run\` to start the dev server\n\n\`\`\`bash\nvelu run\n\`\`\`\n\nYour site is live at \`http://localhost:4321\`.\n`,
+    "quickstart.md": `# Quickstart\n\nWelcome to your new documentation site!\n\n## Prerequisites\n\n- Node.js 20.9+\n- npm\n\n## Getting Started\n\n1. Edit the markdown files in this directory\n2. Update \`velu.json\` to configure navigation\n3. Run \`velu run\` to start the dev server\n\n\`\`\`bash\nvelu run\n\`\`\`\n\nYour site is live at \`http://localhost:4321\`.\n`,
     "installation.md": `# Installation\n\nInstall Velu globally:\n\n\`\`\`bash\nnpm install -g @aravindc26/velu\n\`\`\`\n\nOr run directly with npx:\n\n\`\`\`bash\nnpx @aravindc26/velu run\n\`\`\`\n`,
     "guides/configuration.md": `# Configuration\n\nVelu uses a \`velu.json\` file to define your site's navigation.\n\n## Navigation Structure\n\n- **Tabs** — Top-level horizontal navigation\n- **Groups** — Collapsible sidebar sections within a tab\n- **Pages** — Individual markdown documents\n\n## Example\n\n\`\`\`json\n{\n  "navigation": {\n    "tabs": [\n      {\n        "tab": "Getting Started",\n        "slug": "getting-started",\n        "groups": [\n          {\n            "group": "Basics",\n            "slug": "getting-started",\n            "pages": ["quickstart"]\n          }\n        ]\n      }\n    ]\n  }\n}\n\`\`\`\n`,
     "guides/deployment.md": `# Deployment\n\nBuild your site for production:\n\n\`\`\`bash\nvelu build\n\`\`\`\n\nThe output is a static site you can deploy anywhere — Netlify, Vercel, GitHub Pages, etc.\n`,
@@ -115,16 +126,19 @@ async function lint(docsDir: string) {
 
 async function generateProject(docsDir: string): Promise<string> {
   const { build } = await import("./build.js");
-  const outDir = join(docsDir, ".velu-out");
+  // Place .velu-out inside CLI package dir so node_modules resolves
+  // naturally by walking up — avoids symlinks that Turbopack rejects.
+  const outDir = join(PACKAGE_ROOT, ".velu-out");
   build(docsDir, outDir);
   return outDir;
 }
 
-async function buildStatic(outDir: string) {
+async function buildStatic(outDir: string, docsDir: string) {
   await new Promise<void>((res, rej) => {
     const child = spawn("node", ["_server.mjs", "build"], {
       cwd: outDir,
       stdio: "inherit",
+      env: engineEnv(docsDir),
     });
     child.on("exit", (code) => (code === 0 ? res() : rej(new Error(`Build exited with ${code}`))));
   });
@@ -132,32 +146,18 @@ async function buildStatic(outDir: string) {
 
 async function buildSite(docsDir: string) {
   const outDir = await generateProject(docsDir);
-  await installDeps(outDir);
-  await buildStatic(outDir);
-  const distDir = join(outDir, "dist");
-  console.log(`\n📁 Static site output: ${distDir}`);
+  await buildStatic(outDir, docsDir);
+  const staticOutDir = join(outDir, "dist");
+  console.log(`\n📁 Static site output: ${staticOutDir}`);
 }
 
 // ── run ──────────────────────────────────────────────────────────────────────────
 
-async function installDeps(outDir: string) {
-  if (!existsSync(join(outDir, "node_modules"))) {
-    console.log("\n📦 Installing dependencies...\n");
-    await new Promise<void>((res, rej) => {
-      const child = spawn("npm", ["install", "--silent"], {
-        cwd: outDir,
-        stdio: "inherit",
-        shell: true,
-      });
-      child.on("exit", (code) => (code === 0 ? res() : rej(new Error(`npm install exited with ${code}`))));
-    });
-  }
-}
-
-function spawnServer(outDir: string, command: string, port: number) {
+function spawnServer(outDir: string, command: string, port: number, docsDir: string) {
   const child = spawn("node", ["_server.mjs", command, "--port", String(port)], {
     cwd: outDir,
     stdio: "inherit",
+    env: engineEnv(docsDir),
   });
 
   child.on("exit", (code) => process.exit(code ?? 0));
@@ -169,8 +169,7 @@ function spawnServer(outDir: string, command: string, port: number) {
 
 async function run(docsDir: string, port: number) {
   const outDir = await generateProject(docsDir);
-  await installDeps(outDir);
-  spawnServer(outDir, "dev", port);
+  spawnServer(outDir, "dev", port, docsDir);
 }
 
 // ── Parse args ───────────────────────────────────────────────────────────────────

package/src/engine/_server.mjs

@@ -0,0 +1,271 @@
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { watch } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, extname, join, resolve } from 'node:path';
+
+const require = createRequire(import.meta.url);
+const nextBinPath = require.resolve('next/dist/bin/next');
+
+// ── Docs directory (passed via env var from CLI) ────────────────────────────
+const docsDir = process.env.VELU_DOCS_DIR || resolve('..');
+const contentDir = resolve('content', 'docs');
+
+function loadConfig() {
+  const raw = readFileSync(join(docsDir, 'velu.json'), 'utf-8');
+  return JSON.parse(raw);
+}
+
+function pageBasename(page) {
+  return page.split('/').pop();
+}
+
+function pageLabelFromSlug(slug) {
+  const last = slug.split('/').pop() || slug;
+  return last.replace(/[-_]/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+function buildArtifacts(config) {
+  const pageMap = [];
+  const metaFiles = [];
+  const rootTabs = (config.navigation?.tabs || []).filter((tab) => !tab.href);
+  const rootPages = rootTabs.map((tab) => tab.slug);
+  let firstPage = 'quickstart';
+  let hasFirstPage = false;
+
+  function trackFirstPage(dest) {
+    if (!hasFirstPage) {
+      firstPage = dest;
+      hasFirstPage = true;
+    }
+  }
+
+  function addGroup(group, parentDir) {
+    const groupDir = `${parentDir}/${group.slug}`;
+    const pages = [];
+
+    for (const item of group.pages || []) {
+      if (typeof item === 'string') {
+        const basename = pageBasename(item);
+        const dest = `${groupDir}/${basename}`;
+        pageMap.push({ src: item, dest });
+        pages.push(basename);
+        trackFirstPage(dest);
+      } else {
+        addGroup(item, groupDir);
+        pages.push(item.slug);
+      }
+    }
+
+    const groupMeta = {
+      title: group.group,
+      pages,
+      defaultOpen: group.expanded !== false,
+    };
+
+    if (group.icon) groupMeta.icon = group.icon;
+
+    metaFiles.push({ dir: groupDir, data: groupMeta });
+  }
+
+  for (const tab of rootTabs) {
+    const tabPages = [];
+
+    for (const group of tab.groups || []) {
+      addGroup(group, tab.slug);
+      tabPages.push(group.slug);
+    }
+
+    for (const page of tab.pages || []) {
+      const basename = pageBasename(page);
+      const dest = `${tab.slug}/${basename}`;
+      pageMap.push({ src: page, dest });
+      tabPages.push(basename);
+      trackFirstPage(dest);
+    }
+
+    const tabMeta = {
+      title: tab.tab,
+      root: true,
+      pages: tabPages,
+    };
+
+    if (tab.icon) tabMeta.icon = tab.icon;
+
+    metaFiles.push({ dir: tab.slug, data: tabMeta });
+  }
+
+  if (rootPages.length > 0) {
+    metaFiles.push({ dir: '', data: { pages: rootPages } });
+  }
+
+  return { pageMap, metaFiles, firstPage };
+}
+
+function processPage(srcPath, destPath, slug) {
+  let content = readFileSync(srcPath, 'utf-8');
+  if (!content.startsWith('---')) {
+    const titleMatch = content.match(/^#\s+(.+)$/m);
+    const title = titleMatch ? titleMatch[1] : pageLabelFromSlug(slug);
+    if (titleMatch) {
+      content = content.replace(/^#\s+.+$/m, '').trimStart();
+    }
+    content = `---\ntitle: "${title}"\n---\n\n${content}`;
+  }
+
+  mkdirSync(dirname(destPath), { recursive: true });
+  writeFileSync(destPath, content, 'utf-8');
+}
+
+function writeMetaFiles(metaFiles) {
+  for (const meta of metaFiles) {
+    const metaPath = join(contentDir, meta.dir, 'meta.json');
+    mkdirSync(dirname(metaPath), { recursive: true });
+    writeFileSync(metaPath, JSON.stringify(meta.data, null, 2) + '\n', 'utf-8');
+  }
+}
+
+function writeIndexPage(firstPage) {
+  writeFileSync(
+    join(contentDir, 'index.mdx'),
+    `---\ntitle: "Overview"\ndescription: Documentation powered by Velu + Fumadocs\n---\n\nimport { Card, Cards } from "fumadocs-ui/components/card"\nimport { Callout } from "fumadocs-ui/components/callout"\n\n<Callout type="info">\n  This site is powered by Velu + Fumadocs.\n</Callout>\n\n## Start here\n\n<Cards>\n  <Card\n    title="Read the docs"\n    href="/${firstPage}/"\n    description="Begin with the first page in your configured navigation."\n  />\n</Cards>\n`,
+    'utf-8'
+  );
+}
+
+function rebuildFromConfig() {
+  const config = loadConfig();
+  const artifacts = buildArtifacts(config);
+
+  rmSync(contentDir, { recursive: true, force: true });
+  mkdirSync(contentDir, { recursive: true });
+
+  writeMetaFiles(artifacts.metaFiles);
+
+  for (const { src, dest } of artifacts.pageMap) {
+    const srcPath = join(docsDir, `${src}.md`);
+    if (!existsSync(srcPath)) continue;
+    const destPath = join(contentDir, `${dest}.mdx`);
+    processPage(srcPath, destPath, src);
+  }
+
+  writeIndexPage(artifacts.firstPage);
+  return artifacts.pageMap;
+}
+
+let pageMap = rebuildFromConfig();
+
+function syncMarkdownFile(filename) {
+  const srcSlug = filename.replace(/\\/g, '/').replace(/\.md$/, '');
+  const srcPath = join(docsDir, `${srcSlug}.md`);
+
+  if (!existsSync(srcPath)) {
+    pageMap = rebuildFromConfig();
+    return;
+  }
+
+  const matches = pageMap.filter((entry) => entry.src === srcSlug);
+  if (matches.length === 0) return;
+
+  for (const match of matches) {
+    const destPath = join(contentDir, `${match.dest}.mdx`);
+    processPage(srcPath, destPath, srcSlug);
+  }
+
+  console.log('  \x1b[32m↻\x1b[0m  ' + srcSlug);
+}
+
+function syncConfig() {
+  const srcPath = join(docsDir, 'velu.json');
+  copyFileSync(srcPath, resolve('velu.json'));
+  pageMap = rebuildFromConfig();
+  console.log('  \x1b[32m↻\x1b[0m  velu.json updated (navigation/content synced)');
+}
+
+function startWatcher() {
+  const debounce = new Map();
+
+  watch(docsDir, { recursive: true }, (_, rawFilename) => {
+    if (!rawFilename) return;
+    const filename = rawFilename.replace(/\\/g, '/');
+
+    if (filename.startsWith('.velu-out/')) return;
+    if (filename.includes('node_modules')) return;
+    if (filename.startsWith('.')) return;
+
+    if (debounce.has(filename)) clearTimeout(debounce.get(filename));
+    debounce.set(
+      filename,
+      setTimeout(() => {
+        debounce.delete(filename);
+
+        try {
+          if (filename === 'velu.json') {
+            syncConfig();
+            return;
+          }
+
+          if (extname(filename) === '.md') {
+            syncMarkdownFile(filename);
+          }
+        } catch (error) {
+          console.error('  \x1b[31m✗\x1b[0m  Failed to sync ' + filename + ': ' + error.message);
+        }
+      }, 120)
+    );
+  });
+}
+
+function runNext(command, port) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const args = [nextBinPath, command];
+    if (command === 'dev' || command === 'start') {
+      args.push('--port', String(port));
+    }
+
+    const child = spawn(process.execPath, args, {
+      cwd: '.',
+      stdio: 'inherit',
+      env: process.env,
+    });
+
+    child.on('exit', (code) => {
+      if (code === 0) resolvePromise();
+      else rejectPromise(new Error(`${command} exited with ${code}`));
+    });
+  });
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+const command = args[0] || 'dev';
+const portIdx = args.indexOf('--port');
+const port = portIdx !== -1 ? parseInt(args[portIdx + 1], 10) : 4321;
+
+if (command === 'dev') {
+  console.log('');
+  console.log('  \x1b[36mvelu\x1b[0m  fumadocs dev');
+  console.log('');
+  console.log('  watching for file changes...');
+  startWatcher();
+  await runNext('dev', port);
+} else if (command === 'build') {
+  console.log('\n  Building site...\n');
+  await runNext('build', port);
+
+  // Run Pagefind to index the static output for search
+  console.log('  Indexing for search...');
+  const pagefindBin = join(dirname(require.resolve('next/package.json')), '..', 'pagefind', 'lib', 'runner', 'bin.cjs');
+  await new Promise((res, rej) => {
+    const pf = spawn(process.execPath, [pagefindBin, '--site', 'dist', '--output-path', 'dist/pagefind'], {
+      cwd: '.',
+      stdio: 'inherit',
+    });
+    pf.on('exit', (code) => (code === 0 ? res() : rej(new Error(`pagefind exited with ${code}`))));
+  });
+
+  console.log('\n  ✅ Site built successfully.\n');
+} else {
+  console.error(`Unknown server command: ${command}`);
+  process.exit(1);
+}

package/src/engine/app/(docs)/[[...slug]]/page.tsx

@@ -0,0 +1,66 @@
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import { createRelativeLink } from 'fumadocs-ui/mdx';
+import {
+  DocsBody,
+  DocsDescription,
+  DocsPage,
+  DocsTitle,
+} from 'fumadocs-ui/layouts/docs/page';
+import { getMDXComponents } from '@/mdx-components';
+import { source } from '@/lib/source';
+import { CopyPageButton } from '@/components/copy-page';
+
+interface RouteParams {
+  slug?: string[];
+}
+
+interface PageProps {
+  params: Promise<RouteParams>;
+}
+
+export default async function Page({ params }: PageProps) {
+  const resolvedParams = await params;
+  const page = source.getPage(resolvedParams.slug);
+
+  if (!page) notFound();
+
+  const MDX = page.data.body;
+
+  return (
+    <DocsPage toc={page.data.toc} full={page.data.full}>
+      <div data-pagefind-body data-pagefind-meta={`title:${page.data.title}`}>
+        <div className="velu-title-row">
+          <DocsTitle>{page.data.title}</DocsTitle>
+          <CopyPageButton />
+        </div>
+        {page.data.description ? <DocsDescription>{page.data.description}</DocsDescription> : null}
+        <DocsBody>
+          <MDX
+            components={getMDXComponents({
+              a: createRelativeLink(source, page),
+            })}
+          />
+        </DocsBody>
+      </div>
+    </DocsPage>
+  );
+}
+
+export async function generateStaticParams() {
+  const params = source.generateParams();
+  // Include root path for the optional catch-all [[...slug]]
+  return [{ slug: [] }, ...params];
+}
+
+export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
+  const resolvedParams = await params;
+  const page = source.getPage(resolvedParams.slug);
+
+  if (!page) notFound();
+
+  return {
+    title: page.data.title,
+    description: page.data.description,
+  };
+}

package/src/engine/app/(docs)/layout.tsx

@@ -0,0 +1,16 @@
+import type { ReactNode } from 'react';
+import { DocsLayout } from 'fumadocs-ui/layouts/docs';
+import { baseOptions } from '@/lib/layout.shared';
+import { source } from '@/lib/source';
+
+export default function DocsRootLayout({ children }: { children: ReactNode }) {
+  return (
+    <DocsLayout
+      tree={source.getPageTree()}
+      sidebar={{ collapsible: false }}
+      {...baseOptions()}
+    >
+      {children}
+    </DocsLayout>
+  );
+}