VERSE
b9cec2b3ac
- Remove old docs 1ff2546f63b8eac799dcd70374258c0075380726 - Update guidelines for new user - Update docs for development ---------
112 lines
4.9 KiB
Markdown
112 lines
4.9 KiB
Markdown
# Development guide
|
|
|
|
This document outlines the architectural principles, development workflow, and mandatory coding conventions for contributors working on the Iris codebase
|
|
|
|
## Architecture overview
|
|
|
|
Iris functions as a transparent pseudoterminal (PTY) bridge sitting between the user terminal emulator and the underlying interactive shell (`zsh`, `bash`, or `fish`)
|
|
|
|
- PTY Bridge (`root/wrapper.go`): Intercepts keystrokes in raw mode, tracks typed queries, manages shell input/output buffers, and handles escape sequences
|
|
- Overlay Rendering (`integration/overlay.go`): Computes visual character widths (`lipgloss.Width`), handles cursor column positioning, and draws floating menu boxes directly on the terminal grid
|
|
- Suggestion Engine (`root/suggestions.go`): Collects, deduplicates, and sorts command completions from static specifications and fuzzy history search
|
|
|
|
## Development workflow
|
|
|
|
### Setting up environment
|
|
|
|
Clone the repository and verify that all dependencies are synced:
|
|
|
|
```bash
|
|
git clone https://github.com/versenilvis/iris.git
|
|
cd iris
|
|
go mod tidy
|
|
```
|
|
|
|
### Building and reloading
|
|
|
|
To rapidly compile and reload your local development binary, ensure `just` is installed and run:
|
|
|
|
```bash
|
|
just reload
|
|
```
|
|
|
|
### Running tests
|
|
|
|
Run the full automated test suite without cache to verify system integrity before submitting code:
|
|
|
|
```bash
|
|
go test -v -count=1 ./...
|
|
```
|
|
|
|
OR
|
|
|
|
```bash
|
|
just test
|
|
```
|
|
|
|
OR using my own test analyzer script
|
|
```bash
|
|
just ana
|
|
```
|
|
### Running linters
|
|
|
|
Ensure zero linting errors across the codebase:
|
|
|
|
```bash
|
|
golangci-lint run ./...
|
|
go vet ./...
|
|
```
|
|
|
|
OR
|
|
|
|
```bash
|
|
just lint
|
|
```
|
|
|
|
### Some available `just` commands
|
|
|
|
We use `just` as our primary command runner. Below are common shortcuts available during development:
|
|
|
|
- `just build`: Compile standard local binary
|
|
- `just optimized-build`: Compile stripped, optimized binary
|
|
- `just reload`: Compile binary and hot-reload any currently running Iris session
|
|
- `just run`: Execute local `./iris` binary
|
|
- `just debug`: Launch `./iris -d` in debug logging mode
|
|
- `just test`: Execute full Go test suite
|
|
- `just ana`: Run custom project test analyzer script
|
|
- `just lint`: Execute static analysis and linter checks
|
|
- `just build-release <version>`: Build versioned release binary (e.g. `just build-release v1.2.0`)
|
|
|
|
## Mandatory engineering rules
|
|
|
|
Contributors must strictly adhere to the following core UI/UX and architectural principles:
|
|
|
|
### Absolute positioning for overlay rendering
|
|
|
|
- Never rely on relative cursor movements (`\033[nA` or `\033[nD`) across multi-line inputs to draw menus, as wrapping causes severe visual jitter
|
|
- Always compute absolute target columns (`targetCol = PromptLen + typedLen`) and use carriage return (`\r`) followed by horizontal positioning (`\033[targetColC`) to anchor the overlay box
|
|
|
|
### UI rules
|
|
|
|
- Stationary navigation vs dynamic typing: When navigating up or down through the menu (`↑` or `↓`), the overlay box position must remain fixed in place. When typing characters, the menu must shift dynamically along with the cursor column
|
|
- Menu hiding: When clearing the input line completely or when typing up to a completed token where no further completion exists, the overlay menu must automatically hide
|
|
- Context preservation: When moving left or right with arrow keys (`←` or `→`) or deleting characters with backspace, the engine must preserve context and re-evaluate the exact substring position to generate accurate suggestions
|
|
- Empty buffer arrow suppression: When the command line buffer is entirely empty, pressing left or right arrow keys (`←` or `→`) must not open the menu or trigger suggestions
|
|
- Temporary vs permanent dismissal: Pressing `Esc` hides the overlay menu temporarily for the current command line, whereas pressing `Shift+Tab` disables overlay suggestions permanently until toggled back on
|
|
- Non-blocking navigation and context awareness: When moving the cursor back to the start of a typed command line, cursor movement must never be blocked or frozen, and the overlay menu must dynamically preserve context relative to the cursor position
|
|
|
|
### Responsive PTY handling and non-Blocking UI
|
|
|
|
- Do not block raw PTY keystroke interception loops with long operations or arbitrary debounce timers that freeze user typing
|
|
- When handling navigation keys (up/down arrow) or mode toggles (`Ctrl+R`), update internal state synchronously and render UI feedback immediately
|
|
|
|
### Mode switching integrity
|
|
|
|
- When intercepting mode toggle keys (`Ctrl+R`), always reset navigation flags (`userNavigated = false`) and restore the original typed query buffer
|
|
- This ensures that switching from specification suggestions to history navigation reloads clean completion lists starting from index 0
|
|
|
|
### Concurrency safety
|
|
|
|
- The PTY output read loop and keystroke interception loop run asynchronously in separate goroutines
|
|
- Always use explicit synchronization (`sync.Mutex` or `sync.RWMutex`) when reading or modifying shared state variables such as `naiveBuffer`, `activeMode`, or `overlay.Items`
|