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.
| Input | Behaviour |
|---|---|
new project . | Uses the current directory; the project name is derived from that folder. |
new project MyApp | Creates MyApp/ and names the project MyApp. |
--name Acme.App | Overrides the project name and therefore the root namespace. |
--force | Allows overwriting generated files; without it an existing target is an error. |
--help | Prints 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:
- An explicit
--frameworkmust resolve to a directory containingBuild/Donkeh.propsor a repository root with aDonkehfolder; otherwise it is an error. - Without one, the locator walks up from the current directory and then the tool's base directory looking for the same markers.
- If nothing is found, it returns
nulland 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.
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"
}
});
}
| Decision | Reason |
|---|---|
| Project name from folder | donkeh 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 assembly | A released CLI references the matching package version; the generated file exposes DonkehVersion so it can be overridden. |
No Main | The framework package or checkout build targets generate the entry point from [AppRoot]. |
| No CSS file | The 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.
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:
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:
| Target | Checkout project | NuGet project |
|---|---|---|
| desktop | Already enabled; the command reports that the target is already enabled. | Already enabled; the generated project already targets net10.0. |
| android | Enables <DonkehAndroid>true, uncommenting the template flag when present. | Adds net10.0-android, SupportedOSPlatformVersion 24 and a conditional Donkeh.Windowing.Android reference. |
| web | Enables <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
- Clears all NuGet caches with
dotnet nuget locals all --clear. - Updates
DonkehVersionand any literalDonkeh.*package versions in the project. - Runs
dotnet restore --force --no-cacheso the packages are downloaded fresh. - 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
| Decision | Cost |
|---|---|
| No MSBuild evaluation | Fast and dependency-free, but the CLI cannot understand complex property functions or imported target frameworks. |
| Text-preserving XML edits | Keeps projects human-formatted, but assumes conventional SDK-style XML and inserts only at known anchors. |
| Version from the tool assembly | Released tools align with packages automatically; a locally built CLI with a dev version may need DonkehVersion overridden. |
| No implicit restore/run | Generation stays fast and offline-capable, at the cost of one explicit next command. |
| Folder-per-component convention | Predictable and organised, but a project that intentionally keeps flat component files is not supported by the generator. |
| Regex-based target edits | Small and readable, but unusual project structures may need manual edits. |
| No uninstall/removal command | Generation is additive; deleting a component is a normal file operation, not a CLI feature. |
Code tour
| File | Read it for… |
|---|---|
Program.cs | The one-line process entry point. |
Cli.cs | Command dispatch, help, project/component/target/feature flows and error handling. |
FrameworkLocator.cs | Checkout detection and the NuGet fallback decision. |
ProjectGenerator.cs | Checkout and NuGet project templates, names and versioning. |
ComponentGenerator.cs | Folder layout, component template, namespace and stylesheet registration. |
TargetEnabler.cs | Property/TFM/package edits for Android and browser targets. |
FeatureEnabler.cs | Debug-only hot reload references and executable-project selection. |
WatchService.cs | Runs the project with DONKEH_HOT_RELOAD=1 and forwards app arguments. |
CsprojEditor.cs | Minimal formatting-preserving resource, version and item-group edits. |
Identifiers.cs | PascalCase, namespace and kebab-case policy. |
Tests/GeneratorTests.cs | The 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.