@next-vibe/checker 1.0.11 → 1.0.12

package/src/app/api/[locale]/system/generators/route-handlers/repository.ts

@@ -0,0 +1,277 @@
+/**
+ * Route Handlers Generator Repository
+ * Generates route-handlers.ts with dynamic imports and flat path structure
+ */
+
+import "server-only";
+
+import { join } from "node:path";
+
+import type { ResponseType as BaseResponseType } from "next-vibe/shared/types/response.schema";
+import {
+  ErrorResponseTypes,
+  fail,
+  success,
+} from "next-vibe/shared/types/response.schema";
+import { parseError } from "next-vibe/shared/utils/parse-error";
+
+import type { EndpointLogger } from "@/app/api/[locale]/system/unified-interface/shared/logger/endpoint";
+import {
+  formatCount,
+  formatDuration,
+  formatGenerator,
+} from "@/app/api/[locale]/system/unified-interface/shared/logger/formatters";
+import type { ApiSection } from "@/app/api/[locale]/system/unified-interface/shared/types/endpoint";
+import { PATH_SEPARATOR } from "@/app/api/[locale]/system/unified-interface/shared/utils/path";
+
+import {
+  extractPathKey,
+  findFilesRecursively,
+  generateAbsoluteImportPath,
+  generateFileHeader,
+  writeGeneratedFile,
+} from "../shared/utils";
+
+// Type definitions
+interface RouteHandlersRequestType {
+  outputFile: string;
+  dryRun: boolean;
+}
+
+interface RouteHandlersResponseType {
+  success: boolean;
+  message: string;
+  routesFound: number;
+  duration: number;
+  outputFile?: string;
+}
+
+/**
+ * Route Handlers Generator Repository Interface
+ */
+interface RouteHandlersGeneratorRepository {
+  generateRouteHandlers(
+    data: RouteHandlersRequestType,
+    logger: EndpointLogger,
+  ): Promise<BaseResponseType<RouteHandlersResponseType>>;
+}
+
+/**
+ * Route Handlers Generator Repository Implementation
+ */
+class RouteHandlersGeneratorRepositoryImpl implements RouteHandlersGeneratorRepository {
+  async generateRouteHandlers(
+    data: RouteHandlersRequestType,
+    logger: EndpointLogger,
+  ): Promise<BaseResponseType<RouteHandlersResponseType>> {
+    const startTime = Date.now();
+
+    try {
+      const outputFile = data.outputFile;
+      logger.debug("Starting route handlers generation", {
+        outputFile,
+      });
+
+      // Discover route files
+      // eslint-disable-next-line i18next/no-literal-string
+      const apiCorePath = ["src", "app", "api", "[locale]"];
+      const startDir = join(process.cwd(), ...apiCorePath);
+
+      logger.debug("Discovering route files");
+      const routeFiles = findFilesRecursively(startDir, "route.ts");
+
+      logger.debug(`Found ${routeFiles.length} route files`);
+
+      // Generate content
+      const content = await this.generateContent(routeFiles);
+
+      // Write file
+      await writeGeneratedFile(outputFile, content, data.dryRun);
+
+      const duration = Date.now() - startTime;
+
+      logger.info(
+        formatGenerator(
+          `Generated route handlers file with ${formatCount(routeFiles.length, "route")} in ${formatDuration(duration)}`,
+          "🔗",
+        ),
+      );
+
+      return success({
+        success: true,
+        message: "app.api.system.generators.endpoints.success.generated",
+        routesFound: routeFiles.length,
+        duration,
+        outputFile: data.dryRun ? undefined : outputFile,
+      });
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      logger.error("Route handlers generation failed", {
+        error: parseError(error),
+        duration,
+      });
+
+      return fail({
+        message: "app.api.system.generators.endpoints.post.errors.server.title",
+        errorType: ErrorResponseTypes.INTERNAL_ERROR,
+        messageParams: {
+          duration,
+        },
+      });
+    }
+  }
+
+  /**
+   * Extract HTTP methods from definition file (async)
+   * We extract from definition instead of route because route files have server-only dependencies
+   */
+  private async extractMethodsFromDefinition(
+    routeFile: string,
+  ): Promise<string[]> {
+    const definitionPath = routeFile.replace("/route.ts", "/definition.ts");
+    try {
+      const definition = (await import(definitionPath)) as {
+        default?: ApiSection;
+      };
+      const defaultExport = definition.default;
+
+      if (!defaultExport) {
+        return [];
+      }
+
+      // Get all HTTP methods from the definition
+      const methods = Object.keys(defaultExport).filter((key) =>
+        ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"].includes(
+          key,
+        ),
+      );
+      return methods;
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Extract aliases from definition file (async)
+   */
+  private async extractAliasesFromDefinition(
+    routeFile: string,
+  ): Promise<Array<{ alias: string; method: string }>> {
+    const definitionPath = routeFile.replace("/route.ts", "/definition.ts");
+    try {
+      const definition = (await import(definitionPath)) as {
+        default?: Record<string, { aliases?: string[] }>;
+      };
+      const defaultExport = definition.default;
+
+      if (!defaultExport) {
+        return [];
+      }
+
+      const aliasesWithMethods: Array<{ alias: string; method: string }> = [];
+
+      // Get aliases from each method
+      for (const method of Object.keys(defaultExport)) {
+        const methodDef = defaultExport[method];
+        if (methodDef?.aliases && Array.isArray(methodDef.aliases)) {
+          for (const alias of methodDef.aliases) {
+            aliasesWithMethods.push({ alias, method });
+          }
+        }
+      }
+
+      return aliasesWithMethods;
+    } catch {
+      // Definition file doesn't exist or can't be loaded
+    }
+    return [];
+  }
+
+  /**
+   * Generate route handlers content with dynamic imports and real aliases from definitions
+   * Main paths include method suffix (e.g., "core/agent/ai-stream/POST")
+   * Aliases also include method from their definition
+   */
+  private async generateContent(routeFiles: string[]): Promise<string> {
+    const pathMap: Record<string, { importPath: string; method: string }> = {};
+    const allPaths: string[] = [];
+
+    // Build path map with method suffixes and aliases (deduplicate)
+    for (const routeFile of routeFiles) {
+      const { path } = extractPathKey(routeFile);
+      const importPath = generateAbsoluteImportPath(routeFile, "route");
+
+      // Get methods for this route from definition file
+      const methods = await this.extractMethodsFromDefinition(routeFile);
+
+      // Add main path with method suffix for each method (e.g., "v1_core_agent_ai-stream_POST")
+      for (const method of methods) {
+        const pathWithMethod = `${path}${PATH_SEPARATOR}${method}`;
+        if (!pathMap[pathWithMethod]) {
+          pathMap[pathWithMethod] = { importPath, method };
+          allPaths.push(pathWithMethod);
+        }
+      }
+
+      // Extract and add real aliases from definition file (with their method)
+      const definitionAliases =
+        await this.extractAliasesFromDefinition(routeFile);
+      for (const { alias, method } of definitionAliases) {
+        // Only add if not already present (first wins)
+        if (!pathMap[alias]) {
+          pathMap[alias] = { importPath, method };
+          allPaths.push(alias);
+        }
+      }
+    }
+
+    // Sort paths for consistent output
+    allPaths.sort();
+
+    // Generate getRouteHandler function cases with type-safe loading
+    const cases: string[] = [];
+    for (const path of allPaths) {
+      const { importPath } = pathMap[path];
+      // Return the handler - all handlers conform to GenericHandlerBase structurally
+      // The type assertion is safe because all handlers accept the same props shape
+      // eslint-disable-next-line i18next/no-literal-string
+      cases.push(`    case "${path}":
+      return (await import("${importPath}")).tools.${pathMap[path].method} as GenericHandlerBase;`);
+    }
+
+    // eslint-disable-next-line i18next/no-literal-string
+    const autoGenTitle = "AUTO-GENERATED FILE - DO NOT EDIT";
+    const generatorName = "generators/route-handlers";
+    const header = generateFileHeader(autoGenTitle, generatorName, {
+      "Routes found": routeFiles.length,
+      "Total paths (with aliases)": allPaths.length,
+    });
+
+    // eslint-disable-next-line i18next/no-literal-string
+    return `${header}
+
+import type { GenericHandlerBase } from "../unified-interface/shared/endpoints/route/handler";
+
+/* eslint-disable prettier/prettier */
+/* eslint-disable i18next/no-literal-string */
+
+/**
+ * Dynamically import route handler by path
+ * @param path - The route path (e.g., "core/agent/chat/threads")
+ * @returns The route module or null if not found
+ */
+export async function getRouteHandler(
+  path: string,
+): Promise<GenericHandlerBase | null> {
+  switch (path) {
+${cases.join("\n")}
+    default:
+      return null;
+  }
+}
+`;
+  }
+}
+
+export const routeHandlersGeneratorRepository =
+  new RouteHandlersGeneratorRepositoryImpl();

package/src/app/api/[locale]/system/generators/route-handlers/route.ts

@@ -0,0 +1,17 @@
+import { endpointsHandler } from "@/app/api/[locale]/system/unified-interface/shared/endpoints/route/multi";
+import { Methods } from "@/app/api/[locale]/system/unified-interface/shared/types/enums";
+
+import definitions from "./definition";
+import { routeHandlersGeneratorRepository } from "./repository";
+
+export const { POST, tools } = endpointsHandler({
+  endpoint: definitions,
+  [Methods.POST]: {
+    handler: async (props) => {
+      return await routeHandlersGeneratorRepository.generateRouteHandlers(
+        props.data,
+        props.logger,
+      );
+    },
+  },
+});

package/src/app/api/[locale]/system/generators/shared/utils.ts

@@ -0,0 +1,233 @@
+/**
+ * Shared Generator Utilities
+ * Simple utilities for all generators
+ */
+
+import "server-only";
+
+import { existsSync, mkdirSync, readdirSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+
+import { PATH_SEPARATOR } from "@/app/api/[locale]/system/unified-interface/shared/utils/path";
+
+/**
+ * Default directories to exclude from scanning
+ */
+export const DEFAULT_EXCLUDE_DIRS = [
+  "node_modules",
+  ".git",
+  ".next",
+  "dist",
+  ".dist",
+  "generated",
+];
+
+/**
+ * Recursively find files with specific filename in a directory
+ */
+export function findFilesRecursively(
+  dir: string,
+  targetFilename: string,
+  excludeDirs: string[] = DEFAULT_EXCLUDE_DIRS,
+): string[] {
+  const results: string[] = [];
+
+  if (!existsSync(dir)) {
+    return results;
+  }
+
+  const entries = readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+
+    // Skip excluded directories
+    if (entry.isDirectory() && excludeDirs.includes(entry.name)) {
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      // Recursively search subdirectories
+      results.push(
+        ...findFilesRecursively(fullPath, targetFilename, excludeDirs),
+      );
+    } else if (entry.isFile() && entry.name === targetFilename) {
+      // Found a matching file
+      results.push(fullPath);
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Get relative import path from source file to output file
+ */
+export function getRelativeImportPath(
+  sourceFile: string,
+  outputFile: string,
+): string {
+  const outputDir = dirname(outputFile);
+  let relativePath = relative(outputDir, sourceFile);
+
+  // Remove .ts extension and normalize path separators
+  relativePath = relativePath.replace(/\.ts$/, "").replaceAll("\\", "/");
+
+  // Ensure it starts with ./ or ../
+  if (!relativePath.startsWith(".")) {
+    relativePath = `./${relativePath}`;
+  }
+
+  return relativePath;
+}
+
+/**
+ * Extract nested path segments from a file path
+ * Example: src/app/api/[locale]/agent/chat/characters/definition.ts
+ * Returns: ["agent", "chat", "characters"]
+ */
+export function extractNestedPath(
+  filePath: string,
+  startMarker = "[locale]",
+  endMarker?: string,
+): string[] {
+  const pathParts = filePath.split("/");
+
+  const startIndex = pathParts.findIndex((p) => p === startMarker);
+  if (startIndex === -1) {
+    // eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax -- Build-time generator that throws for invalid configuration at startup
+    throw new Error(`Could not find ${startMarker} in path: ${filePath}`);
+  }
+
+  // If no end marker provided, auto-detect definition.ts or route.ts
+  let actualEndMarker = endMarker;
+  if (!actualEndMarker) {
+    if (pathParts.includes("definition.ts")) {
+      actualEndMarker = "definition.ts";
+    } else if (pathParts.includes("route.ts")) {
+      actualEndMarker = "route.ts";
+    } else {
+      // eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax -- Build-time generator that throws for invalid configuration at startup
+      throw new Error(
+        `Could not auto-detect end marker (definition.ts or route.ts) in path: ${filePath}`,
+      );
+    }
+  }
+
+  const endIndex = pathParts.findIndex((p) => p === actualEndMarker);
+  if (endIndex === -1) {
+    // eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax -- Build-time generator that throws for invalid configuration at startup
+    throw new Error(`Could not find ${actualEndMarker} in path: ${filePath}`);
+  }
+
+  // Extract path segments between locale and the target file
+  // Skip the [locale] marker itself, start from the next segment
+  return pathParts.slice(startIndex + 1, endIndex);
+}
+
+/**
+ * Extract module name from file path
+ * Example: .../core/leads/seeds.ts -> "leads"
+ * Example: .../core/emails/smtp-client/seeds.ts -> "smtp-client"
+ */
+export function extractModuleName(
+  filePath: string,
+  coreMarker = "core",
+): string {
+  const pathParts = filePath.split("/");
+  const coreIndex = pathParts.findIndex((p) => p === coreMarker);
+
+  if (coreIndex === -1 || coreIndex >= pathParts.length - 1) {
+    return pathParts.at(-2) || "unknown";
+  }
+
+  const moduleParts = pathParts.slice(coreIndex + 1, pathParts.length - 1);
+  return moduleParts.at(-1) || moduleParts.join("-");
+}
+
+/**
+ * Write generated content to file
+ */
+export async function writeGeneratedFile(
+  filePath: string,
+  content: string,
+  dryRun = false,
+): Promise<void> {
+  if (dryRun) {
+    return;
+  }
+
+  const outputDir = dirname(filePath);
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+  }
+
+  await writeFile(filePath, content, "utf8");
+}
+
+/**
+ * Generate standard file header
+ */
+export function generateFileHeader(
+  title: string,
+  generatedBy: string,
+  additionalInfo?: Record<string, string | number>,
+): string {
+  const lines = ["/**"];
+  lines.push(` * ${title}`);
+  lines.push(` * Generated by ${generatedBy}`);
+
+  if (additionalInfo) {
+    lines.push(" *");
+    for (const [key, value] of Object.entries(additionalInfo)) {
+      lines.push(` * ${key}: ${value}`);
+    }
+  }
+
+  lines.push(" */");
+
+  return lines.join("\n");
+}
+
+/**
+ * Sanitize a path segment to remove invalid characters for tool names
+ * Removes square brackets from dynamic routes like [id]
+ * This must match the sanitization in endpointToToolName to ensure consistency
+ */
+function sanitizePathSegment(segment: string): string {
+  // Remove square brackets to handle dynamic routes like [id]
+  // Example: "[id]" becomes "id", "[threadId]" becomes "threadId"
+  return segment.replaceAll(/\[|\]/g, "");
+}
+
+/**
+ * Extract path from definition file for flat structure
+ * Returns path only - no duplicate parameter format aliases
+ * Real aliases come from definition files, not parameter format variations
+ * Uses PATH_SEPARATOR constant for consistency
+ * Sanitizes path segments to match endpointToToolName behavior
+ */
+export function extractPathKey(
+  filePath: string,
+  startMarker = "[locale]",
+): { path: string } {
+  const nestedPath = extractNestedPath(filePath, startMarker);
+  // Sanitize each segment to remove brackets from dynamic routes
+  const sanitizedPath = nestedPath.map(sanitizePathSegment);
+  const path = sanitizedPath.join(PATH_SEPARATOR);
+  return { path };
+}
+
+/**
+ * Generate absolute import path for definition or route file
+ * nestedPath extracts segments after [locale], which we then append to the base path
+ */
+export function generateAbsoluteImportPath(
+  filePath: string,
+  fileType: "definition" | "route",
+): string {
+  const nestedPath = extractNestedPath(filePath);
+  const pathStr = nestedPath.join("/");
+  return `@/app/api/[locale]/${pathStr}/${fileType}`;
+}