@cratis/pi 0.0.1

package/README.md

@@ -0,0 +1,43 @@
+<!--
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE in this package for full license information.
+-->
+
+# @cratis/pi
+
+Passive AI skills for the Cratis ecosystem: the whole public skill set the
+Cratis marketplace installs deliver, wrapped as a Pi npm package. Fundamentals,
+Chronicle, Arc, Components, specifications, reviews, and more arrive as
+passive markdown skills — no hooks, no executable code, no MCP server.
+
+This package was previously published as `@cratis/ai-fundamentals`; that name
+is deprecated in favor of `@cratis/pi`.
+
+## Install
+
+Install globally:
+
+```bash
+pi install npm:@cratis/pi
+```
+
+Install it for one trusted project:
+
+```bash
+pi install -l npm:@cratis/pi
+```
+
+Try it for one Pi run without changing settings:
+
+```bash
+pi -e npm:@cratis/pi
+```
+
+## Update or remove
+
+Update to the latest published release with `pi install npm:@cratis/pi`.
+Remove the package with `pi remove npm:@cratis/pi`.
+
+## Status
+
+This is a supported stable release. Review skill instructions before use.

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@cratis/pi",
+  "version": "0.0.1",
+  "description": "The whole public Cratis AI skill set for building event-sourced and CQRS applications, delivered as a passive Pi package",
+  "private": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Cratis/AI"
+  },
+  "homepage": "https://cratis.io/ai",
+  "files": [
+    "skills"
+  ],
+  "keywords": [
+    "pi-package",
+    "cratis"
+  ],
+  "pi": {
+    "skills": [
+      "./skills"
+    ]
+  }
+}

package/skills/cratis-application-react-specifications/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.

package/skills/cratis-application-react-specifications/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: cratis-application-react-specifications
+description: Write specifications for the React and TypeScript surface of a Cratis application slice — view models, helpers, command orchestration, and narrow component behavior — using Vitest with Mocha-style describe/it, Sinon, and the Chai should interface. Use when adding or changing frontend behavior in an application that consumes Cratis. Do not use for backend scenarios or for specifications inside a Cratis framework package.
+license: MIT
+---
+
+# Cratis application React specifications
+
+Frontend specifications are specifications, not tests. The `for_ / when_ / and_`
+shape is deliberately the same BDD language as the backend, so one subject, one
+context, clear setup, and small assertions read as sentences.
+
+This is the **application** frontend peer of the backend slice specification
+skill. Specifications for a Cratis framework package (`@cratis/*`) follow that
+repository's own TypeScript specification conventions instead.
+
+## Stack
+
+- **Vitest** for the runner, with Mocha-style `describe` / `beforeEach` / `it`.
+- **Sinon** for stubs and fakes (`sinon.stub()`, `sinon.createStubInstance()`).
+- **Chai** with the **`.should` fluent interface** — never `expect()`.
+  `result.should.equal(expected)` reads as a sentence.
+
+## Placement and naming
+
+Specifications live next to the unit they specify, in snake_case so the path
+reads as a scenario sentence:
+
+```
+<Slice>/
+    <Subject>.ts
+    for_<Subject>/
+        when_<context>/
+            and_<extra_context>.ts
+```
+
+| Shape | Use for |
+| --- | --- |
+| `for_<Subject>/when_<context>/and_<extra>.ts` | the default — view models, branching helpers, component specs |
+| `for_<Subject>/when_<context>.ts` | a tiny pure helper with no useful extra context |
+
+`describe('when ...')` names the scenario, not the class. `it('should ...')`
+uses spaces, not underscores, and asserts one observable outcome. Do not add
+`.test.ts` or `.spec.ts` files unless the project's configuration changes
+deliberately.
+
+## What to specify
+
+Behavior that can regress without TypeScript catching it:
+
+- **View models** — the primary target. State transitions, computed getters,
+  filtering, sorting, selection, wizard steps, validation state, and
+  command-value derivation.
+- **Command orchestration outside a command dialog** — the unauthorized,
+  invalid, exception, and success branches.
+- **Pure helpers** — parsing, formatting, grouping, boundary cases.
+- **Component rendering** only when the markup, a disabled state, or wrapper
+  behavior is genuinely the point.
+
+Do **not** specify generated Cratis proxies, PrimeReact or framework internals,
+CSS pixel-perfection, snapshots, or trivial presentational pass-throughs.
+
+## View-model specification — the default shape
+
+A view model is a plain class: constructible directly, with no React hooks, no
+direct `window`, `localStorage`, timer, or network access (inject the Cratis
+abstraction instead), and derived values as getters.
+
+```ts
+import { describe, beforeEach, it } from 'vitest';
+import { CandidatesViewModel } from '../../CandidatesViewModel';
+
+describe('when filtering by search text', () => {
+    let viewModel: CandidatesViewModel;
+
+    beforeEach(() => {
+        viewModel = new CandidatesViewModel();
+        viewModel.setSearch('senior');
+    });
+
+    it('should keep only matching candidates', () =>
+        viewModel.filteredItems.should.have.lengthOf(1));
+});
+```
+
+`beforeEach` does the arrange and act once for the context; each `it` asserts
+one outcome. Pass small typed fakes or `sinon.stub()` instances for
+dependencies, and do not build a shared harness until a second specification
+actually reuses it.
+
+A view model that cannot be constructed without React is doing too much or
+depending on the wrong abstraction — that is a design signal, not a testing
+problem.
+
+## Command-result branches
+
+When a command runs outside a command dialog, each granular flag is a branch
+worth specifying: `isAuthorized`, `isValid` with its `validationResults`,
+`hasExceptions`, and the success path. Stub the command and return a result
+object per branch rather than reaching for the network.
+
+## Component specification — when rendering is the point
+
+The environment is `node`. For behavior that does not need browser events,
+render server-side markup and mock only the external component boundary:
+
+```ts
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, beforeEach, it, vi } from 'vitest';
+
+vi.mock('primereact/dialog', () => ({
+    Dialog: (props: { footer?: React.ReactNode; children?: React.ReactNode }) =>
+        React.createElement('div', null, props.footer, props.children),
+}));
+
+describe('when rendered while busy', () => {
+    let html: string;
+
+    beforeEach(() => {
+        html = renderToStaticMarkup(React.createElement(MyDialog, { isBusy: true }));
+    });
+
+    it('should disable the confirm button', () => html.should.include('disabled'));
+});
+```
+
+Prefer typed mock props over `any`. Add jsdom or Testing Library only when the
+behavior truly requires DOM events — do not make it the default. Avoid
+snapshots; they hide behavior and make refactors noisy.
+
+Cratis Components mount inside `CratisComponentsProvider`, so a specification
+that renders one for real must provide it, and jsdom needs a `ResizeObserver`
+stub for the table and split-pane components.
+
+## Async and time
+
+Use `vi.useFakeTimers()` for time-dependent behavior and restore with
+`vi.useRealTimers()` in `afterEach`. Never depend on the real current date,
+random values, the network, or browser storage. For suspense-query
+specifications, clear the Arc query caches in teardown with
+`clearSuspenseQueryCache()` and `clearSuspenseObservableQueryCache()` from
+`@cratis/arc.react/queries`.
+
+## Stories are not specifications
+
+Storybook covers visual states, documentation, and manual verification; Vitest
+covers behavior. A component with non-trivial logic usually needs both. A story
+file is colocated with its component, uses
+`satisfies Meta<typeof Component>` rather than a type annotation, and carries
+`tags: ['autodocs']`. Write stories for reusable components — shared primitives
+and slice-internal components reused across slices — not for live slice pages
+wired to Arc query and command hooks; exercise those in the running app.
+
+An interaction (`play:`) function belongs on stateful components only, and it is
+documentation and QA rather than the enforced gate. The enforced behavioral gate
+is the Vitest specification.
+
+## The engineering bar these specifications serve
+
+- No placeholder or dead UI ships for behavior the code actually implements.
+- Components stay small and single-responsibility; a `// Section` comment inside
+  a component means that section is its own component.
+- State logic lives in a view model or a tested state module, not in the
+  component — extract as soon as there are three or more `useState` calls, any
+  state-synchronizing `useEffect`, or derived values.
+- Reuse an existing Cratis Components wrapper or shared primitive before adding
+  a new component.
+- `unknown` or a real type, never `any`.
+- After editing a `.tsx`, read past its final closing brace to confirm no stale
+  return block or unreachable code remains.
+
+## Gate
+
+Run the project's frontend test gate (typically `yarn test`) plus lint and the
+TypeScript build. Specifications complement lint and build; they do not replace
+them.
+
+## Verify
+
+- Files sit in `for_<Subject>/when_<context>/` beside the unit, in snake_case.
+- `describe` names the scenario; `it` descriptions start with "should" and use
+  spaces.
+- Assertions use the Chai `.should` interface, never `expect()`.
+- Each `it` asserts one observable outcome.
+- View models are constructed directly, with stubs for dependencies and no
+  React involved.
+- No specification covers a generated proxy, a framework internal, or a
+  snapshot.
+- Fake timers are restored in `afterEach` and query caches are cleared for
+  suspense specifications.
+- Lint, the frontend test gate, and the TypeScript build all pass.

package/skills/cratis-application-slice-specifications/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.

package/skills/cratis-application-slice-specifications/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: cratis-application-slice-specifications
+description: Specify the backend behavior of an event-sourced Cratis application slice with the in-process scenario family — CommandScenario, EventScenario, ReadModelScenario and ReactorScenario — including what to cover for each slice type and where the specification files live. Use when adding or changing backend behavior in an application built on Cratis. Do not use for framework library specifications and do not use for frontend behavior.
+license: MIT
+---
+
+# Cratis application slice specifications
+
+A slice is specified from the outside, through the pipeline it actually runs on.
+The scenario family exercises the real Arc and Chronicle code paths in-process —
+no HTTP, no fixture, no server — so a specification says what the slice does
+rather than what its classes do.
+
+This skill decides **which scenario** and **what to cover**. The C# mechanics
+(`Establish`/`Because`, substitutes, contexts) live in
+`cratis-specifications-csharp`.
+
+## Verified product sources
+
+| Package | Version | Purpose |
+| --- | --- | --- |
+| `Cratis.Arc.Testing` | `22.10.4` | `CommandScenario<TCommand>` and the `CommandResult` assertions |
+| `Cratis.Arc.Chronicle.Testing` | `22.10.4` | `Given`, `EventLog`, `AppendedEvents` and the appended-event assertions on a command scenario |
+| `Cratis.Chronicle.Testing` | `16.45.2` | `EventScenario`, `ReadModelScenario<T>`, `ReactorScenario<T>` |
+| `Cratis.Specifications.XUnit` | `4.x` | The `Specification` base and the `ShouldXxx` assertions |
+
+`Cratis.Testing` is the meta-package that brings `Cratis.Arc.Testing` and
+`Cratis.Arc.Chronicle.Testing` together. Reverify against the owning product
+repository before claiming support for another version.
+
+## Route near misses
+
+- The repository builds a Cratis **library** rather than an application: use
+  `cratis-specifications-csharp` and stay on the plain `Specification` base.
+- React, TypeScript, or a view model: use
+  `cratis-application-react-specifications`.
+- The subject is append semantics or a constraint on its own: use
+  `cratis-chronicle-event-specifications`.
+- The subject is a projection or reducer on its own: use
+  `cratis-chronicle-read-model-specifications`.
+- The question is what the slice *should do*: settle the behavior first. A
+  specification records a decision; it does not make one.
+
+## Step 1 — Place the files
+
+Specifications live **in the slice folder**, beside the `.cs` they specify, each
+file wrapped in `#if DEBUG … #endif` so specification code compiles only in
+Debug.
+
+```
+<Feature>/<Slice>/
+├── <Slice>.cs
+└── when_<verb_phrase>/
+    ├── and_<happy_scenario>.cs
+    └── and_<failure_scenario>.cs
+```
+
+- Folder: `when_<verb_phrase>` — `when_registering`.
+- File: `and_<condition>.cs` — `and_name_is_unique.cs`, `and_name_already_exists.cs`.
+- Method: `should_<expected_result>`.
+
+A behavior covering several subjects groups under
+`<Slice>/for_<Subject>/when_<behavior>/`.
+
+## Step 2 — Pick the scenario by slice type
+
+| Slice type | Scenario | Skill |
+| --- | --- | --- |
+| State Change — a command appends events | `CommandScenario<TCommand>` | this one |
+| Append semantics, a constraint | `EventScenario` | `cratis-chronicle-event-specifications` |
+| State View — a projection or reducer | `ReadModelScenario<TReadModel>` | `cratis-chronicle-read-model-specifications` |
+| Automation or Translation — a reactor | `ReactorScenario<TReactor>` | `cratis-specifications-csharp` |
+| A host, transport, or real-infrastructure boundary | Out-of-process integration | `cratis-specifications-csharp` |
+
+## Step 3 — Cover every outcome of a State Change slice
+
+One specification class for **each** of:
+
+1. **The happy path** — the command succeeds and the expected event is appended.
+2. **Each validation failure** — one `and_` class per `CommandValidator` or
+   `ConceptValidator` rule.
+3. **Each business-rule rejection** — one `and_` class per condition in
+   `Handle()` that inspects a read model.
+4. **Each constraint violation** — one class per constraint, written with
+   `EventScenario`, because a constraint is enforced at the append and not by
+   the command.
+
+## Step 4 — `CommandScenario<TCommand>`
+
+It runs authorization, the validators, `Provide()` and `Handle()` in-process and
+exposes what was appended.
+
+```csharp
+#if DEBUG
+namespace MyApp.Projects.Registration.when_registering;
+
+public class and_name_is_unique : Specification
+{
+    readonly CommandScenario<RegisterProject> _scenario = new();
+    readonly ProjectId _id = ProjectId.New();
+    CommandResult _result;
+
+    async Task Because() => _result = await _scenario.Execute(new RegisterProject(_id, "My Project"));
+
+    [Fact] void should_succeed() => _result.ShouldBeSuccessful();
+    [Fact] async Task should_have_appended_the_registered_event() =>
+        await _scenario.ShouldHaveAppendedEvent<RegisterProject, ProjectRegistered>(_id, e => e.Name == "My Project");
+}
+#endif
+```
+
+The scenario's own surface is `Services`, `Context`, `Execute(command)` and
+`Validate(command)` — `Validate` runs the filters without the handler.
+Everything else is an extension method.
+
+## Step 5 — Seed prior state through `Given`
+
+With `Cratis.Arc.Chronicle.Testing` referenced, a command scenario has a
+Chronicle-backed `Given` builder, plus `EventScenario`, `EventLog`,
+`EventSequence` and `AppendedEvents`.
+
+```csharp
+// Seed the events the world already contains. A read model the command injects
+// for this event source is materialized from them by its own projection or
+// reducer — no read-model type is named.
+_scenario.Given.ForEventSource(_cartId).Events(new ItemAddedToCart(itemId));
+
+// Or pin a specific read-model value directly, when the events are beside the point.
+_scenario.Given.ForEventSource(_cartId).ReadModel(new CartSummary { ItemCount = 3 });
+```
+
+Prefer seeding **events**: it exercises the projection that production relies on,
+so a specification cannot pass against a read-model shape the projection never
+produces. Pin an instance only when the events would be noise.
+
+Both builder methods return `void`; there is nothing to await.
+
+Validator and `Provide()` dependencies are registered in `_scenario.Services`;
+the concrete validator itself is discovered automatically.
+
+## Step 6 — Assert twice on every unhappy path
+
+```csharp
+[Fact] void should_not_succeed() => _result.ShouldNotBeSuccessful();
+[Fact] void should_have_validation_errors() => _result.ShouldHaveValidationErrors();
+```
+
+`ShouldNotBeSuccessful()` alone cannot distinguish a validation rejection from an
+unhandled exception, so both facts are required. **Never assert on a message
+string** — it is presentation text.
+
+`CommandResult` assertions, from `Cratis.Arc.Testing.Commands`, throwing
+`CommandResultAssertionException`:
+
+| Assertion | Says |
+| --- | --- |
+| `ShouldBeSuccessful()` / `ShouldNotBeSuccessful()` | Authorized, valid, no exceptions — or not |
+| `ShouldBeValid()` | Validation only; it checks neither authorization nor exceptions |
+| `ShouldHaveValidationErrors()` | At least one validation error |
+| `ShouldHaveValidationErrorFor(message)` | A validation error with that **message** |
+| `ShouldHaveValidationErrorBecauseOf(reason)` | A validation error with that `ValidationResultReason` |
+| `ShouldBeAuthorized()` / `ShouldNotBeAuthorized()` | The authorization outcome |
+| `ShouldHaveExceptions()` / `ShouldNotHaveExceptions()` | Whether the handler threw |
+| `ShouldHaveConstraintViolationFor(name)` | A constraint violation surfaced on the command result |
+
+`ShouldHaveValidationErrorBecauseOf(reason)` is the message-free way to say
+*which kind* of rejection happened — `ValidationResultReason.ConstraintViolation`,
+`ConcurrencyViolation`, `ValidatorFailed`, `Rule`. Prefer it over
+`ShouldHaveValidationErrorFor(message)`, which pins presentation text.
+
+Authorization failures are different in kind: an unauthorized result carries
+**no** validation errors, so assert `ShouldNotBeAuthorized()`. Adding an
+authorization attribute to an existing command therefore breaks both its
+happy-path and its validation-failure specifications — switch the assertions
+rather than patching around them.
+
+## Step 7 — Assert what was appended
+
+The appended-event assertions come from `Cratis.Arc.Chronicle.Testing` and are
+keyed by **command and event type**. They return `Task`, so the fact is
+`async Task`, and they throw `EventSequenceAssertionException`.
+
+- `ShouldHaveAppendedEvent<TCommand, TEvent>(eventSourceId)`
+- `ShouldHaveAppendedEvent<TCommand, TEvent>(eventSourceId, Func<TEvent, bool> predicate)`
+- `ShouldHaveTailSequenceNumber<TCommand>(sequenceNumber)`
+
+⚠️ On a command scenario the second argument is a **predicate**
+(`Func<TEvent, bool>`), not an assertion callback. The `Action<TEvent>` validator
+overloads exist only on the `IEventSequence` extensions in
+`Cratis.Chronicle.Testing`, which is a different receiver.
+
+Sequence numbers are **zero-based**: the first event is `0`, and the tail after a
+single append is `0`, never `1`.
+
+## What breaks
+
+- **A specification passes alone and fails in the suite.** A hard-coded value
+  collided with another specification's uniqueness claim. Use a per-specification
+  value — a fresh `Guid`, or `Guid.NewGuid().ToString("N")[..9]`. Adding
+  `[Collection(…)]` is the wrong fix here.
+- **`Given` does not resolve.** `Cratis.Arc.Chronicle.Testing` (or the
+  `Cratis.Testing` meta-package) is not referenced. It is an extension member,
+  not part of `CommandScenario` itself.
+- **A DCB rejection specification is green for the wrong reason.** The read model
+  was never seeded, so the handler saw a default or `null` instance and rejected
+  on that instead of on the rule. Seed, then confirm the specification fails when
+  the seeding is removed.
+- **The command scenario reports success but nothing was appended.** The
+  assertion is on `CommandResult` only; add a
+  `ShouldHaveAppendedEvent<TCommand, TEvent>` fact.
+- **Injected-validator branches flip with test ordering.** The command-scenario
+  pipeline can cache enough state that a validator branch depends on execution
+  order under parallel xUnit runs. Use `CommandScenario` for the valid path, test
+  rejected state variants by instantiating the validator directly, and only then
+  put that command's specifications in a small `[Collection]`.
+
+## How it is proven
+
+`dotnet build -c Debug` — it compiles the `#if DEBUG` specification code — then
+`dotnet test`, both clean, with a specification for the happy path and one per
+rejection. Before trusting a rejection specification green, remove the condition
+that causes the rejection once and confirm it goes red.

package/skills/cratis-arc-authentication-authorization-and-identity/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.