Add bootstrap mode for managed baseline files (#50 slice 1)

[silug]

First slice of #50 (Renovate-resilient templates): split baseline-file management into two modes so puppetsync stops clobbering values that Renovate maintains in place. Slices 2/3 (the in-place merge tasks for Gemfile and YAML) build on this.

Changes

• New profile::managed_file define — wraps the baseline file pattern with a mode parameter:
  • enforce (default): content fully managed; local changes overwritten — the previous behavior for every file
  • bootstrap: lay down the complete file only when it doesn't exist (replace => false), for files whose values are maintained in place after creation
• All file-managing profiles converted (gemfile, git_files, puppet_lint, pdkignore, rspec, github_actions), each exposing a Hiera-overridable mode parameter — so classification lives in data when it needs to vary per project type.
• Classification in this slice:
  • Gemfile → bootstrap (its pins are actively managed by Renovate via simp/renovate-config:ruby; this is the file where clobbering hurts today)
  • Everything else → enforce, including GHA workflows: puppetsync is still the delivery mechanism for workflow changes (e.g. Add a REFERENCE.md freshness check to pr_tests.yml (bundle exec rake validate:strings) #46), so they stay fully managed until the YAML merge stage lands — at which point they flip via Hiera. The trade-off (an enforce sync can revert Renovate's uses: bumps until then) is documented on the class.

No CHANGELOG.md update in this PR, per the new convention discussion (avoiding the every-PR conflict magnet).

Verification

End-to-end through the real apply_puppet_role stage against a local file:// pupmod fixture (temp config, not committed), with role::pupmod classified from Hiera via project_type:

• Fixture pre-seeded with a custom Gemfile (standing in for Renovate-managed state) and a drifted .gitignore
• After the sync: the Gemfile survived byte-for-byte untouched; .gitignore was re-baselined; all missing baseline files were created (5 workflows, .pdkignore, .puppet-lint.rc, .rspec, spec/spec_helper.rb); the sync commit contained 11 files — not the Gemfile
• A second fixture without a Gemfile got the baseline Gemfile created (bootstrap still seeds new repos)

Also green: puppet parser validate over all changed manifests, bolt plan show, the list_pipeline_stages dry run, the CI idempotency e2e, and rspec (154 examples, 0 failures).

Refs #50

🤖 Generated with Claude Code

[nick-markowski]

LGTM — clean, well-scoped slice 1. Approving.

Correctness (confirmed):

• managed_file is right: content + no ensure → ensure => file inferred, and since file's replace defaults to true, every enforce-classified profile is a byte-for-byte no-op refactor — which is why the suite + e2e stay green.
• Reference integrity preserved: the inner file { $path: } still creates File[$path], so existing File[...] autorequires/references resolve unchanged, with exactly one File[$path] per path.
• Gemfile classification is consistent — bootstrap preserves an existing Gemfile while Gemfile.lock stays force-absent regardless.
• Clean type boundary: managed_file wraps content+replace only; the ensure => absent/directory resources correctly stay plain file.

One consequence worth being explicit about (documented, not a blocker): with Gemfile now bootstrap, puppetsync can no longer push any Gemfile change to existing repos — structure included, not just Renovate pins — until the in-place merge stages (slices 2/3) land. New repos still get seeded. So if a baseline Gemfile change is needed before then, it'd require a temporary per-project_type Hiera flip back to enforce.

Suggestions:

• Add a small unit spec for managed_file asserting replace => false for mode => 'bootstrap' and true otherwise. Right now the Renovate-safety guarantee is verified once, manually, against an uncommitted fixture — so nothing in CI guards it. Since bootstrap-vs-enforce is now the load-bearing contract for not clobbering Renovate, a two-example spec locks it in cheaply against a future refactor of the define. (Happy to push this to a follow-up if you'd rather keep the slice tight.)
• Optional: consider renaming the mode param (e.g. sync_mode/strategy). In a file resource mode conventionally means POSIX perms; here it's the management strategy. No conflict today since the define doesn't expose perms, but it's a latent trip-hazard if perm support is ever added. Docs are clear, so purely a take-it-or-leave-it.

[silug]

Thanks @nick-markowski — both suggestions taken in cbff800, and agreed on the consequence:

• The Gemfile-freeze window you called out is real and intentional: the in-place merge that restores puppetsync's ability to change existing Gemfiles is already up as Add merge_gemfile task and pipeline stage (#50 slice 2) #72 (merge_gemfile), so the window only lasts until that merges. The temporary Hiera flip back to enforce remains the documented escape hatch if something urgent lands in between.
• Contract test: rather than reintroduce rspec-puppet for a two-example spec, the guarantee is now CI-guarded in this repo's testing style — scripts/ci-managed-file-contract.sh (run by the CI bolt job) puppet applys profile::managed_file both ways and asserts: bootstrap never overwrites an existing file, enforce and the default always do, and both create missing files. The load-bearing Renovate-safety contract now fails CI loudly if a future refactor of the define breaks it.
• Rename: took it — mode → strategy across the define and all six profiles (plus docs). You're right that it's free now and a trap later; mode on a file-shaped define invites the POSIX-perms misreading the moment anyone adds perm support.

🤖 Generated with Claude Code