@itphx/synth-shared 0.7.3 → 0.8.3

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 (113) hide show
  1. package/dist/config/defaults.d.ts +0 -1
  2. package/dist/config/defaults.js +44 -1
  3. package/dist/config/index.d.ts +0 -1
  4. package/dist/config/index.js +0 -1
  5. package/dist/config/loader.d.ts +2 -1
  6. package/dist/config/loader.js +10 -6
  7. package/dist/config/merge.d.ts +0 -1
  8. package/dist/config/merge.js +0 -1
  9. package/dist/config/resolve.d.ts +35 -7
  10. package/dist/config/resolve.js +98 -19
  11. package/dist/config/types.d.ts +711 -79
  12. package/dist/config/types.js +138 -2
  13. package/dist/i18n/index.d.ts +1 -2
  14. package/dist/i18n/index.js +116 -1
  15. package/dist/index.d.ts +3 -3
  16. package/dist/index.js +3 -3
  17. package/dist/interfaces/index.d.ts +0 -1
  18. package/dist/interfaces/index.js +0 -1
  19. package/dist/model-metadata.d.ts +0 -1
  20. package/dist/model-metadata.js +0 -1
  21. package/dist/protocols/index.d.ts +0 -1
  22. package/dist/protocols/index.js +0 -1
  23. package/dist/schemas/index.d.ts +558 -25
  24. package/dist/schemas/index.js +244 -8
  25. package/dist/skills/frontmatter.d.ts +20 -0
  26. package/dist/skills/frontmatter.js +69 -0
  27. package/dist/types/commands.d.ts +127 -0
  28. package/dist/types/commands.js +10 -0
  29. package/dist/types/index.d.ts +137 -13
  30. package/dist/types/index.js +68 -6
  31. package/dist/types/permission.d.ts +5 -5
  32. package/dist/types/permission.js +0 -1
  33. package/dist/types/skills.d.ts +135 -0
  34. package/dist/types/skills.js +17 -0
  35. package/dist/types/tools.d.ts +0 -1
  36. package/dist/types/tools.js +0 -1
  37. package/dist/utils/glob.d.ts +0 -1
  38. package/dist/utils/glob.js +0 -1
  39. package/dist/utils/index.d.ts +1 -1
  40. package/dist/utils/index.js +2 -1
  41. package/dist/utils/workspace.d.ts +13 -0
  42. package/dist/utils/workspace.js +34 -0
  43. package/dist/version.d.ts +1 -2
  44. package/dist/version.js +1 -2
  45. package/package.json +2 -2
  46. package/dist/config/defaults.d.ts.map +0 -1
  47. package/dist/config/defaults.js.map +0 -1
  48. package/dist/config/defaults.test.d.ts +0 -2
  49. package/dist/config/defaults.test.d.ts.map +0 -1
  50. package/dist/config/defaults.test.js +0 -66
  51. package/dist/config/defaults.test.js.map +0 -1
  52. package/dist/config/index.d.ts.map +0 -1
  53. package/dist/config/index.js.map +0 -1
  54. package/dist/config/loader.d.ts.map +0 -1
  55. package/dist/config/loader.js.map +0 -1
  56. package/dist/config/loader.test.d.ts +0 -2
  57. package/dist/config/loader.test.d.ts.map +0 -1
  58. package/dist/config/loader.test.js +0 -43
  59. package/dist/config/loader.test.js.map +0 -1
  60. package/dist/config/merge.d.ts.map +0 -1
  61. package/dist/config/merge.js.map +0 -1
  62. package/dist/config/merge.test.d.ts +0 -2
  63. package/dist/config/merge.test.d.ts.map +0 -1
  64. package/dist/config/merge.test.js +0 -49
  65. package/dist/config/merge.test.js.map +0 -1
  66. package/dist/config/resolve.d.ts.map +0 -1
  67. package/dist/config/resolve.js.map +0 -1
  68. package/dist/config/resolve.test.d.ts +0 -2
  69. package/dist/config/resolve.test.d.ts.map +0 -1
  70. package/dist/config/resolve.test.js +0 -81
  71. package/dist/config/resolve.test.js.map +0 -1
  72. package/dist/config/types.d.ts.map +0 -1
  73. package/dist/config/types.js.map +0 -1
  74. package/dist/config/types.test.d.ts +0 -2
  75. package/dist/config/types.test.d.ts.map +0 -1
  76. package/dist/config/types.test.js +0 -63
  77. package/dist/config/types.test.js.map +0 -1
  78. package/dist/i18n/index.d.ts.map +0 -1
  79. package/dist/i18n/index.js.map +0 -1
  80. package/dist/i18n/index.test.d.ts +0 -2
  81. package/dist/i18n/index.test.d.ts.map +0 -1
  82. package/dist/i18n/index.test.js +0 -41
  83. package/dist/i18n/index.test.js.map +0 -1
  84. package/dist/index.d.ts.map +0 -1
  85. package/dist/index.js.map +0 -1
  86. package/dist/interfaces/index.d.ts.map +0 -1
  87. package/dist/interfaces/index.js.map +0 -1
  88. package/dist/model-metadata.d.ts.map +0 -1
  89. package/dist/model-metadata.js.map +0 -1
  90. package/dist/model-metadata.test.d.ts +0 -2
  91. package/dist/model-metadata.test.d.ts.map +0 -1
  92. package/dist/model-metadata.test.js +0 -53
  93. package/dist/model-metadata.test.js.map +0 -1
  94. package/dist/protocols/index.d.ts.map +0 -1
  95. package/dist/protocols/index.js.map +0 -1
  96. package/dist/schemas/index.d.ts.map +0 -1
  97. package/dist/schemas/index.js.map +0 -1
  98. package/dist/types/index.d.ts.map +0 -1
  99. package/dist/types/index.js.map +0 -1
  100. package/dist/types/permission.d.ts.map +0 -1
  101. package/dist/types/permission.js.map +0 -1
  102. package/dist/types/tools.d.ts.map +0 -1
  103. package/dist/types/tools.js.map +0 -1
  104. package/dist/utils/glob.d.ts.map +0 -1
  105. package/dist/utils/glob.js.map +0 -1
  106. package/dist/utils/index.d.ts.map +0 -1
  107. package/dist/utils/index.js.map +0 -1
  108. package/dist/utils/index.test.d.ts +0 -2
  109. package/dist/utils/index.test.d.ts.map +0 -1
  110. package/dist/utils/index.test.js +0 -150
  111. package/dist/utils/index.test.js.map +0 -1
  112. package/dist/version.d.ts.map +0 -1
  113. package/dist/version.js.map +0 -1
@@ -1,10 +1,58 @@
1
1
  import { z } from 'zod';
2
- import { MessageRole, GlobalRole, ProjectRole, StatusMessageType } from '../types/index.js';
2
+ import { MessageRole, GlobalRole, ProjectRole, StatusMessageType, PROJECT_ICON_KEYS, PROJECT_COLOR_KEYS, } from '../types/index.js';
3
3
  import { ToolCapability } from '../types/tools.js';
4
4
  export const messageRoleSchema = z.nativeEnum(MessageRole);
5
5
  export const globalRoleSchema = z.nativeEnum(GlobalRole);
6
6
  export const projectRoleSchema = z.nativeEnum(ProjectRole);
7
7
  export const statusMessageTypeSchema = z.nativeEnum(StatusMessageType);
8
+ /** Zod-схемы канонических ключей иконок/цветов (единые для project и session). */
9
+ export const projectIconKeySchema = z.enum(PROJECT_ICON_KEYS);
10
+ export const projectColorKeySchema = z.enum(PROJECT_COLOR_KEYS);
11
+ /**
12
+ * Legacy-алиасы цветов (нормализация при ЧТЕНИИ, не при записи):
13
+ * `blue→primary`, `red→error`, `green→success`, а также CSS-переменные
14
+ * `--primary`/`--status-info`/`--syntax-*`, которыми пользуются агенты.
15
+ * `--status-info` отдельного ключа не имеет — трактуем как `primary`.
16
+ */
17
+ const COLOR_KEY_ALIASES = {
18
+ blue: 'primary',
19
+ red: 'error',
20
+ green: 'success',
21
+ '--primary': 'primary',
22
+ '--status-info': 'primary',
23
+ '--syntax-keyword': 'keyword',
24
+ '--syntax-string': 'string',
25
+ '--syntax-number': 'number',
26
+ '--syntax-type': 'type',
27
+ '--syntax-comment': 'comment',
28
+ '--status-error': 'error',
29
+ '--status-success': 'success',
30
+ };
31
+ /** true, если значение — канонический ключ иконки (без алиасов; для записи). */
32
+ export function isProjectIconKey(value) {
33
+ return typeof value === 'string' && PROJECT_ICON_KEYS.includes(value);
34
+ }
35
+ /** true, если значение — канонический ключ цвета (без алиасов; для записи). */
36
+ export function isProjectColorKey(value) {
37
+ return typeof value === 'string' && PROJECT_COLOR_KEYS.includes(value);
38
+ }
39
+ /**
40
+ * Нормализация иконки при ЧТЕНИИ. Канонический ключ → как есть; всё прочее
41
+ * (эмодзи/произвольные строки) → `undefined`.
42
+ */
43
+ export function normalizeIconKey(value) {
44
+ return isProjectIconKey(value) ? value : undefined;
45
+ }
46
+ /**
47
+ * Нормализация цвета при ЧТЕНИИ: канонический ключ или legacy-алиас → ключ
48
+ * палитры; всё прочее → `undefined`.
49
+ */
50
+ export function normalizeColorKey(value) {
51
+ if (typeof value !== 'string')
52
+ return undefined;
53
+ const canonical = COLOR_KEY_ALIASES[value] ?? value;
54
+ return isProjectColorKey(canonical) ? canonical : undefined;
55
+ }
8
56
  export const tokenUsageSchema = z.object({
9
57
  inputTokens: z.number().int().min(0),
10
58
  outputTokens: z.number().int().min(0),
@@ -38,16 +86,23 @@ export const sessionSettingsSchema = z.object({
38
86
  language: z.string().optional(),
39
87
  // === Plan/Act (AD-025) ===
40
88
  planMode: z.enum(['auto', 'strict', 'off']).optional(),
89
+ // === Скиллы (AD-046 §4.5) ===
90
+ skills: z.array(z.string()).optional(),
91
+ skillsDisabled: z.array(z.string()).optional(),
41
92
  });
42
93
  export const sessionCreateSchema = z.object({
43
94
  name: z.string().min(1).max(200).optional(),
44
95
  title: z.string().min(1).max(200).optional(),
96
+ icon: projectIconKeySchema.optional().nullable(),
97
+ color: projectColorKeySchema.optional().nullable(),
45
98
  projectId: z.string().optional(),
46
99
  engine: z.enum(['synth', 'opencode', 'cline']).default('synth'),
47
100
  settings: sessionSettingsSchema.optional(),
48
101
  });
49
102
  export const sessionUpdateSchema = z.object({
50
103
  name: z.string().min(1).max(200).optional(),
104
+ icon: projectIconKeySchema.optional().nullable(),
105
+ color: projectColorKeySchema.optional().nullable(),
51
106
  projectId: z.string().optional(),
52
107
  engine: z.enum(['synth', 'opencode', 'cline']).optional(),
53
108
  // passthrough: настройки сессии содержат поля вне sessionSettingsSchema
@@ -55,28 +110,64 @@ export const sessionUpdateSchema = z.object({
55
110
  // их нельзя терять при PATCH — известные поля валидируются, неизвестные пропускаются.
56
111
  settings: sessionSettingsSchema.partial().passthrough().optional(),
57
112
  });
113
+ /**
114
+ * AD-076: запись реестра git-репозиториев. `path` обязателен, остальные поля
115
+ * опциональны; старые формы (`string` / `{ path }`) принимаются через
116
+ * `normalizeGitRepoConfig` и union в `repos`.
117
+ */
58
118
  export const gitRepoConfigSchema = z.object({
119
+ id: z.string().optional(),
120
+ name: z.string().optional(),
121
+ url: z.string().optional(),
122
+ type: z.enum(['https', 'ssh']).optional(),
59
123
  path: z.string().min(1),
60
124
  defaultBranch: z.string().optional(),
125
+ sshKeyId: z.string().optional(),
126
+ lastFetch: z.string().optional(),
61
127
  });
128
+ /**
129
+ * AD-076: нормализация legacy-значения `repos` к `GitRepoConfig`.
130
+ * `string` → `{ path }`; объект → прогон через `gitRepoConfigSchema`
131
+ * (невалидный → `null`). Всё прочее → `null`.
132
+ */
133
+ export function normalizeGitRepoConfig(raw) {
134
+ if (typeof raw === 'string') {
135
+ return raw.length > 0 ? { path: raw } : null;
136
+ }
137
+ if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
138
+ const parsed = gitRepoConfigSchema.safeParse(raw);
139
+ return parsed.success ? parsed.data : null;
140
+ }
141
+ return null;
142
+ }
62
143
  export const projectCreateSchema = z.object({
63
144
  name: z.string().min(1).max(200),
64
145
  description: z.string().default(''),
65
- icon: z.string().optional(),
66
- color: z.string().optional(),
146
+ icon: projectIconKeySchema.optional().nullable(),
147
+ color: projectColorKeySchema.optional().nullable(),
67
148
  workspace: z.string().optional(),
68
- repos: z.array(gitRepoConfigSchema).optional(),
149
+ repos: z.array(z.union([z.string(), gitRepoConfigSchema])).optional(),
69
150
  });
70
151
  export const projectUpdateSchema = z.object({
71
152
  name: z.string().min(1).max(200).optional(),
72
153
  description: z.string().optional(),
73
154
  currentTask: z.string().optional(),
74
155
  invariants: z.string().optional(),
75
- icon: z.string().optional(),
76
- color: z.string().optional(),
156
+ icon: projectIconKeySchema.optional().nullable(),
157
+ color: projectColorKeySchema.optional().nullable(),
77
158
  workspace: z.string().optional(),
78
- repos: z.array(gitRepoConfigSchema).optional(),
159
+ repos: z.array(z.union([z.string(), gitRepoConfigSchema])).optional(),
160
+ });
161
+ /** AD-076: тело создания SSH-ключа (`POST /api/v2/ssh-keys`). */
162
+ export const sshKeyCreateSchema = z.object({
163
+ name: z.string().min(1).max(200),
164
+ type: z.string().optional(),
165
+ privateKey: z.string().min(1),
166
+ passphrase: z.string().optional(),
167
+ agentIds: z.array(z.string()).optional(),
79
168
  });
169
+ /** AD-076: тело обновления SSH-ключа (без id/createdAt). */
170
+ export const sshKeyUpdateSchema = sshKeyCreateSchema.partial();
80
171
  /**
81
172
  * AD-071 §2.4: проектный скоуп MCP (ссылки на реестр по имени).
82
173
  * PUT-семантика: `undefined` ≠ `[]` — отсутствующее поле сохраняет текущее
@@ -86,6 +177,13 @@ export const projectMcpUpdateSchema = z.object({
86
177
  enabled: z.array(z.string()).optional(),
87
178
  defaultOn: z.array(z.string()).optional(),
88
179
  });
180
+ /**
181
+ * AD-075: тело `PUT /api/v2/settings/workspace-policy` — политика для
182
+ * абсолютного workspace вне `workspacesRoot`.
183
+ */
184
+ export const workspacePolicySchema = z.object({
185
+ outsideRoot: z.enum(['confirm', 'deny']),
186
+ });
89
187
  export const promptRequestSchema = z.object({
90
188
  messageId: z.string().optional(),
91
189
  content: z.string().min(1),
@@ -127,6 +225,23 @@ export const fsDownloadQuerySchema = z.object({
127
225
  project_id: z.string().min(1),
128
226
  path: z.string().min(1),
129
227
  });
228
+ /**
229
+ * AD-075: запрос навигации по корню workspace (`GET /fs/workspace-root/browse`,
230
+ * `GET /fs/workspace-root`). `includeHidden` принимает строковые `true`/`false`
231
+ * (query-параметры) — `z.coerce.boolean()` не подходит, т.к. `'false'` → `true`.
232
+ */
233
+ export const fsWorkspaceBrowseQuerySchema = z.object({
234
+ path: z.string().default(''),
235
+ includeHidden: z
236
+ .preprocess((v) => (v === 'true' ? true : v === 'false' ? false : v), z.boolean().optional())
237
+ .default(false),
238
+ });
239
+ /** AD-075: тело `POST /fs/workspace-root/mkdir` — создание каталога в корне workspace. */
240
+ export const fsWorkspaceMkdirBodySchema = z.object({
241
+ path: z.string().min(1),
242
+ /** `confirm`-политика: явное подтверждение создания каталога вне `workspacesRoot`. */
243
+ confirmOutsideRoot: z.boolean().optional(),
244
+ });
130
245
  // --- Git schemas ---
131
246
  export const gitScanBodySchema = z.object({
132
247
  projectId: z.string().min(1),
@@ -135,13 +250,51 @@ export const gitInitBodySchema = z.object({
135
250
  projectId: z.string().min(1),
136
251
  path: z.string(),
137
252
  defaultBranch: z.string().optional(),
253
+ name: z.string().optional(),
254
+ sshKeyId: z.string().optional(),
138
255
  });
139
256
  export const gitCloneBodySchema = z.object({
140
257
  projectId: z.string().min(1),
141
258
  url: z.string().min(1),
142
259
  path: z.string().optional(),
143
260
  branch: z.string().optional(),
261
+ name: z.string().optional(),
262
+ sshKeyId: z.string().optional(),
263
+ });
264
+ /**
265
+ * AD-076: тело `POST /api/v2/git/repos/register` — upsert записи реестра
266
+ * (идемпотентно по `path`). Используется UI для добавления уже существующего
267
+ * локально репозитория.
268
+ */
269
+ export const gitReposRegisterBodySchema = z.object({
270
+ projectId: z.string().min(1),
271
+ path: z.string().min(1),
272
+ name: z.string().optional(),
273
+ url: z.string().optional(),
274
+ type: z.enum(['https', 'ssh']).optional(),
275
+ defaultBranch: z.string().optional(),
276
+ sshKeyId: z.string().optional(),
144
277
  });
278
+ /**
279
+ * AD-076: тело `POST /api/v2/git/repos/remove` — удаление записи реестра;
280
+ * обязателен `id` либо `path`. `deleteLocal` — удалить каталог репозитория.
281
+ */
282
+ export const gitReposRemoveBodySchema = z
283
+ .object({
284
+ projectId: z.string().min(1),
285
+ id: z.string().optional(),
286
+ path: z.string().optional(),
287
+ deleteLocal: z.boolean().optional(),
288
+ })
289
+ .refine((v) => Boolean(v.id || v.path), { message: 'Требуется id или path' });
290
+ /** AD-076: тело `POST /api/v2/git/repos/fetch` — обязателен `id` либо `path`. */
291
+ export const gitReposFetchBodySchema = z
292
+ .object({
293
+ projectId: z.string().min(1),
294
+ id: z.string().optional(),
295
+ path: z.string().optional(),
296
+ })
297
+ .refine((v) => Boolean(v.id || v.path), { message: 'Требуется id или path' });
145
298
  export const gitLogQuerySchema = z.object({
146
299
  project_id: z.string().min(1),
147
300
  repo_path: z.string().default(''),
@@ -204,4 +357,87 @@ export const sessionMcpUpdateSchema = z
204
357
  .refine((v) => v.name !== undefined
205
358
  || v.mcpServers !== undefined
206
359
  || v.mcpDisabledServers !== undefined, { message: 'Требуется name, mcpServers или mcpDisabledServers' });
207
- //# sourceMappingURL=index.js.map
360
+ // --- Скиллы (AD-046) ---
361
+ /** AD-046 §3.2: имя скилла — 1–64, `^[a-z0-9]+(-[a-z0-9]+)*$`. */
362
+ export const SKILL_NAME_REGEX = /^[a-z0-9]+(-[a-z0-9]+)*$/;
363
+ export const SKILL_NAME_MIN = 1;
364
+ export const SKILL_NAME_MAX = 64;
365
+ /** AD-046 §3.2: длина `description`. */
366
+ export const SKILL_DESCRIPTION_MIN = 1;
367
+ export const SKILL_DESCRIPTION_MAX = 1024;
368
+ export const skillNameSchema = z
369
+ .string()
370
+ .min(SKILL_NAME_MIN)
371
+ .max(SKILL_NAME_MAX)
372
+ .regex(SKILL_NAME_REGEX, 'имя скилла: строчные латинские буквы/цифры, разделитель — дефис');
373
+ export const skillCreateSchema = z.object({
374
+ name: skillNameSchema,
375
+ description: z.string().min(SKILL_DESCRIPTION_MIN).max(SKILL_DESCRIPTION_MAX),
376
+ /** Тело Markdown (без frontmatter). */
377
+ body: z.string().optional(),
378
+ /** Дополнительные supporting-файлы (относительный путь → содержимое). */
379
+ files: z.record(z.string().min(1), z.string()).optional(),
380
+ });
381
+ export const skillUpdateSchema = z
382
+ .object({
383
+ description: z.string().min(SKILL_DESCRIPTION_MIN).max(SKILL_DESCRIPTION_MAX).optional(),
384
+ body: z.string().optional(),
385
+ /** Толерантный контейнер (неизвестные ключи сохраняются). */
386
+ metadata: z.record(z.string(), z.unknown()).optional(),
387
+ })
388
+ .refine((v) => v.description !== undefined || v.body !== undefined || v.metadata !== undefined, { message: 'Требуется description, body или metadata' });
389
+ export const skillFileWriteSchema = z.object({
390
+ content: z.string(),
391
+ });
392
+ /**
393
+ * AD-046 §4.5: per-session enable/disable скиллов (по образцу MCP-скоупа).
394
+ * `undefined` ≠ `[]`: отсутствующее поле сохраняет текущее значение.
395
+ */
396
+ export const skillSessionOverrideSchema = z.object({
397
+ skills: z.array(z.string()).optional(),
398
+ skillsDisabled: z.array(z.string()).optional(),
399
+ });
400
+ // --- Slash-команды и bundles (AD-046 §7) ---
401
+ /** AD-046 §7.3: тело `POST/PATCH /api/v2/skill-bundles` (YAML-группа скиллов). */
402
+ export const skillBundleSchema = z.object({
403
+ name: skillNameSchema,
404
+ description: z.string().min(SKILL_DESCRIPTION_MIN).max(SKILL_DESCRIPTION_MAX),
405
+ skills: z.array(skillNameSchema).min(1),
406
+ instruction: z.string().optional(),
407
+ });
408
+ /** AD-046 §7.4: тело `PUT /api/v2/settings/skills-disabled` (группы/имена). */
409
+ export const skillsDisabledSchema = z.object({
410
+ categories: z.array(z.string()).default([]),
411
+ groups: z.array(z.string()).default([]),
412
+ skills: z.array(z.string()).default([]),
413
+ });
414
+ /**
415
+ * AD-046 §4.5: тело `PUT /api/v2/settings/skills` — системные настройки:
416
+ * - `disabled` — hard-gate: скиллы, недоступные НИГДЕ;
417
+ * - `disabledForNewProjects` — сид для НОВЫХ проектов (снимок при создании);
418
+ * - `policy` — политика доступности (строкой, валидируется роутом).
419
+ */
420
+ export const skillsSystemSettingsSchema = z.object({
421
+ disabled: skillsDisabledSchema.optional(),
422
+ disabledForNewProjects: skillsDisabledSchema.optional(),
423
+ policy: z.string().optional(),
424
+ });
425
+ /**
426
+ * AD-046 §4.5: тело `PUT /api/v2/sessions/:id/skills`: точечный toggle
427
+ * (`{ name, enabled }`) или полная/частичная замена (`{ skills?, skillsDisabled? }`).
428
+ */
429
+ export const sessionSkillUpdateSchema = z
430
+ .object({
431
+ name: z.string().min(1).optional(),
432
+ enabled: z.boolean().optional(),
433
+ skills: z.array(z.string()).optional(),
434
+ skillsDisabled: z.array(z.string()).optional(),
435
+ })
436
+ .refine((v) => v.name !== undefined
437
+ || v.skills !== undefined
438
+ || v.skillsDisabled !== undefined, { message: 'Требуется name, skills или skillsDisabled' });
439
+ /** AD-046 §4.5: тело `PUT /api/v2/projects/:id/skills`. */
440
+ export const projectSkillUpdateSchema = z.object({
441
+ enabled: z.array(z.string()).optional(),
442
+ defaultOn: z.array(z.string()).optional(),
443
+ });
@@ -0,0 +1,20 @@
1
+ import type { SkillIssue } from '../types/skills.js';
2
+ export interface ParsedFrontmatter {
3
+ /** Разобранный frontmatter (пустой объект, если его нет/невалиден). */
4
+ data: Record<string, unknown>;
5
+ /** Тело документа (Markdown после frontmatter). */
6
+ body: string;
7
+ /** Проблемы парсинга (не бросаем исключений). */
8
+ issues: SkillIssue[];
9
+ hasFrontmatter: boolean;
10
+ }
11
+ /**
12
+ * Разбирает frontmatter. Возвращает issues, а не throw — вызывающая сторона
13
+ * решает, блокирует ли проблема загрузку скилла.
14
+ */
15
+ export declare function parseFrontmatter(raw: string): ParsedFrontmatter;
16
+ /**
17
+ * Сериализует frontmatter + тело обратно в `SKILL.md`. Используется записью
18
+ * instance-скиллов через сервис (не ручной записью JSON/файлов).
19
+ */
20
+ export declare function stringifyFrontmatter(data: Record<string, unknown>, body: string): string;
@@ -0,0 +1,69 @@
1
+ import { load as parseYaml, dump as dumpYaml } from 'js-yaml';
2
+ /**
3
+ * AD-046 §3.1: толерантный парсер YAML-frontmatter `SKILL.md`.
4
+ *
5
+ * - Неизвестные ключи — не ошибка (совместимость Anthropic/opencode/Claude Code).
6
+ * - Невалидный YAML — фиксируется issue, но не бросает исключение.
7
+ * - Файл без frontmatter — `hasFrontmatter: false`, тело — весь документ.
8
+ *
9
+ * Хелпер не выполняет валидацию `name`/`description` (это делает parser ядра):
10
+ * он лишь отделяет frontmatter от тела и нормализует YAML-объект.
11
+ */
12
+ /** Открывающий `---` в самом начале документа (с возможным BOM/переводом строк). */
13
+ const FRONTMATTER_RE = /^\uFEFF?---[ \t]*\r?\n([\s\S]*?)(?:\r?\n)?---[ \t]*(?:\r?\n|$)/;
14
+ /**
15
+ * Разбирает frontmatter. Возвращает issues, а не throw — вызывающая сторона
16
+ * решает, блокирует ли проблема загрузку скилла.
17
+ */
18
+ export function parseFrontmatter(raw) {
19
+ const match = FRONTMATTER_RE.exec(raw);
20
+ if (!match) {
21
+ return { data: {}, body: raw, issues: [], hasFrontmatter: false };
22
+ }
23
+ const yamlBlock = match[1] ?? '';
24
+ const body = raw.slice(match[0].length);
25
+ let parsed;
26
+ try {
27
+ parsed = parseYaml(yamlBlock);
28
+ }
29
+ catch (err) {
30
+ return {
31
+ data: {},
32
+ body,
33
+ hasFrontmatter: true,
34
+ issues: [{
35
+ code: 'invalid-frontmatter',
36
+ message: `невалидный YAML frontmatter: ${err instanceof Error ? err.message : String(err)}`,
37
+ }],
38
+ };
39
+ }
40
+ if (parsed === null || parsed === undefined) {
41
+ return { data: {}, body, hasFrontmatter: true, issues: [] };
42
+ }
43
+ if (typeof parsed !== 'object' || Array.isArray(parsed)) {
44
+ return {
45
+ data: {},
46
+ body,
47
+ hasFrontmatter: true,
48
+ issues: [{
49
+ code: 'invalid-frontmatter-type',
50
+ message: 'frontmatter должен быть YAML-объектом',
51
+ }],
52
+ };
53
+ }
54
+ return {
55
+ data: parsed,
56
+ body,
57
+ hasFrontmatter: true,
58
+ issues: [],
59
+ };
60
+ }
61
+ /**
62
+ * Сериализует frontmatter + тело обратно в `SKILL.md`. Используется записью
63
+ * instance-скиллов через сервис (не ручной записью JSON/файлов).
64
+ */
65
+ export function stringifyFrontmatter(data, body) {
66
+ const yaml = dumpYaml(data, { indent: 2, lineWidth: 120, noRefs: true, sortKeys: false }).trimEnd();
67
+ const normalizedBody = body.replace(/^\n+/, '');
68
+ return `---\n${yaml}\n---\n\n${normalizedBody}`;
69
+ }
@@ -0,0 +1,127 @@
1
+ import type { SkillScope, SkillLevel } from './skills.js';
2
+ import type { PermissionConfig } from './permission.js';
3
+ /**
4
+ * AD-046 §7: slash-команды и bundles — контракты. Здесь только типы (без
5
+ * бизнес-логики движка); резолвинг выполняется в core до обращения к LLM.
6
+ */
7
+ /** Вид команды (AD-046 §7.2). */
8
+ export declare const COMMAND_KINDS: readonly ["builtin", "template", "skill", "bundle"];
9
+ export type CommandKind = (typeof COMMAND_KINDS)[number];
10
+ /** Режим разрешения конфликтов имён (настройка `commands.conflict.mode`). */
11
+ export declare const COMMAND_CONFLICT_MODES: readonly ["bundle-wins", "conservative", "namespace"];
12
+ export type CommandConflictMode = (typeof COMMAND_CONFLICT_MODES)[number];
13
+ /** Кто инициировал команду (для события `command.invoked`, §8.2). */
14
+ export declare const COMMAND_ACTORS: readonly ["user", "cli"];
15
+ export type CommandActor = (typeof COMMAND_ACTORS)[number];
16
+ /** Уровень диагностики discovery/валидации команд. */
17
+ export type CommandDiagnosticLevel = 'error' | 'warning' | 'info';
18
+ /** Коды диагностики команд/бандлов (только реально эмитируемые). */
19
+ export type CommandIssueCode = 'invalid-frontmatter' | 'missing-name' | 'shadowed' | 'collision' | 'invalid-bundle' | 'missing-skill' | 'read-error'
20
+ /** AD-046 §4.4/§7.1: проектный каталог недоверенный — команда не грузится. */
21
+ | 'untrusted';
22
+ /** Диагностика реестра команд (видна в `GET /api/v2/commands?diagnostics=1`). */
23
+ export interface CommandDiagnostic {
24
+ level: CommandDiagnosticLevel;
25
+ code: CommandIssueCode;
26
+ message: string;
27
+ /** Имя команды/бандла (если известно). */
28
+ command?: string;
29
+ /** Путь к файлу/каталогу (если применимо). */
30
+ path?: string;
31
+ }
32
+ /**
33
+ * YAML-группа скиллов (AD-046 §7.3). `/bundle-name` грузит N тел одним
34
+ * сообщением; bundle побеждает одноимённый skill.
35
+ */
36
+ export interface SkillBundle {
37
+ name: string;
38
+ description: string;
39
+ skills: string[];
40
+ /** Дополнительная инструкция над телами скиллов (опционально). */
41
+ instruction?: string;
42
+ }
43
+ /** Сводка команды (для `GET /api/v2/commands` и автокомплита). */
44
+ export interface CommandSummary {
45
+ name: string;
46
+ kind: CommandKind;
47
+ description: string;
48
+ argumentHint?: string;
49
+ scope?: SkillScope;
50
+ level?: SkillLevel;
51
+ /** Имя бандла-источника (для `kind: 'bundle'`). */
52
+ bundle?: string;
53
+ /** Скиллы, входящие в bundle. */
54
+ skills?: string[];
55
+ /** `false` — команда видна, но недоступна (capabilities/deny). */
56
+ available: boolean;
57
+ unavailableReason?: 'capabilities' | 'denied';
58
+ }
59
+ /** Статус результата резолвинга команды. */
60
+ export type CommandResolveStatus = 'builtin' | 'prompt' | 'template' | 'skill' | 'bundle' | 'summarization' | 'unknown' | 'denied' | 'unavailable';
61
+ /**
62
+ * Результат резолвинга `/`-команды (AD-046 §7.1).
63
+ *
64
+ * - `builtin` — локальный ответ (`output`), LLM не вызывается; user+assistant
65
+ * сообщения помечаются `ephemeral` и исключаются из LLM-контекста;
66
+ * - `prompt` — встроенная команда, генерирующая prompt (`/init`): текст в
67
+ * `prompt` уходит в LLM как явный пользовательский контекст, локального
68
+ * ответа нет и CLI не короткозамыкает;
69
+ * - `template`/`skill`/`bundle` — текст в `prompt` уходит в LLM как явный
70
+ * пользовательский контекст;
71
+ * - `summarization` — триггер ручной суммаризации (`/summary`);
72
+ * - `unknown`/`denied`/`unavailable` — ответ-объяснение, LLM не вызывается.
73
+ */
74
+ export interface CommandResolveResult {
75
+ status: CommandResolveStatus;
76
+ /** Имя команды без `/`. */
77
+ name: string;
78
+ /** Аргументы после имени. */
79
+ args: string;
80
+ kind?: CommandKind;
81
+ /** Текст, инжектируемый в LLM (template/skill/bundle). */
82
+ prompt?: string;
83
+ /** Локальный ответ (builtin/unknown/denied/unavailable). */
84
+ output?: string;
85
+ /** Загруженные тела скиллов (для событий `skill.invoked`). */
86
+ skills?: string[];
87
+ /** Причина denied/unavailable. */
88
+ message?: string;
89
+ }
90
+ /** AD-046 §7.4: результат исполнения inline shell (`` !`cmd` ``). */
91
+ export interface CommandShellResult {
92
+ output: string;
93
+ isError: boolean;
94
+ }
95
+ /**
96
+ * AD-046 §7.4: раннер inline shell. Оркестратор передаёт замыкание, которое
97
+ * само проходит `PermissionEvaluator` (AD-029) и исполняет команду; сервис
98
+ * команд только вызывает его для подстановки `` !`cmd` ``.
99
+ */
100
+ export type CommandShellRunner = (command: string) => Promise<CommandShellResult>;
101
+ /** Общие опции фильтрации/резолвинга команд. */
102
+ export interface CommandRuntimeOpts {
103
+ projectWorkspace?: string;
104
+ capabilities?: readonly string[];
105
+ agent?: {
106
+ id?: string;
107
+ groups?: string[];
108
+ };
109
+ sessionEnabled?: string[];
110
+ sessionDisabled?: string[];
111
+ permissionConfig?: PermissionConfig;
112
+ /** AD-046 §7.4: раннер inline shell (только при включённом `skills.inlineShell`). */
113
+ runShell?: CommandShellRunner;
114
+ }
115
+ /**
116
+ * AD-046 §7.3: рантайм-контракт команд для оркестратора/CLI. Структурно
117
+ * реализуется `CommandService`; прокидывается в `OrchestratorOptions`.
118
+ */
119
+ export interface CommandRuntime {
120
+ /** Список команд (builtin + template + skills + bundles) с учётом фильтров. */
121
+ list(opts?: CommandRuntimeOpts): Promise<{
122
+ commands: CommandSummary[];
123
+ diagnostics: CommandDiagnostic[];
124
+ }>;
125
+ /** Резолвинг `/`-команды. `undefined` — сообщение не является командой. */
126
+ resolve(input: string, opts?: CommandRuntimeOpts): Promise<CommandResolveResult | undefined>;
127
+ }
@@ -0,0 +1,10 @@
1
+ /**
2
+ * AD-046 §7: slash-команды и bundles — контракты. Здесь только типы (без
3
+ * бизнес-логики движка); резолвинг выполняется в core до обращения к LLM.
4
+ */
5
+ /** Вид команды (AD-046 §7.2). */
6
+ export const COMMAND_KINDS = ['builtin', 'template', 'skill', 'bundle'];
7
+ /** Режим разрешения конфликтов имён (настройка `commands.conflict.mode`). */
8
+ export const COMMAND_CONFLICT_MODES = ['bundle-wins', 'conservative', 'namespace'];
9
+ /** Кто инициировал команду (для события `command.invoked`, §8.2). */
10
+ export const COMMAND_ACTORS = ['user', 'cli'];