snan-cli 1.0.0 → 1.0.1

package/README.md

@@ -1,168 +1,127 @@
 # Astro CLI
 
-A Node.js CLI tool that exposes backend HTTP interfaces as command-line commands. Supports modular extension without core file modifications.
+Astro 数据查询命令行工具。通过统一的 `astro <module> <action>` 命令调用 Astro OpenAPI。
 
-## Installation
+## 安装
+
+需要 Node.js 16 或更高版本。
 
 ```bash
 npm install -g snan-cli
+astro --version
 ```
 
-## Configuration
+npm 包名是 `snan-cli`，安装后的可执行命令是 `astro`。
 
-Configure the CLI with one of three methods (priority: env vars > ~/.astrorc > .env):
+## 配置
 
-### 1. Environment Variables (Highest Priority)
+推荐使用交互式配置：
 
-**macOS / Linux / Git Bash（bash 语法）**
+```bash
+astro setup
+```
 
-`export` 仅在 bash/zsh 等 shell 中有效。
+也可以使用环境变量：
 
 ```bash
+export ASTRO_BASE_URL=https://data.snanai.com
 export ASTRO_TOKEN=your-bearer-token
-export ASTRO_BASE_URL=http://127.0.0.1:8080
-export ASTRO_PREFIX=/astro-server/mcp
 export ASTRO_TIMEOUT=30000
 ```
 
-**Windows PowerShell**
-
-PowerShell 不支持 `export`。在当前会话中设置环境变量请使用 `$env:NAME = "value"`（关闭终端后失效）：
-
-```powershell
-$env:ASTRO_TOKEN = "your-bearer-token"
-$env:ASTRO_BASE_URL = "http://127.0.0.1:8080"
-$env:ASTRO_PREFIX = "/astro-server/mcp"
-$env:ASTRO_TIMEOUT = "30000"
-```
-
-检查是否生效：`$env:ASTRO_TOKEN`
+或写入 `~/.astrorc`：
 
-若要在 **用户级永久** 生效（新开 PowerShell 仍有效），可使用：
-
-```powershell
-[System.Environment]::SetEnvironmentVariable('ASTRO_TOKEN', 'your-bearer-token', 'User')
-```
-
-（`ASTRO_BASE_URL` 等同理替换变量名与值。）
-
-### 2. Configuration File (~/.astrorc)
 ```json
 {
-  "baseUrl": "http://127.0.0.1:8080",
-  "token": "your-bearer-token-here",
-  "prefix": "/astro-server/mcp",
+  "baseUrl": "https://data.snanai.com",
+  "token": "your-bearer-token",
   "timeout": 30000
 }
 ```
 
-### 3. .env File
-```
-ASTRO_TOKEN=your-bearer-token
-ASTRO_BASE_URL=http://127.0.0.1:8080
-ASTRO_PREFIX=/astro-server/mcp
-ASTRO_TIMEOUT=30000
-```
+配置优先级为环境变量、`~/.astrorc`、默认配置。默认服务地址是 `https://data.snanai.com`。
 
-## Usage
+## 命令
 
-### Basic Commands
+查看帮助：
 
 ```bash
-# View available commands
 astro --help
+astro metadata --help
+astro metadata tables --help
+```
 
-# View module commands
-astro data --help
+### 元数据
 
-# View action options
-astro data search --help
+```bash
+# 获取数据来源；结果包含 serviceName、dsCode、sourceType 和 dbType
+astro metadata sources
 
-# Execute action with JSON body
-astro data search --body '{"sql":"SELECT * FROM table LIMIT 10"}'
+# serviceName 必须来自 metadata sources
+astro metadata tables --serviceName=tenant-doris_prod --keyword="订单|order"
 
-# Output compact JSON (no pretty-printing)
-astro data search --body '{"sql":"..."}' --raw
+# fqn 为 serviceName.database.schema.table
+astro metadata tableDetail --fqn=tenant-doris_prod.default.prod_dwi.dwi_order
 ```
 
-### Command Structure
+### 数据资产
 
-Commands follow the pattern: `astro <module> <action> [options]`
+```bash
+astro asset dataModels --keyword="销售|订单"
+astro asset dataModelDetail --nameEn=SalesOrder
+astro asset indicators --keyword="GMV|成交额"
+```
 
-- **Module**: Data query/manipulation, standard operations, etc.
-- **Action**: search, insert, update, delete, etc.
-- **Options**: `--body <json>` for request payload, `--raw` for compact output
+### 数仓数据
 
-## Error Handling
+```bash
+astro data queryDw --body="{\"sql\":\"SELECT order_date, COUNT(*) AS order_count FROM prod_dwi.dwi_order GROUP BY order_date LIMIT 100\",\"env\":\"prod\"}"
+```
 
-The CLI provides clear error messages for:
-- Missing token configuration
-- Invalid JSON in `--body`
-- HTTP errors (with status code and response details)
-- Network errors
+请求体字段：
 
-## Adding New Modules
+- `sql`：必填，只读 SQL。
+- `env`：可选，支持 `dev` 或 `prod`，默认 `prod`。
 
-Create a new module file in `src/modules/`:
+### 源数据库数据
 
-**src/modules/standard.js**
-```js
-module.exports = {
-  name: 'standard',
-  description: 'Standard data operations',
-  actions: {
-    query: {
-      description: 'Query data with filters',
-    },
-    transform: {
-      description: 'Transform data format',
-    },
-  },
-};
+```bash
+astro data queryOrigin --body="{\"dsCode\":\"erp_prod\",\"sql\":\"SELECT order_no, amount FROM sale_order LIMIT 50\"}"
 ```
 
-The module is automatically discovered and registered. No core files need modification.
+`dsCode` 必须来自 `metadata sources`，并且对应 `sourceType=DATASOURCE` 的来源。
 
-### Usage
+### 数据标准
 
 ```bash
-astro standard query --body '{"filter":"..."}'
-astro standard transform --body '{"format":"json"}'
+astro standard dataStandard --body='{"nameCn":"客户编码"}'
+astro standard nameRoot --body='{"nameCn":"客户"}'
 ```
 
-## Project Structure
+具体请求字段以服务端 `DataStandardRequestDTO` 和 `StandardDictRequestDTO` 为准。
 
-```
-.
-├── bin/
-│   └── astro                    # Executable entry point
-├── src/
-│   ├── index.js                 # Main CLI orchestrator
-│   ├── config/
-│   │   └── loader.js            # Configuration reader
-│   ├── http/
-│   │   └── client.js            # HTTP client with axios
-│   ├── modules/
-│   │   ├── index.js             # Module auto-loader
-│   │   └── data.js              # Example data module
-│   └── output/
-│       └── formatter.js         # Output formatting & error handling
-├── .astrorc.example             # Configuration template
-└── package.json
+## 输出
+
+默认输出格式化 JSON。添加 `--raw` 输出紧凑 JSON：
+
+```bash
+astro metadata sources --raw
 ```
 
-## API Endpoint Format
+## Shell 补全
 
-Requests are sent to: `{baseUrl}{prefix}/{module}/{action}`
+```bash
+astro --setup-completion
+```
 
-Example: `http://127.0.0.1:8080/astro-server/mcp/data/search`
+执行后重新打开终端，或重新加载对应的 shell 配置文件。
 
-## Dependencies
+## 请求地址
 
-- **axios**: HTTP client
-- **commander**: CLI argument parsing
-- **dotenv**: Environment variable loading
+各模块请求当前版本的 Astro OpenAPI：
 
-## License
+```text
+{baseUrl}/astro-server/openapi/v1/{module}/{action}
+```
 
-MIT
+所有请求使用 `Authorization: Bearer <token>` 认证。

package/bin/astro

@@ -1,3 +1,2 @@
 #!/usr/bin/env node
-
-require('../src');
+require('../src/index.js');

package/package.json

@@ -1,15 +1,21 @@
 {
   "name": "snan-cli",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "CLI tool to expose backend HTTP interfaces as command-line commands",
   "type": "commonjs",
   "bin": {
-    "astro": "bin/astro"
+    "astro": "./bin/astro"
   },
   "main": "src/index.js",
+  "files": [
+    "bin",
+    "src",
+    ".astrorc.example",
+    "README.md"
+  ],
   "scripts": {
     "start": "node bin/astro",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node test/cli.test.js"
   },
   "keywords": [
     "cli",
@@ -18,6 +24,12 @@
   ],
   "author": "",
   "license": "MIT",
+  "engines": {
+    "node": ">=16"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
   "dependencies": {
     "axios": "^1.6.0",
     "commander": "^11.0.0",

package/src/index.js

@@ -5,6 +5,7 @@ const { createHttpClient } = require('./http/client');
 const { loadModules } = require('./modules');
 const { print, error: printError } = require('./output/formatter');
 const { runSetup } = require('./commands/setup');
+const { version } = require('../package.json');
 
 function setupCompletion(modules) {
   const completionTree = {};
@@ -42,7 +43,7 @@ async function main() {
   program
     .name('astro')
     .description('CLI tool to expose backend HTTP interfaces')
-    .version('1.0.0');
+    .version(version);
 
   program
     .command('setup')
@@ -91,7 +92,13 @@ async function main() {
           cmd.option(`--${p.name} <value>`, p.description);
         });
       } else {
-        cmd.option('--body <json>', 'JSON body for the request');
+        const bodyParam = paramDefs.find(p => p.name === 'body');
+        const bodyDescription = bodyParam?.description || 'JSON body for the request';
+        if (bodyParam?.required) {
+          cmd.requiredOption('--body <json>', bodyDescription);
+        } else {
+          cmd.option('--body <json>', bodyDescription);
+        }
       }
 
       cmd.option('--raw', 'Output compact JSON');

package/src/modules/data.js

@@ -12,11 +12,11 @@ module.exports = {
       ],
     },
     queryDw: {
-      description: '查询治理好的数仓资产数据',
+      description: '查询治理好的数仓资产数据（env 支持 dev/prod，不传默认为 prod）',
       method: 'POST',
       path: '/queryDw',
       params: [
-        { name: 'body', description: 'JSON body: { "sql": "SQL查询语句", "rule": "数据统计口径(可选)" }', required: true },
+        { name: 'body', description: 'JSON body: { "sql": "SQL查询语句", "env": "dev或prod(可选，默认prod)" }', required: true },
       ],
     },
   },

package/src/modules/metadata.js

@@ -4,24 +4,23 @@ module.exports = {
   urlPrefix: '/astro-server/openapi/v1/metadata',
   actions: {
     sources: {
-      description: '获取当前租户下所有元数据来源列表（查表前先调此接口获取 systemAbbr）',
+      description: '获取当前租户下所有元数据来源列表（查表前先获取 serviceName，查源数据时使用 dsCode）',
       method: 'GET',
       params: [],
     },
     tables: {
-      description: '根据元数据来源简称和关键字查询表列表（最多 200 条）',
+      description: '根据元数据来源 serviceName 和关键字查询表列表（最多 200 条）',
       method: 'GET',
       params: [
-        { name: 'systemAbbr', description: '元数据来源简称，传 doris_prod 查数仓表，传数据源简称查数据源表', required: true },
+        { name: 'serviceName', description: '元数据来源唯一标识，通过 metadata sources 获取', required: true },
         { name: 'keyword', description: '查询关键字，匹配表名或描述，多关键字用空格或|分隔，为空返回全部', required: false },
       ],
     },
     tableDetail: {
-      description: '获取表详情，包含字段列表和字段类型',
+      description: '根据四段式 FQN 获取表详情，包含字段列表和字段类型',
       method: 'GET',
       params: [
-        { name: 'systemAbbr', description: '元数据来源简称，传 doris_prod 查数仓表，传数据源简称查数据源表', required: true },
-        { name: 'schemaTable', description: '表引用，schema.tablename 形式，如 ods.ods_order', required: true },
+        { name: 'fqn', description: '完全限定名，格式 serviceName.database.schema.table，通过 metadata tables 结果构造', required: true },
       ],
     },
   },