hanlulong/overleaf-sync-now

overleaf-sync-now は何をしますか？

⚠ 注意 — 「Overleaf にログイン」を提案する前にお読みください

ユーザーが Windows で Chrome 130 以降を使用している場合、日常的に使用するブラウザで Overleaf にログインしても認証エラーは修正できません。 Chrome 130 では App-Bound Encryption が追加されました。Cookie データベースの AES キーが、Windows COM を介して Chrome.exe 自体にバインドされたキーで二重にラップされます。Chrome.exe 以外のプロセス（管理者として実行している場合を除く）は、暗号化されたバイトを読み取ることはできますが、復号化することはできません。そのため、browser_cookie3 や rookiepy は、ユーザーが最近ログインしたかどうかに関係なく失敗します。

適切な修正方法は overleaf-sync-now login です。 制御されたブラウザ（Playwright 管理の Chromium）を起動し、ユーザーがそこで一度ログインすると、Chrome DevTools Protocol を介して Cookie を読み取ります。このリクエストはブラウザ内部から発行されるため、平文で結果が返ってきます。ログインはプロファイルに数週間保持されます。

問題

Overleaf の Dropbox ブリッジは一方向（Overleaf → Dropbox）で 10～20 分ごとにポーリングするため、ローカルの Dropbox ミラーリングされた .tex ファイルはその分古くなる可能性があります。このスキルは、Overleaf のバージョン履歴（GET /project/{id}/updates）を調査し、実際に Web 発信の変更があった場合、プロジェクトの ZIP ファイル（GET /project/{id}/download/zip）をダウンロードして、変更されたファイルのみを抽出します。ユーザーの既存の Dropbox ブリッジ設定は変更しないため、デバイス間の Dropbox 同期は以前と同様に機能します。

プロジェクト検索の仕組み

• 自動リンク（ゼロ設定、推奨）: ファイルが …/Apps/Overleaf/<project-name>/ 配下にある場合、スキルはユーザーの Overleaf プロジェクト一覧から <project-name> を検索します（24 時間キャッシュ、v0.3.0 以降は projects.json v2）。キャッシュされた一覧には trashed/archived/lastUpdated/ownerId が保持されるため、リゾルバーはデフォルトでゴミ箱またはアーカイブされたプロジェクトを除外し、同じ名前のアクティブなプロジェクトが 2 つある場合には推測を拒否します。
• マーカー自動書き込み（v0.3.0 以降）: 自動リンクが成功すると、リゾルバーはプロジェクトフォルダーに小さな .overleaf-project JSON マーカーファイルを書き込み、将来の解決ではインデックス検索を完全にスキップします。マーカーには project_id と provenance（source、linked_at、name_at_link_time）が含まれます。
• 手動リンク（オーバーライド）: ユーザーが同じ名前のアクティブなプロジェクトを 2 つ持っている場合（またはローカルフォルダー名が一致しない場合）、リゾルバーは推測を拒否し、コピーペースト可能な overleaf-sync-now link <id> <folder> コマンドとともにすべての候補を表示します。そのコマンドを実行してマーカーを明示的に書き込みます。{"project_id": "..."} のみを含む古いマーカーファイルも引き続き機能します。

sync が警告または拒否する場合

• auto-link: N non-trashed Overleaf projects named <name>. Refusing to guess. — フォルダー名と同じ名前のライブプロジェクトが 2 つ以上存在します。スキルは、ID、最終更新タイムスタンプ、アーカイブフラグを含む候補を一覧表示します。ユーザーに選択させ、表示された link コマンドを実行するように指示します。プロジェクト ID を代わりに選択しないでください。
• WARN: marker at <folder> -> <id> is trashed/archived on Overleaf — ユーザーが明示的に古いプロジェクトにリンクしました。同期は続行されますが、ユーザーはおそらく overleaf-sync-now link <other_id> <folder> を実行してアクティブなプロジェクトにリンクし直す必要があります。
• WARN: project <id> has recent Dropbox-origin updates touching files not present in <folder> — リンクが完全に間違ったプロジェクトを指している強いシグナルです（誤った手動リンク、フォーク、または以前の防御で捕捉できなかった同名の重複）。ユーザーに 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 を介して Cookie を取得します。」
3. （初回実行時は、Playwright + Chromium が自動インストールされます。約 150MB、一度だけです。）ブラウザが overleaf.com を開き、ユーザーがログインすると、スクリプトは Chrome DevTools Protocol を介して Cookie を取得します（ディスク上の復号化は不要です）。ログインはプロファイルに保持されます。
4. ユーザーがログイン完了を確認したら、overleaf-sync-now status を実行して確認し、元の同期を再試行します。

login を実行できない環境向けの代替手段（ディスプレイなし、サーバーなど）: save-cookie <value>。ユーザーに F12 → Application → Cookies → overleaf.com から overleaf_session2 の値をコピーし、overleaf-sync-now save-cookie "<value>" を実行するように依頼します。login が利用可能な場合はこれに頼らないでください。login の方が信頼性が高いです。

サブコマンド

CLI は overleaf-sync-now です（uv tool install でグローバルインストールされます）。

setup

認証ウィザード。自動検出チェーンを実行します。インタラクティブモードでは手動貼り付けのプロンプトも表示します。一度実行すれば後は数週間キャッシュされます。

login

ブラウザ支援ログイン（Playwright + Chromium）。setup が自動検出できない場合の適切な修正方法です。Windows の Chrome 130+ の App-Bound Encryption ケースも含みます。上記のリカバリーフローを参照してください。

save-cookie <value>

最終手段: ブラウザの F12 → Application → Cookies ペインから貼り付けられた overleaf_session2 Cookie 値を保持します。login を実行できない場合（ディスプレイなし / CI / サーバー）にのみ使用します。

sync [folder] [--force]

folder（またはカレントディレクトリ）が所有するプロジェクトを Overleaf に対して更新します。

• /project/<id>/updates を調査します。変更がない場合、またはすべての新しい更新が自身の保存の Dropbox 発信のラウンドトリップである場合はスキップします。それ以外の場合は ZIP をダウンロードし、Web 発信の更新がまだローカルにないファイルのみを抽出します。
• --force: 常に ZIP をダウンロードして再抽出します。ハッシュ比較により、バイトが既にローカルと一致するファイルはスキップされます。また、30 秒の recent-mtime ガードも無効になります（下記参照）。

データ安全性: デフォルトでは、sync は過去 30 秒以内に変更されたローカルファイルの上書きを拒否し、SKIP <path> を stderr に出力します。これは、Dropbox → Overleaf にまだ伝播していない進行中のローカル保存を保護します。上書きするには --force を渡します。

呼び出すタイミング: ユーザーが「Overleaf から最新をプル」と言ったときに手動で、または Codex CLI での編集前に自動的に呼び出します（Codex の Windows では PreToolUse フックは信頼性が高くありません）。

status [folder]

データディレクトリ、Cookie の有効性、リンクされたプロジェクト、最終同期時刻、キャッシュされた Overleaf バージョン（toV）を報告します。サンドボックスによるネットワークブロックと実際の認証失敗を区別します。

projects [--refresh]

ユーザーの Overleaf プロジェクト一覧（名前 + ID）を表示します。--refresh はインデックスの再取得を強制します。

doctor [folder]

診断ダンプ: Cookie キャッシュの状態、ブラウザごとの Cookie 抽出、Playwright プロファイル、認証チェーンの解決、および指定されたフォルダーのリンクされたプロジェクトに対するライブの /updates プローブ。

link <project_id> [folder]

.overleaf-project マーカーを書き込みます。標準以外のフォルダーレイアウト（つまり Apps/Overleaf/<name>/ 以外）の場合にのみ必要です。

hook

Claude Code 用の PreToolUse フックエントリポイント。標準入力から JSON を読み取ります。手動での使用は想定していません。

install

冪等なインストール後セットアップ: SKILL.md を ~/.claude/skills/overleaf/ および ~/.codex/skills/overleaf/（存在する方）にコピーし、Claude Code の PreToolUse フック（マッチャー Read|Edit|Write|MultiEdit）をインストール / 更新し、認証チェーンを実行します。アップグレード後に再実行します。

uninstall

スキルのインストールとフックを削除します。Cookie は保持されます。

サンドボックスに関する注意（Codex CLI、制限付きシェル）

ネットワークを使用するサブコマンド（sync、status、login、doctor、setup）がソケット許可エラーで失敗した場合 — Windows では WinError 10013 / forbidden by its access permissions、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 は Cookie auth: UNKNOWN — outbound HTTPS is blocked ... を INVALID ではなく出力するため、推測する必要はありません。

このスキルを呼び出すタイミング

• Claude Code: めったにありません。フックが編集を自動的に処理します。sync は明示的なユーザーリクエストがあった場合、または setup/link は初回設定時のみ呼び出します。
• Windows の Codex CLI: Apps/Overleaf/ 配下の .tex/.bib/.cls/.sty/.bst ファイルを編集/書き込みする前に、毎回 sync を呼び出します。（Windows では Codex フックが編集前に確実に起動しません。）
• ユーザーが古い Overleaf コンテンツについて言及した場合: sync を呼び出します。
• ユーザーが Overleaf 同期のセットアップを依頼した場合: setup（または、まだ Claude/Codex スキルディレクトリにリンクされていない場合は完全な install）を呼び出します。

障害モードとリカバリー

• 「No valid Overleaf cookies found. Run setup」: Cookie が期限切れか、設定されていません。overleaf-sync-now setup を実行します。チェーンはキャッシュ → ブラウザ → Playwright を試行します。インタラクティブモードでは手動貼り付けにフォールスルーします。
• setup がブラウザ Cookie を見つけられない: ユーザーが Chrome/Edge/Firefox で overleaf.com にログインしていない可能性があります。そこにログインするか、プロンプトが表示されたら手動で Cookie を貼り付けます。
• 自動リンクがプロジェクトを見つけられない: フォルダー名が Overleaf プロジェクト名と一致しません。フォルダー内で link <project_id> . を使用します。

セキュリティ上の注意

キャッシュされた Cookie は、ユーザーの Overleaf アカウントへの完全なアクセスを許可します。~/.overleaf-sync/cookies.json にデフォルトのユーザー権限で保存されます。コミットしたり、共有したりしないでください。