notas-online/README.md

# Notas — editor de notas web estilo Mousepad

Aplicação web completa para gerenciamento de notas inspirada no visual sóbrio e minimalista do
**Mousepad** (editor de texto do XFCE): barra de menus superior, barra de ferramentas, área de
texto limpa e barra de status na parte inferior.

Backend único em **Go** (binário estático de ~7 MB com o frontend já embutido), armazenamento em
disco no estilo **Git** (blobs endereçados por SHA-256 + histórico de revisões com diff e
restauração) e autenticação por **token** (Bearer para API / cookie HttpOnly para o navegador).

```
┌──────────────────────────────────────────────────────────────────────────┐
│ ☰ Notas   Arquivo   Editar   Exibir   Ajuda                              │ ← barra de menus
├──────────────────────────────────────────────────────────────────────────┤
│ ✚Nova 💾Salvar ⬇Baixar │ B I S H1 H2 ≡• 1 ❝ 🔗 </> { } │ Formato ▾     │ ← barra de ferramentas
│                          [ Editar | Preview ]  🕘Versões │
├─────────────────┬────────────────────────────────────────────────────────┤
│ Buscar…         │ ┌ nota.md ● ─┬─ outra.md ─┐        ✚ │ ← abas          │
│ CATEGORIAS +pasta├─────────────┴─────────────┴──────────┴────────────────┤
│ 🗂 Todas as notas│ Título da nota                       🗀 devops +1 ▾   │
│ 🗄 Sem categoria ├────────────────────────────────────────────────────────┤
│  📂 devops    1 │  1 │ # Placas                                         │
│   · 📁 k8s     2 │  2 │                                                  │
│ TAGS             │  3 │ **nvme** em `/dev/nvme0`   │ ← números de linha, │
│ #linux 2 #devops1│  4 │ - controladora #linux     │   cores, marcador   │
│ NOTAS          3 │  5 │ …                       ┊ │   de coluna (80)    │
│  nota1 .md       │                                                  │
│  nota2 .txt      │                                                  │
├─────────────────┴────────────────────────────────────────────────────────┤
│ nota.md  .md  Ln 4, Col 12      128 caracteres · 20 palavras  ● não salvo│ ← barra de status
└──────────────────────────────────────────────────────────────────────────┘
```

No celular (≤760px) a barra lateral vira **gaveta** com backdrop e o painel de versões
ocupa a tela inteira; menus e toolbar rolam horizontalmente com botões só de ícone.

## Funcionalidades

- **3 formatos por nota**: Texto puro (`.txt`), Markdown (`.md`) e HTML (`.html`), alternáveis no
  editor; a nota é baixada com a extensão correspondente.
- **Barra de ferramentas de formatação**: negrito, itálico, tachado, títulos H1/H2, listas,
  citação, link, código inline e bloco de código — inserindo sintaxe Markdown **ou** HTML conforme
  o formato ativo (desabilitada em texto puro).
- **Modo Edição ↔ WYSIWYG ↔ Preview** (`Ctrl+E/M/R`): o WYSIWYG (`Ctrl+M`) renderiza a nota num
  `contenteditable` e sincroniza com o fonte a cada tecla — Markdown vira HTML editável (negrito,
  títulos, listas, citação, código, links, tabelas) e volta a Markdown ao editar/alternar; HTML é
  editado visualmente com tags/atributos preservados (scripts e `on*` são removidos ao abrir).
  O Preview renderiza Markdown no servidor (goldmark, GFM, HTML cru escapado); HTML em
  `<iframe sandbox>`; texto puro como está. Em texto puro o WYSIWYG não se aplica.
- **Categorias como árvore de pastas**: o painel lateral traz um explorador de arquivos —
  categorias aninhadas (subpastas), expansão/colapso, contagem de notas por pasta e menu de
  contexto (Nova subpasta / Renomear / Excluir, sem ciclos). Uma nota pode pertencer a
  **várias categorias** ao mesmo tempo (seletor multi-marca no topo do editor). Filtro por
  pasta é recursivo por padrão (`?recursive=0` desliga); há também "Todas as notas" e
  "Sem categoria". Dados antigos com o campo único `category` são migrados automaticamente
  na abertura (vira categoria raiz de mesmo nome).
- **Tags `#tag`** extraídas automaticamente do conteúdo (cabeçalhos Markdown como `# Título`
  não contam — só `#tag` sem espaço), com filtro por nuvem de tags e busca em
  título/categorias/conteúdo.
- **Abas de arquivos**: abra várias notas ao mesmo tempo (clique na lista, `Ctrl+N` ou botão
  ✚); cada aba tem estado sujo próprio (●), botão ✕ com confirmação, fechar com clique do
  meio, trocar com `Alt+←/→` ou `Alt+1..9`, fechar com `Alt+W`. As abas abertas (inclusive
  rascunhos não salvos) são restauradas entre sessões via `localStorage`.
- **Preferências do editor** (menu Editar → Preferências… ou `Ctrl+,`, em diálogo próprio):
  - **Números de linha** (gutter alinhado mesmo com quebra de linha; alternável pelo menu Exibir).
  - **Marcador de coluna** customizável — padrão **80** (linha vertical no editor, exibida com
    quebra de linha desligada, como no Mousepad/gedit).
  - **Quebrar linha** ligado/desligável (alternável também pelo menu Exibir).
  - **Tecla Tab**: insere N espaços (padrão **4**, configurável 1–16) **ou** o caractere de
    tabulação `\t`; o valor também define a largura exibida do `\t` (`tab-size`) no editor e no
    realce, mantendo as camadas alinhadas.
  - **Fonte** (DejaVu Sans Mono, Ubuntu Mono, Cascadia Code, Liberation Mono, Courier New ou
    monoespaçada do sistema) e **tamanho** (10–32 px).
  - **Esquema de cores / tema** (21 opções, em grupos no diálogo): nativos — Claro (Greybird),
    Escuro (Adwaita), Solarizado claro/escuro; **iTerm2-Color-Schemes** (projeto
    [mbadolato/iTerm2-Color-Schemes](https://github.com/mbadolato/iTerm2-Color-Schemes), MIT) —
    escuros: Dracula, Nord, Atom One Dark, Monokai Pro, Gruvbox Dark, Tokyo Night, Catppuccin
    Mocha, Tomorrow Night, Ayu Mirage, Kanagawa Wave; claros: Catppuccin Latte, Gruvbox Light,
    Atom One Light, Nord Light, Carbon Paper, Tomorrow, Ayu Light. As cores de UI **e** dos
    tokens de sintaxe são derivadas do Background/Foreground + ANSI 0–15 de cada arquivo
    `.itermcolors`; cada tema também declara `color-scheme` (scrollbars/controles nativos
    acompanham). Aplicam-se a toda a interface, incluindo preview e diffs.
  - **Colorização de sintaxe**: Markdown (títulos, negrito/itálico, código inline e blocos ` ``` `,
    listas, citações, links, tags `#tag`, URLs) e HTML (tags, atributos, strings, comentários,
    entidades) renderizados por overlay sobre o textarea; desligável.
  - Tudo persistido no navegador (`localStorage`), com pré-visualização ao vivo no diálogo,
    botões Cancelar (reverte) e Restaurar padrões.
- **Versionamento estilo Git**: cada salvamento de conteúdo cria uma revisão imutável
  (autor, data, mensagem, hash SHA-256 e parent). O painel de histórico mostra o **diff unificado**
  de cada revisão e permite **restaurar** qualquer versão anterior (a restauração vira uma nova
  revisão — nada se perde). Conteúdo idêntico é deduplicado (content-addressed).
- **Colaboração em tempo real entre dispositivos/sessões** (SSE, sem recarregar página):
  - **Presença**: cada janela/aba do navegador é uma *sessão* (id aleatório em `sessionStorage`)
    que envia heartbeat das notas abertas (`POST /api/presence`). Quando outra sessão está com a
    mesma nota aberta, aparece **👥** na aba, na lista de notas e um selo
    *"outra sessão aberta aqui"* no topo do editor.
  - **Propagação de salvamento**: criar/salvar/restaurar/excluir publica um evento
    `{type:"saved", note_id, hash, session}` no stream SSE (`GET /api/events`). Instância com a
    nota **limpa** recarrega o conteúdo sozinha (toast discreto); com a nota **suja**, abre
    automaticamente o diálogo *Conflito de edição* (recarregar | salvar por cima). A própria
    sessão que salvou ignora o evento; reconexão do `EventSource` é automática e o fallback
    continua sendo a checagem no foco da janela.
- **Autosave**: ligado por padrão — após ~1,5 s sem digitar, a alteração é salva como revisão
  `autosave` (rascunho novo vira nota criada automaticamente; status *"salvando…"* na barra).
  Desligável em Preferências. Conflitos durante autosave pausam o ciclo até a resolução.
- **Sincronia entre dispositivos** (celular + desktop no mesmo servidor):
  - Cada aba lembra o hash em que se baseia (`base_hash`). Ao salvar, se o servidor mudou desde
    então, a API responde **409** e a UI abre o diálogo **Conflito de edição** com as duas saídas:
    *Recarregar do servidor* (descarta o texto local) ou *Salvar por cima* (a versão remota fica
    no histórico e é restaurável).
  - Abas **sem edição pendente** são recarregadas automaticamente quando a janela volta ao foco
    (`visibilitychange`/`focus`, com debounce), com aviso discreto.
- **Autenticação por token**: sem token, a interface exibe um diálogo pedindo o token; ele é
  guardado em **cookie HttpOnly/SameSite=Lax** (30 dias). A API também aceita
  `Authorization: Bearer <token>` para scripts.
- **Responsivo para celular** (≤760px): barra lateral vira gaveta com backdrop (☰ fecha ao
  tocar uma nota), painel de versões ocupa a tela toda, toolbar e menus rolam horizontalmente
  sem rótulos, **dropdowns dos menus posicionados como `fixed`** (o `overflow-x` da menubar não
  os corta mais em telas pequenas), alvos de toque ampliados, diálogos em largura total, fonte
  do editor com mínimo de 16px (evita zoom automático do iOS), altura em `dvh` e
  `safe-area-inset` para notch.
- **Estilo Mousepad**: tema claro Greybird-like, menus nativos (Arquivo/Editar/Exibir/Ajuda),
  atalhos `Ctrl+S`, `Ctrl+N`, `Ctrl+E/M/R` (edição/wysiwyg/preview), `Ctrl+H` (histórico), `F9`
  (barra lateral), `Ctrl+B/I/K` (formatação), `Ctrl+,` (preferências), `Alt+W`/`Alt+←/→`/
  `Alt+1..9` (abas), barra de status com arquivo, formato, linha/coluna, contagem de palavras e
  estado de salvamento.

## Estrutura do projeto

```
.
├── cmd/notas/            # main: flags, env, graceful shutdown
├── internal/
│   ├── store/            # persistência em disco, revisões (estilo Git) e árvore de categorias
│   ├── diffx/            # diff unificado (gotextdiff/Myers)
│   └── api/              # rotas HTTP, auth, CRUD de categorias, render de Markdown
├── web/                  # frontend estático (go:embed no binário)
│   ├── index.html  css/app.css  js/app.js
├── Dockerfile            # multi-stage: golang:alpine → scratch
├── docker-compose.yml
└── .env.example
```

## Como rodar com Docker (recomendado)

```bash
cp .env.example .env
# edite .env e defina o token (gere um forte):
#   openssl rand -hex 24
docker compose up -d
# abra http://localhost:8080 e informe o token na tela de login
```

Se a porta 8080 estiver ocupada: `NOTAS_PORT=9090 docker compose up -d`.
Com **Podman**: tudo acima funciona igualmente com `podman-compose`.

Os dados ficam no diretório local **`./data`** (bind mount, ao lado do
`docker-compose.yml`) — já ignorado pelo `.gitignore`. Backup = copiar a pasta;
`docker compose down` não apaga nada.

Permissões do `./data` (a imagem roda como uid 65534, non-root):

- **Podman rootless**: adicione `NOTAS_USER=0:0` ao `.env` — dentro do container
  isso é mapeado para o **seu** usuário no host, que é dono de `./data`.
- **Docker (root)**: `sudo chown -R 65534:65534 data` (ou rode o container com
  `NOTAS_USER=$(id -u):$(id -g)` e ajuste a dona da pasta em conformidade).

## Como rodar sem Docker

```bash
export NOTES_TOKEN=$(openssl rand -hex 24)
go run ./cmd/notas                 # escuta :8080, dados em ./data
# ou o binário:
go build -trimpath -ldflags="-s -w" -o notas ./cmd/notas
./notas -addr :8080 -data ./data
```

### Configuração (variáveis de ambiente / flags)

| Variável         | Flag     | Padrão    | Descrição                                  |
|------------------|----------|-----------|--------------------------------------------|
| `NOTES_TOKEN`    | —        | (sem)     | **Obrigatório.** Token de acesso.          |
| `NOTES_DATA_DIR` | `-data`  | `./data`  | Diretório de dados (notas + blobs).        |
| `NOTES_ADDR`     | `-addr`  | `:8080`   | Endereço de escuta.                        |

## API (para scripts)

Todos os endpoints sob `/api/*` exigem o token, exceto `login/logout/me` e o frontend.

```bash
T=$NOTES_TOKEN; B=http://localhost:8080
curl -H "Authorization: Bearer $T" $B/api/notes   # lista (?category=<id|none>&recursive=0&tag=&q=)
curl -H "Authorization: Bearer $T" $B/api/notes/<id>            # nota + conteúdo
curl -s -X POST -H "Authorization: Bearer $T" -H 'Content-Type: application/json' \
     -d '{"title":"Olá","format":"md","categories":["<id>"],"content":"# Oi #linux"}' $B/api/notes
curl -X PUT  -H "Authorization: Bearer $T" -H 'Content-Type: application/json' \
     -d '{"title":"Olá","format":"md","categories":["<id>"],"content":"editado","author":"lg","message":"revisão 2","base_hash":"<hash carregado>"}' \
     $B/api/notes/<id>
#     base_hash é opcional: se enviado e diferente do atual → 409 {error, server_hash, updated_at}
#     (omitir/enviar vazio = força o salvamento)
curl -H "Authorization: Bearer $T" $B/api/notes/<id>/revisions                # histórico
curl -H "Authorization: Bearer $T" $B/api/notes/<id>/revisions/<hash>/diff     # diff unificado
curl -X POST -H "Authorization: Bearer $T" $B/api/notes/<id>/revisions/<hash>/restore \
     -H 'Content-Type: application/json' -d '{"author":"lg"}'                  # restaurar
curl -H "Authorization: Bearer $T" $B/api/notes/<id>/raw                      # download .txt/.md/.html
curl -H "Authorization: Bearer $T" $B/api/tags   $B/api/categories            # agregações
# árvore de categorias (lista plana; parent="" é raiz)
curl -X POST -H "Authorization: Bearer $T" -H 'Content-Type: application/json' \
     -d '{"name":"devops","parent":""}' $B/api/categories
curl -X PUT  -H "Authorization: Bearer $T" -H 'Content-Type: application/json' \
     -d '{"name":"infra","parent":"<novo-pai>"}' $B/api/categories/<id>       # renomear/mover
curl -X DELETE -H "Authorization: Bearer $T" $B/api/categories/<id>           # remove subtree
# tempo real (SSE): stream de eventos saved/presence (auth por cookie no navegador;
# para scripts, leia o stream com o header Bearer)
curl -N -H "Authorization: Bearer $T" "$B/api/events?session=meu-id"
# heartbeat de presença: informa quais notas a sessão tem abertas
curl -X POST -H "Authorization: Bearer $T" -H 'Content-Type: application/json' \
     -d '{"session":"meu-id","notes":["<id>"]}' $B/api/presence
# PUT/POST/restore aceitam campo opcional "session" — o eco vai no evento saved
# (clientes que ignoram o evento podem sobrescrever a própria edição sem querer)
```

## Como funciona o versionamento

- O conteúdo é guardado em `data/blobs/<aa>/<hash-sha256>` (content-addressed, como objetos do
  Git): conteúdo repetido ocupa um único blob.
- Cada nota tem `data/notes/<id>/meta.json` (estado atual) e `history.json` (lista ordenada de
  revisões: `hash`, `parent`, `author`, `when`, `message`, `bytes`).
- A árvore de categorias fica em `data/categories.json` (lista plana com `parent`; nomes únicos
  entre irmãos; mover para dentro de si mesma é recusado).
- Salvar sem alterar o conteúdo atualiza apenas os metadados (título/categorias/formato) — sem
  revisão nova. Restaurar cria uma revisão nova apontando para o blob antigo.
- Apagar uma nota faz GC dos blobs que ficaram sem referência.

## Segurança

- Token verificado em **tempo constante**; nunca é registrado nos logs.
- Sessão do navegador em cookie **HttpOnly + SameSite=Lax** (mitiga CSRF); o token em
  `localStorage` foi preterido de propósito por ser exposto a XSS.
- CSP restritiva (`default-src 'self'`), `X-Frame-Options: DENY`, `nosniff`; preview de HTML roda
  em iframe `sandbox` sem mesma origem; Markdown renderiza com HTML cru escapado.
- Limite de 2 MiB por nota; corpo HTTP limitado a 4 MiB.
- Rode atrás de TLS (reverse proxy) em produção — o cookie marca `Secure` automaticamente quando
  a requisição chega por HTTPS/`X-Forwarded-Proto`. O modelo é **token único compartilhado**
  (sem usuários múltiplos); a imagem final é `scratch` non-root (uid 65534) — sem shell para
  `exec` de depuração, por design.
- Preferências do editor e abas abertas ficam em `localStorage` (dados não sensíveis, por
  dispositivo/navegador); o token nunca vai para lá.
- Presença/SSE: o stream exige a mesma autenticação das rotas `/api/*` (cookie HttpOnly no
  navegador, Bearer em scripts). O registro de presença guarda apenas id de sessão aleatório +
  ids de notas abertas — nada de conteúdo trafega no canal de presença.

## Testes

```bash
go test ./...   # store (revisões/GC/tags/árvore de categorias/migração),
                # diffx (diff unificado), api (fluxo HTTP completo + CRUD de categorias)
go vet ./...
node --check web/js/app.js
```