minidev 1.0.3 → 1.0.7

package/docs/guide/commands/remote-debug.md

@@ -0,0 +1,137 @@
+# remote-debug
+## 用途
+
+构建小程序并发起真机调试。 
+
+运行后，支付宝小程序 CLI 将会构建可以在手机 App （如支付宝钱包）中使用的真机调试版小程序，并将其发布到支付宝开放平台供手机 App 访问。
+
+![](https://intranetproxy.alipay.com/skylark/lark/0/2021/png/111910/1638460264909-81c151f8-a77b-4dee-a32e-e9492d2d245d.png?x-oss-process=image%2Fresize%2Cw_1486%2Climit_0)
+
+运行成功后，将会返回可供手机 App 扫描的小程序真机调试二维码，使用对应手机 App 扫码即可查看小程序。部分 App 支持自动同步小程序到手机 App 中，无需进行扫码操作。
+
+同时，CLI 会输出可以在浏览器中打开的调试连接，使用浏览器打开后即可开始进行真机调试（默认尝试自动打开）
+
+
+> 使用该指令要求工具进行[授权](../../guide/experiences/auth.md)
+
+## CLI 风格使用 
+
+````
+Usage: minidev remote-debug [options]
+
+发起真机调试
+
+Options:
+  --auto-push                         [可选] 自动推送到客户端, 默认打开, 使用 --no-auto-push 来关 (default: true)
+  --ignore-http-domain-check          [可选] 忽略 http 请求白名单校验
+  --ignore-webview-domain-check       [可选] 忽略 webview 加载域名白名单校验
+  -a, --app-id <appId>                [必填] 小程序应用 id
+  -c, --client-type <clientType>      [可选] 端类型 
+  --page <page>                       [可选] 入口页面
+  --page-query <page>                 [可选] 页面参数, 可在当前页面的 onLoad 中取得，如: name=vendor&color=black
+  --query <page>                      [可选] 全局参数，app.js 的 onLaunch 中取得，如: name=vendor&color=black
+  --scene <page>                      [可选] 进入场景值
+````
+
+## Node.js API 风格使用
+
+````javascript
+
+const { 
+    qrcodeSchema, 
+    qrcodeUrl, 
+    debugUrl
+    } = await minidev.remoteDebug({
+  appId: 'YourAppId',
+  project: '/path/to/mini-program',
+})
+
+// 真机调试二维码图片地址
+console.log(qrcodeUrl);
+
+// 真机调试 schema url，允许手机 App 通过这个 url 唤起调试小程序
+console.log(qrcodeSchema);
+
+// 可在浏览器中打开的调试器应用地址
+console.log(debugUrl);
+
+
+````
+
+
+## 参数说明
+
+### appId
+````Typescript
+appId: string
+````
+本次真机调试使用的小程序 App Id。
+
+### clientType
+````Typescript
+clientType: string
+````
+
+指定真机调试的目标端类型，默认为 alipay (支付宝)，详见[端类型](../../guide/experiences/client-type.md)。
+
+### autoPush
+````Typescript
+autoPush: boolean
+````
+
+如果指定的端（手机 App) 支持，则尝试将调试的小程序直接推送到端，无需进行扫码操作。 此功能默认开启。
+
+### ignoreHttpDomainCheck
+````Typescript
+ignoreHttpDomainCheck: boolean
+````
+
+此次真机调试的小程序运行时忽略 http 请求白名单校验。详见 [小程序网络 API 使用须知](https://opendocs.alipay.com/mini/008gq6)
+
+
+### ignoreWebviewDomainCheck
+````Typescript
+ignoreWebviewDomainCheck: boolean
+````
+
+此次真机调试的小程序运行时忽略 web-view 组件加载域名白名单校验。详见[ web-view 组件 H5 域名配置](https://opendocs.alipay.com/mini/component/idfvg6)
+
+### page
+````Typescript
+page: string
+````
+
+本次调试的入口页面路径。 例: `/page/index/index`.
+
+
+### pageQuery
+
+````Typescript
+pageQuery: string
+````
+
+本次调试的页面参数。可在当前页面的 onLoad 中取得，例: `name=vendor&color=black`
+
+### query
+````Typescript
+query: string
+````
+
+本次调试的全局参数。 可在 app.js 的 onLaunch 中取得，例: `name=vendor&color=black`
+
+### scene
+
+````Typescript
+scene: string
+````
+本次调试的场景值。 输入值为场景的 channelId。例: `ch_appcenter`
+
+可选值可参考[支持的场景值](../../guide/experiences/scene.md)。
+
+### autoOpenDevtools
+
+````Typescript
+autoOpenDevtools: boolean
+````
+
+是否尝试使用默认浏览器自动打开调试器窗口。cli 模式默认自动打开， Node.js API 调用默认不打开。

package/docs/guide/commands/upload.md

@@ -0,0 +1,95 @@
+# upload
+
+## 用途
+
+上传小程序以进行[提审](https://opendocs.alipay.com/mini/introduce/release)。
+
+> 使用该指令要求工具进行[授权](../../guide/experiences/auth.md)
+
+## CLI 风格使用 
+
+````shell
+Usage: minidev upload [options]
+
+上传发布小程序
+
+Options:
+  -d, --delete-version <deleteVersion>  [可选] 上传时，删除指定版本的版本号 (需要对应权限)
+  -e, --experience                      [可选] 上传成功后，自动设置为体验版本 (需要对应权限)
+  -v, --version [version]               [可选] 上传包版本
+  -p, --project <project>               [可选] 目标项目, 默认为当前工作目录
+  -a, --app-id <appId>                   [必填] 小程序应用 id
+  -c, --client-type <clientType>        [可选] 端类型
+                                        
+````
+
+## Node.js API 风格使用
+
+````javascript
+
+const uploadResult = await minidev.upload({
+  appId: 'yourAppId',
+  version: '0.0.1',
+  project: '/path/to/mini-program'
+  // experience: true 添加 experience 选项的话可以一并把刚上传的版本设置为体验版
+}, {
+  onLog: (data) => {
+    // 输出日志
+    console.log(data);
+  }
+})
+
+// 打印上传版本
+console.log(uploadResult.version);
+
+
+````
+
+
+## 参数说明
+
+### clientType
+
+````Typescript
+clientType: string
+````
+
+指定上传提审的目标端类型，默认为 alipay (支付宝)，详见[端类型](../../guide/experiences/client-type.md)
+
+### deleteVersion
+
+````Typescript
+deleteVersion: string
+````
+
+如果添加这个参数，在上传过程中会删除指定的版本（即使它正在构建中或不存在）。记录已上传的版本并使用这个参数能有效避免上传版本无法超过 20 个的问题。
+
+### appId
+
+````Typescript
+appId: string
+````
+
+需要上传的小程序的 appId。 
+
+### version
+
+````Typescript
+version: string
+````
+
+指定上传的版本号，必须满足 x.y.z 的格式，其中x,y,z 必须都为数字。
+
+合法版本号如 `0.0.1`, `10.2.14` 等
+
+> 如果不提供版本号，本次上传的版本会根据当前最新的已上传版本号添加一位 patch 版本号（最后一位数字）
+> 
+> 比如：之前的最新已上传版本号为 0.2.3, 则本次使用的是 0.2.4
+
+### experience
+
+````Typescript
+experience: boolean
+````
+
+上传成功后，自动设置为[体验版本](https://opendocs.alipay.com/mini/introduce/release#%E8%AE%BE%E7%BD%AE%E4%BD%93%E9%AA%8C%E7%89%88%EF%BC%88%E5%8F%AF%E9%80%89%EF%BC%89) (需要对应小程序的管理员权限)

package/docs/guide/experiences/auth.md

@@ -0,0 +1,65 @@
+# 授权信息 & 多机器使用
+
+## 授权信息
+
+支付宝小程序 CLI 的授权信息在用户使用机器上存储的是一对工具Id `toolId` 和 私钥 `privateKey` 的键值对，对应位于开放平台存储的公钥 `publicKey` 可以在[开放平台工具授权页面](https://open.alipay.com/dev/workspace/key-manage/tool)查看。
+
+当需要开始使用 CLI 工具时，可以通过 [login](../commands/login.md) 进行快速授权
+
+````shell
+minidev login
+````
+
+**一个支付宝用户同一时刻仅能存在一个工具授权信息**。 因此，当在不同的电脑上执行 `minidev login` 进行授权时，会重新生成 toolId 和公私钥，从而导致之前的授权失效。
+
+## 授权信息存储位置
+
+授权信息存储在用户目录下 minidev 的资料目录中的配置文件中，默认位置在
+
+* `MacOS/Linux` ~/.minidev/config.json
+* `Windows` C:\\User\\你的用户名\\.minidev/config.json 
+
+对应的配置键为 `alipay.authentication`。 配置相关能力见文档[配置的使用](./config.md)
+
+## 多机器使用
+
+在诸如 ci/cd 的应用场景，由于上述[授权信息的唯一性](##授权信息的唯一性), 我们不能在每一台机器上都通过执行 `minidev login` 来重复进行授权，此时我们建议将上述包含授权信息的配置文件分发到每一台机器上，或者使用运行时配置来注入授权信息。配置项的使用详见[工具配置](./config.md);
+
+### 使用配置项环境变量
+
+````shell
+export MINIDEV_RUNTIME_CONFIG={"alipay.authentication":{"privateKey": "xxxxxxxxxx", "toolId": "xxxxxxxxxx"}}
+minidev upload -a xxxxxxx
+````
+
+### Node.js API 修改授权信息
+Node.js 中的 useDefaults 或者 config.useRuntime 来初始化 minidev 的运行授权信息
+
+```` javascript
+
+const { minidev, useDefaults } = require('minidev');
+
+// 方式 1. 注入默认授权信息
+useDefaults({
+  config: {
+    defaults: {
+      'alipay.authentication.privateKey': 'xxxxxxxxxx',
+      'alipay.authentication.toolId': 'xxxxxxxxxx',
+    }
+  }
+});
+
+// 方式 2. 注入默认授权信息
+minidev.config.useRuntime({
+  'alipay.authentication.privateKey': 'xxxxxxxxxx',
+  'alipay.authentication.toolId': 'xxxxxxxxxx',
+});
+
+// 执行需要授权的 api
+minidev.upload({
+  appId:'xxxxxxxx',
+  project: '/path/to/mini-program'
+});
+
+
+````

package/docs/guide/experiences/client-type.md

@@ -0,0 +1,16 @@
+# 端类型
+
+`preview`、`remote-debug`, `upload` 等指令允许通过传入 `clientType` 参数来指定端类型以开发不同类型的小程序。目前支持的端类型列表如下:
+
+- `alipay` 支付宝
+- `ampe` 支付宝 AMPE 设备
+- `amap` 高德地图
+- `genie` 天猫精灵
+- `alios` 阿里车
+- `alipayiot` 支付宝 IOT 设备
+- `uc` UC 浏览器
+- `quark` 夸克浏览器
+- `health` 阿里医院
+- `koubei` 口碑
+- `cainiao` 菜鸟
+- `alihealth` 医蝶谷

package/docs/guide/experiences/config.md

@@ -0,0 +1,127 @@
+# 工具配置
+
+## 配置项
+
+支付宝小程序 CLI 的配置选项为 `key-value` 键值对存储的字符串、布尔值或者 JSON Object。获取和设置配置项时，可以通过 `minidev config set/get key [value]` 指令来进行操作。
+
+> 典型的配置 key 例子：
+> - `alipay.authentication.privateKey` 工具授权的 privateKey
+> - `compiler.version` 编译器版本
+
+### 配置项解构和聚合
+
+当配置项遇到 JSON Object 类型的配置项时，会根据需要对其进行解构或者聚合。
+
+比如，如下三个配置项是等价的：
+
+````javascript
+// 完全解构
+{
+  "alipay.authentication.privateKey":"myPrivateKey"
+}
+// 完全聚合
+{
+  "alipay": {
+    "authentication": {
+      "privateKey": "myPrivateKey"
+    }
+  }
+}
+// 半解构半聚合
+{
+  "alipay.authentication": {
+    "privateKey": "myPrivateKey"
+  }
+}
+
+````
+
+> 在解析过程中可能会产生冲突，一般会尝试按照顺序进行解析，如果产生不可被解析的情况，配置模块将会抛出错误
+
+## 多级配置
+
+支付宝小程序 CLI 使用了**多级配置**概念来管理工具的配置项。整个工具拥有四个等级的配置级别
+
+- `RUNTIME`: 运行时的配置项，仅仅存在在单次的 Node.js 运行上下文，或者单次 CLI 调用中。
+- `PROJECT`: 项目的配置。项目配置项会默认存储在项目目录下 .minidev/config.json 中。
+- `GLOBAL`: 当前设备（如果存在多用户的话则是当前用户）的配置，默认存储在用户目录 `(MacOS 为 ~, Windows为 C:\\User\\你的用户名)` 下的 .minidev/config.json 中。
+- `DEFAULT`: 支付宝小程序 CLI 的默认配置
+
+
+这四个级别为从下到上依次被覆盖的关系。即对于同一个 key 的配置项，生效优先级为 `RUNTIME` > `PROJECT` > `GLOBAL` > `DEFAULT`
+
+
+比如考虑一下配置项值表
+
+````javascript
+{
+  "RUNTIME": {
+    "key1":"key1_runtime",
+  },
+  "PROJECT": {
+    "key1":"key1_project",
+    "key2.key3": "key3_project",
+  },
+  "GLOBAL": {
+    "key2": {
+      "key3": "key3_global",
+      "key4": "key4_global",
+    }
+  },
+  "DEFAULT": {
+    "key5": {
+      "key6": "key6_default",
+    },
+    "key1": "key1_default"
+  },
+}
+````
+
+最终等价的配置值表为：
+
+````javascript
+{
+  "key1":"key1_runtime",
+  "key2": {
+    "key3":"key3_project",
+    "key4":"key4_global",
+  },
+  "key5": {
+    "key6": "key6_default",
+  }
+}
+````
+
+
+## 使用环境变量改变 config
+
+支付宝小程序 CLI 允许使用环境变量来改变 `RUNTIME` 的配置值。传入 JSON 序列化后的配置项即可。
+
+````shell
+MINIDEV_RUNTIME_CONFIG={"compiler.version.cube":"0.55.20"} minidev build
+````
+
+## Node.js API 中工具设置的使用
+
+minidev 提供了 `useDefaults` 和 `minidev.config.useRuntime` 指令来允许在 Node.js API 调用时
+
+````javascript
+const { minidev, useDefaults } = require('minidev');
+
+// 使用 useDefaults 设置 **DEFAULT** 的配置值
+// 注意 useDefaults 必须在 minidev 的任何指令执行前执行，否则会报错。
+useDefaults({
+  config: {
+    defaults: {
+      'alipay.authentication.privateKey': 'xxxxxxxxxx',
+      'alipay.authentication.toolId': 'xxxxxxxxxx',
+    }
+  }
+});
+
+// 使用 config.useRuntime 来指定 **RUNTIME** 的配置值
+minidev.config.useRuntime({
+  'compiler.version.cube': '0.55.20',
+});
+
+````

package/docs/guide/experiences/sandbox.md

@@ -0,0 +1,12 @@
+
+# 沙箱环境
+
+如果需要在[沙箱环境]下使用支付宝小程序 CLI，只需要传入 MINIDEV_ENV=sandbox 环境变量即可。
+
+````shell
+MINIDEV_ENV=sandbox minidev preview -a {沙箱环境的Appid}
+````
+
+> ### Tip
+> 沙箱环境和生产环境的支付宝钱包授权信息是独立存储的，因此需要重新进行授权。
+

package/docs/guide/experiences/scene.md

@@ -0,0 +1,33 @@
+
+# 支持的场景值
+
+指令 preview, remote-debug 等支持传入场景值 `channelId` 来模拟[小程序场景值](https://opendocs.alipay.com/mini/framework/scene)
+
+目前**仅支付宝端支持传入场景值id, 其他端传入无效**
+
+| `channelId` | `ID` | 含义 |
+|  ----  | ----  |  ----  |
+| ch_appcenter | 1000 | 首页12宫格及更多 |
+| ch_tinycenter | 1001 | 朋友栏小程序主入口，包含最近，收藏，推荐和附近 |
+| ch_appcollect | 1002 | 小程序收藏应用入口，包含朋友tab中的入口 |
+| ch_alipaysearch | 1005 | 顶部搜索框的搜索结果页 |
+| ch_share | 1007 | 单人聊天会话中的小程序消息卡片(分享，包含支付宝内和外部渠道) |
+| ch_scan | 1011 | 二维码，含扫一扫，相册识别，长按识别 |
+| ch_messageservice | 1014 | 小程序模版消息（服务提醒） |
+| ch_life | 1020 | 生活号 profile 页相关小程序列表 |
+| ch_desktop | 1023 | 系统桌面图标 |
+| ch_othertinyapp | 1037 | 小程序打开小程序 |
+| ch_backfromtinyapp | 1038 | 从另一个小程序返回 |
+| ch_tinylongpress | 1090 | 长按小程序右上角菜单唤出的最近使用历史 |
+| ch_cityservice | 1200 | 城市服务频道 |
+| ch_zhima | 1201 | 芝麻信用频道 |
+| ch_carservice | 1202 | 车主服务频道 |
+| ch_medicalservice | 1203 | 医疗服务频道 |
+| ch_college | 1204 | 大学生活频道 |
+| ch_school | 1205 | 中小学频道 |
+| ch_sharebike | 1206 | 共享单车频道 |
+| ch_insurance | 1207 | 保险服务频道 |
+| ch_ttyl | 1208 | 天天有料频道 |
+| ch_membership | 1209 | 支付宝会员频道 |
+| ch_outerUrl | 1300 | 第三方 APP（如钉钉）打开，在跳转链接中传入访问来源参数：chInfo=ch_orderCenter |
+

package/index.d.ts

@@ -34,6 +34,10 @@ declare module 'minidev' {
 
   export function setSilent(boolean): void;
 
+  export function setSpinnerEnabled(enabled: boolean): void;
+
+  export function setLogLevelVerboseEnabled(enabled: boolean): void;
+
   export type MaybePromise<T = void> = T | Promise<T>;
 
   export interface IMinidevPlugin {
@@ -83,7 +87,10 @@ declare module 'minidev' {
      * 需要在运行 dev 之后运行
      * @param opts 
      */
-    devPreview(opts: IDevPreviewArgs): Promise<void>;
+    devPreview(opts: IDevPreviewArgs, build?: IDevServerCompileBuild): Promise<IGenerateDebugQRCodeResult>;
+
+    
+    devWebSimulator(opts:IDevWebSimulatorArgs, build?: IDevServerCompileBuild): Promise<IWebSimulatorLauncher>
   
 
     /**
@@ -91,7 +98,7 @@ declare module 'minidev' {
      * 需要在运行 dev 之后运行
      * @param opts 
      */
-    devRemoteDebug(opts: IDevRemoteDebugArgs): Promise<IRemoteDebugReturn>
+    devRemoteDebug(opts: IDevRemoteDebugArgs, build?: IDevServerCompileBuild): Promise<IRemoteDebugReturn>
 
 
     /**
@@ -99,7 +106,7 @@ declare module 'minidev' {
      * 需要在运行 dev 之后运行
      * @param opts 
      */
-    startIdeForDevServer(opts: IDevIDEOptions): Promise<void>;
+    startIdeForDevServer(opts: IDevIDEOptions, build?: IDevServerCompileBuild): Promise<void>;
 
     /**
      * 进行工具授权
@@ -110,8 +117,9 @@ declare module 'minidev' {
     /**
      * 上传发布小程序
      * @param opts 
+     * @param @optional hooks
      */
-    upload(opts: IUploadOptions): Promise<IPublishResult>;
+    upload(opts: IUploadOptions, hooks?: IPublishHooks): Promise<IPublishResult>;
 
 
     /**
@@ -162,6 +170,15 @@ declare module 'minidev' {
     
   }
 
+  export interface IPublishHooks {
+
+    onLog?:(data: string) => void;
+    
+    onTaskCreated?: (taskId: string) => void;
+  
+    onVersionCreated?: (version: string) => void;
+  }
+
   export interface IMinidevConfig {
 
     get<T = any>(configName: string, opts?: IConfigOptions): Promise<T>;
@@ -170,6 +187,22 @@ declare module 'minidev' {
   
   }
 
+  export interface IWebSimulatorLauncher {
+  
+    bundled: string;
+  
+    /**
+     * 这里返回的 simulator 和 devtool 均为不含 uuid 的模板地址
+     * 如何使用:
+     *  const simulatorUrl = separated.simulator.replace('___uuid___', '当前会话的 uuid')
+     *  const devtoolUrl = separated.devtool.replace('___uuid___', '当前会话的 uuid')
+     */
+    separated: {
+      simulator: string;
+      devtool: string;
+    }
+  }
+
   export interface IConfigOptions extends IProjectArgs {
   
     scope?: ConfigScope.GLOBAL | ConfigScope.PROJECT;
@@ -194,6 +227,15 @@ declare module 'minidev' {
 
   }
 
+  export interface IDevWebSimulatorArgs extends IOptionalAppIdArgs, IClientTypeOptions, ICompileModeOptions {
+
+    /**
+     * 自动打开模拟器, 默认行为为打开
+     */
+    autoOpen?: boolean;
+  
+  }
+
   export interface IGenerateQrCodeArgs extends IClientTypeOptions, ICompileModeOptions, IAMPEOptions {
 
     /**
@@ -498,7 +540,7 @@ declare module 'minidev' {
     once(event: 'hmr-done', listener: () => any): this;
     once(event: 'hmr-error', listener: (error: IDevError) => any): this;
     once(event: 'project-config-change', listener: () => any): this;
-    once(event: 'log', listener: () => any): this;
+    once(event: 'log', listener: (data: string) => any): this;
 
     restart(options?: {appId?: string}): Promise<void>;
 
@@ -523,6 +565,7 @@ declare module 'minidev' {
   export interface IDevDone {
     success: boolean;
   }
+  
 
   export interface IDevIDEOptions extends IOptionalAppIdArgs, IIDECommandOptions {
 
@@ -564,7 +607,12 @@ declare module 'minidev' {
   }
 
   export interface IDevRemoteDebugArgs extends IGenerateQrCodeArgs, IAppIdArgs {
-
+    
+    /**
+     * 是否自动打开 devtool，cli 模式默认自动打开， jsApi 调用默认不打开
+     */
+    autoOpenDevtool?: boolean;
+    
   }
   
   export interface IPublishResult {
@@ -592,6 +640,11 @@ declare module 'minidev' {
     * 上传成功后，自动设置为体验版本 (需要对应权限)
     */
     experience?: boolean;
+
+    /**
+   * 上传时删除指定版本号
+   */
+   deleteVersion?: string;
   
   }
 
@@ -688,7 +741,12 @@ declare module 'minidev' {
     /**
      * 小程序应用 id 
      */
-     appId: string;
+    appId: string;
+
+    /**
+     * 是否自动打开 devtool，cli 模式默认自动打开， jsApi 调用默认不打开
+     */
+    autoOpenDevtool?: boolean;
   
   }