bruno/remotely-save
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
39711d117c
remotely-save/CLAUDE.md
Bruno Miiller 39711d117c
Some checks failed
CI / Lint (push) Failing after 44s
Details
CI / Test (push) Has been skipped
Details
CI / Security (push) Has been skipped
Details
Add CLAUDE.md for AI pair programmer context 
- 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)
2026-05-19 23:15:06 -03:00

3.5 KiB
Raw Blame History

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.