@capyclaw/skills-service 0.1.3 → 0.2.2

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.
Files changed (68) hide show
  1. package/README.md +7 -7
  2. package/node_modules/@capyclaw/foundation/README.md +51 -0
  3. package/node_modules/@capyclaw/foundation/abi/bridge.mjs +86 -0
  4. package/node_modules/@capyclaw/foundation/abi/errors.mjs +63 -0
  5. package/node_modules/@capyclaw/foundation/abi/index.mjs +35 -0
  6. package/node_modules/@capyclaw/foundation/abi/kinds.mjs +271 -0
  7. package/node_modules/@capyclaw/foundation/abi/loader.mjs +345 -0
  8. package/node_modules/@capyclaw/foundation/abi/schema.mjs +98 -0
  9. package/node_modules/@capyclaw/foundation/abi/spec.mjs +255 -0
  10. package/node_modules/@capyclaw/foundation/abi/validate.mjs +24 -0
  11. package/node_modules/@capyclaw/foundation/abi/version.mjs +82 -0
  12. package/node_modules/@capyclaw/foundation/cordis.patch.yml +5 -0
  13. package/node_modules/@capyclaw/foundation/kit/index.mjs +6 -0
  14. package/node_modules/@capyclaw/foundation/lib/adapters/client-panel.mjs +98 -0
  15. package/node_modules/@capyclaw/foundation/lib/adapters/host-event.mjs +35 -0
  16. package/node_modules/@capyclaw/foundation/lib/adapters/http-router.mjs +69 -0
  17. package/node_modules/@capyclaw/foundation/lib/adapters/lifecycle-hook.mjs +55 -0
  18. package/node_modules/@capyclaw/foundation/lib/adapters/own-server.mjs +113 -0
  19. package/node_modules/@capyclaw/foundation/lib/adapters/raw.mjs +68 -0
  20. package/node_modules/@capyclaw/foundation/lib/adapters/runtime-driver.mjs +113 -0
  21. package/node_modules/@capyclaw/foundation/lib/adapters/service-provider.mjs +77 -0
  22. package/node_modules/@capyclaw/foundation/lib/adapters/skill-provider.mjs +56 -0
  23. package/node_modules/@capyclaw/foundation/lib/adapters/tool-provider.mjs +50 -0
  24. package/node_modules/@capyclaw/foundation/lib/adapters/ui-panel.mjs +64 -0
  25. package/node_modules/@capyclaw/foundation/lib/ctx-service.mjs +42 -0
  26. package/node_modules/@capyclaw/foundation/lib/host/caps.mjs +34 -0
  27. package/node_modules/@capyclaw/foundation/lib/host/contract.mjs +85 -0
  28. package/node_modules/@capyclaw/foundation/lib/host/dsh.mjs +50 -0
  29. package/node_modules/@capyclaw/foundation/lib/host/memory.mjs +160 -0
  30. package/node_modules/@capyclaw/foundation/lib/host.mjs +23 -0
  31. package/node_modules/@capyclaw/foundation/lib/kernel.mjs +185 -0
  32. package/node_modules/@capyclaw/foundation/lib/skill/scan.mjs +87 -0
  33. package/node_modules/@capyclaw/foundation/lib/subsystems/events.mjs +60 -0
  34. package/node_modules/@capyclaw/foundation/lib/subsystems/log.mjs +51 -0
  35. package/node_modules/@capyclaw/foundation/lib/subsystems/net.mjs +188 -0
  36. package/node_modules/@capyclaw/foundation/package.json +53 -0
  37. package/node_modules/@capyclaw/foundation/runtime/index.mjs +20 -0
  38. package/node_modules/@capyclaw/plugin-kit/INTEGRATION.md +100 -0
  39. package/node_modules/@capyclaw/plugin-kit/README.md +70 -0
  40. package/node_modules/@capyclaw/plugin-kit/bin/sync.mjs +103 -0
  41. package/node_modules/@capyclaw/plugin-kit/package.json +69 -0
  42. package/node_modules/@capyclaw/plugin-kit/src/cli.mjs +56 -0
  43. package/node_modules/@capyclaw/plugin-kit/src/config.mjs +142 -0
  44. package/node_modules/@capyclaw/plugin-kit/src/editor/heartbeat-worker.js +129 -0
  45. package/node_modules/@capyclaw/plugin-kit/src/editor/lease.mjs +139 -0
  46. package/node_modules/@capyclaw/plugin-kit/src/editor/shadow.mjs +219 -0
  47. package/node_modules/@capyclaw/plugin-kit/src/editor/transport.js +13 -0
  48. package/node_modules/@capyclaw/plugin-kit/src/index.mjs +13 -0
  49. package/node_modules/@capyclaw/plugin-kit/src/pack.mjs +230 -0
  50. package/node_modules/@capyclaw/plugin-kit/src/runtime/context.mjs +128 -0
  51. package/node_modules/@capyclaw/plugin-kit/src/self-contained.mjs +307 -0
  52. package/node_modules/@capyclaw/plugin-kit/src/service/api.mjs +45 -0
  53. package/node_modules/@capyclaw/plugin-kit/src/service/http.mjs +113 -0
  54. package/node_modules/@capyclaw/plugin-kit/src/service/mcp-http.mjs +143 -0
  55. package/node_modules/@capyclaw/plugin-kit/src/service/server.mjs +131 -0
  56. package/node_modules/@capyclaw/plugin-kit/src/skills/provider.mjs +82 -0
  57. package/node_modules/@capyclaw/plugin-kit/src/store/blob-store.mjs +109 -0
  58. package/node_modules/@capyclaw/plugin-kit/src/store/content-store.mjs +17 -0
  59. package/node_modules/@capyclaw/plugin-kit/src/store/journal-store.mjs +89 -0
  60. package/node_modules/@capyclaw/plugin-kit/src/tools/result.mjs +41 -0
  61. package/node_modules/@capyclaw/plugin-kit/src/tools/validate.mjs +150 -0
  62. package/node_modules/@capyclaw/plugin-kit/src/tuning.mjs +82 -0
  63. package/node_modules/@capyclaw/plugin-kit/src/util/fs-lock.mjs +132 -0
  64. package/node_modules/@capyclaw/plugin-kit/src/util/http.mjs +130 -0
  65. package/node_modules/@capyclaw/plugin-kit/src/workspace/manager.mjs +656 -0
  66. package/node_modules/@capyclaw/plugin-kit/src/zip.mjs +181 -0
  67. package/package.json +18 -2
  68. package/server.mjs +237 -201
@@ -0,0 +1,255 @@
1
+ /**
2
+ * 插件描述符:应用插件唯一需要写的东西。
3
+ *
4
+ * import { createPlugin, skillProvider } from '@capyclaw/foundation/abi'
5
+ *
6
+ * export const { name, inject, apply } = createPlugin({
7
+ * name: 'canvas',
8
+ * requires: ['canvas.runtime@^1'],
9
+ * implements: [skillProvider({ skill: './skills/canvas' })],
10
+ * }, import.meta.url)
11
+ *
12
+ * 设计要点:
13
+ * - 构建器在模块加载期就校验 schema,坏描述符不会活到 activate;
14
+ * - 描述符是纯数据 + 函数,不 import 内核、不持有 ctx;
15
+ * - createPlugin 产出的是普通 Cordis 插件形状(name/inject/apply),
16
+ * 装配细节全部收回内核的 mount。
17
+ */
18
+ import { ABI_MAJOR, getInterfaceKind } from './kinds.mjs'
19
+ import { validateSchema } from './schema.mjs'
20
+ import { validateInterface } from './validate.mjs'
21
+ import { AbiError, ERROR_CODES, toAbiError } from './errors.mjs'
22
+
23
+ const PLUGIN_NAME_RE = /^[a-z0-9][a-z0-9-]*$/
24
+ const CAPABILITY_NAME_RE = /^[a-zA-Z][a-zA-Z0-9]*(?:[.-][a-zA-Z0-9*]+)*$/
25
+ const RANGE_RE = /^(?:\^|~|>=|<=|>|<|=)?[0-9x*][0-9A-Za-z.*-]*$/
26
+
27
+ const KINDS = Object.freeze({
28
+ 'skill-provider': 'skill-provider@1',
29
+ 'tool-provider': 'tool-provider@1',
30
+ 'runtime-driver': 'runtime-driver@1',
31
+ 'http-router': 'http-router@1',
32
+ 'ui-panel': 'ui-panel@1',
33
+ 'lifecycle-hook': 'lifecycle-hook@1',
34
+ 'host-event': 'host-event@1',
35
+ 'client-panel': 'client-panel@1',
36
+ 'own-server': 'own-server@1',
37
+ 'service-provider': 'service-provider@1',
38
+ raw: 'raw@1',
39
+ })
40
+
41
+ /**
42
+ * 校验并冻结一个接口描述符。
43
+ * @param {string} kind
44
+ * @param {object} options
45
+ */
46
+ export function defineInterface(kind, options) {
47
+ const definition = getInterfaceKind(kind)
48
+ if (!definition) {
49
+ throw new AbiError(ERROR_CODES.E_KIND_UNKNOWN, `未知接口种类 ${kind}`, {
50
+ kind,
51
+ known: Object.keys(KINDS).map((key) => KINDS[key]),
52
+ })
53
+ }
54
+ if (options === null || typeof options !== 'object' || Array.isArray(options)) {
55
+ throw new AbiError(ERROR_CODES.E_SCHEMA, `${kind} 的描述符必须是对象`, { kind })
56
+ }
57
+ const errors = validateSchema(options, definition.schema)
58
+ definition.extra?.(options, errors)
59
+ if (errors.length) {
60
+ throw new AbiError(ERROR_CODES.E_SCHEMA, `${kind} 描述符非法:${errors.join(';')}`, { kind, errors })
61
+ }
62
+ return Object.freeze({ kind, ...options })
63
+ }
64
+
65
+ /* ------------------------------------------------------------------------- */
66
+ /* 六个接口构建器 + 逃生舱 */
67
+ /* ------------------------------------------------------------------------- */
68
+
69
+ export const skillProvider = (options) => defineInterface(KINDS['skill-provider'], options)
70
+ export const toolProvider = (options) => defineInterface(KINDS['tool-provider'], options)
71
+ export const runtimeDriver = (options) => defineInterface(KINDS['runtime-driver'], options)
72
+ export const httpRouter = (options) => defineInterface(KINDS['http-router'], options)
73
+ export const uiPanel = (options) => defineInterface(KINDS['ui-panel'], options)
74
+ export const lifecycleHook = (options) => defineInterface(KINDS['lifecycle-hook'], options)
75
+ export const hostEvent = (options) => defineInterface(KINDS['host-event'], options)
76
+ export const clientPanel = (options) => defineInterface(KINDS['client-panel'], options)
77
+ export const ownServer = (options) => defineInterface(KINDS['own-server'], options)
78
+ export const serviceProvider = (options) => defineInterface(KINDS['service-provider'], options)
79
+
80
+ /**
81
+ * 驱动层统一入口:基建插件用 defineDriver 声明「我提供哪个 ctx 服务」。
82
+ *
83
+ * 与 createPlugin 的关键区别:不 inject os。驱动必须能在 foundation 之前/之后
84
+ * 独立激活,否则 foundation 的 os.net/os.tools/os.proc 会失去服务来源。
85
+ * apply 仍拿到原生 Cordis ctx,因为提供 ctx.provide 是驱动层的职责。
86
+ */
87
+ export function defineDriver(options = {}) {
88
+ const { name, service, inject = [], apply } = options
89
+ if (!PLUGIN_NAME_RE.test(String(name || ''))) {
90
+ throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE, `driver 名必须是 kebab-case:${name}`, { name })
91
+ }
92
+ if (typeof service !== 'string' || !service.trim()) {
93
+ throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE, 'driver.service 必须是非空字符串', { name, service })
94
+ }
95
+ if (!Array.isArray(inject) || inject.some((item) => typeof item !== 'string' || !item.trim())) {
96
+ throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE, 'driver.inject 必须是非空字符串数组', { name })
97
+ }
98
+ if (typeof apply !== 'function') {
99
+ throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE, 'driver.apply 必须是函数', { name, service })
100
+ }
101
+ return Object.freeze({
102
+ name,
103
+ inject: Object.freeze([...inject]),
104
+ apply,
105
+ driver: Object.freeze({ service }),
106
+ })
107
+ }
108
+
109
+ /** 逃生舱:必须同时导出 apply,且不得与其他接口混用。 */
110
+ export const rawPlugin = (apply) => defineInterface(KINDS.raw, { apply })
111
+
112
+ /* ------------------------------------------------------------------------- */
113
+ /* 插件定义 */
114
+ /* ------------------------------------------------------------------------- */
115
+
116
+ function parseCapability(entry, field) {
117
+ if (typeof entry !== 'string' || !entry.trim()) {
118
+ throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE, `${field} 的每一项必须是非空字符串`, { entry })
119
+ }
120
+ const at = entry.lastIndexOf('@')
121
+ if (at <= 0 || at === entry.length - 1) {
122
+ throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE, `${field} 项 "${entry}" 必须写成 name@range`, { entry })
123
+ }
124
+ const name = entry.slice(0, at)
125
+ const range = entry.slice(at + 1)
126
+ if (!CAPABILITY_NAME_RE.test(name)) {
127
+ throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE, `${field} 项 "${entry}" 的能力名非法`, { entry, name })
128
+ }
129
+ if (!RANGE_RE.test(range)) {
130
+ throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE, `${field} 项 "${entry}" 的版本范围非法`, { entry, range })
131
+ }
132
+ return Object.freeze({ name, range, raw: entry })
133
+ }
134
+
135
+ /**
136
+ * @param {{
137
+ * name: string,
138
+ * apiVersion?: number,
139
+ * description?: string,
140
+ * requires?: string[],
141
+ * provides?: string[],
142
+ * implements: object[]
143
+ * }} options
144
+ */
145
+ export function definePlugin(options = {}) {
146
+ const {
147
+ name, apiVersion = ABI_MAJOR, description, requires = [], provides = [], inject = [], implements: impls,
148
+ } = options
149
+
150
+ if (!PLUGIN_NAME_RE.test(String(name || ''))) {
151
+ throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE, `插件名必须是 kebab-case:${name}`, { name })
152
+ }
153
+ if (!Number.isInteger(apiVersion) || apiVersion !== ABI_MAJOR) {
154
+ throw new AbiError(ERROR_CODES.E_ABI_MISMATCH,
155
+ `插件声明 ABI v${apiVersion},内核只支持 v${ABI_MAJOR}`, { name, apiVersion, supported: ABI_MAJOR })
156
+ }
157
+ if (!Array.isArray(impls) || impls.length === 0) {
158
+ throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE, '插件必须实现至少一个接口', { name })
159
+ }
160
+ if (description !== undefined && typeof description !== 'string') {
161
+ throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE, 'description 必须是字符串', { name })
162
+ }
163
+ /* 附加 Cordis inject 只给 raw@1 逃生舱使用:它需要保留原插件的宿主服务依赖。
164
+ * 普通描述符不接受这个字段,避免把宿主服务名泄漏进应用 ABI。 */
165
+ if (!Array.isArray(inject) || inject.some((item) => typeof item !== 'string' || !item.trim())) {
166
+ throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE, 'inject 必须是非空字符串数组', { name })
167
+ }
168
+ if (inject.length && !impls?.some((impl) => impl?.kind === 'raw@1')) {
169
+ throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE, '只有 raw@1 插件可以声明额外 inject', { name })
170
+ }
171
+
172
+ for (const impl of impls) {
173
+ if (!impl || typeof impl !== 'object' || typeof impl.kind !== 'string') {
174
+ throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE, 'implements 的每一项必须是 define* 产出的描述符', { name })
175
+ }
176
+ const { definition, errors } = validateInterface(impl)
177
+ if (!definition) {
178
+ throw new AbiError(ERROR_CODES.E_KIND_UNKNOWN, `未知接口种类 ${impl.kind}`, { name, kind: impl.kind })
179
+ }
180
+ if (errors.length) {
181
+ throw new AbiError(ERROR_CODES.E_SCHEMA, `${impl.kind} 描述符非法:${errors.join(';')}`, {
182
+ name, kind: impl.kind, errors,
183
+ })
184
+ }
185
+ }
186
+
187
+ if (impls.some((impl) => getInterfaceKind(impl.kind)?.exclusive) && impls.length > 1) {
188
+ throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE, 'raw@1 不得与其他接口混用', { name })
189
+ }
190
+
191
+ const requiresEntries = requires.map((entry) => parseCapability(entry, 'requires'))
192
+ const providesEntries = provides.map((entry) => parseCapability(entry, 'provides'))
193
+ for (const entry of providesEntries) {
194
+ if (/^[\^~<>=]/.test(entry.range)) {
195
+ throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE,
196
+ `provides 必须写精确版本,不能写范围:${entry.raw}`, { entry: entry.raw })
197
+ }
198
+ }
199
+
200
+ return Object.freeze({
201
+ kind: 'plugin',
202
+ name,
203
+ apiVersion,
204
+ description,
205
+ requires: Object.freeze(requiresEntries),
206
+ provides: Object.freeze(providesEntries),
207
+ inject: Object.freeze([...inject]),
208
+ implements: Object.freeze([...impls]),
209
+ })
210
+ }
211
+
212
+ /* ------------------------------------------------------------------------- */
213
+ /* Cordis 接缝 */
214
+ /* ------------------------------------------------------------------------- */
215
+
216
+ /**
217
+ * 把插件定义编译成普通 Cordis 插件:{ name, inject, apply }。
218
+ *
219
+ * apply 的返回值是 disposer(与仓内既有插件一致),内核在卸载时调用。
220
+ * 形状错误(schema / 能力 / 唯一性)同步抛出,让插件加载直接失败;
221
+ * 运行时就绪(子进程拉起等)异步进行,通过 os.report() 观测。
222
+ *
223
+ * @param {object} definition definePlugin 的结果,或直接传 definePlugin 的入参
224
+ * @param {string} baseUrl 插件入口的 import.meta.url,用于解析相对路径
225
+ */
226
+ export function createPlugin(definition, baseUrl) {
227
+ const spec = definition?.kind === 'plugin' ? definition : definePlugin(definition)
228
+
229
+ function apply(ctx, config = {}) {
230
+ const os = ctx?.os
231
+ if (!os || typeof os.mount !== 'function') {
232
+ throw new AbiError(ERROR_CODES.E_KERNEL_MISSING,
233
+ 'ctx.os 不可用:请先安装并启用 @capyclaw/core(公共基建唯一声明者),它会连同 @capyclaw/foundation 一起挂上 os 内核', { plugin: spec.name })
234
+ }
235
+ if (!baseUrl) {
236
+ throw new AbiError(ERROR_CODES.E_BASE_URL_MISSING,
237
+ 'createPlugin 需要第二参数 baseUrl(传 import.meta.url)', { plugin: spec.name })
238
+ }
239
+ const handle = os.mount(spec, config, { baseUrl, ctx })
240
+ const dispose = () => handle.dispose()
241
+ // Cordis 只认 ctx.effect 登记的 disposer,apply 的返回值并不可靠:
242
+ // 不显式登记的话,关掉插件再启用时旧记录还占着 name,会撞 E_DUP_PLUGIN。
243
+ if (typeof ctx?.effect === 'function') ctx.effect(() => () => { void dispose() })
244
+ return dispose
245
+ }
246
+
247
+ return Object.freeze({
248
+ name: spec.name,
249
+ inject: Object.freeze(['os', ...spec.inject.filter((service) => service !== 'os')]),
250
+ apply,
251
+ spec,
252
+ })
253
+ }
254
+
255
+ export { toAbiError }
@@ -0,0 +1,24 @@
1
+ /**
2
+ * 描述符校验:把「kind 之外的全部字段」交给对应接口的 schema。
3
+ *
4
+ * 单独成模块,是因为 spec(构建期)与 loader(加载期)必须用同一套判定;
5
+ * 只要两处各写一遍,迟早会出现「构建能过、加载失败」或反过来。
6
+ */
7
+ import { getInterfaceKind } from './kinds.mjs'
8
+ import { validateSchema } from './schema.mjs'
9
+
10
+ /**
11
+ * @param {object} impl 描述符(含 kind)
12
+ * @returns {{ definition: object|null, errors: string[] }}
13
+ */
14
+ export function validateInterface(impl) {
15
+ const definition = getInterfaceKind(impl?.kind)
16
+ if (!definition) {
17
+ return { definition: null, errors: [`未知接口种类 ${impl?.kind}`] }
18
+ }
19
+ const body = { ...impl }
20
+ delete body.kind
21
+ const errors = validateSchema(body, definition.schema)
22
+ definition.extra?.(body, errors)
23
+ return { definition, errors }
24
+ }
@@ -0,0 +1,82 @@
1
+ /**
2
+ * 版本与范围:能力声明用 `^1` / `^1.2.0` / `>=1.2` / `1.x` / 精确版本。
3
+ *
4
+ * 只实现这份 ABI 需要的语义,不引入 semver 依赖:
5
+ * - `^1.2.3` → >=1.2.3 且同主版本;`^0.2.3` → >=0.2.3 且同次版本(0.x 约定)
6
+ * - `~1.2.3` → >=1.2.3 且同次版本
7
+ * - `1.x` / `1.*` → 同主版本
8
+ * - `>=` `>` `<=` `<` `=` 前缀
9
+ * - 裸版本 → 精确匹配(比较时忽略末位 0)
10
+ */
11
+
12
+ export function parseVersion(text) {
13
+ if (typeof text !== 'string') return null
14
+ const match = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-[0-9A-Za-z.-]+)?$/.exec(text.trim())
15
+ if (!match) return null
16
+ return [Number(match[1]), Number(match[2] || 0), Number(match[3] || 0)]
17
+ }
18
+
19
+ function compareParts(a, b) {
20
+ for (let i = 0; i < 3; i++) {
21
+ if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1
22
+ }
23
+ return 0
24
+ }
25
+
26
+ export function compareVersions(a, b) {
27
+ const left = typeof a === 'string' ? parseVersion(a) : a
28
+ const right = typeof b === 'string' ? parseVersion(b) : b
29
+ if (!left || !right) return NaN
30
+ return compareParts(left, right)
31
+ }
32
+
33
+ /**
34
+ * @param {string} version 提供方版本,如 '1.2.3'
35
+ * @param {string} range 需求范围,如 '^1'
36
+ * @returns {boolean}
37
+ */
38
+ export function satisfies(version, range) {
39
+ const current = parseVersion(version)
40
+ if (!current) return false
41
+ const raw = String(range ?? '').trim()
42
+ if (!raw || raw === '*' || raw === 'x') return true
43
+
44
+ if (raw.startsWith('^')) {
45
+ const base = parseVersion(raw.slice(1))
46
+ if (!base) return false
47
+ if (compareParts(current, base) < 0) return false
48
+ return base[0] === 0 ? current[0] === 0 && current[1] === base[1] : current[0] === base[0]
49
+ }
50
+ if (raw.startsWith('~')) {
51
+ const base = parseVersion(raw.slice(1))
52
+ if (!base) return false
53
+ return compareParts(current, base) >= 0 && current[0] === base[0] && current[1] === base[1]
54
+ }
55
+ if (raw.startsWith('>=')) {
56
+ const base = parseVersion(raw.slice(2))
57
+ return Boolean(base) && compareParts(current, base) >= 0
58
+ }
59
+ if (raw.startsWith('<=')) {
60
+ const base = parseVersion(raw.slice(2))
61
+ return Boolean(base) && compareParts(current, base) <= 0
62
+ }
63
+ if (raw.startsWith('>')) {
64
+ const base = parseVersion(raw.slice(1))
65
+ return Boolean(base) && compareParts(current, base) > 0
66
+ }
67
+ if (raw.startsWith('<')) {
68
+ const base = parseVersion(raw.slice(1))
69
+ return Boolean(base) && compareParts(current, base) < 0
70
+ }
71
+ if (raw.startsWith('=')) return satisfies(version, raw.slice(1))
72
+
73
+ const xRange = /^(\d+)(?:\.(\d+))?\.[x*]$/.exec(raw)
74
+ if (xRange) {
75
+ const major = Number(xRange[1])
76
+ const minor = xRange[2] === undefined ? null : Number(xRange[2])
77
+ return current[0] === major && (minor === null || current[1] === minor)
78
+ }
79
+
80
+ const exact = parseVersion(raw)
81
+ return Boolean(exact) && compareParts(current, exact) === 0
82
+ }
@@ -0,0 +1,5 @@
1
+ # @capyclaw/foundation 的 bundle patch:在 Cordis 树里登记内核,产出 ctx.os。
2
+ # 应用插件由 loader 在各自的 apply 里挂载,不再单独产生 patch 行。
3
+ - insert:
4
+ - id: capyclaw-foundation
5
+ name: '@capyclaw/foundation'
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Legacy plugin-kit compatibility exports. Includes Node resource helpers and
3
+ * dsh runtime-context conventions; importing this entry is not a portability proof.
4
+ * Preserve existing exports; new applications should prefer the descriptor ABI.
5
+ */
6
+ export * from '@capyclaw/plugin-kit'
@@ -0,0 +1,98 @@
1
+ /**
2
+ * client-panel@1 适配器:页面开机全局变量 + 可选静态面板。
3
+ *
4
+ * - bootGlobals 必须是同步函数;异步准备放在 prepare(start 阶段)里,
5
+ * 结果通过 state 传给 bootGlobals,避免事件发射器无法 await 的竞态。
6
+ * - 静态 root 与 ui-panel 共用 editorHost + serviceHost 共享前缀。
7
+ */
8
+ import { fileURLToPath } from 'node:url'
9
+
10
+ import { AbiError, ERROR_CODES } from '../../abi/errors.mjs'
11
+
12
+ export const kind = 'client-panel@1'
13
+
14
+ export function createClientPanelAdapter({ host, net, log }) {
15
+ return {
16
+ kind,
17
+ compile(impl, { spec, config, context }) {
18
+ const ctx = context?.ctx
19
+ if (typeof ctx?.on !== 'function') {
20
+ throw new AbiError(ERROR_CODES.E_ADAPTER_THREW,
21
+ 'client-panel@1 需要支持 ctx.on 的 Cordis 宿主', { plugin: spec.name })
22
+ }
23
+
24
+ let unmount
25
+ let editor
26
+ let app
27
+ if (impl.root) {
28
+ const serviceHost = host.http()
29
+ const editorHost = host.ui()
30
+ if (!serviceHost?.createApp || !editorHost?.createEditorHost) {
31
+ throw new AbiError(ERROR_CODES.E_CAP_MISSING,
32
+ 'ctx.editorHost / ctx.serviceHost 不可用:无法挂静态面板',
33
+ { plugin: spec.name, capability: 'os.ui' })
34
+ }
35
+ if (!context?.baseUrl) {
36
+ throw new AbiError(ERROR_CODES.E_BASE_URL_MISSING,
37
+ `插件 ${spec.name} 缺少 baseUrl,无法解析 ${impl.root}`, { plugin: spec.name })
38
+ }
39
+ const dir = fileURLToPath(new URL(impl.root, context.baseUrl))
40
+ editor = editorHost.createEditorHost({
41
+ id: spec.name,
42
+ dir,
43
+ basePath: '',
44
+ index: impl.index,
45
+ })
46
+ app = serviceHost.createApp({ id: spec.name, title: spec.name })
47
+ try {
48
+ for (const route of editor.routes()) app.use(route)
49
+ unmount = net.mount(impl.mount, app)
50
+ } catch (error) {
51
+ /* 装配/挂载失败回收已建 app(editor 静态宿主无 close,GC 回收)。 */
52
+ try { app.close?.() } catch { /* 尽力回收 */ }
53
+ throw new AbiError(ERROR_CODES.E_ADAPTER_THREW,
54
+ `挂载客户端面板 ${impl.mount} 失败:${error.message}`,
55
+ { plugin: spec.name, prefix: impl.mount, cause: error })
56
+ }
57
+ }
58
+
59
+ const panelState = { ready: typeof impl.prepare !== 'function', value: undefined }
60
+ const off = ctx.on('webserver/index-inject', (table) => {
61
+ if (!impl.bootGlobals || !panelState.ready || !Array.isArray(table)) return
62
+ let globals
63
+ try {
64
+ globals = impl.bootGlobals({
65
+ spec, config, log, os: context.os, state: panelState.value,
66
+ })
67
+ } catch (error) {
68
+ log?.error?.(`[foundation] ${spec.name} bootGlobals 失败:${error.message}`)
69
+ return
70
+ }
71
+ if (!globals || typeof globals !== 'object') return
72
+ for (const [name, value] of Object.entries(globals)) {
73
+ if (value !== undefined) table.push({ kind: 'global', name, value })
74
+ }
75
+ })
76
+
77
+ return {
78
+ editor,
79
+ async start() {
80
+ if (typeof impl.prepare === 'function') {
81
+ panelState.value = await impl.prepare({
82
+ spec, config, log, os: context.os,
83
+ })
84
+ panelState.ready = true
85
+ }
86
+ if (unmount) await net.ready()
87
+ },
88
+ dispose() {
89
+ const errors = []
90
+ try { if (typeof off === 'function') off() } catch (error) { errors.push(error) }
91
+ try { if (typeof unmount === 'function') unmount() } catch (error) { errors.push(error) }
92
+ try { app?.close?.() } catch (error) { errors.push(error) }
93
+ if (errors.length) throw errors[0]
94
+ },
95
+ }
96
+ },
97
+ }
98
+ }
@@ -0,0 +1,35 @@
1
+ /**
2
+ * host-event@1 适配器:把宿主事件订阅交给插件自己的 Cordis ctx。
3
+ *
4
+ * 应用插件只声明事件名与 handler,不接触 ctx;注销由 loader 统一回收。
5
+ */
6
+ import { AbiError, ERROR_CODES } from '../../abi/errors.mjs'
7
+
8
+ export const kind = 'host-event@1'
9
+
10
+ export function createHostEventAdapter({ log }) {
11
+ return {
12
+ kind,
13
+ compile(impl, { spec, context }) {
14
+ const ctx = context?.ctx
15
+ if (!ctx || typeof ctx.on !== 'function') {
16
+ throw new AbiError(ERROR_CODES.E_ADAPTER_THREW,
17
+ 'host-event@1 需要支持 ctx.on 的 Cordis 宿主', { plugin: spec.name, event: impl.event })
18
+ }
19
+
20
+ let dispose
21
+ try {
22
+ const off = ctx.on(impl.event, impl.handler)
23
+ dispose = typeof off === 'function'
24
+ ? off
25
+ : () => { if (typeof ctx.off === 'function') ctx.off(impl.event, impl.handler) }
26
+ } catch (error) {
27
+ throw new AbiError(ERROR_CODES.E_ADAPTER_THREW,
28
+ `订阅宿主事件 ${impl.event} 失败:${error.message}`, { plugin: spec.name, event: impl.event, cause: error })
29
+ }
30
+
31
+ log?.debug?.(`[foundation] ${spec.name} 订阅宿主事件 ${impl.event}`)
32
+ return { dispose }
33
+ },
34
+ }
35
+ }
@@ -0,0 +1,69 @@
1
+ /**
2
+ * http-router@1 适配器:routes(app) 往子 app 上挂路由,内核把子 app 挂到共享宿主的前缀下。
3
+ *
4
+ * 前缀冲突由 service-host 的 sharedHost.mount 检测(重复前缀直接抛错),
5
+ * 应用侧不接触 server、不选端口。
6
+ *
7
+ * 增量(STANDARD v2 V2-1/V2-4 配套,纯向后兼容):
8
+ * - routes 第二参新增 service(name):跨隔离探测公共服务(getService),
9
+ * 让路由插件拿到 ctx.workStore 这类驱动提供的服务,而不必私开句柄;
10
+ * - routes() 返回函数时登记为 disposer:dispose 先 unmount 再调用,
11
+ * 路由层起的定时器/句柄有官方回收点。
12
+ */
13
+ import { AbiError, ERROR_CODES } from '../../abi/errors.mjs'
14
+ import { getService } from '../ctx-service.mjs'
15
+
16
+ export const kind = 'http-router@1'
17
+
18
+ export function createHttpRouterAdapter({ host, net, log }) {
19
+ return {
20
+ kind,
21
+ compile(impl, { spec, config, context }) {
22
+ const serviceHost = host.http()
23
+ if (!serviceHost?.createApp) {
24
+ throw new AbiError(ERROR_CODES.E_CAP_MISSING,
25
+ 'ctx.serviceHost 不可用:无法创建子 app', { plugin: spec.name, capability: 'os.net' })
26
+ }
27
+
28
+ const app = serviceHost.createApp({ id: spec.name, title: spec.name })
29
+ const service = (name) => getService(context?.ctx, name)
30
+ let cleanup
31
+ try {
32
+ const returned = impl.routes(app, { spec, config, log, os: context?.os, service })
33
+ if (typeof returned === 'function') cleanup = returned
34
+ } catch (error) {
35
+ /* routes 抛错时 app 已创建:此 entry 尚未入 loader entries,编译回滚够不到,
36
+ * 必须就地回收,否则子 app/句柄泄漏。 */
37
+ try { app.close?.() } catch { /* 尽力回收 */ }
38
+ throw new AbiError(ERROR_CODES.E_ADAPTER_THREW,
39
+ `路由注册失败:${error.message}`, { plugin: spec.name, cause: error })
40
+ }
41
+
42
+ let unmount
43
+ try {
44
+ unmount = net.mount(impl.mount, app)
45
+ } catch (error) {
46
+ /* mount 失败同样回收已建的 app 与 routes 返回的 cleanup。 */
47
+ try { if (cleanup) cleanup() } catch { /* 尽力回收 */ }
48
+ try { app.close?.() } catch { /* 尽力回收 */ }
49
+ throw new AbiError(ERROR_CODES.E_ADAPTER_THREW,
50
+ `挂载前缀 ${impl.mount} 失败:${error.message}`, { plugin: spec.name, prefix: impl.mount, cause: error })
51
+ }
52
+
53
+ log?.debug?.(`[foundation] ${spec.name} 路由挂到 ${impl.mount}`)
54
+ return {
55
+ app,
56
+ start: () => net.ready(),
57
+ dispose: () => {
58
+ /* unmount 与 cleanup 都要执行;cleanup 错误不再吞掉(旧实现 log.warn 后
59
+ * 假装成功,loader 会释放 claims 但定时器/句柄实际泄漏)。错误上抛进
60
+ * loader cleanupErrors,保留「失败保留所有权」语义。 */
61
+ const errors = []
62
+ try { if (typeof unmount === 'function') unmount() } catch (error) { errors.push(error) }
63
+ if (cleanup) { try { cleanup() } catch (error) { errors.push(error) } }
64
+ if (errors.length) throw errors[0]
65
+ },
66
+ }
67
+ },
68
+ }
69
+ }
@@ -0,0 +1,55 @@
1
+ /**
2
+ * lifecycle-hook@1 的适配器。
3
+ *
4
+ * 运行时只执行 onStart / onStop;onInstall / onUpgrade 属于安装与升级流程,
5
+ * 由安装器(publisher / dsh profile 安装)在对应时点读取描述符后调用。
6
+ * 这里把它们登记进 hook 注册表,保证「声明了就找得到」。
7
+ */
8
+ export const kind = 'lifecycle-hook@1'
9
+
10
+ export function createHookRegistry() {
11
+ return {
12
+ install: [],
13
+ upgrade: [],
14
+ register(phase, entry) {
15
+ if (!this[phase]) throw new Error(`未知生命周期阶段 ${phase}`)
16
+ this[phase].push(entry)
17
+ return () => {
18
+ const index = this[phase].indexOf(entry)
19
+ if (index >= 0) this[phase].splice(index, 1)
20
+ }
21
+ },
22
+ list() {
23
+ return {
24
+ install: this.install.map((entry) => entry.plugin),
25
+ upgrade: this.upgrade.map((entry) => entry.plugin),
26
+ }
27
+ },
28
+ }
29
+ }
30
+
31
+ export function createLifecycleAdapter({ hooks, log }) {
32
+ return {
33
+ kind,
34
+ compile(impl, { spec, config, context }) {
35
+ const removers = []
36
+ if (typeof impl.onInstall === 'function') {
37
+ removers.push(hooks.register('install', { plugin: spec.name, run: impl.onInstall }))
38
+ }
39
+ if (typeof impl.onUpgrade === 'function') {
40
+ removers.push(hooks.register('upgrade', { plugin: spec.name, run: impl.onUpgrade }))
41
+ }
42
+ let entered = false
43
+ return {
44
+ async start({ signal } = {}) {
45
+ entered = true
46
+ if (typeof impl.onStart === 'function') await impl.onStart({ plugin: spec.name, config, log, os: context?.os, signal })
47
+ },
48
+ dispose() {
49
+ for (const remove of removers) remove()
50
+ if (entered && typeof impl.onStop === 'function') return impl.onStop({ plugin: spec.name, config, log, os: context?.os })
51
+ },
52
+ }
53
+ },
54
+ }
55
+ }