@volter/twin-world 0.1.0

package/src/host.ts

@@ -0,0 +1,142 @@
+// Co-located twin host — run many twins in ONE process instead of one OS process
+// per twin. The twin core is a pure, transport-agnostic handler (see a pack's
+// `handle<Vendor>TwinRequest`), so nothing requires a process per twin; this host
+// mounts N of them behind their own ports/URLs (the world env + instance.json are
+// byte-identical to the spawned path — only the process model changes).
+//
+// Isolation is a DIAL, not a binary (the runtime stays minimal — this is still just
+// "bring services up / tear them down", one child process):
+//   - 'shared' : all twins share one event loop + heap. Lightest. A thrown request
+//                handler is isolated (Bun.serve returns 500; siblings serve on), but a
+//                CPU hog / OOM / process.exit in one twin hits all. Default for CI/dev.
+//   - 'worker' : one Worker thread per twin → own event loop + own heap, independently
+//                isolated. A sibling can spin, leak, or hard-exit without taking the
+//                host down — but a crashed twin stays down (doctor red), it is never
+//                respawned. Still ONE OS process to the orchestrator.
+// ('process' isolation — one OS process per twin — is the world runtime's existing
+//  spawn path; it remains the oracle and the choice for share/sealed/hosted worlds.)
+//
+// ARCHITECTURE: the runtime never imports vendor packs. A twin is named by a module
+// SPECIFIER + export resolved with dynamic import() at boot, so this host (and the
+// world config that drives it) stays vendor-agnostic — exactly like `bin` spawning.
+import { Worker } from 'node:worker_threads';
+
+/** One twin to mount in the host. `module`/`export` name a `({port,root,readOnly}) => {port,stop}`
+ *  factory (every pack ships one, e.g. `createStripeTwinServer`). `module` is anything import()
+ *  resolves: a package name (`@volter/twin-stripe`) or an absolute file path (tests/fixtures). */
+export type ColocatedTwinSpec = {
+  id: string;
+  module: string;
+  export: string;
+  port: number;
+  root: string;
+  readOnly?: boolean;
+};
+
+export type HostIsolation = 'shared' | 'worker';
+
+export type ColocatedHost = {
+  isolation: HostIsolation;
+  /** Resolved listening port per twin id (equals the requested port). */
+  ports: Record<string, number>;
+  stop: () => Promise<void>;
+};
+
+type TwinServer = { port: number; stop: () => void };
+type TwinServerFactory = (opts: { port?: number; root?: string; readOnly?: boolean }) => TwinServer;
+
+async function loadFactory(spec: ColocatedTwinSpec): Promise<TwinServerFactory> {
+  const mod = (await import(spec.module)) as Record<string, unknown>;
+  const factory = mod[spec.export];
+  if (typeof factory !== 'function') {
+    throw new Error(`Twin "${spec.id}": ${spec.module} has no factory export "${spec.export}"`);
+  }
+  return factory as TwinServerFactory;
+}
+
+const workerEntry = new URL('./host-worker.ts', import.meta.url);
+
+/**
+ * Start a co-located host. Resolves once every twin is listening. The returned `stop()`
+ * tears the whole host down (all servers / all workers).
+ *
+ * `onEvent` is an optional observability hook (logged by the CLI) — it surfaces a twin
+ * worker crashing (and being given up on), and stray rejections swallowed in shared mode,
+ * so a degraded twin is never a silent fake-success.
+ */
+export async function startColocatedHost(
+  specs: ColocatedTwinSpec[],
+  options: { isolation?: HostIsolation; onEvent?: (e: { twin: string; kind: string; detail?: string; exits?: number }) => void } = {},
+): Promise<ColocatedHost> {
+  const isolation = options.isolation ?? 'shared';
+  const onEvent = options.onEvent ?? (() => {});
+  const ports: Record<string, number> = {};
+  for (const spec of specs) ports[spec.id] = spec.port;
+
+  if (isolation === 'shared') {
+    // Keep one twin's stray async rejection / uncaught throw from killing every other twin in
+    // the shared process. (A thrown *request* handler is already contained by Bun.serve → 500.)
+    // We log and attribute rather than exit — state stays consistent because every kernel write
+    // is atomic (temp→rename) and root-keyed, so a swallowed error can't corrupt a sibling.
+    const onRejection = (reason: unknown) => onEvent({ twin: '(host)', kind: 'unhandledRejection', detail: String(reason) });
+    const onUncaught = (err: unknown) => onEvent({ twin: '(host)', kind: 'uncaughtException', detail: String(err) });
+    process.on('unhandledRejection', onRejection);
+    process.on('uncaughtException', onUncaught);
+
+    const servers: TwinServer[] = [];
+    for (const spec of specs) {
+      const factory = await loadFactory(spec);
+      servers.push(factory({ port: spec.port, root: spec.root, readOnly: spec.readOnly }));
+    }
+    return {
+      isolation,
+      ports,
+      stop: async () => {
+        process.off('unhandledRejection', onRejection);
+        process.off('uncaughtException', onUncaught);
+        for (const s of servers) s.stop();
+      },
+    };
+  }
+
+  // worker isolation — one Worker thread per twin, given up on crash — never respawned.
+  const stopping = { value: false };
+  const workers = new Map<string, Worker>();
+
+  const spawnWorker = (spec: ColocatedTwinSpec): Promise<void> =>
+    new Promise<void>((resolveReady, rejectReady) => {
+      const worker = new Worker(workerEntry, { workerData: spec });
+      // Pure observability, symmetric with `gaveup` below — NOT a supervision hook. Fired exactly
+      // once per spawnWorker() call (there's no counter/timer/keep-alive here), so it doubles as a
+      // direct tamper guard: a stealth respawn re-adding `spawnWorker(spec)` in the exit handler
+      // below would emit a 2nd `spawn` for the same twin, which the isolation test asserts against.
+      onEvent({ twin: spec.id, kind: 'spawn', detail: 'worker started' });
+      let ready = false;
+      worker.on('message', (msg: { type?: string }) => {
+        if (msg?.type === 'ready') { ready = true; resolveReady(); }
+      });
+      worker.on('error', (err) => {
+        onEvent({ twin: spec.id, kind: 'error', detail: String(err) });
+        if (!ready) rejectReady(err);
+      });
+      worker.on('exit', (code) => {
+        workers.delete(spec.id);
+        if (stopping.value || code === 0) return;
+        // Minimal-primitive doctrine: no keep-alive supervisor. A crashed worker is NOT
+        // respawned — record the give-up (host-cli persists it → doctor red) and stay dead.
+        onEvent({ twin: spec.id, kind: 'gaveup', detail: `exit code ${code} — not restarted`, exits: 1 });
+      });
+      workers.set(spec.id, worker);
+    });
+
+  for (const spec of specs) await spawnWorker(spec);
+
+  return {
+    isolation,
+    ports,
+    stop: async () => {
+      stopping.value = true;
+      await Promise.all([...workers.values()].map((w) => w.terminate()));
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+export type {
+  WorldConfig,
+  WorldInstance,
+  WorldIsolation,
+  WorldMode,
+  WorldServiceConfig,
+  WorldServiceType,
+  WorldExternalServiceConfig,
+  WorldExternalDiscover,
+  WorldExternalDiscoverSource,
+  WorldExternalReadyWhen,
+} from './schema.ts';
+export { loadWorldConfig, resolveConfigPath } from './configs.ts';
+export {
+  upWorld,
+  downWorld,
+  listWorlds,
+  statusWorld,
+  doctorWorld,
+  runWithWorldEnv,
+  activateScript,
+  shellWorld,
+  worldShellEnv,
+  ensureWorldProxy,
+  runProxyDaemon,
+  runWorld,
+  shareWorld,
+  shareWorldServices,
+  unshareWorld,
+  urlsWorld,
+} from './runtime.ts';
+export {
+  checkDockerRuntime,
+  checkPrerequisites,
+  formatPrerequisiteChecks,
+} from './prerequisites.ts';
+export type {
+  PrerequisiteCheck,
+  PrerequisiteId,
+} from './prerequisites.ts';
+export { startColocatedHost } from './host.ts';
+export type { ColocatedTwinSpec, ColocatedHost, HostIsolation } from './host.ts';

package/src/prerequisites.ts

@@ -0,0 +1,109 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+export type PrerequisiteId = 'docker';
+
+export type PrerequisiteCheck = {
+  id: PrerequisiteId;
+  ok: boolean;
+  label: string;
+  message: string;
+  guidance: string[];
+  details?: Record<string, string>;
+};
+
+type RunResult = { status: number | null; stdout: string; stderr: string };
+type Runner = (cmd: string, args: string[]) => RunResult;
+
+const realRunner: Runner = (cmd, args) => {
+  const result = spawnSync(cmd, args, { encoding: 'utf8' });
+  return {
+    status: result.status,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+  };
+};
+
+function trim(value: string): string {
+  return value.trim();
+}
+
+function dockerContextHost(runner: Runner): { context?: string; host?: string } {
+  const contextResult = runner('docker', ['context', 'show']);
+  const context = contextResult.status === 0 ? trim(contextResult.stdout) : undefined;
+  if (!context) return {};
+
+  const inspect = runner('docker', ['context', 'inspect', context]);
+  if (inspect.status !== 0 || !inspect.stdout.trim()) return { context };
+  try {
+    const parsed = JSON.parse(inspect.stdout) as Array<{ Endpoints?: { docker?: { Host?: string } } }>;
+    return { context, host: parsed[0]?.Endpoints?.docker?.Host };
+  } catch {
+    return { context };
+  }
+}
+
+function commonDockerGuidance(details: Record<string, string>): string[] {
+  const guidance = [
+    'Start the computer-native Docker-compatible runtime before running this world.',
+    'If you are an AI agent running this command, it is your job to start that local runtime now; do not hand this back to the user unless the runtime cannot be started from the machine.',
+    'Agents should boot the runtime installed on this machine: `colima start` for Colima, open/start Docker Desktop for Docker Desktop, or start the native Docker service on Linux.',
+  ];
+
+  if (details.context || details.host) {
+    guidance.push(`Active Docker context${details.context ? ` '${details.context}'` : ''}${details.host ? ` points at ${details.host}` : ''}.`);
+  }
+
+  const colimaSocket = join(homedir(), '.colima', 'default', 'docker.sock');
+  if (existsSync(colimaSocket)) {
+    guidance.push(`A Colima socket exists at ${colimaSocket}; if the Docker context points elsewhere, update the context or export DOCKER_HOST=unix://${colimaSocket}.`);
+  }
+
+  return guidance;
+}
+
+export function checkDockerRuntime(runner: Runner = realRunner): PrerequisiteCheck {
+  const info = runner('docker', ['info']);
+  if (info.status === 0) {
+    return {
+      id: 'docker',
+      ok: true,
+      label: 'Docker-compatible daemon',
+      message: 'Docker-compatible daemon is reachable.',
+      guidance: [],
+    };
+  }
+
+  const context = dockerContextHost(runner);
+  const details: Record<string, string> = {};
+  if (context.context) details.context = context.context;
+  if (context.host) details.host = context.host;
+  if (info.stderr.trim()) details.error = info.stderr.trim();
+
+  return {
+    id: 'docker',
+    ok: false,
+    label: 'Docker-compatible daemon',
+    message: 'Docker-compatible daemon is not reachable.',
+    guidance: commonDockerGuidance(details),
+    details,
+  };
+}
+
+export function checkPrerequisites(ids: PrerequisiteId[], runner: Runner = realRunner): PrerequisiteCheck[] {
+  return ids.map((id) => {
+    if (id === 'docker') return checkDockerRuntime(runner);
+    throw new Error(`Unknown prerequisite: ${id}`);
+  });
+}
+
+export function formatPrerequisiteChecks(checks: PrerequisiteCheck[]): string {
+  return checks.flatMap((check) => {
+    const status = check.ok ? 'ok' : 'missing';
+    const lines = [`${status} ${check.label}: ${check.message}`];
+    if (!check.ok) lines.push(...check.guidance.map((line) => `  ${line}`));
+    return lines;
+  }).join('\n');
+}

package/src/proxy-daemon.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env bun
+// Detached entry for the ambient TLS redirect proxy. `activate` spawns this as its own process so a
+// long-lived proxy can serve the activated shell(s) for the world's lifetime; it records its
+// pid/url/CA in the instance dir and is stopped by `volter-world down`. Not a user-facing command.
+import { runProxyDaemon } from './runtime.ts';
+
+const [name, ...rest] = process.argv.slice(2);
+const rootIndex = rest.indexOf('--root');
+const root = rootIndex >= 0 && rest[rootIndex + 1] ? rest[rootIndex + 1]! : process.cwd();
+const envFileIndex = rest.indexOf('--env-file');
+const envFile = envFileIndex >= 0 && rest[envFileIndex + 1] ? rest[envFileIndex + 1]! : undefined;
+
+if (!name) {
+  process.stderr.write('proxy-daemon: missing world name\n');
+  process.exit(1);
+}
+
+runProxyDaemon(name, root, envFile).catch((error) => {
+  process.stderr.write(`proxy-daemon: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+});