xtap-core-lib 0.5.1

# xTap Core Lib

> A Rust foundation library by 星TAP实验室 (StarTAP Labs). Cross-platform paths / IO / hardware info / MCP HTTP server / egui theming — modular via Cargo features.

[![crates.io](https://img.shields.io/crates/v/xtap-core-lib)](https://crates.io/crates/xtap-core-lib)
[![docs.rs](https://img.shields.io/docsrs/xtap-core-lib)](https://docs.rs/xtap-core-lib)
[![license](https://img.shields.io/crates/l/xtap-core-lib)](https://crates.io/crates/xtap-core-lib)
[![downloads](https://img.shields.io/crates/d/xtap-core-lib)](https://crates.io/crates/xtap-core-lib)

[中文版](#中文版--chinese) · [English version](#english-version)

---

## English version

A modular Rust foundation for CLI/GUI tools. Pull in only what you need (`features = ["path", "mcp"]`) — the rest never enters the compile graph.

### What you get

- **`path`** — cross-platform home dir, path canonicalization, cache-dir helpers (macOS / Windows / Linux)
- **`io`** — file read/write, async IO (tokio), memory-mapped files (memmap2)
- **`mcp`** — zero-boilerplate MCP HTTP server (`axum`-based): `GET /health`, `GET /tools`, `service / version / tools` discovery out of the box; merge your own routes via `.merge(...)`
- **`ui`** — egui theme + font config (dark Nordic style)
- **`hardware`** — CPU info, parallel iterators (rayon)
- **`process`** — system info (sysinfo)
- **`error` / `shell`** — always compiled, no features needed

### Quick start

```toml
[dependencies]
xtap-core-lib = "0.5"
```

Or with specific features:

```toml
[dependencies]
xtap-core-lib = { version = "0.5", default-features = false, features = ["path", "mcp"] }
```

```rust
use xtap_core_lib::path::get_home_dir;

fn main() -> xtap_core_lib::error::Result<()> {
    let home = get_home_dir()?;
    println!("home: {}", home.display());
    Ok(())
}
```

> Note: crate name `xtap-core-lib` is written as `xtap_core_lib` in Rust code (hyphens → underscores). Full API docs at [docs.rs/xtap-core-lib](https://docs.rs/xtap-core-lib).

### Features

| Feature | Module | Purpose |
|---------|--------|---------|
| `default` | process, path, io, hardware, ui | All-in-one baseline |
| `process` | `process` | Process / system info (sysinfo) |
| `path` | `path` | Cross-platform home / path helpers (dirs) |
| `io` | `io` | Sync file IO |
| `async` | `io::async_io` | Async IO (tokio) |
| `mmap` | `io::mmap` | Memory-mapped files (memmap2) |
| `hardware` | `hardware` | CPU info, parallel iter (num_cpus, rayon) |
| `gpu` | — | GPU init (wgpu, heavy, opt-in) |
| `self_check` | `self_check` | Runtime self-check |
| `ui` | `ui` | egui theme + font + icons |
| `mcp` | `mcp` | MCP HTTP server (axum, tokio) |
| `gui` | — | Marker (combine with `ui`) |

### Constraints

- Edition 2021, license MIT, version `0.5.0`
- `error` / `shell` are always compiled (no feature needed)
- The `ui` fonts/icons resolve at runtime — **no assets are bundled**, so the published crate stays small
- All dependency versions are inlined (no `workspace = true`), so the crate is self-contained and publishes cleanly to crates.io

### Development

```bash
cargo check                  # compile check
cargo test                   # unit tests
cargo clippy --all-targets -- -D warnings   # zero-warning gate
cargo package --allow-dirty  # pack check
```

### License

MIT © 2026 星TAP实验室 (StarTAP Labs)

---

## 中文版 / Chinese

星TAP实验室通用 Rust 基座库。跨平台路径 / IO / 硬件信息 / MCP HTTP 服务 / egui 主题与字体，features 按需裁剪。

### 这库是干嘛的？（人话版）

**有什么用？**
把多个星TAP项目（ARLink、sts-x、初色等）共用的基础设施——路径解析、文件 IO、硬件检测、MCP 服务器、界面主题——抽出来做成一个独立库。写新 Rust 工具时，`Cargo.toml` 加一行依赖就能拿到全套，不用每个项目从零复制。

**给我什么好处？**
- 一个依赖 = 全套基座，新项目秒级起步
- **features 按需裁剪**：只要路径功能就只编路径，二进制不拖泥带水
- 单测 + clippy 门禁，核心逻辑经过多项目实战打磨

**为什么用它（而不是别的）？**
市面上没有"星TAP风格"的整合基座：路径（dirs 跨平台 home 解析）、MCP HTTP 服务器（axum 极简路由）、egui 主题/字体（深色北欧风）已经按我们的工程习惯封装好。用现成 crate 拼要自己接线，这个库帮你接好了。

**跟我有什么关系？**
- **写 Rust 工具的人**：`xtap-core-lib = { version = "0.5", features = ["path", "mcp"] }` 直接用
- **想省事的人**：不用研究 dirs / axum / egui 各自怎么配，这里统一了

### 快速开始

```toml
[dependencies]
xtap-core-lib = { version = "0.5", features = ["path", "mcp"] }
```

```rust
use xtap_core_lib::path::get_home_dir;
```

### Features 表（可机读）

| Feature | 激活模块 | 依赖 | 说明 |
|---------|---------|------|------|
| `default` | process,path,io,hardware,ui | 全量 | 开箱即用 |
| `process` | `process` | sysinfo | 进程/系统信息 |
| `path` | `path` | dirs | 跨平台 home/路径解析 |
| `io` | `io` | — | 文件 IO 工具 |
| `async` | `io::async_io` | tokio | 异步 IO |
| `mmap` | `io::mmap` | memmap2 | 内存映射文件 |
| `hardware` | `hardware` | num_cpus, rayon | CPU/硬件信息 |
| `gpu` | — | wgpu | GPU 初始化（重依赖，按需） |
| `self_check` | `self_check` | — | 自检模块 |
| `ui` | `ui` | egui, eframe, image | egui 主题/字体/图标 |
| `mcp` | `mcp` | axum, tokio, serde_json | MCP HTTP 服务 |
| `gui` | — | — | GUI 标记（配合 ui） |

### 组合建议（实测通过）

```bash
# 最小路径+MCP（服务器场景）
cargo check --no-default-features --features "path,mcp"

# 全量默认
cargo check

# 纯工具集（无 GUI/GPU）
cargo check --no-default-features --features "process,path,io,hardware"
```

### 约束（护栏）

- edition 2021，license MIT，版本保持 0.5.0
- `error` / `shell` 模块无条件编译（不依赖任何 feature）
- `ui` feature 的字体/图标走系统路径，**不打包 assets**，发布包更小
- 依赖版本已内联（无 workspace 继承），可独立发布

### License

MIT © 2026 星TAP实验室