기능: /commands를 CLI가 내보낸 commands.json에서 렌더링

[Matwaetle]

한줄 요약

omm.run의 명령어 페이지가 이제 CLI가 직접 내보낸 파일을 그대로 읽어서 보여줍니다. CLI가 바뀌면 사이트도 따라 바뀌고, 안 따라오면 CI가 잡아냅니다.

배경

지금까지 omm <명령> --help가 알려주는 내용, GitHub README, 그리고 이 웹사이트는 서로 따로 관리됐습니다. 그래서 셋이 조금씩 어긋나도 아무도 모르고 지나갔습니다. 이 문제를 다루는 이슈가 omm-hippo/omm#347 입니다.

해결 방법은 "한 곳에서만 쓰고 나머지는 베껴온다"입니다. omm CLI 저장소가 자기 소스 코드(src/omm/cli.py)에서 명령어 목록을 뽑아 docs/commands.json 파일로 내보내고(CLI 쪽 PR: omm-hippo/omm#350), 이 사이트는 그 파일을 복사해서 화면에 그립니다. 사람이 손으로 옮겨 적는 단계가 없어집니다.

무엇을 바꿨나

• 명령어 설명 페이지(/commands/install 같은 곳) 맨 아래에 "CLI 레퍼런스" 칸이 생겼습니다. 사용법 한 줄, 받는 인자, 옵션 목록, 기본값이 터미널에서 보는 것과 글자 그대로 같습니다.
• omm setting, omm engine처럼 하위 명령이 있는 그룹은 하위 명령이 한 줄씩 펼쳐지고, 각각 바로 가는 주소가 생겼습니다. 예: /commands/setting#version
• --json, --yes처럼 모든 명령이 공통으로 받는 옵션은 명령마다 반복하지 않고 "공통 옵션" 한 칸에만 적었습니다.
• /commands 목록 페이지 아래에 CLI가 가진 전체 명령 표가 붙었습니다. 별칭(ls 같은 것)과 그룹의 하위 명령 개수도 함께 보입니다.
• 아직 사람이 해설을 쓰지 않은 새 명령(export, pin, rollback, unlink, unpin)도 자동으로 페이지가 생깁니다. 예전에는 CLI에 명령이 추가돼도 사이트에는 아무것도 없었습니다. 없는 이름을 치면 그대로 404입니다.
• 손으로 쓴 해설(개요·예제·실제 실행 화면·문제 해결)은 하나도 지우지 않았습니다. 기계가 만들 수 없는 부분은 그대로 두고, 기계가 만들 수 있는 사실만 자동화했습니다.
• 한국어 페이지도 같이 동작합니다. 화면의 안내 문구는 한국어지만, 명령어 이름과 옵션은 번역하지 않았습니다. 실제로 그렇게 입력해야 하기 때문입니다.
• 파일이 낡지 않게 하는 장치를 넣었습니다.
  • npm run sync-commands — CLI 저장소에서 최신 파일을 받아옵니다.
  • npm run check-commands — 받아온 것과 저장된 것이 다르면 실패하고, 어떤 명령이 달라졌는지 알려줍니다.
  • GitHub Actions가 PR마다, 그리고 하루 한 번 이 확인을 돌립니다.
  • 버전 번호(omm_version)는 릴리스마다 바뀌니 비교 대상에서 뺐습니다. 명령이나 옵션이 진짜로 바뀐 경우에만 실패합니다.
• 어디서 온 내용인지 design/FACTS.md와 README.md에 적어 뒀습니다. src/data/commands.json은 손으로 고치면 안 되는 파일입니다.

어떻게 확인했나

로컬에서 돌린 것:

npm ci
npm test          # 44개 통과 (레퍼런스 파일 검증 테스트 4개 새로 추가)
npm run lint      # 경고 0
npx tsc --noEmit  # 오류 0
npx next build    # 성공, 86개 페이지 생성

npm run build(OpenNext)는 Windows에서 exit 127로 멈춥니다. OpenNext가 원래 Windows를 지원하지 않는다고 경고하는 부분이라 이 PR과는 무관하며, CI는 리눅스에서 기존 워크플로로 같은 빌드를 돌립니다.

next build 결과에서 /[locale]/commands/[name]이 export, pin, rollback, unlink, unpin 5개 × 2개 언어 = 10개 페이지를 미리 만들어 두는 것을 확인했습니다.

브라우저(개발 서버)에서 직접 열어 본 것:

• /commands — 맨 아래 "CLI가 가진 모든 명령어" 표에 최상위 29개가 뜨고, omm engine에 "5 sub-commands", omm setting에 "11 sub-commands", omm list에 "alias: ls"가 붙어 있었습니다.
• /commands/install — 목차가 07까지 늘어났고, "CLI 레퍼런스" 칸에 omm install [OPTIONS] NAME과 인자·옵션·기본값이 떴습니다.
• /commands/setting#version — 주소를 치면 omm setting version 항목 위치로 정확히 이동했습니다.
• /commands/pin — 손으로 쓴 해설이 없는 새 명령인데도 레퍼런스 페이지가 정상으로 떴습니다.
• /commands/not-a-real-command — 404.
• /ko/commands, /ko/commands/list — 안내 문구는 한국어, 옵션은 원문 그대로였습니다.
• 휴대폰 너비(375px)에서 가로 스크롤이 생기지 않는 것을 확인했습니다. 사이트가 다크 전용이라 밝은 테마는 확인 대상이 아닙니다.

동기화 스크립트는 가짜 서버를 띄워 세 가지 경우를 직접 확인했습니다. 같으면 통과, 명령이 하나 늘면 실패하며 only upstream: teleport라고 알려주고, 버전 번호만 다를 때는 통과했습니다.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	omm	d3f1b8d	Commit Preview URL Branch Preview URL	Sep 16 2026, 12:19 PM