feat: implement pvm optimizations, robust uninstall logic and php-version auto-detection

[Fahl-Design]

This PR introduces verified optimizations and fixes to the PHP Version Manager (PVM).

Summary of Changes:

1. Uninstall Resilience: Removes rigid 'php' binary checks. Uninstall is now based on directory existence (solving FPM-only uninstalls) and adds confirmation prompts with a '--yes' bypass and automatic TTY-aware detection.
2. Auto-Switching: 'pvm use' automatically switch to the version specified in '.php-version' file if run without arguments, with an auto-install confirmation prompt if it is missing locally.
3. SemVer Sorting Optimization: Reduced SemVer sorting complexity from O(N log N) parses to O(N) cache-based parsing.
4. Permissions Hardening: Unix file metadata permission setting inside 'download_and_extract' is wrapped in safe tuple checks to prevent individual file failures from breaking the entire installation.

---

^{Need help on this PR? Tag @codesmith with what you need. Autofix is disabled.}

Summary by CodeRabbit

• New Features

  • Added --yes/-y flag to uninstall for non-interactive confirmation.
  • use now reads a local .php-version file to select (and optionally install) a version when none is specified.

• Documentation

  • Major rewrite and expansion of the project handbook (architecture, shell integration, operational patterns, testing guidance).
  • Added pvm self-update usage hint to README.

• Improvements

  • More reliable handling of downloaded package permissions and version sorting.

• Tests

  • Added CLI integration tests for uninstall and use.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d2bcbdba-bdc3-45f0-aca6-f0f96bd280cb

📥 Commits

Reviewing files that changed from the base of the PR and between e11df66 and 817e39e.

📒 Files selected for processing (1)

• GEMINI.md

✅ Files skipped from review due to trivial changes (1)

• GEMINI.md

---

📝 Walkthrough

Walkthrough

This PR adds .php-version resolution to use, a --yes/TTY-aware uninstall flow, refactors version sorting and Unix archive-permission handling, updates docs (GEMINI.md, README), and adds integration tests for the new behaviors.

Changes

CLI Enhancements & Efficiency Improvements

Layer / File(s)	Summary
Use command with .php-version file support src/commands/use_cmd.rs, tests/cli.rs	The use command now reads PHP_VERSION_FILE when no explicit version is provided, attempts to resolve and install it if missing (unless silent), and falls back to interactive selection only if resolution fails. The integration test validates reading the file and writing env-update output.
Uninstall command with --yes flag and TTY confirmation src/commands/uninstall.rs, src/interactive.rs, tests/cli.rs	The uninstall command adds a --yes/-y CLI flag to skip confirmation, implements TTY-aware confirmation prompts that only show when interactive, and changes the version-installed check to use directory existence instead of fs::is_version_installed. The interactive menu passes yes: false when calling the command. Tests validate uninstall with only php-fpm present.
Version sorting efficiency refactor src/utils.rs	The sort_versions function now pre-parses all version strings into (original, Result) pairs, eliminating repeated parsing inside the comparator. Sorting logic pattern-matches parse outcomes and falls back to numeric dot-separated comparison for non-semver versions, then writes sorted originals back into the input slice.
Network archive extraction permissions refactor src/network.rs	Unix permission-setting logic in download_and_extract gates on entry.metadata() and entry.file_type().is_file() in a single conditional, deriving permissions from metadata instead of checking the path and re-reading. Permission is still 0o755, but entries not matching the conditional are skipped.
Handbook and README documentation updates GEMINI.md, README.md	GEMINI.md is reorganized with clearer sections on project architecture, filesystem hierarchy ($PVM_DIR resolution, PID-scoped env files), shell integration mechanics, expanded command catalog, detailed "Adding a New Command" flow, stronger coding standards (dialoguer theming, tokio/reqwest expectations, icon mapping, locking patterns), clarified build/release process, and expanded testing guidance (concurrency, filesystem isolation, dynamic version embedding). README.md adds usage hint for pvm self-update.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• WebProject-xyz/php-version-manager#24: Modifies src/commands/use_cmd.rs around Use::call's handling of missing PHP versions—prompting/auto-installing when not in --silent mode.
• WebProject-xyz/php-version-manager#6: Related to PID/session-specific env-update handling and file-locking for env propagation; overlaps with use env-update semantics and network.rs permission logic.
• WebProject-xyz/php-version-manager#19: Also modifies src/network.rs's download_and_extract implementation (progress/streaming helpers vs. current permission adjustments).

Suggested labels

enhancement

Poem

🐰 I read the file that names the day,
The use command finds the PHP way,
Uninstall asks with gentle cheer,
Sorting swift and permissions clear,
Docs hopped up — releases near!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 62.50% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main changes: uninstall improvements, php-version auto-detection via .php-version file, and performance optimizations (SemVer sorting).
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 feat/optimizations-and-fixes

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@GEMINI.md`:
- Line 89: Replace the workspace formatting check command string "`cargo fmt --
--check`" with the workspace-aware "`cargo fmt --all -- --check`" in the
documentation; locate the line containing the old command and update it to
ensure the CI gate and README reflect the project’s pre-commit workflow for
multi-crate formatting checks.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: dd944a5e-2620-48b1-8907-2fa8787f3d26

📥 Commits

Reviewing files that changed from the base of the PR and between 94fac53 and e11df66.

📒 Files selected for processing (8)

• GEMINI.md
• README.md
• src/commands/uninstall.rs
• src/commands/use_cmd.rs
• src/interactive.rs
• src/network.rs
• src/utils.rs
• tests/cli.rs

[Fahl-Design]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[webproject-bot]

🎉 This PR is included in version 1.3.0 🎉

The release is available on:

• v1.3.0
• GitHub release

Your semantic-release bot 📦🚀