@exodus/stasis 1.0.0-beta.12 → 1.0.0-beta.14

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.
package/src/babel.js CHANGED
@@ -141,21 +141,38 @@ function findBabelConfig(projectDir, command) {
141
141
  return configFile
142
142
  }
143
143
 
144
+ // --babel for `stasis bundle --metro`: the project's babel.config.* for each file, loaded as Metro's
145
+ // transformer loads it (its `metro` caller, for `platform`) by @babel/core's `method` (loadPartialConfig,
146
+ // loadOptions) -- the config is project code, run here. -> (file) => what it loads, once a file
147
+ function projectBabelConfig({ projectDir, platform }, method) {
148
+ const configFile = findBabelConfig(projectDir, 'stasis bundle')
149
+ const [babelPath] = resolveFromProject(projectDir, ['@babel/core'], '--babel', 'stasis bundle')
150
+ const babel = require(babelPath)
151
+ const caller = { name: 'metro', bundler: 'metro', platform }
152
+ const byFile = new Map()
153
+ return (file) => {
154
+ if (!byFile.has(file)) {
155
+ try {
156
+ byFile.set(file, babel[method]({ cwd: projectDir, root: projectDir, configFile, filename: file, caller }))
157
+ } catch (cause) {
158
+ throw new Error(`stasis bundle: --babel could not load ${configFile} for ${file}`, { cause })
159
+ }
160
+ }
161
+ return byFile.get(file)
162
+ }
163
+ }
164
+
144
165
  // The file a plugin item names babel-plugin-module-resolver by resolves into this.
145
166
  const MODULE_RESOLVER = /[\\/]node_modules[\\/]babel-plugin-module-resolver[\\/]/u
146
167
 
147
168
  // --babel for `stasis bundle --metro`: the import aliases babel-plugin-module-resolver applies to
148
- // each file under the project's babel.config.*, loaded as Metro's transformer loads it (its `metro`
149
- // caller, for `platform`) -- the config is project code, run here. The plugin's own resolvePath (or
150
- // the config's custom one) maps each specifier, its `cwd` the project's where the config sets none,
151
- // as Metro started there has it. Every instance the config lists, by name or as a value (`require`d
152
- // or imported), counts, in order; one a preset adds doesn't.
169
+ // each file under the project's babel.config.* (projectBabelConfig's partial config). The plugin's own
170
+ // resolvePath (or the config's custom one) maps each specifier, its `cwd` the project's where the
171
+ // config sets none, as Metro started there has it. Every instance the config lists, by name or as a
172
+ // value (`require`d or imported), counts, in order; one a preset adds doesn't.
153
173
  // -> (file, specifier) => the specifier the plugin rewrites it to, else null
154
174
  export function createBabelAliases({ projectDir, platform }) {
155
- const configFile = findBabelConfig(projectDir, 'stasis bundle')
156
- const [babelPath] = resolveFromProject(projectDir, ['@babel/core'], '--babel', 'stasis bundle')
157
- const babel = require(babelPath)
158
- const caller = { name: 'metro', bundler: 'metro', platform }
175
+ const partialConfig = projectBabelConfig({ projectDir, platform }, 'loadPartialConfig')
159
176
  // The project's own copy, which a config passing the plugin as a value passes; none where the
160
177
  // project installs none.
161
178
  let projectPlugin
@@ -170,29 +187,13 @@ export function createBabelAliases({ projectDir, platform }) {
170
187
  if (resolved !== undefined) return MODULE_RESOLVER.test(resolved) ? require(resolved) : null
171
188
  return plugin.value === projectPlugin?.default ? projectPlugin : null
172
189
  }
173
- // file -> [{ resolvePath, options }] of the module-resolver instances its config applies.
174
- const byFile = new Map()
175
- const aliasingOf = (file) => {
176
- if (byFile.has(file)) return byFile.get(file)
177
- let partial
178
- try {
179
- partial = babel.loadPartialConfig({ cwd: projectDir, root: projectDir, configFile, filename: file, caller })
180
- } catch (cause) {
181
- throw new Error(`stasis bundle: --babel could not load ${configFile} for ${file}`, { cause })
182
- }
183
- const instances = []
190
+ return (file, specifier) => {
184
191
  // No partial config: the config ignores the file.
185
- for (const plugin of partial?.options.plugins ?? []) {
192
+ for (const plugin of partialConfig(file)?.options.plugins ?? []) {
186
193
  const module = moduleOf(plugin)
187
194
  if (module === null) continue
188
195
  const options = { cwd: projectDir, ...plugin.options }
189
- instances.push({ resolvePath: typeof options.resolvePath === 'function' ? options.resolvePath : module.resolvePath, options })
190
- }
191
- byFile.set(file, instances)
192
- return instances
193
- }
194
- return (file, specifier) => {
195
- for (const { resolvePath, options } of aliasingOf(file)) {
196
+ const resolvePath = typeof options.resolvePath === 'function' ? options.resolvePath : module.resolvePath
196
197
  const mapped = resolvePath(specifier, file, options)
197
198
  // The first instance mapping it wins: the plugin marks the path it writes resolved, which
198
199
  // later instances leave as it is.
@@ -202,6 +203,16 @@ export function createBabelAliases({ projectDir, platform }) {
202
203
  }
203
204
  }
204
205
 
206
+ // --babel for `stasis bundle --metro`: whether Babel keeps a statement listing types alone in `file`
207
+ // (`import { type A } from` as `import {} from`), as its TypeScript transform does under
208
+ // `onlyRemoveTypeImports`, under the project's babel.config.* (projectBabelConfig's options).
209
+ // -> (file) => boolean
210
+ export function createBabelTypeImportsKept({ projectDir, platform }) {
211
+ const options = projectBabelConfig({ projectDir, platform }, 'loadOptions')
212
+ // No options: the config ignores the file.
213
+ return (file) => (options(file)?.plugins ?? []).some((plugin) => plugin.key === 'transform-typescript' && plugin.options?.onlyRemoveTypeImports === true)
214
+ }
215
+
205
216
  // babel-plugin-module-resolver's path tests, as it writes them.
206
217
  const isRelativePath = (path) => /^\.?\.\//u.test(path)
207
218
  const toLocalPath = (path) => {
@@ -229,16 +240,12 @@ export function createAliases(alias, cwd) {
229
240
  for (const [regExp, substitute] of matchers) {
230
241
  const groups = regExp.exec(specifier)
231
242
  if (groups === null) continue
232
- return rewrite(file, specifier, substitute(groups), cwd)
243
+ // None where the mapping is empty.
244
+ const mapped = substitute(groups)
245
+ if (!mapped) return null
246
+ const rewritten = isRelativePath(mapped) ? toLocalPath(relative(dirname(file), resolve(cwd, mapped)).replace(/\\/gu, '/')) : mapped
247
+ return rewritten === specifier ? null : rewritten
233
248
  }
234
249
  return null
235
250
  }
236
251
  }
237
-
238
- // `mapped`, the alias `specifier` from `file` maps to, as the plugin writes it: none where empty, a
239
- // relative one (`./`, `../`) a path from `cwd` written relative to `file`, any other as it is.
240
- function rewrite(file, specifier, mapped, cwd) {
241
- if (!mapped) return null
242
- const rewritten = isRelativePath(mapped) ? toLocalPath(relative(dirname(file), resolve(cwd, mapped)).replace(/\\/gu, '/')) : mapped
243
- return rewritten === specifier ? null : rewritten
244
- }
@@ -2,6 +2,7 @@ import { createReadStream } from 'node:fs'
2
2
  import { pipeline } from 'node:stream/promises'
3
3
  import { createBrotliDecompress } from 'node:zlib'
4
4
 
5
+ import { trailingJunkError } from '@exodus/stasis-core/brotli'
5
6
  import { Bundle } from '@exodus/stasis-core/bundle'
6
7
  import { assert } from '@exodus/stasis-core/util'
7
8
 
@@ -18,7 +19,7 @@ const untilAborted = (promise, signal) => (signal === undefined ? promise : new
18
19
  // Left in place of each streamed file; fromJSON's contents-free mode requires one per file.
19
20
  const STREAMED = Symbol('streamed')
20
21
 
21
- // Bundle.parse(brotliDecompressSync(source)), without holding the decompressed bytes or the JSON text whole.
22
+ // parseBundleBytes(source), without holding the decompressed bytes or the JSON text whole.
22
23
  // onFile gets each file in stream order, wherever the bundle puts its files, and before the bundle is
23
24
  // validated: what it receives (format included) is provisional until readBundle resolves. See doc/file-formats.md.
24
25
  export async function readBundle(source, { onFile, signal } = {}) {
@@ -46,8 +47,26 @@ export async function readBundle(source, { onFile, signal } = {}) {
46
47
 
47
48
  // Big chunks let zlib's thread pool decompress ahead of the parser; zlib's 16 KiB default runs about 2x slower.
48
49
  const decompress = createBrotliDecompress({ chunkSize: 1024 * 1024, readableHighWaterMark: 4 * 1024 * 1024 })
50
+ // The decoder ends its output at the end of the brotli stream and consumes nothing after it, so
51
+ // the bytes it was given and the bytes it consumed (its bytesWritten) differ by exactly those.
52
+ // Counting them here takes `input` out of pipeline's hands, so this destroys a stream on pipeline's
53
+ // signal, raised on any failure or abort, as pipeline would: one waiting for a chunk holds it open.
54
+ let given = 0
55
+ async function* counted({ signal: stop }) {
56
+ const destroy = () => input.destroy?.()
57
+ stop.addEventListener('abort', destroy, { once: true })
58
+ if (stop.aborted) destroy()
59
+ try {
60
+ for await (const chunk of input) {
61
+ given += Buffer.byteLength(chunk)
62
+ yield chunk
63
+ }
64
+ } finally {
65
+ stop.removeEventListener('abort', destroy)
66
+ }
67
+ }
49
68
  let drained = false
50
- await pipeline(input, decompress, async (chunks) => {
69
+ await pipeline(counted, decompress, async (chunks) => {
51
70
  for await (const chunk of chunks) {
52
71
  parser.write(chunk)
53
72
  for (const [file, contents, format] of pending.splice(0)) {
@@ -58,9 +77,10 @@ export async function readBundle(source, { onFile, signal } = {}) {
58
77
  }
59
78
  drained = true
60
79
  }, { signal }).catch((error) => {
61
- // Once drained, the stream is whole: pipeline reports unread bytes after it as an abort.
62
- if (!drained || signal?.aborted) throw error
80
+ // Output that ends before the input does is a premature close to pipeline: refused just below.
81
+ if (!drained || signal?.aborted || decompress.bytesWritten === given) throw error
63
82
  })
83
+ if (decompress.bytesWritten !== given) throw trailingJunkError()
64
84
 
65
85
  const bundle = Bundle.fromJSON(parser.end(), { contents: !onFile })
66
86
  if (onFile) {
package/src/cmd/build.js CHANGED
@@ -6,9 +6,13 @@ import { spawnSync } from 'node:child_process'
6
6
 
7
7
  import { Bundle } from '@exodus/stasis-core/bundle'
8
8
  import { State } from '@exodus/stasis-core/state'
9
+ import { toPosix } from '@exodus/stasis-core/util'
9
10
  import { StasisEsbuild } from '@exodus/stasis-plugins/esbuild'
11
+ import { bundleDirHost, metroAssetFiles } from '@exodus/stasis-plugins/metro-native'
10
12
  import { HERMES_UNSUPPORTED, createBabelConfigTransform, createHermesTransform } from '../babel.js'
11
13
  import { bundleFromLockfile } from '../bundle-from-lockfile.js'
14
+ import { FLOW_EXTS, stripFlowTypes } from '../flow.js'
15
+ import { ASSET_REGISTRY, assetRegistryResolver, metroAssetCopies, metroAssetDescriptor, metroAssetModule } from '../metro-assets.js'
12
16
  import { parseFileWithKind } from '../parse.js'
13
17
  import { writeFile } from './output.js'
14
18
 
@@ -178,6 +182,113 @@ function loadStateForBundle(root, bundle) {
178
182
  return state
179
183
  }
180
184
 
185
+ // A file's bytes as the State serves them: a Buffer for a base64 resource, else a string.
186
+ const asBytes = (source) => (Buffer.isBuffer(source) ? source : Buffer.from(source))
187
+
188
+ // The bytes the artifact carries for `file` (a path from the State's root), verified by getFile.
189
+ const readCarried = (state, file) => asBytes(state.getFile(pathToFileURL(resolve(state.root, file)).toString()).source)
190
+
191
+ // --metro=PLATFORM's resource hook (StasisEsbuild's `resource`): each resource the build reaches -- in a
192
+ // --metro bundle, a Metro asset, as it records an import edge to no other -- served as the module
193
+ // Metro builds of it for `platform` (metro-assets.js), from the files of the asset the artifact carries
194
+ // in its directory. The module's require of the asset registry resolves to the file the artifact
195
+ // carries for it, an edge added to the State's graph: the bundle records none, as Metro adds it past
196
+ // the source. `built` collects each asset's { descriptor, files } for --assets-dest.
197
+ function metroAssetResource(state, platform, built) {
198
+ const host = bundleDirHost(state)
199
+ const registryFor = assetRegistryResolver(platform, state.sources)
200
+ return (source, { path }) => {
201
+ const rel = toPosix(state.relative(path))
202
+ const files = metroAssetFiles(path, platform, host).map((file) => toPosix(state.relative(file)))
203
+ // The asset's own bytes are those the plugin serves it by.
204
+ const asset = metroAssetDescriptor(rel, { platform, files, read: (file) => (file === rel ? asBytes(source) : readCarried(state, file)) })
205
+ state.addImport(pathToFileURL(path).href, ASSET_REGISTRY, pathToFileURL(resolve(state.root, registryFor(rel))).href)
206
+ built.set(rel, asset)
207
+ return { contents: metroAssetModule(asset.descriptor), loader: 'js' }
208
+ }
209
+ }
210
+
211
+ // --flow's per-file transform (StasisEsbuild's `transform` hook shape), as `stasis bundle --flow` reads
212
+ // a file: a JS-family one esbuild can't parse gets its Flow types stripped (flow.js), an import listing
213
+ // types alone dropped whole, as Babel's Flow transform drops it (a --metro bundle records no edge for
214
+ // it). One that parses is never touched, as stripping plain JS as Flow can misread it (`a < b > (c)`
215
+ // as a call). A file still unparseable fails the build in esbuild: Flow syntax that is code, which
216
+ // stripping leaves, or one flow-remove-types itself can't parse, served as it is.
217
+ function createFlowTransform(esbuild) {
218
+ return async (source, { path, loader }) => {
219
+ if (!FLOW_EXTS.has(extname(path))) return undefined
220
+ try {
221
+ await esbuild.transform(source, { loader, sourcefile: path, logLevel: 'silent' })
222
+ return undefined
223
+ } catch {
224
+ try {
225
+ return { contents: stripFlowTypes(source, { removeEmptyImports: true }), loader }
226
+ } catch {
227
+ return undefined
228
+ }
229
+ }
230
+ }
231
+ }
232
+
233
+ // Two transform hooks over a file in turn, the second over what the first made of it.
234
+ const chainTransforms = (first, second) => async (source, file) => {
235
+ const firstMade = await first(source, file)
236
+ return (await second(firstMade?.contents ?? source, { ...file, loader: firstMade?.loader ?? file.loader })) ?? firstMade
237
+ }
238
+
239
+ const CONFIG_FILE = 'stasis.config.json'
240
+
241
+ // A list option as the command line takes one, as an array of strings or one string, each split at commas.
242
+ const listOf = (value) => [value].flat().flatMap((v) => v.split(',')).map((v) => v.trim()).filter(Boolean)
243
+
244
+ // The options of `entry` in the `entries` of the stasis.config.json the artifact carries at its root
245
+ // (`state`'s), read by `stasis build` itself, apart from how `stasis bundle` builds by them: of each
246
+ // entry's options, those that say how its code is built -- `jsx` (as --loader=.js:jsx), `flow`,
247
+ // `define` (its K=V strings, one or an array) and `metro` with its `platforms` (a list, as on the
248
+ // command line); the rest are the bundle's. An entry is named as `stasis bundle` names it, by its path
249
+ // from the config's directory. -> { jsx, flow, define, platforms } (`platforms` only under `metro`),
250
+ // or null where the artifact carries no config, or it names no such entry
251
+ function configEntryOptions(state, entry) {
252
+ if (!state.sources.has(CONFIG_FILE) && !state.resources.has(CONFIG_FILE)) return null
253
+ let config
254
+ try {
255
+ config = JSON.parse(readCarried(state, CONFIG_FILE).toString('utf8'))
256
+ } catch (cause) {
257
+ throw new Error(`stasis build: the artifact's ${CONFIG_FILE} is not valid JSON`, { cause })
258
+ }
259
+ const entries = config?.entries
260
+ if (entries === undefined) return null
261
+ const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
262
+ if (!isObject(entries)) throw new Error(`stasis build: the artifact's ${CONFIG_FILE}: entries must be an object`)
263
+ const name = Object.keys(entries).find((key) => toPosix(relative(state.root, resolve(state.root, key))) === entry)
264
+ if (name === undefined) return null
265
+ const what = `the artifact's ${CONFIG_FILE}: entries ${JSON.stringify(name)}`
266
+ const options = entries[name]
267
+ if (!isObject(options)) throw new Error(`stasis build: ${what} must be an object of options`)
268
+ for (const flag of ['jsx', 'flow', 'metro']) {
269
+ if (options[flag] !== undefined && typeof options[flag] !== 'boolean') throw new Error(`stasis build: ${what}: ${flag} must be true or false`)
270
+ }
271
+ const strings = (flag) => {
272
+ const value = options[flag] ?? []
273
+ if (typeof value !== 'string' && !(Array.isArray(value) && value.every((v) => typeof v === 'string'))) {
274
+ throw new Error(`stasis build: ${what}: ${flag} must be a string or an array of strings`)
275
+ }
276
+ return [value].flat()
277
+ }
278
+ const define = {}
279
+ for (const pair of strings('define')) {
280
+ const eq = pair.indexOf('=')
281
+ if (eq <= 0) throw new Error(`stasis build: ${what}: define must be KEY=VALUE (got '${pair}')`)
282
+ define[pair.slice(0, eq)] = pair.slice(eq + 1)
283
+ }
284
+ let platforms
285
+ if (options.metro === true) {
286
+ platforms = [...new Set(listOf(strings('platforms')))]
287
+ if (platforms.length === 0) throw new Error(`stasis build: ${what} sets metro but names no platforms`)
288
+ }
289
+ return { name, jsx: options.jsx === true, flow: options.flow === true, define, platforms }
290
+ }
291
+
181
292
  // Run `stasis build`: run esbuild over one recorded entry, following the artifact's
182
293
  // recorded import graph EXACTLY (not esbuild's resolver). A specifier the artifact records
183
294
  // is always followed from the artifact; `external` only steers the specifiers it doesn't.
@@ -189,15 +300,24 @@ export async function buildCommand({
189
300
  format,
190
301
  platform = 'node',
191
302
  babel = false,
303
+ flow = false,
192
304
  minify = false,
193
305
  sourcemap = false,
194
306
  define = {},
195
307
  external = [],
196
308
  loader = {},
309
+ metro,
310
+ assetsDest,
197
311
  } = {}) {
198
312
  if (!artifact) throw new Error('stasis build: an artifact (bundle or lockfile) is required')
199
313
  if (!output) throw new Error('stasis build: --output is required (a .js/.cjs/.mjs file, or a directory)')
200
314
  if (!Array.isArray(external)) throw new Error('stasis build: external must be an array of esbuild patterns')
315
+ if (metro !== undefined && (typeof metro !== 'string' || !/^[^/,]+$/u.test(metro))) {
316
+ throw new Error(`stasis build: --metro takes the platform to build for, e.g. --metro=ios (got '${metro}')`)
317
+ }
318
+ if (flow && babel) {
319
+ throw new Error('stasis build: --babel hands the project\'s Babel config each file as it is, Flow included, for it to compile; --flow strips Flow before esbuild without it -- pass one')
320
+ }
201
321
  // --platform=hermes is a stasis-level target, not an esbuild platform (esbuild gets
202
322
  // 'neutral'): every code file is downleveled to Hermes' dialect before the final bundle,
203
323
  // and the bundle itself must avoid ESM -- Hermes has no import/export.
@@ -221,14 +341,56 @@ export async function buildCommand({
221
341
  // Make the entry absolute against the State's root so resolution is independent of process cwd.
222
342
  const entryPoint = resolve(state.root, selectedEntry)
223
343
 
344
+ // The entry's options in the stasis.config.json the artifact carries, under the flags given: jsx as
345
+ // --loader=.js:jsx, flow as --flow (not under --babel, whose config compiles Flow itself), its define
346
+ // under --define's, and metro as --metro for its one platform; of several, --metro picks one, which
347
+ // must be one of them.
348
+ const configured = configEntryOptions(state, selectedEntry)
349
+ if (configured !== null) {
350
+ const taken = []
351
+ if (configured.jsx && loader['.js'] === undefined) {
352
+ loader = { ...loader, '.js': 'jsx' }
353
+ taken.push('--loader=.js:jsx')
354
+ }
355
+ if (configured.flow && !flow && !babel) {
356
+ flow = true
357
+ taken.push('--flow')
358
+ }
359
+ for (const [key, value] of Object.entries(configured.define)) {
360
+ if (Object.hasOwn(define, key)) continue
361
+ define = { ...define, [key]: value }
362
+ taken.push(`--define=${key}=${value}`)
363
+ }
364
+ const { platforms } = configured
365
+ if (platforms !== undefined) {
366
+ const choices = platforms.map((name) => `--metro=${name}`).join(' or ')
367
+ const what = `${CONFIG_FILE} bundles ${selectedEntry} for ${platforms.join(', ')}`
368
+ if (metro === undefined && platforms.length > 1) throw new Error(`stasis build: ${what}: pass ${choices}`)
369
+ if (metro !== undefined && !platforms.includes(metro)) throw new Error(`stasis build: --metro=${metro}, but ${what} alone: pass ${choices}`)
370
+ if (metro === undefined) {
371
+ metro = platforms[0]
372
+ taken.push(`--metro=${metro}`)
373
+ }
374
+ }
375
+ if (taken.length > 0) console.warn(`[stasis] ${selectedEntry}: ${taken.join(' ')}, as ${CONFIG_FILE}'s entries ${JSON.stringify(configured.name)} sets`)
376
+ }
377
+ if (assetsDest !== undefined && metro === undefined) {
378
+ throw new Error('stasis build: --assets-dest copies the assets --metro builds; pass --metro=PLATFORM with it')
379
+ }
380
+
224
381
  const esbuild = await importEsbuild()
225
382
  // Per-file code rewrites the plugin applies before esbuild parses a served file:
226
383
  // --babel runs the project's own babel.config.* over the original source (no esbuild
227
384
  // pre-transform), and otherwise --platform=hermes uses the built-in downlevel pipeline.
228
- // Both resolve Babel from the project (cwd), never from stasis's own dependencies.
385
+ // Both resolve Babel from the project (cwd), never from stasis's own dependencies. --flow
386
+ // strips Flow types first, from what esbuild can't parse.
229
387
  let transform
230
388
  if (babel) transform = createBabelConfigTransform({ projectDir: cwd })
231
389
  else if (hermes) transform = createHermesTransform({ projectDir: cwd, esbuild })
390
+ if (flow) transform = transform === undefined ? createFlowTransform(esbuild) : chainTransforms(createFlowTransform(esbuild), transform)
391
+ // --metro=PLATFORM: PLATFORM's target of each per-platform edge, and each asset as Metro builds it.
392
+ const builtAssets = new Map()
393
+ const resource = metro === undefined ? undefined : metroAssetResource(state, metro, builtAssets)
232
394
 
233
395
  const outAbs = resolve(cwd, output)
234
396
  const asFile = /\.[cm]?js$/u.test(output)
@@ -255,24 +417,43 @@ export async function buildCommand({
255
417
  ...(asFile ? { outfile: outAbs } : { outdir: outAbs }),
256
418
  // Loader overrides go through the plugin: it serves every in-bundle file, so esbuild's
257
419
  // own `loader` option never sees them. e.g. { '.js': 'jsx' } to parse JSX in .js files.
258
- plugins: [new StasisEsbuild(state, { loaders: new Map(Object.entries(loader)), transform })],
420
+ plugins: [new StasisEsbuild(state, { loaders: new Map(Object.entries(loader)), transform, resource, platform: metro })],
259
421
  })
260
422
  } catch (err) {
261
423
  // Under logLevel:'silent' esbuild puts the real errors on err.errors; surface them, then fail.
262
424
  if (Array.isArray(err?.errors) && err.errors.length > 0) {
263
425
  const formatted = await esbuild.formatMessages(err.errors, { kind: 'error', color: false })
264
426
  for (const line of formatted) process.stderr.write(line)
427
+ // A resource the build reaches with no loader for its extension: what builds one.
428
+ const unloaded = err.errors.map((e) => /^No loader is configured for "([^"]+)" files/u.exec(e.text)?.[1]).find(Boolean)
429
+ if (unloaded !== undefined) {
430
+ process.stderr.write(
431
+ `[stasis] Build a "${unloaded}" resource with --loader=${unloaded}:NAME (an esbuild loader: dataurl, file, text, ...), ` +
432
+ `or with --metro=PLATFORM as the asset module Metro builds of it\n`
433
+ )
434
+ }
435
+ if (metro === undefined && err.errors.some((e) => e.detail?.code === 'ERR_STASIS_PLATFORM_SPECIFIC')) {
436
+ process.stderr.write('[stasis] A --metro multi-platform bundle builds for one platform at a time: pass --metro=PLATFORM (e.g. --metro=ios)\n')
437
+ }
265
438
  throw new Error(`stasis build failed: esbuild reported ${err.errors.length} error(s)`, { cause: err })
266
439
  }
267
440
  throw err
268
441
  }
269
442
 
270
- // Refuse to clobber an attested source, checked against esbuild's actual output paths before any write.
271
- for (const file of result.outputFiles) {
272
- if (attested.has(file.path)) {
443
+ // --assets-dest's copies of the assets built, as `react-native bundle --assets-dest` lays them out for
444
+ // the platform, from the bytes the artifact carries, in a stable order (esbuild loads in parallel).
445
+ const assetFiles = assetsDest === undefined
446
+ ? []
447
+ : metroAssetCopies(metro, [...builtAssets.keys()].toSorted().map((rel) => builtAssets.get(rel)))
448
+ .map(({ dest, file, contents }) => ({ path: resolve(cwd, assetsDest, dest), contents: contents ?? readCarried(state, file) }))
449
+ const writes = [...result.outputFiles, ...assetFiles]
450
+
451
+ // Refuse to clobber an attested source, checked against the actual output paths before any write.
452
+ for (const { path } of writes) {
453
+ if (attested.has(path)) {
273
454
  throw new Error(
274
- `stasis build: refusing to write '${relative(cwd, file.path)}' -- it is a source the artifact records; ` +
275
- `choose an --output path outside the artifact's own files`
455
+ `stasis build: refusing to write '${relative(cwd, path)}' -- it is a source the artifact records; ` +
456
+ `choose an --output${assetsDest === undefined ? '' : '/--assets-dest'} path outside the artifact's own files`
276
457
  )
277
458
  }
278
459
  }
@@ -282,8 +463,13 @@ export async function buildCommand({
282
463
  for (const line of formatted) process.stderr.write(line)
283
464
  }
284
465
 
285
- for (const file of result.outputFiles) writeFile(file.path, file.contents)
466
+ for (const { path, contents } of writes) writeFile(path, contents)
286
467
 
287
468
  console.warn(`[stasis] Built ${selectedEntry} from ${kind} ${artifact} to ${output}`)
469
+ if (assetsDest !== undefined) {
470
+ console.warn(`[stasis] Copied ${builtAssets.size} asset${builtAssets.size === 1 ? '' : 's'} (${assetFiles.length} file${assetFiles.length === 1 ? '' : 's'}) for ${metro} to ${assetsDest}`)
471
+ } else if (builtAssets.size > 0) {
472
+ console.warn(`[stasis] Built ${builtAssets.size} asset${builtAssets.size === 1 ? '' : 's'} for ${metro}; pass --assets-dest to copy their files out`)
473
+ }
288
474
  return { entry: selectedEntry, dir: asFile ? undefined : outAbs, outfile: asFile ? outAbs : undefined }
289
475
  }