Jan De Landtsheer
507bc172c2
- CLI: add topology selection (-t/--topology), preview flags (--show/--report), and removable policy override (--allow-removable) (src/cli/args.rs) - Config: built-in sensible defaults; deterministic overlays for logging, fstab, removable, topology (src/config/loader.rs) - Device: discovery via /proc + /sys with include/exclude regex and removable policy (src/device/discovery.rs) - Idempotency: detection via blkid; safe emptiness checks (src/idempotency/mod.rs) - Partition: topology-driven planning (Single, DualIndependent, BtrfsRaid1, SsdHddBcachefs) (src/partition/plan.rs) - FS: planning + creation (mkfs.vfat, mkfs.btrfs, bcachefs format) and UUID capture via blkid (src/fs/plan.rs) - Orchestrator: pre-flight with preview JSON (disks, partition_plan, filesystems_planned, mount scheme). Skips emptiness in preview; supports stdout+file (src/orchestrator/run.rs) - Util/Logging/Types/Errors: process execution, tracing, shared types (src/util/mod.rs, src/logging/mod.rs, src/types.rs, src/errors.rs) - Docs: add README with exhaustive usage and preview JSON shape (README.md) Builds and unit tests pass: discovery, util, idempotency helpers, and fs parser tests.
130 lines
6.0 KiB
Markdown
130 lines
6.0 KiB
Markdown
# VIBE HOWTO — Work Fast Without Re-reading the Tree
|
||
|
||
Purpose
|
||
- Ship features incrementally, with minimal context reload.
|
||
- Use grep-friendly region markers, a single API index, and clear responsibilities per module.
|
||
- Keep safety and error conventions explicit and consistent.
|
||
|
||
Key Ideas
|
||
- Contracts live in [docs/API-SKELETONS.md](docs/API-SKELETONS.md).
|
||
- Every module starts with REGION blocks that act like a 10-second summary.
|
||
- Architectural decisions go in ADRs under [docs/adr/0001-modular-workflow.md](docs/adr/0001-modular-workflow.md).
|
||
- Examples live at [config/zosstorage.example.yaml](../config/zosstorage.example.yaml).
|
||
|
||
Quickstart
|
||
- Build:
|
||
- cargo build
|
||
- Inspect CLI:
|
||
- cargo run -- --help
|
||
- Run with config and debug logs:
|
||
- cargo run -- --config ./config/zosstorage.example.yaml --log-level debug
|
||
- Default config file location (initramfs/user space):
|
||
- /etc/zosstorage/config.yaml (copy from [config/zosstorage.example.yaml](../config/zosstorage.example.yaml))
|
||
|
||
What the REGION markers mean
|
||
- REGION: API — one-liners for public items; grep target
|
||
- REGION: RESPONSIBILITIES — scope and non-goals
|
||
- REGION: EXTENSION_POINTS — how to extend without rewriting modules
|
||
- REGION: SAFETY — invariants; when to abort; idempotency rules
|
||
- REGION: ERROR_MAPPING — exact mapping to Error variants
|
||
- REGION: TODO — the next concrete steps to implement
|
||
|
||
Where to start (by responsibility)
|
||
- Entrypoint/binary:
|
||
- [src/main.rs](../src/main.rs)
|
||
- CLI parsing:
|
||
- [src/cli/args.rs](../src/cli/args.rs)
|
||
- Logging initialization:
|
||
- [src/logging/mod.rs](../src/logging/mod.rs)
|
||
- Config load/merge/validate:
|
||
- [src/config/loader.rs](../src/config/loader.rs)
|
||
- [src/types.rs](../src/types.rs)
|
||
- Device discovery:
|
||
- [src/device/discovery.rs](../src/device/discovery.rs)
|
||
- Partitioning planning/apply:
|
||
- [src/partition/plan.rs](../src/partition/plan.rs)
|
||
- Filesystem planning/create:
|
||
- [src/fs/plan.rs](../src/fs/plan.rs)
|
||
- Mount planning/apply + fstab:
|
||
- [src/mount/ops.rs](../src/mount/ops.rs)
|
||
- Reporting JSON:
|
||
- [src/report/state.rs](../src/report/state.rs)
|
||
- Orchestration:
|
||
- [src/orchestrator/run.rs](../src/orchestrator/run.rs)
|
||
- Idempotency/emptiness probes:
|
||
- [src/idempotency/mod.rs](../src/idempotency/mod.rs)
|
||
- External tools and shell-out:
|
||
- [src/util/mod.rs](../src/util/mod.rs)
|
||
|
||
Daily workflow (feature implementation)
|
||
1) Find the module
|
||
- Open the file and read the REGION header block for a 10-second overview.
|
||
- If you don’t know where to look, grep by region:
|
||
- grep -R "REGION: TODO" src/
|
||
- grep -R "REGION: API" src/
|
||
|
||
2) Implement only the declared APIs first
|
||
- Keep signatures stable (as in [docs/API-SKELETONS.md](docs/API-SKELETONS.md)).
|
||
- Replace todo!() bodies one by one.
|
||
- Add safety and error notes under REGION: SAFETY and REGION: ERROR_MAPPING.
|
||
|
||
3) Keep docs in sync
|
||
- If you change a signature, update [docs/API-SKELETONS.md](docs/API-SKELETONS.md).
|
||
- If behavior or invariants change, update [docs/SPECS.md](docs/SPECS.md).
|
||
- If it’s an architectural choice, add or edit an ADR under [docs/adr/0001-modular-workflow.md](docs/adr/0001-modular-workflow.md).
|
||
|
||
4) Validate and build
|
||
- cargo build
|
||
- Use [config/zosstorage.example.yaml](../config/zosstorage.example.yaml) to drive configs.
|
||
- For VM testing guidance see [PROMPT.md](../PROMPT.md) Testing & Validation.
|
||
|
||
Error policy (quick rules)
|
||
- Map external tool failures to Error::Tool with status and stderr (see [src/errors.rs](../src/errors.rs)).
|
||
- Validation failures should be Error::Validation with clear messages.
|
||
- Config IO/parse issues are Error::Config; reporting IO errors are Error::Report.
|
||
- Use Error::Other(anyhow) sparingly (last-resort wrapping).
|
||
|
||
Safety and idempotency rules
|
||
- Never change a disk that isn’t empty when require_empty_disks=true.
|
||
- Partitioning must guarantee GPT, 1 MiB alignment, reserved GPT names, and no preexisting signatures.
|
||
- Filesystems must use reserved labels: ZOSBOOT (ESP) and ZOSDATA (all data filesystems).
|
||
- Orchestrator must do nothing on already-provisioned systems and exit success.
|
||
|
||
Suggested first implementation tasks
|
||
- Utilities (unblocks everything else)
|
||
- Implement which_tool, run_cmd, run_cmd_capture, udev_settle in [src/util/mod.rs](../src/util/mod.rs)
|
||
- Kernel cmdline data: URL support
|
||
- Add base64 YAML support to config loading in [src/config/loader.rs](../src/config/loader.rs)
|
||
- Logging init
|
||
- Implement tracing setup in [src/logging/mod.rs](../src/logging/mod.rs), idempotent setup, optional file target
|
||
|
||
VM test matrix (virtio /dev/vd?)
|
||
- 1 disk (/dev/vda):
|
||
- single → btrfs on data, label ZOSDATA
|
||
- 2 disks (/dev/vda, /dev/vdb):
|
||
- dual_independent → btrfs per disk (two ZOSDATA)
|
||
- bcachefs cache/backing → /dev/vda cache (SSD-like), /dev/vdb backing (HDD-like), label ZOSDATA
|
||
- btrfs_raid1 → mirrored btrfs across both, label ZOSDATA
|
||
- 3 disks (/dev/vda, /dev/vdb, /dev/vdc):
|
||
- bcachefs → cache on /dev/vda; backing on /dev/vdb and /dev/vdc with two replicas; label ZOSDATA
|
||
|
||
Continuity checklist (resume after a break)
|
||
- Open the target module and read the REGION block.
|
||
- grep -R "REGION: TODO" src/ to find pending items.
|
||
- Verify the function signatures in [docs/API-SKELETONS.md](docs/API-SKELETONS.md).
|
||
- Check recent ADRs under [docs/adr/0001-modular-workflow.md](docs/adr/0001-modular-workflow.md).
|
||
- Skim [docs/SPECS.md](docs/SPECS.md) for behavior notes and in-progress sections.
|
||
|
||
Commit discipline
|
||
- Small commits per module/functionality.
|
||
- Keep REGION markers accurate (especially API and TODO).
|
||
- When changing behavior, update docs and/or ADRs in the same PR.
|
||
|
||
Reference index
|
||
- Architecture: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
|
||
- Schema: [docs/SCHEMA.md](docs/SCHEMA.md)
|
||
- API Index: [docs/API-SKELETONS.md](docs/API-SKELETONS.md)
|
||
- Specs: [docs/SPECS.md](docs/SPECS.md)
|
||
- Dev Workflow (detailed): [docs/DEV_WORKFLOW.md](docs/DEV_WORKFLOW.md)
|
||
- ADR: [docs/adr/0001-modular-workflow.md](docs/adr/0001-modular-workflow.md)
|
||
- Example config: [config/zosstorage.example.yaml](../config/zosstorage.example.yaml) |