@capyclaw/plugin-validator 0.0.0-stage → 1.0.1
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/bin/cli.mjs +49 -0
- package/lib/index.mjs +303 -0
- package/package.json +26 -4
- package/README.md +0 -3
package/bin/cli.mjs
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* DSH 插件验证 CLI
|
|
4
|
+
* 用法: validate-plugin <plugin-path>
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import { fileURLToPath } from 'node:url'
|
|
8
|
+
import { dirname, resolve } from 'node:path'
|
|
9
|
+
import { validatePlugin } from '../lib/index.mjs'
|
|
10
|
+
|
|
11
|
+
const __filename = fileURLToPath(import.meta.url)
|
|
12
|
+
const __dirname = dirname(__filename)
|
|
13
|
+
|
|
14
|
+
const pluginPath = process.argv[2]
|
|
15
|
+
|
|
16
|
+
if (!pluginPath) {
|
|
17
|
+
console.error('用法: validate-plugin <plugin-path>')
|
|
18
|
+
console.error('示例: validate-plugin B/official/capyclaw-port-sidebar')
|
|
19
|
+
process.exit(1)
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
const absolutePath = resolve(process.cwd(), pluginPath)
|
|
23
|
+
|
|
24
|
+
console.log('🔍 验证插件:', absolutePath)
|
|
25
|
+
console.log('━'.repeat(60))
|
|
26
|
+
|
|
27
|
+
try {
|
|
28
|
+
const result = await validatePlugin(absolutePath)
|
|
29
|
+
|
|
30
|
+
if (result.valid) {
|
|
31
|
+
console.log('\n✅ 验证通过!所有检查项合规。\n')
|
|
32
|
+
if (result.warnings.length > 0) {
|
|
33
|
+
console.log('⚠️ 警告:')
|
|
34
|
+
result.warnings.forEach(w => console.log(' -', w))
|
|
35
|
+
}
|
|
36
|
+
process.exit(0)
|
|
37
|
+
} else {
|
|
38
|
+
console.log('\n❌ 验证失败!发现以下问题:\n')
|
|
39
|
+
result.errors.forEach((err, i) => {
|
|
40
|
+
console.log(`${i + 1}. [${err.rule}] ${err.message}`)
|
|
41
|
+
if (err.hint) console.log(` 提示: ${err.hint}`)
|
|
42
|
+
})
|
|
43
|
+
console.log()
|
|
44
|
+
process.exit(1)
|
|
45
|
+
}
|
|
46
|
+
} catch (error) {
|
|
47
|
+
console.error('\n💥 验证过程出错:', error.message)
|
|
48
|
+
process.exit(1)
|
|
49
|
+
}
|
package/lib/index.mjs
ADDED
|
@@ -0,0 +1,303 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* DSH 插件验证器核心
|
|
3
|
+
* 强制检查插件是否符合规范
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
import { readFileSync, existsSync, statSync, readdirSync } from 'node:fs'
|
|
7
|
+
import { join, basename } from 'node:path'
|
|
8
|
+
import semver from 'semver'
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* 验证规则定义
|
|
12
|
+
*/
|
|
13
|
+
const RULES = {
|
|
14
|
+
// 必需文件
|
|
15
|
+
REQUIRED_FILES: ['package.json', 'README.md', 'lib'],
|
|
16
|
+
|
|
17
|
+
// 包名规则:dsh-<name> / @org/dsh-<name>,或已发布作用域 @capyclaw/<name>
|
|
18
|
+
PACKAGE_NAME_PATTERN: /^((@[\w.-]+\/)?dsh-[\w.-]+|@capyclaw\/[\w.-]+)$/,
|
|
19
|
+
|
|
20
|
+
// 必需的 package.json 字段
|
|
21
|
+
REQUIRED_PKG_FIELDS: ['name', 'version', 'description', 'type', 'main', 'dsh', 'meta'],
|
|
22
|
+
|
|
23
|
+
// 必需的 dsh 字段
|
|
24
|
+
REQUIRED_DSH_FIELDS: ['category', 'platform'],
|
|
25
|
+
|
|
26
|
+
// 有效的插件分类
|
|
27
|
+
VALID_CATEGORIES: ['ui', 'service', 'bridge', 'tool', 'suite', 'skills'],
|
|
28
|
+
|
|
29
|
+
// 有效的平台
|
|
30
|
+
VALID_PLATFORMS: ['web', 'desktop', 'both'],
|
|
31
|
+
|
|
32
|
+
// 基础设施包的锁定版本范围(统一走 @capyclaw/* scope 名)
|
|
33
|
+
INFRASTRUCTURE_VERSIONS: {
|
|
34
|
+
'@capyclaw/foundation': '^0.1.1',
|
|
35
|
+
'@capyclaw/plugin-kit': '^0.2.0',
|
|
36
|
+
'@capyclaw/service-host': '^0.1.0',
|
|
37
|
+
'@capyclaw/tool-host': '^0.1.0',
|
|
38
|
+
'@capyclaw/asset-service': '^0.1.0',
|
|
39
|
+
'@capyclaw/suite-kit': '^0.1.0'
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* 验证插件
|
|
45
|
+
* @param {string} pluginPath - 插件目录的绝对路径
|
|
46
|
+
* @returns {Promise<{valid: boolean, errors: Array, warnings: Array}>}
|
|
47
|
+
*/
|
|
48
|
+
export async function validatePlugin(pluginPath) {
|
|
49
|
+
const errors = []
|
|
50
|
+
const warnings = []
|
|
51
|
+
|
|
52
|
+
// 1. 检查目录存在
|
|
53
|
+
if (!existsSync(pluginPath)) {
|
|
54
|
+
return {
|
|
55
|
+
valid: false,
|
|
56
|
+
errors: [{ rule: 'PATH', message: `插件目录不存在: ${pluginPath}` }],
|
|
57
|
+
warnings: []
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
if (!statSync(pluginPath).isDirectory()) {
|
|
62
|
+
return {
|
|
63
|
+
valid: false,
|
|
64
|
+
errors: [{ rule: 'PATH', message: `路径不是目录: ${pluginPath}` }],
|
|
65
|
+
warnings: []
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
// 2. 加载 package.json(必需文件检查需要区分 suite-only 组合包)
|
|
70
|
+
let pkg
|
|
71
|
+
try {
|
|
72
|
+
const pkgPath = join(pluginPath, 'package.json')
|
|
73
|
+
pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
|
|
74
|
+
} catch (error) {
|
|
75
|
+
checkRequiredFiles(pluginPath, null, errors)
|
|
76
|
+
if (!errors.some(e => e.rule === 'REQUIRED_FILES')) {
|
|
77
|
+
errors.push({
|
|
78
|
+
rule: 'PACKAGE_JSON',
|
|
79
|
+
message: `package.json 格式错误: ${error.message}`
|
|
80
|
+
})
|
|
81
|
+
}
|
|
82
|
+
return { valid: false, errors, warnings }
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
// 3. 检查必需文件
|
|
86
|
+
checkRequiredFiles(pluginPath, pkg, errors)
|
|
87
|
+
|
|
88
|
+
// 4. 验证 package.json 内容
|
|
89
|
+
checkPackageJson(pkg, errors, warnings)
|
|
90
|
+
|
|
91
|
+
// 5. 验证目录结构
|
|
92
|
+
checkDirectoryStructure(pluginPath, pkg, errors, warnings)
|
|
93
|
+
|
|
94
|
+
// 6. 验证依赖
|
|
95
|
+
checkDependencies(pkg, errors, warnings)
|
|
96
|
+
|
|
97
|
+
return {
|
|
98
|
+
valid: errors.length === 0,
|
|
99
|
+
errors,
|
|
100
|
+
warnings
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* 检查必需文件
|
|
106
|
+
*/
|
|
107
|
+
function checkRequiredFiles(pluginPath, pkg, errors) {
|
|
108
|
+
const suiteOnly = pkg?.dsh?.suite && !pkg?.main
|
|
109
|
+
/* 入口有两种合法形态:legacy 的 lib/ 目录,或 foundation ABI 的 plugin.mjs
|
|
110
|
+
* (由 package.json main 指向)。只要 main 可达即可,不再强制 lib/。 */
|
|
111
|
+
const hasEntry = Boolean(pkg?.main) && existsSync(join(pluginPath, pkg.main))
|
|
112
|
+
for (const file of RULES.REQUIRED_FILES) {
|
|
113
|
+
if (file === 'lib' && (suiteOnly || hasEntry)) continue
|
|
114
|
+
const filePath = join(pluginPath, file)
|
|
115
|
+
if (!existsSync(filePath)) {
|
|
116
|
+
errors.push({
|
|
117
|
+
rule: 'REQUIRED_FILES',
|
|
118
|
+
message: `缺少必需文件: ${file}`,
|
|
119
|
+
hint: file === 'lib' ? '创建 lib/ 目录并放入主入口文件' : `创建 ${file} 文件`
|
|
120
|
+
})
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/**
|
|
126
|
+
* 验证 package.json
|
|
127
|
+
*/
|
|
128
|
+
function checkPackageJson(pkg, errors, warnings) {
|
|
129
|
+
// 检查必需字段
|
|
130
|
+
for (const field of RULES.REQUIRED_PKG_FIELDS) {
|
|
131
|
+
// suite 组合包(dsh.suite 且无代码入口)没有 main 字段
|
|
132
|
+
if (field === 'main' && pkg.dsh?.suite && !pkg.main) continue
|
|
133
|
+
if (!pkg[field]) {
|
|
134
|
+
errors.push({
|
|
135
|
+
rule: 'PACKAGE_FIELDS',
|
|
136
|
+
message: `package.json 缺少必需字段: ${field}`,
|
|
137
|
+
hint: `在 package.json 中添加 "${field}" 字段`
|
|
138
|
+
})
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
// 检查包名规范
|
|
143
|
+
if (pkg.name && !RULES.PACKAGE_NAME_PATTERN.test(pkg.name)) {
|
|
144
|
+
errors.push({
|
|
145
|
+
rule: 'PACKAGE_NAME',
|
|
146
|
+
message: `包名不符合规范: ${pkg.name}`,
|
|
147
|
+
hint: '包名必须形如 "dsh-<name>"、"@org/dsh-<name>",或已发布作用域 "@capyclaw/<name>"'
|
|
148
|
+
})
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
// 检查版本号格式
|
|
152
|
+
if (pkg.version && !semver.valid(pkg.version)) {
|
|
153
|
+
errors.push({
|
|
154
|
+
rule: 'VERSION',
|
|
155
|
+
message: `版本号格式错误: ${pkg.version}`,
|
|
156
|
+
hint: '使用语义化版本,如 "1.0.0"'
|
|
157
|
+
})
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
// 检查 type 字段
|
|
161
|
+
if (pkg.type !== 'module') {
|
|
162
|
+
errors.push({
|
|
163
|
+
rule: 'MODULE_TYPE',
|
|
164
|
+
message: `必须使用 ESM 模块: type="${pkg.type || 'commonjs'}"`,
|
|
165
|
+
hint: '在 package.json 中设置 "type": "module"'
|
|
166
|
+
})
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
// 检查 dsh 字段
|
|
170
|
+
if (pkg.dsh) {
|
|
171
|
+
for (const field of RULES.REQUIRED_DSH_FIELDS) {
|
|
172
|
+
if (!pkg.dsh[field]) {
|
|
173
|
+
errors.push({
|
|
174
|
+
rule: 'DSH_FIELDS',
|
|
175
|
+
message: `dsh 配置缺少必需字段: ${field}`,
|
|
176
|
+
hint: `在 package.json 的 dsh 对象中添加 "${field}" 字段`
|
|
177
|
+
})
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
// 检查分类有效性
|
|
182
|
+
if (pkg.dsh.category && !RULES.VALID_CATEGORIES.includes(pkg.dsh.category)) {
|
|
183
|
+
errors.push({
|
|
184
|
+
rule: 'DSH_CATEGORY',
|
|
185
|
+
message: `无效的插件分类: ${pkg.dsh.category}`,
|
|
186
|
+
hint: `category 必须是: ${RULES.VALID_CATEGORIES.join(', ')}`
|
|
187
|
+
})
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
// 检查平台有效性
|
|
191
|
+
if (pkg.dsh.platform && !RULES.VALID_PLATFORMS.includes(pkg.dsh.platform)) {
|
|
192
|
+
errors.push({
|
|
193
|
+
rule: 'DSH_PLATFORM',
|
|
194
|
+
message: `无效的平台: ${pkg.dsh.platform}`,
|
|
195
|
+
hint: `platform 必须是: ${RULES.VALID_PLATFORMS.join(', ')}`
|
|
196
|
+
})
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
// 检查 meta 字段
|
|
201
|
+
if (pkg.meta) {
|
|
202
|
+
if (!pkg.meta.title) {
|
|
203
|
+
errors.push({
|
|
204
|
+
rule: 'META_TITLE',
|
|
205
|
+
message: 'meta.title 必需(用户可见的插件标题)',
|
|
206
|
+
hint: '在 package.json 的 meta 对象中添加 "title" 字段'
|
|
207
|
+
})
|
|
208
|
+
}
|
|
209
|
+
if (!pkg.meta.description) {
|
|
210
|
+
warnings.push('meta.description 建议提供(用户可见的详细描述)')
|
|
211
|
+
}
|
|
212
|
+
}
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
/**
|
|
216
|
+
* 检查目录结构
|
|
217
|
+
*/
|
|
218
|
+
function checkDirectoryStructure(pluginPath, pkg, errors, warnings) {
|
|
219
|
+
// 检查 lib/ 目录内容
|
|
220
|
+
const libPath = join(pluginPath, 'lib')
|
|
221
|
+
if (existsSync(libPath)) {
|
|
222
|
+
const libFiles = readdirSync(libPath)
|
|
223
|
+
if (libFiles.length === 0) {
|
|
224
|
+
errors.push({
|
|
225
|
+
rule: 'LIB_EMPTY',
|
|
226
|
+
message: 'lib/ 目录为空',
|
|
227
|
+
hint: '在 lib/ 中添加主入口文件(如 index.mjs)'
|
|
228
|
+
})
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
// 检查 main 字段指向的文件是否存在
|
|
232
|
+
if (pkg.main) {
|
|
233
|
+
const mainPath = join(pluginPath, pkg.main)
|
|
234
|
+
if (!existsSync(mainPath)) {
|
|
235
|
+
errors.push({
|
|
236
|
+
rule: 'MAIN_NOT_FOUND',
|
|
237
|
+
message: `main 字段指向的文件不存在: ${pkg.main}`,
|
|
238
|
+
hint: '确保 main 字段指向的文件存在'
|
|
239
|
+
})
|
|
240
|
+
}
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
// 检查 README.md 内容
|
|
245
|
+
const readmePath = join(pluginPath, 'README.md')
|
|
246
|
+
if (existsSync(readmePath)) {
|
|
247
|
+
const readme = readFileSync(readmePath, 'utf-8')
|
|
248
|
+
if (readme.trim().length < 100) {
|
|
249
|
+
warnings.push('README.md 内容过少,建议补充使用说明')
|
|
250
|
+
}
|
|
251
|
+
}
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
/**
|
|
255
|
+
* 检查依赖
|
|
256
|
+
*/
|
|
257
|
+
function checkDependencies(pkg, errors, warnings) {
|
|
258
|
+
const deps = pkg.dependencies || {}
|
|
259
|
+
|
|
260
|
+
// 强制:必须依赖 @capyclaw/foundation(新 ABI)或 @capyclaw/plugin-kit(legacy),suite 除外
|
|
261
|
+
if (pkg.dsh?.category !== 'suite') {
|
|
262
|
+
if (deps['@capyclaw/foundation']) {
|
|
263
|
+
const expectedVersion = RULES.INFRASTRUCTURE_VERSIONS['@capyclaw/foundation']
|
|
264
|
+
if (expectedVersion && !semver.satisfies(semver.coerce(deps['@capyclaw/foundation']), expectedVersion)) {
|
|
265
|
+
warnings.push(`@capyclaw/foundation 版本建议使用 ${expectedVersion},当前: ${deps['@capyclaw/foundation']}`)
|
|
266
|
+
}
|
|
267
|
+
} else if (!deps['@capyclaw/plugin-kit']) {
|
|
268
|
+
errors.push({
|
|
269
|
+
rule: 'PLUGIN_KIT_REQUIRED',
|
|
270
|
+
message: '必须依赖 @capyclaw/foundation 或 @capyclaw/plugin-kit',
|
|
271
|
+
hint: '在 dependencies 中添加 "@capyclaw/foundation": "^0.1.0"(新插件)'
|
|
272
|
+
})
|
|
273
|
+
} else {
|
|
274
|
+
// 检查版本范围
|
|
275
|
+
const expectedVersion = RULES.INFRASTRUCTURE_VERSIONS['@capyclaw/plugin-kit']
|
|
276
|
+
if (!semver.satisfies(semver.coerce(deps['@capyclaw/plugin-kit']), expectedVersion)) {
|
|
277
|
+
warnings.push(`@capyclaw/plugin-kit 版本建议使用 ${expectedVersion},当前: ${deps['@capyclaw/plugin-kit']}`)
|
|
278
|
+
}
|
|
279
|
+
}
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
// 检查其他基础设施包的版本
|
|
283
|
+
for (const [pkgName, expectedVersion] of Object.entries(RULES.INFRASTRUCTURE_VERSIONS)) {
|
|
284
|
+
if (deps[pkgName]) {
|
|
285
|
+
const actualVersion = deps[pkgName]
|
|
286
|
+
if (!semver.intersects(actualVersion, expectedVersion)) {
|
|
287
|
+
warnings.push(`${pkgName} 版本不匹配,建议: ${expectedVersion},当前: ${actualVersion}`)
|
|
288
|
+
}
|
|
289
|
+
}
|
|
290
|
+
}
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
/**
|
|
294
|
+
* 批量验证多个插件
|
|
295
|
+
*/
|
|
296
|
+
export async function validatePlugins(pluginPaths) {
|
|
297
|
+
const results = []
|
|
298
|
+
for (const path of pluginPaths) {
|
|
299
|
+
const result = await validatePlugin(path)
|
|
300
|
+
results.push({ path, ...result })
|
|
301
|
+
}
|
|
302
|
+
return results
|
|
303
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,28 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@capyclaw/plugin-validator",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "1.0.1",
|
|
4
|
+
"description": "DSH 插件强制验证工具:检查目录结构、依赖规范、代码质量",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "./lib/index.mjs",
|
|
7
|
+
"bin": {
|
|
8
|
+
"validate-plugin": "./bin/cli.mjs"
|
|
9
|
+
},
|
|
10
|
+
"scripts": {},
|
|
11
|
+
"dependencies": {
|
|
12
|
+
"semver": "^7.5.4",
|
|
13
|
+
"yaml": "^2.3.4"
|
|
14
|
+
},
|
|
15
|
+
"publishConfig": {
|
|
16
|
+
"access": "public"
|
|
17
|
+
},
|
|
18
|
+
"license": "MIT",
|
|
19
|
+
"repository": {
|
|
20
|
+
"type": "git",
|
|
21
|
+
"url": "git+https://github.com/Maple496/capyclaw.git",
|
|
22
|
+
"directory": "C/tools/capyclaw-plugin-validator"
|
|
23
|
+
},
|
|
24
|
+
"bugs": {
|
|
25
|
+
"url": "https://github.com/Maple496/capyclaw/issues"
|
|
26
|
+
},
|
|
27
|
+
"homepage": "https://github.com/Maple496/capyclaw/tree/main/C/tools/capyclaw-plugin-validator#readme"
|
|
28
|
+
}
|
package/README.md
DELETED