@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,253 @@
1
+ import type { FrameworkSource } from "./manifest/package"
2
+ import { resolveDefaultBaseUrl, type AxonCloudClient, type DeployOptions, type DeployStep } from "@arcforge/cloud"
3
+ import { err } from "@arcforge/err"
4
+ import type { ProviderEntry } from "@arcforge/types"
5
+ import { Bundle, type BundleArtifact } from "./bundle"
6
+ import { Cognet } from "./cognet"
7
+ import { Deploy, type DeployResult } from "./deploy"
8
+ import { Installer } from "./installer"
9
+ import { Manifest } from "./manifest"
10
+ import { SourceModules } from "./modules"
11
+ import { Prepare } from "./prepare"
12
+ import { Publish, type PublishResult, type PublishStep } from "./publish"
13
+ import { Tree } from "./tree"
14
+ import type { VerifyReport } from "./verify"
15
+ import { Typegen } from "./typegen"
16
+ import { Watcher } from "./watcher"
17
+ import type { WatcherT, DuringOptions } from "./watcher"
18
+ import { type ProjectKind } from "./kinds"
19
+ import { Bench, type BenchT, type BenchExtras } from "../bench"
20
+
21
+ export type { ProjectKind }
22
+
23
+ type ProjectOpts = {
24
+ root: string
25
+ kind: ProjectKind
26
+ name: string
27
+ cloud: AxonCloudClient
28
+ /** CLI version — prepare pins/repairs the project's @arcforge framework deps to it. */
29
+ frameworkVersion: string
30
+ frameworkSource?: FrameworkSource
31
+ repoRoot?: string
32
+ /** Bench-only collaborators, supplied by Projects. */
33
+ bench: BenchExtras
34
+ /** The active profile's inference sources — carried onto every blueprint this project loads. */
35
+ profileProviders?: () => Promise<readonly ProviderEntry[] | undefined>
36
+ }
37
+
38
+ /**
39
+ * Project — one project of any kind on disk. Pure composition: the verbs are
40
+ * owned by their leaves (Installer, Typegen, Prepare, Publish, bundle); the
41
+ * handle just wires them to one root.
42
+ *
43
+ * Every kind gets the same surface. What a kind IS lives in the kind table
44
+ * (kinds.ts), not in branches here — the one exception being `deploy`, which
45
+ * is genuinely agent-only and says so.
46
+ */
47
+ export function Project(opts: ProjectOpts) {
48
+ const { root, kind, name } = opts
49
+
50
+ const manifest = Manifest({ root: root })
51
+ const tree = Tree({ root: root })
52
+ const modules = SourceModules({ root: root, manifest: manifest })
53
+
54
+ /**
55
+ * Watchers outside this project's root that must suspend along with it.
56
+ *
57
+ * A registry cognet's source lives in `node_modules/<name>/`, and the agent
58
+ * watches it so an edit to the brain rebuilds. But `bun install` rewrites
59
+ * all of node_modules, so an install fired that watcher — unsuspended —
60
+ * straight into the middle of the tree rebuild. The scan then ran against a
61
+ * half-written tree and reported the cognet as missing (AX-COGNET-014) for
62
+ * an install that was working correctly.
63
+ *
64
+ * Registered rather than constructed here because the cognet's location is
65
+ * only known after a blueprint has compiled, which happens in the runtime
66
+ * above this. The project owns the suspension; it does not own the watcher.
67
+ */
68
+ const linked = new Set<WatcherT>()
69
+
70
+ /**
71
+ * Suspend this project's watcher AND every linked one for the duration.
72
+ *
73
+ * Nested rather than merged, so each watcher keeps its own suspend depth
74
+ * and pending path. Restoration is guaranteed by each `during()`'s own
75
+ * finally, including on a throw partway through the chain.
76
+ */
77
+ function during<T>(fn: () => Promise<T>, options?: DuringOptions): Promise<T> {
78
+ let run = fn
79
+ for (const other of linked) {
80
+ const inner = run
81
+ run = () => other.during(inner, options)
82
+ }
83
+ return watcher.during(run, options)
84
+ }
85
+
86
+ // `during` is a thunk because `watcher` is constructed below — the
87
+ // installer suspends the watcher around its own writes so a reload cannot
88
+ // land between the manifest edits and the node_modules rebuild.
89
+ const installer = Installer({
90
+ root: root,
91
+ cloud: opts.cloud,
92
+ manifest: manifest,
93
+ tree: tree,
94
+ during: (fn, options) => during(fn, options),
95
+ })
96
+ const typegen = Typegen({ root: root, kind: kind })
97
+ // `prepare` is a getter: Prepare() is built below and bundling needs it.
98
+ const bundle = Bundle({ root: root, manifest: manifest, modules: modules, prepare: () => prepare })
99
+
100
+ // A bench owns verbs no other kind has (run, result, coordinates) and
101
+ // declarations generated from its own config. It is the one kind with an
102
+ // extension, and it hangs off the project rather than beside it.
103
+ const bench = kind === "bench" ? Bench({ root, cloud: opts.cloud, ...opts.bench }) : null
104
+
105
+ const prepare = Prepare({
106
+ root: root,
107
+ kind: kind,
108
+ installer: installer,
109
+ modules: modules,
110
+ manifest: manifest,
111
+ tree: tree,
112
+ typegen: typegen,
113
+ frameworkVersion: opts.frameworkVersion,
114
+ ...(opts.frameworkSource ? { frameworkSource: opts.frameworkSource } : {}),
115
+ ...(opts.repoRoot ? { repoRoot: opts.repoRoot } : {}),
116
+ ...(bench ? { extend: async () => { await bench.prepare() } } : {}),
117
+ ...(opts.profileProviders ? { profileProviders: opts.profileProviders } : {}),
118
+ })
119
+ const publish = Publish({ kind, root, bundle, manifest, cloud: opts.cloud })
120
+ const deploy = Deploy({ bundle, manifest, cloud: opts.cloud })
121
+ const watcher = Watcher({ root })
122
+
123
+ return {
124
+ root: root,
125
+ kind: kind,
126
+ name: name,
127
+
128
+ /** Registry module management (agent projects). */
129
+ modules: installer,
130
+
131
+ /**
132
+ * The agent's brain, as an updatable dependency. One per agent, so a
133
+ * single answer rather than a list — see Cognet() for why swapping it
134
+ * is deliberately not offered here.
135
+ */
136
+ cognet: Cognet({ manifest, installer, tree }),
137
+
138
+ /**
139
+ * The engine this agent runs on — read it, or point it at another
140
+ * model. A surgical edit to the author's own axon.config.ts, which is
141
+ * what makes the TUI's model picker a change to the agent rather than a
142
+ * switch to something else. Exposed alone rather than the whole
143
+ * manifest: identity and bunfig are the build pipeline's business,
144
+ * but the model is the user's.
145
+ */
146
+ model: manifest.model,
147
+
148
+ /**
149
+ * The agent's own environment — its keys, and setting one.
150
+ *
151
+ * Sits beside `model` for the same reason, and env moved into this
152
+ * category when it stopped being read-only. A deploy reading .env IS
153
+ * pipeline business; a user handing THIS agent a Telegram token is not
154
+ * — it is a per-agent boundary they control, which is the whole point
155
+ * of each agent having its own .env rather than inheriting a shared
156
+ * one. The rest of the manifest stays unexposed.
157
+ */
158
+ env: manifest.env,
159
+
160
+ /**
161
+ * Benchmark verbs — run, result, coordinates, config. Null on every
162
+ * other kind, so reaching for them is a type error rather than a
163
+ * runtime surprise.
164
+ */
165
+ bench: bench as BenchT | null,
166
+
167
+ /**
168
+ * Generated type declarations. Agents pass a loaded blueprint —
169
+ * the dev loop reuses its own to avoid a double scan.
170
+ */
171
+ typegen: typegen.write,
172
+
173
+ /**
174
+ * Regenerate ONE domain's declarations without a full write.
175
+ *
176
+ * The registry (what a config registers, as completable names) is the
177
+ * case this exists for: it changes on every config save, and rewriting
178
+ * the whole frame for one edited line would make saving cost an install
179
+ * check and a manifest read.
180
+ *
181
+ * Exposed as the generators object rather than as one verb per domain,
182
+ * so a caller reaches exactly what it needs and this handle does not
183
+ * grow a method every time a generator is added.
184
+ */
185
+ generate: typegen.generate,
186
+
187
+ /** Package into the publishable artifact — image.json + source.tar.gz. */
188
+ bundle(): Promise<BundleArtifact> {
189
+ return bundle.build(kind)
190
+ },
191
+
192
+ /** Install declared modules, then generate types. What `axon prepare`/`dev` run. */
193
+ prepare: prepare,
194
+
195
+ /**
196
+ * Report what is wrong with this project's installed state, repairing
197
+ * nothing. What `axon doctor` runs.
198
+ *
199
+ * Deliberately the same primitive `prepare` gates on, not a parallel
200
+ * set of checks: a diagnostic that can disagree with the thing it
201
+ * diagnoses is worse than none. The only difference is that this never
202
+ * acts on what it finds.
203
+ *
204
+ * Reads the DECLARED dependency set rather than the one an install run
205
+ * computes — `managed` is a product of resolving, and a diagnostic must
206
+ * not resolve. That makes this a strictly narrower view than prepare's:
207
+ * it can see everything the manifest declares, and nothing about what
208
+ * a fresh resolve would add.
209
+ */
210
+ async diagnose(): Promise<VerifyReport> {
211
+ const declared = await manifest.package.dependencies.all()
212
+ return tree.verify({
213
+ manifest,
214
+ managed: declared,
215
+ registryOrigin: resolveDefaultBaseUrl(),
216
+ })
217
+ },
218
+
219
+ /**
220
+ * Bundle → register → upload → sync visibility. What `axon [module]
221
+ * publish` runs. Pass `onProgress` to observe each step; a publish can
222
+ * spend a long time inside any one of them.
223
+ */
224
+ publish: publish,
225
+
226
+ /** Bundle → register → publish → provision → wait until running. Agents only. */
227
+ deploy(options?: DeployOptions & { onProgress?: (step: DeployStep) => void }): Promise<DeployResult> {
228
+ if (kind !== "agent") throw err("DEPLOY_AGENTS_ONLY")
229
+ return deploy(options)
230
+ },
231
+
232
+ /** Raw fs change notifications for this root — inert until start() is called (Agent does, for dev). */
233
+ watcher: watcher,
234
+
235
+ /**
236
+ * Suspend a watcher OUTSIDE this root alongside this project's own.
237
+ *
238
+ * For a watcher pointed at something an install rewrites but that does
239
+ * not live under `root` — today that is the registry cognet's source in
240
+ * `node_modules`. Without this it reloads mid-`bun install` and reports
241
+ * the cognet missing for an install that is working.
242
+ *
243
+ * Returns an unlink function; a caller that stops its watcher must call
244
+ * it, or a suspension keeps reaching a watcher nobody is listening to.
245
+ */
246
+ link(other: WatcherT): () => void {
247
+ linked.add(other)
248
+ return () => linked.delete(other)
249
+ },
250
+ }
251
+ }
252
+
253
+ export type ProjectT = ReturnType<typeof Project>
@@ -0,0 +1,164 @@
1
+ import type { FrameworkSource } from "./manifest/package"
2
+ import { dirname, join, resolve } from "node:path"
3
+ import type { AxonCloudClient } from "@arcforge/cloud"
4
+ import { err } from "@arcforge/err"
5
+ import { fsx } from "../../utils/fs"
6
+ import { KINDS, detectKind, type ProjectKind } from "./kinds"
7
+ import { Project, type ProjectT } from "./project"
8
+ import type { BenchExtras } from "../bench"
9
+ import type { ProviderEntry } from "@arcforge/types"
10
+
11
+ type ProjectsOpts = {
12
+ cloud: AxonCloudClient
13
+ /** CLI version — scaffolded projects pin @arcforge/types + @arcforge/engines to it exactly. */
14
+ frameworkVersion: string
15
+ frameworkSource?: FrameworkSource
16
+ repoRoot?: string
17
+ /** Collaborators a bench project needs — the test runner and agent resolution. */
18
+ bench: BenchExtras
19
+ /**
20
+ * The active profile's declared inference sources, read fresh per call.
21
+ *
22
+ * A FUNCTION, not a value: the active profile changes while the process
23
+ * runs (a user switches profiles) and a captured array would keep serving
24
+ * the one that was active at boot.
25
+ *
26
+ * Injected rather than read here because this layer deliberately knows
27
+ * nothing about auth or profiles — it resolves WHICH directory and WHAT
28
+ * kind, and a store lookup would give it an opinion about which user is
29
+ * running. The composition root knows; this carries.
30
+ */
31
+ profileProviders?: () => Promise<readonly ProviderEntry[] | undefined>
32
+ }
33
+
34
+ /**
35
+ * Projects — finds, opens, and creates agent/module projects. The entry
36
+ * point of project management: resolves WHICH directory and WHAT kind,
37
+ * the question Blueprint deliberately refuses to answer.
38
+ *
39
+ * Auth never appears here — registry access flows through the injected
40
+ * cloud client and fails loudly at the call site when logged out.
41
+ */
42
+ export function Projects(opts: ProjectsOpts) {
43
+ async function open(root: string): Promise<ProjectT> {
44
+ const absolute = resolve(root)
45
+ const kind = detectKind(absolute)
46
+
47
+ if (!kind) {
48
+ throw err("PROJECT_NOT_FOUND", { context: { path: absolute } })
49
+ }
50
+
51
+ return Project({
52
+ root: absolute,
53
+ kind: kind,
54
+ name: await projectName(absolute),
55
+ cloud: opts.cloud,
56
+ frameworkVersion: opts.frameworkVersion,
57
+ ...(opts.frameworkSource ? { frameworkSource: opts.frameworkSource } : {}),
58
+ ...(opts.repoRoot ? { repoRoot: opts.repoRoot } : {}),
59
+ bench: opts.bench,
60
+ ...(opts.profileProviders ? { profileProviders: opts.profileProviders } : {}),
61
+ })
62
+ }
63
+
64
+ /** Open the project at or above cwd, refusing anything that isn't `kind`. */
65
+ async function openAs(kind: ProjectKind, cwd: string): Promise<ProjectT> {
66
+ const root = find(cwd)
67
+ if (!root) {
68
+ throw err("PROJECT_NOT_FOUND", {
69
+ detail: `no ${KINDS[kind].config} at or above ${cwd}`,
70
+ context: { path: cwd, kind },
71
+ })
72
+ }
73
+ const project = await open(root)
74
+ if (project.kind !== kind) {
75
+ throw err("PROJECT_WRONG_KIND", {
76
+ detail: `${project.root} is a ${project.kind} project, not a ${kind}`,
77
+ context: { root: project.root, expected: kind, actual: project.kind },
78
+ })
79
+ }
80
+ return project
81
+ }
82
+
83
+ /** Walk up from cwd to the nearest project root. Null when outside any project. */
84
+ function find(cwd: string = process.cwd()): string | null {
85
+ let current = resolve(cwd)
86
+ while (true) {
87
+ if (detectKind(current)) return current
88
+ const parent = dirname(current)
89
+ if (parent === current) return null
90
+ current = parent
91
+ }
92
+ }
93
+
94
+ return {
95
+ open: open,
96
+ openAs: openAs,
97
+ find: find,
98
+
99
+ /**
100
+ * Scaffold a project of any kind at <dir>/<name>/ and open it.
101
+ *
102
+ * One path for all five kinds. The scaffolder writes source; prepare()
103
+ * declares + installs the framework deps and generates the type frame
104
+ * — the same path that self-heals an older project, so init and
105
+ * prepare share one dependency story. prepare() is unconditional:
106
+ * kinds with nothing to prepare (prompt packages) no-op inside it
107
+ * rather than relying on this caller to remember to skip them.
108
+ */
109
+ async create(
110
+ kind: ProjectKind,
111
+ input: {
112
+ name: string
113
+ dir?: string
114
+ apiBase?: string
115
+ /**
116
+ * Observe the two phases this composes.
117
+ *
118
+ * Scaffolding writes files in milliseconds; prepare resolves
119
+ * and installs a dependency tree and can run for seconds. A
120
+ * caller rendering one spinner over both is rendering a
121
+ * spinner over the install and calling it something else.
122
+ */
123
+ onProgress?: (step: CreateStep) => void
124
+ },
125
+ ): Promise<ProjectT> {
126
+ const report = input.onProgress ?? (() => {})
127
+
128
+ report({ step: "scaffolding" })
129
+ const root = await KINDS[kind].scaffold({
130
+ name: input.name,
131
+ dir: input.dir ?? process.cwd(),
132
+ frameworkVersion: opts.frameworkVersion,
133
+ ...(opts.frameworkSource ? { frameworkSource: opts.frameworkSource } : {}),
134
+ ...(opts.repoRoot ? { repoRoot: opts.repoRoot } : {}),
135
+ ...(input.apiBase !== undefined ? { apiBase: input.apiBase } : {}),
136
+ })
137
+ const project = await open(root)
138
+
139
+ report({ step: "preparing", root })
140
+ await project.prepare()
141
+
142
+ report({ step: "created", root, name: project.name })
143
+ return project
144
+ },
145
+ }
146
+ }
147
+
148
+ /** Phases surfaced through create()'s onProgress. */
149
+ export type CreateStep =
150
+ | { step: "scaffolding" }
151
+ | { step: "preparing"; root: string }
152
+ | { step: "created"; root: string; name: string }
153
+
154
+ export type ProjectsT = ReturnType<typeof Projects>
155
+
156
+ /** package.json name, falling back to the directory basename. */
157
+ async function projectName(root: string): Promise<string> {
158
+ const text = await fsx.readText(join(root, "package.json"))
159
+ if (text) {
160
+ const name = (JSON.parse(text) as { name?: string }).name
161
+ if (name) return name
162
+ }
163
+ return root.split("/").pop()!
164
+ }
@@ -0,0 +1,120 @@
1
+ /**
2
+ * npm propagation lag — the one policy, shared by everything that installs.
3
+ *
4
+ * A just-published version is not visible from every npm edge immediately. For
5
+ * a few seconds, a machine can ask for a version that genuinely exists and be
6
+ * told it does not, phrased by Bun as:
7
+ *
8
+ * No version matching "2.0.159" found for specifier "@arcforge/cognet"
9
+ * (but package exists)
10
+ *
11
+ * That parenthetical is the tell: the package resolved, the version did not, so
12
+ * this is lag rather than a bad pin.
13
+ *
14
+ * ── Why it lives here rather than in each caller ───────────────────────────
15
+ *
16
+ * There were two implementations. `services/update/installer.ts` retried FOUR
17
+ * times with exponential backoff, and worked. `project/tree.ts` retried ONCE,
18
+ * immediately, with `--no-cache` — which bypasses Bun's manifest cache but
19
+ * cannot make an edge serve a version it has not received yet, so the retry
20
+ * consumed the race rather than waiting it out.
21
+ *
22
+ * The consequence was that `axon update` succeeded and the very next
23
+ * `axon init` failed, against the same registry, seconds apart: the CLI pins
24
+ * framework versions matching itself, so a fresh agent asks for exactly the
25
+ * versions that were just published.
26
+ *
27
+ * One policy, one place.
28
+ */
29
+
30
+ /**
31
+ * How many times to ask, and for how long in total.
32
+ *
33
+ * Seven attempts spans ~63s of backoff (1+2+4+8+16+32). The previous budget was
34
+ * four attempts across ~7s, chosen against an assumption that propagation is
35
+ * near-instant — measured against npm it is not. A publish observed during this
36
+ * work was still invisible to the edge well past the seven-second mark and
37
+ * landed comfortably inside a minute, which is the shape npm's own guidance
38
+ * describes.
39
+ *
40
+ * The cost of overshooting is a slow first run after a release; the cost of
41
+ * undershooting is a hard failure on a condition that resolves itself, which is
42
+ * strictly worse. It is also bounded: only a genuine lag signature retries at
43
+ * all (see `isPropagationLag`), so a real miss still fails immediately.
44
+ */
45
+ export const PROPAGATION_ATTEMPTS = 7
46
+
47
+ /**
48
+ * True when a `bun install` failure is propagation lag rather than a real miss.
49
+ *
50
+ * Matched on Bun's exact phrasing, and deliberately narrow: any other failure
51
+ * (a package that does not exist, auth, network) is real and must surface
52
+ * rather than being retried into a timeout.
53
+ */
54
+ export function isPropagationLag(output: string): boolean {
55
+ return /No version matching .* found for specifier .*\(but package exists\)/.test(output)
56
+ }
57
+
58
+ /** Backoff before attempt N (1-indexed): 1s, 2s, 4s, 8s, 16s, 32s. */
59
+ export function propagationDelay(attempt: number): number {
60
+ return 1_000 * 2 ** (attempt - 1)
61
+ }
62
+
63
+ /** Worst-case total wait, for callers that want to say how long this may take. */
64
+ export function propagationBudgetMs(): number {
65
+ let total = 0
66
+ for (let n = 1; n < PROPAGATION_ATTEMPTS; n++) total += propagationDelay(n)
67
+ return total
68
+ }
69
+
70
+ export type PropagationAttempt = {
71
+ /** Did it succeed? */
72
+ ok: boolean
73
+ /**
74
+ * Combined output, for classifying the failure — omit when the caller
75
+ * cannot capture it.
76
+ *
77
+ * The updater is exactly that case: it runs bun with `stderr: "inherit"`
78
+ * so the user watches the install progress directly, which means the text
79
+ * this classifies on never comes back to it. Absent output retries
80
+ * unconditionally, which is what that path already did and is correct for
81
+ * it — a failed global install is worth a few seconds either way.
82
+ */
83
+ output?: string
84
+ }
85
+
86
+ /**
87
+ * Run `attempt` until it succeeds or stops looking like propagation lag.
88
+ *
89
+ * `onRetry` reports the wait so a multi-second pause is legible rather than
90
+ * looking like a hang — a caller with no surface can pass nothing.
91
+ */
92
+ export async function withPropagationRetry(
93
+ attempt: (n: number) => Promise<PropagationAttempt>,
94
+ opts: {
95
+ sleep?: (ms: number) => Promise<void>
96
+ onRetry?: (delayMs: number, attempt: number) => void
97
+ } = {},
98
+ ): Promise<PropagationAttempt> {
99
+ const sleep = opts.sleep ?? Bun.sleep
100
+ let last: PropagationAttempt = { ok: false, output: "" }
101
+
102
+ for (let n = 1; n <= PROPAGATION_ATTEMPTS; n++) {
103
+ last = await attempt(n)
104
+ if (last.ok) return last
105
+
106
+ // Only lag is worth waiting on when we can tell. A genuine failure
107
+ // surfaces at once rather than costing seven seconds to say the same
108
+ // thing — but a caller that cannot read the output cannot make that
109
+ // distinction, and retrying is the safer default there.
110
+ if (last.output !== undefined && !isPropagationLag(last.output)) return last
111
+
112
+ if (n < PROPAGATION_ATTEMPTS) {
113
+ const delay = propagationDelay(n)
114
+ opts.onRetry?.(delay, n)
115
+ await sleep(delay)
116
+ }
117
+ }
118
+
119
+ return last
120
+ }