Doctor från Larin CLI

Den användarvänliga vägen till Budget Doctor är:

larin doctor
larin budget doctor

Båda formerna kör samma Budget Doctor. larin budget utan underkommando behåller sin tidigare betydelse och visar budgetstatus.

Klienten visar samma versionsmärkta JSON-rapport som Emacs och bevarar motorns exitkod. För installationskontroll och motornära felsökning används ledgerctl doctor och ledgerctl budget doctor.

Två olika Doctor-kommandon

ledgerctl har två kontroller med olika djup:

Båda diagnostiserar. De reparerar inte filer automatiskt.

Vanlig Doctor

ledgerctl doctor

Den visar vilken kodinstallation, arbetsyta och konfigurationsfil som faktiskt används och kontrollerar bland annat:

• att Python finns och är minst version 3.10,
• att make finns,
• att hLedger finns och ligger i det stödda intervallet hledger > 1.50.4 och < 2.0=,
• att importmotorn kan kompileras,
• att routes.conf, imports/ och finance.journal finns,
• att ledgerctl:s delskript är körbara,
• budgetinvarianten när budget är aktiverad och kontrollen kan köras.

Exitstatus är 0 när alla obligatoriska kontroller passerar och 1 när minst ett fel hittas.

Budget Doctor

ledgerctl budget doctor

Maskinläsbart:

ledgerctl budget doctor --format json

Budget Doctor samlar alla oberoende fel i en körning och kontrollerar:

• arbetsytan och ledgerctl.conf,
• att budgetkatalogen och journalerna finns,
• syntax och semantik i envelopes.conf,
• överlappande konto-mappningar,
• att reservkuvertet Att kategorisera finns och har rätt konto,
• kuverttäckning för routes, merchantstandardkonton och verkliga utgifter,
• att auto.journal exakt motsvarar konfigurationen,
• att all.journal har kanonisk include-layout,
• det strikta v2-formatet i funding.journal,
• hLedgers strikta kontroll,
• vald valuta och eventuella extra commodities,
• balanssnapshot och budgetinvariant,
• att revisionsindata inte ändras under kontrollen.

Exitstatus 1 betyder att rapporten innehåller minst ett health-check-fel. Det är fortfarande en giltig rapport, inte nödvändigtvis att Doctor själv kraschade. Emacs UI behandlar därför exitkod 0 och 1 som visningsbara resultat.

Börja alltid med rätt arbetsyta

När ett fel ser orimligt ut:

pwd
ledgerctl config show
ledgerctl config path

Ett vanligt problem är att ledgerctl har hittat en annan ledgerctl.conf högre upp i katalogträdet eller via LEDGERCTL_CONFIG.

För att tvinga en viss arbetsyta i ett enskilt kommando:

LEDGERCTL_CONFIG=/home/jonix/budget/ledgerctl.conf ledgerctl doctor

Felsökningsmatris

python3 finns inte eller för gammal version

Kontrollera:

command -v python3
python3 --version

I en Guix-miljö måste rätt profil vara aktiv i samma shell där ledgerctl körs.

make finns inte

command -v make
ledgerctl config show

Konfigurationen kan peka MAKE till ett annat kommandonamn.

hLedger saknas eller är för gammal

Importens enklaste parsning kan fortfarande nå delar av motorn, men report, reconcile och budgetfunktionerna kräver en stödd hLedger-version. Larin kräver hledger > 1.50.4= och < 2.0.

command -v hledger
hledger --version

Kontrollera även om HLEDGER i ledgerctl.conf pekar på fel binär.

routes.conf saknas

ledgerctl init

init skapar endast saknade filer och ska inte skriva över en befintlig journal.

merchant-db.json saknas

Det påverkar framför allt add, display-namn och suggest-routes.

För en ny arbetsyta:

ledgerctl init --with-seed

För en avsiktligt tom databas:

cat > merchant-db.json <<'JSON'
{"schema_version": 2, "merchants": {}}
JSON

Importmotorn kompilerar inte

Kör testsviten från projektets rot:

bash parse-engine/tests/run

Kontrollera därefter aktuell Git-status och Python-miljö. Doctor testar syntax och importbarhet men ersätter inte regressionstesterna.

Budget finns men BUDGET_ENABLED inte är 1

Kontrollera:

ledgerctl config show

Om budgetlagret ska vara aktivt, kör normalt:

ledgerctl budget init

Undvik att endast sätta flaggan för hand utan att säkerställa all.journal och budgetfilerna.

auto.journal skiljer sig från envelopes.conf

ledgerctl budget regen-auto
ledgerctl budget doctor

Gör detta först efter att envelopes.conf är validerad. regen-auto ska vara den enda normala vägen att ändra auto.journal.

all.journal har fel include-layout

Den kanoniska layouten är i princip:

include finance.journal
include budget/auto.journal
include budget/funding.journal

Låt ledgerctl budget init --force regenerera genererade filer, men ta först en backup och granska kommandots utskrift. Fundinghistoriken ska bevaras.

funding.journal avvisas

Det är ett maskinprotokoll, inte bara fri hLedger-syntax. Återställ senaste korrekta version från Git, backup eller ett verifierat arkivsnapshot. Försök inte göra validatorn nöjd genom improviserad manuell redigering.

Importen stoppas av kuverttäckning

Kör den snabba kontrollen:

ledgerctl budget coverage --scope routes

För enstaka konton kan felrapportens exempel användas direkt med larin envelope update eller larin envelope add. För flera kategorier:

ledgerctl suggest-envelopes

Importen har stannat före CSV-konvertering och har inte ändrat journalerna. Kör coverage igen innan du startar om importen.

En verklig utgift saknar kuvert

ledgerctl budget coverage --scope all

För ett manuellt köp använder du C i Emacs och omklassificerar posten. Om merchantens standardkonto är fel uppdateras det separat med u i Emacs-administrationen. mirror är inte en reparation för otäckta utgifter.

Reservkuvertet saknas

Lägg till det genom Envelope API:t:

larin envelope add \
  --label "Att kategorisera" \
  --id uncategorized \
  --account expenses:uncategorized

Kör därefter ledgerctl budget coverage --scope all och larin doctor.

Budgetinvarianten är bruten

Kör:

ledgerctl budget check
ledgerctl budget status

Vanliga orsaker:

• överföring mellan egna konton,
• transaktion utan pending/cleared-status,
• utgiftskonto som inte mappas till något kuvert,
• överlappande kuvertregler,
• manuell ändring av genererade budgetfiler.

Vid en korrekt off-budget-överföring används budget mirror efter granskning.

Extra commodity rapporteras som varning

Budgeten är konfigurerad för exempelvis SEK men journalen innehåller även EUR. Det behöver inte vara ett fel, men kontrollera att beloppen inte blandas utan avsedd omräkning. Doctor accepterar varningar men redovisar dem.

Diagnostik i Larin CLI

När terminalklienten visar ett kontraktsfel:

1. kör samma operation med ett explicit --workspace,
2. kontrollera att rätt ledgerctl används,
3. kör motsvarande motorkommando med --format json,
4. granska schema_version, revision och felobjekt,
5. rätta backend eller arbetsyta innan konsumenten ändras.

Exempel:

larin --workspace ~/budget status --month 2026-07
ledgerctl budget status --month 2026-07 --format json

Larin CLI ska stoppa vid ett okänt eller felaktigt kontrakt i stället för att gissa. Det skyddar mot att en UI-bugg döljer ett verkligt dataproblem.

Larin låter dessutom ledgerctl workspace locate --format json hitta och validera arbetsytan. Efter det installeras ett runtime-skydd som blockerar direkt filåtkomst i arbetsytan och godtyckliga subprocesser. Ett sådant fel betyder att Larin-konsumenten försökt bryta JSON-gränsen och ska rättas i kod, inte kringgås i arbetsytan.

Diagnostik i Emacs

I budgetpanelen:

• ! öppnar Budget Doctor,
• D visar rå stdout, JSON och stderr,
• g kör kontrollen eller vyn igen.

När ett UI-fel är oklart, kopiera först det exakta kommandot från diagnostiken och kör det i terminalen från samma arbetsyta. Då skiljer du ett backendfel från ett renderings- eller Emacsproblem.

Testa efter en ändring

Grundkontroll:

ledgerctl doctor
bash parse-engine/tests/run

Budget, CLI och Emacs:

ledgerctl budget doctor
consumers/cli/run-tests.sh
consumers/emacs/run-tests.sh

# Samlad acceptans, inklusive containerdemo:
./full-test-run.sh

Kör också de körbara use casen när hLedger finns:

examples/envelope-budget-use-case/run-all.sh