Metadata-Version: 2.4
Name: axwvpm-cli
Version: 0.2.1
Summary: APt - minimal package manager for dotfiles & scripts, multi-ecosystem (apd/apm)
Author: you
Author-email: you <you@example.com>
License: MIT
Project-URL: Homepage, https://github.com/you/apm-repo
Project-URL: Repository, https://github.com/you/apm-repo
Keywords: package-manager,dotfiles,apd,apm,bash
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Environment :: Console
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: requires-python

# apm-cli — Apt Package Manager CLI

一个用 **Python + Bash** 实现的极简包管理器，专为 **dotfiles 和脚本分发** 设计。

> Python 只做薄壳（`pip install` 后给你 `apd` + `apm` 两个命令），**运行时全靠 bash**，不依赖 Python。

---

## 安装

```bash
git clone https://github.com/you/apm-cli.git
cd apm-cli
pip install -e .
```

安装后获得两个命令：
- **`apd`** — Apt Downloader（下载 / 安装 / 更新 / 搜索）
- **`apm`** — Apt Manager（管理 / 打包 / 发布 / 诊断）

---

## 快速开始

```bash
# 配置仓库（指向你的 index.json）
export APM_REPO="https://raw.githubusercontent.com/you/apm-repo/main/index.json"

# 更新索引
apd update

# 搜索 & 安装
apd search vim
apd install mydot-vim

# 管理
apm list
apm info mydot-vim
apm remove mydot-vim
```

---

## 多生态短命令

| 短命令 | 生态 | 示例 |
|--------|------|------|
| `pg` | pkg 索引 | `apd pg vim` |
| `ak` | apk 索引 | `apd ak htop` |
| `pi` | pip (Python) | `apd pi requests` |
| `nm` | npm (Node.js) | `apd nm typescript` |
| `br` | brew (macOS) | `apd br wget` |
| `ap` | apt (Debian/Ubuntu) | `apd ap htop` |
| `yt` | yay (Arch) | `apd yt spotify` |
| `cr` | cargo (Rust) | `apd cr ripgrep` |
| `go` | go install | `apd go install ...` |
| `do` | docker | `apd do nginx:alpine` |
| `sn` | snap | `apd sn code` |
| `fl` | flatpak | `apd fl org.mozilla.firefox` |

每个短命令支持子操作：`install`(默认) / `remove` / `search` / `update` / `download`

```bash
apd eco                # 列出所有生态
apd pg search neovim   # 在 pkg 索引中搜索
apd pi update requests # pip install --upgrade requests
```

---

## 包格式

```
name-version.tar.gz
├── manifest.toml    # 文件映射、权限、依赖、钩子
├── rversion         # 作者、版本、更新日志
└── name/            # 实际脚本/配置文件
    ├── .config/...
    └── sripts/
        ├── post-install.sh
        └── pre-remove.sh
```

### manifest.toml 示例

```toml
name = "mydot-vim"
version = "1.2.0"
description = "我的 Vim/Neovim 配置"

# 文件映射: 包内路径 → 目标路径
[files]
"mydot-vim/.vimrc"          = "~/.vimrc"
"mydot-vim/init.lua"        = "~/.config/nvim/init.lua"

# 权限设置
[permissions]
"~/.config/nvim/init.lua"   = "644"
"~/.local/bin/myhelper"      = "755"

# 依赖声明
[dependencies]
"mydot-bash" = ">=1.0.0"

# 钩子
[hooks]
post_install = "mydot-vim/scripts/post-install.sh"
pre_remove   = "mydot-vim/scripts/pre-remove.sh"
```

### rversion 示例

```
AUTHOR: Your Name
EMAIL: you@example.com
WEBSITE: https://your-site.com
VERSION: 1.2.0
DATE: 2026-08-16

## [1.2.0] - 2026-08-16
### Added
- 新增 Neovim Lua 配置
- 支持 treesitter

### Fixed
- 修复插件管理器路径错误
```

---

## 完整命令列表

### apd (下载器)

| 命令 | 说明 |
|------|------|
| `apd install <包> [版本]` | 安装包 |
| `apd update [包]` | 更新包（不指定=全部） |
| `apd remove <包>` | 卸载包 |
| `apd search <关键词>` | 搜索包 |
| `apd download <包> [版本]` | 仅下载不安装 |
| `apd list` | 已安装列表 |
| `apd info <包>` | 包信息 |
| `apd eco` | 生态列表 |

### apm (管理器)

| 命令 | 说明 |
|------|------|
| `apm list` | 已安装列表 |
| `apm info <包>` | 详细信息（含 rversion） |
| `apm remove <包>` | 卸载（支持 `pip:xxx` 前缀） |
| `apm pack` | 打包当前目录 → `name-version.tar.gz` |
| `apm publish <file>` | 发布包（更新索引 + 上传） |
| `apm version <包> <ver>` | 切换版本 |
| `apm freeze [file]` | 导出锁文件（默认 stdout） |
| `apm restore <file>` | 从锁文件恢复全部包 |
| `apm verify` | 校验所有已装文件完整性 |
| `apm which <文件>` | 查询文件属于哪个包 |
| `apm doctor` | 系统诊断 |
| `apm log [today\|1day\|3days\|stats]` | 操作审计日志 |
| `apm init [名] [版本] [描述]` | 创建新包脚手架 |
| `apm completion [bash\|zsh]` | Shell 补全脚本 |
| `apm clean-bak` | 清理 .bak 残留 |

---

## 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `APM_REPO` | 默认索引 URL | GitHub raw |
| `APM_REPO_PKG` | pkg 索引 URL | GitHub raw |
| `APM_REPO_APK` | apk 索引 URL | GitHub raw |
| `APM_DB` | 数据库路径 | `~/.local/share/apm/installed.json` |
| `APM_CACHE` | 缓存目录 | `~/.cache/apm` |
| `APM_INDEX_REPO` | 索引 Git 仓库地址 | GitHub |
| `APM_PACKAGE_BASE_URL` | 包下载基础 URL | GitHub releases |
| `APM_S3_BUCKET` | S3 上传桶 | — |
| `APM_RSYNC_HOST` | rsync 目标 | — |
| `APM_FORCE` | 强制覆盖冲突文件 | `0` |
| `APM_OFFLINE` | 离线模式 | `0` |

---

## 项目结构

```
apm-cli/
├── setup.py                # pip 安装入口
├── README.md
├── apm/
│   ├── __init__.py
│   └── cli.py             # Python 薄壳，仅转发给 bash
├── sh/
│   ├── apd.sh             # 下载器（install/update/search/download/eco）
│   ├── apm.sh             # 管理器（list/info/remove/pack/publish/version/freeze/restore/verify/which/doctor/log/init/completion/clean-bak）
│   └── lib/
│       ├── detect.sh       # 工具链检测
│       ├── fetch.sh        # 下载（aria2c/curl/wget 降级 + file:// + 错误检测）
│       ├── verify.sh       # SHA256 + GPG 校验
│       ├── extract.sh      # 解包部署 + 权限 + 钩子 + 冲突检测
│       ├── deps.sh         # 依赖递归安装
│       ├── rollback.sh     # 事务快照 + 回滚
│       ├── version.sh      # 版本切换（symlink 管理）
│       ├── ecosystem.sh    # 12 个生态定义中心
│       ├── publish.sh      # 更新 index.json + S3/rsync 上传
│       ├── freeze.sh       # 锁文件导出/恢复 + 文件校验 + which 查询
│       ├── doctor.sh       # 系统诊断
│       ├── log.sh          # 操作审计日志
│       ├── init.sh         # 交互式脚手架生成
│       └── completion.sh   # bash/zsh 自动补全
├── examples/
│   └── mydot-demo/        # 示例包（manifest.toml + rversion + 目录结构）
└── index-repo/
    ├── README.md
    └── index.json         # 索引示例
```

---

## 典型工作流

### 开发者：创建并发布包

```bash
# 1. 创建脚手架
cd ~/projects
apm init mydot-vim 1.0.0 "我的 Vim 配置"

# 2. 编辑 manifest.toml，把实际文件放进 mydot-vim/
vim mydot-vim/manifest.toml
cp ~/.vimrc mydot-vim/.vimrc

# 3. 打包
apm pack
# → mydot-vim-1.0.0.tar.gz

# 4. 发布（自动更新 index.json + 上传）
apm publish mydot-vim-1.0.0.tar.gz
```

### 用户：一键恢复环境

```bash
# 在新机器上
pip install apm-cli
export APM_REPO="https://raw.githubusercontent.com/you/apm-repo/main/index.json"

# 从锁文件恢复全部包
apm restore my-lock-file
```

### 用户：导出当前环境

```bash
apm freeze > my-lock-file
# 提交到 Git，换机器时直接 restore
```

---

## 设计原则

1. **Python 只是安装入口** — 运行时零 Python 依赖
2. **Bash 做所有脏活** — 下载、解包、部署、校验全在 sh 里
3. **数据库是 JSON** — 人类可读，jq 可查，git 可 diff
4. **包格式简单** — tar.gz + toml 元数据，不发明新格式
5. **生态可扩展** — 加新生态只改 `ecosystem.sh` 一个文件

---

## License

MIT
