@autobe/agent 0.18.0 → 0.20.0

package/src/orchestrate/interface/orchestrateInterfaceSchemasReview.ts

@@ -2,14 +2,19 @@ import { IAgenticaController } from "@agentica/core";
 import {
   AutoBeInterfaceSchemasReviewEvent,
   AutoBeOpenApi,
+  AutoBeProgressEventBase,
 } from "@autobe/interface";
 import { ILlmApplication, ILlmSchema, IValidation } from "@samchon/openapi";
+import { OpenApiV3_1Emender } from "@samchon/openapi/lib/converters/OpenApiV3_1Emender";
 import { IPointer } from "tstl";
 import typia from "typia";
+import { v7 } from "uuid";
 
 import { AutoBeContext } from "../../context/AutoBeContext";
+import { assertSchemaModel } from "../../context/assertSchemaModel";
 import { transformInterfaceSchemasReviewHistories } from "./histories/transformInterfaceSchemasReviewHistories";
 import { IAutoBeInterfaceSchemasReviewApplication } from "./structures/IAutobeInterfaceSchemasReviewApplication";
+import { validateAuthorizationSchema } from "./utils/validateAuthorizationSchema";
 
 export async function orchestrateInterfaceSchemasReview<
   Model extends ILlmSchema.Model,
@@ -20,54 +25,73 @@ export async function orchestrateInterfaceSchemasReview<
     string,
     AutoBeOpenApi.IJsonSchemaDescriptive<AutoBeOpenApi.IJsonSchema>
   >,
-  progress: { total: number; completed: number },
+  progress: AutoBeProgressEventBase,
 ): Promise<Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>> {
-  const pointer: IPointer<IAutoBeInterfaceSchemasReviewApplication.IProps | null> =
-    {
-      value: null,
-    };
-
-  const { tokenUsage } = await ctx.conversate({
-    source: "interfaceSchemasReview",
-    controller: createController({
-      model: ctx.model,
-      pointer,
-      schemas,
-    }),
-    histories: transformInterfaceSchemasReviewHistories(
-      ctx.state(),
-      operations,
-      schemas,
-    ),
-    enforceFunctionCall: true,
-    message: "Review type schemas.",
-  });
-  if (pointer.value === null)
-    throw new Error("Failed to extract review information.");
+  try {
+    const pointer: IPointer<IAutoBeInterfaceSchemasReviewApplication.IProps | null> =
+      {
+        value: null,
+      };
+    const { tokenUsage } = await ctx.conversate({
+      source: "interfaceSchemasReview",
+      controller: createController({
+        model: ctx.model,
+        pointer,
+        operations,
+        schemas,
+      }),
+      histories: transformInterfaceSchemasReviewHistories(
+        ctx.state(),
+        operations,
+        schemas,
+      ),
+      enforceFunctionCall: true,
+      message: "Review type schemas.",
+    });
+    if (pointer.value === null) {
+      console.error("Failed to extract review information.");
+      ++progress.completed;
+      return {};
+    }
 
-  ctx.dispatch({
-    type: "interfaceSchemasReview",
-    schemas: schemas,
-    review: pointer.value.review,
-    plan: pointer.value.plan,
-    content: pointer.value.content,
-    tokenUsage,
-    step: ctx.state().analyze?.step ?? 0,
-    total: progress.total,
-    completed: ++progress.completed,
-    created_at: new Date().toISOString(),
-  } satisfies AutoBeInterfaceSchemasReviewEvent);
-  return pointer.value.content;
+    const content: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> =
+      (
+        OpenApiV3_1Emender.convertComponents({
+          schemas: pointer.value.content,
+        }) as AutoBeOpenApi.IComponents
+      ).schemas ?? {};
+    ctx.dispatch({
+      type: "interfaceSchemasReview",
+      id: v7(),
+      schemas: schemas,
+      review: pointer.value.review,
+      plan: pointer.value.plan,
+      content,
+      tokenUsage,
+      step: ctx.state().analyze?.step ?? 0,
+      total: progress.total,
+      completed: ++progress.completed,
+      created_at: new Date().toISOString(),
+    } satisfies AutoBeInterfaceSchemasReviewEvent);
+    return content;
+  } catch (error) {
+    console.error("Error occurred during interface schemas review:", error);
+    ++progress.completed;
+    return {};
+  }
 }
 
 function createController<Model extends ILlmSchema.Model>(props: {
   model: Model;
   pointer: IPointer<IAutoBeInterfaceSchemasReviewApplication.IProps | null>;
+  operations: AutoBeOpenApi.IOperation[];
   schemas: Record<
     string,
     AutoBeOpenApi.IJsonSchemaDescriptive<AutoBeOpenApi.IJsonSchema>
   >;
 }): IAgenticaController.IClass<Model> {
+  assertSchemaModel(props.model);
+
   const validate = (
     next: unknown,
   ): IValidation<IAutoBeInterfaceSchemasReviewApplication.IProps> => {
@@ -76,27 +100,94 @@ function createController<Model extends ILlmSchema.Model>(props: {
     if (result.success === false) return result;
 
     const errors: IValidation.IError[] = [];
-    if (Object.keys(result.data.content).length === 0) {
-      console.log();
-      console.log();
-      console.log();
-      console.log(
-        JSON.stringify({ schemas: props.schemas, ...result.data }, null, 2),
-      );
-      errors.push({
-        path: `$input.content`,
-        expected: `Content must not be empty. If it's at a level that can't be fixed, please create a schema instead to meet the requirements.`,
-        value: result.data.content,
-      });
-    }
+    validateAuthorizationSchema({
+      errors,
+      schemas: result.data.content,
+      path: "$input.content",
+    });
+
+    Object.entries(result.data.content).forEach(
+      ([tagName, jsonDescriptive]) => {
+        const index: AutoBeOpenApi.IOperation | undefined =
+          props.operations.find(
+            (op) =>
+              op.responseBody?.typeName === tagName &&
+              op.method === "patch" &&
+              op.name === "index",
+          );
+
+        // The index API should return the `IPage<T>` type.
+        if (index) {
+          // First check if the schema has the correct object structure
+          if (
+            !("type" in jsonDescriptive) ||
+            jsonDescriptive.type !== "object"
+          ) {
+            errors.push({
+              path: `$input.content.${tagName}`,
+              expected: `{ type: "object", properties: { ... } }`,
+              value: jsonDescriptive,
+              description: `IPage schema must have type: "object". Found: ${JSON.stringify(jsonDescriptive)}`,
+            });
+          } else if (!("properties" in jsonDescriptive)) {
+            errors.push({
+              path: `$input.content.${tagName}`,
+              expected: `Schema with "properties" field`,
+              value: jsonDescriptive,
+              description: `IPage schema must have a "properties" field containing "pagination" and "data" properties.`,
+            });
+          } else if (
+            typia.is<AutoBeOpenApi.IJsonSchema.IObject>(jsonDescriptive)
+          ) {
+            jsonDescriptive.properties ??= {};
+
+            // Check pagination property
+            const pagination = jsonDescriptive.properties["pagination"];
+            if (!pagination || !("$ref" in pagination)) {
+              errors.push({
+                path: `$input.content.${tagName}.properties.pagination`,
+                expected: `{ $ref: "#/components/schemas/IPage.IPagination" }`,
+                value: pagination,
+                description: `IPage must have a "pagination" property with $ref to IPage.IPagination.`,
+              });
+            }
 
-    if (errors.length > 0) {
+            // Check data property
+            const data = jsonDescriptive.properties["data"];
+            if (!typia.is<AutoBeOpenApi.IJsonSchema.IArray>(data)) {
+              errors.push({
+                path: `$input.content.${tagName}.properties.data`,
+                expected: `AutoBeOpenApi.IJsonSchema.IArray`,
+                value: data,
+                description: `The 'data' property must be an array for the index operation.`,
+              });
+            } else {
+              // Check if array items have proper type reference (not 'any')
+              const arraySchema: AutoBeOpenApi.IJsonSchema.IArray = data;
+              if (
+                !arraySchema.items ||
+                !("$ref" in arraySchema.items) ||
+                arraySchema.items.$ref === "#/components/schemas/any"
+              ) {
+                errors.push({
+                  path: `$input.content.${tagName}.properties.data.items`,
+                  expected: `Reference to a specific type (e.g., $ref to ISummary type)`,
+                  value: arraySchema.items,
+                  description: `The 'data' array must have a specific item type, not 'any[]'. Use a proper type reference like '{Entity}.ISummary' for paginated results.`,
+                });
+              }
+            }
+          }
+        }
+      },
+    );
+
+    if (errors.length !== 0)
       return {
         success: false,
         errors,
-        data: result.data,
+        data: next,
       };
-    }
 
     return result;
   };
@@ -106,7 +197,6 @@ function createController<Model extends ILlmSchema.Model>(props: {
   ](
     validate,
   ) satisfies ILlmApplication<any> as unknown as ILlmApplication<Model>;
-
   return {
     protocol: "class",
     name: "Reviewer",
@@ -118,12 +208,6 @@ function createController<Model extends ILlmSchema.Model>(props: {
     } satisfies IAutoBeInterfaceSchemasReviewApplication,
   };
 }
-const claude = (validate: Validator) =>
-  typia.llm.application<IAutoBeInterfaceSchemasReviewApplication, "claude">({
-    validate: {
-      review: validate,
-    },
-  });
 
 const collection = {
   chatgpt: (validate: Validator) =>
@@ -132,10 +216,12 @@ const collection = {
         review: validate,
       },
     }),
-  claude,
-  llama: claude,
-  deepseek: claude,
-  "3.1": claude,
+  claude: (validate: Validator) =>
+    typia.llm.application<IAutoBeInterfaceSchemasReviewApplication, "claude">({
+      validate: {
+        review: validate,
+      },
+    }),
 };
 
 type Validator = (

package/src/orchestrate/interface/structures/IAutoBeInterfaceComplementApplication.ts

@@ -20,6 +20,45 @@ export interface IAutoBeInterfaceComplementApplication {
 }
 export namespace IAutoBeInterfaceComplementApplication {
   export interface IProps {
+    /**
+     * TypeScript draft code for complement schema definitions.
+     *
+     * This property contains TypeScript interface definitions for missing schema
+     * types that were referenced but not defined in the initial schema generation.
+     * Similar to the main schema draft, this serves as a preliminary TypeScript
+     * representation before converting to JSON Schema format.
+     *
+     * The draft helps ensure that complementary schemas maintain consistency with
+     * the existing type system and follow the same conventions as the primary schemas.
+     * 
+     * This draft typically includes:
+     * - Missing entity interfaces referenced via $ref
+     * - Nested object types used within other schemas
+     * - Shared utility types or enumerations
+     * - Any transitively referenced types
+     *
+     * The final schemas in the `schemas` property should be validated against and
+     * derived from this TypeScript draft to ensure type safety and consistency
+     * across the entire API specification.
+     *
+     * Example complement draft:
+     * ```typescript
+     * interface IUserProfile {
+     *   id: string;
+     *   userId: string;
+     *   displayName: string;
+     *   avatarUrl?: string;
+     * }
+     * 
+     * interface IAddress {
+     *   street: string;
+     *   city: string;
+     *   postalCode: string;
+     * }
+     * ```
+     */
+    draft: string;
+
     /**
      * A collection of missing schema definitions that need to be added to the
      * OpenAPI document's `components.schemas` section.

package/src/orchestrate/interface/structures/IAutoBeInterfaceGroupApplication.ts

@@ -5,10 +5,10 @@ export interface IAutoBeInterfaceGroupApplication {
    * Generate logical groups for organizing API endpoint creation based on
    * Prisma schema structure.
    *
-   * Groups MUST be derived from Prisma schema organization (namespaces, file
-   * structure, table prefixes) rather than arbitrary business domains. Only
-   * create new groups when existing schema structure cannot adequately cover
-   * all requirements.
+   * DO: Derive groups from Prisma schema organization (namespaces, file
+   * structure, table prefixes) rather than arbitrary business domains.
+   * DO: Create new groups only when existing schema structure cannot adequately
+   * cover all requirements.
    *
    * @param props Properties containing the groups to be created for API
    *   organization
@@ -21,8 +21,8 @@ export namespace IAutoBeInterfaceGroupApplication {
     /**
      * Array of API endpoint groups for organizing development.
      *
-     * Groups MUST be organized around existing Prisma schema structure and
-     * provide complete coverage of all entities and requirements without
+     * DO: Organize groups around existing Prisma schema structure.
+     * DO: Provide complete coverage of all entities and requirements without
      * overlap.
      */
     groups: IGroup[] & tags.MinItems<1>;
@@ -34,10 +34,11 @@ export namespace IAutoBeInterfaceGroupApplication {
    *
    * **SCHEMA-BASED GROUP REQUIREMENTS:**
    *
-   * Groups MUST be derived from the Prisma schema structure rather than
-   * arbitrary business domain names. This ensures consistency with the
-   * underlying data model and prevents misalignment between API organization
-   * and database structure.
+   * DO: Derive groups from the Prisma schema structure rather than arbitrary
+   * business domain names.
+   * 
+   * This ensures consistency with the underlying data model and prevents
+   * misalignment between API organization and database structure.
    *
    * **Primary Group Sources (in order of priority):**
    *
@@ -51,12 +52,11 @@ export namespace IAutoBeInterfaceGroupApplication {
    *
    * **Group Creation Guidelines:**
    *
-   * - Each group must cover specific Prisma schema entities without overlap
+   * - Each group covers specific Prisma schema entities without overlap
    * - Size groups appropriately for manageable endpoint generation cycles
    * - Maintain clear boundaries based on schema organization
    * - Ensure complete coverage of all database entities and requirements
-   * - Related database tables within the same schema area should be grouped
-   *   together
+   * - Related database tables within the same schema area are grouped together
    *
    * **When to Create Schema-Independent Groups:**
    *
@@ -71,14 +71,14 @@ export namespace IAutoBeInterfaceGroupApplication {
    * **Naming Standards:**
    *
    * - Use PascalCase format (e.g., "Shopping", "BBS", "UserManagement")
-   * - Names MUST directly reflect Prisma schema structure
+   * - Names directly reflect Prisma schema structure
    * - Keep names concise and schema-derived
    * - Avoid arbitrary business domain names
    * - Maintain consistency with schema organization
    *
    * **Quality Requirements:**
    *
-   * - Groups collectively must cover ALL entities and requirements
+   * - Groups collectively cover ALL entities and requirements
    * - Each database entity belongs to exactly one group
    * - Clear mapping to specific Prisma schema elements
    * - Balance group sizes within schema constraints
@@ -88,7 +88,7 @@ export namespace IAutoBeInterfaceGroupApplication {
     /**
      * Unique identifier name derived from Prisma schema structure.
      *
-     * Must correspond to schema namespaces, file names, table prefixes, or
+     * DO: Correspond to schema namespaces, file names, table prefixes, or
      * organizational annotations rather than arbitrary business domain names.
      */
     name: string & tags.MinLength<1>;

package/src/orchestrate/interface/structures/IAutoBeInterfaceOperationApplication.ts

@@ -23,7 +23,7 @@ export namespace IAutoBeInterfaceOperationApplication {
     /**
      * Array of API operations to generate.
      *
-     * Each operation in this array must include:
+     * Each operation in this array includes:
      *
      * - Specification: Detailed API specification with clear purpose and
      *   functionality
@@ -38,7 +38,7 @@ export namespace IAutoBeInterfaceOperationApplication {
      *   components.schemas
      * - ResponseBody: With typeName referencing appropriate response type
      *
-     * All operations must follow strict quality standards:
+     * All operations follow strict quality standards:
      *
      * 1. Detailed descriptions referencing Prisma schema comments
      * 2. Accurate parameter definitions matching path parameters
@@ -66,11 +66,10 @@ export namespace IAutoBeInterfaceOperationApplication {
    * reason and description fields, making it clear why the API was designed and
    * how it should be used.
    *
-   * All request bodies and responses for this operation must be object types
-   * and must reference named types defined in the components section. The
-   * content-type is always `application/json`. For file upload/download
-   * operations, use `string & tags.Format<"uri">` in the appropriate schema
-   * instead of binary data formats.
+   * DO: Use object types for all request bodies and responses. DO: Reference
+   * named types defined in the components section. DO: Use `application/json`
+   * as the content-type. DO: Use `string & tags.Format<"uri">` in the schema
+   * for file upload/download operations instead of binary data formats.
    *
    * In OpenAPI, this might represent:
    *
@@ -88,7 +87,49 @@ export namespace IAutoBeInterfaceOperationApplication {
    * ```
    */
   export interface IOperation
-    extends Omit<AutoBeOpenApi.IOperation, "authorizationRole"> {
+    extends Omit<
+      AutoBeOpenApi.IOperation,
+      "authorizationRole" | "authorizationType"
+    > {
+    /**
+     * Prisma schema models relevant to this operation.
+     *
+     * Contains the complete Prisma schema definitions for all entities involved
+     * in this operation, including their fields, relations, and database
+     * constraints. This enables comprehensive validation and schema-aware
+     * operation design.
+     *
+     * The schema information serves multiple critical purposes:
+     *
+     * - **Field Verification**: Ensures all referenced fields actually exist in
+     *   the database schema and have the correct types
+     * - **Relationship Validation**: Confirms that entity relationships are
+     *   properly defined and can support the operation's data access patterns
+     * - **Soft-Delete Detection**: For DELETE operations, identifies whether
+     *   entities have soft-delete fields (deleted_at, is_deleted, etc.) to
+     *   determine if the operation should perform logical deletion instead of
+     *   physical removal
+     * - **Constraint Awareness**: Understands unique constraints, required
+     *   fields, and default values to generate accurate request/response
+     *   schemas
+     *
+     * Example content might include:
+     *
+     * ```prisma
+     * model User {
+     *   id         String    @id @default(uuid())
+     *   email      String    @unique
+     *   name       String
+     *   deleted_at DateTime? // Indicates soft-delete capability
+     *   posts      Post[]
+     * }
+     * ```
+     *
+     * This schema context ensures operations are fully aligned with the actual
+     * database structure and business logic requirements.
+     */
+    prisma_schemas: string;
+
     /**
      * Authorization roles required to access this API operation.
      *
@@ -96,16 +137,47 @@ export namespace IAutoBeInterfaceOperationApplication {
      * endpoint. Multiple roles can be specified to allow different types of
      * users to access the same endpoint.
      *
+     * ## ⚠️ CRITICAL: Role Multiplication Effect
+     *
+     * **EACH ROLE IN THIS ARRAY GENERATES A SEPARATE ENDPOINT**
+     *
+     * - If you specify `["admin", "moderator", "member"]`, this creates 3
+     *   separate endpoints
+     * - Total generated endpoints = operations × average roles.length
+     * - Example: 100 operations with 3 roles each = 300 actual endpoints
+     *
+     * ## 🔴 AVOID OVER-GENERATION
+     *
+     * **DO NOT create role-specific endpoints when a public endpoint would
+     * suffice:**
+     *
+     * - ❌ BAD: Separate GET endpoints for admin, member, moderator to view the
+     *   same public data
+     * - ✅ GOOD: Single public endpoint `[]` with role-based filtering in business
+     *   logic
+     *
+     * **DO NOT enumerate all possible roles when the Prisma schema uses a
+     * single User table:**
+     *
+     * - If Prisma has a User table with role/permission fields, you likely only
+     *   need `["user"]`
+     * - Avoid listing `["admin", "seller", "buyer", "moderator", ...]`
+     *   unnecessarily
+     * - The actual role checking happens in business logic, not at the endpoint
+     *   level
+     *
      * ## Naming Convention
      *
-     * All role names MUST use camelCase.
+     * DO: Use camelCase for all role names.
      *
      * ## Important Guidelines
      *
      * - Set to empty array `[]` for public endpoints that require no
      *   authentication
      * - Set to array with role strings for role-restricted endpoints
-     * - The role names MUST match exactly with the user type/role defined in the
+     * - **MINIMIZE the number of roles per endpoint to prevent explosion**
+     * - Consider if the endpoint can be public with role-based filtering instead
+     * - The role names match exactly with the user type/role defined in the
      *   database
      * - This will be used by the Realize Agent to generate appropriate decorator
      *   and authorization logic in the provider functions
@@ -114,11 +186,26 @@ export namespace IAutoBeInterfaceOperationApplication {
      *
      * ## Examples
      *
-     * - `[]` - Public endpoint, no authentication required
-     * - `["user"]` - Any authenticated user can access
-     * - `["admin"]` - Only admin users can access
+     * - `[]` - Public endpoint, no authentication required (PREFERRED for read
+     *   operations)
+     * - `["user"]` - Any authenticated user can access (PREFERRED for
+     *   user-specific operations)
+     * - `["admin"]` - Only admin users can access (USE SPARINGLY)
      * - `["admin", "moderator"]` - Both admin and moderator users can access
-     * - `["seller"]` - Only seller users can access
+     *   (AVOID if possible)
+     * - `["seller"]` - Only seller users can access (ONLY if Seller is a separate
+     *   table)
+     *
+     * ## Best Practices
+     *
+     * 1. **Start with public `[]` for all read operations** unless sensitive data
+     *    is involved
+     * 2. **Use single role `["user"]` for authenticated operations** and handle
+     *    permissions in business logic
+     * 3. **Only use multiple roles when absolutely necessary** for different
+     *    business logic paths
+     * 4. **Remember: Fewer roles = Fewer endpoints = Better performance and
+     *    maintainability**
      *
      * Note: The actual authentication/authorization implementation will be
      * handled by decorators at the controller level, and the provider function

package/src/orchestrate/interface/structures/IAutoBeInterfaceOperationsReviewApplication.ts

@@ -97,6 +97,82 @@ export namespace IAutoBeInterfaceOperationsReviewApplication {
      * operations unchanged. These operations are validated and ready for schema
      * generation and subsequent implementation phases.
      */
-    content: AutoBeOpenApi.IOperation[];
+    content: IOperation[];
+  }
+
+  /**
+   * Operation of the Restful API.
+   *
+   * This interface defines a single API endpoint with its HTTP {@link method},
+   * {@link path}, {@link parameters path parameters},
+   * {@link requestBody request body}, and {@link responseBody} structure. It
+   * corresponds to an individual operation in the paths section of an OpenAPI
+   * document.
+   *
+   * Each operation requires a detailed explanation of its purpose through the
+   * reason and description fields, making it clear why the API was designed and
+   * how it should be used.
+   *
+   * All request bodies and responses for this operation must be object types
+   * and must reference named types defined in the components section. The
+   * content-type is always `application/json`. For file upload/download
+   * operations, use `string & tags.Format<"uri">` in the appropriate schema
+   * instead of binary data formats.
+   *
+   * In OpenAPI, this might represent:
+   *
+   * ```json
+   * {
+   *   "/shoppings/customers/orders": {
+   *     "post": {
+   *       "description": "Create a new order application from shopping cart...",
+   *       "parameters": [...],
+   *       "requestBody": {...},
+   *       "responses": {...}
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  export interface IOperation
+    extends Omit<AutoBeOpenApi.IOperation, "authorizationType"> {
+    /**
+     * Prisma schema models relevant to this operation.
+     *
+     * Contains the complete Prisma schema definitions for all entities involved
+     * in this operation, including their fields, relations, and database
+     * constraints. This enables comprehensive validation and schema-aware
+     * operation design.
+     *
+     * The schema information serves multiple critical purposes:
+     *
+     * - **Field Verification**: Ensures all referenced fields actually exist in
+     *   the database schema and have the correct types
+     * - **Relationship Validation**: Confirms that entity relationships are
+     *   properly defined and can support the operation's data access patterns
+     * - **Soft-Delete Detection**: For DELETE operations, identifies whether
+     *   entities have soft-delete fields (deleted_at, is_deleted, etc.) to
+     *   determine if the operation should perform logical deletion instead of
+     *   physical removal
+     * - **Constraint Awareness**: Understands unique constraints, required
+     *   fields, and default values to generate accurate request/response
+     *   schemas
+     *
+     * Example content might include:
+     *
+     * ```prisma
+     * model User {
+     *   id         String    @id @default(uuid())
+     *   email      String    @unique
+     *   name       String
+     *   deleted_at DateTime? // Indicates soft-delete capability
+     *   posts      Post[]
+     * }
+     * ```
+     *
+     * This schema context ensures operations are fully aligned with the actual
+     * database structure and business logic requirements.
+     */
+    prisma_schemas: string;
   }
 }