feat(cli): add adopt replace shortcut

[trippwill]

Summary

• add explicit tuck adopt --replace target-wins reconciliation
• keep package use conservative while adding human/JSON conflict hints
• cover symlink, copy-mode, unsafe replacement, stale copy-state, mode, and hardlink edge cases
• add mise run sandbox:container for manual user/root-context testing

Closes #8.

Tests

• mise run check

User-visible behavior

package use real-file conflicts now suggest tuck adopt --replace ...; users can explicitly replace package source from the target while preserving dry-run/--apply semantics.

Docs/backlog

Updated docs/cli-spec.md for adopt --replace, conflict hints, and JSON conflict hints.

AI assistance

Implemented with AI assistance; reviewed and validated by the maintainer.

[Copilot]

Pull request overview

Adds an explicit tuck adopt --replace workflow to resolve package use real-file conflicts via a target-wins (but still explicit, --apply-gated) reconciliation path, and surfaces that path to users via human and JSON plan conflict hints.

Changes:

• Add --replace to tuck adopt, enabling safe target-wins replacement of an existing regular package file (including copy-mode cases).
• Add optional hint strings to plan conflicts and render them in console + JSON output (notably for package use real-file conflicts).
• Harden copy-apply behavior around overwrite edge cases (symlink destinations, hardlinks), with added unit/acceptance coverage and a new mise sandbox task.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
internal/plan/model.go	Adds Conflict.Hint field for optional plan conflict hints (JSON).
internal/plan/apply.go	Tightens copy destination handling for overwrite and avoids same-file truncation; refactors finish step.
internal/plan/apply_test.go	Adds regression tests for overwrite-to-symlink rejection and hardlink same-file behavior.
internal/command/planconsole/plan.go	Renders conflict hints in human console output.
internal/command/planconsole/plan_test.go	Tests console rendering includes the new conflict hint line.
internal/command/pkgcmd/plan_build.go	Adds adopt/replace hint emission for package use real-file conflicts when safe.
internal/command/pkgcmd/plan_build_test.go	Tests hint presence/absence for real-file conflicts based on package-path safety.
internal/command/filecmd/plan_build.go	Implements adopt --replace planning, including copy-mode/state interactions and unsafe-path rejection.
internal/command/filecmd/plan_build_test.go	Adds unit coverage for adopt --replace in symlink and copy modes, incl. state cleanup scenarios.
internal/command/filecmd/commands.go	Extends AdoptRequest with Replace.
internal/app/file_commands.go	Wires --replace flag into the CLI and request struct.
docs/cli-spec.md	Updates CLI spec for adopt --replace semantics and plan conflict hint contract.
acceptance/testdata/script/target/target.txtar	Adds acceptance coverage for adopt --replace dry-run/apply, unsafe package paths, and copy-mode config.
acceptance/testdata/script/rendering/rendering.txtar	Updates expected human plan rendering to include the new hint line.
acceptance/testdata/script/json/json.txtar	Updates expected JSON plan output to include conflicts[].hint.
.mise/tasks/sandbox/container	Adds mise run sandbox:container task for manual root-context testing in a Fedora podman sandbox.

---

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