billwright 0.2.0__py3-none-any.whl

billwright/AGENTS.md

@@ -0,0 +1,344 @@
+# AGENTS.md
+
+Instructions for a coding agent working on billwright: invoices and yearly
+statements. Read this before touching anything. This is the single source of
+truth for agent rules in this repo; `CLAUDE.md` and `GEMINI.md` only point here.
+
+Everything here is **client-facing or tax-facing**. A broken invoice is
+discovered by a client who is being asked for money; a broken statement is
+discovered by the Steueramt. Bias hard towards verifying rather than assuming.
+
+Humans: see [README.md](README.md).
+
+---
+
+## If you are setting up a new company, start here
+
+Someone has cloned this and wants to bill with it. **Do the setup for them** —
+they should not have to install anything by hand before talking to you.
+
+**Step 1: get the environment working.** Check what is missing and install it,
+asking before you run anything that needs `sudo` or touches their system:
+
+```bash
+uv --version                                   # https://astral.sh/uv if absent
+python3 -c "import ctypes.util as u; print(u.find_library('gobject-2.0'))"
+```
+
+WeasyPrint binds Pango and Cairo through cffi, and a missing one produces
+`cannot load library 'libgobject-2.0-0'` rather than anything about fonts:
+
+| Platform | Command |
+|---|---|
+| macOS | `brew install pango` (and `poppler`, to turn a PDF into a PNG you can look at) |
+| Debian/Ubuntu | `sudo apt install libpango-1.0-0 libpangoft2-1.0-0 poppler-utils` |
+| Fedora | `sudo dnf install pango poppler-utils` |
+
+**Step 2: prove the renderer works before touching their data.** This separates
+a missing system library from a mistake you are about to make:
+
+```bash
+make setup                     # uv sync
+make bill BILL=RE-26001        # renders the bundled example into out/
+```
+
+**Step 3: give them their own profile.** Either way, `data/` is gitignored and
+`example/` stays exactly as it is:
+
+```bash
+uv run billwright init-profile --into data    # empty form, every field marked
+                                              # required or optional
+```
+
+or, if you would rather start from a filled-in example and edit it down:
+
+```bash
+cp -r example data
+rm -rf data/bills/* data/years/*   # their profile, not the sample's numbers
+```
+
+**Step 4: take whatever they have and write the TOML yourself.**
+
+They do not know this file format and should never be asked to learn it. Ask
+what they already have and read it:
+
+- **an invoice they sent before** — PDF, Word, Pages, a photo of a printout.
+  This is the best source: it has the issuer block, the footer, the payment
+  details and a real line item, all in one place.
+- **a letterhead, an email signature, a business card, their website**
+- **a bank statement or e-banking screenshot**, for the IBAN and the bank name
+- **nothing at all** — then just ask, in plain questions, one topic at a time.
+
+Read the source, extract the fields, and write the files. Where a document is
+ambiguous, ask about that one field rather than guessing the lot.
+
+| Where it usually is on an old invoice | Goes to |
+|---|---|
+| Sender block, top left or in the letterhead | `company.toml`: `name`, `person`, `address` |
+| Footer: email, website, CHE number, legal form | `company.toml`: `email`, `website`, `uid`, `legal_form` |
+| Payment slip or "Zahlbar an" | `company.toml`: `iban`, `bank` |
+| "MwSt/TVA" line, or its absence | `company.toml`: `vat_registered`, `vat_rate` |
+| "Zahlbar innert 30 Tagen" | `company.toml`: `default_terms_days` |
+| Recipient block | `clients/<key>.toml` |
+| Line items and their unit prices | `rates.toml` service categories |
+| Logo colours and typeface | `brand.toml`, or leave the neutral default |
+
+**Never invent a financial or legal value, and never trust your own reading of
+one.** An invented or misread IBAN sends money to a stranger; an invented VAT
+rate under-invoices and the difference is still owed.
+
+- **Read every extracted financial value back to them for confirmation** — the
+  IBAN in full, the VAT rate, the rates. OCR and PDF text layers transpose
+  digits, and an invoice is the last place that gets noticed.
+- If they do not know, stop and let them find out. `vat_registered` being absent
+  means *unknown*, not `false`.
+- `billwright doctor` checks the IBAN's mod-97 checksum, so a transposed digit
+  usually fails there — but a checksum-valid wrong IBAN exists, which is why
+  the human confirms it too.
+
+Then:
+
+```bash
+uv run billwright doctor       # is the profile complete and the IBAN valid?
+uv run billwright check        # numbering, gaps, empty bills
+make new CLIENT=<their-key>    # scaffolds the next number
+# fill in the line items, then:
+make bill BILL=<number>        # renders into out/ — LOOK AT IT (rule 6 below)
+make scan                      # nothing private reached a tracked file
+```
+
+Tell them plainly, once, before their first real invoice: **scan the QR code
+with a banking app.** The payload is unit-tested; a live scan is the only thing
+that proves the money would arrive.
+
+---
+
+## First, orient
+
+```bash
+make setup                     # uv sync
+make bill BILL=RE-26001        # render one bill into out/
+make statement YEAR=2026       # yearly accounts + figures sheet into out/
+make scan                      # fail if a tracked file holds a private value
+make check                     # lint + scan + tests + numbering checks (what CI runs)
+uv run billwright --help
+```
+
+The entry point is `billwright.main:main`, exposed as `billwright` and as
+`python -m billwright`.
+
+There is a second, optional entry point: `billwright.mcp_server:main`, exposed
+as `billwright-mcp` and installed only with the `mcp` extra. **It is not the way
+in, and it is not a place to put behaviour.** It serves this file verbatim as a
+resource and calls the same loaders the CLI calls; anything it did that the CLI
+does not is by definition drift. If you are about to add logic there, add it to
+the engine and let both call it.
+
+**How the repo is split** — this is the thing to understand first:
+
+- `src/billwright/` is a **generic engine**. It contains no company name, address,
+  IBAN, colour, font or wordmark.
+- `data/` is the **profile**: all company facts. Gitignored. `example/` is a
+  fictional profile that is committed, and what the tests run against.
+- `src/billwright/assets/fonts/` holds the vendored typeface. It is inside the
+  package so that an installed copy renders correctly with no flags; a face the
+  renderer cannot find is now an error rather than a substitution.
+- `assets/reference/` (gitignored) is for source documents from clients.
+- `skills/` documents how to rebuild the system, split generic vs. specific, so
+  it can be reused for another company. Read
+  [`skills/README.md`](skills/README.md) before making structural changes.
+
+---
+
+## Non-negotiables
+
+**1. Never put a company value in `src/`.** No name, address, IBAN, hex colour,
+font choice or wordmark string. If you need one, it belongs in `data/`. A value
+appearing in `src/` means the engine/profile seam has leaked — fix the seam
+rather than special-casing.
+
+`make scan` enforces this across every **tracked** file, not just `src/`: it
+matches the active profile's own values, anything shaped like an IBAN, a Swiss
+UID, an email address or a phone number, and the literals in the gitignored
+`notes/denylist.txt`. It runs inside `make check`. It never prints what it
+matched — a guard that echoes the value into a log has moved the leak rather
+than caught it, so findings name the file and line and you look yourself.
+
+**2. Totals are computed, never stored.** No data file may carry a `total`
+field. This is not a style preference: the Word original this replaces states
+a total its own lines did not sum to, and computing the total is
+what makes that impossible. `tests/test_load.py` pins it.
+
+**3. Money is `Decimal`.** Never `float`. Format Swiss: `1’234.50 CHF`, with
+U+2019 for thousands and a period for decimals. `’` and `'` look alike and only
+one is correct — `tests/test_money.py` asserts on it.
+
+**4. Swiss German uses `ss`, never `ß`.** `Grüssen`, `vereinbarungsgemäss`. The
+Word originals got this wrong; do not reintroduce it.
+
+**5. Never invent a colour, font or spacing value.** Everything comes from
+`data/brand.toml` (colours, wordmark) and the scale in
+`src/billwright/styles/tokens.css` (type, spacing). The palette mirrors
+the profile's `brand.toml`. If something looks like it
+needs a new value, it almost certainly needs an existing one.
+
+**But the accent is an accent.** One 1 pt rule under the title is the entire
+brand presence on an invoice. Filling boxes with the tint is how this gets
+wrecked.
+
+**6. Render it and actually look at it.** This is the rule that matters most.
+Structural checks pass happily while a payment part sits on top of the totals.
+
+```bash
+make bill BILL=RE-26001
+cd out && pdftoppm -png -r 100 *RE-26001.pdf page   # then open page-1.png
+```
+
+If you cannot view images in your environment, **say so explicitly in your
+report** and describe the check as unverified. Never imply visual confirmation
+you did not perform.
+
+**7. Never edit a PDF, and never edit an archived one at all.** The archived PDF
+is the record of what a client was sent — `OR Art. 958f` requires keeping it ten
+years. Change the data and re-render. `tests/test_reproducible.py` proves a
+re-render is byte-identical.
+
+**8. The invoice body has ~165 mm.** A4 minus the 105 mm Swiss QR payment part
+and the top margin. Every spacing decision lives under that budget. When a bill
+overflows, measure before adjusting:
+
+```python
+# see skills/swiss-billing-generator/references/weasyprint.md
+box.position_y / 96 * 25.4   # mm
+```
+
+**9. Every change to a *tracked* file gets a [CHANGELOG.md](CHANGELOG.md)
+entry** under an `[Unreleased]` heading, added above the current release.
+
+**Using the tool is not a change to it.** Creating a profile under `data/`,
+adding a client, issuing a bill, closing a year — none of these get a changelog
+entry, and none of them get a commit. `data/` is gitignored: nothing there is
+part of this repository, and a public changelog saying that the maintainer set
+up a profile tells its readers nothing while inviting a detail that should not
+be public. The changelog is written for someone who installed this software,
+about the software.
+
+An earlier version of this rule said "data changes and new bills included",
+which was correct when this repository *was* one company's billing system.
+It is now a generic tool with the company outside it. If you find yourself
+writing a changelog line about a bill, you are recording your own bookkeeping
+in someone else's release notes.
+
+**The changelog records what changed in this repository. Nothing else.** It must
+never carry:
+
+- **Client or commercial matters** — a disputed amount, an under- or
+  over-billing, who owes what, why an invoice was reissued.
+- **Open decisions** — anything phrased as "whether to X is still open". A
+  changelog is a record of what happened, not a place to park a question.
+- **Specific money amounts, client names, or account details.** A rule of thumb:
+  if the line would embarrass you in front of the client it names, it is in the
+  wrong file. Describe the *change* ("totals are now computed from line items"),
+  never the *incident* that motivated it.
+
+Those things have homes already, and the changelog is not a shortcut to them:
+
+| Kind of thing | Where it goes |
+|---|---|
+| An open decision needing Daniel | `TODOS.md` (untracked) |
+| A durable fact about the business you bill for | the private company profile skill (gitignored) |
+| A defect that must never recur | a regression test, with a docstring saying why |
+| A fact about one bill | a comment in that bill's TOML |
+
+Before adding a changelog line, ask whether it describes a change to code, data
+or documentation. If it describes a business event, it belongs somewhere above.
+
+**10. No co-authored commits.** No `Co-Authored-By` trailer, no tool attribution
+in commit messages.
+
+---
+
+## What this tool does not do
+
+Stated because the obvious fix for a storage problem is the wrong one here, and
+the next agent to read "the archive has to outlive a laptop" will otherwise
+propose it in good faith.
+
+**No storage backend.** No Drive, no S3, no GCS, no upload of any kind. "It
+reads and writes local files and talks to nothing" is a property people rely on,
+and it is most of why this tool is allowed near a company's bank details at all.
+Making an archive survive a disk is a sync problem, solved outside this tool.
+
+**Nothing that sends a document anywhere.** No mail, no client portal, no
+webhook. An invoice leaving the company is a human decision, and a tool that
+could send one makes that unenforceable.
+
+If a request seems to need either, the answer is a path on disk and a sentence
+explaining who copies it where.
+
+---
+
+## Things that will bite you
+
+**WeasyPrint on macOS.** It binds Pango/GLib/Cairo through cffi and Homebrew
+puts them where dyld does not look. `billwright` repairs this itself by re-execing
+(`src/billwright/native.py`); the `Makefile` exports the variable for pytest.
+Running `uv run python` directly needs it set by hand:
+
+```bash
+DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib uv run python …
+```
+
+**`@page :last` does not exist.** Placing the payment part on the final page is
+a two-pass render: count the body's pages, choose inline or a separate sheet,
+then verify the choice did not itself cause an overflow. `render.py` does this;
+do not simplify it away.
+
+**`position: fixed` repeats on every page.** It is only safe for the
+single-page case, which is why the fallback exists.
+
+**oklch() is not reliable in WeasyPrint.** Tokens are hex, with the oklch source
+in a comment in `data/brand.toml`.
+
+**Fonts are vendored static weights**, embedded as data URIs. Do not switch to a
+variable font or a system install — a substituted face on a client document is
+not something you find out about in time.
+
+---
+
+## Adding things
+
+**A new bill**: `make new CLIENT=<client-key>`, edit the items, `make bill BILL=…`,
+look at it, then `make archive BILL=…`.
+
+**A new client**: a TOML in `data/clients/`. Write the salutation out in full.
+
+**A new language**: add the block to `src/billwright/i18n.py`. Both `de` and `en`
+must stay complete — `StrictUndefined` turns a missing key into a render error,
+which is the intent.
+
+**A different look for one company**: not a change to `src/`. Put CSS in
+`<profile>/styles/` (`overrides.css` for everything, `bill.css` or
+`statement.css` for one document) — it is appended after the packaged rules — or
+replace a template outright by putting a file of the same name in
+`<profile>/templates/`. If you are editing `src/billwright/styles/` to make one
+company's invoice look right, the seam has leaked.
+
+**A new document type**: a template in `templates/`, a stylesheet in `styles/`, a
+subcommand in `main.py`. Reuse `tokens.css` and `print.css`.
+
+**A new command**: a subcommand in `main.py`, and — if an agent without a shell
+would need it — a tool in `mcp_server.py` that calls the same function. Put the
+logic in a module both can import, never in either entry point. `audit.py` and
+`paths.py` exist because that rule was applied to `check` and to filenames.
+
+---
+
+## Definition of done
+
+- [ ] `make check` passes
+- [ ] The document was rendered **and looked at**
+- [ ] No company value landed in `src/`
+- [ ] No hardcoded colour or spacing outside the token files
+- [ ] CHANGELOG entry added
+- [ ] Anything unverified is stated as unverified

billwright/__init__.py

@@ -0,0 +1,12 @@
+"""Bills and yearly statements, generated from data."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("billwright")
+except PackageNotFoundError:  # pragma: no cover - a source tree with nothing installed
+    # Not a silent default: it is a version string that cannot be mistaken for
+    # a release, which is what an un-installed source tree actually is.
+    __version__ = "0+unknown"
+
+__all__ = ["__version__"]

billwright/__main__.py

@@ -0,0 +1,4 @@
+from .main import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

billwright/assets/fonts/OFL.txt

@@ -0,0 +1,92 @@
+Copyright 2016 The Inter Project Authors (https://github.com/rsms/inter)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font
+creation efforts of academic and linguistic communities, and to
+provide a free and open framework in which fonts may be shared and
+improved in partnership with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply to
+any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software
+components as distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to,
+deleting, or substituting -- in part or in whole -- any of the
+components of the Original Version, by changing formats or by porting
+the Font Software to a new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed,
+modify, redistribute, and sell modified and unmodified copies of the
+Font Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components, in
+Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the
+corresponding Copyright Holder. This restriction only applies to the
+primary font name as presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created using
+the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

billwright/audit.py

@@ -0,0 +1,101 @@
+"""Whether a profile's bills hold together as a numbered series.
+
+An auditor reading ``RE-26001, RE-26003`` asks what became of ``RE-26002``, and
+"nothing" is not an answer anyone accepts after the fact. This makes the
+question answerable before it is asked.
+
+Kept out of ``main.py`` because the command line is no longer the only caller:
+the MCP server reports the same audit, and two implementations of "is the
+numbering sound" would eventually disagree about a real invoice.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .load import bill_paths, load_bills, load_expenses
+from .numbering import find_duplicates, find_gaps
+
+
+@dataclass(frozen=True)
+class YearAudit:
+    """One year of the series.
+
+    ``migrated`` counts numbers issued before this tool existed — Word files in
+    a folder somewhere. They are not gaps, but they must be *declared* in
+    ``years/<year>.toml`` so that a genuinely missing number can never hide
+    among them.
+    """
+
+    year: int
+    gaps: tuple[str, ...]
+    migrated: int
+
+
+@dataclass(frozen=True)
+class Audit:
+    """What one profile's bills look like read end to end."""
+
+    bills: int
+    duplicates: tuple[str, ...]
+    years: tuple[YearAudit, ...]
+    empty: tuple[str, ...]
+    nonpositive: tuple[str, ...]
+
+    @property
+    def ok(self) -> bool:
+        return not self.problems
+
+    @property
+    def problems(self) -> tuple[str, ...]:
+        """Every finding, as lines. Empty means the series is sound."""
+        lines = []
+        if self.duplicates:
+            lines.append(f"duplicate bill numbers: {', '.join(self.duplicates)}")
+        for year in self.years:
+            if year.gaps:
+                lines.append(f"{year.year}: gaps in the numbering: {', '.join(year.gaps)}")
+        lines.extend(f"{number}: no line items" for number in self.empty)
+        lines.extend(f"{number}: net amount is not positive" for number in self.nonpositive)
+        return tuple(lines)
+
+    @property
+    def notes(self) -> tuple[str, ...]:
+        """True but not wrong — stated so the numbers below them add up."""
+        return tuple(
+            f"{year.year}: {year.migrated} bill(s) issued before migration, not in this repo"
+            for year in self.years
+            if year.migrated
+        )
+
+
+def audit(profile: Path) -> Audit:
+    """Read every bill in ``profile`` and report what an auditor would ask about."""
+    numbers = [path.stem for path in bill_paths(profile)]
+
+    years = []
+    for year in sorted({int(path.parent.name) for path in bill_paths(profile)}):
+        _, year_data = load_expenses(profile, year)
+        elsewhere = set(year_data.get("bills_issued_elsewhere", []))
+        gaps = [
+            str(gap)
+            for gap in find_gaps(numbers + sorted(elsewhere), year)
+            if str(gap) not in elsewhere
+        ]
+        years.append(YearAudit(year=year, gaps=tuple(gaps), migrated=len(elsewhere)))
+
+    bills = load_bills(profile)
+    # An empty bill is reported as empty and not *also* as non-positive: one
+    # fault, one line. `nonpositive` is for a bill that has lines and still does
+    # not come to anything, which is a different mistake.
+    empty = tuple(bill.number for bill in bills if not bill.items)
+    nonpositive = tuple(bill.number for bill in bills if bill.items and bill.net <= 0)
+
+    return Audit(
+        bills=len(numbers),
+        duplicates=tuple(find_duplicates(numbers)),
+        years=tuple(years),
+        empty=empty,
+        nonpositive=nonpositive,
+    )