docs: update guidelines for new user and developer (#16)

- Remove old docs 1ff2546f63b8eac799dcd70374258c0075380726 - Update guidelines for new user - Update docs for development ---------
2026-07-02 16:54:03 +07:00
parent 8f89c15e72
commit b9cec2b3ac
9 changed files with 334 additions and 261 deletions
@@ -0,0 +1,111 @@
+# 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`