크라우니 자산교환 안내 v2 (vpn.crowny.org) ========================================== 이 글은 옆 기기(다른 맥)의 클로드가 읽고 스스로 설치·동기화하기 위한 안내입니다. 서버 주소: https://vpn.crowny.org (이 안내 = GET /vpn/asset/guide, 패키지 안에도 자산/안내.txt 로 들어 있음) [한 줄 요약] - 이 맥(kpsmac)과 옆 기기가 서로의 학습 자산을 "읽기 전용"으로 주고받습니다. - 받은 자산은 내 정본을 절대 바꾸지 않고, 별도의 단계 저장소에만 쌓입니다. - 정본에 넣는 것은 사장님이 명령했을 때뿐입니다(자동 편입 없음). [1줄 설치] (<아이디> 자리에 본인의 크라우니 통합 아이디) curl -fsS -m 30 https://vpn.crowny.org/vpn/asset/install.sh | bash -s -- <아이디> 옵션: --no-agent (LaunchAgent 를 만들지 않음) --url <주소> (기본 https://vpn.crowny.org) · 하는 일(순서): 패키지 받기·해제(~/.crowny-asset/) -> 가입(join) -> LaunchAgent(5분마다 tick) -> 첫 교환(sync: 받기+보내기) -> 단계 저장소 status 출력 · 여러 번 실행해도 안전합니다(멱등): 같은 파일은 다시 쓰지 않고, 바뀐 파일은 <파일>.prev 로 1벌 보관하고, 이미 가입되어 토큰이 유효하면 로그인을 건너뜁니다. · 필요한 것: macOS 기본 도구만 (bash 3.2, curl, tar, shasum, gzip, awk, sort). python/node/jq 불필요. crownyc 는 있으면 쓰고 없어도 됩니다. · 이 맥도 같은 패키지입니다. 이 맥은 자기 정본을 읽어 공개(1-원본)하고, 옆 기기가 올린 자산을 단계 저장소에 흡수합니다. [비밀번호 취급 - 중요] - 비밀번호는 명령줄 인자(argv)로 절대 넘기지 않습니다. 프롬프트(터미널) 또는 환경변수 CROWNY_ASSET_PW 로만 받습니다. - 1줄 설치는 stdin 이 파이프라서, 비밀번호는 /dev/tty(본인 터미널)에서 물어봅니다. - 클로드의 셸 도구에는 터미널(tty)이 없어 비밀번호를 물을 수 없습니다. 이때 설치는 안내를 출력하고 멈춥니다(exit 3, 패키지는 이미 배치됨). -> 사용자에게 "본인 터미널 창에서 위 1줄을 직접 실행하고 비밀번호를 입력해 달라" 고 요청하세요. (비밀번호를 대화창·로그·파일에 적지 마세요.) - 한 번 가입하면 토큰이 저장(~/.crowny-asset/token, chmod 600)되어 이후 pull/push/sync/update 는 비밀번호 없이 실행됩니다. [아이디는 어떻게 고르나] - 아이디 = 사장님이 만들어 준 본인의 크라우니 통합 계정입니다. 새 계정을 임의로 만들지 마세요. - 권한은 사장님이 이 맥의 기기열람.psv 에 "<아이디>|kpsmac" 행을 넣어서 부여합니다. 행이 없으면 로그인은 되어도 자산교환은 403 입니다. - 어떤 아이디로 할지 모르겠으면 추측하지 말고 사용자(사장님)에게 물어보세요. [읽기전용 원칙 — 정본은 절대 수정되지 않습니다] - "정본" = 저장소 4종의 실제 파일 (학습.dat, all_patterns.dat, 규칙저장소.dat, 의미어_index.dat — $HOME/<저장소 상대경로>). - 교환 코드는 정본을 "읽기만" 합니다: 보낼 줄(로컬 - 기준선) 계산과 sha 확인에만 씁니다. pull 이 정본에 쓰는 일은 없습니다. pull 전후로 정본 sha 를 대조하고, 바뀌었으면 "정본쓰기금지 위반" 으로 실패 처리합니다(옛 흡수엔진이 남아 있는 경우 -> update). - 받은 자산이 쌓이는 곳(단계 저장소, 루트 = ~/.crowny-asset/자산, 환경변수 CROWNY_ASSET_ROOT 로 변경 가능): 1-원본/ 내 정본의 공개용 스냅숏(이 맥이 공개할 때) 2-수신/<기기>/<저장소>/ 받은 그대로(불변 이력) 3-검증/<기기>/<저장소>.dat 판정 "티" 줄의 합집합(현재 뷰) — 조회 시 읽기 오버레이로 함께 보임 4-격리/ 충돌·의심·형식불량 줄(사유 포함) — 사장님 판단 대기 5-승인/ 사장님이 승인한 줄 장부/ 로그/ 작업/ 현재 상태 표: bash ~/.crowny-asset/자산정돈.sh status - 정본으로 "편입" 하는 것은 사장님이 명시적으로 명령한 경우(편입 명령)뿐이며, 자동으로는 실행되지 않습니다. 클로드도 사장님 명령 없이 편입하지 마세요. [되돌리기 — 옛 v1 이 정본에 붙여 넣은 줄 원상복구] - v1 은 받은 줄을 정본에 append 했습니다. 그걸 원래대로 돌립니다: bash ~/.crowny-asset/자산교환.sh 되돌리기 <저장소이름> [--dry] 예) 되돌리기 학습 --dry (먼저 예고만 확인) - 근거가 있을 때만 복원합니다(추측 복원 없음): <정본>.bak_asset_1/2(옛 흡수엔진 백업)가 "현재 정본의 정확한 앞부분"(sha 일치)이고, 흡수장부에 그 저장소의 병합 기록이 있고, 기준선(기준/<저장소>.dat)이 있을 때. 하나라도 없으면 "복원 불가"(exit 1)로 끝나며 정본은 그대로입니다. - 되돌릴 대상은 "백업 이후에 붙은 줄 중 원격 스냅숏에서 온 줄" 뿐입니다. 그 뒤 이 기기가 새로 만든 줄(보낸 줄 포함)은 지우지 않고 보존합니다. - 복원 직전 정본 사본이 ~/.crowny-asset/상태/되돌리기전-<저장소>-<시각>.dat 에 남습니다. 다시 실행해도 안전합니다(더 되돌릴 줄이 없으면 아무 것도 안 함). [갱신 — update] bash ~/.crowny-asset/자산교환.sh update 서버 /vpn/asset/version 과 비교 -> 새 버전이면 package.tar.gz 재수신·해제(이전 파일은 .prev)·LaunchAgent 재설치 bash ~/.crowny-asset/자산교환.sh update --force 같은 버전이어도 다시 받기 bash ~/.crowny-asset/자산교환.sh version 내 설치 버전 표시 - 같은 버전이면 "이미 최신 - 건너뜀", 서버 버전이 더 낮으면 다운그레이드하지 않습니다. - v1 로 이미 가입한 기기는 update 한 번이면 v2 로 바뀝니다(토큰·가입 상태는 유지). 이어서 sync 를 실행하세요. [지금 받아오기 — 이 맥이 요청하면 5분 안에 보냅니다] - 이 맥(kpsmac)의 사장님/세션이 "지금 받아오기"를 요청하면, 이 기기는 5분 안에 sync(push)해서 새 학습자산을 이 맥에 보냅니다. (요청이 없어도 마지막 sync 후 30분이 지나면 tick 이 정기 sync 를 합니다.) - tick(LaunchAgent 가 5분마다 실행, 요청 1회로 가볍다): GET /vpn/asset/request/pending -> 대기 요청이 있으면 즉시 sync 후 POST /vpn/asset/request/done?reqid=..&result=ok|fail 로 결과 보고 / 없으면 마지막 sync 가 30분 이상 전일 때만 sync. - 요청은 서버(이 맥)가 자산/요청.psv 에 기록하며, 6시간이 지난 미완료 요청은 만료되어 무시됩니다. [확인 명령] bash ~/.crowny-asset/자산교환.sh status # 저장소별 기준선·마지막 pull/push·버전·서버 상태 bash ~/.crowny-asset/자산정돈.sh status # 단계 저장소(2-수신/3-검증/4-격리/5-승인) 기기·저장소·행수·용량 표 bash ~/.crowny-asset/자산교환.sh pull # 받기(단계 저장소에만 기록, 정본 무수정) bash ~/.crowny-asset/자산교환.sh push --dry # 무엇을 보낼지 개수만 확인(전송 안 함) bash ~/.crowny-asset/자산교환.sh push # 보내기(정본에서 "로컬 - 기준선" 계산해 새 줄만, 깨진 UTF-8 줄 제외) bash ~/.crowny-asset/자산교환.sh sync # pull -> push bash ~/.crowny-asset/자산교환.sh tick # LaunchAgent 가 5분마다 실행하는 가벼운 진입점 bash ~/.crowny-asset/자산교환.sh agent # LaunchAgent(5분 tick) 설치·재설치 (--no-agent 로 가입한 기기에서 나중에 켜고 싶을 때) bash ~/.crowny-asset/자산교환.sh selftest # 네트워크 없이 자체 점검 bash ~/.crowny-asset/자산교환.sh uninstall # LaunchAgent·토큰 제거 (--purge: ~/.crowny-asset 전체 삭제; 정본 파일은 건드리지 않음) - 정상 pull: "[pull] 학습: 원격 변경 - 팩 내려받기" 뒤 "흡수(...)" 줄. 변경 없으면 "최신(원격 sha 동일 - 건너뜀)". - 정상 push: "신규 N줄 -> 청크 M개" 뒤 "커밋 완료 - N줄 ... 흡수대기". 보낼 게 없으면 "신규 0줄" 또는 "최신". - 정본 파일이 이 기기에 없는 저장소는 push 를 건너뛰고(정본을 만들지 않음), pull 은 단계 저장소에만 기록합니다. - 로그: ~/.crowny-asset/로그/자산교환.log (비밀번호·토큰은 기록되지 않음) [문제해결] 종료코드/증상 원인 -> 조치 --------------------------------------------------------------------------------- 401 (exit 41) 토큰이 없거나 만료 -> 1줄 설치(또는 join)를 다시 실행(사용자가 비밀번호 입력). 가입 중 401 이면 아이디/비밀번호 오류입니다. 403 (exit 43) 이 아이디에 권한 없음 -> 사장님께 "기기열람.psv 에 <아이디>|kpsmac 추가"를 요청. 부여되면 같은 명령을 그냥 다시 실행하면 됩니다(재가입 불필요). 설치 자체는 이미 끝난 상태입니다. 422 (exit 44) push 한 청크가 서버에서 "줄 바이트가 달라짐" 으로 거절됨 = 깨진 줄(UTF-8 이 문자 중간에서 잘림)이 섞임. 클라이언트는 깨진 UTF-8·NUL 줄을 보내기 전에 걸러냅니다(~/.crowny-asset/tmp/<저장소>.bad 에 보관). 그래도 나면 update 로 최신 클라이언트를 받고 재시도하세요. 이 줄들은 정본 파일 자체가 손상된 것이니 사장님께 보고(정본은 고치지 마세요). 게이트웨이/프록시가 본문을 바꿔도 같은 422 가 납니다 -> 한 번 재시도, 반복되면 사장님께 보고. 000 (exit 40) 서버에 연결 못 함. 클라이언트가 먼저 https://vpn.crowny.org 로 시도하고, 000 이면 자동으로 --resolve vpn.crowny.org:443:192.168.219.153 (이 맥의 LAN 주소)로 다시 시도합니다(install.sh 도 같음). 둘 다 실패하면: (1) 두 맥이 같은 공유기 LAN 인지, (2) 이 맥이 켜져 있는지, (3) LAN 주소가 바뀌었으면 CROWNY_ASSET_LANIP=<이 맥 LAN IP> 를 앞에 붙여 실행. 수동 확인: curl -sS -m 8 -o /dev/null -w '%{http_code}\n' https://vpn.crowny.org/vpn/health (200 이어야 함) exit 3 (install) 비밀번호를 물을 tty 가 없음 -> 본인 터미널에서 실행하거나 CROWNY_ASSET_PW='<비밀번호>' 를 앞에 붙여 재실행. "정본쓰기금지 위반" 흡수엔진이 정본을 바꿈(옛 v1 엔진 잔존) -> update 로 엔진 교체, 이미 붙은 줄은 되돌리기 <저장소>. 200 인데 실패 메시지 "위장 응답": 200 이어도 본문이 기대한 JSON/스크립트/tar 가 아니면(로그인 페이지 등) 실패로 처리합니다. 서버 쪽 문제이므로 사장님/이 맥 담당 세션에 보고. sha 불일치 받은 팩이 manifest 와 다름 -> 기준선·단계 저장소는 건드리지 않고 중단됩니다. 잠시 뒤 pull 재시도. 400 sha_mismatch push 커밋 검증 실패(전송 손상) -> 다음 실행에서 자동 재전송됩니다. "기준선 없음" pull 을 먼저 실행(기준선 = 원격 스냅숏이 있어야 "로컬 - 기준선"을 계산할 수 있음). "다른 자산교환 실행 중" LaunchAgent 와 수동 실행이 겹친 것 -> 잠시 뒤 재실행(자동으로 건너뜀). 흡수엔진 없음 update 를 실행. 복원 불가(되돌리기) 백업·장부·기준선 중 하나가 없거나 백업이 정본의 앞부분이 아님 -> 정본은 그대로. 사장님께 보고(수동 판단). [로컬네트워크 권한 창이 안 뜨는 이유] - 이 방식은 SSH·화면공유·LAN 직접 소켓이 아니라 공개 HTTPS(443) 요청 한 종류만 씁니다. macOS 의 "로컬 네트워크" 권한 팝업 대상(LAN 장치 직접 탐색)이 아니고, SSH 키 등록도 필요 없습니다. - 000 폴백도 같은 443 포트로 이 맥의 LAN 주소에 접속할 뿐이며(--resolve), 별도 포트·서비스를 열지 않습니다. - 그래도 팝업이 뜨면 "허용"이 아니라 사용자에게 알리고 멈추세요(다른 프로세스일 수 있음). [하지 말 것] - 비밀번호·토큰(~/.crowny-asset/token)을 대화·로그·커밋에 붙이지 않기. 토큰 파일 권한은 600 유지. - 정본 저장소 파일을 직접 고치거나 덮어쓰지 않기. 교환은 정본을 읽기만 합니다. (되돌리기는 사장님 요청이 있을 때만) - 단계 저장소(자산/2-수신 ... 5-승인)와 ~/.crowny-asset/기준/·상태/ 를 손으로 편집하지 않기(판정이 어긋납니다). 편입은 사장님 명령으로만. - 서버 쪽 파일·다른 사용자 자산에 접근을 시도하지 않기(권한은 기기열람.psv 가 유일한 기준입니다). [환경변수(고급)] CROWNY_ASSET_NO_LAUNCHCTL=1 시험용 — plist 만 쓰고 launchctl 은 부르지 않음 CROWNY_ASSET_URL 기본 https://vpn.crowny.org CROWNY_ASSET_LANIP 기본 192.168.219.153 (000 폴백 주소) CROWNY_ASSET_HOME 정본 루트(기본 $HOME) — 읽기 전용 CROWNY_ASSET_ROOT 단계 저장소 루트(기본 ~/.crowny-asset/자산) CROWNY_ASSET_CLIENT_DIR 클라이언트 디렉토리(기본 ~/.crowny-asset) CROWNY_ASSET_PW 가입용 비밀번호(argv 대신, 프롬프트가 불가능한 환경에서만)