Private/Diagnostics.ps1

# Local-first diagnostics (in-memory bounded history; export explicitly).
# Not a telemetry service. Never records RPC parameters/results, form data,
# exception messages, paths, URLs or credentials: only fixed event names,
# identifiers, numbers and short [A-Za-z0-9_.:-] tokens survive redaction.
$script:NHKDiagnosticHistory = New-Object 'System.Collections.Generic.Queue[object]'
$script:NHKDiagnosticDropped = [long]0
$script:NHKDiagnosticLimit = 2048
# Same alphabet and length as the Core host accepts, so one ID correlates the
# launcher, the host's stderr records ("diagnostic_session_id") and the backend.
$script:NHKSessionPattern = '^[A-Za-z0-9._:-]{1,128}$'
$script:NHKDiagnosticSessionReplaced = $false
$script:NHKDiagnosticSession = [Environment]::GetEnvironmentVariable('NATIVEHTMLKIT_DIAGNOSTIC_SESSION_ID')
if ([string]::IsNullOrEmpty($script:NHKDiagnosticSession) -or $script:NHKDiagnosticSession -cnotmatch $script:NHKSessionPattern) {
    $script:NHKDiagnosticSessionReplaced = -not [string]::IsNullOrEmpty($script:NHKDiagnosticSession)
    $script:NHKDiagnosticSession = 'nhk-ps-' + [guid]::NewGuid().ToString('N')
    # Inherited by the native host and, through it, by the backend process.
    [Environment]::SetEnvironmentVariable('NATIVEHTMLKIT_DIAGNOSTIC_SESSION_ID', $script:NHKDiagnosticSession)
}

# Allow-lists for identifier-position context values. Anything else in these keys, and any
# string under a key not listed in $script:NHKDiagnosticKeyRules, is exported as [REDACTED]:
# the shape of a value never decides whether caller- or host-supplied text is exported.
$script:NHKProtocolMethods = @(
    'app.activate','app.activated','app.before_quit','app.force_quit','app.ready','app.request_quit','app.shutdown',
    'bitmap.close','bitmap.create','bitmap.present','clipboard.read_text','clipboard.write_text','desktop.open_external',
    'desktop.paths','desktop.preferences','desktop.preferences_changed','desktop.reveal_file','dialog.choose_folder',
    'dialog.open_files','dialog.save_file','document.command','document.error','document.event','document.get',
    'document.load','document.unload','host.capabilities','host.diagnostics','host.hello','probe.get_text','probe.set_text',
    'request.cancel','request.cancelled','window.before_close','window.create','window.event','window.get','window.list',
    'window.request_attention','window.request_close','window.set')
$script:NHKDomEventTypes = @(
    'click','dblclick','auxclick','contextmenu','input','beforeinput','change','submit','reset','invalid','keydown','keyup',
    'focus','blur','focusin','focusout','pointerdown','pointerup','pointermove','pointerover','pointerout','pointerenter',
    'pointerleave','pointercancel','mousedown','mouseup','mousemove','mouseover','mouseout','mouseenter','mouseleave',
    'wheel','scroll','compositionstart','compositionupdate','compositionend','dragstart','drag','dragenter','dragover',
    'dragleave','dragend','drop','toggle','close','cancel','select','selectionchange','copy','cut','paste','error','load')
$script:NHKWindowEventTypes = @('closed','close_requested','focused','resized','moved','dropped_files','dropped_text','text',
    'scale_factor_changed','theme_changed','minimized','maximized','restored')
$script:NHKCallbackRoles = @('document_event','notification','host_request','task_completion')
$script:NHKDiagnosticKeyRules = @{
    method = { param($v) $script:NHKProtocolMethods -ccontains $v }
    event_type = { param($v) $script:NHKDomEventTypes -ccontains $v }
    type = { param($v) $script:NHKWindowEventTypes -ccontains $v }
    role = { param($v) $script:NHKCallbackRoles -ccontains $v }
    exception_type = { param($v) $v -cmatch '^[A-Za-z][A-Za-z0-9]{0,63}$' }
    task_id = { param($v) $v -cmatch '^[0-9a-f]{32}$' }
    window_id = { param($v) $v -cmatch '^[A-Za-z0-9-]{1,24}$' }
    document_id = { param($v) $v -cmatch '^[A-Za-z0-9-]{1,24}$' }
}

function Get-NativeHTMLKitDiagnosticRank {
    param([string]$Level)
    switch (([string]$Level).Trim().ToLowerInvariant()) { 'trace' { 3 } 'debug' { 2 } 'off' { 0 } default { 1 } }
}

function Test-NativeHTMLKitDiagnosticEnabled {
    # Cheap gate so hot paths do not build context tables that would be discarded.
    param([ValidateSet('ERROR','WARN','INFO','DEBUG','TRACE')][string]$Level = 'DEBUG')
    $required = switch ($Level) { 'TRACE' { 3 } 'DEBUG' { 2 } 'INFO' { 2 } default { 1 } }
    return ((Get-NativeHTMLKitDiagnosticRank (Get-NativeHTMLKitSdkDiagnosticLevel)) -ge $required)
}

function Get-NativeHTMLKitSdkDiagnosticLevel {
    # One switch for SDK, host and backend. (The 0.1.0 interim off->normal mapping is gone:
    # Core 1.0.3 relays backend output at every level, NHK-CROSS-0007.)
    return [Environment]::GetEnvironmentVariable('NATIVEHTMLKIT_DIAGNOSTICS')
}

function ConvertTo-NativeHTMLKitSafeValue {
    # Allow-list redaction of one context value. Numbers and booleans are kept; strings only when
    # their key has a rule and the value passes it.
    param([string]$Key, $Value)
    if ($null -eq $Value) { return $null }
    if ($Value -is [bool] -or $Value -is [int] -or $Value -is [long]) { return $Value }
    if ($Value -is [double]) { return [Math]::Round($Value, 3) }
    $rule = $script:NHKDiagnosticKeyRules[$Key]
    if ($null -ne $rule -and (& $rule ([string]$Value))) { return [string]$Value }
    return '[REDACTED]'
}


function Write-NativeHTMLKitDiagnostic {
    [CmdletBinding()]
    param([Parameter(Mandatory)][Alias('Event')][string]$EventName,
          [ValidateSet('ERROR','WARN','INFO','DEBUG','TRACE')][string]$Level = 'DEBUG',
          [hashtable]$Context = @{}, [string]$RequestId, $DurationMs, $ErrorCode)
    # Diagnostics must never throw into application/transport paths.
    try {
        if (-not (Test-NativeHTMLKitDiagnosticEnabled $Level)) { return }
        if ($EventName -cnotmatch '^[A-Za-z][A-Za-z0-9_.-]{0,63}$') { $EventName = 'diagnostics.invalid_event_name' }
        $safe = @{}
        foreach ($key in $Context.Keys) {
            $name = [string]$key
            if ($name -cnotmatch '^[A-Za-z][A-Za-z0-9_.-]{0,63}$') { continue }
            if ($name -match '(?i)token|password|secret|credential|authorization|cookie|api.?key|content|payload|body|html|path|url|text|value|filename|message') {
                $safe[$name] = '[REDACTED]'
            } else {
                $safe[$name] = ConvertTo-NativeHTMLKitSafeValue $name $Context[$key]
            }
        }
        if ($script:NHKDiagnosticHistory.Count -ge $script:NHKDiagnosticLimit) {
            [void]$script:NHKDiagnosticHistory.Dequeue()
            $script:NHKDiagnosticDropped++
        }
        $record = [ordered]@{
            schema_version = 1; timestamp = [DateTime]::UtcNow.ToString('o', [Globalization.CultureInfo]::InvariantCulture)
            session_id = $script:NHKDiagnosticSession; component = 'powershell-sdk'
            pid = $PID; level = $Level; event = $EventName
        }
        if ($RequestId) { $record.request_id = $(if ($RequestId -cmatch '^(ps-[0-9]{1,12}|host:[a-z_]{1,24}:[0-9]{1,12})$') { $RequestId } else { '[REDACTED]' }) }
        if ($null -ne $DurationMs) { $record.duration_ms = [long]$DurationMs }
        if ($null -ne $ErrorCode) { $record.error_code = [long]$ErrorCode }
        $record.context = $safe
        $script:NHKDiagnosticHistory.Enqueue($record)
    } catch { $null = $_ }  # by design: a diagnostics failure must not fail the app
}

function Get-NativeHTMLKitHostLossCounters {
    # Only the numeric loss/capacity counters of host.diagnostics; nothing else from the host.
    param($Application)
    $counters = [ordered]@{}
    $result = Invoke-NativeHTMLKitRpc -Application $Application -Method 'host.diagnostics' -TimeoutMilliseconds 5000
    $source = Get-NativeHTMLKitField $result 'logging' $result
    # dropped_notifications (Core 1.0.3): window/document events the host dropped under backpressure.
    foreach ($name in @('dropped_notifications', 'sink_dropped_records', 'backend_omitted_records', 'sink_capacity_records', 'backend_records_per_pump')) {
        $value = Get-NativeHTMLKitField $source $name
        if ($null -eq $value) { $value = Get-NativeHTMLKitField $result $name }
        if ($value -is [int] -or $value -is [long] -or $value -is [uint64]) { $counters[$name] = [long]$value }
    }
    return $counters
}

function Get-NativeHTMLKitDiagnosticReport {
    <#
    .SYNOPSIS
    Returns local SDK diagnostic counters (session, record and loss counts), optionally for one application.
    .DESCRIPTION
    With -Application the report adds that connection's queue-loss and callback-failure counters and,
    when the host is connected, the host's own logging loss counters (host.diagnostics). Values,
    tokens and paths are never included.
    #>

    [CmdletBinding()]
    param([object]$Application)
    $report = [ordered]@{
        SchemaVersion = 1; SessionId = $script:NHKDiagnosticSession
        Level = Get-NativeHTMLKitSdkDiagnosticLevel
        RecordCount = $script:NHKDiagnosticHistory.Count
        RecordLimit = $script:NHKDiagnosticLimit
        DroppedRecords = $script:NHKDiagnosticDropped
        SessionReplaced = $script:NHKDiagnosticSessionReplaced
    }
    if ($null -ne $Application) {
        if (-not (Test-NativeHTMLKitType $Application 'NativeHTMLKit.Application')) { throw 'Expected a NativeHTMLKit.Application from Connect-NativeHTMLKit' }
        $t = $Application.Transport
        $report.Connection = [ordered]@{
            Closed = $Application.Closed; Disconnected = $Application.Disconnected
            ShutdownRequested = $Application.ShutdownRequested
            ReceivedMessages = $t.ReceivedMessages; PendingRequests = $t.PendingCount
            QueuedMessages = $t.QueuedMessages
            DroppedNotifications = $t.DroppedNotifications; RejectedHostRequests = $t.RejectedRequests
            DeferredDropped = $Application.DroppedNotifications
            CallbackFailures = $Application.CallbackFailures
            ActiveTasks = @(Get-NativeHTMLKitTaskStates $Application | Where-Object { -not $_.Completed }).Count
            CancellationPendingTasks = @(Get-NativeHTMLKitTaskStates $Application | Where-Object { $_.StopRequested -and -not $_.AsyncResult.IsCompleted }).Count
        }
        $report.HostCounters = $null
        $report.HostCountersError = $null
        if (-not $Application.Closed -and -not $Application.Disconnected) {
            try { $report.HostCounters = Get-NativeHTMLKitHostLossCounters $Application }
            catch { $report.HostCountersError = $_.Exception.GetType().Name }
        } else { $report.HostCountersError = 'NotConnected' }
    }
    return [pscustomobject]$report
}

function Export-NativeHTMLKitSupportBundle {
    <#
    .SYNOPSIS
    Saves a local, sanitized diagnostics ZIP (manifest.json, timeline.jsonl) only when called. No upload.
    .DESCRIPTION
    The bundle holds redacted SDK records and counters only: no RPC parameters or results, form
    values, tokens, file paths, screenshots, or raw host/backend stdout/stderr (which may contain
    personal data). -Application adds that connection's loss counters.
    #>

    [CmdletBinding()]
    param([Parameter(Mandatory)][string]$Path, [object]$Application)
    # Resolve against the PowerShell location, not the process working directory.
    $destination = [IO.Path]::GetFullPath($ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($Path))
    if (Test-Path -LiteralPath $destination) { throw "Support bundle already exists: $destination" }
    if (-not $destination.EndsWith('.zip', [StringComparison]::OrdinalIgnoreCase)) { throw 'The support bundle path must end with .zip' }
    $parent = Split-Path -Parent $destination
    if (-not (Test-Path -LiteralPath $parent -PathType Container)) { throw "Destination directory missing: $parent" }
    $report = Get-NativeHTMLKitDiagnosticReport -Application $Application
    $stage = Join-Path ([IO.Path]::GetTempPath()) ('nativehtmlkit-support-' + [guid]::NewGuid().ToString('N'))
    try {
        [void](New-Item -ItemType Directory -Path $stage -Force)
        $manifest = [ordered]@{
            schema_version = 1; session_id = $script:NHKDiagnosticSession
            component = 'powershell-sdk'; module_version = $script:NativeHTMLKitVersion
            record_count = $report.RecordCount; record_limit = $report.RecordLimit
            dropped = $report.DroppedRecords; complete = ($report.DroppedRecords -eq 0); sanitized = $true
            includes_raw_host_output = $false
            diagnostics_level = $(if (@('off', 'normal', 'debug', 'trace') -ccontains ([string]$report.Level).Trim().ToLowerInvariant()) { ([string]$report.Level).Trim().ToLowerInvariant() } else { 'normal' })
            powershell_version = $PSVersionTable.PSVersion.ToString()
            powershell_edition = [string]$PSVersionTable.PSEdition
        }
        if ($report.PSObject.Properties['Connection']) {
            $manifest.connection = $report.Connection
            $manifest.host_counters = $report.HostCounters
            $manifest.host_counters_error = $report.HostCountersError
        }
        $utf8 = New-Object System.Text.UTF8Encoding($false)
        [IO.File]::WriteAllText((Join-Path $stage 'manifest.json'), ($manifest | ConvertTo-Json -Depth 6), $utf8)
        $lines = @($script:NHKDiagnosticHistory.ToArray() | ForEach-Object { ConvertTo-Json -InputObject $_ -Depth 6 -Compress })
        [IO.File]::WriteAllText((Join-Path $stage 'timeline.jsonl'), (($lines -join "`n") + "`n"), $utf8)
        Compress-Archive -Path (Join-Path $stage '*') -DestinationPath $destination -ErrorAction Stop
        return (Get-Item -LiteralPath $destination)
    } finally {
        Remove-Item -LiteralPath $stage -Recurse -Force -ErrorAction SilentlyContinue
    }
}