D Donkeh docs
GitHub

CLI tool

Donkeh.CliTool is the donkeh global tool. It is deliberately small: parse a handful of commands, generate a project or a component, wire platform targets into an SDK-style project, and get out of the way. It never evaluates MSBuild, never runs a restore implicitly, and does not own a template engine.

Command surface

donkeh new project [<directory>] [--name <name>] [--type application|framework] [--framework <path>] [--force]
donkeh new component <name> [--project <path>] [--force]
donkeh enable-target <desktop|android|web> [--project <path>]
donkeh enable-feature <hot-reload> [--project <path>]
donkeh watch [--project <path>] [-- <app args>]
donkeh upgrade project [--version <version>] [--project <path>]
donkeh --help
donkeh --version

Program.cs is a one-line entry point that returns Cli.Run(args). The CLI catches CliException and unexpected exceptions alike, prints error: … to stderr and returns exit code 1. Success paths return 0. There is no stack trace or partial stack of console noise on a normal user mistake.

Argument parsing

ParsedArguments is a small hand-written parser, not System.CommandLine. It collects positionals, accepts --option value and --option=value, handles --force and help flags, and rejects unknown options or missing values with a clean message. That keeps startup tiny and avoids a dependency whose help formatting would be larger than the tool.

InputBehaviour
new project .Uses the current directory; the project name is derived from that folder.
new project MyAppCreates MyApp/ and names the project MyApp.
--name Acme.AppOverrides the project name and therefore the root namespace.
--forceAllows overwriting generated files; without it an existing target is an error.
--helpPrints command-specific help and exits 0.

Checkout or NuGet

FrameworkLocator decides whether a new project should reference a local framework checkout or the published packages:

  1. An explicit --framework must resolve to a directory containing Build/Donkeh.props or a repository root with a Donkeh folder; otherwise it is an error.
  2. Without one, the locator walks up from the current directory and then the tool's base directory looking for the same markers.
  3. If nothing is found, it returns null and the generator uses NuGet packages.

A checkout project imports Build/Donkeh.props and Build/Donkeh.targets, uses project references, and carries a generated Directory.Build.targets. A NuGet project has no framework import; it references Donkeh.Windowing at the CLI's own assembly version and leaves the framework's package build assets to supply the entry point.

No restore during generation The CLI writes files and prints the next command. It does not run dotnet restore, so generation stays fast and does not fail because of a transient network or credential problem. dotnet run or dotnet restore performs the restore when the developer is ready.

Project generation

ProjectGenerator creates the project file, Program.cs and .gitignore, plus the checkout targets file when needed. The generated app is intentionally minimal:

using Donkeh.Hosting;
using Donkeh.UILab;
using static Donkeh.UILab.HtmlHelper;

namespace MyApp;

[AppRoot(Width = 1000, Height = 700, Title = "MyApp")]
public sealed class App : Component
{
    public override Node Render() =>
        Div(new()
        {
            ClassName = "app",
            Attributes = new Dictionary<string, string>
            {
                ["style"] = "margin:0;width:100vw;height:100vh;background:#ffffff"
            }
        });
}
DecisionReason
Project name from folderdonkeh new project . uses the containing directory name, so a normal folder does not need a second argument.
Invalid filename characters replaced with _The project name becomes a file name and a namespace; sanitising here prevents a later failure.
Version from the tool assemblyA released CLI references the matching package version; the generated file exposes DonkehVersion so it can be overridden.
No MainThe framework package or checkout build targets generate the entry point from [AppRoot].
No CSS fileThe blank project has no component folder yet; new component adds one with its own stylesheet.

Framework projects

--type framework generates a component library and a console test container instead of a standalone app. The library is packable, the container references it directly, and the container discovers every public component in the library assembly and renders it in a gallery.

Acme.Components/ ├── Acme.Components.sln ├── src/ │ ├── Acme.Components.csproj // packable library │ └── Components/ │ └── HelloCard/ │ ├── HelloCard.cs │ └── HelloCard.css ├── test-container/ │ ├── TestContainer.csproj // executable, references ../src │ ├── Program.cs // AppRoot + reflection gallery │ └── Styles/ │ └── gallery.css ├── .gitignore └── README.md

The library references Donkeh.UILab; the container references Donkeh.Windowing and the library. In checkout mode the library references the checkout's UILab project directly, while the container imports the normal framework props and targets. The container walks the library assembly for non-abstract components with a public parameterless constructor and uses C(type) to mount each one.

donkeh new project Acme.Components --type framework
cd Acme.Components
donkeh enable-feature hot-reload
donkeh watch

# publish when ready
dotnet pack src/Acme.Components.csproj -c Release

The generated README records the same preview and publish commands. Adding a component with donkeh new component from the project root does not currently target the library automatically; pass --project src/Acme.Components.csproj, or run the command from src/.

Component generation

new component FileList finds the project, reads its RootNamespace, normalises the component name and writes one folder per component:

src/ └── Components/ └── FileList/ ├── FileList.cs └── FileList.css

The generated class uses the typed HtmlHelper builder and registers its stylesheet with an assembly attribute:

using Donkeh.UILab;
using static Donkeh.UILab.HtmlHelper;

[assembly: Donkeh.UILab.Stylesheet("src/Components/FileList/FileList.css")]

namespace MyApp.Components;

/// <summary>FileList component.</summary>
public sealed class FileList : Component
{
    /// <inheritdoc/>
    public override Node Render() =>
        Div(new() { ClassName = "file-list" });
}

The component namespace is RootNamespace + ".Components" unless the root namespace already ends with .Components. The CSS class is the PascalCase name converted to kebab case, including acronym handling such as MyHTTPClient → my-http-client. Existing files are refused unless --force is passed.

Formatting-preserving project edits

CsprojEditor does not deserialize and reserialize the project. It detects the file's line ending, checks whether the resource path is already present with either slash style, and inserts a small ItemGroup immediately before the final </Project>. Comments, formatting, ordering and unrelated properties survive unchanged, and the operation is idempotent.

<ItemGroup>
  <EmbeddedResource Include="src/Components/FileList/FileList.css" />
</ItemGroup>

The generator resolves namespaces through XDocument when the file is valid XML, but falls back to the project file name if parsing fails. That keeps a messy but buildable project editable without making XML parsing a hard requirement.

Target wiring

enable-target detects checkout versus NuGet mode by looking for Donkeh.props in the project text, then edits the appropriate surface:

TargetCheckout projectNuGet project
desktopAlready enabled; the command reports that the target is already enabled.Already enabled; the generated project already targets net10.0.
androidEnables <DonkehAndroid>true, uncommenting the template flag when present.Adds net10.0-android, SupportedOSPlatformVersion 24 and a conditional Donkeh.Windowing.Android reference.
webEnables <DonkehWeb>true.Adds net10.0-browser, browser-wasm RIDs, the browser host, the Blazor package and the WebAssembly SDK pack.

The edits are regular-expression and text based, not MSBuild-aware. They preserve the existing TargetFramework or append to TargetFrameworks, add properties inside the first PropertyGroup and add conditional PackageReference items before the closing project tag. Enabling an already-enabled target is a clean error instead of a silent no-op.

Names and sanitising

Identifiers provides the small amount of naming policy the CLI needs. Component names split on spaces, hyphens, underscores, dots and path separators, then PascalCase each word. C# keywords gain a Component suffix, names starting with a digit get an underscore, and namespaces PascalCase each dotted segment. Kebab case inserts hyphens at case boundaries, including acronym-to-word transitions.

Development features and watch

enable-feature hot-reload adds the optional CSS watcher to the executable project:

donkeh enable-feature hot-reload
donkeh watch

A framework root resolves to its test-container project. A framework checkout receives a conditional ProjectReference; a NuGet project receives a conditional PackageReference. Both carry '$(Configuration)' == 'Debug', so Release builds and published applications do not reference or copy the watcher. The same item group marks embedded CSS with Watch="false" so a stylesheet save does not make dotnet watch rebuild. The command is idempotent.

donkeh watch refuses to start until the feature is enabled, then runs dotnet watch run -c Debug -f net10.0 with DONKEH_HOT_RELOAD=1. Arguments after -- are forwarded to the application. Supported C# edits are applied in place by the .NET Hot Reload agent; the development package detects the source change, waits for the patch to settle and re-renders every mounted component. A second refresh covers a slower patch. Unsupported edits make dotnet watch restart the app. CSS edits rebuild the cascade through the in-process stylesheet reloader instead of a build.

Upgrading a project

donkeh upgrade project moves a NuGet-based project to a newer Donkeh package set and updates the installed CLI:

donkeh upgrade project --version=1.0.25

# or resolve the latest stable version
donkeh upgrade project
  1. Clears all NuGet caches with dotnet nuget locals all --clear.
  2. Updates DonkehVersion and any literal Donkeh.* package versions in the project.
  3. Runs dotnet restore --force --no-cache so the packages are downloaded fresh.
  4. Runs dotnet tool update --global Donkeh.CliTool --version ....

A project generated against a local framework checkout is rejected; upgrade the checkout with git instead. If the global tool is locked because it is the process running the command, the update is scheduled for after the command exits.

Tests

The CLI tests call the generators directly against temporary directories rather than spawning processes. They cover checkout and NuGet project shapes, component folder creation and stylesheet registration, target editing, feature reference selection, force protection and identifier normalisation. That keeps the feedback loop fast and makes the generated file content part of the tested contract.

Trade-offs and sharp edges

DecisionCost
No MSBuild evaluationFast and dependency-free, but the CLI cannot understand complex property functions or imported target frameworks.
Text-preserving XML editsKeeps projects human-formatted, but assumes conventional SDK-style XML and inserts only at known anchors.
Version from the tool assemblyReleased tools align with packages automatically; a locally built CLI with a dev version may need DonkehVersion overridden.
No implicit restore/runGeneration stays fast and offline-capable, at the cost of one explicit next command.
Folder-per-component conventionPredictable and organised, but a project that intentionally keeps flat component files is not supported by the generator.
Regex-based target editsSmall and readable, but unusual project structures may need manual edits.
No uninstall/removal commandGeneration is additive; deleting a component is a normal file operation, not a CLI feature.

Code tour

FileRead it for…
Program.csThe one-line process entry point.
Cli.csCommand dispatch, help, project/component/target/feature flows and error handling.
FrameworkLocator.csCheckout detection and the NuGet fallback decision.
ProjectGenerator.csCheckout and NuGet project templates, names and versioning.
ComponentGenerator.csFolder layout, component template, namespace and stylesheet registration.
TargetEnabler.csProperty/TFM/package edits for Android and browser targets.
FeatureEnabler.csDebug-only hot reload references and executable-project selection.
WatchService.csRuns the project with DONKEH_HOT_RELOAD=1 and forwards app arguments.
CsprojEditor.csMinimal formatting-preserving resource, version and item-group edits.
Identifiers.csPascalCase, namespace and kebab-case policy.
Tests/GeneratorTests.csThe generated-file contract and target-edit expectations.

The mental model: the CLI is a thin, predictable file generator. It resolves whether the developer is inside the framework checkout or consuming packages, writes the smallest useful project or component, and edits SDK-style project files without taking ownership of them.