@kaydash9999/banker-plugins 0.3.0 → 0.5.0

package/skills/setup-java/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: setup-java
+description: "(banker) JDK 21 + JAVA_HOME 설치(alternatives로 java·javac 비대칭 방지, Debian은 Adoptium 전용). jdtls 등 Java LSP 전제. 'setup-java'/'JDK 설치'/'Java 21 설치' 또는 /banker:setup 시 사용."
+---
+
+# setup-java: JDK 21 + JAVA_HOME 설치
+
+Java LSP(`jdtls`) 등 Java 도구가 요구하는 JDK 21과 `JAVA_HOME`을 설치·구성한다.
+멱등(이미 21이면 skip·검증만). 답변은 한글(명령·경로는 영문).
+
+## 런타임 배선
+- **Claude Code**: `docs-setup`의 PlantUML 렌더(`java -jar plantuml.jar`)가 java 존재를 전제로 동작.
+- **Codex/OMX**: `jdtls`(Java LSP)와 Spring Boot Language Server(`java -jar ...`)가 JDK 21을 요구한다. 이를 실제로 내려받아 구동하는 별도 LSP 설치 스킬(예: setup-lsp)의 전제조건이 이 스킬이다.
+- 이 스킬은 JDK 설치·`JAVA_HOME` 확정까지만 담당하고, jdtls 자체 배포·`JDTLS_JVM_ARGS` 같은 힙 튜닝은 LSP 설치 스킬의 영역이다.
+
+## 0. 감지 (먼저, 추정 금지)
+```bash
+[ -f /etc/os-release ] && . /etc/os-release && echo "distro=$ID ${VERSION_ID}"
+command -v java  >/dev/null && java -version 2>&1 | head -1 || echo "java=미설치"
+command -v javac >/dev/null && javac -version 2>&1          || echo "javac=미설치"
+echo "JAVA_HOME=${JAVA_HOME:-미설정}"
+```
+```powershell
+$PSVersionTable.PSVersion
+if (Get-Command java -ErrorAction SilentlyContinue) { java -version } else { "java: 미설치" }
+[Environment]::GetEnvironmentVariable('JAVA_HOME','User')
+```
+
+## 1. Rocky Linux 8
+```bash
+sudo dnf install -y java-21-openjdk-devel
+JAVA21_HOME=$(dirname "$(dirname "$(readlink -f /usr/lib/jvm/java-21-openjdk*/bin/java)")")
+sudo alternatives --install /usr/bin/java  java  "$JAVA21_HOME/bin/java"  21 \
+  --slave /usr/bin/javac javac "$JAVA21_HOME/bin/javac" \
+  --slave /usr/bin/jar   jar   "$JAVA21_HOME/bin/jar"
+sudo alternatives --set java "$JAVA21_HOME/bin/java"
+export JAVA_HOME="$JAVA21_HOME"   # 아래 "rc 마커 공통"이 참조
+```
+- `--slave`로 `java`·`javac`·`jar`를 한 그룹으로 묶는 이유: 나중에 `alternatives --config java`로 버전을 바꿀 때 `javac`가 따로 놀면(비대칭) 컴파일이 엉뚱한 버전으로 실행된다.
+
+## 2. Ubuntu 20.04~24.04
+```bash
+sudo apt update
+sudo apt install -y openjdk-21-jdk || echo "openjdk-21-jdk 미제공. 아래 3. Debian의 Adoptium 블록을 그대로 적용"
+sudo update-alternatives --config java     # 여러 버전 중 21 선택(javac도 slave로 동반 전환)
+javac -version   # java와 버전 일치 확인(비대칭 점검)
+export JAVA_HOME="$(dirname "$(dirname "$(readlink -f "$(command -v javac)")")")"   # 아래 "rc 마커 공통"이 참조
+```
+
+## 3. Debian 12 (bookworm): Adoptium Temurin 전용
+⚠️ **default·backports 저장소 모두 JDK 21을 제공하지 않는다.** Adoptium 레포 추가가 유일한 경로(재확인: 배포판이 이후 21을 backport하면 이 단계는 생략 가능).
+```bash
+sudo apt-get install -y wget gnupg
+wget -qO - https://packages.adoptium.net/artifactory/api/gpg/key/public | \
+  sudo gpg --dearmor -o /usr/share/keyrings/adoptium.gpg
+echo "deb [signed-by=/usr/share/keyrings/adoptium.gpg] https://packages.adoptium.net/artifactory/deb bookworm main" | \
+  sudo tee /etc/apt/sources.list.d/adoptium.list
+sudo apt-get update
+sudo apt-get install -y temurin-21-jdk
+sudo update-alternatives --config java
+export JAVA_HOME="/usr/lib/jvm/temurin-21-jdk-$(dpkg --print-architecture)"   # amd64/arm64 자동
+```
+(Ubuntu에서 `openjdk-21-jdk`가 없을 때도 이 블록을 그대로 재사용한다.)
+
+## 4. macOS (Apple Silicon / Intel)
+```zsh
+brew install openjdk@21
+sudo ln -sfn "$(brew --prefix openjdk@21)/libexec/openjdk.jdk" \
+  /Library/Java/JavaVirtualMachines/openjdk-21.jdk   # 유일한 sudo, 1회성
+export JAVA_HOME="$(brew --prefix openjdk@21)"        # 아래 공통 rc 블록 참고
+/usr/libexec/java_home -v 21
+```
+Apple Silicon(`/opt/homebrew`)·Intel(`/usr/local`) 차이는 `brew --prefix`가 자동 흡수하므로 이 스크립트는 두 아키텍처에 동일 적용.
+
+## 5. Windows 10/11
+```powershell
+winget install --id Microsoft.OpenJDK.21 -e
+$jdk = (Get-ChildItem "$env:ProgramFiles\Microsoft\jdk-21*" -Directory | Select-Object -First 1).FullName
+[Environment]::SetEnvironmentVariable('JAVA_HOME', $jdk, 'User')
+[Environment]::SetEnvironmentVariable('PATH', "$jdk\bin;" + [Environment]::GetEnvironmentVariable('PATH','User'), 'User')
+```
+User-scope로 지정하면 Machine-scope에 남아있을 수 있는 구버전(Java 8 등)보다 PATH 우선순위가 앞선다. 새 터미널에서 반영 확인.
+
+## rc 마커 공통 (Linux/macOS, Windows 제외)
+```bash
+RC_FILE="$HOME/.bashrc"    # macOS는 $HOME/.zshrc
+grep -q '### BANKER_JAVA_BEGIN ###' "$RC_FILE" || cat >> "$RC_FILE" <<EOF
+
+### BANKER_JAVA_BEGIN ###
+export JAVA_HOME="$JAVA_HOME"
+export PATH="\$JAVA_HOME/bin:\$PATH"
+### BANKER_JAVA_END ###
+EOF
+source "$RC_FILE"
+```
+
+## 검증 (보고 의무)
+```bash
+java -version    # openjdk 21.x 기대
+javac -version   # java와 동일 21.x(다르면 alternatives 비대칭)
+echo "$JAVA_HOME"
+```
+4-field 보고: 변경(설치 패키지·alternatives 전환·JAVA_HOME 값) / Evidence(위 출력) / 검증(java·javac 버전 일치) / Unknown(관리자 권한 부재로 alternatives 미실행 등, 가짜 성공 금지).
+
+## 함정
+- **java/javac 비대칭**: `alternatives`(RHEL 계열)·`update-alternatives`(Debian 계열)에서 `java`만 바꾸고 `javac`를 안 바꾸면 "실행은 21, 컴파일은 8" 같은 사고 발생 → `--slave`로 묶거나 전환 직후 `javac -version` 대조.
+- **Debian 12 저장소 공백**: default·backports 모두 21 없음 → Adoptium 필수(버전 상황은 실행 전 재확인).
+- **Adoptium GPG/네트워크 차단**: 사내 프록시 환경이면 `packages.adoptium.net` 접근이 막힐 수 있음 → 정직 보고, 프록시 예외 요청.
+- **macOS symlink**: 1회성 sudo. `brew upgrade`로 21 내 패치 버전이 올라가도 재실행 불요하나, 메이저가 바뀌면(예: 21→25) 재실행 필요.
+- **Windows JAVA_HOME 누락**: 설정 안 하면 jdtls 등이 엉뚱한(또는 없는) JRE를 찾아 조용히 실패 → User-scope로 명시 설정 후 새 터미널에서 확인.
+- **버전 기준 재확인**: JDK 21 고정은 jdtls 호환 기준(2026-07 시점). 이후 jdtls·Spring Boot LS가 더 최신 LTS(예: 25)를 요구하게 되면 이 스킬의 버전 인자를 올려 재실행.
+
+ARGUMENTS: [--version <n>] (없으면 21 자동 설치)

package/skills/setup-lsp/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: setup-lsp
+description: "(banker) 언어별 LSP 서버(vtsls·basedpyright·bash·jdtls·spring)와 lsp-mcp 브리지 설치·연동. 'setup-lsp'/'LSP 설치'/'언어 서버' 또는 /banker:setup 시 사용."
+---
+
+# setup-lsp: 언어별 LSP 서버 + lsp-mcp 브리지
+
+symbol/type/reference 기반 코드 탐색(grep 대체)을 위해 언어별 language server(TypeScript·Python·Bash·Java·Spring)와
+이를 MCP 로 노출하는 `lsp-mcp` 브리지를 설치·연동한다. 설치는 **멱등**(이미 있으면 skip·검증만). 답변은 한글(기술 토큰·경로·명령은 영문).
+
+## 런타임 배선
+
+이 스킬은 두 가지를 설치한다 - (A) 표준 language server 바이너리, (B) `codex-lsp-bridge`(lsp-mcp). **소비 방식이 런타임마다 다르다**:
+
+- **Claude Code (OMC)** - 네이티브 `lsp_*` MCP 도구(`lsp_servers`·`lsp_goto_definition`·`lsp_find_references`·`lsp_hover`·`lsp_document_symbols` 등) 또는 `typescript-lsp@claude-plugins-official` 플러그인이 **PATH 의 서버 바이너리를 직접 구동**한다. **브리지 불필요** → §6·§7-Codex 는 건너뛰고 §2~§5 설치 후 §7-Claude 만 수행.
+- **Codex (OMX)** - `codex-lsp-bridge` 를 `~/.codex/config.toml` 의 `[mcp_servers.lsp_bridge]` 에 등록해 `lsp_bridge` tool 로 노출. §2~§7 전부 수행.
+
+먼저 §0 에서 **어느 런타임인지 감지**하고 해당 경로만 실행한다(둘 다 있으면 둘 다).
+
+## 0. 감지 (먼저, 추정 금지)
+```bash
+[ -f /etc/os-release ] && . /etc/os-release && echo "distro=$ID ${VERSION_ID}"; uname -m
+# 런타임
+command -v claude >/dev/null && echo "runtime: claude(OMC)" || echo "claude 없음"
+command -v codex  >/dev/null && echo "runtime: codex(OMX)"  || echo "codex 없음"
+# 선행 런타임 (§1 preflight 대상)
+command -v npm  >/dev/null && echo "npm=$(npm -v)"           || echo "npm 없음 → setup-node"
+command -v pipx >/dev/null && echo "pipx=$(pipx --version)"  || echo "pipx 없음 → setup-python"
+command -v java >/dev/null && java -version 2>&1 | head -1   || echo "java 없음 → setup-java"
+# 이미 설치된 서버
+for c in vtsls basedpyright-langserver ruff bash-language-server jdtls codex-lsp-bridge; do
+  command -v $c >/dev/null && echo "✓ $c" || echo "✗ $c"
+done
+# 프로젝트 언어 (--lang 미지정 시 이 결과로 선택)
+ls tsconfig.json package.json >/dev/null 2>&1 && echo "lang: ts"
+{ ls pyproject.toml setup.py >/dev/null 2>&1 || ls ./*.py >/dev/null 2>&1; } && echo "lang: py"
+ls ./*.sh >/dev/null 2>&1 && echo "lang: bash"
+ls pom.xml build.gradle build.gradle.kts >/dev/null 2>&1 && echo "lang: java"
+ls src/main/resources/application.* >/dev/null 2>&1 && echo "lang: spring"
+```
+> Windows(PowerShell): `Get-Command claude,codex,npm,pipx,java`, `Test-Path tsconfig.json,pom.xml` 등으로 동일 감지. jdtls 는 `jdtls.bat`.
+
+## 1. 사전요구(preflight)
+
+각 서버는 선행 런타임이 필요하다 - **없으면 먼저 해당 setup 스킬을 실행**(추정·강행 금지):
+
+| 대상 | 필요 런타임 | 없을 때 |
+|---|---|---|
+| vtsls·vscode-langservers-extracted·bash-language-server | **Node/npm** | `setup-node` 먼저 |
+| basedpyright·ruff (+ lsp-mcp 브리지도 pipx) | **Python/pipx** (3.8+) | `setup-python` 먼저 |
+| jdtls·Spring Boot LS | **JDK 21** (jdtls 는 21 필수) | `setup-java` 먼저 |
+
+```bash
+command -v npm  >/dev/null || echo "npm 필요 → setup-node 실행 후 재시도"
+command -v pipx >/dev/null || echo "pipx 필요 → setup-python 실행 후 재시도"
+# jdtls 는 Java 21+ 필수 - 미만이면 조용히 실패
+java -version 2>&1 | grep -qE '"(2[1-9]|[3-9][0-9])' || echo "Java 21+ 아님 → setup-java 먼저(java/spring 스킵 가능)"
+```
+
+## 2. 언어 선택
+
+`--lang ts,py,bash,java,spring` 로 명시. 없으면 §0 감지(프로젝트 언어), 그것도 없으면 **전체**.
+매핑: `ts`→§3(npm), `bash`→§3(npm), `py`→§4(pipx), `java`→§5(jdtls), `spring`→§5(jdtls+Spring LS).
+
+## 3. npm 서버 (ts·bash - Node 필요)
+```bash
+npm install -g \
+  @vtsls/language-server \
+  vscode-langservers-extracted \
+  bash-language-server
+for c in vtsls bash-language-server; do command -v $c >/dev/null && echo "✓ $c" || echo "✗ $c"; done
+```
+- `@vtsls/language-server`→`vtsls`(TS/JS), `vscode-langservers-extracted`→JSON/CSS/HTML/ESLint 서버, `bash-language-server`→shell.
+- 전역 설치 권한 필요 - **`sudo npm -g` 금지**(nvm/prefix 는 `setup-node` 참조).
+
+## 4. pipx 서버 (py - Python 필요)
+```bash
+pipx install basedpyright     # → basedpyright-langserver (타입체커 LSP)
+pipx install ruff             # → ruff (formatter/linter + `ruff server` LSP)
+for c in basedpyright-langserver ruff; do command -v $c >/dev/null && echo "✓ $c" || echo "✗ $c"; done
+```
+- pipx 격리 설치 → shebang 고정이라 시스템 Python 변경에 영향 없음.
+
+## 5. jdtls + Spring Boot LS (java·spring - JDK 21 필요)
+
+**jdtls (Java LSP)** - Eclipse 최신 스냅샷:
+```bash
+mkdir -p ~/.local/jdtls
+curl -fLo /tmp/jdtls.tar.gz \
+  "https://download.eclipse.org/jdtls/snapshots/jdt-language-server-latest.tar.gz"
+tar -xzf /tmp/jdtls.tar.gz -C ~/.local/jdtls
+rm /tmp/jdtls.tar.gz
+chmod +x ~/.local/jdtls/bin/jdtls
+which jdtls        # PATH 에 ~/.local/jdtls/bin 필요
+```
+> jdtls 는 **Java 21 미만이면 무증상으로 죽는다** → §1 preflight 필수. Windows 는 `~/.local/jdtls\bin` 을 PATH 에 넣고 `jdtls.bat` 로 호출.
+
+**Spring Boot Language Server** - VSIX(=ZIP) 다운로드. vsassets.io/marketplace 가 **HTML 에러페이지**를 반환할 수 있어 **ZIP 매직바이트(`504b0304`) 검증** 후 `find` 로 `*-exec.jar` 탐색 + 심볼릭 링크:
+```bash
+set -euo pipefail
+TARGET="$HOME/.local/spring-boot-ls"; VSIX=/tmp/sbls.vsix; LINK=spring-boot-language-server.jar
+mkdir -p "$TARGET"
+VSIX_URL="https://vmware.gallery.vsassets.io/_apis/public/gallery/publisher/vmware/extension/vscode-spring-boot/latest/assetbyname/Microsoft.VisualStudio.Services.VSIXPackage"
+FALLBACK="https://marketplace.visualstudio.com/_apis/public/gallery/publishers/vmware/vsextensions/vscode-spring-boot/latest/vspackage"
+curl -fL --connect-timeout 30 --retry 2 -H "User-Agent: Mozilla/5.0" -o "$VSIX" "$VSIX_URL" 2>/dev/null \
+  || curl -fL --connect-timeout 30 --retry 2 -H "User-Agent: Mozilla/5.0" -o "$VSIX" "$FALLBACK"
+# ZIP 매직 검증 (HTML 에러페이지면 즉시 중단)
+[ "$(xxd -l 4 "$VSIX" | awk 'NR==1{print $2$3}')" = "504b0304" ] \
+  || { echo "✗ ZIP 아님(HTML 에러페이지?)"; rm -f "$VSIX"; exit 1; }
+rm -rf "${TARGET:?}"/*; unzip -o -q "$VSIX" -d "$TARGET"
+JAR=$(find "$TARGET" -name "spring-boot-language-server-*-exec.jar" | sort -V | tail -1)
+[ -n "$JAR" ] || { echo "✗ exec.jar 미발견"; rm -f "$VSIX"; exit 1; }
+ln -sf "$(basename "$JAR")" "$(dirname "$JAR")/$LINK"     # 디렉토리 이동에도 유효한 상대 링크
+rm -f "$VSIX"; find ~/.local/spring-boot-ls -name "$LINK" -ls
+```
+> Windows: 심볼릭 링크는 **개발자 모드/관리자 권한** 필요 → 없으면 `Copy-Item` 복사 fallback(둘 다 동작). 매직검증·find 는 PowerShell 로 동일 수행, JAR 경로는 `.Replace('\','/')`. RHEL8 에 `xxd` 없으면 `dnf install -y vim-common` 또는 `od -An -tx1 -N4`.
+
+## 6. lsp-mcp 브리지 설치 (Codex 경로 - Claude Code 는 건너뜀)
+```bash
+mkdir -p ~/.local/src
+git clone https://github.com/CesarPetrescu/lsp-mcp.git ~/.local/src/lsp-mcp
+pipx install --editable ~/.local/src/lsp-mcp     # → ~/.local/bin/codex-lsp-bridge (Windows: .exe)
+which codex-lsp-bridge && codex-lsp-bridge --help | head -5
+```
+
+**브리지에 Java/Spring 서버 등록** - `config/default.toml` 에 `[servers.java]`/`[servers.spring-boot-properties]` append. **idempotent guard 필수**: 두 번 실행하면 중복 선언 → TOML 파싱 실패 → `codex-lsp-bridge` 즉사 → `MCP client for 'lsp_bridge' failed to start`. 기본 default.toml 에 이미 있는 서버(ts/py/bash 등)는 그대로 두고 java/spring 만 추가:
+```bash
+cd ~/.local/src/lsp-mcp
+cp -n config/default.toml config/default.toml.bak    # 최초 1회만 백업
+# guard: 이미 있으면 skip. unquoted heredoc - $HOME 를 셸이 절대경로로 확장
+grep -q '\[servers.java\]' config/default.toml || cat >> config/default.toml << EOF
+
+[servers.java]
+command = "jdtls"
+args = []
+file_extensions = ["java"]
+language_id = "java"
+
+[servers.spring-boot-properties]
+command = "java"
+args = ["-jar", "$HOME/.local/spring-boot-ls/extension/jars/spring-boot-language-server.jar"]
+file_extensions = ["properties", "yml", "yaml"]
+language_id = "spring-boot-properties"
+EOF
+# TOML 유효성 (중복/문법오류 즉시 감지). tomllib 는 Python 3.11+ - RHEL8/Rocky8 기본 python3(3.6)면 setup-python 의 3.11 을 쓴다:
+PY="$(command -v python3.12 || command -v python3.11 || command -v python3)"
+"$PY" -c "import tomllib; tomllib.loads(open('config/default.toml',encoding='utf-8').read()); print('OK lsp-mcp TOML')" 2>/dev/null \
+  || echo "⚠ tomllib(3.11+) 미가용 - append 는 위 grep guard 로 이미 적용됨, setup-python 설치 후 재검증"
+cd - >/dev/null
+```
+> Spring JAR 경로는 §5 `find` 실제 결과와 일치해야 함(환경마다 디렉토리 상이). 깨졌으면 `cp config/default.toml.bak config/default.toml` 복구.
+> Windows: `Get-Content -Raw` 로 읽어 `-match '\[servers\.java\]'` guard 후 `[System.IO.File]::WriteAllText(path, text, [System.Text.UTF8Encoding]::new($false))` 로만 append(CP949/BOM 회피).
+
+## 7. 배선 (Codex config.toml · Claude 네이티브)
+
+### 7-Codex - `[mcp_servers.lsp_bridge]` 등록
+OMX 가 배포한 기존 엔트리를 보존하려 **Python replace-or-append** 로 patch(전체 덮어쓰기 금지):
+```bash
+python3 - << 'PY'
+import re
+from pathlib import Path
+home = str(Path.home())                        # Windows: str(Path.home()).replace("\\","/")
+p = Path.home() / ".codex" / "config.toml"
+txt = p.read_text(encoding="utf-8") if p.exists() else ""
+def rep(body, header, block):
+    pat = rf'\[{re.escape(header)}\].*?(?=\n\[|\Z)'
+    if re.search(pat, body, flags=re.DOTALL):
+        return re.sub(pat, block.strip() + '\n', body, flags=re.DOTALL, count=1)
+    return body.rstrip() + '\n\n' + block.strip() + '\n'
+binname = "codex-lsp-bridge"                   # Windows: codex-lsp-bridge.exe
+block = "\n".join([
+    "[mcp_servers.lsp_bridge]",
+    f'command = "{home}/.local/bin/{binname}"',
+    f'args = ["serve", "--transport", "stdio", "--config", "{home}/.local/src/lsp-mcp/config/default.toml"]',
+    "startup_timeout_sec = 300",               # 첫 기동/다운로드 대비
+])
+txt = rep(txt, "mcp_servers.lsp_bridge", block + "\n")
+p.write_text(txt, encoding="utf-8")            # Windows: encoding 필수(CP949 회피)
+print("patched")
+PY
+PY="$(command -v python3.12 || command -v python3.11 || command -v python3)"   # tomllib=3.11+
+"$PY" -c "import tomllib; tomllib.loads(open('$HOME/.codex/config.toml',encoding='utf-8').read()); print('OK config.toml valid')" 2>/dev/null \
+  || echo "⚠ tomllib(3.11+) 미가용 - patch 는 적용됨, setup-python 후 재검증"
+```
+
+### 7-Claude - 네이티브 lsp_* / 플러그인
+브리지·config.toml patch **불필요**. PATH 의 서버 바이너리가 OMC `lsp_*` 도구를 뒷받침한다:
+- 설치 후 `/reload-plugins`(또는 Claude 재시작) → `lsp_servers` 로 인식된 서버 확인.
+- TypeScript 전용은 `typescript-lsp@claude-plugins-official` 플러그인도 가능(`/plugin install typescript-lsp@claude-plugins-official`).
+- 서버가 `lsp_servers` 에 안 뜨면 PATH(§0)·재시작 확인.
+
+**OS 경로 차이 (요약)**
+
+| 요소 | Linux(rocky/rhel/ubuntu/debian) | Windows | macOS |
+|---|---|---|---|
+| bridge 바이너리 | `$HOME/.local/bin/codex-lsp-bridge` | `...\codex-lsp-bridge.exe` | Linux 동일 |
+| jdtls 실행 | `jdtls` | `jdtls.bat` | `jdtls` |
+| config patch home | `str(Path.home())` | `.replace("\\","/")` | `str(Path.home())` |
+| TOML read/write | 기본 | `encoding='utf-8'` 필수(CP949) | 기본 |
+| Spring JAR 링크 | `ln -sf` | SymbolicLink→권한없으면 `Copy-Item` | `ln -sf` |
+
+## 검증 (보고 의무)
+
+**존재 ≠ 동작** - 각 서버가 실제 응답하는지까지 확인:
+```bash
+basedpyright --version                               # CLI 로 버전 확인(langserver 는 stdio 서버라 --version 없음)
+command -v basedpyright-langserver >/dev/null && echo "✓ basedpyright-langserver"
+vtsls --version
+bash-language-server --version
+ruff --version
+jdtls --version 2>/dev/null || which jdtls           # Windows: jdtls.bat
+# Codex 만:
+codex-lsp-bridge --help | head -3
+grep -q 'lsp_bridge' ~/.codex/config.toml && echo "✓ config.toml lsp_bridge" || echo "✗ 미등록"
+PY="$(command -v python3.12 || command -v python3.11 || command -v python3)"   # tomllib=3.11+
+"$PY" -c "import tomllib; tomllib.loads(open('$HOME/.codex/config.toml',encoding='utf-8').read()); print('✓ config.toml valid')" 2>/dev/null || echo "⚠ tomllib(3.11+) 미가용 - setup-python 후 재검증"
+# Claude 만: lsp_servers 도구로 인식 서버 나열
+```
+4-field 보고: **변경**(설치 서버·브리지·config 배선) / **Evidence**(위 --version·valid 출력) / **검증**(각 서버 응답 + 브리지·config TOML valid + 런타임 인식) / **Unknown**(네트워크 차단으로 미설치·JDK 21 부재로 java/spring 스킵 등).
+
+## 함정
+
+- **Spring VSIX = HTML 에러페이지** - vsassets.io/marketplace 가 ZIP 대신 에러페이지를 반환 → **매직바이트 `504b0304` 검증 필수**(안 하면 깨진 JAR 로 진행). fallback URL 자동 전환.
+- **`[servers.java]` 중복 → 브리지 즉사** - §6 append 를 guard 없이 두 번 → TOML 파싱 실패 → `MCP client for 'lsp_bridge' failed to start`. **grep/`-match` guard 필수**, 깨졌으면 `.bak` 복구.
+- **jdtls Java 21 미만 → 무증상 실패** - preflight(§1)로 `java -version` 21+ 확인. 아니면 `setup-java` 먼저.
+- **Windows CP949/BOM** - 모든 Python `open(...,encoding='utf-8')`, PowerShell append 는 `WriteAllText`+`UTF8Encoding($false)` 만(`Add-Content`/`Out-File -Encoding UTF8` 금지). config patch home 은 forward-slash(`.replace("\\","/")`).
+- **Windows 심볼릭 링크 권한** - 개발자 모드/관리자 아니면 `Copy-Item` 복사 fallback. `.exe`(bridge)·`.bat`(jdtls) 확장자 주의.
+- **첫 실행 timeout** - 브리지/npx 최초 기동은 느림 → `startup_timeout_sec = 300`. 첫 회만 느리면 정상(캐싱 후 빠름).
+- **PATH 미반영** - `~/.local/bin`·`~/.local/jdtls/bin` 이 PATH 에 없으면 서버 미인식 → 새 셸/`source ~/.bashrc` 또는 절대경로(Claude 는 `lsp_servers` 로 재확인).
+- **config 전체 덮어쓰기 금지** - Codex `config.toml` 은 반드시 replace-or-append(§7-Codex)로 patch - OMX 가 배포한 다른 MCP/agents 엔트리를 보존.
+
+ARGUMENTS: [--lang ts,py,bash,java,spring] (없으면 프로젝트 언어 감지 또는 전체)

package/skills/setup-mcp/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: setup-mcp
+description: "(banker) context7·sequential-thinking·filesystem·git·fetch(+선택 tavily) 범용 MCP 서버를 Claude Code(claude mcp add)·Codex(codex mcp add+config.toml)에 배선(serena·lsp_bridge 제외). 'setup-mcp'/'MCP 서버 설치'/'context7·sequential-thinking 설치' 또는 /banker:setup 시 사용."
+---
+
+# setup-mcp: 범용 MCP 서버 설치
+
+context7·sequential-thinking·filesystem·git·fetch - 특정 도구에 종속되지 않는 5종 표준 MCP 서버를
+Claude Code·Codex 양쪽에 배선한다. **`setup-omc`(OMC/OMX 프레임워크 자체 설치, 자기 도구를 따로 들고 옴)와도,
+`setup-lsp`(`lsp_bridge` 전용)와도 다르다** - 이 스킬은 그 외 범용 standalone 서버만 다룬다. Serena 는
+프로젝트 스코프(`--project` 가 홈 디렉터리면 인덱싱 과부하)라 여기서 제외한다. 설치는 **멱등**(있으면
+remove 후 재-add). 답변은 한글(기술 토큰 영문).
+
+## 런타임 배선
+- **Claude Code**: `claude mcp add <name> -s user -- <command> ...` - CLI 가 설정을 직접 관리.
+- **Codex**: 현재 공식 CLI `codex mcp add <name> -- <command> ...` 로 등록(내부적으로 `~/.codex/config.toml`
+  `[mcp_servers.<name>]` 에 기록) - 단 `startup_timeout_sec`(기본 10초, 첫 npx/uvx 다운로드 대비 300초로
+  올려야 함)은 CLI 플래그로 노출되지 않는다 → **Python replace-or-append** 로 그 필드만 추가 패치한다.
+
+## 0. 감지 (먼저, 추정 금지)
+```bash
+command -v npx >/dev/null && echo "npx=yes" || echo "npx=no (setup-node 먼저)"
+command -v uvx >/dev/null && echo "uvx=yes" || echo "uvx=no (setup-python 먼저)"
+command -v claude >/dev/null && claude mcp list 2>/dev/null
+command -v codex >/dev/null && codex mcp list 2>/dev/null
+[ -f ~/.codex/config.toml ] && grep -c 'startup_timeout_sec = 300' ~/.codex/config.toml
+```
+
+## 1. Preflight
+- **npx 없음** → Node 미설치 → `setup-node` 스킬로 먼저 설치.
+- **uvx 없음** → uv 미설치 → `setup-python` 스킬로 먼저 설치(uv 설치는 그 스킬 소관).
+- 둘 다 있으면 2로 진행.
+
+## 2. 서버 목록
+| name | command | args |
+|---|---|---|
+| context7 | npx | `-y @upstash/context7-mcp` |
+| sequential-thinking | npx | `-y @modelcontextprotocol/server-sequential-thinking` |
+| filesystem | npx | `-y @modelcontextprotocol/server-filesystem <dir>` |
+| git | uvx | `mcp-server-git` |
+| fetch | uvx | `mcp-server-fetch` |
+| tavily(선택) | npx | `-y tavily-mcp` (env `TAVILY_API_KEY`) |
+
+`<dir>` = `--fs-dir` 인자 또는 기본 `$HOME/projects`. **홈 디렉터리 전체를 넘기지 않는다** - Serena
+`--project` 경고와 같은 이유(파일 노출 범위 과다)로, 실제 프로젝트 경로만 지정한다.
+
+## 3. Claude Code 배선
+```bash
+FS_DIR="${FS_DIR:-$HOME/projects}"
+
+claude mcp remove context7 -s user 2>/dev/null
+claude mcp add context7 -s user -- npx -y @upstash/context7-mcp
+
+claude mcp remove sequential-thinking -s user 2>/dev/null
+claude mcp add sequential-thinking -s user -- npx -y @modelcontextprotocol/server-sequential-thinking
+
+claude mcp remove filesystem -s user 2>/dev/null
+claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem "$FS_DIR"
+
+claude mcp remove git -s user 2>/dev/null
+claude mcp add git -s user -- uvx mcp-server-git
+
+claude mcp remove fetch -s user 2>/dev/null
+claude mcp add fetch -s user -- uvx mcp-server-fetch
+
+claude mcp list
+```
+선택(Tavily) - **실제 키를 채팅·로그에 남기지 말 것**, 사용자가 자기 터미널에서 직접 교체:
+```bash
+claude mcp remove tavily -s user 2>/dev/null
+claude mcp add tavily -s user -e TAVILY_API_KEY=YOUR_TAVILY_API_KEY -- npx -y tavily-mcp
+```
+
+## 4. Codex 배선
+```bash
+codex mcp remove context7 2>/dev/null
+codex mcp add context7 -- npx -y @upstash/context7-mcp
+
+codex mcp remove sequential-thinking 2>/dev/null
+codex mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking
+
+codex mcp remove filesystem 2>/dev/null
+codex mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem "${FS_DIR:-$HOME/projects}"
+
+codex mcp remove git 2>/dev/null
+codex mcp add git -- uvx mcp-server-git
+
+codex mcp remove fetch 2>/dev/null
+codex mcp add fetch -- uvx mcp-server-fetch
+
+codex mcp list
+```
+선택(Tavily, 실제 키 미노출):
+```bash
+codex mcp remove tavily 2>/dev/null
+codex mcp add tavily --env TAVILY_API_KEY=YOUR_TAVILY_API_KEY -- npx -y tavily-mcp
+```
+
+`startup_timeout_sec` 패치(기본 10초는 첫 npx/uvx 다운로드엔 부족) - **Python replace-or-append** 로 방금
+등록한 테이블에만 삽입하고 그 외(OMX 가 배포한 엔트리 등)는 건드리지 않는다(멱등: 이미 있으면 스킵).
+`tomllib` 는 Python **3.11+** 전용이라(RHEL8/Rocky8 기본 `python3` 는 3.6 인 경우가 흔함) 먼저 인터프리터를
+고른다:
+```bash
+PY="$(command -v python3.12 || command -v python3.11 || command -v python3)"
+"$PY" -c "import tomllib" 2>/dev/null || echo "⚠ tomllib 없음 - Python 3.11+ 설치 후 재시도(setup-python 참고)"
+```
+```bash
+"$PY" <<'EOF'
+import re
+from pathlib import Path
+import tomllib
+
+CFG = Path.home() / ".codex" / "config.toml"
+NAMES = ["context7", "sequential-thinking", "filesystem", "git", "fetch"]  # tavily 추가했으면 여기도 추가
+
+text = CFG.read_text(encoding="utf-8")
+tomllib.loads(text)  # 사전 검증 - 깨진 TOML이면 여기서 예외
+
+parts = re.split(r"(?=^\[)", text, flags=re.MULTILINE)
+out = []
+for part in parts:
+    m = re.match(r"\[mcp_servers\.([^\]]+)\]", part)
+    if m and m.group(1) in NAMES and "startup_timeout_sec" not in part:
+        head, _, rest = part.partition("\n")
+        part = f"{head}\nstartup_timeout_sec = 300\n{rest}"
+    out.append(part)
+
+new_text = "".join(out)
+tomllib.loads(new_text)  # 패치 후 재검증
+CFG.write_text(new_text, encoding="utf-8")
+print("patched:", [n for n in NAMES if f"[mcp_servers.{n}]" in new_text])
+EOF
+```
+
+## 검증 (보고 의무)
+```bash
+claude mcp list                                # 각 서버가 ✔ Connected 인지 확인
+codex mcp list --json | python3 -m json.tool   # 각 서버 등록 확인(json.tool 은 아무 python3 로 충분)
+PY="$(command -v python3.12 || command -v python3.11 || command -v python3)"   # tomllib=3.11+
+"$PY" -c "import tomllib; tomllib.loads(open('$HOME/.codex/config.toml', encoding='utf-8').read()); print('✓ TOML 유효')"
+grep -c 'startup_timeout_sec = 300' ~/.codex/config.toml   # 5(+tavily)건 이상 기대
+```
+4-field 보고: 변경(등록한 서버 목록·config.toml 패치분) / Evidence(위 출력) / 검증(Connected·TOML 유효) /
+Unknown(네트워크 차단으로 첫 다운로드 실패 등).
+
+## 함정
+- **첫 실행 지연**: npx/uvx 첫 다운로드는 수십 초 걸릴 수 있다 - Codex 는 `startup_timeout_sec=300` 로
+  여유를 두지만, Claude Code 쪽은 최초 1회 재시도가 필요할 수 있다(정직 안내).
+- **Tavily 키**: 플레이스홀더 `YOUR_TAVILY_API_KEY` 를 실제 키로 교체하기 전엔 연결 실패 - 채팅·로그·커밋에
+  실키를 노출하지 않는다.
+- **uvx 전제**: uv 미설치 시 git·fetch 서버가 실패 → `setup-python` 선행.
+- **filesystem 디렉터리 범위**: 홈 전체를 넘기면 과다 노출 - 프로젝트 디렉터리로 한정한다.
+- **`codex mcp add` 는 timeout 플래그가 없다**: 위 Python 패치를 별도로 수행해야 300초가 실제로 반영된다.
+- **Windows 인코딩**: config.toml 을 다루는 Python 은 `encoding='utf-8'` 명시(CP949 회피).
+
+ARGUMENTS: [--fs-dir <path>] [--tavily] [--server <name>,...] (없으면 context7·sequential-thinking·filesystem·git·fetch 5종 전부, tavily 는 --tavily 명시 시에만)

package/skills/setup-node/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: setup-node
+description: "(banker) nvm + Node 22(LTS) 런타임 설치(Windows는 winget 또는 nvm-windows). Claude Code npm 설치·Codex/OMX·npx 기반 MCP 서버 전제. 'setup-node'/'Node 설치'/'nvm 설치' 또는 /banker:setup 시 사용."
+---
+
+# setup-node: nvm + Node 22(LTS) 런타임 설치
+
+Claude Code·Codex/OMX 및 다수 npx 기반 MCP 서버가 딛고 서는 Node.js 런타임을 설치한다.
+버전 고정 대신 **현재 LTS**를 설치하는 것이 원칙(2026-07 기준 최소 22 이상). 멱등(이미 있으면 확인만). 답변은 한글.
+
+## 런타임 배선
+- **Claude Code**: 네이티브 인스톨러 자체는 Node가 불필요하지만, npm 설치 경로(v2.1.198+)는 Node 22+를 요구한다. `context7`·`sequential-thinking`·`playwright` 등 다수 MCP 서버가 `npx -y ...`로 구동되어 Node에 의존한다.
+- **Codex/OMX**: `npm install -g @openai/codex oh-my-codex` 자체가 npm(Node)을 전제. LSP 스택(`@vtsls/language-server`·`vscode-langservers-extracted`·`bash-language-server`)도 npm 전역 설치로 배포된다.
+- 즉 이 스킬은 두 런타임 공통 하위 의존성이며, 다른 setup-* 스킬보다 먼저 실행되는 편이 안전하다.
+
+## 0. 감지 (먼저, 추정 금지)
+```bash
+[ -f /etc/os-release ] && . /etc/os-release && echo "distro=$ID ${VERSION_ID}"
+uname -s                                                     # Linux / Darwin
+[ -s "$HOME/.nvm/nvm.sh" ] && echo "nvm=설치됨" || echo "nvm=미설치"
+command -v node >/dev/null && echo "node=$(node -v)" || echo "node=미설치"
+command -v npm  >/dev/null && echo "npm=$(npm -v)"
+```
+```powershell
+$PSVersionTable.PSVersion
+winget --version
+if (Get-Command node -ErrorAction SilentlyContinue) { node -v } else { "node: 미설치" }
+if (Get-Command nvm  -ErrorAction SilentlyContinue) { nvm version } else { "nvm-windows: 미설치" }
+```
+
+## 1. Rocky Linux 8
+```bash
+command -v curl >/dev/null && command -v git >/dev/null || sudo dnf install -y curl git
+```
+이후 아래 "nvm 공통 설치"를 그대로 실행.
+> ⚠️ Rocky8/RHEL8 glibc는 정확히 2.28. Node 최신 메이저의 prebuilt 바이너리 glibc 최저요구치가 이보다 올라가면(예: 2.31+) 설치 실패 가능 → `ldd --version`으로 사전 확인, 실패 시 nvm이 소스빌드로 폴백하거나 에러를 낸다(정직 보고).
+
+## 2. Ubuntu 20.04~24.04
+```bash
+command -v curl >/dev/null && command -v git >/dev/null || sudo apt install -y curl git
+```
+이후 "nvm 공통 설치" 그대로. 최소 서버 이미지가 아니면 대개 이미 충족.
+
+## 3. Debian 12
+```bash
+command -v curl >/dev/null && command -v git >/dev/null || sudo apt install -y curl git
+```
+이후 "nvm 공통 설치" 그대로.
+
+## nvm 공통 설치 (Rocky8·Ubuntu·Debian·macOS)
+```bash
+# 최신 nvm 릴리스 태그 자동확인(하드코딩 회피). 실패 시 수동 확인 안내
+NVM_LATEST=$(curl -fsSL https://api.github.com/repos/nvm-sh/nvm/releases/latest \
+  | grep -m1 '"tag_name":' | sed -E 's/.*"tag_name": *"([^"]+)".*/\1/')
+if [ -z "$NVM_LATEST" ]; then
+  echo "⚠️ 최신 태그 자동확인 실패. https://github.com/nvm-sh/nvm/releases 에서 수동 확인 후 <TAG> 치환"
+  NVM_LATEST="<TAG>"
+fi
+curl -o- "https://raw.githubusercontent.com/nvm-sh/nvm/${NVM_LATEST}/install.sh" | bash
+
+# 설치 스크립트가 rc 파일을 자동 갱신하나, 컨테이너 등 미반영 환경 대비 idempotent 마커도 병행
+RC_FILE="$HOME/.bashrc"    # macOS는 $HOME/.zshrc
+grep -q '### BANKER_NODE_BEGIN ###' "$RC_FILE" || cat >> "$RC_FILE" <<'EOF'
+
+### BANKER_NODE_BEGIN ###
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
+[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
+### BANKER_NODE_END ###
+EOF
+source "$RC_FILE"
+
+nvm install --lts          # 2026-07 기준 22 이상의 현재 LTS 자동 설치
+nvm alias default 'lts/*'
+node -v && npm -v
+```
+
+## 4. macOS (Apple Silicon / Intel)
+curl은 기본 내장. Apple Silicon/Intel 차이는 Homebrew prefix 정도로 nvm 자체엔 영향 없음. 위 "nvm 공통 설치"를 zsh(`~/.zshrc`)에 그대로 적용.
+- Homebrew의 `nvm` formula도 존재하나 `NVM_DIR` 캐비어트가 있어 **공식 curl 스크립트를 우선** 권장(공식 문서 기준).
+
+## 5. Windows 10/11
+멀티버전 전환이 불필요하면 winget 단일 설치가 가장 단순:
+```powershell
+winget install --id OpenJS.NodeJS.LTS -e
+node -v; npm -v
+```
+여러 Node 버전을 넘나들어야 하면 nvm-windows(별개 프로젝트, POSIX nvm과 무관):
+```powershell
+winget install --id CoreyButler.NVMforWindows -e
+# 새 터미널에서
+nvm install lts
+nvm use <설치된 버전>
+```
+> ⚠️ **winget Node와 nvm-windows를 동시에 설치하지 않는다.** 두 경로가 PATH에 동시 등록되면 `node.exe`가 어느 쪽을 가리키는지 꼬인다. 하나만 선택.
+
+## 검증 (보고 의무)
+```bash
+node -v      # v22.x.x 이상 기대(현재 LTS)
+npm -v
+corepack enable 2>/dev/null && corepack --version   # pnpm/yarn 필요 시만(선택, Node 버전에 따라 기본 포함 여부 상이)
+```
+4-field 보고: 변경(nvm 설치 경로·rc 마커·설치된 Node 버전) / Evidence(위 출력) / 검증(`node -v` ≥22 확인) / Unknown(관리자 권한 부재로 시스템 전역 설치 불가 등).
+
+## 함정
+- **새 셸에만 반영**: nvm은 현재 셸에 `source ~/.bashrc`(또는 `~/.zshrc`) 하지 않으면 안 보임.
+- **Windows PATH 충돌**: winget Node와 nvm-windows 동시 설치 금지(위 참조).
+- **corepack**: pnpm/yarn 격리 관리용. Node 메이저에 따라 기본 포함 여부가 바뀔 수 있어 `corepack --version` 미동작 시 `npm install -g corepack`.
+- **EL8 glibc 2.28**: 향후 Node 메이저가 최저 glibc 요구치를 올리면 prebuilt 설치 실패 가능(사전 `ldd --version` 확인).
+- **버전 기준 재확인**: "22 이상"은 2026-07 시점 기준선. `nvm install --lts`는 항상 그 시점 현재 LTS를 설치하므로 자연히 충족되지만, 특정 메이저 고정이 필요하면 `--version` 인자 사용.
+
+ARGUMENTS: [--version <major>] (없으면 `nvm install --lts`로 현재 LTS 자동 설치)

package/skills/setup-omc/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup-omc
-description: "all-in-one·ultra-init·front-qa 가 의존하는 oh-my-claudecode(OMC)를 설치/갱신. Codex는 oh-my-codex(OMX). 'setup-omc'/'OMC 설치'/'oh-my-claudecode 설치' 또는 /banker:setup 시 사용."
+description: "(banker) all-in-one·ultra-init·front-qa 가 의존하는 oh-my-claudecode(OMC) 설치/갱신(Codex는 OMX). 'setup-omc'/'OMC 설치'/'oh-my-claudecode 설치' 또는 /banker:setup 시 사용."
 ---
 
 # setup-omc: oh-my-claudecode(OMC) 설치/갱신

package/skills/setup-omc-hud/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: setup-omc-hud
-description: "omc_hud(Claude Code 상태표시줄)를 OS(mac/linux/windows)별 apply 스크립트로 내려받아 적용. 'setup-omc-hud'/'omc_hud 설치' 또는 /banker:setup 시 사용."
+description: "(banker) omc_hud(Claude Code 상태표시줄)를 OS별 apply 스크립트로 적용(Codex는 OMX hud). 'setup-omc-hud'/'omc_hud 설치' 또는 /banker:setup 시 사용."
 ---
 
 # setup-omc-hud — omc_hud 상태표시줄 설치 (OS별)
 
 `smallOpenSource/omc_hud` 의 apply 스크립트를 OS에 맞게 내려받아 적용한다. `wget` 없으면 `curl`로 폴백. 답변은 한글.
 
+**런타임:** omc_hud 는 Claude Code 상태표시줄(`~/.claude/settings.json` statusLine) 대상이다. **Codex 런타임에선 oh-my-codex(OMX)가 자체 `hud` 스킬/구성을 제공**하므로, Codex에선 이 스킬 대신 OMX 의 `hud` 를 사용한다.
+
 ## 0. 감지
 ```bash
 case "$(uname -s)" in Darwin) OS=mac;; Linux) OS=linux;; *) OS=windows;; esac; echo "OS=$OS"

package/skills/setup-playwright/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup-playwright
-description: "Playwright + headless 브라우저를 OS·권한·conda 감지 후 설치 — RHEL8/Rocky8 비공식·non-root·no-conda venv·xvfb 폴백 지원. 'setup-playwright'/'playwright 설치' 또는 /banker:setup 시 사용."
+description: "(banker) Playwright + headless 브라우저를 OS·권한·conda 감지 후 설치(RHEL8/Rocky8·non-root·no-conda·xvfb 폴백). 'setup-playwright'/'playwright 설치' 또는 /banker:setup 시 사용."
 ---
 
 # setup-playwright — Playwright + headless 브라우저 설치 (OS·권한 적응형)