@pirasan023/pkgscope-darwin-x64 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +121 -0
  2. package/bin/pkgscope +0 -0
  3. package/package.json +15 -6
package/README.md ADDED
@@ -0,0 +1,121 @@
1
+ # pkgscope
2
+
3
+ `pkgscope` is an offline-first CLI/TUI for auditing and safely uninstalling packages managed by Homebrew, npm, pnpm, pipx, uv, Cargo, apt, DNF, pacman, Snap, and Flatpak on macOS and Linux.
4
+
5
+ ## Important notice
6
+
7
+ This project was created with substantial assistance from generative AI. Although its behavior is reviewed and tested, AI-generated code can contain mistakes, unsafe assumptions, or unexpected behavior.
8
+
9
+ Use pkgscope entirely at your own risk. Its uninstall feature runs package-manager commands and may remove software or related data. Always review the displayed command and confirmation screen. The authors, contributors, and AI service providers accept no responsibility or liability for loss, damage, interruption, or other consequences arising from use, to the maximum extent permitted by law. The MIT License's “AS IS” terms apply.
10
+
11
+ ## What it does
12
+
13
+ - Inventories each detected manager instance from local metadata, without requiring a network connection.
14
+ - Shows which commands are active, hidden, shadowed, colliding, or broken in the current `PATH`.
15
+ - Separates explicitly installed apt, DNF, and pacman packages from automatically installed system libraries.
16
+ - Treats Snap applications as records while retaining bases, kernels, and content providers as dependency evidence.
17
+ - Separates Flatpak user, default-system, and named-system installations.
18
+ - Reports locally sourced descriptions, URLs, versions, CPU architectures, sizes, install times, dependencies, and owned commands. Unknown values remain unknown; pkgscope does not guess them.
19
+ - Builds one exact manager-native uninstall action, shows it, and requires typed confirmation before execution.
20
+
21
+ pkgscope does not calculate an “unused score,” read shell history or projects without explicit future consent, use telemetry, delete files directly, contact package registries for inventory, or invoke `sudo`.
22
+
23
+ ## Install
24
+
25
+ The same command is used on supported macOS and Linux systems:
26
+
27
+ ```console
28
+ npm install --global @pirasan023/pkgscope
29
+ pkgscope
30
+ ```
31
+
32
+ Supported release targets are:
33
+
34
+ | OS | CPU | Native target |
35
+ |---|---|---|
36
+ | macOS 14+ | Apple Silicon | `aarch64-apple-darwin` |
37
+ | macOS 14+ | Intel | `x86_64-apple-darwin` |
38
+ | Linux | ARM64 | `aarch64-unknown-linux-musl` |
39
+ | Linux | x64 | `x86_64-unknown-linux-musl` |
40
+
41
+ Linux releases are statically linked musl binaries and are tested on Ubuntu, Debian, Fedora, Arch, Alpine, and the standard Linuxbrew environment. The native archives and generated Homebrew Formula are also attached to each GitHub Release.
42
+
43
+ To build from source, install Rust 1.88 or newer:
44
+
45
+ ```console
46
+ cargo build --release
47
+ ./target/release/pkgscope doctor
48
+ ./target/release/pkgscope
49
+ ```
50
+
51
+ ## Commands
52
+
53
+ ```text
54
+ pkgscope TTY: TUI; non-TTY: list
55
+ pkgscope tui open the interactive interface
56
+ pkgscope list print the inventory
57
+ pkgscope doctor diagnose the local setup
58
+ ```
59
+
60
+ The normal interface intentionally stays small. `--refresh` forces a new scan for non-TUI output. `--format table|json|jsonl|csv` selects output. The TUI always starts with a fresh scan and uses the same screen, keys, and meanings on macOS and Linux.
61
+
62
+ Examples:
63
+
64
+ ```console
65
+ pkgscope
66
+ pkgscope list --refresh
67
+ pkgscope list --format json > snapshot.json
68
+ pkgscope doctor
69
+ ```
70
+
71
+ Exit codes:
72
+
73
+ | Code | Meaning |
74
+ |---:|---|
75
+ | 0 | Requested operation succeeded |
76
+ | 1 | General error or cancellation |
77
+ | 2 | Invalid argument or configuration |
78
+ | 3 | Partial scan; successful manager results remain available |
79
+ | 4 | Requested installation was not found |
80
+
81
+ ## Output and JSON
82
+
83
+ `Known since` is the first exact pkgscope observation, not a guessed installation time. A filesystem timestamp is labeled as estimated. Package managers' local databases and receipts are authoritative for their own fields. Size methods and confidence are reported with the result.
84
+
85
+ JSON output uses schema v2 and includes Linux distribution information read from `os-release`, the eleven manager values, and the new source kinds. See [schema-v2.json](docs/schema-v2.json) and [JSON compatibility](docs/json-compatibility.md). Schema v1 snapshots still deserialize, but v0.3.0 never reuses them as a current cache: it automatically performs a fresh scan and writes v2.
86
+
87
+ ## Local state and privacy
88
+
89
+ State is stored in `~/.local/share/pkgscope/state.db`; `XDG_DATA_HOME` overrides the base directory. The database contains normalized inventory and derived findings, not registry credentials, environment dumps, shell-history text, or project contents. Corrupt databases are preserved before recovery.
90
+
91
+ Optional defaults are read from `~/.config/pkgscope/config.toml` or `XDG_CONFIG_HOME`; see [config.example.toml](docs/config.example.toml). Command-line options override the file. Unsafe requests to enable telemetry or retain raw history are rejected. `--history` and `--project-root` remain consent-shaped preview flags and do not read those sources in v0.3.0.
92
+
93
+ ## Removal safety
94
+
95
+ The TUI requires this sequence: open details with Enter, press `u`, review the exact executable and argument array, type the full package name, and press Enter. pkgscope then performs a fresh scan and revalidates the stable identity, owner, version, install root, executable, dependencies, and action. It refuses to remove itself, the package manager, its runtime, or a record with known managed dependents, and rescans after success.
96
+
97
+ For apt, DNF, and pacman, pkgscope additionally simulates or tests the removal transaction immediately before execution. If it cannot prove that exactly the selected package—and no replacement or dependent package—will change, it refuses the operation. System changes run only when pkgscope already has the required effective root privilege. Otherwise it displays the command and reason and stops; it never starts `sudo`.
98
+
99
+ Snap removal never adds `--purge`, so Snap data is retained. Flatpak removal never adds `--delete-data` and never uninstalls related refs automatically. Homebrew never uses `--zap`. Shared caches, rollback, and configuration removal are not promised.
100
+
101
+ ## Development and verification
102
+
103
+ ```console
104
+ cargo fmt --all -- --check
105
+ cargo clippy --all-targets --all-features --locked -- -D warnings
106
+ cargo test --all-targets --locked
107
+ cargo audit --deny warnings
108
+ npm test --prefix npm
109
+ ```
110
+
111
+ Unit and isolated integration tests cover Mach-O/ELF inspection, all eleven managers, malformed and unknown input, control characters, bounded output, timeouts, safe removal planning, permissions, and direct argument execution. A pseudo-terminal test drives TUI navigation, both sort directions, search, detail scrolling, cancellation, wrong confirmation, and disposable-package removal. CI adds real or container-isolated checks on supported Linux families, Linuxbrew, Flatpak scopes, Snap, ARM64, and macOS regression.
112
+
113
+ ## Distribution security
114
+
115
+ Every release contains four native archives, `SHA256SUMS`, a CycloneDX SBOM per target, GitHub build-provenance attestations, and a generated Homebrew Formula. Linux binaries are checked for CPU type, absence of dynamic dependencies, and real startup. Published npm and GitHub artifacts are re-downloaded into clean x64 and ARM64 Linux jobs and exercised again.
116
+
117
+ The binaries are not code-signed or notarized. macOS may block or warn about a downloaded binary; Linux distributions may also display provenance or trust warnings for manually downloaded executables. Verify the archive against `SHA256SUMS` and its GitHub attestation before use. See [SECURITY.md](SECURITY.md) and [the release procedure](docs/releasing.md).
118
+
119
+ ## License
120
+
121
+ MIT — see [LICENSE](LICENSE).
package/bin/pkgscope CHANGED
Binary file
package/package.json CHANGED
@@ -1,16 +1,25 @@
1
1
  {
2
2
  "name": "@pirasan023/pkgscope-darwin-x64",
3
- "version": "0.2.0",
4
- "description": "pkgscope native binary for macOS x64",
3
+ "version": "0.3.0",
4
+ "description": "pkgscope native binary",
5
5
  "license": "MIT",
6
6
  "repository": {
7
7
  "type": "git",
8
8
  "url": "git+https://github.com/pirasan023/pkgscope.git"
9
9
  },
10
- "os": ["darwin"],
11
- "cpu": ["x64"],
12
- "files": ["bin/pkgscope", "LICENSE"],
10
+ "os": [
11
+ "darwin"
12
+ ],
13
+ "cpu": [
14
+ "x64"
15
+ ],
16
+ "files": [
17
+ "bin/pkgscope",
18
+ "LICENSE",
19
+ "README.md"
20
+ ],
13
21
  "publishConfig": {
14
- "access": "public"
22
+ "access": "public",
23
+ "provenance": true
15
24
  }
16
25
  }