ins 0.10.3

Instant CLI - command-line utilities
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

# 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
  ```