@tq1086/urpf-cli 1.0.0

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@tq1086/urpf-cli",
+  "version": "1.0.0",
+  "description": "URPF CLI 工具 - 基于 URPF v1.0 规范的命令行打包工具",
+  "main": "dist/index.js",
+  "bin": {
+    "urpf-cli": "dist/index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "test": "vitest",
+    "test:coverage": "vitest --coverage",
+    "lint": "eslint src --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "urpf",
+    "pack",
+    "cli",
+    "universal-resource-package-format",
+    "file-packaging",
+    "archive"
+  ],
+  "author": "",
+  "license": "ISC",
+  "homepage": "https://gitcode.com/tq1086/urpf-cli",
+  "repository": {
+    "type": "git",
+    "url": "git@gitcode.com:tq1086/urpf-cli.git"
+  },
+  "bugs": {
+    "url": "https://gitcode.com/tq1086/urpf-cli/issues"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/node": "^25.1.0",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/ui": "^4.0.18",
+    "eslint": "^9.39.2",
+    "prettier": "^3.8.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.54.0",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "@tq1086/urpf-sdk": "^0.1.0",
+    "commander": "^14.0.2"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/readme.md

@@ -0,0 +1,631 @@
+# URPF CLI 工具
+
+基于 URPF (Universal Resource Package Format) v1.0 规范的命令行打包工具。
+
+## 项目链接
+
+- **首页**: https://gitcode.com/tq1086/urpf-cli
+- **仓库**: git@gitcode.com:tq1086/urpf-cli.git
+- **问题反馈**: https://gitcode.com/tq1086/urpf-cli/issues
+
+## 功能特性
+- ✅ 将文件或目录打包成 URPF 格式
+- ✅ 从 URPF 文件中解包资源到文件系统
+- ✅ 向已有 URPF 包添加文件或目录
+- ✅ 从 URPF 包中移除文件（支持变量替换）
+- ✅ 支持 `.gitignore` 风格的忽略规则
+- ✅ 自动检测文件编码和换行符类型
+- ✅ 保留文件权限和元数据
+- ✅ 跨平台支持（Windows、Linux、macOS）
+
+## 安装
+
+```bash
+# 全局安装
+npm install -g @tq1086/urpf-cli
+
+# 本地安装
+npm install @tq1086/urpf-cli
+```
+
+## 使用方法
+
+### 基本用法
+
+#### 打包命令 (pack)
+
+```bash
+# 打包单个文件
+urpf-cli pack package.json
+
+# 打包目录
+urpf-cli pack src/
+
+# 指定输出路径
+urpf-cli pack src/ -o output.urpf
+
+# 显示详细日志
+urpf-cli pack src/ -v
+```
+
+#### 解包命令 (unpack)
+
+```bash
+# 解包到当前目录
+urpf-cli unpack package.urpf
+
+# 解包到指定目录
+urpf-cli unpack package.urpf -o ./output
+
+# 显示详细日志
+urpf-cli unpack package.urpf -v
+
+# 强制覆盖已存在的文件
+urpf-cli unpack package.urpf --force
+
+# 仅当源文件更新时才覆盖
+urpf-cli unpack package.urpf --force-when-newer
+```
+
+#### 添加文件命令 (pack-add)
+
+```bash
+# 向已有 URPF 包添加单个文件
+urpf-cli pack-add package.urpf newfile.txt
+
+# 向已有 URPF 包添加目录
+urpf-cli pack-add package.urpf newdir/
+
+# 不递归扫描子目录
+urpf-cli pack-add package.urpf newdir/ --no-recurse
+
+# 显示详细日志
+urpf-cli pack-add package.urpf newfile.txt -v
+
+# 使用自定义忽略规则
+urpf-cli pack-add package.urpf newdir/ -i .myignore
+```
+
+#### 移除文件命令 (pack-remove)
+
+```bash
+# 从 URPF 包中移除单个文件
+urpf-cli pack-remove package.urpf oldfile.txt
+
+# 支持通配符匹配
+urpf-cli pack-remove package.urpf "old*.txt"
+
+# 支持问号通配符
+urpf-cli pack-remove package.urpf "file?.txt"
+
+# 使用变量替换
+urpf-cli pack-remove package.urpf "${root}/config.json"
+
+# 不应用变量替换
+urpf-cli pack-remove package.urpf "${root}/config.json" --no-apply-variables
+
+# 显示详细日志
+urpf-cli pack-remove package.urpf oldfile.txt -v
+```
+
+### 命令选项
+
+#### pack 命令选项
+
+| 选项 | 描述 | 默认值 |
+| :--- | :--- | :--- |
+| `-o, --output <path>` | 输出文件路径 | 输入路径.urpf |
+| `-v, --verbose` | 显示详细日志 | false |
+| `-i, --ignore <path>` | 指定忽略规则文件 | 自动检测 .gitignore/.iflowignore |
+| `-f, --follow-symlinks` | 跟随符号链接 | false |
+| `-d, --max-depth <number>` | 最大扫描深度（0 表示无限制） | 0 |
+| `--no-recurse` | 不递归扫描子目录 | false |
+| `--force` | 强制覆盖已存在的输出文件 | false |
+
+#### unpack 命令选项
+
+| 选项 | 描述 | 默认值 |
+| :--- | :--- | :--- |
+| `-o, --output <path>` | 输出目录路径 | 当前目录 |
+| `-v, --verbose` | 显示详细日志 | false |
+| `--force` | 强制覆盖已存在的文件 | false |
+| `--force-when-newer` | 仅当源文件比目标文件更新时才覆盖 | false |
+| `--preserve-mtime` | 保留原始修改时间 | false |
+
+#### pack-add 命令选项
+
+| 选项 | 描述 | 默认值 |
+| :--- | :--- | :--- |
+| `-v, --verbose` | 显示详细日志 | false |
+| `-i, --ignore <path>` | 指定忽略规则文件 | 自动检测 .gitignore/.iflowignore |
+| `-f, --follow-symlinks` | 跟随符号链接 | false |
+| `-d, --max-depth <number>` | 最大扫描深度（0 表示无限制） | 0 |
+| `--no-recurse` | 不递归扫描子目录 | false |
+
+#### pack-remove 命令选项
+
+| 选项 | 描述 | 默认值 |
+| :--- | :--- | :--- |
+| `-v, --verbose` | 显示详细日志 | false |
+| `--no-apply-variables` | 不应用变量替换 | true |
+
+### 使用示例
+
+#### 示例 1：打包项目目录
+
+```bash
+urpf-cli pack ./my-project -o my-project.urpf -v
+```
+
+输出：
+```
+✅ URPF 文件已生成: my-project.urpf
+  文件数量: 42
+  目录数量: 8
+  跳过文件: 5
+  URPF 大小: 123456 字节
+  执行耗时: 234ms
+```
+
+#### 示例 2：使用自定义忽略规则
+
+```bash
+urpf-cli pack ./src -o src.urpf -i .myignore -v
+```
+
+#### 示例 3：打包单个文件
+
+```bash
+urpf-cli pack config.json -o config.urpf
+```
+
+#### 示例 4：不递归扫描子目录
+
+```bash
+urpf-cli pack ./src --no-recurse -o src-top-level.urpf
+```
+
+此命令只打包 `src` 目录的顶层文件，不包含子目录。
+
+#### 示例 5：强制覆盖已存在的文件
+
+```bash
+urpf-cli pack ./my-project -o my-project.urpf --force
+```
+
+如果 `my-project.urpf` 已存在，使用 `--force` 选项会强制覆盖它。
+
+### 解包示例
+
+#### 示例 1：基本解包
+
+```bash
+urpf-cli unpack my-project.urpf
+```
+
+输出：
+```bash
+✅ URPF 文件已解包到: /current/directory
+  创建: 42
+  覆盖: 0
+  跳过: 0
+  总字节: 123456
+  执行耗时: 234ms
+```
+
+#### 示例 2：解包到指定目录
+
+```bash
+urpf-cli unpack my-project.urpf -o ./extracted
+```
+
+#### 示例 3：强制覆盖已存在的文件
+
+```bash
+# 第一次解包
+urpf-cli unpack my-project.urpf -o ./output
+
+# 修改一些文件
+echo "modified" > ./output/somefile.txt
+
+# 第二次解包（不使用 --force 会失败）
+urpf-cli unpack my-project.urpf -o ./output
+# 错误: 文件已存在: somefile.txt。请使用 --force 选项强制覆盖，或使用 --force-when-newer 选项仅覆盖更新的文件。
+
+# 使用 --force 强制覆盖
+urpf-cli unpack my-project.urpf -o ./output --force
+```
+
+#### 示例 4：仅覆盖更新的文件
+
+```bash
+urpf-cli unpack my-project.urpf -o ./output --force-when-newer -v
+```
+
+输出：
+```bash
+已创建: ./output/newfile.txt
+跳过（目标文件更新）: ./output/oldfile.txt
+跳过（目标文件更新）: ./output/anotherfile.txt
+✅ URPF 文件已解包到: ./output
+  创建: 1
+  覆盖: 0
+  跳过: 2
+  总字节: 1024
+  执行耗时: 123ms
+```
+
+#### 示例 5：保留原始修改时间
+
+```bash
+urpf-cli unpack my-project.urpf -o ./output --preserve-mtime
+```
+
+### 添加文件示例
+
+#### 示例 1：添加单个文件到 URPF 包
+
+```bash
+# 创建初始 URPF 包
+urpf-cli pack ./my-project -o my-project.urpf
+
+# 添加新文件
+urpf-cli pack-add my-project.urpf newfile.txt
+```
+
+输出：
+```bash
+✅ 已成功添加文件到 URPF 包: my-project.urpf
+  添加文件: 1
+  跳过文件: 0
+  总字节: 1024
+  执行耗时: 123ms
+```
+
+#### 示例 2：添加目录到 URPF 包
+
+```bash
+urpf-cli pack-add my-project.urpf ./new-module/
+```
+
+#### 示例 3：不递归添加目录
+
+```bash
+urpf-cli pack-add my-project.urpf ./new-module/ --no-recurse
+```
+
+此命令只添加 `new-module` 目录的顶层文件，不包含子目录。
+
+#### 示例 4：使用自定义忽略规则
+
+```bash
+urpf-cli pack-add my-project.urpf ./new-module/ -i .myignore -v
+```
+
+### 移除文件示例
+
+#### 示例 1：移除单个文件
+
+```bash
+urpf-cli pack-remove my-project.urpf oldfile.txt
+```
+
+输出：
+```bash
+✅ 已成功从 URPF 包移除文件: my-project.urpf
+  移除文件: 1
+  未找到: 0
+  执行耗时: 89ms
+```
+
+#### 示例 2：使用通配符移除多个文件
+
+```bash
+# 移除所有 .log 文件
+urpf-cli pack-remove my-project.urpf "*.log"
+
+# 移除所有以 old 开头的文件
+urpf-cli pack-remove my-project.urpf "old*"
+```
+
+#### 示例 3：移除子目录中的文件
+
+```bash
+urpf-cli pack-remove my-project.urpf "subdir/oldfile.txt"
+```
+
+#### 示例 4：使用变量替换
+
+首先，创建一个包含变量定义的 URPF 文件：
+
+```bash
+# 创建 URPF 文件（假设包含属性部分）
+urpf-cli pack ./my-project -o my-project.urpf
+```
+
+然后，使用变量替换移除文件：
+
+```bash
+# 移除 ${root}/config.json
+urpf-cli pack-remove my-project.urpf "${root}/config.json" -v
+```
+
+输出：
+```bash
+Variable replacement: ${root}/config.json -> subdir/config.json
+Successfully removed 1 files: my-project.urpf
+  Removed files:
+    - file://subdir/config.json
+  Not found count: 0
+  Duration: 123ms
+```
+
+#### 示例 5：处理不存在的文件
+
+```bash
+urpf-cli pack-remove my-project.urpf nonexistent.txt
+```
+
+输出：
+```bash
+✅ 已成功从 URPF 包移除文件: my-project.urpf
+  移除文件: 0
+  未找到: 1
+  执行耗时: 45ms
+```
+
+## 高级功能
+
+### 忽略规则
+
+URPF CLI 支持 `.gitignore` 风格的忽略规则，可以自动检测并应用以下文件：
+- `.gitignore`
+- `.iflowignore`
+- `.npmignore`
+
+也可以通过 `-i` 选项指定自定义的忽略规则文件。
+
+**忽略规则示例**：
+```gitignore
+# 忽略 node_modules 目录
+node_modules/
+
+# 忽略所有 .log 文件
+*.log
+
+# 忽略 build 目录
+build/
+
+# 忽略 .env 文件
+.env
+```
+
+### 递归控制
+
+默认情况下，`pack` 命令会递归扫描所有子目录。使用 `--no-recurse` 选项可以只打包当前目录的文件：
+
+```bash
+# 递归打包（默认）
+urpf-cli pack ./src
+
+# 只打包顶层文件
+urpf-cli pack ./src --no-recurse
+```
+
+### 输出文件控制
+
+使用 `-o` 或 `--output` 选项指定输出文件路径：
+
+```bash
+# 相对路径
+urpf-cli pack ./src -o ./output/src.urpf
+
+# 绝对路径
+urpf-cli pack ./src -o /tmp/src.urpf
+
+# 自定义文件名
+urpf-cli pack ./src -o my-package.urpf
+```
+
+### 覆盖已存在的文件
+
+如果输出文件已存在，`pack` 命令会报错并提示用户。使用 `--force` 选项可以强制覆盖：
+
+```bash
+# 第一次打包
+urpf-cli pack ./my-project -o my-project.urpf
+
+# 第二次打包（不使用 --force 会失败）
+urpf-cli pack ./my-project -o my-project.urpf
+# 错误: 输出文件已存在: my-project.urpf。请使用 --force 选项强制覆盖，或指定不同的输出路径。
+
+# 使用 --force 强制覆盖
+urpf-cli pack ./my-project -o my-project.urpf --force
+```
+
+## 变量替换
+
+`pack-remove` 命令支持变量替换功能，可以从 URPF 文件的属性部分读取变量定义，并在移除文件时应用这些变量。
+
+### 变量定义
+
+在 URPF 文件的属性部分定义变量：
+
+```
+--URPF-BOUNDARY-a1b2c3d4--
+
+$root=subdir
+$version=1.0.0
+
+--URPF-BOUNDARY-a1b2c3d4--
+
+@file://${root}/config.json utf-8 644 lf
+{"name": "my-app", "version": "${version}"}
+
+--URPF-BOUNDARY-a1b2c3d4--
+```
+
+### 使用变量
+
+在 `pack-remove` 命令中使用变量：
+
+```bash
+# 移除 ${root}/config.json（实际移除 subdir/config.json）
+urpf-cli pack-remove package.urpf "${root}/config.json"
+
+# 移除 ${version}.txt（实际移除 1.0.0.txt）
+urpf-cli pack-remove package.urpf "${version}.txt"
+```
+
+## URPF 文件格式
+
+URPF 是一种用于打包、分发和精确描述多个关联资源的通用文本格式。它通过边界分隔符组织多个独立部分，每个部分可包含属性定义或资源内容。
+
+### 格式示例
+
+```
+--URPF-BOUNDARY-a1b2c3d4--
+
+$project=/home/user/project
+$version=1.0.0
+
+--URPF-BOUNDARY-a1b2c3d4--
+
+@file://${project}/config.json utf-8 644 lf
+{
+  "name": "my-project",
+  "version": "1.0.0"
+}
+
+--URPF-BOUNDARY-a1b2c3d4--
+
+@file://${project}/src/index.js utf-8 644 lf
+console.log("Hello, World!");
+
+--URPF-BOUNDARY-a1b2c3d4--
+```
+
+### 规范说明
+
+- **边界令牌**：8位十六进制数字，用于分隔不同的部分
+- **属性部分**：以 `$` 开头的变量定义
+- **资源部分**：以 `@` 开头的资源引用，包含 UDRS 引用、编码、权限和换行符类型
+- **资源引用**：遵循 UDRS v1.1 规范，支持文件协议和非文件协议
+
+详细规范请参考 [URPF v1.0 规范文档](./goal.md)。
+
+## 忽略规则
+
+工具支持 `.gitignore` 风格的忽略规则，可以自动检测以下文件：
+- `.gitignore`
+- `.iflowignore`
+- `.npmignore`
+
+### 忽略规则示例
+
+```
+# 忽略 node_modules 目录
+node_modules/
+
+# 忽略所有日志文件
+*.log
+
+# 忽略临时文件
+*.tmp
+temp/
+
+# 忽略特定目录
+dist/
+build/
+
+# 但不忽略 dist/config.json
+!dist/config.json
+```
+
+## 开发
+
+### 构建
+
+```bash
+npm run build
+```
+
+### 测试
+
+```bash
+# 运行所有测试
+npm test
+
+# 运行测试并显示覆盖率
+npm run test:coverage
+```
+
+### 代码检查
+
+```bash
+# ESLint 检查
+npm run lint
+
+# 代码格式化
+npm run format
+```
+
+## 项目结构
+
+```
+urpfcli/
+├── src/
+│   ├── commands/       # 命令实现
+│   │   ├── pack.ts
+│   │   ├── unpack.ts
+│   │   └── types.ts
+│   ├── core/
+│   │   ├── parser/      # URPF 解析器
+│   │   ├── scanner/     # 文件扫描器
+│   │   ├── generator/   # URPF 生成器
+│   │   └── engine/      # UDRS 集成层
+│   ├── utils/          # 工具函数
+│   └── index.ts        # CLI 入口
+├── tests/              # 测试文件
+│   ├── integration/    # 集成测试
+│   └── fixtures/       # 测试数据
+├── dist/               # 编译输出
+└── package.json
+```
+
+## 技术栈
+
+- **语言**: TypeScript
+- **模块系统**: ESM (ECMAScript Modules)
+- **运行时**: Node.js
+- **核心依赖**:
+  - `@tq1086/urpf-sdk`: URPF 规范解析 SDK
+  - `commander`: 命令行参数解析
+- **开发工具**:
+  - `tsup`: 构建工具
+  - `vitest`: 测试框架
+  - `eslint`: 代码检查
+  - `prettier`: 代码格式化
+
+## 已知限制
+
+1. **大文件处理**：当前版本将整个文件内容加载到内存，对于超大文件可能会有性能问题
+2. **编码检测**：编码检测功能基于简单的启发式算法，可能不够准确
+3. **符号链接**：默认不跟随符号链接，需要使用 `-f` 选项启用
+
+## 未来计划
+
+- [x] 实现 `unpack` 子命令
+- [x] 支持 `pack-add` 和 `pack-remove` 子命令
+- [ ] 添加 `validate` 子命令（验证 URPF 文件格式）
+- [ ] 添加 `list` 子命令（列出 URPF 文件内容）
+- [ ] 支持流式处理大文件
+- [ ] 添加压缩支持
+
+## 许可证
+
+ISC
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！