@mostra/runtime 0.14.0 → 0.15.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 (61) hide show
  1. package/dist/bin.js +1 -1
  2. package/dist/child-protocol-CPXR6pMu.js +13 -0
  3. package/dist/child-protocol-CPXR6pMu.js.map +1 -0
  4. package/dist/index.d.ts.map +1 -1
  5. package/dist/index.js +1 -1
  6. package/dist/{instance-CFTw3g-c.js → instance-Bw1BxctF.js} +2581 -189
  7. package/dist/instance-Bw1BxctF.js.map +1 -0
  8. package/dist/plugins/child/host.d.ts +1 -0
  9. package/dist/plugins/child/host.js +165 -0
  10. package/dist/plugins/child/host.js.map +1 -0
  11. package/dist/reference/cli.md +147 -5
  12. package/dist/reference/diagnostics.json +234 -0
  13. package/dist/reference/errors/MOSTRA_LICENSE_ACCEPT_INVALID.md +23 -0
  14. package/dist/reference/errors/MOSTRA_LICENSE_MISMATCH.md +23 -0
  15. package/dist/reference/errors/MOSTRA_LICENSE_UNACCEPTED.md +23 -0
  16. package/dist/reference/errors/MOSTRA_LICENSE_UNDECLARED.md +23 -0
  17. package/dist/reference/errors/MOSTRA_PACK_ADDRESS_INVALID.md +23 -0
  18. package/dist/reference/errors/MOSTRA_PACK_CSS_UNIMPORTED.md +23 -0
  19. package/dist/reference/errors/MOSTRA_PACK_FETCH_FAILED.md +23 -0
  20. package/dist/reference/errors/MOSTRA_PACK_FILE_EXISTS.md +23 -0
  21. package/dist/reference/errors/MOSTRA_PACK_ITEM_INVALID.md +23 -0
  22. package/dist/reference/errors/MOSTRA_PACK_ITEM_NOT_FOUND.md +23 -0
  23. package/dist/reference/errors/MOSTRA_PACK_NOT_APPLIED.md +23 -0
  24. package/dist/reference/errors/MOSTRA_PACK_OFFLINE.md +23 -0
  25. package/dist/reference/errors/MOSTRA_PACK_TARGET_INVALID.md +23 -0
  26. package/dist/reference/errors/MOSTRA_PLUGIN_CONFLICT.md +23 -0
  27. package/dist/reference/errors/MOSTRA_PLUGIN_CONTRACT_UNSUPPORTED.md +23 -0
  28. package/dist/reference/errors/MOSTRA_PLUGIN_ENTRY_INVALID.md +23 -0
  29. package/dist/reference/errors/MOSTRA_PLUGIN_EXPORTER_UNKNOWN.md +23 -0
  30. package/dist/reference/errors/MOSTRA_PLUGIN_FAILED.md +23 -0
  31. package/dist/reference/errors/MOSTRA_PLUGIN_MANIFEST_INVALID.md +23 -0
  32. package/dist/reference/errors/MOSTRA_PLUGIN_MANIFEST_WARNING.md +23 -0
  33. package/dist/reference/errors/MOSTRA_PLUGIN_NOT_A_PLUGIN.md +23 -0
  34. package/dist/reference/errors/MOSTRA_PLUGIN_NOT_INSTALLED.md +23 -0
  35. package/dist/reference/errors/MOSTRA_PLUGIN_OPTIONS_INVALID.md +23 -0
  36. package/dist/reference/errors/MOSTRA_PLUGIN_PLATFORM_UNSUPPORTED.md +23 -0
  37. package/dist/reference/errors/MOSTRA_PLUGIN_SCOPE_INVALID.md +23 -0
  38. package/dist/reference/errors/MOSTRA_PLUGIN_SHADOWED.md +23 -0
  39. package/dist/skill/SKILL.md +4 -2
  40. package/dist/skill/references/mcp.md +2 -2
  41. package/dist/skill/references/plugins.md +51 -0
  42. package/package.json +10 -7
  43. package/src/deps/index.ts +407 -90
  44. package/src/deps/installer.ts +53 -10
  45. package/src/deps/lock.ts +74 -2
  46. package/src/home/settings.ts +3 -0
  47. package/src/instance/index.ts +57 -0
  48. package/src/packs/index.ts +7 -0
  49. package/src/packs/methods.ts +49 -0
  50. package/src/packs/packs.ts +706 -0
  51. package/src/packs/read.ts +759 -0
  52. package/src/platform/index.ts +1 -0
  53. package/src/platform/shell.ts +14 -0
  54. package/src/plugins/child/host.ts +231 -0
  55. package/src/plugins/child-protocol.ts +68 -0
  56. package/src/plugins/index.ts +7 -0
  57. package/src/plugins/location.ts +109 -0
  58. package/src/plugins/methods.ts +269 -0
  59. package/src/plugins/plugins.ts +1396 -0
  60. package/src/publish/publisher.ts +71 -3
  61. package/dist/instance-CFTw3g-c.js.map +0 -1
package/src/deps/index.ts CHANGED
@@ -48,16 +48,25 @@ import {
48
48
  linkTarget,
49
49
  replaceDirectoryLink,
50
50
  samePath,
51
- WINDOWS,
51
+ shellWord,
52
52
  } from "../platform/index.ts";
53
53
  import type { ProcessManager } from "../processes/index.ts";
54
54
  import { createInstaller, INSTALL_TIMEOUT_MS, type Installer } from "./installer.ts";
55
- import { type Lock, lockDigest, lockText, parseLock, pinnedPackages } from "./lock.ts";
55
+ import {
56
+ type Lock,
57
+ type LockLicense,
58
+ layoutKey,
59
+ lockDigest,
60
+ lockText,
61
+ parseLock,
62
+ pinnedPackages,
63
+ withExtras,
64
+ } from "./lock.ts";
56
65
  import { scanImports } from "./scan.ts";
57
66
  import { type PackageSpec, parseSpec } from "./specifier.ts";
58
67
  import type { WarmSet } from "./warm.ts";
59
68
 
60
- export { lockDigest, lockText, parseLock } from "./lock.ts";
69
+ export { type Lock, type LockLicense, lockDigest, lockText, parseLock } from "./lock.ts";
61
70
  export { scanImports } from "./scan.ts";
62
71
  export { packageOf, parseSpec } from "./specifier.ts";
63
72
  export { locateWarmSet, runtimeRoot, type WarmSet } from "./warm.ts";
@@ -83,6 +92,33 @@ export interface DependenciesOptions {
83
92
  readonly installTimeoutMs?: number;
84
93
  /** Test fault points `deps:*`. */
85
94
  readonly faults?: Faults;
95
+ /**
96
+ * The plugin gate (WP-16, D172 items 5, 7 and 8): every working lockfile that names plugins
97
+ * passes it before its install scripts run, before it is used and before it is recorded, whoever
98
+ * changed it (`deps/add`, a resolution at `verify` or `publish`, `change`'s own inspector). It is
99
+ * a getter because the plugins module is made after this one, which it uses.
100
+ */
101
+ readonly plugins?: () => PluginGate | undefined;
102
+ }
103
+
104
+ /**
105
+ * What the plugins module answers for a staged lockfile that names plugins: their checks, the
106
+ * disclosure of their licenses before any of their code or scripts run (it calls `staged.ready`
107
+ * once they pass), their entries; and the lockfile's plugins and acknowledgments after it. It
108
+ * throws the refusal (`MOSTRA_PLUGIN_*`, `MOSTRA_LICENSE_UNACCEPTED`), and nothing is recorded.
109
+ */
110
+ export interface PluginGate {
111
+ admit(input: {
112
+ readonly target: DependencyTarget;
113
+ readonly staged: StagedChange;
114
+ /** Licenses the caller acknowledged (`--accept-license`). */
115
+ readonly accept: readonly string[];
116
+ /** The command a refusal's fix repeats with `--accept-license`. */
117
+ readonly command: string;
118
+ }): Promise<{
119
+ readonly plugins: readonly string[];
120
+ readonly licenses: Readonly<Record<string, LockLicense>>;
121
+ }>;
86
122
  }
87
123
 
88
124
  /** What a build resolves its packages from. */
@@ -179,9 +215,75 @@ export interface Dependencies {
179
215
  add(
180
216
  target: DependencyTarget & {
181
217
  readonly packages: readonly string[];
218
+ /** Licenses acknowledged for the plugins the change touches (`--accept-license`, D31). */
219
+ readonly accept?: readonly string[];
182
220
  readonly request?: RequestKey | undefined;
183
221
  },
184
222
  ): Promise<DepsAddResult>;
223
+ /**
224
+ * Changes a working lockfile in one step, holding the artifact's (or the home's) queue
225
+ * throughout: resolves `add` (npm specs, as `deps/add` takes them) and drops `remove`, installs
226
+ * the resulting layout, then lets `inspect` look at it and say what the lockfile's plugins and
227
+ * acknowledgments become. Only when `inspect` returns is the working lockfile written, with
228
+ * them, so an install it refuses (a license nobody accepted, a plugin that doesn't load)
229
+ * records nothing. A `request` replays the result recorded for it.
230
+ */
231
+ change<T>(
232
+ target: DependencyTarget & {
233
+ readonly add: readonly string[];
234
+ readonly remove?: readonly string[];
235
+ readonly request?: RequestKey | undefined;
236
+ },
237
+ inspect: (staged: StagedChange) => Promise<StagedOutcome<T>>,
238
+ ): Promise<T>;
239
+ /**
240
+ * The working lockfile of `key` as it stands, and the layout it builds against. With
241
+ * `install: false` nothing is installed: `nodeModules` is the layout only when it is complete
242
+ * with its scripts run, else absent (a lookup that mustn't start an install, such as finding a
243
+ * plugin's command for a word `mostra` doesn't know).
244
+ */
245
+ working(
246
+ target: DependencyTarget,
247
+ options?: { readonly install?: boolean },
248
+ ): Promise<(Omit<StagedChange, "nodeModules"> & { readonly nodeModules?: string }) | undefined>;
249
+ }
250
+
251
+ /** A lockfile change before it is recorded: what `Dependencies.change` hands its inspector. */
252
+ export interface StagedChange {
253
+ /** The lockfile as it would be: the resolution's packages, the working lockfile's extras. */
254
+ readonly lock: Lock;
255
+ /** The `node_modules` it builds against (the warm set's without on-demand packages). */
256
+ readonly nodeModules: string;
257
+ /** The packages `add` named, as `deps/add` answers them. */
258
+ readonly added: readonly AddedPackage[];
259
+ /**
260
+ * Runs the lifecycle scripts the staged install deferred (D95's scripts, after the inspector's
261
+ * static checks): call it before loading any of the packages' code. The change runs it anyway
262
+ * before it records anything.
263
+ */
264
+ ready(): Promise<void>;
265
+ /** The working lockfile before the change, when there was one. */
266
+ readonly previous?: Lock;
267
+ }
268
+
269
+ /** What an inspector decides: the lockfile's plugins and acknowledgments, and the call's result. */
270
+ export interface StagedOutcome<T> {
271
+ readonly plugins?: readonly string[];
272
+ readonly licenses?: Readonly<Record<string, LockLicense>>;
273
+ /**
274
+ * Files the change writes beside the lockfile (a pack's items): run once the layout is complete
275
+ * with its scripts, just before the lockfile is recorded; `rollback` when recording fails,
276
+ * `commit` once it succeeded. A failure of its own records nothing.
277
+ */
278
+ write?(): Promise<StagedWrite>;
279
+ /** Builds the call's result from the lockfile's digest once it is recorded. */
280
+ result(lockDigest: string): T;
281
+ }
282
+
283
+ /** Files written beside a lockfile change, until the lockfile is recorded. */
284
+ export interface StagedWrite {
285
+ commit(): Promise<void>;
286
+ rollback(): Promise<void>;
185
287
  }
186
288
 
187
289
  /**
@@ -230,16 +332,6 @@ export function isOffline(env: Environment): boolean {
230
332
  );
231
333
  }
232
334
 
233
- /**
234
- * A shell-safe rendering of `value`, for the commands in diagnostics: POSIX shell quoting, or on
235
- * Windows the double quotes PowerShell and `cmd` both read (a Windows path holds no `"`), and a
236
- * plain path with backslashes as it is.
237
- */
238
- function shellQuote(value: string): string {
239
- if (WINDOWS) return /^[\w@%+=:,./\\-]+$/.test(value) ? value : `"${value}"`;
240
- return /^[\w@%+=:,./-]+$/.test(value) ? value : `'${value.replaceAll("'", `'\\''`)}'`;
241
- }
242
-
243
335
  /** Serializes work per key; one supervisor, so in-process order is the order. */
244
336
  class KeyedQueue {
245
337
  readonly #tails = new Map<string, Promise<unknown>>();
@@ -319,17 +411,6 @@ export function createDependencies(options: DependenciesOptions): Dependencies {
319
411
  ? { lock: parseLock(row.lock_text), added: JSON.parse(row.added_json) as string[] }
320
412
  : undefined;
321
413
  };
322
- const writeWorking = (key: string, text: string, added: readonly string[]): void => {
323
- ledger.write((db) =>
324
- db.run(
325
- "INSERT INTO dependency_lock (key, lock_text, added_json, updated_at) VALUES (?, ?, ?, ?) ON CONFLICT(key) DO UPDATE SET lock_text = excluded.lock_text, added_json = excluded.added_json, updated_at = excluded.updated_at",
326
- key,
327
- text,
328
- JSON.stringify([...new Set(added)].sort()),
329
- new Date().toISOString(),
330
- ),
331
- );
332
- };
333
414
  /** A working lockfile's stored text, or `null` without one. */
334
415
  const rowText = (key: string): string | null =>
335
416
  ledger.read(
@@ -398,6 +479,9 @@ export function createDependencies(options: DependenciesOptions): Dependencies {
398
479
  dir: work,
399
480
  cwd: input.artifactDir,
400
481
  offline: isOff,
482
+ // A resolution writes only a lockfile: nothing it fetches may run a script (a git
483
+ // dependency's `prepare`, WP-16 review R03 finding 8), whose license nobody has seen yet.
484
+ scripts: false,
401
485
  releaseAge: {
402
486
  exempt: additions.filter((spec) => spec.exact !== undefined).map((spec) => spec.name),
403
487
  },
@@ -429,6 +513,15 @@ export function createDependencies(options: DependenciesOptions): Dependencies {
429
513
  await replaceDirectoryLink(warm.nodeModules, link);
430
514
  };
431
515
 
516
+ /** A layout's marker, or `undefined` when it has none or it can't be read. */
517
+ const markerOf = async (dir: string): Promise<{ scripts?: string } | undefined> => {
518
+ try {
519
+ return JSON.parse(await readFile(join(dir, LAYOUT_MARKER), "utf8")) as { scripts?: string };
520
+ } catch {
521
+ return undefined;
522
+ }
523
+ };
524
+
432
525
  /**
433
526
  * The layout of `lock`, installed from the store (and the registry for what the store lacks)
434
527
  * into `deps/locks/<lockDigest>` unless it is already complete.
@@ -437,12 +530,32 @@ export function createDependencies(options: DependenciesOptions): Dependencies {
437
530
  lock: Lock,
438
531
  digest: string,
439
532
  target: { readonly key: string; readonly artifactDir: string },
533
+ scripts = true,
440
534
  ): Promise<string> =>
441
535
  byLayout.run(digest, async () => {
442
536
  const dir = join(dirs.locks, digest);
443
537
  const nodeModules = join(dir, "node_modules");
444
538
  if (existsSync(join(dir, LAYOUT_MARKER))) {
445
539
  await relinkWarm(dir);
540
+ // A layout installed with its scripts deferred (WP-16) runs them the first time anyone
541
+ // needs it whole: a plugin whose licenses were accepted, a build, a worker.
542
+ if (scripts && (await markerOf(dir))?.scripts === "pending") {
543
+ const outcome = await install().rebuild({
544
+ dir,
545
+ cwd: target.artifactDir,
546
+ ownerRef: target.key,
547
+ });
548
+ if (!outcome.ok) {
549
+ // Scripts that failed part-way leave a layout nobody can trust: it is made again.
550
+ await rm(dir, { recursive: true, force: true });
551
+ throw new RpcError(outcome.diagnostic);
552
+ }
553
+ await writeFile(
554
+ join(dir, LAYOUT_MARKER),
555
+ `${JSON.stringify({ lockDigest: digest, installer: install().version })}\n`,
556
+ );
557
+ log.info("deps.layout_scripts_ran", { lockDigest: digest });
558
+ }
446
559
  return nodeModules;
447
560
  }
448
561
  const pnpm = lock.pnpm as string;
@@ -471,6 +584,7 @@ export function createDependencies(options: DependenciesOptions): Dependencies {
471
584
  offline: isOff,
472
585
  releaseAge: false,
473
586
  ownerRef: target.key,
587
+ ...(scripts ? {} : { scripts: false as const }),
474
588
  });
475
589
  if (!outcome.ok) throw new RpcError(outcome.diagnostic);
476
590
  // The store index first, then the marker: a crash between them leaves an incomplete
@@ -490,7 +604,11 @@ export function createDependencies(options: DependenciesOptions): Dependencies {
490
604
  faults.at("deps:before-marker");
491
605
  await writeFile(
492
606
  join(dir, LAYOUT_MARKER),
493
- `${JSON.stringify({ lockDigest: digest, installer: install().version })}\n`,
607
+ `${JSON.stringify({
608
+ lockDigest: digest,
609
+ installer: install().version,
610
+ ...(scripts ? {} : { scripts: "pending" }),
611
+ })}\n`,
494
612
  );
495
613
  } catch (error) {
496
614
  await rm(dir, { recursive: true, force: true });
@@ -598,13 +716,14 @@ export function createDependencies(options: DependenciesOptions): Dependencies {
598
716
  const settle = async (
599
717
  lock: Lock,
600
718
  target: { readonly key: string; readonly artifactDir: string },
719
+ scripts = true,
601
720
  ): Promise<ResolvedDependencies> => {
602
721
  const text = lockText(lock);
603
722
  const digest = lockDigest(text);
604
723
  const nodeModules =
605
724
  Object.keys(lock.packages).length === 0
606
725
  ? warm.nodeModules
607
- : await ensureLayout(lock, digest, target);
726
+ : await ensureLayout(lock, layoutKey(lock), target, scripts);
608
727
  return { lock: text, lockDigest: digest, nodeModules };
609
728
  };
610
729
 
@@ -615,7 +734,7 @@ export function createDependencies(options: DependenciesOptions): Dependencies {
615
734
  }): Promise<string> => {
616
735
  const text = await readFile(join(target.versionDir, "lock.yaml"), "utf8");
617
736
  const lock = parseLock(text);
618
- const digest = lockDigest(text);
737
+ const digest = layoutKey(lock);
619
738
  const where = { key: target.artifactId, artifactDir: target.sourceDir ?? target.versionDir };
620
739
  // Mostra's own packages always come from this runtime: they aren't on a registry to pin.
621
740
  const drifted = Object.keys(lock.warm)
@@ -637,7 +756,14 @@ export function createDependencies(options: DependenciesOptions): Dependencies {
637
756
  .map((row) => row.lock_text),
638
757
  );
639
758
  const texts = [...working, ...input.keep];
640
- const named = new Set(texts.map((text) => lockDigest(text)));
759
+ const named = new Set<string>();
760
+ for (const text of texts) {
761
+ try {
762
+ named.add(layoutKey(parseLock(text)));
763
+ } catch {
764
+ // A lockfile Mostra can't read names no layout it could keep.
765
+ }
766
+ }
641
767
  const needed = new Set<string>();
642
768
  const need = (pnpm: string | undefined): void => {
643
769
  if (pnpm === undefined) return;
@@ -750,7 +876,7 @@ export function createDependencies(options: DependenciesOptions): Dependencies {
750
876
  if (missing.length > 0 && options.policy() === "explicit") {
751
877
  const first = missing[0] as string;
752
878
  const site = imports.get(first);
753
- const command = `mostra add ${missing.join(" ")} --artifact ${shellQuote(target.artifactPath)}`;
879
+ const command = `mostra add ${missing.join(" ")} --artifact ${shellWord(target.artifactPath)}`;
754
880
  throw new RpcError(
755
881
  createDiagnostic("MOSTRA_DEP_MISSING", {
756
882
  message: `${missing.join(", ")} ${missing.length === 1 ? "isn't" : "aren't"} in the warm set or the artifact's lockfile, and this home's dependency policy is explicit.`,
@@ -784,7 +910,13 @@ export function createDependencies(options: DependenciesOptions): Dependencies {
784
910
  previous: working?.lock.pnpm,
785
911
  });
786
912
  }
787
- const resolved = await settle(lock, target);
913
+ // Plugins and acknowledgments (WP-16) are carried as they are; a lockfile that names
914
+ // plugins passes the gate again, since its packages may have moved (D172 item 5).
915
+ lock = withExtras(lock, working?.lock);
916
+ const resolved = await admitted(target, lock, working?.lock, [], () => {
917
+ const names = (lock.plugins ?? []).map(shellWord).join(" ");
918
+ return `mostra plugin add ${names} --artifact ${shellWord(target.artifactPath)}`;
919
+ });
788
920
  const seen = rowText(target.key);
789
921
  return {
790
922
  ...resolved,
@@ -818,71 +950,256 @@ export function createDependencies(options: DependenciesOptions): Dependencies {
818
950
  ? undefined
819
951
  : ledger.read((db) => recordedResult<DepsAddResult>(db, request));
820
952
  if (recorded !== undefined) return recorded;
821
- const specs: PackageSpec[] = [];
822
- for (const text of target.packages) {
823
- const spec = parseSpec(text);
824
- if (!spec) {
825
- throw fail(
826
- "MOSTRA_DEP_SPEC_INVALID",
827
- `"${text}" isn't a registry package spec (name, name@version, name@range or name@tag).`,
828
- );
829
- }
830
- specs.push(spec);
831
- }
832
- for (const spec of specs) {
833
- const version = warm.packages[spec.name];
834
- if (version === undefined || spec.range === undefined) continue;
835
- const fits = semver.validRange(spec.range)
836
- ? semver.satisfies(version, spec.range)
837
- : spec.range === "latest";
838
- if (!fits) {
839
- throw fail(
840
- "MOSTRA_DEP_WARM_CONFLICT",
841
- `${spec.name} is in the warm set at ${version}, which every artifact uses; ${spec.name}@${spec.range} can't replace it.`,
842
- );
843
- }
844
- }
845
- const working = readWorking(target.key);
846
- const pinned = working?.lock.packages ?? {};
847
- const onDemand = specs.filter((spec) => !(spec.name in warm.packages));
848
- // A bare name that is already pinned keeps its pin; anything else resolves now.
849
- const additions = onDemand.filter(
850
- (spec) => spec.range !== undefined || pinned[spec.name] === undefined,
851
- );
852
- const additionNames = new Set(additions.map((spec) => spec.name));
853
- const pins = Object.fromEntries(
854
- Object.entries(pinned).filter(
855
- ([name]) => !additionNames.has(name) && !(name in warm.packages),
856
- ),
953
+ // A change of an artifact with plugins (an upgrade of one, or a package that moves their
954
+ // tree) runs nothing before the gate admits it (WP-16 review R01 finding 1); one without
955
+ // installs as it always did, its packages the agent's own choice (D20).
956
+ const plugins = (readWorking(target.key)?.lock.plugins ?? []).length > 0;
957
+ const staged = await stage(target, target.packages, [], !plugins);
958
+ const resolved = await admitted(
959
+ target,
960
+ staged.lock,
961
+ staged.working?.lock,
962
+ target.accept ?? [],
963
+ () =>
964
+ `mostra add ${target.packages.map(shellWord).join(" ")} --artifact ${shellWord(target.artifactPath)}`,
857
965
  );
858
- const lock: Lock =
859
- additions.length === 0 &&
860
- working !== undefined &&
861
- sameRecord(working.lock.warm, warm.packages)
862
- ? working.lock
863
- : Object.keys(pins).length === 0 && additions.length === 0
864
- ? { warm: warm.packages, packages: {} }
865
- : await resolveLock({
866
- key: target.key,
867
- artifactDir: target.artifactDir,
868
- pins,
869
- additions,
870
- previous: working?.lock.pnpm,
871
- });
872
- const resolved = await settle(lock, target);
873
- const added = [...(working?.added ?? []), ...onDemand.map((spec) => spec.name)];
874
- writeWorking(target.key, resolved.lock, added);
875
- const packages: AddedPackage[] = specs.map((spec) => {
876
- const warmVersion = warm.packages[spec.name];
877
- return warmVersion !== undefined
878
- ? { name: spec.name, version: warmVersion, warm: true }
879
- : { name: spec.name, version: lock.packages[spec.name] as string, warm: false };
966
+ const result: DepsAddResult = {
967
+ packages: staged.packages,
968
+ lockDigest: resolved.lockDigest,
969
+ };
970
+ ledger.write((db) => {
971
+ writeRow(db, target.key, resolved.lock, staged.names);
972
+ if (request !== undefined) recordResult(db, request, result);
973
+ });
974
+ return result;
975
+ }),
976
+
977
+ change: (target, inspect) =>
978
+ byArtifact.run(target.key, async () => {
979
+ const request = target.request;
980
+ if (request !== undefined) {
981
+ const recorded = ledger.read((db) => recordedResult<never>(db, request));
982
+ if (recorded !== undefined) return recorded;
983
+ }
984
+ // Nothing of a new package runs before its inspector accepted it: the layout installs
985
+ // without lifecycle scripts, which `ready` runs (once its licenses are accepted, WP-16).
986
+ const staged = await stage(target, target.add, target.remove ?? [], false);
987
+ let ready: Promise<void> | undefined;
988
+ const complete = (): Promise<void> =>
989
+ (ready ??= settle(staged.lock, target).then(() => undefined));
990
+ const outcome = await inspect({
991
+ lock: staged.lock,
992
+ nodeModules: staged.resolved.nodeModules,
993
+ added: staged.packages,
994
+ ready: complete,
995
+ ...(staged.working ? { previous: staged.working.lock } : {}),
880
996
  });
881
- const result: DepsAddResult = { packages, lockDigest: resolved.lockDigest };
882
- if (request !== undefined) ledger.write((db) => recordResult(db, request, result));
997
+ await complete();
998
+ const text = lockText(withOutcome(staged.lock, outcome));
999
+ const result = outcome.result(lockDigest(text));
1000
+ const written = await outcome.write?.();
1001
+ try {
1002
+ ledger.write((db) => {
1003
+ writeRow(db, target.key, text, staged.names);
1004
+ if (request !== undefined) recordResult(db, request, result);
1005
+ });
1006
+ } catch (problem) {
1007
+ await written?.rollback();
1008
+ throw problem;
1009
+ }
1010
+ await written?.commit();
883
1011
  return result;
884
1012
  }),
1013
+
1014
+ working: async (target, workingOptions) => {
1015
+ const working = readWorking(target.key);
1016
+ if (working === undefined) return undefined;
1017
+ const base = {
1018
+ lock: working.lock,
1019
+ added: [],
1020
+ ready: async () => undefined,
1021
+ previous: working.lock,
1022
+ };
1023
+ if (workingOptions?.install === false) {
1024
+ const nodeModules = await installedLayout(working.lock);
1025
+ return nodeModules !== undefined ? { ...base, nodeModules } : base;
1026
+ }
1027
+ // The working lockfile was admitted when it was recorded: its layout installs with its
1028
+ // scripts, as it did then.
1029
+ const resolved = await settle(working.lock, target);
1030
+ return { ...base, nodeModules: resolved.nodeModules };
1031
+ },
885
1032
  };
1033
+
1034
+ /**
1035
+ * Settles `lock` for use: a lockfile without plugins as it always settled; one with plugins with
1036
+ * its scripts held, through the plugin gate, which runs them once it admitted the plugins, and
1037
+ * with the plugins and acknowledgments the gate answers (a host's pre-acceptance is recorded
1038
+ * there). Without a gate (an instance with no plugins module) it fails closed.
1039
+ */
1040
+ async function admitted(
1041
+ target: DependencyTarget,
1042
+ lock: Lock,
1043
+ previous: Lock | undefined,
1044
+ accept: readonly string[],
1045
+ command: () => string,
1046
+ ): Promise<ResolvedDependencies> {
1047
+ if ((lock.plugins ?? []).length === 0) return settle(lock, target);
1048
+ const gate = options.plugins?.();
1049
+ if (gate === undefined) {
1050
+ throw fail(
1051
+ "MOSTRA_PLUGIN_FAILED",
1052
+ "This lockfile names plugins, and this instance has no plugins module to check them.",
1053
+ );
1054
+ }
1055
+ const held = await settle(lock, target, false);
1056
+ let ready: Promise<void> | undefined;
1057
+ const runScripts = (): Promise<void> => {
1058
+ ready ??= settle(lock, target).then(() => undefined);
1059
+ return ready;
1060
+ };
1061
+ const outcome = await gate.admit({
1062
+ target,
1063
+ staged: {
1064
+ lock,
1065
+ nodeModules: held.nodeModules,
1066
+ added: [],
1067
+ ready: runScripts,
1068
+ ...(previous !== undefined ? { previous } : {}),
1069
+ },
1070
+ accept,
1071
+ command: command(),
1072
+ });
1073
+ await runScripts();
1074
+ const text = lockText(withOutcome(lock, outcome));
1075
+ return { lock: text, lockDigest: lockDigest(text), nodeModules: held.nodeModules };
1076
+ }
1077
+
1078
+ /** `lock`'s packages with an outcome's plugins and acknowledgments. */
1079
+ function withOutcome(
1080
+ lock: Lock,
1081
+ outcome: {
1082
+ readonly plugins?: readonly string[];
1083
+ readonly licenses?: Readonly<Record<string, LockLicense>>;
1084
+ },
1085
+ ): Lock {
1086
+ const { plugins: _plugins, licenses: _licenses, ...packages } = lock;
1087
+ const plugins = [...(outcome.plugins ?? [])];
1088
+ const licenses = { ...(outcome.licenses ?? {}) };
1089
+ return {
1090
+ ...packages,
1091
+ ...(plugins.length > 0 ? { plugins } : {}),
1092
+ ...(Object.keys(licenses).length > 0 ? { licenses } : {}),
1093
+ };
1094
+ }
1095
+
1096
+ /** The `node_modules` of `lock` when it is installed complete, scripts run; else `undefined`. */
1097
+ async function installedLayout(lock: Lock): Promise<string | undefined> {
1098
+ if (Object.keys(lock.packages).length === 0) return warm.nodeModules;
1099
+ const dir = join(dirs.locks, layoutKey(lock));
1100
+ const marker = await markerOf(dir);
1101
+ if (marker === undefined || marker.scripts === "pending") return undefined;
1102
+ return join(dir, "node_modules");
1103
+ }
1104
+
1105
+ /**
1106
+ * Resolves a change of a working lockfile without recording it: `add` (npm specs) resolve, the
1107
+ * packages in `remove` leave it (they stay only where the source imports them, at the next
1108
+ * resolution), and the layout is installed.
1109
+ */
1110
+ async function stage(
1111
+ target: DependencyTarget,
1112
+ add: readonly string[],
1113
+ remove: readonly string[],
1114
+ scripts = true,
1115
+ ): Promise<{
1116
+ readonly lock: Lock;
1117
+ readonly resolved: ResolvedDependencies;
1118
+ readonly packages: AddedPackage[];
1119
+ /** The packages added on purpose, kept whatever the source imports. */
1120
+ readonly names: string[];
1121
+ readonly working: WorkingLock | undefined;
1122
+ }> {
1123
+ const specs: PackageSpec[] = [];
1124
+ for (const text of add) {
1125
+ const spec = parseSpec(text);
1126
+ if (!spec) {
1127
+ throw fail(
1128
+ "MOSTRA_DEP_SPEC_INVALID",
1129
+ `"${text}" isn't a registry package spec (name, name@version, name@range or name@tag).`,
1130
+ );
1131
+ }
1132
+ specs.push(spec);
1133
+ }
1134
+ for (const spec of specs) {
1135
+ const version = warm.packages[spec.name];
1136
+ if (version === undefined || spec.range === undefined) continue;
1137
+ const fits = semver.validRange(spec.range)
1138
+ ? semver.satisfies(version, spec.range)
1139
+ : spec.range === "latest";
1140
+ if (!fits) {
1141
+ throw fail(
1142
+ "MOSTRA_DEP_WARM_CONFLICT",
1143
+ `${spec.name} is in the warm set at ${version}, which every artifact uses; ${spec.name}@${spec.range} can't replace it.`,
1144
+ );
1145
+ }
1146
+ }
1147
+ const working = readWorking(target.key);
1148
+ const pinned = working?.lock.packages ?? {};
1149
+ const dropped = new Set(remove);
1150
+ const onDemand = specs.filter((spec) => !(spec.name in warm.packages));
1151
+ // A bare name that is already pinned keeps its pin; anything else resolves now.
1152
+ const additions = onDemand.filter(
1153
+ (spec) => spec.range !== undefined || pinned[spec.name] === undefined,
1154
+ );
1155
+ const additionNames = new Set(additions.map((spec) => spec.name));
1156
+ const pins = Object.fromEntries(
1157
+ Object.entries(pinned).filter(
1158
+ ([name]) => !additionNames.has(name) && !(name in warm.packages) && !dropped.has(name),
1159
+ ),
1160
+ );
1161
+ const unchanged =
1162
+ additions.length === 0 &&
1163
+ !Object.keys(pinned).some((name) => dropped.has(name)) &&
1164
+ working !== undefined &&
1165
+ sameRecord(working.lock.warm, warm.packages);
1166
+ let lock: Lock =
1167
+ unchanged && working !== undefined
1168
+ ? working.lock
1169
+ : Object.keys(pins).length === 0 && additions.length === 0
1170
+ ? { warm: warm.packages, packages: {} }
1171
+ : await resolveLock({
1172
+ key: target.key,
1173
+ artifactDir: target.artifactDir,
1174
+ pins,
1175
+ additions,
1176
+ previous: working?.lock.pnpm,
1177
+ });
1178
+ lock = withExtras(lock, working?.lock);
1179
+ const resolved = await settle(lock, target, scripts);
1180
+ const names = [
1181
+ ...(working?.added ?? []).filter((name) => !dropped.has(name)),
1182
+ ...onDemand.map((spec) => spec.name),
1183
+ ];
1184
+ const packages: AddedPackage[] = specs.map((spec) => {
1185
+ const warmVersion = warm.packages[spec.name];
1186
+ return warmVersion !== undefined
1187
+ ? { name: spec.name, version: warmVersion, warm: true }
1188
+ : { name: spec.name, version: lock.packages[spec.name] as string, warm: false };
1189
+ });
1190
+ return { lock, resolved, packages, names, working };
1191
+ }
1192
+
1193
+ /** Writes a working lockfile's row inside a transaction. */
1194
+ function writeRow(db: LedgerDb, key: string, text: string, added: readonly string[]): void {
1195
+ db.run(
1196
+ "INSERT INTO dependency_lock (key, lock_text, added_json, updated_at) VALUES (?, ?, ?, ?) ON CONFLICT(key) DO UPDATE SET lock_text = excluded.lock_text, added_json = excluded.added_json, updated_at = excluded.updated_at",
1197
+ key,
1198
+ text,
1199
+ JSON.stringify([...new Set(added)].sort()),
1200
+ new Date().toISOString(),
1201
+ );
1202
+ }
886
1203
  }
887
1204
 
888
1205
  /** The bytes of the files under `dir` that nothing else links to (a layout's own files). */