Installation

Gooi is designed for progressive adoption. Install only what your adoption level requires. Each level is a strict superset of the one below it. You never need to uninstall or replace packages when moving up.

L0: Contract-first

Import spec schema types with zero runtime dependency. Use this when you want typed boundaries without running a Gooi runtime.

bun add @gooi/app
# or
npm install @gooi/app

import type { GooiAppSpec } from "@gooi/app/spec";

// Use GooiAppSpec as a shared type contract between services or teams
const spec: GooiAppSpec = { /* ... */ };

What you get:

• Stable TypeScript types for the full spec schema
• Zod-powered validation with descriptive error messages
• No runtime overhead

L1: Compile-first

Add compilation. Use this when you want deterministic, hashed artifacts you can inspect, ship, and gate CI on. L0 packages are already included.

bun add @gooi/app
# or
npm install @gooi/app

@gooi/app includes both define and compile exports.

import { defineApp } from "@gooi/app/define";
import { compileApp } from "@gooi/app/compile";

const spec = defineApp({ yaml: rawYaml });
const bundle = compileApp({ spec });
// bundle: CompiledEntrypointBundle (deterministic, versioned, hashed)

What you get:

• defineApp(): validates and parses a spec document
• compileApp(): emits a CompiledEntrypointBundle with a stable SHA-256 hash
• CapabilityBindingRequirements: describes what providers your spec needs at deploy time

L2: Embedded runtime

Add the execution kernel. Use this when you want canonical runtime semantics inside an existing server. L0 and L1 packages are already included.

bun add @gooi/app @gooi/app-runtime
# or
npm install @gooi/app @gooi/app-runtime

import { compileApp } from "@gooi/app/compile";
import { createAppRuntime } from "@gooi/app-runtime/create";

const bundle = compileApp({ spec });
const runtime = createAppRuntime({ bundle, hostPorts });

// Call from your existing request handlers
const result = await runtime.invoke({
  entrypointKind: "query",
  entrypointId: "list_messages",
  input: { page: 1 },
  authContext,
});

What you get:

• createAppRuntime(): activates the kernel and semantic engines against a compiled bundle
• runtime.invoke(): executes any query, mutation, or route with full access enforcement, replay gating, and canonical envelope assembly
• Full kernel semantics without restructuring your existing server

L3: Full platform

Use the complete arc end-to-end. L0, L1, and L2 packages are already included.

bun add @gooi/app @gooi/app-runtime
# or
npm install @gooi/app @gooi/app-runtime

import { defineApp } from "@gooi/app/define";
import { compileApp } from "@gooi/app/compile";
import { createAppRuntime } from "@gooi/app-runtime/create";

const spec = defineApp({ yaml: rawYaml });
const bundle = compileApp({ spec });
const runtime = createAppRuntime({ bundle, hostPorts });
const result = await runtime.invoke(input);

What you get:

• The full execution model: spec → compile → runtime → invoke
• All surface adapters, semantic engines, and capability binding in one coherent model
• The scenario suite from your spec is your test suite

Testing

bun add -d @gooi/app-testing
# or
npm install --save-dev @gooi/app-testing

import { runScenarios } from "@gooi/app-testing/run";

const results = await runScenarios({ spec, bundle });

@gooi/app-testing uses the same execution pipeline as the production runtime with memory-backed providers. No mocks. No test doubles.

Package exports reference

All packages use explicit subpath exports. Import from the subpath, not from the package root.

Import	What it provides
@gooi/app/spec	GooiAppSpec type, parseGooiAppSpec
@gooi/app/define	defineApp
@gooi/app/compile	compileApp
@gooi/app-runtime/create	createAppRuntime
@gooi/app-testing/run	runScenarios
@gooi/app-marketplace	resolveTrustedProviders

Requirements

• Node.js 20+ or Bun 1.1+
• TypeScript 5.0+ (recommended)