@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,385 @@
1
+ import { dirname, join, relative, sep } from "node:path"
2
+ import { lstat, mkdir, readFile, rm, writeFile } from "node:fs/promises"
3
+ import { err } from "@arcforge/err"
4
+ import { fsx } from "../../../utils/fs"
5
+ import type { StageT } from "./stage"
6
+
7
+ /**
8
+ * Assets — an author's `assets/` folder, validated and compressed into
9
+ * publishable bytes.
10
+ *
11
+ * README screenshots used to live wherever the author could get a URL — in
12
+ * practice a Discord CDN link, which is an attachment URL carrying an expiry
13
+ * signature in its query string. A README is permanent and that link is not,
14
+ * so every published package was accumulating images that would eventually
15
+ * render as broken boxes on a page we serve.
16
+ *
17
+ * So assets become part of the artifact: unpacked to
18
+ * `<kind>s/<id>/versions/<v>/assets/` on publish and addressed relatively
19
+ * (`./assets/x.png`), so one README renders correctly in the repo, on GitHub,
20
+ * and on the site.
21
+ *
22
+ * ── They are a SEPARATE artifact from source.tar.gz, deliberately ───────────
23
+ *
24
+ * This produces its own `assets.tar.gz`, uploaded as its own multipart part.
25
+ * The first version of this shipped assets INSIDE source.tar.gz on the grounds
26
+ * that an asset is a source file the author committed — which is true about
27
+ * provenance and irrelevant to distribution. Measured on @axon/ember-theme:
28
+ * 60,272 of 60,844 bytes (99%) of the install payload was docs screenshots for
29
+ * 5KB of actual code, downloaded by every `axon install` and every transitive
30
+ * dependency resolution, and read by nobody — the site serves the unpacked
31
+ * per-version objects, never the tarball copy.
32
+ *
33
+ * A 10MB demo video for a 100KB extension is the case that makes it obvious.
34
+ * Docs media must not be on the install path, so the two payloads stay apart
35
+ * all the way from the bundler to storage.
36
+ *
37
+ * ── Why this is a leaf and not a row in the kind table ──────────────────────
38
+ *
39
+ * KINDS.files exists for per-kind tarball entries, and assets are NOT per-kind
40
+ * — every source-published kind gets them on the same terms. More importantly
41
+ * an asset is not just an entry to copy: it is validated, re-encoded, budgeted
42
+ * and packaged, which is real work that belongs to something that owns it. The
43
+ * kind table stays a table of differences.
44
+ *
45
+ * ── The staging directory ──────────────────────────────────────────────────
46
+ *
47
+ * Processed bytes cannot be written back over the author's files — that is
48
+ * destroying source in order to publish it. So `collect()` writes compressed
49
+ * assets into the bundle directory under `.assets/assets/…` and tars THAT,
50
+ * giving an archive whose members are `assets/<path>`. The author's `assets/`
51
+ * is never modified.
52
+ */
53
+
54
+ /**
55
+ * Per-asset ceiling.
56
+ *
57
+ * Generous because assets are OFF the install path: they ship as their own
58
+ * tarball, are unpacked to per-version objects, and are fetched only by someone
59
+ * actually looking at the page. A 10MB demo video costs that one viewer, not
60
+ * every `axon install` — which is the whole reason this is not in source.tar.gz.
61
+ */
62
+ const MAX_ASSET_BYTES = 10 * 1024 * 1024
63
+
64
+ /**
65
+ * Ceiling for the folder as a whole.
66
+ *
67
+ * Still bounded: every published version stores its own copy forever, and the
68
+ * publish request has to carry the bytes in one piece.
69
+ */
70
+ const MAX_TOTAL_BYTES = 25 * 1024 * 1024
71
+
72
+ /**
73
+ * Raster formats we recompress. Each is re-encoded in its OWN format — see
74
+ * `compress` for why the filename must never change.
75
+ *
76
+ * GIF is included but handled as animated: re-encoding an animated GIF to a
77
+ * still frame would silently destroy the thing it was uploaded to show.
78
+ */
79
+ const IMAGE_EXTENSIONS = new Set(["png", "jpg", "jpeg", "webp", "gif"])
80
+
81
+ /**
82
+ * Video is passed through untouched — validated, never transcoded.
83
+ *
84
+ * Transcoding needs ffmpeg, which is not a dependency `axon publish` can
85
+ * assume on a user's machine; compressing when present and skipping when
86
+ * absent would mean the same input publishes different bytes depending on who
87
+ * ran it. A size limit is the honest guardrail.
88
+ */
89
+ const VIDEO_EXTENSIONS = new Set(["mp4", "webm", "mov"])
90
+
91
+ /**
92
+ * SVG is deliberately absent from both sets.
93
+ *
94
+ * An SVG is an executable document — it can carry `<script>` and event
95
+ * handlers — and these bytes are served from our own storage origin, so a
96
+ * published SVG is a stored-XSS vector against every visitor reading that
97
+ * README. Accepting it would mean owning an SVG sanitizer as a security
98
+ * boundary, which is a large commitment for a screenshot format.
99
+ */
100
+ const REFUSED_EXTENSIONS = new Set(["svg", "svgz"])
101
+
102
+ /** Longest edge we keep. A README column is ~700px; 1600 covers retina. */
103
+ const MAX_IMAGE_WIDTH = 1600
104
+
105
+ /** Lossy encoders only — PNG and GIF stay lossless (see `encodeAs`). */
106
+ const WEBP_QUALITY = 80
107
+ const JPEG_QUALITY = 82
108
+
109
+ /** What one asset became, for the CLI's publish report. */
110
+ export type AssetReport = {
111
+ /** Path relative to the project root, as the README would reference it. */
112
+ path: string
113
+ /** Bytes on the author's disk. */
114
+ original: number
115
+ /** Bytes as published. Equal to `original` when passed through. */
116
+ final: number
117
+ /** True when we re-encoded it. */
118
+ compressed: boolean
119
+ }
120
+
121
+ export type AssetsResult = {
122
+ /**
123
+ * Absolute path to `assets.tar.gz`, or null when the project has no assets.
124
+ *
125
+ * Its members are `assets/<path>` — no npm `package/` prefix, because this
126
+ * archive is never installed by a package manager. It is uploaded as its own
127
+ * publish part, unpacked server-side into per-version objects, and then
128
+ * discarded: keeping it would store every asset twice forever for no reader.
129
+ */
130
+ tarball: string | null
131
+ /** Every asset published, in tarball order. */
132
+ assets: AssetReport[]
133
+ /** Total published bytes. */
134
+ total: number
135
+ }
136
+
137
+ type AssetsOpts = {
138
+ root: string
139
+ /** Packaging is Stage's job — this leaf owns validation and compression. */
140
+ stage: Pick<StageT, "tar">
141
+ }
142
+
143
+ export function Assets(opts: AssetsOpts) {
144
+ const root = opts.root
145
+
146
+ return {
147
+ /**
148
+ * Validate and compress `assets/` into `<bundleDir>/assets.tar.gz`.
149
+ *
150
+ * Returns `{ tarball: null }` when the project has no assets folder —
151
+ * an absent folder is an ordinary state, not a failure. An INVALID asset
152
+ * is a failure and throws: a refused type or an over-budget file is
153
+ * something the author must see before it becomes an immutable
154
+ * published version.
155
+ */
156
+ async collect(bundleDir: string): Promise<AssetsResult> {
157
+ const sourceDir = join(root, "assets")
158
+ if (!fsx.exists(sourceDir)) return { tarball: null, assets: [], total: 0 }
159
+
160
+ const found = await fsx.walk(sourceDir)
161
+ if (found.length === 0) return { tarball: null, assets: [], total: 0 }
162
+
163
+ // `<bundleDir>/.assets/assets/…` — the trailing `assets` is the
164
+ // directory name as it must appear INSIDE the archive, so taring
165
+ // `.assets` with the entry `assets` yields members named
166
+ // `assets/<path>`. That is what the server unpacks by prefix.
167
+ const stageDir = join(bundleDir, ".assets")
168
+ const targetDir = join(stageDir, "assets")
169
+ const reports: AssetReport[] = []
170
+ let total = 0
171
+
172
+ for (const file of found) {
173
+ // A symlink is refused rather than followed. Following one
174
+ // publishes bytes from outside the project (`assets/x.png` ->
175
+ // `~/.ssh/id_rsa` is a valid symlink), and the archive would
176
+ // carry a link the server then has to decide how to extract.
177
+ const info = await lstat(file.absPath)
178
+ if (info.isSymbolicLink()) {
179
+ throw err("ASSET_PATH_INVALID", {
180
+ detail: `assets/${file.relPath} is a symlink`,
181
+ context: { path: file.relPath },
182
+ })
183
+ }
184
+
185
+ // `walk` builds relPath by joining names, so this cannot
186
+ // currently escape — asserted anyway because the guarantee that
187
+ // matters is about the path we WRITE, and that must not depend
188
+ // on a helper two modules away keeping its current behaviour.
189
+ const destination = join(targetDir, file.relPath)
190
+ if (!isInside(targetDir, destination)) {
191
+ throw err("ASSET_PATH_INVALID", {
192
+ detail: `assets/${file.relPath} escapes the assets directory`,
193
+ context: { path: file.relPath },
194
+ })
195
+ }
196
+
197
+ const extension = extensionOf(file.relPath)
198
+ if (REFUSED_EXTENSIONS.has(extension)) {
199
+ throw err("ASSET_TYPE_REFUSED", {
200
+ detail: `assets/${file.relPath} is an SVG — SVG can carry scripts and is not served from the registry`,
201
+ context: { path: file.relPath, extension },
202
+ })
203
+ }
204
+
205
+ const isImage = IMAGE_EXTENSIONS.has(extension)
206
+ const isVideo = VIDEO_EXTENSIONS.has(extension)
207
+ if (!isImage && !isVideo) {
208
+ throw err("ASSET_TYPE_REFUSED", {
209
+ detail:
210
+ `assets/${file.relPath} has unsupported extension ".${extension}" — `
211
+ + `accepted: ${[...IMAGE_EXTENSIONS, ...VIDEO_EXTENSIONS].join(", ")}`,
212
+ context: { path: file.relPath, extension },
213
+ })
214
+ }
215
+
216
+ const original = await readFile(file.absPath)
217
+
218
+ // Checked BEFORE compression as well as after: a 400MB PNG
219
+ // must be refused rather than handed to an image decoder that
220
+ // will try to hold it, and its decompressed pixel buffer is
221
+ // far larger than the file on disk.
222
+ if (original.byteLength > MAX_ASSET_BYTES) {
223
+ throw err("ASSET_TOO_LARGE", {
224
+ detail: `assets/${file.relPath} is ${mb(original.byteLength)} (max ${mb(MAX_ASSET_BYTES)} per asset)`,
225
+ context: { path: file.relPath, bytes: original.byteLength, limit: MAX_ASSET_BYTES },
226
+ })
227
+ }
228
+
229
+ const output = isImage
230
+ ? await compress(original, file.relPath, extension)
231
+ : { data: original, path: file.relPath, compressed: false }
232
+
233
+ const finalDestination = join(targetDir, output.path)
234
+ await mkdir(dirname(finalDestination), { recursive: true })
235
+ await writeFile(finalDestination, output.data)
236
+
237
+ total += output.data.byteLength
238
+ reports.push({
239
+ path: `assets/${output.path}`,
240
+ original: original.byteLength,
241
+ final: output.data.byteLength,
242
+ compressed: output.compressed,
243
+ })
244
+ }
245
+
246
+ if (total > MAX_TOTAL_BYTES) {
247
+ throw err("ASSETS_BUDGET_EXCEEDED", {
248
+ detail: `assets/ totals ${mb(total)} after compression (max ${mb(MAX_TOTAL_BYTES)} per version)`,
249
+ context: { bytes: total, limit: MAX_TOTAL_BYTES },
250
+ })
251
+ }
252
+
253
+ // Tar `assets` FROM the staging dir, so every member is named
254
+ // `assets/<path>` — no npm `package/` prefix, because nothing
255
+ // installs this archive.
256
+ const tarball = join(bundleDir, "assets.tar.gz")
257
+ try {
258
+ await opts.stage.tar(stageDir, tarball, ["assets"])
259
+ } finally {
260
+ // The staged copies exist only to be packaged. Left behind they
261
+ // would be a second copy of every asset in the project tree,
262
+ // and a stale one after the next edit.
263
+ await rm(stageDir, { recursive: true, force: true })
264
+ }
265
+
266
+ return { tarball, assets: reports, total }
267
+ },
268
+ }
269
+ }
270
+
271
+ export type AssetsT = ReturnType<typeof Assets>
272
+
273
+ /**
274
+ * Compress a raster image IN ITS OWN FORMAT, or return it untouched when that
275
+ * would make it larger.
276
+ *
277
+ * ── The filename never changes, and that is a hard requirement ──────────────
278
+ *
279
+ * An earlier version converted everything to WebP and renamed the file. That
280
+ * silently broke every README it touched: the author writes
281
+ * `./assets/ember.png`, the site resolves exactly that path, and the object in
282
+ * storage was `ember.webp` — a 404 on every compressed image, discovered only
283
+ * by rendering the page. A rename would force the SITE to guess what the
284
+ * BUNDLER did to a filename, which is a coupling with no upside.
285
+ *
286
+ * Keeping the format also keeps content-type honest. The backend derives the
287
+ * type from the extension, so `.png` holding WebP bytes would be served as
288
+ * `image/png` — a lie that browsers tolerate unevenly.
289
+ *
290
+ * And on real content it is simply better: a terminal screenshot is flat colour
291
+ * with sharp edges, exactly what PNG's palette encoder is for. Measured on
292
+ * ember-theme, format-preserving PNG beat WebP 13KB to 29KB from a 34KB source.
293
+ * Lossy WebP only wins on photographs, which a README rarely contains.
294
+ *
295
+ * ── Why sharp is imported here and not at the top of the file ──────────────
296
+ *
297
+ * sharp is a NATIVE module, and this file is reachable from
298
+ * `@arcforge/platform/build/project` — the same barrel the Fleet VS Code
299
+ * extension imports `Frame` from. A top-level import would load a native
300
+ * binary into the extension host on any Fleet startup, for a code path
301
+ * publishing never runs there. Importing inside the one function that needs it
302
+ * keeps the cost on `axon publish` alone.
303
+ */
304
+ async function compress(
305
+ data: Buffer,
306
+ path: string,
307
+ extension: string,
308
+ ): Promise<{ data: Buffer; path: string; compressed: boolean }> {
309
+ const sharp = (await import("sharp")).default
310
+
311
+ // An animated GIF re-encoded without `animated: true` collapses to its
312
+ // first frame — a terminal demo silently becoming a screenshot.
313
+ const animated = extension === "gif"
314
+
315
+ let encoded: Buffer
316
+ try {
317
+ const pipeline = sharp(data, { animated })
318
+ .resize({ width: MAX_IMAGE_WIDTH, withoutEnlargement: true })
319
+
320
+ encoded = await encodeAs(pipeline, extension).toBuffer()
321
+ } catch (cause) {
322
+ // A file named .png that sharp cannot decode is corrupt or mislabelled.
323
+ // Publishing it would ship a broken image, so this throws rather than
324
+ // falling back to the original bytes.
325
+ throw err("ASSET_UNREADABLE", {
326
+ detail: `assets/${path} could not be decoded as an image`,
327
+ context: { path },
328
+ cause,
329
+ })
330
+ }
331
+
332
+ // Already-optimized art can come out bigger — keeping the original is both
333
+ // smaller and fewer transformations to explain.
334
+ if (encoded.byteLength >= data.byteLength) {
335
+ return { data, path, compressed: false }
336
+ }
337
+
338
+ return { data: encoded, path, compressed: true }
339
+ }
340
+
341
+ /**
342
+ * Apply the encoder for the image's OWN format.
343
+ *
344
+ * `palette: true` on PNG is what does the real work on screenshots: it quantizes
345
+ * to an indexed palette, which is how a flat-colour terminal capture goes from
346
+ * 34KB to 13KB. Lossless for images that already have few colours, which a
347
+ * terminal screenshot does by construction.
348
+ */
349
+ function encodeAs(pipeline: import("sharp").Sharp, extension: string): import("sharp").Sharp {
350
+ switch (extension) {
351
+ case "png":
352
+ return pipeline.png({ compressionLevel: 9, palette: true })
353
+ case "jpg":
354
+ case "jpeg":
355
+ return pipeline.jpeg({ quality: JPEG_QUALITY, mozjpeg: true })
356
+ case "webp":
357
+ return pipeline.webp({ quality: WEBP_QUALITY })
358
+ case "gif":
359
+ return pipeline.gif()
360
+ default:
361
+ // Unreachable: callers gate on IMAGE_EXTENSIONS. Throwing rather
362
+ // than passing bytes through keeps "which formats are compressed"
363
+ // answerable in one place instead of two that can disagree.
364
+ throw err("ASSET_TYPE_REFUSED", {
365
+ detail: `no encoder for image extension ".${extension}"`,
366
+ context: { extension },
367
+ })
368
+ }
369
+ }
370
+
371
+ function extensionOf(path: string): string {
372
+ return path.toLowerCase().match(/\.([a-z0-9]+)$/)?.[1] ?? ""
373
+ }
374
+
375
+ /** Is `target` inside `parent` — the path-traversal assertion. */
376
+ function isInside(parent: string, target: string): boolean {
377
+ const rel = relative(parent, target)
378
+ return rel !== "" && !rel.startsWith("..") && !rel.startsWith(sep)
379
+ }
380
+
381
+ function mb(bytes: number): string {
382
+ if (bytes < 1024) return `${bytes}B`
383
+ if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`
384
+ return `${(bytes / (1024 * 1024)).toFixed(1)}MB`
385
+ }
@@ -0,0 +1,160 @@
1
+ import { KINDS, type ProjectKind } from "../kinds"
2
+ import { Frame } from "../../frame"
3
+ import { Agent } from "./agent"
4
+ import { Artifacts } from "./artifacts"
5
+ import { Module } from "./module"
6
+ import { Source } from "./source"
7
+ import { Stage } from "./stage"
8
+ import type { ManifestT } from "../manifest"
9
+ import type { SourceModulesT } from "../modules"
10
+ import type { BundleArtifact, BundleIdentity, BundleImage, SourceImage } from "./types"
11
+
12
+ type BundleOpts = {
13
+ root: string
14
+ /** The project's declaration files — where a bundle's identity comes from. */
15
+ manifest: ManifestT
16
+ /** Local source modules — staged into an agent bundle with their imports rebased. */
17
+ modules: SourceModulesT
18
+ /**
19
+ * Bring the project's dependencies up to date before packaging it.
20
+ *
21
+ * A GETTER because Prepare() is constructed after Bundle() and needs it —
22
+ * resolving at call time rather than construction time breaks the cycle
23
+ * without reordering the composition root.
24
+ */
25
+ prepare: () => () => Promise<unknown>
26
+ }
27
+
28
+ /**
29
+ * Bundle — package a project into its publishable artifact.
30
+ *
31
+ * Agent → .agent/build/image.json + source.tar.gz (deploy upload)
32
+ * Module → .module/build/image.json + manifest.json + source.tar.gz (registry publish)
33
+ * Source → .<kind>/build/image.json + source.tar.gz (cognet, bench, prompt)
34
+ *
35
+ * Which bundler runs is read from the kind table's `bundle` field, not
36
+ * branched on here — the same table every other per-kind decision reads. It
37
+ * used to be an `if (kind === "agent") … if (kind === "module") …` chain
38
+ * duplicated across project.ts and publish.ts, which is exactly the shape
39
+ * kinds.ts exists to prevent.
40
+ *
41
+ * Metadata comes from package.json (canonical name/version) and, for agents,
42
+ * from the evaluated config via Config() — the old regex-parsing of
43
+ * axon.config.ts is gone; a config too broken to evaluate is too broken to ship.
44
+ *
45
+ * ONE verb: build(). It returns the artifact — identity, directory and tarball
46
+ * together — because the directory only means anything once the build that
47
+ * filled it has run. Handing out a path separately made that ordering
48
+ * load-bearing and invisible: a caller that read the path before building
49
+ * uploaded whatever the last build left there, silently. A value cannot be
50
+ * obtained before the work that produces it, so the hazard is gone rather than
51
+ * documented.
52
+ */
53
+ export function Bundle(opts: BundleOpts) {
54
+ const root = opts.root
55
+
56
+ const artifacts = Artifacts({ root: root, manifest: opts.manifest })
57
+ const stage = Stage({ root: root })
58
+
59
+ const agent = Agent({ root: root, artifacts: artifacts, stage: stage, modules: opts.modules })
60
+ const module = Module({ root: root, artifacts: artifacts, stage: stage })
61
+ const source = Source({ root: root, artifacts: artifacts, stage: stage })
62
+
63
+ async function run(kind: ProjectKind): Promise<BundleArtifact> {
64
+ // Prepare first, unconditionally.
65
+ //
66
+ // `build`, `publish` and `deploy` all arrive here, and none of them
67
+ // prepared — only `dev`/`run` did, through RunningAgent. So an agent
68
+ // that had never been run could not be built: its cognet is declared
69
+ // (or defaulted to @axon/zero) but was never installed, and packaging
70
+ // failed with COGNET_NOT_FOUND naming a node_modules tree nobody had
71
+ // populated. On `deploy` that surfaced after provisioning was paid for.
72
+ //
73
+ // Idempotent, so the cost when everything is current is a few reads.
74
+ await opts.prepare()()
75
+
76
+ const via = KINDS[kind].bundle
77
+ const dir = Frame({ root: root, kind: kind }).path("build")
78
+
79
+ const result = via === "agent"
80
+ ? await agent.build()
81
+ : via === "module"
82
+ ? await module.build()
83
+ : await source.build(kind as SourceImage["kind"])
84
+
85
+ return {
86
+ image: result.image,
87
+ identity: identityOf(result.image),
88
+ dir,
89
+ tarball: result.tarball,
90
+ // Absent for agent and module bundles, which have no README to
91
+ // illustrate — a real "this kind carries none", not a masked null.
92
+ assets: result.assets ?? [],
93
+ assetsTarball: result.assetsTarball ?? null,
94
+ }
95
+ }
96
+
97
+ return {
98
+ /**
99
+ * Package this project and return the artifact.
100
+ *
101
+ * Always rebuilds. A bundle is a projection of the whole source tree,
102
+ * and nothing here is watching it — an earlier version of this cached
103
+ * on the package.json version, which served a stale tarball to anyone
104
+ * who edited a source file without bumping (caught by "re-bundling
105
+ * replaces the previous .agent bundle"). Detecting that properly means
106
+ * hashing the tree including node_modules, which costs more than the
107
+ * rebuild it would save.
108
+ *
109
+ * Callers that need the artifact at several points in ONE operation
110
+ * should hold the value rather than calling again — see session().
111
+ */
112
+ build: run,
113
+
114
+ /**
115
+ * A bundling session for one publish/deploy: builds at most once,
116
+ * unless something invalidates the artifact.
117
+ *
118
+ * Publish needs the identity to register and the directory to upload,
119
+ * and on a version collision must rebuild after bumping the patch —
120
+ * three touch points, one build. `rebuild()` is explicit rather than
121
+ * inferred, because the ONE thing that legitimately invalidates a
122
+ * bundle mid-operation is a caller that just rewrote package.json and
123
+ * knows it.
124
+ */
125
+ session(kind: ProjectKind) {
126
+ let artifact: BundleArtifact | null = null
127
+
128
+ return {
129
+ /** The artifact, built on first call and reused thereafter. */
130
+ async current(): Promise<BundleArtifact> {
131
+ artifact ??= await run(kind)
132
+ return artifact
133
+ },
134
+
135
+ /** Discard and rebuild — call after mutating package.json. */
136
+ async rebuild(): Promise<BundleArtifact> {
137
+ artifact = await run(kind)
138
+ return artifact
139
+ },
140
+ }
141
+ },
142
+ }
143
+ }
144
+
145
+ export type BundleT = ReturnType<typeof Bundle>
146
+
147
+ /**
148
+ * Every image spells its name differently (agentId / moduleId / name). Callers
149
+ * register against one identity and care about none of that, so the difference
150
+ * is normalised here — a new kind adds a bundler and nothing else.
151
+ */
152
+ function identityOf(image: BundleImage): BundleIdentity {
153
+ const name = "agentId" in image ? image.agentId : "moduleId" in image ? image.moduleId : image.name
154
+ return {
155
+ name,
156
+ version: image.version,
157
+ public: image.public,
158
+ ...(image.description !== undefined ? { description: image.description } : {}),
159
+ }
160
+ }
@@ -0,0 +1,102 @@
1
+ import { readFile } from "node:fs/promises"
2
+ import { dirname, relative, resolve } from "node:path"
3
+ import { err } from "@arcforge/err"
4
+
5
+ /**
6
+ * Refuse a config that imports from outside the project.
7
+ *
8
+ * ── Why this is a bundle-time check ────────────────────────────────────────
9
+ *
10
+ * A bundle contains the project directory and nothing above it. An agent whose
11
+ * `axon.config.ts` reaches upward — `import Cognet from "../../cognets/zero"` —
12
+ * therefore publishes a config that imports a file which was never shipped. It
13
+ * runs perfectly on the machine that wrote it and dies at boot in the cloud
14
+ * with `Cannot find module`, from inside a container, AFTER provisioning has
15
+ * been paid for. `axon build` reported success the whole time.
16
+ *
17
+ * So the check runs where the tarball is assembled, which is what makes it
18
+ * cover `publish` as well: a published agent with this fault is broken for
19
+ * everyone who installs it, not only for the author.
20
+ *
21
+ * ── Why refusing rather than rewriting ────────────────────────────────────
22
+ *
23
+ * The `cognet:` case looks rewritable — the compiled brain is staged at a path
24
+ * the manifest already declares, so the import could be pointed there. But
25
+ * that is a special case masking a general fault: any out-of-root import has
26
+ * the same problem, and a shared `../lib/utils` cannot be rewritten into
27
+ * anything. Patching the one shape we recognise would leave the others failing
28
+ * exactly as they do now, with the added confusion that one of them silently
29
+ * worked.
30
+ *
31
+ * ── Scope ──────────────────────────────────────────────────────────────────
32
+ *
33
+ * The config only. It is the file the container evaluates before anything
34
+ * else, so it is where this fails first and hardest, and checking it needs no
35
+ * import graph. A `src/` file reaching upward is the same fault and is NOT
36
+ * caught here — worth widening to when there is a reason to walk the graph.
37
+ */
38
+
39
+ /** A relative specifier in an import/export/`from` position, or a bare `import(...)`. */
40
+ const SPECIFIER = /(?:^|\s)(?:import|export)[\s\S]*?from\s*["']([^"']+)["']|import\s*\(\s*["']([^"']+)["']\s*\)/g
41
+
42
+ export type EscapingImport = {
43
+ /** The specifier as written. */
44
+ specifier: string
45
+ /** 1-based line it appears on, for the report. */
46
+ line: number
47
+ }
48
+
49
+ /**
50
+ * Relative specifiers in `source` that resolve outside `root`.
51
+ *
52
+ * Bare specifiers (`@axon/zero`, `node:fs`) are skipped: those are package
53
+ * names resolved from node_modules, which the bundle carries or the consumer
54
+ * installs. Only a path can escape.
55
+ */
56
+ export function escapingImports(source: string, configPath: string, root: string): EscapingImport[] {
57
+ const from = dirname(configPath)
58
+ const found: EscapingImport[] = []
59
+
60
+ for (const match of source.matchAll(SPECIFIER)) {
61
+ const specifier = match[1] ?? match[2]
62
+ if (!specifier || !specifier.startsWith(".")) continue
63
+
64
+ const target = resolve(from, specifier)
65
+ const rel = relative(root, target)
66
+ // `..` at the front, or an absolute result, means the path left the
67
+ // tree. relative() is the reliable test — a string comparison misses
68
+ // `./a/../../b`.
69
+ if (!rel.startsWith("..") && rel !== "") continue
70
+
71
+ // Counted to where the SPECIFIER sits, not to the match start: the
72
+ // pattern's leading `(?:^|\s)` swallows the preceding newline, so
73
+ // measuring from match.index reports the line above.
74
+ found.push({
75
+ specifier,
76
+ line: source.slice(0, source.indexOf(specifier, match.index)).split("\n").length,
77
+ })
78
+ }
79
+
80
+ return found
81
+ }
82
+
83
+ /** Throw if the project's config imports anything from outside `root`. */
84
+ export async function assertConfigContained(root: string, configPath: string): Promise<void> {
85
+ const source = await readFile(configPath, "utf-8").catch(() => null)
86
+ if (source === null) return
87
+
88
+ const escaping = escapingImports(source, configPath, root)
89
+ if (escaping.length === 0) return
90
+
91
+ const where = escaping
92
+ .map(entry => `${relative(root, configPath)}:${entry.line} ${entry.specifier}`)
93
+ .join("\n")
94
+
95
+ throw err("CONFIG_IMPORT_ESCAPES_ROOT", {
96
+ detail: where,
97
+ context: {
98
+ imports: escaping.map(entry => entry.specifier),
99
+ root,
100
+ },
101
+ })
102
+ }
@@ -0,0 +1,16 @@
1
+ // bundle — package a project into its publishable artifact.
2
+ // Bundle() is the module's single entry point.
3
+
4
+ export { Bundle, type BundleT } from "./bundle"
5
+ export type { ArtifactsT } from "./artifacts"
6
+ // Assets is exported as well as its types: the source bundler owns the publish
7
+ // path, but the leaf is independently testable and worth keeping that way.
8
+ export { Assets, type AssetsT, type AssetReport, type AssetsResult } from "./assets"
9
+ export type {
10
+ AgentImage,
11
+ ModuleImage,
12
+ SourceImage,
13
+ BundleImage,
14
+ BundleArtifact,
15
+ BundleIdentity,
16
+ } from "./types"