fastscript 1.0.0 → 2.0.0

package/node_modules/@fastscript/core-private/src/deploy.mjs

@@ -0,0 +1,662 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { runBuild } from "./build.mjs";
+import { buildStylePrimitiveServerSource, transformStylePrimitives } from "./style-primitives.mjs";
+
+function parseArgs(args = []) {
+  let target = "node";
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === "--target") target = (args[i + 1] || "node").toLowerCase();
+  }
+  return { target };
+}
+
+async function ensureBuildArtifacts(root) {
+  const manifestPath = join(root, "dist", "fastscript-manifest.json");
+  if (existsSync(manifestPath)) return;
+  await runBuild();
+}
+
+function writeNodeAdapter(root) {
+  writeFileSync(
+    join(root, "ecosystem.config.cjs"),
+    `module.exports = {
+  apps: [{
+    name: "fastscript-app",
+    script: "node",
+    args: "./src/cli.mjs start",
+    instances: "max",
+    exec_mode: "cluster",
+    env: {
+      NODE_ENV: "production",
+      PORT: 4173
+    }
+  }]
+};
+`,
+    "utf8",
+  );
+  writeFileSync(
+    join(root, "Dockerfile"),
+    `FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --omit=dev
+COPY . .
+RUN npm run build
+ENV NODE_ENV=production
+ENV PORT=4173
+EXPOSE 4173
+HEALTHCHECK --interval=30s --timeout=5s CMD wget -q -O /dev/null http://127.0.0.1:4173/__metrics || exit 1
+CMD ["node","./src/cli.mjs","start"]
+`,
+    "utf8",
+  );
+}
+
+function writeVercelAdapter(root) {
+  mkdirSync(join(root, "api"), { recursive: true });
+  writeFileSync(
+    join(root, "api", "[[...fastscript]].mjs"),
+    `import handler from "../src/serverless-handler.mjs";
+export default handler;
+`,
+    "utf8",
+  );
+  writeFileSync(
+    join(root, "vercel.json"),
+    JSON.stringify(
+      {
+        version: 2,
+        cleanUrls: false,
+        trailingSlash: false,
+        functions: {
+          "api/[[...fastscript]].mjs": {
+            runtime: "nodejs20.x",
+            maxDuration: 30,
+            memory: 1024,
+          },
+        },
+        headers: [
+          {
+            source: "/(.*)",
+            headers: [
+              { key: "x-content-type-options", value: "nosniff" },
+              { key: "x-frame-options", value: "SAMEORIGIN" },
+              { key: "referrer-policy", value: "strict-origin-when-cross-origin" },
+            ],
+          },
+          {
+            source: "/(.*\\.[a-f0-9]{8}\\.(js|css))",
+            headers: [{ key: "cache-control", value: "public, max-age=31536000, immutable" }],
+          },
+          {
+            source: "/(.*\\.(woff|woff2|ttf|otf|svg|png|jpg|jpeg|gif|webp|avif))",
+            headers: [{ key: "cache-control", value: "public, max-age=31536000, immutable" }],
+          },
+          {
+            source: "/(fastscript-manifest\\.json|asset-manifest\\.json|manifest\\.webmanifest)",
+            headers: [{ key: "cache-control", value: "no-store, max-age=0" }],
+          },
+          {
+            source: "/service-worker\\.js",
+            headers: [{ key: "cache-control", value: "no-cache, max-age=0" }],
+          },
+        ],
+        routes: [
+          { src: "/(.*\\.(js|css|json|map|webmanifest|png|jpg|jpeg|svg|gif|woff|woff2|ttf|otf))", dest: "/dist/$1" },
+          { src: "/service-worker.js", dest: "/dist/service-worker.js" },
+          { src: "/manifest.webmanifest", dest: "/dist/manifest.webmanifest" },
+          { src: "/fastscript-manifest.json", dest: "/dist/fastscript-manifest.json" },
+          { src: "/asset-manifest.json", dest: "/dist/asset-manifest.json" },
+          { src: "/(.*)", dest: "/api/[[...fastscript]].mjs" },
+        ],
+      },
+      null,
+      2,
+    ),
+    "utf8",
+  );
+
+  writeFileSync(
+    join(root, "vercel.env.example"),
+    `# FastScript production defaults
+NODE_ENV=production
+PORT=4173
+FASTSCRIPT_DEPLOY_TARGET=vercel
+
+# Optional drivers
+# DB_DRIVER=postgres
+# DATABASE_URL=postgres://...
+# CACHE_DRIVER=redis
+# REDIS_URL=redis://...
+# STORAGE_DRIVER=s3
+# STORAGE_S3_BUCKET=...
+# STORAGE_S3_ENDPOINT=...
+# STORAGE_S3_PRESIGN_BASE_URL=...
+`,
+    "utf8",
+  );
+}
+
+function collectCloudflareModules(manifest) {
+  const modules = new Set();
+  for (const route of manifest.routes || []) modules.add(route.module);
+  for (const route of manifest.parallelRoutes || []) modules.add(route.module);
+  for (const route of manifest.apiRoutes || []) modules.add(route.module);
+  for (const route of manifest.routes || []) {
+    for (const layout of route.layouts || []) modules.add(layout);
+  }
+  if (manifest.layout) modules.add(manifest.layout);
+  if (manifest.notFound) modules.add(manifest.notFound);
+  if (manifest.middleware) modules.add(manifest.middleware);
+  return [...modules].filter(Boolean).sort();
+}
+
+function buildCloudflareWorkerSource({ manifest, assetMap }) {
+  const modulePaths = collectCloudflareModules(manifest);
+  const imports = [];
+  const moduleEntries = [];
+  modulePaths.forEach((modulePath, index) => {
+    const alias = `m${index}`;
+    const spec = `./${String(modulePath).replace(/^\.\//, "")}`;
+    imports.push(`import * as ${alias} from "${spec}";`);
+    moduleEntries.push(`  "${modulePath}": ${alias}`);
+  });
+
+  const lines = [];
+  lines.push(...imports);
+  lines.push("");
+  lines.push(`const MODULES = {\n${moduleEntries.join(",\n")}\n};`);
+  lines.push(`const MANIFEST = ${JSON.stringify(manifest, null, 2)};`);
+  lines.push(`const ASSET_MAP = ${JSON.stringify(assetMap || {}, null, 2)};`);
+  lines.push(buildStylePrimitiveServerSource());
+  lines.push(`
+function moduleFor(path) {
+  return MODULES[path] || null;
+}
+
+function assetPath(name) {
+  return "/" + (ASSET_MAP[name] || name);
+}
+
+function parseRouteToken(token) {
+  const m = /^:([A-Za-z_$][\\w$]*)(\\*)?(\\?)?$/.exec(token || "");
+  if (!m) return null;
+  return { name: m[1], catchAll: Boolean(m[2]), optional: Boolean(m[3]) };
+}
+
+function match(routePath, pathname) {
+  const routeParts = String(routePath || "/").split("/").filter(Boolean);
+  const pathParts = String(pathname || "/").split("/").filter(Boolean);
+  const params = {};
+  let ri = 0;
+  let pi = 0;
+
+  while (ri < routeParts.length) {
+    const token = routeParts[ri];
+    const dyn = parseRouteToken(token);
+    if (dyn && dyn.catchAll) {
+      const rest = pathParts.slice(pi);
+      if (!rest.length && !dyn.optional) return null;
+      params[dyn.name] = rest;
+      pi = pathParts.length;
+      ri = routeParts.length;
+      break;
+    }
+    if (dyn) {
+      const value = pathParts[pi];
+      if (value === undefined) {
+        if (dyn.optional) {
+          params[dyn.name] = undefined;
+          ri += 1;
+          continue;
+        }
+        return null;
+      }
+      params[dyn.name] = value;
+      ri += 1;
+      pi += 1;
+      continue;
+    }
+    if (pathParts[pi] !== token) return null;
+    ri += 1;
+    pi += 1;
+  }
+
+  if (pi !== pathParts.length) return null;
+  return params;
+}
+
+function routePriorityScore(routePath) {
+  const parts = String(routePath || "/").split("/").filter(Boolean);
+  if (!parts.length) return 1000;
+  let score = parts.length;
+  for (const part of parts) {
+    const dyn = parseRouteToken(part);
+    if (!dyn) score += 40;
+    else if (dyn.catchAll && dyn.optional) score += 5;
+    else if (dyn.catchAll) score += 10;
+    else if (dyn.optional) score += 20;
+    else score += 30;
+  }
+  return score;
+}
+
+function resolveRoute(routes, pathname) {
+  let best = null;
+  for (const route of routes || []) {
+    const params = match(route.path, pathname);
+    if (!params) continue;
+    if (!best) {
+      best = { route, params, score: routePriorityScore(route.path) };
+      continue;
+    }
+    const score = routePriorityScore(route.path);
+    if (score > best.score) best = { route, params, score };
+  }
+  return best ? { route: best.route, params: best.params } : null;
+}
+
+function parseCookies(header) {
+  const out = {};
+  String(header || "").split(";").forEach((part) => {
+    const idx = part.indexOf("=");
+    if (idx <= 0) return;
+    const key = decodeURIComponent(part.slice(0, idx).trim());
+    const value = decodeURIComponent(part.slice(idx + 1).trim());
+    out[key] = value;
+  });
+  return out;
+}
+
+function serializeCookie(name, value, opts = {}) {
+  const segs = [\`\${encodeURIComponent(name)}=\${encodeURIComponent(value)}\`];
+  if (opts.maxAge !== undefined) segs.push(\`Max-Age=\${Number(opts.maxAge)}\`);
+  if (opts.path) segs.push(\`Path=\${opts.path}\`);
+  if (opts.httpOnly) segs.push("HttpOnly");
+  if (opts.secure) segs.push("Secure");
+  if (opts.sameSite) segs.push(\`SameSite=\${opts.sameSite}\`);
+  return segs.join("; ");
+}
+
+async function readJsonBody(request) {
+  const text = await request.text();
+  if (!text.trim()) return {};
+  try { return JSON.parse(text); }
+  catch {
+    const error = new Error("Invalid JSON body");
+    error.status = 400;
+    throw error;
+  }
+}
+
+function validateShape(schema, input, scope = "input") {
+  if (!schema || typeof schema !== "object") return { ok: true, value: input ?? {} };
+  const errors = [];
+  const out = {};
+  const source = input && typeof input === "object" ? input : {};
+  for (const [key, rule] of Object.entries(schema)) {
+    const value = source[key];
+    const optional = typeof rule === "string" && rule.endsWith("?");
+    const t = typeof rule === "string" ? rule.replace(/\\?$/, "") : String(rule);
+    if (value === undefined || value === null) {
+      if (!optional) errors.push(\`\${scope}.\${key} is required\`);
+      continue;
+    }
+    if (t === "array") {
+      if (!Array.isArray(value)) errors.push(\`\${scope}.\${key} must be array\`);
+      else out[key] = value;
+      continue;
+    }
+    if (t === "int") {
+      const n = Number(value);
+      if (!Number.isInteger(n)) errors.push(\`\${scope}.\${key} must be integer\`);
+      else out[key] = n;
+      continue;
+    }
+    if (t === "float" || t === "number") {
+      const n = Number(value);
+      if (!Number.isFinite(n)) errors.push(\`\${scope}.\${key} must be number\`);
+      else out[key] = n;
+      continue;
+    }
+    if (t === "bool" || t === "boolean") {
+      if (typeof value !== "boolean") errors.push(\`\${scope}.\${key} must be boolean\`);
+      else out[key] = value;
+      continue;
+    }
+    if (t === "str" || t === "string") {
+      if (typeof value !== "string") errors.push(\`\${scope}.\${key} must be string\`);
+      else out[key] = value;
+      continue;
+    }
+    out[key] = value;
+  }
+  if (errors.length) {
+    const error = new Error(\`Validation failed: \${errors.join("; ")}\`);
+    error.status = 400;
+    error.details = errors;
+    throw error;
+  }
+  return { ok: true, value: out };
+}
+
+function makeHelpers(responseCookies) {
+  return {
+    json(body, status = 200, headers = {}) {
+      return { status, json: body, headers };
+    },
+    text(body, status = 200, headers = {}) {
+      return { status, body, headers };
+    },
+    redirect(location, status = 302) {
+      return { status, headers: { location } };
+    },
+    setCookie(name, value, opts = {}) {
+      responseCookies.push(serializeCookie(name, value, opts));
+    }
+  };
+}
+
+function applySecurityHeaders(headers) {
+  headers.set("x-content-type-options", "nosniff");
+  headers.set("x-frame-options", "SAMEORIGIN");
+  headers.set("referrer-policy", "strict-origin-when-cross-origin");
+  return headers;
+}
+
+function toResponse(payload, responseCookies = []) {
+  if (!payload) return new Response(null, { status: 204 });
+  const status = payload.status ?? 200;
+  const headers = applySecurityHeaders(new Headers(payload.headers || {}));
+  for (const cookie of responseCookies) headers.append("set-cookie", cookie);
+  if (payload.json !== undefined) {
+    headers.set("content-type", "application/json; charset=utf-8");
+    return new Response(JSON.stringify(payload.json), { status, headers });
+  }
+  if (!headers.has("content-type")) headers.set("content-type", "text/plain; charset=utf-8");
+  return new Response(payload.body ?? "", { status, headers });
+}
+
+function htmlDoc(content, ssrData) {
+  const safe = JSON.stringify(ssrData ?? {}).replace(/</g, "\\\\u003c");
+  return \`<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>FastScript</title>
+    <link rel="stylesheet" href="\${assetPath("styles.css")}" />
+  </head>
+  <body>
+    <div id="app">\${content}</div>
+    <script>window.__FASTSCRIPT_SSR=\${safe}</script>
+    <script type="module" src="\${assetPath("router.js")}"></script>
+  </body>
+</html>\`;
+}
+
+function localeFromPath(pathname) {
+  const i18n = MANIFEST.i18n || { locales: ["en"], defaultLocale: "en" };
+  const parts = String(pathname || "/").split("/").filter(Boolean);
+  const head = parts[0];
+  if (head && i18n.locales.includes(head)) {
+    const normalized = "/" + parts.slice(1).join("/");
+    return { locale: head, pathname: normalized === "/" ? "/" : normalized || "/" };
+  }
+  return { locale: i18n.defaultLocale || "en", pathname: pathname || "/" };
+}
+
+async function maybeServeStatic(request, env, pathname) {
+  if (!env || !env.ASSETS) return null;
+  const staticLike = /\\.[a-zA-Z0-9]+$/.test(pathname) || pathname === "/manifest.webmanifest" || pathname === "/service-worker.js";
+  if (!staticLike) return null;
+  const res = await env.ASSETS.fetch(request);
+  if (res && res.status !== 404) {
+    const headers = applySecurityHeaders(new Headers(res.headers));
+    if (/\\.[a-f0-9]{8}\\.(js|css)$/.test(pathname) || /\\.(woff2?|ttf|otf|svg|png|jpe?g|gif|webp|avif)$/.test(pathname)) {
+      headers.set("cache-control", "public, max-age=31536000, immutable");
+    } else if (pathname === "/service-worker.js") {
+      headers.set("cache-control", "no-cache, max-age=0");
+    } else if (pathname === "/manifest.webmanifest" || pathname === "/fastscript-manifest.json" || pathname === "/asset-manifest.json") {
+      headers.set("cache-control", "no-store, max-age=0");
+    }
+    return new Response(res.body, { status: res.status, headers });
+  }
+  return null;
+}
+
+async function runMiddlewares(ctx, middlewares, done) {
+  let idx = -1;
+  async function next() {
+    idx += 1;
+    const mw = middlewares[idx];
+    if (!mw) return done();
+    return mw(ctx, next);
+  }
+  return next();
+}
+
+async function renderParallel(pathname, locale, baseParams) {
+  const slots = {};
+  for (const route of MANIFEST.parallelRoutes || []) {
+    const hit = match(route.path, pathname);
+    if (!hit) continue;
+    const mod = moduleFor(route.module);
+    if (!mod) continue;
+    let data = {};
+    if (typeof mod.load === "function") data = (await mod.load({ pathname, params: baseParams, locale, slot: route.slot })) || {};
+    const html = mod.default ? mod.default({ ...data, pathname, params: baseParams, locale, slot: route.slot }) : "";
+    slots[route.slot || "default"] = html || "";
+  }
+  return slots;
+}
+
+async function applyLayouts(route, pathname, locale, html, params, data, slots) {
+  const list = (route.layouts && route.layouts.length ? route.layouts : (MANIFEST.layout ? [MANIFEST.layout] : [])) || [];
+  let out = html;
+  for (const layoutPath of list) {
+    const mod = moduleFor(layoutPath);
+    if (!mod || typeof mod.default !== "function") continue;
+    out = mod.default({ content: out, pathname, locale, params, data, slots });
+  }
+  return out;
+}
+
+export default {
+  async fetch(request, env) {
+    const url = new URL(request.url);
+    const localized = localeFromPath(url.pathname);
+    const pathname = localized.pathname;
+    const method = (request.method || "GET").toUpperCase();
+
+    const staticResponse = await maybeServeStatic(request, env, url.pathname);
+    if (staticResponse) return staticResponse;
+
+    const responseCookies = [];
+    const helpers = makeHelpers(responseCookies);
+    const cookies = parseCookies(request.headers.get("cookie") || "");
+    const queryObject = Object.fromEntries(url.searchParams.entries());
+    const ctx = {
+      req: request,
+      env,
+      pathname,
+      method,
+      locale: localized.locale,
+      params: {},
+      query: queryObject,
+      cookies,
+      input: {
+        body: null,
+        query: queryObject,
+        async readJson() {
+          if (this.body !== null) return this.body;
+          this.body = await readJsonBody(request);
+          return this.body;
+        },
+        validateQuery(schema) {
+          return validateShape(schema, queryObject, "query").value;
+        },
+        async validateBody(schema) {
+          const body = await this.readJson();
+          return validateShape(schema, body, "body").value;
+        }
+      },
+      helpers,
+      user: null,
+      auth: {
+        requireUser() {
+          const error = new Error("Unauthorized");
+          error.status = 401;
+          throw error;
+        }
+      }
+    };
+
+    try {
+      const middlewares = [];
+      if (MANIFEST.middleware) {
+        const mm = moduleFor(MANIFEST.middleware);
+        if (Array.isArray(mm?.middlewares)) middlewares.push(...mm.middlewares);
+        else if (typeof mm?.middleware === "function") middlewares.push(mm.middleware);
+        else if (typeof mm?.default === "function") middlewares.push(mm.default);
+      }
+
+      const result = await runMiddlewares(ctx, middlewares, async () => {
+        if (pathname.startsWith("/api/")) {
+          const apiHit = resolveRoute(MANIFEST.apiRoutes || [], pathname);
+          if (!apiHit) return { status: 404, json: { ok: false, error: "API route not found" } };
+          ctx.params = apiHit.params;
+          const mod = moduleFor(apiHit.route.module);
+          if (!mod) return { status: 500, json: { ok: false, error: "API module missing" } };
+          const handler = mod[method];
+          if (typeof handler !== "function") return { status: 405, json: { ok: false, error: \`Method \${method} not allowed\` } };
+          if (mod.schemas?.[method]) {
+            const body = await ctx.input.readJson();
+            validateShape(mod.schemas[method], body, "body");
+          }
+          return handler(ctx, helpers);
+        }
+
+        const hit = resolveRoute(MANIFEST.routes || [], pathname);
+        if (!hit) {
+          if (MANIFEST.notFound) {
+            const nf = moduleFor(MANIFEST.notFound);
+            const notFoundHtml = nf?.default ? transformStylePrimitives(nf.default({ pathname, locale: ctx.locale })) : "<h1>404</h1>";
+            return { status: 404, body: htmlDoc(notFoundHtml, { pathname, data: null }), headers: { "content-type": "text/html; charset=utf-8" } };
+          }
+          return { status: 404, body: "Not found" };
+        }
+
+        ctx.params = hit.params;
+        const mod = moduleFor(hit.route.module);
+        if (!mod) return { status: 500, body: "Route module missing" };
+
+        if (!["GET", "HEAD"].includes(method) && typeof mod[method] === "function") {
+          if (mod.schemas?.[method]) {
+            const body = await ctx.input.readJson();
+            validateShape(mod.schemas[method], body, "body");
+          }
+          return mod[method](ctx, helpers);
+        }
+
+        let data = {};
+        if (typeof mod.load === "function") data = (await mod.load({ ...ctx, pathname, params: hit.params, locale: ctx.locale })) || {};
+        let html = mod.default ? mod.default({ ...data, pathname, params: hit.params, locale: ctx.locale }) : "";
+        const slots = await renderParallel(pathname, ctx.locale, hit.params);
+        html = await applyLayouts(hit.route, pathname, ctx.locale, html, hit.params, data, slots);
+        html = transformStylePrimitives(html);
+        return {
+          status: 200,
+          body: htmlDoc(html, { pathname, data }),
+          headers: { "content-type": "text/html; charset=utf-8" },
+        };
+      });
+
+      return toResponse(result, responseCookies);
+    } catch (error) {
+      const status = Number.isInteger(error?.status) ? error.status : 500;
+      const headers = applySecurityHeaders(new Headers({ "content-type": "application/json; charset=utf-8" }));
+      return new Response(JSON.stringify({ ok: false, error: error?.message || "Unknown error", details: error?.details || null }), {
+        status,
+        headers,
+      });
+    }
+  }
+};
+`);
+  return lines.join("\n");
+}
+
+function writeCloudflareAdapter(root) {
+  const distDir = join(root, "dist");
+  const manifestPath = join(distDir, "fastscript-manifest.json");
+  const assetManifestPath = join(distDir, "asset-manifest.json");
+  if (!existsSync(manifestPath)) {
+    throw new Error("Cloudflare deploy requires build output. Run `fastscript build` first.");
+  }
+
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  const assetManifest = existsSync(assetManifestPath) ? JSON.parse(readFileSync(assetManifestPath, "utf8")) : { mapping: {} };
+  const source = buildCloudflareWorkerSource({ manifest, assetMap: assetManifest.mapping || {} });
+
+  writeFileSync(join(distDir, "worker.js"), source, "utf8");
+  writeFileSync(
+    join(root, "wrangler.toml"),
+    `name = "fastscript-app"
+main = "dist/worker.js"
+compatibility_date = "2026-04-14"
+compatibility_flags = ["nodejs_compat"]
+workers_dev = true
+
+[vars]
+NODE_ENV = "production"
+FASTSCRIPT_DEPLOY_TARGET = "cloudflare"
+
+[observability.logs]
+enabled = true
+
+[assets]
+directory = "dist"
+binding = "ASSETS"
+`,
+    "utf8",
+  );
+
+  writeFileSync(
+    join(root, ".dev.vars.example"),
+    `NODE_ENV=production
+FASTSCRIPT_DEPLOY_TARGET=cloudflare
+DEFAULT_TENANT_ID=public
+`,
+    "utf8",
+  );
+}
+
+export async function runDeploy(args = []) {
+  const { target } = parseArgs(args);
+  const root = resolve(process.cwd());
+
+  if (target === "node" || target === "pm2") {
+    writeNodeAdapter(root);
+    console.log("deploy adapter ready: node/pm2 + docker");
+    return;
+  }
+
+  if (target === "vercel") {
+    await ensureBuildArtifacts(root);
+    writeVercelAdapter(root);
+    console.log("deploy adapter ready: vercel (full catch-all SSR/API)");
+    return;
+  }
+
+  if (target === "cloudflare") {
+    await ensureBuildArtifacts(root);
+    writeCloudflareAdapter(root);
+    console.log("deploy adapter ready: cloudflare (worker SSR/API + static assets)");
+    return;
+  }
+
+  throw new Error(`Unknown deploy target: ${target}. Use node|pm2|vercel|cloudflare`);
+}

package/node_modules/@fastscript/core-private/src/dev.mjs

@@ -0,0 +1,5 @@
+import { runServer } from "./server-runtime.mjs";
+
+export async function runDev() {
+  await runServer({ mode: "development", watchMode: true, buildOnStart: true, port: 4173 });
+}

package/node_modules/@fastscript/core-private/src/docs-search.mjs

@@ -0,0 +1,35 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+function tokenize(text) {
+  return String(text || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, " ")
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+export function rankDocs(index = [], query = "", { limit = 20 } = {}) {
+  const q = tokenize(query);
+  if (!q.length) return index.slice(0, limit);
+  return index
+    .map((item) => {
+      const terms = item.terms || {};
+      let score = 0;
+      for (const token of q) score += Number(terms[token] || 0);
+      return { ...item, score };
+    })
+    .filter((item) => item.score > 0)
+    .sort((a, b) => b.score - a.score || a.title.localeCompare(b.title))
+    .slice(0, limit);
+}
+
+export function loadDocsIndex(path = "docs/search-index.json") {
+  const full = resolve(path);
+  if (!existsSync(full)) return [];
+  try {
+    return JSON.parse(readFileSync(full, "utf8"));
+  } catch {
+    return [];
+  }
+}