@mostra/runtime 0.0.0-stage → 0.1.0

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 (114) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +39 -2
  3. package/dist/bin.d.ts +1 -0
  4. package/dist/bin.js +236 -0
  5. package/dist/bin.js.map +1 -0
  6. package/dist/builder/child/main.d.ts +1 -0
  7. package/dist/builder/child/main.js +1408 -0
  8. package/dist/builder/child/main.js.map +1 -0
  9. package/dist/child-xrHmytks.js +49 -0
  10. package/dist/child-xrHmytks.js.map +1 -0
  11. package/dist/deps/child/install.d.ts +1 -0
  12. package/dist/deps/child/install.js +33 -0
  13. package/dist/deps/child/install.js.map +1 -0
  14. package/dist/index.d.ts +221 -0
  15. package/dist/index.d.ts.map +1 -0
  16. package/dist/index.js +3 -0
  17. package/dist/instance-D7_UVdoN.js +15752 -0
  18. package/dist/instance-D7_UVdoN.js.map +1 -0
  19. package/dist/types-NjNy7gXX.js +57 -0
  20. package/dist/types-NjNy7gXX.js.map +1 -0
  21. package/package.json +87 -3
  22. package/src/actions/index.ts +622 -0
  23. package/src/addressing/index.ts +281 -0
  24. package/src/bin.ts +240 -0
  25. package/src/builder/child/dev.ts +383 -0
  26. package/src/builder/child/fields.ts +363 -0
  27. package/src/builder/child/main.ts +47 -0
  28. package/src/builder/child/plugins.ts +195 -0
  29. package/src/builder/child/scan.ts +459 -0
  30. package/src/builder/child/spa.ts +348 -0
  31. package/src/builder/coverage.ts +72 -0
  32. package/src/builder/index.ts +406 -0
  33. package/src/builder/types.ts +180 -0
  34. package/src/deps/child/install.ts +30 -0
  35. package/src/deps/index.ts +918 -0
  36. package/src/deps/installer.ts +321 -0
  37. package/src/deps/lock.ts +82 -0
  38. package/src/deps/scan.ts +266 -0
  39. package/src/deps/specifier.ts +64 -0
  40. package/src/deps/warm.ts +57 -0
  41. package/src/dev/index.ts +518 -0
  42. package/src/faults.ts +65 -0
  43. package/src/gate.ts +55 -0
  44. package/src/gateway/actions.ts +268 -0
  45. package/src/gateway/browser.ts +650 -0
  46. package/src/gateway/capabilities.ts +739 -0
  47. package/src/gateway/controls.ts +91 -0
  48. package/src/gateway/dev.ts +119 -0
  49. package/src/gateway/http.ts +229 -0
  50. package/src/gateway/index.ts +1209 -0
  51. package/src/gateway/integrity.ts +117 -0
  52. package/src/gateway/listener.ts +217 -0
  53. package/src/gateway/routes.ts +197 -0
  54. package/src/gateway/serve.ts +138 -0
  55. package/src/gc/index.ts +451 -0
  56. package/src/home/acquire.ts +276 -0
  57. package/src/home/index.ts +16 -0
  58. package/src/home/paths.ts +192 -0
  59. package/src/home/platform.ts +34 -0
  60. package/src/home/record.ts +76 -0
  61. package/src/home/settings.ts +113 -0
  62. package/src/index.ts +30 -0
  63. package/src/instance/index.ts +942 -0
  64. package/src/interaction/ephemeral.ts +300 -0
  65. package/src/interaction/events.ts +355 -0
  66. package/src/interaction/fields.ts +392 -0
  67. package/src/interaction/index.ts +1009 -0
  68. package/src/interaction/outbox.ts +493 -0
  69. package/src/interaction/policy.ts +26 -0
  70. package/src/interaction/results.ts +341 -0
  71. package/src/interaction/runs.ts +313 -0
  72. package/src/interaction/signals.ts +120 -0
  73. package/src/interaction/submissions.ts +585 -0
  74. package/src/interaction/subscriptions.ts +258 -0
  75. package/src/interaction/viewers.ts +173 -0
  76. package/src/interaction/wait.ts +201 -0
  77. package/src/ledger/index.ts +442 -0
  78. package/src/ledger/migrations.ts +583 -0
  79. package/src/ledger/requests.ts +105 -0
  80. package/src/ledger/types.ts +28 -0
  81. package/src/live/index.ts +573 -0
  82. package/src/log.ts +316 -0
  83. package/src/processes/child.ts +67 -0
  84. package/src/processes/environment.ts +64 -0
  85. package/src/processes/identity.ts +191 -0
  86. package/src/processes/index.ts +19 -0
  87. package/src/processes/manager.ts +543 -0
  88. package/src/protocol-server/client.ts +94 -0
  89. package/src/protocol-server/index.ts +91 -0
  90. package/src/protocol-server/server.ts +509 -0
  91. package/src/protocol-server/streams.ts +81 -0
  92. package/src/publish/checks.ts +92 -0
  93. package/src/publish/digest.ts +87 -0
  94. package/src/publish/index.ts +23 -0
  95. package/src/publish/manifest.ts +409 -0
  96. package/src/publish/methods.ts +96 -0
  97. package/src/publish/publisher.ts +913 -0
  98. package/src/publish/source.ts +272 -0
  99. package/src/publish/tar.ts +110 -0
  100. package/src/registry/index.ts +481 -0
  101. package/src/registry/store.ts +136 -0
  102. package/src/secrets/index.ts +223 -0
  103. package/src/service/idle.ts +64 -0
  104. package/src/service/index.ts +3 -0
  105. package/src/service/unit.ts +250 -0
  106. package/src/verify/fields.ts +125 -0
  107. package/src/verify/index.ts +913 -0
  108. package/src/verify/regression.ts +157 -0
  109. package/src/verify/runner.ts +230 -0
  110. package/src/verify/sandbox.ts +407 -0
  111. package/src/verify/typecheck.ts +371 -0
  112. package/src/workers/index.ts +17 -0
  113. package/src/workers/launcher.ts +260 -0
  114. package/src/workers/pool.ts +708 -0
@@ -0,0 +1,913 @@
1
+ /**
2
+ * Publish (ARCHITECTURE §3, VR-01, VR-02, VR-11): freezes an artifact's source into an immutable,
3
+ * content-addressed version. Steps, any of which can fail and leave no visible version:
4
+ *
5
+ * 1. snapshot the source into staging and read its manifest from the snapshot (never running it);
6
+ * 2. resolve and freeze the dependencies into `lock.yaml` (D95), installing what's missing;
7
+ * 3. compute `sourceDigest`, `envDigest` and the version ID (D89);
8
+ * 4. (the verify gate, WP-09);
9
+ * 5. build in a builder child, archive the source snapshot into `sources/`, seal the output and
10
+ * rename it into `versions/`;
11
+ * 6. commit the version, the source binding and `version.published` in one ledger transaction;
12
+ * 7. return the receipt.
13
+ *
14
+ * Staging lives in the home, and a version directory without its ledger row is removed at the next
15
+ * start, so a crash at any step leaves nothing visible (FAILURE_MODEL §3).
16
+ */
17
+
18
+ import { createHash } from "node:crypto";
19
+ import { createReadStream, createWriteStream, existsSync, readFileSync } from "node:fs";
20
+ import {
21
+ mkdir,
22
+ mkdtemp,
23
+ readdir,
24
+ readFile,
25
+ realpath,
26
+ rename,
27
+ rm,
28
+ stat,
29
+ writeFile,
30
+ } from "node:fs/promises";
31
+ import { basename, dirname, extname, join } from "node:path";
32
+ import { Readable } from "node:stream";
33
+ import { pipeline } from "node:stream/promises";
34
+ import { createZstdCompress } from "node:zlib";
35
+ import {
36
+ type ArtifactCreateParams,
37
+ type ArtifactCreateResult,
38
+ ArtifactId,
39
+ type ArtifactManifest,
40
+ type ArtifactPublishParams,
41
+ type ArtifactVerifyParams,
42
+ BROWSER_PROTOCOL_REVISION,
43
+ createDiagnostic,
44
+ type DepsAddParams,
45
+ type DepsAddResult,
46
+ type Diagnostic,
47
+ type PublishReceipt,
48
+ RpcError,
49
+ type SourceRef,
50
+ type SubmissionPolicy,
51
+ type VerifyVerdict,
52
+ } from "@mostra/protocol";
53
+ import type { RenderMode } from "../builder/index.ts";
54
+ import { type Dependencies, lockKey, type Resolution } from "../deps/index.ts";
55
+ import { type Faults, noFaults } from "../faults.ts";
56
+ import type { Gate } from "../gate.ts";
57
+ import {
58
+ InflightRequests,
59
+ type Ledger,
60
+ type RequestKey,
61
+ recordedResult,
62
+ recordResult,
63
+ requestKey,
64
+ } from "../ledger/index.ts";
65
+ import type { Log } from "../log.ts";
66
+ import { fsyncPath, type Registry, removeTree } from "../registry/index.ts";
67
+ import {
68
+ type BuildOutcome,
69
+ errorCodes,
70
+ type PreparedSource,
71
+ VERIFY_REVISION,
72
+ type Verifier,
73
+ } from "../verify/index.ts";
74
+ import {
75
+ type BuildEnvironment,
76
+ canonicalJson,
77
+ environmentDigest,
78
+ type ListedFile,
79
+ listingDigest,
80
+ sha256Hex,
81
+ versionIdFor,
82
+ } from "./digest.ts";
83
+ import { extractManifest } from "./manifest.ts";
84
+ import {
85
+ copySnapshot,
86
+ listSource,
87
+ type ResolvedSource,
88
+ readEntry,
89
+ resolveSource,
90
+ } from "./source.ts";
91
+ import { TAR_END, tarFile } from "./tar.ts";
92
+
93
+ /** Options for {@link createPublisher}. */
94
+ export interface PublisherOptions {
95
+ readonly registry: Registry;
96
+ readonly ledger: Ledger;
97
+ readonly renderMode: RenderMode;
98
+ /** Resolves each build's packages and lockfile (D95). */
99
+ readonly dependencies: Dependencies;
100
+ /** This runtime's release (`mostraVersion` in `envDigest`). */
101
+ readonly runtimeVersion: string;
102
+ readonly log: Log;
103
+ /** Test fault points `publish:*` (VR-02). */
104
+ readonly faults?: Faults;
105
+ /** The home's submission policy (`HomeConfig.submission`, D102), read at each publish. */
106
+ readonly homePolicy?: () => SubmissionPolicy | undefined;
107
+ /** The verifier, made on first use: publish's gate and `artifact/verify` (D41, D138). */
108
+ readonly verifier: () => Verifier;
109
+ /**
110
+ * Tests of other features only (`MOSTRA_TEST_UNVERIFIED_PUBLISH`): publish without the gate.
111
+ * Such a version records no verdict, so it never counts as passing (D138 item 4).
112
+ */
113
+ readonly unverified?: boolean;
114
+ /**
115
+ * The instance's gate (D140 item 14): publishes, verify runs and dependency additions hold it
116
+ * shared, so `gc` never removes files they use.
117
+ */
118
+ readonly gate?: Gate;
119
+ }
120
+
121
+ /** Publishes and creates artifacts. */
122
+ export interface Publisher {
123
+ /** `artifact/publish`: gated by verify (D41). */
124
+ publish(params: ArtifactPublishParams): Promise<PublishReceipt>;
125
+ /** `artifact/verify`: one run, its verdict cached for the publish that follows (D138). */
126
+ verify(params: ArtifactVerifyParams, progress?: (stage: string) => void): Promise<VerifyVerdict>;
127
+ /** `artifact/create`. */
128
+ create(params: ArtifactCreateParams): Promise<ArtifactCreateResult>;
129
+ /** `deps/add`: adds packages to an artifact's working lockfile (D95). */
130
+ addDependencies(params: DepsAddParams): Promise<DepsAddResult>;
131
+ }
132
+
133
+ const ENTRY_NAMES = ["index.tsx", "index.jsx", "index.mdx"];
134
+
135
+ /** The title of an artifact without a manifest: its directory's name, or a single file's own name. */
136
+ function defaultTitle(source: ResolvedSource): string {
137
+ if (source.kind === "dir") return basename(source.root);
138
+ const stem = basename(source.entry, extname(source.entry));
139
+ return stem === "page" || stem === "index" ? basename(source.root) : stem;
140
+ }
141
+
142
+ /**
143
+ * Whether the source at `path` still claims `artifactId` in its manifest (D51). Synchronous: it
144
+ * runs inside the commit transaction. Anything unreadable no longer claims anything.
145
+ */
146
+ function stillClaims(path: string, artifactId: string): boolean {
147
+ // Read, never check-then-read: the source may change between the two (CodeQL js/file-system-race).
148
+ const claims = (file: string): boolean | undefined => {
149
+ let text: string;
150
+ try {
151
+ text = readFileSync(file, "utf8");
152
+ } catch (error) {
153
+ const code = (error as NodeJS.ErrnoException).code;
154
+ if (code === "ENOENT" || code === "EISDIR" || code === "ENOTDIR") return undefined;
155
+ return false;
156
+ }
157
+ try {
158
+ return extractManifest(basename(file), text).manifest?.id === artifactId;
159
+ } catch {
160
+ return false;
161
+ }
162
+ };
163
+ const asFile = claims(path);
164
+ if (asFile !== undefined) return asFile;
165
+ for (const name of ENTRY_NAMES) {
166
+ const result = claims(join(path, name));
167
+ if (result !== undefined) return result;
168
+ }
169
+ return false;
170
+ }
171
+
172
+ async function hashFile(path: string): Promise<string> {
173
+ const hash = createHash("sha256");
174
+ for await (const chunk of createReadStream(path)) hash.update(chunk as Buffer);
175
+ return hash.digest("hex");
176
+ }
177
+
178
+ /**
179
+ * The canonical listing of a version's output (DATA_MODEL §2, `outputDigest`): every file under
180
+ * `client/` and `server/`, and `registry.json`, with paths relative to the version directory.
181
+ * The version is sealed read-only (0444), so no file is listed as executable: the digest
182
+ * describes the stored tree exactly and can be recomputed from it.
183
+ */
184
+ async function outputListing(versionDir: string): Promise<ListedFile[]> {
185
+ const files: ListedFile[] = [];
186
+ const walk = async (current: string, relative: string): Promise<void> => {
187
+ for (const entry of await readdir(current, { withFileTypes: true })) {
188
+ const path = `${relative}/${entry.name}`;
189
+ const absolute = join(current, entry.name);
190
+ if (entry.isDirectory()) await walk(absolute, path);
191
+ else if (entry.isFile()) {
192
+ files.push({ path, executable: false, sha256: await hashFile(absolute) });
193
+ }
194
+ }
195
+ };
196
+ for (const top of ["client", "server"]) {
197
+ if (existsSync(join(versionDir, top))) await walk(join(versionDir, top), top);
198
+ }
199
+ files.push({
200
+ path: "registry.json",
201
+ executable: false,
202
+ sha256: await hashFile(join(versionDir, "registry.json")),
203
+ });
204
+ return files;
205
+ }
206
+
207
+ /**
208
+ * Writes the source snapshot archive (`sources/<artifact>/<sourceDigest>.tar.zst`), atomically.
209
+ * Returns whether it wrote one: an existing archive holds the same tree (content-addressed).
210
+ */
211
+ async function archiveSnapshot(
212
+ source: string,
213
+ files: readonly ListedFile[],
214
+ target: string,
215
+ ): Promise<boolean> {
216
+ if (existsSync(target)) return false;
217
+ const created = !existsSync(dirname(target));
218
+ await mkdir(dirname(target), { recursive: true, mode: 0o700 });
219
+ // A new artifact directory in sources/ must be durable too.
220
+ if (created) fsyncPath(dirname(dirname(target)), true);
221
+ const temporary = `${target}.${process.pid}.tmp`;
222
+ const sorted = [...files].sort((a, b) =>
223
+ Buffer.compare(Buffer.from(a.path), Buffer.from(b.path)),
224
+ );
225
+ async function* blocks(): AsyncGenerator<Buffer> {
226
+ for (const file of sorted) {
227
+ const data = await readFile(join(source, ...file.path.split("/")));
228
+ yield* tarFile({ path: file.path, executable: file.executable, data });
229
+ }
230
+ yield TAR_END;
231
+ }
232
+ const output = createWriteStream(temporary, { mode: 0o400 });
233
+ await pipeline(Readable.from(blocks()), createZstdCompress(), output);
234
+ const handle = await import("node:fs/promises").then((fs) => fs.open(temporary, "r"));
235
+ try {
236
+ await handle.sync();
237
+ } finally {
238
+ await handle.close();
239
+ }
240
+ await rename(temporary, target);
241
+ fsyncPath(dirname(target), true);
242
+ return true;
243
+ }
244
+
245
+ /** The entry `artifact/create` writes: a manifest with the generated `id` and a minimal page. */
246
+ function scaffold(artifactId: string, title: string): string {
247
+ return [
248
+ 'import { defineArtifact } from "@mostra/react";',
249
+ "",
250
+ "export const artifact = defineArtifact({",
251
+ ` id: ${JSON.stringify(artifactId)},`,
252
+ ` title: ${JSON.stringify(title)},`,
253
+ "});",
254
+ "",
255
+ "export default function Page() {",
256
+ " return (",
257
+ ' <main className="mx-auto max-w-2xl p-8">',
258
+ ' <h1 className="text-2xl font-semibold">{artifact.title}</h1>',
259
+ " </main>",
260
+ " );",
261
+ "}",
262
+ "",
263
+ ].join("\n");
264
+ }
265
+
266
+ /**
267
+ * Writes `artifact/create`'s entry into `dir`, completing an interrupted write: an existing file
268
+ * that is the expected text or a prefix of it (a write cut short) ends as the expected text, and
269
+ * anything else the author has written since is left alone.
270
+ */
271
+ async function writeScaffold(dir: string, artifactId: string, title: string): Promise<void> {
272
+ const expected = scaffold(artifactId, title);
273
+ const file = join(dir, "index.tsx");
274
+ await mkdir(dir, { recursive: true });
275
+ let current: string | undefined;
276
+ try {
277
+ current = await readFile(file, "utf8");
278
+ } catch {
279
+ current = undefined;
280
+ }
281
+ if (current !== undefined && !expected.startsWith(current)) return;
282
+ if (current === expected) return;
283
+ await writeFile(file, expected);
284
+ fsyncPath(file);
285
+ fsyncPath(dir, true);
286
+ }
287
+
288
+ /**
289
+ * The output digest of a version directory's files (DATA_MODEL §2): what its manifest records and
290
+ * the integrity checks compare. Tests that freeze a version for VR-10 recompute it.
291
+ */
292
+ export async function versionOutputDigest(dir: string): Promise<string> {
293
+ return listingDigest(await outputListing(dir));
294
+ }
295
+
296
+ /**
297
+ * What is wrong with a stored version directory, or `undefined` when it is intact: its
298
+ * `manifest.json` names an output digest, and its `client/`, `server/` and `registry.json` still
299
+ * have that digest (DATA_MODEL §2).
300
+ */
301
+ /**
302
+ * What is wrong with a stored version directory, or `undefined` when its files still match the
303
+ * output digest its manifest records (FAILURE_MODEL §3). Publish rebuilds a damaged directory; the
304
+ * gateway refuses to show one.
305
+ */
306
+ export async function versionDamage(dir: string): Promise<string | undefined> {
307
+ let recorded: unknown;
308
+ try {
309
+ recorded = (
310
+ JSON.parse(await readFile(join(dir, "manifest.json"), "utf8")) as { outputDigest?: unknown }
311
+ ).outputDigest;
312
+ } catch (error) {
313
+ return `its manifest.json can't be read (${(error as NodeJS.ErrnoException).code ?? "invalid JSON"})`;
314
+ }
315
+ try {
316
+ const actual = listingDigest(await outputListing(dir));
317
+ return actual === recorded ? undefined : "its files no longer match their output digest";
318
+ } catch (error) {
319
+ return `its files can't be read (${(error as NodeJS.ErrnoException).code ?? "error"})`;
320
+ }
321
+ }
322
+
323
+ /** Serializes work per key, so two publishes of one artifact never race (FAILURE_MODEL §1 rule 2). */
324
+ class KeyedQueue {
325
+ readonly #tails = new Map<string, Promise<unknown>>();
326
+ run<T>(key: string, task: () => Promise<T>): Promise<T> {
327
+ const previous = this.#tails.get(key) ?? Promise.resolve();
328
+ const next = previous.then(task, task);
329
+ const tail = next.then(
330
+ () => undefined,
331
+ () => undefined,
332
+ );
333
+ this.#tails.set(key, tail);
334
+ void tail.then(() => {
335
+ if (this.#tails.get(key) === tail) this.#tails.delete(key);
336
+ });
337
+ return next;
338
+ }
339
+ }
340
+
341
+ /** The first diagnostic of a failed build, or a generic one. */
342
+ function firstDiagnostic(diagnostics: readonly Diagnostic[]): Diagnostic {
343
+ return (
344
+ diagnostics[0] ?? createDiagnostic("MOSTRA_BUILD_FAILED", { message: "The build failed." })
345
+ );
346
+ }
347
+
348
+ /**
349
+ * The verdict of a source verify couldn't prepare (an invalid manifest, dependencies that can't be
350
+ * resolved): that diagnostic alone, never cached (D138 item 3).
351
+ */
352
+ function failedVerdict(path: string, diagnostic: Diagnostic): VerifyVerdict {
353
+ return {
354
+ status: diagnostic.severity === "error" ? "fail" : "pass",
355
+ artifact: { path, sourceDigest: "", envDigest: "" },
356
+ diagnostics: [diagnostic],
357
+ screenshots: [],
358
+ aria: [],
359
+ smoke: { interactions: 0, skippedActions: [], stateChanges: 0 },
360
+ regressions: {},
361
+ timingsMs: { total: 0 },
362
+ };
363
+ }
364
+
365
+ const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
366
+
367
+ /**
368
+ * Verify's stand-in artifact ID for a source no manifest `id` or binding names yet: derived from
369
+ * its real path, shaped like a ULID (D77's alphabet), and never committed anywhere.
370
+ */
371
+ function stableProvisional(bindingPath: string): string {
372
+ const hash = createHash("sha256")
373
+ .update(`mostra verify provisional\u0000${bindingPath}`)
374
+ .digest();
375
+ let body = CROCKFORD[(hash[0] as number) % 8] as string;
376
+ for (let index = 1; index < 26; index += 1) body += CROCKFORD[(hash[index] as number) % 32];
377
+ return ArtifactId.parse(`art_${body}`);
378
+ }
379
+
380
+ /** Creates the publisher of one instance. */
381
+ export function createPublisher(options: PublisherOptions): Publisher {
382
+ const { registry, ledger, renderMode, dependencies, log, verifier } = options;
383
+ const faults = options.faults ?? noFaults;
384
+ const queue = new KeyedQueue();
385
+ const buildConfigDigest = sha256Hex(canonicalJson(renderMode.buildConfig));
386
+ const inflight = new InflightRequests();
387
+
388
+ /**
389
+ * Replays the result recorded for a repeated `requestId` with the same parameters (H-03), joins
390
+ * an attempt still running, or runs `task` once. The same `requestId` with other parameters is
391
+ * `MOSTRA_HOST_REQUEST_ID_REUSED`.
392
+ */
393
+ const idempotent = async <T>(key: RequestKey | undefined, task: () => Promise<T>): Promise<T> => {
394
+ if (key === undefined) return task();
395
+ const recorded = ledger.read((db) => recordedResult<T>(db, key));
396
+ if (recorded !== undefined) return recorded;
397
+ return inflight.run(key, task);
398
+ };
399
+
400
+ const record = (key: RequestKey | undefined, result: unknown): void => {
401
+ if (key === undefined) return;
402
+ ledger.write((db) => recordResult(db, key, result));
403
+ };
404
+
405
+ /** The path a `SourceRef` names: itself, or the path an artifact was last published from. */
406
+ const pathOf = (ref: SourceRef): string => {
407
+ if ("path" in ref) return ref.path;
408
+ const bound = registry.sourceOf(ref.artifactId);
409
+ if (bound === undefined) {
410
+ throw new RpcError(
411
+ createDiagnostic("MOSTRA_ARTIFACT_NOT_FOUND", {
412
+ message: `No artifact ${ref.artifactId} was published in this home; name it by its source path.`,
413
+ }),
414
+ );
415
+ }
416
+ return bound;
417
+ };
418
+
419
+ /** What {@link prepare} read of a snapshot, besides the {@link PreparedSource}. */
420
+ interface Staged {
421
+ readonly prepared: PreparedSource;
422
+ readonly source: ResolvedSource;
423
+ readonly listed: readonly ListedFile[];
424
+ readonly entryHasDefault: boolean;
425
+ readonly environment: BuildEnvironment;
426
+ readonly deps: Resolution;
427
+ }
428
+
429
+ /**
430
+ * Steps 1 to 3 of a publish, shared with verify (D41, D95): the snapshot, its manifest, the
431
+ * dependencies (resolved exactly as publish does, through the same working lockfile) and the
432
+ * digests. Throws the manifest's or the dependencies' diagnostic.
433
+ */
434
+ const prepare = async (
435
+ path: string,
436
+ source: ResolvedSource,
437
+ provisional: string,
438
+ identityKnown: boolean,
439
+ staging: string,
440
+ ): Promise<Staged> => {
441
+ // 1. Snapshot, then read the manifest from the snapshot: what is built is what was read.
442
+ const files = await listSource(source);
443
+ const listed = await copySnapshot(files, join(staging, "source"));
444
+ faults.at("publish:after-snapshot");
445
+ const extracted = extractManifest(
446
+ source.entry,
447
+ await readFile(join(staging, "source", source.entry), "utf8"),
448
+ );
449
+ for (const warning of extracted.warnings)
450
+ log.warn("publish.manifest_warning", { code: warning.code, message: warning.message });
451
+ const manifest: ArtifactManifest = extracted.manifest ?? { title: defaultTitle(source) };
452
+ const artifactId = registry.identityFor(source.bindingPath, manifest.id, () => provisional);
453
+ if (artifactId !== provisional) {
454
+ throw new RpcError(
455
+ createDiagnostic("MOSTRA_PUBLISH_SOURCE_CHANGED", {
456
+ message: `The manifest of ${path} changed while it was being published.`,
457
+ }),
458
+ );
459
+ }
460
+
461
+ // 2. The dependencies, from the snapshot's imports and the artifact's working lockfile.
462
+ const deps = await dependencies.resolve({
463
+ key: lockKey(manifest.id ?? registry.artifactAt(source.bindingPath), source.bindingPath),
464
+ sourceDir: join(staging, "source"),
465
+ artifactDir: source.root,
466
+ artifactPath: path,
467
+ });
468
+ faults.at("publish:after-dependencies");
469
+
470
+ // 3. Digests (DATA_MODEL §2).
471
+ const sourceDigest = listingDigest(listed);
472
+ const environment: BuildEnvironment = {
473
+ mostraVersion: options.runtimeVersion,
474
+ kitVersion: null,
475
+ kitBase: manifest.kit?.base ?? "base",
476
+ mode: manifest.mode ?? "spa",
477
+ lockDigest: deps.lockDigest,
478
+ buildConfigDigest,
479
+ // The browser protocol the version's client runtime speaks (VR-10, D106).
480
+ browserProtocolRevision: BROWSER_PROTOCOL_REVISION,
481
+ };
482
+ const envDigest = environmentDigest(environment);
483
+ const versionId = versionIdFor(artifactId, sourceDigest, envDigest);
484
+ faults.at("publish:after-digests");
485
+ return {
486
+ prepared: {
487
+ path,
488
+ stagingDir: staging,
489
+ sourceDir: source.root,
490
+ manifest,
491
+ warnings: extracted.warnings,
492
+ artifactId,
493
+ identityKnown,
494
+ sourceDigest,
495
+ envDigest,
496
+ versionId,
497
+ nodeModules: deps.nodeModules,
498
+ },
499
+ source,
500
+ listed,
501
+ entryHasDefault: extracted.hasDefaultExport,
502
+ environment,
503
+ deps,
504
+ };
505
+ };
506
+
507
+ /**
508
+ * Step 5's build, laid out as a version directory in `out`: the client and server builds,
509
+ * `registry.json`, `lock.yaml` and `manifest.json` (whose `forcedCodes` and `verify` publish
510
+ * fills in when it promotes; neither is part of the output digest).
511
+ */
512
+ const stageBuild = async (staged: Staged, out: string): Promise<BuildOutcome> => {
513
+ const { prepared } = staged;
514
+ const built = await renderMode.build({
515
+ stagingDir: prepared.stagingDir,
516
+ entry: staged.source.entry,
517
+ entryHasDefault: staged.entryHasDefault,
518
+ manifest: prepared.manifest,
519
+ versionId: prepared.versionId,
520
+ nodeModules: staged.deps.nodeModules,
521
+ outDir: out,
522
+ });
523
+ if (!built.ok) return { ok: false, diagnostics: built.diagnostics };
524
+ faults.at("publish:after-build");
525
+ await writeFile(join(out, "registry.json"), `${JSON.stringify(built.registry, null, 2)}\n`);
526
+ await writeFile(join(out, "lock.yaml"), staged.deps.lock);
527
+ const outputDigest = listingDigest(await outputListing(out));
528
+ await writeVersionManifest(out, staged, {
529
+ outputDigest,
530
+ server: built.server,
531
+ forcedCodes: [],
532
+ });
533
+ return { ok: true, outputDigest, registry: built.registry };
534
+ };
535
+
536
+ /** Writes a version directory's `manifest.json`. */
537
+ const writeVersionManifest = async (
538
+ out: string,
539
+ staged: Staged,
540
+ fields: {
541
+ readonly outputDigest: string;
542
+ readonly server: boolean;
543
+ readonly forcedCodes: readonly string[];
544
+ readonly verify?: { readonly status: "pass" | "fail"; readonly verifyRevision: string };
545
+ },
546
+ ): Promise<void> => {
547
+ const { prepared } = staged;
548
+ await writeFile(
549
+ join(out, "manifest.json"),
550
+ `${JSON.stringify(
551
+ {
552
+ schemaVersion: 1,
553
+ artifactId: prepared.artifactId,
554
+ versionId: prepared.versionId,
555
+ mode: staged.environment.mode,
556
+ entry: staged.source.entry,
557
+ server: fields.server,
558
+ manifest: prepared.manifest,
559
+ sourceDigest: prepared.sourceDigest,
560
+ envDigest: prepared.envDigest,
561
+ environment: staged.environment,
562
+ outputDigest: fields.outputDigest,
563
+ forcedCodes: fields.forcedCodes,
564
+ ...(fields.verify ? { verify: fields.verify } : {}),
565
+ },
566
+ null,
567
+ 2,
568
+ )}\n`,
569
+ );
570
+ };
571
+
572
+ /**
573
+ * Runs `fn` with the source's identity decided and its staging directory made: one at a time per
574
+ * source path, then per artifact (always in that order, so they can't deadlock), so a path-bound
575
+ * artifact's identity is decided once and two copies claiming one ID never promote the same
576
+ * version directory at once. The commit checks the identity again inside its transaction.
577
+ */
578
+ const staged = async <T>(
579
+ ref: SourceRef,
580
+ fn: (input: {
581
+ readonly path: string;
582
+ readonly source: ResolvedSource;
583
+ readonly provisional: string;
584
+ readonly identityKnown: boolean;
585
+ readonly staging: string;
586
+ }) => Promise<T>,
587
+ how?: { readonly stableProvisional?: boolean },
588
+ ): Promise<T> => {
589
+ const path = pathOf(ref);
590
+ const source = await resolveSource(path);
591
+ return queue.run(`path:${source.bindingPath}`, async () => {
592
+ // A manifest that can't be read here is reported by `prepare`, from the snapshot.
593
+ let peeked: string | undefined;
594
+ try {
595
+ peeked = extractManifest(source.entry, await readEntry(source)).manifest?.id;
596
+ } catch {
597
+ peeked = undefined;
598
+ }
599
+ const known = peeked ?? registry.artifactAt(source.bindingPath);
600
+ // An unbound source's artifact is decided at its first publish (D51). Verify's stand-in is
601
+ // derived from the path, so verifying unchanged source again reuses its build; a publish's
602
+ // is new, as the artifact's real ID (Opus review finding 9).
603
+ const provisional =
604
+ known ??
605
+ (how?.stableProvisional ? stableProvisional(source.bindingPath) : ArtifactId.create());
606
+ return queue.run(`artifact:${provisional}`, async () => {
607
+ const staging = await mkdtemp(join(registry.store.stagingDir, "publish-"));
608
+ try {
609
+ return await fn({
610
+ path,
611
+ source,
612
+ provisional,
613
+ identityKnown: known !== undefined,
614
+ staging,
615
+ });
616
+ } finally {
617
+ await removeTree(staging);
618
+ await removeTree(`${staging}-check`);
619
+ }
620
+ });
621
+ });
622
+ };
623
+
624
+ const verifyOnce = (params: ArtifactVerifyParams, progress?: (stage: string) => void) =>
625
+ staged(
626
+ params.source,
627
+ async ({ path, source, provisional, identityKnown, staging }) => {
628
+ progress?.("prepare");
629
+ let ready: Staged;
630
+ try {
631
+ ready = await prepare(path, source, provisional, identityKnown, staging);
632
+ } catch (error) {
633
+ // A manifest or the dependencies that can't be read are the verdict, not a failure of verify.
634
+ if (
635
+ error instanceof RpcError &&
636
+ /^MOSTRA_(MANIFEST|DEP|ARTIFACT|BUILD)_/.test(error.diagnostic.code)
637
+ ) {
638
+ return failedVerdict(path, error.diagnostic);
639
+ }
640
+ throw error;
641
+ }
642
+ // Verify records the working lockfile like publish (D95), so the publish that follows
643
+ // resolves the same versions and its environment digest matches the cached verdict.
644
+ ledger.write((db) =>
645
+ ready.deps.save(
646
+ db,
647
+ lockKey(
648
+ ready.prepared.manifest.id ?? registry.artifactAt(source.bindingPath),
649
+ source.bindingPath,
650
+ ),
651
+ ),
652
+ );
653
+ const outcome = await verifier().run(ready.prepared, {
654
+ build: (out) => stageBuild(ready, out),
655
+ ...(params.screenshots ? { screenshots: params.screenshots } : {}),
656
+ ...(progress ? { progress } : {}),
657
+ });
658
+ return outcome.verdict;
659
+ },
660
+ { stableProvisional: true },
661
+ );
662
+
663
+ const publishOnce = (params: ArtifactPublishParams): Promise<PublishReceipt> =>
664
+ staged(params.source, async ({ path, source, provisional, identityKnown, staging }) => {
665
+ // What this publish placed in the store before its commit; removed again if it fails
666
+ // (the next start removes it too, should this process die first: FAILURE_MODEL §3).
667
+ const undo: (() => Promise<void>)[] = [];
668
+ let committed = false;
669
+ try {
670
+ const ready = await prepare(path, source, provisional, identityKnown, staging);
671
+ const { prepared } = ready;
672
+ const { artifactId, versionId, sourceDigest, envDigest, manifest } = prepared;
673
+
674
+ // 4 and 5. Gate, build, archive and promote, unless this artifact already has this exact
675
+ // version. A version whose directory is missing or no longer matches its own recorded
676
+ // output digest is rebuilt from the same source and environment, and put back in place;
677
+ // its ledger row stays as it was (FAILURE_MODEL §3, D80 Claude review finding 3).
678
+ let outputDigest: string | undefined;
679
+ let forcedCodes: string[] = [];
680
+ let verifyRecord: { status: "pass" | "fail"; verifyRevision: string } | undefined;
681
+ const recorded = registry.version(versionId);
682
+ const exists = recorded !== undefined;
683
+ // An existing version keeps what it was published with: its forced codes reach this
684
+ // receipt and event too, and a repaired directory gets them back (D41, D138).
685
+ if (recorded) {
686
+ forcedCodes = [...recorded.forcedCodes];
687
+ verifyRecord = recorded.verify;
688
+ }
689
+ const damage = exists
690
+ ? await versionDamage(registry.store.versionDir(versionId))
691
+ : undefined;
692
+ if (damage !== undefined) log.warn("publish.version_damaged", { versionId, damage });
693
+ if (!exists || damage !== undefined) {
694
+ const out = join(staging, "out");
695
+ if (exists || options.unverified === true) {
696
+ // A repair (the version passed, or was forced, when it was published), or a test of
697
+ // another feature that publishes without the gate.
698
+ const built = await stageBuild(ready, out);
699
+ if (!built.ok) throw new RpcError(firstDiagnostic(built.diagnostics));
700
+ outputDigest = built.outputDigest;
701
+ if (exists) {
702
+ await writeVersionManifest(out, ready, {
703
+ outputDigest,
704
+ server: existsSync(join(out, "server", "entry.mjs")),
705
+ forcedCodes,
706
+ ...(verifyRecord ? { verify: verifyRecord } : {}),
707
+ });
708
+ }
709
+ } else {
710
+ // 4. The gate (D41, D138): the verdict cached for these digests, or a run now.
711
+ const outcome =
712
+ verifier().cached(prepared) ??
713
+ (await verifier().run(prepared, { build: (dir) => stageBuild(ready, dir) }));
714
+ const { verdict } = outcome;
715
+ // What didn't build can't be published, whatever the flags (D138 item 7): the run
716
+ // recorded whether compile produced a build, so no code is matched to decide it.
717
+ if (!outcome.built) {
718
+ throw new RpcError(
719
+ verdict.diagnostics.find(
720
+ (diagnostic) => diagnostic.severity === "error" && diagnostic.phase === "compile",
721
+ ) ??
722
+ verdict.diagnostics.find((diagnostic) => diagnostic.severity === "error") ??
723
+ createDiagnostic("MOSTRA_BUILD_FAILED", { message: "The build failed." }),
724
+ );
725
+ }
726
+ const errors = errorCodes(verdict);
727
+ // Verify couldn't run (no browser): without --force, publish fails with that
728
+ // environment error itself, so the caller knows it isn't the artifact (D138 item 7).
729
+ const environmental = verdict.diagnostics.find(
730
+ (diagnostic) =>
731
+ diagnostic.severity === "error" && diagnostic.code.startsWith("MOSTRA_ENV_"),
732
+ );
733
+ if (environmental && params.force !== true) throw new RpcError(environmental);
734
+ if (errors.length > 0 && params.force !== true) {
735
+ throw new RpcError(
736
+ createDiagnostic("MOSTRA_PUBLISH_VERIFY_FAILED", {
737
+ message: `Verify found errors, so nothing was published: ${errors.join(", ")}.`,
738
+ }),
739
+ );
740
+ }
741
+ forcedCodes = params.force === true ? errors : [];
742
+ verifyRecord = {
743
+ status: errors.length === 0 ? "pass" : "fail",
744
+ verifyRevision: VERIFY_REVISION,
745
+ };
746
+ // 5. Verify's build, promoted as it is when it was made for this version ID; built
747
+ // again from the same snapshot otherwise (D138 item 5).
748
+ const cachedBuild = verifier().builtVersion(versionId);
749
+ if (cachedBuild && (await versionDamage(cachedBuild)) === undefined) {
750
+ await rename(cachedBuild, out);
751
+ outputDigest = (
752
+ JSON.parse(await readFile(join(out, "manifest.json"), "utf8")) as {
753
+ outputDigest: string;
754
+ }
755
+ ).outputDigest;
756
+ } else {
757
+ log.info("publish.rebuild", {
758
+ versionId,
759
+ reason: cachedBuild ? "damaged" : "not cached",
760
+ });
761
+ const built = await stageBuild(ready, out);
762
+ if (!built.ok) throw new RpcError(firstDiagnostic(built.diagnostics));
763
+ outputDigest = built.outputDigest;
764
+ }
765
+ const server = existsSync(join(out, "server", "entry.mjs"));
766
+ await writeVersionManifest(out, ready, {
767
+ outputDigest,
768
+ server,
769
+ forcedCodes,
770
+ verify: verifyRecord,
771
+ });
772
+ }
773
+ const archive = registry.store.snapshotPath(artifactId, sourceDigest);
774
+ if (await archiveSnapshot(join(staging, "source"), ready.listed, archive)) {
775
+ undo.push(() => rm(archive, { force: true }));
776
+ }
777
+ faults.at("publish:after-archive");
778
+ if (damage !== undefined) await removeTree(registry.store.versionDir(versionId));
779
+ undo.push(() => removeTree(registry.store.versionDir(versionId)));
780
+ await registry.store.promote(out, versionId);
781
+ faults.at("publish:after-promote");
782
+ }
783
+
784
+ // 6. One transaction: identity, version, binding, events.
785
+ const result = registry.commit({
786
+ artifactId,
787
+ bindingPath: source.bindingPath,
788
+ manifestId: manifest.id,
789
+ versionId,
790
+ sourceDigest,
791
+ envDigest,
792
+ outputDigest,
793
+ manifest,
794
+ // D102: the registry resolves the policy in force from these, the earlier publishes'
795
+ // choice and the manifest's request.
796
+ policy: params.policy,
797
+ homePolicy: options.homePolicy?.(),
798
+ forcedCodes,
799
+ ...(verifyRecord ? { verify: verifyRecord } : {}),
800
+ stillClaims,
801
+ faults,
802
+ request: requestKey("artifact/publish", params),
803
+ // The resolution becomes the artifact's working lockfile only with the version (D95):
804
+ // a refused publish, such as a copy claiming another artifact's ID, changes nothing.
805
+ inTransaction: (db) => ready.deps.save(db, artifactId),
806
+ });
807
+ committed = true;
808
+ faults.at("publish:after-commit");
809
+ log.info("publish.committed", {
810
+ artifactId,
811
+ versionId,
812
+ version: result.version,
813
+ reused: result.reused,
814
+ ...(forcedCodes.length > 0 ? { forcedCodes } : {}),
815
+ });
816
+ return {
817
+ artifactId,
818
+ versionId,
819
+ version: result.version,
820
+ cursor: result.cursor,
821
+ reused: result.reused,
822
+ ...(forcedCodes.length > 0 ? { forcedDiagnostics: forcedCodes } : {}),
823
+ };
824
+ } catch (error) {
825
+ if (!committed) {
826
+ for (const step of undo.reverse()) {
827
+ await step().catch((cleanup: unknown) =>
828
+ log.warn("publish.undo_failed", { error: cleanup }),
829
+ );
830
+ }
831
+ }
832
+ throw error;
833
+ }
834
+ });
835
+
836
+ const gated = <T>(fn: () => Promise<T>): Promise<T> =>
837
+ options.gate ? options.gate.shared(fn) : fn();
838
+
839
+ return {
840
+ publish: (params) =>
841
+ gated(() =>
842
+ idempotent(requestKey("artifact/publish", params), async () => {
843
+ // The receipt is recorded inside the commit's transaction (Registry.commit).
844
+ return publishOnce(params);
845
+ }),
846
+ ),
847
+ verify: (params, progress) => gated(() => verifyOnce(params, progress)),
848
+ // Creates run one at a time: two requests for one directory, or one request sent twice, can
849
+ // never both find it empty.
850
+ create: (params) => queue.run("create", () => create(params)),
851
+ // Runs in the source path's queue, like its publishes, so a publish that binds the path never
852
+ // races an addition to the path-keyed lockfile it re-keys.
853
+ addDependencies: (params) => gated(() => addDependencies(params)),
854
+ };
855
+
856
+ async function addDependencies(params: DepsAddParams): Promise<DepsAddResult> {
857
+ {
858
+ const path = pathOf(params.artifact);
859
+ const source = await resolveSource(path);
860
+ return queue.run(`path:${source.bindingPath}`, async () => {
861
+ const manifestId = extractManifest(source.entry, await readEntry(source)).manifest?.id;
862
+ return dependencies.add({
863
+ key: lockKey(manifestId ?? registry.artifactAt(source.bindingPath), source.bindingPath),
864
+ artifactDir: source.root,
865
+ artifactPath: path,
866
+ packages: params.packages,
867
+ request: requestKey("deps/add", params),
868
+ });
869
+ });
870
+ }
871
+ }
872
+
873
+ async function create(params: ArtifactCreateParams): Promise<ArtifactCreateResult> {
874
+ // A retried request completes what the first attempt recorded (H-03): the entry is written
875
+ // only after the result is durable, so a crash in between leaves something to finish.
876
+ const key = requestKey("artifact/create", params);
877
+ if (key !== undefined) {
878
+ const result = ledger.read((db) => recordedResult<ArtifactCreateResult>(db, key));
879
+ if (result !== undefined) {
880
+ await writeScaffold(result.dir, result.artifactId, params.title ?? basename(result.dir));
881
+ return result;
882
+ }
883
+ }
884
+ if (params.template !== undefined) {
885
+ throw new RpcError(
886
+ createDiagnostic("MOSTRA_ARTIFACT_TEMPLATE_UNKNOWN", {
887
+ message: `This Mostra release provides no template "${params.template}"; create the artifact without one.`,
888
+ }),
889
+ );
890
+ }
891
+ if (existsSync(params.dir)) {
892
+ const info = await stat(params.dir);
893
+ if (!info.isDirectory() || (await readdir(params.dir)).length > 0) {
894
+ throw new RpcError(
895
+ createDiagnostic("MOSTRA_ARTIFACT_DIR_NOT_EMPTY", {
896
+ message: `${params.dir} already exists and isn't an empty directory.`,
897
+ }),
898
+ );
899
+ }
900
+ }
901
+ await mkdir(params.dir, { recursive: true });
902
+ const dir = await realpath(params.dir);
903
+ const result: ArtifactCreateResult = {
904
+ artifactId: ArtifactId.create(),
905
+ dir,
906
+ files: ["index.tsx"],
907
+ };
908
+ record(key, result);
909
+ faults.at("create:after-record");
910
+ await writeScaffold(dir, result.artifactId, params.title ?? basename(dir));
911
+ return result;
912
+ }
913
+ }