Showrunner

Cratis Showrunner adds support, licensing, announcements, product feedback and email to applications built on Cratis. It provides .NET libraries, TypeScript clients generated from backend commands and queries, and React components. It also includes Stage Manager, a Kubernetes operator for running applications.

Choose the part that matches what your application needs. The libraries run inside the application that hosts them; Stage Manager runs as a service in your cluster. The sections below lead to setup instructions for each part.

Usher

Usher lets users report issues and carry on support conversations from the application. Its backend adds commands, queries and events to the host's Arc application and Chronicle event store; its frontend packages supply the generated TypeScript clients and React components.

Usher captures errors and lets a reporter grant time-limited support access through AuthProxy's on-behalf sessions, where support acts as the reporter. Public events connect the application to a support desk. Start with the Usher documentation to connect those two sides.

Box Office

Box Office lets a managed product honor the licensing decisions its operator makes for each tenant: trials, seats, modules, compute allowances and suspension. The product receives those decisions and reports back through public events. The operator's catalog holds offers and prices; the product declares what it sells and meters compute use. Follow the Box Office documentation to separate the operator's responsibilities from the product's.

Marquee

Marquee brings product announcements to the people they concern. The people running the product choose the audience, display and time window; the product shows the announcement as a banner or dialog. Add <Marquee /> to the application shell to use its queries and commands. Follow the Marquee documentation to add announcements or host the authoring side.

Notes

Notes connects product feedback to what the user was looking at: a slice of application behavior, a screen or a single component. The people building the application receive that context as events and answer the note. The application hosts Cratis.Showrunner.Notes; the builder hosts Cratis.Showrunner.Notes.Collecting. Use the Notes documentation to connect feedback collection and replies.

Herald

Herald sends application email from templates and records what happened. The application supplies an email kind, such as an invitation, a language and its values. Herald fills the template, makes the HTML safe for email clients, embeds images and sends it over SMTP. Failed sends are queued and retried. Start with the Herald documentation to configure templates and delivery.

Stage Manager

Stage Manager runs applications in Kubernetes. Install it as a service with the cratis/showrunner-operator Helm chart. A Performance runs an application with its AuthProxy and, when onboarding is configured, its own Ante from a Cratis environment. The application is reachable only through AuthProxy. A Performance can also run a published Stage application.

Performance is reconciled: the operator acts on it to run the application. The other resources have schemas only; nothing acts on them yet. Follow the Stage Manager documentation to install the operator and run an application.

Packages

Choose the backend packages for the part you are hosting, then add its TypeScript proxies or React components if the application needs a frontend. The contract packages contain the public events exchanged between hosts. Stage Manager ships separately as a container image and Helm chart, not a NuGet package.

Building

To work on Showrunner, use the .NET 11 SDK selected by global.json, the .NET 10 SDK for the libraries' net10.0 targets and inline specifications, and Node.js 20 or later with Corepack enabled (corepack enable). Yarn is checked in under .yarn/releases.

Run the commands below from the repository root. The full solution test command includes container-based integration specifications, so Docker must be running.

# Backend: Debug builds compile the inline specs and regenerate the TypeScript proxies
dotnet build Showrunner.slnx --configuration Debug
dotnet test Showrunner.slnx --configuration Debug --no-build

# Release is warnings-as-errors; clearing CratisProxiesOutputPath skips proxy generation
dotnet build Showrunner.slnx --configuration Release -p:CratisProxiesOutputPath=

# Frontend
yarn install
yarn lint:ci
yarn compile
yarn test
yarn build

Specifications live beside the code they specify: for_*/when_*/ folders compiled into Debug builds only for .NET, and Vitest specs in the same layout for TypeScript. The Debug build regenerates TypeScript proxies from the backend; do not edit the generated proxies by hand. The pull request build checks that regeneration leaves the committed proxies unchanged.

For a focused integration run, Integration runs Usher and a desk against Chronicle in a container. Integration.Notes runs an application and a collecting host using the same container fixture code. For these two projects, set USHER_CHRONICLE_IMAGE to choose another kernel image and USHER_INTEGRATION_LOG to a file path to keep the hosts' logs.

Integration.Herald/ also tests against Chronicle in a container; its image override is HERALD_CHRONICLE_IMAGE. Integration.BoxOffice/ tests metering storage against MongoDB in Docker.

Releasing

Every pull request carries exactly one of the major, minor, patch or no-release labels. Merging a version-labelled pull request to main releases the NuGet and npm packages under one semantic version through cratis/release-action. Use no-release to skip publishing. Stage Manager's container image and Helm chart are released with the same version.

NuGet and npm use trusted publishing through OpenID Connect (OIDC), with provenance for npm. Build and pack jobs have no publishing rights; separate publish jobs receive short-lived publishing credentials and push the packed artifacts. The npm publisher disables lifecycle scripts when publishing the tarballs.

Part of the Cratis ecosystem

Showrunner is a Cratis project. Its application libraries use Chronicle to store changes as events. Those with commands and queries use Arc to handle writes and reads separately, the pattern called CQRS. The React components build on @cratis/components. Join the community on Discord.

License

See the MIT License for the terms covering this repository.