fix(init): refuse an install it cannot finish before asking to overwrite

[PrzemekGalarowicz]

What this changes

pharn init checked the destination (a symlink on the way, or the wrong kind of entry where it writes) only after the Continue and overwrite? prompt. So a user could answer yes and then be told Refusing to install: … is in the way: the question was never real.

init now runs the same read-only pre-flight before that prompt: preflightInstall calls prepareInstall over the manifest init already builds. A refusal takes init's existing error path: exit 1, with the temporary clone cleaned up first.

The checks under the project lock (before the backup) and in installCapabilities (before the copy) stay unchanged, and they remain the authoritative ones, because the tree can change while the prompt is open.

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/install-archetype | docs

Checklist

• Read the existing file(s) before editing; followed the ESM .js-extension import convention.
• Updated the matching tests/*.test.ts. All three new cases failed on the unchanged code. The whole-runInit case failed because the overwrite warning appeared before the refusal.
• Updated the relevant docs/ page (docs/commands/init.md, docs/troubleshooting.md).
• Preserved the security invariants.

Quality gates

• npm run check passes locally (1666 tests). I ran it as root with the DAC-override capabilities dropped (CI-equivalent).
• npm run build succeeds.
• npm run test:coverage passes.

Notes for the reviewer

• The summary prompt (install / cancel) still comes first. A cancelled summary builds no manifest and runs no pre-flight; a test pins that. The docs say "before it asks to overwrite anything", not "before any prompt".
• The pre-flight now runs three times per install. Each run is a read-only walk over the manifest. The code comments say to keep all three.
• Pre-existing, unchanged: a pre-flight refusal still ends with the PHARN_DEBUG hint, as the lock-time refusal always has.

🤖 Generated with Claude Code

https://claude.ai/code/session_0199owRmYfskqYQVQrVP679o

---

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: 1fa82e0f-211d-4f50-816b-bcd2a1d12b17

---

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.}