@aravindc26/velu 0.10.0 → 0.11.1

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 } 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,27 +36,28 @@ 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
 
   Options:
     --port <number>   Port for the dev server (default: 4321)
     --help            Show this help message
 
-  Run lint/run/build 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,
@@ -55,11 +66,17 @@ function init(targetDir: string) {
         {
           tab: "Getting Started",
           slug: "getting-started",
-          pages: ["quickstart", "installation"],
+          pages: [
+            "quickstart",
+            "installation",
+            { separator: "Resources" },
+            { label: "Velu Website", href: "https://getvelu.com" },
+          ],
           groups: [
             {
               group: "Guides",
               slug: "guides",
+              description: "Step-by-step guides to configure and deploy your docs.",
               pages: ["guides/configuration", "guides/deployment"],
             },
           ],
@@ -70,15 +87,22 @@ function init(targetDir: string) {
           pages: ["api-reference/overview", "api-reference/authentication"],
         },
       ],
+      anchors: [
+        {
+          anchor: "GitHub",
+          href: "https://github.com/aravindc26/velu",
+          icon: "Github",
+        },
+      ],
     },
   };
-  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`,
@@ -94,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}`);
   }
@@ -112,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) {
@@ -122,6 +146,51 @@ async function lint(docsDir: string) {
   }
 }
 
+// ── paths ───────────────────────────────────────────────────────────────────────
+
+interface PathEntry {
+  path: string;
+  file: string | null;
+}
+
+async function paths(docsDir: string) {
+  const { collectPages } = await import("./validate.js");
+  const { normalizeConfigNavigation } = await import("./navigation-normalize.js");
+  const { readFileSync, existsSync } = await import("node:fs");
+  const { join } = await import("node:path");
+
+  const configPath = resolveConfigPath(docsDir);
+  if (!configPath) {
+    console.error("❌ docs.json or velu.json not found.");
+    process.exit(1);
+  }
+
+  const raw = JSON.parse(readFileSync(configPath, "utf-8"));
+  const config = normalizeConfigNavigation(raw);
+  const pages = collectPages(config);
+
+  const entries: PathEntry[] = pages.map((pagePath) => {
+    // Check for .mdx first, then .md
+    const mdxPath = join(docsDir, `${pagePath}.mdx`);
+    const mdPath = join(docsDir, `${pagePath}.md`);
+
+    if (existsSync(mdxPath)) {
+      return { path: pagePath, file: `${pagePath}.mdx` };
+    }
+    if (existsSync(mdPath)) {
+      return { path: pagePath, file: `${pagePath}.md` };
+    }
+    return { path: pagePath, file: null };
+  });
+
+  const output = {
+    paths: entries,
+    count: entries.length,
+  };
+
+  console.log(JSON.stringify(output, null, 2));
+}
+
 // ── build ────────────────────────────────────────────────────────────────────────
 
 async function generateProject(docsDir: string): Promise<string> {
@@ -144,9 +213,41 @@ 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);
+  exportMarkdownRoutes(outDir);
   const staticOutDir = join(outDir, "dist");
   console.log(`\n📁 Static site output: ${staticOutDir}`);
 }
@@ -184,15 +285,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);
 }
 
@@ -201,6 +302,10 @@ switch (command) {
     await lint(docsDir);
     break;
 
+  case "paths":
+    await paths(docsDir);
+    break;
+
   case "build":
     await buildSite(docsDir);
     break;