Add 'cratis render' as a root command for rendering a Screenplay solution

[woksin]

The CLI needs a way to render a Screenplay solution, as a root command — cratis render — sitting alongside cratis run, in the same spirit as docker run / dotnet run / aspire run.

For now it only needs to support Cratis, pulling the rendering packages from Stage. When other targets arrive, that becomes an argument.

Shape

cratis render [PATH] where PATH is a .play file or a folder — mirroring screenplay validate, which already resolves either. Note cratis run currently takes a folder only; worth aligning the three while adding this.

It should be a sibling of run, not a mode of it: run hands a folder to a container and watches, render materializes in-process from SDK packages. They share only play-file discovery and target resolution.

Packages

Cratis.Stage and Cratis.Stage.Contracts are published, and IRenderer lives in Contracts. Cratis.Stage.Rendering.Cratis carries the Cratis implementation, with CratisRenderer.CreateDefault() as the entry point.

Two things to settle first

Version blocker. Taking Cratis.Stage.Contracts forces Cratis.Screenplay 1.8.0, which the CLI cannot currently take: the published Cratis.Arc.Screenplay is compiled against Cratis.Screenplay 1.5.2, and 1.7.0 added a parameter to the ApplicationSyntax primary constructor — source-compatible, binary-breaking. Generation dies at runtime with a missing-method error. An Arc release built against 1.8.0 unblocks this.

Hosting or materializing. Cratis.Stage needs a reachable Chronicle and MongoDB to materialize a model into. If render means "produce the code", the honest first cut needs neither — it is .play → renderer → files on disk. If it means "host it", it inherits the runtime dependency, and the sandbox run already uses is the obvious fallback.

[woksin]

Built it, and it cannot ship yet. The command is on feat/render-root-command (unmerged, deliberately): cratis render [PATH] [--target DIRECTORY], an IScreenplayRendering seam mirroring IScreenplayValidation, six specs, 446 green against a 436 baseline. What blocks it is not the command.

The blocker

Cratis.Stage.Rendering.Cratis is not a text generator's package. It carries the Arc + Chronicle + MongoDB runtime it generates code for, and the template engine it scaffolds with — filed as Cratis/Stage#34. Taking it here costs, in order:

1. 160 compilation errors. The Cratis package contributes GlobalUsings.cs through Cratis.props, so this project silently gains 28 global usings. User becomes ambiguous between Cratis.Arc.Identity.User and Cratis.Chronicle.Contracts.Security.User, AppendedEvent between two Chronicle namespaces, CommandContext between Spectre's and Arc's. Fixed by taking Cratis directly with ExcludeAssets="build;buildTransitive;analyzers" — in Cli.csproj and Cli.Specs.csproj, since it reaches the spec project transitively too.

2. error MSBL001. The template engine brings NuGet.Frameworks, and Microsoft.Build.Locator — which screenplay generate needs — refuses to run when a copy sits beside the executable. Fixed the prescribed way: ExcludeAssets="runtime" PrivateAssets="all".

3. Which breaks rendering at runtime. With that exclusion the build is green and all 446 specs pass, and then:

   $ cratis render invoicing.play --target ./Invoicing
   Error: Failed to install 'Cratis.Templates':
   /Users/…/cratis.templates/1.1.1/cratis.templates.1.1.1.nupkg cannot be installed.
   

   NuGet.Frameworks.dll is not in the output folder, and the template engine needs it to read the template package. The two engines this CLI would host have opposite requirements about the same assembly — MSBuildLocator requires it absent, the template engine requires it present. That is not a workaround away.

4. A version regression underneath all of it. The restore holds Cratis.Chronicle.Contracts and .Connections at the pinned 16.19.3, but pulls Cratis.Chronicle 16.26.0 in behind Arc 21.13.0 — past the 16.20.0 TLS default that Chronicle 16.20.0 validates TLS by default, so the CLI can no longer connect to a local server out of the box #67 exists to hold the CLI back from, and mismatched against its own contracts. Builds clean, passes every spec, and is exactly the shape that throws when it finally talks to a server.

What unblocks it

Cratis/Stage#34, specifically the second half: splitting scaffolding out of Cratis.Stage.Rendering.Cratis so the renderer is what it claims to be — a text generator with Cratis.Screenplay, Cratis.Stage.Contracts and the BCL, and nothing else. Then this command is a package reference and a merge.

Worth settling at the same time, since it decides whether the template engine has to come along at all: does render scaffold? Rendering into a project the caller already has needs no template engine, and --target pointing at an existing project is the common case for regenerating from a document. Scaffolding could be cratis new instead.

Two notes on the branch

• ValidatedScreenplay gained an Applications init property rather than a constructor parameter — a trailing optional parameter on a positional record is source-compatible and binary-breaking.
• --target, not --output: every command already carries a global -o|--output for the output format.

[woksin]

This command works. Proven end to end against a locally-built renderer with the two Cratis/Stage#34 changes applied — the Debug-gated spec references and the template engine removed:

$ cratis render invoicing.play --target ./Invoicing
{"target":"…/Invoicing","documents":1,"notCarried":44}

33 C# files on disk, exit 0, and 44 lines on stderr naming everything the rendered application does not carry. invoicing.play is the language's own 17-slice document with every construct in it.

With those two upstream changes, all three workarounds on feat/render-root-command delete:

Workaround	Why it exists	Removed by
Cratis taken directly with ExcludeAssets="build;…" in Cli.csproj and Cli.Specs.csproj	the meta-package's Cratis.props contributes 28 global usings → 160 ambiguity errors	the Debug condition (verified: build clean with the reference deleted)
NuGet.Frameworks with ExcludeAssets="runtime"	template engine vs Microsoft.Build.Locator	removing the template engine
Microsoft.Build.Framework in Cli.Specs.csproj	same	same

NuGet.Frameworks enters through exactly one path — Microsoft.TemplateEngine.Edge behind the renderer — and nothing else in this CLI brings it.

So the branch as committed is the version that works against the published 2.3.0, warts and all; the version worth merging is that branch minus every csproj workaround, once Stage ships. Nothing about the command itself needs to change.

One thing the run settles that was open in the issue text: render does not need to scaffold. It placed 33 files into an empty directory perfectly well. Scaffolding a project around them is a separate job with a separate audience, and carrying the template engine for it is the sole reason this package cannot be hosted next to screenplay generate.

[woksin]

Shipped in #70. cratis render renders a document or a folder of documents, reporting what the rendered application does not carry; --target chooses the directory and defaults to ./out.