@autobe/agent 0.30.4 → 0.30.5

package/src/orchestrate/realize/structures/IAutoBeRealizeTransformerPlanApplication.ts

@@ -3,26 +3,18 @@ import { IAutoBePreliminaryGetDatabaseSchemas } from "../../common/structures/IA
 import { IAutoBePreliminaryGetInterfaceSchemas } from "../../common/structures/IAutoBePreliminaryGetInterfaceSchemas";
 
 /**
- * Function calling interface for planning transformer DTO generation.
+ * Plans whether a single DTO needs a transformer. Sets databaseSchemaName to
+ * null for non-transformable DTOs.
  *
- * Guides the AI agent through analyzing a single DTO type and determining
- * whether it needs a transformer. Each DTO is analyzed independently, enabling
- * parallel processing across all DTOs.
- *
- * The planning follows a structured RAG workflow: preliminary context gathering
- * (database schemas, DTO schemas) → eligibility analysis → plan generation.
- *
- * **Key Decisions**: Not all DTOs require transformers. The agent must
- * distinguish transformable DTOs (Read DTO + DB-backed + Direct mapping) from
+ * **Key Decisions**: Not all DTOs require transformers. Distinguish
+ * transformable DTOs (Read DTO + DB-backed + direct mapping) from
  * non-transformable DTOs (request params, pagination wrappers, business logic
- * types) and set databaseSchemaName to null for non-transformable ones.
+ * types).
  */
 export interface IAutoBeRealizeTransformerPlanApplication {
   /**
-   * Process transformer planning task or preliminary data requests.
-   *
    * Analyzes the given DTO type and generates a plan entry determining whether
-   * a transformer is needed. Returns exactly ONE plan entry for the given DTO.
+   * a transformer is needed. Returns exactly ONE plan entry.
    *
    * @param props Request containing either preliminary data request or complete
    *   plan
@@ -34,37 +26,16 @@ export namespace IAutoBeRealizeTransformerPlanApplication {
     /**
      * Think before you act.
      *
-     * Before requesting preliminary data or completing your plan, reflect on
-     * your current state and explain your reasoning:
-     *
-     * For preliminary requests:
-     *
-     * - What schemas (database or DTO) are missing that you need?
-     * - Why do you need them for planning?
-     * - Be brief - state the gap, don't list everything you have.
-     *
-     * For completion:
+     * For preliminary requests: what schemas (database or DTO) are missing?
      *
-     * - Is this DTO transformable or non-transformable?
-     * - What database table does it map to (if transformable)?
-     * - Why is it non-transformable (if applicable)?
-     *
-     * This reflection helps you avoid duplicate requests and premature
-     * completion.
+     * For completion: is this DTO transformable or non-transformable? What
+     * database table does it map to (if transformable)?
      */
     thinking: string;
 
     /**
-     * Type discriminator for the request.
-     *
-     * Determines which action to perform:
-     *
-     * - "getDatabaseSchemas": Retrieve database table schemas for DB structure
-     * - "getInterfaceSchemas": Retrieve DTO type definitions for API contracts
-     * - "complete": Generate final transformer plan
-     *
-     * The preliminary types are removed from the union after their respective
-     * data has been provided, physically preventing repeated calls.
+     * Action to perform. Exhausted preliminary types are removed from the
+     * union, physically preventing repeated calls.
      */
     request:
       | IComplete
@@ -74,76 +45,42 @@ export namespace IAutoBeRealizeTransformerPlanApplication {
   }
 
   /**
-   * Request to complete transformer planning.
-   *
-   * Generates a plan with exactly ONE entry for the given DTO, indicating
-   * whether it is transformable (has database schema name) or non-transformable
-   * (null).
+   * Generates exactly ONE plan entry indicating transformable (has DB schema
+   * name) or not (null).
    */
   export interface IComplete {
     /** Type discriminator for completion request. */
     type: "complete";
 
     /**
-     * Plan entry for the given DTO.
-     *
-     * Must contain exactly ONE entry with:
-     *
-     * - DTO type name matching the given DTO
-     * - Chain of thought explaining the analysis
-     * - Database schema name if transformable, or null if not
-     *
-     * Use databaseSchemaName to distinguish:
-     *
-     * - Non-null: Transformable DTO, transformer will be generated
-     * - Null: Non-transformable DTO, no transformer needed
+     * Exactly ONE entry. databaseSchemaName non-null = transformable, null = no
+     * transformer needed.
      */
     plans: IPlan[];
   }
 
-  /**
-   * Plan for a single DTO analysis result.
-   *
-   * Records the planning decision for one DTO from the operation response.
-   */
+  /** Planning decision for one DTO. */
   export interface IPlan {
     /**
-     * DTO type name being analyzed.
-     *
-     * The TypeScript interface type from the operation response.
-     *
-     * Example: "IShoppingSaleUnitStock", "IShoppingCategory", "IPage.IRequest"
+     * TypeScript interface type from the operation response (e.g.,
+     * "IShoppingSaleUnitStock").
      */
     dtoTypeName: string;
 
     /**
-     * Chain of thought for this DTO's planning decision.
-     *
-     * Explains the agent's reasoning:
+     * Reasoning for this DTO's planning decision.
      *
-     * - For transformable DTOs: Why a transformer is needed, which database table
-     *   it maps to
-     * - For non-transformable DTOs: Why no transformer is needed (request param,
-     *   pagination wrapper, business logic, etc.)
+     * Transformable: "Transforms shopping_sales to IShoppingSale with nested
+     * category and tags".
      *
-     * Example (transformable): "Transforms shopping_sales to IShoppingSale with
-     * nested category and tags"
-     *
-     * Example (non-transformable): "IPage.IRequest is pagination parameter, not
-     * database-backed"
+     * Non-transformable: "IPage.IRequest is pagination parameter, not
+     * DB-backed".
      */
     thinking: string;
 
     /**
-     * Database schema name if transformable, null if not.
-     *
-     * - **Non-null**: The database table name this DTO maps to. A transformer
-     *   will be generated for this DTO.
-     * - **Null**: This DTO is non-transformable (request param, pagination
-     *   wrapper, business logic type). No transformer will be generated.
-     *
-     * Example (transformable): "shopping_sales", "shopping_categories" Example
-     * (non-transformable): null
+     * Database table name if transformable (e.g., "shopping_sales"), null if
+     * non-transformable (request param, pagination wrapper, business logic).
      */
     databaseSchemaName: string | null;
   }

package/src/orchestrate/realize/structures/IAutoBeRealizeTransformerWriteApplication.ts

@@ -6,31 +6,13 @@ import {
 import { IAutoBePreliminaryGetDatabaseSchemas } from "../../common/structures/IAutoBePreliminaryGetDatabaseSchemas";
 
 /**
- * Function calling interface for generating DTO transformer functions.
- *
- * Guides the AI agent through creating reusable transformer modules that
- * convert database query results to API response DTOs (DB → API). Each
- * transformer includes type-safe conversion logic and Prisma select
- * specifications for efficient data loading.
- *
- * The generation follows a structured RAG workflow: preliminary context
- * gathering (database schemas only) → implementation planning → code generation
- * → review and refinement. All necessary DTO type information is obtained
- * transitively from the DTO type names provided in the plan
- * (AutoBeRealizeTransformerPlan).
- *
- * The planning phase has already filtered out incompatible DTO types (e.g.,
- * IPage*, *.IRequest, *.ICreate, *.IUpdate), so the write phase only receives
- * DTOs that require transformers.
+ * Generates transformer functions that convert Prisma query results to API
+ * response DTOs (DB → API) via plan/draft/revise workflow.
  */
 export interface IAutoBeRealizeTransformerWriteApplication {
   /**
    * Process transformer generation task or preliminary data requests.
    *
-   * Generates complete transformer module through three-phase workflow (plan →
-   * draft → revise). Ensures type safety, proper Prisma payload types, and
-   * correct DTO mapping.
-   *
    * @param props Request containing either preliminary data request or complete
    *   task
    */
@@ -42,80 +24,40 @@ export namespace IAutoBeRealizeTransformerWriteApplication {
     /**
      * Think before you act.
      *
-     * Before requesting preliminary data or completing your task, reflect on
-     * your current state and explain your reasoning:
-     *
-     * For preliminary requests:
-     *
-     * - What database schemas are missing that you need?
-     * - Why do you need them for transformer generation?
-     * - Be brief - state the gap, don't list everything you have.
-     *
-     * For completion:
-     *
-     * - What schemas did you acquire?
-     * - What transformer patterns did you implement?
-     * - Why is it sufficient to complete?
-     * - Summarize - don't enumerate every field mapping.
+     * For preliminary requests: what database schemas are missing and why?
      *
-     * Note: All necessary DTO type information is available transitively from
-     * the DTO type names in the plan. You only need to request database
-     * schemas.
+     * For completion: what schemas did you acquire, what patterns did you
+     * implement, and why is it sufficient? Summarize — don't enumerate every
+     * field.
      *
-     * This reflection helps you avoid duplicate requests and premature
-     * completion.
+     * Note: All DTO type information is available transitively from the plan's
+     * DTO type names. You only need to request database schemas.
      */
     thinking: string;
 
     /**
-     * Type discriminator for the request.
-     *
-     * Determines which action to perform:
-     *
-     * - "getDatabaseSchemas": Retrieve database table schemas for DB structure
-     * - "complete": Generate final transformer implementation
-     *
-     * All necessary DTO type information is obtained transitively from the DTO
-     * type names provided in the plan (AutoBeRealizeTransformerPlan). Each DTO
-     * type name allows the system to recursively fetch all referenced types,
-     * providing complete type information without requiring explicit schema
-     * requests.
-     *
-     * The preliminary types are removed from the union after their respective
-     * data has been provided, physically preventing repeated calls.
+     * Action to perform. Exhausted preliminary types are removed from the
+     * union, physically preventing repeated calls.
      */
     request: IComplete | IAutoBePreliminaryGetDatabaseSchemas;
   }
 
   /**
-   * Request to generate transformer module implementation.
-   *
-   * Executes three-phase generation to create complete transformer with:
-   *
-   * - `select()` function: Returns Prisma include/select specification
-   * - `transform()` function: Converts Prisma payload to DTO
-   *
-   * Follows plan → draft → revise pattern to ensure type safety and correct
-   * field mappings.
-   *
-   * Note: The database schema name is provided as input from the planning
-   * phase, so it doesn't need to be returned in the response.
+   * Generate transformer module (select + transform functions) via
+   * plan/draft/revise.
    */
   export interface IComplete {
     /** Type discriminator for completion request. */
     type: "complete";
 
     /**
-     * Transformer implementation plan and strategy.
+     * Transformer implementation plan. MUST contain four sections:
      *
-     * MUST contain thorough analysis with these four mandatory sections:
-     *
-     * 1. Database Schema Field Inventory - List ALL fields with exact names from
-     *    schema
-     * 2. DTO Property Inventory - List ALL properties with types
-     * 3. Field-by-Field Mapping Strategy - Explicit table for BOTH select() and
+     * 1. Database Schema Field Inventory — ALL fields with exact names from schema
+     * 2. DTO Property Inventory — ALL properties with types
+     * 3. Field-by-Field Mapping Strategy — explicit table for BOTH select() and
      *    transform()
-     * 4. Edge Cases and Special Handling - Type casts (Decimal, DateTime),
+     * 4. Edge Cases and Special Handling — type casts (Decimal, DateTime),
      *    nullables
      *
      * This forces you to READ the actual schema (not imagine it) and creates an
@@ -124,107 +66,49 @@ export namespace IAutoBeRealizeTransformerWriteApplication {
     plan: string;
 
     /**
-     * Database field-by-field selection mapping for the select() function.
-     *
-     * Documents which database fields/relations must be selected from the
-     * database to enable the transform() function. This ensures no required
-     * data is missing from the query.
+     * Database field-by-field selection mapping for select().
      *
-     * MUST include EVERY database field needed by transform() - no exceptions.
+     * MUST include EVERY database field needed by transform() — no exceptions.
      * Each mapping specifies:
      *
-     * - `member`: Exact database field/relation name (snake_case)
-     * - `kind`: Whether it's a scalar field, belongsTo, hasOne, or hasMany
-     *   relation
-     * - `nullable`: Whether the field/relation is nullable (true/false for
-     *   scalar/belongsTo, null for hasMany/hasOne)
-     * - `how`: Why this field is being selected (which DTO property needs it)
+     * - `member`: Exact Prisma field/relation name (snake_case) — read from the
+     *   Relation Mapping Table and member list, NOT from DTO property names
+     * - `kind`: scalar, belongsTo, hasOne, or hasMany
+     * - `nullable`: true/false for scalar/belongsTo, null for hasMany/hasOne
+     * - `how`: Which DTO property needs it
      *
      * The `kind` property forces explicit classification of each member BEFORE
-     * deciding what to select, preventing confusion between scalars and
-     * relations, and ensuring correct select syntax.
-     *
-     * The `nullable` property documents schema constraints that affect how
-     * transform() will handle the data, enabling proper null handling in
-     * transformations.
-     *
-     * Missing even a single required field will cause validation failure and
-     * trigger regeneration.
+     * deciding select syntax, preventing confusion between scalars and
+     * relations.
      *
-     * This structured approach:
-     *
-     * - Prevents missing field selections through systematic coverage
-     * - Forces explicit decision-making for each database field (kind + nullable
-     *
-     *   - How)
-     * - Ensures select() and transform() are perfectly aligned
-     * - Documents what data to load from database
-     * - Prevents confusion between scalar fields and relations
-     * - Documents nullability constraints for transform() planning
-     * - Enables validation before code generation
-     *
-     * **Common selection patterns by kind**:
-     *
-     * - **Scalar fields (nullable: true/false)**: For direct mapping or type
-     *   conversion
-     * - **Computation sources (nullable: true/false)**: Fields needed for
-     *   computed DTO properties
-     * - **Aggregations (nullable: false)**: _count, _sum, _avg for DTO statistics
-     * - **BelongsTo relations (nullable: true/false)**: For nested object
-     *   transformers
-     * - **HasMany relations (nullable: null)**: For array transformers
-     *
-     * The validator will cross-check this list against the database schema and
-     * DTO requirements to ensure complete coverage.
+     * Missing even a single required field will cause validation failure.
      */
     selectMappings: AutoBeRealizeTransformerSelectMapping[];
 
     /**
-     * DTO property-by-property transformation mapping for the transform()
-     * function.
-     *
-     * Documents how to transform database payload data into each DTO property.
-     * This ensures complete DTO coverage and correct transformation logic.
+     * DTO property-by-property transformation mapping for transform().
      *
-     * MUST include EVERY property from the DTO type definition - no exceptions.
+     * MUST include EVERY property from the DTO type definition — no exceptions.
      * Each mapping specifies:
      *
      * - `property`: Exact DTO property name (camelCase)
-     * - `how`: How to obtain this property value from Prisma payload
-     *
-     * Missing even a single property will cause validation failure and trigger
-     * regeneration.
-     *
-     * This structured approach:
-     *
-     * - Prevents property omissions through systematic coverage
-     * - Forces explicit decision-making for each property transformation
-     * - Documents transformation logic (direct mapping, type conversion,
-     *   computation, nested transformation)
-     * - Ensures select() and transform() are aligned
-     * - Enables validation before code generation
+     * - `how`: How to obtain from Prisma payload
      *
      * **Common transformation patterns**:
      *
-     * - **Direct mapping**: Simple field renaming (snake_case → camelCase)
-     * - **Type conversion**: Decimal → Number, DateTime → ISO string
-     * - **Nullable handling**: DateTime? → string | null
-     * - **Computed properties**: Calculate from multiple database fields
-     * - **Aggregation**: Use _count, _sum, _avg from database
-     * - **Nested objects**: Reuse neighbor transformers
-     * - **Arrays**: Map with ArrayUtil.asyncMap + neighbor transformer
+     * - Direct mapping: snake_case → camelCase
+     * - Type conversion: Decimal → Number, DateTime → ISO string
+     * - Nullable: DateTime? → string | null
+     * - Nested objects: Reuse neighbor transformers
+     * - Arrays: ArrayUtil.asyncMap + neighbor transformer
      *
-     * The validator will cross-check this list against the actual DTO type
-     * definition and reject incomplete mappings.
+     * Missing even a single property will cause validation failure.
      */
     transformMappings: AutoBeRealizeTransformerTransformMapping[];
 
     /**
-     * Initial transformer implementation draft.
-     *
-     * Complete implementation that strictly follows the plan's mapping table.
-     * EVERY field in the plan's Section 3 MUST appear in BOTH select() and
-     * transform(). Implement:
+     * Complete implementation following plan's mapping table. EVERY field from
+     * plan Section 3 MUST appear in BOTH select() and transform(). Implement:
      *
      * - Transform() first, select() second, Payload last (correct order)
      * - All field mappings from plan with correct transformations
@@ -233,45 +117,28 @@ export namespace IAutoBeRealizeTransformerWriteApplication {
      */
     draft: string;
 
-    /**
-     * Revision and finalization phase.
-     *
-     * Reviews the draft implementation and produces the final code with all
-     * improvements and corrections applied.
-     */
+    /** Reviews draft and produces final code. */
     revise: IReviseProps;
   }
 
   export interface IReviseProps {
     /**
-     * Critical review and improvement analysis.
-     *
-     * MUST systematically verify using four checklists:
+     * MUST systematically verify four checklists:
      *
-     * 1. Schema Fidelity - Cross-check EVERY field name against plan Section 1
-     *    inventory
-     * 2. Plan Adherence - Verify EVERY mapping from Section 3 in BOTH select() and
+     * 1. Schema Fidelity — cross-check EVERY field name against plan Section 1
+     * 2. Plan Adherence — verify EVERY mapping from Section 3 in BOTH select() and
      *    transform()
-     * 3. System Rules - Mandatory neighbor reuse, function order, select (not
-     *    include)
-     * 4. Type Safety - Type casts (Decimal→Number, DateTime→ISO), nullable
-     *    handling
+     * 3. System Rules — neighbor reuse, function order, select (not include)
+     * 4. Type Safety — Decimal→Number, DateTime→ISO, nullable handling
      *
-     * Identify specific issues with line numbers and provide clear reasoning.
-     * This catches hallucinated fields, missing transformations, and rule
-     * violations.
+     * Identify issues with line numbers. This catches hallucinated fields,
+     * missing transformations, and rule violations.
      */
     review: string;
 
     /**
-     * Final transformer code with all review improvements applied.
-     *
-     * Apply ALL fixes identified in the review to produce production-ready
-     * code. If review found issues, this MUST contain the corrected
-     * implementation.
-     *
-     * Return `null` ONLY if the draft is already perfect and review found zero
-     * issues.
+     * Final transformer code with all review improvements applied, or null if
+     * draft needs no changes.
      */
     final: string | null;
   }

package/src/orchestrate/realize/utils/generateTS2339Hints.ts

@@ -5,16 +5,20 @@ import { IAutoBeTypeScriptCompileResult } from "@autobe/interface";
  * errors.
  *
  * Parses TS2339 "Property 'X' does not exist on type 'Y'" diagnostics,
- * deduplicates by (property, type) pair, and returns a short explanation when Y
- * appears to be a Prisma model type (snake_case naming).
+ * deduplicates by property name, and returns a short explanation.
  *
- * Returns empty string if no TS2339 diagnostics on Prisma-like types are found.
+ * Handles both simple type names (e.g., `shopping_sales`) and inline Prisma
+ * GetPayload types (e.g., `{ id: string; body: string; ... }`).
+ *
+ * Returns empty string if no TS2339 diagnostics are found.
  */
 export function generateTS2339Hints(
   diagnostics: IAutoBeTypeScriptCompileResult.IDiagnostic[],
 ): string {
-  const TS2339_PATTERN = /^Property '(\w+)' does not exist on type '(\w+)'\.?$/;
-  const PRISMA_MODEL_PATTERN = /^[a-z][a-z0-9]*(_[a-z][a-z0-9]*)+$/;
+  // Match both simple types and inline object types
+  const TS2339_SIMPLE = /^Property '(\w+)' does not exist on type '(\w+)'\.?$/;
+  const TS2339_INLINE =
+    /^Property '(\w+)' does not exist on type '\{[^}]*\}'\.?$/;
 
   const seen = new Set<string>();
   const hints: Array<{ property: string; modelType: string }> = [];
@@ -22,17 +26,28 @@ export function generateTS2339Hints(
   for (const diag of diagnostics) {
     if (Number(diag.code) !== 2339) continue;
 
-    const match = diag.messageText.match(TS2339_PATTERN);
-    if (match === null) continue;
-
-    const [, property, typeName] = match;
-    if (!PRISMA_MODEL_PATTERN.test(typeName)) continue;
+    // Try simple type match first
+    const simpleMatch = diag.messageText.match(TS2339_SIMPLE);
+    if (simpleMatch !== null) {
+      const [, property, typeName] = simpleMatch;
+      const key = `${property}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        hints.push({ property: property!, modelType: typeName! });
+      }
+      continue;
+    }
 
-    const key = `${property}::${typeName}`;
-    if (seen.has(key)) continue;
-    seen.add(key);
-
-    hints.push({ property, modelType: typeName });
+    // Try inline object type match (Prisma GetPayload output)
+    const inlineMatch = diag.messageText.match(TS2339_INLINE);
+    if (inlineMatch !== null) {
+      const [, property] = inlineMatch;
+      const key = `${property}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        hints.push({ property: property!, modelType: "(Prisma Payload)" });
+      }
+    }
   }
 
   if (hints.length === 0) return "";
@@ -44,11 +59,16 @@ export function generateTS2339Hints(
   return [
     "## TS2339 Relation Field Hints",
     "",
-    "These TS2339 errors are caused by accessing **Prisma relation fields** not available on the base model type.",
-    "- For transformers: add the missing relation to `select()` using `NeighborTransformer.select()`",
-    "- For collectors: use the **relation property name** (left side of schema definition) with `{ connect }` syntax",
+    "These TS2339 errors are caused by accessing fields not available on the Prisma Payload type.",
+    "This usually means the field is MISSING from your `select()` object.",
+    "",
+    "**Fix**: For each property below, add it to `select()`:",
+    "- Scalar field → `fieldName: true`",
+    "- Relation (has neighbor transformer) → `relation: NeighborTransformer.select()`",
+    "- Relation (no transformer) → `relation: { select: { ... } }`",
+    "- Aggregate count → `_count: { select: { relation: true } }`",
     "",
-    "Affected:",
+    "Affected properties:",
     lines,
   ].join("\n");
 }