@capyclaw/plugin-validator 0.0.0-stage → 1.0.0

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 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 extensions/official/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,295 @@
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/plugin-kit': '^0.2.0',
35
+ '@capyclaw/service-host': '^0.1.0',
36
+ '@capyclaw/tool-host': '^0.1.0',
37
+ '@capyclaw/asset-service': '^0.1.0',
38
+ '@capyclaw/suite-kit': '^0.1.0'
39
+ }
40
+ }
41
+
42
+ /**
43
+ * 验证插件
44
+ * @param {string} pluginPath - 插件目录的绝对路径
45
+ * @returns {Promise<{valid: boolean, errors: Array, warnings: Array}>}
46
+ */
47
+ export async function validatePlugin(pluginPath) {
48
+ const errors = []
49
+ const warnings = []
50
+
51
+ // 1. 检查目录存在
52
+ if (!existsSync(pluginPath)) {
53
+ return {
54
+ valid: false,
55
+ errors: [{ rule: 'PATH', message: `插件目录不存在: ${pluginPath}` }],
56
+ warnings: []
57
+ }
58
+ }
59
+
60
+ if (!statSync(pluginPath).isDirectory()) {
61
+ return {
62
+ valid: false,
63
+ errors: [{ rule: 'PATH', message: `路径不是目录: ${pluginPath}` }],
64
+ warnings: []
65
+ }
66
+ }
67
+
68
+ // 2. 加载 package.json(必需文件检查需要区分 suite-only 组合包)
69
+ let pkg
70
+ try {
71
+ const pkgPath = join(pluginPath, 'package.json')
72
+ pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
73
+ } catch (error) {
74
+ checkRequiredFiles(pluginPath, null, errors)
75
+ if (!errors.some(e => e.rule === 'REQUIRED_FILES')) {
76
+ errors.push({
77
+ rule: 'PACKAGE_JSON',
78
+ message: `package.json 格式错误: ${error.message}`
79
+ })
80
+ }
81
+ return { valid: false, errors, warnings }
82
+ }
83
+
84
+ // 3. 检查必需文件
85
+ checkRequiredFiles(pluginPath, pkg, errors)
86
+
87
+ // 4. 验证 package.json 内容
88
+ checkPackageJson(pkg, errors, warnings)
89
+
90
+ // 5. 验证目录结构
91
+ checkDirectoryStructure(pluginPath, pkg, errors, warnings)
92
+
93
+ // 6. 验证依赖
94
+ checkDependencies(pkg, errors, warnings)
95
+
96
+ return {
97
+ valid: errors.length === 0,
98
+ errors,
99
+ warnings
100
+ }
101
+ }
102
+
103
+ /**
104
+ * 检查必需文件
105
+ */
106
+ function checkRequiredFiles(pluginPath, pkg, errors) {
107
+ const suiteOnly = pkg?.dsh?.suite && !pkg?.main
108
+ for (const file of RULES.REQUIRED_FILES) {
109
+ // suite 组合包(dsh.suite 且无代码入口)没有 lib/ 目录
110
+ if (file === 'lib' && suiteOnly) continue
111
+ const filePath = join(pluginPath, file)
112
+ if (!existsSync(filePath)) {
113
+ errors.push({
114
+ rule: 'REQUIRED_FILES',
115
+ message: `缺少必需文件: ${file}`,
116
+ hint: file === 'lib' ? '创建 lib/ 目录并放入主入口文件' : `创建 ${file} 文件`
117
+ })
118
+ }
119
+ }
120
+ }
121
+
122
+ /**
123
+ * 验证 package.json
124
+ */
125
+ function checkPackageJson(pkg, errors, warnings) {
126
+ // 检查必需字段
127
+ for (const field of RULES.REQUIRED_PKG_FIELDS) {
128
+ // suite 组合包(dsh.suite 且无代码入口)没有 main 字段
129
+ if (field === 'main' && pkg.dsh?.suite && !pkg.main) continue
130
+ if (!pkg[field]) {
131
+ errors.push({
132
+ rule: 'PACKAGE_FIELDS',
133
+ message: `package.json 缺少必需字段: ${field}`,
134
+ hint: `在 package.json 中添加 "${field}" 字段`
135
+ })
136
+ }
137
+ }
138
+
139
+ // 检查包名规范
140
+ if (pkg.name && !RULES.PACKAGE_NAME_PATTERN.test(pkg.name)) {
141
+ errors.push({
142
+ rule: 'PACKAGE_NAME',
143
+ message: `包名不符合规范: ${pkg.name}`,
144
+ hint: '包名必须形如 "dsh-<name>"、"@org/dsh-<name>",或已发布作用域 "@capyclaw/<name>"'
145
+ })
146
+ }
147
+
148
+ // 检查版本号格式
149
+ if (pkg.version && !semver.valid(pkg.version)) {
150
+ errors.push({
151
+ rule: 'VERSION',
152
+ message: `版本号格式错误: ${pkg.version}`,
153
+ hint: '使用语义化版本,如 "1.0.0"'
154
+ })
155
+ }
156
+
157
+ // 检查 type 字段
158
+ if (pkg.type !== 'module') {
159
+ errors.push({
160
+ rule: 'MODULE_TYPE',
161
+ message: `必须使用 ESM 模块: type="${pkg.type || 'commonjs'}"`,
162
+ hint: '在 package.json 中设置 "type": "module"'
163
+ })
164
+ }
165
+
166
+ // 检查 dsh 字段
167
+ if (pkg.dsh) {
168
+ for (const field of RULES.REQUIRED_DSH_FIELDS) {
169
+ if (!pkg.dsh[field]) {
170
+ errors.push({
171
+ rule: 'DSH_FIELDS',
172
+ message: `dsh 配置缺少必需字段: ${field}`,
173
+ hint: `在 package.json 的 dsh 对象中添加 "${field}" 字段`
174
+ })
175
+ }
176
+ }
177
+
178
+ // 检查分类有效性
179
+ if (pkg.dsh.category && !RULES.VALID_CATEGORIES.includes(pkg.dsh.category)) {
180
+ errors.push({
181
+ rule: 'DSH_CATEGORY',
182
+ message: `无效的插件分类: ${pkg.dsh.category}`,
183
+ hint: `category 必须是: ${RULES.VALID_CATEGORIES.join(', ')}`
184
+ })
185
+ }
186
+
187
+ // 检查平台有效性
188
+ if (pkg.dsh.platform && !RULES.VALID_PLATFORMS.includes(pkg.dsh.platform)) {
189
+ errors.push({
190
+ rule: 'DSH_PLATFORM',
191
+ message: `无效的平台: ${pkg.dsh.platform}`,
192
+ hint: `platform 必须是: ${RULES.VALID_PLATFORMS.join(', ')}`
193
+ })
194
+ }
195
+ }
196
+
197
+ // 检查 meta 字段
198
+ if (pkg.meta) {
199
+ if (!pkg.meta.title) {
200
+ errors.push({
201
+ rule: 'META_TITLE',
202
+ message: 'meta.title 必需(用户可见的插件标题)',
203
+ hint: '在 package.json 的 meta 对象中添加 "title" 字段'
204
+ })
205
+ }
206
+ if (!pkg.meta.description) {
207
+ warnings.push('meta.description 建议提供(用户可见的详细描述)')
208
+ }
209
+ }
210
+ }
211
+
212
+ /**
213
+ * 检查目录结构
214
+ */
215
+ function checkDirectoryStructure(pluginPath, pkg, errors, warnings) {
216
+ // 检查 lib/ 目录内容
217
+ const libPath = join(pluginPath, 'lib')
218
+ if (existsSync(libPath)) {
219
+ const libFiles = readdirSync(libPath)
220
+ if (libFiles.length === 0) {
221
+ errors.push({
222
+ rule: 'LIB_EMPTY',
223
+ message: 'lib/ 目录为空',
224
+ hint: '在 lib/ 中添加主入口文件(如 index.mjs)'
225
+ })
226
+ }
227
+
228
+ // 检查 main 字段指向的文件是否存在
229
+ if (pkg.main) {
230
+ const mainPath = join(pluginPath, pkg.main)
231
+ if (!existsSync(mainPath)) {
232
+ errors.push({
233
+ rule: 'MAIN_NOT_FOUND',
234
+ message: `main 字段指向的文件不存在: ${pkg.main}`,
235
+ hint: '确保 main 字段指向的文件存在'
236
+ })
237
+ }
238
+ }
239
+ }
240
+
241
+ // 检查 README.md 内容
242
+ const readmePath = join(pluginPath, 'README.md')
243
+ if (existsSync(readmePath)) {
244
+ const readme = readFileSync(readmePath, 'utf-8')
245
+ if (readme.trim().length < 100) {
246
+ warnings.push('README.md 内容过少,建议补充使用说明')
247
+ }
248
+ }
249
+ }
250
+
251
+ /**
252
+ * 检查依赖
253
+ */
254
+ function checkDependencies(pkg, errors, warnings) {
255
+ const deps = pkg.dependencies || {}
256
+
257
+ // 强制:必须依赖 @capyclaw/plugin-kit(除非是 suite)
258
+ if (pkg.dsh?.category !== 'suite') {
259
+ if (!deps['@capyclaw/plugin-kit']) {
260
+ errors.push({
261
+ rule: 'PLUGIN_KIT_REQUIRED',
262
+ message: '必须依赖 @capyclaw/plugin-kit',
263
+ hint: '在 dependencies 中添加 "@capyclaw/plugin-kit": "^0.2.0"'
264
+ })
265
+ } else {
266
+ // 检查版本范围
267
+ const expectedVersion = RULES.INFRASTRUCTURE_VERSIONS['@capyclaw/plugin-kit']
268
+ if (!semver.satisfies(semver.coerce(deps['@capyclaw/plugin-kit']), expectedVersion)) {
269
+ warnings.push(`@capyclaw/plugin-kit 版本建议使用 ${expectedVersion},当前: ${deps['@capyclaw/plugin-kit']}`)
270
+ }
271
+ }
272
+ }
273
+
274
+ // 检查其他基础设施包的版本
275
+ for (const [pkgName, expectedVersion] of Object.entries(RULES.INFRASTRUCTURE_VERSIONS)) {
276
+ if (deps[pkgName]) {
277
+ const actualVersion = deps[pkgName]
278
+ if (!semver.intersects(actualVersion, expectedVersion)) {
279
+ warnings.push(`${pkgName} 版本不匹配,建议: ${expectedVersion},当前: ${actualVersion}`)
280
+ }
281
+ }
282
+ }
283
+ }
284
+
285
+ /**
286
+ * 批量验证多个插件
287
+ */
288
+ export async function validatePlugins(pluginPaths) {
289
+ const results = []
290
+ for (const path of pluginPaths) {
291
+ const result = await validatePlugin(path)
292
+ results.push({ path, ...result })
293
+ }
294
+ return results
295
+ }
package/package.json CHANGED
@@ -1,6 +1,28 @@
1
1
  {
2
2
  "name": "@capyclaw/plugin-validator",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.0.0",
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": "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/tools/capyclaw-plugin-validator#readme"
28
+ }
package/README.md DELETED
@@ -1,3 +0,0 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.