rl-rockcli 0.0.2 → 0.0.4

package/README.md

@@ -0,0 +1,400 @@
+# ROCK CLI (rockcli)
+
+ROCK CLI 是一个开源的命令行工具，用于管理和操作沙箱环境以及查询日志数据。
+
+## 功能特性
+
+- **日志查询** - 搜索和实时查看日志数据
+- **沙箱管理** - 启动、停止、执行、上传/下载文件、交互式 REPL
+- **会话管理** - 持久化执行环境，支持环境变量继承
+
+## 安装
+
+```bash
+# 使用 npm 安装
+npm install -g rl-rockcli
+
+# 或使用 yarn 安装
+yarn global add rl-rockcli
+```
+
+## 使用方法
+
+### 基本语法
+
+```bash
+rockcli <command> [options]
+```
+
+### 全局选项
+
+- `--verbose, -v` - 启用详细日志输出
+- `--config` - 配置文件路径（默认：~/.rock/settings.json）
+- `--base-url` - 服务器地址（覆盖配置文件）
+- `--api-key` - API 密钥（覆盖配置文件）
+
+## 命令详解
+
+### 日志查询 (log)
+
+日志查询功能支持两种模式：
+- **search**：查询指定时间范围内的日志
+- **tail**：实时滚动查看日志，每 5 秒自动刷新
+
+#### 命令
+
+```bash
+# 搜索日志
+rockcli log search [options]
+
+# 实时滚动查看日志
+rockcli log tail [options]
+```
+
+#### 选项说明
+
+##### 查询条件参数
+
+- `[sandboxId]` - 位置参数，指定沙箱 ID
+- `--sandbox-id` - 按沙箱 ID 过滤
+- `-k, --keyword` - 搜索关键词
+- `-f, --field` - 按字段名和值搜索（格式：`field=value`，可多次指定）
+- `--log-file` - 指定日志文件名（需配合 --sandbox-id 使用）
+
+##### 时间范围参数（仅 search 支持）
+
+- `-m, --minutes` - 搜索最近 N 分钟的日志（默认：15）
+- `-s, --start-time` - 开始时间
+- `-e, --end-time` - 结束时间
+
+##### 结果控制参数
+
+- `-l, --limit` - 限制返回结果数量（默认：100）
+- `-o, --offset` - 跳过前 N 条日志（默认：0，仅 search 支持）
+
+##### 输出格式参数
+
+- `--raw` - 显示原始输出（默认：false）
+- `--log-format` - 输出格式：`logfmt`（默认）、`json`、`columns`
+- `--columns` - 过滤显示的字段（逗号分隔）
+- `--multilines` - 允许多行展示（默认：false）
+- `--truncate` - 截断长字段值（默认：2048 字符）
+
+##### 特殊功能参数
+
+- `--count` - 仅显示匹配的日志条数（仅 search 支持）
+- `--debug` - 启用调试模式，输出执行的查询语句
+- `-i, --interval` - 扫描间隔（秒），默认：5（仅 tail 支持）
+- `-n` - 首次显示的最近日志条数，默认：10（仅 tail 支持）
+
+#### 示例
+
+```bash
+# 搜索最近 15 分钟的日志
+rockcli log search -k "error"
+
+# 搜索最近 30 分钟的日志
+rockcli log search -k "error" -m 30
+
+# 使用位置参数指定沙箱 ID
+rockcli log search abc123
+
+# 限制返回结果数量（返回 50 条）
+rockcli log search -k "error" -l 50
+
+# 按字段名精确搜索
+rockcli log search -f "level=ERROR" -m 15
+
+# 实时滚动查看日志（默认 5 秒间隔）
+rockcli log tail -k "error"
+
+# 自定义扫描间隔为 10 秒
+rockcli log tail -k "error" -i 10
+
+# 显示最近 20 条日志，然后实时更新
+rockcli log tail -k "error" -n 20
+
+# 监控特定沙箱的日志
+rockcli log tail --sandbox-id abc123
+
+# 使用 JSON 格式输出
+rockcli log search -k "error" --log-format json
+
+# 只统计日志条数，不显示内容
+rockcli log search -k "error" -m 15 --count
+
+# 使用原始输出格式
+rockcli log search -k "error" --raw
+```
+
+### 沙箱管理 (sandbox)
+
+#### 基本语法
+
+```bash
+rockcli sandbox [action] [options]
+rockcli sandbox [sandboxId] [action] [options]
+```
+
+#### 可用操作
+
+**基本操作：**
+- **start** - 启动一个新的 sandbox 实例
+- **stop** - 停止指定的 sandbox 实例
+- **execute** - 在 sandbox 中执行命令（别名：exec）
+- **status** - 查看 sandbox 的运行状态
+- **upload** - 上传文件或文件夹到 sandbox
+- **download** - 从 sandbox 下载文件
+- **write-file** - 在 sandbox 中写入文件
+- **read-file** - 从 sandbox 读取文件
+- **attach** - 进入交互式 REPL 模式
+
+**Session 管理（子命令）：**
+- **session create** - 创建 session
+- **session run** - 在 session 中执行命令
+- **session close** - 关闭 session
+
+#### 新语法格式（推荐）
+
+```bash
+# ID 在前，action 在后（更符合直觉）
+rockcli sandbox start
+rockcli sandbox <sandbox-id> stop
+rockcli sandbox <sandbox-id> status
+rockcli sandbox <sandbox-id> attach
+
+# 执行命令（使用 -- 分隔符）
+rockcli sandbox <sandbox-id> exec -- ls -la
+rockcli sandbox <sandbox-id> exec -- python script.py
+```
+
+#### 基本命令示例
+
+```bash
+# 启动一个新的 sandbox 实例
+rockcli sandbox start --image python:3.11 --memory 8g --cpus 2.0
+
+# 停止指定的 sandbox 实例
+rockcli sandbox <sandbox-id> stop
+
+# 在 sandbox 中执行命令（支持 -- 分隔符）
+rockcli sandbox <sandbox-id> exec -- ls -la
+rockcli sandbox <sandbox-id> exec --command "ls -la"
+
+# 查看 sandbox 的运行状态
+rockcli sandbox <sandbox-id> status
+
+# 上传单个文件到 sandbox
+rockcli sandbox <sandbox-id> upload --file local.txt --target-path /tmp/remote.txt
+
+# 上传文件夹到 sandbox（仅一级文件）
+rockcli sandbox <sandbox-id> upload --dir ./src --target-path /app/src
+
+# 递归上传文件夹（保持目录结构）
+rockcli sandbox <sandbox-id> upload --dir ./project --target-path /app -r
+
+# 从 sandbox 下载文件
+rockcli sandbox <sandbox-id> download --file /tmp/remote.txt
+
+# 在 sandbox 中写入文件
+rockcli sandbox <sandbox-id> write-file --content "Hello World" --target-path /tmp/hello.txt
+
+# 从 sandbox 读取文件
+rockcli sandbox <sandbox-id> read-file --file /tmp/hello.txt --start-line 1 --end-line 10
+```
+
+#### Session 管理示例
+
+**session create - 创建 session**
+
+```bash
+# 创建默认 session
+rockcli sandbox <sandbox-id> session create
+
+# 创建自定义名称的 session
+rockcli sandbox <sandbox-id> session create --session my-session
+
+# 创建带启动脚本的 session
+rockcli sandbox <sandbox-id> session create --startup-source "/root/.bashrc,/app/env.sh"
+
+# 创建带环境变量的 session
+rockcli sandbox <sandbox-id> session create --env '{"PATH":"/usr/local/bin:/usr/bin","ENV":"production"}'
+```
+
+**session run - 在 session 中执行命令**
+
+```bash
+# 使用 -- 分隔符执行命令（推荐）
+rockcli sandbox <sandbox-id> session run -- ls -la
+rockcli sandbox <sandbox-id> session run -- python script.py --arg1 value1
+
+# 使用 --command 参数
+rockcli sandbox <sandbox-id> session run --command "ls -la"
+
+# 在自定义 session 中执行
+rockcli sandbox <sandbox-id> session run --session my-session -- ls -la
+
+# 设置超时时间（30秒）
+rockcli sandbox <sandbox-id> session run --timeout 30 -- python long_task.py
+```
+
+**session close - 关闭 session**
+
+```bash
+# 关闭默认 session
+rockcli sandbox <sandbox-id> session close
+
+# 关闭自定义名称的 session
+rockcli sandbox <sandbox-id> session close --session my-session
+```
+
+### 交互式 REPL 模式
+
+使用 `attach` 命令进入交互式模式：
+
+```bash
+# 进入交互式 REPL
+rockcli sandbox <sandbox-id> attach
+
+# 或使用旧语法
+rockcli attach <sandbox-id>
+```
+
+REPL 模式支持：
+- 持久 session（export、cd 等命令状态保持）
+- 命令历史（上下键浏览）
+- Tab 补全
+- 内置命令（以 `/` 开头）：
+  - `/log` - 搜索日志
+  - `/upload` / `/download` - 文件传输
+  - `/status` - 查看状态
+  - `/help` - 帮助
+  - `/exit` - 退出
+  - `/close` - 关闭 session 并退出
+
+## 配置文件
+
+默认配置文件路径：`~/.rock/settings.json`
+
+配置文件格式（JSON）：
+
+```json
+{
+  "sandbox": {
+    "base_url": "http://localhost:8080",
+    "api_key": "your-api-key"
+  }
+}
+```
+
+## 环境变量
+
+支持通过环境变量设置认证信息：
+
+```bash
+# 设置 API Key
+export ROCK_API_KEY=your-api-key
+
+# 设置服务器地址
+export ROCKCLI_BASE_URL=http://localhost:8080
+
+# 或使用 ROCK_BASE_URL（兼容）
+export ROCK_BASE_URL=http://localhost:8080
+
+# 使用环境变量运行命令
+rockcli sandbox <sandbox-id> status
+```
+
+优先级：命令行参数 > 环境变量 > 配置文件
+
+## 配置管理 (config)
+
+配置管理命令用于设置和查看本地配置参数。
+
+### 基本语法
+
+```bash
+rockcli config [options]
+```
+
+### 选项说明
+
+- `--api-key <key>` - 设置 API 密钥
+- `--base-url <url>` - 设置服务器基础 URL
+- `--list` - 显示当前配置（脱敏敏感值）
+
+### 示例
+
+```bash
+# 设置 API Key 和服务器地址
+rockcli config --api-key xxx --base-url http://localhost:8080
+
+# 显示当前配置
+rockcli config --list
+
+# 仅设置 API Key，其他值保持不变
+rockcli config --api-key xxx
+```
+
+## 开发指南
+
+### 项目结构
+
+```
+opensource/
+├── bin/
+│   └── rockcli.js       # CLI 主入口
+└── package.json         # 包配置
+
+（引用上层目录的共享代码）
+├── commands/            # 命令模块
+├── sdks/                # SDK 客户端
+└── utils/               # 工具类
+```
+
+### 本地开发
+
+```bash
+# 克隆项目
+git clone <repository-url>
+
+# 安装依赖
+npm install
+
+# 本地链接
+npm link
+
+# 测试命令
+rockcli --help
+rockcli sandbox --help
+```
+
+## 相关资源
+
+- GitHub: https://github.com/your-org/rock-cli
+- 文档: https://rock-cli.example.com/docs
+- 问题反馈: https://github.com/your-org/rock-cli/issues
+
+## 许可证
+
+MIT License
+
+Copyright (c) 2026 ROCK CLI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/index.js

@@ -1,18 +1,31 @@
 #!/usr/bin/env node
 
-// 开源版默认配置（只在环境变量未设置时才设置）
-if (!process.env.ROCKCLI_BASE_URL) {
-  process.env.ROCKCLI_BASE_URL = 'http://127.0.0.1:8080';
-}
+/**
+ * rl-rockcli - Open Source ROCK CLI Entry Point
+ * 
+ * 这是开源版本的入口文件，它会：
+ * 1. 设置 ROCKCLI_MODE=opensource 环境变量
+ * 2. **只引用 Core 命令**（不引用 Internal）
+ * 3. 过滤掉内网专有功能
+ */
 
-// 强制设置开源模式（放在环境变量读取之后）
+// 强制设置开源模式（在任何 require 之前）
 process.env.ROCKCLI_MODE = 'opensource';
 
+// 开源版默认配置
+if (!process.env.ROCKCLI_BASE_URL) {
+    process.env.ROCKCLI_BASE_URL = 'http://127.0.0.1:8080';  // 本地开发环境
+}
+
 const yargs = require('yargs/yargs');
 const { hideBin } = require('yargs/helpers');
-const logCommand = require('./commands/log');
-const sandboxCommand = require('./commands/sandbox');
 
+// ⚠️ 关键：只引用 Core 命令，不引用 Internal
+// 这确保打包时不会包含内网代码
+const logCommand = require('../commands/log');  // 已支持 ROCKCLI_MODE 过滤
+const sandboxCommand = require('../commands/sandbox');  // 已支持 ROCKCLI_MODE 过滤
+
+// ASCII Art Logo
 const LOGO = `
 ██████╗  ██████╗  ██████╗██╗  ██╗ ██████╗██╗     ██╗
 ██╔══██╗██╔═══██╗██╔════╝██║ ██╔╝██╔════╝██║     ██║
@@ -20,19 +33,36 @@ const LOGO = `
 ██╔══██╗██║   ██║██║     ██╔═██╗ ██║     ██║     ██║
 ██║  ██║╚██████╔╝╚██████╗██║  ██╗╚██████╗███████╗██║
 ╚═╝  ╚═╝ ╚═════╝  ╚═════╝╚═╝  ╚═╝ ╚═════╝╚══════╝╚═╝
-                                          Open Source
 `;
 
-yargs(hideBin(process.argv))
-  .scriptName('rockcli')
-  .usage(LOGO + '\n\nUsage: $0 <command> [options]')
-  .command(logCommand)
-  .command(sandboxCommand)
-  .demandCommand(1)
-  .strict()
-  .alias('h', 'help')
-  .alias('v', 'version')
-  .version('0.1.0')
-  .help()
-  .wrap(null)
-  .parse();
+function run() {
+    const cli = yargs(hideBin(process.argv));
+
+    cli
+        .scriptName('rockcli')
+        .usage(LOGO + '\n\nUsage: $0 <command> [options]')
+        .command(logCommand)
+        .command(sandboxCommand)
+        .demandCommand(1, '请提供一个有效的命令。使用 --help 查看可用命令。')
+        .strict()
+        .alias('h', 'help')
+        .alias('v', 'version')
+        .version(require('./package.json').version)
+        .help()
+        .epilogue(`
+环境变量：
+  ROCKCLI_API_KEY     - API 密钥（用于认证）
+  ROCKCLI_BASE_URL    - 沙箱服务地址（默认: http://127.0.0.1:8080）
+  ROCKCLI_LOG_LEVEL   - 日志级别（debug/info/warn/error）
+
+文档: https://github.com/rock-cli/rockcli
+    `);
+
+    if (typeof cli.terminalWidth === 'function') {
+        cli.wrap(cli.terminalWidth());
+    }
+
+    cli.parse();
+}
+
+run();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rl-rockcli",
-    "version": "0.0.2",
+    "version": "0.0.4",
     "description": "Open-source ROCK CLI - Sandbox and Log management tool",
     "bin": {
         "rockcli": "./index.js"
@@ -13,6 +13,7 @@
         "sdks/",
         "help/",
         "lib/",
+        "README.md",
         "package.json"
     ],
     "scripts": {
@@ -45,4 +46,4 @@
         "registry": "https://registry.npmjs.org",
         "access": "public"
     }
-}
+}