summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorPaul Buetow <paul@buetow.org>2025-09-07 14:29:35 +0300
committerPaul Buetow <paul@buetow.org>2025-09-07 14:29:35 +0300
commit23482b5d8da5c67da1fc501ddbafdd123be3972c (patch)
tree452dc7c418055ebb79a88a303e50d2dbc1877f09 /docs
parent76f388f9759cdc15cb1eba985cd87cde1906208b (diff)
feat: rename hexai-action -> hexai-tmux-action; remove --tmux/--no-tmux; tmux-only flow; update docs and Magefile
Diffstat (limited to 'docs')
-rw-r--r--docs/configuration.md6
-rw-r--r--docs/go-unit-tests.md27
-rw-r--r--docs/source-structure.md79
-rw-r--r--docs/testing.md30
-rw-r--r--docs/usage.md8
5 files changed, 7 insertions, 143 deletions
diff --git a/docs/configuration.md b/docs/configuration.md
index dc4adbd..09ff519 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -42,11 +42,11 @@ Hexai Action (TUI) configuration
This is mostly useful when Helix runs in a [tmux](https://tmux.github.io/) session!
-- Helix integration (recommended): bind a key to pipe the current selection to `hexai-action` and replace it with the output.
- - Example: `C-a = ":pipe hexai-action"`
+- Helix integration (recommended): bind a key to pipe the current selection to `hexai-tmux-action` and replace it with the output.
+ - Example: `C-a = ":pipe hexai-tmux-action"`
- Default behavior:
- Inline TUI when run in a real terminal (TTY).
- - When invoked via Helix `:pipe` and a tmux session is available, `hexai-action` opens a split pane to render the menu and returns the result on stdout for Helix to apply.
+ - When invoked via Helix `:pipe`, `hexai-tmux-action` opens a split pane to render the menu and returns the result on stdout for Helix to apply.
- If no TTY and no tmux are available, it falls back to echoing the input.
- Flags:
- `--infile` Read input from the given file instead of stdin.
diff --git a/docs/go-unit-tests.md b/docs/go-unit-tests.md
deleted file mode 100644
index 1be9fd0..0000000
--- a/docs/go-unit-tests.md
+++ /dev/null
@@ -1,27 +0,0 @@
-# Go unit tests via code action
-
-Hexai can generate Go unit tests for the function at your cursor.
-
-- Scope: Available only for Go source files ending with `.go` (not `_test.go`).
-- Trigger: Use your editor's code actions on the current selection/position and pick "Implement unit test".
-
-What happens
-
-- Function detection: Hexai finds the nearest `func` definition above the cursor and captures the function body by balancing braces.
-- Test generation:
- - If an LLM provider is configured, Hexai asks it to generate one or more `Test*` functions using the `testing` package. The provider must return only the test function code (no package/import lines).
- - If no provider is configured or the request fails, Hexai inserts a small stub test `Test<Name>` with a TODO.
-- File handling and navigation:
- - If `<file>_test.go` exists, the test function is appended to the end of that file.
- - If it does not exist, Hexai creates it, writing `package <pkg>` (inferred from the source file) and `import "testing"`, followed by the generated test function(s).
- - After applying the edit, Hexai asks the editor to focus the test file and place the cursor at the start of the newly added test function.
-
-Notes and limitations
-
-- Imports on append: when appending to an existing test file, Hexai assumes `testing` is available. If not, add `import "testing"` to the test file and re-run `go test`.
-- Method names: for methods with receivers, test names default to `TestMethod` (stub fallback). Future improvement may generate `TestType_Method` automatically.
-- Formatting: run `go fmt ./...` or your editor's formatter to normalize whitespace if needed.
-
-Examples
-
-In Helix, position the cursor inside a function and invoke code actions; choose "Implement unit test". Hexai will create or update `<file>_test.go` accordingly.
diff --git a/docs/source-structure.md b/docs/source-structure.md
deleted file mode 100644
index 0c7f56f..0000000
--- a/docs/source-structure.md
+++ /dev/null
@@ -1,79 +0,0 @@
-# Source code structure
-
-This document provides a high‑level map of the Hexai source layout and how the
-main packages relate to each other.
-
-## Diagram
-
-```mermaid
-graph TD
- %% Entrypoints
- A[cmd/hexai\nCLI entrypoint] --> B[internal/hexaicli\nCLI runner]
- C[cmd/hexai-lsp\nLSP entrypoint] --> D[internal/hexailsp\nLSP runner]
-
- %% Shared/internal packages
- subgraph internal/
- I[appconfig\nLoad config from file/env]
- L[llm\nClient + providers]
- G[logging\nBound logger + helpers]
- S[lsp\nJSON-RPC, server, handlers]
- end
-
- %% Relationships
- B --> I
- B --> L
- B --> G
-
- D --> I
- D --> L
- D --> G
- D --> S
-
- S --> L
- S --> G
-
- %% LLM providers
- subgraph internal/llm
- P1[openai.go]
- P2[ollama.go]
- P3[copilot.go]
- end
- L --> P1
- L --> P2
- L --> P3
-
- %% Version info
- V[internal/version.go\nVersion string] --> A
- V --> C
-```
-
-## Module overview
-
-- cmd/hexai: CLI binary that parses flags, prints version via `internal.Version`,
- and delegates to `internal/hexaicli.Run`.
-- cmd/hexai-lsp: LSP server binary that parses flags, prints version, and calls
- `internal/hexailsp.Run` (stdio JSON‑RPC server).
-- internal/hexaicli: CLI flow — reads stdin/args, loads config, builds an LLM
- client, constructs messages, and runs a single chat request (streaming when
- supported).
-- internal/hexailsp: LSP orchestration — binds logging, loads config, builds the
- LLM client, constructs `internal/lsp.ServerOptions`, and runs the server.
-- internal/lsp: Minimal LSP over stdio — document store, JSON‑RPC handlers
- (initialize, completion, code action, etc.), context building, and a small
- completion cache.
-- internal/llm: Provider‑agnostic client interface plus concrete providers for
- OpenAI, GitHub Copilot, and Ollama, including streaming support where
- available.
-- internal/appconfig: Loads user configuration from file and environment, shared
- by both CLI and LSP paths.
-- internal/logging: Central logger binding and small helpers for consistent,
- readable logs and chat summaries.
-- internal/version.go: Single place for the version string used by both
- binaries.
-
-## Typical flows
-
-- CLI: `cmd/hexai` → `internal/hexaicli` → `internal/appconfig` → `internal/llm`
- (providers) → print output and a short summary line.
-- LSP: `cmd/hexai-lsp` → `internal/hexailsp` → `internal/lsp.Server` →
- request handlers → `internal/llm` for completions/actions.
diff --git a/docs/testing.md b/docs/testing.md
deleted file mode 100644
index 86d88b1..0000000
--- a/docs/testing.md
+++ /dev/null
@@ -1,30 +0,0 @@
-# Testing Guide
-
-This repository includes a growing test suite designed to be realistic and robust.
-
-Key patterns:
-
-- Table‑driven tests: consolidate repetitive scenarios into concise tables (see `internal/lsp/*_table_test.go`).
-- Shared fixtures: use `internal/testutil/fixtures.go` for multi‑line docblocks, chat replies, function suggestions, and markdown fences.
-- Provider mocks: use `httptest.Server` and/or custom `http.RoundTripper` to simulate OpenAI/Copilot/Ollama responses, including success, stream (SSE), and error cases.
-- E2E LSP tests: capture JSON‑RPC frames from the in‑memory server (`captureResponse`, `captureRequest`) and validate code actions, resolves, and chat edits.
-
-Suggested additions:
-
-- Expand table‑driven coverage for completion edit computations and label/filter selection.
-- Add more negative tests (malformed SSE/JSON payloads) to assert robust error handling.
-
-## Running Tests
-
-- Full suite with coverage:
- - `HEXAI_TEST_SKIP_NET=1 go test ./... -cover`
- - The `HEXAI_TEST_SKIP_NET=1` env var disables any tests that require network access, keeping runs deterministic in CI/sandboxes.
-
-- Package-specific runs:
- - `HEXAI_TEST_SKIP_NET=1 go test ./internal/hexaiaction -cover`
- - `HEXAI_TEST_SKIP_NET=1 go test ./internal/hexaiaction -cover`
-
-Notes
-
-- Some environments restrict writes to the Go build cache; if you see cache permission errors, re-run in a less-restricted shell or allow the command to write to the cache.
-- Always format Go code before committing: `gofumpt -w .`
diff --git a/docs/usage.md b/docs/usage.md
index 05d6c55..fb65596 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -105,7 +105,7 @@ hexai 'install ripgrep on macOS and explain'
## Hexai Action (TUI)
-`hexai-action` runs code actions over a selection or diagnostics+selection piped from stdin, or read from a file.
+`hexai-tmux-action` runs code actions over a selection or diagnostics+selection piped from stdin, or read from a file.
- Choose an action with arrow keys, `j/k`, `g/G`, Enter, or hotkeys `[s] [r] [c] [t]`.
- Output is written to stdout by default, or to a file via `--outfile`.
@@ -122,11 +122,11 @@ Examples
```sh
# From stdin
-cat input.go | hexai-action
+cat input.go | hexai-tmux-action
# From file to file
-hexai-action --infile input.go --outfile output.go
+hexai-tmux-action --infile input.go --outfile output.go
# Using shell redirection
-hexai-action < input.go > output.go
+hexai-tmux-action < input.go > output.go
```