@auto-engineer/server-implementer

AI-powered code implementation that completes TODO-marked TypeScript files in event-driven servers.

Purpose

Without @auto-engineer/server-implementer, you would have to manually implement scaffolded TypeScript code in CQRS/event-sourced servers, run tests, interpret errors, and iterate on fixes by hand.

This package automates that loop. It scans a server project for files containing TODO markers or IMPLEMENTATION INSTRUCTIONS, generates implementations using an LLM, validates the output with TypeScript type-checking and Vitest, and retries with error feedback until tests pass -- up to 5 attempts per file.

Installation

pnpm add @auto-engineer/server-implementer

Quick Start

1. Register the handlers

import { COMMANDS } from '@auto-engineer/server-implementer';
import { createMessageBus } from '@auto-engineer/message-bus';

const bus = createMessageBus();
COMMANDS.forEach(cmd => bus.registerCommand(cmd));

2. Implement an entire server

const result = await bus.dispatch({
  type: 'ImplementServer',
  data: {
    serverDirectory: './server',
  },
  requestId: 'req-123',
});

if (result.type === 'ServerImplemented') {
  console.log('Done:', result.data.scenesImplemented, 'scenes processed');
}

The command walks all scene directories under src/domain/narratives/ and implements every slice it finds.

3. Implement a single slice

const result = await bus.dispatch({
  type: 'ImplementMoment',
  data: {
    momentPath: './server/src/domain/narratives/order/place-order',
  },
  requestId: 'req-456',
});

if (result.type === 'MomentImplemented') {
  console.log('Files implemented:', result.data.filesImplemented);
}

How-to Guides

Run via CLI

auto implement:server --server-directory=./server
auto implement:slice --moment-path=./server/src/domain/narratives/order/place-order

Run programmatically (without the bus)

import { handleImplementMomentCommand } from '@auto-engineer/server-implementer';

const result = await handleImplementMomentCommand({
  type: 'ImplementMoment',
  data: {
    momentPath: './server/src/domain/narratives/order/place-order',
    aiOptions: { maxTokens: 4000 },
  },
  requestId: 'req-789',
});

Retry with previous errors

When an implementation attempt fails, pass the error output back as context so the next attempt can learn from it:

const retryResult = await handleImplementMomentCommand({
  type: 'ImplementMoment',
  data: {
    momentPath: './server/src/domain/narratives/order/place-order',
    context: {
      previousOutputs: 'TypeError: Property "status" is missing...',
      attemptNumber: 2,
    },
  },
  requestId: 'req-790',
});

Handle errors

if (result.type === 'ServerImplementationFailed') {
  console.error(result.data.error);
}

if (result.type === 'MomentImplementationFailed') {
  console.error(result.data.error);
}

Enable debug logging

DEBUG=auto:server-implementer:* auto implement:server --server-directory=./server

Namespaces available:

| Namespace | What it logs | |-----------|-------------| | auto:server-implementer:command | Top-level command lifecycle | | auto:server-implementer:command:handler | Path resolution and validation | | auto:server-implementer:command:process | Scene runner progress | | auto:server-implementer:command:result | Final outcome | | auto:server-implementer:slice | Single-slice command lifecycle | | auto:server-implementer:slice:handler | Slice path resolution | | auto:server-implementer:slice:process | Per-file AI generation and retries | | auto:server-implementer:slice:result | Slice outcome | | auto:server-implementer:scenes | Scene directory discovery |

API Reference

Exports

import {
  COMMANDS,
  implementServerHandler,
  implementMomentHandler,
  handleImplementMomentCommand,
} from '@auto-engineer/server-implementer';

import type {
  ImplementServerCommand,
  ImplementServerEvents,
  ServerImplementedEvent,
  ServerImplementationFailedEvent,
  ImplementMomentCommand,
  ImplementMomentEvents,
  MomentImplementedEvent,
  MomentImplementationFailedEvent,
} from '@auto-engineer/server-implementer';

Commands

| Command | CLI Alias | Description | |---------|-----------|-------------| | ImplementServer | implement:server | Implement all scenes and slices in a server project | | ImplementMoment | implement:slice | Implement a single slice directory |

ImplementServerCommand

type ImplementServerCommand = Command<
  'ImplementServer',
  {
    serverDirectory: string;
  }
>;

Events:

• ServerImplemented -- { serverDirectory: string; scenesImplemented: number }
• ServerImplementationFailed -- { serverDirectory: string; error: string }

ImplementMomentCommand

type ImplementMomentCommand = Command<
  'ImplementMoment',
  {
    momentPath: string;
    context?: {
      previousOutputs?: string;
      attemptNumber?: number;
    };
    aiOptions?: {
      maxTokens?: number;
    };
  }
>;

Events:

• MomentImplemented -- { momentPath: string; filesImplemented: string[] }
• MomentImplementationFailed -- { momentPath: string; error: string }

Architecture

src/
├── index.ts                  # COMMANDS array, re-exports
├── commands/
│   ├── implement-server.ts   # ImplementServer command handler
│   └── implement-slice.ts    # ImplementMoment command handler
├── agent/
│   ├── runFlows.ts           # Discovers and iterates scene directories
│   ├── runAllSlices.ts       # Iterates moment directories within a scene
│   ├── runSlice.ts           # Per-slice: AI generate, test, typecheck, retry
│   └── runTests.ts           # Vitest runner with JSON report parsing
├── prompts/
│   └── systemPrompt.ts       # System prompt for AI code generation
└── utils/
    ├── buildContextSections.ts          # Formats context files into prompt sections
    ├── detectImportedTypeShadowing.ts   # Detects re-declared imported types
    ├── detectTypeAssertions.ts          # Detects forbidden `as` casts
    ├── extractCodeBlock.ts              # Strips markdown fences from AI output
    ├── findFilesToImplement.ts          # Filters + priority-sorts TODO-marked files
    ├── loadContextFiles.ts              # Loads all .ts files in a slice directory
    └── loadSharedContext.ts             # Loads shared domain types from ../../../shared

Implementation flow

flowchart TB
    A[ImplementServer command] --> B[Discover scenes in src/domain/narratives/]
    B --> C[For each scene: discover slices]
    C --> D[For each slice: load context files]
    D --> E[Find files with TODO markers]
    E --> F[Generate implementation via AI]
    F --> G[Write generated code to disk]
    G --> H[Run Vitest + tsc --noEmit]
    H --> I{Pass?}
    I -->|Yes| J[Done]
    I -->|No| K{Retries left?}
    K -->|Yes| L[Build retry prompt with errors]
    L --> F
    K -->|No| M[Report remaining failures]

Validation checks

Each implementation pass runs three checks before accepting the output:

1. Vitest -- runs spec files in the slice, parses JSON report for failures
2. TypeScript -- tsc --noEmit filtered to errors in the slice directory
3. Static analysis -- detects imported-type shadowing and forbidden as type assertions

Files that fail typecheck are retried up to 5 times. Files that fail tests are retried separately, also up to 5 times. If a test fix introduces a type error, a nested typecheck retry loop runs (max depth 2).

Implementation priority

When multiple files need implementation, they are processed in this order: state.ts, events.ts, commands.ts, evolve.ts, decide.ts, then alphabetically.

Implementation markers

Files are identified for AI implementation by the presence of any of:

• // @auto-implement comment
• TODO: comment
• IMPLEMENTATION INSTRUCTIONS text

Dependencies

| Package | Usage | |---------|-------| | @auto-engineer/model-factory | Creates the AI model instance from environment config | | @auto-engineer/message-bus | Command/event handler infrastructure | | ai (Vercel AI SDK) | generateText for LLM calls | | fast-glob | File and directory discovery | | debug | Namespaced debug logging |