hanlulong/overleaf-sync-now

overleaf-sync-now은(는) 무엇을 하나요?

⚠ 중지 — "Overleaf에 로그인"을 제안하기 전에 읽으세요

사용자가 Windows에서 Chrome 130 이상을 사용하는 경우, 일상적인 브라우저에서 Overleaf에 로그인해도 인증 오류가 해결되지 않습니다. Chrome 130은 앱 바인딩 암호화(App-Bound Encryption)를 도입했습니다. 쿠키 데이터베이스 AES 키가 Chrome.exe 자체에 바인딩된 키로 두 번 감싸져 있으며, Windows COM을 통해 중개됩니다. Chrome.exe가 아니거나 관리자 권한으로 실행되지 않는 프로세스는 암호화된 바이트를 읽을 수는 있지만 복호화할 수 없습니다. 따라서 browser_cookie3와 rookiepy는 사용자가 최근에 로그인했는지 여부와 관계없이 실패합니다.

올바른 해결책은 overleaf-sync-now login입니다. 이 명령어는 제어되는 브라우저(Playwright로 관리되는 Chromium)를 실행하고, 사용자가 거기서 한 번 로그인하면 Chrome DevTools Protocol을 통해 쿠키를 읽습니다. 브라우저 내부에서 오는 요청이기 때문에 일반 텍스트로 반환됩니다. 로그인은 우리 프로필에 수주 동안 유지됩니다.

문제

Overleaf의 Dropbox 브리지는 단방향(Overleaf → Dropbox)으로 10~20분마다 폴링하므로, 로컬 Dropbox 미러링된 .tex 파일이 그만큼 오래된 상태일 수 있습니다. 이 스킬은 Overleaf의 버전 기록(GET /project/{id}/updates)을 조회하고, 실제 웹 기반 변경이 있으면 프로젝트 zip(GET /project/{id}/download/zip)을 다운로드하여 변경된 파일만 추출합니다. 사용자의 기존 Dropbox 브리지 설정을 변경하지 않으므로, 기기 간 Dropbox 동기화는 이전과 동일하게 작동합니다.

프로젝트 조회 방식

• 자동 연결 (설정 불필요, 권장): 파일이 …/Apps/Overleaf/<프로젝트-이름>/ 아래에 있으면, 스킬이 사용자의 Overleaf 프로젝트 목록(24시간 캐시, 0.3.0 이후 projects.json v2)에서 <프로젝트-이름>을 조회합니다. 캐시된 목록에는 trashed/archived/lastUpdated/ownerId가 포함되어 있어, 확인자가 기본적으로 휴지통/보관된 프로젝트를 필터링하고, 두 개의 활성 프로젝트가 이름을 공유할 때 추측을 거부합니다.
• 마커 자동 쓰기 (0.3.0 이후): 성공적인 자동 연결 시 확인자가 프로젝트 폴더에 작은 .overleaf-project JSON 마커를 작성하여 이후 조회 시 인덱스 조회를 완전히 건너뜁니다. 마커에는 project_id + 출처(source, linked_at, name_at_link_time)가 포함됩니다.
• 수동 연결 (재정의): 사용자에게 같은 이름의 활성 프로젝트가 두 개 있거나(또는 로컬 폴더 이름이 일치하지 않는 경우) 확인자가 추측을 거부하고 모든 후보와 함께 복사하여 붙여넣을 수 있는 정확한 overleaf-sync-now link <id> <folder> 명령어를 출력합니다. 해당 명령어를 실행하여 마커를 명시적으로 작성하십시오. {"project_id": "..."}만 포함된 이전 마커 파일도 계속 작동합니다.

sync가 경고하거나 거부하는 경우

• auto-link: N non-trashed Overleaf projects named <이름>. Refusing to guess. — 두 개 이상의 라이브 프로젝트가 폴더 이름을 공유합니다. 스킬이 ID, 마지막 업데이트 타임스탬프, 보관 여부 플래그와 함께 후보를 나열합니다. 사용자에게 하나를 선택하고 출력된 link 명령어를 실행하라고 알리세요. 사용자를 대신하여 프로젝트 ID를 선택하지 마십시오.
• WARN: marker at <폴더> -> <id> is trashed/archived on Overleaf — 사용자가 명시적으로 오래된 프로젝트에 연결했습니다. 동기화는 진행되지만 사용자는 아마도 overleaf-sync-now link <other_id> <폴더>를 실행하여 활성 프로젝트에 다시 연결하고 싶을 것입니다.
• WARN: project <id> has recent Dropbox-origin updates touching files not present in <폴더> — 링크가 완전히 잘못된 프로젝트(오타가 있는 수동 링크, 포크, 또는 이전 방어에서 잡히지 않은 동일 이름 중복)를 가리키고 있다는 강력한 신호입니다. 사용자에게 overleaf-sync-now status와 overleaf-sync-now projects를 실행하여 확인하고 link로 수정하도록 하세요.

인증 — 사용자에게 어떤 방법을 사용할지 묻지 마세요

스크립트가 자체적으로 인증을 처리합니다. 다음 순서(자동)로 시도합니다: 캐시된 쿠키 → rookiepy (Chrome 127+ 호환) → browser_cookie3 → Claude Code의 Playwright 프로필 → 수동 붙여넣기 프롬프트.

그냥 overleaf-sync-now setup (또는 install)을 실행하세요. "자동 감지 또는 수동 붙여넣기를 원하십니까?"라고 묻지 마십시오. 스크립트가 사용 가능한 최상의 소스를 선택합니다.

인증 실패 시 (사용해야 할 복구 흐름)

setup이 "AUTO-DETECT FAILED"를 보고하거나 sync가 "No valid Overleaf cookies" 오류를 반환하면, 올바른 복구는 overleaf-sync-now login입니다 (브라우저 지원, Chrome 130+ Windows를 포함한 모든 플랫폼에서 작동). 사용자에게 일상적인 브라우저에서 "로그인"하라고 제안하지 마십시오. Chrome 130+ Windows에서는 도움이 되지 않습니다.

복구 흐름:

1. overleaf-sync-now doctor를 실행하여 어떤 자동 소스가 실패했는지 확인합니다.
2. 사용자에게 말하세요: "터미널에서 overleaf-sync-now login을 실행하세요. 브라우저 창이 열립니다. 거기서 Overleaf에 로그인하세요. 브라우저의 API를 통해 쿠키를 캡처합니다."
3. (첫 실행 시 Playwright + Chromium이 자동 설치되며, 약 150MB, 일회성입니다.) 브라우저가 overleaf.com으로 열리고 사용자가 로그인하면, 스크립트가 Chrome DevTools Protocol을 통해 쿠키를 캡처합니다(디스크 복호화 불필요). 로그인은 프로필에 유지됩니다.
4. 사용자가 로그인 완료를 확인한 후 overleaf-sync-now status를 실행하여 확인한 다음 원래 동기화를 다시 시도하세요.

login을 실행할 수 없는 환경(디스플레이 없음, 서버 등)을 위한 대체 방법: save-cookie <값>. 사용자에게 F12 → 애플리케이션 → 쿠키 → overleaf.com에서 overleaf_session2 값을 복사한 다음 overleaf-sync-now save-cookie "<값>"을 실행하도록 요청하세요. login을 사용할 수 있을 때는 이것에 의존하지 마십시오. login이 더 안정적입니다.

하위 명령어

CLI는 overleaf-sync-now입니다 (uv tool install을 통해 전역 설치).

setup

인증 마법사입니다. 자동 감지 체인을 실행합니다. 대화형 모드에서는 수동 붙여넣기 프롬프트도 표시합니다. 한 번 실행하면 수주 동안 캐시됩니다.

login

브라우저 기반 로그인(Playwright + Chromium)입니다. setup이 자동 감지할 수 없을 때(Windows의 Chrome 130+ 앱 바인딩 암호화 사례 포함) 올바른 해결책입니다. 위의 복구 흐름을 참조하세요.

save-cookie <값>

최후의 수단: 브라우저의 F12 → 애플리케이션 → 쿠키 창에서 붙여넣은 overleaf_session2 쿠키 값을 저장합니다. login을 실행할 수 없을 때만 사용하십시오(디스플레이 없음 / CI / 서버).

sync [폴더] [--force]

폴더(또는 현재 디렉토리)를 소유한 프로젝트를 Overleaf와 동기화합니다.

• /project/<id>/updates를 조회합니다. 변경 사항이 없거나 모든 새 업데이트가 우리가 저장한 Dropbox 기반 왕복인 경우 건너뜁니다. 그렇지 않으면 zip을 다운로드하고 웹 기반 업데이트가 아직 로컬에 반영되지 않은 파일만 추출합니다.
• --force: 항상 zip을 다운로드하고 다시 추출합니다. 해시 비교는 여전히 바이트가 이미 로컬과 일치하는 파일을 건너<0xEB><0x9B><0x84>니다. 또한 30초 최근 수정 시간 가드를 비활성화합니다(아래 참조).

데이터 안전: 기본적으로 sync는 지난 30초 이내에 수정된 로컬 파일을 덮어쓰지 않으며, stderr에 SKIP <경로>를 출력합니다. 이는 아직 Dropbox → Overleaf로 전파되지 않은 진행 중인 로컬 저장을 보호합니다. 재정의하려면 --force를 전달하세요.

호출 시점: 사용자가 "Overleaf에서 최신 버전 가져오기"를 요청할 때 수동으로, 또는 Codex CLI에서 편집 전에 자동으로(Codex의 PreToolUse 훅은 Windows에서 안정적이지 않습니다).

status [폴더]

데이터 디렉토리, 쿠키 유효성, 연결된 프로젝트, 마지막 동기화 시간, 캐시된 Overleaf 버전(toV)을 보고합니다. 샌드박스로 인한 네트워크 차단과 실제 인증 실패를 구분합니다.

projects [--refresh]

사용자의 Overleaf 프로젝트(이름 + ID) 목록을 표시합니다. --refresh는 인덱스 재조회를 강제합니다.

doctor [폴더]

진단 덤프: 쿠키 캐시 상태, 브라우저별 쿠키 추출, Playwright 프로필, 인증 체인 해결, 주어진 폴더의 연결된 프로젝트에 대한 라이브 /updates 프로브.

link <project_id> [폴더]

.overleaf-project 마커를 작성합니다. 비표준 폴더 레이아웃(즉, Apps/Overleaf/<이름>/이 아닌 경우)에만 필요합니다.

hook

Claude Code용 PreToolUse 훅 진입점입니다. stdin에서 JSON을 읽습니다. 수동 사용용이 아닙니다.

install

멱등성 설치 후 설정: SKILL.md를 ~/.claude/skills/overleaf/ 및 ~/.codex/skills/overleaf/(존재하는 쪽)에 복사하고, Claude Code PreToolUse 훅(매처 Read|Edit|Write|MultiEdit)을 설치/업데이트하며, 인증 체인을 실행합니다. 업그레이드 후 다시 실행하세요.

uninstall

스킬 설치와 훅을 제거합니다. 쿠키는 유지됩니다.

샌드박스 참고 사항 (Codex CLI, 제한된 셸)

네트워크를 사용하는 하위 명령어(sync, status, login, doctor, setup)가 소켓 권한 오류로 실패하는 경우 — Windows WinError 10013 / 액세스 권한에 의해 금지됨, POSIX EACCES / EPERM / "Permission denied" — 호스트 셸이 아웃바운드 HTTPS 호출을 차단하고 있는 것입니다. 이는 인증 문제가 아닙니다.

도구는 이 경우를 특별히 감지하여 다음과 같이 출력합니다:

Outbound HTTPS to Overleaf was blocked by the host environment (likely a sandboxed shell — Codex CLI, some CI runners). Auth is probably fine; running setup/login/doctor will fail the same way. Approve the overleaf-sync-now command prefix in your sandbox policy, or re-run outside the sandbox.

해당 메시지(또는 위의 errno 표시)가 표시되면:

• setup / login / doctor를 실행하지 마십시오. 모두 동일하게 차단된 소켓에 접근합니다.
• 사용자에게 샌드박스(Codex CLI의 항상 승인 목록)에서 overleaf-sync-now 명령어 접두사를 승인하거나, 샌드박스 외부에서 다시 실행하도록 요청하세요.
• status는 이 경우 INVALID 대신 Cookie auth: UNKNOWN — outbound HTTPS is blocked ...을 출력하므로 추측할 필요가 없습니다.

이 스킬을 호출해야 하는 경우

• Claude Code: 드물게 — 훅이 편집을 자동으로 처리합니다. 명시적인 사용자 요청이 있을 때만 sync를 호출하거나, 첫 번째 설정을 위해 setup/link를 호출하세요.
• Codex CLI on Windows: Apps/Overleaf/ 아래의 .tex/.bib/.cls/.sty/.bst 파일을 편집/쓰기하려고 할 때마다 먼저 sync를 호출하세요. (Codex 훅은 Windows에서 편집 전에 안정적으로 실행되지 않습니다.)
• 사용자가 오래된 Overleaf 콘텐츠를 언급하는 경우: sync를 호출하세요.
• 사용자가 Overleaf 동기화 설정을 요청하는 경우: setup(또는 아직 Claude/Codex 스킬 디렉토리에 연결되지 않은 경우 전체 install)을 호출하세요.

실패 모드 및 복구

• "No valid Overleaf cookies found. Run setup": 쿠키가 만료되었거나 설정되지 않았습니다. overleaf-sync-now setup을 실행하세요. 체인이 캐시 → 브라우저 → Playwright를 시도합니다. 대화형 모드에서는 수동 붙여넣기로 넘어갑니다.
• setup이 브라우저 쿠키를 찾을 수 없음: 사용자가 Chrome/Edge/Firefox에서 overleaf.com에 로그인하지 않았을 수 있습니다. 거기에 로그인하거나, 프롬프트가 표시될 때 쿠키를 수동으로 붙여넣으세요.
• 자동 연결이 프로젝트를 찾을 수 없음: 폴더 이름이 Overleaf 프로젝트 이름과 일치하지 않습니다. 폴더 안에서 link <project_id> .를 사용하세요.

보안 참고 사항

캐시된 쿠키는 사용자의 Overleaf 계정에 대한 전체 액세스 권한을 부여합니다. 기본 사용자 권한으로 ~/.overleaf-sync/cookies.json에 저장됩니다. 커밋하거나 공유하지 마십시오.