@xemahq/create-biome

Scaffolder for new Xema biome packages

Overview

Generates a real in-tree biome from a single command — a biomes/<id>/ directory whose xema-biome.json passes the canonical BiomeManifestSchema, whose server APIs bootstrap through XemaServiceModule.forBiome(...), and whose web surface registers through the host shell's loader glob. The output mirrors the first-party biomes the platform runs, so a new biome is immediately valid against the biome validator, the boundary checks, and generate-service-bootstrap.mjs.

What a generated biome already has

A scaffolded biome arrives working, not empty. Nothing below is authored by hand — each is derived from a declaration the biome already makes:

| It declares | It already has | |---|---| | @XemaApiSurface(Public) + @XemaResource + @XemaRoute | four authorized, auditable, agent-callable capabilities — <domain>:item.{list,read,create,delete}@1 — in the capability graph, with input/output schemas, risk tiers and approval gating | | xema.capabilityDomain | the <domain> those refs are filed under | | defineWebBiome | routes and a nav entry | | a search-type contribution | a renderable search result-type | | renderHints.routeTemplate | a working deep link into the paired detail page | | a ConnectorAdapterModule (connector kind) | connector capabilities, connection setup, credential custody, OAuth and preflight |

No capability descriptor is written, and none should be. The generated biome ships the conformance test that asserts its exact projected capability set, so the promise is checkable on day one: pnpm test in its API package.

Kinds

• service — a server biome with one NestJS API plus skills/, agents/, contributions/, and workspace-manifests/.
• web — a frontend-only biome: a nav item, a project-scoped lazy route page, and the navHidden detail route deep links land on.
• full — both a server biome and its paired web surface, wired together via requiresServerBiomes.
• connector — a credential-bearing capability provider: one ConnectorAdapterModule and nothing else. Ships no API and no web surface, and depends on no other biome, as tooling/boundaries/check-connector-biome.mjs requires.

When to use it

• Use it to bootstrap a brand-new in-tree biome of any kind.

Installation

# No install needed — run it directly from the monorepo root:
pnpm dlx @xemahq/create-biome <biomeId>

Usage

# Default (no flags) = the smallest viable server biome:
# --kind service --scope platform, ONE api, no optional manifest blocks.
pnpm dlx @xemahq/create-biome my-biome

# Richer layouts stay behind flags:
pnpm dlx @xemahq/create-biome my-portal --kind full --scope base
pnpm dlx @xemahq/create-biome connector-acme --kind connector

After scaffolding a server/full biome, run node tooling/codegen/generate-service-bootstrap.mjs and pnpm refresh from the monorepo root. For web/full, the host's transpilePackages and tsconfig paths are glob-derived — the host's biomes:generate script (run by its predev/prebuild) picks the new biome up with no manual list edit.

License

Business Source License 1.1 (BSL-1.1) — source-available; converts to MPL-2.0 four years after each release. © Xema — xema.dev. See the repository LICENSE.