fix(init): restore first-run overwrite of README/CHANGELOG

[tablackburn]

Summary

Fixes a regression introduced in c6a35cf (PR #16) that breaks the first-run init flow.

What broke

PR #16's c6a35cf added a "don't clobber on re-run" guard around the README/CHANGELOG Move-Item calls:

if (Test-Path -Path $readmeTemplate) {
    if (Test-Path -Path $readmePath) {
        Write-Warning '  README.md already exists; leaving it in place...'
    }
    else {
        Move-Item -Path $readmeTemplate -Destination $readmePath
    }
}

The intent was to handle CodeRabbit's concern about a re-run with template files reappearing wiping out user-customized content. The bug: on a fresh template both files exist already — the template-facing README.md (this repo's own README) and the module-facing README.template.md (source for the new module). The guard sees the destination present and treats first-init as a re-run, leaving the template-facing files in place AND leaving *.template.md files on disk.

Critical knock-on: CHANGELOG.template.md survives post-init, so PR #16's workflow guard reads is_template=true on the downstream and skips every CI job on the user's brand-new module — exactly the failure mode PR #16 was meant to prevent.

Fix

File presence alone can't disambiguate "first init" from "re-init with template files reappearing." Use the existing {{ModuleName}}/ folder check (already at Initialize-Template.ps1:124) as the disambiguator: if it existed at script start, this is a first run; if it didn't, the user already initialized once and is re-running.

$wasAlreadyInitialized = -not (Test-Path -Path $templateModuleFolder)
# (existing prompt logic)

if (Test-Path -Path $readmeTemplate) {
    if ($wasAlreadyInitialized -and (Test-Path -Path $readmePath)) {
        Write-Warning '  README.md already exists; leaving it in place...'
    }
    else {
        Move-Item -Path $readmeTemplate -Destination $readmePath -Force
    }
}

-Force is restored on Move-Item because the first-run path now legitimately needs to overwrite the template-facing README.md.

Verification — fresh-worktree smoke test

Pre-fix run on c8f5586 (post-#16 main) ended with two WARNING lines and left *.template.md files on disk. Post-fix run on this branch:

  Updated 18 files with placeholder values
  Renamed module folder to: SmokeTest
  Renamed example function files
  Renamed docs/en-US files
  Generated module README.md from template
  Generated module CHANGELOG.md from template

Inspecting the resulting worktree:

• *.template.md files: none remaining
• README.md: module-facing content (# SmokeTest + the substituted description)
• CHANGELOG.md: module-facing Keep-a-Changelog scaffold
• {{ModuleName}}/ removed, SmokeTest/ present
• Workflow guard step still intact in CI.yaml (appears 2× as designed: lint + unit-tests)
• is_template=false would be the bash check's result, so downstream CI jobs run normally

Test plan

• First-run smoke test on a git worktree --detach of this branch — passes (above).
• Re-run preservation logic still triggers when $wasAlreadyInitialized is true and destination exists — by inspection of the conditional.
• PowerShell parser check on Initialize-Template.ps1 — clean.
• Reviewer to spot-check the diff against the failure mode described above.

Verified 2026-05-10 by independent spot-check of the merged diff (gh api repos/.../pulls/17/files): the new $wasAlreadyInitialized = -not (Test-Path '{{ModuleName}}/') flag correctly disambiguates first-init from re-init; both README and CHANGELOG move blocks are gated on $wasAlreadyInitialized -and Test-Path dest, so first init enters the else branch and runs Move-Item -Force, removing the orphan *.template.md files and producing module-facing README/CHANGELOG. Cross-checked by smoke test on PR #16 (which ran HEAD post-#17 code) — no *.template.md remained, downstream is_template=false.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes
  • Template initialization script now detects prior initialization and intelligently manages file operations. README and CHANGELOG files are preserved when running initialization multiple times, protecting user customizations. During initial setup, template files are correctly configured to ensure proper installation and placement of all required files.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: cfda1dd6-b2bd-4adc-b705-d378ad44ed8d

📥 Commits

Reviewing files that changed from the base of the PR and between c8f5586 and 5eea5ca.

📒 Files selected for processing (1)

• Initialize-Template.ps1

---

📝 Walkthrough

Walkthrough

The Initialize-Template.ps1 script now tracks initialization state via a $wasAlreadyInitialized flag derived from folder existence. It applies this flag to conditionally handle README and CHANGELOG replacements: preserving existing destination files on re-runs while allowing overwrite on first initialization.

Changes

Cohort / File(s)	Summary
PowerShell Template Initialization Logic Initialize-Template.ps1	Added initialization state tracking via $wasAlreadyInitialized variable to distinguish first-run from re-run scenarios. Modified README.md and CHANGELOG.md handling to preserve existing files on re-runs while allowing overwrites on initial setup. Updated file move operations to use -Force parameter.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰✨ A script grew wise, now marks the time,
First init fresh, re-runs sublime,
User edits safe from overwrite's crime,
Templates move with -Force so fine! 🚀

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix(init): restore first-run overwrite of README/CHANGELOG' directly and specifically describes the main change: restoring the ability to overwrite README and CHANGELOG files during first-run initialization.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/init-first-run-readme-changelog

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 0/1 reviews remaining, refill in 60 minutes.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Restores correct first-run initialization behavior for template repositories by using the presence of the pre-init {{ModuleName}}/ folder to distinguish first init vs re-run, ensuring README/CHANGELOG templates are moved/overwritten appropriately and template marker files don’t survive post-init.

Changes:

• Capture initialization state once ($wasAlreadyInitialized) based on existence of the {{ModuleName}}/ folder.
• Restore Move-Item -Force for README.template.md → README.md and CHANGELOG.template.md → CHANGELOG.md on first init, while preserving user files on re-run.

---

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