bea 0.2.0: jedna inštalácia, celý Beancount nástrojový reťazec

Ak ste niekedy odovzdali kolegovi, novému notebooku alebo nočnému cron jobu fungujúce Beancount nastavenie, viete, že účtovníctvo nikdy nebolo tou ťažkou časťou. Tou ťažkou časťou bol nástrojový reťazec: Python, ktorý sedí, bean-check a bean-query v ceste, knižnica na reporty pritiahnutá kvôli jednej súvahe a formátovač, ktorý prepíše vaše súbory vo chvíli, keď sa ho na niečo spýtate. bea 0.2.0, vydaný 12. septembra 2026, nahrádza tento zoznam úloh jednou inštaláciou. Príkaz bea teraz nesie kompletný natívny Beancount nástrojový reťazec, spúšťa ho v rámci spravovaného enginu, ktorý si sám zabezpečí, a zachováva strojovo čitateľný kontrakt, na ktorý sa už spoliehajú skripty a AI agenti.

Toto je poznámka k vydaniu 0.2.0, napísaná tak, ako sledujeme vydanie interne: čo vyšlo, čo sa zmenilo pod kapotou, ako to bolo overené predtým, než sa to dostalo do balíčkového indexu, čo to zámerne ešte nerobí a ako upgradovať. Ak chcete radšej príbeh prvého spustenia, príspevok k vydaniu 0.1.0 a rýchly štart CLI sú kratšie čítania.

Vydanie na prvý pohľad​

Dva kanály publikujú rovnaký príkaz. Vyberte si jeden a potom potvrďte, že odpovedá svojou verziou:

$ brew install bex-co/tap/bea        # macOS a Linuxbrew
$ uv tool install beancount-io       # kdekoľvek s uv a Python 3.12 alebo novším
$ bea --version
bea 0.2.0

Karta vydania 0.2.0: tag a dátum publikácie, verzie Beancount a Beanquery, na ktoré je spravovaný engine pripnutý, dve voliteľné funkcie enginu a verzie Pythonu, na ktorých bolo vydanie nainštalované a testované.

Čo sa zmenilo pod kapotou: spravovaný engine​

V 0.1.0 bea importoval Beancount do svojho vlastného procesu, ako by to urobil akýkoľvek Python nástroj. To fungovalo, ale urobilo z graf závislostí CLI grafom závislostí Beancount a nechalo „nainštalujte Beancount ako prvý“ ako nepísaný krok v každej príručke.

0.2.0 vedie čiaru cez stred programu. Frontend bea, časť, ktorá vlastní príkazy, možnosti a vykresľovanie, nikdy nenačítava Beancount, Beanquery ani vložený Fava reportovací kód. Lokálna práca s účtovnou knihou beží v spravovanom engine: samostatnom Python prostredí, ktoré bea zabezpečí z hash-pripnutého lock súboru a spustí ako podradený interpret. Frontend pošle JSON požiadavku cez túto hranicu a vykreslí, čo sa vráti. Neinštalujete Beancount, nedávate bean-* nástroje do svojej cesty ani nerozmýšľate nad tým, ktorý Python našli.

Ako engine príde, závisí od kanála:

• Homebrew vytvorí prostredia frontendu a enginu počas inštalácie. Lokálne príkazy používajú keg-lokálny engine bez ďalšieho sťahovania.
• PyPI (uv tool install alebo pipx) zabezpečí pri prvom použití. Prvý lokálny príkaz, ktorý potrebuje engine, stiahne pripnutú kombináciu, čo vyžaduje sieťový prístup a uv v ceste raz. Neskoršie príkazy ho znova použijú offline z ~/.local/share/bea/engine/<verzia>, alebo pod XDG_DATA_HOME, ak ho nastavíte.

Z tohto návrhu vyplývajú tri vlastnosti a každá odstraňuje ticket na podporu, ktorý sme už videli:

1. Upgrady zostávajú spárované. bea upgrade odovzdá aktualizáciu správcovi balíčkov, ktorý nainštaloval túto kópiu, a potom znova zostaví zodpovedajúci engine, takže frontend a engine sa nikdy nemôžu rozísť do rôznych verzií.
2. Rozbitý engine sa sám uzdraví. Ak zabezpečenie zlyhá na polceste, spravované prostredie sa zahodí a znova zostaví pri ďalšom úspešnom pokuse. Osamelé bean-check binárky inde v ceste sa ignorujú, nie náhodou zachytia.
3. Ťažké voliteľné časti zostávajú voliteľné. Beangulp importovací framework potrebuje systémovú knižnicu libmagic a Beanprice ťahá závislosti na načítavanie kurzov. Žiadna z nich nie je v základnom engine. Povolíte ich explicitne, iba do enginu.

$ bea engine status
$ bea engine enable beangulp     # pomocníci pre import; potrebuje systémovú knižnicu libmagic
$ bea engine enable beanprice    # načítavanie kurzov bean-price

bea engine status hlási, či je engine zabezpečený a ktoré voliteľné funkcie sú povolené, a nepotrebuje na to sieť. Ak zabezpečenie pri prvom použití zlyhá, opravte sieť alebo uv a znova spustite akýkoľvek lokálny príkaz, napríklad bea check. Neinštalujte pip install beancount vedľa neho: frontend ho nepoužije.

Každý natívny nástroj, jeden prefix​

Engine je mechanizmus. Zmena viditeľná pre používateľa je zhoda: každý spustiteľný súbor, ktorý upstream Beancount projekt dodáva, má teraz náprotivok bea, s rovnakými argumentmi preposielanými a rovnakým výstupom zachovaným.

$ bea check                                    # bean-check, plus bea --json obálka
$ bea format main.bean -o clean.bean           # bean-format: stdout štandardne, -i prepisuje
$ bea query "SELECT account, sum(position) GROUP BY account"
$ bea doctor context main.bean 2026-01-02      # všetkých jedenásť bean-doctor operácií
$ bea example --seed 1 -o example.beancount    # bean-example
$ bea treeify < balances.txt                   # treeify
$ bea ingest identify --config ingest.py inbox # Beangulp, po engine enable
$ bea price -e USD:yahoo/AAPL                  # bean-price, po engine enable

Mapa zhody: šesť natívnych Beancount spustiteľných súborov nad prerušovanou čiarou funguje hneď po inštalácii; dva pod ňou sú preposielané do Beangulp a Beanprice, keď túto funkciu povolíte v engine.

Niektoré z týchto si zaslúžia viac než riadok v tabuľke.

bea check je bean-check s bea JSON obálkou navrstvenou navrchu: rovnaká validácia, rovnaké chybové správy a pod --json rovnaké polia valid a errors, ktoré skripty už parsujú.

bea format zmenil správanie, a to je jedna zmena v tomto vydaní, ktorá môže prekvapiť skript. V 0.1.0 bea format PATH prepísal súbor. Teraz vypíše formátovaný text na stdout a súbor nechá na pokoji. --in-place (-i) je to, čo prepisuje, --output FILE (-o) zapíše inde, --check je CI brána, ktorá skončí s 1, keď súbory potrebujú formátovanie, a --dry-run vypíše, čo by sa zmenilo. Toto nasleduje bean-format, ktorého štandard je bezpečný: príkaz, ktorý prečíta cestu a ticho ju prepíše, sa nedá najprv vyskúšať. Formátovanie je textová transformácia, nie parse, takže už neodmieta súbor so syntaktickou chybou; zarovná, čo rozpozná, a zvyšok nechá. Spustite bea check pre platnosť.

bea query získal celý natívny povrch. Berie BQL ako argument, zo stdin alebo v interaktívnom shelle, ktorý je teraz upstream Beanquery shell spustený ako podradený proces s jeho .format, .output, .run a .set príkazmi neporušenými. --format vyberá text, csv alebo beancount vykreslenie, --numberify rozdeľuje sumy do jedného stĺpca na menu, -o zapisuje do súboru a --source URI odovzdá natívny Beanquery zdroj priamo.

bea doctor sprístupňuje všetkých jedenásť bean-doctor operácií: lex, parse, roundtrip, directories, list-options, print-options, context, linked, region, missing-open a display-context. Ak ste niekedy ladiili problém s účtovaním pomocou bean-doctor context, je to rovnaký nástroj na rovnakej adrese.

bea example a bea treeify sú natívny generátor a natívny vykresľovač stromov, preposielané tak, ako sú.

bea ingest a bea price preposielajú do Beangulp identify, extract a archive a do bean-price, v uvedenom poradí, po bea engine enable. Cesta bez Pythonu pre CSV, bea import --csv, nepotrebuje ani jedno a je nezmenená.

Jedno pravidlo spája preposielané príkazy: doctor, example, treeify, price a ingest odovzdávajú svoje argumenty upstreamu nezmenené a zachovávajú upstream výstup a exit status. To tiež znamená, že berú účtovnú knihu ako svoj vlastný pozičný argument, ako v bea doctor lex main.bean, nie cez globálny --file. Obálka a kategórie exit kódov nižšie opisujú vlastné príkazy bea.

Kontrakt, ktorému skripty môžu naďalej dôverovať​

Nič na strojovo čitateľnom povrchu sa nehýbalo. Globálny --json stále dáva jednu obálku na stdout s bea, target, data a truncated, plus limit na ohraničených zoznamoch a page na stránkovaných hostovaných zoznamoch. Sumy sú desatinné reťazce, nikdy floaty, a dátumy sú ISO YYYY-MM-DD. --json znamená --no-input; takisto non-terminálové stdin alebo pravdivá premenná CI, takže nespravovaný job nikdy nečaká na človeka. --strict odmieta čiastočné odpovede aj v termináli a --allow-errors každého čítacieho príkazu sa znova prihlási.

Zlyhanie nezapíše nič na stdout a presne jeden objekt na stderr:

{
  "error": {
    "category": "validation",
    "message": "Ledger has 3 error(s). Pass --allow-errors to report anyway.",
    "exit_code": 1,
    "details": ["main.bean:1: Transaction does not balance: (2.50 USD)"]
  }
}

Päť exit kódov a reťazec category, ktorý každý nesie v JSON chybovom objekte. Skript sa vetví podľa čísla; človek číta kategóriu.

Dva detaily sú dôležité pre každého, kto opakuje pri zlyhaní. Nenulový exit neznamená univerzálne, že sa nič nezmenilo: add transactions --partial môže zapísať prijaté riadky, format -i cez viacero súborov môže niektoré prepísať pred zlyhaním na jednom a cloud ledger create --clone môže vytvoriť účtovnú knihu pred zlyhaním klonu. Prečítajte error.result pred opakovaním mutácie. A hostované príkazy mapujú HTTP status servera na rovnakú tabuľku, pričom zachovávajú správu servera: 401 a 403 skončia s 3, 400 s 2, 409 s 4 a všetko ostatné, vrátane obmedzenia rýchlosti, s 1. Zápis, ktorého výsledok CLI nemôže poznať, napríklad timeout uprostred mazania, skončí s 4 a povie to, namiesto hádania.

Sprievodca automatizáciou prevedie jq pipeline cez túto obálku od začiatku do konca.

Opravy, ktoré sa viezli​

Vydanie zhody je tiež príležitosť uzavrieť defekty, ktoré prvé vydanie odhalí. Tie pristáli medzi dvoma tagmi, každý s regresným testom:

• Čísla sa píšu ako text s pevnou desatinnou čiarkou, nikdy nie vedecký zápis, vrátane otváracích zostatkov, ktoré bea init vykresľuje. Účtovná kniha, ktorá hovorí 1E+3, je technicky platná a prakticky nečitateľná.
• Cost loty prežijú JSON serializáciu so svojimi dátumami a štítkami neporušenými a štítky lotov sú správne escapované, keď sa transakcia zapíše.
• Explicitné nulové postings sú reálne sumy počas importu, namiesto toho, aby sa čítali ako „vynechané, prosím vyrovnajte ma.“
• CSV importy idú cez jedného prísneho čitateľa. Objavovanie hlavičiek kedysi odstraňovalo názvy stĺpcov, zatiaľ čo extrakcia zachovávala surové kľúče, takže polstrovaná hlavička, ktorú dokumentácia sľubovala akceptovať, zlyhala ako chýbajúci stĺpec. Teraz sa názvy odstraňujú raz, mapovaný stĺpec sa musí objaviť presne raz a neuzavretý úvodzovka zlyhá s číslom riadku predtým, než sa čokoľvek zapíše.
• BQL načíta presnú cestu účtovnej knihy namiesto reťazca pripojenia parsovaného z URL, takže neobvyklé cesty sa vyriešia tak, ako ich rieši zvyšok CLI.
• bea balance <term> sumarizuje iba to, čo ukazuje. Zachovaný rodič už nehlási súčty vylúčených súrodencov, nesúvisiaci neoceňovaný holding už nezlyhá výber USD a obálka hlási použitý filter. Chybný vzor --account pri reportoch skončí s 2 ako chyba použitia.
• stderr v JSON režime je vždy jeden objekt, aj keď tolerované varovania predchádzajú zlyhaniu.
• Hostované poverenia zlyhajú skoro a konzistentne: BEA_TOKEN obsahujúci medzery je odmietnutý pred akoukoľvek požiadavkou, zrušené poverenie je hlásené rovnako cloud status a príkazmi účtovnej knihy a owner/name je validované pred potvrdzovacou výzvou alebo autentifikovaným volaním. cloud logout nechá BEA_TOKEN na pokoji a cloud ledger list --json vráti stránku, ktorú skutočne obslúžil.
• Homebrew formula pripája presnú URL PyPI artefaktu, takže tap inštalácia a PyPI inštalácia sú dokázateľne rovnaké byty.

Ako to bolo overené, než ste to videli​

Vydanie je tvrdenie a pipeline je dôkaz. Tag cli-v0.2.0 musí pomenovať commit na main, ktorého pyproject.toml verzia sa presne zhoduje; workflow odmieta čokoľvek iné, vrátane prípon predbežných verzií. Odtiaľ:

1. Najprv beží celá sada kontrol. make check-all pokrýva lint, formátovanie, prísny mypy, detekciu mŕtveho kódu, kontrolu driftu generovanej referencie a testovaciu sadu. Pull request vydania zaznamenáva 635 prechádzajúcich testov.
2. Lock enginu je exportovaný a hash-pripnutý a source distribution a wheel sú postavené raz. Každý neskorší krok testuje presne tieto artefakty, nie znovupostavenie.
3. Čisté inštalácie na troch operačných systémoch a dvoch Pythonoch. Wheel sa inštaluje cez uv tool a sdist cez pip na Linuxe, macOS a Windows, na Python 3.12 a 3.14, vrátane voliteľného AI extra. Homebrew job inštaluje sdist cez dočasný tap na macOS a Linuxe.
4. Publikácia je sekvenčná a bez tokenov. PyPI dostáva artefakty cez trusted publishing, takže žiadny dlhodobý API token neexistuje na únik; GitHub Release je vytvorený s priloženými publish attestations; a Formula/bea.rb je posunutý do verejného tapu s URL a hashom sdist, ktoré PyPI skutočne obslúžil.
5. Post-publikačné smoke testy inštalujú zo skutočných indexov. Samostatné joby inštalujú pripnutú verziu z PyPI a z verejného tapu a spúšťajú rovnaké zákaznícke smoke testy proti nainštalovanému spustiteľnému súboru. Zlyhanie tam nič nevracia späť, ale znamená, že vydanie potrebuje pozornosť predtým, než sa o ňom niekto dozvie.

Tento príspevok je písaný na druhej strane kroku päť.

Upgrade z 0.1.0​

Spustite upgrade cez správcu, ktorý nainštaloval vašu kópiu, alebo nechajte bea to urobiť:

$ bea upgrade --check      # hlási nainštalovanú a najnovšiu verziu a príkaz, ktorý by sa spustil
$ bea upgrade              # brew upgrade bea, uv tool upgrade beancount-io, alebo pipx upgrade beancount-io

Po dokončení správcu bea upgrade obnoví spravovaný engine, aby zostali spárované. Potom skontrolujte tri veci:

• Akýkoľvek skript, ktorý spustil bea format PATH na prepísanie súboru, teraz potrebuje bea format -i PATH. Starý štandard sa nedal náhliadnuť a nový sa dá.
• Akýkoľvek skript, ktorý sa spoliehal na format pri zachytení syntaktickej chyby, by na to mal zavolať bea check, pretože formátovanie už neparsuje.
• PyPI inštalácie potrebujú sieť a uv raz pri prvom lokálnom príkaze po upgrade, aby sa engine mohol zabezpečiť. Homebrew inštalácie nepotrebujú nič.

Všetko, čo vaše skripty už parsujú, kľúče obálky, desatinné reťazce a exit kódy, je nezmenené. Pole bea v obálke teraz číta 0.2.0.

Čo toto vydanie nerobí​

• Hostované cielenie nie je implementované. Neexistuje žiadny príznak --ledger; lokálne príkazy čítajú lokálne súbory a nikdy implicitne nenahrávajú žiadny. Hostované účtovné knihy sa spravujú pod bea cloud a pracuje sa na nich ako git klony.
• bea ask stále potrebuje extra ask a poverenia Beancount.io a nepodporuje --json. Štandardná inštalácia nenesie žiadne AI závislosti.
• Beangulp a Beanprice sú voliteľné a Beangulp potrebuje systémovú knižnicu libmagic. bea import --csv pokrýva bankové exporty bez oboch.
• Preposielané natívne príkazy nevydávajú obálku. Ak potrebujete štruktúrovaný výstup z operácie doctor, to je požiadavka, ktorú by sme chceli počuť.

Od tagu main už zachytil prvú várku QA na 0.2.0 a bude jazdiť na ďalšom vydaní: bea format číta stdin ako filter a jeho režim -o FILE odpovedá obálkou pomenúvajúcou, čo zapísal; --json check odmieta príznaky iba pre bean-check a --json je odmietnutý úplne na doctor, example a treeify, takže skript nemôže zameniť natívny text za obálku; --json query -o FILE zapisuje obálku do súboru atómovo, s --numberify aplikovaným aj na JSON; bea engine status pomenúva, ktorá vrstva enginu obsluhuje; BQL dotaz, ktorý sa otvára komentárom, beží; natívny pass-through --help funguje pred zabezpečením enginu; a .output v query shelle obnoví pôvodný prúd po zlyhanom presmerovaní.

Kam ďalej​

• Rýchly štart CLI: inštalácia, prvá účtovná kniha, prvý nákup, prvá kontrola zostatku.
• Váš prvý mesiac s bea: od init po zosúladenú mesačnú správu.
• Import bankových exportov: cesta bez Pythonu pre CSV, súbory pravidiel a Python importery.
• Automatizujte účtovníctvo s bea: riešenie účtovnej knihy, čítanie obálky, vetvenie podľa exit kódov, plánovanie.
• Referencia Beancount CLI: každý príkaz, možnosť, premenná prostredia a exit kód, kontrolované proti generovanej referencii CLI.
• Dajte svojmu AI agentovi účtovnú knihu: agent-first návod z vydania 0.1.0.
• Changelog: každé vydanie, najnovšie prvé.

Uchovávajte svoje knihy ako kód​

Nástrojový reťazec, ktorý môžete nainštalovať v jednom riadku, je reťazec, ktorý môžete odovzdať komukoľvek: spoluzakladateľovi, účtovníkovi, CI runneru, AI agentovi. Beancount.io poskytuje plain-text účtovníctvo, ktoré zostáva transparentné, verzované a reprodukovateľné, s bea ako príkazom, ktorý udržiava lokálnu účtovnú knihu v poriadku, a hostovanou službou ako miestom, kde sa vaša kniha spája s vaším tímom, telefónom a asistentom. Nainštalujte bea a spustite svoju prvú kontrolu, a ak vydanie robí niečo, čo ste neočakávali, GitHub repozitár je miesto, kde to chceme počuť.