@autobe/agent 0.21.0 → 0.22.0

package/src/orchestrate/realize/structures/IAutoBeRealizeAuthorizationCorrectApplication.ts

@@ -1,6 +1,26 @@
 import { IAutoBeRealizeAuthorizationApplication } from "./IAutoBeRealizeAuthorizationApplication";
 
 export interface IAutoBeRealizeAuthorizationCorrectApplication {
+  /**
+   * Corrects TypeScript compilation errors in authentication components.
+   *
+   * This method analyzes and fixes compilation errors in previously generated
+   * authentication provider, decorator, and payload type implementations. It
+   * performs systematic error diagnosis and generates corrected versions of
+   * all three components while maintaining their interconnected functionality.
+   *
+   * The correction process includes:
+   * - TypeScript error analysis and categorization by component
+   * - Identification of type mismatches, import issues, and syntax errors
+   * - Clear solution guidance for each identified problem
+   * - Regeneration of all components with fixes applied
+   *
+   * The corrected components maintain the same naming conventions and
+   * architectural patterns as the original generation while resolving all
+   * compilation issues.
+   *
+   * @param next Properties containing error analysis, solution guidance, and corrected components
+   */
   correctDecorator: (
     next: IAutoBeRealizeAuthorizationCorrectApplication.IProps,
   ) => void;

package/src/orchestrate/realize/structures/IAutoBeRealizeCorrectApplication.ts

@@ -1,81 +1,47 @@
-import { IAutoBeRealizeWriteApplication } from "./IAutoBeRealizeWriteApplication";
-
 export interface IAutoBeRealizeCorrectApplication {
+  /**
+   * Reviews and corrects TypeScript compilation errors.
+   *
+   * Fixes TypeScript compilation errors while preserving original business
+   * logic, applying minimal intervention principle.
+   *
+   * @param props Properties containing the multi-phase error correction process
+   */
   review: (props: IAutoBeRealizeCorrectApplication.IProps) => void;
 }
 
 export namespace IAutoBeRealizeCorrectApplication {
-  export interface IProps extends IAutoBeRealizeWriteApplication.IProps {
-    /**
-     * Compilation Error Analysis and Resolution Strategy
-     *
-     * This field contains a detailed analysis of TypeScript compilation errors
-     * that occurred during the previous compilation attempt, along with
-     * specific strategies to resolve each error.
-     *
-     * The analysis MUST include:
-     *
-     * 📊 ERROR BREAKDOWN:
-     *
-     * - List of all TypeScript error codes encountered (e.g., TS2339, TS2345)
-     * - Exact error messages and the lines/files where they occurred
-     * - Categorization of errors by type (type mismatch, missing property, etc.)
-     *
-     * 🔍 ROOT CAUSE ANALYSIS:
-     *
-     * - Why each error occurred (e.g., incorrect type assumptions, missing
-     *   fields)
-     * - Relationship between errors (e.g., cascading errors from a single issue)
-     * - Common patterns identified across multiple errors
-     *
-     * 🛠 RESOLUTION STRATEGY:
-     *
-     * - Specific fixes for each error type
-     * - Priority order for addressing errors (fix critical errors first)
-     * - Alternative approaches if the direct fix is not possible
-     *
-     * 📝 SCHEMA VERIFICATION:
-     *
-     * - Re-verification of Prisma schema fields actually available
-     * - Identification of assumed fields that don't exist
-     * - Correct field types and relationships
-     *
-     * ⚠️ COMMON ERROR PATTERNS TO CHECK:
-     *
-     * - Using non-existent fields (e.g., deleted_at, created_by)
-     * - Type mismatches in Prisma operations
-     * - Incorrect date handling (using Date instead of string)
-     * - Missing required fields in create/update operations
-     * - Incorrect relation handling in nested operations
-     *
-     * 🎯 CORRECTION APPROACH:
-     *
-     * - Remove references to non-existent fields
-     * - Fix type conversions (especially dates with toISOStringSafe())
-     * - Simplify complex nested operations into separate queries
-     * - Add missing required fields
-     * - Use correct Prisma input types
-     *
-     * Example structure:
-     *
-     *     Errors Found:
-     *     1. TS2339: Property 'deleted_at' does not exist on type 'User'
-     *        - Cause: Field assumed but not in schema
-     *        - Fix: Remove all deleted_at references
-     *
-     *     2. TS2345: Type 'Date' is not assignable to type 'string'
-     *        - Cause: Direct Date assignment without conversion
-     *        - Fix: Use toISOStringSafe() for all date values
-     *
-     *     Resolution Plan:
-     *     1. First, remove all non-existent field references
-     *     2. Then, fix all date type conversions
-     *     3. Finally, adjust Prisma query structures
-     *
-     * This analysis ensures the review process addresses all compilation errors
-     * systematically and produces error-free code in the corrected
-     * implementation.
-     */
-    errorAnalysis: string;
+  /**
+   * Properties for error correction following Chain of Thinking (CoT).
+   *
+   * All phases are wrapped in a `revise` object for systematic error
+   * resolution.
+   */
+  export interface IProps {
+    /** Revision process containing all error correction phases. */
+    revise: IRevise;
+  }
+
+  export interface IRevise {
+    /** Step 1: Compilation error analysis and resolution strategy. */
+    errorAnalysis?: string;
+
+    /** Step 2: Provider function implementation plan. */
+    plan?: string;
+
+    /** Step 3: Relevant Prisma schema definitions. */
+    prismaSchemas?: string;
+
+    /** Step 4: Initial draft without using native Date type. */
+    draftWithoutDateType?: string;
+
+    /** Step 5: Refined version with improved completeness. */
+    review?: string;
+
+    /** Step 6: Corrected implementation after compiler feedback. */
+    withCompilerFeedback?: string;
+
+    /** Step 7: Final complete TypeScript function implementation. */
+    implementationCode: string;
   }
 }

package/src/orchestrate/realize/structures/IAutoBeRealizeFunctionFailure.ts

@@ -0,0 +1,9 @@
+import {
+  AutoBeRealizeFunction,
+  IAutoBeTypeScriptCompileResult,
+} from "@autobe/interface";
+
+export interface IAutoBeRealizeFunctionFailure {
+  function: AutoBeRealizeFunction;
+  diagnostics: IAutoBeTypeScriptCompileResult.IDiagnostic[];
+}

package/src/orchestrate/realize/structures/IAutoBeRealizeScenarioResult.ts

@@ -0,0 +1,45 @@
+import {
+  AutoBeOpenApi,
+  AutoBeRealizeAuthorization,
+  AutoBeTestFile,
+} from "@autobe/interface";
+
+export interface IAutoBeRealizeScenarioResult {
+  /** The OpenAPI operation to be realized. */
+  operation: AutoBeOpenApi.IOperation;
+
+  /**
+   * The name of the function to be generated.
+   *
+   * Derived from the Swagger path and method. The function name must be
+   * written in snake_case. It serves as the entry point in both code
+   * generation and test code.
+   *
+   * Once the function is generated, the function name and file name will be
+   * the same. The generated file will be located at
+   * `src/providers/${function_name}.ts`.
+   */
+  functionName: string;
+
+  /** For example, `src/providers/${function_name}.ts`. */
+  location: string;
+
+  /**
+   * List of scenario descriptions for test code generation.
+   *
+   * Each scenario describes the expected behavior of the function under
+   * certain conditions. Used as a basis for TDD-style automated test
+   * generation.
+   */
+  testFiles: AutoBeTestFile[];
+
+  /**
+   * Optional decorator event for customizing code generation behavior.
+   *
+   * Provides additional metadata or instructions that can modify how the
+   * function implementation is generated. Can include custom annotations,
+   * middleware configurations, or special handling directives that affect the
+   * final code output.
+   */
+  decoratorEvent?: AutoBeRealizeAuthorization;
+}

package/src/orchestrate/realize/structures/IAutoBeRealizeWriteApplication.ts

@@ -1,11 +1,35 @@
 export interface IAutoBeRealizeWriteApplication {
+  /**
+   * Generates provider function implementation through multi-phase development.
+   *
+   * This method implements a systematic approach to generate NestJS provider
+   * functions that handle business logic for API operations. It follows a
+   * schema-first approach with multiple refinement phases to ensure type-safe,
+   * error-free code generation.
+   *
+   * The generation process includes:
+   * 1. Strategic planning based on Prisma schema analysis
+   * 2. Initial draft without Date type usage
+   * 3. Review and refinement for completeness
+   * 4. Compiler feedback integration if errors detected
+   * 5. Final implementation with all validations and type safety
+   *
+   * @param next Properties containing the multi-phase implementation plan and code
+   */
   coding: (next: IAutoBeRealizeWriteApplication.IProps) => void;
 }
 
 export namespace IAutoBeRealizeWriteApplication {
+  /**
+   * Properties for the Realize Write Application following Chain of Thinking (CoT).
+   * 
+   * Each field represents a distinct phase in the reasoning and implementation process,
+   * building upon the previous step to create a complete, error-free implementation.
+   * This structured approach ensures clarity, debuggability, and systematic thinking.
+   */
   export interface IProps {
     /**
-     * Step 1.
+     * Step 1 - Planning Phase (CoT: Initial Reasoning)
      *
      * 🧠 Provider Function Implementation Plan
      *
@@ -22,12 +46,14 @@ export namespace IAutoBeRealizeWriteApplication {
      * - Examine the actual Prisma schema model definition
      * - List EVERY field that exists in the model with exact types
      * - Explicitly note fields that DO NOT exist
+     * - Verify database compatibility (PostgreSQL AND SQLite)
      *
      * DO NOT:
      *
      * - Assume common fields exist without verification
      * - Use fields like deleted_at, created_by, updated_by, is_deleted, is_active
      *   without checking
+     * - Use PostgreSQL-specific features like mode: "insensitive"
      *
      * 📋 STEP 2 - FIELD INVENTORY:
      *
@@ -136,7 +162,7 @@ export namespace IAutoBeRealizeWriteApplication {
     plan: string;
 
     /**
-     * Step 2.
+     * Step 2 - Schema Definition (CoT: Context Establishment)
      *
      * The Prisma schema string that will be used to validate the implementation
      * logic in this file.
@@ -158,7 +184,7 @@ export namespace IAutoBeRealizeWriteApplication {
     prisma_schemas: string;
 
     /**
-     * Step 3.
+     * Step 3 - Initial Draft (CoT: First Implementation Attempt)
      *
      * Draft WITHOUT using native Date type.
      *
@@ -195,7 +221,7 @@ export namespace IAutoBeRealizeWriteApplication {
     draft_without_date_type: string;
 
     /**
-     * Step 4.
+     * Step 4 - Review and Refinement (CoT: Self-Reflection)
      *
      * A refined version of the draft with improved completeness.
      *
@@ -209,29 +235,13 @@ export namespace IAutoBeRealizeWriteApplication {
      * - Avoid unsafe `as` casts unless only for branding or literal narrowing.
      * - Use `toISOStringSafe()` for all date conversions (NOT `.toISOString()`).
      * - Ensure all object keys strictly conform to the expected type definitions.
+     * - NEVER use `mode: "insensitive"` in string operations (breaks SQLite).
      */
     review: string;
 
-    /**
-     * 🛠 Phase 4-2: With compiler feedback (optional)
-     *
-     * A correction pass that applies fixes for compile-time errors that arose
-     * during the review stage (if any).
-     *
-     * ✅ Must:
-     *
-     * - Only include this field if TypeScript errors are detected in the Review
-     *   phase.
-     * - Resolve all TypeScript errors without using `as any`.
-     * - Provide safe brand casting only if required (e.g., `as string &
-     *   tags.Format<'uuid'>`).
-     * - If no TypeScript errors exist, this field MUST contain the text: "No
-     *   TypeScript errors detected - skipping this phase"
-     */
-    withCompilerFeedback: string;
 
     /**
-     * Step 5.
+     * Step 5 - Complete Implementation (CoT: Final Synthesis)
      *
      * The complete and fully correct TypeScript function implementation.
      *
@@ -243,6 +253,7 @@ export namespace IAutoBeRealizeWriteApplication {
      * - Uses only allowed imports (e.g., from `../api/structures` and
      *   `MyGlobal.prisma`).
      * - NEVER creates intermediate variables for Prisma operations.
+     * - NEVER uses `mode: "insensitive"` (PostgreSQL-only, breaks SQLite).
      *
      * ⚠️ Fallback Behavior:
      *

package/src/orchestrate/realize/utils/getRealizeWriteCodeTemplate.ts

@@ -0,0 +1,97 @@
+import { AutoBeOpenApi, AutoBeRealizeAuthorization } from "@autobe/interface";
+import { StringUtil } from "@autobe/utils";
+
+import { IAutoBeRealizeScenarioResult } from "../structures/IAutoBeRealizeScenarioResult";
+import { getRealizeWriteImportStatements } from "./getRealizeWriteImportStatements";
+
+/**
+ * Generate a TypeScript function template for the Realize Agent to complete
+ *
+ * This utility creates a function skeleton with proper imports, parameters, and
+ * return type that the AI needs to implement. The template includes:
+ *
+ * - Import statements for required dependencies
+ * - Function signature with all parameters
+ * - Return type specification
+ *
+ * @example
+ *   // Returns a template like:
+ *   ```typescript
+ *   import { MyGlobal } from "../MyGlobal";
+ *   // ... other imports
+ *
+ *   async function post__users_create(
+ *     body: IUserCreateRequest
+ *   ): Promise<IUserResponse> {
+ *     ...
+ *   }
+ *   ```;
+ *
+ * @param scenario - The realize scenario containing function metadata
+ * @param operation - OpenAPI operation definition
+ * @param authorization - Authorization context if endpoint is authenticated
+ * @returns Complete TypeScript code template as a formatted string
+ */
+export function getRealizeWriteCodeTemplate(
+  scenario: IAutoBeRealizeScenarioResult,
+  operation: AutoBeOpenApi.IOperation,
+  authorization: AutoBeRealizeAuthorization | null,
+): string {
+  // Collect all function parameters in order
+  const functionParameters: string[] = [];
+
+  // Add authentication parameter if needed (e.g., user: IUser, admin: IAdmin)
+  if (authorization && authorization.role.name) {
+    // Debug: Log the values to check what's being used
+    const authParameter = `${authorization.role.name}: ${authorization.payload.name}`;
+    functionParameters.push(authParameter);
+  }
+
+  // Add path parameters (e.g., id, postId, etc.)
+  const pathParameters = operation.parameters.map((param) => {
+    const paramType = param.schema.type;
+    const paramFormat =
+      "format" in param.schema
+        ? ` & tags.Format<'${param.schema.format}'>`
+        : "";
+    return `${param.name}: ${paramType}${paramFormat}`;
+  });
+  functionParameters.push(...pathParameters);
+
+  // Add request body parameter if present
+  if (operation.requestBody?.typeName) {
+    const bodyParameter = `body: ${operation.requestBody.typeName}`;
+    functionParameters.push(bodyParameter);
+  }
+
+  // Format parameters for props object
+  const hasParameters = functionParameters.length > 0;
+
+  let formattedSignature: string;
+  if (hasParameters) {
+    const propsFields = functionParameters
+      .map((param) => `  ${param}`)
+      .join(";\n");
+
+    formattedSignature = `props: {\n${propsFields};\n}`;
+  } else {
+    formattedSignature = "";
+  }
+
+  // Determine return type
+  const returnType = operation.responseBody?.typeName ?? "void";
+
+  // Generate the complete template
+  return StringUtil.trim`
+    Complete the code below, disregard the import part and return only the function part.
+
+    \`\`\`typescript
+    ${getRealizeWriteImportStatements(operation).join("\n")} 
+
+    // ONLY YOU HAVE TO WRITE THIS, AND USE IMPORTED.
+    export async function ${scenario.functionName}(${formattedSignature}): Promise<${returnType}> {
+      ...
+    }
+    \`\`\`
+  `;
+}

package/src/orchestrate/realize/utils/getRealizeWriteDto.ts

@@ -0,0 +1,64 @@
+import { AutoBeOpenApi, IAutoBeCompiler } from "@autobe/interface";
+import { ILlmSchema, OpenApiTypeChecker } from "@samchon/openapi";
+
+import { AutoBeContext } from "../../../context/AutoBeContext";
+
+export async function getRealizeWriteDto<Model extends ILlmSchema.Model>(
+  ctx: AutoBeContext<Model>,
+  operation: AutoBeOpenApi.IOperation,
+): Promise<Record<string, string>> {
+  const document: AutoBeOpenApi.IDocument = filterDocument(
+    operation,
+    ctx.state().interface!.document,
+  );
+
+  const compiler: IAutoBeCompiler = await ctx.compiler();
+  const entries: [string, string][] = Object.entries(
+    await compiler.interface.write(document),
+  );
+
+  const filter = (prefix: string, exclude?: string) => {
+    const result: [string, string][] = entries.filter(
+      ([key]) => key.startsWith(prefix) === true,
+    );
+    return Object.fromEntries(
+      exclude
+        ? result.filter(([key]) => key.startsWith(exclude) === false)
+        : result,
+    );
+  };
+
+  const dto: Record<string, string> = filter("src/api/structures");
+  return dto;
+}
+
+function filterDocument(
+  operation: AutoBeOpenApi.IOperation,
+  document: AutoBeOpenApi.IDocument,
+): AutoBeOpenApi.IDocument {
+  const components: AutoBeOpenApi.IComponents = {
+    authorization: document.components.authorization,
+    schemas: {},
+  };
+
+  const visit = (typeName: string) => {
+    OpenApiTypeChecker.visit({
+      components: document.components,
+      schema: { $ref: `#/components/schemas/${typeName}` },
+      closure: (s) => {
+        if (OpenApiTypeChecker.isReference(s)) {
+          const key: string = s.$ref.split("/").pop()!;
+          components.schemas[key] = document.components.schemas[key];
+        }
+      },
+    });
+  };
+
+  if (operation.requestBody) visit(operation.requestBody.typeName);
+  if (operation.responseBody) visit(operation.responseBody.typeName);
+
+  return {
+    operations: [operation],
+    components,
+  };
+}

package/src/orchestrate/realize/utils/getRealizeWriteImportStatements.ts

@@ -0,0 +1,29 @@
+import { AutoBeOpenApi } from "@autobe/interface";
+
+export function getRealizeWriteImportStatements(
+  operation: AutoBeOpenApi.IOperation,
+) {
+  const typeReferences: string[] = Array.from(
+    new Set(
+      [operation.requestBody, operation.responseBody]
+        .filter((el) => el !== null)
+        .map((el) => el.typeName.split(".")[0]!),
+    ),
+  );
+
+  // Build the standard imports
+  const imports = [
+    'import jwt from "jsonwebtoken";',
+    'import { MyGlobal } from "../MyGlobal";',
+    'import typia, { tags } from "typia";',
+    'import { Prisma } from "@prisma/client";',
+    'import { v4 } from "uuid";',
+    'import { toISOStringSafe } from "../util/toISOStringSafe"',
+    ...typeReferences.map(
+      (ref) =>
+        `import { ${ref} } from "@ORGANIZATION/PROJECT-api/lib/structures/${ref}";`,
+    ),
+  ];
+
+  return imports;
+}

package/src/orchestrate/realize/utils/getRealizeWriteInputType.ts

@@ -0,0 +1,82 @@
+import { AutoBeOpenApi, AutoBeRealizeAuthorization } from "@autobe/interface";
+import { StringUtil } from "@autobe/utils";
+
+/**
+ * Generate TypeScript type definition string for provider function props
+ *
+ * This utility creates the exact props interface that the Realize Agent's
+ * generated provider functions must accept. It combines:
+ *
+ * - Authentication context (user/admin/member from authorization)
+ * - URL path parameters (e.g., id, boardId, postId)
+ * - Request body type (if applicable)
+ *
+ * The output is injected into REALIZE_WRITE_ARTIFACT.md template to tell the AI
+ * exactly what parameter type the function should accept.
+ *
+ * @example
+ *   // For DELETE /posts/:id (authenticated)
+ *   // Returns: "props: { user: IUser; id: string & tags.Format<'uuid'>; }"
+ *
+ * @example
+ *   // For GET /public/info (no auth, no params)
+ *   // Returns: "// No props parameter needed - function should have no parameters"
+ *
+ * @param operation - OpenAPI operation definition containing parameters and
+ *   auth requirements
+ * @param authorization - Authorization context with user/role information (if
+ *   authenticated endpoint)
+ * @returns TypeScript interface string like "props: { user: IUser; id: string;
+ *   body: IRequest; }"
+ */
+export function getRealizeWriteInputType(
+  operation: AutoBeOpenApi.IOperation,
+  authorization: AutoBeRealizeAuthorization | null,
+): string {
+  const functionParameterFields: string[] = [];
+
+  // Add authentication field (user/admin/member) if endpoint requires auth
+  const hasAuthentication = authorization && operation.authorizationRole;
+  if (hasAuthentication) {
+    const authFieldName = operation.authorizationRole;
+    const authFieldType = authorization.payload.name;
+    functionParameterFields.push(`${authFieldName}: ${authFieldType};`);
+  }
+
+  // Add URL path parameters (e.g., /posts/:id → id parameter)
+  const pathParameters = operation.parameters;
+  pathParameters.forEach((pathParam) => {
+    const paramName = pathParam.name;
+    const paramType = pathParam.schema.type;
+    const paramFormat =
+      "format" in pathParam.schema
+        ? ` & tags.Format<'${pathParam.schema.format}'>`
+        : "";
+
+    const parameterField = `${paramName}: ${paramType}${paramFormat};`;
+    functionParameterFields.push(parameterField);
+  });
+
+  // Add request body if present (POST/PUT/PATCH operations)
+  const hasRequestBody = operation.requestBody?.typeName;
+  if (hasRequestBody) {
+    const bodyTypeName = operation.requestBody?.typeName;
+    functionParameterFields.push(`body: ${bodyTypeName};`);
+  }
+
+  // Format as TypeScript props interface or indicate no parameters needed
+  const hasParameters = functionParameterFields.length > 0;
+
+  if (!hasParameters) {
+    return `// No props parameter needed - function should have no parameters`;
+  }
+
+  const formattedFields = functionParameterFields
+    .map((field) => `  ${field}`)
+    .join("\n");
+
+  return StringUtil.trim`
+    props: {
+    ${formattedFields}
+    }`;
+}