@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,312 @@
1
+ import { existsSync } from "node:fs"
2
+ import { mkdtemp, mkdir, readdir, rename, rm } from "node:fs/promises"
3
+ import { dirname, join } from "node:path"
4
+ import { err } from "@arcforge/err"
5
+ import { bundleCognet } from "../../blueprint/cognet/bundle"
6
+ import { Tools } from "../../blueprint/scan/tools"
7
+ import { DisposerSink, loadSource } from "../../extensions/load"
8
+ import type { ProjectKind } from "../kinds"
9
+
10
+ /**
11
+ * Verify a built artifact by BUILDING IT THE WAY A CONSUMER WILL.
12
+ *
13
+ * A published version is immutable: a broken artifact cannot be repaired, only
14
+ * superseded, and every consumer who already resolved it stays stuck until
15
+ * they explicitly move. So the last moment a defect is cheap is here, before
16
+ * `artifacts.create()` — after which it is permanent and someone else's
17
+ * problem.
18
+ *
19
+ * Everything publish did until now concerned TRANSPORT: tar the files, upload,
20
+ * register. Nothing asked whether the thing being shipped works. That is how a
21
+ * cognet went out whose `src/main.ts` imported `../config` while the packager's
22
+ * whitelist dropped `config.ts` from the tarball — valid gzip, correct
23
+ * metadata, accepted by the registry, resolvable, downloadable, and impossible
24
+ * to compile. The only place it could fail was a consumer's machine, naming a
25
+ * path that existed on the author's disk and nowhere else.
26
+ *
27
+ * THIS MUST REUSE THE CONSUMER'S OWN CODE PATH. A parallel "is it valid?"
28
+ * checker is a second model of correctness, and a second model can drift from
29
+ * the first — which is precisely the bug being fixed. Calling bundleCognet()
30
+ * means this gate cannot disagree with the consumer, because it IS the
31
+ * consumer.
32
+ *
33
+ * It verifies the TARBALL, not the project directory. The tarball is the
34
+ * artifact; the project root always holds every file whether or not it
35
+ * shipped, so building from the root would pass exactly when the bug is
36
+ * present.
37
+ */
38
+
39
+ type VerifyOpts = {
40
+ kind: ProjectKind
41
+ /** Absolute path to the built source.tar.gz — the thing consumers download. */
42
+ tarball: string
43
+ /**
44
+ * The project root. Used ONLY to resolve the installed cognet runtime the
45
+ * bundle fuses to — the source being compiled comes from the tarball.
46
+ */
47
+ root: string
48
+ name: string
49
+ }
50
+
51
+ /**
52
+ * Kinds whose artifact is SOURCE the consumer compiles.
53
+ *
54
+ * A cognet's whole artifact is source that bundles on the consumer's machine.
55
+ *
56
+ * A module's is source in the part that matters here: its `src/tools/*.ts`
57
+ * are read by the installing agent's scanner, which compiles their TypeScript
58
+ * declarations to build the tool scope. Nothing in publishing exercised that,
59
+ * so a module whose exported signature referenced an unresolvable type
60
+ * published cleanly and failed on every consumer's install instead —
61
+ * @axon/arxiv@0.1.4 shipped with `QueryOptions` used in an exported signature
62
+ * and never re-exported, and the only surface that ever said so was a user's
63
+ * terminal mid-install.
64
+ */
65
+ /**
66
+ * An extension's is source too, and it is IMPORTED rather than compiled: the
67
+ * TUI evaluates `main.ts` and `plugins/*` on the user's machine. An import
68
+ * that cannot resolve is the same defect class as a module's unresolvable
69
+ * type — invisible to the author, fatal for every consumer, and immutable
70
+ * once published. An extension left unverified was the last kind whose
71
+ * failure surfaced only in someone else's terminal.
72
+ */
73
+ const COMPILES = new Set<ProjectKind>(["cognet", "module", "extension"])
74
+
75
+ export async function verifyArtifact(opts: VerifyOpts): Promise<void> {
76
+ if (!COMPILES.has(opts.kind)) return
77
+
78
+ // Scratch lives UNDER the project root, not in /tmp. The generated entry
79
+ // imports the cognet runtime by bare specifier, so it must sit somewhere a
80
+ // resolver can walk up from and find node_modules — which /tmp is not.
81
+ const scratch = await mkdtemp(join(opts.root, ".axon-verify-"))
82
+ try {
83
+ const extracted = join(scratch, "src")
84
+ await mkdir(extracted, { recursive: true })
85
+
86
+ // Both pipes are drained CONCURRENTLY with the wait, never after it.
87
+ // A pipe has a finite buffer (~64KB): a child that fills one blocks on
88
+ // write and never exits, so `await proc.exited` before reading is a
89
+ // deadlock waiting for a big enough tarball. Reading stderr only on
90
+ // the failure path has the same shape — it leaves an undrained pipe
91
+ // holding the event loop open on every success.
92
+ const untar = Bun.spawn(["tar", "-xzf", opts.tarball, "-C", extracted], {
93
+ stdout: "pipe",
94
+ stderr: "pipe",
95
+ })
96
+ const [untarCode, , untarStderr] = await Promise.all([
97
+ untar.exited,
98
+ new Response(untar.stdout).text(),
99
+ new Response(untar.stderr).text(),
100
+ ])
101
+ if (untarCode !== 0) {
102
+ throw err("PUBLISH_VERIFY_FAILED", {
103
+ detail: `${opts.name}: could not extract the built tarball — ${untarStderr}`,
104
+ context: { name: opts.name, tarball: opts.tarball },
105
+ })
106
+ }
107
+
108
+ // npm-format tarballs put everything under package/.
109
+ const sourceDir = join(extracted, "package")
110
+
111
+ if (opts.kind === "module") {
112
+ await verifyModuleTools(sourceDir, opts.name, scratch)
113
+ return
114
+ }
115
+
116
+ if (opts.kind === "extension") {
117
+ await verifyExtensionLoads(sourceDir, opts.name)
118
+ return
119
+ }
120
+
121
+ try {
122
+ // agentRoot is the PROJECT root, not the scratch dir: the cognet
123
+ // runtime it compiles against is resolved from an installed
124
+ // node_modules, and the extracted tarball has none. Output lands
125
+ // under scratch so a verify never touches the project's own
126
+ // .agent/ artifacts.
127
+ await bundleCognet({ sourceDir, agentRoot: opts.root, outDir: join(scratch, "out") })
128
+ } catch (cause) {
129
+ throw err("PUBLISH_VERIFY_FAILED", {
130
+ detail:
131
+ `${opts.name} was packaged but does not compile from its own artifact — `
132
+ + `a consumer installing it would hit this same error. Most often a file `
133
+ + `the source imports was not included in the package.`,
134
+ context: { name: opts.name, kind: opts.kind },
135
+ cause,
136
+ })
137
+ }
138
+ } finally {
139
+ await rm(scratch, { recursive: true, force: true })
140
+ }
141
+ }
142
+
143
+ /**
144
+ * Load an extension exactly as the TUI will, from its own artifact.
145
+ *
146
+ * Same rule as the two gates above: call the CONSUMER'S function rather than
147
+ * reimplementing the check. `loadSource` is what the TUI runs on every boot,
148
+ * so a defect it does not catch is a defect the user will not hit, and one it
149
+ * does catch is one they certainly would.
150
+ *
151
+ * ── What this can and cannot prove ──────────────────────────────────────────
152
+ *
153
+ * It proves the package RESOLVES and EVALUATES: every import present, no
154
+ * throw at module scope, syntax valid. That is the failure that matters,
155
+ * because it is total — an extension that cannot be imported contributes
156
+ * nothing at all, and the author's only signal today is a stranger's install.
157
+ *
158
+ * It cannot prove the extension is CORRECT. The globals it registers against
159
+ * belong to the TUI, so they are stubbed here: a call is recorded, never
160
+ * executed. An extension that registers a broken command still publishes,
161
+ * which is right — that is a bug in its behaviour, not in its packaging, and
162
+ * publishing is not the place to run someone's terminal.
163
+ *
164
+ * The stubs are permissive on purpose. A missing global would make this
165
+ * report a defect in OUR harness as a defect in THEIR package, which is the
166
+ * one outcome worse than not checking at all.
167
+ */
168
+ async function verifyExtensionLoads(sourceDir: string, name: string): Promise<void> {
169
+ const restore = installStubGlobals()
170
+ try {
171
+ const result = await loadSource({
172
+ root: sourceDir,
173
+ label: name,
174
+ sink: DisposerSink(),
175
+ mainError: "EXTENSION_LOAD_FAILED",
176
+ })
177
+
178
+ const failed = result.files.find(file => file.error !== null)
179
+ if (!failed) return
180
+
181
+ throw err("PUBLISH_VERIFY_FAILED", {
182
+ detail:
183
+ `${name} was packaged but does not load from its own artifact — `
184
+ + `a user installing it would hit this same error. Most often a file `
185
+ + `the source imports was not included in the package.`,
186
+ context: { name, kind: "extension", file: failed.path },
187
+ cause: failed.error,
188
+ })
189
+ } finally {
190
+ restore()
191
+ }
192
+ }
193
+
194
+ /**
195
+ * Stand-ins for the globals a config is written against, for the duration of
196
+ * one verification.
197
+ *
198
+ * A Proxy per global answers any property with a no-op returning a disposer,
199
+ * so an extension calling `commands.register(...)`, `theme.create(...)` or
200
+ * anything added later evaluates without this file needing to track the API
201
+ * surface. Keeping that list in sync would mean a new global silently failing
202
+ * every publish until someone noticed.
203
+ *
204
+ * Previous values are restored rather than deleted: this runs inside the
205
+ * user's own CLI process, which may itself have loaded a config.
206
+ */
207
+ function installStubGlobals(): () => void {
208
+ const scope = globalThis as Record<string, unknown>
209
+ const names = ["tui", "palette", "commands", "keys", "mode", "input", "agents", "theme", "lines", "components"]
210
+ const previous = new Map(names.map(key => [key, scope[key]]))
211
+
212
+ const noop = (): (() => void) => () => {}
213
+ const stub = new Proxy({}, {
214
+ get: () => noop,
215
+ // An extension may read a value (`theme.active`) as well as call a
216
+ // verb, and answering every read with a function is enough for
217
+ // evaluation to proceed.
218
+ has: () => true,
219
+ })
220
+
221
+ for (const key of names) if (previous.get(key) === undefined) scope[key] = stub
222
+
223
+ return () => {
224
+ for (const [key, value] of previous) {
225
+ if (value === undefined) delete scope[key]
226
+ else scope[key] = value
227
+ }
228
+ }
229
+ }
230
+
231
+ /**
232
+ * Compile a module's tool declarations exactly as an installing agent will.
233
+ *
234
+ * The consumer's scanner reads `src/tools/*.ts` to build the tool scope — the
235
+ * model needs each tool's signature and every type that signature names. A
236
+ * type with no resolvable definition throws on the consumer's machine, at
237
+ * install time, for an artifact that is already immutable.
238
+ *
239
+ * Same rule as the cognet gate above: this calls the CONSUMER'S function
240
+ * rather than reimplementing the check. A parallel "are these types
241
+ * resolvable?" validator would be a second model of correctness, free to
242
+ * drift from the real one — and drift is the bug class this exists to catch.
243
+ *
244
+ * VERIFYING IN THE CONSUMER'S LOCATION IS PART OF CALLING THE CONSUMER'S
245
+ * FUNCTION. This extracted to a plain scratch directory at first, and the
246
+ * distinction turned out to be the whole ballgame: TypeScript skips
247
+ * declaration emit for anything under `node_modules`, so a module that
248
+ * verified perfectly in scratch failed for every consumer that installed it.
249
+ * @axon/arxiv shipped twice that way. Same bytes, same function, different
250
+ * answer — so the location is an input to the check, and the check has to use
251
+ * the real one.
252
+ *
253
+ * A module with no tools verifies trivially: plenty are routes, plugins or
254
+ * prompts, and having nothing to declare is not a defect.
255
+ */
256
+ async function verifyModuleTools(sourceDir: string, name: string, scratch: string): Promise<void> {
257
+ if (!existsSync(join(sourceDir, "src", "tools"))) return
258
+
259
+ // Re-root the extracted package under a node_modules path, because that is
260
+ // where a consumer's copy lives and TypeScript behaves differently there.
261
+ // Named for the module so the path a consumer would have is reproduced as
262
+ // closely as the scratch allows.
263
+ const installedAs = join(scratch, "node_modules", ...name.split("/"))
264
+ await mkdir(dirname(installedAs), { recursive: true })
265
+ await rename(sourceDir, installedAs)
266
+
267
+ const toolsDir = join(installedAs, "src", "tools")
268
+ if (!existsSync(toolsDir)) return
269
+
270
+ const files = (await readdir(toolsDir))
271
+ .filter(file => file.endsWith(".ts") && !file.endsWith(".test.ts"))
272
+ .map(file => join(toolsDir, file))
273
+ if (files.length === 0) return
274
+
275
+ try {
276
+ // The consumer's ENTRY POINT, not the compiler underneath it. Tools()
277
+ // is what an installing agent calls, and it prefers the published
278
+ // manifest over recompiling — so verifying through declareTools()
279
+ // directly would test a path the consumer no longer takes, which is
280
+ // the same class of mistake as verifying in the wrong directory.
281
+ //
282
+ // `required: true` makes a failure throw rather than degrade to a
283
+ // warning: at publish time there is no running agent to keep alive,
284
+ // and a warning nobody reads is how a broken artifact ships.
285
+ const scanned = await Tools(installedAs, { required: true })
286
+
287
+ // A tool file that produced no entry is a silent omission — the model
288
+ // is never told the tool exists, and the author's only signal is its
289
+ // absence. Publishing that is worse than failing here.
290
+ if (scanned.entries.length !== files.length) {
291
+ const found = new Set(scanned.entries.map(entry => entry.name))
292
+ const missing = files
293
+ .map(file => file.slice(file.lastIndexOf("/") + 1, -3))
294
+ .filter(base => !found.has(base))
295
+ throw err("PUBLISH_VERIFY_FAILED", {
296
+ detail:
297
+ `${name} was packaged but ${missing.join(", ")} produced no tool declaration — `
298
+ + `an agent installing it would not see ${missing.length === 1 ? "that tool" : "those tools"} at all.`,
299
+ context: { name, kind: "module", missing },
300
+ })
301
+ }
302
+ } catch (cause) {
303
+ throw err("PUBLISH_VERIFY_FAILED", {
304
+ detail:
305
+ `${name} was packaged but its tools do not compile from its own artifact — `
306
+ + `an agent installing it would hit this same error, and the published `
307
+ + `version cannot be changed afterwards.`,
308
+ context: { name, kind: "module" },
309
+ cause,
310
+ })
311
+ }
312
+ }
@@ -0,0 +1,155 @@
1
+ import { HttpError } from "@arcforge/cloud"
2
+ import { err } from "@arcforge/err"
3
+ import type { ArtifactKind, AxonCloudClient } from "@arcforge/cloud"
4
+ import type { AssetReport, BundleT } from "./bundle"
5
+ import { KINDS, type ProjectKind } from "./kinds"
6
+ import type { ManifestT } from "./manifest"
7
+ import { verifyArtifact } from "./publish/verify"
8
+
9
+ export type PublishResult = {
10
+ /** package.json name — what the user calls it */
11
+ name: string
12
+ /** registry id the backend assigned */
13
+ registeredId: string
14
+ /** version actually published — patch-bumped when the local version already exists */
15
+ version: string
16
+ public: boolean
17
+ /**
18
+ * README assets that shipped, for the CLI's report. Empty for kinds that
19
+ * carry none — an author who compressed 3MB of screenshots into 800KB
20
+ * should see that happen rather than infer it.
21
+ */
22
+ assets: AssetReport[]
23
+ }
24
+
25
+ /**
26
+ * Steps surfaced through onProgress during publish.
27
+ *
28
+ * A discriminated union rather than a string so a step can carry the one fact
29
+ * that makes it meaningful — which version collided, how big the upload is —
30
+ * matching how DeployStep already reports the deploy flow.
31
+ *
32
+ * `bumped` is the reason this is not simply a linear sequence. A published
33
+ * version is immutable, so a 409 sends the flow back through bump → rebuild →
34
+ * verify, and a renderer that assumed forward-only progress would either
35
+ * freeze or silently redo completed steps. Emitting the retry makes the loop
36
+ * something the user watches rather than something they infer from a pause.
37
+ */
38
+ export type PublishStep =
39
+ | { step: "bundling" }
40
+ | { step: "verifying" }
41
+ | { step: "registering"; name: string }
42
+ | { step: "uploading"; version: string }
43
+ | { step: "bumped"; from: string; to: string }
44
+ | { step: "published"; version: string }
45
+
46
+ type PublishOpts = {
47
+ kind: ProjectKind
48
+ /** Project root — verification resolves the installed runtime from here. */
49
+ root: string
50
+ bundle: BundleT
51
+ manifest: ManifestT
52
+ cloud: AxonCloudClient
53
+ }
54
+
55
+
56
+ /**
57
+ * Narrows a ProjectKind to what the registry accepts.
58
+ *
59
+ * A predicate rather than a bare boolean check so the narrowing is real:
60
+ * `ArtifactKind` is the BACKEND's contract (a Postgres enum), and the two
61
+ * unions diverging is the whole point — a kind the registry has never heard of
62
+ * must not reach `artifacts.create()`. Casting past this would turn a compile
63
+ * error into a runtime 4xx, which is the trade this guard exists to refuse.
64
+ */
65
+ function isPublishable(kind: ProjectKind): kind is ArtifactKind {
66
+ return KINDS[kind].publishable
67
+ }
68
+
69
+ /**
70
+ * Publish — bundle, register (idempotent), upload, sync visibility.
71
+ * Uploads only — provisioning/starting compute is deploy's job (Agents.deploy).
72
+ *
73
+ * ONE path for all four kinds. It used to fork on `kind === "agent"` with
74
+ * everything else falling through to the module branch, which silently
75
+ * registered a cognet in the modules table and claimed its name in the shared
76
+ * namespace as the wrong kind. Now the kind is data: it selects a bundler and
77
+ * is sent to the backend, and nothing else about publishing differs.
78
+ *
79
+ * Published versions are immutable. A collision (backend 409) auto-bumps the
80
+ * patch in package.json, rebuilds so the tarball and registry metadata agree,
81
+ * and retries.
82
+ *
83
+ * Auth failures (401) and username-required (403) propagate as HttpError —
84
+ * the caller owns how to present them.
85
+ */
86
+ export function Publish(opts: PublishOpts) {
87
+ const { kind, bundle, manifest, cloud } = opts
88
+
89
+ return async function publish(
90
+ options: { onProgress?: (step: PublishStep) => void } = {},
91
+ ): Promise<PublishResult> {
92
+ // Absent by default so every existing caller is unchanged and a
93
+ // consumer that wants no progress pays nothing for the option.
94
+ const report = options.onProgress ?? (() => {})
95
+
96
+ // Before anything is built. Failing here costs a bundle nobody wanted,
97
+ // rather than a confusing API error after one was produced.
98
+ if (!isPublishable(kind)) throw err("PUBLISH_UNSUPPORTED_KIND", { context: { kind } })
99
+
100
+ report({ step: "bundling" })
101
+ const session = bundle.session(kind)
102
+ let artifact = await session.current()
103
+
104
+ // Before ANY registry mutation. A published version is immutable, so
105
+ // an artifact that cannot be compiled is not a bug to fix later — it
106
+ // is a permanent one, already resolving for anyone who asks. The last
107
+ // cheap moment is here.
108
+ report({ step: "verifying" })
109
+ await verifyArtifact({ kind, tarball: artifact.tarball, root: opts.root, name: artifact.identity.name })
110
+
111
+ report({ step: "registering", name: artifact.identity.name })
112
+ const handle = await cloud.registry.artifacts.create({
113
+ kind,
114
+ name: artifact.identity.name,
115
+ ...(artifact.identity.description !== undefined ? { description: artifact.identity.description } : {}),
116
+ private: !artifact.identity.public,
117
+ })
118
+
119
+ let version: string
120
+ while (true) {
121
+ try {
122
+ report({ step: "uploading", version: artifact.identity.version })
123
+ ; ({ version } = await handle.publish({ path: artifact.dir }))
124
+ break
125
+ } catch (error) {
126
+ if (!(error instanceof HttpError) || error.status !== 409) throw error
127
+ // The bump rewrites package.json, so the built artifact now
128
+ // carries the wrong version — rebuild before retrying, or the
129
+ // tarball ships the old metadata under the new number.
130
+ const from = artifact.identity.version
131
+ await manifest.package.bump(from)
132
+ artifact = await session.rebuild()
133
+ report({ step: "bumped", from, to: artifact.identity.version })
134
+ // The rebuild is a different tarball, so it earns its own
135
+ // check — a bump must not be a way around the gate. Reported
136
+ // again because it is a real second verification: leaving the
137
+ // display on "bumped" would attribute its duration to a step
138
+ // that already finished.
139
+ report({ step: "verifying" })
140
+ await verifyArtifact({ kind, tarball: artifact.tarball, root: opts.root, name: artifact.identity.name })
141
+ }
142
+ }
143
+
144
+ await handle.update({ private: !artifact.identity.public })
145
+ report({ step: "published", version })
146
+
147
+ return {
148
+ name: artifact.identity.name,
149
+ registeredId: handle.id,
150
+ version,
151
+ public: artifact.identity.public,
152
+ assets: artifact.assets,
153
+ }
154
+ }
155
+ }
@@ -0,0 +1,93 @@
1
+ import type { ManifestT } from "./manifest"
2
+ import type { TreeT } from "./tree"
3
+
4
+ /**
5
+ * Reconcile — bring the manifest and the installed tree into agreement with
6
+ * what the project actually declares.
7
+ *
8
+ * `axon prepare` is the RECONCILING command, the way `npm install` is: it
9
+ * reads the declaration, notices where reality disagrees, and fixes it. The
10
+ * reproducible counterpart is `--frozen`, which asserts agreement instead of
11
+ * creating it (see `frozen` below).
12
+ *
13
+ * Prepare used to do neither. It asked one question — "is anything missing?" —
14
+ * and every dependency bug of the last day fell out of that:
15
+ *
16
+ * - a package present at the wrong version passed as installed, because
17
+ * installed-ness was `existsSync(dir)`
18
+ * - a declared range that permitted a newer version never re-resolved, so a
19
+ * published fix could not reach an agent that already had the broken one
20
+ * - a cognet replaced in axon.config.ts left its predecessor declared
21
+ * forever, because only `file:` modules were ever pruned
22
+ * - "declared" short-circuited the install entirely, so a declared-but-
23
+ * deleted package produced an error telling the user to run the command
24
+ * that had just skipped it
25
+ *
26
+ * Each was a different symptom of the same missing step.
27
+ */
28
+
29
+ export type ReconcileResult = {
30
+ /** Dependencies Axon owns that are no longer declared — removed from package.json. */
31
+ pruned: string[]
32
+ /** True when the MANIFEST had to change. The tree's state is verify's answer. */
33
+ changed: boolean
34
+ }
35
+
36
+ type ReconcileOpts = {
37
+ manifest: ManifestT
38
+ tree: TreeT
39
+ /**
40
+ * Every dependency Axon manages for this project, and the range each
41
+ * should be declared at — the cognet plus registry modules.
42
+ *
43
+ * The map is authoritative in BOTH directions: a name present here is
44
+ * declared, and an Axon-managed name absent from it is removed. Anything
45
+ * not mentioned is the user's own dependency and is never touched.
46
+ */
47
+ managed: Record<string, string>
48
+ /**
49
+ * Names Axon has ever managed, used to decide what may be pruned.
50
+ * Deliberately wider than `managed`: pruning has to recognise the cognet
51
+ * an agent USED to declare, which by definition is not in the new map.
52
+ */
53
+ owned: (name: string) => boolean
54
+ /**
55
+ * Inspect without repairing. `--frozen` needs to know whether the project
56
+ * is in agreement, and must not become the thing that puts it there —
57
+ * a check that fixes what it finds can never fail.
58
+ */
59
+ dryRun?: boolean
60
+ }
61
+
62
+ /**
63
+ * Compare declaration against reality. Pure inspection plus manifest repair —
64
+ * it never installs, so a caller can report or gate on the result.
65
+ */
66
+ export async function reconcile(opts: ReconcileOpts): Promise<ReconcileResult> {
67
+ const { manifest, tree, managed, owned } = opts
68
+
69
+ // ── 1. manifest ← declaration ────────────────────────────────────────
70
+ const declared = await manifest.package.dependencies.all()
71
+
72
+ const dead = Object.keys(declared).filter(name => owned(name) && !(name in managed))
73
+ const pruned = dead.length === 0
74
+ ? []
75
+ : opts.dryRun ? dead : await manifest.package.dependencies.remove(dead)
76
+
77
+ const additions: Record<string, string> = {}
78
+ for (const [name, range] of Object.entries(managed)) {
79
+ if (declared[name] !== range) additions[name] = range
80
+ }
81
+ const declarationChanged = Object.keys(additions).length === 0
82
+ ? false
83
+ : opts.dryRun ? true : await manifest.package.dependencies.set(additions)
84
+
85
+ return {
86
+ pruned,
87
+ // Whether the MANIFEST had to change. Whether the TREE agrees with it
88
+ // is `tree.verify()`'s answer — this used to compute both, and two
89
+ // implementations of "is the installed tree right" is exactly how they
90
+ // drift apart. Prepare asks each for its own half.
91
+ changed: pruned.length > 0 || declarationChanged,
92
+ }
93
+ }
@@ -0,0 +1,42 @@
1
+ import { err } from "@arcforge/err"
2
+
3
+ /**
4
+ * "@axon/telegram@1.2.0" → { name: "@axon/telegram", version: "1.2.0" }
5
+ *
6
+ * Only scoped names are valid as NAMES — the registry refuses to publish
7
+ * anything else — so the leading "@" is always the scope, never a version
8
+ * marker. A bare uuid is also accepted, because it addresses the same artifact
9
+ * through the same backend lookup; what stays refused is an unscoped name,
10
+ * which can never resolve.
11
+ *
12
+ * Shared by Installer (which installs a specifier) and Registry (which clones
13
+ * or forks one). Both name the same thing: a published registry artifact,
14
+ * optionally pinned. Registry used to carry its own copy that silently
15
+ * tolerated an unscoped name and then asked the backend to resolve something
16
+ * that cannot exist.
17
+ */
18
+ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
19
+
20
+ export function parseSpecifier(specifier: string): { name: string; version: string | undefined } {
21
+ // A bare artifact id is a valid address, not a specifier: the registry
22
+ // resolves by uuid OR scoped name (see the backend's artifacts `get`), and
23
+ // `axon clone <id>` is how the dashboard's copy-id button is meant to be
24
+ // used. It carries no version — a uuid names the artifact, never a release
25
+ // — so it passes through unparsed rather than being split on its hyphens.
26
+ if (UUID.test(specifier)) return { name: specifier, version: undefined }
27
+
28
+ if (!specifier.startsWith("@")) {
29
+ throw err("MODULE_SPECIFIER_INVALID", {
30
+ detail: `"${specifier}" is not a scoped module name — expected @scope/name`,
31
+ context: { specifier: specifier },
32
+ })
33
+ }
34
+
35
+ const at = specifier.indexOf("@", 1)
36
+ if (at === -1) return { name: specifier, version: undefined }
37
+
38
+ return {
39
+ name: specifier.slice(0, at),
40
+ version: specifier.slice(at + 1) || undefined,
41
+ }
42
+ }