@volter/twin-world 0.1.0

package/src/schema.ts

@@ -0,0 +1,471 @@
+export type WorldServiceType = 'twin' | 'process' | 'external';
+export type WorldMode = 'local' | 'share' | 'sealed';
+
+/**
+ * Process model for the world's twins — a DIAL, not a binary (see src/host.ts):
+ *  - 'process'   (default): one OS process per service — the existing spawn path. Strongest
+ *                 isolation; the oracle, and the only choice for share/sealed/hosted worlds
+ *                 (enforced by `upWorld` — see runtime.ts, not just documented here; TWIN-67).
+ *  - 'colocated': every service declaring `colocate` runs in ONE `volter-world-host` child
+ *                 sharing a single event loop + heap (host 'shared' mode). Lightest.
+ *  - 'worker'   : same single host child, but one Worker thread per twin — own event loop +
+ *                 heap, independently isolated (a crashed twin stays dead — never respawned),
+ *                 still one OS process to the orchestrator.
+ * Services without `colocate` (and all 'external' services) always use the spawn path.
+ */
+export type WorldIsolation = 'process' | 'colocated' | 'worker';
+export type WorldShareProvider = 'cloudflare-quick' | 'command';
+
+/**
+ * EXTERNAL (self-managed) service type.
+ *
+ * Most services in a world are owned by us: we spawn `command`, assign a PORT, and inject a
+ * `*_URL` (types 'twin' and 'process'). An EXTERNAL service is the opposite: its lifecycle is
+ * DELEGATED to an external tool that runs the REAL software (e.g. Supabase's `supabase start`,
+ * LocalStack, MinIO, Mailpit). We do NOT assign it a port — the external tool manages its own
+ * ports — and its connection URL + keys are DISCOVERED from the tool's own output, then injected
+ * into the world env exactly like a twin's `injectEnv`.
+ *
+ * The runtime is deliberately VENDOR-AGNOSTIC: it never branches on a tool's identity. Everything
+ * the runtime needs (how to start, how to probe readiness, how to read connection info, how to
+ * stop) is declared in the config below. Supabase is just an EXAMPLE config (see
+ * `configs/supabase-world.json`, which mixes a Supabase external service with stripe/github twins);
+ * there is zero Supabase-specific code in `runtime.ts`.
+ *
+ * Lifecycle on world `up`:
+ *   1. run `up` (start the external stack),
+ *   2. wait for `readyWhen` (Docker-backed externals take seconds to boot),
+ *   3. run `status` (or reuse `up` output) to obtain connection info,
+ *   4. apply `discover` mappings → inject env vars into the world env (and world.env/instance.json).
+ * On world teardown (`down`): run `down` for each external service.
+ *
+ * Robustness contract: if the external tool is missing on PATH, or `up`/`status` fail, or
+ * readiness times out, world `up` fails LOUDLY with the captured output — never a fake success.
+ */
+
+/** Source of the text a `discover` mapping reads from: the `status` output (default) or `up` output. */
+export type WorldExternalDiscoverSource = 'status' | 'up';
+
+/**
+ * One declarative env-var extraction. Exactly one of `jsonPath` or `pattern` must be set.
+ *  - `jsonPath`: dotted path into the JSON the source command printed (e.g. `API_URL`, `db.url`,
+ *    `services.0.endpoint`). Numeric segments index into arrays.
+ *  - `pattern`: a regex applied to the raw source text; capture group `value` (or group 1) is used.
+ * The resolved value is injected as the env var named by `as`.
+ */
+export type WorldExternalDiscover = {
+  as: string;
+  source?: WorldExternalDiscoverSource;
+  jsonPath?: string;
+  pattern?: string;
+};
+
+/**
+ * Optional readiness probe, polled after `up` until it passes or `timeoutMs` elapses. Exactly one of:
+ *  - `command`/`args`: a command that must exit 0,
+ *  - `httpUrl`: an HTTP(S) URL that must return a 2xx/3xx response,
+ *  - `stdoutMatch`: a regex that must appear in the `up` command's captured stdout/stderr log.
+ */
+export type WorldExternalReadyWhen = {
+  command?: string;
+  args?: string[];
+  httpUrl?: string;
+  stdoutMatch?: string;
+  timeoutMs?: number;
+  intervalMs?: number;
+};
+
+export type WorldExternalServiceConfig = {
+  up: string[];
+  status?: string[];
+  down: string[];
+  discover?: WorldExternalDiscover[];
+  readyWhen?: WorldExternalReadyWhen;
+};
+
+export type WorldShareServiceConfig = {
+  id: string;
+  verifyPath?: string | false;
+};
+
+export type WorldShareConfig = {
+  provider?: WorldShareProvider;
+  /** Custom tunnel command (provider 'command'). `{url}` in args is replaced with the
+   *  service's local URL. When set, provider defaults to 'command'. */
+  command?: string;
+  args?: string[];
+  services: WorldShareServiceConfig[];
+};
+
+export type WorldServiceConfig = {
+  id: string;
+  type?: WorldServiceType;
+  /** Required for 'twin'/'process' services. Omitted for 'external' (the tool's `up`/`down` hold the commands). */
+  command?: string;
+  args?: string[];
+  /** Optional working directory for this process. Relative paths resolve from the world root. */
+  cwd?: string;
+  port?: number | 'auto';
+  /**
+   * Required whenever `port` is a literal number (schema-enforced, TWIN-66): stable configs are
+   * meant to be instance-agnostic (see WORLD.md's config/instance split), so a numeric port is the
+   * declared EXCEPTION, not the norm — it must record WHY the port can't be `'auto'`-allocated
+   * (e.g. a consumer needs a pre-known issuer/callback URL baked in elsewhere). Ignored/forbidden
+   * when `port` is `'auto'` or unset.
+   */
+  portReason?: string;
+  env?: Record<string, string>;
+  /**
+   * Marks this service as world infrastructure rather than an app/vendor process.
+   *
+   * Control-plane services still receive the world's declared/injected service env, but they do not
+   * inherit app-side egress machinery (`NODE_OPTIONS` injector preload or ambient HTTP(S) proxy env).
+   * Use this for helper proxies, seeders, local asset servers, or orchestration daemons that must talk
+   * to loopback services directly while presenting a disguised world to the app/user.
+   */
+  controlPlane?: boolean;
+  injectEnv?: string;
+  /**
+   * Additional env vars exported into the generated world env after this service starts.
+   * Templates are resolved against the owned loopback service:
+   *   - `${url}` / `${httpUrl}` → http://127.0.0.1:<port>
+   *   - `${host}` → 127.0.0.1
+   *   - `${port}` → the allocated port
+   * This is the process-service equivalent of external.discover for services whose client-facing
+   * endpoint is not the default http URL, e.g. a real local LiveKit server needing ws://.
+   */
+  injectEnvTemplates?: Record<string, string>;
+  rootArg?: string | false;
+  portArg?: string | false;
+  /**
+   * Optional per-CLI redirect: env vars exported into the world env so the vendor's REAL CLI
+   * (`aws`, `gh`, `sentry-cli`, …) talks to THIS service instead of the real vendor. The literal
+   * `${url}` is substituted with the service's resolved URL — e.g. `{ "AWS_ENDPOINT_URL": "${url}" }`.
+   * Honored by `volter-world env/run/activate` (it flows into the world env like `injectEnv`). The
+   * pure-env path for CLIs that accept an http endpoint; CLIs needing https use the proxy (Phase 2).
+   * See docs/WORLD_ACTIVATE.md.
+   */
+  cliRedirect?: Record<string, string>;
+  /**
+   * Readiness probe for a 'process'/'twin' service. The default (or `'tcp'`) waits only until the
+   * port accepts TCP connections — but a process can bind its port BEFORE it is actually serving
+   * (Vite, an HTTP app warming up a DB pool). Pass a probe object to make `up` wait until the
+   * service truly serves, so `up` returning means "ready" (no post-up re-polling needed):
+   *   - `{ httpUrl }`  — poll until 2xx/3xx. `${url}`/`${host}`/`${port}` resolve to the allocated port.
+   *   - `{ command, args }` — poll until the command exits 0 (runs with the service env, incl. `PORT`).
+   *   - `{ stdoutMatch }` — poll until a regex matches the service's stdout/stderr log.
+   * 'external' services use `external.readyWhen` instead.
+   */
+  ready?: 'tcp' | WorldExternalReadyWhen;
+  /**
+   * Extra Node preloads for a 'process'/'twin' service, appended as `--require <module>` to the
+   * world's NODE_OPTIONS (which already loads `@volter/twin/inject`). Use this to add an app-local
+   * preload (e.g. an in-process sandbox) WITHOUT losing the injector. Setting `service.env.NODE_OPTIONS`
+   * directly REPLACES the world default (dropping the injector) — only do that if you truly mean to.
+   */
+  preload?: string[];
+  /** Required when `type === 'external'`: the self-managed lifecycle (up/status/down/discover/readyWhen). */
+  external?: WorldExternalServiceConfig;
+  /**
+   * Names this twin's in-process server factory so it can run CO-LOCATED inside the single
+   * `volter-world-host` child when the world's isolation is 'colocated'/'worker'. `module` is
+   * anything `import()` resolves — a package name (`@volter/twin-stripe`) or a file path
+   * (relative paths resolve from the world root); `export` names a
+   * `({port,root,readOnly}) => {port,stop}` factory (every pack ships one, e.g.
+   * `createStripeTwinServer`). Ignored under 'process' isolation (the default), where
+   * `command` is spawned as usual — declare BOTH to let one config serve every dial setting.
+   */
+  colocate?: { module: string; export: string };
+};
+
+export type WorldConfig = {
+  id: string;
+  description?: string;
+  /** Default process model for this world's twins ('process' when omitted). `upWorld`'s
+   * `isolation` option overrides it per boot. */
+  isolation?: WorldIsolation;
+  env?: Record<string, string>;
+  services: WorldServiceConfig[];
+  share?: WorldShareConfig;
+  actors?: Record<string, unknown>;
+  fixtures?: Record<string, unknown>;
+};
+
+export type WorldServiceInstance = {
+  id: string;
+  type: WorldServiceType;
+  command: string[];
+  /** Absent for 'external' services — we do not assign them a port. */
+  port?: number;
+  /** Absent for 'external' services — their URL is discovered into env vars, not assigned by us. */
+  url?: string;
+  /** 0 for 'external' services — they have no process we own (the external tool manages it). */
+  pid: number;
+  log: string;
+  env: Record<string, string>;
+  /**
+   * Set only for 'external' services. Records the `down` command so teardown can stop the
+   * self-managed stack, plus the cwd it was started from (the marker that the stack was brought up).
+   */
+  external?: {
+    down: string[];
+    cwd: string;
+    /** Env discovered during `up` (the injected vars), passed to the `down` command so teardown can
+     * reference connection info it needs (e.g. a stop command that takes the discovered URL). */
+    discoveredEnv?: Record<string, string>;
+  };
+  publicUrl?: string;
+  publicUrlEphemeral?: boolean;
+  publicReady?: boolean;
+  publicVerification?: {
+    path: string;
+    checkedAt: string;
+    hostname: string;
+    resolvedIp?: string;
+    status?: number;
+    body?: string;
+  };
+  tunnel?: {
+    provider: 'cloudflare-quick' | 'command';
+    pid: number;
+    log: string;
+    command: string[];
+    startedAt: string;
+  };
+  /**
+   * Set for a 'worker'-isolated co-located twin whose host-managed Worker thread crashed and
+   * was given up on (never respawned — still discoverable: the port answers nothing, but the
+   * dead twin is no longer silent). Not written directly by the runtime process: the co-located
+   * host CHILD records it in a sidecar file (`host-gaveup.json`, same instance dir) since it
+   * cannot safely rewrite instance.json out from under the parent; `readWorldInstance` merges
+   * the sidecar in here so every reader sees it as if it were in instance.json all along.
+   */
+  workerGaveUp?: {
+    /** ISO timestamp of the give-up. */
+    at: string;
+    /** Exits observed for this twin under the no-respawn contract (always 1 — field kept for
+     *  record compatibility with the sidecar/schema shape). */
+    exits: number;
+    detail: string;
+  };
+};
+
+export type WorldInstance = {
+  name: string;
+  config: string;
+  configPath: string;
+  root: string;
+  createdAt: string;
+  mode: WorldMode;
+  dirs: {
+    instance: string;
+    logs: string;
+    data: string;
+  };
+  services: Record<string, WorldServiceInstance>;
+  env: Record<string, string>;
+  envFile: string;
+  pidsFile: string;
+  actors?: Record<string, unknown>;
+  fixtures?: Record<string, unknown>;
+};
+
+function assertStringArray(value: unknown, what: string, path: string): asserts value is string[] {
+  if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== 'string')) {
+    throw new Error(`${what} must be a non-empty string array in ${path}`);
+  }
+}
+
+function assertValidRegex(pattern: string, what: string, path: string): void {
+  try {
+    new RegExp(pattern);
+  } catch (error) {
+    throw new Error(`${what} has an invalid regex (${error instanceof Error ? error.message : String(error)}) in ${path}`);
+  }
+}
+
+/** Shared validator for a readiness probe — used by both `external.readyWhen` and a process/twin
+ * service's `ready` object. Exactly one of command/httpUrl/stdoutMatch, correct types, and any
+ * stdoutMatch regex must compile (so a typo fails at config time, not mid-boot). */
+function assertReadyWhen(ready: unknown, what: string, path: string): void {
+  if (!ready || typeof ready !== 'object' || Array.isArray(ready)) {
+    throw new Error(`${what} must be an object in ${path}`);
+  }
+  const r = ready as WorldExternalReadyWhen;
+  const probes = [r.command !== undefined, r.httpUrl !== undefined, r.stdoutMatch !== undefined].filter(Boolean).length;
+  if (probes !== 1) {
+    throw new Error(`${what} must set exactly one of command/httpUrl/stdoutMatch in ${path}`);
+  }
+  if (r.command !== undefined && typeof r.command !== 'string') throw new Error(`${what}.command must be a string in ${path}`);
+  if (r.httpUrl !== undefined && typeof r.httpUrl !== 'string') throw new Error(`${what}.httpUrl must be a string in ${path}`);
+  if (r.stdoutMatch !== undefined) {
+    if (typeof r.stdoutMatch !== 'string') throw new Error(`${what}.stdoutMatch must be a string in ${path}`);
+    assertValidRegex(r.stdoutMatch, `${what}.stdoutMatch`, path);
+  }
+}
+
+function assertExternalServiceConfig(service: Partial<WorldServiceConfig>, path: string): void {
+  const id = service.id;
+  if (service.command !== undefined) {
+    throw new Error(`External service "${id}" must not set "command" (use external.up/down) in ${path}`);
+  }
+  if (service.port !== undefined) {
+    throw new Error(`External service "${id}" must not set "port" — the external tool manages its own ports in ${path}`);
+  }
+  if (service.portReason !== undefined) {
+    throw new Error(`External service "${id}" must not set "portReason" — it never sets a literal "port" in ${path}`);
+  }
+  const external = service.external;
+  if (!external || typeof external !== 'object' || Array.isArray(external)) {
+    throw new Error(`External service "${id}" must define an "external" object in ${path}`);
+  }
+  assertStringArray(external.up, `External service "${id}" external.up`, path);
+  assertStringArray(external.down, `External service "${id}" external.down`, path);
+  if (external.status !== undefined) assertStringArray(external.status, `External service "${id}" external.status`, path);
+  if (external.discover !== undefined) {
+    if (!Array.isArray(external.discover)) throw new Error(`External service "${id}" external.discover must be an array in ${path}`);
+    for (const mapping of external.discover) {
+      if (!mapping || typeof mapping !== 'object' || Array.isArray(mapping)) {
+        throw new Error(`External service "${id}" discover entries must be objects in ${path}`);
+      }
+      if (!mapping.as || typeof mapping.as !== 'string') {
+        throw new Error(`External service "${id}" discover entry must define string "as" in ${path}`);
+      }
+      const hasJson = typeof mapping.jsonPath === 'string';
+      const hasPattern = typeof mapping.pattern === 'string';
+      if (hasJson === hasPattern) {
+        throw new Error(`External service "${id}" discover "${mapping.as}" must set exactly one of jsonPath/pattern in ${path}`);
+      }
+      if (hasPattern) assertValidRegex(mapping.pattern as string, `External service "${id}" discover "${mapping.as}" pattern`, path);
+      if (mapping.source !== undefined && mapping.source !== 'status' && mapping.source !== 'up') {
+        throw new Error(`External service "${id}" discover "${mapping.as}" source must be "status" or "up" in ${path}`);
+      }
+      if (mapping.source === 'status' && external.status === undefined && hasJson) {
+        // jsonPath against status requires a status command to produce the JSON.
+      }
+    }
+    if (external.status === undefined && external.discover.some((m) => (m.source ?? 'status') === 'status')) {
+      throw new Error(`External service "${id}" has discover entries reading "status" but no external.status command in ${path}`);
+    }
+  }
+  if (external.readyWhen !== undefined) {
+    assertReadyWhen(external.readyWhen, `External service "${id}" external.readyWhen`, path);
+  }
+}
+
+export function assertWorldConfig(value: unknown, path: string): WorldConfig {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`World config must be an object: ${path}`);
+  }
+  const config = value as Partial<WorldConfig>;
+  if (!config.id || typeof config.id !== 'string') {
+    throw new Error(`World config must define string id: ${path}`);
+  }
+  if (!Array.isArray(config.services)) {
+    throw new Error(`World config must define services[]: ${path}`);
+  }
+  if (config.isolation !== undefined && config.isolation !== 'process' && config.isolation !== 'colocated' && config.isolation !== 'worker') {
+    throw new Error(`World config isolation must be "process", "colocated", or "worker" in ${path}`);
+  }
+  const ids = new Set<string>();
+  for (const service of config.services as Partial<WorldServiceConfig>[]) {
+    if (!service || typeof service !== 'object') throw new Error(`Invalid service in ${path}`);
+    if (!service.id || typeof service.id !== 'string') throw new Error(`Service must define string id in ${path}`);
+    if (!/^[a-z0-9][a-z0-9._-]*$/.test(service.id)) throw new Error(`Invalid service id "${service.id}" in ${path}`);
+    if (ids.has(service.id)) throw new Error(`Duplicate service id "${service.id}" in ${path}`);
+    ids.add(service.id);
+    if (service.type !== undefined && service.type !== 'twin' && service.type !== 'process' && service.type !== 'external') {
+      throw new Error(`Service "${service.id}" type must be "twin", "process", or "external" in ${path}`);
+    }
+    if (service.type === 'external') {
+      assertExternalServiceConfig(service, path);
+    } else {
+      if (!service.command || typeof service.command !== 'string') {
+        throw new Error(`Service "${service.id}" must define command in ${path}`);
+      }
+      if (service.ready !== undefined && service.ready !== 'tcp') {
+        assertReadyWhen(service.ready, `Service "${service.id}" ready`, path);
+      }
+      if (service.preload !== undefined) {
+        if (!Array.isArray(service.preload) || service.preload.some((p) => typeof p !== 'string')) {
+          throw new Error(`Service "${service.id}" preload must be a string array in ${path}`);
+        }
+      }
+      if (typeof service.port === 'number') {
+        if (!service.portReason || typeof service.portReason !== 'string') {
+          throw new Error(`Service "${service.id}" sets a literal "port" — this requires a "portReason" string recording why it can't be 'auto' in ${path}`);
+        }
+      } else if (service.portReason !== undefined) {
+        throw new Error(`Service "${service.id}" sets "portReason" without a literal numeric "port" in ${path}`);
+      }
+    }
+    if (service.colocate !== undefined) {
+      if (service.type === 'external') {
+        throw new Error(`External service "${service.id}" must not set colocate (its lifecycle is delegated) in ${path}`);
+      }
+      const colocate = service.colocate as Partial<{ module: string; export: string }>;
+      if (!colocate || typeof colocate !== 'object' || Array.isArray(colocate)
+        || !colocate.module || typeof colocate.module !== 'string'
+        || !colocate.export || typeof colocate.export !== 'string') {
+        throw new Error(`Service "${service.id}" colocate must be { module, export } (non-empty strings) in ${path}`);
+      }
+    }
+    if (service.args && !Array.isArray(service.args)) throw new Error(`Service "${service.id}" args must be an array`);
+    if (service.env && (typeof service.env !== 'object' || Array.isArray(service.env))) {
+      throw new Error(`Service "${service.id}" env must be an object`);
+    }
+    if (service.injectEnv !== undefined && typeof service.injectEnv !== 'string') {
+      throw new Error(`Service "${service.id}" injectEnv must be a string in ${path}`);
+    }
+    if (service.injectEnvTemplates !== undefined) {
+      if (typeof service.injectEnvTemplates !== 'object' || service.injectEnvTemplates === null || Array.isArray(service.injectEnvTemplates)
+        || Object.values(service.injectEnvTemplates).some((v) => typeof v !== 'string')) {
+        throw new Error(`Service "${service.id}" injectEnvTemplates must be a string→string object in ${path}`);
+      }
+    }
+    if (service.cliRedirect !== undefined) {
+      if (typeof service.cliRedirect !== 'object' || service.cliRedirect === null || Array.isArray(service.cliRedirect)
+        || Object.values(service.cliRedirect).some((v) => typeof v !== 'string')) {
+        throw new Error(`Service "${service.id}" cliRedirect must be a string→string object in ${path}`);
+      }
+    }
+  }
+  if (config.share !== undefined) {
+    if (!config.share || typeof config.share !== 'object' || Array.isArray(config.share)) {
+      throw new Error(`World config share must be an object in ${path}`);
+    }
+    const share = config.share as Partial<WorldShareConfig>;
+    if (share.provider !== undefined && share.provider !== 'cloudflare-quick' && share.provider !== 'command') {
+      throw new Error(`World config share.provider must be "cloudflare-quick" or "command" in ${path}`);
+    }
+    if (share.provider === 'command' && (typeof share.command !== 'string' || !share.command)) {
+      throw new Error(`World config share.provider "command" requires a non-empty share.command in ${path}`);
+    }
+    if (share.command !== undefined) {
+      if (typeof share.command !== 'string' || !share.command) {
+        throw new Error(`World config share.command must be a non-empty string in ${path}`);
+      }
+      if (share.provider !== undefined && share.provider !== 'command') {
+        throw new Error(`World config share.command requires share.provider to be omitted or "command" in ${path}`);
+      }
+    }
+    if (share.args !== undefined) {
+      if (share.command === undefined) {
+        throw new Error(`World config share.args is only allowed when share.command is set in ${path}`);
+      }
+      if (!Array.isArray(share.args) || share.args.some((arg) => typeof arg !== 'string')) {
+        throw new Error(`World config share.args must be a string array in ${path}`);
+      }
+    }
+    if (!Array.isArray(share.services)) throw new Error(`World config share.services must be an array in ${path}`);
+    for (const target of share.services as Partial<WorldShareServiceConfig>[]) {
+      if (!target || typeof target !== 'object' || Array.isArray(target)) throw new Error(`Invalid share service in ${path}`);
+      if (!target.id || typeof target.id !== 'string') throw new Error(`Share service must define string id in ${path}`);
+      if (!ids.has(target.id)) throw new Error(`Share service "${target.id}" does not match a configured service in ${path}`);
+      if (target.verifyPath !== undefined && target.verifyPath !== false && typeof target.verifyPath !== 'string') {
+        throw new Error(`Share service "${target.id}" verifyPath must be a string or false in ${path}`);
+      }
+    }
+  }
+  return config as WorldConfig;
+}