notion-starter 0.3.0__tar.gz

notion_starter-0.3.0/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.py]
+indent_size = 4
+
+[*.md]
+trim_trailing_whitespace = false

notion_starter-0.3.0/.env.example

@@ -0,0 +1,13 @@
+# Token de integração do Notion — usado pelos exemplos em examples/.
+# Crie uma integração em https://www.notion.so/my-integrations,
+# compartilhe o database/página alvo com ela e cole o token aqui.
+# O token deve começar com "ntn_".
+NOTION_TOKEN=ntn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# ID do database de tarefas padrão (opcional — pode ser passado por chamada).
+# NOTION_DATABASE_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# Token do GitHub (opcional; necessário só para repositórios privados nos
+# serviços de inventário/sincronização GitHub).
+# Prefira token fine-grained com acesso somente de leitura.
+# GITHUB_TOKEN=

notion_starter-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  python:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Test
+        run: pytest -q

notion_starter-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,68 @@
+name: Release Python package
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Build and validate metadata
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: notion-starter-dist
+          path: dist/*
+
+  smoke:
+    needs: build
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: notion-starter-dist
+          path: dist
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install wheel and smoke
+        shell: bash
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install dist/*.whl
+          python -c "from notion_starter import NotionClient; print(NotionClient.__name__)"
+
+  publish:
+    needs: [build, smoke]
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: notion-starter-dist
+          path: dist
+      - name: Publish to PyPI with Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

notion_starter-0.3.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+.env
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+*.sqlite3
+dist/
+build/
+*.egg-info/
+node_modules/
+staticfiles/
+.notion-backups/

notion_starter-0.3.0/AGENTS.md

@@ -0,0 +1,33 @@
+# AGENTS.md — notion-starter
+
+Biblioteca Python **base** do ecossistema [Automações do Notion](https://github.com/Felipe-Alcantara/Automa-es-do-Notion) — o hub tem o roteamento completo entre módulos; leia-o se a tarefa envolver o CLI ou o app.
+
+## O que vive aqui
+
+| Arquivo | Responsabilidade |
+| --- | --- |
+| `src/notion_starter/client.py` | Cliente HTTP resiliente (retries por semântica, rate limit, erros tipados); `obter_pagina`/`atualizar_pagina` leem e editam propriedades |
+| `src/notion_starter/schema.py` | Leitura/comparação de schema de databases |
+| `src/notion_starter/tasks.py` | `Tarefa`, `TaskList`, `CamposTarefa` |
+| `src/notion_starter/content.py` + `properties.py` + `readers.py` | Conversão Markdown ↔ blocos (lógica pura); `properties.title`/`rich_text` fatiam texto >2000 (via `utils.fatiar_utf16`) |
+| `src/notion_starter/inventory.py` | Mapeamento do workspace (lógica pura, sem rede) |
+| `src/notion_starter/git_historico.py` | Histórico de um repositório git agrupado por dia (lógica pura, sem rede/Notion) |
+| `src/notion_starter/github.py`, `openrouter.py` | Adaptadores externos compartilhados por CLI e app |
+| `src/notion_starter/services/` | Casos de uso compartilhados entre CLI e app; defaults de ambiente continuam nos consumidores via `integrations.notion` |
+| `src/notion_starter/utils.py` | Saneamento de texto/JSON (surrogates inválidos); `fatiar_utf16` (fatia por unidades UTF-16, teto em `constants.MAX_RICH_TEXT`) |
+| `examples/` | Scripts de uso direto da lib |
+
+## Regras
+
+- Regra de negócio compartilhada entre CLI e app pode viver em `notion_starter.services`.
+  Bordas e configuração de ambiente continuam fora daqui (`cli/`, `api/`, `mcp_server`,
+  `integrations.notion` dos consumidores).
+- Só o `NotionClient` fala com a API do Notion; módulos de lógica são puros.
+- Código e mensagens em português; exceções derivam de `NotionSyncError`; Conventional Commits.
+- **Mudança de API pública quebra dois repos consumidores** — mantenha compatibilidade ou avise nos dois.
+
+## Testar
+
+```bash
+python -m pytest        # não precisa instalar; tests/conftest.py adiciona src/ ao path
+```

notion_starter-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# 🤝 Contribuindo com o notion-starter
+
+Obrigado por querer contribuir! Este repositório é a biblioteca Python base do
+ecossistema [Automações do Notion](https://github.com/Felipe-Alcantara/Automa-es-do-Notion):
+cliente resiliente para a API do Notion, schema, tarefas, conteúdo, inventário e a
+camada compartilhada `notion_starter.services`. Issues, correções de documentação,
+novos helpers, exemplos, testes e melhorias de resiliência são bem-vindos.
+
+> Contribuições devem preservar os contratos existentes, a documentação viva e o
+> gate de qualidade descrito abaixo.
+
+---
+
+## 🚀 Como Contribuir
+
+1. **Faça um fork** do repositório.
+2. **Crie uma branch** descritiva (`fix/...`, `feat/...`, `docs/...`) para mudanças
+   grandes; correções pequenas podem ir direto no `main` de quem mantém.
+3. **Faça suas mudanças** seguindo os padrões abaixo.
+4. **Rode os testes e o lint** antes de abrir o PR.
+5. **Abra um Pull Request** explicando o que mudou e por quê.
+
+Não tem certeza por onde começar? Abra uma issue descrevendo a ideia — a gente
+conversa antes de você investir tempo no código.
+
+---
+
+## 🛠️ Ambiente de Desenvolvimento
+
+```bash
+git clone https://github.com/Felipe-Alcantara/notion-starter.git
+cd notion-starter
+python -m pip install -e ".[dev]"
+
+# Gate de qualidade (HTTP é mockado — não precisa de token nem rede)
+ruff check .
+python -m pytest
+```
+
+Requer Python 3.10+. Copie `.env.example` para `.env` apenas se for rodar os
+exemplos de `examples/` contra um workspace real do Notion — nunca versione o `.env`.
+
+---
+
+## ✅ Padrões de Qualidade
+
+- **Entenda o padrão existente antes de alterar.** Módulos coesos por
+  responsabilidade: `client` (único que fala HTTP com o Notion), `schema`,
+  `properties`/`readers`, `content`, `tasks`, `inventory`, `services` (casos de uso,
+  sem HTTP próprio). Preserve essas fronteiras.
+- **Prefira a solução mais simples** que resolva o problema real. A biblioteca tem
+  poucas dependências de runtime de propósito.
+- **Preserve contratos.** Assinaturas públicas, objetos (`Tarefa`, `RepoInfo`, ...) e
+  exceções (`NotionSyncError` e derivadas) devem permanecer estáveis; mudança
+  quebradora precisa ser explícita e documentada.
+- **Tipos e validação.** `TypedDict` para payloads, `dataclass` para resultados;
+  valide entradas externas.
+- **Não exponha segredos.** Nada de tokens, IDs reais ou URLs privadas no código,
+  nos testes ou na documentação.
+- **Teste o comportamento.** Bugs corrigidos viram caso de regressão; HTTP é sempre
+  mockado com `responses`.
+- **Código, docstrings e mensagens de erro em português.**
+- **Atualize a documentação viva** (`README.md` e `IA.md`) no mesmo passo quando a
+  mudança alterar comportamento, estrutura ou comandos.
+
+---
+
+## ✍️ Padrões de Linguagem (Documentação e Logs)
+
+- **Escreva para qualquer leitor** — linguagem geral e acessível, sem jargão interno.
+- **Sem valores hardcoded** — use placeholders genéricos em vez de caminhos, tokens
+  ou IDs reais.
+- **Enquadre o trabalho futuro como convite à contribuição** em vez de uma lista de
+  tarefas interna.
+
+---
+
+## 🔄 Fluxo de Pull Request
+
+Um bom PR responde claramente:
+
+- **O que mudou?**
+- **Por que mudou?**
+- **Como foi validado?** (ex.: `ruff check .` + `python -m pytest`)
+- **Qual risco sobrou?**
+
+Mantenha o PR focado: evite misturar refatoração ampla com novas funcionalidades.
+Use commits pequenos no formato `tipo: descrição` (`feat`/`fix`/`docs`/`refactor`/`chore`).
+
+---
+
+## 💬 Código de Conduta
+
+Seja respeitoso e acolhedor. Este é um espaço para aprender e construir juntos —
+contribuições de pessoas de todos os níveis de experiência são bem-vindas.

notion_starter-0.3.0/IA.md

@@ -0,0 +1,381 @@
+# 🤖 IA.md — Contexto operacional do notion-starter
+
+> **O que é**: Memória técnica deste repositório para retomada de contexto por IA ou
+> por um novo mantenedor, sem reler todo o código. Baseado no template de contexto do
+> Felixo System Design.
+>
+> **Histórico anterior**: este módulo nasceu da separação do monorepo
+> [Automações do Notion](https://github.com/Felipe-Alcantara/Automa-es-do-Notion)
+> em 2026-07-02. Toda a linha do tempo anterior (decisões de arquitetura, bugs e
+> validações do core) permanece registrada no `IA.md` do hub — este arquivo cobre a
+> vida do módulo a partir da separação.
+
+---
+
+## 📊 ESTADO ATUAL (RESUMO VIVO)
+
+Última atualização: [2026-09-04]
+
+- Fase: biblioteca base estável, preparada como pacote `notion-starter` para a
+  distribuição da CLI única.
+- Qualidade: 355 testes verdes e `ruff` limpo; CI cobre Python 3.10–3.13.
+- Documentação: README alinhado ao Felixo System Design e contrato de qualidade
+  centralizado em `QUALIDADE.md`.
+- Próximos passos abertos: confirmação do contrato de publicação no PyPI e mais
+  tipos de propriedade/bloco e escrita em data sources.
+- Risco conhecido: consumidores devem fixar suas próprias resoluções de
+  dependências quando precisarem de builds reproduzíveis.
+
+---
+
+## 🎯 OBJETIVO DO PROJETO
+
+[2026-07-02] `notion-starter` é a biblioteca Python base do ecossistema: cliente
+resiliente para a API do Notion (retry/backoff, cache de schema), helpers de
+propriedade e leitura, conversor Markdown ↔ blocos, camada de tarefas (`TaskList`),
+inventário do workspace e a camada compartilhada `notion_starter.services`
+(clonagem, conteúdo, ingestão, sincronização GitHub, exportação DOCX). É consumida
+pelo `notion-tasks-cli` e pelo `notion-workspace-app`.
+
+---
+
+## 📐 DECISÕES DE ARQUITETURA
+
+- [2026-07-02] Fronteiras herdadas do monorepo (registradas no hub): só o
+  `NotionClient` fala HTTP com o Notion; `services` orquestra casos de uso sem
+  conhecer HTTP de borda; conversões e leituras (`content`, `properties`,
+  `readers`, `inventory`) são lógica pura testável sem rede.
+- [2026-07-02] Exceções continuam derivando de `NotionSyncError` (compatibilidade).
+- [2026-07-08] O repositório **não tem `start_app.py`**: é uma biblioteca importável,
+  não um programa. A porta de entrada interativa do ecossistema vive no hub
+  (`Automa-es-do-Notion/start_app.py`) e no `notion-workspace-app`. Os exemplos de
+  `examples/` são executados diretamente (`python examples/<nome>.py`) e documentados
+  no README. Exceção registrada conforme o padrão de qualidade.
+
+---
+
+## 🛠️ STACK & DEPENDÊNCIAS
+
+- Python 3.10+ (CI: 3.10–3.13). Runtime: `requests`, `python-docx` (exportação DOCX),
+  `typing_extensions` só em Python < 3.11.
+- Dev: `pytest`, `responses` (HTTP mockado), `ruff`.
+
+---
+
+## 🧪 TESTES & GATE
+
+- Gate: `ruff check .` + `python -m pytest` (193 testes em 2026-07-13, sem rede).
+- CI: GitHub Actions (`.github/workflows/ci.yml`) com matriz Python 3.10–3.13.
+
+---
+
+## 🧠 LINHA DO TEMPO
+
+- [2026-07-02] ✅ Módulo extraído do monorepo. Recebeu depois a consolidação da
+  camada compartilhada: `integrations` (GitHub/OpenRouter) e `services` comuns dos
+  consumidores viraram shims apontando para cá.
+- [2026-07-08] ✅ Alinhamento ao padrão de qualidade Felixo: adicionados
+  `CONTRIBUTING.md`, `IA.md`, `.env.example` e CI GitHub Actions. Decisão registrada:
+  sem `start_app.py` por ser biblioteca. Validação: `ruff check .` limpo e 183 testes
+  verdes.
+- [2026-07-13] ✅ Merge do PR #1 (contribuição externa): `mover_pagina`,
+  `mover_database` (re-parent, versão 2025-09-03 por chamada) e `enviar_arquivo`
+  (File Upload API) + `properties.arquivo_enviado`. Em seguida, hardening no
+  `main`: o passo multipart do upload passou a usar retry/backoff próprio
+  (`_enviar_multipart`, espelhando a política do `_request_json` — antes era um
+  `requests.post` cru, sem resiliência) e `enviar_arquivo` valida o limite de
+  20 MB (`NOTION_UPLOAD_MAX_BYTES`) antes de tocar a API. Motivo: migrações com
+  dezenas de uploads quebravam no primeiro 429 do `/send`. Validação:
+  `ruff check .` limpo e 193 testes verdes (3 novos: limite, retry em 429 e
+  retry em falha de rede).
+- [2026-07-13] ✅ Fechadas as melhorias propostas no relatório de 10/07 (5.2):
+  `criar_database` estendido (is_inline, icone, descricao, prefixo_id/unique_id),
+  `valores_br` (números e datas BR), `FontePlanilha` (.xlsx via extra
+  `planilha`, .csv via stdlib) com `ItemColetado.propriedades` tipadas,
+  `services/importacao` (import em lote retomável por estado local),
+  `properties.schema_propriedade` e `services/anexos.anexar_arquivo` (upload +
+  propriedade files preservando anexos). Validação: 230 testes verdes, ruff
+  limpo, CI verde.
+- [2026-07-18] ✅ Documentação alinhada ao Felixo System Design: README passou a
+  ter badges, índice, árvore real, guia de uso e rodapé open source;
+  `QUALIDADE.md` centralizou o gate e registrou a exceção motivada de versões
+  mínimas para uma biblioteca instalável. Motivo: tornar setup, manutenção e
+  critérios de pronto verificáveis sem quebrar a resolução dos consumidores.
+  Validação: 235 testes verdes e `ruff` limpo.
+
+- [2026-07-23] ✅ `services/inventario_github.atualizar_repos`/`exportar_repos`
+  passam a aceitar um **repositório específico** em `contas` (`owner/repo` ou
+  URL completa do repo), além de contas inteiras. Nova função privada
+  `_repo_completo_da_entrada` distingue os dois formatos (via `_PADRAO_URL_REPO`
+  e checagem de `/` fora de URL de perfil) e `_listar_repos_da_entrada` chama
+  `GitHubClient.detalhar_repo` nesse caso, em vez de `listar_repos`. Motivo:
+  inventariar um projeto pontual de terceiros (ex.: um repo de outra conta)
+  sem trazer o resto dos repositórios dela para a database. Validação: 6 novos
+  testes em `notion-tasks-cli/tests/test_services_inventario_github.py`
+  (reconhecimento de owner/repo, URL de repo, URL de perfil sem repo, coleta
+  sem duplicar quando o mesmo repo aparece via conta e via entrada avulsa);
+  235 testes do notion-starter e 132 do notion-tasks-cli seguem verdes, ruff
+  limpo em ambos.
+
+- [2026-07-23] ✅ Novo módulo `services/estrutura_projeto.py` com três casos de
+  uso para a moldura fixa de projeto do workspace (README + `## Acompanhamento`
+  com 4 subpáginas + `## Planejamento e documentação` com 2 databases, ver
+  `DESIGN-WORKSPACE-NOTION.md` no hub): `inspecionar_estrutura` (lê
+  recursivamente subpáginas/databases de uma página de referência, read-only),
+  `clonar_estrutura_projeto` (recria a forma — títulos de subpágina + schema de
+  databases via `clonar_database` — em outra página, sem herdar conteúdo) e
+  `montar_estrutura_projeto` (aplica o padrão do zero). Também
+  `services/conteudo.criar_subpagina`, que expõe `client.criar_subpagina` como
+  caso de uso reutilizável (antes só usado internamente pelo README do
+  GitHub). Motivo: montar essa estrutura manualmente (como feito para o
+  projeto Audiofy) exigiu inspecionar várias páginas de exemplo bloco a bloco,
+  sem nenhuma ferramenta reutilizável — o padrão documentado não tinha
+  automação correspondente. Validação: 9 novos testes em
+  `notion-tasks-cli/tests/test_services_estrutura_projeto.py`; 244 testes do
+  notion-starter e 137 do notion-tasks-cli seguem verdes, ruff limpo em ambos.
+
+- [2026-07-23] ✅ `NotionClient.anexar_blocos` ganhou o parâmetro opcional
+  `apos_bloco_id`, usando `position: after_block` da API do Notion (confirmado
+  na doc oficial, `developers.notion.com/reference/patch-block-children` —
+  substitui o antigo `after` no nível raiz, hoje legado) para inserir blocos
+  novos depois de um irmão específico, não só no final. Novo
+  `services/reordenacao.py` com `reordenar_bloco`: como a API do Notion não
+  tem endpoint para mover um bloco existente, a implementação apaga e recria
+  na posição pedida — sempre grava um backup em JSON do bloco original antes
+  de apagar. **Risco documentado e ativamente bloqueado por padrão**: para
+  `child_page`/`child_database`, apagar e recriar gera um **ID novo**,
+  quebrando links/backlinks/referências externas salvas para o ID antigo; a
+  função levanta `BlocoArriscadoError` nesses tipos a menos que o chamador
+  passe `forcar_tipos_arriscados=True` explicitamente. Motivo: precisei
+  reordenar um database solto numa página de projeto (Audiofy) e não havia
+  ferramenta alguma para isso — o único caminho seria apagar manualmente e
+  reimportar dados. Validação: 7 novos testes em
+  `tests/test_services_reordenacao.py`, mais os testes existentes de
+  `anexar_blocos`; 251 testes do notion-starter e 140 do notion-tasks-cli
+  seguem verdes, ruff limpo em ambos.
+
+- [2026-07-23] ✅ Correção: `montar_estrutura_projeto` criava "Próximos passos"
+  e "Documentações" com um schema mínimo genérico (título + Observações), que
+  não batia com o schema real observado nas páginas de projeto existentes do
+  workspace ("Próximos passos": Tarefa/Status/Prioridade/Concluída/
+  Observações; "Documentações": Documento/Tipo/Status/Criado em/Atualizado
+  em/URL/Observações — com `select` de opções coerentes, não `rich_text`
+  solto). `DATABASES_PLANEJAMENTO` virou um dict `título -> schema` em vez de
+  uma tupla de títulos. Motivo: ao aplicar a ferramenta na página real do
+  projeto Audiofy, os databases criados ficaram visivelmente fora do padrão
+  das páginas de referência lidas anteriormente. Validação: teste ajustado
+  para checar as colunas específicas de cada database (não mais um schema
+  genérico); 251 testes do notion-starter e 140 do notion-tasks-cli seguem
+  verdes, ruff limpo.
+
+- [2026-07-23] ✅ Correção crítica em `services/reordenacao.reordenar_bloco`:
+  `child_database` foi movido de `_TIPOS_ARRISCADOS` (bloqueável com
+  `forcar_tipos_arriscados=True`) para uma nova categoria `_TIPOS_IMPOSSIVEIS`,
+  recusada **sempre**, sem flag de escape (`BlocoImpossivelError`, distinta de
+  `BlocoArriscadoError`). Motivo: confirmado em produção (workspace real da
+  Flávia) que apagar+recriar um `child_database` via `anexar_blocos` **nunca
+  funciona** — a API do Notion só cria databases por `POST /databases`, não
+  por `PATCH /blocks/.../children`; a implementação anterior prometia essa
+  capacidade com a flag de força e, ao ser usada, apagava o database original
+  (com linhas) e falhava ao recriá-lo, deixando-o arquivado até restauração
+  manual. `child_page` continua suportado com a flag (recriação real funciona,
+  só o ID muda). Validação: novo teste
+  `test_reordenar_bloco_rejeita_child_database_mesmo_com_forcar`; 252 testes
+  do notion-starter e 141 do notion-tasks-cli verdes, ruff limpo.
+
+- [2026-07-24] ✅ Novo `services/schema.garantir_coluna`: adiciona uma coluna a
+  um database **já existente**, sem apagar nada. Generaliza o padrão que só
+  existia hardcoded em
+  `inventario_github.garantir_coluna_hash` (que só cuidava da coluna de hash
+  do README) para qualquer nome/tipo de coluna. Usa *data source* quando
+  disponível, cai para o endpoint clássico de `database` caso contrário —
+  mesma estratégia do original. Motivo: nenhuma ferramenta do ecossistema
+  evoluía o schema de um database depois de criado (`criar-database` só
+  define na criação; `editar-linha`/`importar-planilha` só escrevem em
+  colunas existentes) — faltou ao tentar adicionar uma coluna real (Idioma)
+  a um database do workspace da Flávia. TDD: testes escritos e confirmados
+  falhando antes da implementação existir, só então o módulo foi criado.
+  Validação: 4 novos testes em `test_services_schema.py`; 256 testes do
+  notion-starter seguem verdes, ruff limpo.
+- [2026-07-27] ✅ Relatórios diários a partir do git: `git_historico.py` (módulo
+  puro — executa `git` e agrupa commits por dia, sem conhecer Notion nem rede) e
+  `services/relatorios_diarios.py` (upsert **por data**: se o dia já tem página,
+  o corpo é anexado em vez de duplicar a linha). A separação existe porque o
+  histórico serve a outros destinos além do Notion, e o upsert serve a conteúdo
+  de qualquer origem, não só git. Decisão: página existente **preserva** suas
+  propriedades por padrão (`atualizar_propriedades_existentes=False`) — um mesmo
+  dia costuma acumular trabalho de projetos diferentes, e sobrescrever o resumo
+  apagaria o registro do outro projeto. Nasceu de um script pontual que publicou
+  9 dias de trabalho de um repositório na database de relatórios. TDD: testes
+  antes da implementação, e um deles pegou um defeito real — mensagem de commit
+  contendo o byte separador fazia o registro ser descartado silenciosamente
+  (corrigido limitando as divisões do `split`). Exemplo executável em
+  `examples/relatorios_do_git.py`, com `--simular`. Validação: 30 testes novos,
+  286 do notion-starter verdes, ruff limpo, e execução real contra um
+  repositório de 9 dias.
+
+- [2026-08-13] ✅ `DiaDeTrabalho` ganhou `duracao_minutos` e
+  `duracao_por_extenso()` (ex.: `"5h30"`, `"35 min"`, vazio com um único
+  commit), e `resumo_markdown()` passou a incluir a duração entre o primeiro
+  e o último commit do dia na linha de resumo, além da hora que já existia
+  (`"2 commits, das 09:00 às 14:30 (duração: 5h30)."`). Motivo: alguns
+  agentes já registravam hora e duração manualmente ao publicar relatórios
+  no Notion (ex.: "Commit automático do Fetch All das 08:36") — o padrão foi
+  formalizado em `docs/PADRAO-RELATORIOS.md` no hub, e este módulo passou a
+  gerar esse dado automaticamente em vez de depender de alguém lembrar.
+  Validação: 5 novos testes em `test_git_historico.py`; 295 testes do
+  notion-starter verdes, ruff limpo.
+
+---
+
+Ideias abertas à contribuição: cobertura de mais tipos de propriedade do Notion,
+mais tipos de bloco no conversor Markdown, escrita de linhas em data sources.
+
+---
+
+## [2026-08-17] Operar Notion às cegas era o gargalo real — três defesas na biblioteca
+
+**Contexto.** Uma sessão longa de trabalho real no workspace (criar 17 tarefas
+ricas, reescrever 16 e montar 48 ligações entre elas) expôs o mesmo padrão em
+todas as fricções: **a biblioteca não respondia perguntas que antecedem a
+escrita**, e o custo aparecia depois, já gravado no Notion.
+
+### 1. `descrever_database` — ler o schema sem chamar a API na mão
+
+`schema.py` só sabia **comparar** um database com um schema esperado. Para
+descobrir o nome exato de uma coluna, os valores aceitos por um select ou como
+uma relação está configurada, era preciso chamar `/v1/databases/<id>` cru e ler
+JSON — passo que se pula com pressa.
+
+Entram `DescricaoDatabase`, `Coluna` e `Relacao` (funções puras, sem rede):
+colunas ordenadas com o título primeiro, opções de select/status/multi_select,
+`editavel` marcando os tipos que o Notion calcula e recusa em PATCH
+(`TIPOS_SOMENTE_LEITURA`), e a configuração de cada relação com `auto_referente`
+comparando IDs sem hífen.
+
+### 2. `services/relacoes.py` — o tipo da relação não prevê o comportamento
+
+Hipótese inicial: `single_property` = mão única, então uma ligação simétrica
+exige gravar as duas pontas. **Medido no workspace real e a hipótese caiu
+parcialmente.** Experimento: duas linhas novas no database `30296e2d…`, coluna
+`Subtarefas relacionadas`, reportada como `single_property` pelas versões de API
+`2022-06-28` **e** `2025-09-03`. PATCH só na ponta C→D; releitura de D **já
+trazia C**. O Notion espelhou sem segunda escrita.
+
+Conclusão registrada: **não dá para deduzir do tipo declarado se o espelho
+acontece.** Assumir "espelha" deixa metade da malha faltando; assumir "não
+espelha" gasta requisição e pode duplicar. `relacionar()` resolve conferindo —
+escreve uma ponta, **relê a outra** e grava só o que faltar. Sai simétrico nos
+dois mundos, é idempotente e o retorno diz quais páginas precisaram de escrita.
+Relação para outro database e de mão única não tem coluna de volta: escreve só A.
+
+### 3. Reescrita que não custa o que não sabe repor
+
+`limpar_conteudo` apagava **todos** os blocos de topo, e `escrever(substituir=True)`
+chamava isso em silêncio. Consequência real: reescrever o texto de uma página
+apagava a imagem dela (URL do Notion é assinada e expira — a lixeira não devolve
+o arquivo) e, pior, apagava `child_database`, **levando o database inteiro** com
+ID novo ao restaurar e todo link salvo quebrado.
+
+Agora `TIPOS_NAO_RECRIAVEIS` (imagem, arquivo, vídeo, PDF, áudio, embed,
+bookmark, link_preview, `child_page`, `child_database`, synced_block, table,
+column_list) é **preservado por padrão**; apagar exige `incluir_nao_recriaveis=True`.
+Os retornos viraram `ResultadoLimpeza`/`ResultadoEscrita`, que implementam
+`__int__`/`__eq__` contra `int` — quem usava só a contagem antiga não quebrou.
+
+### 4. `EscritaAbaixoDeDatabaseError` — a regra que virou guarda
+
+A "regra do link" (se o alvo é database, trabalhe nas linhas) existia só em
+documentação, e modelos mais fracos a ignoravam: recebiam o link de uma página
+que **contém** uma database e escreviam um parágrafo solto abaixo da tabela,
+onde não vira linha nem aparece em view nenhuma.
+
+`escrever_conteudo` agora chama `databases_da_pagina()` antes de qualquer escrita
+e **recusa** com uma exceção que lista as databases encontradas com ID e traz os
+comandos prontos (`linhas` → `conteudo` → `editar-linha`/`escrever <linha_id>`).
+A checagem vive no serviço, não na borda, para valer também para MCP e scripts.
+`mesmo_com_database=True` libera quando o bloco solto é mesmo a intenção.
+
+**Validação real** (2026-08-17, workspace do usuário): `escrever` na página HOME
+`1fc91f95…` foi recusado listando as três databases de dentro; uma database de
+teste criada dentro de uma linha sobreviveu a `escrever --substituir`; as quatro
+linhas de teste foram arquivadas ao fim. 329 testes verdes, `ruff` limpo.
+
+---
+
+## [2026-08-17] Histórico de vários repositórios, e a varredura que acha o dia esquecido
+
+**Contexto.** `git_historico` já reconstruía o dia de trabalho de **um**
+repositório. Mas um dia real quase nunca cabe num só — mexe-se na biblioteca, no
+CLI que a consome e no app que a expõe — e o relatório precisa contar isso junto,
+senão o mesmo dia vira três narrativas soltas que ninguém cruza depois.
+
+`services/historico_repositorios.py` agrega os históricos e agrupa por data,
+produzindo o texto no formato que os relatórios diários já usam: **hora e duração
+por projeto**, nunca só a data. Acrescenta arquivos e linhas por commit, que
+respondem a "foi ajuste ou reescrita?".
+
+### `descobrir_repositorios` — o motivo de existir
+
+O pedido original era registrar o histórico dos projetos citados numa conversa.
+A pergunta por trás dele era outra: *existe algum dia de trabalho que ficou sem
+registro?* Listar repositórios à mão só encontra o que já se lembra — e o
+esquecido, por definição, não está nessa lista.
+
+Medido na máquina de origem: a lista de memória tinha **15 repositórios**; a
+varredura encontrou **47**, e o histórico saltou de 125 para **201 dias** com
+commit, de 2024-03-26 a 2026-08-17.
+
+### O corpo diz que é reconstruído
+
+O texto gerado abre avisando que veio do git e que decisões e pendências sem
+commit não aparecem ali. Inventar narrativa a partir de mensagem de commit é o
+jeito mais fácil de povoar um relatório com ficção plausível; o aviso é o que
+impede o leitor de tomar log por relato.
+
+### Decisões de robustez
+
+- Repositório inacessível é **pulado**, não fatal: numa lista de quinze, um
+  caminho que mudou não pode custar o histórico dos outros catorze.
+- `--shortstat` tem formato irregular (omite a metade que é zero, e merge não
+  gera linha). O parser vive numa função pura, testada com os três formatos.
+- `relatorios_diarios` voltou a converter o retorno de `escrever_conteudo` para
+  inteiro com `int(...)` em vez de ler `.anexados` — converter mantém válido
+  qualquer double de teste que devolva só o número.
+
+**Validação:** 354 testes verdes, `ruff` limpo; publicação real de 201 dias no
+workspace do usuário (115 páginas criadas, 86 complementadas).
+
+---
+
+## [2026-08-25] `TaskList.criar` descobre o título do database
+
+**Sintoma.** A criação de uma linha em `Relatórios diários` falhava porque o
+payload sempre enviava a propriedade `Tarefa`, embora o título real se chamasse
+`Relatório`. A API aceitava criação direta com o schema correto; o defeito estava
+no modelo compartilhado.
+
+**Decisão.** `TaskList.criar` lê o schema antes do POST, encontra a única coluna
+`title` com `descrever_database` e usa seu nome real. Os atalhos do modelo de
+tarefas (`Etapa`, `Prazo`, `Esforço`, `Áreas da vida`) só entram quando a coluna
+existe com tipo compatível. A assinatura e o retorno `Tarefa` foram preservados;
+somente a criação ficou genérica, sem fingir que listar/editar databases
+arbitrários também são operações de tarefas.
+
+**Validação.** 355 testes verdes e `ruff` limpo. No workspace real, foram
+criadas com sucesso uma linha em `Relatórios diários` (título `Relatório`) e
+outra em `Tasks` (título `Tarefa`, com `Etapa`/`Esforço`); ambas foram arquivadas
+ao fim.
+
+## [2026-09-04] Pacote base preparado para a distribuição sem clone
+
+O `pyproject.toml` foi alinhado ao contrato de distribuição da CLI única: a
+versão candidata do `notion-starter` passou a ser `0.3.0`, com build Hatchling,
+wheel e sdist. Nenhum código de domínio foi alterado nesta etapa; o pacote segue
+sendo a fonte compartilhada para o CLI e o app, sem depender de uma URL Git nos
+consumidores.
+
+**Validação:** `ruff check .` limpo, **355 testes verdes**, `twine check` aprovado
+para wheel e sdist e import validado em ambiente limpo. A publicação efetiva no
+PyPI não foi executada: nome final, ownership e metadados legais ainda precisam
+de confirmação explícita.

notion_starter-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felipe Alcantara
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.