@mehdad67/apitogo 0.1.24

package/src/vite/pagefind-dev-index.ts

@@ -0,0 +1,100 @@
+import path from "node:path";
+import { createIndex, type PagefindIndex } from "pagefind";
+import { isRunnableDevEnvironment, type ViteDevServer } from "vite";
+import type { LoadedConfig } from "../config/config.js";
+import invariant from "../lib/util/invariant.js";
+import { joinUrl } from "../lib/util/joinUrl.js";
+import { getAppServerEntryPath } from "./config.js";
+import { getDevHtml } from "./html.js";
+import { routesToPaths } from "./prerender/utils.js";
+
+type EntryServerImport = typeof import("../app/entry.server.js");
+
+export type IndexProgress = {
+  type: "progress";
+  total: number;
+  current: number;
+  path: string;
+};
+
+export type IndexComplete = {
+  type: "complete";
+  success: boolean;
+  indexed: number;
+  error?: string;
+};
+
+export type IndexEvent = IndexProgress | IndexComplete;
+
+export async function* buildPagefindDevIndex(
+  vite: ViteDevServer,
+  config: LoadedConfig,
+): AsyncGenerator<IndexEvent> {
+  const { index, errors } = await createIndex();
+  invariant(index, `Failed to create pagefind index: ${errors.join(", ")}`);
+
+  const pagefindIndex: PagefindIndex = index;
+  const ssrEnvironment = vite.environments.ssr;
+
+  if (!isRunnableDevEnvironment(ssrEnvironment)) {
+    throw new Error("SSR environment is not runnable");
+  }
+
+  // Import the entry server module
+  const serverModule = (await ssrEnvironment.runner.import(
+    getAppServerEntryPath(),
+  )) as EntryServerImport;
+
+  const routes = serverModule.getRoutesByConfig(config);
+  const paths = routesToPaths(routes);
+  const { basePath } = config;
+
+  const template = getDevHtml({
+    jsEntry: "/__z/entry.client.tsx",
+    dir: config.site?.dir,
+  });
+  const transformedTemplate = await vite.transformIndexHtml("/", template);
+
+  let indexed = 0;
+
+  for (const urlPath of paths) {
+    try {
+      const pathname = joinUrl(basePath, urlPath);
+      const url = joinUrl("http://localhost", pathname);
+      const request = new Request(url);
+
+      const response = await serverModule.handleRequest({
+        template: transformedTemplate,
+        request,
+        routes,
+        basePath,
+        bypassProtection: true,
+      });
+
+      if (response.status < 400 && response.body) {
+        const content = await response.text();
+        await pagefindIndex.addHTMLFile({
+          url: urlPath,
+          content,
+        });
+        indexed++;
+      }
+    } catch (error) {
+      // biome-ignore lint/suspicious/noConsole: Log errors during indexing
+      console.error(`Failed to index ${urlPath}:`, error);
+    }
+
+    yield {
+      type: "progress",
+      total: paths.length,
+      current: indexed,
+      path: urlPath,
+    };
+  }
+
+  // Write the index to public/pagefind
+  const outputPath = path.join(vite.config.publicDir, "pagefind");
+  await pagefindIndex.writeFiles({ outputPath });
+
+  yield { type: "complete", success: true, indexed };
+}

package/src/vite/pagefind-dev-stub.ts

@@ -0,0 +1,17 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const NOT_BUILT_YET = 'throw new Error("NOT_BUILT_YET");';
+
+/**
+ * Writes a minimal `pagefind.js` under the Vite public dir so dev-time
+ * `import("/pagefind/pagefind.js")` resolves and the real index can be built later.
+ */
+export async function ensurePagefindDevStub(publicDir: string): Promise<void> {
+  const pagefindPath = path.join(publicDir, "pagefind/pagefind.js");
+  const exists = await fs.stat(pagefindPath).catch(() => false);
+  if (!exists) {
+    await fs.mkdir(path.dirname(pagefindPath), { recursive: true });
+    await fs.writeFile(pagefindPath, NOT_BUILT_YET);
+  }
+}

package/src/vite/plugin-api-keys.ts

@@ -0,0 +1,55 @@
+import type { Plugin } from "vite";
+import { ZuploEnv } from "../app/env.js";
+import { getCurrentConfig } from "../config/loader.js";
+import { getZuploSystemConfigurations } from "./zuplo.js";
+
+const viteApiKeysPlugin = (): Plugin => {
+  const virtualModuleId = "virtual:zudoku-api-keys-plugin";
+  const resolvedVirtualModuleId = `\0${virtualModuleId}`;
+  return {
+    name: "zudoku-api-keys-plugin",
+    resolveId(id) {
+      if (id === virtualModuleId) {
+        return resolvedVirtualModuleId;
+      }
+    },
+    async load(id) {
+      if (id === resolvedVirtualModuleId) {
+        const config = getCurrentConfig();
+        const apiKeysPath = config.__resolvedModules.userPanel.apiKeys.path;
+
+        if (
+          !config.__resolvedModules.userPanel.apiKeys.enabled ||
+          config.__meta.mode === "standalone"
+        ) {
+          return `export const configuredApiKeysPlugin = undefined;`;
+        }
+
+        const deploymentName =
+          ZuploEnv.buildConfig?.deploymentName ||
+          getZuploSystemConfigurations(process.env.ZUPLO_SYSTEM_CONFIGURATIONS)
+            ?.__ZUPLO_DEPLOYMENT_NAME;
+
+        const code = [
+          `import config from "virtual:zudoku-config";`,
+          config.__meta.mode === "internal"
+            ? `import { apiKeyPlugin } from "${config.__meta.moduleDir}/src/lib/plugins/api-keys/index.tsx";`
+            : `import { apiKeyPlugin } from "@lukoweb/apitogo/plugins/api-keys";`,
+          `export const configuredApiKeysPlugin = apiKeyPlugin({
+            ...config.apiKeys,
+            path: "${apiKeysPath}",
+            isZuplo: ${ZuploEnv.isZuplo},
+            ${deploymentName ? `deploymentName: "${deploymentName}"` : ""}
+          });`,
+        ];
+
+        return {
+          code: code.join("\n"),
+          map: null,
+        };
+      }
+    },
+  };
+};
+
+export default viteApiKeysPlugin;

package/src/vite/plugin-api.ts

@@ -0,0 +1,323 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { deepEqual } from "fast-equals";
+import { type Plugin, runnerImport } from "vite";
+import { ZuploEnv } from "../app/env.js";
+import { getZudokuRootDir } from "../cli/common/package-json.js";
+import { getCurrentConfig } from "../config/loader.js";
+import {
+  getBuildConfig,
+  type Processor,
+} from "../config/validators/BuildSchema.js";
+import { getAllTags } from "../lib/oas/graphql/index.js";
+import type {
+  ApiCatalogItem,
+  ApiCatalogPluginOptions,
+} from "../lib/plugins/api-catalog/index.js";
+import type { VersionedInput } from "../lib/plugins/openapi/interfaces.js";
+import { ensureArray } from "../lib/util/ensureArray.js";
+import { SchemaManager } from "./api/SchemaManager.js";
+import { reload } from "./plugin-config-reload.js";
+import { invalidate as invalidateNavigation } from "./plugin-navigation.js";
+
+const viteApiPlugin = async (): Promise<Plugin> => {
+  const virtualModuleId = "virtual:zudoku-api-plugins";
+  const resolvedVirtualModuleId = `\0${virtualModuleId}`;
+
+  const initialConfig = getCurrentConfig();
+
+  // Load Zuplo-specific processors if in Zuplo environment
+  const zuploProcessors = ZuploEnv.isZuplo
+    ? await runnerImport<{ default: (rootDir: string) => Processor[] }>(
+        path.resolve(getZudokuRootDir(), "src/zuplo/with-zuplo-processors.ts"),
+      ).then((m) => m.module.default(initialConfig.__meta.rootDir))
+    : [];
+
+  const buildConfig = await getBuildConfig();
+  const buildProcessors = buildConfig?.processors ?? [];
+
+  const tmpStoreDir = path.posix.join(
+    initialConfig.__meta.rootDir,
+    "node_modules/.apitogo/processed",
+  );
+
+  const processors = [...buildProcessors, ...zuploProcessors];
+  const schemaManager = new SchemaManager({
+    storeDir: tmpStoreDir,
+    config: initialConfig,
+    processors,
+  });
+
+  return {
+    name: "zudoku-api-plugins",
+    async buildStart() {
+      await fs.rm(tmpStoreDir, { recursive: true, force: true });
+      await fs.mkdir(tmpStoreDir, { recursive: true });
+
+      await schemaManager.processAllSchemas();
+
+      schemaManager
+        .getAllTrackedFiles()
+        .forEach((file) => this.addWatchFile(file));
+    },
+    configureServer(server) {
+      // Serve original OpenAPI schema files
+      server.middlewares.use(async (req, res, next) => {
+        if (req.method !== "GET" || !req.url) return next();
+        if (
+          !req.url.toLowerCase().endsWith(".json") &&
+          !req.url.toLowerCase().endsWith(".yaml")
+        ) {
+          return next();
+        }
+
+        const pathMap = schemaManager.getUrlToFilePathMap();
+
+        const inputPath = pathMap.get(req.url);
+        if (!inputPath) return next();
+
+        const content = await fs.readFile(inputPath, "utf-8");
+        const mimeType =
+          path.extname(inputPath).toLowerCase() === ".json"
+            ? "application/json"
+            : "application/x-yaml";
+
+        res.setHeader("Content-Type", `${mimeType}; charset=utf-8`);
+        return res.end(content);
+      });
+
+      server.watcher.on("change", async (id) => {
+        const mainFiles = schemaManager.getFilesToReprocess(id);
+        if (mainFiles.length === 0) return;
+
+        // biome-ignore lint/suspicious/noConsole: Logging allowed here
+        console.log(`Re-processing schema ${id}`);
+
+        for (const inputConfig of mainFiles) {
+          await schemaManager.processSchema(inputConfig);
+        }
+        schemaManager
+          .getAllTrackedFiles()
+          .forEach((file) => server.watcher.add(file));
+
+        invalidateNavigation(server);
+        reload(server);
+      });
+    },
+    resolveId(id) {
+      if (id === virtualModuleId) {
+        return resolvedVirtualModuleId;
+      }
+    },
+    async load(id) {
+      if (id !== resolvedVirtualModuleId) return;
+
+      const config = getCurrentConfig();
+
+      if (!deepEqual(schemaManager.config.apis, config.apis)) {
+        schemaManager.config = config;
+        await schemaManager.processAllSchemas();
+        schemaManager
+          .getAllTrackedFiles()
+          .forEach((file) => this.addWatchFile(file));
+      }
+
+      if (
+        config.__meta.mode === "standalone" ||
+        !config.__resolvedModules.docs.enabled
+      ) {
+        return [
+          "export const configuredApiPlugins = [];",
+          "export const configuredApiCatalogPlugins = [];",
+        ].join("\n");
+      }
+
+      const code = [
+        `import config from "virtual:zudoku-config";`,
+        `const configuredApiPlugins = [];`,
+        `const configuredApiCatalogPlugins = [];`,
+      ];
+
+      if (config.apis) {
+        code.push(
+          'import { openApiPlugin } from "@lukoweb/apitogo/plugins/openapi";',
+        );
+        code.push(
+          `const apis = Array.isArray(config.apis) ? config.apis : [config.apis]`,
+        );
+        const apis = ensureArray(config.apis);
+        const apiMetadata: ApiCatalogItem[] = [];
+
+        for (const apiConfig of apis) {
+          if (apiConfig.type === "file" && apiConfig.path) {
+            const latestSchema = schemaManager.getLatestSchema(apiConfig.path);
+            if (!latestSchema?.schema.info) continue;
+
+            apiMetadata.push({
+              path: apiConfig.path,
+              label: latestSchema.schema.info.title,
+              description: latestSchema.schema.info.description ?? "",
+              categories: apiConfig.categories ?? [],
+            });
+          }
+        }
+
+        // Generate API plugin code
+        let apiIndex = -1;
+        for (const apiConfig of apis) {
+          apiIndex++;
+          if (apiConfig.type === "file") {
+            if (!apiConfig.path) continue;
+
+            const schemas = schemaManager.getSchemasForPath(apiConfig.path);
+
+            if (!schemas?.length) continue;
+
+            const allSlugs = new Set<string>();
+            const versionedInput = schemas.map<VersionedInput>((s) => {
+              const versionTags = getAllTags(s.schema);
+              versionTags.forEach(({ slug }) => {
+                if (slug) allSlugs.add(slug);
+              });
+
+              return {
+                path: s.path,
+                version: s.version,
+                downloadUrl: s.downloadUrl,
+                label: s.label ?? s.schema.info?.version,
+                input: s.importKey,
+                hasUntaggedOperations: versionTags.some(
+                  (tag) => tag.name === undefined,
+                ),
+                tagPages: versionTags.flatMap((t) => t.slug ?? []),
+              };
+            });
+
+            const tags = Array.from(allSlugs);
+
+            const schemaImports = schemaManager.getSchemaImports();
+
+            code.push(
+              "configuredApiPlugins.push(openApiPlugin({",
+              `  type: "file",`,
+              `  input: ${JSON.stringify(versionedInput)},`,
+              `  path: ${JSON.stringify(apiConfig.path)},`,
+              `  tagPages: ${JSON.stringify(tags)},`,
+              `  options: {`,
+              `    examplesLanguage: config.defaults?.apis?.examplesLanguage ?? config.defaults?.examplesLanguage,`,
+              `    supportedLanguages: config.defaults?.apis?.supportedLanguages,`,
+              `    disablePlayground: config.defaults?.apis?.disablePlayground,`,
+              `    disableSidecar: config.defaults?.apis?.disableSidecar,`,
+              `    showVersionSelect: config.defaults?.apis?.showVersionSelect ?? "if-available",`,
+              `    expandAllTags: config.defaults?.apis?.expandAllTags ?? true,`,
+              `    showInfoPage: config.defaults?.apis?.showInfoPage ?? true,`,
+              `    schemaDownload: config.defaults?.apis?.schemaDownload,`,
+              `    transformExamples: config.defaults?.apis?.transformExamples,`,
+              `    generateCodeSnippet: config.defaults?.apis?.generateCodeSnippet,`,
+              `    ...(apis[${apiIndex}].options ?? {}),`,
+              `  },`,
+              `  schemaImports: {`,
+              ...schemaImports.map(
+                (s) =>
+                  `    "${s.importKey.replaceAll("\\", "\\\\")}": () => import("${s.importKey.replaceAll("\\", "/")}?d=${s.processedTime}"),`,
+              ),
+              `  },`,
+              "}));",
+            );
+          } else {
+            code.push(
+              "configuredApiPlugins.push(openApiPlugin({",
+              `  ...${JSON.stringify(apiConfig)},`,
+              "  options: {",
+              `    examplesLanguage: config.defaults?.apis?.examplesLanguage ?? config.defaults?.examplesLanguage,`,
+              `    supportedLanguages: config.defaults?.apis?.supportedLanguages,`,
+              `    disablePlayground: config.defaults?.apis?.disablePlayground,`,
+              `    disableSidecar: config.defaults?.apis?.disableSidecar,`,
+              `    showVersionSelect: config.defaults?.apis?.showVersionSelect ?? "if-available",`,
+              `    expandAllTags: config.defaults?.apis?.expandAllTags ?? false,`,
+              `    showInfoPage: config.defaults?.apis?.showInfoPage ?? true,`,
+              `    schemaDownload: config.defaults?.apis?.schemaDownload,`,
+              `    ...${JSON.stringify(apiConfig.options ?? {})},`,
+              "  },",
+              "}));",
+            );
+          }
+        }
+
+        if (config.catalogs) {
+          code.push(
+            'import { apiCatalogPlugin } from "@lukoweb/apitogo/plugins/api-catalog";',
+          );
+
+          const catalogs = ensureArray(config.catalogs);
+
+          const categories = apis
+            .flatMap((api) => api.categories ?? [])
+            .reduce((acc, catalog) => {
+              if (!acc.has(catalog.label)) {
+                acc.set(catalog.label ?? "", new Set(catalog.tags));
+              }
+              for (const tag of catalog.tags) {
+                acc.get(catalog.label ?? "")?.add(tag);
+              }
+              return acc;
+            }, new Map<string, Set<string>>());
+
+          const categoryList = Array.from(categories.entries()).map(
+            ([label, tags]) => ({
+              label,
+              tags: Array.from(tags),
+            }),
+          );
+
+          for (let i = 0; i < catalogs.length; i++) {
+            const catalog = catalogs[i];
+            if (!catalog) {
+              continue;
+            }
+            const apiCatalogConfig: ApiCatalogPluginOptions = {
+              ...catalog,
+              items: apiMetadata,
+              label: catalog.label,
+              categories: categoryList,
+              filterCatalogItems: catalog.filterItems,
+            };
+
+            code.push(
+              `configuredApiCatalogPlugins.push(apiCatalogPlugin({`,
+              `  ...${JSON.stringify(apiCatalogConfig, null, 2)},`,
+              `  filterCatalogItems: Array.isArray(config.catalogs)`,
+              `    ? config.catalogs[${i}].filterItems`,
+              `    : config.catalogs.filterItems,`,
+              `}));`,
+            );
+          }
+        }
+      }
+
+      code.push(
+        `export { configuredApiPlugins, configuredApiCatalogPlugins };`,
+      );
+
+      return code.join("\n");
+    },
+    async closeBundle() {
+      if (this.environment.name === "ssr") return;
+
+      const config = getCurrentConfig();
+      const pathMap = schemaManager.getUrlToFilePathMap();
+
+      if (process.env.NODE_ENV !== "production") return;
+
+      for (const [urlPath, inputPath] of pathMap) {
+        const content = await fs.readFile(inputPath, "utf-8");
+        const outputPath = path.join(config.__meta.rootDir, "dist", urlPath);
+
+        await fs.mkdir(path.dirname(outputPath), { recursive: true });
+        await fs.writeFile(outputPath, content, "utf-8");
+      }
+    },
+  };
+};
+
+export default viteApiPlugin;

package/src/vite/plugin-auth.ts

@@ -0,0 +1,42 @@
+import type { Plugin } from "vite";
+import { getCurrentConfig } from "../config/loader.js";
+
+const viteAuthPlugin = (): Plugin => {
+  const virtualModuleId = "virtual:zudoku-auth";
+  const resolvedVirtualModuleId = `\0${virtualModuleId}`;
+
+  return {
+    name: "zudoku-auth-plugin", // required, will show up in warnings and errors
+    resolveId(id) {
+      if (id === virtualModuleId) {
+        return resolvedVirtualModuleId;
+      }
+    },
+    async load(id) {
+      if (id === resolvedVirtualModuleId) {
+        const config = getCurrentConfig();
+
+        if (
+          !config.authentication ||
+          !config.__resolvedModules.userPanel.userManagement.enabled ||
+          config.__meta.mode === "standalone"
+        ) {
+          return `export const configuredAuthProvider = undefined;`;
+        }
+        // TODO: Validate that the authConfig.type is a valid authentication provider
+        return [
+          `const config = {
+            ...${JSON.stringify(config.authentication, null, 2)},
+            basePath: ${config.basePath ? JSON.stringify(config.basePath) : "undefined"},
+          };`,
+          config.__meta.mode === "internal"
+            ? `import authProvider from "${config.__meta.moduleDir}/src/lib/authentication/providers/${config.authentication.type}.tsx";`
+            : `import authProvider from "@lukoweb/apitogo/auth/${config.authentication.type}";`,
+          `export const configuredAuthProvider = authProvider(config);`,
+        ].join("\n");
+      }
+    },
+  };
+};
+
+export default viteAuthPlugin;

package/src/vite/plugin-component.ts

@@ -0,0 +1,45 @@
+import path from "node:path";
+import type { Plugin } from "vite";
+import { getCurrentConfig } from "../config/loader.js";
+
+const viteAliasPlugin = (): Plugin => {
+  return {
+    name: "zudoku-component-plugin",
+    config: () => {
+      const config = getCurrentConfig();
+
+      const replacements = [
+        ["@lukoweb/apitogo/components", "src/lib/components/index.ts"],
+        [
+          "@lukoweb/apitogo/plugins/openapi",
+          "src/lib/plugins/openapi/index.tsx",
+        ],
+        [
+          "@lukoweb/apitogo/plugins/api-catalog",
+          "src/lib/plugins/api-catalog/index.tsx",
+        ],
+        [
+          "@lukoweb/apitogo/plugins/search-inkeep",
+          "src/lib/plugins/search-inkeep/index.tsx",
+        ],
+        [
+          "@lukoweb/apitogo/plugins/search-pagefind",
+          "src/lib/plugins/search-pagefind/index.tsx",
+        ],
+        [/^@lukoweb\/apitogo\/ui\/(.*)\.js/, "src/lib/ui/$1.tsx"],
+      ] as const;
+
+      const aliases = replacements.map(([find, replacement]) => ({
+        find,
+        replacement: path.posix.join(config.__meta.moduleDir, replacement),
+      }));
+
+      return config.__meta.mode === "internal" ||
+        config.__meta.mode === "standalone"
+        ? { resolve: { alias: aliases } }
+        : undefined;
+    },
+  };
+};
+
+export default viteAliasPlugin;

package/src/vite/plugin-config-reload.ts

@@ -0,0 +1,49 @@
+import path from "node:path";
+import colors from "picocolors";
+import type { Plugin, ViteDevServer } from "vite";
+import { logger } from "../cli/common/logger.js";
+import { getCurrentConfig } from "../config/loader.js";
+import { invalidate as invalidateNavigation } from "./plugin-navigation.js";
+
+export const reload = ({ ws, environments }: ViteDevServer) => {
+  Object.values(environments).forEach((environment) => {
+    environment.moduleGraph.invalidateAll();
+  });
+
+  ws.send({ type: "full-reload" });
+};
+
+export const viteConfigReloadPlugin = (): Plugin => ({
+  name: "zudoku-config-reload",
+  configureServer: (server) => {
+    const initialConfig = getCurrentConfig();
+    let importDependencies = initialConfig.__meta.dependencies;
+    server.watcher.on("change", async (file) => {
+      if (
+        !importDependencies.includes(file) &&
+        file !== initialConfig.__meta.configPath
+      ) {
+        return;
+      }
+
+      const currentConfig = getCurrentConfig();
+      importDependencies = currentConfig.__meta.dependencies;
+
+      // Assume `.tsx` files are handled by HMR (skip if the config file itself changed)
+      if (file !== currentConfig.__meta.configPath && file.endsWith(".tsx"))
+        return;
+
+      invalidateNavigation(server);
+      Object.values(server.environments).forEach((env) => {
+        env.moduleGraph.invalidateAll();
+      });
+
+      logger.info(
+        colors.blue(
+          `Config ${path.basename(currentConfig.__meta.configPath)} changed. Reloading...`,
+        ),
+        { timestamp: true },
+      );
+    });
+  },
+});