From 7ddf732952c6d6fb7393577d11a6169b5fbdd94d Mon Sep 17 00:00:00 2001 From: ai-bot Date: Sat, 14 Nov 2026 11:53:36 +0000 Subject: [PATCH] docs: add Skuld work plan --- docs/TODO.md | 375 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 375 insertions(+) create mode 100644 docs/TODO.md diff --git a/docs/TODO.md b/docs/TODO.md new file mode 100644 index 0000000..e860c48 --- /dev/null +++ b/docs/TODO.md @@ -0,0 +1,375 @@ +# Skuld — work plan + +Read `docs/spec.md` first. It is the contract; this file is the order of work. If this plan and +the spec disagree, the spec wins and the disagreement is a bug in this file. + +## Goal + +A StartOS service package named **Skuld**: a self-hosted web app that keeps a Bitcoin ledger and +computes the Norwegian tax figures for a tax year (formue, gevinst, tap, inntekt). Python +standard library, SQLite on the `main` volume, admin-password protected, UI in Norwegian +Nynorsk. After the last step the package builds, installs on StartOS, and produces the same +figures as the owner's spreadsheet. + +## Not in this plan + +Everything in `docs/spec.md` §11. Specifically: no other assets than BTC, no price feeds or +exchange import, no multi-user, no database encryption, no charts, no NOSTR, no PHP version. +Do not add abstraction, configuration or dependencies for any of them. The PHP version (§12) is +a later project; the only concession to it is that the DDL lives in `schema.sql`. + +## Rules for every step + +- Code, identifiers, comments and commit messages in English. User-facing text in Nynorsk. +- One step, then the repository is consistent: it imports, the tests pass, and nothing is left + half-written. Never leave a page without its script or a module without its caller. +- Commit at the end of each step, message in English, one line about what changed. +- Run the step's verification before moving on. If it fails, fix it in the same step. +- Do not reorder. Phase A is testable without any UI or packaging; Phase C is the packaging. +- When the spec is silent, choose the smaller option and record the choice in the commit + message. Ask the owner only for the four open questions in the spec (§13). + +## Decisions and why + +| # | Decision | Reason | +| --- | --- | --- | +| D1 | Python standard library + SQLite, same shape as the owner's VardKey app | No dependencies to install or patch, one file to back up, and the logic stays plain SQL and arithmetic so the PHP port is mechanical | +| D2 | Dates as `TEXT 'YYYY-MM-DD'` | Sorts and compares correctly in SQLite, no timezone handling anywhere | +| D3 | Money as integer øre, BTC as integer sats | No floating point in the ledger, so no rounding drift in cost bases | +| D4 | Lot-based ledger, explicit lot picking plus FIFO/LIFO/HIFO | The owner asked for UTXO-like picking; Norway has no FIFO requirement, so both must exist | +| D5 | `ledger.rebuild()` recomputes lots and auto consumptions on every write | Simplest model that cannot be corrupted by an edit or a delete, and fast enough for thousands of transactions | +| D6 | `schema.sql` at the repository root is the only DDL source, applied by `database.py` | One place to change, and phase 2 can apply the same file | +| D7 | Server returns JSON only; every page is a static file under `static/`; no JS framework, no build step | Same pattern as VardKey, and it is the pattern that ports to PHP unchanged | +| D8 | Prices entered by hand, seeded with Skatteetaten's published year-end BTC rates | A StartOS service should not need an external price API, and the owner already enters values by hand | +| D9 | GPL-3.0 | The auth pattern and the packaging shape are adapted from VardKey, which is GPL-3.0 | +| D10 | Wealth tax off by default, threshold and rate configurable | Thresholds change every year; a hardcoded number would be wrong within a year | +| D11 | A transfer consumes lots at the source and mirrors them at the destination, and generates the `transfer_in` row | The owner's spec requires the auto-generated row; mirroring is what carries the acquisition date and the cost basis | +| D12 | Non-taxable accounts are real accounts with `taxable = 0`, plus `custody_market_id` for the `TOT` rows | Reproduces the spreadsheet's main sheet, including the reconciliation rows | +| D13 | No secret-scanning module, unlike VardKey | Skuld has no field where a seed phrase or a key would belong; a guard would be decoration | +| D14 | The 22 % rate is a setting, not a constant | Rates change; the report shows which rate produced the figures | + +## Phase A — application core (Python, testable from a terminal) + +### 1. `LICENSE` +Add GPL-3.0, verbatim, with the owner's copyright line. +**Verify:** file exists and starts with `GNU GENERAL PUBLIC LICENSE`. + +### 2. `.gitignore` +Ignore `__pycache__/`, `*.pyc`, `*.sqlite3`, `*.sqlite3-journal`, `data/`, `node_modules/`, +`dist/`, `*.s9pk`, `.env`. +**Verify:** `git status` shows no database file or `__pycache__`. + +### 3. `schema.sql` +The DDL from `docs/spec.md` §4, verbatim, in the same order, with `CREATE TABLE IF NOT EXISTS` +and the indexes. No seed data. +**Verify:** `sqlite3 /tmp/skuld.sqlite3 < schema.sql` succeeds; `.schema` lists every table. + +### 4. `database.py` +`connect()` returning a connection with `PRAGMA foreign_keys = ON` and +`PRAGMA journal_mode = WAL`; `apply_schema()` reading `schema.sql` from the directory of this +file; `schema_version` written as `1`; `seed_defaults()` inserting the settings keys of +`docs/spec.md` §4.1 with their defaults and the six published BTC rates of §5.3 using +`INSERT OR IGNORE`; `get_setting(key)` / `set_setting(key, value)`; row factory so rows behave +like dicts. The database path comes from the `DATABASE_PATH` environment variable, defaulting +to `data/skuld.sqlite3` for local development, and the parent directory is created if missing. +**Verify:** `python3 -c "import database; database.connect(); print('ok')"` creates the file and +`sqlite3 data/skuld.sqlite3 "select count(*) from prices"` returns `6`. + +### 5. `rates.py` +`year_end_date(tax_year)` returning `'-01-01'`; `get_rate(tax_year)` reading `prices` +and returning øre per BTC or `None`; `set_rate(date, nok_per_btc_ore, source)`; `list_rates()`. +Money conversion helpers: `nok_to_ore(text)`, `ore_to_nok(ore)` and `parse_btc_to_sats(text)` +accepting both `,` and `.` as the decimal separator, rejecting more than 8 decimals. +**Verify:** a unit test asserting `year_end_date(2025) == '2026-01-01'`, `get_rate(2025)` equals +`88120606` øre, and `nok_to_ore("1 234,50") == 123450`. + +### 6. `auth.py` +The admin account and the sessions, following the VardKey pattern described in `docs/spec.md` +§9: `admin_exists()`, `create_admin(username, password)`, `verify_login(username, password)`, +`create_session()` returning the raw token, `session_valid(token)`, `delete_session(token)`, +`change_password(current, new)`; PBKDF2-HMAC-SHA256 with a random 16-byte salt and an iteration +count stored in the row; `hmac.compare_digest` for both the password and the session hash; +sessions store only the SHA-256 hash of the token with an expiry, and expired rows are deleted +on use. Minimum password length 12, enforced here and in `validation.py`. +**Verify:** a unit test creating an admin, asserting the wrong password fails, the right one +passes, a session is valid once and that a second `session_valid` after expiry returns False. + +### 7. `validation.py` +Field validation returning `(value, error_message)` pairs with Nynorsk messages: dates, +amounts in sats and øre, the type list, the per-type required-field rules of `docs/spec.md` +§7.3, the rule that exactly one leg of a `trade` is sats and the other NOK, that +`transfer_in` may not be chosen as a type, and that a `transfer_out` needs a different +destination account. +**Verify:** a unit test covering one rejection per rule, asserting the message is Nynorsk and +the `field` name is the offending one. + +### 8. `ledger.py` +The lot ledger of `docs/spec.md` §5: `create_lots_for(tx)`, `consume(tx, picks)`, +`candidate_lots(market_id, date)`, `pick_for_method(lots, sats, method)`, `holdings_at(date)`, +`sats_in_market(market_id, date)` and `rebuild()`. Rounding exactly as §5.3. A shortfall raises +`LedgerError` with the shortfall in sats. `rebuild()` deletes and replays as §5.4 describes and +is idempotent. +**Verify:** `tests/test_ledger.py` (step 15) plus, in this step, a manual check: +`python3 -c "import ledger"` and a rebuild over an empty database does nothing and raises +nothing. + +### 9. `tax.py` +The year report of `docs/spec.md` §6: `report(year)` returning the per-account rows, the totals, +the tax figures, the `skattemelding` block, the non-taxable rows and the `custody_totals` rows, +using only the ledger state at 31.12 and the transactions of the year. No presentation logic and +no currency formatting here. +**Verify:** `tests/test_tax.py` (step 16) plus the golden example of §6.4 by hand for FIFO. + +### 10. `export.py` +`report_csv(year)` and `transactions_csv(year)`: semicolon-separated, UTF-8 BOM, Norwegian +decimal comma, one block of report rows then one block of transactions with the consumed cost +per transaction. +**Verify:** `python3 -c "import export; print(export.report_csv(2024)[:80])"` and confirm the +BOM is present and the separator is `;`. + +### 11. `maintenance.py` +A command-line script the StartOS actions run inside the container: `set-admin-password` +generating a random password inside the container, storing it, and printing one JSON object +`{"username": ..., "password": ...}` on stdout; `delete-all-data` wiping every table except +`admin` and `settings` and requiring `--confirm`. Both open the database at `DATABASE_PATH`. +**Verify:** `DATABASE_PATH=/tmp/m.sqlite3 python3 maintenance.py set-admin-password` prints one +JSON object, and the password it prints logs in through `auth.verify_login`. + +### 12. `app.py` — server core +`ThreadingHTTPServer` and a `BaseHTTPRequestHandler` subclass; the route table as a list of +`(method, pattern, handler)`; `/health` answering `{"status":"ok"}` without a session; static +file serving from `static/` with correct content types and `Cache-Control: no-store`; the +session cookie; the CSRF check on every mutating `/api/*` call; the 401/redirect gate; and the +`/api/auth/*` routes of `docs/spec.md` §8. Port from `PORT`, default 8080; binds `0.0.0.0`. +**Verify:** `python3 app.py` then `curl -s localhost:8080/health` returns `{"status":"ok"}`, +`curl -s -o /dev/null -w '%{http_code}' localhost:8080/api/markets` returns 401, and +`curl -s localhost:8080/api/auth/state` returns `admin_exists: false`. + +### 13. `app.py` — data routes +Add `/api/markets`, `/api/transactions`, `/api/lots`, `/api/prices` and `/api/settings` with the +methods of §8, calling `ledger.rebuild()` after every write that can change the ledger, and +returning validation errors as `{"error", "field"}` with status 400. +**Verify:** create an account and a buy with `curl`, then `GET /api/lots` shows one lot with the +right sats and cost; delete the transaction and the lot is gone. + +### 14. `app.py` — report routes +Add `/api/report` and `/api/report/export.csv`, the latter with +`Content-Disposition: attachment`. +**Verify:** `curl -s 'localhost:8080/api/report?year=2024'` returns the report JSON for a +seeded year, and the CSV download opens in a spreadsheet with Norwegian number formatting. + +### 15. `tests/test_ledger.py` +`unittest`, run with the standard library only. Cases: FIFO/LIFO/HIFO ordering on the golden +example of `docs/spec.md` §6.4; a partial consumption and its rounding; consuming across three +lots; explicit picks overriding the method; a shortfall raising `LedgerError`; a transfer +consuming at the source and mirroring the acquisition date and cost at the destination; a +rebuild run twice producing identical rows; `holdings_at` before and after a sale. +**Verify:** `python3 -m unittest discover -s tests -v` — all green. + +### 16. `tests/test_tax.py` +`unittest`. Cases: the four gains of the golden example per method; formue from the year-end +rate; income as income and not as gain; a non-taxable account excluded from every total but +present in the holdings; the `TOT` row summing the custodian's own sats and its dependants'; +fees applied per `docs/spec.md` §3.2 for a buy and a sell; a gift received setting the cost +basis; `netto`, `skatt_ore` and the `skattemelding` block. +**Verify:** `python3 -m unittest discover -s tests -v` — all green. + +## Phase B — user interface (Nynorsk) + +### 17. `static/style.css` +One stylesheet: layout, the main-sheet table with right-aligned numbers, the form, inline error +text, the navigation, and print styles for the report. No external fonts or CDNs. +**Verify:** open `/login` with the server running and confirm the page is readable and needs no +network access. + +### 18. `static/session.js` +Patches `window.fetch` to add the `X-CSRF-Token` header on same-origin calls when it is not +already set, and to redirect to `/login` on a 401. +**Verify:** `curl -s localhost:8080/login` loads and the browser console shows no error; a +mutation from the console carries the header. + +### 19. `static/app.js` +Shared helpers used by every page: `api(method, path, body)` returning parsed JSON and throwing +an error object with `field`, number and date formatting for Norwegian, the main-sheet row +renderer, and the page dispatcher on `document.body.dataset.page`. +**Verify:** no page breaks; the console has no syntax errors. + +### 20. `static/login.html`, `static/login.js` +Sign in, and the create-admin form when `admin_exists` is false, both in Nynorsk, with the +password rule and the inline errors from the API. On success, go to `/` if accounts exist, +otherwise to `/marknader`. +**Verify:** a fresh database shows the create-admin form; after creating the admin, a reload +shows the sign-in form, and a wrong password shows a Nynorsk error. + +### 21. `static/index.html`, `static/index.js` +The main sheet of `docs/spec.md` §7.2: totals row first, then taxable accounts, then the +non-taxable accounts, then the `TOT` rows, with the columns and headings of §7.2, a year +selector, a "Ny transaksjon" button, and the legend. Empty state per §7.5. +**Verify:** with the golden example loaded, the row for the account matches the numbers from +`/api/report`, and `TOT` rows appear only where an account has custody of another's coins. + +### 22. `static/transactions.html`, `static/transactions.js` +The filterable list: year, account and type filters; newest first; each row links to the form; +generated `transfer_in` rows are marked as generated and cannot be edited. Delete asks for +confirmation and deletes the pair for a `transfer_out`. +**Verify:** filtering by year and account changes the list; deleting a `transfer_out` removes +both rows. + +### 23. `static/transaction.html`, `static/transaction.js` +The form of `docs/spec.md` §7.3: the field order Generelt, the type-specific fields, Avgift, +Anna; the taxable checkbox ticked by default; the currency selectors; the `Parti` section with +the candidate lots, the method's automatic pick pre-selected, the ability to tick other lots or +change the amounts, and a "Bruk automatisk" button. Inline Nynorsk errors, and the shortfall +message from `LedgerError` shown next to the amount. +**Verify:** save one transaction of each type; each appears in the list with the expected +figures; a shortfall produces the Nynorsk message and no row is written. + +### 24. `static/markets.html`, `static/markets.js` +Account admin: name, kind (Børs/Lommebok/Anna), taxable flag, custody account, note, sort order, +archive. Refuse deletion of an account that has transactions, with the reason shown. +**Verify:** create one exchange, one wallet, one child account with the exchange as custodian, +and confirm the main sheet shows the `TOT` row. + +### 25. `static/report.html`, `static/report.js` +The year report of §6: the per-account table, the totals, the tax figures, the `skattemelding` +block with the four figures, the non-taxable section, the method and rate used, and the CSV +download button. +**Verify:** the figures equal the API response, and the download saves a file that opens in a +spreadsheet. + +### 26. `static/settings.html`, `static/settings.js` +Settings: method (FIFO/LIFO/HIFO), tax rate, wealth tax switch, threshold and rate, +`deduct_admin_costs`, the rate table with editing, the price source text, and change password. +Changing the method warns that the figures will change and rebuilds the ledger. +**Verify:** switching FIFO → HIFO changes the report figures to the golden example's HIFO +values, and switching back restores them. + +## Phase C — StartOS package + +### 27. `package.json`, `tsconfig.json`, `.prettierrc` +The build tooling for the packaging TypeScript, copied in shape from the owner's VardKey +repository and the StartOS packaging guide. Start from the packaging workspace created by +`start-cli s9pk init-workspace` and read the recipe index before copying anything. +**Verify:** `npm install` succeeds and `npx tsc --noEmit` reports no errors. + +### 28. `Dockerfile`, `.dockerignore` +Slim Python base; copy `app.py`, `auth.py`, `database.py`, `ledger.py`, `tax.py`, `rates.py`, +`export.py`, `validation.py`, `maintenance.py` and `schema.sql` into `/app`; copy `static/` into +`/app/static`. No `USER` line, because the `main` volume must be writable without a `chown`. +No packages installed: the app is standard library only. +**Verify:** `docker build -t skuld-test .` succeeds and +`docker run --rm -e PORT=8080 -e DATABASE_PATH=/tmp/s.sqlite3 skuld-test python3 -c "import app"` +exits 0. + +### 29. `Makefile` +The packaging targets of the StartOS template, pointing at `startos/index.ts`. +**Verify:** `make` produces `skuld.s9pk`. + +### 30. `icon.svg` +The app icon, under 40 KiB, same artwork as any icon the app serves. A simple mark is enough; +do not add a second icon file. +**Verify:** the file is valid SVG and under the size limit. + +### 31. `startos/sdk.ts`, `startos/utils.ts` +`sdk` built with the package id `skuld`; the constants `uiPort = 8080`, `volumeId = 'main'`, +`dataMountpoint = '/data'`, `databasePath = '/data/skuld.sqlite3'`, `imageId`, `subcontainerName`. +**Verify:** `npx tsc --noEmit` passes. + +### 32. `startos/manifest/index.ts`, `startos/manifest/i18n.ts` +The manifest: id `skuld`, Nynorsk title and description, `dockerBuild: {}`, architectures +`x86_64` and `aarch64`, the `main` volume, the `ui` interface, no dependencies, the donation +link if the owner wants one. +**Verify:** `make` still builds and the manifest text is Nynorsk. + +### 33. `startos/versions/index.ts` +The version graph with the first version and its `main` entry. +**Verify:** `npx tsc --noEmit` passes and `make` produces a package whose version matches. + +### 34. `startos/interfaces.ts`, `startos/backups.ts`, `startos/dependencies.ts` +The `ui` interface on port 8080 with `preferredExternalPort: 80`; +`sdk.Backups.ofVolumes('main')`; no dependencies. +**Verify:** `make` builds; the built package lists one interface and one volume. + +### 35. `startos/i18n/index.ts`, `startos/i18n/dictionaries/nb_NO.ts` +The i18n wrapper and the Nynorsk dictionary for everything StartOS displays: the readiness +messages, the action names and descriptions, the task text. +**Verify:** `make` builds and no user-facing string in `startos/` is English. + +### 36. `startos/actions/index.ts`, `startos/actions/setAdminPassword.ts`, `startos/actions/deleteAllData.ts` +The two actions of `docs/spec.md` §9, each running `maintenance.py` in a `withTemp` +subcontainer mounted on the main volume. `set-admin-password` shows the generated credentials +once; `delete-all-data` refuses to run unless its confirmation box is ticked. +**Verify:** both actions appear under Actions & Config on a test box; the generated password +signs in; the wipe returns the app to the empty state while the admin still works. + +### 37. `startos/init/index.ts`, `startos/init/requireAdmin.ts` +The init script registered in `sdk.setupInit()` after the actions, raising the recommended task +"Set the admin password before Skuld can be used." while no admin exists and clearing it +afterwards, with a stored replay id. The probe reads the SQLite database readonly in a +`withTemp` subcontainer and fails open. +**Verify:** on a fresh install the task shows as recommended and the service still starts; after +setting the password the task disappears. + +### 38. `startos/main.ts` +The single daemon `primary` in `skuld-sub`: image, the `main` volume mounted writable at +`/data`, `python3 app.py` with `PORT` and `DATABASE_PATH`, and the readiness check against +`http://127.0.0.1:8080/health` displayed as "Web Interface". The port must be the same number +in `utils.ts`, `main.ts` and `interfaces.ts`. +**Verify:** `make` builds and installing the package on a test box turns the health check green. + +### 39. `.github/workflows/build.yml` +The build workflow of the StartOS template: build and release the `.s9pk` on a tag. +**Verify:** the workflow file is valid YAML and the lint job (if the template has one) passes. + +### 40. `README.md` +The technical reference for an AI support agent or an administering agent, in the section order +of the owner's VardKey README: image and container runtime, volume and data layout, file models, +dependencies, network access and interfaces, installation and first-run flow, actions, tasks, +health checks, backups and restore, limitations and differences, and a quick reference block +for AI consumers. +**Verify:** every claim in it matches `startos/` and the Dockerfile. + +### 41. `instructions.md` +The end-user documentation, in Nynorsk: what Skuld does, how to set the admin password, how to +create accounts, how to enter each transaction type, how to read the main sheet, how to get the +tax figures, and the limitations — including that the database is not encrypted and that Skuld +gives figures, not tax advice. +**Verify:** a reader who has never seen the app can go from install to a tax figure. + +### 42. `AGENTS.md` +The repository mechanics: that the code is English and the UI Nynorsk, that `schema.sql` is the +only DDL source, that the ledger is rebuilt rather than patched, that `docs/spec.md` outranks +this plan, and the build and test invocations. +**Verify:** it contradicts nothing in `docs/spec.md`. + +## Phase D — verification + +### 43. Build, install and run through +1. `python3 -m unittest discover -s tests -v` — all green. +2. `make` — builds `skuld.s9pk` without warnings. +3. Install on a StartOS box: the service starts, the health check goes green, the interface + opens, the first-run flow creates the admin. +4. Enter the golden example of `docs/spec.md` §6.4 through the UI and compare every figure with + the spec, for all three methods. +5. Create a child account with the exchange as custodian and confirm the `TOT` row and the + exclusion from the totals. +6. Do a transfer between two accounts, edit it, and delete it: the lots and the report must + return to their earlier state. +7. Back up, restore, and confirm the figures are identical. +8. Download the CSV and open it in a spreadsheet. + +## Verification commands + +| Command | Checks | +| --- | --- | +| `python3 -m unittest discover -s tests -v` | the ledger and the tax rules | +| `python3 app.py` + `curl -s localhost:8080/health` | the server starts and answers | +| `curl -s -o /dev/null -w '%{http_code}' localhost:8080/api/markets` | 401 without a session | +| `sqlite3 data/skuld.sqlite3 ".schema"` | the schema was applied | +| `npx tsc --noEmit` | the packaging TypeScript | +| `make` | the `.s9pk` builds | +| install on a StartOS box | the package really runs | + +`make` and `npx tsc` need the StartOS packaging workspace (`start-cli s9pk init-workspace`) and +Docker. If the toolchain is not available, say so in the step's commit message instead of +skipping the step silently.