knott 0.1.7

Fast Rust package manager helper for Arch Linux repos and the AUR
Documentation 
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

# knott

knott is a fast Rust Arch Linux package helper for pacman repositories and the
AUR. It combines repo/AUR search, provider-aware AUR planning, and upfront
install menus.

## Current Features

- Pacman-like CLI defaults: `knott` runs `-Syu`, bare terms open a search menu.
- Combined repo/AUR search with AUR narrowing by the shortest term first.
- AUR RPC client with keep-alive, gzip, batching, request timeouts, and per-run caches.
- AUR package info, PKGBUILD printing, and PKGBUILD clone/update support.
- AUR install dry-run/planning with dependency graph ordering and provider lookup.
- Local pacman DB parser for installed markers and AUR update checks, loaded only
  when those local markers are needed.
- Arch-like version comparison for local-vs-AUR upgrade detection.
- Numeric menu parser supporting `1 2`, `1-3`, `^4`, and package names.
- Sanitized terminal output for package metadata, errors, and dry-run commands.
- Aisling-powered tqdm progress loaders for batched AUR metadata fetches.
- Release builds keep Cargo defaults, with `ring` capped at `opt-level = 2` to
  avoid a GCC 16.1 internal compiler error during `cargo install`.

## Installation

```sh
cargo install --path . --locked
knott --version
```

Install the published crate from crates.io:

```sh
cargo install knott --locked
# or pin it explicitly:
cargo install knott --version 0.1.7 --locked
```

If the crates.io index has not picked up the latest release yet, use the exact
version above or retry after the index updates.

## Build

```sh
cargo build --release
./target/release/knott --help
```

## Commands

```sh
knott                       # repo upgrade, then AUR upgrade
knott ripgrep               # interactive search/install
knott -Ss linux headers     # combined repo/AUR search
knott --aur -Ss shellcheck-bin  # AUR-only search
knott -S ripgrep            # install repo or AUR target
knott -Syu --needed         # refresh repos, upgrade, skip installed targets
knott -Ss linux --no-progress # disable progress loaders for this run
knott --aur -S shellcheck-bin --dry-run --noconfirm
knott -Si shellcheck-bin    # package info
knott -G shellcheck-bin     # clone/update PKGBUILD
knott -Gp shellcheck-bin    # print PKGBUILD
knott -Qm                   # foreign packages
knott -Qua --aur            # AUR updates
knott --diagnostics         # resource limits and process diagnostics
knott --help                # command help
knott --version             # version
```

## Resource Limits

- AUR info RPC requests are batched in chunks of 150 package names.
- AUR info cache is capped at 4096 packages per process.
- AUR search cache is capped at 128 search entries per process.
- Search result sets larger than 2048 packages are returned but not cached.
- PKGBUILD responses are capped at 1 MiB, with `Content-Length` rejected early
  when the server provides it.
- AUR dependency resolution is capped at 4096 packages per graph.
- Local pacman `desc` files are read with a 1 MiB per-file limit.
- knott does not spawn background Tokio tasks or use channels; child processes are
  awaited directly.

Use `knott --diagnostics` to print the active limits and current RSS where the
platform exposes it.

## Output Safety

- Package metadata, search results, info output, status lines, errors, warnings,
  prompts, and dry-run command echoes go through sanitized output helpers before
  printing to a terminal.
- Sanitization strips ANSI escape sequences and control characters while keeping
  normal Unicode text, tabs, and line breaks where appropriate.
- `knott -Gp` prints raw PKGBUILD data intentionally so it remains suitable for
  redirection and inspection.
- Progress loaders use `aisling`'s `tqdm` loader on stderr only when stderr is a
  TTY. `--quiet`, `--no-progress`, or `KNOTT_PROGRESS=0` disable them.

## Environment

- `KNOTT_AUR_URL`: AUR base URL, defaults to `https://aur.archlinux.org`.
- `KNOTT_BUILDDIR`: AUR build cache, defaults to `$XDG_CACHE_HOME/knott/build`.
- `KNOTT_PACMAN`: pacman executable, defaults to `pacman`.
- `KNOTT_MAKEPKG`: makepkg executable, defaults to `makepkg`.
- `KNOTT_GIT`: git executable, defaults to `git`.
- `KNOTT_SUDO`: privilege escalation command, defaults to `sudo`.
- `KNOTT_PROGRESS`: set to `0`, `false`, or `off` to disable progress loaders;
  values are trimmed and matched case-insensitively.

## Verification

```sh
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test
```

## Maintenance

- Bump the patch version for every project change, and keep `Cargo.toml`,
  `Cargo.lock`, and README install examples on the same version.
- Keep `README.md`, `knott --help` output in `src/cli.rs`, and CLI parser tests
  synced whenever commands or options change.
- Keep all caches, dependency graphs, and file reads bounded; update the
  `Resource Limits` section and `knott --diagnostics` output when limits change.
- Before publishing, verify the package and install path:

```sh
cargo package
cargo install --path . --locked --root /tmp/knott-install-check --force
/tmp/knott-install-check/bin/knott --version
/tmp/knott-install-check/bin/knott --help
/tmp/knott-install-check/bin/knott --diagnostics
```