Record the StartOS package round in ai-note.md
This commit is contained in:
1 parent
f37e19878d
commit
c5de94b147
1 file changed
+41
-5
+41
-5
@@ -2,21 +2,57 @@
|
|||||||
|
|
||||||
Short working handover for the next model. Keep it short.
|
Short working handover for the next model. Keep it short.
|
||||||
|
|
||||||
- `TODO.md` (Norwegian) is the requirement specification. Sections 1–18 are the binding spec; sections 19–29 are short summaries of the rounds that are implemented and verified, and section 30 is the round that is decided but **not started**. The full reasoning is in the git history.
|
- `TODO.md` (Norwegian) is the requirement specification. Sections 1–18 are the binding spec; sections 19–29 are short summaries of the rounds that are implemented and verified, and section 30 is the StartOS package round. The full reasoning is in the git history.
|
||||||
- The binding rules live in `TODO.md` and `README.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.
|
- The binding rules live in `TODO.md` and `README.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.md` was deleted as outdated. Do not recreate it.
|
- `HANDOVER.md` was deleted as outdated. Do not recreate it.
|
||||||
|
|
||||||
## Status
|
## Status
|
||||||
|
|
||||||
- **Done and verified:** sections 19–29 and section 18 steps 1–8. Schema version 11. 346 green tests.
|
- **Done and verified:** sections 19–29 and section 18 steps 1–8. Schema version 11. 346 green tests.
|
||||||
- **Next work:** **Section 30 — the StartOS 0.4.0 package**, with the persistent volume, backup/restore, and the `.s9pk`. Covered by sections 13, 14, 16 and 17 of `TODO.md`. Decided and **not started**; its work items are the unchecked boxes in section 30. Do not start it before the user says so.
|
- **Section 30 is written, not built and not installed.** The StartOS package lives in this repository beside the application: `startos/`, `Dockerfile`, `.dockerignore`, `Makefile`, `package.json`, `tsconfig.json`, `.prettierrc`, `LICENSE`, `icon.svg`, `instructions.md`, `UPDATING.md`, `AGENTS.md`, `README.md`, and `CLAUDE.md`. What is left is the build, the install, and the manual tests — section 13's `Build .s9pk` and the install verification, section 14, the StartOS test in section 16, and section 17.
|
||||||
- **Section 29 is done.** The app is **VardKey**, described as **Bitcoin Multisig Health Monitor**, the database file is `data/vardkey.sqlite3`, and the export is `vardkey-export.csv`. The Gitea repo and the project id stay `ai-bot/helsesjekk`.
|
- **Section 29 is done.** The app is **VardKey**, described as **Bitcoin Multisig Health Monitor**, the database file is `data/vardkey.sqlite3`, and the export is `vardkey-export.csv`. The Gitea repo and the project id stay `ai-bot/helsesjekk`.
|
||||||
- **The decisions behind section 30 are already written into `TODO.md`.** Read them there instead of re-deriving them: the package is `id: 'vardkey'`, `title: 'VardKey'`, `volumes: ['main']`, starting at `0.1.0:0` with license `GPL-3.0-only`, and the description is shown in the StartOS manifest as well.
|
- **A round stops when it is done.** Section 30 is the round; do not roll into anything after it. In particular, do not install on a StartOS box, and do not start on anything beyond section 30.
|
||||||
- **A round stops when it is done.** Section 30 is the next round; do not roll into anything after it.
|
|
||||||
- **Verified how:** the automated suite and the user's manual browser testing. The remaining manual tests are the ones in section 16 of `TODO.md`; the StartOS test there is still open.
|
- **Verified how:** the automated suite and the user's manual browser testing. The remaining manual tests are the ones in section 16 of `TODO.md`; the StartOS test there is still open.
|
||||||
- **Tests:** the user runs them: `python3 -m unittest discover -s tests`. They run on a Windows copy at `C:\Users\<brukarnamn>\Downloads\helsesjekk`, so they must pass there as well as on Linux.
|
- **Tests:** the user runs them: `python3 -m unittest discover -s tests`. They run on a Windows copy at `C:\Users\<brukarnamn>\Downloads\helsesjekk`, so they must pass there as well as on Linux.
|
||||||
- **Future work, deliberately not built:** more than three keys, and another threshold than 2-of-3.
|
- **Future work, deliberately not built:** more than three keys, and another threshold than 2-of-3.
|
||||||
|
|
||||||
|
## Section 30 — the StartOS package
|
||||||
|
|
||||||
|
The package is one service: one daemon, one container, one SQLite database on the persistent `main` volume, mounted at `/data`. No Postgres, no Redis, no external backend, no extra container.
|
||||||
|
|
||||||
|
The decisions are recorded in `TODO.md` section 30; this is what the next model needs on top of them.
|
||||||
|
|
||||||
|
### Where the files live, and why
|
||||||
|
|
||||||
|
The application and the package share one repository, at the root. That is a deliberate deviation from the guide's "a package repo is not a fork of the application": the rule assumes a published upstream image or a git submodule, and VardKey has neither. `AGENTS.md` states the deviation so nobody adds an `upstream-project/` submodule to "fix" it.
|
||||||
|
|
||||||
|
The image is built by the root `Dockerfile`, referenced as `dockerBuild: {}` in `startos/manifest/index.ts`, which makes the build context the repository root. **Anything the `Dockerfile` does not `COPY` is not in the image.** In particular `static/` must be copied: `app.py` answers `/health` from code, but every page is read from `ROOT/static`, so an image without it reports a healthy service whose entire UI answers `404`.
|
||||||
|
|
||||||
|
There is no CI. The guide assumes GitHub Actions; this repository is on Gitea, so there are no `.github/workflows/` and there must not be any. The `.s9pk` is built locally with `make`.
|
||||||
|
|
||||||
|
### The three things that must agree
|
||||||
|
|
||||||
|
`startos/utils.ts` holds `uiPort` (8080). `startos/main.ts` passes it as `PORT` to the daemon and uses it in the readiness URL; `startos/interfaces.ts` binds it. Change one alone and the readiness check never goes green. The `DATABASE_PATH` constant in the same file is what puts the database on the volume instead of the application's own default of `data/vardkey.sqlite3` relative to the working directory.
|
||||||
|
|
||||||
|
The readiness check is `checkWebUrl` against `http://127.0.0.1:8080/health`, not `checkPortListening` — section 30 asks for the endpoint, and `/health` is the application's own.
|
||||||
|
|
||||||
|
### Backups
|
||||||
|
|
||||||
|
`startos/backups.ts` is `sdk.Backups.ofVolumes('main')`. The open question section 30 raised — whether `setupBackups` has a hook for a consistent SQLite snapshot — turned out not to need one: StartOS stops the service for the duration of a backup, so the database file is quiescent while it is copied. That is written up in `README.md` and in `startos/backups.ts`; it is not a known limitation.
|
||||||
|
|
||||||
|
### What is not verified
|
||||||
|
|
||||||
|
Nothing about this package has been run. `make` has not been invoked, no `.s9pk` exists, and no StartOS box has seen it. Treat every claim in `README.md` about runtime behaviour as intended, not observed.
|
||||||
|
|
||||||
|
Two specific things to reconcile on the first build:
|
||||||
|
|
||||||
|
- **The skeleton was written by hand.** `package.json`, `tsconfig.json`, `Makefile`, `.prettierrc`, `startos/sdk.ts`, `startos/index.ts`, `startos/actions/index.ts`, `startos/i18n/`, `startos/fileModels/.gitkeep`, and `assets/.gitkeep` were written to match the Start9 template rather than generated by `s9pk init-workspace`, because that command was not available in the environment that wrote them. Run `s9pk init-package` in a scratch directory and diff, above all the `@start9labs/start-sdk` version in `package.json` — it is pinned to the latest published release, not to whatever a current scaffold would pick.
|
||||||
|
- **The icon is a placeholder.** Section 30 defers the real `icon.svg` to the round that raises the package to `1.0.0`; a minimal placeholder sits in the repository so the build has an icon to pack.
|
||||||
|
|
||||||
|
### Documentation layout
|
||||||
|
|
||||||
|
`README.md` is now the StartOS package README, with the guide's fixed heading set. The application's own reference — the HTTP API, the alerts table, the schema history — moved to `docs/application.md`, which is what `instructions.md` links to under `## Documentation`. `AGENTS.md` is the repo-specific agent context, and `CLAUDE.md` is the one-line `@AGENTS.md` import.
|
||||||
|
|
||||||
## Sections 27 and 28 — implemented and verified
|
## Sections 27 and 28 — implemented and verified
|
||||||
|
|
||||||
What the code does now, and the parts that are easy to get wrong:
|
What the code does now, and the parts that are easy to get wrong:
|
||||||
@@ -70,7 +106,7 @@ What the code does now, and the parts that are easy to get wrong:
|
|||||||
|
|
||||||
## API
|
## API
|
||||||
|
|
||||||
Pages: `/`, `/setup`, `/settings`, `/health-check`, `/history`. Endpoints: `GET /health`, `GET /api/setup`, `POST /api/setup`, `GET /api/keys`, `GET /api/key-status`, `GET /api/previous-values`, `GET /api/settings`, `POST /api/settings/keys`, `POST /api/settings/wallet-software`, `POST /api/keys/<id>/rotate`, `GET /api/health-checks`, `GET /api/health-checks/<id>`, `GET /api/alerts`, `POST /api/alerts/acknowledge`, `GET /api/export`, `POST /api/health-checks`. Field details are in `README.md`.
|
Pages: `/`, `/setup`, `/settings`, `/health-check`, `/history`. Endpoints: `GET /health`, `GET /api/setup`, `POST /api/setup`, `GET /api/keys`, `GET /api/key-status`, `GET /api/previous-values`, `GET /api/settings`, `POST /api/settings/keys`, `POST /api/settings/wallet-software`, `POST /api/keys/<id>/rotate`, `GET /api/health-checks`, `GET /api/health-checks/<id>`, `GET /api/alerts`, `POST /api/alerts/acknowledge`, `GET /api/export`, `POST /api/health-checks`. Field details are in `docs/application.md`.
|
||||||
|
|
||||||
The rotate payload is `replaced` + `keep_name` + `name` + `type` + `address_path`, and `type` is optional. `GET /api/health-checks/<id>` also returns `closed_alerts`. The settings page has two sections, and `POST /api/settings/keys` is what a rename alone goes through.
|
The rotate payload is `replaced` + `keep_name` + `name` + `type` + `address_path`, and `type` is optional. `GET /api/health-checks/<id>` also returns `closed_alerts`. The settings page has two sections, and `POST /api/settings/keys` is what a rename alone goes through.
|
||||||
|
|
||||||
|
|||||||
Reference in new issue
Block a user