firmwareloop 0.0.8__py3-none-any.whl

tools/can.ps1

@@ -0,0 +1,130 @@
+<#
+.SYNOPSIS
+    CAN bus adapter (Spec §12). Minimum capability: session_start, send, read,
+    filter, session_stop. Backend is Agentic HIL (or a vendor CLI): the exact
+    verbs/schema MUST be confirmed against the installed version at setup time
+    (Spec §32). With no CAN backend configured this returns CONFIG_ERROR.
+
+    Safety: CAN TX defaults to manual authorization (Spec §12/§24); the
+    --authorized flag is required for send so the AI agent cannot TX silently.
+
+    Usage:
+        .\tools\can.ps1 session-start -Json
+        .\tools\can.ps1 send --arbitration-id 0x123 --frame-count 1 --authorized -Json
+        .\tools\can.ps1 read --duration-ms 500 -Json
+        .\tools\can.ps1 session-stop -Json
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)][ValidateSet('session-start', 'send', 'read', 'session-stop', 'filter')]
+    [string]$Command,
+    [ValidateSet('agentic-hil', 'vendor')]
+    [string]$Backend = 'agentic-hil',
+    [string]$Adapter,
+    [string]$Channel,
+    [int]$Bitrate = 500000,
+    [string]$ArbitrationId,          # hex string, e.g. 0x123
+    [string]$Data,                   # hex bytes, e.g. "11 22 33"
+    [int]$FrameCount = 1,
+    [int]$DurationMs = 500,
+    [switch]$Authorized,             # required for TX (default denied)
+    [switch]$Json
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+Import-Module (Join-Path $PSScriptRoot 'common\fw.psm1') -Force
+
+$repoRoot = Get-FwRepoRoot
+$stamp = Get-Date -Format 'yyyyMMdd-HHmmss'
+
+function Exit-WithError {
+    param([string]$Class, [string]$Message, [string]$Detail)
+    $body = New-FwError -ErrorClass $Class -Message $Message -Detail $Detail
+    if ($Json) { Write-FwJson $body -Compact } else { Write-FwJson $body; Write-Error "$Class : $Message" -ErrorAction Continue }
+    exit 2
+}
+
+# CAN TX default requires explicit authorization (Spec §12: 人工授权)
+if ($Command -eq 'send' -and -not $Authorized) {
+    Exit-WithError -Class 'PERMISSION_DENIED' -Message 'CAN TX requires explicit human authorization; pass -Authorized after approval (Spec §12/§24).'
+}
+
+$cmd = Get-Command agentic-hil -ErrorAction SilentlyContinue
+$tool = if ($cmd) { $cmd.Source } else { $null }
+
+if ($Backend -eq 'agentic-hil' -and -not $tool) {
+    Exit-WithError -Class 'PROBE_NOT_FOUND' -Message "'agentic-hil' is not installed; CAN is not available until Agentic HIL is installed (Spec §32)." -Detail 'Install Agentic HIL, then verify its CAN schema with: agentic-hil --help'
+}
+
+# Resolve lab config for adapter/channel/bitrate defaults (never hardcoded)
+$labCfg = Join-Path $repoRoot 'lab\lab.yaml'
+if (-not (Test-Path -LiteralPath $labCfg)) { $labCfg = Join-Path $repoRoot 'lab\lab.example.yaml' }
+$canCfg = @{}
+if (Test-Path -LiteralPath $labCfg) {
+    try {
+        $parsed = Get-Content -LiteralPath $labCfg -Raw | ConvertFrom-Json -ErrorAction SilentlyContinue
+        if ($parsed -and $parsed.can) { $canCfg = $parsed.can }
+    } catch { }
+} else { $canCfg = @{ adapter = $null; channel = $null; bitrate = $Bitrate } }
+if (-not $Adapter) { $Adapter = $canCfg.adapter }
+if (-not $Channel) { $Channel = $canCfg.channel }
+if ($Bitrate -eq 500000 -and $canCfg.bitrate) { $Bitrate = $canCfg.bitrate }
+
+if (-not $Adapter) {
+    Exit-WithError -Class 'CAN_ERROR' -Message 'CAN adapter is not configured; set lab/lab.yaml can.adapter (e.g. "PCAN_USBBus1").' -Detail 'Only adapter, channel and bitrate are betrothed by config; payload/structure are backend-enforced.'
+}
+
+# NOTE: verbs below follow Agentic HIL's documented surface; confirm against the
+# installed version at setup time (Spec §32). Failures surface as CAN_ERROR.
+$logFile = Join-Path $repoRoot "artifacts\logs\can-$stamp.log"
+New-Item -ItemType Directory -Force -Path (Split-Path $logFile) | Out-Null
+
+switch ($Command) {
+    'session-start' {
+        $res = Invoke-FwProcess -FilePath $tool -Arguments @('can', 'session_start', '--adapter', $Adapter, '--channel', $Channel, '--bitrate', $Bitrate) -WorkingDirectory $repoRoot -TimeoutMs 30000 -StdoutFile $logFile
+        if ($res.timed_out -or $res.exit_code -ne 0) {
+            Exit-WithError -Class 'CAN_ERROR' -Message 'CAN session_start failed.' -Detail ($res.stdout + $res.stderr)
+        }
+    }
+    'send' {
+        if (-not $ArbitrationId) { Exit-WithError -Class 'CONFIG_ERROR' -Message 'send requires --arbitration-id (e.g. 0x123)' }
+        $res = Invoke-FwProcess -FilePath $tool -Arguments @('can', 'send', '--id', $ArbitrationId, '--data', $Data, '--count', $FrameCount) -WorkingDirectory $repoRoot -TimeoutMs 30000 -StdoutFile $logFile
+        if ($res.timed_out -or $res.exit_code -ne 0) {
+            Exit-WithError -Class 'CAN_ERROR' -Message 'CAN send failed.' -Detail ($res.stdout + $res.stderr)
+        }
+    }
+    'read' {
+        $res = Invoke-FwProcess -FilePath $tool -Arguments @('can', 'read', '--duration-ms', $DurationMs) -WorkingDirectory $repoRoot -TimeoutMs 60000 -StdoutFile $logFile
+        if ($res.timed_out -or $res.exit_code -ne 0) {
+            Exit-WithError -Class 'CAN_ERROR' -Message 'CAN read failed.' -Detail ($res.stdout + $res.stderr)
+        }
+    }
+    'filter' {
+        if (-not $ArbitrationId) { Exit-WithError -Class 'CONFIG_ERROR' -Message 'filter requires --arbitration-id' }
+        $res = Invoke-FwProcess -FilePath $tool -Arguments @('can', 'filter', '--id', $ArbitrationId) -WorkingDirectory $repoRoot -TimeoutMs 30000 -StdoutFile $logFile
+        if ($res.timed_out -or $res.exit_code -ne 0) {
+            Exit-WithError -Class 'CAN_ERROR' -Message 'CAN filter failed.' -Detail ($res.stdout + $res.stderr)
+        }
+    }
+    'session-stop' {
+        $res = Invoke-FwProcess -FilePath $tool -Arguments @('can', 'session_stop') -WorkingDirectory $repoRoot -TimeoutMs 30000 -StdoutFile $logFile
+        if ($res.timed_out -or $res.exit_code -ne 0) {
+            Exit-WithError -Class 'CAN_ERROR' -Message 'CAN session_stop failed.' -Detail ($res.stdout + $res.stderr)
+        }
+    }
+}
+
+$result = [ordered]@{
+    schema      = 'firmware-can-result/v1'
+    ok          = $true
+    command     = $Command
+    backend     = $Backend
+    adapter     = $Adapter
+    channel     = $Channel
+    bitrate     = $Bitrate
+    log         = (Resolve-Path -LiteralPath $logFile).Path
+    generated_at = Get-FwTimestamp
+}
+if ($Json) { Write-FwJson ([pscustomobject]$result) -Compact } else { Write-FwJson ([pscustomobject]$result) }
+exit 0

tools/check-qoder-mcp.ps1

@@ -0,0 +1,111 @@
+<#
+.SYNOPSIS
+    Qoder MCP readiness check (GAP-010, release-fix #6).
+
+    Checks whether the machine is READY to use Agentic HIL inside Qoder, and
+    prints the exact registration command when it is not yet registered.
+    This is a CHECK-ONLY script: it never modifies Qoder or Agentic HIL
+    configuration. (Formerly configure-qoder.ps1; renamed because it does not
+    actually register - registration belongs to Qoder local/user scope.)
+
+        detect  -> locate agentic-hil (user-level install preferred, per Agentic
+                   HIL official quickstart) + qoder/qodercli CLI
+        verify  -> agentic-hil mcp-stdio boots (warmup window)
+        advise  -> exact registration command when missing
+
+    Usage:
+        .\tools\check-qoder-mcp.ps1 -Json
+#>
+[CmdletBinding()]
+param([switch]$Json)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+Import-Module (Join-Path $PSScriptRoot 'common\fw.psm1') -Force
+
+$repoRoot = Get-FwRepoRoot
+
+function Exit-WithError {
+    param([string]$Class, [string]$Message, [string]$Detail)
+    $body = New-FwError -ErrorClass $Class -Message $Message -Detail $Detail
+    if ($Json) { Write-FwJson $body -Compact } else { Write-FwJson $body; Write-Error "$Class : $Message" -ErrorAction Continue }
+    exit 2
+}
+
+$report = [ordered]@{ schema = 'qoder-mcp-check/v1'; steps = [ordered]@{} }
+
+# ---- 1. detect ------------------------------------------------------------------
+# Agentic HIL quickstart recommends a persistent USER-LEVEL installation, not
+# one venv per repo. Prefer PATH (user-level), fall back to the repo venv.
+$ahil = $null
+$g = Get-Command agentic-hil -ErrorAction SilentlyContinue
+if ($g) { $ahil = $g.Source }
+$ahilSource = 'user-level (PATH)'
+if (-not $ahil) {
+    $venvAhil = Join-Path $repoRoot '.venv\Scripts\agentic-hil.exe'
+    if (Test-Path -LiteralPath $venvAhil) {
+        $ahil = $venvAhil
+        $ahilSource = 'repo .venv (consider a user-level install: agentic-hil agent-install)'
+    }
+}
+if (-not $ahil -or -not (Test-Path -LiteralPath $ahil)) {
+    Exit-WithError -Class 'PROBE_NOT_FOUND' -Message 'agentic-hil not found; install it user-level (uv tool install agentic-hil / pipx) or into .venv (uv pip install agentic-hil).'
+}
+$report.steps.detect = [ordered]@{ ok = $true; agentic_hil = (Resolve-Path -LiteralPath $ahil).Path; source = $ahilSource }
+
+# qoder CLI: try both spellings seen in the wild (release-fix #6: discovery,
+# never hardcode one command name)
+$qoderCmd = $null
+foreach ($name in @('qoder', 'qodercli')) {
+    $c = Get-Command $name -ErrorAction SilentlyContinue
+    if ($c) { $qoderCmd = $c; break }
+}
+$report.steps.detect.qoder = if ($qoderCmd) { $qoderCmd.Source } else { $null }
+$report.steps.detect.qoder_candidate = if ($qoderCmd) { $qoderCmd.Name } else { $null }
+
+# ---- 2. verify MCP server boots ---------------------------------------------------
+$proc = $null
+$serverOk = $false
+try {
+    $proc = [System.Diagnostics.Process]::new()
+    $psi = [System.Diagnostics.ProcessStartInfo]::new()
+    $psi.FileName = $ahil
+    $psi.ArgumentList.Add('mcp-stdio')
+    $psi.WorkingDirectory = $repoRoot
+    $psi.UseShellExecute = $false
+    $psi.CreateNoWindow = $true
+    $proc.StartInfo = $psi
+    if ($proc.Start()) {
+        Start-Sleep -Milliseconds 1500
+        $serverOk = -not $proc.HasExited
+    }
+} catch {
+    $serverOk = $false
+} finally {
+    if ($proc -and -not $proc.HasExited) { try { $proc.Kill($true) } catch { } }
+}
+$report.steps.verify = [ordered]@{
+    ok = $serverOk
+    mcp_handshake = if ($serverOk) { 'agentic-hil mcp-stdio booted and stayed alive (full handshake runs inside Qoder)' } else { 'mcp-stdio exited during warmup - check the installation' }
+}
+
+# ---- 3. advise ---------------------------------------------------------------------
+$advice = [ordered]@{ ok = $true; registered = $null; command = $null }
+if (-not $qoderCmd) {
+    $advice.ok = $false
+    $advice.note = 'no qoder/qodercli CLI on PATH; register manually in Qoder UI (local/user scope).'
+} else {
+    # runtime discovery of the mcp subcommand (Spec §32)
+    $help = Invoke-FwProcess -FilePath $qoderCmd.Source -Arguments @('mcp', '--help') -WorkingDirectory $repoRoot -TimeoutMs 30000
+    if ($help.exit_code -eq 0) {
+        $advice.command = "$($qoderCmd.Name) mcp add agentic-hil -- $ahil mcp-stdio"
+        $advice.note = 'registration command (run in Qoder local/user scope):'
+    } else {
+        $advice.ok = $false
+        $advice.note = "$($qoderCmd.Name) CLI found but no 'mcp' subcommand; register manually in Qoder UI (local/user scope)."
+    }
+}
+$report.steps.advise = $advice
+
+if ($Json) { Write-FwJson ([pscustomobject]$report) -Compact } else { Write-FwJson ([pscustomobject]$report) }
+exit $(if ($report.steps.detect.ok -and $report.steps.verify.ok -and $advice.ok) { 0 } else { 1 })

tools/common/build-backends.psm1

@@ -0,0 +1,294 @@
+# build-backends.psm1 - FirmwareLoop v0.0.2 (GAP-002): build backend registry.
+#
+# Thin adapter: detection precedence, command construction and artifact
+# collection per backend. No build system is reimplemented - each backend
+# invokes the official CLI (cmake / make / pio / UV4 / IarBuild / west /
+# idf.py). Command construction is testable via -DryRun (tools/build.ps1).
+
+Set-StrictMode -Version Latest
+
+$script:FW_BACKENDS = @('cmake', 'make', 'platformio', 'keil', 'iar', 'zephyr', 'esp-idf')
+
+# ---- strong project markers (checked BEFORE generic CMake) --------------------
+$script:FW_MARKERS = @(
+    @{ backend = 'zephyr';     marker = 'west.yml' },
+    @{ backend = 'esp-idf';    marker = 'sdkconfig' },      # sdkconfig / sdkconfig.defaults
+    @{ backend = 'esp-idf';    marker = 'idf.py' },
+    @{ backend = 'platformio'; marker = 'platformio.ini' },
+    @{ backend = 'keil';       marker = '*.uvproj*' },     # uvproj/uvprojx
+    @{ backend = 'iar';        marker = '*.ewp' },
+    @{ backend = 'make';       marker = 'Makefile' },
+    @{ backend = 'cmake';      marker = 'CMakeLists.txt' }
+)
+
+function Find-FwProject {
+    <#
+    .SYNOPSIS
+        Locate the actual project directory for a backend inside a search
+        root: root level first, then one directory deep. Returns
+        @{ src; project_file } (project_file null when the marker is a dir).
+    #>
+    param([string]$BackendName, [string]$SearchRoot)
+    foreach ($level in @($SearchRoot)) {
+        foreach ($m in $script:FW_MARKERS) {
+            if ($m.backend -ne $BackendName) { continue }
+            $hit = Get-ChildItem -LiteralPath $level -Filter $m.marker -File -ErrorAction SilentlyContinue | Select-Object -First 1
+            if ($hit) { return [pscustomobject]@{ src = $level; project_file = $hit.FullName } }
+        }
+    }
+    foreach ($sub in (Get-ChildItem -LiteralPath $SearchRoot -Directory -ErrorAction SilentlyContinue)) {
+        foreach ($m in $script:FW_MARKERS) {
+            if ($m.backend -ne $BackendName) { continue }
+            $hit = Get-ChildItem -LiteralPath $sub.FullName -Filter $m.marker -File -ErrorAction SilentlyContinue | Select-Object -First 1
+            if ($hit) { return [pscustomobject]@{ src = $sub.FullName; project_file = $hit.FullName } }
+        }
+    }
+    return [pscustomobject]@{ src = $SearchRoot; project_file = $null }
+}
+
+function Get-FwBackendDetect {
+    <#
+    .SYNOPSIS
+        Detection precedence (Spec GAP-002): explicit -Backend > project
+        config > strong marker > generic detection. Returns
+        @{ backend; src; project_file } or $null when nothing found.
+    #>
+    param(
+        [string]$ExplicitBackend,
+        [string]$ProjectBackend,
+        [string]$SourceDir,
+        [string]$RepoRoot
+    )
+    if ($ExplicitBackend -and $ExplicitBackend -in $script:FW_BACKENDS) {
+        $root = if ($SourceDir) { $SourceDir } else { $RepoRoot }
+        $found = Find-FwProject -BackendName $ExplicitBackend -SearchRoot $root
+        return [pscustomobject]@{ backend = $ExplicitBackend; src = $found.src; project_file = $found.project_file; source = 'explicit' }
+    }
+    if ($ProjectBackend -and $ProjectBackend -in $script:FW_BACKENDS) {
+        $root = if ($SourceDir) { $SourceDir } else { $RepoRoot }
+        $found = Find-FwProject -BackendName $ProjectBackend -SearchRoot $root
+        return [pscustomobject]@{ backend = $ProjectBackend; src = $found.src; project_file = $found.project_file; source = 'project-config' }
+    }
+
+    $candidates = @()
+    if ($SourceDir) {
+        $candidates += $SourceDir
+    } else {
+        $candidates += $RepoRoot
+        Get-ChildItem -LiteralPath $RepoRoot -Directory -ErrorAction SilentlyContinue |
+            Where-Object { $_.Name -notmatch '^(\.|artifacts|tests|tools|lab|docs|Spec|\.venv|node_modules|demo-make)$' } |
+            ForEach-Object { $candidates += $_.FullName }
+    }
+
+    foreach ($c in $candidates) {
+        if (-not (Test-Path -LiteralPath $c)) { continue }
+        foreach ($m in $script:FW_MARKERS) {
+            $hit = Get-ChildItem -LiteralPath $c -Filter $m.marker -File -ErrorAction SilentlyContinue | Select-Object -First 1
+            if ($hit) {
+                return [pscustomobject]@{ backend = $m.backend; src = $c; project_file = $hit.FullName; source = 'marker' }
+            }
+        }
+    }
+    return $null
+}
+
+function Resolve-FwTool {
+    <#
+    .SYNOPSIS
+        Find a tool on PATH or return $null (never throws on missing).
+    #>
+    param([string]$Name, [string]$Override)
+    if ($Override) { return $Override }
+    $g = Get-Command $Name -ErrorAction SilentlyContinue
+    if ($g) { return $g.Source }
+    return $null
+}
+
+function Get-FwBackendCommand {
+    <#
+    .SYNOPSIS
+        Build the official CLI invocation for a backend. Pure construction -
+        no execution - so tests can assert command shape (Spec GAP-002
+        "Keil command construction" etc). Returns @{ file; args; cwd; label }.
+    #>
+    param(
+        [Parameter(Mandatory = $true)][string]$Backend,
+        [Parameter(Mandatory = $true)][string]$Src,
+        [string]$ProjectFile,
+        [string]$Configuration = 'Debug',
+        [string]$BuildDir,
+        [string]$Tool = $null,       # override (fake executable for tests)
+        [switch]$AllowMissingTool   # construction tests without installed tools
+    )
+    $b = $Backend.ToLowerInvariant()
+    switch ($b) {
+        'cmake' {
+            $generator = if (Get-Command ninja -ErrorAction SilentlyContinue) { 'Ninja' } else { 'MinGW Makefiles' }
+            if ($Tool) { $toolPath = $Tool } else { $toolPath = Resolve-FwTool -Name 'cmake' }; if (-not $toolPath) { if ($AllowMissingTool) { $toolPath = "<missing:cmake>" } else { return @{ missing = 'cmake' } } }
+            return @{
+                file = $toolPath
+                args = @('-S', $Src, '-B', $BuildDir, '-G', $generator, "-DCMAKE_BUILD_TYPE=$Configuration")
+                # follow-up steps executed in order after the configure command
+                steps = @(
+                    @{ file = $toolPath; args = @('--build', $BuildDir, '--config', $Configuration); cwd = $null }
+                )
+                cwd  = $null
+                label = "cmake -S <src> -B <build> -G $generator -DCMAKE_BUILD_TYPE=$Configuration; cmake --build <build> --config $Configuration"
+            }
+        }
+        'make' {
+            if ($Tool) { $toolPath = $Tool } else { $toolPath = Resolve-FwTool -Name 'make' }; if (-not $toolPath) { if ($AllowMissingTool) { $toolPath = "<missing:make>" } else { return @{ missing = 'make' } } }
+            if (-not $toolPath) { return @{ missing = 'make' } }
+            return @{
+                file = $toolPath
+                args = @('-C', $Src, "-CONFIG=$Configuration")
+                cwd  = $null
+                label = "make -C <src> -CONFIG=$Configuration"
+            }
+        }
+        'platformio' {
+            if ($Tool) { $toolPath = $Tool } else { $toolPath = Resolve-FwTool -Name 'pio' }; if (-not $toolPath) { if ($AllowMissingTool) { $toolPath = "<missing:pio>" } else { return @{ missing = 'pio' } } }
+            if (-not $toolPath) { return @{ missing = 'platformio' } }
+            return @{
+                file = $toolPath
+                args = @('run', '-d', $Src, '-e', "$Configuration")
+                cwd  = $null
+                label = "pio run -d <src> -e <env>"
+            }
+        }
+        'keil' {
+            if ($Tool) { $toolPath = $Tool } else { $toolPath = Resolve-FwTool -Name 'UV4' }; if (-not $toolPath) { if ($AllowMissingTool) { $toolPath = "<missing:UV4>" } else { return @{ missing = 'UV4' } } }
+            if (-not $toolPath) { return @{ missing = 'keil' } }
+            if (-not $ProjectFile) { return @{ missing = 'keil-project' } }
+            return @{
+                file = $toolPath
+                args = @('-b', $ProjectFile, '-j0')
+                cwd  = $null
+                label = "UV4 -b <project.uvprojx> -j0"
+            }
+        }
+        'iar' {
+            if ($Tool) { $toolPath = $Tool } else { $toolPath = Resolve-FwTool -Name 'IarBuild' }; if (-not $toolPath) { if ($AllowMissingTool) { $toolPath = "<missing:IarBuild>" } else { return @{ missing = 'IarBuild' } } }
+            if (-not $toolPath) { return @{ missing = 'iar' } }
+            if (-not $ProjectFile) { return @{ missing = 'iar-project' } }
+            return @{
+                file = $toolPath
+                args = @($ProjectFile, '-build', $Configuration)
+                cwd  = $null
+                label = "IarBuild <project.ewp> -build <config>"
+            }
+        }
+        'zephyr' {
+            if ($Tool) { $toolPath = $Tool } else { $toolPath = Resolve-FwTool -Name 'west' }; if (-not $toolPath) { if ($AllowMissingTool) { $toolPath = "<missing:west>" } else { return @{ missing = 'west' } } }
+            if (-not $toolPath) { return @{ missing = 'zephyr' } }
+            $board = $env:ZEPHYR_BOARD
+            if (-not $board) { return @{ missing = 'zephyr-board'; detail = 'set ZEPHYR_BOARD (e.g. native_sim) or pass -Configuration' } }
+            return @{
+                file = $toolPath
+                args = @('build', '-d', $BuildDir, '-b', $board, '-p', 'auto')
+                cwd  = $Src
+                label = "west build -d <build> -b <ZEPHYR_BOARD> -p auto"
+            }
+        }
+        'esp-idf' {
+            if ($Tool) { $toolPath = $Tool } else { $toolPath = Resolve-FwTool -Name 'idf.py' }; if (-not $toolPath) { if ($AllowMissingTool) { $toolPath = "<missing:idf.py>" } else { return @{ missing = 'idf.py' } } }
+            if (-not $toolPath) { return @{ missing = 'esp-idf' } }
+            return @{
+                file = $toolPath
+                args = @('build')
+                cwd  = $Src
+                label = "idf.py build (cwd=<src>)"
+            }
+        }
+        default { return @{ missing = $b } }
+    }
+}
+
+# artifact naming per backend (Spec GAP-002 artifact manifest)
+$script:FW_ARTIFACT_PATTERNS = @{
+    cmake      = @{ primary = 'firmware.elf'; formats = @('elf'); secondary = @('firmware.hex', 'firmware.bin', 'firmware.map') }
+    make       = @{ primary = 'app.elf';      formats = @('elf'); secondary = @('app.hex') }
+    keil       = @{ primary = 'app.axf';      formats = @('axf'); secondary = @('app.hex') }
+    iar        = @{ primary = 'app.out';      formats = @('out'); secondary = @('app.hex') }
+    zephyr     = @{ primary = 'zephyr.elf';   formats = @('elf'); secondary = @('zephyr.hex') }
+    'esp-idf'  = @{ primary = 'firmware.elf'; formats = @('elf'); secondary = @('firmware.bin') }
+    platformio = @{ primary = 'firmware.elf'; formats = @('elf'); secondary = @('firmware.bin', 'firmware.hex') }
+}
+
+# discovery fallback patterns per backend (release-fix #5): when the named
+# primary is absent, scan the native output dir for the newest matching image
+# (real projects rarely name their binary app.elf/app.axf/app.out).
+$script:FW_DISCOVERY_PATTERNS = @{
+    make       = @('*.elf', '*.hex')
+    keil       = @('*.axf', '*.hex')
+    iar        = @('*.out', '*.hex')
+    platformio = @('*.elf', '*.bin', '*.hex')
+}
+
+function Get-FwBackendArtifacts {
+    <#
+    .SYNOPSIS
+        Collect artifacts per backend into a firmware-artifacts/v1 manifest
+        object. Artifacts are located in each backend's NATIVE output
+        location (never fabricated, never borrowed from another backend's
+        leftovers). Missing files stay absent.
+    #>
+    param(
+        [Parameter(Mandatory = $true)][string]$Backend,
+        [Parameter(Mandatory = $true)][string]$ArtifactDir,
+        [string]$Src,
+        [string]$BuildDir
+    )
+    $pat = $script:FW_ARTIFACT_PATTERNS[$Backend]
+    if (-not $pat) { return $null }
+    # native output dir per backend
+    $outDir = switch ($Backend) {
+        'cmake'    { $ArtifactDir }
+        'make'     { $Src }
+        'keil'     { $Src }
+        'iar'      { $Src }
+        'zephyr'   { Join-Path $BuildDir 'zephyr' }
+        'esp-idf'  { Join-Path $Src 'build' }
+        'platformio' { Join-Path $Src '.pio\build' }
+        default    { $ArtifactDir }
+    }
+    $primary = $null
+    $secondary = @()
+    $pPath = Join-Path $outDir $pat.primary
+    if (-not (Test-Path -LiteralPath $pPath)) {
+        # artifact discovery (release-fix #5): newest matching image in the
+        # native output location, including platformio's per-env subdirs
+        $discovery = $script:FW_DISCOVERY_PATTERNS[$Backend]
+        if ($discovery) {
+            $hits = @()
+            foreach ($g in $discovery) {
+                $hits += Get-ChildItem -LiteralPath $outDir -Filter $g -File -Recurse -ErrorAction SilentlyContinue
+            }
+            $newest = $hits | Sort-Object LastWriteTime -Descending | Select-Object -First 1
+            if ($newest) { $pPath = $newest.FullName }
+        }
+    }
+    if (Test-Path -LiteralPath $pPath) {
+        $primary = [ordered]@{
+            path        = $pPath
+            format      = ([System.IO.Path]::GetExtension($pPath)).TrimStart('.')
+            native_path = (Resolve-Path -LiteralPath $pPath).Path
+        }
+    }
+    foreach ($s in $pat.secondary) {
+        $sp = Join-Path $outDir $s
+        if (Test-Path -LiteralPath $sp) {
+            $secondary += [ordered]@{ path = $sp; format = ([System.IO.Path]::GetExtension($s)).TrimStart('.') }
+        }
+    }
+    return [ordered]@{
+        schema        = 'firmware-artifacts/v1'
+        backend       = $Backend
+        configuration = $null   # filled by caller
+        output_dir    = $outDir
+        primary       = $primary
+        secondary     = $secondary
+    }
+}
+
+Export-ModuleMember -Function Get-FwBackendDetect, Get-FwBackendCommand, Get-FwBackendArtifacts -Variable FW_BACKENDS