@volter/world-runtime 2.0.0

package/src/index.ts

@@ -0,0 +1,171 @@
+export type {
+  WorldConfig,
+  WorldInstance,
+  WorldIsolation,
+  WorldMode,
+  WorldServiceConfig,
+  WorldServiceType,
+  WorldExternalServiceConfig,
+  WorldExternalDiscover,
+  WorldExternalDiscoverSource,
+  WorldExternalReadyWhen,
+  WorldRunOutcome,
+  WorldRunRecord,
+  WorldResourceRequirements,
+  WorldManifestV2,
+  WorldSelection,
+  WorldSelectionSelector,
+  WorldUsage,
+} from './schema.ts';
+export { DEFAULT_WORLD_SELECTION, LEGACY_WORLD_SELECTION, WORLD_SCHEMA_VERSION, WORLD_USAGES, worldConfigDocument, worldSelectionIncludes } from './schema.ts';
+export { loadWorldConfig, migrateWorldConfig, resolveConfigPath, writeWorldConfig } from './configs.ts';
+export type { WorldConfigMigration } from './configs.ts';
+export {
+  upWorld,
+  downWorld,
+  pruneWorlds,
+  listWorlds,
+  statusWorld,
+  doctorWorld,
+  runWithWorldEnv,
+  attachWorld,
+  retireWorldConsumers,
+  activateScript,
+  shellWorld,
+  worldShellEnv,
+  ensureWorldProxy,
+  runProxyDaemon,
+  runWorld,
+  shareWorld,
+  shareWorldServices,
+  unshareWorld,
+  urlsWorld,
+  urlWorld,
+} from './runtime.ts';
+export type { WorldCleanupEntry } from './runtime.ts';
+export { worldResourceReport } from './resources.ts';
+// `volter-world app-url` — the recorded, queryable app endpoint of an instance (see app-url.ts).
+export { appUrlFile, appUrlUnsetMessage, detectAppUrl, readAppUrl, setAppUrl } from './app-url.ts';
+export type { AppUrlRecord, AppUrlSource } from './app-url.ts';
+export { tailWorldActions } from './tail.ts';
+export type { TailWorldOptions } from './tail.ts';
+// the changeset primitive + the diff verb (docs/concepts/the-model.md v0) and the operational-PR
+// contract over it (v1: verify/approve/status). World-side glue only — markers, deltas, content
+// hashing, replay, verifier evaluation and approval binding live in @volter/world-core's control plane.
+export {
+  pushWorldChangeset,
+  rebaseWorldChangeset,
+  approveWorldChangeset,
+  createWorldChangeset,
+  diffWorld,
+  EPHEMERAL_VERIFY_TARGET,
+  findWorldChangeset,
+  listWorldChangesets,
+  listWorldMarks,
+  markWorld,
+  MARK_NOTE_MAX,
+  replayWorldChangeset,
+  resolveBaseMarker,
+  statusWorldChangeset,
+  verifyWorldChangeset,
+  worldChangesetsDir,
+  worldLedgers,
+  worldMarksDir,
+} from './changeset.ts';
+export type { NotedMarker, PushWorldOptions, PushWorldOutcome, RebaseWorldOutcome, ApproveWorldOutcome, ChangesetLocation, VerifyWorldOutcome, WorldRootOptions } from './changeset.ts';
+export {
+  checkLocalExecution,
+  checkPrerequisites,
+  formatPrerequisiteChecks,
+} from './prerequisites.ts';
+export { inspectProject, formatProjectInspection, projectDependencies, projectEnvNames, SDK_TWINS, workspaceDirs } from './project-inspect.ts';
+export type { ProjectInspection } from './project-inspect.ts';
+// Structurally valid fake credentials for world configs (fixture env) — see fixture-env.ts
+// for the pattern (a fake a client SDK parses/signs with must be structurally real).
+export { fakeEnvValue, fakeGoogleOAuthClientJson, fakeGoogleServiceAccountJson, isGoogleOAuthClientEnvName, isGoogleServiceAccountEnvName } from './fixture-env.ts';
+export type { FakeServiceAccountOptions } from './fixture-env.ts';
+export {
+  coverWorld,
+  detectRepoVendors,
+  envNameVendor,
+  formatCoverageReport,
+  injectorVendorKeysFor,
+  isCredentialShapedEnvName,
+  worldTwinInventory,
+} from './covers.ts';
+export type { CoverageReport, CoverageRow, CoverageStatus, CoverageOptions, RepoVendorSignals } from './covers.ts';
+// `volter-world init` — the deterministic front door: detect the repo's vendors (covers), emit a
+// world config + env file OUTSIDE the repo (fixture-env), and prove the emission with `covers`.
+export { formatInitReport, initWorld, packCatalog, planWorldInit, renderEnvFile, writeWorldInit } from './init.ts';
+export { STATE_GITIGNORE } from './init.ts';
+export { clockFile } from './runtime.ts';
+export { checkoutCatalog, findInstalledPackage, installedCatalog, resolveCatalog, resolveServicePackage, twinPackageName, TWIN_PACKAGE_PREFIX, type Catalog, type CatalogKind, packCli, packEntry } from './catalog.ts';
+export { MINT_ENV } from './schema.ts';
+export type {
+  EnvDisposition,
+  InitEnvRow,
+  InitInfraStub,
+  InitOptions,
+  InitPlan,
+  InitResult,
+  InitVendorPlan,
+  InitWiring,
+} from './init.ts';
+export {
+  deriveWorldManifest,
+  findWorldRefFile,
+  isRemoteWorldRef,
+  resolveWorldRef,
+  WORLD_REF_FILE,
+  worldManifest,
+} from './attach.ts';
+export type { ResolvedWorldRef, WorldManifest, WorldRefSource } from './attach.ts';
+export {
+  parseSni,
+  readReflectRoutes,
+  reflectRoutesPath,
+  reflectManifestPath,
+  readReflectManifest,
+  writeReflectManifest,
+  clearReflectManifest,
+  composeOverrideForReflect,
+  splitDockerComposeArgs,
+  dockerComposeWithOverride,
+  CA_TRUST_ENV,
+  ATTACHED_CA_PATH,
+  startReflectFront,
+  startReflectResolver,
+  writeReflectRoutes,
+} from './reflect.ts';
+export type { ReflectFrontHandle, ReflectFrontOptions, ReflectManifest, ReflectResolverHandle, ReflectResolverOptions } from './reflect.ts';
+export type {
+  PrerequisiteCheck,
+  PrerequisiteId,
+} from './prerequisites.ts';
+export { startColocatedHost } from './host.ts';
+export type { ColocatedTwinSpec, ColocatedHost, HostIsolation } from './host.ts';
+export {
+  advertiseWorldManifest,
+  fetchRemoteManifest,
+  MANIFEST_PATH,
+  remoteAttachEnv,
+  startManifestServer,
+} from './serve.ts';
+export type { ManifestServerHandle, ManifestServerOptions } from './serve.ts';
+
+export { resetWorld, seedEntryFor, seedWorld } from './placeholder.ts';
+export type { SeedWorldOptions, SeedWorldOutcome } from './placeholder.ts';
+
+export { fetchFromOrigin, worldOrigin } from './origin.ts';
+export type { FetchOptions, FetchOutcome } from './origin.ts';
+
+export { branchWorld, checkoutWorld } from './branch.ts';
+export type { BranchOptions } from './branch.ts';
+export { deployWorld, refreshTwin, adaptersFor, credentialPath, credentialPayloadFrom, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from './root.ts';
+export type { DeployTwinOutcome, MaterializedRoot } from './root.ts';
+export { landReceipts, mountWorld, readServeRecord, refreshSchedule, servedName, serveWorld, TOKEN_HEADER, WorldDoors } from './served-world.ts';
+export type { DoorHost, MountedWorld, ServeRecord, WorldLayout } from './served-world.ts';
+export type { ServedWorld } from './served-world.ts';
+export { CONSOLE_BASE, consoleRedirect, serveConsoleApart, serveConsoleFor, type ConsoleMount } from './console-apart.ts';
+
+export { assertWorldStateRemovable } from './ancestry.ts';

package/src/infra-cli.ts

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// Private implementation for infrastructure emitted by `volter-world init`. World configs invoke
+// this declared service; application agents never operate or diagnose its backing mechanism.
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { infraConnections, parseInfraDefinition } from './pglite-backing.ts';
+
+const phase = process.argv[2];
+if (phase !== 'up' && phase !== 'status' && phase !== 'down') {
+  process.stderr.write('managed infrastructure: expected up, status, or down\n');
+  process.exit(2);
+}
+
+const worldConfig = process.env.VOLTER_WORLD_CONFIG;
+const worldData = process.env.VOLTER_WORLD_DATA;
+if (!worldConfig || !worldData) {
+  process.stderr.write('managed infrastructure: missing World lifecycle context\n');
+  process.exit(2);
+}
+const definition = join(dirname(worldConfig), 'world.infrastructure.yml');
+if (!existsSync(definition)) {
+  process.stderr.write('managed infrastructure: declared definition is missing\n');
+  process.exit(2);
+}
+
+const base = ['compose', '-f', definition];
+const run = (args: string[]) => spawnSync('docker', [...base, ...args], {
+  encoding: 'utf8',
+  env: { ...process.env, VOLTER_WORLD_DATA: worldData },
+  timeout: 120_000,
+});
+const classify = (raw: string): string => /no space left on device|enospc/iu.test(raw)
+  ? 'insufficient writable storage'
+  : /out of memory|cannot allocate memory|killed/iu.test(raw)
+    ? 'insufficient memory'
+    : /cannot connect|not running|daemon/iu.test(raw)
+      ? 'local execution capacity is unavailable'
+      : 'managed infrastructure operation failed';
+const fail = (result: ReturnType<typeof run>): never => {
+  const raw = `${result.stdout ?? ''}\n${result.stderr ?? ''}`.trim();
+  process.stderr.write(`managed infrastructure ${phase} failed: ${classify(raw)}\n`);
+  process.exit(result.status && result.status > 0 ? result.status : 1);
+};
+
+// ---- backing selection ------------------------------------------------------
+// The declared service contract (up/status/down) is the boundary; WHICH
+// runtime answers it is private and chosen here, per machine, at each phase:
+//   1. VOLTER_WORLD_INFRA_BACKING=docker|pglite — explicit, for tests/operators;
+//   2. a working container runtime — the compose path, byte-identical to before;
+//   3. no container runtime + a postgres-only definition — the PGlite backing
+//      (pglite-host.ts), announced loudly;
+//   4. otherwise the honest refusal naming what this machine cannot serve.
+function selectBacking(): 'docker' | 'pglite' {
+  const forced = process.env.VOLTER_WORLD_INFRA_BACKING;
+  if (forced === 'docker' || forced === 'pglite') return forced;
+  if (forced !== undefined) {
+    process.stderr.write(`managed infrastructure: VOLTER_WORLD_INFRA_BACKING must be docker or pglite (got ${JSON.stringify(forced)})\n`);
+    process.exit(2);
+  }
+  const probe = spawnSync('docker', ['info', '--format', '{{.ServerVersion}}'], { encoding: 'utf8', timeout: 10_000 });
+  if (probe.status === 0) return 'docker';
+  // Absence of a container runtime (no binary, no daemon) is a capability
+  // difference: swap backings. A PRESENT runtime failing on resources stays
+  // on the docker path so the real capacity problem is classified and
+  // surfaced — a full disk starves every backing equally.
+  if (probe.error !== undefined) return 'pglite';
+  const reason = classify(`${probe.stdout ?? ''}\n${probe.stderr ?? ''}`);
+  return reason === 'local execution capacity is unavailable' ? 'pglite' : 'docker';
+}
+
+async function runPglite(): Promise<never> {
+  const { unsupportedKinds, pgliteUp, pgliteStatus, pgliteDown } = await import('./pglite-backing.ts');
+  const services = parseInfraDefinition(readFileSync(definition, 'utf8'));
+  if (services.length === 0) {
+    process.stderr.write('managed infrastructure: the declared definition names no services\n');
+    process.exit(1);
+  }
+  const unsupported = unsupportedKinds(services);
+  if (unsupported.length > 0) {
+    process.stderr.write(`managed infrastructure ${phase} failed: local execution capacity is unavailable (no container runtime, and the containerless backing cannot serve: ${unsupported.join(', ')})\n`);
+    process.exit(1);
+  }
+  if (phase === 'up') {
+    process.stdout.write('managed infrastructure backing: pglite (no container runtime)\n');
+    try {
+      await pgliteUp(services, worldData!);
+    } catch (error) {
+      process.stderr.write(`managed infrastructure up failed: ${String((error as Error).message ?? error)}\n`);
+      process.exit(1);
+    }
+    process.stdout.write('managed infrastructure ready\n');
+    process.exit(0);
+  }
+  if (phase === 'status') {
+    const status = await pgliteStatus(services, worldData!);
+    if (!status.ok) {
+      process.stderr.write(`managed infrastructure status failed: ${status.ready}/${services.length} declared services are ready\n`);
+      process.exit(1);
+    }
+    process.stdout.write(`${JSON.stringify({ ok: true, services: services.length, connections: infraConnections(services, process.env) })}\n`);
+    process.exit(0);
+  }
+  await pgliteDown(services, worldData!);
+  process.stdout.write('managed infrastructure stopped\n');
+  process.exit(0);
+}
+
+if (selectBacking() === 'pglite') {
+  await runPglite();
+}
+
+if (phase === 'up') {
+  const result = run(['up', '-d', '--wait']);
+  if (result.status !== 0) fail(result);
+  process.stdout.write('managed infrastructure ready\n');
+} else if (phase === 'status') {
+  const expected = run(['config', '--services']);
+  if (expected.status !== 0) fail(expected);
+  const running = run(['ps', '--status', 'running', '--services']);
+  if (running.status !== 0) fail(running);
+  const expectedNames = expected.stdout.split(/\s+/u).filter(Boolean).sort();
+  const runningNames = running.stdout.split(/\s+/u).filter(Boolean).sort();
+  if (expectedNames.length === 0 || expectedNames.join('\0') !== runningNames.join('\0')) {
+    process.stderr.write(`managed infrastructure status failed: ${runningNames.length}/${expectedNames.length} declared services are ready\n`);
+    process.exit(1);
+  }
+  process.stdout.write(`${JSON.stringify({ ok: true, services: expectedNames.length, connections: infraConnections(parseInfraDefinition(readFileSync(definition, 'utf8')), process.env) })}\n`);
+} else {
+  const result = run(['down', '--remove-orphans']);
+  if (result.status !== 0) fail(result);
+  process.stdout.write('managed infrastructure stopped\n');
+}