@autobe/agent 0.21.0 → 0.22.1

package/src/orchestrate/realize/orchestrateRealizeScenario.ts

@@ -6,7 +6,7 @@ import {
 import { ILlmSchema } from "@samchon/openapi";
 
 import { AutoBeContext } from "../../context/AutoBeContext";
-import { IAutoBeRealizeScenarioApplication } from "./structures/IAutoBeRealizeScenarioApplication";
+import { IAutoBeRealizeScenarioResult } from "./structures/IAutoBeRealizeScenarioResult";
 
 /**
  * Generates a planning result that defines what kind of function should be
@@ -32,7 +32,7 @@ export const orchestrateRealizeScenario = <Model extends ILlmSchema.Model>(
   ctx: AutoBeContext<Model>,
   operation: AutoBeOpenApi.IOperation,
   authorization?: AutoBeRealizeAuthorization,
-): IAutoBeRealizeScenarioApplication.IProps => {
+): IAutoBeRealizeScenarioResult => {
   const testFiles: AutoBeTestFile[] =
     ctx
       .state()

package/src/orchestrate/realize/orchestrateRealizeWrite.ts

@@ -11,11 +11,10 @@ import { v7 } from "uuid";
 
 import { AutoBeContext } from "../../context/AutoBeContext";
 import { assertSchemaModel } from "../../context/assertSchemaModel";
-import { getTestScenarioArtifacts } from "../test/compile/getTestScenarioArtifacts";
-import { IAutoBeTestScenarioArtifacts } from "../test/structures/IAutoBeTestScenarioArtifacts";
 import { transformRealizeWriteHistories } from "./histories/transformRealizeWriteHistories";
-import { IAutoBeRealizeScenarioApplication } from "./structures/IAutoBeRealizeScenarioApplication";
+import { IAutoBeRealizeScenarioResult } from "./structures/IAutoBeRealizeScenarioResult";
 import { IAutoBeRealizeWriteApplication } from "./structures/IAutoBeRealizeWriteApplication";
+import { getRealizeWriteDto } from "./utils/getRealizeWriteDto";
 import { replaceImportStatements } from "./utils/replaceImportStatements";
 
 export async function orchestrateRealizeWrite<Model extends ILlmSchema.Model>(
@@ -23,27 +22,24 @@ export async function orchestrateRealizeWrite<Model extends ILlmSchema.Model>(
   props: {
     totalAuthorizations: AutoBeRealizeAuthorization[];
     authorization: AutoBeRealizeAuthorization | null;
-    scenario: IAutoBeRealizeScenarioApplication.IProps;
+    scenario: IAutoBeRealizeScenarioResult;
     progress: AutoBeProgressEventBase;
     promptCacheKey: string;
   },
 ): Promise<AutoBeRealizeWriteEvent> {
-  const artifacts: IAutoBeTestScenarioArtifacts =
-    await getTestScenarioArtifacts(ctx, {
-      endpoint: props.scenario.operation,
-      dependencies: [],
-    });
   const pointer: IPointer<IAutoBeRealizeWriteApplication.IProps | null> = {
     value: null,
   };
+
+  const dto = await getRealizeWriteDto(ctx, props.scenario.operation);
   const { tokenUsage } = await ctx.conversate({
     source: "realizeWrite",
     histories: transformRealizeWriteHistories({
       state: ctx.state(),
       scenario: props.scenario,
-      artifacts,
       authorization: props.authorization,
       totalAuthorizations: props.totalAuthorizations,
+      dto,
     }),
     controller: createController({
       model: ctx.model,
@@ -73,11 +69,11 @@ export async function orchestrateRealizeWrite<Model extends ILlmSchema.Model>(
   });
   if (pointer.value === null) throw new Error("Failed to write code.");
 
-  pointer.value.implementationCode = await replaceImportStatements(ctx)(
-    artifacts,
-    pointer.value.implementationCode,
-    props.authorization?.payload.name,
-  );
+  pointer.value.implementationCode = await replaceImportStatements(ctx, {
+    operation: props.scenario.operation,
+    code: pointer.value.implementationCode,
+    decoratorType: props.authorization?.payload.name,
+  });
 
   const event: AutoBeRealizeWriteEvent = {
     type: "realizeWrite",

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

@@ -1,6 +1,23 @@
 import { CamelPattern, PascalPattern } from "@autobe/interface";
 
 export interface IAutoBeRealizeAuthorizationApplication {
+  /**
+   * Generates authentication provider, decorator, and payload type for role-based authorization.
+   *
+   * This method creates a complete authentication infrastructure for a specific
+   * role in the NestJS application. It generates three interconnected components
+   * that work together to provide JWT-based authentication and authorization.
+   *
+   * The generated components include:
+   * - **Provider Function**: Handles JWT verification and user validation from database
+   * - **Decorator**: NestJS parameter decorator for injecting authenticated user data
+   * - **Payload Type**: TypeScript interface defining the authenticated user structure
+   *
+   * All components follow strict naming conventions and integrate with the existing
+   * authentication architecture using the shared jwtAuthorize function.
+   *
+   * @param next Properties containing provider, decorator, and payload type configurations
+   */
   createDecorator: (
     next: IAutoBeRealizeAuthorizationApplication.IProps,
   ) => void;

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;
+}