sumac-home 0.1.0__tar.gz

sumac_home-0.1.0/.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "f=$(cat | python3 -c 'import json,sys; print(json.load(sys.stdin).get(\"tool_input\",{}).get(\"file_path\",\"\"))'); case \"$f\" in *.py) uv run ruff format \"$f\" ;; esac"
+          }
+        ]
+      }
+    ]
+  }
+}

sumac_home-0.1.0/.gitattributes

@@ -0,0 +1 @@
+data/**/*.jsonl merge=union

sumac_home-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - run: uv sync --all-groups
+      - run: uv run ruff format --check .
+      - run: uv run ruff check .
+      - run: uv run ty check
+      - run: uv run pytest

sumac_home-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/

sumac_home-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

sumac_home-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.5
+Name: sumac-home
+Version: 0.1.0
+Summary: Home grocery inventory app
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2
+Requires-Dist: rich>=13
+Requires-Dist: sealedlog>=0.1.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# sumac
+
+**🍋 sumac: home grocery inventory app**
+
+Encrypted-at-rest grocery inventory for a household sharing one git repo and one passphrase.
+Locations, products, and quantities are never visible to someone holding the repo without the
+passphrase — not even in file or directory names. See `docs/FORMAT.md` for the on-disk format
+and threat model, and `docs/LAYOUT.md` for what's read-only vs mutable.
+
+## Install
+
+Published on PyPI as `sumac-home` (`sumac` was taken); the command is still `sumac`.
+
+```sh
+uv tool install sumac-home     # or: pip install sumac-home
+```
+
+For development (this checkout):
+
+```sh
+uv sync
+```
+
+Depends on [`sealedlog`](https://pypi.org/project/sealedlog/) (the encrypted append-only log
+primitive) from PyPI.
+
+## Passphrase
+
+Set `SUMAC_PASSPHRASE`, or sumac will prompt interactively. The passphrase is shared by every
+user of the household's vault.
+
+## Usage
+
+```sh
+sumac init                                              # once, creates data/
+sumac config add-location "Fridge" --id fridge
+sumac config add-location "Pantry" --id pantry
+sumac config show
+
+sumac add purchase milk 2 l --to fridge
+sumac add consumption milk 1 l --from fridge
+sumac add movement rice 1 kg --from pantry --to fridge
+sumac snapshot fridge "milk=1/l" "eggs=6/ct"            # reconciliation: resets fridge's products
+
+sumac status                                             # current inventory, all locations
+sumac status fridge                                      # current inventory, one location
+sumac find milk                                           # where is milk right now?
+sumac log                                                 # full ordered event log
+sumac verify                                              # re-authenticate every line; check actors
+```
+
+All commands take `--data-dir` (default `data`, or `$SUMAC_DATA_DIR`).
+
+### Locations nest
+
+A location can have a parent, so shelves, doors, bins, drawers — anything — nest under a
+container to arbitrary depth. There's no separate "shelf" or "grid" type; a sub-location is just
+another location with `--parent` set.
+
+```sh
+sumac config add-location "Door" --id fridge-door --parent fridge
+sumac config add-array "Shelf" --parent fridge --count 4       # Shelf 1..4 under fridge
+sumac config add-grid "Bin" --parent pantry --rows 3 --cols 4  # Bin R1C1..R3C4 under pantry
+sumac config show                                              # renders the tree
+```
+
+`sumac status <location>` and `sumac find` both include everything nested under a location, not
+just that exact node — `sumac status fridge` sums the fridge itself, its door, and its shelves in
+one pass. Query a sub-location directly (e.g. `sumac status fridge-door`) to scope to just that
+node and its own descendants.
+
+## Development
+
+```sh
+uv run ruff format .
+uv run ruff check .
+uv run ty check
+uv run pytest
+```

sumac_home-0.1.0/README.md

@@ -0,0 +1,79 @@
+# sumac
+
+**🍋 sumac: home grocery inventory app**
+
+Encrypted-at-rest grocery inventory for a household sharing one git repo and one passphrase.
+Locations, products, and quantities are never visible to someone holding the repo without the
+passphrase — not even in file or directory names. See `docs/FORMAT.md` for the on-disk format
+and threat model, and `docs/LAYOUT.md` for what's read-only vs mutable.
+
+## Install
+
+Published on PyPI as `sumac-home` (`sumac` was taken); the command is still `sumac`.
+
+```sh
+uv tool install sumac-home     # or: pip install sumac-home
+```
+
+For development (this checkout):
+
+```sh
+uv sync
+```
+
+Depends on [`sealedlog`](https://pypi.org/project/sealedlog/) (the encrypted append-only log
+primitive) from PyPI.
+
+## Passphrase
+
+Set `SUMAC_PASSPHRASE`, or sumac will prompt interactively. The passphrase is shared by every
+user of the household's vault.
+
+## Usage
+
+```sh
+sumac init                                              # once, creates data/
+sumac config add-location "Fridge" --id fridge
+sumac config add-location "Pantry" --id pantry
+sumac config show
+
+sumac add purchase milk 2 l --to fridge
+sumac add consumption milk 1 l --from fridge
+sumac add movement rice 1 kg --from pantry --to fridge
+sumac snapshot fridge "milk=1/l" "eggs=6/ct"            # reconciliation: resets fridge's products
+
+sumac status                                             # current inventory, all locations
+sumac status fridge                                      # current inventory, one location
+sumac find milk                                           # where is milk right now?
+sumac log                                                 # full ordered event log
+sumac verify                                              # re-authenticate every line; check actors
+```
+
+All commands take `--data-dir` (default `data`, or `$SUMAC_DATA_DIR`).
+
+### Locations nest
+
+A location can have a parent, so shelves, doors, bins, drawers — anything — nest under a
+container to arbitrary depth. There's no separate "shelf" or "grid" type; a sub-location is just
+another location with `--parent` set.
+
+```sh
+sumac config add-location "Door" --id fridge-door --parent fridge
+sumac config add-array "Shelf" --parent fridge --count 4       # Shelf 1..4 under fridge
+sumac config add-grid "Bin" --parent pantry --rows 3 --cols 4  # Bin R1C1..R3C4 under pantry
+sumac config show                                              # renders the tree
+```
+
+`sumac status <location>` and `sumac find` both include everything nested under a location, not
+just that exact node — `sumac status fridge` sums the fridge itself, its door, and its shelves in
+one pass. Query a sub-location directly (e.g. `sumac status fridge-door`) to scope to just that
+node and its own descendants.
+
+## Development
+
+```sh
+uv run ruff format .
+uv run ruff check .
+uv run ty check
+uv run pytest
+```

sumac_home-0.1.0/docs/FORMAT.md

@@ -0,0 +1,61 @@
+# On-disk format and threat model
+
+## Threat model
+
+Anyone holding the repo but not the passphrase must learn nothing about the home's layout or
+its contents: no location names, no product names, no quantities. Accepted leakage: record
+count, approximate record size, commit timestamps, and OS usernames.
+
+Households share one passphrase. Ownership of a user's log is a convention
+(`getpass.getuser()`), not enforced by file permissions — the design makes violations
+*detectable* (`sumac verify`), not impossible.
+
+## Layout
+
+```
+data/
+  vault.json           # plaintext: format version, Argon2id params, salt, verifier
+  config.jsonl.enc      # encrypted JSONL, append-only: location definitions
+  log/<osuser>.jsonl     # encrypted JSONL, append-only, one per user: changes and snapshots
+```
+
+Every path component is a fixed literal or an OS username — never derived from a location or
+product name.
+
+## Sealed line
+
+The line-sealing primitive — AEAD, nonces, base64 framing, AAD, Argon2id key derivation, and
+the wrong-passphrase verifier — is not sumac's own code. It's provided by
+[`sealedlog`](https://pypi.org/project/sealedlog/), a standalone library extracted from an
+earlier version of this app; see its `docs/FORMAT.md` for the full spec. Summary of what that
+buys sumac:
+
+Each line is `base64(nonce‖ciphertext‖tag)`, sealed with XChaCha20-Poly1305 and a fresh random
+24-byte nonce. Appending is a byte-append, so git packs the history well. This costs per-line
+ciphertext overhead and leaks record count and approximate size — accepted per the threat model.
+
+## AAD binding
+
+Every sealed line is bound to the stream it belongs to via associated data built from sumac's
+namespace (`sumac.NAMESPACE`, `"sumac"`) and the `stream_id` (`"config"` or `"log:<osuser>"`) —
+see `sealedlog`'s AAD scheme for the exact byte layout. A line copied out of one stream into
+another fails to authenticate. This is what makes the ownership convention auditable: it can't
+stop a user from truncating their own file, but it prevents laundering a record into someone
+else's history.
+
+## Key derivation
+
+The key is derived from the shared passphrase via Argon2id (`sealedlog.Vault`), with a random
+salt and the KDF params stored in `vault.json` alongside sumac's own `format_version`. A
+`verifier` — a known plaintext sealed at vault-creation time — lets `sealedlog.Vault.unlock`
+reject a wrong passphrase immediately with `WrongPassphraseError`, instead of producing garbage
+downstream. `sumac.vault` wraps `Vault.create`/`Vault.unlock` with sumac's namespace baked in so
+call sites can't typo it.
+
+## Versioning
+
+Every record carries `schema_version`. A reader that encounters a record from a newer schema
+than it understands raises an "upgrade sumac" error rather than guessing.
+
+`data/**/*.jsonl` is declared `merge=union` in `.gitattributes`: correct for append-only
+streams, and it keeps concurrent pushes from conflicting.

sumac_home-0.1.0/docs/LAYOUT.md

@@ -0,0 +1,21 @@
+# Read-only vs mutable
+
+Read-only-ness is a convention, not enforced by file permissions. `sumac verify` detects
+violations after the fact; nothing prevents them at write time except `store.append`'s check
+that a `log:<osuser>` stream matches the current OS user.
+
+| Path | Mutability | Notes |
+| --- | --- | --- |
+| `src/sumac/` | Read-only for users | Pulled with the app; users don't edit it. |
+| `pyproject.toml`, `uv.lock`, CI, hooks | Read-only for users | App-level tooling. |
+| `data/vault.json` | Written once, by `sumac init` | KDF params and verifier; not append-only. |
+| `data/config.jsonl.enc` | Mutable by any user | Shared location registry; append-only. |
+| `data/log/<osuser>.jsonl` | Mutable only by `<osuser>` | Everyone else: read-only. |
+
+A user appends their own changes and snapshots to `data/log/<their-username>.jsonl` and never
+writes into another user's log. Corrections are new records carrying `supersedes: <record-id>`;
+no one ever rewrites or deletes a line in a log that isn't theirs — or, for that matter, in
+their own, since the format is append-only end to end.
+
+Run `sumac verify` after pulling to confirm every line in every log still authenticates under
+its own stream, and that no record's `actor` field disagrees with the file it lives in.

sumac_home-0.1.0/docs/PLAN.md

@@ -0,0 +1,136 @@
+# sumac — encrypted home grocery inventory
+
+## Context
+
+`/workspace` is a greenfield repo (`README.md`, `prompt.md`, one commit). `prompt.md` specifies a Python
+app that logs a household's grocery inventory across locations, with everything sensitive encrypted at
+rest so the repo can be pushed to a normal git remote.
+
+The threat model is narrow and worth stating, because it drives the whole design: **anyone holding the
+repo but not the passphrase must learn nothing about the home's layout or its contents.** That means the
+location config is encrypted too, and no filename, directory name, or git metadata may be derived from a
+location or product name. What we knowingly accept as leakage: record count, approximate record size,
+timestamps of commits, and OS usernames.
+
+Households share one passphrase. Users `git pull` the app, append their own records, and push. Ownership
+is a convention (`getpass.getuser()`), not file permissions — so the design makes violations *detectable*
+rather than impossible.
+
+Decisions taken with the user: passphrase from `SUMAC_PASSPHRASE` else interactive prompt; Typer + rich
+for the CLI; one JSONL log per user.
+
+## On-disk layout
+
+```
+data/                       # mutable — users append here
+  vault.json                # plaintext header: format version, KDF params, salt, verifier
+  config.jsonl.enc          # encrypted JSONL, append-only; latest revision wins
+  log/<osuser>.jsonl        # encrypted JSONL, one per user, append-only
+src/sumac/                  # read-only for users
+```
+
+Every path component is a fixed literal or an OS username. Nothing is derived from user data.
+
+**Sealed line** — `base64(nonce‖ciphertext‖tag)` + `\n`, XChaCha20-Poly1305, fresh 24-byte nonce per line.
+Appending is a byte-append; git packs it well.
+
+**AAD binds each line to its stream**: `b"sumac/v1|" + stream_id`, where `stream_id` is `"config"` or
+`"log:<osuser>"`. A ciphertext line copied out of alice's log into bob's fails to open. This is what makes
+the ownership convention auditable — it can't stop alice from truncating her own file, but no one can
+launder a record into someone else's history.
+
+**`vault.json`** holds `format_version`, Argon2id params (`salt`, `opslimit`, `memlimit`), and a `verifier`
+line sealed under AAD `sumac/v1|verifier`. A wrong passphrase fails there with a clear message instead of
+producing garbage downstream.
+
+## Modules
+
+One scope each; `models.py` is standalone so the data model can be edited without touching anything else.
+
+| Module | Responsibility |
+| --- | --- |
+| `sumac/__init__.py` | `__version__`, `SCHEMA_VERSION`, `FORMAT_VERSION` |
+| `sumac/models.py` | Frozen dataclasses. No I/O, no crypto, no pydantic imports. |
+| `sumac/schemas.py` | Pydantic v2 models at ingest boundaries + `to_domain()` converters |
+| `sumac/crypto.py` | `derive_key`, `seal_line`, `open_line`, `new_header`, `check_passphrase` |
+| `sumac/passphrase.py` | env-then-prompt resolution, key caching within a process |
+| `sumac/paths.py` | Data-dir layout; the single place path names are constructed |
+| `sumac/store.py` | Encrypted JSONL append/iterate over a `stream_id` |
+| `sumac/config.py` | Location layout on top of `store` |
+| `sumac/ledger.py` | Fold snapshots + changes → current inventory |
+| `sumac/render.py` | rich tables/panels — kept out of `cli.py` so command logic stays testable |
+| `sumac/cli.py` | Typer app |
+| `sumac/errors.py` | Exception hierarchy the CLI maps to exit codes |
+
+## Data model (`models.py`)
+
+- `Location(id, name, parent_id, metadata)` — flat with optional parent, so sublocations nest arbitrarily.
+- `Product(id, name, unit, category, metadata)`
+- `Quantity(amount: Decimal, unit: str)` — mismatched units raise rather than silently coerce.
+- `ChangeKind` enum: `purchase | consumption | waste | discovery | correction | movement`.
+- `InventoryChange(..., product_id, quantity, from_location, to_location, ...)` — a delta or a transfer.
+- `SnapshotEntry(product_id, quantity, metadata)`; `InventorySnapshot(location_id, entries, ...)` — the
+  full observed state of one location at one time.
+- `Record(schema_version, type, id, ts, actor, supersedes, payload)` — the envelope on every JSONL line.
+
+`metadata: Mapping[str, JsonValue]` on products, changes, snapshots and snapshot entries carries seller- or
+user-supplied extras beyond the core model; validated as JSON-serialisable at ingest, otherwise untouched.
+
+Corrections never rewrite: a new record carries `supersedes: <record-id>`.
+
+## Ledger semantics (`ledger.py`)
+
+1. Read all logs, drop any record id named by a `supersedes` field.
+2. Order by `(ts, actor, id)` for determinism across machines.
+3. Baseline per location = its most recent snapshot at or before the query time; a snapshot **resets** that
+   location's products rather than merging into them.
+4. Apply changes after that snapshot; `movement` applies a negative delta at `from_location` and a positive
+   one at `to_location`.
+
+## Ownership and versioning
+
+- `store.append()` refuses any `stream_id` other than the current user's — with the AAD binding above, that
+  is the mechanism, and `docs/LAYOUT.md` documents which paths are read-only by convention.
+- `sumac verify` re-opens every line of every log under its own AAD and reports lines that fail plus records
+  whose `actor` disagrees with the owning file.
+- `SCHEMA_VERSION` on every record; readers reject records from a newer schema with an "upgrade sumac" error.
+- `.gitattributes`: `merge=union` on `data/**/*.jsonl` — correct for append-only streams and it keeps
+  concurrent pushes from conflicting.
+
+## CLI
+
+`init`, `config show|add-location`, `add` (a change), `snapshot`, `status [location]`, `find <product>`,
+`log`, `verify`. Rendering lives in `render.py`.
+
+## Tooling
+
+- `pyproject.toml` (uv, `uv.lock` committed): `pynacl`, `pydantic>=2`, `rich`, `typer`; dev group `ruff`,
+  `ty`, `pytest`. PyNaCl for XChaCha20-Poly1305 — `cryptography` only ships the 12-byte-nonce variant.
+- `.claude/settings.json`: `PostToolUse` hook on `Edit|Write` running `uv run ruff format` on edited `.py`.
+- `.github/workflows/ci.yml`: `uv sync` → `ruff format --check` → `ruff check` → `ty check` → `pytest`.
+- Docs: `README.md` (usage), `docs/FORMAT.md` (on-disk format + threat model), `docs/LAYOUT.md`
+  (read-only vs mutable). Concise; no narration.
+
+## Build order
+
+1. Scaffolding: `pyproject.toml`, ruff/ty config, CI, Claude hook, doc skeletons.
+2. `models.py` + `schemas.py` + tests.
+3. `crypto.py`, `passphrase.py`, `paths.py`, `store.py` + tests.
+4. `config.py` + `ledger.py` + tests.
+5. `cli.py` + `render.py`, docs filled in.
+
+## Verification
+
+Tests: crypto round-trip; wrong passphrase fails at the verifier; a line moved between streams fails to
+open; `append` rejects a foreign `stream_id`; ledger cases (snapshot reset, movement, supersede, unit
+mismatch); config latest-revision-wins; and a leak test walking `data/` asserting every path component is a
+fixed literal or a known username.
+
+End-to-end, against a scratch data dir:
+
+```
+SUMAC_PASSPHRASE=test uv run sumac init
+… add-location, add, snapshot, status, verify
+grep -r "pantry\|fridge" data/     # must find nothing
+uv run ruff format --check . && uv run ruff check . && uv run ty check && uv run pytest
+```

sumac_home-0.1.0/prompt.md

@@ -0,0 +1,48 @@
+Make a Python app with encrypted event store to log the inventory of a home’s groceries in different locations.
+
+Make it fully generic, reading the config for the locations from a file that is encrypted.
+
+Encryption is with a universal passphrase that can be shared between users of the app. The goal of
+encryption is for the grocery records to be encrypted at rest (the config of the location layout and the content of groceries at those locations).
+The app must not leak these secrets through any files it creates (e.g. by using location names as
+folder names).
+
+The form of encryption will be per-line AEAD: each JSONL record is independently encrypted (XChaCha20-Poly1305, random nonce per line, base64'd), so appending a line is a byte-append and git packs it well. This costs you per-line ciphertext overhead and leaks record count and approximate size, but we accept that.
+
+The users of the app will pull down the app and update the mutable parts.
+
+The app users should expect some parts of the app to be read only and some parts to be mutable, and the app itself should be versioned.
+
+Users cannot mutate another user's historical records; they correct or supersede them by appending new records.
+
+Note that the read-only-ness is a convention and not achieved by file permissions. The name of the user can be obtained from the OS (`getpass.getuser()` in Python).
+
+The datasets should be read-only for the given user, no user should be able to edit someone else’s data.
+
+The program should be documented (but concisely, not narrated extensively). Use uv to manage the dependencies and include Claude Code hooks that tell an agent to run ruff format when editing the code.
+
+Keep the data model of the objects stored standalone in a module so that it can be easily edited.
+
+The product inventory should be able to carry extra metadata (such as might be provided by a grocery seller, or by users) beyond the core data model.
+
+Opt for modules dedicated to each of the scopes of functionality, do not overburden any one module. Use Pydantic for validation at the boundaries where data is ingested, and frozen dataclasses elsewhere.
+
+Use the rich library for the terminal app.
+
+Use ty in a GitHub CI check on the software.
+
+Use JSONL for the format of inventory logging, users will write that (users being the people living there).
+
+Model inventory logging around two primitives: inventory snapshots and inventory changes.
+
+A snapshot records the observed quantities of items at a particular location/sublocation at a specific point in time.
+
+A change records a delta or transfer to/from inventory (e.g. purchase, consumption, waste, discovery, correction, or movement between locations).
+
+Treat changes as the normal operational input and snapshots as explicit observations/reconciliation points.
+
+The current inventory should be derivable from a snapshot plus subsequent changes.
+
+Write concisely and avoid ‘slop’.
+
+Initially, create a plan, do not go all in

sumac_home-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "sumac-home"
+version = "0.1.0"
+description = "Home grocery inventory app"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "sealedlog>=0.1.0",
+    "pydantic>=2",
+    "rich>=13",
+    "typer>=0.12",
+]
+
+[project.scripts]
+sumac = "sumac.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sumac"]
+
+[dependency-groups]
+dev = [
+    "pynacl>=1.5",
+    "ruff>=0.6",
+    "ty>=0.0.1a1",
+    "pytest>=8",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sumac_home-0.1.0/src/sumac/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "0.1.0"
+
+SCHEMA_VERSION = 1
+FORMAT_VERSION = 1
+NAMESPACE = "sumac"