@mostra/sdk 0.4.0 → 0.6.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.
@@ -0,0 +1,187 @@
1
+ /**
2
+ * A Windows bundle's links (D153). An ordinary Windows user can't create symbolic links (that
3
+ * takes an administrator or Developer Mode), so a Windows archive holds none: its `files.json`
4
+ * lists each link, every one to a directory inside the bundle, and setup makes each a junction,
5
+ * which any user can create. A junction names its target by absolute path, so it is made at the
6
+ * bundle's real path, and a bundle moved since is set up again (`readSetup` compares the root
7
+ * its marker names).
8
+ *
9
+ * Nothing outside the bundle is ever touched: a listed link's path and target must stay inside
10
+ * it, every directory above a link must be a real directory (never a link), the target must be a
11
+ * directory, and what already sits at a link's path is replaced only when it is itself a link, or
12
+ * a real directory holding exactly the files and bytes of the link's target. That is what a copy
13
+ * made by a tool that follows junctions leaves (Explorer, `Copy-Item`, `robocopy` without `/SJ`,
14
+ * and a move to another drive, which is a copy), so such a copy is set up again; a directory
15
+ * holding anything else is refused and kept (Opus review of WP-W3, finding 4).
16
+ *
17
+ * Two setups of one bundle may run at once (a moved bundle met by two commands): each step
18
+ * tolerates the other's, and a link counts as made once it names its target, whoever made it
19
+ * (finding 5).
20
+ */
21
+ import {
22
+ lstat,
23
+ mkdir,
24
+ readdir,
25
+ readlink,
26
+ rm,
27
+ rmdir,
28
+ stat,
29
+ symlink,
30
+ unlink,
31
+ } from "node:fs/promises";
32
+ import { dirname, join, resolve } from "node:path";
33
+ import type { BundleFiles, BundleLinkEntry } from "@mostra/protocol";
34
+ import { hashFile, linkStaysInside, linkTarget, realOrNone, safeRelative } from "./tree.ts";
35
+
36
+ /** Why a link couldn't be made; the caller reports it as `MOSTRA_ENV_BUNDLE_INVALID`. */
37
+ export class LinkRefused extends Error {}
38
+
39
+ /** Whether `path` (an absolute path inside `root`) has only real directories above it. */
40
+ async function realParents(root: string, path: string): Promise<boolean> {
41
+ let dir = dirname(path);
42
+ const chain: string[] = [];
43
+ while (dir.length > root.length) {
44
+ chain.unshift(dir);
45
+ dir = dirname(dir);
46
+ }
47
+ for (const parent of chain) {
48
+ const info = await lstat(parent).catch(() => undefined);
49
+ if (info === undefined) {
50
+ await mkdir(parent);
51
+ continue;
52
+ }
53
+ if (!info.isDirectory() || info.isSymbolicLink()) return false;
54
+ }
55
+ return true;
56
+ }
57
+
58
+ /**
59
+ * Makes every link `manifest` lists as a junction under `root`, which must be the bundle's real
60
+ * path (`realpath.native`). A link that already names its target is kept; one that names another
61
+ * (the bundle moved) is replaced. Throws {@link LinkRefused} for a link the manifest can't have.
62
+ */
63
+ export async function makeJunctions(root: string, manifest: BundleFiles): Promise<void> {
64
+ // A link's target may lie behind another link (`node_modules/x` through a scope's link), so a
65
+ // link whose target isn't there yet waits for the next round; a round that makes nothing ends.
66
+ const realRoot = realOrNone(root);
67
+ let waiting = [...manifest.links].sort((a, b) => a.path.length - b.path.length);
68
+ while (waiting.length > 0) {
69
+ const later: typeof waiting = [];
70
+ for (const link of waiting) {
71
+ if (!(await makeJunction(root, link, realRoot))) later.push(link);
72
+ }
73
+ if (later.length === waiting.length) {
74
+ const first = later[0] as BundleLinkEntry;
75
+ throw new LinkRefused(`${first.path} links to ${first.target}, which is no directory.`);
76
+ }
77
+ waiting = later;
78
+ }
79
+ }
80
+
81
+ /** Makes one link; `false` when its target isn't a directory (yet). */
82
+ async function makeJunction(
83
+ root: string,
84
+ link: BundleLinkEntry,
85
+ realRoot: string | undefined,
86
+ ): Promise<boolean> {
87
+ if (!safeRelative(link.path) || !linkStaysInside(root, link.path, link.target)) {
88
+ throw new LinkRefused(`${link.path} links outside the bundle (${link.target}).`);
89
+ }
90
+ const at = join(root, link.path);
91
+ const target = resolve(dirname(at), link.target);
92
+ if (!(await realParents(root, at))) {
93
+ throw new LinkRefused(`${link.path} sits below a link or a file.`);
94
+ }
95
+ const kind = await stat(target).catch(() => undefined);
96
+ if (kind === undefined || !kind.isDirectory()) {
97
+ return names(root, link, at, realRoot);
98
+ }
99
+ // Another setup of this bundle may be making the same links (finding 5). Each attempt reads the
100
+ // state afresh and accepts a link that names its target, whoever made it; a setup removes only
101
+ // what doesn't, and always makes the link right after, while nothing ever makes a stale one, so
102
+ // the link names its target once both stop.
103
+ let last: unknown;
104
+ for (let attempt = 0; attempt < 20; attempt++) {
105
+ if (await names(root, link, at, realRoot)) return true;
106
+ const current = await lstat(at).catch(() => undefined);
107
+ try {
108
+ if (current?.isSymbolicLink()) {
109
+ // A junction is a directory to Windows: `rmdir` removes the link, never what it names.
110
+ await rmdir(at).catch(async (error: NodeJS.ErrnoException) => {
111
+ if (error.code !== "ENOENT") await unlink(at);
112
+ });
113
+ } else if (current !== undefined) {
114
+ if (!current.isDirectory() || !(await sameTree(at, target))) {
115
+ // Read again: another setup may have replaced the copy while it was compared.
116
+ if (await names(root, link, at, realRoot)) return true;
117
+ const now = await lstat(at).catch(() => undefined);
118
+ if (now !== undefined && !now.isSymbolicLink()) {
119
+ throw new LinkRefused(
120
+ `${link.path} is a file or directory where the bundle has a link, and it isn't a copy of ${link.target}.`,
121
+ );
122
+ }
123
+ continue;
124
+ }
125
+ // A copy of the target: no link inside it (`sameTree` refuses one), so nothing outside it.
126
+ await rm(at, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
127
+ }
128
+ await symlink(target, at, "junction");
129
+ } catch (error) {
130
+ if (error instanceof LinkRefused) throw error;
131
+ last = error; // another setup's step came between: the next attempt reads the state again
132
+ }
133
+ }
134
+ if (await names(root, link, at, realRoot)) return true;
135
+ throw new LinkRefused(
136
+ `${link.path} couldn't be made as a junction to ${link.target}${last ? `: ${(last as Error).message}` : ""}.`,
137
+ );
138
+ }
139
+
140
+ /** Whether the link at `at` exists and names the manifest's target. */
141
+ async function names(
142
+ root: string,
143
+ link: BundleLinkEntry,
144
+ at: string,
145
+ realRoot: string | undefined,
146
+ ): Promise<boolean> {
147
+ const info = await lstat(at).catch(() => undefined);
148
+ if (info === undefined || !info.isSymbolicLink()) return false;
149
+ const written = await readlink(at).catch(() => undefined);
150
+ return written !== undefined && linkTarget(root, link.path, written, realRoot) === link.target;
151
+ }
152
+
153
+ /**
154
+ * Whether the real directory `copy` holds exactly what `original` holds: the same names, files of
155
+ * the same bytes, and directories alike all the way down. A link anywhere in the copy, or an entry
156
+ * of any other kind, makes it no copy.
157
+ */
158
+ async function sameTree(copy: string, original: string): Promise<boolean> {
159
+ const [mine, theirs] = await Promise.all([
160
+ readdir(copy, { withFileTypes: true }).catch(() => undefined),
161
+ readdir(original, { withFileTypes: true }).catch(() => undefined),
162
+ ]);
163
+ if (mine === undefined || theirs === undefined || mine.length !== theirs.length) return false;
164
+ const byName = new Map(theirs.map((entry) => [entry.name, entry]));
165
+ for (const entry of mine) {
166
+ const other = byName.get(entry.name);
167
+ if (other === undefined || entry.isSymbolicLink()) return false;
168
+ const a = join(copy, entry.name);
169
+ const b = join(original, entry.name);
170
+ if (entry.isDirectory()) {
171
+ // The original may reach a directory through a link (a junction made a moment ago).
172
+ if (!(await stat(b).catch(() => undefined))?.isDirectory()) return false;
173
+ if (!(await sameTree(a, b))) return false;
174
+ } else if (entry.isFile()) {
175
+ if (!(other.isFile() || other.isSymbolicLink()) || !(await sameBytes(a, b))) return false;
176
+ } else return false;
177
+ }
178
+ return true;
179
+ }
180
+
181
+ /** Whether two files hold the same bytes (streamed, so a large program isn't held in memory). */
182
+ async function sameBytes(a: string, b: string): Promise<boolean> {
183
+ const [sa, sb] = await Promise.all([stat(a), stat(b)]).catch(() => [undefined, undefined]);
184
+ if (sa === undefined || sb === undefined || !sb.isFile() || sa.size !== sb.size) return false;
185
+ const [ha, hb] = await Promise.all([hashFile(a), hashFile(b)]);
186
+ return ha.sha256 === hb.sha256;
187
+ }
@@ -6,6 +6,7 @@
6
6
  * hand, and for the Rust crate (WP-12), so there is one implementation of what "ready" means.
7
7
  */
8
8
  import { spawn } from "node:child_process";
9
+ import { realpathSync } from "node:fs";
9
10
  import { readFile, rename, rm, writeFile } from "node:fs/promises";
10
11
  import { join } from "node:path";
11
12
  import {
@@ -14,9 +15,12 @@ import {
14
15
  BundleInfo,
15
16
  BundleSetup,
16
17
  createDiagnostic,
18
+ isWindowsBundle,
17
19
  RpcError,
18
20
  } from "@mostra/protocol";
21
+ import { childEnvironment } from "../environment.ts";
19
22
  import { scrubUrls } from "./download.ts";
23
+ import { LinkRefused, makeJunctions } from "./links.ts";
20
24
  import { checkTree, hashFile, safeRelative } from "./tree.ts";
21
25
 
22
26
  /** The environment setup reads. */
@@ -90,14 +94,28 @@ export async function readBundle(root: string): Promise<Bundle> {
90
94
  return { root, info };
91
95
  }
92
96
 
93
- /** The setup marker, when it describes exactly this bundle. */
97
+ /**
98
+ * The bundle's real path: links followed, Windows' short names written out, the case as the file
99
+ * system keeps it. A Windows bundle's junctions point into it, and its marker names it.
100
+ */
101
+ export function realRoot(root: string): string {
102
+ return realpathSync.native(root);
103
+ }
104
+
105
+ /**
106
+ * The setup marker, when it describes exactly this bundle. A Windows bundle's marker must also
107
+ * name the root it sits at now: its junctions point into the root setup ran at, so a bundle moved
108
+ * or copied since is set up again, which makes them afresh (D153).
109
+ */
94
110
  export async function readSetup(bundle: Bundle): Promise<BundleSetup | undefined> {
95
111
  try {
96
112
  const marker = BundleSetup.parse(
97
113
  JSON.parse(await readFile(join(bundle.root, BUNDLE_SETUP_MARKER), "utf8")),
98
114
  );
99
115
  const { info } = bundle;
100
- return marker.files === info.files.sha256 &&
116
+ const here = isWindowsBundle(info.platform) ? marker.root === realRoot(bundle.root) : true;
117
+ return here &&
118
+ marker.files === info.files.sha256 &&
101
119
  marker.version === info.version &&
102
120
  marker.platform === info.platform &&
103
121
  marker.browser.revision === info.browser.revision
@@ -120,8 +138,8 @@ export function setupExtras(path: string): boolean {
120
138
  );
121
139
  }
122
140
 
123
- /** Checks the bundle's files; throws `MOSTRA_ENV_BUNDLE_INVALID` naming what differs. */
124
- export async function checkFiles(bundle: Bundle): Promise<void> {
141
+ /** The bundle's `files.json`, once its SHA-256 is the one `bundle.json` pins. */
142
+ async function readManifest(bundle: Bundle): Promise<BundleFiles> {
125
143
  const { root, info } = bundle;
126
144
  const listing = join(root, info.files.path);
127
145
  const { sha256 } = await hashFile(listing).catch(() => ({ sha256: "" }));
@@ -130,7 +148,39 @@ export async function checkFiles(bundle: Bundle): Promise<void> {
130
148
  }
131
149
  const manifest = BundleFiles.safeParse(JSON.parse(await readFile(listing, "utf8")));
132
150
  if (!manifest.success) throw invalid(`${info.files.path} isn't a bundle's file list.`);
133
- const problems = await checkTree(root, manifest.data, { allowExtra: setupExtras });
151
+ return manifest.data;
152
+ }
153
+
154
+ /**
155
+ * Makes a Windows bundle's links, each a junction at the bundle's real path (D153); nothing for
156
+ * any other bundle, whose archive carries its links. Throws `MOSTRA_ENV_BUNDLE_INVALID` for a link
157
+ * the bundle can't have.
158
+ */
159
+ export async function makeLinks(bundle: Bundle, read?: BundleFiles): Promise<void> {
160
+ if (!isWindowsBundle(bundle.info.platform)) return;
161
+ const manifest = read ?? (await readManifest(bundle));
162
+ try {
163
+ await makeJunctions(realRoot(bundle.root), manifest);
164
+ } catch (error) {
165
+ if (error instanceof LinkRefused) throw invalid(`The runtime bundle's links: ${error.message}`);
166
+ throw error;
167
+ }
168
+ }
169
+
170
+ /**
171
+ * Checks the bundle's files; throws `MOSTRA_ENV_BUNDLE_INVALID` naming what differs. With
172
+ * `links: false` the files alone are checked (a Windows bundle before `makeLinks` made its junctions).
173
+ */
174
+ export async function checkFiles(
175
+ bundle: Bundle,
176
+ options: { readonly links?: boolean; readonly manifest?: BundleFiles } = {},
177
+ ): Promise<void> {
178
+ const { root, info } = bundle;
179
+ const manifest = options.manifest ?? (await readManifest(bundle));
180
+ const problems = await checkTree(root, manifest, {
181
+ allowExtra: setupExtras,
182
+ links: options.links ?? true,
183
+ });
134
184
  if (problems.length > 0) {
135
185
  throw invalid(
136
186
  `Mostra ${info.version}'s runtime bundle for ${info.platform} differs from its file list: ${problems.join("; ")}.`,
@@ -151,13 +201,13 @@ export async function checkBrowser(bundle: Bundle): Promise<readonly string[]> {
151
201
 
152
202
  /** The environment the browser install runs in: proxies and Playwright's mirror pass through. */
153
203
  function installEnvironment(bundle: Bundle, env: Environment): NodeJS.ProcessEnv {
154
- const out: NodeJS.ProcessEnv = {};
204
+ const out: Record<string, string> = {};
155
205
  for (const [name, value] of Object.entries(env)) {
156
206
  if (value !== undefined && !name.startsWith("MOSTRA_") && name !== "PLAYWRIGHT_BROWSERS_PATH")
157
207
  out[name] = value;
158
208
  }
159
209
  out["PLAYWRIGHT_BROWSERS_PATH"] = browsersDir(bundle.root);
160
- return out;
210
+ return childEnvironment(out);
161
211
  }
162
212
 
163
213
  /** The variables whose URLs may carry credentials the browser's fetch uses. */
@@ -202,6 +252,7 @@ async function installBrowser(bundle: Bundle, options: SetupOptions): Promise<vo
202
252
  cwd: root,
203
253
  env: installEnvironment(bundle, options.env ?? process.env),
204
254
  stdio: ["ignore", "pipe", "pipe"],
255
+ windowsHide: true,
205
256
  ...(options.signal ? { signal: options.signal } : {}),
206
257
  timeout: 15 * 60_000,
207
258
  },
@@ -239,9 +290,16 @@ async function installBrowser(bundle: Bundle, options: SetupOptions): Promise<vo
239
290
  export async function setupBundle(root: string, options: SetupOptions = {}): Promise<BundleSetup> {
240
291
  const env = options.env ?? process.env;
241
292
  const bundle = await readBundle(root);
293
+ // A Windows bundle's junctions are made where it sits now, each read back as it is made; a
294
+ // tree checked a moment ago (`filesChecked`, before the cache's rename) needs nothing more.
295
+ // `files.json` is read and checked against its pin once, for both steps (Opus review of
296
+ // WP-W3, finding 9): it lists every file of the bundle and is large.
297
+ const windows = isWindowsBundle(bundle.info.platform);
298
+ const manifest = windows || !options.filesChecked ? await readManifest(bundle) : undefined;
299
+ await makeLinks(bundle, manifest);
242
300
  if (!options.filesChecked) {
243
301
  options.onStep?.("files");
244
- await checkFiles(bundle);
302
+ await checkFiles(bundle, manifest ? { manifest } : {});
245
303
  }
246
304
  options.onStep?.("browser");
247
305
  if ((await checkBrowser(bundle)).length > 0) {
@@ -270,6 +328,7 @@ export async function setupBundle(root: string, options: SetupOptions = {}): Pro
270
328
  files: bundle.info.files.sha256,
271
329
  browser: { revision: bundle.info.browser.revision },
272
330
  at: new Date().toISOString(),
331
+ root: realRoot(root),
273
332
  };
274
333
  const temporary = join(root, `${BUNDLE_SETUP_MARKER}.tmp-${process.pid}`);
275
334
  await writeFile(temporary, `${JSON.stringify(marker, null, 2)}\n`);
@@ -2,13 +2,65 @@
2
2
  * A bundle's files against its manifest (RT-01): one walk that both writes `files.json` (the
3
3
  * assembler) and checks an extracted bundle against it (setup), so the two can't disagree about
4
4
  * what counts. Links must stay inside the bundle; nothing may be missing, changed or extra.
5
+ *
6
+ * On Windows (D153) a link is read as the relative, `/`-separated path from its directory to its
7
+ * target, whether it is a symbolic link (`..\\x`, as pnpm makes them for an administrator) or a
8
+ * junction (an absolute target, as setup makes them for everyone), so `files.json` reads the same
9
+ * on every system; and no file is executable, since Windows keeps no execute bit (D150 item 8).
5
10
  */
6
11
  import { createHash } from "node:crypto";
7
- import { createReadStream } from "node:fs";
12
+ import { createReadStream, realpathSync } from "node:fs";
8
13
  import { lstat, readdir, readlink } from "node:fs/promises";
9
- import { dirname, isAbsolute, join, resolve, sep } from "node:path";
14
+ import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
10
15
  import type { BundleFileEntry, BundleFiles, BundleLinkEntry } from "@mostra/protocol";
11
16
 
17
+ /** Whether this process runs on Windows, whose links and modes the walk reads its own way. */
18
+ const WINDOWS = process.platform === "win32";
19
+
20
+ /**
21
+ * A link's target as the manifest spells it: relative to the link's directory, `/`-separated.
22
+ * POSIX targets are kept exactly as written; a Windows junction's absolute target, and a Windows
23
+ * symbolic link's `\\`-separated one, are rewritten into that form. `realRoot` is `root`'s real
24
+ * path, which a caller reading many links computes once (Opus review of WP-W3, finding 8).
25
+ */
26
+ export function linkTarget(
27
+ root: string,
28
+ path: string,
29
+ written: string,
30
+ realRoot: string | undefined = realOrNone(root),
31
+ ): string {
32
+ if (!WINDOWS) return written;
33
+ // A junction's target may carry the `\\?\` prefix of Windows' own namespace.
34
+ const plain = written.startsWith("\\\\?\\") ? written.slice(4) : written;
35
+ if (!isAbsolute(plain)) return plain.split(sep).join("/");
36
+ // A junction stores an absolute path, spelled as whoever made it spelled the bundle's root:
37
+ // setup uses the real path, while `root` may be another spelling of it (an 8.3 short name such
38
+ // as `RUNNER~1`, another case). Each spelling of the link's directory is tried against the
39
+ // same spelling of the root, so neither reads as a detour out of the bundle; Windows compares
40
+ // without case.
41
+ const given = resolve(root);
42
+ const dir = dirname(join(given, path));
43
+ const spellings: [string, string][] = [[given, dir]];
44
+ // A root that doesn't exist holds no junction; the lexical form then reports the mismatch.
45
+ if (realRoot !== undefined) spellings.push([realRoot, join(realRoot, relative(given, dir))]);
46
+ const lower = plain.toLowerCase();
47
+ for (const [base, from] of spellings) {
48
+ if (lower === base.toLowerCase() || lower.startsWith(`${base.toLowerCase()}${sep}`))
49
+ return relative(from, plain).split(sep).join("/");
50
+ }
51
+ return relative(dir, plain).split(sep).join("/");
52
+ }
53
+
54
+ /** `root`'s real path on Windows (where junction targets need it), or `undefined`. */
55
+ export function realOrNone(root: string): string | undefined {
56
+ if (!WINDOWS) return undefined;
57
+ try {
58
+ return realpathSync.native(resolve(root));
59
+ } catch {
60
+ return undefined;
61
+ }
62
+ }
63
+
12
64
  /** The SHA-256 and size of one file, read as a stream. */
13
65
  export async function hashFile(path: string): Promise<{ sha256: string; size: number }> {
14
66
  const hash = createHash("sha256");
@@ -29,6 +81,7 @@ type Walked =
29
81
  /** Every file and link under `root`, sorted by path, skipping `exclude`d paths (and below). */
30
82
  async function walk(root: string, exclude: (path: string) => boolean): Promise<Walked[]> {
31
83
  const out: Walked[] = [];
84
+ const realRoot = realOrNone(root);
32
85
  const visit = async (dir: string): Promise<void> => {
33
86
  const entries = await readdir(join(root, dir), { withFileTypes: true });
34
87
  for (const entry of entries) {
@@ -36,10 +89,12 @@ async function walk(root: string, exclude: (path: string) => boolean): Promise<W
36
89
  if (exclude(path)) continue;
37
90
  if (entry.isDirectory()) await visit(path);
38
91
  else if (entry.isSymbolicLink()) {
39
- out.push({ kind: "link", path, target: await readlink(join(root, path)) });
92
+ const written = await readlink(join(root, path));
93
+ out.push({ kind: "link", path, target: linkTarget(root, path, written, realRoot) });
40
94
  } else if (entry.isFile()) {
41
- const stats = await lstat(join(root, path));
42
- out.push({ kind: "file", path, executable: (stats.mode & 0o100) !== 0 });
95
+ // Windows keeps no execute bit: Node.js reports one there for every file it can read.
96
+ const executable = WINDOWS ? false : ((await lstat(join(root, path))).mode & 0o100) !== 0;
97
+ out.push({ kind: "file", path, executable });
43
98
  } else out.push({ kind: "other", path });
44
99
  }
45
100
  };
@@ -67,7 +122,7 @@ async function mapLimit<T, R>(
67
122
 
68
123
  /** Whether a link's target is relative and resolves inside `root`. */
69
124
  export function linkStaysInside(root: string, path: string, target: string): boolean {
70
- if (isAbsolute(target)) return false;
125
+ if (isAbsolute(target) || /[\\:\0]/.test(target)) return false;
71
126
  const base = resolve(root);
72
127
  const resolved = resolve(base, dirname(path), target);
73
128
  return resolved === base || resolved.startsWith(base + sep);
@@ -118,10 +173,19 @@ export type TreeProblems = readonly string[];
118
173
  export async function checkTree(
119
174
  root: string,
120
175
  manifest: BundleFiles,
121
- options: { readonly allowExtra?: (path: string) => boolean; readonly limit?: number } = {},
176
+ options: {
177
+ readonly allowExtra?: (path: string) => boolean;
178
+ readonly limit?: number;
179
+ /**
180
+ * Whether the links are checked; `false` checks the files alone and lets each listed link be
181
+ * there or not, for a Windows bundle whose junctions setup makes after a rename (D153).
182
+ */
183
+ readonly links?: boolean;
184
+ } = {},
122
185
  ): Promise<TreeProblems> {
123
186
  const limit = options.limit ?? 20;
124
187
  const allowExtra = options.allowExtra ?? (() => false);
188
+ const checkLinks = options.links ?? true;
125
189
  const problems: string[] = [];
126
190
  const add = (problem: string): void => {
127
191
  if (problems.length < limit) problems.push(problem);
@@ -153,7 +217,7 @@ export async function checkTree(
153
217
  if (!allowExtra(entry.path)) add(`${entry.path}: not in the bundle's file list`);
154
218
  }
155
219
  }
156
- for (const [path, link] of expectedLinks) {
220
+ for (const [path, link] of checkLinks ? expectedLinks : new Map<string, BundleLinkEntry>()) {
157
221
  const actual = found.get(path);
158
222
  if (actual?.kind !== "link") add(`${path}: missing link`);
159
223
  else if (actual.target !== link.target)
@@ -0,0 +1,59 @@
1
+ /**
2
+ * The environment of a process the SDK starts (the instance, the browser's fetch). A host may
3
+ * give an environment of its own (`createMostra`'s `env`), and on Windows a program starts only
4
+ * with the system's own variables: Node.js aborts without `SystemRoot`, which its random-number
5
+ * source needs. So on Windows each of them this process has is added where the host's environment
6
+ * lacks it, matched without case as Windows matches names (D150 item 9, D153). They name the
7
+ * system's own folders and nothing of the user's secrets. Elsewhere the environment is the host's,
8
+ * as it is.
9
+ */
10
+ /** An environment as a host gives it. */
11
+ type Environment = Readonly<Record<string, string | undefined>>;
12
+
13
+ /** What Windows gives every program, which a child of the SDK keeps (D150 item 9). */
14
+ const WINDOWS_SYSTEM_VARIABLES: readonly string[] = [
15
+ "SystemRoot",
16
+ "SystemDrive",
17
+ "windir",
18
+ "ComSpec",
19
+ "PATHEXT",
20
+ "TEMP",
21
+ "TMP",
22
+ "USERPROFILE",
23
+ "HOMEDRIVE",
24
+ "HOMEPATH",
25
+ "APPDATA",
26
+ "LOCALAPPDATA",
27
+ "ProgramData",
28
+ "ProgramFiles",
29
+ "ProgramFiles(x86)",
30
+ "ProgramW6432",
31
+ "CommonProgramFiles",
32
+ "CommonProgramFiles(x86)",
33
+ "CommonProgramW6432",
34
+ "USERNAME",
35
+ "USERDOMAIN",
36
+ "COMPUTERNAME",
37
+ "OS",
38
+ "NUMBER_OF_PROCESSORS",
39
+ "PROCESSOR_ARCHITECTURE",
40
+ "PROCESSOR_IDENTIFIER",
41
+ ];
42
+
43
+ /** `env` for a child process: on Windows with the system's own variables this process has. */
44
+ export function childEnvironment(
45
+ env: Environment,
46
+ options: { readonly platform?: string; readonly own?: Environment } = {},
47
+ ): NodeJS.ProcessEnv {
48
+ const out: NodeJS.ProcessEnv = {};
49
+ for (const [name, value] of Object.entries(env)) if (value !== undefined) out[name] = value;
50
+ if ((options.platform ?? process.platform) !== "win32") return out;
51
+ const own = options.own ?? process.env;
52
+ const present = new Set(Object.keys(out).map((name) => name.toUpperCase()));
53
+ for (const name of WINDOWS_SYSTEM_VARIABLES) {
54
+ if (present.has(name.toUpperCase())) continue;
55
+ const found = Object.entries(own).find(([key]) => key.toUpperCase() === name.toUpperCase());
56
+ if (found?.[1] !== undefined) out[found[0]] = found[1];
57
+ }
58
+ return out;
59
+ }
package/src/events.ts CHANGED
@@ -17,6 +17,7 @@ import {
17
17
  eventsUnsubscribeMethod,
18
18
  type MethodDefinition,
19
19
  RpcError,
20
+ receivable,
20
21
  } from "@mostra/protocol";
21
22
 
22
23
  /** One page of events. */
@@ -109,7 +110,8 @@ class EventStream implements AsyncIterator<EventPage> {
109
110
  }
110
111
 
111
112
  #receive(params: unknown): void {
112
- const parsed = EventsNotifyParams.safeParse(params);
113
+ // Events of types a newer instance added arrive too, never dropping their page (#45).
114
+ const parsed = receivable(EventsNotifyParams).safeParse(params);
113
115
  if (!parsed.success) return;
114
116
  if (parsed.data.subscriptionId !== this.#subscription) {
115
117
  this.#early?.push(parsed.data);
package/src/index.ts CHANGED
@@ -42,7 +42,7 @@ export {
42
42
  safeRelative,
43
43
  type TreeProblems,
44
44
  } from "./bundle/tree.ts";
45
- export { type ControlOptions, connectControl } from "./control.ts";
45
+ export { type ControlOptions, connectControl, windowsHelper } from "./control.ts";
46
46
  export type { EventPage, EventStreamOptions } from "./events.ts";
47
47
  export {
48
48
  type ArtifactInput,
package/src/mostra.ts CHANGED
@@ -59,6 +59,7 @@ import {
59
59
  type ResultsMarkdown,
60
60
  RpcError,
61
61
  RpcPeer,
62
+ receivable,
62
63
  resultsGetMethod,
63
64
  type SourceRef,
64
65
  type StateGetResult,
@@ -81,6 +82,7 @@ import {
81
82
  } from "@mostra/protocol";
82
83
  import type { InstallProgress } from "./bundle/cache.ts";
83
84
  import type { Environment } from "./bundle/setup.ts";
85
+ import { childEnvironment } from "./environment.ts";
84
86
  import { type EventPage, type EventStreamOptions, openEventStream } from "./events.ts";
85
87
  import { type Runtime, resolveRuntime } from "./runtime.ts";
86
88
  import { sdkVersion } from "./version.ts";
@@ -337,7 +339,11 @@ function portNames(ports: Ports): PortName[] {
337
339
  return names;
338
340
  }
339
341
 
340
- /** Ends the child: stdin closed, then SIGTERM after `graceMs`, then SIGKILL after 5 s more. */
342
+ /**
343
+ * Ends the child: stdin closed (which stops it, D87), then SIGTERM after `graceMs`, then SIGKILL
344
+ * after 5 s more. Windows has no signals between processes (D150 item 6): there the first of
345
+ * them ends the process at once.
346
+ */
341
347
  function stopChild(
342
348
  child: ChildProcess,
343
349
  exited: Promise<InstanceExit>,
@@ -395,7 +401,10 @@ export async function createMostra(options: MostraOptions): Promise<Mostra> {
395
401
  if (options.urlHost !== undefined) args.push("--url-host", options.urlHost);
396
402
  const child = spawn(runtime.node, args, {
397
403
  stdio: ["pipe", "pipe", "pipe"],
398
- env: env as NodeJS.ProcessEnv,
404
+ // The host's environment, which on Windows keeps the system's own variables (D153).
405
+ env: childEnvironment(env),
406
+ // A Windows host with no console of its own (a desktop app) opens no window for its instance.
407
+ windowsHide: true,
399
408
  });
400
409
  const logTail: string[] = [];
401
410
  const exited = new Promise<InstanceExit>((done) => {
@@ -436,7 +445,9 @@ export async function createMostra(options: MostraOptions): Promise<Mostra> {
436
445
  -32601,
437
446
  );
438
447
  }
439
- const parsed = definition.params.safeParse(params);
448
+ // A newer instance may send enum values and union members this host's schemas don't
449
+ // name yet (#45): the port's handler meets them, as it meets any value it can't act on.
450
+ const parsed = receivable(definition.params).safeParse(params);
440
451
  if (!parsed.success) {
441
452
  throw new RpcError(
442
453
  createDiagnostic("MOSTRA_HOST_INVALID_PARAMS", {
package/src/platform.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  /**
2
- * Which runtime bundle this machine takes (RT-01, D35): one per operating system and architecture
3
- * of v1, glibc only on Linux. Anything else fails closed before a download starts.
2
+ * Which runtime bundle this machine takes (RT-01, RT-12, D35, D146): one per operating system and
3
+ * architecture of v1 (macOS, glibc Linux and Windows, each on x64 and arm64). Anything else fails
4
+ * closed before a download starts.
4
5
  */
5
6
  import {
6
7
  BUNDLE_PLATFORMS,
@@ -56,21 +57,21 @@ export function currentPlatform(): PlatformFacts {
56
57
  }
57
58
 
58
59
  /**
59
- * The bundle platform for these facts. Throws `MOSTRA_PLATFORM_UNSUPPORTED` for Windows, other
60
- * architectures and Linux without glibc, whose libraries the bundle's Node.js and browser need.
60
+ * The bundle platform for these facts. Throws `MOSTRA_PLATFORM_UNSUPPORTED` for other systems and
61
+ * architectures and for Linux without glibc, whose libraries the bundle's Node.js and browser need.
61
62
  */
62
63
  export function bundlePlatform(facts: PlatformFacts = currentPlatform()): BundlePlatform {
63
64
  const name = `${facts.platform}-${facts.arch}`;
64
65
  const known = (BUNDLE_PLATFORMS as readonly string[]).includes(name);
65
66
  if (known && facts.platform === "linux" && facts.glibc === undefined) {
66
67
  throw unsupported(
67
- `Mostra's Linux bundle needs glibc, and this system has none (musl, as on Alpine Linux); it supports macOS and glibc-based Linux on x64 and arm64.`,
68
+ `Mostra's Linux bundle needs glibc, and this system has none (musl, as on Alpine Linux); it supports macOS, glibc-based Linux and Windows on x64 and arm64.`,
68
69
  );
69
70
  }
70
71
  if (!known) {
71
72
  const label = facts.platform === "win32" ? `Windows (${name})` : name;
72
73
  throw unsupported(
73
- `Mostra doesn't run on ${label}; it supports macOS and Linux on x64 and arm64.`,
74
+ `Mostra doesn't run on ${label}; it supports macOS, Linux and Windows on x64 and arm64.`,
74
75
  );
75
76
  }
76
77
  return name as BundlePlatform;
package/src/runtime.ts CHANGED
@@ -11,7 +11,7 @@
11
11
  * Anything a bundle supplies is checked first: its setup marker must match it, or setup runs.
12
12
  */
13
13
  import { existsSync, readFileSync } from "node:fs";
14
- import { join, resolve, sep } from "node:path";
14
+ import { join, resolve } from "node:path";
15
15
  import { BundlePins, createDiagnostic, RpcError } from "@mostra/protocol";
16
16
  import { type InstallProgress, installPinned } from "./bundle/cache.ts";
17
17
  import {
@@ -61,7 +61,8 @@ export interface RuntimeOptions {
61
61
  */
62
62
  export function pinsFile(env: Environment, root: string): string {
63
63
  const override = env["MOSTRA_TEST_BUNDLE_PINS"];
64
- const installed = root.split(sep).includes("node_modules");
64
+ // Either separator: a path spelled with `/` on Windows is still inside `node_modules`.
65
+ const installed = root.split(/[\\/]/).includes("node_modules");
65
66
  return override && !installed ? override : join(root, "dist", "bundles.json");
66
67
  }
67
68