@aravindc26/velu 0.11.0 → 0.11.3

package/src/cli.ts

@@ -1,5 +1,5 @@
 import { resolve, join, dirname, delimiter } from "node:path";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync, readdirSync, copyFileSync, cpSync, rmSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
@@ -7,6 +7,16 @@ 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");
+const PRIMARY_CONFIG_NAME = "docs.json";
+const LEGACY_CONFIG_NAME = "velu.json";
+
+function resolveConfigPath(dir: string): string | null {
+  const primary = join(dir, PRIMARY_CONFIG_NAME);
+  if (existsSync(primary)) return primary;
+  const legacy = join(dir, LEGACY_CONFIG_NAME);
+  if (existsSync(legacy)) return legacy;
+  return null;
+}
 
 /** Build env that lets spawned processes resolve deps from the CLI's own node_modules */
 function engineEnv(docsDir?: string): NodeJS.ProcessEnv {
@@ -26,7 +36,7 @@ function printHelp() {
 
   Usage:
     velu init              Scaffold a new docs project with example files
-    velu lint              Validate velu.json and check referenced pages
+    velu lint              Validate docs.json (or velu.json) and check referenced pages
     velu run [--port N]    Build site and start dev server (default: 4321)
     velu build             Build a deployable static site (SSG)
     velu paths             Output all navigation paths and their source files as JSON
@@ -35,19 +45,19 @@ function printHelp() {
     --port <number>   Port for the dev server (default: 4321)
     --help            Show this help message
 
-  Run lint/run/build/paths from a directory containing velu.json.
+  Run lint/run/build/paths from a directory containing docs.json (or velu.json).
 `);
 }
 
 // ── init ────────────────────────────────────────────────────────────────────────
 
 function init(targetDir: string) {
-  if (existsSync(join(targetDir, "velu.json"))) {
-    console.error("❌ velu.json already exists in this directory.");
+  if (resolveConfigPath(targetDir)) {
+    console.error("❌ docs.json or velu.json already exists in this directory.");
     process.exit(1);
   }
 
-  // velu.json
+  // docs.json
   const config = {
     $schema: "https://raw.githubusercontent.com/aravindc26/velu/main/schema/velu.schema.json",
     theme: "neutral" as const,
@@ -86,13 +96,13 @@ function init(targetDir: string) {
       ],
     },
   };
-  writeFileSync(join(targetDir, "velu.json"), JSON.stringify(config, null, 2) + "\n", "utf-8");
+  writeFileSync(join(targetDir, PRIMARY_CONFIG_NAME), JSON.stringify(config, null, 2) + "\n", "utf-8");
 
   // Example pages
   const pages: Record<string, string> = {
-    "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`,
+    "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 \`docs.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/configuration.md": `# Configuration\n\nVelu uses a \`docs.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`,
     "api-reference/overview.md": `# API Overview\n\nThis section covers the API reference for your project.\n\n## Endpoints\n\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /api/health | Health check |\n| POST | /api/data | Create data |\n`,
     "api-reference/authentication.md": `# Authentication\n\nAll API requests require an API key.\n\n## Headers\n\n\`\`\`\nAuthorization: Bearer YOUR_API_KEY\n\`\`\`\n\n## Getting an API Key\n\nVisit the dashboard to generate your API key.\n`,
@@ -108,7 +118,7 @@ function init(targetDir: string) {
   console.log("  \x1b[36mvelu\x1b[0m  project initialized");
   console.log("");
   console.log("  Created:");
-  console.log("    velu.json");
+  console.log("    docs.json");
   for (const filePath of Object.keys(pages)) {
     console.log(`    ${filePath}`);
   }
@@ -126,7 +136,7 @@ async function lint(docsDir: string) {
   const result = validateVeluConfig(docsDir, SCHEMA_PATH);
 
   if (result.valid) {
-    console.log("✅ velu.json is valid. All referenced pages exist.");
+    console.log("✅ docs.json/velu.json is valid. All referenced pages exist.");
   } else {
     console.error("❌ Validation failed:\n");
     for (const err of result.errors) {
@@ -149,9 +159,9 @@ async function paths(docsDir: string) {
   const { readFileSync, existsSync } = await import("node:fs");
   const { join } = await import("node:path");
 
-  const configPath = join(docsDir, "velu.json");
-  if (!existsSync(configPath)) {
-    console.error("❌ velu.json not found.");
+  const configPath = resolveConfigPath(docsDir);
+  if (!configPath) {
+    console.error("❌ docs.json or velu.json not found.");
     process.exit(1);
   }
 
@@ -185,13 +195,25 @@ async function paths(docsDir: string) {
 
 async function generateProject(docsDir: string): Promise<string> {
   const { build } = await import("./build.js");
-  // 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");
+  // Generate into the active docs project directory.
+  const outDir = join(docsDir, ".velu-out");
   build(docsDir, outDir);
   return outDir;
 }
 
+function samePath(a: string, b: string): boolean {
+  return resolve(a).replace(/\\/g, "/").toLowerCase() === resolve(b).replace(/\\/g, "/").toLowerCase();
+}
+
+function prepareRuntimeOutDir(docsOutDir: string): string {
+  const runtimeOutDir = join(PACKAGE_ROOT, ".velu-out");
+  if (samePath(docsOutDir, runtimeOutDir)) return runtimeOutDir;
+
+  rmSync(runtimeOutDir, { recursive: true, force: true });
+  cpSync(docsOutDir, runtimeOutDir, { recursive: true, force: true });
+  return runtimeOutDir;
+}
+
 async function buildStatic(outDir: string, docsDir: string) {
   await new Promise<void>((res, rej) => {
     const child = spawn("node", ["_server.mjs", "build"], {
@@ -203,10 +225,51 @@ async function buildStatic(outDir: string, docsDir: string) {
   });
 }
 
+function exportMarkdownRoutes(outDir: string) {
+  const distDir = join(outDir, "dist");
+  const mdRouteRoot = join(distDir, "md-file");
+  if (!existsSync(mdRouteRoot)) return;
+
+  let copied = 0;
+
+  function walk(relDir: string) {
+    const absDir = join(mdRouteRoot, relDir);
+    const entries = readdirSync(absDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const relPath = relDir ? join(relDir, entry.name) : entry.name;
+      if (entry.isDirectory()) {
+        walk(relPath);
+        continue;
+      }
+      if (!entry.isFile() || !entry.name.toLowerCase().endsWith(".md")) continue;
+
+      const src = join(mdRouteRoot, relPath);
+      const dest = join(distDir, relPath);
+      mkdirSync(dirname(dest), { recursive: true });
+      copyFileSync(src, dest);
+      copied += 1;
+    }
+  }
+
+  walk("");
+  console.log(`📝 Exported ${copied} markdown files to static route paths`);
+}
+
 async function buildSite(docsDir: string) {
-  const outDir = await generateProject(docsDir);
-  await buildStatic(outDir, docsDir);
-  const staticOutDir = join(outDir, "dist");
+  const docsOutDir = await generateProject(docsDir);
+  const runtimeOutDir = prepareRuntimeOutDir(docsOutDir);
+  await buildStatic(runtimeOutDir, docsDir);
+  exportMarkdownRoutes(runtimeOutDir);
+
+  if (!samePath(docsOutDir, runtimeOutDir)) {
+    const docsDistDir = join(docsOutDir, "dist");
+    const runtimeDistDir = join(runtimeOutDir, "dist");
+    rmSync(docsDistDir, { recursive: true, force: true });
+    cpSync(runtimeDistDir, docsDistDir, { recursive: true, force: true });
+  }
+
+  const staticOutDir = join(docsOutDir, "dist");
   console.log(`\n📁 Static site output: ${staticOutDir}`);
 }
 
@@ -227,8 +290,9 @@ function spawnServer(outDir: string, command: string, port: number, docsDir: str
 }
 
 async function run(docsDir: string, port: number) {
-  const outDir = await generateProject(docsDir);
-  spawnServer(outDir, "dev", port, docsDir);
+  const docsOutDir = await generateProject(docsDir);
+  const runtimeOutDir = prepareRuntimeOutDir(docsOutDir);
+  spawnServer(runtimeOutDir, "dev", port, docsDir);
 }
 
 // ── Parse args ───────────────────────────────────────────────────────────────────
@@ -243,15 +307,15 @@ if (!command || command === "--help" || command === "-h") {
 
 const docsDir = process.cwd();
 
-// init doesn't require velu.json
+// init doesn't require docs.json
 if (command === "init") {
   init(docsDir);
   process.exit(0);
 }
 
-if (!existsSync(join(docsDir, "velu.json"))) {
-  console.error("❌ No velu.json found in the current directory.");
-  console.error("   Run `velu init` to scaffold a new project, or run from a directory containing velu.json.");
+if (!resolveConfigPath(docsDir)) {
+  console.error("❌ No docs.json or velu.json found in the current directory.");
+  console.error("   Run `velu init` to scaffold a new project, or run from a directory containing docs.json.");
   process.exit(1);
 }