From 2fd655c58f35c5100afda832a216f455f1c12127 Mon Sep 17 00:00:00 2001 From: Jan De Landtsheer Date: Mon, 29 Sep 2025 11:42:35 +0200 Subject: [PATCH] docs: add TODO checklist for apply-mode path and follow-ups (TODO.md); README usage and preview JSON --- TODO.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 TODO.md diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..dac0935 --- /dev/null +++ b/TODO.md @@ -0,0 +1,87 @@ +# TODO checklist + +Project status: first-draft preview is implemented and committed. This checklist tracks remaining work to reach end-to-end provisioning (apply mode), plus follow-ups and QA. + +Conventions: +- [x] Completed +- [-] In progress +- [ ] Pending + +Core execution + +- [ ] Add “apply mode” switch to orchestrator to perform destructive actions after preview validation + - Wire phase execution in [orchestrator.run(&Context)](src/orchestrator/run.rs:101): apply partitions → udev settle → mkfs → mount → maybe write fstab → build/write report + - Introduce a CLI flag (e.g. `--apply`) guarded by clear logs and safety checks (not preview) +- [ ] Partition application (destructive) in [fn apply_partitions(...)](src/partition/plan.rs:287) + - Translate [PartitionPlan](src/partition/plan.rs:80) to sgdisk commands (create GPT, partitions in order with alignment and names) + - Enforce idempotency: skip if table already matches plan (or abort with explicit validation error) + - Ensure unique partition GUIDs; capture partition device paths and GUIDs for results + - Call [util::udev_settle()](src/util/mod.rs:128) after changes; robust error mapping to Error::Tool / Error::Partition +- [-] Filesystem creation in [fn make_filesystems(...)](src/fs/plan.rs:182) + - [x] Base mkfs implemented for vfat/btrfs/bcachefs (UUID capture via blkid) + - [ ] Apply btrfs raid profile from config (e.g., `-m raid1 -d raid1`) for [Topology::BtrfsRaid1](src/types.rs:29) and the desired profile in [struct BtrfsOptions](src/types.rs:89) + - [ ] Optionally map compression options for btrfs and bcachefs from config (e.g., `-O compress=zstd:3` or format-equivalent) + - [ ] Consider verifying UUID consistency across multi-device filesystems and improve error messages +- [ ] Mount planning and application in [mount::ops](src/mount/ops.rs:1) + - [ ] Implement [fn plan_mounts(...)](src/mount/ops.rs:68): map FsResult UUIDs into `/var/cache/{UUID}` using [cfg.mount.base_dir](src/types.rs:136), and synthesize options per FS kind + - [ ] Implement [fn apply_mounts(...)](src/mount/ops.rs:75): mkdir -p targets, perform mount syscalls (nix), structured errors + - [ ] Implement [fn maybe_write_fstab(...)](src/mount/ops.rs:81): deterministic entries + idempotent writes when enabled in config + - [ ] Option synthesis (btrfs: compress=zstd:3, ssd/ssd_spread when appropriate; vfat defaults) [src/mount/ops.rs](src/mount/ops.rs:31) +- [ ] Reporting implementation in [report::state](src/report/state.rs:1) + - [ ] Implement [fn build_report(...)](src/report/state.rs:67): include disks, partitions (with GUIDs), filesystems (uuid, label, kind), mounts, and status + - [ ] Implement [fn write_report(...)](src/report/state.rs:77): atomic write via tempfile + rename, robust IO error mapping + - [ ] Consider monotonic sequence number or boot-epoch marker [src/report/state.rs](src/report/state.rs:27) + +Discovery, idempotency, safety + +- [x] Device discovery with removable policy: exclude `/sys/class/block/*/removable == 1` by default; allow via `--allow-removable` [src/device/discovery.rs](src/device/discovery.rs:61) +- [x] Idempotency detection via blkid; filesystem label / PARTLABEL checks [src/idempotency/mod.rs](src/idempotency/mod.rs:42) +- [x] Emptiness checks (idempotency::is_empty_disk) and skip during preview mode [src/orchestrator/run.rs](src/orchestrator/run.rs:140) +- [ ] Optional: additional include/exclude helpers (e.g. path allowlist) and stronger heuristics for device class selection (NVMe/SATA only, etc.) + +CLI, config, defaults + +- [x] Built-in sensible defaults (no YAML required) [src/config/loader.rs](src/config/loader.rs:320) +- [x] Overlays from CLI: log level, file logging, fstab, removable policy, topology [src/config/loader.rs](src/config/loader.rs:247) +- [x] Preview flags (`--show`, `--report`) and topology selection (`-t/--topology`) [src/cli/args.rs](src/cli/args.rs:55) +- [ ] Add `--apply` flag to toggle execute mode and keep preview non-destructive by default [src/cli/args.rs](src/cli/args.rs:55) +- [ ] Consider environment variable overlays [src/config/loader.rs](src/config/loader.rs:39) +- [ ] Consider hidden/dev flags behind features (e.g., `--dry-run-verbose`, `--trace-io`) [src/cli/args.rs](src/cli/args.rs:26) + +Orchestrator tracing and spans + +- [ ] Add per-phase timing/spans in [orchestrator::run](src/orchestrator/run.rs:97) (discovery, plan, partition apply, mkfs, mount, report) +- [x] Preview JSON includes filesystems_planned and mount scheme [src/orchestrator/run.rs](src/orchestrator/run.rs:170) + +Logging/utilities + +- [x] which_tool/run_cmd/run_cmd_capture/udev_settle implemented [src/util/mod.rs](src/util/mod.rs:58) +- [ ] Optional: enrich debug spans around all shell-outs (command-line echo with redactions if needed) +- [ ] Confirm file logging idempotence and guard path creation [src/logging/mod.rs](src/logging/mod.rs:1) + +Docs and tests + +- [x] Exhaustive README with usage and JSON shapes [README.md](README.md:1) +- [ ] Audit rustdoc coverage for all public functions and important helpers; beef up where minimal +- [ ] Topology planning tests (unit-level) for single/dual/raid1/ssd+hdd setups [src/partition/plan.rs](src/partition/plan.rs:112) +- [ ] Filesystem planning tests for RAID1 aggregation and bcachefs mapping [src/fs/plan.rs](src/fs/plan.rs:98) +- [ ] Orchestrator preview tests (JSON contains filesystems_planned/mount section) [src/orchestrator/run.rs](src/orchestrator/run.rs:170) +- [ ] Integration tests in QEMU/KVM matrix; exercise `/dev/vd*` topologies and ensure safe abort on unexpected signatures + +Packaging and integration + +- [ ] Provide build profile for static musl and Alpine initramfs integration (Cargo config + CI) +- [ ] Add minimal init script / docs for integrating into early boot + +Stretch goals and polish + +- [ ] Dry-run mode that outputs proposed sgdisk/mkfs/mount commands in detail with “why” annotations +- [ ] Richer structured report schema (typed disks/partitions/filesystems/mounts) and tooling to diff reports across runs +- [ ] Optional telemetry hooks / metrics (phase durations, device counts) behind features + +Stale TODOs to review/remove + +- [ ] Validate and remove TODOs in: + - [src/fs/plan.rs](src/fs/plan.rs:31) (mapping/mkfs largely implemented) + - [src/util/mod.rs](src/util/mod.rs:30) (helpers implemented) + - [src/logging/mod.rs](src/logging/mod.rs:26) (if file layer is already idempotent) \ No newline at end of file