sunfish-admin
12d2179c20
Ship Magisk like GOLDEN; KernelSU optional recycle only; parallel to sunfish-a16-rom standby.
223 lines
13 KiB
Plaintext
223 lines
13 KiB
Plaintext
001 tasks review pack — for ChatGPT
|
||
Generated: 2026-08-09T12:30:10+02:00
|
||
|
||
================================================================================
|
||
FILE: specs/001-development-environment/tasks.md
|
||
================================================================================
|
||
|
||
# Tasks: Development environment on rom-dev01
|
||
|
||
**Input**: Design documents from `/specs/001-development-environment/`
|
||
|
||
**Prerequisites**: plan.md (required), spec.md, research.md, data-model.md,
|
||
quickstart.md, contracts/ (N/A)
|
||
|
||
**Tests**: Observational verify steps embedded in tasks (no separate TDD suite).
|
||
|
||
**Organization**: Setup → Foundational (preflight) → User stories by priority →
|
||
Polish. **Do not run these tasks until `rom-dev01` SSH works.** Generating this
|
||
file is documentation-only.
|
||
|
||
**Canonical paths**:
|
||
- Meta Spec Kit tree: `/home/android-build/sunfish-a16-rom`
|
||
- Data root: `/srv/rom/`
|
||
- Automation repo (after Gitea): `sunfish-rom-build` (not the meta repo)
|
||
|
||
## Format: `[ID] [P?] [Story] Description`
|
||
|
||
- **[P]**: Can run in parallel (different files, no incomplete dependencies)
|
||
- **[Story]**: US1…US5 from spec.md
|
||
- Every task includes a path and an observable verify hint
|
||
|
||
## Path Conventions
|
||
|
||
Host paths are absolute on `rom-dev01`. Docs/logs also land under
|
||
`/home/android-build/sunfish-a16-rom/docs/` or `/srv/rom/logs/` as noted.
|
||
|
||
---
|
||
|
||
## Phase 1: Setup (docs readiness — can be done on laptop before VM)
|
||
|
||
- [ ] T001 Confirm active feature is `specs/001-development-environment` via `.specify/feature.json` and that constitution is `0.1.5` in `.specify/memory/constitution.md`
|
||
- [ ] T002 [P] Create host-facing doc stub `docs/001-host-runbook.md` in meta repo (preflight results, paths, Gitea tunnel notes — fill during implement)
|
||
- [ ] T003 [P] Create FR/SC evidence checklist stub `docs/001-verification-matrix.md` mapping each FR-*/SC-* from `specs/001-development-environment/spec.md` to blank evidence fields
|
||
|
||
---
|
||
|
||
## Phase 2: Foundational (blocking — host preflight before stories)
|
||
|
||
**Goal**: Observe `rom-dev01` without fighting `saltenv=base`; abort on conflict.
|
||
|
||
- [ ] T004 On `rom-dev01` as admin, capture preflight baseline into `/srv/rom/logs/preflight/` (create `/srv/rom/logs` with safe perms if needed): Ubuntu/kernel, CPU/RAM/swap, disk free, interfaces/routes, users, firewall summary (**do not flush**), listening ports, apt sources → also summarize in `docs/001-host-runbook.md`
|
||
- [ ] T005 Record coexistence rule in `docs/001-host-runbook.md`: if base-managed config conflicts with project needs, **stop and report**; do not silently replace Salt-managed settings
|
||
- [ ] T006 Verify SSH admin path still works after any read-only inspection; note rollback contacts/commands in `docs/001-host-runbook.md`
|
||
|
||
---
|
||
|
||
## Phase 3: User Story 1 — Reachable build workspace (P1)
|
||
|
||
**Story goal**: `android-build` exists with documented workspace; `/srv/rom` owned correctly; meta tree at fixed path.
|
||
|
||
**Independent test**: `sudo -iu android-build` works; `/srv/rom/artifacts` writable; `/home/android-build/sunfish-a16-rom` contains Spec Kit tree (after T012).
|
||
|
||
### Implementation
|
||
|
||
- [ ] T007 [US1] Create unprivileged user `android-build` with home `/home/android-build` (admin); document uid/gid in `docs/001-host-runbook.md`
|
||
- [ ] T008 [US1] Create `/srv/rom/{src,references,tooling,ccache,artifacts,logs,secrets}` with ownership for `android-build` on writable trees; `secrets/` restricted/empty — document modes in `docs/001-host-runbook.md`
|
||
- [ ] T009 [US1] Verify: `namei -l /srv/rom /srv/rom/artifacts` and `sudo -iu android-build touch /srv/rom/artifacts/.write_test` succeeds; no `chmod 777`
|
||
- [ ] T010 [US1] Document account model (admin vs `android-build` vs service users) in `docs/001-host-runbook.md` — never build Android as root
|
||
- [ ] T011 [US1] Copy laptop staging Git tree to `/home/android-build/sunfish-a16-rom` preserving `.git` (rsync/scp/bundle); verify `test -f /home/android-build/sunfish-a16-rom/specs/001-development-environment/spec.md`
|
||
- [ ] T012 [US1] Ensure `/srv/rom/tooling` is **not** used as Spec Kit checkout; note distinction in `docs/001-host-runbook.md`
|
||
|
||
---
|
||
|
||
## Phase 4: User Story 2 — Android host toolchain (P1)
|
||
|
||
**Story goal**: Clean-login toolchain ready for later `003` (no `repo sync` / build).
|
||
|
||
**Independent test**: `sudo -iu android-build` → `git`, `git lfs`, `repo`, `python3`, `ccache -s`, and LOS-doc Java/prereqs succeed.
|
||
|
||
### Implementation
|
||
|
||
- [ ] T013 [US2] As admin, install host packages per **current** primary LineageOS/AOSP Ubuntu build documentation; record exact package list in `/srv/rom/logs/toolchain-packages.txt`
|
||
- [ ] T014 [US2] Install/configure `repo` for `android-build` per current docs; verify `sudo -iu android-build repo --version`
|
||
- [ ] T015 [US2] Ensure `git` + `git-lfs` for `android-build`; verify `sudo -iu android-build git lfs version`
|
||
- [ ] T016 [US2] Configure ccache: `CCACHE_DIR=/srv/rom/ccache`, ownership `android-build`, size cap; document env in `/home/android-build/.bashrc` or `/home/android-build/.profile` and `docs/001-host-runbook.md`
|
||
- [ ] T017 [US2] Verify: `sudo -iu android-build ccache -s` shows configured cache dir
|
||
- [ ] T018 [US2] Document FR-007 capacity (6 vCPU / 52 GB / 32 GB swap) and **defer `-j`/OOM tuning to `003`** in `docs/001-host-runbook.md` — do not run a Lineage build
|
||
- [ ] T019 [US2] Clean-shell toolchain smoke checklist executed; paste command outputs into `/srv/rom/logs/toolchain-smoke.txt` and tick FR-002/SC-001 in `docs/001-verification-matrix.md`
|
||
|
||
---
|
||
|
||
## Phase 5: User Story 5 — Laptop thin client (P1/P2 overlap — do after US1–US2)
|
||
|
||
**Story goal**: Cursor Remote SSH + artifact rsync proven; Pixel stays on laptop USB.
|
||
|
||
**Independent test**: Remote SSH edit on host; dummy artifact SHA256 matches after rsync.
|
||
|
||
### Implementation
|
||
|
||
- [ ] T020 [US5] Document Cursor Remote SSH → `/home/android-build/sunfish-a16-rom` in `docs/001-host-runbook.md` and `specs/001-development-environment/quickstart.md` (update if needed)
|
||
- [ ] T021 [US5] Create `/srv/rom/artifacts/dummy-001.txt` as `android-build`; record `sha256sum` in `/srv/rom/logs/rsync-smoke.txt`
|
||
- [ ] T022 [US5] From laptop, `rsync` dummy artifact; verify SHA256 match; record laptop path in `/srv/rom/logs/rsync-smoke.txt` and `docs/001-verification-matrix.md` (SC-002)
|
||
- [ ] T023 [US5] Document adb/fastboot-on-laptop / no USB passthrough rule in `docs/001-host-runbook.md` (SC-004 partial)
|
||
|
||
---
|
||
|
||
## Phase 6: User Story 3 — Gitea, Ansible, Semaphore, off-VM mirror (P2)
|
||
|
||
**Story goal**: Private Gitea with four repos; canonical meta remote; laptop pull mirrors; unprivileged Semaphore smoke via Ansible in `sunfish-rom-build`.
|
||
|
||
**Independent test**: Four repos on Gitea; meta history pushed; laptop `git clone --mirror` works; Semaphore runs unprivileged smoke.
|
||
|
||
### Implementation
|
||
|
||
- [ ] T024 [US3] Install Gitea on `rom-dev01` with systemd + persistent data; bind UI to loopback/non-public; document unit/paths in `docs/001-host-runbook.md`
|
||
- [ ] T025 [US3] Store Gitea admin credentials only in restricted host location under `/srv/rom/secrets/` or service-native secret path — **never** commit to Git; document location (not secrets) in `docs/001-host-runbook.md`
|
||
- [ ] T026 [US3] Verify: local `curl` to Gitea UI succeeds; confirm not relying on public Internet exposure; record bind address in `docs/001-host-runbook.md`
|
||
- [ ] T027 [US3] Document Git transport chosen after host inspection (HTTP via SSH tunnel and/or tunneled Git SSH); **do not** open public `:2222` or blindly edit `saltenv=base` sshd — write choice in `docs/001-host-runbook.md`
|
||
- [ ] T028 [US3] Create Gitea repos: `sunfish-a16-rom`, `sunfish-rom-manifest`, `sunfish-rom-build`, `sunfish-rom-patches`
|
||
- [ ] T029 [US3] Push `/home/android-build/sunfish-a16-rom` history to Gitea `sunfish-a16-rom`; set `origin` to Gitea; verify remote in that directory
|
||
- [ ] T030 [US3] Seed minimal structure in `sunfish-rom-build` for Ansible (e.g. `ansible/` playbooks path) — **not** inside Spec Kit meta repo
|
||
- [ ] T031 [US3] Install Ansible on `rom-dev01`; document version in `docs/001-host-runbook.md`
|
||
- [ ] T032 [US3] Add unprivileged smoke playbook in `sunfish-rom-build` (gather_facts + asserts for `/srv/rom`, `android-build`, toolchain); **no become/sudo secrets**
|
||
- [ ] T033 [US3] Run smoke playbook successfully via `ansible-playbook` CLI as documented non-root/project user; log output to `/srv/rom/logs/ansible-smoke.txt`
|
||
- [ ] T034 [US3] Install Semaphore; bind like Gitea (loopback/tunnel); no public exposure; document in `docs/001-host-runbook.md`
|
||
- [ ] T035 [US3] Wire Semaphore to run the **same unprivileged** smoke playbook only; execute once successfully; evidence in `/srv/rom/logs/semaphore-smoke.txt` (FR-005)
|
||
- [ ] T036 [US3] From **laptop**, create bare mirrors with `git clone --mirror` for all four repos (laptop initiates connection); run `git remote update` + `git fsck`; document mirror paths in `docs/001-host-runbook.md` (FR-010/SC-007)
|
||
- [ ] T037 [US3] Confirm laptop staging `/home/aventura/Workspaces/sunfish-a16-rom` is **retained** until T029+T036 verified; only then optionally mark staging as non-canonical in `docs/001-host-runbook.md`
|
||
|
||
---
|
||
|
||
## Phase 7: User Story 4 — Guest isolation (P2)
|
||
|
||
**Story goal**: Isolation checklist passes without breaking SSH.
|
||
|
||
**Independent test**: Public-NIC-only workflow; UIs non-public; SSH still works; no VPN/internal DNS required in docs.
|
||
|
||
### Implementation
|
||
|
||
- [ ] T038 [US4] Document interfaces/routes: project workflow requires only public NIC — `docs/001-host-runbook.md` + evidence in `docs/001-verification-matrix.md` (SC-006)
|
||
- [ ] T039 [US4] Apply isolation/firewall guidance **additively** if needed: never flush nftables/iptables; never close active SSH before tested alternative; record before/after in `/srv/rom/logs/firewall-notes.txt`
|
||
- [ ] T040 [US4] Re-verify Gitea/Semaphore binds remain non-public; SSH admin + tunnel still work — update `docs/001-verification-matrix.md` FR-009/SC-006
|
||
- [ ] T041 [US4] Confirm day-to-day runbook does not require SSYSTEMS VPN/internal DNS/LDAP/GitLab/NFS/Zabbix — `docs/001-host-runbook.md`
|
||
|
||
---
|
||
|
||
## Phase 8: Polish & cross-cutting
|
||
|
||
- [ ] T042 [P] Fill all FR-*/SC-* evidence rows in `docs/001-verification-matrix.md` (including SC-005: no PVE/qm/Salt VM tasks were performed)
|
||
- [ ] T043 [P] Align `specs/001-development-environment/quickstart.md` with final ports/paths/tunnel commands actually used
|
||
- [ ] T044 Restart Gitea (+ Semaphore) via systemd; confirm recovery; optional reboot when safe; note results in `/srv/rom/logs/restart-smoke.txt`
|
||
- [ ] T045 Declare handoff in `docs/001-host-runbook.md`: **`001` complete → proceed to `002`**, do not start Lineage sync/build
|
||
- [ ] T046 Ensure no secrets/tokens landed in `/home/android-build/sunfish-a16-rom` or `sunfish-rom-build` Git history (`git grep` / review)
|
||
|
||
---
|
||
|
||
## Dependencies & story order
|
||
|
||
```text
|
||
Phase 1 (laptop docs)
|
||
↓
|
||
Phase 2 preflight (host)
|
||
↓
|
||
US1 workspace + /srv/rom + meta copy
|
||
↓
|
||
US2 toolchain ──────────────┐
|
||
↓ │
|
||
US5 thin-client smokes ←───┘ (needs artifacts + meta path)
|
||
↓
|
||
US3 Gitea → repos → Ansible in sunfish-rom-build → Semaphore → laptop mirrors
|
||
↓
|
||
US4 isolation hardening/validation
|
||
↓
|
||
Polish / handoff → STOP (wait was already for implement; next feature 002)
|
||
```
|
||
|
||
**MVP (minimum useful host)**: complete through US2 + US5 (T007–T023) even if Gitea delayed — but **formal `001` done** requires P2 (US3+US4+polish) per plan.
|
||
|
||
## Parallel opportunities
|
||
|
||
- T002/T003 on laptop before VM
|
||
- After T008: T010 docs can parallel T011 copy if disk ready
|
||
- T013–T015 package/`repo`/`git-lfs` partly serial (apt) then T016 ccache
|
||
- T042/T043 polish docs in parallel after evidence exists
|
||
|
||
## FR/SC coverage map
|
||
|
||
| ID | Tasks |
|
||
|----|-------|
|
||
| FR-001 | T007–T010 |
|
||
| FR-002 | T013–T017, T019 |
|
||
| FR-003 | T008–T009, T012 |
|
||
| FR-004 | T024–T029 |
|
||
| FR-005 | T030–T035 |
|
||
| FR-006 | T020–T023 |
|
||
| FR-007 | T018 |
|
||
| FR-008 | T011, T029 |
|
||
| FR-009 | T038–T041 |
|
||
| FR-010 | T036–T037 |
|
||
| SC-001 | T019 |
|
||
| SC-002 | T021–T022 |
|
||
| SC-003 | T028–T029 |
|
||
| SC-004 | T020, T023, T045 |
|
||
| SC-005 | T005, T042 |
|
||
| SC-006 | T038–T041 |
|
||
| SC-007 | T036 |
|
||
|
||
## Implementation strategy
|
||
|
||
1. Do **not** execute host tasks until SSH to `rom-dev01` works.
|
||
2. After this `tasks.md` is approved: `/speckit-analyze` → STOP.
|
||
3. `/speckit-implement` follows P1 then P2; stop/report on Salt conflicts.
|
||
4. Do not plan `002` until `001` implement + verification complete.
|
||
|
||
================================================================================
|
||
Micro-adjustments applied to plan (summary)
|
||
================================================================================
|
||
- Meta path fixed: /home/android-build/sunfish-a16-rom
|
||
- Ansible in sunfish-rom-build only
|
||
- Semaphore smoke unprivileged (no sudo secrets)
|
||
- Off-VM mirror: laptop pull only
|
||
- No public :2222 / no blind sshd edits; transport documented at implement
|