# WARP.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

Project: instantCLI (Rust CLI named "ins")

- Primary language/tooling: Rust (Cargo)
- Local task runner: just (see justfile)
- CI reference: .github/workflows/ci.yml

Commands you will commonly use

- Build
  - Debug build:
    ```bash path=null start=null
    cargo build
    ```
  - Release build:
    ```bash path=null start=null
    cargo build --release
    ```
  - Quick type-check only:
    ```bash path=null start=null
    cargo check
    ```
  - Local install to ~/.local/bin (creates both ins and i aliases):
    ```bash path=null start=null
    just install
    ```
  - System-wide install (requires sudo):
    ```bash path=null start=null
    just rootinstall
    ```

- Test
  - All Rust unit/integration tests (cargo-level):
    ```bash path=null start=null
    cargo test
    ```
  - Run a single Rust test by name (substring match):
    ```bash path=null start=null
    cargo test <test_name_substring>
    # example
    cargo test path_tests
    ```
  - Shell-based end-to-end tests (custom):
    ```bash path=null start=null
    just test            # runs tests/run_all.sh
    ```
  - Run one shell e2e test script:
    ```bash path=null start=null
    bash tests/test_dot_basic.sh
    ```

- Lint and Format
  - Format (write changes):
    ```bash path=null start=null
    cargo fmt
    ```
  - Format check (CI parity):
    ```bash path=null start=null
    cargo fmt -- --check
    ```
  - Clippy lints (CI parity):
    ```bash path=null start=null
    cargo clippy --all-targets --all-features
    ```

- Running the CLI
  - With debug flag passthrough to ins:
    ```bash path=null start=null
    cargo run -- --debug <command>
    ```
  - After local install:
    ```bash path=null start=null
    ins --help
    ```

Prerequisites (from README)

- Rust, Git, FZF, Restic, SQLite3

High-level architecture and structure

- Entry point
  - src/main.rs uses clap to define the CLI and dispatches to subcommand modules.

- Dotfile management (src/dot)
  - Responsibilities: manage dotfile repositories, track file hashes, apply/fetch/reset files, and handle multi-repo overlays and subdirectory activation.
  - Key pieces:
    - config.rs: loads and manages TOML config at ~/.config/instant/dots.toml
    - db.rs: SQLite-backed hash store to protect user modifications (source vs target file distinction)
    - dotfile.rs: core apply/fetch/reset logic with safety checks
    - git.rs, localrepo.rs, meta.rs, repo/: plumbing for cloning/updating repos and subdir management

- Game save management (src/game)
  - Responsibilities: configure games, track save paths, back up and restore via Restic, and support relocation.
  - Structure: cli.rs and commands.rs define surfaces; restic/ wrapper implements backup/restore; operations/ contains launch/sync flows; repository/ manages on-disk state; utils/ provides helpers.

- System diagnostics (src/doctor)
  - Responsibilities: run health checks and apply common fixes; registry/orchestration plus individual checks.

- Interactive menus and scratchpad (src/menu, src/scratchpad, src/fzf_wrapper.rs)
  - Responsibilities: FZF-powered dialogs, TUI server/client, scratchpad terminal windows with configurable names, terminal backends, and sizing.
  - fzf_wrapper.rs exposes a builder-style API for rich confirmation/message dialogs, used by menu flows and commands.

- App launcher (src/launch)
  - Responsibilities: discover/parse desktop entries and execute applications; includes caching and type definitions.

- Common utilities (src/common)
  - Shared plumbing (git helpers, progress, compositor-specific integration for window management).

- Other surfaces
  - completions/: shell completion generation
  - dev/: developer utilities (clone, package, etc.)

Data/config locations (source of truth in code and CLAUDE.md)

- Config: ~/.config/instant/dots.toml
- Database: ~/.local/share/instant/instant.db
- Dot repos: ~/.local/share/instant/dots/

Agent-focused rules and notes (adapted from CLAUDE.md and CI)

- Do not create Git commits automatically. Ask for explicit permission before committing.
- After making code changes, compile to validate:
  - Quick check: cargo check
  - Full build: cargo build
- Some commands open interactive FZF UIs (e.g., ins menu …). These require a human to interact; avoid running them in non-interactive automation.
- For lint/format parity with CI, use:
  - cargo fmt -- --check
  - cargo clippy --all-targets --all-features

Release/packaging references (for context)

- CI builds and tests on Arch container, then builds release artifacts (.github/workflows/release.yml).
- AUR packaging is handled via the pkgbuild job; local development typically uses just install or cargo install.

Helpful development flows

- Local iteration:
  ```bash path=null start=null
  cargo fmt && cargo clippy --all-targets --all-features
  cargo test
  cargo run -- --debug <command>
  ```
- End-to-end check (requires Restic for game flows):
  ```bash path=null start=null
  just test
  ```
