spltty 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3bf97f1aff65eb471face732214bed57413de422a2e1bbae72d562931849db79
+  data.tar.gz: aaaf79b631b2972234bf56dbec3a9a2db7c37448addba068fdb84026cc04aa3c
+SHA512:
+  metadata.gz: f5d18872e7428a31860edc70d027e4e922ea71c29eb0a008890986cbe1f24cc1ba6449fb47f48683c0b56af1a71157bb92b27a1d11aac4544b26c64df765135c
+  data.tar.gz: 3000707668e2ca9604cd5f411ed973dbcac99067192b172783d1a32a19ba2c4ae29afc76ae7f0488c57019376954ccc5e780c99c253a8576739eab8a0b11c892

data/LICENSE

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

data/README.md

@@ -0,0 +1,351 @@
+# spltty
+
+Shared-expense tracking in **plain markdown ledgers**, with the arithmetic owned by
+a CLI instead of a spreadsheet — and a generated `CLAUDE.md` so an AI agent can do
+the transcription while `spltty` does the math.
+
+The data is markdown tables you can read, diff and grep. `spltty` owns the parts
+that must be exact: appending rows, resolving split groups, computing who owes
+whom, and recording settlements.
+
+```sh
+mkdir ~/finances && cd ~/finances
+spltty install                       # asks who splits what, scaffolds the workspace
+spltty add "Groceries" -v 84.20 -p Ana -m cash -r Both
+spltty totals
+```
+
+## Install
+
+**Homebrew**
+
+```sh
+brew install thiagodiniz/spltty/spltty
+# from a checkout, before the tap exists:
+brew install --build-from-source ./Formula/spltty.rb
+```
+
+**RubyGems** (needs Ruby >= 3.1)
+
+```sh
+gem install spltty
+```
+
+**Linux/Unix script** — installs the gem, falls back to a per-user install and
+tells you if the bin dir is not on your `PATH`:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/thiagodiniz/spltty/main/install.sh | sh
+```
+
+**From a checkout** (development). Ruby is pinned via [mise](https://mise.jdx.dev)
+(`.tool-versions` → ruby 3.4.2); `bin/spltty` selects it automatically, so the CLI
+runs from any directory without activating mise:
+
+```sh
+mise install && bundle install
+./bin/spltty help
+rake install            # build the gem and put `spltty` on your PATH
+```
+
+## Setting up a workspace
+
+`spltty install [PATH]` creates everything a tracker needs in a folder (the current
+directory by default):
+
+```
+.spltty/config.json     participants, split groups, payment methods, ledger cache
+accounts/               one ledger per account being tracked
+sources/INDEX.md        tracker for raw statements/receipts
+CLAUDE.md               generated workflow guide for the AI agent
+.claude/skills/ingest/  the /ingest skill for raw inputs
+```
+
+It asks for the participants (at least one is required), a shared split group, the
+ledgers to create, optional payment-method defaults, and whether to `git init`.
+Every step but the participants can be skipped — pressing enter through it yields
+one monthly ledger named `expenses`.
+
+Non-interactively:
+
+```sh
+spltty install ~/finances -y -P Ana,Bruno -s Ana:60,Bruno:40 -l HOME,TRIP --no-git
+```
+
+| Flag | Meaning |
+|------|---------|
+| `-P, --participants` | comma-separated names (required) |
+| `-g, --group` / `-s, --split` | shared group name and `NAME:PCT,NAME:PCT` split (default: `Both`, even) |
+| `-l, --ledgers` | comma-separated ledger names (default: `expenses`) |
+| `--single` | create ledgers as single files instead of per-month |
+| `--no-git` / `--git` | skip or force `git init` |
+| `-f, --force` | overwrite an existing workspace config |
+
+Every command afterwards finds the workspace by walking up from the current
+directory for `.spltty/config.json` — like git. Override with `--config` /
+`SPLTTY_CONFIG`.
+
+## Usage
+
+```sh
+spltty install [PATH]    # scaffold a new workspace (accounts, sources, CLAUDE.md)
+spltty add [options]     # (alias: a)  append an entry (flags + interactive confirm)
+spltty list              # (alias: ls) list discovered ledgers (also runs the notes<->config sync)
+spltty sync              # sync ledger config between notes-file headers and config.json
+spltty totals [LEDGER..] # per-person totals & settlement per ledger (--combined to merge)
+spltty settle [LEDGER..] # record a settlement (one ledger = cash; several/none = offsets + optional cash)
+spltty groups            # list split groups (global + per-ledger)
+spltty groups add NAME   # define/update a split group (in a ledger header, or --global)
+spltty groups rm NAME    # remove a split group
+spltty methods           # list configured payment methods
+spltty methods add NAME  # add/update a payment method in the config
+spltty help              # show every command with its arguments/options
+spltty add --help        # options for a single command
+```
+
+Add or update a payment method without hand-editing the config:
+
+```sh
+spltty methods add "Visa 1234" -s visa-1234 -p Ana -r Both -b 10
+#   -s slug   -p paid-by   -r responsible   -b bill-day (1-31 or "last")
+# Only the properties you pass are set; existing ones are preserved.
+```
+
+`add` takes the **title as a positional argument**; everything else is a flag
+with a short alias. It prompts for any required field you omit, applies
+payment-method defaults, shows the resolved row, and asks before writing. Pass
+`--yes`/`-y` to skip prompts (required fields must then be supplied).
+
+**Unknown ledger names are treated as typos, not new accounts.** `-l CAS` when
+you meant `CASA` would otherwise scaffold a junk ledger that then shows up in
+every totals run. Interactively you get a menu — create it, or pick the one you
+meant:
+
+```
+$ spltty add "Coffee" -l CAS -v 12.90
+Ledger "CAS" is not known yet.
+  1) Create a new ledger "CAS"
+  2) HOME
+  3) TRIP
+Which ledger? [1]: 2        # or type HOME
+```
+
+With `--yes` there is nobody to ask, so it errors and lists the known ledgers.
+Creating a ledger from a script needs `--create-ledger`:
+
+```sh
+spltty add "Mooring" -l BOAT -v 40 -p Ana -m cash -y --create-ledger
+```
+
+### Examples
+
+```sh
+# Positional title + short flags:
+spltty add "Leite 1L" -l HOME -v 14.20 -p Ana -m cash
+
+# Card entry — Paid By/Responsible/Date default from the card's config:
+spltty add "Extra" -l HOME -v 66.69 -m "Visa 1234" -y
+
+# Multi-currency entry:
+spltty add "Metro" -l TRIP -o 3.75 -c CAD -v 14.20 -p Bruno -m Wise -y
+
+# Fully interactive (prompts for what's missing):
+spltty add
+```
+
+### Arguments & options
+
+| Flag             | Short | Meaning                                                     |
+|------------------|-------|-------------------------------------------------------------|
+| `<title>`        |       | Expense description — **positional** (first bare argument)  |
+| `--ledger`       | `-l`  | Ledger name (default: `default_ledger` in config; case-insensitive) |
+| `--date`         | `-d`  | `YYYY-MM-DD` (default: today, or the card's bill day)       |
+| `--value`        | `-v`  | Amount in R$ (`12.5`, `12,50`, `1.234,56` all accepted)     |
+| `--paid-by`      | `-p`  | Who fronted the money                                        |
+| `--method`       | `-m`  | Payment instrument; matches a configured payment method     |
+| `--responsible`  | `-r`  | Who bears the cost — a split-group name (`Both`, …) or a person (`Ana`) |
+| `--paid-responsible` | `-pr` | Shortcut: sets **both** Paid By and Responsible (e.g. `-pr Ana`); `-p`/`-r` override |
+| `--source`       | `-s`  | Provenance (default `text`)                                  |
+| `--orig-value`   | `-o`  | Original amount — multi-currency schema only                      |
+| `--currency`     | `-c`  | Original currency — multi-currency schema only                    |
+| `--create-ledger`|       | Create `--ledger` when it doesn't exist (required with `--yes`) |
+| `--yes`          | `-y`  | Non-interactive; no prompts or confirmation                 |
+| `--config`       | `-C`  | Config path (default `.spltty/config.json`; or `SPLTTY_CONFIG`) |
+| `--accounts-dir` | `-A`  | Override accounts dir (or `SPLTTY_ACCOUNTS_DIR`)            |
+
+## Config (`.spltty/config.json`)
+
+Only `payment_methods` is authored by hand. The `ledgers` block is **optional and
+auto-maintained**: on every run the CLI scans `accounts/` and records what it
+finds. Discovery treats as a ledger:
+
+- a root file named `<NAME>.ledger.md` (single-file ledger), or
+- a subfolder containing `YYYY-MM.md` files (monthly ledger, e.g. `HOME`).
+
+Everything else is ignored. Structural fields (`type`/`file`/`dir`/`schema`) are
+set automatically; `title`, `default_responsible`, `default_currency`, and
+`notes` are user overrides that discovery preserves. See `config.example.json`.
+
+### Notes-header sync
+
+The three tunable fields — `title`, `default_responsible`, `default_currency` —
+also live in each ledger's `*.notes.md` file, in a YAML frontmatter header under a
+`spltty:` key, so the config sits next to the rules it documents:
+
+```markdown
+---
+spltty:
+  default_responsible: Both
+  groups:
+    Both: {Ana: 65, Bruno: 35}
+---
+# WEDDING — Wedding — Notes
+…
+```
+
+`spltty sync` (and `spltty list`) keep the header and `config.json` in agreement.
+**The notes file is the source of truth.** Each `ledgers` entry carries a
+`synced_at` timestamp; the direction is decided by comparing it to the notes
+file's filesystem mtime:
+
+- **notes file edited more recently** (or never synced) → the header wins and
+  updates config.
+- **config newer, or the header is missing the field** → config is copied into
+  the header.
+
+Every field is optional: only keys present on the winning side are merged, an
+absent key is never cleared, and a ledger with no tunable config gets no
+`spltty:` block. Any other frontmatter keys you add are left untouched. Don't
+hand-edit `synced_at` — the sync manages it (and stamps it to the post-write
+mtime so a write never ping-pongs). `spltty add` does **not** run this sync.
+
+### Split groups
+
+A **split group** is a named split — `name → {participant: percentage}` — such as
+`Both → {Ana: 70, Bruno: 30}` or `Presente → {Ana: 100}`. Percentages are
+integers and should sum to 100 (a mismatch only warns).
+
+Each ledger's own groups live in its notes header, under `spltty.groups`, and are
+synced into `config.json` (as `ledgers.<NAME>.groups`) by the same
+notes↔config sync above:
+
+```yaml
+---
+spltty:
+  default_responsible: Both
+  groups:
+    Both: {Ana: 70, Bruno: 30}
+    Presente: {Ana: 100}
+---
+# HOME — … — Notes
+```
+
+When the **identical** definition (same name + participants + percentages) appears
+in **two or more** ledgers, it is promoted to a shared **global** group at the top
+level of `config.json` (`"groups": { … }`). Global groups are config-only — they
+are never written back into any header, and the sync only manages ledger-specific
+groups. A ledger group shadows a global group of the same name (e.g. a global
+`Both` 50/50 vs HOME's own `Both` 70/30).
+
+Manage groups without hand-editing YAML:
+
+```sh
+spltty groups                                   # list global + per-ledger groups
+spltty groups add Both -s Ana:70,Bruno:30 -l HOME   # write into HOME's header
+spltty groups add Both -s Ana:50,Bruno:50 --global  # write a global group
+spltty groups rm Both -l HOME                   # remove from a ledger (or --global)
+```
+
+**Consumed by `spltty totals`:** when computing settlement, each row's
+`Responsible` value is resolved against these groups (ledger header groups first,
+then global). A match splits the cost by the group's percentages; anything
+unmatched is treated as a person (100%). There is no `Both (NN/NN T/C)`
+string-parsing anymore — the split lives in the group. (`spltty add` still writes
+the `Responsible` cell verbatim; it does not yet validate it against known groups.)
+
+## Totals & settlement
+
+`spltty totals` compiles per-person **Paid**, **Owes**, **Net = Paid − Owes**, a
+spending breakdown, and a greedy **Settlement** (who pays whom):
+
+```sh
+spltty totals                 # one report per ledger (reference ledgers flagged)
+spltty totals HOME TRIP   # only these ledgers
+spltty totals --combined      # merge all non-reference ledgers into ONE settlement
+```
+
+A monthly ledger (HOME) merges all its `YYYY-MM.md` files into one per-ledger
+report. Splits are resolved via split groups (above).
+
+### Reference ledgers
+
+A ledger that intentionally **duplicates** rows already recorded in another one — a
+project tracker mirroring shared spend, so the project's cost is visible in one
+place — must never be summed with the primaries; that double-counts. Mark it in its
+notes header:
+
+```yaml
+---
+spltty:
+  reference: true
+---
+```
+
+Reference ledgers are flagged in per-ledger `totals`, **excluded** from `--combined`
+(and listed as skipped), and refused in a cross-ledger `settle` — settle them on
+their own in cash mode.
+
+Each payment method may define an optional **`slug`** — a short alias you can pass
+to `-m` instead of the full name. Both are matched case-insensitively, and the
+row always stores the full canonical name:
+
+```json
+"Visa 5678": { "slug": "visa-5678", "paid_by": "Bruno", "responsible": "Bruno", "bill_day": "last" }
+```
+
+Then `spltty add "Coffee" -l HOME -v 12 -m visa-5678` fills Paid By / Responsible /
+Date from that card. If a method has no default for a field, interactive mode
+prompts for it (and `--yes` errors). `spltty methods` lists every method with its
+slug.
+
+## Settling up
+
+`spltty settle` **records** a settlement (the `Settlement:` line in `totals` is
+only a suggestion). A settlement is written as a normal table row — a transfer
+where **Paid By = debtor** and **Responsible = creditor** — so it flows through
+the totals math and offsets the debt exactly. No table is ever hand-edited.
+
+```sh
+spltty settle HOME                 # cash-settle HOME in full (Pix row in the current month file)
+spltty settle TRIP -v 500 -y   # partial cash settle, non-interactive
+spltty settle                      # global offset mode: zero opposite-direction ledgers, rest stays open
+spltty settle -v 2000              # global: offsets + R$ 2000 cash, smallest ledger first
+spltty settle HOME WEDDING       # offset mode restricted to these two ledgers
+```
+
+Two modes, chosen by how many ledgers you pass:
+
+- **One ledger — cash mode.** A real payment for that ledger's outstanding
+  balance (or `-v` part of it, titled `(partial)`), never touching other
+  ledgers. Payment method defaults to `Pix` (`-m` overrides).
+- **None/several ledgers — offset mode.** None = all non-reference ledgers.
+  Ledgers whose debt points *opposite* to the combined direction are zeroed with
+  mirrored rows (payment method `offset` — no real money moves): e.g. HOME has
+  Bruno owing Ana 7000 and WEDDING has Ana owing Bruno 5000 ⇒
+  WEDDING gets an offset row Ana → Bruno 5000, HOME the mirror
+  Bruno → Ana 5000, leaving 2000 open in HOME. Without `-v` that is all
+  that happens — the remainder **stays open** (with nothing to offset, it just
+  prints the outstanding and writes nothing). With `-v X`, X is then recorded
+  as a cash payment against the remainder. Offsets and cash are both allocated
+  **smallest-outstanding ledger first**.
+
+Rows are stamped with today's date (`-d` overrides; a card method's bill day is
+ignored) and `Source = settle` (`-s` overrides). The plan is previewed and
+confirmed before writing (`-y` skips). Ledgers marked `reference: true` never join
+offset mode — settle them on their own in cash mode.
+
+## Tests
+
+```sh
+bundle exec rake test
+```

data/config.example.json

@@ -0,0 +1,33 @@
+{
+  "//": "Reference for .spltty/config.json — normally written by `spltty install`, not by hand. Only payment_methods really needs hand-authoring.",
+
+  "accounts_dir": "../accounts",
+  "//accounts_dir": "Ledger root, resolved relative to this config file. Override at runtime with --accounts-dir or SPLTTY_ACCOUNTS_DIR.",
+
+  "default_ledger": "expenses",
+  "date_format": "%Y-%m-%d",
+
+  "participants": ["Ana", "Bruno"],
+  "//participants": "Everyone who can appear in Paid By / Responsible. Recorded by `spltty install` and used to render the workspace CLAUDE.md; the split groups below decide how a cost is divided.",
+
+  "payment_methods": {
+    "//": "name -> defaults applied when --method matches (by full name or slug, case-insensitive). bill_day is the day the bill is paid; it fills the Date column ('last' = last day of month). slug is an optional shortcut you can pass to -m (e.g. -m visa-1234).",
+    "Visa 1234": { "slug": "visa-1234", "paid_by": "Ana", "responsible": "Both", "bill_day": "last" },
+    "Visa 5678": { "slug": "visa-5678", "paid_by": "Bruno", "responsible": "Both", "bill_day": 21 }
+  },
+
+  "ledgers": {
+    "//": "OPTIONAL and auto-maintained. Discovery scans accounts/ on every run and writes this block. type/file/dir/schema are set automatically; title, default_responsible, default_currency, reference, and notes are user overrides that are preserved.",
+    "//sync": "The tunable fields (title, default_responsible, default_currency, reference, groups) also live in each ledger's *.notes.md YAML header under `spltty:`, and are two-way synced by `spltty sync` (and by `spltty list`). synced_at is a per-ledger timestamp written by the sync: if the notes file's mtime is newer, the header wins and updates config; otherwise config is copied into the header. The notes file has precedence. Do not hand-edit synced_at.",
+    "//groups": "ledgers.<NAME>.groups holds that ledger's split groups (name -> {participant: pct}), mirrored from the header's spltty.groups. Manage with `spltty groups add NAME -s Ana:70,Bruno:30 -l <NAME>`.",
+    "//reference": "reference: true marks a ledger whose rows duplicate another ledger's. It is flagged in `totals`, excluded from --combined, and refused in a cross-ledger `settle`.",
+    "expenses": { "type": "monthly", "dir": "expenses", "schema": "standard", "notes": "notes.md", "default_responsible": "Both", "groups": { "Both": { "Ana": 70, "Bruno": 30 } }, "synced_at": "2026-07-05T12:00:00Z" },
+    "TRIP": { "type": "single", "file": "TRIP.ledger.md", "schema": "montreal", "notes": "TRIP.notes.md", "default_currency": "CAD", "synced_at": "2026-07-05T12:00:00Z" },
+    "RENOVATION": { "type": "single", "file": "RENOVATION.ledger.md", "schema": "standard", "notes": "RENOVATION.notes.md", "reference": true, "synced_at": "2026-07-05T12:00:00Z" }
+  },
+
+  "groups": {
+    "//": "GLOBAL split groups, shared across ledgers. Auto-populated when the identical definition (name + participants + percentages) appears in >=2 ledger headers; also editable via `spltty groups add NAME -s ... --global`. Never written back into any header. A ledger's own group shadows a global one of the same name.",
+    "Both": { "Ana": 50, "Bruno": 50 }
+  }
+}

data/exe/spltty

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Gem entrypoint. Also works straight from a checkout (`exe/spltty …`) by
+# putting the sibling lib/ on the load path when it exists.
+lib = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(lib) if File.directory?(lib) && !$LOAD_PATH.include?(lib)
+
+require "spltty_cli"
+
+SplttyCLI.run(ARGV)