xbintsc 0.3.13 → 0.3.15

package/src/driver/modules.ts

@@ -13,7 +13,7 @@
  */
 
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { dirname, isAbsolute, resolve } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import {
   ModifierKind,
   SyntaxKind,
@@ -55,27 +55,50 @@ export interface BundleResult {
   readonly moduleCount: number;
 }
 
-const RESOLVE_SUFFIXES = ["", ".ts", ".tsx", ".mts", ".cts", "/index.ts", "/index.tsx"];
-
 /**
- * Bare module specifiers (`fs`, `node:fs`, `@scope/pkg`) are not files to
- * bundle: they are resolved at code generation time against the registered
- * extension modules.
+ * Source extensions probed for an extension-less specifier. TypeScript suffixes
+ * are tried before their JavaScript counterparts so a project that ships both
+ * `foo.ts` and a compiled `foo.js` prefers the source it is compiled from.
  */
-function isExternalSpecifier(specifier: string): boolean {
-  return !specifier.startsWith(".") && !isAbsolute(specifier);
+const RESOLVE_SUFFIXES = ["", ".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
+/** File extensions a directory `index` entry may use. */
+const INDEX_SUFFIXES = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
+/** Conditions consulted, in order, when reading a package `exports` map. */
+const EXPORT_CONDITIONS = ["import", "module", "default", "node", "require"];
+
+/** A specifier is a file path (`./x`, `../x`, `/x`) rather than a package. */
+function isRelativeSpecifier(specifier: string): boolean {
+  return specifier.startsWith(".") || isAbsolute(specifier);
 }
 
-function resolveModule(fromDir: string, specifier: string): string | undefined {
-  const base = resolve(fromDir, specifier);
-  // TypeScript sources are imported using their emitted `.js` extension
-  // (`import ... from "./foo.js"`), so map the extension back to the source
-  // file before probing the usual suffixes.
+/**
+ * Resolve a path on disk, tolerating TypeScript's `.js` import convention
+ * (`import "./foo.js"` pointing at `foo.ts`) and Node's directory/`index`
+ * conventions.
+ */
+function resolvePath(base: string): string | undefined {
+  // A JavaScript specifier may refer to a TypeScript source that will emit it
+  // (`import "./foo.js"` pointing at `foo.ts`). Probe the matching TypeScript
+  // extensions after the literal path: `.js`/`.jsx` -> `.ts`/`.tsx`,
+  // `.mjs` -> `.mts`, `.cjs` -> `.cts`.
   const candidates = [base];
-  const jsExtension = /\.(?:m|c)?jsx?$/.exec(base);
+  const jsExtension = /\.((?:m|c)?jsx?)$/.exec(base);
   if (jsExtension) {
     const stem = base.slice(0, jsExtension.index);
-    candidates.push(`${stem}.ts`, `${stem}.tsx`, `${stem}.mts`, `${stem}.cts`);
+    switch (jsExtension[1]) {
+      case "jsx":
+        candidates.push(`${stem}.tsx`, `${stem}.ts`);
+        break;
+      case "mjs":
+        candidates.push(`${stem}.mts`);
+        break;
+      case "cjs":
+        candidates.push(`${stem}.cts`);
+        break;
+      default:
+        candidates.push(`${stem}.ts`, `${stem}.tsx`);
+        break;
+    }
   }
   for (const candidate of candidates) {
     if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
@@ -84,9 +107,197 @@ function resolveModule(fromDir: string, specifier: string): string | undefined {
     const candidate = base + suffix;
     if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
   }
+  if (existsSync(base) && statSync(base).isDirectory()) return resolveDirectory(base);
+  return undefined;
+}
+
+/** Resolve a directory to its package entry or an `index` file. */
+function resolveDirectory(directory: string): string | undefined {
+  const pkg = readPackageJson(directory);
+  if (pkg && typeof pkg.main === "string") {
+    const main = resolvePath(resolve(directory, pkg.main));
+    if (main) return main;
+  }
+  for (const suffix of INDEX_SUFFIXES) {
+    const candidate = join(directory, `index${suffix}`);
+    if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
+  }
+  return undefined;
+}
+
+function resolveModule(fromDir: string, specifier: string): string | undefined {
+  return resolvePath(resolve(fromDir, specifier));
+}
+
+interface PackageJson {
+  readonly main?: string;
+  readonly module?: string;
+  readonly exports?: unknown;
+}
+
+function readPackageJson(directory: string): PackageJson | undefined {
+  const file = join(directory, "package.json");
+  if (!existsSync(file) || !statSync(file).isFile()) return undefined;
+  try {
+    const parsed = JSON.parse(readFileSync(file, "utf8")) as unknown;
+    return parsed && typeof parsed === "object" ? (parsed as PackageJson) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Split `pkg/sub/path` or `@scope/pkg/sub/path` into package name and subpath. */
+function splitPackageSpecifier(specifier: string): { packageName: string; subpath: string } {
+  const parts = specifier.split("/");
+  if (specifier.startsWith("@")) {
+    return { packageName: parts.slice(0, 2).join("/"), subpath: parts.slice(2).join("/") };
+  }
+  return { packageName: parts[0] ?? specifier, subpath: parts.slice(1).join("/") };
+}
+
+/**
+ * Resolve a bare specifier against the `node_modules` directories above
+ * `fromDir`, following a package's `exports` map and falling back to
+ * `module`/`main`/`index`. Packages that only ship CommonJS resolve here too;
+ * their `require` calls are then rejected during code generation.
+ */
+function resolveNodePackage(fromDir: string, specifier: string): string | undefined {
+  const { packageName, subpath } = splitPackageSpecifier(specifier);
+  if (!packageName || packageName.startsWith(".")) return undefined;
+  let directory = fromDir;
+  for (;;) {
+    const packageDir = join(directory, "node_modules", packageName);
+    if (existsSync(packageDir) && statSync(packageDir).isDirectory()) {
+      const resolved = subpath
+        ? resolvePackageSubpath(packageDir, subpath)
+        : resolvePackageEntry(packageDir);
+      if (resolved) return resolved;
+    }
+    const parent = dirname(directory);
+    if (parent === directory) return undefined;
+    directory = parent;
+  }
+}
+
+function resolvePackageEntry(packageDir: string): string | undefined {
+  const pkg = readPackageJson(packageDir);
+  if (pkg) {
+    const exported = resolveExportTarget(subpathValue(pkg.exports, "."));
+    if (exported) {
+      const resolved = resolvePath(resolve(packageDir, exported));
+      if (resolved) return resolved;
+    }
+    if (typeof pkg.module === "string") {
+      const resolved = resolvePath(resolve(packageDir, pkg.module));
+      if (resolved) return resolved;
+    }
+    if (typeof pkg.main === "string") {
+      const resolved = resolvePath(resolve(packageDir, pkg.main));
+      if (resolved) return resolved;
+    }
+  }
+  return resolveDirectory(packageDir);
+}
+
+function resolvePackageSubpath(packageDir: string, subpath: string): string | undefined {
+  const pkg = readPackageJson(packageDir);
+  const exported = resolveExportTarget(subpathValue(pkg?.exports, `./${subpath}`));
+  if (exported) {
+    const resolved = resolvePath(resolve(packageDir, exported));
+    if (resolved) return resolved;
+  }
+  return resolvePath(join(packageDir, subpath));
+}
+
+/** Pick the export target for a subpath (`"."` or `"./sub"`) from an exports map. */
+function subpathValue(exportsField: unknown, subpath: string): unknown {
+  if (exportsField === undefined) return undefined;
+  if (typeof exportsField === "string" || Array.isArray(exportsField)) {
+    return subpath === "." ? exportsField : undefined;
+  }
+  if (!exportsField || typeof exportsField !== "object") return undefined;
+  const record = exportsField as Record<string, unknown>;
+  const keys = Object.keys(record);
+  // A map without `.`-prefixed keys is a condition map for the root export.
+  if (!keys.some((key) => key.startsWith("."))) {
+    return subpath === "." ? exportsField : undefined;
+  }
+  if (subpath in record) return record[subpath];
+  // Wildcard patterns such as `"./*": "./dist/*.js"`.
+  for (const key of keys) {
+    const star = key.indexOf("*");
+    if (star === -1) continue;
+    const prefix = key.slice(0, star);
+    const suffix = key.slice(star + 1);
+    if (subpath.startsWith(prefix) && subpath.endsWith(suffix)) {
+      const matched = subpath.slice(prefix.length, subpath.length - suffix.length);
+      return substituteStar(record[key], matched);
+    }
+  }
+  return undefined;
+}
+
+function substituteStar(target: unknown, matched: string): unknown {
+  if (typeof target === "string") return target.split("*").join(matched);
+  if (Array.isArray(target)) return target.map((entry) => substituteStar(entry, matched));
+  if (target && typeof target === "object") {
+    const record: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(target)) record[key] = substituteStar(value, matched);
+    return record;
+  }
+  return target;
+}
+
+/** Pick a runtime string from a (possibly conditional) exports target. */
+function resolveExportTarget(target: unknown): string | undefined {
+  if (typeof target === "string") return target;
+  if (Array.isArray(target)) {
+    for (const entry of target) {
+      const resolved = resolveExportTarget(entry);
+      if (resolved) return resolved;
+    }
+    return undefined;
+  }
+  if (target && typeof target === "object") {
+    const record = target as Record<string, unknown>;
+    for (const condition of EXPORT_CONDITIONS) {
+      if (condition in record) {
+        const resolved = resolveExportTarget(record[condition]);
+        if (resolved) return resolved;
+      }
+    }
+  }
   return undefined;
 }
 
+type DependencyResolution =
+  | { readonly kind: "external" }
+  | { readonly kind: "file"; readonly path: string }
+  | { readonly kind: "missing" };
+
+/**
+ * Classify an import specifier. Known platform modules (extension modules and
+ * `node:` builtins) are left for code generation; relative paths and
+ * `node_modules` packages are resolved to a source file to bundle; a relative
+ * path that does not exist is an error.
+ */
+function classifyDependency(
+  fromDir: string,
+  specifier: string,
+  externalSpecifiers: ReadonlySet<string>,
+): DependencyResolution {
+  if (specifier.startsWith("node:") || externalSpecifiers.has(specifier)) {
+    return { kind: "external" };
+  }
+  const resolved = isRelativeSpecifier(specifier)
+    ? resolveModule(fromDir, specifier)
+    : resolveNodePackage(fromDir, specifier);
+  if (resolved) return { kind: "file", path: resolved };
+  // A bare specifier that is not a file may still be a platform module the
+  // generator knows about (e.g. when the caller passes no extension registry).
+  return isRelativeSpecifier(specifier) ? { kind: "missing" } : { kind: "external" };
+}
+
 function hasModifier(node: Node, kind: ModifierKind): boolean {
   const modifiers = (node as { modifiers?: { modifierKind: ModifierKind }[] }).modifiers;
   return !!modifiers && modifiers.some((modifier) => modifier.modifierKind === kind);
@@ -111,7 +322,11 @@ function declarationName(node: Node): Identifier | undefined {
 }
 
 /** Load, parse and bind the entry module and every module it imports. */
-function loadGraph(entryPath: string, diagnostics: DiagnosticBag): ModuleRecord[] | undefined {
+function loadGraph(
+  entryPath: string,
+  diagnostics: DiagnosticBag,
+  externalSpecifiers: ReadonlySet<string>,
+): ModuleRecord[] | undefined {
   const records = new Map<string, ModuleRecord>();
   const order: ModuleRecord[] = [];
   const visiting = new Set<string>();
@@ -152,9 +367,9 @@ function loadGraph(entryPath: string, diagnostics: DiagnosticBag): ModuleRecord[
     for (const statement of sourceFile.statements) {
       const specifier = moduleSpecifierOf(statement);
       if (!specifier) continue;
-      if (isExternalSpecifier(specifier)) continue;
-      const dependency = resolveModule(dirname(path), specifier);
-      if (!dependency) {
+      const dependency = classifyDependency(dirname(path), specifier, externalSpecifiers);
+      if (dependency.kind === "external") continue;
+      if (dependency.kind === "missing") {
         diagnostics.error(
           DiagnosticCode.CodegenError,
           `Cannot resolve module '${specifier}' from '${path}'`,
@@ -164,7 +379,7 @@ function loadGraph(entryPath: string, diagnostics: DiagnosticBag): ModuleRecord[
         failed = true;
         continue;
       }
-      load(dependency);
+      load(dependency.path);
     }
     visiting.delete(path);
     order.push(record);
@@ -215,14 +430,18 @@ function topLevelSymbols(record: ModuleRecord): SymbolInfo[] {
  * Merge every module's statements into a single file. Dependencies come first
  * (post-order over the import graph), the entry module last.
  */
-export function bundleModules(entryPath: string, diagnostics: DiagnosticBag): BundleResult | undefined {
-  const records = loadGraph(entryPath, diagnostics);
+export function bundleModules(
+  entryPath: string,
+  diagnostics: DiagnosticBag,
+  externalSpecifiers: ReadonlySet<string> = new Set(),
+): BundleResult | undefined {
+  const records = loadGraph(entryPath, diagnostics, externalSpecifiers);
   if (!records) return undefined;
 
   const byPath = new Map(records.map((record) => [record.path, record]));
   const dependencyOf = (record: ModuleRecord, specifier: string): ModuleRecord | undefined => {
-    const resolved = resolveModule(dirname(record.path), specifier);
-    return resolved ? byPath.get(resolved) : undefined;
+    const resolution = classifyDependency(dirname(record.path), specifier, externalSpecifiers);
+    return resolution.kind === "file" ? byPath.get(resolution.path) : undefined;
   };
 
   // Phase 1: record every top-level binding and pick a unique final name.
@@ -328,8 +547,14 @@ export function bundleModules(entryPath: string, diagnostics: DiagnosticBag): Bu
   for (const record of records) {
     for (const statement of record.sourceFile.statements) {
       if (statement.kind === SyntaxKind.ImportDeclaration) {
-        // External (extension) imports stay in place for code generation.
-        if (isExternalSpecifier((statement as ImportDeclaration).moduleSpecifier.value)) {
+        // External (extension / built-in) imports stay in place for codegen.
+        const declaration = statement as ImportDeclaration;
+        const resolution = classifyDependency(
+          dirname(record.path),
+          declaration.moduleSpecifier.value,
+          externalSpecifiers,
+        );
+        if (resolution.kind === "external") {
           merged.push(statement);
         } else {
           const synthetic = namespaceStatements.get(statement);

package/src/driver/paths.ts

@@ -22,15 +22,6 @@ export function findRuntimeDir(): string {
   throw new Error("Unable to locate the xbintsc runtime directory (missing runtime/rt.h)");
 }
 
-export function findPackageRoot(): string {
-  return resolve(findRuntimeDir(), "..");
-}
-
-/** `<package>/vendor` — where a bundled toolchain is assembled (may not exist). */
-export function vendorRootDir(): string {
-  return resolve(findPackageRoot(), "vendor");
-}
-
 /** Platform-architecture slug, e.g. `darwin-arm64`, `linux-x64`, `win32-x64`. */
 export function platformSlug(): string {
   return `${process.platform}-${process.arch}`;
@@ -68,25 +59,3 @@ export function releaseArchiveFileName(
 export function releaseArchiveExtension(useZstd: boolean): string {
   return useZstd ? ".tar.zst" : ".tar.gz";
 }
-
-/**
- * Directory that may hold a toolchain shipped next to the package:
- * `<package>/vendor/<os>-<arch>` (or a generic `vendor/`). Undefined when none
- * is present, in which case the driver falls back to the system PATH.
- */
-export function findVendorDir(): string | undefined {
-  const roots: string[] = [];
-  try {
-    roots.push(findPackageRoot());
-  } catch {
-    // `runtime/` may be absent (e.g. a bare `emit` install); vendor is optional.
-  }
-  roots.push(resolve(here, "../../.."), resolve(here, "../.."), process.cwd());
-  for (const root of roots) {
-    const specific = join(root, "vendor", platformSlug());
-    if (existsSync(specific)) return specific;
-    const generic = join(root, "vendor");
-    if (existsSync(generic)) return generic;
-  }
-  return undefined;
-}

package/src/driver/toolchain-provider.ts

@@ -3,23 +3,23 @@
  *
  * xbintsc shells out to a clang-compatible driver for three jobs: lowering LLVM
  * IR to an object, compiling the C runtime, and linking. This module decides
- * *which* driver to use, in a fixed priority order, so a bundled toolchain can
- * shadow the system one without touching the driver code:
+ * *which* driver to use, in a fixed priority order:
  *
  *   1. an explicit `xbintsc_CLANG` / `xbintsc_TOOLCHAIN`
- *   2. a toolchain shipped next to the package (`vendor/<os>-<arch>/bin`)
- *   3. the system `PATH` (`findClang`)
+ *   2. the system `PATH` (`findClang`)
+ *
+ * xbintsc does not ship a compiler. Every host must provide a clang-compatible
+ * toolchain (see `doc/requirements.md`): the Xcode Command Line Tools on macOS,
+ * the distribution's clang/lld on Linux, and LLVM plus the Visual Studio C++
+ * build tools (the MSVC ABI) on Windows.
  *
  * Extra linker arguments (for example `-fuse-ld=lld`) can be supplied through
  * `xbintsc_LINKER_ARGS`.
  */
 
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import { findVendorDir } from "./paths.js";
 import { findClang, realRunner, type Runner } from "./toolchain.js";
 
-export type ToolchainSource = "env" | "vendor" | "system";
+export type ToolchainSource = "env" | "system";
 
 export interface ResolvedToolchain {
   /** Path or name of the clang-compatible driver to invoke. */
@@ -28,17 +28,14 @@ export interface ResolvedToolchain {
   readonly source: ToolchainSource;
   /** Extra arguments to pass to the link step. */
   readonly linkerArgs: readonly string[];
-  /**
-   * Extra environment for the toolchain subprocesses, merged over the current
-   * environment. Used to point `LD_LIBRARY_PATH` at bundled shared libraries
-   * (for example the legacy `libtinfo.so.5` the official Linux build needs).
-   */
+  /** Extra environment for the toolchain subprocesses, merged over the current
+   * environment. */
   readonly env: Record<string, string>;
 }
 
-function works(runner: Runner, command: string, env?: Record<string, string>): boolean {
+function works(runner: Runner, command: string): boolean {
   try {
-    return runner.run(command, ["--version"], env ? { env } : undefined).status === 0;
+    return runner.run(command, ["--version"]).status === 0;
   } catch {
     return false;
   }
@@ -50,18 +47,6 @@ function linkerArgs(fallback: readonly string[]): string[] {
   return [...fallback];
 }
 
-/**
- * Environment overrides for a bundled toolchain. The official Linux build links
- * the removed `libtinfo.so.5` soname, so when we ship it under `vendor/lib/` we
- * prepend that directory to the dynamic linker search path.
- */
-function vendorEnv(vendor: string): Record<string, string> {
-  const libDir = join(vendor, "lib");
-  if (process.platform !== "linux" || !existsSync(libDir)) return {};
-  const existing = process.env.LD_LIBRARY_PATH;
-  return { LD_LIBRARY_PATH: existing ? libDir + ":" + existing : libDir };
-}
-
 /** Resolve the toolchain that `build` should use. See the module docblock. */
 export function resolveToolchain(runner: Runner = realRunner): ResolvedToolchain {
   const explicit = process.env.xbintsc_CLANG ?? process.env.xbintsc_TOOLCHAIN;
@@ -69,23 +54,5 @@ export function resolveToolchain(runner: Runner = realRunner): ResolvedToolchain
     return { clang: explicit, source: "env", linkerArgs: linkerArgs([]), env: {} };
   }
 
-  const vendor = findVendorDir();
-  if (vendor) {
-    const env = vendorEnv(vendor);
-    const names = process.platform === "win32" ? ["clang.exe", "clang"] : ["clang"];
-    for (const name of names) {
-      const candidate = join(vendor, "bin", name);
-      if (existsSync(candidate) && works(runner, candidate, env)) {
-        // A bundled toolchain ships `ld.lld`, so prefer lld over any system linker.
-        return {
-          clang: candidate,
-          source: "vendor",
-          linkerArgs: linkerArgs(["-fuse-ld=lld"]),
-          env,
-        };
-      }
-    }
-  }
-
   return { clang: findClang(runner), source: "system", linkerArgs: linkerArgs([]), env: {} };
 }

package/src/driver/toolchain.ts

@@ -64,8 +64,13 @@ export function findClang(runner: Runner = realRunner): string {
     "cc",
   ].filter((candidate): candidate is string => Boolean(candidate));
   for (const candidate of candidates) {
-    const result = runner.run(candidate, ["--version"]);
-    if (result.status === 0) return candidate;
+    let status: number;
+    try {
+      status = runner.run(candidate, ["--version"]).status;
+    } catch {
+      continue;
+    }
+    if (status === 0) return candidate;
   }
   throw new ToolchainError("clang --version", 1, "No C compiler found. Set xbintsc_CLANG to a clang binary.");
 }

package/src/extensions/native.ts

@@ -18,9 +18,8 @@
  * {
  *   "name": "mathx",
  *   "description": "C++ math helpers",
- *   "objects": ["build/libmathx.a"],
- *   "linkerFlags": ["-lm"],
- *   "linkerFlagsByPlatform": { "linux": ["-lstdc++"], "darwin": ["-lc++"] },
+ *   "objects": ["build/mathx.o"],
+ *   "linkerFlagsByPlatform": { "linux": ["-lstdc++", "-lm"], "darwin": ["-lc++"], "win32": ["-lmsvcprt"] },
  *   "builtins": { "fastAdd": { "symbol": "mathx_add" } },
  *   "modules": {
  *     "mathx": {

package/src/extensions/node/fs/fs-ops.ts

@@ -1,20 +1,62 @@
 /**
- * Builtins for the filesystem operations in Node's `fs` module
- * (`existsSync`, directory handling, rename/copy, `statSync`, ...).
+ * Builtins for the filesystem operations in Node's `fs` module.
+ *
+ * Every runtime symbol uses the uniform `xt_value fn(int32_t, xt_value *)`
+ * ABI. xbintsc has no event loop, so only the synchronous API is exposed
+ * (`*Sync`), plus the watcher factories, whose objects never fire events.
  */
 
 import type { BuiltinFunction } from "../../registry.js";
 
 export const fsOpsBuiltins: Readonly<Record<string, BuiltinFunction>> = {
+  // Path / metadata -------------------------------------------------------
   existsSync: { symbol: "xt_node_exists" },
+  accessSync: { symbol: "xt_node_access" },
+  statSync: { symbol: "xt_node_stat" },
+  lstatSync: { symbol: "xt_node_lstat" },
+  statfsSync: { symbol: "xt_node_statfs" },
+  realpathSync: { symbol: "xt_node_realpath" },
+  chmodSync: { symbol: "xt_node_chmod" },
+  lchmodSync: { symbol: "xt_node_lchmod" },
+  chownSync: { symbol: "xt_node_chown" },
+  lchownSync: { symbol: "xt_node_lchown" },
+  truncateSync: { symbol: "xt_node_truncate" },
+  utimesSync: { symbol: "xt_node_utimes" },
+  lutimesSync: { symbol: "xt_node_lutimes" },
+
+  // Directories / entries -------------------------------------------------
   readdirSync: { symbol: "xt_node_read_dir" },
   mkdirSync: { symbol: "xt_node_mkdir" },
+  mkdtempSync: { symbol: "xt_node_mkdtemp" },
+  rmdirSync: { symbol: "xt_node_rmdir" },
   rmSync: { symbol: "xt_node_rm" },
   unlinkSync: { symbol: "xt_node_unlink" },
-  rmdirSync: { symbol: "xt_node_rmdir" },
   renameSync: { symbol: "xt_node_rename" },
   copyFileSync: { symbol: "xt_node_copy_file" },
-  realpathSync: { symbol: "xt_node_realpath" },
-  statSync: { symbol: "xt_node_stat" },
-  lstatSync: { symbol: "xt_node_lstat" },
+  cpSync: { symbol: "xt_node_cp" },
+  linkSync: { symbol: "xt_node_link" },
+  symlinkSync: { symbol: "xt_node_symlink" },
+  readlinkSync: { symbol: "xt_node_readlink" },
+  opendirSync: { symbol: "xt_node_opendir" },
+  globSync: { symbol: "xt_node_glob" },
+
+  // File descriptors ------------------------------------------------------
+  openSync: { symbol: "xt_node_open" },
+  closeSync: { symbol: "xt_node_close" },
+  readSync: { symbol: "xt_node_read" },
+  writeSync: { symbol: "xt_node_write" },
+  readvSync: { symbol: "xt_node_readv" },
+  writevSync: { symbol: "xt_node_writev" },
+  fstatSync: { symbol: "xt_node_fstat" },
+  fsyncSync: { symbol: "xt_node_fsync" },
+  fdatasyncSync: { symbol: "xt_node_fdatasync" },
+  ftruncateSync: { symbol: "xt_node_ftruncate" },
+  fchmodSync: { symbol: "xt_node_fchmod" },
+  fchownSync: { symbol: "xt_node_fchown" },
+  futimesSync: { symbol: "xt_node_futimes" },
+
+  // Watchers (API-shaped, no events) --------------------------------------
+  watch: { symbol: "xt_node_watch" },
+  watchFile: { symbol: "xt_node_watch_file" },
+  unwatchFile: { symbol: "xt_node_unwatch_file" },
 };

package/src/extensions/node/fs/index.ts

@@ -1,24 +1,46 @@
 /**
  * Node's `fs` module: synchronous file and directory operations backed by
  * `runtime/ext_node/fs`. Asynchronous callbacks are not supported (xbintsc has
- * no event loop), so only the `*Sync` API is exposed. Import the functions, e.g.
- * `import { readFileSync } from "fs"`.
+ * no event loop), so the API is the `*Sync` surface plus `watch`/`watchFile`
+ * (which return API-shaped watchers that never emit).
+ *
+ * `fs.constants` and `fs.promises` are exposed as value getters, so both
+ * `import { constants } from "fs"` and the `fs.constants.F_OK` property form
+ * work.
  */
 
 import type { NodeModule } from "../module.js";
 import { resolveFrom } from "../module.js";
+import type { ModuleExports } from "../../registry.js";
 import { readFileBuiltins } from "./read-file.js";
 import { writeFileBuiltins } from "./write-file.js";
 import { fsOpsBuiltins } from "./fs-ops.js";
 import { fsStreamBuiltins } from "./streams.js";
 
+const builtins = { ...readFileBuiltins, ...writeFileBuiltins, ...fsOpsBuiltins, ...fsStreamBuiltins };
+
+const exports: ModuleExports = {
+  ...builtins,
+  constants: { valueSymbol: "xt_fs_constants" },
+  promises: { valueSymbol: "xt_fs_promises" },
+};
+
 export const fsModule: NodeModule = {
   name: "fs",
   runtimeSources: () => [
     resolveFrom(import.meta.url, "../../../../runtime/ext_node/fs/read_file.c"),
     resolveFrom(import.meta.url, "../../../../runtime/ext_node/fs/write_file.c"),
     resolveFrom(import.meta.url, "../../../../runtime/ext_node/fs/fs_ops.c"),
+    resolveFrom(import.meta.url, "../../../../runtime/ext_node/fs/fd_ops.c"),
+    resolveFrom(import.meta.url, "../../../../runtime/ext_node/fs/meta_ops.c"),
+    resolveFrom(import.meta.url, "../../../../runtime/ext_node/fs/link_ops.c"),
+    resolveFrom(import.meta.url, "../../../../runtime/ext_node/fs/copy_ops.c"),
+    resolveFrom(import.meta.url, "../../../../runtime/ext_node/fs/dir.c"),
+    resolveFrom(import.meta.url, "../../../../runtime/ext_node/fs/glob.c"),
+    resolveFrom(import.meta.url, "../../../../runtime/ext_node/fs/watch.c"),
+    resolveFrom(import.meta.url, "../../../../runtime/ext_node/fs/constants.c"),
     resolveFrom(import.meta.url, "../../../../runtime/ext_node/fs/streams.c"),
   ],
-  builtins: () => ({ ...readFileBuiltins, ...writeFileBuiltins, ...fsOpsBuiltins, ...fsStreamBuiltins }),
+  builtins: () => builtins,
+  exports: () => exports,
 };