@xemahq/xema 0.1.5 → 0.2.1

package/README.md

@@ -28,16 +28,17 @@
 
 ## Overview
 
-The single global binary for Xema. Install it once to boot the local stack,
-author and ship biomes, and invoke capabilities from your terminal. It scaffolds,
-installs, publishes, and lints biomes; runs capabilities by name; and ships a
-`doctor` check for diagnosing your environment. It works as a standalone tool —
-no monorepo checkout required.
+The single global binary for Xema. Install it once to **launch the whole
+platform with one command**, author and ship biomes, and invoke capabilities
+from your terminal.
 
-## When to use it
-
-- Use it for day-0 onboarding and everyday authoring: boot the stack, scaffold a
-  biome, and run a capability without wiring up tooling by hand.
+`xema up` resolves the platform's distribution lock into an effective service
+roster, brings up the backing infrastructure you don't already run, and
+supervises every service to readiness — over a **container** substrate
+(customers) or a **native** substrate (contributors). It is a thin bring-up
+coordinator: it resolves topology and sequences startup, delegating process
+lifecycle (restart, health, resource limits) to the substrate beneath it
+(Docker/Podman, or your own infra). It never becomes a second orchestrator.
 
 ## Installation
 
@@ -45,14 +46,83 @@ no monorepo checkout required.
 npm i -g @xemahq/xema
 ```
 
-## Usage
+## Launch the platform
+
+```bash
+xema up                    # boot the backend (infra + services) as one supervised process
+xema up --web              # also start the host-shell frontend
+xema up --all              # everything, including the frontend
+xema up --detach           # leave container workloads running and return
+xema down                  # stop everything (xema down --purge also deletes data volumes)
+xema status                # show launcher-owned workloads + health
+xema logs <service> -f     # stream a service's logs
+```
+
+### Topology — `xema.config.yaml`
+
+The launcher reads an optional `xema.config.yaml` (or `~/.xema/config.yaml`)
+declaring **which infrastructure you own** and **what to run**. Every backing
+component is `managed` (the launcher starts it), `external` (you already run it —
+provide the URL), or `disabled`:
+
+```yaml
+edition: oss
+infra:
+  postgres:    { mode: managed }
+  redis:       { mode: managed }
+  etcd:        { mode: managed }
+  keycloak:    { mode: external, url: https://sso.corp/realms/xema, realm: xema }
+  objectStore: { mode: external, url: https://s3.corp }
+  search:      { mode: managed }
+  temporal:    { mode: managed }
+app:
+  substrate: container        # container | native
+  include: [ all ]            # all | <tier> | [service ...]
+  features: []                # curated capability bundles
+  web: { enabled: true }
+```
+
+- **`container`** (recommended): pulls content-addressed service images
+  (`imageRef:contentHash`) and runs them on a shared network, after bringing up
+  and bootstrapping managed infra — works without a monorepo checkout.
+- **`native`**: runs services as host processes against a built monorepo (the
+  contributor inner loop). Equivalent: `xema serve --profile single-instance`.
+- **`helm`**: deploys to Kubernetes via `helm upgrade --install` (the appliance /
+  cluster target). Equivalent: `xema serve --profile appliance`.
+
+`xema up` fails fast on a missing required secret, an unreachable `external`
+dependency, or a disabled-but-mandatory infra component — never a silent
+degradation.
+
+### Memory-optimized single-process mode + realtime dev
+
+For a low-RAM local box or appliance, collapse the native composition into ONE
+process (in-process registry + SQLite, no etcd):
+
+```bash
+xema up --monolith         # or: app.processModel: monolith in xema.config.yaml
+```
+
+Monolith is native-only and single-tenant — it trades fault isolation /
+horizontal scaling for RAM. Prisma-bound services that can't run in-process are
+fail-fast skip-logged (full collapse is gated on a cross-repo Prisma change;
+tracked in the plan). The default `distributed` model is unchanged.
+
+For development, see code changes live — the composition restarts when service
+output changes (pair with each service's own `tsc -w` / `turbo watch`):
+
+```bash
+xema dev --watch           # add --monolith for the low-RAM single-process loop
+```
+
+## Author biomes & run capabilities
 
 ```bash
-xema dev                  # boot the local stack
-xema biome scaffold <name> # author a new biome
-xema biome publish <path>  # ship a biome
-xema run <capability>      # invoke a capability by name
-xema doctor                # diagnose your environment
+xema dev                    # lock-driven native dev boot (contributors)
+xema biome scaffold <name>  # author a new biome
+xema biome publish <path>   # ship a biome
+xema run <capability>       # invoke a capability by name
+xema doctor                 # diagnose your environment
 ```
 
 ## License

package/dist/assets/boot-graph.json

@@ -0,0 +1,72 @@
+{
+  "$comment": "Declarative source of truth for system-authority STARTUP dependencies (Gate A, plan .claude/plans/federated-crunching-thompson.md Phase 1.5). Consumed by tooling/boundaries/check-boot-graph.mjs. Human-prose rationale + degraded behavior lives in docs/architecture/system-boot-graph.md — keep the two in lockstep. INVARIANT: no service may HARD-REQUIRE a higher- or same-boot-tier service at startup; the hard-require graph must be acyclic. 'startupRequires' lists ONLY hard boot-blocking deps (the service refuses to come up / crash-loops until each is reachable). Lazy/at-request-time deps are NOT listed here — they are captured as 'degraded' prose in the doc. Boot tiers (lower boots first): infra(-1) < kernel(0) < system(1) < base(2) < platform(3) < third-party(4). 'infra' = submodules + external generic plane (identity-api, event-hub, secrets, llm-gateway, keycloak, postgres, valkey, kernel-state/etcd) which always boot before the Xema service mesh and can never participate in a service-mesh cycle.",
+  "tiers": {
+    "infra": -1,
+    "kernel": 0,
+    "system": 1,
+    "base": 2,
+    "platform": 3,
+    "third-party": 4
+  },
+  "infraServices": [
+    "identity-api",
+    "event-hub-api",
+    "secrets-api",
+    "llm-gateway-api",
+    "kernel-state"
+  ],
+  "services": {
+    "authorization-api": {
+      "tier": "system",
+      "startupRequires": ["identity-api"]
+    },
+    "object-registry-api": {
+      "tier": "system",
+      "startupRequires": ["identity-api"]
+    },
+    "capability-registry-api": {
+      "tier": "system",
+      "startupRequires": ["identity-api"]
+    },
+    "user-hub-api": {
+      "tier": "system",
+      "startupRequires": ["identity-api"]
+    },
+    "public-gateway-api": {
+      "tier": "system",
+      "startupRequires": ["identity-api"]
+    },
+    "xema-shell-api": {
+      "tier": "system",
+      "startupRequires": ["identity-api"]
+    },
+    "xema-capability-router": {
+      "tier": "system",
+      "startupRequires": []
+    },
+    "biome-host-api": {
+      "tier": "system",
+      "startupRequires": ["identity-api"]
+    },
+    "workload-runtime-api": {
+      "tier": "system",
+      "startupRequires": ["identity-api"]
+    },
+    "xema-biome-runner": {
+      "tier": "system",
+      "startupRequires": ["identity-api"]
+    },
+    "project-registry-api": {
+      "tier": "base",
+      "startupRequires": ["identity-api"]
+    },
+    "space-registry-api": {
+      "tier": "system",
+      "startupRequires": ["identity-api"]
+    },
+    "xema-kernel-server": {
+      "tier": "kernel",
+      "startupRequires": []
+    }
+  }
+}