initial commit; layout Plan for agentic development

2026-03-08 00:13:24 +01:00 · 2026-03-08 00:13:24 +01:00 · a34229a6ae
commit a34229a6ae
14 changed files with 1125 additions and 0 deletions
--- a/TASKS.md
+++ b/TASKS.md
@ -0,0 +1,381 @@
+
+
+# TASKS
+
+## Codex working agreement
+
+Use these rules for every implementation task in this repository:
+
+- Write tests first.
+- Use `uv` for all Python commands and dependency management.
+- Use `ruff` for linting and formatting.
+- Prefer small vertical slices that can be implemented and verified independently.
+- Keep Proxmox API and business logic out of Textual widgets where possible.
+- Every screen must have explicit default, loading, success, empty, and error states where applicable.
+- Every interactive screen must be covered by Textual interaction tests using `run_test()` and `Pilot`.
+- Important visual states should be covered by snapshot tests.
+- At the end of each task, summarize what changed and list unresolved UX concerns.
+
+## Repository commands
+
+Codex should use these commands:
+
+- Install dependencies: `uv sync`
+- Run app: `uv run python -m your_app`
+- Run tests: `uv run pytest`
+- Run lint checks: `uv run ruff check .`
+- Format code: `uv run ruff format .`
+
+## Implementation backlog
+
+### Task 1: Bootstrap the Textual app and project structure
+
+Create the initial Textual application structure and make the repository runnable and testable.
+
+Requirements:
+
+- Create the application entrypoint used by `uv run python -m your_app`.
+- Set up a project structure that separates app shell, screens, widgets, models, and services.
+- Add the initial test setup for unit tests, Textual interaction tests, and snapshot tests.
+- Add a central state or domain module for the VM configuration workflow.
+- Add a service interface for Proxmox API access so UI code can be tested with fakes or mocks.
+
+Definition of done:
+
+- Add or update tests first.
+- `uv run pytest` passes.
+- `uv run ruff check .` passes.
+- `uv run ruff format .` has been run.
+- The app opens a minimal Textual shell screen.
+- Summarize what changed and list unresolved UX concerns.
+
+### Task 2: Implement authentication screen and Proxmox login flow
+
+Build the login screen shown in `SPEC.md` and authenticate before the VM creation workflow starts.
+
+Requirements:
+
+- Ask the user for username and password.
+- Load available authentication realms from the Proxmox API.
+- Let the user choose the authentication realm.
+- Default the authentication realm to Linux PAM standard authentication.
+- Handle authentication failure and loading states.
+- Prevent the wizard from continuing until authentication succeeds.
+
+Definition of done:
+
+- Add or update tests first.
+- Add service tests for realm loading and login handling.
+- Add Textual interaction tests using `run_test()` and `Pilot` for the login flow.
+- Add snapshot coverage for default, loading, and authentication-error states.
+- Summarize what changed and list unresolved UX concerns.
+
+### Task 3: Implement the general VM configuration screen
+
+Build the general configuration screen from `SPEC.md`.
+
+Fields:
+
+- Node
+- VM ID
+  - Default: next free VM ID above 100
+- Name
+- Resource Pool
+  - Default: empty
+  - Empty is allowed
+  - Load available resource pools from the server
+  - The pool list may be empty
+- Tags
+  - List existing tags
+  - Allow adding tags one by one
+  - Allow removing tags
+- High Availability (HA)
+  - Default: enabled
+- Start at boot
+  - Default: disabled
+- Start/shutdown order
+  - Optional
+- Startup delay
+  - Optional
+- Shutdown timeout
+  - Optional
+
+Definition of done:
+
+- Add or update tests first.
+- Cover default values, validation, optional fields, and empty pool lists.
+- Add service tests for loading nodes, next VM ID, pools, and existing tags.
+- Add Textual interaction tests using `run_test()` and `Pilot`.
+- Add snapshot coverage for the default general screen and an empty-pool state.
+- Summarize what changed and list unresolved UX concerns.
+
+### Task 4: Implement the OS selection screen
+
+Build the OS configuration screen from `SPEC.md`.
+
+Requirements:
+
+- Ask whether the user wants to use installation media.
+- Valid choices:
+  - ISO
+  - Physical disc drive
+  - No
+- If the user selects ISO:
+  - Load available storages from the Proxmox API
+  - Default storage to `cephfs`
+  - When the storage changes, reload the available ISOs
+  - The ISO list may be empty
+  - Let the user choose the ISO
+  - Default ISO to the latest available NixOS minimal ISO matching this pattern:
+    - `nixos-minimal-<two digit year>-<two digit month>.<some alphanumeric id or hash>.<architecture>-linux.iso`
+- Let the user select guest type and version
+  - Default type: Linux
+  - Default version: 6.x - 2.6 Kernel
+
+Definition of done:
+
+- Add or update tests first.
+- Add service tests for storage and ISO loading and NixOS ISO default selection.
+- Add Textual interaction tests for switching media type, storage, and ISO selection.
+- Add snapshot coverage for:
+  - default OS screen
+  - ISO selected with results
+  - ISO selected with no results
+- Summarize what changed and list unresolved UX concerns.
+
+### Task 5: Implement the system configuration screen
+
+Build the system configuration screen from `SPEC.md`.
+
+Fields:
+
+- Graphic card
+  - Default: Default
+- Machine
+  - Default: q35
+- Firmware BIOS
+  - Default: OVMF (UEFI)
+- Add EFI Disk
+  - Default: enabled
+- EFI storage
+  - Default: ceph-pool
+- Pre-Enroll keys
+  - Default: disabled
+- SCSI Controller
+  - Default: VirtIO SCSI single
+- Qemu Agent
+  - Default: enabled
+- TPM
+  - Default: disabled
+
+Definition of done:
+
+- Add or update tests first.
+- Model system settings separately from widgets.
+- Add Textual interaction tests using `run_test()` and `Pilot`.
+- Add snapshot coverage for the default system screen.
+- Summarize what changed and list unresolved UX concerns.
+
+### Task 6: Implement the disks configuration screen
+
+Build the disks configuration screen from `SPEC.md`.
+
+Requirements:
+
+- Allow the user to configure zero to multiple disks.
+- Allow the user to add, modify, and remove disks one by one.
+- For each disk, support:
+  - Bus/Device
+    - Default bus: SCSI
+    - Default device: increasing integer starting from 0 such as `scsi0`, `scsi1`, ...
+  - Storage
+    - Default: `ceph-pool`
+  - Disk size in GiB
+    - Default: 32
+  - Format
+    - Default: RAW
+    - Not changeable
+  - Cache
+    - Default: no cache
+  - Discard
+    - Default: disabled
+  - IO Thread
+    - Default: enabled
+  - SSD emulation
+    - Default: enabled
+  - Backup
+    - Default: enabled
+  - Skip replication
+    - Default: disabled
+  - Async IO
+    - Default: `io_uring`
+
+Definition of done:
+
+- Add or update tests first.
+- Model disk configuration separately from widgets.
+- Add service tests for available storage loading if required by the UI.
+- Add Textual interaction tests for add, edit, and remove disk flows.
+- Add snapshot coverage for the default disk state and a multi-disk state.
+- Summarize what changed and list unresolved UX concerns.
+
+### Task 7: Implement the CPU configuration screen
+
+Build the CPU configuration screen from `SPEC.md`.
+
+Fields:
+
+- Cores
+  - Default: 2
+- Sockets
+  - Default: 1
+- CPU Type
+  - Default: host
+
+Definition of done:
+
+- Add or update tests first.
+- Cover default values and validation.
+- Add Textual interaction tests using `run_test()` and `Pilot`.
+- Add snapshot coverage for the default CPU screen.
+- Summarize what changed and list unresolved UX concerns.
+
+### Task 8: Implement the memory configuration screen
+
+Build the memory configuration screen from `SPEC.md`.
+
+Fields:
+
+- Memory size in MiB
+  - Default: 2048
+- Min Memory in MiB
+  - Default: same as Memory size
+- Ballooning
+  - Default: enabled
+- Allow KSM
+  - Default: enabled
+
+Definition of done:
+
+- Add or update tests first.
+- Cover default values, derived defaults, and validation.
+- Add Textual interaction tests using `run_test()` and `Pilot`.
+- Add snapshot coverage for the default memory screen.
+- Summarize what changed and list unresolved UX concerns.
+
+### Task 9: Implement the network configuration screen
+
+Build the network configuration screen from `SPEC.md`.
+
+Fields:
+
+- No Network device
+  - Default: disabled
+- Bridge
+  - Default: `vmbr9`
+- VLAN Tag
+  - Default: none
+- Model
+  - Default: virtio
+- MAC Address
+  - Default: auto-generated by the API
+- Firewall
+  - Default: enabled
+- Disconnected
+  - Default: disabled
+- MTU
+  - Default: none
+- Rate Limit in MB/s
+  - Default: none
+- Multiqueue
+  - Default: none
+
+Definition of done:
+
+- Add or update tests first.
+- Cover defaults, validation, and no-network behavior.
+- Add Textual interaction tests using `run_test()` and `Pilot`.
+- Add snapshot coverage for the default network screen and the no-network state.
+- Summarize what changed and list unresolved UX concerns.
+
+### Task 10: Implement the confirmation screen
+
+Build the confirmation screen from `SPEC.md`.
+
+Requirements:
+
+- Display a summary of the full VM configuration collected in previous steps.
+- Clearly show all relevant settings before submission.
+- Show validation issues or missing required inputs.
+- Provide a `Create VM` button.
+
+Definition of done:
+
+- Add or update tests first.
+- Add Textual interaction tests for reaching the confirmation step.
+- Add snapshot coverage for a fully populated confirmation screen and a validation-error state.
+- Summarize what changed and list unresolved UX concerns.
+
+### Task 11: Implement VM creation against the Proxmox API
+
+Submit the VM creation request after confirmation.
+
+Requirements:
+
+- Translate the collected workflow state into the correct Proxmox API request payload.
+- Use the Proxmox VE API to create the VM.
+- After VM creation succeeds, send the required follow-up configuration request(s) to:
+  - add `serial0: socket`
+  - set `vga: serial0`
+- Treat serial-console configuration as part of the overall success criteria because it is required for using the Proxmox VE xterm.js serial console.
+- Handle API request errors cleanly.
+- Distinguish between:
+  - VM creation failure before the VM exists
+  - post-creation serial-console configuration failure after the VM already exists
+- Show progress, success, and failure states.
+- Preserve enough information in the UI so the user can understand what failed.
+
+Definition of done:
+
+- Add or update tests first.
+- Add service tests for payload building, request sequencing, and error handling.
+- Add Textual interaction tests for submission, full success, VM-create failure, and post-create serial-console failure flows.
+- Add snapshot coverage for submission, success, VM-create error, and post-create serial-console error states.
+- Summarize what changed and list unresolved UX concerns.
+
+### Task 12: Polish navigation, error handling, and documentation
+
+Improve the overall wizard experience and repository documentation.
+
+Requirements:
+
+- Ensure step-to-step navigation is clear and keyboard-friendly.
+- Make back/next/confirm actions predictable across screens.
+- Standardize loading, empty, success, and error messaging.
+- Update `README.md` if the real module name or run command differs from the placeholder.
+- Document any remaining constraints, assumptions, or known gaps.
+
+Definition of done:
+
+- Add or update tests first where behavior changes.
+- Add or update interaction tests for navigation flows.
+- Add snapshot coverage for any changed visual states.
+- Summarize what changed and list unresolved UX concerns.
+
+## API references
+
+- Proxmox API documentation: `https://pve.proxmox.com/wiki/Proxmox_VE_API`
+- Proxmox API schema / viewer: `https://pve.proxmox.com/pve-docs/api-viewer/index.html`
+
+## Suggested prompt template for Codex
+
+Use this prompt pattern for each task:
+
+> Implement `TASKS.md` task N.
+> First add or update tests.
+> Use Textual interaction tests with `run_test()` and `Pilot`.
+> Add snapshot coverage for relevant default, loading, empty, success, and error states.
+> Use `uv` for commands and `ruff` for linting / formatting.
+> Keep Proxmox API logic in a service layer.
+> Run `uv run pytest`, `uv run ruff check .`, and `uv run ruff format .`.
+> Summarize what changed and list unresolved UX concerns.