AXP-Resurection/specs/001-development-environment/spec.md

# Feature Specification: Development environment on rom-dev01

**Feature Branch**: `001-development-environment`

**Created**: 2026-08-09

**Status**: Draft

**Input**: Provision the ROM development environment on an already-existing
`rom-dev01` host and establish the laptop ↔ VM ↔ Pixel workflow defined by the
project constitution.

## Context / non-goals

**Assumed already true before this feature starts:**

- `rom-dev01` exists (Ubuntu Server 24.04 LTS);
- one reachable public IPv4 address (public NIC only);
- SSH administration works;
- SSYSTEMS base provisioning (`saltenv=base`) is complete.

**Explicitly out of scope:**

- Proxmox / `pm-test01` VM creation;
- public subnet/IP selection;
- company Salt states, Redmine, or SSYSTEMS governance;
- LineageOS source sync or first ROM build (see `003`);
- AXP capture (see `002`).

**Isolation posture (in scope for guest config/docs):**

- Keep the host usable without SSYSTEMS internal network services.
- Do not add an internal NIC from this feature.
- Bind Gitea/Semaphore so they need not be world-exposed.
- Document guest firewall / egress expectations (block or avoid unnecessary
  traffic to SSYSTEMS internal ranges; SSH from laptop must work).
- Sharing the public VLAN with lab/gateway VMs is acceptable.

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Reachable ROM build host workspace (Priority: P1)

As the developer, I can SSH from my laptop into `rom-dev01` and use a dedicated
`android-build` account with a documented home/workspace layout for Android
work.

**Why this priority**: Without a stable host account and layout, no later build
feature can proceed.

**Independent Test**: SSH as the project build user, create a file under the
documented workspace, confirm ownership and paths.

**Acceptance Scenarios**:

1. **Given** `rom-dev01` is up, **When** I connect via SSH from the laptop,
   **Then** authentication succeeds without requiring this project to change
   PVE/network provisioning.
2. **Given** SSH works, **When** the `android-build` account is provisioned,
   **Then** it exists with a documented home and build-related directories.
3. **Given** the account exists, **When** I inspect `/srv/rom` (or the agreed
   layout), **Then** directories for sources, artifacts, logs, and tooling are
   present with clear ownership.

---

### User Story 2 - Android build toolchain prerequisites (Priority: P1)

As the developer, the host has the packages and tools needed to sync and build
LineageOS for sunfish (repo, git, git-lfs, JDK, build deps, ccache), sized for
6 vCPU / 52 GB RAM / 32 GB swap.

**Why this priority**: Vanilla LOS build (`003`) depends on this.

**Independent Test**: `repo`/`git`/`ccache` respond; documented package set is
installed; ccache directory exists and is writable by `android-build`.

**Acceptance Scenarios**:

1. **Given** `android-build` session, **When** I run `repo --version` and
   `git --version`, **Then** both succeed.
2. **Given** build dependencies are installed, **When** I check ccache config
   and cache dir, **Then** ccache is usable by `android-build`.
3. **Given** constrained host resources, **When** build parallelism defaults are
   documented, **Then** they are conservative (not assuming 16 vCPU / 64 GB).

---

### User Story 3 - Project Git and orchestration services (Priority: P2)

As the developer, private Gitea and Semaphore (over Ansible) run on `rom-dev01`
for project repos and ROM workflow orchestration, without exposing those UIs
unnecessarily to the public Internet. Project Git history must not exist only
on the build VM.

**Why this priority**: Needed before multi-repo ROM automation; can follow basic
toolchain if sequenced. Losing `out/` is fine; losing specs/patches/history is
not.

**Independent Test**: Gitea serves locally/over SSH tunnel; initial repos
`sunfish-a16-rom`, `sunfish-rom-manifest`, `sunfish-rom-build`,
`sunfish-rom-patches` exist or are documented to create; Semaphore can run a
trivial Ansible playbook; off-VM backup/mirror procedure documented and proven
once.

**Acceptance Scenarios**:

1. **Given** Gitea is installed, **When** I access it via the approved path
   (SSH tunnel or existing access policy), **Then** I can create/browse private
   project repositories.
2. **Given** Ansible is installed, **When** Semaphore is configured, **Then** it
   drives Ansible without hiding undocumented build steps.
3. **Given** public IP exists, **When** reviewing listening services, **Then**
   Gitea/Semaphore are not required to be open to the whole Internet for normal
   operation.
4. **Given** the four project repositories, **When** backup/mirror is configured,
   **Then** an off-VM copy exists (laptop clone, Borg, or other agreed target)
   so `rom-dev01` is not the only copy of project history.

---

### User Story 4 - Guest isolation from SSYSTEMS internals (Priority: P2)

As the developer, normal ROM work on `rom-dev01` does not require company
internal DNS, VPN, LDAP, GitLab, NFS, or Zabbix, and project UIs are not
exposed more than necessary.

**Why this priority**: Limits blast radius and keeps the personal project
logically separate even though the hypervisor is shared lab hardware.

**Independent Test**: From the VM, confirm no required route/NIC into internal
SSYSTEMS networks for the workflow; Gitea/Semaphore reachable via approved
non-public path; checklist documents firewall/DNS posture.

**Acceptance Scenarios**:

1. **Given** the provisioned guest, **When** I inspect network interfaces,
   **Then** only the public NIC is required for this project's workflow.
2. **Given** Gitea and Semaphore are installed, **When** I review listen
   addresses / access docs, **Then** they are not required to be open to the
   whole Internet.
3. **Given** guest firewall/DNS docs, **When** I follow them, **Then** day-to-day
   ROM work does not depend on SSYSTEMS internal resolvers or VPN.

---

### User Story 5 - Laptop remains a thin client (Priority: P2)

As the developer, Cursor Remote SSH uses `rom-dev01` as the heavy workspace;
the Pixel stays USB-attached to the laptop; artifacts are `rsync`'d for
flashing.

**Why this priority**: Enforces the disk/space strategy and flashing model.

**Independent Test**: Documented Remote SSH workflow; sample artifact path
`/srv/rom/artifacts` syncs to the laptop with `rsync`.

**Acceptance Scenarios**:

1. **Given** Cursor on the laptop, **When** I open the project via Remote SSH,
   **Then** I edit/build on `rom-dev01` without keeping `.repo`/`out` on the
   laptop.
2. **Given** a dummy artifact in `/srv/rom/artifacts`, **When** I `rsync` it to
   the laptop, **Then** the file arrives for local `adb`/`fastboot` use.
3. **Given** the Pixel is attached to the laptop, **When** following the
   workflow docs, **Then** no USB passthrough to the VM is required.

---

### Edge Cases

- Host reboots: services and mount/layout expectations are documented.
- Disk pressure on 2 TB: cleanup conventions for `out/` and old artifacts.
- SSH admin user ≠ `android-build`: project must not hard-depend on laptop
  usernames (`aventura` / `ubuntu`).

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: Provide dedicated `android-build` account and documented workspace.
- **FR-002**: Install Android/LineageOS build prerequisites and ccache.
- **FR-003**: Create `/srv/rom` layout (sources, artifacts, logs, tooling) or
  document an equivalent and use it consistently.
- **FR-004**: Install and configure private Gitea for project repositories,
  including meta repo `sunfish-a16-rom` plus `sunfish-rom-manifest`,
  `sunfish-rom-build`, and `sunfish-rom-patches`.
- **FR-005**: Install Ansible; configure Semaphore as UI over Ansible for ROM
  workflow (initially may only prove a smoke playbook).
- **FR-006**: Document Cursor Remote SSH + `rsync` artifact + laptop
  adb/fastboot workflow.
- **FR-007**: Document conservative build parallelism defaults for 6 vCPU /
  52 GB / swap 32 GB.
- **FR-008**: Ensure Spec Kit project for `sunfish-a16-rom` is available on the
  host (push/clone the meta repo from this staging tree or Gitea once published).
- **FR-009**: Document and apply guest isolation posture: public-NIC-only
  workflow; no required dependency on SSYSTEMS internal DNS/VPN/LDAP/GitLab/NFS/
  Zabbix; Gitea/Semaphore not world-exposed by default; guest firewall guidance
  to avoid unnecessary traffic to internal SSYSTEMS ranges (without encoding
  concrete company IPs as project secrets/config in Git unless necessary).
- **FR-010**: Provide an off-VM backup or mirror of project-owned Gitea
  repositories so the build VM is not the only copy of project history
  (mechanism may be laptop clones, Borg, or another agreed target).

### Key Entities

- **rom-dev01**: pre-existing Ubuntu 24.04 build host.
- **android-build**: project build account.
- **/srv/rom**: canonical on-host data layout.
- **Gitea / Semaphore / Ansible**: project-owned services on the VM.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: From a clean SSH session as `android-build`, toolchain commands
  required for `003` are available without further ad-hoc package hunting.
- **SC-002**: `/srv/rom/artifacts` (or documented equivalent) is writable and
  used as the artifact handoff point to the laptop.
- **SC-003**: Gitea hosts (or is ready to host) the **four** initial project
  repos (`sunfish-a16-rom`, `sunfish-rom-manifest`, `sunfish-rom-build`,
  `sunfish-rom-patches`) without using company GitLab.
- **SC-004**: Written workflow doc allows a cold start: SSH → workspace →
  (later) build → rsync → flash on laptop-attached Pixel.
- **SC-005**: No playbook or doc in this feature creates or reconfigures the
  Proxmox VM itself.
- **SC-006**: Isolation checklist passes: no internal NIC required; project UIs
  accessible without public Internet exposure; workflow docs do not require
  SSYSTEMS VPN/internal DNS for normal use.
- **SC-007**: Off-VM backup/mirror of the four Gitea project repos is documented
  and demonstrated at least once.