From 39711d117cd417a708f086848092be05dd310d1d Mon Sep 17 00:00:00 2001
From: Bruno Miiller <miiller.bru@gmail.com>
Date: Tue, 19 May 2026 23:11:08 -0300
Subject: [PATCH] Add CLAUDE.md for AI pair programmer context
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Stack and pin policy (Node 24, npm 11, 30-day dep aging)
- Fork-specific convention: English commits (vs upstream-aligned)
- Coverage ratchet at 8% (only goes up)
- CI structure: Lint → Test → Security, build moved to release.yml
- Pointers to docs/ARCHITECTURE, DEVELOPMENT, CONTRIBUTING
- Sensitive areas flagged: fake-license shortcut in pro/account.ts,
  large untested files (main.ts, settings.ts, pro/sync.ts)
---
 CLAUDE.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..41d1990
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,84 @@
+# 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.