`, `ISBN` is an `EventSourceId`, and identifiers such as `AuthorId` and `MemberId` are dedicated types rather than loose primitives. A Debug build regenerates the TypeScript commands, queries, and models used by each React slice.
+
+## Build and verify
+
+From the Samples repository root:
+
+```bash
+dotnet build Library/Library.slnx --configuration Debug
+dotnet test Library/Library.slnx --configuration Debug --no-build
+dotnet build Library/Library.slnx --configuration Release -p:CratisProxiesOutputPath=
+yarn --cwd Library/Lending build
+yarn --cwd Library/Members build
+```
+
+## Ideas to try
+
+- Register an author, then add a book and select that author in the generated command form.
+- Keep the Authors or Books table open while changing data and observe the query update.
+- Open Chronicle Workbench and follow `AuthorRegistered` or `BookAddedToInventory` from event to projection.
+- Compare `Registration.cs`, its generated `RegisterAuthor.ts` proxy, and `AddAuthor.tsx` to see the full-stack type flow.
+- Follow book availability through the lending reducers, then inspect the borrowing event contracts on each side.
+- Run the colocated specifications from this directory with `dotnet test Library.slnx`.
diff --git a/ModelFirst/Library/README.md b/ModelFirst/Library/README.md
new file mode 100644
index 00000000..409f7e7b
--- /dev/null
+++ b/ModelFirst/Library/README.md
@@ -0,0 +1,80 @@
+
+
+# Model-First Library
+
+### Write the behavior once. Compile it. Run the specifications.
+
+**Screenplay · Stage · Commands · Events · Model specifications**
+
+[Back to all samples](../../README.md)
+
+
+
+---
+
+## The idea
+
+[`library.play`](./library.play) describes one small catalog workflow as a software model:
+
+```text
+AddBook command
+ │
+ ├── validates title and author
+ │
+ ▼
+BookAddedToCatalog event
+```
+
+The same file contains one accepted example and one rejected example. Screenplay compiles the model; Stage runs those examples as model-level specifications.
+
+```mermaid
+flowchart LR
+ model[library.play] --> compiler[Screenplay compiler]
+ compiler --> stage[Stage specification runner]
+ stage --> result[2 model specifications]
+```
+
+## What is in the model
+
+- `BookId`, `BookTitle`, and `AuthorName` concepts;
+- an `AddBook` state-change slice;
+- required title and author rules;
+- the `BookAddedToCatalog` fact;
+- one successful scenario;
+- one expected validation rejection.
+
+Open [`library.play`](./library.play) before running anything—the complete behavior fits on one screen.
+
+## Run it
+
+This sample uses already-built local Screenplay and Stage checkouts. With the standard Cratis sibling-repository layout, run these commands from this directory:
+
+```bash
+export SCREENPLAY_REPO=${SCREENPLAY_REPO:-../../../Screenplay}
+export STAGE_REPO=${STAGE_REPO:-../../../Stage}
+
+# Compile the model and treat warnings as errors.
+dotnet run --no-build --no-restore \
+ --project "$SCREENPLAY_REPO/Source/DotNET/Tool/Tool.csproj" -- \
+ "$PWD/library.play" --warnaserror
+
+# Run the specifications embedded in the model.
+RESULTS_PATH="${TMPDIR:-/tmp}/cratis-library-stage-results.json"
+dotnet run --no-build --no-restore \
+ --project "$STAGE_REPO/Source/SpecRunner/SpecRunner.csproj" -- \
+ --model "$PWD" --output "$RESULTS_PATH"
+
+cat "$RESULTS_PATH"
+```
+
+The current model compiles without diagnostics and produces two passing specification results.
+
+## Make it yours
+
+- Add an ISBN concept and require it on `AddBook`.
+- Add a second rejection for an empty author name.
+- Introduce a read model after exploring the focused state-change slice.
+- Change an expected event value and watch the specification catch it.
+
+> [!NOTE]
+> This is the first bounded model-first step. It verifies compilation and model specifications; it does not yet demonstrate a live Chronicle command, query results, Scene UI, complete source generation, or a Studio round trip.
diff --git a/ModelFirst/Library/library.play b/ModelFirst/Library/library.play
new file mode 100644
index 00000000..9d8388c9
--- /dev/null
+++ b/ModelFirst/Library/library.play
@@ -0,0 +1,51 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+// A deliberately small model-first sample: one command, one fact, and two model specifications.
+domain Library
+
+concept BookId : Uuid
+concept BookTitle : String
+concept AuthorName : String
+
+module Library
+ description "A small catalog model used to demonstrate the model-first developer journey"
+
+ feature Catalog
+ description "Adding a book to the library catalog"
+
+ slice StateChange AddBook
+ description "Adds one identified book to the catalog"
+
+ command AddBook
+ bookId BookId identifier
+ title BookTitle
+ authorName AuthorName
+
+ validate
+ title not empty message "A title is required"
+ authorName not empty message "An author name is required"
+
+ produces BookAddedToCatalog
+ title = title
+ authorName = authorName
+
+ event BookAddedToCatalog
+ title BookTitle
+ authorName AuthorName
+
+ specification AddingABook
+ when AddBook
+ bookId = "75926956-26c2-4e60-a239-10367a2afbd8"
+ title = "The Quiet Archive"
+ authorName = "Mara North"
+ then BookAddedToCatalog
+ title = "The Quiet Archive"
+ authorName = "Mara North"
+
+ specification RejectingABookWithoutATitle
+ when AddBook
+ bookId = "69064f39-6a76-458a-8a34-088eb4752650"
+ title = ""
+ authorName = "Mara North"
+ then error "A title is required"
diff --git a/NuGet.config b/NuGet.config
index 94410df1..31f07936 100644
--- a/NuGet.config
+++ b/NuGet.config
@@ -1,7 +1,7 @@
-
+
diff --git a/README.md b/README.md
index 5b87ad8c..0f4d8667 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,112 @@
+
+
# Cratis Samples
-[](https://github.com/Cratis/Samples/actions/workflows/build.yml)
-[](https://github.com/Cratis/Samples/actions/workflows/update-dependencies.yml)
-[](https://github.com/Cratis/Samples/actions/workflows/documentation.yml)
+### Learn the Cratis stack by running real applications
+
+From a small Chronicle process to a React application composed with Arc, Components, and Aspire.
+
+[](https://github.com/Cratis/Samples/actions/workflows/build.yml)
+[](https://github.com/Cratis/Samples/actions/workflows/update-dependencies.yml)
+[](https://github.com/Cratis/Samples/actions/workflows/documentation.yml)
+
+[Explore the samples](#pick-a-sample) · [Run locally](#run-locally) · [Browse the documentation](https://cratis.io/samples/)
+
+
+
+---
+
+## Pick a sample
+
+| Sample | Experience | Products | Start here |
+| --- | --- | --- | --- |
+| **[Chronicle Backend](./Chronicle/Backend/README.md)** | HTTP API | Chronicle | Append one immutable fact and read an event source's history. |
+| **[Chronicle Processing](./Chronicle/Processing/README.md)** | HTTP API | Chronicle, Fundamentals | Compare a projection, reducer, and reactor on one event stream. |
+| **[Idea Loom — Arc + React](./Arc/React/README.md)** | React | Arc, Components, Fundamentals | Follow a typed command and observable query from C# to a polished UI. |
+| **[Chronicle Multi-Tenancy](./Chronicle/MultiTenancy/README.md)** | HTTP API | Arc, Chronicle, Fundamentals | Isolate the same typed workflow across tenant namespaces. |
+| **[Chronicle Cross-Store](./Chronicle/CrossStore/README.md)** | HTTP API | Chronicle, Fundamentals | Connect two event stores through an outbox, inbox, and local translation. |
+| **[Chronicle Operations Diagnosis](./Chronicle/OperationsDiagnosis/README.md)** | CLI + Workbench | Chronicle, CLI, Fundamentals | Create one known failure and learn to inspect it before repair. |
+| **[Chronicle with ASP.NET Core](./Chronicle/Quickstart/AspNetCore/README.md)** | HTTP API | Chronicle | Host Chronicle through dependency injection and expose focused endpoints. |
+| **[Model-First Library](./ModelFirst/Library/README.md)** | Executable model | Screenplay, Stage | Compile one modeled workflow and run its accepted and rejected examples. |
+| **[Library](./Library/README.md)** | React + APIs | Arc, Chronicle, Components | Explore separate lending and membership applications under one local composition. |
+
+> [!TIP]
+> Start with Chronicle Backend for the smallest HTTP path, then open Chronicle Processing to compare projections, reducers, and reactors. Move to Library when you want generated TypeScript contracts and React.
+
+## What the journey looks like
+
+```text
+Arc: command → current-state store → observable query → React
+Chronicle: append → event history → projections / reactions → views
+Model-first: .play model → Screenplay compiler → Stage specifications
+```
+
+Choose the path matching what you want to learn. The focused samples keep one idea in view; Library brings several paths together in a larger application.
+
+## Run locally
+
+### You will need
+
+- [.NET 10 SDK](https://dotnet.microsoft.com/download)
+- [Docker](https://www.docker.com/) or another compatible container runtime
+- Node.js 23 or newer for the React applications
+- Corepack/Yarn for frontend work
+
+Clone the repository and validate the catalog:
+
+```bash
+git clone https://github.com/Cratis/Samples.git
+cd Samples
+corepack enable
+yarn install
+yarn samples:validate
+yarn lint:ci
+yarn build
+```
+
+Build the .NET samples:
+
+```bash
+dotnet restore Samples.slnx
+dotnet build Samples.slnx --configuration Debug
+dotnet test Samples.slnx --configuration Debug --no-build
+dotnet build Samples.slnx --configuration Release -p:CratisProxiesOutputPath=
+```
+
+Each sample README contains its own infrastructure and run commands, a short tour of the code, and ideas to try next.
+
+## How the repository is organized
+
+```text
+Arc/ standalone Arc and React samples
+Chronicle/ focused Chronicle samples
+ModelFirst/ executable Screenplay and Stage samples
+Library/ the larger React and multi-service showcase
+samples.json the catalog used by repository checks and the documentation site
+scripts/ catalog and repository checks
+```
+
+The catalog is deliberately machine-readable. The [Cratis documentation sample roster](https://cratis.io/samples/) is generated from it so descriptions and source links stay aligned with the runnable projects. A sample can add `previewUrl` and `previewLabel` when a real read-only experience, such as an event-model viewer, is available.
+
+## Samples are for learning
+
+These projects favor clarity and visible behavior. They demonstrate exact, documented combinations of Cratis packages and local infrastructure; they are not production templates or support commitments. Every sample calls out the pieces it intentionally leaves out.
+
+## Contributing a sample
+
+A sample should be enjoyable to explore and easy to understand:
+
+1. Give it one clear learning goal.
+2. Keep it independently runnable.
+3. Include an inviting `README.md` with an architecture sketch, exact commands, expected behavior, and a few ideas to try.
+4. Add tests for the behavior the sample teaches.
+5. Add the entry to [`samples.json`](./samples.json).
+6. Run `yarn samples:validate` and the sample's own build and test commands.
+
+---
+
+
-This repository consists of samples for the things you find in the Cratis universe.
+**Build something, change it, and watch the model and runtime tell the same story.**
-| Project | Description |
-| ------- | ----------- |
-| [Chronicle Console Quickstart](./Chronicle/Quickstart/Console/README.md) | The starting point for getting started with Cratis Chronicle with a simple .NET Console application |
-| [Chronicle AspNetCore Quickstart](./Chronicle/Quickstart/AspNetCore) | The starting point for getting started with Cratis Chronicle with an AspNet.Core based application |
-| [Library](./Library/README.md) | An end-to-end implementation based for an imaginary Library. |
+
diff --git a/Samples.slnx b/Samples.slnx
index 38b35f24..860c2da7 100644
--- a/Samples.slnx
+++ b/Samples.slnx
@@ -5,12 +5,35 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
diff --git a/eslint.config.mjs b/eslint.config.mjs
index d6de0f39..9f80ae91 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -7,10 +7,9 @@ import typescriptEslint from '@typescript-eslint/eslint-plugin';
import tsParser from '@typescript-eslint/parser';
import noNull from 'eslint-plugin-no-null';
import globals from 'globals';
+import header from 'eslint-plugin-header';
import tseslint from 'typescript-eslint';
-header.rules.header.meta.schema = false;
-
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const compat = new FlatCompat({
@@ -23,7 +22,7 @@ const getRules = configArray => {
let rules = {};
const addRulesFromObject = config => {
- if (config.hasOwnProperty('rules')) {
+ if (Object.hasOwn(config, 'rules')) {
rules = {
...rules,
...config.rules,
@@ -67,15 +66,6 @@ const rules = {
'@typescript-eslint/ban-ts-comment': 0,
"@typescript-eslint/no-empty-interface": 0,
- 'header/header': [
- 2,
- 'line',
- [
- ' Copyright (c) Cratis. All rights reserved.',
- ' Licensed under the MIT license. See LICENSE file in the project root for full license information.'
- ],
- 1
- ],
},
};
@@ -124,6 +114,12 @@ const defaultConfig = [
},
},
},
+ {
+ files: ['Library/**/*.ts'],
+ rules: {
+ '@typescript-eslint/no-explicit-any': 'off',
+ },
+ },
{
files: ['**/for_*/**/*.ts'],
rules: {
diff --git a/package.json b/package.json
index dc4a9fe3..1244f6e3 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,7 @@
{
"private": true,
"workspaces": [
+ "Arc/React",
"Library/Lending",
"Library/Members"
],
@@ -24,8 +25,10 @@
"clean": "node ./run-task-on-workspaces.cjs clean",
"build": "node ./run-task-on-workspaces.cjs build",
"lint": "node ./run-task-on-workspaces.cjs lint",
+ "lint:ci": "node ./run-task-on-workspaces.cjs lint:ci",
"test": "node ./run-task-on-workspaces.cjs test",
"ci": "node ./run-task-on-workspaces.cjs ci",
+ "samples:validate": "node ./scripts/validate-samples.mjs",
"publish-version": "node ./run-task-on-workspaces.cjs publish-version $*",
"update": "node ./run-task-on-workspaces.cjs update"
},
diff --git a/run-task-on-workspaces.cjs b/run-task-on-workspaces.cjs
index ffdc532d..49bd75f0 100755
--- a/run-task-on-workspaces.cjs
+++ b/run-task-on-workspaces.cjs
@@ -12,7 +12,7 @@ if (process.argv.length < 3) {
const path = require('path');
const fs = require('fs');
-const spawn = require('child_process').spawnSync;
+const spawnSync = require('child_process').spawnSync;
const editJsonFile = require('edit-json-file');
const rootPackageJson = require('./package.json')
const glob = require('glob').sync;
@@ -24,13 +24,22 @@ const distFolder = `dist${path.sep}`
for (const workspaceDef of rootPackageJson.workspaces) {
console.log(`Getting packages for workspace definition '${workspaceDef}' \n`);
- const files = glob(workspaceDef, { cwd: process.cwd() });
+ const packagePattern = workspaceDef.endsWith('package.json')
+ ? workspaceDef
+ : `${workspaceDef.replace(/\/$/, '')}/package.json`;
+ const files = glob(packagePattern, { cwd: process.cwd() });
const packages = files
- .filter(_ => path.basename(_) === 'package.json' && _.indexOf(distFolder) < 0 && _.indexOf('node_modules') < 0)
+ .filter(_ => !_.includes(distFolder) && !_.includes('node_modules'))
.sort((a, b) => a.length - b.length);
packages.forEach(_ => {
- const localPackage = JSON.parse(fs.readFileSync(_).toString());
+ let localPackage;
+ try {
+ localPackage = JSON.parse(fs.readFileSync(_).toString());
+ } catch (error) {
+ console.error(`Could not read workspace package '${_}':`, error.message);
+ process.exit(1);
+ }
workspaces[localPackage.name] = path.dirname(_);
console.log(`Including workspace '${localPackage.name}' at '${workspaces[localPackage.name]}'`);
@@ -80,12 +89,12 @@ for (const workspaceName in workspaces) {
if (fs.existsSync(packageJsonFile)) {
const file = editJsonFile(packageJsonFile, { stringify_width: 4 });
const packageJson = file.toObject();
- if (packageJson.private === true) {
- console.log(`Workspace private '${workspaceName}' at '${workspaceRelativeLocation}'`);
- continue;
- }
-
if (task === 'publish-version') {
+ if (packageJson.private === true) {
+ console.log(`Skipping private workspace '${workspaceName}' at '${workspaceRelativeLocation}'`);
+ continue;
+ }
+
if (args.length === 1) {
const version = args[0];
file.set('version', version);
@@ -99,7 +108,7 @@ for (const workspaceName in workspaces) {
}
console.log(`Publishing workspace '${workspaceName}' at '${workspaceRelativeLocation}'`);
- const result = spawn('npm', ['publish'], { cwd: workspaceAbsoluteLocation, shell: true });
+ const result = spawnSync('npm', ['publish'], { cwd: workspaceAbsoluteLocation, shell: false });
console.log(result.stdout.toString());
if (result.status !== 0) {
console.log(`Error publishing workspace '${workspaceName}'`);
@@ -108,14 +117,14 @@ for (const workspaceName in workspaces) {
}
} else {
- if (!packageJson.scripts || !packageJson.scripts.hasOwnProperty(task)) {
+ if (!packageJson.scripts || !Object.hasOwn(packageJson.scripts, task)) {
console.log(`Skipping workspace '${workspaceName}' - no script with name '${task}'`);
continue;
}
console.log(`Workspace '${workspaceName}' at '${workspaceRelativeLocation}'`);
- const result = spawn('yarn', [task], { cwd: workspaceAbsoluteLocation, shell: true });
+ const result = spawnSync('yarn', [task], { cwd: workspaceAbsoluteLocation, shell: false });
if (result.error) {
console.log(`Error running task '${task}' on workspace '${workspaceName}':`,
result.error.message);
diff --git a/samples.json b/samples.json
new file mode 100644
index 00000000..162377b1
--- /dev/null
+++ b/samples.json
@@ -0,0 +1,288 @@
+{
+ "$schema": "./samples.schema.json",
+ "schemaVersion": 1,
+ "tracks": [
+ {
+ "id": "getting-started",
+ "title": "Getting started",
+ "description": "Meet Chronicle in a small application and follow an event from append to observation."
+ },
+ {
+ "id": "event-processing",
+ "title": "Event processing",
+ "description": "Turn recorded facts into useful views and follow-up behavior with projections, reducers, and reactors."
+ },
+ {
+ "id": "full-stack-cqrs",
+ "title": "Full-stack CQRS",
+ "description": "Build typed commands and observable queries from C# through generated contracts to React."
+ },
+ {
+ "id": "boundaries",
+ "title": "Boundaries and isolation",
+ "description": "Keep tenant data and bounded contexts separate while allowing explicit, typed communication."
+ },
+ {
+ "id": "operations",
+ "title": "Operations",
+ "description": "Create a known local symptom and learn to inspect Chronicle before taking action."
+ },
+ {
+ "id": "model-first",
+ "title": "Model-first",
+ "description": "Describe behavior as an executable model, compile it, and run its specifications."
+ },
+ {
+ "id": "full-applications",
+ "title": "Full applications",
+ "description": "Explore how Cratis products fit together across backend, frontend, runtime, and local composition."
+ }
+ ],
+ "samples": [
+ {
+ "id": "chronicle-backend",
+ "title": "Chronicle Backend",
+ "tagline": "Append an immutable fact and read one event source's history through a focused HTTP API.",
+ "track": "getting-started",
+ "path": "Chronicle/Backend",
+ "sourceUrl": "https://github.com/Cratis/Samples/tree/main/Chronicle/Backend",
+ "ui": "None",
+ "level": "Start here",
+ "products": ["Chronicle"],
+ "runtime": ["ASP.NET Core", "Chronicle"],
+ "prerequisites": [".NET 10 SDK", "Docker", "curl"],
+ "highlights": [
+ "Configure one named Chronicle event store",
+ "Use ConceptAs and EventSourceId for clear domain values and identities",
+ "Read the stored history without introducing a projection"
+ ],
+ "verification": [
+ "dotnet build Chronicle/Backend/Backend.csproj --configuration Debug",
+ "dotnet test Chronicle/Backend/Backend.Specs/Backend.Specs.csproj"
+ ],
+ "limitations": [
+ "The sample teaches the event log directly and intentionally leaves out projections and a frontend.",
+ "Its tests specify the Chronicle-facing behavior without starting external infrastructure."
+ ],
+ "featured": true
+ },
+ {
+ "id": "chronicle-processing",
+ "title": "Chronicle Processing",
+ "tagline": "See one event stream feed a projection, reducer, and reactor without timing guesses.",
+ "track": "event-processing",
+ "path": "Chronicle/Processing",
+ "sourceUrl": "https://github.com/Cratis/Samples/tree/main/Chronicle/Processing",
+ "ui": "None",
+ "level": "Focused",
+ "products": ["Chronicle", "Fundamentals"],
+ "runtime": ["ASP.NET Core", "Chronicle"],
+ "prerequisites": [".NET 10 SDK", "Docker", "curl"],
+ "highlights": [
+ "Use ConceptAs values and an EventSourceId identity throughout the model",
+ "Compare a model-bound projection with a prior-state reducer",
+ "Return a deterministic follow-up event from a reactor"
+ ],
+ "verification": [
+ "dotnet build Chronicle/Processing/Processing.csproj --configuration Debug",
+ "dotnet test Chronicle/Processing/Processing.Specs/Processing.Specs.csproj"
+ ],
+ "limitations": [
+ "The endpoint uses fixed sample data so the processing styles stay in focus.",
+ "The sample is backend-only and uses local Chronicle development infrastructure."
+ ],
+ "featured": true
+ },
+ {
+ "id": "arc-react",
+ "title": "Idea Loom — Arc + React",
+ "tagline": "Build a polished command-and-query experience with generated contracts and no event sourcing.",
+ "track": "full-stack-cqrs",
+ "path": "Arc/React",
+ "sourceUrl": "https://github.com/Cratis/Samples/tree/main/Arc/React",
+ "ui": "React",
+ "level": "Focused",
+ "products": ["Arc", "Components", "Fundamentals"],
+ "runtime": ["ASP.NET Core", "React"],
+ "prerequisites": [".NET 10 SDK", "Node.js 23 or newer", "Yarn"],
+ "highlights": [
+ "Use ConceptAs values and validators in a model-bound Arc command",
+ "Generate TypeScript command, query, and read-model contracts",
+ "Compose React MVVM, an observable query, and a Cratis CommandDialog"
+ ],
+ "verification": [
+ "dotnet build Arc/React/Arc.React.csproj --configuration Debug",
+ "dotnet test Arc/React/Arc.React.Specs/Arc.React.Specs.csproj",
+ "yarn --cwd Arc/React build"
+ ],
+ "limitations": [
+ "The current-state store is in memory so the Arc and React boundary stays easy to see.",
+ "This sample deliberately does not use Chronicle."
+ ],
+ "featured": true
+ },
+ {
+ "id": "chronicle-multi-tenancy",
+ "title": "Chronicle Multi-Tenancy",
+ "tagline": "Use Arc header tenancy to isolate the same workflow in separate Chronicle namespaces.",
+ "track": "boundaries",
+ "path": "Chronicle/MultiTenancy",
+ "sourceUrl": "https://github.com/Cratis/Samples/tree/main/Chronicle/MultiTenancy",
+ "ui": "None",
+ "level": "Focused",
+ "products": ["Arc", "Chronicle", "Fundamentals"],
+ "runtime": ["ASP.NET Core", "Chronicle", "MongoDB"],
+ "prerequisites": [".NET 10 SDK", "Docker", "curl"],
+ "highlights": [
+ "Resolve the tenant from Arc's standard header",
+ "Map tenant context to Chronicle namespaces",
+ "Use the same EventSourceId safely in tenant A, tenant B, and Default"
+ ],
+ "verification": [
+ "dotnet build Chronicle/MultiTenancy/MultiTenancy.csproj --configuration Debug",
+ "dotnet test Chronicle/MultiTenancy/MultiTenancy.Specs/MultiTenancy.Specs.csproj"
+ ],
+ "limitations": [
+ "The tenant header selects context but is not an authorization policy.",
+ "The sample is backend-only and uses local development infrastructure."
+ ],
+ "featured": true
+ },
+ {
+ "id": "chronicle-cross-store",
+ "title": "Chronicle Cross-Store",
+ "tagline": "Connect two named event stores through a typed outbox, filtered inbox, and local translation.",
+ "track": "boundaries",
+ "path": "Chronicle/CrossStore",
+ "sourceUrl": "https://github.com/Cratis/Samples/tree/main/Chronicle/CrossStore",
+ "ui": "None",
+ "level": "Advanced",
+ "products": ["Chronicle", "Fundamentals"],
+ "runtime": ["ASP.NET Core", "Chronicle"],
+ "prerequisites": [".NET 10 SDK", "Docker", "curl"],
+ "highlights": [
+ "Keep Orders and Fulfillment in separate event stores",
+ "Forward one narrow contract through source outbox and target inbox",
+ "Translate the contract into a target-owned event and read model"
+ ],
+ "verification": [
+ "dotnet build Chronicle/CrossStore/CrossStore.csproj --configuration Debug",
+ "dotnet test Chronicle/CrossStore/CrossStore.Specs/CrossStore.Specs.csproj"
+ ],
+ "limitations": [
+ "Cross-store processing is asynchronous and is not a distributed transaction.",
+ "The sample does not claim exactly-once delivery."
+ ],
+ "featured": true
+ },
+ {
+ "id": "chronicle-aspnetcore-quickstart",
+ "title": "Chronicle with ASP.NET Core",
+ "tagline": "Host the same event-processing concepts behind a small HTTP API.",
+ "track": "getting-started",
+ "path": "Chronicle/Quickstart/AspNetCore",
+ "sourceUrl": "https://github.com/Cratis/Samples/tree/main/Chronicle/Quickstart/AspNetCore",
+ "ui": "None",
+ "level": "Start here",
+ "products": ["Chronicle"],
+ "runtime": ["ASP.NET Core", "Chronicle", "MongoDB"],
+ "prerequisites": [".NET 10 SDK", "Docker", "curl"],
+ "highlights": [
+ "Configure Chronicle through ASP.NET Core dependency injection",
+ "Register reducers, projections, reactors, and query services",
+ "Append events through minimal HTTP endpoints"
+ ],
+ "verification": [
+ "dotnet build Chronicle/Quickstart/AspNetCore/AspNetCore.csproj --configuration Debug"
+ ],
+ "limitations": [
+ "The sample concentrates on backend hosting and does not include a browser frontend.",
+ "Its HTTP surface is deliberately small."
+ ],
+ "featured": true
+ },
+ {
+ "id": "chronicle-operations-diagnosis",
+ "title": "Chronicle Operations Diagnosis",
+ "tagline": "Create one deterministic failed partition and find it with the CLI and Workbench.",
+ "track": "operations",
+ "path": "Chronicle/OperationsDiagnosis",
+ "sourceUrl": "https://github.com/Cratis/Samples/tree/main/Chronicle/OperationsDiagnosis",
+ "ui": "Workbench and CLI",
+ "level": "Focused",
+ "products": ["Chronicle", "Cratis CLI", "Fundamentals"],
+ "runtime": ["ASP.NET Core", "Chronicle", "CLI", "Workbench"],
+ "prerequisites": [".NET 10 SDK", "Docker", "Cratis CLI", "curl"],
+ "highlights": [
+ "Use typed probe identity and name values",
+ "Create one stable reactor failure",
+ "Inspect the event, observer, and failed partition without repair actions"
+ ],
+ "verification": [
+ "dotnet build Chronicle/OperationsDiagnosis/OperationsDiagnosis.csproj --configuration Debug",
+ "dotnet test Chronicle/OperationsDiagnosis/OperationsDiagnosis.Specs/OperationsDiagnosis.Specs.csproj"
+ ],
+ "limitations": [
+ "The POST endpoint intentionally creates local fixture data.",
+ "Replay, retry, quarantine changes, redaction, and administration are outside the sample."
+ ],
+ "featured": true
+ },
+ {
+ "id": "model-first-library",
+ "title": "Model-First Library",
+ "tagline": "Compile one Screenplay model and run its accepted and rejected examples through Stage.",
+ "track": "model-first",
+ "path": "ModelFirst/Library",
+ "sourceUrl": "https://github.com/Cratis/Samples/tree/main/ModelFirst/Library",
+ "ui": "None",
+ "level": "Focused",
+ "products": ["Screenplay", "Stage"],
+ "runtime": ["Screenplay compiler", "Stage specification runner"],
+ "prerequisites": [".NET 10 SDK", "Built Screenplay checkout", "Built Stage checkout"],
+ "highlights": [
+ "Describe concepts, a command, validation, and an event in one model",
+ "Keep accepted and rejected examples beside the behavior",
+ "Compile with Screenplay and run model specifications with Stage"
+ ],
+ "verification": [
+ "dotnet run --no-build --no-restore --project ../../../Screenplay/Source/DotNET/Tool/Tool.csproj -- library.play --warnaserror",
+ "dotnet run --no-build --no-restore --project ../../../Stage/Source/SpecRunner/SpecRunner.csproj -- --model ."
+ ],
+ "limitations": [
+ "The sample verifies the model and its specifications without running a live Chronicle command.",
+ "Scene UI, source generation, and Studio round trips are intentionally outside this first step."
+ ],
+ "featured": true
+ },
+ {
+ "id": "library-showcase",
+ "title": "Library",
+ "tagline": "Tour a larger Cratis application with separate lending and membership experiences.",
+ "track": "full-applications",
+ "path": "Library",
+ "sourceUrl": "https://github.com/Cratis/Samples/tree/main/Library",
+ "ui": "React",
+ "level": "Showcase",
+ "products": ["Arc", "Chronicle", "Components"],
+ "runtime": ["ASP.NET Core", "React", "Aspire", "Chronicle", "MongoDB"],
+ "prerequisites": [".NET 10 SDK", "Node.js 23 or newer", "Corepack/Yarn", "Docker", "Bash"],
+ "highlights": [
+ "Organize behavior as cohesive vertical slices",
+ "Generate TypeScript contracts from backend commands and queries",
+ "Compose separate lending and membership applications for local development"
+ ],
+ "verification": [
+ "dotnet build Library/Library.slnx --configuration Debug",
+ "dotnet build Library/Library.slnx --configuration Release -p:CratisProxiesOutputPath=",
+ "yarn --cwd Library/Lending build",
+ "yarn --cwd Library/Members build"
+ ],
+ "limitations": [
+ "The MongoDB profile is the current reference path for the demonstrated read models.",
+ "Some domain flows are backend examples and are not yet represented by a dedicated screen."
+ ],
+ "featured": true
+ }
+ ]
+}
diff --git a/samples.schema.json b/samples.schema.json
new file mode 100644
index 00000000..762722dd
--- /dev/null
+++ b/samples.schema.json
@@ -0,0 +1,73 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": "https://cratis.io/schemas/samples.schema.json",
+ "title": "Cratis samples catalog",
+ "type": "object",
+ "required": ["schemaVersion", "tracks", "samples"],
+ "additionalProperties": false,
+ "properties": {
+ "schemaVersion": { "const": 1 },
+ "tracks": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "required": ["id", "title", "description"],
+ "additionalProperties": false,
+ "properties": {
+ "id": { "type": "string", "pattern": "^[a-z0-9-]+$" },
+ "title": { "type": "string", "minLength": 1 },
+ "description": { "type": "string", "minLength": 1 }
+ }
+ }
+ },
+ "samples": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "required": [
+ "id",
+ "title",
+ "tagline",
+ "track",
+ "path",
+ "sourceUrl",
+ "ui",
+ "level",
+ "products",
+ "runtime",
+ "prerequisites",
+ "highlights",
+ "verification",
+ "limitations"
+ ],
+ "additionalProperties": false,
+ "properties": {
+ "id": { "type": "string", "pattern": "^[a-z0-9-]+$" },
+ "title": { "type": "string", "minLength": 1 },
+ "tagline": { "type": "string", "minLength": 1 },
+ "track": { "type": "string", "pattern": "^[a-z0-9-]+$" },
+ "path": { "type": "string", "minLength": 1 },
+ "sourceUrl": { "type": "string", "format": "uri" },
+ "previewUrl": { "type": "string", "format": "uri-reference" },
+ "previewLabel": { "type": "string", "minLength": 1 },
+ "ui": { "enum": ["None", "Terminal", "React", "Workbench and CLI"] },
+ "level": { "enum": ["Start here", "Focused", "Advanced", "Showcase"] },
+ "products": { "$ref": "#/$defs/nonEmptyStrings" },
+ "runtime": { "$ref": "#/$defs/nonEmptyStrings" },
+ "prerequisites": { "$ref": "#/$defs/nonEmptyStrings" },
+ "highlights": { "$ref": "#/$defs/nonEmptyStrings" },
+ "verification": { "$ref": "#/$defs/nonEmptyStrings" },
+ "limitations": { "$ref": "#/$defs/nonEmptyStrings" },
+ "featured": { "type": "boolean" }
+ }
+ }
+ }
+ },
+ "$defs": {
+ "nonEmptyStrings": {
+ "type": "array",
+ "minItems": 1,
+ "items": { "type": "string", "minLength": 1 }
+ }
+ }
+}
diff --git a/scripts/validate-samples.mjs b/scripts/validate-samples.mjs
new file mode 100644
index 00000000..fe4d4099
--- /dev/null
+++ b/scripts/validate-samples.mjs
@@ -0,0 +1,115 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { access, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
+const repositoryRoot = path.resolve(scriptDirectory, '..');
+const catalogPath = path.join(repositoryRoot, 'samples.json');
+let catalog;
+try {
+ catalog = JSON.parse(await readFile(catalogPath, 'utf8'));
+} catch (error) {
+ console.error(`Could not read ${catalogPath}:`, error.message);
+ process.exit(1);
+}
+const errors = [];
+
+const requireText = (value, location) => {
+ if (typeof value !== 'string' || value.trim().length === 0) {
+ errors.push(`${location} must be a non-empty string`);
+ }
+};
+
+const requireStringList = (value, location) => {
+ if (!Array.isArray(value) || value.length === 0) {
+ errors.push(`${location} must contain at least one entry`);
+ return;
+ }
+
+ value.forEach((entry, index) => requireText(entry, `${location}[${index}]`));
+};
+
+if (catalog.schemaVersion !== 1) {
+ errors.push('schemaVersion must be 1');
+}
+
+if (!Array.isArray(catalog.tracks) || catalog.tracks.length === 0) {
+ errors.push('tracks must contain at least one track');
+}
+
+if (!Array.isArray(catalog.samples) || catalog.samples.length === 0) {
+ errors.push('samples must contain at least one sample');
+}
+
+const trackIds = new Set();
+for (const [index, track] of (catalog.tracks ?? []).entries()) {
+ const location = `tracks[${index}]`;
+ requireText(track.id, `${location}.id`);
+ requireText(track.title, `${location}.title`);
+ requireText(track.description, `${location}.description`);
+
+ if (trackIds.has(track.id)) {
+ errors.push(`${location}.id duplicates '${track.id}'`);
+ }
+ trackIds.add(track.id);
+}
+
+const sampleIds = new Set();
+for (const [index, sample] of (catalog.samples ?? []).entries()) {
+ const location = `samples[${index}]`;
+ for (const field of ['id', 'title', 'tagline', 'track', 'path', 'sourceUrl', 'ui', 'level']) {
+ requireText(sample[field], `${location}.${field}`);
+ }
+
+ for (const field of ['products', 'runtime', 'prerequisites', 'highlights', 'verification', 'limitations']) {
+ requireStringList(sample[field], `${location}.${field}`);
+ }
+
+ if (sample.previewUrl || sample.previewLabel) {
+ requireText(sample.previewUrl, `${location}.previewUrl`);
+ requireText(sample.previewLabel, `${location}.previewLabel`);
+ }
+
+ if (sampleIds.has(sample.id)) {
+ errors.push(`${location}.id duplicates '${sample.id}'`);
+ }
+ sampleIds.add(sample.id);
+
+ if (!trackIds.has(sample.track)) {
+ errors.push(`${location}.track references unknown track '${sample.track}'`);
+ }
+
+ const sampleDirectory = path.resolve(repositoryRoot, sample.path ?? '');
+ const relativePath = path.relative(repositoryRoot, sampleDirectory);
+ if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+ errors.push(`${location}.path must stay inside the repository`);
+ continue;
+ }
+
+ try {
+ const sampleStats = await stat(sampleDirectory);
+ if (!sampleStats.isDirectory()) {
+ errors.push(`${location}.path is not a directory: ${sample.path}`);
+ }
+ } catch {
+ errors.push(`${location}.path does not exist: ${sample.path}`);
+ continue;
+ }
+
+ try {
+ await access(path.join(sampleDirectory, 'README.md'));
+ } catch {
+ errors.push(`${location}.path must contain README.md: ${sample.path}`);
+ }
+}
+
+if (errors.length > 0) {
+ console.error('Sample catalog validation failed:\n');
+ errors.forEach(error => console.error(` - ${error}`));
+ process.exit(1);
+}
+
+console.log(`Validated ${catalog.samples.length} samples across ${catalog.tracks.length} tracks.`);