@mosetta/build 0.0.0-stage → 0.0.9

package/src/conditions.mjs

@@ -0,0 +1,21 @@
+/**
+ * `exports` conditions of the target environments.
+ *
+ * Conditions are a statement about the TARGET, not a property of the resolver. A dual package's
+ * `require` and `import` branches are different files, and if the condition is not set it gets
+ * picked as a side effect of what the resolver is written with: `createRequire` always says
+ * "I am require, I am node" about itself, even when building code for the browser. The failure
+ * is silent — the build passes, things break later.
+ *
+ * That is why the policy lives here, apart from the mechanics, and is visible as a whole.
+ */
+
+// Client artifacts execute in the browser (SystemJS) AND in ssr isolates (MiniSystem, workerd) —
+// it is the same artifact set. The browser ESM branch suits both environments: it contains no
+// node specifics by construction.
+export const CLIENT_CONDITIONS = ['browser', 'import'];
+
+// A private monolith is a self-contained ESM targeting Web API (`platform: 'neutral'`). We do
+// not claim `browser` here: the monolith executes in an isolate, not in a document, and a
+// package's browser branch may pull DOM dependencies.
+export const MONOLITH_CONDITIONS = ['import'];

package/src/configBundle.mjs

@@ -0,0 +1,59 @@
+import { path } from './nodeApi.mjs';
+import { portResolveEsbuild } from './plugins/portResolveEsbuild.mjs';
+import { monolithCompat, monolithCompatOptions } from './plugins/monolithCompat.mjs';
+import { MONOLITH_CONDITIONS } from './conditions.mjs';
+
+/**
+ * Bundling the tenant's `mosetta.build.mjs` FOR PHASE 2 of recomposition.
+ *
+ * The config is foreign code and is NOT executed here: only bundled into one ESM module with
+ * the same compatibility set as the monoliths (builtin shims, node:* external, patches). ONLY
+ * the runner's composition makes it executable — the module lands in the phase-2 isolate's
+ * bundle under the name CONFIG_MODULE, and the action imports it from the bundle.
+ *
+ * The config's closure is already in the body: the scanner collects seeds from
+ * mosetta.build.mjs itself too (SOURCE_EXTENSIONS includes .mjs), so its dependencies arrive
+ * normally. A non-portable config (node natives, unresolvable imports) fails here with a
+ * bundling error — it goes into the text of the loud refusal.
+ */
+
+export const CONFIG_MODULE = 'mosetta.config.js';
+
+export async function bundleBuildConfig(fileSystem, resolver, { engine, root, frameworkDir }) {
+  const file = path.join(root, 'mosetta.build.mjs');
+  const result = await engine.bundle({
+    entryPoints: [file],
+    bundle: true,
+    format: 'esm',
+    platform: 'neutral',
+    target: 'es2022',
+    write: false,
+    logLevel: 'silent',
+    absWorkingDir: root,
+    plugins: [
+      monolithCompat(fileSystem, resolver),
+      portResolveEsbuild(fileSystem, resolver, frameworkDir, MONOLITH_CONDITIONS),
+    ],
+    ...monolithCompatOptions(),
+  });
+  return result.outputFiles.find((f) => !f.path.endsWith('.map')).text;
+}
+
+const asFn = (v, name) => {
+  if (v === undefined || v === null) return null;
+  if (typeof v !== 'function') throw new Error(`mosetta.build.mjs: \`${name}\` must be a function`);
+  return v;
+};
+
+/** Hooks from an ALREADY IMPORTED (by composition) config module — same shape as the CLI's loadBuildConfig. */
+export function buildConfigFrom(ns) {
+  const cfg = ns?.default ?? {};
+  if (typeof cfg !== 'object') throw new Error('mosetta.build.mjs must default-export an object of hooks');
+  return {
+    file: 'mosetta.build.mjs',
+    stamp: 'recomposed', // the composition's identity already includes the config module's hash
+    clientPlugins: asFn(cfg.clientPlugins, 'clientPlugins'),
+    serverEsbuild: asFn(cfg.serverEsbuild, 'serverEsbuild'),
+    rollupOptions: asFn(cfg.rollupOptions, 'rollupOptions'),
+  };
+}

package/src/css.mjs

@@ -0,0 +1,108 @@
+import { path } from './nodeApi.mjs';
+import postcss from 'postcss';
+import valueParser from 'postcss-value-parser';
+import { hashedAssetName } from './hash.mjs';
+
+// Scope every rule's selectors under `.<scopeClass>` (skip @keyframes steps).
+function scopePlugin(scopeClass) {
+  const plugin = () => ({
+    postcssPlugin: 'mosetta-scope',
+    // Once + walkRules visits each existing rule exactly once (the Rule visitor re-runs on mutation).
+    Once(root) {
+      root.walkRules((rule) => {
+        const parent = rule.parent;
+        if (parent && parent.type === 'atrule' && /keyframes$/i.test(parent.name)) return;
+        rule.selectors = rule.selectors.map((s) => `.${scopeClass} ${s}`);
+      });
+    },
+  });
+  plugin.postcss = true;
+  return plugin();
+}
+
+// Neutralize global root selectors (html/body/:root/:host) in UNscoped shared css: under the
+// per-module scope these rules were dead (`.<full> body` never matches) — we keep the same
+// semantics deterministically and byte-identically: a dead-class prefix. Disciplined css
+// (.dui-root) never touches this path.
+function neutralizeGlobals() {
+  const GLOBAL_ROOT = /^(html|body|:root|:host)(?![\w-])/;
+  const plugin = () => ({
+    postcssPlugin: 'mosetta-neutralize-globals',
+    Once(root) {
+      root.walkRules((rule) => {
+        const parent = rule.parent;
+        if (parent && parent.type === 'atrule' && /keyframes$/i.test(parent.name)) return;
+        rule.selectors = rule.selectors.map((s) => (GLOBAL_ROOT.test(s.trim()) ? `.mosetta-neutralized-global ${s}` : s));
+      });
+    },
+  });
+  plugin.postcss = true;
+  return plugin();
+}
+
+// Rewrite relative url(...) refs → ./<hashed>, collecting assets to co-locate next to the stylesheet.
+function urlRewrite(fileSystem, cssDir, assets) {
+  const plugin = () => ({
+    postcssPlugin: 'mosetta-url-rewrite',
+    Declaration(decl) {
+      if (!decl.value || !decl.value.includes('url(')) return;
+      const parsed = valueParser(decl.value);
+      parsed.walk((node) => {
+        if (node.type !== 'function' || node.value !== 'url' || !node.nodes[0]) return;
+        const urlNode = node.nodes[0];
+        const raw = urlNode.value;
+        if (!raw || /^(https?:|data:|#|\/)/.test(raw)) return; // skip absolute / data / anchor
+        const abs = path.resolve(cssDir, raw);
+        if (!fileSystem.exists(abs)) return;
+        const buf = fileSystem.readFile(abs);
+        const out = hashedAssetName(abs, buf);
+        assets.set(out, abs);
+        urlNode.value = './' + out;
+      });
+      decl.value = parsed.toString();
+    },
+  });
+  plugin.postcss = true;
+  return plugin();
+}
+
+/**
+ * Css minification — a prod post-pass by the SAME engine that minifies js (`minifyChunk`).
+ *
+ * A dedicated css tool (lightningcss and the like) is deliberately not bundled: the only thing
+ * we were missing is compression, and the engine already has it; a full css compiler is +16 MB
+ * of wasm in EVERY isolate's bundle (the whole build bundle is 18.9 MB today) for percentage
+ * points of compression and browserslist lowering — i.e. for one distributive's configuration.
+ * Whoever needs that plugs their own into `mosetta.build.mjs` (the hook path was verified with
+ * lightningcss-wasm exactly).
+ *
+ * `target` is NOT set: we want compression, not syntax rewriting — lowering for old browsers is
+ * the tenant's choice, and the build must not silently change css semantics on their behalf.
+ */
+async function minifyCss(engine, css) {
+  const r = await engine.transform(css, { loader: 'css', minify: true });
+  return r.code;
+}
+
+/**
+ * Process a module's CSS files: scope selectors with `.<scopeClass>` (dev+prod) and rewrite
+ * relative url() to co-located hashed assets. Returns { css, assets: Map(out -> srcAbs) }.
+ * scopeClass === null → no scoping (dependency css isolates itself).
+ *
+ * Minification — production only and AFTER scoping/`url()` rewriting: compression gets exactly
+ * the css that would ship in the distributive, with scope prefixes and `./<hashed>` links in place.
+ */
+export async function processCss({ fileSystem, cssFiles, scopeClass, engine, mode = 'development' }) {
+  const assets = new Map();
+  let combined = '';
+  for (const file of cssFiles) {
+    const raw = fileSystem.readFile(file, 'utf8');
+    const result = await postcss([
+      ...(scopeClass ? [scopePlugin(scopeClass)] : [neutralizeGlobals()]),
+      urlRewrite(fileSystem, path.dirname(file), assets),
+    ]).process(raw, { from: file });
+    combined += result.css + '\n';
+  }
+  const css = mode === 'production' ? await minifyCss(engine, combined) : combined;
+  return { css, assets };
+}

package/src/discovery.mjs

@@ -0,0 +1,184 @@
+import { path } from './nodeApi.mjs';
+import { packageDirOf } from './packageMeta.mjs';
+
+// No logger is imported here: the console is a host capability, and discovery is portable.
+// Warnings go into the injected `log`.
+const SILENT = () => {};
+
+// Module entry convention: <name>/<name>.<type>.(ts|tsx)  (folder name === module name)
+const MODULE_FILE_RE = /^(?<name>[a-z][A-Za-z0-9]*)\.(?<type>[a-z][A-Za-z0-9]*)\.(?:ts|tsx)$/;
+// Content entities (pages/prefabs) follow the same lowerCamel naming (folder-per-entity).
+const ENTITY_NAME_RE = /^[a-z][A-Za-z0-9]*$/;
+
+// Module types that are NOT built for the client distributive. `settings` is no module at all: a
+// block's settings schema beside it, read by the build into the block's catalog entry.
+const NON_CLIENT_TYPES = new Set(['server', 'router', 'settings']);
+
+// A tile palette's config: `mosetta.json`. Its `brand` is whose tiles these are (ADR-0071) — on the
+// wire it stays the namespace, the `_ns_` of every tile id, so the build carries it as `namespace`.
+export function readConfig(fileSystem, root) {
+  const file = path.join(root, 'mosetta.json');
+  const cfg = fileSystem.readJson(file);
+  if (cfg && typeof cfg === 'object' && 'namespace' in cfg) {
+    throw new Error(`${file}: "namespace" is called "brand" now — rename the key`);
+  }
+  return cfg && typeof cfg === 'object' && typeof cfg.brand === 'string' ? { ...cfg, namespace: cfg.brand } : cfg;
+}
+function readPkg(fileSystem, root) {
+  return fileSystem.readJson(path.join(root, 'package.json'));
+}
+
+/** a distribution's version: plain X.Y.Z — a release is immutable, and its id must name it exactly */
+const RELEASE_VERSION_RE = /^\d+\.\d+\.\d+$/;
+
+/** the version a distribution is built under, or a build error saying what it must be */
+export function releaseVersionOf(version, namespace, dir) {
+  if (typeof version !== 'string' || !RELEASE_VERSION_RE.test(version)) {
+    throw new Error(`tile palette ${namespace} (${dir}): version "${version}" is not X.Y.Z — a deployed version never changes, and its tile ids must name it exactly (pre-releases are not supported)`);
+  }
+  return version;
+}
+
+/**
+ * Distributive roots = the app itself (if type library) + `libraries` + `devLibraries` (dev only).
+ * Each: { dir, namespace, version, isDev }.
+ */
+export function discoverRoots(fileSystem, root, { resolver, includeDev = true, log = SILENT } = {}) {
+  const cfg = readConfig(fileSystem, root);
+  const pkg = readPkg(fileSystem, root);
+  const roots = [];
+
+  if (cfg.type === 'library') {
+    roots.push({ dir: root, namespace: cfg.namespace, version: releaseVersionOf(pkg.version, cfg.namespace, root), isDev: false });
+  }
+
+  const resolveLib = (lib, isDev) => {
+    // editor & co. only export '.', so resolve the main entry then walk up to its package.json.
+    let mainPath;
+    try {
+      mainPath = resolver.resolve(lib, root);
+    } catch (e) {
+      log(`  ! library ${lib} not resolved (${e.code || e.message}) — skipped`);
+      return null;
+    }
+    const dir = packageDirOf(fileSystem, mainPath);
+    if (!dir) {
+      log(`  ! library ${lib}: package.json not found — skipped`);
+      return null;
+    }
+    const libCfg = readConfig(fileSystem, dir);
+    const libPkg = readPkg(fileSystem, dir);
+    return { dir, namespace: libCfg.namespace, version: releaseVersionOf(libPkg.version, libCfg.namespace, dir), isDev };
+  };
+
+  for (const lib of cfg.libraries || []) {
+    const r = resolveLib(lib, false);
+    if (r) roots.push(r);
+  }
+  if (includeDev) {
+    for (const lib of cfg.devLibraries || []) {
+      const r = resolveLib(lib, true);
+      if (r) roots.push(r);
+    }
+  }
+  return roots;
+}
+
+// Walk <root.dir>/tiles (the tile sources) for entries matching the naming convention whose type passes `keepType`.
+// Returns [{ file, name, type, namespace, version }].
+function collectModules(fileSystem, { dir, namespace, version }, keepType) {
+  const modulesDir = path.join(dir, 'tiles');
+  const out = [];
+  if (!fileSystem.exists(modulesDir)) return out;
+
+  const walk = (d) => {
+    for (const entry of fileSystem.readDir(d)) {
+      const p = path.join(d, entry.name);
+      if (entry.isDirectory) {
+        walk(p);
+        continue;
+      }
+      const m = MODULE_FILE_RE.exec(entry.name);
+      if (!m) continue;
+      if (path.basename(path.dirname(p)) !== m.groups.name) continue;
+      if (!keepType(m.groups.type)) continue;
+      out.push({ file: p, name: m.groups.name, type: m.groups.type, namespace, version });
+    }
+  };
+
+  walk(modulesDir);
+  return out;
+}
+
+/**
+ * Discover CLIENT module entries (everything except server-only types → the browser distributive).
+ */
+export function discoverModulesIn(fileSystem, root) {
+  return collectModules(fileSystem, root, (type) => !NON_CLIENT_TYPES.has(type));
+}
+
+/**
+ * Discover SERVER-action module entries (`.server.ts`). Built as PRIVATE monoliths,
+ * executed in a Worker Loader isolate — not client artifacts.
+ */
+export function discoverServerModulesIn(fileSystem, root) {
+  return collectModules(fileSystem, root, (type) => type === 'server');
+}
+
+/**
+ * Discover ROUTER facets (`.router.ts`) — only to refuse them: there is no router any more
+ * (ADR-0053), the build names a leftover facet instead of ignoring it.
+ */
+export function discoverRouterModulesIn(fileSystem, root) {
+  return collectModules(fileSystem, root, (type) => type === 'router');
+}
+
+// Revisioned content entity: `<collection>/<name>/<metaFile>` + `versions/<rev>.json`.
+// Only the LIVE (published) revision is distributed; entities without a live revision (drafts only)
+// are editor-material and never reach the dist. Returns { meta, json } or null.
+function readLiveEntity(fileSystem, collectionDir, name, metaFile, log) {
+  let meta;
+  try {
+    meta = fileSystem.readJson(path.join(collectionDir, name, metaFile));
+  } catch {
+    return null;
+  }
+  if (!meta || typeof meta.live !== 'number') return null;
+  let json;
+  try {
+    json = fileSystem.readJson(path.join(collectionDir, name, 'versions', `${meta.live}.json`));
+  } catch {
+    log(`  ! ${name}: live revision ${meta.live} file missing/broken — skipped`);
+    return null;
+  }
+  return { meta, json };
+}
+
+function discoverEntitiesIn(fileSystem, dir, collection, metaFile, log) {
+  const collectionDir = path.join(dir, collection);
+  const out = [];
+  if (!fileSystem.exists(collectionDir)) return out;
+  for (const entry of fileSystem.readDir(collectionDir)) {
+    if (!entry.isDirectory || !ENTITY_NAME_RE.test(entry.name)) continue;
+    const live = readLiveEntity(fileSystem, collectionDir, entry.name, metaFile, log);
+    if (live) out.push({ name: entry.name, ...live });
+  }
+  return out;
+}
+
+/**
+ * Discover prefabs (live revisions) in <dir>/prefabs. Returns [{ name, type, json }] —
+ * type comes from the entity meta (it moved out of the file name).
+ */
+export function discoverPrefabsIn(fileSystem, dir, log = SILENT) {
+  return discoverEntitiesIn(fileSystem, dir, 'prefabs', 'prefab.json', log)
+    .map(({ name, meta, json }) => ({ name, type: meta.type || 'unit', json }));
+}
+
+// Pages are a SEPARATE collection from prefabs (prefabs are reusable templates; a page is a routed,
+// servable tree). Folder per page in `<root>/pages/<name>/` (meta + revisions). Edited by
+// the content manager (in dev — coder via the local editor); in prod they live in S3.
+export function discoverPagesIn(fileSystem, dir, log = SILENT) {
+  return discoverEntitiesIn(fileSystem, dir, 'pages', 'page.json', log)
+    .map(({ name, json }) => ({ name, json }));
+}

package/src/fileSystem.mjs

@@ -0,0 +1,69 @@
+/**
+ * Build environment port: file system, READ-ONLY.
+ *
+ * The name is literal: the port answers exactly the questions about files. Package resolution
+ * is not part of it — that is a separate abstraction (`PackagesResolver`) ON TOP of the port:
+ * it needs files, but is itself policy over the package catalog, not an environment capability.
+ * Pure math — `node:path` and `node:crypto` — is deliberately outside the port: both modules
+ * exist in workerd under `nodejs_compat`, and wrapping them would breed an abstraction with no
+ * second implementation.
+ *
+ * The port ONLY READS: no writes, no execution. This is not tidiness but a property —
+ * the build isolate has no capability to change anything; artifacts leave as the return value.
+ *
+ * The contract is deliberately SYNCHRONOUS on reads: both rollup and postcss call these
+ * operations from their synchronous places. A network implementation is not hindered — it
+ * arrives with an already-warmed slice (the plan knows the closure in advance) instead of
+ * fetching each file at call time.
+ */
+export class FileSystem {
+  /** Read a source file. `encoding: 'utf8'` → string, otherwise binary (Uint8Array-compatible). */
+  readFile(_file, _encoding = null) {
+    throw new Error('FileSystem.readFile is not implemented');
+  }
+
+  /** Read + parse JSON. The default is expressed via readFile — implementations need not override. */
+  readJson(file) {
+    return JSON.parse(this.readFile(file, 'utf8'));
+  }
+
+  exists(_file) {
+    throw new Error('FileSystem.exists is not implemented');
+  }
+
+  /** Directory listing as [{ name, isDirectory }]. */
+  readDir(_dir) {
+    throw new Error('FileSystem.readDir is not implemented');
+  }
+
+  /**
+   * Is this a directory. Needed by the resolver: `exists` does not tell a file from a directory,
+   * and the difference matters — with both `foo.js` and `foo/` present, node picks the FILE.
+   * The answer must be SELF-SUFFICIENT, not derived from other calls (spike lesson: on a
+   * case-insensitive FS `exists('src/Router')` answers for the `router/` directory, and a
+   * derivation from the file map diverges from the truth).
+   */
+  isDirectory(dir) {
+    try {
+      this.readDir(dir);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Canonical path of a file. On node this is symlink dereferencing (pnpm workspace layout);
+   * for a graph implementation it is identity: package identity is baked into the id, symlinks
+   * do not exist.
+   */
+  realPath(_file) {
+    throw new Error('FileSystem.realPath is not implemented');
+  }
+
+  /** Mtime in milliseconds, or null when the file is missing. Needed by freshness-validated caches. */
+  mtimeMs(_file) {
+    throw new Error('FileSystem.mtimeMs is not implemented');
+  }
+
+}

package/src/format.mjs

@@ -0,0 +1,4 @@
+/** Human-readable size for build reports. Pure function — touches no environment. */
+export function formatBytes(bytes) {
+  return bytes < 1024 ? `${bytes} B` : `${(bytes / 1024).toFixed(1)} KB`;
+}

package/src/hash.mjs

@@ -0,0 +1,13 @@
+import { crypto, path } from './nodeApi.mjs';
+
+// Short content hash for asset cache-busting (build-time; Node crypto is fine here).
+export function shortHash(buffer) {
+  return crypto.createHash('sha1').update(buffer).digest('hex').slice(0, 8);
+}
+
+// `image.png` + <buf> -> `image_a1b2c3d4.png`
+export function hashedAssetName(sourcePath, buffer) {
+  const ext = path.extname(sourcePath);
+  const base = path.basename(sourcePath, ext);
+  return `${base}_${shortHash(buffer)}${ext}`;
+}

package/src/memoryFileSystem.mjs

@@ -0,0 +1,81 @@
+import { path } from './nodeApi.mjs';
+import { FileSystem } from './fileSystem.mjs';
+
+/**
+ * IN-MEMORY file port (build-action): the unpacked build body — a "path → bytes" map plus a
+ * directory index derived on insertion. Case is EXACT (unlike macOS — the `isDirectory` lesson:
+ * the port's answers are self-sufficient, nothing to derive). `realPath` is identity (symlinks
+ * do not exist in the plan), `mtimeMs` is null (freshness caches have nothing to validate: the
+ * plan is immutable).
+ */
+export class MemoryFileSystem extends FileSystem {
+  constructor() {
+    super();
+    this.files = new Map(); // absolute path -> Uint8Array
+    this.children = new Map(); // directory -> Map(name -> isDirectory)
+  }
+
+  set(file, bytes) {
+    this.files.set(file, bytes);
+    let name = path.basename(file);
+    let dir = path.dirname(file);
+    let isDir = false;
+    for (;;) {
+      let listing = this.children.get(dir);
+      if (!listing) {
+        listing = new Map();
+        this.children.set(dir, listing);
+      }
+      const known = listing.has(name);
+      listing.set(name, listing.get(name) || isDir);
+      if (known) break;
+      name = path.basename(dir);
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+      isDir = true;
+    }
+  }
+
+  readFile(file, encoding = null) {
+    const bytes = this.files.get(file);
+    if (bytes === undefined) {
+      const e = new Error(`ENOENT: ${file}`);
+      e.code = 'ENOENT';
+      throw e;
+    }
+    return encoding ? new TextDecoder().decode(bytes) : bytes;
+  }
+
+  exists(file) {
+    return this.files.has(file) || this.children.has(file);
+  }
+
+  readDir(dir) {
+    const listing = this.children.get(dir);
+    if (!listing) {
+      const e = new Error(`ENOENT: ${dir} is not a directory`);
+      e.code = 'ENOENT';
+      throw e;
+    }
+    return [...listing].map(([name, isDirectory]) => ({ name, isDirectory }));
+  }
+
+  isDirectory(dir) {
+    return this.children.has(dir);
+  }
+
+  realPath(file) {
+    if (!this.exists(file)) {
+      const e = new Error(`ENOENT: ${file}`);
+      e.code = 'ENOENT';
+      throw e;
+    }
+    return file;
+  }
+
+  mtimeMs() {
+    return null;
+  }
+
+}

package/src/moduleName.mjs

@@ -0,0 +1,11 @@
+// Canonical module-name encoding: _ns_<namespace>_t_<type>_n_<name>_v_<version>
+// Pure naming primitives live in @mosetta/runtime (browser-safe, shared with the runtime resolver).
+import { normalizeVersion } from '@mosetta/runtime/naming';
+
+export { normalizeVersion, dependencyFullId } from '@mosetta/runtime/naming';
+
+export const NAME_TOKENS = { ns: '_ns_', t: '_t_', n: '_n_', v: '_v_' };
+
+export function fullTileName({ namespace, type, name, version }) {
+  return `${NAME_TOKENS.ns}${namespace}${NAME_TOKENS.t}${type}${NAME_TOKENS.n}${name}${NAME_TOKENS.v}${normalizeVersion(version)}`;
+}

package/src/nodeApi.mjs

@@ -0,0 +1,22 @@
+/* eslint-disable no-restricted-imports -- the ONLY place in the package where `node:*` is allowed */
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { builtinModules } from 'node:module';
+
+/**
+ * The showcase of standard library allowed to the builder.
+ *
+ * The rest of the package is FORBIDDEN by lint to import `node:*` — otherwise an environment
+ * access sneaks in unnoticed and only surfaces in an isolate. Here the exception list is visible
+ * in full, and each entry must stay true: these are **pure computations**, not environment
+ * capabilities, and all three modules exist in workerd under `nodejs_compat` (verified on
+ * `workerd@1.20260719.1`).
+ *
+ * If something else is ever needed, that is a reason not to add a line here but to ask whether
+ * the new need is an ENVIRONMENT capability. Those go into the port (`BuildHost`), not this file.
+ *
+ * - `path`   — string math over paths, does no I/O;
+ * - `crypto` — hashes (`sha1` for asset names, `sha256` for SRI), also a pure function of bytes;
+ * - `builtinModules` — just a LIST OF NAMES: target-environment policy (the browser has no node builtins).
+ */
+export { path, crypto, builtinModules };

package/src/packageMeta.mjs

@@ -0,0 +1,37 @@
+import { path } from './nodeApi.mjs';
+
+// Metadata of the package owning a file — free functions OVER the port (like probeFile):
+// a pure upward walk over files that needs no second implementation, so it is neither a port
+// method nor a resolver method but logic shared by both.
+
+const MAX_WALK_UP = 50;
+
+/** Directory of the nearest package.json upwards, or null. */
+export function packageDirOf(fileSystem, file) {
+  let dir = path.dirname(file);
+  for (let i = 0; i < MAX_WALK_UP; i++) {
+    if (fileSystem.exists(path.join(dir, 'package.json'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/** Version from the nearest package.json upwards ('0.0.0' when not found). */
+export function packageVersionOf(fileSystem, file) {
+  let dir = path.dirname(file);
+  for (let i = 0; i < MAX_WALK_UP; i++) {
+    const pj = path.join(dir, 'package.json');
+    if (fileSystem.exists(pj)) {
+      try {
+        const v = fileSystem.readJson(pj).version;
+        if (v) return v;
+      } catch { /* ignore malformed */ }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return '0.0.0';
+}