@hit-sudomaker/ccw 0.4.1 → 0.5.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.
@@ -0,0 +1,380 @@
1
+ import { step, sequence } from './work.js';
2
+ import { knownTitle } from './management-catalog.js';
3
+ import { isObject } from './machine.js';
4
+ import { commandReceipt, json, object, success } from './model.js';
5
+ import { applyFrozenJson, assessFrozenJson, jsonField, jsonFingerprint as digest } from './frozen-json.js';
6
+ // 保留字段只定位已有键;偏好默认值由编辑器提交,不在安装初始化时补齐
7
+ const ROOT_FIELDS = {
8
+ $schema: { placement: 'prefix', role: 'preserve' },
9
+ defaultShell: { placement: 'prefix', role: 'preserve' },
10
+ permissions: { placement: 'prefix', role: 'preserve' },
11
+ includeCoAuthoredBy: { placement: 'prefix', role: 'preserve' },
12
+ attribution: { placement: 'prefix', role: 'attribution', value: { commit: '', pr: '', sessionUrl: false } },
13
+ language: { placement: 'prefix', role: 'preference' },
14
+ outputStyle: { placement: 'prefix', role: 'preference' },
15
+ statusLine: { placement: 'prefix', role: 'preserve' },
16
+ enabledPlugins: { placement: 'prefix', role: 'preserve' },
17
+ autoCompactEnabled: { placement: 'prefix', role: 'preserve' },
18
+ autoCompactWindow: { placement: 'prefix', role: 'preserve' },
19
+ autoUpdatesChannel: { placement: 'prefix', role: 'preserve' },
20
+ skipDangerousModePermissionPrompt: { placement: 'prefix', role: 'preserve' },
21
+ apiKeyHelper: { placement: 'suffix', role: 'helper' },
22
+ env: { placement: 'suffix', role: 'environment' },
23
+ model: { placement: 'suffix', role: 'preserve' },
24
+ };
25
+ const ENV_FIELDS = {
26
+ DISABLE_TELEMETRY: { placement: 'prefix', role: 'default', when: 'configure', value: '1' },
27
+ DISABLE_ERROR_REPORTING: { placement: 'prefix', role: 'default', when: 'configure', value: '1' },
28
+ DISABLE_INSTALLATION_CHECKS: { placement: 'prefix', role: 'default', when: 'configure', value: '1' },
29
+ CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: { placement: 'prefix', role: 'default', when: 'configure', value: '80' },
30
+ CLAUDE_CODE_USE_POWERSHELL_TOOL: { placement: 'prefix', role: 'default', when: 'win32', value: '1' },
31
+ CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: { placement: 'prefix', role: 'default', when: 'configure', value: '1' },
32
+ CLAUDE_CODE_ATTRIBUTION_HEADER: { placement: 'prefix', role: 'default', when: 'custom-base', value: '0' },
33
+ MCP_TIMEOUT: { placement: 'prefix', role: 'preserve' },
34
+ ANTHROPIC_BASE_URL: { placement: 'suffix', role: 'base' },
35
+ ANTHROPIC_CUSTOM_HEADERS: { placement: 'suffix', role: 'preserve' },
36
+ ANTHROPIC_API_KEY: { placement: 'suffix', role: 'key' },
37
+ ANTHROPIC_AUTH_TOKEN: { placement: 'suffix', role: 'token' },
38
+ ANTHROPIC_MODEL: { placement: 'suffix', role: 'model', editor: 'model' },
39
+ ANTHROPIC_DEFAULT_MODEL: { placement: 'suffix', role: 'preserve' },
40
+ ANTHROPIC_DEFAULT_FABLE_MODEL: { placement: 'suffix', role: 'model', editor: 'fable' },
41
+ ANTHROPIC_DEFAULT_OPUS_MODEL: { placement: 'suffix', role: 'model', editor: 'opus' },
42
+ ANTHROPIC_DEFAULT_SONNET_MODEL: { placement: 'suffix', role: 'model', editor: 'sonnet' },
43
+ ANTHROPIC_DEFAULT_HAIKU_MODEL: { placement: 'suffix', role: 'model', editor: 'haiku' },
44
+ };
45
+ const rootFields = Object.entries(ROOT_FIELDS);
46
+ const envFields = Object.entries(ENV_FIELDS);
47
+ const connectionKeys = envFields
48
+ .filter(([, field]) => ['base', 'key', 'token', 'model'].includes(field.role))
49
+ .map(([key]) => key);
50
+ const helperKeys = rootFields.filter(([, field]) => field.role === 'helper').map(([key]) => key);
51
+ /**
52
+ * 准备模型连接、偏好和默认设置变更
53
+ *
54
+ * @param selection - configure 可留空凭据以沿用所选认证类型;detach 只移除连接字段和凭据助手
55
+ * @param claude - 官方登录所需的绑定命令
56
+ * @returns 预览不含凭据的延迟流程,执行时复核字段并保留无关设置
57
+ * @throws Error - 读取、动作、连接字段、登录依赖无效,无连接可解除或继承环境变量冲突时拒绝
58
+ * @remarks 登录失败或取消不回滚已保存设置
59
+ */
60
+ export async function prepareSettings(ctx, selection, claude) {
61
+ if (!['configure', 'detach'].includes(selection.action))
62
+ throw new Error('action-unavailable');
63
+ const settings = await json(ctx.machine, ctx.settingsFile);
64
+ const env = object(settings.env);
65
+ if (selection.action === 'detach' &&
66
+ !connectionKeys.some(key => env[key] !== undefined) &&
67
+ !helperKeys.some(key => settings[key] !== undefined))
68
+ throw new Error('no-connection');
69
+ const fields = selection.action === 'detach' ? {} : (selection.fields ?? {});
70
+ const changes = {};
71
+ const preferences = {};
72
+ const shouldLogin = fields.mode === 'official' && fields.login === 'yes';
73
+ if (shouldLogin && !claude)
74
+ throw new Error('claude-not-installed');
75
+ const shouldControlHelper = selection.action === 'detach' || fields.mode === 'official' || fields.mode === 'api';
76
+ if (selection.action === 'detach' || fields.mode === 'official') {
77
+ for (const key of connectionKeys)
78
+ changes[key] = undefined;
79
+ }
80
+ if (fields.mode === 'api') {
81
+ const selectedCredential = fields.auth === 'token' ? 'token' : 'key';
82
+ let base = fields.baseUrl?.trim();
83
+ let credential = fields.secret?.trim();
84
+ for (const [key, field] of envFields) {
85
+ const value = env[key];
86
+ if (typeof value !== 'string')
87
+ continue;
88
+ if (field.role === 'base')
89
+ base ??= value.trim();
90
+ if (field.role === selectedCredential)
91
+ credential ||= value;
92
+ }
93
+ const problem = apiConfigurationProblem(base, Boolean(credential?.trim()));
94
+ if (problem)
95
+ throw new Error(problem);
96
+ for (const [key, field] of envFields) {
97
+ if (field.role === 'base')
98
+ changes[key] = base;
99
+ if (field.role === 'key' || field.role === 'token')
100
+ changes[key] = field.role === selectedCredential ? credential : undefined;
101
+ }
102
+ }
103
+ if (shouldControlHelper)
104
+ for (const key of helperKeys)
105
+ preferences[key] = undefined;
106
+ for (const [key, field] of envFields)
107
+ if (field.role === 'model' && fields[field.editor] !== undefined)
108
+ changes[key] = fields[field.editor]?.trim() || undefined;
109
+ for (const [key, field] of rootFields)
110
+ if (field.role === 'preference' && fields[key] !== undefined)
111
+ preferences[key] = fields[key] || undefined;
112
+ if ((ctx.inheritedKeys ?? []).some(key => Object.hasOwn(changes, key)))
113
+ throw new Error('inherited-configuration-conflict');
114
+ const patches = [];
115
+ const add = (parts, before, after, isSecret = false, isDefault = false) => {
116
+ patches.push({
117
+ path: parts,
118
+ before: digest(before),
119
+ after: digest(after),
120
+ mode: isDefault ? 'default' : after === undefined ? 'absent' : isSecret ? 'credential' : 'value',
121
+ value: after === undefined || isSecret ? null : jsonValue(after),
122
+ });
123
+ };
124
+ for (const [key, value] of Object.entries(changes))
125
+ add(['env', key], env[key], value, ['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN'].includes(key) && value !== undefined);
126
+ for (const [key, value] of Object.entries(preferences))
127
+ add([key], settings[key], value);
128
+ if (selection.action === 'configure') {
129
+ const draft = structuredClone(settings);
130
+ const draftEnv = { ...env };
131
+ for (const [key, value] of Object.entries(changes)) {
132
+ if (value === undefined)
133
+ delete draftEnv[key];
134
+ else
135
+ draftEnv[key] = value;
136
+ }
137
+ draft.env = draftEnv;
138
+ const defaults = initializeDefaults(draft, ctx);
139
+ for (const [key, value] of Object.entries(defaults.env))
140
+ if (!Object.hasOwn(changes, key))
141
+ add(['env', key], env[key], value, false, true);
142
+ for (const [key, value] of Object.entries(defaults.root))
143
+ if (key === 'permissions')
144
+ add(['permissions', 'defaultMode'], object(settings.permissions).defaultMode, object(value).defaultMode, false, true);
145
+ else if (!Object.hasOwn(preferences, key))
146
+ add([key], settings[key], value, false, key !== 'autoUpdatesChannel');
147
+ }
148
+ const write = writeSettings(ctx, patches, fields.secret?.trim() || undefined, [
149
+ { code: selection.action === 'detach' ? 'settings-disconnect' : 'settings-edit', detail: ctx.settingsFile },
150
+ ]);
151
+ return shouldLogin && claude
152
+ ? sequence([
153
+ step([], async () => {
154
+ await claude.verify();
155
+ return { state: 'complete' };
156
+ }),
157
+ write,
158
+ loginWork(claude),
159
+ ])
160
+ : write;
161
+ }
162
+ /** 供 Claude 管理域检查模型设置;只返回公开字段和凭据存在标记 */
163
+ export async function inspectSettings(ctx) {
164
+ const settings = await json(ctx.machine, ctx.settingsFile);
165
+ const env = object(settings.env);
166
+ const hasApiConfiguration = envFields.some(([key, field]) => ['base', 'key', 'token'].includes(field.role) && typeof env[key] === 'string');
167
+ const values = {};
168
+ if (hasApiConfiguration || Object.keys(settings).length > 0)
169
+ values.mode = hasApiConfiguration ? 'api' : 'official';
170
+ // 仅提示本文件的编辑选择,不代表已解析当前会话的认证来源
171
+ values.auth = envFields.some(([key, field]) => field.role === 'token' && typeof env[key] === 'string' && env[key].trim() !== '')
172
+ ? 'token'
173
+ : 'key';
174
+ for (const [key, field] of envFields) {
175
+ const value = env[key];
176
+ if (typeof value === 'string') {
177
+ if (field.role === 'base')
178
+ values.baseUrl = value;
179
+ if (field.role === 'model')
180
+ values[field.editor] = value;
181
+ }
182
+ }
183
+ for (const [key, field] of rootFields)
184
+ if (field.role === 'preference' && typeof settings[key] === 'string')
185
+ values[key] = settings[key];
186
+ if (values.baseUrl !== undefined) {
187
+ try {
188
+ const url = new URL(values.baseUrl);
189
+ if (url.username || url.password || url.search || url.hash)
190
+ delete values.baseUrl;
191
+ }
192
+ catch {
193
+ delete values.baseUrl;
194
+ }
195
+ }
196
+ return {
197
+ id: 'settings',
198
+ title: knownTitle('settings'),
199
+ kind: 'settings',
200
+ canInstall: true,
201
+ location: ctx.settingsFile,
202
+ values,
203
+ hasCredential: envFields.some(([key, field]) => field.role === values.auth && typeof env[key] === 'string' && env[key].trim() !== ''),
204
+ facts: [{ code: hasApiConfiguration ? 'api-configured' : 'official-connection' }],
205
+ canUninstall: connectionKeys.some(key => env[key] !== undefined) || helperKeys.some(key => settings[key] !== undefined),
206
+ };
207
+ }
208
+ function writeSettings(ctx, patches, secret, changes) {
209
+ let frozenDefaults;
210
+ return step(changes, async (fact) => {
211
+ const current = await json(ctx.machine, ctx.settingsFile);
212
+ const defaults = Object.fromEntries(patches
213
+ .filter(patch => patch.mode === 'default')
214
+ .map(patch => {
215
+ const value = jsonField(current, patch.path);
216
+ return [
217
+ patch.path.join('/'),
218
+ value === undefined && !(patch.path[0] === 'attribution' && current.includeCoAuthoredBy === true)
219
+ ? patch.after
220
+ : digest(value),
221
+ ];
222
+ }));
223
+ const expectedDefaults = frozenDefaults ?? defaults;
224
+ const assessment = assessFrozenJson(current, patches.map(patch => ({
225
+ path: patch.path,
226
+ before: patch.mode === 'default' ||
227
+ (patch.path[0] === 'autoUpdatesChannel' && digest(current.autoUpdatesChannel) === patch.after)
228
+ ? digest(jsonField(current, patch.path))
229
+ : patch.before,
230
+ after: patch.mode === 'default' ? String(expectedDefaults[patch.path.join('/')]) : patch.after,
231
+ })), fact);
232
+ if (assessment.state === 'complete')
233
+ return {
234
+ ...assessment,
235
+ effects: [{ state: 'done', code: 'settings-saved' }],
236
+ };
237
+ if (assessment.state === 'ready')
238
+ frozenDefaults = defaults;
239
+ return assessment;
240
+ }, async () => {
241
+ await ctx.effects.editJson(ctx.settingsFile, current => {
242
+ const fields = patches.map(patch => {
243
+ const currentValue = jsonField(current, patch.path);
244
+ if (patch.mode === 'default') {
245
+ const expected = frozenDefaults?.[patch.path.join('/')];
246
+ const eligible = currentValue === undefined && !(patch.path[0] === 'attribution' && current.includeCoAuthoredBy === true);
247
+ if (eligible && expected !== patch.after)
248
+ throw new Error('target-changed');
249
+ return {
250
+ path: patch.path,
251
+ before: eligible ? patch.before : String(expected),
252
+ after: String(expected),
253
+ value: eligible ? patch.value : currentValue,
254
+ };
255
+ }
256
+ const value = patch.mode === 'absent' ? undefined : patch.mode === 'credential' ? (secret ?? currentValue) : patch.value;
257
+ if (patch.mode === 'credential' && digest(value) !== patch.after)
258
+ throw new Error('credential-required');
259
+ return {
260
+ path: patch.path,
261
+ before: patch.path[0] === 'autoUpdatesChannel' && digest(currentValue) === patch.after
262
+ ? patch.after
263
+ : patch.before,
264
+ after: patch.after,
265
+ value,
266
+ };
267
+ });
268
+ applyFrozenJson(current, fields);
269
+ if (current.env !== undefined)
270
+ orderFields(object(current.env), envFields);
271
+ orderFields(current, rootFields);
272
+ });
273
+ return { receipt: { kind: 'returned', failure: null }, effects: [{ state: 'done', code: 'settings-saved' }] };
274
+ });
275
+ }
276
+ function loginWork(claude) {
277
+ const login = step([{ code: 'login-browser' }], async (fact) => {
278
+ await claude.verify();
279
+ if (!fact.dispatched || (fact.receipt?.kind === 'returned' && fact.receipt.failure))
280
+ return { state: 'ready' };
281
+ const status = JSON.parse(success(await claude.execute(['auth', 'status', '--json'])));
282
+ return isObject(status) && status.loggedIn === true
283
+ ? { state: 'complete', effects: [{ state: 'done', code: 'logged-in' }] }
284
+ : { state: 'blocked', problem: 'login-unconfirmed' };
285
+ }, async () => {
286
+ const result = await claude.execute(['auth', 'login'], true);
287
+ return { receipt: commandReceipt(result, 'login-failed') };
288
+ });
289
+ return login;
290
+ }
291
+ /** 补齐安装默认值;保留显式值和继承变量声明 */
292
+ function initializeDefaults(settings, ctx) {
293
+ const env = object(settings.env);
294
+ const hasCustomBase = envFields.some(([key, field]) => {
295
+ const base = env[key];
296
+ return (field.role === 'base' &&
297
+ typeof base === 'string' &&
298
+ apiConfigurationProblem(base, true) === null &&
299
+ new URL(base).hostname !== 'api.anthropic.com');
300
+ });
301
+ const added = {};
302
+ for (const [key, field] of envFields)
303
+ if (field.role === 'default' &&
304
+ env[key] === undefined &&
305
+ !ctx.inheritedKeys?.includes(key) &&
306
+ (field.when !== 'win32' || ctx.platform === 'win32') &&
307
+ (field.when !== 'custom-base' || hasCustomBase)) {
308
+ env[key] = field.value;
309
+ added[key] = field.value;
310
+ }
311
+ settings.env = env;
312
+ const root = {};
313
+ for (const [key, field] of rootFields)
314
+ if (field.role === 'attribution' && settings[key] === undefined && settings.includeCoAuthoredBy !== true) {
315
+ settings[key] = { ...field.value };
316
+ root[key] = settings[key];
317
+ }
318
+ // 始终使用 stable 通道;首次危险模式确认使用官方设置
319
+ if (settings.autoUpdatesChannel !== 'stable') {
320
+ settings.autoUpdatesChannel = 'stable';
321
+ root.autoUpdatesChannel = 'stable';
322
+ }
323
+ if (settings.skipDangerousModePermissionPrompt === undefined) {
324
+ settings.skipDangerousModePermissionPrompt = true;
325
+ root.skipDangerousModePermissionPrompt = true;
326
+ }
327
+ // 权限默认模式只在缺失时补齐;已有选择(含更保守模式)不覆盖,allow/ask/deny 原样保留
328
+ const permissions = object(settings.permissions);
329
+ if (permissions.defaultMode === undefined) {
330
+ permissions.defaultMode = 'bypassPermissions';
331
+ settings.permissions = permissions;
332
+ root.permissions = permissions;
333
+ }
334
+ return { env: added, root };
335
+ }
336
+ /** 只重排 root/env 自身属性;未知键保持相对顺序,嵌套值保持原样 */
337
+ function orderFields(value, fields) {
338
+ const known = new Set(fields.map(([key]) => key));
339
+ const ordered = Object.fromEntries([
340
+ ...fields.filter(([key, field]) => field.placement === 'prefix' && Object.hasOwn(value, key)),
341
+ ...Object.entries(value).filter(([key]) => !known.has(key)),
342
+ ...fields.filter(([key, field]) => field.placement === 'suffix' && Object.hasOwn(value, key)),
343
+ ].map(([key]) => [key, value[key]]));
344
+ for (const key of Object.keys(value))
345
+ delete value[key];
346
+ // JSON 可包含 __proto__;以自身属性重建,不触发原型 setter
347
+ Object.defineProperties(value, Object.getOwnPropertyDescriptors(ordered));
348
+ }
349
+ function jsonValue(value) {
350
+ if (value === null ||
351
+ typeof value === 'string' ||
352
+ typeof value === 'boolean' ||
353
+ (typeof value === 'number' && Number.isFinite(value)))
354
+ return value;
355
+ if (Array.isArray(value))
356
+ return value.map(jsonValue);
357
+ if (isObject(value))
358
+ return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, jsonValue(child)]));
359
+ throw new Error('invalid-settings');
360
+ }
361
+ /**
362
+ * 校验 API 地址和凭据存在性,不连接远端服务
363
+ *
364
+ * @param baseUrl - 可带首尾空白的 HTTP 或 HTTPS 地址
365
+ * @param hasCredential - 调用方已确认是否存在有效凭据
366
+ * @returns 缺少字段或地址格式的问题码;校验通过时为 null
367
+ */
368
+ export function apiConfigurationProblem(baseUrl, hasCredential) {
369
+ if (!baseUrl?.trim())
370
+ return hasCredential ? 'base-url-required' : 'api-fields-required';
371
+ try {
372
+ const url = new URL(baseUrl.trim());
373
+ if (!['http:', 'https:'].includes(url.protocol) || url.password || url.username || url.search || url.hash)
374
+ return 'invalid-base-url';
375
+ }
376
+ catch {
377
+ return 'invalid-base-url';
378
+ }
379
+ return hasCredential ? null : 'credential-required';
380
+ }
@@ -1,112 +1,198 @@
1
+ import { step, sequence } from './work.js';
1
2
  import path from 'node:path';
2
3
  import { randomUUID } from 'node:crypto';
3
- import { treeFilesStamp } from './machine.js';
4
+ import { treeFilesStamp, isObject } from './machine.js';
4
5
  import { SKILL_ENTRY } from './management-catalog.js';
5
- import { cancelled, json, unchanged } from './model.js';
6
- import { disabledDirectory, replacedDirectory, sourcesFile } from './storage.js';
6
+ import { json, unchanged } from './model.js';
7
+ import { jsonFingerprint } from './frozen-json.js';
8
+ const REVISION_DISPLAY_LENGTH = 12;
9
+ /** 返回技能来源记录路径,不读取或创建文件 */
10
+ export const sourcesFile = (ctx) => path.join(ctx.storage, 'sources.json');
11
+ const replacedDirectory = (ctx) => path.join(ctx.storage, 'replaced');
12
+ const disabledDirectory = (ctx) => path.join(ctx.storage, 'disabled');
13
+ /** 仅在仓库匹配且现存目录摘要等于记录摘要时确认受管归属 */
14
+ export function ownsSkill(record, repository, stamp) {
15
+ return repository !== undefined && stamp !== null && skillSourceMatches(record, repository) && record.stamp === stamp;
16
+ }
17
+ /**
18
+ * 校验已有来源记录与目标仓库一致,允许尚无记录
19
+ *
20
+ * @throws Error - 已有记录无法证明属于该仓库时抛出 integration-source-conflict
21
+ */
22
+ export function checkSkillSource(record, repository) {
23
+ if (record !== undefined && !skillSourceMatches(record, repository))
24
+ throw new Error('integration-source-conflict');
25
+ }
26
+ /**
27
+ * 复核并保留已有技能目录
28
+ *
29
+ * @param before - 执行及最终核验时须匹配的目录摘要
30
+ * @remarks 不写文件或查询更新,目录变化记为执行问题
31
+ */
7
32
  export function currentSkill(ctx, name, directory, before) {
8
- const verify = async () => unchanged(await ctx.machine.treeStamp(directory), before);
33
+ const installed = step([{ code: 'skill-current', detail: name }], async () => {
34
+ unchanged(await ctx.machine.treeStamp(directory), before);
35
+ return {
36
+ state: 'complete',
37
+ effects: [{ state: 'kept', code: 'skill-current', detail: name }],
38
+ };
39
+ });
40
+ return { ...installed, skillDirectories: [directory] };
41
+ }
42
+ /**
43
+ * 准备替换技能树、保留旧目录并登记来源
44
+ *
45
+ * @param target - 已获替换许可的目录、原摘要和来源记录
46
+ * @param source - 含非空根级 SKILL.md 的文件树,派发前须匹配摘要
47
+ * @returns 延迟流程及覆盖目录,准备时只生成保留路径
48
+ * @remarks 执行时复核目标、来源记录和保留副本;登记失败仅报告元数据问题
49
+ * 取消不回滚目录或副本
50
+ */
51
+ export function prepareSkillFiles(ctx, target, source) {
52
+ const { name, directory, stamp: before } = target;
53
+ const destination = before === null ? null : path.join(replacedDirectory(ctx), randomUUID() + '-' + name);
54
+ const expectedStamp = source.stamp;
55
+ const installed = step([
56
+ { code: 'skill-install', detail: name + ' · ' + source.revision.slice(0, REVISION_DISPLAY_LENGTH) },
57
+ ...(destination ? [{ code: 'preserved-at', detail: destination }] : []),
58
+ ], async (fact) => {
59
+ const stamp = await ctx.machine.treeStamp(directory);
60
+ if (!fact.dispatched)
61
+ await unchangedSource(ctx, directory, target.sourceRecord);
62
+ if (stamp === expectedStamp &&
63
+ (before !== expectedStamp || (fact.receipt?.kind === 'returned' && !fact.receipt.failure))) {
64
+ if (destination !== null && (await ctx.machine.treeStamp(destination)) !== before)
65
+ return { state: 'blocked', problem: 'target-changed' };
66
+ return {
67
+ state: 'complete',
68
+ effects: [{ state: 'done', code: 'skill-installed', detail: name }],
69
+ };
70
+ }
71
+ if (fact.confirmed || stamp !== before)
72
+ return { state: 'blocked', problem: 'target-changed' };
73
+ return { state: 'ready' };
74
+ }, async () => {
75
+ const files = source.files;
76
+ unchanged(skillFilesStamp(files), expectedStamp);
77
+ await unchangedSource(ctx, directory, target.sourceRecord);
78
+ await ctx.effects.replaceTree(directory, files, before, destination === null ? undefined : destination);
79
+ return { receipt: { kind: 'returned', failure: null } };
80
+ });
81
+ const recorded = recordSource(ctx, target, source);
82
+ return { ...sequence([installed, recorded]), skillDirectories: [directory] };
83
+ }
84
+ /**
85
+ * 为内容匹配的目录补记来源,不替换文件
86
+ *
87
+ * @remarks 执行时复核目录;记录漂移或读写失败仅报告 source-metadata-unavailable
88
+ */
89
+ export function repairSkillSource(ctx, target, source) {
90
+ const recorded = recordSource(ctx, target, source);
91
+ return { ...recorded, skillDirectories: [target.directory] };
92
+ }
93
+ /**
94
+ * 移出技能入口并删除匹配的来源记录
95
+ *
96
+ * @param before - 已确认受管归属的目录摘要
97
+ * @param sourceRecord - 执行前须匹配的来源记录
98
+ * @returns 原内容移至停用目录的延迟流程,不动链接目标或共享源
99
+ * @remarks 核验入口及保留位置;元数据问题仅提示,取消不回滚
100
+ */
101
+ export function disableSkillEntry(ctx, directory, before, sourceRecord) {
102
+ const destination = path.join(disabledDirectory(ctx), randomUUID() + '-' + path.basename(directory));
103
+ const disabled = step([
104
+ { code: 'entry-disable', detail: directory },
105
+ { code: 'preserved-at', detail: destination },
106
+ { code: 'keep-link-target' },
107
+ ], async (fact) => {
108
+ const stamp = await ctx.machine.treeStamp(directory);
109
+ const preserved = await ctx.machine.treeStamp(destination);
110
+ if (!fact.dispatched)
111
+ await unchangedSource(ctx, directory, sourceRecord);
112
+ if (stamp === null && preserved === before)
113
+ return {
114
+ state: 'complete',
115
+ effects: [{ state: 'done', code: 'entry-disabled', detail: destination }],
116
+ };
117
+ if (fact.confirmed || stamp !== before || preserved !== null)
118
+ return { state: 'blocked', problem: 'target-changed' };
119
+ return { state: 'ready' };
120
+ }, async () => {
121
+ await unchangedSource(ctx, directory, sourceRecord);
122
+ await ctx.effects.removeTree(directory, before, destination);
123
+ return { receipt: { kind: 'returned', failure: null } };
124
+ });
125
+ const removed = recordSource(ctx, { name: path.basename(directory), directory, stamp: before, sourceRecord });
9
126
  return {
10
- changes: [{ code: 'skill-current', detail: name }],
11
- async run(report) {
12
- await verify();
13
- report({ state: 'kept', code: 'skill-current', detail: name });
14
- },
15
- verify,
127
+ ...sequence([disabled, removed]),
128
+ skillDirectories: [directory],
16
129
  };
17
130
  }
18
- /** 校验技能入口并冻结载荷摘要 */
131
+ /**
132
+ * 校验技能入口存在并计算完整载荷的树摘要
133
+ *
134
+ * @throws Error - 缺少非空根级 SKILL.md 时抛出 skill-payload-missing,路径无效时沿用树摘要校验错误
135
+ */
19
136
  export function skillFilesStamp(files) {
20
137
  if (!files.some(file => file.path === SKILL_ENTRY && file.data.length > 0))
21
138
  throw new Error('skill-payload-missing');
22
139
  return treeFilesStamp(files);
23
140
  }
24
- export function repairSkillSource(ctx, target, source) {
25
- return {
26
- changes: [{ code: 'skill-source-repair', detail: target.name }],
27
- async run(report) {
28
- unchanged(await ctx.machine.treeStamp(target.directory), source.stamp);
29
- await saveSkillSource(ctx, report, target, source);
30
- },
141
+ // 内容已独立核验;省略 source 时删除记录,元数据问题不撤销已部署或停用的内容
142
+ function recordSource(ctx, target, source) {
143
+ let metadataUnavailable = false;
144
+ const recordTarget = {
145
+ file: sourcesFile(ctx),
146
+ directory: target.directory,
147
+ before: jsonFingerprint(target.sourceRecord),
148
+ source: source ? { repository: source.repository, revision: source.revision, stamp: source.stamp } : undefined,
31
149
  };
32
- }
33
- async function saveSkillSource(ctx, report, target, source) {
34
- const file = sourcesFile(ctx);
35
- try {
36
- await ctx.machine.editJson(file, values => {
37
- unchanged(values[target.directory], target.sourceRecord);
38
- values[target.directory] = { repository: source.repository, revision: source.revision, stamp: source.stamp };
39
- });
40
- report({ state: 'kept', code: 'skill-source-recorded' });
41
- }
42
- catch {
43
- report({ state: 'kept', code: 'source-metadata-unavailable' });
44
- }
45
- }
46
- export function prepareSkillFiles(ctx, target, source) {
47
- const { name, directory, stamp: before } = target;
48
- const destination = before === null ? undefined : path.join(replacedDirectory(ctx), `${randomUUID()}-${name}`);
49
- let isDeployed = false;
50
- let isComplete = false;
51
- const verify = async () => unchanged(await ctx.machine.treeStamp(directory), source.stamp);
52
- const operation = {
53
- get changes() {
54
- return isDeployed
55
- ? [{ code: 'skill-confirm', detail: name }]
56
- : [
57
- { code: 'skill-install', detail: `${name} · ${source.revision.slice(0, 12)}` },
58
- ...(destination ? [{ code: 'preserved-at', detail: destination }] : []),
59
- ];
60
- },
61
- async run(report, signal) {
62
- cancelled(signal);
63
- if (!isDeployed) {
64
- await ctx.machine.replaceTree(directory, source.files, before, destination);
65
- isDeployed = true;
66
- report({ state: 'done', code: 'skill-installed', detail: name });
67
- }
68
- await verify();
69
- await saveSkillSource(ctx, report, target, source);
70
- isComplete = true;
71
- report({ state: 'kept', code: 'skill-confirm', detail: name });
72
- },
73
- remaining: () => (isComplete ? undefined : operation),
74
- verify,
150
+ const unavailableEffects = [{ state: 'kept', code: 'source-metadata-unavailable' }];
151
+ const unavailable = () => {
152
+ metadataUnavailable = true;
153
+ return { state: 'complete', effects: unavailableEffects };
75
154
  };
76
- return operation;
155
+ return step(source ? [{ code: 'skill-source-repair', detail: target.name }] : [], async () => {
156
+ if (recordTarget.source)
157
+ unchanged(await ctx.machine.treeStamp(recordTarget.directory), recordTarget.source.stamp);
158
+ if (metadataUnavailable)
159
+ return unavailable();
160
+ let current;
161
+ try {
162
+ current = (await json(ctx.machine, recordTarget.file))[recordTarget.directory];
163
+ }
164
+ catch {
165
+ return unavailable();
166
+ }
167
+ if (jsonFingerprint(current) === jsonFingerprint(recordTarget.source))
168
+ return source
169
+ ? { state: 'complete', effects: [{ state: 'kept', code: 'skill-source-recorded' }] }
170
+ : { state: 'complete' };
171
+ if (jsonFingerprint(current) !== recordTarget.before)
172
+ return unavailable();
173
+ return { state: 'ready' };
174
+ }, async () => {
175
+ try {
176
+ await ctx.effects.editJson(recordTarget.file, values => {
177
+ unchanged(jsonFingerprint(values[recordTarget.directory]), recordTarget.before);
178
+ if (source)
179
+ values[recordTarget.directory] = recordTarget.source;
180
+ else
181
+ delete values[recordTarget.directory];
182
+ });
183
+ }
184
+ catch {
185
+ metadataUnavailable = true;
186
+ }
187
+ return {
188
+ receipt: { kind: 'returned', failure: null },
189
+ ...(metadataUnavailable && source ? { effects: unavailableEffects } : {}),
190
+ };
191
+ });
77
192
  }
78
- export function disableSkillEntry(ctx, directory, before) {
79
- const destination = path.join(disabledDirectory(ctx), `${randomUUID()}-${path.basename(directory)}`);
80
- const records = sourcesFile(ctx);
81
- return {
82
- writes: [directory, records],
83
- changes: [
84
- { code: 'entry-disable', detail: directory },
85
- { code: 'preserved-at', detail: destination },
86
- { code: 'keep-link-target' },
87
- ],
88
- async run(report) {
89
- await ctx.machine.removeTree(directory, before, destination);
90
- report({ state: 'done', code: 'entry-disabled', detail: destination });
91
- // 解除后清除该路径的过期来源记录(防误归属旧套件);失败只降级提示
92
- let metadata;
93
- try {
94
- metadata = await json(ctx.machine, records);
95
- }
96
- catch {
97
- // 记录不可读时降级提示,不影响解除结果
98
- report({ state: 'kept', code: 'source-metadata-unavailable' });
99
- metadata = null;
100
- }
101
- if (metadata !== null && Object.hasOwn(metadata, directory))
102
- try {
103
- await ctx.machine.editJson(records, values => {
104
- delete values[directory];
105
- });
106
- }
107
- catch {
108
- report({ state: 'kept', code: 'source-metadata-unavailable' });
109
- }
110
- },
111
- };
193
+ async function unchangedSource(ctx, directory, record) {
194
+ unchanged(jsonFingerprint((await json(ctx.machine, sourcesFile(ctx)))[directory]), jsonFingerprint(record));
195
+ }
196
+ function skillSourceMatches(record, repository) {
197
+ return isObject(record) && record.repository === repository;
112
198
  }