Developer Guide

LDFLAGS_AUTOMERGENT := -s -w \
  -X 'github.com/iSundram/Automergent/internal/version.Version=$(VERSION)' \
  -X 'github.com/iSundram/Automergent/internal/version.Commit=$(COMMIT)' \
  -X 'github.com/iSundram/Automergent/internal/version.BuildDate=$(BUILD_DATE)'

name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: "1.25"
      - run: CGO_ENABLED=1 go test ./...
      - run: go vet ./...
      - run: golangci-lint run ./...

name: Release
on:
  push:
    tags: ["v*"]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-go@v5
        with:
          go-version: "1.25"
      - uses: goreleaser/goreleaser-action@v6
        with:
          version: latest
          args: release --clean -f dist/goreleaser-automergent.yaml
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

CGO_ENABLED=1 go test ./...

# Run tests in a specific package
CGO_ENABLED=1 go test ./internal/tools/...

# Run tests matching a pattern
CGO_ENABLED=1 go test -run TestTool ./internal/tools/

# Run tests with verbose output
CGO_ENABLED=1 go test -v ./internal/agent/...

# Run tests with race detection
CGO_ENABLED=1 go test -race ./...

golangci-lint run ./...

type Tool interface {
    Name() string
    Description() string
    Schema() map[string]any
    Execute(ctx context.Context, args map[string]any) (Result, error)
    RequiresConfirmation(mode string) bool
    IsConcurrencySafe(args map[string]any) bool
    IsReadOnly(args map[string]any) bool
    IsDestructive(args map[string]any) bool
    EstimatedCost() ToolCost
}

type MyTool struct {
    tools.BaseTool
}

func (t *MyTool) Name() string        { return "my_tool" }
func (t *MyTool) Description() string  { return "Does something useful" }
func (t *MyTool) Schema() map[string]any {
    return map[string]any{
        "type":       "object",
        "properties": map[string]any{...},
        "required":   []string{...},
    }
}
func (t *MyTool) Execute(ctx context.Context, args map[string]any) (tools.Result, error) {
    // implementation
}

type Provider interface {
    Name() string
    Complete(ctx context.Context, req CompletionRequest) (CompletionResponse, error)
    Models(ctx context.Context) ([]Model, error)
    TokenCount(messages []Message) (int, error)
    ContextLimit() int
}

type RetryObserver interface {
    SetRetryObserver(func(RetryInfo))
}

package mytool

import (
    "context"

    "github.com/iSundram/Automergent/internal/tools"
)

// MyTool implements tools.Tool
type MyTool struct {
    tools.BaseTool
}

func (t *MyTool) Name() string { return "my_tool" }

func (t *MyTool) Description() string {
    return "Description shown to the AI model"
}

func (t *MyTool) Schema() map[string]any {
    return map[string]any{
        "type": "object",
        "properties": map[string]any{
            "input": map[string]any{
                "type":        "string",
                "description": "The input parameter",
            },
        },
        "required": []string{"input"},
    }
}

func (t *MyTool) Execute(ctx context.Context, args map[string]any) (tools.Result, error) {
    input, _ := args["input"].(string)

    // Tool logic here

    return tools.Result{
        Content: "Result text",
        Summary: "Short summary for UI",
    }, nil
}

import (
    toolsMyTool "github.com/iSundram/Automergent/internal/tools/mytool"
)

// In the tool registry setup:
reg.Register(&toolsMytool.MyTool{})

func TestMyTool(t *testing.T) {
    tool := &MyTool{}

    if tool.Name() != "my_tool" {
        t.Errorf("expected name my_tool, got %s", tool.Name())
    }

    result, err := tool.Execute(context.Background(), map[string]any{
        "input": "test",
    })

    if err != nil {
        t.Fatal(err)
    }
    if result.IsError {
        t.Error("expected success")
    }
}

package myprovider

import (
    "context"
    "github.com/iSundram/Automergent/internal/ai"
)

type Provider struct {
    config ai.ProviderConfig
}

func New(cfg ai.ProviderConfig) *Provider {
    return &Provider{config: cfg}
}

func (p *Provider) Name() string { return "myprovider" }

func (p *Provider) Complete(
    ctx context.Context,
    req ai.CompletionRequest,
) (ai.CompletionResponse, error) {
    // Call your provider's API here
    // Return a CompletionResponse with streaming support
}

func (p *Provider) Models(ctx context.Context) ([]ai.Model, error) {
    // Return available models
}

func (p *Provider) TokenCount(messages []ai.Message) (int, error) {
    // Estimate token count
}

func (p *Provider) ContextLimit() int {
    return 128000 // context window size
}

// In the catalog entry:
"myprovider": {
    Name:        "myprovider",
    DisplayName: "My Provider",
    EnvKey:      "MYPROVIDER_API_KEY",
    Models:      []string{"model-1", "model-2"},
    DefaultModel: "model-1",
}

case "myprovider":
    provider = myprovider.New(aiCfg)

provider: custom
model: model-1

providers:
  custom:
    apiKey: "your-api-key-here"
    baseUrl: "https://your-endpoint/v1"
    defaultModel: "model-1"

package themes

import "charm.land/lipgloss/v2"

func MyTheme() *Theme {
    return &Theme{
        Name:          "mytheme",
        Background:    lipgloss.Color("#1a1b26"),
        Surface:       lipgloss.Color("#24283b"),
        Overlay:       lipgloss.Color("#414868"),
        Text:          lipgloss.Color("#c0caf5"),
        Subtext:       lipgloss.Color("#a9b1d6"),
        Muted:         lipgloss.Color("#565f89"),
        Accent:        lipgloss.Color("#7aa2f7"),
        AccentAlt:     lipgloss.Color("#bb9af7"),
        Green:         lipgloss.Color("#9ece6a"),
        Red:           lipgloss.Color("#f7768e"),
        Yellow:        lipgloss.Color("#e0af68"),
        Blue:          lipgloss.Color("#7aa2f7"),
        Magenta:       lipgloss.Color("#bb9af7"),
        Cyan:          lipgloss.Color("#7dcfff"),
        BorderNormal:  lipgloss.Color("#414868"),
        BorderFocused: lipgloss.Color("#7aa2f7"),
    }
}

func NewThemeEngine() *ThemeEngine {
    te := &ThemeEngine{...}

    // Register themes
    te.RegisterTheme(Catppuccin())
    te.RegisterTheme(Dracula())
    te.RegisterTheme(MyTheme())  // ← add here
    // ...
}

type DebugProvider struct {
    provider ai.Provider
    logger   *Logger
}

func (d *DebugProvider) Complete(
    ctx context.Context, req ai.CompletionRequest,
) (ai.CompletionResponse, error) {
    start := time.Now()
    d.logger.LogRequest(ctx, d.provider.Name(), req)

    resp, err := d.provider.Complete(ctx, req)

    if err != nil {
        d.logger.LogError(ctx, d.provider.Name(), err, req)
        return nil, err
    }

    d.logger.LogResponse(ctx, d.provider.Name(), resp, time.Since(start))
    return resp, nil
}

debug:
  enabled: true
  output_dir: "./debug-logs"

export AUTOMERGENT_DEBUG_ENABLED=true

// Provider resolution chain:
provider := googleProvider.New(aiCfg)    // base provider
provider = cache.NewCachingProvider(...)  // optional caching wrapper
provider = debug.NewDebugProvider(...)    // debug wrapper (outermost)

mcp:
  servers:
    my-server:
      command: "npx"
      args: ["-y", "@my/mcp-server"]
      env:
        API_KEY: "xxx"