Overhaul Dev Experience (#656)

The idea is to bring the explainer per paragraph into the TUI.

CONTRIBUTING.md

@@ -31,7 +31,7 @@ To request a new feature you should open an [issue](../../issues/new) and summar
 This is an outline of what the workflow for code contributions looks like
 
 - Check the list of open [issues](../../issues). Either assign an existing issue to yourself, or
-  create a new one that you would like work on and discuss your ideas and use cases.
+   create a new one that you would like work on and discuss your ideas and use cases.
 
 It is always best to discuss your plans beforehand, to ensure that your contribution is in line with our goals.
 
@@ -86,9 +86,9 @@ Following is some documentation on the different build targets `runme` has, and
 
 #### CLI
 
-CLI is built with:
+Build the CLI:
 
-```sh {"id":"01HF7BT3HEQBTBM9SSTFD1C6N4","interactive":"false"}
+```sh {"id":"01HF7BT3HEQBTBM9SSTFD1C6N4","interactive":"false","name":"build"}
 make build
 ```
 
@@ -99,18 +99,13 @@ This builds the CLI binary for the current platform to an executable file "runme
 # outputs: "runme version 1.3.0-27-g3cca8a6-3cca8a6 (3cca8a6e7d34f401c1bdd99828a7fac5b1d8fac9) on 2023-07-31T16:49:57Z"
 ```
 
-To run the server in dev mode with predictable port and TLS credentials location:
-
-```sh {"background":"true","id":"01HJ9NZT45B03C9J6YJJJDB8PG","interactive":"true","name":"server-dev"}
-go run . server --dev --address 127.0.0.1:9999 --tls /tmp/runme/tls 2>&1
-```
-
 #### WASM
 
 WASM is built with:
 
-```sh {"id":"01HF7BT3HEQBTBM9SSTH3HC2DS","interactive":"false"}
+```sh {"id":"01HF7BT3HEQBTBM9SSTH3HC2DS"}
 make wasm
+ls -la examples/web/runme.wasm
 ```
 
 This builds the wasm file to `examples/web/runme.wasm`.
@@ -119,13 +114,13 @@ This builds the wasm file to `examples/web/runme.wasm`.
 
 To install tools like `gofumpt` and `revive` which are used for development (e.g. linting) run
 
-```sh
+```sh {"id":"01J5P9MKFZ4SRS1VE6J62HFKP0","name":"setup"}
 make install/dev
 ```
 
 You will need the [pre-commit](https://pre-commit.com/) tool to run the pre-commit hooks. You can install it with:
 
-```sh
+```sh {"id":"01J5P9MKFZ4SRS1VE6J8XKD8ZM"}
 python3 -m pip install pre-commit
 ```
 
@@ -147,33 +142,59 @@ pre-commit run --files */**
 
 Tests are run with Go's default test runner wrapped in Makefile targets. So, for example, you can run all tests with:
 
-```sh {"id":"01HF7BT3HEQBTBM9SSTS88ZSCF"}
-make test
+```sh {"id":"01HF7BT3HEQBTBM9SSTS88ZSCF","name":"test","terminalRows":"15"}
+go clean -testcache
+TAGS="test_with_docker" make test
 ```
 
 Please notice that our tests include integration tests which depend on additional software like Python or node.js. If you don't want to install them or tests fail because of different versions, you can run all tests in a Docker container:
 
-```sh
+```sh {"id":"01J5P9MKFZ4SRS1VE6JBKG3EAK","terminalRows":"15"}
 make test-docker
 ```
 
+## Development
+
+To run the server in dev mode with predictable port and TLS credentials location:
+
+```sh {"background":"true","id":"01HJ9NZT45B03C9J6YJJJDB8PG","interactive":"true","name":"server-dev"}
+go run . server --dev --address 127.0.0.1:9999 --tls /tmp/runme/tls 2>&1
+```
+
+### Upgrading Minor Version Dependencies
+
+For upgrading dependencies that have minor version changes, as well as test dependencies, use the following command. This command fetches the latest minor or patch versions of the modules required for building the current module, including their dependencies:
+Periodically dependencies need to be upgraded. For minor versions with test deps:
+
+```sh {"id":"01HF7BT3HEQBTBM9SSSG798S2D"}
+$ go get -t -u ./...
+```
+
+### Upgrading Major Version Dependencies
+
+When you need to upgrade to major versions of your dependencies, it’s prudent to upgrade each dependency one at a time to manage potential breaking changes efficiently. The `gomajor` tool can assist you in listing and upgrading major version dependencies. To list all major version upgrades available for your project, use the following command:
+
+```sh {"id":"01HF7BT3HEQBTBM9SSSK6JMS58"}
+$ gomajor list
+```
+
 ### Coverage
 
 In order to generate a coverage report, run tests using
 
-```sh {"name":"coverage-run"}
+```sh {"id":"01J5P9MKFZ4SRS1VE6JCT00N4K"}
 make test-coverage
 ```
 
-And then:
+And then, for the html coverage report, run:
 
-```sh {"id":"01HJVHEVPX2AZJ86999P1MY5H0","name":"coverage-html"}
+```sh {"id":"01HJVHEVPX2AZJ86999P1MY5H0"}
 make test/coverage/html
 ```
 
 Output coverage profile information for each function:
 
-```sh {"id":"01HJVHHNMZRNK0ZGA154A9AJCZ","name":"coverage-func"}
+```sh {"id":"01HJVHHNMZRNK0ZGA154A9AJCZ"}
 make test/coverage/func
 ```
 
@@ -223,6 +244,20 @@ export RUNME_EXT_BASE="../vscode-runme"
 make proto/dev/reset
 ```
 
+### Publish Protobuf Definitions
+
+Firstly, set up your Buffer (Buf) token by exporting it as an environment variable. Replace `Your buf token` with your actual Buf token:
+
+```sh {"id":"01HF7BT3HEQBTBM9SSSNM5ZT19"}
+export BUF_TOKEN=Your buf token
+```
+
+After setting the Buf token, proceed to publish the updated protobuf definitions. The `make proto/publish` command below will trigger the publishing process, ensuring your protobuf definitions are released and available for use:
+
+```sh {"id":"01HF7BT3HEQBTBM9SSSPD5B5WW","name":"proto-publish-buf"}
+make proto/publish
+```
+
 ### GraphQL
 
 GraphQL schema are generated as part of:
@@ -249,7 +284,7 @@ make generate
 
 This project uses [gomock](https://github.com/golang/mock) to generate some mocks for some interfaces. You will need to install `gomock` in order for `go generate` to work.
 
-## Releasing
+## Release Kernel/CLI
 
 The releaser uses `goreleaser` to handle cross-compilation, as well as snapshotting etc. This is run with:
 
@@ -262,11 +297,3 @@ The requisite tools can be installed with:
 ```sh {"id":"01HF7BT3HF9WY615MNGR8HJEKZ","interactive":"false"}
 make install/goreleaser
 ```
-
-## Upgrading to go 1.22
-
-After upgrading go to version 1.22, you'll need to make sure to reinstall dev packages, as some may be outdated:
-
-```sh {"id":"01HF7BT3HF9WY615MNGREVYKFG","name":"upgrade-go-1-22"}
-make install/dev
-```

internal/cmd/tui.go

@@ -3,6 +3,7 @@ package cmd
 import (
 	"fmt"
 	"math"
+	"path/filepath"
 	"strings"
 
 	"github.com/atotto/clipboard"
@@ -295,7 +296,7 @@ func (m tuiModel) Init() tea.Cmd {
 
 const (
 	tab                   = "  "
-	defaultVisibleEntries = 5
+	defaultVisibleEntries = 6
 )
 
 func (m tuiModel) View() string {
@@ -319,21 +320,30 @@ func (m tuiModel) View() string {
 
 		{
 			name := block.Name()
-
 			if block.IsUnnamed() {
 				name += " (unnamed)"
 			}
 
-			filename := ansi.Color(getRelativePath(getCwd(), task.DocumentPath), "white+d")
+			relFilename := getRelativePath(getCwd(), task.DocumentPath)
+			filename := ansi.Color(relFilename, "white+d")
 
 			if active {
-				name = ansi.Color(name, "white+b")
+				name = ansi.Color(name, "white+ub")
+			}
+
+			intro := block.Intro()
+			words := strings.Split(intro, " ")
+			// todo(sebastian): this likely only works well for English
+			max := 9 - len(strings.Split(relFilename, fmt.Sprint(filepath.Separator)))
+			if len(words) > max {
+				intro = strings.Join(words[:max], " ") + "..."
 			}
 
 			identifier := fmt.Sprintf(
-				"%s %s",
+				"%s %s: %s",
 				name,
 				filename,
+				intro,
 			)
 
 			line += identifier + "\n"