@cratis/showrunner.usher 0.0.0-bootstrap.0

package/Listing/Listing.ts

@@ -0,0 +1,271 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+// **DO NOT EDIT** - This file is an automatically generated file.
+// @generated by Cratis. Source: Cratis.Showrunner.Usher.Listing.ReportedIssue, Cratis.Showrunner.Usher.Listing.ReportedIssue. Time: 2026-10-26T20:48:58.8871950Z. Hash: E94FF103309F27881C5673E44ECED7CEB12718F227E91804FAB86F9B879A7C86
+import { ChangeSet, ObservableQueryFor, Paging, QueryResultWithState, Sorting, SortingActions, SortingActionsForObservableQuery } from '@cratis/arc/queries';
+import { ObservableQueryWhen, SetPage, SetPageSize, SetSorting, useChangeStream, useObservableQuery, useObservableQueryWithPaging, useSuspenseObservableQuery, useSuspenseObservableQueryWithPaging } from '@cratis/arc.react/queries';
+import { SliceLocation as ArcSliceLocation, ParameterDescriptor } from '@cratis/arc/reflection';
+import { Guid, field } from '@cratis/fundamentals';
+import { IssueKind } from '../Issues/IssueKind';
+import { IssueState } from '../Issues/IssueState';
+import { UserIdentity } from '../Identity/UserIdentity';
+import { WorkItem } from '../Contracts/WorkItems/WorkItem';
+
+class MyIssuesSortBy {
+    private _fixedInVersion: SortingActionsForObservableQuery<ReportedIssue[]>;
+    private _id: SortingActionsForObservableQuery<ReportedIssue[]>;
+    private _kind: SortingActionsForObservableQuery<ReportedIssue[]>;
+    private _knownIssueTitle: SortingActionsForObservableQuery<ReportedIssue[]>;
+    private _lastActivityAt: SortingActionsForObservableQuery<ReportedIssue[]>;
+    private _openQuestions: SortingActionsForObservableQuery<ReportedIssue[]>;
+    private _reportedAt: SortingActionsForObservableQuery<ReportedIssue[]>;
+    private _reportedBy: SortingActionsForObservableQuery<ReportedIssue[]>;
+    private _state: SortingActionsForObservableQuery<ReportedIssue[]>;
+    private _title: SortingActionsForObservableQuery<ReportedIssue[]>;
+    private _waitingOnReporter: SortingActionsForObservableQuery<ReportedIssue[]>;
+    private _workItem: SortingActionsForObservableQuery<ReportedIssue[]>;
+
+    constructor(readonly query: MyIssues) {
+        this._fixedInVersion = new SortingActionsForObservableQuery<ReportedIssue[]>('fixedInVersion', query);
+        this._id = new SortingActionsForObservableQuery<ReportedIssue[]>('id', query);
+        this._kind = new SortingActionsForObservableQuery<ReportedIssue[]>('kind', query);
+        this._knownIssueTitle = new SortingActionsForObservableQuery<ReportedIssue[]>('knownIssueTitle', query);
+        this._lastActivityAt = new SortingActionsForObservableQuery<ReportedIssue[]>('lastActivityAt', query);
+        this._openQuestions = new SortingActionsForObservableQuery<ReportedIssue[]>('openQuestions', query);
+        this._reportedAt = new SortingActionsForObservableQuery<ReportedIssue[]>('reportedAt', query);
+        this._reportedBy = new SortingActionsForObservableQuery<ReportedIssue[]>('reportedBy', query);
+        this._state = new SortingActionsForObservableQuery<ReportedIssue[]>('state', query);
+        this._title = new SortingActionsForObservableQuery<ReportedIssue[]>('title', query);
+        this._waitingOnReporter = new SortingActionsForObservableQuery<ReportedIssue[]>('waitingOnReporter', query);
+        this._workItem = new SortingActionsForObservableQuery<ReportedIssue[]>('workItem', query);
+    }
+
+    get fixedInVersion(): SortingActionsForObservableQuery<ReportedIssue[]> {
+        return this._fixedInVersion;
+    }
+    get id(): SortingActionsForObservableQuery<ReportedIssue[]> {
+        return this._id;
+    }
+    get kind(): SortingActionsForObservableQuery<ReportedIssue[]> {
+        return this._kind;
+    }
+    get knownIssueTitle(): SortingActionsForObservableQuery<ReportedIssue[]> {
+        return this._knownIssueTitle;
+    }
+    get lastActivityAt(): SortingActionsForObservableQuery<ReportedIssue[]> {
+        return this._lastActivityAt;
+    }
+    get openQuestions(): SortingActionsForObservableQuery<ReportedIssue[]> {
+        return this._openQuestions;
+    }
+    get reportedAt(): SortingActionsForObservableQuery<ReportedIssue[]> {
+        return this._reportedAt;
+    }
+    get reportedBy(): SortingActionsForObservableQuery<ReportedIssue[]> {
+        return this._reportedBy;
+    }
+    get state(): SortingActionsForObservableQuery<ReportedIssue[]> {
+        return this._state;
+    }
+    get title(): SortingActionsForObservableQuery<ReportedIssue[]> {
+        return this._title;
+    }
+    get waitingOnReporter(): SortingActionsForObservableQuery<ReportedIssue[]> {
+        return this._waitingOnReporter;
+    }
+    get workItem(): SortingActionsForObservableQuery<ReportedIssue[]> {
+        return this._workItem;
+    }
+}
+
+class MyIssuesSortByWithoutQuery {
+    private _fixedInVersion: SortingActions  = new SortingActions('fixedInVersion');
+    private _id: SortingActions  = new SortingActions('id');
+    private _kind: SortingActions  = new SortingActions('kind');
+    private _knownIssueTitle: SortingActions  = new SortingActions('knownIssueTitle');
+    private _lastActivityAt: SortingActions  = new SortingActions('lastActivityAt');
+    private _openQuestions: SortingActions  = new SortingActions('openQuestions');
+    private _reportedAt: SortingActions  = new SortingActions('reportedAt');
+    private _reportedBy: SortingActions  = new SortingActions('reportedBy');
+    private _state: SortingActions  = new SortingActions('state');
+    private _title: SortingActions  = new SortingActions('title');
+    private _waitingOnReporter: SortingActions  = new SortingActions('waitingOnReporter');
+    private _workItem: SortingActions  = new SortingActions('workItem');
+
+    get fixedInVersion(): SortingActions {
+        return this._fixedInVersion;
+    }
+    get id(): SortingActions {
+        return this._id;
+    }
+    get kind(): SortingActions {
+        return this._kind;
+    }
+    get knownIssueTitle(): SortingActions {
+        return this._knownIssueTitle;
+    }
+    get lastActivityAt(): SortingActions {
+        return this._lastActivityAt;
+    }
+    get openQuestions(): SortingActions {
+        return this._openQuestions;
+    }
+    get reportedAt(): SortingActions {
+        return this._reportedAt;
+    }
+    get reportedBy(): SortingActions {
+        return this._reportedBy;
+    }
+    get state(): SortingActions {
+        return this._state;
+    }
+    get title(): SortingActions {
+        return this._title;
+    }
+    get waitingOnReporter(): SortingActions {
+        return this._waitingOnReporter;
+    }
+    get workItem(): SortingActions {
+        return this._workItem;
+    }
+}
+
+
+/**
+ * Observes the issues the signed-in reporter reported, in the current tenant, most recent activity first.
+ */
+export class MyIssues extends ObservableQueryFor<ReportedIssue[]> {
+    static readonly sliceLocation: ArcSliceLocation = new ArcSliceLocation('', '', 'Listing');
+    readonly route: string = '/api/listing/my-issues';
+    readonly queryName: string = 'Cratis.Showrunner.Usher.Listing.ReportedIssue.MyIssues';
+    readonly treatWarningsAsErrors: boolean = false;
+    readonly roles: string[] = [];
+    readonly defaultValue: ReportedIssue[] = [];
+    private readonly _sortBy: MyIssuesSortBy;
+    private static readonly _sortBy: MyIssuesSortByWithoutQuery = new MyIssuesSortByWithoutQuery();
+
+    constructor() {
+        super(ReportedIssue, true);
+        this._sortBy = new MyIssuesSortBy(this);
+    }
+
+    get requiredRequestParameters(): string[] {
+        return [
+        ];
+    }
+
+    readonly parameterDescriptors: ParameterDescriptor[] = [
+    ];
+
+
+    get sortBy(): MyIssuesSortBy {
+        return this._sortBy;
+    }
+
+    static get sortBy(): MyIssuesSortByWithoutQuery {
+        return this._sortBy;
+    }
+
+    static use(sorting?: Sorting): [QueryResultWithState<ReportedIssue[]>, SetSorting] {
+        return useObservableQuery<ReportedIssue[], MyIssues>(MyIssues, undefined, sorting);
+    }
+
+    static useWithPaging(pageSize: number, sorting?: Sorting): [QueryResultWithState<ReportedIssue[]>, SetSorting, SetPage, SetPageSize] {
+        return useObservableQueryWithPaging<ReportedIssue[], MyIssues>(MyIssues, new Paging(0, pageSize), undefined, sorting);
+    }
+
+    static useSuspense(sorting?: Sorting): [QueryResultWithState<ReportedIssue[]>, SetSorting] {
+        return useSuspenseObservableQuery<ReportedIssue[], MyIssues>(MyIssues, undefined, sorting);
+    }
+
+    static useSuspenseWithPaging(pageSize: number, sorting?: Sorting): [QueryResultWithState<ReportedIssue[]>, SetSorting, SetPage, SetPageSize] {
+        return useSuspenseObservableQueryWithPaging<ReportedIssue[], MyIssues>(MyIssues, new Paging(0, pageSize), undefined, sorting);
+    }
+
+    static useChangeStream(getKey?: (item: ReportedIssue) => unknown, sorting?: Sorting): ChangeSet<ReportedIssue> {
+        return useChangeStream<ReportedIssue, MyIssues>(MyIssues, undefined, getKey, sorting);
+    }
+
+    static when(condition: boolean): ObservableQueryWhen<MyIssues, ReportedIssue[]> {
+        return new ObservableQueryWhen<MyIssues, ReportedIssue[]>(MyIssues, condition);
+    }
+}
+
+/**
+ * One of the reporter's issues, as the list of their issues shows it.
+ */
+export class ReportedIssue {
+
+    /**
+     * The issue.
+     */
+    @field(Guid)
+    id!: Guid;
+
+    /**
+     * How the issue was reported.
+     */
+    @field(Number)
+    kind!: IssueKind;
+
+    /**
+     * The summary of a problem described by hand, or the message of a reported error.
+     */
+    @field(String)
+    title!: string;
+
+    /**
+     * The state the issue is in.
+     */
+    @field(Number)
+    state!: IssueState;
+
+    /**
+     * When the issue was reported.
+     */
+    @field(Date)
+    reportedAt!: Date;
+
+    /**
+     * When anything last happened on the issue.
+     */
+    @field(Date)
+    lastActivityAt!: Date;
+
+    /**
+     * Whether support asked something the reporter has not answered.
+     */
+    @field(Boolean)
+    waitingOnReporter!: boolean;
+
+    /**
+     * The title of the known issue it is linked to; {@link NotSet} when it is not.
+     */
+    @field(String)
+    knownIssueTitle!: string;
+
+    /**
+     * The work item it is linked to; {@link WorkItem} when it is not.
+     */
+    @field(WorkItem)
+    workItem!: WorkItem;
+
+    /**
+     * The version that has the fix; {@link NotSet} until a release ships it.
+     */
+    @field(String)
+    fixedInVersion!: string;
+
+    /**
+     * Who reported the issue, at their identity provider.
+     */
+    @field(UserIdentity)
+    reportedBy!: UserIdentity;
+
+    /**
+     * The questions support asked that the reporter has not answered.
+     */
+    @field(Guid, true)
+    openQuestions!: Guid[];
+}

package/Listing/index.ts

@@ -0,0 +1,4 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './Listing';

package/README.md

@@ -0,0 +1,59 @@
+# Showrunner
+
+> Showrunner is a set of ready-made product parts for applications built on [Cratis](https://www.cratis.io) — drop-in backend and frontend packages, built as Arc and Chronicle vertical slices.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Build](https://github.com/Cratis/Showrunner/actions/workflows/build.yml/badge.svg)](https://github.com/Cratis/Showrunner/actions/workflows/build.yml)
+[![Publish](https://github.com/Cratis/Showrunner/actions/workflows/publish.yml/badge.svg)](https://github.com/Cratis/Showrunner/actions/workflows/publish.yml)
+[![Discord](https://img.shields.io/discord/1182595891576717413?label=Discord&logo=discord&logoColor=white)](https://discord.gg/kt4AMpV8WV)
+
+## Usher
+
+**Usher** is the support part: it lets the users of an application report issues and hold support conversations with the people running it. It is a library an application hosts, not a service of its own — the backend package adds Usher's commands, queries and events to the host's Arc application and Chronicle event store, and the frontend packages give the host's React UI the generated proxies and components to drive them.
+
+Usher is in its earliest stage: the packages are scaffolded and published, but carry no behavior yet. See [Documentation](./Documentation/index.md).
+
+## Packages
+
+| Package | Registry | What it is |
+| --- | --- | --- |
+| `Cratis.Showrunner.Usher.Contracts` | NuGet | Usher's event contracts, for hosts that react to what Usher records |
+| `Cratis.Showrunner.Usher` | NuGet | Usher's backend — Arc commands and queries over Chronicle |
+| `@cratis/showrunner.usher` | npm | The generated TypeScript proxies for Usher's commands and queries; no UI framework dependency |
+| `@cratis/showrunner.usher.react` | npm | React components for Usher, built on `@cratis/arc.react` and `@cratis/components` |
+
+## Building
+
+Prerequisites: the .NET SDK from [`global.json`](./global.json) (10.0.400 or later) and Node.js 20 or later with Corepack enabled (`corepack enable`); Yarn itself is checked in under `.yarn/releases`.
+
+```shell
+# 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 end-to-end specifications in [`Integration`](./Integration) run Usher and a desk against a real Chronicle kernel in a container, so `dotnet test Showrunner.slnx` needs Docker. Set `USHER_CHRONICLE_IMAGE` to run them against another kernel image, and `USHER_INTEGRATION_LOG` to a file path to keep the application's log.
+
+## 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 all four packages under one semantic version through [`cratis/release-action`](https://github.com/Cratis/release-action) — NuGet packages through NuGet trusted publishing and npm packages through npm trusted publishing with provenance. The packages are built and packed in jobs without publishing rights; separate jobs that run no build or install script hold the short-lived OIDC token and only push what was packed.
+
+## Part of the Cratis ecosystem
+
+Showrunner is a [Cratis](https://www.cratis.io) project, built on event sourcing with [Chronicle](https://github.com/Cratis/Chronicle) and CQRS with [Arc](https://github.com/Cratis/Arc), with frontends on [`@cratis/components`](https://github.com/Cratis/Components). Join the community on [Discord](https://discord.gg/kt4AMpV8WV).
+
+## License
+
+Showrunner is licensed under the [MIT License](LICENSE) and free to use.

package/Reporting/ReportError/ReportError.ts

@@ -0,0 +1,254 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+// **DO NOT EDIT** - This file is an automatically generated file.
+// @generated by Cratis. Source: Cratis.Showrunner.Usher.Reporting.ReportError.ReportError. Time: 2026-10-26T21:13:51.1172240Z. Hash: DA734075048BC8A92F219C6B3D979A212428CC1933A9599F3B8E52AE6981D25D
+import { Command, CommandValidator } from '@cratis/arc/commands';
+import { ClearCommandValues, SetCommandValues, useCommand } from '@cratis/arc.react/commands';
+import { SliceLocation as ArcSliceLocation, PropertyDescriptor } from '@cratis/arc/reflection';
+import { AccessDuration } from '../../Access/AccessDuration';
+import { SliceLocation } from '../../Contracts/Reporting/SliceLocation';
+import { StackFrame } from '../../Contracts/Reporting/StackFrame';
+import { Guid } from '@cratis/fundamentals';
+
+/**
+ * The reporter reports an error they hit, optionally saying what they were doing. They can let support know who they are and let support sign in as them for a while; granting access always shares who they are.
+ */
+export interface IReportError {
+
+    /**
+     * How long support may sign in as the reporter, when access is granted.
+     */
+    accessDuration?: AccessDuration;
+
+    /**
+     * The version of the application the reporter runs.
+     */
+    applicationVersion?: string;
+
+    /**
+     * The correlation ids of the failing command or query and those run just before it; may be empty.
+     */
+    correlationIds?: Guid[];
+
+    /**
+     * What the reporter was doing; empty when they wrote nothing.
+     */
+    details?: string;
+
+    /**
+     * The message of the error.
+     */
+    errorMessage?: string;
+
+    /**
+     * The type of the error.
+     */
+    errorType?: string;
+
+    /**
+     * Whether to let support sign in as the reporter.
+     */
+    grantAccess?: boolean;
+
+    /**
+     * The id of the new issue, chosen by the caller so a retried report does not open a second issue.
+     */
+    issueId?: Guid;
+
+    /**
+     * Where in the application the error happened.
+     */
+    location?: SliceLocation;
+
+    /**
+     * Whether to let support know who the reporter is.
+     */
+    shareIdentity?: boolean;
+
+    /**
+     * The stack trace of the error, top frame first; empty when there is none.
+     */
+    stackFrames?: StackFrame[];
+}
+
+export class ReportErrorValidator extends CommandValidator<IReportError> {
+    constructor() {
+        super();
+        this.ruleFor(c => c.details).maxLength(4000).withMessage('Keep what you were doing within 4000 characters.');
+        this.ruleFor(c => c.errorMessage).notEmpty().withMessage('The error to report has no message.');
+        this.ruleFor(c => c.errorMessage).maxLength(2000).withMessage('The error message can be at most 2000 characters.');
+        this.ruleFor(c => c.errorType).maxLength(500).withMessage('The error type can be at most 500 characters.');
+    }
+}
+
+/**
+ * The reporter reports an error they hit, optionally saying what they were doing. They can let support know who they are and let support sign in as them for a while; granting access always shares who they are.
+ */
+export class ReportError extends Command<IReportError> implements IReportError {
+    static readonly sliceLocation: ArcSliceLocation = new ArcSliceLocation('', 'Reporting', 'ReportError');
+    readonly route: string = '/api/reporting/report-error';
+    readonly validation: CommandValidator = new ReportErrorValidator();
+    readonly treatWarningsAsErrors: boolean = false;
+    readonly roles: string[] = [];
+    readonly propertyDescriptors: PropertyDescriptor[] = [
+        new PropertyDescriptor('accessDuration', Number, false),
+        new PropertyDescriptor('applicationVersion', String, false),
+        new PropertyDescriptor('correlationIds', Guid, false),
+        new PropertyDescriptor('details', String, false),
+        new PropertyDescriptor('errorMessage', String, false),
+        new PropertyDescriptor('errorType', String, false),
+        new PropertyDescriptor('grantAccess', Boolean, false),
+        new PropertyDescriptor('issueId', Guid, false),
+        new PropertyDescriptor('location', SliceLocation, false),
+        new PropertyDescriptor('shareIdentity', Boolean, false),
+        new PropertyDescriptor('stackFrames', StackFrame, false),
+    ];
+
+    #accessDuration!: AccessDuration;
+    #applicationVersion!: string;
+    #correlationIds!: Guid[];
+    #details!: string;
+    #errorMessage!: string;
+    #errorType!: string;
+    #grantAccess!: boolean;
+    #issueId!: Guid;
+    #location!: SliceLocation;
+    #shareIdentity!: boolean;
+    #stackFrames!: StackFrame[];
+
+    constructor() {
+        super(Object, false);
+    }
+
+    get requestParameters(): string[] {
+        return [
+        ];
+    }
+
+    /**
+     * How long support may sign in as the reporter, when access is granted.
+     */
+    get accessDuration(): AccessDuration {
+        return this.#accessDuration;
+    }
+
+    set accessDuration(value: AccessDuration) {
+        this.#accessDuration = value;
+        this.propertyChanged('accessDuration');
+    }
+    /**
+     * The version of the application the reporter runs.
+     */
+    get applicationVersion(): string {
+        return this.#applicationVersion;
+    }
+
+    set applicationVersion(value: string) {
+        this.#applicationVersion = value;
+        this.propertyChanged('applicationVersion');
+    }
+    /**
+     * The correlation ids of the failing command or query and those run just before it; may be empty.
+     */
+    get correlationIds(): Guid[] {
+        return this.#correlationIds;
+    }
+
+    set correlationIds(value: Guid[]) {
+        this.#correlationIds = value;
+        this.propertyChanged('correlationIds');
+    }
+    /**
+     * What the reporter was doing; empty when they wrote nothing.
+     */
+    get details(): string {
+        return this.#details;
+    }
+
+    set details(value: string) {
+        this.#details = value;
+        this.propertyChanged('details');
+    }
+    /**
+     * The message of the error.
+     */
+    get errorMessage(): string {
+        return this.#errorMessage;
+    }
+
+    set errorMessage(value: string) {
+        this.#errorMessage = value;
+        this.propertyChanged('errorMessage');
+    }
+    /**
+     * The type of the error.
+     */
+    get errorType(): string {
+        return this.#errorType;
+    }
+
+    set errorType(value: string) {
+        this.#errorType = value;
+        this.propertyChanged('errorType');
+    }
+    /**
+     * Whether to let support sign in as the reporter.
+     */
+    get grantAccess(): boolean {
+        return this.#grantAccess;
+    }
+
+    set grantAccess(value: boolean) {
+        this.#grantAccess = value;
+        this.propertyChanged('grantAccess');
+    }
+    /**
+     * The id of the new issue, chosen by the caller so a retried report does not open a second issue.
+     */
+    get issueId(): Guid {
+        return this.#issueId;
+    }
+
+    set issueId(value: Guid) {
+        this.#issueId = value;
+        this.propertyChanged('issueId');
+    }
+    /**
+     * Where in the application the error happened.
+     */
+    get location(): SliceLocation {
+        return this.#location;
+    }
+
+    set location(value: SliceLocation) {
+        this.#location = value;
+        this.propertyChanged('location');
+    }
+    /**
+     * Whether to let support know who the reporter is.
+     */
+    get shareIdentity(): boolean {
+        return this.#shareIdentity;
+    }
+
+    set shareIdentity(value: boolean) {
+        this.#shareIdentity = value;
+        this.propertyChanged('shareIdentity');
+    }
+    /**
+     * The stack trace of the error, top frame first; empty when there is none.
+     */
+    get stackFrames(): StackFrame[] {
+        return this.#stackFrames;
+    }
+
+    set stackFrames(value: StackFrame[]) {
+        this.#stackFrames = value;
+        this.propertyChanged('stackFrames');
+    }
+
+    static use(initialValues?: IReportError): [ReportError, SetCommandValues<IReportError>, ClearCommandValues] {
+        return useCommand<ReportError, IReportError>(ReportError, initialValues);
+    }
+}

package/Reporting/ReportError/index.ts

@@ -0,0 +1,4 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './ReportError';