Files
vardkey/AGENTS.md
T

86 lines
5.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Working in this repository
This repository holds **both** the VardKey application and its StartOS package, side by side at the
repository root. The application is the Python source at the top level (`app.py`, `database.py`,
`alerts.py`, `export.py`, `validation.py`, `auth.py`, `maintenance.py`, `secret_guard.py`,
`static/`, `tests/`); the package is `startos/` together with the `Dockerfile`, `Makefile`,
`package.json`, `tsconfig.json`, and the rest of the StartOS skeleton.
## Repository mechanics
- **The package repo is also the application repo.** The packaging guide says a package repo is not
a fork of the application. That rule assumes a published upstream image or a git submodule, and
VardKey has neither — it is our own application and publishes no image — so the package builds
the application from this repository's root. **Do not add an `upstream-project/` submodule to
"fix" this**; it would point at this same repository and break the build.
- **There is no CI.** The packaging guide assumes GitHub Actions workflows. This repository is on
Gitea, so there are no `.github/workflows/` and there must not be any. Build the `.s9pk` locally
with `make`.
- **The image is built by `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. The `COPY *.py ./` line is what keeps a new
module from being left out; see the traps in `ai-note.md`.
- **The application is pure Python standard library.** There is no `requirements.txt` and no
package-installation step in the image.
- **The package version is date based.** It lives in `startos/versions/current.ts` as
`YYYY.MM.DD:revision`, and the bump edits `version` and `releaseNotes` in place — `index.ts` and
the `current` export never change, and `startos/versions/` stays otherwise empty because the
application migrates its own schema. `UPDATING.md` carries the rule, including the trap that
ExVer normalizes numeric leading zeros, so a single-digit month or day is written without one
(`2026.1.5`, not `2026.01.05`). The git tag is the version with `:` replaced by `_` and a leading
`v` (`v2026.10.28_0`), pushed individually.
- **The admin account is touched outside the HTTP API only by `maintenance.py`.** The two StartOS
actions, `delete-all-data` and `set-admin-password`, run it in a `withTemp` subcontainer, and the
generated password never travels from the host into the container, as an argument or on stdin:
`maintenance.py` generates it inside the container and prints the credentials back. The task that
asks the user to set the password is raised and cleared by `startos/init/requireAdmin.ts`, which
is registered in `sdk.setupInit()` after the actions; on the box it shows as *recommended*, so it
does not hold the service back. Its probe fails open.
## Things that look right and are not
- **Do not add a `USER` line to the `Dockerfile`.** The `main` volume is mounted at `/data` and
must be writable without a `chown`; dropping privileges in the image makes the SQLite database
unwritable.
- **`static/` must be `COPY`ed into the image.** `app.py` answers `/health` from code, but every
page and asset is read from `ROOT/static`. Leave it out and the health check goes green while the
whole UI answers `404`.
- **The internal port must be the same in three places.** `startos/utils.ts` holds `uiPort`;
`startos/main.ts` passes it as `PORT` to the daemon and uses it in the readiness URL, and
`startos/interfaces.ts` binds it. Changing one alone leaves the readiness check permanently red.
- **Do not add a second container, Postgres, Redis, an external backend, or external storage for
application data.** This is a standing prohibition, not a work item — see `TODO.md` sections 1
and 13.
## Tests
```sh
python3 -m unittest discover -s tests
```
The suite is the application's regression net and does not exercise the package. It must stay
green, on Linux and on the Windows copy alike.
It also covers `secret_guard.py`, the one place that decides whether a piece of free text looks like
a wallet secret. That module is local, silent, and narrow by design: it makes no network call, never
puts the text in a log, a message, or an exception, and matches only unmistakable shapes. The
embedded BIP39 wordlist is pinned by the suite — 2048 words, alphabetical, 3–8 lower-case letters,
and no two words sharing their first four letters — and so are the shapes the guard recognises and
the shapes it deliberately does not. **Do not edit the wordlist without that test.**
## Build
```sh
make x86 # or: make arm
```
Building needs a StartOS packaging workspace — see the packaging guide's Environment Setup.
The TypeScript under `startos/` has to be formatted the way prettier would write it. The SDK's
makefile supplies prettier and defines the check as `FORMAT_CHECK` — `npx prettier --config
node_modules/@start9labs/start-sdk/prettier.config.json --check startos` — but **`make x86` does not
run it**, so run that command yourself; the `--write` form fixes the files.
`make install` needs `host.default` in the workspace `.startos/config.yaml` and one
`start-cli auth login`.