@mosetta/cli 0.0.0-stage → 0.0.9

package/src/deploy.mjs

@@ -0,0 +1,154 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { contentTypeOf, release, ReleaseRefused } from '@mosetta/build/release';
+import { importServer } from './serverPackage.mjs';
+import { sectionLog } from './log.mjs';
+
+const require = createRequire(import.meta.url);
+
+// `mosetta deploy`: the built distribution goes to the project's stores by the provider
+// registry — public code to the CDN store, private code to the private store, and (on request)
+// the content seed to the content store. The registry is the same file the Worker gets as its
+// PROVIDERS secret: one description of the project's stores for both sides. No platform API is
+// involved — every store is reached through its provider handle, so a self-hosted S3 deploys the
+// same way as R2. The code goes up by the release rules every publisher runs (@mosetta/build/release):
+// a deployed version never changes, the catalogs only grow, and two deploys at once cannot drop
+// each other's entries.
+
+function walk(dir, base = dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) walk(p, base, out);
+    else if (entry.isFile()) out.push({ file: p, key: path.relative(base, p).split(path.sep).join('/') });
+  }
+  return out;
+}
+
+/** the built distribution as a release reads it: both catalogs, every key, the bytes by key */
+export function builtDistribution(dist) {
+  const side = (name) => {
+    const files = walk(path.join(dist, name));
+    return { catalog: JSON.parse(fs.readFileSync(path.join(dist, name, 'modules.json'), 'utf8')), keys: files.map((f) => f.key) };
+  };
+  const pub = side('public');
+  const priv = side('private');
+  return {
+    catalogs: { public: pub.catalog, private: priv.catalog },
+    files: { public: pub.keys, private: priv.keys },
+    async read(name, key) {
+      const file = path.join(dist, name, ...key.split('/'));
+      return fs.existsSync(file) ? new Uint8Array(fs.readFileSync(file)) : null;
+    },
+  };
+}
+
+const CONCURRENCY = 8;
+
+async function uploadAll(handle, files, { log, existing = null, label }) {
+  let done = 0;
+  let skipped = 0;
+  const queue = [...files];
+  const worker = async () => {
+    for (let item = queue.shift(); item; item = queue.shift()) {
+      if (existing?.has(item.key)) {
+        skipped++;
+        continue;
+      }
+      const res = await handle.put(item.key, new Uint8Array(fs.readFileSync(item.file)), { contentType: contentTypeOf(item.key) });
+      if (!res.ok) throw new Error(`${label}: put ${item.key} failed (${res.status} ${(await res.text()).slice(0, 200)})`);
+      await res.arrayBuffer();
+      done++;
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(CONCURRENCY, files.length) }, worker));
+  log(`${label}: ${done} object(s) uploaded${skipped ? `, ${skipped} kept (already present)` : ''}`);
+  return { done, skipped };
+}
+
+/**
+ * @param root app root (holds dist/ after `mosetta build`, and pages/ prefabs/ config.json)
+ * @param registryFile the provider registry JSON (default <root>/.mosetta/providers.json)
+ * @param content also seed the content store (keys already present are kept unless forceContent)
+ */
+export async function deploy(root, { registryFile, content = false, forceContent = false, contentOnly = false, dryRun = false, log = sectionLog('deploy') } = {}) {
+  const file = registryFile ?? path.join(root, '.mosetta', 'providers.json');
+  if (!fs.existsSync(file)) throw new Error(`deploy: registry not found at ${file} (copy providers.example.json and fill in the credentials)`);
+  const dist = path.join(root, 'dist');
+  // the content seed alone: the code is released elsewhere (`mosetta push`), the registry may name
+  // no code store this machine can write
+  if (!contentOnly && !fs.existsSync(path.join(dist, 'public'))) throw new Error(`deploy: no ${dist}/public — run \`mosetta build\` first`);
+
+  // @mosetta/stores is TS source: bundled for node exactly like the server package
+  const { module: provider, cleanup } = await importServer(require.resolve('@mosetta/stores'), { platform: 'node' });
+  try {
+    const providers = provider.parseStoreConnectors(JSON.parse(fs.readFileSync(file, 'utf8')));
+    if (!providers.length) throw new Error(`deploy: ${file} holds no valid store connector`);
+    const manager = new provider.StoreConnectors(providers);
+    const need = (store) => {
+      const handle = manager.pick(store, 'put');
+      if (!handle) throw new Error(`deploy: the registry has no "${store}" store connector that can put`);
+      return handle;
+    };
+
+    let summary = {};
+    if (!contentOnly) {
+      try {
+        summary = await release(
+          { public: need('public-code'), private: need('private-code') },
+          builtDistribution(dist),
+          { label: path.basename(file), dryRun, log },
+        );
+      } catch (e) {
+        // a refusal is an answer: said as it is, without the stack
+        if (e instanceof ReleaseRefused) throw new Error(e.message);
+        throw e;
+      }
+    }
+    if (dryRun) return summary;
+
+    if (content || contentOnly) {
+      const handle = need('content');
+      const files = [
+        ...walk(path.join(root, 'pages'), root),
+        ...walk(path.join(root, 'prefabs'), root),
+        ...(fs.existsSync(path.join(root, 'config.json')) ? [{ file: path.join(root, 'config.json'), key: 'config.json' }] : []),
+      ];
+      // the seed never overwrites what editors have written: present keys are kept
+      const existing = forceContent ? null : new Set((await handle.list('')).map((o) => o.key));
+      summary.content = await uploadAll(handle, files, { log, existing, label: 'content' });
+      // the route table is a LISTING of publish markers (pages/published/<pattern>~<name>~<rev>):
+      // the dev store derives it from the metas, a real store needs the markers put — one per
+      // live page of the seed
+      // …but only for pages this run actually seeded: a page the store already holds has moved
+      // on (published from the workbench) — re-putting its seed marker would resurrect an old route
+      const markers = [];
+      for (const dir of fs.existsSync(path.join(root, 'pages')) ? fs.readdirSync(path.join(root, 'pages')) : []) {
+        const metaFile = path.join(root, 'pages', dir, 'page.json');
+        if (!fs.existsSync(metaFile)) continue;
+        if (existing?.has(`pages/${dir}/page.json`)) continue;
+        const meta = JSON.parse(fs.readFileSync(metaFile, 'utf8'));
+        if (!Number.isInteger(meta.live)) continue;
+        const docFile = path.join(root, 'pages', dir, 'versions', `${meta.live}.json`);
+        if (!fs.existsSync(docFile)) continue;
+        const { pattern } = JSON.parse(fs.readFileSync(docFile, 'utf8'));
+        if (typeof pattern !== 'string') continue;
+        markers.push(`pages/published/${encodeURIComponent(pattern)}~${dir}~${meta.live}`);
+      }
+      let put = 0;
+      for (const key of markers) {
+        if (existing?.has(key)) continue;
+        const res = await handle.put(key, '{}', { contentType: contentTypeOf('marker.json') });
+        if (!res.ok) throw new Error(`content: marker ${key} failed (${res.status})`);
+        await res.arrayBuffer();
+        put++;
+      }
+      log(`content: ${put} publish marker(s) put${markers.length - put ? `, ${markers.length - put} kept` : ''}`);
+      summary.content.markers = put;
+    }
+    return summary;
+  } finally {
+    cleanup();
+  }
+}

package/src/dev.mjs

@@ -0,0 +1,145 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { startDevBuilder } from './devBuilder.mjs';
+import { buildRenderWorker } from './buildWorker.mjs';
+import { resolveWorkerdBin, writeWorkerdConfig, spawnWorkerd, killWorkerd, probePort } from './workerd.mjs';
+import { createStaticDir } from './devStaticDir.mjs';
+import { loadDevKeys, devRegistry } from './devKeys.mjs';
+import { startTypecheckWatch } from './typecheck.mjs';
+import { sectionLog, silentLog, renderBuildReport } from './log.mjs';
+
+// Dev orchestration: ONE process owns the network.
+//
+//   workerd (:port) — render, static assets (disk service over the generations dir), the content
+//                     channel (writable disk services on pages/ and prefabs/) and SSE reload
+//   node            — builds, watches files, writes generations. OPENS NO SOCKETS.
+//
+// The dev environment is exposed via a tunnel (cloudflared/ngrok) so code on the developer's
+// machine joins the prod app as a regular provider — a single address gets tunneled. There used
+// to be two ports, then node stayed on loopback only for disk writes; now the worker can write
+// too (`disk (writable = true)`), so the node server is gone entirely.
+//
+// Coordination between them is FILE-based, in the generations dir: `lock` (build in progress),
+// `current` (generation pointer), `reload` (counter, bumped only on CODE edits). The worker polls
+// them, node only writes — there is no back channel.
+export async function startDev({
+  root, port, write = false, typecheck = true, quiet = false, contentRoot,
+  fileSystem, engine, frameworkDir,
+}) {
+  // NO port default here: 3000 is the DEVELOPER's port, and the human-facing default lives in
+  // the CLI bin alone. Every other caller — tests, harnesses, tooling — states its port, and
+  // takes a dynamic one (freePort). A library default would let any of them land on 3000 by
+  // simply forgetting the field.
+  if (!Number.isInteger(port)) throw new Error('startDev: an explicit port is required (the CLI default lives in bin/mosetta.mjs)');
+  // quiet (tests): mute summaries — [assets], static counters, the dev address; warnings
+  // ([cli] warnings, [workerd], [esbuild]) stay loud
+  const clog = sectionLog('cli');
+  // port busy — almost always a workerd copy that survived a previous run. Saying so directly
+  // is cheaper than leaving the user with a bare "readiness timed out"
+  if (await probePort(port)) {
+    const stale = await fetch(`http://127.0.0.1:${port}/__mosetta_ping__`).then((r) => r.status === 204).catch(() => false);
+    throw new Error(stale
+      ? `port ${port} is taken by a previous mosetta dev process — close it (or pick another: --port <n>)`
+      : `port ${port} is taken by another process — pick a free one: --port <n>`);
+  }
+  const plog = quiet ? silentLog : sectionLog('tiles');
+  const origin = `http://127.0.0.1:${port}`;
+  const appRoot = fs.realpathSync(root);
+  // where content writes land: the app's source folders by default; tests substitute a temp
+  // dir so writes don't mutate the fixture
+  const contentSource = contentRoot ? fs.realpathSync(contentRoot) : appRoot;
+  const staticDir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'mosetta-static-')));
+  const store = createStaticDir(staticDir);
+  // content bindings point at specific folders — they must exist even if the app has not created them yet
+  // media: pictures uploaded from the workbench — the dev's stand-in for the CDN folder
+  for (const dir of ['pages', 'prefabs', 'media']) fs.mkdirSync(path.join(contentSource, dir), { recursive: true });
+
+  const builder = await startDevBuilder({
+    root,
+    write,
+    quiet,
+    fileSystem,
+    engine,
+    frameworkDir,
+    // lock for the whole rebuild: while the file exists the worker serves neither static nor render
+    onRebuildStart: () => store.lock(),
+    onRebuild: (state, { codeChange }) => {
+      const { written, linked } = store.publish(state.fs.files);
+      if (codeChange) store.bumpReload(); // content edits come from the editor — do not reload it
+      plog(`static: ${written} written, ${linked} linked`);
+    },
+    // ALWAYS: the lock is released here, and a build error goes into status — the overlay shows it
+    onRebuildEnd: ({ error }) => {
+      store.report('build', error);
+      store.unlock();
+    },
+  });
+
+  // live typecheck companion: types never gate the dev loop — errors land in this log as [types]
+  // and INTO STATUS, where the overlay picks them up (typecheck runs its own cycle, decoupled from builds)
+  const tsWatch = typecheck ? startTypecheckWatch({ root, onResult: (errors) => store.report('typescript', errors) }) : null;
+
+  // initial tree — before the worker starts: it resolves its directory at startup
+  const first = store.publish(builder.getState().fs.files);
+  plog(`static: ${first.written} written`);
+  const report = renderBuildReport(builder.getState().report);
+  if (report && !quiet) sectionLog('assets')(report);
+
+  // dev is closed by default: keys always exist, the credentials registry is seeded into env
+  const keys = loadDevKeys(appRoot, clog);
+  const registry = devRegistry(origin, keys);
+
+  const workerCode = await buildRenderWorker({ mode: 'development', dev: true });
+  const { dir, configPath } = writeWorkerdConfig({
+    workerCode,
+    port,
+    // the provider for both browser and runner is the worker ITSELF (one origin, no cross-origin)
+    providerOrigin: `${origin}/`,
+    staticDir,
+    appRoot,
+    contentRoot: contentSource,
+    providersJson: JSON.stringify(registry),
+  });
+
+  const binPath = resolveWorkerdBin();
+  let child;
+  const cleanup = () => {
+    tsWatch?.stop();
+    builder.close();
+    fs.rmSync(dir, { recursive: true, force: true });
+    fs.rmSync(staticDir, { recursive: true, force: true });
+  };
+  try {
+    child = await spawnWorkerd({ binPath, configPath, port, log: sectionLog('workerd') });
+  } catch (e) {
+    cleanup();
+    throw e;
+  }
+
+  if (!quiet) clog(`dev: ${origin}  (single port: render, static, content; node holds no sockets)`);
+
+  let down = false;
+  // GUARANTEED kill: SIGTERM → wait → SIGKILL. A surviving workerd holds the port and the next
+  // `mosetta dev` fails to start; so exiting waits for the child to actually die.
+  const shutdown = async () => {
+    if (down) return;
+    down = true;
+    const dead = await killWorkerd(child);
+    if (!dead) clog(`workerd (pid ${child.pid}) did not exit — port ${port} may stay taken`);
+    cleanup();
+  };
+  const bye = () => { shutdown().finally(() => process.exit(0)); };
+  process.on('SIGINT', bye);
+  process.on('SIGTERM', bye);
+  // last safety net: synchronous SIGKILL on process exit — this also covers crashes where the
+  // async shutdown never gets to finish
+  process.on('exit', () => {
+    try { if (child.exitCode === null && child.signalCode === null) process.kill(child.pid, 'SIGKILL'); } catch { /* ignore */ }
+  });
+  child.on('exit', (code, signal) => {
+    if (!down) clog(`workerd exited (code=${code} signal=${signal})`);
+  });
+
+  return { builder, child, dir, origin, staticDir, keys, registry, shutdown };
+}

package/src/devBuilder.mjs

@@ -0,0 +1,116 @@
+import path from 'node:path';
+import chokidar from 'chokidar';
+import { build } from '@mosetta/build';
+import { PackagesResolver } from '@mosetta/build/packagesResolver';
+import { ArtifactCache } from '@mosetta/build/artifactCache';
+import { scanCatalog } from '@mosetta/build/scanner';
+import { loadBuildConfig, mirrorArtifacts } from './buildConfigLoader.mjs';
+import { frameworkResolutions } from './scanner.mjs';
+import { sectionLog, silentLog } from './log.mjs';
+import { evaluateModule } from './evaluate.mjs';
+
+/**
+ * Dev build loop: build → watch files → rebuild.
+ *
+ * It used to live inside the dev provider (`staticServer.mjs`), but serving is now workerd's
+ * job and node remains the builder-watcher. So the loop is a thing of its own: `dev.mjs` takes
+ * it with no server at all, the test provider — together with its own server.
+ *
+ * Hooks: `onRebuildStart` — before the build (whoever serves the code takes the lock),
+ * `onRebuild(state, { codeChange })` — after a successful one, `onRebuildEnd({ ok, error })` —
+ * ALWAYS, in `finally`. The last one guarantees the lock gets released: a failed build must not
+ * hang dev on the worker's timeout, and its text must reach status (the error overlay).
+ *
+ * `codeChange` distinguishes CODE edits from CONTENT edits: content is written by the editor
+ * itself, and reloading its browser would kill the editing session.
+ */
+export async function startDevBuilder({
+  root, write = false, quiet = false, fileSystem, engine, frameworkDir,
+  onRebuildStart, onRebuild, onRebuildEnd,
+}) {
+  // quiet mutes summaries ([tiles] chatter); build errors go via [esbuild] and stay loud
+  const plog = quiet ? silentLog : sectionLog('tiles');
+  // Artifact cache across iterations: the process is long-lived, and editing one file must not
+  // rebuild every artifact. Validity is by mtime of each artifact's graph.
+  const cache = new ArtifactCache(fileSystem);
+
+  // the build writes nothing: mirroring into dist for inspection is the host's business
+  const runBuild = async () => {
+    const buildConfig = await loadBuildConfig(root);
+    // the package catalog is rescanned ON EVERY iteration: a `pnpm add` mid dev-session is
+    // picked up by the next rebuild without a restart
+    const resolver = new PackagesResolver({
+      fileSystem,
+      // dev sees devDependencies (devLibraries live there), but a seed import from devDeps gets
+      // an immediate warning — a prod build will not allow it
+      catalog: { ...scanCatalog({ fileSystem, root, frameworkDir, includeDev: true, log: plog }), framework: frameworkResolutions() },
+    });
+    const s = await build(root, { mode: 'development', fileSystem, resolver, engine, frameworkDir, buildConfig, log: plog, cache, evaluate: evaluateModule });
+    const { hits, misses } = cache.take();
+    if (hits) plog(`cache: ${hits} file(s) reused, ${misses} rebuilt`);
+    if (write) mirrorArtifacts(s.fs.files, path.join(root, 'dist'));
+    return s;
+  };
+
+  let state = await runBuild();
+
+  // The watch set follows the LAST SUCCESSFUL build, not the initial one: a branch checkout or
+  // a mosetta.json edit can add roots and pull sources from previously unknown places.
+  let watched = new Set([...(state.watchDirs || []), ...state.watchFiles]);
+  const watcher = chokidar.watch([...watched], { ignoreInitial: true });
+  const resyncWatcher = () => {
+    const next = new Set([...(state.watchDirs || []), ...state.watchFiles]);
+    for (const t of next) if (!watched.has(t)) watcher.add(t);
+    for (const t of watched) if (!next.has(t)) watcher.unwatch(t);
+    watched = next;
+  };
+
+  let building = false;
+  let pending = false;
+  let codeChanged = false; // accumulates across coalesced rebuilds
+  const rebuild = async (isCodeChange = false) => {
+    codeChanged = codeChanged || isCodeChange;
+    if (building) { pending = true; return; }
+    building = true;
+    const codeChange = codeChanged;
+    codeChanged = false;
+    let error = null;
+    try {
+      if (onRebuildStart) await onRebuildStart();
+      state = await runBuild();
+      resyncWatcher();
+      if (onRebuild) await onRebuild(state, { codeChange });
+      plog(`rebuilt${codeChange ? '' : ' (content change — no browser reload)'}`);
+    } catch (e) {
+      // the last intact state keeps being served — a broken tree mid-checkout is fixed by the
+      // very next event
+      error = String((e && e.stack) || (e && e.message) || e);
+      sectionLog('esbuild')(error);
+    } finally {
+      // ALWAYS: the lock is released here, so a failed build does not hang serving
+      if (onRebuildEnd) {
+        try {
+          await onRebuildEnd({ ok: error === null, error });
+        } catch { /* status is auxiliary — it must not crash the loop */ }
+      }
+      building = false;
+      if (pending) { pending = false; rebuild(); }
+    }
+  };
+
+  // Content (page/prefab revisions and drafts) is written by the editor itself — its edits rebuild
+  // SILENTLY. The folders count too: the first draft of an entity creates its `drafts/` folder,
+  // and a reload for that would throw the author's workbench away mid-edit.
+  const isContentPath = (file) => !!file && /(^|[/\\])(pages|prefabs)([/\\]|$)/.test(file)
+    && !/\.(?:[cm]?[jt]sx?|css)$/.test(file);
+  watcher.on('all', (event, file) => rebuild(!isContentPath(file)));
+  // a warning, not a summary — loud even under quiet
+  watcher.on('error', (e) => sectionLog('tiles')(`watcher error: ${e.message}`));
+
+  return {
+    getState: () => state,
+    watcher,
+    rebuild,
+    close: () => watcher.close(),
+  };
+}

package/src/devKeys.mjs

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+/**
+ * Closed-dev keys. There is no "open mode": keys always exist — dev itself gets them for free
+ * (this module generates and seeds them), so there is no reason to weaken the model.
+ *
+ * Two pairs: READ (distributable — handed to the tunnel consumer and shipped into the isolate
+ * projection) and WRITE (never leaves the machine; enters an isolate only via a
+ * `contentWriters` grant). Keys live in `.mosetta/devKeys.json` at the app root and survive
+ * restarts — the tunnel consumer never needs re-keying. The directory must be in `.gitignore` —
+ * the secret must not reach the repository; the CLI warns about it.
+ */
+export function loadDevKeys(appRoot, log) {
+  const dir = path.join(appRoot, '.mosetta');
+  const file = path.join(dir, 'devKeys.json');
+  let keys = null;
+  try {
+    keys = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch { /* missing or corrupt file — regenerated below */ }
+  if (!keys?.read?.accessKeyId || !keys?.read?.secretAccessKey || !keys?.write?.accessKeyId || !keys?.write?.secretAccessKey) {
+    const pair = (prefix) => ({
+      accessKeyId: `${prefix}${crypto.randomBytes(6).toString('hex').toUpperCase()}`,
+      secretAccessKey: crypto.randomBytes(32).toString('hex'),
+    });
+    keys = { read: pair('DEVR'), write: pair('DEVW') };
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(keys, null, 2));
+  }
+  if (!isGitignored(appRoot) && log) log(`warning: add \`.mosetta/\` to .gitignore — it holds dev keys (${file})`);
+  return keys;
+}
+
+// the rule may live in a .gitignore at any level up to the git root (monorepo) — walk upward
+function isGitignored(appRoot) {
+  let dir = appRoot;
+  for (let depth = 0; depth < 8; depth++) {
+    const gitignore = path.join(dir, '.gitignore');
+    if (fs.existsSync(gitignore) && fs.readFileSync(gitignore, 'utf8').split('\n')
+      .some((line) => line.trim().replace(/^\*\*\//, '').replace(/\/$/, '') === '.mosetta')) {
+      return true;
+    }
+    if (fs.existsSync(path.join(dir, '.git'))) return false;
+    const parent = path.dirname(dir);
+    if (parent === dir) return false;
+    dir = parent;
+  }
+  return false;
+}
+
+/**
+ * Closed-dev registry: credentials of self entries double as the KEY TABLE of the fake S3, and
+ * an entry's `intent` is the ACL (read: get/conditionalGet/list; read-write: + put/delete).
+ * Order matters for `pick`: the content read entry before rw (reads get the read key), the
+ * private-code web connector before s3 (same URLs as the CDN form).
+ */
+export function devRegistry(origin, keys) {
+  const base = origin.replace(/\/+$/, '');
+  const endpoint = `${base}/__mosetta_s3__/`;
+  return [
+    { name: 'dev', store: 'content', intent: 'read', connector: { transport: 's3', endpoint, bucket: 'content', credentials: keys.read } },
+    { name: 'dev', store: 'content', intent: 'read-write', connector: { transport: 's3', endpoint, bucket: 'content', credentials: keys.write } },
+    { name: 'dev', store: 'public-code', intent: 'read', connector: { transport: 'web', url: `${base}/` } },
+    // uploads (media/…) go through the S3 form of the public store with the WRITE key; the web
+    // entry above stays first — reading and the public base keep their plain URLs
+    { name: 'dev', store: 'public-code', intent: 'read-write', connector: { transport: 's3', endpoint, bucket: 'public-code', credentials: keys.write } },
+    { name: 'dev', store: 'private-code', intent: 'read', connector: { transport: 'web', url: `${base}/private/` } },
+    { name: 'dev', store: 'private-code', intent: 'read', connector: { transport: 's3', endpoint, bucket: 'private-code', credentials: keys.read } },
+  ];
+}

package/src/devStaticDir.mjs

@@ -0,0 +1,112 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+/**
+ * The directory workerd's `disk` service reads, plus the dev-build status.
+ *
+ *   <dir>/current/…    ← artifacts being served right now
+ *   <dir>/next/…       ← the next build while it is being written
+ *   <dir>/lock         ← exists while a rebuild is in progress (the worker polls it)
+ *   <dir>/dev.json     ← status: whether the build succeeded, build and typecheck errors
+ *
+ * WRITES ARE ALL-OR-NOTHING. A new build is written into `next`, and only once fully assembled
+ * the directories swap via two `rename`s (metadata operations, instant). A failed or interrupted
+ * build leaves no half-written tree: the previous one keeps being served.
+ *
+ * Unchanged files move over as HARD LINKS from the current tree — on APFS/ext4 that is metadata,
+ * no disk rewrite. With the artifact cache, editing one file = one real write; the other 165 are
+ * links. Side effect: a link keeps the old mtime, so the worker-synthesized ETag of unchanged
+ * artifacts stays the same and 304 keeps working.
+ *
+ * The lock is released GUARANTEED — the caller does it in `finally` (see dev.mjs): dev must not
+ * hang because of a failed build, and waiting out the worker's five-second timeout is pointless.
+ */
+
+const hashOf = (bytes) => crypto.createHash('sha1').update(bytes).digest('hex');
+
+export function createStaticDir(dir) {
+  fs.rmSync(dir, { recursive: true, force: true });
+  fs.mkdirSync(dir, { recursive: true });
+  const lockFile = path.join(dir, 'lock');
+  const statusFile = path.join(dir, 'dev.json');
+  const currentDir = path.join(dir, 'current');
+  const nextDir = path.join(dir, 'next');
+  const oldDir = path.join(dir, 'old');
+  let hashes = new Map(); // path → sha1 of the current tree (for hard links)
+  let reloads = 0;
+  let status = { ok: true, build: null, typescript: null };
+
+  const writeStatus = () => {
+    // `stamp` is a fingerprint of the error TEXT: the overlay uses it to remember it was
+    // dismissed on this exact problem, and shows up again when the problem changes
+    const ok = !status.build && !status.typescript;
+    const stamp = ok ? '' : hashOf(`${status.build ?? ''}\u0000${status.typescript ?? ''}`).slice(0, 12);
+    const body = JSON.stringify({ ...status, ok, stamp }, null, 2);
+    const tmp = `${statusFile}.tmp`;
+    fs.writeFileSync(tmp, body);
+    fs.renameSync(tmp, statusFile); // a reader must never see half a file
+  };
+  writeStatus();
+
+  return {
+    dir,
+
+    /** node takes the lock and node releases it — the worker only polls the file */
+    lock() {
+      fs.writeFileSync(lockFile, String(Date.now()));
+    },
+
+    unlock() {
+      fs.rmSync(lockFile, { force: true });
+    },
+
+    /**
+     * Reload counter: bumped ONLY on code edits. The worker holds the SSE connections and
+     * watches this file — no back channel from node is needed (content edits come from the
+     * editor itself, and a reload would kill its session).
+     */
+    bumpReload() {
+      reloads += 1;
+      fs.writeFileSync(path.join(dir, 'reload'), String(reloads));
+    },
+
+    /** build/typecheck error (or its absence) goes to dev.json, where the overlay picks it up */
+    report(section, message) {
+      status = { ...status, [section]: message || null };
+      writeStatus();
+    },
+
+    /** files: Map(path → string|bytes) — the build artifact tree as-is */
+    publish(files) {
+      fs.rmSync(nextDir, { recursive: true, force: true });
+      const nextHashes = new Map();
+      let written = 0;
+      let linked = 0;
+
+      for (const [rel, content] of files) {
+        const bytes = Buffer.isBuffer(content) ? content : Buffer.from(content);
+        const hash = hashOf(bytes);
+        nextHashes.set(rel, hash);
+        const target = path.join(nextDir, rel);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        if (hashes.get(rel) === hash) {
+          try {
+            fs.linkSync(path.join(currentDir, rel), target);
+            linked += 1;
+            continue;
+          } catch { /* link failed (race, foreign FS) — just write the file */ }
+        }
+        fs.writeFileSync(target, bytes);
+        written += 1;
+      }
+
+      // the swap is the LAST action: before it the whole previous tree is served, after — the new one
+      if (fs.existsSync(currentDir)) fs.renameSync(currentDir, oldDir);
+      fs.renameSync(nextDir, currentDir);
+      fs.rmSync(oldDir, { recursive: true, force: true });
+      hashes = nextHashes;
+      return { written, linked };
+    },
+  };
+}

package/src/engineLoader.mjs

@@ -0,0 +1,46 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createWasmEngine } from './wasmEngine.mjs';
+
+/**
+ * Build engine: ONE for all environments — wasm (the parity policy).
+ *
+ * The framework deliberately ships no native binaries: they bring a class of problems we do not
+ * have to own — per-OS platform builds (and their differences), optional dependencies and
+ * postinstall in CI, plus the need to differentially verify that two engines produce the same
+ * bytes. Wasm behaves identically on the developer's machine, in the CI pipeline and in the
+ * isolate; everything else in the build is plain JS.
+ *
+ * `mosetta.engine.mjs` is an escape hatch for a developer who values speed more: a default export
+ * of a factory returning `{ rollup, transform, bundle }` (e.g. native rollup+esbuild). The rules
+ * of the game transfer to it: artifacts must keep the protocol shape (checked by
+ * `assertNamedRegister`), and parity with the isolate build is its responsibility.
+ * The hook is NOT applied IN THE ISOLATE: building the hook itself needs an engine — chicken and
+ * egg; there the engine arrives as the declared wasm modules of the set.
+ */
+
+const ENGINE_FILE = 'mosetta.engine.mjs';
+const REQUIRED = ['rollup', 'transform', 'bundle'];
+
+export async function loadEngine(root, { mode = 'development', log = () => {} } = {}) {
+  const file = path.join(root, ENGINE_FILE);
+  let mtimeMs;
+  try {
+    mtimeMs = fs.statSync(file).mtimeMs;
+  } catch {
+    return createWasmEngine(); // default: wasm — the same set that ships into the isolate
+  }
+  // cache-bust by mtime: the ESM import cache is permanent, a hook edit must be picked up without a restart
+  const ns = await import(`${pathToFileURL(file).href}?v=${mtimeMs}`);
+  if (typeof ns.default !== 'function') {
+    throw new Error(`${ENGINE_FILE} must default-export a factory returning { rollup, transform, bundle }`);
+  }
+  const engine = await ns.default({ mode });
+  const missing = REQUIRED.filter((k) => typeof engine?.[k] !== 'function');
+  if (missing.length) {
+    throw new Error(`${ENGINE_FILE}: the engine must provide functions ${REQUIRED.join(', ')} (missing: ${missing.join(', ')})`);
+  }
+  log(`engine: ${ENGINE_FILE} — custom build engine; parity with the platform's build is on you`);
+  return engine;
+}

package/src/evaluate.mjs

@@ -0,0 +1,18 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// The build's `evaluate` capability, in node: a self-contained ESM module the build bundled (a
+// block's settings schema with what turns it into JSON Schema) run in this process, its exports
+// handed back. The build itself runs nothing — this is the host's to give.
+export async function evaluateModule(jsCode) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mosetta-evaluate-'));
+  const file = path.join(dir, 'module.mjs');
+  fs.writeFileSync(file, jsCode);
+  try {
+    return { ...(await import(pathToFileURL(file).href)) };
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}