iris-context/docs/development.md

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:

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:

just reload

Running tests

Run the full automated test suite without cache to verify system integrity before submitting code:

go test -v -count=1 ./...

OR

just test

OR using my own test analyzer script

just ana

Running linters

Ensure zero linting errors across the codebase:

golangci-lint run ./...
go vet ./...

OR

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