@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,383 @@
1
+ /**
2
+ * `mostra dev`'s server (D140 item 12, VR-08): Vite in middleware mode over the dev root, whose
3
+ * `source/` the supervisor keeps a mirror of the artifact's source, with the SPA build's own
4
+ * plugins, so a page in dev is built as its published version would be. It listens on a loopback
5
+ * port the operating system picks and answers only requests that carry the session's secret,
6
+ * which only the dev sandbox's gateway sends: a browser reaches it only through the gateway's
7
+ * route table (Host, Origin, session), never directly, and never through a capability URL of the
8
+ * home. Its HMR WebSocket is served through the same check, on Vite's own token and allowed hosts.
9
+ *
10
+ * When the source changes, Vite updates client modules in place (HMR). When the artifact has
11
+ * server code, the server bundle and `registry.json` are built again and the supervisor told
12
+ * (`builder/dev.server`); once it runs the new bundle, it asks the child to reload every page.
13
+ * When `pages/`, `"use server"` modules or `live.ts` change, the generated entry is written again.
14
+ */
15
+ import { createHash, timingSafeEqual } from "node:crypto";
16
+ import { mkdir, readdir, readFile, rm, symlink, writeFile } from "node:fs/promises";
17
+ import {
18
+ createServer as createHttpServer,
19
+ type IncomingMessage,
20
+ type ServerResponse,
21
+ } from "node:http";
22
+ import { join } from "node:path";
23
+ import type { Duplex } from "node:stream";
24
+ import tailwind from "@tailwindcss/vite";
25
+ import react from "@vitejs/plugin-react";
26
+ import { parseSync } from "oxc-parser";
27
+ import { build, createServer, type Plugin, type ViteDevServer } from "vite";
28
+ import type { SupervisorConnection } from "../../processes/index.ts";
29
+ import {
30
+ DEV_SECRET_HEADER,
31
+ DEV_SERVER_NOTIFICATION,
32
+ DEV_UPDATE_NOTIFICATION,
33
+ type DevChange,
34
+ type DevReady,
35
+ type DevRequest,
36
+ type DevServerBuild,
37
+ LIVE_DECLARATION,
38
+ type ServerFunctionEntry,
39
+ STAGING_FILES,
40
+ type VersionRegistry,
41
+ } from "../types.ts";
42
+ import { type BuildInputs, confinePlugin, mdxPlugin, serverClientStubPlugin } from "./plugins.ts";
43
+ import { type ScanResult, scanArtifact } from "./scan.ts";
44
+ import {
45
+ baseConfig,
46
+ clientEntry,
47
+ diagnose,
48
+ GENERATED,
49
+ html,
50
+ packageRoots,
51
+ serverEntry,
52
+ } from "./spa.ts";
53
+
54
+ /** A running dev server. */
55
+ export interface DevServer {
56
+ readonly ready: DevReady;
57
+ /** The supervisor changed these files of the mirror: update the pages, rebuild what depends on them. */
58
+ changed(changes: readonly DevChange[]): Promise<void>;
59
+ /** Tells every page to load again. */
60
+ reload(): void;
61
+ close(): Promise<void>;
62
+ }
63
+
64
+ /** The custom HMR event a dev page sends with the time it was served. */
65
+ const LOADED_EVENT = "mostra:dev.loaded";
66
+
67
+ /** Whether a request carries the session's secret (compared in constant time). */
68
+ function hasSecret(headers: IncomingMessage["headers"], secret: string): boolean {
69
+ const given = headers[DEV_SECRET_HEADER];
70
+ if (typeof given !== "string") return false;
71
+ const a = Buffer.from(given);
72
+ const b = Buffer.from(secret);
73
+ return a.length === b.length && timingSafeEqual(a, b);
74
+ }
75
+
76
+ /** What the server entry depends on: which server modules, functions and live sources exist. */
77
+ function serverShape(scan: ScanResult): string {
78
+ return JSON.stringify({
79
+ modules: [...scan.serverModules].map(([module, entries]) => [module, entries.map((e) => e.id)]),
80
+ live: scan.hasLive,
81
+ });
82
+ }
83
+
84
+ /** What the client entry depends on: the pages. */
85
+ const pageShape = (scan: ScanResult): string => JSON.stringify(scan.pages);
86
+
87
+ /** Starts the dev server for `request`. */
88
+ export async function startDev(
89
+ request: DevRequest,
90
+ supervisor: SupervisorConnection,
91
+ ): Promise<DevServer> {
92
+ const root = request.root;
93
+ const sourceDir = join(root, "source");
94
+ const generated = join(root, GENERATED);
95
+ await mkdir(generated, { recursive: true });
96
+ for (const [name, text] of Object.entries(STAGING_FILES)) await writeFile(join(root, name), text);
97
+ await rm(join(root, "node_modules"), { force: true, recursive: true });
98
+ await symlink(request.nodeModules, join(root, "node_modules"), "dir");
99
+ await writeFile(join(generated, "styles.css"), `@import "tailwindcss" source("../source");\n`);
100
+ await mkdir(request.outDir, { recursive: true });
101
+ // Vite's pre-bundled dependencies live in the session's root (`cacheDir` below); they are
102
+ // packages the build may import, as the layout they were bundled from is.
103
+ const viteCache = join(root, ".vite");
104
+ const inputs: BuildInputs = {
105
+ sourceDir,
106
+ generatedDir: generated,
107
+ packageRoots: [...(await packageRoots(request.nodeModules)), viteCache],
108
+ };
109
+
110
+ let scan = await scanArtifact(sourceDir);
111
+ // The client stubs read this map on every transform, so a new "use server" export is stubbed
112
+ // once the map is refreshed and the module invalidated.
113
+ const serverModules = new Map<string, readonly ServerFunctionEntry[]>();
114
+ const refreshServerModules = (): void => {
115
+ serverModules.clear();
116
+ for (const [module, entries] of scan.serverModules)
117
+ serverModules.set(join(sourceDir, module), entries);
118
+ };
119
+ refreshServerModules();
120
+ const writeEntry = async (): Promise<void> => {
121
+ await writeFile(join(generated, "entry.js"), clientEntry(request, scan));
122
+ if (scan.hasLive) await writeFile(join(generated, "mostra-env.d.ts"), LIVE_DECLARATION);
123
+ };
124
+ await writeEntry();
125
+ await writeFile(
126
+ join(generated, "dev-loaded.js"),
127
+ `const served = Number(document.querySelector('meta[name="mostra-dev-served"]')?.content);\nimport.meta.hot?.send(${JSON.stringify(LOADED_EVENT)}, served);\n`,
128
+ );
129
+ const indexHtml = html(request.manifest.title, request.versionId);
130
+
131
+ /** Builds the server bundle and `registry.json` into the dev version's directory. */
132
+ let lastBundle = "";
133
+ const buildServer = async (): Promise<DevServerBuild> => {
134
+ if (scan.diagnostics.length > 0 || scan.unparsed.length > 0)
135
+ return { ok: false, diagnostics: [...scan.diagnostics, ...scan.unparsed] };
136
+ const server = scan.serverModules.size > 0 || scan.hasLive;
137
+ if (server) {
138
+ await writeFile(join(generated, "server-entry.js"), serverEntry(scan));
139
+ try {
140
+ await build({
141
+ ...baseConfig({ stagingDir: root }, sourceDir, [
142
+ confinePlugin(inputs),
143
+ mdxPlugin(),
144
+ react(),
145
+ ]),
146
+ mode: "development",
147
+ publicDir: false,
148
+ ssr: { external: ["@mostra/server"], target: "node" },
149
+ build: {
150
+ ssr: join(generated, "server-entry.js"),
151
+ outDir: join(request.outDir, "server"),
152
+ emptyOutDir: true,
153
+ sourcemap: true,
154
+ rolldownOptions: {
155
+ external: ["@mostra/server"],
156
+ output: { entryFileNames: "entry.mjs", format: "es" },
157
+ },
158
+ },
159
+ });
160
+ } catch (error) {
161
+ return { ok: false, diagnostics: [diagnose(error, sourceDir)] };
162
+ }
163
+ } else {
164
+ await rm(join(request.outDir, "server"), { recursive: true, force: true });
165
+ }
166
+ lastBundle = await bundleDigest(join(request.outDir, "server"));
167
+ const registry: VersionRegistry = {
168
+ schemaVersion: 1,
169
+ entry: request.entry,
170
+ actions: [...scan.serverModules.values()].flat(),
171
+ liveSources: scan.liveSources,
172
+ pages: scan.pages,
173
+ terminals: Object.keys(request.manifest.terminals ?? {}).sort(),
174
+ demos: Object.keys(request.manifest.demos ?? {}).sort(),
175
+ // Dev serves whatever the source names; nothing is ever orphaned in a preview.
176
+ fields: { ...scan.fields, open: true, openReasons: [{ reason: "a development preview" }] },
177
+ };
178
+ await writeFile(
179
+ join(request.outDir, "registry.json"),
180
+ `${JSON.stringify(registry, null, 2)}\n`,
181
+ );
182
+ return { ok: true, registry, server };
183
+ };
184
+
185
+ const firstBuild = await buildServer();
186
+
187
+ // Vite's HMR WebSocket attaches to this server, which never listens: the real server hands it
188
+ // only upgrades that carry the secret.
189
+ const hmrServer = createHttpServer();
190
+ const vite: ViteDevServer = await createServer({
191
+ ...baseConfig({ stagingDir: root }, sourceDir, [
192
+ confinePlugin(inputs),
193
+ mdxPlugin(),
194
+ serverClientStubPlugin(serverModules, sourceDir),
195
+ manifestExportPlugin(join(sourceDir, request.entry)),
196
+ react(),
197
+ tailwind(),
198
+ ]),
199
+ mode: "development",
200
+ appType: "custom",
201
+ // Vite's pre-bundled dependencies stay in the session's own root, never in the shared warm
202
+ // set or a lock layout behind `node_modules`, which other sessions and builds read.
203
+ cacheDir: viteCache,
204
+ publicDir: join(sourceDir, "public"),
205
+ server: {
206
+ middlewareMode: true,
207
+ ws: { server: hmrServer },
208
+ // Vite watches nothing: the supervisor, which keeps the mirror, says what changed (and a
209
+ // watcher would walk the whole package layout behind node_modules).
210
+ watch: null,
211
+ // Requests arrive from the gateway's artifact origin on loopback; any other Host (a DNS
212
+ // rebinding) is refused by Vite as well as by the gateway.
213
+ allowedHosts: ["127.0.0.1", "localhost"],
214
+ cors: false,
215
+ fs: { strict: true, allow: [root, ...inputs.packageRoots] },
216
+ },
217
+ optimizeDeps: { entries: [`${GENERATED}/entry.js`] },
218
+ });
219
+
220
+ // A page reports when it was served once its modules have run; one served before the last
221
+ // change (that update reached it before its modules accepted updates, or before its socket
222
+ // opened, as after a new dev server) loads again. Vite's own client drops such updates. Times,
223
+ // not a counter, so a page a previous dev server of the session served compares too.
224
+ let changedAt = 0;
225
+ vite.ws.on(LOADED_EVENT, (served: unknown, client) => {
226
+ if (typeof served === "number" && served <= changedAt) client.send({ type: "full-reload" });
227
+ });
228
+ const serveHtml = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
229
+ // The time is a meta tag the report module reads: an inline module would be cached by Vite
230
+ // (and by the browser, behind its ETag) with the first page's time. The report runs after the
231
+ // entry's module graph has run (module scripts run in document order, each after its
232
+ // imports), so every module that accepts updates has said so: an update that arrived before
233
+ // that was dropped by Vite's client, and the report makes the page load again.
234
+ const served = `<meta name="mostra-dev-served" content="${Date.now()}" />`;
235
+ const report = `<script type="module" src="/${GENERATED}/dev-loaded.js"></script>`;
236
+ const page = await vite.transformIndexHtml(
237
+ req.url ?? "/",
238
+ indexHtml
239
+ .replace("</head>", ` ${served}\n </head>`)
240
+ .replace("</body>", ` ${report}\n </body>`),
241
+ );
242
+ res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-cache" });
243
+ res.end(page);
244
+ };
245
+ const http = createHttpServer((req, res) => {
246
+ if (!hasSecret(req.headers, request.secret)) {
247
+ res.writeHead(403).end();
248
+ return;
249
+ }
250
+ const path = (req.url ?? "/").split("?")[0] ?? "/";
251
+ const navigation =
252
+ req.headers["sec-fetch-dest"] === "document" ||
253
+ req.headers["sec-fetch-dest"] === "iframe" ||
254
+ path === "/" ||
255
+ path === "/index.html";
256
+ if ((req.method === "GET" || req.method === "HEAD") && navigation) {
257
+ serveHtml(req, res).catch((error: unknown) => {
258
+ res.writeHead(500, { "content-type": "text/plain" }).end(String(error));
259
+ });
260
+ return;
261
+ }
262
+ vite.middlewares(req, res, () => {
263
+ // A deep link inside the artifact's routes gets its page (D57).
264
+ if (req.headers.accept?.includes("text/html")) {
265
+ serveHtml(req, res).catch(() => res.writeHead(500).end());
266
+ return;
267
+ }
268
+ res.writeHead(404).end();
269
+ });
270
+ });
271
+ http.on("upgrade", (req: IncomingMessage, socket: Duplex, head: Buffer) => {
272
+ if (!hasSecret(req.headers, request.secret)) {
273
+ socket.destroy();
274
+ return;
275
+ }
276
+ hmrServer.emit("upgrade", req, socket, head);
277
+ });
278
+ await new Promise<void>((done) => http.listen(0, "127.0.0.1", done));
279
+ const port = (http.address() as { port: number }).port;
280
+
281
+ // Changes in the mirror: Vite updates the client modules (HMR); rescan; write the entry again
282
+ // when the pages changed; rebuild the server bundle when the artifact has server code.
283
+ let running: Promise<void> = Promise.resolve();
284
+ const settle = async (changes: readonly DevChange[]): Promise<void> => {
285
+ const files = changes.map((change) => change.file);
286
+ changedAt = Date.now();
287
+ for (const change of changes)
288
+ vite.watcher.emit(change.kind, join(sourceDir, ...change.file.split("/")));
289
+ const before = { pages: pageShape(scan), server: serverShape(scan) };
290
+ scan = await scanArtifact(sourceDir);
291
+ const serverChanged = before.server !== serverShape(scan);
292
+ const pagesChanged = before.pages !== pageShape(scan);
293
+ if (pagesChanged || serverChanged) {
294
+ refreshServerModules();
295
+ await writeEntry();
296
+ // Vite watches nothing, so it hears of the rewritten entry from here: the route table
297
+ // (or the server stubs) it imports changed, and every page loads it again.
298
+ vite.watcher.emit("change", join(generated, "entry.js"));
299
+ if (serverChanged) vite.moduleGraph.invalidateAll();
300
+ }
301
+ if (pagesChanged && !serverChanged) vite.ws.send({ type: "full-reload" });
302
+ const hasServer = scan.serverModules.size > 0 || scan.hasLive || scan.unparsed.length > 0;
303
+ if (hasServer || serverChanged) {
304
+ // The server bundle is built again; only a bundle that changed restarts the worker and
305
+ // loads the pages again. A client edit stays a hot update.
306
+ const before = lastBundle;
307
+ const built = await buildServer();
308
+ if (!built.ok || serverChanged || lastBundle !== before) {
309
+ supervisor.notify(DEV_SERVER_NOTIFICATION, { build: built, files });
310
+ return;
311
+ }
312
+ }
313
+ supervisor.notify(DEV_UPDATE_NOTIFICATION, { files });
314
+ };
315
+ return {
316
+ ready: { port, build: firstBuild },
317
+ changed: (changes) => {
318
+ running = running.then(() => settle(changes)).catch(() => {});
319
+ return running;
320
+ },
321
+ reload: () => vite.ws.send({ type: "full-reload" }),
322
+ close: async () => {
323
+ await running;
324
+ http.closeAllConnections();
325
+ await new Promise<void>((done) => http.close(() => done()));
326
+ await vite.close();
327
+ },
328
+ };
329
+ }
330
+
331
+ /**
332
+ * Keeps React Fast Refresh working on the entry (D140 item 12): the entry exports its manifest
333
+ * (`export const artifact = defineArtifact(…)`, D51), and a module that exports anything but
334
+ * components can't be refreshed in place, so every edit of a single-file artifact would load the
335
+ * page again. In dev only, the `export` keyword of that one declaration becomes spaces (positions
336
+ * and source maps stay exact); nothing imports the manifest at run time, since Mostra reads it
337
+ * statically.
338
+ */
339
+ export function manifestExportPlugin(entryFile: string): Plugin {
340
+ return {
341
+ name: "mostra:dev-manifest-export",
342
+ enforce: "pre",
343
+ transform(code, id) {
344
+ if (id.split("?")[0] !== entryFile || !/\.[jt]sx$/.test(entryFile)) return null;
345
+ const parsed = parseSync(entryFile, code, {
346
+ lang: entryFile.endsWith(".tsx") ? "tsx" : "jsx",
347
+ });
348
+ if (parsed.errors.length > 0) return null;
349
+ for (const statement of parsed.program.body) {
350
+ if (statement.type !== "ExportNamedDeclaration") continue;
351
+ const declaration = statement.declaration;
352
+ if (declaration?.type !== "VariableDeclaration" || declaration.declarations.length !== 1)
353
+ continue;
354
+ const id = declaration.declarations[0]?.id;
355
+ if (id?.type !== "Identifier" || id.name !== "artifact") continue;
356
+ const blank = " ".repeat(declaration.start - statement.start);
357
+ return {
358
+ code: code.slice(0, statement.start) + blank + code.slice(declaration.start),
359
+ map: null,
360
+ };
361
+ }
362
+ return null;
363
+ },
364
+ };
365
+ }
366
+
367
+ /** A digest of the server bundle's files, to tell a rebuild that changed nothing. */
368
+ export async function bundleDigest(dir: string): Promise<string> {
369
+ const hash = createHash("sha256");
370
+ let names: string[];
371
+ try {
372
+ names = (await readdir(dir, { recursive: true })).sort();
373
+ } catch {
374
+ return "";
375
+ }
376
+ for (const name of names) {
377
+ if (name.endsWith(".map")) continue;
378
+ const text = await readFile(join(dir, name)).catch(() => undefined);
379
+ if (text === undefined) continue;
380
+ hash.update(name).update("\u0000").update(text).update("\u0000");
381
+ }
382
+ return hash.digest("hex");
383
+ }