@arcforge/platform 2.0.166

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 (207) hide show
  1. package/README.md +31 -0
  2. package/package.json +69 -0
  3. package/src/bin/supervisor.ts +102 -0
  4. package/src/bin/test-api.ts +30 -0
  5. package/src/bin/test-preload.ts +308 -0
  6. package/src/bin/update-helper.ts +32 -0
  7. package/src/build/bench/CLAUDE.md +106 -0
  8. package/src/build/bench/SPEC.md +209 -0
  9. package/src/build/bench/agents.ts +105 -0
  10. package/src/build/bench/axes.ts +84 -0
  11. package/src/build/bench/bench.ts +96 -0
  12. package/src/build/bench/discover.ts +147 -0
  13. package/src/build/bench/index.ts +7 -0
  14. package/src/build/bench/log.ts +47 -0
  15. package/src/build/bench/matrix.ts +23 -0
  16. package/src/build/bench/preload.ts +440 -0
  17. package/src/build/bench/prepare.ts +61 -0
  18. package/src/build/bench/projection.ts +112 -0
  19. package/src/build/bench/resolve.ts +54 -0
  20. package/src/build/bench/runner.ts +309 -0
  21. package/src/build/bench/schema/extract.ts +148 -0
  22. package/src/build/bench/schema/index.ts +2 -0
  23. package/src/build/bench/schema/schema.ts +95 -0
  24. package/src/build/bench/schema/worker.ts +30 -0
  25. package/src/build/bench/typegen.ts +119 -0
  26. package/src/build/bench/workspace/files.ts +139 -0
  27. package/src/build/bench/workspace/handle.ts +133 -0
  28. package/src/build/bench/workspace/index.ts +11 -0
  29. package/src/build/bench/workspace/workspace.ts +14 -0
  30. package/src/build/blueprint/blueprint.ts +398 -0
  31. package/src/build/blueprint/cognet/abi.ts +207 -0
  32. package/src/build/blueprint/cognet/bundle-worker.ts +93 -0
  33. package/src/build/blueprint/cognet/bundle.ts +664 -0
  34. package/src/build/blueprint/cognet/cognet.ts +249 -0
  35. package/src/build/blueprint/cognet/index.ts +10 -0
  36. package/src/build/blueprint/cognet/manifest.ts +38 -0
  37. package/src/build/blueprint/cognet/resolve.ts +113 -0
  38. package/src/build/blueprint/collisions.ts +51 -0
  39. package/src/build/blueprint/index.ts +29 -0
  40. package/src/build/blueprint/modules/entries.ts +117 -0
  41. package/src/build/blueprint/modules/index.ts +300 -0
  42. package/src/build/blueprint/modules/meta.ts +174 -0
  43. package/src/build/blueprint/scan/boot.ts +34 -0
  44. package/src/build/blueprint/scan/cognetImports.ts +56 -0
  45. package/src/build/blueprint/scan/components.ts +45 -0
  46. package/src/build/blueprint/scan/config.ts +234 -0
  47. package/src/build/blueprint/scan/configImports.ts +232 -0
  48. package/src/build/blueprint/scan/declare-worker.ts +61 -0
  49. package/src/build/blueprint/scan/declare.ts +393 -0
  50. package/src/build/blueprint/scan/h3-globals.ts +137 -0
  51. package/src/build/blueprint/scan/knowledge.ts +101 -0
  52. package/src/build/blueprint/scan/middleware.ts +110 -0
  53. package/src/build/blueprint/scan/moduleImports.ts +79 -0
  54. package/src/build/blueprint/scan/plugins.ts +93 -0
  55. package/src/build/blueprint/scan/promptPackages.ts +45 -0
  56. package/src/build/blueprint/scan/prompts.ts +164 -0
  57. package/src/build/blueprint/scan/published.ts +131 -0
  58. package/src/build/blueprint/scan/resolve.ts +398 -0
  59. package/src/build/blueprint/scan/routes.ts +109 -0
  60. package/src/build/blueprint/scan/scripts.ts +119 -0
  61. package/src/build/blueprint/scan/tool-bundle-worker.ts +69 -0
  62. package/src/build/blueprint/scan/tools.ts +610 -0
  63. package/src/build/blueprint/types.ts +28 -0
  64. package/src/build/extensions/config.ts +261 -0
  65. package/src/build/extensions/edit.ts +684 -0
  66. package/src/build/extensions/extensions.ts +731 -0
  67. package/src/build/extensions/index.ts +10 -0
  68. package/src/build/extensions/load.ts +350 -0
  69. package/src/build/extensions/registrations.ts +189 -0
  70. package/src/build/extensions/store.ts +200 -0
  71. package/src/build/frame/frame.ts +145 -0
  72. package/src/build/frame/index.ts +5 -0
  73. package/src/build/frame/migrate.ts +246 -0
  74. package/src/build/project/bundle/agent.ts +382 -0
  75. package/src/build/project/bundle/artifacts.ts +88 -0
  76. package/src/build/project/bundle/assets.ts +385 -0
  77. package/src/build/project/bundle/bundle.ts +160 -0
  78. package/src/build/project/bundle/imports.ts +102 -0
  79. package/src/build/project/bundle/index.ts +16 -0
  80. package/src/build/project/bundle/module.ts +130 -0
  81. package/src/build/project/bundle/source.ts +136 -0
  82. package/src/build/project/bundle/stage.ts +97 -0
  83. package/src/build/project/bundle/types.ts +111 -0
  84. package/src/build/project/cognet.ts +156 -0
  85. package/src/build/project/create/agent.ts +52 -0
  86. package/src/build/project/create/bench.ts +81 -0
  87. package/src/build/project/create/cognet.ts +102 -0
  88. package/src/build/project/create/extension.ts +63 -0
  89. package/src/build/project/create/module.ts +43 -0
  90. package/src/build/project/create/profile.ts +102 -0
  91. package/src/build/project/create/prompt.ts +68 -0
  92. package/src/build/project/create/templates.ts +88 -0
  93. package/src/build/project/deploy.ts +96 -0
  94. package/src/build/project/index.ts +40 -0
  95. package/src/build/project/installer.ts +616 -0
  96. package/src/build/project/kinds.ts +374 -0
  97. package/src/build/project/links.ts +33 -0
  98. package/src/build/project/manifest/bunfig.ts +139 -0
  99. package/src/build/project/manifest/config.ts +246 -0
  100. package/src/build/project/manifest/env.ts +184 -0
  101. package/src/build/project/manifest/index.ts +9 -0
  102. package/src/build/project/manifest/manifest.ts +49 -0
  103. package/src/build/project/manifest/model.ts +124 -0
  104. package/src/build/project/manifest/package.ts +386 -0
  105. package/src/build/project/manifest/text.ts +19 -0
  106. package/src/build/project/models/fetch.ts +123 -0
  107. package/src/build/project/models/index.ts +8 -0
  108. package/src/build/project/models/models.ts +111 -0
  109. package/src/build/project/models/specifier.ts +106 -0
  110. package/src/build/project/models/store.ts +202 -0
  111. package/src/build/project/modules/hash.ts +31 -0
  112. package/src/build/project/modules/index.ts +5 -0
  113. package/src/build/project/modules/lock.ts +78 -0
  114. package/src/build/project/modules/modules.ts +155 -0
  115. package/src/build/project/prepare.ts +709 -0
  116. package/src/build/project/project.ts +253 -0
  117. package/src/build/project/projects.ts +164 -0
  118. package/src/build/project/propagation.ts +120 -0
  119. package/src/build/project/publish/verify.ts +312 -0
  120. package/src/build/project/publish.ts +155 -0
  121. package/src/build/project/reconcile.ts +93 -0
  122. package/src/build/project/specifier.ts +42 -0
  123. package/src/build/project/tree.ts +615 -0
  124. package/src/build/project/treecache.ts +356 -0
  125. package/src/build/project/typegen/axon-dts.ts +362 -0
  126. package/src/build/project/typegen/cognet-dts.ts +91 -0
  127. package/src/build/project/typegen/components.ts +45 -0
  128. package/src/build/project/typegen/env.ts +59 -0
  129. package/src/build/project/typegen/generators.ts +108 -0
  130. package/src/build/project/typegen/hooks.ts +71 -0
  131. package/src/build/project/typegen/index.ts +137 -0
  132. package/src/build/project/typegen/prompt-dts.ts +40 -0
  133. package/src/build/project/typegen/prompts.ts +36 -0
  134. package/src/build/project/typegen/registry-dts.ts +109 -0
  135. package/src/build/project/typegen/scripts.ts +37 -0
  136. package/src/build/project/typegen/tools.ts +31 -0
  137. package/src/build/project/typegen/tsconfig.ts +243 -0
  138. package/src/build/project/typegen/tui-dts.ts +120 -0
  139. package/src/build/project/typegen/write.ts +40 -0
  140. package/src/build/project/verify.ts +268 -0
  141. package/src/build/project/watcher.ts +266 -0
  142. package/src/build/runtime/agent.ts +550 -0
  143. package/src/build/runtime/escalations.ts +159 -0
  144. package/src/build/runtime/index.ts +15 -0
  145. package/src/build/runtime/instances.ts +604 -0
  146. package/src/build/runtime/profile.ts +91 -0
  147. package/src/build/runtime/progress.ts +143 -0
  148. package/src/build/runtime/requests.ts +167 -0
  149. package/src/build/runtime/resolve.ts +159 -0
  150. package/src/build/runtime/runtime.ts +233 -0
  151. package/src/build/runtime/sessions/index.ts +5 -0
  152. package/src/build/runtime/sessions/record.ts +145 -0
  153. package/src/build/runtime/sessions/sessions.ts +240 -0
  154. package/src/build/runtime/zeno.ts +120 -0
  155. package/src/index.ts +11 -0
  156. package/src/link/agent-main.ts +395 -0
  157. package/src/link/index.ts +70 -0
  158. package/src/link/services.ts +120 -0
  159. package/src/platform.ts +293 -0
  160. package/src/procs/index.ts +15 -0
  161. package/src/procs/tree.ts +177 -0
  162. package/src/services/cloud.ts +419 -0
  163. package/src/services/control/client.ts +126 -0
  164. package/src/services/control/dispatch.ts +156 -0
  165. package/src/services/control/index.ts +17 -0
  166. package/src/services/control/protocol.ts +179 -0
  167. package/src/services/control/server.ts +241 -0
  168. package/src/services/deployments.ts +81 -0
  169. package/src/services/files.ts +329 -0
  170. package/src/services/index.ts +5 -0
  171. package/src/services/mic/capture.ts +248 -0
  172. package/src/services/mic/config.ts +109 -0
  173. package/src/services/mic/fft.ts +93 -0
  174. package/src/services/mic/index.ts +139 -0
  175. package/src/services/mic/visualizer.ts +46 -0
  176. package/src/services/ollama/catalog.ts +122 -0
  177. package/src/services/ollama/http.ts +124 -0
  178. package/src/services/ollama/index.ts +13 -0
  179. package/src/services/ollama/models.ts +153 -0
  180. package/src/services/ollama/ollama.ts +89 -0
  181. package/src/services/ollama/registry.ts +112 -0
  182. package/src/services/ollama/types.ts +72 -0
  183. package/src/services/prompts.ts +76 -0
  184. package/src/services/registry.ts +220 -0
  185. package/src/services/resources/hardware.ts +125 -0
  186. package/src/services/resources/index.ts +6 -0
  187. package/src/services/resources/reservations.ts +162 -0
  188. package/src/services/resources/resources.ts +156 -0
  189. package/src/services/running/index.ts +1 -0
  190. package/src/services/running/running.ts +200 -0
  191. package/src/services/store/disk.ts +97 -0
  192. package/src/services/store/index.ts +15 -0
  193. package/src/services/store/store.ts +729 -0
  194. package/src/services/store/types.ts +303 -0
  195. package/src/services/test/child.ts +150 -0
  196. package/src/services/test/events.ts +102 -0
  197. package/src/services/test/files.ts +26 -0
  198. package/src/services/test/frames.ts +39 -0
  199. package/src/services/test/index.ts +7 -0
  200. package/src/services/test/runner.ts +122 -0
  201. package/src/services/test/types.ts +26 -0
  202. package/src/services/update/contract.ts +77 -0
  203. package/src/services/update/index.ts +12 -0
  204. package/src/services/update/installer.ts +139 -0
  205. package/src/services/update/updates.ts +137 -0
  206. package/src/utils/fs.ts +148 -0
  207. package/src/utils/tsast.ts +102 -0
@@ -0,0 +1,684 @@
1
+ import ts from "typescript"
2
+ import { readFile, writeFile } from "node:fs/promises"
3
+ import { join } from "node:path"
4
+ import { err } from "@arcforge/err"
5
+ import { fsx } from "../../utils/fs"
6
+ import { tsast } from "../../utils/tsast"
7
+ import { parseRef } from "./store"
8
+
9
+ /**
10
+ * Surgical edits to `profile.config.ts` — adding and removing entries in its
11
+ * `extensions` array.
12
+ *
13
+ * ── Why an AST edit rather than a rewrite ───────────────────────────────────
14
+ *
15
+ * This is the user's own file. It may carry comments, an entry disabled with
16
+ * `enabled: false`, an ordering they chose deliberately (load order IS the
17
+ * collision policy), and whatever else they wrote around it. Regenerating it
18
+ * from a parsed model would silently discard all of that, so the array's
19
+ * contents are located in the source and the surrounding text is left byte-for-
20
+ * byte identical.
21
+ *
22
+ * The same reasoning as `manifest/engine.ts`, which edits `axon.config.ts` in
23
+ * place rather than re-emitting it — and the property that made a declarative
24
+ * `extensions:` array the right choice over Vim-style imperative registration:
25
+ * a list a machine can edit.
26
+ *
27
+ * ── Failing loudly is the point ─────────────────────────────────────────────
28
+ *
29
+ * A config this cannot parse is NOT edited. There is no fallback that appends
30
+ * text hopefully, because a botched write damages a file the user wrote by
31
+ * hand — the error names the file and asks them to add the line themselves,
32
+ * which is a worse experience than it working and a far better one than a
33
+ * corrupted config.
34
+ */
35
+
36
+ /** Where the `extensions: [...]` array lives in a profile config's source. */
37
+ type Located = {
38
+ array: ts.ArrayLiteralExpression
39
+ source: ts.SourceFile
40
+ text: string
41
+ }
42
+
43
+ const CONFIG = "profile.config.ts"
44
+
45
+ function configPath(profileRoot: string): string {
46
+ return join(profileRoot, CONFIG)
47
+ }
48
+
49
+ /**
50
+ * Find `defineProfile({ extensions: [...] })`.
51
+ *
52
+ * Located by shape rather than by position: the call may be assigned, exported
53
+ * directly, or wrapped, and only the argument object matters.
54
+ */
55
+ function locate(path: string, text: string, field = "extensions"): Located | null {
56
+ const source = tsast.parse(path, text)
57
+ let found: ts.ArrayLiteralExpression | null = null
58
+
59
+ const visit = (node: ts.Node): void => {
60
+ if (found) return
61
+ if (
62
+ ts.isCallExpression(node)
63
+ && ts.isIdentifier(node.expression)
64
+ && node.expression.text === "defineProfile"
65
+ && node.arguments.length > 0
66
+ ) {
67
+ const arg = node.arguments[0]
68
+ if (arg && ts.isObjectLiteralExpression(arg)) {
69
+ const value = tsast.prop(arg, field)
70
+ if (value && ts.isArrayLiteralExpression(value)) {
71
+ found = value
72
+ return
73
+ }
74
+ }
75
+ }
76
+ ts.forEachChild(node, visit)
77
+ }
78
+ visit(source)
79
+
80
+ return found ? { array: found, source, text } : null
81
+ }
82
+
83
+ /**
84
+ * The `defineProfile({ ... })` object itself, for a field that may be absent.
85
+ *
86
+ * `locate()` answers "where is this array" and returns null when the field is
87
+ * not declared at all — which is the right answer for reading, and the wrong
88
+ * one for a write that should CREATE the field. Connecting a provider on a
89
+ * profile that has never named one has to work.
90
+ */
91
+ function locateObject(path: string, text: string): { object: ts.ObjectLiteralExpression; source: ts.SourceFile } | null {
92
+ const source = tsast.parse(path, text)
93
+ let found: ts.ObjectLiteralExpression | null = null
94
+
95
+ tsast.visitCalls(source, "defineProfile", call => {
96
+ if (found) return
97
+ const arg = call.arguments[0]
98
+ if (arg && ts.isObjectLiteralExpression(arg)) found = arg
99
+ })
100
+
101
+ return found ? { object: found, source } : null
102
+ }
103
+
104
+ /** The `source` string of one entry — a bare string, or the `source:` of an object form. */
105
+ function sourceOf(element: ts.Expression): string | null {
106
+ if (ts.isStringLiteralLike(element)) return element.text
107
+ if (ts.isObjectLiteralExpression(element)) {
108
+ const value = tsast.prop(element, "source")
109
+ return value && ts.isStringLiteralLike(value) ? value.text : null
110
+ }
111
+ return null
112
+ }
113
+
114
+ /** Read the enabled extension sources a config declares, in order. */
115
+ export async function readEntries(profileRoot: string): Promise<string[]> {
116
+ const path = configPath(profileRoot)
117
+ if (!fsx.exists(path)) return []
118
+
119
+ const located = locate(path, await readFile(path, "utf-8"))
120
+ if (!located) return []
121
+
122
+ return located.array.elements
123
+ .map(sourceOf)
124
+ .filter((s): s is string => s !== null)
125
+ }
126
+
127
+ export type EditResult = {
128
+ /** False when the entry was already in the state asked for — nothing was written. */
129
+ changed: boolean
130
+ }
131
+
132
+ /**
133
+ * Add an entry to `extensions`, if it is not already there.
134
+ *
135
+ * Appended rather than inserted: the array is load order, and load order
136
+ * decides collisions, so a new extension goes last — where it loses to
137
+ * everything already installed rather than silently displacing it.
138
+ */
139
+ export async function addEntry(profileRoot: string, source: string): Promise<EditResult> {
140
+ const path = configPath(profileRoot)
141
+ if (!fsx.exists(path)) {
142
+ throw err("PROFILE_CONFIG_MISSING", { detail: path, context: { path } })
143
+ }
144
+
145
+ const text = await readFile(path, "utf-8")
146
+ const located = locate(path, text)
147
+ if (!located) {
148
+ throw err("PROFILE_CONFIG_UNEDITABLE", {
149
+ detail: `could not find an "extensions: [ ... ]" array in ${path}`,
150
+ context: { path, source },
151
+ })
152
+ }
153
+
154
+ const existing = located.array.elements.map(sourceOf)
155
+ if (existing.includes(source)) return { changed: false }
156
+
157
+ // Same extension at a DIFFERENT version replaces it, rather than joining
158
+ // it in the list.
159
+ //
160
+ // Installs pin the resolved version, so re-installing after a publish
161
+ // produces a new ref ("@cody/theme@0.1.2" where the config holds
162
+ // "@cody/theme@0.1.1"). A plain string dedupe sees two different entries
163
+ // and keeps both — which loads the extension twice, and every collision
164
+ // between the two copies resolves against whichever came first. One
165
+ // extension, one entry.
166
+ const { name } = parseRef(source)
167
+ const conflicting = existing.find(entry => entry !== null && parseRef(entry).name === name)
168
+ if (conflicting !== undefined && conflicting !== null) {
169
+ await removeEntry(profileRoot, conflicting)
170
+ // Re-read: the removal moved every offset this function had computed.
171
+ return addEntry(profileRoot, source)
172
+ }
173
+
174
+ const entry = `"${source}"`
175
+ const elements = located.array.elements
176
+
177
+ // Indentation is copied from whatever is already there, so an edit is
178
+ // invisible in a diff beside the user's own formatting. A first entry has
179
+ // nothing to copy, so it takes the array's own line plus one level.
180
+ const last = elements[elements.length - 1]
181
+ const arrayStart = located.array.getStart(located.source)
182
+
183
+ let next: string
184
+ if (last) {
185
+ // Insert AFTER the previous element's trailing comma when it has one.
186
+ // Inserting before it produced `"a"\n "b",,` — caught by verified()
187
+ // rather than written, which is what that check is for.
188
+ const trailing = text.slice(last.getEnd()).match(/^\s*,/)
189
+ const insertAt = last.getEnd() + (trailing ? trailing[0].length : 0)
190
+ const indent = " ".repeat(indentOf(text, last.getStart(located.source)))
191
+
192
+ next = text.slice(0, insertAt) + `${trailing ? "" : ","}\n${indent}${entry},` + text.slice(insertAt)
193
+ } else {
194
+ // An empty array: open a line inside it, and close on the array's own
195
+ // indentation so the `]` lands where the user would have put it.
196
+ const indent = " ".repeat(indentOf(text, arrayStart) + 4)
197
+ const closing = " ".repeat(indentOf(text, arrayStart))
198
+ next = text.slice(0, arrayStart + 1) + `\n${indent}${entry},\n${closing}` + text.slice(arrayStart + 1)
199
+ }
200
+
201
+ await writeFile(path, verified(next, path))
202
+
203
+ return { changed: true }
204
+ }
205
+
206
+ /**
207
+ * Remove an entry from `extensions`, if it is there.
208
+ *
209
+ * The whole element goes, including an object form carrying `enabled: false` —
210
+ * uninstalling is not the same as disabling, and leaving a disabled husk behind
211
+ * would make `axon ext list` show something that is not installed.
212
+ */
213
+ export async function removeEntry(profileRoot: string, source: string): Promise<EditResult> {
214
+ const path = configPath(profileRoot)
215
+ if (!fsx.exists(path)) return { changed: false }
216
+
217
+ const text = await readFile(path, "utf-8")
218
+ const located = locate(path, text)
219
+ if (!located) {
220
+ throw err("PROFILE_CONFIG_UNEDITABLE", {
221
+ detail: `could not find an "extensions: [ ... ]" array in ${path}`,
222
+ context: { path, source },
223
+ })
224
+ }
225
+
226
+ const target = located.array.elements.find(element => sourceOf(element) === source)
227
+ if (!target) return { changed: false }
228
+
229
+ // Take the element, its trailing comma, and the whitespace BEFORE it —
230
+ // getFullStart() includes that leading trivia, which is the newline and
231
+ // indent the element sits on.
232
+ const start = target.getFullStart()
233
+ const after = text.slice(target.getEnd())
234
+ const comma = after.match(/^[^\S\n]*,/)
235
+ let end = target.getEnd() + (comma ? comma[0].length : 0)
236
+
237
+ // Removing the LAST element leaves the array's own closing line preceded by
238
+ // the indent that used to belong to an entry — `[\n ]` rather than `[]`.
239
+ // Each removal adds one such line, so a user who installs and uninstalls a
240
+ // few times ends up with a stack of blank lines inside the brackets. It
241
+ // parses, which is why the parse-before-write check never caught it, and it
242
+ // is still wrong in a file whose whole purpose is being opened and edited.
243
+ //
244
+ // Only when the array is now EMPTY: with entries left, the whitespace
245
+ // between them is the formatting the user (or addEntry) chose, and
246
+ // rewriting it would reformat lines nobody touched.
247
+ let next = text.slice(0, start) + text.slice(end)
248
+ if (located.array.elements.length === 1) {
249
+ next = next.replace(/\[\s*\]/, "[]")
250
+ }
251
+ await writeFile(path, verified(next, path))
252
+
253
+ return { changed: true }
254
+ }
255
+
256
+ /** Columns of indentation on the line containing `offset`. */
257
+ function indentOf(text: string, offset: number): number {
258
+ const lineStart = text.lastIndexOf("\n", offset - 1) + 1
259
+ const line = text.slice(lineStart, offset)
260
+ const match = line.match(/^\s*/)
261
+ return match ? match[0].length : 0
262
+ }
263
+
264
+ /**
265
+ * Parse the result before it is written.
266
+ *
267
+ * A write that produced a syntactically broken config would take the user's
268
+ * whole TUI config down — every command, key and palette — for an install. The
269
+ * edits above are careful, but "careful" is not a guarantee and this is: a
270
+ * result that does not parse is never written.
271
+ */
272
+ function verified(next: string, path: string): string {
273
+ const parsed = ts.createSourceFile(path, next, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
274
+ // `parseDiagnostics` is not on the public type but is populated by the
275
+ // parser; an empty list is the only acceptable outcome here.
276
+ const diagnostics = (parsed as unknown as { parseDiagnostics?: readonly unknown[] }).parseDiagnostics ?? []
277
+ if (diagnostics.length > 0) {
278
+ throw err("PROFILE_CONFIG_UNEDITABLE", {
279
+ detail: `editing ${path} would have produced invalid TypeScript — the file was left unchanged`,
280
+ context: { path },
281
+ })
282
+ }
283
+ return next
284
+ }
285
+
286
+
287
+ // ── Settings ─────────────────────────────────────────────────────────────────
288
+
289
+ /**
290
+ * Find the object literal `defineProfile()` was called with.
291
+ *
292
+ * Separate from `locate()` above, which narrows straight to the `extensions`
293
+ * array. Settings live on a sibling key that may not exist yet, so this needs
294
+ * the whole argument to write into.
295
+ */
296
+ function locateConfig(path: string, text: string): { object: ts.ObjectLiteralExpression; source: ts.SourceFile } | null {
297
+ const source = tsast.parse(path, text)
298
+ let found: ts.ObjectLiteralExpression | null = null
299
+
300
+ const visit = (node: ts.Node): void => {
301
+ if (found) return
302
+ if (
303
+ ts.isCallExpression(node)
304
+ && ts.isIdentifier(node.expression)
305
+ && node.expression.text === "defineProfile"
306
+ && node.arguments.length > 0
307
+ ) {
308
+ const arg = node.arguments[0]
309
+ if (arg && ts.isObjectLiteralExpression(arg)) {
310
+ found = arg
311
+ return
312
+ }
313
+ }
314
+ ts.forEachChild(node, visit)
315
+ }
316
+ visit(source)
317
+
318
+ return found ? { object: found, source } : null
319
+ }
320
+
321
+ /** Read the `settings` object a config declares, as plain data. */
322
+ export async function readSettings(profileRoot: string): Promise<Record<string, unknown>> {
323
+ const path = configPath(profileRoot)
324
+ if (!fsx.exists(path)) return {}
325
+
326
+ const text = await readFile(path, "utf-8")
327
+ const located = locateConfig(path, text)
328
+ if (!located) return {}
329
+
330
+ const value = tsast.prop(located.object, "settings")
331
+ if (!value || !ts.isObjectLiteralExpression(value)) return {}
332
+ return literalOf(value) as Record<string, unknown>
333
+ }
334
+
335
+ /**
336
+ * The machine-wide policy ceiling a profile declares.
337
+ *
338
+ * A TOP-LEVEL key, sibling to `settings` rather than inside it. `ProfileSettings`
339
+ * is deliberately "the keys the terminal itself acts on"; policy is read by the
340
+ * RUNTIME and enforced in the capsule, so folding it in would widen that set's
341
+ * meaning to "anything configurable" and lose the boundary it draws.
342
+ *
343
+ * Read by AST, exactly like `readSettings` — no import, no evaluation, no
344
+ * lock. That matters more here than there: the blueprint path resolves this on
345
+ * every agent load, including `axon run` in a script, and it must not depend on
346
+ * the extensions loader (which imports and evaluates the user's TypeScript
347
+ * behind a serialized lock). A ceiling that only applied when the TUI happened
348
+ * to have loaded a config would be advisory, and advisory is not a ceiling.
349
+ *
350
+ * Returns `{}` for a profile with no policy, which the resolver reads as "no
351
+ * opinion" — every capability falls through to the agent's own policy.
352
+ */
353
+ export async function readPolicy(profileRoot: string): Promise<Record<string, unknown>> {
354
+ const path = configPath(profileRoot)
355
+ if (!fsx.exists(path)) return {}
356
+
357
+ const text = await readFile(path, "utf-8")
358
+ const located = locateConfig(path, text)
359
+ if (!located) return {}
360
+
361
+ const value = tsast.prop(located.object, "policy")
362
+ if (!value || !ts.isObjectLiteralExpression(value)) return {}
363
+ return literalOf(value) as Record<string, unknown>
364
+ }
365
+
366
+ /**
367
+ * Set one key on `settings`, creating the block if it is absent.
368
+ *
369
+ * ── Why the config and not a sidecar ────────────────────────────────────────
370
+ *
371
+ * `profile.config.ts` is the source of truth for a terminal, so what is in
372
+ * effect is what you can read. A second store holding runtime changes would
373
+ * make "why isn't my config taking effect" a real question, and answering it
374
+ * would mean explaining a precedence rule nobody asked for.
375
+ *
376
+ * ── Whole-value replacement ────────────────────────────────────────────────
377
+ *
378
+ * A key is replaced entirely rather than deep-merged. `verbosity` is one
379
+ * setting whose value happens to be an object; merging into it would make
380
+ * "clear this back to default" impossible to express, since every write would
381
+ * only ever add.
382
+ *
383
+ * Formatting is copied from whatever is already there, so an edit is invisible
384
+ * in a diff beside the user's own layout — same as `addEntry`.
385
+ */
386
+ /**
387
+ * A settings key as it must appear in source.
388
+ *
389
+ * Quoted unless it is a plain identifier. Settings names follow CSS where CSS
390
+ * has a name for the thing (`padding-inline`, `padding-block`), and a hyphen is
391
+ * not valid in a bare property name — emitting one produced source that
392
+ * `verified()` correctly refused to write, so the setting could never be
393
+ * stored. Reading already handled quoted keys (see `nameOf`); only writing did
394
+ * not.
395
+ */
396
+ function keyToken(key: string): string {
397
+ return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : JSON.stringify(key)
398
+ }
399
+
400
+ export async function setSetting(profileRoot: string, key: string, value: unknown): Promise<EditResult> {
401
+ const path = configPath(profileRoot)
402
+ if (!fsx.exists(path)) {
403
+ throw err("PROFILE_CONFIG_MISSING", { detail: path, context: { path } })
404
+ }
405
+
406
+ const text = await readFile(path, "utf-8")
407
+ const located = locateConfig(path, text)
408
+ if (!located) {
409
+ throw err("PROFILE_CONFIG_UNEDITABLE", {
410
+ detail: `could not find a defineProfile({ ... }) call in ${path}`,
411
+ context: { path, key },
412
+ })
413
+ }
414
+
415
+ const settings = tsast.prop(located.object, "settings")
416
+ const rendered = render(value, indentOf(text, located.object.getStart(located.source)) + 8)
417
+
418
+ // Already exactly this — nothing to write, and nothing to reload.
419
+ const current = await readSettings(profileRoot)
420
+ if (JSON.stringify(current[key]) === JSON.stringify(value)) return { changed: false }
421
+
422
+ if (settings && ts.isObjectLiteralExpression(settings)) {
423
+ const existing = settings.properties.find(
424
+ prop => ts.isPropertyAssignment(prop) && nameOf(prop.name) === key,
425
+ )
426
+ const inner = indentOf(text, settings.getStart(located.source)) + 4
427
+
428
+ if (existing && ts.isPropertyAssignment(existing)) {
429
+ // Replace just the value, so the key keeps its place in the block.
430
+ const next = text.slice(0, existing.initializer.getStart(located.source))
431
+ + render(value, inner)
432
+ + text.slice(existing.initializer.getEnd())
433
+ await writeFile(path, verified(next, path))
434
+ return { changed: true }
435
+ }
436
+
437
+ // Appended after the last property, not prepended at the brace.
438
+ //
439
+ // Inserting at the open brace put every new key at the TOP, so a config
440
+ // read back in reverse order of when its settings were set — which is
441
+ // not how anyone writes a settings block, and made a machine edit
442
+ // obvious in a diff for no reason.
443
+ const closing = " ".repeat(indentOf(text, settings.getStart(located.source)))
444
+ const props = settings.properties
445
+ const lastProp = props[props.length - 1]
446
+
447
+ let next: string
448
+ if (lastProp) {
449
+ const trailing = text.slice(lastProp.getEnd()).match(/^[^\S\n]*,/)
450
+ const insertAt = lastProp.getEnd() + (trailing ? trailing[0].length : 0)
451
+ next = text.slice(0, insertAt)
452
+ + `${trailing ? "" : ","}\n${" ".repeat(inner)}${keyToken(key)}: ${render(value, inner)},`
453
+ + text.slice(insertAt)
454
+ } else {
455
+ const open = settings.getStart(located.source) + 1
456
+ next = text.slice(0, open)
457
+ + `\n${" ".repeat(inner)}${keyToken(key)}: ${render(value, inner)},\n${closing}`
458
+ + text.slice(open)
459
+ }
460
+ await writeFile(path, verified(next, path))
461
+ return { changed: true }
462
+ }
463
+
464
+ // No settings block at all — add one after the last existing property, so
465
+ // it lands beside `extensions` rather than at the top of a file the user
466
+ // has already arranged.
467
+ const props = located.object.properties
468
+ const last = props[props.length - 1]
469
+ const indent = " ".repeat(last ? indentOf(text, last.getStart(located.source)) : 4)
470
+ const block = `\n\n${indent}settings: {\n${indent} ${keyToken(key)}: ${rendered},\n${indent}},`
471
+
472
+ if (last) {
473
+ const trailing = text.slice(last.getEnd()).match(/^\s*,/)
474
+ const insertAt = last.getEnd() + (trailing ? trailing[0].length : 0)
475
+ const next = text.slice(0, insertAt) + `${trailing ? "" : ","}` + block + text.slice(insertAt)
476
+ await writeFile(path, verified(next, path))
477
+ return { changed: true }
478
+ }
479
+
480
+ const open = located.object.getStart(located.source) + 1
481
+ const next = text.slice(0, open) + block + `\n` + text.slice(open)
482
+ await writeFile(path, verified(next, path))
483
+ return { changed: true }
484
+ }
485
+
486
+ /** A property key as written — identifier or string literal. */
487
+ function nameOf(name: ts.PropertyName): string | null {
488
+ if (ts.isIdentifier(name)) return name.text
489
+ if (ts.isStringLiteralLike(name)) return name.text
490
+ return null
491
+ }
492
+
493
+ /**
494
+ * A literal AST node as plain data. Returns undefined for anything computed —
495
+ * a settings file may contain expressions, and guessing at their value would
496
+ * be worse than reporting the key as unset.
497
+ */
498
+ function literalOf(node: ts.Expression): unknown {
499
+ if (ts.isStringLiteralLike(node)) return node.text
500
+ if (ts.isNumericLiteral(node)) return Number(node.text)
501
+ if (node.kind === ts.SyntaxKind.TrueKeyword) return true
502
+ if (node.kind === ts.SyntaxKind.FalseKeyword) return false
503
+ if (ts.isArrayLiteralExpression(node)) return node.elements.map(literalOf)
504
+ if (ts.isObjectLiteralExpression(node)) {
505
+ const out: Record<string, unknown> = {}
506
+ for (const prop of node.properties) {
507
+ if (!ts.isPropertyAssignment(prop)) continue
508
+ const key = nameOf(prop.name)
509
+ if (key !== null) out[key] = literalOf(prop.initializer)
510
+ }
511
+ return out
512
+ }
513
+ return undefined
514
+ }
515
+
516
+ /**
517
+ * A value as TypeScript source, matching the file's own formatting.
518
+ *
519
+ * Arrays and objects go multi-line at the given indent, because that is how a
520
+ * person writes a settings block and a machine edit should be indistinguishable
521
+ * from a hand edit.
522
+ */
523
+ function render(value: unknown, indent: number): string {
524
+ const pad = " ".repeat(indent)
525
+ const inner = " ".repeat(indent + 4)
526
+
527
+ if (typeof value === "string") return JSON.stringify(value)
528
+ if (typeof value === "number" || typeof value === "boolean") return String(value)
529
+ if (value === null || value === undefined) return "undefined"
530
+
531
+ if (Array.isArray(value)) {
532
+ if (value.length === 0) return "[]"
533
+ const items = value.map(item => `${inner}${render(item, indent + 4)},`).join("\n")
534
+ return `[\n${items}\n${pad}]`
535
+ }
536
+
537
+ const entries = Object.entries(value as Record<string, unknown>)
538
+ if (entries.length === 0) return "{}"
539
+ const body = entries
540
+ .map(([key, item]) => `${inner}${/^[A-Za-z_$][\w$]*$/.test(key) ? key : JSON.stringify(key)}: ${render(item, indent + 4)},`)
541
+ .join("\n")
542
+ return `{\n${body}\n${pad}}`
543
+ }
544
+
545
+ // ── providers ────────────────────────────────────────────────────────────────
546
+
547
+ /**
548
+ * Which provider factory a `providers:` element calls.
549
+ *
550
+ * Elements here are CALL EXPRESSIONS (`Axon()`, `Ollama({ url })`), not the
551
+ * strings `extensions:` holds — so identity is the callee's name. An element
552
+ * that is not a recognisable call answers null and is left strictly alone: a
553
+ * user may have written something this editor does not understand, and
554
+ * touching it would be worse than ignoring it.
555
+ */
556
+ function factoryOf(element: ts.Expression): string | null {
557
+ if (!ts.isCallExpression(element)) return null
558
+ return ts.isIdentifier(element.expression) ? element.expression.text : null
559
+ }
560
+
561
+ /** Whether a `providers:` element was written with options — `Ollama({ url })` rather than `Ollama()`. */
562
+ function hasOptions(element: ts.Expression): boolean {
563
+ return ts.isCallExpression(element) && element.arguments.length > 0
564
+ }
565
+
566
+ /** The provider factories a profile declares, in order. */
567
+ export async function readProviders(profileRoot: string): Promise<string[]> {
568
+ const path = configPath(profileRoot)
569
+ if (!fsx.exists(path)) return []
570
+
571
+ const located = locate(path, await readFile(path, "utf-8"), "providers")
572
+ if (!located) return []
573
+
574
+ return located.array.elements
575
+ .map(factoryOf)
576
+ .filter((name): name is string => name !== null)
577
+ }
578
+
579
+ /**
580
+ * Declare a provider, if it is not already declared.
581
+ *
582
+ * Called AFTER the vault connection succeeds, never before: a profile that
583
+ * advertised a provider whose credential never landed would fail its
584
+ * catalogue on every boot, for something the user never finished setting up.
585
+ *
586
+ * Creates the `providers:` field when the profile has none, so connecting on a
587
+ * profile that never named a provider works rather than throwing about a
588
+ * missing array.
589
+ */
590
+ export async function addProvider(profileRoot: string, factory: string): Promise<EditResult> {
591
+ const path = configPath(profileRoot)
592
+ if (!fsx.exists(path)) {
593
+ throw err("PROFILE_CONFIG_MISSING", { detail: path, context: { path } })
594
+ }
595
+
596
+ const text = await readFile(path, "utf-8")
597
+ const located = locate(path, text, "providers")
598
+
599
+ if (located) {
600
+ if (located.array.elements.map(factoryOf).includes(factory)) return { changed: false }
601
+
602
+ const entry = `${factory}()`
603
+ const elements = located.array.elements
604
+ const last = elements[elements.length - 1]
605
+ const arrayStart = located.array.getStart(located.source)
606
+
607
+ // Same splice discipline as addEntry: copy the author's indentation,
608
+ // insert after a trailing comma rather than before it.
609
+ let next: string
610
+ if (last) {
611
+ const trailing = text.slice(last.getEnd()).match(/^\s*,/)
612
+ const insertAt = last.getEnd() + (trailing ? trailing[0].length : 0)
613
+ const indent = " ".repeat(indentOf(text, last.getStart(located.source)))
614
+ next = text.slice(0, insertAt) + `${trailing ? "" : ","}\n${indent}${entry},` + text.slice(insertAt)
615
+ } else {
616
+ const indent = " ".repeat(indentOf(text, arrayStart) + 4)
617
+ const closing = " ".repeat(indentOf(text, arrayStart))
618
+ next = text.slice(0, arrayStart + 1) + `\n${indent}${entry},\n${closing}` + text.slice(arrayStart + 1)
619
+ }
620
+
621
+ await writeFile(path, verified(next, path))
622
+ return { changed: true }
623
+ }
624
+
625
+ // No `providers:` yet — add the whole field.
626
+ const object = locateObject(path, text)
627
+ if (!object) {
628
+ throw err("PROFILE_CONFIG_UNEDITABLE", {
629
+ detail: `could not find a defineProfile({ ... }) call in ${path}`,
630
+ context: { path, factory },
631
+ })
632
+ }
633
+
634
+ const first = object.object.properties[0]
635
+ const insertAt = first ? first.getStart(object.source) : object.object.getStart(object.source) + 1
636
+ const indent = first ? " ".repeat(indentOf(text, insertAt)) : " "
637
+ const field = `providers: [${factory}()],`
638
+ const next = first
639
+ ? text.slice(0, insertAt) + `${field}\n\n${indent}` + text.slice(insertAt)
640
+ : text.slice(0, insertAt) + `\n${indent}${field}\n` + text.slice(insertAt)
641
+
642
+ await writeFile(path, verified(next, path))
643
+ return { changed: true }
644
+ }
645
+
646
+ /**
647
+ * Undeclare a provider, if it is declared with no options.
648
+ *
649
+ * An entry WITH options (`Ollama({ url: "http://box.local:11434" })`) is left
650
+ * in place: the user configured it deliberately, and silently deleting a
651
+ * self-hosted endpoint on a disconnect is destroying something they cannot
652
+ * recover from this command. A bare `Ollama()` carries no such information and
653
+ * is safe to remove.
654
+ *
655
+ * Removing matters because `providers:` means "sources I have". A disconnected
656
+ * provider left declared contributes a failing catalogue on every boot — a
657
+ * visible error for something the user deliberately turned off.
658
+ */
659
+ export async function removeProvider(profileRoot: string, factory: string): Promise<EditResult> {
660
+ const path = configPath(profileRoot)
661
+ if (!fsx.exists(path)) return { changed: false }
662
+
663
+ const text = await readFile(path, "utf-8")
664
+ const located = locate(path, text, "providers")
665
+ if (!located) return { changed: false }
666
+
667
+ const element = located.array.elements.find(entry => factoryOf(entry) === factory)
668
+ if (!element) return { changed: false }
669
+ if (hasOptions(element)) return { changed: false }
670
+
671
+ const start = element.getStart(located.source)
672
+ const end = element.getEnd()
673
+
674
+ // Take the trailing comma and the whitespace before the element, so the
675
+ // removal leaves no blank line and no dangling `,` — the same shape
676
+ // removeEntry produces.
677
+ const after = text.slice(end).match(/^\s*,/)
678
+ const cutEnd = end + (after ? after[0].length : 0)
679
+ const before = text.slice(0, start).match(/\s*$/)
680
+ const cutStart = start - (before ? before[0].length : 0)
681
+
682
+ await writeFile(path, verified(text.slice(0, cutStart) + text.slice(cutEnd), path))
683
+ return { changed: true }
684
+ }