@autobe/agent 0.17.1 → 0.18.0

package/src/orchestrate/realize/orchestrateRealizeWrite.ts

@@ -0,0 +1,120 @@
+import {
+  AutoBeRealizeAuthorization,
+  AutoBeRealizeWriteEvent,
+} from "@autobe/interface";
+import { ILlmApplication, ILlmController, ILlmSchema } from "@samchon/openapi";
+import { IPointer } from "tstl";
+import typia from "typia";
+
+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 { IAutoBeRealizeWriteApplication } from "./structures/IAutoBeRealizeWriteApplication";
+import { replaceImportStatements } from "./utils/replaceImportStatements";
+
+export async function orchestrateRealizeWrite<Model extends ILlmSchema.Model>(
+  ctx: AutoBeContext<Model>,
+  authorization: AutoBeRealizeAuthorization | null,
+  scenario: IAutoBeRealizeScenarioApplication.IProps,
+  progress: IProgress,
+): Promise<AutoBeRealizeWriteEvent> {
+  const artifacts: IAutoBeTestScenarioArtifacts =
+    await getTestScenarioArtifacts(ctx, {
+      endpoint: scenario.operation,
+      dependencies: [],
+    });
+  const pointer: IPointer<IAutoBeRealizeWriteApplication.IProps | null> = {
+    value: null,
+  };
+  const { tokenUsage } = await ctx.conversate({
+    source: "realizeWrite",
+    histories: transformRealizeWriteHistories({
+      state: ctx.state(),
+      scenario,
+      artifacts,
+      authorization,
+    }),
+    controller: createController({
+      model: ctx.model,
+      build: (next) => {
+        pointer.value = next;
+      },
+    }),
+    enforceFunctionCall: true,
+    message: [
+      `Write complete, production-ready TypeScript code that strictly follows these rules:`,
+      "",
+      `1. Do **not** use the native \`Date\` type anywhere.`,
+      `2. All date or datetime values must be written as \`string & tags.Format<'date-time'>\`.`,
+      `3. UUIDs must be generated using \`v4()\` and typed as \`string & tags.Format<'uuid'>\`.`,
+      `4. Do not use \`as\` for type assertions — resolve types properly.`,
+      `5. All functions must be fully typed with clear parameter and return types.`,
+      `6. Do not skip validations or default values where necessary.`,
+      `7. Follow functional, immutable, and consistent code structure.`,
+      "",
+      `Use \`@nestia/e2e\` test structure if relevant.`,
+    ].join("\n"),
+  });
+  if (pointer.value === null) throw new Error("Failed to write code.");
+
+  pointer.value.implementationCode = await replaceImportStatements(ctx)(
+    artifacts,
+    pointer.value.implementationCode,
+    authorization?.payload.name,
+  );
+
+  const event: AutoBeRealizeWriteEvent = {
+    type: "realizeWrite",
+    location: scenario.location,
+    content: pointer.value.implementationCode,
+    tokenUsage,
+    completed: ++progress.completed,
+    total: progress.total,
+    step: ctx.state().analyze?.step ?? 0,
+    created_at: new Date().toISOString(),
+  };
+  ctx.dispatch(event);
+  return event;
+}
+
+function createController<Model extends ILlmSchema.Model>(props: {
+  model: Model;
+  build: (next: IAutoBeRealizeWriteApplication.IProps) => void;
+}): ILlmController<Model> {
+  assertSchemaModel(props.model);
+
+  const application: ILlmApplication<Model> = collection[
+    props.model
+  ] satisfies ILlmApplication<any> as unknown as ILlmApplication<Model>;
+
+  return {
+    protocol: "class",
+    name: "Write code",
+    application,
+    execute: {
+      coding: (next) => {
+        props.build(next);
+      },
+    } satisfies IAutoBeRealizeWriteApplication,
+  };
+}
+
+const claude = typia.llm.application<
+  IAutoBeRealizeWriteApplication,
+  "claude"
+>();
+const collection = {
+  chatgpt: typia.llm.application<IAutoBeRealizeWriteApplication, "chatgpt">(),
+  claude,
+  llama: claude,
+  deepseek: claude,
+  "3.1": claude,
+};
+
+export interface IProgress {
+  total: number;
+  completed: number;
+}

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

@@ -1,3 +1,5 @@
+import { CamelPattern, PascalPattern } from "@autobe/interface";
+
 export interface IAutoBeRealizeAuthorizationApplication {
   createDecorator: (
     next: IAutoBeRealizeAuthorizationApplication.IProps,
@@ -38,8 +40,10 @@ export namespace IAutoBeRealizeAuthorizationApplication {
      * format (e.g., adminAuthorize, userAuthorize). This function will be
      * called by the decorator to verify JWT tokens and return authenticated
      * user information for the specified role.
+     *
+     * MUST use camelCase naming convention.
      */
-    name: string;
+    name: string & CamelPattern;
 
     /**
      * Complete TypeScript code for the authentication Provider function. Must
@@ -59,8 +63,10 @@ export namespace IAutoBeRealizeAuthorizationApplication {
      * decorator in Controller methods to automatically authenticate and
      * authorize users for the specific role, injecting the authenticated user
      * payload as a method parameter.
+     *
+     * MUST use PascalCase naming convention.
      */
-    name: string;
+    name: string & PascalPattern;
 
     /**
      * Complete TypeScript code for the authentication Decorator implementation.
@@ -79,8 +85,10 @@ export namespace IAutoBeRealizeAuthorizationApplication {
      * (e.g., AdminPayload, UserPayload). This type defines the structure of the
      * authenticated user data that will be injected into Controller methods
      * when using the decorator.
+     *
+     * MUST use PascalCase naming convention.
      */
-    name: string;
+    name: string & PascalPattern;
 
     /**
      * Complete TypeScript code for the Payload type interface in {Role}Payload

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

@@ -0,0 +1,81 @@
+import { IAutoBeRealizeWriteApplication } from "./IAutoBeRealizeWriteApplication";
+
+export interface IAutoBeRealizeCorrectApplication {
+  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;
+  }
+}

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

@@ -0,0 +1,43 @@
+import { AutoBeOpenApi, AutoBeRealizeAuthorization } from "@autobe/interface";
+
+export namespace IAutoBeRealizeScenarioApplication {
+  export interface IProps {
+    /** 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.
+     */
+    testScenarios: string[];
+
+    /**
+     * 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

@@ -0,0 +1,282 @@
+export interface IAutoBeRealizeWriteApplication {
+  coding: (next: IAutoBeRealizeWriteApplication.IProps) => void;
+}
+
+export namespace IAutoBeRealizeWriteApplication {
+  export interface IProps {
+    /**
+     * Step 1.
+     *
+     * 🧠 Provider Function Implementation Plan
+     *
+     * This field outlines the strategic plan for implementing the provider
+     * function according to the Realize Coder Agent specification. Before
+     * writing the actual code, think through the logic and structure.
+     *
+     * The plan MUST follow MANDATORY SCHEMA-FIRST APPROACH:
+     *
+     * 📋 STEP 1 - PRISMA SCHEMA VERIFICATION (MOST CRITICAL):
+     *
+     * - 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 (e.g., "Note: deleted_at field
+     *   DOES NOT EXIST")
+     * - Common assumption errors to avoid: `deleted_at`, `created_by`,
+     *   `updated_by`, `is_deleted`, `is_active`
+     *
+     * 📋 STEP 2 - FIELD INVENTORY:
+     *
+     * - List ONLY fields confirmed to exist in schema
+     * - Example: "Verified fields in user model: id (String), email (String),
+     *   created_at (DateTime), updated_at (DateTime)"
+     * - Example: "Fields that DO NOT exist: deleted_at, is_active, created_by"
+     *
+     * 📋 STEP 3 - FIELD ACCESS STRATEGY:
+     *
+     * - Plan which verified fields will be used in select, update, create
+     *   operations
+     * - For complex operations with type errors, plan to use separate queries
+     *   instead of nested operations
+     *
+     * 📋 STEP 4 - TYPE COMPATIBILITY:
+     *
+     * - Plan DateTime to ISO string conversions using toISOStringSafe()
+     * - Plan handling of nullable vs required fields
+     *
+     * 📋 STEP 5 - IMPLEMENTATION APPROACH:
+     *
+     * - 🧩 Required business entities (e.g., users, posts, logs) and their
+     *   relationships
+     * - 🛠 Operations needed to fulfill the business scenario (e.g., fetch,
+     *   create, update) using ONLY verified fields
+     * - 🔄 Data dependencies between steps (e.g., use userId to fetch related
+     *   data)
+     * - ✅ Validation points (based on business rules, not field presence)
+     * - 🚧 Error and edge cases that must be handled explicitly (e.g., missing
+     *   records)
+     * - 🏗 Structure: always a single `async function`, using only `parameters`
+     *   and `body`
+     *
+     * ⚠️ Important Constraints:
+     *
+     * - Do NOT perform input validation — assume `parameters` and `body` are
+     *   already valid
+     * - Use `typia.random<T>()` with an explanatory comment if logic can't be
+     *   implemented
+     * - Never use `any` or make assumptions without sufficient context
+     * - Use only allowed imports — DTOs and Prisma types
+     * - Use `MyGlobal.prisma` for DB access and respect Prisma typing rules
+     *
+     * ⚠️ TypeScript-specific considerations:
+     *
+     * - Do **not** use native `Date` objects directly; always convert all dates
+     *   using `toISOStringSafe()` and brand as `string &
+     *   tags.Format<'date-time'>`. This rule applies throughout all phases.
+     * - Prefer `satisfies` for DTO conformance instead of unsafe `as` casts
+     * - Avoid weak typing such as `any`, `as any`, or `satisfies any`
+     * - Use branded types (e.g., `tags.Format<'uuid'>`) and literal unions where
+     *   applicable
+     *
+     * ✅ Example Structure:
+     *
+     * ```ts
+     * export async function doSomething(
+     *   user: { id: string & tags.Format<"uuid">; type: string },
+     *   parameters: IParams,
+     *   body: IBody
+     * ): Promise<IReturn> {
+     *   const { id } = parameters;
+     *   const { name } = body;
+     *   const user = await MyGlobal.prisma.users.findFirst({ where: { id } });
+     *   if (!user) throw new Error("User not found");
+     *   ...
+     *   return result;
+     * }
+     * ```
+     *
+     * 🔍 Feasibility Analysis Requirement:
+     *
+     * - Before generating any code, the agent **must analyze** whether the
+     *   requested implementation is **feasible based on the given Prisma schema
+     *   and DTO types**.
+     * - If required fields or relationships are **missing or incompatible**, the
+     *   plan should explicitly state that the implementation is **not
+     *   possible** with the current schema/DTO, and no code should be generated
+     *   in later stages.
+     * - In such cases, only a detailed **comment in the `implementationCode`**
+     *   should be returned explaining why the logic cannot be implemented.
+     *
+     * 🔥 Error Handling Plan:
+     *
+     * If an error is expected or encountered during implementation:
+     *
+     * - Clearly document the error message(s) and TypeScript error codes.
+     * - Analyze the root cause (e.g., type mismatch, missing field, nullability
+     *   issue).
+     * - Define concrete steps to resolve the issue, such as:
+     *
+     *   - Adjusting type declarations or using Prisma-generated input types.
+     *   - Using `?? undefined` to normalize nullable fields.
+     *   - Applying correct relation handling (e.g., `connect` instead of direct
+     *       foreign key assignment).
+     *   - Ensuring all date fields use `.toISOString()` and proper branding.
+     * - Include fallback or workaround plans if a direct fix is complex.
+     * - If no error is present, simply omit this section.
+     *
+     * This plan ensures the function will:
+     *
+     * - Respect the global architecture and coding conventions
+     * - Be safe, predictable, and aligned with upstream logic
+     */
+    plan: string;
+
+    /**
+     * Step 2.
+     *
+     * The Prisma schema string that will be used to validate the implementation
+     * logic in this file.
+     *
+     * You must **explicitly specify only the relevant models and fields** from
+     * your full schema that are used in this implementation. This ensures that
+     * your logic is aligned with the expected database structure without
+     * accidentally introducing unrelated fields or models.
+     *
+     * ⚠️ Important: The value of this field must be a valid Prisma schema
+     * string containing only the models used in this code — not the entire
+     * schema.
+     *
+     * This acts as a safeguard against:
+     *
+     * - Forgetting required fields used in this implementation
+     * - Including fields or models that are not actually used
+     */
+    prisma_schemas: string;
+
+    /**
+     * Step 3.
+     *
+     * Draft WITHOUT using native Date type.
+     *
+     * This is the initial drafting phase where you outline the basic skeleton
+     * of the function. CRITICAL: This draft must NEVER use the native Date
+     * type.
+     *
+     * - The function signature must correctly include `user`, `parameters`, and
+     *   `body` arguments.
+     * - Design the main flow of business logic, such as DB fetches and early
+     *   returns based on conditions.
+     * - Mark any incomplete or missing parts clearly with placeholders (e.g.,
+     *   comments or temporary values).
+     *
+     * ⚠️ Import rules:
+     *
+     * - Do NOT add any new import statements manually.
+     * - All necessary imports are provided globally or by the system
+     *   automatically.
+     * - Writing import statements directly is prohibited and may cause compile
+     *   errors. If import errors occur, check your environment configuration.
+     *
+     * ✅ Requirements:
+     *
+     * - Avoid using the `any` type at all costs to ensure type safety.
+     * - NEVER declare variables with `: Date` type
+     * - ALWAYS use `string & tags.Format<'date-time'>` for date values
+     * - Use `toISOStringSafe(new Date())` for current timestamps
+     * - Maintain a single-function structure; avoid using classes.
+     */
+    draft_without_date_type: string;
+
+    /**
+     * Step 4.
+     *
+     * A refined version of the draft with improved completeness.
+     *
+     * - Replace placeholder logic with real DTO-conformant operations.
+     * - Add error handling (`throw new Error(...)`) where necessary.
+     * - Begin resolving structural or type mismatches.
+     *
+     * ✅ Requirements:
+     *
+     * - Use `satisfies` to ensure DTO conformity.
+     * - 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.
+     */
+    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.
+     *
+     * The complete and fully correct TypeScript function implementation.
+     *
+     * - Passes strict type checking without errors.
+     * - Uses only safe branding or literal type assertions.
+     * - Converts all date values properly using `toISOStringSafe()`.
+     * - Follows DTO structures using `satisfies`.
+     * - Avoids any weak typing such as `any`, `as any`, or `satisfies any`.
+     * - Uses only allowed imports (e.g., from `../api/structures` and
+     *   `MyGlobal.prisma`).
+     * - NEVER creates intermediate variables for Prisma operations.
+     *
+     * ⚠️ Fallback Behavior:
+     *
+     * - If the `plan` phase explicitly determines that the requested logic is
+     *   **not feasible** due to mismatches or limitations in the provided
+     *   Prisma schema and DTO types:
+     *
+     *   - The implementation must still return a syntactically valid function.
+     *   - In such cases, return mock data using `typia.random<T>()` wrapped in the
+     *       correct structure, along with a comment explaining the limitation.
+     *
+     *   Example fallback:
+     *
+     * ```ts
+     *   // ⚠️ Cannot implement logic due to missing relation between A and B
+     *   export async function someFunction(...) {
+     *     return typia.random<IReturn>(); // mocked output
+     *   }
+     * ```
+     *
+     * ⚠️ Prohibited Practices:
+     *
+     * - Do NOT add or modify import statements manually. Imports are handled
+     *   automatically by the system.
+     * - Do NOT use `any`, `as any`, or `satisfies any` to bypass type checking.
+     * - Do NOT assign native `Date` objects directly; always convert them using
+     *   `toISOStringSafe()`.
+     * - Do NOT use unsafe type assertions except for safe branding or literal
+     *   narrowing.
+     * - Do NOT write code outside the single async function structure (e.g., no
+     *   classes or multiple functions).
+     * - Do NOT perform any input validation — assume all inputs are already
+     *   validated.
+     * - Do NOT use dynamic import expressions (`import()`); all imports must be
+     *   static.
+     * - Do NOT use Prisma-generated input types; always use types from
+     *   `../api/structures`.
+     * - Do NOT use `Object.prototype.hasOwnProperty.call()` for field checks.
+     * - Do NOT escape newlines or quotes in the implementation string (e.g., no
+     *   `\\n` or `\"`); use a properly formatted template literal with actual
+     *   line breaks instead.
+     */
+    implementationCode: string;
+  }
+}

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

@@ -59,7 +59,7 @@ export function replaceImportStatements<Model extends ILlmSchema.Model>(
       /import\s*(?:type\s*)?{\s*[^}]+\s*}\s*from\s*["']@ORGANIZATION\/PROJECT-api\/lib\/structures\/[^"']+["']\s*;?\s*/gm,
       "",
     );
-    
+
     // Remove specific type imports that match our typeReferences
     for (const ref of typeReferences) {
       // Remove any import of this specific type from any path
@@ -119,6 +119,8 @@ export function replaceImportStatements<Model extends ILlmSchema.Model>(
     // Apply final beautification
     code = await compiler.typescript.beautify(code);
 
+    code = code.replaceAll("typia.tags.assert", "typia.assert");
+
     return code;
   };
 }

package/src/orchestrate/test/experimental/orchestrateTestCorrect.ast

@@ -89,7 +89,7 @@ async function correct<Model extends ILlmSchema.Model>(
     },
     histories: transformTestCorrectHistories(written, event.result),
     controllers: [
-      createApplication({
+      createController({
         model: ctx.model,
         build: (next) => {
           pointer.value = next;
@@ -153,7 +153,7 @@ function getUnionTypeName(unit: IJsonSchemaUnit): string {
     .join(" | ");
 }
 
-function createApplication<Model extends ILlmSchema.Model>(props: {
+function createController<Model extends ILlmSchema.Model>(props: {
   model: Model;
   build: (next: ICorrectTestFunctionProps) => void;
 }): IAgenticaController.IClass<Model> {
@@ -161,7 +161,7 @@ function createApplication<Model extends ILlmSchema.Model>(props: {
 
   const application: ILlmApplication<Model> = collection[
     props.model
-  ] as unknown as ILlmApplication<Model>;
+  ] satisfies ILlmApplication<any> as unknown as ILlmApplication<Model>;
   return {
     protocol: "class",
     name: "Modify Test Code",
@@ -176,16 +176,12 @@ function createApplication<Model extends ILlmSchema.Model>(props: {
 
 const claude = typia.llm.application<
   IApplication,
-  "claude",
-  {
-    reference: true;
-  }
+  "claude"
 >();
 const collection = {
   chatgpt: typia.llm.application<
     IApplication,
-    "chatgpt",
-    { reference: true }
+    "chatgpt"
   >(),
   claude,
   llama: claude,