Gum Cli

Exit codes: 0 = success, 1 = errors found / generation blocked, 2 = load failure, bad args, or non-Windows (fonts).

Architecture

Program.cs
  ├── NewCommand      → ProjectCreator / FormsTemplateCreator
  ├── CheckCommand    → ProjectLoader → HeadlessErrorChecker
  ├── CodegenCommand  → ProjectLoader → HeadlessErrorChecker (gates) → HeadlessCodeGenerationService
  ├── CodegenInitCommand → CodeGenerationAutoSetupService
  └── FontsCommand    → ProjectLoader → HeadlessFontGenerationService (Windows-gated)

Each command class has a static Create() returning a System.CommandLine Command with handler, then a static Execute() doing the work.

CLI-specific adapters:

• ConsoleCodeGenLogger — implements ICodeGenLogger, writes to stdout/stderr
• HeadlessNameVerifier — implements INameVerifier for C# name validation

Gum.ProjectServices

The headless service library GumCli depends on. All logic lives here; the CLI just wires it together.

Key types:

Non-obvious: HeadlessErrorChecker is not a duplicate of the tool's ErrorChecker — the tool's ErrorChecker delegates to HeadlessErrorChecker. Zero duplication by design.

HeadlessErrorChecker accepts a second constructor overload taking IEnumerable<IAdditionalErrorSource> for extensibility; the CLI uses the single-argument overload.

HeadlessNameVerifier only implements real logic in IsValidCSharpName; all other INameVerifier methods return true unconditionally. This is intentional — the CLI only needs C# name validation for codegen.

ProjectLoader runs DetectSilentlyDroppedContent after deserialization to catch incorrect XML element names (e.g., <States> instead of <State>, <InstanceSave> instead of <Instance>) that XmlSerializer silently ignores. Without this, AI-generated files with wrong structure load as empty elements with no error.

CodeGenerationAutoSetupService detects MonoGame vs non-MonoGame projects by scanning for <PackageReference Include="MonoGame.Framework. or nkast.Xna.Framework in the .csproj, then sets OutputLibrary accordingly. Namespace falls back to the .csproj filename (dots/dashes/spaces replaced with underscores) when <RootNamespace> is absent.

CodeGenerationAutoSetupService has two Run overloads: Run(gumxFilePath) for auto-detection, and Run(gumxFilePath, explicitCsprojPath) for when the caller already knows the .csproj path. The explicit overload validates the file exists and skips directory walking entirely; all namespace/OutputLibrary derivation logic is shared via the private BuildResultFromCsprojDirectory helper.

Font files are named like Font18Arial.fnt and Font18Arial_0.png (size+name convention, zero-indexed). Always use gumcli fonts <project.gumx> to generate missing bitmap fonts — never create .fnt files manually.

Codegen Flow (non-obvious details)

• codegen iterates elements individually (not via GenerateCodeForAllElements) so it can run per-element error checks first; GenerateCodeForAllElements exists on HeadlessCodeGenerationService but the CLI does not call it
• Only Screens and Components are generated; StandardElements are intentionally excluded
• Errors (ErrorSeverity.Error) block generation for that element; warnings print to stderr but do not block
• ObjectFinder.Self cache is managed at the CLI level (enabled before the loop, disabled in finally)
• If ProjectCodeSettings.codsj is missing, codegen attempts CodeGenerationAutoSetupService auto-detection first and writes the settings file before continuing; exit code 2 only if auto-detection also fails
• When --element is specified, checkForMissing: true is passed so GenerateCodeForElement auto-generates any referenced elements whose code files do not yet exist; full-run mode skips that check
• codegen-init exits with code 2 (not 1) if settings already exist and --force is absent

Key Files

Testing Notes

• ObjectFinder is a singleton — tests disable parallel execution (TestAssemblyInitialize)
• BaseTestClass pre-populates GumProjectSave with standard elements and handles ObjectFinder.Self cleanup