@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,731 @@
1
+ import { mkdir, rename, rm } from "node:fs/promises"
2
+ import { dirname, join } from "node:path"
3
+ import { err } from "@arcforge/err"
4
+ import { gt, valid } from "semver"
5
+ import { fsx } from "../../utils/fs"
6
+ import { Watcher } from "../project"
7
+ import { ProfileConfigFile, resolveEntry, type ResolvedEntry } from "./config"
8
+ import { addEntry, addProvider, readEntries, readProviders, readSettings, removeEntry, removeProvider, setSetting } from "./edit"
9
+ import { ExtensionStore, formatRef, parseRef, type ExtensionStoreT } from "./store"
10
+ import { DisposerSink, disposeSource, loadSource, RELOAD_PREFIX, type LoadedSource } from "./load"
11
+
12
+ /**
13
+ * Extensions — loads a profile's own config and every extension it enables.
14
+ *
15
+ * Headless. It imports the user's files and tracks what they registered; it
16
+ * knows nothing about a terminal, which is what lets the whole load order,
17
+ * containment and teardown story be tested without one. The API those files
18
+ * call into is installed by the caller before this runs (see `install`).
19
+ *
20
+ * ── Load order is the contract ──────────────────────────────────────────────
21
+ *
22
+ * profile main.ts → profile plugins/*
23
+ * → extension[0] main.ts → extension[0] plugins/*
24
+ * → extension[1] ...
25
+ *
26
+ * The profile goes FIRST so a user's own config wins every collision — under
27
+ * first-wins, order is the policy. Extensions follow in the order
28
+ * profile.config.ts lists them, which is why resolution may be concurrent but
29
+ * loading never is: a load order that varied would make collisions
30
+ * non-deterministic, and "which of my two extensions bound ctrl+o" is not a
31
+ * question anyone should have to answer twice.
32
+ *
33
+ * ── Nothing here throws ─────────────────────────────────────────────────────
34
+ *
35
+ * Every failure lands in the returned result. A user with a broken config still
36
+ * gets a terminal — the one they need in order to go fix it — and the caller
37
+ * decides how loudly to say what broke. That is also the correct layering: this
38
+ * package has no surface to report on.
39
+ */
40
+
41
+ export type ExtensionsResult = {
42
+ /** Every source that loaded, in load order. The profile is first when present. */
43
+ sources: LoadedSource[]
44
+ /**
45
+ * Failures that are not attributable to one file — an unreadable
46
+ * profile.config.ts, an extension that could not be found or installed.
47
+ * Per-file errors live on their own source's `files`.
48
+ */
49
+ errors: unknown[]
50
+ }
51
+
52
+ export type UninstallResult = {
53
+ /** True when a `profile.config.ts` entry was removed. False when it was not declared. */
54
+ changed: boolean
55
+ /**
56
+ * True when fetched files were deleted from disk.
57
+ *
58
+ * False for a local entry — that is source the user wrote, and uninstall
59
+ * only ever stops loading it. Reported rather than assumed so the CLI can
60
+ * say which of the two happened instead of printing a fixed sentence that
61
+ * is wrong half the time.
62
+ */
63
+ removed: boolean
64
+ }
65
+
66
+ type ExtensionsOpts = {
67
+ /**
68
+ * The active profile's directory, resolved per call.
69
+ *
70
+ * A thunk rather than a value: which profile is active is a function of who
71
+ * is logged in, which changes within one process (`switchProfile`), and
72
+ * reading it at construction would bind this to whoever happened to be
73
+ * active at boot. It may also throw when nobody is — construction is
74
+ * wiring, so that failure belongs at load(), not here.
75
+ */
76
+ root: () => string
77
+ /**
78
+ * Fetches and prepares a registry extension into `dir`.
79
+ *
80
+ * A thunk rather than the Registry handle, same idiom as Zeno's `clone`:
81
+ * registry is constructed in terms of projects, and taking a value here
82
+ * would force a reorder in platform.ts.
83
+ *
84
+ * Omitted by callers that only load local extensions — a registry entry
85
+ * then reports EXTENSION_NOT_FOUND rather than silently doing nothing.
86
+ */
87
+ install?: (ref: string, dir: string) => Promise<{ version: string }>
88
+ /**
89
+ * The newest published version of `name`, without fetching anything.
90
+ *
91
+ * Separate from `install` because checking and applying are different acts
92
+ * with different risk: an extension is arbitrary code that runs at boot, so
93
+ * asking what exists must never be the same call as installing it. Omitted
94
+ * by callers with no registry — `updates()` then reports nothing rather
95
+ * than pretending everything is current.
96
+ */
97
+ latest?: (name: string) => Promise<string>
98
+ /**
99
+ * Where fetched extensions live, shared by every profile. Injected so
100
+ * tests can point it at a scratch dir.
101
+ */
102
+ store?: ExtensionStoreT
103
+ }
104
+
105
+ /** One declared extension, against what the registry currently publishes. */
106
+ export type ExtensionUpdate = {
107
+ /** The config entry verbatim, e.g. "@cody/ember-theme@0.2.0". */
108
+ source: string
109
+ name: string
110
+ /** Null for a legacy unpinned entry — it has no version to compare. */
111
+ current: string | null
112
+ /** Null when the registry could not be reached or has no such artifact. */
113
+ latest: string | null
114
+ /** True only when both versions are known AND differ. */
115
+ outdated: boolean
116
+ }
117
+
118
+ /** True when a directory is an extension — it carries the marker config. */
119
+ function isExtension(root: string): boolean {
120
+ return fsx.exists(join(root, "extension.config.ts"))
121
+ }
122
+
123
+ export function Extensions(opts: ExtensionsOpts) {
124
+ const store = opts.store ?? ExtensionStore()
125
+ const sink = DisposerSink()
126
+ let loaded: LoadedSource[] = []
127
+ /**
128
+ * What `profile.config.ts` currently declares, whether or not it loaded.
129
+ *
130
+ * Distinct from `sources`, which holds only what actually loaded. A UI
131
+ * offering "uninstall" must list the BROKEN one too — an extension that
132
+ * fails to load is the one a user most needs to remove, and deriving the
133
+ * list from load results makes it the one entry they cannot select.
134
+ *
135
+ * ── Refreshed on every WRITE, not only on load ──────────────────────────
136
+ *
137
+ * This mirrors a file, so it goes stale the instant anything edits that
138
+ * file without loading. install/update/uninstall all do exactly that —
139
+ * they rewrite the config and let the watcher reload asynchronously — so a
140
+ * load-time-only snapshot was wrong for the whole window in between, which
141
+ * is precisely when a user is looking at the list.
142
+ *
143
+ * The symptom was a palette that could not undo itself: after an update,
144
+ * `:ext uninstall` rendered "(none installed)" while the config plainly
145
+ * declared one, because the cache still held the pre-update ref (or, on a
146
+ * fresh handle, nothing at all). Anything that writes the config must call
147
+ * `syncDeclared()`.
148
+ */
149
+ let declared: string[] = []
150
+
151
+ /** Re-read the declared list from disk. Call after ANY config write. */
152
+ async function syncDeclared(): Promise<void> {
153
+ declared = await readEntries(opts.root())
154
+ }
155
+
156
+ /**
157
+ * addEntry/removeEntry, with the cache refreshed.
158
+ *
159
+ * Wrapped rather than each call site remembering, because forgetting is
160
+ * silent: the write lands, the file is right, and only a UI reading the
161
+ * cache is wrong — which is a bug that surfaces far from its cause. Four
162
+ * call sites and a fifth arriving with the next verb is exactly the shape
163
+ * that wants one door.
164
+ */
165
+ async function declareEntry(root: string, source: string) {
166
+ const result = await addEntry(root, source)
167
+ await syncDeclared()
168
+ return result
169
+ }
170
+
171
+ async function undeclareEntry(root: string, source: string) {
172
+ const result = await removeEntry(root, source)
173
+ await syncDeclared()
174
+ return result
175
+ }
176
+ /**
177
+ * Runs a write without the watcher reacting to it. Null when not watching.
178
+ *
179
+ * Held rather than passed per call because only `watch()` knows the
180
+ * watcher exists, and every settings write wants the same treatment.
181
+ */
182
+ let suppress: (<T>(fn: () => Promise<T>) => Promise<T>) | null = null
183
+
184
+ /**
185
+ * Materialize one entry, returning the reason it is unusable.
186
+ *
187
+ * A local entry must already exist — it is a path the user wrote, and
188
+ * creating something there would be inventing an extension they did not
189
+ * write. A registry entry is fetched when it is not already usable, then
190
+ * checked the same way, because a fetch that succeeds but produces
191
+ * something without a config is not an extension either.
192
+ */
193
+ async function materialize(entry: ResolvedEntry): Promise<unknown | null> {
194
+ // Fetched only when it is not already a usable extension on disk.
195
+ //
196
+ // Not "when the directory is absent": a half-materialized directory —
197
+ // an interrupted clone, or a fetch that produced something without a
198
+ // config — would otherwise be permanently stuck, since clone() refuses
199
+ // to write into a non-empty target. Clearing it first is what makes a
200
+ // reinstall a repair rather than a no-op.
201
+ if (entry.kind === "registry" && !isExtension(entry.root)) {
202
+ if (fsx.exists(entry.root)) await rm(entry.root, { recursive: true, force: true })
203
+
204
+ if (!opts.install) {
205
+ return err("EXTENSION_NOT_FOUND", {
206
+ detail: `${entry.source} is not installed`,
207
+ context: { source: entry.source, root: entry.root },
208
+ })
209
+ }
210
+ try {
211
+ await opts.install(entry.source, entry.root)
212
+ } catch (cause) {
213
+ return err("EXTENSION_INSTALL_FAILED", {
214
+ detail: `${entry.source} — ${cause instanceof Error ? cause.message : String(cause)}`,
215
+ context: { source: entry.source, root: entry.root },
216
+ cause,
217
+ })
218
+ }
219
+ }
220
+
221
+ if (!fsx.exists(entry.root)) {
222
+ return err("EXTENSION_NOT_FOUND", {
223
+ detail: `${entry.source} → ${entry.root}`,
224
+ context: { source: entry.source, root: entry.root },
225
+ })
226
+ }
227
+ if (!isExtension(entry.root)) {
228
+ return err("EXTENSION_NOT_AN_EXTENSION", {
229
+ detail: `${entry.root} has no extension.config.ts`,
230
+ context: { source: entry.source, root: entry.root },
231
+ })
232
+ }
233
+ return null
234
+ }
235
+
236
+ return {
237
+ /** Every source currently loaded, in load order. */
238
+ get sources(): readonly LoadedSource[] {
239
+ return loaded
240
+ },
241
+
242
+ /**
243
+ * Every extension the last load DECLARED, in load order — including
244
+ * any that failed. Synchronous, for a UI that cannot await.
245
+ */
246
+ get declared(): readonly string[] {
247
+ return declared
248
+ },
249
+
250
+ /**
251
+ * Populate `declared` from disk without loading anything.
252
+ *
253
+ * For a surface that may render the list BEFORE the first load — or
254
+ * before one has been triggered at all. Reading the config is cheap and
255
+ * runs no extension code, which is the whole reason it is safe to offer
256
+ * separately from `load()`.
257
+ */
258
+ syncDeclared,
259
+
260
+ /** Every extension the profile declares, in load order. */
261
+ list(): Promise<string[]> {
262
+ return readEntries(opts.root())
263
+ },
264
+
265
+ /**
266
+ * The platform settings the config declares.
267
+ *
268
+ * `profile.config.ts` is the source of truth — there is no sidecar
269
+ * store holding runtime overrides, so what a user reads in that file is
270
+ * always what is in effect. A second store would make "why isn't my
271
+ * config taking effect" a real question with a precedence rule for an
272
+ * answer, which is exactly the confusion one file avoids.
273
+ */
274
+ settings(): Promise<Record<string, unknown>> {
275
+ return readSettings(opts.root())
276
+ },
277
+
278
+ /**
279
+ * Write one setting, and suppress the reload it would otherwise cause.
280
+ *
281
+ * The watcher sees `profile.config.ts` change and re-runs the whole
282
+ * config — right for a hand edit, wasteful for `:theme set`, which
283
+ * would dispose and re-import every extension to change one string. The
284
+ * caller already applied the change in memory; re-running the config
285
+ * would only arrive at the same state, slower and with a visible hitch.
286
+ *
287
+ * `suppress` is the watcher's own `during()`, handed in by whoever
288
+ * started watching — so this needs no knowledge of whether anything is
289
+ * watching at all.
290
+ */
291
+ async setSetting(key: string, value: unknown): Promise<{ changed: boolean }> {
292
+ const root = opts.root()
293
+ const write = () => setSetting(root, key, value)
294
+ return suppress ? suppress(write) : write()
295
+ },
296
+
297
+ /**
298
+ * The provider factories this profile declares.
299
+ *
300
+ * Read from the config rather than from a cache, because the user may
301
+ * have edited it by hand — `providers:` is theirs to write, and the
302
+ * connect commands are a convenience over it, not the only way in.
303
+ */
304
+ readProviders(): Promise<string[]> {
305
+ return readProviders(opts.root())
306
+ },
307
+
308
+ /**
309
+ * Declare a provider — called after its vault connection succeeds.
310
+ *
311
+ * Suppressed like every other config write: rewriting the file must
312
+ * not fire the watcher's reload, or connecting a provider would
313
+ * restart every extension as a side effect.
314
+ */
315
+ async addProvider(factory: string): Promise<{ changed: boolean }> {
316
+ const root = opts.root()
317
+ const write = () => addProvider(root, factory)
318
+ return suppress ? suppress(write) : write()
319
+ },
320
+
321
+ /** Undeclare a provider — called after its vault connection is dropped. */
322
+ async removeProvider(factory: string): Promise<{ changed: boolean }> {
323
+ const root = opts.root()
324
+ const write = () => removeProvider(root, factory)
325
+ return suppress ? suppress(write) : write()
326
+ },
327
+
328
+ /**
329
+ * Does this local path point at an extension?
330
+ *
331
+ * The marker config is the only test — the same one the loader applies
332
+ * — so "is it an extension" has exactly one answer everywhere rather
333
+ * than a CLI-side guess that can disagree with what load() will do.
334
+ *
335
+ * False for a path that does not exist. A caller routing on this wants
336
+ * to know whether to treat it as an extension, and a missing directory
337
+ * is not one; the install it falls through to reports the absence with
338
+ * the context to fix it.
339
+ */
340
+ isLocalExtension(source: string): boolean {
341
+ try {
342
+ return isExtension(resolveEntry(source, opts.root(), store).root)
343
+ } catch {
344
+ // resolveEntry needs an active profile, and nobody may be
345
+ // logged in. Not an extension we can install, which is the
346
+ // same answer either way.
347
+ return false
348
+ }
349
+ },
350
+
351
+ /**
352
+ * Fetch an extension and record it in `profile.config.ts`.
353
+ *
354
+ * Two steps, in this order: materialize first, declare second. A config
355
+ * naming an extension that is not on disk reports EXTENSION_NOT_FOUND
356
+ * on every boot until someone edits the file — so nothing is written
357
+ * until there is something for it to point at.
358
+ *
359
+ * Idempotent. Re-installing an already-declared extension refetches it
360
+ * (a repair) and leaves the config alone.
361
+ */
362
+ async install(source: string): Promise<{ root: string; declared: boolean; ref: string }> {
363
+ const root = opts.root()
364
+
365
+ // A local path is declared as written and lives where it sits —
366
+ // it is the user's own source, and copying it into a shared store
367
+ // would make the copy the thing that loads.
368
+ if (resolveEntry(source, root, store).kind === "local") {
369
+ const entry = resolveEntry(source, root, store)
370
+ const problem = await materialize(entry)
371
+ if (problem) throw problem
372
+ const { changed } = await declareEntry(root, source)
373
+ return { root: entry.root, declared: changed, ref: source }
374
+ }
375
+
376
+ const { name, version: pinned } = parseRef(source)
377
+
378
+ // Already stored at the pinned version — nothing to fetch. This is
379
+ // what makes a second profile's install instant, and it is the
380
+ // whole point of the shared store.
381
+ const existing = pinned ? store.resolve(source) : null
382
+ if (existing) {
383
+ const ref = formatRef(existing.name, existing.version)
384
+ const { changed } = await declareEntry(root, ref)
385
+ return { root: existing.root, declared: changed, ref }
386
+ }
387
+
388
+ if (!opts.install) {
389
+ throw err("EXTENSION_NOT_FOUND", {
390
+ detail: `${source} is not installed`,
391
+ context: { source },
392
+ })
393
+ }
394
+
395
+ // Fetched into a staging path, then moved to its version once the
396
+ // registry says what that version is: the destination is not
397
+ // knowable until resolution, and a directory named for a version
398
+ // it does not hold is worse than one that briefly does not exist.
399
+ const staging = join(store.root, ".staging", crypto.randomUUID())
400
+ let resolvedVersion: string
401
+ try {
402
+ ;({ version: resolvedVersion } = await opts.install(source, staging))
403
+ } catch (cause) {
404
+ await rm(staging, { recursive: true, force: true })
405
+ throw err("EXTENSION_INSTALL_FAILED", {
406
+ detail: `${source} — ${cause instanceof Error ? cause.message : String(cause)}`,
407
+ context: { source },
408
+ cause,
409
+ })
410
+ }
411
+
412
+ const target = store.pathFor(name, resolvedVersion)
413
+ if (store.isUsable(target)) {
414
+ // Another profile fetched this version while we were fetching.
415
+ // Theirs is as good as ours — drop the duplicate.
416
+ await rm(staging, { recursive: true, force: true })
417
+ } else {
418
+ await mkdir(dirname(target), { recursive: true })
419
+ await rename(staging, target)
420
+ }
421
+
422
+ const ref = formatRef(name, resolvedVersion)
423
+ const { changed } = await declareEntry(root, ref)
424
+ return { root: target, declared: changed, ref }
425
+ },
426
+
427
+ /**
428
+ * Uninstall an extension: undeclare it. Files are left alone.
429
+ *
430
+ * ── Nothing is deleted, and that is the point ───────────────────────
431
+ *
432
+ * Fetched extensions live in a MACHINE-WIDE store now, shared by every
433
+ * profile. Deleting the directory would rip an extension out from
434
+ * under a profile the user was not touching — a terminal breaking
435
+ * because of something done in an unrelated one.
436
+ *
437
+ * So uninstall means "this profile stops loading it", which is what
438
+ * the word means to the person typing it. Reclaiming the disk is its
439
+ * own explicit act (`axon ext prune`), because deciding that no
440
+ * profile needs a version any more is a different question from
441
+ * deciding this one does not.
442
+ *
443
+ * A local entry (`./themes`, `~/dev/my-ext`) is the opposite: it is
444
+ * source the user wrote, `uninstall` means "stop loading this", and
445
+ * deleting it would be unrecoverable. So it is only ever undeclared.
446
+ *
447
+ * `resolveEntry` already distinguishes them, which is why this needs no
448
+ * flag: the kind of the entry decides, not the caller's intent.
449
+ */
450
+ async uninstall(source: string): Promise<UninstallResult> {
451
+ const root = opts.root()
452
+
453
+ // Matched on NAME, so `axon ext uninstall @cody/vim` removes the
454
+ // entry however it is pinned. Requiring the exact `@0.1.0` back
455
+ // would make uninstall a lookup exercise, and the user is removing
456
+ // the extension rather than one version of it.
457
+ const declaredNow = await readEntries(root)
458
+ const { name } = parseRef(source)
459
+ const target = declaredNow.find(entry => parseRef(entry).name === name) ?? source
460
+
461
+ const { changed } = await undeclareEntry(root, target)
462
+
463
+ // Files are NEVER deleted here — see the note above. Reported as
464
+ // `removed: false` always, so the CLI says what actually happened.
465
+ return { changed, removed: false }
466
+ },
467
+
468
+ /**
469
+ * What the profile declares, with the newest published version of each.
470
+ *
471
+ * ── Read-only, and that is the whole design ─────────────────────────
472
+ *
473
+ * An extension is arbitrary TypeScript that runs at module scope on
474
+ * every boot with the full TUI API — it can bind keys, register
475
+ * commands and drive the agent. So updating one is a privileged act
476
+ * that stays MANUAL: nothing here fetches, writes or reloads. Asking
477
+ * the registry what exists is safe; applying it is the user's call.
478
+ *
479
+ * That is also why there is no auto-update path to opt out of. A
480
+ * background update would swap running code under a user mid-session,
481
+ * and the pin in `profile.config.ts` is already a deliberate contract:
482
+ * `store.resolve()` refuses to load a version the config does not name,
483
+ * because "silently loading a version the config does not name is how a
484
+ * pinned config stops meaning anything".
485
+ *
486
+ * LOCAL entries are excluded entirely. A `./my-ext` path is the user's
487
+ * own source with no version and no publisher — there is nothing to
488
+ * update it to, and offering it would be offering a row that cannot work.
489
+ *
490
+ * A name the registry cannot resolve (unpublished, renamed, network
491
+ * down) is reported with `latest: null` rather than dropped, so a
492
+ * caller can say so instead of quietly showing a shorter list.
493
+ */
494
+ async updates(): Promise<ExtensionUpdate[]> {
495
+ if (!opts.latest) return []
496
+
497
+ const root = opts.root()
498
+ const entries = await readEntries(root)
499
+
500
+ const checked = await Promise.all(entries.map(async (source): Promise<ExtensionUpdate | null> => {
501
+ if (resolveEntry(source, root, store).kind === "local") return null
502
+
503
+ const { name, version } = parseRef(source)
504
+ try {
505
+ const latest = await opts.latest!(name)
506
+ // A COMPARISON, not an inequality. `latest !== version`
507
+ // reports any difference as "newer", so a registry serving
508
+ // an older version — a yank, a rollback, a staging
509
+ // endpoint — offered the user an "update" that was a
510
+ // downgrade. Unparseable versions on either side compare
511
+ // to false: unknown is not out of date.
512
+ const outdated = version !== null
513
+ && valid(version) !== null
514
+ && valid(latest) !== null
515
+ && gt(latest, version)
516
+ return { source, name, current: version, latest, outdated }
517
+ } catch {
518
+ // Unreachable is not the same as up to date. Reported as
519
+ // unknown so the caller can distinguish "nothing new" from
520
+ // "could not ask" — a failed check that rendered as "up to
521
+ // date" would be a lie the user acts on.
522
+ return { source, name, current: version, latest: null, outdated: false }
523
+ }
524
+ }))
525
+
526
+ return checked.filter((entry): entry is ExtensionUpdate => entry !== null)
527
+ },
528
+
529
+ /**
530
+ * Move one extension to a version, and re-pin the config to it.
531
+ *
532
+ * Deliberately just `install()` at an explicit ref: an update IS an
533
+ * install of a different version, and `addEntry` already replaces a
534
+ * same-name entry rather than appending one — logic that exists for
535
+ * precisely this ("re-installing after a publish produces a new ref").
536
+ * A second code path would be the same operation written twice, free to
537
+ * disagree about pinning.
538
+ *
539
+ * The version is REQUIRED rather than defaulted to latest. The caller
540
+ * has already resolved and shown what it is moving to; re-resolving
541
+ * here could silently land on something newer than the user agreed to
542
+ * between the list rendering and their pressing enter.
543
+ */
544
+ async update(name: string, version: string): Promise<{ root: string; ref: string }> {
545
+ const { root: installed, ref } = await this.install(formatRef(name, version))
546
+ return { root: installed, ref }
547
+ },
548
+
549
+ /**
550
+ * The sink the API implementation reports registrations to.
551
+ *
552
+ * Exposed because the two halves are built in different packages: the
553
+ * globals live in the TUI (they need its composables), the ownership
554
+ * bookkeeping lives here. `track()` on every register is the whole
555
+ * coupling between them.
556
+ */
557
+ get disposers(): DisposerSink {
558
+ return sink
559
+ },
560
+
561
+ /**
562
+ * Load the profile and its extensions.
563
+ *
564
+ * Idempotent in the sense that matters: calling it again after
565
+ * `unload()` produces a clean load. Calling it twice without one would
566
+ * double-register, so `reload()` exists and this does not guard —
567
+ * a silent no-op would be worse than the honest sequence.
568
+ */
569
+ async load(): Promise<ExtensionsResult> {
570
+ const errors: unknown[] = []
571
+ const sources: LoadedSource[] = []
572
+ const root = opts.root()
573
+
574
+ // The user's own config first — it wins every collision, and it
575
+ // loads even when the extension list is unreadable.
576
+ if (fsx.exists(root)) {
577
+ sources.push(await loadSource({
578
+ root: root,
579
+ label: "profile",
580
+ sink: sink,
581
+ mainError: "PROFILE_MAIN_FAILED",
582
+ }))
583
+ }
584
+
585
+ const config = await ProfileConfigFile(root, store)
586
+ if (config.error) errors.push(config.error)
587
+
588
+ // Sequential, deliberately — see the load-order note above.
589
+ declared = config.entries.map(entry => entry.source)
590
+
591
+ for (const entry of config.entries) {
592
+ const problem = await materialize(entry)
593
+ if (problem) {
594
+ errors.push(problem)
595
+ continue
596
+ }
597
+ sources.push(await loadSource({
598
+ root: entry.root,
599
+ label: entry.source,
600
+ sink: sink,
601
+ mainError: "EXTENSION_LOAD_FAILED",
602
+ }))
603
+ }
604
+
605
+ loaded = sources
606
+ return { sources, errors }
607
+ },
608
+
609
+ /**
610
+ * Undo everything, newest source first.
611
+ *
612
+ * Reverse order for the same reason a source's own disposers run in
613
+ * reverse: a later registration may have been made against state an
614
+ * earlier one owns.
615
+ */
616
+ unload(): void {
617
+ for (const source of [...loaded].reverse()) disposeSource(source)
618
+ loaded = []
619
+ },
620
+
621
+ /**
622
+ * Tear down and load again — what a config file change triggers.
623
+ *
624
+ * Unload FIRST, completely, before anything re-imports. Overlapping the
625
+ * two would leave both generations registered at once, and every
626
+ * collision would resolve against the old copy.
627
+ */
628
+ async reload(): Promise<ExtensionsResult> {
629
+ this.unload()
630
+ return this.load()
631
+ },
632
+
633
+ /**
634
+ * Call `onChange` when the user's config changes on disk. Returns a
635
+ * stop function.
636
+ *
637
+ * ── What is watched ─────────────────────────────────────────────────
638
+ *
639
+ * The profile root — `main.ts`, anything it imports, `plugins/`,
640
+ * `profile.config.ts`, and each extension under `extensions/`.
641
+ * Deliberately NOT `agents/` (each agent runs its own watcher, and an
642
+ * agent's source is not terminal config), `store/` (Axon writes
643
+ * history there continuously — a committed session event is not a
644
+ * config change), or `.axon/` (generated BY the reload, so watching it
645
+ * is a loop by construction).
646
+ *
647
+ * ── Why this notifies rather than reloads ───────────────────────────
648
+ *
649
+ * A reload here would be `this.reload()` — correct for the registry,
650
+ * wrong for the terminal, which must also settle its input surface
651
+ * first and fire `tui:boot`/`tui:reloaded` after. Two reload paths that
652
+ * had to stay in step is exactly the drift this package avoids
653
+ * elsewhere; the caller owns what a reload MEANS and this owns when.
654
+ *
655
+ * ── Why a reload's own writes must be DISCARDED ─────────────────────
656
+ *
657
+ * A reload writes inside the profile — an install's lockfile, a
658
+ * regenerated frame. The watcher's own `during()` holds changes raised
659
+ * while it runs and REPLAYS them on resume. That is right for a bounded
660
+ * operation (an install writes, finishes, and replaying once catches a
661
+ * user edit made alongside it) and wrong here, because the suspended
662
+ * operation IS the reload: a replayed write starts another reload,
663
+ * which writes, which replays. Unbounded, not a slow leak — and the
664
+ * first thing a user would notice.
665
+ *
666
+ * So this gates at its own listener instead. Everything arriving while
667
+ * a reload runs, plus a short tail afterwards, is dropped: fs
668
+ * notifications are asynchronous, so a write made inside the reload is
669
+ * still being delivered for a few milliseconds after it returns, and a
670
+ * gate that closed the instant it finished would let exactly those
671
+ * through.
672
+ *
673
+ * The cost is a real edit inside that window being missed. Bounded by
674
+ * one save on an operation that is normally tens of milliseconds, and
675
+ * recovered by the next save or `:reload`. The alternative is a
676
+ * terminal that reloads forever, which is not a trade.
677
+ */
678
+ watch(onChange: () => Promise<void>): () => void {
679
+ const watcher = Watcher({
680
+ root: opts.root(),
681
+ ignore: ["node_modules", ".git", ".axon", "agents", "store"],
682
+ // The transient copies importFile() evaluates. Writing one is
683
+ // part of performing a reload, so reacting to it would make
684
+ // every reload schedule the next one, forever.
685
+ ignoreFiles: name => name.startsWith(RELOAD_PREFIX),
686
+ // An editor writes several times per save (temp file, rename,
687
+ // mtime touch). Long enough to coalesce those, short enough
688
+ // that saving still feels immediate.
689
+ debounceMs: 150,
690
+ })
691
+
692
+ // How long after a reload returns its own writes may still be
693
+ // arriving. Comfortably over the debounce, since a notification
694
+ // scheduled just before the gate closes lands one window later.
695
+ const TAIL_MS = 400
696
+
697
+ // `selfReloads`: suppression must actually suppress. A bare
698
+ // during() only DEFERS — the held change is delivered on resume,
699
+ // so a `:theme set` still triggered the full config reload this
700
+ // exists to avoid. The deaf-window below happened to absorb it,
701
+ // but that is a 400ms race rather than a guarantee, and it broke
702
+ // the moment a write took longer than the window.
703
+ suppress = fn => watcher.during(fn, { selfReloads: true })
704
+
705
+ let running = false
706
+ let deafUntil = 0
707
+
708
+ const stop = watcher.onChange(() => {
709
+ if (running || Date.now() < deafUntil) return
710
+ running = true
711
+ void (async () => {
712
+ try {
713
+ await onChange()
714
+ } finally {
715
+ running = false
716
+ deafUntil = Date.now() + TAIL_MS
717
+ }
718
+ })()
719
+ })
720
+
721
+ void watcher.start()
722
+ return () => {
723
+ suppress = null
724
+ stop()
725
+ watcher.stop()
726
+ }
727
+ },
728
+ }
729
+ }
730
+
731
+ export type ExtensionsT = ReturnType<typeof Extensions>