Metadata-Version: 2.4
Name: hicmd
Version: 0.1.0
Summary: 基于 Conan 2.x 的鸿蒙 PC 系统包管理器 — 制品投影层
Author: OpenHarmony PC Developer
License-Expression: Apache-2.0
Project-URL: Homepage, https://gitcode.com/OpenHarmonyPCDeveloper/hicmd
Project-URL: Repository, https://gitcode.com/OpenHarmonyPCDeveloper/hicmd
Project-URL: Issues, https://gitcode.com/OpenHarmonyPCDeveloper/hicmd/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Software Distribution
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: portalocker>=2.7
Requires-Dist: requests>=2.25
Requires-Dist: urllib3>=1.26
Requires-Dist: colorama>=0.4
Requires-Dist: patch-ng>=1.18
Requires-Dist: fasteners>=0.15
Requires-Dist: distro>=1.4
Requires-Dist: Jinja2>=3.0
Requires-Dist: python-dateutil>=2.8
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Dynamic: license-file

# hicmd

基于 Conan 2.x 二次开发的命令行包管理器，面向鸿蒙 PC（OpenHarmony PC）系统软件的安装、投影与生命周期管理。

## 定位

hicmd **不取代 Conan**，而是 Conan 制品仓之上的**系统投影层（projection layer）**：

- **Conan 负责**：依赖解析、graph 构建、package_id 计算、远端协议、本地 cache 拉取
- **hicmd 负责**：把 cache 里的预编译制品**暴露成可运行/可链接的系统入口**，处理冲突、反向依赖、版本切换
- **包索引**：hicmd 维护独立的包索引（`index/packages.json`），用户通过包名安装，不感知 Conan ref 格式

对标 Homebrew 的用户体验，但底层依赖解析复用 Conan，不重复造轮子。

## 核心设计思想

1. **统一 prefix + symlink 汇聚** —— 所有包投影到同一个 `<prefix>/`，bin/lib/include 各自汇聚。用户只需配置一次 `PATH`/`LD_LIBRARY_PATH`/`CMAKE_PREFIX_PATH`，装任何包后自动生效。
2. **三层元数据策略** —— 标准 conan 包不可改，投影元数据从包内 `cpp_info` 自动推断（80%）+ 文件启发式（10%）+ 外部 override 仓库（10%）。
3. **Manifest DB 为唯一事实来源** —— SQLite 单文件，记录"装了什么、装在哪、谁依赖谁、暴露了什么"。
4. **默认拒绝冲突** —— 不做自动决策，路径冲突默认报错，用户显式 `--force` 覆盖。
5. **包索引驱动** —— hicmd 维护 `index/packages.json` 作为可用包目录，`hicmd update` 通过纯 HTTP 下载索引，`hicmd search` 基于本地索引，不依赖 Conan search API。

## 快速上手

```bash
hicmd init                  # 初始化 prefix + 写 shell 配置
hicmd update                # 更新包索引（纯 HTTP 下载）
hicmd install <pkg>         # 安装（下载 + 投影）
hicmd search [keyword]      # 搜索本地包索引（无参数列出全部）
hicmd list                  # 列出已装包
hicmd info <pkg>            # 包详情 + 依赖链
hicmd uninstall <pkg>       # 卸载（反向依赖检查 + 精确回收）
hicmd autoremove            # 清理不再被需要的依赖包
hicmd upgrade <pkg>         # 升级到最新版本
hicmd switch <pkg> <ver>    # 切换已安装包的 link 版本
hicmd link <pkg>            # 将 unlinked 的包暴露到汇聚区
hicmd unlink <pkg>          # 将包从汇聚区移除（保留 Cellar）
hicmd doctor                # 环境诊断
```

安装命令支持多种语法：

```bash
hicmd install zlib                    # 包名（自动选最新版本）
hicmd install zlib==1.3.1             # pip 风格（包名==版本）
hicmd install zlib/1.3.1              # Conan 风格兼容
hicmd install zlib/1.3.1 # 完整 ref
```

## 文档索引

| 文档 | 内容 |
|------|------|
| [架构设计](docs/01-architecture.md) | 四层模型、组件职责、与 Conan 的边界 |
| [目录布局](docs/02-directory-layout.md) | hicmd 与 Conan 各自的目录边界，**鸿蒙 PC 差异点标注** |
| [Manifest DB](docs/03-manifest-db.md) | SQLite 表结构、事务模型、查询样例 |
| [安装流程与冲突仲裁](docs/04-install-flow.md) | 投影流程、冲突类型、仲裁策略、统一 env |
| [元数据策略](docs/05-metadata-strategy.md) | 三层推断、override 仓库结构、schema 契约 |
| [Conan API 适配](docs/06-conan-api.md) | Conan 2.x Python API 用法、PoC 验证结论 |
| [MVP 开发路线](docs/07-roadmap.md) | 分阶段实现顺序与验收标准 |

## 制品仓

- 仓库地址：`https://cnb.cool/OpenHarmonyPCDeveloper/Conan`
- 远端配置：`conan remote add ohpcd https://conan.cnb.cool/OpenHarmonyPCDeveloper/Conan/-/packages/`
- 制品为标准 Conan 2.x 包，由专门团队按 conan 协议上传，不可修改
- 包索引远端：`https://gitcode.com/api/v5/repos/OpenHarmonyPCDeveloper/hicmd/raw/index/packages.json?ref=main`，纯 HTTP 下载（urllib），无 git 依赖

## 安装

```bash
# 从源码安装（开发模式）
pip install -e .

# 从 sdist 安装
pip install dist/hicmd-0.1.0.tar.gz

# 开发依赖（含 pytest、build）
pip install -e ".[dev]"
```

## 开发

```bash
# 运行全部测试（94 个：87 单元 + 7 集成）
python -m pytest tests/ -v

# 构建 sdist
python -m build --sdist
```

## 技术栈

- **语言**：Python 3.11+（直接复用 Conan API，无跨语言开销）
- **CLI 框架**：Click / Typer
- **存储**：SQLite（标准库自带）
- **输出**：Rich（彩色、进度条、表格）
- **依赖**：conan >= 2.0

## 鸿蒙 PC 适配说明

本文档已基于鸿蒙 PC 真机环境（HongMeng Kernel 1.12.0, aarch64, OHOS）完成验证。所有涉及文件系统路径、环境变量、动态库加载的差异点均已确认并修正为鸿蒙实际值。

### 已确认的关键环境事实

| 项目 | 鸿蒙实际值 |
|------|-----------|
| 可写根路径 | `$HOME`（`/storage/Users/currentUser`），`/opt` 不存在、`/data` 不可写、`/tmp` 只读 |
| 交互 Shell | zsh（`/usr/bin/zsh`），rc 文件为 `~/.zshrc`；系统 shell 为 `/system/bin/sh` |
| Conan home | `$HOME/.conan2`，可持久化写入 |
| Conan profile | `os=OHOS`（非 Linux），`arch=armv8`，`compiler=clang/15` |
| LD_LIBRARY_PATH | 标准名称，已生效，无需 ldconfig（鸿蒙无 ldconfig） |
| symlink | 完整支持，在 `$HOME` 下正常创建和解析 |
| 可执行文件格式 | ELF（ARM64），magic number 判断不受影响 |
| 无 SELinux | 无额外执行限制 |

### 与用户现有环境的隔离

用户 `.zshrc` 已配置 `$HOME/usr/local` 作为手动安装前缀（bin/lib/include + PATH + LD_LIBRARY_PATH + CMAKE_PREFIX_PATH）。hicmd 使用独立的 `$HOME/.hicmd` 作为 prefix，两者物理隔离、互不干扰。

## 开源协议

hicmd 使用 [Apache License 2.0](LICENSE) 开源协议。

第三方依赖及其协议声明见 [NOTICE](NOTICE) 文件。

- Conan 2.x — MIT License
- Click — BSD-3-Clause License
- Rich — MIT License
- PyYAML — MIT License
- portalocker — BSD-3-Clause License
