TypeScript Healer - Proper Architecture

System Overview


                    Developer Workflow                        
  buildkit heal typescript [path]                            

                            
                            

              agent-buildkit CLI (Entry Point)                
  $LLM_ROOT/agent-buildkit/src/cli/heal.ts   
   buildkit heal typescript                                  
   buildkit heal scan --all                                  
   buildkit heal dashboard                                   

                            
                            

           agent-brain API (Core Service)                     
  $LLM_ROOT/common_npm/agent-brain/src/api/  
   POST /api/v1/heal/typescript                             
   GET /api/v1/heal/health                                  
   GET /api/v1/heal/patterns                                
  OpenAPI: openapi/typescript-healer.yaml                    
  Zod: src/types/typescript-healer.schemas.ts                

                            
                
                                       
  
  Qdrant Vector DB            PostgreSQL (Prisma)     
  Collection:                 Model:                  
  ts_error_patterns           TypeScriptError         
   Error embeddings           Error history         
   Fix strategies             Fix tracking          
   Cross-project learn        Project health        
  
                            
                            

         workflow-engine (Orchestration)                      
  $LLM_ROOT/common_npm/workflow-engine/      
  workflows/typescript-healing.json                          
   Daily scan all projects                                  
   Auto-heal critical errors                                
   Create MRs for fixes                                     
   Notify dashboard                                         

                            
                            

         compliance-engine (Enforcement)                      
  $LLM_ROOT/common_npm/compliance-engine/    
  rules/typescript.yml                                       
   Block merges with TS errors                              
   Enforce error thresholds                                 
   Track compliance metrics                                 

                            
                            

         gitlab_components (CI/CD)                           
  $LLM_ROOT/gitlab_components/               
  .gitlab/ci/typescript-healer.yml                          
   Reusable CI template                                     
   Pre-commit hook installer                                
   Pipeline guard job                                       

                            
                            

              All 16 Projects (Consumers)                     
  Agent Infrastructure (9):                                   
   agent-brain, agent-chat, agent-docker, agent-mesh        
   agent-protocol, agent-router, agent-studio, agent-tracer 
   agent_tailscale                                          
                                                             
  Platform Services (7):                                     
   agentic-flows, compliance-engine, foundation-bridge      
   kiro-supercharger, rfp-automation, studio-ui             
   workflow-engine

Component Responsibilities

1. agent-buildkit (CLI Interface)

Path: $LLM_ROOT/agent-buildkit/src/cli/commands/heal.ts

import { z } from 'zod';
import { agentBrainClient } from '@bluefly/agent-brain';

export const healCommand = {
  command: 'heal <subcommand>',
  subcommands: {
    typescript: {
      command: 'typescript [path]',
      handler: async (path: string) => {
        const result = await agentBrainClient.heal.typescript({ projectPath: path });
        console.log(result);
      }
    },
    scan: {
      command: 'scan --all-projects',
      handler: async () => {
        const projects = getAllProjects();
        for (const project of projects) {
          await agentBrainClient.heal.typescript({ projectPath: project });
        }
      }
    },
    dashboard: {
      command: 'dashboard',
      handler: async () => {
        const health = await agentBrainClient.heal.health();
        renderDashboard(health);
      }
    }
  }
};

2. agent-brain (Core API)

Path: $LLM_ROOT/common_npm/agent-brain/src/api/typescript-healer.ts

OpenAPI Spec: openapi/typescript-healer.yaml

openapi: 3.1.0
paths:
  /api/v1/heal/typescript:
    post:
      operationId: healTypescript
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HealRequest'
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealingReport'

components:
  schemas:
    HealRequest:
      type: object
      required: [projectPath]
      properties:
        projectPath: { type: string }
        autoFix: { type: boolean, default: true }
    
    HealingReport:
      type: object
      properties:
        totalErrors: { type: integer }
        patterns: { type: array, items: { $ref: '#/components/schemas/ErrorPattern' }}
        appliedFixes: { type: array, items: { type: string }}

Zod Schemas: src/types/typescript-healer.schemas.ts

import { z } from 'zod';

export const HealRequestSchema = z.object({
  projectPath: z.string(),
  autoFix: z.boolean().default(true)
});

export const ErrorPatternSchema = z.object({
  code: z.string(),
  count: z.number(),
  samples: z.array(z.string()),
  fix: z.string(),
  autoFixable: z.boolean()
});

export const HealingReportSchema = z.object({
  totalErrors: z.number(),
  patterns: z.array(ErrorPatternSchema),
  appliedFixes: z.array(z.string())
});

3. llm-platform_model (Data Model)

Path: $LLM_ROOT/models/llm-platform_model/schema.prisma

model TypeScriptError {
  id          String   @id @default(cuid())
  code        String   // TS2304, TS2307, etc.
  message     String
  project     String
  filePath    String
  count       Int
  fixed       Boolean  @default(false)
  fixStrategy String?
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
  
  @@index([project, code])
  @@index([fixed])
}

model HealingSession {
  id            String   @id @default(cuid())
  project       String
  totalErrors   Int
  fixedErrors   Int
  appliedFixes  String[] // JSON array
  duration      Int      // milliseconds
  createdAt     DateTime @default(now())
  
  @@index([project])
  @@index([createdAt])
}

4. gitlab_components (CI/CD Template)

Path: $LLM_ROOT/gitlab_components/.gitlab/ci/typescript-healer.yml

.typescript_healer:
  stage: validate
  image: node:20-alpine
  variables:
    AGENT_BRAIN_URL: ${AGENT_BRAIN_URL}
    AGENT_BRAIN_TOKEN: ${AGENT_BRAIN_TOKEN}
  before_script:
    - npm install -g @bluefly/agent-buildkit
  script:
    - buildkit heal typescript ${CI_PROJECT_DIR}
  artifacts:
    when: always
    reports:
      typescript-health: .ts-healer-report.json
    expire_in: 30 days
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      changes:
        - "**/*.ts"
        - "**/*.tsx"
        - "tsconfig.json"

.typescript_healer_hook:
  stage: setup
  script:
    - buildkit install-hooks --typescript-healer
  only:
    - branches

5. workflow-engine (Automation)

Path: $LLM_ROOT/common_npm/workflow-engine/workflows/typescript-healing.json

{
  "name": "typescript-healing",
  "version": "0.4.9",
  "trigger": {
    "type": "schedule",
    "cron": "0 2 * * *"
  },
  "steps": [
    {
      "id": "scan",
      "action": "agent-brain.heal.scanAllProjects",
      "output": "scanResults"
    },
    {
      "id": "heal-critical",
      "action": "agent-brain.heal.healProjects",
      "input": {
        "projects": "{{ scanResults.critical }}"
      },
      "output": "healResults"
    },
    {
      "id": "create-mrs",
      "action": "gitlab.createMergeRequests",
      "input": {
        "fixes": "{{ healResults.appliedFixes }}"
      }
    },
    {
      "id": "notify",
      "action": "notifications.send",
      "input": {
        "channel": "typescript-health",
        "message": "Daily healing complete: {{ healResults.summary }}"
      }
    }
  ]
}

6. compliance-engine (Enforcement)

Path: $LLM_ROOT/common_npm/compliance-engine/rules/typescript.yml

rules:
  - id: typescript-errors-blocked
    name: Block merges with TypeScript errors
    severity: critical
    check:
      type: typescript
      condition: errorCount == 0
    action: block-merge
    message: "TypeScript errors detected. Run 'buildkit heal typescript' to fix."
  
  - id: typescript-error-threshold
    name: Enforce error threshold
    severity: high
    check:
      type: typescript
      condition: errorCount < 100
    action: warn
    message: "Project has {{ errorCount }} TypeScript errors. Target: <100"
  
  - id: typescript-healing-required
    name: Require healing for critical projects
    severity: medium
    check:
      type: typescript
      condition: lastHealedAt < 7 days ago
    action: notify
    message: "Project hasn't been healed in 7 days. Run healing workflow."

Deployment Strategy

Phase 1: Core Infrastructure

Add API to agent-brain with OpenAPI + Zod
Add CLI commands to agent-buildkit
Add Prisma schema to llm-platform_model
Create gitlab_components template

Phase 2: Automation

Create workflow-engine workflow
Add compliance-engine rules
Deploy Qdrant collection

Phase 3: Rollout (All 16 Projects)

# For each project
cd $LLM_ROOT/common_npm/{project}

# 1. Include gitlab_components template
echo "include:
  - component: gitlab.com/llm/gitlab_components/.gitlab/ci/typescript-healer.yml@main" >> .gitlab-ci.yml

# 2. Install pre-commit hook
buildkit install-hooks --typescript-healer

# 3. Run initial healing
buildkit heal typescript .

# 4. Commit and push
git add .
git commit -m "feat: integrate TypeScript healer"
git push

Benefits of Proper Architecture

DRY: Single API in agent-brain, consumed everywhere OpenAPI: All endpoints documented and typed Zod: Validation centralized and reusable CRUD: Standard REST operations Tracked: All errors stored in PostgreSQL Learned: Patterns stored in Qdrant Automated: workflow-engine runs daily Enforced: compliance-engine blocks bad code Reusable: gitlab_components template for all projects Accessible: agent-buildkit CLI for developers Scalable: Works across all 16 projects + future ones

Migration from POC

Move standalone scripts to agent-brain API
Add OpenAPI spec and Zod schemas
Create Prisma migrations
Build agent-buildkit CLI commands
Create gitlab_components template
Deploy to all projects
Enable workflow-engine automation
Enable compliance-engine enforcement