@kynetic-ai/spec 0.1.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.
Files changed (278) hide show
  1. package/README.md +263 -0
  2. package/dist/acp/client.d.ts +159 -0
  3. package/dist/acp/client.d.ts.map +1 -0
  4. package/dist/acp/client.js +255 -0
  5. package/dist/acp/client.js.map +1 -0
  6. package/dist/acp/framing.d.ts +119 -0
  7. package/dist/acp/framing.d.ts.map +1 -0
  8. package/dist/acp/framing.js +302 -0
  9. package/dist/acp/framing.js.map +1 -0
  10. package/dist/acp/index.d.ts +14 -0
  11. package/dist/acp/index.d.ts.map +1 -0
  12. package/dist/acp/index.js +13 -0
  13. package/dist/acp/index.js.map +1 -0
  14. package/dist/acp/types.d.ts +89 -0
  15. package/dist/acp/types.d.ts.map +1 -0
  16. package/dist/acp/types.js +99 -0
  17. package/dist/acp/types.js.map +1 -0
  18. package/dist/agents/adapters.d.ts +55 -0
  19. package/dist/agents/adapters.d.ts.map +1 -0
  20. package/dist/agents/adapters.js +84 -0
  21. package/dist/agents/adapters.js.map +1 -0
  22. package/dist/agents/index.d.ts +8 -0
  23. package/dist/agents/index.d.ts.map +1 -0
  24. package/dist/agents/index.js +10 -0
  25. package/dist/agents/index.js.map +1 -0
  26. package/dist/agents/spawner.d.ts +53 -0
  27. package/dist/agents/spawner.d.ts.map +1 -0
  28. package/dist/agents/spawner.js +83 -0
  29. package/dist/agents/spawner.js.map +1 -0
  30. package/dist/cli/batch.d.ts +82 -0
  31. package/dist/cli/batch.d.ts.map +1 -0
  32. package/dist/cli/batch.js +162 -0
  33. package/dist/cli/batch.js.map +1 -0
  34. package/dist/cli/commands/clone-for-testing.d.ts +6 -0
  35. package/dist/cli/commands/clone-for-testing.d.ts.map +1 -0
  36. package/dist/cli/commands/clone-for-testing.js +176 -0
  37. package/dist/cli/commands/clone-for-testing.js.map +1 -0
  38. package/dist/cli/commands/derive.d.ts +6 -0
  39. package/dist/cli/commands/derive.d.ts.map +1 -0
  40. package/dist/cli/commands/derive.js +450 -0
  41. package/dist/cli/commands/derive.js.map +1 -0
  42. package/dist/cli/commands/help.d.ts +6 -0
  43. package/dist/cli/commands/help.d.ts.map +1 -0
  44. package/dist/cli/commands/help.js +196 -0
  45. package/dist/cli/commands/help.js.map +1 -0
  46. package/dist/cli/commands/inbox.d.ts +6 -0
  47. package/dist/cli/commands/inbox.d.ts.map +1 -0
  48. package/dist/cli/commands/inbox.js +235 -0
  49. package/dist/cli/commands/inbox.js.map +1 -0
  50. package/dist/cli/commands/index.d.ts +20 -0
  51. package/dist/cli/commands/index.d.ts.map +1 -0
  52. package/dist/cli/commands/index.js +21 -0
  53. package/dist/cli/commands/index.js.map +1 -0
  54. package/dist/cli/commands/init.d.ts +6 -0
  55. package/dist/cli/commands/init.d.ts.map +1 -0
  56. package/dist/cli/commands/init.js +245 -0
  57. package/dist/cli/commands/init.js.map +1 -0
  58. package/dist/cli/commands/item.d.ts +6 -0
  59. package/dist/cli/commands/item.d.ts.map +1 -0
  60. package/dist/cli/commands/item.js +1311 -0
  61. package/dist/cli/commands/item.js.map +1 -0
  62. package/dist/cli/commands/link.d.ts +6 -0
  63. package/dist/cli/commands/link.d.ts.map +1 -0
  64. package/dist/cli/commands/link.js +288 -0
  65. package/dist/cli/commands/link.js.map +1 -0
  66. package/dist/cli/commands/log.d.ts +16 -0
  67. package/dist/cli/commands/log.d.ts.map +1 -0
  68. package/dist/cli/commands/log.js +291 -0
  69. package/dist/cli/commands/log.js.map +1 -0
  70. package/dist/cli/commands/meta.d.ts +15 -0
  71. package/dist/cli/commands/meta.d.ts.map +1 -0
  72. package/dist/cli/commands/meta.js +1378 -0
  73. package/dist/cli/commands/meta.js.map +1 -0
  74. package/dist/cli/commands/module.d.ts +6 -0
  75. package/dist/cli/commands/module.d.ts.map +1 -0
  76. package/dist/cli/commands/module.js +102 -0
  77. package/dist/cli/commands/module.js.map +1 -0
  78. package/dist/cli/commands/ralph.d.ts +9 -0
  79. package/dist/cli/commands/ralph.d.ts.map +1 -0
  80. package/dist/cli/commands/ralph.js +465 -0
  81. package/dist/cli/commands/ralph.js.map +1 -0
  82. package/dist/cli/commands/search.d.ts +6 -0
  83. package/dist/cli/commands/search.d.ts.map +1 -0
  84. package/dist/cli/commands/search.js +134 -0
  85. package/dist/cli/commands/search.js.map +1 -0
  86. package/dist/cli/commands/session.d.ts +164 -0
  87. package/dist/cli/commands/session.d.ts.map +1 -0
  88. package/dist/cli/commands/session.js +745 -0
  89. package/dist/cli/commands/session.js.map +1 -0
  90. package/dist/cli/commands/setup.d.ts +26 -0
  91. package/dist/cli/commands/setup.d.ts.map +1 -0
  92. package/dist/cli/commands/setup.js +586 -0
  93. package/dist/cli/commands/setup.js.map +1 -0
  94. package/dist/cli/commands/shadow.d.ts +6 -0
  95. package/dist/cli/commands/shadow.d.ts.map +1 -0
  96. package/dist/cli/commands/shadow.js +299 -0
  97. package/dist/cli/commands/shadow.js.map +1 -0
  98. package/dist/cli/commands/task.d.ts +6 -0
  99. package/dist/cli/commands/task.d.ts.map +1 -0
  100. package/dist/cli/commands/task.js +1514 -0
  101. package/dist/cli/commands/task.js.map +1 -0
  102. package/dist/cli/commands/tasks.d.ts +6 -0
  103. package/dist/cli/commands/tasks.d.ts.map +1 -0
  104. package/dist/cli/commands/tasks.js +347 -0
  105. package/dist/cli/commands/tasks.js.map +1 -0
  106. package/dist/cli/commands/trait.d.ts +10 -0
  107. package/dist/cli/commands/trait.d.ts.map +1 -0
  108. package/dist/cli/commands/trait.js +295 -0
  109. package/dist/cli/commands/trait.js.map +1 -0
  110. package/dist/cli/commands/validate.d.ts +6 -0
  111. package/dist/cli/commands/validate.d.ts.map +1 -0
  112. package/dist/cli/commands/validate.js +626 -0
  113. package/dist/cli/commands/validate.js.map +1 -0
  114. package/dist/cli/exit-codes.d.ts +62 -0
  115. package/dist/cli/exit-codes.d.ts.map +1 -0
  116. package/dist/cli/exit-codes.js +65 -0
  117. package/dist/cli/exit-codes.js.map +1 -0
  118. package/dist/cli/help/content.d.ts +35 -0
  119. package/dist/cli/help/content.d.ts.map +1 -0
  120. package/dist/cli/help/content.js +312 -0
  121. package/dist/cli/help/content.js.map +1 -0
  122. package/dist/cli/index.d.ts +5 -0
  123. package/dist/cli/index.d.ts.map +1 -0
  124. package/dist/cli/index.js +85 -0
  125. package/dist/cli/index.js.map +1 -0
  126. package/dist/cli/introspection.d.ts +87 -0
  127. package/dist/cli/introspection.d.ts.map +1 -0
  128. package/dist/cli/introspection.js +127 -0
  129. package/dist/cli/introspection.js.map +1 -0
  130. package/dist/cli/output.d.ts +56 -0
  131. package/dist/cli/output.d.ts.map +1 -0
  132. package/dist/cli/output.js +467 -0
  133. package/dist/cli/output.js.map +1 -0
  134. package/dist/cli/suggest.d.ts +16 -0
  135. package/dist/cli/suggest.d.ts.map +1 -0
  136. package/dist/cli/suggest.js +72 -0
  137. package/dist/cli/suggest.js.map +1 -0
  138. package/dist/index.d.ts +3 -0
  139. package/dist/index.d.ts.map +1 -0
  140. package/dist/index.js +5 -0
  141. package/dist/index.js.map +1 -0
  142. package/dist/parser/alignment.d.ts +113 -0
  143. package/dist/parser/alignment.d.ts.map +1 -0
  144. package/dist/parser/alignment.js +261 -0
  145. package/dist/parser/alignment.js.map +1 -0
  146. package/dist/parser/assess.d.ts +81 -0
  147. package/dist/parser/assess.d.ts.map +1 -0
  148. package/dist/parser/assess.js +197 -0
  149. package/dist/parser/assess.js.map +1 -0
  150. package/dist/parser/convention-validation.d.ts +48 -0
  151. package/dist/parser/convention-validation.d.ts.map +1 -0
  152. package/dist/parser/convention-validation.js +167 -0
  153. package/dist/parser/convention-validation.js.map +1 -0
  154. package/dist/parser/fix.d.ts +38 -0
  155. package/dist/parser/fix.d.ts.map +1 -0
  156. package/dist/parser/fix.js +185 -0
  157. package/dist/parser/fix.js.map +1 -0
  158. package/dist/parser/index.d.ts +12 -0
  159. package/dist/parser/index.d.ts.map +1 -0
  160. package/dist/parser/index.js +13 -0
  161. package/dist/parser/index.js.map +1 -0
  162. package/dist/parser/items.d.ts +138 -0
  163. package/dist/parser/items.d.ts.map +1 -0
  164. package/dist/parser/items.js +321 -0
  165. package/dist/parser/items.js.map +1 -0
  166. package/dist/parser/meta.d.ts +120 -0
  167. package/dist/parser/meta.d.ts.map +1 -0
  168. package/dist/parser/meta.js +441 -0
  169. package/dist/parser/meta.js.map +1 -0
  170. package/dist/parser/refs.d.ts +185 -0
  171. package/dist/parser/refs.d.ts.map +1 -0
  172. package/dist/parser/refs.js +404 -0
  173. package/dist/parser/refs.js.map +1 -0
  174. package/dist/parser/shadow.d.ts +253 -0
  175. package/dist/parser/shadow.d.ts.map +1 -0
  176. package/dist/parser/shadow.js +1053 -0
  177. package/dist/parser/shadow.js.map +1 -0
  178. package/dist/parser/traits.d.ts +72 -0
  179. package/dist/parser/traits.d.ts.map +1 -0
  180. package/dist/parser/traits.js +120 -0
  181. package/dist/parser/traits.js.map +1 -0
  182. package/dist/parser/validate.d.ts +89 -0
  183. package/dist/parser/validate.d.ts.map +1 -0
  184. package/dist/parser/validate.js +817 -0
  185. package/dist/parser/validate.js.map +1 -0
  186. package/dist/parser/yaml.d.ts +326 -0
  187. package/dist/parser/yaml.d.ts.map +1 -0
  188. package/dist/parser/yaml.js +1383 -0
  189. package/dist/parser/yaml.js.map +1 -0
  190. package/dist/ralph/cli-renderer.d.ts +20 -0
  191. package/dist/ralph/cli-renderer.d.ts.map +1 -0
  192. package/dist/ralph/cli-renderer.js +179 -0
  193. package/dist/ralph/cli-renderer.js.map +1 -0
  194. package/dist/ralph/events.d.ts +65 -0
  195. package/dist/ralph/events.d.ts.map +1 -0
  196. package/dist/ralph/events.js +397 -0
  197. package/dist/ralph/events.js.map +1 -0
  198. package/dist/ralph/index.d.ts +8 -0
  199. package/dist/ralph/index.d.ts.map +1 -0
  200. package/dist/ralph/index.js +10 -0
  201. package/dist/ralph/index.js.map +1 -0
  202. package/dist/schema/common.d.ts +46 -0
  203. package/dist/schema/common.d.ts.map +1 -0
  204. package/dist/schema/common.js +71 -0
  205. package/dist/schema/common.js.map +1 -0
  206. package/dist/schema/inbox.d.ts +90 -0
  207. package/dist/schema/inbox.d.ts.map +1 -0
  208. package/dist/schema/inbox.js +30 -0
  209. package/dist/schema/inbox.js.map +1 -0
  210. package/dist/schema/index.d.ts +6 -0
  211. package/dist/schema/index.d.ts.map +1 -0
  212. package/dist/schema/index.js +7 -0
  213. package/dist/schema/index.js.map +1 -0
  214. package/dist/schema/meta.d.ts +762 -0
  215. package/dist/schema/meta.d.ts.map +1 -0
  216. package/dist/schema/meta.js +144 -0
  217. package/dist/schema/meta.js.map +1 -0
  218. package/dist/schema/spec.d.ts +912 -0
  219. package/dist/schema/spec.d.ts.map +1 -0
  220. package/dist/schema/spec.js +104 -0
  221. package/dist/schema/spec.js.map +1 -0
  222. package/dist/schema/task.d.ts +664 -0
  223. package/dist/schema/task.d.ts.map +1 -0
  224. package/dist/schema/task.js +130 -0
  225. package/dist/schema/task.js.map +1 -0
  226. package/dist/sessions/index.d.ts +11 -0
  227. package/dist/sessions/index.d.ts.map +1 -0
  228. package/dist/sessions/index.js +13 -0
  229. package/dist/sessions/index.js.map +1 -0
  230. package/dist/sessions/store.d.ts +144 -0
  231. package/dist/sessions/store.d.ts.map +1 -0
  232. package/dist/sessions/store.js +325 -0
  233. package/dist/sessions/store.js.map +1 -0
  234. package/dist/sessions/types.d.ts +157 -0
  235. package/dist/sessions/types.d.ts.map +1 -0
  236. package/dist/sessions/types.js +90 -0
  237. package/dist/sessions/types.js.map +1 -0
  238. package/dist/strings/errors.d.ts +420 -0
  239. package/dist/strings/errors.d.ts.map +1 -0
  240. package/dist/strings/errors.js +282 -0
  241. package/dist/strings/errors.js.map +1 -0
  242. package/dist/strings/guidance.d.ts +65 -0
  243. package/dist/strings/guidance.d.ts.map +1 -0
  244. package/dist/strings/guidance.js +66 -0
  245. package/dist/strings/guidance.js.map +1 -0
  246. package/dist/strings/index.d.ts +12 -0
  247. package/dist/strings/index.d.ts.map +1 -0
  248. package/dist/strings/index.js +12 -0
  249. package/dist/strings/index.js.map +1 -0
  250. package/dist/strings/labels.d.ts +74 -0
  251. package/dist/strings/labels.d.ts.map +1 -0
  252. package/dist/strings/labels.js +75 -0
  253. package/dist/strings/labels.js.map +1 -0
  254. package/dist/strings/validation.d.ts +126 -0
  255. package/dist/strings/validation.d.ts.map +1 -0
  256. package/dist/strings/validation.js +135 -0
  257. package/dist/strings/validation.js.map +1 -0
  258. package/dist/utils/commit.d.ts +23 -0
  259. package/dist/utils/commit.d.ts.map +1 -0
  260. package/dist/utils/commit.js +67 -0
  261. package/dist/utils/commit.js.map +1 -0
  262. package/dist/utils/git.d.ts +57 -0
  263. package/dist/utils/git.d.ts.map +1 -0
  264. package/dist/utils/git.js +192 -0
  265. package/dist/utils/git.js.map +1 -0
  266. package/dist/utils/grep.d.ts +28 -0
  267. package/dist/utils/grep.d.ts.map +1 -0
  268. package/dist/utils/grep.js +86 -0
  269. package/dist/utils/grep.js.map +1 -0
  270. package/dist/utils/index.d.ts +8 -0
  271. package/dist/utils/index.d.ts.map +1 -0
  272. package/dist/utils/index.js +6 -0
  273. package/dist/utils/index.js.map +1 -0
  274. package/dist/utils/time.d.ts +18 -0
  275. package/dist/utils/time.d.ts.map +1 -0
  276. package/dist/utils/time.js +61 -0
  277. package/dist/utils/time.js.map +1 -0
  278. package/package.json +62 -0
@@ -0,0 +1,441 @@
1
+ /**
2
+ * Meta manifest loading and operations.
3
+ *
4
+ * The meta manifest (kynetic.meta.yaml) contains process definitions:
5
+ * - Agents: roles, capabilities, conventions
6
+ * - Workflows: structured processes with steps
7
+ * - Conventions: project rules and standards
8
+ * - Observations: feedback about processes
9
+ */
10
+ import * as fs from 'node:fs/promises';
11
+ import * as path from 'node:path';
12
+ import { ulid } from 'ulid';
13
+ import { MetaManifestSchema, AgentSchema, WorkflowSchema, ConventionSchema, ObservationSchema, SessionContextSchema, getMetaItemType, } from '../schema/index.js';
14
+ import { readYamlFile, writeYamlFilePreserveFormat, expandIncludePattern, getAuthor } from './yaml.js';
15
+ /**
16
+ * Find the meta manifest file (kynetic.meta.yaml)
17
+ */
18
+ export async function findMetaManifest(specDir) {
19
+ const candidates = ['kynetic.meta.yaml'];
20
+ for (const candidate of candidates) {
21
+ const filePath = path.join(specDir, candidate);
22
+ try {
23
+ await fs.access(filePath);
24
+ return filePath;
25
+ }
26
+ catch {
27
+ // File doesn't exist, try next
28
+ }
29
+ }
30
+ return null;
31
+ }
32
+ /**
33
+ * Get the meta manifest file path.
34
+ * Returns path even if file doesn't exist yet.
35
+ */
36
+ export function getMetaManifestPath(ctx) {
37
+ return path.join(ctx.specDir, 'kynetic.meta.yaml');
38
+ }
39
+ /**
40
+ * Load meta items from a single file.
41
+ */
42
+ async function loadMetaFile(filePath) {
43
+ const result = {
44
+ agents: [],
45
+ workflows: [],
46
+ conventions: [],
47
+ observations: [],
48
+ };
49
+ try {
50
+ const raw = await readYamlFile(filePath);
51
+ if (!raw || typeof raw !== 'object') {
52
+ return result;
53
+ }
54
+ const obj = raw;
55
+ // Parse agents
56
+ if (Array.isArray(obj.agents)) {
57
+ for (const agent of obj.agents) {
58
+ const parsed = AgentSchema.safeParse(agent);
59
+ if (parsed.success) {
60
+ result.agents.push({ ...parsed.data, _sourceFile: filePath });
61
+ }
62
+ }
63
+ }
64
+ // Parse workflows
65
+ if (Array.isArray(obj.workflows)) {
66
+ for (const workflow of obj.workflows) {
67
+ const parsed = WorkflowSchema.safeParse(workflow);
68
+ if (parsed.success) {
69
+ result.workflows.push({ ...parsed.data, _sourceFile: filePath });
70
+ }
71
+ }
72
+ }
73
+ // Parse conventions
74
+ if (Array.isArray(obj.conventions)) {
75
+ for (const convention of obj.conventions) {
76
+ const parsed = ConventionSchema.safeParse(convention);
77
+ if (parsed.success) {
78
+ result.conventions.push({ ...parsed.data, _sourceFile: filePath });
79
+ }
80
+ }
81
+ }
82
+ // Parse observations
83
+ if (Array.isArray(obj.observations)) {
84
+ for (const observation of obj.observations) {
85
+ const parsed = ObservationSchema.safeParse(observation);
86
+ if (parsed.success) {
87
+ result.observations.push({ ...parsed.data, _sourceFile: filePath });
88
+ }
89
+ }
90
+ }
91
+ }
92
+ catch {
93
+ // File doesn't exist or parse error
94
+ }
95
+ return result;
96
+ }
97
+ /**
98
+ * Load the meta context from a kspec context.
99
+ * Loads meta manifest and follows includes.
100
+ */
101
+ export async function loadMetaContext(ctx) {
102
+ const result = {
103
+ manifest: null,
104
+ manifestPath: null,
105
+ agents: [],
106
+ workflows: [],
107
+ conventions: [],
108
+ observations: [],
109
+ };
110
+ const manifestPath = await findMetaManifest(ctx.specDir);
111
+ if (!manifestPath) {
112
+ return result;
113
+ }
114
+ result.manifestPath = manifestPath;
115
+ try {
116
+ const raw = await readYamlFile(manifestPath);
117
+ const parsed = MetaManifestSchema.safeParse(raw);
118
+ if (!parsed.success) {
119
+ // Invalid manifest, but we can still try to extract items
120
+ const items = await loadMetaFile(manifestPath);
121
+ result.agents.push(...items.agents);
122
+ result.workflows.push(...items.workflows);
123
+ result.conventions.push(...items.conventions);
124
+ result.observations.push(...items.observations);
125
+ return result;
126
+ }
127
+ result.manifest = parsed.data;
128
+ // Load items from manifest
129
+ const manifestItems = await loadMetaFile(manifestPath);
130
+ result.agents.push(...manifestItems.agents);
131
+ result.workflows.push(...manifestItems.workflows);
132
+ result.conventions.push(...manifestItems.conventions);
133
+ result.observations.push(...manifestItems.observations);
134
+ // Process includes
135
+ const includes = parsed.data.includes || [];
136
+ const manifestDir = path.dirname(manifestPath);
137
+ for (const include of includes) {
138
+ const expandedPaths = await expandIncludePattern(include, manifestDir);
139
+ for (const filePath of expandedPaths) {
140
+ const items = await loadMetaFile(filePath);
141
+ result.agents.push(...items.agents);
142
+ result.workflows.push(...items.workflows);
143
+ result.conventions.push(...items.conventions);
144
+ result.observations.push(...items.observations);
145
+ }
146
+ }
147
+ }
148
+ catch {
149
+ // Manifest exists but may be invalid
150
+ }
151
+ return result;
152
+ }
153
+ /**
154
+ * Get meta stats summary
155
+ */
156
+ export function getMetaStats(meta) {
157
+ return {
158
+ agents: meta.agents.length,
159
+ workflows: meta.workflows.length,
160
+ conventions: meta.conventions.length,
161
+ observations: meta.observations.length,
162
+ unresolvedObservations: meta.observations.filter((o) => !o.resolved).length,
163
+ };
164
+ }
165
+ /**
166
+ * Find a meta item by reference (ULID, short ULID, or id)
167
+ */
168
+ export function findMetaItemByRef(meta, ref) {
169
+ const cleanRef = ref.startsWith('@') ? ref.slice(1) : ref;
170
+ // Search all item types
171
+ const allItems = [
172
+ ...meta.agents,
173
+ ...meta.workflows,
174
+ ...meta.conventions,
175
+ ...meta.observations,
176
+ ];
177
+ for (const item of allItems) {
178
+ // Match full ULID
179
+ if (item._ulid === cleanRef)
180
+ return item;
181
+ // Match short ULID (prefix)
182
+ if (item._ulid.toLowerCase().startsWith(cleanRef.toLowerCase()))
183
+ return item;
184
+ // Match by id (for agents and workflows)
185
+ if ('id' in item && item.id === cleanRef)
186
+ return item;
187
+ // Match by domain (for conventions)
188
+ if ('domain' in item && item.domain === cleanRef)
189
+ return item;
190
+ }
191
+ return undefined;
192
+ }
193
+ /**
194
+ * Determine if an item is a meta item type
195
+ */
196
+ export function isMetaItemType(type) {
197
+ return ['agent', 'workflow', 'convention', 'observation'].includes(type);
198
+ }
199
+ // ============================================================
200
+ // META ITEM CRUD
201
+ // ============================================================
202
+ /**
203
+ * Save the entire meta manifest to file
204
+ */
205
+ async function saveMetaManifest(manifestPath, manifest) {
206
+ await writeYamlFilePreserveFormat(manifestPath, manifest);
207
+ }
208
+ /**
209
+ * Strip runtime metadata before serialization
210
+ */
211
+ function stripMetaMetadata(item) {
212
+ const { _sourceFile, ...cleanItem } = item;
213
+ return cleanItem;
214
+ }
215
+ /**
216
+ * Create a new observation
217
+ */
218
+ export function createObservation(type, content, options = {}) {
219
+ return {
220
+ _ulid: ulid(),
221
+ type,
222
+ content,
223
+ workflow_ref: options.workflow_ref,
224
+ created_at: new Date().toISOString(),
225
+ author: options.author ?? getAuthor(),
226
+ resolved: false,
227
+ resolution: null,
228
+ };
229
+ }
230
+ /**
231
+ * Save an observation to the meta manifest
232
+ */
233
+ export async function saveObservation(ctx, observation) {
234
+ const manifestPath = getMetaManifestPath(ctx);
235
+ // Ensure directory exists
236
+ const dir = path.dirname(manifestPath);
237
+ await fs.mkdir(dir, { recursive: true });
238
+ // Load existing manifest
239
+ let manifest = {
240
+ kynetic_meta: '1.0',
241
+ agents: [],
242
+ workflows: [],
243
+ conventions: [],
244
+ observations: [],
245
+ includes: [],
246
+ };
247
+ try {
248
+ const raw = await readYamlFile(manifestPath);
249
+ const parsed = MetaManifestSchema.safeParse(raw);
250
+ if (parsed.success) {
251
+ manifest = parsed.data;
252
+ }
253
+ }
254
+ catch {
255
+ // File doesn't exist, use defaults
256
+ }
257
+ // Strip runtime metadata
258
+ const cleanObs = stripMetaMetadata(observation);
259
+ // Update or add
260
+ const existingIndex = manifest.observations.findIndex((o) => o._ulid === observation._ulid);
261
+ if (existingIndex >= 0) {
262
+ manifest.observations[existingIndex] = cleanObs;
263
+ }
264
+ else {
265
+ manifest.observations.push(cleanObs);
266
+ }
267
+ await saveMetaManifest(manifestPath, manifest);
268
+ }
269
+ /**
270
+ * Delete an observation from the meta manifest
271
+ */
272
+ export async function deleteObservation(ctx, ulid) {
273
+ const manifestPath = getMetaManifestPath(ctx);
274
+ try {
275
+ const raw = await readYamlFile(manifestPath);
276
+ const parsed = MetaManifestSchema.safeParse(raw);
277
+ if (!parsed.success) {
278
+ return false;
279
+ }
280
+ const manifest = parsed.data;
281
+ const index = manifest.observations.findIndex((o) => o._ulid === ulid);
282
+ if (index < 0) {
283
+ return false;
284
+ }
285
+ manifest.observations.splice(index, 1);
286
+ await saveMetaManifest(manifestPath, manifest);
287
+ return true;
288
+ }
289
+ catch {
290
+ return false;
291
+ }
292
+ }
293
+ // Re-export the getMetaItemType function
294
+ export { getMetaItemType };
295
+ // ============================================================
296
+ // GENERIC META ITEM CRUD
297
+ // ============================================================
298
+ /**
299
+ * Save any meta item (agent, workflow, convention) to the manifest
300
+ */
301
+ export async function saveMetaItem(ctx, item, itemType) {
302
+ const manifestPath = getMetaManifestPath(ctx);
303
+ // Ensure directory exists
304
+ const dir = path.dirname(manifestPath);
305
+ await fs.mkdir(dir, { recursive: true });
306
+ // Load existing manifest
307
+ let manifest = {
308
+ kynetic_meta: '1.0',
309
+ agents: [],
310
+ workflows: [],
311
+ conventions: [],
312
+ observations: [],
313
+ includes: [],
314
+ };
315
+ try {
316
+ const raw = await readYamlFile(manifestPath);
317
+ const parsed = MetaManifestSchema.safeParse(raw);
318
+ if (parsed.success) {
319
+ manifest = parsed.data;
320
+ }
321
+ }
322
+ catch {
323
+ // File doesn't exist, use defaults
324
+ }
325
+ // Strip runtime metadata
326
+ const cleanItem = stripMetaMetadata(item);
327
+ // Get the appropriate array
328
+ const getArray = () => {
329
+ switch (itemType) {
330
+ case 'agent':
331
+ return manifest.agents;
332
+ case 'workflow':
333
+ return manifest.workflows;
334
+ case 'convention':
335
+ return manifest.conventions;
336
+ }
337
+ };
338
+ const array = getArray();
339
+ // Update or add
340
+ const existingIndex = array.findIndex((i) => i._ulid === item._ulid);
341
+ if (existingIndex >= 0) {
342
+ array[existingIndex] = cleanItem;
343
+ }
344
+ else {
345
+ array.push(cleanItem);
346
+ }
347
+ await saveMetaManifest(manifestPath, manifest);
348
+ }
349
+ /**
350
+ * Delete any meta item from the manifest
351
+ */
352
+ export async function deleteMetaItem(ctx, itemUlid, itemType) {
353
+ const manifestPath = getMetaManifestPath(ctx);
354
+ try {
355
+ const raw = await readYamlFile(manifestPath);
356
+ const parsed = MetaManifestSchema.safeParse(raw);
357
+ if (!parsed.success) {
358
+ return false;
359
+ }
360
+ const manifest = parsed.data;
361
+ const getArray = () => {
362
+ switch (itemType) {
363
+ case 'agent':
364
+ return manifest.agents;
365
+ case 'workflow':
366
+ return manifest.workflows;
367
+ case 'convention':
368
+ return manifest.conventions;
369
+ case 'observation':
370
+ return manifest.observations;
371
+ }
372
+ };
373
+ const array = getArray();
374
+ const index = array.findIndex((i) => i._ulid === itemUlid);
375
+ if (index < 0) {
376
+ return false;
377
+ }
378
+ array.splice(index, 1);
379
+ await saveMetaManifest(manifestPath, manifest);
380
+ return true;
381
+ }
382
+ catch {
383
+ return false;
384
+ }
385
+ }
386
+ // ============================================================
387
+ // SESSION CONTEXT
388
+ // ============================================================
389
+ /**
390
+ * Get the session context file path
391
+ */
392
+ export function getSessionContextPath(ctx) {
393
+ return path.join(ctx.specDir, '.kspec-session');
394
+ }
395
+ /**
396
+ * Load session context (or return empty context if not exists)
397
+ */
398
+ export async function loadSessionContext(ctx) {
399
+ const contextPath = getSessionContextPath(ctx);
400
+ try {
401
+ const raw = await readYamlFile(contextPath);
402
+ if (!raw || typeof raw !== 'object') {
403
+ return {
404
+ focus: null,
405
+ threads: [],
406
+ open_questions: [],
407
+ updated_at: new Date().toISOString(),
408
+ };
409
+ }
410
+ // Validate and parse using schema
411
+ const result = SessionContextSchema.safeParse(raw);
412
+ if (result.success) {
413
+ return result.data;
414
+ }
415
+ // If validation fails, return empty context
416
+ return {
417
+ focus: null,
418
+ threads: [],
419
+ open_questions: [],
420
+ updated_at: new Date().toISOString(),
421
+ };
422
+ }
423
+ catch {
424
+ return {
425
+ focus: null,
426
+ threads: [],
427
+ open_questions: [],
428
+ updated_at: new Date().toISOString(),
429
+ };
430
+ }
431
+ }
432
+ /**
433
+ * Save session context
434
+ */
435
+ export async function saveSessionContext(ctx, context) {
436
+ const contextPath = getSessionContextPath(ctx);
437
+ // Update timestamp
438
+ context.updated_at = new Date().toISOString();
439
+ await writeYamlFilePreserveFormat(contextPath, context);
440
+ }
441
+ //# sourceMappingURL=meta.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"meta.js","sourceRoot":"","sources":["../../src/parser/meta.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,185 @@
1
+ /**
2
+ * Reference resolution system for @references.
3
+ *
4
+ * Handles resolution of @slug and @ulid references to actual items,
5
+ * with proper error handling for not-found and ambiguous cases.
6
+ */
7
+ import type { LoadedSpecItem, LoadedTask, AnyLoadedItem } from './yaml.js';
8
+ import type { LoadedMetaItem } from './meta.js';
9
+ /**
10
+ * Successful resolution result
11
+ * AC: @agent-definitions ac-agent-3
12
+ */
13
+ export interface ResolveSuccess {
14
+ ok: true;
15
+ ulid: string;
16
+ item: AnyLoadedItem | LoadedMetaItem;
17
+ /** How the reference was matched */
18
+ matchType: 'slug' | 'ulid-full' | 'ulid-prefix';
19
+ }
20
+ /**
21
+ * Failed resolution - reference not found
22
+ */
23
+ export interface ResolveNotFound {
24
+ ok: false;
25
+ error: 'not_found';
26
+ ref: string;
27
+ }
28
+ /**
29
+ * Failed resolution - ambiguous ULID prefix
30
+ */
31
+ export interface ResolveAmbiguous {
32
+ ok: false;
33
+ error: 'ambiguous';
34
+ ref: string;
35
+ /** The matching ULIDs */
36
+ candidates: string[];
37
+ }
38
+ /**
39
+ * Failed resolution - duplicate slug
40
+ */
41
+ export interface ResolveDuplicateSlug {
42
+ ok: false;
43
+ error: 'duplicate_slug';
44
+ ref: string;
45
+ /** The ULIDs that share this slug */
46
+ candidates: string[];
47
+ }
48
+ export type ResolveResult = ResolveSuccess | ResolveNotFound | ResolveAmbiguous | ResolveDuplicateSlug;
49
+ /**
50
+ * Validation error for a single reference
51
+ */
52
+ export interface RefValidationError {
53
+ /** The reference string that failed */
54
+ ref: string;
55
+ /** Where this reference was found */
56
+ sourceFile?: string;
57
+ /** The item containing this reference */
58
+ sourceUlid?: string;
59
+ /** The field containing this reference */
60
+ field: string;
61
+ /** Error type */
62
+ error: 'not_found' | 'ambiguous' | 'duplicate_slug';
63
+ /** Additional context */
64
+ message: string;
65
+ }
66
+ /**
67
+ * Validation warning for a single reference
68
+ */
69
+ export interface RefValidationWarning {
70
+ /** The reference string */
71
+ ref: string;
72
+ /** Where this reference was found */
73
+ sourceFile?: string;
74
+ /** The item containing this reference */
75
+ sourceUlid?: string;
76
+ /** The field containing this reference */
77
+ field: string;
78
+ /** Warning type */
79
+ warning: 'deprecated_target';
80
+ /** Additional context */
81
+ message: string;
82
+ }
83
+ /**
84
+ * Index for efficient reference resolution.
85
+ * Build once when loading the spec, then resolve many times.
86
+ * AC: @agent-definitions ac-agent-3
87
+ */
88
+ export declare class ReferenceIndex {
89
+ /** slug → ULID mapping */
90
+ private slugIndex;
91
+ /** ULID → item mapping */
92
+ private ulidIndex;
93
+ /** All ULIDs for prefix matching */
94
+ private allUlids;
95
+ /**
96
+ * Build index from loaded items and meta items
97
+ * AC: @agent-definitions ac-agent-3
98
+ */
99
+ constructor(tasks: LoadedTask[], items: LoadedSpecItem[], metaItems?: LoadedMetaItem[]);
100
+ private indexItem;
101
+ /**
102
+ * Index a meta item (agent, workflow, convention, observation)
103
+ * Meta items use 'id' field as their slug
104
+ * AC: @agent-definitions ac-agent-3
105
+ */
106
+ private indexMetaItem;
107
+ /**
108
+ * Resolve a reference to an item.
109
+ *
110
+ * Resolution order:
111
+ * 1. Exact slug match
112
+ * 2. Full ULID match
113
+ * 3. ULID prefix match (must be unique)
114
+ */
115
+ resolve(ref: string): ResolveResult;
116
+ /**
117
+ * Get an item by exact ULID (no resolution, direct lookup)
118
+ */
119
+ getByUlid(ulid: string): AnyLoadedItem | LoadedMetaItem | undefined;
120
+ /**
121
+ * Get the minimum unique prefix for a ULID.
122
+ * Returns the shortest prefix that uniquely identifies this ULID
123
+ * among all indexed items.
124
+ *
125
+ * @param ulid The full ULID to shorten
126
+ * @param minLength Minimum prefix length (default 8)
127
+ * @returns Shortest unique prefix
128
+ */
129
+ shortUlid(ulid: string, minLength?: number): string;
130
+ /**
131
+ * Get all indexed ULIDs
132
+ */
133
+ getAllUlids(): string[];
134
+ /**
135
+ * Get all slugs and their mappings
136
+ */
137
+ getAllSlugs(): Map<string, string[]>;
138
+ /**
139
+ * Check if a slug exists
140
+ */
141
+ hasSlug(slug: string): boolean;
142
+ /**
143
+ * Get count of indexed items
144
+ */
145
+ get size(): number;
146
+ }
147
+ /**
148
+ * Validation result with errors and warnings
149
+ */
150
+ export interface RefValidationResult {
151
+ errors: RefValidationError[];
152
+ warnings: RefValidationWarning[];
153
+ }
154
+ /**
155
+ * Validate all references in the spec.
156
+ * Returns list of validation errors and warnings.
157
+ */
158
+ export declare function validateRefs(index: ReferenceIndex, tasks: LoadedTask[], items: LoadedSpecItem[]): RefValidationResult;
159
+ /**
160
+ * Find duplicate slugs in the index.
161
+ * Returns map of slug → ULIDs for slugs with multiple items.
162
+ */
163
+ export declare function findDuplicateSlugs(index: ReferenceIndex): Map<string, string[]>;
164
+ /**
165
+ * Result of checking slug uniqueness
166
+ */
167
+ export interface SlugCheckSuccess {
168
+ ok: true;
169
+ }
170
+ export interface SlugCheckConflict {
171
+ ok: false;
172
+ slug: string;
173
+ existingUlid: string;
174
+ }
175
+ export type SlugCheckResult = SlugCheckSuccess | SlugCheckConflict;
176
+ /**
177
+ * Check if proposed slugs are unique (don't conflict with existing items).
178
+ *
179
+ * @param index The reference index to check against
180
+ * @param slugs Array of proposed slugs to check
181
+ * @param excludeUlid Optional ULID to exclude from conflict check (for updates)
182
+ * @returns Success if all slugs are available, or conflict info if one exists
183
+ */
184
+ export declare function checkSlugUniqueness(index: ReferenceIndex, slugs: string[], excludeUlid?: string): SlugCheckResult;
185
+ //# sourceMappingURL=refs.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../../src/parser/refs.ts"],"names":[],"mappings":"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"}