hanlulong/overleaf-sync-now

O que overleaf-sync-now faz?

⚠ PARE — leia isto antes de sugerir "fazer login no Overleaf"

Se o usuário estiver no Windows com Chrome 130 ou superior, fazer login no Overleaf no navegador diário NÃO corrigirá falhas de autenticação. O Chrome 130 adicionou a Criptografia Vinculada ao Aplicativo: a chave AES do banco de dados de cookies é encapsulada uma segunda vez com uma chave vinculada ao próprio Chrome.exe, intermediada pelo COM do Windows. Qualquer processo que não seja o Chrome.exe (e que não esteja sendo executado como administrador) pode ler os bytes criptografados, mas não pode descriptografá-los. Portanto, browser_cookie3 e rookiepy falham independentemente de quão recentemente o usuário fez login.

A correção adequada é overleaf-sync-now login. Ela inicia um navegador controlado (Chromium gerenciado pelo Playwright), o usuário faz login ali uma vez, e lemos o cookie através do Chrome DevTools Protocol — que retorna texto simples porque a requisição vem de dentro do navegador. O login persiste em nosso perfil por semanas.

O problema

O Dropbox bridge do Overleaf pesquisa em uma direção (Overleaf → Dropbox) a cada 10–20 minutos, então um arquivo .tex espelhado localmente pelo Dropbox pode estar desatualizado por esse período. Esta habilidade corrige isso sondando o histórico de versões do Overleaf (GET /project/{id}/updates) e, em caso de alteração real de origem web, baixando o zip do projeto (GET /project/{id}/download/zip) e extraindo apenas os arquivos que mudaram — sem alterar a configuração existente do Dropbox bridge, para que a sincronização entre dispositivos via Dropbox continue funcionando como antes.

Como funciona a busca do projeto

• Link automático (zero-config, preferido): se um arquivo estiver em qualquer pasta …/Apps/Overleaf/<nome-do-projeto>/, a habilidade busca <nome-do-projeto> na lista de projetos do Overleaf do usuário (cache de 24 h, projects.json v2 desde 0.3.0). A lista em cache mantém trashed/archived/lastUpdated/ownerId, então o resolvedor filtra projetos na lixeira e arquivados por padrão e se recusa a adivinhar quando dois projetos ativos compartilham o mesmo nome.
• Marcador auto-escrito (desde 0.3.0): em um link automático bem-sucedido, o resolvedor escreve um pequeno marcador JSON .overleaf-project na pasta do projeto, para que resoluções futuras ignorem completamente a busca no índice. O marcador contém project_id + proveniência (source, linked_at, name_at_link_time).
• Link manual (substituição): se o usuário tiver dois projetos ativos com o mesmo nome (ou o nome da pasta local não corresponder), o resolvedor se recusa a adivinhar e imprime todos os candidatos com o comando exato overleaf-sync-now link <id> <folder> para copiar e colar. Execute esse comando para escrever o marcador explicitamente. Marcadores antigos contendo apenas {"project_id": "..."} continuam funcionando.

Quando sync avisa ou se recusa

• auto-link: N projetos Overleaf não-lixeira nomeados <nome>. Recusando a adivinhar. — Dois ou mais projetos ativos compartilham o nome da pasta. A habilidade lista candidatos com IDs, timestamps da última atualização e qualquer flag de arquivado. Diga ao usuário para escolher um e executar o comando link impresso. NÃO escolha um ID de projeto para ele.
• AVISO: marcador em <pasta> -> <id> está na lixeira/arquivado no Overleaf — Usuário vinculou explicitamente um projeto desatualizado. A sincronização prossegue, mas o usuário provavelmente quer overleaf-sync-now link <outro_id> <pasta> para religar ao projeto ativo.
• AVISO: projeto <id> tem atualizações recentes de origem Dropbox tocando arquivos não presentes em <pasta> — Forte sinal de que o link aponta para o projeto errado (um link manual digitado errado, um fork ou uma duplicata de mesmo nome que as defesas anteriores não detectaram). Peça ao usuário para executar overleaf-sync-now status e overleaf-sync-now projects para verificar, depois link para corrigir.

Autenticação — NÃO pergunte ao usuário qual método usar

O script gerencia a autenticação sozinho. Ele tenta (nesta ordem exata, automaticamente): cookies em cache → rookiepy (amigável ao Chrome 127+) → browser_cookie3 → perfil Playwright do Claude Code → prompt de colagem manual.

Apenas execute overleaf-sync-now setup (ou install). Não pergunte ao usuário "você quer detecção automática ou colagem manual?" — o script escolhe a melhor fonte disponível.

Quando a autenticação falha (o fluxo de recuperação que você deve usar)

Quando setup relatar "FALHA NA DETECÇÃO AUTOMÁTICA" ou sync retornar um erro "Nenhum cookie Overleaf válido", a recuperação adequada é overleaf-sync-now login (assistido pelo navegador, funciona em todas as plataformas, incluindo Windows com Chrome 130+). Não sugira ao usuário "fazer login" no navegador diário — no Windows com Chrome 130+ isso não ajuda.

Fluxo de recuperação:

1. Execute overleaf-sync-now doctor para confirmar quais fontes automáticas falharam.
2. Diga ao usuário: "Execute overleaf-sync-now login no seu terminal. Uma janela do navegador será aberta. Faça login no Overleaf lá. Capturaremos o cookie através da API do navegador."
3. (Na primeira execução, isso instala automaticamente Playwright + Chromium, ~150 MB, uma única vez.) O navegador abre em overleaf.com, o usuário faz login e o script captura o cookie via Chrome DevTools Protocol (nenhuma descriptografia em disco necessária). O login persiste no perfil.
4. Após o usuário confirmar que o login terminou, execute overleaf-sync-now status para verificar e, em seguida, repita a sincronização original.

Alternativa para ambientes onde login não pode ser executado (sem display, servidor, etc.): save-cookie <valor>. Peça ao usuário para copiar o valor do overleaf_session2 de F12 → Application → Cookies → overleaf.com e execute overleaf-sync-now save-cookie "<valor>". Não confie nisso quando login estiver disponível — login é mais confiável.

Subcomandos

A CLI é overleaf-sync-now (instalada globalmente via uv tool install).

setup

Assistente de autenticação. Percorre a cadeia de detecção automática; no modo interativo, também solicita colagem manual. Execute uma vez; armazenado em cache por semanas depois.

login

Login assistido pelo navegador (Playwright + Chromium). A correção adequada quando setup não consegue detectar automaticamente — incluindo o caso de criptografia vinculada ao aplicativo do Chrome 130+ no Windows. Veja o fluxo de recuperação acima.

save-cookie <valor>

Último recurso: persistir um valor de cookie overleaf_session2 colado do painel F12 → Application → Cookies do navegador. Use apenas quando login não puder ser executado (sem display / CI / servidor).

sync [pasta] [--force]

Atualiza o projeto proprietário de pasta (ou diretório atual) contra o Overleaf.

• Sonda /project/<id>/updates; pula se não houver alteração ou se todas as novas atualizações forem viagens de ida e volta de origem Dropbox de nossos próprios salvamentos; caso contrário, baixa o zip e extrai apenas os arquivos cujas atualizações de origem web ainda não estão no local.
• --force: sempre baixar o zip e reextrair. A comparação de hash ainda pula arquivos cujos bytes já correspondem ao local. Também desabilita a proteção de 30 segundos de mtime recente (veja abaixo).

Segurança de dados: por padrão, sync se recusa a sobrescrever um arquivo local modificado nos últimos 30 segundos e imprime PULAR <caminho> no stderr. Isso protege um salvamento local em andamento que ainda não propagou Dropbox → Overleaf. Use --force para substituir.

Quando invocar: manualmente quando o usuário disser "puxar o mais recente do Overleaf", ou automaticamente antes de editar no Codex CLI (ganchos PreToolUse não são confiáveis no Windows no Codex).

status [pasta]

Relata diretório de dados, validade do cookie, projeto vinculado, hora da última sincronização e versão em cache do Overleaf (toV). Distingue rede bloqueada por sandbox de falhas reais de autenticação.

projects [--refresh]

Lista os projetos Overleaf do usuário (nome + ID). --refresh força uma nova busca do índice.

doctor [pasta]

Despejo de diagnóstico: estado do cache de cookies, extração de cookies por navegador, perfil Playwright, resolução da cadeia de autenticação e uma sonda ao vivo /updates contra o projeto vinculado à pasta fornecida.

link <id_do_projeto> [pasta]

Escreve um marcador .overleaf-project. Necessário apenas para layouts de pasta não padrão (ou seja, não Apps/Overleaf/<nome>/).

hook

Ponto de entrada do gancho PreToolUse para Claude Code. Lê JSON do stdin. Não para uso manual.

install

Configuração pós-instalação idempotente: copia SKILL.md para ~/.claude/skills/overleaf/ e ~/.codex/skills/overleaf/ (o que existir), instala / atualiza o gancho PreToolUse do Claude Code (correspondente Read|Edit|Write|MultiEdit), executa a cadeia de autenticação. Execute novamente após atualizar.

uninstall

Remove as instalações da habilidade e o gancho. Os cookies são preservados.

Notas de sandbox (Codex CLI, shells restritos)

Se qualquer subcomando que usa rede (sync, status, login, doctor, setup) falhar com um erro de permissão de soquete — Windows WinError 10013 / proibido por suas permissões de acesso, POSIX EACCES / EPERM / "Permissão negada" — o shell host está bloqueando a chamada HTTPS de saída. Isso não é um problema de autenticação.

A ferramenta detecta este caso especificamente e imprime:

O HTTPS de saída para o Overleaf foi bloqueado pelo ambiente host (provavelmente um shell em sandbox — Codex CLI, alguns runners de CI). A autenticação provavelmente está ok; executar setup/login/doctor falhará da mesma forma. Aprove o prefixo de comando overleaf-sync-now na sua política de sandbox ou execute novamente fora do sandbox.

Quando você vir essa mensagem (ou qualquer um dos marcadores de errno acima):

• Não execute setup / login / doctor — cada um atinge o mesmo soquete bloqueado.
• Diga ao usuário para aprovar o prefixo de comando overleaf-sync-now em sua sandbox (lista de sempre-aprovar do Codex CLI) ou executar novamente de um shell sem sandbox.
• status imprimirá Autenticação por cookie: DESCONHECIDA — HTTPS de saída está bloqueado ... em vez de INVÁLIDO neste caso, para que você não precise adivinhar.

Quando invocar esta habilidade

• No Claude Code: raramente — o gancho lida com a edição automaticamente. Invoque sync apenas a pedido explícito do usuário, ou setup/link para configuração inicial.
• No Codex CLI no Windows: toda vez que você estiver prestes a Editar/Escrever um arquivo .tex/.bib/.cls/.sty/.bst sob Apps/Overleaf/, invoque sync primeiro. (Os ganchos do Codex não disparam confiavelmente pré-edição no Windows.)
• Usuário menciona conteúdo desatualizado do Overleaf: invoque sync.
• Usuário pede para configurar sincronização com Overleaf: invoque setup (ou install completo se ainda não estiver vinculado aos diretórios de habilidades do Claude/Codex).

Modos de falha e recuperação

• "Nenhum cookie Overleaf válido encontrado. Execute setup": cookies expiraram ou nunca foram definidos. Execute overleaf-sync-now setup. A cadeia tentará cache → navegadores → Playwright; cai em colagem manual no modo interativo.
• setup não encontra cookies do navegador: o usuário pode não estar logado em overleaf.com no Chrome/Edge/Firefox. Faça login lá ou cole o cookie manualmente quando solicitado.
• Link automático não encontra o projeto: o nome da pasta não corresponde ao nome do projeto Overleaf. Use link <id_do_projeto> . dentro da pasta.

Nota de segurança

Cookies em cache concedem acesso total à conta Overleaf do usuário. Armazenados em ~/.overleaf-sync/cookies.json com permissões de usuário padrão. Não commite, não compartilhe.