Korean IME Typo Fix / 한글 IME 오타 자동 교정

터미널에서 한글 입력 상태로 명령어를 실수로 입력했을 때 자동으로 영문 명령어로 교정해줍니다.
Automatically corrects Korean IME typos in terminal commands — no more 햣 when you meant git.

---

동작 원리 / How It Works

두벌식 표준 키보드에서 영문 모드 대신 한글 모드로 명령어를 입력하면, 각 키는 한글 자모로 입력됩니다.
이 플러그인은 입력된 한글 문자열을 두벌식 역변환 테이블을 통해 원래 영문 키 시퀀스로 복원합니다.

When typing commands with Korean IME active, each keystroke produces a Korean character instead of the intended English letter. This plugin reverse-maps Korean syllables and jamo back to the original English keystrokes using the Dubeolsik (두벌식) standard layout table.

변환 예시 / Conversion Examples

입력 (Korean)	출력 (English)	설명
햣	git	g→ㅎ, i→ㅏ, t→ㅅ → 합자 햣
인	ls	l→ㅇ, s→ㄴ → 합자 인
ㅊㅇ	cd	c→ㅊ, d→ㅇ (낱자)
우에으	npm	n→ㅜ, p→ㅔ, m→ㅡ
햣 헤ㅇㅇ	git add	명령어+인자 모두 교정
ㅔ쟝	pwd	낱자+합자 혼합
ㄴㄴㅎ	ssh	낱자 자음만으로 구성

흐름도 / Flow

사용자 입력 → 한글 포함 여부 확인 → 두벌식 역변환 → 알려진 명령어 목록 대조 → 교정 또는 원본 실행

---

지원 환경 / Supported Environments

환경	버전	상태
PowerShell (Windows)	5.1+	✅
PowerShell 7+ (cross-platform)	7.0+	✅
zsh (macOS)	5.0+	✅
zsh (WSL / Linux)	5.0+	✅
Oh My Zsh	any	✅
bash	—	❌ (미지원)

---

설치 방법 / Installation

PowerShell

방법 A: 모듈 설치 (권장) / Method A: Module Install (Recommended)

로컬 저장소를 클론한 경우:

git clone https://github.com/yourname/korean-ime-fix.git
cd korean-ime-fix
.\scripts\install.ps1 -FromLocal

GitHub에서 직접 설치:

.\scripts\install.ps1

설치 후 현재 세션에 즉시 적용:

Import-Module KoreanImeTypoFix

새 PowerShell 창을 열면 자동으로 로드됩니다 (프로파일에 자동 추가됨).

---

방법 B: 프로파일에 직접 추가 / Method B: Direct Profile Source

# 프로파일 열기
notepad $PROFILE

# 또는 VS Code로
code $PROFILE

프로파일에 아래 줄 추가:

Import-Module "C:\path\to\korean-ime-fix\src\powershell\KoreanImeTypoFix\KoreanImeTypoFix.psm1"

---

zsh / WSL / macOS

git clone https://github.com/yourname/korean-ime-fix.git
cd korean-ime-fix
chmod +x scripts/install.sh
./scripts/install.sh

설치 후 적용:

source ~/.zshrc

또는 수동 설치:

mkdir -p ~/.zsh/korean-ime-fix
cp src/zsh/korean-ime-fix/dubeolsik.py ~/.zsh/korean-ime-fix/
cp src/zsh/korean-ime-fix/korean-ime-fix.plugin.zsh ~/.zsh/korean-ime-fix/
echo 'source ~/.zsh/korean-ime-fix/korean-ime-fix.plugin.zsh' >> ~/.zshrc
source ~/.zshrc

---

Oh My Zsh

# 커스텀 플러그인 디렉토리에 복사
mkdir -p "${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/korean-ime-fix"
cp src/zsh/korean-ime-fix/* "${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/korean-ime-fix/"

# .zshrc의 plugins 배열에 추가
# plugins=(git zsh-autosuggestions korean-ime-fix)

~/.zshrc의 plugins=(...) 항목에 korean-ime-fix를 추가한 후:

source ~/.zshrc

---

사용법 / Usage

설치 후 별도 조작 없이 자동으로 동작합니다.
한글 입력 상태에서 명령어를 입력하고 Enter를 누르면:

$ 햣 헤ㅇㅇ
  ↳ IME 교정: git add
[git add 실행됨]

$ 인 -ㅣk
  ↳ IME 교정: ls -la
[ls -la 실행됨]

$ 안녕하세요
[교정 없이 원본 실행 — 알려진 명령어 아님]

알려진 명령어 목록에 없는 한글 입력은 그대로 실행되어 기존 동작을 방해하지 않습니다.

---

명령어 추가하기 / Adding Custom Commands

PowerShell

KoreanImeTypoFix.psm1에서 $script:KnownCommands 초기화 블록에 명령어를 추가하거나,
모듈 로드 후 런타임에 추가할 수 있습니다:

# 런타임에 추가 (세션 한정)
# 모듈 내부 변수에 직접 접근하려면 psm1을 수정하세요

# psm1 파일의 KnownCommands 배열에 추가:
'mycli','mytool'

KoreanImeTypoFix.psm1 파일의 명령어 목록 섹션에 직접 추가하는 방법:

# KoreanImeTypoFix.psm1 내 목록에 추가
@(
    # ... 기존 명령어 ...
    'mycli', 'mytool', 'myapp'
) | ForEach-Object { $null = $script:KnownCommands.Add($_) }

zsh

korean-ime-fix.plugin.zsh의 for _cmd in \ 루프에 명령어를 추가:

for _cmd in \
    # ... 기존 명령어 ...
    mycli mytool myapp; do
    _KIMF_COMMANDS[$_cmd]=1
done

---

비활성화 방법 / How to Disable

PowerShell

임시 비활성화 (현재 세션):

Remove-Module KoreanImeTypoFix

영구 비활성화: $PROFILE에서 Import-Module KoreanImeTypoFix 줄을 제거하거나 주석 처리합니다.

# Import-Module KoreanImeTypoFix

zsh

임시 비활성화:

bindkey '^M' accept-line
bindkey '^J' accept-line

영구 비활성화: ~/.zshrc에서 source ... korean-ime-fix.plugin.zsh 줄을 제거합니다.

---

테스트 실행 / Running Tests

Python 테스트 (두벌식 변환 엔진)

# pytest 설치 (필요한 경우)
pip install pytest

# 테스트 실행
cd korean-ime-fix
python -m pytest tests/test_dubeolsik.py -v

예상 출력:

tests/test_dubeolsik.py::TestConvert::test_git PASSED
tests/test_dubeolsik.py::TestConvert::test_ls PASSED
tests/test_dubeolsik.py::TestConvert::test_cd_jamo PASSED
...
tests/test_dubeolsik.py::TestHasKorean::test_korean_syllable PASSED
...
15 passed in 0.XXs

PowerShell 테스트 (Pester)

# Pester 설치 (필요한 경우)
Install-Module Pester -Force -Scope CurrentUser

# 테스트 실행
cd korean-ime-fix
Invoke-Pester tests\KoreanImeTypoFix.Tests.ps1 -Output Detailed

---

트러블슈팅 / Troubleshooting

PowerShell

Q: Import-Module KoreanImeTypoFix 시 PSReadLine 오류가 발생합니다.

A: PSReadLine 모듈이 설치되어 있어야 합니다.

Install-Module PSReadLine -Force -Scope CurrentUser

---

Q: Enter 키가 동작하지 않거나 이중 실행됩니다.

A: 다른 모듈이 Enter 키 핸들러를 덮어썼을 수 있습니다. 모듈 로드 순서를 확인하세요.

# 핸들러 재등록
Remove-Module KoreanImeTypoFix
Import-Module KoreanImeTypoFix

---

Q: 한글이 포함된 명령어인데 교정되지 않습니다.

A: 해당 명령어가 알려진 명령어 목록에 없을 수 있습니다. 명령어 추가하기 섹션을 참고하세요.

---

zsh

Q: python3 또는 python을 찾을 수 없다는 오류가 납니다.

A: Python 3이 설치되어 있어야 합니다.

# macOS
brew install python3

# Ubuntu/Debian
sudo apt install python3

# 설치 확인
python3 --version

---

Q: WSL에서 한글 입력이 제대로 전달되지 않습니다.

A: 터미널 에뮬레이터(Windows Terminal, iTerm2 등)의 인코딩이 UTF-8로 설정되어 있는지 확인하세요.
LANG 환경변수도 확인합니다:

echo $LANG
# ko_KR.UTF-8 또는 en_US.UTF-8 이어야 함
export LANG=en_US.UTF-8

---

Q: zsh에서 Enter 후 명령어가 두 번 실행됩니다.

A: .zshrc에 bindkey '^M' accept-line이 중복 선언되어 있을 수 있습니다. 확인 후 제거하세요.

---

기여하기 / Contributing

1. 이 저장소를 Fork합니다.
2. 기능 브랜치를 생성합니다: git checkout -b feature/my-feature
3. 변경사항을 커밋합니다: git commit -m 'feat: add my feature'
4. 브랜치에 Push합니다: git push origin feature/my-feature
5. Pull Request를 생성합니다.

기여 시 다음을 확인해주세요:

• Python 테스트 모두 통과: python -m pytest tests/ -v
• PowerShell 테스트 모두 통과: Invoke-Pester tests\KoreanImeTypoFix.Tests.ps1
• 새 명령어 매핑 추가 시 테스트 케이스도 함께 추가

---

라이선스 / License

MIT License — 자유롭게 사용, 수정, 배포하세요.
See LICENSE for details.