Skip to content

GEMINI.md

Latest commit

 

History

History
59 lines (49 loc) · 3.35 KB

GEMINI.md

File metadata and controls

59 lines (49 loc) · 3.35 KB

Gemini AI Assistant Instructions

CRITICAL SAFETY DIRECTIVE: NEVER use backticks (`) inside git commit messages.

Why?

When running git commit -m "..." in the shell (like Zsh/Bash), backticks are immediately evaluated as command substitution by the user's shell BEFORE the commit is executed. If a file, branch, or text snippet contains a command-like string inside backticks, the shell will execute it silently with the user's full privileges.

Rule

  1. Do not use backticks (`) in commit bodies or summaries.
  2. If you need to quote code, files, or strings in a commit message, use single quotes (e.g. 'filename.rs') or double quotes (e.g. "function_name") instead.
  3. Obey this rule forever, until the end of electronics.

Project Architecture (The Map)

Filesystem Hierarchy

  • $PVM_DIR: Root directory. Resolved via dirs::data_local_dir(), so defaults to ~/.local/share/pvm on Linux and ~/Library/Application Support/pvm on macOS.
  • $PVM_DIR/versions/: Installation directory for specific PHP versions.
  • $PVM_DIR/bin/pvm: The pvm binary itself.
  • $PVM_DIR/remote_cache-.json: 24-hour cache for the remote version index, scoped per target triple (e.g. linux-x86_64).
  • $PVM_DIR/.env_update[_]: Short-lived files written per shell invocation; the shell wrapper sources them to mutate the parent shell's environment.

Module Responsibilities

  • src/cli.rs: Command definitions using clap.
  • src/commands/: Implementation of subcommands. Each command is a struct with a call() method.
  • src/fs.rs: Filesystem utilities (handling PVM_DIR, version paths, env files).
  • src/network.rs: API client for fetching and downloading PHP versions.
  • src/shell.rs: Shell-specific logic for setting environment variables.

static-php-cli Integration

  • Endpoint: https://dl.static-php.dev/static-php-cli/bulk/
  • Supported OS: linux, macOS.
  • Supported Arch: x86_64, aarch64.
  • Packages: cli, fpm, micro.
  • Format: tar.gz only.

Operational Patterns (The Handbook)

Adding a New Command

  1. Add a new module file in src/commands/.
  2. Define the command struct with #[derive(Parser, Debug)].
  3. Export the module in src/commands/mod.rs.
  4. Register the variant in the Commands enum in src/cli.rs.
  5. Implement the call() method logic.

Coding Standards

  • Errors: Use anyhow::Result for all command-level fallible functions.
  • Interactivity: Use dialoguer for menus and confirmations.
  • Icons: Use colored for status icons: ✓ (green), ✗ (red), ↻ (blue), 💡 (yellow).
  • Async: Use tokio for runtime and reqwest for all network I/O.
  • Data Integrity: Use file locking (std::fs::File::lock / lock_shared / unlock, stable since Rust 1.89) when writing to env update files or the remote cache.

Testing & Validation

Testing Protocol

  • Isolation: Every integration test MUST use tempfile::tempdir() and set PVM_DIR to that path.
  • CLI Verification: Use assert_cmd and predicates for output and exit code verification.

Development Workflow

  • Pre-commit: Run cargo clippy -- -D warnings and cargo fmt --all -- --check.
  • Tooling: Use replace or write_file for codebase modifications. Avoid sed/echo in shell.
  • Commit Messages: Follow Conventional Commits. No backticks (Rule 1).