@blurname/debrief 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 blurname
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,188 @@
+# debrief
+
+***Debrief* 你的 Debian 机器——问它到底装了什么,并追踪它的变化。**
+
+（名字取自 `deb` + *debrief*「事后汇报」：把整台机器的安装情况汇报上来。）
+
+主线用法:**收集当前机器上装了什么,变成一份清单,然后追踪它的变化。** 软件你(或某个
+agent)照常用 apt 直接装,debrief 不负责装、负责"看和管"——`collect` 把系统快照成
+`debrief.json` + `debrief.lock`,`status` 告诉你系统相对快照又多了/少了/升级了什么。
+
+## 概念映射
+
+| npm | debrief |
+| --- | --- |
+| `package.json`(直接依赖) | `debrief.json` — 你**主动装**的包(`apt-mark showmanual`) |
+| `package-lock.json`(完整依赖树) | `debrief.lock` — **全部**已装包 + 确切版本(含依赖) |
+| `node_modules` | 系统 dpkg 状态(通过后端读写) |
+| npm registry | apt sources / Debian 镜像 |
+| `pip freeze` / `dpkg --get-selections` | `debrief collect` — 从系统反向生成清单 |
+| `git status` | `debrief status` — 系统当前状态 vs 快照 |
+| `npm install` | `debrief install` — 把清单里缺的装到另一台机器 |
+
+底层就是 Debian 原生的 `dpkg-query`(装了什么)+ `apt-mark showmanual`(哪些是你主动装的、
+而非被依赖带进来的)。后者恰好等价于"直接依赖 vs 传递依赖":主动装的进 manifest,依赖只进 lock。
+
+### 也能抓"非 dpkg"装的裸二进制
+
+有些软件根本不走 apt——`curl … | sh`、手动下载、brew/cargo 之类,直接把一个可执行文件丢到
+PATH 上(比如 [herdr](https://herdr.dev/docs/install/) 就是 `curl -fsSL https://herdr.dev/install.sh | sh`)。
+`collect` 会顺带扫 `/usr/local/bin`、`~/.local/bin` 等目录,对每个可执行文件用 `dpkg -S` 反查:
+**dpkg 不认领的,就是这类"裸二进制"**,记进 lock 的 `binaries`(含内容 `sha256`,所以自更新会被
+`status` 认出来;加 `--probe-versions` 还能跑 `--version` 取版本)。
+
+```
+$ debrief status
+non-dpkg binaries (curl|sh / manual / brew / ...):
++ herdr /usr/local/bin/herdr
+~ bun /usr/local/bin/bun (contents changed)
+```
+
+`--no-binaries` 关掉这个扫描;`--scan-dirs a:b:c` 指定要扫的目录。
+
+## 主线:收集 & 追踪
+
+```bash
+debrief collect          # 把当前系统快照进 debrief.json(主动装的)+ debrief.lock(全部)
+debrief collect --pin    # manifest 里记确切版本(而非默认的 "*")
+debrief status           # 对比:系统相对上次 collect 多了/少了/升级了什么
+debrief list             # 清单里的包及其状态、可升级情况
+debrief outdated         # 有新版本可升级的包
+```
+
+典型场景:把 `debrief.json` + `debrief.lock` 提交进你的 dotfiles / 配置仓库。之后 agent 直接
+`apt install` 了什么新东西,`debrief status` 一眼就能看出来;确认无误就 `debrief collect` 重新快照。
+
+```
+$ debrief status
++ ripgrep 14.1.0-1
++ libpcre2-16-0 10.42-1 (dep)
+~ nginx 1.24.0-2 → 1.26.0-1
+- jq 1.6-2.1
+
++2 added  ~1 changed  -1 removed (vs snapshot; run `debrief collect` to update it)
+```
+
+## 设计取向:友好封装(friendly wrapper)
+
+这是刻意选择的最保守语义:
+
+- **`install` 只增不改**:只安装 manifest 里*尚未安装*的包。已经装了的,即使版本不满足约束
+  (drift),也**只警告、绝不改动**。不做整机对齐(no reconcile),不会去卸载"多余"的包。
+- **`add` / `remove` 是显式动作**:`add` 会安装并写入 manifest;`remove` 会卸载并从 manifest 移除。
+- **lockfile 给你可复现性**:`install` 时若锁定的版本仍然可用且满足约束,就装*锁定的那个*
+  (输出里标 `↺`),而不是最新的——这样在另一台机器上 `install` 得到同样的结果。
+
+## 后端(可插拔)
+
+所有逻辑都只依赖一个 `Backend` 接口,因此同一套代码能在有没有 apt 的机器上跑:
+
+- **`apt`** — 真实 Debian,底层调用 `dpkg-query` / `apt-cache` / `apt-get`(改动系统的操作会在
+  非 root 时自动加 `sudo`)。
+- **`mock`** — 内存/文件模拟的假仓库,自带一批仿真包版本。在没有 dpkg 的机器(比如 NixOS)上
+  默认启用,用于开发和测试。
+
+选择顺序:`--backend` > `$DEBRIEF_BACKEND` > lockfile 里记录的后端 > 自动探测(有 `apt-get` 就用
+`apt`,否则 `mock`)。
+
+## 反向:把清单装到另一台机器(可选)
+
+collect 出来的清单也能反过来用——在一台新机器上把清单里缺的装齐。这条线是刻意保守的
+"友好封装":
+
+- **`install` 只增不改**:只安装清单里*尚未安装*的包。已装的即使版本不满足约束(drift),
+  也**只警告、绝不改动**;绝不卸载"多余"的包。
+- **`add` / `remove` 是显式动作**:`add` 会安装并写入 manifest;`remove` 会卸载并移除。
+- **lockfile 给可复现性**:`install` 时若锁定版本仍可用且满足约束,就装*锁定的那个*(标 `↺`)。
+
+```bash
+debrief install                    # 把 manifest 里缺的装上(优先按 lock 复现)
+debrief add nginx@^1.24 git        # 显式安装并记录
+debrief add htop=3.2.1-1           # 钉死一个确切版本
+debrief remove git                 # 卸载 + 从 manifest 移除
+debrief remove git --save-only     # 只从 manifest 移除,保留已安装
+debrief init                       # 创建一个空的 debrief.json
+debrief --dry-run <cmd>            # 预演,不改动任何东西
+```
+
+安装用 bun:`bun link` 后可直接用 `debrief`;或 `bun run bin/debrief.ts <command>` 直接跑。
+
+## 版本约束(npm 风格,作用在真实 Debian 版本号上)
+
+约束语法借用 npm,但比较用的是 dpkg 自己的版本算法(epoch、`~` 预发布排序等都正确处理):
+
+| 写法 | 含义 |
+| --- | --- |
+| `nginx` | 最新候选版;manifest 里写成 `^<装上的版本>` |
+| `nginx@^1.24` | `>=1.24` 且 `<2`(caret:允许非 major 升级) |
+| `nginx@~1.24` | `>=1.24` 且 `<1.25`(tilde:钉住 minor) |
+| `nginx@'>=1.22 <1.26'` | 空格分隔 = AND 组合区间 |
+| `nginx=1.24.0-1` | 精确的 Debian 版本 |
+
+## 开发
+
+```bash
+bun install
+bun test            # 单元 + 集成测试(全程用 mock 后端,任何机器都能跑)
+bun run typecheck
+```
+
+## 分发
+
+代码只用 `node:` 内置模块(通过 `src/sys.ts` 这层薄封装),所以**同一份代码在 Bun 和 Node
+(≥18)上都能跑**。默认分发方式:打成一个几十 KB 的 JS,**要求目标机有 `bun` 或 `node`**——比把整个
+运行时塞进二进制(~100MB)划算得多。
+
+```bash
+bun run build      # → dist/debrief.js(~40KB,单文件,含 node shebang)
+node dist/debrief.js collect        # 用 node 跑
+bun  dist/debrief.js collect        # 用 bun 跑
+```
+
+- **npm**:`npm i -g debrief`(或 `bunx debrief`)—— `bin` 指向 `dist/debrief.js`,`prepack`
+  会自动构建。`npm pack` 出来的包只有 16KB / 3 个文件。
+- **`curl | sh`**:`curl -fsSL <host>/install.sh | sh` —— 拉下 `dist/debrief.js` 和一个 exec
+  node/bun 的启动器丢到 `~/.local/bin`(见 `scripts/install.sh`)。注意:这样装的 `debrief`
+  自己就是个"裸二进制",会被它自己的 `collect` 扫描逮到。
+
+已在真实 Debian 上验证:
+- 两种运行时结果一致 —— `bun run test:apt`(Bun)、`bun run test:node`(纯 Node)。
+- **`npm pack` → 在干净的 node 机器上 `npm i -g` → `debrief collect`/`add hello` 对着真 apt 跑通。**
+- `install.sh` 拉取 + 启动器 + 运行,链路验证过。
+
+> 真正 `npm publish` / 建 Release / 建 apt 仓库还没做(需要账号和授权)——上面验证的是"发出去就能用"。
+
+### 想要"零运行时依赖"?(体积换取)
+
+如果目标机连 node/bun 都不想装,可以退回自包含二进制 / `.deb`(每个 ~100MB,因为把运行时也打进去了):
+
+```bash
+bun run build:bin     # → dist/debrief-linux-{x64,arm64}(自包含,无需运行时)
+bun run build:deb     # → dist/debrief_<ver>_amd64.deb(需 dpkg-deb;NixOS 上在容器里打)
+sudo apt install ./dist/debrief_0.1.0_amd64.deb
+```
+
+`.deb` 有个额外的好处:装完 debrief 就是个正经 dpkg 包,会出现在它自己的 `collect` 里(吃自己的狗粮)。
+
+## 已知边界
+
+- 管理的是**系统级**的包(不是项目本地隔离);这是 apt 的本性。
+- `apt` 后端已在 **Debian 13 (trixie) 容器**里对着真实镜像端到端验证过(见下);开发主机
+  (NixOS)日常用 mock 后端顶替。
+- 依赖解析交给 apt 自己:manifest 只记你主动装的包,依赖只进 lock——正如 npm 只把直接依赖
+  写进 `package.json`。
+
+## 在真实 Debian 上验证
+
+单元测试全程用 mock 后端,任何机器都能跑。`apt` 后端要在真 Debian 上验证,用容器即可:
+
+```bash
+docker run --rm -v "$PWD":/app:ro oven/bun:debian bash /app/test/apt-e2e.sh
+# 受限网络下加 --dns 1.1.1.1
+```
+
+已验证:`collect`/`status` 正确解析 `dpkg-query` + `apt-mark showmanual`(手动装的包进
+manifest、依赖标 `auto:true` 只进 lock、带 `arch`);`status` 能发现绕过工具、直接用 apt 装/删
+的包;`add`/`remove` 走真实 `apt-get install/remove`。
+
+MIT