dsh-ensp 0.3.3 → 0.4.0

package/src/core/launcher.mjs

@@ -35,6 +35,7 @@ import path from 'node:path'
 
 import { calibrateAnchors, DEFAULT_ANCHORS } from './calibrate.mjs'
 import { checkTopologySupport, describeBlocked, rootFromExe } from './compat.mjs'
+import { resolveEnspExe } from './paths.mjs'
 import { readTopology } from './topology.mjs'
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
@@ -301,7 +302,7 @@ export function enspPids() {
  * @returns {Promise<{pid: number, hwnd: string}>}
  */
 export async function launchEnsp({ topology, exspPath, readyTimeoutMs = 120000 } = {}) {
-  const exe = exspPath ?? process.env.DSH_ENSP_EXE ?? 'E:\\Huawei\\eNSP\\eNSP_Client.exe'
+  const exe = resolveEnspExe(exspPath).path
   const target = topology ? path.resolve(topology) : null
 
   // Reject topologies whose devices have no installed image *before* starting the
@@ -469,7 +470,7 @@ $p = Start-Process -FilePath '${exe.replace(/'/g, "''")}'${topology ? ` -Argumen
  * @param {string} topology
  */
 function reopenTopology(topology) {
-  const exe = process.env.DSH_ENSP_EXE ?? 'E:\\Huawei\\eNSP\\eNSP_Client.exe'
+  const exe = resolveEnspExe().path
   startDetached(exe, topology)
 }
 
@@ -591,15 +592,87 @@ Start-Sleep -Milliseconds 250
   return r.ok && r.stdout.split(/\s+/).pop() === 'True'
 }
 
+/**
+ * The window handle that currently holds the foreground, or null.
+ *
+ * Captured before eNSP is raised so it can be handed back afterwards.
+ *
+ * @returns {string|null}
+ */
+export function foregroundWindow() {
+  const r = runPowerShell(
+    `$h = [EnspWin]::GetForegroundWindow()
+([int64]$h).ToString()`,
+    { timeoutMs: 15000 },
+  )
+  const raw = (r.stdout || '').trim().split(/\s+/).pop()
+  if (!raw || raw === '0') return null
+  return raw
+}
+
+/**
+ * Put the foreground back on a previously active window.
+ *
+ * Used after a click that had to raise eNSP: leaving eNSP in front is a
+ * side effect the caller did not ask for. The window state is not touched, so a
+ * visible topology stays visible.
+ *
+ * @param {string|null} hwnd
+ * @returns {boolean} whether the foreground moved back
+ */
+export function restoreForeground(hwnd) {
+  if (!hwnd) return false
+  const r = runPowerShell(
+    `$prev = [IntPtr]::new([int64]${hwnd})
+$ok = [EnspWin]::SetForegroundWindow($prev)
+Start-Sleep -Milliseconds 120
+($ok -and ([EnspWin]::GetForegroundWindow() -eq $prev)).ToString()`,
+    { timeoutMs: 15000 },
+  )
+  return r.ok && (r.stdout || '').trim().split(/\s+/).pop() === 'True'
+}
+
 /**
  * Minimise the eNSP window, handing the desktop back to the user.
+ *
+ * `ShowWindow(SW_MINIMIZE)` minimises without moving the activation: the window
+ * is iconic but still holds the foreground, and Windows then treats the first
+ * taskbar click as an activation correction, so the window appears not to come
+ * back. Restoring the previous foreground window after minimising keeps the
+ * taskbar behaviour standard.
+ *
  * @param {string} hwnd
+ * @param {{previousForeground?: string|null}} [options]
+ * @returns {{iconic: boolean, handedBack: boolean, foreground: string|null}}
  */
-export function minimiseEnsp(hwnd) {
-  runPowerShell(
-    `[EnspWin]::ShowWindow([IntPtr]::new([int64]${hwnd}), 6) | Out-Null; 'ok'`,
-    { timeoutMs: 15000 },
+export function minimiseEnsp(hwnd, options = {}) {
+  const previous = options.previousForeground ?? null
+  const r = runPowerShell(
+    `
+$h = [IntPtr]::new([int64]${hwnd})
+[EnspWin]::ShowWindow($h, 6) | Out-Null
+Start-Sleep -Milliseconds 150
+$fg = [EnspWin]::GetForegroundWindow()
+$iconic = [EnspWin]::IsIconic($h)
+$back = $false
+if ($iconic -and $fg -eq $h) {
+  $prev = $null
+  ${previous ? `$prev = [IntPtr]::new([int64]${previous})` : ''}
+  if ($prev -ne $null -and $prev -ne [IntPtr]::Zero) {
+    $back = [EnspWin]::SetForegroundWindow($prev)
+  }
+  $fg = [EnspWin]::GetForegroundWindow()
+  if ($fg -eq $h) { $back = $false }
+}
+"ICONIC=$iconic FOREGROUND=" + ([int64]$fg).ToString() + " BACK=$back"
+`,
+    { timeoutMs: 20000 },
   )
+  const text = r.stdout || ''
+  const iconic = /ICONIC=True/i.test(text)
+  const handedBack = /BACK=True/i.test(text)
+  const m = /FOREGROUND=(-?\d+)/.exec(text)
+  return { iconic, handedBack, foreground: m ? m[1] : null }
 }
 
 /**
@@ -820,6 +893,8 @@ export async function startAllDevices({
   // Doing it the other way round reports the window that was on top a moment ago
   // (usually the terminal that launched us) as if it were a permanent blocker.
   report({ phase: 'focus', hwnd })
+  // Remember who had the foreground so the minimised eNSP does not keep it.
+  const previousForeground = minimise ? foregroundWindow() : null
   let focused = focusEnsp(hwnd)
   if (focused) await new Promise((resolve) => setTimeout(resolve, 300))
 
@@ -867,8 +942,8 @@ export async function startAllDevices({
 
   // Hand the desktop back immediately; boot continues without the window.
   if (minimise) {
-    minimiseEnsp(hwnd)
-    report({ phase: 'minimised' })
+    const handback = minimiseEnsp(hwnd, { previousForeground })
+    report({ phase: 'minimised', ...handback })
   }
 
   report({ phase: 'wait', devices: targets.length })
@@ -909,7 +984,12 @@ export function stopAllDevices(hwnd, options = {}) {
       anchors = { ...DEFAULT_ANCHORS, method: 'default', detail: {} }
     }
   }
+  const previousForeground = foregroundWindow()
   const focused = focusEnsp(hwnd)
   const result = clickToolbar(hwnd, { button: 'stop', anchors })
-  return { focused, anchors, ...result }
+  // The click needs eNSP in front, but leaving it there surprises the user who
+  // asked for a stop: hand the foreground back without touching the window
+  // state, so the topology stays visible while the devices power down.
+  const handback = restoreForeground(previousForeground)
+  return { focused, anchors, handback, ...result }
 }

package/src/core/paths.mjs

@@ -0,0 +1,190 @@
+/**
+ * Locate the eNSP client and VBoxManage.
+ *
+ * Both used to be hardcoded to `E:\`, which made every machine with a normal
+ * install fail at launch. The lookup order is:
+ *
+ *   1. an explicit override (CLI flag, plugin config, or function argument)
+ *   2. `DSH_ENSP_EXE` / `ENSP_EXE` / `DSH_VBOX`
+ *   3. the Windows install registry
+ *   4. the usual install roots
+ *   5. `where` on PATH (VBoxManage only)
+ *
+ * Every candidate that was tried is reported on failure, so a wrong override
+ * produces a message that says what was looked at instead of a bare ENOENT.
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+/** Registry keys an installer may have written the install root to. */
+const ENSP_REGISTRY = [
+  ['HKLM\\SOFTWARE\\Huawei\\eNSP', 'InstallPath'],
+  ['HKLM\\SOFTWARE\\WOW6432Node\\Huawei\\eNSP', 'InstallPath'],
+  ['HKLM\\SOFTWARE\\Huawei\\eNSP', 'InstallDir'],
+]
+
+/** Install roots seen on real machines, most common first. */
+const ENSP_ROOTS = [
+  'C:\\Program Files\\Huawei\\eNSP',
+  'C:\\Program Files (x86)\\Huawei\\eNSP',
+  'D:\\Huawei\\eNSP',
+  'E:\\Huawei\\eNSP',
+]
+
+/** Where VirtualBox installs itself, most common first. */
+const VBOX_PATHS = [
+  'C:\\Program Files\\Oracle\\VirtualBox\\VBoxManage.exe',
+  'C:\\Program Files (x86)\\Oracle\\VirtualBox\\VBoxManage.exe',
+  'D:\\VirtualBox\\VBoxManage.exe',
+  'E:\\VirtualBox\\VBoxManage.exe',
+]
+
+const isWindows = process.platform === 'win32'
+
+/** True when the path exists and is a file. Never throws. */
+function isFile(candidate) {
+  if (!candidate) return false
+  try {
+    return fs.statSync(candidate).isFile()
+  } catch {
+    return false
+  }
+}
+
+/** Read one string value out of the registry, or null. */
+function registryValue(key, name) {
+  if (!isWindows) return null
+  const r = spawnSync('reg', ['query', key, '/v', name], { encoding: 'utf8', windowsHide: true })
+  if (r.status !== 0 || !r.stdout) return null
+  const m = new RegExp(`${name}\\s+REG_\\w+\\s+(.+)`).exec(r.stdout)
+  return m ? m[1].trim() : null
+}
+
+/** Expand `%VAR%` and strip surrounding quotes from a registry value. */
+function cleanRoot(value) {
+  if (!value) return null
+  const unquoted = value.trim().replace(/^"|"$/g, '')
+  const expanded = unexpanded(unquoted)
+  return expanded || null
+}
+
+/** Expand Windows environment variables without depending on the shell. */
+function unexpanded(value) {
+  return value.replace(/%([^%]+)%/g, (whole, name) => process.env[name] ?? whole)
+}
+
+/** Every candidate eNSP client path, in lookup order, with its source. */
+export function enspCandidates(override) {
+  const out = []
+  if (override) out.push({ path: override, source: 'override' })
+  for (const name of ['DSH_ENSP_EXE', 'ENSP_EXE']) {
+    const v = process.env[name]
+    if (v) out.push({ path: v, source: name })
+  }
+  for (const [key, name] of ENSP_REGISTRY) {
+    const root = cleanRoot(registryValue(key, name))
+    if (root) out.push({ path: path.join(root, 'eNSP_Client.exe'), source: `${key}\\${name}` })
+  }
+  for (const root of ENSP_ROOTS) out.push({ path: path.join(root, 'eNSP_Client.exe'), source: 'install root' })
+  return out
+}
+
+/** Every candidate VBoxManage path, in lookup order, with its source. */
+export function vboxCandidates(override) {
+  const out = []
+  if (override) out.push({ path: override, source: 'override' })
+  if (process.env.DSH_VBOX) out.push({ path: process.env.DSH_VBOX, source: 'DSH_VBOX' })
+  if (isWindows) {
+    const r = spawnSync('where', ['VBoxManage.exe'], { encoding: 'utf8', windowsHide: true })
+    const first = (r.stdout || '').split(/\r?\n/).map((s) => s.trim()).filter(Boolean)[0]
+    if (first) out.push({ path: first, source: 'PATH' })
+  }
+  for (const p of VBOX_PATHS) out.push({ path: p, source: 'install root' })
+  return out
+}
+
+/** First existing candidate, or null. */
+function firstExisting(candidates) {
+  for (const c of candidates) if (isFile(c.path)) return c
+  return null
+}
+
+/**
+ * Resolve the eNSP client executable.
+ *
+ * @param {string} [override] - explicit path from a flag or plugin config
+ * @returns {{path: string, source: string, tried: string[]}}
+ * @throws when nothing exists
+ */
+export function resolveEnspExe(override) {
+  // An explicit path is a statement of intent, not a hint. Falling back to some
+  // other installation would run a different eNSP than the one that was asked
+  // for, and the user would see a working launch on the machine they pointed at
+  // and a mystery on the machine they meant.
+  if (override && !isFile(override)) {
+    throw new Error(
+      `the eNSP client path given does not exist: ${override}\n`
+        + 'Check the path, or drop --exe to let the tool search for an installation.',
+    )
+  }
+  const candidates = enspCandidates(override)
+  const hit = firstExisting(candidates)
+  if (hit) return { path: hit.path, source: hit.source, tried: candidates.map((c) => c.path) }
+  const tried = candidates.map((c) => `  ${c.path}  (${c.source})`).join('\n')
+  throw new Error(
+    `eNSP client not found. Looked at:\n${tried}\n\n`
+      + 'Pass --exe, set DSH_ENSP_EXE, or configure the plugin, with the full path to eNSP_Client.exe. '
+      + 'Installing eNSP to its default location also works.',
+  )
+}
+
+/**
+ * Resolve VBoxManage.
+ *
+ * @param {string} [override]
+ * @returns {{path: string, source: string, tried: string[]}}
+ * @throws when nothing exists
+ */
+export function resolveVBoxManage(override) {
+  if (override && !isFile(override)) {
+    throw new Error(
+      `the VBoxManage path given does not exist: ${override}\n`
+        + 'Check the path, or drop --vbox to let the tool search for an installation.',
+    )
+  }
+  const candidates = vboxCandidates(override)
+  const hit = firstExisting(candidates)
+  if (hit) return { path: hit.path, source: hit.source, tried: candidates.map((c) => c.path) }
+  const tried = candidates.map((c) => `  ${c.path}  (${c.source})`).join('\n')
+  throw new Error(
+    `VBoxManage.exe not found. Looked at:\n${tried}\n\n`
+      + 'Pass --vbox, set DSH_VBOX, or add the VirtualBox install directory to PATH.',
+  )
+}
+
+/**
+ * Resolve the eNSP install root, which holds `res/items.xml` and the plugins.
+ *
+ * Derived from the client path when it can be found, so a machine that launches
+ * successfully also has a correct catalogue path.
+ *
+ * @param {{exe?: string, root?: string}} [options]
+ * @returns {string|null}
+ */
+export function resolveEnspRoot(options = {}) {
+  if (options.root && fs.existsSync(options.root)) return options.root
+  if (options.exe) return path.dirname(options.exe)
+  const hit = firstExisting(enspCandidates())
+  return hit ? path.dirname(hit.path) : null
+}
+
+/** Non-throwing probe used by `doctor`, which reports instead of raising. */
+export function probePaths({ exe, vbox } = {}) {
+  const ensp = firstExisting(enspCandidates(exe))
+  const box = firstExisting(vboxCandidates(vbox))
+  return {
+    ensp: ensp ? { ok: true, path: ensp.path, source: ensp.source } : { ok: false, path: null },
+    vbox: box ? { ok: true, path: box.path, source: box.source } : { ok: false, path: null },
+  }
+}

package/src/core/provision.mjs

@@ -22,10 +22,37 @@
  * @module dsh-ensp/provision
  */
 
-import { openConsole, viewOf } from './console.mjs'
+import { openConsole } from './console.mjs'
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
 
+/**
+ * Errors that mean "the device is already in the state you asked for".
+ *
+ * Re-running the same configuration is the normal way to work: change one line,
+ * apply again, look at the effect. VRP answers the unchanged lines with an error,
+ * and aborting the batch there makes the tool unusable for that loop. These
+ * specific replies are recorded as no-ops instead. Everything else still stops
+ * the batch, because a genuine rejection means the rest of the script is
+ * probably landing on the wrong object.
+ */
+const IDEMPOTENT_RE =
+  /already exists|The VLAN already exists|address already exists|The object already exists|has already been created|is already configured|The route already exists|The ACL rule already exists/i
+
+/**
+ * Whether a VRP error means "this line is already in effect".
+ *
+ * Exported so the behaviour can be tested without a device: the distinction
+ * between "already there" and "rejected" is the whole point of a re-runnable
+ * apply, and it is easy to widen the pattern until real failures are swallowed.
+ *
+ * @param {string} message
+ * @returns {boolean}
+ */
+export function isIdempotentError(message) {
+  return IDEMPOTENT_RE.test(String(message ?? ''))
+}
+
 /**
  * Split a configuration script into executable lines.
  *
@@ -111,21 +138,21 @@ export async function pushConfig({
       // not. Because we already entered system view above, a leading `system-view`
       // would be rejected ("Unrecognized command") and abort the batch. Treat it as
       // idempotent: skip it when we are already in the right place.
-      if (/^system-view$/i.test(command) && viewOf(session.prompt) === 'system') {
+      if (/^system-view$/i.test(command) && session.view === 'system') {
         applied += 1
         transcript.push({ line, command, ok: true, skipped: 'already in system view', output: '' })
         report?.({ phase: 'command', device, line, command, ok: true, skipped: true })
         continue
       }
       // Likewise `return` from system view is a no-op noise source.
-      if (/^return$/i.test(command) && viewOf(session.prompt) === 'system') {
+      if (/^return$/i.test(command) && session.view === 'system') {
         applied += 1
         transcript.push({ line, command, ok: true, skipped: 'already at top of system view', output: '' })
         report?.({ phase: 'command', device, line, command, ok: true, skipped: true })
         continue
       }
       // Guard against view drift: a previous `quit` may have dropped us out.
-      if (viewOf(session.prompt) === 'user') {
+      if (session.view === 'user') {
         const back = await session.ensureSystemView()
         if (!back.ok) {
           return {
@@ -159,6 +186,15 @@ export async function pushConfig({
       })
       report({ phase: 'command', device, line, command, ok: result.ok, view: result.view })
 
+      if (!result.ok && isIdempotentError(result.error)) {
+        // Already in the requested state. Count it so the totals stay meaningful,
+        // and keep the transcript honest about what the device actually said.
+        applied += 1
+        transcript[transcript.length - 1].skipped = 'already in the requested state'
+        report({ phase: 'command', device, line, command, ok: true, skipped: true, view: result.view })
+        continue
+      }
+
       if (!result.ok) {
         if (stopOnError) {
           return {

package/src/dsh/index.mjs

@@ -104,6 +104,45 @@ function stripRequired(node) {
 /** Declare a closed output object. */
 const obj = (properties) => compileObject(properties)
 
+/**
+ * Fill in required properties that a return branch omitted.
+ *
+ * A tool has several branches, and some of them legitimately have nothing to
+ * report: when eNSP is not running there is no pid, no hwnd and no anchor. The
+ * consumer still benefits from a stable shape, so the branch does not have to
+ * repeat empty fields and the schema does not have to relax.
+ *
+ * Missing required keys get the empty value for their type. Keys the branch did
+ * return are never touched, so a wrong value still reaches the validator.
+ */
+/**
+ * Fill in the branches a tool did not return.
+ *
+ * Exported so the contract can be tested without calling a device: every tool
+ * declares its full output shape, and a run that legitimately has nothing to say
+ * about one field must still satisfy that shape.
+ */
+export function conform(schema, value) {
+  if (!schema || schema.type !== 'object') return value
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return value
+  const out = { ...value }
+  for (const key of schema.required ?? []) {
+    if (out[key] !== undefined) continue
+    out[key] = emptyFor(schema.properties?.[key])
+  }
+  return out
+}
+
+/** The empty value for a schema node's type. */
+function emptyFor(node) {
+  const type = node?.type
+  if (type === 'number' || type === 'integer') return 0
+  if (type === 'boolean') return false
+  if (type === 'array') return []
+  if (type === 'object') return {}
+  return ''
+}
+
 /** One plain text content block. */
 const text = (value) => [{ type: 'text', text: String(value) }]
 
@@ -121,7 +160,8 @@ function add(tools, definition) {
   return tools.register({
     ...rest,
     async execute(args) {
-      return execute(args ?? {})
+      const value = await execute(args ?? {})
+      return conform(definition.output?.schema, value)
     },
   })
 }