snan-cli 1.0.0

package/.astrorc.example

@@ -0,0 +1,6 @@
+{
+  "baseUrl": "http://127.0.0.1:8080",
+  "token": "your-bearer-token-here",
+  "prefix": "/astro-server/mcp",
+  "timeout": 30000
+}

package/README.md

@@ -0,0 +1,168 @@
+# Astro CLI
+
+A Node.js CLI tool that exposes backend HTTP interfaces as command-line commands. Supports modular extension without core file modifications.
+
+## Installation
+
+```bash
+npm install -g snan-cli
+```
+
+## Configuration
+
+Configure the CLI with one of three methods (priority: env vars > ~/.astrorc > .env):
+
+### 1. Environment Variables (Highest Priority)
+
+**macOS / Linux / Git Bash（bash 语法）**
+
+`export` 仅在 bash/zsh 等 shell 中有效。
+
+```bash
+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`
+
+若要在 **用户级永久** 生效（新开 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",
+  "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
+```
+
+## Usage
+
+### Basic Commands
+
+```bash
+# View available commands
+astro --help
+
+# View module commands
+astro data --help
+
+# View action options
+astro data search --help
+
+# Execute action with JSON body
+astro data search --body '{"sql":"SELECT * FROM table LIMIT 10"}'
+
+# Output compact JSON (no pretty-printing)
+astro data search --body '{"sql":"..."}' --raw
+```
+
+### Command Structure
+
+Commands follow the pattern: `astro <module> <action> [options]`
+
+- **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
+
+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
+
+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',
+    },
+  },
+};
+```
+
+The module is automatically discovered and registered. No core files need modification.
+
+### Usage
+
+```bash
+astro standard query --body '{"filter":"..."}'
+astro standard transform --body '{"format":"json"}'
+```
+
+## Project Structure
+
+```
+.
+├── 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
+```
+
+## API Endpoint Format
+
+Requests are sent to: `{baseUrl}{prefix}/{module}/{action}`
+
+Example: `http://127.0.0.1:8080/astro-server/mcp/data/search`
+
+## Dependencies
+
+- **axios**: HTTP client
+- **commander**: CLI argument parsing
+- **dotenv**: Environment variable loading
+
+## License
+
+MIT

package/bin/astro

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

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "snan-cli",
+  "version": "1.0.0",
+  "description": "CLI tool to expose backend HTTP interfaces as command-line commands",
+  "type": "commonjs",
+  "bin": {
+    "astro": "bin/astro"
+  },
+  "main": "src/index.js",
+  "scripts": {
+    "start": "node bin/astro",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "cli",
+    "http",
+    "command-line"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.6.0",
+    "commander": "^11.0.0",
+    "dotenv": "^16.3.1",
+    "enquirer": "^2.4.1",
+    "omelette": "^0.4.17"
+  }
+}

package/src/commands/setup.js

@@ -0,0 +1,77 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { prompt } = require('enquirer');
+
+const ZSHRC = path.join(os.homedir(), '.zshrc');
+const BASHRC = path.join(os.homedir(), '.bashrc');
+const MARKER_BEGIN = '# begin astro config';
+const MARKER_END = '# end astro config';
+
+const DEFAULT_BASE_URL = 'https://data.snanai.com';
+
+function detectShellRc() {
+  const shell = process.env.SHELL || '';
+  if (shell.includes('zsh') && fs.existsSync(ZSHRC)) return ZSHRC;
+  if (fs.existsSync(BASHRC)) return BASHRC;
+  return ZSHRC;
+}
+
+function writeExports(rcFile, baseUrl, token) {
+  let content = fs.existsSync(rcFile) ? fs.readFileSync(rcFile, 'utf-8') : '';
+
+  const lines = [
+    MARKER_BEGIN,
+    `export ASTRO_BASE_URL="${baseUrl}"`,
+  ];
+  if (token) {
+    lines.push(`export ASTRO_TOKEN="${token}"`);
+  }
+  lines.push(MARKER_END);
+
+  const block = lines.join('\n');
+  const regex = new RegExp(`${MARKER_BEGIN}[\\s\\S]*?${MARKER_END}`, 'm');
+
+  if (regex.test(content)) {
+    content = content.replace(regex, block);
+  } else {
+    content = content.trimEnd() + '\n\n' + block + '\n';
+  }
+
+  fs.writeFileSync(rcFile, content, 'utf-8');
+}
+
+async function runSetup() {
+  console.log('Astro CLI Setup\n');
+
+  const answers = await prompt([
+    {
+      type: 'input',
+      name: 'baseUrl',
+      message: 'API Base URL (host only)',
+      initial: DEFAULT_BASE_URL,
+    },
+    {
+      type: 'password',
+      name: 'token',
+      message: 'API Key (token, leave empty to skip)',
+      initial: '',
+    },
+  ]);
+
+  // Strip trailing slash
+  const baseUrl = answers.baseUrl.replace(/\/+$/, '');
+
+  const rcFile = detectShellRc();
+  writeExports(rcFile, baseUrl, answers.token);
+
+  console.log(`\nSaved to ${rcFile}:`);
+  console.log(`  ASTRO_BASE_URL=${baseUrl}`);
+  if (answers.token) {
+    console.log(`  ASTRO_TOKEN=****`);
+  }
+  console.log('\nApply now by running:');
+  console.log(`  source ${rcFile}`);
+}
+
+module.exports = { runSetup };

package/src/config/loader.js

@@ -0,0 +1,45 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+require('dotenv').config();
+
+function loadConfig() {
+  // Default config
+  const defaults = {
+    baseUrl: 'https://data.snanai.com',
+    prefix: '/astro-server/mcp',
+    timeout: 30000,
+  };
+
+  let config = { ...defaults };
+
+  // Load from ~/.astrorc
+  const rcPath = path.join(os.homedir(), '.astrorc');
+  if (fs.existsSync(rcPath)) {
+    try {
+      const rcContent = fs.readFileSync(rcPath, 'utf-8');
+      const rcConfig = JSON.parse(rcContent);
+      config = { ...config, ...rcConfig };
+    } catch (err) {
+      console.error(`Warning: Failed to parse ~/.astrorc: ${err.message}`);
+    }
+  }
+
+  // Override with environment variables
+  if (process.env.ASTRO_BASE_URL) {
+    config.baseUrl = process.env.ASTRO_BASE_URL;
+  }
+  if (process.env.ASTRO_TOKEN) {
+    config.token = process.env.ASTRO_TOKEN;
+  }
+  if (process.env.ASTRO_PREFIX) {
+    config.prefix = process.env.ASTRO_PREFIX;
+  }
+  if (process.env.ASTRO_TIMEOUT) {
+    config.timeout = parseInt(process.env.ASTRO_TIMEOUT, 10);
+  }
+
+  return config;
+}
+
+module.exports = { loadConfig };

package/src/http/client.js

@@ -0,0 +1,56 @@
+const axios = require('axios');
+
+function createHttpClient(config) {
+  const instance = axios.create({
+    baseURL: config.baseUrl,
+    timeout: config.timeout || 30000,
+    headers: {
+      'Authorization': `Bearer ${config.token}`,
+    },
+  });
+
+  // Response interceptor for error handling
+  instance.interceptors.response.use(
+    response => response.data,
+    error => {
+      if (error.response) {
+        return {
+          status: error.response.status,
+          message: error.response.data?.message || error.response.statusText || 'HTTP Error',
+          data: error.response.data,
+          isHttpError: true,
+        };
+      } else if (error.request) {
+        return {
+          status: 0,
+          message: error.message || 'Network Error',
+          isHttpError: false,
+        };
+      } else {
+        return {
+          status: 0,
+          message: error.message || 'Request Error',
+          isHttpError: false,
+        };
+      }
+    }
+  );
+
+  /**
+   * 统一请求方法
+   * @param {string} method - 'GET' | 'POST'
+   * @param {string} url
+   * @param {object} params - GET 时作为 query string，POST 时作为 request body
+   */
+  instance.request2 = function(method, url, params = {}) {
+    if (method.toUpperCase() === 'GET') {
+      return instance.get(url, { params });
+    } else {
+      return instance.post(url, params);
+    }
+  };
+
+  return instance;
+}
+
+module.exports = { createHttpClient };

package/src/index.js

@@ -0,0 +1,147 @@
+const { program } = require('commander');
+const omelette = require('omelette');
+const { loadConfig } = require('./config/loader');
+const { createHttpClient } = require('./http/client');
+const { loadModules } = require('./modules');
+const { print, error: printError } = require('./output/formatter');
+const { runSetup } = require('./commands/setup');
+
+function setupCompletion(modules) {
+  const completionTree = {};
+  Object.entries(modules).forEach(([moduleName, moduleDef]) => {
+    completionTree[moduleName] = Object.keys(moduleDef.actions);
+  });
+
+  const completion = omelette('astro <module> <action>');
+
+  completion.on('module', ({ reply }) => {
+    reply(Object.keys(completionTree));
+  });
+
+  completion.on('action', ({ before, reply }) => {
+    reply(completionTree[before] || []);
+  });
+
+  completion.init();
+
+  if (process.argv.includes('--setup-completion')) {
+    completion.setupShellInitFile();
+    console.log('Tab completion configured! Restart your shell or run:');
+    console.log('  source ~/.zshrc   (zsh)');
+    console.log('  source ~/.bashrc  (bash)');
+    process.exit(0);
+  }
+}
+
+async function main() {
+  const modules = loadModules();
+
+  setupCompletion(modules);
+
+  // setup 命令不需要 token，提前注册并处理
+  program
+    .name('astro')
+    .description('CLI tool to expose backend HTTP interfaces')
+    .version('1.0.0');
+
+  program
+    .command('setup')
+    .description('Configure API base URL and token (writes to shell rc file)')
+    .action(async () => {
+      await runSetup();
+      process.exit(0);
+    });
+
+  // 如果是 setup 命令，直接解析执行，跳过 token 检查
+  if (process.argv[2] === 'setup') {
+    await program.parseAsync(process.argv);
+    return;
+  }
+
+  const config = loadConfig();
+
+  if (!config.token) {
+    console.error('Error: ASTRO_TOKEN is not configured');
+    console.error('');
+    console.error('Run "astro setup" to configure interactively, or:');
+    console.error('1. Set environment variable: export ASTRO_TOKEN=your-token');
+    console.error('2. Create ~/.astrorc with: { "token": "your-token" }');
+    process.exit(1);
+  }
+
+  const httpClient = createHttpClient(config);
+
+  Object.entries(modules).forEach(([moduleName, moduleDefinition]) => {
+    const urlPrefix = moduleDefinition.urlPrefix || `${config.prefix}/${moduleName}`;
+
+    const moduleCommand = program
+      .command(moduleName)
+      .description(moduleDefinition.description);
+
+    Object.entries(moduleDefinition.actions).forEach(([actionName, actionDef]) => {
+      const cmd = moduleCommand
+        .command(actionName)
+        .description(actionDef.description);
+
+      const method = (actionDef.method || 'POST').toUpperCase();
+      const paramDefs = actionDef.params || [];
+
+      if (method === 'GET') {
+        paramDefs.forEach(p => {
+          cmd.option(`--${p.name} <value>`, p.description);
+        });
+      } else {
+        cmd.option('--body <json>', 'JSON body for the request');
+      }
+
+      cmd.option('--raw', 'Output compact JSON');
+
+      cmd.action(async (options) => {
+        try {
+          // action.path 优先（支持子路径），否则自动拼接 /actionName
+          const url = actionDef.path ? `${urlPrefix}${actionDef.path}` : `${urlPrefix}/${actionName}`;
+          let requestParams = {};
+
+          if (method === 'GET') {
+            paramDefs.forEach(p => {
+              if (options[p.name] !== undefined) {
+                requestParams[p.name] = options[p.name];
+              } else if (p.required) {
+                console.error(`Error: --${p.name} is required`);
+                process.exit(1);
+              }
+            });
+          } else {
+            if (options.body) {
+              try {
+                requestParams = JSON.parse(options.body);
+              } catch (err) {
+                console.error(`Error: Invalid JSON in --body: ${err.message}`);
+                process.exit(1);
+              }
+            }
+          }
+
+          const response = await httpClient.request2(method, url, requestParams);
+
+          if (response && response.isHttpError) {
+            printError(response);
+            process.exit(1);
+          }
+
+          print(response, { raw: options.raw });
+        } catch (err) {
+          printError(err);
+          process.exit(1);
+        }
+      });
+    });
+  });
+
+  await program.parseAsync(process.argv);
+}
+
+main().catch(err => {
+  console.error('Fatal error:', err.message);
+  process.exit(1);
+});

package/src/modules/asset.js

@@ -0,0 +1,28 @@
+module.exports = {
+  name: 'asset',
+  description: '数据资产：数据模型和指标查询',
+  urlPrefix: '/astro-server/openapi/v1/asset',
+  actions: {
+    dataModels: {
+      description: '获取数据资产模型列表（含可用表信息）',
+      method: 'GET',
+      params: [
+        { name: 'keyword', description: '查询关键字，多个关键字用空格或|分隔，为空查询全部', required: false },
+      ],
+    },
+    dataModelDetail: {
+      description: '获取数据模型详情（含逻辑实体和属性字段）',
+      method: 'GET',
+      params: [
+        { name: 'nameEn', description: '模型英文名（唯一标识），如 SalesOrder', required: true },
+      ],
+    },
+    indicators: {
+      description: '获取所有指标列表',
+      method: 'GET',
+      params: [
+        { name: 'keyword', description: '查询关键字，多个关键字用空格或|分隔，为空查询全部', required: false },
+      ],
+    },
+  },
+};

package/src/modules/data.js

@@ -0,0 +1,23 @@
+module.exports = {
+  name: 'data',
+  description: '数据查询：原始数据库和数仓数据查询',
+  urlPrefix: '/astro-server/openapi/v1/data',
+  actions: {
+    queryOrigin: {
+      description: '查询源数据库原始数据（ERP、CRM 等原始系统）',
+      method: 'POST',
+      path: '/queryOrigin',
+      params: [
+        { name: 'body', description: 'JSON body: { "dsCode": "数据源编码", "sql": "SQL查询语句" }', required: true },
+      ],
+    },
+    queryDw: {
+      description: '查询治理好的数仓资产数据',
+      method: 'POST',
+      path: '/queryDw',
+      params: [
+        { name: 'body', description: 'JSON body: { "sql": "SQL查询语句", "rule": "数据统计口径(可选)" }', required: true },
+      ],
+    },
+  },
+};

package/src/modules/index.js

@@ -0,0 +1,28 @@
+const fs = require('fs');
+const path = require('path');
+
+function loadModules() {
+  const modulesDir = __dirname;
+  const modules = {};
+
+  const files = fs.readdirSync(modulesDir).filter(file => {
+    return file.endsWith('.js') && file !== 'index.js';
+  });
+
+  files.forEach(file => {
+    try {
+      const modulePath = path.join(modulesDir, file);
+      const moduleDefinition = require(modulePath);
+
+      if (moduleDefinition.name && moduleDefinition.actions) {
+        modules[moduleDefinition.name] = moduleDefinition;
+      }
+    } catch (err) {
+      console.error(`Warning: Failed to load module ${file}: ${err.message}`);
+    }
+  });
+
+  return modules;
+}
+
+module.exports = { loadModules };

package/src/modules/metadata.js

@@ -0,0 +1,28 @@
+module.exports = {
+  name: 'metadata',
+  description: '元数据查询：数据源和数仓表结构查询',
+  urlPrefix: '/astro-server/openapi/v1/metadata',
+  actions: {
+    sources: {
+      description: '获取当前租户下所有元数据来源列表（查表前先调此接口获取 systemAbbr）',
+      method: 'GET',
+      params: [],
+    },
+    tables: {
+      description: '根据元数据来源简称和关键字查询表列表（最多 200 条）',
+      method: 'GET',
+      params: [
+        { name: 'systemAbbr', description: '元数据来源简称，传 doris_prod 查数仓表，传数据源简称查数据源表', required: true },
+        { name: 'keyword', description: '查询关键字，匹配表名或描述，多关键字用空格或|分隔，为空返回全部', required: false },
+      ],
+    },
+    tableDetail: {
+      description: '获取表详情，包含字段列表和字段类型',
+      method: 'GET',
+      params: [
+        { name: 'systemAbbr', description: '元数据来源简称，传 doris_prod 查数仓表，传数据源简称查数据源表', required: true },
+        { name: 'schemaTable', description: '表引用，schema.tablename 形式，如 ods.ods_order', required: true },
+      ],
+    },
+  },
+};

package/src/modules/standard.js

@@ -0,0 +1,23 @@
+module.exports = {
+  name: 'standard',
+  description: '数据标准：数据标准和词根的创建与修改',
+  urlPrefix: '/astro-server/openapi/v1/standard',
+  actions: {
+    dataStandard: {
+      description: '创建或修改数据标准（按中文名称判断：已存在则修改，否则新建）',
+      method: 'POST',
+      path: '/dataStandard',
+      params: [
+        { name: 'body', description: 'DataStandardRequestDTO JSON 对象', required: true },
+      ],
+    },
+    nameRoot: {
+      description: '创建或修改词根/数据字典（按中文名称判断：已存在则修改，否则新建）',
+      method: 'POST',
+      path: '/nameRoot',
+      params: [
+        { name: 'body', description: 'StandardDictRequestDTO JSON 对象', required: true },
+      ],
+    },
+  },
+};

package/src/output/formatter.js

@@ -0,0 +1,23 @@
+function print(data, options = {}) {
+  if (options.raw) {
+    console.log(JSON.stringify(data));
+  } else {
+    console.log(JSON.stringify(data, null, 2));
+  }
+}
+
+function error(err) {
+  if (err.isHttpError) {
+    console.error(`HTTP ${err.status}: ${err.message}`);
+    if (err.data !== undefined) {
+      console.error(typeof err.data === 'string' ? err.data : JSON.stringify(err.data, null, 2));
+    }
+  } else {
+    console.error(`Error: ${err.message}`);
+    if (err.stack) {
+      console.error(err.stack);
+    }
+  }
+}
+
+module.exports = { print, error };