From 24fddaccfef8302a7850434f3ddebe5a0d2d8015 Mon Sep 17 00:00:00 2001 From: VERSE Date: Fri, 3 Jul 2026 11:37:20 +0700 Subject: [PATCH] docs: introducing to iris (#11) --- .github/CODE_OF_CONDUCT.md | 6 ++ .github/CONTRIBUTING.md | 63 ++++++++++++++ .github/SECURITY.md | 3 + .github/workflows/release.yml | 2 +- README.md | 155 ++++++++++++++++++++++++++++++++++ docs/README.md | 6 ++ scripts/install.sh | 34 ++++++-- 7 files changed, 260 insertions(+), 9 deletions(-) create mode 100644 .github/CODE_OF_CONDUCT.md create mode 100644 .github/CONTRIBUTING.md create mode 100644 .github/SECURITY.md create mode 100644 README.md diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..14e78a0 --- /dev/null +++ b/.github/CODE_OF_CONDUCT.md @@ -0,0 +1,6 @@ +# Code of Conduct + +- Just be nice +- Be helpful +- You can use AI but just don't use it to produce slop code that no one needs +- Or use AI or yourself changing any information from README, contributing, security, issue template, license, ... diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..501684d --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,63 @@ +# Contributing to IRIS + +Thank you for your interest in IRIS. We welcome community contributions and appreciate your time and effort in helping improve the project. Before getting started, please take a moment to review these guidelines. + +Need to contact? Reach out to my Telegram [@VerseNilVis](t.me/VerseNilVis). + +## 1. How to Contribute + +We welcome contributions in various forms, including: + +- Add more features +- Bug fixes +- Documentation improvements +- Tests and performance optimizations + +To contribute, follow these steps: + +- **Fork** the repository and create a new branch. +- **Make your changes**, ensuring they align with our coding standards (§4 below). +- **Run tests** to ensure your changes do not break existing functionality. +- **Submit a pull request (PR)** with a clear description of the changes. +- Another maintainer or I will review your PR, suggest any necessary changes, and merge it once approved. + +### Commit Messages + +Use clear and descriptive commit messages. Follow the conventional commit format when possible: + ++ chore(commands): add more commands ++ fix(overlay): extra left border ++ docs(lookup): update lookup docs + +## 2. Legal Terms + +By submitting a contribution, you represent and warrant that: + +- It is your original work, or you have sufficient rights to submit it. +- You grant the IRIS maintainers and users the right to use, modify, and distribute it under the 0BSD license (see LICENSE file) +- To the extent your contribution is covered by patents, you grant a perpetual, worldwide, non-exclusive, royalty-free, irrevocable license to the IRIS maintainers and users to make, use, sell, offer for sale, import, and otherwise transfer your contribution as part of the project. + +We do not require a Contributor License Agreement (CLA). However, by contributing, you agree to license your submission under terms compatible with the 0BSD License and to grant the patent rights described above. If your contribution includes third-party code, you are responsible for ensuring it is 0BSD-compatible and properly attributed. + +Where permitted by law, you waive any moral rights in your contribution (e.g., the right to object to modifications). If such rights cannot be waived, you agree not to assert them in a way that interferes with the project’s use of your contribution. + +## 3. Coding Standards + +To maintain a consistent codebase, please follow these guidelines: + +- Use the existing coding style and conventions. +- Ensure all code changes are well-documented. +- Write tests for new features and bug fixes. +- Avoid introducing unnecessary dependencies. + +## 4. Reporting Issues + +If you find a bug or have a feature request, please open an issue and provide as much detail as possible: + +- Steps to reproduce, including operating system, and IRIS version +- Expected and actual behavior +- Suspected cause (if any) + +## 5. Recognition + +We use the All Contributors specification to recognize community members. If your contribution is merged, you will be added to the project's list of contributors. This includes contributions of all kinds—code, documentation, design, testing, and more. diff --git a/.github/SECURITY.md b/.github/SECURITY.md new file mode 100644 index 0000000..7695eef --- /dev/null +++ b/.github/SECURITY.md @@ -0,0 +1,3 @@ +# Security Policy + +If you believe you've found a security vulnerability in this project, please report it to us via: versedev.store@proton.me diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 4ede34a..e2af1c6 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -76,7 +76,7 @@ jobs: echo "" >> $GITHUB_ENV echo "## Installation" >> $GITHUB_ENV echo "\`\`\`bash" >> $GITHUB_ENV - echo "curl -sS https://raw.githubusercontent.com/versenilvis/iris/main/scripts/install.sh | sudo sh" >> $GITHUB_ENV + echo "curl -sS https://raw.githubusercontent.com/versenilvis/iris/main/scripts/install.sh | sh" >> $GITHUB_ENV echo "\`\`\`" >> $GITHUB_ENV echo "EOF" >> $GITHUB_ENV env: diff --git a/README.md b/README.md new file mode 100644 index 0000000..2950f0c --- /dev/null +++ b/README.md @@ -0,0 +1,155 @@ +
+ + + logo + + +

IRIS (Intelligent Real-time Input Suggestion) - A shell auto-completion tool that works like code editor's IntelliSense

+ + [![GitHub Actions](https://img.shields.io/github/actions/workflow/status/versenilvis/IRIS/release.yml?branch=main&style=for-the-badge&logo=github&logoColor=white&label=Actions)](https://github.com/versenilvis/IRIS/actions/workflows/release.yml) + [![License: 0BSD](https://img.shields.io/badge/License-0BSD-blue?style=for-the-badge&logo=github&logoColor=white)](./LICENSE) + + Comparison · Installation · Docs · Shortcuts · Reporting bugs + +
+
+ + + showcase +
+ +**IRIS is built on top of TTY, so it runs everywhere. It just needs a terminal!** + +Run iris wherever you already work; your local machine, a remote server, or anywhere you can ssh. Each suggestion menu renders directly inline inside your real terminal session, not an app's imitation of one, so it never breaks full-screen TUIs or terminal formatting. Automatically index your aliases and shell history to suggest commands that match your actual workflow in real time. Change configurations and propagate them instantly without restarting your shell. One single local native Go binary, not an app: no gui, no electron, no mac-only wrapper, no account, no telemetry. (if you've used fig: it's that, rebuilt to run purely on TTY) + + + + +## Why Iris instead of Fig + +> [!IMPORTANT] +> **[Fig](https://app.fig.io/) was officially sunset in September 2024 and migrated to Amazon Q Developer (which requires cloud authentication and proprietary bloat)** +> **IRIS is the lightweight, open-source, zero-telemetry alternative built purely on native Go and TTY with no accounts, no GUI app, and no background daemons required** + +### How it compares + +| Feature | Iris | Fig | +| :-------------------------- | :------------------- | :--------------- | +| **Platforms** | Linux, macOS | macOS only | +| **Engine** | Native Go (TTY) | Electron | +| **Startup** | Near-zero overhead | Low overhead | +| **UI** | Inline overlay | GUI popover | +| **Remote SSH** | TTY-native, portable | macOS GUI-bound | +| **Tmux** | ✓ | Limited | +| **Linux virtual terminals** | ✓ | - | +| **Memory** | < 15 MB | Electron runtime | + +## Why not shell autocomplete plugins? + +Shell plugins are great, but they also come with trade-offs. And also, not everyone use Zsh or Fish especially on SSH. + +| Feature | Iris | Shell plugins | +| :-------------------------- | :---------------------- | :--------------------------- | +| **Installation** | Single binary | Plugin manager required | +| **Shell support** | Most shells supported | Usually shell-specific | +| **Startup** | No shell initialization | Increases shell startup time | +| **SSH** | One config | Per-shell config | +| **Tmux** | ✓ | Depends on the shell | +| **Linux virtual terminals** | ✓ | Depends on the shell | + +## Installation + +```bash +curl -sSL https://raw.githubusercontent.com/versenilvis/iris/main/scripts/install.sh | sh +``` + +> [!WARNING] +> Currently, Windows is not supported + +## Theme +> [!NOTE] +> Currently, IRIS doesn't have custom theme but it does have 2 basic styles + + + + + + + + + + + + + + +
Modern styleClassic style
specspec
historyhistory
+ +## Docs + +- [Getting started](./docs/README.md#getting-started): dependencies, installation methods, and shell integration setup +- [Usage guide](./docs/README.md#usage-guide): core navigation, mode switching, instant alias expansion, and ghost text +- [Configuration guide](./docs/README.md#configuration-guide): TOML configuration file structure, settings sections, and CLI commands +- [Troubleshooting guide](./docs/README.md#troubleshooting-guide): debug mode, runtime log inspection, and common solutions +- [Developer guide](./docs/development.md): system architecture overview, PTY bridge mechanics, and contribution instructions + +## Shortcuts + +| Shortcut | Action | Description | +| :--------------------------------- | :---------------------- | :------------------------------------------------------------------------ | +| Shift + Tab | Toggle menu | Show or hide the suggestion menu. | +| Esc | Hide menu | Temporarily hide the menu until the next key press. | +| Tab | Accept suggestion | Insert the currently selected suggestion into the prompt. | +| Enter | Execute command | Close the menu and send the current command to the shell. | +| ↑ | Navigate up / history | Move the selection up, or open command history when the prompt is empty. | +| ↓ | Navigate down / history | Move the selection down, or open command history when the prompt is empty. | +| → | Accept ghost text | Accept the faded ghost text suggestion when the menu is open. | +| ← / → | Move cursor | Move the cursor inside the input buffer. Disabled when the prompt is empty. | +| Ctrl + R | Switch mode | Toggle between `spec` and `history` mode. | +| Ctrl + A | Beginning of line | Move the cursor to the start of the command line. | +| Ctrl + E | End of line | Move the cursor to the end of the command line. | +| Ctrl + L | Clear screen | Clear the terminal while preserving the input buffer and redrawing the menu. | +| Ctrl + U | Clear command | Remove the entire current command and close the menu. | +| Ctrl + C | Cancel command | Send `SIGINT`, clear the input buffer, and close the menu. | +| Ctrl + W | Delete word | Delete the word immediately before the cursor. | + +> [!NOTE] +> With Ctrl + A, Ctrl + E, Ctrl + W, Ctrl + U, Ctrl + L, and Ctrl + C: they belong to your shell by default. IRIS handles them directly in raw mode so your cursor and menu stay in sync + +## Reporting bugs +> [!NOTE] +> Describing the bug you are facing, along with the relevant log +> Enabling debug mode and then performing actions that led to the error + +Run IRIS with debug mode: +```bash +iris -d +``` +or `config.toml`: +```toml +debug=true +``` + +> [!IMPORTANT] +> **Since IRIS logs everything you type, you should only enable debug mode when you need to report bugs** + +## License + +This project is licensed under the [0BSD License](LICENSE) - no strings attached. Meaning you can do whatever you want with it. + +For those who fork it and want to publish a new version or something else; if you can, a credit or co-author mention is always welcome :) (though never required). + +Thank you! + +## Feedback + +I'd love to hear your feedback + +Feel free to reach out via: +* [Email](mailto:versedev.store@proton.me) +* [Twitter](https://twitter.com/versenilvis) +* [GitHub issues](https://github.com/versenilvis/iris/issues/new) diff --git a/docs/README.md b/docs/README.md index ea6ce64..81e1517 100644 --- a/docs/README.md +++ b/docs/README.md @@ -151,6 +151,12 @@ mode = "last" debug = false [ui] +# visual style: "modern" (icons, category pills, shortcut footer) or "classic" (minimalist, centered number, no icons) +style = "modern" + +# enable Nerd Fonts icons in overlay menu +nerd-fonts = true + # enable inline ghost text ghost-text = true diff --git a/scripts/install.sh b/scripts/install.sh index 6840619..333e4f1 100755 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -49,18 +49,36 @@ main() { bin=$(find . -name "iris" -type f | head -1) [ -z "$bin" ] && err "Binary not found in archive" - mkdir -p "${BIN_DIR}" - cp "$bin" "${BIN_DIR}/iris" - chmod +x "${BIN_DIR}/iris" - - echo "" - echo "Installed iris to ${BIN_DIR}/iris" - echo "" + # check if we have write permission to the install directory + has_write_permission=0 + if [ -d "${BIN_DIR}" ]; then + if [ -w "${BIN_DIR}" ]; then + has_write_permission=1 + fi + else + parent_dir=$(dirname "${BIN_DIR}") + if [ -w "${parent_dir}" ]; then + has_write_permission=1 + fi + fi if "${BIN_DIR}/iris" version >/dev/null 2>&1; then echo "Installation verified." else - echo "Warning: could not verify binary" + chmod +x "$bin" + if "$bin" version >/dev/null 2>&1; then + echo "Binary verification successful." + else + echo "Warning: could not verify binary" + fi + + cp "$bin" "/tmp/iris" + chmod +x "/tmp/iris" + + echo "" + echo "Warning: permission denied to write to ${BIN_DIR}" + echo "Please complete the installation by running:" + echo " sudo cp /tmp/iris ${BIN_DIR}/iris && sudo chmod +x ${BIN_DIR}/iris" fi echo ""