# xsh-rm

**Repository Path**: drm/xsh-rm

## Basic Information

- **Project Name**: xsh-rm
- **Description**: xsh-rm：轻量级Shell命令管理工具，专注简化日常终端操作，支持自定义别名与快捷指令，提升开发者工作效率。
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-23
- **Last Updated**: 2026-07-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xsh-rm

跨平台、**零第三方依赖**的命令行安全删除工具。

它会先把目标目录**改名**成 32 位随机名，再按平台**隐藏**，最后**逐文件慢删**（每删一个文件 sleep 约 1ms），从而避免误删难以挽回、也避免一次性删除把电脑搞卡。

## 安装

```bash
npm install -g xsh-rm
```

或本地使用：

```bash
git clone <repo>
cd xsh-rm
node bin/xsh-rm.js <目录名> [选项]
```

> 要求 Node.js >= 14。

## 用法

```
xsh-rm <目录名> [选项]
```

| 选项 | 说明 |
| --- | --- |
| `-y, --yes` | 跳过删除前确认（慎用） |
| `-d, --delay <ms>` | 每个文件删除后的睡眠时间（毫秒），默认 `1` |
| `-n, --dry-run` | 只打印将要执行的操作，不实际改名/隐藏/删除 |
| `-h, --help` | 显示帮助并退出 |
| `-v, --version` | 显示版本号并退出 |

## 工作流程

1. **瞬时转移**：把目标目录 `rename` 到「**目标所在盘的根目录下的固定容器 `xsh-rm-temp`**」
   内的一个 32 位十六进制随机名子目录：
   - 容器路径 = `path.join(path.parse(目标).root, 'xsh-rm-temp')`（例：`D:\projects\xsh-rm\mydir`
     → `D:\xsh-rm-temp\<随机名>`）。
   - 容器位于目标所在盘的根目录，天然与源同卷，`rename` 是 O(1) 的元数据操作，**瞬间完成、
     不跨卷退化成复制**；当前目录不留下任何隐藏目录，保持干净。
   - 隐藏：Windows 由后台 worker 调用 `attrib +h`；Unix/macOS 在随机名前加 `.` 前缀。
2. **后台慢删**：父进程立即返回，并 `spawn` 一个 detached 子进程接管逐文件慢删
   （每删完一个文件 `await` 睡眠约 1ms），全过程中**无提示、无日志**。
3. **删完清场**：后台子进程删空随机子目录后，再**移除 `xsh-rm-temp` 容器本身**
   （当容器内还有其他并发删除的随机目录时会因非空而跳过，属正常），做到删完无残留。

### 暂存容器的权限降级

优先把容器建在「目标所在盘的根目录」下（如 `C:\xsh-rm-temp`）。但 Windows 的盘符根目录
（尤其 `C:\`）通常需要管理员权限才能创建目录，会抛 `EACCES`/`EPERM`。此时 xsh-rm **静默降级**
到 `os.tmpdir()` 下的同名容器（如 `C:\Users\<用户>\AppData\Local\Temp\xsh-rm-temp`）：

- 降级过程**不打印任何日志**，行为对调用方透明；
- 降级后容器仍不在当前目录，删除逻辑完全相同（仅当跨盘时 `rename` 会退化成复制，功能正确）；
- 删完后该降级容器同样会被移除，不留残留。

> 因此无论是否发生降级，删除完成后盘根（或临时目录）下的 `xsh-rm-temp` 容器都会被清理掉。

## 安全护栏

- 目标必须是**已存在的目录**，否则报错退出（非零退出码）。
- **拒绝删除危险路径**：绝对路径长度过短，或命中以下任一会被拒绝并退出：
  - 根目录（`/`）
  - 盘符根（如 `C:\`、`D:\`）
  - 用户家目录（`os.homedir()`）
  - 当前工作目录（`process.cwd()`）
  - `.`、`..` 及其解析结果
- **删除前确认**：除非传 `-y/--yes`，否则用 readline 展示目标绝对路径并要求输入 `y` 确认，否则中止。

## 示例

```bash
# 先看看会做什么（不会真正删除）
xsh-rm ./old-project --dry-run

# 真正删除，并跳过确认、把每文件延迟调大到 5ms
xsh-rm ./old-project -y -d 5
```

## 本地验证

```bash
# 运行单元测试
npm test

# 冒烟测试
node bin/xsh-rm.js /path/to/some/temp/dir --dry-run   # 应只打印，不删文件
node bin/xsh-rm.js /path/to/some/temp/dir -y          # 真正改名隐藏后删除
```

## License

MIT