@cfour-hi/dsh-plugin-devicex 0.0.0-stage → 1.5.0

package/host/win/software.ps1

@@ -0,0 +1,119 @@
+# Device X - Windows installed-software inventory (registry Uninstall keys).
+#
+# Emits exactly one JSON document on stdout (no other stdout text).
+# Read-only: no admin rights, no network calls, no external modules.
+# `winget --version` only runs when the executable is present (no install, no
+# source agreement prompt) and never touches the network.
+$ErrorActionPreference = 'Stop'
+
+$errors = @()
+
+function Invoke-NativeOem([scriptblock]$action) {
+  # Native console tools (netsh/tasklist/manage-bde/winget) write OEM/ANSI bytes
+  # on a non-English Windows. The bridge sets the console to UTF-8 for the JSON
+  # document; temporarily decode native output with the OEM code page so SSIDs,
+  # user names and device names are not mojibake, then restore in finally.
+  $originalEncoding = [Console]::OutputEncoding
+  $oemCodePage = 437
+  try {
+    $cultureCodePage = [System.Globalization.CultureInfo]::CurrentCulture.TextInfo.OEMCodePage
+    if ($cultureCodePage -gt 0) { $oemCodePage = $cultureCodePage }
+    [Console]::OutputEncoding = [System.Text.Encoding]::GetEncoding($oemCodePage)
+    return & $action
+  } finally {
+    [Console]::OutputEncoding = $originalEncoding
+  }
+}
+
+$uninstallRoots = @(
+  [pscustomobject]@{ hive = 'HKLM'; path = 'HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall'; arch = 'x64' },
+  [pscustomobject]@{ hive = 'HKLM'; path = 'HKLM:\Software\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall'; arch = 'x86' },
+  [pscustomobject]@{ hive = 'HKCU'; path = 'HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall'; arch = 'x64' }
+)
+
+$applications = @()
+foreach ($root in $uninstallRoots) {
+  try {
+    $uninstallKeys = @(Get-ChildItem -Path $root.path -ErrorAction Stop)
+  } catch {
+    $message = $_.Exception.Message
+    if ($message -notmatch 'Cannot find path' -and $message -notmatch 'does not exist') {
+      $errors += ('registry ' + $root.path + ': ' + $message)
+    }
+    continue
+  }
+  $relativeRoot = $root.path -replace '^(HKLM|HKCU):\\', ''
+  foreach ($uninstallKey in $uninstallKeys) {
+    $keyName = [string]$uninstallKey.PSChildName
+    $keyPath = $relativeRoot + '\' + $keyName
+    $properties = $null
+    try {
+      $properties = Get-ItemProperty -Path $uninstallKey.PSPath -ErrorAction Stop
+    } catch {
+      continue
+    }
+    if ($null -eq $properties) { continue }
+    $displayName = [string]$properties.DisplayName
+    if (-not $displayName.Trim()) { continue }
+    if ($null -ne $properties.SystemComponent -and [int]$properties.SystemComponent -eq 1) { continue }
+    if ($null -ne $properties.ParentKeyName -and [string]$properties.ParentKeyName) { continue }
+    $estimatedSizeKb = $null
+    if ($null -ne $properties.EstimatedSize) {
+      try { $estimatedSizeKb = [long]$properties.EstimatedSize } catch { $estimatedSizeKb = $null }
+    }
+    $applications += [ordered]@{
+      displayName = $displayName.Trim()
+      version = [string]$properties.DisplayVersion
+      publisher = [string]$properties.Publisher
+      installLocation = [string]$properties.InstallLocation
+      estimatedSizeKB = $estimatedSizeKb
+      keyName = $keyName
+      keyPath = $keyPath
+      hive = $root.hive
+      arch = $root.arch
+      uninstallString = [string]$properties.UninstallString
+      quietUninstallString = [string]$properties.QuietUninstallString
+    }
+  }
+}
+
+# ---------------------------------------------------------- winget presence --
+$winget = [ordered]@{ available = $false; version = $null }
+$wingetExe = $null
+try {
+  $resolved = Get-Command -Name 'winget.exe' -CommandType Application -ErrorAction SilentlyContinue
+  if ($null -ne $resolved) { $wingetExe = [string]$resolved.Source }
+} catch { $wingetExe = $null }
+if (-not $wingetExe) {
+  try {
+    $resolved = Get-Command -Name 'winget' -CommandType Application -ErrorAction SilentlyContinue
+    if ($null -ne $resolved) { $wingetExe = [string]$resolved.Source }
+  } catch { $wingetExe = $null }
+}
+if ($wingetExe) {
+  try {
+    $versionLines = @(Invoke-NativeOem { & $wingetExe --version 2>$null })
+    $versionText = $null
+    foreach ($line in $versionLines) {
+      $text = [string]$line
+      if ($text.Trim()) {
+        if ($text -match '(\d+\.\d+[0-9A-Za-z.\-]*)') { $versionText = $matches[1]; break }
+      }
+    }
+    $winget.available = $true
+    if ($versionText) { $winget.version = $versionText }
+  } catch {
+    $winget.available = $true
+    $errors += ('winget --version: ' + $_.Exception.Message)
+  }
+}
+
+# -------------------------------------------------------------------- emit --
+$result = [ordered]@{
+  generatedAt = ([DateTimeOffset]::UtcNow).ToUnixTimeMilliseconds()
+  applications = $applications
+  winget = $winget
+  errors = $errors
+}
+
+$result | ConvertTo-Json -Depth 8 -Compress

package/host/win/system.ps1

@@ -0,0 +1,279 @@
+# Device X - Windows system inventory (OS, device, users, startup, locale).
+#
+# Emits exactly one JSON document on stdout (no other stdout text).
+# Read-only: no admin rights, no network calls, no external modules.
+$ErrorActionPreference = 'Stop'
+
+$errors = @()
+
+function To-EpochMs($value) {
+  if ($null -eq $value) { return $null }
+  try { return ([DateTimeOffset]$value).ToUnixTimeMilliseconds() } catch { return $null }
+}
+
+function To-LongOrNull($value) {
+  if ($null -eq $value) { return $null }
+  try { return [long]$value } catch { return $null }
+}
+
+$hostName = $env:COMPUTERNAME
+if (-not $hostName) {
+  try { $hostName = [System.Net.Dns]::GetHostName() } catch { $hostName = $null }
+}
+
+# ---------------------------------------------------------------------- OS --
+$osInfo = $null
+$bootInfo = $null
+try {
+  $os = Get-CimInstance -ClassName Win32_OperatingSystem -ErrorAction Stop
+  $displayVersion = $null
+  try {
+    $winVersionKey = Get-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion' -ErrorAction Stop
+    if ($winVersionKey.DisplayVersion) { $displayVersion = [string]$winVersionKey.DisplayVersion }
+  } catch { $displayVersion = $null }
+  $bootTimeMs = To-EpochMs $os.LastBootUpTime
+  $uptimeSec = $null
+  if ($null -ne $bootTimeMs -and $bootTimeMs -gt 0) {
+    $nowMs = ([DateTimeOffset]::UtcNow).ToUnixTimeMilliseconds()
+    $uptimeSec = [long][math]::Floor(($nowMs - $bootTimeMs) / 1000)
+  }
+  $osInfo = [ordered]@{
+    caption = [string]$os.Caption
+    displayVersion = $displayVersion
+    version = [string]$os.Version
+    build = [string]$os.BuildNumber
+    installDateMs = To-EpochMs $os.InstallDate
+    lastBootUpTimeMs = $bootTimeMs
+    osArchitecture = [string]$os.OSArchitecture
+    processorArchitecture = $env:PROCESSOR_ARCHITECTURE
+  }
+  $bootInfo = [ordered]@{ bootTimeMs = $bootTimeMs; uptimeSec = $uptimeSec }
+} catch { $errors += ('Win32_OperatingSystem: ' + $_.Exception.Message) }
+
+# ------------------------------------------------------------ OS/device facts --
+$processorName = $null
+try {
+  $processors = @(Get-CimInstance -ClassName Win32_Processor -ErrorAction Stop)
+  if ($processors.Count -gt 0) { $processorName = [string]$processors[0].Name }
+} catch { $processorName = $null }
+
+$device = $null
+try {
+  $computerSystem = Get-CimInstance -ClassName Win32_ComputerSystem -ErrorAction Stop
+  $bios = Get-CimInstance -ClassName Win32_BIOS -ErrorAction Stop
+  $product = Get-CimInstance -ClassName Win32_ComputerSystemProduct -ErrorAction Stop
+  $modelId = $null
+  if ($computerSystem.SystemSKUNumber) { $modelId = [string]$computerSystem.SystemSKUNumber }
+  elseif ($product.Version) { $modelId = [string]$product.Version }
+  $device = [ordered]@{
+    hostname = $hostName
+    computerName = [string]$computerSystem.Name
+    localHostname = $hostName
+    manufacturer = [string]$computerSystem.Manufacturer
+    model = [string]$computerSystem.Model
+    modelId = $modelId
+    chip = $processorName
+    serial = [string]$bios.SerialNumber
+    hardwareUuid = [string]$product.UUID
+  }
+} catch { $errors += ('Win32_ComputerSystem/BIOS: ' + $_.Exception.Message) }
+
+# -------------------------------------------------------------------- users --
+$profiles = @{}
+try {
+  $profileKeys = @(Get-ChildItem -Path 'HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion\ProfileList' -ErrorAction Stop)
+  foreach ($profileKey in $profileKeys) {
+    $sid = [string]$profileKey.PSChildName
+    try {
+      $profileProperties = Get-ItemProperty -Path $profileKey.PSPath -Name 'ProfileImagePath' -ErrorAction Stop
+      if ($profileProperties.ProfileImagePath) { $profiles[$sid] = [string]$profileProperties.ProfileImagePath }
+    } catch { }
+  }
+} catch { $profiles = @{} }
+
+$localUsers = @()
+try {
+  $accounts = @(Get-LocalUser -ErrorAction Stop)
+  foreach ($account in $accounts) {
+    $sid = $null
+    if ($account.SID) { $sid = [string]$account.SID.Value }
+    $homePath = $null
+    if ($sid -and $profiles.ContainsKey($sid)) { $homePath = $profiles[$sid] }
+    $localUsers += [ordered]@{
+      name = [string]$account.Name
+      fullName = [string]$account.FullName
+      enabled = [bool]$account.Enabled
+      sid = $sid
+      home = $homePath
+    }
+  }
+} catch {
+  $errors += ('Get-LocalUser: ' + $_.Exception.Message)
+  try {
+    $fallbackAccounts = @(Get-CimInstance -ClassName Win32_UserAccount -Filter 'LocalAccount = True' -ErrorAction Stop)
+    foreach ($account in $fallbackAccounts) {
+      $sid = [string]$account.SID
+      $homePath = $null
+      if ($sid -and $profiles.ContainsKey($sid)) { $homePath = $profiles[$sid] }
+      $localUsers += [ordered]@{
+        name = [string]$account.Name
+        fullName = [string]$account.FullName
+        enabled = (-not [bool]$account.Disabled)
+        sid = $sid
+        home = $homePath
+      }
+    }
+  } catch { $errors += ('Win32_UserAccount: ' + $_.Exception.Message) }
+}
+
+$admins = @()
+try {
+  $adminGroup = $null
+  try { $adminGroup = Get-LocalGroup -SID 'S-1-5-32-544' -ErrorAction Stop } catch { $adminGroup = $null }
+  if ($null -eq $adminGroup) {
+    # The group display name is localized; resolve it by the well-known
+    # Administrators SID instead of the English name.
+    $adminGroup = Get-LocalGroup -ErrorAction Stop | Where-Object { $_.SID.Value -eq 'S-1-5-32-544' } | Select-Object -First 1
+  }
+  if ($null -eq $adminGroup) { throw 'Could not resolve the local Administrators group (S-1-5-32-544).' }
+  $members = @(Get-LocalGroupMember -Group $adminGroup -ErrorAction Stop)
+  foreach ($member in $members) {
+    $memberName = [string]$member.Name
+    if ($memberName -match '\\') {
+      $parts = $memberName -split '\\'
+      $memberName = [string]$parts[$parts.Count - 1]
+    }
+    if ($memberName) { $admins += $memberName }
+  }
+} catch { $errors += ('local administrators: ' + $_.Exception.Message) }
+
+$currentUser = $null
+if ($env:USERNAME) {
+  $currentFullName = $null
+  foreach ($account in $localUsers) {
+    if ([string]$account.name -ieq [string]$env:USERNAME) { $currentFullName = [string]$account.fullName; break }
+  }
+  $isAdmin = $false
+  foreach ($adminName in $admins) {
+    if ([string]$adminName -ieq [string]$env:USERNAME) { $isAdmin = $true; break }
+  }
+  $currentUser = [ordered]@{
+    name = [string]$env:USERNAME
+    fullName = $currentFullName
+    home = [string]$env:USERPROFILE
+    admin = $isAdmin
+  }
+}
+
+# ---------------------------------------------------------------- startup --
+$startup = @()
+$runKeys = @(
+  [pscustomobject]@{ hive = 'HKCU'; path = 'HKCU:\Software\Microsoft\Windows\CurrentVersion\Run' },
+  [pscustomobject]@{ hive = 'HKLM'; path = 'HKLM:\Software\Microsoft\Windows\CurrentVersion\Run' },
+  # The 32-bit registry view needs its own pseudo-hive so the action engine
+  # (system.launchAgent) can re-enable the entry in the same key it came from;
+  # disabling startup:HKLM:<name> would otherwise target the 64-bit Run key.
+  [pscustomobject]@{ hive = 'HKLM32'; path = 'HKLM:\Software\WOW6432Node\Microsoft\Windows\CurrentVersion\Run' }
+)
+foreach ($runKey in $runKeys) {
+  try {
+    $properties = Get-ItemProperty -Path $runKey.path -ErrorAction Stop
+    $scope = 'system'
+    if ($runKey.hive -eq 'HKCU') { $scope = 'user' }
+    # HKLM and HKLM32 are both machine scope; only the pseudo-path differs.
+    foreach ($property in $properties.PSObject.Properties) {
+      $valueName = [string]$property.Name
+      if ($valueName -like 'PS*') { continue }
+      $startup += [ordered]@{
+        label = $valueName
+        path = ('startup:' + $runKey.hive + ':' + $valueName)
+        scope = $scope
+        loaded = $true
+        program = [string]$property.Value
+        hive = $runKey.hive
+        location = 'Software\Microsoft\Windows\CurrentVersion\Run'
+        source = 'registry'
+      }
+    }
+  } catch {
+    $message = $_.Exception.Message
+    if ($message -notmatch 'Cannot find path' -and $message -notmatch 'does not exist') {
+      $errors += ('registry ' + $runKey.path + ': ' + $message)
+    }
+  }
+}
+
+# Entries disabled by the DeviceX action engine (see system.launchAgent). The
+# action side stores one subkey per hive under
+# `HKCU:\Software\DeviceX\DisabledStartup\<HIVE>`, value name -> command.
+foreach ($disabledHive in @('HKCU', 'HKLM', 'HKLM32')) {
+  $disabledKeyPath = 'HKCU:\Software\DeviceX\DisabledStartup\' + $disabledHive
+  try {
+    $disabledProperties = Get-ItemProperty -Path $disabledKeyPath -ErrorAction Stop
+    if ($null -eq $disabledProperties) { continue }
+    $disabledScope = 'system'
+    if ($disabledHive -eq 'HKCU') { $disabledScope = 'user' }
+    foreach ($property in $disabledProperties.PSObject.Properties) {
+      $valueName = [string]$property.Name
+      if ($valueName -like 'PS*' -or -not $valueName) { continue }
+      $startup += [ordered]@{
+        label = $valueName
+        path = ('startup:' + $disabledHive + ':' + $valueName)
+        scope = $disabledScope
+        loaded = $false
+        program = [string]$property.Value
+        hive = $disabledHive
+        location = 'Software\Microsoft\Windows\CurrentVersion\Run'
+        source = 'registry'
+      }
+    }
+  } catch { }
+}
+
+$loginItems = @()
+try {
+  $startupCommands = @(Get-CimInstance -ClassName Win32_StartupCommand -ErrorAction Stop)
+  foreach ($startupCommand in $startupCommands) {
+    $location = [string]$startupCommand.Location
+    if ($location -match '^(HKCU|HKLM)') { continue }
+    $loginItems += [ordered]@{
+      name = [string]$startupCommand.Name
+      command = [string]$startupCommand.Command
+    }
+  }
+} catch { $errors += ('Win32_StartupCommand: ' + $_.Exception.Message) }
+
+# ------------------------------------------------------ environment/locale --
+$environment = [ordered]@{
+  PATH = [string]$env:Path
+  SHELL = $null
+  HOME = [string]$env:USERPROFILE
+  USER = [string]$env:USERNAME
+  LANG = $env:LANG
+  TERM = $env:TERM
+}
+
+$locale = [ordered]@{ timezone = $null; locale = $null; language = $null }
+try { $locale.timezone = [string](Get-TimeZone).Id } catch { $locale.timezone = $null }
+try { $locale.locale = [string](Get-Culture).Name } catch { $locale.locale = $null }
+try { $locale.language = [string](Get-UICulture).Name } catch { $locale.language = $null }
+
+# -------------------------------------------------------------------- emit --
+$result = [ordered]@{
+  generatedAt = ([DateTimeOffset]::UtcNow).ToUnixTimeMilliseconds()
+  os = $osInfo
+  device = $device
+  boot = $bootInfo
+  users = [ordered]@{
+    current = $currentUser
+    localUsers = $localUsers
+    admins = $admins
+  }
+  startup = $startup
+  loginItems = $loginItems
+  environment = $environment
+  locale = $locale
+  errors = $errors
+}
+
+$result | ConvertTo-Json -Depth 8 -Compress

package/host/win.js

@@ -0,0 +1,187 @@
+/**
+ * Device X — PowerShell bridge for the Windows host half.
+ *
+ * Every Windows collection and action goes through this module so one place
+ * guarantees: a resolved interpreter (Windows PowerShell 5.1 preferred, then
+ * pwsh 7), stdin-streamed scripts (`-Command -`; no shell, no quoting
+ * injection, and no 32,767-character command-line limit), UTF-8 console
+ * output, a wall-clock timeout, a bounded buffer, and JSON parsing that never
+ * throws.
+ *
+ * Parameters reach scripts through environment variables (`DEVICEX_ARG_*`)
+ * rather than string interpolation; callers use {@link psString} only for
+ * constant option values.
+ *
+ * @module @cfour-hi/dsh-plugin-devicex/host/win
+ */
+import { readFileSync } from 'node:fs';
+import { run } from './proc.js';
+
+/** Default wall-clock timeout for one PowerShell call. */
+export const DEFAULT_TIMEOUT = 20_000;
+/** Default stdout/stderr buffer (CIM JSON is well below this). */
+export const DEFAULT_MAX_BUFFER = 16 * 1024 * 1024;
+
+/** Prefix every script with UTF-8 console settings and a quiet progress bar. */
+const OUTPUT_PREFIX =
+  "[Console]::OutputEncoding=[System.Text.Encoding]::UTF8;" +
+  "$OutputEncoding=[System.Text.Encoding]::UTF8;" +
+  "$ProgressPreference='SilentlyContinue';";
+
+/** Interpreter candidates, in preference order.
+ *
+ * Windows PowerShell 5.1 comes first: the collectors/actions use inbox Windows
+ * modules (`Get-LocalUser`, `Get-BitLockerVolume`, `Get-MpComputerStatus`,
+ * `Get-PnpDevice`, `Get-PhysicalDisk`) that are not guaranteed under pwsh 7.
+ * Set DEVICEX_PWSH to override (useful on hosts where only pwsh 7 exists).
+ */
+/** @type {string[]} */
+export const PS_CANDIDATES = /** @type {string[]} */ ([
+  process.env.DEVICEX_PWSH,
+  'powershell.exe',
+  'pwsh.exe',
+  'C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe',
+].filter((candidate) => typeof candidate === 'string' && candidate.length > 0));
+
+/** One resolved interpreter per Host process lifetime. */
+let resolution;
+
+/**
+ * Resolve the first working PowerShell interpreter.
+ * @returns {Promise<{command: string, major: number|null}|null>}
+ */
+export function resolveInterpreter() {
+  resolution ??= (async () => {
+    for (const candidate of PS_CANDIDATES) {
+      const probe = await run(
+        candidate,
+        ['-NoProfile', '-NonInteractive', '-Command', '$PSVersionTable.PSVersion.Major'],
+        { timeout: 8_000, maxBuffer: 64 * 1024 },
+      );
+      if (probe.ok) {
+        const major = Number.parseInt(probe.stdout.trim(), 10);
+        return { command: candidate, major: Number.isFinite(major) ? major : null };
+      }
+    }
+    return null;
+  })();
+  return resolution;
+}
+
+/**
+ * Build the interpreter argv for one streamed script.
+ *
+ * The script is written to stdin (`-Command -`) instead of being encoded into
+ * argv: Windows caps a command line at 32,767 characters and the bundled
+ * collectors are larger than that once UTF-16/base64 encoded.
+ * @returns {string[]}
+ */
+export function commandArguments() {
+  return ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', '-'];
+}
+
+/**
+ * Quote one value as a PowerShell single-quoted literal.
+ * @param {string} value
+ * @returns {string}
+ */
+export function psString(value) {
+  return `'${String(value).replaceAll("'", "''")}'`;
+}
+
+/**
+ * Run a PowerShell script with no implicit shell.
+ * @param {string} script PowerShell source.
+ * @param {object} [options]
+ * @param {number} [options.timeout] milliseconds.
+ * @param {number} [options.maxBuffer] bytes.
+ * @param {Record<string,string>} [options.env] extra environment variables.
+ * @returns {Promise<{ok: boolean, stdout: string, stderr: string, code: number|null,
+ *   signal: string|null, timedOut: boolean, error: string|null}>}
+ */
+export async function runPS(script, options = {}) {
+  const interpreter = await resolveInterpreter();
+  if (interpreter === null) {
+    return {
+      ok: false,
+      stdout: '',
+      stderr: 'no PowerShell interpreter found (pwsh.exe / powershell.exe)',
+      code: null,
+      signal: null,
+      timedOut: false,
+      error: 'PowerShell is not available on this host',
+    };
+  }
+  return run(interpreter.command, commandArguments(), {
+    timeout: options.timeout ?? DEFAULT_TIMEOUT,
+    maxBuffer: options.maxBuffer ?? DEFAULT_MAX_BUFFER,
+    env: options.env === undefined ? undefined : { ...process.env, ...options.env },
+    input: `${OUTPUT_PREFIX}${script}`,
+  });
+}
+
+/** Strip a UTF-8 BOM and surrounding whitespace. */
+function trimOutput(text) {
+  return String(text ?? '').replace(/^\uFEFF/, '').trim();
+}
+
+/**
+ * Run a script that ends by writing one JSON document, and parse it.
+ * A failed run, empty output, or malformed JSON becomes `{ ok: false }` with
+ * a short diagnostic supplied by the script (or from stderr); it never throws.
+ * @param {string} script
+ * @param {object} [options] same as {@link runPS}.
+ * @returns {Promise<{ok: true, data: any, raw: string} | {ok: false, error: string, raw: string, stderr: string}>}
+ */
+export async function runPSJson(script, options = {}) {
+  const result = await runPS(script, options);
+  const raw = trimOutput(result.stdout);
+  if (raw === '') {
+    const detail = trimOutput(result.stderr) || result.error || 'PowerShell returned no output';
+    return { ok: false, error: short(detail), raw, stderr: trimOutput(result.stderr) };
+  }
+  try {
+    return { ok: true, data: JSON.parse(raw), raw };
+  } catch (error) {
+    return {
+      ok: false,
+      error: `PowerShell JSON was not parseable: ${short(error instanceof Error ? error.message : String(error))}`,
+      raw,
+      stderr: trimOutput(result.stderr),
+    };
+  }
+}
+
+/**
+ * Read one bundled PowerShell script from `plugin/host/win/`.
+ * Scripts are cached after first use.
+ * @param {string} name file name inside `host/win/`.
+ * @returns {string}
+ */
+const scriptCache = new Map();
+export function readScript(name) {
+  if (!scriptCache.has(name)) {
+    const url = new URL(`./win/${name}`, import.meta.url);
+    scriptCache.set(name, readFileSync(url, 'utf8'));
+  }
+  return scriptCache.get(name);
+}
+
+/** Shorten a diagnostic to a single useful line. */
+function short(text) {
+  const line = String(text ?? '')
+    .split(/\r?\n/)
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .slice(0, 2)
+    .join(' ');
+  return line.length > 400 ? `${line.slice(0, 400)}…` : line || 'unknown PowerShell failure';
+}
+
+/** Test seam: stable pure helpers used by the offline verification script. */
+export const __test = {
+  commandArguments,
+  psString,
+  trimOutput,
+  OUTPUT_PREFIX,
+};

package/icon.svg

@@ -0,0 +1,18 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="Device X">
+  <defs>
+    <linearGradient id="dx-body" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#2f6bff"/>
+      <stop offset="1" stop-color="#7a4dff"/>
+    </linearGradient>
+    <linearGradient id="dx-orbit" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#63e6ff"/>
+      <stop offset="1" stop-color="#9d7bff"/>
+    </linearGradient>
+  </defs>
+  <rect x="13" y="17" width="38" height="30" rx="7" fill="url(#dx-body)"/>
+  <rect x="19" y="23" width="26" height="18" rx="3" fill="#0b1024" opacity="0.82"/>
+  <path d="M19 28h26M19 33h18M19 38h22" stroke="#63e6ff" stroke-width="1.6" stroke-linecap="round" opacity="0.9"/>
+  <path d="M22 47v6M32 47v6M42 47v6M17 22v-5M32 22V14M47 22v-5" stroke="#c9d6ff" stroke-width="2.4" stroke-linecap="round"/>
+  <ellipse cx="32" cy="32" rx="29" ry="11" fill="none" stroke="url(#dx-orbit)" stroke-width="2" transform="rotate(-24 32 32)" opacity="0.95"/>
+  <circle cx="52.5" cy="21.5" r="3.1" fill="#63e6ff"/>
+</svg>

package/index.js

@@ -0,0 +1,65 @@
+/**
+ * Device X host half.
+ *
+ * Owns the device data collectors, the whitelisted device action engine, the
+ * browser HTTP API consumed by `client.js`, and the two agent tools. The whole
+ * surface is one implementation: the UI routes and the tools call the same
+ * functions.
+ *
+ * @module @cfour-hi/dsh-plugin-devicex
+ */
+import {
+  SECTIONS,
+  PLATFORM,
+  warmup,
+  collectMetrics,
+  collectSection,
+  collectInventory,
+} from './host/collector.js';
+import { GROUPS, actionCatalog, actionHistory, runAction } from './host/actions.js';
+import { scanCleanup } from './host/cleanup.js';
+import { runBenchmark } from './host/benchmark.js';
+import { registerRoutes } from './host/transport.js';
+import { registerTools } from './host/tool.js';
+
+/** Cordis function-plugin name. */
+export const name = 'devicex';
+
+/**
+ * The route carrier, its trust fence, and the tool registry. All are hard
+ * dependencies: without them the plugin has nothing to serve.
+ */
+export const inject = ['webServer', 'connection', 'tools'];
+
+/** The one shared operation surface both callers use. */
+/** @type {import('../types/contracts.js').PluginOperations} */
+const operations = {
+  SECTIONS,
+  PLATFORM,
+  GROUPS,
+  collectMetrics,
+  collectSection,
+  collectInventory,
+  actionCatalog,
+  actionHistory,
+  runAction,
+  scanCleanup,
+  runBenchmark,
+};
+
+/**
+ * Register the browser API and the agent tools, keeping the slow collectors
+ * warm so the first panel view is fast.
+ * @param {import('../types/contracts.js').PluginContext} ctx - the plugin's Cordis context.
+ */
+export function apply(ctx) {
+  warmup();
+  ctx.effect(
+    () => registerRoutes(ctx, operations),
+    'devicex: browser API routes',
+  );
+  ctx.effect(
+    () => registerTools(ctx, operations),
+    'devicex: agent tools',
+  );
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Device X",
+    "description": "See everything about this device — hardware, system, software, network, security, and processes — and control what can be changed."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Device X 设备总览",
+    "description": "一览本机硬件、系统、软件、网络、安全与进程，并直接控制一切可修改项。"
+  }
+}