Dirate

Dirate = dir + curate：Bun 驱动的交互式 CLI，可根据 dirs.kdl（兼容旧版 folder.kdl）描述同步与整理 Linux XDG user-dirs 及自定义目录结构。

使用 Bun/TypeScript 编写的交互式工具，可根据 dirs.kdl 描述同步 Linux XDG user-dirs 及自定义目录结构。

安装

Dirate 依赖 Bun >= 1.3.3，可直接通过 bunx 试用，或全局安装：

bunx @boze46/dirate --help
# 或全局安装后直接使用
npm install -g @boze46/dirate
dirate --help

即便通过 npm 安装，CLI 仍通过 #!/usr/bin/env bun 启动，需确保本地已安装 Bun（参考 https://bun.sh/ 安装指南）。

运行方式

bun install
bun run src/index.ts help             # 默认输出帮助
bun run src/index.ts init             # 在 ~/.config/dirate 生成模板 dirs.kdl
bun run src/index.ts sync \
  --dirs ~/.config/dirate/dirs.kdl \
  --config ~/.config/user-dirs.dirs
bun run src/index.ts version

参数说明：

• --dirs: KDL 布局文件路径，默认按顺序查找 $XDG_CONFIG_HOME/dirate/dirs.kdl、./dirs.kdl、./folder.kdl。
• --config: user-dirs.dirs 文件路径，默认 $XDG_CONFIG_HOME/user-dirs.dirs（或 ~/.config/user-dirs.dirs）。
• --dry-run: 仅输出计划与提示，不执行任何写操作。
• --backup-dir: 自定义备份根目录（默认 $HOME/.bak）。
• --yes/-y、--no/-n: 无交互模式，分别全选同意/拒绝（不可同时指定）。
• 子命令：help（默认）、init、sync、version。
• 环境变量等价项：DIRATE_DIRS_PATH、DIRATE_CONFIG_PATH、DIRATE_BACKUP_DIR、DIRATE_DRY_RUN、DIRATE_YES、DIRATE_NO。
• init: 生成一份带注释的 dirs.kdl 模板，便于开始使用。

功能特性

1. KDL 布局解析：home { ... } 树定义目录层级；user-dirs（desktop/download/...）可使用 "新名称" 重命名并支持嵌套。
2. 迁移与备份：对 8 个固定 XDG 目录生成迁移计划，逐步确认；目标存在且非空时提供 备份后替换、合并、删除、跳过 选项。备份统一存储于 $HOME/.bak/<timestamp>/...。
3. 配置同步：迁移后写回 user-dirs.dirs，写入前自动备份；流程结束可选择执行 xdg-user-dirs-update。
4. 自定义目录创建：对非 user-dirs 节点统一 mkdir -p，已存在则跳过。
5. 安全模式：所有写操作均需确认；--dry-run 用于审阅计划。

开发/测试

项目依赖 Bun 1.3+，使用 Bun 作为唯一包管理与运行时。可参考 user-dirs.dirs.sample 与示例 folder.kdl 做 dry-run：

bun run src/index.ts --dry-run \
  --config ./user-dirs.dirs.sample \
  --kdl ./folder.kdl

类型检查：

bun run typecheck

KDL 约定

• 根节点必须为 home。
• 8 个 XDG 目录以英文小写键名：desktop, download, templates, publicshare, documents, music, pictures, videos。
• 需要重命名时使用字符串值：music "audio"；普通目录仅保留名称（可继续嵌套子节点）。