456 lines
30 KiB
Markdown
456 lines
30 KiB
Markdown
# 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 B3 must be finished before Phase C starts.
|
||
- 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 |
|
||
| D15 | BTC is shown in sats everywhere, in the UI and in the CSV; the only `10^8` conversion is inside the price and formue arithmetic | The owner reads sats; a BTC amount with eight decimals is unreadable in a sheet |
|
||
| D16 | NOK is displayed in whole kroner, stored and computed in øre; decimals are accepted only in input fields | The owner does not want to see decimals, but rounding in the ledger would lose øre and let sums drift |
|
||
| D17 | `admin_cost` has no account (`market_id` null), takes no fee, and consumes no lots | The owner wants it to stand on its own; it changes no holdings, so nothing else can be derived from it |
|
||
| D18 | The transaction price is derived on the fly and never stored, and is called `btc_price_ore` in the API on both transactions and lots | It is a function of legs the owner already entered, so storing it would let it drift; the owner's word for it is "bitcoin pris", so the API uses one name for one unit |
|
||
| D19 | The stored rate column keeps its name `prices.nok_per_btc_ore`, and the settings table keeps the heading `NOK per BTC` | It is Skatteetaten's year-end rate, not a transaction price; renaming a stored column buys a migration and nothing else |
|
||
| D20 | The Avgift section is hidden for `gift_received` and `admin_cost` | The owner's field list gives those two no fee, and the schema refuses one |
|
||
| D21 | A fee is entered in sats only; a kroner cost is folded into the amount the owner types | The owner asked for it, and it keeps every leg to one currency with no conversion the app would have to invent |
|
||
| D22 | A transfer's fee is taken on top at the source, so what is sent is exactly what arrives | The owner requires `INN` on the `transfer_in` to equal `Sendt` on the `transfer_out`; subtracting the fee would also make the fee vanish from the destination's holdings instead of the source's |
|
||
| D23 | The mirrored lots cover exactly the sent amount, and the cost share of the fee sats leaves the ledger with them | It keeps the destination's price per sat identical to the source's, which is what "inherits the price of the chosen lot" means. Skuld books no gain or loss for a fee |
|
||
| D24 | A transfer's price comes from its consumed lots (out) and its mirrored lots (in) | Same unit as the price of a buy, both sides of the pair agree, and nothing extra is stored |
|
||
| D25 | `admin_cost` is in kroner | The owner confirmed it. No account, no lots, and no conversion: the report shows the sum and subtracts it only when `deduct_admin_costs` is on |
|
||
| D26 | `fee_ore` stays in the schema, always 0 | `CREATE TABLE IF NOT EXISTS` cannot drop a column, and a migration is not worth it for a dead field; no client ever sends it |
|
||
| D27 | A field with a single currency shows the unit as plain text instead of a selector | The owner asked for it, and a select with one option claims a choice that does not exist |
|
||
| D28 | A fictional `Bank` account pays the costs, and a `Forvaltningskostnad` is one row on it | The cost must not draw on a real account; one row keeps the list short. Superseded in part by D36 |
|
||
| D29 | The kroner balance of an account is derived from its legs and never stored | It is a sum over rows that already exist, so nothing can drift |
|
||
| D30 | A `transfer_out` carries either sats or kroner, never both | One currency per transfer keeps the mirroring rules and the form simple |
|
||
| D31 | Only kroner can be withdrawn with an empty `Til` | The owner asked for it, and a sats transfer always needs a destination |
|
||
| D32 | `deduct_admin_costs` stays off by default | The owner confirmed it; the deductibility of the cost is still open as Q2 |
|
||
| D33 | Kroner move only between an account and the bank, never between two real accounts | The owner asked for it: kroner on an exchange are not a holding to move around, but fiat goes in and out through the bank |
|
||
| D34 | `Til` is always required, and the bank may be chosen there or as the account of a kroner transfer | It replaces the empty-`Til` withdrawal: nothing leaves the ledger silently, and where the money went is visible as a stored pair |
|
||
| D35 | A `trade` buy is refused when the kroner do not cover it | The owner asked whether a buy should draw on available kroner; buying with money the account does not hold is the same mistake as selling coins it does not hold, and the remedy is a deposit from the bank |
|
||
| D36 | A `Forvaltningskostnad` is one `leg_out_ore` on the bank, and it must have the kroner there | The owner asked whether the two equal legs were wrong: they were, once the bank became a real account, because the cost never reduced it and the "in" leg was a movement that never happened |
|
||
| D37 | No account, the bank included, may go negative | The owner's rule: every payment that would overdraw is refused, and the remedy is to record where the money came from |
|
||
|
||
## Phase A — application core (steps 1-16) — DONE
|
||
|
||
Implemented and committed: `LICENSE`, `.gitignore`, `schema.sql`, `database.py`, `rates.py`,
|
||
`auth.py`, `validation.py`, `ledger.py`, `tax.py`, `export.py`, `maintenance.py`, `app.py` (in
|
||
three steps) and `tests/test_ledger.py`, `tests/test_tax.py`.
|
||
`python3 -m unittest discover -s tests -v` is green.
|
||
|
||
## Phase B — user interface (steps 17-26) — DONE
|
||
|
||
Implemented and committed: `static/style.css`, `static/session.js`, `static/app.js`, and the
|
||
page pairs `login.*`, `index.*`, `transactions.*`, `transaction.*`, `markets.*`, `report.*` and
|
||
`settings.*`.
|
||
|
||
## Phase B2 — first round of corrections (steps 27-44) — DONE
|
||
|
||
Sats everywhere, whole kroner in the display, the `Bitcoin pris` figure, `admin_cost` off the
|
||
accounts, and no fee for `gift_received`.
|
||
|
||
## Phase B3 — second round of corrections (steps 45-55)
|
||
|
||
Do these before Phase C. The owner has reviewed the app again. These steps change the fee to
|
||
sats only, change the transfer pair so that what is sent is what arrives, make
|
||
`Forvaltningskostnad` a kroner cost, and make the form match the owner's field list exactly.
|
||
|
||
### 45. `validation.py`
|
||
A fee is sats only. `ORE_FIELDS` loses `fee_ore`, and `validate_transaction` still reads it but
|
||
only to reject it: a non-blank `fee_ore` gives the error "Avgift må berre førast i sats." on
|
||
`fee_sats`, and the stored value is always 0. Keep the rule that `gift_received` and `admin_cost`
|
||
take no fee, and keep the check that a fee is smaller than the amount it belongs to.
|
||
|
||
`admin_cost` is a kroner cost now: `_ALLOWED_LEGS["admin_cost"] = ("leg_out_ore",)`,
|
||
`_REQUIRED["admin_cost"] = (("leg_out_ore", "Fyll ut kostnaden i kroner."),)`, and
|
||
`_check_admin_cost` accepts exactly one `leg_out_ore` and rejects `leg_out_sats`.
|
||
|
||
`loss` requires its price: add `("value_ore", "Fyll ut prisen i kroner.")` to
|
||
`_REQUIRED["loss"]`.
|
||
**Verify:** an `admin_cost` payload with `leg_out_ore` validates clean, the same payload with
|
||
`leg_out_sats` gives a Nynorsk error on `leg_out_sats`, a payload with `fee_ore` gives the
|
||
"berre sats" error, and a `loss` without `value_ore` is rejected.
|
||
|
||
### 46. `ledger.py`
|
||
`FEE_ADDS_TO_CONSUMPTION` becomes `("trade", "spend", "transfer_out")` and its comment says that
|
||
a transfer's fee is taken on top of what is sent. In `create_lots_for`, drop the `fee_ore`
|
||
arithmetic: the cost of a buy is the kroner that left the account, and the cost of `income` and
|
||
`gift_received` is `value_ore`.
|
||
|
||
Rewrite `_mirror_transfer`: read `leg_out_sats` from the source `transfer_out` as well as its id,
|
||
then mirror exactly that many sats across the consumed parts in order, using `_split_capped`.
|
||
For each part the mirrored cost is the part's proportional share, `_cost_for(part cost, part
|
||
sats, mirrored sats)`, so the cost per sat is unchanged. The `fee_sats` and `fee_ore` of the
|
||
`transfer_in` are not read at all. Delete `_split_even`, which nothing else uses.
|
||
**Verify:** `python3 -m unittest discover -s tests -v`; then, by hand, a transfer of 100 000 sats
|
||
with a 1 000 sats fee leaves the source 101 000 sats lighter, the destination 100 000 sats
|
||
richer, and both sides' lots at the same price per sat.
|
||
|
||
### 47. `tax.py`
|
||
`btc_price_ore` learns the transfer case: for a `transfer_out` it uses `cost_ore` and
|
||
`consumed_sats`, for a `transfer_in` it uses `lot_cost_ore` and `lot_sats`, and it still returns
|
||
None for `gift_given` and `admin_cost`. Remove `fee_ore` from the income and proceeds arithmetic
|
||
in `report`, since it is always 0 now.
|
||
|
||
`admin_cost` is kroner: sum `leg_out_ore` of the year's taxable `admin_cost` rows into
|
||
`admin_cost_ore`, drop `admin_cost_sats` from the totals, and subtract the sum from `netto_ore`
|
||
only when `deduct_admin_costs` is on. Drop `fee_ore` from the `_year_rows` select.
|
||
**Verify:** `python3 -m unittest discover -s tests -v`; a `transfer_out` and its `transfer_in`
|
||
report the same `btc_price_ore`, and a transfer with a fee still reports the same price on both
|
||
sides.
|
||
|
||
### 48. `app.py`
|
||
In `_sync_transfer_pair`, `arrived` becomes the sent amount itself, `tx["leg_out_sats"]`, and the
|
||
generated `transfer_in` is written with `fee_sats` and `fee_ore` of 0 on both the insert and the
|
||
update path.
|
||
|
||
In `_load_transaction` and `transactions_list`, add the three derived columns `btc_price_ore`
|
||
needs for a transfer: `COALESCE(SUM(c.sats), 0) AS consumed_sats`, and
|
||
`COALESCE((SELECT SUM(l.cost_ore_original) FROM lots l WHERE l.origin_tx_id = t.id), 0) AS
|
||
lot_cost_ore` with the same for `l.sats_original` as `lot_sats`.
|
||
**Verify:** save a transfer with a fee: `GET /api/transactions` shows the `transfer_out` with
|
||
`leg_out_sats` 100000 and `fee_sats` 1000, and the `transfer_in` with `leg_in_sats` 100000 and
|
||
`fee_sats` 0, and both with the same `btc_price_ore`.
|
||
|
||
### 49. `export.py`
|
||
Drop the `Avgift (kr)` column and rename `Pris (kr)` to `Bitcoin pris (kr)`. In the report block
|
||
keep one line, `Forvaltningskostnad (kr)` from `admin_cost_ore`. Add the same three derived
|
||
columns as step 48 to the transaction query, so the transfer price is filled in.
|
||
**Verify:** download a year with a transfer and an `admin_cost`; both sides of the transfer carry
|
||
the same price, the `admin_cost` row is present with its kroner amount, and there is no
|
||
`Avgift (kr)` column.
|
||
|
||
### 50. `tests/test_ledger.py`
|
||
Update the fixtures for the sats-only fee and the new transfer rules, and add: a transfer with a
|
||
fee leaves the destination with exactly the sent sats and the source with the sent sats plus the
|
||
fee gone; the destination lots keep the source's cost per sat; the fee's cost share is not
|
||
mirrored; `holdings_at` after a transfer is source − sent − fee and destination + sent.
|
||
**Verify:** `python3 -m unittest discover -s tests -v` — green.
|
||
|
||
### 51. `tests/test_tax.py`
|
||
Update the fixtures and add: `admin_cost` in kroner lands in `admin_cost_ore` and is subtracted
|
||
only when the setting is on; a `loss` without a price is rejected by validation;
|
||
`btc_price_ore` is the same for a `transfer_out` and its `transfer_in`, and is None for
|
||
`gift_given` and `admin_cost`.
|
||
**Verify:** `python3 -m unittest discover -s tests -v` — green.
|
||
|
||
### 52. `static/transaction.html`
|
||
Give every currency slot a plain-text unit next to its amount: a `<span class="unit"
|
||
data-unit="leg_in">`, the same for `leg_out`, `value` and `fee`. Keep the two `<select>`s for
|
||
`leg_in_currency` and `leg_out_currency`, with the options `sats` and `kr`, because those are the
|
||
only slots where the currency is a choice. Remove the `fee_currency` select: a fee is sats only.
|
||
Rewrite the Avgift hint to say that the fee is in sats, that it raises the cost basis of a buy,
|
||
and that on a transfer it is taken on top of what you send. Add the `.field-currency .unit` rule
|
||
to `static/style.css` if the plain text needs it.
|
||
**Verify:** open the form; the Avgift section has one amount field and the text `sats`, and no
|
||
currency selector.
|
||
|
||
### 53. `static/transaction.js`
|
||
`TYPE_FIELDS` per `docs/spec.md` §7.3: `trade` gets `default: "sats"` on `in` and `default: "nok"`
|
||
on `out`; `loss` loses `optional` on its `value`, so the price is required; `admin_cost` becomes
|
||
`out: {label: "Kostnad", currencies: ["nok"]}`; and `transfer_in` is added for display only, as
|
||
`{in: {label: "Motteke", currencies: ["sats"]}, consumes: false, market: true, fee: false}`.
|
||
|
||
`applyType()` picks the currency for each slot: set the select to `settings.default ||
|
||
settings.currencies[0]` when the slot has a choice, otherwise hide the select and show the unit
|
||
span with `sats` or `kr`. The `value` slot always shows `kr` and the `fee` slot always shows
|
||
`sats`. `fillTypes()` adds the `transfer_in` option with `disabled = true`, so a generated
|
||
transfer can be displayed while never being selectable.
|
||
|
||
`FEE_TAKEN_ON_TOP` gains `transfer_out`, matching `ledger.FEE_ADDS_TO_CONSUMPTION`. `payload()`
|
||
always sends `fee_sats` and never `fee_currency` or `fee_ore`. `fill()` drops its `fee_currency`
|
||
branch.
|
||
**Verify:** walk through every type: each one shows exactly the fields of the owner's list, the
|
||
unit is plain text wherever there is only one choice, Handel opens with `sats` on Kjøp and `kr`
|
||
on Salg/kostnad, and a saved transfer shows `Sendt` and `INN` as the same number with no Avgift.
|
||
|
||
### 54. `static/transactions.html`
|
||
Rename the column heading `Pris` to `Bitcoin pris`.
|
||
**Verify:** the heading sits between `Til konto` and `Inn`.
|
||
|
||
### 55. `static/report.js`
|
||
The `Forvaltningskostnad` figure shows kroner from `totals.admin_cost_ore`, and the sats line
|
||
goes away.
|
||
**Verify:** the report shows one Forvaltningskostnad figure, in kroner.
|
||
|
||
## Phase B4 — kroner on an account, and the bank (steps B4.1-B4.9)
|
||
|
||
The owner's third review round. Kroner can live on an account as a derived balance, kroner can
|
||
move between accounts, and the costs are paid from a fictional bank account so that no real
|
||
account is touched. The steps are lettered on purpose: Phase C and Phase D keep their numbers.
|
||
|
||
### B4.1 `docs/spec.md`, `docs/TODO.md`
|
||
Fold the approved text in: the new §3.11, and the lines that change in §3.2, §3.10, §4, §4.1,
|
||
§5.2, §7.3, §7.4, §7.6, §8 and §13, plus this phase and the decisions D28-D32.
|
||
**Verify:** the spec reads consistently, and Phase C still starts at 56 and Phase D at 72.
|
||
|
||
### B4.2 `database.py`
|
||
Seed the bank account next to the settings and the rates: one `markets` row named `Bank` with
|
||
`kind = 'other'`, `taxable = 0` and `archived = 1`, and the setting `bank_market_id` pointing at
|
||
it. Both with `INSERT OR IGNORE`, so a second run changes nothing.
|
||
**Verify:** a fresh database has exactly one `Bank` row and a `bank_market_id`; a second run adds
|
||
nothing.
|
||
|
||
### B4.3 `validation.py`
|
||
A `transfer_out` carries exactly one of `leg_out_sats` and `leg_out_ore`; `Til` is required when
|
||
the amount is in sats and may be empty when it is in kroner. `admin_cost` is sent as `leg_out_ore`
|
||
only: the server fills `market_id` (the bank) and the matching `leg_in_ore`, and the taxable flag
|
||
defaults to ticked.
|
||
**Verify:** eight payloads, clean and rejected, each with its Nynorsk message.
|
||
|
||
### B4.4 `ledger.py`
|
||
`kroner_in_market(market_id, date)`, and a refusal in `rebuild()` that names the kroner shortfall;
|
||
a `transfer_out` that carries kroner consumes no lots and mirrors none.
|
||
**Verify:** the unit tests, plus a hand check of a filled account, an over-drawn one, and one that
|
||
sold sats first.
|
||
|
||
### B4.5 `app.py`
|
||
`_sync_transfer_pair()` mirrors `leg_out_ore` for a kroner transfer and writes no pair when `Til`
|
||
is empty; `_write_transaction()` fills the bank and the second leg of an `admin_cost`;
|
||
`GET /api/markets` carries `kroner_ore` and leaves the bank out.
|
||
**Verify:** `curl` a kroner transfer in, a withdrawal, an over-drawn one and a
|
||
`Forvaltningskostnad`.
|
||
|
||
### B4.6 `tax.py`, `export.py`
|
||
Nothing taxable changes: the cost line stays `admin_cost_ore` from the kroner out of the bank, the
|
||
bank is in no figure, and no CSV column is added.
|
||
**Verify:** the suite, and that a kroner transfer moves no figure in the report.
|
||
|
||
### B4.7 `static/transaction.html`, `static/transaction.js`
|
||
The currency choice on `Sendt` (sats/kr) and an empty `Til` allowed for kroner.
|
||
**Verify:** in the browser, a kroner transfer, a withdrawal, and the refusal message.
|
||
|
||
### B4.8 `static/markets.html`, `static/markets.js`
|
||
A `Kroner` column, for the real accounts only.
|
||
**Verify:** the balance is shown, it drops when kroner are transferred out, and it rises when they
|
||
arrive.
|
||
|
||
### B4.9 `tests/test_ledger.py`, `tests/test_tax.py`
|
||
The kroner balance, the refusals, the bank's two legs leaving it at zero, and that no tax figure
|
||
moves.
|
||
**Verify:** `python3 -m unittest discover -s tests -v` — green.
|
||
|
||
## Phase B5 — corrections to the kroner model (steps B5.1-B5.6)
|
||
|
||
The owner's fourth review round. Kroner are not moved between two real accounts: they go in and
|
||
out through the bank, which is a real side of the transfer and is visible in the list. `Til` is
|
||
always required, the empty-`Til` withdrawal goes away, and a buy must have the kroner. The steps
|
||
are lettered on purpose: Phase C and Phase D keep their numbers.
|
||
|
||
### B5.1 `docs/spec.md`, `docs/TODO.md`
|
||
Fold the corrections in: §3.11 (the bank as a side of a kroner transfer, `Til` always required,
|
||
the buy refused when the kroner do not cover it), §7.3, §7.4, §8 and the decisions D33-D35, plus
|
||
this phase.
|
||
**Verify:** the spec reads consistently and Phase C still starts at 56.
|
||
|
||
### B5.2 `static/transaction.js`
|
||
Fix the regression from B4.7: the listener on the outgoing currency called `applyType()`, which
|
||
set the select back to the default of the type, so `Salg/kostnad` on Handel could never be
|
||
changed to sats. Only the parts that depend on the currency are refreshed (`syncDestination()`).
|
||
**Verify:** in the browser, Handel lets `Salg/kostnad` be switched between kr and sats and the
|
||
choice stays.
|
||
|
||
### B5.3 `validation.py`
|
||
A kroner `transfer_out` must have the bank on exactly one side: as `market_id` (a deposit) or as
|
||
`to_market_id` (a withdrawal). Kroner between two real accounts are rejected, `to_market_id` is
|
||
always required, and a sats transfer may not name the bank. `validation` learns the bank id as a
|
||
parameter.
|
||
**Verify:** six payloads, clean and rejected, each with its Nynorsk message.
|
||
|
||
### B5.4 `ledger.py`
|
||
Refuse a `trade` buy that overdraws the kroner balance, with the same message as a transfer.
|
||
**Verify:** the unit tests, plus a hand check of a buy that overdraws and one that a deposit
|
||
covers.
|
||
|
||
### B5.5 `app.py`
|
||
Allow the bank as the `market_id` or the `to_market_id` of a kroner `transfer_out` (and keep it
|
||
refused everywhere else), drop the branch that wrote no pair, and let `GET /api/markets` carry
|
||
the bank with `bank: true` and `kroner_ore`.
|
||
**Verify:** `curl` a withdrawal to the bank, a deposit from it, kroner between two real accounts
|
||
(refused), and a `Forvaltningskostnad`.
|
||
|
||
### B5.6 `static/transaction.html`, `static/transaction.js`, tests
|
||
Offer the bank in `Til` and in `Marknad` only for a kroner `Overføring ut`, drop the withdrawal
|
||
hint, and update the tests for the new rules.
|
||
**Verify:** in the browser, a withdrawal and a deposit; then
|
||
`python3 -m unittest discover -s tests -v` — green.
|
||
|
||
## Phase C — StartOS package (steps 56-71)
|
||
|
||
### 56. `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.
|
||
|
||
### 57. `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.
|
||
|
||
### 58. `Makefile`
|
||
The packaging targets of the StartOS template, pointing at `startos/index.ts`.
|
||
**Verify:** `make` produces `skuld.s9pk`.
|
||
|
||
### 59. `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.
|
||
|
||
### 60. `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.
|
||
|
||
### 61. `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.
|
||
|
||
### 62. `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.
|
||
|
||
### 63. `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.
|
||
|
||
### 64. `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.
|
||
|
||
### 65. `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.
|
||
|
||
### 66. `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.
|
||
|
||
### 67. `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.
|
||
|
||
### 68. `.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.
|
||
|
||
### 69. `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.
|
||
|
||
### 70. `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, that amounts are
|
||
shown in sats and whole kroner, that a fee is in sats, 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.
|
||
|
||
### 71. `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 amounts are sats and whole
|
||
kroner, that a fee is sats only, that `docs/spec.md` outranks this plan, and the build and test
|
||
invocations.
|
||
**Verify:** it contradicts nothing in `docs/spec.md`.
|
||
|
||
## Phase D — verification
|
||
|
||
### 72. 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. Every BTC quantity must read as whole sats with spaces, and
|
||
every kroner figure as whole kroner.
|
||
5. Enter a buy of 1 000 sats for 10 kr and confirm `Bitcoin pris` reads `1 000 000 kr` on
|
||
`/transaksjonar`.
|
||
6. Make a transfer of 100 000 sats with a 1 000 sats fee: `Sendt` and `INN` are both 100 000, the
|
||
fee shows on the `transfer_out` only, and both rows carry the same `Bitcoin pris`.
|
||
7. Enter a Forvaltningskostnad: no account, no fee section, a kroner amount, its own line in the
|
||
report and the CSV.
|
||
8. Create a child account with the exchange as custodian and confirm the `TOT` row and the
|
||
exclusion from the totals.
|
||
9. Edit a transfer and then delete it: the lots and the report must return to their earlier
|
||
state.
|
||
10. Back up, restore, and confirm the figures are identical.
|
||
11. 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.
|