Files
skuld/docs/TODO.md
T

24 KiB

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.

Progress

Steps finished, in the order of this plan. The coding agent appends one line per finished step, with the commit message it used where the spec left a choice.

  • 1 LICENSE — GPL-3.0 verbatim, copyright line Copyright (C) 2026 sondreolav (no personal name in the spec).
  • 2 .gitignore
  • 3 schema.sql — the DDL of docs/spec.md §4 verbatim, 10 tables, 5 indexes.
  • 4 database.py
  • 5 rates.py
  • 6 auth.py — the CSRF secret is derived from the session token, because sessions has no CSRF column; session lifetime 30 days (not specified).
  • 7 validation.py
  • 8 ledger.py — a sats fee raises the consumed sats for a sale and a spend only (spec §3.2); for a transfer it lowers what arrives, and elsewhere it is only recorded. rebuild() clears every consumption, because lot_consumptions is derived and lot_picks is the durable input; a stale pick is skipped rather than fatal.
  • 9 tax.py — holdings come from the ledger at 31.12, so a sale in a later year cannot change an earlier year's formue.
  • 10 export.py — report_csv() carries the UTF-8 BOM and is followed by transactions_csv().
  • 11 maintenance.py — auth.reset_password() added, because the action cannot know the old password.
  • 12 app.py — server core, static pages, the session cookie, the CSRF check and /api/auth/*.
  • 13 app.py — /api/markets, /api/transactions, /api/lots, /api/prices, /api/settings; every write that can move the ledger ends with ledger.rebuild().
  • 14 app.py — /api/report and /api/report/export.csv.
  • next: 15 tests/test_ledger.py, 16 tests/test_tax.py

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 '<year+1>-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.