# Omarchy Keyguide

[English](README.md) · [한국어](README.ko.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [Español](README.es.md)

> 공개 저장소: <https://github.com/mrai125kr/omarchy-keyguide>

![Omarchy Keyguide 설정과 실시간 HUD 미리보기](preview.png)

Omarchy Keyguide는 현재 사용할 수 있는 단축키를 입력을 방해하지 않는 HUD로
보여 주고, 안전한 범위 안에서 단축키를 등록·변경·제거할 수 있게 해 주는
Omarchy용 플러그인입니다.

## 목적과 대상 사용자

Keyguide의 목적은 Omarchy를 처음 사용하는 사람이 많은 단축키를 외우지 않아도
현재 키 조합으로 무엇을 할 수 있는지 바로 알 수 있게 하는 것입니다. 숙련된
사용자에게도 현재 PC에 실제로 적용된 단축키와 설치된 프로그램을 빠르게 검색하는
도구가 됩니다.

다음과 같은 상황에 사용할 수 있습니다.

- `Super` 조합을 누른 상태에서 현재 실행 가능한 단축키 확인
- 영어 또는 선택한 언어로 일반 액션 검색
- 설치된 그래픽 프로그램과 실행 명령을 한 검색창에서 찾기
- 지원되는 단축키를 충돌 검사와 함께 이동·교체·제거·복원
- HUD 위치, 크기, 투명도, 테마 연동과 표시 항목 조정

Keyguide는 매크로 녹화기나 제한 없는 Hyprland 설정 편집기가 아닙니다. 안전하게
재구성하고 결과를 검증할 수 있는 액션만 변경하도록 의도적으로 범위를 제한합니다.

## 주요 기능

- HUD 위치, 크기, 투명도, 테마 연동, 표시 그룹과 개별 행 설정
- 영어(기본), 한국어, 일본어, 중국어 간체, 스페인어 설정창과 HUD
- 빈 키는 중앙 팝업에서 등록하고 기존 키는 해당 행 옆에서 변경하거나 제거
- 일반 액션·설치된 프로그램·명령을 한 검색창에서 검색
- 프로그램 아이콘 표시와 명령의 `(CMD)` 구분
- 영어와 선택한 언어를 모두 사용하는 일반 액션 검색
- 설치·제거된 프로그램을 선택창이 열린 동안 자동 갱신
- 숨겨진 Hyprland 런타임 바인딩까지 포함하는 중복 검사
- 충돌·동시 변경·재로드 오류 시 이전 상태로 정확히 롤백
- Keyguide가 이동한 원래 단축키와 새로 만든 단축키를 `모두 초기화`로 복원

## 요구 사항과 호환성

대상 환경은 Omarchy `4.0.0-1`, Hyprland `0.56.2` 이상입니다. 표준 Omarchy
환경 외에 Python 3, `xkbcli`, 읽을 수 있는 키보드 이벤트 장치가 필요합니다.
소스 또는 Git 플러그인으로 처음 설치할 때는 C 컴파일러가 필요하며 Arch Linux의
`base-devel`로 준비할 수 있습니다.

저장소 루트에서 다음 명령으로 현재 PC의 호환성을 확인합니다.

```sh
PYTHONPATH=src/backend python -m keyguide_backend compat
```

명령은 감지한 버전, 키보드 이벤트 장치 사용 가능 여부와 오류 원인을 JSON으로
표시합니다. 지원되지 않는 환경에서는 0이 아닌 종료 코드를 반환합니다.

Linux는 기본적으로 키보드와 포인터 이벤트 장치를 보호합니다. 저장소를 복제하거나
플러그인을 추가한 뒤 저장소 디렉터리에서 입력 접근을 한 번 설정하세요.

```sh
sudo make install-input-access
omarchy restart shell
```

이 명령은 systemd-logind의 `uaccess` 방식을 사용하는 udev 규칙 하나를 설치합니다.
계정을 광범위하고 영구적인 `input` 그룹에 넣지 않고, 현재 활성 로컬 세션에만
키보드·마우스·터치패드 이벤트 장치 접근을 허용합니다. 이 ACL은 Keyguide
프로세스만이 아니라 활성 세션의 사용자 계정에 부여되므로, 권한이 유지되는 동안
같은 사용자로 실행되는 다른 프로세스도 선택된 이벤트 장치를 읽을 수 있습니다.
나중에 해제하려면 저장소가 남아 있을 때 `sudo make uninstall-input-access`를 실행한
뒤 Shell을 다시 시작하세요.

## 설치와 사용

### Omarchy Git 플러그인으로 설치 — 권장

```sh
omarchy plugin add https://github.com/mrai125kr/omarchy-keyguide.git --enable
```

처음 활성화할 때 저장소에 포함된 C 소스로 작은 입력 관찰기를 컴파일하므로 잠시
걸릴 수 있습니다. 외부에서 실행 파일을 내려받지 않습니다. Keyguide 아이콘이
상단 바에 나타나면 아이콘을 눌러 빠른 설정 또는 전체 설정창을 열 수 있습니다.

### 처음 사용하기

1. 상단 바의 Keyguide 아이콘에서 전체 설정을 엽니다.
2. 표시 언어를 선택합니다. 기본값은 영어이며 한국어·일본어·중국어 간체·
   스페인어를 선택할 수 있습니다.
3. HUD 위치, 크기, 투명도, 테마 연동과 표시할 수정 키 그룹을 정합니다.
4. `Super` 또는 `Super`와 Ctrl·Shift·Alt 조합을 누른 상태로 유지하면 그 조합에서
   현재 사용할 수 있는 단축키가 표시됩니다.
5. 단축키 편집에서 빈 키를 선택하면 등록창이 중앙에 열립니다. 기존 항목의
   `변경`을 누르면 해당 행 가까이에 편집창이 열리고, `제거`를 누르면 그 키가
   빈 키가 됩니다.
6. `모두 초기화`는 복원 가능한 원래 단축키를 되돌리고 Keyguide가 새로 만든
   단축키를 제거합니다. 관련 없는 Omarchy 설정은 초기화하지 않습니다.

### 단축키 액션 검색과 등록

한 검색창에서 일반 액션, 설치된 프로그램, 실행 명령을 찾을 수 있습니다. 일반
액션은 영어와 선택한 언어 모두로 검색됩니다. 프로그램에는 데스크톱 아이콘이
표시되고 명령에는 `(CMD)`가 표시됩니다. 명령을 선택한 경우에만 선택 인수를
입력할 수 있습니다.

기존 액션을 다른 키에 등록하면 같은 액션을 복제하지 않고 현재 키에서 새 키로
이동합니다. 이미 할당된 키를 교체할 때는 제거될 액션 이름을 보여 주고 한 번 더
확인합니다. 안전하게 재구성할 수 없는 액션은 이유와 함께 읽기 전용으로 남습니다.

### 업데이트

```sh
omarchy plugin update mrai.keyguide --yes
```

Omarchy는 변경 내용을 확인하고 빠른 전달 방식으로 업데이트합니다. 로컬에서
플러그인 파일을 수정해 업데이트할 수 없는 경우에는 먼저 해당 변경을 보관하거나
검토해야 합니다.

### 제거

```sh
omarchy plugin remove mrai.keyguide
```

Git 플러그인 제거는 저장소 안에서 생성된 빌드 결과도 함께 제거합니다. Keyguide의
표시 설정과 독립적으로 관리되는 단축키 모듈은 기본적으로 남겨 두어 재설치나
업데이트 시 선택을 보존합니다.

### 소스에서 설치·제거

```sh
make test
make install
```

이미 설치된 Keyguide를 사용자 셸 설정을 보존하면서 갱신하려면 다음 명령을
사용합니다.

```sh
PRESERVE_USER_SHELL=1 make install
```

설치 기록에 포함된 파일만 안전하게 제거하려면 다음 명령을 사용합니다.

```sh
make uninstall
```

Keyguide가 관리한 단축키와 표시 설정까지 초기화한 뒤 제거하려면 의도를 명시해야
합니다.

```sh
REMOVE_PREFERENCES=1 make uninstall
```

## 안전성과 개인정보

- 입력 관찰기는 키를 잡거나 소비하거나 다시 보내지 않으며 키 입력을 기록하지
  않습니다.
- Keyguide는 `~/.config/hypr/bindings.lua`를 수정하지 않습니다.
- 사용자가 단축키 변경을 확인한 경우에만 전용 생성 모듈을 변경합니다.
- 저장 전, Hyprland 재로드 후, 실제 런타임 결과까지 중복과 일치 여부를 확인합니다.
- 오류가 발생하면 변경 전 파일 바이트로 되돌리고 부분 설정을 남기지 않습니다.
- 비밀번호, API 토큰, 계정 정보나 네트워크 데이터를 수집하거나 저장하지 않습니다.
- 제거 프로그램은 인증된 설치 기록 밖의 파일이나 별도 사용자 변경을 삭제하지
  않습니다.

단축키 변경은
`~/.local/state/omarchy/toggles/hypr/omarchy-keyguide.lua`에 저장되고 HUD 표시
설정은 `~/.local/share/omarchy-keyguide/settings.json`에 저장됩니다.

## 문제 해결

- 먼저 위의 호환성 검사 명령을 실행해 오류 원인을 확인합니다.
- 컴파일러가 없으면 `omarchy pkg add base-devel`을 실행한 뒤 다시 설치하거나
  업데이트합니다.
- HUD가 키 누름을 감지하지 못하면 호환성 결과에서 읽을 수 있는 키보드 이벤트
  장치가 있는지 확인합니다.
- 설치됐지만 UI가 나타나지 않으면 `omarchy restart shell`을 실행하고 다시
  확인합니다.
- 내려받은 소스의 플러그인 구조는 `omarchy plugin validate .`로 검증합니다.
- 중복 키, 모호한 액션, 지원하지 않는 키 또는 작업 중 외부 설정 변경은 저장하지
  않고 화면에 이유를 표시합니다.

## 개발과 검증

```sh
make test
make build
```

`make test`는 비파괴 자동 검증을 실행하고 `make build`는 입력 관찰기 빌드와
Python 백엔드 컴파일 검사를 실행합니다.

GitHub Actions에서는 `make test-ci`로 이식 가능한 C·Python·셸 문법·안전성 검사를
실행합니다. QML과 플러그인 검증 하네스에는 실제 Omarchy/Quickshell 환경이 필요하므로,
릴리스 전에는 지원되는 Omarchy PC에서 전체 `make test`도 실행해야 합니다.

## 라이선스

MIT 라이선스입니다. 자세한 내용은 [LICENSE](LICENSE)와 [NOTICE](NOTICE)를
참조하세요.