firmwareloop 0.0.8__py3-none-any.whl

tools/common/fw.psm1

@@ -0,0 +1,311 @@
+# fw.psm1 - FirmwareLoop: shared helpers for PowerShell tools.
+# Provides: unified JSON result envelope, Error Class registry (Spec §22),
+# python/venv resolution, log saving, compiler diagnostics parsing.
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+# --- Error Classes (Spec §22 + v0.0.2 §24 additions) --------------------------
+$script:FW_ERROR_CLASSES = @(
+    'BUILD_ERROR', 'ARTIFACT_NOT_FOUND', 'PROBE_NOT_FOUND', 'TARGET_MISMATCH',
+    'FLASH_ERROR', 'FLASH_VERIFY_ERROR', 'RESET_ERROR', 'UART_TIMEOUT',
+    'UART_BUSY', 'CAN_ERROR', 'DEBUGGER_ERROR', 'LOGIC_CAPTURE_ERROR',
+    'INSTRUMENT_NOT_FOUND', 'INSTRUMENT_TIMEOUT', 'MEASUREMENT_OUT_OF_RANGE',
+    'TEST_FAILED', 'PERMISSION_DENIED', 'SAFETY_LIMIT', 'CONFIG_ERROR',
+    'UNKNOWN_ERROR',
+    # v0.0.2 additions (Gap spec §24)
+    'CAPABILITY_NOT_SUPPORTED', 'DEPENDENCY_DISCOVERY_REQUIRED',
+    'HARDWARE_GATE_BYPASSED', 'REAL_HARDWARE_REQUIRED', 'HARDWARE_VALIDATION_FAILED'
+)
+
+# --- JSON output --------------------------------------------------------------
+function Write-FwJson {
+    <#
+    .SYNOPSIS
+        Emit a structured result as JSON. Always UTF-8; deep serialization.
+    #>
+    param(
+        [Parameter(Mandatory = $true)] $Object,
+        [switch]$Compact
+    )
+    $depth = 20
+    if ($Compact) {
+        $json = $Object | ConvertTo-Json -Depth $depth -Compress
+    } else {
+        $json = $Object | ConvertTo-Json -Depth $depth
+    }
+    [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+    Write-Output $json
+}
+
+function Get-FwErrorClass {
+    <#
+    .SYNOPSIS
+        Validate that a string is a legal Error Class (Spec §22).
+    #>
+    param([Parameter(Mandatory = $true)][string]$Name)
+    if ($Name -notin $script:FW_ERROR_CLASSES) {
+        throw "Illegal error class '$Name'. Allowed: $($script:FW_ERROR_CLASSES -join ', ')"
+    }
+    return $Name
+}
+
+function New-FwError {
+    <#
+    .SYNOPSIS
+        Deterministic failure envelope. Every external-process failure must
+        return one of these (Spec Rule: every operation returns structured errors).
+    #>
+    param(
+        [Parameter(Mandatory = $true)][string]$ErrorClass,
+        [Parameter(Mandatory = $true)][string]$Message,
+        [string]$Detail = $null,
+        [int]$ExitCode = 1
+    )
+    Get-FwErrorClass $ErrorClass | Out-Null
+    $body = [ordered]@{
+        ok          = $false
+        error_class = $ErrorClass
+        error       = $Message
+    }
+    if ($Detail) { $body.detail = $Detail }
+    [pscustomobject]$body
+}
+
+# --- Python / venv resolution -------------------------------------------------
+function Resolve-FwPython {
+    <#
+    .SYNOPSIS
+        Locate a project Python: prefer .venv\Scripts\python.exe relative to
+        repo root, then PATH. Never hardcoded absolute paths (Spec §25).
+    #>
+    param([string]$RepoRoot)
+    $candidates = @()
+    if ($RepoRoot) {
+        $candidates += (Join-Path $RepoRoot '.venv\Scripts\python.exe')
+        $candidates += (Join-Path $RepoRoot 'venv\Scripts\python.exe')
+    }
+    foreach ($path in $candidates) {
+        if (Test-Path -LiteralPath $path) { return (Resolve-Path -LiteralPath $path).Path }
+    }
+    $fromPath = Get-Command python -ErrorAction SilentlyContinue
+    if ($fromPath) { return $fromPath.Source }
+    return $null
+}
+
+function Get-FwRepoRoot {
+    <#
+    .SYNOPSIS
+        Root of the firmware project = directory containing tools/ and lab/.
+    #>
+    $cur = Get-Location
+    while ($cur) {
+        if ((Test-Path (Join-Path $cur 'tools')) -and (Test-Path (Join-Path $cur 'lab'))) {
+            return $cur.Path
+        }
+        $cur = $cur.Parent
+    }
+    return (Get-Location).Path
+}
+
+function Save-FwLog {
+    <#
+    .SYNOPSIS
+        Append text to a log file under artifacts/logs/ (creates dirs).
+    #>
+    param(
+        [Parameter(Mandatory = $true)][AllowEmptyString()][string]$Path,
+        [Parameter(Mandatory = $true)][AllowEmptyString()][string]$Content
+    )
+    $dir = Split-Path -Parent $Path
+    if ($dir -and -not (Test-Path -LiteralPath $dir)) {
+        New-Item -ItemType Directory -Force -Path $dir | Out-Null
+    }
+    if ($Content -eq '') { $Content = "`n" }
+    Add-Content -LiteralPath $Path -Value $Content -Encoding utf8
+}
+
+function Get-FwTimestamp {
+    return (Get-Date).ToString('yyyy-MM-ddTHH:mm:sszzz')
+}
+
+function Get-FwRunId {
+    <#
+    .SYNOPSIS
+        run_id like "20260817-a81f" (Spec §19).
+    #>
+    $stamp = Get-Date -Format 'yyyyMMddHHmmss'
+    $rand = -join ((97..122) | Get-Random -Count 4 | ForEach-Object { [char]$_ })
+    return "$stamp-$rand"
+}
+
+function Get-FwGitInfo {
+    <#
+    .SYNOPSIS
+        {commit, dirty} for audit purposes. Never fails the caller when
+        the directory is not a git repo.
+    #>
+    param([string]$RepoRoot)
+    $info = [ordered]@{ commit = $null; dirty = $true }
+    if (-not $RepoRoot) { return [pscustomobject]$info }
+    $commit = git -C $RepoRoot rev-parse --short HEAD 2>$null
+    if ($LASTEXITCODE -eq 0 -and $commit) {
+        $info.commit = $commit
+        $dirtyLines = git -C $RepoRoot status --porcelain 2>$null
+        $info.dirty = [bool]($dirtyLines | Where-Object { $_ })
+    }
+    return [pscustomobject]$info
+}
+
+# --- Compiler diagnostics (GCC/Clang "file:line:col: severity: msg") ----------
+function Get-FwDiagnostics {
+    <#
+    .SYNOPSIS
+        Parse a compiler log into specified diagnostics entries. Handles both
+        "file:line:col: error: message" and bare "error:"/"warning:" lines
+        (attributed to the last seen file when possible).
+    #>
+    param(
+        [Parameter(Mandatory = $true)][string[]]$Lines,
+        [string]$BaseDir = $null
+    )
+    $diags = [System.Collections.Generic.List[object]]::new()
+    $lastFile = $null
+    foreach ($raw in $Lines) {
+        $line = $raw.TrimEnd()
+        if (-not $line) { continue }
+        $m = [regex]::Match($line, '^(?<file>.+?):(?<line>\d+):(?<col>\d+):\s*(?<sev>fatal error|error|warning):\s*(?<msg>.*)$')
+        if ($m.Success) {
+            $file = $m.Groups['file'].Value.Trim('"')
+            if ($BaseDir) {
+                # Normalize separators so windows/posix mixups don't block the trim.
+                $fileNorm = $file.Replace('/', '\')
+                $baseNorm = $BaseDir.Replace('/', '\')
+                if ($fileNorm.StartsWith($baseNorm, [System.StringComparison]::OrdinalIgnoreCase)) {
+                    $file = $fileNorm.Substring($baseNorm.Length).TrimStart('\')
+                } else {
+                    $file = $fileNorm
+                }
+            }
+            $sev = $m.Groups['sev'].Value
+            if ($sev -eq 'fatal error') { $sev = 'error' }
+            $diags.Add([pscustomobject]@{
+                file     = $file
+                line     = [int]$m.Groups['line'].Value
+                col      = [int]$m.Groups['col'].Value
+                severity = $sev
+                message  = $m.Groups['msg'].Value
+            })
+            $lastFile = $file
+            continue
+        }
+        $m2 = [regex]::Match($line, '^\s*(?<sev>fatal error|error|warning):\s*(?<msg>.*)$')
+        if ($m2.Success) {
+            $sev = $m2.Groups['sev'].Value
+            if ($sev -eq 'fatal error') { $sev = 'error' }
+            $diags.Add([pscustomobject]@{
+                file     = if ($lastFile) { $lastFile } else { $null }
+                line     = $null
+                col      = $null
+                severity = $sev
+                message  = $m2.Groups['msg'].Value
+            })
+        }
+    }
+    return ,$diags
+}
+
+function Invoke-FwProcess {
+    <#
+    .SYNOPSIS
+        Run an external process with a hard timeout. Every external process
+        in this toolchain MUST go through here (Spec Rule 6).
+        Returns { exit_code, timed_out, stdout, stderr }.
+    #>
+    param(
+        [Parameter(Mandatory = $true)][string]$FilePath,
+        [string[]]$Arguments = @(),
+        [string]$WorkingDirectory = $null,
+        [int]$TimeoutMs = 300000,
+        [string]$StdoutFile = $null,
+        [string]$StderrFile = $null
+    )
+    $psi = [System.Diagnostics.ProcessStartInfo]::new()
+    $psi.FileName = $FilePath
+    foreach ($a in $Arguments) { $psi.ArgumentList.Add($a) }
+    $psi.UseShellExecute = $false
+    $psi.CreateNoWindow = $true
+    $psi.RedirectStandardOutput = $true
+    $psi.RedirectStandardError = $true
+    if ($WorkingDirectory) { $psi.WorkingDirectory = $WorkingDirectory }
+
+    try {
+        $proc = [System.Diagnostics.Process]::new()
+        $proc.StartInfo = $psi
+        if (-not $proc.Start()) {
+            return [pscustomobject]@{ exit_code = -1; timed_out = $false; stdout = ''; stderr = 'failed to start' }
+        }
+        $stdoutTask = $proc.StandardOutput.ReadToEndAsync()
+        $stderrTask = $proc.StandardError.ReadToEndAsync()
+
+        $timedOut = -not $proc.WaitForExit($TimeoutMs)
+        if ($timedOut) {
+            try { $proc.Kill($true) } catch { }
+            $proc.WaitForExit()
+        }
+        $stdout = $stdoutTask.GetAwaiter().GetResult()
+        $stderr = $stderrTask.GetAwaiter().GetResult()
+
+        if ($StdoutFile) {
+            Save-FwLog -Path $StdoutFile -Content $stdout
+        }
+        if ($StderrFile) {
+            Save-FwLog -Path $StderrFile -Content $stderr
+        }
+
+        return [pscustomobject]@{
+            exit_code = $proc.ExitCode
+            timed_out = $timedOut
+            stdout    = $stdout
+            stderr    = $stderr
+        }
+    }
+    catch {
+        return [pscustomobject]@{
+            exit_code = -1
+            timed_out = $false
+            stdout    = ''
+            stderr    = "failed to launch '$FilePath': $($_.Exception.Message)"
+        }
+    }
+}
+
+function Get-FwLabConfig {
+    <#
+    .SYNOPSIS
+        Parse lab/lab.yaml (or the example fallback) into a PowerShell object.
+        YAML is not natively parseable in PowerShell; the project venv python
+        + PyYAML does the parsing (release-fix #5: no ConvertFrom-Json on YAML).
+    #>
+    param([string]$RepoRoot)
+    if (-not $RepoRoot) { return $null }
+    $python = Resolve-FwPython -RepoRoot $RepoRoot
+    if (-not $python) { return $null }
+    $candidates = @(
+        (Join-Path $RepoRoot 'lab\lab.yaml'),
+        (Join-Path $RepoRoot 'lab\lab.example.yaml')
+    )
+    foreach ($path in $candidates) {
+        if (-not (Test-Path -LiteralPath $path)) { continue }
+        $script = "import json, sys; sys.stdout.reconfigure(encoding='utf-8', errors='replace');`nimport yaml`nprint(json.dumps(yaml.safe_load(open(sys.argv[1], encoding='utf-8')) or {}))"
+        $res = Invoke-FwProcess -FilePath $python -Arguments @('-c', $script, $path) -TimeoutMs 30000
+        if ($res.exit_code -eq 0) {
+            try { return ($res.stdout | ConvertFrom-Json) } catch { }
+        }
+    }
+    return $null
+}
+
+Export-ModuleMember -Function Write-FwJson, Get-FwErrorClass, New-FwError, `
+    Resolve-FwPython, Get-FwRepoRoot, Save-FwLog, Get-FwTimestamp, `
+    Get-FwRunId, Get-FwGitInfo, Get-FwDiagnostics, Invoke-FwProcess, Get-FwLabConfig

tools/common/uart_probe.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+"""uart_probe.py - minimal DUT UART probe over a subprocess (simulator DUT).
+
+Spawns the compiled firmware artifact, waits for the boot banner, sends one
+CLI command and prints the observed reply line as JSON:
+
+    {"ok": true, "banner": [...], "command": "jedec", "reply": "JEDEC EF 40 18"}
+
+Used by tools/acceptance-scenario.ps1 for the offline (simulator) leg of the
+final acceptance scenario. Real-serial probing goes through Agentic HIL.
+"""
+
+import json
+import subprocess
+import sys
+import time
+
+REPLY_TOKENS = ("JEDEC", "PWM", "ERR")
+
+
+def main() -> int:
+    exe = sys.argv[1]
+    command = sys.argv[2] if len(sys.argv) > 2 else "jedec"
+    timeout = float(sys.argv[3]) if len(sys.argv) > 3 else 8.0
+
+    try:
+        proc = subprocess.Popen(
+            [exe], stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT, text=True, encoding="utf-8", errors="replace", bufsize=1,
+        )
+    except OSError as exc:
+        print(json.dumps({"ok": False, "error_class": "PROBE_NOT_FOUND",
+                          "error": f"cannot spawn artifact: {exc}"}))
+        return 2
+
+    banner: list[str] = []
+    deadline = time.monotonic() + timeout
+    reply = None
+
+    # read banner until it becomes quiet or the prompt command lands
+    while time.monotonic() < deadline:
+        try:
+            line = proc.stdout.readline()
+        except Exception:  # noqa: BLE001
+            break
+        if not line:
+            break
+        line = line.rstrip("\r\n")
+        if not line:
+            continue
+        banner.append(line)
+        if line.startswith("Application started"):
+            break
+
+    try:
+        proc.stdin.write(command + "\n")
+        proc.stdin.flush()
+    except Exception as exc:  # noqa: BLE001
+        print(json.dumps({"ok": False, "error_class": "UART_TIMEOUT",
+                          "error": f"cannot write command: {exc}", "banner": banner}))
+        proc.kill()
+        return 1
+
+    deadline = time.monotonic() + timeout
+    collected: list[str] = []
+    while time.monotonic() < deadline:
+        try:
+            line = proc.stdout.readline()
+        except Exception:  # noqa: BLE001
+            break
+        if not line:
+            break
+        line = line.rstrip("\r\n")
+        if not line:
+            continue
+        if line.startswith(("Bootloader ", "Application ")):
+            continue
+        collected.append(line)
+        if line.startswith(REPLY_TOKENS):
+            reply = line
+            break
+
+    proc.kill()
+    try:
+        proc.wait(timeout=3)
+    except Exception:  # noqa: BLE001
+        pass
+
+    if reply is None:
+        print(json.dumps({"ok": False, "error_class": "UART_TIMEOUT", "error": "no reply",
+                          "banner": banner, "collected": collected}))
+        return 1
+
+    print(json.dumps({"ok": True, "banner": banner, "command": command,
+                      "reply": reply, "collected": collected}, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tools/doctor.ps1

@@ -0,0 +1,148 @@
+<#
+.SYNOPSIS
+    Environment doctor (Spec M0 / §26). Checks the pieces of the baseline
+    toolchain and returns one JSON document:
+
+        .\tools\doctor.ps1 -Json
+
+    The doctor NEVER fails the whole run because hardware is absent: hardware
+    categories report status "missing"/"not_configured" and delivery is
+    deferred to the project. Only a broken core toolchain (no python, no git,
+    no build tool) is reported as not-ok.
+#>
+[CmdletBinding()]
+param([switch]$Json)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+Import-Module (Join-Path $PSScriptRoot 'common\fw.psm1') -Force
+
+$repoRoot = Get-FwRepoRoot
+$python = Resolve-FwPython -RepoRoot $repoRoot
+$venvBin = if ($python -and $python -match '.venv[\\/]Scripts[\\/]python.exe$') { Split-Path $python } else { $null }
+
+function Test-Tool {
+    param([string]$Name)
+    # prefer the project venv bin dir (tools installed without polluting PATH)
+    $candidate = if ($venvBin) { Join-Path $venvBin ($Name + '.exe') } else { $null }
+    $cmd = if ($candidate -and (Test-Path -LiteralPath $candidate)) {
+        Get-Item -LiteralPath $candidate
+    } else {
+        Get-Command $Name -ErrorAction SilentlyContinue
+    }
+    if ($cmd) {
+        $v = $null
+        $src = if ($cmd.GetType().Name -eq 'ApplicationInfo') { $cmd.Source } else { $cmd.FullName }
+        try { $v = (& $src --version 2>&1 | Select-Object -First 1) } catch { }
+        return [pscustomobject]@{ status = 'ok'; path = $src; version = [string]$v }
+    }
+    return [pscustomobject]@{ status = 'missing'; path = $null; version = $null }
+}
+
+function Test-PyModule {
+    param([string]$Module, [string]$Python)
+    if (-not $Python) { return [pscustomobject]@{ status = 'missing'; detail = 'no python' } }
+    $out = & $Python -c "import $Module; print(getattr($Module, '__version__', 'present'))" 2>&1
+    if ($LASTEXITCODE -eq 0) { return [pscustomobject]@{ status = 'ok'; detail = ([string]$out).Trim() } }
+    return [pscustomobject]@{ status = 'missing'; detail = ([string]$out).Trim() }
+}
+
+$checks = [ordered]@{}
+
+# --- core toolchain -----------------------------------------------------------
+$checks.python = if ($python) {
+    $pyv = & $python --version 2>&1
+    [pscustomobject]@{ status = 'ok'; path = $python; version = ([string]$pyv).Trim() }
+} else {
+    [pscustomobject]@{ status = 'missing'; path = $null; version = $null }
+}
+
+$checks.git = if ((Get-Command git -ErrorAction SilentlyContinue)) {
+    $gv = git --version 2>&1
+    $gitStatus = [pscustomobject]@{ status = 'ok'; path = (Get-Command git).Source; version = ([string]$gv).Trim() }
+    $gitStatus | Add-Member -NotePropertyName repo -NotePropertyValue (git -C $repoRoot rev-parse --is-inside-work-tree 2>$null)
+    $gitStatus
+} else {
+    [pscustomobject]@{ status = 'missing'; path = $null; version = $null }
+}
+
+# --- build backends -----------------------------------------------------------
+foreach ($tool in @('cmake', 'ninja', 'make', 'gcc', 'clang')) {
+    $checks[$tool] = Test-Tool $tool
+}
+$checks.keil = Test-Tool 'UV4'
+$checks.iar = Test-Tool 'IarBuild'
+$checks.idf = Test-Tool 'idf.py'
+$checks.west = Test-Tool 'west'
+$checks.platformio = Test-Tool 'pio'
+
+# --- hardware / lab layer ------------------------------------------------------
+$checks.agentic_hil = Test-Tool 'agentic-hil'
+$checks.openocd = Test-Tool 'openocd'
+$checks.sigrok_cli = Test-Tool 'sigrok-cli'
+$checks.pyocd = if ($python) {
+    Test-PyModule 'pyocd' $python
+} else { [pscustomobject]@{ status = 'missing'; detail = 'no python' } }
+
+$checks.pytest = if ($python) { Test-PyModule 'pytest' $python } else { [pscustomobject]@{ status = 'missing'; detail = 'no python' } }
+$checks.pyserial = if ($python) { Test-PyModule 'serial' $python } else { [pscustomobject]@{ status = 'missing'; detail = 'no python' } }
+$checks.pyvisa = if ($python) { Test-PyModule 'pyvisa' $python } else { [pscustomobject]@{ status = 'missing'; detail = 'no python' } }
+
+# COM ports present (UART candidates) - informational, never hardcoded.
+# Prefer Agentic HIL's enumeration (hardware-aware) when installed, else WMI.
+$comPorts = @()
+$ahil = if ($venvBin) { Join-Path $venvBin 'agentic-hil.exe' } else { $null }
+if ($ahil -and (Test-Path -LiteralPath $ahil)) {
+    try {
+        $raw = & $ahil com-ports 2>$null | Out-String
+        $parsed = $raw | ConvertFrom-Json -ErrorAction SilentlyContinue
+        if ($parsed -and $parsed.ports) {
+            $comPorts = @($parsed.ports | ForEach-Object { $_.device } | Where-Object { $_ })
+        }
+    } catch { }
+}
+if ($comPorts.Count -eq 0) {
+    try {
+        $comPorts = @((Get-CimInstance Win32_SerialPort -ErrorAction SilentlyContinue | Select-Object -ExpandProperty DeviceID))
+    } catch { }
+}
+$checks.com_ports = [pscustomobject]@{
+    status = if ($comPorts.Count -gt 0) { 'ok' } else { 'none' }
+    source = if ($ahil -and (Test-Path -LiteralPath $ahil)) { 'agentic-hil' } else { 'wmi' }
+    ports  = $comPorts
+}
+
+# Saleae Logic 2 MCP endpoint (127.0.0.1:10530) is optional; check socket
+$logicOk = $false
+try {
+    $tcp = [System.Net.Sockets.TcpClient]::new()
+    $tcp.Connect('127.0.0.1', 10530)
+    $logicOk = $tcp.Connected
+    $tcp.Close()
+} catch { }
+$checks.logic2_mcp = [pscustomobject]@{ status = if ($logicOk) { 'ok' } else { 'not_configured' }; endpoint = 'http://127.0.0.1:10530' }
+
+# --- composition ----------------------------------------------------------------
+$coreNames = @('python', 'git', 'cmake')
+$coreOk = $true
+$missingCore = @()
+foreach ($n in $coreNames) {
+    if ($checks[$n].status -ne 'ok') { $coreOk = $false; $missingCore += $n }
+}
+
+$result = [ordered]@{
+    schema       = 'firmware-doctor/v1'
+    ok           = $coreOk
+    generated_at = Get-FwTimestamp
+    host         = [ordered]@{
+        os      = [System.Environment]::OSVersion.VersionString
+        pwsh    = $PSVersionTable.PSVersion.ToString()
+        machine = $env:COMPUTERNAME
+    }
+    missing_core = $missingCore
+    checks       = $checks
+}
+
+if ($Json) { Write-FwJson ([pscustomobject]$result) -Compact } else { Write-FwJson ([pscustomobject]$result) }
+
+exit $(if ($coreOk) { 0 } else { 1 })