6.7 KiB
6.7 KiB
AI Agent Note — Helsesjekk
Short working handover for the next model. Keep it short.
TODO.md(Norwegian) is the requirement specification: sections 1–18 are the spec, sections 19–22 a short appendix with the four decisions taken along the way.- The binding rules live in
TODO.mdandREADME.md. This note does not repeat them — it carries the handover, the rules that are easy to get wrong, and the traps that already cost time. HANDOVER.mdwas deleted as outdated. Do not recreate it.
Status
- Done and verified: sections 19–22 and section 18 steps 1–8. All ticked in
TODO.md. - Tests: 123, all passing. The user runs them:
python3 -m unittest discover -s testsfrom/home/snes/start9/helsesjekk. - Remaining: steps 9–12 — StartOS package, persistent volume, backup/restore,
.s9pk. Covered by sections 13, 14, 16 and 17 ofTODO.md.
Ground rules
- English everywhere except
TODO.md. - Read the existing files first. Work one file at a time and finish each file before starting the next.
- Do not start a new step without asking.
- The user runs the tests and reports the result. Wait for it.
- Ask one question at a time, with concrete options.
- Never add fields for seed phrases, private keys, PINs, passwords, cloud tokens, or contact details. The app records results only.
- The HTTP tests create their own database and server per test. Keep them order-independent; a shared database already caused one order-dependent failure.
- Record a new decision in
TODO.mdand this note before implementing it, and mark it as not implemented until the tests pass. gitea_update_fileneeds a freshpreview_idfromgitea_preview_filefor the same path and content.gitea_create_filereturns422on an existing file.
Rules that are easy to get wrong — do not re-open
- One submission records one key. There is no "round" grouping, and each key's next check is its own date plus one calendar year, computed on the server and not editable in the form.
- An unavailable key records nothing else. When
availableis0,wallet_software,tool_checksandai_security_checksmust be empty; a non-empty value is a400, not something dropped silently. Nothing is stored for them, andsoftware_compatibility_statusbecomesNOT_ASSESSED. Availabilityis required and offers only Yes/No. There is no "not assessed" value for it, and the server rejects a payload without it.- Key 3 collects only
Availability. Cloud health, "provider operational" and software compatibility are all derived from it. - Security status follows the wallet software choice. For keys 1 and 2 the third provider is hidden and its last saved status carried forward, and it reappears by itself when that status was
VULNERABLEorCOMPROMISED. - BIP327 and SLIP39 are
YES/NO/NOT_ASSESSED. OnlyYESraises the informational alert; a reportedNOis a negative result and raises nothing. Address pathis only recorded whenAddress path verifiedisOK. The form enforces this; the server does not./api/alertscovers every saved check, not only the newest, and merges identical alerts bycodeplussource. A security alert'ssourceis the provider, not the key — so two keys' Nunchuk results merge into one alert, which is intended.- The export is plain CSV only. XLSX is not built and the app does not promise Excel compatibility.
- The prohibition lists in sections 1 and 13 of
TODO.mdstay unticked. They are standing prohibitions, to be re-confirmed before release. - Readable user-defined key names are not built. The section 3 item stays unticked.
- Whether a date is overdue is decided in the browser, so
/api/key-statusstays independent of the current date.
Data model (schema version 6)
health_checks:checked_at,next_check_due,wallet_software,software_version,software_compatibility_status,software_comments,contact_info_verified,comments, plus the legacysparrow_version/nunchuk_version.key_checks: one row per submission —available,hardware_works,firmware_version,seed_backup_verified,cloud_health_status,cloud_provider_operational,address_path_verified,address_path,comments.tool_checks:product,bip327_status,slip39_status. The legacyversion,checked_at,notesare kept for old rows but never written.ai_security_checks:provider,status,comments.- Startup migration rebuilds
key_checksandai_security_checkswhen they still use the old layout, and rebuildshealth_checks,key_checksandtool_checkswhen theirCHECKconstraints still allowIKKJE_VURDERT. - The table definitions are
{table}templates, so a rebuild can create the same table under a temporary name.health_checksis a parent table, so the whole migration runs withPRAGMA foreign_keys = OFF, checksPRAGMA foreign_key_checkbefore committing, and rolls back on any failure.
API
GET /health, GET /api/keys, GET /api/key-status, GET /api/health-checks, GET /api/health-checks/<id>, GET /api/alerts, GET /api/export, POST /api/health-checks. Field details are in README.md.
Two things that are easy to break:
- New static files must be added to
STATIC_FILESinapp.py, or they return404. /api/alertsand/api/key-statusare extra endpoints that are not in the minimum list in section 11. They are noted in section 11 but not in the specification itself.
Traps that already cost time — do not repeat
- A
requiredcontrol inside adisplay:nonecontainer still blocks submission. The browser refuses to submit and logs "An invalid form control is not focusable". Hiding a section is not enough: the required flags must be cleared, or the section must render something other than required fields. That is whyrenderToolChecks()andrenderSecurityChecks()show an empty note instead of cards when the key is unavailable. - Do not assert on the quoting style of the JavaScript.
static/health-check.jsuses single quotes for constant selectors and template literals where a${...}substitution is needed. Assert on the selector text, e.g.[name="address_path"]. clean_record()intests/test_alerts.pyhas a fixed provider list. A test that needs another provider must replace the entry itself.- Section 19 records one key per submission, so a
Check idin the export can cover up to three keys only for rows saved before section 19.
Product clarification
Nunchuk has two roles: it is the third key and also wallet software. Record only one Nunchuk security status per submission and only one Nunchuk BIP327/SLIP39 row. Sparrow is software only and is checked on every submission.