@zackees/soldr 0.9.20 → 0.9.21

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zackees/soldr",
3
- "version": "0.9.20",
3
+ "version": "0.9.21",
4
4
  "description": "Instant Rust tools and builds from one command.",
5
5
  "license": "BSD-3-Clause",
6
6
  "homepage": "https://github.com/zackees/soldr",
@@ -139,6 +139,49 @@ function platformTarget(platform = process.platform, arch = process.arch, libc =
139
139
  return target;
140
140
  }
141
141
 
142
+ // The ORDERED list of release artifacts this host may install (soldr#1060).
143
+ //
144
+ // The RFC's policy is "failure -> try the corresponding sibling build", and
145
+ // the honest generalization is "retry the OTHER libc", not "always retry gnu":
146
+ // `detectLibc` already prefers gnu when the host's glibc is at or above
147
+ // MIN_GLIBC_FOR_GNU, so on those hosts the fallback is musl and on every other
148
+ // Linux host it is gnu. Both directions are real: a gnu-preferring host whose
149
+ // -gnu artifact is missing from a release still has a musl artifact that runs
150
+ // there, and a musl-preferring host whose musl artifact 404s can still try gnu.
151
+ //
152
+ // Non-Linux platforms are single-candidate: there is no sibling libc to fall
153
+ // back to, and silently installing a different macOS/Windows triple would be
154
+ // wrong rather than merely slower.
155
+ function platformCandidates(platform = process.platform, arch = process.arch, libc = detectLibc(platform)) {
156
+ // Resolve the preferred artifact through `platformTarget` rather than
157
+ // rebuilding the key rule here. Two copies of "which artifact does this host
158
+ // want?" are free to disagree silently: a hand-rolled `libc === "gnu" ? ... :
159
+ // "musl"` would quietly answer musl for an unrecognised libc string that
160
+ // `platformTarget` treats as a hard error, so the two entry points would
161
+ // return different things for the same input. One implementation, one answer
162
+ // -- including the unsupported-platform throw.
163
+ const primary = platformTarget(platform, arch, libc);
164
+ if (platform !== "linux") {
165
+ return [primary];
166
+ }
167
+ // Read the preferred libc back off the RESOLVED triple instead of off the
168
+ // `libc` argument: platformTarget has already applied its own
169
+ // `libc || "musl"` default, and re-deriving it is exactly where a second
170
+ // copy would drift from the first.
171
+ const sibling = primary.triple.endsWith("-gnu") ? "musl" : "gnu";
172
+ const candidates = [primary];
173
+ try {
174
+ const fallback = platformTarget(platform, arch, sibling);
175
+ if (fallback.triple !== primary.triple) {
176
+ candidates.push(fallback);
177
+ }
178
+ } catch (err) {
179
+ // A future arch published for only one libc (the RFC's deferred armv7 is
180
+ // musl-only) has no sibling. One candidate is correct there, not an error.
181
+ }
182
+ return candidates;
183
+ }
184
+
142
185
  function releaseBaseUrl(version) {
143
186
  const override = process.env.SOLDR_NPM_RELEASE_BASE_URL;
144
187
  if (override) {
@@ -277,16 +320,17 @@ function findExtractedBinary(root, binaryName) {
277
320
  return null;
278
321
  }
279
322
 
280
- async function install() {
281
- if (process.env.SOLDR_NPM_SKIP_DOWNLOAD) {
282
- console.log("soldr: skipping native binary download because SOLDR_NPM_SKIP_DOWNLOAD is set");
283
- return;
284
- }
285
-
286
- const version = PACKAGE_JSON.version;
287
- const target = platformTarget();
323
+ // Download, verify, and install one candidate target's release archive into
324
+ // bin/native/. Extracted from install() (soldr#1060) so a retry loop can call
325
+ // it once per candidate.
326
+ //
327
+ // A failed candidate must not leave bin/native/ half-populated for the next
328
+ // one, so every source path is resolved and validated first: manifest
329
+ // location + parse + validateReleaseManifest, then every findExtractedBinary
330
+ // lookup for BUNDLED_BINARIES and soldrDebugInfoEntries. Only once every
331
+ // source is known-present does bin/native/ get cleared and repopulated.
332
+ async function installRelease(target, version, baseUrl) {
288
333
  const filename = `soldr-v${version}-${target.triple}.${ARCHIVE_EXT}`;
289
- const baseUrl = releaseBaseUrl(version);
290
334
  const archiveUrl = `${baseUrl}/${filename}`;
291
335
  const checksumUrl = `${baseUrl}/soldr-v${version}-SHA256SUMS.txt`;
292
336
  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "soldr-npm-"));
@@ -307,14 +351,12 @@ async function install() {
307
351
  extractArchive(archivePath, extractDir);
308
352
 
309
353
  const nativeDir = path.join(PACKAGE_ROOT, "bin", "native");
310
- fs.rmSync(nativeDir, { recursive: true, force: true });
311
- fs.mkdirSync(nativeDir, { recursive: true });
312
354
 
313
- // Copy every bundled binary so soldr has its daemon and can find
314
- // crgx via SOLDR_CRGX_LOCAL_DIR and cargo-chef via
315
- // SOLDR_CARGO_CHEF_LOCAL_DIR.
316
- // `bin/soldr.js` wires these env vars before exec. The archive
317
- // layout is flat: all bundled binaries live at the archive root.
355
+ // Resolve every source before touching bin/native/. `bin/soldr.js`
356
+ // wires SOLDR_CRGX_LOCAL_DIR / SOLDR_CARGO_CHEF_LOCAL_DIR to this dir,
357
+ // so soldr has its daemon and can find crgx / cargo-chef once this
358
+ // completes. The archive layout is flat: all bundled binaries live at
359
+ // the archive root.
318
360
  const binaryExt = target.binary.endsWith(".exe") ? ".exe" : "";
319
361
  const manifestSrc = findExtractedBinary(extractDir, zccacheContract.MANIFEST_NAME);
320
362
  if (!manifestSrc) {
@@ -332,30 +374,41 @@ async function install() {
332
374
  return filePath;
333
375
  },
334
376
  });
377
+
378
+ const copyPlan = [];
335
379
  for (const baseName of BUNDLED_BINARIES) {
336
380
  const fileName = `${baseName}${binaryExt}`;
337
381
  const src = findExtractedBinary(extractDir, fileName);
338
382
  if (!src) {
339
383
  throw new Error(`release archive ${filename} did not contain ${fileName}`);
340
384
  }
341
- const dst = path.join(nativeDir, fileName);
342
- fs.copyFileSync(src, dst);
343
- if (process.platform !== "win32") {
344
- fs.chmodSync(dst, 0o755);
345
- }
385
+ copyPlan.push({ src, dst: path.join(nativeDir, fileName), executable: true });
346
386
  }
347
387
  for (const entry of zccacheContract.soldrDebugInfoEntries(manifest)) {
348
388
  const src = findExtractedBinary(extractDir, entry.name);
349
389
  if (!src) {
350
390
  throw new Error(`release archive ${filename} did not contain ${entry.name}`);
351
391
  }
352
- fs.copyFileSync(src, path.join(nativeDir, entry.name));
392
+ copyPlan.push({ src, dst: path.join(nativeDir, entry.name), executable: false });
353
393
  }
354
-
355
394
  // Drop manifest.json alongside the binaries so downstream tooling
356
395
  // (and humans reading `bin/native/`) can introspect provenance —
357
396
  // soldr / zccache versions, target triples, build commit, sha256s.
358
- fs.copyFileSync(manifestSrc, path.join(nativeDir, zccacheContract.MANIFEST_NAME));
397
+ copyPlan.push({
398
+ src: manifestSrc,
399
+ dst: path.join(nativeDir, zccacheContract.MANIFEST_NAME),
400
+ executable: false,
401
+ });
402
+
403
+ // Every source is known-present now — safe to clear and repopulate.
404
+ fs.rmSync(nativeDir, { recursive: true, force: true });
405
+ fs.mkdirSync(nativeDir, { recursive: true });
406
+ for (const { src, dst, executable } of copyPlan) {
407
+ fs.copyFileSync(src, dst);
408
+ if (executable && process.platform !== "win32") {
409
+ fs.chmodSync(dst, 0o755);
410
+ }
411
+ }
359
412
 
360
413
  console.log(
361
414
  `soldr: installed ${target.triple} (soldr + daemon + crgx + cargo-chef) into ${nativeDir}`,
@@ -365,6 +418,59 @@ async function install() {
365
418
  }
366
419
  }
367
420
 
421
+ // Walk `candidates` in order, returning the first that installs. `attempt` is
422
+ // injected (rather than inlined into install()) so the fallthrough policy can
423
+ // be tested without a network: an untestable retry loop is how "we have a
424
+ // fallback" becomes true in the comments and false in the code.
425
+ async function installFirstWorkingCandidate(candidates, attempt, log = console) {
426
+ if (!Array.isArray(candidates) || candidates.length === 0) {
427
+ // A zero-length list would fall straight through the loop to a rejection
428
+ // whose detail string is empty -- "could not install ()" tells nobody
429
+ // anything. platformCandidates never produces one (it throws instead), so
430
+ // reaching here means the caller built the list some other way.
431
+ throw new Error("no soldr release candidates to install (empty candidate list)");
432
+ }
433
+ const failures = [];
434
+ for (let index = 0; index < candidates.length; index += 1) {
435
+ const target = candidates[index];
436
+ try {
437
+ await attempt(target);
438
+ if (index > 0) {
439
+ log.warn(
440
+ `soldr: installed the sibling libc build ${target.triple} instead of the ` +
441
+ `preferred ${failures[0].target.triple} (${failures.length} candidate(s) failed first)`,
442
+ );
443
+ }
444
+ return target;
445
+ } catch (error) {
446
+ failures.push({ target, error });
447
+ const next = candidates[index + 1];
448
+ if (next) {
449
+ log.warn(
450
+ `soldr: ${target.triple} failed (${error.message}); falling back to the sibling libc build ${next.triple}`,
451
+ );
452
+ }
453
+ }
454
+ }
455
+ const detail = failures
456
+ .map(({ target, error }) => `${target.triple}: ${error.message}`)
457
+ .join("; ");
458
+ throw new Error(`no soldr release artifact could be installed (${detail})`);
459
+ }
460
+
461
+ async function install() {
462
+ if (process.env.SOLDR_NPM_SKIP_DOWNLOAD) {
463
+ console.log("soldr: skipping native binary download because SOLDR_NPM_SKIP_DOWNLOAD is set");
464
+ return;
465
+ }
466
+ const version = PACKAGE_JSON.version;
467
+ const baseUrl = releaseBaseUrl(version);
468
+ const candidates = platformCandidates();
469
+ await installFirstWorkingCandidate(candidates, (target) =>
470
+ installRelease(target, version, baseUrl),
471
+ );
472
+ }
473
+
368
474
  if (require.main === module) {
369
475
  install().catch((error) => {
370
476
  console.error(`soldr: npm install failed: ${error.message}`);
@@ -382,5 +488,7 @@ module.exports = {
382
488
  verifyArchiveChecksum,
383
489
  detectLibc,
384
490
  platformTarget,
491
+ platformCandidates,
492
+ installFirstWorkingCandidate,
385
493
  releaseBaseUrl,
386
494
  };
@@ -112,6 +112,91 @@ assert.strictEqual(install.platformTarget("win32", "x64").triple, "x86_64-pc-win
112
112
  assert.strictEqual(install.platformTarget("win32", "arm64").triple, "aarch64-pc-windows-msvc");
113
113
  assert.throws(() => install.platformTarget("freebsd", "x64"), /unsupported platform/);
114
114
 
115
+ // platformCandidates orders the download attempts for a host. Linux gets a
116
+ // preferred triple plus a sibling-libc fallback so a wrong libc guess (or a
117
+ // missing release asset) can be retried without a second npm install; every
118
+ // other platform has no sibling to fall back to.
119
+ const triples = (list) => list.map((t) => t.triple);
120
+
121
+ // a. A glibc new enough for the shipped artifact prefers gnu, with musl as
122
+ // the fallback if the gnu asset turns out to be missing or broken.
123
+ assert.deepStrictEqual(triples(install.platformCandidates("linux", "x64", "gnu")), [
124
+ "x86_64-unknown-linux-gnu",
125
+ "x86_64-unknown-linux-musl",
126
+ ]);
127
+ assert.deepStrictEqual(triples(install.platformCandidates("linux", "arm64", "gnu")), [
128
+ "aarch64-unknown-linux-gnu",
129
+ "aarch64-unknown-linux-musl",
130
+ ]);
131
+
132
+ // b. An old/unknown glibc, or a musl system, prefers musl -- gnu would not
133
+ // even run -- but still lists gnu second in case musl's own asset is the
134
+ // one that is missing.
135
+ assert.deepStrictEqual(triples(install.platformCandidates("linux", "x64", "musl")), [
136
+ "x86_64-unknown-linux-musl",
137
+ "x86_64-unknown-linux-gnu",
138
+ ]);
139
+ assert.deepStrictEqual(triples(install.platformCandidates("linux", "arm64", "musl")), [
140
+ "aarch64-unknown-linux-musl",
141
+ "aarch64-unknown-linux-gnu",
142
+ ]);
143
+
144
+ // c. `libc === null` (both detectLibc probes unavailable) must behave like
145
+ // musl, matching detectLibc's own unknown case (line 105-108) rather than
146
+ // contradicting it -- picking gnu here would be the opposite of the
147
+ // "unknown host, run anywhere" reasoning detectLibc already applies.
148
+ assert.deepStrictEqual(triples(install.platformCandidates("linux", "x64", null)), [
149
+ "x86_64-unknown-linux-musl",
150
+ "x86_64-unknown-linux-gnu",
151
+ ]);
152
+
153
+ // d. Non-Linux platforms have exactly one candidate: there is no sibling
154
+ // libc, and "falling back" to a different macOS/Windows triple would
155
+ // install a binary that cannot run on the host at all.
156
+ assert.deepStrictEqual(triples(install.platformCandidates("darwin", "arm64")), [
157
+ "aarch64-apple-darwin",
158
+ ]);
159
+ assert.strictEqual(install.platformCandidates("darwin", "x64").length, 1);
160
+ assert.strictEqual(install.platformCandidates("win32", "x64").length, 1);
161
+ assert.strictEqual(install.platformCandidates("win32", "arm64").length, 1);
162
+
163
+ // e. An arch/platform we do not ship at all is still a hard error, not an
164
+ // empty candidate list a caller could silently iterate zero times over.
165
+ assert.throws(() => install.platformCandidates("freebsd", "x64"), /unsupported platform/);
166
+ assert.throws(() => install.platformCandidates("linux", "riscv64", "gnu"), /unsupported platform/);
167
+
168
+ // e2. platformCandidates must resolve its preferred artifact THROUGH
169
+ // platformTarget rather than rebuilding the key rule, so the two can
170
+ // never answer differently for the same input. An unrecognised libc
171
+ // string is where a second hand-rolled `libc === "gnu" ? ... : "musl"`
172
+ // copy would silently answer musl while platformTarget throws.
173
+ assert.throws(() => install.platformTarget("linux", "x64", "uclibc"), /unsupported platform/);
174
+ assert.throws(() => install.platformCandidates("linux", "x64", "uclibc"), /unsupported platform/);
175
+
176
+ // f. Structural invariants for every Linux candidate list: the two
177
+ // candidates are distinct, the first one is unchanged from what
178
+ // `platformTarget` already picks for the same args (this feature must
179
+ // not change the shipped preference), and every candidate is a real
180
+ // entry from TARGETS rather than a hand-built object that happens to
181
+ // look right.
182
+ for (const [arch, libc] of [
183
+ ["x64", "gnu"],
184
+ ["x64", "musl"],
185
+ ["x64", null],
186
+ ["arm64", "gnu"],
187
+ ["arm64", "musl"],
188
+ ]) {
189
+ const candidates = install.platformCandidates("linux", arch, libc);
190
+ assert.notStrictEqual(candidates[0].triple, candidates[1].triple);
191
+ assert.deepStrictEqual(candidates[0], install.platformTarget("linux", arch, libc));
192
+ for (const candidate of candidates) {
193
+ assert.ok(
194
+ Object.values(install.TARGETS).includes(candidate),
195
+ `platformCandidates("linux", "${arch}", ${libc}) returned an object not in TARGETS`,
196
+ );
197
+ }
198
+ }
199
+
115
200
  // detectLibc must return null on non-Linux platforms so the platform key
116
201
  // stays `<platform>-<arch>` rather than `<platform>-<arch>-gnu`.
117
202
  assert.strictEqual(install.detectLibc("darwin"), null);
@@ -203,6 +288,74 @@ assert.strictEqual(
203
288
  null,
204
289
  );
205
290
 
291
+ // g. Candidate ordering driven end to end from the HOST's glibc rather than
292
+ // from a literal libc string. The RFC states its cases as "new glibc" /
293
+ // "old glibc", and `libc` is only detectLibc's answer to that question --
294
+ // asserting the order for the string "gnu" proves the ordering helper
295
+ // works, not that a new-glibc host reaches it. Composing the two is what
296
+ // covers the path install() actually walks.
297
+ {
298
+ // One step below the shipped floor, derived rather than hardcoded. A
299
+ // literal "2.36" here would stop testing the too-old branch the day
300
+ // MIN_GLIBC_FOR_GNU drops to 2.17 -- it would silently become a
301
+ // new-ENOUGH version and this case would assert the opposite of its name.
302
+ const floorParts = install.MIN_GLIBC_FOR_GNU.split(".").map((p) => parseInt(p, 10) || 0);
303
+ floorParts[floorParts.length - 1] -= 1;
304
+ const TOO_OLD = floorParts.join(".");
305
+ assert.strictEqual(
306
+ install.compareVersions(TOO_OLD, install.MIN_GLIBC_FOR_GNU),
307
+ -1,
308
+ `derived too-old glibc ${TOO_OLD} must sort below ${install.MIN_GLIBC_FOR_GNU}`,
309
+ );
310
+
311
+ const GLIBC_LIB = ["ld-linux-x86-64.so.2", "libc.so.6"];
312
+ const candidatesForHost = (probes) =>
313
+ triples(install.platformCandidates("linux", "x64", install.detectLibc("linux", probes)));
314
+
315
+ // New-enough glibc -> gnu first, musl second as the sibling fallback.
316
+ assert.deepStrictEqual(
317
+ candidatesForHost({
318
+ readHeader: () => ({ glibcVersionRuntime: NEW_ENOUGH }),
319
+ listLib: () => GLIBC_LIB,
320
+ }),
321
+ ["x86_64-unknown-linux-gnu", "x86_64-unknown-linux-musl"],
322
+ );
323
+ // Too-old glibc (the Debian 12 case that motivated soldr#1060) -> musl
324
+ // first, because gnu would not even load, but gnu is still listed second
325
+ // so a missing/broken musl asset is recoverable without a second install.
326
+ assert.deepStrictEqual(
327
+ candidatesForHost({
328
+ readHeader: () => ({ glibcVersionRuntime: TOO_OLD }),
329
+ listLib: () => GLIBC_LIB,
330
+ }),
331
+ ["x86_64-unknown-linux-musl", "x86_64-unknown-linux-gnu"],
332
+ );
333
+ // A musl SYSTEM reaches the same order through the /lib probe.
334
+ assert.deepStrictEqual(
335
+ candidatesForHost({ readHeader: () => ({}), listLib: () => ["ld-musl-x86_64.so.1"] }),
336
+ ["x86_64-unknown-linux-musl", "x86_64-unknown-linux-gnu"],
337
+ );
338
+ // Both probes dead -> still musl-first, never an empty or single list that
339
+ // would quietly drop the fallback on exactly the hosts that need it most.
340
+ assert.deepStrictEqual(
341
+ candidatesForHost({ readHeader: throwingProbe, listLib: throwingProbe }),
342
+ ["x86_64-unknown-linux-musl", "x86_64-unknown-linux-gnu"],
343
+ );
344
+ }
345
+
346
+ // h. The zero-argument shape install() itself calls: on this host the first
347
+ // candidate must still be exactly what platformTarget picks today. The
348
+ // retry may add a fallback; it may not change which artifact is preferred.
349
+ {
350
+ const hostCandidates = install.platformCandidates();
351
+ assert.deepStrictEqual(hostCandidates[0], install.platformTarget());
352
+ assert.strictEqual(
353
+ hostCandidates.length,
354
+ process.platform === "linux" ? 2 : 1,
355
+ `platformCandidates() length on ${process.platform}: ${triples(hostCandidates).join(", ")}`,
356
+ );
357
+ }
358
+
206
359
  // MIN_GLIBC_FOR_GNU must track the ceiling release-auto.yml enforces on the
207
360
  // gnu BINARIES. If the release build is fixed to link a 2.17 baseline and that
208
361
  // ceiling drops, the installer must follow it down -- otherwise every glibc
@@ -453,4 +606,175 @@ for (const required of [
453
606
  );
454
607
  }
455
608
 
456
- console.log("npm package and PyPI version checks passed");
609
+ // installFirstWorkingCandidate's retry policy: it must try candidates in
610
+ // order, stay quiet on the common case, and when it does fall back, the log
611
+ // has to say which artifact failed, why, and which one was installed
612
+ // instead -- otherwise a user staring at a successful install with the
613
+ // "wrong" binary has no way to find out why.
614
+ async function checkCandidateFallback() {
615
+ const gnu = { triple: "x86_64-unknown-linux-gnu", binary: "soldr" };
616
+ const musl = { triple: "x86_64-unknown-linux-musl", binary: "soldr" };
617
+ const collector = () => {
618
+ const lines = [];
619
+ return { lines, warn: (line) => lines.push(line) };
620
+ };
621
+
622
+ // 1. First candidate succeeds -> it is returned, attempt ran exactly once,
623
+ // and nothing is logged. A normal install must stay quiet; logging a
624
+ // "warning" on the success path would train users to ignore warnings.
625
+ {
626
+ const log = collector();
627
+ const attempts = [];
628
+ const result = await install.installFirstWorkingCandidate(
629
+ [gnu, musl],
630
+ async (target) => {
631
+ attempts.push(target.triple);
632
+ return target;
633
+ },
634
+ log,
635
+ );
636
+ assert.deepStrictEqual(result, gnu);
637
+ assert.deepStrictEqual(attempts, [gnu.triple]);
638
+ assert.deepStrictEqual(log.lines, []);
639
+ }
640
+
641
+ // 2. First candidate fails, sibling succeeds -> resolves with the sibling,
642
+ // attempts happened in order (gnu before musl -- it must not try the
643
+ // sibling first), and the log names both the failed triple and its
644
+ // reason, plus a line reporting the sibling that was actually
645
+ // installed. This is the RFC's whole point: the log must say what
646
+ // happened and why.
647
+ {
648
+ const log = collector();
649
+ const attempts = [];
650
+ const result = await install.installFirstWorkingCandidate(
651
+ [gnu, musl],
652
+ async (target) => {
653
+ attempts.push(target.triple);
654
+ if (target.triple === gnu.triple) {
655
+ throw new Error("HTTP 404");
656
+ }
657
+ return target;
658
+ },
659
+ log,
660
+ );
661
+ assert.deepStrictEqual(result, musl);
662
+ assert.deepStrictEqual(attempts, [gnu.triple, musl.triple]);
663
+ assert.ok(
664
+ log.lines.some((l) => l.includes("x86_64-unknown-linux-gnu") && l.includes("HTTP 404")),
665
+ "fallthrough must log the failed triple and the reason",
666
+ );
667
+ // Must be a line that says something was INSTALLED, naming both what was
668
+ // installed and what was preferred. Matching the musl triple alone is not
669
+ // enough: the fallthrough warning already names it, so that weaker check
670
+ // would still pass if the success line were deleted entirely.
671
+ assert.ok(
672
+ log.lines.some(
673
+ (l) =>
674
+ l.includes("installed") &&
675
+ l.includes("x86_64-unknown-linux-musl") &&
676
+ l.includes("x86_64-unknown-linux-gnu"),
677
+ ),
678
+ `a non-first success must log what was installed and what was preferred: ${log.lines.join(" | ")}`,
679
+ );
680
+ }
681
+
682
+ // 3. Both candidates fail -> the promise rejects, and the rejection names
683
+ // every triple and every reason. A fallback that swallows the original
684
+ // error on the way to the final rejection makes the failure
685
+ // unreportable -- exactly the failure mode this feature exists to fix.
686
+ {
687
+ const log = collector();
688
+ const promise = install.installFirstWorkingCandidate(
689
+ [gnu, musl],
690
+ async (target) => {
691
+ if (target.triple === gnu.triple) {
692
+ throw new Error("HTTP 404");
693
+ }
694
+ throw new Error("checksum mismatch");
695
+ },
696
+ log,
697
+ );
698
+ await assert.rejects(promise, /no soldr release artifact could be installed/);
699
+ await assert.rejects(
700
+ promise,
701
+ (err) =>
702
+ err.message.includes("x86_64-unknown-linux-gnu") &&
703
+ err.message.includes("x86_64-unknown-linux-musl") &&
704
+ err.message.includes("HTTP 404") &&
705
+ err.message.includes("checksum mismatch"),
706
+ );
707
+ // Exactly one log line: the gnu -> musl fallthrough. Nothing may claim an
708
+ // install happened when every candidate failed.
709
+ assert.strictEqual(log.lines.length, 1, `unexpected log lines: ${log.lines.join(" | ")}`);
710
+ assert.ok(
711
+ !log.lines.some((l) => l.includes("installed")),
712
+ "an all-candidates-failed run must not log that anything was installed",
713
+ );
714
+ }
715
+
716
+ // 4. Single-candidate (the non-Linux shape) failure -> rejects, attempted
717
+ // exactly once, and nothing is logged. There is no sibling to fall back
718
+ // to, so nothing may claim a fallback happened.
719
+ {
720
+ const log = collector();
721
+ const attempts = [];
722
+ const promise = install.installFirstWorkingCandidate(
723
+ [{ triple: "aarch64-apple-darwin", binary: "soldr" }],
724
+ async (target) => {
725
+ attempts.push(target.triple);
726
+ throw new Error("HTTP 404");
727
+ },
728
+ log,
729
+ );
730
+ await assert.rejects(promise, /no soldr release artifact could be installed/);
731
+ assert.strictEqual(attempts.length, 1);
732
+ assert.deepStrictEqual(log.lines, []);
733
+ }
734
+
735
+ // 4b. An empty candidate list is rejected with a message that says so,
736
+ // rather than falling through the loop to "could not be installed ()"
737
+ // with an empty reason list. platformCandidates throws instead of
738
+ // returning one, so this only fires for a hand-built list.
739
+ {
740
+ const log = collector();
741
+ let attempted = false;
742
+ await assert.rejects(
743
+ install.installFirstWorkingCandidate([], async () => {
744
+ attempted = true;
745
+ }, log),
746
+ /empty candidate list/,
747
+ );
748
+ assert.strictEqual(attempted, false);
749
+ assert.deepStrictEqual(log.lines, []);
750
+ }
751
+
752
+ // 5. Real-shape wiring: platformCandidates feeding straight into
753
+ // installFirstWorkingCandidate resolves with the sibling when the
754
+ // preferred triple fails, proving the ordering helper and the retry
755
+ // loop compose the way install() actually uses them.
756
+ {
757
+ const log = collector();
758
+ const candidates = install.platformCandidates("linux", "x64", "musl");
759
+ const result = await install.installFirstWorkingCandidate(
760
+ candidates,
761
+ async (target) => {
762
+ if (target.triple === "x86_64-unknown-linux-musl") {
763
+ throw new Error("HTTP 404");
764
+ }
765
+ return target;
766
+ },
767
+ log,
768
+ );
769
+ assert.strictEqual(result.triple, "x86_64-unknown-linux-gnu");
770
+ }
771
+ }
772
+
773
+ checkCandidateFallback()
774
+ .then(() => {
775
+ console.log("npm package and PyPI version checks passed");
776
+ })
777
+ .catch((error) => {
778
+ console.error(error && error.stack ? error.stack : error);
779
+ process.exit(1);
780
+ });