@autobe/agent 0.21.0 → 0.22.0

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/fulfillJsonSchemaErrorMessages.ts

@@ -0,0 +1,90 @@
+import { StringUtil } from "@autobe/utils";
+import { IValidation } from "typia";
+
+export const fulfillJsonSchemaErrorMessages = (
+  errors: IValidation.IError[],
+): void => {
+  for (const e of errors)
+    if (
+      // type := ["number", "string", ...] case
+      isInvalidJsonSchema(e) &&
+      typeof e.value === "object" &&
+      e.value !== null &&
+      "type" in e.value &&
+      Array.isArray(e.value.type)
+    )
+      e.description = StringUtil.trim`
+        You have defined the JSON schema's type property value as an 
+        array type listing up the every types what you want, but it is not 
+        allowed in the JSON schema.
+        
+        The JSON schema's type property value must be a single string type.
+        In your case, you have to change it to an "oneOf" type which 
+        represents an union type.
+
+        So, please change the value as below:
+
+        \`\`\`
+        {
+          oneOf: [
+        ${e.value.type.map((t) => `    { "type": ${JSON.stringify(t)}, ... },`).join("\n")}
+          ],${"description" in e.value ? `\n  description: ${JSON.stringify(e.value.description)},` : ""}
+        }
+        \`\`\`
+      `;
+    else if (
+      isInvalidJsonSchema(e) &&
+      typeof e.value === "object" &&
+      e.value !== null &&
+      "enum" in e.value &&
+      Array.isArray(e.value.enum)
+    )
+      e.description = StringUtil.trim`
+        You have defined only enum property, but it is not allowed in the 
+        JSON schema. You have to define it as oneOf type containing multiple
+        const types like below:
+        
+        \`\`\`
+        {
+          oneOf: [
+        ${e.value.enum.map((t) => `    { "const": ${JSON.stringify(t)} },`).join("\n")}
+          ],${"description" in e.value ? `\n  description: ${JSON.stringify(e.value.description)},` : ""}
+        }
+        \`\`\`
+      `;
+    else if (e.value === undefined && e.path.endsWith(".description"))
+      // no description
+      e.description = StringUtil.trim`
+        You have missed the "description" property in the JSON schema. 
+        
+        Please fill it with detailed description about the type.
+      `;
+    else if (
+      e.value === undefined &&
+      e.path.endsWith(".required") &&
+      e.expected === "Array<string>"
+    )
+      e.description = StringUtil.trim`
+        You have missed the "required" property in the JSON schema of object type.
+
+        When defining the object type, you have to fill the "required" property
+        which lists up the every required property names.
+
+        Please fill it with the required fields. If you think that there is
+        not any required fields at all, you still have to fill the 
+        "required" property even though it becomes an empty array.
+      `;
+};
+
+const isInvalidJsonSchema = (e: IValidation.IError): boolean =>
+  e.expected.startsWith("(") &&
+  e.expected.endsWith(")") &&
+  e.expected.includes("|") &&
+  e.expected
+    .split("|")
+    .map((s) => s.trim())
+    .every(
+      (s) =>
+        s.startsWith("AutoBeOpenApi.IJsonSchema.") ||
+        s.startsWith("AutoBeOpenApi.IJsonSchemaDescriptive."),
+    );

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

@@ -25,7 +25,7 @@ export const validateAuthorizationSchema = (props: {
     value.properties["token"] = {
       $ref: "#/components/schemas/IAuthorizationToken",
       description: "JWT token information for authentication",
-    } as AutoBeOpenApi.IJsonSchemaDescriptive<AutoBeOpenApi.IJsonSchema.IReference>;
+    } as AutoBeOpenApi.IJsonSchemaDescriptive.IReference;
 
     value.required ??= [];
     if (value.required.includes("token") === false) {
@@ -36,6 +36,6 @@ export const validateAuthorizationSchema = (props: {
 
 const isObjectSchema = (
   schema: AutoBeOpenApi.IJsonSchemaDescriptive,
-): schema is AutoBeOpenApi.IJsonSchemaDescriptive<AutoBeOpenApi.IJsonSchema.IObject> => {
+): schema is AutoBeOpenApi.IJsonSchemaDescriptive.IObject => {
   return "type" in schema && schema.type === "object";
 };

package/src/orchestrate/prisma/orchestratePrismaCorrect.ts

@@ -18,7 +18,6 @@ import { IAutoBePrismaCorrectApplication } from "./structures/IAutoBePrismaCorre
 export function orchestratePrismaCorrect<Model extends ILlmSchema.Model>(
   ctx: AutoBeContext<Model>,
   application: AutoBePrisma.IApplication,
-  life: number = 4,
 ): Promise<IAutoBePrismaValidation> {
   const unique: Set<string> = new Set();
   for (const file of application.files)
@@ -28,7 +27,7 @@ export function orchestratePrismaCorrect<Model extends ILlmSchema.Model>(
       return true;
     });
   application.files = application.files.filter((f) => f.models.length !== 0);
-  return iterate(ctx, application, life);
+  return iterate(ctx, application, ctx.retry);
 }
 
 async function iterate<Model extends ILlmSchema.Model>(