Provides the discoverable root for AppSurface coverage commands.
The root command keeps the coverage workflow visible in appsurface --help. The stable v1 contract includes coverage run, which executes instrumented .NET test projects, coverage merge, which fans in existing Cobertura shards, and coverage gate, which evaluates the merged coverage without requiring a hosted coverage service.
ValueTask ExecuteAsync(IConsole console)
Source
Prints the coverage command family summary.
consoleCliFx console used for command output.A completed task.
Exports an AppSurface/RazorWire application through the product-facing appsurface export command.
This command delegates crawling, hybrid split-origin rewriting, validation, and materialization to the shared RazorWire export engine while keeping the common AppSurface workflow discoverable from the AppSurface CLI.
string? PublishRootExtrasPath { get; set; }
Source
Gets or sets an optional path to a publish-root deployment extras manifest.
The manifest declares explicit deployment-owned files, such as CNAME, that should be copied into the publish root after export proves they do not collide with generated output. This option is distinct from SeedRoutesPath, which contains routes to crawl.
string? LiveOrigin { get; set; }
Source
Gets or sets the optional live origin for RazorWire-managed split-origin hybrid interactions.
The value must be an absolute http or https origin with no path, query string, fragment, or userinfo. Use this when the exported static files are served from one origin but RazorWire-owned live streams, islands, and lazy anti-forgery forms must call a different live app origin. Leave it unset for same-origin hybrid deployments.
RazorWireHybridCredentialsMode HybridCredentials { get; set; }
Source
Gets or sets credential behavior for RazorWire-managed live calls in hybrid output.
Defaults to RazorWireHybridCredentialsMode.Auto, which includes credentials only when LiveOrigin is set. Use RazorWireHybridCredentialsMode.Include for cookie-backed cross-origin live apps and RazorWireHybridCredentialsMode.Omit for public live surfaces that do not depend on cookies or anti-forgery token refreshes.
Verifies that a running web app exposes AppSurface-compatible PWA install metadata.
string? Url { get; set; }
Source
Gets the app origin or URL to verify.
string? BaseUrl { get; set; }
Source
Gets the app base URL to verify.
string EntryPath { get; set; }
Source
Gets the app-root-relative entry path whose HTML should expose the manifest link.
string? ExpectedStartUrl { get; set; }
Source
Gets the expected manifest start_url value.
string? ExpectedScope { get; set; }
Source
Gets the expected manifest scope value.
string? ExpectedDisplay { get; set; }
Source
Gets the expected manifest display mode.
string? ExpectedThemeColor { get; set; }
Source
Gets the expected manifest theme_color value.
string? ExpectedBackgroundColor { get; set; }
Source
Gets the expected manifest background_color value.
string[] ExpectedIcons { get; set; }
Source
Gets expected icon size tokens, optionally followed by a purpose after a colon.
bool Json { get; set; }
Source
Gets a value indicating whether machine-readable JSON should be written.
Fetches verifier resources without automatically following redirects.
Redirect custody stays with PwaVerifier so origin and path-base boundaries are checked before each hop.
Task<PwaHttpResponse> GetAsync(Uri uri, int maxBodyBytes, CancellationToken cancellationToken)
Source
Fetches one response and reads no more than the requested body limit.
uriThe absolute resource URI.maxBodyBytesThe maximum response-body bytes retained for evidence.cancellationTokenCancels the network request and bounded body read.The response metadata and bounded body.
Adapts HttpClient to the verifier's bounded, redirect-aware fetch contract.
httpClientA client configured with automatic redirect handling disabled.Enabling automatic redirects bypasses the verifier's same-origin and path-base checks.
Captures one bounded HTTP response before verifier-managed redirect handling.
StatusCodeThe actual server status code.ContentTypeThe response media type, or an empty string when absent.BodyBytesThe retained response bytes, capped by the requested read limit.RedirectLocationThe unmodified Location header value, when present.BodyTruncatedWhether bytes beyond the configured read limit were discarded.bool IsSuccess { get; }
Source
Gets whether the actual response status is in the HTTP 2xx range.
string Body { get; }
Source
Gets the retained body decoded as UTF-8 text.
Binary consumers should use BodyBytes instead.
Represents schema-versioned PWA verification evidence written by the CLI.
SchemaVersionThe JSON evidence schema version.PassedWhether no error-severity diagnostics were recorded.OriginThe verified scheme, host, and port without a path base.BaseUrlThe verified application root, including its path base.EntryPathThe app-root-relative entry path supplied to the verifier.EntryUrlThe absolute entry URL resolved under BaseUrl.ManifestPathThe app-origin-relative manifest path discovered or probed.StartUrlThe manifest start_url value, when parsed.ScopeThe manifest scope value, when parsed.DisplayThe manifest display value, when parsed.ThemeColorThe manifest theme_color value, when parsed.BackgroundColorThe manifest background_color value, when parsed.IconsBounded fetch and dimension evidence for manifest icons.DiagnosticsStable diagnostics supporting the pass or failure result.Consumers should branch on SchemaVersion and diagnostic codes instead of parsing human-readable messages.
Represents one stable, structured PWA verification observation.
CodeThe stable ASPWA2xx identifier.SeverityThe lowercase error, warning, or info token.MessageA human-readable explanation.SubjectThe bounded manifest field or verifier surface involved.ExpectedThe expected bounded value, when applicable.ActualThe observed redacted value, when applicable.FixA concise remediation, when known.DocsUrlCanonical documentation for the diagnostic, when available.Do not place query strings, fragments, response bodies, or other secrets in structured evidence.
Normalizes the trusted origin, application path base, and real entry route used by one verification run.
OriginThe scheme, host, and port boundary.BaseUriThe application root including its normalized path base.BasePathThe normalized path base ending in a slash.EntryPathThe validated app-root-relative entry path.EntryUriThe entry path resolved beneath BaseUri.Query strings and fragments belong in neither the base URL nor entry path because verifier evidence intentionally excludes them.
PwaVerificationTarget Create(Uri url, string entryPath = "/")
Source
Creates a normalized verification target after enforcing the URL and entry-path boundaries.
urlAn absolute HTTP or HTTPS application root without a query or fragment.entryPathAn app-root-relative path without traversal, query, fragment, or absolute URL syntax.The normalized target used for all verifier requests.
ArgumentExceptionThe URL or entry path violates a verifier boundary.Carries normalized CLI assertions into a PWA verification run.
BaseUrlThe absolute app root to verify.EntryPathThe app-root-relative HTML entry route.ExpectedStartUrlAn optional exact manifest start_url assertion.ExpectedScopeAn optional exact manifest scope assertion.ExpectedDisplayAn optional exact manifest display assertion.ExpectedThemeColorAn optional exact manifest theme_color assertion.ExpectedBackgroundColorAn optional exact manifest background_color assertion.ExpectedIconsParsed icon size and purpose assertions.Target safety is enforced by PwaVerificationTarget.Create(Uri, string) before network access.
PwaVerificationOptions Create(Uri baseUrl, string entryPath = "/", string? expectedStartUrl = null, string? expectedScope = null, string? expectedDisplay = null, string? expectedThemeColor = null, string? expectedBackgroundColor = null, IReadOnlyList<string>? expectedIcons = null)
Source
Creates verification options and parses repeated icon assertions.
baseUrlThe absolute app root to verify.entryPathThe app-root-relative entry route; blank values normalize to root.expectedStartUrlAn optional exact start_url assertion.expectedScopeAn optional exact scope assertion.expectedDisplayAn optional exact display assertion.expectedThemeColorAn optional exact theme_color assertion.expectedBackgroundColorAn optional exact background_color assertion.expectedIconsRepeated WIDTHxHEIGHT or WIDTHxHEIGHT:purpose assertions.Normalized options for PwaVerifier.
ArgumentExceptionAn icon assertion is malformed.Represents one explicit manifest icon size and optional purpose assertion.
SizeA positive WIDTHxHEIGHT token.PurposeAn optional manifest purpose token such as maskable.PwaExpectedIcon Parse(string value)
Source
Parses a command-line icon assertion.
valueWIDTHxHEIGHT or WIDTHxHEIGHT:purpose.The parsed assertion.
ArgumentExceptionThe size or purpose token is malformed.string ToString()
Source
Formats the assertion using its command-line token shape.
WIDTHxHEIGHT or WIDTHxHEIGHT:purpose.
Captures the final verifier-managed fetch state after zero or more accepted redirects.
FinalUriThe URI that produced Response.ResponseThe actual final response without fabricated sentinel status codes.RedirectLimitExceededWhether this response was an unfollowed redirect beyond the hop limit.Callers must not reinterpret Response as a terminal HTTP failure when RedirectLimitExceeded is true; ASPWA264 is the authoritative failure.
HttpStatusCode StatusCode { get; }
Source
Gets the actual final response status code.
string ContentType { get; }
Source
Gets the actual final response media type.
string Body { get; }
Source
Gets the retained final response body decoded as UTF-8.
byte[] BodyBytes { get; }
Source
Gets the retained final response bytes.
bool IsSuccess { get; }
Source
Gets whether the actual final response is in the HTTP 2xx range.
Represents dimensions decoded directly from a bounded PNG response.
WidthThe positive pixel width.HeightThe positive pixel height.Represents privacy-safe fetch and optional PNG dimension evidence for one manifest icon.
SourceThe manifest src value.SizesThe manifest sizes token list.TypeThe declared media type.PurposeThe declared purpose token list.PathThe fetched app-origin-relative path without query or fragment.ContentTypeThe observed response media type.WidthThe decoded PNG width, when available.HeightThe decoded PNG height, when available.FetchedWhether the icon returned an HTTP 2xx response.Models the manifest fields required for install-readiness verification.
NameThe manifest name.ShortNameThe manifest short_name.StartUrlThe manifest start_url.ScopeThe manifest scope.DisplayThe manifest display mode.ThemeColorThe manifest theme_color.BackgroundColorThe manifest background_color.IconsThe manifest icon declarations.Models one manifest icon declaration without trusting it as fetched evidence.
SourceThe manifest src value.SizesThe space-delimited manifest sizes tokens.TypeThe declared media type.PurposeThe space-delimited manifest purpose tokens.Models the server-known AppSurface PWA diagnostics used for install, worker, offline, and push posture checks.
EnabledWhether AppSurface PWA metadata is enabled.OfflineEnabledWhether the offline strategy is enabled.ServiceWorkerPathThe active service-worker path when offline is enabled.OfflineFallbackPathThe active offline fallback path when offline is enabled.ConfiguredServiceWorkerPathThe configured worker path used to prove absence when offline is disabled.WorkerEnabledWhether either offline or push configuration activates the shared service worker.WorkerPathThe active shared service-worker path when a worker capability is enabled.PushEnabledWhether push event handling is enabled in the shared service worker.WorkerScopeThe effective registration scope for the shared service worker.RegistrationHelperPathThe registration-helper path exposed when push is enabled.These server-known values do not prove browser runtime capability or registration state.
Runs .NET test projects with Coverlet and produces merged private coverage artifacts.
The command is a public package-consumer orchestrator for repositories that already own their test instrumentation. It discovers or accepts test projects, runs dotnet test with Coverlet MSBuild properties, preserves logs and per-project Cobertura files, merges coverage via AppSurface's package-owned ReportGenerator dependency, and writes artifacts that appsurface coverage gate can evaluate without additional path translation.
ValueTask ExecuteAsync(IConsole console, CancellationToken cancellationToken)
Source
Executes the coverage run with an explicit cancellation token.
consoleConsole used for user-visible output.cancellationTokenCancellation token for process and artifact IO.A task that completes when the run finishes.
string? SolutionPath { get; set; }
Source
Gets or sets the solution used for discovery. Supports .sln and .slnx.
string[] TestProjects { get; set; }
Source
Gets or sets explicit test project paths. Repeat this option to skip solution discovery.
string OutputDirectory { get; set; }
Source
Gets or sets the coverage output directory.
string Configuration { get; set; }
Source
Gets or sets the build and test configuration.
int Parallelism { get; set; }
Source
Gets or sets the maximum number of non-exclusive projects that may run at once.
string Schedule { get; set; }
Source
Gets or sets the project scheduling mode.
string? ScheduleTimings { get; set; }
Source
Gets or sets an explicit timings file used by --schedule longest-first.
string[] PriorityTestProjects { get; set; }
Source
Gets or sets non-exclusive projects that should be scheduled before duration-sorted projects.
bool NoRestore { get; set; }
Source
Gets or sets a value indicating whether build and test commands should pass --no-restore.
bool Build { get; set; }
Source
Gets or sets a value indicating whether to build once before running tests.
bool NoBuild { get; set; }
Source
Gets or sets a value indicating whether to skip the solution build before tests.
string? IncludeFilter { get; set; }
Source
Gets or sets the optional Coverlet include filter.
string? ExcludeFilter { get; set; }
Source
Gets or sets the Coverlet exclude filter.
bool DryRun { get; set; }
Source
Gets or sets a value indicating whether discovery and scheduling should be printed without running tests.
bool ListProjects { get; set; }
Source
Gets or sets a value indicating whether projects should be listed without running tests.
bool NoDiscoverExclusive { get; set; }
Source
Gets or sets a value indicating whether automatic integration/Playwright exclusive classification is disabled.
string[] ExclusiveTestProjects { get; set; }
Source
Gets or sets projects that should run exclusively. Repeat this option for multiple projects.
string[] Loggers { get; set; }
Source
Gets or sets test logger arguments forwarded to dotnet test. Repeat this option for multiple loggers.
string[] TestArguments { get; set; }
Source
Gets or sets extra arguments appended to every dotnet test invocation.
string? TestResults { get; set; }
Source
Gets or sets the managed test result artifact format.
bool SlowTestDiagnostics { get; set; }
Source
Gets or sets a value indicating whether slow-test diagnostic artifacts should be written.
bool NoClean { get; set; }
Source
Gets or sets a value indicating whether existing owned output should not be cleaned before the run.
string Verbosity { get; set; }
Source
Gets or sets the dotnet test verbosity.
Request for running and merging coverage from one or more .NET test projects.
SolutionPathOptional .sln or .slnx path used for discovery.TestProjectsExplicit test project paths. Supplying at least one path skips solution discovery.OutputDirectoryCoverage artifact directory. Existing content must be AppSurface-owned unless cleaning is disabled.ConfigurationBuild and test configuration forwarded to dotnet build and dotnet test.ParallelismMaximum concurrent non-exclusive test projects.ScheduleModeProject scheduling mode used before process execution.ScheduleTimingsPathOptional explicit timings file for duration-aware scheduling.PriorityTestProjectsNon-exclusive project path or file-name matches scheduled ahead of duration-sorted projects.NoRestoreWhether build and test commands should pass --no-restore.BuildWhether to build once before tests, including explicit-project runs.NoBuildWhether to skip AppSurface's build phase and forward --no-build to dotnet test.IncludeFilterOptional Coverlet include filter.ExcludeFilterCoverlet exclude filter. Commas are escaped before forwarding to MSBuild.DryRunWhether to print discovery and artifact paths without running tests or cleaning output.NoDiscoverExclusiveWhether automatic integration/Playwright exclusive classification is disabled.ExclusiveTestProjectsExplicit project path or file-name matches that should run exclusively.LoggersLogger values forwarded to dotnet test as repeatable --logger: arguments.TestArgumentsExtra tokens appended to each dotnet test invocation.TestResultsManaged test result artifact format.SlowTestDiagnosticsWhether slow-test diagnostic artifacts should be written.CleanWhether AppSurface-owned output is cleaned before writing new artifacts.VerbosityVerbosity forwarded to dotnet test.The request is the internal contract behind the public coverage run command. Paths are interpreted relative to the current working directory for explicit-project runs, or relative to the solution directory after solution discovery. The workflow never mutates consumer projects: Coverlet must already be referenced by each selected test project, logger arguments are forwarded verbatim, and extra test arguments are appended after AppSurface's required coverage properties.
Result of a public coverage run.
SuccessWhether all required test, merge, and artifact steps succeeded.OutputDirectoryAbsolute output directory.CoveragePathAbsolute merged Cobertura path.FailureLogPathPrimary failing project log path, when a project failed.A result is returned only after discovery, test execution, merge, summary, and timings steps have finished. Diagnostic failures throw CommandException before this result is created. When tests fail after writing coverage, Success is false while merged artifacts are still available for inspection.
Coordinates public coverage run discovery, scheduling, test execution, merge, and artifacts.
Task<CoverageRunResult> RunAsync(CoverageRunRequest request, IConsole console, CancellationToken cancellationToken)
Source
Runs the coverage workflow.
requestCoverage run request.consoleConsole used for user-visible output.cancellationTokenCancellation token for process and artifact IO.Coverage run result.
Planned project execution order for a coverage run.
ModePublic scheduling mode name written to console output and timings.TimingSourceSource used to load prior project durations.WarningsNon-fatal scheduling warnings.EntriesExecution entries in original-index-compatible project space.Prior-duration source used to build a schedule.
KindSource kind: none, inferred, or explicit.PathTimings file path when one was considered.StatusRead status for the source.One project's execution slot in the schedule.
OriginalIndexProject index from discovery or explicit input order.ExecutionIndexIndex used to launch the process.ProjectProject scheduled for this slot.ScheduledSecondsPrior duration used for sorting, when available.DurationSourceWhere ScheduledSeconds came from.ScheduleReasonHuman-readable reason for the chosen slot.Prior timing data loaded before output cleanup.
KindSource kind: inferred or explicit.PathSource file path.StatusLoad status.DurationSourcePer-project duration source value.TimingsByProjectProject durations keyed by normalized relative project path.WarningsNon-fatal load warnings.Project paired with its discovery/input index.
OriginalIndexProject index from discovery or explicit input order.ProjectProject metadata.Resolved project set used by the coverage runner after discovery or explicit selection.
SolutionPathAbsolute solution path when discovery was solution-based; otherwise null.SolutionDirectoryDirectory used as the working directory for build, test, and discovery commands.ProjectsSelected test projects in scheduled order.SkippedProjectsProjects discovered from the solution but excluded from coverage execution.Selected test project and scheduling metadata.
RelativePathProject path as displayed to users and recorded in timings.FullPathAbsolute project path passed to dotnet test.SlugStable artifact directory segment allocated from the project path.IsExclusiveWhether the project must run outside parallel batches.Project that solution discovery intentionally did not include.
ProjectPathPath reported by dotnet sln list.ReasonHuman-readable reason the project was skipped.Per-project test execution result.
IndexOriginal discovery or explicit input index.ExecutionIndexProject process launch index.ProjectProject metadata.ScheduledSecondsPrior duration used for scheduling, when available.DurationSourceSource used for ScheduledSeconds.ScheduleReasonReason the project received its execution slot.SecondsElapsed whole seconds for the project test command.ExitCodeTest process exit code.LogFilePer-project log file path.TestResultsManaged test result artifacts requested for this project.Managed test result artifact requested by coverage run.
FormatArtifact format.ProjectProject that owns the artifact.PathAbsolute artifact path.ParserStatusBest-effort parser status recorded in timings.Build phase result used to coordinate later dotnet test arguments.
SecondsElapsed whole seconds spent in the AppSurface build phase.TestsShouldSkipBuildWhether test commands should pass --no-build.Bounded prefix of a project log replayed to the console.
TextLog text prefix.TruncatedWhether additional log content remains on disk.Runs external processes for the coverage run workflow.
Implementations must preserve command output for diagnostics and honor cancellation promptly. When outputFile is supplied, implementations should stream output to that file during process execution and may return an empty CoverageRunProcessResult.Output.
Task<CoverageRunProcessResult> RunAsync(string fileName, IReadOnlyList<string> arguments, string workingDirectory, CancellationToken cancellationToken, string? outputFile = null)
Source
Runs a process and returns its exit code plus captured output.
fileNameExecutable name or path.argumentsArgument tokens passed without shell interpolation.workingDirectoryWorking directory for the child process.cancellationTokenCancellation token that should terminate the process tree.outputFileOptional log file that receives captured standard output and error.Process exit code and captured output.
Result of running a coverage workflow process.
ExitCodeChild process exit code.OutputCaptured standard output followed by captured standard error.Default process runner used by the public coverage command.
The runner delegates tokenized argument escaping and cancellation to CliWrap. It buffers short-lived discovery/build commands, streams per-project test logs to disk, and disables non-zero exit-code validation so coverage workflow failures remain ordinary command results.
Runs AppSurface's package-owned ReportGenerator dependency.
The merge contract accepts one or more per-project Cobertura files and writes ReportGenerator output into a caller-owned directory. Implementations must not read consumer tool manifests or require repositories to install ReportGenerator themselves.
Task<CoverageRunMergeResult> MergeAsync(IReadOnlyList<string> coverageFiles, string outputDirectory, CancellationToken cancellationToken)
Source
Merges Cobertura coverage files into one ReportGenerator output directory.
coverageFilesCobertura files emitted by instrumented test projects.outputDirectoryReportGenerator output directory for this run.cancellationTokenCancellation token for the merge process.Merge exit code plus expected Cobertura and text-summary paths.
Result of a ReportGenerator merge.
ExitCodeReportGenerator process exit code.CoberturaPathExpected merged Cobertura file path.SummaryPathExpected ReportGenerator text summary path.ReportGenerator-backed merge implementation for coverage run.
Locates the ReportGenerator package restored as a dependency of the AppSurface CLI package.
Packaged local tools carry ReportGenerator under the CLI base directory. Source and development runs may instead rely on NuGet's package cache, so the locator probes the pinned dependency first and then other installed ReportGenerator package versions as a compatibility fallback.
string ResolveReportGeneratorDll()
Source
Resolves the ReportGenerator DLL entrypoint.
Scheduling modes supported by coverage run.
Managed test result artifact format for coverage run.
Merges existing Cobertura shards into AppSurface coverage artifacts.
Use this command when another workflow already produced Cobertura files, such as a GitHub Actions matrix job that downloads shard artifacts into one fan-in directory. Repositories that want AppSurface to discover test projects and run Coverlet should use coverage run instead.
ValueTask ExecuteAsync(IConsole console, CancellationToken cancellationToken)
Source
Executes the coverage merge with an explicit cancellation token.
consoleConsole used for user-visible output.cancellationTokenCancellation token for package and artifact IO.A task that completes when the merge finishes.
string? SourceDirectory { get; set; }
Source
Gets or sets the directory that contains Cobertura shard files named coverage.cobertura.xml.
string OutputDirectory { get; set; }
Source
Gets or sets the merged coverage output directory.
Request for merging existing Cobertura coverage shards.
SourceDirectoryDirectory recursively searched for shard files named coverage.cobertura.xml.OutputDirectoryDirectory that receives merged AppSurface coverage artifacts.CleanWhether existing AppSurface-owned merge artifacts should be cleaned first.Result of a public coverage merge.
OutputDirectoryAbsolute output directory.CoveragePathAbsolute merged Cobertura path.SelectedReportsAbsolute selected input report paths.Coordinates public coverage merge source discovery, package-owned ReportGenerator execution, and artifacts.
Task<CoverageMergeResult> MergeAsync(CoverageMergeRequest request, IConsole console, CancellationToken cancellationToken)
Source
Merges existing Cobertura shard files into AppSurface coverage artifacts.
requestCoverage merge request.consoleConsole used for user-visible output.cancellationTokenCancellation token for package and artifact IO.Coverage merge result.
IReadOnlyList<string> Resolve(string sourceDirectory, string outputDirectory)
Source
Discovers and validates Cobertura shard inputs for coverage merge.
sourceDirectoryExisting readable directory searched recursively for files named exactly coverage.cobertura.xml.outputDirectoryMerge output directory whose resolved tree is excluded from discovery so reruns do not re-merge prior output.Absolute selected Cobertura report paths sorted by ordinal path.
Resolve expects the workflow to pass a non-empty existing sourceDirectory and a normalized outputDirectory. It rejects empty discovery results with ASCOV131, unreadable source traversal with ASCOV130, and malformed or unreadable selected Cobertura files with ASCOV132. The resolver ignores reports under the resolved output directory and any reportgenerator-input staging directory because those files are AppSurface-owned implementation details, not user-supplied shards. Existing symlinked path segments are compared through CoverageMergePathSafety.ResolvePhysicalPath(string); callers still need normal filesystem permissions, and concurrent writes can surface as IO diagnostics.
void Prepare(string outputDirectory, string sourceDirectory, bool clean)
Source
Validates, creates, marks, and optionally cleans the coverage merge output directory.
outputDirectoryDedicated output directory for merged coverage artifacts.sourceDirectoryDirectory containing user-supplied Cobertura shards.cleanWhether known AppSurface-owned merge artifacts should be removed before writing new output.Prepare rejects blank output paths, filesystem roots, the current working directory, the user home directory, files, source/output overlap in either direction, and populated directories that do not contain the .appsurface-coverage-output ownership marker. Missing or empty output directories are allowed. Marked directories are treated as AppSurface-owned; when clean is true, only known merge artifacts and staging directories are deleted, while unrelated directories such as legacy project coverage output are preserved. The method creates outputDirectory and writes the marker file as side effects, so callers need create/write/delete permissions and should avoid concurrent writers. Source/output overlap checks resolve existing symlink segments through CoverageMergePathSafety.ResolvePhysicalPath(string) to catch path aliases.
string ResolvePhysicalPath(string path)
Source
Resolves existing filesystem segments in a path to their physical targets for overlap checks.
pathPath to normalize and resolve.A full path where existing files, directories, and symlink targets have been resolved where possible; missing trailing segments are preserved as full paths.
ResolvePhysicalPath(string) is used by merge source/output exclusion and output-guard overlap checks so aliases such as symlinked output directories are compared by physical location instead of lexical spelling. It does not create files or directories. Callers must pass a non-null path; invalid path shapes or inaccessible segments can raise platform filesystem exceptions before higher-level callers translate them to ASCOV138 or related diagnostics. Symlinks are resolved with FileSystemInfo.ResolveLinkTarget(bool) using returnFinalTarget: true; if no target is available, or if recursive target resolution reaches sixteen hops, the current full path is returned to avoid unbounded loops.
Validates that coverage merge staging preserved the selected shard set before ReportGenerator sees the glob.
void EnsurePreservedSelectedShardCount(int selectedReportCount, int stagedReportCount)
Source
Ensures that the staged ReportGenerator input tree contains one Cobertura file for each selected source shard.
selectedReportCountNumber of source shards selected by discovery.stagedReportCountNumber of staged Cobertura files visible to the ReportGenerator glob.Evaluates a Cobertura coverage file against line and branch thresholds.
This is the stable v1 coverage command. It reads a local Cobertura artifact, writes private JSON and Markdown reports, optionally appends the Markdown report to GitHub's step summary, and exits non-zero when the configured quality gate fails.
ValueTask ExecuteAsync(IConsole console)
Source
Executes the coverage gate.
consoleCliFx console used for command output.A task that completes after report files are written.
ValueTask ExecuteAsync(IConsole console, CancellationToken cancellationToken)
Source
Executes the coverage gate with an explicit cancellation token.
consoleCliFx console used for command output.cancellationTokenCancellation token for evaluator and report IO.A task that completes after report files are written and gate outcome is emitted.
string CoveragePath { get; set; }
Source
Gets or sets the Cobertura XML file to evaluate.
decimal MinLine { get; set; }
Source
Gets or sets the minimum line coverage percentage from 0 to 100.
decimal MinBranch { get; set; }
Source
Gets or sets the minimum branch coverage percentage from 0 to 100.
string? DiffBase { get; set; }
Source
Gets or sets the git ref or commit used to compute changed-line coverage.
string? DiffFile { get; set; }
Source
Gets or sets a unified diff file used to compute changed-line coverage.
bool DiffStdin { get; set; }
Source
Gets or sets a value indicating whether unified diff text should be read from stdin.
string? DiffLabel { get; set; }
Source
Gets or sets an optional display label for the selected patch diff source.
string? RepositoryRoot { get; set; }
Source
Gets or sets the repository root used for Cobertura and diff path matching.
decimal? MinPatchLine { get; set; }
Source
Gets or sets the minimum changed-line coverage percentage from 0 to 100.
decimal? MinPatchBranch { get; set; }
Source
Gets or sets the minimum changed-branch coverage percentage from 0 to 100.
string? OutputDirectory { get; set; }
Source
Gets or sets the directory where coverage-gate.json and coverage-gate.md are written.
bool GithubSummary { get; set; }
Source
Gets or sets a value indicating whether the Markdown report should be appended to $GITHUB_STEP_SUMMARY.
bool NoGithubSummary { get; set; }
Source
Gets or sets a value indicating whether GitHub summary output should be suppressed.
Request for evaluating a Cobertura coverage quality gate.
CoveragePathAbsolute path to the Cobertura XML file.OutputDirectoryAbsolute directory where private report artifacts should be written.MinLinePercentMinimum accepted line coverage percentage.MinBranchPercentMinimum accepted branch coverage percentage.WriteGithubSummaryWhether to append Markdown output to GithubStepSummaryPath.GithubStepSummaryPathOptional GitHub step summary file path.PatchCoverageOptional changed-line coverage request.Request for estimating coverage on lines changed by a patch diff source.
RepositoryRootRepository root used for diff acquisition and path normalization.DiffSourcePatch diff source used to acquire unified diff text.MinPatchLinePercentOptional changed-line threshold.MinPatchBranchPercentOptional changed-branch threshold.Result of evaluating coverage against line and branch thresholds.
CoveragePathCobertura file that was evaluated.LineCoverageLine coverage metric.BranchCoverageBranch coverage metric.MinLinePercentMinimum accepted line coverage percentage.MinBranchPercentMinimum accepted branch coverage percentage.PassedWhether both metrics met their thresholds.JsonReportPathJSON report path.MarkdownReportPathMarkdown report path.MinPatchLinePercentOptional minimum accepted changed-line coverage percentage.PatchLineCoverageOptional changed-line coverage metric.MinPatchBranchPercentOptional minimum accepted changed-branch coverage percentage.PatchBranchCoverageOptional changed-branch coverage metric.PatchDiffSourceOptional patch diff source provenance.One Cobertura coverage metric expressed as optional covered/valid counts and a percentage.
CoveredCovered line or branch count, when Cobertura provides it.ValidValid line or branch count, when Cobertura provides it.PercentCoverage percentage from 0 to 100.Coverage estimate for changed lines from a git diff.
DiffBaseGit ref or commit compared with HEAD.ChangedLinesTotal added or modified lines in the diff.MeasurableLinesChanged lines present in the Cobertura line map.CoveredLinesMeasurable changed lines with at least one hit.PercentChanged-line coverage percentage.Coverage estimate for branch conditions on changed lines from a git diff.
DiffBaseGit ref or commit compared with HEAD.ChangedLinesTotal added or modified lines in the diff.MeasurableBranchesChanged-line branch conditions present in the Cobertura line map.CoveredBranchesMeasurable changed-line branch conditions that were covered.PercentChanged-branch coverage percentage.Coverage estimates for changed lines and changed-line branch conditions.
SourceReportPatch diff source provenance captured during evaluation.LineCoverageChanged-line coverage metric.BranchCoverageChanged-branch coverage metric.Parses Cobertura XML and evaluates coverage thresholds.
XML parsing disables DTD processing and external resolution because coverage files are CI artifacts, not trusted configuration. The evaluator accepts either Cobertura rate attributes or covered/valid counts and validates that the resulting metrics are finite percentages.
Task<CoverageGateResult> EvaluateAsync(CoverageGateRequest request, CancellationToken cancellationToken)
Source
Evaluates a Cobertura file against the requested line and branch thresholds.
requestCoverage gate request.cancellationTokenCancellation token for file IO.The gate result.
CommandExceptionThrown when inputs are missing, unsafe, or unsupported.bool IsPercentInRange(decimal value)
Source
Gets whether a threshold percentage is in the valid inclusive range.
valueCandidate percentage.true when value is from 0 through 100.
Estimates coverage for lines and branch conditions added or modified by a git diff.
Task<PatchCoverageMetrics> EvaluateAsync(string coveragePath, CoveragePatchRequest request, CancellationToken cancellationToken)
Source
Evaluates changed-line and changed-branch coverage by reading git diff and the Cobertura line map.
coveragePathCobertura XML file.requestChanged-line coverage request.cancellationTokenCancellation token.Changed-line and changed-branch coverage metrics.
Task<PatchCoverageMetrics> EvaluateAsync(string coveragePath, CoveragePatchRequest request, string diffText, CancellationToken cancellationToken)
Source
Evaluates changed-line and changed-branch coverage from supplied git diff text.
coveragePathCobertura XML file.requestChanged-line coverage request.diffTextUnified git diff text.cancellationTokenCancellation token.Changed-line and changed-branch coverage metrics.
Reads changed lines from git.
Task<string> ReadDiffAsync(string repositoryRoot, string diffBase, CancellationToken cancellationToken)
Source
Reads a zero-context diff between diffBase and HEAD.
repositoryRootRepository root where git should run.diffBaseGit ref or commit compared with HEAD.cancellationTokenCancellation token.Unified diff text.
Writes private coverage gate report artifacts.
Task WriteAsync(CoverageGateResult result, CoverageGateRequest request, CancellationToken cancellationToken)
Source
Writes JSON, Markdown, and optional GitHub summary output for a coverage gate result.
resultGate result to render.requestOriginal gate request.cancellationTokenCancellation token for file IO.A task that completes when output files are written.
string RenderMarkdown(CoverageGateResult result)
Source
Renders the Markdown gate report.
resultCoverage gate result.Markdown report content.
Validates coverage report output paths before report writers create or replace files.
The coverage gate writes only two report files, but it still refuses unsafe destinations so future run/merge cleanup behavior can share the same conservative policy.
void ValidateReportOutput(string coveragePath, string outputDirectory)
Source
Validates that the report output directory is distinct from the coverage file and safe to create.
coveragePathCoverage file path being read.outputDirectoryReport output directory to validate.CommandExceptionThrown when the output path is dangerous or overlaps the input file.Internal CLI entry point that adds a scoped test seam around AppSurfaceCliApp.
Production code uses RunAsync directly. Tests can use PushConfigureOptionsOverrideForTests to add temporary console or DI overrides without changing the top-level statement in Program.cs.
Task RunAsync(string[] args, Action<ConsoleOptions>? configureOptions = null)
Source
Runs the AppSurface CLI with the specified arguments and optional console configuration.
argsCommand-line arguments to parse and execute.configureOptionsOptional primary console-options callback for the current invocation.A task that represents the CLI execution.
IDisposable PushConfigureOptionsOverrideForTests(Action<ConsoleOptions> configureOptions)
Source
Pushes a test-only console-options override for the current async context.
configureOptionsOverride callback to apply after any direct invocation callback.A disposable scope that restores the previous override when disposed.
Always dispose the returned scope, typically with using var. Overrides compose with RunAsync callbacks in direct-then-override order so tests can replace services after production defaults are configured.
Restores the previously active test override when disposed.
previousOverride that was active before the current scope was pushed.Provides the discoverable root for AppSurface local secret commands.
ValueTask ExecuteAsync(IConsole console)
Source
Prints the local secrets command family summary.
consoleCliFx console used for command output.A completed task.
Initializes or verifies a LocalSecrets namespace.
Writes a local secret value.
string? Value { get; set; }
Source
Gets or sets the secret value.
bool ReadFromStandardInput { get; set; }
Source
Gets or sets a value indicating whether to read the secret value from standard input.
Verifies a local secret exists without printing its value.
Lists currently retrievable local secret names in a namespace.
bool NamesOnly { get; set; }
Source
Gets or sets a value indicating whether to print only secret names.
Deletes one local secret.
Diagnoses LocalSecrets platform availability.
Shared options and helpers for local secret commands.
ValueTask ExecuteAsync(IConsole console)
Source
Executes the command.
consoleCliFx console used for command output.A value task that completes when the command finishes.
SecretsCommandContext BuildContext()
Source
Builds a normalized command context.
The command context.
IAppSurfaceLocalSecretStore CreatePlatformStore(AppSurfaceLocalSecretsOptions options)
Source
Creates the OS-backed LocalSecrets store for commands that do not use the deterministic file store.
optionsOptions derived from the CLI command line.The platform-backed local secret store.
ValueTask WriteResultAsync(IConsole console, AppSurfaceLocalSecretResult result, string successVerb)
Source
Writes a command result.
consoleCliFx console used for command output.resultThe local secret result.successVerbThe success verb to display.A value task that completes when output is written.
LocalSecrets treats LocalSecretResultStatus.Missing as failure everywhere except doctor-style readiness probes that return a ready-class posture diagnostic. Keep that exception explicit when adding commands so ordinary missing secrets do not report success.
string ApplicationName { get; set; }
Source
Gets or sets the AppSurface application identity.
string EnvironmentName { get; set; }
Source
Gets or sets the AppSurface environment identity.
string? KeyPrefix { get; set; }
Source
Gets or sets an optional LocalSecrets key prefix.
string? StoreFile { get; set; }
Source
Gets or sets an optional file-backed store path for deterministic examples and tests.
string? SecretToolPath { get; set; }
Source
Gets or sets an explicit Linux secret-tool executable path for nonstandard trusted installs.
Shared options for commands that target one local secret key.
AppSurfaceLocalSecretIdentity Normalize(SecretsCommandContext context)
Source
Normalizes the configured key into a local secret identity.
contextThe command context.The local secret identity.
string Key { get; set; }
Source
Gets or sets the AppSurface config key.
Captures normalized command state.
NormalizerIdentity normalizer.StoreLocal secret store.ApplicationNameNormalized application identity.EnvironmentNormalized environment identity.KeyPrefixNormalized optional key prefix.Previews AppSurface Docs for a local repository through the public appsurface docs command.
This command starts the AppSurface Docs standalone host with CLI-friendly defaults and delegates option validation and argument construction to AppSurfaceDocsPreviewCommand.
Previews AppSurface Docs for a local repository through the appsurface docs preview alias.
Use this alias when a command hierarchy reads better in scripts. It has the same options and behavior as DocsCommand.
Exports AppSurface Docs for a local repository through the appsurface docs export command.
This command owns the AppSurface Docs source-host lifecycle and delegates static crawling, URL rewriting, CDN validation, and materialization to the RazorWire export engine.
ValueTask ExecuteAsync(IConsole console)
Source
Executes the command through the CliFx console integration.
consoleConsole abstraction used to register cancellation handling.A value task that completes when export finishes or command validation fails.
ValueTask ExecuteAsync(CancellationToken cancellationToken)
Source
Executes the command using an explicit cancellation token.
cancellationTokenToken observed while starting the host and exporting static output.A value task that completes when export finishes.
AppSurfaceDocsExportArgs BuildExportArgs()
Source
Translates CLI options into an AppSurface Docs export invocation.
The export runner arguments.
Export defaults to Production and binds a loopback ephemeral port internally. It does not expose preview's --urls or --port options because humans and CI should not manage export listener ports.
IReadOnlyList<string> BuildDefaultSeedRoutes()
Source
Builds the default export seed routes from the resolved AppSurface Docs routing options.
The root route plus the live docs root, with duplicates removed.
string OutputPath { get; set; }
Source
Gets the directory where static docs files will be written.
Defaults to dist/docs for local use. CI should pass an explicit output path so upload artifacts and export output stay tied together.
ExportMode Mode { get; set; }
Source
Gets the export mode used by the underlying RazorWire exporter.
ExportMode.Cdn validates and rewrites output for static CDN hosting. ExportMode.Hybrid preserves application-style internal URLs for server-backed deployments.
string? LiveOrigin { get; set; }
Source
Gets the live origin used for RazorWire-managed live references in hybrid exports.
This option is only needed for split-origin hybrid output. The value must be an absolute http or https origin with no path, query string, fragment, or userinfo. When configured, RazorWire-owned live surfaces such as streams, islands, and lazy anti-forgery form posts are rewritten to this origin while docs navigation and canonical routes remain on the static docs host. Leave it unset when the published docs and live app share an origin.
RazorWireHybridCredentialsMode HybridCredentials { get; set; }
Source
Gets credential behavior for RazorWire-managed live references.
Defaults to RazorWireHybridCredentialsMode.Auto, which includes credentials when LiveOrigin is set and omits them otherwise. Choose RazorWireHybridCredentialsMode.Include for cookie-backed live docs interactions across origins. Choose RazorWireHybridCredentialsMode.Omit only for public live endpoints that do not need cookies or lazy anti-forgery token refresh.
ExportRedirectStrategy RedirectStrategy { get; set; }
Source
Gets the redirect alias materialization strategy used by the underlying RazorWire exporter.
ExportRedirectStrategy.Html is the default and works on GitHub Pages and generic static hosts by writing alias HTML fallback files. ExportRedirectStrategy.Netlify writes a root _redirects file for Netlify-compatible CDN hosting and is valid only with ExportMode.Cdn.
string? SeedRoutesPath { get; set; }
Source
Gets an optional path to a seed-route file.
This option is long-only because -r is reserved for --repo across AppSurface docs commands. When omitted, export derives default seeds from the configured docs routing surface.
Verifies one catalog-pinned AppSurface Docs release archive without starting a web host.
This command exercises the same catalog and archive verification path used at runtime so operators can diagnose manifest, digest, and file drift locally before deploying a version catalog change.
ValueTask ExecuteAsync(IConsole console)
Source
Executes the command through the CliFx console integration.
consoleConsole abstraction used to register cancellation handling.A value task that completes after archive verification.
string? CatalogPath { get; set; }
Source
Gets the path to the AppSurface Docs version catalog JSON file.
string? Version { get; set; }
Source
Gets the version identifier to verify from the catalog.
string? TrustedReleaseRootPath { get; set; }
Source
Gets the trusted release root used to resolve catalog exactTreePath entries.
Verifies AppSurface Docs harvest health for CI and release gates.
This command loads the standalone docs host service graph, reads the same redacted health response shape as the JSON endpoint, and fails when the machine-checkable health response is not OK.
ValueTask ExecuteAsync(IConsole console)
Source
Executes the command through the CliFx console integration.
consoleConsole abstraction used to register cancellation handling.A value task that completes when verification finishes.
ValueTask ExecuteAsync(CancellationToken cancellationToken)
Source
Executes the command using an explicit cancellation token.
cancellationTokenToken observed while loading host services and reading harvest health.A value task that completes when verification finishes.
AppSurfaceDocsHealthVerifyArgs BuildVerifyArgs()
Source
Translates CLI options into a one-shot harvest-health verification invocation.
The health verification runner arguments.
bool RequireCompleteEventDoclets { get; set; }
Source
Gets a value indicating whether public JavaScript event doclets must include complete event contract fields.
This forwards AppSurfaceDocs:Harvest:JavaScript:RequireCompleteEventDoclets=true into the verification host without changing runtime startup failure semantics.
bool VerifyEventDispatches { get; set; }
Source
Gets a value indicating whether public JavaScript event doclets should be compared with literal CustomEvent dispatch evidence.
This forwards AppSurfaceDocs:Harvest:JavaScript:VerifyEventDispatches=true into the verification host. Mismatches remain warning-only diagnostics; the command prints them on successful verification runs.
Shared implementation for AppSurface Docs preview commands.
The base command translates CLI options into AppSurface Docs standalone host arguments. It keeps command parsing separate from process hosting so tests can verify validation and argument forwarding without starting Kestrel.
ValueTask ExecuteAsync(IConsole console)
Source
Executes the command through the CliFx console integration.
consoleConsole abstraction used to register cancellation handling.A value task that completes when the preview host exits or command validation fails.
ValueTask ExecuteAsync(CancellationToken cancellationToken)
Source
Executes the command using an explicit cancellation token.
cancellationTokenToken observed before the host runner starts.A value task that completes when the preview host exits.
This overload exists for tests and shared command execution paths that already own cancellation registration.
string? Urls { get; set; }
Source
Gets the explicit URL binding forwarded to the AppSurface Docs host.
Use this for a full Kestrel binding such as http://127.0.0.1:5189. Prefer Port when only the port needs to change.
int? Port { get; set; }
Source
Gets the port shortcut forwarded to the AppSurface Docs host.
Use this for local preview scripts that only need a port override. Use Urls for explicit host, scheme, or multi-binding scenarios.
bool AllHosts { get; set; }
Source
Gets a value indicating whether the port shortcut should bind all hosts instead of localhost only.
Use this only with Port when LAN, container, or other non-loopback preview access is intentional.
Shared repository, routing, environment, and startup-timeout options for AppSurface docs commands.
Preview and export share these options so route and source configuration cannot drift. Preview adds listener binding options, while export keeps listener management internal and adds output/export options instead.
AppSurfaceDocsHostArgs BuildHostArgs(string? defaultEnvironmentName)
Source
Translates shared CLI options into standalone AppSurface Docs host arguments.
defaultEnvironmentNameEnvironment to use when EnvironmentName is blank.The repository root, forwarded host arguments, startup timeout, and resolved environment.
AppSurfaceDocsHostArgs BuildHostArgs(string? urls, int? port, bool allHosts, string? defaultEnvironmentName)
Source
Translates shared and preview-only CLI options into standalone AppSurface Docs host arguments.
urlsOptional explicit preview URL binding.portOptional preview port shortcut.allHostsWhether the preview port shortcut should bind all hosts instead of localhost only.defaultEnvironmentNameEnvironment to use when EnvironmentName is blank.The repository root, forwarded host arguments, startup timeout, and resolved environment.
string RepositoryRoot { get; set; }
Source
Gets the repository root to harvest.
Defaults to the current directory. Use this when running the CLI from a parent directory, script workspace, or package output folder. The value must resolve to an existing directory.
bool StrictHarvest { get; }
Source
Gets a value indicating whether startup should fail when every configured AppSurface Docs harvester fails.
string? RouteRootPath { get; set; }
Source
Gets the route-family root for AppSurface Docs version and archive routes.
Use this when the docs route family is mounted somewhere other than /docs, for example --route-root /reference. Pair it with DocsRootPath when the live docs path should differ from archive/version routes.
string? DocsRootPath { get; set; }
Source
Gets the live docs root path.
Use this to serve current docs under a nested route, for example --route-root /reference --docs-root /reference/next. Leave unset to use AppSurface Docs defaults.
string? PublicOrigin { get; set; }
Source
Gets the public origin used for absolute AppSurface Docs canonical metadata.
Use this for published docs exports when the public host is known, for example --public-origin https://docs.example.com. Configure only the origin; route paths such as /docs come from RouteRootPath and DocsRootPath.
string? EnvironmentName { get; set; }
Source
Gets the host environment forwarded to the AppSurface Docs standalone host.
Preview defaults to Development so the host can use deterministic per-workspace local endpoints. Export defaults to Production before starting the in-process host.
double StartupTimeoutSeconds { get; set; }
Source
Gets the number of seconds to wait for the web host to start before failing fast.
Defaults to 10 seconds. Set to 0 to disable the startup watchdog. Negative, infinite, and NaN values are rejected before the host starts.
Restores the previous process current directory when disposed.
The standalone host resolves some relative paths from the current directory, so preview and export temporarily scope it to the repository root while the host runs.
CurrentDirectoryScope ChangeTo(string directory)
Source
Changes the process current directory and returns a scope that restores the previous value.
directoryDirectory to make current for the scope lifetime.A disposable scope that restores the previous current directory.
void Dispose()
Source
Restores the current directory captured when the scope was created.
Shared repository command options for AppSurface docs commands that expose strict harvest startup behavior.
bool StrictHarvestEnabled { get; set; }
Source
Gets or sets a value indicating whether startup should fail when every configured AppSurface Docs harvester fails.
This is a source-harvest fail-closed gate. Static artifact validation is controlled separately by docs export --mode cdn. The option is intentionally omitted from docs verify-health, which keeps startup permissive and evaluates the health endpoint response instead.
Describes the AppSurface Docs host invocation produced by the CLI option translator.
RepositoryRootAbsolute repository root that the AppSurface Docs host should harvest.ArgsCommand-line arguments forwarded to the standalone AppSurface Docs host.StartupTimeoutStartup watchdog timeout, or null when disabled.EnvironmentNameResolved host environment, or null when the host should use its default.Describes a one-shot AppSurface Docs static export request.
HostArgsStandalone AppSurface Docs host arguments.OutputPathAbsolute output directory for exported files.SeedRoutesPathOptional absolute seed-route file path.InitialSeedRoutesOptional in-memory seed routes used when SeedRoutesPath is null.ModeRazorWire static export mode.RedirectStrategyRedirect alias materialization strategy carried into the RazorWire export context. ExportRedirectStrategy.Html is the command default and writes portable fallback HTML pages for source-shaped aliases. Use ExportRedirectStrategy.Netlify only with ExportMode.Cdn when publishing to Netlify or a compatible host that reads a root _redirects file; export rejects that provider strategy with ExportMode.Hybrid because the generated rules target publish-root static routes. The selected strategy affects only alias materialization after the loopback host is crawled from RequestedBaseUrl.RequestedBaseUrlLoopback URL passed to Kestrel. The default uses port 0 so the OS chooses a free port.HybridOptionsOptional split-origin hybrid settings forwarded into the RazorWire export context.Describes a one-shot AppSurface Docs harvest-health verification request.
HostArgsStandalone AppSurface Docs host arguments.HealthJsonPathApp-relative health JSON path represented by this verification run.RequestedBaseUrlLoopback URL passed to Kestrel. The default uses port 0 so the OS chooses a free port.Result returned by the AppSurface Docs harvest-health verification runner.
HealthParsed health response from the docs host.HttpStatusCodeHTTP status code that the health endpoint would return for this health response.Raw HTTP response returned by the AppSurface Docs harvest-health client seam.
StatusCodeHTTP status returned by the health endpoint.BodyResponse body read from the health endpoint.Applies shared host options required by packaged AppSurface docs tooling.
void ConfigurePackagedToolHost(WebOptions options, TimeSpan? startupTimeout)
Source
Configures the standalone AppSurface Docs host shape used by packaged preview and export commands.
optionsWeb startup options to mutate.startupTimeoutStartup watchdog timeout, or null when disabled.void ConfigureQuietPreviewLogging(ILoggingBuilder logging)
Source
Suppresses routine ASP.NET Core host lifecycle output for interactive AppSurface Docs preview runs.
loggingLogging builder for the preview host.The CLI prints the resolved docs URL itself after Kestrel starts, so routine messages such as Now listening on, Application started, AppSurface Web's endpoint fallback note, and routine docs harvest summaries would duplicate that command-owned status. Warnings and errors remain visible so startup and request failures are not hidden.
Starts a AppSurface Docs host for CLI preview commands.
This seam keeps command parsing and validation testable without starting a real web host. Production implementations should honor cancellation before delegating into long-running host lifetimes.
Task RunAsync(string[] args, TimeSpan? startupTimeout, CancellationToken cancellationToken)
Source
Runs the AppSurface Docs host with translated command-line arguments.
argsArguments forwarded to the standalone AppSurface Docs host.startupTimeoutStartup watchdog timeout, or null to disable it.cancellationTokenToken that cancels before the host is started.A task that completes when the host exits.
Starts the AppSurface Docs host and exports it to static files.
Task ExportAsync(AppSurfaceDocsExportArgs args, CancellationToken cancellationToken)
Source
Starts the docs host, runs static export, and stops the host.
argsResolved export arguments.cancellationTokenToken observed during host startup and export.A task that completes when export finishes.
Loads the AppSurface Docs host service graph and verifies the redacted harvest-health response.
Task<AppSurfaceDocsHealthVerificationResult> VerifyAsync(AppSurfaceDocsHealthVerifyArgs args, CancellationToken cancellationToken)
Source
Starts the docs host, reads harvest health, and stops the host.
argsResolved verification arguments.cancellationTokenToken observed during host startup and health retrieval.The parsed harvest-health verification result.
Reads the AppSurface Docs harvest-health JSON endpoint.
Task<AppSurfaceDocsHealthHttpResponse> GetAsync(string url, CancellationToken cancellationToken)
Source
Requests a redacted health JSON URL and returns the body regardless of success or failure HTTP status.
urlAbsolute health JSON URL.cancellationTokenToken observed by the HTTP request.The HTTP status and body.
Builds and starts the AppSurface Docs host used by harvest-health verification.
Task<IHost> BuildAndStartAsync(AppSurfaceDocsHealthVerifyArgs args, string environmentName, CancellationToken cancellationToken)
Source
Builds the standalone docs host, starts Kestrel, and returns the started host for health verification.
argsResolved verification arguments.environmentNameResolved host environment.cancellationTokenToken observed while starting the host.The started host.
Adapts the RazorWire static exporter behind a small AppSurface CLI test seam.
Task ExportAsync(ExportContext context, CancellationToken cancellationToken)
Source
Exports the started docs host described by context.
contextRazorWire export context.cancellationTokenToken observed by the export operation.A task that completes when export finishes.
Adds AppSurface Docs-specific export graph state after the host starts and before RazorWire crawls it.
Task ConfigureAsync(IHost host, ExportContext context, CancellationToken cancellationToken)
Source
Configures the export context using services from the started docs host.
hostStarted AppSurface Docs host.contextExport context to configure.cancellationTokenToken observed while resolving host state.A task that completes after context configuration.
Production IAppSurfaceDocsHostRunner that delegates to the standalone AppSurface Docs web host.
Use this adapter for the packaged AppSurface CLI path. Tests should prefer fake runners so they can verify argument translation without starting Kestrel. The type is internal and sealed because callers should depend on IAppSurfaceDocsHostRunner rather than subclassing host lifetime behavior.
Shared exception classification helpers used by command cleanup and best-effort diagnostics.
bool IsNonFatal(Exception ex)
Source
Determines whether an exception is safe to catch for cleanup, fallback logging, or diagnostic reporting.
exException to classify.true when the exception is non-fatal and can be handled locally.
Reads a command-owned harvest summary from a started AppSurface Docs preview host.
Task<AppSurfaceDocsHarvestSummary?> ReadAsync(IHost host, CancellationToken cancellationToken)
Source
Reads the current docs harvest summary if the started host exposes the AppSurface Docs aggregator.
hostStarted preview host.cancellationTokenToken observed while waiting for the first cached docs snapshot.A summary when available; otherwise null.
Concise harvest summary emitted by the AppSurface Docs CLI preview command.
StatusAggregate harvest status.TotalDocsNumber of final documentation nodes in the cached snapshot.TotalHarvestersNumber of active harvesters that participated in the snapshot.SuccessfulHarvestersNumber of harvesters that completed successfully.DiagnosticCountNumber of structured harvest diagnostics in the snapshot.Production IAppSurfaceDocsHarvestSummaryReader that reads DocAggregator health.
Describes a preview AppSurface Docs host startup request.
ArgsArguments forwarded to the standalone AppSurface Docs host.StartupTimeoutStartup watchdog timeout, or null when disabled.Builds and starts the AppSurface Docs preview host.
Task<IHost> BuildAndStartAsync(AppSurfaceDocsPreviewHostArgs args, CancellationToken cancellationToken)
Source
Builds the standalone docs host, starts Kestrel, and returns the started host for preview.
argsResolved preview arguments.cancellationTokenToken observed while starting the host.The started host.
Production IAppSurfaceDocsPreviewHostStarter that uses the AppSurface Docs standalone host builder.
Attempts to open the preview docs URL in the user's browser.
Task<AppSurfaceDocsBrowserLaunchResult> TryOpenAsync(Uri url, CancellationToken cancellationToken)
Source
Attempts to open url in the user's browser without failing the preview command.
urlAbsolute docs URL to open.cancellationTokenToken observed before launch.The browser launch outcome.
Describes the outcome of an attempted browser launch.
SucceededWhether a platform launch command was started successfully.FailureReasonUser-facing failure detail when Succeeded is false.AppSurfaceDocsBrowserLaunchResult Failure(string reason)
Source
Creates a failed browser-launch result.
reasonUser-facing failure detail.A failed browser-launch result.
AppSurfaceDocsBrowserLaunchResult Success { get; }
Source
Gets a successful browser-launch result.
Browser launcher that uses the current operating system's conventional URL opener.
Runs the platform command that asks the operating system to open a browser URL.
Task OpenAsync(Uri url, CancellationToken cancellationToken)
Source
Opens the given URL with the platform opener command.
urlAbsolute URL to open.cancellationTokenToken observed while starting the opener command.A task that completes when the opener command exits.
CliWrap-backed IAppSurfaceDocsBrowserOpenCommandRunner implementation.
Resolves browser-facing URLs for AppSurface Docs preview hosts.
string ResolveRepositoryRoot(IReadOnlyList<string> args, string fallbackRoot)
Source
Resolves the repository root forwarded to the standalone host.
argsArguments forwarded to the standalone host.fallbackRootFallback root used when the forwarded arguments do not contain a repository root.The forwarded repository root when present; otherwise fallbackRoot.
string? ResolveDefaultPreviewUrl(IReadOnlyList<string> args, string repositoryRoot)
Source
Resolves the default preview listener when the CLI invocation did not configure an endpoint explicitly.
argsArguments forwarded to the standalone host.repositoryRootRepository root used as the deterministic-port seed.A localhost URL, or null when explicit endpoint configuration should win.
string ResolveBoundBaseUrl(IHost host)
Source
Resolves the browser-facing base URL from Kestrel's published server addresses.
hostStarted host that exposes Kestrel server addresses.The scheme and authority that should be opened in the browser.
string ResolveBoundBaseUrl(ICollection<string>? addresses)
Source
Resolves the browser-facing base URL from Kestrel's published server addresses.
addressesPublished server addresses.The scheme and authority that should be opened in the browser.
Uri ResolveDocsUrl(string baseUrl, IReadOnlyList<string> args)
Source
Combines the bound host base URL with the configured AppSurface Docs root path.
baseUrlBound host base URL.argsArguments forwarded to the standalone host.The absolute docs page URL to open.
Production export runner that starts the standalone AppSurface Docs host in-process and exports it over real loopback HTTP.
string ResolveBoundBaseUrl(IHost host)
Source
Resolves the single bound loopback base URL published by the started export host.
hostStarted host that exposes Kestrel server addresses.The scheme and authority used by the export crawler.
InvalidOperationExceptionThrown when the host does not publish exactly one valid loopback URL.string ResolveBoundBaseUrl(ICollection<string>? addresses)
Source
Resolves the crawler base URL from a Kestrel address collection.
addressesPublished server addresses.The absolute URL authority to crawl.
InvalidOperationExceptionThrown when no URL, multiple URLs, an invalid URL, or a non-loopback URL is published.Task<IHost> BuildAndStartHostWithTimeoutAsync(AppSurfaceDocsExportArgs args, string environmentName, CancellationToken cancellationToken)
Source
Builds and starts the docs host while enforcing the configured startup watchdog.
argsResolved export arguments.environmentNameEnvironment name applied to the standalone host.cancellationTokenExternal cancellation token for the export operation.The started host.
TimeoutExceptionThrown when the host does not start before the startup timeout.StartupTimeoutCancellationLease CreateStartupTimeout(TimeSpan startupTimeout, CancellationToken cancellationToken)
Source
Creates the linked cancellation source used to distinguish startup timeout from external cancellation.
startupTimeoutStartup timeout to enforce.cancellationTokenExternal cancellation token to link.A disposable lease for the linked startup cancellation source.
void ObserveTimedOutStartupTask(Task<IHost> startTask, CancellationTokenSource startupTimeoutCts)
Source
Observes a startup task that outlived the configured timeout so late completion can stop or log the host.
startTaskBackground startup task to observe.startupTimeoutCtsCancellation source transferred from the timeout branch.void ObserveCanceledStartupTask(Task<IHost> startTask, CancellationTokenSource startupTimeoutCts)
Source
Observes a startup task that outlived external cancellation so late completion can stop or log the host.
startTaskBackground startup task to observe.startupTimeoutCtsCancellation source transferred from the external cancellation branch.Task ObserveStartupTaskAsync(Task<IHost> startTask, CancellationTokenSource startupTimeoutCts, string lateCompletionMessage)
Source
Awaits a late startup task and disposes the host if startup eventually succeeds.
startTaskBackground startup task to observe.startupTimeoutCtsCancellation source owned by the observation task.lateCompletionMessageDebug message used when late startup faults.A task that completes after the late startup task is observed.
TimeoutException CreateStartupTimeoutException(TimeSpan startupTimeout, Exception? innerException)
Source
Creates the user-facing timeout exception for a host that failed to start in time.
startupTimeoutTimeout that elapsed.innerExceptionOptional cancellation exception that came from the startup token.The timeout exception reported to command execution.
Task StopAndDisposeHostAsync(IHost host)
Source
Stops the export host and always disposes it, logging non-fatal shutdown failures.
hostHost to stop and dispose.A task that completes after shutdown and disposal.
Owns a startup cancellation source until timeout observation needs to transfer that ownership.
Task CancelAsync()
Source
Requests cancellation of the owned startup cancellation source.
A task that completes after cancellation callbacks have run.
CancellationTokenSource Transfer()
Source
Transfers cancellation source ownership to a late-startup observer.
The owned cancellation source.
void Dispose()
Source
Disposes the owned cancellation source unless ownership has been transferred.
CancellationToken Token { get; }
Source
Gets the token exposed by the owned startup cancellation source.
Production harvest-health HTTP client used by AppSurfaceDocsInProcessHealthVerifyRunner.
Production IAppSurfaceDocsHealthHostStarter that uses the AppSurface Docs standalone host builder.
Provides a fixed environment name to the standalone host builder during health verification startup.
string? GetEnvironmentVariable(string name, string? defaultValue = null)
Source
Gets environment variable values while overriding ASP.NET and .NET environment variables.
nameEnvironment variable name.defaultValueFallback value when the variable is not set.The fixed host environment for environment-name variables, otherwise the process value or fallback.
string Environment { get; }
Source
Gets the fixed environment name.
bool IsDevelopment { get; }
Source
Gets a value indicating whether the fixed environment is Development.
Starts AppSurface Docs in-process and verifies the redacted harvest-health response over loopback HTTP.
Default AppSurface Docs export configurator that publishes docs route aliases into RazorWire's export graph and captures the frozen route manifest alongside the static output.
Test-seam configurator used when unit tests provide a fake host that does not contain AppSurface Docs services.
Builds and starts the in-process AppSurface Docs export host.
Task<IHost> BuildAndStartAsync(AppSurfaceDocsExportArgs args, string environmentName, CancellationToken cancellationToken)
Source
Builds the standalone docs host, starts Kestrel, and returns the started host for export.
argsResolved export arguments.environmentNameResolved host environment.cancellationTokenToken observed while starting the host.The started host.
Production IAppSurfaceDocsExportHostStarter that uses the AppSurface Docs standalone host builder.
Provides a fixed environment name to the standalone host builder during export startup.
string? GetEnvironmentVariable(string name, string? defaultValue = null)
Source
Gets environment variable values while overriding ASP.NET and .NET environment variables.
nameEnvironment variable name.defaultValueFallback value when the variable is not set.The fixed host environment for environment-name variables, otherwise the process value or fallback.
string Environment { get; }
Source
Gets the fixed environment name.
bool IsDevelopment { get; }
Source
Gets a value indicating whether the fixed environment is Development.
Production IRazorWireStaticExporter that delegates to RazorWire's ExportEngine.
Represents the AppSurface CLI root module used to bootstrap command execution.
The module is intentionally empty today: the CLI owns command registration in AppSurfaceCliApp and delegates web-host behavior to AppSurface Docs-specific runners. Add dependencies here only when every AppSurface CLI command needs the same module-level dependency graph or host lifecycle hook. Prefer command-local services or custom test registrations for isolated behavior, and do not place runtime command logic in this module.
void ConfigureServices(StartupContext context, IServiceCollection services)
Source
Configures shared CLI services after the default command runtime registrations have been added.
contextStartup context for the CLI run.servicesService collection that will back command construction.The default implementation is a no-op. Keep it empty unless a service truly applies to the whole CLI surface.
void ConfigureHostBeforeServices(StartupContext context, IHostBuilder builder)
Source
Configures a Generic Host builder before services are registered.
contextStartup context for the CLI run.builderHost builder that would be configured by host-based startup paths.The command runtime does not currently build a Generic Host through this module, so this hook is intentionally a no-op and exists to satisfy the shared AppSurface host-module contract.
void ConfigureHostAfterServices(StartupContext context, IHostBuilder builder)
Source
Configures a Generic Host builder after services are registered.
contextStartup context for the CLI run.builderHost builder that would be configured by host-based startup paths.Keep this empty until the CLI adopts a host-backed lifecycle. Command behavior should stay in command classes.
void RegisterDependentModules(ModuleDependencyBuilder builder)
Source
Registers root-module dependencies for the AppSurface CLI module graph.
builderDependency builder used by AppSurface startup composition.The CLI has no module dependencies by default. Add dependencies here only for cross-command infrastructure that must participate in AppSurface module ordering.
Provides the DI-backed execution runtime for AppSurface CLI commands.
This internal runtime exists so the top-level tool entry point stays thin while command discovery, dependency registration, logging defaults, and CliFx execution stay testable. It discovers commands from the AppSurface CLI entry assembly, applies module and caller-provided service registrations, temporarily assigns CommandService.PrimaryServiceProvider for constructor-injected command dependencies, and always restores the previous provider after command execution.
Task RunAsync(string[] args, Action<ConsoleOptions>? configureOptions = null)
Source
Runs the AppSurface CLI with the provided command-line arguments.
argsCommand-line arguments to parse and execute.configureOptionsOptional callback that customizes ConsoleOptions before execution. Defaults start from ConsoleOptions.Default with ConsoleOutputMode.CommandFirst so command output remains the primary console experience.A task that completes when the selected command finishes.
Use this seam from process entry points and tests that need the real command pipeline without shelling out. The method builds and disposes a fresh service provider for each run, registers AppSurface CLI defaults, then applies custom registrations last so tests or future host integrations can replace defaults intentionally.
void AddExportEngineServices(IServiceCollection services)
Source
Registers the RazorWire export engine dependencies used by AppSurface-owned export commands.
servicesThe service collection to populate.The named ExportEngine HTTP client disables automatic redirects so artifact-producing requests are surfaced to ExportEngine. The engine then applies its explicit redirect boundary checks before reading or writing redirected response bodies, while source and readiness probes continue to treat surfaced HTTP redirect responses as evidence that an app endpoint is reachable.
void AddPwaVerifierServices(IServiceCollection services)
Source
Registers the HTTP client used by appsurface pwa verify.
servicesThe service collection to populate.Automatic redirects are disabled so the verifier observes the requested manifest, icon, diagnostics, and offline fallback URLs directly. That keeps the verifier's same-origin and base-path checks authoritative instead of letting HttpClient silently follow a redirect outside the app being verified.
Writes best-effort slow-test diagnostic artifacts for coverage run.
WriteAsync may write artifacts twice when aggregation timing changes during the initial write.Task<CoverageRunSlowTestDiagnosticsReport> CollectAsync(IReadOnlyList<CoverageProjectRunResult> results, CancellationToken cancellationToken)
Source
Parses managed JUnit files and builds a diagnostic report.
resultsProject run results with managed test result artifact paths.cancellationTokenCancellation token for artifact reads.Slow-test diagnostic report model.
Task<CoverageRunSlowTestDiagnosticsRun> WriteAsync(string outputDirectory, CoverageRunSlowTestDiagnosticsReport report, Func<long> getAggregationSeconds, Func<long, decimal> calculateAggregationPercent, CancellationToken cancellationToken)
Source
Writes diagnostic artifacts with measured aggregation overhead.
outputDirectoryCoverage output directory.reportReport model returned by CollectAsync.getAggregationSecondsReads elapsed diagnostic aggregation seconds.calculateAggregationPercentCalculates aggregation overhead as a percent of runner time.cancellationTokenCancellation token for artifact writes.Written artifact paths and high-level metadata.
WriteAsync may call WriteArtifactsAsync twice when aggregationSeconds differs from finalAggregationSeconds. The single re-write includes the first file-write cost in reported aggregation overhead; later timing drift is not captured.
Written slow-test diagnostic artifact metadata.
Slow-test diagnostic report before overhead fields are finalized.
Project timing metadata included in slow-test diagnostics.
Best-effort parse result for one managed JUnit file.
Parsed JUnit test case timing included in slow-test diagnostics.
Resolves the AppSurface CLI version string shown by appsurface --version.
The .NET tool package version is the user-facing release identity. Runtime assemblies carry that value through AssemblyInformationalVersionAttribute, sometimes with a leading release-tag v or build metadata. This helper normalizes the display value while preserving prerelease labels so RC installs remain distinguishable from stable packages.
string ResolveDisplayVersion(Assembly assembly)
Source
Resolves the display version from the supplied assembly metadata.
assemblyAssembly whose informational version carries the package identity.A single-line printable version suitable for CliFx --version output.
string NormalizeDisplayVersion(string? informationalVersion)
Source
Normalizes package identity metadata for user-facing CLI version output.
informationalVersionRaw assembly informational version.The package SemVer display value without a leading release-tag v or build metadata, or a truthful fallback when package identity metadata is unavailable.