@mehdad67/apitogo 0.1.24

package/src/vite/css/plugin.ts

@@ -0,0 +1,105 @@
+// Taken and adapted from
+// https://github.com/hi-ogawa/vite-plugins/tree/main/packages/ssr-css
+import path from "node:path";
+import { type DevEnvironment, isCSSRequest, type Plugin } from "vite";
+import { getCurrentConfig } from "../../config/loader.js";
+import { virtualModuleId as THEME_VIRTUAL_MODULE } from "../plugin-theme.js";
+import { collectStyle } from "./collect.js";
+
+const VIRTUAL_ENTRY = "virtual:ssr-css.css";
+
+export function vitePluginSsrCss(pluginOpts: { entries: string[] }): Plugin {
+  let server: DevEnvironment;
+
+  const config = getCurrentConfig();
+
+  const virtualHref = path.join(
+    config.basePath ?? "",
+    `/@id/__x00__${VIRTUAL_ENTRY}?direct`,
+  );
+  const cssModuleMap = new Map<string, string>();
+
+  return {
+    name: "zudoku-ssr-css",
+    apply: "serve",
+    configureServer(server_) {
+      server = server_.environments.ssr;
+
+      // invalidate virtual modules for each inline request
+      server_.middlewares.use((req, _res, next) => {
+        if (req.url === virtualHref) {
+          invalidateModule(server, `\0${VIRTUAL_ENTRY}?direct`);
+        }
+        next();
+      });
+
+      // Clear CSS cache when config files change
+      server_.watcher.on("change", (file) => {
+        const currentConfig = getCurrentConfig();
+        if (
+          currentConfig.__meta.dependencies.includes(file) ||
+          file === currentConfig.__meta.configPath
+        ) {
+          cssModuleMap.clear();
+          invalidateModule(server, `\0${VIRTUAL_ENTRY}?direct`);
+          invalidateModule(server, `\0${THEME_VIRTUAL_MODULE}`);
+        }
+      });
+    },
+
+    resolveId(id) {
+      return id.startsWith(VIRTUAL_ENTRY) ? `\0${id}` : undefined;
+    },
+    transform(code, id) {
+      if (!isCSSRequest(id)) return;
+
+      cssModuleMap.set(id, code);
+    },
+    async load(id) {
+      if (!id.startsWith(`\0${VIRTUAL_ENTRY}`)) return;
+
+      const url = new URL(id.slice(1), "https://test.local");
+      let code = await collectStyle(server, pluginOpts.entries, cssModuleMap);
+      if (!url.searchParams.has("direct")) {
+        code = `export default ${JSON.stringify(code)};`;
+      }
+      return code;
+    },
+
+    // also expose via transformIndexHtml
+    transformIndexHtml: {
+      handler: async () => {
+        return [
+          {
+            tag: "link",
+            injectTo: "head",
+            attrs: {
+              rel: "stylesheet",
+              href: virtualHref,
+              "data-ssr-css": true,
+            },
+          },
+          {
+            tag: "script",
+            injectTo: "head",
+            attrs: { type: "module" },
+            children: `
+              import { createHotContext } from "/@vite/client";
+              const hot = createHotContext("/__clear_ssr_css");
+              hot.on("vite:afterUpdate", () => {
+                document.querySelectorAll("[data-ssr-css]").forEach(node => node.remove());
+              });
+            `,
+          },
+        ];
+      },
+    },
+  };
+}
+
+function invalidateModule(server: DevEnvironment, id: string) {
+  const mod = server.moduleGraph.getModuleById(id);
+  if (mod) {
+    server.moduleGraph.invalidateModule(mod);
+  }
+}

package/src/vite/debug.ts

@@ -0,0 +1,18 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+export async function writePluginDebugCode(
+  rootDir: string,
+  pluginName: string,
+  code: string | string[],
+  extension: string = "js",
+) {
+  if (process.env.ZUDOKU_BUILD_DEBUG) {
+    const debugDir = path.join(rootDir, "dist", "debug");
+    await mkdir(debugDir, { recursive: true });
+    await writeFile(
+      path.join(debugDir, `${pluginName}.${extension}`),
+      typeof code === "string" ? code : code.join("\n"),
+    );
+  }
+}

package/src/vite/dev-server.ts

@@ -0,0 +1,294 @@
+import fs from "node:fs/promises";
+import type { Server } from "node:http";
+import http from "node:http";
+import https from "node:https";
+import path from "node:path";
+import { createHttpTerminator, type HttpTerminator } from "http-terminator";
+import {
+  createServer as createViteServer,
+  isRunnableDevEnvironment,
+  mergeConfig,
+  type ViteDevServer,
+} from "vite";
+import { logger } from "../cli/common/logger.js";
+import { printDiagnosticsToConsole } from "../cli/common/output.js";
+import { findAvailablePort } from "../cli/common/utils/ports.js";
+import type { LoadedConfig } from "../config/config.js";
+import { loadZudokuConfig } from "../config/loader.js";
+import { createGraphQLServer } from "../lib/oas/graphql/index.js";
+import {
+  getAppClientEntryPath,
+  getAppServerEntryPath,
+  getViteConfig,
+  type ZudokuConfigEnv,
+} from "./config.js";
+import { getDevHtml } from "./html.js";
+import { buildPagefindDevIndex } from "./pagefind-dev-index.js";
+import { ensurePagefindDevStub } from "./pagefind-dev-stub.js";
+
+const DEFAULT_DEV_PORT = 3000;
+
+type EntryServerImport = typeof import("../app/entry.server.js");
+
+export class DevServer {
+  private terminator: HttpTerminator | undefined;
+  public resolvedPort = 0;
+  public protocol = "http";
+
+  constructor(
+    private options: {
+      dir: string;
+      ssr?: boolean;
+      open?: boolean;
+      argPort?: number;
+    },
+  ) {}
+
+  private async createNodeServer(config: LoadedConfig): Promise<Server> {
+    if (!config.https) return http.createServer();
+
+    this.protocol = "https";
+    const { dir } = this.options;
+
+    const [key, cert, ca] = await Promise.all([
+      fs.readFile(path.resolve(dir, config.https.key)),
+      fs.readFile(path.resolve(dir, config.https.cert)),
+      config.https.ca
+        ? fs.readFile(path.resolve(dir, config.https.ca))
+        : undefined,
+    ]);
+
+    return https.createServer({ key, cert, ca });
+  }
+
+  async start(): Promise<{ vite: ViteDevServer }> {
+    const configEnv: ZudokuConfigEnv = {
+      mode: "development",
+      command: "serve",
+      isSsrBuild: this.options.ssr,
+    };
+    const viteConfig = await getViteConfig(this.options.dir, configEnv);
+    const { config } = await loadZudokuConfig(configEnv, this.options.dir);
+
+    this.resolvedPort = await findAvailablePort(
+      this.options.argPort ?? config.port ?? DEFAULT_DEV_PORT,
+    );
+
+    const server = await this.createNodeServer(config);
+
+    if (config.search?.type === "pagefind" && viteConfig.publicDir !== false) {
+      const publicRoot = path.resolve(
+        this.options.dir,
+        typeof viteConfig.publicDir === "string"
+          ? viteConfig.publicDir
+          : "public",
+      );
+      await ensurePagefindDevStub(publicRoot);
+    }
+
+    const mergedViteConfig = mergeConfig(viteConfig, {
+      server: {
+        hmr: { server },
+      },
+      plugins: [
+        {
+          // Serves the client entry via Vite's client transform pipeline.
+          // Must be registered via configureServer so it runs before Vite's
+          // built-in transform middleware which would treat the path as a static asset.
+          name: "apitogo:entry-client",
+          configureServer(server: ViteDevServer) {
+            const entryPath = path.posix.join(
+              server.config.base,
+              "/__z/entry.client.tsx",
+            );
+            server.middlewares.use(entryPath, async (_req, res) => {
+              const transformed =
+                await server.environments.client.transformRequest(
+                  getAppClientEntryPath(),
+                );
+
+              if (!transformed) {
+                res.writeHead(500);
+                res.end("Error transforming client entry");
+                return;
+              }
+              res.writeHead(200, { "Content-Type": "text/javascript" });
+              res.end(transformed.code);
+            });
+          },
+        },
+      ],
+    });
+
+    const vite = await createViteServer(mergedViteConfig);
+    const graphql = createGraphQLServer({ graphqlEndpoint: "/__z/graphql" });
+
+    // Handle base path redirect
+    vite.middlewares.use((req, res, next) => {
+      if (
+        req.method === "GET" &&
+        req.originalUrl === "/" &&
+        config.basePath &&
+        config.basePath !== "/"
+      ) {
+        res.writeHead(307, { Location: config.basePath });
+        res.end();
+        return;
+      }
+      next();
+    });
+
+    vite.middlewares.use(graphql.graphqlEndpoint, graphql);
+
+    // Pagefind reindex endpoint (SSE)
+    vite.middlewares.use("/__z/pagefind-reindex", async (_req, res) => {
+      res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive",
+      });
+
+      const { config: currentConfig } = await loadZudokuConfig(
+        configEnv,
+        this.options.dir,
+      );
+
+      const sendEvent = (data: unknown) =>
+        res.write(`data: ${JSON.stringify(data)}\n\n`);
+
+      if (currentConfig.search?.type !== "pagefind") {
+        sendEvent({
+          type: "complete",
+          success: false,
+          indexed: 0,
+          error: "Pagefind search is not enabled",
+        });
+        res.end();
+        return;
+      }
+
+      try {
+        for await (const event of buildPagefindDevIndex(vite, currentConfig)) {
+          sendEvent(event);
+        }
+      } catch (error) {
+        const message =
+          error instanceof Error ? error.message : "Unknown error";
+
+        sendEvent({
+          type: "complete",
+          success: false,
+          indexed: 0,
+          error: message,
+        });
+      }
+
+      res.end();
+    });
+
+    printDiagnosticsToConsole(
+      `Server-side rendering ${this.options.ssr ? "enabled" : "disabled"}`,
+    );
+
+    if (config.search?.type === "pagefind" && vite.config.publicDir) {
+      await ensurePagefindDevStub(vite.config.publicDir);
+    }
+
+    vite.middlewares.use(async (req, res) => {
+      const url = req.originalUrl ?? req.url ?? "/";
+      const ssrEnvironment = vite.environments.ssr;
+
+      if (!isRunnableDevEnvironment(ssrEnvironment)) {
+        res.writeHead(500);
+        res.end("SSR environment not available");
+        return;
+      }
+
+      try {
+        const { config: currentConfig } = await loadZudokuConfig(
+          configEnv,
+          this.options.dir,
+        );
+        const rawHtml = getDevHtml({
+          jsEntry: "/__z/entry.client.tsx",
+          dir: currentConfig.site?.dir,
+        });
+        const template = await vite.transformIndexHtml(url, rawHtml);
+
+        if (this.options.ssr) {
+          const entryServer =
+            await ssrEnvironment.runner.import<EntryServerImport>(
+              getAppServerEntryPath(),
+            );
+
+          const hasBody = req.method !== "GET" && req.method !== "HEAD";
+          const request = new Request(
+            `${this.protocol}://${req.headers.host}${url}`,
+            {
+              method: req.method,
+              headers: req.headers as HeadersInit,
+              body: hasBody ? (req as unknown as BodyInit) : undefined,
+              // Required by Node when body is a readable stream
+              // @ts-expect-error Missing type definition
+              duplex: hasBody ? "half" : undefined,
+            },
+          );
+
+          const response = await entryServer.handleRequest({
+            template,
+            request,
+            routes: entryServer.getRoutesByConfig(currentConfig),
+            basePath: currentConfig.basePath,
+          });
+
+          for (const [key, value] of response.headers) {
+            res.appendHeader(key, value);
+          }
+          res.writeHead(response.status);
+
+          for await (const chunk of response.body ?? []) {
+            res.write(chunk);
+          }
+          res.end();
+        } else {
+          res.writeHead(200, { "Content-Type": "text/html" });
+          res.end(template);
+        }
+      } catch (e) {
+        logger.error(e);
+        const html = `<!DOCTYPE html><html><body><script type="module">
+          import { ErrorOverlay } from '/@vite/client';
+          document.body.appendChild(new ErrorOverlay(${JSON.stringify({
+            message: e instanceof Error ? e.message : String(e),
+            stack: e instanceof Error ? e.stack : "",
+          })}));
+        </script></body></html>`;
+        res.writeHead(500, { "Content-Type": "text/html" });
+        res.end(html);
+      }
+    });
+
+    server.on("request", vite.middlewares);
+
+    await new Promise<void>((resolve) => {
+      server.listen(this.resolvedPort, resolve);
+    });
+
+    this.terminator = createHttpTerminator({ server });
+
+    if (this.options.open || process.env.ZUDOKU_OPEN_BROWSER) {
+      const url = `${this.protocol}://localhost:${this.resolvedPort}`;
+      vite.resolvedUrls = {
+        local: [`${url}${vite.config.base || "/"}`],
+        network: [],
+      };
+      vite.openBrowser();
+    }
+
+    return { vite };
+  }
+
+  async stop() {
+    await this.terminator?.terminate();
+  }
+}

package/src/vite/html.ts

@@ -0,0 +1,54 @@
+export function getDevHtml({
+  jsEntry,
+  dir,
+}: {
+  jsEntry: string;
+  dir?: "ltr" | "rtl";
+}) {
+  return `
+<!doctype html>
+<html lang="en" ${dir ? `dir="${dir}"` : ""}>
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
+    <!--app-helmet-->
+    <link rel="preconnect" href="https://cdn.zudoku.dev/">
+  </head>
+  <body>
+    <div id="root"><!--app-html--></div>
+    <script type="module" src="${jsEntry}"></script>
+  </body>
+</html>
+`.trim();
+}
+
+export function getBuildHtml({
+  jsEntry,
+  cssEntries,
+  dir,
+}: {
+  jsEntry: string;
+  cssEntries: string[];
+  dir?: "ltr" | "rtl";
+}) {
+  const cssLinks = cssEntries
+    .map((css) => `    <link rel="stylesheet" crossorigin href="${css}">`)
+    .join("\n");
+
+  return `
+<!doctype html>
+<html lang="en" ${dir ? `dir="${dir}"` : ""}>
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
+    <script type="module" crossorigin src="${jsEntry}"></script>
+${cssLinks}
+    <!--app-helmet-->
+    <link rel="preconnect" href="https://cdn.zudoku.dev/">
+  </head>
+  <body>
+    <div id="root"><!--app-html--></div>
+  </body>
+</html>
+`.trim();
+}

package/src/vite/index.ts

@@ -0,0 +1,2 @@
+export type { ConfigEnv, Plugin, PluginOption, UserConfig } from "vite";
+export { defineConfig, mergeConfig } from "vite";

package/src/vite/llms.ts

@@ -0,0 +1,99 @@
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import colors from "picocolors";
+import { joinUrl } from "../lib/util/joinUrl.js";
+import type { MarkdownFileInfo } from "./plugin-markdown-export.js";
+export async function generateLlmsTxtFiles({
+  markdownFileInfos,
+  outputUrls,
+  baseOutputDir,
+  basePath,
+  siteName,
+  llmsTxt,
+  llmsTxtFull,
+  redirectUrls,
+}: {
+  markdownFileInfos: MarkdownFileInfo[];
+  basePath: string | undefined;
+  outputUrls: string[];
+  baseOutputDir: string;
+  siteName?: string;
+  llmsTxt?: boolean;
+  llmsTxtFull?: boolean;
+  redirectUrls: Set<string>;
+}) {
+  const nonRedirectUrls = outputUrls.filter((url) => !redirectUrls.has(url));
+
+  const baseUrl = basePath ?? "";
+  const title = siteName ?? "Documentation";
+
+  const markdownMap = new Map(
+    markdownFileInfos.map((info) => [info.routePath, info]),
+  );
+
+  // Generate llms.txt
+  if (llmsTxt) {
+    const llmsTxtParts: string[] = [];
+
+    llmsTxtParts.push(`# ${title}\n`);
+    llmsTxtParts.push("> Documentation files for Large Language Models\n");
+
+    // Add documentation section with links to all pages (matching sitemap structure)
+    llmsTxtParts.push("## Documentation\n");
+
+    for (const url of nonRedirectUrls) {
+      // Skip error pages
+      if (/(400|404|500)$/.test(url)) continue;
+
+      const mdInfo = markdownMap.get(url);
+
+      // Only include pages that have markdown content
+      if (mdInfo) {
+        // If we have markdown for this page, link to the .md file
+        const mdUrl = joinUrl(baseUrl, `${url}.md`);
+        const linkTitle = mdInfo.title ?? url;
+        const description = mdInfo.description ? `: ${mdInfo.description}` : "";
+        llmsTxtParts.push(`- [${linkTitle}](${mdUrl})${description}`);
+      }
+    }
+
+    const llmsTxt = llmsTxtParts.join("\n");
+    await writeFile(path.join(baseOutputDir, "llms.txt"), llmsTxt, "utf-8");
+
+    if (process.env.APITOGO_JSON_ONLY !== "1") {
+      // biome-ignore lint/suspicious/noConsole: Logging allowed here
+      console.log(colors.blue("✓ generated llms.txt"));
+    }
+  }
+
+  // Generate llms-full.txt (full content of all markdown documents)
+  if (llmsTxtFull) {
+    const llmsFullParts: string[] = [];
+
+    llmsFullParts.push(`# ${title}\n`);
+    llmsFullParts.push("> Complete documentation for Large Language Models\n");
+
+    // Add each markdown document's full content
+    for (const info of markdownFileInfos) {
+      llmsFullParts.push(`\n---\n`);
+      llmsFullParts.push(`## Document: ${info.title ?? info.routePath}\n`);
+      if (info.description) {
+        llmsFullParts.push(`${info.description}\n`);
+      }
+      llmsFullParts.push(`URL: ${joinUrl(baseUrl, info.routePath)}\n`);
+      llmsFullParts.push(`\n${info.content}\n`);
+    }
+
+    const llmsFull = llmsFullParts.join("\n");
+    await writeFile(
+      path.join(baseOutputDir, "llms-full.txt"),
+      llmsFull,
+      "utf-8",
+    );
+
+    if (process.env.APITOGO_JSON_ONLY !== "1") {
+      // biome-ignore lint/suspicious/noConsole: Allowed here
+      console.log(colors.blue("✓ generated llms-full.txt"));
+    }
+  }
+}

package/src/vite/mdx/rehype-extract-toc-with-jsx-export.ts

@@ -0,0 +1,19 @@
+import { name as isIdentifierName } from "estree-util-is-identifier-name";
+import type { Root } from "hast";
+import type { Plugin } from "unified";
+import { exportMdxjsConst } from "./utils.js";
+
+const rehypeExtractTocWithJsxExport: Plugin<[{ name?: string }?], Root> = ({
+  name = "tableOfContents",
+} = {}) => {
+  if (!isIdentifierName(name)) {
+    throw new Error(`Invalid identifier name: ${JSON.stringify(name)}`);
+  }
+
+  return (tree, vfile) => {
+    if (vfile.data.toc == null) return;
+    tree.children.unshift(exportMdxjsConst(name, vfile.data.toc));
+  };
+};
+
+export default rehypeExtractTocWithJsxExport;

package/src/vite/mdx/rehype-extract-toc-with-jsx.ts

@@ -0,0 +1,70 @@
+import type { Element, RootContent } from "hast";
+import { headingRank } from "hast-util-heading-rank";
+import { toString as hastToString } from "hast-util-to-string";
+import type { Plugin } from "unified";
+import { visit } from "unist-util-visit";
+
+export type TocEntry = {
+  depth: number;
+  text: string;
+  id?: string;
+  children?: TocEntry[];
+  /** Rich AST nodes for rendering (includes JSX components) */
+  rich?: RootContent[];
+};
+
+export type Toc = TocEntry[];
+
+declare module "vfile" {
+  interface DataMap {
+    toc: Toc;
+  }
+}
+
+const rehypeExtractTocWithJsx: Plugin<[]> = () => (tree, vfile) => {
+  const headings: TocEntry[] = [];
+
+  visit(tree, "element", (node: Element) => {
+    const level = headingRank(node);
+
+    if (!level) return;
+
+    const richChildren = node.children as RootContent[];
+    const hasRichContent = richChildren.some((child) => child.type !== "text");
+
+    const heading: TocEntry = {
+      depth: level,
+      text: hastToString(node),
+      ...(hasRichContent ? { rich: richChildren } : {}),
+    };
+
+    if (node.properties?.id) {
+      heading.id = String(node.properties.id);
+    }
+
+    headings.push(heading);
+  });
+
+  vfile.data.toc = createTree(headings);
+};
+
+const createTree = (headings: TocEntry[]): Toc => {
+  const root: TocEntry = { depth: 0, text: "", children: [] };
+  const stack: TocEntry[] = [root];
+
+  for (const heading of headings) {
+    // biome-ignore lint/style/noNonNullAssertion: We check the length of the stack before
+    while (stack.length > 1 && stack.at(-1)!.depth >= heading.depth) {
+      stack.pop();
+    }
+
+    const parent = stack.at(-1) ?? root;
+    parent.children ??= [];
+    parent.children.push(heading);
+    stack.push(heading);
+  }
+
+  return root.children ?? [];
+};
+
+export default rehypeExtractTocWithJsx;