feat(cli): formalize run/build with System.CommandLine and add a diag command group#10
Merged
Merged
Conversation
… command group Route the host's run/build modes through a single System.CommandLine pipeline and add a read-only `diag` command group for inspecting a site (built for humans and AI assistants). Every host gets the CLI for free via RunOrBuildAsync — no Program.cs changes. - Pennington.Cli: PenningtonCli is the single source of run-mode detection (PenningtonRunMode serve/build/diag; IsHeadlessOneShot/WritesOutput/IsHelpOrVersion gate the TestServer swap, logging, and dev overlays). PenningtonBuildMode is kept as a back-compat shim. RunOrBuildAsync builds one RootCommand (serve + build + diag) and dispatches via Parse().InvokeAsync(), so --help/--version work at the root and every subcommand. - diag subcommands (text output): info, toc, routes, warnings (--full crawls), translation/i18n, frontmatter, llms. Each reuses existing services (NavigationBuilder, IContentService, IAuditCache, OutputGenerationService, Localization/TranslationOptions); no new abstractions — "area" is the top-level nav node. - Build path behavior unchanged (TestServer, strict keys, progress logs, exit code). diag and --help/--version keep stdout clean regardless of host appsettings. - AuditRunner: expose WaitForInitialPassAsync() and register as a resolvable singleton so diag reads a complete audit snapshot. - Pennington.Tui steps aside for `diag` as well as `build`. Tests: add PenningtonCli mode-classification and AsciiTreeWriter tests; OutputOptions and Tui regressions stay green. Full suite: 877 unit + 51 treesitter + 48 integration, 0 failed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Routes the host's run/build modes through a single System.CommandLine pipeline and adds a read-only
diagcommand group for inspecting a site — built for humans and AI assistants. Every host gets the CLI for free viaRunOrBuildAsync; noProgram.cschanges anywhere.Why
We had two implicit modes selected by an
args[0] == "build"boolean that was consulted in ~10 gated places. This formalizes them (real--help/--version, validated options, room for more verbs) and exposes tooling so an AI assistant can quickly see the shape of a docs/blog site.How
Pennington.Cli—PenningtonCliis the single source of run-mode detection (PenningtonRunModeserve/build/diag;IsHeadlessOneShot/WritesOutput/IsHelpOrVersiongate the TestServer swap, logging, and dev overlays).PenningtonBuildModestays as a back-compat shim.RunOrBuildAsyncbuilds oneRootCommand(serve + build + diag) and dispatches viaParse().InvokeAsync(), so--help/--versionwork at the root and every subcommand.diagsubcommands (text output):info,toc,routes,warnings(--fullcrawls),translation/i18n,frontmatter,llms. Each reuses existing services (NavigationBuilder,IContentService,IAuditCache,OutputGenerationService,Localization/TranslationOptions). No new abstractions — "area" is just the top-level nav node.diagand--help/--versionkeep stdout clean regardless of the host's appsettings.AuditRunnerexposesWaitForInitialPassAsync()and is registered as a resolvable singleton sodiagreads a complete audit snapshot.Pennington.Tuisteps aside fordiagas well asbuild.Test plan
PenningtonClimode-classification +AsciiTreeWriterunit tests;OutputOptionsand Tui regressions stay green.WebApplicationFactory.diag info/toc/routes/warnings/frontmatter/llms,build(473 pages, exit 0),--help/--versionat root and every subcommand; multi-localetranslationagainstBeyondLocaleExample.Closes nothing tracked; net-new feature.