Soften updater stub messaging (no error)

PLAN.md

@@ -0,0 +1,77 @@
+# Pi-Kit Updater Plan
+
+## Goals
+- Add seamless in-dashboard updates for Pi-Kit assets (web UI, api script, helper scripts).
+- Allow manual check/apply + rollback; optional daily auto-check with a status chip.
+- Use release tarballs (not git clones) from Gitea; verify hashes; stage before swap; keep one backup.
+- Keep UX friendly: clear progress, errors, and “update available” indicator.
+
+## Release Format (Gitea)
+- Release asset: `pikit-<version>.tar.gz` containing:
+  - `pikit-web/` (built assets only, no node_modules)
+  - `pikit-api.py`
+  - helper scripts/configs that should overwrite
+  - `manifest.json` (see below)
+- `manifest.json` fields:
+  - `version` (string)
+  - `changelog` (url)
+  - `files`: array of { `path`, `sha256`, `mode`? }
+  - `post_install` (optional array of commands or service restarts)
+- Optional: detached signature in future (ed25519), not in v1.
+
+## On-device Updater (Python helper)
+- Location: `/usr/local/bin/pikit-updater.py` (invoked by API and timer).
+- State file: `/var/lib/pikit-update/state.json` (latest, current, last_check, last_result, progress, backup_path).
+- Steps for apply:
+  1) Fetch manifest (HTTP GET release URL).
+  2) Download tarball to `/var/tmp/pikit-update/<version>/bundle.tar.gz`.
+  3) Verify SHA256 against manifest.
+  4) Unpack to staging dir.
+  5) Backup current managed files to `/var/backups/pikit/<ts>/` (keep 1 latest).
+  6) Rsync staged files to destinations:
+     - `/var/www/pikit-web/` (built assets)
+     - `/usr/local/bin/pikit-api.py`
+  7) Restart services: `dietpi-dashboard-frontend`, api service (if exists), maybe nginx reload.
+  8) Update state; mark current version file `/etc/pikit/version`.
+- Rollback: restore latest backup and restart services.
+- Concurrency: use lockfile in `/var/run/pikit-update.lock`.
+
+## API additions (pikit-api.py)
+- `GET /api/update/status` -> returns state.json contents + current version.
+- `POST /api/update/check` -> fetch manifest only, update state.
+- `POST /api/update/apply` -> spawn updater apply (can run inline for v1) and stream status.
+- `POST /api/update/rollback` -> restore last backup.
+- `POST /api/update/auto` -> enable/disable daily timer.
+
+## Timer
+- systemd timer: `pikit-update.timer/service` running check daily (e.g., 04:20).
+- Writes last_check and latest_version to state.
+
+## UI changes (pikit-web)
+- Top-bar chip: “Updates: Up to date / Update available / Checking…”.
+- New “Updates” modal (not the OS auto-updates) for Pi-Kit releases:
+  - Show current vs latest version, changelog link.
+  - Buttons: Check, Download & Install, Rollback, View logs.
+  - Progress states + errors.
+- Hook into existing status refresh: call `/api/update/status`.
+
+## Safety / Edge
+- Preflight disk space check before download.
+- Handle offline: clear message.
+- If apply fails, auto rollback.
+- Skip overwriting user-edited config? For v1 assume assets/api are managed; nginx site left unchanged.
+
+## Implementation steps
+1) Add current version markers (maybe file in repo, read by UI).
+2) Implement updater helper script with check/apply/rollback + state.
+3) Add systemd service/timer units template (install script TBD, for now keep files in repo).
+4) Extend `pikit-api.py` with new endpoints calling updater functions.
+5) Extend UI (status chip + modal) and wire to API.
+6) Add mock responses for dev (mock-update-status.json).
+7) Test locally (mock) and on device (manual apply pointing to a dummy URL or skip download logic for now).
+
+## Open questions / assumptions
+- Release hosting: use Gitea releases at `https://git.44r0n.cc/44r0n7/pi-kit/releases/latest` (JSON API? or static URLs). For v1, hardcode base URL env var or config.
+- Services to restart: assume `dietpi-dashboard-frontend` and `pikit-api` (if we add a service file). Need to verify actual service names on device.
+- Device perms: updater runs as root (via sudo from API). Ensure API endpoint requires auth (existing login).
+