npm package: @koklam/miniapp-cli
Description: Dimina 小程序打包、同步、发布、调试 CLI 工具
Author: KOKLAM
Latest version: 0.1.0

# @koklam/miniapp-cli

KOKLAM Dimina 小程序打包、同步、发布、调试 CLI 工具。

## 安装

```bash
# 全局安装
npm install -g @koklam/miniapp-cli

# 或项目内使用
npm install --save-dev @koklam/miniapp-cli
```

## 快速开始

```bash
# 1. 初始化配置
cat > miniapp.config.json << 'EOF'
{
  "appId": "my-app",
  "source": "./dist/wx",
  "output": "./release"
}
EOF

# 2. 编译打包
miniapp build

# 3. 启动开发服务器
miniapp dev
```

## 命令

### `miniapp build`

编译小程序源码并打包为 ZIP。

```bash
miniapp build --source ./dist/wx --app-id my-app --out ./release
```

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `-s, --source <dir>` | 小程序源码目录 | `./dist/wx` |
| `-a, --app-id <id>` | 应用 ID | `miniapp` |
| `-o, --out <dir>` | 输出目录 | `./release` |

产物结构：
```
release/my-app/
  ├── my-app.zip    # 小程序包
  └── config.json   # 配置信息
```

### `miniapp sync`

同步构建产物到本地目录（如 Flutter example assets）。

```bash
miniapp sync --targets ./example/assets/local_release
```

| 参数 | 说明 |
|------|------|
| `-z, --zip <path>` | 指定源 ZIP |
| `-c, --config <path>` | 指定源 config |
| `-t, --targets <dirs>` | 目标目录（逗号分隔） |

### `miniapp publish`

上传构建产物到远端存储。

```bash
# 阿里云 OSS
miniapp publish --provider oss --bucket my-bucket --endpoint oss-cn-hangzhou.aliyuncs.com

# AWS S3
miniapp publish --provider s3 --bucket my-bucket --region ap-east-1

# 自定义 HTTP 接口
miniapp publish --provider http --endpoint https://api.example.com/upload
```

| 参数 | 说明 |
|------|------|
| `-p, --provider <type>` | `oss` / `s3` / `http` |
| `--bucket <name>` | 存储桶 |
| `--prefix <path>` | 远端路径前缀 |
| `--endpoint <url>` | 端点地址 |
| `--cdn-base-url <url>` | CDN 公网 URL |

发布后自动生成 `manifest.json` 并上传，输出 Manifest URL。

### `miniapp dev`

启动本地开发服务器，模拟远端 CDN。

```bash
miniapp dev --source ./dist/wx --port 3000
```

启动后输出局域网地址，宿主 App 中配置 `manifestUriBuilder` 指向该地址即可实时调试：

```dart
MiniAppPackageManager(
  manifestUriBuilder: (appId) => Uri.parse(
    'http://192.168.1.100:3000/$appId/manifest.json',
  ),
);
```

支持 watch 模式：修改源码自动 rebuild，宿主 App 重新打开小程序即可加载最新版本。

### `miniapp qrcode`

生成二维码（终端显示 + PNG 文件）。

```bash
# 下载链接二维码
miniapp qrcode --url https://cdn.example.com/miniapps --type download

# Deep Link 二维码
miniapp qrcode --url https://cdn.example.com/miniapps --type deeplink --scheme miniapp

# 两种都生成 + 输出 PNG
miniapp qrcode --url https://cdn.example.com/miniapps --output ./qr.png
```

Deep Link 格式：`miniapp://open?appId=xxx&url=xxx`，宿主 App 注册对应 scheme 后扫码即可打开小程序。

### `miniapp version`

版本管理。

```bash
# patch 递增 (1.0.0 → 1.0.1)
miniapp version --bump patch

# minor 递增 + 打 git tag
miniapp version --bump minor --tag
```

| 参数 | 说明 |
|------|------|
| `-b, --bump <level>` | `major` / `minor` / `patch` |
| `--tag` | 自动创建 git tag |

自动递增 `versionCode`，更新 `versionName`，并基于 git log 生成 CHANGELOG。

## 配置文件

在项目根目录创建 `miniapp.config.json`：

```json
{
  "appId": "my-app",
  "source": "./dist/wx",
  "output": "./release",
  "publish": {
    "provider": "oss",
    "bucket": "my-bucket",
    "prefix": "miniapps/",
    "endpoint": "oss-cn-hangzhou.aliyuncs.com"
  },
  "dev": {
    "port": 3000
  },
  "qrcode": {
    "scheme": "miniapp",
    "baseUrl": "https://cdn.example.com/miniapps"
  }
}
```

命令行参数优先于配置文件。

## 要求

- Node.js >= 18
- 编译功能需要 `@dimina/compiler`（自动通过 npx 安装）
- OSS 发布需要 `ossutil` 或 `aliyun` CLI
- S3 发布需要 `aws` CLI