feat: complete TUI debugger iteration 3

Changes:
- refactor
- cli params
- UX details
- help screen
- aligned readme
- aligned Taskfile

.github/workflows/go.yml

@@ -1,4 +1,4 @@
-name: Go
+name: Go Test
 
 on: [push]
 

.gitignore

@@ -44,4 +44,6 @@ go.work
 
 # local dev
 /.dev
-/docs/cookbook.md
+/docs/cookbook.md
+/tools/am-dbg/am-dbg
+/*.log

README.md

@@ -137,15 +137,52 @@ func HandleFileProcessingTask(ctx context.Context, t *asynq.Task) error {
    - [Relations](/docs/manual.md#relations)
    - [Queue](/docs/manual.md#queue)
 
-## Debugger
+## TUI Debugger
 
-Preview of the TUI debugger, currently being work on in #5.
+`am-dbg` is a simple, yet effective tool to debug your machines, including:
 
-![TUI Debugger](assets/debugger.png)
+- states with relations
+- time travel
+- transition steps
+- logs
+
+![TUI Debugger](assets/am-dbg.jpg)
+
+### Installation
+
+`go install github.com/pancsta/asyncmachine-go/tools/am-dbg@latest`
+
+### Usage
+
+Set up telemetry:
+
+```go
+import (
+    "github.com/pancsta/asyncmachine-go/pkg/telemetry"
+)
+// ...
+err := telemetry.MonitorTransitions(machine, telemetry.RpcHost)
+```
+
+Run `am-dbg`:
+
+```text
+Usage:
+  am-dbg [flags]
+
+Flags:
+      --am-dbg-url string   Debug this instance of am-dbg with another one
+      --enable-mouse        Enable mouse support
+  -h, --help                help for am-dbg
+      --log-file string     Log file path (default "am-dbg.log")
+      --log-level int       Log level, 0-5 (silent-everything)
+      --log-machine-id      Include machine ID in log messages (default true)
+      --server-url string   Host and port for the server to listen on (default "localhost:9823")
+```
 
 ## Changelog
 
-Latest release: `v0.2.1`
+Latest release: `v0.3.0`
 
 See [CHANELOG.md](/CHANGELOG.md) for details.
 

Taskfile.yml

@@ -2,19 +2,47 @@ version: '3'
 
 dotenv: ['.env']
 
+env:
+  GOFMT: gofumpt
+
 tasks:
 
-  demo:
+  build-machine:
+    cmds:
+      - go build pkg/machine/*.go
+
+  build-telemetry:
     cmds:
-      - task: install-deps
-      - task: build-protobufs
-      - task: test
-      - task: start
+      - go build pkg/telemetry/*.go
+
+  build-debugger:
+    cmds:
+      - go build -o build/am-dbg tools/am-dbg/*.go
 
   build:
     cmds:
-      - go build src/machine/*
-    silent: true
+      - task: build-machine
+      - task: build-telemetry
+      - task: build-debugger
+
+  debugger:
+    cmds:
+      - go run tools/am-dbg/main.go {{.CLI_ARGS}}
+
+  debugger-client:
+    cmds:
+      - go run tools/am-dbg/main.go 
+          --log-machine-id false 
+          --log-level 2
+          --am-dbg-url localhost:9913
+
+  debugger-debugger:
+    cmds:
+      - go run tools/am-dbg/main.go 
+          --log-file am-dbg-dbg.log 
+          --log-machine-id false 
+          --log-level 2
+          --server-url localhost:9913
 
   test:
     cmds:
@@ -33,14 +61,17 @@ tasks:
     cmds:
       - gocloc pkg/machine --not-match=_test\.go
       - gocloc pkg/machine/*_test.go
+      - gocloc tools/am-dbg/**/* --not-match=_test\.go
       - gocloc examples
       - gocloc --include-lang=md docs
 
   format:
     cmds:
-      - gofumpt -w pkg/machine/*.go
-      - gofumpt -w examples/*/*.go
-      - goimports -w pkg/**
+      - $GOFMT -w examples/*/*.go
+      - $GOFMT -w pkg/**/*.go
+      - $GOFMT -w tools/**/*.go
+      - goimports -w -local "github.com/pancsta/asyncmachine-go" pkg/**/*.go
+      - goimports -w -local "github.com/pancsta/asyncmachine-go" tools/**/*.go
 
   lint:
     cmds:
@@ -52,15 +83,24 @@ tasks:
           echo "Error: Empty links" >&2
           exit 1
         fi
+      - task: check-fmt
 
   lint-go:
     cmds:
-      - golangci-lint run
+      - golangci-lint run --fix
 
   lint-md:
     cmds:
-      # TODO -g
-      - mdl -c .mdlrc .
+      - mdl -g -c .mdlrc .
+
+  check-fmt:
+    silent: false
+    cmds:
+      - test -z $($GOFMT -l examples/**/*.go)
+      - test -z $($GOFMT -l pkg/**/*.go)
+      - test -z $($GOFMT -l tools/am-dbg/*.go)
+      - test -z $(goimports -l -local "github.com/pancsta/asyncmachine-go" pkg/**/*.go)
+      - test -z $(goimports -l -local "github.com/pancsta/asyncmachine-go" tools/**/*.go)
 
   changelog:
     cmds:
@@ -74,5 +114,6 @@ tasks:
       - curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.55.2
       - go install mvdan.cc/gofumpt@latest
       - go install golang.org/x/tools/cmd/goimports@latest
+      # TODO switch to nodejs md linter
       - gem install mdl
       - gem install github_changelog_generator

go.mod

@@ -10,6 +10,7 @@ require (
 	github.com/lithammer/dedent v1.1.0
 	github.com/pancsta/cview v1.5.10
 	github.com/samber/lo v1.39.0
+	github.com/spf13/cobra v1.8.0
 	github.com/stretchr/testify v1.8.4
 )
 
@@ -19,13 +20,15 @@ require (
 	github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect
 	github.com/gdamore/encoding v1.0.0 // indirect
 	github.com/golang/protobuf v1.5.2 // indirect
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
 	github.com/mattn/go-runewidth v0.0.15 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/redis/go-redis/v9 v9.0.3 // indirect
 	github.com/rivo/uniseg v0.4.7-0.20240127222946-601bbb3750c2 // indirect
 	github.com/robfig/cron/v3 v3.0.1 // indirect
 	github.com/spf13/cast v1.3.1 // indirect
+	github.com/spf13/pflag v1.0.5 // indirect
 	golang.org/x/exp v0.0.0-20220303212507-bbda1eaf7a17 // indirect
 	golang.org/x/sys v0.16.0 // indirect
 	golang.org/x/term v0.16.0 // indirect
@@ -35,4 +38,4 @@ require (
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )
 
-//replace github.com/pancsta/cview => ../cview
+replace github.com/pancsta/cview => ../cview

go.sum

@@ -1,11 +1,13 @@
 code.rocketnine.space/tslocum/cbind v0.1.5 h1:i6NkeLLNPNMS4NWNi3302Ay3zSU6MrqOT+yJskiodxE=
 code.rocketnine.space/tslocum/cbind v0.1.5/go.mod h1:LtfqJTzM7qhg88nAvNhx+VnTjZ0SXBJtxBObbfBWo/M=
+code.rocketnine.space/tslocum/cview v1.5.9/go.mod h1:nraCJ41xU9AOAP/pJDV5t2fOelYp8CRGBZr8ZbEzw0w=
 github.com/bsm/ginkgo/v2 v2.7.0 h1:ItPMPH90RbmZJt5GtkcNvIRuGEdwlBItdNVoyzaNQao=
 github.com/bsm/ginkgo/v2 v2.7.0/go.mod h1:AiKlXPm7ItEHNc/2+OkrNG4E0ITzojb9/xWzvQ9XZ9w=
 github.com/bsm/gomega v1.26.0 h1:LhQm+AFcgV2M0WyKroMASzAzCAJVpAxQXv4SaI9a69Y=
 github.com/bsm/gomega v1.26.0/go.mod h1:JyEr/xRbxbtgWNi8tIEVPUYZ5Dzef52k01W3YH0H+O0=
 github.com/cespare/xxhash/v2 v2.2.0 h1:DC2CZ1Ep5Y4k3ZQ899DldepgrayRUGE6BBZ/cd9Cj44=
 github.com/cespare/xxhash/v2 v2.2.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/cpuguy83/go-md2man/v2 v2.0.3/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
@@ -27,6 +29,8 @@ github.com/google/uuid v1.5.0 h1:1p67kYwdtXjb0gL0BPiP1Av9wiZPo5A8z2cWkTZ+eyU=
 github.com/google/uuid v1.5.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/hibiken/asynq v0.24.1 h1:+5iIEAyA9K/lcSPvx3qoPtsKJeKI5u9aOIvUmSsazEw=
 github.com/hibiken/asynq v0.24.1/go.mod h1:u5qVeSbrnfT+vtG5Mq8ZPzQu/BmCKMHvTGb91uy9Tts=
+github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
+github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
 github.com/kr/pretty v0.1.0 h1:L/CwN0zerZDmRFUapSPitk6f+Q3+0za1rQkzVuMiMFI=
 github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
 github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
@@ -54,10 +58,15 @@ github.com/rivo/uniseg v0.4.7-0.20240127222946-601bbb3750c2 h1:tcc3ZFBvjydcgrAxa
 github.com/rivo/uniseg v0.4.7-0.20240127222946-601bbb3750c2/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
 github.com/robfig/cron/v3 v3.0.1 h1:WdRxkvbJztn8LMz/QEvLN5sBU+xKpSqwwUO1Pjr4qDs=
 github.com/robfig/cron/v3 v3.0.1/go.mod h1:eQICP3HwyT7UooqI/z+Ov+PtYAWygg1TEWWzGIFLtro=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/samber/lo v1.39.0 h1:4gTz1wUhNYLhFSKl6O+8peW0v2F4BCY034GRpU9WnuA=
 github.com/samber/lo v1.39.0/go.mod h1:+m/ZKRl6ClXCE2Lgf3MsQlWfh4bn1bz6CXEOxnEXnEA=
 github.com/spf13/cast v1.3.1 h1:nFm6S0SMdyzrzcmThSipiEubIDy8WEXKNZ0UOgiRpng=
 github.com/spf13/cast v1.3.1/go.mod h1:Qx5cxh0v+4UWYiBimWS+eyWzqEqokIECu5etghLkUJE=
+github.com/spf13/cobra v1.8.0 h1:7aJaZx1B85qltLMc546zn58BxxfZdR/W22ej9CFoEf0=
+github.com/spf13/cobra v1.8.0/go.mod h1:WXLWApfZ71AjXPya3WOlMsY9yMs7YeiHhFVlvLyhcho=
+github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA=
+github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/testify v1.2.2/go.mod h1:a8OnRcib4nhh0OaRAV+Yts87kKdq0PP7pXfy6kDkUVs=
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=

pkg/telemetry/telemetry.go

@@ -2,6 +2,7 @@ package telemetry
 
 import (
 	"encoding/gob"
+	"fmt"
 	"log"
 	"net/rpc"
 
@@ -12,6 +13,7 @@ import (
 
 const RpcHost = "localhost:9823"
 
+// Msg is the interface for the messages to be sent to the am-dbg server.
 type Msg interface {
 	// Clock returns the state's clock, using the passed index
 	Clock(statesIndex am.S, state string) uint64
@@ -39,23 +41,23 @@ func (d *MsgStruct) Is(_ am.S, _ am.S) bool {
 	return false
 }
 
-// MsgTx contains transaction data.
+// MsgTx contains transition data.
 type MsgTx struct {
 	// Transition ID
 	ID string
-	// map of positions from the index to the active state
+	// StatesIndex-based active indicators
 	StatesActive []bool
 	// map of positions from the index to state clocks
 	Clocks []uint64
 	// result of the transition
 	Accepted bool
 	// all the transition steps
 	Steps []*am.TransitionStep
-	// log entries since the last diff
+	// log entries created during the transition
 	LogEntries []string
 	// log entries before the transition, which happened after the prev one
 	PreLogEntries []string
-	// tx was triggered by an auto state
+	// transition was triggered by an auto state
 	IsAuto bool
 	// queue length at the start of the transition
 	Queue int
@@ -114,7 +116,7 @@ func MonitorTransitions(m *am.Machine, url string) error {
 	gob.Register(am.Relation(0))
 	client, err := newClient(url)
 	if err != nil {
-		return err
+		return fmt.Errorf("failed to connect to am-dbg: %w", err)
 	}
 	msg := &MsgStruct{
 		ID:          m.ID,
@@ -125,7 +127,7 @@ func MonitorTransitions(m *am.Machine, url string) error {
 	// TODO retries
 	err = client.sendMsgStruct(msg)
 	if err != nil {
-		log.Println(err)
+		return fmt.Errorf("failed to send a msg to am-dbg: %w", err)
 	}
 	go func() {
 		// bind to transitions
@@ -156,7 +158,7 @@ func MonitorTransitions(m *am.Machine, url string) error {
 			// TODO retries
 			err := client.sendMsgTx(msg)
 			if err != nil {
-				log.Println(err)
+				log.Println("failed to send a msg to am-dbg: " + url + err.Error())
 				return
 			}
 		}