# CLAUDE.md

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

## Sobre o projeto

Fork de [`remotely-save/remotely-save`](https://github.com/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

```bash
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.