@autobe/agent 0.25.7 → 0.27.0

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

@@ -86,7 +86,11 @@ export namespace IAutoBeInterfaceOperationApplication {
    * }
    * ```
    */
-  export interface IOperation extends AutoBeOpenApi.IEndpoint {
+  export interface IOperation
+    extends Omit<
+      AutoBeOpenApi.IEndpoint,
+      "authorizationActor" | "prerequisites"
+    > {
     /**
      * Specification of the API operation.
      *
@@ -341,58 +345,58 @@ export namespace IAutoBeInterfaceOperationApplication {
     name: string & CamelCasePattern;
 
     /**
-     * Authorization roles required to access this API operation.
+     * Authorization actors required to access this API operation.
      *
-     * This field specifies which user roles are allowed to access this
-     * endpoint. Multiple roles can be specified to allow different types of
+     * This field specifies which user actors are allowed to access this
+     * endpoint. Multiple actors can be specified to allow different types of
      * users to access the same endpoint.
      *
-     * ## ⚠️ CRITICAL: Role Multiplication Effect
+     * ## ⚠️ CRITICAL: Actor Multiplication Effect
      *
-     * **EACH ROLE IN THIS ARRAY GENERATES A SEPARATE ENDPOINT**
+     * **EACH ACTOR 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
+     * - Total generated endpoints = operations × average actors.length
+     * - Example: 100 operations with 3 actors each = 300 actual endpoints
      *
      * ## 🔴 AVOID OVER-GENERATION
      *
-     * **DO NOT create role-specific endpoints when a public endpoint would
+     * **DO NOT create actor-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
+     * - ✅ GOOD: Single public endpoint `[]` with actor-based filtering in business
      *   logic
      *
-     * **DO NOT enumerate all possible roles when the Prisma schema uses a
+     * **DO NOT enumerate all possible actors 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
+     * - The actual actor checking happens in business logic, not at the endpoint
      *   level
      *
      * ## Naming Convention
      *
-     * DO: Use camelCase for all role names.
+     * DO: Use camelCase for all actor names.
      *
      * ## Important Guidelines
      *
      * - Set to empty array `[]` for public endpoints that require no
      *   authentication
-     * - Set to array with role strings for role-restricted endpoints
-     * - **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
+     * - Set to array with actor strings for actor-restricted endpoints
+     * - **MINIMIZE the number of actors per endpoint to prevent explosion**
+     * - Consider if the endpoint can be public with actor-based filtering instead
+     * - The actor names match exactly with the user type/actor defined in the
      *   database
      * - This will be used by the Realize Agent to generate appropriate decorator
      *   and authorization logic in the provider functions
      * - The controller will apply the corresponding authentication decorator
-     *   based on these roles
+     *   based on these actors
      *
      * ## Examples
      *
@@ -410,17 +414,17 @@ export namespace IAutoBeInterfaceOperationApplication {
      *
      * 1. **Start with public `[]` for all read operations** unless sensitive data
      *    is involved
-     * 2. **Use single role `["user"]` for authenticated operations** and handle
+     * 2. **Use single actor `["user"]` for authenticated operations** and handle
      *    permissions in business logic
-     * 3. **Only use multiple roles when absolutely necessary** for different
+     * 3. **Only use multiple actors when absolutely necessary** for different
      *    business logic paths
-     * 4. **Remember: Fewer roles = Fewer endpoints = Better performance and
+     * 4. **Remember: Fewer actors = 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
      * will receive the authenticated user object with the appropriate type.
      */
-    authorizationRoles: Array<string & CamelCasePattern & tags.MinLength<1>>;
+    authorizationActors: Array<string & CamelCasePattern & tags.MinLength<1>>;
   }
 }

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

@@ -18,8 +18,8 @@ export interface IAutoBeInterfaceOperationsReviewApplication {
    * process containing review findings and improvement plans, plus the final
    * production-ready operations with all critical issues resolved.
    *
-   * @param input Properties containing the thinking process (review & plan)
-   *   and the enhanced operations content
+   * @param input Properties containing the thinking process (review & plan) and
+   *   the enhanced operations content
    */
   reviewOperations(
     input: IAutoBeInterfaceOperationsReviewApplication.IProps,
@@ -32,7 +32,7 @@ export namespace IAutoBeInterfaceOperationsReviewApplication {
    *
    * Contains both the input operations to be reviewed and the outputs generated
    * by the Interface Operations Review Agent, which will be published as part
-   * of the AutoBeInterfaceOperationsReviewEvent.
+   * of the AutoBeInterfaceOperationReviewEvent.
    */
   export interface IProps {
     /**
@@ -70,10 +70,10 @@ export namespace IAutoBeInterfaceOperationsReviewApplication {
   /**
    * Structured thinking process for comprehensive API operation review.
    *
-   * Combines analytical review findings with actionable improvement planning
-   * to guide the systematic enhancement of API operations. This thinking
-   * structure ensures all aspects of API quality are evaluated and addressed
-   * before producing the final operations.
+   * Combines analytical review findings with actionable improvement planning to
+   * guide the systematic enhancement of API operations. This thinking structure
+   * ensures all aspects of API quality are evaluated and addressed before
+   * producing the final operations.
    */
   export interface IThink {
     /**

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

@@ -0,0 +1,108 @@
+import { AutoBeOpenApi } from "@autobe/interface";
+
+export interface IAutoBeInterfaceSchemaContentReviewApplication {
+  /**
+   * Reviews and validates DTO content completeness and consistency in OpenAPI
+   * schemas.
+   *
+   * This specialized content review function focuses exclusively on ensuring
+   * DTOs accurately and completely represent their business entities. It
+   * validates field completeness, type accuracy, required field settings, and
+   * documentation quality.
+   *
+   * The review process validates and corrects:
+   *
+   * - Field completeness against Prisma schema
+   * - Data type accuracy (Prisma to OpenAPI type mappings)
+   * - Required field arrays matching Prisma nullability
+   * - Description quality and comprehensiveness
+   * - Consistency across DTO variants (IEntity, ICreate, IUpdate, ISummary)
+   * - Missing variant detection and creation
+   *
+   * @param props Content review results including completeness issues found,
+   *   fixes applied, and modified schemas
+   */
+  review: (
+    props: IAutoBeInterfaceSchemaContentReviewApplication.IProps,
+  ) => void;
+}
+
+export namespace IAutoBeInterfaceSchemaContentReviewApplication {
+  /**
+   * Output structure for the content review function.
+   *
+   * Contains the content analysis, completeness fixes, and schemas modified for
+   * content quality during the validation process.
+   */
+  export interface IProps {
+    /** Content analysis and completeness planning information. */
+    think: IThink;
+
+    /**
+     * Modified schemas resulting from content and completeness fixes.
+     *
+     * Contains ONLY the schemas that were modified for content reasons during
+     * review. This includes both modified existing schemas and newly created
+     * variant schemas.
+     *
+     * Content modifications include:
+     *
+     * - Adding missing fields from Prisma schema
+     * - Correcting data type mappings
+     * - Fixing required field arrays
+     * - Enhancing or adding descriptions
+     * - Creating missing variant types (ISummary, IUpdate, etc.)
+     * - Ensuring cross-variant consistency
+     *
+     * Return empty object {} when all content is already complete and accurate,
+     * requiring no modifications.
+     */
+    content: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>;
+  }
+
+  export interface IThink {
+    /**
+     * Content completeness and quality findings from the review process.
+     *
+     * Documents all content issues discovered during validation, categorized by
+     * type: field completeness, type accuracy, required fields, descriptions,
+     * variant consistency, and missing variants. Each issue includes the
+     * affected schema and specific problem identified.
+     *
+     * Common issues documented:
+     *
+     * - Field Completeness: Missing fields that exist in Prisma schema
+     * - Type Accuracy: Incorrect type mappings (e.g., Decimal as string)
+     * - Required Fields: Misaligned with Prisma nullable settings
+     * - Description Quality: Missing or inadequate descriptions
+     * - Variant Consistency: Same field with different types across variants
+     * - Missing Variants: Required DTO variants not present
+     *
+     * Should state "No content or completeness issues found." when all schemas
+     * have complete and accurate content.
+     */
+    review: string;
+
+    /**
+     * Content corrections and completeness fixes applied during review.
+     *
+     * Lists all content modifications implemented, organized by fix type:
+     * fields added, types corrected, required arrays fixed, descriptions
+     * enhanced, consistency fixes, and variants created. Documents both field-
+     * level changes and schema-level additions.
+     *
+     * Typical fixes documented:
+     *
+     * - Fields added to match Prisma schema
+     * - Type mappings corrected (Int→integer, Decimal→number)
+     * - Required arrays aligned with nullability
+     * - Descriptions added or enhanced for clarity
+     * - Variant consistency issues resolved
+     * - Missing variants created with appropriate fields
+     *
+     * Should state "No content issues require fixes. All DTOs are complete and
+     * consistent." when no content modifications were necessary.
+     */
+    plan: string;
+  }
+}

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

@@ -0,0 +1,104 @@
+import { AutoBeOpenApi } from "@autobe/interface";
+
+export interface IAutoBeInterfaceSchemaRelationReviewApplication {
+  /**
+   * Reviews and validates DTO relations and structural patterns in OpenAPI
+   * schemas.
+   *
+   * This specialized relation review function focuses exclusively on data
+   * relations, foreign key transformations, and structural integrity. It
+   * ensures proper modeling of business domains while preventing circular
+   * references and enabling efficient code generation.
+   *
+   * The review process validates and corrects:
+   *
+   * - Relation classifications (Composition vs Association vs Aggregation)
+   * - Foreign key to object transformations in response DTOs
+   * - Actor reversal violations (e.g., User containing articles array)
+   * - Inline object extractions to named types with $ref
+   * - IInvert pattern applications for alternative perspectives
+   *
+   * @param props Relation review results including violations found, fixes
+   *   applied, and modified schemas
+   */
+  review: (
+    props: IAutoBeInterfaceSchemaRelationReviewApplication.IProps,
+  ) => void;
+}
+
+export namespace IAutoBeInterfaceSchemaRelationReviewApplication {
+  /**
+   * Output structure for the relation review function.
+   *
+   * Contains the relation analysis, structural fixes, and schemas modified for
+   * proper relations during the validation process.
+   */
+  export interface IProps {
+    /** Relation analysis and structural planning information. */
+    think: IThink;
+
+    /**
+     * Modified schemas resulting from relation and structural fixes.
+     *
+     * Contains ONLY the schemas that were modified for relation or structural
+     * reasons during review. This includes both modified existing schemas and
+     * newly created schemas (extracted types, IInvert types).
+     *
+     * Relation modifications include:
+     *
+     * - Extracting inline objects to named types with $ref
+     * - Transforming foreign keys to object references
+     * - Removing incorrect reverse relations
+     * - Creating new IInvert types for alternative views
+     * - Correcting relation types (composition/association/aggregation)
+     *
+     * Return empty object {} when all relations are already correct and no
+     * structural fixes were needed.
+     */
+    content: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>;
+  }
+
+  export interface IThink {
+    /**
+     * Relation and structural violation findings from the review process.
+     *
+     * Documents all relation issues discovered during validation, categorized
+     * by severity and type. Each violation includes the affected schema,
+     * specific relation problem, and theoretical justification.
+     *
+     * Common violations documented:
+     *
+     * - CRITICAL: Inline object types instead of named types with $ref
+     * - CRITICAL: Actor reversal violations (User.articles[], Seller.sales[])
+     * - HIGH: Raw foreign keys instead of object references
+     * - HIGH: Wrong relation types (event-driven data as composition)
+     * - MEDIUM: Missing IInvert types for independent child views
+     * - LOW: Naming convention violations (plural instead of singular)
+     *
+     * Should state "No relation or structure issues found." when all schemas
+     * have correct relations.
+     */
+    review: string;
+
+    /**
+     * Relation corrections and structural fixes applied during review.
+     *
+     * Lists all relation modifications implemented, organized by fix type and
+     * impact. Documents both schemas modified and new schemas created during
+     * the fix process.
+     *
+     * Typical fixes documented:
+     *
+     * - Inline objects extracted to named types
+     * - Foreign keys transformed to object references
+     * - Actor reversal arrays removed with API endpoint suggestions
+     * - IInvert types created with parent context
+     * - Relation types corrected based on lifecycle analysis
+     * - Naming conventions standardized
+     *
+     * Should state "No relation issues require fixes. All relations are
+     * properly structured." when no modifications were necessary.
+     */
+    plan: string;
+  }
+}

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

@@ -0,0 +1,45 @@
+import { AutoBeInterfaceSchemaRefactor } from "@autobe/interface";
+
+export interface IAutoBeInterfaceSchemaRenameApplication {
+  /**
+   * Analyze DTO type names and identify naming violations.
+   *
+   * This method examines existing DTO type names to detect violations of the
+   * CRITICAL naming rule: ALL words from the Prisma table name MUST be
+   * preserved in the DTO type name. Omitting intermediate words breaks
+   * type-to-table traceability and causes system failures.
+   *
+   * The method receives a list of Prisma table names and current DTO type
+   * names, then identifies which type names incorrectly omit service prefixes
+   * or intermediate components from their corresponding table names.
+   *
+   * @param props Properties containing refactoring operations to fix naming
+   *   violations.
+   */
+  rename(props: IAutoBeInterfaceSchemaRenameApplication.IProps): void;
+}
+export namespace IAutoBeInterfaceSchemaRenameApplication {
+  export interface IProps {
+    /**
+     * List of refactoring operations to rename incorrectly named DTO types.
+     *
+     * Each refactor specifies:
+     *
+     * - `from`: The current INCORRECT type name (e.g., "ISale", "IBbsComment")
+     * - `to`: The CORRECT type name with all components preserved (e.g.,
+     *   "IShoppingSale", "IBbsArticleComment")
+     *
+     * IMPORTANT: Only include type names that violate the naming rules. If a
+     * type name correctly preserves all components from the table name, do NOT
+     * include it in the refactors list.
+     *
+     * The orchestrator will automatically handle:
+     *
+     * - Renaming the base type (e.g., ISale → IShoppingSale)
+     * - Renaming all variants (e.g., ISale.ICreate → IShoppingSale.ICreate)
+     * - Renaming page types (e.g., IPageISale → IPageIShoppingSale)
+     * - Updating all $ref references throughout the OpenAPI document
+     */
+    refactors: AutoBeInterfaceSchemaRefactor[];
+  }
+}

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

@@ -0,0 +1,99 @@
+import { AutoBeOpenApi } from "@autobe/interface";
+
+export interface IAutoBeInterfaceSchemaSecurityReviewApplication {
+  /**
+   * Reviews and validates OpenAPI schema definitions for security compliance.
+   *
+   * This specialized security review function focuses exclusively on
+   * authentication boundaries, data protection, and system integrity. It
+   * enforces strict security policies to prevent authentication bypass, data
+   * exposure, and unauthorized access.
+   *
+   * The review process identifies and removes:
+   *
+   * - Authentication context fields in request DTOs (e.g., bbs_member_id)
+   * - Password and token fields in response DTOs
+   * - System-managed fields in request DTOs
+   * - Phantom fields that don't exist in Prisma schema
+   *
+   * @param props Security review results including violations found, fixes
+   *   applied, and modified schemas
+   */
+  review: (
+    props: IAutoBeInterfaceSchemaSecurityReviewApplication.IProps,
+  ) => void;
+}
+
+export namespace IAutoBeInterfaceSchemaSecurityReviewApplication {
+  /**
+   * Output structure for the security review function.
+   *
+   * Contains the security analysis, remediation actions, and schemas modified
+   * for security compliance during the validation process.
+   */
+  export interface IProps {
+    /** Security analysis and remediation planning information. */
+    think: IThink;
+
+    /**
+     * Modified schemas resulting from security fixes.
+     *
+     * Contains ONLY the schemas that were modified for security reasons during
+     * review. This focused output enables precise tracking of security-related
+     * changes.
+     *
+     * Security modifications include:
+     *
+     * - Removing authentication context fields (user_id, session_id, etc.)
+     * - Removing password/token fields from responses
+     * - Removing system-managed fields from requests
+     * - Removing phantom fields not in Prisma schema
+     *
+     * Return empty object {} when all schemas are already secure and no
+     * security fixes were needed.
+     */
+    content: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>;
+  }
+
+  export interface IThink {
+    /**
+     * Security violation findings from the review process.
+     *
+     * Documents all security issues discovered during validation, categorized
+     * by severity level (CRITICAL, HIGH, MEDIUM, LOW). Each violation includes
+     * the affected schema name, field name, and specific security rule
+     * violated.
+     *
+     * Common violations documented:
+     *
+     * - CRITICAL: Authentication context in requests (bbs_member_id, session_id)
+     * - CRITICAL: Password/token exposure in responses
+     * - CRITICAL: Phantom fields not existing in Prisma schema
+     * - HIGH: System-managed fields in requests
+     * - HIGH: Immutable ownership fields in updates
+     *
+     * Should state "No security violations found." when all schemas pass
+     * security validation.
+     */
+    review: string;
+
+    /**
+     * Security remediation actions applied to fix identified violations.
+     *
+     * Lists all security fixes implemented during the review process, organized
+     * by fix type and priority. Each fix documents which field was removed or
+     * modified and from which schema.
+     *
+     * Typical fixes documented:
+     *
+     * - Authentication context fields removed from request DTOs
+     * - Sensitive data removed from response DTOs
+     * - Phantom fields deleted to match Prisma schema
+     * - System fields removed from client-controllable DTOs
+     *
+     * Should state "No security issues require fixes. All schemas are secure."
+     * when no security modifications were necessary.
+     */
+    plan: string;
+  }
+}

package/src/orchestrate/interface/utils/JsonSchemaFactory.ts

@@ -1,6 +1,6 @@
 import { AutoBeOpenApi, AutoBePrisma } from "@autobe/interface";
 import { AutoBeOpenApiTypeChecker, StringUtil } from "@autobe/utils";
-import { OpenApiTypeChecker } from "@samchon/openapi";
+import { OpenApi, OpenApiTypeChecker } from "@samchon/openapi";
 import typia, { tags } from "typia";
 
 export namespace JsonSchemaFactory {
@@ -53,6 +53,7 @@ export namespace JsonSchemaFactory {
     application: AutoBePrisma.IApplication;
   }): void => {
     removeUnused(props.document);
+    removeDuplicated(props.document);
     fixTimestamps(props);
   };
 
@@ -84,6 +85,47 @@ export namespace JsonSchemaFactory {
       if (used.has(key) === false) delete document.components.schemas[key];
   };
 
+  const removeDuplicated = (document: AutoBeOpenApi.IDocument): void => {
+    // gather duplicated schemas
+    const correct: Map<string, string> = new Map();
+    for (const key of Object.keys(document.components.schemas)) {
+      if (key.includes(".") === false) continue;
+      const dotRemoved: string = key.replace(".", "");
+      if (document.components.schemas[dotRemoved] === undefined) continue;
+      correct.set(dotRemoved, key);
+    }
+
+    // fix operations' references
+    for (const op of document.operations) {
+      if (op.requestBody && correct.has(op.requestBody.typeName))
+        op.requestBody.typeName = correct.get(op.requestBody.typeName)!;
+      if (op.responseBody && correct.has(op.responseBody.typeName))
+        op.responseBody.typeName = correct.get(op.responseBody.typeName)!;
+    }
+
+    // fix schemas' references
+    const $refChangers: Map<OpenApi.IJsonSchema, () => void> = new Map();
+    for (const value of Object.values(document.components.schemas))
+      OpenApiTypeChecker.visit({
+        components: { schemas: document.components.schemas },
+        schema: value,
+        closure: (next) => {
+          if (OpenApiTypeChecker.isReference(next) === false) return;
+          const x: string = next.$ref.split("/").pop()!;
+          const y: string | undefined = correct.get(x);
+          if (y === undefined) return;
+          $refChangers.set(
+            next,
+            () => (next.$ref = `#/components/schemas/${y}`),
+          );
+        },
+      });
+    for (const fn of $refChangers.values()) fn();
+
+    // remove duplicated schemas
+    for (const key of correct.keys()) delete document.components.schemas[key];
+  };
+
   const fixTimestamps = (props: {
     document: AutoBeOpenApi.IDocument;
     application: AutoBePrisma.IApplication;
@@ -220,8 +262,8 @@ namespace IPage {
  * refresh tokens along with their expiration information.
  *
  * This token structure is automatically included in API schemas when the system
- * detects authorization roles in the requirements analysis phase. It provides a
- * standard format for JWT-based authentication across the generated backend
+ * detects authorization actors in the requirements analysis phase. It provides
+ * a standard format for JWT-based authentication across the generated backend
  * applications.
  */
 interface IAuthorizationToken {