remotely-save/CLAUDE.md

CLAUDE.md

Guia para Claude Code (claude.ai/code) trabalhar neste fork.

Sobre o projeto

Fork de remotely-save/remotely-save, plugin Obsidian que sincroniza vaults com WebDAV/S3/Dropbox/OneDrive/etc. Upstream com main branch parada desde 2024-11. Este fork retoma manutenção.

Detalhes técnicos completos em:

• docs/ARCHITECTURE.md — abstração FakeFs, fluxo de sync, state em IndexedDB
• docs/DEVELOPMENT.md — setup mise, comandos npm
• docs/CONTRIBUTING.md — workflow, convenções, política de cobertura

Stack

• TypeScript 5.5 + Node 24.15.0 (pin via mise.toml)
• npm 11 (pin via packageManager)
• Webpack (build principal) + esbuild (alternativo)
• Biome (lint + format)
• Mocha + chai-as-promised + tsx (testes)
• c8 (cobertura)

Convenções específicas deste fork

Commits

Inglês, não pt-BR (alinhar com upstream). Imperativo, primeira letra maiúscula, ~72 caracteres na primeira linha. Corpo opcional com bullets -. Citar PR upstream quando aplicável (based on upstream PR #1094).

Dependências

• Só versões com ≥ 30 dias publicadas no npm registry — checar time antes de subir
• Pinar exato (sem ^/~) quando você mexer numa versão
• Usar overrides para forçar transitivas seguras quando o upstream não atualizou

Cobertura

Floor atual: 8% (ratchet — só sobe). Configurado em package.json:scripts.test:coverage com c8 --check-coverage --lines=N. Ao subir cobertura, atualizar N no script.

Lint

Pode usar // biome-ignore <rule>: <razão> para suprimir regra com justificativa explícita. Sem suprimir silenciosamente.

Estilo de código

• SRP: uma coisa por função, uma responsabilidade por módulo.
• Nomes: específicos e únicos. Evitar data, handler, Manager. Preferir nomes que retornem menos de 5 hits num grep do codebase.
• Tipos: explícitos. Sem any, sem Dict, sem funções sem tipo.
• Funções: ≤ 50 linhas. Dividir se passar.
• Controle de fluxo: early returns, no máximo 2 níveis de aninhamento.
• Exceções: incluir o valor ofensor e o formato esperado na mensagem.

CI (.github/workflows/ci.yml)

Padrão Lint → Test → Security, cada um com responsabilidade única:

Stage	Comando	Timeout
Lint	npx @biomejs/biome ci .	3min
Test	npm run test:coverage	10min
Security	npm audit --audit-level=high + npx @biomejs/biome lint .	5min

Build de produção fica em release.yml (não no CI de PR). Local: npm run build.

Cherry-pick de PRs do upstream

git fetch upstream pull/<N>/head:pr-<N>
git cherry-pick <commits>

Validar local (npm run format && npm test && npm run build) antes de commit. Mencionar o PR no commit message.

Cuidados ao mexer

• pro/src/account.ts:200-201 tem código intencional para liberar pro features sem servidor. Não remover.
• src/main.ts (~2k LOC) e src/settings.ts (~3k LOC) são funções gigantes — refactors em passos pequenos.
• pro/src/sync.ts:doActualSync é o coração. Sem testes atualmente. Qualquer mudança aqui precisa teste novo.
• Backends fs*.ts seguem FakeFs. Não criar novo sem implementar a interface completa.

Filosofia

• AI como pair programmer: narrar decisões técnicas (especialmente em tsconfig/build/CI). Perguntar em vez de assumir. Explicar trade-off.
• Mudança incremental: commits pequenos e bisect-friendly.
• Cada feature ou bugfix inclui teste.