Starting out all 3 written

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211/* The course's preload. Every panel runs with `node --require <this file>`, and every
   `node` a terminal panel starts gets it through NODE_OPTIONS. It is the scaffolding
   around a panel, kept out of the panel's own files so that line numbers in a stack
   trace are the line numbers you see on the page.

   It reads everything it needs from the environment and contains no path:

     COURSE_VENDOR_ROOT   the vendored node_modules (React, TypeScript, happy-dom)
     COURSE_SCRATCH       the directory the panel lives in
     COURSE_SIDE          a file the panel's warnings and build records are appended to
     COURSE_DOM           "1": give the panel a DOM (happy-dom)
     COURSE_ACT           "1": tell React it is running under act()
     NODE_ENV             "production" selects React's production build

   Eight steps, in this order. */
'use strict';

const fs = require('node:fs');
const path = require('node:path');
const util = require('node:util');
const net = require('node:net');
const nodeModule = require('node:module');
const { fileURLToPath } = require('node:url');

const VENDOR_ROOT = process.env.COURSE_VENDOR_ROOT;
const SCRATCH = process.env.COURSE_SCRATCH;
const SIDE = process.env.COURSE_SIDE;
if (!VENDOR_ROOT) throw new Error('course: COURSE_VENDOR_ROOT is not set');
if (!SCRATCH) throw new Error('course: COURSE_SCRATCH is not set');
if (!SIDE) throw new Error('course: COURSE_SIDE is not set');

/* One line of JSON per record. Synchronous, so a record written just before the
   process dies is still there. */
function record(level, text) {
  fs.appendFileSync(SIDE, JSON.stringify({ level, text }) + '\n');
}

const inside = (file, root) => file === root || file.startsWith(root + path.sep);

/* 1. Stack traces name the lines of the file as written, not of the compiled code. */
nodeModule.setSourceMapsSupport(true);

/* 2. Two hooks.
      resolve: nothing may be loaded from outside the vendored tree or the panel's own
               directory. Node's built-ins pass.
      load:    .jsx files are compiled by the vendored TypeScript, with an inline source
               map. Every .jsx file is an ES module. Everything else passes untouched. */
let ts = null;
let jsxOptions = null;

function compiler() {
  if (!ts) ts = nodeModule.createRequire(path.join(VENDOR_ROOT, 'noop.js'))('typescript');
  if (!jsxOptions) jsxOptions = JSON.parse(fs.readFileSync(path.join(__dirname, 'jsx.json'), 'utf8'));
  return ts;
}

function compileJsx(file, source) {
  const tsc = compiler();
  const name = path.basename(file);
  const options = process.env.NODE_ENV === 'production' ? jsxOptions.production : jsxOptions.development;
  const result = tsc.transpileModule(source, {
    fileName: name,
    compilerOptions: options,
    reportDiagnostics: true,
  });
  const diagnostics = result.diagnostics || [];
  if (diagnostics.length) {
    const first = diagnostics.reduce((a, b) => ((b.start || 0) < (a.start || 0) ? b : a));
    const line = first.file ? first.file.getLineAndCharacterOfPosition(first.start || 0).line + 1 : 1;
    const text = `${name}:${line}: ${tsc.flattenDiagnosticMessageText(first.messageText, ' ')}`;
    /* The record comes first: the verdict fails the panel on it, so a compile error
       can never pass as a panel that declared it would die with a SyntaxError. */
    record('jsx', text);
    const error = new SyntaxError(text);
    error.code = 'ERR_COURSE_JSX';
    throw error;
  }
  return result.outputText;
}

nodeModule.registerHooks({
  resolve(specifier, context, nextResolve) {
    const resolved = nextResolve(specifier, context);
    const url = resolved.url;
    if (!url || !url.startsWith('file:')) return resolved;
    const file = fileURLToPath(url);
    if (inside(file, VENDOR_ROOT) || inside(file, SCRATCH)) return resolved;
    /* Only names, never the directories they sit in: where this machine keeps node, npm
       or the project is nobody's business but its owner's. */
    const name = (p) => (path.isAbsolute(p) ? path.basename(p) : p);
    const error = new Error(`course: ${name(specifier)} resolved outside the vendored tree, to ${path.basename(file)}`);
    error.code = 'ERR_COURSE_UNVENDORED';
    throw error;
  },
  load(url, context, nextLoad) {
    if (url.startsWith('file:') && /\.jsx(?:[?#].*)?$/.test(url)) {
      const file = fileURLToPath(url.replace(/[?#].*$/, ''));
      const source = compileJsx(file, fs.readFileSync(file, 'utf8'));
      return { format: 'module', source, shortCircuit: true };
    }
    return nextLoad(url, context);
  },
});

/* 3. check(name, got, want): the assertion every panel uses. It prints "ok   name" or
      "FAIL name  got ..., want ...". Deep equality, so a Map is not {} and NaN is not
      null, which a JSON.stringify comparison would claim. */
const { isDeepStrictEqual, inspect } = require("node:util");

globalThis.check = function check(name, got, want) {
  const ok = isDeepStrictEqual(got, want);
  console.log((ok ? "ok   " : "FAIL ") + name + (ok ? "" : "  got " + inspect(got) + ", want " + inspect(want)));
};

/* 4. Warnings. console.error and console.warn still print exactly what they printed;
      each call is also recorded, so the build knows which warnings a panel produced. */
for (const level of ['error', 'warn']) {
  const original = console[level];
  console[level] = function (...args) {
    record(level, util.format(...args));
    return Reflect.apply(original, this, args);
  };
}

/* 5. A DOM, when the panel asks for one: a happy-dom window installed as the globals a
      browser would have, and an empty region to render into, available as `stage`. It
      loads no scripts, styles or frames. */
function defineGlobal(name, value) {
  Object.defineProperty(globalThis, name, { value, configurable: true, writable: true, enumerable: false });
}

if (process.env.COURSE_DOM === '1') {
  const { Window } = nodeModule.createRequire(path.join(VENDOR_ROOT, 'noop.js'))('happy-dom');
  const window = new Window({
    url: 'http://localhost/',
    settings: {
      disableJavaScriptEvaluation: true,
      disableJavaScriptFileLoading: true,
      disableCSSFileLoading: true,
      disableIframePageLoading: true,
    },
  });
  const names = [
    'window', 'document', 'navigator', 'Node', 'Element', 'Text', 'MutationObserver',
    'Event', 'MouseEvent', 'KeyboardEvent', 'InputEvent', 'FocusEvent', 'SubmitEvent', 'FormData',
    ...Object.getOwnPropertyNames(window).filter((n) => /^(?:HTML|SVG)\w*Element$/.test(n)),
  ];
  for (const name of names) {
    if (name === 'window') defineGlobal(name, window);
    else if (window[name] !== undefined) defineGlobal(name, window[name]);
  }
  defineGlobal('requestAnimationFrame', window.requestAnimationFrame.bind(window));
  defineGlobal('cancelAnimationFrame', window.cancelAnimationFrame.bind(window));

  const region = window.document.createElement('div');
  region.setAttribute('id', 'stage');
  region.setAttribute('role', 'region');
  region.setAttribute('aria-label', 'Rendered output');
  window.document.body.appendChild(region);
  defineGlobal('stage', region);

  if (process.env.COURSE_ACT === '1') globalThis.IS_REACT_ACT_ENVIRONMENT = true;

  /* 6. Clean up when the process ends through process.exit(). A timer the panel left
        running keeps the process alive, so it never reaches here: unmount your roots and
        clear your timers. */
  process.on('exit', () => {
    try { window.happyDOM.abort(); } catch { /* already closed */ }
    try { window.close(); } catch { /* already closed */ }
  });
}

/* 7. Servers listen on this machine only. The sandbox already stops anything leaving it;
      this stops a panel from listening on every interface. A Unix socket path is fine. */
const LOOPBACK = new Set(['127.0.0.1', 'localhost', '::1']);
const originalListen = net.Server.prototype.listen;

net.Server.prototype.listen = function listen(...args) {
  const first = args[0];
  let host;
  let socketPath = false;
  if (first !== null && typeof first === 'object') {
    if (typeof first.path === 'string') socketPath = true;
    else host = first.host;
  } else if (typeof first === 'string' && !/^\d+$/.test(first)) {
    socketPath = true;
  } else if (typeof args[1] === 'string') {
    host = args[1];
  }
  if (!socketPath && !LOOPBACK.has(host)) {
    const error = new Error(
      `course: listen on ${host === undefined ? 'every interface' : host} is refused; a panel's server listens on 127.0.0.1`,
    );
    error.code = 'ERR_COURSE_NOT_LOOPBACK';
    throw error;
  }
  return Reflect.apply(originalListen, this, args);
};

/* 8. Which React build ran. When the process ends, every React file that was loaded
      and evaluated is written down as "development: react/cjs/react.development.js" or
      "production: ...". The build compares that with the build the panel declared, so
      a panel cannot print a "production" badge while running the development build. */
const REACT_BUILD = /\/node_modules\/((?:react|react-dom|scheduler)\/cjs\/[^/]+\.(development|production)\.js)$/;

process.on('exit', () => {
  for (const [file, mod] of Object.entries(require.cache)) {
    const m = REACT_BUILD.exec(file);
    if (m && mod && mod.loaded === true) record('build', `${m[2]}: ${m[1]}`);
  }
});

The scaffolding every panel runs with, shown here once as a tool of the course and never as part of a panel. It is the file on disk, byte for byte, so it is the one that ran.

1
2
3
4
5
6(version 1)
(allow default)
(deny network-outbound)
(allow network-outbound (remote ip "localhost:*"))
(deny network-bind)
(allow network-bind (local ip "localhost:*"))

The profile every panel runs under, shown here once as a tool of the course. Apple has deprecated sandbox-exec but it still ships with macOS, and it is what makes "no network" a fact about the build and not a promise.

1
2
3
4npm create vite@latest my-app -- --template react
cd my-app
npm install
npm run dev

needs Vite and the npm registry, which this offline course never contacts. The panels above run the same React without them.