@autobe/agent 0.21.0 → 0.22.1

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

@@ -91,45 +91,6 @@ export namespace IAutoBeInterfaceOperationApplication {
       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.
      *

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

@@ -5,19 +5,21 @@ import { AutoBeOpenApi } from "@autobe/interface";
  *
  * Provides functionality to systematically review generated API operations
  * against business requirements, technical specifications, and OpenAPI
- * standards. The review process ensures each operation meets quality criteria
- * before proceeding to implementation.
+ * standards. The review process outputs a structured thinking process with
+ * analytical findings and actionable improvements, along with the final
+ * enhanced operations ready for implementation.
  */
 export interface IAutoBeInterfaceOperationsReviewApplication {
   /**
    * Reviews a batch of API operations for quality and correctness.
    *
-   * Validates each operation's request/response schemas, authentication
-   * handling, error responses, and documentation completeness. Operations are
-   * marked as passed or failed based on compliance with enterprise standards.
+   * Analyzes operations for security vulnerabilities, schema compliance,
+   * logical consistency, and standard adherence. Outputs a structured thinking
+   * process containing review findings and improvement plans, plus the final
+   * production-ready operations with all critical issues resolved.
    *
-   * @param input Collection of operations to review with their validation
-   *   results
+   * @param input Properties containing the thinking process (review & plan)
+   *   and the enhanced operations content
    */
   reviewOperations(
     input: IAutoBeInterfaceOperationsReviewApplication.IProps,
@@ -33,6 +35,47 @@ export namespace IAutoBeInterfaceOperationsReviewApplication {
    * of the AutoBeInterfaceOperationsReviewEvent.
    */
   export interface IProps {
+    /**
+     * Comprehensive thinking process for API operation review.
+     *
+     * Encapsulates the agent's analytical review findings and actionable
+     * improvement plan. This structured thinking process ensures systematic
+     * evaluation of API operations against AutoBE's quality standards before
+     * generating the final enhanced operations.
+     */
+    think: IThink;
+
+    /**
+     * Production-ready operations with all critical issues resolved.
+     *
+     * Final API operations after systematic enhancement:
+     *
+     * - **Security Fixes Applied**: All authentication boundaries enforced,
+     *   sensitive data removed from responses, proper authorization
+     *   implemented
+     * - **Logic Corrections Made**: Return types match operation intent, HTTP
+     *   methods align with semantics, parameters properly utilized
+     * - **Schema Alignment Verified**: All fields exist in Prisma schema, types
+     *   correctly mapped, relationships properly defined
+     * - **Quality Improvements Added**: Enhanced documentation, format
+     *   specifications, validation rules, consistent naming patterns
+     *
+     * If no issues were found during review, this contains the exact original
+     * operations unchanged. These operations are validated and ready for schema
+     * generation and subsequent implementation phases.
+     */
+    content: AutoBeOpenApi.IOperation[];
+  }
+
+  /**
+   * 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.
+   */
+  export interface IThink {
     /**
      * Comprehensive review analysis with prioritized findings.
      *
@@ -77,144 +120,5 @@ export namespace IAutoBeInterfaceOperationsReviewApplication {
      * needed, and the rationale for the modification.
      */
     plan: string;
-
-    /**
-     * Production-ready operations with all critical issues resolved.
-     *
-     * Final API operations after systematic enhancement:
-     *
-     * - **Security Fixes Applied**: All authentication boundaries enforced,
-     *   sensitive data removed from responses, proper authorization
-     *   implemented
-     * - **Logic Corrections Made**: Return types match operation intent, HTTP
-     *   methods align with semantics, parameters properly utilized
-     * - **Schema Alignment Verified**: All fields exist in Prisma schema, types
-     *   correctly mapped, relationships properly defined
-     * - **Quality Improvements Added**: Enhanced documentation, format
-     *   specifications, validation rules, consistent naming patterns
-     *
-     * If no issues were found during review, this contains the exact original
-     * operations unchanged. These operations are validated and ready for schema
-     * generation and subsequent implementation phases.
-     */
-    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;
-
-    /**
-     * Primary Prisma model name for this operation.
-     *
-     * Identifies the main database table/model that this operation targets.
-     * This must match exactly with the Prisma model name defined in the schema.
-     * When soft deletion is specified, this model name indicates which table
-     * should be soft-deleted.
-     *
-     * For example:
-     * - In a "GET /users/:id" operation, this would be "User"
-     * - In a "POST /articles" operation, this would be "Article"
-     * - In a "DELETE /comments/:id" with soft delete, this specifies the "Comment" model to soft-delete
-     *
-     * This property is essential for:
-     * - Determining the primary entity for CRUD operations
-     * - Identifying which table to apply soft deletion to
-     * - Validating operations against the correct Prisma model
-     * - Generating appropriate database queries and validations
-     */
-    model_name: string;
-
-    /**
-     * Soft delete column name for the Prisma models.
-     *
-     * Specifies the column name used for soft deletion in the database tables
-     * associated with this operation. When set to a non-null value, it indicates
-     * that the related entities support soft deletion through this column
-     * (typically a timestamp field like `deleted_at` or `deletedAt`).
-     *
-     * When null, it means the entities involved in this operation use hard
-     * deletion or don't support deletion at all. This information is crucial
-     * for generating appropriate CRUD operations and ensuring data integrity
-     * policies are correctly implemented.
-     *
-     * Common soft delete patterns:
-     * - `"deleted_at"`: Records deletion timestamp
-     * - `"deletedAt"`: Camel-cased deletion timestamp
-     * - `"is_deleted"`: Boolean flag for deletion status
-     * - `null`: No soft deletion (hard delete only)
-     */
-    soft_delete_column: string | null;
   }
 }

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

@@ -29,15 +29,44 @@ export namespace IAutoBeInterfaceSchemasReviewApplication {
    * interface to understand what outputs are required.
    */
   export interface IProps {
+    think: IThink;
+
+    /**
+     * Final validated and enhanced schemas ready for production use.
+     *
+     * DO:
+     *
+     * - Include valid OpenAPI schema definitions
+     * - Include all entities that were in the original input
+     * - Provide fixed versions if original schemas have issues
+     * - Rename entities correctly if names are wrong
+     * - Include created variants if schemas are missing them
+     *
+     * DO NOT:
+     *
+     * - Return an empty object {} (this will delete all schemas)
+     * - Return undefined or null
+     * - Include explanations or excuses in schema descriptions
+     * - Leave broken schemas unfixed
+     *
+     * When original schemas are beyond repair, recreate them properly based on
+     * entity names and context. This field becomes the final schemas used by
+     * the system, so it must always contain complete, valid schemas.
+     */
+    content: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>;
+  }
+
+  export interface IThink {
     /**
      * Issues and problems found during schema analysis.
      *
-     * DO: Document only problems that need fixing.
-     * DO NOT: Include positive feedback, compliments, or confirmations
+     * DO: Document only problems that need fixing. DO NOT: Include positive
+     * feedback, compliments, or confirmations
      *
      * Focus exclusively on issues organized by severity:
      *
      * Severity levels:
+     *
      * - Security vulnerabilities (exposed passwords, missing auth boundaries)
      * - Missing required variants, incorrect type mappings
      * - Missing format specifications, incomplete relationships
@@ -63,30 +92,5 @@ export namespace IAutoBeInterfaceSchemasReviewApplication {
      * field.
      */
     plan: string;
-
-    /**
-     * Final validated and enhanced schemas ready for production use.
-     *
-     * DO:
-     * - Include valid OpenAPI schema definitions
-     * - Include all entities that were in the original input
-     * - Provide fixed versions if original schemas have issues
-     * - Rename entities correctly if names are wrong
-     * - Include created variants if schemas are missing them
-     *
-     * DO NOT:
-     * - Return an empty object {} (this will delete all schemas)
-     * - Return undefined or null
-     * - Include explanations or excuses in schema descriptions
-     * - Leave broken schemas unfixed
-     *
-     * When original schemas are beyond repair, recreate them properly based on
-     * entity names and context. This field becomes the final schemas used by
-     * the system, so it must always contain complete, valid schemas.
-     */
-    content: Record<
-      string,
-      AutoBeOpenApi.IJsonSchemaDescriptive<AutoBeOpenApi.IJsonSchema>
-    >;
   }
 }

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

@@ -0,0 +1,171 @@
+import { AutoBeOpenApi } from "@autobe/interface";
+import { AutoBeOpenApiTypeChecker, StringUtil } from "@autobe/utils";
+import typia, { tags } from "typia";
+
+export namespace JsonSchemaFactory {
+  export const presets = (
+    typeNames: Set<string>,
+  ): Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> => {
+    const schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> = {};
+    for (const [key, value] of Object.entries(DEFAULT_SCHEMAS)) {
+      schemas[key] = value;
+      typeNames.delete(key);
+    }
+    for (const key of typeNames)
+      if (isPage(key)) {
+        const data: string = getPageName(key);
+        schemas[key] = page(data);
+        typeNames.delete(key);
+        typeNames.add(data);
+      }
+    return schemas;
+  };
+
+  export const authorize = (
+    schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>,
+  ): void => {
+    for (const [key, value] of Object.entries(schemas)) {
+      if (key.endsWith(".IAuthorized") === false) continue;
+      else if (AutoBeOpenApiTypeChecker.isObject(value) === false) continue;
+
+      const parent: AutoBeOpenApi.IJsonSchemaDescriptive | undefined =
+        schemas[key.substring(0, key.length - ".IAuthorized".length)];
+      if (parent === undefined) continue;
+      else if (AutoBeOpenApiTypeChecker.isObject(parent) === false) continue;
+
+      value.properties = {
+        ...parent.properties,
+        ...value.properties,
+      };
+      value.required = [...parent.required];
+      if (value.required.includes("id") === false) value.required.push("id");
+      if (value.required.includes("token") === false)
+        value.required.push("token");
+    }
+  };
+
+  export const page = (
+    key: string,
+  ): AutoBeOpenApi.IJsonSchemaDescriptive.IObject => ({
+    type: "object",
+    properties: {
+      pagination: {
+        $ref: "#/components/schemas/IPage.IPagination",
+        description: "Page information.",
+      },
+      data: {
+        type: "array",
+        items: {
+          $ref: `#/components/schemas/${key}`,
+        },
+        description: "List of records.",
+      },
+    },
+    required: ["pagination", "data"],
+    description: StringUtil.trim`
+      A page.
+  
+      Collection of records with pagination information.
+    `,
+  });
+
+  export const fix = (path: string, input: unknown): void => {
+    if (isRecord(input) === false || isRecord(input[path]) === false) return;
+
+    if (input[path].description) delete input[path].description;
+    if (input[path].required) delete input[path].required;
+
+    for (const key of Object.keys(input[path]))
+      if (DEFAULT_SCHEMAS[key] !== undefined)
+        input[path][key] = DEFAULT_SCHEMAS[key];
+      else if (isPage(key) === true) {
+        const data: string = key.substring("IPage".length);
+        input[path][key] = page(data);
+      }
+  };
+
+  export const isPage = (key: string): boolean =>
+    key.startsWith("IPage") === true &&
+    key.startsWith("IPage.") === false &&
+    key !== "IPage";
+
+  export const getPageName = (key: string): string =>
+    key.substring("IPage".length);
+
+  const isRecord = (input: unknown): input is Record<string, unknown> =>
+    typeof input === "object" && input !== null;
+}
+
+const DEFAULT_SCHEMAS = typia.assertEquals<
+  Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>
+>(
+  typia.json.schemas<[IPage.IPagination, IAuthorizationToken]>().components
+    ?.schemas,
+);
+
+namespace IPage {
+  /** Page information. */
+  export interface IPagination {
+    /** Current page number. */
+    current: number & tags.Type<"uint32">;
+
+    /** Limitation of records per a page. */
+    limit: number & tags.Type<"uint32">;
+
+    /** Total records in the database. */
+    records: number & tags.Type<"uint32">;
+
+    /**
+     * Total pages.
+     *
+     * Equal to {@link records} / {@link limit} with ceiling.
+     */
+    pages: number & tags.Type<"uint32">;
+  }
+}
+
+/**
+ * Authorization token response structure.
+ *
+ * This interface defines the structure of the authorization token response
+ * returned after successful user authentication. It contains both access and
+ * 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
+ * applications.
+ */
+interface IAuthorizationToken {
+  /**
+   * JWT access token for authenticated requests.
+   *
+   * This token should be included in the Authorization header for subsequent
+   * authenticated API requests as `Bearer {token}`.
+   */
+  access: string;
+
+  /**
+   * Refresh token for obtaining new access tokens.
+   *
+   * This token can be used to request new access tokens when the current access
+   * token expires, extending the user's session.
+   */
+  refresh: string;
+
+  /**
+   * Access token expiration timestamp.
+   *
+   * ISO 8601 date-time string indicating when the access token will expire and
+   * can no longer be used for authentication.
+   */
+  expired_at: string & tags.Format<"date-time">;
+
+  /**
+   * Refresh token expiration timestamp.
+   *
+   * ISO 8601 date-time string indicating the latest time until which the
+   * refresh token can be used to obtain new access tokens.
+   */
+  refreshable_until: string & tags.Format<"date-time">;
+}

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

@@ -0,0 +1,83 @@
+import { AutoBeOpenApi } from "@autobe/interface";
+import { MapUtil } from "@autobe/utils";
+import { OpenApiTypeChecker } from "@samchon/openapi";
+
+export namespace JsonSchemaNamingConvention {
+  export const operations = (operations: AutoBeOpenApi.IOperation[]): void => {
+    const typeNames: Set<string> = new Set();
+    operate(typeNames, operations);
+  };
+
+  export const schemas = (
+    operations: AutoBeOpenApi.IOperation[],
+    ...componentSchemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>[]
+  ): void => {
+    const typeNames: Set<string> = new Set();
+    for (const schemas of componentSchemas)
+      for (const key of Object.keys(schemas)) typeNames.add(key);
+    const answer = operate(typeNames, operations);
+
+    for (const dict of componentSchemas)
+      for (const x of Object.keys(dict)) {
+        const y: string = answer(x);
+        if (x === y) continue;
+        dict[y] = dict[x]!;
+        delete dict[x];
+      }
+    for (const dict of componentSchemas)
+      for (const x of Object.values(dict)) {
+        OpenApiTypeChecker.visit({
+          components: { schemas: dict },
+          schema: x,
+          closure: (s) => {
+            if (OpenApiTypeChecker.isReference(s) === false) return;
+            s.$ref = `#/components/schemas/${answer(s.$ref.split("/").pop()!)}`;
+          },
+        });
+      }
+  };
+
+  const operate = (
+    typeNames: Set<string>,
+    operations: AutoBeOpenApi.IOperation[],
+  ): ((v: string) => string) => {
+    for (const op of operations) {
+      if (op.requestBody) typeNames.add(op.requestBody.typeName);
+      if (op.responseBody) typeNames.add(op.responseBody.typeName);
+    }
+    const answer = prepare(typeNames);
+    for (const op of operations) {
+      if (op.requestBody)
+        op.requestBody.typeName = answer(op.requestBody.typeName);
+      if (op.responseBody)
+        op.responseBody.typeName = answer(op.responseBody.typeName);
+    }
+    return answer;
+  };
+
+  const prepare = (typeNames: Set<string>): ((v: string) => string) => {
+    const similar: Map<string, string[]> = new Map();
+    const getKey = (v: string) => v.split(".")[0]!.toLowerCase();
+    const getValue = (v: string) => v.split(".")[0]!;
+    const emplace = (v: string) =>
+      MapUtil.take(similar, getKey(v), () => []).push(getValue(v));
+
+    for (const v of typeNames) emplace(v);
+
+    const solution: Map<string, string> = new Map();
+    for (const [key, values] of similar) {
+      if (values.length === 1) continue;
+      const winner: string = values.sort(
+        (a, b) => countCapitalLetters(b) - countCapitalLetters(a),
+      )[0]!;
+      solution.set(key, winner);
+    }
+    return (v: string) => {
+      const key: string = getKey(v);
+      if (solution.has(key) === false) return v;
+      return [solution.get(key), ...v.split(".").slice(1)].join(".");
+    };
+  };
+}
+
+const countCapitalLetters = (str: string) => (str.match(/[A-Z]/g) || []).length;

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

@@ -0,0 +1,66 @@
+import { AutoBeOpenApi } from "@autobe/interface";
+import { AutoBeOpenApiTypeChecker, StringUtil } from "@autobe/utils";
+import { IValidation } from "typia";
+import { Escaper } from "typia/lib/utils/Escaper";
+
+export namespace JsonSchemaValidator {
+  export interface IProps {
+    errors: IValidation.IError[];
+    schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>;
+    path: string;
+  }
+
+  export const validate = (props: IProps): void => {
+    authorization(props);
+    validateKey(props);
+  };
+
+  const authorization = (props: IProps): void => {
+    for (const [key, value] of Object.entries(props.schemas)) {
+      if (!key.endsWith(".IAuthorized")) continue;
+
+      // Check if it's an object type
+      if (AutoBeOpenApiTypeChecker.isObject(value) === false) {
+        props.errors.push({
+          path: `${props.path}.${key}`,
+          expected: `AutoBeOpenApi.IJsonSchemaDescriptive<AutoBeOpenApi.IJsonSchema.IObject>`,
+          value: value,
+          description: `${key} must be an object type for authorization responses`,
+        });
+        continue;
+      }
+
+      // Check if token property exists
+      value.properties ??= {};
+      value.properties["token"] = {
+        $ref: "#/components/schemas/IAuthorizationToken",
+        description: "JWT token information for authentication",
+      } as AutoBeOpenApi.IJsonSchemaDescriptive.IReference;
+
+      value.required ??= [];
+      if (value.required.includes("token") === false)
+        value.required.push("token");
+    }
+  };
+
+  const validateKey = (props: IProps): void => {
+    for (const key of Object.keys(props.schemas)) {
+      const variable: boolean = key.split(".").every(Escaper.variable);
+      if (variable === false)
+        props.errors.push({
+          path: `${props.path}[${JSON.stringify(key)}]`,
+          expected: "Valid variable name",
+          value: key,
+          description: StringUtil.trim`
+            JSON schema type name must be a valid variable name.
+
+            Even though JSON schema type name allows dot(.) character, but
+            each segment separated by dot(.) must be a valid variable name.
+
+            Current key name ${JSON.stringify(key)} is not valid. Change
+            it to a valid variable name at the next time.
+          `,
+        });
+    }
+  };
+}