@mehdad67/apitogo 0.1.24

package/src/vite/api/schema-codegen.ts

@@ -0,0 +1,163 @@
+import { type RecordAny, traverse } from "../../lib/util/traverse.js";
+
+const unescapeJsonPointer = (uri: string) =>
+  decodeURIComponent(uri.replace(/~1/g, "/").replace(/~0/g, "~"));
+
+const getSegmentsFromPath = (path: string) =>
+  path.split("/").slice(1).map(unescapeJsonPointer);
+
+// Find all $ref occurrences in the schema and assign them unique variable names
+const createLocalRefMap = (obj: RecordAny) => {
+  const refMap = new Map<string, number>();
+  const siblingsMap = new Map<
+    string,
+    { refPath: string; siblings: RecordAny }
+  >();
+
+  traverse(obj, (node) => {
+    if (typeof node.$ref === "string" && node.$ref.startsWith("#/")) {
+      if (!refMap.has(node.$ref)) {
+        refMap.set(node.$ref, refMap.size);
+      }
+
+      const { $ref, ...siblings } = node;
+
+      if (Object.keys(siblings).length > 0) {
+        const uniqueKey = `${$ref}__${siblingsMap.size}`;
+        siblingsMap.set(uniqueKey, { refPath: $ref, siblings });
+        node.__uniqueRefKey = uniqueKey;
+      }
+    }
+    return node;
+  });
+
+  return { refMap, siblingsMap };
+};
+
+// Replace $ref nodes with markers that become JS variable references
+const setRefMarkers = (obj: RecordAny, refMap: Map<string, number>) =>
+  traverse(obj, (node) => {
+    const { $ref, __uniqueRefKey } = node;
+    if (typeof $ref === "string" && refMap.has($ref)) {
+      return __uniqueRefKey
+        ? `__refMap+Siblings:${__uniqueRefKey}`
+        : `__refMap:${$ref}`;
+    }
+    return node;
+  });
+
+// Replace ref markers in generated code with actual variable references
+const replaceMarkers = (code: string, mergedRefs: Map<string, string>) =>
+  code
+    .replace(/"__refMap:(.*?)"/g, '__refMap["$1"]')
+    .replace(
+      /"__refMap\+Siblings:(.*?)"/g,
+      (_, key) => mergedRefs.get(key) ?? `__refMap["${key}"]`,
+    );
+
+const lookup = (
+  schema: RecordAny,
+  path: string,
+  filePath?: string,
+): RecordAny => {
+  const parts = getSegmentsFromPath(path);
+  let val = schema;
+
+  for (const part of parts) {
+    while (val.$ref?.startsWith("#/")) {
+      val = val.$ref === path ? val : lookup(schema, val.$ref, filePath);
+    }
+
+    if (val[part] === undefined) {
+      throw new Error(
+        `Error in ${filePath ?? "code generation"}: Could not find path segment ${part} in path: ${path}`,
+      );
+    }
+
+    val = val[part];
+  }
+
+  return val;
+};
+
+const stringify = (obj: unknown, indent = 2) =>
+  JSON.stringify(obj, null, indent);
+
+/**
+ * Generate JavaScript code that exports the schema with all references resolved as variables.
+ *
+ * Handles circular references by:
+ * 1. Creating empty objects first to establish the references
+ * 2. Adding these objects to the reference map
+ * 3. Using Object.assign to populate their properties later
+ *
+ * This ensures object identity throughout the circular references.
+ */
+export const generateCode = (schema: RecordAny, filePath?: string) => {
+  const { refMap, siblingsMap } = createLocalRefMap(schema);
+  const lines: string[] = [];
+
+  lines.push(
+    `const __refs = Array.from({ length: ${refMap.size} }, () => ({}));`,
+    "const __refMap = {",
+    Array.from(refMap)
+      .map(([refPath, index]) => `  "${refPath}": __refs[${index}]`)
+      .join(",\n"),
+    "};",
+    "const __refMapPaths = Object.keys(__refMap);",
+  );
+
+  // Pre-declare merged ref variables as empty objects so they can be referenced
+  // during base ref population (they get populated after)
+  const mergedRefs = new Map<string, string>();
+
+  for (const uniqueKey of siblingsMap.keys()) {
+    const varName = `__merged_${mergedRefs.size}`;
+    mergedRefs.set(uniqueKey, varName);
+    lines.push(`const ${varName} = {};`);
+  }
+
+  const toCode = (obj: RecordAny) =>
+    replaceMarkers(stringify(setRefMarkers(obj, refMap)), mergedRefs);
+
+  // Pass 1: Populate all base refs. Bare $ref+siblings aliases are deferred
+  // until all regular base refs are populated (ordering is DFS-dependent).
+  const deferred: string[] = [];
+  for (const [refPath, index] of refMap) {
+    const value = lookup(schema, refPath, filePath);
+
+    if (!value) {
+      // biome-ignore lint/suspicious/noConsole: Logging allowed here
+      console.warn(`Could not find value for refPath: ${refPath}`);
+      continue;
+    }
+
+    const siblingEntry =
+      value.__uniqueRefKey && siblingsMap.get(value.__uniqueRefKey);
+    const target = siblingEntry ? deferred : lines;
+
+    target.push(
+      siblingEntry
+        ? `Object.assign(__refs[${index}], __refMap["${siblingEntry.refPath}"], ${stringify(siblingEntry.siblings)});`
+        : `Object.assign(__refs[${index}], ${toCode(value)});`,
+      `Object.defineProperty(__refs[${index}], "__$ref", { value: __refMapPaths[${index}], enumerable: false });`,
+    );
+  }
+  lines.push(...deferred);
+
+  // Pass 2: Populate merged objects (refs with sibling overrides like description)
+  for (const [uniqueKey, { refPath, siblings }] of siblingsMap) {
+    const varName = mergedRefs.get(uniqueKey);
+    const refIndex = refMap.get(refPath);
+    lines.push(
+      `Object.assign(${varName}, __refMap["${refPath}"], ${stringify(siblings)});`,
+      `Object.defineProperty(${varName}, "__$ref", { value: __refMapPaths[${refIndex}], enumerable: false });`,
+    );
+  }
+
+  const finalCode = toCode(schema);
+
+  lines.push(`export const schema = ${finalCode};`);
+
+  return lines.join("\n");
+};

package/src/vite/build.ts

@@ -0,0 +1,237 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { build as esbuild } from "esbuild";
+import type { Rollup } from "vite";
+import { build as viteBuild, mergeConfig } from "vite";
+import { ZuploEnv } from "../app/env.js";
+import { getZudokuRootDir } from "../cli/common/package-json.js";
+import {
+  findOutputPathOfServerConfig,
+  loadZudokuConfig,
+} from "../config/loader.js";
+import { getIssuer } from "../lib/auth/issuer.js";
+import invariant from "../lib/util/invariant.js";
+import { joinUrl } from "../lib/util/joinUrl.js";
+import { getViteConfig } from "./config.js";
+import { getBuildHtml } from "./html.js";
+import { writeOutput } from "./output.js";
+import { prerender } from "./prerender/prerender.js";
+
+const DIST_DIR = "dist";
+
+const extractAssets = (result: Rollup.RollupOutput) => {
+  const jsEntry = result.output.find(
+    (o) => "isEntry" in o && o.isEntry,
+  )?.fileName;
+  const cssEntries = result.output
+    .filter((o) => o.fileName.endsWith(".css"))
+    .map((o) => o.fileName);
+
+  if (!jsEntry || cssEntries.length === 0) {
+    throw new Error("Build failed. No js or css assets found");
+  }
+
+  return { jsEntry, cssEntries };
+};
+
+export type BuildOptions = {
+  dir: string;
+  ssr?: boolean;
+  adapter?: "node" | "cloudflare" | "vercel";
+  /** Suppress Vite build table and most build logs (used with `apitogo deploy --json-only`). */
+  jsonOnly?: boolean;
+};
+
+export async function runBuild(options: BuildOptions) {
+  const { dir, ssr, adapter = "node", jsonOnly = false } = options;
+
+  // Build client and server bundles
+  const viteClientConfig = await getViteConfig(dir, {
+    mode: "production",
+    command: "build",
+  });
+  const viteServerConfig = await getViteConfig(dir, {
+    mode: "production",
+    command: "build",
+    isSsrBuild: true,
+  });
+
+  const clientResult = await viteBuild(
+    jsonOnly
+      ? mergeConfig(viteClientConfig, { logLevel: "silent" as const })
+      : viteClientConfig,
+  );
+  const serverResult = await viteBuild({
+    ...viteServerConfig,
+    logLevel: "silent",
+  });
+
+  if (Array.isArray(clientResult) || !("output" in clientResult)) {
+    throw new Error("Client build failed");
+  }
+  if (Array.isArray(serverResult) || !("output" in serverResult)) {
+    throw new Error("Server build failed");
+  }
+
+  const { config } = await loadZudokuConfig(
+    { mode: "production", command: "build" },
+    dir,
+  );
+
+  const { jsEntry, cssEntries } = extractAssets(clientResult);
+
+  const html = getBuildHtml({
+    jsEntry: joinUrl(viteClientConfig.base, jsEntry),
+    cssEntries: cssEntries.map((css) => joinUrl(viteClientConfig.base, css)),
+    dir: config.site?.dir,
+  });
+
+  invariant(viteClientConfig.build?.outDir, "Client build outDir is missing");
+  invariant(viteServerConfig.build?.outDir, "Server build outDir is missing");
+
+  const clientOutDir = viteClientConfig.build.outDir;
+  const serverOutDir = viteServerConfig.build.outDir;
+  const serverConfigFilename = findOutputPathOfServerConfig(serverResult);
+
+  if (ssr) {
+    // SSR: bundle entry.js and remove index.html
+    await bundleSSREntry({
+      dir,
+      adapter,
+      serverOutDir,
+      serverConfigFilename,
+      html,
+      basePath: config.basePath,
+    });
+    await rm(path.join(clientOutDir, "index.html"), { force: true });
+  } else {
+    // SSG: prerender and clean up server
+    await runPrerender({
+      dir,
+      config,
+      html,
+      clientOutDir,
+      serverOutDir,
+      serverResult,
+    });
+  }
+}
+
+type PrerenderOptions = {
+  dir: string;
+  config: Awaited<ReturnType<typeof loadZudokuConfig>>["config"];
+  html: string;
+  clientOutDir: string;
+  serverOutDir: string;
+  serverResult: Rollup.RollupOutput;
+};
+
+const runPrerender = async (options: PrerenderOptions) => {
+  const { dir, config, html, clientOutDir, serverOutDir, serverResult } =
+    options;
+  const issuer = await getIssuer(config);
+  const serverConfigFilename = findOutputPathOfServerConfig(serverResult);
+
+  try {
+    const { workerResults, rewrites } = await prerender({
+      html,
+      dir,
+      basePath: config.basePath,
+      serverConfigFilename,
+      writeRedirects: process.env.VERCEL === undefined,
+    });
+
+    const indexHtml = path.join(clientOutDir, "index.html");
+    if (!workerResults.find((r) => r.outputPath === indexHtml)) {
+      await writeFile(indexHtml, html, "utf-8");
+    }
+
+    // Move status pages (400, 404, 500) to root path
+    const statusPages = workerResults.flatMap((r) =>
+      /400|404|500\.html$/.test(r.outputPath) ? r.outputPath : [],
+    );
+    for (const statusPage of statusPages) {
+      await rename(
+        statusPage,
+        path.join(dir, DIST_DIR, path.basename(statusPage)),
+      );
+    }
+
+    // Delete server build - not needed after prerender
+    await rm(serverOutDir, { recursive: true, force: true });
+
+    if (process.env.VERCEL) {
+      await mkdir(path.join(dir, ".vercel/output/static"), { recursive: true });
+      await rename(
+        path.join(dir, DIST_DIR),
+        path.join(dir, ".vercel/output/static"),
+      );
+    }
+
+    await writeOutput(dir, {
+      config,
+      redirects: workerResults.flatMap((r) => r.redirect ?? []),
+      rewrites,
+    });
+
+    if (ZuploEnv.isZuplo && issuer) {
+      await writeFile(
+        path.join(dir, DIST_DIR, ".output/zuplo.json"),
+        JSON.stringify({ issuer }, null, 2),
+        "utf-8",
+      );
+    }
+  } catch (e) {
+    // biome-ignore lint/suspicious/noConsole: Logging allowed here
+    console.error(e);
+    throw e;
+  }
+};
+
+type SSREntryOptions = {
+  dir: string;
+  adapter: "node" | "cloudflare" | "vercel";
+  serverOutDir: string;
+  serverConfigFilename: string;
+  html: string;
+  basePath?: string;
+};
+
+const bundleSSREntry = async (options: SSREntryOptions) => {
+  const { dir, adapter, serverOutDir, serverConfigFilename, html, basePath } =
+    options;
+  const tempEntryPath = path.join(dir, "__ssr-entry.ts");
+
+  const packageRoot = getZudokuRootDir();
+
+  const templateContent = await readFile(
+    path.join(packageRoot, "src/vite/ssr-templates", `${adapter}.ts`),
+    "utf-8",
+  );
+
+  const entryContent = templateContent
+    .replace('"__TEMPLATE__"', JSON.stringify(html))
+    .replace('"__CONFIG_FILE__"', JSON.stringify(`./${serverConfigFilename}`))
+    .replace(
+      '"__BASE_PATH__"',
+      basePath ? JSON.stringify(basePath) : "undefined",
+    );
+
+  await writeFile(tempEntryPath, entryContent, "utf-8");
+
+  try {
+    await esbuild({
+      entryPoints: [tempEntryPath],
+      bundle: true,
+      platform: adapter === "node" ? "node" : "neutral",
+      target: "es2022",
+      format: "esm",
+      outfile: path.join(serverOutDir, "entry.js"),
+      external: ["./entry.server.js", `./${serverConfigFilename}`],
+      nodePaths: [path.join(packageRoot, "node_modules")],
+      banner: { js: "// Bundled SSR entry" },
+    });
+  } finally {
+    await rm(tempEntryPath, { force: true });
+  }
+};

package/src/vite/config.ts

@@ -0,0 +1,258 @@
+import path from "node:path";
+import dotenv from "dotenv";
+import colors from "picocolors";
+import {
+  type ConfigEnv,
+  type InlineConfig,
+  type LogLevel,
+  loadConfigFromFile,
+  mergeConfig,
+} from "vite";
+import packageJson from "../../package.json" with { type: "json" };
+import { ZuploEnv } from "../app/env.js";
+import { logger } from "../cli/common/logger.js";
+import { getZudokuRootDir } from "../cli/common/package-json.js";
+import { loadZudokuConfig } from "../config/loader.js";
+import { CdnUrlSchema } from "../config/validators/ZudokuConfig.js";
+import { joinUrl } from "../lib/util/joinUrl.js";
+import { findPackageRoot } from "./package-root.js";
+import { ensurePagefindDevStub } from "./pagefind-dev-stub.js";
+import vitePlugin from "./plugin.js";
+import { getZuploSystemConfigurations } from "./zuplo.js";
+
+/** Resolved absolute public directory (Vite default: `<root>/public`). */
+const resolveMergedPublicDir = (
+  rootDir: string,
+  merged: InlineConfig,
+): string | undefined => {
+  if (merged.publicDir === false) return undefined;
+  const rel =
+    typeof merged.publicDir === "string" ? merged.publicDir : "public";
+  return path.resolve(rootDir, rel);
+};
+
+export type ZudokuConfigEnv = ConfigEnv & {
+  mode: "development" | "production";
+};
+
+export const getAppClientEntryPath = () =>
+  path.posix.join(getZudokuRootDir(), "src/app/entry.client.tsx");
+
+export const getAppServerEntryPath = () =>
+  path.posix.join(getZudokuRootDir(), "src/app/entry.server.tsx");
+
+// the vite config gets loaded multiple times, so we only log the CDN info once
+let hasLoggedCdnInfo = false;
+const MEDIA_REGEX =
+  /\.(a?png|jpe?g|gif|bmp|svg|webp|tiff|ico|webm|ogg|mp3|wav|m4a|avif|mp4)/i;
+
+const defineEnvVars = (vars: string[]) =>
+  Object.fromEntries(
+    vars.flatMap((v) => [
+      [`process.env.${v}`, JSON.stringify(process.env[v])],
+      [`import.meta.env.${v}`, JSON.stringify(process.env[v])],
+    ]),
+  );
+
+export async function getViteConfig(
+  dir: string,
+  configEnv: ZudokuConfigEnv,
+): Promise<InlineConfig> {
+  const { config, publicEnv, envPrefix } = await loadZudokuConfig(
+    configEnv,
+    dir,
+  );
+
+  const cdnUrl = CdnUrlSchema.parse(config.cdnUrl);
+
+  const base = cdnUrl?.base
+    ? joinUrl(cdnUrl.base, config.basePath)
+    : config.basePath;
+
+  if (cdnUrl && !hasLoggedCdnInfo) {
+    logger.info(colors.blue(`Using CDN URL:`));
+    logger.info(colors.blue(`  base:  `) + colors.dim(cdnUrl.base));
+    logger.info(colors.blue(`  media: `) + colors.dim(cdnUrl.media));
+    hasLoggedCdnInfo = true;
+  }
+
+  // We define public env vars as `process.env` vars because Vite only exposes them as `import.meta.env` vars
+  const publicVarsProcessEnvDefine = Object.fromEntries(
+    Object.entries(publicEnv).map(([key, value]) => [
+      `process.env.${key}`,
+      value,
+    ]),
+  );
+
+  if (ZuploEnv.isZuplo) {
+    dotenv.config({
+      path: path.resolve(config.__meta.rootDir, "../.env.zuplo"),
+      quiet: true,
+    });
+  }
+
+  const deploymentName =
+    ZuploEnv.buildConfig?.deploymentName ||
+    getZuploSystemConfigurations(process.env.ZUPLO_SYSTEM_CONFIGURATIONS)
+      ?.__ZUPLO_DEPLOYMENT_NAME;
+
+  const viteConfig: InlineConfig = {
+    root: dir,
+    base,
+    appType: "custom",
+    configFile: false,
+    clearScreen: false,
+    logLevel: (process.env.LOG_LEVEL ?? "info") as LogLevel,
+    customLogger: logger,
+    envPrefix,
+    resolve: {
+      dedupe: ["react", "react-dom"],
+      alias: {
+        "@mdx-js/react": import.meta.resolve("@mdx-js/react"),
+      },
+    },
+    define: {
+      "process.env.ZUDOKU_VERSION": JSON.stringify(packageJson.version),
+      "process.env.IS_ZUPLO": ZuploEnv.isZuplo,
+      "import.meta.env.IS_ZUPLO": ZuploEnv.isZuplo,
+      "import.meta.env.ZUPLO_PUBLIC_DEPLOYMENT_NAME":
+        JSON.stringify(deploymentName),
+      ...defineEnvVars([
+        "SENTRY_DSN",
+        "ZUPLO_BUILD_ID",
+        "ZUPLO_BUILD_CONFIG",
+        "ZUPLO_ENVIRONMENT_TYPE",
+        "ZUPLO_SERVER_URL",
+        "ZUPLO_GATEWAY_SERVICE_URL",
+      ]),
+      ...publicVarsProcessEnvDefine,
+    },
+    ssr: {
+      target: "node",
+      noExternal: [/apitogo/, "@mdx-js/react"],
+      external: ["@shikijs/themes", "@shikijs/langs"],
+    },
+    server: {
+      middlewareMode: true,
+      open: true,
+      watch: {
+        ignored: [
+          `${dir}/dist`,
+          `${dir}/lib`,
+          `${dir}/.git`,
+          `${config.__meta.moduleDir}/src/vite`,
+          `${config.__meta.moduleDir}/src/cli`,
+        ],
+      },
+    },
+    build: {
+      ssr: configEnv.isSsrBuild,
+      sourcemap: true,
+      target: "es2022",
+      outDir: path.resolve(
+        path.join(
+          dir,
+          "dist",
+          config.basePath ?? "",
+          configEnv.isSsrBuild ? "server" : "",
+        ),
+      ),
+      emptyOutDir: true,
+      rollupOptions: {
+        input:
+          configEnv.command === "build"
+            ? configEnv.isSsrBuild
+              ? [
+                  "@lukoweb/apitogo/app/entry.server.tsx",
+                  config.__meta.configPath,
+                ]
+              : "@lukoweb/apitogo/app/entry.client.tsx"
+            : undefined,
+        external: [joinUrl(config.basePath, "/pagefind/pagefind.js")],
+      },
+      chunkSizeWarningLimit: 1500,
+    },
+    experimental: {
+      renderBuiltUrl(filename) {
+        if (cdnUrl?.base && [".js", ".css"].includes(path.extname(filename))) {
+          return joinUrl(cdnUrl.base, filename);
+        }
+
+        if (cdnUrl?.media && MEDIA_REGEX.test(filename)) {
+          return joinUrl(cdnUrl.media, filename);
+        }
+
+        return { relative: true };
+      },
+    },
+    optimizeDeps: {
+      esbuildOptions: {
+        target: "es2022",
+      },
+      entries: [path.posix.join(getZudokuRootDir(), "src/{app,lib}/**")],
+      exclude: ["@lukoweb/apitogo"],
+      include: [
+        "react-dom/client",
+        "@lukoweb/apitogo/icons",
+        ...(process.env.SENTRY_DSN ? ["@sentry/react"] : []),
+      ],
+    },
+    assetsInclude: [
+      // Workaround for Pre-transform error for "virtual" file: https://github.com/vitejs/vite/issues/15374
+      "/__z/entry.client.tsx",
+      "**/pagefind.js",
+    ],
+    plugins: [vitePlugin()],
+    future: {
+      removeServerModuleGraph: "warn",
+      removeSsrLoadModule: "warn",
+      removeServerTransformRequest: "warn",
+      removePluginHookHandleHotUpdate: "warn",
+      removePluginHookSsrArgument: "warn",
+      removeServerHot: "warn",
+    },
+  };
+
+  // Merge vite configs from plugin directories and user's project
+  const configRoots = await Promise.all(
+    (config.__pluginDirs ?? []).map(findPackageRoot),
+  );
+  configRoots.push(dir);
+
+  let mergedViteConfig = viteConfig;
+
+  for (const root of configRoots) {
+    if (!root) continue;
+    const loaded = await loadConfigFromFile(
+      configEnv,
+      undefined,
+      root,
+      undefined,
+      undefined,
+      "runner",
+    );
+    if (!loaded) continue;
+
+    mergedViteConfig = mergeConfig(mergedViteConfig, loaded.config, true);
+
+    if (root === dir) {
+      logger.info(colors.blue(`merged with custom user Vite config`), {
+        timestamp: true,
+      });
+    }
+  }
+
+  // Create pagefind stub before Vite starts. In development, `optimizeDeps.entries` crawls all of
+  // `src/lib/**`, which includes PagefindSearch's dev import of `/pagefind/pagefind.js`; esbuild
+  // must be able to open that path even when search is not configured. Pagefind users still get
+  // the stub until a real index is written (dev index or production prerender).
+  const publicDir = resolveMergedPublicDir(dir, mergedViteConfig);
+  if (
+    publicDir &&
+    (configEnv.mode === "development" || config.search?.type === "pagefind")
+  ) {
+    await ensurePagefindDevStub(publicDir);
+  }
+
+  return mergedViteConfig;
+}

package/src/vite/css/collect.ts

@@ -0,0 +1,42 @@
+import { type DevEnvironment, isCSSRequest } from "vite";
+
+export async function collectStyle(
+  server: DevEnvironment,
+  entries: string[],
+  cssModuleMap: Map<string, string>,
+) {
+  const urls = await collectStyleUrls(server, entries);
+
+  return urls.map((url) => cssModuleMap.get(url) ?? "").join("\n");
+}
+
+async function collectStyleUrls(
+  server: DevEnvironment,
+  entries: string[],
+): Promise<string[]> {
+  const visited = new Set<string>();
+
+  async function traverse(url: string) {
+    const [, id] = await server.moduleGraph.resolveUrl(url);
+    if (visited.has(id)) {
+      return;
+    }
+    visited.add(id);
+    const mod = server.moduleGraph.getModuleById(id);
+    if (!mod) {
+      return;
+    }
+    await Promise.all(
+      [...mod.importedModules].map((childMod) => traverse(childMod.url)),
+    );
+  }
+
+  // ensure vite's import analysis is ready _only_ for top entries to not go too aggresive
+  await Promise.all(entries.map((e) => server.transformRequest(e)));
+
+  // traverse
+  await Promise.all(entries.map((url) => traverse(url)));
+
+  // filter
+  return [...visited].filter((url) => isCSSRequest(url));
+}