@zackees/soldr 0.9.20 → 0.9.22

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/README.md CHANGED
@@ -76,7 +76,7 @@ every later build on any branch or worktree hits the shared cache.
76
76
  | `soldr build --target <triple\|alias>` | Blessed cross-compile with a managed SDK (`win-x64`, `mac-arm64`, `linux-x64-musl`, ...) |
77
77
  | `soldr cc` / `soldr c++` | Compile C / C++ with a catalogue-backed toolchain |
78
78
  | `soldr lint` | Unified Rust and dependency lint suites |
79
- | `soldr ci-test` | **The supported way to test soldr-built projects.** The prescribed host-validation DAG used in CI — see [Testing strategy](#testing-strategy) |
79
+ | `soldr ci-test` | **The supported way to test soldr-built projects.** The prescribed validation DAG used in CI — see [Testing strategy](#testing-strategy) |
80
80
  | `soldr <tool>` | Fetch and run a pre-built ecosystem tool: `nextest`, `deny`, `audit`, `mdbook`, `just`, ... |
81
81
 
82
82
  ### Testing strategy
@@ -89,21 +89,23 @@ Hand-rolled sequences of `cargo fmt` + `cargo clippy` + `cargo nextest` + doctes
89
89
  recompile the same crates several times over and drift apart from what CI runs.
90
90
 
91
91
  ```bash
92
- soldr ci-test # the whole host-validation DAG
92
+ soldr ci-test # build and run the host-validation DAG
93
93
  soldr ci-test --explain-plan --format json # inspect the plan, no compiler work
94
94
  soldr ci-test --package soldr-core # host-scope narrowing
95
+ soldr ci-test --no-run --target mac-arm64 # compile and archive a foreign target
95
96
  ```
96
97
 
97
- **Know the one boundary.** `ci-test` validates on the *host* and deliberately
98
- **rejects** `--target`, `--toolchain` and `--profile` rather than silently
99
- creating a different compile domain. So it is not the tool for *executing*
100
- binaries built for another platform. For that, build a nextest archive on the
101
- cross-build lane and replay it on the target:
98
+ **Know the execution boundary.** `ci-test --target <triple>` runs tests by
99
+ default for the exact host triple. A foreign target without a registered
100
+ executor fails with guidance to pass `--no-run`; it never reports a green
101
+ build-only result as a test pass. `--no-run` runs the compile-side checks and
102
+ writes a Nextest archive at the printed path (also in the JSON plan). Replay
103
+ that archive on the target:
102
104
 
103
105
  ```bash
104
- soldr cargo nextest archive --target <triple> --archive-file tests.tar.zst
106
+ soldr ci-test --no-run --target <triple>
105
107
  # then, on (or emulating) the target:
106
- cargo-nextest nextest run --archive-file tests.tar.zst --workspace-remap <checkout>
108
+ cargo-nextest nextest run --archive-file <printed-path> --workspace-remap <checkout>
107
109
  ```
108
110
 
109
111
  Two things bite consumers here, both observed rather than hypothesised:
@@ -115,8 +117,7 @@ Two things bite consumers here, both observed rather than hypothesised:
115
117
  workspace root. Without it: `error: workspace root manifest at ... does not
116
118
  exist`. `--workspace-remap` must point at a real checkout.
117
119
 
118
- A blessed `--execution container` mode that does all of this for you is proposed
119
- in soldr#3084.
120
+ Automatic foreign-target executors are tracked in soldr#3294.
120
121
 
121
122
  And a caution soldr learned the hard way (soldr#2945): **a green CI lane only
122
123
  proves the verb CI runs.** When a tool has more than one entry point, check that
@@ -230,7 +231,7 @@ Two equivalent ways to declare a cross target: declaratively via `rust-toolchain
230
231
  ```toml
231
232
  # rust-toolchain.toml — declarative (preferred)
232
233
  [toolchain]
233
- channel = "1.95.0"
234
+ channel = "1.98.1"
234
235
  targets = ["aarch64-pc-windows-msvc"]
235
236
  ```
236
237
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zackees/soldr",
3
- "version": "0.9.20",
3
+ "version": "0.9.22",
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",
@@ -43,16 +43,15 @@ const BUNDLED_BINARIES = zccacheContract.RELEASE_BUNDLED_BINARIES;
43
43
  // The lowest glibc a host must have before the `-gnu` artifact is worth
44
44
  // downloading (soldr#1060).
45
45
  //
46
- // Those artifacts are built natively on ubuntu-24.04, so they currently
47
- // require GLIBC_2.39 — measured on the published v0.8.29 binaries, x86_64 and
48
- // aarch64. On Debian 12 (glibc 2.36) the gnu binary dies with
49
- // "version `GLIBC_2.39' not found" while the musl artifact from the same
50
- // release runs fine, so "is this host glibc?" is the wrong question. The
51
- // question is "is this host's glibc new enough for the binary we ship?".
46
+ // This tracks release-auto.yml's BUNDLED-ARCHIVE glibc ceiling
47
+ // (`verify_release_bundle.py --check glibc-baseline`), because the installer
48
+ // downloads the whole archive. soldr's own binaries reach glibc 2.17 through
49
+ // the managed sysroot (soldr#1060, verified in manylinux2014), but the
50
+ // archive also ships prebuilt `crgx` and `cargo-chef` from soldr-toolchain,
51
+ // which measure GLIBC_2.39. Until those are rebuilt against 2.17, a host
52
+ // below 2.39 must get the musl archive, whose tools all run.
52
53
  //
53
- // Kept in lockstep with the `--max-glibc` ceiling in release-auto.yml by a
54
- // check in test-npm-package.js. When the release build is fixed to link
55
- // against a 2.17 baseline that ceiling drops, and this must follow it down.
54
+ // Kept in lockstep with that ceiling by a check in test-npm-package.js.
56
55
  const MIN_GLIBC_FOR_GNU = "2.39";
57
56
 
58
57
  function compareVersions(left, right) {
@@ -139,6 +138,49 @@ function platformTarget(platform = process.platform, arch = process.arch, libc =
139
138
  return target;
140
139
  }
141
140
 
141
+ // The ORDERED list of release artifacts this host may install (soldr#1060).
142
+ //
143
+ // The RFC's policy is "failure -> try the corresponding sibling build", and
144
+ // the honest generalization is "retry the OTHER libc", not "always retry gnu":
145
+ // `detectLibc` already prefers gnu when the host's glibc is at or above
146
+ // MIN_GLIBC_FOR_GNU, so on those hosts the fallback is musl and on every other
147
+ // Linux host it is gnu. Both directions are real: a gnu-preferring host whose
148
+ // -gnu artifact is missing from a release still has a musl artifact that runs
149
+ // there, and a musl-preferring host whose musl artifact 404s can still try gnu.
150
+ //
151
+ // Non-Linux platforms are single-candidate: there is no sibling libc to fall
152
+ // back to, and silently installing a different macOS/Windows triple would be
153
+ // wrong rather than merely slower.
154
+ function platformCandidates(platform = process.platform, arch = process.arch, libc = detectLibc(platform)) {
155
+ // Resolve the preferred artifact through `platformTarget` rather than
156
+ // rebuilding the key rule here. Two copies of "which artifact does this host
157
+ // want?" are free to disagree silently: a hand-rolled `libc === "gnu" ? ... :
158
+ // "musl"` would quietly answer musl for an unrecognised libc string that
159
+ // `platformTarget` treats as a hard error, so the two entry points would
160
+ // return different things for the same input. One implementation, one answer
161
+ // -- including the unsupported-platform throw.
162
+ const primary = platformTarget(platform, arch, libc);
163
+ if (platform !== "linux") {
164
+ return [primary];
165
+ }
166
+ // Read the preferred libc back off the RESOLVED triple instead of off the
167
+ // `libc` argument: platformTarget has already applied its own
168
+ // `libc || "musl"` default, and re-deriving it is exactly where a second
169
+ // copy would drift from the first.
170
+ const sibling = primary.triple.endsWith("-gnu") ? "musl" : "gnu";
171
+ const candidates = [primary];
172
+ try {
173
+ const fallback = platformTarget(platform, arch, sibling);
174
+ if (fallback.triple !== primary.triple) {
175
+ candidates.push(fallback);
176
+ }
177
+ } catch (err) {
178
+ // A future arch published for only one libc (the RFC's deferred armv7 is
179
+ // musl-only) has no sibling. One candidate is correct there, not an error.
180
+ }
181
+ return candidates;
182
+ }
183
+
142
184
  function releaseBaseUrl(version) {
143
185
  const override = process.env.SOLDR_NPM_RELEASE_BASE_URL;
144
186
  if (override) {
@@ -277,16 +319,17 @@ function findExtractedBinary(root, binaryName) {
277
319
  return null;
278
320
  }
279
321
 
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();
322
+ // Download, verify, and install one candidate target's release archive into
323
+ // bin/native/. Extracted from install() (soldr#1060) so a retry loop can call
324
+ // it once per candidate.
325
+ //
326
+ // A failed candidate must not leave bin/native/ half-populated for the next
327
+ // one, so every source path is resolved and validated first: manifest
328
+ // location + parse + validateReleaseManifest, then every findExtractedBinary
329
+ // lookup for BUNDLED_BINARIES and soldrDebugInfoEntries. Only once every
330
+ // source is known-present does bin/native/ get cleared and repopulated.
331
+ async function installRelease(target, version, baseUrl) {
288
332
  const filename = `soldr-v${version}-${target.triple}.${ARCHIVE_EXT}`;
289
- const baseUrl = releaseBaseUrl(version);
290
333
  const archiveUrl = `${baseUrl}/${filename}`;
291
334
  const checksumUrl = `${baseUrl}/soldr-v${version}-SHA256SUMS.txt`;
292
335
  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "soldr-npm-"));
@@ -307,14 +350,12 @@ async function install() {
307
350
  extractArchive(archivePath, extractDir);
308
351
 
309
352
  const nativeDir = path.join(PACKAGE_ROOT, "bin", "native");
310
- fs.rmSync(nativeDir, { recursive: true, force: true });
311
- fs.mkdirSync(nativeDir, { recursive: true });
312
353
 
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.
354
+ // Resolve every source before touching bin/native/. `bin/soldr.js`
355
+ // wires SOLDR_CRGX_LOCAL_DIR / SOLDR_CARGO_CHEF_LOCAL_DIR to this dir,
356
+ // so soldr has its daemon and can find crgx / cargo-chef once this
357
+ // completes. The archive layout is flat: all bundled binaries live at
358
+ // the archive root.
318
359
  const binaryExt = target.binary.endsWith(".exe") ? ".exe" : "";
319
360
  const manifestSrc = findExtractedBinary(extractDir, zccacheContract.MANIFEST_NAME);
320
361
  if (!manifestSrc) {
@@ -332,30 +373,41 @@ async function install() {
332
373
  return filePath;
333
374
  },
334
375
  });
376
+
377
+ const copyPlan = [];
335
378
  for (const baseName of BUNDLED_BINARIES) {
336
379
  const fileName = `${baseName}${binaryExt}`;
337
380
  const src = findExtractedBinary(extractDir, fileName);
338
381
  if (!src) {
339
382
  throw new Error(`release archive ${filename} did not contain ${fileName}`);
340
383
  }
341
- const dst = path.join(nativeDir, fileName);
342
- fs.copyFileSync(src, dst);
343
- if (process.platform !== "win32") {
344
- fs.chmodSync(dst, 0o755);
345
- }
384
+ copyPlan.push({ src, dst: path.join(nativeDir, fileName), executable: true });
346
385
  }
347
386
  for (const entry of zccacheContract.soldrDebugInfoEntries(manifest)) {
348
387
  const src = findExtractedBinary(extractDir, entry.name);
349
388
  if (!src) {
350
389
  throw new Error(`release archive ${filename} did not contain ${entry.name}`);
351
390
  }
352
- fs.copyFileSync(src, path.join(nativeDir, entry.name));
391
+ copyPlan.push({ src, dst: path.join(nativeDir, entry.name), executable: false });
353
392
  }
354
-
355
393
  // Drop manifest.json alongside the binaries so downstream tooling
356
394
  // (and humans reading `bin/native/`) can introspect provenance —
357
395
  // soldr / zccache versions, target triples, build commit, sha256s.
358
- fs.copyFileSync(manifestSrc, path.join(nativeDir, zccacheContract.MANIFEST_NAME));
396
+ copyPlan.push({
397
+ src: manifestSrc,
398
+ dst: path.join(nativeDir, zccacheContract.MANIFEST_NAME),
399
+ executable: false,
400
+ });
401
+
402
+ // Every source is known-present now — safe to clear and repopulate.
403
+ fs.rmSync(nativeDir, { recursive: true, force: true });
404
+ fs.mkdirSync(nativeDir, { recursive: true });
405
+ for (const { src, dst, executable } of copyPlan) {
406
+ fs.copyFileSync(src, dst);
407
+ if (executable && process.platform !== "win32") {
408
+ fs.chmodSync(dst, 0o755);
409
+ }
410
+ }
359
411
 
360
412
  console.log(
361
413
  `soldr: installed ${target.triple} (soldr + daemon + crgx + cargo-chef) into ${nativeDir}`,
@@ -365,6 +417,59 @@ async function install() {
365
417
  }
366
418
  }
367
419
 
420
+ // Walk `candidates` in order, returning the first that installs. `attempt` is
421
+ // injected (rather than inlined into install()) so the fallthrough policy can
422
+ // be tested without a network: an untestable retry loop is how "we have a
423
+ // fallback" becomes true in the comments and false in the code.
424
+ async function installFirstWorkingCandidate(candidates, attempt, log = console) {
425
+ if (!Array.isArray(candidates) || candidates.length === 0) {
426
+ // A zero-length list would fall straight through the loop to a rejection
427
+ // whose detail string is empty -- "could not install ()" tells nobody
428
+ // anything. platformCandidates never produces one (it throws instead), so
429
+ // reaching here means the caller built the list some other way.
430
+ throw new Error("no soldr release candidates to install (empty candidate list)");
431
+ }
432
+ const failures = [];
433
+ for (let index = 0; index < candidates.length; index += 1) {
434
+ const target = candidates[index];
435
+ try {
436
+ await attempt(target);
437
+ if (index > 0) {
438
+ log.warn(
439
+ `soldr: installed the sibling libc build ${target.triple} instead of the ` +
440
+ `preferred ${failures[0].target.triple} (${failures.length} candidate(s) failed first)`,
441
+ );
442
+ }
443
+ return target;
444
+ } catch (error) {
445
+ failures.push({ target, error });
446
+ const next = candidates[index + 1];
447
+ if (next) {
448
+ log.warn(
449
+ `soldr: ${target.triple} failed (${error.message}); falling back to the sibling libc build ${next.triple}`,
450
+ );
451
+ }
452
+ }
453
+ }
454
+ const detail = failures
455
+ .map(({ target, error }) => `${target.triple}: ${error.message}`)
456
+ .join("; ");
457
+ throw new Error(`no soldr release artifact could be installed (${detail})`);
458
+ }
459
+
460
+ async function install() {
461
+ if (process.env.SOLDR_NPM_SKIP_DOWNLOAD) {
462
+ console.log("soldr: skipping native binary download because SOLDR_NPM_SKIP_DOWNLOAD is set");
463
+ return;
464
+ }
465
+ const version = PACKAGE_JSON.version;
466
+ const baseUrl = releaseBaseUrl(version);
467
+ const candidates = platformCandidates();
468
+ await installFirstWorkingCandidate(candidates, (target) =>
469
+ installRelease(target, version, baseUrl),
470
+ );
471
+ }
472
+
368
473
  if (require.main === module) {
369
474
  install().catch((error) => {
370
475
  console.error(`soldr: npm install failed: ${error.message}`);
@@ -382,5 +487,7 @@ module.exports = {
382
487
  verifyArchiveChecksum,
383
488
  detectLibc,
384
489
  platformTarget,
490
+ platformCandidates,
491
+ installFirstWorkingCandidate,
385
492
  releaseBaseUrl,
386
493
  };
@@ -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);
@@ -146,12 +231,15 @@ assert.strictEqual(
146
231
  );
147
232
 
148
233
  // 2. A glibc that is too old must NOT take the gnu build. This is the live
149
- // bug: Debian 12 reports 2.36, the published gnu binary requires
150
- // GLIBC_2.39, and it dies with "version `GLIBC_2.39' not found" while the
151
- // musl artifact from the same release runs fine.
234
+ // bug soldr#1060 exists to prevent: a host whose glibc is below what the
235
+ // published gnu binary actually requires must not be sent to it, or it
236
+ // dies with "version `GLIBC_2.xx' not found" while the musl artifact
237
+ // from the same release runs fine. RHEL 7 / CentOS 7 (glibc 2.17,
238
+ // exactly the shipped floor) is the boundary case; one below it is
239
+ // unambiguously too old regardless of where the floor currently sits.
152
240
  assert.strictEqual(
153
241
  install.detectLibc("linux", {
154
- readHeader: () => ({ glibcVersionRuntime: "2.36" }),
242
+ readHeader: () => ({ glibcVersionRuntime: "2.12" }),
155
243
  listLib: () => ["ld-linux-x86-64.so.2", "libc.so.6"],
156
244
  }),
157
245
  "musl",
@@ -203,10 +291,78 @@ assert.strictEqual(
203
291
  null,
204
292
  );
205
293
 
294
+ // g. Candidate ordering driven end to end from the HOST's glibc rather than
295
+ // from a literal libc string. The RFC states its cases as "new glibc" /
296
+ // "old glibc", and `libc` is only detectLibc's answer to that question --
297
+ // asserting the order for the string "gnu" proves the ordering helper
298
+ // works, not that a new-glibc host reaches it. Composing the two is what
299
+ // covers the path install() actually walks.
300
+ {
301
+ // One step below the shipped floor, derived rather than hardcoded. A
302
+ // literal "2.36" here would stop testing the too-old branch the day
303
+ // MIN_GLIBC_FOR_GNU drops to 2.17 -- it would silently become a
304
+ // new-ENOUGH version and this case would assert the opposite of its name.
305
+ const floorParts = install.MIN_GLIBC_FOR_GNU.split(".").map((p) => parseInt(p, 10) || 0);
306
+ floorParts[floorParts.length - 1] -= 1;
307
+ const TOO_OLD = floorParts.join(".");
308
+ assert.strictEqual(
309
+ install.compareVersions(TOO_OLD, install.MIN_GLIBC_FOR_GNU),
310
+ -1,
311
+ `derived too-old glibc ${TOO_OLD} must sort below ${install.MIN_GLIBC_FOR_GNU}`,
312
+ );
313
+
314
+ const GLIBC_LIB = ["ld-linux-x86-64.so.2", "libc.so.6"];
315
+ const candidatesForHost = (probes) =>
316
+ triples(install.platformCandidates("linux", "x64", install.detectLibc("linux", probes)));
317
+
318
+ // New-enough glibc -> gnu first, musl second as the sibling fallback.
319
+ assert.deepStrictEqual(
320
+ candidatesForHost({
321
+ readHeader: () => ({ glibcVersionRuntime: NEW_ENOUGH }),
322
+ listLib: () => GLIBC_LIB,
323
+ }),
324
+ ["x86_64-unknown-linux-gnu", "x86_64-unknown-linux-musl"],
325
+ );
326
+ // Too-old glibc (the Debian 12 case that motivated soldr#1060) -> musl
327
+ // first, because gnu would not even load, but gnu is still listed second
328
+ // so a missing/broken musl asset is recoverable without a second install.
329
+ assert.deepStrictEqual(
330
+ candidatesForHost({
331
+ readHeader: () => ({ glibcVersionRuntime: TOO_OLD }),
332
+ listLib: () => GLIBC_LIB,
333
+ }),
334
+ ["x86_64-unknown-linux-musl", "x86_64-unknown-linux-gnu"],
335
+ );
336
+ // A musl SYSTEM reaches the same order through the /lib probe.
337
+ assert.deepStrictEqual(
338
+ candidatesForHost({ readHeader: () => ({}), listLib: () => ["ld-musl-x86_64.so.1"] }),
339
+ ["x86_64-unknown-linux-musl", "x86_64-unknown-linux-gnu"],
340
+ );
341
+ // Both probes dead -> still musl-first, never an empty or single list that
342
+ // would quietly drop the fallback on exactly the hosts that need it most.
343
+ assert.deepStrictEqual(
344
+ candidatesForHost({ readHeader: throwingProbe, listLib: throwingProbe }),
345
+ ["x86_64-unknown-linux-musl", "x86_64-unknown-linux-gnu"],
346
+ );
347
+ }
348
+
349
+ // h. The zero-argument shape install() itself calls: on this host the first
350
+ // candidate must still be exactly what platformTarget picks today. The
351
+ // retry may add a fallback; it may not change which artifact is preferred.
352
+ {
353
+ const hostCandidates = install.platformCandidates();
354
+ assert.deepStrictEqual(hostCandidates[0], install.platformTarget());
355
+ assert.strictEqual(
356
+ hostCandidates.length,
357
+ process.platform === "linux" ? 2 : 1,
358
+ `platformCandidates() length on ${process.platform}: ${triples(hostCandidates).join(", ")}`,
359
+ );
360
+ }
361
+
206
362
  // MIN_GLIBC_FOR_GNU must track the ceiling release-auto.yml enforces on the
207
- // gnu BINARIES. If the release build is fixed to link a 2.17 baseline and that
208
- // ceiling drops, the installer must follow it down -- otherwise every glibc
209
- // host below 2.39 keeps being sent to musl long after gnu would work.
363
+ // gnu ARCHIVE (see the lockstep assertion below). When that ceiling drops,
364
+ // the installer must follow it down -- otherwise glibc hosts keep being sent
365
+ // to musl long after gnu would work -- and it must never go below it.
210
366
  //
211
367
  // Anchored on the script name rather than on any `--max-glibc`. release-auto
212
368
  // now passes that flag twice: 2.39 to verify_glibc_baseline.py for the
@@ -295,17 +451,23 @@ const releaseWorkflow = fs.readFileSync(
295
451
  path.join(root, ".github", "workflows", "release-auto.yml"),
296
452
  "utf8",
297
453
  );
298
- const binaryCeiling = glibcCeilingFor(releaseWorkflow, "verify_glibc_baseline.py");
454
+ // The installer downloads the whole -gnu ARCHIVE, not just soldr's own
455
+ // binary, so its floor must be the ceiling release-auto.yml enforces on the
456
+ // bundle (`verify_release_bundle.py --check glibc-baseline`), which also
457
+ // covers the prebuilt `crgx` / `cargo-chef` fetched from soldr-toolchain.
458
+ // Tracking the own-binary ceiling instead (2.17 since soldr#1060) would send
459
+ // glibc 2.17-2.38 hosts an archive whose bundled tools need 2.39.
460
+ const bundleCeiling = glibcCeilingFor(releaseWorkflow, "--check glibc-baseline");
299
461
  assert(
300
- binaryCeiling,
301
- "release-auto.yml must pass --max-glibc to verify_glibc_baseline.py",
462
+ bundleCeiling,
463
+ "release-auto.yml must pass --max-glibc to the bundled glibc-baseline check",
302
464
  );
303
465
  assert.strictEqual(
304
466
  install.MIN_GLIBC_FOR_GNU,
305
- binaryCeiling,
467
+ bundleCeiling,
306
468
  `install.js MIN_GLIBC_FOR_GNU (${install.MIN_GLIBC_FOR_GNU}) must match the ` +
307
- `--max-glibc ceiling verify_glibc_baseline.py enforces in release-auto.yml ` +
308
- `(${binaryCeiling})`,
469
+ `--max-glibc ceiling release-auto.yml enforces on the bundled -gnu archive ` +
470
+ `(${bundleCeiling})`,
309
471
  );
310
472
 
311
473
  assert.strictEqual(
@@ -453,4 +615,175 @@ for (const required of [
453
615
  );
454
616
  }
455
617
 
456
- console.log("npm package and PyPI version checks passed");
618
+ // installFirstWorkingCandidate's retry policy: it must try candidates in
619
+ // order, stay quiet on the common case, and when it does fall back, the log
620
+ // has to say which artifact failed, why, and which one was installed
621
+ // instead -- otherwise a user staring at a successful install with the
622
+ // "wrong" binary has no way to find out why.
623
+ async function checkCandidateFallback() {
624
+ const gnu = { triple: "x86_64-unknown-linux-gnu", binary: "soldr" };
625
+ const musl = { triple: "x86_64-unknown-linux-musl", binary: "soldr" };
626
+ const collector = () => {
627
+ const lines = [];
628
+ return { lines, warn: (line) => lines.push(line) };
629
+ };
630
+
631
+ // 1. First candidate succeeds -> it is returned, attempt ran exactly once,
632
+ // and nothing is logged. A normal install must stay quiet; logging a
633
+ // "warning" on the success path would train users to ignore warnings.
634
+ {
635
+ const log = collector();
636
+ const attempts = [];
637
+ const result = await install.installFirstWorkingCandidate(
638
+ [gnu, musl],
639
+ async (target) => {
640
+ attempts.push(target.triple);
641
+ return target;
642
+ },
643
+ log,
644
+ );
645
+ assert.deepStrictEqual(result, gnu);
646
+ assert.deepStrictEqual(attempts, [gnu.triple]);
647
+ assert.deepStrictEqual(log.lines, []);
648
+ }
649
+
650
+ // 2. First candidate fails, sibling succeeds -> resolves with the sibling,
651
+ // attempts happened in order (gnu before musl -- it must not try the
652
+ // sibling first), and the log names both the failed triple and its
653
+ // reason, plus a line reporting the sibling that was actually
654
+ // installed. This is the RFC's whole point: the log must say what
655
+ // happened and why.
656
+ {
657
+ const log = collector();
658
+ const attempts = [];
659
+ const result = await install.installFirstWorkingCandidate(
660
+ [gnu, musl],
661
+ async (target) => {
662
+ attempts.push(target.triple);
663
+ if (target.triple === gnu.triple) {
664
+ throw new Error("HTTP 404");
665
+ }
666
+ return target;
667
+ },
668
+ log,
669
+ );
670
+ assert.deepStrictEqual(result, musl);
671
+ assert.deepStrictEqual(attempts, [gnu.triple, musl.triple]);
672
+ assert.ok(
673
+ log.lines.some((l) => l.includes("x86_64-unknown-linux-gnu") && l.includes("HTTP 404")),
674
+ "fallthrough must log the failed triple and the reason",
675
+ );
676
+ // Must be a line that says something was INSTALLED, naming both what was
677
+ // installed and what was preferred. Matching the musl triple alone is not
678
+ // enough: the fallthrough warning already names it, so that weaker check
679
+ // would still pass if the success line were deleted entirely.
680
+ assert.ok(
681
+ log.lines.some(
682
+ (l) =>
683
+ l.includes("installed") &&
684
+ l.includes("x86_64-unknown-linux-musl") &&
685
+ l.includes("x86_64-unknown-linux-gnu"),
686
+ ),
687
+ `a non-first success must log what was installed and what was preferred: ${log.lines.join(" | ")}`,
688
+ );
689
+ }
690
+
691
+ // 3. Both candidates fail -> the promise rejects, and the rejection names
692
+ // every triple and every reason. A fallback that swallows the original
693
+ // error on the way to the final rejection makes the failure
694
+ // unreportable -- exactly the failure mode this feature exists to fix.
695
+ {
696
+ const log = collector();
697
+ const promise = install.installFirstWorkingCandidate(
698
+ [gnu, musl],
699
+ async (target) => {
700
+ if (target.triple === gnu.triple) {
701
+ throw new Error("HTTP 404");
702
+ }
703
+ throw new Error("checksum mismatch");
704
+ },
705
+ log,
706
+ );
707
+ await assert.rejects(promise, /no soldr release artifact could be installed/);
708
+ await assert.rejects(
709
+ promise,
710
+ (err) =>
711
+ err.message.includes("x86_64-unknown-linux-gnu") &&
712
+ err.message.includes("x86_64-unknown-linux-musl") &&
713
+ err.message.includes("HTTP 404") &&
714
+ err.message.includes("checksum mismatch"),
715
+ );
716
+ // Exactly one log line: the gnu -> musl fallthrough. Nothing may claim an
717
+ // install happened when every candidate failed.
718
+ assert.strictEqual(log.lines.length, 1, `unexpected log lines: ${log.lines.join(" | ")}`);
719
+ assert.ok(
720
+ !log.lines.some((l) => l.includes("installed")),
721
+ "an all-candidates-failed run must not log that anything was installed",
722
+ );
723
+ }
724
+
725
+ // 4. Single-candidate (the non-Linux shape) failure -> rejects, attempted
726
+ // exactly once, and nothing is logged. There is no sibling to fall back
727
+ // to, so nothing may claim a fallback happened.
728
+ {
729
+ const log = collector();
730
+ const attempts = [];
731
+ const promise = install.installFirstWorkingCandidate(
732
+ [{ triple: "aarch64-apple-darwin", binary: "soldr" }],
733
+ async (target) => {
734
+ attempts.push(target.triple);
735
+ throw new Error("HTTP 404");
736
+ },
737
+ log,
738
+ );
739
+ await assert.rejects(promise, /no soldr release artifact could be installed/);
740
+ assert.strictEqual(attempts.length, 1);
741
+ assert.deepStrictEqual(log.lines, []);
742
+ }
743
+
744
+ // 4b. An empty candidate list is rejected with a message that says so,
745
+ // rather than falling through the loop to "could not be installed ()"
746
+ // with an empty reason list. platformCandidates throws instead of
747
+ // returning one, so this only fires for a hand-built list.
748
+ {
749
+ const log = collector();
750
+ let attempted = false;
751
+ await assert.rejects(
752
+ install.installFirstWorkingCandidate([], async () => {
753
+ attempted = true;
754
+ }, log),
755
+ /empty candidate list/,
756
+ );
757
+ assert.strictEqual(attempted, false);
758
+ assert.deepStrictEqual(log.lines, []);
759
+ }
760
+
761
+ // 5. Real-shape wiring: platformCandidates feeding straight into
762
+ // installFirstWorkingCandidate resolves with the sibling when the
763
+ // preferred triple fails, proving the ordering helper and the retry
764
+ // loop compose the way install() actually uses them.
765
+ {
766
+ const log = collector();
767
+ const candidates = install.platformCandidates("linux", "x64", "musl");
768
+ const result = await install.installFirstWorkingCandidate(
769
+ candidates,
770
+ async (target) => {
771
+ if (target.triple === "x86_64-unknown-linux-musl") {
772
+ throw new Error("HTTP 404");
773
+ }
774
+ return target;
775
+ },
776
+ log,
777
+ );
778
+ assert.strictEqual(result.triple, "x86_64-unknown-linux-gnu");
779
+ }
780
+ }
781
+
782
+ checkCandidateFallback()
783
+ .then(() => {
784
+ console.log("npm package and PyPI version checks passed");
785
+ })
786
+ .catch((error) => {
787
+ console.error(error && error.stack ? error.stack : error);
788
+ process.exit(1);
789
+ });