컴윗 클라우드 개발 도구 설치·로그인 안내
https://comwit.io/install.txt

이 문서는 프로젝트 설정을 돕는 AI 에이전트가 읽는 안내문입니다.
셸 스크립트가 아니므로 이 문서 자체를 sh/bash에 넘겨 실행하지 마세요.
프로젝트 핸드오프에서 도구나 로그인이 준비되지 않았을 때 필요한 항목만 진행하세요.
완료하면 원래 핸드오프로 돌아가 저장소와 .env 등 프로젝트별 설정을 이어갑니다.

진행 원칙
- 사용자는 비개발자입니다. 설치·설정은 에이전트가 실행하고 진행 상황은 일상 언어로 짧게 알려주세요.
- 이미 설치되어 정상 작동하는 도구는 재설치하지 않습니다. 로그인도 유효하면 그대로 사용합니다.
- 비밀번호·관리자 권한, 설치창, 라이선스 동의처럼 사용자가 직접 해야 하는 일이 생기면 미리 안내하세요.
- 토큰 원문은 대화·로그·명령 인자에 넣지 않습니다. 기기 승인 URL과 일회용 user code만 사용자에게 보여줍니다.
- 설치나 확인에 실패하면 원인을 알리고 해당 단계에서 멈추세요. 실패한 채 완료로 보고하지 않습니다.

1. 작업 환경과 설치 상태 확인

먼저 OS와 셸을 확인합니다. 설치, 로그인, 저장소 작업, 프로젝트 설정을 모두 같은 환경에서 진행하세요.
Comwit CLI 설치 스크립트는 macOS와 Linux를 지원합니다.
Windows에서는 WSL(Ubuntu 등)을 사용하세요. WSL이 없거나 현재 앱에서 WSL 프로젝트를 사용할 수 없으면 필요한 준비를 사용자에게 안내하고 멈춥니다.
Windows에 설치된 도구만 확인하고 WSL 안에도 설치됐다고 판단하지 마세요.

다음 명령을 각각 실행합니다.
  node --version
  git --version
  pnpm --version
  comwit version

Node.js는 22.9 이상, Comwit CLI는 0.1.10 이상이어야 합니다.
Comwit CLI 0.1.10부터 로그인 시 Comwit Cloud Git credential helper를 등록합니다.
네 도구가 이미 준비되어 있으면 설치를 건너뛰고 로그인 확인으로 이동하세요.

2. 없는 기본 도구만 설치

Git과 Node.js는 OS의 표준 패키지 관리자 또는 공식 설치 방법으로 준비합니다.
- macOS: Git이 없으면 xcode-select --install을 실행하고 설치 팝업을 안내하세요.
  Node.js가 없거나 기준보다 낮으면 공식 Node.js LTS 설치 방법이나 기존 패키지 관리자를 사용합니다.
- Linux와 WSL: 배포판 패키지 관리자로 Git과 curl을 설치합니다.
  Ubuntu/Debian에서 없는 항목은 sudo apt update 후 sudo apt install -y git curl로 준비할 수 있습니다.
  Node.js는 기본 패키지 버전이 너무 낮을 수 있으므로 22.9 이상인 LTS를 선택하세요.
  기존 Node 버전 관리자가 있으면 그 방식을 유지합니다.
- Node.js 공식 설치 안내: https://nodejs.org/en/download
- Git 공식 설치 안내: https://git-scm.com/downloads

pnpm이 없으면 Node.js 설치 후 다음 명령으로 준비합니다.
  npm i -g pnpm
이 명령은 pnpm 자체를 준비하기 위한 것입니다. 프로젝트 의존성 설치에는 pnpm을 사용합니다.

CLI 설치에 필요한 curl, tar 및 체크섬 도구(sha256sum 또는 shasum)가 있는지도 확인하고, 없으면 OS 패키지 관리자로 준비하세요.
설치 후 현재 셸의 경로를 반영하고 새 셸에서도 node, git, pnpm의 버전이 정상으로 나오는지 확인합니다.

3. Comwit CLI 설치·갱신

먼저 comwit version을 확인하세요.
명령이 없거나 0.1.10 미만이면 아래 공식 설치 명령을 실행합니다.
지원 버전이 이미 설치돼 있으면 건너뜁니다. 이후 핸드오프에서 요구하는 명령을 지원하지 않는 경우에도 같은 명령으로 최신 버전으로 갱신합니다.

  curl -fsSL https://raw.githubusercontent.com/burrr-ai/comwit-cli/main/install.sh | sh

설치 스크립트는 OS와 CPU에 맞는 릴리스 바이너리를 내려받아 체크섬을 확인한 뒤 설치합니다.
설치 위치는 /usr/local/bin 또는 사용자 홈의 .local/bin이며 실제 출력된 경로를 따르세요.
"add … to your PATH"가 나오면 안내된 폴더를 현재 셸과 새 셸의 PATH에 반영합니다.
현재 사용하는 앱에서 실행하는 명령에도 적용되고 재로그인 뒤에도 유지되도록 설정하세요.
현재 셸과 새 셸에서 comwit version을 다시 실행해 설치 성공과 버전을 확인합니다.
이미 열린 앱에 경로가 반영되지 않으면 앱을 완전히 종료했다가 다시 열도록 안내하세요.

4. Comwit Cloud 로그인 확인

  comwit projects list

명령이 성공하고 저장소 호스트의 CLI Git credential helper도 등록되어 있으면 기존 로그인을 사용합니다.
핸드오프에 Cloud 프로젝트 ID가 있으면 목록에 그 ID가 있는지 확인합니다. 프로젝트 이름으로 대체하지 마세요.
인증이 유효한데 프로젝트 권한이 없으면 사용자에게 알리고 멈춥니다.
네트워크·서버 오류를 로그인 만료로 간주해 반복 로그인하지 마세요.

로그인이 없거나 만료됐거나 CLI Git credential helper가 없으면 다음 명령을 실행합니다.
  comwit login

- CLI가 출력한 승인 URL과 일회용 user code를 그대로 보여주고 "브라우저에서 Comwit Cloud에 로그인한 뒤 이 코드를 입력하고 승인해 주세요."라고 안내합니다.
- 브라우저가 자동으로 열리지 않으면 CLI가 출력한 승인 URL을 직접 열 수 있게 알려주세요.
- 로그인·코드 입력·승인은 사용자 대신 수행하지 않습니다.
- CLI가 "Logged in"으로 끝날 때까지 기다리고 "git access configured"도 확인합니다.
- 거부·만료·시간 초과면 이유를 알리고 멈춥니다. 사용자가 다시 진행하겠다고 한 뒤에만 로그인을 재시도합니다.
- comwit login --token이나 임시 토큰으로 우회하지 않습니다. 토큰을 clone 주소나 Git 비밀번호에 직접 넣지 마세요.
- 로그인 후 comwit projects list를 다시 확인합니다. Git helper 등록이 실패했으면 원인을 해결하기 전에는 저장소 작업으로 넘어가지 않습니다.

5. 원래 프로젝트 핸드오프로 복귀

같은 작업 환경에서 node --version, git --version, pnpm --version, comwit version이 모두 정상인지 다시 확인합니다.
로그인과 대상 프로젝트 권한도 확인되면 "개발 도구 준비가 끝났어요. 프로젝트 설정을 이어갈게요."라고 안내하고 원래 핸드오프를 이어가세요.
.env 생성·병합, CLI 토큰의 비노출 병합, MCP 확인과 프로젝트 의존성 설치는 핸드오프에 있는 프로젝트별 명령을 사용합니다.
이 문서를 따라 별도 MCP PAT을 발급하거나 공통 토큰을 OS 전역 환경변수로 등록할 필요는 없습니다.