refactor: generalize Distro add_user and shutdown_command

[blackboxsw]

Decomposed #6689 into part-1 and part-2 to aid reviewing.

Proposed Commit Message

Perform preliminary refactor to be used by security event logging.

Split add_user method into separate methods:
- _add_user: allow distro overrides for custom user creation handling
- _build_add_user_cmd: return tuple of cmd and log_command
- _post_add_user: distro-specific post-creation steps for Alpine
- _user_groups_to_list: normalize group input to a list

Move util.is_user check into create_user and make add_user
raise on failure instead of returning bool.  Distro subclasses now
override the separate methods instead of duplicating add_user.

Refactor shutdown_command introducing a new
_build_shutdown_command which is overridden in subclasses.

Additional Context

Test Steps

tox -e py3

Merge type

• Squash merge using "Proposed Commit Message"
• Rebase and merge unique commits. Requires commit messages per-commit each referencing the pull request number (#<PR_NUM>)

[blackboxsw]

@holmanb I think I have addressed your question. I'm uncertain if there is something else you would like me to address here.

[blackboxsw]

Thanks @holmanb I have responded to your questions and pulled in our group param normalization from #6801.

[holmanb]

I'd like to avoid using unnamed keyword args - being explicit is less verbose and easier to read.

[blackboxsw]

@holmanb I dropped _add_user_preprocess_kwargs in favor of encapsulating that in _add_user. Additionally, I've added typing for passwd for passwd in _post_add_user

[Copilot]

Pull request overview

Preliminary refactor of distro user-creation and shutdown command construction to support upcoming security event logging work, along with corresponding test updates and some typing cleanups.

Changes:

• Refactors Distro.add_user into a wrapper + internal hooks (_add_user, _build_add_user_cmd, _post_add_user) and adjusts create_user semantics around existing users.
• Introduces _build_shutdown_command to centralize shutdown command construction with distro overrides (e.g., Alpine).
• Normalizes user groups handling in cc_users_groups and updates unit tests to pass list-based groups explicitly.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
cloudinit/distros/__init__.py	Refactors user creation flow, adds hook methods, updates shutdown command building, adjusts snap-user handling.
cloudinit/config/cc_users_groups.py	Adds _normalize_user_groups and passes normalized groups into distro.create_user.
cloudinit/distros/alpine.py	Switches Alpine user creation to override _add_user and adds Alpine _build_shutdown_command.
cloudinit/distros/raspberry_pi_os.py	Moves Raspberry Pi OS post-user setup into _post_add_user.
cloudinit/distros/netbsd.py	Refactors NetBSD user creation to _build_add_user_cmd + _post_add_user.
cloudinit/distros/freebsd.py	Refactors FreeBSD user creation to _build_add_user_cmd + _post_add_user.
cloudinit/distros/bsd.py	Tightens type annotations for chpasswd.
cloudinit/netinfo.py	Corrects return type annotation for netdev_info.
cloudinit/config/cc_set_passwords.py	Tightens return type annotation for get_users_by_type.
tests/unittests/config/test_cc_users_groups.py	Adds coverage for group normalization/deprecation and updates expected calls.
tests/unittests/distros/test_create_users.py	Updates calls to create_user(..., groups=...) and adjusts deprecation-log assertions.
tests/unittests/distros/test_alpine.py	Updates Alpine user creation tests for new groups parameter and logstring expectations.
tests/unittests/distros/test_raspberry_pi_os.py	Updates Raspberry Pi OS user creation tests for new hook-based behavior.
tests/unittests/distros/test_user_data_normalize.py	Updates snap-user tests for new create_user call pattern and group list usage.
tests/unittests/distros/test_openbsd.py	Updates add_user calls to include groups=[].
tests/unittests/distros/test_netbsd.py	Updates add_user calls to include groups=[].
tests/unittests/distros/test_freebsd.py	Updates add_user calls to include groups=[].
tests/unittests/distros/test_dragonflybsd.py	Updates add_user calls to include groups=[].

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[blackboxsw]

Addressed all outstanding review comments from copilot as well as @holmanb. This is ready for re-review.

[holmanb]

Getting better, thanks!

[holmanb]

Can we avoid kwargs use here?

[blackboxsw]

Done in alpine. Left freebsd, netbsd and init untyped because of the complexity of useradd_flags processing that would require a lot more work than I want to include in this PR.

[blackboxsw]

@holmanb thanks for the review again.
I believe I have addressed all comments.

[blackboxsw]

Alternate distros action expected fail. Success run seen with PR #6864

[blackboxsw]

Now that CI actions are happy and snap stores are back online, We are now ready for re-review. Note I rebased against update/main and squash merged into 4 logically separate commits to add visibility to the separate intent in each changeset. This helped me review any stray whitespace changes I introduced during this refactor. Should be ready for review @holmanb. Also failing Alpine/edge job is expected dueto missing dependency. #6864 should resolve that issue.

[blackboxsw]

Rebased against main to get alpine workflow fix.