@amaster.ai/cli 1.1.27 → 1.1.29

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,17 +1,165 @@
1
1
  # @amaster.ai/cli
2
2
 
3
- CLI utilities for React + Vite template checks.
3
+ `amaster` 提供两类能力,`amaster-cli` 作为兼容命令保留:
4
4
 
5
- Current commands:
5
+ 1. 模板检查
6
+ 2. Addon Marketplace
6
7
 
7
- - `amaster-cli check route`
8
- - `amaster-cli check ast --stack react-vite`
9
- - `amaster-cli check type --stack react-vite`
10
- - `amaster-cli check build --stack react-vite`
11
- - `amaster-cli check type --stack taro`
12
- - `amaster-cli check build --stack taro`
13
- - `amaster-cli check all --stack react-vite`
14
- - `amaster-cli check all --stack taro`
8
+ ## Registry
15
9
 
16
- This command validates that the default-exported routes config in `src/routes.tsx`
17
- contains a home route whose `path` resolves to `"/"`.
10
+ - 默认 registry:`helige` -> `https://www.helige.cn`
11
+ - 内置别名:`helige-int` -> `https://www.helige-int.cn`
12
+ - 默认 registry 可通过环境变量 `AMASTER_CLI_REGISTRY` 覆盖
13
+ - 临时切换其他环境时使用 `--registry`
14
+
15
+ ## 认证
16
+
17
+ ```bash
18
+ export AMASTER_CLI_REGISTRY=amaster.local
19
+
20
+ amaster login
21
+ amaster login --registry helige-int --browser
22
+ amaster login --registry helige-int
23
+ amaster login --registry https://demo.example.com --email admin@amaster.ai --password password
24
+ amaster whoami
25
+ amaster logout
26
+ ```
27
+
28
+ 登录流程:
29
+
30
+ 1. `--browser`:打开 `/login?redirect=/api/oauth/authorize...`,通过本地 `http://127.0.0.1:18147/oauth/callback` 接收授权码
31
+ 2. 默认密码模式:先登录 `/api/auth/login`
32
+ 3. 再用 `amaster-cli` 这个 public PKCE OAuth client 兑换 Addon 写接口可用的 Bearer Token
33
+ 4. 本地 session 按 registry 隔离保存到 `~/.amaster/cli/config.json`
34
+
35
+ ## Addon 命令
36
+
37
+ ```bash
38
+ amaster addon search crm
39
+ amaster addon view crm-pages
40
+ amaster addon view crm-pages@1.0.0
41
+ amaster addon versions crm-pages
42
+ amaster addon members crm-pages@1.0.0
43
+ amaster addon content crm-pages@1.0.0 lead-summary
44
+
45
+ amaster addon publish .
46
+ amaster addon publish ./dist/addon.tgz --scope official
47
+ amaster addon activate crm-pages
48
+ amaster addon deactivate crm-pages
49
+ amaster addon delete crm-pages
50
+
51
+ amaster addon install crm-pages@1.0.0
52
+ amaster addon install crm-pages --registry helige-int
53
+ amaster addon upgrade crm-pages
54
+ amaster addon list
55
+ ```
56
+
57
+ `addon search` 在未显式传 `--application-type` 时,会从当前目录向上查找最近的 `package.json`,读取同级 `app.settings.yml` 的 `type`,并自动按 `web` 或 `mini` 过滤。
58
+
59
+ 常用参数:
60
+
61
+ - `--registry <alias-or-url>`
62
+ - `--organization-code <code>`
63
+ - `--json`
64
+ - `--set key=value`:安装参数
65
+ - `--application-type web|mini`
66
+ - `--target <path>`:显式指定应用根目录;不传时从当前目录向上查找最近的 `package.json`
67
+
68
+ ## 安装规则
69
+
70
+ 设计态安装成员类型:
71
+
72
+ - `component`
73
+ - `page`
74
+ - `theme`
75
+ - `workflow`
76
+ - `bpmn`
77
+ - `entity`
78
+ - `datasource`
79
+ - `settings`
80
+
81
+ 安装结果会写入:
82
+
83
+ - `src/addons/<addon-name>/meta.json`
84
+ - `settings` 成员会深合并到应用根目录 `app.settings.yml`
85
+
86
+ Addon 可在 `addon.json` 中声明安装后的运行配置要求:
87
+
88
+ ```json
89
+ {
90
+ "install": {
91
+ "requirements": {
92
+ "envs": [
93
+ {
94
+ "key": "OAUTH_CLIENT_ID",
95
+ "required": true,
96
+ "description": "OAuth client id",
97
+ "defaultValue": "demo-client"
98
+ }
99
+ ],
100
+ "secrets": [
101
+ {
102
+ "key": "OAUTH_CLIENT_SECRET",
103
+ "required": true,
104
+ "description": "OAuth client secret"
105
+ }
106
+ ]
107
+ }
108
+ }
109
+ }
110
+ ```
111
+
112
+ `install.requirements` 会写入 `meta.json`,并在安装/升级结果中返回 `requirements` 和 `missingRequirements`。`secrets` 只保存键名和说明,不保存密钥值。
113
+
114
+ 页面注册方式:
115
+
116
+ - `web`:生成 `src/amaster/registry/addon-routes.generated.ts`,并 patch `src/routes.tsx`
117
+ - `mini`:生成 `src/amaster/registry/addon-pages.generated.ts`,并 patch `src/app.config.ts`
118
+
119
+ 升级策略:
120
+
121
+ - 先读取已安装 `meta.json`
122
+ - 如果受管文件被本地修改,升级会停止
123
+ - 冲突会先汇总后返回,不会写入半成品
124
+ - 普通输出会打印冲突摘要;`--json` 会输出 MCP/AI 可消费的结构化冲突信息
125
+
126
+ 冲突 JSON 示例:
127
+
128
+ ```json
129
+ {
130
+ "success": false,
131
+ "code": "ADDON_INSTALL_CONFLICT",
132
+ "message": "Addon install has 1 conflict(s)",
133
+ "operation": "install",
134
+ "addon": {
135
+ "name": "approval-addon",
136
+ "version": "1.0.0",
137
+ "applicationType": "web"
138
+ },
139
+ "targetDir": "/path/to/app",
140
+ "conflicts": [
141
+ {
142
+ "kind": "target_exists",
143
+ "path": "src/pages/approval/index.tsx",
144
+ "sourcePath": "pages/approval/index.tsx",
145
+ "memberName": "approval-page",
146
+ "memberType": "page",
147
+ "message": "src/pages/approval/index.tsx already exists in target application"
148
+ }
149
+ ]
150
+ }
151
+ ```
152
+
153
+ MCP 接入时可按 `conflicts[].path` 读取应用里的当前文件,并按 `memberName` / `sourcePath` 获取 Addon 原始内容,再交给 AI 合并后重试安装或升级。
154
+
155
+ ## 模板检查
156
+
157
+ 命令:
158
+
159
+ ```bash
160
+ amaster check route [--cwd <path>] [--routes-file <path>]
161
+ amaster check ast --stack react-vite [--cwd <path>]
162
+ amaster check type --stack <react-vite|taro> [--cwd <path>]
163
+ amaster check build --stack <react-vite|taro> [--cwd <path>]
164
+ amaster check all --stack <react-vite|taro> [--cwd <path>]
165
+ ```