@inventarch/cli 3.7.0 → 3.8.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.
Files changed (82) hide show
  1. package/README.md +5 -2
  2. package/SPEC.md +6 -6
  3. package/assets/base/08eaab3e1a6215d78283b82a94a0228367ac7bd78d0a746c56db79c8d7546c3a.ia.tgz +0 -0
  4. package/assets/base/3ada760ec07848770957538a8562ec94c6f3a9ceb6f1e29d2739b217f9234728.ia.tgz +0 -0
  5. package/assets/base/62ecd5092f364b40e335e9e509ef512ac8030eb5689e72a5d0ff1e073cb13cfb.ia.tgz +0 -0
  6. package/assets/base/7b36e4b4959a7bead1c57906cd346b419f32570dac0ac764af805ad20cd63b16.ia.tgz +0 -0
  7. package/assets/base/7db20e0dbbc2b88701ea24991886b4a8e08d419dda469cce5caff66911f81e4c.ia.tgz +0 -0
  8. package/assets/base/969a1cf9091534f9194c8584c0e45c92449f2e24849db1431841ef73df52b888.ia.tgz +0 -0
  9. package/assets/base/df626d1dc4949649ba7203842b29b4f064e0552e8db8c2c41ff74b6462b81b75.ia.tgz +0 -0
  10. package/assets/base.json +3 -3
  11. package/assets/bases.json +50 -0
  12. package/assets/host/7d452748b9a79528d227b1c3374977cc713d5d9b5d3b81069cd9f01c47e825f1.tgz +0 -0
  13. package/assets/host.json +4 -4
  14. package/assets/language-compat.json +1 -0
  15. package/assets/vocabulary.json +3 -3
  16. package/dist/bundled-base.d.ts +13 -0
  17. package/dist/bundled-base.d.ts.map +1 -1
  18. package/dist/bundled-base.js +68 -19
  19. package/dist/bundled-base.js.map +1 -1
  20. package/dist/commands.d.ts.map +1 -1
  21. package/dist/commands.js +14 -1
  22. package/dist/commands.js.map +1 -1
  23. package/dist/console/batch-next.d.ts +2 -0
  24. package/dist/console/batch-next.d.ts.map +1 -1
  25. package/dist/console/batch-next.js +1 -1
  26. package/dist/console/batch-next.js.map +1 -1
  27. package/dist/console/batch-run.d.ts.map +1 -1
  28. package/dist/console/batch-run.js +3 -4
  29. package/dist/console/batch-run.js.map +1 -1
  30. package/dist/console/batch-screen.d.ts +1 -1
  31. package/dist/console/batch-screen.d.ts.map +1 -1
  32. package/dist/console/batch-screen.js +7 -4
  33. package/dist/console/batch-screen.js.map +1 -1
  34. package/dist/console/run.d.ts.map +1 -1
  35. package/dist/console/run.js +5 -2
  36. package/dist/console/run.js.map +1 -1
  37. package/dist/consumer.d.ts.map +1 -1
  38. package/dist/consumer.js +2 -0
  39. package/dist/consumer.js.map +1 -1
  40. package/dist/distribute.d.ts +5 -0
  41. package/dist/distribute.d.ts.map +1 -1
  42. package/dist/distribute.js +267 -56
  43. package/dist/distribute.js.map +1 -1
  44. package/dist/floor.d.ts +49 -0
  45. package/dist/floor.d.ts.map +1 -0
  46. package/dist/floor.js +315 -0
  47. package/dist/floor.js.map +1 -0
  48. package/dist/format.d.ts.map +1 -1
  49. package/dist/format.js +10 -3
  50. package/dist/format.js.map +1 -1
  51. package/dist/handoff.d.ts +3 -2
  52. package/dist/handoff.d.ts.map +1 -1
  53. package/dist/handoff.js +5 -2
  54. package/dist/handoff.js.map +1 -1
  55. package/dist/init.d.ts +1 -1
  56. package/dist/init.d.ts.map +1 -1
  57. package/dist/init.js +1 -1
  58. package/dist/init.js.map +1 -1
  59. package/dist/main.d.ts +3 -2
  60. package/dist/main.d.ts.map +1 -1
  61. package/dist/main.js +9 -3
  62. package/dist/main.js.map +1 -1
  63. package/dist/pack.d.ts +8 -0
  64. package/dist/pack.d.ts.map +1 -1
  65. package/dist/pack.js +20 -5
  66. package/dist/pack.js.map +1 -1
  67. package/dist/package-manager.d.ts +3 -1
  68. package/dist/package-manager.d.ts.map +1 -1
  69. package/dist/package-manager.js +8 -2
  70. package/dist/package-manager.js.map +1 -1
  71. package/dist/position.d.ts.map +1 -1
  72. package/dist/position.js +11 -1
  73. package/dist/position.js.map +1 -1
  74. package/dist/record-sources.d.ts +13 -0
  75. package/dist/record-sources.d.ts.map +1 -0
  76. package/dist/record-sources.js +44 -0
  77. package/dist/record-sources.js.map +1 -0
  78. package/dist/tracked.d.ts.map +1 -1
  79. package/dist/tracked.js +3 -8
  80. package/dist/tracked.js.map +1 -1
  81. package/package.json +7 -7
  82. package/assets/host/e373b0f6699516f2ab8794f966728d2f82bca05ba3199c9fc642437cb79b13d5.tgz +0 -0
@@ -39,9 +39,12 @@
39
39
  * with the service's code, message and file, and its next action opens "The installation is applied." before the
40
40
  * repair, so a script sees the failure and a reader sees what did happen. `ia doctor` reports the drift until then.
41
41
  */
42
- import { readBase } from './bundled-base.js';
43
- import { canonicalDistributionJson, decodeDistributionRequests, DISTRIBUTION_ENGINE_VERSION, INSTALL_PATHS, lockedReleases, } from '@inventarch/db/distribution';
44
- import { ARCHIVE_CACHE, applyInstallation, cacheArchive, collectionsWouldChange, planInstallation, } from '@inventarch/distribution/install';
42
+ import { existsSync } from 'node:fs';
43
+ import { join } from 'node:path';
44
+ import { readBases, readCompatIndex } from './bundled-base.js';
45
+ import { gapText, recordSources } from './record-sources.js';
46
+ import { canonicalDistributionJson, commonRange, compareVersions, decodeDistributionRequests, DISTRIBUTION_ENGINE_VERSION, INSTALL_PATHS, languageFloor, lockedReleases, satisfies, usageOf, version as exactVersion, } from '@inventarch/db/distribution';
47
+ import { ARCHIVE_CACHE, applyInstallation, cacheArchive, cachePath, collectionsWouldChange, planInstallation, } from '@inventarch/distribution/install';
45
48
  import { intactCollections, KIT_COLLECTIONS } from '@inventarch/distribution/kit-collections';
46
49
  import { legacyProjectionActions, observeProjection } from '@inventarch/distribution/projection';
47
50
  import { PACKET_MARKER } from '@inventarch/runtime';
@@ -331,17 +334,177 @@ function refreshed(view, host) {
331
334
  * (apps/distribution/src/install.ts `planInstallation`). Every other operation, and every other state, still refuses.
332
335
  */
333
336
  const RESTORABLE = new Set(['restore-required', 'lock-drift']);
334
- function installedLock(root, operation) {
337
+ /**
338
+ * `update` of the language base is let through those two states as well (`moving`): a fresh clone locked on one base
339
+ * moves to another without a restore first. Its previous state is then the committed lock, and the move is planned as a
340
+ * restore of the new lock, the one operation the installer plans over a partial installation; `partial` says so.
341
+ */
342
+ function installedLock(root, operation, moving) {
335
343
  try {
336
- return readInstalledState({ root }).lock;
344
+ return { previous: readInstalledState({ root }).lock, partial: false };
337
345
  }
338
346
  catch (error) {
339
347
  const reason = error !== null && typeof error === 'object' && 'reason' in error ? error.reason : undefined;
340
- if (operation === 'restore' && typeof reason === 'string' && RESTORABLE.has(reason))
341
- return undefined;
348
+ if (typeof reason === 'string' && RESTORABLE.has(reason)) {
349
+ if (operation === 'restore')
350
+ return { previous: undefined, partial: true };
351
+ if (moving)
352
+ return { previous: readWorkspaceLock({ root }), partial: true };
353
+ }
342
354
  throw error;
343
355
  }
344
356
  }
357
+ /**
358
+ * The language bases this CLI carries (`readBases`, ascending): none for a caller that names no package root (a 1.x
359
+ * `collectPlan` request), and none for a workspace with no committed lock, which locks no base to move from or restore.
360
+ */
361
+ function carriedBases(request) {
362
+ if (request.packageRoot === undefined || !existsSync(join(request.root, INSTALL_PATHS.lock)))
363
+ return [];
364
+ return readBases(request.packageRoot);
365
+ }
366
+ /** The value, or undefined when the codec refuses it (not canonical SemVer, not a range). */
367
+ function attempt(run) {
368
+ try {
369
+ return run();
370
+ }
371
+ catch {
372
+ return undefined;
373
+ }
374
+ }
375
+ const majorOf = (value) => Number(value.split('.')[0]);
376
+ /** Whether version `a` is at or above `b` (`compareVersions` orders the highest first). */
377
+ const atLeast = (a, b) => compareVersions(a, b) <= 0;
378
+ function carriedOffer(root, packageRoot, bases, lock, requests, naming) {
379
+ const newest = bases.at(-1);
380
+ if (newest === undefined || packageRoot === undefined)
381
+ return undefined;
382
+ const id = newest.pin.id, row = lock?.packages.find((pkg) => pkg.id === id);
383
+ if (row === undefined)
384
+ return undefined;
385
+ // Identity is the archive: a carried archive is the version it carries, whatever the row's label says.
386
+ const at = bases.find((base) => base.pin.archive === row.archive)?.pin.version ?? attempt(() => exactVersion(row.version));
387
+ const range = requests.find((request) => request.id === id)?.range ?? `^${at ?? row.version}`;
388
+ const eligible = at === undefined || majorOf(at) !== majorOf(newest.pin.version)
389
+ ? []
390
+ : bases.filter((base) => majorOf(base.pin.version) === majorOf(at) &&
391
+ atLeast(base.pin.version, at) &&
392
+ attempt(() => satisfies(base.pin.version, range)) === true);
393
+ let minimum;
394
+ if (naming || eligible.some((base) => base.pin.archive !== row.archive)) {
395
+ const { floor, gaps } = languageFloor(usageOf(recordSources(root)), readCompatIndex(packageRoot));
396
+ minimum = { floor, gap: gaps[0] };
397
+ }
398
+ const offered = eligible.filter((base) => base.pin.archive === row.archive ||
399
+ (minimum !== undefined && minimum.floor !== null && atLeast(base.pin.version, minimum.floor)));
400
+ return { id, locked: { version: at ?? row.version, archive: row.archive }, range, offered, eligible, minimum };
401
+ }
402
+ /**
403
+ * `update` of the base refuses before resolving when the workspace's records need a base above every candidate the
404
+ * CLI carries for it: none reads them at all, or none at or above their minimum is within the range and not below the
405
+ * lock. A lock above or outside the carried bases is left to resolution, which a registry may still answer.
406
+ */
407
+ function requireMinimum(offer, newest, reruns, update) {
408
+ const { id, locked, range, eligible, minimum } = offer;
409
+ const carriedMajor = attempt(() => exactVersion(locked.version)) !== undefined && majorOf(locked.version) === majorOf(newest);
410
+ if (minimum === undefined || !carriedMajor || !atLeast(newest, locked.version))
411
+ return;
412
+ const { floor, gap } = minimum;
413
+ const why = gap === undefined ? '' : `: ${gapText(gap)}`;
414
+ if (floor === null)
415
+ throw new Refusal('IA-DIST-CONFLICT', `No ${id} base this CLI carries reads the workspace's records${why}`, 3, gap === undefined ? null : { path: gap.source }, `Fix the record the message names, then run "${reruns.again}".`);
416
+ if (eligible.some((base) => atLeast(base.pin.version, floor)))
417
+ return;
418
+ const lowest = atLeast(floor, locked.version) ? floor : locked.version;
419
+ throw new Refusal('IA-DIST-CONFLICT', `The workspace's records need ${id} ${floor} or later${why}; no base this CLI carries (up to ${newest}) at or above ${lowest} satisfies ${range}`, 3, null, `Run "${update(`^${lowest}`)}" to move the workspace to a base its records can use.`);
420
+ }
421
+ /**
422
+ * `update` of the base with `--to` never plans a downgrade: a range that admits no version at or above the locked one
423
+ * refuses before anything is resolved, naming the lock. A range the codec refuses is left to resolution.
424
+ */
425
+ function requireNoDowngrade(offer, to, update) {
426
+ const locked = attempt(() => exactVersion(offer.locked.version));
427
+ if (locked === undefined || attempt(() => commonRange(to, `>=${locked}`)) !== null)
428
+ return;
429
+ throw new Refusal('IA-DIST-CONFLICT', `The range ${to} admits only ${offer.id} versions below the locked ${offer.id} ${locked}, and update never moves the base down`, 3, { path: INSTALL_PATHS.lock }, `Run "${update(`^${locked}`)}" to update within the versions at or above the lock.`);
430
+ }
431
+ function languageBound(offer, reruns) {
432
+ if (offer === undefined)
433
+ return undefined;
434
+ const locked = attempt(() => exactVersion(offer.locked.version));
435
+ if (locked === undefined)
436
+ return undefined;
437
+ const floor = offer.minimum?.floor ?? null, refused = new Set();
438
+ const admits = ({ id, version, archive }) => {
439
+ if (id !== offer.id || archive === offer.locked.archive)
440
+ return true;
441
+ const admitted = attempt(() => atLeast(version, locked) && (floor === null || atLeast(version, floor))) === true;
442
+ if (!admitted)
443
+ refused.add(version);
444
+ return admitted;
445
+ };
446
+ return {
447
+ admits,
448
+ within: (candidates) => candidates.filter(({ release }) => admits({ id: release.manifest.id, version: release.manifest.version, archive: release.archiveDigest })),
449
+ explain: (error) => {
450
+ // Only a search that found no complete set is the bound's doing, and only when its reasons (`<id>: <ranges>`,
451
+ // separated by ` | `) name the language id or name none (a selected base a later range excluded); a conflict
452
+ // the search lays on other ids, or any other conflict, keeps its own message.
453
+ const message = error instanceof Error ? error.message : String(error), search = /^No compatible complete release set: ?(.*)$/s.exec(message);
454
+ const reasons = search?.[1] === undefined || search[1] === '' ? [] : search[1].split(' | ');
455
+ if (refused.size === 0 ||
456
+ codeOf(error, '') !== 'IA-DIST-CONFLICT' ||
457
+ search === null ||
458
+ (reasons.length > 0 && !reasons.some((reason) => reason.startsWith(`${offer.id}: `))))
459
+ return error;
460
+ // The effective bound: the minimum when the records need more than the lock, else the lock.
461
+ const versions = [...refused].sort((a, b) => compareVersions(b, a)), limit = floor !== null && !atLeast(locked, floor)
462
+ ? `the minimum ${floor} the workspace's records need`
463
+ : `the locked ${locked}`;
464
+ return new Refusal('IA-DIST-CONFLICT', `${message}: ${offer.id} ${versions.join(', ')} ${versions.length === 1 ? 'is' : 'are'} below ${limit}, and a plan never moves the base below the lock or that minimum`, 3, { path: INSTALL_PATHS.lock }, `The lock holds ${offer.id} ${locked}. Run "${reruns.inspect}" for the installed generation, and install a release whose range admits it.`);
465
+ },
466
+ };
467
+ }
468
+ /** `run`'s value, or its error as `bound` explains it. */
469
+ async function heldBy(bound, run) {
470
+ try {
471
+ return await run();
472
+ }
473
+ catch (error) {
474
+ throw bound === undefined ? error : bound.explain(error);
475
+ }
476
+ }
477
+ /** The offered bases as resolution candidates beside `candidates`, except one whose id and version they already hold. */
478
+ function carriedCandidates(offer, candidates) {
479
+ const extra = (offer?.offered ?? []).filter((base) => !candidates.some(({ release }) => release.manifest.id === base.pin.id &&
480
+ (release.manifest.version === base.pin.version || release.archiveDigest === base.pin.archive)));
481
+ return [
482
+ ...candidates,
483
+ ...extra.map((base) => ({
484
+ release: { manifest: base.manifest, archiveDigest: base.pin.archive, manifestDigest: base.pin.manifest },
485
+ location: `sha256:${base.pin.archive}`,
486
+ withdrawn: false,
487
+ })),
488
+ ];
489
+ }
490
+ /**
491
+ * Restore stays exact (it never rewrites the lock), so a lock on a base this CLI does not carry, that the workspace
492
+ * cache does not hold and that the source cannot supply, refuses as the service refused it. Its next action is the
493
+ * update that moves the workspace to a carried base, when one can be (same major, not below the lock), and otherwise a
494
+ * CLI that carries the locked base. Any other refusal passes through unchanged.
495
+ */
496
+ function stranded(error, row, newest, reruns, update) {
497
+ const code = codeOf(error, ''), message = error instanceof Error ? error.message : String(error);
498
+ const unavailable = (code === 'IA-DIST-CONFLICT' && message.endsWith(`: ${row.id}@${row.version}`)) ||
499
+ (code === 'IA-DIST-RESTORE-REQUIRED' && (message.includes(row.archive) || message.includes(`locked ${row.id}`)));
500
+ if (!unavailable)
501
+ return error;
502
+ const at = attempt(() => exactVersion(row.version));
503
+ const movable = at !== undefined && majorOf(at) === majorOf(newest) && atLeast(newest, at);
504
+ return new Refusal(code, message, 3, null, movable
505
+ ? `This CLI does not carry ${row.id} ${row.version}, and restore never changes the lock. Run "${update(row.id)}" to preview the move to a base it carries.`
506
+ : `This CLI carries ${row.id} up to ${newest}. Install an @inventarch/cli release that carries ${row.id} ${row.version}, then run "${reruns.again}".`);
507
+ }
345
508
  /**
346
509
  * The `Reruns` of a request that supplies none (a 1.x caller of this published function), spelled from its own fields
347
510
  * as `rerunsOf` spells them from the parsed arguments: `--root` when the request says it was named, the registry
@@ -354,9 +517,10 @@ function requestReruns(request) {
354
517
  const parts = [`ia ${named}`, ...(variant.ids ?? request.ids).map(quote)];
355
518
  if (named === 'install' && request.package !== undefined)
356
519
  parts.push('--package', quote(request.package));
357
- if (named === 'update' && to !== undefined)
358
- parts.push('--to', quote(to));
359
- if (request.requestsFile !== undefined)
520
+ const range = variant.to ?? (operation === 'update' ? to : undefined);
521
+ if (named === 'update' && range !== undefined)
522
+ parts.push('--to', quote(range));
523
+ if (request.requestsFile !== undefined && named !== 'update')
360
524
  parts.push('--requests', quote(request.requestsFile));
361
525
  if (variant.source !== undefined)
362
526
  parts.push(...variant.source);
@@ -366,7 +530,8 @@ function requestReruns(request) {
366
530
  parts.push('--plan-out', quote(request.planOut));
367
531
  if (variant.source === undefined && variant.online !== true && request.offline)
368
532
  parts.push('--offline');
369
- if (request.allowWithdrawn)
533
+ // `update` takes no --allow-withdrawn, so restore's move to a carried base names none.
534
+ if (request.allowWithdrawn && named !== 'update')
370
535
  parts.push('--allow-withdrawn');
371
536
  if (request.rooted === true)
372
537
  parts.push('--root', quote(root));
@@ -381,6 +546,7 @@ function requestReruns(request) {
381
546
  install: spell('install', { ids: request.ids.map((id) => (to === undefined ? id : `${id}@${to}`)) }),
382
547
  inspect: `ia inspect${request.rooted === true ? ` --root ${quote(root)}` : ''}`,
383
548
  together: (extra) => spell('install', { ids: joined(request.ids, extra) }),
549
+ update: (id, range) => spell('update', { ids: [id], ...(range === undefined ? {} : { to: range }) }),
384
550
  };
385
551
  }
386
552
  /**
@@ -430,7 +596,11 @@ export async function collectPlan(request) {
430
596
  throw new Refusal('IA-DIST-INPUT-INVALID', message, 3, null, `Run "${rerun}" naming an existing ${option === 'catalog' ? 'catalog' : 'requests'} file.`);
431
597
  }
432
598
  };
433
- const previous = installedLock(root, operation);
599
+ const bases = operation === 'remove' || request.package !== undefined ? [] : carriedBases(request);
600
+ const newest = bases.at(-1)?.pin;
601
+ // The update of one id from this command's source; a 1.x request's is spelled from its own fields.
602
+ const update = reruns.update ?? requestReruns(request).update;
603
+ const { previous, partial } = installedLock(root, operation, operation === 'update' && newest !== undefined && request.ids[0] === newest.id);
434
604
  let plan;
435
605
  let withdrawn = [];
436
606
  let registries = [];
@@ -450,49 +620,58 @@ export async function collectPlan(request) {
450
620
  offline: request.offline,
451
621
  again: reruns.again,
452
622
  });
453
- if (request.packageRoot !== undefined) {
454
- const base = readBase(request.packageRoot);
455
- const locked = lock.packages.find((row) => row.id === base.pin.id);
456
- if (locked?.archive === base.pin.archive) {
457
- if (locked.manifest !== base.pin.manifest || locked.version !== base.pin.version)
458
- throw new Refusal('IA-DIST-INPUT-INVALID', 'The locked bundled base manifest or version differs from its verified archive', 3, { path: INSTALL_PATHS.lock }, `Restore the exact portable lock from source control, then run "${reruns.again}".`);
459
- cacheArchive(root, base.bytes, base.pin.archive);
460
- }
623
+ // Every published base this CLI carries restores exactly: the locked archive, when carried, is cached from the CLI's
624
+ // own verified bytes, so no registry or catalog has to supply it.
625
+ const locked = newest === undefined ? undefined : lock.packages.find((row) => row.id === newest.id);
626
+ const base = locked === undefined ? undefined : bases.find((carried) => carried.pin.archive === locked.archive);
627
+ if (locked !== undefined && base !== undefined) {
628
+ if (locked.manifest !== base.pin.manifest || locked.version !== base.pin.version)
629
+ throw new Refusal('IA-DIST-INPUT-INVALID', 'The locked bundled base manifest or version differs from its verified archive', 3, { path: INSTALL_PATHS.lock }, `Restore the exact portable lock from source control, then run "${reruns.again}".`);
630
+ cacheArchive(root, base.bytes, base.pin.archive);
461
631
  }
462
- if (request.catalog === undefined && !request.offline) {
463
- const choose = chooserOf(request);
464
- const restored = await acquiring(async () => {
465
- const pins = await registryWithdrawals(root, lock, choose, request.signal);
466
- return planRestore({
632
+ // A locked base the CLI does not carry and the cache does not hold can come only from the source.
633
+ const uncarried = locked !== undefined && base === undefined && !existsSync(join(root, cachePath(locked.archive)))
634
+ ? locked
635
+ : undefined;
636
+ try {
637
+ if (request.catalog === undefined && !request.offline) {
638
+ const choose = chooserOf(request);
639
+ const restored = await acquiring(async () => {
640
+ const pins = await registryWithdrawals(root, lock, choose, request.signal);
641
+ return planRestore({
642
+ root,
643
+ signal: request.signal,
644
+ lock,
645
+ offline: false,
646
+ allowWithdrawn: request.allowWithdrawn,
647
+ withdrawnRefusalPrefix,
648
+ withdrawn: pins,
649
+ });
650
+ }, null, 'registry', reruns);
651
+ plan = restored.plan;
652
+ withdrawn = restored.withdrawn;
653
+ // The registries asked: every locked package's except an unpublished cached pin, which no registry lists (§6.3).
654
+ const unpublished = unpublishedPins(root, lock);
655
+ registries = registrySources(lock.packages.filter((pkg) => !unpublished.has(pkg.id)).map((pkg) => choose(pkg.id)));
656
+ }
657
+ else {
658
+ const entries = request.offline ? undefined : supplied(request.catalog, 'catalog');
659
+ await warm(root, entries, request.offline, reruns, request.signal);
660
+ const restored = await acquiring(() => planRestore({
467
661
  root,
468
662
  signal: request.signal,
469
663
  lock,
470
- offline: false,
664
+ offline: request.offline,
471
665
  allowWithdrawn: request.allowWithdrawn,
472
666
  withdrawnRefusalPrefix,
473
- withdrawn: pins,
474
- });
475
- }, null, 'registry', reruns);
476
- plan = restored.plan;
477
- withdrawn = restored.withdrawn;
478
- // The registries asked: every locked package's except an unpublished cached pin, which no registry lists (§6.3).
479
- const unpublished = unpublishedPins(root, lock);
480
- registries = registrySources(lock.packages.filter((pkg) => !unpublished.has(pkg.id)).map((pkg) => choose(pkg.id)));
667
+ ...(request.offline ? {} : { catalog: entries }),
668
+ }), request.catalog ?? null, 'catalog', reruns);
669
+ plan = restored.plan;
670
+ withdrawn = restored.withdrawn;
671
+ }
481
672
  }
482
- else {
483
- const entries = request.offline ? undefined : supplied(request.catalog, 'catalog');
484
- await warm(root, entries, request.offline, reruns, request.signal);
485
- const restored = await acquiring(() => planRestore({
486
- root,
487
- signal: request.signal,
488
- lock,
489
- offline: request.offline,
490
- allowWithdrawn: request.allowWithdrawn,
491
- withdrawnRefusalPrefix,
492
- ...(request.offline ? {} : { catalog: entries }),
493
- }), request.catalog ?? null, 'catalog', reruns);
494
- plan = restored.plan;
495
- withdrawn = restored.withdrawn;
673
+ catch (error) {
674
+ throw uncarried === undefined ? error : stranded(error, uncarried, newest.version, reruns, update);
496
675
  }
497
676
  }
498
677
  else if (request.package !== undefined) {
@@ -519,14 +698,25 @@ export async function collectPlan(request) {
519
698
  .map((dependency) => dependency.id);
520
699
  // A range the user typed is theirs: an update names one only with --to.
521
700
  direct = updated !== undefined && request.to === undefined ? [] : named;
701
+ // The carried bases this plan may offer beside its source's releases, so a workspace locked on a base moves to a
702
+ // newer carried one when a kit's range or an update of the base asks for it, cold or warm, offline or online.
703
+ const naming = newest !== undefined && updated === newest.id;
704
+ const offer = carriedOffer(root, request.packageRoot, bases, previous, requests, naming);
705
+ if (naming && offer !== undefined && request.to !== undefined)
706
+ requireNoDowngrade(offer, request.to, (to) => update(offer.id, to));
707
+ if (naming && offer !== undefined)
708
+ requireMinimum(offer, newest.version, reruns, (to) => update(offer.id, to));
709
+ // Every source's language candidates are held to the same bound as the carried ones: never below the lock or the
710
+ // workspace's minimum.
711
+ const bound = languageBound(offer, reruns), within = bound?.within ?? ((candidates) => candidates);
522
712
  let choices;
523
713
  if (request.catalog !== undefined) {
524
714
  const entries = supplied(request.catalog, 'catalog');
525
715
  await warm(root, entries, request.offline, reruns, request.signal);
526
- choices = await acquiring(() => resolveCatalog({ root, entries, offline: request.offline, signal: request.signal }), request.catalog, 'catalog', reruns);
716
+ choices = carriedCandidates(offer, within(await acquiring(() => resolveCatalog({ root, entries, offline: request.offline, signal: request.signal }), request.catalog, 'catalog', reruns)));
527
717
  }
528
718
  else if (request.offline) {
529
- choices = cached(root, [...requests.map((dependency) => dependency.id), ...(previous?.packages ?? []).map((pkg) => pkg.id)], reruns);
719
+ choices = carriedCandidates(offer, within(cached(root, [...requests.map((dependency) => dependency.id), ...(previous?.packages ?? []).map((pkg) => pkg.id)], reruns)));
530
720
  }
531
721
  else {
532
722
  // Registry spec §5: metadata selection, then only the selected archives are fetched and verified. Only the ids the
@@ -547,7 +737,7 @@ export async function collectPlan(request) {
547
737
  ...recorded.named,
548
738
  ...(previous?.requests ?? []).map((dependency) => dependency.id).filter((id) => !listed.has(id)),
549
739
  ];
550
- const resolution = await acquiring(() => resolveFromRegistries({
740
+ const resolution = await heldBy(bound, () => acquiring(() => resolveFromRegistries({
551
741
  allowKits: operation === 'install',
552
742
  collectionMembers,
553
743
  direct: earlier,
@@ -559,7 +749,16 @@ export async function collectPlan(request) {
559
749
  named,
560
750
  choose,
561
751
  signal: request.signal,
562
- }), null, 'registry', reruns);
752
+ extra: (offer?.offered ?? []).map((base) => ({
753
+ release: {
754
+ manifest: base.manifest,
755
+ archiveDigest: base.pin.archive,
756
+ manifestDigest: base.pin.manifest,
757
+ },
758
+ bytes: base.bytes,
759
+ })),
760
+ admits: bound?.admits,
761
+ }), null, 'registry', reruns));
563
762
  requests = resolution.expandedRequests ?? requests;
564
763
  // A holder whose shared member this install narrowed still accepts where it lands, so its row is recorded again at
565
764
  // the new pin, with its own version and registry; left alone, the record merge would drop it as re-pinned, and the
@@ -587,7 +786,14 @@ export async function collectPlan(request) {
587
786
  ? { ...previous, packages: previous.packages.filter((pkg) => pkg.id !== updated) }
588
787
  : previous;
589
788
  request.signal?.throwIfAborted();
590
- plan = planInstallation(root, resolveReleases(requests, choices, DISTRIBUTION_ENGINE_VERSION, preference).lock, operation);
789
+ const { lock } = await heldBy(bound, () => resolveReleases(requests, choices, DISTRIBUTION_ENGINE_VERSION, preference));
790
+ // A selected carried base is cached from the CLI's verified bytes, as a selected registry archive is, so the plan
791
+ // reads it where every installation reads its archives.
792
+ const chosen = lock.packages.find((pkg) => pkg.id === offer?.id);
793
+ const carried = offer?.offered.find((base) => base.pin.archive === chosen?.archive);
794
+ if (carried !== undefined)
795
+ cacheArchive(root, carried.bytes, carried.pin.archive);
796
+ plan = planInstallation(root, lock, partial ? 'restore' : operation);
591
797
  }
592
798
  request.signal?.throwIfAborted();
593
799
  const planOut = request.planOut === undefined
@@ -826,11 +1032,14 @@ function invocationOf(context, operation, variant = {}) {
826
1032
  if (given !== undefined)
827
1033
  parts.push(`--${name}`, quote(given));
828
1034
  };
829
- if (operation === 'update')
1035
+ if (operation === 'update' && variant.to !== undefined)
1036
+ parts.push('--to', quote(variant.to));
1037
+ else if (operation === 'update')
830
1038
  value('to');
831
1039
  if (operation === 'install')
832
1040
  value('package');
833
- value('requests');
1041
+ if (operation !== 'update')
1042
+ value('requests');
834
1043
  if (variant.source === undefined) {
835
1044
  value('registry');
836
1045
  value('catalog');
@@ -840,7 +1049,8 @@ function invocationOf(context, operation, variant = {}) {
840
1049
  value('plan-out');
841
1050
  if (variant.source === undefined && variant.online !== true && args.flag('offline'))
842
1051
  parts.push('--offline');
843
- if (args.flag('allow-withdrawn'))
1052
+ // `update` takes no --allow-withdrawn, so restore's move to a carried base names none.
1053
+ if (args.flag('allow-withdrawn') && operation !== 'update')
844
1054
  parts.push('--allow-withdrawn');
845
1055
  value('root');
846
1056
  return parts.join(' ');
@@ -862,6 +1072,7 @@ function rerunsOf(context, operation) {
862
1072
  }),
863
1073
  inspect: `ia inspect${root === undefined ? '' : ` --root ${quote(root)}`}`,
864
1074
  together: (extra) => invocationOf(context, 'install', { ids: joined(args.positionals, extra) }),
1075
+ update: (id, range) => invocationOf(context, 'update', { ids: [id], ...(range === undefined ? {} : { to: range }) }),
865
1076
  };
866
1077
  }
867
1078
  /** The ids a command named, then each of `extra` whose id none of them names (`acme/b` is named by `acme/b@1`). */