@volter/world-core 2.0.0

package/dist/attach.cjs

@@ -0,0 +1,80 @@
+// The rung-2 dormant attach (docs/guides/route-a-cli-through-the-world.md): `import '@volter/world-core/attach'`
+// as line 1 of an entrypoint. A NO-OP unless VOLTER_WORLD is set — production
+// behavior is byte-identical. When set:
+//   • a URL ref: fetch the world manifest (blocking child — this runs at
+//     module load, before the app constructs SDK clients), apply the attach
+//     env (vendor twin URLs, suggested fake credentials, CA trust), then load
+//     the injector.
+//   • anything else (a local name whose env the launcher already exported, or
+//     plain twin-URL env vars): just load the injector.
+// The injector itself remains ./inject.cjs — this file only decides whether
+// and how to arm it.
+'use strict';
+
+const ref = process.env.VOLTER_WORLD;
+if (ref) {
+  if (/^https?:\/\//i.test(ref)) {
+    const { spawnSync } = require('node:child_process');
+    const { mkdtempSync, readFileSync, writeFileSync } = require('node:fs');
+    const { tmpdir } = require('node:os');
+    const { join } = require('node:path');
+    const url = ref.replace(/\/$/, '').endsWith('/.well-known/volter-world')
+      ? ref.replace(/\/$/, '')
+      : `${ref.replace(/\/$/, '')}/.well-known/volter-world`;
+    const token = process.env.VOLTER_WORLD_TOKEN;
+    // a blocking fetch at module load: spawn a child that prints the manifest
+    const probe = spawnSync(
+      process.execPath,
+      ['-e', 'fetch(process.argv[1],process.argv[2]?{headers:{authorization:"Bearer "+process.argv[2]}}:undefined).then(r=>{if(!r.ok)throw new Error(r.status);return r.text()}).then(t=>process.stdout.write(t)).catch(e=>{console.error(String(e));process.exit(1)})', url, ...(token ? [token] : [])],
+      // the child must NOT inherit NODE_OPTIONS/VOLTER_WORLD — it would
+      // re-run this very file at its own startup (a spawn recursion bomb)
+      { encoding: 'utf8', env: { ...process.env, NODE_OPTIONS: '', VOLTER_WORLD: '' } },
+    );
+    if (probe.status !== 0) {
+      throw new Error(`[twin-attach] could not fetch the world manifest from ${url}: ${(probe.stderr || '').trim()}`);
+    }
+    const manifest = JSON.parse(probe.stdout);
+    for (const [vendor, origin] of Object.entries(manifest.vendors ?? {})) {
+      const key = `${vendor.toUpperCase()}_TWIN_URL`;
+      if (process.env[key] === undefined) process.env[key] = origin;
+    }
+    for (const [key, value] of Object.entries(manifest.env ?? {})) {
+      if (process.env[key] === undefined) process.env[key] = value;
+    }
+    // a World's byte-stream doors (a hosted World's smtp, planetscale's mysql): loopback listeners in
+    // this process, bridged over WebSocket (./stream-bridge.cjs). The env names the listener now, so the
+    // ports are chosen by a blocking child; the listeners bind on the next turn, before any client
+    // can connect, and never hold the process open.
+    const streams = Object.values(manifest.streams ?? {});
+    if (streams.length) {
+      const picked = spawnSync(
+        process.execPath,
+        ['-e', 'const n=require("node:net");const k=+process.argv[1];const s=[];const d=()=>{if(s.length<k){const v=n.createServer().listen(0,"127.0.0.1",()=>{s.push(v);d()})}else{process.stdout.write(s.map(v=>v.address().port).join(","));s.forEach(v=>v.close())}};d()', String(streams.length)],
+        { encoding: 'utf8', env: { ...process.env, NODE_OPTIONS: '', VOLTER_WORLD: '' } },
+      );
+      if (picked.status !== 0) throw new Error(`[twin-attach] could not choose loopback ports for the world's streams: ${(picked.stderr || '').trim()}`);
+      const ports = picked.stdout.split(',').map(Number);
+      const { bridgeStream, streamEnv } = require('./stream-bridge.cjs');
+      const streamToken = token ?? manifest.env?.VOLTER_TWINS_KEY ?? '';
+      streams.forEach((stream, i) => {
+        for (const [key, value] of Object.entries(streamEnv(stream.env, ports[i]))) {
+          if (process.env[key] === undefined) process.env[key] = value;
+        }
+        bridgeStream(stream.url, streamToken, ports[i]).then((server) => server.unref(), (error) => {
+          process.stderr.write(`[twin-attach] ${stream.url}: could not listen on 127.0.0.1:${ports[i]}: ${error.message}\n`);
+        });
+      });
+    }
+    if (manifest.ca) {
+      const existingCa = process.env.NODE_EXTRA_CA_CERTS
+        ? readFileSync(process.env.NODE_EXTRA_CA_CERTS, 'utf8') : '';
+      const caFile = join(mkdtempSync(join(tmpdir(), 'twin-attach-')), 'ca.pem');
+      writeFileSync(caFile, `${existingCa}\n${manifest.ca}\n`);
+      process.env.NODE_EXTRA_CA_CERTS = caFile;
+      // NODE_EXTRA_CA_CERTS is read at process START — too late for THIS
+      // process's default TLS store. The injector's https forwards accept the
+      // session CA explicitly via this env; child processes inherit it fully.
+    }
+  }
+  require('./inject.cjs');
+}