@mostra/sdk 0.5.0 → 0.6.1

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.
@@ -1,14 +1,14 @@
1
1
  import { createHash, randomBytes } from "node:crypto";
2
- import { link, lstat, mkdir, open, readFile, readdir, readlink, rename, rm, stat, statfs, utimes, writeFile } from "node:fs/promises";
2
+ import { link, lstat, mkdir, open, readFile, readdir, readlink, rename, rm, rmdir, stat, statfs, symlink, unlink, utimes, writeFile } from "node:fs/promises";
3
3
  import { homedir } from "node:os";
4
- import { dirname, isAbsolute, join, resolve, sep } from "node:path";
5
- import { BUNDLE_PLATFORMS, BUNDLE_SETUP_MARKER, BundleAsset, BundleFiles, BundleInfo, BundlePins, BundleSetup, RpcError, bundleAssetName, createDiagnostic } from "@mostra/protocol";
6
- import { createReadStream, createWriteStream, existsSync, readFileSync } from "node:fs";
4
+ import { dirname, isAbsolute, join, posix, relative, resolve, sep, win32 } from "node:path";
5
+ import { BUNDLE_PLATFORMS, BUNDLE_SETUP_MARKER, BundleAsset, BundleFiles, BundleInfo, BundlePins, BundleSetup, RpcError, bundleAssetName, createDiagnostic, isWindowsBundle } from "@mostra/protocol";
6
+ import { closeSync, createReadStream, createWriteStream, existsSync, mkdirSync, openSync, readFileSync, realpathSync, symlinkSync, writeSync } from "node:fs";
7
7
  import { Readable } from "node:stream";
8
8
  import { pipeline } from "node:stream/promises";
9
9
  import { fileURLToPath } from "node:url";
10
10
  import { EnvHttpProxyAgent, fetch } from "undici";
11
- import { x } from "tar";
11
+ import { Parser } from "tar";
12
12
  import { spawn } from "node:child_process";
13
13
  //#region src/bundle/download.ts
14
14
  /**
@@ -175,47 +175,219 @@ function delay(ms, signal) {
175
175
  //#endregion
176
176
  //#region src/bundle/extract.ts
177
177
  /**
178
- * Unpacking a downloaded archive (RT-01). Only regular files, directories and symbolic links are
179
- * accepted, all under the archive's one top directory, which is stripped. node-tar refuses
180
- * absolute paths, `..` and writing through a link; it does create a link whatever its target, so
181
- * setup then checks the whole tree against the bundle's file list (`checkTree`), which refuses any
182
- * file or link it doesn't list and any link that leaves the bundle. A pinned archive's SHA-256 is
183
- * checked before any of this.
178
+ * Unpacking a downloaded archive (RT-01) into a new, empty directory. Only regular files,
179
+ * directories and symbolic links are accepted, all under the archive's one top directory, which is
180
+ * stripped; an entry's path must be relative, with no `..`, `.` or empty part and no backslash
181
+ * (nor, on Windows, a colon; node-tar reads a backslash there as a separator, so its parts are
182
+ * judged as separate ones), and no path may appear twice. Links are made only after every file
183
+ * and directory is written, and after every link's own directory, so no write and no link ever
184
+ * goes through one. Setup then checks the whole tree
185
+ * against the bundle's file list (`checkTree`), which refuses any file or link it doesn't list and
186
+ * any link that leaves the bundle. A pinned archive's SHA-256 is checked before any of this. A
187
+ * Windows archive holds no links at all (D153): one that does is refused, since its junctions are
188
+ * made by setup, from `files.json`.
189
+ *
190
+ * The files are written synchronously as node-tar's parser reads them. node-tar's own `x` checks
191
+ * and clobbers what each path already holds, and on Windows writes one entry at a time; into an
192
+ * empty directory none of that is needed, and a first install wrote its ~50,000 files 4 to 10
193
+ * times slower for it: 6 minutes on Windows arm64 (#88, VERIFIED_FACTS, MT-02).
184
194
  */
185
- const ACCEPTED = /* @__PURE__ */ new Set([
195
+ const FILES = /* @__PURE__ */ new Set([
186
196
  "File",
187
197
  "OldFile",
188
- "ContiguousFile",
189
- "Directory",
190
- "SymbolicLink"
198
+ "ContiguousFile"
191
199
  ]);
200
+ /** An entry a bundle's archive never has, or an archive that doesn't read as a tar at all. */
201
+ var ArchiveRefused = class extends Error {};
202
+ /**
203
+ * Whether `error` is two of the archive's entries meeting where the file system names them as one
204
+ * path: a file where a directory must go, a directory or file already there, names the file system
205
+ * folds alike (`σ` and `ς`, `ß` and `ss`). The directory is new and only this extractor writes in
206
+ * it, so these are never the disk's failure (the Opus review of MT-02).
207
+ */
208
+ function collides(error) {
209
+ const code = error.code;
210
+ return code === "EEXIST" || code === "ENOTDIR" || code === "EISDIR";
211
+ }
192
212
  /** Extracts `archive` (a `.tar.gz` with one top directory `top`) into the empty directory `into`. */
193
- async function extractBundle(archive, into, top) {
194
- let refused;
213
+ async function extractBundle(archive, into, top, options = {}) {
195
214
  try {
196
- await x({
197
- file: archive,
198
- cwd: into,
199
- strip: 1,
200
- strict: true,
201
- preservePaths: false,
202
- preserveOwner: false,
203
- noChmod: false,
204
- filter: (path, entry) => {
205
- const type = "type" in entry ? String(entry.type) : "File";
206
- if (!(path === `${top}/` || path === top || path.startsWith(`${top}/`)) || !ACCEPTED.has(type)) {
207
- refused ??= `${path} (${type})`;
208
- return false;
209
- }
210
- return true;
211
- }
212
- });
215
+ await unpack(archive, resolve(into), top, options.links === "refuse");
213
216
  } catch (error) {
217
+ if (error instanceof ArchiveRefused) throw new RpcError(createDiagnostic("MOSTRA_ENV_BUNDLE_INVALID", { message: error.message }));
214
218
  const code = error.code;
215
219
  if (typeof code === "string" && /^E[A-Z]+$/.test(code) && code !== "EOF") throw new RpcError(createDiagnostic("MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED", { message: `The runtime bundle couldn't be written to ${into}: ${error.message}${code === "ENOSPC" ? " (the disk is full)" : ""}` }));
216
220
  throw new RpcError(createDiagnostic("MOSTRA_ENV_BUNDLE_INVALID", { message: `The runtime bundle's archive couldn't be read: ${error.message}` }));
217
221
  }
218
- if (refused !== void 0) throw new RpcError(createDiagnostic("MOSTRA_ENV_BUNDLE_INVALID", { message: `The runtime bundle's archive holds an entry a bundle never has: ${refused}.` }));
222
+ }
223
+ /** The path below `top` an entry names, as parts, or why it is refused. */
224
+ function entryParts(path, top, windows) {
225
+ const parts = path.split("/");
226
+ if (parts[0] !== top) return "it is outside the bundle's directory";
227
+ if (parts.length > 1 && parts.at(-1) === "") parts.pop();
228
+ const below = parts.slice(1);
229
+ for (const part of below) {
230
+ if (part === "" || part === "." || part === "..") return "its path isn't a plain relative one";
231
+ if (part.includes("\\") || windows && part.includes(":")) return "its path holds a character a bundle's paths never have";
232
+ }
233
+ return below;
234
+ }
235
+ async function unpack(archive, root, top, refuseLinks) {
236
+ const windows = process.platform === "win32";
237
+ const seen = /* @__PURE__ */ new Set();
238
+ const made = /* @__PURE__ */ new Set([root]);
239
+ const links = [];
240
+ const ensureDir = (dir) => {
241
+ if (made.has(dir)) return;
242
+ mkdirSync(dir, {
243
+ recursive: true,
244
+ mode: 493
245
+ });
246
+ for (let at = dir; !made.has(at); at = dirname(at)) made.add(at);
247
+ };
248
+ let failure;
249
+ let open;
250
+ const fail = (error) => {
251
+ failure ??= error;
252
+ };
253
+ const refuse = (path, type, why) => fail(new ArchiveRefused(`The runtime bundle's archive holds an entry a bundle never has: ${path} (${type}): ${why}.`));
254
+ const parser = new Parser({ strict: true });
255
+ parser.on("entry", (entry) => {
256
+ const type = String(entry.type);
257
+ if (failure !== void 0) return entry.resume();
258
+ const parts = entryParts(entry.path, top, windows);
259
+ if (typeof parts === "string") {
260
+ refuse(entry.path, type, parts);
261
+ return entry.resume();
262
+ }
263
+ const path = parts.length === 0 ? root : join(root, ...parts);
264
+ const key = windows || process.platform === "darwin" ? path.normalize("NFC").toLowerCase() : path;
265
+ if (parts.length > 0 && seen.has(key)) {
266
+ refuse(entry.path, type, "its path appears twice");
267
+ return entry.resume();
268
+ }
269
+ seen.add(key);
270
+ try {
271
+ if (type === "Directory") {
272
+ entry.resume();
273
+ ensureDir(path);
274
+ } else if (type === "SymbolicLink" && parts.length > 0) {
275
+ entry.resume();
276
+ if (refuseLinks) refuse(entry.path, type, "a Windows bundle's links are made by setup");
277
+ else if (!entry.linkpath) refuse(entry.path, type, "it links to nothing");
278
+ else links.push({
279
+ path,
280
+ target: entry.linkpath
281
+ });
282
+ } else if (FILES.has(type) && parts.length > 0) {
283
+ ensureDir(dirname(path));
284
+ const fd = openSync(path, "wx", (entry.mode ?? 0) & 73 ? 493 : 420);
285
+ open = fd;
286
+ entry.on("data", (chunk) => {
287
+ if (failure !== void 0) return;
288
+ try {
289
+ let at = 0;
290
+ while (at < chunk.length) at += writeSync(fd, chunk, at);
291
+ } catch (error) {
292
+ fail(error);
293
+ }
294
+ });
295
+ entry.on("end", () => {
296
+ open = void 0;
297
+ try {
298
+ closeSync(fd);
299
+ } catch (error) {
300
+ fail(error);
301
+ }
302
+ });
303
+ } else {
304
+ refuse(entry.path, type, "a bundle holds only files, directories and links");
305
+ entry.resume();
306
+ }
307
+ } catch (error) {
308
+ if (collides(error)) refuse(entry.path, type, "its path meets another entry's, as this file system names them");
309
+ else fail(error);
310
+ entry.resume();
311
+ }
312
+ });
313
+ const ended = new Promise((done) => {
314
+ parser.on("end", done);
315
+ parser.on("error", (error) => {
316
+ fail(new ArchiveRefused(`The runtime bundle's archive couldn't be read: ${error.message}`));
317
+ done();
318
+ });
319
+ });
320
+ try {
321
+ for await (const chunk of createReadStream(archive, { highWaterMark: 1048576 })) {
322
+ parser.write(chunk);
323
+ if (failure !== void 0) break;
324
+ }
325
+ if (failure === void 0) {
326
+ parser.end();
327
+ await ended;
328
+ }
329
+ } finally {
330
+ if (open !== void 0) closeSync(open);
331
+ }
332
+ if (failure !== void 0) throw failure;
333
+ const refused = (path, why) => new ArchiveRefused(`The runtime bundle's archive holds an entry a bundle never has: ${path} (SymbolicLink): ${why}.`);
334
+ for (const link of links) try {
335
+ ensureDir(dirname(link.path));
336
+ } catch (error) {
337
+ if (collides(error)) throw refused(link.path, "it lies beneath a file");
338
+ throw error;
339
+ }
340
+ for (const link of links) try {
341
+ symlinkSync(link.target, link.path);
342
+ } catch (error) {
343
+ if (collides(error)) throw refused(link.path, "other entries are inside it, or meet its path");
344
+ throw error;
345
+ }
346
+ }
347
+ //#endregion
348
+ //#region src/environment.ts
349
+ /** What Windows gives every program, which a child of the SDK keeps (D150 item 9). */
350
+ const WINDOWS_SYSTEM_VARIABLES = [
351
+ "SystemRoot",
352
+ "SystemDrive",
353
+ "windir",
354
+ "ComSpec",
355
+ "PATHEXT",
356
+ "TEMP",
357
+ "TMP",
358
+ "USERPROFILE",
359
+ "HOMEDRIVE",
360
+ "HOMEPATH",
361
+ "APPDATA",
362
+ "LOCALAPPDATA",
363
+ "ProgramData",
364
+ "ProgramFiles",
365
+ "ProgramFiles(x86)",
366
+ "ProgramW6432",
367
+ "CommonProgramFiles",
368
+ "CommonProgramFiles(x86)",
369
+ "CommonProgramW6432",
370
+ "USERNAME",
371
+ "USERDOMAIN",
372
+ "COMPUTERNAME",
373
+ "OS",
374
+ "NUMBER_OF_PROCESSORS",
375
+ "PROCESSOR_ARCHITECTURE",
376
+ "PROCESSOR_IDENTIFIER"
377
+ ];
378
+ /** `env` for a child process: on Windows with the system's own variables this process has. */
379
+ function childEnvironment(env, options = {}) {
380
+ const out = {};
381
+ for (const [name, value] of Object.entries(env)) if (value !== void 0) out[name] = value;
382
+ if ((options.platform ?? process.platform) !== "win32") return out;
383
+ const own = options.own ?? process.env;
384
+ const present = new Set(Object.keys(out).map((name) => name.toUpperCase()));
385
+ for (const name of WINDOWS_SYSTEM_VARIABLES) {
386
+ if (present.has(name.toUpperCase())) continue;
387
+ const found = Object.entries(own).find(([key]) => key.toUpperCase() === name.toUpperCase());
388
+ if (found?.[1] !== void 0) out[found[0]] = found[1];
389
+ }
390
+ return out;
219
391
  }
220
392
  //#endregion
221
393
  //#region src/bundle/tree.ts
@@ -223,7 +395,41 @@ async function extractBundle(archive, into, top) {
223
395
  * A bundle's files against its manifest (RT-01): one walk that both writes `files.json` (the
224
396
  * assembler) and checks an extracted bundle against it (setup), so the two can't disagree about
225
397
  * what counts. Links must stay inside the bundle; nothing may be missing, changed or extra.
398
+ *
399
+ * On Windows (D153) a link is read as the relative, `/`-separated path from its directory to its
400
+ * target, whether it is a symbolic link (`..\\x`, as pnpm makes them for an administrator) or a
401
+ * junction (an absolute target, as setup makes them for everyone), so `files.json` reads the same
402
+ * on every system; and no file is executable, since Windows keeps no execute bit (D150 item 8).
226
403
  */
404
+ /** Whether this process runs on Windows, whose links and modes the walk reads its own way. */
405
+ const WINDOWS = process.platform === "win32";
406
+ /**
407
+ * A link's target as the manifest spells it: relative to the link's directory, `/`-separated.
408
+ * POSIX targets are kept exactly as written; a Windows junction's absolute target, and a Windows
409
+ * symbolic link's `\\`-separated one, are rewritten into that form. `realRoot` is `root`'s real
410
+ * path, which a caller reading many links computes once (Opus review of WP-W3, finding 8).
411
+ */
412
+ function linkTarget(root, path, written, realRoot = realOrNone(root)) {
413
+ if (!WINDOWS) return written;
414
+ const plain = written.startsWith("\\\\?\\") ? written.slice(4) : written;
415
+ if (!isAbsolute(plain)) return plain.split(sep).join("/");
416
+ const given = resolve(root);
417
+ const dir = dirname(join(given, path));
418
+ const spellings = [[given, dir]];
419
+ if (realRoot !== void 0) spellings.push([realRoot, join(realRoot, relative(given, dir))]);
420
+ const lower = plain.toLowerCase();
421
+ for (const [base, from] of spellings) if (lower === base.toLowerCase() || lower.startsWith(`${base.toLowerCase()}${sep}`)) return relative(from, plain).split(sep).join("/");
422
+ return relative(dir, plain).split(sep).join("/");
423
+ }
424
+ /** `root`'s real path on Windows (where junction targets need it), or `undefined`. */
425
+ function realOrNone(root) {
426
+ if (!WINDOWS) return void 0;
427
+ try {
428
+ return realpathSync.native(resolve(root));
429
+ } catch {
430
+ return;
431
+ }
432
+ }
227
433
  /** The SHA-256 and size of one file, read as a stream. */
228
434
  async function hashFile(path) {
229
435
  const hash = createHash("sha256");
@@ -240,23 +446,26 @@ async function hashFile(path) {
240
446
  /** Every file and link under `root`, sorted by path, skipping `exclude`d paths (and below). */
241
447
  async function walk(root, exclude) {
242
448
  const out = [];
449
+ const realRoot = realOrNone(root);
243
450
  const visit = async (dir) => {
244
451
  const entries = await readdir(join(root, dir), { withFileTypes: true });
245
452
  for (const entry of entries) {
246
453
  const path = dir === "" ? entry.name : `${dir}/${entry.name}`;
247
454
  if (exclude(path)) continue;
248
455
  if (entry.isDirectory()) await visit(path);
249
- else if (entry.isSymbolicLink()) out.push({
250
- kind: "link",
251
- path,
252
- target: await readlink(join(root, path))
253
- });
254
- else if (entry.isFile()) {
255
- const stats = await lstat(join(root, path));
456
+ else if (entry.isSymbolicLink()) {
457
+ const written = await readlink(join(root, path));
458
+ out.push({
459
+ kind: "link",
460
+ path,
461
+ target: linkTarget(root, path, written, realRoot)
462
+ });
463
+ } else if (entry.isFile()) {
464
+ const executable = WINDOWS ? false : ((await lstat(join(root, path))).mode & 64) !== 0;
256
465
  out.push({
257
466
  kind: "file",
258
467
  path,
259
- executable: (stats.mode & 64) !== 0
468
+ executable
260
469
  });
261
470
  } else out.push({
262
471
  kind: "other",
@@ -282,7 +491,7 @@ async function mapLimit(items, limit, task) {
282
491
  }
283
492
  /** Whether a link's target is relative and resolves inside `root`. */
284
493
  function linkStaysInside(root, path, target) {
285
- if (isAbsolute(target)) return false;
494
+ if (isAbsolute(target) || /[\\:\0]/.test(target)) return false;
286
495
  const base = resolve(root);
287
496
  const resolved = resolve(base, dirname(path), target);
288
497
  return resolved === base || resolved.startsWith(base + sep);
@@ -335,6 +544,7 @@ async function describeTree(root, exclude = () => false) {
335
544
  async function checkTree(root, manifest, options = {}) {
336
545
  const limit = options.limit ?? 20;
337
546
  const allowExtra = options.allowExtra ?? (() => false);
547
+ const checkLinks = options.links ?? true;
338
548
  const problems = [];
339
549
  const add = (problem) => {
340
550
  if (problems.length < limit) problems.push(problem);
@@ -353,7 +563,7 @@ async function checkTree(root, manifest, options = {}) {
353
563
  for (const entry of walked) if (!expectedFiles.has(entry.path) && !expectedLinks.has(entry.path)) {
354
564
  if (!allowExtra(entry.path)) add(`${entry.path}: not in the bundle's file list`);
355
565
  }
356
- for (const [path, link] of expectedLinks) {
566
+ for (const [path, link] of checkLinks ? expectedLinks : /* @__PURE__ */ new Map()) {
357
567
  const actual = found.get(path);
358
568
  if (actual?.kind !== "link") add(`${path}: missing link`);
359
569
  else if (actual.target !== link.target) add(`${path}: links to ${actual.target}, not ${link.target}`);
@@ -371,6 +581,142 @@ async function checkTree(root, manifest, options = {}) {
371
581
  return problems;
372
582
  }
373
583
  //#endregion
584
+ //#region src/bundle/links.ts
585
+ /**
586
+ * A Windows bundle's links (D153). An ordinary Windows user can't create symbolic links (that
587
+ * takes an administrator or Developer Mode), so a Windows archive holds none: its `files.json`
588
+ * lists each link, every one to a directory inside the bundle, and setup makes each a junction,
589
+ * which any user can create. A junction names its target by absolute path, so it is made at the
590
+ * bundle's real path, and a bundle moved since is set up again (`readSetup` compares the root
591
+ * its marker names).
592
+ *
593
+ * Nothing outside the bundle is ever touched: a listed link's path and target must stay inside
594
+ * it, every directory above a link must be a real directory (never a link), the target must be a
595
+ * directory, and what already sits at a link's path is replaced only when it is itself a link, or
596
+ * a real directory holding exactly the files and bytes of the link's target. That is what a copy
597
+ * made by a tool that follows junctions leaves (Explorer, `Copy-Item`, `robocopy` without `/SJ`,
598
+ * and a move to another drive, which is a copy), so such a copy is set up again; a directory
599
+ * holding anything else is refused and kept (Opus review of WP-W3, finding 4).
600
+ *
601
+ * Two setups of one bundle may run at once (a moved bundle met by two commands): each step
602
+ * tolerates the other's, and a link counts as made once it names its target, whoever made it
603
+ * (finding 5).
604
+ */
605
+ /** Why a link couldn't be made; the caller reports it as `MOSTRA_ENV_BUNDLE_INVALID`. */
606
+ var LinkRefused = class extends Error {};
607
+ /** Whether `path` (an absolute path inside `root`) has only real directories above it. */
608
+ async function realParents(root, path) {
609
+ let dir = dirname(path);
610
+ const chain = [];
611
+ while (dir.length > root.length) {
612
+ chain.unshift(dir);
613
+ dir = dirname(dir);
614
+ }
615
+ for (const parent of chain) {
616
+ const info = await lstat(parent).catch(() => void 0);
617
+ if (info === void 0) {
618
+ await mkdir(parent);
619
+ continue;
620
+ }
621
+ if (!info.isDirectory() || info.isSymbolicLink()) return false;
622
+ }
623
+ return true;
624
+ }
625
+ /**
626
+ * Makes every link `manifest` lists as a junction under `root`, which must be the bundle's real
627
+ * path (`realpath.native`). A link that already names its target is kept; one that names another
628
+ * (the bundle moved) is replaced. Throws {@link LinkRefused} for a link the manifest can't have.
629
+ */
630
+ async function makeJunctions(root, manifest) {
631
+ const realRoot = realOrNone(root);
632
+ let waiting = [...manifest.links].sort((a, b) => a.path.length - b.path.length);
633
+ while (waiting.length > 0) {
634
+ const later = [];
635
+ for (const link of waiting) if (!await makeJunction(root, link, realRoot)) later.push(link);
636
+ if (later.length === waiting.length) {
637
+ const first = later[0];
638
+ throw new LinkRefused(`${first.path} links to ${first.target}, which is no directory.`);
639
+ }
640
+ waiting = later;
641
+ }
642
+ }
643
+ /** Makes one link; `false` when its target isn't a directory (yet). */
644
+ async function makeJunction(root, link, realRoot) {
645
+ if (!safeRelative(link.path) || !linkStaysInside(root, link.path, link.target)) throw new LinkRefused(`${link.path} links outside the bundle (${link.target}).`);
646
+ const at = join(root, link.path);
647
+ const target = resolve(dirname(at), link.target);
648
+ if (!await realParents(root, at)) throw new LinkRefused(`${link.path} sits below a link or a file.`);
649
+ const kind = await stat(target).catch(() => void 0);
650
+ if (kind === void 0 || !kind.isDirectory()) return names(root, link, at, realRoot);
651
+ let last;
652
+ for (let attempt = 0; attempt < 20; attempt++) {
653
+ if (await names(root, link, at, realRoot)) return true;
654
+ const current = await lstat(at).catch(() => void 0);
655
+ try {
656
+ if (current?.isSymbolicLink()) await rmdir(at).catch(async (error) => {
657
+ if (error.code !== "ENOENT") await unlink(at);
658
+ });
659
+ else if (current !== void 0) {
660
+ if (!current.isDirectory() || !await sameTree(at, target)) {
661
+ if (await names(root, link, at, realRoot)) return true;
662
+ const now = await lstat(at).catch(() => void 0);
663
+ if (now !== void 0 && !now.isSymbolicLink()) throw new LinkRefused(`${link.path} is a file or directory where the bundle has a link, and it isn't a copy of ${link.target}.`);
664
+ continue;
665
+ }
666
+ await rm(at, {
667
+ recursive: true,
668
+ force: true,
669
+ maxRetries: 5,
670
+ retryDelay: 100
671
+ });
672
+ }
673
+ await symlink(target, at, "junction");
674
+ } catch (error) {
675
+ if (error instanceof LinkRefused) throw error;
676
+ last = error;
677
+ }
678
+ }
679
+ if (await names(root, link, at, realRoot)) return true;
680
+ throw new LinkRefused(`${link.path} couldn't be made as a junction to ${link.target}${last ? `: ${last.message}` : ""}.`);
681
+ }
682
+ /** Whether the link at `at` exists and names the manifest's target. */
683
+ async function names(root, link, at, realRoot) {
684
+ const info = await lstat(at).catch(() => void 0);
685
+ if (info === void 0 || !info.isSymbolicLink()) return false;
686
+ const written = await readlink(at).catch(() => void 0);
687
+ return written !== void 0 && linkTarget(root, link.path, written, realRoot) === link.target;
688
+ }
689
+ /**
690
+ * Whether the real directory `copy` holds exactly what `original` holds: the same names, files of
691
+ * the same bytes, and directories alike all the way down. A link anywhere in the copy, or an entry
692
+ * of any other kind, makes it no copy.
693
+ */
694
+ async function sameTree(copy, original) {
695
+ const [mine, theirs] = await Promise.all([readdir(copy, { withFileTypes: true }).catch(() => void 0), readdir(original, { withFileTypes: true }).catch(() => void 0)]);
696
+ if (mine === void 0 || theirs === void 0 || mine.length !== theirs.length) return false;
697
+ const byName = new Map(theirs.map((entry) => [entry.name, entry]));
698
+ for (const entry of mine) {
699
+ const other = byName.get(entry.name);
700
+ if (other === void 0 || entry.isSymbolicLink()) return false;
701
+ const a = join(copy, entry.name);
702
+ const b = join(original, entry.name);
703
+ if (entry.isDirectory()) {
704
+ if (!(await stat(b).catch(() => void 0))?.isDirectory()) return false;
705
+ if (!await sameTree(a, b)) return false;
706
+ } else if (entry.isFile()) {
707
+ if (!(other.isFile() || other.isSymbolicLink()) || !await sameBytes(a, b)) return false;
708
+ } else return false;
709
+ }
710
+ return true;
711
+ }
712
+ /** Whether two files hold the same bytes (streamed, so a large program isn't held in memory). */
713
+ async function sameBytes(a, b) {
714
+ const [sa, sb] = await Promise.all([stat(a), stat(b)]).catch(() => [void 0, void 0]);
715
+ if (sa === void 0 || sb === void 0 || !sb.isFile() || sa.size !== sb.size) return false;
716
+ const [ha, hb] = await Promise.all([hashFile(a), hashFile(b)]);
717
+ return ha.sha256 === hb.sha256;
718
+ }
719
+ //#endregion
374
720
  //#region src/bundle/setup.ts
375
721
  /**
376
722
  * Making an extracted bundle usable (RT-01, D142): its files checked against `files.json`, which
@@ -419,12 +765,23 @@ async function readBundle(root) {
419
765
  info
420
766
  };
421
767
  }
422
- /** The setup marker, when it describes exactly this bundle. */
768
+ /**
769
+ * The bundle's real path: links followed, Windows' short names written out, the case as the file
770
+ * system keeps it. A Windows bundle's junctions point into it, and its marker names it.
771
+ */
772
+ function realRoot(root) {
773
+ return realpathSync.native(root);
774
+ }
775
+ /**
776
+ * The setup marker, when it describes exactly this bundle. A Windows bundle's marker must also
777
+ * name the root it sits at now: its junctions point into the root setup ran at, so a bundle moved
778
+ * or copied since is set up again, which makes them afresh (D153).
779
+ */
423
780
  async function readSetup(bundle) {
424
781
  try {
425
782
  const marker = BundleSetup.parse(JSON.parse(await readFile(join(bundle.root, BUNDLE_SETUP_MARKER), "utf8")));
426
783
  const { info } = bundle;
427
- return marker.files === info.files.sha256 && marker.version === info.version && marker.platform === info.platform && marker.browser.revision === info.browser.revision ? marker : void 0;
784
+ return (isWindowsBundle(info.platform) ? marker.root === realRoot(bundle.root) : true) && marker.files === info.files.sha256 && marker.version === info.version && marker.platform === info.platform && marker.browser.revision === info.browser.revision ? marker : void 0;
428
785
  } catch {
429
786
  return;
430
787
  }
@@ -433,15 +790,41 @@ async function readSetup(bundle) {
433
790
  function setupExtras(path) {
434
791
  return path === "bundle.json" || path === "files.json" || path === "browsers" || path.startsWith("browsers/") || path === BUNDLE_SETUP_MARKER || path.startsWith(`${BUNDLE_SETUP_MARKER}.tmp-`);
435
792
  }
436
- /** Checks the bundle's files; throws `MOSTRA_ENV_BUNDLE_INVALID` naming what differs. */
437
- async function checkFiles(bundle) {
793
+ /** The bundle's `files.json`, once its SHA-256 is the one `bundle.json` pins. */
794
+ async function readManifest(bundle) {
438
795
  const { root, info } = bundle;
439
796
  const listing = join(root, info.files.path);
440
797
  const { sha256 } = await hashFile(listing).catch(() => ({ sha256: "" }));
441
798
  if (sha256 !== info.files.sha256) throw invalid(`${info.files.path} doesn't match the SHA-256 that bundle.json pins.`);
442
799
  const manifest = BundleFiles.safeParse(JSON.parse(await readFile(listing, "utf8")));
443
800
  if (!manifest.success) throw invalid(`${info.files.path} isn't a bundle's file list.`);
444
- const problems = await checkTree(root, manifest.data, { allowExtra: setupExtras });
801
+ return manifest.data;
802
+ }
803
+ /**
804
+ * Makes a Windows bundle's links, each a junction at the bundle's real path (D153); nothing for
805
+ * any other bundle, whose archive carries its links. Throws `MOSTRA_ENV_BUNDLE_INVALID` for a link
806
+ * the bundle can't have.
807
+ */
808
+ async function makeLinks(bundle, read) {
809
+ if (!isWindowsBundle(bundle.info.platform)) return;
810
+ const manifest = read ?? await readManifest(bundle);
811
+ try {
812
+ await makeJunctions(realRoot(bundle.root), manifest);
813
+ } catch (error) {
814
+ if (error instanceof LinkRefused) throw invalid(`The runtime bundle's links: ${error.message}`);
815
+ throw error;
816
+ }
817
+ }
818
+ /**
819
+ * Checks the bundle's files; throws `MOSTRA_ENV_BUNDLE_INVALID` naming what differs. With
820
+ * `links: false` the files alone are checked (a Windows bundle before `makeLinks` made its junctions).
821
+ */
822
+ async function checkFiles(bundle, options = {}) {
823
+ const { root, info } = bundle;
824
+ const problems = await checkTree(root, options.manifest ?? await readManifest(bundle), {
825
+ allowExtra: setupExtras,
826
+ links: options.links ?? true
827
+ });
445
828
  if (problems.length > 0) throw invalid(`Mostra ${info.version}'s runtime bundle for ${info.platform} differs from its file list: ${problems.join("; ")}.`);
446
829
  }
447
830
  /** The browser files that differ from the pin, relative to `browsers/`. */
@@ -457,7 +840,7 @@ function installEnvironment(bundle, env) {
457
840
  const out = {};
458
841
  for (const [name, value] of Object.entries(env)) if (value !== void 0 && !name.startsWith("MOSTRA_") && name !== "PLAYWRIGHT_BROWSERS_PATH") out[name] = value;
459
842
  out["PLAYWRIGHT_BROWSERS_PATH"] = browsersDir(bundle.root);
460
- return out;
843
+ return childEnvironment(out);
461
844
  }
462
845
  /** The variables whose URLs may carry credentials the browser's fetch uses. */
463
846
  const CREDENTIAL_URLS = [
@@ -501,6 +884,7 @@ async function installBrowser(bundle, options) {
501
884
  "pipe",
502
885
  "pipe"
503
886
  ],
887
+ windowsHide: true,
504
888
  ...options.signal ? { signal: options.signal } : {},
505
889
  timeout: 9e5
506
890
  });
@@ -526,9 +910,11 @@ async function installBrowser(bundle, options) {
526
910
  async function setupBundle(root, options = {}) {
527
911
  const env = options.env ?? process.env;
528
912
  const bundle = await readBundle(root);
913
+ const manifest = isWindowsBundle(bundle.info.platform) || !options.filesChecked ? await readManifest(bundle) : void 0;
914
+ await makeLinks(bundle, manifest);
529
915
  if (!options.filesChecked) {
530
916
  options.onStep?.("files");
531
- await checkFiles(bundle);
917
+ await checkFiles(bundle, manifest ? { manifest } : {});
532
918
  }
533
919
  options.onStep?.("browser");
534
920
  if ((await checkBrowser(bundle)).length > 0) {
@@ -547,7 +933,8 @@ async function setupBundle(root, options = {}) {
547
933
  platform: bundle.info.platform,
548
934
  files: bundle.info.files.sha256,
549
935
  browser: { revision: bundle.info.browser.revision },
550
- at: (/* @__PURE__ */ new Date()).toISOString()
936
+ at: (/* @__PURE__ */ new Date()).toISOString(),
937
+ root: realRoot(root)
551
938
  };
552
939
  const temporary = join(root, `${BUNDLE_SETUP_MARKER}.tmp-${process.pid}`);
553
940
  await writeFile(temporary, `${JSON.stringify(marker, null, 2)}\n`);
@@ -564,14 +951,23 @@ async function setupBundle(root, options = {}) {
564
951
  * installers of one bundle share a lock, so it is downloaded once; a crash leaves a temporary
565
952
  * directory the next install removes, never a half-ready bundle.
566
953
  */
567
- /** Where the cache is: `MOSTRA_CACHE_DIR`, else the platform's per-user cache directory. */
954
+ /**
955
+ * Where the cache is: `MOSTRA_CACHE_DIR`, else the platform's per-user cache directory:
956
+ * `~/Library/Caches/mostra` on macOS, `%LOCALAPPDATA%\mostra-cache` on Windows (beside the home,
957
+ * `%LOCALAPPDATA%\mostra`, as npm keeps `npm-cache`), `${XDG_CACHE_HOME:-~/.cache}/mostra` on
958
+ * Linux.
959
+ */
568
960
  function cacheRoot(env, platform = process.platform) {
569
961
  const override = env["MOSTRA_CACHE_DIR"];
570
962
  if (override) return resolve(override);
963
+ if (platform === "win32") {
964
+ const local = env["LOCALAPPDATA"] || win32.join(env["USERPROFILE"] || homedir(), "AppData", "Local");
965
+ return win32.join(local, "mostra-cache");
966
+ }
571
967
  const home = env["HOME"] || homedir();
572
- if (platform === "darwin") return join(home, "Library", "Caches", "mostra");
968
+ if (platform === "darwin") return posix.join(home, "Library", "Caches", "mostra");
573
969
  const xdg = env["XDG_CACHE_HOME"];
574
- return join(xdg?.startsWith("/") ? xdg : join(home, ".cache"), "mostra");
970
+ return posix.join(xdg?.startsWith("/") ? xdg : posix.join(home, ".cache"), "mostra");
575
971
  }
576
972
  /** The directory a bundle with this archive digest lives in. */
577
973
  function bundleDir(env, sha256) {
@@ -628,7 +1024,8 @@ async function installPinned(pins, options) {
628
1024
  */
629
1025
  async function filesIntact(dir) {
630
1026
  try {
631
- await checkFiles(await readBundle(dir));
1027
+ const bundle = await readBundle(dir);
1028
+ await checkFiles(bundle, { links: !isWindowsBundle(bundle.info.platform) });
632
1029
  return true;
633
1030
  } catch (error) {
634
1031
  if (error instanceof RpcError && error.diagnostic.code === "MOSTRA_ENV_BUNDLE_INVALID") return false;
@@ -670,23 +1067,44 @@ async function fetchInto(pins, asset, dir, bundles, options) {
670
1067
  await mkdir(root);
671
1068
  const top = asset.file.replace(/\.tar\.gz$/, "");
672
1069
  if (top !== bundleAssetName(pins.version, options.platform).replace(/\.tar\.gz$/, "")) throw new RpcError(createDiagnostic("MOSTRA_ENV_BUNDLE_INVALID", { message: `The pinned archive ${asset.file} isn't Mostra ${pins.version}'s bundle for ${options.platform}.` }));
673
- await extractBundle(archive, root, top);
1070
+ const windows = isWindowsBundle(options.platform);
1071
+ await extractBundle(archive, root, top, { links: windows ? "refuse" : "keep" });
674
1072
  await rm(archive, { force: true });
675
1073
  const bundle = await readBundle(root);
676
1074
  if (bundle.info.version !== pins.version || bundle.info.platform !== options.platform) throw new RpcError(createDiagnostic("MOSTRA_ENV_BUNDLE_INVALID", { message: `The archive holds Mostra ${bundle.info.version} for ${bundle.info.platform}, not ${pins.version} for ${options.platform}.` }));
677
1075
  options.onProgress?.({ step: "files" });
678
- await checkFiles(bundle);
1076
+ await checkFiles(bundle, { links: !windows });
679
1077
  try {
680
- await rename(root, dir);
1078
+ await renameIntoPlace(root, dir);
681
1079
  } catch (error) {
682
1080
  const code = error.code;
683
- if (!(code === "ENOTEMPTY" || code === "EEXIST") || !await exists(dir)) throw error;
1081
+ if (!(code === "ENOTEMPTY" || code === "EEXIST" || code === "EPERM") || !await exists(dir)) throw error;
684
1082
  }
685
1083
  } finally {
686
1084
  await rm(scratch, {
687
1085
  recursive: true,
688
- force: true
689
- });
1086
+ force: true,
1087
+ maxRetries: 10,
1088
+ retryDelay: 200
1089
+ }).catch(() => void 0);
1090
+ }
1091
+ }
1092
+ /**
1093
+ * Renames `from` to `to`. On Windows a file that an antivirus scan or the indexer holds for a
1094
+ * moment refuses the rename (EPERM, EACCES, EBUSY) though nothing is wrong, so the rename is
1095
+ * tried again with backoff for up to 3 s, as the runtime's renames are (D150 item 8), and never
1096
+ * turned into a copy; a refusal that lasts is thrown, and EPERM over an existing directory with it.
1097
+ */
1098
+ async function renameIntoPlace(from, to) {
1099
+ const deadline = Date.now() + 3e3;
1100
+ for (let wait = 25;; wait = Math.min(wait * 2, 400)) try {
1101
+ await rename(from, to);
1102
+ return;
1103
+ } catch (error) {
1104
+ const code = error.code;
1105
+ const held = code === "EPERM" || code === "EACCES" || code === "EBUSY";
1106
+ if (process.platform !== "win32" || !held || Date.now() > deadline || await exists(to)) throw error;
1107
+ await new Promise((done) => setTimeout(done, wait));
690
1108
  }
691
1109
  }
692
1110
  /** Fails early when the cache's file system can't hold the bundle. */
@@ -735,40 +1153,65 @@ function withoutTrailingSlashes(url) {
735
1153
  return url.slice(0, end);
736
1154
  }
737
1155
  /**
738
- * Removes the lock at `path` when it is stale (its owner gone, or older than an hour) and says
739
- * whether it did. The lock is read and judged through one descriptor, then moved aside, and only
740
- * the file judged is removed: a fresh lock another installer took in between is put back (or,
741
- * if a third took one meanwhile, left to the next round). The lock only saves a second download;
742
- * the scratch directory and its rename keep the cache correct whatever happens here.
1156
+ * Judges the lock at `path` through one descriptor: `gone`, `live`, or stale (its owner gone, or
1157
+ * older than an hour) with what identifies the file judged.
743
1158
  */
744
- async function takeOverIfStale(path) {
1159
+ async function judgeLock(path) {
745
1160
  let handle;
746
1161
  try {
747
1162
  handle = await open(path, "r");
748
1163
  } catch {
749
- return true;
1164
+ return "gone";
750
1165
  }
751
- let judged;
752
1166
  try {
753
1167
  const info = await handle.stat();
754
- const owner = Number.parseInt(await handle.readFile("utf8"), 10);
755
- if (!(Date.now() - info.mtimeMs > STALE_LOCK_MS || Number.isInteger(owner) && owner > 0 && !alive(owner))) return false;
756
- judged = {
1168
+ const text = await handle.readFile("utf8");
1169
+ const owner = Number.parseInt(text, 10);
1170
+ return Date.now() - info.mtimeMs > STALE_LOCK_MS || Number.isInteger(owner) && owner > 0 && !alive(owner) ? {
757
1171
  ino: info.ino,
758
- dev: info.dev
759
- };
1172
+ dev: info.dev,
1173
+ text
1174
+ } : "live";
760
1175
  } finally {
761
1176
  await handle.close();
762
1177
  }
1178
+ }
1179
+ /**
1180
+ * Moves the lock at `path` aside and removes it only if it is the file `judged` describes, by
1181
+ * identity and by contents: a fresh lock another installer took in between is put back (or, if a
1182
+ * third took one meanwhile, left to the next round). The contents matter because a file system may
1183
+ * give a new file the number of one just removed (ext4 does at once), and each lock holds its
1184
+ * owner's PID and its own token (MT-02).
1185
+ */
1186
+ async function removeJudged(path, judged) {
763
1187
  const aside = `${path}.stale-${randomBytes(6).toString("hex")}`;
764
1188
  try {
765
1189
  await rename(path, aside);
766
1190
  } catch {
767
- return true;
1191
+ return;
1192
+ }
1193
+ let same = false;
1194
+ const handle = await open(aside, "r").catch(() => void 0);
1195
+ if (handle) try {
1196
+ const moved = await handle.stat();
1197
+ const text = await handle.readFile("utf8");
1198
+ same = moved.ino === judged.ino && moved.dev === judged.dev && text === judged.text;
1199
+ } catch {} finally {
1200
+ await handle.close();
768
1201
  }
769
- const moved = await stat(aside).catch(() => void 0);
770
- if (moved && (moved.ino !== judged.ino || moved.dev !== judged.dev)) await link(aside, path).catch(() => void 0);
1202
+ if (!same) await link(aside, path).catch(() => void 0);
771
1203
  await rm(aside, { force: true });
1204
+ }
1205
+ /**
1206
+ * Removes the lock at `path` when it is stale and says whether it may be taken now. The lock only
1207
+ * saves a second download; the scratch directory and its rename keep the cache correct whatever
1208
+ * happens here.
1209
+ */
1210
+ async function takeOverIfStale(path) {
1211
+ const judged = await judgeLock(path);
1212
+ if (judged === "gone") return true;
1213
+ if (judged === "live") return false;
1214
+ await removeJudged(path, judged);
772
1215
  return true;
773
1216
  }
774
1217
  /**
@@ -806,8 +1249,9 @@ async function lock(path, signal) {
806
1249
  //#endregion
807
1250
  //#region src/platform.ts
808
1251
  /**
809
- * Which runtime bundle this machine takes (RT-01, D35): one per operating system and architecture
810
- * of v1, glibc only on Linux. Anything else fails closed before a download starts.
1252
+ * Which runtime bundle this machine takes (RT-01, RT-12, D35, D146): one per operating system and
1253
+ * architecture of v1 (macOS, glibc Linux and Windows, each on x64 and arm64). Anything else fails
1254
+ * closed before a download starts.
811
1255
  */
812
1256
  /**
813
1257
  * The glibc release Node.js reports, read from its diagnostic report's header. The report runs in
@@ -839,14 +1283,14 @@ function currentPlatform() {
839
1283
  return facts;
840
1284
  }
841
1285
  /**
842
- * The bundle platform for these facts. Throws `MOSTRA_PLATFORM_UNSUPPORTED` for Windows, other
843
- * architectures and Linux without glibc, whose libraries the bundle's Node.js and browser need.
1286
+ * The bundle platform for these facts. Throws `MOSTRA_PLATFORM_UNSUPPORTED` for other systems and
1287
+ * architectures and for Linux without glibc, whose libraries the bundle's Node.js and browser need.
844
1288
  */
845
1289
  function bundlePlatform(facts = currentPlatform()) {
846
1290
  const name = `${facts.platform}-${facts.arch}`;
847
1291
  const known = BUNDLE_PLATFORMS.includes(name);
848
- if (known && facts.platform === "linux" && facts.glibc === void 0) throw unsupported(`Mostra's Linux bundle needs glibc, and this system has none (musl, as on Alpine Linux); it supports macOS and glibc-based Linux on x64 and arm64.`);
849
- if (!known) throw unsupported(`Mostra doesn't run on ${facts.platform === "win32" ? `Windows (${name})` : name}; it supports macOS and Linux on x64 and arm64.`);
1292
+ if (known && facts.platform === "linux" && facts.glibc === void 0) throw unsupported(`Mostra's Linux bundle needs glibc, and this system has none (musl, as on Alpine Linux); it supports macOS, glibc-based Linux and Windows on x64 and arm64.`);
1293
+ if (!known) throw unsupported(`Mostra doesn't run on ${facts.platform === "win32" ? `Windows (${name})` : name}; it supports macOS, Linux and Windows on x64 and arm64.`);
850
1294
  return name;
851
1295
  }
852
1296
  function unsupported(message) {
@@ -907,7 +1351,7 @@ function packageRoot() {
907
1351
  */
908
1352
  function pinsFile(env, root) {
909
1353
  const override = env["MOSTRA_TEST_BUNDLE_PINS"];
910
- const installed = root.split(sep).includes("node_modules");
1354
+ const installed = root.split(/[\\/]/).includes("node_modules");
911
1355
  return override && !installed ? override : join(root, "dist", "bundles.json");
912
1356
  }
913
1357
  /** The pins this build carries: `dist/bundles.json` (a test override applies only in a development checkout). */
@@ -1005,6 +1449,6 @@ async function resolveRuntime(options = {}) {
1005
1449
  throw new RpcError(createDiagnostic("MOSTRA_ENV_BUNDLE_UNAVAILABLE", { message: "This build of @mostra/sdk pins no runtime bundle and has no runtime beside it; set MOSTRA_BUNDLE to an extracted bundle." }));
1006
1450
  }
1007
1451
  //#endregion
1008
- export { safeRelative as C, linkStaysInside as S, setupBundle as _, sdkVersion as a, describeTree as b, bundleDir as c, browsersDir as d, checkBrowser as f, readSetup as g, readBundle as h, runtimeOf as i, cacheRoot as l, offline as m, readPins as n, bundlePlatform as o, checkFiles as p, resolveRuntime as r, currentPlatform as s, enclosingBundle as t, installPinned as u, setupExtras as v, redactUrl as w, hashFile as x, checkTree as y };
1452
+ export { safeRelative as C, linkStaysInside as S, redactUrl as T, setupBundle as _, sdkVersion as a, describeTree as b, bundleDir as c, browsersDir as d, checkBrowser as f, readSetup as g, readBundle as h, runtimeOf as i, cacheRoot as l, offline as m, readPins as n, bundlePlatform as o, checkFiles as p, resolveRuntime as r, currentPlatform as s, enclosingBundle as t, installPinned as u, setupExtras as v, childEnvironment as w, hashFile as x, checkTree as y };
1009
1453
 
1010
- //# sourceMappingURL=runtime-CUbnK5Za.js.map
1454
+ //# sourceMappingURL=runtime-NiLgW1ED.js.map