@raystack/chronicle 0.1.0-canary.a638730 → 0.1.0-canary.cb102e9

package/dist/cli/index.js

@@ -85,6 +85,18 @@ async function createViteConfig(options) {
 }
 var init_vite_config = () => {};
 
+// src/server/utils/safe-path.ts
+import path6 from "path";
+function safePath(baseDir, urlPath) {
+  const decoded = decodeURIComponent(urlPath.split("?")[0]);
+  const resolved = path6.resolve(baseDir, "." + decoded);
+  if (!resolved.startsWith(path6.resolve(baseDir) + path6.sep) && resolved !== path6.resolve(baseDir)) {
+    return null;
+  }
+  return resolved;
+}
+var init_safe_path = () => {};
+
 // src/server/dev.ts
 var exports_dev = {};
 __export(exports_dev, {
@@ -94,7 +106,7 @@ import { createServer as createViteServer } from "vite";
 import { createServer } from "http";
 import fsPromises from "fs/promises";
 import { createReadStream } from "fs";
-import path6 from "path";
+import path7 from "path";
 import chalk3 from "chalk";
 async function startDevServer(options) {
   const { port, root, contentDir } = options;
@@ -104,7 +116,7 @@ async function startDevServer(options) {
     server: { middlewareMode: true },
     appType: "custom"
   });
-  const templatePath = path6.resolve(root, "src/server/index.html");
+  const templatePath = path7.resolve(root, "src/server/index.html");
   const server = createServer(async (req, res) => {
     const url = req.url || "/";
     try {
@@ -115,12 +127,12 @@ async function startDevServer(options) {
         });
         return;
       }
-      const contentFile = path6.join(contentDir, decodeURIComponent(url.split("?")[0]));
-      if (!url.endsWith(".md") && !url.endsWith(".mdx")) {
+      const contentFile = safePath(contentDir, url);
+      if (contentFile && !url.endsWith(".md") && !url.endsWith(".mdx")) {
         try {
           const stat = await fsPromises.stat(contentFile);
           if (stat.isFile()) {
-            const ext = path6.extname(contentFile).toLowerCase();
+            const ext = path7.extname(contentFile).toLowerCase();
             const mimeTypes = {
               ".png": "image/png",
               ".jpg": "image/jpeg",
@@ -148,7 +160,7 @@ async function startDevServer(options) {
         });
         return;
       }
-      const { matchRoute } = await vite.ssrLoadModule(path6.resolve(root, "src/server/router.ts"));
+      const { matchRoute } = await vite.ssrLoadModule(path7.resolve(root, "src/server/router.ts"));
       const routeHandler = matchRoute(new URL(url, `http://localhost:${port}`).href);
       if (routeHandler) {
         const request = new Request(new URL(url, `http://localhost:${port}`));
@@ -161,11 +173,11 @@ async function startDevServer(options) {
       }
       const pathname = new URL(url, `http://localhost:${port}`).pathname;
       const slug = pathname === "/" ? [] : pathname.slice(1).split("/").filter(Boolean);
-      const source = await vite.ssrLoadModule(path6.resolve(root, "src/lib/source.ts"));
-      const { mdxComponents } = await vite.ssrLoadModule(path6.resolve(root, "src/components/mdx/index.tsx"));
-      const { loadConfig } = await vite.ssrLoadModule(path6.resolve(root, "src/lib/config.ts"));
+      const source = await vite.ssrLoadModule(path7.resolve(root, "src/lib/source.ts"));
+      const { mdxComponents } = await vite.ssrLoadModule(path7.resolve(root, "src/components/mdx/index.tsx"));
+      const { loadConfig } = await vite.ssrLoadModule(path7.resolve(root, "src/lib/config.ts"));
       const config = loadConfig();
-      const { loadApiSpecs } = await vite.ssrLoadModule(path6.resolve(root, "src/lib/openapi.ts"));
+      const { loadApiSpecs } = await vite.ssrLoadModule(path7.resolve(root, "src/lib/openapi.ts"));
       const apiSpecs = config.api?.length ? loadApiSpecs(config.api) : [];
       const [tree, sourcePage] = await Promise.all([
         source.buildPageTree(),
@@ -187,9 +199,10 @@ async function startDevServer(options) {
       }
       let template = await fsPromises.readFile(templatePath, "utf-8");
       template = await vite.transformIndexHtml(url, template);
-      const dataScript = `<script>window.__PAGE_DATA__ = ${JSON.stringify(embeddedData)}</script>`;
+      const safeJson = JSON.stringify(embeddedData).replace(/</g, "\\u003c");
+      const dataScript = `<script>window.__PAGE_DATA__ = ${safeJson}</script>`;
       template = template.replace("<!--head-outlet-->", `<!--head-outlet-->${dataScript}`);
-      const { render } = await vite.ssrLoadModule(path6.resolve(root, "src/server/entry-server.tsx"));
+      const { render } = await vite.ssrLoadModule(path7.resolve(root, "src/server/entry-server.tsx"));
       const html = render(url, { config, tree, page: pageData, apiSpecs });
       const finalHtml = template.replace("<!--ssr-outlet-->", html);
       res.setHeader("Content-Type", "text/html");
@@ -219,6 +232,307 @@ async function startDevServer(options) {
 }
 var init_dev = __esm(() => {
   init_vite_config();
+  init_safe_path();
+});
+
+// src/lib/config.ts
+import fs3 from "fs";
+import path8 from "path";
+import { parse as parse2 } from "yaml";
+function resolveConfigPath() {
+  const projectRoot = process.env.CHRONICLE_PROJECT_ROOT;
+  if (projectRoot) {
+    const rootPath = path8.join(projectRoot, CONFIG_FILE);
+    if (fs3.existsSync(rootPath))
+      return rootPath;
+  }
+  const cwdPath = path8.join(process.cwd(), CONFIG_FILE);
+  if (fs3.existsSync(cwdPath))
+    return cwdPath;
+  const contentDir = process.env.CHRONICLE_CONTENT_DIR;
+  if (contentDir) {
+    const contentPath = path8.join(contentDir, CONFIG_FILE);
+    if (fs3.existsSync(contentPath))
+      return contentPath;
+  }
+  return null;
+}
+function loadConfig() {
+  const configPath = resolveConfigPath();
+  if (!configPath) {
+    return defaultConfig;
+  }
+  const raw = fs3.readFileSync(configPath, "utf-8");
+  const userConfig = parse2(raw);
+  return {
+    ...defaultConfig,
+    ...userConfig,
+    theme: {
+      name: userConfig.theme?.name ?? defaultConfig.theme.name,
+      colors: { ...defaultConfig.theme?.colors, ...userConfig.theme?.colors }
+    },
+    search: { ...defaultConfig.search, ...userConfig.search },
+    footer: userConfig.footer,
+    api: userConfig.api,
+    llms: { enabled: false, ...userConfig.llms },
+    analytics: { enabled: false, ...userConfig.analytics }
+  };
+}
+var CONFIG_FILE = "chronicle.yaml", defaultConfig;
+var init_config = __esm(() => {
+  defaultConfig = {
+    title: "Documentation",
+    theme: { name: "default" },
+    search: { enabled: true, placeholder: "Search..." }
+  };
+});
+// src/lib/openapi.ts
+import fs4 from "fs";
+import path9 from "path";
+import { parse as parseYaml } from "yaml";
+function loadApiSpecs(apiConfigs) {
+  const contentDir = process.env.CHRONICLE_CONTENT_DIR ?? process.cwd();
+  return apiConfigs.map((config) => loadApiSpec(config, contentDir));
+}
+function loadApiSpec(config, contentDir) {
+  const specPath = path9.resolve(contentDir, config.spec);
+  const raw = fs4.readFileSync(specPath, "utf-8");
+  const isYaml = specPath.endsWith(".yaml") || specPath.endsWith(".yml");
+  const doc = isYaml ? parseYaml(raw) : JSON.parse(raw);
+  let v3Doc;
+  if ("swagger" in doc && doc.swagger === "2.0") {
+    v3Doc = convertV2toV3(doc);
+  } else if ("openapi" in doc && doc.openapi.startsWith("3.")) {
+    v3Doc = resolveDocument(doc);
+  } else {
+    throw new Error(`Unsupported spec version in ${config.spec}`);
+  }
+  return {
+    name: config.name,
+    basePath: config.basePath,
+    server: config.server,
+    auth: config.auth,
+    document: v3Doc
+  };
+}
+function resolveRef(ref, root) {
+  const parts = ref.replace(/^#\//, "").split("/");
+  let current = root;
+  for (const part of parts) {
+    if (current && typeof current === "object" && !Array.isArray(current)) {
+      current = current[part];
+    } else {
+      throw new Error(`Cannot resolve $ref: ${ref}`);
+    }
+  }
+  return current;
+}
+function deepResolveRefs(obj, root, stack = new Set, cache = new Map) {
+  if (obj === null || obj === undefined || typeof obj !== "object")
+    return obj;
+  if (Array.isArray(obj)) {
+    return obj.map((item) => deepResolveRefs(item, root, stack, cache));
+  }
+  const record = obj;
+  if (typeof record.$ref === "string") {
+    const ref = record.$ref;
+    if (cache.has(ref))
+      return cache.get(ref);
+    if (stack.has(ref))
+      return { type: "object", description: "[circular]" };
+    stack.add(ref);
+    const resolved = deepResolveRefs(resolveRef(ref, root), root, stack, cache);
+    stack.delete(ref);
+    cache.set(ref, resolved);
+    return resolved;
+  }
+  const result = {};
+  for (const [key, value] of Object.entries(record)) {
+    result[key] = deepResolveRefs(value, root, stack, cache);
+  }
+  return result;
+}
+function resolveDocument(doc) {
+  const root = doc;
+  return deepResolveRefs(doc, root);
+}
+function convertV2toV3(doc) {
+  const root = doc;
+  const resolved = deepResolveRefs(doc, root);
+  const v3Paths = {};
+  for (const [pathStr, pathItem] of Object.entries(resolved.paths ?? {})) {
+    if (!pathItem)
+      continue;
+    const v3PathItem = {};
+    for (const method of ["get", "post", "put", "delete", "patch"]) {
+      const op = pathItem[method];
+      if (!op)
+        continue;
+      v3PathItem[method] = convertV2Operation(op);
+    }
+    v3Paths[pathStr] = v3PathItem;
+  }
+  return {
+    openapi: "3.0.0",
+    info: resolved.info,
+    paths: v3Paths,
+    tags: resolved.tags ?? []
+  };
+}
+function convertV2Operation(op) {
+  const params = op.parameters ?? [];
+  const v3Params = params.filter((p) => p.in !== "body").map((p) => ({
+    name: p.name,
+    in: p.in,
+    required: p.required ?? false,
+    description: p.description,
+    schema: { type: p.type ?? "string", format: p.format }
+  }));
+  const bodyParam = params.find((p) => p.in === "body");
+  let requestBody;
+  if (bodyParam?.schema) {
+    requestBody = {
+      required: bodyParam.required ?? false,
+      content: {
+        "application/json": {
+          schema: bodyParam.schema
+        }
+      }
+    };
+  }
+  const v3Responses = {};
+  for (const [status, resp] of Object.entries(op.responses ?? {})) {
+    const v2Resp = resp;
+    const v3Resp = {
+      description: v2Resp.description ?? ""
+    };
+    if (v2Resp.schema) {
+      v3Resp.content = {
+        "application/json": {
+          schema: v2Resp.schema
+        }
+      };
+    }
+    v3Responses[status] = v3Resp;
+  }
+  const result = {
+    operationId: op.operationId,
+    summary: op.summary,
+    description: op.description,
+    tags: op.tags,
+    parameters: v3Params,
+    responses: v3Responses
+  };
+  if (requestBody) {
+    result.requestBody = requestBody;
+  }
+  return result;
+}
+var init_openapi = () => {};
+
+// src/lib/api-routes.ts
+import slugify from "slugify";
+function getSpecSlug(spec) {
+  return slugify(spec.name, { lower: true, strict: true });
+}
+var init_api_routes = () => {};
+
+// src/server/build-search-index.ts
+var exports_build_search_index = {};
+__export(exports_build_search_index, {
+  generateSearchIndex: () => generateSearchIndex
+});
+import fs5 from "fs/promises";
+import path10 from "path";
+import matter from "gray-matter";
+function extractHeadings(markdown) {
+  const headingRegex = /^#{1,6}\s+(.+)$/gm;
+  const headings = [];
+  let match;
+  while ((match = headingRegex.exec(markdown)) !== null) {
+    headings.push(match[1].trim());
+  }
+  return headings.join(" ");
+}
+async function scanContent(contentDir) {
+  const docs = [];
+  async function scan(dir, prefix = []) {
+    let entries;
+    try {
+      entries = await fs5.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith(".") || entry.name === "node_modules")
+        continue;
+      const fullPath = path10.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await scan(fullPath, [...prefix, entry.name]);
+        continue;
+      }
+      if (!entry.name.endsWith(".mdx") && !entry.name.endsWith(".md"))
+        continue;
+      const raw = await fs5.readFile(fullPath, "utf-8");
+      const { data: fm, content } = matter(raw);
+      const baseName = entry.name.replace(/\.(mdx|md)$/, "");
+      const slugs = baseName === "index" ? prefix : [...prefix, baseName];
+      const url = slugs.length === 0 ? "/" : "/" + slugs.join("/");
+      docs.push({
+        id: url,
+        url,
+        title: fm.title ?? baseName,
+        content: extractHeadings(content),
+        type: "page"
+      });
+    }
+  }
+  await scan(contentDir);
+  return docs;
+}
+function buildApiDocs() {
+  const config = loadConfig();
+  if (!config.api?.length)
+    return [];
+  const docs = [];
+  const specs = loadApiSpecs(config.api);
+  for (const spec of specs) {
+    const specSlug = getSpecSlug(spec);
+    const paths = spec.document.paths ?? {};
+    for (const [, pathItem] of Object.entries(paths)) {
+      if (!pathItem)
+        continue;
+      for (const method of ["get", "post", "put", "delete", "patch"]) {
+        const op = pathItem[method];
+        if (!op?.operationId)
+          continue;
+        const url = `/apis/${specSlug}/${encodeURIComponent(op.operationId)}`;
+        docs.push({
+          id: url,
+          url,
+          title: `${method.toUpperCase()} ${op.summary ?? op.operationId}`,
+          content: op.description ?? "",
+          type: "api"
+        });
+      }
+    }
+  }
+  return docs;
+}
+async function generateSearchIndex(contentDir, outDir) {
+  const [contentDocs, apiDocs] = await Promise.all([
+    scanContent(contentDir),
+    Promise.resolve(buildApiDocs())
+  ]);
+  const documents = [...contentDocs, ...apiDocs];
+  const outPath = path10.join(outDir, "search-index.json");
+  await fs5.writeFile(outPath, JSON.stringify(documents));
+  return documents.length;
+}
+var init_build_search_index = __esm(() => {
+  init_config();
+  init_openapi();
+  init_api_routes();
 });
 
 // src/server/adapters/vercel.ts
@@ -226,38 +540,38 @@ var exports_vercel = {};
 __export(exports_vercel, {
   buildVercelOutput: () => buildVercelOutput
 });
-import path7 from "path";
-import fs3 from "fs/promises";
+import path11 from "path";
+import fs6 from "fs/promises";
 import { existsSync } from "fs";
 import chalk5 from "chalk";
 async function buildVercelOutput(options) {
   const { distDir, contentDir, projectRoot } = options;
-  const outputDir = path7.resolve(projectRoot, ".vercel/output");
+  const outputDir = path11.resolve(projectRoot, ".vercel/output");
   console.log(chalk5.gray("Generating Vercel output..."));
-  await fs3.rm(outputDir, { recursive: true, force: true });
-  const staticDir = path7.resolve(outputDir, "static");
-  const funcDir = path7.resolve(outputDir, "functions/index.func");
-  await fs3.mkdir(staticDir, { recursive: true });
-  await fs3.mkdir(funcDir, { recursive: true });
-  const clientDir = path7.resolve(distDir, "client");
+  await fs6.rm(outputDir, { recursive: true, force: true });
+  const staticDir = path11.resolve(outputDir, "static");
+  const funcDir = path11.resolve(outputDir, "functions/index.func");
+  await fs6.mkdir(staticDir, { recursive: true });
+  await fs6.mkdir(funcDir, { recursive: true });
+  const clientDir = path11.resolve(distDir, "client");
   await copyDir(clientDir, staticDir);
   console.log(chalk5.gray("  Copied client assets to static/"));
   if (existsSync(contentDir)) {
     await copyContentAssets(contentDir, staticDir);
     console.log(chalk5.gray("  Copied content assets to static/"));
   }
-  const serverDir = path7.resolve(distDir, "server");
+  const serverDir = path11.resolve(distDir, "server");
   await copyDir(serverDir, funcDir);
   console.log(chalk5.gray("  Copied server bundle to functions/"));
-  const templateSrc = path7.resolve(clientDir, "src/server/index.html");
-  await fs3.copyFile(templateSrc, path7.resolve(funcDir, "index.html"));
-  await fs3.writeFile(path7.resolve(funcDir, "package.json"), JSON.stringify({ type: "module" }, null, 2));
-  await fs3.writeFile(path7.resolve(funcDir, ".vc-config.json"), JSON.stringify({
-    runtime: "nodejs22.x",
+  const templateSrc = path11.resolve(clientDir, "src/server/index.html");
+  await fs6.copyFile(templateSrc, path11.resolve(funcDir, "index.html"));
+  await fs6.writeFile(path11.resolve(funcDir, "package.json"), JSON.stringify({ type: "module" }, null, 2));
+  await fs6.writeFile(path11.resolve(funcDir, ".vc-config.json"), JSON.stringify({
+    runtime: "nodejs24.x",
     handler: "entry-vercel.js",
     launcherType: "Nodejs"
   }, null, 2));
-  await fs3.writeFile(path7.resolve(outputDir, "config.json"), JSON.stringify({
+  await fs6.writeFile(path11.resolve(outputDir, "config.json"), JSON.stringify({
     version: 3,
     routes: [
       { handle: "filesystem" },
@@ -267,44 +581,44 @@ async function buildVercelOutput(options) {
   console.log(chalk5.green("Vercel output generated →"), outputDir);
 }
 async function copyDir(src, dest) {
-  await fs3.mkdir(dest, { recursive: true });
-  const entries = await fs3.readdir(src, { withFileTypes: true });
+  await fs6.mkdir(dest, { recursive: true });
+  const entries = await fs6.readdir(src, { withFileTypes: true });
   for (const entry of entries) {
-    const srcPath = path7.join(src, entry.name);
-    const destPath = path7.join(dest, entry.name);
+    const srcPath = path11.join(src, entry.name);
+    const destPath = path11.join(dest, entry.name);
     if (entry.isDirectory()) {
       await copyDir(srcPath, destPath);
     } else {
-      await fs3.copyFile(srcPath, destPath);
+      await fs6.copyFile(srcPath, destPath);
     }
   }
 }
 async function copyContentAssets(contentDir, staticDir) {
-  const entries = await fs3.readdir(contentDir, { withFileTypes: true });
+  const entries = await fs6.readdir(contentDir, { withFileTypes: true });
   for (const entry of entries) {
-    const srcPath = path7.join(contentDir, entry.name);
+    const srcPath = path11.join(contentDir, entry.name);
     if (entry.isDirectory()) {
-      const destSubDir = path7.join(staticDir, entry.name);
+      const destSubDir = path11.join(staticDir, entry.name);
       await copyContentAssetsRecursive(srcPath, destSubDir);
     } else {
-      const ext = path7.extname(entry.name).toLowerCase();
+      const ext = path11.extname(entry.name).toLowerCase();
       if (CONTENT_EXTENSIONS.has(ext)) {
-        await fs3.copyFile(srcPath, path7.join(staticDir, entry.name));
+        await fs6.copyFile(srcPath, path11.join(staticDir, entry.name));
       }
     }
   }
 }
 async function copyContentAssetsRecursive(srcDir, destDir) {
-  const entries = await fs3.readdir(srcDir, { withFileTypes: true });
+  const entries = await fs6.readdir(srcDir, { withFileTypes: true });
   for (const entry of entries) {
-    const srcPath = path7.join(srcDir, entry.name);
+    const srcPath = path11.join(srcDir, entry.name);
     if (entry.isDirectory()) {
-      await copyContentAssetsRecursive(srcPath, path7.join(destDir, entry.name));
+      await copyContentAssetsRecursive(srcPath, path11.join(destDir, entry.name));
     } else {
-      const ext = path7.extname(entry.name).toLowerCase();
+      const ext = path11.extname(entry.name).toLowerCase();
       if (CONTENT_EXTENSIONS.has(ext)) {
-        await fs3.mkdir(destDir, { recursive: true });
-        await fs3.copyFile(srcPath, path7.join(destDir, entry.name));
+        await fs6.mkdir(destDir, { recursive: true });
+        await fs6.copyFile(srcPath, path11.join(destDir, entry.name));
       }
     }
   }
@@ -332,11 +646,11 @@ var exports_prod = {};
 __export(exports_prod, {
   startProdServer: () => startProdServer
 });
-import path9 from "path";
+import path13 from "path";
 import chalk7 from "chalk";
 async function startProdServer(options) {
   const { port, distDir } = options;
-  const serverEntry = path9.resolve(distDir, "server/entry-prod.js");
+  const serverEntry = path13.resolve(distDir, "server/entry-prod.js");
   const { startServer } = await import(serverEntry);
   console.log(chalk7.cyan("Starting production server..."));
   return startServer({ port, distDir });
@@ -548,11 +862,16 @@ var devCommand = new Command2("dev").description("Start development server").opt
 
 // src/cli/commands/build.ts
 import { Command as Command3 } from "commander";
-import path8 from "path";
+import path12 from "path";
 import chalk6 from "chalk";
 var buildCommand = new Command3("build").description("Build for production").option("-c, --content <path>", "Content directory").option("-o, --outDir <path>", "Output directory", "dist").option("--adapter <adapter>", "Deploy adapter (vercel)").action(async (options) => {
   const contentDir = resolveContentDir(options.content);
-  const outDir = path8.resolve(options.outDir);
+  const outDir = path12.resolve(options.outDir);
+  const VALID_ADAPTERS = ["vercel"];
+  if (options.adapter && !VALID_ADAPTERS.includes(options.adapter)) {
+    console.error(chalk6.red(`Unknown adapter: ${options.adapter}. Valid adapters: ${VALID_ADAPTERS.join(", ")}`));
+    process.exit(1);
+  }
   process.env.CHRONICLE_PROJECT_ROOT = process.cwd();
   process.env.CHRONICLE_CONTENT_DIR = contentDir;
   console.log(chalk6.cyan("Building for production..."));
@@ -563,14 +882,14 @@ var buildCommand = new Command3("build").description("Build for production").opt
   await build({
     ...baseConfig,
     build: {
-      outDir: path8.join(outDir, "client"),
+      outDir: path12.join(outDir, "client"),
       ssrManifest: true,
       rolldownOptions: {
-        input: path8.resolve(PACKAGE_ROOT, "src/server/index.html")
+        input: path12.resolve(PACKAGE_ROOT, "src/server/index.html")
       }
     }
   });
-  const serverEntry = options.adapter === "vercel" ? path8.resolve(PACKAGE_ROOT, "src/server/entry-vercel.ts") : path8.resolve(PACKAGE_ROOT, "src/server/entry-prod.ts");
+  const serverEntry = options.adapter === "vercel" ? path12.resolve(PACKAGE_ROOT, "src/server/entry-vercel.ts") : path12.resolve(PACKAGE_ROOT, "src/server/entry-prod.ts");
   console.log(chalk6.gray("Building server..."));
   await build({
     ...baseConfig,
@@ -578,10 +897,15 @@ var buildCommand = new Command3("build").description("Build for production").opt
       noExternal: true
     },
     build: {
-      outDir: path8.join(outDir, "server"),
-      ssr: serverEntry
+      outDir: path12.join(outDir, "server"),
+      ssr: serverEntry,
+      target: "node22"
     }
   });
+  console.log(chalk6.gray("Building search index..."));
+  const { generateSearchIndex: generateSearchIndex2 } = await Promise.resolve().then(() => (init_build_search_index(), exports_build_search_index));
+  const docCount = await generateSearchIndex2(contentDir, path12.join(outDir, "server"));
+  console.log(chalk6.gray(`  Indexed ${docCount} documents`));
   console.log(chalk6.green("Build complete →"), outDir);
   if (options.adapter === "vercel") {
     const { buildVercelOutput: buildVercelOutput2 } = await Promise.resolve().then(() => (init_vercel(), exports_vercel));
@@ -595,12 +919,12 @@ var buildCommand = new Command3("build").description("Build for production").opt
 
 // src/cli/commands/start.ts
 import { Command as Command4 } from "commander";
-import path10 from "path";
+import path14 from "path";
 import chalk8 from "chalk";
 var startCommand = new Command4("start").description("Start production server").option("-p, --port <port>", "Port number", "3000").option("-c, --content <path>", "Content directory").option("-d, --dist <path>", "Dist directory", "dist").action(async (options) => {
   const contentDir = resolveContentDir(options.content);
   const port = parseInt(options.port, 10);
-  const distDir = path10.resolve(options.dist);
+  const distDir = path14.resolve(options.dist);
   process.env.CHRONICLE_PROJECT_ROOT = process.cwd();
   process.env.CHRONICLE_CONTENT_DIR = contentDir;
   console.log(chalk8.cyan("Starting production server..."));
@@ -610,12 +934,12 @@ var startCommand = new Command4("start").description("Start production server").
 
 // src/cli/commands/serve.ts
 import { Command as Command5 } from "commander";
-import path11 from "path";
+import path15 from "path";
 import chalk9 from "chalk";
 var serveCommand = new Command5("serve").description("Build and start production server").option("-p, --port <port>", "Port number", "3000").option("-c, --content <path>", "Content directory").option("-o, --outDir <path>", "Output directory", "dist").action(async (options) => {
   const contentDir = resolveContentDir(options.content);
   const port = parseInt(options.port, 10);
-  const outDir = path11.resolve(options.outDir);
+  const outDir = path15.resolve(options.outDir);
   process.env.CHRONICLE_PROJECT_ROOT = process.cwd();
   process.env.CHRONICLE_CONTENT_DIR = contentDir;
   console.log(chalk9.cyan("Building for production..."));
@@ -625,10 +949,10 @@ var serveCommand = new Command5("serve").description("Build and start production
   await build({
     ...baseConfig,
     build: {
-      outDir: path11.join(outDir, "client"),
+      outDir: path15.join(outDir, "client"),
       ssrManifest: true,
       rolldownOptions: {
-        input: path11.resolve(PACKAGE_ROOT, "src/server/index.html")
+        input: path15.resolve(PACKAGE_ROOT, "src/server/index.html")
       }
     }
   });
@@ -638,8 +962,8 @@ var serveCommand = new Command5("serve").description("Build and start production
       noExternal: true
     },
     build: {
-      outDir: path11.join(outDir, "server"),
-      ssr: path11.resolve(PACKAGE_ROOT, "src/server/entry-prod.ts")
+      outDir: path15.join(outDir, "server"),
+      ssr: path15.resolve(PACKAGE_ROOT, "src/server/entry-prod.ts")
     }
   });
   console.log(chalk9.cyan("Starting production server..."));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raystack/chronicle",
-  "version": "0.1.0-canary.a638730",
+  "version": "0.1.0-canary.cb102e9",
   "description": "Config-driven documentation framework",
   "license": "Apache-2.0",
   "type": "module",

package/src/cli/commands/build.ts

@@ -13,6 +13,12 @@ export const buildCommand = new Command('build')
     const contentDir = resolveContentDir(options.content)
     const outDir = path.resolve(options.outDir)
 
+    const VALID_ADAPTERS = ['vercel']
+    if (options.adapter && !VALID_ADAPTERS.includes(options.adapter)) {
+      console.error(chalk.red(`Unknown adapter: ${options.adapter}. Valid adapters: ${VALID_ADAPTERS.join(', ')}`))
+      process.exit(1)
+    }
+
     process.env.CHRONICLE_PROJECT_ROOT = process.cwd()
     process.env.CHRONICLE_CONTENT_DIR = contentDir
 
@@ -50,9 +56,16 @@ export const buildCommand = new Command('build')
       build: {
         outDir: path.join(outDir, 'server'),
         ssr: serverEntry,
+        target: 'node22',
       },
     })
 
+    // Generate search index
+    console.log(chalk.gray('Building search index...'))
+    const { generateSearchIndex } = await import('@/server/build-search-index')
+    const docCount = await generateSearchIndex(contentDir, path.join(outDir, 'server'))
+    console.log(chalk.gray(`  Indexed ${docCount} documents`))
+
     console.log(chalk.green('Build complete →'), outDir)
 
     // Run Vercel adapter post-build

package/src/components/ui/search.tsx

@@ -18,23 +18,27 @@ interface SearchResult {
 function useSearch(query: string) {
   const [results, setResults] = useState<SearchResult[]>([]);
   const [isLoading, setIsLoading] = useState(false);
-  const timerRef = useRef<ReturnType<typeof setTimeout>>();
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
   useEffect(() => {
-    clearTimeout(timerRef.current);
+    let cancelled = false;
+    if (timerRef.current) clearTimeout(timerRef.current);
     timerRef.current = setTimeout(async () => {
       setIsLoading(true);
       try {
         const params = new URLSearchParams();
         if (query) params.set("query", query);
         const res = await fetch(`/api/search?${params}`);
-        setResults(await res.json());
+        if (!cancelled) setResults(await res.json());
       } catch {
-        setResults([]);
+        if (!cancelled) setResults([]);
       }
-      setIsLoading(false);
+      if (!cancelled) setIsLoading(false);
     }, 100);
-    return () => clearTimeout(timerRef.current);
+    return () => {
+      cancelled = true;
+      if (timerRef.current) clearTimeout(timerRef.current);
+    };
   }, [query]);
 
   return { results, isLoading };

package/src/server/adapters/vercel.ts

@@ -59,7 +59,7 @@ export async function buildVercelOutput(options: VercelAdapterOptions) {
   await fs.writeFile(
     path.resolve(funcDir, '.vc-config.json'),
     JSON.stringify({
-      runtime: 'nodejs22.x',
+      runtime: 'nodejs24.x',
       handler: 'entry-vercel.js',
       launcherType: 'Nodejs',
     }, null, 2),

package/src/server/build-search-index.ts

@@ -0,0 +1,107 @@
+import fs from 'fs/promises'
+import path from 'path'
+import matter from 'gray-matter'
+import { loadConfig } from '@/lib/config'
+import { loadApiSpecs } from '@/lib/openapi'
+import { getSpecSlug } from '@/lib/api-routes'
+import type { OpenAPIV3 } from 'openapi-types'
+
+interface SearchDocument {
+  id: string
+  url: string
+  title: string
+  content: string
+  type: 'page' | 'api'
+}
+
+function extractHeadings(markdown: string): string {
+  const headingRegex = /^#{1,6}\s+(.+)$/gm
+  const headings: string[] = []
+  let match
+  while ((match = headingRegex.exec(markdown)) !== null) {
+    headings.push(match[1].trim())
+  }
+  return headings.join(' ')
+}
+
+async function scanContent(contentDir: string): Promise<SearchDocument[]> {
+  const docs: SearchDocument[] = []
+
+  async function scan(dir: string, prefix: string[] = []) {
+    let entries
+    try { entries = await fs.readdir(dir, { withFileTypes: true }) }
+    catch { return }
+
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') || entry.name === 'node_modules') continue
+      const fullPath = path.join(dir, entry.name)
+
+      if (entry.isDirectory()) {
+        await scan(fullPath, [...prefix, entry.name])
+        continue
+      }
+
+      if (!entry.name.endsWith('.mdx') && !entry.name.endsWith('.md')) continue
+
+      const raw = await fs.readFile(fullPath, 'utf-8')
+      const { data: fm, content } = matter(raw)
+      const baseName = entry.name.replace(/\.(mdx|md)$/, '')
+      const slugs = baseName === 'index' ? prefix : [...prefix, baseName]
+      const url = slugs.length === 0 ? '/' : '/' + slugs.join('/')
+
+      docs.push({
+        id: url,
+        url,
+        title: fm.title ?? baseName,
+        content: extractHeadings(content),
+        type: 'page',
+      })
+    }
+  }
+
+  await scan(contentDir)
+  return docs
+}
+
+function buildApiDocs(): SearchDocument[] {
+  const config = loadConfig()
+  if (!config.api?.length) return []
+
+  const docs: SearchDocument[] = []
+  const specs = loadApiSpecs(config.api)
+
+  for (const spec of specs) {
+    const specSlug = getSpecSlug(spec)
+    const paths = spec.document.paths ?? {}
+    for (const [, pathItem] of Object.entries(paths)) {
+      if (!pathItem) continue
+      for (const method of ['get', 'post', 'put', 'delete', 'patch'] as const) {
+        const op = pathItem[method] as OpenAPIV3.OperationObject | undefined
+        if (!op?.operationId) continue
+        const url = `/apis/${specSlug}/${encodeURIComponent(op.operationId)}`
+        docs.push({
+          id: url,
+          url,
+          title: `${method.toUpperCase()} ${op.summary ?? op.operationId}`,
+          content: op.description ?? '',
+          type: 'api',
+        })
+      }
+    }
+  }
+
+  return docs
+}
+
+export async function generateSearchIndex(contentDir: string, outDir: string) {
+  const [contentDocs, apiDocs] = await Promise.all([
+    scanContent(contentDir),
+    Promise.resolve(buildApiDocs()),
+  ])
+
+  const documents = [...contentDocs, ...apiDocs]
+  const outPath = path.join(outDir, 'search-index.json')
+  await fs.writeFile(outPath, JSON.stringify(documents))
+
+  return documents.length
+}

package/src/server/dev.ts

@@ -5,6 +5,7 @@ import { createReadStream } from 'fs'
 import path from 'path'
 import chalk from 'chalk'
 import { createViteConfig } from './vite-config'
+import { safePath } from './utils/safe-path'
 
 export interface DevServerOptions {
   port: number
@@ -38,8 +39,8 @@ export async function startDevServer(options: DevServerOptions) {
       }
 
       // Serve static files from content dir (skip .md/.mdx)
-      const contentFile = path.join(contentDir, decodeURIComponent(url.split('?')[0]))
-      if (!url.endsWith('.md') && !url.endsWith('.mdx')) {
+      const contentFile = safePath(contentDir, url)
+      if (contentFile && !url.endsWith('.md') && !url.endsWith('.mdx')) {
         try {
           const stat = await fsPromises.stat(contentFile)
           if (stat.isFile()) {
@@ -119,7 +120,8 @@ export async function startDevServer(options: DevServerOptions) {
       template = await vite.transformIndexHtml(url, template)
 
       // Embed page data for client hydration
-      const dataScript = `<script>window.__PAGE_DATA__ = ${JSON.stringify(embeddedData)}</script>`
+      const safeJson = JSON.stringify(embeddedData).replace(/</g, '\\u003c')
+      const dataScript = `<script>window.__PAGE_DATA__ = ${safeJson}</script>`
       template = template.replace('<!--head-outlet-->', `<!--head-outlet-->${dataScript}`)
 
       const { render } = await vite.ssrLoadModule(path.resolve(root, 'src/server/entry-server.tsx'))

package/src/server/entry-prod.ts

@@ -9,6 +9,7 @@ import { loadConfig } from '@/lib/config'
 import { loadApiSpecs } from '@/lib/openapi'
 import { getPage, loadPageComponent, buildPageTree } from '@/lib/source'
 import { handleRequest } from './request-handler'
+import { safePath } from './utils/safe-path'
 
 export { render, matchRoute, loadConfig, loadApiSpecs, getPage, loadPageComponent, buildPageTree }
 
@@ -45,8 +46,8 @@ export async function startServer(options: { port: number; distDir: string }) {
 
       // Serve static files from content dir (skip .md/.mdx)
       const contentDir = process.env.CHRONICLE_CONTENT_DIR || process.cwd()
-      const contentFile = path.join(contentDir, decodeURIComponent(url.split('?')[0]))
-      if (!url.endsWith('.md') && !url.endsWith('.mdx')) {
+      const contentFile = safePath(contentDir, url)
+      if (contentFile && !url.endsWith('.md') && !url.endsWith('.mdx')) {
         try {
           const stat = await fsPromises.stat(contentFile)
           if (stat.isFile()) {
@@ -77,7 +78,7 @@ export async function startServer(options: { port: number; distDir: string }) {
     } catch (e) {
       console.error(e)
       res.statusCode = 500
-      res.end((e as Error).message)
+      res.end('Internal Server Error')
     }
   })
 

package/src/server/entry-vercel.ts

@@ -1,9 +1,11 @@
 // Vercel serverless function entry — built by Vite, deployed as catch-all function
 import type { IncomingMessage, ServerResponse } from 'http'
 import { readFileSync } from 'fs'
+import { fileURLToPath } from 'url'
 import path from 'path'
 import { handleRequest } from './request-handler'
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const templatePath = path.resolve(__dirname, 'index.html')
 const template = readFileSync(templatePath, 'utf-8')
 
@@ -21,6 +23,6 @@ export default async function handler(req: IncomingMessage, res: ServerResponse)
   } catch (e) {
     console.error(e)
     res.statusCode = 500
-    res.end((e as Error).message)
+    res.end('Internal Server Error')
   }
 }

package/src/server/handlers/apis-proxy.ts

@@ -20,6 +20,11 @@ export async function handleApisProxy(req: Request): Promise<Response> {
     return Response.json({ error: `Unknown spec: ${specName}` }, { status: 404 })
   }
 
+  // Validate path doesn't contain protocol or escape the base URL
+  if (/^[a-z]+:\/\//i.test(path) || path.includes('..')) {
+    return Response.json({ error: 'Invalid path' }, { status: 400 })
+  }
+
   const url = spec.server.url + path
 
   try {

package/src/server/handlers/search.ts

@@ -16,7 +16,35 @@ interface SearchDocument {
 }
 
 let searchIndex: MiniSearch<SearchDocument> | null = null
+let cachedDocs: SearchDocument[] | null = null
 
+function createIndex(docs: SearchDocument[]): MiniSearch<SearchDocument> {
+  const index = new MiniSearch<SearchDocument>({
+    fields: ['title', 'content'],
+    storeFields: ['url', 'title', 'type'],
+    searchOptions: {
+      boost: { title: 2 },
+      fuzzy: 0.2,
+      prefix: true,
+    },
+  })
+  index.addAll(docs)
+  return index
+}
+
+// Try loading pre-built search index (generated at build time)
+async function loadPrebuiltIndex(): Promise<SearchDocument[] | null> {
+  try {
+    // In bundled server, search-index.json is next to the entry file
+    const indexPath = path.resolve(__dirname, 'search-index.json')
+    const raw = await fs.readFile(indexPath, 'utf-8')
+    return JSON.parse(raw)
+  } catch {
+    return null
+  }
+}
+
+// Fallback: scan filesystem at runtime (dev mode)
 function getContentDir(): string {
   return process.env.CHRONICLE_CONTENT_DIR || path.join(process.cwd(), 'content')
 }
@@ -91,25 +119,29 @@ function buildApiDocs(): SearchDocument[] {
   return docs
 }
 
-async function getIndex(): Promise<MiniSearch<SearchDocument>> {
-  if (searchIndex) return searchIndex
+async function loadDocuments(): Promise<SearchDocument[]> {
+  // Try pre-built index first
+  const prebuilt = await loadPrebuiltIndex()
+  if (prebuilt) return prebuilt
 
+  // Fallback to filesystem scanning (dev mode)
   const [contentDocs, apiDocs] = await Promise.all([
     scanContent(),
     Promise.resolve(buildApiDocs()),
   ])
+  return [...contentDocs, ...apiDocs]
+}
 
-  searchIndex = new MiniSearch<SearchDocument>({
-    fields: ['title', 'content'],
-    storeFields: ['url', 'title', 'type'],
-    searchOptions: {
-      boost: { title: 2 },
-      fuzzy: 0.2,
-      prefix: true,
-    },
-  })
+async function getDocs(): Promise<SearchDocument[]> {
+  if (cachedDocs) return cachedDocs
+  cachedDocs = await loadDocuments()
+  return cachedDocs
+}
 
-  searchIndex.addAll([...contentDocs, ...apiDocs])
+async function getIndex(): Promise<MiniSearch<SearchDocument>> {
+  if (searchIndex) return searchIndex
+  const docs = await getDocs()
+  searchIndex = createIndex(docs)
   return searchIndex
 }
 
@@ -119,8 +151,8 @@ export async function handleSearch(req: Request): Promise<Response> {
   const index = await getIndex()
 
   if (!query) {
-    const contentDocs = await scanContent()
-    const suggestions = contentDocs.slice(0, 8).map((d) => ({
+    const docs = await getDocs()
+    const suggestions = docs.filter(d => d.type === 'page').slice(0, 8).map((d) => ({
       id: d.id,
       url: d.url,
       type: d.type,

package/src/server/request-handler.ts

@@ -51,7 +51,8 @@ export async function handleRequest(url: string, options: RequestHandlerOptions)
 
   const html = render(url, { config, tree, page: pageData, apiSpecs })
 
-  const dataScript = `<script>window.__PAGE_DATA__ = ${JSON.stringify(embeddedData)}</script>`
+  const safeJson = JSON.stringify(embeddedData).replace(/</g, '\\u003c')
+  const dataScript = `<script>window.__PAGE_DATA__ = ${safeJson}</script>`
   const finalHtml = template
     .replace('<!--head-outlet-->', `<!--head-outlet-->${dataScript}`)
     .replace('<!--ssr-outlet-->', html)

package/src/server/utils/safe-path.ts

@@ -0,0 +1,14 @@
+import path from 'path'
+
+/**
+ * Resolve a URL path within a base directory, preventing path traversal.
+ * Returns null if the resolved path escapes the base directory.
+ */
+export function safePath(baseDir: string, urlPath: string): string | null {
+  const decoded = decodeURIComponent(urlPath.split('?')[0])
+  const resolved = path.resolve(baseDir, '.' + decoded)
+  if (!resolved.startsWith(path.resolve(baseDir) + path.sep) && resolved !== path.resolve(baseDir)) {
+    return null
+  }
+  return resolved
+}