@volter/twin-world 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-world",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "World configs for twins: boot named local runtimes, allocate ports, generate world.env/instance.json, and run apps against fake-key twin worlds.",
   "keywords": [
     "twin",
@@ -19,6 +19,7 @@
   },
   "files": [
     "src",
+    "known-external-services.json",
     "client",
     "test-fixtures",
     "README.md",
@@ -41,21 +42,27 @@
   "bin": {
     "volter-world": "src/cli.ts",
     "volter-world-browser-proxy": "src/browser-proxy-cli.ts",
-    "volter-world-host": "src/host-cli.ts"
+    "volter-world-host": "src/host-cli.ts",
+    "volter-world-managed-infra": "src/managed-infra-cli.ts"
   },
   "scripts": {
     "test": "bun test src/*.test.ts",
     "typecheck": "tsc --noEmit"
   },
-  "dependencies": {
-    "@volter/twin": "0.1.0"
-  },
   "devDependencies": {
     "@types/bun": "^1.2.20",
     "@types/node": "^24.0.0",
+    "pg": "8.16.3",
     "typescript": "^5.9.0"
   },
   "engines": {
     "bun": ">=1.2.0"
+  },
+  "peerDependencies": {
+    "@volter/twin": "^0.1.2"
+  },
+  "dependencies": {
+    "@electric-sql/pglite": "0.5.8",
+    "pg-gateway": "0.3.0-beta.4"
   }
 }

package/src/app-url.ts

@@ -0,0 +1,175 @@
+// `volter-world app-url` — the recorded, queryable APP endpoint of a world instance.
+//
+// Worlds own the lifecycle of SERVICES; the app under test is usually booted OUTSIDE the world by
+// the caller (the attach pattern), so nothing in the instance knows where the app listens — every
+// consumer (a browser step, a webhook target, a teammate's curl) re-derives it by folklore. The
+// subject pilots hit exactly this: the world's URLs are one `volter-world url` away, the APP's URL
+// is tribal knowledge. This verb makes the app endpoint a first-class instance record:
+//
+//   • the BOOTER writes it once, as the LAST boot step — `--set <url>`, or `--detect <pid|port>`
+//     to read it off the already-listening process instead of typing it;
+//   • any consumer reads it back (`volter-world app-url <world> [--json]`);
+//   • an UNSET read fails LOUDLY with the registration recipe — never a guess, never a default.
+//
+// A world that boots the app itself declares an `app` service (`type: 'process'`) — that existing
+// convention needs no registration: the read falls back to the `app` service's assigned URL.
+//
+// RUNTIME MINIMALISM HOLDS: this is a record, not orchestration. The runtime never boots, probes,
+// supervises, or health-checks the app — `--detect` inspects the caller-named pid/port exactly
+// once, at the caller's request, and stores what it saw. The record lives in the instance dir, so
+// a re-`up` (which wipes the dir) or `down --purge` clears it: a recorded URL never outlives the
+// instance it described.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import net from 'node:net';
+import { instanceDir, statusWorld } from './runtime.ts';
+
+/** Who answered: an explicit `--set`, a `--detect` inspection, or the world's own `app` service. */
+export type AppUrlSource = 'set' | 'detect' | 'service';
+
+export type AppUrlRecord = {
+  world: string;
+  url: string;
+  via: AppUrlSource;
+  /** ISO timestamp of the registration (absent for the `app`-service fallback — nothing was recorded) */
+  recordedAt?: string;
+  /** how the URL was obtained, for the human reading `--json` output later */
+  detail?: string;
+};
+
+export function appUrlFile(root: string, name: string): string {
+  return join(instanceDir(root, name), 'app-url.json');
+}
+
+function assertHttpUrl(url: string): URL {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`volter-world app-url: "${url}" is not a URL (want e.g. http://127.0.0.1:3000)`);
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new Error(`volter-world app-url: "${url}" must be http(s) — an app endpoint consumers can fetch`);
+  }
+  return parsed;
+}
+
+/** Record `url` as the app endpoint of the RUNNING/booted instance `name`. The instance must
+ * exist (a record for a world that was never upped would describe nothing); the app itself is
+ * deliberately NOT probed — the booter declaring "this is where I put the app" is the truth. */
+export function setAppUrl(name: string, url: string, options: { root?: string; via?: Exclude<AppUrlSource, 'service'>; detail?: string } = {}): AppUrlRecord {
+  const root = options.root ?? process.cwd();
+  const status = statusWorld(name, root); // throws "World instance not found" — the loud path
+  assertHttpUrl(url);
+  const record: AppUrlRecord = {
+    world: status.name,
+    url,
+    via: options.via ?? 'set',
+    recordedAt: new Date().toISOString(),
+    ...(options.detail === undefined ? {} : { detail: options.detail }),
+  };
+  writeFileSync(appUrlFile(root, name), `${JSON.stringify(record, null, 2)}\n`);
+  return record;
+}
+
+/** The listening TCP ports of a live pid, via lsof (macOS + Linux). */
+function listeningTcpPorts(pid: number): number[] {
+  const result = spawnSync('lsof', ['-a', '-p', String(pid), '-iTCP', '-sTCP:LISTEN', '-P', '-n', '-Fn'], { encoding: 'utf8' });
+  if (result.error) {
+    throw new Error(`volter-world app-url: \`lsof\` is unavailable (${result.error.message}) — pass the port, or --set the URL directly`);
+  }
+  const ports = new Set<number>();
+  for (const line of (result.stdout ?? '').split('\n')) {
+    if (!line.startsWith('n')) continue;
+    const port = Number(line.slice(line.lastIndexOf(':') + 1));
+    if (Number.isInteger(port) && port > 0 && port <= 65535) ports.add(port);
+  }
+  return [...ports].sort((a, b) => a - b);
+}
+
+function pidIsLive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+/** One TCP connection attempt to 127.0.0.1:<port> — is anything listening RIGHT NOW? */
+function tcpListening(port: number, timeoutMs = 1500): Promise<boolean> {
+  return new Promise((resolvePromise) => {
+    const socket = net.connect({ port, host: '127.0.0.1' });
+    const done = (ok: boolean): void => {
+      socket.destroy();
+      resolvePromise(ok);
+    };
+    socket.once('connect', () => done(true));
+    socket.once('error', () => done(false));
+    socket.setTimeout(timeoutMs, () => done(false));
+  });
+}
+
+/**
+ *`--detect <pid|port>`: resolve the app URL off what is ALREADY listening and record it.
+ * Disambiguation (both are just numbers): a live pid with listening ports wins — its single
+ * listening port is the app; several listening ports is a loud error (name the port instead).
+ * Otherwise the number is tried as a loopback port and must actually be listening. Detection
+ * that finds nothing refuses loudly rather than recording a URL nothing serves.
+ */
+export async function detectAppUrl(name: string, target: string, options: { root?: string } = {}): Promise<AppUrlRecord> {
+  const numeric = Number(target);
+  if (!Number.isInteger(numeric) || numeric <= 0) {
+    throw new Error(`volter-world app-url: --detect wants a pid or a port, got "${target}"`);
+  }
+  if (pidIsLive(numeric)) {
+    const ports = listeningTcpPorts(numeric);
+    if (ports.length === 1) {
+      return setAppUrl(name, `http://127.0.0.1:${ports[0]}`, { ...options, via: 'detect', detail: `detected from pid ${numeric} (listening on ${ports[0]})` });
+    }
+    if (ports.length > 1) {
+      throw new Error(
+        `volter-world app-url: pid ${numeric} is listening on ${ports.length} ports (${ports.join(', ')}) — `
+        + `ambiguous. Detect the app's port directly (--detect <port>) or record it explicitly (--set <url>).`,
+      );
+    }
+    // a live pid with NO listeners: fall through — the number was probably meant as a port
+  }
+  if (numeric <= 65535 && await tcpListening(numeric)) {
+    return setAppUrl(name, `http://127.0.0.1:${numeric}`, { ...options, via: 'detect', detail: `port ${numeric} is listening on 127.0.0.1` });
+  }
+  throw new Error(
+    `volter-world app-url: nothing to detect from "${target}" — it is not a live pid with a listening TCP port, `
+    + `and nothing is listening on 127.0.0.1:${target}. Boot the app first, then register its URL (--set <url> once it listens).`,
+  );
+}
+
+/**
+ * The recorded app URL of `name`, or the `app` service's assigned URL when nothing was recorded
+ * (the world-boots-the-app convention), or null. Null is the CALLER's loud-error cue — the CLI
+ * turns it into exit 1 with the registration recipe; a library consumer decides for itself.
+ */
+export function readAppUrl(name: string, options: { root?: string } = {}): AppUrlRecord | null {
+  const root = options.root ?? process.cwd();
+  const status = statusWorld(name, root); // loud when the world does not exist at all
+  const file = appUrlFile(root, name);
+  if (existsSync(file)) {
+    return JSON.parse(readFileSync(file, 'utf8')) as AppUrlRecord;
+  }
+  const app = status.services['app'];
+  if (app?.url !== undefined) {
+    return { world: status.name, url: app.url, via: 'service', detail: 'the world\'s own "app" service (nothing was recorded)' };
+  }
+  return null;
+}
+
+/** The message the CLI prints when no app URL is known — the registration recipe, not a guess. */
+export function appUrlUnsetMessage(name: string): string {
+  return (
+    `World ${name} has no recorded app URL.\n`
+    + `If the app is booted OUTSIDE the world (the attach pattern), the booter registers it as the LAST boot step:\n`
+    + `  volter-world app-url ${name} --set http://127.0.0.1:<port>    # or: --detect <pid|port>\n`
+    + `A world that boots the app itself can declare an "app" service (type "process") — its URL answers automatically.`
+  );
+}

package/src/attach.ts

@@ -0,0 +1,113 @@
+// The attach surface of the two-part model (docs/ATTACH.md): resolving a world
+// reference and deriving the world manifest — the single document a world
+// publishes and every attachment mechanism consumes. `world.env` /
+// `instance.json` remain the local renderings; this module derives the manifest
+// FROM them (it invents nothing). Attaching itself stays thin: `--via env`
+// delegates to runWithWorldEnv, `--via direct` prints the manifest. Reflect and
+// remote refs are proposals (docs/ATTACH.md) and are refused loudly, never
+// silently degraded.
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { activeVendorMap } from './redirect-proxy.ts';
+import { statusWorld } from './runtime.ts';
+
+export const WORLD_REF_FILE = '.volter-world';
+
+export type WorldRefSource = 'explicit' | 'env' | 'file';
+
+export interface ResolvedWorldRef {
+  ref: string;
+  source: WorldRefSource;
+  /** set when source === 'file' — the .volter-world file that supplied the ref */
+  file?: string;
+}
+
+/** A world reference is remote when it is a URL; every other ref is a local world name. */
+export function isRemoteWorldRef(ref: string): boolean {
+  return /^https?:\/\//i.test(ref);
+}
+
+/** Find the nearest .volter-world file from `cwd` upward. First non-empty,
+ * non-comment line is the ref (à la .nvmrc). */
+export function findWorldRefFile(cwd: string): { file: string; ref: string } | undefined {
+  let dir = resolve(cwd);
+  for (;;) {
+    const candidate = join(dir, WORLD_REF_FILE);
+    if (existsSync(candidate)) {
+      const line = readFileSync(candidate, 'utf8')
+        .split('\n')
+        .map((entry) => entry.trim())
+        .find((entry) => entry.length > 0 && !entry.startsWith('#'));
+      if (line) return { file: candidate, ref: line };
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+/** Resolution order (docs/ATTACH.md): explicit argument → VOLTER_WORLD env var →
+ * nearest committed .volter-world file. No silent machine-default fallback:
+ * a missing ref is an explicit, actionable error. */
+export function resolveWorldRef(
+  explicit: string | undefined,
+  options: { cwd?: string; env?: Record<string, string | undefined> } = {},
+): ResolvedWorldRef {
+  if (explicit !== undefined && explicit.length > 0) return { ref: explicit, source: 'explicit' };
+  const env = options.env ?? process.env;
+  const fromEnv = env.VOLTER_WORLD;
+  if (fromEnv !== undefined && fromEnv.trim().length > 0) return { ref: fromEnv.trim(), source: 'env' };
+  const fromFile = findWorldRefFile(options.cwd ?? process.cwd());
+  if (fromFile) return { ref: fromFile.ref, source: 'file', file: fromFile.file };
+  throw new Error(
+    `no world reference: pass one (volter-world attach <world> …), set VOLTER_WORLD, or commit a ${WORLD_REF_FILE} file`,
+  );
+}
+
+/** The manifest (docs/ATTACH.md): what a world publishes to its attachers. */
+export interface WorldManifest {
+  name: string;
+  /** vendor host → twin endpoint, exactly the map the injector/proxy redirect */
+  vendors: Record<string, string>;
+  /** session CA (PEM) when the world has one, else null */
+  ca: string | null;
+  /** attachment traffic proxy when present, else null */
+  proxy: string | null;
+  /** suggested fake credentials — the world env minus runtime internals */
+  env: Record<string, string>;
+}
+
+// Internal runtime vars are plumbing, not suggested credentials. CA-trust
+// bundle vars are local renderings of `ca` (they hold machine-local paths), so
+// a manifest never carries them — an attacher re-renders trust from `ca`.
+const MANIFEST_ENV_EXCLUDED =
+  /^(volter_world_|node_options$|twin_inject$|no_proxy$|https?_proxy$|node_extra_ca_certs$|ssl_cert_file$|(aws|curl|requests)_ca_bundle$)/i;
+
+/** Derive the manifest from a world's generated env map (the local rendering).
+ * Pure — the CA is inlined only when its file is readable. */
+export function deriveWorldManifest(name: string, worldEnv: Record<string, string | undefined>): WorldManifest {
+  const vendors = activeVendorMap(worldEnv);
+  const caPath = worldEnv.VOLTER_WORLD_CA;
+  let ca: string | null = null;
+  if (caPath && existsSync(caPath)) {
+    try {
+      ca = readFileSync(caPath, 'utf8');
+    } catch {
+      ca = null;
+    }
+  }
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(worldEnv)) {
+    if (value === undefined) continue;
+    if (MANIFEST_ENV_EXCLUDED.test(key)) continue;
+    if (/_TWIN_URL$/.test(key)) continue; // rendered as `vendors`, not credentials
+    env[key] = value;
+  }
+  return { name, vendors, ca, proxy: worldEnv.VOLTER_WORLD_PROXY ?? null, env };
+}
+
+/** The manifest of a local world instance (name resolved against `root` like every other verb). */
+export function worldManifest(name: string, root = process.cwd()): WorldManifest {
+  const status = statusWorld(name, root);
+  return deriveWorldManifest(name, status.env);
+}

package/src/browser-proxy-cli.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 // @ts-nocheck
+import { keepProcessAlive } from '@volter/twin/lifecycle';
 // Browser proxy launcher for fullstack app worlds. This is APP/WORLD orchestration glue
 // (it wires specific app vendors + app URLs from env), so it lives in @volter/twin-world,
 // NOT in the vendor-agnostic kernel — control-plane must never name a vendor (A2). The kernel
@@ -40,4 +41,4 @@ const redirectOrigins = [
 
 const proxy = createTwinProxy({ target, map, redirectOrigins, port });
 process.stdout.write(`[browser-proxy] http://127.0.0.1:${proxy.port} -> ${target} (${Object.keys(map).join(', ') || 'no browser vendors'})\n`);
-await new Promise(() => {});
+await keepProcessAlive();