kotsu-cli 0.1.0__py3-none-any.whl

kotsu_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,252 @@
+Metadata-Version: 2.5
+Name: kotsu-cli
+Version: 0.1.0
+Summary: Cozy personal finance in your terminal: income, expenses and installments of the month on one screen.
+Project-URL: Homepage, https://github.com/Sera-DAI/kotsu
+Project-URL: Issues, https://github.com/Sera-DAI/kotsu/issues
+Project-URL: Português, https://github.com/Sera-DAI/kotsu/blob/main/README.pt-BR.md
+Author: Sera-DAI
+License-Expression: MIT
+License-File: LICENSE
+Keywords: budget,finance,terminal,textual,tui
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.11
+Requires-Dist: textual<9,>=8.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/banner.en.svg" alt="Kotsu: cozy personal finance in your terminal" width="100%">
+</p>
+
+<p align="center"><b>English</b> · <a href="https://github.com/Sera-DAI/kotsu/blob/main/README.pt-BR.md">Português (Brasil)</a></p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/python-3.11%2B-ff7fb8?style=flat-square&labelColor=1d1424&logo=python&logoColor=ffe9f4" alt="Python 3.11+">
+  <img src="https://img.shields.io/badge/terminal-Windows%20%C2%B7%20Linux-ff7fb8?style=flat-square&labelColor=1d1424&logo=windowsterminal&logoColor=ffe9f4" alt="Windows Terminal and Linux">
+  <img src="https://img.shields.io/badge/data-only%20on%20your%20computer-ffa28c?style=flat-square&labelColor=1d1424&logo=sqlite&logoColor=ffe9f4" alt="Local data">
+  <img src="https://img.shields.io/badge/license-MIT-ffa28c?style=flat-square&labelColor=1d1424" alt="MIT license">
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/stack/python.svg" width="44" alt="Python" title="Python">
+  <img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/stack/githubactions.svg" width="44" alt="GitHub Actions" title="GitHub Actions">
+  <img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/stack/claude.svg" width="44" alt="Claude" title="Claude">
+</p>
+
+<p align="center"><sub>Built with Python, Textual, SQLite and Claude</sub></p>
+
+<p align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/divisor.svg" width="420" alt=""></p>
+
+# Kotsu
+
+**Kotsu** (コツコツ, *kotsukotsu*) is a Japanese word for "little by little, steadily". It is a terminal app for everyday money: income, expenses and the month's installments on a single screen, in a pink and salmon **Cotton Candy** look. No giant spreadsheet, no dashboard full of charts. You jot an entry on one line, see the whole month and get on with your day.
+
+It runs on Windows Terminal and Linux, works offline and keeps everything in a SQLite file on your computer. No account, no cloud, no telemetry, no ads.
+
+> The app interface is in Brazilian Portuguese for now (labels such as *receitas* = income, *despesas* = expenses, *saldo* = balance). The commands and keys below work the same in any language.
+
+## Contents
+
+- [I. What it does](#i-what-it-does)
+- [II. Install](#ii-install)
+- [III. Use](#iii-use)
+- [IV. Your data and backups](#iv-your-data-and-backups)
+- [V. Under the hood](#v-under-the-hood)
+- [VI. Development](#vi-development)
+- [VII. License](#vii-license)
+
+## I. What it does
+
+<table>
+  <tr>
+    <td width="72" align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/icones/lancar.svg" width="44" alt=""></td>
+    <td><b>Quick line</b><br><code>89,90 mercado #alimentação @nubank</code> and Enter. No forms: the amount comes first, then account, category and date in any order.</td>
+  </tr>
+  <tr>
+    <td align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/icones/parcelas.svg" width="44" alt=""></td>
+    <td><b>One screen</b><br>Income, expenses and balance for the month, one line per account (each with its own color) and the list of entries. The ← / → arrows switch months.</td>
+  </tr>
+  <tr>
+    <td align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/icones/todomes.svg" width="44" alt=""></td>
+    <td><b>Installments and "every month"</b><br><code>120 geladeira @nubank 10x</code> becomes 10 installments, one per month. Categories marked "every month" (rent, internet, salary) show up on their own, with a <code>↻</code>.</td>
+  </tr>
+  <tr>
+    <td align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/icones/temas.svg" width="44" alt=""></td>
+    <td><b>Two Cotton Candy themes</b><br>Night (default) and light, with hearts, a little face and "zzz… zerada" when an account is empty. The <code>t</code> key switches and your choice is saved.</td>
+  </tr>
+  <tr>
+    <td align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/icones/teclado.svg" width="44" alt=""></td>
+    <td><b>Keyboard first</b><br>Everything has a key, and the footer reminds you which. Filter by <code>@account</code> or <code>#category</code> with <code>/</code>.</td>
+  </tr>
+  <tr>
+    <td align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/icones/privado.svg" width="44" alt=""></td>
+    <td><b>Truly private</b><br>Your data stays on your computer. Kotsu never sends anything over the network.</td>
+  </tr>
+</table>
+
+## II. Install
+
+<table>
+  <tr>
+    <td width="72" align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/icones/instalar.svg" width="44" alt=""></td>
+    <td>Requires Python 3.11 or newer and <a href="https://pipx.pypa.io/">pipx</a>. The package is not on PyPI yet: install straight from GitHub.</td>
+  </tr>
+</table>
+
+Windows Terminal (PowerShell), in one line:
+
+```powershell
+irm https://raw.githubusercontent.com/Sera-DAI/kotsu/main/instalar.ps1 | iex
+```
+
+Linux/macOS (needs pipx; the script tells you if it is missing):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Sera-DAI/kotsu/main/instalar.sh | bash
+```
+
+Or step by step, without a script:
+
+Windows Terminal (PowerShell):
+
+```powershell
+py -m pip install --user pipx
+py -m pipx ensurepath
+py -m pipx install kotsu-cli
+```
+
+Linux (Debian/Ubuntu):
+
+```bash
+sudo apt install pipx
+pipx ensurepath
+pipx install kotsu-cli
+```
+
+Reopen the terminal and run `kotsu`. To update: `pipx upgrade kotsu-cli` (or run the installer again). To remove: `pipx uninstall kotsu-cli` (your data stays in the data folder).
+
+## III. Use
+
+```text
+ ☁ Algodão-Doce ☁   novembro de 2026
+
+ ♡ receitas 3.500,00   ✧ despesas 432,90   ☆ saldo 3.067,10   (◕‿◕)♡
+
+ ♡ itaú     ♥♥♥♥♥♥♥♥♥♥♥♥♥♥·    -210,50  +3.500,00
+ ♡ nubank   ♥♥♥♥♥♥♥♥♥♥♥♥♥♥     -222,40
+
+ Data   Descrição   Categoria     Conta    Valor
+ 08/11  padaria     alimentação   nubank   12,50
+ 07/11  mercado     alimentação   nubank   89,90
+```
+
+| Key | Action |
+|---|---|
+| `l` | opens the quick line (Enter saves, Esc closes) |
+| ← / → | previous / next month |
+| `/` | filters by `@account`, `#category`, both, or just a name (empty Enter or Esc clears) |
+| `e` | edits the selected entry in the quick line, date included |
+| `c` | copies the selected entry into the quick line, dated today |
+| `d` | deletes the selected entry (an installment asks "only this one or all?") |
+| `r` | renames the selected entry |
+| `m` | turns "every month" on/off for the selected entry's category |
+| `b` | manual database backup (a new copy in `backups/`) |
+| `t` | switches the theme (Cotton Candy night or light) |
+| `v` | shows the check code (same on another device = same data) |
+| `q` | quits |
+
+The line starts with the amount; the rest comes in any order:
+
+```text
+89,90 mercado #alimentação @nubank     expense (no sign)
++3500 salário @itaú                    income
+120 geladeira #casa @nubank 10x        10 installments of 120.00, one per month
+45 farmácia ontem                      date: ontem (yesterday), 15/10 or 15/10/2025 (default: today)
+```
+
+Every entry needs an `@account`; without one the line is not saved. An account or category that does not exist yet asks whether to create it. Editing or renaming an installment asks "only this one or all?". Amounts use a decimal comma and dates are day/month, as in Brazil.
+
+### ↻ Categories that repeat every month
+
+When you create a category, Kotsu asks whether it repeats every month (or press `m` on an existing one). Every new entry in it reappears each month with the same amount, account and day (day 31 becomes the last day of the month), with no end, until you stop it. Months appear as you navigate with ← / →, up to 24 months ahead of today. Deleting, editing or renaming one asks "only this month or the following ones?".
+
+## IV. Your data and backups
+
+<table>
+  <tr>
+    <td width="72" align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/icones/backup.svg" width="44" alt=""></td>
+    <td>
+      <ul>
+        <li><b>Where it lives:</b> <code>%APPDATA%\money-cli</code> on Windows and <code>~/.local/share/money-cli</code> on Linux (or the folder in the <code>MONEY_CLI_DADOS</code> variable). <code>kotsu --dados FOLDER</code> opens another folder.</li>
+        <li><b>Manual backup:</b> the <code>b</code> key creates <code>backups/money.YYYY-MM-DD-HHMMSS.sqlite</code> and keeps the 5 most recent copies. Kotsu never backs up on its own.</li>
+        <li><b>Using two computers (Google Drive):</b> on both, run <code>kotsu --pasta-dados "G:\My Drive\Kotsu"</code> (any existing data on the computer is copied there; if both already have data, choose which one wins). Keep the folder "Available offline". Use one computer at a time: Kotsu warns if it is open on the other one and refuses to open if Drive created conflicting copies (<code>--forcar</code> skips the warning). Backups from the <code>b</code> key stay in the local folder, outside Drive. <code>kotsu --pasta-dados-padrao</code> undoes it.</li>
+        <li><b>Merging with another device:</b> <code>kotsu --exportar data.json</code> writes everything to a file; on the other device, <code>kotsu --importar data.json</code> merges it with what is there (the most recent change to each entry wins, and deleted entries stay deleted). Do it both ways and check: <code>kotsu --conferir</code> shows a short code that is the same on both when the data is the same; <code>kotsu --conferir data.json</code> lists the differences. Before importing, Kotsu saves <code>backups/money.antes-da-troca.sqlite</code>.</li>
+        <li><b>No password or encryption:</b> protect your computer and the folder as you would any personal file.</li>
+        <li><b>Restore:</b> close the app, move the current <code>money.sqlite</code> elsewhere, copy the chosen backup to <code>money.sqlite</code>, open the app and check the totals.</li>
+      </ul>
+    </td>
+  </tr>
+</table>
+
+## V. Under the hood
+
+<table>
+  <tr>
+    <td width="72" align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/icones/estrutura.svg" width="44" alt=""></td>
+    <td>Three layers, and a test fails if one of them imports what it must not. Financial rules (totals, installments, the quick-line parser) live in the domain; the screen only displays.</td>
+  </tr>
+</table>
+
+```mermaid
+%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#41274f", "primaryTextColor": "#ffe9f4", "primaryBorderColor": "#ff7fb8", "lineColor": "#ffa28c", "secondaryColor": "#291b33", "tertiaryColor": "#1d1424", "fontFamily": "Segoe UI, sans-serif"}}}%%
+flowchart LR
+    T["tela/<br>Textual: display only"] --> A["armazenamento/<br>SQLite, migrations, backup"]
+    T --> D["dominio/<br>money in cents,<br>installments, quick line"]
+    A --> D
+    A --> F[("money.sqlite<br>on your computer")]
+```
+
+- Money is an integer number of cents, never a `float`; the sign comes from the type (income or expense).
+- Every write is a transaction: all or nothing. Changed the schema? A numbered migration, with a copy of the database made first.
+- Totals are never stored: SQL computes them per month.
+
+Full contributor rules (in Portuguese): [AGENTS.md](AGENTS.md).
+
+## VI. Development
+
+<table>
+  <tr>
+    <td width="72" align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/icones/dev.svg" width="44" alt=""></td>
+    <td>Requires Python 3.11+. The tests never touch the network.</td>
+  </tr>
+</table>
+
+```bash
+git clone https://github.com/Sera-DAI/kotsu.git
+cd kotsu
+python -m venv .venv
+# Windows: .venv\Scripts\activate    Linux: source .venv/bin/activate
+pip install -e ".[dev]"
+kotsu --dados ./tmp                          # uses a test folder
+python ferramentas/verificar.py --rapido     # lint + fast tests
+python ferramentas/verificar.py              # everything, same as CI
+```
+
+## VII. License
+
+<table>
+  <tr>
+    <td width="72" align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/icones/licenca.svg" width="44" alt=""></td>
+    <td><a href="https://github.com/Sera-DAI/kotsu/blob/main/LICENSE">MIT</a>. Made with care, little by little.</td>
+  </tr>
+</table>
+
+<p align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/divisor.svg" width="420" alt=""></p>

kotsu_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,33 @@
+money_cli/__init__.py,sha256=fst8zy8ia_p-wERJK3zPVksz5g_PXiKOUHVHxv_RY88,72
+money_cli/__main__.py,sha256=kvoZiYTk_BKgasOophgCNb9AWJWY-8Byu2mEKJCf4Jw,7945
+money_cli/armazenamento/__init__.py,sha256=m2cds88krvPtWa326k9ixijdYc5ymNL5XY5vFrjBOjc,135
+money_cli/armazenamento/backup.py,sha256=dU4VpLSuoeupJx8r9wGxq5nxrXOiQ4Gafcd9XFJCbgg,2673
+money_cli/armazenamento/banco.py,sha256=909n4leU8e_UTkcY0h2rvH-YPnyQ0OiV4HBNjA7JFeQ,20840
+money_cli/armazenamento/caminhos.py,sha256=deCfRPCwnWU9J5tsR4ZQe7tA71k61fzDt7MFu2REfpw,2478
+money_cli/armazenamento/preferencias.py,sha256=YPDoBcNZo4FTAihQJssXLDnwa1uFOvJZvkTl7fbAYAg,1025
+money_cli/armazenamento/trava.py,sha256=zHfmHCfilJy2S4DlxKf87lp5dFlT9MQJ11_ijbJWwKw,4433
+money_cli/armazenamento/troca.py,sha256=tMEYlEpXI3dAfMUyNRDlaimtxvwxZrxCU8J6l9XpZfc,10630
+money_cli/armazenamento/migracoes/0001_inicial.sql,sha256=pO0n8J9gYJZDmrUvkz9ADf9MeuCan8a0RaNX6QJBLDE,1424
+money_cli/armazenamento/migracoes/0002_recorrencia.sql,sha256=yEs_QhQCXRuLA7DXTMS1fZpQo_Aw5kM5rSdqrknm9xU,1122
+money_cli/armazenamento/migracoes/0003_mesclagem.sql,sha256=wr5jaxDlIbtI5fi_m3OnHiN9-F6rI4KHl-vkH07n8ok,2439
+money_cli/armazenamento/migracoes/__init__.py,sha256=fijRhzsluMP5iL9CulV_290UDTFWj6k0yPUVMgkuRI4,1028
+money_cli/dominio/__init__.py,sha256=cmvisdxU6BwtvcundWYs1KQCwSRbzxKLcHNE-cFvrjY,198
+money_cli/dominio/dinheiro.py,sha256=kcuwt09F9evqZdHHOrMc7qGhlkbTG_okEdMuH2T0Mt8,355
+money_cli/dominio/filtro.py,sha256=ZuwodluBDmybLiAAjQuB4e0Eay9QYp2liDcjdbAKRpU,1998
+money_cli/dominio/linha.py,sha256=8DINcGnDUfVZLbqvSzgD1pYcgvxfjMBut_BRxn19GBw,5954
+money_cli/dominio/mes.py,sha256=LXyJ6pKpwIGhJ0tIC0CQCchmrk0Fe8RRcZ8EOjbrMbw,1214
+money_cli/dominio/mescla.py,sha256=dDculF64YjLMKGcXCSRI7UlAhKYjOYNOvCuRoKnoLOU,17295
+money_cli/dominio/parcelas.py,sha256=S3NOgBtXeaL77dmIBDjbfq8cakIzNOBoVSrg_OnOwgc,1596
+money_cli/dominio/recorrencia.py,sha256=THYjBCbLM7y5hbW1bGYXbXInoQvcmeEZVWyoBbLZovo,712
+money_cli/dominio/tipos.py,sha256=W4L_Kzwp60j0U9pIBPfHAHECb9XlOsGuqJcpM8o_xEs,2502
+money_cli/dominio/totais.py,sha256=HHaAbF_LF_Th5FFCOFQz8EpOKyU2sqn5OC921gWxouU,451
+money_cli/tela/__init__.py,sha256=i2hx_7yc99VbenvOKRuKIfA883--ROqSq_d45CMSock,83
+money_cli/tela/app.py,sha256=Jitbt7PHiXf-LaGb4d2snNJP2qE8AGKk3VIsZOwbVCE,32336
+money_cli/tela/cores.py,sha256=M5EPoVLZvyJL0FRq8tx6a_NEh8kevj-b1Jlx_--YtEY,918
+money_cli/tela/perguntas.py,sha256=aSHyOYa92P-Awt5EkcLaNPWKjQEz6DYWsXuazEHiAMY,4581
+money_cli/tela/temas.py,sha256=inxLMPQMXGwl9leM4eCoeQuK8auLmnqRQ1LN1lKZ72E,2203
+kotsu_cli-0.1.0.dist-info/METADATA,sha256=Cv8_NqScSil4PW0mUwtf7msfgOwCcKHTEyYZEayXeis,13640
+kotsu_cli-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+kotsu_cli-0.1.0.dist-info/entry_points.txt,sha256=E0svGN498wq8qvDw8820U6nJItPV5aVpl0qzFopHidw,82
+kotsu_cli-0.1.0.dist-info/licenses/LICENSE,sha256=9_YiWxWshiRbKfTki_c_6nuceaqeME91Vd3S6mXhJMQ,1065
+kotsu_cli-0.1.0.dist-info/RECORD,,

kotsu_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

kotsu_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+kotsu = money_cli.__main__:main
+money = money_cli.__main__:main

kotsu_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sera-DAI
+
+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.

money_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Money CLI: finanças pessoais no terminal."""
+
+__version__ = "0.1.0"

money_cli/__main__.py

@@ -0,0 +1,197 @@
+"""Ponto de entrada: `kotsu` (ou `money`, ou `python -m money_cli`)."""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import sys
+from pathlib import Path
+
+from money_cli import __version__
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="kotsu", description="Finanças pessoais no terminal.")
+    parser.add_argument("--dados", type=Path, help="pasta de dados (padrão: pasta do usuário)")
+    parser.add_argument(
+        "--pasta-dados",
+        type=Path,
+        metavar="PASTA",
+        help="guarda PASTA (ex.: no Google Drive) como pasta de dados deste computador e sai",
+    )
+    parser.add_argument(
+        "--pasta-dados-padrao",
+        action="store_true",
+        help="volta à pasta de dados padrão deste computador e sai",
+    )
+    parser.add_argument(
+        "--forcar",
+        action="store_true",
+        help="abre mesmo com o Kotsu aberto em outro computador ou com cópias em conflito",
+    )
+    troca = parser.add_mutually_exclusive_group()
+    troca.add_argument(
+        "--exportar",
+        type=Path,
+        metavar="ARQUIVO",
+        help="escreve os dados num arquivo de troca para outro aparelho e sai",
+    )
+    troca.add_argument(
+        "--importar",
+        type=Path,
+        metavar="ARQUIVO",
+        help="junta aos dados daqui o arquivo de troca de outro aparelho e sai",
+    )
+    troca.add_argument(
+        "--conferir",
+        type=Path,
+        nargs="?",
+        const=True,
+        metavar="ARQUIVO",
+        help="mostra o código de conferência; com ARQUIVO, as diferenças para ele, e sai",
+    )
+    parser.add_argument("--version", action="version", version=f"money-cli {__version__}")
+    args = parser.parse_args(argv)
+
+    if args.pasta_dados is not None or args.pasta_dados_padrao:
+        return _configurar_pasta(args)
+
+    from money_cli.armazenamento import trava
+    from money_cli.armazenamento.banco import Banco
+    from money_cli.armazenamento.caminhos import arquivo_do_banco, pasta_de_backups
+    from money_cli.tela.app import MoneyApp
+
+    arquivo = arquivo_do_banco(args.dados)
+    pasta = arquivo.parent
+    copias = trava.conflitos(pasta, arquivo.name)
+    if copias and not args.forcar:
+        lista = "\n".join(f"  {c}" for c in copias)
+        print(
+            "O Drive guardou cópias do banco em conflito (dois computadores salvaram ao mesmo\n"
+            f"tempo):\n{lista}\n"
+            "Veja qual tem os lançamentos certos, deixe só ele como money.sqlite e mova as\n"
+            "outras para fora da pasta. Para abrir mesmo assim: kotsu --forcar",
+            file=sys.stderr,
+        )
+        return 1
+    try:
+        minha = trava.tomar(pasta, f"{dt.datetime.now():%d/%m/%Y %H:%M}", args.forcar)
+    except trava.BancoEmUso as erro:
+        print(
+            f"{erro}\nFeche o Kotsu lá e espere o Drive terminar de sincronizar. Se ele foi\n"
+            "fechado à força, use: kotsu --forcar",
+            file=sys.stderr,
+        )
+        return 1
+    try:
+        banco = Banco.abrir(arquivo, pasta_de_backups(pasta))
+        try:
+            if args.exportar or args.importar or args.conferir:
+                return _trocar(banco, args)
+            MoneyApp(banco, pasta_tema=pasta).run()
+        finally:
+            banco.fechar()
+    finally:
+        minha.liberar()
+    return 0
+
+
+def _trocar(banco, args: argparse.Namespace) -> int:
+    """`--exportar`, `--importar` e `--conferir` (D39): troca de dados entre aparelhos."""
+    from money_cli.armazenamento import troca
+    from money_cli.dominio import mescla
+
+    try:
+        if args.exportar:
+            codigo = troca.exportar(banco, args.exportar.expanduser())
+            print(f"Dados exportados para {args.exportar}\nCódigo de conferência: {codigo}")
+        elif args.importar:
+            resumo = troca.importar(banco, args.importar.expanduser())
+            if resumo.nada:
+                print("Nada mudou aqui: este aparelho já tinha tudo o que o arquivo traz.")
+            else:
+                print(
+                    f"Lançamentos: {resumo.entraram} entraram, {resumo.mudaram} mudaram,"
+                    f" {resumo.sairam} saíram."
+                )
+            print(f"Código de conferência: {troca.codigo(banco)}")
+            diferencas = troca.comparar(banco, args.importar.expanduser())
+            if not diferencas.iguais:
+                print(
+                    "O outro aparelho ainda não tem tudo o que há aqui: exporte daqui e"
+                    " importe lá para os códigos baterem."
+                )
+        elif args.conferir is True:
+            print(f"Código de conferência: {troca.codigo(banco)}")
+        else:
+            aqui = troca.ler_estado(banco)
+            la = troca.ler_arquivo(args.conferir.expanduser())
+            diferencas = mescla.comparar(aqui, la)
+            print(f"Código daqui:      {diferencas.codigo_aqui}")
+            print(f"Código do arquivo: {diferencas.codigo_la}")
+            if diferencas.iguais:
+                print("Iguais: os dois têm os mesmos dados.")
+                return 0
+            for titulo, itens, estado in (
+                ("Só aqui", diferencas.so_aqui, aqui),
+                ("Só no arquivo", diferencas.so_la, la),
+            ):
+                if itens:
+                    print(f"\n{titulo} ({len(itens)}):")
+                    for item in itens:
+                        print(f"  {mescla.descrever(item, estado)}")
+            if diferencas.diferentes:
+                print(f"\nDiferentes ({len(diferencas.diferentes)}):")
+                for meu, dele in diferencas.diferentes:
+                    print(f"  aqui:    {mescla.descrever(meu, aqui)}")
+                    print(f"  arquivo: {mescla.descrever(dele, la)}")
+            if not (diferencas.so_aqui or diferencas.so_la or diferencas.diferentes):
+                print("Os lançamentos são os mesmos; a diferença está em contas, categorias,")
+                print("séries de todo mês ou exclusões ainda não trocadas.")
+            return 2
+    except mescla.ErroDeTroca as erro:
+        print(f"Não deu certo: {erro}", file=sys.stderr)
+        return 1
+    except OSError as erro:
+        print(f"Não foi possível gravar o arquivo: {erro}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def _configurar_pasta(args: argparse.Namespace) -> int:
+    """`--pasta-dados`: aponta este computador para uma pasta (ex.: do Drive) e sai."""
+    from money_cli.armazenamento import caminhos
+    from money_cli.armazenamento.banco import copiar_arquivo_banco
+
+    try:
+        if args.pasta_dados_padrao:
+            caminhos.gravar_pasta_configurada(None)
+            print(f"Pasta de dados: {caminhos.pasta_local()} (padrão).")
+            return 0
+        destino = args.pasta_dados.expanduser().resolve()
+        novo = caminhos.arquivo_do_banco(destino)
+        atual = caminhos.arquivo_do_banco(caminhos.pasta_de_dados())
+        if atual.resolve() != novo and atual.exists():
+            if novo.exists():
+                print(
+                    f"Já existe um banco em {novo} e outro em {atual}. O Kotsu não junta os\n"
+                    "dois: escolha qual vale, mova o outro para fora e rode de novo.",
+                    file=sys.stderr,
+                )
+                return 1
+            destino.mkdir(parents=True, exist_ok=True)
+            copiar_arquivo_banco(atual, novo)
+            print(f"Banco copiado para {novo} (o original continua em {atual}).")
+        caminhos.gravar_pasta_configurada(destino)
+    except OSError as erro:
+        print(f"Não foi possível configurar a pasta: {erro}", file=sys.stderr)
+        return 1
+    print(
+        f"Pasta de dados deste computador: {destino}\nBackups (tecla b) ficam em "
+        f"{caminhos.pasta_local() / 'backups'}, fora da sincronização."
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

money_cli/armazenamento/__init__.py

@@ -0,0 +1,4 @@
+"""Camada de armazenamento: SQLite, migrações, gravação atômica.
+
+Depende só de `dominio`. Nunca importa `tela` nem Textual.
+"""

money_cli/armazenamento/backup.py

@@ -0,0 +1,70 @@
+"""Backup manual do SQLite: cada pedido publica uma cópia completa nova e mantém as 5 últimas."""
+
+from __future__ import annotations
+
+import datetime as dt
+import os
+import re
+import sqlite3
+import tempfile
+from pathlib import Path
+
+MANTER = 5
+
+
+def backup_manual(
+    conexao: sqlite3.Connection,
+    caminho: Path,
+    agora: dt.datetime,
+    pasta: Path | None = None,
+) -> Path:
+    from money_cli.armazenamento.banco import copiar_banco
+
+    pasta = pasta or caminho.parent / "backups"
+    pasta.mkdir(parents=True, exist_ok=True)
+    base = f"{caminho.stem}.{agora:%Y-%m-%d-%H%M%S}"
+    descritor, nome = tempfile.mkstemp(prefix=".backup-", suffix=".tmp", dir=pasta)
+    os.close(descritor)  # Windows: fechar antes de SQLite abrir o mesmo arquivo.
+    temporario = Path(nome)
+    try:
+        copiar_banco(conexao, temporario)
+        with temporario.open("r+b") as arquivo:
+            os.fsync(arquivo.fileno())
+        # Mesmo segundo: sufixo maior que o de qualquer cópia existente, para que a ordem
+        # por nome continue sendo a ordem de criação depois da poda.
+        usados = [_numero(p.name, base) for p in pasta.glob(f"{base}*.sqlite")]
+        for tentativa in range(max([0, *usados]) + 1, max([0, *usados]) + 1000):
+            destino = pasta / (f"{base}.sqlite" if tentativa == 1 else f"{base}-{tentativa}.sqlite")
+            try:
+                # Publicação atômica sem sobrescrever cópia existente (NTFS e Linux).
+                os.link(temporario, destino)
+                break
+            except FileExistsError:
+                continue
+        else:
+            raise OSError("não foi possível escolher um nome livre para o backup")
+    finally:
+        temporario.unlink(missing_ok=True)
+    _podar(pasta, caminho.stem)
+    return destino
+
+
+def _numero(nome: str, base: str) -> int:
+    resto = nome[len(base) : -len(".sqlite")]
+    return int(resto[1:]) if re.fullmatch(r"-\d+", resto) else 1 if resto == "" else 0
+
+
+def _podar(pasta: Path, stem: str) -> None:
+    """Só depois de publicar: mantém as `MANTER` mais recentes.
+
+    Só olha cópias com o nome deste módulo (`money.AAAA-MM-DD-HHMMSS[-N].sqlite`); cópias de
+    pré-migração, backups de outro formato e outros arquivos nunca são tocados.
+    """
+    padrao = re.compile(re.escape(stem) + r"\.(\d{4}-\d{2}-\d{2}-\d{6})(?:-(\d+))?\.sqlite")
+    copias = []
+    for arquivo in pasta.iterdir():
+        achado = padrao.fullmatch(arquivo.name)
+        if achado and arquivo.is_file():
+            copias.append(((achado[1], int(achado[2] or 1)), arquivo))
+    for _, antigo in sorted(copias, reverse=True)[MANTER:]:
+        antigo.unlink(missing_ok=True)