Cli

Remarks

Public command-line tool entry points need predictable command output for help, validation errors, and export progress. Running the command service directly keeps those flows independent from the Generic Host lifecycle while preserving AppSurface's command registration, dependency injection, and unknown-option suggestions.

Remarks

URL sources are probed for readiness and returned without starting a process. Project sources are published first unless ExportSourceRequest.NoBuild is set, then launched with an ephemeral loopback binding when no explicit URL argument is present. DLL sources are launched directly. The returned ResolvedExportSource must be disposed by the caller so any process launched for the export is stopped after crawling. If the resolver cannot observe a listening URL or the app does not become reachable before the configured timeouts, any launched process is disposed before the exception is rethrown.

Remarks

This seam exists so resolver tests can verify command composition without launching real processes. Callers should treat a non-zero exit as data and decide whether to raise an exception or fall back.

Remarks

MSBuild is preferred because it evaluates imports and conditional properties that raw XML parsing cannot see. If MSBuild exits non-zero, produces no usable stdout, or throws a non-cancellation exception, the resolver logs the failure details and falls back to XML parsing. Omitting framework can mis-evaluate conditional AssemblyName declarations for multi-target projects.

Remarks

This method intentionally does not evaluate imports or conditional MSBuild properties. It is the low-cost fallback used when MSBuild evaluation is unavailable or fails to return a usable value.

Remarks

Calling Start more than once is invalid. Startup failures that occur after the command task is created are surfaced through ErrorLineReceived followed by Exited so callers waiting for a listening URL can report the underlying launch failure instead of a generic readiness timeout.

Remarks

1. Check HasExited when startup completed.
2. If the process is still running, cancel the CliWrap command task. CliWrap translates cancellation into process-tree termination for the launched command.
3. Wait up to 5 seconds for the command task and output pipes to complete before returning.

• Short-lived processes can exit before callers observe their output callbacks, so Exited is raised only after the command task completes and output pipes have drained when possible.
• Cleanup swallows InvalidOperationException, timeout-driven OperationCanceledException, ObjectDisposedException, and recoverable command-task exceptions such as CliWrapException, Win32Exception, or NotSupportedException as part of best-effort disposal.
• Callers must not rely on guaranteed process termination; disposal can return after the 5-second timeout even if the operating system process has not fully exited.

Remarks

Disposing a URL-backed source is a no-op because URL sources are owned by the caller. Disposing a launched source delegates to the owned process once so the temporary app host is stopped after crawling or after a failed export.

Remarks

seed queue
       -> crawl/fetch/discover
       -> validate canonical artifacts and redirect aliases
       -> materialize/rewrite text routes
       -> redirect strategy
            |-- html: write alias HTML fallback artifacts
            `-- netlify: write root _redirects rules

Remarks

StripAppSurfaceDocsDiagnosticsChrome returns null or empty input unchanged, then performs an ordinal case-insensitive marker precheck against AppSurfaceDocsDiagnosticsChromeAttributeName before applying a global Regex.Replace(string, string) with AppSurfaceDocsDiagnosticsChromeRegex. All matching diagnostics disclosures are removed.

The method operates on raw HTML rather than a parsed DOM, so marker-like text in unexpected locations can be removed. The static compiled regex is thread-safe for concurrent exports, but it intentionally trades parser-level correctness for lightweight export-time cleanup and inherits the regex constraints documented on AppSurfaceDocsDiagnosticsChromeRegex.

Remarks

Custom AppSurfaceDocs hosts can mount under route families such as /foo/bar, so export detection cannot rely only on path prefixes. The client config marker covers search and shell pages, while the content frame covers document detail pages.

Remarks

The method intentionally returns ProcessResult for launch/setup failures so callers can preserve command context in their own diagnostics. Arguments are passed to CliWrap as ordered tokens, not as a shell command string. Standard output and standard error remain separate unbounded buffers to preserve the previous Process contract for this CLI slice.

Remarks

CDN and hybrid exports both rewrite static assets to materialized files, but page routes and live routes are validated through their route outcomes instead. This method intentionally keys off Role so supported link hints that resolve to page routes do not become false missing-asset diagnostics. It differs from IsAsset because a reference can be classified as a static asset while an export mode that does not materialize static output would not require missing-asset validation.

Remarks

Host integrations should call this only when the output tree is intended to satisfy the AppSurface Docs exact release archive contract. The exporter then writes .appsurface-docs-release-manifest.json and populates ReleaseArchiveManifest with the digest that should be pinned in trusted catalog configuration.

Remarks

This API is intended for hosts that know route aliases before crawling starts. The export engine validates registered aliases before materialization so collisions and missing canonical artifacts fail early. The selected RedirectStrategy controls whether aliases become HTML fallback artifacts or provider redirect rules, so source-shaped aliases do not become duplicate public pages.

Remarks

This compatibility wrapper preserves the original artifact-oriented API name. New host integrations should call AddRedirectAlias so code describes the route relationship instead of the selected materialization strategy.

Remarks

Use this when a host already knows its public route graph. The export engine validates, normalizes, and de-duplicates registered routes during the seed queue phase. Query strings and fragments follow the same rules as other seed sources, but host-specific route manifests should generally register clean canonical paths.

Remarks

Deployment extras are explicit single files for host metadata such as GitHub Pages CNAME files. They are validated with the same rules as CLI manifest entries, never overwrite generated exporter output, and are incompatible with exact AppSurface Docs release archive exports. Raw provider-owned files such as /_redirects and /_headers are reserved so future structured provider support can remain exporter-owned.

Remarks

This overload exists for internal call paths that already produced an ExportDeploymentExtra instance. It still enforces case-insensitive publish-path uniqueness using StringComparison.OrdinalIgnoreCase; callers should not register duplicate publish-root targets.

Remarks

Use this for string materialization paths such as route manifests, redirects, and release manifests. The route and artifact path are diagnostic context only; the output path boundary is still enforced by ExportOutputPathGuards after the auth audit passes.

Remarks

The byte payload is decoded for audit using the declared charset when available, then UTF-8 and Windows-1252 fallbacks. The exact input bytes are written only after all decoded representations pass, which keeps legacy encoded text stable while preserving fail-closed auth leak detection.

Remarks

The audit checks raw text plus HTML-decoded and JSON-unescaped forms so escaped private auth markers cannot hide in search payloads, manifests, JavaScript strings, or copied text extras. Diagnostics intentionally name the reason label and artifact kind without echoing sensitive policy, subject, claim, or persona values.

Remarks

Pass a declared encoding from the HTTP charset when known. Unknown or unsupported charsets are ignored by ResolveDeclaredEncoding(string?) so the UTF-8 and Windows-1252 audit fallbacks still run.

Remarks

This method follows explicit HTTP and extension signals. Use ShouldAuditLocalTextArtifact(string) for final inventory or local-copy scans where extensionless artifacts are also text candidates.

Remarks

Final inventory treats extensionless files as auditable because static routes commonly materialize without file extensions. Callers must pass the concrete output path that will be written or scanned.

Remarks

Returns null for missing, invalid, or unsupported charsets so audit callers can continue with default decoding fallbacks instead of treating a bad charset as permission to skip validation.

Remarks

Exactly one of baseUrl, projectPath, or dllPath must be provided. URL sources must be absolute HTTP(S) URLs. Project and DLL sources must have the expected extension and must already exist on disk. Prefer this factory for CLI and host-facing option binding so source-specific parameters do not accidentally affect the wrong source kind.

Remarks

The export pipeline needs a concrete ExportReferenceKind.ScriptSrc reference even when a host relies on the <rw:scripts /> lazy detector instead of rendering section-copy.js eagerly. This method first skips documents that already reference /razorwire/section-copy.js in any script src, using case-insensitive matching so versioned or path-base-qualified runtime URLs are treated as already materialized. It then looks for data-rw-section-copy or data-rw-section-copy-target markers, prefers the autoload script's own encoded source assignment when present, and otherwise injects the default RazorWire runtime path with HTML provenance from the first marker.

Remarks

The exporter first honors any explicit form-interactions.js script tag, then prefers the inline autoload block's source value when the lazy detector is present, and finally falls back to the managed package path. This order preserves host-owned eager loading while still materializing the split runtime for exported pages that rely on <rw:scripts /> lazy loading. The scan is intentionally limited to top-level form-toggle and form-collection markers; malformed collection templates remain runtime diagnostics rather than export blockers.

Remarks

Implementations should avoid throwing for ordinary process start failures so higher-level callers can decide whether to surface an exception, retry, or fall back. Cancellation should still propagate via OperationCanceledException.