zosstorage/docs/VIBE_HOWTO.md

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.
• 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.
• Examples live at 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)

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
• CLI parsing:
  • src/cli/args.rs
• Logging initialization:
  • src/logging/mod.rs
• Config load/merge/validate:
  • src/config/loader.rs
  • src/types.rs
• Device discovery:
  • src/device/discovery.rs
• Partitioning planning/apply:
  • src/partition/plan.rs
• Filesystem planning/create:
  • src/fs/plan.rs
• Mount planning/apply + fstab:
  • src/mount/ops.rs
• Reporting JSON:
  • src/report/state.rs
• Orchestration:
  • src/orchestrator/run.rs
• Idempotency/emptiness probes:
  • src/idempotency/mod.rs
• External tools and shell-out:
  • 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).
   • 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.
   • If behavior or invariants change, update docs/SPECS.md.
   • If it’s an architectural choice, add or edit an ADR under docs/adr/0001-modular-workflow.md.

4. Validate and build

   • cargo build
   • Use config/zosstorage.example.yaml to drive configs.
   • For VM testing guidance see PROMPT.md Testing & Validation.

Error policy (quick rules)

• Map external tool failures to Error::Tool with status and stderr (see 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
• Kernel cmdline data: URL support
  • Add base64 YAML support to config loading in src/config/loader.rs
• Logging init
  • Implement tracing setup in 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.
• Check recent ADRs under docs/adr/0001-modular-workflow.md.
• Skim 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
• Schema: docs/SCHEMA.md
• API Index: docs/API-SKELETONS.md
• Specs: docs/SPECS.md
• Dev Workflow (detailed): docs/DEV_WORKFLOW.md
• ADR: docs/adr/0001-modular-workflow.md
• Example config: config/zosstorage.example.yaml