@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,615 @@
1
+ import { dirname, isAbsolute, join, resolve } from "node:path"
2
+ import { homedir, tmpdir } from "node:os"
3
+ import { cp, mkdir, mkdtemp, readdir, readlink, rename, rm, symlink } from "node:fs/promises"
4
+ import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs"
5
+ import { err } from "@arcforge/err"
6
+ import { graftBroken, verify, type VerifyReport } from "./verify"
7
+ import { TreeCache } from "./treecache"
8
+ import { resolveAbsoluteLinks } from "./links"
9
+ import { isPropagationLag, withPropagationRetry } from "./propagation"
10
+ import type { ManifestT } from "./manifest"
11
+
12
+ type TreeOpts = {
13
+ root: string
14
+ /** Override the shared tree cache. Tests point this at a temp dir. */
15
+ cache?: { root?: string; max?: number }
16
+ }
17
+
18
+ /**
19
+ * Tree — the project's installed node_modules.
20
+ *
21
+ * The counterpart to Manifest: where Manifest owns what the project DECLARES,
22
+ * this owns what is actually materialized on disk. One sentence: it asks Bun to
23
+ * resolve the manifest and puts the result where the project can see it.
24
+ *
25
+ * Every dependency question is answered here. Merging module dependencies into
26
+ * the agent, reconciling conflicting semver ranges, and linking a parallel
27
+ * module store all used to live in this concern; each was compensation for Bun
28
+ * not knowing where Axon modules came from. It does now (the registry speaks
29
+ * the npm protocol), so a module's dependencies are simply its own package.json
30
+ * dependencies, and two modules wanting incompatible versions of the same
31
+ * package resolve by nesting rather than throwing a conflict the user could not
32
+ * act on.
33
+ */
34
+ export function Tree(opts: TreeOpts) {
35
+ const root = opts.root
36
+ // The machine-wide resolved-tree cache. Injectable so tests never touch
37
+ // the developer's real one.
38
+ const cache = TreeCache(opts.cache ?? {})
39
+
40
+ /**
41
+ * Walk up from the project root looking for an installed package, as a
42
+ * resolver would.
43
+ *
44
+ * Deliberately NOT Bun.resolveSync: that also resolves through bun's GLOBAL
45
+ * install cache (~/.bun/install/cache), so it returns true for a project
46
+ * with an empty node_modules whose version merely happens to be cached.
47
+ * That false positive skipped the install and left the agent unrunnable.
48
+ */
49
+ function resolves(name: string): boolean {
50
+ let dir = resolve(root)
51
+ while (true) {
52
+ if (existsSync(join(dir, "node_modules", ...name.split("/")))) return true
53
+ const parent = dirname(dir)
54
+ if (parent === dir) return false
55
+ dir = parent
56
+ }
57
+ }
58
+
59
+ /**
60
+ * The directory a package resolved to, or null. Same walk as resolves(),
61
+ * kept separate so callers that need the path do not repeat it.
62
+ */
63
+ function locate(name: string): string | null {
64
+ let dir = resolve(root)
65
+ while (true) {
66
+ const candidate = join(dir, "node_modules", ...name.split("/"))
67
+ if (existsSync(candidate)) return candidate
68
+ const parent = dirname(dir)
69
+ if (parent === dir) return null
70
+ dir = parent
71
+ }
72
+ }
73
+
74
+ /**
75
+ * What is actually installed for `name` — its version, read from the
76
+ * package.json on disk. Null when absent or unreadable.
77
+ *
78
+ * The distinction resolves() cannot make. A directory being present was
79
+ * the entire installed-ness test, so a package that was present but WRONG
80
+ * — an older version than the range now permits, or one whose contents
81
+ * were replaced — passed as installed. That is how an agent stayed pinned
82
+ * to a broken 0.1.0 after 0.1.1 was published to fix it: the directory
83
+ * existed, so nothing ever looked closer.
84
+ */
85
+ function installedVersion(name: string): string | null {
86
+ const dir = locate(name)
87
+ if (!dir) return null
88
+ try {
89
+ const raw = readFileSync(join(dir, "package.json"), "utf8")
90
+ const parsed = JSON.parse(raw) as { version?: string }
91
+ return parsed.version ?? null
92
+ } catch {
93
+ // Present but unreadable is not installed. A half-extracted or
94
+ // corrupt package must reinstall rather than be trusted.
95
+ return null
96
+ }
97
+ }
98
+
99
+ return {
100
+ resolves: resolves,
101
+ locate: locate,
102
+ installedVersion: installedVersion,
103
+
104
+ /**
105
+ * True when the framework packages are materialized in a node_modules
106
+ * tree the project can see — its own, or a parent workspace's. A fresh
107
+ * scaffold declares the deps in package.json but has no node_modules
108
+ * yet, so "declared" is not "installed": prepare must install whenever
109
+ * this is false.
110
+ *
111
+ * `existsSync` FOLLOWS symlinks, which is what makes this correct for a
112
+ * grafted project: every entry is a link into the shared tree cache, so
113
+ * a tree that was evicted out from under it reads as not-installed and
114
+ * triggers the reinstall that fixes it. A link-existence check (lstat)
115
+ * would see the dangling link, call it installed, and leave the agent
116
+ * permanently broken.
117
+ */
118
+ frameworkInstalled(): boolean {
119
+ if (!resolves("@arcforge/types")) return false
120
+
121
+ // Resolving is not enough when a SOURCE checkout is in play: a
122
+ // grafted cache tree resolves perfectly well and is the published
123
+ // framework, so treating it as installed skipped the relink and
124
+ // left every agent testing against whatever was last released —
125
+ // no matter what the developer had edited. Asking whether the
126
+ // link already points at the checkout makes "installed" mean the
127
+ // right framework, not merely a present one.
128
+ const workspace = workspaceSource()
129
+ if (!workspace) return true
130
+
131
+ return FRAMEWORK_PACKAGES.every(name => {
132
+ const source = frameworkDir(workspace, name)
133
+ if (!source) return true // not in this checkout — published is correct
134
+ const target = join(root, "node_modules", ...name.split("/"))
135
+ try {
136
+ return realpathSync(target) === source
137
+ } catch {
138
+ return false
139
+ }
140
+ })
141
+ },
142
+
143
+ /**
144
+ * True when node_modules exists but its entries point nowhere — a
145
+ * graft onto a shared cache tree that has since been evicted.
146
+ */
147
+ graftBroken(): boolean {
148
+ return graftBroken(root)
149
+ },
150
+
151
+ /**
152
+ * Is the installed tree coherent with what the project declares?
153
+ *
154
+ * THE ONE GATE. Every dependency question the pipeline asks resolves
155
+ * here, so a new class of breakage becomes a new `Fault` variant
156
+ * instead of another bespoke repair bolted to the front of prepare —
157
+ * which is how four separate repairs accumulated before this existed.
158
+ *
159
+ * Pure inspection: it reports faults and repairs nothing, because
160
+ * `--frozen` must be able to ask this exact question and refuse. A
161
+ * check that fixes what it finds can never fail.
162
+ */
163
+ async verify(input: {
164
+ manifest: ManifestT
165
+ managed: Record<string, string>
166
+ registryOrigin: string
167
+ }): Promise<VerifyReport> {
168
+ return verify({
169
+ root,
170
+ manifest: input.manifest,
171
+ managed: input.managed,
172
+ registryOrigin: input.registryOrigin,
173
+ installedVersion: installedVersion,
174
+ locate: locate,
175
+ })
176
+ },
177
+
178
+ /** True when every name is resolvable from this project. */
179
+ allResolve(names: string[]): boolean {
180
+ return names.every(resolves)
181
+ },
182
+
183
+ /**
184
+ * Delete the project's node_modules.
185
+ *
186
+ * For the broken-graft case specifically: installing over a directory
187
+ * of dangling links leaves them in place (bun writes what it resolves
188
+ * and does not audit what it did not touch), so the tree has to go
189
+ * before the reinstall rather than after.
190
+ */
191
+ async clearModules(): Promise<void> {
192
+ await rm(join(root, "node_modules"), { recursive: true, force: true })
193
+ },
194
+
195
+ /**
196
+ * Delete the lockfile.
197
+ *
198
+ * For a registry switch specifically. A lockfile is a pin, and
199
+ * replaying one is normally exactly right — but bun.lock pins
200
+ * fully-qualified TARBALL URLs, so a lock written against another
201
+ * registry re-fetches every package from there regardless of what
202
+ * bunfig now maps. Discarding it is what makes the next install
203
+ * resolve against the registry actually in play.
204
+ */
205
+ async clearLock(): Promise<void> {
206
+ await rm(join(root, "bun.lock"), { force: true })
207
+ },
208
+
209
+ /**
210
+ * Materialize node_modules from package.json, via Bun.
211
+ *
212
+ * Resolves in an ISOLATED copy of the manifest rather than in place:
213
+ * agents often live inside a monorepo, and running `bun install` there
214
+ * makes Bun walk up to the workspace root, where a checked-in source
215
+ * package can shadow the published module of the same name. Installing
216
+ * a copy and then materializing its node_modules keeps the agent
217
+ * self-contained and makes local dev match a fresh clone.
218
+ */
219
+ async install(opts?: {
220
+ refresh?: string[]
221
+ /**
222
+ * Called before each wait while a just-published version reaches
223
+ * this npm edge. Optional — a caller with no surface passes
224
+ * nothing, and a multi-second pause simply happens quietly.
225
+ */
226
+ onPropagationRetry?: (delayMs: number, attempt: number) => void
227
+ }): Promise<void> {
228
+ // A refresh deliberately re-resolves within declared ranges, so
229
+ // its result depends on what the registry holds right now rather
230
+ // than on what the project declares. Nothing else is excluded: an
231
+ // existing lockfile is a pin, and treeKey() hashes it, so a hit
232
+ // means the ranges AND the pins matched.
233
+ const cacheable = !opts?.refresh?.length
234
+
235
+ const staging = await mkdtemp(join(tmpdir(), "axon-agent-deps-"))
236
+ try {
237
+ // `workspace:*` and `file:` are both "local", and they need
238
+ // OPPOSITE treatment in the isolated install:
239
+ //
240
+ // workspace:* cannot resolve here — there is no workspace in
241
+ // the staging dir, by design. Stripped, then
242
+ // symlinked back afterwards, so a deliberate link
243
+ // to a local checkout (how the framework is
244
+ // developed against a real agent) survives rather
245
+ // than being rewritten to the published version.
246
+ //
247
+ // file: resolves fine, and MUST be kept: a source
248
+ // module's own dependencies are declared in ITS
249
+ // package.json, so stripping the file: entry means
250
+ // Bun never sees them and they are never fetched.
251
+ // The module then symlinks in with an empty dep
252
+ // tree and fails at import. Only the path needs
253
+ // fixing — it is relative to the agent root, and
254
+ // staging is somewhere else entirely.
255
+ const declared = JSON.parse(await Bun.file(join(root, "package.json")).text()) as {
256
+ dependencies?: Record<string, string>
257
+ overrides?: Record<string, string>
258
+ }
259
+ const entries = Object.entries(declared.dependencies ?? {})
260
+ const workspace = entries.filter(([, range]) => range.startsWith("workspace:"))
261
+
262
+ // `overrides` carries the SAME rewrite as dependencies: it
263
+ // exists to redirect a linked package's own `workspace:*`
264
+ // deps at the local tree, and those paths are relative to the
265
+ // agent root just like the dependency entries. Left
266
+ // unrewritten (or dropped by the spread) the staging install
267
+ // fails with "Workspace dependency not found" on a package
268
+ // the agent never declared.
269
+ const isolated = {
270
+ ...declared,
271
+ ...(declared.overrides ? { overrides: rebase(declared.overrides, root) } : {}),
272
+ dependencies: Object.fromEntries(
273
+ entries
274
+ .filter(([name]) => !workspace.some(([wsName]) => wsName === name))
275
+ .map(([name, range]): [string, string] => range.startsWith("file:")
276
+ ? [name, `file:${resolve(root, range.slice("file:".length)).split(/[\\/]/).join("/")}`]
277
+ : [name, range]),
278
+ ),
279
+ }
280
+ await Bun.write(join(staging, "package.json"), JSON.stringify(isolated, null, 2))
281
+
282
+ // The agent's bunfig.toml carries the @axon scope → registry
283
+ // mapping. Without it the isolated install cannot resolve a
284
+ // single Axon module.
285
+ const bunfig = join(root, "bunfig.toml")
286
+ if (existsSync(bunfig)) await cp(bunfig, join(staging, "bunfig.toml"))
287
+
288
+ // The isolated install is a pure function of what was just
289
+ // written into staging: the rebased manifest, the registry
290
+ // mapping, and the lockfile pin. Identical inputs therefore
291
+ // produce an identical tree, and that is worth caching —
292
+ // scaffolding N projects from one template (every fixture in
293
+ // the test suite, every `axon init` on a warm machine) re-ran
294
+ // the same resolution and then physically copied the same
295
+ // ~36MB/1400 files each time.
296
+ //
297
+ // Keyed by content rather than by project, so nothing has to
298
+ // decide when it went stale: a changed dependency is a
299
+ // different key, and the old entry is simply never read again.
300
+ const key = cacheable ? await cache.key(staging) : null
301
+ if (key) {
302
+ const hit = cache.entry(key)
303
+ if (existsSync(join(hit, "node_modules"))) {
304
+ await cache.touch(hit) // a hit is a use — eviction sorts on this, not on write time
305
+ await graft(join(hit, "node_modules"), join(root, "node_modules"))
306
+ // Recorded AFTER the graft, so the tree is only claimed
307
+ // once this project genuinely points into it.
308
+ await cache.addReferrer(hit, resolve(root))
309
+ if (existsSync(join(hit, "bun.lock"))) await cp(join(hit, "bun.lock"), join(root, "bun.lock"))
310
+ await linkLocal(root, workspace)
311
+ await linkFramework(root)
312
+ return
313
+ }
314
+ }
315
+
316
+ // Replay the existing lockfile so an install that changes
317
+ // nothing re-resolves nothing — same versions as the last run.
318
+ const lock = join(root, "bun.lock")
319
+ if (existsSync(lock)) await cp(lock, join(staging, "bun.lock"))
320
+
321
+ let result = await Bun.$`bun install --cwd ${staging}`.quiet().nothrow()
322
+
323
+ // Then force the named packages to re-resolve inside their
324
+ // declared ranges. The lockfile is a pin, correctly: replaying
325
+ // it is what makes an unchanged install reproducible. But a
326
+ // pin also means a published fix can never reach an agent that
327
+ // already holds the broken version — `^0.1.0` permits 0.1.1
328
+ // and the lock says 0.1.0, so nothing moves and the author's
329
+ // fix is invisible forever. `bun update <name>` is the one
330
+ // thing that re-resolves within a range, and it runs ONLY for
331
+ // packages reconcile found outside theirs.
332
+ if (result.exitCode === 0 && opts?.refresh?.length) {
333
+ const refreshed = await Bun.$`bun update --cwd ${staging} ${opts.refresh}`.quiet().nothrow()
334
+ // A refresh failure is not fatal: the tree from the
335
+ // install above is still valid, just older than it could
336
+ // be. Reconcile will report it again next run.
337
+ if (refreshed.exitCode === 0) result = refreshed
338
+ }
339
+
340
+ // Propagation lag: the version we pinned exists but has not
341
+ // reached this npm edge yet. The CLI pins framework versions
342
+ // matching ITSELF, so the very first `axon init` after an
343
+ // `axon update` asks for exactly the versions just published —
344
+ // which is why this fires seconds after an update succeeded.
345
+ //
346
+ // `--no-cache` alone was the previous answer, retried ONCE and
347
+ // immediately. It bypasses Bun's manifest cache but cannot make
348
+ // an edge serve what it has not received, so the retry consumed
349
+ // the race rather than waiting it out. `axon update` had the
350
+ // right policy all along (four attempts, backoff); this now
351
+ // shares it. See project/propagation.ts.
352
+ if (result.exitCode !== 0 && isPropagationLag(combinedOutput(result))) {
353
+ const retried = await withPropagationRetry(
354
+ async () => {
355
+ const attempt = await Bun.$`bun install --cwd ${staging} --no-cache`.quiet().nothrow()
356
+ result = attempt
357
+ return { ok: attempt.exitCode === 0, output: combinedOutput(attempt) }
358
+ },
359
+ { ...(opts?.onPropagationRetry ? { onRetry: opts.onPropagationRetry } : {}) },
360
+ )
361
+ void retried
362
+ }
363
+
364
+ // A `file:` dependency is materialized through bun's shared
365
+ // link cache, so two installs linking the SAME package at the
366
+ // same moment race and one loses with EEXIST. That is the
367
+ // normal case under a parallel test run, where several
368
+ // fixtures link this repo's framework at once. `copyfile`
369
+ // copies instead of linking, so concurrent installs never
370
+ // touch the same cache entry.
371
+ if (result.exitCode !== 0 && isConcurrentLinkRace(combinedOutput(result))) {
372
+ result = await Bun.$`bun install --cwd ${staging} --backend=copyfile`.quiet().nothrow()
373
+ }
374
+
375
+ if (result.exitCode !== 0) {
376
+ const detail = result.stderr.toString().trim()
377
+ || result.stdout.toString().trim()
378
+ || `exit ${result.exitCode}`
379
+ throw err("MODULE_DEPENDENCY_INSTALL_FAILED", { detail })
380
+ }
381
+
382
+ // Publish before materializing: the tree in staging is the
383
+ // clean one. The project's copy gets local symlinks grafted
384
+ // into it by linkLocal() below, and those point at THIS
385
+ // project's checkout — caching them would hand another project
386
+ // a tree with someone else's paths baked in.
387
+ if (key) await cache.publish(key, staging)
388
+
389
+ await materialize(join(staging, "node_modules"), join(root, "node_modules"))
390
+ // Only workspace deps are relinked. A file: dep was part of the
391
+ // real install, so its directory in node_modules is the tree Bun
392
+ // built — replacing it with a bare symlink would discard exactly
393
+ // the transitive dependencies this install went and fetched.
394
+ await linkLocal(root, workspace)
395
+ await linkFramework(root)
396
+ if (existsSync(join(staging, "bun.lock"))) {
397
+ await cp(join(staging, "bun.lock"), join(root, "bun.lock"))
398
+ }
399
+ } finally {
400
+ await rm(staging, { recursive: true, force: true })
401
+ }
402
+ },
403
+
404
+ materialize: materialize,
405
+ }
406
+ }
407
+
408
+ export type TreeT = ReturnType<typeof Tree>
409
+
410
+ /**
411
+ * Copy an isolated Bun install into its permanent location.
412
+ *
413
+ * Links are preserved, then the ones that would dangle are repaired.
414
+ *
415
+ * The distinction matters because bun's isolated linker keeps exactly one real
416
+ * copy of each package under `node_modules/.bun/` and makes every other
417
+ * appearance a RELATIVE link into it. Those stay valid when the tree moves, so
418
+ * copying them verbatim is both correct and much cheaper: dereferencing turned
419
+ * 1,115 files into 3,917 (the same packages, materialized once per referrer)
420
+ * and took 3.4x as long.
421
+ *
422
+ * What genuinely cannot survive is an ABSOLUTE link — bun emits those in
423
+ * `.bin`, pointing back into the staging directory that is deleted moments
424
+ * later, which would make every package executable vanish. Those are resolved
425
+ * here, while the source still exists. Fixing exactly them keeps the guarantee
426
+ * the old blanket dereference was reaching for (a self-contained tree) without
427
+ * paying for it across the whole install.
428
+ */
429
+ async function materialize(source: string, target: string): Promise<void> {
430
+ await rm(target, { recursive: true, force: true })
431
+ await cp(source, target, { recursive: true, verbatimSymlinks: true })
432
+ await resolveAbsoluteLinks(target)
433
+ }
434
+
435
+ /**
436
+ * Point a project's node_modules at a cached tree, without copying it.
437
+ *
438
+ * One symlink per top-level entry rather than a recursive copy: the cached
439
+ * tree is immutable and shared, so 925 files do not need to exist once per
440
+ * project. This is the difference between ~370ms and ~1ms per install, which
441
+ * is what makes scaffolding cheap enough to do in a test fixture.
442
+ *
443
+ * The top level is a REAL directory holding links, never a link to the cached
444
+ * directory itself. That is what keeps the shared tree safe: linkLocal() and
445
+ * any later install replace entries HERE — unlinking this project's pointer —
446
+ * and a project that adds a dependency gets its own real tree from the install
447
+ * path below. Nothing writes through into the cache.
448
+ *
449
+ * Absolute links inside the cached tree would still be a hazard, since they
450
+ * escape it entirely; publishTree() resolves them before an entry is stored,
451
+ * so by this point there are none.
452
+ */
453
+ async function graft(source: string, target: string): Promise<void> {
454
+ await rm(target, { recursive: true, force: true })
455
+ await mkdir(target, { recursive: true })
456
+
457
+ for (const entry of await readdir(source)) {
458
+ await symlink(join(source, entry), join(target, entry))
459
+ }
460
+ }
461
+
462
+ async function linkLocal(root: string, local: Array<[string, string]>): Promise<void> {
463
+ for (const [name, range] of local) {
464
+ const source = range.startsWith("file:")
465
+ ? resolve(root, range.slice("file:".length))
466
+ : findWorkspacePackage(root, name)
467
+ if (!source) continue
468
+
469
+ const target = join(root, "node_modules", ...name.split("/"))
470
+ await rm(target, { recursive: true, force: true })
471
+ await mkdir(dirname(target), { recursive: true })
472
+ await symlink(source, target, "dir")
473
+ }
474
+ }
475
+
476
+ /** Re-anchor `file:` ranges from the agent root to absolute paths the staging install can resolve. */
477
+ function rebase(ranges: Record<string, string>, root: string): Record<string, string> {
478
+ return Object.fromEntries(
479
+ Object.entries(ranges).map(([name, range]): [string, string] => range.startsWith("file:")
480
+ ? [name, `file:${resolve(root, range.slice("file:".length)).split(/[\\/]/).join("/")}`]
481
+ : [name, range]),
482
+ )
483
+ }
484
+
485
+ /**
486
+ * The framework packages an agent resolves at runtime.
487
+ *
488
+ * These are the ones a compiled cognet fuses to or imports by bare specifier,
489
+ * so a stale copy in an agent's tree is a stale RUNTIME — not merely an old
490
+ * type. `@arcforge/cognet` is the sharp case: its `host.ts` hand-writes the
491
+ * ambient `kernel` facade, so an agent holding a published copy from before an
492
+ * ABI change gets a shim missing the new verb and fails with a bare TypeError
493
+ * naming a syscall that does exist.
494
+ */
495
+ const FRAMEWORK_PACKAGES = [
496
+ "@arcforge/types",
497
+ "@arcforge/err",
498
+ "@arcforge/engines",
499
+ "@arcforge/air",
500
+ "@arcforge/session",
501
+ "@arcforge/cognet",
502
+ ] as const
503
+
504
+ /**
505
+ * The workspace checkout a source build should link its framework from.
506
+ *
507
+ * Set by the source-run entrypoint (`apps/tui/bin/axon`, what `axonl` runs);
508
+ * absent for an installed CLI, which must always use published packages. That
509
+ * asymmetry is the whole point: an agent lives outside the repo (under
510
+ * `~/.axon-dev/profiles/...`), so the ordinary workspace walk finds nothing
511
+ * and every agent silently installs whatever the registry last published.
512
+ *
513
+ * Without this, the only way to exercise a framework change against a real
514
+ * agent is a full release — which makes the publish step part of the inner
515
+ * dev loop, and means a broken ABI is discovered by users rather than by the
516
+ * person who changed it.
517
+ */
518
+ function workspaceSource(): string | null {
519
+ const root = process.env.AXON_WORKSPACE
520
+ if (!root) return null
521
+ return existsSync(join(root, "package.json")) ? resolve(root) : null
522
+ }
523
+
524
+ /**
525
+ * Framework packages, linked from the source checkout rather than installed.
526
+ *
527
+ * Runs only when AXON_WORKSPACE is set, and only for packages that genuinely
528
+ * exist there — an unknown name is skipped rather than removed, so a partial
529
+ * checkout degrades to the published copy instead of an unresolvable import.
530
+ */
531
+ async function linkFramework(root: string): Promise<void> {
532
+ const workspace = workspaceSource()
533
+ if (!workspace) return
534
+
535
+ for (const name of FRAMEWORK_PACKAGES) {
536
+ const source = frameworkDir(workspace, name)
537
+ if (!source) continue
538
+
539
+ const target = join(root, "node_modules", ...name.split("/"))
540
+ // Already pointing at this source — leave it, so a reload does not
541
+ // churn the tree the bundler may be reading.
542
+ if (existsSync(target) && realpathSync(target) === source) continue
543
+
544
+ await rm(target, { recursive: true, force: true })
545
+ await mkdir(dirname(target), { recursive: true })
546
+ await symlink(source, target, "dir")
547
+ }
548
+ }
549
+
550
+ /**
551
+ * Where a framework package lives inside the checkout.
552
+ *
553
+ * A DIRECT search rather than findWorkspacePackage(), which caps its scan at
554
+ * `-maxdepth 4` and so cannot see a manifest at `libs/axon/packages/<pkg>` (depth
555
+ * 5). That limit is fine for the workspace walk it was written for; silently
556
+ * inheriting it here would link two packages and skip four, which is worse
557
+ * than linking none — a tree half on source and half on published is a
558
+ * version skew nobody would think to look for.
559
+ *
560
+ * Verified by NAME, never by path convention: the manifest has to actually
561
+ * claim the specifier, so a moved or renamed package fails to link instead of
562
+ * linking the wrong directory.
563
+ */
564
+ function frameworkDir(workspace: string, name: string): string | null {
565
+ const found = Bun.spawnSync([
566
+ "find", join(workspace, "libs"), "-maxdepth", "5", "-name", "package.json",
567
+ "-not", "-path", "*/node_modules/*",
568
+ ]).stdout.toString().trim().split("\n")
569
+
570
+ for (const candidate of found) {
571
+ if (!candidate) continue
572
+ try {
573
+ const pkg = JSON.parse(readFileSync(candidate, "utf8")) as { name?: string }
574
+ if (pkg.name === name) return dirname(candidate)
575
+ } catch { /* unreadable manifest is not a match */ }
576
+ }
577
+ return null
578
+ }
579
+
580
+ /** Walk up looking for a workspace member with this package name. */
581
+ function findWorkspacePackage(from: string, name: string): string | null {
582
+ let dir = resolve(from)
583
+ while (true) {
584
+ const manifest = join(dir, "package.json")
585
+ if (existsSync(manifest)) {
586
+ try {
587
+ const pkg = JSON.parse(readFileSync(manifest, "utf8")) as { workspaces?: string[] }
588
+ if (pkg.workspaces) {
589
+ const found = Bun.spawnSync(["find", dir, "-maxdepth", "4", "-name", "package.json",
590
+ "-not", "-path", "*/node_modules/*"]).stdout.toString().trim().split("\n")
591
+ for (const candidate of found) {
592
+ if (!candidate) continue
593
+ try {
594
+ const c = JSON.parse(readFileSync(candidate, "utf8")) as { name?: string }
595
+ if (c.name === name) return dirname(candidate)
596
+ } catch { /* unreadable manifest is not a match */ }
597
+ }
598
+ }
599
+ } catch { /* unreadable manifest — keep walking */ }
600
+ }
601
+ const parent = dirname(dir)
602
+ if (parent === dir) return null
603
+ dir = parent
604
+ }
605
+ }
606
+
607
+ /** Everything a bun subprocess said, for classifying its failure. */
608
+ function combinedOutput(result: { stderr: Buffer; stdout: Buffer }): string {
609
+ return result.stderr.toString() + result.stdout.toString()
610
+ }
611
+
612
+ /** Two installs linking the same `file:` package into bun's shared cache at once. */
613
+ function isConcurrentLinkRace(output: string): boolean {
614
+ return /EEXIST.*failed to link package/.test(output)
615
+ }