fix(init): a re-run init backs up your edits and keeps your manual adds (PHARN-11)

[PrzemekGalarowicz]

What this changes

Running pharn init again on a project that already has PHARN installed lost local edits and dropped capabilities the user had added by hand. Reproduced:

1. init, then pharn add a11y, then edit pharn-spec.md.
2. Run init again and confirm the overwrite prompt.

The prompt listed only 10 of the 417 existing paths ("…and 407 more"). No .pharn-backup/ was created, the edit was lost, and a11y disappeared from the config while its files stayed on disk. This path is easy to reach, because the CLI itself tells users to run init to recover from a legacy or broken config.

• Overwrite prompt (steps/overwrite-check.ts): files that differ from upstream are listed first and marked (edited). The prompt also says how many there are and that they will be copied to .pharn-backup/ first.
• Backup before writing (steps/install-archetype.ts): immediately before copying, init scans the project again and copies each edited file to .pharn-backup/<ts>/. It prints the backup directory as soon as it is created. This uses the same scan and backup functions as add (scanDest + createBackup).
• Manual capabilities kept (commands/init.ts): init reads the config it is about to replace and keeps every source: "manual" capability that upstream still ships: it installs it again and records it as manual. An unreadable or invalid old config never blocks init; in that case nothing is carried over.
• Docs: docs/commands/init.md and CLAUDE.md updated.

Built with /pharn-dev-ship; stage artifacts are in .dev/features/reinit-preserve-edits/. Results:

• validate: exit 0
• regress: no-regressions
• verify: PASS
• coverage: 97.14% (the gate is 97%)

Type of change

• feat — new stack option, wizard step, or command capability
• fix — bug fix
• docs — docs-only change
• chore / refactor — tooling or internal restructure, no behavior change

Area(s) touched

commands/init | steps/overwrite-check | steps/install-archetype | docs

Checklist

• Read the existing file(s) before editing; followed the ESM .js-extension import convention.
• New tests:
  • 4 fail on the old code: edited files listed first in the prompt; backup made and its path printed; manual capability recorded as manual; init carries a manual capability over.
  • control cases: no backup when nothing was edited; nothing marked (edited) when files are byte-identical; a corrupt old config does not block init.
• Updated docs/commands/init.md.
• Preserved the security invariants.

Quality gates

• npm run check + npm run test:coverage pass locally (1360/1360; non-root user, node 22).
• npm run build (left to CI).

Notes for the reviewer

pharn.config.json is not part of the files init installs, so it is not backed up. Hand-added capabilities are carried over instead. Hand-edited models/seam blocks are still reset to defaults when init runs again; that was already the case before this PR, and the existing ConfigParseError message warns about it.

🤖 Generated with Claude Code

https://claude.ai/code/session_01TvcuVhk8hTeDskp5pAJhnc

---

Generated by Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 226ac21f-090b-479f-bd9d-9925ada058f8

---

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

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