@autobe/agent 0.17.1 → 0.18.0

package/lib/agent/src/orchestrate/realize/structures/IAutoBeRealizeCoderApplication.d.ts

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

package/lib/agent/src/orchestrate/realize/structures/IAutoBeRealizeCoderApplication.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IAutoBeRealizeCoderApplication.js","sourceRoot":"","sources":["../../../../../../src/orchestrate/realize/structures/IAutoBeRealizeCoderApplication.ts"],"names":[],"mappings":""}

package/lib/agent/src/orchestrate/realize/structures/IAutoBeRealizeCompile.d.ts

@@ -0,0 +1,56 @@
+import { AutoBeOpenApi, IAutoBeTypeScriptCompileResult } from "@autobe/interface";
+import { tags } from "typia";
+import { IAutoBeRealizeCoderApplication } from "./IAutoBeRealizeCoderApplication";
+import { FAILED } from "./IAutoBeRealizeFailedSymbol";
+export declare namespace IAutoBeRealizeCompile {
+    export type Result = IAutoBeRealizeCompile.Success | IAutoBeRealizeCompile.Fail;
+    type IBase<T extends "success" | "failed"> = {
+        /**
+         * Indicates whether code generation was attempted. "success" means code was
+         * generated, but compilation may still fail. "failed" means code generation
+         * was not possible (e.g., invalid input).
+         */
+        type: T;
+    };
+    export interface Success extends IBase<"success"> {
+        /**
+         * Operation: An object containing the function specification including the
+         * endpoint
+         */
+        operation: AutoBeOpenApi.IOperation;
+        /** Result */
+        result: IAutoBeRealizeCoderApplication.RealizeCoderOutput;
+    }
+    export interface Fail extends IBase<"failed"> {
+        /**
+         * Operation: An object containing the function specification including the
+         * endpoint
+         */
+        operation: AutoBeOpenApi.IOperation;
+        /** Result */
+        result: FAILED;
+    }
+    export interface CodeArtifact {
+        result: "failed" | "success";
+        content: string;
+        role?: (string & tags.MinLength<1>) | null;
+        endpoint?: AutoBeOpenApi.IEndpoint;
+        location: string;
+        name?: string;
+    }
+    export type FileContentMap = Record<string, CodeArtifact>;
+    export interface CompileDiagnostics {
+        /**
+         * Array containing all errors including previous attempts. Includes errors
+         * that have already been resolved. Used to preserve error context and
+         * identify recurring error patterns.
+         */
+        total: IAutoBeTypeScriptCompileResult.IDiagnostic[];
+        /**
+         * Array containing errors from the most recent code compilation. These are
+         * the errors that need to be resolved in the current iteration.
+         */
+        current: IAutoBeTypeScriptCompileResult.IDiagnostic[];
+    }
+    export {};
+}

package/lib/agent/src/orchestrate/realize/structures/IAutoBeRealizeCompile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IAutoBeRealizeCompile.js","sourceRoot":"","sources":["../../../../../../src/orchestrate/realize/structures/IAutoBeRealizeCompile.ts"],"names":[],"mappings":""}

package/lib/agent/src/orchestrate/realize/structures/IAutoBeRealizeFailedSymbol.d.ts

@@ -0,0 +1,2 @@
+export declare const FAILED: unique symbol;
+export type FAILED = typeof FAILED;

package/lib/agent/src/orchestrate/realize/structures/IAutoBeRealizeFailedSymbol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IAutoBeRealizeFailedSymbol.js","sourceRoot":"","sources":["../../../../../../src/orchestrate/realize/structures/IAutoBeRealizeFailedSymbol.ts"],"names":[],"mappings":";;;AAAa,QAAA,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC"}

package/lib/agent/src/orchestrate/realize/structures/IAutoBeRealizeReviewApplication.d.ts

@@ -0,0 +1,79 @@
+import { IAutoBeRealizeWriteApplication } from "./IAutoBeRealizeWriteApplication";
+export interface IAutoBeRealizeCorrectApplication {
+    review: (props: IAutoBeRealizeCorrectApplication.IProps) => void;
+}
+export declare namespace IAutoBeRealizeCorrectApplication {
+    interface IProps extends IAutoBeRealizeWriteApplication.IProps {
+        /**
+         * Compilation Error Analysis and Resolution Strategy
+         *
+         * This field contains a detailed analysis of TypeScript compilation errors
+         * that occurred during the previous compilation attempt, along with
+         * specific strategies to resolve each error.
+         *
+         * The analysis MUST include:
+         *
+         * 📊 ERROR BREAKDOWN:
+         *
+         * - List of all TypeScript error codes encountered (e.g., TS2339, TS2345)
+         * - Exact error messages and the lines/files where they occurred
+         * - Categorization of errors by type (type mismatch, missing property, etc.)
+         *
+         * 🔍 ROOT CAUSE ANALYSIS:
+         *
+         * - Why each error occurred (e.g., incorrect type assumptions, missing
+         *   fields)
+         * - Relationship between errors (e.g., cascading errors from a single issue)
+         * - Common patterns identified across multiple errors
+         *
+         * 🛠 RESOLUTION STRATEGY:
+         *
+         * - Specific fixes for each error type
+         * - Priority order for addressing errors (fix critical errors first)
+         * - Alternative approaches if the direct fix is not possible
+         *
+         * 📝 SCHEMA VERIFICATION:
+         *
+         * - Re-verification of Prisma schema fields actually available
+         * - Identification of assumed fields that don't exist
+         * - Correct field types and relationships
+         *
+         * ⚠️ COMMON ERROR PATTERNS TO CHECK:
+         *
+         * - Using non-existent fields (e.g., deleted_at, created_by)
+         * - Type mismatches in Prisma operations
+         * - Incorrect date handling (using Date instead of string)
+         * - Missing required fields in create/update operations
+         * - Incorrect relation handling in nested operations
+         *
+         * 🎯 CORRECTION APPROACH:
+         *
+         * - Remove references to non-existent fields
+         * - Fix type conversions (especially dates with toISOStringSafe())
+         * - Simplify complex nested operations into separate queries
+         * - Add missing required fields
+         * - Use correct Prisma input types
+         *
+         * Example structure:
+         *
+         *     Errors Found:
+         *     1. TS2339: Property 'deleted_at' does not exist on type 'User'
+         *        - Cause: Field assumed but not in schema
+         *        - Fix: Remove all deleted_at references
+         *
+         *     2. TS2345: Type 'Date' is not assignable to type 'string'
+         *        - Cause: Direct Date assignment without conversion
+         *        - Fix: Use toISOStringSafe() for all date values
+         *
+         *     Resolution Plan:
+         *     1. First, remove all non-existent field references
+         *     2. Then, fix all date type conversions
+         *     3. Finally, adjust Prisma query structures
+         *
+         * This analysis ensures the review process addresses all compilation errors
+         * systematically and produces error-free code in the corrected
+         * implementation.
+         */
+        errorAnalysis: string;
+    }
+}

package/lib/agent/src/orchestrate/realize/structures/IAutoBeRealizeReviewApplication.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=IAutoBeRealizeReviewApplication.js.map

package/lib/agent/src/orchestrate/realize/structures/IAutoBeRealizeReviewApplication.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IAutoBeRealizeReviewApplication.js","sourceRoot":"","sources":["../../../../../../src/orchestrate/realize/structures/IAutoBeRealizeReviewApplication.ts"],"names":[],"mappings":""}

package/lib/agent/src/orchestrate/realize/structures/IAutoBeRealizeScenarioApplication.d.ts

@@ -0,0 +1,38 @@
+import { AutoBeOpenApi, AutoBeRealizeAuthorization } from "@autobe/interface";
+export declare namespace IAutoBeRealizeScenarioApplication {
+    interface IProps {
+        /** The OpenAPI operation to be realized. */
+        operation: AutoBeOpenApi.IOperation;
+        /**
+         * The name of the function to be generated.
+         *
+         * Derived from the Swagger path and method. The function name must be
+         * written in snake_case. It serves as the entry point in both code
+         * generation and test code.
+         *
+         * Once the function is generated, the function name and file name will be
+         * the same. The generated file will be located at
+         * `src/providers/${function_name}.ts`.
+         */
+        functionName: string;
+        /** For example, `src/providers/${function_name}.ts`. */
+        location: string;
+        /**
+         * List of scenario descriptions for test code generation.
+         *
+         * Each scenario describes the expected behavior of the function under
+         * certain conditions. Used as a basis for TDD-style automated test
+         * generation.
+         */
+        testScenarios: string[];
+        /**
+         * Optional decorator event for customizing code generation behavior.
+         *
+         * Provides additional metadata or instructions that can modify how the
+         * function implementation is generated. Can include custom annotations,
+         * middleware configurations, or special handling directives that affect the
+         * final code output.
+         */
+        decoratorEvent?: AutoBeRealizeAuthorization;
+    }
+}

package/lib/agent/src/orchestrate/realize/structures/IAutoBeRealizeScenarioApplication.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=IAutoBeRealizeScenarioApplication.js.map

package/lib/agent/src/orchestrate/realize/structures/IAutoBeRealizeScenarioApplication.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IAutoBeRealizeScenarioApplication.js","sourceRoot":"","sources":["../../../../../../src/orchestrate/realize/structures/IAutoBeRealizeScenarioApplication.ts"],"names":[],"mappings":""}