kordoc을 Node.js 없이 쓰는 Windows 실행 파일로 — kordoc-exe
HWP·HWPX·PDF·DOCX·XLSX를 Markdown으로 바꾸는 kordoc을 Bun으로 묶어, Node.js 설치 없이 도는 Windows 실행 파일로 만드는 빌드 스크립트입니다. 그대로 컴파일하면 생기는 문제를 어떻게 고쳤는지도 정리했습니다.
kordoc은 HWP, HWPX, PDF, DOCX, XLSX 문서를 Markdown으로 바꾸는 CLI이자 MCP 서버입니다. Node.js 프로그램이라 쓰려면 Node.js와 패키지 설치가 먼저 필요합니다. 다른 Windows 프로그램에 같이 실어 보내거나, 개발 도구가 없는 PC에서 돌리기에는 이 점이 걸립니다.
kordoc-exe는 kordoc을 Bun으로 컴파일해 Node.js 없이 실행되는 Windows x64 실행 파일로 만드는 스크립트 모음입니다. 원본 소스는 upstream/에 git submodule로 참조합니다. 원본은 고치지 않고, 빌드할 때 번들 단계에서 필요한 곳만 바꿉니다.
빌드
git clone --recurse-submodules https://github.com/civilian7/kordoc-exe
cd kordoc-exe
bun scripts/build-exe.ts
out/에 kordoc.exe(CLI)와 kordoc-mcp.exe(MCP 서버)가 생깁니다. 각각 약 113MB입니다. 옆에 pdfjs/와 templates/ 폴더도 함께 생기는데, 배포할 때는 폴더째 옮겨야 합니다. exe만 옮기면 내장 서식과 한글 CID 폰트용 PDF cMap이 빠집니다.
의존성 버전은 루트의 bun.lock으로 고정합니다. upstream을 올릴 때는 --update-lock으로 잠금을 새로 풉니다.
그대로 컴파일하면 안 되는 이유
bun build src/cli.ts --compile은 통과하지만, 만든 exe는 실행하자마자 죽습니다. 빌드 스크립트가 바꾸는 곳은 다음과 같습니다.
| 증상 | 원인 | 처리 |
|---|---|---|
Cannot find package 'cfb'로 바로 종료 |
createRequire(...)("cfb")를 번들러가 따라가지 못함 |
번들되는 일반 require로 |
| 한글 CID 폰트 PDF의 글자가 조용히 빠짐 | exe 안에서 require.resolve 실패를 catch가 삼킴 |
exe 옆 pdfjs/에서 읽음 |
fill --template이 서식을 못 찾음 |
import.meta.url이 가상 경로 |
exe 옆 templates/를 후보에 추가 |
| PDF 변환 결과 앞에 경고 4줄이 섞임 | pdfjs가 stdout으로 경고 출력 | 텍스트 추출에 필요 없는 그 부분을 끔 |
| HWP3 암호 문서가 맞는 암호로도 실패 | Bun의 node:crypto에 des-ede3-ecb가 없음 |
순수 JS DES로 대체 |
바꿀 문자열이 upstream에서 사라지면 빌드가 조용히 넘어가지 않고 실패합니다. 원본에 없는 옵션도 하나 더했습니다. --password-stdin은 문서 암호를 표준 입력 첫 줄에서 읽습니다. --password로 주면 암호가 명령줄에 실려 다른 프로그램이나 감사 로그에서 보이기 때문입니다.
써 보기
kordoc 문서.hwpx # 표준 출력으로
kordoc 문서.hwp -o 문서.md # 파일로(그림은 옆의 images\ 에)
kordoc *.pdf -d out # 여러 파일 → out\<이름>.md, 그림은 out\images\
kordoc 보고서.pdf -p 1-3 --no-header-footer
문서를 Markdown으로 바꾸는 기본 명령 말고도 kordoc의 하위 명령 대부분이 exe에서 동작합니다. Markdown을 공문서 HWPX로 만드는 generate, 서식 빈칸을 채우는 fill, 개인정보를 가리는 redact, 공문서 표기법을 검사하는 lint, MCP 서버를 띄우는 mcp 등입니다. 하위 명령별 옵션은 저장소 README에 표로 정리해 두었습니다.
알아 둘 점
exe에서 안 되는 기능
OCR(--ocr, 이미지 입력)과 PNG·JPEG 래스터 출력(render --format png/jpeg, crop, tables --visual)은 동작하지 않습니다. 필요한 네이티브 바이너리를 exe 안에서 찾지 못하기 때문입니다. render --format pdf는 PC에 설치된 Chrome이나 Edge를 띄워 인쇄하는 방식으로 됩니다.
- 시험 스크립트(
scripts/test-exe.ps1)는 같은 명령을 exe와 upstream 원본 소스로 돌려 결과를 비교합니다. v4.15.6 기준으로 fixtures 21개가 모두 일치했습니다. - 암호 걸린 HWPX를
--password없이 넘기면 끝나지 않는 upstream 결함이 있어, 호출하는 쪽에서 미리 걸러야 합니다. - 이 저장소의 스크립트는 MIT입니다. kordoc도 MIT이며, 빌드 결과에 들어가는 원본의
LICENSE·NOTICE·THIRD_PARTY/는 배포할 때 빼면 안 됩니다.
소스와 전체 옵션 설명은 GitHub 저장소에 있습니다.