npm package: @nasl/cli
Description: NASL (Next Application Specific Language) CLI tool for checking, compiling and developing NASL code
Latest version: 0.3.5

# @nasl/cli

NASL 语言的命令行工具，提供编译、检查、开发服务等功能。

目前只支持 NaturalTS 表示的 NASL 代码，编译为 Vue 和 JS。

## 安装

```bash
npm install -g @nasl/cli
```

## 使用

### 初始化配置（nasl init）

```bash
nasl init
```

会在当前目录创建 `nasl.config.json` 配置文件。

```json
{
  "serverBaseURL": "https://nasl.lcap.163yun.com", // NASL 编译服务的基础 URL
  "representation": "NaturalTS", // NASL 语言的表示
  "namespaceResolution": "filename-as-namespace", // 命名空间解析策略
  "ideVersion": "4.4", // IDE 版本
  "srcDir": "src", // 源代码目录
  "outDir": "out" // 输出目录
}
```

### 入口文件说明

下面的命令中均支持 [entry] 参数，表示入口文件：

- 入口文件可选，不填则表示处理整个 src 目录
- 入口文件路径相对于项目目录，但必须在 src 目录下
- 支持具体文件和 glob 模式（注意要用引号包裹）
  - src/app.enums.Status.ts 支持具体文件
  - "src/app.enums.*.ts" 表示所有枚举
  - "src/app.{*.entities.*.ts,structures.*.ts,enums.*.ts}" 表示所有实体、数据结构和枚举，即全部用户自定义类型
  - "src/app.logics.*.ts" 表示所有逻辑文件
  - "src/*.tsx" 表示所有页面文件
- 会自动进行依赖分析，收集所有依赖的文件
- 依赖的页面文件（.tsx）不会继续进行依赖分析，而是直接提取签名，以提高性能

### 编译 NASL 代码（nasl compile 或 naslc）

```bash
# 编译整个 src 目录
nasl compile

# 编译指定入口文件及其依赖（自动进行依赖分析）
nasl compile src/app.frontendTypes.pc.frontends.pc.views.dashboard.tsx
# 或使用简写
naslc src/app.frontendTypes.pc.frontends.pc.views.dashboard.tsx
naslc "src/app.enums.*.ts"
naslc "src/app.{*.entities.*.ts,structures.*.ts,enums.*.ts}"
naslc "src/app.logics.*.ts"
naslc "src/*.tsx"
```

### 检查 NASL 代码（nasl check）

```bash
# 检查整个 src 目录
nasl check

# 检查指定入口文件及其依赖（自动进行依赖分析）
nasl check src/app.frontendTypes.pc.frontends.pc.views.dashboard.tsx
nasl check "src/app.enums.*.ts"
nasl check "src/app.{*.entities.*.ts,structures.*.ts,enums.*.ts}"
nasl check "src/app.logics.*.ts"
nasl check "src/*.tsx"
```

### 检查 plan 文档中的 NaturalTS（nasl-doc / nasld）

用于检查 plan 目录下 markdown 里 `naturalts` 代码块的语法（与 `nasl check` 面向 `src` 的 NASL 源码检查不同）。

安装 `@nasl/cli` 后，可使用 **`nasl-doc`** 或 **`nasld`**（同一命令的短名）：

```bash
nasl-doc check path/to/plan.md
# 或
nasld check path/to/plan.md
```

支持的文档类型包括：`enums.md`、`entity-*.md`、`structure-*.md`、`logic-*.md`、`view-*.md` 等（详见命令帮助：`nasl-doc check --help`）。

### 依赖分析（nasl dep）

建议指定入口文件，否则会扫描整个 src 目录，输出量较大。

```bash
nasl dep "src/app.enums.*.ts"
nasl dep "src/app.{*.entities.*.ts,structures.*.ts,enums.*.ts}"
nasl dep "src/app.logics.loadStudentList.ts"
nasl dep "src/*.tsx"
nasl dep
```

### 启动开发服务（nasl dev）

```bash
nasl dev
```

启动开发服务后，默认访问 http://localhost:3100 查看预览效果。

可以用 --port 和 --host 更换端口号和主机名。

```bash
nasl dev --port 4900 --host 0.0.0.0
```

dev 进程始终保持运行，规则如下：

1. 启动:
  1. 有 src: 初始编译生成 out，然后启动 webpack
  2. 无 src:
    1. 有 out：直接启动 webpack，等待 src 目录创建
    2. 无 out：启动 webpack，等待 src 目录创建
2. 运行中
  1. out 被删除：如果有 src，自动重新编译恢复 out
  2. src 被创建：自动编译生成 out 目录
  3. src 被删除: 使用缓存的 out 目录

### 构建项目（nasl build）

与 nasl dev 对应，构建成最终用于浏览器的 dist 产物。

```bash
# 使用生产模式构建（默认）
nasl build

# 使用开发模式构建
nasl build --mode development

# 构建指定入口文件及其依赖
nasl build src/app.frontendTypes.pc.frontends.pc.views.dashboard.tsx
```

### 转换文件格式（nasl transform）

```bash
# files2full: 将 src 中的文件组合成 fullNaturalTS
nasl transform files2full [entry] --output [outputPath]
# 默认输出到 ./full-natural.ts

# json2files: 将 JSON 文件转换成 src 的 files
nasl transform json2files [jsonFile] --output [outputPath]
# 如果不指定 jsonFile，将按照默认 IDE 版本的基础模板转换

# files2json: 将 src 中的文件转换成一个 JSON（待实现）
nasl transform files2json [entry] --output [outputPath]
# 默认输出到 ./files.json
```

### 在 IDE 中创建 / 更新应用

**注意**：`create-app-in-ide` 与 `update-app-in-ide` 只能在测试环境使用。

两个命令都会先按 [入口文件说明](#入口文件说明) 解析本地 NASL（可选 `[entry]`，不传则处理整个 `src`），将源码组合为 fullNaturalTS（含依赖）后调用远程服务。均支持 `--quiet` 跳过确认、`--verbose` 输出依赖分析等详细信息。

#### 在 IDE 中创建应用（nasl create-app-in-ide）

```bash
# 会询问确认（默认）
nasl create-app-in-ide [entry]

# 跳过确认，直接执行
nasl create-app-in-ide [entry] --quiet

# 显示详细信息
nasl create-app-in-ide [entry] --verbose
```

执行前会展示即将使用的**应用名称**、**包名**、IDE 版本与租户。应用名与包名由项目目录推导：若存在 `specs/` 目录，则取其中**第一个子文件夹名**作为基础名；否则使用**项目根目录名**。基础名经清洗（仅保留字母数字、去掉开头数字、最长 12 字符）后，再拼接时间后缀生成最终名称。

#### 在 IDE 中更新已有应用（nasl update-app-in-ide）

第一个参数为远程应用的 **appId**（必填），其余与创建命令一致。

```bash
# 会询问确认（默认）
nasl update-app-in-ide <appId> [entry]

# 跳过确认
nasl update-app-in-ide <appId> [entry] --quiet

# 显示详细信息
nasl update-app-in-ide <appId> [entry] --verbose
```

将当前本地 NASL 同步到指定应用，用于在 IDE 中更新已有应用而非新建。

## 环境变量配置

除了在 `nasl.config.json` 中配置外，也可以通过环境变量来配置部分选项。

**环境变量的优先级高于配置文件**，如果同时设置了环境变量和配置文件，将使用环境变量的值。

### 支持的环境变量

- `NASL_IDE_VERSION`: IDE 版本号，对应配置`ideVersion`字段
  ```bash
  export NASL_IDE_VERSION=4.4
  ```

- `NASL_SERVER_BASE_URL`: NASL 编译服务的基础 URL，对应配置`serverBaseURL`字段
  ```bash
  export NASL_SERVER_BASE_URL=https://nasl.lcap.163yun.com
  ```

- `USE_LCAP_OPENAPI`: 是否使用 OpenAPI 方式调用（值为 `'true'` 时启用），对应配置`useOPENAPI`字段
  ```bash
  export USE_LCAP_OPENAPI=true
  ```

- `LCAP_OPENAPI_AK`: LCAP OpenAPI Access Key（使用 OpenAPI 时必需），对应配置`OPENAPI_AK`字段
  ```bash
  export LCAP_OPENAPI_AK=your_access_key
  ```

- `LCAP_OPENAPI_SK`: LCAP OpenAPI Secret Key（使用 OpenAPI 时必需），对应配置`OPENAPI_SK`字段
  ```bash
  export LCAP_OPENAPI_SK=your_secret_key
  ```

### 配置文件示例（包含 OpenAPI 配置）

```json
{
  "serverBaseURL": "https://sometenant.codewave.163.com",
  "representation": "NaturalTS",
  "namespaceResolution": "filename-as-namespace",
  "ideVersion": "4.4",
  "srcDir": "src",
  "outDir": "out",
  "useOPENAPI": true,
  "OPENAPI_AK": "your_access_key",
  "OPENAPI_SK": "your_secret_key"
}
```

注意：如果配置了 `useOPENAPI: true`，则必须同时配置 `OPENAPI_AK` 和 `OPENAPI_SK`（可在配置文件中配置，或通过环境变量 `LCAP_OPENAPI_AK` 和 `LCAP_OPENAPI_SK` 配置）。

## DEVELOPMENT

```bash
# 安装依赖
pnpm install

# 构建
pnpm run build

# 开发模式（监听文件变化）
pnpm run dev

# 代码检查
pnpm run lint

# 代码修复
pnpm run lint:fix

# 代码格式化
pnpm run format
```