docs: add the second correction phase and renumber the plan
This commit is contained in:
1 parent
fdf1631b01
commit
02c4420083
1 file changed
+150
-160
+150
-160
@@ -25,7 +25,7 @@ a later project; the only concession to it is that the DDL lives in `schema.sql`
|
||||
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 B2 must be finished before Phase C starts.
|
||||
- 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).
|
||||
|
||||
@@ -52,7 +52,14 @@ a later project; the only concession to it is that the DDL lives in `schema.sql`
|
||||
| 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 now refuses one |
|
||||
| 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 |
|
||||
|
||||
## Phase A — application core (steps 1-16) — DONE
|
||||
|
||||
@@ -67,165 +74,144 @@ Implemented and committed: `static/style.css`, `static/session.js`, `static/app.
|
||||
page pairs `login.*`, `index.*`, `transactions.*`, `transaction.*`, `markets.*`, `report.*` and
|
||||
`settings.*`.
|
||||
|
||||
## Phase B2 — corrections the owner asked for (steps 27-44)
|
||||
## Phase B2 — first round of corrections (steps 27-44) — DONE
|
||||
|
||||
Do these before Phase C. They change the ledger schema, the field set of one transaction type,
|
||||
the way amounts are shown, and add one derived figure. Nothing here is optional, and nothing
|
||||
here may spill into Phase C.
|
||||
Sats everywhere, whole kroner in the display, the `Bitcoin pris` figure, `admin_cost` off the
|
||||
accounts, and no fee for `gift_received`.
|
||||
|
||||
### 27. `schema.sql`
|
||||
Change `transactions.market_id` from `INTEGER NOT NULL REFERENCES markets(id)` to
|
||||
`INTEGER REFERENCES markets(id)`, with a comment that it is null only for `admin_cost`. Add the
|
||||
two CHECK constraints of `docs/spec.md` §4: `(type = 'admin_cost' OR market_id IS NOT NULL)` and
|
||||
`(type NOT IN ('gift_received', 'admin_cost') OR (fee_sats = 0 AND fee_ore = 0))`. `lots` keeps
|
||||
its `NOT NULL`.
|
||||
**Verify:** on a fresh database, an `INSERT` of an `admin_cost` row without a market succeeds,
|
||||
the same insert for a `trade` fails, and an `admin_cost` with a fee fails.
|
||||
## Phase B3 — second round of corrections (steps 45-55)
|
||||
|
||||
### 28. `rates.py`
|
||||
Replace `parse_btc_to_sats(text)` with `parse_sats(text)`: whole sats only, space, narrow space
|
||||
and non-breaking space allowed as thousands separators, a decimal separator rejected with
|
||||
`ValueError`. Replace `ore_to_nok(ore)` with `kroner_whole(ore)`: whole kroner, halves rounded
|
||||
up, grouped with spaces, no unit and no decimals. Delete `sats_to_btc()`. Keep `nok_to_ore`,
|
||||
`group_int`, `SATS_PER_BTC`, `ORE_PER_NOK` and the rate functions untouched.
|
||||
**Verify:** `parse_sats("1 500 000") == 1500000`, `parse_sats("1500000") == 1500000`,
|
||||
`parse_sats("0,5")` raises, `kroner_whole(106037489) == "1 060 375"`.
|
||||
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.
|
||||
|
||||
### 29. `validation.py`
|
||||
`validate_sats` uses `rates.parse_sats` and its messages talk about sats: "Antal må fyllast ut.",
|
||||
"Antal må vere eit heiltal i sats.", "Antal må vere større enn null." `_ALLOWED_LEGS` for
|
||||
`admin_cost` becomes `("leg_out_sats",)` and `_REQUIRED["admin_cost"]` becomes
|
||||
`(("leg_out_sats", "Fyll ut kostnaden i sats."),)`. `_check_admin_cost` requires exactly one
|
||||
`leg_out_sats` and rejects `leg_out_ore`. `validate_transaction` must not require an account for
|
||||
`admin_cost` (store `market_id` as `None`), must still require one for every other type, must
|
||||
reject a fee for `admin_cost` and `gift_received`, and must default the taxable flag to 1 for
|
||||
`admin_cost` since there is no account to take it from.
|
||||
**Verify:** a manual check that an `admin_cost` payload without `market_id` validates clean, and
|
||||
that the same payload with `leg_out_ore` gives a Nynorsk error on `leg_out_sats`.
|
||||
### 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.
|
||||
|
||||
### 30. `ledger.py`
|
||||
Remove `admin_cost` from `CONSUMING_TYPES`. Rename the derived field of `_lot_view` from
|
||||
`nok_per_btc_ore` to `btc_price_ore` (`docs/spec.md` §8), keeping the arithmetic identical.
|
||||
**Verify:** `python3 -m unittest discover -s tests -v`; an `admin_cost` row leaves every lot
|
||||
untouched after `ledger.rebuild()`.
|
||||
`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`.
|
||||
|
||||
### 31. `tax.py`
|
||||
Add `btc_price_ore(tx)`: the bitcoin price of `docs/spec.md` §7.3 as øre per whole BTC, or
|
||||
`None`. The kroner amount is `leg_out_ore` or `leg_in_ore`; the sats amount is the sats leg; for
|
||||
`income` and `gift_received` the kroner amount is `value_ore` with the incoming sats; for
|
||||
`spend` and `loss` it is `value_ore` with the outgoing sats; `transfer_out`, `transfer_in`,
|
||||
`gift_given` and `admin_cost` give `None`. Round halves up.
|
||||
`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.
|
||||
|
||||
Handle `admin_cost` with no account: it is no longer looked up among the accounts, it is counted
|
||||
when its own `taxable` flag is set, its sats are summed into a new totals field
|
||||
`admin_cost_sats`, and `admin_cost_ore` becomes `admin_cost_sats × the year-end rate ÷ 10^8`
|
||||
when `deduct_admin_costs` is on and `0` otherwise. Keep every other figure as it is.
|
||||
**Verify:** the golden price case — a buy of 1 000 sats for 10 kr gives
|
||||
`btc_price_ore == 100000000` (1 000 000 kr) — and `report(2024)` still returns every field of §6.
|
||||
### 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`.
|
||||
|
||||
### 32. `export.py`
|
||||
`JOIN markets m ON m.id = t.market_id` becomes `LEFT JOIN` in `transactions_csv`. Rename `_btc()`
|
||||
to `_sats()` and use `rates.group_int`; make `_amount()` use `rates.kroner_whole`. Headings
|
||||
become `Antall inn (sats)`, `Antall ut (sats)`, `Avgift (sats)`, `Antall (sats)` and
|
||||
`Antall (sats)` for the TOT block. Add a `Pris (kr)` column to the transaction block, after
|
||||
`Til konto`, carrying `tax.btc_price_ore(row)`. Change the report line
|
||||
`Forvaltningskostnad (kr)` into `Forvaltningskostnad (sats)` from `admin_cost_sats`, and keep a
|
||||
`Forvaltningskostnad (kr)` line from `admin_cost_ore`.
|
||||
**Verify:** download the CSV for a year with an `admin_cost` row and open it; the row is present,
|
||||
the price column is filled for the trades, and no cell carries a decimal.
|
||||
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.
|
||||
|
||||
### 33. `app.py`
|
||||
Make the account join a `LEFT JOIN markets m ON m.id = t.market_id` in `_load_transaction` and
|
||||
in `transactions_list`, so a row with no account is not dropped. Add `btc_price_ore` to both
|
||||
payloads by calling `tax.btc_price_ore`. Confirm that `transactions_get` builds no candidate
|
||||
lots for `admin_cost`, which step 30 should already have settled.
|
||||
**Verify:** `GET /api/transactions` returns the `admin_cost` row with `market_id: null`,
|
||||
`market_name: null` and `btc_price_ore: null`, and a buy returns the golden price.
|
||||
### 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.
|
||||
|
||||
### 34. `tests/test_ledger.py`
|
||||
Update the fixtures to whole sats and the renamed lot field. Add: an `admin_cost` transaction
|
||||
consumes nothing and leaves `holdings_at` unchanged; a rebuild after it still produces the same
|
||||
lots.
|
||||
`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.
|
||||
|
||||
### 35. `tests/test_tax.py`
|
||||
Update the fixtures and add: an `admin_cost` with `market_id` null and `taxable = 1` lands in
|
||||
`admin_cost_sats` and leaves every account row untouched; `admin_cost_ore` is 0 with the setting
|
||||
off, and the sats converted at the year-end rate with it on; `btc_price_ore` for the golden case
|
||||
(1 000 sats for 10 kr → 1 000 000 kr) and for a sale (sats out, kroner in); `btc_price_ore` is
|
||||
None for `transfer_out` and `admin_cost`.
|
||||
### 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.
|
||||
|
||||
### 36. `static/app.js`
|
||||
`formatSats(sats)` returns the grouped whole number of sats and nothing else, and its doc comment
|
||||
says so. `formatKroner(ore)` returns whole kroner with spaces and the unit, rounding halves up,
|
||||
with no decimals. `formatOre(ore)` stays exactly as it is and stays exported: it is what fills a
|
||||
form from a stored value. `parseSats(text)` parses whole sats with spaces allowed and returns
|
||||
null for anything carrying a decimal separator.
|
||||
**Verify:** in the browser console, `Skuld.formatSats(1500000)` is `"1 500 000"`,
|
||||
`Skuld.formatKroner(106037489)` is `"1 060 375 kr"`, `Skuld.formatOre(123450)` is
|
||||
`"1 234,50"`, and `Skuld.parseSats("1 500 000")` is `1500000`.
|
||||
### 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.
|
||||
|
||||
### 37. `static/transactions.html`
|
||||
Add `<th class="numeric">Pris</th>` between the `Til konto` and `Inn` headings.
|
||||
**Verify:** the list renders with the new column in the right place.
|
||||
### 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}`.
|
||||
|
||||
### 38. `static/transactions.js`
|
||||
`amount()` returns `Skuld.formatSats(sats) + " sats"` instead of `" BTC"`. Add the `Pris` cell
|
||||
between the `Til konto` and `Inn` cells, showing `Skuld.formatKroner(transaction.btc_price_ore)`
|
||||
or an empty string.
|
||||
**Verify:** a buy shows its price, a transfer shows an empty cell, and every sats cell ends in
|
||||
`sats`.
|
||||
`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.
|
||||
|
||||
### 39. `static/transaction.html`
|
||||
Rename the lot table heading `Kostnad per BTC` to `Bitcoin pris`. Give the Marknad field a
|
||||
`data-group="market"` wrapper so it can be hidden, and do the same for the whole Avgift
|
||||
`fieldset` with `data-group="fee"`.
|
||||
**Verify:** the form still renders, and nothing else moved.
|
||||
`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.
|
||||
|
||||
### 40. `static/transaction.js`
|
||||
In `TYPE_FIELDS`: `admin_cost` becomes `out: {label: "Kostnad", currencies: ["sats"]}` with
|
||||
`consumes: false`, `market: false` and `fee: false`; `gift_received` gets `fee: false`. Every
|
||||
other type gets `market: true, fee: true`. `applyType()` hides the market group and the fee
|
||||
group when the type says so, sets the `market_id` select's `required` flag to match (a hidden
|
||||
required field blocks the submit), and clears the value it hides. `payload()` sends
|
||||
`market_id: null` for `admin_cost`. Keep `Skuld.formatOre` for the NOK inputs and use
|
||||
`Skuld.parseSats` for the sats inputs and the lot amounts, which are now whole sats. Rename the
|
||||
`nok_per_btc_ore` reads in `autoPick` and `buildLotRow` to `btc_price_ore`.
|
||||
**Verify:** choose Forvaltningskostnad: the Marknad and Avgift sections disappear, the Valuta
|
||||
selector is gone and fixed to sats, and saving writes a row with no account. Choose Gåve
|
||||
(motteke): the Avgift section is gone.
|
||||
### 54. `static/transactions.html`
|
||||
Rename the column heading `Pris` to `Bitcoin pris`.
|
||||
**Verify:** the heading sits between `Til konto` and `Inn`.
|
||||
|
||||
### 41. `static/index.html`
|
||||
Change the `Antall` heading to `Antall (sats)`.
|
||||
**Verify:** the main sheet heading matches the values.
|
||||
### 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.
|
||||
|
||||
### 42. `static/report.html`
|
||||
Change all three `Antall` headings to `Antall (sats)`.
|
||||
**Verify:** the report headings match the values.
|
||||
## Phase C — StartOS package (steps 56-71)
|
||||
|
||||
### 43. `static/report.js`
|
||||
The `Forvaltningskostnad` figure shows sats:
|
||||
`Skuld.formatSats(totals.admin_cost_sats) + " sats"`, and when `totals.admin_cost_ore` is not
|
||||
zero a second figure shows the kroner that were deducted. The year-end rate line keeps
|
||||
`formatKroner`, which now prints whole kroner.
|
||||
**Verify:** a year with an `admin_cost` shows it in sats; with the setting on, the kroner line
|
||||
appears too.
|
||||
|
||||
### 44. `static/markets.html`
|
||||
Change the `Antall` heading to `Antall (sats)`. `static/markets.js` needs no change: it already
|
||||
calls `Skuld.formatSats`, which now prints sats.
|
||||
**Verify:** the account table shows whole sats with spaces.
|
||||
|
||||
## Phase C — StartOS package (steps 45-60)
|
||||
|
||||
### 45. `package.json`, `tsconfig.json`, `.prettierrc`
|
||||
### 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.
|
||||
|
||||
### 46. `Dockerfile`, `.dockerignore`
|
||||
### 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`.
|
||||
@@ -234,48 +220,48 @@ No packages installed: the app is standard library only.
|
||||
`docker run --rm -e PORT=8080 -e DATABASE_PATH=/tmp/s.sqlite3 skuld-test python3 -c "import app"`
|
||||
exits 0.
|
||||
|
||||
### 47. `Makefile`
|
||||
### 58. `Makefile`
|
||||
The packaging targets of the StartOS template, pointing at `startos/index.ts`.
|
||||
**Verify:** `make` produces `skuld.s9pk`.
|
||||
|
||||
### 48. `icon.svg`
|
||||
### 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.
|
||||
|
||||
### 49. `startos/sdk.ts`, `startos/utils.ts`
|
||||
### 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.
|
||||
|
||||
### 50. `startos/manifest/index.ts`, `startos/manifest/i18n.ts`
|
||||
### 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.
|
||||
|
||||
### 51. `startos/versions/index.ts`
|
||||
### 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.
|
||||
|
||||
### 52. `startos/interfaces.ts`, `startos/backups.ts`, `startos/dependencies.ts`
|
||||
### 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.
|
||||
|
||||
### 53. `startos/i18n/index.ts`, `startos/i18n/dictionaries/nb_NO.ts`
|
||||
### 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.
|
||||
|
||||
### 54. `startos/actions/index.ts`, `startos/actions/setAdminPassword.ts`, `startos/actions/deleteAllData.ts`
|
||||
### 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.
|
||||
|
||||
### 55. `startos/init/index.ts`, `startos/init/requireAdmin.ts`
|
||||
### 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`
|
||||
@@ -283,18 +269,18 @@ 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.
|
||||
|
||||
### 56. `startos/main.ts`
|
||||
### 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.
|
||||
|
||||
### 57. `.github/workflows/build.yml`
|
||||
### 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.
|
||||
|
||||
### 58. `README.md`
|
||||
### 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,
|
||||
@@ -302,22 +288,24 @@ health checks, backups and restore, limitations and differences, and a quick ref
|
||||
AI consumers.
|
||||
**Verify:** every claim in it matches `startos/` and the Dockerfile.
|
||||
|
||||
### 59. `instructions.md`
|
||||
### 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, and that Skuld gives figures, not tax advice.
|
||||
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.
|
||||
|
||||
### 60. `AGENTS.md`
|
||||
### 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 `docs/spec.md` outranks this plan, and the build and test invocations.
|
||||
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
|
||||
|
||||
### 61. Build, install and run through
|
||||
### 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,
|
||||
@@ -325,16 +313,18 @@ kroner, that `docs/spec.md` outranks this plan, and the build and test invocatio
|
||||
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 `Pris` reads `1 000 000 kr` on
|
||||
5. Enter a buy of 1 000 sats for 10 kr and confirm `Bitcoin pris` reads `1 000 000 kr` on
|
||||
`/transaksjonar`.
|
||||
6. Enter a Forvaltningskostnad and confirm it has no account, no fee section, and its own line in
|
||||
the report and the CSV.
|
||||
7. Create a child account with the exchange as custodian and confirm the `TOT` row and the
|
||||
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.
|
||||
8. Do a transfer between two accounts, edit it, and delete it: the lots and the report must return
|
||||
to their earlier state.
|
||||
9. Back up, restore, and confirm the figures are identical.
|
||||
10. Download the CSV and open it in a spreadsheet.
|
||||
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
|
||||
|
||||
|
||||
Reference in new issue
Block a user