tatara-claude-code-wrapper Implementation Plan¶

package main

import (
    "fmt"
    "os"
    "os/exec"
    "time"

    "github.com/creack/pty"
)

func main() {
    cmd := exec.Command("claude", "--permission-mode", "bypassPermissions")
    cmd.Env = append(os.Environ(),
        "HOME=/tmp/ccw-spike", "TERM=xterm-256color")
    cmd.Dir = "/tmp/ccw-spike"
    ptmx, err := pty.Start(cmd)
    if err != nil {
        panic(err)
    }
    defer func() { _ = ptmx.Close() }()
    _ = pty.Setsize(ptmx, &pty.Winsize{Rows: 40, Cols: 120})
    go func() { _, _ = io.Copy(os.Stdout, ptmx) }() // observe TUI

    time.Sleep(8 * time.Second) // boot
    msg := "Reply with exactly the word PONG and nothing else."
    // bracketed paste so newlines never submit early, then CR to submit
    _, _ = ptmx.Write([]byte("\x1b[200~" + msg + "\x1b[201~"))
    time.Sleep(200 * time.Millisecond)
    _, _ = ptmx.Write([]byte("\r"))

    for i := 0; i < 120; i++ {
        if _, err := os.Stat("/tmp/ccw-spike/.cap/last_hook_payload.json"); err == nil {
            b, _ := os.ReadFile("/tmp/ccw-spike/.cap/last_hook_payload.json")
            fmt.Printf("\n=== HOOK PAYLOAD ===\n%s\n", b)
            return
        }
        time.Sleep(time.Second)
    }
    fmt.Println("TIMEOUT: no hook fired")
}

package turn_test

import (
    "encoding/json"
    "testing"
    "time"

    "github.com/stretchr/testify/require"
    "github.com/szymonrychu/tatara-claude-code-wrapper/internal/turn"
)

func TestStore_CreateCompleteGet(t *testing.T) {
    s := turn.NewStore()
    t0 := time.Unix(1000, 0)
    rec := s.Create("turn-1", "hello", "https://cb.example/x", t0)
    require.Equal(t, turn.Running, rec.State)

    got, ok := s.Get("turn-1")
    require.True(t, ok)
    require.Equal(t, turn.Running, got.State)
    require.Equal(t, "https://cb.example/x", got.CallbackURL)

    t1 := time.Unix(1005, 0)
    require.NoError(t, s.Complete("turn-1", "PONG",
        json.RawMessage(`{"status":"success"}`), json.RawMessage(`{"output_tokens":3}`), "end_turn", t1))

    got, _ = s.Get("turn-1")
    require.Equal(t, turn.Complete, got.State)
    require.Equal(t, "PONG", got.FinalText)
    require.Equal(t, "end_turn", got.StopReason)
    require.NotNil(t, got.CompletedAt)

    require.ErrorIs(t, s.Complete("missing", "", nil, nil, "", t1), turn.ErrNotFound)
}

func TestStore_ListOrderedAndFail(t *testing.T) {
    s := turn.NewStore()
    s.Create("a", "1", "", time.Unix(1, 0))
    s.Create("b", "2", "", time.Unix(2, 0))
    require.NoError(t, s.Fail("a", "boom", time.Unix(3, 0)))

    list := s.List()
    require.Len(t, list, 2)
    require.Equal(t, "a", list[0].ID)
    require.Equal(t, turn.Failed, list[0].State)
    require.Equal(t, "b", list[1].ID)
}

// Package turn holds per-turn records and a thread-safe store.
package turn

import (
    "encoding/json"
    "time"
)

type State string

const (
    Running  State = "running"
    Complete State = "complete"
    Failed   State = "failed"
)

// Record is one user turn and its eventual result.
type Record struct {
    ID          string          `json:"turnId"`
    State       State           `json:"state"`
    Text        string          `json:"-"`
    CallbackURL string          `json:"-"`
    FinalText   string          `json:"finalText,omitempty"`
    ResultJSON  json.RawMessage `json:"resultJson,omitempty"`
    Usage       json.RawMessage `json:"usage,omitempty"`
    StopReason  string          `json:"stopReason,omitempty"`
    Error       string          `json:"error,omitempty"`
    StartedAt   time.Time       `json:"startedAt"`
    CompletedAt *time.Time      `json:"completedAt,omitempty"`
}

// Summary is the compact form returned by List.
type Summary struct {
    ID          string     `json:"turnId"`
    State       State      `json:"state"`
    StartedAt   time.Time  `json:"startedAt"`
    CompletedAt *time.Time `json:"completedAt,omitempty"`
}

package turn

import (
    "encoding/json"
    "errors"
    "sync"
    "time"
)

var ErrNotFound = errors.New("turn: not found")

type Store struct {
    mu    sync.RWMutex
    byID  map[string]*Record
    order []string
}

func NewStore() *Store { return &Store{byID: map[string]*Record{}} }

func (s *Store) Create(id, text, callbackURL string, now time.Time) *Record {
    s.mu.Lock()
    defer s.mu.Unlock()
    rec := &Record{ID: id, State: Running, Text: text, CallbackURL: callbackURL, StartedAt: now}
    s.byID[id] = rec
    s.order = append(s.order, id)
    return rec
}

func (s *Store) Get(id string) (*Record, bool) {
    s.mu.RLock()
    defer s.mu.RUnlock()
    rec, ok := s.byID[id]
    if !ok {
        return nil, false
    }
    cp := *rec
    return &cp, true
}

func (s *Store) List() []Summary {
    s.mu.RLock()
    defer s.mu.RUnlock()
    out := make([]Summary, 0, len(s.order))
    for _, id := range s.order {
        r := s.byID[id]
        out = append(out, Summary{ID: r.ID, State: r.State, StartedAt: r.StartedAt, CompletedAt: r.CompletedAt})
    }
    return out
}

func (s *Store) Complete(id, finalText string, resultJSON, usage json.RawMessage, stopReason string, now time.Time) error {
    s.mu.Lock()
    defer s.mu.Unlock()
    r, ok := s.byID[id]
    if !ok {
        return ErrNotFound
    }
    r.State, r.FinalText, r.ResultJSON, r.Usage, r.StopReason = Complete, finalText, resultJSON, usage, stopReason
    r.CompletedAt = &now
    return nil
}

func (s *Store) Fail(id, msg string, now time.Time) error {
    s.mu.Lock()
    defer s.mu.Unlock()
    r, ok := s.byID[id]
    if !ok {
        return ErrNotFound
    }
    r.State, r.Error, r.CompletedAt = Failed, msg, &now
    return nil
}

package metrics_test

import (
    "testing"

    "github.com/prometheus/client_golang/prometheus"
    "github.com/stretchr/testify/require"
    "github.com/szymonrychu/tatara-claude-code-wrapper/internal/metrics"
)

func TestNew_RegistersAllCollectors(t *testing.T) {
    reg := prometheus.NewRegistry()
    m := metrics.New(reg)
    require.NotNil(t, m)

    m.TurnsTotal.WithLabelValues("complete").Inc()
    m.TurnDuration.Observe(1.2)
    m.TurnInFlight.Set(1)
    m.ClaudeRestarts.Inc()
    m.WebhookDelivery.WithLabelValues("ok").Inc()
    m.HookReceived.Inc()

    mfs, err := reg.Gather()
    require.NoError(t, err)
    names := map[string]bool{}
    for _, mf := range mfs {
        names[mf.GetName()] = true
    }
    for _, want := range []string{
        "ccw_turns_total", "ccw_turn_duration_seconds", "ccw_turn_in_flight",
        "ccw_claude_restarts_total", "ccw_webhook_delivery_total", "ccw_hook_received_total",
    } {
        require.True(t, names[want], "missing %s", want)
    }
}

// Package metrics holds the wrapper's prometheus collectors.
package metrics

import "github.com/prometheus/client_golang/prometheus"

type Metrics struct {
    TurnsTotal      *prometheus.CounterVec
    TurnDuration    prometheus.Histogram
    TurnInFlight    prometheus.Gauge
    ClaudeRestarts  prometheus.Counter
    WebhookDelivery *prometheus.CounterVec
    HookReceived    prometheus.Counter
}

func New(reg prometheus.Registerer) *Metrics {
    m := &Metrics{
        TurnsTotal: prometheus.NewCounterVec(prometheus.CounterOpts{
            Name: "ccw_turns_total", Help: "Turns by terminal result."}, []string{"result"}),
        TurnDuration: prometheus.NewHistogram(prometheus.HistogramOpts{
            Name: "ccw_turn_duration_seconds", Help: "Turn wall-clock duration.",
            Buckets: prometheus.ExponentialBuckets(1, 2, 12)}),
        TurnInFlight: prometheus.NewGauge(prometheus.GaugeOpts{
            Name: "ccw_turn_in_flight", Help: "Turns currently in flight (0 or 1)."}),
        ClaudeRestarts: prometheus.NewCounter(prometheus.CounterOpts{
            Name: "ccw_claude_restarts_total", Help: "claude process restarts."}),
        WebhookDelivery: prometheus.NewCounterVec(prometheus.CounterOpts{
            Name: "ccw_webhook_delivery_total", Help: "Webhook deliveries by result."}, []string{"result"}),
        HookReceived: prometheus.NewCounter(prometheus.CounterOpts{
            Name: "ccw_hook_received_total", Help: "Stop-hook callbacks received."}),
    }
    reg.MustRegister(m.TurnsTotal, m.TurnDuration, m.TurnInFlight,
        m.ClaudeRestarts, m.WebhookDelivery, m.HookReceived)
    return m
}

package webhook_test

import (
    "context"
    "net/http"
    "net/http/httptest"
    "sync/atomic"
    "testing"
    "time"

    "github.com/prometheus/client_golang/prometheus"
    "github.com/stretchr/testify/require"
    "github.com/szymonrychu/tatara-claude-code-wrapper/internal/metrics"
    "github.com/szymonrychu/tatara-claude-code-wrapper/internal/turn"
    "github.com/szymonrychu/tatara-claude-code-wrapper/internal/webhook"
)

func newSender(t *testing.T, retries int) *webhook.Sender {
    t.Helper()
    return webhook.New(webhook.Config{Retries: retries, Backoff: time.Millisecond},
        metrics.New(prometheus.NewRegistry()), discardLogger())
}

func TestDeliver_SucceedsAfterRetry(t *testing.T) {
    var hits int32
    srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
        if atomic.AddInt32(&hits, 1) < 2 {
            w.WriteHeader(http.StatusInternalServerError)
            return
        }
        w.WriteHeader(http.StatusOK)
    }))
    defer srv.Close()

    s := newSender(t, 3)
    rec := &turn.Record{ID: "t1", State: turn.Complete, FinalText: "PONG"}
    s.Deliver(context.Background(), srv.URL, rec)
    require.Eventually(t, func() bool { return atomic.LoadInt32(&hits) == 2 }, time.Second, 5*time.Millisecond)
}

func TestDeliver_EmptyURLIsNoop(t *testing.T) {
    s := newSender(t, 1)
    s.Deliver(context.Background(), "", &turn.Record{ID: "t1"}) // must not panic
}

func discardLogger() *slog.Logger { return slog.New(slog.NewTextHandler(io.Discard, nil)) }

// Package webhook delivers turn results to caller-supplied callback URLs.
package webhook

import (
    "bytes"
    "context"
    "encoding/json"
    "fmt"
    "log/slog"
    "net/http"
    "time"

    "github.com/szymonrychu/tatara-claude-code-wrapper/internal/metrics"
    "github.com/szymonrychu/tatara-claude-code-wrapper/internal/turn"
)

type Config struct {
    Retries int
    Backoff time.Duration
}

type Sender struct {
    cfg    Config
    client *http.Client
    m      *metrics.Metrics
    log    *slog.Logger
}

func New(cfg Config, m *metrics.Metrics, log *slog.Logger) *Sender {
    if cfg.Backoff <= 0 {
        cfg.Backoff = time.Second
    }
    return &Sender{cfg: cfg, client: &http.Client{Timeout: 30 * time.Second}, m: m, log: log}
}

// Deliver posts the record to url asynchronously, retrying with exponential
// backoff. A blank url is a no-op (poll-only callers).
func (s *Sender) Deliver(ctx context.Context, url string, rec *turn.Record) {
    if url == "" {
        return
    }
    body, err := json.Marshal(rec)
    if err != nil {
        s.log.Error("webhook: marshal", "err", err, "turn_id", rec.ID)
        return
    }
    go s.deliver(ctx, url, rec.ID, body)
}

func (s *Sender) deliver(ctx context.Context, url, turnID string, body []byte) {
    backoff := s.cfg.Backoff
    for attempt := 0; attempt <= s.cfg.Retries; attempt++ {
        if err := s.post(ctx, url, body); err != nil {
            s.log.Warn("webhook: attempt failed", "err", err, "turn_id", turnID, "attempt", attempt)
            select {
            case <-ctx.Done():
                s.m.WebhookDelivery.WithLabelValues("dropped").Inc()
                return
            case <-time.After(backoff):
            }
            backoff *= 2
            continue
        }
        s.m.WebhookDelivery.WithLabelValues("ok").Inc()
        s.log.Info("webhook: delivered", "turn_id", turnID, "url", url)
        return
    }
    s.m.WebhookDelivery.WithLabelValues("dropped").Inc()
    s.log.Error("webhook: dropped after retries", "turn_id", turnID, "url", url)
}

func (s *Sender) post(ctx context.Context, url string, body []byte) error {
    req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body))
    if err != nil {
        return fmt.Errorf("new request: %w", err)
    }
    req.Header.Set("Content-Type", "application/json")
    resp, err := s.client.Do(req)
    if err != nil {
        return fmt.Errorf("do: %w", err)
    }
    defer func() { _ = resp.Body.Close() }()
    if resp.StatusCode >= 300 {
        return fmt.Errorf("status %d", resp.StatusCode)
    }
    return nil
}

package bootstrap_test

import (
    "encoding/json"
    "os"
    "path/filepath"
    "testing"

    "github.com/stretchr/testify/require"
    "github.com/szymonrychu/tatara-claude-code-wrapper/internal/bootstrap"
)

func TestRender_WritesClaudeMdSettingsSkillsAndMergesMCP(t *testing.T) {
    home := t.TempDir()
    ws := t.TempDir()
    overlay := t.TempDir()
    skillsSrc := t.TempDir()

    // a baked skill source
    require.NoError(t, os.MkdirAll(filepath.Join(skillsSrc, "handoff"), 0o755))
    require.NoError(t, os.WriteFile(filepath.Join(skillsSrc, "handoff", "SKILL.md"), []byte("# /handoff"), 0o644))
    // an mcp overlay fragment
    require.NoError(t, os.WriteFile(filepath.Join(overlay, "tasks.json"),
        []byte(`{"mcpServers":{"tasks":{"type":"stdio","command":"/bin/tasks"}}}`), 0o644))

    var gitCalls [][]string
    p := bootstrap.Params{
        HomeDir: home, Workspace: ws,
        GlobalClaudeMd:  "GLOBAL RULES",
        ProjectClaudeMd: "PROJECT RULES",
        BaseMCP:         []byte(`{"mcpServers":{"tatara-memory":{"type":"stdio","command":"tatara","args":["mcp"]}}}`),
        MCPOverlayDir:   overlay,
        SkillsSrc:       []string{skillsSrc},
        HookCommand:     "/usr/local/bin/cc-stop-hook",
        AllowedTools:    []string{"Bash", "Edit"},
        EnableAllMCP:    true,
        PermissionMode:  "bypassPermissions",
    }
    require.NoError(t, bootstrap.Render(p, func(a ...string) error { gitCalls = append(gitCalls, a); return nil }))

    // global + project CLAUDE.md
    b, _ := os.ReadFile(filepath.Join(home, ".claude", "CLAUDE.md"))
    require.Equal(t, "GLOBAL RULES", string(b))
    b, _ = os.ReadFile(filepath.Join(ws, "CLAUDE.md"))
    require.Equal(t, "PROJECT RULES", string(b))

    // merged .mcp.json has BOTH servers
    b, _ = os.ReadFile(filepath.Join(ws, ".mcp.json"))
    var mcp struct{ MCPServers map[string]any `json:"mcpServers"` }
    require.NoError(t, json.Unmarshal(b, &mcp))
    require.Contains(t, mcp.MCPServers, "tatara-memory")
    require.Contains(t, mcp.MCPServers, "tasks")

    // settings.json wires Stop hook + enableAllProjectMcpServers
    b, _ = os.ReadFile(filepath.Join(home, ".claude", "settings.json"))
    require.Contains(t, string(b), "/usr/local/bin/cc-stop-hook")
    require.Contains(t, string(b), "enableAllProjectMcpServers")

    // skill copied
    b, _ = os.ReadFile(filepath.Join(ws, ".claude", "skills", "handoff", "SKILL.md"))
    require.Equal(t, "# /handoff", string(b))

    // no repo configured -> git not called
    require.Empty(t, gitCalls)
}

func TestRender_ClonesRepoWhenURLSet(t *testing.T) {
    var gitCalls [][]string
    p := bootstrap.Params{
        HomeDir: t.TempDir(), Workspace: t.TempDir(),
        BaseMCP: []byte(`{"mcpServers":{}}`),
        RepoURL: "https://github.com/x/y", RepoBranch: "main",
        HookCommand: "/usr/local/bin/cc-stop-hook", PermissionMode: "bypassPermissions",
    }
    require.NoError(t, bootstrap.Render(p, func(a ...string) error { gitCalls = append(gitCalls, a); return nil }))
    require.Len(t, gitCalls, 1)
    require.Contains(t, gitCalls[0], "clone")
    require.Contains(t, gitCalls[0], "https://github.com/x/y")
    require.Contains(t, gitCalls[0], "main")
}

// Package bootstrap renders the per-session files claude reads at startup.
package bootstrap

import (
    "fmt"
    "os"
    "path/filepath"
)

type Params struct {
    HomeDir, Workspace          string
    GlobalClaudeMd, ProjectClaudeMd string
    BaseMCP                     []byte
    MCPOverlayDir               string
    SkillsSrc                   []string
    HookCommand                 string
    AllowedTools                []string
    EnableAllMCP                bool
    PermissionMode              string
    AnthropicAPIKey             string // used to seed customApiKeyResponses (last 20 chars)
    RepoURL, RepoBranch         string
}

// GitRunner runs a git subcommand; injected for testability.
type GitRunner func(args ...string) error

func Render(p Params, git GitRunner) error {
    claudeHome := filepath.Join(p.HomeDir, ".claude")
    if err := os.MkdirAll(claudeHome, 0o755); err != nil {
        return fmt.Errorf("mkdir claude home: %w", err)
    }
    if err := os.MkdirAll(p.Workspace, 0o755); err != nil {
        return fmt.Errorf("mkdir workspace: %w", err)
    }
    if p.RepoURL != "" {
        if err := cloneRepo(p, git); err != nil {
            return err
        }
    }
    if err := writeIfSet(filepath.Join(p.Workspace, "CLAUDE.md"), p.ProjectClaudeMd); err != nil {
        return err
    }
    if err := writeIfSet(filepath.Join(claudeHome, "CLAUDE.md"), p.GlobalClaudeMd); err != nil {
        return err
    }
    if err := mergeMCP(p); err != nil {
        return err
    }
    if err := writeSettings(p, claudeHome); err != nil {
        return err
    }
    if err := writeClaudeJSON(p); err != nil {
        return err
    }
    return installSkills(p)
}

func writeIfSet(path, content string) error {
    if content == "" {
        return nil
    }
    if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
        return fmt.Errorf("write %s: %w", path, err)
    }
    return nil
}

package bootstrap

import (
    "encoding/json"
    "fmt"
    "os"
    "path/filepath"
)

type mcpDoc struct {
    MCPServers map[string]json.RawMessage `json:"mcpServers"`
}

// mergeMCP unions the baked base config with every *.json fragment in the
// overlay dir and writes /workspace/.mcp.json. Overlay keys win on conflict.
func mergeMCP(p Params) error {
    merged := mcpDoc{MCPServers: map[string]json.RawMessage{}}
    if len(p.BaseMCP) > 0 {
        var base mcpDoc
        if err := json.Unmarshal(p.BaseMCP, &base); err != nil {
            return fmt.Errorf("parse base mcp: %w", err)
        }
        for k, v := range base.MCPServers {
            merged.MCPServers[k] = v
        }
    }
    if p.MCPOverlayDir != "" {
        entries, err := os.ReadDir(p.MCPOverlayDir)
        if err != nil && !os.IsNotExist(err) {
            return fmt.Errorf("read mcp overlay: %w", err)
        }
        for _, e := range entries {
            if e.IsDir() || filepath.Ext(e.Name()) != ".json" {
                continue
            }
            b, err := os.ReadFile(filepath.Join(p.MCPOverlayDir, e.Name()))
            if err != nil {
                return fmt.Errorf("read overlay %s: %w", e.Name(), err)
            }
            var frag mcpDoc
            if err := json.Unmarshal(b, &frag); err != nil {
                return fmt.Errorf("parse overlay %s: %w", e.Name(), err)
            }
            for k, v := range frag.MCPServers {
                merged.MCPServers[k] = v
            }
        }
    }
    out, err := json.MarshalIndent(merged, "", "  ")
    if err != nil {
        return fmt.Errorf("marshal mcp: %w", err)
    }
    if err := os.WriteFile(filepath.Join(p.Workspace, ".mcp.json"), out, 0o644); err != nil {
        return fmt.Errorf("write .mcp.json: %w", err)
    }
    return nil
}

package bootstrap

import (
    "encoding/json"
    "fmt"
    "os"
    "path/filepath"
)

func writeSettings(p Params, claudeHome string) error {
    type hookCmd struct {
        Type    string `json:"type"`
        Command string `json:"command"`
    }
    type hookMatcher struct {
        Matcher string    `json:"matcher"`
        Hooks   []hookCmd `json:"hooks"`
    }
    settings := map[string]any{
        "hooks": map[string]any{
            "Stop": []hookMatcher{{Matcher: "", Hooks: []hookCmd{{Type: "command", Command: p.HookCommand}}}},
        },
        "enableAllProjectMcpServers": p.EnableAllMCP,
    }
    if p.PermissionMode != "" || len(p.AllowedTools) > 0 {
        perms := map[string]any{}
        if p.PermissionMode != "" {
            perms["defaultMode"] = p.PermissionMode
        }
        if len(p.AllowedTools) > 0 {
            perms["allow"] = p.AllowedTools
        }
        settings["permissions"] = perms
    }
    out, err := json.MarshalIndent(settings, "", "  ")
    if err != nil {
        return fmt.Errorf("marshal settings: %w", err)
    }
    if err := os.WriteFile(filepath.Join(claudeHome, "settings.json"), out, 0o644); err != nil {
        return fmt.Errorf("write settings.json: %w", err)
    }
    return nil
}

// skills.go
package bootstrap

import (
    "fmt"
    "io"
    "os"
    "path/filepath"
)

// installSkills copies every skill tree under each SkillsSrc dir into
// /workspace/.claude/skills, so baked + custom skills coexist.
func installSkills(p Params) error {
    dst := filepath.Join(p.Workspace, ".claude", "skills")
    if err := os.MkdirAll(dst, 0o755); err != nil {
        return fmt.Errorf("mkdir skills: %w", err)
    }
    for _, src := range p.SkillsSrc {
        if src == "" {
            continue
        }
        if _, err := os.Stat(src); os.IsNotExist(err) {
            continue
        }
        if err := copyTree(src, dst); err != nil {
            return fmt.Errorf("install skills from %s: %w", src, err)
        }
    }
    return nil
}

func copyTree(src, dst string) error {
    return filepath.Walk(src, func(path string, info os.FileInfo, err error) error {
        if err != nil {
            return err
        }
        rel, _ := filepath.Rel(src, path)
        target := filepath.Join(dst, rel)
        if info.IsDir() {
            return os.MkdirAll(target, 0o755)
        }
        return copyFile(path, target)
    })
}

func copyFile(src, dst string) error {
    in, err := os.Open(src)
    if err != nil {
        return err
    }
    defer func() { _ = in.Close() }()
    out, err := os.Create(dst)
    if err != nil {
        return err
    }
    defer func() { _ = out.Close() }()
    _, err = io.Copy(out, in)
    return err
}