refactor(ansible): rename keeper_create folder_uid parameter to subfolder_uid (KSM-1454)

[mgallego-keeper]

Summary

The keeper_create module can create a record inside a subfolder. KSM-845 added this in v1.5.0 under the parameter name folder_uid. KSM-1445 later added the sibling module keeper_create_folder, which uses subfolder_uid for the same concept. The Python SDK's CreateOptions class also uses subfolder_uid. This PR renames keeper_create's parameter to subfolder_uid. All three now use one name.

Why now

Version 1.5.0 is not published yet. PyPI shows 1.4.0 as the latest release. Ansible Galaxy also shows 1.4.0. The release PR into master is still open. No released user can set folder_uid today. This rename breaks no public interface.

A decision this revisits

Commit cafdaab already faced this exact naming conflict. Its message says the author dropped an external PR's subfolder_uid addition to create_record(), in favor of the shipped name folder_uid. That same commit then added keeper_create_folder, which uses subfolder_uid for the identical concept. The shipped state today has two names for one idea, split across two sibling modules. This PR finishes that conflict resolution. It does not reverse it. subfolder_uid is now the name in both modules, and it matches the SDK too.

Two defects fixed in the same lines

1. create_record() now turns an empty subfolder_uid into None. Before this change, the SDK payload sent subFolderUid: "" to the server. CreateOptions receives the raw value, and the payload serializes every attribute unconditionally.
2. keeper_create now raises a clear error if a playbook still sets the old folder_uid key. No plugin in this integration declares an argument_spec. Ansible would otherwise drop an unknown key with no warning. Without this check, an unmigrated playbook would create the record at the shared folder root instead of the intended subfolder.

You can ask me to remove the second fix if you would rather not have it.

Also fixed

The subfolder_uid option now carries version_added: "1.5.0". The option had no version_added before, even though it lands in a version later than the module's own 1.1.2.

Origin

External contributor Geoffroy RABOUIN opened GitHub PR #1170. It adds this same ability under the name subfolder_uid. The ability already existed under folder_uid, so the PR added no new function. It does show that an outside user expects the name subfolder_uid, which matches KSM-845's own ticket title. This PR leaves GitHub PR #1170 open. A maintainer will follow up with the contributor separately.

Out of scope

keeper_create_folder's own CreateOptions call has the same empty-string gap that create_record() had before this fix. That call belongs to KSM-1445's code, not this ticket. It needs its own fix in a separate change.

Testing

CI runs no Ansible job for a pull request based on release/integration/ansible/**. The only Ansible workflow filters on branches: [master]. Local verification only:

• Python 3.9.6, which matches the CI floor.
• ansible-core 2.15.13, keeper-secrets-manager-core 17.3.0, keeper-secrets-manager-helper 1.1.2. All versions come from requirements.txt.
• Baseline before this change: 47 passed, 0 failed.
• After this change: 49 passed, 0 failed. The two new tests cover the empty-string case and the old-key rejection.
• Mutation-tested both fixes by hand. Reverting the empty-string normalization fails the new empty-string test. Reverting the guard fails the new rejection test.
• Confirmed by hand, before adding the guard, that an unmigrated playbook using the old folder_uid key was silently accepted. It created the record at the shared folder root with no error.
• Confirmed with ansible-doc --json that the rendered module documentation shows subfolder_uid with version_added 1.5.0, and shows no folder_uid option.
• Grepped the whole integration directory for folder_uid after the change. Every remaining line is either shared_folder_uid, an SDK attribute name, keeper_create_folder's own code, or the guard's own error text.

Files changed

• keeper_secrets_manager_ansible/init.py
• keeper_secrets_manager_ansible/plugins/action/keeper_create.py
• keeper_secrets_manager_ansible/plugins/modules/keeper_create.py
• tests/ansible_example/playbooks/keeper_create_subfolder.yml
• tests/ansible_example/playbooks/keeper_create_subfolder_stale_key.yml (new fixture, tests the guard)
• tests/keeper_create_subfolder_test.py
• README.md
• ansible_galaxy/keepersecurity/keeper_secrets_manager/README.md

JIRA: KSM-1454

[stas-schaller]

Great stuff!