LocalAuthority
/
agents.md
Newer
■
■
■
■
■
■
■
■
■
■
Older
64 lines
|
3.772kb
| 1 |
# Agent Notes |
|
| 2 | ||
| 3 |
Madagascar Local Authority is the local authority application for the Madagascar network. |
|
| 4 | ||
| 5 |
Start with these documents: |
|
| 6 | ||
| 7 |
- [README.md](README.md) - current repository, deployment model, runtime paths, GitPrep remote. |
|
| 8 |
- [.doc/database/](.doc/database/README.md) - SQLite runtime store schema, table docs, seed rules, backup and restore. |
|
| 9 |
- [.doc/host-manager.md](.doc/host-manager.md) - application behavior, OTP, Work Orders, local CA, registry rules. |
|
| 10 |
- [.doc/local-hosts.md](.doc/local-hosts.md) - local DNS rules, resolver sync, source priority. |
|
| 11 |
- [.doc/development-log.md](.doc/development-log.md) - development log index with component logs under `.doc/development-logs/`. |
|
| 12 | ||
| 13 |
Operational rules: |
|
| 14 | ||
| 15 |
- Develop in this checkout: `/Users/bogdan/Documents/Workspaces/Xdev/Madagascar/LocalAuthority`. |
|
| 16 |
- Canonical git remote is GitPrep: `git@192.168.2.102:repositories/bogdan/LocalAuthority.git`. |
|
| 17 |
- Jumper is the runtime/deployment target, not the primary editing location. |
|
| 18 |
- Development work must be committed locally before testing or archiving; do not leave useful changes as forgotten dirty working-tree state. |
|
| 19 |
- Push committed code to `jumper-runtime` for live testing on jumper. |
|
| 20 |
- Push committed code to `origin`/GitPrep for archival/canonical history. |
|
| 21 |
- `scripts/deploy_to_jumper.sh` is available for explicit rsync deploys, but the normal development loop is commit plus push. |
|
| 22 |
- Agent work is not complete while there are uncommitted local changes, local commits not pushed to both `jumper-runtime` and `origin`, or a jumper `BUILD` that does not match the intended commit. |
|
| 23 |
- Before ending a change task, verify `git status -sb`, `git ls-remote origin refs/heads/main`, `git ls-remote jumper-runtime refs/heads/main`, and `ssh jumper.madagascar.xdev.ro 'cat /usr/local/xdev-host-manager/BUILD'`. |
|
| 24 |
- If `git push jumper-runtime HEAD:main` is blocked by dirty tracked files on jumper, inspect and compare the jumper diff before clearing it. Only reset or remove jumper files after confirming the changes are already represented by the commit being pushed or after saving a backup patch under `/usr/local/xdev-host-manager/backups/`. |
|
| 25 |
- Do not report success until the same commit is visible locally, in GitPrep, in `jumper-runtime`, and in the served build badge/`BUILD`, unless the user explicitly asks to stop before deploy or archive. |
|
| 26 |
- Runtime registry and Work Orders live in `var/host-manager.sqlite` on jumper. |
|
| 27 |
- Do not deploy `config/` unless the user explicitly asks to replace seed/snapshot/export files. |
|
| 28 |
- Treat `config/hosts.yaml`, `config/local-hosts.tsv`, and `config/work-orders.yaml` as compatibility exports/seeds, not the live source of truth. |
|
| 29 |
- Do not install npm, pip, or CPAN packages directly on hosts. Distribution packages are acceptable when needed. |
|
| 30 |
- Perl from the distribution and core/distribution modules are allowed. |
|
| 31 |
- CPAN modules are allowed only after requesting an audit and RPM packaging for the local audited repository. |
|
| 32 |
- Secrets live outside git, mainly under `/etc/xdev/host-manager.env` on jumper. |
|
| 33 |
- UI flows that can lead to a save must verify authentication before the user starts editing, before tab/section changes, and again before submit/save. If authentication is missing or expired, return to login without discarding in-progress form data. |
|
| 34 | ||
| 35 |
Before code changes: |
|
| 36 | ||
| 37 |
```bash |
|
| 38 |
git status --short |
|
| 39 |
``` |
|
| 40 | ||
| 41 |
Before deployment: |
|
| 42 | ||
| 43 |
```bash |
|
| 44 |
perl -c scripts/host_manager.pl |
|
| 45 |
perl -c scripts/mdns_host_seed.pl |
|
| 46 |
``` |
|
| 47 | ||
| 48 |
Normal live-test deployment after a committed change: |
|
| 49 | ||
| 50 |
```bash |
|
| 51 |
git push jumper-runtime HEAD:main |
|
| 52 |
``` |
|
| 53 | ||
| 54 |
Archive/canonical push: |
|
| 55 | ||
| 56 |
```bash |
|
| 57 |
git push origin main |
|
| 58 |
``` |
|
| 59 | ||
| 60 |
After deployment, verify: |
|
| 61 | ||
| 62 |
```bash |
|
| 63 |
ssh jumper.madagascar.xdev.ro 'systemctl is-active host-manager && curl -fsS http://127.0.0.1:8088/healthz >/dev/null' |
|
| 64 |
``` |