fix(installers): explain why btrfs is required when /home check fails #152

Merged

mahmoud merged 2 commits from fix/btrfs-precondition-ux-150 into development

2026-04-28 09:38:55 +00:00

mahmoud commented

2026-04-28 07:54:38 +00:00

Owner

Closes #150.

What changed

tools/modules/installers/lib.nu — require_btrfs now tells the operator why btrfs is needed (multi-user template snapshot flow), points at tools/docs/template.md, and notes that single-user Hero can skip multi_user_template_create entirely.
tools/modules/installers/multiuser.nu — multi_user_install had its own near-identical inline /home fs check; replaced with a call to require_btrfs so both surfaces produce the same error.
tools/modules/installers/template.nu — [1/12] preconditions step label now names the requirement so the failure mode is visible before the check runs.

Rendered error

/home is on ext4, but btrfs is required.

The multi-user template flow uses btrfs subvolumes for per-user snapshots (see tools/docs/template.md). Single-user Hero does not need this — you can skip multi_user_template_create entirely if you don't intend to host multiple users on this machine.

To continue with multi-user setup, /home must be on btrfs. See tools/docs/template.md.

Verification

All three modules parse-checked on kristof6:

nu -c 'use tools/modules/installers/lib.nu *; help require_btrfs'
nu -c 'use tools/modules/installers/multiuser.nu *; help multi_user_install'
nu -c 'use tools/modules/installers/template.nu *; help multi_user_template_create'

This machine is on btrfs so the failure path can't be exercised live; the rendered string was confirmed by interpolating the literal message in a one-off nu -c.

Doc-side preflight (issue #150 follow-up suggestion 2) is intentionally deferred — the better error already surfaces the doc link, and a separate doc-only PR keeps this diff focused.

Test plan

Modules still parse
Rendered error reads as intended
(Manual on a fresh ext4 host) multi_user_template_create produces the new error and an operator can act on it without reading source

Closes #150. ## What changed - `tools/modules/installers/lib.nu` — `require_btrfs` now tells the operator *why* btrfs is needed (multi-user template snapshot flow), points at `tools/docs/template.md`, and notes that single-user Hero can skip `multi_user_template_create` entirely. - `tools/modules/installers/multiuser.nu` — `multi_user_install` had its own near-identical inline `/home` fs check; replaced with a call to `require_btrfs` so both surfaces produce the same error. - `tools/modules/installers/template.nu` — `[1/12] preconditions` step label now names the requirement so the failure mode is visible before the check runs. ## Rendered error ``` /home is on ext4, but btrfs is required. The multi-user template flow uses btrfs subvolumes for per-user snapshots (see tools/docs/template.md). Single-user Hero does not need this — you can skip multi_user_template_create entirely if you don't intend to host multiple users on this machine. To continue with multi-user setup, /home must be on btrfs. See tools/docs/template.md. ``` ## Verification All three modules parse-checked on `kristof6`: ``` nu -c 'use tools/modules/installers/lib.nu *; help require_btrfs' nu -c 'use tools/modules/installers/multiuser.nu *; help multi_user_install' nu -c 'use tools/modules/installers/template.nu *; help multi_user_template_create' ``` This machine is on btrfs so the failure path can't be exercised live; the rendered string was confirmed by interpolating the literal message in a one-off `nu -c`. Doc-side preflight (issue #150 follow-up suggestion 2) is intentionally deferred — the better error already surfaces the doc link, and a separate doc-only PR keeps this diff focused. ## Test plan - [x] Modules still parse - [x] Rendered error reads as intended - [ ] (Manual on a fresh ext4 host) `multi_user_template_create` produces the new error and an operator can act on it without reading source

mahmoud added 1 commit

2026-04-28 07:54:38 +00:00

fix(installers): explain why btrfs is required when /home check fails

Build and Publish Skills / build-and-publish (pull_request) Successful in 6s

Details

68673571cd

The error in require_btrfs (and the inline duplicate in multi_user_install)
told the operator the filesystem was wrong but offered no remediation. On a
fresh Ubuntu/Debian box where /home defaults to ext4, this stops onboarding
at the very first command of the multi-user flow.

Rewrite the error to:
  - explain that btrfs is needed for the multi-user template snapshot flow,
  - point at tools/docs/template.md,
  - tell single-user operators they can skip multi_user_template_create.

Also collapse the inline /home fs check in multi_user_install into a call
to require_btrfs (was a near-line-for-line duplicate), and tag the [1/12]
preconditions step label so the requirement is visible before the check
runs.

#150